Merge 26e11fa into e17e4ad

README.md

@@ -123,20 +123,26 @@ export const PersonSchema = S.Struct({
 
 ## Schema Transformations
 
-There are two types of schema transformations in `schemata-ts`: ['combinators'](#schema) which are functions that take schemas as parameters and return new schemas, and 'transformers' which are specific to a particular schema. Starting with version 2.1 it is possible to adjust the declaration of a schema _after_ it's declared. The possibilities here are endless. Schemata-ts currently supports the following transformations:
-
-- `StructSchema`: A struct specific schema transformer which permits the following methods:
-  - `omit`: Omit one or many properties from a struct schema
-  - `pick`: Pick one or many properties from a struct schema
-  - `extend`: Extend a struct schema with additional properties
-  - `intersect`: Extend a struct schema with additional properties from another struct schema
-  - `partial`: Make both input and output properties of a struct schema optional
-  - `partialOption`: Make both input properties optional, and map output properties to the fp-ts `Option` type
-  - `strict`: Raise an `UnexpectedValue` transcode error when encountering unspecified properties
-  - `addIndexSignature`: Add an index signature to a struct schema, effectively providing a schema for all properties not explicitly defined
-  - `readonly`: Mark all properties of a struct schema readonly
-
-And others are soon to come, for instance `Array` and `String` with `nonEmpty`; `Tuple` with `prepend` and `append`; and `Union` with `extend`.
+There are three ways to transform a schema in `schemata-ts`: ['combinators'](#schema) which are functions that take schemas as parameters and return new schemas, 'transformers' which are specific to particular schemata, and `Imap` which applies an invariant transformation to the underlying data-type.
+
+### Invariant Transformations
+
+Aside from `Guard`, all data-types derivable from schemas are invariant functors. This means that supplying mapping functions `to` and `from` to `Imap` adjusts the `Output` of that particular data type. Because `Guard` is not invariant, you must supply the resulting `Guard` to the invariant map. The combinator version of this is `Imap`. In version `3.0` (coming late 2023/early 2024) it will be possible to `.imap()` any schema.
+
+### Schema Transformers
+
+Schema transformers are classes which extend `SchemaImplementation`, and allow adjustment to the underlying schema parameters after it has been declared in an immutable fashion. This is useful for type-specific methods like `pick` or `omit` for `Struct`.
+
+Here are the current transformers and available methods,
+
+- Struct: `pick`, `omit`, `partial`, `partialOption`, `readonly`, `strict`, `addIndexSignature`, `extend`, `intersect`
+- Array: `minLength`, `maxLength`, `nonEmpty`
+- String: `brand`, `minLength`, `maxLength`, `errorName`
+- Int: `brand`, `min`, `max`, `errorName`
+- Float: `brand`, `min`, `max`, `errorName`
+- Tuple: `append`, `prepend`
+
+... with more to come!
 
 ### Transformation Example
 

docs/Assert.md

@@ -0,0 +1,81 @@
+---
+title: Assert.ts
+nav_order: 2
+permalink: /assert/
+---
+
+## Assert overview
+
+Added in v2.2.0
+
+---
+
+<h2 class="text-delta">Table of contents</h2>
+
+- [Interpreters](#interpreters)
+  - [deriveAssert](#deriveassert)
+  - [deriveInputAssert](#deriveinputassert)
+  - [deriveInputAssertTree](#deriveinputasserttree)
+- [Models](#models)
+  - [Assert (interface)](#assert-interface)
+
+---
+
+# Interpreters
+
+## deriveAssert
+
+A trait which will throw an error for when an expected "output" value does not match a
+schema's output type
+
+**Signature**
+
+```ts
+export declare const deriveAssert: <I, O>(schema: Schema<I, O>) => Assert<O>
+```
+
+Added in v2.2.0
+
+## deriveInputAssert
+
+A trait which will throw an error for when an expected "input" value does not match a
+schema's input type
+
+**Signature**
+
+```ts
+export declare const deriveInputAssert: <I, O>(schema: Schema<I, O>) => Assert<I>
+```
+
+Added in v2.2.0
+
+## deriveInputAssertTree
+
+A trait which will throw an error for when an expected "input" value does not match a
+schema's input type
+
+Unlike `deriveInputAssert`, this will include the error tree in the error message
+
+**Signature**
+
+```ts
+export declare const deriveInputAssertTree: <I, O>(schema: Schema<I, O>) => Assert<I>
+```
+
+Added in v2.2.0
+
+# Models
+
+## Assert (interface)
+
+A trait which will throw an error for when a value does not match a schema
+
+**Signature**
+
+```ts
+export interface Assert<T> {
+  readonly assert: (output: unknown) => asserts output is T
+}
+```
+
+Added in v2.2.0

docs/Eq.md

@@ -1,6 +1,6 @@
 ---
 title: Eq.ts
-nav_order: 3
+nav_order: 4
 permalink: /eq/
 ---
 

docs/Guard.md

@@ -1,6 +1,6 @@
 ---
 title: Guard.ts
-nav_order: 5
+nav_order: 6
 permalink: /guard/
 ---
 

docs/JsonSchema.md

@@ -1,6 +1,6 @@
 ---
 title: JsonSchema.ts
-nav_order: 7
+nav_order: 8
 permalink: /json-schema/
 ---
 

docs/MergeSemigroup.md

@@ -1,6 +1,6 @@
 ---
 title: MergeSemigroup.ts
-nav_order: 8
+nav_order: 9
 permalink: /merge-semigroup/
 ---
 

docs/Schema.md

@@ -1,6 +1,6 @@
 ---
 title: Schema.ts
-nav_order: 10
+nav_order: 11
 permalink: /schema/
 ---
 

docs/TranscodeError.md

@@ -1,6 +1,6 @@
 ---
 title: TranscodeError.ts
-nav_order: 87
+nav_order: 91
 permalink: /transcode-error/
 ---
 
@@ -34,6 +34,9 @@ Added in v2.0.0
     - [\_tag (property)](#_tag-property-3)
   - [TranscodeError (type alias)](#transcodeerror-type-alias)
   - [TranscodeErrors (class)](#transcodeerrors-class)
+    - [toJSON (method)](#tojson-method)
+    - [toString (method)](#tostring-method)
+    - [[Symbol.for('nodejs.util.inspect.custom')] (method)](#symbolfornodejsutilinspectcustom-method)
     - [\_tag (property)](#_tag-property-4)
   - [TypeMismatch (class)](#typemismatch-class)
     - [\_tag (property)](#_tag-property-5)
@@ -309,6 +312,36 @@ export declare class TranscodeErrors {
 
 Added in v2.0.0
 
+### toJSON (method)
+
+**Signature**
+
+```ts
+public toJSON(this: TranscodeErrors)
+```
+
+Added in v2.2.0
+
+### toString (method)
+
+**Signature**
+
+```ts
+public toString(this: TranscodeErrors)
+```
+
+Added in v2.2.0
+
+### [Symbol.for('nodejs.util.inspect.custom')] (method)
+
+**Signature**
+
+```ts
+public [Symbol.for('nodejs.util.inspect.custom')](this: TranscodeErrors)
+```
+
+Added in v2.2.0
+
 ### \_tag (property)
 
 **Signature**

docs/Transcoder.md

@@ -1,6 +1,6 @@
 ---
 title: Transcoder.ts
-nav_order: 88
+nav_order: 92
 permalink: /transcoder/
 ---
 

docs/TranscoderPar.md

@@ -1,6 +1,6 @@
 ---
 title: TranscoderPar.ts
-nav_order: 89
+nav_order: 93
 permalink: /transcoder-par/
 ---
 

docs/TypeString.md

@@ -1,6 +1,6 @@
 ---
 title: TypeString.ts
-nav_order: 90
+nav_order: 94
 permalink: /type-string/
 ---
 

docs/brand.md

@@ -1,6 +1,6 @@
 ---
 title: brand.ts
-nav_order: 2
+nav_order: 3
 permalink: /brand/
 ---
 

docs/float.md

@@ -1,6 +1,6 @@
 ---
 title: float.ts
-nav_order: 4
+nav_order: 5
 permalink: /float/
 ---
 

docs/index.md

@@ -130,20 +130,26 @@ export const PersonSchema = S.Struct({
 
 ## Schema Transformations
 
-There are two types of schema transformations in `schemata-ts`: ['combinators'](#schema) which are functions that take schemas as parameters and return new schemas, and 'transformers' which are specific to a particular schema. Starting with version 2.1 it is possible to adjust the declaration of a schema _after_ it's declared. The possibilities here are endless. Schemata-ts currently supports the following transformations:
-
-- `StructSchema`: A struct specific schema transformer which permits the following methods:
-  - `omit`: Omit one or many properties from a struct schema
-  - `pick`: Pick one or many properties from a struct schema
-  - `extend`: Extend a struct schema with additional properties
-  - `intersect`: Extend a struct schema with additional properties from another struct schema
-  - `partial`: Make both input and output properties of a struct schema optional
-  - `partialOption`: Make both input properties optional, and map output properties to the fp-ts `Option` type
-  - `strict`: Raise an `UnexpectedValue` transcode error when encountering unspecified properties
-  - `addIndexSignature`: Add an index signature to a struct schema, effectively providing a schema for all properties not explicitly defined
-  - `readonly`: Mark all properties of a struct schema readonly
-
-And others are soon to come, for instance `Array` and `String` with `nonEmpty`; `Tuple` with `prepend` and `append`; and `Union` with `extend`.
+There are three ways to transform a schema in `schemata-ts`: ['combinators'](#schema) which are functions that take schemas as parameters and return new schemas, 'transformers' which are specific to a particular schema, and `Imap` which applies an invariant transformation to the underlying data-type.
+
+### Invariant Transformations
+
+All data-types derivable from schemas are invariant functors, aside from `Guard`. This means that if you supply mapping functions `to`, and `from` the new type, you will adjust the `Output` type of that particular data type. Because `Guard` is not invariant, you must supply the resulting `Guard` to the invariant map. The combinator version of this is `Imap`. In version `3.0` which is coming in late 2023/early 2024 it will be possible to `.imap` a schema.
+
+### Schema Transformers
+
+Schema transformers are classes which extend `SchemaImplementation`, and allow adjustment to the underlying schema parameters after it has been declared in an immutable fashion. This is useful for type-specific methods like `pick` or `omit` for `Struct`.
+
+Here are the current transformers and available methods:
+
+- `StructSchema`: `pick`, `omit`, `partial`, `partialOption`, `readonly`, `strict`, `addIndexSignature`, `extend`, `intersect`
+- `ArraySchema`: `minLength`, `maxLength`, `nonEmpty`
+- `StringSchema`: `brand`, `minLength`, `maxLength`, `errorName`
+- `IntSchema`: `brand`, `min`, `max`, `errorName`
+- `FloatSchema`: `brand`, `min`, `max`, `errorName`
+- `TupleSchema`: `append`, `prepend`
+
+... and more to come!
 
 ### Transformation Example
 

docs/integer.md

@@ -1,6 +1,6 @@
 ---
 title: integer.ts
-nav_order: 6
+nav_order: 7
 permalink: /integer/
 ---
 

docs/newtype.md

@@ -1,6 +1,6 @@
 ---
 title: newtype.ts
-nav_order: 9
+nav_order: 10
 permalink: /newtype/
 ---
 

docs/schemata/Annotate.md

@@ -1,6 +1,6 @@
 ---
 title: Annotate
-nav_order: 11
+nav_order: 12
 parent: schemata
 ---