@sinclair/typebox 0.22.1 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sinclair/typebox",
-  "version": "0.22.1",
+  "version": "0.23.0",
   "description": "JSONSchema Type Builder with Static Type Resolution for TypeScript",
   "keywords": [
     "json-schema",

package/typebox.d.ts

@@ -28,6 +28,7 @@ export declare const BooleanKind: unique symbol;
 export declare const NullKind: unique symbol;
 export declare const UnknownKind: unique symbol;
 export declare const AnyKind: unique symbol;
+export declare const RefKind: unique symbol;
 export interface CustomOptions {
     $id?: string;
     title?: string;
@@ -174,6 +175,11 @@ export interface TAny extends TSchema, CustomOptions {
     $static: any;
     kind: typeof AnyKind;
 }
+export interface TRef<T extends TSchema> extends TSchema, CustomOptions {
+    $static: Static<T>;
+    kind: typeof RefKind;
+    $ref: string;
+}
 export declare const ConstructorKind: unique symbol;
 export declare const FunctionKind: unique symbol;
 export declare const PromiseKind: unique symbol;
@@ -209,6 +215,9 @@ export interface TVoid extends TSchema, CustomOptions {
     kind: typeof VoidKind;
     type: 'void';
 }
+export declare type Pickable = TObject<TProperties> | TRef<TObject<TProperties>>;
+export declare type PickablePropertyKeys<T extends Pickable> = T extends TObject<infer U> ? keyof U : T extends TRef<TObject<infer U>> ? keyof U : never;
+export declare type PickableProperties<T extends Pickable> = T extends TObject<infer U> ? U : T extends TRef<TObject<infer U>> ? U : never;
 export declare type UnionToIntersect<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
 export declare type StaticReadonlyOptionalPropertyKeys<T extends TProperties> = {
     [K in keyof T]: T[K] extends TReadonlyOptional<TSchema> ? K : never;
@@ -262,6 +271,7 @@ export declare type StaticFunction<T extends readonly TSchema[], U extends TSche
 export declare type StaticPromise<T extends TSchema> = Promise<Static<T>>;
 export declare type Static<T extends TSchema> = T['$static'];
 export declare class TypeBuilder {
+    private readonly schemas;
     /** `Standard` Modifies an object property to be both readonly and optional */
     ReadonlyOptional<T extends TSchema>(item: T): TReadonlyOptional<T>;
     /** `Standard` Modifies an object property to be readonly */
@@ -299,17 +309,17 @@ export declare class TypeBuilder {
     /** `Standard` Creates an any type */
     Any(options?: CustomOptions): TAny;
     /** `Standard` Creates a keyof type from the given object */
-    KeyOf<T extends TObject<TProperties>>(schema: T, options?: CustomOptions): TKeyOf<(keyof T['properties'])[]>;
+    KeyOf<T extends TObject<TProperties>>(object: T, options?: CustomOptions): TKeyOf<(keyof T['properties'])[]>;
     /** `Standard` Creates a record type */
     Record<K extends TRecordKey, T extends TSchema>(key: K, value: T, options?: ObjectOptions): TRecord<K, T>;
     /** `Standard` Makes all properties in the given object type required */
-    Required<T extends TObject<any>>(schema: T, options?: ObjectOptions): TObject<StaticRequired<T['properties']>>;
+    Required<T extends TObject<TProperties> | TRef<TObject<TProperties>>>(object: T, options?: ObjectOptions): TObject<StaticRequired<T['properties']>>;
     /** `Standard` Makes all properties in the given object type optional */
-    Partial<T extends TObject<any>>(schema: T, options?: ObjectOptions): TObject<StaticPartial<T['properties']>>;
+    Partial<T extends TObject<TProperties> | TRef<TObject<TProperties>>>(object: T, options?: ObjectOptions): TObject<StaticPartial<T['properties']>>;
     /** `Standard` Picks property keys from the given object type */
-    Pick<T extends TObject<TProperties>, K extends (keyof T['properties'])[]>(schema: T, keys: [...K], options?: ObjectOptions): TObject<Pick<T['properties'], K[number]>>;
+    Pick<T extends TObject<TProperties> | TRef<TObject<TProperties>>, K extends PickablePropertyKeys<T>[]>(object: T, keys: [...K], options?: ObjectOptions): TObject<Pick<PickableProperties<T>, K[number]>>;
     /** `Standard` Omits property keys from the given object type */
-    Omit<T extends TObject<any>, K extends (keyof T['properties'])[]>(schema: T, keys: [...K], options?: ObjectOptions): TObject<Omit<T['properties'], K[number]>>;
+    Omit<T extends TObject<TProperties> | TRef<TObject<TProperties>>, K extends PickablePropertyKeys<T>[]>(object: T, keys: [...K], options?: ObjectOptions): TObject<Omit<PickableProperties<T>, K[number]>>;
     /** `Standard` Omits the `kind` and `modifier` properties from the underlying schema */
     Strict<T extends TSchema>(schema: T, options?: CustomOptions): T;
     /** `Extended` Creates a constructor type */
@@ -322,14 +332,17 @@ export declare class TypeBuilder {
     Undefined(options?: CustomOptions): TUndefined;
     /** `Extended` Creates a void type */
     Void(options?: CustomOptions): TVoid;
+    /** `Standard` Creates a namespace for a set of related types */
+    Namespace<T extends TDefinitions>($defs: T, options?: CustomOptions): TNamespace<T>;
+    /** `Standard` References a type within a namespace. The referenced namespace must specify an `$id` */
+    Ref<T extends TNamespace<TDefinitions>, K extends keyof T['$defs']>(box: T, key: K): TRef<T['$defs'][K]>;
+    /** `Standard` References type. The referenced type must specify an `$id` */
+    Ref<T extends TSchema>(schema: T): TRef<T>;
     /** `Experimental` Creates a recursive type */
     Rec<T extends TSchema>(callback: (self: TAny) => T, options?: CustomOptions): T;
-    /** `Experimental` Creates a recursive type. Pending https://github.com/ajv-validator/ajv/issues/1709 */
-    /** `Experimental` Creates a namespace for a set of related types */
-    Namespace<T extends TDefinitions>($defs: T, options?: CustomOptions): TNamespace<T>;
-    /** `Experimental` References a type within a namespace. The referenced namespace must specify an `$id` */
-    Ref<T extends TNamespace<TDefinitions>, K extends keyof T['$defs']>(box: T, key: K): T['$defs'][K];
-    /** `Experimental` References type. The referenced type must specify an `$id` */
-    Ref<T extends TSchema>(schema: T): T;
+    /** Stores this schema if it contains an $id. This function is used for later referencing. */
+    private Store;
+    /** Resolves a schema by $id. May resolve recursively if the target is a TRef. */
+    private Resolve;
 }
 export declare const Type: TypeBuilder;

package/typebox.js

@@ -27,7 +27,7 @@ THE SOFTWARE.
 
 ---------------------------------------------------------------------------*/
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Type = exports.TypeBuilder = exports.VoidKind = exports.UndefinedKind = exports.PromiseKind = exports.FunctionKind = exports.ConstructorKind = exports.AnyKind = exports.UnknownKind = exports.NullKind = exports.BooleanKind = exports.IntegerKind = exports.NumberKind = exports.StringKind = exports.LiteralKind = exports.EnumKind = exports.ArrayKind = exports.RecordKind = exports.ObjectKind = exports.TupleKind = exports.UnionKind = exports.IntersectKind = exports.KeyOfKind = exports.BoxKind = exports.ReadonlyModifier = exports.OptionalModifier = exports.ReadonlyOptionalModifier = void 0;
+exports.Type = exports.TypeBuilder = exports.VoidKind = exports.UndefinedKind = exports.PromiseKind = exports.FunctionKind = exports.ConstructorKind = exports.RefKind = exports.AnyKind = exports.UnknownKind = exports.NullKind = exports.BooleanKind = exports.IntegerKind = exports.NumberKind = exports.StringKind = exports.LiteralKind = exports.EnumKind = exports.ArrayKind = exports.RecordKind = exports.ObjectKind = exports.TupleKind = exports.UnionKind = exports.IntersectKind = exports.KeyOfKind = exports.BoxKind = exports.ReadonlyModifier = exports.OptionalModifier = exports.ReadonlyOptionalModifier = void 0;
 // --------------------------------------------------------------------------
 // Modifiers
 // --------------------------------------------------------------------------
@@ -54,6 +54,7 @@ exports.BooleanKind = Symbol('BooleanKind');
 exports.NullKind = Symbol('NullKind');
 exports.UnknownKind = Symbol('UnknownKind');
 exports.AnyKind = Symbol('AnyKind');
+exports.RefKind = Symbol('RefKind');
 // --------------------------------------------------------------------------
 // Extended Schema Types
 // --------------------------------------------------------------------------
@@ -82,6 +83,7 @@ function clone(object) {
 // TypeBuilder
 // --------------------------------------------------------------------------
 class TypeBuilder {
+    schemas = new Map();
     /** `Standard` Modifies an object property to be both readonly and optional */
     ReadonlyOptional(item) {
         return { ...item, modifier: exports.ReadonlyOptionalModifier };
@@ -99,9 +101,10 @@ class TypeBuilder {
         const additionalItems = false;
         const minItems = items.length;
         const maxItems = items.length;
-        return ((items.length > 0)
+        const schema = ((items.length > 0)
             ? { ...options, kind: exports.TupleKind, type: 'array', items, additionalItems, minItems, maxItems }
             : { ...options, kind: exports.TupleKind, type: 'array', minItems, maxItems });
+        return this.Store(schema);
     }
     /** `Standard` Creates an object type with the given properties */
     Object(properties, options = {}) {
@@ -114,35 +117,35 @@ class TypeBuilder {
         });
         const required_names = property_names.filter(name => !optional.includes(name));
         const required = (required_names.length > 0) ? required_names : undefined;
-        return ((required)
+        return this.Store(((required)
             ? { ...options, kind: exports.ObjectKind, type: 'object', properties, required }
-            : { ...options, kind: exports.ObjectKind, type: 'object', properties });
+            : { ...options, kind: exports.ObjectKind, type: 'object', properties }));
     }
     /** `Standard` Creates an intersect type. */
     Intersect(items, options = {}) {
-        return { ...options, kind: exports.IntersectKind, type: 'object', allOf: items };
+        return this.Store({ ...options, kind: exports.IntersectKind, type: 'object', allOf: items });
     }
     /** `Standard` Creates a union type */
     Union(items, options = {}) {
-        return { ...options, kind: exports.UnionKind, anyOf: items };
+        return this.Store({ ...options, kind: exports.UnionKind, anyOf: items });
     }
     /** `Standard` Creates an array type */
     Array(items, options = {}) {
-        return { ...options, kind: exports.ArrayKind, type: 'array', items };
+        return this.Store({ ...options, kind: exports.ArrayKind, type: 'array', items });
     }
     /** `Standard` Creates an enum type from a TypeScript enum */
     Enum(item, options = {}) {
         const values = Object.keys(item).filter(key => isNaN(key)).map(key => item[key]);
         const anyOf = values.map(value => typeof value === 'string' ? { type: 'string', const: value } : { type: 'number', const: value });
-        return { ...options, kind: exports.EnumKind, anyOf };
+        return this.Store({ ...options, kind: exports.EnumKind, anyOf });
     }
     /** `Standard` Creates a literal type. Supports string, number and boolean values only */
     Literal(value, options = {}) {
-        return { ...options, kind: exports.LiteralKind, const: value, type: typeof value };
+        return this.Store({ ...options, kind: exports.LiteralKind, const: value, type: typeof value });
     }
     /** `Standard` Creates a string type */
     String(options = {}) {
-        return { ...options, kind: exports.StringKind, type: 'string' };
+        return this.Store({ ...options, kind: exports.StringKind, type: 'string' });
     }
     /** `Standard` Creates a string type from a regular expression */
     RegEx(regex, options = {}) {
@@ -150,32 +153,32 @@ class TypeBuilder {
     }
     /** `Standard` Creates a number type */
     Number(options = {}) {
-        return { ...options, kind: exports.NumberKind, type: 'number' };
+        return this.Store({ ...options, kind: exports.NumberKind, type: 'number' });
     }
     /** `Standard` Creates an integer type */
     Integer(options = {}) {
-        return { ...options, kind: exports.IntegerKind, type: 'integer' };
+        return this.Store({ ...options, kind: exports.IntegerKind, type: 'integer' });
     }
     /** `Standard` Creates a boolean type */
     Boolean(options = {}) {
-        return { ...options, kind: exports.BooleanKind, type: 'boolean' };
+        return this.Store({ ...options, kind: exports.BooleanKind, type: 'boolean' });
     }
     /** `Standard` Creates a null type */
     Null(options = {}) {
-        return { ...options, kind: exports.NullKind, type: 'null' };
+        return this.Store({ ...options, kind: exports.NullKind, type: 'null' });
     }
     /** `Standard` Creates an unknown type */
     Unknown(options = {}) {
-        return { ...options, kind: exports.UnknownKind };
+        return this.Store({ ...options, kind: exports.UnknownKind });
     }
     /** `Standard` Creates an any type */
     Any(options = {}) {
-        return { ...options, kind: exports.AnyKind };
+        return this.Store({ ...options, kind: exports.AnyKind });
     }
     /** `Standard` Creates a keyof type from the given object */
-    KeyOf(schema, options = {}) {
-        const keys = Object.keys(schema.properties);
-        return { ...options, kind: exports.KeyOfKind, type: 'string', enum: keys };
+    KeyOf(object, options = {}) {
+        const keys = Object.keys(object.properties);
+        return this.Store({ ...options, kind: exports.KeyOfKind, type: 'string', enum: keys });
     }
     /** `Standard` Creates a record type */
     Record(key, value, options = {}) {
@@ -188,14 +191,15 @@ class TypeBuilder {
                 default: throw Error('Invalid Record Key');
             }
         })();
-        return { ...options, kind: exports.RecordKind, type: 'object', patternProperties: { [pattern]: value } };
+        return this.Store({ ...options, kind: exports.RecordKind, type: 'object', patternProperties: { [pattern]: value } });
     }
     /** `Standard` Makes all properties in the given object type required */
-    Required(schema, options = {}) {
-        const next = { ...clone(schema), ...options };
-        next.required = Object.keys(next.properties);
-        for (const key of Object.keys(next.properties)) {
-            const property = next.properties[key];
+    Required(object, options = {}) {
+        const source = this.Resolve(object);
+        const schema = { ...clone(source), ...options };
+        schema.required = Object.keys(schema.properties);
+        for (const key of Object.keys(schema.properties)) {
+            const property = schema.properties[key];
             switch (property.modifier) {
                 case exports.ReadonlyOptionalModifier:
                     property.modifier = exports.ReadonlyModifier;
@@ -211,14 +215,15 @@ class TypeBuilder {
                     break;
             }
         }
-        return next;
+        return this.Store(schema);
     }
     /** `Standard` Makes all properties in the given object type optional */
-    Partial(schema, options = {}) {
-        const next = { ...clone(schema), ...options };
-        delete next.required;
-        for (const key of Object.keys(next.properties)) {
-            const property = next.properties[key];
+    Partial(object, options = {}) {
+        const source = this.Resolve(object);
+        const schema = { ...clone(source), ...options };
+        delete schema.required;
+        for (const key of Object.keys(schema.properties)) {
+            const property = schema.properties[key];
             switch (property.modifier) {
                 case exports.ReadonlyOptionalModifier:
                     property.modifier = exports.ReadonlyOptionalModifier;
@@ -234,27 +239,29 @@ class TypeBuilder {
                     break;
             }
         }
-        return next;
+        return this.Store(schema);
     }
     /** `Standard` Picks property keys from the given object type */
-    Pick(schema, keys, options = {}) {
-        const next = { ...clone(schema), ...options };
-        next.required = next.required ? next.required.filter((key) => keys.includes(key)) : undefined;
-        for (const key of Object.keys(next.properties)) {
+    Pick(object, keys, options = {}) {
+        const source = this.Resolve(object);
+        const schema = { ...clone(source), ...options };
+        schema.required = schema.required ? schema.required.filter((key) => keys.includes(key)) : undefined;
+        for (const key of Object.keys(schema.properties)) {
             if (!keys.includes(key))
-                delete next.properties[key];
+                delete schema.properties[key];
         }
-        return next;
+        return this.Store(schema);
     }
     /** `Standard` Omits property keys from the given object type */
-    Omit(schema, keys, options = {}) {
-        const next = { ...clone(schema), ...options };
-        next.required = next.required ? next.required.filter((key) => !keys.includes(key)) : undefined;
-        for (const key of Object.keys(next.properties)) {
+    Omit(object, keys, options = {}) {
+        const source = this.Resolve(object);
+        const schema = { ...clone(source), ...options };
+        schema.required = schema.required ? schema.required.filter((key) => !keys.includes(key)) : undefined;
+        for (const key of Object.keys(schema.properties)) {
             if (keys.includes(key))
-                delete next.properties[key];
+                delete schema.properties[key];
         }
-        return next;
+        return this.Store(schema);
     }
     /** `Standard` Omits the `kind` and `modifier` properties from the underlying schema */
     Strict(schema, options = {}) {
@@ -262,43 +269,70 @@ class TypeBuilder {
     }
     /** `Extended` Creates a constructor type */
     Constructor(args, returns, options = {}) {
-        return { ...options, kind: exports.ConstructorKind, type: 'constructor', arguments: args, returns };
+        return this.Store({ ...options, kind: exports.ConstructorKind, type: 'constructor', arguments: args, returns });
     }
     /** `Extended` Creates a function type */
     Function(args, returns, options = {}) {
-        return { ...options, kind: exports.FunctionKind, type: 'function', arguments: args, returns };
+        return this.Store({ ...options, kind: exports.FunctionKind, type: 'function', arguments: args, returns });
     }
     /** `Extended` Creates a promise type */
     Promise(item, options = {}) {
-        return { ...options, type: 'promise', kind: exports.PromiseKind, item };
+        return this.Store({ ...options, type: 'promise', kind: exports.PromiseKind, item });
     }
     /** `Extended` Creates a undefined type */
     Undefined(options = {}) {
-        return { ...options, type: 'undefined', kind: exports.UndefinedKind };
+        return this.Store({ ...options, type: 'undefined', kind: exports.UndefinedKind });
     }
     /** `Extended` Creates a void type */
     Void(options = {}) {
-        return { ...options, type: 'void', kind: exports.VoidKind };
+        return this.Store({ ...options, type: 'void', kind: exports.VoidKind });
+    }
+    /** `Standard` Creates a namespace for a set of related types */
+    Namespace($defs, options = {}) {
+        return this.Store({ ...options, kind: exports.BoxKind, $defs });
+    }
+    Ref(...args) {
+        if (args.length === 2) {
+            const namespace = args[0];
+            const targetKey = args[1];
+            if (namespace.$id === undefined)
+                throw new Error(`Referenced namespace has no $id`);
+            if (!this.schemas.has(namespace.$id))
+                throw new Error(`Unable to locate namespace with $id '${namespace.$id}'`);
+            return this.Store({ kind: exports.RefKind, $ref: `${namespace.$id}#/$defs/${targetKey}` });
+        }
+        else if (args.length === 1) {
+            const target = args[0];
+            if (target.$id === undefined)
+                throw new Error(`Referenced schema has no $id`);
+            if (!this.schemas.has(target.$id))
+                throw new Error(`Unable to locate schema with $id '${target.$id}'`);
+            return this.Store({ kind: exports.RefKind, $ref: target.$id });
+        }
+        else {
+            throw new Error('Type.Ref: Invalid arguments');
+        }
     }
     /** `Experimental` Creates a recursive type */
     Rec(callback, options = {}) {
         const $id = options.$id || '';
         const self = callback({ $ref: `${$id}#/$defs/self` });
-        return { ...options, $ref: `${$id}#/$defs/self`, $defs: { self } };
-    }
-    /** `Experimental` Creates a recursive type. Pending https://github.com/ajv-validator/ajv/issues/1709 */
-    // public Rec<T extends TProperties>($id: string, callback: (self: TAny) => T, options: ObjectOptions = {}): TObject<T> {
-    //     const properties = callback({ $recursiveRef: `${$id}` } as any)
-    //     return { ...options, kind: ObjectKind, $id, $recursiveAnchor: true, type: 'object', properties }
-    // }
-    /** `Experimental` Creates a namespace for a set of related types */
-    Namespace($defs, options = {}) {
-        return { ...options, kind: exports.BoxKind, $defs };
-    }
-    Ref(...args) {
-        const $id = args[0]['$id'] || '';
-        const key = args[1];
-        return (args.length === 2) ? { $ref: `${$id}#/$defs/${key}` } : { $ref: $id };
+        return this.Store({ ...options, $ref: `${$id}#/$defs/self`, $defs: { self } });
+    }
+    /** Stores this schema if it contains an $id. This function is used for later referencing. */
+    Store(schema) {
+        if (!schema.$id)
+            return schema;
+        this.schemas.set(schema.$id, schema);
+        return schema;
+    }
+    /** Resolves a schema by $id. May resolve recursively if the target is a TRef. */
+    Resolve(schema) {
+        if (schema.kind !== exports.RefKind)
+            return schema;
+        if (!this.schemas.has(schema.$ref))
+            throw Error(`Unable to locate schema with $id '${schema.$ref}'`);
+        return this.Resolve(this.schemas.get(schema.$ref));
     }
 }
 exports.TypeBuilder = TypeBuilder;