add Eq experimental module

CHANGELOG.md

@@ -17,6 +17,7 @@
 # 2.2.2
 
 - **Experimental**
+  - add `Eq` module (@gcanti)
   - `Decoder`
     - add `DecodeError` interface (@gcanti)
 

Eq.md

@@ -0,0 +1,70 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Eq interface](#eq-interface)
+- [Built-in primitive eqs](#built-in-primitive-eqs)
+- [Combinators](#combinators)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# Eq interface
+
+```ts
+export interface Eq<A> {
+  readonly equals: (x: A, y: A) => boolean
+}
+```
+
+The `Eq` type class represents types which support decidable equality.
+
+Instances must satisfy the following laws:
+
+1. Reflexivity: `E.equals(a, a) === true`
+2. Symmetry: `E.equals(a, b) === E.equals(b, a)`
+3. Transitivity: if `E.equals(a, b) === true` and `E.equals(b, c) === true`, then `E.equals(a, c) === true`
+
+**Example**
+
+```ts
+import { Eq } from 'fp-ts/lib/Eq'
+
+export const string: Eq<string> = {
+  equals: (x, y) => x === y
+}
+```
+
+# Built-in primitive eqs
+
+- `string: Eq<string>`
+- `number: Eq<number>`
+- `boolean: Eq<boolean>`
+- `UnknownArray: Eq<Array<unknown>>`
+- `UnknownRecord: Eq<Record<string, unknown>>`
+
+# Combinators
+
+- `literal`
+- `nullable`
+- `type`
+- `partial`
+- `record`
+- `array`
+- `tuple`
+- `intersection`
+- `sum`
+- `lazy`
+
+**Example**
+
+```ts
+import * as E from 'io-ts/lib/Eq'
+
+const Person = E.type({
+  name: E.string,
+  age: E.number
+})
+
+console.log(Person.equals({ name: 'a', age: 0 }, { name: 'a', age: 0 })) // => true
+console.log(Person.equals({ name: 'a', age: 0 }, { name: '', age: 0 })) // => false
+console.log(Person.equals({ name: 'a', age: 0 }, { name: 'a', age: 1 })) // => false
+```

README.md

@@ -8,6 +8,7 @@
 
 - [Installation](#installation)
 - [Documentation](#documentation)
+  - [Usage](#usage)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -38,4 +39,5 @@ Experimental features are published in order to get early feedback from the comm
 - [`Decoder`](Decoder.md)
 - [`Encoder`](Encoder.md)
 - [`Codec`](Codec.md)
+- [`Eq`](Eq.md)
 - [`Schema` (advanced feature)](Schema.md)

Schema.md

@@ -8,6 +8,7 @@ import * as D from 'io-ts/lib/Decoder'
 import * as E from 'io-ts/lib/Encoder'
 import * as C from 'io-ts/lib/Codec'
 import * as G from 'io-ts/lib/Guard'
+import * as Eq from 'io-ts/lib/Eq'
 
 export const Person = S.make((S) =>
   S.type({
@@ -20,4 +21,5 @@ export const PersonDecoder = Person(D.decoder)
 export const PersonEncoder = Person(E.encoder)
 export const PersonCodec = Person(C.codec)
 export const PersonGuard = Person(G.guard)
+export const PersonEq = Person(Eq.eq)
 ```

docs/modules/Eq.ts.md

@@ -0,0 +1,183 @@
+---
+title: Eq.ts
+nav_order: 4
+parent: Modules
+---
+
+# Eq overview
+
+Added in v2.2.2
+
+---
+
+<h2 class="text-delta">Table of contents</h2>
+
+- [UnknownArray](#unknownarray)
+- [UnknownRecord](#unknownrecord)
+- [array](#array)
+- [boolean](#boolean)
+- [eq](#eq)
+- [intersection](#intersection)
+- [lazy](#lazy)
+- [nullable](#nullable)
+- [number](#number)
+- [partial](#partial)
+- [record](#record)
+- [string](#string)
+- [sum](#sum)
+- [tuple](#tuple)
+- [type](#type)
+
+---
+
+# UnknownArray
+
+**Signature**
+
+```ts
+export declare const UnknownArray: E.Eq<unknown[]>
+```
+
+Added in v2.2.2
+
+# UnknownRecord
+
+**Signature**
+
+```ts
+export declare const UnknownRecord: E.Eq<Record<string, unknown>>
+```
+
+Added in v2.2.2
+
+# array
+
+**Signature**
+
+```ts
+export declare const array: <A>(eq: E.Eq<A>) => E.Eq<A[]>
+```
+
+Added in v2.2.2
+
+# boolean
+
+**Signature**
+
+```ts
+export declare const boolean: E.Eq<boolean>
+```
+
+Added in v2.2.2
+
+# eq
+
+**Signature**
+
+```ts
+export declare const eq: Contravariant1<'Eq'> & S.Schemable<'Eq'>
+```
+
+Added in v2.2.2
+
+# intersection
+
+**Signature**
+
+```ts
+export declare function intersection<A, B>(left: Eq<A>, right: Eq<B>): Eq<A & B>
+```
+
+Added in v2.2.2
+
+# lazy
+
+**Signature**
+
+```ts
+export declare function lazy<A>(f: () => Eq<A>): Eq<A>
+```
+
+Added in v2.2.2
+
+# nullable
+
+**Signature**
+
+```ts
+export declare function nullable<A>(or: Eq<A>): Eq<null | A>
+```
+
+Added in v2.2.2
+
+# number
+
+**Signature**
+
+```ts
+export declare const number: E.Eq<number>
+```
+
+Added in v2.2.2
+
+# partial
+
+**Signature**
+
+```ts
+export declare function partial<A>(properties: { [K in keyof A]: Eq<A[K]> }): Eq<Partial<A>>
+```
+
+Added in v2.2.2
+
+# record
+
+**Signature**
+
+```ts
+export declare const record: <A>(codomain: E.Eq<A>) => E.Eq<Record<string, A>>
+```
+
+Added in v2.2.2
+
+# string
+
+**Signature**
+
+```ts
+export declare const string: E.Eq<string>
+```
+
+Added in v2.2.2
+
+# sum
+
+**Signature**
+
+```ts
+export declare function sum<T extends string>(
+  tag: T
+): <A>(members: { [K in keyof A]: Eq<A[K] & Record<T, K>> }) => Eq<A[keyof A]>
+```
+
+Added in v2.2.2
+
+# tuple
+
+**Signature**
+
+```ts
+export declare const tuple: <A extends readonly unknown[]>(...components: { [K in keyof A]: E.Eq<A[K]> }) => E.Eq<A>
+```
+
+Added in v2.2.2
+
+# type
+
+**Signature**
+
+```ts
+export declare const type: <A>(eqs: { [K in keyof A]: E.Eq<A[K]> }) => E.Eq<A>
+```
+
+Added in v2.2.2

docs/modules/Guard.ts.md

@@ -1,6 +1,6 @@
 ---
 title: Guard.ts
-nav_order: 4
+nav_order: 5
 parent: Modules
 ---
 

docs/modules/PathReporter.ts.md

@@ -1,6 +1,6 @@
 ---
 title: PathReporter.ts
-nav_order: 6
+nav_order: 7
 parent: Modules
 ---
 

docs/modules/Reporter.ts.md

@@ -1,6 +1,6 @@
 ---
 title: Reporter.ts
-nav_order: 7
+nav_order: 8
 parent: Modules
 ---
 

docs/modules/Schema.ts.md

@@ -1,6 +1,6 @@
 ---
 title: Schema.ts
-nav_order: 8
+nav_order: 9
 parent: Modules
 ---
 

docs/modules/Schemable.ts.md

@@ -1,6 +1,6 @@
 ---
 title: Schemable.ts
-nav_order: 9
+nav_order: 10
 parent: Modules
 ---
 

docs/modules/Tree.ts.md

@@ -1,6 +1,6 @@
 ---
 title: Tree.ts
-nav_order: 10
+nav_order: 11
 parent: Modules
 ---
 

docs/modules/index.ts.md

@@ -1,6 +1,6 @@
 ---
 title: index.ts
-nav_order: 5
+nav_order: 6
 parent: Modules
 ---
 

package.json

@@ -22,7 +22,7 @@
     "perf": "ts-node perf/index",
     "dtslint": "dtslint dtslint",
     "mocha": "TS_NODE_CACHE=false mocha -r ts-node/register test/*.ts",
-    "doctoc": "doctoc README.md Type.md Decoder.md Encoder.md Codec.md",
+    "doctoc": "doctoc README.md Type.md Decoder.md Encoder.md Codec.md Eq.md",
     "docs": "docs-ts",
     "import-path-rewrite": "import-path-rewrite"
   },