kitsu-core

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
• 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:127-147

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

query

packages/kitsu-core/src/query/index.js:33-42

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)

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

Changelog

10.0.2 (2022-08-17)

Bug Fixes

• kitsu-core: deserialize meta only relationships (#727) (5b2c64c)