Add support for custom transformAndCheckStatus transform, and forcing json transforms (#159)

* Add support for custom transformAndCheckStatus transform, and forcing json transforms

* Checking new transform setup

* Finalising new transform and updating transformAndCheckStatus to match

* Adding exports and bumping version

* Bumping more versions and fixing comments

Author: aaronc-kablamo

packages/kerosene-test/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kablamo/kerosene-test",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "repository": "https://github.com/KablamoOSS/kerosene/tree/master/packages/kerosene-test",
   "bugs": {
     "url": "https://github.com/KablamoOSS/kerosene/issues"
@@ -46,7 +46,7 @@
     "utils"
   ],
   "dependencies": {
-    "@kablamo/kerosene": "^0.0.47",
+    "@kablamo/kerosene": "^0.0.48",
     "lodash": "^4.17.21",
     "sinon": "^19.0.2"
   },

packages/kerosene-ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kablamo/kerosene-ui",
-  "version": "0.0.47",
+  "version": "0.0.48",
   "repository": "https://github.com/KablamoOSS/kerosene/tree/master/packages/kerosene-ui",
   "bugs": {
     "url": "https://github.com/KablamoOSS/kerosene/issues"
@@ -35,12 +35,12 @@
     "node": ">=18.12.0"
   },
   "dependencies": {
-    "@kablamo/kerosene": "^0.0.47",
+    "@kablamo/kerosene": "^0.0.48",
     "lodash": "^4.17.21",
     "use-sync-external-store": "^1.4.0"
   },
   "devDependencies": {
-    "@kablamo/kerosene-test": "^0.0.20",
+    "@kablamo/kerosene-test": "^0.0.21",
     "@kablamo/rollup-plugin-resolve-externals": "^0.0.2",
     "@optimize-lodash/rollup-plugin": "^5.0.2",
     "@sinonjs/fake-timers": "^14.0.0",

packages/kerosene/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kablamo/kerosene",
-  "version": "0.0.47",
+  "version": "0.0.48",
   "repository": "https://github.com/KablamoOSS/kerosene/tree/master/packages/kerosene",
   "bugs": {
     "url": "https://github.com/KablamoOSS/kerosene/issues"

packages/kerosene/src/fetch/transform.spec.ts

@@ -1,11 +1,49 @@
 import _contentType, { type ParsedMediaType } from "content-type";
 import { when } from "jest-when";
 import type { DeepPartial } from "../types";
-import transform from "./transform";
+import transform, { createTransform, transformDefaultJson } from "./transform";
 
 jest.mock("content-type");
 const contentType = _contentType as unknown as jest.Mocked<typeof _contentType>;
 
+const contentTypes = [
+  {
+    type: "application/json",
+    method: "json",
+    content: { some: "prop" },
+    hasExplicitSupport: true,
+  },
+  {
+    type: "text/plain",
+    method: "text",
+    content: "Text",
+    hasExplicitSupport: true,
+  },
+  {
+    type: "application/pdf",
+    method: "blob",
+    content: Symbol("Blob"),
+    hasExplicitSupport: false,
+  },
+  {
+    type: "application/zip",
+    method: "blob",
+    content: Symbol("Blob"),
+    hasExplicitSupport: false,
+  },
+  {
+    type: "application/octet-stream",
+    method: "blob",
+    content: Symbol("Blob"),
+    hasExplicitSupport: false,
+  },
+] as const satisfies {
+  type: string;
+  method: string;
+  content: unknown;
+  hasExplicitSupport: boolean;
+}[];
+
 describe("transform", () => {
   it("should resolve a 204 status as null", async () => {
     await expect(
@@ -28,33 +66,7 @@ describe("transform", () => {
     ).resolves.toBe(text);
   });
 
-  [
-    {
-      type: "application/json",
-      method: "json",
-      content: { some: "prop" },
-    },
-    {
-      type: "text/plain",
-      method: "text",
-      content: "Text",
-    },
-    {
-      type: "application/pdf",
-      method: "blob",
-      content: Symbol("Blob"),
-    },
-    {
-      type: "application/zip",
-      method: "blob",
-      content: Symbol("Blob"),
-    },
-    {
-      type: "application/octet-stream",
-      method: "blob",
-      content: Symbol("Blob"),
-    },
-  ].forEach(({ type, method, content }) => {
+  contentTypes.forEach(({ type, method, content }) => {
     it(`should use ${method}() for ${type}`, async () => {
       const header = `${type}; charset=utf-8`;
       when(contentType.parse)
@@ -76,3 +88,111 @@ describe("transform", () => {
     });
   });
 });
+
+describe("createTransform", () => {
+  it("should resolve a 204 status as null", async () => {
+    const customTransform = createTransform();
+    await expect(
+      customTransform({ status: 204 } as Partial<Response> as Response),
+    ).resolves.toBe(null);
+  });
+
+  it("should resolve a response without a content type as the defaultTransform result", async () => {
+    const result = "transformedValue";
+    const customTransform = createTransform({
+      defaultTransform: () => Promise.resolve(result),
+    });
+    await expect(
+      customTransform({
+        status: 200,
+        headers: {
+          get: jest.fn().mockReturnValue(null),
+        },
+      } as DeepPartial<Response> as Response),
+    ).resolves.toBe(result);
+  });
+
+  contentTypes.forEach(({ type, method, content, hasExplicitSupport }) => {
+    const result = "transformedValue";
+    const customTransform = createTransform({
+      defaultTransform: () => Promise.resolve(result),
+    });
+
+    it(
+      hasExplicitSupport
+        ? `should use ${method}() for ${type}`
+        : `should use the provided transform for type ${type}`,
+      async () => {
+        const header = `${type}; charset=utf-8`;
+        when(contentType.parse)
+          .calledWith(header)
+          .mockReturnValue({
+            type,
+          } as Partial<ParsedMediaType> as ParsedMediaType);
+        const getHeaders = jest.fn();
+        when(getHeaders).calledWith("Content-Type").mockReturnValue(header);
+        await expect(
+          customTransform({
+            status: 200,
+            headers: {
+              get: getHeaders,
+            },
+            [method]: async () => content,
+          } as DeepPartial<Response> as Response),
+        ).resolves.toEqual(hasExplicitSupport ? content : result);
+      },
+    );
+  });
+});
+
+describe("transformDefaultJson", () => {
+  it("should resolve a 204 status as null", async () => {
+    await expect(
+      transformDefaultJson({
+        status: 204,
+      } as Partial<Response> as Response),
+    ).resolves.toBe(null);
+  });
+
+  it("should resolve a response without a content type as the json result", async () => {
+    const result = "transformedValue";
+    await expect(
+      transformDefaultJson({
+        status: 200,
+        headers: {
+          get: jest.fn().mockReturnValue(null),
+        },
+        json: () => Promise.resolve(result),
+      } as DeepPartial<Response> as Response),
+    ).resolves.toBe(result);
+  });
+
+  contentTypes.forEach(({ type, method, content, hasExplicitSupport }) => {
+    const result = { key: "value" };
+    it(
+      hasExplicitSupport
+        ? `should use ${method}() for ${type}`
+        : `should use the json transform for type ${type}`,
+      async () => {
+        const header = `${type}; charset=utf-8`;
+        when(contentType.parse)
+          .calledWith(header)
+          .mockReturnValue({
+            type,
+          } as Partial<ParsedMediaType> as ParsedMediaType);
+        const getHeaders = jest.fn();
+        when(getHeaders).calledWith("Content-Type").mockReturnValue(header);
+        await expect(
+          transformDefaultJson({
+            status: 200,
+            headers: {
+              get: getHeaders,
+            },
+            json: () => Promise.resolve(result),
+            [method]: async () => content,
+          } as DeepPartial<Response> as Response),
+        ).resolves.toEqual(hasExplicitSupport ? content : result);
+      },
+    );
+  });
+});

packages/kerosene/src/fetch/transform.ts

@@ -1,31 +1,57 @@
 import { parse } from "content-type";
 
+export type CreateTransformOptions = {
+  defaultTransform?: (res: Response) => Promise<unknown>;
+};
+
 /**
- * Takes a fetch response and attempts to transform the response automatically according to the status code and
- * Content-Type header (if provided)
- * @param response
+ * Create a handler for parsing fetch responses, using the status code and Content-Type header if provided, and falling back to an option custom transform if not. This is only necessary if you want to provide a defaultTransform for `transform` different to the existing behaviour
+ * @param options
+
  */
-export default function transform(response: Response) {
-  if (response.status === 204) {
-    return Promise.resolve(null);
-  }
+export function createTransform({
+  defaultTransform,
+}: CreateTransformOptions = {}) {
+  return (response: Response) => {
+    if (response.status === 204) {
+      return Promise.resolve(null);
+    }
 
-  const contentType = response.headers.get("Content-Type");
+    const contentType = response.headers.get("Content-Type");
 
-  if (!contentType) {
-    return response.text();
-  }
+    if (!contentType) {
+      return defaultTransform ? defaultTransform(response) : response.text();
+    }
 
-  const { type } = parse(contentType);
+    const { type } = parse(contentType);
 
-  switch (type) {
-    case "application/json":
-      return response.json();
+    switch (type) {
+      case "application/json":
+        return response.json();
 
-    case "text/plain":
-      return response.text();
+      case "text/plain":
+        return response.text();
 
-    default:
-      return response.blob();
-  }
+      default:
+        return defaultTransform ? defaultTransform(response) : response.blob();
+    }
+  };
 }
+
+/**
+ * Takes a fetch response and attempts to transform the response automatically according to the status code and
+ * Content-Type header (if provided), falling back to the JSON response if a matching type is not found
+ * @param response
+ */
+export const transformDefaultJson = createTransform({
+  defaultTransform: (response) => response.json(),
+});
+
+/**
+ * Takes a fetch response and attempts to transform the response automatically according to the status code and
+ * Content-Type header (if provided)
+ * @param response
+ */
+const transform = createTransform();
+
+export default transform;