diff --git a/packages/kitsu-core/README.md b/packages/kitsu-core/README.md index 55838e79..9116e174 100644 --- a/packages/kitsu-core/README.md +++ b/packages/kitsu-core/README.md @@ -28,11 +28,11 @@ ## Features -- JSON-API 1.0 compliant -- Automatically links relationships to data -- Works in Node & browsers -- Tree shakeable components -- Zero dependencies +* JSON-API 1.0 compliant +* Automatically links relationships to data +* Works in Node & browsers +* Tree shakeable components +* Zero dependencies ## Node / Browser Support @@ -86,8 +86,11 @@ See [CHANGELOG] 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 @@ -96,75 +99,75 @@ All code released under [MIT] #### 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) -- [query](#query) - - [Parameters](#parameters-7) - - [Examples](#examples-7) -- [serialise](#serialise) - - [Parameters](#parameters-8) - - [Examples](#examples-8) -- [snake](#snake) - - [Parameters](#parameters-9) - - [Examples](#examples-9) -- [splitModel](#splitmodel) - - [Parameters](#parameters-10) - - [Examples](#examples-10) +* [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) +* [query](#query) + * [Parameters](#parameters-7) + * [Examples](#examples-7) +* [serialise](#serialise) + * [Parameters](#parameters-8) + * [Examples](#examples-8) +* [snake](#snake) + * [Parameters](#parameters-9) + * [Examples](#examples-9) +* [splitModel](#splitmodel) + * [Parameters](#parameters-10) + * [Examples](#examples-10) ### camel -[packages/kitsu-core/src/camel/index.js:14-14](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu-core/src/camel/index.js#L14-L14 "Source code on GitHub") +[packages/kitsu-core/src/camel/index.js:14-14](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/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 +* `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' +camel('hello-world') // 'helloWorld' ``` Convert snake_case ```javascript -camel("hello_world"); // 'helloWorld' +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/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu-core/src/deattribute/index.js#L29-L51 "Source code on GitHub") +[packages/kitsu-core/src/deattribute/index.js:29-51](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/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 +* `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 @@ -174,13 +177,13 @@ Deattribute an array of resources // JSON:API 'data' field const data = [ { - id: "1", - type: "users", - attributes: { slug: "wopian" }, - }, -]; + id: '1', + type: 'users', + attributes: { slug: 'wopian' } + } +] -const output = deattribute(data); // [ { id: '1', type: 'users', slug: 'wopian' } ] +const output = deattribute(data) // [ { id: '1', type: 'users', slug: 'wopian' } ] ``` Deattribute a resource @@ -188,25 +191,25 @@ Deattribute a resource ```javascript // JSON:API 'data' field const data = { - id: "1", - type: "users", - attributes: { slug: "wopian" }, -}; + id: '1', + type: 'users', + attributes: { slug: 'wopian' } +} -const output = deattribute(data); // { id: '1', type: 'users', 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:57-72](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu-core/src/deserialise/index.js#L57-L72 "Source code on GitHub") +[packages/kitsu-core/src/deserialise/index.js:57-72](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/packages/kitsu-core/src/deserialise/index.js#L57-L72 "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 +* `response` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The raw JSON:API response object #### Examples @@ -215,11 +218,11 @@ Deserialise with a basic data object ```javascript deserialise({ data: { - id: "1", - attributes: { liked: true }, + id: '1', + attributes: { liked: true } }, - meta: { hello: "world" }, -}); // { data: { id: '1', liked: true }, meta: { hello: 'world' } } + meta: { hello: 'world' } +}) // { data: { id: '1', liked: true }, meta: { hello: 'world' } } ``` Deserialise with relationships @@ -227,98 +230,95 @@ Deserialise with relationships ```javascript deserialise({ data: { - id: "1", + id: '1', relationships: { user: { data: { - type: "users", - id: "2", - }, - }, - }, + type: 'users', + id: '2' } + } + } }, included: [ { - type: "users", - id: "2", - attributes: { slug: "wopian" }, - }, - ], -}); // { data: { id: '1', user: { type: 'users', id: '2', slug: 'wopian' } } } + 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:27-33](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu-core/src/error/index.js#L27-L33 "Source code on GitHub") +[packages/kitsu-core/src/error/index.js:27-33](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/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 +* `Error` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The Error #### Examples ```javascript -error("Hello"); +error('Hello') ``` ```javascript -error({ errors: [{ code: 400 }] }); +error({errors: [ { code: 400 } ]}) ``` ```javascript error({ response: { data: { - errors: [ - { - title: "Filter is not allowed", - detail: "x is not allowed", - code: "102", - status: "400", - }, - ], - }, - }, -}); + 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 +* 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/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu-core/src/filterIncludes/index.js#L33-L46 "Source code on GitHub") +[packages/kitsu-core/src/filterIncludes/index.js:33-46](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/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)** +* `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 + * `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: '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: '2', + type: 'users', + attributes: { name: 'Josh' } + } +] +const relationship = { id: '1', type: 'users' } +const response = filterIncludes(includes, relationship) // { // id: '1', // type: 'users', @@ -330,53 +330,51 @@ Returns **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Gl ### kebab -[packages/kitsu-core/src/kebab/index.js:11-11](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu-core/src/kebab/index.js#L11-L11 "Source code on GitHub") +[packages/kitsu-core/src/kebab/index.js:11-11](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/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 +* `input` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** camelCase string #### Examples ```javascript -kebab("helloWorld"); // 'hello-world' +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:108-128](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu-core/src/linkRelationships/index.js#L108-L128 "Source code on GitHub") +[packages/kitsu-core/src/linkRelationships/index.js:108-128](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/packages/kitsu-core/src/linkRelationships/index.js#L108-L128 "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 `{}`) +* `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 `{}`) #### Examples ```javascript const data = { - attributes: { author: "Joe" }, + attributes: { author: 'Joe' }, relationships: { author: { - data: { id: "1", type: "people" }, - }, - }, -}; -const included = [ - { - id: "1", - type: "people", - attributes: { name: "Joe" }, - }, -]; -const output = linkRelationships(data, included); + data: { id: '1', type: 'people' } + } + } +} +const included = [ { + id: '1', + type: 'people', + attributes: { name: 'Joe' } +} ] +const output = linkRelationships(data, included) // { // attributes: { author: 'Joe' }, // author: { @@ -389,14 +387,14 @@ Returns **any** Parsed data ### query -[packages/kitsu-core/src/query/index.js:33-42](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu-core/src/query/index.js#L33-L42 "Source code on GitHub") +[packages/kitsu-core/src/query/index.js:33-42](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/packages/kitsu-core/src/query/index.js#L33-L42 "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 `null`) +* `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 `null`) #### Examples @@ -417,107 +415,104 @@ Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G ### serialise -[packages/kitsu-core/src/serialise/index.js:213-224](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu-core/src/serialise/index.js#L213-L224 "Source code on GitHub") +[packages/kitsu-core/src/serialise/index.js:213-224](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/packages/kitsu-core/src/serialise/index.js#L213-L224 "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 `{}`) +* `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`) + * `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"; +import { serialise, camel } from 'kitsu-core' +import pluralize from 'pluralize' -const model = "anime"; -const obj = { id: "1", slug: "shirobako" }; +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, -}); +const output = serialise(model, obj, 'PATCH', { camelCaseTypes: camel, pluralTypes: pluralize }) ``` Basic usage (no case conversion or pluralisation) ```javascript -import { serialise } from "kitsu-core"; +import { serialise } from 'kitsu-core' -const model = "anime"; -const obj = { id: "1", slug: "shirobako" }; +const model = 'anime' +const obj = { id: '1', slug: 'shirobako' } // { data: { id: '1', type: 'anime', attributes: { slug: 'shirobako' } } } -const output = serialise(model, obj, "PATCH"); +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/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu-core/src/snake/index.js#L11-L11 "Source code on GitHub") +[packages/kitsu-core/src/snake/index.js:11-11](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/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 +* `input` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** camelCase string #### Examples ```javascript -snake("helloWorld"); // 'hello_world' +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/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu-core/src/splitModel/index.js#L29-L39 "Source code on GitHub") +[packages/kitsu-core/src/splitModel/index.js:29-39](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/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 +* `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`) + * `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"); +splitModel('posts/1/comments') // [ 'comments', 'posts/1/comments' ] ``` With pluralModel option ```javascript -import plural from "pluralize"; -splitModel("posts/1/comment", { pluralModel: plural }); +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 }); +import { kebab, snake } from 'kitsu-core' +splitModel('libraryEntries', { resourceCase: kebab }) // [ 'libraryEntries', 'library-entries' ] -splitModel("libraryEntries", { resourceCase: snake }); +splitModel('libraryEntries', { resourceCase: snake }) // [ 'libraryEntries', 'library_entries' ] ``` diff --git a/packages/kitsu/README.md b/packages/kitsu/README.md index 88233909..84a1fefe 100644 --- a/packages/kitsu/README.md +++ b/packages/kitsu/README.md @@ -28,10 +28,10 @@ ## Features -- JSON-API 1.0 compliant -- Automatically links relationships to data -- Works in Node & browsers -- Uses the [Promise] API +* JSON-API 1.0 compliant +* Automatically links relationships to data +* Works in Node & browsers +* Uses the [Promise] API ## Node / Browser Support @@ -189,13 +189,21 @@ See [CHANGELOG] All code released under [MIT] [kitsu.io]: https://kitsu.io + [json:api]: http://jsonapi.org + [promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises + [more examples]: https://github.com/wopian/kitsu/tree/master/packages/kitsu/example + [kitsu.io api docs]: https://kitsu.docs.apiary.io + [migration guide]: https://github.com/wopian/kitsu/blob/master/packages/kitsu/MIGRATING.md + [changelog]: https://github.com/wopian/kitsu/blob/master/packages/kitsu/CHANGELOG.md + [contributing]: https://github.com/wopian/kitsu/blob/master/CONTRIBUTING.md + [mit]: https://github.com/wopian/kitsu/blob/master/LICENSE.md ## API @@ -204,66 +212,66 @@ All code released under [MIT] #### Table of Contents -- [Kitsu](#kitsu) - - [Parameters](#parameters) - - [Examples](#examples) - - [plural](#plural) - - [Examples](#examples-1) - - [headers](#headers) - - [Examples](#examples-2) - - [interceptors](#interceptors) - - [Examples](#examples-3) - - [get](#get) - - [Parameters](#parameters-1) - - [Examples](#examples-4) - - [patch](#patch) - - [Parameters](#parameters-2) - - [Examples](#examples-5) - - [post](#post) - - [Parameters](#parameters-3) - - [Examples](#examples-6) - - [delete](#delete) - - [Parameters](#parameters-4) - - [Examples](#examples-7) - - [self](#self) - - [Parameters](#parameters-5) - - [Examples](#examples-8) - - [request](#request) - - [Parameters](#parameters-6) - - [Examples](#examples-9) +* [Kitsu](#kitsu) + * [Parameters](#parameters) + * [Examples](#examples) + * [plural](#plural) + * [Examples](#examples-1) + * [headers](#headers) + * [Examples](#examples-2) + * [interceptors](#interceptors) + * [Examples](#examples-3) + * [get](#get) + * [Parameters](#parameters-1) + * [Examples](#examples-4) + * [patch](#patch) + * [Parameters](#parameters-2) + * [Examples](#examples-5) + * [post](#post) + * [Parameters](#parameters-3) + * [Examples](#examples-6) + * [delete](#delete) + * [Parameters](#parameters-4) + * [Examples](#examples-7) + * [self](#self) + * [Parameters](#parameters-5) + * [Examples](#examples-8) + * [request](#request) + * [Parameters](#parameters-6) + * [Examples](#examples-9) ### Kitsu -[packages/kitsu/src/index.js:30-523](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu/src/index.js#L30-L523 "Source code on GitHub") +[packages/kitsu/src/index.js:30-523](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/packages/kitsu/src/index.js#L30-L523 "Source code on GitHub") Creates a new `kitsu` instance #### Parameters -- `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Options (optional, default `{}`) +* `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Options (optional, default `{}`) - - `options.baseURL` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Set the API endpoint (optional, default `https://kitsu.io/api/edge`) - - `options.headers` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional headers to send with the requests - - `options.camelCaseTypes` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** If enabled, `type` will be converted to camelCase from kebab-casae or snake_case (optional, default `true`) - - `options.resourceCase` **(`"kebab"` | `"snake"` | `"none"`)** Case to convert camelCase to. `kebab` - `/library-entries`; `snake` - /library_entries`; `none`-`/libraryEntries\` (optional, default `kebab`) - - `options.pluralize` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** If enabled, `/user` will become `/users` in the URL request and `type` will be pluralized in POST, PATCH and DELETE requests (optional, default `true`) - - `options.timeout` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** Set the request timeout in milliseconds (optional, default `30000`) - - `options.axiosOptions` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional options for the axios instance (see [axios/axios#request-config](https://github.com/axios/axios#request-config) for details) + * `options.baseURL` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Set the API endpoint (optional, default `https://kitsu.io/api/edge`) + * `options.headers` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional headers to send with the requests + * `options.camelCaseTypes` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** If enabled, `type` will be converted to camelCase from kebab-casae or snake_case (optional, default `true`) + * `options.resourceCase` **(`"kebab"` | `"snake"` | `"none"`)** Case to convert camelCase to. `kebab` - `/library-entries`; `snake` - /library_entries` ; `none`-`/libraryEntries\` (optional, default `kebab`) + * `options.pluralize` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** If enabled, `/user` will become `/users` in the URL request and `type` will be pluralized in POST, PATCH and DELETE requests (optional, default `true`) + * `options.timeout` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** Set the request timeout in milliseconds (optional, default `30000`) + * `options.axiosOptions` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional options for the axios instance (see [axios/axios#request-config](https://github.com/axios/axios#request-config) for details) #### Examples Using with Kitsu.io's API ```javascript -const api = new Kitsu(); +const api = new Kitsu() ``` Using another API server ```javascript const api = new Kitsu({ - baseURL: "https://api.example.org/2", -}); + baseURL: 'https://api.example.org/2' +}) ``` Setting headers @@ -271,18 +279,18 @@ Setting headers ```javascript const api = new Kitsu({ headers: { - "User-Agent": "MyApp/1.0.0 (github.com/username/repo)", - Authorization: "Bearer 1234567890", - }, -}); + 'User-Agent': 'MyApp/1.0.0 (github.com/username/repo)', + Authorization: 'Bearer 1234567890' + } +}) ``` #### plural -[packages/kitsu/src/index.js:52-53](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu/src/index.js#L52-L53 "Source code on GitHub") +[packages/kitsu/src/index.js:52-53](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/packages/kitsu/src/index.js#L52-L53 "Source code on GitHub") -- **See**: for documentation -- **See**: [Kitsu](#kitsu) constructor options for disabling pluralization +* **See**: for documentation +* **See**: [Kitsu](#kitsu) constructor options for disabling pluralization If pluralization is enabled (default, see Kitsu constructor docs) then pluralization rules can be added @@ -291,14 +299,14 @@ If pluralization is enabled (default, see Kitsu constructor docs) then pluraliza Adding an uncountable pluralization rule ```javascript -api.plural.plural("paper"); //=> 'papers' -api.plural.addUncountableRule("paper"); -api.plural.plural("paper"); //=> 'paper' +api.plural.plural('paper') //=> 'papers' +api.plural.addUncountableRule('paper') +api.plural.plural('paper') //=> 'paper' ``` #### headers -[packages/kitsu/src/index.js:67-67](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu/src/index.js#L67-L67 "Source code on GitHub") +[packages/kitsu/src/index.js:67-67](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/packages/kitsu/src/index.js#L67-L67 "Source code on GitHub") Get the current headers or add additional headers @@ -307,28 +315,28 @@ Get the current headers or add additional headers Get all headers ```javascript -api.headers; +api.headers ``` Get a single header's value ```javascript -api.headers["User-Agent"]; +api.headers['User-Agent'] ``` Add or update a header's value ```javascript -api.headers["Authorization"] = "Bearer 1234567890"; +api.headers['Authorization'] = 'Bearer 1234567890' ``` Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** All the current headers #### interceptors -[packages/kitsu/src/index.js:113-113](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu/src/index.js#L113-L113 "Source code on GitHub") +[packages/kitsu/src/index.js:113-113](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/packages/kitsu/src/index.js#L113-L113 "Source code on GitHub") -- **See**: for documentation +* **See**: for documentation Axios Interceptors (alias of `axios.interceptors`) @@ -340,34 +348,28 @@ Request Interceptor ```javascript // Add a request interceptor -api.interceptors.request.use( - (config) => { - // Do something before request is sent - return config; - }, - (error) => { - // Do something with the request error - return Promise.reject(error); - } -); +api.interceptors.request.use(config => { + // Do something before request is sent + return config +}, error => { + // Do something with the request error + return Promise.reject(error) +}) ``` Response Interceptor ```javascript // Add a response interceptor -api.interceptors.response.use( - (response) => { - // Any status code that lie within the range of 2xx cause this function to trigger - // Do something with response data - return response; - }, - (error) => { - // Any status codes that falls outside the range of 2xx cause this function to trigger - // Do something with response error - return Promise.reject(error); - } -); +api.interceptors.response.use(response => { + // Any status code that lie within the range of 2xx cause this function to trigger + // Do something with response data + return response +}, error => { + // Any status codes that falls outside the range of 2xx cause this function to trigger + // Do something with response error + return Promise.reject(error) +}) ``` Removing Interceptors @@ -379,85 +381,84 @@ api.interceptors.request.eject(myInterceptor) #### get -[packages/kitsu/src/index.js:211-240](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu/src/index.js#L211-L240 "Source code on GitHub") +[packages/kitsu/src/index.js:211-240](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/packages/kitsu/src/index.js#L211-L240 "Source code on GitHub") Fetch resources (alias `fetch`) ##### Parameters -- `model` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Resource to fetch data from. Expected formats are [`:resource`](https://jsonapi.org/format/#document-resource-objects), [`:resource/:id`](https://jsonapi.org/format/#document-resource-objects), [`:resource/:id/:relationship`](https://jsonapi.org/format/#document-resource-object-relationships) or [`:resource/:id/relationships/:relationship`](https://jsonapi.org/format/#document-resource-object-linkage) -- `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional configuration (optional, default `{}`) +* `model` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Resource to fetch data from. Expected formats are [`:resource`](https://jsonapi.org/format/#document-resource-objects), [`:resource/:id`](https://jsonapi.org/format/#document-resource-objects), [`:resource/:id/:relationship`](https://jsonapi.org/format/#document-resource-object-relationships) or [`:resource/:id/relationships/:relationship`](https://jsonapi.org/format/#document-resource-object-linkage) +* `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional configuration (optional, default `{}`) - - `config.headers` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional headers to send with the request - - `config.params` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** JSON:API request queries. JSON:API query parameters not listed are supported + * `config.headers` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional headers to send with the request + * `config.params` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** JSON:API request queries. JSON:API query parameters not listed are supported - - `config.params.fields` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Return a sparse fieldset with only the included attributes/relationships - [JSON:API Sparse Fieldsets](http://jsonapi.org/format/#fetching-sparse-fieldsets) - - `config.params.filter` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Filter dataset by attribute values - [JSON:API Filtering](http://jsonapi.org/format/#fetching-filtering) - - `config.params.include` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Include relationship data - [JSON:API Includes](http://jsonapi.org/format/#fetching-includes) - - `config.params.sort` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Sort dataset by one or more comma separated attributes (prepend `-` for descending order) - [JSON:API Sorting](http://jsonapi.org/format/#fetching-sorting) - - `config.params.page` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** [JSON:API Pagination](http://jsonapi.org/format/#fetching-pagination). All pagination strategies are supported, even if they are not listed below. + * `config.params.fields` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Return a sparse fieldset with only the included attributes/relationships - [JSON:API Sparse Fieldsets](http://jsonapi.org/format/#fetching-sparse-fieldsets) + * `config.params.filter` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Filter dataset by attribute values - [JSON:API Filtering](http://jsonapi.org/format/#fetching-filtering) + * `config.params.include` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Include relationship data - [JSON:API Includes](http://jsonapi.org/format/#fetching-includes) + * `config.params.sort` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Sort dataset by one or more comma separated attributes (prepend `-` for descending order) - [JSON:API Sorting](http://jsonapi.org/format/#fetching-sorting) + * `config.params.page` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** [JSON:API Pagination](http://jsonapi.org/format/#fetching-pagination). All pagination strategies are supported, even if they are not listed below. - - `config.params.page.limit` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Number of resources to return in request (Offset-based) - **Note:** For Kitsu.io, max is `20` except on `libraryEntries` which has a max of `500` - - `config.params.page.offset` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Number of resources to offset the dataset by (Offset-based) - - `config.params.page.number` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Page of resources to return in request (Page-based) - **Note:** Not supported on Kitsu.io - - `config.params.page.size` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Number of resources to return in request (Page-based and cursor-based) - **Note:** Not supported on Kitsu.io - - `config.params.page.before` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Get the previous page of resources (Cursor-based) - **Note:** Not Supported on Kitsu.io - - `config.params.page.after` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Get the next page of resources (Cursor-based) - **Note:** Not Supported on Kitsu.io - - - `config.axiosOptions` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional options for the axios instance (see [axios/axios#request-config](https://github.com/axios/axios#request-config) for details) + * `config.params.page.limit` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Number of resources to return in request (Offset-based) - **Note:** For Kitsu.io, max is `20` except on `libraryEntries` which has a max of `500` + * `config.params.page.offset` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Number of resources to offset the dataset by (Offset-based) + * `config.params.page.number` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Page of resources to return in request (Page-based) - **Note:** Not supported on Kitsu.io + * `config.params.page.size` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Number of resources to return in request (Page-based and cursor-based) - **Note:** Not supported on Kitsu.io + * `config.params.page.before` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Get the previous page of resources (Cursor-based) - **Note:** Not Supported on Kitsu.io + * `config.params.page.after` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Get the next page of resources (Cursor-based) - **Note:** Not Supported on Kitsu.io + * `config.axiosOptions` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional options for the axios instance (see [axios/axios#request-config](https://github.com/axios/axios#request-config) for details) ##### Examples Getting a resource with JSON:API parameters ```javascript -api.get("users", { +api.get('users', { params: { fields: { - users: "name,birthday", + users: 'name,birthday' }, filter: { - name: "wopian", - }, - }, -}); + name: 'wopian' + } + } +}) ``` Getting a collection of resources with their relationships ```javascript -api.get("anime", { +api.get('anime', { params: { - include: "categories", - }, -}); + include: 'categories' + } +}) ``` Getting a single resource by ID (method one) ```javascript -api.get("anime/2", { +api.get('anime/2', { params: { - include: "categories", - }, -}); + include: 'categories' + } +}) ``` Getting a single resource by ID (method two) ```javascript -api.get("anime", { +api.get('anime', { params: { - include: "categories", - filter: { id: "2" }, - }, -}); + include: 'categories', + filter: { id: '2' } + } +}) ``` Getting a resource's relationship data only ```javascript -api.get("anime/2/categories"); +api.get('anime/2/categories') ``` Getting a resource with nested JSON:API filters (not supported by Kitsu.io's API) @@ -517,142 +518,145 @@ Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G #### patch -[packages/kitsu/src/index.js:276-304](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu/src/index.js#L276-L304 "Source code on GitHub") +[packages/kitsu/src/index.js:276-304](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/packages/kitsu/src/index.js#L276-L304 "Source code on GitHub") Update a resource (alias `update`) ##### Parameters -- `model` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Resource to update data in. Expected formats are [`:resource`](https://jsonapi.org/format/#document-resource-objects), [`:resource/:id`](https://jsonapi.org/format/#document-resource-objects), [`:resource/:id/:relationship`](https://jsonapi.org/format/#document-resource-object-relationships) or [`:resource/:id/relationships/:relationship`](https://jsonapi.org/format/#document-resource-object-linkage) -- `body` **([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)>)** Data to send in the request -- `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional configuration (optional, default `{}`) +* `model` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Resource to update data in. Expected formats are [`:resource`](https://jsonapi.org/format/#document-resource-objects), [`:resource/:id`](https://jsonapi.org/format/#document-resource-objects), [`:resource/:id/:relationship`](https://jsonapi.org/format/#document-resource-object-relationships) or [`:resource/:id/relationships/:relationship`](https://jsonapi.org/format/#document-resource-object-linkage) +* `body` **([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)>)** Data to send in the request +* `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional configuration (optional, default `{}`) - - `config.params` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** JSON:API request queries. See [#get](#get) for documentation - - `config.headers` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional headers to send with the request - - `config.axiosOptions` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional options for the axios instance (see [axios/axios#request-config](https://github.com/axios/axios#request-config) for details) + * `config.params` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** JSON:API request queries. See [#get](#get) for documentation + * `config.headers` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional headers to send with the request + * `config.axiosOptions` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional options for the axios instance (see [axios/axios#request-config](https://github.com/axios/axios#request-config) for details) ##### Examples Update a resource ```javascript -api.update("posts", { - id: "1", - content: "Goodbye World", -}); +api.update('posts', { + id: '1', + content: 'Goodbye World' +}) ``` Update a resource with relationships ```javascript -api.update("posts", { - content: "Hello World", +api.update('posts', { + content: 'Hello World', uploads: { - id: "167585", - type: "uploads", - }, -}); + id: '167585', + type: 'uploads' + } +}) ``` Clear to-one relationships from a resource ```javascript -api.update("posts/1/relationships/uploads", null); +api.update('posts/1/relationships/uploads', null) ``` Clear to-many relationships from a resource ```javascript -api.update("posts/1/relationships/uploads", []); +api.update('posts/1/relationships/uploads', []) ``` Update multiple resources (API must support the Bulk Extension) ```javascript -api.update("posts", [ - { id: "1", content: "Hello World" }, - { id: "2", content: "Another post" }, -]); +api.update('posts', [ + { id: '1', content: 'Hello World' }, + { id: '2', content: 'Another post' } +]) ``` 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)>)** JSON-parsed response #### post -[packages/kitsu/src/index.js:334-360](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu/src/index.js#L334-L360 "Source code on GitHub") +[packages/kitsu/src/index.js:334-360](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/packages/kitsu/src/index.js#L334-L360 "Source code on GitHub") Create a new resource (alias `create`) ##### Parameters -- `model` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Resource to create. Expected formats are [`:resource`](https://jsonapi.org/format/#document-resource-objects), [`:resource/:id`](https://jsonapi.org/format/#document-resource-objects), [`:resource/:id/:relationship`](https://jsonapi.org/format/#document-resource-object-relationships) or [`:resource/:id/relationships/:relationship`](https://jsonapi.org/format/#document-resource-object-linkage) -- `body` **([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)>)** Data to send in the request -- `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional configuration (optional, default `{}`) +* `model` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Resource to create. Expected formats are [`:resource`](https://jsonapi.org/format/#document-resource-objects), [`:resource/:id`](https://jsonapi.org/format/#document-resource-objects), [`:resource/:id/:relationship`](https://jsonapi.org/format/#document-resource-object-relationships) or [`:resource/:id/relationships/:relationship`](https://jsonapi.org/format/#document-resource-object-linkage) +* `body` **([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)>)** Data to send in the request +* `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional configuration (optional, default `{}`) - - `config.params` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** JSON:API request queries. See [#get](#get) for documentation - - `config.headers` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional headers to send with the request + * `config.params` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** JSON:API request queries. See [#get](#get) for documentation + * `config.headers` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional headers to send with the request ##### Examples Create a post on a user's profile feed ```javascript -api.create("posts", { - content: "Hello World", +api.create('posts', { + content: 'Hello World', targetUser: { - id: "42603", - type: "users", + id: '42603', + type: 'users' }, user: { - id: "42603", - type: "users", - }, -}); + id: '42603', + type: 'users' + } +}) ``` Create multiple resources (API must support the Bulk Extension) ```javascript -api.create("posts", [{ content: "Hello World" }, { content: "Another post" }]); +api.create('posts', [ + { content: 'Hello World' }, + { content: 'Another post' } +]) ``` 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)>)** JSON-parsed response #### delete -[packages/kitsu/src/index.js:378-412](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu/src/index.js#L378-L412 "Source code on GitHub") +[packages/kitsu/src/index.js:378-412](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/packages/kitsu/src/index.js#L378-L412 "Source code on GitHub") Remove a resource (alias `remove`) ##### Parameters -- `model` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Resource to remove. Expected formats are [`:resource`](https://jsonapi.org/format/#document-resource-objects), [`:resource/:id/:relationship`](https://jsonapi.org/format/#document-resource-object-relationships) or [`:resource/:id/relationships/:relationship`](https://jsonapi.org/format/#document-resource-object-linkage) -- `id` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)>)** Resource ID to remove. Pass an array of IDs to delete multiple resources (Bulk Extension) -- `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional configuration (optional, default `{}`) +* `model` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Resource to remove. Expected formats are [`:resource`](https://jsonapi.org/format/#document-resource-objects), [`:resource/:id/:relationship`](https://jsonapi.org/format/#document-resource-object-relationships) or [`:resource/:id/relationships/:relationship`](https://jsonapi.org/format/#document-resource-object-linkage) +* `id` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)>)** Resource ID to remove. Pass an array of IDs to delete multiple resources (Bulk Extension) +* `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional configuration (optional, default `{}`) - - `config.params` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** JSON:API request queries. See [#get](#get) for documentation - - `config.headers` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional headers to send with the request - - `config.axiosOptions` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional options for the axios instance (see [axios/axios#request-config](https://github.com/axios/axios#request-config) for details) + * `config.params` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** JSON:API request queries. See [#get](#get) for documentation + * `config.headers` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional headers to send with the request + * `config.axiosOptions` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional options for the axios instance (see [axios/axios#request-config](https://github.com/axios/axios#request-config) for details) ##### Examples Remove a single resource ```javascript -api.delete("posts", 123); +api.delete('posts', 123) ``` Remove multiple resources (API must support the Bulk Extension) ```javascript -api.delete("posts", [1, 2]); +api.delete('posts', [ 1, 2 ]) ``` 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)>)** JSON-parsed response #### self -[packages/kitsu/src/index.js:436-445](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu/src/index.js#L436-L445 "Source code on GitHub") +[packages/kitsu/src/index.js:436-445](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/packages/kitsu/src/index.js#L436-L445 "Source code on GitHub") Get the authenticated user's data @@ -660,18 +664,18 @@ Get the authenticated user's data ##### Parameters -- `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional configuration (optional, default `{}`) +* `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional configuration (optional, default `{}`) - - `config.params` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** JSON:API request queries. See [#get](#get) for documentation - - `config.headers` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional headers to send with the request - - `config.axiosOptions` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional options for the axios instance (see [axios/axios#request-config](https://github.com/axios/axios#request-config) for details) + * `config.params` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** JSON:API request queries. See [#get](#get) for documentation + * `config.headers` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional headers to send with the request + * `config.axiosOptions` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional options for the axios instance (see [axios/axios#request-config](https://github.com/axios/axios#request-config) for details) ##### Examples Get the authenticated user's resource ```javascript -api.self(); +api.self() ``` Using JSON:API parameters @@ -680,17 +684,17 @@ Using JSON:API parameters api.self({ params: { fields: { - users: "name,birthday", - }, - }, -}); + users: 'name,birthday' + } + } +}) ``` Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** JSON-parsed response #### request -[packages/kitsu/src/index.js:500-522](https://github.com/wopian/kitsu/blob/9bda3199ca205b32c1f6926ba9b27f87cdfab125/packages/kitsu/src/index.js#L500-L522 "Source code on GitHub") +[packages/kitsu/src/index.js:500-522](https://github.com/wopian/kitsu/blob/a130f763dbc5b721b289d7ec27d780c1dacdb28e/packages/kitsu/src/index.js#L500-L522 "Source code on GitHub") Send arbitrary requests @@ -698,15 +702,15 @@ Send arbitrary requests ##### Parameters -- `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Request configuration +* `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Request configuration - - `config.body` **([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)>)?** Data to send in the request - - `config.method` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Request method - `GET`, `PATCH`, `POST` or `DELETE` (defaults to `GET`, case-insensitive) - - `config.params` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** JSON:API request queries. See [#get](#get) for documentation - - `config.type` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The resource type - - `config.url` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The URL path of the resource - - `config.headers` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional headers to send with the request - - `config.axiosOptions` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional options for the axios instance (see [axios/axios#request-config](https://github.com/axios/axios#request-config) for details) + * `config.body` **([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)>)?** Data to send in the request + * `config.method` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Request method - `GET`, `PATCH`, `POST` or `DELETE` (defaults to `GET`, case-insensitive) + * `config.params` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** JSON:API request queries. See [#get](#get) for documentation + * `config.type` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The resource type + * `config.url` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The URL path of the resource + * `config.headers` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional headers to send with the request + * `config.axiosOptions` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Additional options for the axios instance (see [axios/axios#request-config](https://github.com/axios/axios#request-config) for details) ##### Examples @@ -714,43 +718,43 @@ Raw GET request ```javascript api.request({ - url: "anime/1/mappings", - type: "mappings", - params: { filter: { externalSite: "aozora" } }, -}); + url: 'anime/1/mappings', + type: 'mappings', + params: { filter: { externalSite: 'aozora' } } +}) ``` Raw PATCH request ```javascript api.request({ - method: "PATCH", - url: "anime", - type: "anime", - body: { id: "1", subtype: "tv" }, -}); + method: 'PATCH', + url: 'anime', + type: 'anime', + body: { id: '1', subtype: 'tv' } +}) ``` Raw POST request ```javascript api.request({ - method: "PATCH", - url: "anime", - type: "anime", - body: { subtype: "tv" }, -}); + method: 'PATCH', + url: 'anime', + type: 'anime', + body: { subtype: 'tv' } +}) ``` Raw DELETE request ```javascript api.request({ - method: "DELETE", - url: "anime/1", - type: "anime", - body: { id: "1" }, -}); + method: 'DELETE', + url: 'anime/1', + type: 'anime', + body: { id: '1' } +}) ``` Bulk Extension support (`PATCH`, `POST` & `DELETE`)