Eco Faker

CI npm version npm downloads records/sec relational integrity

Stateful, relationally-consistent fake-data generator for e-commerce apps. Every Cart, Order, Shipment, and ReturnRequest is derived from the same underlying state machine, so the dataset reads like a real store's history instead of unrelated fixtures.

Users → Carts → (AbandonedCheckouts | Orders → Shipments → ReturnRequests)

• It's a database, not a pile of JSON. Every order references a real cart, every shipment a real order, every return a real shipment -- financials balance and referential integrity holds by construction. lint/fuzz exist specifically to break that on purpose so you can test what happens when it doesn't.
• It's an API, not just a file. serve turns any dataset into a live REST endpoint in one command, with pagination, filtering, chaos testing, auth, and adapters for MSW, tRPC, GraphQL, Apollo Client, and React Query.
• It tests real systems, not just itself. test --contract/--mutate fire real requests at a live API and check it against an OpenAPI contract. lint --sql --db-url dry-runs real SQL against a real Postgres. warp replays a fixed scenario at a different point in time.

_{Live browser demo (no install) · GitHub · npm}

📖 Full documentation

This README is a landing page, not the reference. The complete docs -- every command, every flag, every adapter, with worked examples -- live at the documentation site, built from docs-site/ (VitePress):

🚀 Getting Started	Installation, quick start, run from source
💻 CLI Reference	Every subcommand: generate, serve, data quality, exports, scaffolding, MCP
📚 Library API	generate()/serialize(), scenarios, configuration, unique values
🔌 Adapters	MSW, tRPC, GraphQL, React Query, Apollo Client
🧪 Testing	Contract/mutation/scenario/Gherkin testing, plus 7 real example projects
🤝 Contributing	Dev setup, project layout, CI, publishing, VS Code extension

Run it locally: cd docs-site && npm install && npm run docs:dev

Try it in 30 seconds

npm install -g eco-faker
my-eco-gen generate --scenario black-friday --users 100 --format sql --output ./seed.sql

No Node? No problem:

docker compose up --build
# Postgres @ localhost:5432 (eco/eco/eco_faker) seeded with a Black Friday dataset

Run it from source (~2 minutes)

git clone https://github.com/Hung1510/Eco-Faker.git
cd Eco-Faker
npm install
npm run build
npm test
node dist/cli.js generate --users 50 --seed 1 --scenario black-friday --format json --output ./eco-data.json
node dist/cli.js serve --users 50 --seed 1 --port 4000 &
curl "http://localhost:4000/api/orders?status=delivered&pageSize=5"

See Run from Source for the full walkthrough, including the exact verification pass CI runs.

What's inside, at a glance

Full-fidelity e-commerce data generation (product catalog, recommendations, inventory, support tickets, transactional emails, fraud/anomaly injection, 73 locales) · a mock REST API (serve) with chaos mode, auth, live feeds, and OpenAPI/Postman export · adapters for MSW, tRPC, GraphQL, React Query, and Apollo Client -- no server required · contract/mutation/scenario/Gherkin testing against any live API · data-quality tooling (lint, fuzz, score, diff) · exports to SQL/CSV/Elasticsearch/ClickHouse/Great Expectations/k6/OpenTelemetry · framework scaffolding for Next.js, MSW, Prisma, Drizzle, and SQLAlchemy · an MCP server · a VS Code extension · and more.

See the CLI Reference for the complete, current list -- this README no longer tries to enumerate every feature itself.

Roadmap

See ROADMAP.md for what's next and the full history of what's been built, why, and every real bug found along the way.