开源软件名称：

开源软件地址：

开源编程语言：

开源软件介绍：

json-api-serializer

A Node.js/browser framework agnostic library for serializing your data to JSON API compliant responses (a specification for building APIs in JSON).

Installation

npm install --save json-api-serializer

Documentation

Register

var JSONAPISerializer = require("json-api-serializer");
var Serializer = new JSONAPISerializer();
Serializer.register(type, options);

Serialization options:

• id (optional): The key to use as the reference. Default = 'id'.
• blacklist (optional): An array of blacklisted attributes. Default = [].
• whitelist (optional): An array of whitelisted attributes. Default = [].
• jsonapiObject (optional): Enable/Disable JSON API Object. Default = true.
• links (optional): Describes the links inside data. It can be:
  • An object (values can be string or function).
  • A function with one argument function(data) { ... } or with two arguments function(data, extraData) { ... }
• topLevelMeta (optional): Describes the top-level meta. It can be:
  • An object (values can be string or function).
  • A function with one argument function(extraData) { ... } or with two arguments function(data, extraData) { ... }
• topLevelLinks (optional): Describes the top-level links. It can be:
  • An object (values can be string or function).
  • A function with one argument function(extraData) { ... } or with two arguments function(data, extraData) { ... }
• meta (optional): Describes resource-level meta. It can be:
  • An object (values can be string or function).
  • A function with one argument function(data) { ... } or with two arguments function(data, extraData) { ... }
• relationships (optional): An object defining some relationships
  • relationship: The property in data to use as a relationship
    • type: A string or a function function(relationshipData, data) { ... } for the type to use for serializing the relationship (type need to be register).
    • alternativeKey (optional): An alternative key (string or path) to use if relationship key not exist (example: 'author_id' as an alternative key for 'author' relationship). See issue #12.
    • schema (optional): A custom schema for serializing the relationship. If no schema define, it use the default one.
    • links (optional): Describes the links for the relationship. It can be:
      • An object (values can be string or function).
      • A function with one argument function(data) { ... } or with two arguments function(data, extraData) { ... }
    • meta (optional): Describes meta that contains non-standard meta-information about the relationship. It can be:
      • An object (values can be string or function).
      • A function with one argument function(data) { ... } or with two arguments function(data, extraData) { ... }
    • deserialize (optional): Describes the function which should be used to deserialize a related property which is not included in the JSON:API document. It should be:
      • A function with one argument function(data) { ... }which defines the format to which a relation should be deserialized. By default, the ID of the related object is returned, which would be equal to function(data) {return data.id}. See issue #65.
• convertCase (optional): Case conversion for serializing data. Value can be : kebab-case, snake_case, camelCase
• beforeSerialize (optional): A function with one argument beforeSerialize(data) => newData to transform data before serialization.

Deserialization options:

• unconvertCase (optional): Case conversion for deserializing data. Value can be : kebab-case, snake_case, camelCase
• blacklistOnDeserialize (optional): An array of blacklisted attributes. Default = [].
• whitelistOnDeserialize (optional): An array of whitelisted attributes. Default = [].
• afterDeserialize (optional): A function with one argument afterDeserialize(data) => newData to transform data after deserialization.

Global options:

To avoid repeating the same options for each type, it's possible to add global options on JSONAPISerializer instance:

When using convertCase, a LRU cache is utilized for optimization. The default size of the cache is 5000 per conversion type. The size of the cache can be set with the convertCaseCacheSize option. Passing in 0 will result in a LRU cache of infinite size.

var JSONAPISerializer = require("json-api-serializer");
var Serializer = new JSONAPISerializer({
  convertCase: "kebab-case",
  unconvertCase: "camelCase",
  convertCaseCacheSize: 0
});

Usage

input data (can be an object or an array of objects)

// Data
var data = [
  {
    id: "1",
    title: "JSON API paints my bikeshed!",
    body: "The shortest article. Ever.",
    created: "2015-05-22T14:56:29.000Z",
    updated: "2015-05-22T14:56:28.000Z",
    author: {
      id: "1",
      firstName: "Kaley",
      lastName: "Maggio",
      email: "[email protected]",
      age: "80",
      gender: "male"
    },
    tags: ["1", "2"],
    photos: [
      "ed70cf44-9a34-4878-84e6-0c0e4a450cfe",
      "24ba3666-a593-498c-9f5d-55a4ee08c72e",
      "f386492d-df61-4573-b4e3-54f6f5d08acf"
    ],
    comments: [
      {
        _id: "1",
        body: "First !",
        created: "2015-08-14T18:42:16.475Z"
      },
      {
        _id: "2",
        body: "I Like !",
        created: "2015-09-14T18:42:12.475Z"
      },
      {
        _id: "3",
        body: "Awesome",
        created: "2015-09-15T18:42:12.475Z"
      }
    ]
  }
];

Register

Register your resources types :

var JSONAPISerializer = require("json-api-serializer");
var Serializer = new JSONAPISerializer();

// Register 'article' type
Serializer.register("article", {
  id: "id", // The attributes to use as the reference. Default = 'id'.
  blacklist: ["updated"], // An array of blacklisted attributes. Default = []
  links: {
    // An object or a function that describes links.
    self: function(data) {
      // Can be a function or a string value ex: { self: '/articles/1'}
      return "/articles/" + data.id;
    }
  },
  relationships: {
    // An object defining some relationships.
    author: {
      type: "people", // The type of the resource
      links: function(data) {
        // An object or a function that describes Relationships links
        return {
          self: "/articles/" + data.id + "/relationships/author",
          related: "/articles/" + data.id + "/author"
        };
      }
    },
    tags: {
      type: "tag"
    },
    photos: {
      type: "photo"
    },
    comments: {
      type: "comment",
      schema: "only-body" // A custom schema
    }
  },
  topLevelMeta: function(data, extraData) {
    // An object or a function that describes top level meta.
    return {
      count: extraData.count,
      total: data.length
    };
  },
  topLevelLinks: {
    // An object or a function that describes top level links.
    self: "/articles" // Can be a function (with extra data argument) or a string value
  }
});

// Register 'people' type
Serializer.register("people", {
  id: "id",
  links: {
    self: function(data) {
      return "/peoples/" + data.id;
    }
  }
});

// Register 'tag' type
Serializer.register("tag", {
  id: "id"
});

// Register 'photo' type
Serializer.register("photo", {
  id: "id"
});

// Register 'comment' type with a custom schema
Serializer.register("comment", "only-body", {
  id: "_id"
});

Serialize

Serialize it with the corresponding resource type, data and optional extra data :

// Synchronously (blocking)
const result = Serializer.serialize('article', data, {count: 2});

// Asynchronously (non-blocking)
Serializer.serializeAsync('article', data, {count: 2})
  .then((result) => {
    ...
  });

The output data will be :

{
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "count": 2,
    "total": 1
  },
  "links": {
    "self": "/articles"
  },
  "data": [{
    "type": "article",
    "id": "1",
    "attributes": {
      "title": "JSON API paints my bikeshed!",
      "body": "The shortest article. Ever.",
      "created": "2015-05-22T14:56:29.000Z"
    },
    "relationships": {
      "author": {
        "data": {
          "type": "people",
          "id": "1"
        },
        "links": {
          "self": "/articles/1/relationships/author",
          "related": "/articles/1/author"
        }
      },
      "tags": {
        "data": [{
          "type": "tag",
          "id": "1"
        }, {
          "type": "tag",
          "id": "2"
        }]
      },
      "photos": {
        "data": [{
          "type": "photo",
          "id": "ed70cf44-9a34-4878-84e6-0c0e4a450cfe"
        }, {
          "type": "photo",
          "id": "24ba3666-a593-498c-9f5d-55a4ee08c72e"
        }, {
          "type": "photo",
          "id": "f386492d-df61-4573-b4e3-54f6f5d08acf"
        }]
      },
      "comments": {
        "data": [{
          "type": "comment",
          "id": "1"
        }, {
          "type": "comment",
          "id": "2"
        }, {
          "type": "comment",
          "id": "3"
        }]
      }
    },
    "links": {
      "self": "/articles/1"
    }
  }],
  "included": [{
    "type": "people",
    "id": "1",
    "attributes": {
      "firstName": "Kaley",
      "lastName": "Maggio",
      "email": "[email protected]",
      "age": "80",
      "gender": "male"
    },
    "links": {
      "self": "/peoples/1"
    }
  }, {
    "type": "comment",
    "id": "1",
    "attributes": {
      "body": "First !"
    }
  }, {
    "type": "comment",
    "id": "2",
    "attributes": {
      "body": "I Like !"
    }
  }, {
    "type": "comment",
    "id": "3",
    "attributes": {
      "body": "Awesome"
    }
  }]
}

There is an available argument excludeData that will exclude the data property from the serialized object. This can be used in cases where you may want to only include the topLevelMeta in your response, such as a DELETE response with only a meta property, or other cases defined in the JSON:API spec.

// Synchronously (blocking)
const result = Serializer.serialize('article', data, 'default', {count: 2}, true);

// Asynchronously (non-blocking)
Serializer.serializeAsync('article', data, 'default', {count: 2}, true)
  .then((result) => {
    ...
  });

Override schema options

On each individual call to serialize or serializeAsync, there is an parameter to override the options of any registered type. For example on a call to serialize, if a whitelist was not defined on the registered schema options, a whitelist (or any other options) for that type can be provided. This parameter is an object, where the key are the registered type names, and the values are the objects to override the registered schema.

In the following example, only the attribute name will be serialized on the article, and if there is a relationship for person, it will be serialized with camelCase even if the registered schema has a different value.

const result = Serializer.serialize('article', data, 'default', {count: 2}, true), {
  article: {
    whitelist: ['name']
  },
  person: {
    convertCase: 'camelCase'
  }
};

Some others examples are available in tests folders

Deserialize

input data (can be an simple object or an array of objects)

var data = {
  data: {
    type: 'article',
    id: '1',
    attributes: {
      title: 'JSON API paints my bikeshed!',
      body: 'The shortest article. Ever.',
      created: '2015-05-22T14:56:29.000Z'
    },
    relationships: {
      author: {
        data: {
          type: 'people',
          id: '1'
        }
      },
      comments: {
        data: [{
          type: 'comment',
          id: '1'
        }, {
          type: 'comment',
          id: '2'
        }]
      }
    }
  }
};

// Synchronously (blocking)
Serializer.deserialize('article', data);

// Asynchronously (non-blocking)
Serializer.deserializeAsync('article', data)
  .then((result) => {
    // ...
  });

{
  "id": "1",
  "title": "JSON API paints my bikeshed!",
  "body": "The shortest article. Ever.",
  "created": "2015-05-22T14:56:29.000Z",
  "author": "1",
  "comments": [
    "1",
    "2"
  ]
}

serializeError

Serializes any error into a JSON API error document.

Input data can be:

• An instance of Error or an array of Error instances.
• A JSON API error object or an array of JSON API error objects.

Using an instance of Error:

const error = new Error('An error occurred');
error.id = 123
error.links = { about: 'https://example.com/errors/123' }
error.status = 500; // or `statusCode`
error.code = 'xyz'
error.meta = { time: Date.now() }

Serializer.serializeError(error);

The result will be:

{
  "errors": [
    {
      "id": 123,
      "links": {
        "about": "https://example.com/errors/123"
      },
      "status": "500",
      "code": "xyz",
      "title": "Error",
      "detail": "An error occurred",
      "meta": {
        "time": 1593561258853
      }
    }
  ]
}

Using an instance of a class that inherits from Error:

class MyCustomError extends Error {
  constructor(message = 'Something went wrong') {
    super(message)
    this.id = 123
    this.links = {
      about: 'https://example.com/errors/123'
    }
    this.status = 500 // or `statusCode`
    this.code = 'xyz'
    this.meta = {
      time: Date.now()
    }
  }
}

Serializer.serializeError(new MyCustomError());

The result will be:

{
  "errors": [
    {
      "id": 123,
      "links": {
        "about": "https://example.com/errors/123"
      },
      "status": "500",
      "code": "xyz",
      "title": "MyCustomError",
      "detail": "Something went wrong",
      "meta": {
        "time": 1593561258853
      }
    }
  ]
}

Using a POJO:

Serializer.serializeError({
  id: 123,
  links: {
    about: 'https://example.com/errors/123'
  },
  status: 500, // or `statusCode`
  code: 'xyz',
  title: 'UserNotFound',
  detail: 'Unable to find a user with the provided ID',
  meta: {
    time: Date.now()
  }
});

The result will be:

{
  "errors": [
    {
      "id": 123,
      "links": {
        "about": "https://example.com/errors/123"
      },
      "status": "500<