/* Copyright (c) 2021-2024 Richard Rodger and other contributors, MIT License */ // FIX: does not work if Shape is inside a Proxy - jest fails // FEATURE: validator on completion of object or array // FEATURE: support non-index properties on array shape // FEATURE: state should indicate if value was present, not just undefined // FEATURE: support custom builder registration so that can chain on builtins // FEATURE: merge shapes (allows extending given shape - e.g. adding object props) // FEATURE: Key validation by RegExp // TODO: ShapeShape.d is damaged by composition // TODO: Better stringifys for builder shapes // TODO: node.s can be a lazy function to avoid unnecessary string building // FIX: Shape(Shape(..)) should work // DOC: Skip also makes value optional - thus Skip() means any value, or nonexistent // DOC: Optional import { inspect } from 'util' // Package version. const VERSION = '12.2.5' // Unique symbol for marking and recognizing Shape shapes. const SHAPE$ = Symbol.for('shape$') // A singleton for fast equality checks. const SHAPE = { shape$: SHAPE$, v$: VERSION } // TODO SHAPE$UNDEF for explicit undefined // A special marker for property abscence. // const SHAPE$UNDEF = Symbol.for('shape$undef') // RegExp: first letter is upper case const UPPER_CASE_FIRST_RE = /^[A-Z]/ // RegExp: key expression pattern (hoisted from inner loop for performance) const KEY_EXPR_RE = /^\s*("(\\.|[^"\\])*"|[^\s]+):\s*(.*?)\s*$/ // The children of an object or array node, as the walk needs them, compiled // on the node's first visit and reused after: the object's keys in the order // they were first seen with their nodes, or the array's fixed element nodes. // Kept off the node itself so nothing leaks into its spec or its JSON. // A compiled child list: the keys, their nodes, and for each the leaf fast // path it may take (see fastKind; 0 when it may not). type Compiled = { keys: string[], nodes: Node[], fast: number[], vgen: number, known: Set | null, // For each key, whether Object.prototype has a member of that name, so // only those keys pay for an own-property check. proto: boolean[], } const COMPILED = new WeakMap() // Child shapes (Child, Rest, a one-element array) normalized to their full // depth once; a later visit only refreshes the depth. const DEEP = new WeakSet() // The inline check a child may take in place of a full visit: a String, // Number, Boolean or Integer with no befores or afters. A present value that // passes the kind's whole check (the empty string, NaN and fraction rules // included) needs no frame; anything else takes the general path. An object // takes it for all of its children or none: a custom validator on one child // may read the frames of its siblings (the argument parser does), so a // sibling of a validator is always given a frame. // The builder generation: bumped by every builder application and whenever // a before or after is attached to any node, so that a compiled list can // tell that a child may have changed since its kinds were compiled (a spec // is read at compile time, but a retained node can be re-chained to // another kind, or given a validator, afterwards) and recompile them // rather than trust what it saw. No builder runs during a validation, so // a compiled list is recompiled once per change, not per call. let VGEN = 0 function attach(list: any[], v: any) { VGEN++ list.push(v) } // The fast kinds of a compiled object's children: all zero when any child // has a validator, since a validator may read its siblings' frames. function fastKinds(nodes: Node[]): number[] { for (let i = 0; i < nodes.length; i++) { if (0 < nodes[i].b.length || 0 < nodes[i].a.length) return nodes.map(() => 0) } return nodes.map(fastKind) } const FAST_STRING = 1 const FAST_NUMBER = 2 const FAST_BOOLEAN = 3 const FAST_INTEGER = 4 function fastKind(cn: Node): number { if (0 < cn.b.length || 0 < cn.a.length) return 0 return S.string === cn.t ? FAST_STRING : S.number === cn.t ? FAST_NUMBER : S.boolean === cn.t ? FAST_BOOLEAN : S.integer === cn.t ? FAST_INTEGER : 0 } function fastValid(f: number, cv: any): boolean { const tv = typeof cv return FAST_STRING === f ? (S.string === tv && '' !== cv) : FAST_NUMBER === f ? (S.number === tv && cv === cv) : FAST_BOOLEAN === f ? S.boolean === tv : (S.number === tv && Number.isInteger(cv)) } function childNode(c: any, depth: number): Node { if (null != c && DEEP.has(c)) { c.d = depth return c } const node = nodizeDeep(c, depth) DEEP.add(node) return node } const { toString } = Object.prototype // Options for creating a ShapeShape. type ShapeOptions = { name?: string // Name this Shape shape. // Meta properties meta?: { active?: boolean // If true, recognize meta properties. Default: false. suffix?: string // Key suffix to mark meta properties. Default: '$$' } // Key expressions ({'a: Open':1}) keyexpr?: { active?: boolean // If true, recognize key expressions. Default: true. } // TODO: should be valexpr // Special keys to define value expr for parent object or array. valexpr?: { active?: boolean // If true, recognize keyspec in object. Default: false. keymark?: string // Special key to mark parent object expr. Default: meta.suffix. } // The trials one validation may run (see trial): each shape a Nof tries, // each When condition and each item a Contains counts takes one. A whole // number above zero; anything else is the default, 100000. trials?: number } // User context for a given Shape validation run. // Add your own references here for use in your own custom validations. // The reserved properties are: `err`. type Context = Record & { // Provide an array to collect errors, instead of throwing. err?: ErrDesc[] | boolean log?: (point: string, state: State) => void skip?: { depth?: number | number[] keys?: string[] } prefix?: string suffix?: string } // The semantic types recognized by Shape. // Not that Shape considers values to be subtypes. type ValType = 'any' | // Any type. 'array' | // An array. 'bigint' | // A BigInt value. 'boolean' | // The values `true` or `false`. 'date' | // A Date instance. 'function' | // A function. 'integer' | // A number with no fractional part. 'instance' | // An instance of a constructed object. 'list' | // A list of types under a given logical rule. 'nan' | // The `NaN` value. 'never' | // No type. 'null' | // The `null` value. 'number' | // A number. 'object' | // A plain object. 'string' | // A string (but *not* the empty string). 'symbol' | // A symbol reference. 'regexp' | // A regular expression. 'check' | // A check function. 'undefined' // The `undefined` value. // A node in the validation tree structure. type Node = { $: typeof SHAPE // Special marker to indicate normalized. readonly __v?: V // The spec type, for inference only; never set. // o: any t: ValType // Value type name. d: number // Depth. v: any // Defining value. f: any // Default, if any. r: boolean // Value is required. p: boolean // Value is skippable - can be missing or undefined. n: number // Number of keys in default value c: any // Default child. k: string[] // Final keys of value, in order of appearance. e: boolean // If false, match failures are not an error. u: Record // Custom user meta data b: Validate[] // Custom before validation functions. a: Validate[] // Custom after vaidation functions. // TODO: use u m: NodeMeta // Meta data. // s?: string | Function // Custom stringification. z?: string // Custom error message. } & { [name: string]: Builder } // Meta data for shape node. type NodeMeta = Record // A validation Node builder. type Builder = ( opts?: any, // Builder options. ...vals: any[] // Values for the builder. ) => Node // Validate a given value, potentially updating the value and state. type Validate = ((val: any, update: Update, state: State) => boolean) & { s?: (n: Node) => string, // stringify validator of builder a?: readonly any[] // args to the builder n?: string // name of builder o?: any // builder options the string form cannot express } // The value a spec produces, by type. A builder's node carries the spec it // was given (or the type it stands for), so the result is read through it; // a type marker is its primitive; a literal is itself; a one-element array // is an array of that element and a longer one a tuple; an object maps its // properties, with a key expression ("a: Min(2)") reduced to its name. type IsAny = 0 extends (1 & T) ? true : false // The runtime grammar (KEY_EXPR_RE): optional whitespace, a quoted or a // whitespace-free name, a colon, then a non-empty expression; anything else // is a plain key. type Trim = S extends ` ${infer R}` ? Trim : S extends `${infer R} ` ? Trim : S type KeyName = K extends string ? ( Trim extends `"${infer Q}":${infer E}` ? ('' extends Trim ? K : Q) : Trim extends `${infer N}:${infer E}` ? (N extends `${string} ${string}` ? K : '' extends Trim ? K : N) : K ) : K // A result object keeps the input's own extra properties; a property the // spec declares is the spec's (Coerce turns a string into a number). type Produced = IsAny extends true ? R : R extends readonly any[] ? R : R extends object ? (V extends object ? Omit & R : R) : R // A builder used bare (`{ n: Integer }`) carries the type it stands for. The // brand's key is a symbol this module does not export, so nothing can read // it at runtime. declare const BARE: unique symbol type Bare = { readonly [BARE]: R } // An Exact value list: its literals are the result, not their widened kinds. type Literal = { readonly literal$: L } type ShapeResult = IsAny extends true ? any : T extends Literal ? L : T extends Node ? ShapeResult : T extends StringConstructor ? string : T extends NumberConstructor ? number : T extends BooleanConstructor ? boolean : T extends DateConstructor ? Date : T extends ArrayConstructor ? any[] : T extends ObjectConstructor ? any : T extends FunctionConstructor ? Function : T extends SymbolConstructor ? symbol : T extends 'String' | 'string' ? string : T extends 'Number' | 'number' | 'Integer' | 'integer' ? number : T extends 'Boolean' | 'boolean' ? boolean : T extends 'Date' | 'date' ? Date : T extends 'Array' | 'array' ? any[] : T extends 'Object' | 'object' | 'Function' | 'function' | 'Symbol' | 'symbol' ? any : T extends RegExp ? string : T extends Date ? Date : T extends readonly [] ? any[] : T extends readonly [infer E] ? ShapeResult[] : T extends readonly any[] ? { -readonly [K in keyof T]: ShapeResult } : T extends Bare ? R : T extends (this: any, ...args: any[]) => Node ? any : T extends (...args: any[]) => any ? T : T extends { [key: string]: any } ? { -readonly [K in keyof T as KeyName]: ShapeResult } : T extends string ? string : T extends number ? number : T extends boolean ? boolean : T // Brand a builder with the type it stands for when used bare. function bare() { return (f: F): F & Bare => f as F & Bare } // The result type an algebra builder produces from a spec type. type Names = N extends string ? N : N extends readonly (infer S)[] ? S : never type PickResult = { [K in keyof V as KeyName extends Names ? K : never]: V[K] } type OmitResult = { [K in keyof V as KeyName extends Names ? never : K]: V[K] } type ExtendResult = { [K in keyof V as KeyName extends KeyName ? never : K]: V[K] } & E // TODO: make this work // type Shape = ((root?: V, ctx?: Context) => V & ShapeResult) // Help the minifier const S = { shape: 'shape', name: 'name', nan: 'nan', never: 'never', number: 'number', required: 'required', array: 'array', function: 'function', object: 'object', string: 'string', boolean: 'boolean', undefined: 'undefined', any: 'any', list: 'list', instance: 'instance', null: 'null', type: 'type', closed: 'closed', check: 'check', regexp: 'regexp', integer: 'integer', date: 'date', String: 'String', Number: 'Number', Boolean: 'Boolean', Object: 'Object', Array: 'Array', Symbol: 'Symbol', Function: 'Function', Integer: 'Integer', Date: 'Date', Value: 'Value', Above: 'Above', After: 'After', All: 'All', Any: 'Any', Before: 'Before', Below: 'Below', Check: 'Check', Child: 'Child', Closed: 'Closed', Define: 'Define', Default: 'Default', Empty: 'Empty', Exact: 'Exact', Func: 'Func', Key: 'Key', Max: 'Max', Min: 'Min', Never: 'Never', Nof: 'Nof', When: 'When', Contains: 'Contains', Unique: 'Unique', trial: 'trial', Nullable: 'Nullable', Catch: 'Catch', Coerce: 'Coerce', Describe: 'Describe', Discriminated: 'Discriminated', Pick: 'Pick', Omit: 'Omit', Partial: 'Partial', Extend: 'Extend', DateTime: 'DateTime', Email: 'Email', Ip: 'Ip', Ipv4: 'Ipv4', Ipv6: 'Ipv6', Url: 'Url', Uuid: 'Uuid', Len: 'Len', Open: 'Open', Optional: 'Optional', Refer: 'Refer', Rename: 'Rename', Required: 'Required', Skip: 'Skip', Transform: 'Transform', Ignore: 'Ignore', Fault: 'Fault', Rest: 'Rest', forprop: ' for property ', $PATH: '"$PATH"', $VALUE: '"$VALUE"', } const TNAT = { [S.String]: String, [S.Number]: Number, [S.Boolean]: Boolean, [S.Object]: Object, [S.Array]: Array, [S.Symbol]: Symbol, [S.Function]: Function, [S.Date]: Date, } // Utility shortcuts. const keys = (arg: any) => Object.keys(arg) const defprop = (o: any, p: any, a: any) => Object.defineProperty(o, p, a) const hasOwn = (o: any, k: any) => Object.prototype.hasOwnProperty.call(o, k) // The names an object inherits from Object.prototype: toString, valueOf, // constructor, __proto__ and the rest. A key with one of these names is // read as the value's own property only, so an input without it has no // such value whatever the prototype lends, as in Go and Rust. const PROTO_KEYS = new Set(Object.getOwnPropertyNames(Object.prototype)) const ownval = (o: any, k: string) => (PROTO_KEYS.has(k) && !hasOwn(o, k)) ? undefined : o[k] // Write a key as an own property: assigning __proto__ would set the // prototype rather than add the key. const setprop = (o: any, k: any, v: any) => { if ('__proto__' === k) { ownprop(o, k, v) } else { o[k] = v } } // The constructor an object is an instance of, read from its prototype: an // own "constructor" key is a property like any other. const ctorOf = (v: any) => Object.getPrototypeOf(v)?.constructor const isarr = (arg: any) => Array.isArray(arg) const JP = (arg: string) => JSON.parse(arg) const JS = (a0: any, a1?: any) => JSON.stringify(a0, a1) // The current validation state. class State { match: boolean = false // The caller wants a verdict only (valid() or match() without a context // of its own), so an error is recorded without its path, text or value // rendering: nothing will read them. terse: boolean = false dI: number = 0 // Node depth. nI: number = 2 // Next free slot in nodes. cI: number = -1 // Pointer to next node. pI: number = 0 // Pointer to current node. sI: number = -1 // Pointer to next sibling node. valType: string = S.never isRoot: boolean = false key: string = '' type: string = S.never stop: boolean = true nextSibling: boolean = true fromDflt: boolean = false // NOTE: tri-valued; undefined = soft ignore ignoreVal: boolean | undefined = undefined curerr: any[] = [] err: any[] = [] // TODO: is this needed - try using ancestors instead parents: Node[] = [] keys: string[] = [] ancestors: Node[] = [] // NOTE: not "clean"! // Actual path is always only path[0,dI+1] path: string[] = [] node: Node root: any // Initialised here so every State has one shape from construction: // a field first written in next() would move the object to another // hidden class per call. val: any = undefined parent: any = undefined nodes: (Node | number)[] vals: any[] ctx: any oval: any = undefined check: Function | undefined = undefined checkargs?: Record // The trial budget of the validation (see trial), which every validation // within it shares. trials: any = undefined // The last parent object seen (see next). lastParent: any = undefined constructor( root: any, top: Node, ctx?: Context, match?: boolean, terse?: boolean ) { this.root = root this.vals = [root, -1] this.node = top // The root's back pointer is 0, which stops the walk as any zero does: // a negative index is not an array index, and reading it takes the // generic keyed-load path, at the same site every pop uses. this.nodes = [top, 0] this.ctx = ctx || {} this.match = !!match this.terse = !!terse } next() { // Uncomment for debugging (definition below). DO NOT REMOVE. // this.printStacks() this.stop = false this.fromDflt = false this.ignoreVal = undefined this.isRoot = 0 === this.pI this.check = undefined // Dereference the back pointers to ancestor siblings. // Only objects|arrays can be nodes, so a number is a back pointer (a // zero or the end of the stack stops the walk below). let nextNode = this.nodes[this.pI] while (S.number === typeof nextNode && 0 !== nextNode) { this.dI-- this.ctx.log && -1 < this.dI && this.ctx.log('e' + (isarr(this.parents[this.pI]) ? 'a' : 'o'), this) this.pI = +nextNode nextNode = this.nodes[this.pI] } if (!nextNode) { this.stop = true return } else { this.node = (nextNode as Node) } this.updateVal(this.vals[this.pI]) this.key = this.keys[this.pI] this.cI = this.pI this.sI = this.pI + 1 // A parent that cannot take new keys is copied before its first child // runs (see thawParent); siblings share a parent, so the check runs once // per parent object. const parent = this.parents[this.pI] if (parent !== this.lastParent) { this.lastParent = null != parent && !Object.isExtensible(parent) ? this.thawParent(parent) : parent } this.parent = this.parents[this.pI] this.nextSibling = true this.type = this.node.t // NOTE: this is always correct for the current node, up to dI, because // previous values at dI get overwritten. Avoids need to duplicate on each descent. // ancestors[dI] is set where the walk descends to dI (see exec). this.path[this.dI] = this.key this.oval = this.val if (0 < this.curerr.length) { this.curerr = [] } } updateVal(val: any) { this.val = val this.valType = typeof (this.val) if (S.number === this.valType && isNaN(this.val)) { this.valType = S.nan } if (this.isRoot && !this.match) { this.root = this.val } } // A parent that cannot take new keys (frozen, sealed) is copied once, // before its first child runs. The child and its later siblings take the // copy, an error about the parent names it, and it takes the parent's // place wherever the parent still is: under its key, or the key a Rename // of it moved it to, or as the result. Only a validation that produces // writes the parent's place. thawParent(p: any): any { const c = thaw(p) let j = this.pI for (; S.number !== typeof this.nodes[j]; j++) { if (this.parents[j] === p) { this.parents[j] = c } } for (const e of this.err) { if (e.value === p) { e.value = c } } // The back pointer that ends the block is one past the parent's slot. const at = (this.nodes[j] as number) - 1 const gp = this.parents[at] if (!this.match) { if (0 === at) { // A check after the root's own may have replaced the result. if (this.root === p) { this.root = c } } else { const key = this.keys[at] if (gp[key] === p) { gp[key] = c } for (const b of (this.nodes[at] as Node).b) { const to = S.Rename === b.n ? (b.a as string[])[0] : undefined if (undefined !== to && gp[to] === p) { gp[to] = c } } } } return c } // UNCOMMENT TO DEBUG - DO NOT REMOVE /* printStacks() { console.log('\nNODE', 'd=' + this.dI, 'c=' + this.cI, 'p=' + this.pI, 'n=' + this.nI, +this.node, this.node.t, this.path, this.err.length) console.log('A:' + this.ancestors .map((a: any, i: number) => i + '=' + stringify(a)).join(' ')) for (let i = 0; i < this.nodes.length || i < this.vals.length || i < this.parents.length ; i++) { console.log(i, '\t', ('' + (isNaN(+this.nodes[i]) ? this.keys[i] + ':' + (this.nodes[i] as any)?.t : +this.nodes[i])).padEnd(32, ' '), stringify(this.vals[i]).padEnd(32, ' '), stringify(this.parents[i]), ) } } */ } // Return updates to the validation state. type Update = { done?: boolean val?: any uval?: any // Use for undefined and NaN node?: Node type?: ValType nI?: number sI?: number pI?: number err?: string | ErrDesc | ErrDesc[] why?: string fatal?: boolean } // Validation error description. type ErrDesc = { key: string // Key of failing value. type: string // type of node node: Node // Failing shape node. value: any // Failing value. path: string // Key path to value. pathArr: (string | number)[] // Key path as array (numeric array indices as numbers). why: string // Error code ("why"). check: string // Check function name. args: Record // Builder args. mark: number // Error mark for debugging. text: string // Error message text. use: any // User custom info. } // Standard Schema V1 interop types (vendored from https://standardschema.dev/). // Kept inline to avoid adding a runtime/type dependency. type StandardSchemaV1Issue = { readonly message: string readonly path?: ReadonlyArray } type StandardSchemaV1PathSegment = { readonly key: PropertyKey } type StandardSchemaV1Result = | StandardSchemaV1SuccessResult | StandardSchemaV1FailureResult type StandardSchemaV1SuccessResult = { readonly value: Output readonly issues?: undefined } type StandardSchemaV1FailureResult = { readonly issues: ReadonlyArray } type StandardSchemaV1Types = { readonly input: Input readonly output: Output } type StandardSchemaV1Props = { readonly version: 1 readonly vendor: string readonly validate: ( value: unknown ) => StandardSchemaV1Result | Promise> readonly types?: StandardSchemaV1Types } type StandardSchemaV1 = { readonly '~standard': StandardSchemaV1Props } // Custom Error class. class ShapeError extends TypeError { shape = true code: string gname: string props: ({ path: string, type: string, value: any, }[]) desc: () => ({ name: string, code: string, err: ErrDesc[], ctx: any }) constructor( code: string, gname: string | undefined, err: ErrDesc[], ctx: any, ) { gname = (null == gname) ? '' : (!gname.startsWith('G$') ? gname + ': ' : '') const prefix = (null == ctx.prefix ? '' : ctx.prefix + ': ') const suffix = (null == ctx.suffix ? '' : ' ' + ctx.suffix) super(gname + prefix + err.map((e: ErrDesc) => e.text).join('\n') + suffix) let name = 'ShapeError' let ge = this as unknown as any ge.name = name this.code = code this.gname = gname this.desc = () => ({ name, code, err, ctx, }) // The frames are formatted when the stack is first read, as they are // for any error, and this module's own frames removed then: formatting // them in the constructor cost more than the validation that threw. const raw = Object.getOwnPropertyDescriptor(this, 'stack') let done = false let stack: any = undefined Object.defineProperty(this, 'stack', { configurable: true, enumerable: false, get: () => { if (!done) { done = true const text = raw && (raw.get ? raw.get.call(this) : raw.value) stack = text?.replace(/.*\/shape\/shape\.[tj]s.*\n/g, '') } return stack }, set: (v: any) => { done = true stack = v }, }) this.props = err.map((e: ErrDesc) => ({ path: e.path, what: e.why, type: e.node?.t, value: e.value })) } toJSON() { return { ...this, err: (this as any).desc().err, name: this.name, message: this.message, } } } // TODO: There are a lot more!!! Error, Blob, etc // Identify JavaScript wrapper types by name. const IS_TYPE: { [name: string]: boolean } = { Array: true, BigInt: true, Boolean: true, Date: true, Function: true, Number: true, Object: true, String: true, Symbol: true, } // Empty values for each type. const EMPTY_VAL: { [name: string]: any } = { string: '', number: 0, integer: 0, boolean: false, object: {}, array: [], symbol: Symbol(''), bigint: BigInt(0), null: null, regexp: /.*/, } // Normalize a value into a Node. function nodize(shape?: any, depth?: number, meta?: NodeMeta): Node { // Shape itself is no shape: as a spec ({ a: Shape }), or handed to // buildize, it gives nothing, which is Any. if (shapify === shape) { shape = undefined } // A bare builder reference (`{ a: Any }`) means that builder applied to // nothing. Without this it falls through to the class-instance branch below // and becomes an `instanceof` check that can never pass. if (S.function === typeof shape && true === (shape as any).nullary$) { shape = shape() } // Is this a (possibly incomplete) Node? if (null != shape && shape.$?.shape$) { // Assume complete if shape$ has special internal reference. if (SHAPE$ === shape.$.shape$) { shape.d = null == depth ? shape.d : depth return shape } // Normalize an incomplete Node, avoiding any recursive calls to norm. else if (true === shape.$.shape$) { let node = { ...shape } node.$ = { v$: VERSION, ...node.$, shape$: SHAPE$ } node.v = (null != node.v && S.object === typeof (node.v)) ? { ...node.v } : node.v // Leave as-is: node.c node.t = node.t || typeof (node.v) if (S.function === node.t && IS_TYPE[node.v.name]) { node.t = (node.v.name.toLowerCase() as ValType) node.v = clone(EMPTY_VAL[node.t]) node.f = node.v } node.r = !!node.r node.p = !!node.p node.d = null == depth ? null == node.d ? -1 : node.d : depth node.b = node.b || [] node.a = node.a || [] node.u = node.u || {} node.m = node.m || meta || {} return node } } // Not a Node, so build one based on value and its type. let t: ValType | 'undefined' = (null === shape ? (S.null as ValType) : typeof (shape)) t = (S.undefined === t ? S.any : t) as ValType let v = shape let f = v let c: any = undefined let r = false // Not required by default. let p = false // Only true when Skip builder is used. let u: any = {} let a: any[] = [] let b: any[] = [] if (S.object === t) { f = undefined if (isarr(v)) { t = (S.array as ValType) if (1 === v.length) { c = v[0] v = [] } // Else no child, thus closed. } else if ( null != v && Function !== ctorOf(v) && Object !== ctorOf(v) && null != ctorOf(v) ) { let strdesc = toString.call(v) if ('[object RegExp]' === strdesc) { t = (S.regexp as ValType) r = true // The engine regexp of the shared subset; v keeps the original. u.re = engineRegexp(v) } else if ('[object Date]' === strdesc) { t = (S.date as ValType) } else { t = (S.instance as ValType) u.n = ctorOf(v).name u.i = ctorOf(v) } f = v } else { // Empty object "{}" is considered Open if (0 === keys(v).length) { c = Any() } } } // NOTE: use Check for validation functions else if (S.function === t) { if (IS_TYPE[shape.name]) { t = (shape.name.toLowerCase() as ValType) r = true v = clone(EMPTY_VAL[t]) f = v // Required "Object" is considered Open if (S.Object === shape.name) { c = Any() } } else if (v.shape === SHAPE || true === v.$?.shape) { let gs = v.node ? v.node() : v t = gs.t v = gs.v // The shape's own default: an object's children are not one. f = gs.f r = gs.r u = { ...gs.u } a = [...gs.a] b = [...gs.b] } // Instance of a class. // Note: uses the convention that a class name is captialized. else if ( S.Function === v.constructor.name && UPPER_CASE_FIRST_RE.test(v.name) ) { t = (S.instance as ValType) r = true u.n = v.prototype?.constructor?.name u.i = v } } else if (S.number === t && isNaN(v)) { t = (S.nan as ValType) } else if (S.string === t && '' === v) { u.empty = true } let vmap = (null != v && (S.object === t || S.array === t)) ? { ...v } : v let node = ({ $: SHAPE, t, v: vmap, f, n: null != vmap && S.object === typeof (vmap) ? keys(vmap).length : 0, c, r, p, d: null == depth ? -1 : depth, k: [], e: true, u, a, b, m: meta || {}, [Symbol.for('nodejs.util.inspect.custom')]() { const nd: any = { ...this } delete nd.$ return JSON.stringify( nd, (_k, v) => 'function' === typeof v && !(BuilderMap as any)[v.name] && !TNAT[v.name] ? v.name : v ).replace(/"/g, '').replace(/,/g, ' ') } } as unknown as Node) return node } function nodizeDeep(root: any, depth: number) { const nodes = [[{}, 'root', root, depth]] for (let i = 0; i < nodes.length; i++) { const p = nodes[i] const n = p[0][p[1]] = nodize(p[2], p[3]) if (undefined !== n.c) { if (!n.c.$?.shape$) { nodes.push([n, 'c', n.c, n.d]) } } let vt = typeof n.v if (S.object === vt && null != n.v) { const vkeys = keys(n.v) for (let kI = 0; kI < vkeys.length; kI++) { const k = vkeys[kI] if (!n.v[k]?.$?.shape$) { nodes.push([n.v, k, n.v[k], n.d + 1]) } } } } return nodes[0][0].root } // Create a ShapeShape from a shape specification. function shapify(intop?: S, inopts?: ShapeOptions) { const opts: ShapeOptions = null == inopts ? {} : inopts // TODO: move to prepopts utility function // Ironically, we can't Shape ShapeOptions, so we have to set // option defaults manually. opts.name = null == opts.name ? 'G$' + ('' + Math.random()).substring(2, 8) : '' + opts.name // Meta properties are off by default. let optsmeta = opts.meta = opts.meta || ({} as any) optsmeta.active = (true === optsmeta.active) || false optsmeta.suffix = S.string == typeof optsmeta.suffix ? optsmeta.suffix : '$$' // Key expressions are on by default. let optskeyexpr = opts.keyexpr = opts.keyexpr || ({} as any) optskeyexpr.active = (false !== optskeyexpr.active) // Key specs are off by default. let optsvalexpr = opts.valexpr = (opts.valexpr || ({} as any)) optsvalexpr.active = (true === optsvalexpr.active) optsvalexpr.keymark = S.string == typeof optsvalexpr.keymark ? optsvalexpr.keymark : optsmeta.suffix let top: Node = nodize(intop, 0) let desc: string = '' let json: any = undefined // Lazily execute top against root to see if they match function exec( root: any, ctx?: Context, match?: boolean, // Suppress errors and return boolean result (true if match) terse?: boolean, // The caller reads no error: record them without text ): any { const skipd = ctx?.skip?.depth const skipa = Array.isArray(ctx?.skip?.depth) ? new Set(ctx.skip.depth) : null const skipk = Array.isArray(ctx?.skip?.keys) ? new Set(ctx.skip.keys) : null // A trial's errors are thrown away, so it records them without text. const s = new State(root, top, ctx, match, terse || true === ctx?.terse$) // A validation counts its trials against a budget of its own; one // within another, such as a composition's branch, counts against its // parent's. const ownTrials = undefined === s.ctx.trial$ s.trials = ownTrials ? { left: trialBudget(opts.trials), budget: trialBudget(opts.trials), spent: undefined } : s.ctx.trial$ // A log callback is called for every node, so nothing is skipped for it. const fastOk = !s.ctx.log // Iterative depth-first traversal of the shape using append-only array stacks. // Stack entries are either sub-nodes to validate, or back pointers to // next depth-first sub-node index. while (true) { s.next() if (s.stop) { break } let n = s.node let done = false let fatal = false // Shapes of different kinds (see Nof) put a value to the shape of its // kind, which stands in this node's place where that cannot change // what the composition was given: a scalar, or a value that is this // validation's own copy. const kinds = S.list === n.t && undefined !== n.u.nof ? nofKindsNow(n) : undefined if (undefined !== kinds && undefined !== s.val && 1 === n.b.length && 0 === n.a.length && (null === s.val || S.object !== typeof s.val || s.ctx.own$)) { const kI = kinds.indexOf(kindOf(s.val) as string) if (-1 < kI) { n = s.node = n.u.list[kI] s.type = n.t } } // Context skip can override node skip let skip = (n.d === skipd || (skipa && skipa.has(n.d)) || (skipk && 1 === n.d && skipk.has(s.key))) ? true : n.p // Call Befores. A node's definitions are registered first, so that a // check of the node (a composition's branch) can refer to it. A check // that puts another node in this one's place (Refer, a claimed Rename) // leaves that node's checks to run, from its first, each check once. if (0 < n.b.length) { if (n.u.defines) { defineFirst(n, s) } let ran: Validate[] | null = null for (let bI = 0; bI < n.b.length; bI++) { const vf = n.b[bI] if (null !== ran) { if (ran.includes(vf)) { continue } ran.push(vf) } const was = n let update = handleValidate(vf, s) n = s.node if (undefined !== update.done) { done = update.done } fatal = fatal || !!update.fatal if (n !== was) { ran = null === ran ? was.b.slice(0, bI + 1) : ran if (n.u.defines) { defineFirst(n, s) } bI = -1 } } } if (!done) { let descend = true let valundef = undefined === s.val // Nullable: an explicit null is accepted as the value. if (null === s.val && n.u.nullable) { s.ctx.log && s.ctx.log('kv', s) } else if (S.never === s.type) { if (!valundef || n.r) { s.curerr.push(makeErrImpl(S.never, s, 1070)) } } // Handle objects. else if (S.object === s.type) { let val if (undefined !== n.c) { n.c = childNode(n.c, 1 + s.dI) } if (n.r && valundef) { s.ignoreVal = true s.curerr.push(makeErrImpl(S.required, s, 1010)) } else if ( !valundef && ( null === s.val || S.object !== s.valType || isarr(s.val) ) ) { s.curerr.push(makeErrImpl(S.type, s, 1020)) val = isarr(s.val) ? s.val : {} // The container is the wrong type, so its declared keys are // meaningless. Descending would add a spurious "is required" error // for every one of them on top of the real type error. descend = false } // Not skippable, use default or create object else if (!skip && valundef && undefined !== n.f) { s.updateVal(n.f) s.fromDflt = true val = s.val descend = false } else if (!skip || !valundef) { // Descend into object, constructing child defaults s.updateVal(s.val || (s.fromDflt = true, {})) val = s.val } if (descend) { val = null == val && false === s.ctx.err ? {} : val if (null != val) { s.ctx.log && s.ctx.log('so', s) let hasKeys = false let start = s.nI const compiled = COMPILED.get(n) let ck: string[] | null = null let known: Set | null = null if (undefined !== compiled) { // Compiled on an earlier visit: the children in first-seen // order, no key expressions or meta keys left to read. const ckeys = ck = compiled.keys const cnodes = compiled.nodes known = compiled.known if (compiled.vgen !== VGEN) { compiled.fast = fastKinds(cnodes) compiled.vgen = VGEN } const cfast = compiled.fast const cproto = compiled.proto if (0 < ckeys.length) { s.pI = start for (let kI = 0; kI < ckeys.length; kI++) { const rk = ckeys[kI] const cv = cproto[kI] && !hasOwn(val, rk) ? undefined : val[rk] const f = cfast[kI] if (fastOk && 0 !== f && fastValid(f, cv)) { continue } s.nodes[s.nI] = cnodes[kI] s.vals[s.nI] = cv s.parents[s.nI] = val s.keys[s.nI] = rk s.nI++ } hasKeys = start < s.nI } } else { let vkeys = keys(n.v) let knownKeys = new Set(n.k) if (0 < vkeys.length) { hasKeys = true s.pI = start //for (let k of vkeys) { for (let kI = 0; kI < vkeys.length; kI++) { let k = vkeys[kI] let meta: NodeMeta | undefined = undefined // TODO: make optional, needs tests // Experimental feature for jsonic docs // NOTE: Meta key *must* immediately preceed key: // { x$$: , x: 1 }} if (optsmeta.active && k.endsWith(optsmeta.suffix)) { meta = { short: '' } if (S.string === typeof (n.v[k])) { meta.short = n.v[k] } else { meta = { ...meta, ...n.v[k] } } delete n.v[k] kI++ if (vkeys.length <= kI) { break } if (vkeys[kI] !== k .substring(0, k.length - optsmeta.suffix.length)) { throw new Error('Invalid meta key: ' + k) } k = vkeys[kI] } let rk = k let ov: any = n.v[k] if (optskeyexpr.active) { let m = KEY_EXPR_RE.exec(k) if (m && '' !== m[3]) { rk = keyExprName(m[1]) let src = m[3] ov = keyExprNode(src, ov, 1 + s.dI, meta) delete n.v[k] } } if (optsvalexpr.active && k.startsWith(optsvalexpr.keymark)) { if (k === optsvalexpr.keymark) { let outn = expr({ src: ov, d: 1 + s.dI, meta, ancestors: s.ancestors, node: n, }, n) Object.assign(n, outn) } else { n.m.$$ = (n.m.$$ || {}) n.m.$$[k.substring(optsvalexpr.keymark.length)] = n.v[k] } delete n.v[k] continue } let nvs = nodize(ov, 1 + s.dI, meta) setprop(n.v, rk, nvs) if (!knownKeys.has(rk)) { n.k.push(rk) knownKeys.add(rk) } s.nodes[s.nI] = nvs s.vals[s.nI] = ownval(val, rk) s.parents[s.nI] = val s.keys[s.nI] = rk s.nI++ } } // Every key is now a node under its final name, so later // visits can take the compiled list. Value expressions read // the ancestors at validation time, so they stay uncompiled. if (!optsvalexpr.active) { COMPILED.set(n, { keys: n.k.slice(), nodes: n.k.map((k: string) => n.v[k]), fast: fastKinds(n.k.map((k: string) => n.v[k])), vgen: VGEN, known: new Set(n.k), proto: n.k.map((k: string) => PROTO_KEYS.has(k)), }) } } let extra: string[] | null = null let valKeys = keys(val) // The value's keys are the declared keys in order, or a // prefix of them (JSON written from the same shape): none is // extra, and no lookup is needed. Otherwise a declared key is // found in the compiled set, and only an undeclared one is // looked up in the spec, as every key was before. let aligned = null !== ck && valKeys.length <= ck.length for (let i = 0; aligned && i < valKeys.length; i++) { aligned = ck![i] === valKeys[i] } if (!aligned) { for (let vkI = 0; vkI < valKeys.length; vkI++) { const k = valKeys[vkI] if (!(null !== known && known.has(k)) && !hasOwn(n.v, k)) { (extra ??= []).push(k) } } } if (null !== extra) { if (undefined === n.c) { s.ignoreVal = true s.curerr.push(makeErrImpl( S.closed, s, 1100, undefined, { k: extra })) } else { hasKeys = true s.pI = start for (let k of extra) { let nvs = n.c = nodize(n.c, 1 + s.dI) s.nodes[s.nI] = nvs s.vals[s.nI] = val[k] s.parents[s.nI] = val s.keys[s.nI] = k s.nI++ } } } if (hasKeys) { s.dI++ // The parent of every child at this depth, until a node at // the depth above descends again. s.ancestors[s.dI] = n s.nodes[s.nI] = s.sI s.parents[s.nI] = val s.nextSibling = false s.nI++ } else { s.ctx.log && s.ctx.log('eo', s) } } } } // Handle arrays. else if (S.array === s.type) { if (n.r && valundef) { s.ignoreVal = true s.curerr.push(makeErrImpl(S.required, s, 1030)) } else if (!valundef && !isarr(s.val)) { s.curerr.push(makeErrImpl(S.type, s, 1040)) } else if (!skip && valundef && undefined !== n.f) { s.updateVal(n.f) s.fromDflt = true } else if (!skip || null != s.val) { s.updateVal(s.val || (s.fromDflt = true, [])) // n.c set by nodize for array with len=1 let hasChildShape = undefined !== n.c let hasValueElements = 0 < s.val.length // The fixed element shapes, compiled on the first visit. let compiled = COMPILED.get(n) if (undefined === compiled) { let elementKeys: string[] = [] let nvKeys = keys(n.v) for (let ekI = 0; ekI < nvKeys.length; ekI++) { if (!isNaN(+nvKeys[ekI])) { elementKeys.push(nvKeys[ekI]) } } const elementNodes: Node[] = [] for (let ekI = 0; ekI < elementKeys.length; ekI++) { elementNodes.push(n.v[ekI] = nodize(n.v[ekI], 1 + s.dI)) } compiled = { keys: elementKeys, nodes: elementNodes, fast: [], vgen: VGEN, known: null, proto: [] } COMPILED.set(n, compiled) } const elementKeys = compiled.keys const elementNodes = compiled.nodes let hasFixedElements = 0 < elementKeys.length if (hasChildShape) { n.c = childNode(n.c, 1 + s.dI) } s.ctx.log && s.ctx.log('sa', s) if (hasValueElements || hasFixedElements) { s.pI = s.nI let elementIndex = 0 // Fixed element array means match shapes at each index only. if (hasFixedElements) { if (elementKeys.length < s.val.length && !hasChildShape) { s.ignoreVal = true s.curerr.push(makeErrImpl(S.closed, s, 1090, undefined, { k: elementKeys.length })) } else { for (; elementIndex < elementKeys.length; elementIndex++) { let elementShape = elementNodes[elementIndex] s.nodes[s.nI] = elementShape s.vals[s.nI] = s.val[elementIndex] s.parents[s.nI] = s.val s.keys[s.nI] = '' + elementIndex s.nI++ } } } // Single element array shape means 0 or more elements of shape if (hasChildShape && hasValueElements) { let elementShape: Node = n.c // = nodize(n.c, 1 + s.dI) const efast = fastOk ? fastKind(elementShape) : 0 for (; elementIndex < s.val.length; elementIndex++) { if (0 !== efast && fastValid(efast, s.val[elementIndex])) { continue } s.nodes[s.nI] = elementShape s.vals[s.nI] = s.val[elementIndex] s.parents[s.nI] = s.val s.keys[s.nI] = '' + elementIndex s.nI++ } } if (!s.ignoreVal && s.pI < s.nI) { s.dI++ s.ancestors[s.dI] = n s.nodes[s.nI] = s.sI s.parents[s.nI] = s.val s.nextSibling = false s.nI++ } } else { // Ensure single element array still generates log // for the element when only walking shape. s.ctx.log && hasChildShape && undefined == root && s.ctx.log('kv', { ...s, key: 0, val: n.c }) s.ctx.log && s.ctx.log('ea', s) } } } // Handle regexps. else if (S.regexp === s.type) { if (valundef && !n.r) { s.ignoreVal = true } else if (S.string !== s.valType) { s.ignoreVal = true s.curerr.push(makeErrImpl(S.type, s, 1045)) } else if (!(n.u.re || n.v).test(s.val)) { s.ignoreVal = true s.curerr.push(makeErrImpl(S.regexp, s, 1045)) } } // Invalid type. else if (!( S.any === s.type || S.list === s.type || S.check === s.type || undefined === s.val || s.type === s.valType || (S.instance === s.type && n.u.i && s.val instanceof n.u.i) || (S.null === s.type && null === s.val) || (S.integer === s.type && S.number === s.valType && Number.isInteger(s.val)) || (S.date === s.type && s.val instanceof Date && !isNaN(s.val.getTime())) )) { s.curerr.push(makeErrImpl(S.type, s, 1050)) } // Value itself, or default. else if (undefined === s.val) { let parentKey = s.path[s.dI] if ( !skip && n.r && (S.undefined !== s.type || !hasOwn(s.parent, parentKey)) ) { s.ignoreVal = true s.curerr.push(makeErrImpl(S.required, s, 1060)) } else if ( // undefined !== n.v && undefined !== n.f && !skip || S.undefined === s.type ) { // Inject default value. s.updateVal(n.f) s.fromDflt = true } else if (S.any === s.type) { s.ignoreVal = undefined === s.ignoreVal ? true : s.ignoreVal } // TODO: ensure object,array points called even if errors s.ctx.log && s.ctx.log('kv', s) } // Empty strings fail even if string is optional. Use Empty() to allow. else if (S.string === s.type && '' === s.val && !n.u.empty) { s.curerr.push(makeErrImpl(S.required, s, 1080)) s.ctx.log && s.ctx.log('kv', s) } else { s.ctx.log && s.ctx.log('kv', s) } } // Call Afters if (0 < n.a.length) { for (let aI = 0; aI < n.a.length; aI++) { let update = handleValidate(n.a[aI], s) n = s.node if (undefined !== update.done) { done = update.done } fatal = fatal || !!update.fatal } } // Explicit ignoreVal overrides Skip // let ignoreVal = s.node.p ? false === s.ignoreVal ? false : true : !!s.ignoreVal let ignoreVal = skip ? false === s.ignoreVal ? false : true : !!s.ignoreVal let setParent = !s.match && null != s.parent && !done && !ignoreVal if (setParent) { setprop(s.parent, s.key, s.val) } if (s.nextSibling) { s.pI = s.sI } if (0 < s.curerr.length && (s.node.e || fatal)) { s.err.push(...s.curerr) } } // A spent budget leaves no verdict standing, as a trial it refused may // have decided any of them: its error is the only one. if (ownTrials && undefined !== s.trials.spent) { s.err = [s.trials.spent] } // s.err = s.err.filter(e => null != e) if (0 < s.err.length) { if (isarr(s.ctx.err)) { s.ctx.err.push(...s.err) } else if (!s.match && false !== s.ctx.err) { throw new ShapeError(S.shape, opts.name, s.err, s.ctx) } } return s.match ? 0 === s.err.length : s.root } // The produced value: the spec's result, keeping the input's own extra // properties when both are objects. const shape = (root?: V, ctx?: Context): Produced> => { return (exec(root, ctx, false)) } function valid(root?: V, ctx?: Context): root is (V & ShapeResult) { // Without a context of the caller's nothing can read the errors, so // they are recorded without their text. const terse = undefined === ctx let actx: any = ctx || {} actx.err = actx.err || [] exec(root, actx, false, terse) return 0 === actx.err.length } shape.valid = valid shape.match = (root?: any, ctx?: Context): boolean => { const terse = undefined === ctx ctx = ctx || {} return (exec(root, ctx, true, terse) as boolean) } // List the errors from a given root value. shape.error = (root?: any, ctx?: Context): ErrDesc[] => { let actx: any = ctx || {} actx.err = actx.err || [] exec(root, actx, false) return actx.err } shape.spec = () => { // Normalize spec, discard errors. shape(undefined, { err: false }) const str = stringify(top, false, true, { key: Object.keys(TNAT) }, (_key: string, val: any) => { if (SHAPE$ === val) { return true } return val }) return JP(str) } shape.node = (): Node => { shape.spec() return top } shape.stringify = (...rest: any[]) => { const json = shape.jsonify() return '' === desc ? (desc = ('string' === typeof json ? json.replace(/^"(.*)"$/, '$1') : JSON.stringify(json, ...rest))) : desc } shape.jsonify = () => { return null == json ? (json = node2json(shape.node())) : json } // JSON Schema (draft 2020-12) for the values this shape accepts. shape.jsonSchema = () => jsonSchema(shape.node()) // The declarative JSON of the shape, which build() reads back. shape.json = () => nodeJson(shape.node()) shape.toString = function(this: any) { desc = '' === desc ? this.stringify() : desc return `[Shape ${opts.name} ${truncate(desc)}]` } if (inspect && inspect.custom) { (shape as any)[inspect.custom] = shape.toString } shape.shape = SHAPE // Standard Schema V1 interop (https://standardschema.dev/). ;(shape as any)['~standard'] = { version: 1, vendor: 'shape', validate(value: unknown) { const sctx: Context = { err: [] } const out = exec(value, sctx, false) const errs = sctx.err as ErrDesc[] if (0 === errs.length) { return { value: out } } return { issues: errs.map((e: ErrDesc) => ({ message: e.text, path: e.pathArr, })), } }, } // Validate shape spec. This will throw if there's an issue with the spec. shape.spec() return shape } // Parse a builder expression into actual Builders. // Function call syntax; Depth first; literals must be JSON values; // Commas are optional. Top level builders are applied in order. // Dot-concatenated builders are applied in order. // Primary value is passed as Builder `this` context. // Examples: // Shape({ // 'x: Open': {}, // 'y: Min(1) Max(4)': 2, // 'z: Required(Min(1))': 2, // 'q: Min(1).Below(4)': 3, // }) function expr( spec: { src: string keymark?: string val?: any d?: number meta?: NodeMeta ancestors?: Node[], node?: Node, tokens?: string[] i?: number refs?: any carrier?: any } | string, current?: any ) { let g: any = undefined let top = false if ('string' === typeof spec) { spec = { src: spec } } spec.keymark = spec.keymark || '$$' const currentIsNode = current?.$?.shape$ spec.i = spec.i || 0 if (null == spec.tokens) { g = undefined != spec.val ? nodize(spec.val, (spec.d || 0) + 1, spec.meta) : undefined top = true spec.tokens = [] // A O BC D L E F M H N I JK let tre = /\s*,?\s*(-?\d+\.\d+(?:[eE][+-]?\d+)?|[)(\.]|"(\\.|[^"\\])*"|\/(\\.|[^\/\\])*\/[a-z]?|[^)(,.\s]+)\s*/g // A: prefixing space and/or comma // B-J: the next token is submatch 1, containing a set of alternates // O: a number with a fraction (1.5), which is one token, not 1 . 5 // C: class parens-dot // D: quoted string // L: backslash escape within string // E: unescaped char (not a quote or backslash) // F: regexp // M: literal dot // H: not a regexp escape or end slash // N: regexp end and flags // I: not a char token (thus a builder name) // K: suffix space let t = null while (t = tre.exec(spec.src)) { spec.tokens.push(t[1]) } // The object of a carrier with no properties of its own (see build): a // head that names a node is that node, and any other call takes the // empty object as its last argument, so Required.Child($$0) is // Required({}).Child($$0). if (undefined !== spec.carrier && carrierApplies(spec.tokens[0])) { const refname = 'token_carrier' spec.refs = (spec.refs || {}) spec.refs[refname] = spec.carrier if ('(' === spec.tokens[1]) { spec.tokens.splice(closingParen(spec.tokens, 1), 0, spec.keymark + refname) } else { spec.tokens.splice(1, 0, '(', spec.keymark + refname, ')') } } // Append current into leftmost deepest Builder args if (!currentIsNode) { let tI = 0 let paren = false // for (; tI < spec.tokens.length && ')' !== spec.tokens[tI]; tI++); for (; tI < spec.tokens.length; tI++) { if (')' == spec.tokens[tI]) { paren = true break } } if (paren || tI === spec.tokens.length) { //let ctj = JSON.stringify(current) // if (undefined !== ctj) { if (undefined !== current) { let refname = 'token_' + spec.d + '_' + spec.i spec.refs = (spec.refs || {}) spec.refs[refname] = current // A composition reads each argument as a branch or its count, so // the example is neither: when the call it would land in is a // composition or sits inside one, the outermost such composition // takes it as its default instead, and Nof(1,String,Number) with // 5 reads as Default(5,Nof(1,String,Number)). // A Contains reads its first two arguments as its count and the // shape of its items, so the example is its spec, after them. const cI = paren ? compositionCallAt(spec.tokens, tI) : -1 if (-1 < cI && S.Contains === spec.tokens[cI]) { spec.tokens.splice(closingParen(spec.tokens, cI + 1), 0, spec.keymark + refname) } else if (-1 < cI) { spec.tokens.splice(closingParen(spec.tokens, cI + 1) + 1, 0, ')') spec.tokens.splice(cI, 0, S.Default, '(', spec.keymark + refname) } else if (paren && exactLists(spec.tokens, tI, current)) { // An Exact that already lists the example would only list it // twice; left alone, it still takes the example as its default. } else if (paren) { // spec.tokens.splice(tI, 0, ctj) spec.tokens.splice(tI, 0, spec.keymark + refname) } else { // spec.tokens.push('(', ctj, ')') spec.tokens.push('(', spec.keymark + refname, ')') } } } } } let head = spec.tokens[spec.i] let fn = (BuilderMap as any)[head] if (')' === spec.tokens[spec.i]) { spec.i++ return current } spec.i++ let args = [] if (null == fn) { try { let m // let val = TNAT[head] if (TNAT[head]) { fn = Type args.unshift(head) } else if (S.undefined === head) { return undefined } else if ('NaN' === head) { return NaN } else if (head.match(/^\/.*\/[a-z]$/)) { throw regexpFault(head.substring(1, head.length - 2), 'flags are not supported') } else if (2 <= head.length && head.match(/^\/.*\/$/)) { const body = head.substring(1, head.length - 1) // Held to the shared subset here; the node compiles the engine form. canonicalRegexp(body) return new RegExp(body) } else if (m = head.match(/^\$\$([^$]+)$/)) { const held = spec.node ? ((spec.node.m?.$$ || {})[m[1]] || spec.node.v?.['$$' + m[1]]) : undefined return undefined !== held ? held : spec.refs ? spec.refs[m[1]] : undefined } else { let val = JP(head) if (top) { fn = Default args.unshift(val) } else { return val } } } catch (je: any) { if (S.string === typeof je?.message && je.message.startsWith('Shape: invalid regexp')) { throw je } throw new SyntaxError( `Shape: unexpected token ${head} in builder expression ${spec.src}`) } } if ('(' === spec.tokens[spec.i]) { spec.i++ let t = null while (null != (t = spec.tokens[spec.i]) && ')' !== t) { let ev = expr(spec) args.push(ev) } spec.i++ } if (!currentIsNode) { g = fn.call(undefined, ...args) } else { g = fn.call(current, ...args) } if ('.' === spec.tokens[spec.i]) { spec.i++ g = expr(spec, g) } else if (top && spec.i < spec.tokens.length) { g = expr(spec, g) } return g } // The index of the outermost All, Nof, When or Contains call open at // tokens[tI], the first closing parenthesis, so every call opened before it // is still open; -1 when none is. Each reads its leading arguments as // shapes of its own, so none of them can be the example. function compositionCallAt(tokens: string[], tI: number): number { for (let i = 1; i < tI; i++) { if ('(' === tokens[i] && (S.All === tokens[i - 1] || S.Nof === tokens[i - 1] || S.When === tokens[i - 1] || S.Contains === tokens[i - 1])) { return i - 1 } } return -1 } // Whether the call that tokens[tI] closes is an Exact already listing the // example, a scalar: an object or array is never one, as Exact compares it // by identity. function exactLists(tokens: string[], tI: number, example: any): boolean { const oI = tokens.lastIndexOf('(', tI) if (oI < 1 || S.Exact !== tokens[oI - 1] || (null !== example && S.object === typeof example)) { return false } return tokens.slice(oI + 1, tI).some((t: string) => { try { return JSON.parse(t) === example } catch (_e: any) { return false } }) } // The index of the parenthesis that closes the one at tokens[oI], or the // end of the tokens when none does (the expression is then malformed, and // parsing it says so or reads what is there, as it would have). function closingParen(tokens: string[], oI: number): number { let depth = 1 let i = oI + 1 while (i < tokens.length && 0 < (depth += '(' === tokens[i] ? 1 : ')' === tokens[i] ? -1 : 0)) { i++ } return i } // Whether the expression of a carrier with no properties applies to the // empty object, which its first call then takes: a builder does, unless it // names a node by itself, as a composition, Any, Integer, Check and Key do. // A type token, a literal and a sidecar name their node too. function carrierApplies(head: string): boolean { return undefined !== (BuilderMap as any)[head] && !CARRIER_NODES.includes(head) } const CARRIER_NODES = [S.All, S.Nof, S.When, S.Exact, S.Discriminated, S.Any, S.Integer, S.Check, S.Key] // Whether a key is a key expression: a name, a colon, and an expression. function isKeyExpr(k: string): boolean { const m = KEY_EXPR_RE.exec(k) return null != m && '' !== m[3] } // The property name of a key expression. A name may be quoted to hold a // space, a colon or an escaped quote: `{ '"a b": Min(1)': 0 }` declares the // property "a b", and `{ '"a\\"b": Min(1)': 0 }` the property a"b. function keyExprName(name: string): string { if (2 <= name.length && '"' === name[0] && '"' === name[name.length - 1]) { try { return JP(name) } catch (_e: any) { return name.substring(1, name.length - 1) } } return name } // The shared regexp subset // ======================== // A regexp in a shape is read by three engines (JavaScript, RE2 in Go, the // regex crate in Rust), which agree only on a subset of syntax and meaning. // A pattern is held to that subset here and rewritten for this engine, so // that the same pattern matches the same strings everywhere; the original // text is what renders and exports. The rules are the ones the reference // page docs/reference/regexp.md states, and the Go and Rust ports carry the // same scanner with the same error texts. // // In the subset: literals, \ escapes of the syntax characters and /, \t \n // \r \f \v and \xHH, character classes with ranges, \d \w \s (ASCII) and // their negations outside a class, . (anything but a newline), ^ $ \b \B, // groups ( ) and (?: ), alternation, and the quantifiers * + ? {n} {n,} // {n,m} with a lazy ?. Not in it: flags, lookaround, backreferences, named // groups, inline flags, POSIX and \p classes, \u escapes, class set // operators and lone braces. const RE_SYNTAX_ESCAPES = '\\^$.|?*+()[]{}/' const RE_ASCII_D = '0-9' const RE_ASCII_W = 'A-Za-z0-9_' const RE_ASCII_S = ' \\t\\n\\r\\f\\v' function regexpFault(src: string, reason: string): Error { return new Error('Shape: invalid regexp /' + src + '/: ' + reason) } // Validate a pattern against the subset and return the pattern this engine // runs, or throw the shared error. function canonicalRegexp(src: string): string { const fail = (reason: string) => { throw regexpFault(src, reason) } if ('' === src) fail('empty pattern') let out = '' let inClass = false let classItems = 0 // items so far in the open class let shorthand = false // the previous class item was \d \w or \s let depth = 0 let atom = false // an atom precedes, so a quantifier may follow let quant = false // a quantifier precedes, so a ? makes it lazy const n = src.length const HEX2 = /^[0-9A-Fa-f]{2}$/ for (let i = 0; i < n; i++) { const c = src[i] if (inClass) { if (']' === c) { if (0 === classItems) fail('empty character class') out += ']' inClass = false atom = true quant = false continue } if ('[' === c) { fail(':' === src[i + 1] ? 'POSIX classes are not in the subset' : '[ must be escaped inside a character class') } if (('&' === c || '-' === c || '~' === c) && c === src[i + 1] && '-' !== c) { fail('class set operators (&&, --, ~~) are not in the subset') } if ('-' === c && '-' === src[i + 1]) { fail('class set operators (&&, --, ~~) are not in the subset') } if ('-' === c) { // A range: neither end may be a shorthand class. const ends = ']' === src[i + 1] || 0 === classItems if (!ends && shorthand) fail('a range cannot start or end at a class shorthand') if (!ends && '\\' === src[i + 1] && 'dwsDWS'.includes(src[i + 2])) { fail('a range cannot start or end at a class shorthand') } out += '-' continue } if ('\\' === c) { i++ if (i >= n) fail('trailing backslash') const e = src[i] shorthand = false if (RE_SYNTAX_ESCAPES.includes(e) || '-' === e) out += '\\' + e else if ('tnrfv'.includes(e)) out += '\\' + e else if ('x' === e) { const h = src.substring(i + 1, i + 3) if (!HEX2.test(h)) fail('\\x needs two hex digits') out += '\\x' + h i += 2 } else if ('d' === e) { out += RE_ASCII_D; shorthand = true } else if ('w' === e) { out += RE_ASCII_W; shorthand = true } else if ('s' === e) { out += RE_ASCII_S; shorthand = true } else if ('D' === e || 'W' === e || 'S' === e) { fail('\\D, \\W and \\S are not allowed inside a character class') } else if ('b' === e || 'B' === e) { fail('\\b and \\B are not allowed inside a character class') } else fail('escape \\' + e + ' is not in the subset') classItems++ continue } shorthand = false out += c classItems++ continue } if ('\\' === c) { i++ if (i >= n) fail('trailing backslash') const e = src[i] if (RE_SYNTAX_ESCAPES.includes(e)) out += '\\' + e else if ('tnrfv'.includes(e)) out += '\\' + e else if ('x' === e) { const h = src.substring(i + 1, i + 3) if (!HEX2.test(h)) fail('\\x needs two hex digits') out += '\\x' + h i += 2 } else if ('d' === e) out += '[' + RE_ASCII_D + ']' else if ('D' === e) out += '[^' + RE_ASCII_D + ']' else if ('w' === e) out += '[' + RE_ASCII_W + ']' else if ('W' === e) out += '[^' + RE_ASCII_W + ']' else if ('s' === e) out += '[' + RE_ASCII_S + ']' else if ('S' === e) out += '[^' + RE_ASCII_S + ']' else if ('b' === e || 'B' === e) { out += '\\' + e atom = false quant = false continue } else if ('-' === e) fail('escape \\- is only allowed inside a character class') else fail('escape \\' + e + ' is not in the subset') atom = true quant = false continue } if ('[' === c) { inClass = true classItems = 0 shorthand = false out += '[' if ('^' === src[i + 1]) { out += '^' i++ } continue } if (']' === c) fail('unescaped ]') if ('(' === c) { if ('?' === src[i + 1]) { if (':' !== src[i + 2]) fail('lookaround, named groups and inline flags are not in the subset') out += '(?:' i += 2 } else { out += '(' } depth++ atom = false quant = false continue } if (')' === c) { depth-- if (depth < 0) fail('unbalanced parentheses') out += ')' atom = true quant = false continue } if ('|' === c || '^' === c || '$' === c) { out += c atom = false quant = false continue } if ('*' === c || '+' === c || '?' === c) { if ('?' === c && quant) { // Lazy. out += '?' quant = false atom = false continue } if (!atom) fail('nothing to repeat') out += c atom = false quant = true continue } if ('{' === c) { const m = src.substring(i).match(/^\{(\d+)(,(\d*))?\}/) if (null == m) fail('lone quantifier brace') if (!atom) fail('nothing to repeat') out += m![0] i += m![0].length - 1 atom = false quant = true continue } if ('}' === c) fail('lone quantifier brace') if ('.' === c) { out += '[^\\n]' atom = true quant = false continue } out += c atom = true quant = false } if (inClass) fail('unterminated character class') if (0 !== depth) fail('unbalanced parentheses') return out } // The engine regexp for a pattern in the subset: the rewrite, with the u // flag so that . and classes see whole characters, as the RE2 engines do. function compileRegexp(src: string): RegExp { const canon = canonicalRegexp(src) try { return new RegExp(canon, 'u') } /* node:coverage disable */ catch (_e: any) { // The scanner admits nothing the JavaScript engine refuses. throw regexpFault(src, 'not accepted by the engine') } /* node:coverage enable */ } // A RegExp given to a shape: no flags, and its source in the subset. function engineRegexp(re: RegExp): RegExp { if ('' !== re.flags) throw regexpFault(re.source, 'flags are not supported') return compileRegexp(re.source) } // Build the node for a key expression such as `{ 'a: Optional(Number)': 5 }`. // // expr() splices the example value in as the innermost builder call's last // argument. Where that lands in a shape slot the builder reads, it does the // right thing: `Min(2)` becomes `Min(2, 5)` and takes the example's kind and // default, `Child(Number)` becomes `Child(Number, [])` and becomes an array. // But a builder whose arity is already satisfied drops it silently — // `Optional(Number, 5)` ignores the 5 and injects the Number token's 0 — and // the example is the author's stated default, so it should survive. // // Building both ways tells the two apart: if the example made no difference to // the node, the builder ignored it, and it is applied as the value/default // instead. The kind is left alone, since only the builder knows whether it // declared one or merely defaulted to it. function keyExprNode(src: string, example: any, depth: number, meta?: NodeMeta) { if (undefined === example) { return expr({ src, d: depth, meta }) } let bare: any try { bare = expr({ src, d: depth, meta }) } catch (_e: any) { // The expression cannot be built without the example — Pick(["a"]) has // nothing to pick from — so the example plainly made a difference. bare = undefined } // A chain that names its kind (String, Integer.Min(2), Optional(Number), // Any) keeps it: the example is the value and the default, nothing more. // Without this the example's own kind won ({ 'a: Integer.Min(2)': 0 } read // as a number) and so did what its value implied ({ 'a: String': '' } // allowed the empty string). if (null != bare && bare.$?.shape$ && true === bare.u.tset) { const ex: any = nodize(example, depth, meta) bare.v = ex.v bare.f = ex.f bare.n = ex.n if (undefined === bare.c) { bare.c = ex.c } return bare } // Otherwise the example is appended as the innermost call's last argument, // so a builder that takes a shape consumes it: Child(Number) with [] is an // array of numbers, Min(2) with 0 a bounded number. const node: any = expr({ src, d: depth, meta }, example) if (null == node || !node.$?.shape$ || null == bare || !bare.$?.shape$ || !sameShapeNode(node, bare)) { return node } // The example made no difference to the node (Optional(Number, 5) drops // the 5), so it is the author's stated default, applied as the value. const ex: any = nodize(example, depth, meta) node.v = ex.v node.f = ex.f node.n = null != ex.v && S.object === typeof (ex.v) ? keys(ex.v).length : 0 // An Exact asks for a value only until it has a default, as a Default // around it would make it optional: here the example is that default, // unless the expression says Required outright. if (node.b.some((v: any) => S.Exact === v.n) && !/\bRequired\b/.test(src)) { node.r = false } return node } // Structural comparison of the parts of a node a key expression's example // could have influenced. function sameShapeNode(x: any, y: any): boolean { return x.t === y.t && x.r === y.r && x.p === y.p && x.b.length === y.b.length && x.a.length === y.a.length && JSON.stringify(x.v) === JSON.stringify(y.v) && JSON.stringify(x.f) === JSON.stringify(y.f) && JSON.stringify(x.c) === JSON.stringify(y.c) } function build(v: any, opts: ShapeOptions = {}, top = true): any { let out: any const t = Array.isArray(v) ? 'array' : null === v ? 'null' : typeof v if ('string' === t) { // A string is an expression; the empty string is the empty example, as // a required string's example is ({ 'a: String': '' }). out = '' === v ? v : expr(v) } else if ('number' === t || 'boolean' === t || 'null' === t) { out = v } else if (S.object === t) { const keymark = opts.valexpr?.keymark || '$$' let mark: any = undefined out = {} for (const [k, cv] of Object.entries(v)) { if (keymark === k && S.string === typeof cv) { mark = cv } // The example of a key expression is a value, so a string there is // the string itself ({ 'a: String.Optional': 'x' }). else { setprop(out, k, (S.string === typeof cv && isKeyExpr(k)) ? cv : build(cv, opts, false)) } } // The expression under the mark applies to the object that holds it, // and the sidecars beside it ("$$0") are its arguments, read from the // object or, where a type token has remade it, kept aside. if (S.string === typeof mark) { const refs: any = {} for (const k of keys(out)) { if (k.startsWith(keymark)) { refs[k.substring(keymark.length)] = out[k] } } // A carrier that holds sidecars and nothing else is the node its // expression names, String.Contains(1,$$0), or an empty object its // first call takes, Required.Child($$0); see carrierApplies. One with // no sidecars at all is an empty object ({"$$": "Closed"}). if (0 < keys(refs).length && keys(out).length === keys(refs).length) { const g = expr({ src: mark, refs, carrier: {} }) return top ? Shape(g, opts) : g } const node: any = nodize(out) const res: any = nodize(expr({ src: mark, node, refs }, node)) if (null != res.v && S.object === typeof res.v) { for (const k of keys(res.v)) { if (k.startsWith(keymark)) { delete res.v[k] } } res.n = keys(res.v).length } out = res } } else if (S.array === t) { out = v.map((n: any) => build(n, opts, false)) } if (top) { return Shape(out, opts) } return out } // Register the definitions a node carries, ahead of its other checks. function defineFirst(n: Node, s: State) { for (let bI = 0; bI < n.b.length; bI++) { if (S.Define === (n.b[bI] as any).n) { n.b[bI](s.val, {}, s) } } } function handleValidate(vf: Validate, s: State): Update { let update: Update = {} let valid = false let thrown try { // Check does not have to deal with `undefined` valid = undefined === s.val && ((vf as any).shape$?.Check) ? true : (s.check = vf, vf(s.val, update, s)) } catch (ve: any) { thrown = ve } let hasErrs = isarr(update.err) ? 0 < (update.err as Array).length : null != update.err if (!valid || hasErrs) { // Skip allows undefined if (undefined === s.val && (s.node.p || !s.node.r) && true !== update.done) { delete update.err return update } // Nullable allows null, whatever the check made of it. if (null === s.val && s.node.u.nullable) { delete update.err delete update.done return update } let w = update.why || S.check if (S.string === typeof (update.err)) { s.curerr.push(makeErr(s, (update.err as string))) } else if (S.object === typeof (update.err)) { // Assumes makeErr already called; only an error without a path of // its own needs the path built here. const path = pathstr(s) const patha = patharr(s) const errsrc = update.err if (isarr(errsrc)) { for (let eI = 0; eI < (errsrc as any[]).length; eI++) { const e = (errsrc as any[])[eI] if (null != e) { e.path = null == e.path ? path : e.path e.pathArr = null == e.pathArr ? patha : e.pathArr e.mark = null == e.mark ? 2010 : e.mark s.curerr.push(e) } } } else if (null != errsrc) { ;(errsrc as any).path = null == (errsrc as any).path ? path : (errsrc as any).path ;(errsrc as any).pathArr = null == (errsrc as any).pathArr ? patha : (errsrc as any).pathArr ;(errsrc as any).mark = null == (errsrc as any).mark ? 2010 : (errsrc as any).mark s.curerr.push(errsrc) } } else { let fname = vf.name if (null == fname || '' == fname) { fname = truncate(vf.toString().replace(/[ \t\r\n]+/g, ' ')) } s.curerr.push(makeErrImpl( w, s, 1045, undefined, { thrown }, fname)) } update.done = null == update.done ? true : update.done } // Use uval for undefined and NaN // The update is the plain object made above, so its own properties are // all it has. if ('uval' in update) { s.updateVal(update.uval) s.ignoreVal = false } else if (undefined !== update.val && !Number.isNaN(update.val)) { s.updateVal(update.val) s.ignoreVal = false } if (undefined !== update.node) { s.node = update.node } if (undefined !== update.type) { s.type = update.type } return update } // Create string description of property path, using "dot notation". function pathstr(s: State) { let out = null == s.ctx.path$ ? '' : s.ctx.path$.join('.') for (let i = 1; i <= s.dI; i++) { const p = s.path[i] if (null != p) { if (out.length > 0) out += '.' out += p } } return out } // Create an array form of the property path. Numeric entries for array // element indices are emitted as numbers; object keys remain strings. function patharr(s: State): (string | number)[] { const out: (string | number)[] = null == s.ctx.path$ ? [] : s.ctx.path$.slice() for (let i = 1; i <= s.dI; i++) { const p = s.path[i] if (null != p) { // ancestors[i] is the node whose child path[i] names. const parentNode = s.ancestors[i] out.push(parentNode && S.array === parentNode.t ? Number(p) : p) } } return out } // A bound on a number or a date compares the value itself; anything else is // measured by its length or key count. const isNumeric = (val: any) => S.number === typeof (val) || val instanceof Date function valueLen(val: any) { return S.number === typeof (val) ? val : S.number === typeof (val?.length) ? val.length : val instanceof Date ? val.getTime() : null != val && S.object === typeof (val) ? keys(val).length : NaN } function truncate(str?: string, len?: number): string { let strval = String(str) let outlen = null == len || isNaN(len) ? 30 : len < 0 ? 0 : ~~len let strlen = null == str ? 0 : strval.length let substr = null == str ? '' : strval.substring(0, strlen) substr = outlen < strlen ? substr.substring(0, outlen - 3) + '...' : substr return substr.substring(0, outlen) } // Builder Definitions // =================== // Value is required. const Required = function (this: any, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) node.r = true node.p = false if (undefined === shape) { node.f = undefined // Handle an explicit undefined. if (1 === arguments.length) { node.t = (S.undefined as ValType) node.v = undefined } } // Required(foo) by itself does set default value = foo, // which might then be used later. But if chained, the default cannot survive. else if (this?.$?.shape$) { node.f = undefined } return node } // Value can contain additional undeclared properties. const Open = function (this: any, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) node.c = Any() return node } // Value is optional. const Optional = function (this: any, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) node.r = false // Handle an explicit undefined. if (undefined === shape && 1 === arguments.length) { node.t = (S.undefined as ValType) node.v = undefined } return node } // Strict ISO 8601 / RFC 3339 date-time: the one form both implementations parse // identically. Calendar ranges are checked so that 2024-02-30 is rejected // rather than rolled over into March. const ISO_DATETIME_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?(Z|[+-]\d{2}:\d{2})$/ function isoDateTime(s: string): boolean { const m = ISO_DATETIME_RE.exec(s) if (null == m) { return false } const y = +m[1], mo = +m[2], d = +m[3], h = +m[4], mi = +m[5], sec = +m[6] if (mo < 1 || 12 < mo || 23 < h || 59 < mi || 59 < sec) { return false } const leap = (0 === y % 4 && 0 !== y % 100) || 0 === y % 400 const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][mo - 1] if (d < 1 || days < d) { return false } if ('Z' !== m[8] && (23 < +m[8].substring(1, 3) || 59 < +m[8].substring(4, 6))) { return false } return true } // Decimal numeric strings only: no hex, no Infinity, nothing JS's Number() // would accept that a Go strconv would not. const NUMERIC_RE = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/ // The value a Coerce node converts to for kind t, or undefined to leave it as // it is (and let the type check report it). function coerceTo(t: string, val: any): any { const vt = typeof val if (S.number === t || S.integer === t) { if (S.string === vt) { const str = val.trim() return NUMERIC_RE.test(str) && isFinite(Number(str)) ? Number(str) : undefined } if (S.boolean === vt) { return val ? 1 : 0 } } else if (S.string === t) { if (S.number === vt) { return isFinite(val) ? String(val) : undefined } if (S.boolean === vt) { return val ? 'true' : 'false' } } else if (S.boolean === t) { if (S.string === vt) { const str = val.trim().toLowerCase() return 'true' === str || '1' === str ? true : 'false' === str || '0' === str ? false : undefined } if (S.number === vt) { return 1 === val ? true : 0 === val ? false : undefined } } else if (S.date === t) { if (S.string === vt) { const str = val.trim() return isoDateTime(str) ? new Date(str) : undefined } if (S.number === vt) { return isFinite(val) ? new Date(val) : undefined } } return undefined } // Convert the value to the node's kind where the conversion is unambiguous, // before the type check: a decimal string to a number, "true"/"false"/"1"/"0" // to a boolean, a number or boolean to a string, an ISO 8601 string or a time // value to a Date. Anything else is left alone, so the usual type error speaks. const Coerce = function (this: any, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) const coercer: any = function Coerce(val: any, update: Update, state: State) { const c = coerceTo(state.node.t, val) if (undefined !== c) { update.val = c } return true } coercer.n = S.Coerce // Ahead of any bound, so a bound sees the converted value. node.b.unshift(coercer) return node } // String Formats: Email, Url, Uuid, DateTime, Ip, Ipv4, Ipv6 // ========================================================== // Every pattern here is written so that the JavaScript engine and RE2 agree on // it: ASCII classes only, no lookaround, explicit whitespace. // A pragmatic RFC 5322 addr-spec: a dot-atom local part of at most 64 // characters, then a dotted domain ending in an alphabetic top-level label, // 254 characters in all. No quoted local parts, no address literals. const EMAIL_RE = /^[A-Za-z0-9!#$%&'*+\/=?^_`{|}~-]+(?:\.[A-Za-z0-9!#$%&'*+\/=?^_`{|}~-]+)*@(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)+[A-Za-z]{2,63}$/ function isEmail(s: string): boolean { return s.length <= 254 && s.indexOf('@') <= 64 && EMAIL_RE.test(s) } // scheme://[user@]host[:port][/path][?query][#fragment]: an absolute URL with // a non-empty host and no whitespace. Nothing is decoded or resolved. const URL_RE = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/(?:[^ \t\r\n\/?#@]+@)?(?:\[[0-9A-Fa-f:.]+\]|[^ \t\r\n\/?#@:\[\]]+)(?::\d{1,5})?(?:[\/?#][^ \t\r\n]*)?$/ // 8-4-4-4-12 hex digits; any version, including the nil UUID. const UUID_RE = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/ // A dotted quad of decimal octets 0-255 without leading zeros. const IPV4_RE = /^(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/ const HEX4_RE = /^[0-9A-Fa-f]{1,4}$/ // RFC 4291 text form: eight 16-bit hex groups, one optional "::" standing for // a run of zero groups, and optionally a trailing dotted quad in place of the // last two groups. No zone index and no prefix length. function isIpv6(s: string): boolean { const parts = s.split('::') if (2 < parts.length) { return false } const head = '' === parts[0] ? [] : parts[0].split(':') const tail = 2 === parts.length && '' !== parts[1] ? parts[1].split(':') : [] const groups = head.concat(tail) let count = 0 for (let gI = 0; gI < groups.length; gI++) { if (HEX4_RE.test(groups[gI])) { count++ } // A dotted quad may only end the address, so not ahead of a "::". else if (gI === groups.length - 1 && (1 === parts.length || head.length <= gI) && IPV4_RE.test(groups[gI])) { count += 2 } else { return false } } return 2 === parts.length ? count <= 7 : 8 === count } // A format is a before on a string-shaped node. It speaks only once the value // is known to be present and of the node's kind; otherwise the structural // check reports the real problem. function makeFormatBuilder( self: any, shape: any, name: string, what: string, valid: (str: string) => boolean ) { let node = buildize(chainNode(self), shape) // A format is a shape of string, so an untyped node becomes one. if (S.any === node.t) { Type.call(node, String) } let validator: any = function(val: any, update: Update, state: State) { if (undefined === val || typeWillFail(state)) { return true } if (S.string === typeof val && valid(val)) { return true } update.err = makeErr(state, S.Value + ' ' + S.$VALUE + S.forprop + S.$PATH + ' is not a valid ' + what + '.', name) return false } Object.defineProperty(validator, S.name, { value: name }) validator.n = name validator.s = () => name validator[Symbol.for('nodejs.util.inspect.custom')] = name validator.toJSON = () => name attach(node.b, validator) return node } const Email = bare()(function Email (this: any, shape?: Node | V): Node { return makeFormatBuilder(this, shape, S.Email, 'email address', isEmail) }) const Url = bare()(function Url (this: any, shape?: Node | V): Node { return makeFormatBuilder(this, shape, S.Url, 'URL', (s) => URL_RE.test(s)) }) const Uuid = bare()(function Uuid (this: any, shape?: Node | V): Node { return makeFormatBuilder(this, shape, S.Uuid, 'UUID', (s) => UUID_RE.test(s)) }) // The string form of a date-time; the value stays a string. Coerce(Date) is // the one that produces a Date. const DateTime = bare()(function DateTime (this: any, shape?: Node | V): Node { return makeFormatBuilder(this, shape, S.DateTime, 'ISO 8601 date-time', isoDateTime) }) const Ip = bare()(function Ip (this: any, shape?: Node | V): Node { return makeFormatBuilder(this, shape, S.Ip, 'IP address', (s) => IPV4_RE.test(s) || isIpv6(s)) }) const Ipv4 = bare()(function Ipv4 (this: any, shape?: Node | V): Node { return makeFormatBuilder(this, shape, S.Ipv4, 'IPv4 address', (s) => IPV4_RE.test(s)) }) const Ipv6 = bare()(function Ipv6 (this: any, shape?: Node | V): Node { return makeFormatBuilder(this, shape, S.Ipv6, 'IPv6 address', isIpv6) }) // Isolated Validation: Catch, Transform, Ignore // ============================================= // These builders take the checks a node carries — its befores, its afters — // inside, and validate the node as a whole (those checks, the structural // check, every descendant) in a sub-run before the node itself proceeds. Only // then is the outcome of the entire subtree known: a node's afters run before // its children are visited, so an after alone cannot see a descendant fail. type Inner = { b: Validate[], a: Validate[] } function takeInner(node: Node): Inner { const inner = { b: node.b, a: node.a } node.b = [] node.a = [] return inner } // Render the taken checks ahead of the taking builder, so that the shape // still reads Number.Min(2).Catch(0). function innerDesc(inner: Inner, n: Node): string { return inner.b.concat(inner.a).map((v: any) => v.s ? v.s(n) + '.' : '').join('') } const probeShapes = new WeakMap() // Validate the node as it stands, with the taken checks, in isolation. Errors // are collected, with their full paths, rather than thrown; Define names are // shared with the run that is probing. function probeNode(state: State, inner: Inner, val: any): { out: any, errs: ErrDesc[] } { // Errors must be observable, so the probe is never silent (Ignore's e). let ps = probeShapes.get(inner) if (undefined === ps) { const top: any = { ...state.node, b: inner.b, a: inner.a, e: true } ps = { top, exec: shapify(top) } probeShapes.set(inner, ps) } else { // The node may have been wrapped further since (Optional, Default, ...). Object.assign(ps.top, state.node, { b: inner.b, a: inner.a, e: true }) } const errs: ErrDesc[] = [] const ref = state.ctx.ref = state.ctx.ref || {} const out = ps.exec(val, { err: errs, ref, log: state.ctx.log, path$: patharr(state), trial$: state.trials }) return { out, errs } } // The taken checks and the structural check ran in the probe; the value still // goes back to the parent, which a lone done would prevent. const release: Validate = function release(_val: any, update: Update) { update.done = false return true } function jsonText(val: any): string { return '' + JSON.stringify(val) } // Whatever fails inside is replaced by the fallback, and raises nothing. const Catch = function (this: any, fallback: F, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) const inner = takeInner(node) const catcher: any = function Catch(val: any, update: Update, state: State) { const { out, errs } = probeNode(state, inner, val) update.uval = 0 < errs.length ? clone(fallback) : out update.done = true return true } catcher.n = S.Catch catcher.a = [fallback] catcher.s = (n: Node) => innerDesc(inner, n) + S.Catch + '(' + jsonText(fallback) + ')' catcher.inner = inner attach(node.b, catcher) attach(node.a, release) return node } // Replace a valid value with a function of it. An invalid one fails as it // would have, with the same errors. const Transform = function ( this: any, transform: (val: ShapeResult, state: State) => R, shape?: Node | V ): Node { let node = buildize(chainNode(this), shape) const inner = takeInner(node) const transformer: any = function Transform(val: any, update: Update, state: State) { const { out, errs } = probeNode(state, inner, val) if (0 < errs.length) { update.err = errs return false } update.uval = transform(out, state) update.done = true return true } transformer.n = S.Transform transformer.s = (n: Node) => innerDesc(inner, n) + S.Transform transformer.inner = inner attach(node.b, transformer) attach(node.a, release) return node } // Attach a description to the node, read back as node.m.description. const Describe = function (this: any, description: string, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) node.m = node.m || {} node.m.description = '' + description return node } // Discriminated Union // =================== // Choose the branch by the value of a tag property, then validate against that // branch alone, so the errors are its own rather than a list of every // alternative. An object-shaped branch without the tag property has it added, // as the literal it is keyed by. const Discriminated = function >( this: any, tag: T, branches: B ): Node<{ [K in keyof B]: B[K] & { [P in T]: Literal } }[keyof B]> { if (S.string !== typeof tag || '' === tag || null == branches || S.object !== typeof branches || isarr(branches) || 0 === keys(branches).length) { throw new Error('Shape: Discriminated needs a tag property name and at least one branch') } let node = buildize(chainNode(this)) node.t = (S.list as ValType) node.r = true const tags = keys(branches).sort() const shapes = new Map() for (const t of tags) { const bn = nodize(branches[t]) if (S.object === bn.t && null != bn.v && !hasOwn(bn.v, tag)) { setprop(bn.v, tag, nodize(t)) } shapes.set(t, shapify(bn)) } node.u.list = tags.map((t) => shapes.get(t).node()) node.u.discriminated = { tag, tags } const validator: any = function Discriminated(val: any, update: Update, state: State) { // Required or optional is for the structural check to say. if (undefined === val) { return true } const tv = null != val && S.object === typeof val && !isarr(val) ? ownval(val, tag) : undefined if (undefined === tv) { update.err = makeErr(state, S.Value + ' ' + S.$VALUE + S.forprop + S.$PATH + ' is not an object with a "' + tag + '" property.', S.Discriminated) return false } const shape = S.string === typeof tv ? shapes.get(tv) : undefined if (undefined === shape) { update.err = makeErr(state, S.Value + ' ' + S.$VALUE + S.forprop + S.$PATH + ' has unknown "' + tag + '" ' + JSON.stringify(tv) + ', expected one of: ' + tags.join(', ') + '.', S.Discriminated) return false } const errs: ErrDesc[] = [] const ref = state.ctx.ref = state.ctx.ref || {} const out = shape(val, { err: errs, ref, log: state.ctx.log, path$: patharr(state), trial$: state.trials }) if (0 < errs.length) { update.err = errs return false } update.val = out return true } validator.n = S.Discriminated validator.a = [tag, branches] attach(node.b, validator) return node } // Object Algebra // ============== // Build a new object shape out of an existing one. The result is a fresh // node, so the source is left as it was and one base can be reshaped many // times. Key expressions in the source (`{ 'a: Min(2)': 0 }`) are compiled // here, since the algebra has to know the real property names. type Entry = { key: string, child: any } function objectEntries(n: Node): Entry[] { const out: Entry[] = [] const vkeys = keys(n.v) for (let kI = 0; kI < vkeys.length; kI++) { const k = vkeys[kI] const m = KEY_EXPR_RE.exec(k) if (m && '' !== m[3]) { out.push({ key: keyExprName(m[1]), child: keyExprNode(m[3], n.v[k], 0) }) } else { out.push({ key: k, child: n.v[k] }) } } return out } // A structural copy of a node: the same settings, with its own value and // check lists, so that changing the copy leaves the original as it was. function copyNode(n: Node, over?: Record): Node { const v = isarr(n.v) ? n.v.slice() : (null != n.v && S.object === typeof n.v) ? { ...n.v } : n.v const copy = { $: SHAPE, t: n.t, d: n.d, v, f: n.f, n: n.n, c: n.c, r: n.r, p: n.p, k: [], e: n.e, z: n.z, u: { ...n.u }, b: n.b.slice(), a: n.a.slice(), m: { ...n.m }, ...over, } as unknown as Node return buildize(copy) } function ownprop(o: any, k: string, value: any) { defprop(o, k, { value, enumerable: true, writable: true, configurable: true }) } function objectBase(self: any, shape: any, name: string): Node { const base = buildize(chainNode(self), shape) if (S.object !== base.t) { throw new Error('Shape: ' + name + ' needs an object shape') } return base } // The base's settings with just these properties. An object default is // narrowed to them too. function objectNode(base: Node, entries: Entry[]): Node { // Own properties, so that a "__proto__" key is a property and not the // prototype. const v: any = {} for (const e of entries) { ownprop(v, e.key, e.child) } let f = base.f if (null != f && S.object === typeof f && !isarr(f)) { f = {} for (const e of entries) { if (hasOwn(base.f, e.key) && undefined !== base.f[e.key]) { ownprop(f, e.key, base.f[e.key]) } } } return copyNode(base, { v, f, n: entries.length }) } function keyList(names: any, name: string): string[] { const list = isarr(names) ? names : [names] for (const k of list) { if (S.string !== typeof k) { throw new Error('Shape: ' + name + ' needs a list of property names') } } return list } // Keep only the named properties. Naming one the shape does not declare is // an error: there is nothing there to pick. const Pick = function ( this: any, names: N, shape?: Node | V ): Node> { const base = objectBase(this, shape, S.Pick) const want = keyList(names, S.Pick) const entries = objectEntries(base) for (const k of want) { if (undefined === entries.find((e) => e.key === k)) { throw new Error('Shape: ' + S.Pick + ': unknown property "' + k + '"') } } return objectNode(base, entries.filter((e) => want.includes(e.key))) } // Drop the named properties. A name the shape does not declare is simply not // there to drop. const Omit = function ( this: any, names: N, shape?: Node | V ): Node> { const base = objectBase(this, shape, S.Omit) const want = keyList(names, S.Omit) return objectNode(base, objectEntries(base).filter((e) => !want.includes(e.key))) } // Every declared property becomes optional, as Optional would make it: a // type token then injects its empty value, a literal its own. Shallow: a // nested object's own properties are as they were. const Partial = function (this: any, shape?: Node | V): Node { const base = objectBase(this, shape, S.Partial) return objectNode(base, objectEntries(base).map((e) => ({ key: e.key, child: copyNode(nodize(e.child), { r: false }), }))) } // Add the properties of another object shape; a property both declare takes // the extension's. Only its properties are taken: the result stays open or // closed as the base was. const Extend = function (this: any, extra: E, shape?: Node | V): Node> { const base = objectBase(this, shape, S.Extend) const ext = nodize(extra) if (S.object !== ext.t) { throw new Error('Shape: ' + S.Extend + ' needs an object to extend with') } const entries = objectEntries(base) for (const e of objectEntries(ext)) { const i = entries.findIndex((x) => x.key === e.key) if (-1 === i) { entries.push(e) } else { entries[i] = e } } return objectNode(base, entries) } // Value may also be null. Absent is still governed by required/optional. const Nullable = function (this: any, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) node.u.nullable = true return node } // A number with no fractional part. Behaves as a type token: required, with // the default 0, so Optional(Integer) injects 0 and Integer alone demands one. const Integer = bare()(function Integer (this: any, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) node.t = (S.integer as ValType) node.r = true node.p = false node.v = 0 node.f = 0 node.u.tset = true return node }) // Value can be anything. const Any = bare()(function Any (this: any, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) node.t = (S.any as ValType) // Any is a kind the spec asked for, not an absent one: a key expression's // example value supplies the default but must not narrow it. (Type marks its // own nodes; Any is a builder, so it never passes through Type.) node.u.tset = true if (undefined !== shape) { node.v = shape node.f = shape } return node }) // Custom error message. const Fault = function (this: any, msg: string, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) node.z = msg return node } // Value is skipped if not present (optional, but no default). const Skip = function (this: any, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) node.r = false // Do not insert empty arrays and objects. node.p = true return node } // Errors for this value are ignored, and the value is undefined. The whole // subtree is probed, so a failing descendant is swallowed too. const Ignore = function (this: any, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) node.r = false // Do not insert empty arrays and objects. node.p = true node.e = false const inner = takeInner(node) const ignorer: any = function Ignore(val: any, update: Update, state: State) { const { out, errs } = probeNode(state, inner, val) update.uval = 0 < errs.length ? undefined : out update.done = true return true } ignorer.n = S.Ignore ignorer.s = (n: Node) => innerDesc(inner, n).replace(/\.$/, '') ignorer.inner = inner attach(node.b, ignorer) attach(node.a, release) return node } // Value must be a function. const Func = bare()(function Func (this: any, shape?: Node | V): Node { let node = buildize(chainNode(this)) node.t = (S.function as ValType) node.v = shape node.f = shape return node }) // Specify default value. const Default = function (this: any, dval?: D, shape?: Node | V): Node { // The node is the shape's, given or chained onto, so an object or array // shape keeps its children and child shape, and a composition its // branches; the default is only the value: X.Default(v) is Default(v, X). // An untyped shape (Required(), Exact(1)) is built over the default // instead, and so takes the default's kind, as Default(value) alone does. const self = chainNode(this) const over = undefined === shape && (undefined === self || S.any === self.t) let node: Node if (over) { node = buildize(self, dval) } else if (undefined === shape) { node = buildize(self) } else if (S.any === nodize(shape).t) { node = buildize(buildize(self, dval), shape) } else { node = buildize(self, shape) } node.r = false node.f = dval if (over) { let t = typeof dval if (S.function === t && IS_TYPE[(dval as any).name]) { node.t = ((dval as any).name.toLowerCase() as ValType) node.f = clone(EMPTY_VAL[node.t]) } } // Always insert default. node.p = false return node } // String can be empty. const Empty = function (this: any, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) node.u.empty = true return node } // Value will never match anything. // Absent is still governed by required or optional: Never alone requires a // value, and so fails always; Optional or Skip around it means the value // must be absent. const Never = bare()(function Never (this: any, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) node.t = (S.never as ValType) if (!this?.$?.shape$) { node.r = true } return node as Node }) // Inject the key path of the value. // OR: provide validation of Key - depth could also be a RegExp // Key yields the parent key, the path up to a depth (joined with a // separator when one is given), or whatever a function of the path returns. interface KeyBuilder { (this: any): Node (this: any, depth: number, join: string): Node (this: any, depth: number): Node (this: any, depth: (path: string[], state: State) => R): Node } const Key = bare()(function Key(this: any, depth?: number | Function, join?: string): Node { let node = buildize(chainNode(this)) let ascend = S.number === typeof depth node.t = (S.string as ValType) if (ascend && null == join) { node = nodize([]) } let custom: any = null if (S.function === typeof depth) { custom = depth node = Any() } const keyer: any = function Key(_val: any, update: Update, state: State) { if (custom) { update.val = custom(state.path, state) } else if (ascend) { let d = (depth as number) update.val = state.path.slice( state.path.length - 1 - (0 <= d ? d : 0), state.path.length - 1 + (0 <= d ? 0 : 1), ) if (S.string === typeof join) { update.val = update.val.join(join) } } else if (null == depth) { update.val = state.path[state.path.length - 2] } return true } keyer.n = S.Key keyer.a = custom ? [custom] : ascend ? (null == join ? [depth] : [depth, join]) : [] attach(node.b, keyer) return node } as KeyBuilder) // Pass only if all match. Does not short circuit (as defaults may be missed). const All = function (this: any, ...inshapes: S): Node { const node = buildize(chainNode(this)) node.t = (S.list as ValType) node.r = true const shapes = inshapes.map(s => Shape(s)) node.u.list = shapes.map(g => g.node()) const validator = function All(val: any, update: Update, state: State) { let pass = true // The value is threaded through the branches, each producing from what // the one before it made; the subject itself is never changed, so a // failing composition leaves it as it was. A failing branch's errors // are the errors, each said once. const err: ErrDesc[] = [] const path$ = patharr(state) let out = clone(val) for (let shape of shapes) { let subctx = { ...state.ctx, err: [] as ErrDesc[], path$, trial$: state.trials } const res = shape(out, subctx) if (0 < subctx.err.length) { pass = false for (const e of subctx.err) { if (!err.some((x: ErrDesc) => x.path === e.path && x.text === e.text)) { err.push(e) } } } else if (undefined !== res) { // A branch that drops its value (Ignore) passes the previous one on. out = res } } // An absent subject stays absent, for the required check to see. if (pass && undefined !== val) { update.val = out } else if (!pass) { update.why = S.All update.err = err } return pass } validator.n = S.All validator.a = inshapes attach(node.b, validator) return node } // Pass if the number of shapes the value satisfies is one the count admits. // The count is a whole number, for exactly that many, or a shape the number // must satisfy: Nof(1, ...) is exactly one, Nof(Min(1), ...) at least one, // Nof(0, s) not s. A shape is tried on a copy of the value only while the // shapes left untried could still change the verdict. A count of exactly // one produces: the one shape the value satisfies makes the result. Any // other count only checks, and the value is left as it was given. An absent // value is not tried, so whether it may be absent is the node's required or // optional. interface NofBuilder { (this: any, count: 0, ...shapes: S): Node (this: any, count: number, ...shapes: S): Node (this: any, count: any, ...shapes: S): Node } const Nof = function Nof(this: any, count: any, ...inshapes: any[]): Node { const exact = S.number === typeof count if (undefined === count || (exact && !(Number.isInteger(count) && 0 <= count))) { throw new Error('Shape: Nof needs a whole number of zero or more, or a shape for the count') } const node = buildize(chainNode(this)) node.t = (S.list as ValType) node.r = true const shapes = inshapes.map(s => Shape(s)) node.u.list = shapes.map(g => g.node()) // The counts the count admits, from none of the shapes to all of them. const countShape = exact ? undefined : Shape(count) const ok: boolean[] = [] for (let c = 0; c <= shapes.length; c++) { ok.push(exact ? c === count : (countShape as any).match(c)) } node.u.nof = { count: exact ? count : (countShape as any).node(), ok } // Whether the count admits exactly one shape and nothing else. const one = 1 < ok.length && ok.every((v: boolean, c: number) => v === (1 === c)) // Exactly one of shapes of different kinds is the shape of the value's // kind: the value is put to that shape alone (see nofKindsNow). node.u.nof.one = one const validator = function Nof(val: any, update: Update, state: State) { if (undefined === val) { return true } // Shapes of different kinds: the value is put only to the shape of its // kind, whose errors are then the errors. A value of no kind listed is // counted, and fails, as any other. const kinds = nofKindsNow(node) const kI = undefined === kinds ? -1 : kinds.indexOf(kindOf(val) as string) if (-1 < kI) { const err: ErrDesc[] = [] const out = shapes[kI](clone(val), { ...state.ctx, err, path$: patharr(state), own$: true, trial$: state.trials }) if (0 < err.length) { update.err = err return false } update.val = out return true } let k = 0 let tried = 0 let matched = 0 const tctx = trialCtx(state, patharr(state)) while (NOF_SOME === nofSpan(ok, k, shapes.length - tried)) { if (trial(shapes[tried], val, state, tctx)) { k++ matched = tried } tried++ } if (NOF_NONE === nofSpan(ok, k, shapes.length - tried)) { update.why = S.Nof update.err = [ makeErr(state, S.Value + ' ' + S.$VALUE + S.forprop + S.$PATH + ' satisfies ' + k + (tried < shapes.length ? ' to ' + (k + shapes.length - tried) : '') + ' of: ' + inshapes.map(x => stringify(x, true)).join(', ') + '; the count must be ' + stringify(count, true) + '.') ] return false } // Exactly one: the shape the value satisfies produces from a copy. if (one) { update.val = shapes[matched](clone(val), { ...state.ctx, err: [], path$: patharr(state), trial$: state.trials }) } return true } validator.n = S.Nof validator.a = [count, ...inshapes] attach(node.b, validator) return node } as NofBuilder const NOF_NONE = 0 const NOF_SOME = 1 // The kind of a JSON value, by its type or its node's. const KIND_OF_TYPE: any = { null: 'null', boolean: 'boolean', number: 'number', integer: 'number', string: 'string', regexp: 'string', object: 'object', array: 'array', } function kindOf(val: any): string | undefined { return null === val ? 'null' : isarr(val) ? 'array' : KIND_OF_TYPE[typeof val] } // The checks that leave a shape's kind as it was: a shape with no others // takes a value of its own kind only. const KIND_KEEPING: any = { Above: 1, Below: 1, Check: 1, Contains: 1, DateTime: 1, Define: 1, Email: 1, Exact: 1, Ip: 1, Ipv4: 1, Ipv6: 1, Len: 1, Max: 1, Min: 1, Unique: 1, Url: 1, Uuid: 1, } // The kinds of a Nof's shapes, where its count admits exactly one and each // shape is of a different kind (see nofKinds), worked out again when a // builder may have re-chained a shape since (see VGEN). function nofKindsNow(n: Node): string[] | undefined { const nof = n.u.nof if (nof.kgen !== VGEN) { nof.kinds = nof.one ? nofKinds(n.u.list) : undefined nof.kgen = VGEN } return nof.kinds } // The kinds of the shapes, where each is of a different kind and takes // values of that kind only. function nofKinds(list: any[]): string[] | undefined { const kinds = list.map((n: any) => !n.u.nullable && n.b.concat(n.a).every((v: any) => KIND_KEEPING[v.n]) ? KIND_OF_TYPE[n.t] : undefined) return kinds.every((k: any, i: number) => undefined !== k && i === kinds.indexOf(k)) ? kinds : undefined } // Whether the counts from k to k + open are all admitted (2), some (1) or // none (0): a shape is tried only while it is some. function nofSpan(ok: boolean[], k: number, open: number): number { let yes = 0 for (let c = k; c <= k + open; c++) { yes += ok[c] ? 1 : 0 } return 0 === yes ? NOF_NONE : open + 1 === yes ? 2 : NOF_SOME } // The trials one validation may run, unless its options say otherwise. const TRIALS = 100000 function trialBudget(n: any): number { return Number.isInteger(n) && 0 < n ? n : TRIALS } // The context a composition's trials run in, made once for all of them: a // trial's errors are thrown away, so they are recorded without text, and // the path is there for the error of a spent budget (see trial). function trialCtx(state: State, path$: (string | number)[]): any { return { ...state.ctx, err: [], path$, trial$: state.trials, terse$: true } } // Try a shape on a copy of a value: a verdict, which changes nothing. Each // trial takes one from the budget of the validation it is part of. Past the // budget a trial refuses, and the validation fails with the error made here, // at the first place a trial was refused (see exec). function trial(shape: any, val: any, state: State, tctx: any): boolean { const t = state.trials if (t.left <= 0) { if (undefined === t.spent) { // Whoever asked, a trial or not, this error is read in full. const terse = state.terse state.terse = false t.spent = makeErr(state, TEXT_PREFIX + ' needs more trials than the budget of ' + t.budget + '.', S.trial) state.terse = terse } return false } t.left-- // Each trial starts as a fresh copy of the context would: what a trial // writes there (its errors and definitions) stays its own. tctx.err = [] tctx.ref = state.ctx.ref return shape.match(clone(val), tctx) } // Pass if the value satisfies the shape its condition picks: then, where the // value satisfies cond, and otherwise where it does not. The condition is // tried on a copy and only checks (see trial); the shape it picks validates // the value and makes the result, and its errors are the errors. A shape // not given passes. An absent value is not tried, so whether it may be // absent is the node's required or optional. const When = function When(this: any, cond: any, then?: any, otherwise?: any): Node { if (undefined === cond) { throw new Error('Shape: When needs a shape for its condition') } const node = buildize(chainNode(this)) node.t = (S.list as ValType) node.r = true const inshapes = [cond, undefined === then ? Any() : then, undefined === otherwise ? Any() : otherwise] const shapes = inshapes.map(s => Shape(s)) node.u.list = shapes.map(g => g.node()) node.u.when = true const validator = function When(val: any, update: Update, state: State) { if (undefined === val) { return true } const path$ = patharr(state) const picked = trial(shapes[0], val, state, trialCtx(state, path$)) ? shapes[1] : shapes[2] const err: ErrDesc[] = [] const out = picked(clone(val), { ...state.ctx, err, path$, trial$: state.trials }) if (0 < err.length) { update.why = S.When update.err = err return false } // A shape that drops its value (Ignore) leaves the value as it was. if (undefined !== out) { update.val = out } return true } validator.n = S.When validator.a = inshapes attach(node.b, validator) return node } // Pass if the number of an array's items that satisfy the shape is one the // count admits. The count is a whole number, for exactly that many, or a // shape the number must satisfy: Contains(Min(1), s) is at least one, // Contains(0, s) none. Each item is tried on a copy (see trial), and only // while the items left untried could still change the verdict; the array is // left as it was given. A value that is not an array is not counted, so // whether it is one is the node's type check. Without a spec of its own the // node is an array of anything. const Contains = function Contains(this: any, count: any, inshape: any, spec?: any): Node { const exact = S.number === typeof count if (undefined === count || (exact && !(Number.isInteger(count) && 0 <= count))) { throw new Error('Shape: Contains needs a whole number of zero or more, or a shape for the count') } if (undefined === inshape) { throw new Error('Shape: Contains needs a shape for the items it counts') } const node = buildize(chainNode(this), undefined === spec && !this?.$?.shape$ ? [] : spec) const shape = Shape(inshape) const countShape = exact ? undefined : Shape(count) const bounds = exact ? { lo: count, hi: count, exact: true } : countBounds((countShape as any).node()) // Whether the count admits c, kept for the next array to ask. const okc: boolean[] = [] const admits = (c: number) => undefined === okc[c] ? (okc[c] = (countShape as any).match(c)) : okc[c] const validator = function Contains(val: any, update: Update, state: State) { if (!isarr(val)) { return true } // The counts from k to k + open are all, some or none admitted: at once // for a count that is an interval, and otherwise off the running total // of admitted counts. const n = val.length let span = (k: number, open: number) => Math.min(bounds.hi, k + open) < Math.max(bounds.lo, k) ? NOF_NONE : bounds.lo <= k && k + open <= bounds.hi ? 2 : NOF_SOME if (!bounds.exact) { const yes = [0] for (let c = 0; c <= n; c++) { yes.push(yes[c] + (admits(c) ? 1 : 0)) } span = (k: number, open: number) => { const y = yes[k + open + 1] - yes[k] return 0 === y ? NOF_NONE : open + 1 === y ? 2 : NOF_SOME } } const path$ = patharr(state) const tctx = trialCtx(state, path$) let k = 0 let tried = 0 while (NOF_SOME === span(k, n - tried)) { tctx.path$ = path$.concat(tried) if (trial(shape, val[tried], state, tctx)) { k++ } tried++ } if (NOF_NONE === span(k, n - tried)) { update.err = makeErr(state, TEXT_PREFIX + ' has ' + k + (tried < n ? ' to ' + (k + n - tried) : '') + ' of its items satisfying ' + stringify(inshape, true) + '; the count must be ' + stringify(count, true) + '.') return false } return true } validator.n = S.Contains validator.a = [count, inshape] validator.u = { bounds, shape: shape.node() } validator.c = exact ? count : (countShape as any).node() validator.s = () => S.Contains + '(' + stringify(count, true) + ',' + stringify(inshape, true) + ')' attach(node.b, validator) return node } // Pass if no two of an array's items are equal as JSON values: a number by // its value, an array by its items in order, an object by its keys and // their values, in any order. The error names the first item equal to one // before it, and the first of those. A value that is not an array is not // checked. Without a spec of its own the node is an array of anything. const Unique = function Unique(this: any, spec?: any): Node { const node = buildize(chainNode(this), undefined === spec && !this?.$?.shape$ ? [] : spec) const validator = function Unique(val: any, update: Update, state: State) { if (!isarr(val)) { return true } const [i, j] = repeated(val) if (-1 === j) { return true } update.err = makeErr(state, TEXT_PREFIX + ' must have unique items (items ' + i + ' and ' + j + ' are equal).') return false } validator.n = S.Unique validator.a = [] as any[] validator.s = () => S.Unique + '()' attach(node.b, validator) return node } // The first item equal to an item before it, and the first of those; -1 for // both where no two are equal. A scalar is looked up by its value, and an // array or plain object compared with the containers before it. function repeated(items: any[]): [number, number] { const seen = new Map() const containers: number[] = [] for (let j = 0; j < items.length; j++) { const v = items[j] if (isContainer(v)) { for (const i of containers) { if (sameJson(items[i], v)) { return [i, j] } } containers.push(j) } else { const i = seen.get(v) if (undefined !== i) { return [i, j] } seen.set(v, j) } } return [-1, -1] } // An array, or an object made by a literal or JSON.parse. function isContainer(v: any): boolean { if (isarr(v)) { return true } const proto = null !== v && S.object === typeof v ? Object.getPrototypeOf(v) : undefined return Object.prototype === proto || null === proto } // Equal as JSON values (see Unique); a value that is neither container nor // JSON scalar is equal to itself alone. function sameJson(x: any, y: any): boolean { if (x === y || (x !== x && y !== y)) { return true } if (!isContainer(x) || !isContainer(y) || isarr(x) !== isarr(y)) { return false } const xk = keys(x) return xk.length === keys(y).length && xk.every((k: string) => hasOwn(y, k) && sameJson(x[k], y[k])) } // Value must match excatly one of the literal values provided. const Exact = function (this: any, ...vals: T): Node> { const node = buildize(chainNode(this)) // Exact asks for a value, as a type token does, so Optional or Skip after // it lets the value be absent. Chained, the node stays as it was. if (!this?.$?.shape$) { node.r = true } const validator = function Exact(val: any, update: Update, state: State) { for (let i = 0; i < vals.length; i++) { if (val === vals[i]) { return true } } const hasDftl = state.node.hasOwnProperty('f') if (hasDftl && undefined === val) { const valDftl = state.node.f for (let i = 0; i < vals.length; i++) { if (valDftl === vals[i]) { return true } } } // Absent, where the node does not require a value and has no default // to put in its place. if (undefined === val && (state.node.p || (!state.node.r && undefined === state.node.f))) { return true } update.err = makeErr(state, S.Value + ' ' + S.$VALUE + S.forprop + S.$PATH + ' must be exactly one of: ' + vals.map((v: any) => stringify(v, true)).join(', ') ) update.done = true return false } validator.n = S.Exact validator.a = vals validator.s = () => S.Exact + '(' + vals.map((v: any) => stringify(v, true)).join(',') + ')' attach(node.b, validator) return node } // Define a custom operation to run before standard matching. const Before = function ( this: any, validate: Validate, shape?: Node | V ): Node { let node = buildize(chainNode(this), shape) attach(node.b, validate) return node } // Define a custom operation to run after standard matching. const After = function ( this: any, validate: Validate, shape?: Node | V ): Node { let node = buildize(chainNode(this), shape) attach(node.a, validate) return node } // Define a customer validation function. const Check = function ( this: any, check: Validate | RegExp | string, shape?: Node | V ): Node { let node = buildize(chainNode(this), shape) node.r = true if (S.function === typeof check) { let c$ = check as any c$.shape$ = c$.shape$ || {} c$.shape$.Check = true c$.s = () => S.Check + '(' + stringify(check, true) + ')' attach(node.b, (check as Validate)) node.t = (S.check as ValType) } else if (S.object === typeof check) { let dstr = Object.prototype.toString.call(check) if (dstr.includes('RegExp')) { // Only a string can match. Coercing first (String(1).match(/^[0-9]+$/)) // let Check(/re/) accept values that a bare /re/ rejects outright. // The engine regexp is the shared subset's; the name is the original. const cre = engineRegexp(check as RegExp) let refn: any = (v: any) => (S.string === typeof v) && cre.test(v) defprop(refn, S.name, { value: String(check) }) defprop(refn, 'shape$', { value: { Check: true } }) refn.n = S.Check refn.a = [check] refn.s = () => S.Check + '(' + stringify(check, true) + ')' attach(node.b, refn) node.t = (S.check as ValType) } } // string is type name. // TODO: validate check is ValType else if (S.string === typeof check) { node.t = check as ValType } if (undefined !== shape) { const sn = nodize(shape) node.t = sn.t } return node } // Value cannot contain undeclared properties or elements. const Closed = function (this: any, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) // Makes one element array fixed. if (S.array === node.t && undefined !== node.c && 0 === node.n) { node.v = [node.c] } node.c = undefined return node } // Whether a bound is a finite number, a string that reads as one, a date, // or absent (the key-expression form). function boundArg(size: any): boolean { return undefined === size ? true : S.number === typeof size ? Number.isFinite(size) : S.string === typeof size ? ('' !== size.trim() && Number.isFinite(+size)) : size instanceof Date && !isNaN(size.getTime()) } // A builder that names something needs a name. function needsName(builder: string, name: any) { if (S.string !== typeof name || '' === name) { throw new Error('Shape: ' + builder + ' needs a name') } } // Define a named reference to this value. See Refer. const Define = function (this: any, inopts: any, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) let opts = S.object === typeof inopts ? inopts || {} : {} let name = S.string === typeof inopts ? inopts : opts.name needsName(S.Define, name) { const definer: any = function Define(_val: any, _update: Update, state: State) { let ref = state.ctx.ref = state.ctx.ref || {} ref[name] = state.node return true } definer.n = S.Define definer.a = [name] attach(node.b, definer) node.u.defines = true } return node } // TODO: copy option to copy value instead of node - need index of value in stack // Inject a referenced value. See Define. const Refer = function (this: any, inopts: any, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) let opts = S.object === typeof inopts ? inopts || {} : {} let name = S.string === typeof inopts ? inopts : opts.name // Fill should be false (the default) if used recursively, to prevent loops. let fill = !!opts.fill // Strict: a name with no Define is an error, rather than a Refer that // does nothing. let strict = !!opts.strict needsName(S.Refer, name) { const referrer: any = function Refer(val: any, update: Update, state: State) { if (undefined !== val || fill) { let ref = state.ctx.ref = state.ctx.ref || {} if (undefined !== ref[name]) { let node = { ...ref[name] } node.t = node.t || S.never update.node = node update.type = node.t } else if (strict) { update.err = 'Value "$VALUE" for property "$PATH" refers to "' + name + '", which is not defined.' return false } } return true } referrer.n = S.Refer referrer.a = [name] // Options the string form has no word for. referrer.o = (fill || strict) ? opts : undefined attach(node.b, referrer) } return node } // A writable copy of an object or array that cannot take new keys (see // State.thawParent), so the input stays as it was: an array by its // elements, an object by its own enumerable keys (a key named __proto__ // stays a key), keeping its prototype. function thaw(v: any): any { if (isarr(v)) { return v.slice() } const c = { ...v } const proto = Object.getPrototypeOf(v) return Object.prototype === proto ? c : Object.setPrototypeOf(c, proto) } // A key a Rename's claim took is the object's: a closed object does not // report it, and an open one's rest shape does not take it. The object // settled both before its keys were validated, so the claim undoes them: // the key leaves the closed error, which goes once no key is left, and the // rest entry queued for it after the declared keys checks nothing. function claimKey(s: State, cn: string) { const obj = s.parent for (let eI = 0; eI < s.err.length; eI++) { const e = s.err[eI] if (S.closed === e.why && e.value === obj && isarr(e.use.k)) { const k = e.use.k.filter((x: string) => x !== cn) if (0 === k.length) { s.err.splice(eI, 1) } else if (k.length < e.use.k.length) { const was = closedText(e.use.k) if (e.text.endsWith(was)) { e.text = e.text.substring(0, e.text.length - was.length) + closedText(k) } e.use = { ...e.use, k } } break } } const rest = s.ancestors[s.dI].c if (undefined !== rest) { for (let j = s.cI + 1; S.number !== typeof s.nodes[j]; j++) { if (s.keys[j] === cn && s.nodes[j] === rest && s.parents[j] === obj) { s.nodes[j] = (CLAIMED ??= nodize(Skip(Any()))) s.vals[j] = undefined break } } } } // What the rest entry of a claimed key becomes: absent and skipped, it // checks and writes nothing. let CLAIMED: Node | undefined = undefined // The clause a closed object's error ends with (see makeErrImpl). A claim's // object declares a key, so it names its keys as properties. function closedText(k: string[]): string { return 1 < k.length ? 'the properties "' + k.join(', ') + '" are not allowed.' : 'the property "' + k[0] + '" is not allowed.' } // TODO: no mutate is State.match // Rename a property. const Rename = function (this: any, inopts: any, shape?: Node | V): Node { let node = buildize(chainNode(this), shape) let opts = S.object === typeof inopts ? inopts || {} : {} let name = S.string === typeof inopts ? inopts : opts.name let keep = S.boolean === typeof opts.keep ? opts.keep : undefined // NOTE: Rename claims are experimental. let claim = isarr(opts.claim) ? opts.claim : [] needsName(S.Rename, name) { // A claim: while this key is absent, the value of the first claim key // the object holds, which this key's node then validates. A claim reads // the object as it stands, so a key an earlier claim removed is gone. // The claimed key is the object's (see claimKey), and is removed unless // kept. With no claim key there, the key is absent as it would be. let before: any = (val: any, update: Update, s: State) => { if (undefined === val && 0 < claim.length) { for (let cn of claim) { const cv = ownval(s.parent, cn) if (undefined !== cv) { update.val = cv if (!s.match) { setprop(s.parent, name, cv) } if (!keep) { delete s.parent[cn] } claimKey(s, cn) break } } } return true } defprop(before, S.name, { value: 'Rename:' + name }) before.n = S.Rename before.a = [name] // Options the string form has no word for. before.o = (undefined !== keep || 0 < claim.length) ? opts : undefined attach(node.b, before) let after: any = (val: any, update: Update, s: State) => { setprop(s.parent, name, val) if (!s.match && !keep && s.key !== name && // Arrays require explicit deletion as validation is based on index // and will be lost. !(isarr(s.parent) && false !== keep) ) { delete s.parent[s.key] update.done = true } return true } defprop(after, S.name, { value: 'Rename:' + name }) after.n = S.Rename attach(node.a, after) } return node } // Children must have a specified shape. const Child = function ( this: any, child?: C, shape?: Node | V ): Node { // Child provides implicit open object if no shape defined. let node = buildize(chainNode(this), shape) node.c = nodize(child) if (undefined === node.v) { node.t = 'object' node.v = {} node.f = {} } return node } const Rest = function ( this: any, child?: C, shape?: Node | V ): Node { // Chained on an array node with no shape, the node itself is the array, // so a tuple keeps its positions: [String, Number].Rest(Number). let self = this let chainedArray = undefined === shape && null != self && S.array === self.t let node = chainedArray ? buildize(self) : buildize(chainNode(self), shape || []) node.t = 'array' node.c = nodize(child) node.m = node.m || {} node.m.rest = true return node } type TypeRef = 'Number' | 'String' | 'Boolean' | 'Object' | 'Array' | 'Function' | 'Symbol' | 'Integer' | 'Date' | DateConstructor | StringConstructor | NumberConstructor | BooleanConstructor | ArrayConstructor | ObjectConstructor | FunctionConstructor | SymbolConstructor | Symbol | Record | null | undefined | typeof NaN // The result is the forced kind's; the spec's structure is discarded. const Type = function ( this: any, tref: K, shape?: any ): Node> { let tnat = nodize(TNAT[tref as string] || (S.Integer === tref ? Integer : tref)) let node = buildize(chainNode(this), shape) if (node !== tnat) { node.t = tnat.t node.r = tnat.r node.p = tnat.p node.v = tnat.v // Carry the fallback too. Omitting it made the string DSL disagree with // the builder API: expr('Optional(String)') dropped the '' default that // Optional(String) injects for an absent key. node.f = tnat.f } // Record that the kind came from the spec rather than being left open, so a // key expression's example value does not overwrite it. node.u.tset = true return (node as any) } // Size Builders: Min, Max, Above, Below, Len // ========================================== // True when the node declares a concrete type that this value does not have. // The structural check is about to report a type error, and a size bound on a // value of the wrong type is meaningless — `Min(2,String)` against 1 would // otherwise complain about the number 1 being below a minimum of 2, masking // the real problem. Mirrors the type tests in the validate loop. function typeWillFail(state: State): boolean { const n: any = state.node const t: string = n.t const val = state.val // An absent value has no type either, so a bound on a required value // stands aside for the missing-property error. if (S.any === t || S.list === t || S.check === t || S.never === t) return false if (S.object === t) return null === val || S.object !== state.valType || isarr(val) if (S.array === t) return !isarr(val) if (S.null === t) return null !== val if (S.instance === t) return !(n.u.i && val instanceof n.u.i) if (S.regexp === t) return S.string !== state.valType if (S.integer === t) return !Number.isInteger(val) if (S.date === t) return !(val instanceof Date) return t !== state.valType } function makeSizeBuilder( self: any, size: any, shape: any, name: string, valid: (vsize: number, size: number, val: any, update: Update, state: State) => boolean ) { let node = buildize(chainNode(self), shape) // A bound is a finite number, a string that reads as one, or a date; no // bound at all is the key-expression form ("a: Min()": 3), whose bound // is the example. Anything else is a mistake in the spec, not a value. if (!boundArg(size)) { throw new Error('Shape: ' + name + ' needs a number') } size = +size let validator: any = function(val: any, update: Update, state: State) { if (typeWillFail(state)) { return true } return valid(valueLen(val), size, val, update, state) } Object.defineProperty(validator, S.name, { value: name }) validator.n = name validator.a = [size] validator.s = () => name + '(' + size + ')' validator[Symbol.for('nodejs.util.inspect.custom')] = validator.s() validator.toJSON = () => validator.s() attach(node.b, validator) return node } // Specific a minimum value or length. const Min = function ( this: any, min: number | string, shape?: Node | V ): Node { return makeSizeBuilder(this, min, shape, S.Min, (vsize: number, min: number, val: any, update: Update, state: State) => { if (min <= vsize) { return true } state.checkargs = { min: 1 } let errmsgpart = isNumeric(val) ? '' : 'length ' update.err = makeErr(state, S.Value + ' ' + S.$VALUE + S.forprop + S.$PATH + ` must be a minimum ${errmsgpart}of ${min} (was ${vsize}).`) return false }) } // Specific a maximum value or length. const Max = function ( this: any, max: number | string, shape?: Node | V ): Node { return makeSizeBuilder(this, max, shape, S.Max, (vsize: number, max: number, val: any, update: Update, state: State) => { if (vsize <= max) { return true } let errmsgpart = isNumeric(val) ? '' : 'length ' update.err = makeErr(state, S.Value + ' ' + S.$VALUE + S.forprop + S.$PATH + ` must be a maximum ${errmsgpart}of ${max} (was ${vsize}).`) return false }) } // Specify a lower bound value or length. const Above = function ( this: any, above: number | string, shape?: Node | V ): Node { return makeSizeBuilder(this, above, shape, S.Above, (vsize: number, above: number, val: any, update: Update, state: State) => { if (above < vsize) { return true } let errmsgpart = isNumeric(val) ? 'be' : 'have length' update.err = makeErr(state, S.Value + ' ' + S.$VALUE + S.forprop + S.$PATH + ` must ${errmsgpart} above ${above} (was ${vsize}).`) return false }) } // Specify an upper bound value or length. const Below = function ( this: any, below: number | string, shape?: Node | V ): Node { return makeSizeBuilder(this, below, shape, S.Below, (vsize: number, below: number, val: any, update: Update, state: State) => { if (vsize < below) { return true } let errmsgpart = isNumeric(val) ? 'be' : 'have length' update.err = makeErr(state, S.Value + ' ' + S.$VALUE + S.forprop + S.$PATH + ` must ${errmsgpart} below ${below} (was ${vsize}).`) return false }) } // Value must have a specific length. const Len = function ( this: any, len: number, shape?: Node | V ): Node { if (!boundArg(len) || undefined === len || !Number.isInteger(+len) || +len < 0) { throw new Error('Shape: Len needs a whole number of zero or more') } return makeSizeBuilder(this, len, shape, S.Len, (vsize: number, len: number, val: any, update: Update, state: State) => { if (len === vsize) { return true } let errmsgpart = isNumeric(val) ? '' : ' in length' update.err = makeErr(state, S.Value + ' ' + S.$VALUE + S.forprop + S.$PATH + ` must be exactly ${len}${errmsgpart} (was ${vsize}).`) return false }) } // Make a Node chainable with Builder methods. // The node a builder chains onto: its `this` where that is a node, as in // node.Min(1). Called bare, or as a method of Shape or of the module // (Shape.Min, shape.Min), a builder chains onto nothing, so Shape.Min(1, // String) is Min(1, String). function chainNode(self: any): any { return null != self && self.$?.shape$ ? self : undefined } function buildize(self?: any, shape?: any): Node { // A builder may re-chain a retained node (see VGEN). VGEN++ // Detect chaining. If not chained, ignore `this` if it is the global context. let globalNode = null != self && (self.window === self || self.global === self) let node: Node if ((undefined === self || globalNode) && undefined !== shape) { node = nodize(shape) } else if (undefined !== self && !globalNode) { // Merge self into shape, retaining previous chained builders. if (undefined !== shape) { node = nodize(shape) let selfNode: Node = nodize(self) // TODO: need a more robust way to prevent Builders breaking each other. if (undefined === node.v && 'list' !== node.t) { node.v = selfNode.v node.t = selfNode.t } ;['f', 'r', 'p', 'c', 'e', 'z'].map((pn: string) => node[pn] = undefined !== selfNode[pn] ? selfNode[pn] : node[pn]) node.u = Object.assign({}, selfNode.u, node.u) node.m = Object.assign({}, selfNode.m, node.m) node.a = selfNode.a.concat(node.a) node.b = selfNode.b.concat(node.b) } else { node = nodize(self) } } else { node = nodize(undefined) } // Only add chainable Builders. // NOTE: All and Nof are not chainable. if ((node as any).Above) { return node // No need if already made chainable } // The same own, enumerable, writable properties that assignment gives, // defined in one step: assigning this many named properties one by one // takes a V8 object past its fast-property limit into dictionary mode, // and every read of the node's fields in the walk becomes a hash lookup. const chain: Record = { Above, After, Any, Before, Below, Catch, Check, Child, Closed, Coerce, Contains, DateTime, Default, Define, Describe, Empty, Email, Exact, Extend, Fault, Func, Ignore, Integer, Ip, Ipv4, Ipv6, Len, Max, Min, Never, Nullable, Omit, Open, Optional, Partial, Pick, Refer, Rename, Required, Rest, Skip, Transform, Type, Unique, Url, Uuid, String: () => Type.call(node, String), Number: () => Type.call(node, Number), Boolean: () => Type.call(node, Boolean), Object: () => Type.call(node, Object), Array: () => Type.call(node, Array), Function: () => Type.call(node, Function), Symbol: () => Type.call(node, Symbol), Date: () => Type.call(node, Date), } const descs: PropertyDescriptorMap = {} for (const name in chain) { descs[name] = { value: chain[name], writable: true, enumerable: true, configurable: true } } return Object.defineProperties(node, descs) } // External utility to make ErrDesc objects. function makeErr(state: State, text?: string, why?: string, user?: any) { return makeErrImpl( why || S.check, state, 4000, text, user, ) } // The characters JSON.stringify escapes in a string (a surrogate is taken // whether or not it is paired), and the quote the rendering removes. const JSON_ESCAPED_RE = /["\\\u0000-\u001f\ud800-\udfff]/ // The start of a builder's message: the value, then the path. const TEXT_PREFIX = S.Value + ' ' + S.$VALUE + S.forprop + S.$PATH // The parts of a verdict-only error nothing reads. const TERSE_ARR: any[] = Object.freeze([]) as any const TERSE_OBJ: any = Object.freeze({}) // Internal utility to make ErrDesc objects. function makeErrImpl( why: string, s: State, mark: number, text?: string, user?: any, fname?: string, ): ErrDesc { // A verdict-only call reads none of the path, the rendering or the text. if (s.terse) { return { key: s.key, type: s.node.t, node: s.node, value: s.val, path: '', pathArr: TERSE_ARR, why, check: s.check?.name || 'none', args: s.checkargs || TERSE_OBJ, mark, text: '', use: user || TERSE_OBJ, } } let err: ErrDesc = { key: s.key, type: s.node.t, node: s.node, value: s.val, path: pathstr(s), pathArr: patharr(s), why: why, check: s.check?.name || 'none', args: s.checkargs || {}, mark: mark, text: '', use: user || {}, } // TODO: truncate len, and ignore should be ShapeOptions // A primitive renders as its JSON with the quotes removed, as it would // through the replacer: a string with nothing JSON would escape and no // quote is that JSON, a finite number is its own text, and neither has a // quote to remove; anything else is rendered and stripped as before. const vt = typeof s.val let valstr = S.string === vt ? (JSON_ESCAPED_RE.test(s.val) ? JS(s.val).replace(/"/g, '') : s.val) : S.number === vt ? (s.val === s.val ? (Number.isFinite(s.val) ? '' + s.val : 'null') : 'NaN') : S.boolean === vt ? (s.val ? 'true' : 'false') : undefined === s.val ? S.undefined : stringify(s.val, false, false, { key: [/\$$/] }).replace(/"/g, '') if (111 < valstr.length) { valstr = truncate(valstr, 111) } text = text || s.node.z if (null == text || '' === text) { let valkind = valstr.startsWith('[') ? S.array : valstr.startsWith('{') ? S.object : (null == s.val || (S.number === typeof s.val && isNaN(s.val)) ? 'value' : (typeof s.val)) let propkind = (valstr.startsWith('[') || isarr(s.parents[s.pI])) ? 'index' : 'property' // The disallowed keys of a closed object are listed in one error, so the // clause about them pluralizes; the path before it names one value. let listkind = propkind let propkindverb = 'is' let propkey = user?.k propkey = isarr(propkey) ? (listkind = (1 < propkey.length ? (propkindverb = 'are', 'properties') : listkind), propkey.join(', ')) : propkey // A property that is not there is named, not rendered: nothing is // there to render, and "the property is missing" says what happened. const missing = S.required === why && undefined === s.val && 0 < err.path.length err.text = `Validation failed for ` + (0 < err.path.length ? `${propkind} "${err.path}"` + (missing ? ' ' : ' with ') : '') + (missing ? '' : `${valkind} "${valstr}" `) + `because ` + ( S.type === why ? ( S.instance === s.node.t ? `the ${valkind} is not an instance of ${s.node.u.n}` : `the ${valkind} is not of type ${S.regexp === s.node.t ? S.string : s.node.t}` ) : S.required === why ? ( missing ? `the ${'index' === propkind ? 'element' : 'property'} is missing` : '' === s.val ? 'an empty string is not allowed' : `the ${valkind} is required` ) : 'closed' === why ? `the ${listkind} "${propkey}" ${propkindverb} not allowed` : S.regexp === why ? 'the string did not match ' + s.node.v : S.never === why ? 'no value is allowed' : `check "${null == fname ? why : fname}" failed` ) + (err.use.thrown ? ' (threw: ' + err.use.thrown.message + ')' : '.') } else { // A builder's text starts with the value and the path, each once; when // neither they nor the rest of the text hold a '$', assembling it is // what the two replacements produce (a '$' anywhere could be another // placeholder or a replacement pattern, and takes them). const tail = text.startsWith(TEXT_PREFIX) ? text.substring(TEXT_PREFIX.length) : '$' err.text = (-1 === tail.indexOf('$') && -1 === valstr.indexOf('$') && -1 === err.path.indexOf('$')) ? 'Value "' + valstr + '" for property "' + err.path + '"' + tail : text .replace(/\$VALUE/g, valstr) .replace(/\$PATH/g, err.path) } return err } // Convert Node to JSON suitable for Shape.build. // The builder suffixes of a node's checks, skipping any that render as nothing. function bdesc(n: Node): string { return n.b .map((v: any) => v.s ? v.s(n) : '') .filter((d: string) => '' !== d) .map((d: string) => '.' + d) .join('') } function node2json(n: Node): any { let t = n.t const fixed: any = { number: S.Number, string: S.String, boolean: S.Boolean, integer: S.Integer, } if (fixed[t]) { let s = '' if (n.r) { s += fixed[t] } if ('' === s) { s = JSON.stringify(n.v) } s += bdesc(n) return s } else if (S.any === t) { let s = '' // Required is implicit with Exact. if (n.r && !n.b.some((v: any) => S.Exact === v.n)) { s += S.Required } if (S.any == n.c?.t) { s += ('' === s ? '' : '.') + S.Open } s += bdesc(n) if (s.startsWith('.')) { s = s.slice(1) } if ('' === s) { s = S.Any } return s } else if (S.check === t) { let s = '' // Required is implicit with Check s += bdesc(n) if (s.startsWith('.')) { s = s.slice(1) } return s } else if (S.object === t) { let o: any = {} for (let k in n.v) { o[k] = node2json(n.v[k]) } if (undefined !== n.c) { if (fixed[n.c.t]) { o.$$ = S.Child + '(' + fixed[n.c.t] + ')' } else if ('any' === n.c.t) { o.$$ = S.Open } else { o.$$ = S.Child + '($$child)' o.$$child = node2json(n.c) } } if (0 < n.b.length) { if (undefined === o.$$) { o.$$ = '' } o.$$ += bdesc(n) if (o.$$.startsWith('.')) { o.$$ = o.$$.slice(1) } } // naturalize, since `Child(Number)` implies `Child(Number,{})` if (o.$$ && 1 === Object.keys(o).length && o.$$.startsWith(S.Child)) { return o.$$ } return o } else if (S.list === t && n.u.discriminated) { return S.Discriminated + '(' + n.u.discriminated.tag + ',' + n.u.discriminated.tags.join(',') + ')' } else if (S.list === t) { let refs: any = {} let rI = 0 // A Nof's count leads its shapes. let list = (undefined === n.u.nof ? n.u.list : [n.u.nof.count, ...n.u.list]) .map((n: any) => S.number === typeof n ? n : node2json(n)) .map((n: any, _: any) => S.object === typeof n ? (refs[_ = '$$ref' + (rI++)] = n, _) : n) let s = (n.b[0].n || n.b[0].name) + '(' + list.join(',') + ')' return 0 === rI ? s : { $$: s, ...refs } } else if (S.array === t) { let a: any[] = [] if (undefined !== n.c) { a[0] = node2json(n.c) } else { a = Object.keys(n.v) .reduce((a: any[], i: any) => (a[+i] = n.v[i], a), []) .map((n: any) => node2json(n)) } return a } else if (S.regexp === t) { return n.v.toString() } else if (S.date === t) { let s = n.r ? S.Date : JSON.stringify(n.v) s += bdesc(n) return s } else if (S.never === t) { return S.Never + bdesc(n) } else if (S.null === t) { return 'null' + bdesc(n) } } // Declarative JSON // ================ // A shape written back as the JSON that build() reads: every string is an // expression of the string DSL, a key expression ("a: String") carries its // example as the value, and a "$$" key applies an expression to the object // that holds it, with "$$0", "$$1", ... beside it for the arguments an // expression cannot spell inline (an object or array shape). The result // reads back as the same shape: build(shape.json()).json() is shape.json(), // and the two accept and produce the same values. Nothing a function does // can be written down, so a shape carrying one (Check(fn), Before, After, // Transform, Key(fn)) throws, as does a builder option the DSL has no word // for (Rename's keep and claim, Refer's fill and strict) and a default that // is an object, an array or a date. const JSON_MARK = '$$' const JSON_TOKEN: { [t: string]: string } = { string: S.String, number: S.Number, integer: S.Integer, boolean: S.Boolean, } const JSON_FORMATS: { [n: string]: boolean } = { Email: true, Url: true, Uuid: true, DateTime: true, Ip: true, Ipv4: true, Ipv6: true, } // An argument of a call: inline expression text, or a spec that rides in a // sidecar ("$$0") beside the expression. type JsonArg = { x: string } | { j: any } type JsonCall = { n: string, a: JsonArg[] } function jsonFault(what: string): never { throw new Error('Shape: json cannot express ' + what) } // The inline text of a literal argument: a JSON scalar, or NaN. function jsonLiteral(v: any, what: string): string { const t = typeof v if (S.number === t) { return Number.isFinite(v) ? '' + v : isNaN(v) ? 'NaN' : jsonFault(what + ' ' + v) } if (S.string === t || S.boolean === t || null === v) { return JSON.stringify(v) } return jsonFault(what + ' ' + (undefined === v ? S.undefined : t)) } // A node whose children have been compiled. The walk compiles an object's // keys (a key expression under its name) the first time the shape runs; // a node that has not run yet (an array element, a list branch) runs here. function jsonNode(n: any): Node { n = nodize(n) if (S.object === n.t && null != n.v && n.k.length !== keys(n.v).length) { const d = n.d shapify(n).node() n.d = d } return n } function jsonNoAfters(afters: Validate[]) { for (const v of afters) { if (release !== v && S.Rename !== (v as any).n) { jsonFault('a custom after check' + (v.name ? ' ' + v.name : '')) } } } // The checks a node carries, as calls, in the order they run; a check named // in `skip` is the head of the expression and is left out. function jsonValidatorCalls(n: Node, skip?: any): JsonCall[] { const calls: JsonCall[] = [] for (const v of n.b) { if (skip !== v) { jsonValidatorCall(v, calls, n) } } jsonNoAfters(n.a) return calls } function jsonValidatorCall(v: any, calls: JsonCall[], n: Node) { const name: string | undefined = v.n const args: any[] = v.a || [] if (undefined === name) { jsonFault('a custom check' + (v.name ? ' ' + v.name : '')) } else if (undefined !== v.o) { jsonFault('the options of ' + name) } else if (S.Min === name || S.Max === name || S.Above === name || S.Below === name || S.Len === name) { calls.push({ n: name, a: [{ x: jsonLiteral(args[0], 'the bound') }] }) } else if (S.Catch === name || S.Ignore === name) { // The taken checks run inside, so they read ahead of the taker. for (const iv of v.inner.b) { jsonValidatorCall(iv, calls, n) } jsonNoAfters(v.inner.a) calls.push({ n: name, a: S.Catch === name ? [{ x: jsonLiteral(args[0], 'the fallback') }] : [] }) // Ignore makes the node optional and skipped; a builder after it that // required the node, or gave it a default to insert, follows it. if (S.Ignore === name && n.r) { calls.push({ n: S.Required, a: [] }) } else if (S.Ignore === name && !n.p && undefined !== n.f) { calls.push({ n: S.Default, a: [{ x: jsonLiteral(n.f, 'the default') }] }) } } else if (S.Coerce === name || JSON_FORMATS[name]) { calls.push({ n: name, a: [] }) } else if (S.Define === name || S.Refer === name || S.Rename === name) { calls.push({ n: name, a: [{ x: JSON.stringify(args[0]) }] }) } else if (S.Key === name) { calls.push({ n: name, a: args.map((a: any) => ({ x: jsonLiteral(a, 'the Key argument') })) }) } else if (S.Check === name) { calls.push({ n: name, a: [{ x: String(args[0]) }] }) } else if (S.Exact === name) { calls.push({ n: name, a: args.map((a: any) => ({ x: jsonLiteral(a, 'the Exact value') })) }) } else if (S.Contains === name) { calls.push({ n: name, a: [S.number === typeof v.c ? { x: '' + v.c } : jsonArg(v.c), jsonArg(v.u.shape)] }) } else if (S.Unique === name) { calls.push({ n: name, a: [] }) } else if (S.All === name || S.Nof === name || S.When === name || S.Discriminated === name) { // The list itself is the head of the expression. } else { jsonFault(name) } } // Whether the node is required or skipped, as calls, for a head that says // neither: Required where the head is optional by itself, Optional or Skip // where it is required. Ignore says optional and skipped, and what a later // builder changed of that follows it (see jsonValidatorCall). function jsonRequiredCalls(n: Node, headRequired: boolean): JsonCall[] { const calls: JsonCall[] = [] if (jsonIgnored(n)) { return calls } if (n.r && !headRequired) { calls.push({ n: S.Required, a: [] }) } else if (!n.r) { if (n.p) { calls.push({ n: S.Skip, a: [] }) } else if (headRequired) { calls.push({ n: S.Optional, a: [] }) } } return calls } // Whether an Ignore, or a Catch that took one, is among the node's checks. function jsonIgnored(n: Node): boolean { const has = (b: any[]): boolean => b.some((v: any) => S.Ignore === v.n || (S.Catch === v.n && has(v.inner.b))) return has(n.b) } // The flags of the node, as calls. An empty literal head says Empty by // itself. function jsonFlagCalls(n: Node, literalHead: boolean): JsonCall[] { const calls: JsonCall[] = [] if (S.string === n.t && n.u.empty && !(literalHead && '' === n.f)) { calls.push({ n: S.Empty, a: [] }) } if (n.u.nullable) { calls.push({ n: S.Nullable, a: [] }) } return calls } function jsonTailCalls(n: Node): JsonCall[] { const calls: JsonCall[] = [] if (undefined !== n.m?.description) { calls.push({ n: S.Describe, a: [{ x: JSON.stringify(n.m.description) }] }) } if (undefined !== n.z) { calls.push({ n: S.Fault, a: [{ x: JSON.stringify(n.z) }] }) } return calls } // The value form of a node as an argument: inline when it is a string. function jsonArg(n: any): JsonArg { const j = nodeJson(n) return S.string === typeof j ? { x: j } : { j } } // Whether an open object's child shape is the plain Any of Open. function jsonIsOpen(c: any): boolean { return S.any === c.t && !c.r && 0 === c.b.length && 0 === c.a.length && undefined === c.c && undefined === c.f } // The text of a call, its sidecar arguments registered in refs. A shape is // the call's last argument. function jsonCallText(c: JsonCall, refs: any, shape?: string): string { const parts: string[] = [] for (const a of c.a) { if ('x' in a) { parts.push(a.x) } else { const name = JSON_MARK + keys(refs).length refs[name] = a.j parts.push(name) } } if (undefined !== shape) { parts.push(shape) } return c.n + (0 < parts.length ? '(' + parts.join(',') + ')' : '') } // A chain of calls after a head, or (with no head) as a bare chain; null // with neither. function jsonChainText(head: string | null, calls: JsonCall[], refs: any): string | null { let out = head for (const c of calls) { const text = jsonCallText(c, refs) out = null === out ? text : out + '.' + text } return out } // The calls around a shape that is not a node by itself (a literal, a // regexp, a sidecar): the first takes it, the rest chain: Min(2,0).Skip. function jsonWrapText(calls: JsonCall[], shape: string, refs: any): string { let out = jsonCallText(calls[0], refs, shape) for (let i = 1; i < calls.length; i++) { out += '.' + jsonCallText(calls[i], refs) } return out } // A carrier object: the expression under "$$", the sidecars beside it. function jsonCarrier(text: string, refs: any): any { return { [JSON_MARK]: text, ...refs } } // The text alone where it needs no sidecars, a carrier where it does (a // shape argument of Contains, say). function jsonCarried(text: string, refs: any): any { return 0 === keys(refs).length ? text : jsonCarrier(text, refs) } // A literal, held by the call that says whether it is required. function jsonLiteralHead(n: Node, lit: string): string { return (n.p ? S.Skip : n.r ? S.Required : S.Optional) + '(' + lit + ')' } // The validators that make the node the head of its expression, so that // the node has no key form: Key makes it, and Exact reads every argument // as a value. function jsonHeadValidator(n: Node): any { return n.b.find((v: any) => S.Key === v.n || S.Exact === v.n) } // The parts of a scalar: the head (a type token, a held literal, or Key), // the token of the key form (null where the head is not one), the example // of the key form, and the calls after the head. function jsonScalar(n: Node): { head: string, token: string | null, example: any, calls: JsonCall[] } { const z = EMPTY_VAL[n.t] const zero = undefined === n.f || z === n.f const other = jsonOtherKind(n) const example = zero || other ? z : n.f const hv = jsonHeadValidator(n) let head: string let token: string | null = null let calls: JsonCall[] if (undefined !== hv && S.Key === hv.n) { const kc: JsonCall[] = [] jsonValidatorCall(hv, kc, n) head = jsonCallText(kc[0], {}) calls = jsonRequiredCalls(n, false).concat(jsonFlagCalls(n, false)) } // A default of another kind would read as a literal of its own: the type // token holds the kind, and Default the value. else if (!n.r && other) { head = JSON_TOKEN[n.t] const dflt: JsonCall[] = [{ n: S.Default, a: [{ x: jsonLiteral(n.f, 'the default') }] }] calls = dflt.concat(n.p && !jsonIgnored(n) ? [{ n: S.Skip, a: [] }] : [], jsonFlagCalls(n, false)) } // A literal stands for its own kind, but not for integer, and an empty // string literal allows the empty string; a required zero is the type // token, and so is a required node whose default, which it never // inserts, is of another kind. else if ((n.r && (zero || other)) || S.integer === n.t || (S.string === n.t && !n.u.empty && '' === n.f)) { token = JSON_TOKEN[n.t] head = token calls = jsonRequiredCalls(n, true).concat(jsonFlagCalls(n, false)) } else { head = jsonLiteralHead(n, jsonLiteral(example, 'the default')) calls = jsonFlagCalls(n, true) } calls = calls.concat( jsonValidatorCalls(n, undefined !== hv && S.Key === hv.n ? hv : undefined), jsonTailCalls(n)) return { head, token, example, calls } } // Whether a scalar's default is of another kind than the node, which its // literal cannot say: String.Default(5). function jsonOtherKind(n: Node): boolean { const own = S.integer === n.t ? S.number : n.t return undefined !== n.f && (null === n.f || own !== typeof n.f) } // The key form of a property, "name: chain" with its example, or null where // the node has no key form (a list, a regexp, a shape needing sidecars, a // default the example cannot be). function jsonKeyForm(n: Node): { chain: string, example: any } | null { const t = n.t // A composition has no key form, whatever kind a type token gave it. if (undefined !== jsonHeadValidator(n) || undefined !== n.u.list || (undefined !== JSON_TOKEN[t] && !n.r && jsonOtherKind(n))) { return null } if (undefined !== JSON_TOKEN[t]) { const sc = jsonScalar(n) // With a literal head, the call that held the literal starts the chain. const head = null !== sc.token ? sc.token : n.p ? S.Skip : n.r ? S.Required : null const refs: any = {} const chain = jsonChainText(head, sc.calls, refs) || '' return 0 < keys(refs).length ? null : { chain, example: sc.example } } if (S.object === t) { const o = jsonObject(n) if (0 < keys(o.refs).length) { return null } return { chain: o.chain || '', example: o.children } } if (S.array === t) { const a = jsonArray(n) if (0 < keys(a.refs).length || a.closed) { return null } return { chain: a.chain || '', example: a.elements } } return null } // The children of an object in key form, and the chain that applies to // the object (null when there is none). function jsonObject(n: Node): { children: any, chain: string | null, refs: any } { const children: any = {} const refs: any = {} const kk = 0 < n.k.length ? n.k : keys(n.v) // A type token brings the empty object as its default, which the walk // makes for an absent object anyway; any other default is one the // expression form cannot spell. if (undefined !== n.f && 0 < keys(n.f).length) { jsonFault('an object default') } for (const k of kk) { if (k.startsWith(JSON_MARK)) { jsonFault('the property name ' + JSON.stringify(k)) } const c = jsonNode(n.v[k]) const kf = jsonKeyForm(c) const quoted = /[\s"\\]/.test(k) || '' === k || isKeyExpr(k) if (null != kf && '' !== kf.chain) { children[(quoted ? JSON.stringify(k) : k) + ': ' + kf.chain] = kf.example } else if (null != kf && isKeyExpr(k)) { // A name that reads as a key expression is quoted, and so needs a // chain; Optional says nothing about a node that is optional already. children[JSON.stringify(k) + ': ' + S.Optional] = kf.example } else if (isKeyExpr(k)) { jsonFault('the property name ' + JSON.stringify(k) + ' of a value with no key form') } else { setprop(children, k, nodeJson(c)) } } const calls = jsonRequiredCalls(n, false).concat(jsonFlagCalls(n, false), jsonValidatorCalls(n)) if (undefined === n.c) { if (0 === kk.length) { calls.push({ n: S.Closed, a: [] }) } } else if (jsonIsOpen(n.c)) { if (0 < kk.length) { calls.push({ n: S.Open, a: [] }) } } else { calls.push({ n: S.Child, a: [jsonArg(n.c)] }) } calls.push(...jsonTailCalls(n)) const chain = 0 === calls.length ? null : jsonChainText(null, calls, refs) return { children, chain, refs } } // The elements of an array in value form: the fixed positions, or the one // element shape. A single fixed position is closed, which [X] cannot say. function jsonArray(n: Node): { elements: any[], calls: JsonCall[], chain: string | null, refs: any, closed: boolean } { const refs: any = {} let elements: any[] let closed = false if (undefined !== n.f && 0 < n.f.length) { jsonFault('an array default') } const positions = null == n.v ? [] : keys(n.v).map((k: string) => n.v[k]) if (0 < positions.length) { elements = positions.map((p: any) => nodeJson(p)) closed = 1 === positions.length } else if (undefined !== n.c && !n.m?.rest) { elements = [nodeJson(n.c)] } else { elements = [] } const calls = jsonRequiredCalls(n, false).concat(jsonFlagCalls(n, false), jsonValidatorCalls(n)) if (n.m?.rest) { calls.push({ n: S.Rest, a: [jsonArg(n.c)] }) } calls.push(...jsonTailCalls(n)) const chain = 0 === calls.length ? null : jsonChainText(null, calls, refs) return { elements, calls, chain, refs, closed } } // A node whose head is a call that makes it (Key, Exact on an object or an // array): the head, then the rest of the chain. function jsonHeaded(n: Node, hv: any, kind: string): any { if (S.Exact === hv.n) { jsonFault('Exact on ' + kind) } const kc: JsonCall[] = [] jsonValidatorCall(hv, kc, n) const calls = jsonRequiredCalls(n, false) .concat(jsonFlagCalls(n, false), jsonValidatorCalls(n, hv), jsonTailCalls(n)) const refs: any = {} return jsonCarried(jsonChainText(jsonCallText(kc[0], refs), calls, refs) as string, refs) } // The composition that heads a list node: its own check, or one that a // Catch, Transform or Ignore took inside with the node's other checks. function jsonListHead(b: Validate[]): string { const head: any = b.find((v: any) => S.All === v.n || S.Nof === v.n || S.When === v.n) const taker: any = b.find((v: any) => undefined !== v.inner) return undefined !== head ? head.n : jsonListHead(taker.inner.b) } // The call that heads a list node: its composition, or Discriminated. function jsonListCall(n: Node): JsonCall { return n.u.discriminated ? { n: S.Discriminated, a: [ { x: JSON.stringify(n.u.discriminated.tag) }, { j: jsonBranches(n) }, ] } : { n: jsonListHead(n.b), // A Nof's count leads its shapes: a number inline, a shape as its value. a: (undefined === n.u.nof ? [] : [S.number === typeof n.u.nof.count ? { x: '' + n.u.nof.count } : jsonArg(n.u.nof.count)]) .concat(n.u.list.map((b: any) => jsonArg(b))) } } // The type tokens that give a composition a kind of its own; a Check gives // it one too, and is among its checks. const JSON_TYPED: { [t: string]: string } = { string: S.String, number: S.Number, integer: S.Integer, boolean: S.Boolean, object: S.Object, array: S.Array, date: S.Date, function: S.Function, } // A composition that a type token or a Check gave a kind of its own: the // composition heads it, and its checks, the type, its flags and whether it // is required follow, in that order, as both a type token and a Check say // required: All(Any.Min(2)).Check(/^a/).Optional reads back as it was. function jsonTyped(n: Node): any { const t = n.t if (S.check !== t && undefined === JSON_TYPED[t]) { jsonFault('a composition of kind ' + t) } // The type token brings its own default; any other is one the // expression cannot spell. if (JSON.stringify(n.f) !== JSON.stringify(EMPTY_VAL[t])) { jsonFault('the default of a composition given a kind') } const refs: any = {} const token: JsonCall[] = S.check === t ? [] : [{ n: JSON_TYPED[t], a: [] }] // A container's own shape follows its token: Open, or the shape of its // children, or of its rest. const shape: JsonCall[] = (S.object !== t && S.array !== t) || undefined === n.c ? [] : S.object === t && jsonIsOpen(n.c) ? [{ n: S.Open, a: [] }] : [{ n: n.m?.rest ? S.Rest : S.Child, a: [jsonArg(n.c)] }] // A type token says required and not skipped, after an Ignore too, so // whether the node is either follows it. const required: JsonCall[] = 0 === token.length ? jsonRequiredCalls(n, true) : n.r ? [] : [{ n: n.p ? S.Skip : S.Optional, a: [] }] const calls = jsonValidatorCalls(n) .concat(token, shape, jsonFlagCalls(n, false), required, jsonTailCalls(n)) return jsonCarried(jsonChainText(jsonCallText(jsonListCall(n), refs), calls, refs) as string, refs) } // The value form of a node: the JSON that reads back as it. function nodeJson(n: Node): any { n = jsonNode(n) const t = n.t // A composition that a type token or a Check gave a kind of its own. if (S.list !== t && undefined !== n.u.list && !n.u.discriminated) { return jsonTyped(n) } if (undefined !== JSON_TOKEN[t]) { const sc = jsonScalar(n) // A literal with nothing after it is the JSON value; a string is quoted, // as a bare one would read as an expression. if (null === sc.token && 0 === sc.calls.length && undefined === jsonHeadValidator(n) && !n.r && !n.p) { return S.string === t ? JSON.stringify(sc.example) : sc.example } const refs: any = {} return jsonCarried(jsonChainText(sc.head, sc.calls, refs) as string, refs) } const hv = jsonHeadValidator(n) if (S.object === t) { if (undefined !== hv) { return jsonHeaded(n, hv, 'an object') } const o = jsonObject(n) if (null !== o.chain) { o.children[JSON_MARK] = o.chain Object.assign(o.children, o.refs) } return o.children } if (S.array === t) { if (undefined !== hv) { return jsonHeaded(n, hv, 'an array') } const a = jsonArray(n) if (null === a.chain && !a.closed) { return a.elements } // The calls take the array as their shape; a single position is closed // first, as a one element array is an element shape. const refs: any = {} const name = JSON_MARK + '0' refs[name] = a.elements const shape = a.closed ? S.Closed + '(' + name + ')' : name return jsonCarrier(0 === a.calls.length ? shape : jsonWrapText(a.calls, shape, refs), refs) } if (S.list === t) { const refs: any = {} // A default the node injects is a Default around the list, which makes // it optional too, unless an Ignore says it (see jsonValidatorCall). const dflt = undefined !== n.f && !n.r && !n.p && !jsonIgnored(n) const headText = jsonCallText(jsonListCall(n), refs) const calls = (dflt ? [] : jsonRequiredCalls(n, true)) .concat(jsonFlagCalls(n, false), jsonValidatorCalls(n), jsonTailCalls(n)) const text = jsonChainText(dflt ? S.Default + '(' + jsonLiteral(n.f, 'the default') + ',' + headText + ')' : headText, calls, refs) as string return 0 === keys(refs).length ? text : jsonCarrier(text, refs) } if (S.regexp === t) { // A regexp is not a node until a builder takes it, so the calls wrap it. const calls = jsonRequiredCalls(n, true) .concat(jsonFlagCalls(n, false), jsonValidatorCalls(n), jsonTailCalls(n)) const re = String(n.v) const refs: any = {} return 0 === calls.length ? re : jsonCarried(jsonWrapText(calls, re, refs), refs) } // From here on, the sidecars of any call that takes a shape. const refs: any = {} if (S.nan === t) { const calls = jsonFlagCalls(n, true).concat(jsonValidatorCalls(n), jsonTailCalls(n)) return 0 === calls.length && !n.r && !n.p ? 'NaN' : jsonCarried(jsonChainText(jsonLiteralHead(n, 'NaN'), calls, refs) as string, refs) } // The rest are a call that names the kind, then the chain. let head: string let headRequired = true let headSkipped = false if (S.any === t) { head = n.r ? S.Required : S.Any headRequired = n.r // A required value never takes its default, so a required Any has none // to write, and Required(5) would read as a required number. if (undefined !== n.f && !n.r) { head += '(' + jsonLiteral(n.f, 'the default') + ')' } if (undefined !== n.c && jsonIsOpen(n.c)) { head += '.' + S.Open } } else if (S.never === t) { head = S.Never } else if (S.null === t) { // A default it inserts that is not null, which no null literal says. if (!n.r && !n.p && undefined !== n.f && null !== n.f) { jsonFault('the default of a null') } if (!n.r && !n.p && 0 === n.b.length && 0 === n.a.length && !n.u.nullable && undefined === n.z && undefined === n.m?.description) { return null } head = n.r ? S.Required + '(null)' : n.p ? S.Skip + '(null)' : 'null' headRequired = n.r headSkipped = n.p } else if (S.undefined === t) { head = (n.r ? S.Required : S.Optional) + '(undefined)' headRequired = n.r } else if (S.date === t || S.function === t) { if (undefined !== n.f) { jsonFault('a ' + t + ' default') } head = S.date === t ? S.Date : S.Function } else if (S.check === t) { // Check is the first call, and says required. const first: any = n.b[0] if (0 === n.b.length || S.Check !== first.n) { jsonFault('a check function') } const kc: JsonCall[] = [] jsonValidatorCall(first, kc, n) head = jsonCallText(kc[0], refs) const calls = jsonRequiredCalls(n, true) .concat(jsonFlagCalls(n, false), jsonValidatorCalls(n, first), jsonTailCalls(n)) return jsonCarried(jsonChainText(head, calls, refs) as string, refs) } else { jsonFault('a ' + t + ' value') } const rp = headSkipped ? [] : jsonRequiredCalls(n, headRequired) const calls = jsonFlagCalls(n, false).concat(jsonValidatorCalls(n), jsonTailCalls(n)) if (headRequired && 0 < rp.length && S.any !== t) { // Optional(Date), Skip(Never): the call holds the token. head = rp[0].n + '(' + head + ')' return jsonCarried(jsonChainText(head, calls, refs) as string, refs) } const text = jsonChainText(head, rp.concat(calls), refs) as string if (S.any === t && n.r && 0 < keys(refs).length) { // A carrier that starts with a bare Required is a required object, as // Required.Child($$0) is, so a required Any names its kind first. const anyRefs: any = {} return jsonCarrier(jsonChainText(S.Any + head.substring(S.Required.length), [{ n: S.Required, a: [] } as JsonCall].concat(calls), anyRefs) as string, anyRefs) } return jsonCarried(text, refs) } // The branches of a Discriminated union by tag value. A branch's tag // property is what the union added, unless the author declared it. function jsonBranches(n: Node): any { const { tag, tags } = n.u.discriminated const out: any = {} tags.forEach((t: string, i: number) => { const b = jsonNode(n.u.list[i]) const j = nodeJson(b) const tn = S.object === b.t && hasOwn(b.v, tag) ? b.v[tag] : undefined if (undefined !== tn && S.string === tn.t && !tn.r && t === tn.f && 0 === tn.b.length && 0 === tn.a.length && undefined === tn.z) { delete j[tag] } setprop(out, t, j) }) return out } function stringify( src: any, dequote?: boolean, expand?: boolean, ignore?: { key?: (string | RegExp)[], val?: (string | RegExp)[] }, replacer?: any, ) { let str: string const use_node2str = !expand && !!(src && src.$) && (SHAPE$ === src.$.shape$ || true === (src.$ as any).shape$) if (use_node2str) { src = JSON.stringify(node2json(src)) if (dequote) { src = 'string' === typeof src ? src.replace(/\\/g, '').replace(/"/g, '') : '' } return src } try { str = JS(src, (key: any, val: any) => { if (replacer) { val = replacer(key, val) } if ( ignore?.key?.reduce((a, n) => (a ? a : n === key || key.match(n)), false) || ignore?.val?.reduce((a, n) => (a ? a : n === val || key.match(n)), false) ) { val = undefined } else if ( null != val && S.object === typeof (val) && ctorOf(val) && S.Object !== ctorOf(val).name && S.Array !== ctorOf(val).name ) { let strdesc = toString.call(val) if ('[object RegExp]' === strdesc) { val = val.toString() } else { val = S.function === typeof val.toString ? val.toString() : ctorOf(val).name } } else if (!expand && SHAPE$ === val?.$?.shape$) { if ('number' === val.t || 'string' === val.t || 'boolean' === val.t) { val = val.v } else { val = node2json(val) val = JSON.stringify(val) if (dequote) { val = 'string' === typeof val ? val.replace(/\\/g, '').replace(/"/g, '') : '' } } } else if (S.function === typeof (val)) { if (S.function === typeof ((shapify as any)[val.name]) && isNaN(+key)) { val = undefined } else if (ignore?.val?.reduce((a, n) => (a ? a : n === val.name || val.name.match(n)), false)) { val = undefined } else if (null != val.name && '' !== val.name) { val = val.name } else { val = truncate(val.toString().replace(/[ \t\r\n]+/g, ' ')) } } else if ('bigint' === typeof (val)) { val = String(val.toString()) } else if (Number.isNaN(val)) { val = 'NaN' } else if (true !== expand && (true === val?.$?.shape$ || SHAPE$ === val?.$?.shape$)) { val = JSON.stringify(node2json(val)) } return val }) str = String(str) } catch (e: any) { str = JS(String(src)) } if (true === dequote) { str = str.replace(/^"/, '').replace(/"$/, '') } return str } // Deep, so that a Catch fallback holding an object is never shared between // two results; anything that is not a plain object or array is kept as-is. // A cycle, or an object reached twice, is reproduced rather than followed. function clone(x: any, seen?: Map): any { if (null == x || S.object !== typeof x) return x if (x instanceof RegExp) return new RegExp(x.source, x.flags) if (x instanceof Date) return new Date(x.getTime()) if (!isarr(x)) { const proto = Object.getPrototypeOf(x) if (Object.prototype !== proto && null !== proto) return x } seen = seen || new Map() if (seen.has(x)) return seen.get(x) if (isarr(x)) { const out: any[] = [] seen.set(x, out) for (let i = 0; i < x.length; i++) { out.push(clone(x[i], seen)) } return out } const out: any = {} seen.set(x, out) for (const k of keys(x)) { defprop(out, k, { value: clone(x[k], seen), enumerable: true, writable: true, configurable: true }) } return out } // JSON Schema // =========== // Export a node as a JSON Schema (draft 2020-12) describing the values it // accepts. Every kind, bound, format, literal set, composition, reference and // default has a rendering; a check that is a function, and the builders that // only change what comes out (Coerce, Catch, Transform, Rename, Key), have // none. The Go port renders the same schema for the same shape, and the // differential harness compares the two. const JSON_SCHEMA_DRAFT = 'https://json-schema.org/draft/2020-12/schema' function jsonSchema(top: Node): any { const defs: any = {} const body = nodeSchema(top, defs) const out: any = { $schema: JSON_SCHEMA_DRAFT, ...body } if (0 < keys(defs).length) { out.$defs = defs } return out } const JSON_SCHEMA_TYPE: any = { string: 'string', number: 'number', nan: 'number', integer: 'integer', boolean: 'boolean', null: 'null', object: 'object', array: 'array', date: 'string', regexp: 'string', } const JSON_SCHEMA_FORMAT: any = { Email: 'email', Url: 'uri', Uuid: 'uuid', DateTime: 'date-time', Ipv4: 'ipv4', Ipv6: 'ipv6', } function nodeSchema(raw: any, defs: any): any { const n = nodize(raw) const s: any = {} // A reference stands for the named shape, which is rendered where it is // defined. const referrer: any = n.b.find((v: any) => S.Refer === v.n) if (undefined !== referrer) { s.$ref = '#/$defs/' + referrer.a[0] return describe(n, s) } if (undefined !== JSON_SCHEMA_TYPE[n.t]) { s.type = JSON_SCHEMA_TYPE[n.t] } if (S.string === n.t && !n.u.empty) { s.minLength = 1 } else if (S.date === n.t) { s.format = 'date-time' } else if (S.regexp === n.t) { s.pattern = n.v.source } else if (S.never === n.t) { s.not = {} } else if (S.object === n.t) { objectSchema(n, s, defs) } else if (S.array === n.t) { arraySchema(n, s, defs) } // A composition says what its branches say, whatever kind a type token // or a Check gave it, beside what the kind says: a keyword both say holds // as an allOf of its own, so that neither replaces the other. A nullable // one admits null whatever the branches make of it. if (S.list === n.t && n.u.nullable) { const ls: any = {} listSchema(n, ls, defs) s.anyOf = [{ type: S.null }, ls] } else if (S.list === n.t) { listSchema(n, s, defs) } else if (undefined !== n.u.list && !n.u.discriminated) { const ls: any = {} listSchema(n, ls, defs) const part: any = n.u.nullable ? { anyOf: [{ type: S.null }, ls] } : ls // In key order, so that every language says them in one order. for (const k of keys(part).sort()) { if (undefined === s[k]) { s[k] = part[k] } else { s.allOf = (s.allOf || []).concat({ [k]: part[k] }) } } } checkSchema(n, s, defs) if (n.u.nullable && undefined !== s.type) { s.type = (isarr(s.type) ? s.type : [s.type]).concat('null') } // A tuple position the shape requires must be there, and so must every // one before it. if (S.array === n.t) { const need = 1 + keys(n.v).reduce((m: number, k: string) => !isNaN(+k) && nodize(n.v[k]).r ? Math.max(m, +k) : m, -1) if (need > (s.minItems || 0)) { s.minItems = need } } if (!n.r && !n.p && undefined !== n.f && S.function !== typeof n.f && !isNaN2(n.f)) { s.default = n.f } describe(n, s) const definer: any = n.b.find((v: any) => S.Define === v.n) if (undefined !== definer) { defs[definer.a[0]] = s } return s } function isNaN2(v: any): boolean { return S.number === typeof v && isNaN(v) } function describe(n: Node, s: any): any { if (S.string === typeof n.m?.description) { s.description = n.m.description } return s } function objectSchema(n: Node, s: any, defs: any) { const entries = objectEntries(n) const props: any = {} const required: string[] = [] for (const e of entries) { const cn = nodize(e.child) ownprop(props, e.key, nodeSchema(cn, defs)) if (cn.r) { required.push(e.key) } } if (0 < entries.length) { s.properties = props } if (0 < required.length) { s.required = required.sort() } if (undefined === n.c) { s.additionalProperties = false } else if (!isAnySchema(n.c)) { s.additionalProperties = nodeSchema(n.c, defs) } } // A child shape of Any says nothing, unless it stands for a reference. function isAnySchema(child: any): boolean { const cn = nodize(child) return S.any === cn.t && undefined === cn.b.find((v: any) => S.Refer === v.n) } function arraySchema(n: Node, s: any, defs: any) { const fixed = keys(n.v) .filter((k: string) => !isNaN(+k)) .sort((a: string, b: string) => +a - +b) .map((k: string) => nodeSchema(n.v[k], defs)) // An element shape of Any says nothing, as an Any rest shape does not for // an object. const child = undefined === n.c || isAnySchema(n.c) ? undefined : n.c if (0 < fixed.length) { s.prefixItems = fixed // Nothing may follow a closed tuple; an Any rest says nothing. if (undefined === n.c) { s.items = false } else if (undefined !== child) { s.items = nodeSchema(child, defs) } } else if (undefined !== child) { s.items = nodeSchema(child, defs) } } function listSchema(n: Node, s: any, defs: any) { const branches = n.u.list.map((bn: any) => nodeSchema(bn, defs)) const disc = n.u.discriminated if (undefined !== disc) { for (let bI = 0; bI < branches.length; bI++) { const b = branches[bI] b.properties = b.properties || {} b.properties[disc.tag] = { type: S.string, const: disc.tags[bI] } b.required = (b.required || []).filter((k: string) => k !== disc.tag).concat(disc.tag).sort() } s.oneOf = branches } else if (undefined !== n.u.nof) { if (!kindsSchema(nofKindsNow(n), branches, s)) { nofSchema(n.u.nof.ok, branches, s) } } else if (n.u.when) { // A shape that passes everything says nothing. s.if = branches[0] if (0 < keys(branches[1]).length) { s.then = branches[1] } if (0 < keys(branches[2]).length) { s.else = branches[2] } } else { s.allOf = branches } } // Exactly one of a shape for every JSON kind is a schema with no type: the // keywords of each kind side by side. A shape that says more than its // kind's keywords can say is counted, as oneOf. function kindsSchema(kinds: string[] | undefined, branches: any[], s: any): boolean { if (undefined === kinds || !JSON_KINDS.every((k: string) => kinds.includes(k)) || !branches.every((b: any) => JSON_KINDS.includes(b.type) && keys(b).every((k: string) => 'type' === k || (JSON_SCHEMA_KIND_KEYWORDS[b.type] || []).includes(k)))) { return false } for (const b of branches) { for (const k of keys(b)) { if ('type' !== k) { s[k] = b[k] } } } return true } const JSON_KINDS = ['null', 'boolean', 'number', 'string', 'object', 'array'] // A count of the shapes, as the keywords that count: none of them is not, // exactly one oneOf, every one allOf. JSON Schema has no keyword for any // other count, so it is bounded by what it rules out: anyOf when the count // is never none, not allOf when it is never every one. That bound is exact // for at least one, not every one, and both together. function nofSchema(ok: boolean[], branches: any[], s: any) { const n = branches.length const only = (c: number) => ok.every((v: boolean, i: number) => v === (i === c)) if (ok.every((v: boolean) => v)) { return } if (!ok.includes(true)) { s.not = {} } else if (only(0)) { s.not = 1 === n ? branches[0] : { anyOf: branches } } else if (only(1)) { s.oneOf = branches } else if (only(n)) { s.allOf = branches } else { if (!ok[0]) { s.anyOf = branches } if (!ok[n]) { s.not = { allOf: branches } } } } // The bounds a size builder puts on a value: the number families for a // number, the length families for a string, array or object, and every // family for a node that has not said. const SIZE_FAMILIES: any = { number: ['minimum'], nan: ['minimum'], integer: ['minimum'], string: ['minLength'], array: ['minItems'], object: ['minProperties'], } const SIZE_MAX: any = { minimum: 'maximum', minLength: 'maxLength', minItems: 'maxItems', minProperties: 'maxProperties', } function checkSchema(n: Node, s: any, defs: any) { const families = SIZE_FAMILIES[n.t] || keys(SIZE_MAX) const vs: any[] = n.b.concat(n.a) for (let vI = 0; vI < vs.length; vI++) { const v = vs[vI] // Catch, Transform and Ignore take the node's checks inside. if (undefined !== v.inner) { vs.push(...v.inner.b, ...v.inner.a) continue } const name = v.n || v.name if (S.Exact === name) { s.enum = v.a.slice() } else if (undefined !== JSON_SCHEMA_FORMAT[name]) { s.format = JSON_SCHEMA_FORMAT[name] } else if (S.Ip === name) { s.anyOf = [{ format: 'ipv4' }, { format: 'ipv6' }] } else if (S.Min === name || S.Max === name || S.Above === name || S.Below === name || S.Len === name) { const size = +v.a[0] for (const lo of families) { const hi = SIZE_MAX[lo] const numeric = 'minimum' === lo if (S.Min === name) { s[lo] = size } else if (S.Max === name) { s[hi] = size } else if (S.Above === name) { numeric ? (s.exclusiveMinimum = size) : (s[lo] = size + 1) } else if (S.Below === name) { numeric ? (s.exclusiveMaximum = size) : (s[hi] = size - 1) } else { s[lo] = size s[hi] = size } } } else if (S.Check === name && undefined !== v.a && v.a[0] instanceof RegExp) { s.pattern = v.a[0].source } else if (S.Contains === name) { // Each count is a constraint of its own: a second one on the node // joins the first through allOf. const c = containsSchema(v, defs) if (undefined === s.contains) { Object.assign(s, c) } else { s.allOf = (s.allOf || []).concat(c) } } else if (S.Unique === name) { s.uniqueItems = true } } } // A count of an array's items, as contains and the bounds on it. A count // shape with a check that is not a bound has no keyword for that check, so // the schema admits more than the shape does. function containsSchema(v: any, defs: any): any { const s: any = { contains: nodeSchema(v.u.shape, defs) } const { lo, hi } = v.u.bounds if (1 !== lo) { s.minContains = lo } if (Infinity !== hi) { s.maxContains = hi } return s } // The counts a count shape admits from its Min, Max, Above, Below and Len, // as the whole numbers lo to hi; exact where the shape has nothing else to // say of a whole number. function countBounds(n: Node): { lo: number, hi: number, exact: boolean } { let lo = 0 let hi = Infinity let exact = (S.any === n.t || S.number === n.t || S.integer === n.t) && 0 === n.a.length for (const cv of n.b) { const b = +cv.a?.[0] if (S.Min === cv.n) { lo = Math.max(lo, Math.ceil(b)) } else if (S.Max === cv.n) { hi = Math.min(hi, Math.floor(b)) } else if (S.Above === cv.n) { lo = Math.max(lo, Math.floor(b) + 1) } else if (S.Below === cv.n) { hi = Math.min(hi, Math.ceil(b) - 1) } else if (S.Len === cv.n) { lo = Math.max(lo, b) hi = Math.min(hi, b) } else { exact = false } } return { lo, hi, exact } } const G$ = (node: any): Node => nodize({ ...node, $: { shape$: true } }) const BuilderMap = { Above, After, All, Any, Before, Below, Catch, Check, Child, Closed, Coerce, Contains, DateTime, Default, Define, Describe, Discriminated, Email, Empty, Exact, Extend, Fault, Func, Ignore, Integer, Ip, Ipv4, Ipv6, Key, Len, Max, Min, Never, Nof, Nullable, Omit, Open, Optional, Partial, Pick, Refer, Rename, Required, Skip, Transform, Rest, Type, Unique, Url, Uuid, When, } // Builders that mean something applied to nothing, so a bare reference to one // in a spec (`{ a: Any }`) is read as a call. See nodize. const NULLARY_BUILDERS = [Any, Closed, Coerce, DateTime, Email, Empty, Func, Ignore, Integer, Ip, Ipv4, Ipv6, Key, Never, Nullable, Open, Optional, Required, Skip, Unique, Url, Uuid] for (let builder of NULLARY_BUILDERS) { defprop(builder, 'nullary$', { value: true }) } // Fix builder names after terser mangles them. /* node:coverage ignore next 5 */ if (S.undefined !== typeof (window)) { for (let builderName in BuilderMap) { defprop((BuilderMap as any)[builderName], S.name, { value: builderName }) } } // JSON Schema import // ================== // Build a spec from a JSON Schema (draft 2020-12, and the common keywords of // earlier drafts), the inverse of the export above: a type becomes a token, // bounds become size builders, formats and patterns their builders, enum and // const become Exact, properties and items become objects and arrays, the // compositions become All, Nof and Discriminated (anyOf a count of at // least one, oneOf of exactly one, not of none), and a definition is inlined // where it is referenced — Define and Refer only where a definition refers to // itself. A property that is not required and has no default is Skip. Unknown // keywords are ignored; an unknown type or reference is an error. The Go port // builds the same spec, and the differential harness compares the export of // what each imports. const JSON_SCHEMA_KIND: any = { string: 1, number: 1, integer: 1, boolean: 1, null: 1, object: 1, array: 1, } const JSON_SCHEMA_FORMAT_BUILDER: any = { email: 'Email', uri: 'Url', uuid: 'Uuid', 'date-time': 'DateTime', ipv4: 'Ipv4', ipv6: 'Ipv6', } // The drafts in which a $ref stands for the whole schema it sits in, so the // keywords beside it are ignored. From 2019-09 on, a $ref is one keyword // among the others. const JSON_SCHEMA_REF_ALONE = /^https?:\/\/json-schema\.org\/draft-0[3-7]\/schema#?$/ // Keywords the import recognises but does not enforce. It passes over them, // as it does a keyword it does not know, unless it is strict. const JSON_SCHEMA_UNSUPPORTED = [ '$dynamicRef', '$recursiveRef', 'multipleOf', 'patternProperties', 'propertyNames', 'unevaluatedItems', 'unevaluatedProperties', ] type JsonSchemaImportOptions = { // Refuse a keyword the import would pass over. strict?: boolean } function fromJsonSchema(schema: any, opts?: JsonSchemaImportOptions): any { if (S.boolean !== typeof schema && (null == schema || S.object !== typeof schema || Array.isArray(schema))) { throw new Error('JSON Schema: the schema must be an object or boolean') } const ctx = { root: schema, defs: schema.$defs || schema.definitions || {}, stack: [] as string[], recursive: {} as any, backrefs: 0, refAlone: S.string === typeof schema.$schema && JSON_SCHEMA_REF_ALONE.test(schema.$schema), strict: true === opts?.strict, } return importSchema(schema, ctx, '') } function jsonSchemaFault(msg: string, path: string): Error { return new Error('JSON Schema: ' + msg + ' at ' + ('' === path ? '/' : path)) } // A kind, where given, is the one kind of value the enclosing schema lets // through to this one (see importKindSplit). function importSchema(s: any, ctx: any, path: string, kind?: string): any { if (true === s) { return Any() } if (false === s) { return Never() } if (null == s || S.object !== typeof s || Array.isArray(s)) { throw jsonSchemaFault('a schema must be an object or boolean', path) } let spec: any = S.string === typeof s.$ref && ctx.refAlone ? importRef(s.$ref, ctx, path) : importKeywords(s, ctx, path, kind) if (S.string === typeof s.description) { spec = Describe(s.description, spec) } return spec } // A definition is inlined at each reference, so validation order cannot // matter; a definition that refers to itself is Defined at its outermost // expansion and Referred within. function importRef(ref: string, ctx: any, path: string): any { let name: string let def: any const m = ref.match(/^#\/(\$defs|definitions)\/([^/]+)$/) if (null != m) { name = decodeURIComponent(m[2]) def = ctx.defs[name] if (undefined === def) { throw jsonSchemaFault('unknown $ref "' + ref + '"', path) } } else if ('#' === ref) { name = '' def = ctx.root } else { throw jsonSchemaFault('unsupported $ref "' + ref + '"', path) } const refname = '' === name ? '$root' : name if (ctx.stack.includes(name)) { ctx.recursive[name] = true ctx.backrefs++ return Refer(refname) } ctx.stack.push(name) const wasRecursive = ctx.recursive[name] ctx.recursive[name] = false const spec = importSchema(def, ctx, path) const recursive = ctx.recursive[name] ctx.recursive[name] = wasRecursive ctx.stack.pop() return recursive ? Define(refname, spec) : spec } // Every keyword applies, each a part of All. Not comes first, so that it // sees the value as given. An enum or a const keeps only the values the // other parts allow, and so stays one Exact, with Exact's message. function importKeywords(s: any, ctx: any, path: string, kind?: string): any { if (ctx.strict) { for (const k of JSON_SCHEMA_UNSUPPORTED) { if (undefined !== s[k]) { throw jsonSchemaFault('unsupported keyword "' + k + '"', path) } } } let spec: any // not: {} admits nothing, whatever else the schema says. if (isEmptyObject(s.not)) { spec = Never() } else { // The subschemas of not, allOf, anyOf and oneOf see the same value, so // they need only meet the one kind this schema lets through, if it has // one. const inner = typeKind(s) || kind const backrefs = ctx.backrefs const parts: any[] = [] if (undefined !== s.not) { parts.push(Nof(0, importSchema(s.not, ctx, path + '/not', inner))) } // A condition sees the value as given, before a part fills it in. An if // with neither then nor else asserts nothing. if (undefined !== s.if && (undefined !== s.then || undefined !== s.else)) { const arm = (k: string) => undefined === s[k] ? undefined : importSchema(s[k], ctx, path + '/' + k, inner) parts.push(When(arm('if'), arm('then'), arm('else'))) } parts.push(...importDependents(s, ctx, path)) if (S.string === typeof s.$ref) { parts.push(importRef(s.$ref, ctx, path)) } const typed = importTyped(s, ctx, path, kind) if (!isBareAny(typed)) { parts.push(typed) } if (undefined !== s.allOf) { parts.push(All(...importBranches(s.allOf, ctx, path + '/allOf', inner))) } if (undefined !== s.anyOf && !isIpFormats(s.anyOf)) { parts.push(Nof(Min(1), ...importBranches(s.anyOf, ctx, path + '/anyOf', inner))) } if (undefined !== s.oneOf) { parts.push( importDiscriminated(importBranchList(s.oneOf, path + '/oneOf'), ctx, path + '/oneOf') || Nof(1, ...importBranches(s.oneOf, ctx, path + '/oneOf', inner))) } spec = undefined !== s.enum || undefined !== s.const ? importExact(s, parts, backrefs < ctx.backrefs, path) : 0 === parts.length ? Any() : 1 === parts.length ? parts[0] : All(...parts) } if (undefined !== s.default) { spec = Default(s.default, spec) } return spec } // Each entry of a dependent keyword is a When on its key being present: the // object must then hold the names dependentRequired lists, or satisfy the // schema dependentSchemas gives, which can only meet an object. Draft 7's // dependencies holds either form, and is read where neither of the two // that replaced it is written. function importDependents(s: any, ctx: any, path: string): any[] { const out: any[] = [] const holds = (names: string[]) => Open(names.reduce((o: any, k: string) => (ownprop(o, k, Required()), o), {})) const names = (v: any, at: string): string[] => { if (!Array.isArray(v) || v.some((n: any) => S.string !== typeof n)) { throw jsonSchemaFault('a dependency must be an array of property names', at) } return v } const required = (k: string, v: any, at: string) => { const list = names(v, at) if (0 < list.length) { out.push(When(holds([k]), holds(list))) } } const schema = (k: string, v: any, at: string) => out.push(When(holds([k]), importSchema(v, ctx, at, 'object'))) const legacy = undefined === s.dependentRequired && undefined === s.dependentSchemas for (const [kw, each] of [['dependentRequired', required], ['dependentSchemas', schema], ['dependencies', null]] as any[]) { const v = s[kw] if (undefined === v || ('dependencies' === kw && !legacy)) { continue } if (!isPlainObject(v)) { throw jsonSchemaFault(kw + ' must be an object', path + '/' + kw) } for (const k of keys(v)) { const at = path + '/' + kw + '/' + k ;(each || (Array.isArray(v[k]) ? required : schema))(k, v[k], at) } } return out } // An enum or a const, less the values the other parts refuse. A part that // refers back to a definition still being read cannot be tried yet, so the // parts then stay beside the Exact. function importExact(s: any, parts: any[], backref: boolean, path: string): any { let vals: any[] if (undefined !== s.enum) { if (!Array.isArray(s.enum)) { throw jsonSchemaFault('enum must be an array', path) } vals = undefined === s.const ? s.enum : s.enum.filter((v: any) => jsonEqual(v, s.const)) } else { vals = [s.const] } if (backref) { return All(0 === vals.length ? Never() : Exact(...vals), ...parts) } if (0 < parts.length) { const rest = Shape(1 === parts.length ? parts[0] : All(...parts)) vals = vals.filter((v: any) => rest.match(clone(v))) } return 0 === vals.length ? Never() : Exact(...vals) } // Equality of JSON values, as enum and const compare them. function jsonEqual(x: any, y: any): boolean { if (x === y) { return true } if (null == x || null == y || S.object !== typeof x || S.object !== typeof y || isarr(x) !== isarr(y)) { return false } const xk = keys(x) return xk.length === keys(y).length && xk.every((k: string) => hasOwn(y, k) && jsonEqual(x[k], y[k])) } function importBranchList(list: any, path: string): any[] { if (!Array.isArray(list)) { throw jsonSchemaFault(path.slice(path.lastIndexOf('/') + 1) + ' must be an array', path) } return list } function importBranches(list: any, ctx: any, path: string, kind?: string): any[] { return importBranchList(list, path).map((b: any, i: number) => importSchema(b, ctx, path + '/' + i, kind)) } function isPlainObject(v: any): boolean { return null != v && S.object === typeof v && !Array.isArray(v) } function isEmptyObject(v: any): boolean { return isPlainObject(v) && 0 === keys(v).length } // Whether a spec is the Any of a schema that says nothing. function isBareAny(spec: any): boolean { const n = nodize(spec) return S.any === n.t && 0 === n.b.length && 0 === n.a.length } // The export's rendering of Ip: an anyOf of the two address formats. function isIpFormats(anyOf: any): boolean { return Array.isArray(anyOf) && 2 === anyOf.length && anyOf.every((b: any) => null != b && S.object === typeof b && 1 === keys(b).length) && 'ipv4' === anyOf[0].format && 'ipv6' === anyOf[1].format } // The one kind of value a schema's type lets through, if it names one. function typeKind(s: any): string | undefined { const t = Array.isArray(s.type) && 1 === s.type.length ? s.type[0] : s.type return S.string === typeof t ? KIND_OF_TYPE[t] : undefined } function importTyped(s: any, ctx: any, path: string, kind?: string): any { const given: any[] = Array.isArray(s.type) ? s.type : (undefined === s.type ? [] : [s.type]) for (const t of given) { if (S.string !== typeof t || undefined === JSON_SCHEMA_KIND[t]) { throw jsonSchemaFault('unknown type "' + t + '"', path) } } // Null beside another type is Nullable, and a number covers an integer. let types = given.filter((t: any, i: number) => i === given.indexOf(t)) const nullable = types.includes('null') && 1 < types.length types = types.filter((t: any) => !(nullable && 'null' === t) && !('integer' === t && types.includes('number'))) if (0 === types.length) { return importKindSplit(s, ctx, path, kind) } // The types are of different kinds, so the value's kind chooses among // them (see Nof). const spec: any = 1 === types.length ? importKind(types[0], s, ctx, path) : Nof(1, ...types.map((t: any) => importKind(t, s, ctx, path))) return nullable ? Nullable(spec) : spec } function importKind(t: string, s: any, ctx: any, path: string): any { if ('string' === t) { return importString(s, path) } if ('number' === t || 'integer' === t) { return importNumber('integer' === t ? Integer() : Number, s) } if ('boolean' === t) { return Boolean } if ('null' === t) { return Required(null) } if ('object' === t) { return importObject(s, ctx, path) } return importArray(s, ctx, path) } // The keywords that apply to one kind of value only. const JSON_SCHEMA_KIND_KEYWORDS: any = { number: ['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum'], string: ['minLength', 'maxLength', 'pattern', 'format'], object: ['properties', 'required', 'additionalProperties', 'minProperties', 'maxProperties'], array: ['items', 'prefixItems', 'minItems', 'maxItems', 'contains', 'uniqueItems'], } // A schema without a type checks each kind of value with the keywords of // that kind, and lets every other kind through: { minLength: 2 } fails "a" // and passes 1. Where the enclosing schema lets one kind through, only that // kind's keywords can apply. function importKindSplit(s: any, ctx: any, path: string, kind?: string): any { const has = (k: string) => (undefined === kind || k === kind) && (JSON_SCHEMA_KIND_KEYWORDS[k].some((w: string) => undefined !== s[w]) || ('string' === k && isIpFormats(s.anyOf))) if (!['number', 'string', 'object', 'array'].some(has)) { return Any() } if (undefined !== kind) { return 'number' === kind ? importNumber(Number, s) : 'string' === kind ? importString(s, path) : 'object' === kind ? importObject(s, ctx, path) : importArray(s, ctx, path) } // A shape for each kind of JSON value: the value's kind chooses (see Nof). return Nof(1, Required(null), Boolean, has('number') ? importNumber(Number, s) : Number, has('string') ? importString(s, path) : Empty(String), has('object') ? importObject(s, ctx, path) : Open({}), has('array') ? importArray(s, ctx, path) : [], ) } function importString(s: any, path: string): any { let spec: any if (S.string === typeof s.pattern) { try { canonicalRegexp(s.pattern) spec = new RegExp(s.pattern) } catch (e: any) { throw jsonSchemaFault('bad pattern "' + s.pattern + '"', path) } } else { spec = String } const format = JSON_SCHEMA_FORMAT_BUILDER[s.format] if (undefined !== format) { // Called bare: a builder invoked as a method takes its receiver as the // shape to extend. const build = (BuilderMap as any)[format] spec = build(spec) } else if (Array.isArray(s.anyOf) && isIpFormats(s.anyOf)) { spec = Ip(spec) } else if (String === spec && !(0 < s.minLength)) { // A string with no lower bound is allowed to be empty; a pattern or // format decides for itself. spec = Empty(spec) } if (S.number === typeof s.minLength && 1 < s.minLength) { spec = Min(s.minLength, spec) } if (S.number === typeof s.maxLength) { spec = Max(s.maxLength, spec) } return spec } function importNumber(spec: any, s: any): any { // A numeric exclusive bound (draft 6 and later) and a plain bound are // independent keywords, so both apply; the boolean form (draft 4) makes // the plain bound exclusive instead. if (S.number === typeof s.exclusiveMinimum) { spec = Above(s.exclusiveMinimum, spec) } if (S.number === typeof s.minimum) { spec = true === s.exclusiveMinimum ? Above(s.minimum, spec) : Min(s.minimum, spec) } if (S.number === typeof s.exclusiveMaximum) { spec = Below(s.exclusiveMaximum, spec) } if (S.number === typeof s.maximum) { spec = true === s.exclusiveMaximum ? Below(s.maximum, spec) : Max(s.maximum, spec) } return spec } function importObject(s: any, ctx: any, path: string): any { if (undefined !== s.properties && !isPlainObject(s.properties)) { throw jsonSchemaFault('properties must be an object', path + '/properties') } const props: any = s.properties || {} const required: string[] = Array.isArray(s.required) ? s.required : [] const obj: any = {} for (const k of keys(props)) { ownprop(obj, k, importProperty(props[k], required.includes(k), ctx, path + '/properties/' + k)) } // A required name with no property schema must still be present. for (const k of required) { if (S.string === typeof k && !hasOwn(obj, k)) { ownprop(obj, k, Required()) } } let spec: any if (false === s.additionalProperties) { spec = 0 === keys(obj).length ? Closed(obj) : obj } else if (undefined === s.additionalProperties || true === s.additionalProperties) { spec = Open(obj) } else { spec = Child(importSchema(s.additionalProperties, ctx, path + '/additionalProperties'), obj) } if (S.number === typeof s.minProperties) { spec = Min(s.minProperties, spec) } if (S.number === typeof s.maxProperties) { spec = Max(s.maxProperties, spec) } return spec } // A property is required when listed, has its default when given, and is // otherwise Skip: absent stays absent. function importProperty(ps: any, required: boolean, ctx: any, path: string): any { const spec = importSchema(ps, ctx, path) if (null != ps && S.object === typeof ps && undefined !== ps.default) { return spec } return required ? Required(spec) : Skip(spec) } function importArray(s: any, ctx: any, path: string): any { if (undefined !== s.prefixItems && !Array.isArray(s.prefixItems)) { throw jsonSchemaFault('prefixItems must be an array', path + '/prefixItems') } let spec: any if (undefined !== s.prefixItems) { // Closed makes a one-element list a tuple rather than an element shape; // items says what may follow (anything, when it is absent or true). // A position may be absent, but for one before a position with a // default to fill in: an array has no holes. const dflt = (e: any) => isPlainObject(e) && undefined !== e.default const last = s.prefixItems.reduce((m: number, e: any, i: number) => dflt(e) ? i : m, -1) const tuple = Closed(s.prefixItems.map((e: any, i: number) => { const spec = importSchema(e, ctx, path + '/prefixItems/' + i) return dflt(e) ? spec : i < last ? Required(spec) : Skip(spec) })) if (false === s.items) { spec = tuple } else if (undefined === s.items || true === s.items) { spec = Rest(Any(), tuple) } else { spec = Rest(importSchema(s.items, ctx, path + '/items'), tuple) } } else if (undefined === s.items || true === s.items) { spec = [] } else { spec = [importSchema(s.items, ctx, path + '/items')] } if (S.number === typeof s.minItems) { spec = Min(s.minItems, spec) } if (S.number === typeof s.maxItems) { spec = Max(s.maxItems, spec) } // contains counts the items its schema admits, at least one unless // minContains says otherwise; a count of at least none asserts nothing. if (undefined !== s.contains) { const lo = S.number === typeof s.minContains ? s.minContains : 1 const hi = S.number === typeof s.maxContains ? s.maxContains : undefined if (0 < lo || undefined !== hi) { const count = lo === hi ? lo : undefined === hi ? Min(lo) : 0 === lo ? Max(hi) : Max(hi, Min(lo)) spec = Contains(count, importSchema(s.contains, ctx, path + '/contains'), spec) } } if (true === s.uniqueItems) { spec = Unique(spec) } return spec } // A oneOf of objects that each require one property with a distinct string // const is a discriminated union on that property. function importDiscriminated(branches: any[], ctx: any, path: string): any { if (0 === branches.length) { return undefined } let tag: string | undefined const tags: string[] = [] for (const b of branches) { if (null == b || S.object !== typeof b || null == b.properties || !Array.isArray(b.required)) { return undefined } // Candidates in name order, so both implementations pick the same tag. const found = keys(b.properties).sort().filter((k: string) => null != b.properties[k] && S.string === typeof b.properties[k].const && b.required.includes(k)) if (undefined === tag) { tag = found.find((k: string) => branches.every((o: any) => null != o && null != o.properties && null != o.properties[k] && S.string === typeof o.properties[k].const)) if (undefined === tag) { return undefined } } // A branch that does not require the tag could match a value without // one, so it is no tagged branch. const t = b.properties[tag].const if (tags.includes(t) || !b.required.includes(tag)) { return undefined } tags.push(t) } const out: any = {} for (let bI = 0; bI < branches.length; bI++) { const b = branches[bI] const props: any = {} for (const k of keys(b.properties)) { if (k !== tag) { ownprop(props, k, b.properties[k]) } } const required = b.required.filter((k: string) => k !== tag) out[tags[bI]] = importObject({ ...b, properties: props, required }, ctx, path + '/' + bI) } return Discriminated(tag as string, out) } Object.assign(shapify, { Shape: shapify, // Builders by name, allows `const { Open } = Shape`. ...BuilderMap, // Builders by alias, allows `const { GOpen } = Shape`, to avoid naming conflicts. ...(Object.entries(BuilderMap).reduce((a: any, n) => (a['G' + n[0]] = n[1], a), {})), isShape: (v: any) => (v && SHAPE === v.shape), G$, buildize, makeErr, stringify, jsonSchema, fromJsonSchema, truncate, nodize, expr, build, MakeArgu, }) type ShapeShape = ReturnType & { valid: (root?: D, ctx?: any) => root is (D & S), match: (root?: any, ctx?: any) => boolean, error: (root?: any, ctx?: Context) => ErrDesc[], spec: () => any, node: () => Node, jsonSchema: () => any, json: () => any, isShape: (v: any) => boolean, shape: typeof SHAPE } & StandardSchemaV1 type Shape = typeof shapify & typeof BuilderMap & { G$: typeof G$, buildize: typeof buildize, makeErr: typeof makeErr, stringify: typeof stringify, jsonSchema: typeof jsonSchema, fromJsonSchema: typeof fromJsonSchema, truncate: typeof truncate, nodize: typeof nodize, expr: typeof expr, build: typeof build, MakeArgu: typeof MakeArgu, } defprop(shapify, S.name, { value: S.shape }) // The primary export. const Shape: Shape = (shapify as Shape) // "G" Namespaced builders for convenient use in case of conflicts. const GAbove = Above const GAfter = After const GAll = All const GAny = Any const GInteger = Integer const GCoerce = Coerce const GCatch = Catch const GDescribe = Describe const GDiscriminated = Discriminated const GPick = Pick const GOmit = Omit const GPartial = Partial const GExtend = Extend const GTransform = Transform const GDateTime = DateTime const GEmail = Email const GIp = Ip const GIpv4 = Ipv4 const GIpv6 = Ipv6 const GUrl = Url const GUuid = Uuid const GNullable = Nullable const GBefore = Before const GBelow = Below const GCheck = Check const GChild = Child const GRest = Rest const GClosed = Closed const GDefault = Default const GDefine = Define const GEmpty = Empty const GExact = Exact const GFault = Fault const GFunc = Func const GIgnore = Ignore const GKey = Key const GLen = Len const GMax = Max const GMin = Min const GNever = Never const GNof = Nof const GWhen = When const GContains = Contains const GUnique = Unique const GOpen = Open const GOptional = Optional const GRefer = Refer const GRename = Rename const GRequired = Required const GSkip = Skip const GType = Type type args = any[] | IArguments type Argu = ( args: args | string, whence: string | Record, spec?: Record ) => (typeof args extends string ? ((args: args) => Record) : Record) function MakeArgu(name: string): Argu { // TODO: caching, make arguments optionals return function Argu( args: args | string, whence: string | Record, argSpec?: Record ): any { let partial = false if (S.string === typeof args) { partial = true argSpec = (whence as Record) whence = (args as string | Record) } argSpec = argSpec || (whence as Record) whence = S.string === typeof whence ? ' (' + whence + ')' : '' const shape = Shape(argSpec, { name: name + whence }) const top = shape.node() const keys = top.k let inargs = args let argmap: any = {} let kI = 0 let skips = 0 for (; kI < keys.length; kI++) { let kn = top.v[keys[kI]] // Skip in arg shape means a literal skip, // shifting all following agument elements down. if (kn.p) { // if (0 === kI) { kn = top.v[keys[kI]] = ((kI) => After(function Skipper( _val: any, update: Update, state: State ) { if (0 < state.curerr.length) { skips++ for (let sI = keys.length - 1; sI > kI; sI--) { // Subtract kI as state.pI has already advanced kI along val list. // If Rest, append to array at correct position. if (top.v[keys[sI]].m.rest) { argmap[keys[sI]] .splice(top.v[keys[sI]].m.rest_pos + kI - sI, 0, argmap[keys[sI - 1]]) } else { state.vals[state.pI + sI - kI] = state.vals[state.pI + sI - kI - 1] argmap[keys[sI]] = argmap[keys[sI - 1]] } } update.uval = undefined update.done = false } return true }, kn))(kI) kn.e = false } if (kI === keys.length - 1 && !top.v[keys[kI]].m.rest) { top.v[keys[kI]] = After(function ArgCounter( _val: any, update: Update, state: State ) { if ((keys.length - skips) < inargs.length) { if (0 === state.curerr.length) { update.err = `Too many arguments for type signature ` + `(was ${inargs.length}, expected ${keys.length - skips})` } update.fatal = true return false } return true }, top.v[keys[kI]]) } } function buildArgMap(args: args) { for (let kI = 0; kI < keys.length; kI++) { let kn = top.v[keys[kI]] if (kn.m.rest) { argmap[keys[kI]] = [...args].slice(kI) kn.m.rest_pos = argmap[keys[kI]].length } else { argmap[keys[kI]] = args[kI] } } return argmap } return partial ? function PartialArgu(args: args) { inargs = args argmap = {} kI = 0 skips = 0 return shape(buildArgMap(args)) } : shape(buildArgMap((args as args))) } } export type { Validate, Update, Context, ErrDesc, ShapeOptions, JsonSchemaImportOptions, Builder, Node, State, ShapeShape, StandardSchemaV1, StandardSchemaV1Props, StandardSchemaV1Result, StandardSchemaV1Issue, StandardSchemaV1PathSegment, StandardSchemaV1Types, } // Module-level export declarations are not executable statements, so V8 line // coverage never records them. /* node:coverage disable */ export { Shape, G$, nodize, buildize, makeErr, stringify, truncate, expr, MakeArgu, build, fromJsonSchema, Above, After, All, Any, Before, Below, Catch, Check, Child, Closed, Coerce, DateTime, Default, Define, Describe, Discriminated, Extend, Omit, Partial, Pick, Email, Empty, Exact, Fault, Func, Ignore, Integer, Ip, Ipv4, Ipv6, Key, Len, Max, Min, Never, Nof, Nullable, Open, Optional, Refer, Rename, Required, Skip, Transform, Type, Rest, Url, Uuid, When, Contains, Unique, GAbove, GAfter, GAll, GAny, GBefore, GBelow, GCheck, GChild, GClosed, GCoerce, GCatch, GDescribe, GDiscriminated, GPick, GOmit, GPartial, GExtend, GTransform, GDateTime, GEmail, GIp, GIpv4, GIpv6, GUrl, GUuid, GDefault, GDefine, GEmpty, GExact, GFault, GFunc, GIgnore, GInteger, GKey, GLen, GMax, GMin, GNever, GNof, GNullable, GOpen, GOptional, GRefer, GRename, GRequired, GSkip, GType, GRest, GWhen, GContains, GUnique, }