{"id":14657,"library":"kitsu-core","title":"Kitsu Core JSON:API (De)serializer","description":"kitsu-core is a compact and framework-agnostic JavaScript/TypeScript library designed for the (de)serialization of JSON:API 1.0 compliant data structures. Currently in its 11.x stable release cycle, with version 11.1.1 being the latest, the project demonstrates an active development and release cadence, often publishing minor and patch updates within weeks or months. Its core differentiators include strict adherence to the JSON:API specification, automatic linking of relationships, and a zero-dependency footprint, making it highly tree-shakeable and suitable for both Node.js and browser environments. Recent updates have focused on significant performance improvements for large datasets (up to 1,000 times faster deserialization in v11.0.2) and introducing opt-in data hoisting features, allowing for more flexible data structuring post-deserialization. The library emphasizes minimal bundle size and broad modern environment compatibility.","status":"active","version":"11.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/wopian/kitsu","tags":["javascript","kitsu","jsonapi","json-api","serialize","deserialize","typescript"],"install":[{"cmd":"npm install kitsu-core","lang":"bash","label":"npm"},{"cmd":"yarn add kitsu-core","lang":"bash","label":"yarn"},{"cmd":"pnpm add kitsu-core","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Prefer ES Module imports in modern Node.js and browser environments; CommonJS requires named property access. The library is optimized for ESM.","wrong":"const deserialise = require('kitsu-core').deserialise;","symbol":"deserialise","correct":"import { deserialise } from 'kitsu-core';"},{"note":"All primary functions and utilities are named exports. There is no default export from 'kitsu-core'.","wrong":"import serialise from 'kitsu-core';","symbol":"serialise","correct":"import { serialise } from 'kitsu-core';"},{"note":"Directly import specific utility functions like `camel` for optimal tree-shaking and bundle size.","wrong":"import * as kitsuCore from 'kitsu-core'; kitsuCore.camel(...);","symbol":"camel","correct":"import { camel } from 'kitsu-core';"},{"note":"For TypeScript, use `import type` for type-only imports to improve clarity and potential bundler optimizations, especially since v10.1.4 improved fine-grained type exports.","wrong":"import { JsonApiDocument } from 'kitsu-core';","symbol":"JsonApiDocument","correct":"import type { JsonApiDocument } from 'kitsu-core';"}],"quickstart":{"code":"import { deserialise, serialise, camel } from 'kitsu-core';\n\n// Example JSON:API response structure\nconst jsonApiResponse = {\n  data: {\n    type: 'articles',\n    id: '1',\n    attributes: {\n      'title-post': 'JSON:API is great!',\n      'content-body': 'This is some content.'\n    },\n    relationships: {\n      author: {\n        data: { type: 'users', id: '9' }\n      },\n      comments: {\n        data: [\n          { type: 'comments', id: '5' },\n          { type: 'comments', id: '12' }\n        ]\n      }\n    }\n  },\n  included: [\n    {\n      type: 'users',\n      id: '9',\n      attributes: {\n        'full-name': 'John Doe'\n      }\n    },\n    {\n      type: 'comments',\n      id: '5',\n      attributes: {\n        body: 'First comment'\n      }\n    },\n    {\n      type: 'comments',\n      id: '12',\n      attributes: {\n        body: 'Second comment'\n      },\n      relationships: {\n          author: {\n              data: { type: 'users', id: '9' }\n          }\n      }\n    }\n  ]\n};\n\nasync function runKitsuCoreExample() {\n  console.log('Original JSON:API Response:', JSON.stringify(jsonApiResponse, null, 2));\n\n  // Deserialise the JSON:API response into a plain JavaScript object, applying camelCaseKeys\n  const deserializedData = await deserialise(jsonApiResponse, { camelCaseKeys: true });\n  console.log('\\nDeserialized Data (camelCaseKeys: true):', JSON.stringify(deserializedData, null, 2));\n\n  // Example of using the standalone camel utility\n  const camelCasedKey = camel('my-kebab-case-key');\n  console.log('\\nCamel cased key:', camelCasedKey); // myKebabCaseKey\n\n  // Prepare data for serialization (e.g., after modifying it)\n  const articleToSerialize = {\n    id: '1',\n    type: 'articles',\n    titlePost: 'Updated Title',\n    contentBody: 'New content here.',\n    author: {\n      id: '9',\n      type: 'users'\n    },\n    comments: [\n      { id: '5', type: 'comments' },\n      { id: '12', type: 'comments' }\n    ]\n  };\n\n  // Serialize a plain JavaScript object back into JSON:API format\n  const serializedData = await serialise(articleToSerialize, 'articles', { camelCaseKeys: true });\n  console.log('\\nSerialized Data (camelCaseKeys: true):', JSON.stringify(serializedData, null, 2));\n\n  // Demonstrate data hoisting (introduced in v11.1.0)\n  const hoistedData = await deserialise(jsonApiResponse, {\n    camelCaseKeys: true,\n    hoist: ['author'] // Hoist the 'author' relationship directly onto the article object\n  });\n  console.log('\\nDeserialized Data with Author Hoisted (opt-in since v11.1.0):', JSON.stringify(hoistedData, null, 2));\n}\n\nrunKitsuCoreExample();","lang":"typescript","description":"This code snippet demonstrates how to use `kitsu-core` to deserialize a JSON:API response into a plain JavaScript object, apply camel-casing to keys, serialize an object back into JSON:API format, and utilize the opt-in data hoisting feature for relationships."},"warnings":[{"fix":"Consult the official migration guide at `https://github.com/wopian/kitsu/blob/master/packages/kitsu-core/MIGRATING.md` before upgrading to understand necessary code adaptations.","_review":true,"message":"Upgrading to v11.x introduces potential breaking changes. The project's migration guide (linked in the README) details API changes, particularly around `deserialise` and `serialise` functions, and updates to internal type definitions and usage patterns. While the provided changelog for v11.0.0 mostly notes JSDoc fixes, major version bumps often imply broader compatibility or API shifts.","severity":"breaking","_review_reason":"Could not access the external migration guide link to enumerate specific breaking changes.","affected_versions":">=11.0.0"},{"fix":"Prefer ES Module `import` syntax (`import { symbol } from 'kitsu-core';`). Ensure your Node.js environment is version 18 or higher. For browser usage, consider modern bundlers that handle ESM correctly.","message":"This library is designed for modern Node.js environments (v18, 20, 22+) and browsers supporting ES Modules. While CommonJS `require` syntax is shown in some examples, the library is optimized for and increasingly leverages ES Modules. Mixing CJS and ESM in complex projects or using older Node.js versions (below 18) may lead to module resolution issues or require additional configuration.","severity":"gotcha","affected_versions":">=10.0.0"},{"fix":"To utilize data hoisting, pass a `hoist` option (e.g., `hoist: ['author', 'comments']`) to the `deserialise` function with an array of relationship keys you wish to hoist.","message":"Version 11.1.0 introduced an opt-in data hoisting feature when deserializing responses. By default, JSON:API relationships are linked but maintain the specified structure. If you expect a flatter data structure where relationships are directly merged onto the parent object, you must explicitly enable and configure the `hoist` option in `deserialise`.","severity":"gotcha","affected_versions":">=11.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const { symbol } = require('kitsu-core');` to `import { symbol } from 'kitsu-core';`. Ensure your project's module configuration in `package.json` and `tsconfig.json` (if applicable) aligns with your chosen module system.","cause":"Attempting to use CommonJS `require()` syntax in an ES Module (ESM) context (e.g., in a file with `.mjs` extension or when `\"type\": \"module\"` is set in `package.json`).","error":"ReferenceError: require is not defined"},{"fix":"Ensure `kitsu-core` is correctly installed. Verify `tsconfig.json` includes `\"compilerOptions\": { \"moduleResolution\": \"Node16\", \"module\": \"Node16\", \"allowSyntheticDefaultImports\": true }` or `\"Bundler\"` for modern setups. Consider updating TypeScript and `kitsu-core` to their latest versions.","cause":"TypeScript compiler cannot locate the type definitions for `kitsu-core`, or there's a mismatch in module resolution settings between `tsconfig.json` and the installed package version. This can be exacerbated by changes in v10.1.4 regarding fine-grained type exports.","error":"TS2307: Cannot find module 'kitsu-core' or its corresponding type declarations."},{"fix":"Carefully inspect your JSON:API response to ensure it includes all related resources in the `included` array and that `relationships.data` objects correctly reference these resources by `type` and `id`.","cause":"The input JSON:API response is malformed, missing required `included` data, or does not strictly adhere to the JSON:API 1.0 specification for relationships and compound documents.","error":"Deserialized data does not have expected relationships linked, or relationships are present but not resolved to full objects."}],"ecosystem":"npm"}