feat(kitsu-core): implement opt-in data hoisting when deserialising response

Author: wopian

package.json

@@ -58,6 +58,9 @@
     "size-limit": "^8.2.0",
     "typescript": "^5.9.0"
   },
+  "resolutions": {
+    "@types/minimatch": "5.1.2"
+  },
   "jest": {
     "coverageThreshold": {
       "global": {

packages/kitsu-core/README.md

@@ -99,40 +99,42 @@ All code released under [MIT]
 *   [deattribute](#deattribute)
     *   [Parameters](#parameters-1)
     *   [Examples](#examples-1)
-*   [deserialise](#deserialise)
+*   [hoist](#hoist)
     *   [Parameters](#parameters-2)
+*   [deserialise](#deserialise)
+    *   [Parameters](#parameters-3)
     *   [Examples](#examples-2)
 *   [error](#error)
-    *   [Parameters](#parameters-3)
+    *   [Parameters](#parameters-4)
     *   [Examples](#examples-3)
 *   [filterIncludes](#filterincludes)
-    *   [Parameters](#parameters-4)
+    *   [Parameters](#parameters-5)
     *   [Examples](#examples-4)
 *   [kebab](#kebab)
-    *   [Parameters](#parameters-5)
+    *   [Parameters](#parameters-6)
     *   [Examples](#examples-5)
 *   [linkRelationships](#linkrelationships)
-    *   [Parameters](#parameters-6)
+    *   [Parameters](#parameters-7)
     *   [Examples](#examples-6)
 *   [isDeepEqual](#isdeepequal)
-    *   [Parameters](#parameters-7)
+    *   [Parameters](#parameters-8)
     *   [Examples](#examples-7)
 *   [query](#query)
-    *   [Parameters](#parameters-8)
+    *   [Parameters](#parameters-9)
     *   [Examples](#examples-8)
 *   [serialise](#serialise)
-    *   [Parameters](#parameters-9)
+    *   [Parameters](#parameters-10)
     *   [Examples](#examples-9)
 *   [snake](#snake)
-    *   [Parameters](#parameters-10)
+    *   [Parameters](#parameters-11)
     *   [Examples](#examples-10)
 *   [splitModel](#splitmodel)
-    *   [Parameters](#parameters-11)
+    *   [Parameters](#parameters-12)
     *   [Examples](#examples-11)
 
 ### camel
 
-[packages/kitsu-core/src/camel/index.js:14-14](https://github.com/wopian/kitsu/blob/a794fdd4c0266be8d8404455ebf2847e47e66a64/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/9039f9be49ca8ba032ad6b7099316b6751e18198/packages/kitsu-core/src/camel/index.js#L14-L14 "Source code on GitHub")
 
 Converts kebab-case and snake\_case into camelCase
 
@@ -158,7 +160,7 @@ Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G
 
 ### deattribute
 
-[packages/kitsu-core/src/deattribute/index.js:29-51](https://github.com/wopian/kitsu/blob/a794fdd4c0266be8d8404455ebf2847e47e66a64/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/9039f9be49ca8ba032ad6b7099316b6751e18198/packages/kitsu-core/src/deattribute/index.js#L29-L51 "Source code on GitHub")
 
 Hoists attributes to be top-level
 
@@ -198,15 +200,35 @@ 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
 
+### hoist
+
+[packages/kitsu-core/src/deserialise/index.js:24-77](https://github.com/wopian/kitsu/blob/9039f9be49ca8ba032ad6b7099316b6751e18198/packages/kitsu-core/src/deserialise/index.js#L24-L77 "Source code on GitHub")
+
+Recursively traverses and clones an object or array, handling cyclic references.
+If the object is a wrapper of the form { data: ... }, it unwraps and processes the `data` property.
+
+#### Parameters
+
+*   `object` **any** The input to hoist (object or array)
+
+Returns **any** The hoisted object or array
+
 ### deserialise
 
-[packages/kitsu-core/src/deserialise/index.js:63-78](https://github.com/wopian/kitsu/blob/a794fdd4c0266be8d8404455ebf2847e47e66a64/packages/kitsu-core/src/deserialise/index.js#L63-L78 "Source code on GitHub")
+[packages/kitsu-core/src/deserialise/index.js:150-170](https://github.com/wopian/kitsu/blob/9039f9be49ca8ba032ad6b7099316b6751e18198/packages/kitsu-core/src/deserialise/index.js#L150-L170 "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
+*   `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Deserialisation options (optional, default `{}`)
+
+    *   `options.hoistData` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** If enabled, the contents of the `data` property will be hoisted to the parent. This provides a flatter response object, but removes access to `links` and `meta` properties. It will transform:```js
+        { data: { id: '1', type: 'people', coworkers: data: [ { id: '2', type: 'people' } ] } }
+        ```into the following:```js
+        { id: '1', type: 'people', coworkers: [ { id: '2', type: 'people' } ] }
+        ``` (optional, default `false`)
 
 #### Examples
 
@@ -250,7 +272,7 @@ Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G
 
 ### error
 
-[packages/kitsu-core/src/error/index.js:27-33](https://github.com/wopian/kitsu/blob/a794fdd4c0266be8d8404455ebf2847e47e66a64/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/9039f9be49ca8ba032ad6b7099316b6751e18198/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.
 
@@ -287,7 +309,7 @@ error({
 
 ### filterIncludes
 
-[packages/kitsu-core/src/filterIncludes/index.js:33-46](https://github.com/wopian/kitsu/blob/a794fdd4c0266be8d8404455ebf2847e47e66a64/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/9039f9be49ca8ba032ad6b7099316b6751e18198/packages/kitsu-core/src/filterIncludes/index.js#L33-L46 "Source code on GitHub")
 
 Filters includes for the specific relationship requested
 
@@ -327,7 +349,7 @@ Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G
 
 ### kebab
 
-[packages/kitsu-core/src/kebab/index.js:11-11](https://github.com/wopian/kitsu/blob/a794fdd4c0266be8d8404455ebf2847e47e66a64/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/9039f9be49ca8ba032ad6b7099316b6751e18198/packages/kitsu-core/src/kebab/index.js#L11-L11 "Source code on GitHub")
 
 Converts camelCase into kebab-case
 
@@ -345,7 +367,7 @@ Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G
 
 ### linkRelationships
 
-[packages/kitsu-core/src/linkRelationships/index.js:144-164](https://github.com/wopian/kitsu/blob/a794fdd4c0266be8d8404455ebf2847e47e66a64/packages/kitsu-core/src/linkRelationships/index.js#L144-L164 "Source code on GitHub")
+[packages/kitsu-core/src/linkRelationships/index.js:144-164](https://github.com/wopian/kitsu/blob/9039f9be49ca8ba032ad6b7099316b6751e18198/packages/kitsu-core/src/linkRelationships/index.js#L144-L164 "Source code on GitHub")
 
 Links relationships to included data
 
@@ -385,7 +407,7 @@ Returns **any** Parsed data
 
 ### isDeepEqual
 
-[packages/kitsu-core/src/deepEqual/index.js:18-42](https://github.com/wopian/kitsu/blob/a794fdd4c0266be8d8404455ebf2847e47e66a64/packages/kitsu-core/src/deepEqual/index.js#L18-L42 "Source code on GitHub")
+[packages/kitsu-core/src/deepEqual/index.js:18-42](https://github.com/wopian/kitsu/blob/9039f9be49ca8ba032ad6b7099316b6751e18198/packages/kitsu-core/src/deepEqual/index.js#L18-L42 "Source code on GitHub")
 
 Compare two objects equality
 
@@ -414,7 +436,7 @@ Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/
 
 ### query
 
-[packages/kitsu-core/src/query/index.js:57-66](https://github.com/wopian/kitsu/blob/a794fdd4c0266be8d8404455ebf2847e47e66a64/packages/kitsu-core/src/query/index.js#L57-L66 "Source code on GitHub")
+[packages/kitsu-core/src/query/index.js:57-66](https://github.com/wopian/kitsu/blob/9039f9be49ca8ba032ad6b7099316b6751e18198/packages/kitsu-core/src/query/index.js#L57-L66 "Source code on GitHub")
 
 Constructs a URL query string for JSON:API parameters
 
@@ -443,7 +465,7 @@ Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G
 
 ### serialise
 
-[packages/kitsu-core/src/serialise/index.js:210-221](https://github.com/wopian/kitsu/blob/a794fdd4c0266be8d8404455ebf2847e47e66a64/packages/kitsu-core/src/serialise/index.js#L210-L221 "Source code on GitHub")
+[packages/kitsu-core/src/serialise/index.js:210-221](https://github.com/wopian/kitsu/blob/9039f9be49ca8ba032ad6b7099316b6751e18198/packages/kitsu-core/src/serialise/index.js#L210-L221 "Source code on GitHub")
 
 Serialises an object into a JSON-API structure
 
@@ -488,7 +510,7 @@ Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G
 
 ### snake
 
-[packages/kitsu-core/src/snake/index.js:11-11](https://github.com/wopian/kitsu/blob/a794fdd4c0266be8d8404455ebf2847e47e66a64/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/9039f9be49ca8ba032ad6b7099316b6751e18198/packages/kitsu-core/src/snake/index.js#L11-L11 "Source code on GitHub")
 
 Converts camelCase into snake\_case
 
@@ -506,7 +528,7 @@ Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G
 
 ### splitModel
 
-[packages/kitsu-core/src/splitModel/index.js:29-39](https://github.com/wopian/kitsu/blob/a794fdd4c0266be8d8404455ebf2847e47e66a64/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/9039f9be49ca8ba032ad6b7099316b6751e18198/packages/kitsu-core/src/splitModel/index.js#L29-L39 "Source code on GitHub")
 
 Split model name from the model's resource URL
 

packages/kitsu-core/package.json

@@ -17,6 +17,7 @@
   "unpkg": "dist/index.browser.js",
   "jsdelivr": "dist/index.browser.js",
   "types": "types/index.d.ts",
+  "type": "module",
   "homepage": "https://github.com/wopian/kitsu/tree/master/packages/kitsu-core#readme",
   "repository": "https://github.com/wopian/kitsu",
   "bugs": {

packages/kitsu-core/src/deserialise/index.js

@@ -1,6 +1,84 @@
 import { deattribute } from '../deattribute'
 import { linkRelationships } from '../linkRelationships'
 
+/**
+ * Hoists the contents of `data` properties to their parent object recursively.
+ * This provides a flatter response object, but removes access to `links` and `meta`
+ * properties.
+ *
+ * @param {Object} response The response object
+ * @returns {Object} The response with `data` properties hoisted
+ * @private
+ */
+function hoistData (response) {
+  const seen = new WeakMap()
+  const hasOwn = Object.prototype.hasOwnProperty
+
+  /**
+   * Recursively traverses and clones an object or array, handling cyclic references.
+   * If the object is a wrapper of the form { data: ... }, it unwraps and processes the `data` property.
+   *
+   * @param {any} object The input to hoist (object or array)
+   * @returns {any} The hoisted object or array
+   */
+  function hoist (object) {
+    if (object && typeof object === 'object') {
+      if (seen.has(object)) {
+        return seen.get(object)
+      }
+
+      let out
+
+      if (Array.isArray(object)) {
+        out = []
+        seen.set(object, out)
+
+        let i = 0
+
+        for (const item of object) {
+          out[i] = hoist(item)
+          i++
+        }
+
+        return out
+      }
+
+      // Check for { data: ... } wrapper without allocating Object.keys
+      let onlyData = false
+
+      for (const key in object) {
+        if (!hasOwn.call(object, key)) continue
+
+        if (key === 'data' && !onlyData) {
+          onlyData = true
+        } else {
+          onlyData = false
+          break
+        }
+      }
+
+      if (onlyData) {
+        return hoist(object.data)
+      }
+
+      out = {}
+      seen.set(object, out)
+
+      for (const key in object) {
+        if (hasOwn.call(object, key)) {
+          out[key] = hoist(object[key])
+        }
+      }
+
+      return out
+    }
+
+    return object
+  }
+
+  return hoist(response)
+}
+
 /**
  * Deserialises an array from a JSON-API structure
  *
@@ -28,6 +106,15 @@ function deserialiseArray (response) {
  * Deserialises a JSON-API response
  *
  * @param {Object} response The raw JSON:API response object
+ * @param {Object} [options={}] Deserialisation options
+ * @param {boolean} [options.hoistData=false] If enabled, the contents of the `data` property will be hoisted to the parent. This provides a flatter response object, but removes access to `links` and `meta` properties. It will transform:
+ * ```js
+ * { data: { id: '1', type: 'people', coworkers: data: [ { id: '2', type: 'people' } ] } }
+ * ```
+ * into the following:
+ * ```js
+ * { id: '1', type: 'people', coworkers: [ { id: '2', type: 'people' } ] }
+ * ```
  * @returns {Object} The deserialised response
  *
  * @example <caption>Deserialise with a basic data object</caption>
@@ -60,7 +147,7 @@ function deserialiseArray (response) {
  *   ]
  * }) // { data: { id: '1', user: { data: { type: 'users', id: '2', slug: 'wopian' } } } }
  */
-export function deserialise (response) {
+export function deserialise (response, options = { hoistData: false }) {
   if (!response) return
 
   // Collection of resources
@@ -74,5 +161,10 @@ export function deserialise (response) {
   // Move attributes to the parent object
   if (response.data?.attributes) response.data = deattribute(response.data)
 
+  // Hoist data to flatten the response structure if requested
+  if (options.hoistData && response.data) {
+    response = hoistData(response)
+  }
+
   return response
 }