Skip to content

Commit 929efd2

Browse files
sinclairzx81sinclairzx81
committed
Documentation
1 parent 4e97af2 commit 929efd2

File tree

1 file changed

+79
-64
lines changed

1 file changed

+79
-64
lines changed

‎readme.md

+79-64
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,6 @@ License MIT
6464
- [Types](#types)
6565
- [Json](#types-json)
6666
- [JavaScript](#types-javascript)
67-
- [Import](#types-import)
6867
- [Options](#types-options)
6968
- [Properties](#types-properties)
7069
- [Generics](#types-generics)
@@ -97,16 +96,18 @@ License MIT
9796
- [Mutate](#values-mutate)
9897
- [Pointer](#values-pointer)
9998
- [Syntax](#syntax)
100-
- [Type](#syntax-type)
101-
- [Options](#syntax-options)
99+
- [Create](#syntax-create)
102100
- [Parameters](#syntax-parameters)
101+
- [Options](#syntax-options)
103102
- [Generics](#syntax-generics)
104103
- [TypeRegistry](#typeregistry)
105104
- [Type](#typeregistry-type)
106105
- [Format](#typeregistry-format)
107106
- [TypeCheck](#typecheck)
108107
- [Ajv](#typecheck-ajv)
109108
- [TypeCompiler](#typecheck-typecompiler)
109+
- [TypeMap](#typemap)
110+
- [Usage](#typemap-usage)
110111
- [TypeSystem](#typesystem)
111112
- [Policies](#typesystem-policies)
112113
- [Error Function](#error-function)
@@ -638,22 +639,6 @@ TypeBox provides an extended type set that can be used to create schematics for
638639
└────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘
639640
```
640641
641-
<a name='types-import'></a>
642-
643-
### Import
644-
645-
Import the Type namespace to bring in the full TypeBox type system. This is recommended for most users.
646-
647-
```typescript
648-
import { Type, type Static } from '@sinclair/typebox'
649-
```
650-
651-
You can also selectively import types. This enables modern bundlers to tree shake for unused types.
652-
653-
```typescript
654-
import { Object, Number, String, Boolean, type Static } from '@sinclair/typebox'
655-
```
656-
657642
<a name='types-options'></a>
658643
659644
### Options
@@ -741,22 +726,6 @@ const Nullable = <T extends TSchema>(T: T) => { // type Nullable<T> = T | nu
741726
const T = Nullable(Type.String()) // type T = Nullable<string>
742727
```
743728
744-
Generic types can also be created with Argument types
745-
746-
```typescript
747-
const Vector = Type.Object({ // type Vector<A_0, A_1, A_2> = {
748-
x: Type.Argument(0), // x: A_0,
749-
y: Type.Argument(1), // y: A_1,
750-
z: Type.Argument(2), // z: A_2
751-
}) // }
752-
753-
const T = Type.Instantiate(Vector, [ // type T = Vector<
754-
Type.Boolean(), // boolean,
755-
Type.Number(), // number,
756-
Type.String() // string
757-
]) // >
758-
```
759-
760729
<a name='types-recursive'></a>
761730
762731
### Recursive Types
@@ -1337,30 +1306,50 @@ ValuePointer.Set(A, '/z', 1) // A' = { x: 1, y: 1, z: 1
13371306
13381307
## Syntax Types
13391308
1340-
TypeBox provides optional support for runtime and type level parsing from TypeScript syntax.
1309+
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.
1310+
1311+
Syntax types are available via optional import.
13411312
13421313
```typescript
13431314
import { Syntax } from '@sinclair/typebox/syntax'
13441315
```
13451316
1346-
<a name='syntax-type'></a>
1317+
<a name='syntax-create'></a>
1318+
1319+
### Create
1320+
1321+
Use the Syntax function to create TypeBox types from TypeScript syntax
13471322
1348-
### Type
1323+
```typescript
1324+
const T = Syntax(`{ x: number, y: number }`) // const T: TObject<{
1325+
// x: TNumber,
1326+
// y: TNumber
1327+
// }>
1328+
```
1329+
1330+
<a name="syntax-parameters"></a>
1331+
1332+
### Parameters
13491333
1350-
Use the Syntax function to create TypeBox type from TypeScript syntax.
1334+
Syntax types can be parameterized to receive exterior types.
13511335
13521336
```typescript
13531337
const T = Syntax(`{ x: number, y: number }`) // const T: TObject<{
1354-
// x: TNumber
1338+
// x: TNumber,
13551339
// y: TNumber
13561340
// }>
1341+
1342+
const S = Syntax({ T }, `Partial<T>`) // const S: TObject<{
1343+
// x: TOptional<TNumber>,
1344+
// y: TOptional<TNumber>
1345+
// }>
13571346
```
13581347
13591348
<a name='syntax-options'></a>
13601349
13611350
### Options
13621351
1363-
Options can be passed to types on the last parameter
1352+
Options can be passed via the last parameter
13641353
13651354
```typescript
13661355
const T = Syntax(`number`, { // const T = {
@@ -1370,42 +1359,30 @@ const T = Syntax(`number`, { // const T = {
13701359
// }
13711360
```
13721361
1373-
<a name="syntax-parameters"></a>
1374-
1375-
### Parameters
1376-
1377-
Syntax types can be parameterized to accept exterior types.
1378-
1379-
```typescript
1380-
const T = Syntax('number')
1381-
1382-
const S = Syntax({ T }, `{ x: T, y: T, z: T }`) // const S: TObject<{
1383-
// x: TNumber,
1384-
// y: TNumber,
1385-
// z: TNumber
1386-
// }>
1387-
```
1388-
13891362
<a name="syntax-generics"></a>
13901363
13911364
### Generics
13921365
1393-
Generic types can be created using Argument types.
1366+
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))
13941367
13951368
```typescript
1396-
const Vector = Syntax(`{
1397-
x: Argument<0>,
1398-
y: Argument<1>,
1399-
z: Argument<2>
1369+
const T0 = Syntax('Argument<0>')
1370+
const T1 = Syntax('Argument<1>')
1371+
const T2 = Syntax('Argument<2>')
1372+
1373+
const Vector = Syntax({ T0, T1, T2 }, `{
1374+
x: T0,
1375+
y: T1,
1376+
z: T2
14001377
}`)
14011378

1402-
const Basis = Syntax({ Vector }, `{
1379+
const BasisVectors = Syntax({ Vector }, `{
14031380
x: Vector<1, 0, 0>,
14041381
y: Vector<0, 1, 0>,
14051382
z: Vector<0, 0, 1>,
14061383
}`)
14071384

1408-
type Basis = Static<typeof Basis> // type Basis = {
1385+
type BasisVectors = Static<typeof BasisVectors> // type BasisVectors = {
14091386
// x: { x: 1, y: 0, z: 0 },
14101387
// y: { x: 0, y: 1, z: 0 },
14111388
// z: { x: 0, y: 0, z: 1 }
@@ -1573,6 +1550,44 @@ const C = TypeCompiler.Code(Type.String()) // const C = `return functi
15731550
// }`
15741551
```
15751552
1553+
<a name='typemap'></a>
1554+
1555+
## TypeMap
1556+
1557+
TypeBox offers an external package for bi-directional mapping between TypeBox, Valibot, and Zod type libraries. It also includes syntax parsing support for Valibot and Zod and supports the Standard Schema specification. For more details on TypeMap, refer to the project repository.
1558+
1559+
[TypeMap Repository](https://github.com/sinclairzx81/typemap)
1560+
1561+
<a name='typemap-usage'></a>
1562+
1563+
### Usage
1564+
1565+
TypeMap needs to be installed seperately
1566+
1567+
```bash
1568+
$ npm install @sinclair/typemap
1569+
```
1570+
1571+
Once installed it offers advanced structural remapping between various runtime type libraries ([Example](https://www.typescriptlang.org/play/?moduleResolution=99&module=199&ts=5.8.0-beta#code/JYWwDg9gTgLgBAbzgFQJ5gKYCEIA8A0cAyqgHYwCGBcAWhACZwC+cAZlBCHAOQACAzsFIBjADYVgUAPQx0GEBTDcAUMuERS-eMjgBeFHJy4AFAAMkuAFxxSAVxAAjDFEKprdx88IAvd-adQzKYAlHBwUlJw6pra1sgA8g4AVhjCMAA8CMphObl5+QWFRcW5ETlWKABy-s4A3NkljU3NBWVhblU1UPUtvX3FbXC+nZ7dDf0TE2VMAHyq0VrEesRklCbIoS1lC-BE1twWfqOuRwE+p87MKmoaiwBKy3T0xkTBAHRgFFD8GMZ2oqJNnltrd4HdrFlJltImEKh4Aj0oU1Bh14XVxkiBjChhcxpjGtMwkA))
1572+
1573+
```typescript
1574+
import { TypeBox, Syntax, Zod } from '@sinclair/typemap'
1575+
1576+
const T = TypeBox(`{ x: number, y: number, z: number }`) // const T: TObject<{
1577+
// x: TNumber;
1578+
// y: TNumber;
1579+
// z: TNumber;
1580+
// }>
1581+
1582+
const S = Syntax(T) // const S: '{ x: number, y: number, z: number }'
1583+
1584+
const R = Zod(S).parse(null) // const R: {
1585+
// x: number;
1586+
// y: number;
1587+
// z: number;
1588+
// }
1589+
```
1590+
15761591
<a name='typesystem'></a>
15771592
15781593
## TypeSystem

0 commit comments

Comments
 (0)