{"id":36955113,"url":"https://github.com/alirezahematidev/fakelab","last_synced_at":"2026-01-13T13:01:39.229Z","repository":{"id":328019904,"uuid":"1113966667","full_name":"alirezahematidev/fakelab","owner":"alirezahematidev","description":"A fast, easy-config mock API server for frontend developers.","archived":false,"fork":false,"pushed_at":"2026-01-04T19:40:22.000Z","size":1714,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-05T15:12:59.294Z","etag":null,"topics":["fakerjs","mock-server","typescript"],"latest_commit_sha":null,"homepage":"https://alirezahematidev.github.io/fakelab/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alirezahematidev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-10T17:58:59.000Z","updated_at":"2025-12-29T16:54:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alirezahematidev/fakelab","commit_stats":null,"previous_names":["alirezahematidev/fakelab"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/alirezahematidev/fakelab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alirezahematidev%2Ffakelab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alirezahematidev%2Ffakelab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alirezahematidev%2Ffakelab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alirezahematidev%2Ffakelab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alirezahematidev","download_url":"https://codeload.github.com/alirezahematidev/fakelab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alirezahematidev%2Ffakelab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28385802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T12:01:30.995Z","status":"ssl_error","status_checked_at":"2026-01-13T12:00:09.625Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fakerjs","mock-server","typescript"],"created_at":"2026-01-13T13:01:38.030Z","updated_at":"2026-01-13T13:01:39.212Z","avatar_url":"https://github.com/alirezahematidev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ![logo](https://raw.githubusercontent.com/alirezahematidev/fakelab/refs/heads/main/src/public/icons/logo24.svg) Fakelab\n\n⚡ A fast, easy-config mock API server for frontend developers.\n\n**[Documentation Website](https://alirezahematidev.github.io/fakelab/)**\n\n## Features\n\n- 🚀 Instant mock server\n- 🗂️ Mock from TypeScript files\n- 📦 Lightweight\n- 🗄️ Persistent database\n- 📸 Snapshot real APIs into mocks\n- 🌐 Network simulation (latency, errors, offline mode)\n- 🔔 Webhooks for event-driven integrations\n\n## Demo\n\nCheck out the [React + TypeScript + Vite example](./examples/react-typescript-vite) to see Fakelab in action!\n\n### Quick Demo\n\n1. Define your types with Faker annotations:\n\n```typescript\n// fixtures/user.ts\nexport interface User {\n  /** @faker string.ulid */\n  id: string;\n  /** @faker person.fullName */\n  name: string;\n  /** @faker location.streetAddress */\n  address: string;\n  /** @faker phone.number */\n  phone: string;\n  /** @faker number.int({min:10,max:80}) */\n  age: number;\n}\n```\n\n2. Configure Fakelab:\n\n```typescript\n// fakelab.config.ts\nimport { defineConfig } from \"fakelab\";\n\nexport default defineConfig({\n  sourcePath: [\"./fixtures\"],\n  server: { port: 50001 },\n});\n```\n\n3. Run the example:\n\n```bash\nnpm run example\n# or\nyarn example\n# or\npnpm run example\n```\n\nOr start the server manually:\n\n`./examples/react-typescript-vite`:\n\n```bash\nnpm run serve\n# or\nyarn serve\n# or\npnpm run serve\n```\n\n## Installation\n\n```bash\nnpm install fakelab --save-dev\n# or\npnpm add -D fakelab\n# or\nyarn add -D fakelab\n```\n\n## Usage/Examples\n\ncreate `fakelab.config.ts` file in the project root. and reference your typescript files.\n\n```typescript\nimport { defineConfig } from \"fakelab\";\n\nexport default defineConfig({\n  sourcePath: [\"./types\", \"./fixtures/**/*.ts\"], // supports glob pattern\n  faker: { locale: \"en\" }, // optional\n  server: { pathPrefix: \"api/v1\", port: 8080 }, // optional\n});\n```\n\n## Faker Annotations\n\nFakelab allows you to control generated mock data using JSDoc tags.\nYou simply annotate your TypeScript interfaces with the @faker tag, and Fakelab uses the corresponding [faker](https://fakerjs.dev/)\nmethod when generating mock values.\n\n`/other/post.ts`:\n\n```typescript\nexport type Post = {\n  id: string;\n  title: string;\n};\n```\n\n`/other/profile.ts`:\n\n```typescript\nexport type Profile = {\n  id: string;\n};\n```\n\n`/types/user.ts`:\n\n```typescript\nexport { type Profile } from \"../other/profile\";\nimport { type Post } from \"../other/post\";\n\nexport interface User {\n  /** @faker string.uuid */\n  id: string;\n\n  /** @faker person.fullName */\n  name: string;\n\n  // Use it as a function to pass the arguments.\n  /** @faker number.int({ max: 10 }) */\n  age: number;\n\n  /** @faker datatype.boolean */\n  admin: boolean;\n\n  /** @faker location.streetAddress */\n  address: string;\n\n  posts: Post[];\n}\n```\n\n**NOTE:** Fakelab only supports `interfaces`, `types`, `named export declarations`.\n\n## Fakelab Runtime\n\n`fakelab/browser` enables `fakelab` module at runtime, allowing your frontend or Node environment to communicate with the running Fakelab mock server.\n\n## `fakelab.url()`\n\nThe base URL of the running Fakelab server.\n\n```ts\nfakelab.url();\n// e.g. \"http://localhost:50000/api\"\n```\n\n## `fakelab.fetch()`\n\nFetch mock data from the Fakelab server by **typescript interface/type name**.\n\n### Signature\n\n```ts\nfakelab.fetch(name: string, count?: number): Promise\u003cT\u003e\n```\n\n### Parameters\n\n| Name    | Type     | Description                            |\n| ------- | -------- | -------------------------------------- |\n| `name`  | `string` | Interface/Type name                    |\n| `count` | `number` | Number of items to generate (optional) |\n\n### Basic example\n\n```ts\nimport { fakelab } from \"fakelab/browser\";\n\nconst users = await fakelab.fetch(\"User\", 10);\n\nconsole.log(users);\n```\n\n**NOTE:** Set count to a negative number to get an empty array.\n\n## Database Mode\n\nFakelab can persist generated mock data to a local database.\n\nUnder the hood, Fakelab uses the lightweight [lowdb](https://github.com/typicode/lowdb)\nlibrary for persistence, ensuring fast reads, simple JSON storage, and zero external dependencies.\n\n### Database Options\n\n```ts\nexport type DatabaseOptions = {\n  enabled: boolean;\n};\n```\n\n### Basic example\n\n```ts\nexport default defineConfig({\n  database: { enabled: true },\n});\n\nimport { database } from \"fakelab/browser\";\n\nconst users = await database.get(\"User\");\n\nconsole.log(users);\n\n// or insert fresh data to database\nawait database.post(\"User\");\n```\n\n### Database Seeding\n\nFakelab supports database seeding to initialize mock data.\n\n```ts\ntype SeedOptions = {\n  count?: number;\n  strategy?: \"reset\" | \"once\" | \"merge\";\n};\n```\n\n### Options\n\n| Name       | Type                     | Description                                                                   |\n| ---------- | ------------------------ | ----------------------------------------------------------------------------- |\n| `count`    | `number`                 | Number of records to generate                                                 |\n| `strategy` | `reset`, `once`, `merge` | Defines how seeding interacts with existing database data. default is `reset` |\n\n- `reset`: Removes all existing data and recreates it from scratch.\n- `once`: Seeds data only if the database is empty.\n- `merge`: Inserts new records and updates existing ones. The total number of items per table is limited to `1000` records.\n\n### Basic example\n\n```ts\nexport default defineConfig({\n  database: { enabled: true },\n});\n\nimport { database } from \"fakelab/browser\";\n\nawait database.seed(\"User\", { count: 10, strategy: \"once\" });\n\n// to flush the database\nawait database.flush(\"User\");\n```\n\n## Snapshot\n\nThe snapshot command allows you to capture a real API response and turn it into a reusable mock source.\n\nThis is useful when you want to:\n\n- Bootstrap mocks from an existing API\n\n- Freeze API responses for offline development\n\n- Generate realistic mock data without writing schemas manually\n\n### Snapshot Options\n\n```ts\nexport type SnapshotDataSource = {\n  url: string;\n  name: string;\n  headers?: SourceHeaders;\n};\n\nexport type SnapshotOptions = {\n  enabled: boolean;\n  sources?: SnapshotDataSource[];\n};\n```\n\n### Usage\n\n```bash\n# Basic usage\nnpx fakelab snapshot [url] [options]\n```\n\n### Options\n\n| Option               | Alias | Description                    |\n| -------------------- | ----- | ------------------------------ |\n| `--name \u003cstring\u003e`    | `-n`  | Specify snapshot source name   |\n| `--refresh \u003cstring\u003e` | `-r`  | Refresh the specified snapshot |\n| `--delete \u003cstring\u003e`  | `-d`  | Delete the specified snapshot  |\n\n### Examples\n\n```bash\n# Basic usage\nnpx fakelab snapshot https://jsonplaceholder.typicode.com/todos\n\n# specify a name for captured source\nnpx fakelab snapshot https://jsonplaceholder.typicode.com/todos --name Todo\n\n# refresh the existing snapshot\nnpx fakelab snapshot --refresh Todo\n\n# delete the existing snapshot\nnpx fakelab snapshot --delete Todo\n\n# update all snapshots\nnpx fakelab snapshot\n```\n\nAlso can define snapshot sources in config, run `npx fakelab snapshot` command to capture them all:\n\n```ts\nexport default defineConfig({\n  sourcePath: [\"./fixtures\"],\n  server: { includeSnapshots: true },\n  snapshot: {\n    enabled: true,\n    sources: [\n      {\n        name: \"Todo\",\n        url: \"https://jsonplaceholder.typicode.com/todos\",\n      },\n      {\n        name: \"Post\",\n        url: \"https://jsonplaceholder.typicode.com/posts\",\n      },\n    ],\n  },\n});\n```\n\n## Network Simulation\n\nFakelab can simulate real-world network conditions such as latency, random failures, timeouts, and offline mode.\nThis is useful for testing loading states, retry logic, and poor network UX without changing frontend code.\n\n### Network Options\n\n```ts\ntype NetworkErrorOptions = {\n  statusCodes?: ErrorStatusCode[];\n  messages?: Record\u003cErrorStatusCode, string\u003e;\n};\n\ntype NetworkBehaviourOptions = {\n  delay?: number | [number, number];\n  errorRate?: number;\n  timeoutRate?: number;\n  offline?: boolean;\n  errors?: NetworkErrorOptions;\n};\n\nexport type NetworkOptions = NetworkBehaviourOptions \u0026 {\n  preset?: string;\n  presets?: Record\u003cstring, NetworkBehaviourOptions\u003e;\n};\n```\n\n### Configuration\n\n```ts\nexport default defineConfig({\n  network: {\n    delay: [300, 1200],\n    errorRate: 0.1,\n    timeoutRate: 0.05,\n    errors: {\n      statusCodes: [400, 404, 500],\n      messages: {\n        400: \"Bad request\",\n        404: \"Not found\",\n        500: \"Server error\",\n      },\n    },\n    presets: { wifi: { errorRate: 1 } },\n    preset: \"wifi\",\n  },\n});\n```\n\n**NOTE:** When both inline network options and a `preset` are defined, inline options always take precedence and override the preset values.\n\n## Webhooks\n\nWebhooks allow you to listen to internal events and send HTTP requests to external services when those events occur.\n\nEach webhook hook subscribes to a specific event and sends a POST request with the event payload (or a transformed payload) to the configured endpoint.\n\n### Configuration\n\n```ts\nimport { defineConfig } from \"fakelab\";\n\nexport default defineConfig({\n  webhook: {\n    enabled: true,\n    hooks: [\n      {\n        name: \"snapshot-captured\",\n        trigger: {\n          event: \"snapshot:captured\",\n        },\n        method: \"POST\",\n        url: \"https://example.com/webhooks/snapshot\",\n        headers: {\n          Authorization: \"Bearer YOUR_TOKEN\",\n        },\n      },\n    ],\n  },\n});\n```\n\n### Hook Options\n\n| Name        | Type                           | Description                                  |\n| ----------- | ------------------------------ | -------------------------------------------- |\n| `name`      | `string`                       | Unique name used for logging and debugging   |\n| `trigger`   | `{ event: TriggerEvent }`      | Event that triggers the webhook              |\n| `method`    | `POST`                         | HTTP method (only POST is supported)         |\n| `url`       | `string`                       | Target webhook endpoint (must be HTTP/HTTPS) |\n| `headers`   | `HttpHeaders (optional)`       | Custom HTTP headers                          |\n| `transform` | `(data) =\u003e unknown (optional)` | Transform event payload before sending       |\n\n### Payload Transformation\n\nBy default, the raw event payload is sent to the webhook endpoint.\n\nYou can customize the payload using the `transform` function:\n\n```ts\ntransform: (data) =\u003e ({\n  ...data,\n  createdAt: new Date().toISOString(),\n});\n```\n\n### Notes \u0026 Limitations\n\n- Only `POST` requests are supported\n- Payloads are sent as `application/json`\n- Webhooks are executed asynchronously\n- Failed webhooks are logged but not retried (yet)\n\n## Server Command\n\nUsage:\n\n```bash\nnpx fakelab serve [options]\n```\n\n### Options\n\n| Option                  | Alias | Description                                           |\n| ----------------------- | ----- | ----------------------------------------------------- |\n| `--source`              | `-s`  | Path to the source typescript file(s) or directory(s) |\n| `--pathPrefix \u003cprefix\u003e` | `-x`  | Prefix for all generated API routes                   |\n| `--locale \u003clocale\u003e`     | `-l`  | Locale used for fake data generation                  |\n| `--port \u003cnumber\u003e`       | `-p`  | Port to run the server on                             |\n| `--fresh-snapshots`     | `-f`  | Capture or refresh all snapshots                      |\n\n### Examples\n\n```bash\n# Basic usage\nnpx fakelab serve\n\n# Custom source and port\nnpx fakelab serve -s ./types -p 4000\n\n# Custom API prefix and locale\nnpx fakelab serve --pathPrefix /v1 --locale fr\n\n# refresh existing snapshots\nnpx fakelab serve --fresh-snapshots\n```\n\n## Related\n\nFakelab is powered by [Fakerjs](https://fakerjs.dev/) library.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falirezahematidev%2Ffakelab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falirezahematidev%2Ffakelab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falirezahematidev%2Ffakelab/lists"}