feat: add base inline documentation

Annotate every external function with jsdocs. Made sure everything had
some example code to go with it.

Author: andy.patterson

README.md

@@ -8,41 +8,209 @@ A runtime and compile-time type checker library.
 
 
 ### any
+Creates a validator instance that is _always_ true.
+This is useful for specifying that an object _must_ have a given parameter, but you don't care what type that parameter is.
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const data: any = getData();
+
+const validator = v.object({ a: v.string(), b: v.any() });
+
+if (validator.isValid(data)) doThing(data); // typeof data => `{ a: string, b: any }`
+else throw new Error('oops!'); // typeof data => `any`
+```
 
 ### array
+Creates a `Validator` instance that matches on arrays of the given type.
+
+| Param | Description |
+| --- | --- |
+| v | A `Validator` instance that specifies the shape of the array elements. |
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const validator = v.array( v.number() );
+const data: any = getData();
+
+if (validator.isValid(data)) doThing(data); // typeof data = `number[]`;
+else throw new Error('oops!'); // typeof data = `any`
+```
 
 ### boolean
+Creates a validator instance that is true when the given type is a boolean.
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const validator = v.boolean();
+const data: any = getData();
+
+if (validator.isValid(data)) doThing(data); // typeof data => `boolean`
+else throw new Error('oops!'); // typeof data => `any`
+```
 
 ### intersect
+Creates a `Validator` instance that matches on _both_ of the given possible types.
+
+| Param | Description |
+| --- | --- |
+| v1 | A `Validator` instance that the specified type must match. |
+| v2 | A `Validator` instance that the specified type must match. |
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const validator = v.intersect( v.object({ a: v.string() }), v.object({ b: v.number() }) );
+const data: any = getData();
+
+if (validator.isValid(data)) doThing(data); // typeof data = `{ a: string, b: number }`
+else throw new Error('oops!'); // typeof data = `any`
+```
 
 ### nominal
+Creates a validator instance that passes type checking through to the given validator.
+Operates as an identity function for the runtime `Validator` type, but annotates the compile-time encapsulated `Validator<T>`
+with a nominal string.
+
+This is useful for marking `id`s or other fields as being a _specific_ type that should not be edited.
+
+| Param | Description |
+| --- | --- |
+| v | The validator instance that will be passed through for checking runtime correctness. |
+| s | The nominal type tag for compile-time types. |
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const validator = v.nominal(v.string(), 'id');
+const data: any = getData();
+
+if (validator.isValid(data)) doThing(data); // typeof data => `Nominal<string, 'id'>`
+else throw new Error('oops!'); // typeof data => `any`
+
+const id = 'user-id' as Nominal<string, 'id'>;
+const newId = id + '-new'; // typeof data => `string`. Since we've modified this type, it can no longer be an `id`.
+```
 
 ### number
+Creates a validator instance that is true when the given type is a number.
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const validator = v.number();
+const data: any = getData();
+
+if (validator.isValid(data)) doThing(data); // typeof data => `number`
+else throw new Error('oops!'); // typeof data => `any`
+```
 
 ### object
+Creates a validator instance that validates the given data is an object, and every property of that object matches the given schemas.
+By default, all listed properties **are required**.
+By default, unlisted properties are also allowed.
+
+| Param | Description |
+| --- | --- |
+| o | An object whose keys will be required keys of the valid type and whose properties are `Validator` instances matching the valid property's types. |
+| opts | [optional] An options object |
+| opts.optional | [optional] A list of keys that should be marked as optional in the valid type. |
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const validator = v.object({ a: v.string(), b: v.number() });
+const data: any = getData();
+
+if (validator.isValid(data)) doThing(data); // typeof data = `{ a: string, b: number }`;
+else throw new Error('oops!'); // typeof data = `any`
+```
 
 ### partial
+Creates a `Validator` instance that matches on objects with no required keys, but mandated types for certain keys if they _do_ exist.
+
+| Param | Description |
+| --- | --- |
+| v | A `Validator` instance that specifies an object type. |
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const validator = v.partial( v.object({
+a: v.string(),
+b: v.number(),
+}));
+const data: any = getData();
+
+if (validator.isValid(data)) doThing(data); // typeof data = `{ a?: string, b?: number }`;
+else throw new Error('oops!'); // typeof data = `any`
+```
 
 ### record
+Creates a `Validator` instance that matches on objects with _any_ keys, and whose properties match the given `Validator`.
+
+This is useful for "dictionary"-like objects, for instance a record of users by userId.
+
+| Param | Description |
+| --- | --- |
+| types | A `Validator` instance that specifies the right-side types of the record. |
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const validator = v.record( v.number() );
+const data: any = getData();
+
+if (validator.isValid(data)) doThing(data); // typeof data = `Record<string, number>`;
+else throw new Error('oops!'); // typeof data = `any`
+```
 
 ### string
 Creates a validator instance that is true when the given type is a string.
 
 | Param | Description |
 | --- | --- |
 | union | [optional] an array of possible string literals that the valid data could take. |
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const validator = v.string();
+const data: any = getData();
+
+if (validator.isValid(data)) doThing(data); // typeof data => `string`
+else throw new Error('oops!'); // typeof data => `any`
+```
 
 ### union
+Creates a `Validator` instance that matches on any one of the given list of possible types.
+
+| Param | Description |
+| --- | --- |
+| v | A list of `Validator` instances that specify the possible types that the valid type could take. |
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const validator = v.union([ v.string(), v.number() ]);
+const data: any = getData();
+
+if (validator.isValid(data)) doThing(data); // typeof data = `number | string`
+else throw new Error('oops!'); // typeof data = `any`
+```
 
 ### Validator
-A `Valdiator<T>` instance is an encapsulated pair of some TS type `T` and a corresponding JSON schema.
+A `Validator<T>` instance is an encapsulated pair of some TS type `T` and a corresponding JSON schema.
 
 A `Validator` already knows how to map from `T` to its json schema: using a json schema validator.
 Additionally, a `Validator` can perform simple algebraic operations with other `Validator`s resulting in more complex validatable types.
 
 A `Validator` will always maintain a valid json schema representation of the type, `T`, that it encapsulates.
 The underlying json schema can always be accessed with `getSchema()`.
-#### Example
+###### Example:
  ```typescript
 const stringValidator = new Validator<string>({ type: 'string' });
 const numberValidator = new Validator<number>({ type: 'number' });
@@ -55,8 +223,8 @@ Creates a new validator that is true whenever the data matches `this` _and_ `v`.
 
 | Param | Description |
 | --- | --- |
-| v | Another validator instance whose type will form an intersection with `this` encapsulated type. |
-#### Example
+| other | Another validator instance whose type will form an intersection with `this` encapsulated type. |
+###### Example:
  ```typescript
 import * as v from 'validtyped';
 
@@ -69,6 +237,13 @@ const and = v1.and(v2).and(v3); // { a: string, b: number, c: boolean }
 
 ### Validator.getSchema
 Returns the underlying JSON schema.
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const schema = v.string().getSchema();
+console.log(schema); // { type: 'string' }
+```
 
 ### Validator.isValid
 Predicate returning `true` if the given data matches the JSON schema.
@@ -77,13 +252,32 @@ Acts as a type guard for the encapsulated typescript type.
 | Param | Description |
 | --- | --- |
 | thing | Any data of unknown type which will be validated. |
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const userIdModel = v.nominal(v.string(), 'userId');
+const userModel = v.object({
+name: v.string(),
+id: userIdModel,
+});
+
+const x: any = getUserData();
+if (userModel.isValid(x)) doThing(x);
+```
 
 ### Validator.or
 Creates a new validator that is true whenever the data matches `this` _or_ `v`.
 
 | Param | Description |
 | --- | --- |
-| v | Another validator instance whose type will form a union with `this` encapsulated type. |
+| other | Another validator instance whose type will form a union with `this` encapsulated type. |
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const or = v.string().or(v.number()).or(v.boolean()); // string | number | boolean
+```
 
 ### Validator.setSchemaMetaData
 Add meta-data to the underlying JSON schema.
@@ -93,6 +287,13 @@ but supplies the `getSchema` method to have a complete JSON schema with meta-dat
 | Param | Description |
 | --- | --- |
 | meta | JSON schema meta-data (name, description, etc.) |
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const validator = v.string();
+validator.setSchemaMetaData({ name: 'string validator' });
+```
 
 ### Validator.validate
 Takes data of unknown type and returns a discriminated union with either the data as the valid type,
@@ -101,6 +302,25 @@ or an error object describing what part of the data did not match.
 | Param | Description |
 | --- | --- |
 | data | Any data of unknown type which will be validated. |
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const stringModel = v.string();
+
+const result = stringModel.validate(22);
+if (result.valid) doThing(result.data);
+else logger.error(...result.errors);
+```
 
 ### ValidType
+Returns the encapsulated type of a `Validator` type.
+###### Example:
+ ```typescript
+import * as v from 'validtyped';
+
+const validator = v.string();
+
+type x = v.ValidType<typeof validator>; // `string`
+```
 

package.json

@@ -6,11 +6,12 @@
   "types": "dist/src/index.d.ts",
   "scripts": {
     "doc": "ts-node scripts/generateDocumentation.ts > README.md",
+    "commitDocs": "sh scripts/commitDocsIfChanged.sh",
     "commitmsg": "commitlint -e $GIT_PARAMS",
     "lint": "tslint --config tslint.json --project . --format stylish",
     "test": "jest",
     "tsc": "tsc",
-    "prepush": "npm run -s lint && npm test",
+    "prepush": "npm run -s lint && npm test && npm run -s commitDocs",
     "release": "rm -rf dist && npm run tsc && npx semantic-release"
   },
   "jest": {

scripts/commitDocsIfChanged.sh

@@ -0,0 +1,6 @@
+npm run doc
+CHANGED=$(git status 'README.md' --porcelain)
+if [ -n "${CHANGED}" ]; then
+    git add README.md
+    git commit -m "docs: generate documentation"
+fi

scripts/generateDocumentation.ts

@@ -120,7 +120,7 @@ const generateMarkdown = (fileName: string) => {
                     : '';
 
                 const example = typeInfo.example
-                    ? `#### Example\n ${typeInfo.example}`
+                    ? `###### Example:\n ${typeInfo.example}`
                     : '';
 
                 const parts = [