{"id":51199979,"url":"https://github.com/antistructured/sigiljs","last_synced_at":"2026-06-28T00:00:50.324Z","repository":{"id":343483127,"uuid":"1177300072","full_name":"antistructured/sigiljs","owner":"antistructured","description":"Turns JavaScript data structures into executable contracts.","archived":false,"fork":false,"pushed_at":"2026-06-25T23:50:49.000Z","size":6692,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-26T01:12:44.259Z","etag":null,"topics":["bun","contracts","data-contracts","executable-contracts","javascript","json-schema","openapi","runtime","runtime-contracts","schema","sigil","type-checking","types","typescript","validation","zero-dependencies","zero-dependency"],"latest_commit_sha":null,"homepage":"https://github.com/antistructured/sigiljs#readme","language":"JavaScript","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/antistructured.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/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":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-09T22:33:40.000Z","updated_at":"2026-06-25T23:50:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/antistructured/sigiljs","commit_stats":null,"previous_names":["weipertda/sigiljs","antistructured/sigiljs"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/antistructured/sigiljs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antistructured%2Fsigiljs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antistructured%2Fsigiljs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antistructured%2Fsigiljs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antistructured%2Fsigiljs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antistructured","download_url":"https://codeload.github.com/antistructured/sigiljs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antistructured%2Fsigiljs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34872279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"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":["bun","contracts","data-contracts","executable-contracts","javascript","json-schema","openapi","runtime","runtime-contracts","schema","sigil","type-checking","types","typescript","validation","zero-dependencies","zero-dependency"],"created_at":"2026-06-28T00:00:32.851Z","updated_at":"2026-06-28T00:00:50.287Z","avatar_url":"https://github.com/antistructured.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SigilJS\n\nExecutable data contracts for JavaScript runtime boundaries.\n\nDefine structure once, then enforce, transform, project, and prove it across runtime boundaries.\n\n\u003cimg src=\"assets/images/sigiljs-logo-banner-v1.png\" alt=\"SigilJS – Executable Data Contracts in Plain JS\" width=\"100%\" height=\"auto\"\u003e\n\n---\n\n## Install\n\n```bash\nnpm install @weipertda/sigiljs\n```\n\nor:\n\n```bash\nbun add @weipertda/sigiljs\n```\n\nSigilJS is written in JavaScript and ships TypeScript declarations for public API consumption.\nThe declarations are intentionally conservative: they describe the runtime API, but do not yet infer precise object shapes from every contract definition. For typed usage, pass an explicit generic such as `sigil.exact\u003cUser\u003e(...)`; see [`docs/typescript.md`](docs/typescript.md).\n\n---\n\n## 30-second example\n\n```js\nimport { oneOf, optional, sigil } from '@weipertda/sigiljs';\n\nconst User = sigil.exact({\n  id: String,\n  email: String,\n  role: oneOf('admin', 'user'),\n  age: optional(Number),\n});\n\nconst result = User.safeParse(unknownInput);\n\nif (result.success) {\n  // result.data is trusted — id, email, role, age are verified\n  saveUser(result.data);\n} else {\n  console.error(result.error.message);\n}\n```\n\n---\n\n## Five pillars\n\n| Pillar | Purpose | Methods |\n|--------|---------|---------|\n| **Define** | Declare structure in JavaScript | `sigil()`, `sigil.exact()`, `optional()`, `oneOf()`, `union()` |\n| **Enforce** | Validate runtime data | `parse()`, `safeParse()`, `assert()`, `check()` |\n| **Transform** | Normalize trusted data | `transform()`, `pipe()`, `trim()`, `serialize()` |\n| **Project** | Generate tooling artifacts | `toJSONSchema()`, `toTypeScript()`, `toOpenAPI()`, `toFormConstraints()`, `describe()` |\n| **Prove** | Test contract behavior | `mock()`, `cases()`, `test()`, `diff()` |\n\n---\n\n## Why SigilJS\n\nData crosses runtime boundaries constantly — API responses, form submissions, database rows, AI outputs, CLI inputs. That data is untrusted until a contract enforces it.\n\nSigilJS provides one contract object per shape that you can:\n- enforce at any runtime boundary\n- project into JSON Schema, TypeScript, OpenAPI, or form metadata\n- use to generate test fixtures and run self-tests\n- compare across versions with structural diffs\n- consume from TypeScript projects without missing declaration errors\n\nA sigil is not a schema. It is a contract object that lives in your JavaScript and travels with your data.\n\n---\n\n## Boundary examples\n\nUse SigilJS anywhere data crosses a boundary: APIs, databases, forms, events, queues, webhooks, config files, local storage, plugin systems, and AI structured outputs.\n\n### API response\n\n```js\nconst ApiResponse = sigil.exact({\n  id: String,\n  name: String,\n  role: oneOf('admin', 'user'),\n});\n\nconst result = ApiResponse.safeParse(await response.json());\n\nif (!result.success) {\n  throw new Error(`Unexpected API shape: ${result.error.message}`);\n}\nreturn result.data;\n```\n\n### Database record\n\n```js\nconst UserRecord = sigil.exact({\n  id: String,\n  email: String,\n  role: oneOf('admin', 'user'),\n  createdAt: String,\n});\n\nconst user = UserRecord.parse(rowFromDatabase);\n```\n\n### Form submission\n\n```js\nconst SignupForm = sigil.exact({\n  name: String,\n  email: String,\n  plan: oneOf('free', 'pro'),\n});\n\nconst result = SignupForm.safeParse(formValues);\nif (!result.success) {\n  showFieldError(result.error.path?.at(-1), result.error.message);\n}\n```\n\n### AI structured output\n\n```js\nconst LeadIntent = sigil.exact({\n  name: String,\n  urgency: oneOf('low', 'medium', 'high'),\n  summary: String,\n});\n\n// JSON Schema bridges the contract to LLM structured output APIs\nconst schema = LeadIntent.toJSONSchema();\n// Pass schema to your LLM provider as the output format\n\nconst result = LeadIntent.safeParse(llmOutput);\nif (result.success) {\n  handleTrustedLead(result.data);\n}\n```\n\nMore boundary recipes: [`docs/recipes/`](docs/recipes/index.md)\n\n---\n\n## Stable API quick map\n\n```js\n// Define\nimport { sigil, optional, oneOf, union, pipe, trim } from '@weipertda/sigiljs';\n\nsigil.exact(definition)       // exact object contract\n\n// Enforce\ncontract.parse(value)         // throws on invalid\ncontract.safeParse(value)     // { success, data } | { success, error }\ncontract.assert(value)        // throws on invalid, returns void\ncontract.check(value)         // boolean\n\n// Transform\ncontract.transform(fn)        // returns new contract with transform\ncontract.serialize(value)     // validates and returns\n\n// Project\ncontract.describe()           // stable contract description model\ncontract.toJSONSchema()       // JSON Schema\ncontract.toTypeScript(name)   // TypeScript type declaration\ncontract.toOpenAPI()          // OpenAPI schema\ncontract.toFormConstraints()  // form field metadata (experimental)\n\n// Prove\ncontract.mock()               // deterministic valid sample\ncontract.cases()              // { valid, invalid } test case sets\ncontract.test(cases)          // run and report contract behavior\ncontract.diff(other)          // structural change report\n```\n\nSee [`docs/api.md`](docs/api.md) for the full API reference.\n\n---\n\n## Projection example\n\n```js\nconst User = sigil({ id: String, name: String, email: String },\n  { name: 'User', version: '1.0.0' });\n\nUser.toJSONSchema();\nUser.toTypeScript('User');\nUser.toOpenAPI();\nUser.describe();\n```\n\n---\n\n## Contract diff example\n\n```bash\nsigil diff contracts/user-v1.sigil contracts/user-v2.sigil\n```\n\n```\nContract changes:\n\nBREAKING\n- required property: email\n\nNON-BREAKING\n- added property: displayName\n```\n\n---\n\n## CLI (experimental)\n\nSigilJS includes a dependency-free CLI for contract workflows. The CLI is **Bun-first and experimental** — commands, output shapes, exit-code guarantees, CWD/module-loading behavior, and `.sigil` compatibility may change before 1.0.0.\n\n```bash\nsigil check contracts/user.sigil data/user.json\nsigil json-schema contracts/user.sigil\nsigil types contracts/user.sigil User\nsigil mock contracts/user.sigil\nsigil cases contracts/user.sigil.js\nsigil diff contracts/user-v1.sigil contracts/user-v2.sigil\n```\n\nThe CLI supports both `.sigil` text files and `.sigil.js` JavaScript module files.\n\nSee [`docs/cli.md`](docs/cli.md) and [`examples/cli/`](examples/cli/README.md).\n\n---\n\n## Experimental features\n\nThe following APIs are experimental — they are tested and usable, but their surface may change before 1.0.0:\n\n- **HTTP helpers** — `httpContract()` for framework-neutral request/response boundaries\n- **Form constraints** — `contract.toFormConstraints()` for form field metadata\n- **CLI workflows** — `sigil` bin for terminal contract workflows\n\nSee [`docs/experimental.md`](docs/experimental.md).\n\nFuture `@sigil/*` package extraction is intentionally deferred until the core API stabilizes at 1.0.0.\n\n---\n\n## Docs\n\n**Getting started**\n- [Public API](docs/api.md)\n- [Quickstart](docs/quickstart.md)\n- [Sigils](docs/sigils.md)\n- [Stability Map](docs/stability.md)\n- [Known Limitations](docs/known-limitations.md)\n\n**Real-world recipes**\n- [All recipes](docs/recipes/README.md)\n- [Full Lifecycle](docs/recipes/full-lifecycle.md) — all five pillars in one workflow ⭐\n- [API Route](docs/recipes/api-route.md)\n- [LLM Output](docs/recipes/llm-output.md)\n- [Form Submission](docs/recipes/form-submission.md)\n- [Database Persistence](docs/recipes/database-persistence.md)\n- [Contract Testing](docs/recipes/contract-testing.md)\n\n**CLI**\n- [CLI Reference](docs/cli.md)\n- [CLI Overview](docs/cli/overview.md)\n- [CLI Contract Files](docs/cli/contract-files.md)\n- [CLI Projections](docs/cli/projections.md)\n- [CLI Prove](docs/cli/prove.md)\n\n**Boundaries**\n- [HTTP Boundary Helpers](docs/projections/http.md)\n- [Form Contracts](docs/forms/form-contracts.md)\n- [Database Record Contracts](docs/database/record-contracts.md)\n- [AI Structured Output](docs/projections/ai-structured-output.md)\n- [Boundary Recipes](docs/recipes/index.md)\n\n**Projections**\n- [JSON Schema](docs/projections/json-schema.md)\n- [OpenAPI](docs/projections/openapi.md)\n- [Forms Projection](docs/projections/forms.md)\n- [Testing Helpers](docs/projections/testing.md)\n\n**Testing**\n- [Contract-Driven Testing](docs/testing.md)\n\n**Reference**\n- [Experimental APIs](docs/experimental.md)\n- [Package Split Policy](docs/package-split.md)\n- [SigilJS vs Zod](docs/sigil-vs-zod.md)\n- [Full docs index](docs/README.md)\n\n---\n\n## SigilJS vs Zod\n\nZod is a mature, expressive TypeScript-first validation library with a large ecosystem. SigilJS is a smaller executable data contract system for teams that want one readable runtime contract object they can enforce, transform, describe, and project across system boundaries without a TypeScript compiler dependency.\n\nSigilJS does not claim to replace Zod. It is a focused alternative when you need runtime contracts with zero runtime dependencies, cross-boundary projection workflows, and a CLI for contract tooling.\n\n---\n\n## Status\n\nVersion `0.18.0`. Core API is ready for broader public 0.x usage feedback, but this is not a 1.0.0 release. HTTP helpers, form constraints, and CLI are experimental.\n\nSee [`docs/stability.md`](docs/stability.md) and [`docs/known-limitations.md`](docs/known-limitations.md).\n\n---\n\n## License\n\nMIT\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantistructured%2Fsigiljs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantistructured%2Fsigiljs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantistructured%2Fsigiljs/lists"}