@sdk-it/spec 0.22.0 → 0.23.0

package/dist/lib/pagination/pagination.js

@@ -0,0 +1,222 @@
+import { isRef } from "@sdk-it/core/ref.js";
+import { isEmpty } from "@sdk-it/core/utils.js";
+import { getHasMoreName, getItemsName } from "./pagination-result.js";
+const OFFSET_PARAM_REGEXES = [
+  /\boffset\b/i,
+  /\bskip\b/i,
+  /\bstart(?:ing_at|_index)?\b/i,
+  // e.g., start, starting_at, start_index
+  /\bfrom\b/i
+];
+const GENERIC_LIMIT_PARAM_REGEXES = [
+  /\blimit\b/i,
+  /\bcount\b/i,
+  /\b(?:page_?)?size\b/i,
+  // e.g., size, page_size, pagesize
+  /\bmax_results\b/i,
+  /\bnum_results\b/i,
+  /\bshow\b/i,
+  // Can sometimes mean limit
+  /\bper_?page\b/i,
+  // e.g., per_page, perpage
+  /\bper-page\b/i,
+  /\btake\b/i
+];
+const PAGE_NUMBER_REGEXES = [
+  // /^(currentPage)?page$/i, // Exact match for "page"
+  // /^currentPage$/i, // Exact match for "currentPage"
+  /^p$/i,
+  // Exact match for "p" (common shorthand)
+  // /\bpage_?(?:number|no|num|idx|index)\b/i, // e.g., page_number, pageNumber, page_num, page_idx
+  /^(current)?_?page(_?)(?:number|no|num|idx|index)?\b/i
+];
+const PAGE_SIZE_REGEXES = [
+  /\bpage_?size\b/i,
+  // e.g., page_size, pagesize
+  /^size$/i,
+  // Exact "size"
+  // /\bsize\b/i, // Broader "size" - can be ambiguous, prefer more specific ones first
+  /\blimit\b/i,
+  // Limit is often used for page size
+  /\bcount\b/i,
+  // Count can also be used for page size
+  /\bper_?page\b/i,
+  // e.g., per_page, perpage
+  /\bper-page\b/i,
+  /\bnum_?(?:items|records|results)\b/i,
+  // e.g., num_items, numitems
+  /\bresults_?per_?page\b/i
+];
+const CURSOR_REGEXES = [
+  /\bmarker\b/i,
+  /\bcursor\b/i,
+  /\bafter(?:_?cursor)?\b/i,
+  // e.g., after, after_cursor
+  /\bbefore(?:_?cursor)?\b/i,
+  // e.g., before, before_cursor
+  /\b(next|prev|previous)_?(?:page_?)?token\b/i,
+  // e.g., next_page_token, nextPageToken, prev_token
+  /\b(next|prev|previous)_?cursor\b/i,
+  // e.g., next_cursor, previousCursor
+  /\bcontinuation(?:_?token)?\b/i,
+  // e.g., continuation, continuation_token
+  /\bpage(?:_?(token|id))?\b/i,
+  // e.g., after, after_cursor
+  /\bstart_?(?:key|cursor|token|after)\b/i
+  // e.g., start_key, startCursor, startToken, startAfter
+];
+const CURSOR_LIMIT_REGEXES = [
+  /\blimit\b/i,
+  /\bcount\b/i,
+  /\bsize\b/i,
+  // General size
+  /\bfirst\b/i,
+  // Common in Relay-style cursor pagination (forward pagination)
+  /\blast\b/i,
+  // Common in Relay-style cursor pagination (backward pagination)
+  /\bpage_?size\b/i,
+  // Sometimes page_size is used with cursors
+  /\bnum_?(?:items|records|results)\b/i,
+  // e.g., num_items
+  /\bmax_?items\b/i,
+  /\btake\b/i
+];
+function findParamAndKeyword(queryParams, regexes, excludeParamName) {
+  for (const param of queryParams) {
+    if (param.name === excludeParamName) {
+      continue;
+    }
+    for (const regex of regexes) {
+      const match = param.name.match(regex);
+      if (match) {
+        return { param, keyword: match[0] };
+      }
+    }
+  }
+  return null;
+}
+function coearceParameters(parameters) {
+  const cleanedParameters = [];
+  for (const param of parameters) {
+    if (!param.schema) {
+      continue;
+    }
+    if (isRef(param.schema)) {
+      continue;
+    }
+    if (!param.schema.type) {
+      continue;
+    }
+    if (param.schema) {
+      cleanedParameters.push({
+        ...param,
+        schema: {
+          ...param.schema,
+          type: Array.isArray(param.schema.type) ? param.schema.type : [param.schema.type]
+        }
+      });
+    }
+  }
+  return cleanedParameters;
+}
+function isOffsetPagination(operation, parameters) {
+  const params = coearceParameters(parameters).filter(
+    (it) => it.schema.type.includes("integer") || it.schema.type.includes("number")
+  );
+  const offsetMatch = findParamAndKeyword(params, OFFSET_PARAM_REGEXES);
+  if (!offsetMatch) return null;
+  const limitMatch = findParamAndKeyword(
+    params,
+    GENERIC_LIMIT_PARAM_REGEXES,
+    offsetMatch.param.name
+  );
+  if (!limitMatch) return null;
+  return {
+    type: "offset",
+    offsetParamName: offsetMatch.param.name,
+    offsetKeyword: offsetMatch.keyword,
+    limitParamName: limitMatch.param.name,
+    limitKeyword: limitMatch.keyword
+  };
+}
+function isPagePagination(operation, parameters) {
+  const params = coearceParameters(parameters).filter(
+    (it) => it.schema.type.includes("integer") || it.schema.type.includes("number")
+  );
+  if (params.length < 2) return null;
+  const pageNoMatch = findParamAndKeyword(params, PAGE_NUMBER_REGEXES);
+  if (!pageNoMatch) return null;
+  const pageSizeMatch = findParamAndKeyword(
+    params,
+    PAGE_SIZE_REGEXES,
+    pageNoMatch.param.name
+  );
+  if (!pageSizeMatch) return null;
+  return {
+    type: "page",
+    pageNumberParamName: pageNoMatch.param.name,
+    pageNumberKeyword: pageNoMatch.keyword,
+    pageSizeParamName: pageSizeMatch.param.name,
+    pageSizeKeyword: pageSizeMatch.keyword
+  };
+}
+function isCursorPagination(operation, parameters = []) {
+  const queryParams = parameters;
+  if (queryParams.length < 2) return null;
+  const cursorMatch = findParamAndKeyword(queryParams, CURSOR_REGEXES);
+  if (!cursorMatch) return null;
+  const limitMatch = findParamAndKeyword(
+    queryParams,
+    CURSOR_LIMIT_REGEXES,
+    cursorMatch.param.name
+  );
+  if (!limitMatch) return null;
+  return {
+    type: "cursor",
+    cursorParamName: cursorMatch.param.name,
+    cursorKeyword: cursorMatch.keyword,
+    limitParamName: limitMatch.param.name,
+    limitKeyword: limitMatch.keyword
+  };
+}
+function guessPagination(operation, body, response) {
+  const bodyParameters = body && body.properties ? Object.entries(body.properties).map(([it, schema]) => ({
+    name: it,
+    schema
+  })) : [];
+  const parameters = operation.parameters;
+  if (isEmpty(operation.parameters) && isEmpty(bodyParameters)) {
+    return { type: "none", reason: "no parameters" };
+  }
+  if (!response) {
+    return { type: "none", reason: "no response" };
+  }
+  if (!response.properties) {
+    return { type: "none", reason: "empty response" };
+  }
+  const properties = response.properties;
+  const itemsKey = getItemsName(properties);
+  if (!itemsKey) {
+    return { type: "none", reason: "no items key" };
+  }
+  const hasMoreKey = getHasMoreName(excludeKey(properties, itemsKey));
+  if (!hasMoreKey) {
+    return { type: "none", reason: "no hasMore key" };
+  }
+  const pagination = isOffsetPagination(operation, [...parameters, ...bodyParameters]) || isPagePagination(operation, [...parameters, ...bodyParameters]) || isCursorPagination(operation, [...parameters, ...bodyParameters]);
+  return pagination ? { ...pagination, items: itemsKey, hasMore: hasMoreKey } : { type: "none", reason: "no pagination" };
+}
+function excludeKey(obj, key) {
+  const { [key]: _, ...rest } = obj;
+  return rest;
+}
+export {
+  CURSOR_LIMIT_REGEXES,
+  CURSOR_REGEXES,
+  GENERIC_LIMIT_PARAM_REGEXES,
+  OFFSET_PARAM_REGEXES,
+  PAGE_NUMBER_REGEXES,
+  PAGE_SIZE_REGEXES,
+  guessPagination
+};
+//# sourceMappingURL=pagination.js.map

package/dist/lib/pagination/pagination.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/pagination/pagination.ts"],
+  "sourcesContent": ["import type {\n  ReferenceObject,\n  SchemaObject,\n  SchemasObject,\n} from 'openapi3-ts/oas31';\n\nimport { isRef } from '@sdk-it/core/ref.js';\nimport { isEmpty } from '@sdk-it/core/utils.js';\n\nimport type { TunedOperationObject } from '../types.js';\nimport { getHasMoreName, getItemsName } from './pagination-result.js';\n\ninterface PaginationResultBase {\n  type: 'offset' | 'page' | 'cursor' | 'none';\n}\n\nexport interface OffsetPaginationResult extends PaginationResultBase {\n  type: 'offset';\n  offsetParamName: string;\n  offsetKeyword: string; // The actual part of param name that matched\n  limitParamName: string;\n  limitKeyword: string; // The actual part of param name that matched\n}\n\nexport interface PagePaginationResult extends PaginationResultBase {\n  type: 'page';\n  pageNumberParamName: string;\n  pageNumberKeyword: string;\n  pageSizeParamName: string;\n  pageSizeKeyword: string;\n}\n\nexport interface CursorPaginationResult extends PaginationResultBase {\n  type: 'cursor';\n  cursorParamName: string;\n  cursorKeyword: string;\n  limitParamName: string;\n  limitKeyword: string;\n}\n\nexport interface NoPaginationResult extends PaginationResultBase {\n  type: 'none';\n  reason: string;\n}\n\nexport type PaginationGuess =\n  | ((\n      | OffsetPaginationResult\n      | PagePaginationResult\n      | CursorPaginationResult\n    ) & { items: string; hasMore: string })\n  | NoPaginationResult;\n\n// --- Keyword Regex Definitions ---\n\nexport const OFFSET_PARAM_REGEXES: RegExp[] = [\n  /\\boffset\\b/i,\n  /\\bskip\\b/i,\n  /\\bstart(?:ing_at|_index)?\\b/i, // e.g., start, starting_at, start_index\n  /\\bfrom\\b/i,\n];\n\nexport const GENERIC_LIMIT_PARAM_REGEXES: RegExp[] = [\n  /\\blimit\\b/i,\n  /\\bcount\\b/i,\n  /\\b(?:page_?)?size\\b/i, // e.g., size, page_size, pagesize\n  /\\bmax_results\\b/i,\n  /\\bnum_results\\b/i,\n  /\\bshow\\b/i, // Can sometimes mean limit\n  /\\bper_?page\\b/i, // e.g., per_page, perpage\n  /\\bper-page\\b/i,\n  /\\btake\\b/i,\n];\n\nexport const PAGE_NUMBER_REGEXES: RegExp[] = [\n  // /^(currentPage)?page$/i, // Exact match for \"page\"\n  // /^currentPage$/i, // Exact match for \"currentPage\"\n  /^p$/i, // Exact match for \"p\" (common shorthand)\n  // /\\bpage_?(?:number|no|num|idx|index)\\b/i, // e.g., page_number, pageNumber, page_num, page_idx\n  /^(current)?_?page(_?)(?:number|no|num|idx|index)?\\b/i,\n];\n\n// Regexes for parameters indicating page size (when used with page number)\nexport const PAGE_SIZE_REGEXES: RegExp[] = [\n  /\\bpage_?size\\b/i, // e.g., page_size, pagesize\n  /^size$/i, // Exact \"size\"\n  // /\\bsize\\b/i, // Broader \"size\" - can be ambiguous, prefer more specific ones first\n  /\\blimit\\b/i, // Limit is often used for page size\n  /\\bcount\\b/i, // Count can also be used for page size\n  /\\bper_?page\\b/i, // e.g., per_page, perpage\n  /\\bper-page\\b/i,\n  /\\bnum_?(?:items|records|results)\\b/i, // e.g., num_items, numitems\n  /\\bresults_?per_?page\\b/i,\n];\n\n// Regexes for parameters indicating a cursor\nexport const CURSOR_REGEXES: RegExp[] = [\n  /\\bmarker\\b/i,\n  /\\bcursor\\b/i,\n  /\\bafter(?:_?cursor)?\\b/i, // e.g., after, after_cursor\n  /\\bbefore(?:_?cursor)?\\b/i, // e.g., before, before_cursor\n  /\\b(next|prev|previous)_?(?:page_?)?token\\b/i, // e.g., next_page_token, nextPageToken, prev_token\n  /\\b(next|prev|previous)_?cursor\\b/i, // e.g., next_cursor, previousCursor\n  /\\bcontinuation(?:_?token)?\\b/i, // e.g., continuation, continuation_token\n  /\\bpage(?:_?(token|id))?\\b/i, // e.g., after, after_cursor\n\n  /\\bstart_?(?:key|cursor|token|after)\\b/i, // e.g., start_key, startCursor, startToken, startAfter\n];\n\n// Regexes for parameters indicating a limit when used with cursors\nexport const CURSOR_LIMIT_REGEXES: RegExp[] = [\n  /\\blimit\\b/i,\n  /\\bcount\\b/i,\n  /\\bsize\\b/i, // General size\n  /\\bfirst\\b/i, // Common in Relay-style cursor pagination (forward pagination)\n  /\\blast\\b/i, // Common in Relay-style cursor pagination (backward pagination)\n  /\\bpage_?size\\b/i, // Sometimes page_size is used with cursors\n  /\\bnum_?(?:items|records|results)\\b/i, // e.g., num_items\n  /\\bmax_?items\\b/i,\n  /\\btake\\b/i,\n];\n\n// --- Helper Function ---\nfunction findParamAndKeyword(\n  queryParams: { name: string }[],\n  regexes: RegExp[],\n  excludeParamName?: string,\n) {\n  for (const param of queryParams) {\n    if (param.name === excludeParamName) {\n      continue;\n    }\n    for (const regex of regexes) {\n      const match = param.name.match(regex);\n      if (match) {\n        return { param, keyword: match[0] }; // match[0] is the actual matched substring\n      }\n    }\n  }\n  return null;\n}\n\nfunction coearceParameters(\n  parameters: { name: string; schema?: SchemaObject | ReferenceObject }[],\n) {\n  const cleanedParameters: {\n    name: string;\n    schema: Omit<SchemaObject, 'type'> & {\n      type: string[]; // Ensure type is always an array\n    };\n  }[] = [];\n  for (const param of parameters) {\n    if (!param.schema) {\n      continue;\n    }\n    if (isRef(param.schema)) {\n      continue;\n    }\n    if (!param.schema.type) {\n      continue;\n    }\n    if (param.schema) {\n      cleanedParameters.push({\n        ...param,\n        schema: {\n          ...param.schema,\n          type: Array.isArray(param.schema.type)\n            ? param.schema.type\n            : [param.schema.type],\n        },\n      });\n    }\n  }\n  return cleanedParameters;\n}\n\nfunction isOffsetPagination(\n  operation: TunedOperationObject,\n  parameters: { name: string; schema?: SchemaObject | ReferenceObject }[],\n): OffsetPaginationResult | null {\n  const params = coearceParameters(parameters).filter(\n    (it) =>\n      it.schema.type.includes('integer') || it.schema.type.includes('number'),\n  );\n  const offsetMatch = findParamAndKeyword(params, OFFSET_PARAM_REGEXES);\n\n  if (!offsetMatch) return null;\n\n  const limitMatch = findParamAndKeyword(\n    params,\n    GENERIC_LIMIT_PARAM_REGEXES,\n    offsetMatch.param.name,\n  );\n  if (!limitMatch) return null;\n\n  return {\n    type: 'offset',\n    offsetParamName: offsetMatch.param.name,\n    offsetKeyword: offsetMatch.keyword,\n    limitParamName: limitMatch.param.name,\n    limitKeyword: limitMatch.keyword,\n  };\n}\n\nfunction isPagePagination(\n  operation: TunedOperationObject,\n  parameters: { name: string; schema?: SchemaObject | ReferenceObject }[],\n): PagePaginationResult | null {\n  const params = coearceParameters(parameters).filter(\n    (it) =>\n      it.schema.type.includes('integer') || it.schema.type.includes('number'),\n  );\n\n  if (params.length < 2) return null;\n\n  const pageNoMatch = findParamAndKeyword(params, PAGE_NUMBER_REGEXES);\n  if (!pageNoMatch) return null;\n\n  const pageSizeMatch = findParamAndKeyword(\n    params,\n    PAGE_SIZE_REGEXES,\n    pageNoMatch.param.name,\n  );\n  if (!pageSizeMatch) return null;\n\n  return {\n    type: 'page',\n    pageNumberParamName: pageNoMatch.param.name,\n    pageNumberKeyword: pageNoMatch.keyword,\n    pageSizeParamName: pageSizeMatch.param.name,\n    pageSizeKeyword: pageSizeMatch.keyword,\n  };\n}\n\nfunction isCursorPagination(\n  operation: TunedOperationObject,\n  parameters: { name: string; schema?: SchemaObject | ReferenceObject }[] = [],\n): CursorPaginationResult | null {\n  const queryParams = parameters;\n  if (queryParams.length < 2) return null; // Need at least a cursor and a limit-like param\n\n  const cursorMatch = findParamAndKeyword(queryParams, CURSOR_REGEXES);\n  if (!cursorMatch) return null;\n\n  const limitMatch = findParamAndKeyword(\n    queryParams,\n    CURSOR_LIMIT_REGEXES,\n    cursorMatch.param.name,\n  );\n  if (!limitMatch) return null;\n\n  return {\n    type: 'cursor',\n    cursorParamName: cursorMatch.param.name,\n    cursorKeyword: cursorMatch.keyword,\n    limitParamName: limitMatch.param.name,\n    limitKeyword: limitMatch.keyword,\n  };\n}\n\n/**\n * Guesses the pagination strategy of an OpenAPI operation based on its query parameters.\n * It checks for offset, page-based, and cursor-based pagination in that order.\n *\n * @param operation The OpenAPI operation object.\n * @returns A PaginationGuess object indicating the detected type and relevant parameters.\n */\nexport function guessPagination(\n  operation: TunedOperationObject,\n  body?: SchemaObject,\n  response?: SchemaObject,\n): PaginationGuess {\n  const bodyParameters =\n    body && body.properties\n      ? Object.entries(body.properties).map(([it, schema]) => ({\n          name: it,\n          schema,\n        }))\n      : [];\n  const parameters = operation.parameters;\n\n  if (isEmpty(operation.parameters) && isEmpty(bodyParameters)) {\n    return { type: 'none', reason: 'no parameters' };\n  }\n  if (!response) {\n    return { type: 'none', reason: 'no response' };\n  }\n  if (!response.properties) {\n    return { type: 'none', reason: 'empty response' };\n  }\n  const properties = response.properties as SchemasObject;\n\n  const itemsKey = getItemsName(properties);\n  if (!itemsKey) {\n    return { type: 'none', reason: 'no items key' };\n  }\n  const hasMoreKey = getHasMoreName(excludeKey(properties, itemsKey));\n\n  if (!hasMoreKey) {\n    return { type: 'none', reason: 'no hasMore key' };\n  }\n  const pagination =\n    isOffsetPagination(operation, [...parameters, ...bodyParameters]) ||\n    isPagePagination(operation, [...parameters, ...bodyParameters]) ||\n    isCursorPagination(operation, [...parameters, ...bodyParameters]);\n  return pagination\n    ? { ...pagination, items: itemsKey, hasMore: hasMoreKey }\n    : { type: 'none', reason: 'no pagination' };\n}\n\nfunction excludeKey<T extends Record<string, any>>(\n  obj: T,\n  key: string,\n): Omit<T, typeof key> {\n  const { [key]: _, ...rest } = obj;\n  return rest;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/pagination/pagination.test.js

@@ -0,0 +1,378 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import {
+  CURSOR_LIMIT_REGEXES,
+  CURSOR_REGEXES,
+  GENERIC_LIMIT_PARAM_REGEXES,
+  OFFSET_PARAM_REGEXES,
+  PAGE_NUMBER_REGEXES,
+  PAGE_SIZE_REGEXES,
+  guessPagination
+} from "./pagination.ts";
+function createOperation(params) {
+  return {
+    tags: ["test"],
+    operationId: "testOperation",
+    parameters: params,
+    requestBody: { content: {} },
+    responses: {}
+  };
+}
+function qParam(name) {
+  return {
+    name,
+    in: "query",
+    required: false,
+    schema: {
+      type: "string"
+    }
+  };
+}
+function hParam(name) {
+  return {
+    name,
+    in: "header",
+    required: false,
+    schema: {
+      type: "string"
+    }
+  };
+}
+function pParam(name) {
+  return {
+    name,
+    in: "path",
+    required: false,
+    schema: {
+      type: "string"
+    }
+  };
+}
+function getExpectedKeyword(paramName, regexArray) {
+  for (const regex of regexArray) {
+    const match = paramName.match(regex);
+    if (match) {
+      return match[0];
+    }
+  }
+  return paramName;
+}
+describe("guessPagination()", () => {
+  describe("No Pagination Detected", () => {
+    test('should return "none" for an operation with an empty parameters array', () => {
+      const op = createOperation([]);
+      assert.deepStrictEqual(guessPagination(op), { type: "none" });
+    });
+    test('should return "none" for an operation with undefined parameters', () => {
+      const op = createOperation(void 0);
+      assert.deepStrictEqual(guessPagination(op), { type: "none" });
+    });
+    test('should return "none" for non-pagination query parameters', () => {
+      const op = createOperation([qParam("search"), qParam("filterBy")]);
+      assert.deepStrictEqual(guessPagination(op), { type: "none" });
+    });
+    test('should return "none" if relevant parameters are not in "query"', () => {
+      const op = createOperation([hParam("offset"), hParam("limit")]);
+      assert.deepStrictEqual(guessPagination(op), { type: "none" });
+    });
+    test('should return "none" if only one part of a pair is present (e.g., only offset)', () => {
+      assert.deepStrictEqual(
+        guessPagination(createOperation([qParam("offset")])),
+        { type: "none" },
+        "Only offset"
+      );
+      assert.deepStrictEqual(
+        guessPagination(createOperation([qParam("page")])),
+        { type: "none" },
+        "Only page"
+      );
+      assert.deepStrictEqual(
+        guessPagination(createOperation([qParam("cursor")])),
+        { type: "none" },
+        "Only cursor"
+      );
+      assert.deepStrictEqual(
+        guessPagination(createOperation([qParam("limit")])),
+        { type: "none" },
+        "Only limit"
+      );
+    });
+    test('should return "none" for mixed non-query and insufficient query params', () => {
+      const op = createOperation([
+        pParam("userId"),
+        qParam("offset"),
+        hParam("X-Request-ID")
+      ]);
+      assert.deepStrictEqual(guessPagination(op), { type: "none" });
+    });
+  });
+  describe("Offset Pagination Detection", () => {
+    const testOffsetKeywords = [
+      "offset",
+      "skip",
+      "start",
+      "start_index",
+      "starting_at",
+      "from",
+      "Offset",
+      "SKIP"
+    ];
+    const testLimitKeywords = [
+      "limit",
+      "count",
+      "size",
+      "page_size",
+      "pageSize",
+      "max_results",
+      "take",
+      "Limit",
+      "COUNT"
+    ];
+    for (const offsetKey of testOffsetKeywords) {
+      for (const limitKey of testLimitKeywords) {
+        if (offsetKey.toLowerCase() === limitKey.toLowerCase()) continue;
+        test(`should detect offset with "${offsetKey}" and "${limitKey}"`, () => {
+          const op = createOperation([qParam(offsetKey), qParam(limitKey)]);
+          const result = guessPagination(op);
+          assert.strictEqual(
+            result.type,
+            "offset",
+            `Failed for ${offsetKey}, ${limitKey}`
+          );
+          assert.strictEqual(result.offsetParamName, offsetKey);
+          assert.strictEqual(
+            result.offsetKeyword,
+            getExpectedKeyword(offsetKey, OFFSET_PARAM_REGEXES)
+          );
+          assert.strictEqual(result.limitParamName, limitKey);
+          assert.strictEqual(
+            result.limitKeyword,
+            getExpectedKeyword(limitKey, GENERIC_LIMIT_PARAM_REGEXES)
+          );
+        });
+      }
+    }
+    test("should not detect offset if one param is not in query", () => {
+      const op = createOperation([hParam("offset"), qParam("limit")]);
+      assert.deepStrictEqual(guessPagination(op), { type: "none" });
+    });
+    test("should not detect with two offset-like params and no limit", () => {
+      const op = createOperation([qParam("offset"), qParam("skip")]);
+      assert.deepStrictEqual(guessPagination(op), { type: "none" });
+    });
+    test("should correctly handle params in different order", () => {
+      const op = createOperation([qParam("limit"), qParam("offset")]);
+      const result = guessPagination(op);
+      assert.strictEqual(result.type, "offset");
+      assert.strictEqual(result.offsetParamName, "offset");
+      assert.strictEqual(result.limitParamName, "limit");
+    });
+    test("should handle extra non-pagination params", () => {
+      const op = createOperation([
+        qParam("filter"),
+        qParam("offset"),
+        qParam("sort"),
+        qParam("limit")
+      ]);
+      const result = guessPagination(op);
+      assert.strictEqual(result.type, "offset");
+      assert.strictEqual(result.offsetParamName, "offset");
+      assert.strictEqual(result.limitParamName, "limit");
+    });
+  });
+  describe("Page Pagination Detection", () => {
+    const testPageNumKeywords = [
+      "page",
+      "p",
+      "page_number",
+      "pageNum",
+      "page_idx",
+      "Page",
+      "P"
+    ];
+    const testPageSizeKeywords = [
+      "page_size",
+      "pageSize",
+      "size",
+      "limit",
+      "count",
+      "per_page",
+      "per-page",
+      "num_items",
+      "Size",
+      "LIMIT"
+    ];
+    for (const pageKey of testPageNumKeywords) {
+      for (const sizeKey of testPageSizeKeywords) {
+        if (pageKey.toLowerCase() === sizeKey.toLowerCase()) continue;
+        test(`should detect page with "${pageKey}" and "${sizeKey}"`, () => {
+          const op = createOperation([qParam(pageKey), qParam(sizeKey)]);
+          const result = guessPagination(op);
+          assert.strictEqual(
+            result.type,
+            "page",
+            `Failed for ${pageKey}, ${sizeKey}`
+          );
+          assert.strictEqual(result.pageNumberParamName, pageKey);
+          assert.strictEqual(
+            result.pageNumberKeyword,
+            getExpectedKeyword(pageKey, PAGE_NUMBER_REGEXES)
+          );
+          assert.strictEqual(result.pageSizeParamName, sizeKey);
+          assert.strictEqual(
+            result.pageSizeKeyword,
+            getExpectedKeyword(sizeKey, PAGE_SIZE_REGEXES)
+          );
+        });
+      }
+    }
+    test("should not detect page if one param is not in query", () => {
+      const op = createOperation([hParam("page"), qParam("size")]);
+      assert.deepStrictEqual(guessPagination(op), { type: "none" });
+    });
+    test("should not detect with two page-number-like params and no size", () => {
+      const op = createOperation([qParam("page"), qParam("page_number")]);
+      assert.deepStrictEqual(guessPagination(op), { type: "none" });
+    });
+  });
+  describe("Cursor Pagination Detection", () => {
+    const testCursorKeywords = [
+      "cursor",
+      "after",
+      "before_cursor",
+      "next_page_token",
+      "pageToken",
+      "continuation_token",
+      "Cursor",
+      "AFTER"
+    ];
+    const testCursorLimitKeywords = [
+      "limit",
+      "count",
+      "size",
+      "first",
+      "last",
+      "page_size",
+      "num_items",
+      "take",
+      "First",
+      "LAST"
+    ];
+    for (const cursorKey of testCursorKeywords) {
+      for (const limitKey of testCursorLimitKeywords) {
+        if (cursorKey.toLowerCase() === limitKey.toLowerCase()) continue;
+        test(`should detect cursor with "${cursorKey}" and "${limitKey}"`, () => {
+          const op = createOperation([qParam(cursorKey), qParam(limitKey)]);
+          const result = guessPagination(op);
+          assert.strictEqual(
+            result.type,
+            "cursor",
+            `Failed for ${cursorKey}, ${limitKey}`
+          );
+          assert.strictEqual(result.cursorParamName, cursorKey);
+          assert.strictEqual(
+            result.cursorKeyword,
+            getExpectedKeyword(cursorKey, CURSOR_REGEXES)
+          );
+          assert.strictEqual(result.limitParamName, limitKey);
+          assert.strictEqual(
+            result.limitKeyword,
+            getExpectedKeyword(limitKey, CURSOR_LIMIT_REGEXES)
+          );
+        });
+      }
+    }
+    test("should not detect cursor if one param is not in query", () => {
+      const op = createOperation([hParam("cursor"), qParam("first")]);
+      assert.deepStrictEqual(guessPagination(op), { type: "none" });
+    });
+    test("should not detect with two cursor-like params and no limit", () => {
+      const op = createOperation([qParam("cursor"), qParam("after")]);
+      assert.deepStrictEqual(guessPagination(op), { type: "none" });
+    });
+  });
+  describe("Pagination Type Precedence", () => {
+    test('Offset should take precedence over Page (e.g., "skip", "limit", "page")', () => {
+      const op = createOperation([
+        qParam("skip"),
+        qParam("limit"),
+        qParam("page")
+      ]);
+      const result = guessPagination(op);
+      assert.strictEqual(result.type, "offset");
+      if (result.type === "offset") {
+        assert.strictEqual(result.offsetParamName, "skip");
+        assert.strictEqual(result.limitParamName, "limit");
+      }
+    });
+    test('Offset should take precedence over Cursor (e.g., "offset", "count", "after_token")', () => {
+      const op = createOperation([
+        qParam("offset"),
+        qParam("count"),
+        qParam("after_token")
+      ]);
+      const result = guessPagination(op);
+      assert.strictEqual(result.type, "offset");
+      if (result.type === "offset") {
+        assert.strictEqual(result.offsetParamName, "offset");
+        assert.strictEqual(result.limitParamName, "count");
+      }
+    });
+    test('Page should take precedence over Cursor (e.g., "page", "size", "next_cursor")', () => {
+      const op = createOperation([
+        qParam("page"),
+        qParam("size"),
+        qParam("next_cursor")
+      ]);
+      const result = guessPagination(op);
+      assert.strictEqual(result.type, "page");
+      if (result.type === "page") {
+        assert.strictEqual(result.pageNumberParamName, "page");
+        assert.strictEqual(result.pageSizeParamName, "size");
+      }
+    });
+    test('Params like "page" and "limit" should resolve to Page pagination', () => {
+      const op = createOperation([qParam("page"), qParam("limit")]);
+      const result = guessPagination(op);
+      assert.strictEqual(result.type, "page");
+      if (result.type === "page") {
+        assert.strictEqual(result.pageNumberParamName, "page");
+        assert.strictEqual(result.pageSizeParamName, "limit");
+      }
+    });
+  });
+  describe("Regex Specificity and Word Boundaries", () => {
+    test('should not match "custom_offset" as "offset" due to word boundary (with real implementation)', () => {
+      const op = createOperation([
+        qParam("custom_offset_param"),
+        qParam("limit")
+      ]);
+      assert.ok(
+        true,
+        "Test needs real implementation for accurate regex boundary check"
+      );
+    });
+    test('should match "offset_custom" for "offset" keyword (with real implementation)', () => {
+      const op = createOperation([qParam("offset_custom"), qParam("limit")]);
+      assert.ok(
+        true,
+        "Test needs real implementation for accurate keyword extraction"
+      );
+    });
+    test('should match "page" exactly for page number, not "my_page_details" (with real implementation)', () => {
+      const op = createOperation([qParam("my_page_details"), qParam("size")]);
+      assert.ok(
+        true,
+        "Test needs real implementation for exact regex matching"
+      );
+    });
+    test('should match "p" exactly for page number (with real implementation)', () => {
+      const op = createOperation([qParam("p"), qParam("size")]);
+      assert.ok(
+        true,
+        "Test needs real implementation for exact regex matching"
+      );
+    });
+  });
+});
+//# sourceMappingURL=pagination.test.js.map