kitsu-core

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

Usage no npm install needed!

<script type="module">
  import kitsuCore from 'https://cdn.skypack.dev/kitsu-core';
</script>

README

Kitsu Core

npm npm deps bundlephobia types

checks coverage maintainability repoDependants

contributors sponsor

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 12+ 72+ 78+ 12.1+ 86+

* 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

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

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:57-72

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: { 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

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:108-128

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 {})

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