\n\n## Features\n\n- **Tiny & tree-shakeable** -- zero dependencies, ships ESM + CJS, `sideEffects: false`. You bundle only the decoders you import, and the [`mini` entry point](#the-mini-entry-point) drops the class wrapper for about 1 kB less.\n- **Rich, structured errors** -- every failure is a `{ message, path }` issue, and _all_ failures are reported at once, not just the first.\n- **Standard Schema compliant** -- decoders implement the [Standard Schema](https://standardschema.dev) spec, so they drop straight into any Standard-Schema-aware tool.\n- **Type inference** -- derive your static types from the decoders themselves with `FromDecoder`. No duplicate interfaces to keep in sync.\n\n## Installation\n\n```bash\nnpm install ts.data.json\n```\n\n## Quick example\n\nOne import gives you every decoder:\n\n```ts\nimport * as JsonDecoder from 'ts.data.json';\n```\n\nDescribe the shape you expect, then let TypeScript infer the type from it:\n\n```ts\nconst userDecoder = JsonDecoder.object({\n id: JsonDecoder.number(),\n name: JsonDecoder.string(),\n roles: JsonDecoder.array(JsonDecoder.string()),\n lastLogin: JsonDecoder.nullable(JsonDecoder.string().map(iso => new Date(iso)))\n});\n\n// No separate interface needed:\ntype User = JsonDecoder.FromDecoder;\n// { id: number; name: string; roles: string[]; lastLogin: Date | null }\n```\n\nDecode trusted-looking data and get back a typed value:\n\n```ts\nconst result = userDecoder.decode({\n id: 123,\n name: 'Marty McFly',\n roles: ['user', 'premium'],\n lastLogin: '1985-10-26T01:21:00Z'\n});\n\nif (result.isOk()) {\n const user: User = result.value;\n console.log(`Welcome back, ${user.name}!`);\n}\n```\n\nWhen the data is wrong, you get structured issues that point at exactly what failed:\n\n```ts\nconst result = userDecoder.decode({\n id: 'not-a-number', // should be a number\n name: 'Marty McFly',\n roles: ['user', 42], // 42 should be a string\n lastLogin: null\n});\n\nif (!result.isOk()) {\n result.issues.forEach(issue => {\n console.log(`${JsonDecoder.formatIssuePath(issue.path)}: ${issue.message}`);\n });\n // id: \"not-a-number\" is not a valid number\n // roles[1]: 42 is not a valid string\n}\n```\n\n## The `mini` entry point\n\n`ts.data.json/mini` is the same library without the `Decoder` class. A decoder is a plain function `(json) => Result`, and the methods become standalone imports:\n\n```ts\nimport * as J from 'ts.data.json/mini';\n\nconst userDecoder = J.object({\n id: J.number(),\n name: J.string()\n});\n\ntype User = J.FromDecoder; // { id: number; name: string }\n\nJ.decode(userDecoder, json); // Result, never throws\nJ.parse(userDecoder, json); // User, throws on failure\nJ.map(J.string(), iso => new Date(iso)); // instead of .map()\n```\n\nBoth entry points bundle only the decoders you import. What `mini` removes is the fixed cost of the class: its prototype and the per-instance Standard Schema property, neither of which a bundler can drop. Measured against the published build, minified and gzipped:\n\n| What you import | main entry | `mini` |\n| ------------------------------------------- | --------------- | --------------- |\n| `string()` alone | 1457 B / 631 B | 452 B / 269 B |\n| object + string + number + array + optional | 2562 B / 1033 B | 1451 B / 673 B |\n| the whole API | 6909 B / 2214 B | 6057 B / 2108 B |\n\nSo the saving is about 1 kB minified, which matters most for an app that uses only a few decoders. Reach for `mini` when you are counting bytes, and for the main entry when you prefer the chained method style.\n\nOne thing to know:\n\n- `mini` exports a `Decoder` type, but it is a function type, not the class. Decoders from the two entry points are not interchangeable, so pick one per project.\n\n## Documentation\n\nFull, auto-generated API docs and guides live on the [documentation site](https://joanllenas.github.io/ts.data.json/):\n\n- [Basic Usage](https://joanllenas.github.io/ts.data.json/latest/documents/Basic_Usage.html)\n- [Advanced Usage](https://joanllenas.github.io/ts.data.json/latest/documents/Advanced_Usage.html)\n- [Migrating from v2 to v3](https://joanllenas.github.io/ts.data.json/v3.0.0/documents/Migrating_to_v3.html)\n- [Migrating from v3 to v4](https://joanllenas.github.io/ts.data.json/latest/documents/Migrating_to_v4.html)\n\nNew to JSON decoding? The introductory article [Decoding JSON with TypeScript](https://dev.to/joanllenas/decoding-json-with-typescript-1jjc) explains the how and why (slightly dated, but the ideas still hold).\n\n## Related libraries\n\n- [zod](https://github.com/colinhacks/zod)\n- [valibot](https://github.com/fabian-hiller/valibot)\n- [io-ts](https://github.com/gcanti/io-ts)\n\n## License\n\nReleased under the [BSD-3-Clause](LICENSE) license.\n","readmeFilename":"README.md"}
![\"All](\"assets/media/all-your-json-are-belong-to-us.jpg\")
\n \n