@cxai/faker

Template-based fake data generator for Yjs. Uses @faker-js/faker templates to produce items and push them into Y.Map collections with progress tracking and toggle control.

Install

npm install @cxai/faker

Usage

Standalone — generate items

import { generateFromTemplate, createFakerIterable, createFakerJob } from "@cxai/faker";
import * as Y from "yjs";

// Single item
const user = generateFromTemplate({ id: "{{string.uuid}}", name: "{{person.fullName}}" });

// Async generator (no Yjs dependency)
for await (const { item, progress } of createFakerIterable(template, { count: 5 })) {
  console.log(`${progress}%`, item);
}

// Self-contained Yjs job
const doc = new Y.Doc();
const job = createFakerJob(doc, "users", {
  id: "{{string.uuid}}",
  name: "{{person.fullName}}",
  email: "{{internet.email}}",
}, { count: 20, interval: [200, 500], autoStart: true });

job.getStatus();  // { status: "running", progress: 40 }
job.stop();
job.clear();
job.destroy();

Combined with @cxai/job

import { createFakerIterable } from "@cxai/faker";
import { createJob } from "@cxai/job";

const job = createJob({
  doc,
  path: "products",
  iterable: () => createFakerIterable({ id: "{{string.uuid}}", name: "{{commerce.productName}}" }, { count: 100 }),
});
job.trigger();

Combined with @cxai/yapi

import { createFakerJob } from "@cxai/faker";
import { createApp } from "@cxai/yapi";

const doc = new Y.Doc();
createFakerJob(doc, "orders", template, { count: 50, autoStart: true });

const api = createApp(doc, {
  routes: { "/orders": { collection: "orders", sse: { event: "new-order" } } },
});
// SSE streams fake items as they're generated

HTTP App (@cxai/faker/app)

import fakerApp from "@cxai/faker/app";

fakerApp.config(doc, {
  users: { collection: "users", template: { id: "{{string.uuid}}", name: "{{person.fullName}}" }, options: { count: 10 } },
  orders: { collection: "orders", template: { id: "{{string.uuid}}", total: "{{commerce.price}}" } },
});

app.route("/faker", fakerApp);
// POST /faker/users/start
// POST /faker/users/stop
// POST /faker/users/clear
// GET  /faker/status        — all jobs
// GET  /faker/users/config  — job definition

API Reference

generateFromTemplate<T>(template): T

Generate a single object. Template values are @faker-js/faker expressions like "{{person.fullName}}". Date/time fields are auto-converted to ISO strings.

createFakerIterable<T>(template, options?): AsyncGenerator<{ item: T, progress: number }>

Pure async generator — no Y.Doc dependency.

| Option | Type | Default | Description | |--------|------|---------|-------------| | count | number | 10 | Items to generate | | interval | [min, max] | [1000, 2000] | Delay range in ms between items | | until | Date \| number | — | Stop after this time |

createFakerJob<T>(doc, collection, template, options?)

Self-contained job that pushes into doc.getMap(collection). Returns:

| Method | Description | |--------|-------------| | trigger() | Start generation | | stop() | Abort | | isRunning() | boolean | | getStatus() | { status, progress, lastSyncTime? } | | getItems() | T[] | | clear() | Stop + clear items | | destroy() | Cleanup observers | | paths | { collection, statusPath, togglePath } |

Additional options: autoStart, statusPath, togglePath.

Re-export

export { faker } from "@faker-js/faker"; // convenience re-export

Examples

• @cxai/example-faker-standalone — Standalone faker generation
• @cxai/example-faker-yapi-combined — Faker feeding a yapi SSE endpoint
• @cxai/example-job-app-discovery — Job-based app discovery

See Also

• @cxai/job — Generic async iterable job engine
• @cxai/yapi — Content-negotiated Y.Map server