{"id":13527236,"url":"https://github.com/SeyZ/jsonapi-serializer","last_synced_at":"2025-04-01T09:31:18.746Z","repository":{"id":33028621,"uuid":"36664196","full_name":"SeyZ/jsonapi-serializer","owner":"SeyZ","description":"A Node.js framework agnostic library for (de)serializing your data to JSON API","archived":false,"fork":false,"pushed_at":"2023-12-20T12:15:00.000Z","size":797,"stargazers_count":736,"open_issues_count":104,"forks_count":199,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-03-17T20:09:53.315Z","etag":null,"topics":["deserializer","javascript","json-api","serializer"],"latest_commit_sha":null,"homepage":"","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/SeyZ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2015-06-01T13:57:56.000Z","updated_at":"2025-01-19T22:55:23.000Z","dependencies_parsed_at":"2024-06-18T12:14:33.395Z","dependency_job_id":null,"html_url":"https://github.com/SeyZ/jsonapi-serializer","commit_stats":{"total_commits":221,"total_committers":37,"mean_commits":5.972972972972973,"dds":"0.30316742081447967","last_synced_commit":"b70219d926a885a96367504b5fccd6ea842ed174"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeyZ%2Fjsonapi-serializer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeyZ%2Fjsonapi-serializer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeyZ%2Fjsonapi-serializer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeyZ%2Fjsonapi-serializer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SeyZ","download_url":"https://codeload.github.com/SeyZ/jsonapi-serializer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246616062,"owners_count":20806048,"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":["deserializer","javascript","json-api","serializer"],"created_at":"2024-08-01T06:01:43.803Z","updated_at":"2025-04-01T09:31:18.308Z","avatar_url":"https://github.com/SeyZ.png","language":"JavaScript","readme":"# I am looking for new maintainers\nIf you are interested, send me an email: sandro@munda.me\n\n# JSON API Serializer\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/SeyZ/jsonapi-serializer/blob/master/logo.jpg?raw=true\" alt=\"JSONAPI Serializer Logo\"\u003e\n\u003c/p\u003e\n\n[![Build Status](https://travis-ci.org/SeyZ/jsonapi-serializer.svg?branch=master)](https://travis-ci.org/SeyZ/jsonapi-serializer)\n[![npm version](https://img.shields.io/npm/v/jsonapi-serializer.svg)](https://yarnpkg.com/en/package/jsonapi-serializer)\n[![download](https://img.shields.io/npm/dm/jsonapi-serializer.svg)](https://yarnpkg.com/en/package/jsonapi-serializer)\n\nA Node.js framework agnostic library for (de)serializing your data to [JSON\nAPI](http://jsonapi.org) (1.0 compliant).\n\npsst: If you need an off-the-shelf admin panel for your app, check out what I build in my day job at [forestadmin.com](https://www.forestadmin.com) - it uses jsonapi-serializer to de/serialize data data coming from/to the APIs.\n\n- [Migrate from 2.0 to 3.0](https://github.com/SeyZ/jsonapi-serializer/wiki/Migrate-from-2.0-to-3.0)\n- [Migrate from 1.x to 2.0](https://github.com/SeyZ/jsonapi-serializer/wiki/Migrate-from-1.x-to-2.0)\n\n## Installation\n`$ npm install jsonapi-serializer`\n\n## Documentation\n\n### Serialization\n\n    var JSONAPISerializer = require('jsonapi-serializer').Serializer;\n    new JSONAPISerializer(type, opts).serialize(data);\n\nThe function `JSONAPISerializer` takes two arguments:\n\n- `type`: The resource type.\n- `opts`: The serialization options.\n\nCalling the `serialize` method on the returned object will serialize your `data` (object or array) to a compliant JSONAPI document.\n\n\n#### Available serialization option (`opts` argument)\n\n- **attributes**: An array of attributes to show. You can define an attribute as an option if you want to define some relationships (included or not).\n    - **ref**: If present, it's considered as a relationships.\n    - **included**: Consider the relationships as [compound document](http://jsonapi.org/format/#document-compound-documents). Default: true.\n    - **id**: Configurable identifier field for the resource. Default: `id`.\n    - **attributes**: An array of attributes to show.\n    - **topLevelLinks**: An object that describes the top-level links. Values can be *string* or a *function*\n    - **dataLinks**: An object that describes the links inside data. Values can be *string* or a *function* (see examples below)\n    - **dataMeta**: An object that describes the meta inside data. Values can be a plain value or a *function* (see examples below)\n    - **relationshipLinks**: An object that describes the links inside relationships. Values can be *string* or a *function*\n    - **relationshipMeta**: An object that describes the meta inside relationships. Values can be a plain value or a *function*\n    - **ignoreRelationshipData**: Do not include the `data` key inside the relationship. Default: false.\n    - **keyForAttribute**: A function or string to customize attributes. Functions are passed the attribute as a single argument and expect a string to be returned. Strings are aliases for inbuilt functions for common case conversions. Options include: `dash-case` (default), `lisp-case`, `spinal-case`, `kebab-case`, `underscore_case`, `snake_case`, `camelCase`, `CamelCase`.\n    - **nullIfMissing**: Set the attribute to null if missing from your data input. Default: false.\n    - **pluralizeType**: A boolean to indicate if the type must be pluralized or not. Default: true.\n    - **typeForAttribute**: A function that maps the attribute (passed as an argument) to the type you want to override. If it returns `undefined`, ignores the flag for that attribute. Option *pluralizeType* ignored if set.\n    - **meta**: An object to include non-standard meta-information. Values can be a plain value or a *function*\n    - **transform**: A function to transform each record before the serialization.\n\n**Examples**\n\n- [Express example](https://github.com/SeyZ/jsonapi-serializer/tree/master/examples/express)\n- [Simple usage](#simple-usage-serializer)\n- [More examples in tests](https://github.com/SeyZ/jsonapi-serializer/blob/master/test/serializer.js)\n\n\u003ca name=\"simple-usage-serializer\"\u003e\u003c/a\u003e\nSimple usage:\n\n```javascript\nvar data = [\n  { id: 1, firstName: 'Sandro', lastName: 'Munda' },\n  { id: 2, firstName: 'John', lastName: 'Doe' }\n];\n```\n\n```javascript\nvar JSONAPISerializer = require('jsonapi-serializer').Serializer;\n\nvar UserSerializer = new JSONAPISerializer('users', {\n  attributes: ['firstName', 'lastName']\n});\n\nvar users = UserSerializer.serialize(data);\n\n// `users` here are JSON API compliant.\n```\n\nThe result will be something like:\n\n```javascript\n{\n  \"data\": [{\n    \"type\": \"users\",\n    \"id\": \"1\",\n    \"attributes\": {\n      \"first-name\": \"Sandro\",\n      \"last-name\": \"Munda\"\n    }\n  }, {\n    \"type\": \"users\",\n    \"id\": \"2\",\n    \"attributes\": {\n      \"first-name\": \"John\",\n      \"last-name\": \"Doe\"\n    }\n  }]\n}\n```\n\n### Deserialization\n\n    var JSONAPIDeserializer = require('jsonapi-serializer').Deserializer;\n    new JSONAPIDeserializer(opts).deserialize(data);\n\nThe function `JSONAPIDeserializer` takes one argument:\n\n- `opts`: The deserializer options.\n\nCalling the `deserialize` method on the returned object will deserialize your `data` (JSONAPI document) to a plain javascript object.\n\n#### Available deserialization option (`opts` argument)\n\n- **keyForAttribute**: A function or string to customize attributes. Functions are passed the attribute as a single argument and expect a string to be returned. Strings are aliases for inbuilt functions for common case conversions. Options include: `dash-case` (default), `lisp-case`, `spinal-case`, `kebab-case`, `underscore_case`, `snake_case`, `camelCase`, `CamelCase`.\n- **AN\\_ATTRIBUTE\\_TYPE**: this option name corresponds to the type of a relationship from your JSONAPI document.\n\t- **valueForRelationship**: A function that returns whatever you want for a relationship (see examples below) ***can return a Promise (see tests)***\n   - **transform**: A function to transform each record after the deserialization.\n\n**Examples**\n\n- [Simple usage](#simple-usage-deserializer)\n- [Relationship](#relationship-deserializer)\n- [More examples in tests](https://github.com/SeyZ/jsonapi-serializer/blob/master/test/deserializer.js)\n\n\u003ca name=\"simple-usage-deserializer\"\u003e\u003c/a\u003e\nSimple usage:\n\n```\n{\n  data: [{\n    type: 'users',\n    id: '1',\n    attributes: {\n      'first-name': Sandro,\n      'last-name': Munda\n    }\n  }, {\n    type: 'users',\n    id: '2',\n    attributes: {\n      'first-name': 'John',\n      'last-name': 'Doe'\n    }\n  }]\n}\n```\n\n```javascript\nvar JSONAPIDeserializer = require('jsonapi-serializer').Deserializer;\n\nnew JSONAPIDeserializer().deserialize(jsonapi, function (err, users) {\n  // `users` is...\n});\n```\n\n```javascript\n[\n  { id: 1, firstName: 'Sandro', lastName: 'Munda' },\n  { id: 2, firstName: 'John', lastName: 'Doe' }\n];\n```\n\u003ca name=\"relationship-deserializer\"\u003e\u003c/a\u003e\nRelationship:\n\n```\n{\n  data: [{\n    type: 'users',\n    id: '54735750e16638ba1eee59cb',\n    attributes: {\n      'first-name': 'Sandro',\n      'last-name': 'Munda'\n    },\n    relationships: {\n      address: {\n        data: { type: 'addresses', id: '54735722e16620ba1eee36af' }\n      }\n    }\n  }, {\n    type: 'users',\n    id: '5490143e69e49d0c8f9fc6bc',\n    attributes: {\n      'first-name': 'Lawrence',\n      'last-name': 'Bennett'\n    },\n    relationships: {\n      address: {\n        data: { type: 'addresses', id: '54735697e16624ba1eee36bf' }\n      }\n    }\n  }]\n}\n```\n\n```javascript\nvar JSONAPIDeserializer = require('jsonapi-serializer').Deserializer;\n\nnew JSONAPIDeserializer({\n  addresses: {\n    valueForRelationship: function (relationship) {\n      return {\n        id: relationship.id,\n        'address-line1': '406 Madison Court',\n        'zip-code': '49426',\n        country: 'USA'\n      };\n    }\n  }\n}).deserialize(jsonapi, function (err, users) {\n  // `users` is...\n});\n```\n\n```\n[{\n  id: '54735750e16638ba1eee59cb',\n  'first-name': 'Sandro',\n  'last-name': 'Munda',\n  address: {\n    id: '54735722e16620ba1eee36af',\n    'address-line1': '406 Madison Court',\n    'zip-code': '49426',\n    country: 'USA'\n  }\n}, {\n  id: '5490143e69e49d0c8f9fc6bc',\n  'first-name': 'Lawrence',\n  'last-name': 'Bennett',\n  address: {\n    id: '54735697e16624ba1eee36bf',\n    'address-line1': '406 Madison Court',\n    'zip-code': '49426',\n    country: 'USA'\n  }\n}]\n```\n\n#### Notes on Promises\nThe deserialization option `valueForRelationship` supports returning a `Promise` and so this library uses `Promises` under the hood. `bluebird` was previously used as a dependency, but due to bundle size concerns on both node and the web it was replaced with native promises.\n\n`bluebird` is definitely [more performant](http://bluebirdjs.com/docs/benchmarks.html) than native Promises. If performance is a major concern `Promise` can be globally polyfilled\n- node - via `global.Promise = require('bluebird')`\n- web - global `Promise` automatically gets assigned when using the [script tag](http://bluebirdjs.com/docs/getting-started.html) to load `bluebird`\n\n## Error serialization\n\n    var JSONAPIError = require('jsonapi-serializer').Error;\n    var error = new JSONAPIError(opts);\n\nThe function JSONAPIError takes one argument:\n\n- `opts`: The error options. All options are optional.\n\n#### Available error option (`opts` argument)\n\n- **id**: a unique identifier for this particular occurrence of the problem.\n- **status**: the HTTP status code applicable to this problem, expressed as a string value.\n- **code**: an application-specific error code, expressed as a string value.\n- **title**: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.\n- **detail**: a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.\n- **source**: an object containing references to the source of the error, optionally including any of the following members:\n  - **pointer**: a JSON Pointer [RFC6901] to the associated entity in the request document [e.g. \"/data\" for a primary data object, or \"/data/attributes/title\" for a specific attribute].\n  - **parameter**: a string indicating which URI query parameter caused the error.\n- **links**: a links object containing the following members:\n  - **about**: a link that leads to further details about this particular occurrence of the problem.\n- **meta**: a meta object containing non-standard meta-information about the error.\n\n**Examples**\n\n- [Simple usage](#simple-usage-error)\n- [More example](https://github.com/SeyZ/jsonapi-serializer/blob/master/test/error.js)\n\n\u003ca name=\"simple-usage-error\"\u003e\u003c/a\u003e\nSimple usage:\n\n```javascript\nvar JSONAPIError = require('jsonapi-serializer').Error;\n\nvar errors = new JSONAPIError({\n  code: '123',\n  source: { 'pointer': '/data/attributes/first-name' },\n  title: 'Value is too short',\n  detail: 'First name must contain at least three characters.'\n});\n\n// `errors` here are JSON API compliant.\n```\n\nThe result will be something like:\n\n```javascript\n{\n  \"errors\": [\n    {\n      \"code\":   \"123\",\n      \"source\": { \"pointer\": \"/data/attributes/first-name\" },\n      \"title\":  \"Value is too short\",\n      \"detail\": \"First name must contain at least three characters.\"\n    }\n  ]\n}\n```\n\n# License\n\n[MIT](https://github.com/SeyZ/jsonapi-serializer/blob/master/LICENSE)\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSeyZ%2Fjsonapi-serializer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSeyZ%2Fjsonapi-serializer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSeyZ%2Fjsonapi-serializer/lists"}