Discovered thanks to an email by a user, which I'm surprised I didn't discover the mistake sooner.

Note: Examples below use post as the parent resource and comment as the relationship resource

GET

Related spec: https://jsonapi.org/format/#fetching-relationships

GET has a different error compared to POST/PATCH/DELETE as it handles self relationship requests (get id/type/attributes/relationships) post/1/comment, but not related relationship requests (get id/type) as its implementation only uses the first 3 strings separated by /, making the request URI correct to post/1 but the type is relationships instead of comment.

Potential refactoring for this method would be to store the 4th item and check if the 4th item exists and the 3rd item is "relationships" to turn api.fetch('post/1/relationships/comment') into GET https://example.api/posts/1/relationships/comments.

POST

Related spec: https://jsonapi.org/format/#crud-updating-to-many-relationships

Currently with api.create('post/1/comment', '...') it will attempt to create a resource with the type posts/1/comments. Correct behaviour is per the spec:

In the following example, the comment with ID 123 is added to the list of comments for the article with ID 1:

POST /articles/1/relationships/comments HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": [
    { "type": "comments", "id": "123" }
  ]
}

PATCH

Related spec: https://jsonapi.org/format/#crud-updating-to-one-relationships and https://jsonapi.org/format/#crud-updating-to-many-relationships

Same as POST but can also remove relationships with data: null on one-to-one relationships and data: [] on one-to-many relationships.

DELETE

Related spec: https://jsonapi.org/format/#crud-updating-to-many-relationships

Same as POST, but deleting instead of adding relationships 😉

In the following example, comments with IDs of 12 and 13 are removed from the list of comments for the article with ID 1:

DELETE /articles/1/relationships/comments HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": [
    { "type": "comments", "id": "12" },
    { "type": "comments", "id": "13" }
  ]
}

Unable to serialise data using kitsu-core as a standalone - tests did not pick this up as they're pre-bound in the specs for each bind combination.

Should fallback to requiring pluralize if this.plural is not a function

Ref: https://codepen.io/wopian/pen/KQZwzq (console)

Is there any chance to update axios dependency to the latest version? axios/axios@960e1c8

Is it possible to get the season and its year of a particular anime from the API? I see everything but the season.

Hello,
So I've noticed when I search up a particular anime like "100% Pascal-sensei" on kitsu.io, it returns the two version (1 TV and 1 OVA)
but if I go to https://kitsu.io/api/edge/anime?filter[text]=100%20Pascal-sensei, it gives a huge chunk of anime that are related and none related. Is there a way to narrow down to how the main page search does it?

Thanks!

It looks like the only place the relations are used in the GET request. Any way to send a POST|PATCH request while including a relationship?

kitsu currently throws an error if POST/PATCH/DELETE requests are attempted without the Authorization header being set.

This poses an issue in 2 places:

• APIs using non-standard headers for their authentication system (e.g. X-Something)
• APIs that allow guest usage (e.g comments) where authentication is not needed to send POST requests.

In both cases, if an unauthenticated request is to an endpoint that requires authentication, the JSON:API API returns its own (403) error in the expected JSON:API error format.

• camel
• deattribute
• deserialise
• error
• filterIncludes
• kebab
• linkRelationships
• query
• serialise
• snake

request: /example/id?include=something
plain response:

    "included": [
        {
            "id": "...",
            "type": "...",
            "attributes": {attributes: {}, ...} // (!) is also named as "attributes"
        }
    ]

Problem: obj.something.attributes is missing. Renaming attributes to props helps. Something eats the attributes property.

6.4.0 added auto generated declaration files with any type for the exported functions' arguments. Ideally this should be fully typed with the expected types from the JSDoc comments.

Once this is complete, IDEs (such as Visual Studio Code's Intellisense) will be able to provide the structure and documentation to developers as they use this library in their own code.

What needs doing

As this is not (and won't be) a TypeScript project, these will have to be manually modified. The generated declarations were made with dts-gen and has correctly listed the two package's structure with their public functions.

These need:

• The function's argument names and types added instead of the ...args: any[] placeholder.
  • ℹ️ Do's & Don'ts for typings.
  • ⚠️ Arguments that accept multiple types should have the any type
• The function's return type
  • ⚠️ If the JSDoc does not specify the return type but does use the return keyword in the code, keep it as any.

The documentation for each package is in the same file the function is declared in, so searching for the function name will give you the required documentation.

TypeScript Declarations

• packages/kitsu/index.d.ts
• packages/kitsu-core/index.d.ts

Useful Resources

https://blogs.msdn.microsoft.com/typescript/2016/12/14/writing-dts-files-for-types/
https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html
http://definitelytyped.org/guides.html

The library currently sees any object in attributes as a relationship, however, based on the JSONAPI spec, objects and arrays are allowed as attribute values.

here is a demo of the issue codesandbox

how could I write this code with Kitsu?

filter[lte][postingDate]=endDate

• Turn repo into a lerna repo
• Create kitsu-core
• Copy private util functions in kitsu to kitsu-core
• Require kitsu-core in kitsu
• Import kitsu-core functions
• Setup rollup configs
• Setup changelog generation

I am wondering how can I patch multiple objects? In what format should I pass modified data?

Function serialise has a Cognitive Complexity of 34 (exceeds 6 allowed). Consider refactoring.

https://codeclimate.com/github/wopian/kitsu/src/util/serialise/index.js#issue_5a6c1706938b34000100003a

Using this piece of code

const Kitsu = require('kitsu');
const kitsu = new Kitsu();
const { data } = await kitsu.fetch('anime', { filter: { name: "Attack On Titan"} });

(used inside an async function) throws following error

senpai_1    | [2018-03-08 12:27:30] [0] TypeError [ERR_UNESCAPED_CHARACTERS]: Request path contains unescaped characters
senpai_1    | [2018-03-08 12:27:30] [0]     at new ClientRequest (_http_client.js:127:13)
senpai_1    | [2018-03-08 12:27:30] [0]     at Object.request (https.js:275:10)
senpai_1    | [2018-03-08 12:27:30] [0]     at RedirectableRequest._performRequest (/usr/src/Senpai/node_modules/follow-redirects/index.js:128:24)
senpai_1    | [2018-03-08 12:27:30] [0]     at new RedirectableRequest (/usr/src/Senpai/node_modules/follow-redirects/index.js:54:8)
senpai_1    | [2018-03-08 12:27:30] [0]     at Object.wrappedProtocol.request (/usr/src/Senpai/node_modules/follow-redirects/index.js:252:14)
senpai_1    | [2018-03-08 12:27:30] [0]     at dispatchHttpRequest (/usr/src/Senpai/node_modules/axios/lib/adapters/http.js:141:25)
senpai_1    | [2018-03-08 12:27:30] [0]     at new Promise (<anonymous>)
senpai_1    | [2018-03-08 12:27:30] [0]     at httpAdapter (/usr/src/Senpai/node_modules/axios/lib/adapters/http.js:18:10)
senpai_1    | [2018-03-08 12:27:30] [0]     at dispatchRequest (/usr/src/Senpai/node_modules/axios/lib/core/dispatchRequest.js:59:10)
senpai_1    | [2018-03-08 12:27:30] [0]     at <anonymous>

and im pretty sure that this piece of code is correct 🤔 would appreciate some information how i would go about fixing this issue

After switching one project to webpack4 I got error messages from the compiler (kitsu / kitsu-core). I tried to fix problems myself but on every new instalation the problem will remain. Thanx

Failed to compile with 13 errors                                                                        13:32:11

 error  in ./node_modules/kitsu/lib/index.mjs

102:122-131 Can't import the named export 'serialise' from non EcmaScript module (only default export is available)

 error  in ./node_modules/kitsu/lib/index.mjs

110:69-74 Can't import the named export 'error' from non EcmaScript module (only default export is available)

 error  in ./node_modules/kitsu/lib/index.mjs

131:132-141 Can't import the named export 'serialise' from non EcmaScript module (only default export is available)

 error  in ./node_modules/kitsu/lib/index.mjs

142:69-74 Can't import the named export 'error' from non EcmaScript module (only default export is available)

 error  in ./node_modules/kitsu/lib/index.mjs

172:68-73 Can't import the named export 'error' from non EcmaScript module (only default export is available)

 error  in ./node_modules/kitsu/lib/index.mjs

21:12-17 Can't import the named export 'camel' from non EcmaScript module (only default export is available)

 error  in ./node_modules/kitsu/lib/index.mjs

23:41-46 Can't import the named export 'snake' from non EcmaScript module (only default export is available)

 error  in ./node_modules/kitsu/lib/index.mjs

23:49-54 Can't import the named export 'kebab' from non EcmaScript module (only default export is available)

 error  in ./node_modules/kitsu/lib/index.mjs

45:43-48 Can't import the named export 'query' from non EcmaScript module (only default export is available)

 error  in ./node_modules/kitsu/lib/index.mjs

50:78-89 Can't import the named export 'deserialise' from non EcmaScript module (only default export is available)

 error  in ./node_modules/kitsu/lib/index.mjs

52:69-74 Can't import the named export 'error' from non EcmaScript module (only default export is available)

 error  in ./node_modules/kitsu/lib/index.mjs

73:59-68 Can't import the named export 'serialise' from non EcmaScript module (only default export is available)

 error  in ./node_modules/kitsu/lib/index.mjs

81:69-74 Can't import the named export 'error' from non EcmaScript module (only default export is available)

It seems like kitsu omits my cookies (session) data. Why?

Changes are broken down by package (kitsu and kitsu-core)

kitsu

What

1. Change the first parameter behaviour of api.get, api.patch, api.post and api.delete to be a plain URL path. E.g.

   • api.get(anime/1/relationships/episodes)
   • api.patch(users/1/password, body) where the type may not be passwords

2. Remove the second parameter of api.delete

   • api.delete('posts', 1) is redundant when you can do api.delete('posts/1')

3. Second parameter (deserialised JSON:API) of api.patch and api.post would now require the type to be defined

   • Current:
     • api.post('post', { content: 'some content' }
     • api.patch('post', { id: '1', content: 'some content' }
   • Proposed:
     • api.post('posts', { type: 'posts', content: 'some content' }
     • api.patch('posts', { id: '1', type: 'posts', content: 'some content' }

4. Drop dependency on pluralize

Why

• (1/2) Allows custom URLs for JSON:API resources without creating custom requests (#414)

• (4) Significantly reduces kitsu bundle size by 30% - pluralize is 2.3 kB of kitsu's 8.2 kB.

• (1/3/4) Pluralisation leads to ambiguity of what the real value of type in the API actually is (especially when it is not simple rules like post -> posts)

  • Proposed behaviour would be WYSIWYG (What You See Is What You Get)

• (1/3/4) Pluralisation can get in the way of the correct value of type in some API endpoints, but not all endpoints.

  • Which results in consumers either disabling pluralisation entirely or setting pluralisation rules to mitigate the one wrong type

Pain points

• This would break SOME GET, PATCH, POST and DELETE requests that relied on pluralisation to request the API resource

• This would break ALL PATCH, POST requests as the data sent to the API will now be lacking the type without changes to consumer code

• This would break ALL DELETE requests as the 2nd argument is removed, making the 3rd argument for additional headers the 2nd argument

kitsu-core

What

1. Remove the first parameter of serialise (model / the root resources' type)

   • The second parameter (obj / the deserialised JSON:API input) now requires the type to be defined. E.g:
     • Current: serialise('posts', { id: '1', content: 'some content' }
     • Proposed: serialise({ id: '1', type: 'posts', content: 'some content' }

2. Remove pluralTypes and camelCaseTypes options added in 9.x as with (1.) the type will already be in the resource object and should be correctly formatted already

   • For upgrades from 8.x and older it would be serialise.apply({ camel, resCase: kebab, plural }, [ model, obj ]) to serialise(obj) (with model now obj.type)
   • Instead of being extracted from the model string in the Kitsu class and passed down, where pluralisation mismatch and kebab/snakecase could be present, which necessitated these options`

Why

• (1/2) It is only used once to set the type of a new object (along with pluralisation and camelCase conversion)

• (1) With the logic removed from the get, patch and post methods from the Kitsu class this doesn't really make much sense to keep type separate here still

• (1) With the proposed behaviour it would match the existing behaviour of adding the id to the new data object - extracting it from the second parameter (obj)

  • serialise will need to throw an error if type is missing
    • Only when obj is NOT null or [] (syntax to delete relationships)
    • In current behaviour it is guaranteed to have a type set

Pain points

• This would break ALL uses of serialise as the first argument is dropped, making the input object (deserialised JSON:API) the first argument.

The following block is unnecessary as the Kitsu class declaration has already been declared above that.

And therefore, the following line gives a TS2300 error:

I'm getting this error while initializing with the following:

const Kitsu = require('kitsu');

const api = new Kitsu({
  baseURL: "http://localhost:3000/api/v1"
});

The serializer is throwing error TypeError: Cannot read property 'constructor' of undefined if one of the fields is undefined. I looked at the code and it seems that it only checks if it is not null.

Function serialiseObject has 5 arguments (exceeds 4 allowed). Consider refactoring.

https://codeclimate.com/github/wopian/kitsu/packages/kitsu-core/src/serialise/index.js#issue_5b73904103ff7d000100003e

It is OK to have a POST request without a body. I am not sure why it is restricted here..

Avoid deeply nested control flow statements.

https://codeclimate.com/github/wopian/kitsu/src/util/serialise/index.js#issue_5a6c1706938b34000100003c

Is it possible to filter like this :

?filter[myfilter][condition][path]=field_page.name&filter[myfilter][condition][value]=home

I tried several objects and arrays in filter but had no chance

The following aliases currently exist:

• get -> fetch
• post -> create
• patch -> update

Would it be possible to also have:

• delete -> remove

To match the HTTP methods/JSONAPI spec methods?

Hi, love your work on the project

I was reading through the source code is there any reason for async/await on all the methods provided?

It seems irrelevant since all methods can just be run right away?

Best regards
Simon

I'd like to capture http status code.

At the least, 4xx and 5xx return codes should throw an error...

All is fine if i make such a request:

this.api.get('printers', {
      include: 'paper',
    })

This works as well:

this.api.get('printers', {
      include: 'labels',
    })

And this returns 400 Bad Request:

this.api.get('printers', {
      include: 'labels,nonexistinginclude',
    })

But this causes to client to freeze, the Browsertab becomes unresponsive and i have to close it:

this.api.get('printers', {
      include: 'paper,labels',
    })

I tried sending the request from elsewhere, no problem whatsoever. Maybe Kitsu can not deal with multiple includes?

I just upgraded from 3.1.4 to 4.1.0.

Here's how I initialize kitsu:

<script>
const Kitsu = require('kitsu');

const api = new Kitsu({
    baseURL: '{{config['PREFERRED_URL_SCHEME']}}://{{config['SERVER_NAME']}}/api',
//    headers: {
//        Authorization: 'foobar'
//    }
});
api.headers['Authorization'] = 'foobar';

And here's how I make a request:

        api.update('containers', {
            id: container_id,
            status: container_action
        }).then(function(res) {
            console.log(res);
        })
            .catch((reason) => console.log(reason));

My requests should be sent with application/vnd.api+json Content-Type, but they aren't, no matter what I do it is sent with application/json;charset=utf-8 which happens to be the Axios default.

So I suspect that something broke between 3.x and 4.x that causes Axios to no longer set / see the correct Content-Type.

Here is the libs I am using:

├─ [email protected]
│  ├─ axios@^0.17.0
│  ├─ babel-runtime@^6.26.0
│  └─ pluralize@^7.0.0

Thanks for a great library!

It would be awesome if we could disable pluralization and decamelize when requesting resources. I'm using the library on my own API, but unfortunately one of those functions is breaking my ids (MongoID) in the request.

I'd like to filter Library entries of a user to get a list of his completed TV (anime.showType) anime x)
As of now I'm not filtering on showType.

https://stackoverflow.com/questions/40204854/json-api-filter-included-resources

In fact I want a random completed TV anime of a user library entries x). I'm currently doing that through 3 requests right now :/
First to get user ID, second to get library entries number of completed animes of this user (found in meta), and third to get the said random anime (with page offset limit 1).

Is there a way to send a raw request? for ex I used to do something like this with https://github.com/twg/devour:

api.runMiddleware({
      url: api.apiUrl + '/users/' + id + '/password',
      method: 'PATCH',
      data,
      model: 'update-password-request'
})

It would be nice to have an option to modify the api (the instance or request) dynamically. The close examples are interceptor or middleware. The closest case is to add a global header for each request without modifying the get method or use the 3rd argument.

ie:

api.interceptors.push((request, next) => {
  request.headers.set('example', 'example');
  next();
});

Hi 👋

Not seeing an obvious change that caused this, but upgrading to 7.0.1 breaks my deserialise imports:

"export 'deserialise' was not found in 'kitsu-core'

In the course of #81 it came up that serialise doesn't validate data correctly: #81 (comment)

Do we need different validation logic for different methods (POST/PATCH/PUT?) or is it the same for all?

Hi, I'm trying to implement kitsu-core deserialise method in Axios interceptor, which works just fine, however, I'm having an issue with relationships. Say for example resource has more than one relationship, the base object should include all of them inside relationship objects with corresponding links to them which are used for client discovery (in my case at least). Example without include:

"relationships": {
  "author": {
    "links": {
      "self": "http://api.com/posts/1/relationships/authors",
      "related": "http://api.com/posts/1/authors"
    },
    "data": {}
  },
  "comments": {
    "links": {
      "self": "http://api.com/posts/1/relationships/comments",
      "related": "http://api.com/posts/1/comments"
    },
    "data": []
  },
}

And this works fine, as relationships are not being parsed, however, as soon as I include let's say author it will try to parse comments as well, and end up with "comments": { id: undefined, type: undefined } and there is no "relationships" object anymore, which is a problem for me, in case I wanna dynamically fetch the comments later on instead of including them on first request. What's more, it even tries to parse relationships of included resource, which are always going to resolve in an undefined type object like above

I use this package in my Create React App (CRA). I import it When I run npm run-script build I get the following error:

Creating an optimized production build...
Failed to compile.

Failed to minify the code from this file:

        ./node_modules/kitsu/lib/index.mjs:1:1379

Read more here: http://bit.ly/2tRViJ9

Not sure what causes it, but according to link provided in the error message it CRA fails to compile es6 files.

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Error type: Preset is invalid JSON (github>wopian/renovate-config)

Trying to post this with kitsu:

    container_users = container_users.map(x => ({
        id: x,
        type: 'users'
    }));

    api.create('container', {
        name: container_name,
        'creator': {
            'id': container_creator,
            'type': 'users'
        },
        'host': {
            'id': container_host,
            'type': 'hosts'
        },
        'users': container_users
    }).then(res => console.log(res)
    ).catch((reason) => console.log(reason));

results in this being POSTed:

{
  "data": {
    "type": "containers",
    "attributes": {
      "name": "testcontainer3",
      "users": [
        {
          "id": 1,
          "type": "users"
        },
        {
          "id": 2,
          "type": "users"
        }
      ]
    },
    "relationships": {
      "creator": {
        "data": {
          "id": 1,
          "type": "users"
        }
      },
      "host": {
        "data": {
          "id": 1,
          "type": "hosts"
        }
      }
    }
  },
  "headers": {
    "Authorization": "foobar",
    "accept": "application\/vnd.api+json",
    "content-type": "application\/vnd.api+json"
  }
}

it puts users into attributes instead of relationships, where it should go.

This is because the relationship test in serialise.js does not test for arrays.

I created and issue on camelcase and they said they aimed on node, so could you change camelcase for camel-case in dependencies for example?

I use pnpm as my package manager, and I can't install kitsu nor kitsu-core because the file uploaded to the npm registry has the wrong directory permissions. You can try it yourself:

http://registry.npmjs.org/kitsu/-/kitsu-5.0.6.tgz

untar it and try to enter the directory: you won't be able to cd into it (at least on macOS and on Linux).

I've already asked in the npm registry issue tracker and they suggest to solve this by releasing a new patch version with the fix.

Can you please do it? Thanks in advance!

Like the GET method, it seems as though the POST and PATCH methods should return a deserialized response as well. Currently, they are only returning the raw json response. Is this by design or just needs to be implemented?

Function serialise has 38 lines of code (exceeds 25 allowed). Consider refactoring.

https://codeclimate.com/github/wopian/kitsu/src/util/serialise/index.js#issue_5a6c1706938b34000100003b

The following data received in a GET response is not deserialised as expected in v7.0.3.

I tried to setup a test in the kitsu-core/src/deserialise/index.spec.js file to demonstrate but I couldn't quite get it working.

Call in my app:

const res = await api.get('workspace/39'})

Response / deserialised data:

{
  "data": {
    "type": "workspace",
    "id": "39",
    "links": {
      "self": "\/admin\/workspaces\/39"
    },
    "attributes": {
      "id": "39",
      "title": "iure",
      "createdAt": "2018-07-24T07:47:48+00:00",
      "updatedAt": "2018-07-24T07:47:48+00:00",
      "materializedPath": "\/workspace-39"
    },
    "relationships": {
      "projects": {
        "links": {
          "related": "\/admin\/projects?resourceScopeType=workspace&resourceScopeId=39"
        },
        "data": [
          {
            "type": "project",
            "id": "42"
          }
        ],
        "meta": []
      }
    },
    "meta": []
  },
  "includes": [
    {
      "type": "project",
      "id": "42",
      "links": {
        "self": "\/admin\/projects\/42"
      },
      "attributes": {
        "id": "42",
        "title": "Project 42",
        "createdAt": "2019-06-03T04:38:46+00:00",
        "updatedAt": "2019-06-03T04:38:46+00:00",
        "materializedPath": "\/workspace-39\/project-42"
      },
      "relationships": {
        "workspace": {
          "links": {
            "related": "\/admin\/workspaces\/39"
          },
          "data": {
            "type": "workspace",
            "id": "39"
          },
          "meta": []
        }
      },
      "meta": []
    }
  ]
}

Any ideas what would be causing the deserialisation to be skipped?

In the jsonapi spec, there is accommodation for client-generated IDs. In this library, however, they are explicitly not serialized in the request body.

See this line in serilaize/index.js.

...
} else if (key !== 'id' && key !== 'type') {
  data = serialiseAttr(node, key, data)
}
...

This is causing us quite an issue and we've had to put in a temporary vanilla fetch as a workaround.

Is there any specific reason for this being stripped out or can we accommodate it? Maybe as an optional parameter instead?

When I use the api of Kitsu to fetch data, it works fine. I was wondering if there is a way to serialize the data when it's coming from web sockets. Does Kitsu have any api whereby I can only serialize the data?

There's many edge cases that kitsu currently doesn't test its spec compliance with. Discussion about a test suite cropped up at json-api/json-api#1209, but they're all Ruby solutions at the moment.

Ideally we just want generic JSON responses that contains everything the spec allows.

An initial implementation has been added in __cases__ and the Kitsu class spec for get requests.

Hi there

I'm trying to make this work with Drupal JSONAPI is it possible to do filters like this :

filter[uid.uuid][value]=BB09E2CD-9487-44BC-B219-3DC03D6820CD
filter[title][operator]=CONTAINS&filter[title][value]=Foo

Thanks in advance