wopian
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
Yarn / NPM
yarn add kitsu-core
npm install kitsu-coreimport { 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
- deattribute
- hoist
- deserialise
- error
- filterIncludes
- kebab
- linkRelationships
- isDeepEqual
- query
- serialise
- snake
- splitModel
camel
packages/kitsu-core/src/camel/index.js:14-14
Converts kebab-case and snake_case into camelCase
Parameters
inputstring 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
hoist
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
objectany The input to hoist (object or array)
Returns any The hoisted object or array
deserialise
packages/kitsu-core/src/deserialise/index.js:150-170
Deserialises a JSON-API response
Parameters
responseObject The raw JSON:API response objectoptionsObject Deserialisation options (optional, default{})options.hoistDataboolean If enabled, the contents of thedataproperty will be hoisted to the parent. This provides a flatter response object, but removes access tolinksandmetaproperties. 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, defaultfalse)
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
ErrorObject 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
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 Object The matched includes
kebab
packages/kitsu-core/src/kebab/index.js:11-11
Converts camelCase into kebab-case
Parameters
inputstring camelCase string
Examples
kebab('helloWorld') // 'hello-world'Returns string kebab-case formatted string
linkRelationships
packages/kitsu-core/src/linkRelationships/index.js:144-164
Links relationships to included data
Parameters
dataObject The response data objectincludedArray<Object>? The response included object (optional, default[])previouslyLinkedObject? A mapping of already visited resources (internal use only) (optional, default{})relationshipCacheObject? 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
isDeepEqual
packages/kitsu-core/src/deepEqual/index.js:18-42
Compare two objects equality
Parameters
leftObject Object to compare against the right objectrightObject Object to compare against the left object
Examples
Deep equality check
isDeepEqual({
firstName: 'John',
lastName: 'Doe',
age: 35
},{
firstName: 'John',
lastName: 'Doe',
age: 35
}) // trueReturns boolean Whether the objects are equal
query
packages/kitsu-core/src/query/index.js:57-66
Constructs a URL query string for JSON:API parameters
Parameters
paramsObject? Parameters to parseprefixstring? Prefix for nested parameters - used internally (optional, defaultundefined)traditionalboolean 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, defaulttrue)
Examples
query({
filter: {
slug: 'cowboy-bebop',
title: {
value: 'foo'
}
}
sort: '-id'
})
// filter%5Bslug%5D=cowboy-bebop&filter%5Btitle%5D%5Bvalue%5D=foo&sort=-idReturns string URL query string
serialise
packages/kitsu-core/src/serialise/index.js:210-221
Serialises an object into a JSON-API structure
Parameters
typestring Resource typedata(Object | Array<Object>)? The data (optional, default{})methodstring? Request type (PATCH, POST, DELETE) (optional, default'POST')optionsObject? Optional configuration for camelCase and pluralisation handling (optional, default{})options.camelCaseTypesFunction Convert library-entries and library_entries to libraryEntries (default no conversion). To use parameter, import camel from kitsu-core (optional, defaults=>s)options.pluralTypesFunction Pluralise types (default no pluralisation). To use parameter, import pluralize (or another pluralisation npm package) (optional, defaults=>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
inputstring 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
urlstring URL path for the modeloptionsObject? Optional configuration for camelCase and pluralisation handlingoptions.resourceCaseFunction Convert libraryEntries to library-entries or library_entries (default no conversion). To use parameter, import kebab or snake from kitsu-core (optional, defaults=>s)options.pluralModelFunction Pluralise models (default no pluralisation). To use parameter, import pluralize (or another pluralisation npm package) (optional, defaults=>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