npm.io
11.1.0 • Published 10 months ago

kitsu-core

Licence
MIT
Version
11.1.0
Deps
0
Size
107 kB
Vulns
0
Weekly
0
Stars
294
SummaryDependencyVersions

Kitsu Core

npm npm bundlephobia types

checks repoDependants contributors sponsor

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-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

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

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
  • object any 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

  • response Object The raw JSON:API response object

  • options Object Deserialisation options (optional, default {})

    • options.hoistData boolean If enabled, the contents of the data property will be hoisted to the parent. This provides a flatter response object, but removes access to links and meta properties. 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, default false)
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
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

  • included Array<Object> The response included object

  • relationship Object

    • relationship.id string The relationship ID
    • relationship.type string The relationship type
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
  • input string 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
  • data Object The response data object
  • included 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 object
  • right 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:57-66

Constructs a URL query string for JSON:API parameters

Parameters
  • params Object? Parameters to parse
  • prefix string? Prefix for nested parameters - used internally (optional, default undefined)
  • 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, default true)
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:210-221

Serialises an object into a JSON-API structure

Parameters

  • type string Resource type

  • data (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, default s=>s)
    • options.pluralTypes 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)

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 model

  • options Object? Optional configuration for camelCase and pluralisation handling

    • options.resourceCase 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 Pluralise models (default no pluralisation). To use parameter, import pluralize (or another pluralisation npm package) (optional, default s=>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

Keywords

kitsujsonapijson-apiserializedeserialize