kitsu-core
Version:
Simple, lightweight & framework agnostic JSON:API (de)serialsation components
553 lines (393 loc) • 19.5 kB
Markdown
<h1 align=center>Kitsu Core</h1>
<p align=center>
<a href=https://www.npmjs.com/package/kitsu-core><img alt=npm src=https://flat.badgen.net/npm/v/kitsu-core></a>
<a href=https://www.npmjs.com/package/kitsu-core><img alt=npm src=https://flat.badgen.net/npm/dt/kitsu-core></a>
<a href="https://bundlephobia.com/result?p=kitsu-core"><img alt=bundlephobia src='https://flat.badgen.net/bundlephobia/minzip/kitsu-core?label=library%20size'></a>
<img alt=types src='https://flat.badgen.net/npm/types/kitsu-core'>
</p>
<p align=center>
<a href=https://github.com/wopian/kitsu/actions><img alt=checks src=https://flat.badgen.net/github/checks/wopian/kitsu></a>
<a href=https://codeclimate.com/github/wopian/kitsu/code?sort=test_coverage><img alt=coverage src=https://flat.badgen.net/codeclimate/coverage/wopian/kitsu></a>
<a href=https://codeclimate.com/github/wopian/kitsu/code?sort=maintainability><img alt=maintainability src=https://flat.badgen.net/codeclimate/maintainability/wopian/kitsu></a>
<a href=https://github.com/wopian/kitsu/network/dependents><img alt=repoDependants src=https://flat.badgen.net/github/dependents-repo/wopian/kitsu></a>
</p>
<p align=center>
<a href=https://github.com/wopian/kitsu/graphs/contributors><img alt=contributors src=https://flat.badgen.net/github/contributors/wopian/kitsu></a>
<a href=https://github.com/sponsors/wopian><img alt=sponsor src='https://flat.badgen.net/badge/sponsor/%E2%9D%A4/pink?icon=github'></a>
</p>
<p align=center>Simple, lightweight & framework agnostic <a href=http://jsonapi.org>JSON:API</a> (de)serialisation components</p>
<p align=center><a href=https://github.com/wopian/kitsu/blob/master/packages/kitsu-core/MIGRATING.md>Migration guide</a> for v10 & previous major releases</p>
#
## 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<br> 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
```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(...)
```
### CDNs
```html
<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/kitsu-core"></script>
<!-- unpkg -->
<script src="https://unpkg.com/kitsu-core"></script>
```
```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
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
#### Table of Contents
* [camel](#camel)
* [Parameters](#parameters)
* [Examples](#examples)
* [deattribute](#deattribute)
* [Parameters](#parameters-1)
* [Examples](#examples-1)
* [deserialise](#deserialise)
* [Parameters](#parameters-2)
* [Examples](#examples-2)
* [error](#error)
* [Parameters](#parameters-3)
* [Examples](#examples-3)
* [filterIncludes](#filterincludes)
* [Parameters](#parameters-4)
* [Examples](#examples-4)
* [kebab](#kebab)
* [Parameters](#parameters-5)
* [Examples](#examples-5)
* [linkRelationships](#linkrelationships)
* [Parameters](#parameters-6)
* [Examples](#examples-6)
* [isDeepEqual](#isdeepequal)
* [Parameters](#parameters-7)
* [Examples](#examples-7)
* [query](#query)
* [Parameters](#parameters-8)
* [Examples](#examples-8)
* [serialise](#serialise)
* [Parameters](#parameters-9)
* [Examples](#examples-9)
* [snake](#snake)
* [Parameters](#parameters-10)
* [Examples](#examples-10)
* [splitModel](#splitmodel)
* [Parameters](#parameters-11)
* [Examples](#examples-11)
### camel
[packages/kitsu-core/src/camel/index.js:14-14](https://github.com/wopian/kitsu/blob/8bf9d387e3bd45936dd6ec49f9bd6f043571b9e6/packages/kitsu-core/src/camel/index.js#L14-L14 "Source code on GitHub")
Converts kebab-case and snake\_case into camelCase
#### Parameters
* `input` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** String to convert
#### Examples
Convert kebab-case
```javascript
camel('hello-world') // 'helloWorld'
```
Convert snake\_case
```javascript
camel('hello_world') // 'helloWorld'
```
Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** camelCase formatted string
### deattribute
[packages/kitsu-core/src/deattribute/index.js:29-51](https://github.com/wopian/kitsu/blob/8bf9d387e3bd45936dd6ec49f9bd6f043571b9e6/packages/kitsu-core/src/deattribute/index.js#L29-L51 "Source code on GitHub")
Hoists attributes to be top-level
#### Parameters
* `data` **([Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) | [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) | [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>)** Deattributed resource data
### deserialise
[packages/kitsu-core/src/deserialise/index.js:62-77](https://github.com/wopian/kitsu/blob/8bf9d387e3bd45936dd6ec49f9bd6f043571b9e6/packages/kitsu-core/src/deserialise/index.js#L62-L77 "Source code on GitHub")
Deserialises a JSON-API response
#### Parameters
* `response` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The raw JSON:API response object
#### 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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The deserialised response
### error
[packages/kitsu-core/src/error/index.js:27-33](https://github.com/wopian/kitsu/blob/8bf9d387e3bd45936dd6ec49f9bd6f043571b9e6/packages/kitsu-core/src/error/index.js#L27-L33 "Source code on GitHub")
Uniform error handling for Axios, JSON:API and internal package errors. Mutated Error object is rethrown to the caller.
#### Parameters
* `Error` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The mutated Error
### filterIncludes
[packages/kitsu-core/src/filterIncludes/index.js:33-46](https://github.com/wopian/kitsu/blob/8bf9d387e3bd45936dd6ec49f9bd6f043571b9e6/packages/kitsu-core/src/filterIncludes/index.js#L33-L46 "Source code on GitHub")
Filters includes for the specific relationship requested
#### Parameters
* `included` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>** The response included object
* `relationship` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
* `relationship.id` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The relationship ID
* `relationship.type` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The matched includes
### kebab
[packages/kitsu-core/src/kebab/index.js:11-11](https://github.com/wopian/kitsu/blob/8bf9d387e3bd45936dd6ec49f9bd6f043571b9e6/packages/kitsu-core/src/kebab/index.js#L11-L11 "Source code on GitHub")
Converts camelCase into kebab-case
#### Parameters
* `input` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** camelCase string
#### Examples
```javascript
kebab('helloWorld') // 'hello-world'
```
Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** kebab-case formatted string
### linkRelationships
[packages/kitsu-core/src/linkRelationships/index.js:144-164](https://github.com/wopian/kitsu/blob/8bf9d387e3bd45936dd6ec49f9bd6f043571b9e6/packages/kitsu-core/src/linkRelationships/index.js#L144-L164 "Source code on GitHub")
Links relationships to included data
#### Parameters
* `data` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The response data object
* `included` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>?** The response included object (optional, default `[]`)
* `previouslyLinked` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** A mapping of already visited resources (internal use only) (optional, default `{}`)
* `relationshipCache` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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
### isDeepEqual
[packages/kitsu-core/src/deepEqual/index.js:18-42](https://github.com/wopian/kitsu/blob/8bf9d387e3bd45936dd6ec49f9bd6f043571b9e6/packages/kitsu-core/src/deepEqual/index.js#L18-L42 "Source code on GitHub")
Compare two objects equality
#### Parameters
* `left` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Object to compare against the right object
* `right` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether the objects are equal
### query
[packages/kitsu-core/src/query/index.js:57-66](https://github.com/wopian/kitsu/blob/8bf9d387e3bd45936dd6ec49f9bd6f043571b9e6/packages/kitsu-core/src/query/index.js#L57-L66 "Source code on GitHub")
Constructs a URL query string for JSON:API parameters
#### Parameters
* `params` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Parameters to parse
* `prefix` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Prefix for nested parameters - used internally (optional, default `undefined`)
* `traditional` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** URL query string
### serialise
[packages/kitsu-core/src/serialise/index.js:210-221](https://github.com/wopian/kitsu/blob/8bf9d387e3bd45936dd6ec49f9bd6f043571b9e6/packages/kitsu-core/src/serialise/index.js#L210-L221 "Source code on GitHub")
Serialises an object into a JSON-API structure
#### Parameters
* `type` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Resource type
* `data` **([Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) | [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>)?** The data (optional, default `{}`)
* `method` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Request type (PATCH, POST, DELETE) (optional, default `'POST'`)
* `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Optional configuration for camelCase and pluralisation handling (optional, default `{}`)
* `options.camelCaseTypes` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The serialised data
### snake
[packages/kitsu-core/src/snake/index.js:11-11](https://github.com/wopian/kitsu/blob/8bf9d387e3bd45936dd6ec49f9bd6f043571b9e6/packages/kitsu-core/src/snake/index.js#L11-L11 "Source code on GitHub")
Converts camelCase into snake\_case
#### Parameters
* `input` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** camelCase string
#### Examples
```javascript
snake('helloWorld') // 'hello_world'
```
Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** snake\_case formatted string
### splitModel
[packages/kitsu-core/src/splitModel/index.js:29-39](https://github.com/wopian/kitsu/blob/8bf9d387e3bd45936dd6ec49f9bd6f043571b9e6/packages/kitsu-core/src/splitModel/index.js#L29-L39 "Source code on GitHub")
Split model name from the model's resource URL
#### Parameters
* `url` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** URL path for the model
* `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Optional configuration for camelCase and pluralisation handling
* `options.resourceCase` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)]** } Array containing the model name and the resource URL with pluralisation applied