Kitsu Core

Simple, lightweight & framework agnostic JSON:API (de)serialisation components

Migration guide for v10 & previous major releases

Features

• JSON-API 1.0 compliant
• Automatically links relationships to data
• Works in Node & browsers
• Tree shakeable components
• Zero dependencies

Node / Browser Support

Package	Package Size*	ESM Size†	Node	Chrome	Firefox	Safari	Edge
kitsu-core	≤ 1.5 kb	≤ 1.4 KB	14+	83+	78+	13.1+	95+

* Minified with brotli † EcmaScript Modules package size*

Install

Yarn / NPM

yarn add kitsu-core
npm install kitsu-core

import { camel } from 'kitsu-core'      // ES Modules and Babel
const { camel } = require('kitsu-core') // CommonJS and Browserify

camel(...)

CDNs

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/kitsu-core"></script>

<!-- unpkg -->
<script src="https://unpkg.com/kitsu-core"></script>

kitsuCore.camel(...)

Contributing

See CONTRIBUTING

Releases

See CHANGELOG

License

All code released under MIT

API

Table of Contents

• camel
  • Parameters
  • Examples
• deattribute
  • Parameters
  • Examples
• deserialise
  • Parameters
  • Examples
• error
  • Parameters
  • Examples
• filterIncludes
  • Parameters
  • Examples
• kebab
  • Parameters
  • Examples
• linkRelationships
  • Parameters
  • Examples
• isDeepEqual
  • Parameters
  • Examples
• query
  • Parameters
  • Examples
• serialise
  • Parameters
  • Examples
• snake
  • Parameters
  • Examples
• splitModel
  • Parameters
  • Examples

camel

packages/kitsu-core/src/camel/index.js:14-14

Converts kebab-case and snake_case into camelCase

Parameters

• input string String to convert

Examples

Convert kebab-case

camel('hello-world') // 'helloWorld'

Convert snake_case

camel('hello_world') // 'helloWorld'

Returns string camelCase formatted string

deattribute

packages/kitsu-core/src/deattribute/index.js:29-51

Hoists attributes to be top-level

Parameters

• data (Object | Array<Object>) Resource data

Examples

Deattribute an array of resources

// JSON:API 'data' field
const data = [
  {
    id: '1',
    type: 'users',
    attributes: { slug: 'wopian' }
  }
]

const output = deattribute(data) // [ { id: '1', type: 'users', slug: 'wopian' } ]

Deattribute a resource

// JSON:API 'data' field
const data = {
  id: '1',
  type: 'users',
  attributes: { slug: 'wopian' }
}

const output = deattribute(data) // { id: '1', type: 'users', slug: 'wopian' }

Returns (Object | Array<Object>) Deattributed resource data

deserialise

packages/kitsu-core/src/deserialise/index.js:62-77

Deserialises a JSON-API response

Parameters

• response Object The raw JSON:API response object

Examples

Deserialise with a basic data object

deserialise({
  data: {
    id: '1',
    attributes: { liked: true }
  },
  meta: { hello: 'world' }
}) // { data: { id: '1', liked: true }, meta: { hello: 'world' } }

Deserialise with relationships

deserialise({
  data: {
    id: '1',
    relationships: {
      user: {
        data: {
          type: 'users',
          id: '2' }
      }
    }
  },
  included: [
    {
      type: 'users',
      id: '2',
      attributes: { slug: 'wopian' }
    }
  ]
}) // { data: { id: '1', user: { data: { type: 'users', id: '2', slug: 'wopian' } } } }

Returns Object The deserialised response

error

packages/kitsu-core/src/error/index.js:27-33

Uniform error handling for Axios, JSON:API and internal package errors. Mutated Error object is rethrown to the caller.

Parameters

• Error Object The Error

Examples

error('Hello')

error({errors: [ { code: 400 } ]})

error({
  response: {
    data: {
      errors: [ {
        title: 'Filter is not allowed',
        detail: 'x is not allowed',
        code: '102',
        status: '400'
      } ]
    }
  }
})

• Throws Object The mutated Error

filterIncludes

packages/kitsu-core/src/filterIncludes/index.js:33-46

Filters includes for the specific relationship requested

Parameters

• included Array<Object> The response included object

• relationship Object

  • relationship.id string The relationship ID
  • relationship.type string The relationship type

Examples

const includes = [
  {
    id: '1',
    type: 'users',
    attributes: { name: 'Emma' }
  },
  {
    id: '2',
    type: 'users',
    attributes: { name: 'Josh' }
  }
]
const relationship = { id: '1', type: 'users' }
const response = filterIncludes(includes, relationship)
// {
//   id: '1',
//   type: 'users',
//   attributes: { name: 'Emma' }
// }

Returns Array<Object> The matched includes

kebab

packages/kitsu-core/src/kebab/index.js:11-11

Converts camelCase into kebab-case

Parameters

• input string camelCase string

Examples

kebab('helloWorld') // 'hello-world'

Returns string kebab-case formatted string

linkRelationships

packages/kitsu-core/src/linkRelationships/index.js:145-165

Links relationships to included data

Parameters

• data Object The response data object
• included Array<Object>? The response included object (optional, default [])
• previouslyLinked Object? A mapping of already visited resources (internal use only) (optional, default {})
• relationshipCache Object? A cache object for relationship meta and links (optional, default {})

Examples

const data = {
  attributes: { author: 'Joe' },
  relationships: {
    author: {
      data: { id: '1', type: 'people' }
    }
  }
}
const included = [ {
  id: '1',
  type: 'people',
  attributes: { name: 'Joe' }
} ]
const output = linkRelationships(data, included)
// {
//   attributes: { author: 'Joe' },
//   author: {
//     data: { id: '1', name: 'Joe', type: 'people' }
//   }
// }

Returns any Parsed data

isDeepEqual

packages/kitsu-core/src/deepEqual/index.js:18-42

Compare two objects equality

Parameters

• left Object Object to compare against the right object
• right Object Object to compare against the left object

Examples

Deep equality check

isDeepEqual({
  firstName: 'John',
  lastName: 'Doe',
  age: 35
},{
  firstName: 'John',
  lastName: 'Doe',
  age: 35
}) // true

Returns boolean Whether the objects are equal

query

packages/kitsu-core/src/query/index.js:55-64

Constructs a URL query string for JSON:API parameters

Parameters

• params Object? Parameters to parse
• prefix string? Prefix for nested parameters - used internally (optional, default null)
• traditional boolean Use the traditional (default) or modern param serializer. Set to false if your server is running Ruby on Rails or other modern web frameworks (optional, default true)

Examples

query({
  filter: {
    slug: 'cowboy-bebop',
    title: {
      value: 'foo'
    }
  }
 sort: '-id'
})
// filter%5Bslug%5D=cowboy-bebop&filter%5Btitle%5D%5Bvalue%5D=foo&sort=-id

Returns string URL query string

serialise

packages/kitsu-core/src/serialise/index.js:213-224

Serialises an object into a JSON-API structure

Parameters

• type string Resource type

• data (Object | Array<Object>)? The data (optional, default {})

• method string? Request type (PATCH, POST, DELETE) (optional, default 'POST')

• options Object? Optional configuration for camelCase and pluralisation handling (optional, default {})

  • options.camelCaseTypes Function Convert library-entries and library_entries to libraryEntries (default no conversion). To use parameter, import camel from kitsu-core (optional, default s=>s)
  • options.pluralTypes Function Pluralise types (default no pluralisation). To use parameter, import pluralize (or another pluralisation npm package) (optional, default s=>s)

Examples

Setting camelCaseTypes and pluralTypes options (example shows options used by the kitsu package by default)

import { serialise, camel } from 'kitsu-core'
import pluralize from 'pluralize'

const model = 'anime'
const obj = { id: '1', slug: 'shirobako' }

// { data: { id: '1', type: 'anime', attributes: { slug: 'shirobako' } } }
const output = serialise(model, obj, 'PATCH', { camelCaseTypes: camel, pluralTypes: pluralize })

Basic usage (no case conversion or pluralisation)

import { serialise } from 'kitsu-core'

const model = 'anime'
const obj = { id: '1', slug: 'shirobako' }

// { data: { id: '1', type: 'anime', attributes: { slug: 'shirobako' } } }
const output = serialise(model, obj, 'PATCH')

Returns Object The serialised data

snake

packages/kitsu-core/src/snake/index.js:11-11

Converts camelCase into snake_case

Parameters

• input string camelCase string

Examples

snake('helloWorld') // 'hello_world'

Returns string snake_case formatted string

splitModel

packages/kitsu-core/src/splitModel/index.js:29-39

Split model name from the model's resource URL

Parameters

• url string URL path for the model

• options Object? Optional configuration for camelCase and pluralisation handling

  • options.resourceCase Function Convert libraryEntries to library-entries or library_entries (default no conversion). To use parameter, import kebab or snake from kitsu-core (optional, default s=>s)
  • options.pluralModel Function Pluralise models (default no pluralisation). To use parameter, import pluralize (or another pluralisation npm package) (optional, default s=>s)

Examples

splitModel('posts/1/comments')
// [ 'comments', 'posts/1/comments' ]

With pluralModel option

import plural from 'pluralize'
splitModel('posts/1/comment', { pluralModel: plural })
// [ 'comment', 'posts/1/comments' ]

With resourceCase option

import { kebab, snake } from 'kitsu-core'
splitModel('libraryEntries', { resourceCase: kebab })
// [ 'libraryEntries', 'library-entries' ]

splitModel('libraryEntries', { resourceCase: snake })
// [ 'libraryEntries', 'library_entries' ]

Returns [string, string] } Array containing the model name and the resource URL with pluralisation applied