Fluent-Faker

Overview

A library for generating data in a simple way for testing

Faker is used for fake data generation

Getting Started

Install

Install it as a Dev Dependency using your favorite package manager

npm install @maarkis/fluent-faker --save-dev

or

pnpm install @maarkis/fluent-faker --save-dev

or

yarn add @maarkis/fluent-faker --dev

Usage

interface Todo {
    id: number,
    name: string,
    description: string,
    done: boolean,
}

import {createBuilder} from '@maarkis/fluent-faker'

// unique instance
createBuilder<Todo>({id: 1, name: 'Todo 1'}).generate() // { id: 1, name: 'Todo 1' }

// using faker
createBuilder<Todo>((faker) = (
    {
        id: faker.number.int(),
        name: faker.lorem.word()
    }))
    .generate() // { id: 654, name: 'eaque' }

import {generate} from '@maarkis/fluent-faker'

// unique instance
generate<Todo>({id: 1, name: 'Todo 1'}) // { id: 1, name: 'Todo 1' }

// unique instance
generate<Todo>({id: 1, name: 'Todo 1'}, 2)
// [{ id: 1, name: 'Todo 1' },{ id: 1, name: 'Todo 1' }]

Switching locales

By default, fluent-faker uses the default locale of Faker.js (en) when constructing new instances of the Builder.

You can change the locale by providing the locale parameter during the construction of the Builder class.

import {Builder} from '@maarkis/fluent-faker'

new Builder<Todo>('pt_BR')

Check Available locales in Faker.js documentation.

Using seed

Sets the seed or generates a new one

Please note that generated values are dependent on both the seed and the number of calls that have been made since it was set

This method is intended to allow for consistent values in a tests, so you might want to use hardcoded values as the seed

Global:

import {useSeed} from '@maarkis/fluent-faker'

useSeed(596) // 596

global scope, values modify Faker.js lib

Local:

import {Builder} from '@maarkis/fluent-faker'

new Builder<Todo>().useSeed(596) // 596

API Reference

createBuilder

Parameters:

| Name | Type | Description | required | |----------|-------------------------|-------------------------------|:--------:| | model | Partial<T> / Function | Initial setup for the builder | no | | locale | string | The locale to set | no |

Returns: new Builder instance

Usage:

import {createBuilder} from "@maarkis/fluent-faker";

createBuilder<Todo>({ id: 1, name: 'Todo 1' })

or

import {createBuilder} from "@maarkis/fluent-faker";

createBuilder<Todo>((faker) => ({
    id: faker.number.int(),
    name: 'Todo 1'
}))

or

import {createBuilder} from "@maarkis/fluent-faker";

createBuilder<Todo>(() => ({ id: 1, name: 'Todo 1' }), 'pt_BR')

generate

Parameters:

| Name | Type | Description | required | |----------|-------------------------|-------------------------------|:--------:| | model | Partial<T> / Function | Initial setup for the builder | no | | length | number | The locale to set | no |

Returns: new T instance or collection

Usage:

import {generate} from "@maarkis/fluent-faker";

generate<Todo>({ id: 1, name: 'Todo 1'}) // { id: 1, name: 'Todo 1' }

or

import {generate} from "@maarkis/fluent-faker";

generate<Todo>((faker) => ({
    id: faker.number.int(),
    name: 'Todo 1'
})) // { id: 8874, name: 'Todo 1' }

or

import {generate} from "@maarkis/fluent-faker";

generate<Todo>((faker) => ({
    id: faker.number.int(),
    name: 'Todo 1'
}), 2) // [{ id: 8874, name: 'Todo 1' },{ id: 97856, name: 'Todo 1' }]

Builder

addModel

Parameters:

| Name | Type | Description | required | |---------|-------------------------|-------------------------|:--------:| | model | Partial<T> / Function | Defines a set of rules. | yes |

Returns: Builder instance

Usage:

new Builder<Todo>()
    .addModel({id: 1, name: 'Todo 1'})
    .generate() // { id: 1, name: 'Todo 1' }

or

new Builder<Todo>()
    .addModel((faker) => ({
        id: faker.number.int(),
        name: 'Todo 1'
    }))
    .generate() // { id: 9763, name: 'Todo 1' }

addSet

Parameters:

| Name | Type | Description | required | |-----------|-------------------------|------------------------------------------------|:--------:| | name | string | The set name | yes | | dataSet | Partial<T> / Function | The dataset to apply when the set is specified | yes |

Returns: Builder instance

Usage:

new Builder<Todo>()
    .addSet('todo done', {id: 1, name: 'Todo 1', done: true})
    .useSet('todo done')
    .generate() // { id: 1, name: 'Todo 1', done: true }

or

new Builder<Todo>()
    .addSet('todo done', (faker) => ({
        id: faker.number.int(),
        name: 'Todo 1',
        done: true
    }))
    .useSet('todo done')
    .generate() // { id: 9763, name: 'Todo 1', done: true }

clone

Description: Clone hte internal state into a new so that both are isolated from each other

Returns: new Builder instance

Usage:

new Builder<Todo>().clone()

generate

Parameters:

| Name | Type | Description | required | note | |----------|----------|----------------------------------|:--------:|----------------------------------------------------------------| | length | number | The number of instances to spawn | no | If you don't pass a length, only one entity will be generated. |

Returns: T instance or collection of T

Usage:

new Builder<Todo>()
    .addModel({id: 1, name: 'Todo 1'})
    .generate() // { id: 1, name: 'Todo 1' }

or

new Builder<Todo>()
    .addModel({id: 1, name: 'Todo 1'})
    .generate(2) // [{ id: 1, name: 'Todo 1' }, { id: 1, name: 'Todo 1' }]

ruleFor

Parameters:

| Name | Type | Description | required | |-----------------|------------------------------|-----------------------|:--------:| | property | P extends keyof T / string | Property of an entity | yes | | valueFunction | T[keyof T] / Function | Value of a property | yes |

Returns: Builder instance

Usage:

new Builder<Todo>()
    .ruleFor('id', 1)
    .generate() // { id: 1 }

or

new Builder<Todo>()
    .ruleFor('id', () => 1)
    .generate() // { id: 1 }

or

new Builder<Todo>()
    .ruleFor('id', (faker) => faker.number.int())
    .generate() // { id: 1564 }

useSeed

Parameters:

| Name | Type | Description | required | |--------|----------|-----------------|:--------:| | seed | number | The seed to set | yes |

Returns: number

Usage:

new Builder<Todo>().useSeed(1) // 1

useSet

Parameters:

| Name | Type | Description | |--------|----------|--------------| | name | string | The set name |

Returns: Builder instance

Usage:

new Builder<Todo>()
    .addSet('todo done', {id: 1, name: 'Todo 1', done: true})
    .useSet('todo done')

or

new Builder<Todo>()
    .addSet('todo done', (faker) => ({
        id: faker.number.int(),
        name: 'Todo 1',
        done: true
    }))
    .useSet('todo done')