[dsch] engine docs updated

docs/1-engine.md

@@ -1,5 +1,6 @@
 # ts-cast · Type Checking Engine API
 
+
 <a name="1-caster-fn"></a>
 ## 1. CasterFn&lt;T&gt; <sup>`type`</sup>
 
@@ -15,18 +16,18 @@ export interface CasterFn<T> {
 export type ErrorReporter = (message: string, context?: string) => never;
 ```
 
-### Argumernts
+**Argumernts**
 
 |    Parameter    |      Type       | Mandatory / Optional | Descriptions                                                                                                                          |
 | :-------------: | :-------------: | :------------------: | :------------------------------------------------------------------------------------------------------------------------------------ |
 |    **value**    |    `unknown`    |    **mandatory**     | The value to be casted                                                                                                                |
 |   **context**   |    `string`     |      _optional_      | The Casting Context. It is could be considered as a name of root object to be casted. As instance it could be "SomeApiMethodResponse" |
 | **reportError** | `ErrorReporter` |      _optional_      | The function accepts an error message and casting context. It could throw an error or return undefined.                               |
 
-### Returns
+**Returns**
  - **casted value**: `T`
 
-### Example
+**Example**
 
 ```ts
 import { CasterFn, ErrorReporter } from 'ts-cast';
@@ -66,8 +67,8 @@ export interface Caster<T> extends CasterFn<T> {
   default(defaltValue: T): Caster<Exclude<T, undefined>>;
   restrict(...rules: RuleFn<Exclude<T, null | undefined>>[]): Caster<T>;
   map<D>(
-    transform: (value: Exclude<T, null | undefined>
-  ) => D): Caster<D | Exclude<T, Exclude<T, null | undefined>>>;
+    transform: (value: Exclude<T, null | undefined>) => D
+  ): Caster<D | Exclude<T, Exclude<T, null | undefined>>>;
   validate(value: unknown): ValidationResult<T>;
 
   either<Right, Left>(
@@ -82,7 +83,9 @@ export interface Caster<T> extends CasterFn<T> {
 }
 ```
 
-### Property `.optional`: `Caster<T | undefined>`
+### Property `.optional`
+
+> `Caster<T | undefined>`
 
 The `.optional` property refers to `Caster` of **optional** type. Optional is considered as _could be undefined_.
 
@@ -96,7 +99,9 @@ optNumber(undefined); // returns undefined
 optNumber(null); // throws a TypeError
 ```
 
-### Property `.nullable`: `Caster<T | null>`
+### Property `.nullable`
+
+> `Caster<T | null>`
 
 The `.nullable` property refers to `Caster` of **nullable** type that means the correspondent caster accepts `null` as valid value.
 
@@ -110,14 +115,16 @@ nullableStr(null); // returns null
 nullableStr(undefined); // throws a TypeError
 ```
 
-### Method `.default(value: T)` : `Caster<Exclude<T, undefined>>`
+### Method `.default`
+
+> `(value: T) => Caster<Exclude<T, undefined>>`
 
 Creates new `Caster` that replaces `undefined` input with `value` specified as argument.
 
 **Arguments**
 
-| Parameter | Type  | Mandatory | Description                          |
-| :-------: | :---: | :-------: | :----------------------------------- |
+| Parameter | Type  | Mandatory | Description                            |
+| :-------: | :---: | :-------: | :------------------------------------- |
 | **value** |  `T`  |  **yes**  | The value to replace `undefined` input |
 
 **Returns**
@@ -133,6 +140,55 @@ someStr(undefined); // returns "no-input"
 someStr(null); // throws a TypeError
 ```
 
+### Method `.restrict`
+
+> `(...rules: RuleFn<Exclude<T, null | undefined>>[]) => Caster<T>`
+
+Creates new `Caster` that cheks if casted value satisfies restrictions described with one ore more `RuleFn`.
+
+The `RuleFn<T>` is a type of function that accepts: `value` of type `T`, optionally `context` of type `string`,
+and returns `null` if `value` satisfies rule and `string` with error message that descibes rule violation.
+
+<font color="red">Note</font>
+> if type `T` allows `null` or/and `undefined` the correspondent values will not be verified with any rule.
+
+More details avout restrictions are described in [Narrowing Types](./4-restrictions.md)
+
+**Arguments**
+
+| Parameters |                   Type                   |      Mandatory      | Description              |
+| :--------: | :--------------------------------------: | :-----------------: | :----------------------- |
+| **...rules** | `RuleFn<Exclude<T, null \| undefined>>[]` | _at least one rule_ | Rules to narrow the type |
+
+**Returns**
+ - **caster**: `Caster<T>`
+
+### Method `.map`
+
+ > `<D>(transform: (value: Exclude<T, null | undefined>) => D) => Caster<D | Exclude<T, Exclude<T, null | undefined>>>;`
+
+Creates `caster` that addionally transforms casted value to other type keeping `null | undefined` context untouched.
+
+The `.map` method is originally aimed to normalize casted value, as instance as shown in the example bellow, however it
+can give much more 
+
+**Example**
+
+```ts
+import { union, string, integer } from `ts-cast`;
+
+const ID = union(
+  string.map(value => value.toUpperCase()),
+  integer.map(value => value.toString()),
+);
+
+ID('abc'); // returns "ABC"
+ID('ABC'); // returns "ABC";
+ID(123); // returns "123";
+
+export type TID = ReturnType<typeof ID>; // ReturnType<Caster<string>> is string
+```
+
 <a name="3-caster-api"></a>
 ## 3. casterApi&lt;T&gt; <sup>`fn`</sup>
 

docs/2-types.md

@@ -0,0 +1,65 @@
+# ts-cast · Type Casters
+
+<a name="1-primitives"></a>
+## 1. Primitive Type Casters
+
+<a name="1-1-boolean"></a>
+### `boolean`
+
+<a name="1-2-integer"></a>
+### `integer`
+
+<a name="1-3-number"></a>
+### `number`
+
+<a name="1-4-string"></a>
+### `string`
+
+<a name="1-5-text.integer"></a>
+### `text.integer
+
+<a name="1-6-text.number"></a>
+### `text.number
+
+
+<a name="2-literals"></a>
+## 2. Literal Types Casters
+
+<a name="2-1-value"></a>
+### `value`
+
+<a name="2-2-values"></a>
+### `values`
+
+
+<a name="3-special"></a>
+## 3. Special Types Casters
+
+<a name="3-1-any"></a>
+### `any`
+
+<a name="3-2-nil"></a>
+### `nil`
+
+<a name="3-3-undef"></a>
+### `undef`
+
+
+<a name="4-complex"></a>
+## 4. Complex Type Casters
+
+<a name="4-1-array"></a>
+### `array`
+
+<a name="4-2-record"></a>
+### `record`
+
+<a name="4-3-struct"></a>
+### `struct`
+
+<a name="4-4-tuple"></a>
+### `tuple`
+
+
+<a name="5-recursive"></a>
+## 5. Recursive Type Casters

docs/3-operations.md

@@ -0,0 +1,7 @@
+# ts-cast · Type Composition
+
+<a name="1-prod"><a/>
+## 1. prod <sup>`fn`</sup>
+
+<a name="2-union"><a/>
+## 2. union <sup>`fn`</sup>

docs/4-restrictions.md

@@ -0,0 +1,61 @@
+
+<a name="1-rules"><a/>
+## 1. Narrowing Types
+
+<a name="1-1-predicate"><a/>
+### Predicate&lt;T&gt; <sup>`type`</sup>
+
+<a name="1-2-rulefn"><a/>
+### RuleFn&lt;T&gt; <sup>`type`</sup>
+
+<a name="1-3-tobe"><a/>
+### toBe <sup>`fn`</sup>
+
+<a name="1-4-nottobe"><a/>
+### notToBe <sup>`fn`</sup>
+
+<a name="1-5-and"><a/>
+### and <sup>`fn`</sup>
+
+<a name="1-6-or"><a/>
+### or <sup>`fn`</sup>
+
+<a name="1-7-not"><a/>
+### not <sup>`fn`</sup>
+
+
+<a name="2-predicates"><a/>
+## 2. Predicates
+
+<a name="2-1-gt"><a/>
+### `greaterThen` (`gt`)
+
+<a name="2-2-lt"><a/>
+### `lessThen` (`lt`)
+
+<a name="2-3-gte"><a/>
+### `notGreaterThen` (`gte`)
+
+<a name="2-4-lte"><a/>
+### `notLessThen` (`lte`)
+
+<a name="2-5-notempty"><a/>
+### `nonEmpty`
+
+<a name="2-6-length-gt"><a/>
+### `longerThen` (`length.gt`)
+
+<a name="2-7-length-lt"><a/>
+### `shorterThen` (`length.lt`)
+
+<a name="2-8-length-lte"><a/>
+### `notLongerThen` (`length.lte`)
+
+<a name="2-9-length-gte"><a/>
+### `notShorterThen` (`length.gte`)
+
+<a name="2-10-matching"><a/>
+### `matching`
+
+<a name="2-11-ne"><a/>
+### `notEqual` (`ne`)

docs/README.md

@@ -12,12 +12,12 @@ Runtime type checking for Typescript and JavaScript projects.
    5. [validate <sup>`fn`</sup>](./1-engine.md#5-validate)
 
 2. [Primitive Type Casters](./2-types.md#1-primitives)
-   1. [boolean](./2-types.md$1-1-boolean)
-   2. [integer](./2-types.md$1-2-integer)
-   3. [number](./2-types.md$1-3-number)
-   4. [string](./2-types.md$1-4-string)
-   5. [text.integer](./2-types.md$1-5-text.integer)
-   6. [text.number](./2-types.md$1-6-text.number)
+   1. [boolean](./2-types.md#1-1-boolean)
+   2. [integer](./2-types.md#1-2-integer)
+   3. [number](./2-types.md#1-3-number)
+   4. [string](./2-types.md#1-4-string)
+   5. [text.integer](./2-types.md#1-5-text.integer)
+   6. [text.number](./2-types.md#1-6-text.number)
 
 3. [Literal Types Casters](./2-types.md#2-literals)
    1. [value](./2-types.md#2-1-value)
@@ -34,7 +34,7 @@ Runtime type checking for Typescript and JavaScript projects.
    3. [struct](./2-types.md#4-3-struct)
    4. [tuple](./2-types.md#4-4-tuple)
 
-6. [Recursive Type Casters](./2-types.md)
+6. [Recursive Type Casters](./2-types.md#5-recursive)
 
 7. [Type Composition](./3-operations.md)
    1. [prod <sup>`fn`</sup>](./3-operations.md#1-prod)
@@ -62,8 +62,8 @@ Runtime type checking for Typescript and JavaScript projects.
    10. [matching](./4-restrictions.md#2-10-matching)
    11. [notEqual (ne)](./4-restrictions.md#2-11-ne)
 
-10. [Type Guards](./6-type-guards.md)
-
 ## How To
-   1. [Create Custom Types](./custom-types.md)
-   2. [Cast to Either&lt;\*, T&gt; and Validation&lt;\*, T&gt;](./monadic-caster.md)
+   1. [Create Custom Types](./5-custom-types.md)
+   2. [Cast to Either&lt;\*, T&gt; and Validation&lt;\*, T&gt;](./6-monadic-caster.md)
+   3. [Node: Express Example](./7-node-express.md)
+   4. [Browser: Fetch Example](./8-browser-fetch.md)

src/engine/types.ts

@@ -31,8 +31,8 @@ export interface Caster<T> extends CasterFn<T> {
   restrict(...rules: RuleFn<Exclude<T, null | undefined>>[]): Caster<T>;
 
   map<D>(
-    transform: (value: Exclude<T, null | undefined>
-  ) => D): Caster<D | Exclude<T, Exclude<T, null | undefined>>>;
+    transform: (value: Exclude<T, null | undefined>) => D
+  ): Caster<D | Exclude<T, Exclude<T, null | undefined>>>;
 
   default(defaltValue: T): Caster<Exclude<T, undefined>>;