feat: add docs

README.md

@@ -1,17 +1,25 @@
 # io-ts-reporters
 
-[Error reporters](https://github.com/gcanti/io-ts#error-reporters) for io-ts.
+[Error reporters](https://github.com/gcanti/io-ts#error-reporters) for
+[io-ts](https://github.com/gcanti/io-ts).
 
-Currently this package only includes one reporter. The output is an array of strings in the format of:
+Currently this package only includes one reporter. The output is an array of
+strings in the format of:
 
-`Expected type of ${path} to be ${expectedType}, but got ${actualType}: ${actualValue}.`
+```
+Expecting ${expectedType} at ${path} but instead got: ${expectedType}
+```
 
-## TypeScript compatibility
+And for union types:
 
-| io-ts-reporters version | required typescript version |
-| ----------------------- | --------------------------- |
-| 1.0.0 | 3.5+ |
-| <= 0.0.21 | 2.7+ |
+```
+Expecting one of:
+ ${unionType1}
+ ${unionType2}
+ ${...}
+ ${unionTypeN}
+at ${path} but instead got: ${actualValue}
+```
 
 ## Installation
 
@@ -23,8 +31,7 @@ yarn add io-ts-reporters
 
 ```ts
 import * as t from 'io-ts';
-import reporter, { formatValidationErrors } from 'io-ts-reporters';
-import * as E from 'fp-ts/lib/Either';
+import reporter from 'io-ts-reporters';
 
 const User = t.interface({ name: t.string });
 
@@ -37,7 +44,8 @@ reporter.report(User.decode({ name: 'Jane' }));
 //=> []
 ```
 
-If you want to report the errors on the `Left` only use `formatValidationErrors` instead.
+To only format the validation errors in case the validation failed (ie.
+`mapLeft`) use `formatValidationErrors` instead.
 
 ```ts
 import * as t from 'io-ts';
@@ -47,11 +55,20 @@ import { pipe } from 'fp-ts/lib/pipeable';
 
 const User = t.interface({ name: t.string });
 
-pipe({ nam: 'Jane' }, User.decode, E.mapLeft(formatValidationErrors));
+const result = User.decode({ nam: 'Jane' }); // Either<t.Errors, User>
+
+E.mapLeft(formatValidationErrors)(result); // Either<string[], User>
 ```
 
 For more examples see [the tests](./tests/index.test.ts).
 
+## TypeScript compatibility
+
+| io-ts-reporters version | required typescript version |
+| ----------------------- | --------------------------- |
+| 1.0.0 | 3.5+ |
+| <= 0.0.21 | 2.7+ |
+
 ## Testing
 
 ```bash

docs/_config.yml

@@ -0,0 +1,12 @@
+remote_theme: fluffyemily/just-the-docs
+
+search_enabled: false
+
+# Aux links for the upper right navigation
+aux_links:
+ "Docs":
+ - "//gillchristian.github.io/io-ts-reporters/"
+ "API Reference":
+ - "//gillchristian.github.io/io-ts-reporters/modules/"
+ 'GitHub':
+ - 'https://github.com/gillchristian/io-ts-reporters'

docs/index.md

@@ -0,0 +1,66 @@
+---
+title: Home
+nav_order: 1
+---
+
+# io-ts-reporters
+
+[Error reporters](https://github.com/gcanti/io-ts#error-reporters) for
+[io-ts](https://github.com/gcanti/io-ts).
+
+Currently this package only includes one reporter. The output is an array of
+strings in the format of:
+
+```
+Expecting ${expectedType} at ${path} but instead got: ${expectedType}
+```
+
+And for union types:
+
+```
+Expecting one of:
+ ${unionType1}
+ ${unionType2}
+ ${...}
+ ${unionTypeN}
+at ${path} but instead got: ${actualValue}
+```
+
+## Example
+
+```ts
+import * as t from 'io-ts';
+import reporter from 'io-ts-reporters';
+
+const User = t.interface({ name: t.string });
+
+// When decoding fails, the errors are reported
+reporter.report(User.decode({ nam: 'Jane' }));
+//=> ['Expecting string at name but instead got: undefined']
+
+// Nothing gets reported on success
+reporter.report(User.decode({ name: 'Jane' }));
+//=> []
+```
+
+To only format the validation errors in case the validation failed (ie.
+`mapLeft`) use `formatValidationErrors` instead.
+
+```ts
+import * as t from 'io-ts';
+import { formatValidationErrors } from 'io-ts-reporters';
+import * as E from 'fp-ts/lib/Either';
+import { pipe } from 'fp-ts/lib/pipeable';
+
+const User = t.interface({ name: t.string });
+
+const result = User.decode({ nam: 'Jane' }); // Either<t.Errors, User>
+
+E.mapLeft(formatValidationErrors)(result); // Either<string[], User>
+```
+
+For more examples see [the tests](./tests/index.test.ts).
+
+## Credits
+
+This library was created by [OliverJAsh](https://github.com/OliverJAsh).

docs/modules/index.md

@@ -0,0 +1,6 @@
+---
+title: Modules
+has_children: true
+permalink: /docs/modules
+nav_order: 2
+---

docs/modules/index.ts.md

@@ -0,0 +1,87 @@
+---
+title: index.ts
+nav_order: 1
+parent: Modules
+---
+
+## index overview
+
+An [io-ts Reporter](https://gcanti.github.io/io-ts/modules/Reporter.ts.html#reporter-interface).
+
+**Example**
+
+```ts
+import * as t from 'io-ts'
+import Reporter from 'io-ts-reporters'
+
+const User = t.interface({ name: t.string })
+
+assert.deepEqual(Reporter.report(User.decode({ nam: 'Jane' })), ['Expecting string at name but instead got: undefined'])
+assert.deepEqual(Reporter.report(User.decode({ name: 'Jane' })), [])
+```
+
+Added in v1.2.0
+
+---
+
+<h2 class="text-delta">Table of contents</h2>
+
+- [deprecated](#deprecated)
+ - [~~reporter~~](#reporter)
+- [formatters](#formatters)
+ - [formatValidationError](#formatvalidationerror)
+ - [formatValidationErrors](#formatvalidationerrors)
+
+---
+
+# deprecated
+
+## ~~reporter~~
+
+Deprecated, use the default export instead.
+
+**Signature**
+
+```ts
+export declare const reporter: <T>(validation: E.Either<t.Errors, T>) => any[]
+```
+
+Added in v1.0.0
+
+# formatters
+
+## formatValidationError
+
+Format a single validation error.
+
+**Signature**
+
+```ts
+export declare const formatValidationError: (error: t.ValidationError) => O.Option<string>
+```
+
+Added in v1.0.0
+
+## formatValidationErrors
+
+Format validation errors (`t.Errors`).
+
+**Signature**
+
+```ts
+export declare const formatValidationErrors: (errors: t.Errors) => string[]
+```
+
+**Example**
+
+```ts
+import * as E from 'fp-ts/lib/Either'
+import * as t from 'io-ts'
+import { formatValidationErrors } from 'io-ts-reporters'
+
+const result = t.string.decode(123)
+
+assert.deepEqual(E.mapLeft(formatValidationErrors)(result), E.left(['Expecting string but instead got: 123']))
+```
+
+Added in v1.2.0

docs/modules/utils.ts.md

@@ -0,0 +1,30 @@
+---
+title: utils.ts
+nav_order: 2
+parent: Modules
+---
+
+## utils overview
+
+Added in v1.1.0
+
+---
+
+<h2 class="text-delta">Table of contents</h2>
+
+- [utils](#utils)
+ - [takeUntil](#takeuntil)
+
+---
+
+# utils
+
+## takeUntil
+
+**Signature**
+
+```ts
+export declare const takeUntil: <A = unknown>(predicate: Predicate<A>) => (as: readonly A[]) => readonly A[]
+```
+
+Added in v1.1.0

package.json

@@ -1,31 +1,61 @@
 {
  "name": "io-ts-reporters",
+ "version": "1.1.0",
+ "description": "Formatting of io-ts validation errors",
  "main": "./target/src/index.js",
  "typings": "./target/src/index.d.ts",
- "version": "1.1.0",
+ "sideEffects": false,
  "scripts": {
+ "docs": "yarn docs-ts",
  "lint": "npm run typecheck && npm run lint:only",
  "lint:only": "xo",
  "typecheck": "tsc --noEmit",
  "compile": "rm -rf ./target/* && tsc",
- "test": "npm run lint && npm run test:unit",
+ "test": "npm run lint && npm run test:unit && yarn docs",
  "test:unit": "ava",
  "prepublishOnly": "npm run compile && npm run lint"
  },
  "files": [
  "target/src",
  "src"
  ],
- "dependencies": {
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/gillchristian/io-ts-reporters.git"
+ },
+ "license": "MIT",
+ "bugs": {
+ "url": "https://github.com/gillchristian/io-ts-reporters/issues"
+ },
+ "homepage": "https://github.com/gillchristian/io-ts-reporters",
+ "dependencies": {},
+ "peerDependencies": {
  "fp-ts": "^2.0.2",
  "io-ts": "^2.0.0"
  },
  "devDependencies": {
+ "fp-ts": "^2.0.2",
+ "io-ts": "^2.0.0",
  "@types/tape": "^4.2.34",
  "ava": "^3.8.2",
+ "docs-ts": "^0.5.1",
  "io-ts-types": "^0.5.6",
  "ts-node": "^8.6.2",
  "typescript": "^3.5.3",
  "xo": "^0.30.0"
- }
+ },
+ "tags": [
+ "typescript",
+ "runtime",
+ "decoder",
+ "encoder",
+ "schema"
+ ],
+ "keywords": [
+ "typescript",
+ "runtime",
+ "decoder",
+ "encoder",
+ "schema"
+ ]
 }