@sinclair/typebox - npm Package Compare versions

Comparing version 0.17.1 to 0.17.2

package.json

 {
   "name": "@sinclair/typebox",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "description": "JSONSchema Type Builder with Static Type Resolution for TypeScript",
@@ -5,0 +5,0 @@ "keywords": [

readme.md

@@ -50,4 +50,4 @@ <div align='center'>
 - [Options](#Options)
-- [Additional Properties](#AdditionalProperties)
 - [Strict](#Strict)
+- [Reference Types](#Reference-Types)
 - [Extended Types](#Extended-Types)
@@ -123,8 +123,4 @@ - [Interfaces](#Interfaces)
 
-function receive(record: Record) { // ... as a type
-    if(JSON.validate(Record, {     // ... as a schema
-        id: '42', 
-        name: 'dave', 
-        timestamp: Date.now() 
-    })) {
+function receive(record: Record) {      // ... as a type
+    if(JSON.validate(Record, record)) { // ... as a schema
         // ok...
@@ -386,36 +382,2 @@ }
 
-<a name="AdditionalProperties"></a>
-
-### Additional Properties
-
-By default, schemas created with `Type.Object({...})` and `Type.Intersect([...])` are permissive of additional properties. This is inline with TypeScript's behaviour with respect to structural and polymorphic types as well as JSON schema rules around applying additive constraints (which aligns to a form of downstream polymorphism for the schema). This is quite a subtle concept, but consider the following where one might assume that the additional property `c` would raise a static assertion error.
-
-#### TypeScript
-
-```typescript
-type T = { a: number, b: number }
-
-function run(data: T) { }
-
-const data = { a: 10, b: 10, c: 20 } as const // 'c' is an additional property
-
-run(data) // this is fine
-```
-
-#### TypeBox
-
-```typescript
-const T = Type.Object({ a: Type.Number(), b: Type.Number() })
-
-function run(data: Static<typeof T>) { }
-
-const data = { a: 10, b: 10, c: 20 } as const // 'c' is an additional property
-
-run(data) // this is fine
-```
-TypeBox aligns with TypeScript and JSON Schema semantics in this regard, however this may be undesirable for data received over the wire. You can disallow additional properties by applying the standard `additionalProperties` property as an option to the schema.
-```typescript
-const T = Type.Object({ a: Type.Number(), b: Type.Number() }, { additionalProperties: false })
-```
-
 <a name="Strict"></a>
@@ -449,3 +411,70 @@
 ```
+<a name="Reference-Types"></a>
 
+### Reference Types
+
+It's common to want to group related schemas together under a common shared namespace. This is typically handled via `$id` and `$ref` properties in JSON schema. TypeBox provides rudimentary support for this using the `Type.Box(...)` and `Type.Ref(...)` methods. The `Type.Box(...)` method allows one to register a collection of related schemas under a common `$id` or namespace, and `Type.Ref(...)` allows for referencing into the box. The following demonstrates the usage for a set of `Math3D` types.
+
+```typescript
+const Vector2 = Type.Object({ x: Type.Number(), y: Type.Number() })
+const Vector3 = Type.Object({ x: Type.Number(), y: Type.Number(), z: Type.Number() })
+const Vector4 = Type.Object({ x: Type.Number(), y: Type.Number(), z: Type.Number(), w: Type.Number() })
+
+const Math3D  = Type.Box('math3d', { Vector2, Vector3, Vector4 })
+
+const Vertex = Type.Object({
+    position: Type.Ref(Math3D, 'Vector4'),
+    normal:   Type.Ref(Math3D, 'Vector3'),
+    uv:       Type.Ref(Math3D, 'Vector2'),
+})
+```
+Where `Math3D` is expressed as
+```typescript
+const Math3D = {
+  $id: "math3d",
+  definitions: {
+    Vector2: {
+      type: "object",
+      properties: {
+        x: { "type": "number" },
+        y: { "type": "number" }
+      },
+      required: ["x", "y" ]
+    },
+    Vector3: {
+      type: "object",
+      properties: {
+        x: { "type": "number" },
+        y: { "type": "number" },
+        z: { "type": "number" }
+      },
+      required: ["x", "y", "z"]
+    },
+    Vector4: {
+      type: "object",
+      properties: {
+        x: { "type": "number" },
+        y: { "type": "number" },
+        z: { "type": "number" },
+        w: { "type": "number" }
+      },
+      required: ["x", "y", "z", "w"]
+    }
+  }
+}
+```
+And the `Vertex` is expressed as.
+```typescript
+const Vertex = {
+  type: "object",
+  properties: {
+    position: { $ref: "math3d#/definitions/Vector4" },
+    normal: { $ref: "math3d#/definitions/Vector3" },
+    uv: { $ref: "math3d#/definitions/Vector2" }
+  },
+  required: ["position", "normal", "uv"]
+}
+```
+> Note, the methods `Type.Partial(...)`, `Type.Required(...)`, `Type.Pick(...)` and `Type.Omit(...)` are currently not supported for referenced types. This may change in future releases where the referenced schema is copied into the dependent schema with the appropriate schema modifications applied. This project is open to community feedback on advancing this feature in future releases.
+
 <a name="Extended-Types"></a>
@@ -452,0 +481,0 @@

typebox.d.ts

@@ -14,2 +14,3 @@ export declare const ReadonlyOptionalModifier: unique symbol;
 };
+export declare const BoxKind: unique symbol;
 export declare const KeyOfKind: unique symbol;
@@ -68,5 +69,13 @@ export declare const UnionKind: unique symbol;
 export declare type TValue = string | number | boolean;
+export declare type TDefinitions = {
+    [key: string]: TSchema;
+};
 export declare type TProperties = {
     [key: string]: TSchema;
 };
+export declare type TBox<T extends TDefinitions> = {
+    kind: typeof BoxKind;
+    $id: string;
+    definitions: T;
+};
 export declare type TTuple<T extends TSchema[]> = {
@@ -203,2 +212,3 @@ kind: typeof TupleKind;
 };
+export declare type StaticRef<T extends TSchema> = Static<T>;
 export declare type StaticKeyOf<T extends TKey[]> = T extends Array<infer K> ? K : never;
@@ -287,3 +297,7 @@ export declare type StaticUnion<T extends readonly TSchema[]> = {
     Void(options?: CustomOptions): TVoid;
+    /** `EXPERIMENTAL` Creates a box of schema definitions. */
+    Box<T extends TDefinitions>($id: string, definitions: T): TBox<T>;
+    /** `EXPERIMENTAL` References a type within a box of definitions. */
+    Ref<T extends TBox<TDefinitions>, K extends keyof T['definitions']>(box: T, key: K): T['definitions'][K];
 }
 export declare const Type: TypeBuilder;

typebox.js

@@ -30,3 +30,3 @@ "use strict";
 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.DictKind = exports.ObjectKind = exports.TupleKind = exports.UnionKind = exports.KeyOfKind = exports.ReadonlyModifier = exports.OptionalModifier = exports.ReadonlyOptionalModifier = void 0;
+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.DictKind = exports.ObjectKind = exports.TupleKind = exports.UnionKind = exports.KeyOfKind = exports.BoxKind = exports.ReadonlyModifier = exports.OptionalModifier = exports.ReadonlyOptionalModifier = void 0;
 // ------------------------------------------------------------------------
@@ -41,2 +41,3 @@ // Modifiers
 // ------------------------------------------------------------------------
+exports.BoxKind = Symbol('BoxKind');
 exports.KeyOfKind = Symbol('KeyOfKind');
@@ -289,4 +290,12 @@ exports.UnionKind = Symbol('UnionKind');
     }
+    /** `EXPERIMENTAL` Creates a box of schema definitions. */
+    Box($id, definitions) {
+        return { kind: exports.BoxKind, $id, definitions };
+    }
+    /** `EXPERIMENTAL` References a type within a box of definitions. */
+    Ref(box, key) {
+        return { $ref: `${box.$id}#/definitions/${key}` }; // facade
+    }
 }
 exports.TypeBuilder = TypeBuilder;
 exports.Type = new TypeBuilder();

No alert changes

Improved metrics

Total package byte prevSize

79941

increased by2.62%

Lines of code

594

increased by4.21%

Number of lines in readme file

679

increased by4.46%

No dependency changes