kitsu-core

Kitsu Core

Core JSON:API serialisation and deserialisation components

Features

• JSON-API 1.0 compliant
• Automatically links relationships to data
• Works in Node and on the web

Node / Browser Support

Package	Package Size*	Node	Chrome	Firefox	Safari	Edge
kitsu-core†	≤ 1.4 kb	10+	79+	68+	12.1+	18+

* Including all dependencies, minified & gzipped

† Changes in Node 12 and newer require the full path to be used if using ES Modules: kitsu-core/index.mjs

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(...)

API

Table of Contents

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

deattribute

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

Hoists attributes to be top-level

Parameters

• data (Object | Array) 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) Deattributed resource data

deserialise

packages/kitsu-core/src/deserialise/index.js:57-74

Deserialises a JSON-API response

Parameters

• obj Object The response

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: { type: 'users', id: '2', slug: 'wopian' } } }

Returns Object The deserialised response

error

packages/kitsu-core/src/error/index.js:7-13

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

Parameters

• E Object The Error

• Throws Object The mutated Error

filterIncludes

packages/kitsu-core/src/filterIncludes/index.js:12-25

Filters includes for the specific relationship

Parameters

• included Object The response included object
• opts Object
  • opts.id string The relationship ID
  • opts.type string The relationship type

Returns Array The matched includes

linkRelationships

packages/kitsu-core/src/linkRelationships/index.js:75-96

Links relationships to included data

Parameters

• data Object The response data object
• included Object The response included object (optional, default [])

query

packages/kitsu-core/src/query/index.js:21-32

Constructs a URL query string for JSON:API parameters

Parameters

• params Object Parameters to parse
• prefix string Prefix for nested parameters - used internally (default null) (optional, default null)

Returns string URL query string

serialise

packages/kitsu-core/src/serialise/index.js:119-152

Serialises an object into a JSON-API structure

Parameters

• model string Request model
• obj 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
  • options.pluralTypes Function Pluralise types (default no pluralisation). To use parameter, import pluralize (or another pluralisation npm package)

Examples

Setting camelCaseTypes and pluralTypes options (example shows options used by kitsu 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

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

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 Array Array containing the model name and the resource URL with pluralisation applied

camel

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

Converts kebab-case and snake_case into camelCase

Parameters

• s string String to convert

Examples

Convert kebab-case

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

Convert snake_case

camel('hello_world') // 'helloWorld'

Returns string camelCase formatted string

kebab

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

Converts camelCase into kebab-case

Parameters

• s string camelCase string

Examples

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

Returns string kebab-case formatted string

snake

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

Converts camelCase into snake_case

Parameters

• s string camelCase string

Examples

snake('helloWorld') // 'hello_world'

Returns string snake_case formatted string

Contributing

See CONTRIBUTING

Releases

See CHANGELOG

License

All code released under MIT

Changelog

9.0.0 (2020-05-07)

Build System / Dependencies

• update jest monorepo to ~26.0.0 (major) (#407) (a73ae66)
• kitsu: update devdependency @size-limit/preset-small-lib to ~4.5.0 (#405) (7e0072d)
• update devdependency size-limit to ~4.5.0 (#406) (fb7a139)

Chores

• release: update documentation (08362a8)

Documentation Changes

• kitsu: add 9.0.0 migration guide (8f899c5)
• kitsu-core: add 9.0.0 migration guide (8576749)
• update README (6a73433)
• kitsu-core: use lowercase string for param type (8254710)

New Features

• kitsu: handle nested (relationship) routes using kitsu-core's splitModel (4f641b9)
• kitsu-core: add splitModel (782d1b6)
• kitsu-core: preserve links in relationships during deserialisation (cbf50df)

Refactors

• kitsu: (internal) pass camel and plural options as arguments to serialise (046b51a)
• kitsu-core: pass camelCase and pluralisation options as arguments to serialise (34b9cae)

BREAKING CHANGES

• kitsu-core: for deserialise and linkRelationships
• kitsu-core: serialise.apply[{ camel, resCase, plural}, [ model, data, method ]) is no longer neccessary. New syntax is serialise(model, data, method, { camelCaseTypes: camel, pluralTypes: plural}).