Kitsu Core
Core JSON:API serialisation and deserialisation components
Check out the Migration Guide for breaking changes in 6.x
#
## Features
- JSON-API 1.0 compliant
- Automatically links relationships to data
- Works in Node and on the web
- Uses the [Promise] API
## Node / Browser Support
| Package | Package
Size\* | Node | Chrome | Firefox | Safari | Edge | IE |
| ----------------: | :----------------: | :--: | :----: | :-----: | :----: | :--: | :-: |
| `kitsu-core` | ≤ 4.3 kb | 6+ | 54+ | 51+ | 10+ | 15+ | |
| `kitsu-core/node` | ≤ 1.5 kb | 6+ | | | | | |
\* Including all dependencies, minified & gzipped
## Install
### Yarn / NPM
```bash
yarn add kitsu-core
npm install kitsu-core
```
```js
import { camel } from 'kitsu-core' // ES Modules and Babel
import { camel } from 'kitsu-core/node' // Lighter node-only package
const { camel } = require('kitsu-core') // CommonJS and Browserify
camel(...)
```
### Packd CDN
```html
```
```js
kitsuCore.camel(...)
```
## API
#### Table of Contents
- [deattribute](#deattribute)
- [Parameters](#parameters)
- [Examples](#examples)
- [deserialise](#deserialise)
- [Parameters](#parameters-1)
- [Examples](#examples-1)
- [error](#error)
- [Parameters](#parameters-2)
- [filterIncludes](#filterincludes)
- [Parameters](#parameters-3)
- [linkRelationships](#linkrelationships)
- [Parameters](#parameters-4)
- [queryFormat](#queryformat)
- [Parameters](#parameters-5)
- [query](#query)
- [Parameters](#parameters-6)
- [isValid](#isvalid)
- [Parameters](#parameters-7)
- [serialise](#serialise)
- [Parameters](#parameters-8)
- [Examples](#examples-2)
- [camel](#camel)
- [Parameters](#parameters-9)
- [Examples](#examples-3)
- [kebab](#kebab)
- [Parameters](#parameters-10)
- [Examples](#examples-4)
- [snake](#snake)
- [Parameters](#parameters-11)
- [Examples](#examples-5)
### deattribute
[packages/kitsu-core/src/deattribute/index.js:29-38](https://github.com/wopian/kitsu/blob/77a568d003a49a776c5eedd684e865b112a9af93/packages/kitsu-core/src/deattribute/index.js#L29-L38 "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))** Resource data
#### Examples
_Deattribute an array of resources_
```javascript
// JSON:API 'data' field
const data = [
{
id: '1',
type: 'users',
attributes: { slug: 'wopian' }
}
]
const output = await 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 = await 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))** Deattributed resource data
### deserialise
[packages/kitsu-core/src/deserialise/index.js:56-70](https://github.com/wopian/kitsu/blob/77a568d003a49a776c5eedd684e865b112a9af93/packages/kitsu-core/src/deserialise/index.js#L56-L70 "Source code on GitHub")
Deserialises a JSON-API response
#### Parameters
- `obj` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The response
#### Examples
_Deserialise with a basic data object_
```javascript
await deserialise({
data: {
id: '1',
attributes: { liked: true }
},
meta: { hello: 'world' }
}) // { data: { id: '1', liked: true }, meta: { hello: 'world' } }
```
_Deserialise with relationships_
```javascript
await deserialise({
data: {
id: '1',
relationships: {
user: {
data: {
type: 'users',
id: '2' }
}
}
},
included: [
{
type: 'users',
id: '2',
attributes: { slug: 'wopian' }
}
]
}) // { data: { id: '1', user: { 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:7-13](https://github.com/wopian/kitsu/blob/77a568d003a49a776c5eedd684e865b112a9af93/packages/kitsu-core/src/error/index.js#L7-L13 "Source code on GitHub")
Mutates an error and rethrows it
#### Parameters
- `E` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The Error
- Throws **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The mutated Error
### filterIncludes
[packages/kitsu-core/src/filterIncludes/index.js:12-21](https://github.com/wopian/kitsu/blob/77a568d003a49a776c5eedd684e865b112a9af93/packages/kitsu-core/src/filterIncludes/index.js#L12-L21 "Source code on GitHub")
Filters includes for the specific relationship
#### Parameters
- `included` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The response included object
- `opts` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**
- `opts.id` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The relationship ID
- `opts.type` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The relationship type
Returns **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)** The matched includes
### linkRelationships
[packages/kitsu-core/src/linkRelationships/index.js:55-74](https://github.com/wopian/kitsu/blob/77a568d003a49a776c5eedd684e865b112a9af93/packages/kitsu-core/src/linkRelationships/index.js#L55-L74 "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` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The response included object
### queryFormat
[packages/kitsu-core/src/query/index.js:8-11](https://github.com/wopian/kitsu/blob/77a568d003a49a776c5eedd684e865b112a9af93/packages/kitsu-core/src/query/index.js#L8-L11 "Source code on GitHub")
Formats a single URL query
#### Parameters
- `value` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Right-hand side of the query
- `key` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Left-hand side of the query
Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** URL query string
### query
[packages/kitsu-core/src/query/index.js:20-31](https://github.com/wopian/kitsu/blob/77a568d003a49a776c5eedd684e865b112a9af93/packages/kitsu-core/src/query/index.js#L20-L31 "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 (default `null`) (optional, default `null`)
Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** URL query string
### isValid
[packages/kitsu-core/src/serialise/index.js:11-20](https://github.com/wopian/kitsu/blob/77a568d003a49a776c5eedd684e865b112a9af93/packages/kitsu-core/src/serialise/index.js#L11-L20 "Source code on GitHub")
Checks if data is valid for serialisation
#### Parameters
- `obj` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The data
- `method` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Request type
- `type`
### serialise
[packages/kitsu-core/src/serialise/index.js:67-92](https://github.com/wopian/kitsu/blob/77a568d003a49a776c5eedd684e865b112a9af93/packages/kitsu-core/src/serialise/index.js#L67-L92 "Source code on GitHub")
Serialises an object into a JSON-API structure
#### Parameters
- `model` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Request model
- `obj` **[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 (optional, default `'POST'`)
#### Examples
_Due to its usage in kitsu, it **MUST** be called with **this** set in 6.0.x_
```javascript
import { serialise, camel, kebab } from 'kitsu-core'
import plural from 'pluralize'
const output = await serialise.apply({ camel, resCase: kebab, plural }, [ model, obj, 'PATCH' ])
```
Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The serialised data
### camel
[packages/kitsu-core/src/camel/index.js:14-14](https://github.com/wopian/kitsu/blob/77a568d003a49a776c5eedd684e865b112a9af93/packages/kitsu-core/src/camel/index.js#L14-L14 "Source code on GitHub")
Converts kebab-case and snake_case into camelCase
#### Parameters
- `s` **[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
### kebab
[packages/kitsu-core/src/kebab/index.js:11-11](https://github.com/wopian/kitsu/blob/77a568d003a49a776c5eedd684e865b112a9af93/packages/kitsu-core/src/kebab/index.js#L11-L11 "Source code on GitHub")
Converts camelCase into kebab-case
#### Parameters
- `s` **[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)** kekab-case formatted string
### snake
[packages/kitsu-core/src/snake/index.js:11-11](https://github.com/wopian/kitsu/blob/77a568d003a49a776c5eedd684e865b112a9af93/packages/kitsu-core/src/snake/index.js#L11-L11 "Source code on GitHub")
Converts camelCase into snake_case
#### Parameters
- `s` **[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
## Contributing
See [CONTRIBUTING]
## Releases
See [CHANGELOG]
## License
All code released under [MIT]
[json:api]: http://jsonapi.org
[promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises
[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