Quik Framework :: Faker

• Codename: Berlin
• Version: 0.2.0-beta.76
• License: Check license here

Declarative fake data generation and anonymization for Quik database models. Generates realistic demo records and replaces PII in existing rows using a JSON spec file and @faker-js/faker.

Installation

pnpm add @quik/faker

Usage

Module setup

import { Module as FakerModule } from '@quik/faker';

await FakerModule.setup({ /* bootstrap options */ });

1. Generate a spec file

Run the CLI command after your application has booted (so all QModel entities are registered):

quik faker:spec:generate
# writes ./faker.spec.json

quik faker:spec:generate --output ./config/faker.spec.json
quik faker:spec:generate --entities User Product Order

The generated file contains one entry per QModel entity with heuristic generator suggestions based on field names and types. Edit it before running the engines.

2. Spec file format

{
  "locale": "en",
  "seed": null,
  "models": {
    "User": {
      "mode": "generate",
      "count": 100,
      "batchSize": 500,
      "fields": {
        "id":        { "skip": true },
        "createdAt": { "skip": true },
        "updatedAt": { "skip": true },
        "name":      { "generator": "person.fullName" },
        "email":     { "generator": "internet.email", "unique": true },
        "phone":     { "generator": "phone.number", "args": ["+40 ### ### ###"] },
        "age":       { "generator": "number.int", "args": [{ "min": 18, "max": 80 }] },
        "bio":       { "generator": "lorem.paragraph", "nullable": true, "nullRate": 0.2 }
      }
    }
  }
}

Field	Description
locale	BCP-47 locale tag: en, de, es, fr, it, nl, pt, ro. Defaults to "en".
seed	Integer seed for reproducible output. null for random.
mode	"generate" → INSERT new rows. "anonymize" → UPDATE existing rows in place.
count	Number of rows to insert (generate mode). Defaults to 100.
batchSize	INSERT batch size or SELECT page size (anonymize mode). Defaults to 500.
tableName	Override the DB table name. Defaults to the model/entity name.
fields[x].generator	Dot-path into the faker API, e.g. "person.fullName", "internet.email".
fields[x].args	Positional arguments spread into the faker call.
fields[x].skip	Omit from generation entirely. Use for PKs, FKs, and auto-timestamps.
fields[x].unique	Retry until a unique value is produced (generate mode, up to 100 attempts).
fields[x].nullable	Randomly set to null at nullRate probability (default 0.1).

3. Generate fake records

quik faker:generate
# uses ./faker.spec.json, runs all generate-mode models

quik faker:generate --spec ./config/faker.spec.json --model User

4. Anonymize existing records

Anonymize mode reads existing rows in batches, replaces the configured fields, and writes them back. PKs, FK columns, and any field marked skip: true are preserved.

quik faker:anonymize
# uses ./faker.spec.json, runs all anonymize-mode models

quik faker:anonymize --spec ./config/faker.spec.json --model User

Switch the model entry to "mode": "anonymize" to use it for anonymization:

{
  "models": {
    "User": {
      "mode": "anonymize",
      "batchSize": 1000,
      "fields": {
        "id":    { "skip": true },
        "name":  { "generator": "person.fullName" },
        "email": { "generator": "internet.email" }
      }
    }
  }
}

Programmatic API

import { QFakerGenerateEngine, QFakerAnonymizeEngine } from '@quik/faker';
import type { QFakerSpec } from '@quik/faker';

const spec: QFakerSpec = { /* … */ };

const generator = new QFakerGenerateEngine();
await generator.runAll(spec);           // all generate-mode models
await generator.run(spec, 'User');      // single model

const anonymizer = new QFakerAnonymizeEngine();
await anonymizer.runAll(spec);          // all anonymize-mode models
await anonymizer.run(spec, 'User');     // single model

Generate a spec programmatically

import { generateSpec } from '@quik/faker';

const spec = generateSpec();                        // all registered QModel entities
const partial = generateSpec(['User', 'Product']);  // specific entities only

Configuration

• faker.specPath — default spec file path used by CLI commands. Defaults to "./faker.spec.json".

API Highlights

• QFakerGenerateEngine — inserts batches of fake rows; supports unique-value enforcement per field.
• QFakerAnonymizeEngine — paginates existing rows and updates PII fields in place.
• generateSpec(entityNames?) — introspects registered QModel entities and returns a starter QFakerSpec.
• resolveGenerator(faker, path, args?) — calls any faker method by dot-path string.
• createFakerInstance(spec) — builds a locale- and seed-configured faker instance from a spec.
• QFakerError — error thrown by engines on invalid generator paths or exhausted unique retries.

CLI Commands

Command	Description
faker:spec:generate	Write a starter spec from registered QModel entities
faker:generate	INSERT fake rows for all generate-mode models in the spec
faker:anonymize	UPDATE existing rows for all anonymize-mode models in the spec

All commands accept --spec <path> and --model <name> flags.

Testing and Coverage

pnpm test

See the root instructions for coverage details.

API Reference

Generated API documentation is available in the faker API section.