@sinclair/typebox
Advanced tools
Comparing version 0.17.2 to 0.17.3
{ | ||
"name": "@sinclair/typebox", | ||
"version": "0.17.2", | ||
"version": "0.17.3", | ||
"description": "JSONSchema Type Builder with Static Type Resolution for TypeScript", | ||
@@ -5,0 +5,0 @@ "keywords": [ |
179
readme.md
@@ -50,5 +50,5 @@ <div align='center'> | ||
- [Options](#Options) | ||
- [Extended Types](#Extended-Types) | ||
- [Reference Types](#Reference-Types) | ||
- [Strict](#Strict) | ||
- [Reference Types](#Reference-Types) | ||
- [Extended Types](#Extended-Types) | ||
- [Interfaces](#Interfaces) | ||
@@ -381,98 +381,3 @@ - [Validation](#Validation) | ||
<a name="Strict"></a> | ||
### Strict | ||
TypeBox includes the properties `kind` and `modifier` on each underlying schema. These properties are used to help TypeBox statically resolve the schemas to the appropriate TypeScript type as well as apply the appropriate modifiers to an objects properties (such as optional). These properties are not strictly valid JSON schema so in some cases it may be desirable to omit them. TypeBox provides a `Type.Strict()` function that will omit these properties if nessasary. | ||
```typescript | ||
const T = Type.Object({ // const T = { | ||
name: Type.Optional(Type.String()) // kind: Symbol(ObjectKind), | ||
}) // type: 'object', | ||
// properties: { | ||
// name: { | ||
// kind: Symbol(StringKind), | ||
// type: 'string', | ||
// modifier: Symbol(OptionalModifier) | ||
// } | ||
// } | ||
// } | ||
const U = Type.Strict(T) // const U = { | ||
// type: 'object', | ||
// properties: { | ||
// name: { | ||
// type: 'string' | ||
// } | ||
// } | ||
// } | ||
``` | ||
<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> | ||
@@ -535,2 +440,82 @@ | ||
<a name="Reference-Types"></a> | ||
### Reference Types | ||
Type referencing can be useful to help reduce schema duplication when composing complex schemas. TypeBox allows for type referencing with the `Type.Box(...)` and `Type.Ref(...)` functions. The `Type.Box(...)` function creates a container for set of common related types and the `Type.Ref(...)` function allows referencing into the box. The following shows a set of common math types contained within a box, and a vertex structure that references those types. | ||
```typescript | ||
const Math3D = Type.Box('math3d', { // const Math3D = { | ||
Vector4: Type.Object({ // $id: 'math3d', | ||
x: Type.Number(), // definitions: { | ||
y: Type.Number(), // Vector4: { | ||
z: Type.Number(), // type: 'object', | ||
w: Type.Number() // properties: { | ||
}), // x: { type: 'number' }, | ||
Vector3: Type.Object({ // y: { type: 'number' }, | ||
x: Type.Number(), // z: { type: 'number' }, | ||
y: Type.Number(), // w: { type: 'number' } | ||
z: Type.Number() // }, | ||
}), // required: ['x', 'y', 'z', 'w'] | ||
Vector2: Type.Object({ // }, | ||
x: Type.Number(), // Vector3: { | ||
y: Type.Number() // type: 'object', | ||
}) // properties: { | ||
}) // x: { 'type': 'number' }, | ||
// y: { 'type': 'number' }, | ||
// z: { 'type': 'number' } | ||
// }, | ||
// required: ['x', 'y', 'z'] | ||
// }, | ||
// Vector2: { | ||
// type: 'object', | ||
// properties: { | ||
// x: { 'type': 'number' }, | ||
// y: { 'type': 'number' }, | ||
// }, | ||
// required: ['x', 'y', 'z', 'w'] | ||
// } | ||
// } | ||
// } | ||
const Vertex = Type.Object({ // const Vertex = { | ||
position: Type.Ref(Math3D, 'Vector4'), // type: 'object', | ||
normal: Type.Ref(Math3D, 'Vector3'), // properties: { | ||
uv: Type.Ref(Math3D, 'Vector2') // position: { $ref: 'math3d#/definitions/Vector4' }, | ||
}) // normal: { $ref: 'math3d#/definitions/Vector3' }, | ||
// uv: { $ref: 'math3d#/definitions/Vector2' } | ||
// }, | ||
// required: ['position', 'normal', 'uv'] | ||
// } | ||
``` | ||
<a name="Strict"></a> | ||
### Strict | ||
TypeBox includes the properties `kind` and `modifier` on each underlying schema. These properties are used to help TypeBox statically resolve the schemas to the appropriate TypeScript type as well as apply the appropriate modifiers to an objects properties (such as optional). These properties are not strictly valid JSON schema so in some cases it may be desirable to omit them. TypeBox provides a `Type.Strict()` function that will omit these properties if nessasary. | ||
```typescript | ||
const T = Type.Object({ // const T = { | ||
name: Type.Optional(Type.String()) // kind: Symbol(ObjectKind), | ||
}) // type: 'object', | ||
// properties: { | ||
// name: { | ||
// kind: Symbol(StringKind), | ||
// type: 'string', | ||
// modifier: Symbol(OptionalModifier) | ||
// } | ||
// } | ||
// } | ||
const U = Type.Strict(T) // const U = { | ||
// type: 'object', | ||
// properties: { | ||
// name: { | ||
// type: 'string' | ||
// } | ||
// } | ||
// } | ||
``` | ||
<a name="Interfaces"></a> | ||
@@ -537,0 +522,0 @@ |
@@ -210,3 +210,2 @@ export declare const ReadonlyOptionalModifier: unique symbol; | ||
}; | ||
export declare type StaticRef<T extends TSchema> = Static<T>; | ||
export declare type StaticKeyOf<T extends TKey[]> = T extends Array<infer K> ? K : never; | ||
@@ -295,7 +294,7 @@ export declare type StaticUnion<T extends readonly TSchema[]> = { | ||
Void(options?: CustomOptions): TVoid; | ||
/** `EXPERIMENTAL` Creates a box of schema definitions. */ | ||
/** `EXPERIMENTAL` Creates a container for schema definitions. */ | ||
Box<T extends TDefinitions>($id: string, definitions: T): TBox<T>; | ||
/** `EXPERIMENTAL` References a type within a box of definitions. */ | ||
/** `EXPERIMENTAL` References a schema within a box. */ | ||
Ref<T extends TBox<TDefinitions>, K extends keyof T['definitions']>(box: T, key: K): T['definitions'][K]; | ||
} | ||
export declare const Type: TypeBuilder; |
@@ -288,7 +288,7 @@ "use strict"; | ||
} | ||
/** `EXPERIMENTAL` Creates a box of schema definitions. */ | ||
/** `EXPERIMENTAL` Creates a container for schema definitions. */ | ||
Box($id, definitions) { | ||
return { kind: exports.BoxKind, $id, definitions }; | ||
} | ||
/** `EXPERIMENTAL` References a type within a box of definitions. */ | ||
/** `EXPERIMENTAL` References a schema within a box. */ | ||
Ref(box, key) { | ||
@@ -295,0 +295,0 @@ return { $ref: `${box.$id}#/definitions/${key}` }; // facade |
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
81013
593
664