if (validated) {
const validatedInput = validated.value; // validatedInput is type-safe
...
}
```

### From object (require JSON file)
```ts
...
import { deserializeFromObject } from 'tynder/modules/lib/serializer';
import { Foo, A } from './path/to/schema-types/my-schema'; // type definitions (.d.ts)

// import { createRequireFromPath } from 'module';
// import { fileURLToPath } from 'url';
// const require = createRequireFromPath(fileURLToPath(import.meta.url));

const mySchema = deserializeFromObject(
require('./path/to/schema-compiled/my-schema.json')); // pre-compiled schema (.json)

if (validated) {
const validatedInput = validated.value; // validatedInput is type-safe
...
}
```
or
```ts
...
import { deserializeFromObject } from 'tynder/modules/lib/serializer';
import { Foo, A } from './path/to/schema-types/my-schema'; // type definitions (.d.ts)
import mySchemaJson from './path/to/schema-compiled/my-schema.json'; // pre-compiled schema (.json)

const mySchema = deserializeFromObject(mySchemaJson);

if (validated) {
const validatedInput = validated.value; // validatedInput is type-safe
...
}
```

### From text
```ts
...
import { deserialize } from 'tynder/modules/lib/serializer';
import { Foo, A } from './path/to/schema-types/my-schema'; // type definitions (.d.ts)
import * as fs from 'fs';

const mySchema = deserialize(
fs.readFileSync('./path/to/compiled/my-schema.json', 'utf8')); // pre-compiled schema (.json)

if (validated) {
const validatedInput = validated.value; // validatedInput is type-safe
...
}
```

### Type-safe Cherrypicking and patching:

```ts
// Load pre-compiled schema and type definitions
...

interface Store {
baz: A;
}
const store: Store = {
baz: {
a: 'x',
z: false,
}
};

const needleType = op.picked(getType(mySchema, 'A'), 'a');

### Type guards

```ts
import { isType,
getType } from 'tynder/modules/validator';

...

const unknownInput: unknown = {a: 'x'};

```ts
import { assertType,
getType } from 'tynder/modules/validator';

...

const unknownInput: unknown = {a: 'x'};

## Define schema with functional API

```ts
import { picked,
omit,
partial,
intersect,
oneOf,
subtract,
primitive,
regexpPatternStringType,
primitiveValue,
optional,
repeated,
sequenceOf,
spread,
enumType,
objectType,
derived,
symlinkType,
withName,
withTypeName,
withDocComment,
withRange,
withMinValue,
withMaxValue,
withGreaterThan,
withLessThan,
withMinLength,
withMaxLength,
withMatch,
withStereotype,
withStereotype,
withForceCast,
withRecordType,
withMeta,
withMsg as $$,
withMsgId as $ } from 'tynder/modules/operators';

const myType =
oneOf(
derived(
objectType(
['a', 10],
['b', optional(20)],
['c', $('MyType-c')(
optional('aaa'))],
['d', sequenceOf(
10, 20,
spread(primitive('string'), {min: 3, max: 10}),
50)], ),
objectType(
['e', optional(primitive('string'))],
['f', primitive('string?')],
['g', repeated('string', {min: 3, max: 10})],
[[/^[a-z][0-9]$/], optional(primitive('string'))], ),
intersect(
objectType(
['x', 10], ['y', 10], ['p', 10], ),
objectType(
['x', 10], ['y', 10], ['q', 10], )),
subtract(
objectType(
['w', 10], ['z', 10], ),
objectType(
['w', 10], ))),
10, 20, 30,
primitive('string'),
primitiveValue(50), );

/*
Equivalent to following type definition:

interface P {
e?: string;
f?: string;
g: string[3..10];
[propName: /^[a-z][0-9]$/]?: string;
}
type Q = {
x: 10, y: 10, p: 10,
} & {
x: 10, y: 10, q: 10,
};
type R = {
w: 10, z: 10,
} - {
w: 10,
};
interface S extends P, Q, R {
a: 10;
b?: 20;
@msgId('MyType-c')
c: 'aaa';
d: [10, 20, ..., 50];
}
type MyType = S | 10 | 20 | 30 | string | 50;
*/

const validated1 = validate({...}, myType);
```

## DSL syntax

### Type

```ts
type Foo = string;
type Bar = string[] | 10 | {a: boolean} | [number, string];
```

### Interface

#### Named interface
```ts
interface Foo {
a: string; // Separators `;` and `,` are both allowed.
b?: number;
}

interface Bar {
c: boolean;
}

interface Baz extends Foo, Bar {
d: string[];
}
```

#### Unnamed literal interface
```ts
type A = {
a: string, // Separators `;` and `,` are both allowed.
b?: number,
};
```

#### Optional member
```ts
interface A {
b?: number; // optional member
};
```

#### Additional properties
```ts
type X = {a: string, b: number};

interface A {
// Additional properties (Error if `propName` is unmatched)
[propName: string | number | /^[a-z][0-9]+$/]: number;
};

interface B {
// Optional additional properties (Check type if propName matches)
// -> Implicit additional properties are allowed
// even if `ctx.noAdditionalProps` is true.
[propName: string | number | /^[a-z][0-9]+$/]?: number;
};

interface C {
// `propName` can be any name
[p: string]: X;
};

interface D {
// Error if app `propName`s are unmatched
[propName1: /^[a-z][0-9]+$/]: number;
[propName2: number]: number;
};

interface E {
// If optional additional properties definition(s) exist,
// implicit additional properties are allowed
// even if `ctx.noAdditionalProps` is true.
[propName1: /^[a-z][0-9]+$/]: number;
[propName2: number]: number;
[propName3: /^[A-F]+$/]?: number;
};
```
Only `string`, `number`, and `RegExp` are allowed for the `propName` type.

### Type decoration

#### Decorate to interface member
```ts
interface A {
@range(-10, 10) @msgId('M1234')
a: number;
}
```

#### Decorate to type component
```ts
type A = @range(-10, -1) number | @range(1, 10) number;

interface B {
b: @range(-10, -1) number | @range(1, 10) number;
}
```

* `@range(minValue: number | string, maxValue: number | string)`
* Check value range.
* minValue <= data <= maxValue
* `@minValue(minValue: number | string)`
* Check value range.
* minValue <= data
* `@maxValue(maxValue: number | string)`
* Check value range.
* data <= maxValue
* `@greaterThan(minValue: number | string)`
* Check value range.
* minValue < data
* `@lessThan(maxValue: number | string)`
* Check value range.
* data < maxValue
* `@minLength(minLength: number)`
* Check value range.
* minLength <= data.length
* `@maxLength(maxLength: number)`
* Check value range.
* data.length <= maxLength
* `@match(pattern: RegExp)`
* Check value text pattern.
* RegExp flags are allowed.
* e.g.: `/^[\u{3000}-\u{301C}]+$/u`
* pattern.test(data)
* `@stereotype(stereotype: string)`
* Perform custom validation.
* > **WARNING**: In the JSON schema output, this is stripped.
* `@constraint(constraintName: string, args: any)`
* Perform custom constraint.
* > **WARNING**: In the JSON schema output, this is stripped.
* `@constraint('unique', fields?: string[])`
* Check unique.
* `@constraint('unique-non-null', fields?: string[])`
* Check unique (null field is always unique).
```ts
interface A {
@constraint('unique')
a: string[];
}
interface B {
@constraint('unique', ['p', 'r'])
b: {p: string, q: string, r: string}[];
}
```
* `@forceCast`
* Validate after forcibly casting to the assertion's type.
* > **WARNING**: In the JSON schema output, this is stripped.
* `@recordType`
* If the decorated member field of object is validated, the union type is determined.
* Use to receive reasonable validation error messages.
```ts
interface Foo {
@recordType kind: 'foo';
...
}
interface Bar {
@recordType kind: 'bar';
...
}
type FooBar = Foo | Bar;
// If data {kind: 'foo', ...} is passed,
// the union type will be determined as `Foo`.
```
* `@meta`
* User defined custom properties (meta informations).
* Output to the compiled schema.
```ts
@meta({ objectId: '0ffc31e6-f534-4e49-b6d7-a3ec21f49637' })
interface A {
@meta({
fieldId: '82bd5832-c399-4d4c-8bc4-b76a95823ebf',
fieldType: 'checkbox',
})
a: ('foo' | 'bar' | 'baz')[];
}
```
* `@msg(messages: string | ErrorMessages)`
* Set custom error message.
* `@msgId(messageId: string)`
* Set custom error message id.

##### Date / Datetime stereotypes

```ts
...
import { stereotypes as dateStereotypes } from 'tynder/modules/stereotypes/date';

const schema = compile(`
interface Foo {
@stereotype('date')
@range('=today first-date-of-mo', '=today last-date-of-mo')
a: string;

@stereotype('date')
@range('2020-01-01', '2030-12-31')
b: string;

@stereotype('date')
@range('2020-01-01', '=today +2yr @12mo @31day')
c: string;
}
`);

const ty = getType(schema, 'Foo');
const ctx: Partial = {
checkAll: true,
stereotypes: new Map([
...dateStereotypes,
]),
};

const d = (new Date()).toISOString().slice(0, 10);

const z = validate({
a: d,
b: '2020-01-01',
c: d,
}, ty, ctx);
```

###### Stereotypes

* `date`
* date (UTC timezone)
* `lcdate`
* date (local timezone)
* `datetime`
* datetime (UTC timezone)
* `lcdatetime`
* datetime (local timezone)

###### Formula syntax

```
Expression =
ISODateAndDatetime |
("=" , DateTimeFormula , {whitespace, DateTimeFormula}) ;

DateTimeFormula =
ISODateAndDatetime |
("current" | "now") |
"today"
("@" | "+" | "-") , NaturalNumber ,
("yr" | "mo" | ("days" | "day") |
"hr" | "min" | "sec" | "ms") |
"first-date-of-yr" |
"last-date-of-yr" |
"first-date-of-mo" |
"last-date-of-mo" |
"first-date-of-fy", "(", NaturalNumber1To12, ")" ;
```

###### Formula examples

* This month (date)
* `@range('=today first-date-of-mo', '=today last-date-of-mo')`
* This month (datetime)
* `@minValue('=today first-date-of-mo') @lessThan('=today last-date-of-mo +1day')`
* Next month (date)
* `@range('=today first-date-of-mo +1mo', '=today @1day +1mo last-date-of-mo')`
* Next month (datetime)
* `@minValue('=today first-date-of-mo +1mo') @lessThan('=today @1day +1mo last-date-of-mo +1day')`
* This year (date)
* `@range('=today first-date-of-yr', '=today last-date-of-yr')`
* This year (datetime)
* `@minValue('=today first-date-of-yr') @lessThan('=today last-date-of-yr +1day')`
* Next year (date)
* `@range('=today first-date-of-yr +1yr', '=today @1day +1yr last-date-of-yr')`
* Next year (datetime)
* `@minValue('=today first-date-of-yr +1yr') @lessThan('=today @1day +1yr last-date-of-yr +1day')`
* This fiscal year (date)
* `@range('=today first-date-of-fy(9)', '=today first-date-of-fy(9) +1yr -1day')`
* Fiscal year beginning in September
* This fiscal year (datetime)
* `@minValue('=today first-date-of-fy(9)') @lessThan('=today first-date-of-fy(9) +1yr')`
* Fiscal year beginning in September
* Next fiscal year (date)
* `@range('=today first-date-of-fy(9) +1yr', '=today first-date-of-fy(9) +2yr -1day')`
* Fiscal year beginning in September
* Next fiscal year (datetime)
* `@minValue('=today first-date-of-fy(9) +1yr') @lessThan('=today first-date-of-fy(9) +2yr')`
* Fiscal year beginning in September

##### Unique constraint

```ts
...
import { constraints as uniqueConstraints } from 'tynder/modules/constraints/unique';

const schema = compile(`
interface A {
@constraint('unique')
a: string[];
}
interface B {
@constraint('unique', ['p', 'r'])
b: {p: string, q: string, r: string}[];
}
`);

{
const ty = getType(schema, 'A');
const ctx: Partial = {
checkAll: true,
customConstraints: new Map([
...uniqueConstraints,
]),
};
const z = validate({a: [
'x',
'y',
'x', // duplicated
]}, ty, ctx);
}
{
const ty = getType(schema, 'B');
const ctx: Partial = {
checkAll: true,
customConstraints: new Map([
...uniqueConstraints,
]),
};
const z = validate({a: [
{p: '1', q: '2', r: '3'},
{p: '2', q: '3', r: '4'},
{p: '1', q: '4', r: '3'}, // duplicated
]}, ty, ctx);
}
```

### Enum

```ts
enum Foo {
A, // 0
B, // 1
C, // 2
}

enum Bar {
A = 1, // 1
B, // 2
C = 100, // 100
}

enum Baz {
A = 'AAA',
B = 'BBB',
C = 'CCC',
}

const enum Qux {
A,
}
```

### Primitive types

```ts
/** Primitive types */
type A = number | integer | bigint | string | boolean;

/** Null-like types */
type B = null | undefined;

/** Placeholder types */
type C = any | unknown | never;
```

### Value types

See `Literals > Type literals` section.

### Array type component (Repeated type component)

#### Simple array type
```ts
type A = string[];
```

#### Complex array type
```ts
type A = Array;
```

#### Simple array type with quantity assertion
```ts
type A = string[10..20]; // 10 <= data.length <= 20
type B = string[10..]; // 10 <= data.length
type C = string[..20]; // data.length <= 20
type D = string[10]; // data.length === 10
```

#### Complex array type with quantity assertion
```ts
type A = Array; // 10 <= data.length <= 20
type B = Array; // 10 <= data.length
type C = Array; // data.length <= 20
type D = Array; // data.length === 10
```

### Sequence type component (Tuple type component)

#### Fixed length
```ts
type A = [string, number, 10, 20, 'a'];
```

#### Flex length
```ts
type A = [string, number?, boolean?, string?]; // Zero or once
type B = [string, ..., ..., ...]; // Zero or more
type C = [string, ...,
...,
...]; // With quantity assertion
```

> **WARNING**: In the JSON schema output, this translates into a simplified array assertion.

### Referencing other interface members
```ts
interface Foo {
@match(/^[A-Za-z]+$/)
name: string;
@match(/^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*$/)
email: string;
}

interface Bar {
foo: Foo
}

interface User {
userName: Foo.name;
primaryEmail: Foo.email;
primaryAliasName: Bar.foo.name;
aliasNames: Bar.foo.name[];
}
```

> NOTE:
> * This syntax is incompatible with TypeScript.
> * Generated TypeScript type definition is `userName: Foo['name'];`.
> * Tynder compiler does not allow `userName: Foo['name'];`.

### Type operators

* `P & Q`
* Intersection type
* Result type has all the members of P and Q.
* `P | Q`
* Union type
* Match to P or Q type.
* `P - Q`
* Subtraction type
* Result type has the members of P that is NOT exist in Q.
* `Pick`
* e.g. `Pick`
* Picked type
* Result type has the members of T that is exist in K.
* `Omit`
* e.g. `Omit`
* Picked type
* Result type has the members of T that is NOT exist in K.
* `Partial`
* All the member of result type are optioonal.
* `Partial<{a: string}>` is equivalent to `{a?: string}`.

### Export

```ts
export type Foo = string;

export interface Bar {
a: string;
}

export enum Baz {
A,
}

export const enum Qux {
A,
}
```

### Import

This statement is passed through to the generated codes.

```ts
import from 'foo';
import * as foo from 'foo';
import {a, b as bb} from 'foo';
```

### Declared types
```ts
declare type A = string;
declare interface B {}
declare enum C {}
declare const enum D {}

export declare type E = string;
export declare interface F {}
export declare enum G {}
export declare const enum H {}
```

### Declared variables

This statement is passed through to the generated codes.

```ts
declare var a: number;
declare let b: number;
declare const c: number;

export declare var d: number;
export declare let e: number;
export declare const f: number;
```

### External

This statement is removed from the generated code.

#### Untyped external statement
Define the external (ambient) symbols as `any` type.

```ts
external P, Q, R;
```
or
```ts
/// @tynder-external P, Q, R
```
or
```ts
/* @tynder-external P, Q, R */
```

#### Typed external statement

```ts
external P: string[],
Q: P | string,
R: {a: string}[];
```
or
```ts
/// @tynder-external P: string[], Q: P | string, R: {a: string}[]
```
or
```ts
/* @tynder-external
P: string[],
Q: P | string,
R: {a: string}[]
*/
```

### Pass-through code block

This comment body is passed through to the generated codes.

```ts
// Nominal type

declare const phoneNumberString: unique symbol;
/* @tynder-pass-through
export type PhoneNumberString = string & { [phoneNumberString]: never };
*/
external PhoneNumberString: @match(/^[0-9]{2,4}-[0-9]{1,4}-[0-9]{4}$/) string;
```

### Comments

```ts
// ↓↓↓ directive line comment ↓↓↓
// @tynder-external P, Q, R
/// @tynder-external S, T

// ↓↓↓ directive block comment ↓↓↓
/* @tynder-external U, V */

/** doc comment */
type Foo = string | number;

/** doc comment */
interface Bar {
/** doc comment */
a?: string;
}

/** doc comment */
enum Baz {
/** doc comment */
A,
}

// line comment
# line comment

/* block comment */
/*
block comment
*/
```
Doc comments are preserved.

### Literals

#### Type literals
```ts
type A = 'a' | "b" | `c` |
20 | -10 | -0.12 | -9.3+8e |
-10_000_000.999_999 |
0xff | 0o77 | 0b11 | +Infinity | -Infinity |
-10n | 0n | 123n |
true | false | null | undefined |
{a: string, b: 'aaa'} | [10, string];
```

#### Value literals
```ts
type A = @match(/^.+$/) string; // RegExp
type B = @range(10, 20) number; // number
type C = @range('a', 'b') string; // string
type D = @msg({
required: '...',
typeUnmatched: '...' }) number; // object
```

### Directives

```ts
/// @tynder-external P, Q, R
```

* `@tynder-external` _type_ [, ...]
* Declare external types as `any`.

```ts
/* @tynder-pass-through
export type PhoneNumberString = string & { [phoneNumberString]: never };
*/
```

* `@tynder-pass-through` _body_
* This comment body is passed through to the generated codes.

### Generics
Generics actual parameters are removed.

#### DSL:
```ts
/// @tynder-external Map, Set

interface Foo {
a: Map; // validator treats it as `any`.
b: Set; // validator treats it as `any`.
}
```

#### TypeScript generated type definition:

```ts
interface Foo {
a: Map; // generics actual parameters are removed.
b: Set; // generics actual parameters are removed.
}
```

> NOTE: Generic interfaces and generic types cannot be defined.

* e.g.

```ts
interface Foo { // It is not possible.
a: T;
}
```

## Customize error messages

### Customize message of items

```ts
@msgId('M1111') // Custom error message id
export interface Foo {
@msgId('M1234')
s: number; // Custom error message id

@msg({
required: '"%{name}" of "%{parentType}" is required.',
typeUnmatched: '"%{name}" of "%{parentType}" should be "%{expectedType}".',
})
t: number; // Custom error message

@msg('"%{name}" of "%{parentType}" is not valid.')
u: number; // Custom error message
}
```

### Default error messages

```ts
export const defaultMessages: ErrorMessages = {
invalidDefinition: '"%{name}" of "%{parentType}" type definition is invalid.',
required: '"%{name}" of "%{parentType}" is required.',
typeUnmatched: '"%{name}" of "%{parentType}" should be type "%{expectedType}".',
additionalPropUnmatched: '"%{addtionalProps}" of "%{parentType}" are not matched to additional property patterns.',
repeatQtyUnmatched: '"%{name}" of "%{parentType}" should repeat %{repeatQty} times.',
sequenceUnmatched: '"%{name}" of "%{parentType}" sequence is not matched',
valueRangeUnmatched: '"%{name}" of "%{parentType}" value should be in the range %{minValue} to %{maxValue}.',
valuePatternUnmatched: '"%{name}" of "%{parentType}" value should be matched to pattern "%{pattern}"',
valueLengthUnmatched: '"%{name}" of "%{parentType}" length should be in the range %{minLength} to %{maxLength}.',
valueUnmatched: '"%{name}" of "%{parentType}" value should be "%{expectedValue}".',
};
```

### Change default messages
```ts
import { compile } from 'tynder/modules/compiler';
import { getType } from 'tynder/modules/validator';
import { pick,
merge } from 'tynder/modules/picker';
import { ValidationContext } from 'tynder/modules/types';

export default const mySchema = compile(`
interface A {
@msg({
required: 'Don\'t forget "%{name}"!.',
})
a: string;
}
`);

const ctx: Partial = {
checkAll: true,
noAdditionalProps: true,
schema: mySchema,
errorMessages: {
required: '%{name}" is requred!',
},
};

const validated = validate({
aa: 'x',
}, getType(mySchema, 'A'), ctx3);

if (validated3 === null) {
console.log(JSON.stringify(
ctx3.errors, // error messages
null, 2));
}
```

Precedence is "`Default messages` < `ctx.errorMessages` < `@msg()`".

### Keyword substitutions

* `%{expectedType}`
* `%{type}`
* `%{expectedValue}`
* `%{value}`
* `%{repeatQty}`
* `%{minValue}`
* `%{maxValue}`
* `%{pattern}`
* `%{minLength}`
* `%{maxLength}`
* `%{name}`
* `%{parentType}`
* `%{dataPath}`
* `%{addtionalProps}`

## CLI subcommands and options

```
Usage:
tynder subcommand options...

Subcommands:
help
Show this help.
compile
Compile schema and output as JSON files.
* default input file extension is *.tss
* default output file extension is *.json
compile-as-ts
Compile schema and output as JavaScript|TypeScript files.
* default input file extension is *.tss
* default output file extension is *.ts
Generated code is:
const schema = {...};
export default schema;
gen-ts
Compile schema and generate TypeScript type definition files.
* default input file extension is *.tss
* default output file extension is *.d.ts
gen-json-schema
Compile schema and generate 'JSON Schema' files.
* default input file extension is *.tss
* default output file extension is *.json
gen-json-schema-as-ts
Compile schema and generate 'JSON Schema'
as JavaScript|TypeScript files.
* default input file extension is *.tss
* default output file extension is *.ts
Generated code is:
const schema = {...};
export default schema;
gen-csharp
Compile schema and generate 'C#' type definition files.
* default input file extension is *.tss
* default output file extension is *.cs
gen-proto3
Compile schema and generate 'Protocol Buffers 3' type definition files.
* default input file extension is *.tss
* default output file extension is *.proto
gen-graphql
Compile schema and generate 'GraphQL' type definition files.
* default input file extension is *.tss
* default output file extension is *.graphql

Options:
--indir dirname
Input directory
--outdir dirname
Output directory
--inext fileExtensionName
Input files' extension
--outext fileExtensionName
Output files' extension
```

Example:
```sh
tynder compile --indir path/to/schema/tynder --outdir path/to/schema/_compiled
```

## Limitations
* Generics actual parameters are removed.
* Except
`Array`,
[`Pick`](https://www.typescriptlang.org/docs/handbook/utility-types.html#picktk),
[`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittk) and
[`Partial`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialt).