Simple, lightweight & framework agnostic JSON:API (de)serialsation components
npm install kitsu-coreSimple, lightweight & framework agnostic JSON:API (de)serialisation components
Migration guide for v11 & previous major releases
#
* JSON-API 1.0 compliant
* Automatically links relationships to data
* Works in Node & browsers
* Tree shakeable components
* Zero dependencies
| 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
``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(...)
`
`html
`
`js`
kitsuCore.camel(...)
See [CONTRIBUTING]
See [CHANGELOG]
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
#### 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
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
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
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
packages/kitsu-core/src/deserialise/index.js:150-170
Deserialises a JSON-API response
#### Parameters
* response Object The raw JSON:API response objectoptions
* 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
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
packages/kitsu-core/src/filterIncludes/index.js:33-46
Filters includes for the specific relationship requested
#### Parameters
* included Array<Object> The response included objectrelationship
* Object
* relationship.id string The relationship IDrelationship.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
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
packages/kitsu-core/src/linkRelationships/index.js:144-164
Links relationships to included data
#### Parameters
* data Object The response data objectincluded
* 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
packages/kitsu-core/src/deepEqual/index.js:18-42
Compare two objects equality
#### Parameters
* left Object Object to compare against the right objectright
* 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
packages/kitsu-core/src/query/index.js:57-66
Constructs a URL query string for JSON:API parameters
#### Parameters
* params Object? Parameters to parseprefix
* 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
packages/kitsu-core/src/serialise/index.js:210-221
Serialises an object into a JSON-API structure
#### Parameters
* type string Resource typedata
* (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
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
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 modeloptions
* 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