@sinclair/typebox 0.30.0-dev-2 → 0.30.0-dev-3

package/compiler/compiler.js

@@ -140,7 +140,7 @@ class TypeCompilerUnknownTypeError extends Error {
 exports.TypeCompilerUnknownTypeError = TypeCompilerUnknownTypeError;
 class TypeCompilerDereferenceError extends Error {
     constructor(schema) {
-        super(`TypeCompiler: Unable to dereference schema with $id '${schema.$ref}'`);
+        super(`TypeCompiler: Unable to dereference type with $id '${schema.$ref}'`);
         this.schema = schema;
     }
 }

package/errors/errors.js

@@ -131,7 +131,7 @@ class ValueErrorsUnknownTypeError extends Error {
 exports.ValueErrorsUnknownTypeError = ValueErrorsUnknownTypeError;
 class ValueErrorsDereferenceError extends Error {
     constructor(schema) {
-        super(`ValueErrors: Unable to dereference schema with $id '${schema.$ref}'`);
+        super(`ValueErrors: Unable to dereference type with $id '${schema.$ref}'`);
         this.schema = schema;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sinclair/typebox",
-  "version": "0.30.0-dev-2",
+  "version": "0.30.0-dev-3",
   "description": "JSONSchema Type Builder with Static Type Resolution for TypeScript",
   "keywords": [
     "typescript",

package/readme.md

@@ -198,13 +198,13 @@ function receive(value: T) {                         // ... as a Static Type
 
 ## Types
 
-TypeBox types are JSON schema fragments that can be composed into more complex types. Each fragment is structured such that a JSON schema compliant validator can runtime assert a value the same way TypeScript will statically assert a type. TypeBox provides a set of Standard types which are used create JSON schema compliant schematics as well as an Extended type set used to create schematics for constructs native to JavaScript.
+TypeBox types are JSON schema fragments that compose into complex types. Each fragment is structured such that a JSON schema compliant validator can runtime assert a value the same way TypeScript will statically assert a type. TypeBox provides a set of Standard types which are used create JSON schema compliant schematics as well as an Extended type set used to create schematics for constructs native to JavaScript.
 
 <a name='types-standard'></a>
 
 ### Standard Types
 
-The following table lists the Standard TypeBox types. These types are fully compatible with the JSON Schema Draft 6 specification.
+The following table lists the Standard TypeBox types. These types are fully compatible with the JSON Schema Draft 7 specification.
 
 ```typescript
 ┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
@@ -668,7 +668,7 @@ Object properties can be modified with `readonly` or `optional`. The following t
 
 ### Generic Types
 
-Generic types can be created with generic functions constrained to type `TSchema`. The following creates a generic `Vector<T>` type.
+Generic types are created with generic functions. All TypeBox types extend the sub type `TSchema` so it is common to constrain function arguments to this type. The following creates a generic `Vector<T>` type.
 
 ```typescript
 import { Type, Static, TSchema } from '@sinclair/typebox'
@@ -692,7 +692,7 @@ type NumberVector = Static<typeof NumberVector>      // type NumberVector = {
                                                      // }
 ```
 
-The following creates a generic `Nullable<T>` type.
+Generic types can be used to create aliases for more complex types. The following creates a `Nullable<T>` type.
 
 ```typescript
 const Nullable = <T extends TSchema>(schema: T) => Type.Union([schema, Type.Null()])
@@ -711,24 +711,26 @@ type T = Static<typeof T>                           // type T = string | null
 
 ### Reference Types
 
-Reference types are supported with `Type.Ref`. The target type must specify a valid `$id`.
+Reference types are supported with `Ref`.
 
 ```typescript
 const T = Type.String({ $id: 'T' })                  // const T = {
-                                                     //    $id: 'T',
-                                                     //    type: 'string'
+                                                     //   $id: 'T',
+                                                     //   type: 'string'
                                                      // }
 
-const R = Type.Ref(T)                                // const R = {
-                                                     //    $ref: 'T'
+const R = Type.Ref<typeof T>('T')                    // const R = {
+                                                     //   $ref: 'T'
                                                      // }
+
+type R = Static<typeof R>                            // type R = string
 ```
 
 <a name='types-recursive'></a>
 
 ### Recursive Types
 
-Recursive types are supported with `Type.Recursive`.
+Recursive types are supported with `Recursive`. Recursive type inference is also supported.
 
 ```typescript
 const Node = Type.Recursive(This => Type.Object({    // const Node = {
@@ -765,7 +767,7 @@ function test(node: Node) {
 
 ### Conditional Types
 
-TypeBox supports conditional types with `Type.Extends`. This type will perform a structural assignment check for the first two parameters and return a `true` or `false` type from the second two parameters. The types `Type.Exclude` and `Type.Extract` are also supported.
+TypeBox supports conditional types with `Extends`. This type performs a structural assignment check against the first two parameters and returns either the `true` or `false` type as given from the second two parameters. The conditional types `Exclude` and `Extract` are also supported.
 
 ```typescript
 // TypeScript
@@ -778,17 +780,17 @@ type T2 = Exclude<(1 | 2 | 3), 1>                    // type T2 = 2 | 3
 
 // TypeBox
 
-const T0 = Type.Extends(                             // const T0: TLiteral<false>
-  Type.String(), 
-  Type.Number(), 
-  Type.Literal(true), 
+const T0 = Type.Extends(                             // const T0: TLiteral<false> = {
+  Type.String(),                                     //   type: 'boolean',
+  Type.Number(),                                     //   const: false
+  Type.Literal(true),                                // }
   Type.Literal(false)
 )
 
-const T1 = Type.Extract(                             // const T1: TLiteral<1>
-  Type.Union([
-    Type.Literal(1), 
-    Type.Literal(2), 
+const T1 = Type.Extract(                             // const T1: TLiteral<1> = {
+  Type.Union([                                       //   type: 'number',
+    Type.Literal(1),                                 //   const: 1
+    Type.Literal(2),                                 // }
     Type.Literal(3) 
   ]), 
   Type.Literal(1)
@@ -797,42 +799,38 @@ const T1 = Type.Extract(                             // const T1: TLiteral<1>
 const T2 = Type.Exclude(                            // const T2: TUnion<[
   Type.Union([                                      //   TLiteral<2>,
     Type.Literal(1),                                //   TLiteral<3>
-    Type.Literal(2),                                // ]>
-    Type.Literal(3) 
-  ]), 
-  Type.Literal(1)
-)
+    Type.Literal(2),                                // ]> = {
+    Type.Literal(3)                                 //   anyOf: [{
+  ]),                                               //     type: 'number',
+  Type.Literal(1)                                   //     const: 2
+)                                                   //   }, {
+                                                    //     type: 'number',
+                                                    //     const: 3
+                                                    //   }]
+                                                    // }
 ```
 
 <a name='types-template-literal'></a>
 
 ### Template Literal Types
 
-TypeBox supports template literal types with `Type.TemplateLiteral`. This type implements an embedded DSL syntax to match the TypeScript template literal syntax. This type can also be composed by passing an array of union and literal types as parameters. The following example shows the DSL syntax.
+TypeBox supports template literal types with `TemplateLiteral`. This type provides an embedded DSL syntax that is similar to the TypeScript template literal syntax. These type can also be composed by passing a tuple of exterior union and literal types. The following example shows the DSL syntax.
 
 ```typescript
 // TypeScript
 
-type P = `/post/${string}/user/${number}`            // type P = `/post/${string}/user/${number}`
-
-type T = `option${'A'|'B'}`                          // type T = 'optionA' | 'optionB'
+type T = `option${'A'|'B'|'C'}`                      // type T = 'optionA' | 'optionB' | 'optionC'
 
 type R = Record<T, string>                           // type R = {
                                                      //   optionA: string
                                                      //   optionB: string
+                                                     //   optionC: string
                                                      // }
 
 // TypeBox
 
-const P = Type.TemplateLiteral('/post/${string}/user/${number}')
-
-                                                     // const P = {
-                                                     //   type: 'string',
-                                                     //   pattern: '^/post/(.*)/user/(0|[1-9][0-9]*)$'
-                                                     // }
-
-const T = Type.TemplateLiteral('option${A|B}')       // const T = {
-                                                     //   pattern: '^option(A|B)$',
+const T = Type.TemplateLiteral('option${A|B|C}')     // const T = {
+                                                     //   pattern: '^option(A|B|C)$',
                                                      //   type: 'string'
                                                      // }
 
@@ -846,6 +844,9 @@ const R = Type.Record(T, Type.String())              // const R = {
                                                      //     optionB: {
                                                      //       type: 'string'
                                                      //     }
+                                                     //     optionC: {
+                                                     //       type: 'string'
+                                                     //     }
                                                      //   }
                                                      // }
 ```
@@ -854,7 +855,7 @@ const R = Type.Record(T, Type.String())              // const R = {
 
 ### Indexed Access Types
 
-TypeBox supports indexed access types using `Type.Index`. This type provides a consistent way to access interior property and array element types without having to extract them from the underlying schema representation. Indexed access types are supported for object, array, tuple, union and intersect types.
+TypeBox supports indexed access types using `Index`. This type provides a consistent way of accessing interior property and array element types without having to extract them from the underlying schema representation. Indexed access types are supported for object, array, tuple, union and intersect types.
 
 ```typescript
 const T = Type.Object({                              // const T = {
@@ -889,7 +890,7 @@ const C = Type.Index(T, Type.KeyOf(T))               // const C = {
 
 ### Negated Types
 
-TypeBox has support for type negation with `Type.Not`. This type will always infer as `unknown`.
+TypeBox has support for type negation with `Not`. This type will always infer as `unknown`.
 
 ```typescript
 const T = Type.Not(Type.String())                   // const T = {
@@ -900,7 +901,7 @@ type T = Static<typeof T>                           // type T = unknown
                                                     //
                                                     // where T could be any type other than string
 ```
-This type can be useful for certain forms of type narrowing. For example, consider a type that represents a `number` but not the values `1, 2, 3`. The example below shows an imaginary TypeScript syntax to express such a type followed by the TypeBox representation.
+Type negation can be useful for certain forms of type narrowing. For example, consider a type that represents a `number` but not the numbers `1, 2, 3`. The example below shows an imaginary TypeScript syntax to express such a type followed by the TypeBox representation.
 
 ```typescript
 // TypeScript
@@ -926,7 +927,6 @@ const T = Type.Intersect([                           // const T = {
 
 type T = Static<typeof T>                            // type T = number
 ```
-
 This type can be used with constraints to create schematics that would otherwise be difficult to express.
 ```typescript
 const Even = Type.Number({ multipleOf: 2 })
@@ -937,7 +937,7 @@ const Odd = Type.Intersect([Type.Number(), Type.Not(Even)])
 
 ### Rest Types
 
-Rest parameters are supported with `Type.Rest`. This function is used to extract interior type elements from tuples which enables them to compose with the JavaScript spread operator `...`. This type can be used for tuple concatenation as well as for variadic functions.
+Rest parameters are supported with `Rest`. This function is used to extract interior type elements from tuples which enables them to compose with the JavaScript spread operator `...`. This type can be used for tuple concatenation as well function parameter assignment.
 
 ```typescript
 // TypeScript
@@ -975,7 +975,7 @@ const F = Type.Function(Type.Rest(C), Type.Void())   // const F: TFunction<[
 
 ### Unsafe Types
 
-Use `Type.Unsafe` to create custom schematics with user defined inference rules.
+TypeBox supports the creation of user defined schematics with user defined inference rules using the Unsafe type.
 
 ```typescript
 const T = Type.Unsafe<string>({ type: 'number' })    // const T = {
@@ -985,7 +985,7 @@ const T = Type.Unsafe<string>({ type: 'number' })    // const T = {
 type T = Static<typeof T>                            // type T = string
 ```
 
-The `Type.Unsafe` type can be useful to express specific OpenAPI schema representations.
+This type can be useful to create various extended schematics, such as those used by OpenAPI.
 
 ```typescript
 import { Type, Static, TSchema } from '@sinclair/typebox'
@@ -1020,12 +1020,12 @@ type T = Static<typeof T>                            // type T = 'A' | 'B' | 'C'
 
 ### Type Guards
 
-TypeBox provides a `TypeGuard` module that can be used for reflection and asserting values as types.
+TypeBox provides a TypeGuard module to assert JavaScript values are valid TypeBox types.
 
 ```typescript
-import { Type, TypeGuard } from '@sinclair/typebox'
+import { Type, Kind, TypeGuard } from '@sinclair/typebox'
 
-const T = Type.String()
+const T = { [Kind]: 'String', type: 'string' }
 
 if(TypeGuard.TString(T)) {
 
@@ -1037,7 +1037,7 @@ if(TypeGuard.TString(T)) {
 
 ### Strict
 
-TypeBox types contain various symbol properties that are used for reflection, composition and compilation. 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 necessary.
+TypeBox types contain various symbol properties that are used for reflection, composition and compilation. These properties are not strictly valid JSON schema; so in some cases it may be desirable to omit them. TypeBox provides a `Strict` function that will omit these properties if necessary.
 
 ```typescript
 const T = Type.Object({                              // const T = {
@@ -1110,7 +1110,7 @@ const R = Value.Check(T, { x: 1 })                   // const R = true
 
 ### Convert
 
-Use the Convert function to convert a value into its target type if a reasonable conversion is possible.
+Use the Convert function to convert a value into its target type if a reasonable conversion is possible. This function may return an invalid value and should be checked before use. It's return type is `unknown`.
 
 ```typescript
 const T = Type.Object({ x: Type.Number() })
@@ -1262,7 +1262,7 @@ ValuePointer.Set(A, '/z', 1)                         // const A' = { x: 1, y: 1,
 
 ## TypeCheck
 
-TypeBox types target JSON Schema draft 6 so are compatible with any validator that supports this specification. TypeBox also provides a built in type checking compiler designed specifically for high performance compilation and value assertion.
+TypeBox types target JSON Schema draft 7 so are compatible with any validator that supports this specification. TypeBox also provides a built in type checking compiler designed specifically for high performance compilation and value assertion.
 
 The following sections detail using Ajv and TypeBox's compiler infrastructure.
 

package/value/cast.js

@@ -74,7 +74,7 @@ class ValueCastUnknownTypeError extends Error {
 exports.ValueCastUnknownTypeError = ValueCastUnknownTypeError;
 class ValueCastDereferenceError extends Error {
     constructor(schema) {
-        super(`ValueCast: Unable to dereference schema with $id '${schema.$ref}'`);
+        super(`ValueCast: Unable to dereference type with $id '${schema.$ref}'`);
         this.schema = schema;
     }
 }

package/value/check.js

@@ -44,7 +44,7 @@ class ValueCheckUnknownTypeError extends Error {
 exports.ValueCheckUnknownTypeError = ValueCheckUnknownTypeError;
 class ValueCheckDereferenceError extends Error {
     constructor(schema) {
-        super(`ValueCheck: Unable to dereference schema with $id '${schema.$ref}'`);
+        super(`ValueCheck: Unable to dereference type with $id '${schema.$ref}'`);
         this.schema = schema;
     }
 }

package/value/convert.js

@@ -44,7 +44,7 @@ class ValueConvertUnknownTypeError extends Error {
 exports.ValueConvertUnknownTypeError = ValueConvertUnknownTypeError;
 class ValueConvertDereferenceError extends Error {
     constructor(schema) {
-        super(`ValueConvert: Unable to dereference schema with $id '${schema.$ref}'`);
+        super(`ValueConvert: Unable to dereference type with $id '${schema.$ref}'`);
         this.schema = schema;
     }
 }

package/value/create.js

@@ -71,7 +71,7 @@ class ValueCreateTempateLiteralTypeError extends Error {
 exports.ValueCreateTempateLiteralTypeError = ValueCreateTempateLiteralTypeError;
 class ValueCreateDereferenceError extends Error {
     constructor(schema) {
-        super(`ValueCreate: Unable to dereference schema with $id '${schema.$ref}'`);
+        super(`ValueCreate: Unable to dereference type with $id '${schema.$ref}'`);
         this.schema = schema;
     }
 }