kitsu-core
v10.1.5
Published
Simple, lightweight & framework agnostic JSON:API (de)serialsation components
Downloads
42,681
Maintainers
Readme
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 | 14+ | 83+ | 78+ | 13.1+ | 95+ |
* 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
- deattribute
- 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
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:62-77
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: { 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
Error
Object 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
relationship
Object
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:145-165
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
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
left
Object Object to compare against the right objectright
Object Object to compare against the left object
Examples
Deep equality check
isDeepEqual({
firstName: 'John',
lastName: 'Doe',
age: 35
},{
firstName: 'John',
lastName: 'Doe',
age: 35
}) // true
Returns boolean Whether the objects are equal
query
packages/kitsu-core/src/query/index.js:55-64
Constructs a URL query string for JSON:API parameters
Parameters
params
Object? Parameters to parseprefix
string? Prefix for nested parameters - used internally (optional, defaultnull
)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, defaulttrue
)
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 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, defaults=>s
)options.pluralTypes
Function 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
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 modeloptions
Object? Optional configuration for camelCase and pluralisation handlingoptions.resourceCase
Function 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.pluralModel
Function 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