kitsu-core

<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></a> <a href="https://david-dm.org/wopian/kitsu?path=packages/kitsu-core"><img alt=deps src="https://flat.badgen.net/david/dep/wopian/kitsu/packages/kitsu-core"></a> </p> <p align=center> <a href=https://travis-ci.org/wopian/kitsu><img alt=travis src=https://flat.badgen.net/travis/wopian/kitsu></a> <a href=https://ci.appveyor.com/project/wopian/kitsu><img alt=appveyor src=https://flat.badgen.net/appveyor/ci/wopian/kitsu></a> <a href="https://packagephobia.now.sh/result?p=kitsu-core"><img alt=packagephobia src=https://flat.badgen.net/packagephobia/install/kitsu-core></a> <a href=https://github.com/wopian/kitsu/graphs/contributors><img alt=contributors src=https://flat.badgen.net/github/contributors/wopian/kitsu></a> </p> <p align=center> <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://codeclimate.com/github/wopian/kitsu/trends/technical_debt><img alt="technical debt"src=https://flat.badgen.net/codeclimate/tech-debt/wopian/kitsu></a> <a href=https://codeclimate.com/github/wopian/kitsu/issues><img alt=issues src=https://flat.badgen.net/codeclimate/issues/wopian/kitsu></a> </p> <p align=center> <a href=https://paypal.me/wopian><img alt="support me on paypal.me"src=https://flat.badgen.net/badge/support%20me%20on/paypal.me/pink></a> </p> <p align=center>Core <a href=http://jsonapi.org>JSON:API</a> serialisation and deserialisation components</p> <p align=center><em>Check out the <a href=https://github.com/wopian/kitsu/blob/master/packages/kitsu-core/MIGRATING.md>Migration Guide</a> for breaking changes in <code>6.x</code></em></p> # ## 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<br> 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<br> ## 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 <script src='https://bundle.run/kitsu-core@6?name=kitsuCore'></script> ``` ```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