@sinclair/typebox 0.32.0-dev-12 → 0.32.0-dev-14

package/readme.md

@@ -67,15 +67,17 @@ License MIT
   - [JavaScript](#types-javascript)
   - [Options](#types-options)
   - [Properties](#types-properties)
+  - [Imports](#types-imports)
   - [Generics](#types-generics)
   - [References](#types-references)
   - [Recursive](#types-recursive)
   - [Conditional](#types-conditional)
+  - [Mapped](#types-mapped)
   - [Template Literal](#types-templateliteral)
   - [Indexed](#types-indexed)
-  - [Rest](#types-rest)
-  - [Transform](#types-transform)
   - [Intrinsic](#types-intrinsic)
+  - [Transform](#types-transform)
+  - [Rest](#types-rest)
   - [Guard](#types-guard)
   - [Unsafe](#types-unsafe)
   - [Strict](#types-strict)
@@ -375,8 +377,8 @@ The following table lists the supported Json types. These types are fully compat
 ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 │ const T = Type.Extends(        │ type T =                    │ const T = {                    │
 │   Type.String(),               │  string extends number      │   const: false,                │
-│   Type.Number(),               │  true : false               │   type: 'boolean'              │
-│   Type.Literal(true),          │                             │ }                              │
+│   Type.Number(),               │    ? true                   │   type: 'boolean'              │
+│   Type.Literal(true),          │    : false                  │ }                              │
 │   Type.Literal(false)          │                             │                                │
 │ )                              │                             │                                │
 │                                │                             │                                │
@@ -399,6 +401,20 @@ The following table lists the supported Json types. These types are fully compat
 │ )                              │                             │                                │
 │                                │                             │                                │
 ├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
+│ const T = Type.Mapped(         │ type T = {                  │ const T = {                    │
+│   Type.Union([                 │   [_ in 'x' | 'y'] : number │   type: 'object',              │
+│     Type.Literal('x'),         │ }                           │   required: ['x', 'y'],        │
+│     Type.Literal('y')          │                             │   properties: {                │
+│   ]),                          │                             │     x: {                       │
+│   () => Type.Number()          │                             │       type: 'number'           │
+│ )                              │                             │     },                         │
+│                                │                             │     y: {                       │
+│                                │                             │       type: 'number'           │
+│                                │                             │     }                          │
+│                                │                             │   }                            │
+│                                │                             │ }                              │
+│                                │                             │                                │
+├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
 │ const U = Type.Union([         │ type U = 'open' | 'close'   │ const T = {                    │
 │   Type.Literal('open'),        │                             │   type: 'string',              │
 │   Type.Literal('close')        │ type T = `on${U}`           │   pattern: '^on(open|close)$'  │
@@ -700,6 +716,32 @@ Object properties can be modified with Readonly and Optional. The following tabl
 │                                │                             │                                │
 └────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘
 ```
+
+<a name='types-imports'></a>
+
+### Import Types
+
+TypeBox supports a modular type system. For most users, importing the full type system is generally recommended as it offers the best overall user experience as well as enabling easier discovery of available types.
+
+```typescript
+import { Type } from '@sinclair/typebox'             // 34.9 kb minified
+
+const T = Type.Object({
+  x: Type.Number(),
+  y: Type.Number()
+})
+```
+For developers building for resource constrained environments, selective imports can allow bundle optimizers to tree shake unused types. This can dramatically reduce bundle output sizes.
+```typescript
+import { Object, Number } from '@sinclair/typebox'   // 6.4 kb minified
+
+const T = Object({
+  x: Number(),
+  y: Number()
+})
+```
+For additional information on bundle optimizations, refer to the documentation provided by your bundler of choice.
+
 <a name='types-generics'></a>
 
 ### Generic Types
@@ -848,7 +890,7 @@ function test(node: Node) {
 
 ### Conditional Types
 
-TypeBox supports runtime conditional types with Extends. This type performs a structural assignability check for the first two arguments and will infer one of the second two arguments based on the result. The Extends type is designed to match the assignability rules of TypeScript conditional types. The conditional derived types Exclude and Extract are also supported.
+TypeBox supports runtime Conditional Types with Type.Extends. This type runs a structural assignability check against the first and second arguments and will return either the third (`true`) or fourth (`false`) argument based on the result. Additionally, the conditional backed types Exclude and Extract are also supported. The following shows both TypeScript and TypeBox examples of this feature.
 
 ```typescript
 // Extends
@@ -889,11 +931,37 @@ const T = Type.Exclude(                              // const T: TUnion<[
 )
 ```
 
+<a name='types-mapped'></a>
+
+### Mapped Types
+
+TypeBox supports Mapped Types with Type.Mapped. This type accepts a union set of property keys as the first argument, and a type mapping function which accepts each key (`K`) as the second. This type can be used with Conditional and Indexed Access types to allow for generalized property remapping irrespective of property type. The following example remaps each property of `T` to be `T[K] | null`.
+
+```typescript
+const T = Type.Object({                              // const T: TObject<{
+  x: Type.Number(),                                  //   x: TNumber,
+  y: Type.String(),                                  //   y: TString,
+  z: Type.Boolean()                                  //   z: TBoolean
+})                                                   // }>
+
+const M = Type.Mapped(Type.KeyOf(T), K => {          // type M = {
+  return Type.Union([                                //   [K in keyof T]: T[K] | null
+    Type.Index(T, K),                                // }
+    Type.Null()                                      //
+  ])                                                 // ... runtime mapped as
+})                                                   //
+                                                     // const M: TObject<{
+                                                     //   x: TUnion<[TNumber, TNull]>,
+                                                     //   y: TUnion<[TString, TNull]>,
+                                                     //   z: TUnion<[TBoolean, TNull]>
+                                                     // }>
+```
+
 <a name='types-templateliteral'></a>
 
 ### Template Literal Types
 
-TypeBox supports template literal types with TemplateLiteral. This type can be created using a syntax similar to the TypeScript template literal syntax. TypeBox encodes template literals as regular expression string patterns which enable the template be checked via Json Schema. It also supports regular expression parsing, enabling template patterns to be used for generative types. The following shows both TypeScript and TypeBox usage.
+TypeBox supports Template Literal types with Type.TemplateLiteral. This type can be created using a syntax similar to the TypeScript Template Literal syntax. TypeBox encodes Template Literals as regular expression string patterns which enables the template to be checked by Json Schema validators. This type also supports regular expression parsing, enabling template patterns to be used for generative types. The following shows both TypeScript and TypeBox usage.
 
 ```typescript
 // TypeScript
@@ -928,7 +996,7 @@ const R = Type.Record(K, Type.String())              // const R: TObject<{
 
 ### Indexed Access Types
 
-TypeBox supports Indexed Access Types with Index. This type enables uniform access to interior property and array element types without having to extract them from the underlying schema representation. This type is supported for Object, Array, Tuple, Union and Intersect types.
+TypeBox supports Indexed Access Types with Type.Index. This type enables uniform access to interior property and array element types without having to extract them from the underlying schema representation. This type is supported for Object, Array, Tuple, Union and Intersect types.
 
 ```typescript
 const T = Type.Object({                              // const T: TObject<{
@@ -951,23 +1019,35 @@ const C = Type.Index(T, Type.KeyOf(T))               // const C: TUnion<[
                                                      // ]>
 ```
 
-<a name='types-rest'></a>
+<a name='types-intrinsic'></a>
 
-### Rest Types
+### Intrinsic Types
 
-TypeBox provides the Rest type to uniformly extract variadic tuples from Intersect, Union and Tuple types. This type can be useful to remap variadic types into different forms. The following uses Rest to remap a Tuple into a Union.
+TypeBox supports the TypeScript Intrinsic String Manipulation types Uppercase, Lowercase, Capitalize and Uncapitalize. These types can be used to remap String Literal, Template Literal and Union of Literal types.
 
 ```typescript
-const T = Type.Tuple([                               // const T: TTuple<[
-  Type.String(),                                     //   TString,
-  Type.Number()                                      //   TNumber
-])                                                   // ]>
+// TypeScript
 
-const R = Type.Rest(T)                               // const R: [TString, TNumber]
+type A = Capitalize<'hello'>                         // type A = 'Hello'
+type B = Capitalize<'hello' | 'world'>               // type C = 'Hello' | 'World'
+type C = Capitalize<`hello${1|2|3}`>                 // type B = 'Hello1' | 'Hello2' | 'Hello3'
 
-const U = Type.Union(R)                              // const T: TUnion<[
-                                                     //   TString,
-                                                     //   TNumber
+// TypeBox
+
+const A = Type.Capitalize(Type.Literal('hello'))     // const A: TLiteral<'Hello'>
+
+const B = Type.Capitalize(Type.Union([               // const B: TUnion<[
+  Type.Literal('hello'),                             //   TLiteral<'Hello'>,
+  Type.Literal('world')                              //   TLiteral<'World'>
+]))                                                  // ]>
+
+const C = Type.Capitalize(                           // const C: TTemplateLiteral<[
+  Type.TemplateLiteral('hello${1|2|3}')              //   TLiteral<'Hello'>,
+)                                                    //   TUnion<[
+                                                     //     TLiteral<'1'>,
+                                                     //     TLiteral<'2'>,
+                                                     //     TLiteral<'3'>
+                                                     //   ]>
                                                      // ]>
 ```
 
@@ -1000,35 +1080,23 @@ type E = StaticEncode<typeof T>                      // type E = Array<number>
 type T = Static<typeof T>                            // type T = Array<number>
 ```
 
-<a name='types-intrinsic'></a>
+<a name='types-rest'></a>
 
-### Intrinsic Types
+### Rest Types
 
-TypeBox supports the TypeScript Intrinsic String Manipulation types Uppercase, Lowercase, Capitalize and Uncapitalize. These types can be used to remap String Literal, TemplateLiteral and Union types.
+TypeBox provides the Rest type to uniformly extract variadic tuples from Intersect, Union and Tuple types. This type can be useful to remap variadic types into different forms. The following uses Rest to remap a Tuple into a Union.
 
 ```typescript
-// TypeScript
-
-type A = Capitalize<'hello'>                         // type A = 'Hello'
-type B = Capitalize<'hello' | 'world'>               // type C = 'Hello' | 'World'
-type C = Capitalize<`hello${1|2|3}`>                 // type B = 'Hello1' | 'Hello2' | 'Hello3'
-
-// TypeBox
-
-const A = Type.Capitalize(Type.Literal('hello'))     // const A: TLiteral<'Hello'>
+const T = Type.Tuple([                               // const T: TTuple<[
+  Type.String(),                                     //   TString,
+  Type.Number()                                      //   TNumber
+])                                                   // ]>
 
-const B = Type.Capitalize(Type.Union([               // const B: TUnion<[
-  Type.Literal('hello'),                             //   TLiteral<'Hello'>,
-  Type.Literal('world')                              //   TLiteral<'World'>
-]))                                                  // ]>
+const R = Type.Rest(T)                               // const R: [TString, TNumber]
 
-const C = Type.Capitalize(                           // const C: TTemplateLiteral<[
-  Type.TemplateLiteral('hello${1|2|3}')              //   TLiteral<'Hello'>,
-)                                                    //   TUnion<[
-                                                     //     TLiteral<'1'>,
-                                                     //     TLiteral<'2'>,
-                                                     //     TLiteral<'3'>
-                                                     //   ]>
+const U = Type.Union(R)                              // const T: TUnion<[
+                                                     //   TString,
+                                                     //   TNumber
                                                      // ]>
 ```
 
@@ -1751,12 +1819,12 @@ The following table lists esbuild compiled and minified sizes for each TypeBox m
 ┌──────────────────────┬────────────┬────────────┬─────────────┐
 │       (index)        │  Compiled  │  Minified  │ Compression │
 ├──────────────────────┼────────────┼────────────┼─────────────┤
-│ typebox/compiler     │ '109.3 kb' │ ' 48.5 kb' │  '2.25 x'   │
-│ typebox/errors       │ ' 54.8 kb' │ ' 24.9 kb' │  '2.20 x'   │
-│ typebox/system       │ ' 12.1 kb' │ '  6.1 kb' │  '1.98 x'   │
-│ typebox/type         │ ' 77.8 kb' │ ' 32.8 kb' │  '2.37 x'   │
-│ typebox/value        │ '143.7 kb' │ ' 61.2 kb' │  '2.35 x'   │
-│ typebox              │ ' 77.9 kb' │ ' 32.8 kb' │  '2.37 x'   │
+│ typebox/compiler     │ '109.2 kb' │ ' 48.6 kb' │  '2.25 x'   │
+│ typebox/errors       │ ' 55.0 kb' │ ' 25.1 kb' │  '2.19 x'   │
+│ typebox/system       │ '  4.6 kb' │ '  2.0 kb' │  '2.31 x'   │
+│ typebox/type         │ ' 82.9 kb' │ ' 34.9 kb' │  '2.38 x'   │
+│ typebox/value        │ '144.2 kb' │ ' 61.5 kb' │  '2.34 x'   │
+│ typebox              │ ' 82.9 kb' │ ' 34.9 kb' │  '2.37 x'   │
 └──────────────────────┴────────────┴────────────┴─────────────┘
 ```
 

package/build/import/type/extends/extends-mapped.d.mts

@@ -1,17 +0,0 @@
-import type { TSchema } from '../schema/index.mjs';
-import type { TProperties } from '../object/index.mjs';
-import type { Assert } from '../helpers/index.mjs';
-import { type TMappedResult, type TMappedKey } from '../mapped/index.mjs';
-import { TLiteral, TLiteralValue } from '../literal/index.mjs';
-import { type TExtends } from './extends.mjs';
-type MappedExtendsPropertyKey<K extends PropertyKey, U extends TSchema, L extends TSchema, R extends TSchema> = {
-    [_ in K]: TExtends<TLiteral<Assert<K, TLiteralValue>>, U, L, R>;
-};
-declare function MappedExtendsPropertyKey<K extends PropertyKey, U extends TSchema, L extends TSchema, R extends TSchema>(K: K, U: U, L: L, R: R): MappedExtendsPropertyKey<K, U, L, R>;
-type MappedExtendsPropertyKeys<K extends PropertyKey[], U extends TSchema, L extends TSchema, R extends TSchema> = (K extends [infer LK extends PropertyKey, ...infer RK extends PropertyKey[]] ? MappedExtendsPropertyKey<LK, U, L, R> & MappedExtendsPropertyKeys<RK, U, L, R> : {});
-declare function MappedExtendsPropertyKeys<K extends PropertyKey[], U extends TSchema, L extends TSchema, R extends TSchema>(K: [...K], U: U, L: L, R: R): MappedExtendsPropertyKeys<K, U, L, R>;
-type MappedExtendsProperties<K extends TMappedKey, U extends TSchema, L extends TSchema, R extends TSchema> = (MappedExtendsPropertyKeys<K['keys'], U, L, R>);
-declare function MappedExtendsProperties<K extends TMappedKey, U extends TSchema, L extends TSchema, R extends TSchema>(K: K, U: U, L: L, R: R): MappedExtendsProperties<K, U, L, R>;
-export type MappedExtends<T extends TMappedKey, U extends TSchema, L extends TSchema, R extends TSchema, P extends TProperties = MappedExtendsProperties<T, U, L, R>> = (TMappedResult<P>);
-export declare function MappedExtends<T extends TMappedKey, U extends TSchema, L extends TSchema, R extends TSchema, P extends TProperties = MappedExtendsProperties<T, U, L, R>>(T: T, U: U, L: L, R: R): TMappedResult<P>;
-export {};

package/build/import/type/extends/extends-mapped.mjs

@@ -1,21 +0,0 @@
-import { MappedResult } from '../mapped/index.mjs';
-import { Literal } from '../literal/index.mjs';
-import { Extends } from './extends.mjs';
-function MappedExtendsPropertyKey(K, U, L, R) {
-    return {
-        [K]: Extends(Literal(K), U, L, R)
-    };
-}
-function MappedExtendsPropertyKeys(K, U, L, R) {
-    const [LK, ...RK] = K;
-    return (K.length > 0
-        ? { ...MappedExtendsPropertyKey(LK, U, L, R), ...MappedExtendsPropertyKeys(RK, U, L, R) }
-        : {});
-}
-function MappedExtendsProperties(K, U, L, R) {
-    return MappedExtendsPropertyKeys(K.keys, U, L, R);
-}
-export function MappedExtends(T, U, L, R) {
-    const P = MappedExtendsProperties(T, U, L, R);
-    return MappedResult(P);
-}

package/build/require/type/extends/extends-mapped.d.ts

@@ -1,17 +0,0 @@
-import type { TSchema } from '../schema/index';
-import type { TProperties } from '../object/index';
-import type { Assert } from '../helpers/index';
-import { type TMappedResult, type TMappedKey } from '../mapped/index';
-import { TLiteral, TLiteralValue } from '../literal/index';
-import { type TExtends } from './extends';
-type MappedExtendsPropertyKey<K extends PropertyKey, U extends TSchema, L extends TSchema, R extends TSchema> = {
-    [_ in K]: TExtends<TLiteral<Assert<K, TLiteralValue>>, U, L, R>;
-};
-declare function MappedExtendsPropertyKey<K extends PropertyKey, U extends TSchema, L extends TSchema, R extends TSchema>(K: K, U: U, L: L, R: R): MappedExtendsPropertyKey<K, U, L, R>;
-type MappedExtendsPropertyKeys<K extends PropertyKey[], U extends TSchema, L extends TSchema, R extends TSchema> = (K extends [infer LK extends PropertyKey, ...infer RK extends PropertyKey[]] ? MappedExtendsPropertyKey<LK, U, L, R> & MappedExtendsPropertyKeys<RK, U, L, R> : {});
-declare function MappedExtendsPropertyKeys<K extends PropertyKey[], U extends TSchema, L extends TSchema, R extends TSchema>(K: [...K], U: U, L: L, R: R): MappedExtendsPropertyKeys<K, U, L, R>;
-type MappedExtendsProperties<K extends TMappedKey, U extends TSchema, L extends TSchema, R extends TSchema> = (MappedExtendsPropertyKeys<K['keys'], U, L, R>);
-declare function MappedExtendsProperties<K extends TMappedKey, U extends TSchema, L extends TSchema, R extends TSchema>(K: K, U: U, L: L, R: R): MappedExtendsProperties<K, U, L, R>;
-export type MappedExtends<T extends TMappedKey, U extends TSchema, L extends TSchema, R extends TSchema, P extends TProperties = MappedExtendsProperties<T, U, L, R>> = (TMappedResult<P>);
-export declare function MappedExtends<T extends TMappedKey, U extends TSchema, L extends TSchema, R extends TSchema, P extends TProperties = MappedExtendsProperties<T, U, L, R>>(T: T, U: U, L: L, R: R): TMappedResult<P>;
-export {};

package/build/require/type/extends/extends-mapped.js

@@ -1,25 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MappedExtends = void 0;
-const index_1 = require("../mapped/index");
-const index_2 = require("../literal/index");
-const extends_1 = require("./extends");
-function MappedExtendsPropertyKey(K, U, L, R) {
-    return {
-        [K]: (0, extends_1.Extends)((0, index_2.Literal)(K), U, L, R)
-    };
-}
-function MappedExtendsPropertyKeys(K, U, L, R) {
-    const [LK, ...RK] = K;
-    return (K.length > 0
-        ? { ...MappedExtendsPropertyKey(LK, U, L, R), ...MappedExtendsPropertyKeys(RK, U, L, R) }
-        : {});
-}
-function MappedExtendsProperties(K, U, L, R) {
-    return MappedExtendsPropertyKeys(K.keys, U, L, R);
-}
-function MappedExtends(T, U, L, R) {
-    const P = MappedExtendsProperties(T, U, L, R);
-    return (0, index_1.MappedResult)(P);
-}
-exports.MappedExtends = MappedExtends;