Kitsu Core JSON:API (De)serializer

11.1.0 · active · verified Sun Apr 19

kitsu-core is a compact and framework-agnostic JavaScript/TypeScript library designed for the (de)serialization of JSON:API 1.0 compliant data structures. Currently in its 11.x stable release cycle, with version 11.1.1 being the latest, the project demonstrates an active development and release cadence, often publishing minor and patch updates within weeks or months. Its core differentiators include strict adherence to the JSON:API specification, automatic linking of relationships, and a zero-dependency footprint, making it highly tree-shakeable and suitable for both Node.js and browser environments. Recent updates have focused on significant performance improvements for large datasets (up to 1,000 times faster deserialization in v11.0.2) and introducing opt-in data hoisting features, allowing for more flexible data structuring post-deserialization. The library emphasizes minimal bundle size and broad modern environment compatibility.

Common errors

Warnings

Install

Imports

Quickstart

This code snippet demonstrates how to use `kitsu-core` to deserialize a JSON:API response into a plain JavaScript object, apply camel-casing to keys, serialize an object back into JSON:API format, and utilize the opt-in data hoisting feature for relationships.

import { deserialise, serialise, camel } from 'kitsu-core';

// Example JSON:API response structure
const jsonApiResponse = {
  data: {
    type: 'articles',
    id: '1',
    attributes: {
      'title-post': 'JSON:API is great!',
      'content-body': 'This is some content.'
    },
    relationships: {
      author: {
        data: { type: 'users', id: '9' }
      },
      comments: {
        data: [
          { type: 'comments', id: '5' },
          { type: 'comments', id: '12' }
        ]
      }
    }
  },
  included: [
    {
      type: 'users',
      id: '9',
      attributes: {
        'full-name': 'John Doe'
      }
    },
    {
      type: 'comments',
      id: '5',
      attributes: {
        body: 'First comment'
      }
    },
    {
      type: 'comments',
      id: '12',
      attributes: {
        body: 'Second comment'
      },
      relationships: {
          author: {
              data: { type: 'users', id: '9' }
          }
      }
    }
  ]
};

async function runKitsuCoreExample() {
  console.log('Original JSON:API Response:', JSON.stringify(jsonApiResponse, null, 2));

  // Deserialise the JSON:API response into a plain JavaScript object, applying camelCaseKeys
  const deserializedData = await deserialise(jsonApiResponse, { camelCaseKeys: true });
  console.log('\nDeserialized Data (camelCaseKeys: true):', JSON.stringify(deserializedData, null, 2));

  // Example of using the standalone camel utility
  const camelCasedKey = camel('my-kebab-case-key');
  console.log('\nCamel cased key:', camelCasedKey); // myKebabCaseKey

  // Prepare data for serialization (e.g., after modifying it)
  const articleToSerialize = {
    id: '1',
    type: 'articles',
    titlePost: 'Updated Title',
    contentBody: 'New content here.',
    author: {
      id: '9',
      type: 'users'
    },
    comments: [
      { id: '5', type: 'comments' },
      { id: '12', type: 'comments' }
    ]
  };

  // Serialize a plain JavaScript object back into JSON:API format
  const serializedData = await serialise(articleToSerialize, 'articles', { camelCaseKeys: true });
  console.log('\nSerialized Data (camelCaseKeys: true):', JSON.stringify(serializedData, null, 2));

  // Demonstrate data hoisting (introduced in v11.1.0)
  const hoistedData = await deserialise(jsonApiResponse, {
    camelCaseKeys: true,
    hoist: ['author'] // Hoist the 'author' relationship directly onto the article object
  });
  console.log('\nDeserialized Data with Author Hoisted (opt-in since v11.1.0):', JSON.stringify(hoistedData, null, 2));
}

runKitsuCoreExample();

view raw JSON →