@sinclair/typebox 0.34.8 → 0.34.10

package/readme.md

@@ -78,9 +78,6 @@ License MIT
   - [Unsafe](#types-unsafe)
 - [Syntax](#syntax)
   - [Parse](#syntax-parse)
-  - [Compose](#syntax-compose)
-  - [Context](#syntax-context)
-  - [Module](#syntax-module)
   - [Static](#syntax-static)
   - [Limits](#syntax-limits)
 - [Values](#values)
@@ -1025,9 +1022,9 @@ if(TypeGuard.IsString(T)) {
 
 ## Syntax Types
 
-TypeBox provides support for parsing TypeScript syntax directly into TypeBox Json Schema schematics. Syntax Types offer a string based DSL frontend to TypeBox's Type Builder system and can be useful for converting existing TypeScript type definitions into Json Schema schematics without reimplementation via the Type Builder.
+TypeBox has support for parsing TypeScript type annotations directly into TypeBox types. This feature supports both runtime and static parsing, with TypeBox implementing TypeScript parsers within the TypeScript type system itself. Syntax Types use the TypeBox Json Schema representations as an AST target for TypeScript types, providing a direct mapping between TypeScript syntax and Json Schema. Syntax Types are offered as a syntactical frontend to the Standard Type Builder API.
 
-Syntax Types are provided via optional import.
+This feature is available via optional import.
 
 ```typescript
 import { Parse } from '@sinclair/typebox/syntax'
@@ -1037,7 +1034,7 @@ import { Parse } from '@sinclair/typebox/syntax'
 
 ### Parse
 
-Use the Parse function to convert a TypeScript string into a TypeBox type. TypeBox will infer the appropriate TSchema type or return undefined if there is a syntax error.
+Use the Parse function to transform a TypeScript type annotation into a TypeBox type. This function will return the parsed TypeBox type or undefined on error.
 
 ```typescript
 const A = Parse('string')                           // const A: TString
@@ -1054,45 +1051,46 @@ const C = Parse(`{ x: number, y: number }`)         // const C: TObject<{
                                                     // }>
 ```
 
-
-
-<a name='syntax-compose'></a>
-
-### Compose
-
-Syntax Types are designed to be interchangeable with standard Types.
+Syntax Types can compose with Standard Types created via the Type Builder API
 
 ```typescript
 const T = Type.Object({                             // const T: TObject<{
   x: Parse('number'),                               //   x: TNumber,
-  y: Parse('number'),                               //   y: TNumber,
-  z: Parse('number')                                //   z: TNumber
+  y: Parse('string'),                               //   y: TString,
+  z: Parse('boolean')                               //   z: TBoolean
 })                                                  // }>
 ```
 
-<a name='syntax-module'></a>
+Standard Types can also be passed to and referenced within Syntax Types.
 
-### Module
+```typescript
+const X = Type.Number()
+const Y = Type.String()
+const Z = Type.Boolean()
+
+const T = Parse({ X, Y, Z }, `{ 
+  x: X, 
+  y: Y, 
+  z: Z 
+}`)
+```
 
-Syntax Types also support Module parsing. This can provide a more terse syntax for creating Module definitions, but comes with an inference performance cost. Module parsing supports interface and type alias definitions. Generics types are currently unsupported. 
+Syntax Types also support Module parsing.
 
 ```typescript
-const Module = Parse(`module {
-  
+const Foo = Parse(`module Foo {
+
+  export type PartialUser = Pick<User, 'id'> & Partial<Omit<User, 'id'>>
+
   export interface User {
     id: string
     name: string
     email: string
   }
- 
-  export type PartialUser = (
-    Pick<User, 'id'> &
-    Partial<Omit<User, 'id'>>
-  )
 
 }`)
 
-const PartialUser = Module.Import('PartialUser')    // TImport<{...}, 'PartialUser'>
+const PartialUser = Foo.Import('PartialUser')       // TImport<{...}, 'PartialUser'>
 
 type PartialUser = Static<typeof PartialUser>       // type PartialUser = {
                                                     //   id: string,
@@ -1102,45 +1100,11 @@ type PartialUser = Static<typeof PartialUser>       // type PartialUser = {
                                                     // }
 ```
 
-<a name='syntax-context'></a>
-
-### Context
-
-The Parse function takes an optional leading Context object that contains external types. This Context allows the syntax to reference these external types using the property identifiers provided by the Context. The following passes the external type `T` to Parse.
-
-```typescript
-const T = Type.Object({                             // const T: TObject<{
-  x: Type.Number(),                                 //   x: TNumber,
-  y: Type.Number(),                                 //   y: TNumber,
-  z: Type.Number()                                  //   z: TNumber
-})                                                  // }>
-
-const A = Parse({ T }, 'Partial<T>')                // const A: TObject<{
-                                                    //   x: TOptional<TNumber>,
-                                                    //   y: TOptional<TNumber>,
-                                                    //   z: TOptional<TNumber>
-                                                    // }>
-
-const B = Parse({ T }, 'keyof T')                   // const B: TUnion<[
-                                                    //   TLiteral<'x'>,
-                                                    //   TLiteral<'y'>,
-                                                    //   TLiteral<'z'>
-                                                    // ]>
-
-const C = Parse({ T }, 'T & { w: number }')         // const C: TIntersect<[TObject<{
-                                                    //    x: TNumber;
-                                                    //    y: TNumber;
-                                                    //    z: TNumber;
-                                                    // }>, TObject<{
-                                                    //    w: TNumber;
-                                                    // }>]>
-```
-
 <a name='syntax-static'></a>
 
 ### Static
 
-Syntax Types provide two Static types for inferring TypeScript types and TypeBox schematics from strings.
+Syntax Types provide two Static types specific to inferring TypeBox and TypeScript types from strings.
 
 ```typescript
 import { StaticParseAsSchema, StaticParseAsType } from '@sinclair/typebox/syntax' 
@@ -1154,8 +1118,8 @@ type S = StaticParseAsSchema<{}, '{ x: number }'>   // type S: TObject<{
 // Will infer as a type
 
 type T = StaticParseAsType<{}, '{ x: number }'>     // type T = {
-                                                    //  x: number
-                                                    //                       
+                                                    //   x: number
+                                                    // }                      
 ```
 
 
@@ -1163,7 +1127,7 @@ type T = StaticParseAsType<{}, '{ x: number }'>     // type T = {
 
 ### Limitations
 
-Syntax Types work by having TypeBox parse TypeScript syntax within the TypeScript type system. This approach can place some strain on the TypeScript compiler and language service, potentially affecting responsiveness. While TypeBox makes a best-effort attempt to optimize for Syntax Types, users should be mindful of the following structures:
+TypeBox parses TypeScript types directly within the TypeScript type system. This process does come with an inference cost, which scales with the size and complexity of the types being parsed. Although TypeBox strives to optimize Syntax Types, users should be aware of the following structures:
 
 ```typescript
 // Excessively wide structures will result in instantiation limits exceeding
@@ -1190,12 +1154,12 @@ const B = Parse(`{
 }`)
 ```
 
-In cases where Syntax Types exceed TypeScript's instantiation limits, TypeBox offers a fallback ParseOnly function, which will only parse but not infer. This function can also be used to parse types where the syntax is statically unknown to TypeScript (for example, when loading types from disk).
+If Syntax Types exceed TypeScript's instantiation limits, users are advised to fall back to the Standard Type Builder API. Alternatively, TypeBox offers a `ParseOnly` function that parses the TypeScript syntax at runtime without statically inferring the schema.
 
 ```typescript
 import { ParseOnly } from '@sinclair/typebox/syntax'
 
-// Where A is TSchema | undefined 
+// const A: TSchema | undefined 
 
 const A = ParseOnly(`{
   x: {
@@ -1208,7 +1172,7 @@ const A = ParseOnly(`{
 }`)
 ```
 
-For more information on TypeBox's parsing infrastructure, refer to the [ParseBox](https://github.com/sinclairzx81/parsebox) project.
+For more information on static parsing, refer to the [ParseBox](https://github.com/sinclairzx81/parsebox) project.
 
 <a name='values'></a>
 
@@ -1361,26 +1325,28 @@ const B = Value.Encode(Type.String(), 42)             // throw
 
 ### Parse
 
-Use the Parse function to parse a value or throw if invalid. This function internally uses Default, Clean, Convert and Decode to make a best effort attempt to parse the value into the expected type. This function should not be used in performance critical code paths.
+Use the Parse function to parse a value. This function calls the `Clone` `Clean`, `Default`, `Convert`, `Assert` and `Decode` Value functions in this exact order to process a value.
 
 ```typescript
-const T = Type.Object({ x: Type.Number({ default: 0 }), y: Type.Number({ default: 0 }) })
+const R = Value.Parse(Type.String(), 'hello')      // const R: string = "hello"
 
-// Default
+const E = Value.Parse(Type.String(), undefined)    // throws AssertError 
+```
 
-const A = Value.Parse(T, { })                                 // const A = { x: 0, y: 0 }
+You can override the order in which functions are run, or omit functions entirely using the following.
 
-// Convert
+```typescript
+// Runs no functions.
 
-const B = Value.Parse(T, { x: '1', y: '2' })                  // const B = { x: 1, y: 2 }
+const R = Value.Parse([], Type.String(), 12345)
 
-// Clean
+// Runs the Assert() function.
 
-const C = Value.Parse(T, { x: 1, y: 2, z: 3 })                // const C = { x: 1, y: 2 }
+const E = Value.Parse(['Assert'], Type.String(), 12345)
 
-// Assert
+// Runs the Convert() function followed by the Assert() function.
 
-const D = Value.Parse(T, undefined)                           // throws AssertError
+const S = Value.Parse(['Convert', 'Assert'], Type.String(), 12345)
 ```
 
 <a name='values-equal'></a>