@flanksource/clicky-ui 0.3.36 → 0.3.37

package/dist/rpc/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sources":["../../src/rpc/types.ts"],"sourcesContent":["import type { ClickyNode } from \"../data/Clicky\";\nimport type { TimeRangePresetGroup } from \"../components/TimeRange\";\n\nexport type OperationRequestValues = Record<string, string | string[]>;\n\nexport interface ExecutionRequest {\n  args?: string[];\n  flags?: OperationRequestValues;\n}\n\nexport interface ExecutionPagination {\n  total?: number;\n  limit?: number;\n  offset?: number;\n\n  // totalRelation says whether total is a count or a lower bound. A backend\n  // that stops counting past a threshold reports \"gte\", and rendering that as\n  // a count would state a number nobody promised.\n  totalRelation?: \"eq\" | \"gte\";\n\n  // hasMore is the server's answer, not an inference from the page length: a\n  // short page and the end of the data are different facts.\n  hasMore?: boolean;\n\n  // nextCursor resumes after this page. Opaque — it is passed back unchanged\n  // and never parsed, because a client that can read one can forge one.\n  nextCursor?: string;\n\n  // truncated reports that the server stopped short of the whole result, so a\n  // partial answer is never rendered as a complete one.\n  truncated?: boolean;\n}\n\nexport interface ExecutionResponse {\n  success: boolean;\n  message?: string;\n  output?: string;\n  stdout?: string;\n  stderr?: string;\n  exit_code: number;\n  error?: string;\n  cli?: string;\n  input?: ExecutionRequest;\n  contentType?: string;\n  requestUrl?: string;\n  responseHeaders?: Record<string, string>;\n  pagination?: ExecutionPagination;\n  blob?: Blob;\n  parsed?: unknown;\n}\n\nexport interface OpenAPISchema {\n  type?: string;\n  format?: string;\n  default?: unknown;\n  enum?: unknown[];\n  description?: string;\n  properties?: Record<string, OpenAPISchema>;\n  items?: OpenAPISchema;\n  oneOf?: OpenAPISchema[];\n  additionalProperties?: OpenAPISchema | boolean;\n  nullable?: boolean;\n}\n\n// ClickyParameterRole tells the UI which widget owns a parameter:\n//   \"search\"    — render as the FilterBar's dedicated search input\n//   \"filter\"    — render as a FilterBar chip on the DataTable\n//   \"limit\"     — feed into DataTable pagination's pageSize\n//   \"offset\"    — feed into DataTable pagination's page (or skip)\n//   \"cursor\"    — carry the opaque position the previous page returned\n//   \"sort\"      — select a public server-side sort key from a table header\n//   \"order\"     — carry that sort's asc/desc direction\n//   \"time-from\" — left edge of a time-range picker\n//   \"time-to\"   — right edge of a time-range picker\n// Set server-side by clicky's converter (see paramRole in clicky/rpc/openapi.go).\nexport type ClickyParameterRole =\n  | \"search\"\n  | \"filter\"\n  | \"limit\"\n  | \"offset\"\n  | \"cursor\"\n  | \"sort\"\n  | \"order\"\n  | \"time-from\"\n  | \"time-to\";\n\nexport interface ClickyParameterMeta {\n  role?: ClickyParameterRole;\n}\n\n/**\n * A parameter's pointer to its filter control, set server-side.\n *\n * `$ref` names the control's SHAPE — which control this is — and is present on\n * every generated filter, because a control's identity never varies with the\n * values currently selected. `url`/`filter`/`searchParam` are the separate\n * question of where its OPTIONS come from, and are present only when the\n * backend can enumerate them: a range has no list to offer.\n */\nexport interface ClickyParameterLookup {\n  /** JSON pointer into `components[\"x-clicky-filters\"]`. */\n  $ref?: string;\n  url?: string;\n  filter?: string;\n  searchParam?: string;\n  multi?: boolean;\n}\n\n/**\n * One entry of `components[\"x-clicky-filters\"]`: a filter control's shape,\n * published once per spec and invariant for the life of it.\n *\n * Distinct from OperationLookupFilter, which is the per-request answer to \"what\n * values can this filter take right now\" and may legitimately narrow as other\n * filters are selected. Reading shape from here rather than from a lookup\n * response is what keeps a control from decaying into a text box while its\n * options are in flight.\n */\nexport interface ClickyFilterShape {\n  label?: string;\n  type?: OperationLookupFilterType;\n  multi?: boolean;\n}\n\nexport interface OpenAPIParameter {\n  name: string;\n  in: \"query\" | \"path\" | \"header\";\n  description?: string;\n  required?: boolean;\n  schema?: OpenAPISchema;\n  /** Hint text shown inside the empty input. Distinct from `description`,\n   *  which is help text and must NOT be used as a placeholder. */\n  placeholder?: string;\n  \"x-clicky\"?: ClickyParameterMeta;\n  \"x-clicky-lookup\"?: ClickyParameterLookup;\n  /** Vendor-extension placeholder, set server-side by clicky's converter.\n   *  Takes precedence over `placeholder` when both are present. */\n  \"x-clicky-placeholder\"?: string;\n}\n\n/** Resolves the input placeholder for a parameter, drawing ONLY from explicit\n *  placeholder fields — never from `description` (help text). Returns undefined\n *  when no placeholder is declared so callers can apply their own fallback. */\nexport function parameterPlaceholder(\n  param: OpenAPIParameter,\n): string | undefined {\n  return param[\"x-clicky-placeholder\"] ?? param.placeholder;\n}\n\nexport interface OpenAPIOperation {\n  tags?: string[];\n  summary?: string;\n  description?: string;\n  operationId?: string;\n  parameters?: OpenAPIParameter[];\n  requestBody?: {\n    content?: Record<string, { schema?: OpenAPISchema }>;\n  };\n  // Optional because nothing here reads it, and a server may serve this catalog\n  // with the response schemas reduced to a stub — they are over half the bytes\n  // of a spec whose only job here is to describe what can be called.\n  responses?: Record<string, unknown>;\n  \"x-clicky\"?: ClickyOperationMeta;\n}\n\nexport interface OpenAPISpec {\n  openapi: string;\n  info: { title: string; description?: string; version: string };\n  paths: Record<string, Record<string, OpenAPIOperation>>;\n  tags?: Array<{ name: string; description?: string }>;\n  components?: {\n    \"x-clicky-filters\"?: Record<string, ClickyFilterShape>;\n  };\n  \"x-clicky\"?: ClickySpecMeta;\n}\n\nexport interface ResolvedOperation {\n  path: string;\n  method: string;\n  operation: OpenAPIOperation;\n}\n\nexport interface DomainDefinition {\n  key: string;\n  title: string;\n  description: string;\n  icon?: string;\n  emptyTitle?: string;\n  emptyDescription?: string;\n}\n\nexport interface ClickySpecMeta {\n  surfaces?: ClickySurface[];\n}\n\nexport interface ClickySurface {\n  key: string;\n  entity: string;\n  title: string;\n  parent?: string;\n  admin?: boolean;\n  description?: string;\n  /** Opaque icon name emitted by the backend (x-clicky-icon), resolved to a glyph in the UI. */\n  icon?: string;\n  /**\n   * Hierarchy position within `parent`, \"/\"-separated (x-clicky-path) — e.g.\n   * \"jms/incoming/disbursements\". The backend has already applied whatever\n   * delimiter its own naming convention uses, so the UI never guesses one.\n   * Absent — the default — means the parent group renders as a flat list.\n   */\n  path?: string;\n}\n\nexport interface ClickyOperationMeta {\n  command?: string;\n  surface?: string;\n  verb: \"list\" | \"get\" | \"create\" | \"update\" | \"delete\" | \"action\";\n  scope: \"collection\" | \"entity\";\n  actionName?: string;\n  idParam?: string;\n  supportsLookup?: boolean;\n  supportsFilterMode?: boolean;\n  group?: string;\n  toolHints?: ClickyToolHints;\n  export?: ClickyExportMeta;\n}\n\nexport interface ClickyExportMeta {\n  formats?: string[];\n  scopes?: Array<\"page\" | \"all\">;\n  allRowsMode?: \"streaming\" | \"buffered\";\n  formatMaxRows?: Record<string, number>;\n}\n\nexport interface ClickyToolHints {\n  title?: string;\n  readOnlyHint?: boolean;\n  destructiveHint?: boolean;\n  idempotentHint?: boolean;\n  openWorldHint?: boolean;\n  icon?: string;\n  group?: string;\n  parent?: string;\n  /** Captain's tool vocabulary. The legacy `on`/`off` spellings are still\n   *  accepted on decode and mean `allow`/`deny`. */\n  defaultPermission?: \"allow\" | \"ask\" | \"deny\" | \"auto\" | \"on\" | \"off\";\n  strict?: boolean;\n}\n\nexport type OperationLookupFilterType =\n  | \"bool\"\n  | \"number\"\n  | \"date\"\n  /** Both edges of a range under one parameter, as \">=from,<=to\". */\n  | \"date-range\"\n  /** A \"date-range\" with the clock taken off it: whole days, same grammar. */\n  | \"day-range\"\n  /**\n   * A numeric range over elapsed time. Same grammar as \"number\"; the operands\n   * are the column's own unit, which `unit` names.\n   */\n  | \"duration\"\n  | \"from\"\n  | \"to\"\n  | \"multi-filter\"\n  /** A Kubernetes workload selected inside a profile's target scope. */\n  | \"workload\"\n  /** Kubernetes label values, grouped by key when options are key=value pairs. */\n  | \"labels\"\n  /**\n   * An exact-value selection with nothing to enumerate — a UUID column, say.\n   * Same wire grammar as \"multi-filter\"; typed rather than picked, because a\n   * dropdown over identifiers is a page of the rows.\n   */\n  | \"value\";\n\nexport interface OperationLookupFilter {\n  label?: string;\n  options?: Record<string, ClickyNode>;\n  selected?: Record<string, ClickyNode>;\n  multi?: boolean;\n  type?: OperationLookupFilterType;\n  /** True when `options` is only the head of a larger set (server-side capped). */\n  truncated?: boolean;\n  /** True distinct count behind a truncated option set; drives \"… and N more\". */\n  total?: number;\n  presets?: Array<\n    { label: string; from: string; to: string } | TimeRangePresetGroup\n  >;\n  timeEnabled?: boolean;\n  timeZone?: string;\n  timeZones?: string[];\n  /** The unit a \"duration\" filter's operands are written in (\"ms\" or \"s\"), so\n   *  the control labels itself in the numbers the column is stored in. Absent\n   *  means milliseconds. */\n  unit?: string;\n}\n\nexport interface OperationLookupResponse {\n  filters: Record<string, OperationLookupFilter>;\n}\n\nexport function isPositionalParam(p: OpenAPIParameter): boolean {\n  return (\n    p.name === \"args\" ||\n    p.description?.toLowerCase().includes(\"positional argument\") === true\n  );\n}\n"],"names":[],"mappings":"AA+IO,SAAS,qBACd,OACoB;AACpB,SAAO,MAAM,sBAAsB,KAAK,MAAM;AAChD;AA2JO,SAAS,kBAAkB,GAA8B;AA/JzD;AAgKL,SACE,EAAE,SAAS,YACX,OAAE,gBAAF,mBAAe,cAAc,SAAS,4BAA2B;AAErE;"}
+{"version":3,"file":"types.js","sources":["../../src/rpc/types.ts"],"sourcesContent":["import type { ClickyNode } from \"../data/Clicky\";\nimport type { TimeRangePresetGroup } from \"../components/TimeRange\";\nimport type { CronSuggestion } from \"../components/schedule-types\";\n\nexport type OperationRequestValues = Record<string, string | string[]>;\n\nexport interface ExecutionRequest {\n  args?: string[];\n  flags?: OperationRequestValues;\n}\n\nexport interface ExecutionPagination {\n  total?: number;\n  limit?: number;\n  offset?: number;\n\n  // totalRelation says whether total is a count or a lower bound. A backend\n  // that stops counting past a threshold reports \"gte\", and rendering that as\n  // a count would state a number nobody promised.\n  totalRelation?: \"eq\" | \"gte\";\n\n  // hasMore is the server's answer, not an inference from the page length: a\n  // short page and the end of the data are different facts.\n  hasMore?: boolean;\n\n  // nextCursor resumes after this page. Opaque — it is passed back unchanged\n  // and never parsed, because a client that can read one can forge one.\n  nextCursor?: string;\n\n  // truncated reports that the server stopped short of the whole result, so a\n  // partial answer is never rendered as a complete one.\n  truncated?: boolean;\n}\n\nexport interface ExecutionResponse {\n  success: boolean;\n  message?: string;\n  output?: string;\n  stdout?: string;\n  stderr?: string;\n  exit_code: number;\n  error?: string;\n  cli?: string;\n  input?: ExecutionRequest;\n  contentType?: string;\n  requestUrl?: string;\n  responseHeaders?: Record<string, string>;\n  pagination?: ExecutionPagination;\n  blob?: Blob;\n  parsed?: unknown;\n}\n\nexport interface OpenAPISchema {\n  type?: string;\n  format?: string;\n  default?: unknown;\n  enum?: unknown[];\n  description?: string;\n  properties?: Record<string, OpenAPISchema>;\n  items?: OpenAPISchema;\n  oneOf?: OpenAPISchema[];\n  additionalProperties?: OpenAPISchema | boolean;\n  nullable?: boolean;\n}\n\n// ClickyParameterRole tells the UI which widget owns a parameter:\n//   \"search\"    — render as the FilterBar's dedicated search input\n//   \"filter\"    — render as a FilterBar chip on the DataTable\n//   \"limit\"     — feed into DataTable pagination's pageSize\n//   \"offset\"    — feed into DataTable pagination's page (or skip)\n//   \"cursor\"    — carry the opaque position the previous page returned\n//   \"sort\"      — select a public server-side sort key from a table header\n//   \"order\"     — carry that sort's asc/desc direction\n//   \"time-from\" — left edge of a time-range picker\n//   \"time-to\"   — right edge of a time-range picker\n// Set server-side by clicky's converter (see paramRole in clicky/rpc/openapi.go).\nexport type ClickyParameterRole =\n  | \"search\"\n  | \"filter\"\n  | \"limit\"\n  | \"offset\"\n  | \"cursor\"\n  | \"sort\"\n  | \"order\"\n  | \"time-from\"\n  | \"time-to\";\n\nexport interface ClickyParameterMeta {\n  role?: ClickyParameterRole;\n}\n\n/**\n * A parameter's pointer to its filter control, set server-side.\n *\n * `$ref` names the control's SHAPE — which control this is — and is present on\n * every generated filter, because a control's identity never varies with the\n * values currently selected. `url`/`filter`/`searchParam` are the separate\n * question of where its OPTIONS come from, and are present only when the\n * backend can enumerate them: a range has no list to offer.\n */\nexport interface ClickyParameterLookup {\n  /** JSON pointer into `components[\"x-clicky-filters\"]`. */\n  $ref?: string;\n  url?: string;\n  filter?: string;\n  searchParam?: string;\n  multi?: boolean;\n}\n\n/**\n * One entry of `components[\"x-clicky-filters\"]`: a filter control's shape,\n * published once per spec and invariant for the life of it.\n *\n * Distinct from OperationLookupFilter, which is the per-request answer to \"what\n * values can this filter take right now\" and may legitimately narrow as other\n * filters are selected. Reading shape from here rather than from a lookup\n * response is what keeps a control from decaying into a text box while its\n * options are in flight.\n */\nexport interface ClickyFilterShape {\n  label?: string;\n  type?: OperationLookupFilterType;\n  unit?: string;\n  defaultOperator?: \">\" | \">=\" | \"<\" | \"<=\";\n  multi?: boolean;\n}\n\nexport interface OpenAPIParameter {\n  name: string;\n  in: \"query\" | \"path\" | \"header\";\n  description?: string;\n  required?: boolean;\n  schema?: OpenAPISchema;\n  /** Hint text shown inside the empty input. Distinct from `description`,\n   *  which is help text and must NOT be used as a placeholder. */\n  placeholder?: string;\n  \"x-clicky\"?: ClickyParameterMeta;\n  \"x-clicky-lookup\"?: ClickyParameterLookup;\n  /** Vendor-extension placeholder, set server-side by clicky's converter.\n   *  Takes precedence over `placeholder` when both are present. */\n  \"x-clicky-placeholder\"?: string;\n}\n\n/** Resolves the input placeholder for a parameter, drawing ONLY from explicit\n *  placeholder fields — never from `description` (help text). Returns undefined\n *  when no placeholder is declared so callers can apply their own fallback. */\nexport function parameterPlaceholder(\n  param: OpenAPIParameter,\n): string | undefined {\n  return param[\"x-clicky-placeholder\"] ?? param.placeholder;\n}\n\nexport interface OpenAPIOperation {\n  tags?: string[];\n  summary?: string;\n  description?: string;\n  operationId?: string;\n  parameters?: OpenAPIParameter[];\n  requestBody?: {\n    content?: Record<string, { schema?: OpenAPISchema }>;\n  };\n  // Optional because nothing here reads it, and a server may serve this catalog\n  // with the response schemas reduced to a stub — they are over half the bytes\n  // of a spec whose only job here is to describe what can be called.\n  responses?: Record<string, unknown>;\n  \"x-clicky\"?: ClickyOperationMeta;\n}\n\nexport interface OpenAPISpec {\n  openapi: string;\n  info: { title: string; description?: string; version: string };\n  paths: Record<string, Record<string, OpenAPIOperation>>;\n  tags?: Array<{ name: string; description?: string }>;\n  components?: {\n    \"x-clicky-filters\"?: Record<string, ClickyFilterShape>;\n  };\n  \"x-clicky\"?: ClickySpecMeta;\n}\n\nexport interface ResolvedOperation {\n  path: string;\n  method: string;\n  operation: OpenAPIOperation;\n}\n\nexport interface DomainDefinition {\n  key: string;\n  title: string;\n  description: string;\n  icon?: string;\n  emptyTitle?: string;\n  emptyDescription?: string;\n}\n\nexport interface ClickySpecMeta {\n  surfaces?: ClickySurface[];\n}\n\nexport interface ClickySurface {\n  key: string;\n  entity: string;\n  title: string;\n  parent?: string;\n  admin?: boolean;\n  description?: string;\n  /** Opaque icon name emitted by the backend (x-clicky-icon), resolved to a glyph in the UI. */\n  icon?: string;\n  /**\n   * Hierarchy position within `parent`, \"/\"-separated (x-clicky-path) — e.g.\n   * \"jms/incoming/disbursements\". The backend has already applied whatever\n   * delimiter its own naming convention uses, so the UI never guesses one.\n   * Absent — the default — means the parent group renders as a flat list.\n   */\n  path?: string;\n}\n\nexport interface ClickyOperationMeta {\n  command?: string;\n  surface?: string;\n  verb: \"list\" | \"get\" | \"create\" | \"update\" | \"delete\" | \"action\";\n  scope: \"collection\" | \"entity\";\n  actionName?: string;\n  idParam?: string;\n  supportsLookup?: boolean;\n  supportsFilterMode?: boolean;\n  group?: string;\n  toolHints?: ClickyToolHints;\n  export?: ClickyExportMeta;\n  schedule?: ClickyScheduleMeta;\n}\n\nexport interface ClickyScheduleMeta {\n  suggestions?: CronSuggestion[];\n  timeout?: number;\n}\n\nexport interface ClickyExportMeta {\n  formats?: string[];\n  scopes?: Array<\"page\" | \"all\">;\n  allRowsMode?: \"streaming\" | \"buffered\";\n  formatMaxRows?: Record<string, number>;\n}\n\nexport interface ClickyToolHints {\n  title?: string;\n  readOnlyHint?: boolean;\n  destructiveHint?: boolean;\n  idempotentHint?: boolean;\n  openWorldHint?: boolean;\n  icon?: string;\n  group?: string;\n  parent?: string;\n  /** Captain's tool vocabulary. The legacy `on`/`off` spellings are still\n   *  accepted on decode and mean `allow`/`deny`. */\n  defaultPermission?: \"allow\" | \"ask\" | \"deny\" | \"auto\" | \"on\" | \"off\";\n  strict?: boolean;\n}\n\nexport type OperationLookupFilterType =\n  | \"bool\"\n  | \"number\"\n  | \"date\"\n  /** Both edges of a range under one parameter, as \">=from,<=to\". */\n  | \"date-range\"\n  /** A \"date-range\" with the clock taken off it: whole days, same grammar. */\n  | \"day-range\"\n  /**\n   * A numeric range over elapsed time. Same grammar as \"number\"; the operands\n   * are the column's own unit, which `unit` names.\n   */\n  | \"duration\"\n  | \"from\"\n  | \"to\"\n  | \"multi-filter\"\n  /** A Kubernetes workload selected inside a profile's target scope. */\n  | \"workload\"\n  /** Kubernetes label values, grouped by key when options are key=value pairs. */\n  | \"labels\"\n  /**\n   * An exact-value selection with nothing to enumerate — a UUID column, say.\n   * Same wire grammar as \"multi-filter\"; typed rather than picked, because a\n   * dropdown over identifiers is a page of the rows.\n   */\n  | \"value\";\n\nexport interface OperationLookupFilter {\n  label?: string;\n  options?: Record<string, ClickyNode>;\n  selected?: Record<string, ClickyNode>;\n  multi?: boolean;\n  type?: OperationLookupFilterType;\n  /** True when `options` is only the head of a larger set (server-side capped). */\n  truncated?: boolean;\n  /** True distinct count behind a truncated option set; drives \"… and N more\". */\n  total?: number;\n  /**\n   * Per-value row counts, keyed the same as `options`. A value absent from\n   * this map is a value the source did not count — never rendered as zero —\n   * and the whole field is omitted when the source doesn't count at all.\n   */\n  counts?: Record<string, number>;\n  presets?: Array<\n    { label: string; from: string; to: string } | TimeRangePresetGroup\n  >;\n  timeEnabled?: boolean;\n  timeZone?: string;\n  timeZones?: string[];\n  /** Unit used by numeric values. For durations this is the storage unit\n   *  (\"ms\", \"s\", \"m\", or \"h\"); absent duration units mean milliseconds. */\n  unit?: string;\n  defaultOperator?: \">\" | \">=\" | \"<\" | \"<=\";\n}\n\nexport interface OperationLookupResponse {\n  filters: Record<string, OperationLookupFilter>;\n}\n\nexport function isPositionalParam(p: OpenAPIParameter): boolean {\n  return (\n    p.name === \"args\" ||\n    p.description?.toLowerCase().includes(\"positional argument\") === true\n  );\n}\n"],"names":[],"mappings":"AAkJO,SAAS,qBACd,OACoB;AACpB,SAAO,MAAM,sBAAsB,KAAK,MAAM;AAChD;AAuKO,SAAS,kBAAkB,GAA8B;AA3KzD;AA4KL,SACE,EAAE,SAAS,YACX,OAAE,gBAAF,mBAAe,cAAc,SAAS,4BAA2B;AAErE;"}

package/dist/rpc/useOperationCatalogFollow.cjs

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react = require("react");
+const useLogTail = require("../hooks/use-log-tail.cjs");
+const operationCatalogFollow = require("./operationCatalogFollow.cjs");
+function useOperationCatalogFollow(options) {
+  const { follow, operations, listEndpoint, listParameters, effectiveFilters, showTable } = options;
+  const followEnabled = follow === true || typeof follow === "object" && follow !== null;
+  const followMaxRows = typeof follow === "object" && follow !== null ? follow.maxRows : void 0;
+  const sessionOperation = react.useMemo(
+    () => followEnabled ? operationCatalogFollow.findSessionStartOperation(operations, listEndpoint) : void 0,
+    [followEnabled, operations, listEndpoint]
+  );
+  const followTarget = react.useMemo(
+    () => listEndpoint ? operationCatalogFollow.deriveLogTailTarget(listEndpoint.path) : void 0,
+    [listEndpoint]
+  );
+  const followParams = react.useMemo(
+    () => typeof follow === "object" && (follow == null ? void 0 : follow.mode) === "reconcile" ? follow.params : operationCatalogFollow.followSessionParams(listParameters, effectiveFilters),
+    [follow, listParameters, effectiveFilters]
+  );
+  const tail = useLogTail.useLogTail({
+    profile: (followTarget == null ? void 0 : followTarget.profile) ?? "",
+    basePath: followTarget == null ? void 0 : followTarget.basePath,
+    params: followParams,
+    following: followEnabled && !!sessionOperation && !!followTarget,
+    ...followMaxRows !== void 0 ? { maxRows: followMaxRows } : {}
+  });
+  return {
+    followEnabled,
+    sessionOperation,
+    followMissing: followEnabled && showTable && !sessionOperation,
+    tail
+  };
+}
+exports.useOperationCatalogFollow = useOperationCatalogFollow;
+//# sourceMappingURL=useOperationCatalogFollow.cjs.map

package/dist/rpc/useOperationCatalogFollow.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOperationCatalogFollow.cjs","sources":["../../src/rpc/useOperationCatalogFollow.ts"],"sourcesContent":["import { useMemo } from \"react\";\nimport { useLogTail, type UseLogTailResult } from \"../hooks/use-log-tail\";\nimport {\n  deriveLogTailTarget,\n  findSessionStartOperation,\n  followSessionParams,\n} from \"./operationCatalogFollow\";\nimport type { OpenAPIParameter, ResolvedOperation } from \"./types\";\n\nexport type OperationCatalogFollowOption = boolean\n  | { mode?: \"append\"; maxRows?: number }\n  | { mode: \"reconcile\"; params: Record<string, string>; maxRows?: number; onReconcile?: (sequence: number) => void }\n  | undefined;\n\nexport type UseOperationCatalogFollowResult = {\n  /** True when the host asked to follow (`follow` was truthy). */\n  followEnabled: boolean;\n  /** The `POST <listPath>/sessions` operation, once one is found. */\n  sessionOperation: ResolvedOperation | undefined;\n  /** `follow` was asked for but no session-start operation is advertised —\n   *  the caller renders this as a loud, surface-naming error, never a\n   *  silent no-op. */\n  followMissing: boolean;\n  tail: UseLogTailResult;\n};\n\n/**\n * Bundles OperationCatalog's `follow` wiring behind one hook call: resolving\n * whether the list operation advertises a session to follow, deriving the\n * `useLogTail` target from its path, and opening the tail with either the\n * list's filters or the stream scope supplied by a reconciling caller.\n */\nexport function useOperationCatalogFollow(options: {\n  follow: OperationCatalogFollowOption;\n  operations: ResolvedOperation[];\n  listEndpoint: ResolvedOperation | undefined;\n  listParameters: OpenAPIParameter[];\n  effectiveFilters: Record<string, string>;\n  showTable: boolean;\n}): UseOperationCatalogFollowResult {\n  const { follow, operations, listEndpoint, listParameters, effectiveFilters, showTable } = options;\n  const followEnabled = follow === true || (typeof follow === \"object\" && follow !== null);\n  const followMaxRows = typeof follow === \"object\" && follow !== null ? follow.maxRows : undefined;\n\n  // The session-start operation is looked up in the *whole* operations list,\n  // not a surface-filtered one: it is a distinct OpenAPI operation that may\n  // carry no `x-clicky.surface` tag of its own, so filtering by surface\n  // first would never find it.\n  const sessionOperation = useMemo(\n    () => (followEnabled ? findSessionStartOperation(operations, listEndpoint) : undefined),\n    [followEnabled, operations, listEndpoint],\n  );\n  const followTarget = useMemo(\n    () => (listEndpoint ? deriveLogTailTarget(listEndpoint.path) : undefined),\n    [listEndpoint],\n  );\n  const followParams = useMemo(\n    () => typeof follow === \"object\" && follow?.mode === \"reconcile\"\n      ? follow.params\n      : followSessionParams(listParameters, effectiveFilters),\n    [follow, listParameters, effectiveFilters],\n  );\n\n  const tail = useLogTail({\n    profile: followTarget?.profile ?? \"\",\n    basePath: followTarget?.basePath,\n    params: followParams,\n    following: followEnabled && !!sessionOperation && !!followTarget,\n    ...(followMaxRows !== undefined ? { maxRows: followMaxRows } : {}),\n  });\n\n  return {\n    followEnabled,\n    sessionOperation,\n    followMissing: followEnabled && showTable && !sessionOperation,\n    tail,\n  };\n}\n"],"names":["useMemo","findSessionStartOperation","deriveLogTailTarget","followSessionParams","useLogTail"],"mappings":";;;;;AAgCO,SAAS,0BAA0B,SAON;AAClC,QAAM,EAAE,QAAQ,YAAY,cAAc,gBAAgB,kBAAkB,cAAc;AAC1F,QAAM,gBAAgB,WAAW,QAAS,OAAO,WAAW,YAAY,WAAW;AACnF,QAAM,gBAAgB,OAAO,WAAW,YAAY,WAAW,OAAO,OAAO,UAAU;AAMvF,QAAM,mBAAmBA,MAAAA;AAAAA,IACvB,MAAO,gBAAgBC,uBAAAA,0BAA0B,YAAY,YAAY,IAAI;AAAA,IAC7E,CAAC,eAAe,YAAY,YAAY;AAAA,EAAA;AAE1C,QAAM,eAAeD,MAAAA;AAAAA,IACnB,MAAO,eAAeE,uBAAAA,oBAAoB,aAAa,IAAI,IAAI;AAAA,IAC/D,CAAC,YAAY;AAAA,EAAA;AAEf,QAAM,eAAeF,MAAAA;AAAAA,IACnB,MAAM,OAAO,WAAW,aAAY,iCAAQ,UAAS,cACjD,OAAO,SACPG,2CAAoB,gBAAgB,gBAAgB;AAAA,IACxD,CAAC,QAAQ,gBAAgB,gBAAgB;AAAA,EAAA;AAG3C,QAAM,OAAOC,WAAAA,WAAW;AAAA,IACtB,UAAS,6CAAc,YAAW;AAAA,IAClC,UAAU,6CAAc;AAAA,IACxB,QAAQ;AAAA,IACR,WAAW,iBAAiB,CAAC,CAAC,oBAAoB,CAAC,CAAC;AAAA,IACpD,GAAI,kBAAkB,SAAY,EAAE,SAAS,cAAA,IAAkB,CAAA;AAAA,EAAC,CACjE;AAED,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,eAAe,iBAAiB,aAAa,CAAC;AAAA,IAC9C;AAAA,EAAA;AAEJ;;"}

package/dist/rpc/useOperationCatalogFollow.d.ts

@@ -0,0 +1,37 @@
+import { UseLogTailResult } from '../hooks/use-log-tail';
+import { OpenAPIParameter, ResolvedOperation } from './types';
+export type OperationCatalogFollowOption = boolean | {
+    mode?: "append";
+    maxRows?: number;
+} | {
+    mode: "reconcile";
+    params: Record<string, string>;
+    maxRows?: number;
+    onReconcile?: (sequence: number) => void;
+} | undefined;
+export type UseOperationCatalogFollowResult = {
+    /** True when the host asked to follow (`follow` was truthy). */
+    followEnabled: boolean;
+    /** The `POST <listPath>/sessions` operation, once one is found. */
+    sessionOperation: ResolvedOperation | undefined;
+    /** `follow` was asked for but no session-start operation is advertised —
+     *  the caller renders this as a loud, surface-naming error, never a
+     *  silent no-op. */
+    followMissing: boolean;
+    tail: UseLogTailResult;
+};
+/**
+ * Bundles OperationCatalog's `follow` wiring behind one hook call: resolving
+ * whether the list operation advertises a session to follow, deriving the
+ * `useLogTail` target from its path, and opening the tail with either the
+ * list's filters or the stream scope supplied by a reconciling caller.
+ */
+export declare function useOperationCatalogFollow(options: {
+    follow: OperationCatalogFollowOption;
+    operations: ResolvedOperation[];
+    listEndpoint: ResolvedOperation | undefined;
+    listParameters: OpenAPIParameter[];
+    effectiveFilters: Record<string, string>;
+    showTable: boolean;
+}): UseOperationCatalogFollowResult;
+//# sourceMappingURL=useOperationCatalogFollow.d.ts.map

package/dist/rpc/useOperationCatalogFollow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOperationCatalogFollow.d.ts","sourceRoot":"","sources":["../../src/rpc/useOperationCatalogFollow.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAM1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEnE,MAAM,MAAM,4BAA4B,GAAG,OAAO,GAC9C;IAAE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACjH,SAAS,CAAC;AAEd,MAAM,MAAM,+BAA+B,GAAG;IAC5C,gEAAgE;IAChE,aAAa,EAAE,OAAO,CAAC;IACvB,mEAAmE;IACnE,gBAAgB,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAChD;;wBAEoB;IACpB,aAAa,EAAE,OAAO,CAAC;IACvB,IAAI,EAAE,gBAAgB,CAAC;CACxB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE;IACjD,MAAM,EAAE,4BAA4B,CAAC;IACrC,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,YAAY,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC5C,cAAc,EAAE,gBAAgB,EAAE,CAAC;IACnC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,+BAA+B,CAsClC"}

package/dist/rpc/useOperationCatalogFollow.js

@@ -0,0 +1,37 @@
+import { useMemo } from "react";
+import { useLogTail } from "../hooks/use-log-tail.js";
+import { findSessionStartOperation, deriveLogTailTarget, followSessionParams } from "./operationCatalogFollow.js";
+function useOperationCatalogFollow(options) {
+  const { follow, operations, listEndpoint, listParameters, effectiveFilters, showTable } = options;
+  const followEnabled = follow === true || typeof follow === "object" && follow !== null;
+  const followMaxRows = typeof follow === "object" && follow !== null ? follow.maxRows : void 0;
+  const sessionOperation = useMemo(
+    () => followEnabled ? findSessionStartOperation(operations, listEndpoint) : void 0,
+    [followEnabled, operations, listEndpoint]
+  );
+  const followTarget = useMemo(
+    () => listEndpoint ? deriveLogTailTarget(listEndpoint.path) : void 0,
+    [listEndpoint]
+  );
+  const followParams = useMemo(
+    () => typeof follow === "object" && (follow == null ? void 0 : follow.mode) === "reconcile" ? follow.params : followSessionParams(listParameters, effectiveFilters),
+    [follow, listParameters, effectiveFilters]
+  );
+  const tail = useLogTail({
+    profile: (followTarget == null ? void 0 : followTarget.profile) ?? "",
+    basePath: followTarget == null ? void 0 : followTarget.basePath,
+    params: followParams,
+    following: followEnabled && !!sessionOperation && !!followTarget,
+    ...followMaxRows !== void 0 ? { maxRows: followMaxRows } : {}
+  });
+  return {
+    followEnabled,
+    sessionOperation,
+    followMissing: followEnabled && showTable && !sessionOperation,
+    tail
+  };
+}
+export {
+  useOperationCatalogFollow
+};
+//# sourceMappingURL=useOperationCatalogFollow.js.map

package/dist/rpc/useOperationCatalogFollow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOperationCatalogFollow.js","sources":["../../src/rpc/useOperationCatalogFollow.ts"],"sourcesContent":["import { useMemo } from \"react\";\nimport { useLogTail, type UseLogTailResult } from \"../hooks/use-log-tail\";\nimport {\n  deriveLogTailTarget,\n  findSessionStartOperation,\n  followSessionParams,\n} from \"./operationCatalogFollow\";\nimport type { OpenAPIParameter, ResolvedOperation } from \"./types\";\n\nexport type OperationCatalogFollowOption = boolean\n  | { mode?: \"append\"; maxRows?: number }\n  | { mode: \"reconcile\"; params: Record<string, string>; maxRows?: number; onReconcile?: (sequence: number) => void }\n  | undefined;\n\nexport type UseOperationCatalogFollowResult = {\n  /** True when the host asked to follow (`follow` was truthy). */\n  followEnabled: boolean;\n  /** The `POST <listPath>/sessions` operation, once one is found. */\n  sessionOperation: ResolvedOperation | undefined;\n  /** `follow` was asked for but no session-start operation is advertised —\n   *  the caller renders this as a loud, surface-naming error, never a\n   *  silent no-op. */\n  followMissing: boolean;\n  tail: UseLogTailResult;\n};\n\n/**\n * Bundles OperationCatalog's `follow` wiring behind one hook call: resolving\n * whether the list operation advertises a session to follow, deriving the\n * `useLogTail` target from its path, and opening the tail with either the\n * list's filters or the stream scope supplied by a reconciling caller.\n */\nexport function useOperationCatalogFollow(options: {\n  follow: OperationCatalogFollowOption;\n  operations: ResolvedOperation[];\n  listEndpoint: ResolvedOperation | undefined;\n  listParameters: OpenAPIParameter[];\n  effectiveFilters: Record<string, string>;\n  showTable: boolean;\n}): UseOperationCatalogFollowResult {\n  const { follow, operations, listEndpoint, listParameters, effectiveFilters, showTable } = options;\n  const followEnabled = follow === true || (typeof follow === \"object\" && follow !== null);\n  const followMaxRows = typeof follow === \"object\" && follow !== null ? follow.maxRows : undefined;\n\n  // The session-start operation is looked up in the *whole* operations list,\n  // not a surface-filtered one: it is a distinct OpenAPI operation that may\n  // carry no `x-clicky.surface` tag of its own, so filtering by surface\n  // first would never find it.\n  const sessionOperation = useMemo(\n    () => (followEnabled ? findSessionStartOperation(operations, listEndpoint) : undefined),\n    [followEnabled, operations, listEndpoint],\n  );\n  const followTarget = useMemo(\n    () => (listEndpoint ? deriveLogTailTarget(listEndpoint.path) : undefined),\n    [listEndpoint],\n  );\n  const followParams = useMemo(\n    () => typeof follow === \"object\" && follow?.mode === \"reconcile\"\n      ? follow.params\n      : followSessionParams(listParameters, effectiveFilters),\n    [follow, listParameters, effectiveFilters],\n  );\n\n  const tail = useLogTail({\n    profile: followTarget?.profile ?? \"\",\n    basePath: followTarget?.basePath,\n    params: followParams,\n    following: followEnabled && !!sessionOperation && !!followTarget,\n    ...(followMaxRows !== undefined ? { maxRows: followMaxRows } : {}),\n  });\n\n  return {\n    followEnabled,\n    sessionOperation,\n    followMissing: followEnabled && showTable && !sessionOperation,\n    tail,\n  };\n}\n"],"names":[],"mappings":";;;AAgCO,SAAS,0BAA0B,SAON;AAClC,QAAM,EAAE,QAAQ,YAAY,cAAc,gBAAgB,kBAAkB,cAAc;AAC1F,QAAM,gBAAgB,WAAW,QAAS,OAAO,WAAW,YAAY,WAAW;AACnF,QAAM,gBAAgB,OAAO,WAAW,YAAY,WAAW,OAAO,OAAO,UAAU;AAMvF,QAAM,mBAAmB;AAAA,IACvB,MAAO,gBAAgB,0BAA0B,YAAY,YAAY,IAAI;AAAA,IAC7E,CAAC,eAAe,YAAY,YAAY;AAAA,EAAA;AAE1C,QAAM,eAAe;AAAA,IACnB,MAAO,eAAe,oBAAoB,aAAa,IAAI,IAAI;AAAA,IAC/D,CAAC,YAAY;AAAA,EAAA;AAEf,QAAM,eAAe;AAAA,IACnB,MAAM,OAAO,WAAW,aAAY,iCAAQ,UAAS,cACjD,OAAO,SACP,oBAAoB,gBAAgB,gBAAgB;AAAA,IACxD,CAAC,QAAQ,gBAAgB,gBAAgB;AAAA,EAAA;AAG3C,QAAM,OAAO,WAAW;AAAA,IACtB,UAAS,6CAAc,YAAW;AAAA,IAClC,UAAU,6CAAc;AAAA,IACxB,QAAQ;AAAA,IACR,WAAW,iBAAiB,CAAC,CAAC,oBAAoB,CAAC,CAAC;AAAA,IACpD,GAAI,kBAAkB,SAAY,EAAE,SAAS,cAAA,IAAkB,CAAA;AAAA,EAAC,CACjE;AAED,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,eAAe,iBAAiB,aAAa,CAAC;AAAA,IAC9C;AAAA,EAAA;AAEJ;"}

package/dist/rpc/useOperationPages.cjs

@@ -10,13 +10,20 @@ function useOperationPages({
   client,
   endpoint,
   parameters,
-  filters
+  filters,
+  paginationMode
 }) {
   var _a;
   const queryClient = reactQuery.useQueryClient();
   const cursorParam = cursorStale.cursorParameterName(parameters);
   const path = endpoint == null ? void 0 : endpoint.path;
   const method = endpoint == null ? void 0 : endpoint.method;
+  if (endpoint && paginationMode === "infinite" && !cursorParam) {
+    throw new Error(
+      `Operation ${method == null ? void 0 : method.toUpperCase()} ${path} cannot use infinite pagination without a cursor parameter`
+    );
+  }
+  const walkMode = paginationMode === "infinite" || paginationMode === void 0 && !!cursorParam;
   const walkFilters = react.useMemo(() => {
     if (!cursorParam) return filters;
     const rest = { ...filters };
@@ -35,7 +42,7 @@ function useOperationPages({
   const single = reactQuery.useQuery({
     queryKey: [LIST_KEY, method, path, filters],
     queryFn: () => execute(filters),
-    enabled: !!endpoint && !cursorParam,
+    enabled: !!endpoint && !walkMode,
     placeholderData: reactQuery.keepPreviousData,
     staleTime: 3e4,
     retry: 0
@@ -55,7 +62,7 @@ function useOperationPages({
       var _a2;
       return ((_a2 = lastPage.pagination) == null ? void 0 : _a2.hasMore) ? lastPage.pagination.nextCursor : void 0;
     },
-    enabled: !!endpoint && !!cursorParam,
+    enabled: !!endpoint && walkMode,
     placeholderData: reactQuery.keepPreviousData,
     staleTime: 3e4,
     retry: 0
@@ -68,18 +75,18 @@ function useOperationPages({
   }, [queryClient, staleWalk, walkKey]);
   const fetchNextPage = walk.fetchNextPage;
   const infinite = react.useMemo(() => {
-    if (!cursorParam) return void 0;
+    if (!walkMode || !cursorParam) return void 0;
     return {
       hasMore: walk.hasNextPage,
       loading: walk.isFetchingNextPage,
       onLoadMore: () => void fetchNextPage()
     };
-  }, [cursorParam, fetchNextPage, walk.hasNextPage, walk.isFetchingNextPage]);
+  }, [cursorParam, fetchNextPage, walk.hasNextPage, walk.isFetchingNextPage, walkMode]);
   const resetWalk = react.useCallback(() => {
     void queryClient.resetQueries({ queryKey: walkKey });
   }, [queryClient, walkKey]);
   const refetchSingle = single.refetch;
-  if (!cursorParam) {
+  if (!walkMode) {
     return {
       pages: single.data ? [single.data] : [],
       response: single.data ?? null,

package/dist/rpc/useOperationPages.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useOperationPages.cjs","sources":["../../src/rpc/useOperationPages.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo } from \"react\";\nimport {\n  keepPreviousData,\n  useInfiniteQuery,\n  useQuery,\n  useQueryClient,\n  type InfiniteData,\n  type QueryKey,\n} from \"@tanstack/react-query\";\n\nimport type { DataTableInfinite } from \"../data/DataTable\";\nimport { cursorParameterName, isCursorStale } from \"./cursorStale\";\nimport { packParameterValues, type ParameterValues } from \"./formMetadata\";\nimport type {\n  ExecutionResponse,\n  OpenAPIParameter,\n  ResolvedOperation,\n} from \"./types\";\nimport type { OperationsApiClient } from \"./useOperations\";\n\nconst LIST_KEY = \"operation-list\";\nconst CLICKY_HEADERS = { Accept: \"application/json+clicky\" };\n\nexport type OperationPagesOptions = {\n  client: OperationsApiClient;\n  /** The list operation, or undefined for a surface that has none. */\n  endpoint: ResolvedOperation | undefined;\n  /** Every parameter the operation declares — the source of the cursor role. */\n  parameters: OpenAPIParameter[];\n  /** Current filter/pagination state, as the catalog holds and URL-mirrors it. */\n  filters: ParameterValues;\n};\n\nexport type OperationPages = {\n  /** Every page fetched so far, oldest first. One entry outside a walk. */\n  pages: ExecutionResponse[];\n  /** The newest page — what every renderer means by \"the response\". */\n  response: ExecutionResponse | null;\n  /** True while the whole result is being replaced, not while it is growing. */\n  isFetching: boolean;\n  isPending: boolean;\n  isError: boolean;\n  error: unknown;\n  /** Re-runs the list. A walk restarts rather than replaying its cursors. */\n  refetch: () => void;\n  /** Load-more handle; absent unless the operation can walk by cursor. */\n  infinite?: DataTableInfinite;\n};\n\n/**\n * useOperationPages runs a surface's list operation, walking it forward when it\n * declares a cursor and fetching a single page when it does not.\n *\n * The mode is the operation's to decide, not the caller's: a cursor role is the\n * server saying \"you may resume this query\", and everything else — the majority\n * of surfaces — keeps the single-page query it has always had, replacing its\n * rows when the offset moves.\n *\n * In walk mode the cursor is deliberately absent from the query key. The key is\n * the identity of the query being walked, and the cursor is a position inside\n * it; keying on it made every page a different query, which is precisely why\n * advancing replaced the rows instead of extending them. Every other filter\n * stays in the key, so any filter, parameter or time-range change starts a new\n * walk on its own, with no reset logic layered on top.\n */\nexport function useOperationPages({\n  client,\n  endpoint,\n  parameters,\n  filters,\n}: OperationPagesOptions): OperationPages {\n  const queryClient = useQueryClient();\n  const cursorParam = cursorParameterName(parameters);\n  const path = endpoint?.path;\n  const method = endpoint?.method;\n\n  // The walk's own view of the filters: everything that identifies the query,\n  // with the position taken out. A cursor left over in the URL from a shared\n  // link names a position in a walk this session never made, so it is dropped\n  // rather than replayed.\n  const walkFilters = useMemo(() => {\n    if (!cursorParam) return filters;\n    const rest = { ...filters };\n    delete rest[cursorParam];\n    return rest;\n  }, [cursorParam, filters]);\n\n  const execute = useCallback(\n    (values: ParameterValues) =>\n      client.executeCommand(\n        path!,\n        method!,\n        packParameterValues(values, parameters),\n        CLICKY_HEADERS,\n      ),\n    [client, method, parameters, path],\n  );\n\n  // Both queries are declared on every render — hooks are not conditional — and\n  // exactly one is enabled. Their keys differ in shape as well as content, so a\n  // surface that switches modes can never read a page array as a page.\n  const single = useQuery<ExecutionResponse>({\n    queryKey: [LIST_KEY, method, path, filters],\n    queryFn: () => execute(filters),\n    enabled: !!endpoint && !cursorParam,\n    placeholderData: keepPreviousData,\n    staleTime: 30_000,\n    retry: 0,\n  });\n\n  // Prefixed with the same LIST_KEY as the single-page query: host apps\n  // invalidate [\"operation-list\"] after a mutation, and a walk that fell\n  // outside that prefix would keep serving rows the mutation changed.\n  const walkKey = useMemo(\n    () => [LIST_KEY, \"walk\", method, path, walkFilters],\n    [method, path, walkFilters],\n  );\n\n  const walk = useInfiniteQuery<\n    ExecutionResponse,\n    Error,\n    InfiniteData<ExecutionResponse, string | undefined>,\n    QueryKey,\n    string | undefined\n  >({\n    queryKey: walkKey,\n    queryFn: ({ pageParam }) =>\n      execute(pageParam ? { ...walkFilters, [cursorParam!]: pageParam } : walkFilters),\n    initialPageParam: undefined,\n    // The server's two answers, both required: it has more, and here is where\n    // to resume. A page claiming more without minting a token cannot be walked,\n    // and guessing one is how a client forges a position it was never given.\n    getNextPageParam: (lastPage) =>\n      lastPage.pagination?.hasMore ? lastPage.pagination.nextCursor : undefined,\n    enabled: !!endpoint && !!cursorParam,\n    placeholderData: keepPreviousData,\n    staleTime: 30_000,\n    retry: 0,\n  });\n\n  const walkPages = walk.data?.pages;\n\n  // A cursor the server refuses is recoverable by construction: the query is\n  // fine and only the position is gone, so the walk starts again instead of\n  // stranding the reader on an error panel they cannot page out of. Resetting\n  // is what does it — refetching would replay the very cursors that were\n  // refused, page by page.\n  //\n  // Guarded on a page having already been fetched, because only then can a\n  // cursor have been sent. A first page refused this way is a server that\n  // answers `cursor_stale` to a request carrying no cursor, and restarting on\n  // that spins: refuse, restart, refuse.\n  const staleWalk = isCursorStale(walk.error) && (walkPages?.length ?? 0) > 0;\n\n  useEffect(() => {\n    if (!staleWalk) return;\n    void queryClient.resetQueries({ queryKey: walkKey });\n  }, [queryClient, staleWalk, walkKey]);\n\n  const fetchNextPage = walk.fetchNextPage;\n  const infinite = useMemo<DataTableInfinite | undefined>(() => {\n    if (!cursorParam) return undefined;\n    return {\n      hasMore: walk.hasNextPage,\n      loading: walk.isFetchingNextPage,\n      onLoadMore: () => void fetchNextPage(),\n    };\n  }, [cursorParam, fetchNextPage, walk.hasNextPage, walk.isFetchingNextPage]);\n\n  const resetWalk = useCallback(() => {\n    void queryClient.resetQueries({ queryKey: walkKey });\n  }, [queryClient, walkKey]);\n  const refetchSingle = single.refetch;\n\n  if (!cursorParam) {\n    return {\n      pages: single.data ? [single.data] : [],\n      response: single.data ?? null,\n      isFetching: single.isFetching,\n      isPending: single.isPending,\n      isError: single.isError,\n      error: single.error,\n      refetch: () => void refetchSingle(),\n    };\n  }\n\n  const pages = walkPages ?? [];\n  return {\n    pages,\n    response: pages[pages.length - 1] ?? null,\n    // Fetching the next page grows the run; it does not replace it. Reporting\n    // it as a load of the whole surface is what drops a spinner over rows the\n    // reader is still reading.\n    isFetching: walk.isFetching && !walk.isFetchingNextPage,\n    isPending: walk.isPending,\n    isError: walk.isError && !staleWalk,\n    error: staleWalk ? undefined : walk.error,\n    // A mutation just changed the rows this walk was cut from, so its cursors\n    // no longer name positions in it. Starting over is the only honest refetch.\n    refetch: resetWalk,\n    ...(infinite ? { infinite } : {}),\n  };\n}\n"],"names":["useQueryClient","cursorParameterName","useMemo","useCallback","packParameterValues","useQuery","keepPreviousData","useInfiniteQuery","_a","isCursorStale","useEffect"],"mappings":"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"}
+{"version":3,"file":"useOperationPages.cjs","sources":["../../src/rpc/useOperationPages.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo } from \"react\";\nimport {\n  keepPreviousData,\n  useInfiniteQuery,\n  useQuery,\n  useQueryClient,\n  type InfiniteData,\n  type QueryKey,\n} from \"@tanstack/react-query\";\n\nimport type { DataTableInfinite } from \"../data/DataTable\";\nimport { cursorParameterName, isCursorStale } from \"./cursorStale\";\nimport { packParameterValues, type ParameterValues } from \"./formMetadata\";\nimport type {\n  ExecutionResponse,\n  OpenAPIParameter,\n  ResolvedOperation,\n} from \"./types\";\nimport type { OperationsApiClient } from \"./useOperations\";\n\nconst LIST_KEY = \"operation-list\";\nconst CLICKY_HEADERS = { Accept: \"application/json+clicky\" };\n\nexport type OperationPagesOptions = {\n  client: OperationsApiClient;\n  /** The list operation, or undefined for a surface that has none. */\n  endpoint: ResolvedOperation | undefined;\n  /** Every parameter the operation declares — the source of the cursor role. */\n  parameters: OpenAPIParameter[];\n  /** Current filter/pagination state, as the catalog holds and URL-mirrors it. */\n  filters: ParameterValues;\n  /** Omit to infer a cursor walk from the operation; hosts may force either presentation. */\n  paginationMode?: \"paged\" | \"infinite\";\n};\n\nexport type OperationPages = {\n  /** Every page fetched so far, oldest first. One entry outside a walk. */\n  pages: ExecutionResponse[];\n  /** The newest page — what every renderer means by \"the response\". */\n  response: ExecutionResponse | null;\n  /** True while the whole result is being replaced, not while it is growing. */\n  isFetching: boolean;\n  isPending: boolean;\n  isError: boolean;\n  error: unknown;\n  /** Re-runs the list. A walk restarts rather than replaying its cursors. */\n  refetch: () => void;\n  /** Load-more handle; absent unless the operation can walk by cursor. */\n  infinite?: DataTableInfinite;\n};\n\n/**\n * useOperationPages runs a surface's list operation, walking it forward when it\n * declares a cursor and fetching a single page when it does not. A host can\n * explicitly keep a cursor-capable operation paged when readers need offset\n * controls; omission retains automatic selection.\n *\n * Automatic mode follows the operation: a cursor role is the server saying\n * \"you may resume this query\", and everything else keeps the single-page query\n * it has always had. An explicit host override changes only the presentation;\n * the operation still owns the available cursor and offset capabilities.\n *\n * In walk mode the cursor is deliberately absent from the query key. The key is\n * the identity of the query being walked, and the cursor is a position inside\n * it; keying on it made every page a different query, which is precisely why\n * advancing replaced the rows instead of extending them. Every other filter\n * stays in the key, so any filter, parameter or time-range change starts a new\n * walk on its own, with no reset logic layered on top.\n */\nexport function useOperationPages({\n  client,\n  endpoint,\n  parameters,\n  filters,\n  paginationMode,\n}: OperationPagesOptions): OperationPages {\n  const queryClient = useQueryClient();\n  const cursorParam = cursorParameterName(parameters);\n  const path = endpoint?.path;\n  const method = endpoint?.method;\n  if (endpoint && paginationMode === \"infinite\" && !cursorParam) {\n    throw new Error(\n      `Operation ${method?.toUpperCase()} ${path} cannot use infinite pagination without a cursor parameter`,\n    );\n  }\n  const walkMode = paginationMode === \"infinite\" || (paginationMode === undefined && !!cursorParam);\n\n  // The walk's own view of the filters: everything that identifies the query,\n  // with the position taken out. A cursor left over in the URL from a shared\n  // link names a position in a walk this session never made, so it is dropped\n  // rather than replayed.\n  const walkFilters = useMemo(() => {\n    if (!cursorParam) return filters;\n    const rest = { ...filters };\n    delete rest[cursorParam];\n    return rest;\n  }, [cursorParam, filters]);\n\n  const execute = useCallback(\n    (values: ParameterValues) =>\n      client.executeCommand(\n        path!,\n        method!,\n        packParameterValues(values, parameters),\n        CLICKY_HEADERS,\n      ),\n    [client, method, parameters, path],\n  );\n\n  // Both queries are declared on every render — hooks are not conditional — and\n  // exactly one is enabled. Their keys differ in shape as well as content, so a\n  // surface that switches modes can never read a page array as a page.\n  const single = useQuery<ExecutionResponse>({\n    queryKey: [LIST_KEY, method, path, filters],\n    queryFn: () => execute(filters),\n    enabled: !!endpoint && !walkMode,\n    placeholderData: keepPreviousData,\n    staleTime: 30_000,\n    retry: 0,\n  });\n\n  // Prefixed with the same LIST_KEY as the single-page query: host apps\n  // invalidate [\"operation-list\"] after a mutation, and a walk that fell\n  // outside that prefix would keep serving rows the mutation changed.\n  const walkKey = useMemo(\n    () => [LIST_KEY, \"walk\", method, path, walkFilters],\n    [method, path, walkFilters],\n  );\n\n  const walk = useInfiniteQuery<\n    ExecutionResponse,\n    Error,\n    InfiniteData<ExecutionResponse, string | undefined>,\n    QueryKey,\n    string | undefined\n  >({\n    queryKey: walkKey,\n    queryFn: ({ pageParam }) =>\n      execute(pageParam ? { ...walkFilters, [cursorParam!]: pageParam } : walkFilters),\n    initialPageParam: undefined,\n    // The server's two answers, both required: it has more, and here is where\n    // to resume. A page claiming more without minting a token cannot be walked,\n    // and guessing one is how a client forges a position it was never given.\n    getNextPageParam: (lastPage) =>\n      lastPage.pagination?.hasMore ? lastPage.pagination.nextCursor : undefined,\n    enabled: !!endpoint && walkMode,\n    placeholderData: keepPreviousData,\n    staleTime: 30_000,\n    retry: 0,\n  });\n\n  const walkPages = walk.data?.pages;\n\n  // A cursor the server refuses is recoverable by construction: the query is\n  // fine and only the position is gone, so the walk starts again instead of\n  // stranding the reader on an error panel they cannot page out of. Resetting\n  // is what does it — refetching would replay the very cursors that were\n  // refused, page by page.\n  //\n  // Guarded on a page having already been fetched, because only then can a\n  // cursor have been sent. A first page refused this way is a server that\n  // answers `cursor_stale` to a request carrying no cursor, and restarting on\n  // that spins: refuse, restart, refuse.\n  const staleWalk = isCursorStale(walk.error) && (walkPages?.length ?? 0) > 0;\n\n  useEffect(() => {\n    if (!staleWalk) return;\n    void queryClient.resetQueries({ queryKey: walkKey });\n  }, [queryClient, staleWalk, walkKey]);\n\n  const fetchNextPage = walk.fetchNextPage;\n  const infinite = useMemo<DataTableInfinite | undefined>(() => {\n    if (!walkMode || !cursorParam) return undefined;\n    return {\n      hasMore: walk.hasNextPage,\n      loading: walk.isFetchingNextPage,\n      onLoadMore: () => void fetchNextPage(),\n    };\n  }, [cursorParam, fetchNextPage, walk.hasNextPage, walk.isFetchingNextPage, walkMode]);\n\n  const resetWalk = useCallback(() => {\n    void queryClient.resetQueries({ queryKey: walkKey });\n  }, [queryClient, walkKey]);\n  const refetchSingle = single.refetch;\n\n  if (!walkMode) {\n    return {\n      pages: single.data ? [single.data] : [],\n      response: single.data ?? null,\n      isFetching: single.isFetching,\n      isPending: single.isPending,\n      isError: single.isError,\n      error: single.error,\n      refetch: () => void refetchSingle(),\n    };\n  }\n\n  const pages = walkPages ?? [];\n  return {\n    pages,\n    response: pages[pages.length - 1] ?? null,\n    // Fetching the next page grows the run; it does not replace it. Reporting\n    // it as a load of the whole surface is what drops a spinner over rows the\n    // reader is still reading.\n    isFetching: walk.isFetching && !walk.isFetchingNextPage,\n    isPending: walk.isPending,\n    isError: walk.isError && !staleWalk,\n    error: staleWalk ? undefined : walk.error,\n    // A mutation just changed the rows this walk was cut from, so its cursors\n    // no longer name positions in it. Starting over is the only honest refetch.\n    refetch: resetWalk,\n    ...(infinite ? { infinite } : {}),\n  };\n}\n"],"names":["useQueryClient","cursorParameterName","useMemo","useCallback","packParameterValues","useQuery","keepPreviousData","useInfiniteQuery","_a","isCursorStale","useEffect"],"mappings":"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"}

package/dist/rpc/useOperationPages.d.ts

@@ -10,6 +10,8 @@ export type OperationPagesOptions = {
     parameters: OpenAPIParameter[];
     /** Current filter/pagination state, as the catalog holds and URL-mirrors it. */
     filters: ParameterValues;
+    /** Omit to infer a cursor walk from the operation; hosts may force either presentation. */
+    paginationMode?: "paged" | "infinite";
 };
 export type OperationPages = {
     /** Every page fetched so far, oldest first. One entry outside a walk. */
@@ -28,12 +30,14 @@ export type OperationPages = {
 };
 /**
  * useOperationPages runs a surface's list operation, walking it forward when it
- * declares a cursor and fetching a single page when it does not.
+ * declares a cursor and fetching a single page when it does not. A host can
+ * explicitly keep a cursor-capable operation paged when readers need offset
+ * controls; omission retains automatic selection.
  *
- * The mode is the operation's to decide, not the caller's: a cursor role is the
- * server saying "you may resume this query", and everything else — the majority
- * of surfaces — keeps the single-page query it has always had, replacing its
- * rows when the offset moves.
+ * Automatic mode follows the operation: a cursor role is the server saying
+ * "you may resume this query", and everything else keeps the single-page query
+ * it has always had. An explicit host override changes only the presentation;
+ * the operation still owns the available cursor and offset capabilities.
  *
  * In walk mode the cursor is deliberately absent from the query key. The key is
  * the identity of the query being walked, and the cursor is a position inside
@@ -42,5 +46,5 @@ export type OperationPages = {
  * stays in the key, so any filter, parameter or time-range change starts a new
  * walk on its own, with no reset logic layered on top.
  */
-export declare function useOperationPages({ client, endpoint, parameters, filters, }: OperationPagesOptions): OperationPages;
+export declare function useOperationPages({ client, endpoint, parameters, filters, paginationMode, }: OperationPagesOptions): OperationPages;
 //# sourceMappingURL=useOperationPages.d.ts.map

package/dist/rpc/useOperationPages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOperationPages.d.ts","sourceRoot":"","sources":["../../src/rpc/useOperationPages.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAK3D,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACxC,8EAA8E;IAC9E,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,gFAAgF;IAChF,OAAO,EAAE,eAAe,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,yEAAyE;IACzE,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACnC,8EAA8E;IAC9E,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,2EAA2E;IAC3E,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,MAAM,EACN,QAAQ,EACR,UAAU,EACV,OAAO,GACR,EAAE,qBAAqB,GAAG,cAAc,CAoIxC"}
+{"version":3,"file":"useOperationPages.d.ts","sourceRoot":"","sources":["../../src/rpc/useOperationPages.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAK3D,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACxC,8EAA8E;IAC9E,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,gFAAgF;IAChF,OAAO,EAAE,eAAe,CAAC;IACzB,2FAA2F;IAC3F,cAAc,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,yEAAyE;IACzE,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACnC,8EAA8E;IAC9E,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,2EAA2E;IAC3E,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,MAAM,EACN,QAAQ,EACR,UAAU,EACV,OAAO,EACP,cAAc,GACf,EAAE,qBAAqB,GAAG,cAAc,CA0IxC"}

package/dist/rpc/useOperationPages.js

@@ -8,13 +8,20 @@ function useOperationPages({
   client,
   endpoint,
   parameters,
-  filters
+  filters,
+  paginationMode
 }) {
   var _a;
   const queryClient = useQueryClient();
   const cursorParam = cursorParameterName(parameters);
   const path = endpoint == null ? void 0 : endpoint.path;
   const method = endpoint == null ? void 0 : endpoint.method;
+  if (endpoint && paginationMode === "infinite" && !cursorParam) {
+    throw new Error(
+      `Operation ${method == null ? void 0 : method.toUpperCase()} ${path} cannot use infinite pagination without a cursor parameter`
+    );
+  }
+  const walkMode = paginationMode === "infinite" || paginationMode === void 0 && !!cursorParam;
   const walkFilters = useMemo(() => {
     if (!cursorParam) return filters;
     const rest = { ...filters };
@@ -33,7 +40,7 @@ function useOperationPages({
   const single = useQuery({
     queryKey: [LIST_KEY, method, path, filters],
     queryFn: () => execute(filters),
-    enabled: !!endpoint && !cursorParam,
+    enabled: !!endpoint && !walkMode,
     placeholderData: keepPreviousData,
     staleTime: 3e4,
     retry: 0
@@ -53,7 +60,7 @@ function useOperationPages({
       var _a2;
       return ((_a2 = lastPage.pagination) == null ? void 0 : _a2.hasMore) ? lastPage.pagination.nextCursor : void 0;
     },
-    enabled: !!endpoint && !!cursorParam,
+    enabled: !!endpoint && walkMode,
     placeholderData: keepPreviousData,
     staleTime: 3e4,
     retry: 0
@@ -66,18 +73,18 @@ function useOperationPages({
   }, [queryClient, staleWalk, walkKey]);
   const fetchNextPage = walk.fetchNextPage;
   const infinite = useMemo(() => {
-    if (!cursorParam) return void 0;
+    if (!walkMode || !cursorParam) return void 0;
     return {
       hasMore: walk.hasNextPage,
       loading: walk.isFetchingNextPage,
       onLoadMore: () => void fetchNextPage()
     };
-  }, [cursorParam, fetchNextPage, walk.hasNextPage, walk.isFetchingNextPage]);
+  }, [cursorParam, fetchNextPage, walk.hasNextPage, walk.isFetchingNextPage, walkMode]);
   const resetWalk = useCallback(() => {
     void queryClient.resetQueries({ queryKey: walkKey });
   }, [queryClient, walkKey]);
   const refetchSingle = single.refetch;
-  if (!cursorParam) {
+  if (!walkMode) {
     return {
       pages: single.data ? [single.data] : [],
       response: single.data ?? null,

package/dist/rpc/useOperationPages.js.map

@@ -1 +1 @@
-{"version":3,"file":"useOperationPages.js","sources":["../../src/rpc/useOperationPages.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo } from \"react\";\nimport {\n  keepPreviousData,\n  useInfiniteQuery,\n  useQuery,\n  useQueryClient,\n  type InfiniteData,\n  type QueryKey,\n} from \"@tanstack/react-query\";\n\nimport type { DataTableInfinite } from \"../data/DataTable\";\nimport { cursorParameterName, isCursorStale } from \"./cursorStale\";\nimport { packParameterValues, type ParameterValues } from \"./formMetadata\";\nimport type {\n  ExecutionResponse,\n  OpenAPIParameter,\n  ResolvedOperation,\n} from \"./types\";\nimport type { OperationsApiClient } from \"./useOperations\";\n\nconst LIST_KEY = \"operation-list\";\nconst CLICKY_HEADERS = { Accept: \"application/json+clicky\" };\n\nexport type OperationPagesOptions = {\n  client: OperationsApiClient;\n  /** The list operation, or undefined for a surface that has none. */\n  endpoint: ResolvedOperation | undefined;\n  /** Every parameter the operation declares — the source of the cursor role. */\n  parameters: OpenAPIParameter[];\n  /** Current filter/pagination state, as the catalog holds and URL-mirrors it. */\n  filters: ParameterValues;\n};\n\nexport type OperationPages = {\n  /** Every page fetched so far, oldest first. One entry outside a walk. */\n  pages: ExecutionResponse[];\n  /** The newest page — what every renderer means by \"the response\". */\n  response: ExecutionResponse | null;\n  /** True while the whole result is being replaced, not while it is growing. */\n  isFetching: boolean;\n  isPending: boolean;\n  isError: boolean;\n  error: unknown;\n  /** Re-runs the list. A walk restarts rather than replaying its cursors. */\n  refetch: () => void;\n  /** Load-more handle; absent unless the operation can walk by cursor. */\n  infinite?: DataTableInfinite;\n};\n\n/**\n * useOperationPages runs a surface's list operation, walking it forward when it\n * declares a cursor and fetching a single page when it does not.\n *\n * The mode is the operation's to decide, not the caller's: a cursor role is the\n * server saying \"you may resume this query\", and everything else — the majority\n * of surfaces — keeps the single-page query it has always had, replacing its\n * rows when the offset moves.\n *\n * In walk mode the cursor is deliberately absent from the query key. The key is\n * the identity of the query being walked, and the cursor is a position inside\n * it; keying on it made every page a different query, which is precisely why\n * advancing replaced the rows instead of extending them. Every other filter\n * stays in the key, so any filter, parameter or time-range change starts a new\n * walk on its own, with no reset logic layered on top.\n */\nexport function useOperationPages({\n  client,\n  endpoint,\n  parameters,\n  filters,\n}: OperationPagesOptions): OperationPages {\n  const queryClient = useQueryClient();\n  const cursorParam = cursorParameterName(parameters);\n  const path = endpoint?.path;\n  const method = endpoint?.method;\n\n  // The walk's own view of the filters: everything that identifies the query,\n  // with the position taken out. A cursor left over in the URL from a shared\n  // link names a position in a walk this session never made, so it is dropped\n  // rather than replayed.\n  const walkFilters = useMemo(() => {\n    if (!cursorParam) return filters;\n    const rest = { ...filters };\n    delete rest[cursorParam];\n    return rest;\n  }, [cursorParam, filters]);\n\n  const execute = useCallback(\n    (values: ParameterValues) =>\n      client.executeCommand(\n        path!,\n        method!,\n        packParameterValues(values, parameters),\n        CLICKY_HEADERS,\n      ),\n    [client, method, parameters, path],\n  );\n\n  // Both queries are declared on every render — hooks are not conditional — and\n  // exactly one is enabled. Their keys differ in shape as well as content, so a\n  // surface that switches modes can never read a page array as a page.\n  const single = useQuery<ExecutionResponse>({\n    queryKey: [LIST_KEY, method, path, filters],\n    queryFn: () => execute(filters),\n    enabled: !!endpoint && !cursorParam,\n    placeholderData: keepPreviousData,\n    staleTime: 30_000,\n    retry: 0,\n  });\n\n  // Prefixed with the same LIST_KEY as the single-page query: host apps\n  // invalidate [\"operation-list\"] after a mutation, and a walk that fell\n  // outside that prefix would keep serving rows the mutation changed.\n  const walkKey = useMemo(\n    () => [LIST_KEY, \"walk\", method, path, walkFilters],\n    [method, path, walkFilters],\n  );\n\n  const walk = useInfiniteQuery<\n    ExecutionResponse,\n    Error,\n    InfiniteData<ExecutionResponse, string | undefined>,\n    QueryKey,\n    string | undefined\n  >({\n    queryKey: walkKey,\n    queryFn: ({ pageParam }) =>\n      execute(pageParam ? { ...walkFilters, [cursorParam!]: pageParam } : walkFilters),\n    initialPageParam: undefined,\n    // The server's two answers, both required: it has more, and here is where\n    // to resume. A page claiming more without minting a token cannot be walked,\n    // and guessing one is how a client forges a position it was never given.\n    getNextPageParam: (lastPage) =>\n      lastPage.pagination?.hasMore ? lastPage.pagination.nextCursor : undefined,\n    enabled: !!endpoint && !!cursorParam,\n    placeholderData: keepPreviousData,\n    staleTime: 30_000,\n    retry: 0,\n  });\n\n  const walkPages = walk.data?.pages;\n\n  // A cursor the server refuses is recoverable by construction: the query is\n  // fine and only the position is gone, so the walk starts again instead of\n  // stranding the reader on an error panel they cannot page out of. Resetting\n  // is what does it — refetching would replay the very cursors that were\n  // refused, page by page.\n  //\n  // Guarded on a page having already been fetched, because only then can a\n  // cursor have been sent. A first page refused this way is a server that\n  // answers `cursor_stale` to a request carrying no cursor, and restarting on\n  // that spins: refuse, restart, refuse.\n  const staleWalk = isCursorStale(walk.error) && (walkPages?.length ?? 0) > 0;\n\n  useEffect(() => {\n    if (!staleWalk) return;\n    void queryClient.resetQueries({ queryKey: walkKey });\n  }, [queryClient, staleWalk, walkKey]);\n\n  const fetchNextPage = walk.fetchNextPage;\n  const infinite = useMemo<DataTableInfinite | undefined>(() => {\n    if (!cursorParam) return undefined;\n    return {\n      hasMore: walk.hasNextPage,\n      loading: walk.isFetchingNextPage,\n      onLoadMore: () => void fetchNextPage(),\n    };\n  }, [cursorParam, fetchNextPage, walk.hasNextPage, walk.isFetchingNextPage]);\n\n  const resetWalk = useCallback(() => {\n    void queryClient.resetQueries({ queryKey: walkKey });\n  }, [queryClient, walkKey]);\n  const refetchSingle = single.refetch;\n\n  if (!cursorParam) {\n    return {\n      pages: single.data ? [single.data] : [],\n      response: single.data ?? null,\n      isFetching: single.isFetching,\n      isPending: single.isPending,\n      isError: single.isError,\n      error: single.error,\n      refetch: () => void refetchSingle(),\n    };\n  }\n\n  const pages = walkPages ?? [];\n  return {\n    pages,\n    response: pages[pages.length - 1] ?? null,\n    // Fetching the next page grows the run; it does not replace it. Reporting\n    // it as a load of the whole surface is what drops a spinner over rows the\n    // reader is still reading.\n    isFetching: walk.isFetching && !walk.isFetchingNextPage,\n    isPending: walk.isPending,\n    isError: walk.isError && !staleWalk,\n    error: staleWalk ? undefined : walk.error,\n    // A mutation just changed the rows this walk was cut from, so its cursors\n    // no longer name positions in it. Starting over is the only honest refetch.\n    refetch: resetWalk,\n    ...(infinite ? { infinite } : {}),\n  };\n}\n"],"names":["_a"],"mappings":"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"}
+{"version":3,"file":"useOperationPages.js","sources":["../../src/rpc/useOperationPages.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo } from \"react\";\nimport {\n  keepPreviousData,\n  useInfiniteQuery,\n  useQuery,\n  useQueryClient,\n  type InfiniteData,\n  type QueryKey,\n} from \"@tanstack/react-query\";\n\nimport type { DataTableInfinite } from \"../data/DataTable\";\nimport { cursorParameterName, isCursorStale } from \"./cursorStale\";\nimport { packParameterValues, type ParameterValues } from \"./formMetadata\";\nimport type {\n  ExecutionResponse,\n  OpenAPIParameter,\n  ResolvedOperation,\n} from \"./types\";\nimport type { OperationsApiClient } from \"./useOperations\";\n\nconst LIST_KEY = \"operation-list\";\nconst CLICKY_HEADERS = { Accept: \"application/json+clicky\" };\n\nexport type OperationPagesOptions = {\n  client: OperationsApiClient;\n  /** The list operation, or undefined for a surface that has none. */\n  endpoint: ResolvedOperation | undefined;\n  /** Every parameter the operation declares — the source of the cursor role. */\n  parameters: OpenAPIParameter[];\n  /** Current filter/pagination state, as the catalog holds and URL-mirrors it. */\n  filters: ParameterValues;\n  /** Omit to infer a cursor walk from the operation; hosts may force either presentation. */\n  paginationMode?: \"paged\" | \"infinite\";\n};\n\nexport type OperationPages = {\n  /** Every page fetched so far, oldest first. One entry outside a walk. */\n  pages: ExecutionResponse[];\n  /** The newest page — what every renderer means by \"the response\". */\n  response: ExecutionResponse | null;\n  /** True while the whole result is being replaced, not while it is growing. */\n  isFetching: boolean;\n  isPending: boolean;\n  isError: boolean;\n  error: unknown;\n  /** Re-runs the list. A walk restarts rather than replaying its cursors. */\n  refetch: () => void;\n  /** Load-more handle; absent unless the operation can walk by cursor. */\n  infinite?: DataTableInfinite;\n};\n\n/**\n * useOperationPages runs a surface's list operation, walking it forward when it\n * declares a cursor and fetching a single page when it does not. A host can\n * explicitly keep a cursor-capable operation paged when readers need offset\n * controls; omission retains automatic selection.\n *\n * Automatic mode follows the operation: a cursor role is the server saying\n * \"you may resume this query\", and everything else keeps the single-page query\n * it has always had. An explicit host override changes only the presentation;\n * the operation still owns the available cursor and offset capabilities.\n *\n * In walk mode the cursor is deliberately absent from the query key. The key is\n * the identity of the query being walked, and the cursor is a position inside\n * it; keying on it made every page a different query, which is precisely why\n * advancing replaced the rows instead of extending them. Every other filter\n * stays in the key, so any filter, parameter or time-range change starts a new\n * walk on its own, with no reset logic layered on top.\n */\nexport function useOperationPages({\n  client,\n  endpoint,\n  parameters,\n  filters,\n  paginationMode,\n}: OperationPagesOptions): OperationPages {\n  const queryClient = useQueryClient();\n  const cursorParam = cursorParameterName(parameters);\n  const path = endpoint?.path;\n  const method = endpoint?.method;\n  if (endpoint && paginationMode === \"infinite\" && !cursorParam) {\n    throw new Error(\n      `Operation ${method?.toUpperCase()} ${path} cannot use infinite pagination without a cursor parameter`,\n    );\n  }\n  const walkMode = paginationMode === \"infinite\" || (paginationMode === undefined && !!cursorParam);\n\n  // The walk's own view of the filters: everything that identifies the query,\n  // with the position taken out. A cursor left over in the URL from a shared\n  // link names a position in a walk this session never made, so it is dropped\n  // rather than replayed.\n  const walkFilters = useMemo(() => {\n    if (!cursorParam) return filters;\n    const rest = { ...filters };\n    delete rest[cursorParam];\n    return rest;\n  }, [cursorParam, filters]);\n\n  const execute = useCallback(\n    (values: ParameterValues) =>\n      client.executeCommand(\n        path!,\n        method!,\n        packParameterValues(values, parameters),\n        CLICKY_HEADERS,\n      ),\n    [client, method, parameters, path],\n  );\n\n  // Both queries are declared on every render — hooks are not conditional — and\n  // exactly one is enabled. Their keys differ in shape as well as content, so a\n  // surface that switches modes can never read a page array as a page.\n  const single = useQuery<ExecutionResponse>({\n    queryKey: [LIST_KEY, method, path, filters],\n    queryFn: () => execute(filters),\n    enabled: !!endpoint && !walkMode,\n    placeholderData: keepPreviousData,\n    staleTime: 30_000,\n    retry: 0,\n  });\n\n  // Prefixed with the same LIST_KEY as the single-page query: host apps\n  // invalidate [\"operation-list\"] after a mutation, and a walk that fell\n  // outside that prefix would keep serving rows the mutation changed.\n  const walkKey = useMemo(\n    () => [LIST_KEY, \"walk\", method, path, walkFilters],\n    [method, path, walkFilters],\n  );\n\n  const walk = useInfiniteQuery<\n    ExecutionResponse,\n    Error,\n    InfiniteData<ExecutionResponse, string | undefined>,\n    QueryKey,\n    string | undefined\n  >({\n    queryKey: walkKey,\n    queryFn: ({ pageParam }) =>\n      execute(pageParam ? { ...walkFilters, [cursorParam!]: pageParam } : walkFilters),\n    initialPageParam: undefined,\n    // The server's two answers, both required: it has more, and here is where\n    // to resume. A page claiming more without minting a token cannot be walked,\n    // and guessing one is how a client forges a position it was never given.\n    getNextPageParam: (lastPage) =>\n      lastPage.pagination?.hasMore ? lastPage.pagination.nextCursor : undefined,\n    enabled: !!endpoint && walkMode,\n    placeholderData: keepPreviousData,\n    staleTime: 30_000,\n    retry: 0,\n  });\n\n  const walkPages = walk.data?.pages;\n\n  // A cursor the server refuses is recoverable by construction: the query is\n  // fine and only the position is gone, so the walk starts again instead of\n  // stranding the reader on an error panel they cannot page out of. Resetting\n  // is what does it — refetching would replay the very cursors that were\n  // refused, page by page.\n  //\n  // Guarded on a page having already been fetched, because only then can a\n  // cursor have been sent. A first page refused this way is a server that\n  // answers `cursor_stale` to a request carrying no cursor, and restarting on\n  // that spins: refuse, restart, refuse.\n  const staleWalk = isCursorStale(walk.error) && (walkPages?.length ?? 0) > 0;\n\n  useEffect(() => {\n    if (!staleWalk) return;\n    void queryClient.resetQueries({ queryKey: walkKey });\n  }, [queryClient, staleWalk, walkKey]);\n\n  const fetchNextPage = walk.fetchNextPage;\n  const infinite = useMemo<DataTableInfinite | undefined>(() => {\n    if (!walkMode || !cursorParam) return undefined;\n    return {\n      hasMore: walk.hasNextPage,\n      loading: walk.isFetchingNextPage,\n      onLoadMore: () => void fetchNextPage(),\n    };\n  }, [cursorParam, fetchNextPage, walk.hasNextPage, walk.isFetchingNextPage, walkMode]);\n\n  const resetWalk = useCallback(() => {\n    void queryClient.resetQueries({ queryKey: walkKey });\n  }, [queryClient, walkKey]);\n  const refetchSingle = single.refetch;\n\n  if (!walkMode) {\n    return {\n      pages: single.data ? [single.data] : [],\n      response: single.data ?? null,\n      isFetching: single.isFetching,\n      isPending: single.isPending,\n      isError: single.isError,\n      error: single.error,\n      refetch: () => void refetchSingle(),\n    };\n  }\n\n  const pages = walkPages ?? [];\n  return {\n    pages,\n    response: pages[pages.length - 1] ?? null,\n    // Fetching the next page grows the run; it does not replace it. Reporting\n    // it as a load of the whole surface is what drops a spinner over rows the\n    // reader is still reading.\n    isFetching: walk.isFetching && !walk.isFetchingNextPage,\n    isPending: walk.isPending,\n    isError: walk.isError && !staleWalk,\n    error: staleWalk ? undefined : walk.error,\n    // A mutation just changed the rows this walk was cut from, so its cursors\n    // no longer name positions in it. Starting over is the only honest refetch.\n    refetch: resetWalk,\n    ...(infinite ? { infinite } : {}),\n  };\n}\n"],"names":["_a"],"mappings":"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"}

package/dist/rpc/useSession.cjs

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const reactQuery = require("@tanstack/react-query");
+const react = require("react");
+const sessionTypes = require("./sessionTypes.cjs");
+const string = require("../lib/string.cjs");
+const SESSION_POLL_MS = 2e3;
+const DEFAULT_BASE_PATH = "/api/v1";
+function sessionPath(basePath, id, action, durationMs) {
+  const path = `${string.stripTrailingSlashes(basePath)}/sessions/${encodeURIComponent(id)}`;
+  if (!action) return path;
+  if (action === "stop") return `${path}/stop`;
+  if (durationMs === void 0) throw new Error(`session ${action} requires a duration`);
+  return `${path}/${action}?duration=${sessionTypes.sessionDurationParam(durationMs)}`;
+}
+async function requestSession(client, path, method) {
+  const response = await client.executeCommand(path, method, {});
+  if (!response.success) {
+    throw new Error(
+      `${method} ${path} failed: ${response.error || response.stderr || response.stdout || `exit ${response.exit_code}`}`
+    );
+  }
+  return sessionTypes.parseSessionInfo(response.parsed, `${method} ${path}`);
+}
+function useSession(id, options) {
+  var _a;
+  const { client, basePath = DEFAULT_BASE_PATH, pollMs = SESSION_POLL_MS } = options;
+  if (!id) throw new Error("useSession requires a session id");
+  const queryClient = reactQuery.useQueryClient();
+  const queryKey = ["commons-db-session", basePath, id];
+  const query = reactQuery.useQuery({
+    queryKey,
+    queryFn: () => requestSession(client, sessionPath(basePath, id), "GET"),
+    refetchInterval: (current) => {
+      var _a2;
+      if (current.state.status === "error") return false;
+      const state = (_a2 = current.state.data) == null ? void 0 : _a2.state;
+      return state !== void 0 && sessionTypes.isSessionTerminal(state) ? false : pollMs;
+    }
+  });
+  const [actionError, setActionError] = react.useState(void 0);
+  const mutation = reactQuery.useMutation({
+    // A poll already in flight read the session before this action; landing
+    // after the action's answer, it would put back the old state or stopAt.
+    onMutate: () => queryClient.cancelQueries({ queryKey }),
+    mutationFn: ({ action, durationMs }) => requestSession(client, sessionPath(basePath, id, action, durationMs), "POST"),
+    onSuccess: (next, { action }) => {
+      if (action === "restart") {
+        void queryClient.invalidateQueries({ queryKey });
+        return;
+      }
+      queryClient.setQueryData(queryKey, next);
+    }
+  });
+  const { mutateAsync } = mutation;
+  const run = react.useCallback(
+    async (request) => {
+      setActionError(void 0);
+      try {
+        sessionPath(basePath, id, request.action, request.durationMs);
+        return await mutateAsync(request);
+      } catch (cause) {
+        setActionError(cause);
+        throw cause;
+      }
+    },
+    [basePath, id, mutateAsync]
+  );
+  return {
+    session: query.data,
+    error: query.error ?? void 0,
+    isLoading: query.isLoading,
+    refetch: query.refetch,
+    pendingAction: mutation.isPending ? ((_a = mutation.variables) == null ? void 0 : _a.action) ?? null : null,
+    actionError,
+    stop: react.useCallback(() => run({ action: "stop" }), [run]),
+    extend: react.useCallback((durationMs) => run({ action: "extend", durationMs }), [run]),
+    restart: react.useCallback(
+      ({ durationMs }) => run({ action: "restart", durationMs }),
+      [run]
+    )
+  };
+}
+exports.SESSION_POLL_MS = SESSION_POLL_MS;
+exports.useSession = useSession;
+//# sourceMappingURL=useSession.cjs.map

package/dist/rpc/useSession.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSession.cjs","sources":["../../src/rpc/useSession.ts"],"sourcesContent":["import { useMutation, useQuery, useQueryClient } from \"@tanstack/react-query\";\nimport { useCallback, useState } from \"react\";\nimport type { OperationsApiClient } from \"./useOperations\";\nimport {\n  isSessionTerminal,\n  parseSessionInfo,\n  sessionDurationParam,\n  type SessionInfo,\n} from \"./sessionTypes\";\nimport { stripTrailingSlashes } from \"../lib/string\";\n\n// useSession reads one commons-db query session for a session page and drives\n// its control routes. It polls rather than subscribing: SessionInfo changes a\n// few times a minute (state, heartbeat, eventCount), and the events a page\n// renders ride their own record-results stream, so a 2s refetch is enough —\n// and it stops the moment the session reaches a state nothing can leave.\n\nexport const SESSION_POLL_MS = 2_000;\n\nexport type SessionAction = \"stop\" | \"extend\" | \"restart\";\n\nexport type UseSessionOptions = {\n  /** The host's API client; its base URL, headers and credentials apply to every request. */\n  client: OperationsApiClient;\n  /** Where the sessions API is mounted. Defaults to \"/api/v1\". */\n  basePath?: string;\n  /** Refetch interval while the session is active. Defaults to SESSION_POLL_MS. */\n  pollMs?: number;\n};\n\nexport type UseSessionResult = {\n  session: SessionInfo | undefined;\n  /** The last read's failure, including a response that broke the SessionInfo contract. Polling stops on it. */\n  error: unknown;\n  isLoading: boolean;\n  refetch: () => Promise<unknown>;\n  /** The control request in flight, if any. */\n  pendingAction: SessionAction | null;\n  /**\n   * The last control request's failure, undefined once the next action starts.\n   * The action's promise still rejects with it; a host that renders this\n   * (SessionHeader's `actionError`) need not catch it again.\n   */\n  actionError: unknown;\n  /** POST {basePath}/sessions/{id}/stop; resolves with the session as the server reports it afterwards. */\n  stop: () => Promise<SessionInfo>;\n  /** POST {basePath}/sessions/{id}/extend?duration=<ms>ms. */\n  extend: (durationMs: number) => Promise<SessionInfo>;\n  /** POST {basePath}/sessions/{id}/restart?duration=<ms>ms; resolves with the NEW session. */\n  restart: (options: { durationMs: number }) => Promise<SessionInfo>;\n};\n\nconst DEFAULT_BASE_PATH = \"/api/v1\";\n\ntype ActionRequest = { action: SessionAction; durationMs?: number };\n\nfunction sessionPath(basePath: string, id: string, action?: SessionAction, durationMs?: number) {\n  const path = `${stripTrailingSlashes(basePath)}/sessions/${encodeURIComponent(id)}`;\n  if (!action) return path;\n  if (action === \"stop\") return `${path}/stop`;\n  if (durationMs === undefined) throw new Error(`session ${action} requires a duration`);\n  return `${path}/${action}?duration=${sessionDurationParam(durationMs)}`;\n}\n\nasync function requestSession(\n  client: OperationsApiClient,\n  path: string,\n  method: \"GET\" | \"POST\",\n): Promise<SessionInfo> {\n  const response = await client.executeCommand(path, method, {});\n  if (!response.success) {\n    throw new Error(\n      `${method} ${path} failed: ${response.error || response.stderr || response.stdout || `exit ${response.exit_code}`}`,\n    );\n  }\n  return parseSessionInfo(response.parsed, `${method} ${path}`);\n}\n\nexport function useSession(id: string, options: UseSessionOptions): UseSessionResult {\n  const { client, basePath = DEFAULT_BASE_PATH, pollMs = SESSION_POLL_MS } = options;\n  if (!id) throw new Error(\"useSession requires a session id\");\n  const queryClient = useQueryClient();\n  const queryKey = [\"commons-db-session\", basePath, id];\n\n  const query = useQuery<SessionInfo>({\n    queryKey,\n    queryFn: () => requestSession(client, sessionPath(basePath, id), \"GET\"),\n    refetchInterval: (current) => {\n      if (current.state.status === \"error\") return false;\n      const state = current.state.data?.state;\n      return state !== undefined && isSessionTerminal(state) ? false : pollMs;\n    },\n  });\n\n  const [actionError, setActionError] = useState<unknown>(undefined);\n\n  const mutation = useMutation<SessionInfo, unknown, ActionRequest>({\n    // A poll already in flight read the session before this action; landing\n    // after the action's answer, it would put back the old state or stopAt.\n    onMutate: () => queryClient.cancelQueries({ queryKey }),\n    mutationFn: ({ action, durationMs }) =>\n      requestSession(client, sessionPath(basePath, id, action, durationMs), \"POST\"),\n    onSuccess: (next, { action }) => {\n      // A restart answers with the session it created; this id only gains a\n      // `restartedAs` entry, which the next read derives.\n      if (action === \"restart\") {\n        void queryClient.invalidateQueries({ queryKey });\n        return;\n      }\n      queryClient.setQueryData(queryKey, next);\n    },\n  });\n\n  const { mutateAsync } = mutation;\n  const run = useCallback(\n    async (request: ActionRequest) => {\n      setActionError(undefined);\n      try {\n        // Validated before the mutation so a bad duration never reaches the wire.\n        sessionPath(basePath, id, request.action, request.durationMs);\n        return await mutateAsync(request);\n      } catch (cause) {\n        setActionError(cause);\n        throw cause;\n      }\n    },\n    [basePath, id, mutateAsync],\n  );\n\n  return {\n    session: query.data,\n    error: query.error ?? undefined,\n    isLoading: query.isLoading,\n    refetch: query.refetch,\n    pendingAction: mutation.isPending ? (mutation.variables?.action ?? null) : null,\n    actionError,\n    stop: useCallback(() => run({ action: \"stop\" }), [run]),\n    extend: useCallback((durationMs: number) => run({ action: \"extend\", durationMs }), [run]),\n    restart: useCallback(\n      ({ durationMs }: { durationMs: number }) => run({ action: \"restart\", durationMs }),\n      [run],\n    ),\n  };\n}\n"],"names":["stripTrailingSlashes","sessionDurationParam","parseSessionInfo","useQueryClient","useQuery","_a","isSessionTerminal","useState","useMutation","useCallback"],"mappings":"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"}