README.md

# Table of Contents

* [Architecture](#architecture)
* [Building](#building)
* [Testing](TESTING.md)
* [Usage](USAGE.md)

## Architecture

The source code is intended to be available through `src` (for testing), but bundled versions are provided to ensure portabilty:

- Both `cjs` and `es` modules are exported for NodeJS and modern Javascript environments respectively
- Standard `.js` and `.min.js` are emitted for browser usage, they're exported as `umd` without dependencies (`json-schema-ref-parser` and `jsonpath`)
- Also a single `.bundle.min.js` is generated containing both dependencies from above, also as `umd`

Generated sources are available as an [NPM dependency](https://www.npmjs.com/package/json-schema-faker) and through [UNPKG](https://unpkg.com/json-schema-faker@0.5.0-rc16/dist/).

```js
import jsf from 'json-schema-faker';
```

Let's examine how the library works:

```js
// 1.0 - first, we need a working (and valid) `schema`
const schema = {
  type: 'string',
};

// 1.1 - optionally, you can provide used `refs`
const refs = [
  {
    id: 'Test',
    type: 'boolean',
  }
];

// 1.2 - additionally, you can provide a `cwd` for local references
const cwd = `${__dirname}/schema`;
```

Note that:

- 1.0 — All input MUST be valid JSON-Schema
- 1.1 — Given `refs` are also valid JSON-Schema
- 1.2 — Given `cwd` is needed only if relative paths are used

Now we can produce values from our previous settings:

```js
// 2.0 - generate a sample from the given `schema`
const syncValue = jsf.generate(schema, refs);

// 2.1 - resolve and generate complex schemas with remote references
const asyncValue = await jsf.resolve(schema, refs, cwd);
```

The core provides typed generators for all basic types and well-known formats.

- 2.0 — Built-in generators can be resolved synchronously
- 2.1 — Local and remote references are resolved asynchronously

For more specific values `jsf` offers a rich menu of options and methods:

```js
// 3.0 - custom formats are supported
jsf.format('name', callback);
jsf.format('name', null); // unregister `name` format

// 3.1 - define `jsf` settings
jsf.option('optionName', 'value');
jsf.option({ optionName: 'value' });

// 3.2 - the `version` is also exported
jsf.version; // 0.5.0-rc16

// 3.3 - internal `random` generators
jsf.random; // { pick, date, shuffle, number, randexp }

// 3.4 - extend keywords with external generators
jsf.extend('chance', () => require('chance'));
jsf.extend('faker', () => require('faker'));

// 3.5 - extend keywords with custom generators
jsf.define('myProp', (value, schema) => schema);

// 3.6 - unregister extensions by keyword
jsf.reset('myProp');
jsf.reset(); // clear extensions

// 3.7 - retrieve registered extensions by keyword
jsf.locate('faker');
```

- 3.0 — This method should register non supported formats
- 3.1 — You should be able to setup custom behavior or defaults, etc.
- 3.2 — As convenience the package `version` should be exported
- 3.3 — Helpers should be shared too, to be used outside the API
- 3.4 — Third-party generators should be setup through this method (dependencies)
- 3.5 — Custom keywords like `autoIncrement` and `pattern` should be setup through this method (extensions) and stored in a shared container
- 3.6 — Added dependencies and extensions should be cleared from the container through this method, if no name is given the the entire container should be reset
- 3.7 — Any registered third-party generator should be returned through this method

### Available options

- `defaultInvalidTypeProduct` — If `failOnInvalidTypes` is disabled this value will be returned on any invalid `type` given (default: `null`)
- `defaultRandExpMax` — Setup default value directly as `RandExp.prototype.max` (default: `10`)
- `ignoreProperties` — Skip given properties from being generated (default: `[]`)
- `ignoreMissingRefs` — If enabled, it will resolve to `{}` for unknown references (default: `false`)
- `failOnInvalidTypes` — If enabled, it will throw an `Error` for unknown types (default: `true`)
- `failOnInvalidFormat` — If enabled, it will throw an `Error` for unknown formats (default: `true`)
- `alwaysFakeOptionals` — When enabled, it will set `optionalsProbability: 1.0` and ` fixedProbabilities: true` (default: `false`)
- `optionalsProbability` — A value from `0.0` to `1.0` to generate values in a consistent way, e.g. `0.5` will generate from `0%` to `50%` of values. Using arrays it means items, on objects they're properties, etc. (default: `false`)
- `fixedProbabilities` — If enabled, then `optionalsProbability: 0.5` will always generate the half of values (default: `false`)
- `useExamplesValue` — If enabled, it will return a random value from `examples` if they're present (default: `false`)
- `useDefaultValue` — If enabled, it will return the `default` value if present (default: `false`)
- `requiredOnly` — If enabled, only `required` properties will be generated (default: `false`)
- `minItems` — Override `minItems` if it's less than this value (default: `0`)
- `maxItems` — Override `maxItems` if it's greater than this value (default: `null`)
- `minLength` — Override `minLength` if it's less than this value  (default: `0`)
- `maxLength` — Override `maxLength` if it's greater than this value (default: `null`)
- `resolveJsonPath` — If enabled, it will expand `jsonPath` keywords on all generated objects  (default: `false`)
- `reuseProperties` — If enabled, it will try to generate missing properties from existing ones. Only when `fillProperties` is enabled too  (default: `false`)
- `fillProperties` — If enabled, it will try to generate missing properties to fulfill the schema definition (default: `true`)
- `random` — Setup a custom _randonmess_ generator, useful for getting deterministic results (default: `Math.random`)
- `replaceEmptyByRandomValue` — Remplace default empty value by a random value (default: `false`)

## Building

**JSON-Schema-Faker** is a JavaScript tool that can be executed both in the browser and the server.

It's built with [bili](https://github.com/egoist/bili), as we're using ES6 syntax for the source code and modules.

To generate `dist/` sources run:

```bash
$ npm run build
```

## Testing

Unit tests are run with `mocha -r esm` in order to use ES6 modules syntax, allowing to import and test code directly from the `src` folder.

Also we include "schema tests" to ensure generated data is also valid.

See our [reference guide](TESTING.md) to learn how.

## Usage

Use the [website](http://json-schema-faker.js.org/) tool and generate some values right now.

Please read our [guide](USAGE.md) for further usage instructions.