@schmock/query 2.2.2 → 2.3.0

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,UAAU,iBAAiB;IACzB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,cAAc;IACtB,iCAAiC;IACjC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC9B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,gBAAgB;IACxB,mCAAmC;IACnC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,UAAU,kBAAkB;IAC1B,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAoCvE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,UAAU,iBAAiB;IACzB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,cAAc;IACtB,iCAAiC;IACjC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC9B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,gBAAgB;IACxB,mCAAmC;IACnC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,UAAU,kBAAkB;IAC1B,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AA2CD,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAoCvE"}

package/dist/index.js

@@ -1 +1 @@
-var B="2.2.2";function N(c){return{name:"query",version:B,process(h,d){if(!Array.isArray(d))return{context:h,response:d};let j=[...d],k=h.query||{};if(c.filtering)j=E(j,k,c.filtering);if(c.sorting)j=G(j,k,c.sorting);if(c.pagination){let v=H(j,k,c.pagination);return{context:h,response:v}}return{context:h,response:j}}}}function E(c,h,d){let j=d.filterPrefix??"filter",k=c;for(let v of d.allowed){let g=`${j}[${v}]`,f=`${j}.${v}`,b=h[g]??h[f]??h[v];if(b!==void 0)k=k.filter((w)=>{if(typeof w!=="object"||w===null)return!1;let D=w[v];if(D===void 0)return!1;return String(D)===b})}return k}function G(c,h,d){let j=d.sortParam??"sort",k=d.orderParam??"order",v=h[j]??d.default,f=(h[k]??d.defaultOrder??"asc")==="desc"?"desc":"asc";if(!v)return c;if(!d.allowed.includes(v))return c;return c.sort((b,w)=>{if(typeof b!=="object"||b===null)return 0;if(typeof w!=="object"||w===null)return 0;let z=b,D=w,M=z[v],T=D[v];if(M===T)return 0;if(M===void 0)return 1;if(T===void 0)return-1;let A;if(typeof M==="number"&&typeof T==="number")A=M-T;else A=String(M).localeCompare(String(T));return f==="desc"?-A:A})}function H(c,h,d){let j=d.pageParam??"page",k=d.limitParam??"limit",v=d.defaultLimit??10,g=d.maxLimit??100,f=Math.max(1,Number.parseInt(h[j]||"1",10)||1),b=Math.min(g,Math.max(1,Number.parseInt(h[k]||String(v),10)||v)),w=c.length,z=Math.ceil(w/b),D=(f-1)*b;return{data:c.slice(D,D+b),pagination:{page:f,limit:b,total:w,totalPages:z}}}export{N as queryPlugin};
+import{isStatusTuple as N}from"@schmock/core";var I="2.3.0";function H(c){return typeof c==="object"&&c!==null}function W(c){return H(c)&&Object.values(c).every((h)=>typeof h==="string")}function Q(c){return H(c)&&!Array.isArray(c)&&typeof c.status==="number"&&"body"in c&&(c.headers===void 0||W(c.headers))}function X(c){if(N(c))return c[1];if(Q(c))return c.body;return c}function J(c,h){if(N(c))return c.length===3?[c[0],h,c[2]]:[c[0],h];if(Q(c))return{...c,body:h};return h}function T(c){return{name:"query",version:I,process(h,j){let M=X(j);if(!Array.isArray(M))return{context:h,response:j};let w=[...M],k=h.query||{};if(c.filtering)w=Y(w,k,c.filtering);if(c.sorting)w=Z(w,k,c.sorting);if(c.pagination){let C=_(w,k,c.pagination);return{context:h,response:J(j,C)}}return{context:h,response:J(j,w)}}}}function Y(c,h,j){let M=j.filterPrefix??"filter",w=c;for(let k of j.allowed){let C=`${M}[${k}]`,E=`${M}.${k}`,f=h[C]??h[E]??h[k];if(f!==void 0)w=w.filter((z)=>{if(!H(z))return!1;let D=z[k];if(D===void 0)return!1;return String(D)===f})}return w}function Z(c,h,j){let M=j.sortParam??"sort",w=j.orderParam??"order",k=h[M]??j.default,E=(h[w]??j.defaultOrder??"asc")==="desc"?"desc":"asc";if(!k)return c;if(!j.allowed.includes(k))return c;return c.sort((f,z)=>{if(!H(f)||!H(z))return 0;let D=f[k],A=z[k];if(D===A)return 0;if(D===void 0)return 1;if(A===void 0)return-1;let G;if(typeof D==="number"&&typeof A==="number")G=D-A;else G=String(D).localeCompare(String(A));return E==="desc"?-G:G})}function _(c,h,j){let M=j.pageParam??"page",w=j.limitParam??"limit",k=j.defaultLimit??10,C=j.maxLimit??100,E=Math.max(1,Number.parseInt(h[M]||"1",10)||1),f=Math.min(C,Math.max(1,Number.parseInt(h[w]||String(k),10)||k)),z=c.length,D=Math.ceil(z/f),A=(E-1)*f;return{data:c.slice(A,A+f),pagination:{page:E,limit:f,total:z,totalPages:D}}}export{T as queryPlugin};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@schmock/query",
   "description": "Pagination, filtering, and sorting plugin for Schmock",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -19,9 +19,9 @@
   },
   "scripts": {
     "build": "bun build:lib && bun build:types",
-    "build:lib": "bun build --minify --target node --outdir=dist src/index.ts",
+    "build:lib": "bun build --minify --target node --format esm --outdir=dist src/index.ts --external @schmock/core",
     "build:types": "tsc -p tsconfig.json",
-    "test": "vitest",
+    "test": "vitest run",
     "test:watch": "vitest --watch",
     "test:bdd": "vitest run --config vitest.config.bdd.ts",
     "lint": "biome check src/*.ts",
@@ -30,7 +30,7 @@
   },
   "license": "MIT",
   "peerDependencies": {
-    "@schmock/core": "^2.2.2"
+    "@schmock/core": "^2.3.0"
   },
   "devDependencies": {
     "@amiceli/vitest-cucumber": "^7.0.0",

package/src/index.test.ts

@@ -52,6 +52,132 @@ describe("queryPlugin", () => {
     });
   });
 
+  it("paginates the array body of a two-element status tuple", async () => {
+    const plugin = queryPlugin({
+      pagination: { defaultLimit: 2, maxLimit: 10 },
+    });
+    const items = [{ id: 1 }, { id: 2 }, { id: 3 }, { id: 4 }, { id: 5 }];
+    const context: Schmock.PluginContext = {
+      path: "/test",
+      route: {},
+      method: "GET",
+      params: {},
+      query: { page: "2", limit: "2" },
+      headers: {},
+      state: new Map(),
+    };
+
+    const result = await plugin.process(context, [206, items] satisfies [
+      number,
+      unknown,
+    ]);
+
+    expect(result.response).toEqual([
+      206,
+      {
+        data: [{ id: 3 }, { id: 4 }],
+        pagination: { page: 2, limit: 2, total: 5, totalPages: 3 },
+      },
+    ]);
+  });
+
+  it("paginates a status tuple body without changing its headers", async () => {
+    const plugin = queryPlugin({
+      pagination: { defaultLimit: 2, maxLimit: 10 },
+    });
+    const items = [{ id: 1 }, { id: 2 }, { id: 3 }, { id: 4 }, { id: 5 }];
+    const headers = {
+      "content-type": "application/json",
+      "x-response-source": "tuple",
+    };
+    const context: Schmock.PluginContext = {
+      path: "/test",
+      route: {},
+      method: "GET",
+      params: {},
+      query: { page: "2", limit: "2" },
+      headers: {},
+      state: new Map(),
+    };
+
+    const result = await plugin.process(context, [
+      206,
+      items,
+      headers,
+    ] satisfies [number, unknown, Record<string, string>]);
+
+    expect(result.response).toEqual([
+      206,
+      {
+        data: [{ id: 3 }, { id: 4 }],
+        pagination: { page: 2, limit: 2, total: 5, totalPages: 3 },
+      },
+      headers,
+    ]);
+  });
+
+  it("paginates a structured response body without changing metadata", async () => {
+    const plugin = queryPlugin({
+      pagination: { defaultLimit: 2, maxLimit: 10 },
+    });
+    const items = [{ id: 1 }, { id: 2 }, { id: 3 }, { id: 4 }, { id: 5 }];
+    const response = {
+      status: 206,
+      body: items,
+      headers: { "x-response-source": "structured" },
+    };
+    const context: Schmock.PluginContext = {
+      path: "/test",
+      route: {},
+      method: "GET",
+      params: {},
+      query: { page: "2", limit: "2" },
+      headers: {},
+      state: new Map(),
+    };
+
+    const result = await plugin.process(context, response);
+
+    expect(result.response).toEqual({
+      status: 206,
+      body: {
+        data: [{ id: 3 }, { id: 4 }],
+        pagination: { page: 2, limit: 2, total: 5, totalPages: 3 },
+      },
+      headers: { "x-response-source": "structured" },
+    });
+  });
+
+  it("passes response containers through when their semantic body is not an array", async () => {
+    const plugin = queryPlugin({ pagination: { defaultLimit: 2 } });
+    const context: Schmock.PluginContext = {
+      path: "/test",
+      route: {},
+      method: "GET",
+      params: {},
+      query: { page: "2", limit: "2" },
+      headers: {},
+      state: new Map(),
+    };
+    const responses: unknown[] = [
+      [
+        202,
+        { message: "accepted" },
+        { "x-response-source": "tuple" },
+      ] satisfies [number, unknown, Record<string, string>],
+      {
+        status: 202,
+        body: { message: "accepted" },
+        headers: { "x-response-source": "structured" },
+      },
+    ];
+
+    for (const response of responses) {
+      const result = await plugin.process(context, response);
+      expect(result.response).toBe(response);
+    }
+  });
+
   it("sorts array responses", async () => {
     const plugin = queryPlugin({
       sorting: { allowed: ["name"], default: "name" },

package/src/index.ts

@@ -1,5 +1,6 @@
 /// <reference path="../../core/schmock.d.ts" />
 
+import { isStatusTuple } from "@schmock/core";
 import { version as packageVersion } from "../package.json";
 
 interface PaginationOptions {
@@ -39,6 +40,47 @@ interface QueryPluginOptions {
   filtering?: FilteringOptions;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return (
+    isRecord(value) &&
+    Object.values(value).every((entry) => typeof entry === "string")
+  );
+}
+
+function isStructuredResponse(value: unknown): value is {
+  status: number;
+  body: unknown;
+  headers?: Record<string, string>;
+} {
+  return (
+    isRecord(value) &&
+    !Array.isArray(value) &&
+    typeof value.status === "number" &&
+    "body" in value &&
+    (value.headers === undefined || isStringRecord(value.headers))
+  );
+}
+
+function getResponseBody(response: unknown): unknown {
+  if (isStatusTuple(response)) return response[1];
+  if (isStructuredResponse(response)) return response.body;
+  return response;
+}
+
+function replaceResponseBody(response: unknown, body: unknown): unknown {
+  if (isStatusTuple(response)) {
+    return response.length === 3
+      ? [response[0], body, response[2]]
+      : [response[0], body];
+  }
+  if (isStructuredResponse(response)) return { ...response, body };
+  return body;
+}
+
 export function queryPlugin(options: QueryPluginOptions): Schmock.Plugin {
   return {
     name: "query",
@@ -48,12 +90,12 @@ export function queryPlugin(options: QueryPluginOptions): Schmock.Plugin {
       context: Schmock.PluginContext,
       response?: unknown,
     ): Schmock.PluginResult {
-      // Only process array responses
-      if (!Array.isArray(response)) {
+      const responseBody = getResponseBody(response);
+      if (!Array.isArray(responseBody)) {
         return { context, response };
       }
 
-      let items: unknown[] = [...response];
+      let items: unknown[] = [...responseBody];
       const query = context.query || {};
 
       // Apply filtering
@@ -69,10 +111,10 @@ export function queryPlugin(options: QueryPluginOptions): Schmock.Plugin {
       // Apply pagination
       if (options.pagination) {
         const result = applyPagination(items, query, options.pagination);
-        return { context, response: result };
+        return { context, response: replaceResponseBody(response, result) };
       }
 
-      return { context, response: items };
+      return { context, response: replaceResponseBody(response, items) };
     },
   };
 }
@@ -95,9 +137,8 @@ function applyFiltering(
 
     if (value !== undefined) {
       result = result.filter((item) => {
-        if (typeof item !== "object" || item === null) return false;
-        const record = item as Record<string, unknown>;
-        const itemValue = record[field];
+        if (!isRecord(item)) return false;
+        const itemValue = item[field];
         if (itemValue === undefined) return false;
         // Intentional string coercion: query params are inherently strings
         return String(itemValue) === value;
@@ -125,12 +166,9 @@ function applySorting(
   if (!options.allowed.includes(sortField)) return items;
 
   return items.sort((a, b) => {
-    if (typeof a !== "object" || a === null) return 0;
-    if (typeof b !== "object" || b === null) return 0;
-    const aRecord = a as Record<string, unknown>;
-    const bRecord = b as Record<string, unknown>;
-    const aVal = aRecord[sortField];
-    const bVal = bRecord[sortField];
+    if (!isRecord(a) || !isRecord(b)) return 0;
+    const aVal = a[sortField];
+    const bVal = b[sortField];
 
     if (aVal === bVal) return 0;
     if (aVal === undefined) return 1;

package/src/steps/query-plugin.steps.ts

@@ -5,13 +5,52 @@ import { queryPlugin } from "../index";
 
 const feature = await loadFeature("../../features/query-plugin.feature");
 
-describeFeature(feature, ({ Scenario }) => {
-  let mock: any;
-  let response: any;
+function isUnknownArray(value: unknown): value is unknown[] {
+  return Array.isArray(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function requireRecord(
+  value: unknown,
+  description: string,
+): Record<string, unknown> {
+  if (!isRecord(value)) {
+    throw new Error(`Expected ${description} to be an object`);
+  }
+  return value;
+}
+
+function requireRecordArray(
+  value: unknown,
+  description: string,
+): Record<string, unknown>[] {
+  if (!isUnknownArray(value)) {
+    throw new Error(`Expected ${description} to be an array`);
+  }
+  return value.map((item) => requireRecord(item, `${description} item`));
+}
+
+function requirePaginatedBody(response: Schmock.Response) {
+  const body = requireRecord(response.body, "paginated response body");
+  return {
+    data: requireRecordArray(body.data, "paginated response data"),
+    pagination: requireRecord(body.pagination, "pagination metadata"),
+  };
+}
+
+describeFeature(feature, ({ Scenario, ScenarioOutline }) => {
+  let mock: Schmock.CallableMockInstance;
+  let response: Schmock.Response;
 
   // Generate test data
   const generateItems = (count: number) =>
-    Array.from({ length: count }, (_, i) => ({ id: i + 1, name: `Item ${i + 1}` }));
+    Array.from({ length: count }, (_, i) => ({
+      id: i + 1,
+      name: `Item ${i + 1}`,
+    }));
 
   const namedItems = [
     { id: 1, name: "Charlie" },
@@ -27,41 +66,51 @@ describeFeature(feature, ({ Scenario }) => {
     { id: 5, name: "Eve", role: "moderator" },
   ];
 
-  Scenario("Basic pagination with default settings", ({ Given, When, Then, And }) => {
-    Given("I create a mock with 25 items and pagination plugin", () => {
-      mock = schmock();
-      mock("GET /items", generateItems(25))
-        .pipe(queryPlugin({
-          pagination: { defaultLimit: 10, maxLimit: 100 },
-        }));
-    });
+  Scenario(
+    "Basic pagination with default settings",
+    ({ Given, When, Then, And }) => {
+      Given("I create a mock with 25 items and pagination plugin", () => {
+        mock = schmock();
+        mock("GET /items", generateItems(25)).pipe(
+          queryPlugin({
+            pagination: { defaultLimit: 10, maxLimit: 100 },
+          }),
+        );
+      });
 
-    When("I request page 1", async () => {
-      response = await mock.handle("GET", "/items", {
-        query: { page: "1" },
+      When("I request page 1", async () => {
+        response = await mock.handle("GET", "/items", {
+          query: { page: "1" },
+        });
       });
-    });
 
-    Then("I should receive {int} items", (_, count: number) => {
-      expect(response.body.data).toHaveLength(count);
-    });
+      Then("I should receive {int} items", (_, count: number) => {
+        expect(requirePaginatedBody(response).data).toHaveLength(count);
+      });
 
-    And("the pagination total should be {int}", (_, total: number) => {
-      expect(response.body.pagination.total).toBe(total);
-    });
+      And("the pagination total should be {int}", (_, total: number) => {
+        expect(requirePaginatedBody(response).pagination.total).toBe(total);
+      });
 
-    And("the pagination totalPages should be {int}", (_, totalPages: number) => {
-      expect(response.body.pagination.totalPages).toBe(totalPages);
-    });
-  });
+      And(
+        "the pagination totalPages should be {int}",
+        (_, totalPages: number) => {
+          expect(requirePaginatedBody(response).pagination.totalPages).toBe(
+            totalPages,
+          );
+        },
+      );
+    },
+  );
 
   Scenario("Pagination with custom limit", ({ Given, When, Then, And }) => {
     Given("I create a mock with 25 items and pagination plugin", () => {
       mock = schmock();
-      mock("GET /items", generateItems(25))
-        .pipe(queryPlugin({
+      mock("GET /items", generateItems(25)).pipe(
+        queryPlugin({
           pagination: { defaultLimit: 10, maxLimit: 100 },
-        }));
+        }),
+      );
     });
 
     When("I request page 1 with limit 5", async () => {
@@ -71,69 +120,87 @@ describeFeature(feature, ({ Scenario }) => {
     });
 
     Then("I should receive {int} items", (_, count: number) => {
-      expect(response.body.data).toHaveLength(count);
+      expect(requirePaginatedBody(response).data).toHaveLength(count);
     });
 
-    And("the pagination totalPages should be {int}", (_, totalPages: number) => {
-      expect(response.body.pagination.totalPages).toBe(totalPages);
-    });
+    And(
+      "the pagination totalPages should be {int}",
+      (_, totalPages: number) => {
+        expect(requirePaginatedBody(response).pagination.totalPages).toBe(
+          totalPages,
+        );
+      },
+    );
   });
 
   Scenario("Sort items ascending by name", ({ Given, When, Then, And }) => {
     Given("I create a mock with named items and sorting plugin", () => {
       mock = schmock();
-      mock("GET /items", namedItems)
-        .pipe(queryPlugin({
+      mock("GET /items", namedItems).pipe(
+        queryPlugin({
           sorting: { allowed: ["name", "id"], default: "id" },
-        }));
+        }),
+      );
     });
 
-    When("I request with sort {string} order {string}", async (_, sort: string, order: string) => {
-      response = await mock.handle("GET", "/items", {
-        query: { sort, order },
-      });
-    });
+    When(
+      "I request with sort {string} order {string}",
+      async (_, sort: string, order: string) => {
+        response = await mock.handle("GET", "/items", {
+          query: { sort, order },
+        });
+      },
+    );
 
     Then("the first item name should be {string}", (_, name: string) => {
-      expect(response.body[0].name).toBe(name);
+      const items = requireRecordArray(response.body, "sorted response body");
+      expect(items.at(0)?.name).toBe(name);
     });
 
     And("the last item name should be {string}", (_, name: string) => {
-      expect(response.body[response.body.length - 1].name).toBe(name);
+      const items = requireRecordArray(response.body, "sorted response body");
+      expect(items.at(-1)?.name).toBe(name);
     });
   });
 
   Scenario("Sort items descending by name", ({ Given, When, Then, And }) => {
     Given("I create a mock with named items and sorting plugin", () => {
       mock = schmock();
-      mock("GET /items", namedItems)
-        .pipe(queryPlugin({
+      mock("GET /items", namedItems).pipe(
+        queryPlugin({
           sorting: { allowed: ["name", "id"], default: "id" },
-        }));
+        }),
+      );
     });
 
-    When("I request with sort {string} order {string}", async (_, sort: string, order: string) => {
-      response = await mock.handle("GET", "/items", {
-        query: { sort, order },
-      });
-    });
+    When(
+      "I request with sort {string} order {string}",
+      async (_, sort: string, order: string) => {
+        response = await mock.handle("GET", "/items", {
+          query: { sort, order },
+        });
+      },
+    );
 
     Then("the first item name should be {string}", (_, name: string) => {
-      expect(response.body[0].name).toBe(name);
+      const items = requireRecordArray(response.body, "sorted response body");
+      expect(items.at(0)?.name).toBe(name);
     });
 
     And("the last item name should be {string}", (_, name: string) => {
-      expect(response.body[response.body.length - 1].name).toBe(name);
+      const items = requireRecordArray(response.body, "sorted response body");
+      expect(items.at(-1)?.name).toBe(name);
     });
   });
 
   Scenario("Filter items by field value", ({ Given, When, Then, And }) => {
     Given("I create a mock with categorized items and filtering plugin", () => {
       mock = schmock();
-      mock("GET /items", categorizedItems)
-        .pipe(queryPlugin({
+      mock("GET /items", categorizedItems).pipe(
+        queryPlugin({
           filtering: { allowed: ["role"] },
-        }));
+        }),
+      );
     });
 
     When("I request with filter role {string}", async (_, role: string) => {
@@ -143,75 +210,153 @@ describeFeature(feature, ({ Scenario }) => {
     });
 
     Then("I should receive {int} filtered items", (_, count: number) => {
-      expect(response.body).toHaveLength(count);
+      expect(
+        requireRecordArray(response.body, "filtered response body"),
+      ).toHaveLength(count);
     });
 
     And("all items should have role {string}", (_, role: string) => {
-      for (const item of response.body) {
+      const items = requireRecordArray(response.body, "filtered response body");
+      for (const item of items) {
         expect(item.role).toBe(role);
       }
     });
   });
 
-  Scenario("Combined pagination, sorting, and filtering", ({ Given, When, Then, And }) => {
-    const users = [
-      { id: 1, name: "Dave", role: "admin" },
-      { id: 2, name: "Alice", role: "user" },
-      { id: 3, name: "Charlie", role: "admin" },
-      { id: 4, name: "Bob", role: "admin" },
-      { id: 5, name: "Eve", role: "user" },
-      { id: 6, name: "Frank", role: "admin" },
-      { id: 7, name: "Grace", role: "user" },
-      { id: 8, name: "Hank", role: "admin" },
-      { id: 9, name: "Ivy", role: "user" },
-      { id: 10, name: "Jack", role: "admin" },
-      { id: 11, name: "Karen", role: "user" },
-      { id: 12, name: "Leo", role: "admin" },
-      { id: 13, name: "Mona", role: "user" },
-      { id: 14, name: "Nate", role: "admin" },
-      { id: 15, name: "Olivia", role: "user" },
-      { id: 16, name: "Paul", role: "admin" },
-      { id: 17, name: "Quinn", role: "user" },
-      { id: 18, name: "Rose", role: "admin" },
-      { id: 19, name: "Sam", role: "user" },
-      { id: 20, name: "Tina", role: "admin" },
-    ];
-
-    Given("I create a mock with 20 users and full query plugin", () => {
-      mock = schmock();
-      mock("GET /users", users)
-        .pipe(queryPlugin({
-          pagination: { defaultLimit: 10, maxLimit: 100 },
-          sorting: { allowed: ["name", "id"] },
-          filtering: { allowed: ["role"] },
-        }));
-    });
+  Scenario(
+    "Combined pagination, sorting, and filtering",
+    ({ Given, When, Then, And }) => {
+      const users = [
+        { id: 1, name: "Dave", role: "admin" },
+        { id: 2, name: "Alice", role: "user" },
+        { id: 3, name: "Charlie", role: "admin" },
+        { id: 4, name: "Bob", role: "admin" },
+        { id: 5, name: "Eve", role: "user" },
+        { id: 6, name: "Frank", role: "admin" },
+        { id: 7, name: "Grace", role: "user" },
+        { id: 8, name: "Hank", role: "admin" },
+        { id: 9, name: "Ivy", role: "user" },
+        { id: 10, name: "Jack", role: "admin" },
+        { id: 11, name: "Karen", role: "user" },
+        { id: 12, name: "Leo", role: "admin" },
+        { id: 13, name: "Mona", role: "user" },
+        { id: 14, name: "Nate", role: "admin" },
+        { id: 15, name: "Olivia", role: "user" },
+        { id: 16, name: "Paul", role: "admin" },
+        { id: 17, name: "Quinn", role: "user" },
+        { id: 18, name: "Rose", role: "admin" },
+        { id: 19, name: "Sam", role: "user" },
+        { id: 20, name: "Tina", role: "admin" },
+      ];
+
+      Given("I create a mock with 20 users and full query plugin", () => {
+        mock = schmock();
+        mock("GET /users", users).pipe(
+          queryPlugin({
+            pagination: { defaultLimit: 10, maxLimit: 100 },
+            sorting: { allowed: ["name", "id"] },
+            filtering: { allowed: ["role"] },
+          }),
+        );
+      });
 
-    When("I request page 1 with limit 2 filter role {string} and sort {string}", async (_, role: string, sort: string) => {
-      response = await mock.handle("GET", "/users", {
-        query: { page: "1", limit: "2", "filter[role]": role, sort },
+      When(
+        "I request page 1 with limit 2 filter role {string} and sort {string}",
+        async (_, role: string, sort: string) => {
+          response = await mock.handle("GET", "/users", {
+            query: { page: "1", limit: "2", "filter[role]": role, sort },
+          });
+        },
+      );
+
+      Then("I should receive {int} items", (_, count: number) => {
+        expect(requirePaginatedBody(response).data).toHaveLength(count);
       });
-    });
 
-    Then("I should receive {int} items", (_, count: number) => {
-      expect(response.body.data).toHaveLength(count);
-    });
+      And("the items should be sorted by name ascending", () => {
+        const names = requirePaginatedBody(response).data.map((item) => {
+          if (typeof item.name !== "string") {
+            throw new Error(
+              "Expected each paginated item to have a string name",
+            );
+          }
+          return item.name;
+        });
+        const sorted = [...names].sort();
+        expect(names).toEqual(sorted);
+      });
 
-    And("the items should be sorted by name ascending", () => {
-      const names = response.body.data.map((item: any) => item.name);
-      const sorted = [...names].sort();
-      expect(names).toEqual(sorted);
-    });
+      And("all items should have role {string}", (_, role: string) => {
+        for (const item of requirePaginatedBody(response).data) {
+          expect(item.role).toBe(role);
+        }
+      });
 
-    And("all items should have role {string}", (_, role: string) => {
-      for (const item of response.body.data) {
-        expect(item.role).toBe(role);
-      }
-    });
+      And("the pagination total should reflect filtered count", () => {
+        // 11 admins in the dataset
+        expect(requirePaginatedBody(response).pagination.total).toBe(11);
+      });
+    },
+  );
+
+  ScenarioOutline(
+    "Paginate array response containers without losing metadata",
+    ({ Given, When, Then, And }, variables) => {
+      Given("I create a mock returning 5 items in a {string} response", () => {
+        mock = schmock();
+        const headers = { "x-query-source": variables.container };
+        if (variables.container === "tuple") {
+          mock(
+            "GET /items",
+            () =>
+              [206, generateItems(5), headers] satisfies [
+                number,
+                unknown,
+                Record<string, string>,
+              ],
+          );
+        } else if (variables.container === "structured") {
+          mock("GET /items", () => ({
+            status: 206,
+            body: generateItems(5),
+            headers,
+          }));
+        } else {
+          throw new Error(
+            `Unsupported query response container: ${variables.container}`,
+          );
+        }
+        mock.pipe(
+          queryPlugin({
+            pagination: { defaultLimit: 10, maxLimit: 100 },
+          }),
+        );
+      });
 
-    And("the pagination total should reflect filtered count", () => {
-      // 11 admins in the dataset
-      expect(response.body.pagination.total).toBe(11);
-    });
-  });
+      When("I request page 2 with limit 2", async () => {
+        response = await mock.handle("GET", "/items", {
+          query: { page: "2", limit: "2" },
+        });
+      });
+
+      Then("the response status should be 206", () => {
+        expect(response.status).toBe(206);
+      });
+
+      And(
+        "response header {string} should be {string}",
+        (_, header: string) => {
+          expect(response.headers[header]).toBe(variables.container);
+        },
+      );
+
+      And("I should receive 2 items", () => {
+        expect(requirePaginatedBody(response).data).toHaveLength(2);
+      });
+
+      And("the pagination total should be 5", () => {
+        expect(requirePaginatedBody(response).pagination.total).toBe(5);
+      });
+    },
+  );
 });