{"id":19382716,"url":"https://github.com/danivek/hal-serializer","last_synced_at":"2025-07-31T04:39:12.192Z","repository":{"id":57260340,"uuid":"61485268","full_name":"danivek/hal-serializer","owner":"danivek","description":"Framework agnostic HAL (http://stateless.co/hal_specification.html) serializer.","archived":false,"fork":false,"pushed_at":"2017-10-12T10:53:24.000Z","size":21,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-07T15:01:48.677Z","etag":null,"topics":["hal","hal-serializer","hypermedia","serializer"],"latest_commit_sha":null,"homepage":null,"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/danivek.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}},"created_at":"2016-06-19T14:54:31.000Z","updated_at":"2022-04-07T10:04:08.000Z","dependencies_parsed_at":"2022-08-25T01:40:19.294Z","dependency_job_id":null,"html_url":"https://github.com/danivek/hal-serializer","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/danivek/hal-serializer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danivek%2Fhal-serializer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danivek%2Fhal-serializer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danivek%2Fhal-serializer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danivek%2Fhal-serializer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danivek","download_url":"https://codeload.github.com/danivek/hal-serializer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danivek%2Fhal-serializer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267988489,"owners_count":24176996,"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","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"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":["hal","hal-serializer","hypermedia","serializer"],"created_at":"2024-11-10T09:22:55.526Z","updated_at":"2025-07-31T04:39:12.135Z","avatar_url":"https://github.com/danivek.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hal-serializer\n[![Build Status](https://travis-ci.org/danivek/hal-serializer.svg?branch=master)](https://travis-ci.org/danivek/hal-serializer)\n[![Coverage Status](https://coveralls.io/repos/github/danivek/hal-serializer/badge.svg?branch=master)](https://coveralls.io/github/danivek/hal-serializer?branch=master)\n[![npm](https://img.shields.io/npm/v/hal-serializer.svg)](https://www.npmjs.org/package/hal-serializer)\n\n\nA Node.js framework agnostic library for serializing your data to [HAL](http://stateless.co/hal_specification.html) compliant responses (a specification for building APIs in JSON).\n\n## Installation\n```bash\nnpm install --save hal-serializer\n```\n\n## Documentation\n\n#### Register\n\n```javascript\nvar HALSerializer = require('hal-serializer');\nvar Serializer = new HALSerializer();\nSerializer.register(type, options);\n```\n**Available options :**\n\n- **blacklist** (optional): An array of blacklisted attributes. Default = [].\n- **whitelist** (optional): An array of whitelisted attributes. Default = [].\n- **links** (optional): An *object* or a *function* that describes the links inside data. (If it is an object values can be string or function).\n- **topLevelMeta** (optional): An *object* or a *function* that describes the links inside data. (If it is an object values can be string or function).\n- **topLevelLinks** (optional): An *object* or a *function* that describes the links inside data. (If it is an object values can be string or function).\n- **embedded** (optional): An object defining some embedded resources\n    - *embedded*: The property in data to use as an embedded resource\n        - **type**: The type to use for serializing the embedded resource (type need to be register)\n        - **schema** (optional): A custom schema for serializing the embedded resource. If no schema define, it use the default one.\n        - **links** (optional): An *object* or a *function* that describes the links for the relationship. (If it is an object values can be string or function).\n- **convertCase** (optional): Case conversion for serializing data. Value can be : `kebab-case`, `snake_case`, `camelCase`\n\n## Usage\n\ninput data (can be a simple object or an array of objects)\n```javascript\n// Data\nvar data = {\n  id: \"1\",\n  title: \"HAL Hypertext Application Language\",\n  body: \"The shortest article. Ever.\",\n  created: \"2015-05-22T14:56:29.000Z\",\n  updated: \"2015-05-22T14:56:28.000Z\",\n  author: {\n    id: \"1\",\n    firstName: \"Kaley\",\n    lastName: \"Maggio\",\n    email: \"Kaley-Maggio@example.com\",\n    age: \"80\",\n    gender: \"male\"\n  },\n  tags: [\"1\", \"2\"],\n  photos: [\"ed70cf44-9a34-4878-84e6-0c0e4a450cfe\", \"24ba3666-a593-498c-9f5d-55a4ee08c72e\", \"f386492d-df61-4573-b4e3-54f6f5d08acf\"],\n  comments: [{\n    _id: \"1\",\n    body: \"First !\",\n    created: \"2015-08-14T18:42:16.475Z\"\n  }, {\n    _id: \"2\",\n    body: \"I Like !\",\n    created: \"2015-09-14T18:42:12.475Z\"\n  }, {\n    _id: \"3\",\n    body: \"Awesome\",\n    created: \"2015-09-15T18:42:12.475Z\"\n  }]\n}\n```\n\nRegister your resources types :\n```javascript\nvar HALSerializer = require('hal-serializer');\nvar Serializer = new HALSerializer();\n\n// Register 'article' type\nSerializer.register('article', {\n  blacklist: ['updated'], // An array of blacklisted attributes. Default = []\n  links: function(data) { // An object or a function that describes links.\n    return {\n      self: {\n        href: '/articles/' + data.id\n      }\n    }\n  },\n  embedded: { // An object defining some embedded resources.\n    author: {\n      type: 'people', // The type of the embedded resource\n      links: function(data) {\n        return {\n          href: '/peoples/' + data.id\n        }\n      }\n    },\n    tags: {\n      type: 'tag'\n    },\n    photos: {\n      type: 'photo'\n    },\n    comments: {\n      type: 'comment',\n      schema: 'only-body' // A custom schema\n    }\n  },\n  topLevelMeta: function(extraOptions) { // An object or a function that describes top level meta.\n    return {\n      count: extraOptions.count\n    }\n  },\n  topLevelLinks: { // An object or a function that describes top level links.\n    self: {\n      href: '/articles'\n    }\n  }\n});\n\n// Register 'people' type\nSerializer.register('people', {\n  links: {\n    self: function(data) {\n      return {\n        href: '/peoples/' + data.id\n      };\n    }\n  }\n});\n\n// Register 'tag' type\nSerializer.register('tag', {});\n\n// Register 'photo' type\nSerializer.register('photo', {});\n\n// Register 'comment' type with a custom schema\nSerializer.register('comment', 'only-body', {\n  whitelist: ['body'],\n});\n```\n\nSerialize it with the corresponding resource type, data and optional extra options :\n\n```javascript\n// Synchronously (blocking)\nSerializer.serialize('article', data, {count: 2});\n\n// Asynchronously (non-blocking)\nSerializer.serializeAsync('article', data, {count: 2})\n  .then((result) =\u003e {\n    ...\n  });\n```\n\nThe output data will be :\n```JSON\n{\n  \"_links\": {\n    \"self\": {\n      \"href\": \"/articles/1\"\n    },\n    \"author\": {\n      \"href\": \"/peoples/1\"\n    }\n  },\n  \"count\": 2,\n  \"id\": \"1\",\n  \"title\": \"HAL Hypertext Application Language\",\n  \"body\": \"The shortest article. Ever.\",\n  \"created\": \"2015-05-22T14:56:29.000Z\",\n  \"_embedded\": {\n    \"author\": {\n      \"_links\": {\n        \"self\": {\n          \"href\": \"/peoples/1\"\n        }\n      },\n      \"id\": \"1\",\n      \"firstName\": \"Kaley\",\n      \"lastName\": \"Maggio\",\n      \"email\": \"Kaley-Maggio@example.com\",\n      \"age\": \"80\",\n      \"gender\": \"male\"\n    },\n    \"comments\": [\n      {\n        \"body\": \"First !\"\n      },\n      {\n        \"body\": \"I Like !\"\n      },\n      {\n        \"body\": \"Awesome\"\n      }\n    ]\n  }\n}\n```\n\n### Deserialize\n\ninput data (can be an simple object or an array of objects)\n\n```javascript\nvar data = {\n  _links: {\n    self: {\n      href: '/articles/1'\n    },\n    author: {\n      href: '/peoples/1'\n    }\n  },\n  id: '1',\n  title: 'HAL Hypertext Application Language',\n  body: 'The shortest article. Ever.',\n  created: '2015-05-22T14:56:29.000Z',\n  _embedded: {\n    author: {\n      _links: {\n        self: {\n          href: '/peoples/1'\n        }\n      },\n      id: '1',\n      firstName: 'Kaley',\n      lastName: 'Maggio',\n      email: 'Kaley-Maggio@example.com',\n      age: '80',\n      gender: 'male'\n    }\n  }\n};\n\nSerializer.deserialize('article', data);\n```\n\n```JSON\n{\n  \"id\": \"1\",\n  \"title\": \"HAL Hypertext Application Language\",\n  \"body\": \"The shortest article. Ever.\",\n  \"created\": \"2015-05-22T14:56:29.000Z\",\n  \"author\": {\n    \"id\": \"1\",\n    \"firstName\": \"Kaley\",\n    \"lastName\": \"Maggio\",\n    \"email\": \"Kaley-Maggio@example.com\",\n    \"age\": \"80\",\n    \"gender\": \"male\"\n  }\n}\n```\n\n## Custom schemas\n\nIt is possible to define multiple custom schemas for a resource type :\n\n```javascript\nSerializer.register(type, 'customSchema', options);\n```\n\nIf you want to apply this schema on the primary data :\n\n```javascript\nSerializer.serialize('article', data, 'customSchema', {count: 2});\n```\n\nOr if you want to apply this schema on a embedded resource, define this schema on embedded resource options with the key `schema` :\n\nExample :\n```javascript\nembedded: {\n  comments: {\n    type: 'comment'\n    schema: 'customSchema'\n  }\n}\n```\n\n## Requirements\n\nhal-serializer use ECMAScript 2015 (ES6) features supported natively by Node.js 4 and above ([ECMAScript 2015 (ES6) | Node.js](https://nodejs.org/en/docs/es6/)). Make sure that you have Node.js 4+ or above.\n\n## License\n\n[MIT](https://github.com/danivek/hal-serializer/blob/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanivek%2Fhal-serializer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanivek%2Fhal-serializer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanivek%2Fhal-serializer/lists"}