# doctyr

> Runtime type checking and document generation for JavaScript

Latest version **0.0.6-b** (published 2018-11-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install doctyr
pnpm add doctyr
yarn add doctyr
bun add doctyr
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.6-b |
| Published | 2018-11-16 |
| First published | 2018-08-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | 9.x |
| Dependencies | 0 |
| Unpacked size | 33.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | anywhichway |

## Links

- npm: https://www.npmjs.com/package/doctyr
- Repository: https://github.com/doctyr/doctyr
- Homepage: https://github.com/doctyr/doctyr#readme
- Issues: https://github.com/doctyr/doctyr/issues
- npm.io page: https://npm.io/package/doctyr

## Recent versions

- 0.0.6-b (latest) — 2018-11-16
- 0.0.5-b — 2018-11-16
- 0.0.4-b — 2018-11-14
- 0.0.3-b — 2018-08-12
- 0.0.2-b — 2018-08-12
- 0.0.1-b — 2018-08-12

## README

# doctyr v0.0.6b

DOCument, TYpe, Runtime - Runtime type checking and document generation for JavaScript. 

`doctyr` supports runtime type checking and documentation generation for JavaScript functions and return values.
Types can be directly specified or infered from default arguments. Type checking can go beyond basic types and 
includes support for instanceof checks and custom validation functions.

The API has been designed with simplicity in mind. 

1) Primitive and complex object type checking can be accomplished without learning a schema system.

3) Re-writing existing code is not required.

3) Types can be infered from default arguments.

4) Any boolean functions from existing libraries or custom written ones can be used to check types.

5) Using the live documentation facility is completely optional and incurs no compute or substative memory overhead if no 
documentation for functions is provided.

6) The type checking can be optionally included or excluded from production builds and dynamically turned on and off.

# Installation

`npm install doctyr`

There are browser based files in the `browser` sub-directory.

# Basic Usage

The call signature for `doctyr` is `(function,thisType,[argType[,...]],returnType)`. That is
a function followed by an array, the first element of which is the type of the `this` argument, an array of
 types of the arguments, and a final arguments that is the type of the return value.

The type specifications can be `undefined`, strings, objects, or instances of `doctyr.spec`. If the
value `undefined` is used, then the type is unconstrained. See API section for more detail.

You can use multiple coding styles to take advantage of `doctyr` including:

## Direct function defintion, e.g.

```javascript
const myFunction = doctyr(function(arg1) { ...; return arg1; },undefined,["string"],"string");
```

## Re-defining functions by assigning a return value, e.g.

```javascript
function myFunction(arg1) { ...; return arg1; }

myFunction = doctyr(func,undefined,["string"],"string"); // this could be done conditionally for non-production
```

## Re-writing functions to include guard calls and return conform checks, e.g.

```javascript
function myFunction(arg1) {
	const returns = doctyr.guard(this,myFunction,[undefined,"string","string"]);
	... // your code that assigns something to returnValue
	return doctyr.conforms(returnValue,returns);
}
```

## Type Inference

You can rely on default arguments to determine the types. Both the below allow any type for `this` and return value, 
but constrain the argument to a string.

```javascript
function myFunction(arg1="myArg") { ...; return arg1; }

myFunction = doctyr(func);

```

```javascript
function myFunction(arg1="myArg") {
	doctyr.guard(this,myFunction,arguments);
	... // your code
	return doctyr.conforms(arg1,"string");
}
```

## Test Functions and Instances

You can provide functions to do type checks, e.g. ensure a value is even

```javascript
function myFunction(arg1) { ...; return arg1; }

myFunction = doctyr(func,undefined,[value => value % 2 ===0]); 
```

If the function is a constructor, then the check will be satisfied if the argument is an object that satisfies `instanceof`, 
e.g. ensure an argument is an instanceof a Date:

```javascript
function myFunction(arg1) { ...; return arg1; }

myFunction = doctyr(func,undefined,[Date]); 
```


## Polymorphic Values

Polymorphic arguments and return values are supported through the use of an array to contain the types. The example below will
allow a string or number as the function argument:

```javascript
function myFunction(arg1) { ...; return arg1; }

myFunction = doctyr(func,undefined,[["string","number"]],"string");
```

## Complex Objects

Complex object type checking just requires the provision of an object having the expected surface with property values being types.
The example below ensures that the argument has a name property with a value of type string, an age property with a value of type number,
and an address that is either `undefined` or an instanceof Object, i.e. it is optional. The below ensure the argument has
a string name property, and age number sproperty, and an optional address that if provided is an instance of an `Object`.

```javascript
function myFunction(arg1) { ...; return arg1; }

myFunction = doctyr(func,undefined,[{name:"string",age:"number",address:[undefined,Object]}]);
```


## Code As Documentation

By using `doctyr.spec(config)` instead on primitive values, you can add documentation to your code for runtime generation, e.g.

```javascript
function myFunction(arg1) { ...; return arg1; }

myFunction = doctyr(myFunction,doctyr.spec({type:undefined,doc:{description:"No 'this' context is expected."}}),
						["string"],
						doctyr.spec({type:"string",doc:{description:"The original string argument is returned."}}));
							
const html = doctyr.toHTML(myFunction);
```

will return HTML that renders as:

<div>
	myFunction(arg1)
	<ul>
	  <li>thisType
			<ul><li>undefined No 'this' context is expected.</li></ul>
		</li>
	</ul>
	<ul>
		<li>Arguments
		<ul>
			<li>arg1:string </li>
		</ul>
		</li>
	</ul>
	<ul>
		<li>Returns
			<ul><li>string The original string argument is returned.</li></ul>
		</li>
	</ul>
</div>

## Turning doctyr off

Just set `doctyr.on = false`.


	
# Developed and Tested With

[Eclipse](https://www.eclipse.org/), [Mocha](https://mochajs.org/), [Chai](www.chaijs.com), and [Browserstack](https://www.browserstack.com).

# Release History (reverse chronological order)

2018-11-14 v0.0.6b Synchronized version numbers.

2018-11-14 v0.0.5b Reintroduced HTML generation.

2018-11-13 v0.0.4b Removed JavaScript parser and changed API to dramatically simplify. HTML generation temporarily removed.

2018-08-12 v0.0.3b Documentation updates.

2018-08-12 v0.0.2b Documentation updates.

2018-08-11 v0.0.1b First public release.

# License

MIT License

Copyright (c) 2018 Simon Y. Blackwell, AnyWhichWay, LLC

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---
_Source: https://npm.io/package/doctyr · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._