{"id":18256892,"url":"https://github.com/mediacomem/express-serializer","last_synced_at":"2025-12-31T14:34:06.195Z","repository":{"id":73832478,"uuid":"111670187","full_name":"MediaComem/express-serializer","owner":"MediaComem","description":"Serialization helper to handle arrays and property filtering for Express APIs","archived":false,"fork":false,"pushed_at":"2017-11-28T12:16:39.000Z","size":57,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-06-27T23:03:16.349Z","etag":null,"topics":[],"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/MediaComem.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2017-11-22T10:31:10.000Z","updated_at":"2019-08-12T19:34:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"13f6f2cc-df86-4460-8dd7-0399f04e6ce3","html_url":"https://github.com/MediaComem/express-serializer","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/MediaComem/express-serializer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MediaComem%2Fexpress-serializer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MediaComem%2Fexpress-serializer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MediaComem%2Fexpress-serializer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MediaComem%2Fexpress-serializer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MediaComem","download_url":"https://codeload.github.com/MediaComem/express-serializer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MediaComem%2Fexpress-serializer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265829236,"owners_count":23835090,"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":[],"created_at":"2024-11-05T10:24:03.024Z","updated_at":"2025-12-31T14:34:06.169Z","avatar_url":"https://github.com/MediaComem.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# express-serializer\n\nSerialization helper to handle arrays and property filtering for [Express][express] APIs.\n\n[![npm version](https://badge.fury.io/js/express-serializer.svg)](https://badge.fury.io/js/express-serializer)\n[![Dependency Status](https://gemnasium.com/badges/github.com/MediaComem/express-serializer.svg)](https://gemnasium.com/github.com/MediaComem/express-serializer)\n[![Build Status](https://travis-ci.org/MediaComem/express-serializer.svg?branch=master)](https://travis-ci.org/MediaComem/express-serializer)\n[![Coverage Status](https://coveralls.io/repos/github/MediaComem/express-serializer/badge.svg?branch=master)](https://coveralls.io/github/MediaComem/express-serializer?branch=master)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n\n- [Usage](#usage)\n  - [Arrays](#arrays)\n  - [Passing serialization options](#passing-serialization-options)\n  - [Filtering](#filtering)\n    - [Filtering with options](#filtering-with-options)\n    - [Filtering with query parameters](#filtering-with-query-parameters)\n    - [Filtering complex objects](#filtering-complex-objects)\n    - [Combining filters](#combining-filters)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\nDeveloped at the [Media Engineering Institute](http://mei.heig-vd.ch) ([HEIG-VD](https://heig-vd.ch)).\n\n\n\n## Usage\n\nThe most basic usage of this module is to call your own serialization functions to serialize objects:\n\n```js\nconst express = require('express');\nconst serializer = require('express-serializer');\n\nconst router = express.Router();\n\nrouter.get('/api/user', (req, res) =\u003e {\n\n  // Get an object to serialize.\n  const user = {\n    first_name: 'John',\n    last_name: 'Doe',\n    birth_date: new Date()\n  };\n\n  // Write your own custom serialization function\n  // or use your favorite ORM.\n  function serializeUser(req, user) {\n    return {\n      firstName: user.first_name,\n      lastName: user.last_name,\n      age: new Date().getFullYear() - user.getFullYear()\n    };\n  }\n\n  // Call the serializer; it always returns a promise\n  // (your serialization function can return a promise too).\n  serialize(req, user, serializeUser).then(json =\u003e {\n    res.send(json);\n    // HTTP/1.1 200 OK\n    // Content-Type: application/json\n    //\n    // {\n    //   \"firstName\": \"John\",\n    //   \"lastName\": \"Doe\",\n    //   \"age\": 42\n    // }\n  }).catch(next);\n});\n```\n\n### Arrays\n\nNow for the interesting part. It will automatically serialize each object in an array:\n\n```js\n// Get an array of objects to serialize.\nconst users = [\n  {\n    first_name: 'John',\n    last_name: 'Doe',\n    birth_date: new Date()\n  },\n  {\n    first_name: 'Bob',\n    last_name: 'Smith',\n    birth_date: new Date()\n  }\n];\n\n// Use the same serialization function as before.\nfunction serializeUser(req, user) {\n  return {\n    firstName: user.first_name,\n    lastName: user.last_name,\n    age: new Date().getFullYear() - user.getFullYear()\n  };\n}\n\n// Each object in the array will be serialized with your function.\nserialize(req, users, serializeUser).then(json =\u003e {\n  res.send(json);\n  // HTTP/1.1 200 OK\n  // Content-Type: application/json\n  //\n  // [\n  //   {\n  //     \"firstName\": \"John\",\n  //     \"lastName\": \"Doe\",\n  //     \"age\": 42\n  //   },\n  //   {\n  //     \"firstName\": \"Bob\",\n  //     \"lastName\": \"Smith\",\n  //     \"age\": 24\n  //   }\n  // ]\n});\n```\n\n### Passing serialization options\n\nAny additional options passed to the serializer as the fourth argument will also be passed to your serialization function:\n\n```js\nfunction serializeUser(req, user, options) {\n\n  const serialized = {\n    name: `${user.first_name} ${user.last_name}`\n  };\n\n  // Use options to customize the behavior of your serialization function.\n  if (options \u0026\u0026 options.includeBirthDate) {\n    serialized.birthDate = user.birth_date\n  }\n\n  return serialized;\n}\n\n// Call the serializer with options.\nconst options = { includeBirthDate: true };\nserialize(req, user, serializeUser, options).then(json =\u003e {\n  res.send(json);\n  // HTTP/1.1 200 OK\n  // Content-Type: application/json\n  //\n  // {\n  //   \"name\": \"John Doe\",\n  //   \"birthDate\": \"2000-01-01T00:00:00Z\"\n  // }\n});\n```\n\n### Filtering\n\nProperties of serialized objects can be whitelisted or blacklisted with the `only` and `except` options.\n\n#### Filtering with options\n\n`only` and `except` can be passed in the serialization options:\n\n```js\nconst user = {\n  first_name: 'John',\n  last_name: 'Doe',\n  birth_date: new Date()\n};\n\nfunction serializeUser(req, user) {\n  return {\n    firstName: user.first_name,\n    lastName: user.last_name,\n    age: new Date().getFullYear() - user.getFullYear()\n  };\n}\n\n// Pick only the first name:\nserialize(req, user, serializeUser, { only: 'firstName' }).then(json =\u003e {\n  res.send(json);\n  // HTTP/1.1 200 OK\n  // Content-Type: application/json\n  //\n  // {\n  //   \"firstName\": \"John\"\n  // }\n});\n\n// Pick both the first and last names:\nserialize(req, user, serializeUser, { only: [ 'firstName', 'lastName' ] }).then(json =\u003e {\n  res.send(json);\n  // HTTP/1.1 200 OK\n  // Content-Type: application/json\n  //\n  // {\n  //   \"firstName\": \"John\",\n  //   \"lastName\": \"Doe\"\n  // }\n});\n\n// Omit the last name:\nserialize(req, user, serializeUser, { except: 'lastName' }).then(json =\u003e {\n  res.send(json);\n  // HTTP/1.1 200 OK\n  // Content-Type: application/json\n  //\n  // {\n  //   \"firstName\": \"John\",\n  //   \"age\": 42\n  // }\n});\n```\n\n#### Filtering with query parameters\n\nThe `only` and `except` query parameters have the same effect if present in the HTTP request:\n\n```js\n// Pick only the first name:\n//\n// GET /api/user?only=firstName HTTP/1.1\n// Accept: application/json\nserialize(req, user, serializeUser).then(json =\u003e {\n  res.send(json);\n  // HTTP/1.1 200 OK\n  // Content-Type: application/json\n  //\n  // {\n  //   \"firstName\": \"John\"\n  // }\n});\n\n// Pick both the first and last names:\n//\n// GET /api/user?only=firstName\u0026only=lastName HTTP/1.1\n// Accept: application/json\nserialize(req, user, serializeUser).then(json =\u003e {\n  res.send(json);\n  // HTTP/1.1 200 OK\n  // Content-Type: application/json\n  //\n  // {\n  //   \"firstName\": \"John\",\n  //   \"lastName\": \"Doe\"\n  // }\n});\n\n// Omit the last name:\n//\n// GET /api/user?except=lastName HTTP/1.1\n// Accept: application/json\nserialize(req, user, serializeUser).then(json =\u003e {\n  res.send(json);\n  // HTTP/1.1 200 OK\n  // Content-Type: application/json\n  //\n  // {\n  //   \"firstName\": \"John\",\n  //   \"age\": 42\n  // }\n});\n```\n\n#### Filtering complex objects\n\nYou can use a dotted notation in `only` and `except` to filter properties of more complex objects:\n\n```js\nconst user = {\n  first_name: 'John',\n  last_name: 'Doe',\n  address: {\n    city: 'Sunnydale',\n    state: 'California'\n  }\n};\n\nfunction serializeUser(req, user) {\n  return {\n    firstName: user.first_name,\n    lastName: user.last_name,\n    address: user.address\n  };\n}\n\n// Pick only the last name and city:\nconst options = {\n  only: [ 'lastName', 'address.city' ]\n};\n\nserialize(req, user, serializeUser, options).then(json =\u003e {\n  res.send(json);\n  // HTTP/1.1 200 OK\n  // Content-Type: application/json\n  //\n  // {\n  //   \"firstName\": \"John\",\n  //   \"address\": {\n  //     \"city\": \"Sunnydale\"\n  //   }\n  // }\n});\n\n// Omit the last name and city through query parameters:\n//\n// GET /api/user?except=lastName\u0026except=address.city HTTP/1.1\n// Accept: application/json\nserialize(req, user, serializeUser).then(json =\u003e {\n  res.send(json);\n  // HTTP/1.1 200 OK\n  // Content-Type: application/json\n  //\n  // {\n  //   \"firstName\": \"John\",\n  //   \"address\": {\n  //     \"state\": \"California\"\n  //   }\n  // }\n});\n```\n\n#### Combining filters\n\nProperties which are both in `only` and `except` are not included in the serialized object:\n\n```js\n// Pick only the first and last names,\n// and omit the last name and city:\nconst options = {\n  only: [ 'firstName', 'lastName' ],\n  except: [ 'lastName', 'address.city' ]\n};\n\nserialize(req, user, serializeUser, options).then(json =\u003e {\n  res.send(json);\n  // HTTP/1.1 200 OK\n  // Content-Type: application/json\n  //\n  // {\n  //   \"firstName\": \"John\",\n  //   \"address\": {\n  //     \"state\": \"California\"\n  //   }\n  // }\n});\n```\n\nIf `only` and `except` are specified both in the options and in query parameters, they are merged:\n\n```js\n// Pick only the first and last names through options,\n// and omit the first name through query parameters:\n//\n// GET /api/user?except=firstName HTTP/1.1\n// Accept: application/json\nconst options = {\n  only: [ 'firstName', 'lastName' ]\n};\n\nserialize(req, user, serializeUser, options).then(json =\u003e {\n  res.send(json);\n  // HTTP/1.1 200 OK\n  // Content-Type: application/json\n  //\n  // {\n  //   \"lastName\": \"Doe\"\n  // }\n});\n```\n\nIf `except` is present in both the options and in query parameters, the union of all `except` properties is used:\n\n```js\n// Omit the first and last names through options, and omit the state through query parameters:\n//\n// GET /api/user?except=address.state HTTP/1.1\n// Accept: application/json\nconst options = {\n  only: [ 'firstName', 'lastName' ]\n};\n\nserialize(req, user, serializeUser, options).then(json =\u003e {\n  res.send(json);\n  // HTTP/1.1 200 OK\n  // Content-Type: application/json\n  //\n  // {\n  //   \"address\": {\n  //     \"city\": \"Sunnydale\"\n  //   }\n  // }\n});\n```\n\nIf `only` is present in both the options and in query parameters, the intersection of all `only` properties is used:\n\n```js\n// Pick the first and last names through options,\n// and pick the first name through query parameters:\n//\n// GET /api/user?only=firstName HTTP/1.1\n// Accept: application/json\nconst options = {\n  only: [ 'firstName', 'lastName' ]\n};\n\nserialize(req, user, serializeUser, options).then(json =\u003e {\n  res.send(json);\n  // HTTP/1.1 200 OK\n  // Content-Type: application/json\n  //\n  // {\n  //   \"firstName\": \"John\"\n  // }\n});\n```\n\n\n\n[express]: https://expressjs.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmediacomem%2Fexpress-serializer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmediacomem%2Fexpress-serializer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmediacomem%2Fexpress-serializer/lists"}