Builder reference#

Builders wrap a shape to add behaviour. Every builder exists as a top-level function and—in TypeScript, and for most in Go—as a chainable method on a node. Most take an optional trailing spec that they narrow or wrap.

• TS: const { Min } = require('shape') then Min(2, String) or Required(Number).Min(2).
• Go: shape.Min(2, shape.String); chainable form buildize(shape.String).Min(2). G-prefixed aliases (shape.GMin) avoid stdlib name clashes.

One, Some, All, Exact and Discriminated are top-level only (not chainable).

Required / optional / defaults#

Notes:

• A literal in a spec is already "optional with a default"; these builders adjust that. A type marker is required; Optional/Default relax it.
• Default(value) alone takes the value's kind; Default(value, spec) keeps the spec, and an untyped spec (Required(), Exact(1)) takes the value's kind. In a key expression "a: Default()": 5 the example is the default.
• A builder called with the wrong argument is a mistake in the spec: Min('x'), Len(-1), Define(''). TypeScript throws at build (Shape: Min needs a number); a Go builder cannot, so it returns a node that accepts nothing and reports the same message at validation.
• Ignore keeps a valid value and silently drops an invalid one. It judges the whole subtree, so a failing descendant is swallowed too.

Type / equality#

Coercion#

The conversions, identical in both languages:

Coerce(Any) converts nothing. Bare Coerce is an untyped node, so it converts nothing either.

String formats#

Each requires a string in the given format; bare, it is a required string.

A format only speaks for a present string of the node's kind: a missing or wrongly typed value still gets the required or type error, and a bound on the same node (Email(Min(10, String))) is checked first. A format failure keeps its own message (Value "nope" for property "a" is not a valid email address.) under Fault too, which replaces structural text only. Every pattern is written for the RE2 and JavaScript engines alike; IPv6 is checked algorithmically. A pattern of your own (/re/, Check(/re/)) is held to the shared regexp subset, so it matches the same strings in every language.

Bounds#

For numbers these bound the value; for strings/arrays/objects they bound the length/size.

Custom checks#

Validator signature (all three): (val, update, state) => boolean. Return true to pass. Use update.val to replace the value, update.err to set a message ($VALUE and $PATH are expanded), update.done to skip the node's structural check. In TypeScript a validator that throws fails with the exception's message appended; in Go a panic and in Rust an unwinding panic escape the call (see the parity page). See Shape nodes.

A bare regular expression in a spec ({ a: /^a/ }) is a type: a string that must match, so a non-string fails as a type error. Check(/^a/) is the explicit check form and reports as a failed check.

Isolation: Catch, Transform, Describe#

These judge the node as a whole—its own checks, its type, every descendant—before the node proceeds.

A bound outside the isolation still applies to what comes out: Min(2, Catch(0, Number)) against "x" reports that 0 is under the bound of 2.

Composition#

None of the three changes the value it was given: each branch matches and produces from a copy, and the composition's result replaces the value only when it passes, so a failing One, Some or All leaves the input as it was. | Discriminated(tag, { name: shape, … }) | A tagged union: the branch is chosen by the string value of the tag property and the value validated against that branch alone, so the errors are its own rather than a list of every alternative. |

Discriminated adds the tag property to an object-shaped branch that does not declare it, as the literal it is keyed by, so the branch's output carries the tag. A value without the tag, or with an unknown one, fails on the union itself:

Value "{bark:true}" for property "p" is not an object with a "kind" property.
Value "{kind:cat}" for property "p" has unknown "kind" "cat", expected one of: dog, fish.

An absent optional composition (Optional(One(String, Number))) is simply absent; it is not put to its branches.

Objects / arrays#

Object algebra#

Each builds a new object shape out of an existing one. The source is left as it was, so one base can be reshaped many times. names is a property name or a list of them.

const User = { id: Number, name: String, role: 'user' }

Shape(Pick(['id', 'name'], User))          // { id, name }
Shape(Omit('id', User))                    // { name, role }
Shape(Partial(User))({})                   // → { id: 0, name: '', role: 'user' }
Shape(Extend({ email: Email }, User))      // User plus a required email
Closed(User).Pick('id').Extend({ v: 1 })   // chainable; each step is a new node

An object default is narrowed with the properties (Pick('a', Default({ a: 1, b: 2 })) defaults to { a: 1 }). Key expressions in the source ({ 'a: Min(2)': 0 }) are compiled by the algebra, since it has to know the real property names. In the string DSL, which has no object literal, the algebra is reached through a key expression, whose example is the shape: { 'u: Pick(["a"])': { a: 1, b: 2 } }.

References#

Misc#

Language differences#

• Len reports its own name in stringify/spec and in the error check field (it does not masquerade as Below).
• All bounded/custom-check errors carry the check name; the built-in message text is identical across languages.
• Go splits the TS options-object forms into explicit ReferWith / RenameWith helpers alongside the Refer / Rename shortcuts.
• Key() returns the value's parent key in both languages.
• Any, Integer and Date are builder functions (or, for Date, the constructor) in TypeScript, usable bare or called, and type tokens in Go; narrow them there with Type(Any, spec) or .Any(), .Integer(), .Date().
• Construction faults. TypeScript throws when a builder is called wrongly — Discriminated without a branch, Pick of an unknown property. Go builders return a *Node and cannot, so the fault surfaces at validation, as it does for any bad spec, with the same message. In the string DSL both fail at build, since expr throws and Expr returns an error.
• Go has no Symbol token and no .String() chain shortcut—see the parity page.

Key expressions#

A key of the form "name: <expression>" compiles the expression and takes the value as an example. The example is appended as the innermost builder call's final argument, so a builder that takes a shape consumes it:

{ 'a: Min(2)': 0 }          // a bounded number; the example gives the kind
{ 'a: Child(Number)': [] }  // an array of numbers; the example gives the kind
{ 'u: Pick(["a"])': { a: 1, b: 2 } }  // the example is the shape picked from

A builder whose arity is already satisfied has no room for it—Optional(Number) already has its one argument—so there the example is applied as the value and default instead:

{ 'a: Optional(Number)': 5 }   // an optional number defaulting to 5
{ 'a: Optional(String)': 'z' } // an optional string defaulting to "z"
{ 'a: Any': 5 }                // still accepts anything; defaults to 5

Either way the example survives, and the expression keeps whatever kind it declared. Skip still means no injection at all, and a bare literal expression ({ 'a: 5': 3 }) has no builder to hand the example to, so its own value stands.

Ordering within a node#

Coerce runs first. Then a size bound (Min, Max, Above, Below, Len) or a format stands aside when the node declares a type the value does not have, so Min(2, String) against 1 reports that 1 is not a string rather than that it breaks the bound. A check that fails skips the node's own structural check, so Min(2, String) against "" reports only the bound, not the empty string too. Every before and after still runs after one has failed, so a failing bound and a failing format (Min(10, Email) against "nope"), or a failing format and a failing custom check, both report.

A failed container type check ends the descent: validating { a: String } against 1 reports one error, not a type error plus "property a is required" for every declared key.

For per-builder examples, follow the how-to guides linked from the docs index.