faker-schema

Create deterministic schemas with Faker

Introduction

This library, faker-schema, provides a neat API around @faker-js/faker to deterministically create one or more pseudo-random records from schemas with advanced features like derived values and probability.

Installation

npm i faker-schema

Usage

Basic Usage

The Schema class is used to create schemas from a blueprint. A blueprint is a function that returns an object literal.

Instatiate a new Schema with a blueprint:

const { faker } = require('@faker-js/faker')
const { Schema } = require('faker-schema')

const personSchema = new Schema(() => ({
  firstName: faker.name.firstName(),
  lastName: faker.name.lastName(),
  address: {
    streetAddress: faker.address.streetAddress(),
    city: faker.address.city(),
    state: faker.address.state(),
    country: faker.address.country(),
    postalCode: faker.address.zipCode(),
  }
}))

Make a random person from the schema:

const person = personSchema.makeOne()

Example output from console.log(person):

{
  "firstName": "Amira",
  "lastName": "Hintz",
  "address": {
    "streetAddress": "64724 Reinhold Plaza",
    "city": "Jastport",
    "state": "Georgia",
    "country": "Rwanda",
    "postalCode": "16974-6122"
  }
} 

Make an array of five random people from the schema:

const people = personSchema.make(5)

You can seed the schema which will result in a deterministic sequence:

personSchema.setSeed(123)

But an even better approach is to pass the optional seed argument to the makeOne and make methods:

const seed = 123
const person = personSchema.makeOne(seed)
const people = personSchema.make(5, seed)

The above techinique is deterministic. The same random record will be returned if the methods are called again with the same seed.

If you seed the make method, the nth item in the array will have a seed of seed + n - 1. This means if you seed make with 2, such as make(5, 2), then makeOne(2) will return the first item from the result of make and makeOne(3) will return the second item from the result of make, and so on.

Tip: Because of the behavior described above, seeding by id is a great way to use this library to implement a deterministic mock API with pseudo-random data.

Advanced Usage

Blueprints for schemas can be nested any-level deep, have derived properties that are deterministic, and using the withProbability helper, can return either a value or null, also deterministically.

The following code snippet displays how to combine these advanced techniques:

const { faker } = require('@faker-js/faker')
const { 
  Schema, 
  withProbability 
} = require('faker-schema')

const personSchema = new Schema(() => ({
  firstName: faker.name.firstName(),
  lastName: withProbability(
    faker.name.lastName(), 0.5
  ),
  fullName: ({ firstName, lastName }) =>
    firstName && lastName
      ? `${firstName} ${lastName}`
      : firstName || lastName,
  address: {
    streetAddress: withProbabilit(
      faker.address.streetAddress(), 0.5
    ),
    city: faker.address.city(),
    state: faker.address.state(),
    country: withProbability(
      faker.address.country(), 0.5
    ),
    postalCode: withProbability(
      faker.address.zipCode(), 0.25
    ),
  },
  fullAddress: ({ address }) =>
    Object
      .values(address)
      .filter(v => v !== null)
      .join(', ')
      .trim()
}))

const seed = 123
const person = personSchema.makeOne(seed)
const people = personSchema.make(5, seed)

Example output from console.log(person):

{
  "firstName": "Nannie",
  "lastName": null,
  "fullName": "Nannie",
  "address": {
    "streetAddress": "82890 Andreane Pass",
    "city": "Pabloshire",
    "state": "Massachusetts",
    "country": "Qatar",
    "postalCode": null 
  },
  "fullAddress": "82890 Andreane Pass, Pabloshire, Massachusetts, Qatar"
}

More Information

As you may have noticed, much of the heavy-lifting here comes from Faker. Consult the Faker README for more information.

License

Copyright (c) 2019-2022 Nickolas Kenyeres [e-mail]

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.