{"id":19806486,"url":"https://github.com/monade/json-api-parser","last_synced_at":"2026-03-15T08:11:39.233Z","repository":{"id":57683109,"uuid":"475813234","full_name":"monade/json-api-parser","owner":"monade","description":"A parser for JSON:API format that maps data to models using decorators, inspired by retrofit.","archived":false,"fork":false,"pushed_at":"2025-01-28T08:43:39.000Z","size":48,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-25T13:04:13.625Z","etag":null,"topics":["json","json-api","json-api-response","typescript"],"latest_commit_sha":null,"homepage":"https://monade.io/en/home-en/","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/monade.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2022-03-30T09:41:35.000Z","updated_at":"2025-01-28T08:43:43.000Z","dependencies_parsed_at":"2024-04-16T10:45:17.560Z","dependency_job_id":"ff55042f-ae36-4100-9c58-272300fa5e18","html_url":"https://github.com/monade/json-api-parser","commit_stats":{"total_commits":7,"total_committers":1,"mean_commits":7.0,"dds":0.0,"last_synced_commit":"c651bb4ee0b9571fcafc70757545804d69542f89"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monade%2Fjson-api-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monade%2Fjson-api-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monade%2Fjson-api-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monade%2Fjson-api-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/monade","download_url":"https://codeload.github.com/monade/json-api-parser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251840152,"owners_count":21652289,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["json","json-api","json-api-response","typescript"],"created_at":"2024-11-12T09:07:41.501Z","updated_at":"2025-11-11T19:28:59.048Z","avatar_url":"https://github.com/monade.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Tests](https://github.com/monade/json-api-parser/actions/workflows/test.yml/badge.svg)\n[![npm version](https://badge.fury.io/js/@monade%2Fjson-api-parser.svg)](https://badge.fury.io/js/@monade%2Fjson-api-parser)\n\n# @monade/json-api-parser\n\nThis library provides a parser for the [JSON:API](https://jsonapi.org/) format, enabling seamless mapping of JSON data to TypeScript/JavaScript models using decorators.\n\n## Table of Contents\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Features](#features)\n    - [Model Declaration](#model-declaration)\n    - [The Parser](#the-parser)\n- [Full Example](#full-example)\n- [Zod Interoperability (Experimental)](#zod-interoperability-experimental)\n- [TODO](#todo)\n\n\n## Installation\n\nInstall the package via npm:\n\n```bash\n  npm install @monade/json-api-parser\n```\n\n## Quick Start\nTo get started, simply declare your models using the `@JSONAPI` and `@Attr` decorators and use the `Parser` class to parse JSON:API data.\n\n```typescript\nimport { JSONAPI, Attr, Parser } from \"@monade/json-api-parser\";\n\n@JSONAPI(\"posts\")\nclass Post {\n  @Attr() title: string;\n}\n\nconst jsonData = /* fetch your JSON:API data here */;\nconst parsedData = new Parser(jsonData).run\u003cPost[]\u003e();\n```\n\n## Features\n### Models declaration\n**`@JSONAPI(type: string)`**\n\nThis decorator acts as the entry point for declaring a JSON:API model. It maps a JSON:API object type to the decorated class.\n\n```typescript\n@JSONAPI(\"posts\")\nclass Post extends Model {}\n```\n\n**`@Attr([name?: string, options?: { parser?: Function, default?: any }])`**\n\nThis decorator is used for declaring attributes on a JSON:API model. You can optionally specify a different name for the attribute, a default value and a parser function to transform the data.\n\n```typescript\n@JSONAPI(\"posts\")\nclass Post extends Model {\n  @Attr() title: string;\n}\n```\n\n**`@Rel([name?: string, options?: { parser?: Function, default?: any }])`**\n\nUse this decorator to declare relationships between JSON:API models. You can optionally specify a different name for the relationship, a default value and a parser function to transform the data.\n\n```typescript\n@JSONAPI(\"posts\")\nclass Post extends Model {\n  @Rel() author: User;\n}\n```\n\n### The Parser\nThe Parser class is responsible for transforming JSON:API objects into instances of the declared models. To use it, create a new instance of `Parser` and call its `run\u003cT\u003e` method.\n\nExample:\nUsage:\n```typescript\nconst jsonData = await fetch('https://some-api.com/posts').then(e =\u003e e.json());\nconst parsedData = new Parser(jsonData).run\u003cPost[]\u003e();\n```\n\n## Full Example\n\n```typescript\nimport { Attr, JSONAPI, Model, Rel } from \"@monade/json-api-parser\";\n\nexport const DateParser = (data: any) =\u003e new Date(data);\n\n@JSONAPI(\"posts\")\nexport class Post extends Model {\n  @Attr() name!: string;\n  @Attr(\"description\") content!: string;\n  @Attr(\"created_at\", { parser: DateParser }) createdAt!: Date;\n  @Attr(\"active\", { default: true }) enabled!: boolean;\n  @Attr() missing!: boolean;\n\n  @Rel(\"user\") author!: User;\n  @Rel() reviewer!: User | null;\n}\n\n@JSONAPI(\"users\")\nclass User extends Model {\n  @Attr() firstName!: string;\n  @Attr() lastName!: string;\n  @Attr(\"created_at\", { parser: DateParser }) createdAt!: Date;\n\n  @Rel() favouritePost!: Post;\n}\n```\n\n## Zod Interoperability [EXPERIMENTAL]\nThis library also offers experimental support for [Zod](https://zod.dev/), allowing for runtime type-checking of your JSON:API models.\n\n```typescript\nimport { declareModel, InferModel, modelOfType } from \"@monade/json-api-parser/zod\";\n\nconst UserSchema = declareModel(\n  \"users\",\n  {\n    attributes: z.object({\n      firstName: z.string(),\n      lastName: z.string(),\n      created_at: z.string().transform((v) =\u003e new Date(v)),\n    }),\n\n    relationships: z.object({\n      // Circular references must be addressed like this\n      favouritePost: modelOfType('posts'),\n    }),\n  }\n);\n\nconst PostSchema = declareModel(\n  \"posts\",\n  {\n    attributes: z.object({\n      name: z.string(),\n      description: z.string(),\n      created_at: z.string().transform((v) =\u003e new Date(v)),\n      active: z.boolean().default(true),\n    }),\n    relationships: z.object({ user: UserSchema, reviewer: UserSchema })\n  }\n);\n\ntype User = InferModel\u003ctypeof UserSchema\u003e;\ntype Post = InferModel\u003ctypeof PostSchema\u003e;\n```\n\n## TODO\n* Improve Documentation\n* Edge case tests\n* Improve interoperability with zod\n\n\nAbout Monade\n----------------\n\n![monade](https://monade.io/wp-content/uploads/2023/02/logo-monade.svg)\n\njson-api-parser is maintained by [mònade srl](https://monade.io/en/home-en/).\n\nWe \u003c3 open source software. [Contact us](https://monade.io/en/contact-us/) for your next project!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonade%2Fjson-api-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmonade%2Fjson-api-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonade%2Fjson-api-parser/lists"}