Kitsu Core

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

Migration guide for v11 & 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 | ≤ 2.16 kb | ≤ 1.75 KB | 18+ | 116+ | 118+ | 17.1+ | 134+ |

\* Minified with brotli
† Guaranteed supported versions. Older versions may still work or might require polyfills

Install

$3

``bash
yarn add kitsu-core
npm install kitsu-core
`

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

camel(...)
`

$3

`html





`

`js
kitsuCore.camel(...)
`

Contributing

See [CONTRIBUTING]

Releases

See [CHANGELOG]

License

All code released under [MIT]

[json:api]: http://jsonapi.org

[changelog]: https://github.com/wopian/kitsu/blob/master/packages/kitsu-core/CHANGELOG.md

[contributing]: https://github.com/wopian/kitsu/blob/master/CONTRIBUTING.md

[mit]: https://github.com/wopian/kitsu/blob/master/LICENSE.md

API

#### Table of Contents

* camel
* Parameters
* Examples
* deattribute
* Parameters
* Examples
* hoist
* Parameters
* 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

$3

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

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

Convert snake\_case

`javascript
camel('hello_world') // 'helloWorld'
`

Returns string camelCase formatted string

$3

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

`javascript
// 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

`javascript
// 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

$3

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

Recursively traverses and clones an object or array, handling cyclic references.
If the object is a wrapper of the form { data: ... }, it unwraps and processes the data property.

#### Parameters

* object any The input to hoist (object or array)

Returns any The hoisted object or array

$3

packages/kitsu-core/src/deserialise/index.js:150-170

Deserialises a JSON-API response

#### Parameters

* response Object The raw JSON:API response object
* options Object Deserialisation options (optional, default {})

* options.hoistData boolean If enabled, the contents of the data property will be hoisted to the parent. This provides a flatter response object, but removes access to links and meta properties. It will transform:`js
{ data: { id: '1', type: 'people', coworkers: data: [ { id: '2', type: 'people' } ] } }
`into the following:`js
{ id: '1', type: 'people', coworkers: [ { id: '2', type: 'people' } ] }
` (optional, default false)

#### Examples

Deserialise with a basic data object

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

Deserialise with relationships

`javascript
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

$3

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

`javascript
error('Hello')
`

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

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

* Throws Object The mutated Error

$3

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

`javascript
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 Object The matched includes

$3

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

Converts camelCase into kebab-case

#### Parameters

* input string camelCase string

#### Examples

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

Returns string kebab-case formatted string

$3

packages/kitsu-core/src/linkRelationships/index.js:144-164

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

`javascript
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

$3

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

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

Returns boolean Whether the objects are equal

$3

packages/kitsu-core/src/query/index.js:57-66

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 undefined)
* 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

`javascript
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

$3

packages/kitsu-core/src/serialise/index.js:210-221

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)

`javascript
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)

`javascript
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

$3

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

Converts camelCase into snake\_case

#### Parameters

* input string camelCase string

#### Examples

`javascript
snake('helloWorld') // 'hello_world'
`

Returns string snake\_case formatted string

$3

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

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

With pluralModel option

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

With resourceCase option

`javascript
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