{"id":36542751,"url":"https://github.com/nick-vanduijn/synthex","last_synced_at":"2026-01-12T05:49:26.501Z","repository":{"id":304961399,"uuid":"1020493756","full_name":"nick-vanduijn/synthex","owner":"nick-vanduijn","description":" A fluent, type-safe TypeScript library for generating mock data from structured schemas ideal for testing, prototyping, and LLM development workflows.","archived":false,"fork":false,"pushed_at":"2025-09-20T20:11:32.000Z","size":120,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-20T22:08:48.553Z","etag":null,"topics":["ai","development","devtools","llm","mocking","production","prototyping","streaming","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nick-vanduijn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-07-16T00:56:55.000Z","updated_at":"2025-09-20T20:11:35.000Z","dependencies_parsed_at":"2025-07-17T16:54:09.967Z","dependency_job_id":"ed579ca3-f00b-492c-9c3f-3a2c922c4001","html_url":"https://github.com/nick-vanduijn/synthex","commit_stats":null,"previous_names":["nick-vanduijn/synthex"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nick-vanduijn/synthex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nick-vanduijn%2Fsynthex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nick-vanduijn%2Fsynthex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nick-vanduijn%2Fsynthex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nick-vanduijn%2Fsynthex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nick-vanduijn","download_url":"https://codeload.github.com/nick-vanduijn/synthex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nick-vanduijn%2Fsynthex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28335325,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"online","status_checked_at":"2026-01-12T02:00:08.677Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai","development","devtools","llm","mocking","production","prototyping","streaming","typescript"],"created_at":"2026-01-12T05:49:26.415Z","updated_at":"2026-01-12T05:49:26.496Z","avatar_url":"https://github.com/nick-vanduijn.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/nick-vanduijn/synthex\"\u003e\n    \u003cimg src=\"images/logo.png\" alt=\"Logo\" width=\"80\" height=\"80\"\u003e\n  \u003c/a\u003e\n\n  \u003ch3 align=\"center\"\u003eSynthex\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    Type-safe Mocking for LLMs \u0026 Structured APIs  \n  \u003c/p\u003e\n\n  ![npm version](https://img.shields.io/npm/v/synthex?color=brightgreen\u0026label=npm)\n  ![types](https://img.shields.io/npm/types/synthex?label=types)\n  ![downloads](https://img.shields.io/npm/dt/synthex?color=blue)\n  ![license](https://img.shields.io/npm/l/synthex?color=orange)\n  ![build](https://img.shields.io/github/actions/workflow/status/nick-vanduijn/synthex/ci.yml?branch=main\u0026label=build)\n\u003c/div\u003e\n\n\n## Table of Contents\n\n- [Install](#install)\n- [Features](#features)\n- [Example Usage](#-example-usage)\n- [Sample Output](#-sample-output)\n- [API Overview](#api-overview)\n- [Streaming / LLM Simulation](#streaming--llm-simulation)\n- [Why Synthex?](#why-synthex)\n- [Documentation](#documentation)\n- [More Examples](#more-examples)\n- [CLI Demo](#cli-demo)\n- [FAQ](#faq)\n- [Contributing](#contributing)\n- [License](#license)\n## Documentation\n\nFor a comprehensive usage guide, advanced schema patterns, and API reference, see:\n\n- [docs/USAGE.md](docs/USAGE.md)\n\n---\n\n## More Examples\n\n- `node examples/form-demo.cjs` — Interactive form mocker\n- `node examples/llm-demo.cjs` — LLM-style streaming and error demo\n- `node examples/advanced-demo.cjs` — Advanced: nested, error, streaming, and conditional fields\n\n---\n\n\n## The Problem\n\nWhen building AI or LLM-powered applications, testing and prototyping can be painfully slow. Every time you want to check a new feature, you have to wait for your LLM to respond—sometimes for seconds or even minutes. This slows down your feedback loop, makes debugging tedious, and can rack up unnecessary API costs.\n\n**Synthex** solves this by letting you instantly simulate type-safe, realistic LLM or API responses. You can test your code, validate edge cases, and iterate rapidly—without waiting for a real LLM or burning tokens. Save time, move faster, and focus on building, not waiting.\n\n## Install\n\n```bash\nnpm install synthex\n```\n\nhttps://www.npmjs.com/package/synthex\n\n## Features\n\n- **Type-safe schema builder**: primitives, objects, enums, unions, intersections\n- **Realistic mock data** for testing, prototyping, or LLM scaffolding\n- **Conditional fields** with probabilities\n- **Simulated errors** for edge-case testing\n- **Streaming mock generation** — mimic LLM token flow\n- **Context-aware** field templates (e.g. IDs, tokens, slugs)\n- **Test-friendly metadata**: timestamps, token usage, finish reasons\n- **Composable** schema API, like Zod but mock-first\n- **Markdown \u0026 JSON formatters** for quick debugging\n- **Plugin system**: extend or override field generation logic\n- **Schema import/export**: JSON/YAML, CLI utilities\n- **LLM simulation**: hallucination (for all types, including enums), function-calling, streaming, error injection\n- **Performance profiling utility**: measure mock generation speed\n- **Lite entry point**: minimal bundle for browser or edge\n- **CI/CD ready**: robust tests, linting, and GitHub Actions\n\n## Example Usage\n\n```ts\nimport { s, MockGenerator } from 'synthex';\n\nconst userSchema = s\n  .object({\n    id: s.uuid().required(),\n    name: s.string().min(2).max(50).required(),\n    email: s.email().required(),\n    age: s.number().min(18).max(99),\n    isActive: s.boolean(),\n    role: s.enum(['user', 'admin', 'moderator']),\n    profile: s\n      .object({\n        bio: s.string().max(160),\n        website: s.url(),\n      })\n      .optional(),\n  })\n  .build('UserSchema');\n\nconst generator = new MockGenerator({ seed: 42 });\nconst mock = generator.generate(userSchema);\n\nconsole.log(mock.data);\n```\n\n## Sample Output\n\n```json\n{\n  \"id\": \"8c5d3a91-14b4-4c5b-a301-cb837b66f0a1\",\n  \"name\": \"Ava Jackson\",\n  \"email\": \"ava.jackson@example.com\",\n  \"age\": 35,\n  \"isActive\": true,\n  \"role\": \"admin\",\n  \"profile\": {\n    \"bio\": \"Developer. Writer. Tinkerer.\",\n    \"website\": \"https://ava.dev\"\n  }\n}\n```\n\n## API Overview\n\n| Type               | Builder                            |\n|--------------------|------------------------------------|\n| String             | `s.string()`                       |\n| Number             | `s.number()`                       |\n| Boolean            | `s.boolean()`                      |\n| Date / Time        | `s.date().format()`                |\n| Email, URL, UUID   | `s.email()`, `s.url()`, `s.uuid()` |\n| Arrays             | `s.array(s.string())`              |\n| Objects            | `s.object({...})`                  |\n| Enums              | `s.enum(['a', 'b'])`               |\n| Conditional Fields | `.probability(0.5)`                |\n| Error Simulation   | `.simulateError(true)`             |\n| Streaming Output   | `generator.streamGenerate()`       |\n\n\n## Streaming / LLM Simulation \u0026 Hallucination\n\n```ts\nconst generator = new MockGenerator({\n  hallucinate: true, // Enable hallucination for all fields\n  hallucinationProbability: 0.5, // 50% chance per field\n  seed: 123,\n});\nconst mock = generator.generate(userSchema);\nconsole.log(mock.data);\n\n// Streaming (mimic LLM token flow)\nconst stream = generator.streamGenerate(userSchema, { chunkSize: 10, delayMs: 50 });\nfor await (const chunk of stream) {\n  process.stdout.write(chunk);\n}\n```\n\n**Advanced:**\n- Hallucination works for all field types (string, number, boolean, array, object, enum, etc.)\n- Simulate OpenAI-style function-calling, error injection, and role-based responses\n\n## Why Synthex?\n\n| Feature                      | Synthex | Zod | Faker | json-schema-faker |\n|------------------------------|:--------:|:---:|:-----:|:-----------------:|\n| Type-safe schema builder     |   ✅     | ✅  |  ❌   |        ❌         |\n| Realistic mock data          |   ✅     | ❌  |  ✅   |        ✅         |\n| Field-level error simulation |   ✅     | ❌  |  ❌   |        ❌         |\n| Streaming LLM-like output    |   ✅     | ❌  |  ❌   |        ❌         |\n| Composable API               |   ✅     | ✅  |  ❌   |   ⚠️ Partial     |\n\n\n## CLI \u0026 Utilities\n\n- **Schema import/export:**\n  ```bash\n  node bin/schema-io.js import ./schema.yaml\n  node bin/schema-io.js export ./schema.json\n  ```\n- **Performance profiling:**\n  ```ts\n  import { profileMockGeneration } from 'synthex/perf';\n  profileMockGeneration(userSchema, 1000);\n  ```\n- **Lite entry point:**\n  ```ts\n  import { s, MockGenerator } from 'synthex/lite';\n  ```\n- **Examples:**\n  - `node examples/form-demo.cjs` — Interactive form mocker\n  - `node examples/llm-demo.cjs` — LLM-style streaming and error demo\n  - `node examples/advanced-demo.cjs` — Advanced: nested, error, streaming, and conditional fields\n\n## FAQ\n\n**Q: What makes this better than Faker?**\nA: Synthex combines type-safety, streaming support, error injection, hallucination, and realistic test metadata. Ideal for LLMs and structured APIs.\n\n**Q: Can I use this to test OpenAI function-calling?**\nA: Yes! It’s designed to simulate real-world outputs for tools/functions, including function-calling mocks and streaming.\n\n**Q: Does it support nesting?**\nA: Yup. Nest objects, arrays, even deeply nested enums and conditional fields.\n\n**Q: How do I handle type-only tests and linting?**\nA: Type-only tests (e.g., `test/types.test.ts`) may trigger `@typescript-eslint/no-unused-vars` for schema variables used only for type inference. Suppress these with `// eslint-disable-next-line @typescript-eslint/no-unused-vars` or use a dummy test to satisfy Jest.\n\n**Q: How do I extend Synthex?**\nA: Use the plugin system to override or extend field generation logic. See [docs/RECIPES.md](docs/RECIPES.md) for advanced patterns.\n\n## Contributing\n\nWe welcome PRs, ideas, and issue reports. Clone the repo and run:\n\n```bash\nnpm run dev\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnick-vanduijn%2Fsynthex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnick-vanduijn%2Fsynthex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnick-vanduijn%2Fsynthex/lists"}