@sinclair/typebox 0.28.8 → 0.28.9

package/package.json

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

package/readme.md

@@ -83,7 +83,7 @@ License MIT
   - [References](#types-references)
   - [Recursive](#types-recursive)
   - [Conditional](#types-conditional)
-  - [Template](#types-template-literal)
+  - [Template Literal](#types-template-literal)
   - [Indexed](#types-indexed)
   - [Rest](#types-rest)
   - [Guards](#types-guards)
@@ -814,11 +814,13 @@ type T2 = Static<typeof T2>                        // type T2 = string
 
 ### Template Literal Types
 
-Template Literal types are supported with `Type.TemplateLiteral`
+TypeBox supports Template Literal types using `Type.TemplateLiteral`. These types can be created using a simple template DSL syntax, however more complex template literals can be created by passing an array of literal and union types. The examples below show the template 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 R = Record<T, string>                           // type R = {
@@ -828,13 +830,17 @@ type R = Record<T, string>                           // type R = {
 
 // TypeBox
 
-const T = Type.TemplateLiteral([                     // const T = {
-  Type.Literal('option'),                            //   pattern: '^option(A|B)$',
-  Type.Union([                                       //   type: 'string'
-    Type.Literal('A'),                               // }
-    Type.Literal('B')
-  ])
-])
+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)$',
+                                                     //   type: 'string'
+                                                     // }
 
 const R = Type.Record(T, Type.String())              // const R = {
                                                      //   type: 'object',
@@ -848,37 +854,48 @@ const R = Type.Record(T, Type.String())              // const R = {
                                                      //     }
                                                      //   }
                                                      // }
-
-type T = Static<typeof T>                            // type T = 'optionA' | 'optionB'
-
-type R = Static<typeof R>                            // type R = {
-                                                     //   optionA: string
-                                                     //   optionB: string
-                                                     // }
 ```
 
 <a name='types-indexed'></a>
 
 ### Indexed Access Types
 
-Indexed Access types are supported with `Type.Index`
+TypeBox supports Indexed Access types using `Type.Index`. This feature provides a consistent way to access property types without having to extract them from the underlying schema representation. Indexed accessors are supported for object and tuples, as well as nested union and intersect types.
 
 ```typescript
-const T = Type.Object({                              // type T = {
-  x: Type.Number(),                                  //   x: number
-  y: Type.String(),                                  //   y: string
-  z: Type.Boolean()                                  //   z: boolean
-})                                                   // }
+const T = Type.Object({                              // const T = {
+  x: Type.Number(),                                  //   type: 'object',
+  y: Type.String(),                                  //   required: ['x', 'y', 'z'],
+  z: Type.Boolean()                                  //   properties: {
+})                                                   //     x: { type: 'number' },
+                                                     //     y: { type: 'string' },
+                                                     //     z: { type: 'string' },
+                                                     //   }
+                                                     // }
 
-const A = Type.Index(T, ['x'])                       // type A = T['x']
+const A = Type.Index(T, ['x'])                       // const A = { type: 'number' }
 
-const B = Type.Index(T, Type.KeyOf(T))               // type B = T[keyof T]
+const B = Type.Index(T, ['x', 'y'])                  // const B = { 
+                                                     //   anyOf: [
+                                                     //     { type: 'number' },  
+                                                     //     { type: 'string' }
+                                                     //   ]
+                                                     // }
+
+const C = Type.Index(T, Type.KeyOf(T))               // const C = { 
+                                                     //   anyOf: [
+                                                     //     { type: 'number' },  
+                                                     //     { type: 'string' },
+                                                     //     { type: 'boolean' }
+                                                     //   ]
+                                                     // }
 ```
+
 <a name='types-rest'></a>
 
 ### Rest Types
 
-Rest parameters are supported with `Type.Rest`. This function is used to extract interior arrays from tuples to allow them to compose with the JavaScript spread operator `...`. This type can be used for tuple concatination and variadic function composition.
+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 concatination as well as for variadic functions.
 
 ```typescript
 // TypeScript

package/typebox.d.ts

@@ -16,6 +16,7 @@ export type UnionLast<U> = UnionToIntersect<U extends unknown ? (x: U) => 0 : ne
 export type UnionToTuple<U, L = UnionLast<U>> = [U] extends [never] ? [] : [...UnionToTuple<Exclude<U, L>>, L];
 export type Discard<T extends unknown[], D extends unknown> = T extends [infer L, ...infer R] ? (L extends D ? Discard<R, D> : [L, ...Discard<R, D>]) : [];
 export type Flat<T> = T extends [] ? [] : T extends [infer L] ? [...Flat<L>] : T extends [infer L, ...infer R] ? [...Flat<L>, ...Flat<R>] : [T];
+export type Trim<T> = T extends `${' '}${infer U}` ? Trim<U> : T extends `${infer U}${' '}` ? Trim<U> : T;
 export type Assert<T, E> = T extends E ? T : never;
 export type Evaluate<T> = T extends infer O ? {
     [K in keyof O]: O[K];
@@ -358,6 +359,13 @@ export interface TSymbol extends TSchema, SchemaOptions {
     type: 'null';
     typeOf: 'Symbol';
 }
+export type TTemplateLiteralDslParserUnionLiteral<T extends string> = T extends `${infer L}|${infer R}` ? [TLiteral<Trim<L>>, ...TTemplateLiteralDslParserUnionLiteral<R>] : T extends `${infer L}` ? [TLiteral<Trim<L>>] : [
+];
+export type TTemplateLiteralDslParserUnion<T extends string> = UnionType<TTemplateLiteralDslParserUnionLiteral<T>>;
+export type TTemplateLiteralDslParserTerminal<T extends string> = T extends 'boolean' ? TBoolean : T extends 'bigint' ? TBigInt : T extends 'number' ? TNumber : T extends 'string' ? TString : TTemplateLiteralDslParserUnion<T>;
+export type TTemplateLiteralDslParserTemplate<T extends string> = T extends `{${infer L}}${infer R}` ? [TTemplateLiteralDslParserTerminal<L>, ...TTemplateLiteralDslParserTemplate<R>] : T extends `${infer L}$${infer R}` ? [TLiteral<L>, ...TTemplateLiteralDslParserTemplate<R>] : T extends `${infer L}` ? [TLiteral<L>] : [
+];
+export type TTemplateLiteralDslParser<T extends string> = Ensure<TTemplateLiteral<Assert<TTemplateLiteralDslParserTemplate<T>, TTemplateLiteralKind[]>>>;
 export type IsTemplateLiteralFiniteCheck<T> = T extends TTemplateLiteral<infer U> ? IsTemplateLiteralFiniteArray<Assert<U, TTemplateLiteralKind[]>> : T extends TUnion<infer U> ? IsTemplateLiteralFiniteArray<Assert<U, TTemplateLiteralKind[]>> : T extends TString ? false : T extends TBoolean ? false : T extends TNumber ? false : T extends TInteger ? false : T extends TBigInt ? false : T extends TLiteral ? true : false;
 export type IsTemplateLiteralFiniteArray<T extends TTemplateLiteralKind[]> = T extends [infer L, ...infer R] ? IsTemplateLiteralFiniteCheck<L> extends false ? false : IsTemplateLiteralFiniteArray<Assert<R, TTemplateLiteralKind[]>> : true;
 export type IsTemplateLiteralFinite<T> = T extends TTemplateLiteral<infer U> ? IsTemplateLiteralFiniteArray<U> : false;
@@ -621,6 +629,9 @@ export declare namespace TemplateLiteralFinite {
 export declare namespace TemplateLiteralGenerator {
     function Generate(expression: TemplateLiteralParser.Expression): IterableIterator<string>;
 }
+export declare namespace TemplateLiteralDslParser {
+    function Parse(template_dsl: string): TTemplateLiteralKind[];
+}
 export declare class TypeBuilder {
     /** `[Utility]` Creates a schema without `static` and `params` types */
     protected Create<T>(schema: Omit<T, 'static' | 'params'>): T;
@@ -717,6 +728,8 @@ export declare class StandardTypeBuilder extends TypeBuilder {
     Rest<T extends TSchema>(schema: T): TRest<T>;
     /** `[Standard]` Creates a String type */
     String(options?: StringOptions): TString;
+    /** `[Experimental]` Creates a template literal type from dsl string */
+    TemplateLiteral<T extends string>(dsl: T, options?: SchemaOptions): TTemplateLiteralDslParser<T>;
     /** `[Standard]` Creates a template literal type */
     TemplateLiteral<T extends TTemplateLiteralKind[]>(kinds: [...T], options?: SchemaOptions): TTemplateLiteral<T>;
     /** `[Standard]` Creates a Tuple type */

package/typebox.js

@@ -27,7 +27,7 @@ THE SOFTWARE.
 
 ---------------------------------------------------------------------------*/
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Type = exports.StandardType = exports.ExtendedTypeBuilder = exports.StandardTypeBuilder = exports.TypeBuilder = exports.TemplateLiteralGenerator = exports.TemplateLiteralFinite = exports.TemplateLiteralParser = exports.TemplateLiteralParserError = exports.TemplateLiteralResolver = exports.TemplateLiteralPattern = exports.UnionResolver = exports.KeyArrayResolver = exports.KeyResolver = exports.ObjectMap = exports.IndexedAccessor = exports.TypeClone = exports.TypeExtends = exports.TypeExtendsResult = exports.ExtendsUndefined = exports.TypeGuard = exports.TypeGuardUnknownTypeError = exports.FormatRegistry = exports.TypeRegistry = exports.PatternStringExact = exports.PatternNumberExact = exports.PatternBooleanExact = exports.PatternString = exports.PatternNumber = exports.PatternBoolean = exports.Kind = exports.Hint = exports.Modifier = void 0;
+exports.Type = exports.StandardType = exports.ExtendedTypeBuilder = exports.StandardTypeBuilder = exports.TypeBuilder = exports.TemplateLiteralDslParser = exports.TemplateLiteralGenerator = exports.TemplateLiteralFinite = exports.TemplateLiteralParser = exports.TemplateLiteralParserError = exports.TemplateLiteralResolver = exports.TemplateLiteralPattern = exports.UnionResolver = exports.KeyArrayResolver = exports.KeyResolver = exports.ObjectMap = exports.IndexedAccessor = exports.TypeClone = exports.TypeExtends = exports.TypeExtendsResult = exports.ExtendsUndefined = exports.TypeGuard = exports.TypeGuardUnknownTypeError = exports.FormatRegistry = exports.TypeRegistry = exports.PatternStringExact = exports.PatternNumberExact = exports.PatternBooleanExact = exports.PatternString = exports.PatternNumber = exports.PatternBoolean = exports.Kind = exports.Hint = exports.Modifier = void 0;
 // --------------------------------------------------------------------------
 // Symbols
 // --------------------------------------------------------------------------
@@ -1847,6 +1847,54 @@ var TemplateLiteralGenerator;
     }
     TemplateLiteralGenerator.Generate = Generate;
 })(TemplateLiteralGenerator = exports.TemplateLiteralGenerator || (exports.TemplateLiteralGenerator = {}));
+// ---------------------------------------------------------------------
+// TemplateLiteralDslParser
+// ---------------------------------------------------------------------
+var TemplateLiteralDslParser;
+(function (TemplateLiteralDslParser) {
+    function* ParseUnion(template) {
+        const trim = template.trim().replace(/"|'/g, '');
+        if (trim === 'boolean')
+            return yield exports.Type.Boolean();
+        if (trim === 'number')
+            return yield exports.Type.Number();
+        if (trim === 'bigint')
+            return yield exports.Type.BigInt();
+        if (trim === 'string')
+            return yield exports.Type.String();
+        const literals = trim.split('|').map((literal) => exports.Type.Literal(literal.trim()));
+        return yield literals.length === 0 ? exports.Type.Never() : literals.length === 1 ? literals[0] : exports.Type.Union(literals);
+    }
+    function* ParseTerminal(template) {
+        if (template[1] !== '{') {
+            const L = exports.Type.Literal('$');
+            const R = ParseLiteral(template.slice(1));
+            return yield* [L, ...R];
+        }
+        for (let i = 2; i < template.length; i++) {
+            if (template[i] === '}') {
+                const L = ParseUnion(template.slice(2, i));
+                const R = ParseLiteral(template.slice(i + 1));
+                return yield* [...L, ...R];
+            }
+        }
+        yield exports.Type.Literal(template);
+    }
+    function* ParseLiteral(template) {
+        for (let i = 0; i < template.length; i++) {
+            if (template[i] === '$') {
+                const L = exports.Type.Literal(template.slice(0, i));
+                const R = ParseTerminal(template.slice(i));
+                return yield* [L, ...R];
+            }
+        }
+        yield exports.Type.Literal(template);
+    }
+    function Parse(template_dsl) {
+        return [...ParseLiteral(template_dsl)];
+    }
+    TemplateLiteralDslParser.Parse = Parse;
+})(TemplateLiteralDslParser = exports.TemplateLiteralDslParser || (exports.TemplateLiteralDslParser = {}));
 // --------------------------------------------------------------------------
 // TypeOrdinal: Used for auto $id generation
 // --------------------------------------------------------------------------
@@ -2198,8 +2246,11 @@ class StandardTypeBuilder extends TypeBuilder {
         return this.Create({ ...options, [exports.Kind]: 'String', type: 'string' });
     }
     /** `[Standard]` Creates a template literal type */
-    TemplateLiteral(kinds, options = {}) {
-        const pattern = TemplateLiteralPattern.Create(kinds);
+    TemplateLiteral(unresolved, options = {}) {
+        // prettier-ignore
+        const pattern = (typeof unresolved === 'string')
+            ? TemplateLiteralPattern.Create(TemplateLiteralDslParser.Parse(unresolved))
+            : TemplateLiteralPattern.Create(unresolved);
         return this.Create({ ...options, [exports.Kind]: 'TemplateLiteral', type: 'string', pattern });
     }
     /** `[Standard]` Creates a Tuple type */