Revision 0.34.24 (#1175)

* Support Generic Parameter Syntax

* Documentation

* Version

* ChangeLog

Author: sinclairzx81

changelog/0.34.0.md

@@ -4,7 +4,8 @@
 
 ### Revision Updates
 
-
+- [Revision 0.34.24](https://github.com/sinclairzx81/typebox/pull/1175)
+  - Add Support For Generic Parameter Syntax
 - [Revision 0.34.23](https://github.com/sinclairzx81/typebox/pull/1174)
   - Inline Instantiate Type Logic Local to Instantiate Module
 - [Revision 0.34.22](https://github.com/sinclairzx81/typebox/pull/1171)

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@sinclair/typebox",
-  "version": "0.34.23",
+  "version": "0.34.24",
   "description": "Json Schema Type Builder with Static Type Resolution for TypeScript",
   "keywords": [
     "typescript",

package.json

@@ -98,8 +98,8 @@ License MIT
 - [Syntax](#syntax)
   - [Create](#syntax-create)
   - [Parameters](#syntax-parameters)
-  - [Options](#syntax-options)
   - [Generics](#syntax-generics)
+  - [Options](#syntax-options)
 - [TypeRegistry](#typeregistry)
   - [Type](#typeregistry-type)
   - [Format](#typeregistry-format)
@@ -1306,9 +1306,9 @@ ValuePointer.Set(A, '/z', 1)                         // A' = { x: 1, y: 1, z: 1
 
 ## Syntax Types
 
-TypeBox has support for parsing TypeScript syntax at runtime as well as statically in the type system. This feature offers a syntactical frontend to the TypeBox type builder.
+TypeBox includes support for parsing TypeScript annotation syntax into TypeBox schematics.
 
-Syntax types are available via optional import.
+This feature is provided via optional import.
 
 ```typescript
 import { Syntax } from '@sinclair/typebox/syntax'
@@ -1318,20 +1318,25 @@ import { Syntax } from '@sinclair/typebox/syntax'
 
 ### Create
 
-Use the Syntax function to create TypeBox types from TypeScript syntax
+Use the Syntax function to create TypeBox types from TypeScript syntax ([Example](https://www.typescriptlang.org/play/?moduleResolution=99&module=199&ts=5.8.0-beta#code/JYWwDg9gTgLgBAbzgZQJ4DsYEMAecC+cAZlBCHAOQACAzsOgMYA2WwUA9DKmAKYBGEHOxoZsOCgChQkWIhTYYwBgWKly1OoxZtO3foMkSGEdDXgAVOAF4Uo3AAoABkhwAuOOgCuIPjygAaOFR3Lx8-AkcASjgY2Jj2djhjUwt3cwB5PgArHgYYAB4ECTiS0rLyisrYhNi3OHMAOW9fAOKq9o7OuBqY4PqmsKg2rpHR+MT8AD4JCS5eeut5LEUGfLmeCCJ6ybHKmvWFmyLdk86euDrQlv9h07uy876rv1v7t-GCIA))
 
 ```typescript
 const T = Syntax(`{ x: number, y: number }`)        // const T: TObject<{
                                                     //   x: TNumber,
                                                     //   y: TNumber
                                                     // }>
+
+type T = Static<typeof T>                            // type T = {
+                                                     //   x: number,
+                                                     //   y: number
+                                                     // }
 ```
 
 <a name="syntax-parameters"></a>
 
 ### Parameters
 
-Syntax types can be parameterized to receive exterior types.
+Syntax types can be parameterized to receive exterior types ([Example](https://www.typescriptlang.org/play/?moduleResolution=99&module=199&ts=5.8.0-beta#code/JYWwDg9gTgLgBAbzgZQJ4DsYEMAecC+cAZlBCHAOQACAzsOgMYA2WwUA9DKmAKYBGEHOxoZsOCgCgJDCOhrwAKnAC8KUbgAUAAyQ4AXHHQBXEHx5QANHFQHjp8wS0BKOK7ev27ODLmKDCgHk+ACseBhgAHgQJd1i4+ITEpLdPN304BQA5EzNLGOSCwqK4VNcbDOz7KHzi2rqPL3wAPikfeRQVNUxNJCV8Ky0ABSxYYCwmCIUm52LUtvhkfyDQ8Kia+o2C0rh0wLAYYFlxycrcpot1zav47fK9g6OJrJzzFuv3m8amoA))
 
 ```typescript
 const T = Syntax(`{ x: number, y: number }`)        // const T: TObject<{
@@ -1345,35 +1350,19 @@ const S = Syntax({ T }, `Partial<T>`)               // const S: TObject<{
                                                     // }>
 ```
 
-<a name='syntax-options'></a>
-
-### Options
 
-Options can be passed via the last parameter
-
-```typescript
-const T = Syntax(`number`, {                      // const T = {
-  minimum: 0,                                     //   type: 'number',
-  maximum: 10                                     //   minimum: 0,
-})                                                //   maximum: 10
-                                                  // }
-```
 
 <a name="syntax-generics"></a>
 
 ### Generics
 
-Generic types can be created using positional argument types ([Example](https://www.typescriptlang.org/play/?moduleResolution=99&module=199&ts=5.8.0-beta#code/JYWwDg9gTgLgBAbzgZQJ4DsYEMAecC+cAZlBCHAOQACAzsOgMYA2WwUA9DKmAKYBGEHOxoZsOCgChQkWIhTYYwBgWKly1OoxZtO3foMkSGEdDXgAVAAxwAvClG4AFBQCCUAOYBXED0wAeSwA+CgBKIxMzOHMARlt7TCdXD29fGD9o4LDjUwsAJji0BJxnNy8ff1zMiXCcuAA1HgYYaAKHYqQrABoo6O7zfPxugAMECTg4HAAuKMtOsbhUaZi58YAvJdyJfCGwmsiAISw6Ggam6BpWosckU+aoAmHR8an6xrv07tm4IJWF6dvoAFur1voFfutXmcoEDvsCwVsdtUuLw4IdjgCoBc7MgFEo-MieBAiKijsATm9zoFxtT2Ow4ASSeiKZi4k9qeyOZyudyeTzadSXkgXiDFrC4BDrIN5ryZbK5ez+eNRULpl9RSCJQ9pfKdbqFXS1tMVWLRV8IbF8Nq9da5fzCEA))
+Syntax types support generic parameters in the following way ([Example](https://www.typescriptlang.org/play/?moduleResolution=99&module=199&ts=5.8.0-beta#code/JYWwDg9gTgLgBAbzgZQJ4DsYEMAecC+cAZlBCHAOQACAzsOgMYA2WwUA9DKmAKYBGEHOxoZsOCgChQkWIhTYYwBgWKly1OoxZtO3foMkSGEdDXgA1HgxjQ4AXhSjcACgAGAHgAaAGjgBNXwAtAD45CTg4HAAuOB84cLhUGID4iIAvGMD4-FcASgkjEzM4ACEsOhpLa2gae0dMFyQqmygCX1cEBOi4Zuh3AEZfAAZh4O8EpJ6rFvcRuEG4IbGEjKnqqFnh337lnPyJLl5S8uBK6Zq65AUld0OeCCJjit6oGlCIiPZ2ODun05fag5Oh8QaCweCIZCoV8Pt0kN0FpM5qshm0ElCMZisSCYRFJvCYnNJgsUWjseSKeDcXBVgTFr4kb5Vv0COjKezsTD8EA))
 
 ```typescript
-const T0 = Syntax('Argument<0>')
-const T1 = Syntax('Argument<1>')
-const T2 = Syntax('Argument<2>')
-
-const Vector = Syntax({ T0, T1, T2 }, `{
-  x: T0,
-  y: T1,
-  z: T2
+const Vector = Syntax(`<X, Y, Z> { 
+  x: X, 
+  y: Y, 
+  z: Z 
 }`)
 
 const BasisVectors = Syntax({ Vector }, `{
@@ -1386,7 +1375,20 @@ type BasisVectors = Static<typeof BasisVectors>     // type BasisVectors = {
                                                     //   x: { x: 1, y: 0, z: 0 },
                                                     //   y: { x: 0, y: 1, z: 0 },
                                                     //   z: { x: 0, y: 0, z: 1 }
-                                                    // } 
+                                                    // }
+```
+
+<a name='syntax-options'></a>
+
+### Options
+
+Options can be passed via the last parameter
+
+```typescript
+const T = Syntax(`number`, { minimum: 42 })       // const T = {
+                                                  //   type: 'number',
+                                                  //   minimum: 42
+                                                  // }
 ```
 
 <a name='typeregistry'></a>

readme.md

@@ -66,6 +66,46 @@ const Dereference = (context: t.TProperties, key: string): t.TSchema => {
   return key in context ? context[key] : t.Ref(key)
 }
 // ------------------------------------------------------------------
+// GenericArgumentList
+// ------------------------------------------------------------------
+// prettier-ignore
+const GenericArgumentListMapping = (results: unknown[]) => {
+  return (
+    results.length === 3 ? [results[0], ...results[2] as unknown[]] :
+    results.length === 2 ? [results[0]] :
+    results.length === 1 ? [results[0]] :
+    []
+  )
+}
+// prettier-ignore
+const GenericArgumentList = Runtime.Union([
+  Runtime.Tuple([Runtime.Ident(), Runtime.Const(Comma), Runtime.Ref('GenericArgumentList')]),
+  Runtime.Tuple([Runtime.Ident(), Runtime.Const(Comma)]),
+  Runtime.Tuple([Runtime.Ident()]),
+  Runtime.Tuple([]),
+], (results) => GenericArgumentListMapping(results))
+// ------------------------------------------------------------------
+// GenericArguments
+// ------------------------------------------------------------------
+// prettier-ignore
+const GenericArgumentsContext = (args: string[]) => {
+  return args.reduce((result, arg, index) => {
+    return { ...result, [arg]: t.Argument(index) }
+  }, {})
+}
+// prettier-ignore
+const GenericArgumentsMapping = (results: unknown[]) => {
+  return results.length === 3
+    ? GenericArgumentsContext(results[1] as string[])
+    : {}
+}
+// prettier-ignore
+const GenericArguments = Runtime.Tuple([
+  Runtime.Const(LAngle),
+  Runtime.Ref('GenericArgumentList'),
+  Runtime.Const(RAngle),
+], results => GenericArgumentsMapping(results))
+// ------------------------------------------------------------------
 // GenericReference
 // ------------------------------------------------------------------
 function GenericReferenceMapping(results: unknown[], context: t.TProperties) {
@@ -657,11 +697,17 @@ const Date = Runtime.Const('Date', Runtime.As(t.Date()))
 // Uint8Array
 // ------------------------------------------------------------------
 const Uint8Array = Runtime.Const('Uint8Array', Runtime.As(t.Uint8Array()))
+
 // ------------------------------------------------------------------
 // Module
 // ------------------------------------------------------------------
 // prettier-ignore
 export const Module = new Runtime.Module({
+  // ----------------------------------------------------------------
+  // Generic Arguments
+  // ----------------------------------------------------------------
+  GenericArgumentList,
+  GenericArguments,
   // ----------------------------------------------------------------
   // Type Expressions
   // ----------------------------------------------------------------

src/syntax/runtime.ts

@@ -143,6 +143,46 @@ type Dereference<Context extends t.TProperties, Ref extends string> = (
   Ref extends keyof Context ? Context[Ref] : t.TRef<Ref>
 )
 // ------------------------------------------------------------------
+// GenericArgumentList
+// ------------------------------------------------------------------
+// prettier-ignore
+interface GenericArgumentListMapping extends Static.IMapping {
+  output: (
+    this['input'] extends [infer Ident extends string, Comma, infer Rest extends unknown[]] ? [Ident, ...Rest] :
+    this['input'] extends [infer Ident extends string, Comma] ? [Ident] :
+    this['input'] extends [infer Ident extends string] ? [Ident] :
+    []
+  )
+}
+// prettier-ignore
+type GenericArgumentList = Static.Union<[
+  Static.Tuple<[Static.Ident, Static.Const<Comma>, GenericArgumentList]>,
+  Static.Tuple<[Static.Ident, Static.Const<Comma>]>,
+  Static.Tuple<[Static.Ident]>,
+  Static.Tuple<[]>,
+], GenericArgumentListMapping>
+// ------------------------------------------------------------------
+// GenericArguments
+// ------------------------------------------------------------------
+// prettier-ignore
+type GenericArgumentsContext<Args extends string[], Result extends t.TProperties = {}> = (
+  Args extends [...infer Left extends string[], infer Right extends string]
+    ? GenericArgumentsContext<Left, Result & { [_ in Right]: t.TArgument<Left['length']> }>
+    : t.Evaluate<Result>
+)
+// prettier-ignore
+interface GenericArgumentsMapping extends Static.IMapping {
+  output: this['input'] extends [LAngle, infer Args extends string[], RAngle]
+    ? GenericArgumentsContext<Args>
+    : never
+}
+// prettier-ignore
+export type GenericArguments = Static.Tuple<[
+  Static.Const<LAngle>,
+  GenericArgumentList,
+  Static.Const<RAngle>,
+], GenericArgumentsMapping>
+// ------------------------------------------------------------------
 // GenericReference
 // ------------------------------------------------------------------
 // prettier-ignore

src/syntax/static.ts

@@ -26,80 +26,88 @@ THE SOFTWARE.
 
 ---------------------------------------------------------------------------*/
 
-import * as Types from '../type/index'
+import * as t from '../type/index'
 import { Static } from '../parser/index'
 import { Module } from './runtime'
-import { Type } from './static'
+import { Type, GenericArguments } from './static'
 
+// ------------------------------------------------------------------
+// ParseSyntax: Two-Phase Parse
+// ------------------------------------------------------------------
+// prettier-ignore
+type TParseSyntax<Context extends Record<PropertyKey, t.TSchema>, Code extends string> = (
+  Static.Parse<GenericArguments, Code, {}> extends [infer Args extends t.TProperties, infer Rest extends string]
+    ? Static.Parse<Type, Rest, Context & Args>
+    : Static.Parse<Type, Code, Context>
+)
+// prettier-ignore
+function ParseSyntax<Context extends Record<PropertyKey, t.TSchema>, Code extends string>(context: Context, code: Code): [] | [t.TSchema, string] {
+  const results = Module.Parse('GenericArguments', code, {}) // [ArgumentContext, Rest]
+  return (
+    results.length === 2
+      ? Module.Parse('Type', results[1], { ...context, ...results[0] })
+      : Module.Parse('Type', code, context)
+  ) as never
+}
 // ------------------------------------------------------------------
 // NoInfer
 // ------------------------------------------------------------------
-/** Parses a TSchema type from TypeScript syntax but does not infer schematics */
-export function NoInfer<Context extends Record<PropertyKey, Types.TSchema>, Code extends string>(context: Context, code: Code, options?: Types.SchemaOptions): Types.TSchema | undefined
-/** Parses a TSchema type from TypeScript syntax but does not infer schematics */
-export function NoInfer<Code extends string>(code: Code, options?: Types.SchemaOptions): Types.TSchema | undefined
-/** Parses a TSchema type from TypeScript syntax but does not infer schematics */
+/** Parses a TypeScript annotation into a TypeBox type but does not infer schematics */
+export function NoInfer<Context extends Record<PropertyKey, t.TSchema>, Code extends string>(context: Context, code: Code, options?: t.SchemaOptions): t.TSchema
+/** Parses a TypeScript annotation into a TypeBox type but does not infer schematics */
+export function NoInfer<Code extends string>(code: Code, options?: t.SchemaOptions): t.TSchema
+/** Parses a TypeScript annotation into a TypeBox type but does not infer schematics */
 // prettier-ignore
-export function NoInfer(...args: any[]): Types.TSchema | undefined {
+export function NoInfer(...args: any[]): t.TSchema {
   const withContext = typeof args[0] === 'string' ? false : true
   const [context, code, options] = withContext ? [args[0], args[1], args[2] || {}] : [{}, args[0], args[1] || {}]
-  const type = Module.Parse('Type', code, context)[0]
-  return Types.KindGuard.IsSchema(type) 
-    ? Types.CloneType(type, options) 
-    : Types.Never(options)
+  const result = ParseSyntax(context, code)[0]
+  return t.KindGuard.IsSchema(result) 
+    ? t.CloneType(result, options) 
+    : t.Never(options)
 }
-// ------------------------------------------------------------------
-// Syntax
-// ------------------------------------------------------------------
-/** Infers a TSchema type from TypeScript syntax. */
+
+/** Parses a TypeScript annotation into a TypeBox type */
 // prettier-ignore
-export type TSyntax<Context extends Record<PropertyKey, Types.TSchema>, Code extends string> = (
-  Static.Parse<Type, Code, Context> extends [infer Type extends Types.TSchema, string] 
-    ? Type
-    : Types.TNever
+export type TSyntax<Context extends Record<PropertyKey, t.TSchema>, Code extends string> = (
+  TParseSyntax<Context, Code> extends [infer Type extends t.TSchema, string] ? Type : t.TNever
 )
-/** Parses a TSchema type from TypeScript syntax */
-export function Syntax<Context extends Record<PropertyKey, Types.TSchema>, Code extends string>(context: Context, code: Code, options?: Types.SchemaOptions): TSyntax<Context, Code>
-/** Parses a TSchema type from TypeScript syntax */
-export function Syntax<Code extends string>(code: Code, options?: Types.SchemaOptions): TSyntax<{}, Code>
-/** Parses a TSchema type from TypeScript syntax */
+/** Parses a TypeScript annotation into a TypeBox type */
+export function Syntax<Context extends Record<PropertyKey, t.TSchema>, Annotation extends string>(context: Context, annotation: Annotation, options?: t.SchemaOptions): TSyntax<Context, Annotation>
+/** Parses a TypeScript annotation into a TypeBox type */
+export function Syntax<Annotation extends string>(annotation: Annotation, options?: t.SchemaOptions): TSyntax<{}, Annotation>
+/** Parses a TypeScript annotation into a TypeBox type */
 export function Syntax(...args: any[]): never {
   return NoInfer.apply(null, args as never) as never
 }
 // ------------------------------------------------------------------
 // Deprecated
 // ------------------------------------------------------------------
 /**
- * Parses a TSchema type from Syntax.
  * @deprecated Use Syntax() function
  */
-export function Parse<Context extends Record<PropertyKey, Types.TSchema>, Code extends string>(context: Context, code: Code, options?: Types.SchemaOptions): TSyntax<Context, Code>
+export function Parse<Context extends Record<PropertyKey, t.TSchema>, Annotation extends string>(context: Context, annotation: Annotation, options?: t.SchemaOptions): TSyntax<Context, Annotation>
 /**
- * Parses a TSchema type from Syntax.
  * @deprecated Use Syntax() function
  */
-export function Parse<Code extends string>(code: Code, options?: Types.SchemaOptions): TSyntax<{}, Code>
+export function Parse<Annotation extends string>(annotation: Annotation, options?: t.SchemaOptions): TSyntax<{}, Annotation>
 /**
- * Parses a TSchema type from Syntax.
  * @deprecated Use Syntax() function
  */
 export function Parse(...args: any[]): never {
   return NoInfer.apply(null, args as never) as never
 }
 /**
- * Parses a TSchema from TypeScript Syntax
  * @deprecated Use NoInfer() function
  */
-export function ParseOnly<Context extends Record<PropertyKey, Types.TSchema>, Code extends string>(context: Context, code: Code, options?: Types.SchemaOptions): Types.TSchema | undefined
+export function ParseOnly<Context extends Record<PropertyKey, t.TSchema>, Code extends string>(context: Context, code: Code, options?: t.SchemaOptions): t.TSchema | undefined
 /**
- * Parses a TSchema from TypeScript Syntax
  * @deprecated Use NoInfer() function
  */
-export function ParseOnly<Code extends string>(code: Code, options?: Types.SchemaOptions): Types.TSchema | undefined
+export function ParseOnly<Code extends string>(code: Code, options?: t.SchemaOptions): t.TSchema | undefined
 /**
- * Parses a TSchema from TypeScript Syntax
  * @deprecated Use NoInfer() function
  */
-export function ParseOnly(...args: any[]): Types.TSchema | undefined {
+export function ParseOnly(...args: any[]): t.TSchema | undefined {
   return NoInfer.apply(null, args as never) as never
 }