@vielzeug/sourcerer 1.0.2

package/README.md

@@ -0,0 +1,86 @@
+# @vielzeug/sourcerer
+
+> Typed reactive data sources for pagination, filtering, sorting, search, and infinite scroll.
+
+[![npm version](https://img.shields.io/npm/v/@vielzeug/sourcerer)](https://www.npmjs.com/package/@vielzeug/sourcerer) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`@vielzeug/sourcerer` is part of Vielzeug and ships as a TypeScript package with ESM+CJS output.
+
+## Installation
+
+```sh
+pnpm add @vielzeug/sourcerer
+npm install @vielzeug/sourcerer
+yarn add @vielzeug/sourcerer
+```
+
+## Quick Start
+
+```ts
+import { createLocalSource } from '@vielzeug/sourcerer';
+
+const source = createLocalSource(
+  [
+    { id: 1, name: 'Ada' },
+    { id: 2, name: 'Grace' },
+    { id: 3, name: 'Linus' },
+  ],
+  { limit: 2 },
+);
+
+await source.search('a', { immediate: true });
+console.log(source.current); // [{ id: 1, name: 'Ada' }]
+console.log(source.meta.pageNumber); // 1
+```
+
+```ts
+import { createRemoteSource } from '@vielzeug/sourcerer';
+
+const source = createRemoteSource({
+  fetch: async ({ limit, page, search }, signal) => {
+    const res = await fetch(`/api/users?page=${page}&limit=${limit}&q=${search ?? ''}`, { signal });
+    return res.json(); // { items: User[], total: number }
+  },
+  limit: 20,
+});
+
+// autoFetch is true by default — initial data loads immediately
+await source.ready();
+console.log(source.current, source.meta.totalItems);
+```
+
+## Sources Overview
+
+| Factory                  | Data model         | Navigation                |
+| ------------------------ | ------------------ | ------------------------- |
+| `createLocalSource()`    | In-memory array    | Page number               |
+| `createRemoteSource()`   | Async server fetch | Page number               |
+| `createCursorSource()`   | Async server fetch | Cursor tokens (next/prev) |
+| `createInfiniteSource()` | Async server fetch | Append (load more)        |
+
+## Error Handling
+
+All async sources expose `meta.error` as a typed `SourceError | null` — not a plain string.
+`SourceError` extends `Error` and carries structured context:
+
+```ts
+import { sourceState } from '@vielzeug/sourcerer';
+
+const state = sourceState(source);
+if (state.status === 'error') {
+  console.error(state.error.message); // human-readable message
+  console.error(state.error.cause); // original thrown value
+  console.error(state.error.context); // structured context bag (query fields, kind, etc.)
+}
+```
+
+## Documentation
+
+- [Overview](https://vielzeug.dev/sourcerer/)
+- [Usage Guide](https://vielzeug.dev/sourcerer/usage)
+- [API Reference](https://vielzeug.dev/sourcerer/api)
+- [Examples](https://vielzeug.dev/sourcerer/examples)
+
+## License
+
+MIT © [Helmuth Saatkamp](https://github.com/helmuthdu) — part of the [Vielzeug](https://github.com/helmuthdu/vielzeug) monorepo.

package/dist/_dev.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=_dev.d.ts.map

package/dist/_dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dev.d.ts","sourceRoot":"","sources":["../src/_dev.ts"],"names":[],"mappings":""}

package/dist/_utils.cjs

@@ -0,0 +1,2 @@
+let e=require("@vielzeug/arsenal");var t=e.hash,n=e=>e instanceof Error?e.message:typeof e==`string`&&e.length>0?e:`Request failed`,r=t=>(0,e.backoff)(t);exports.defaultKeyOf=t,exports.defaultRetryDelay=r,exports.extractError=n;
+//# sourceMappingURL=_utils.cjs.map

package/dist/_utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"_utils.cjs","names":[],"sources":["../src/_utils.ts"],"sourcesContent":["import { backoff, hash, retry } from '@vielzeug/arsenal';\n\nexport { retry };\n\n// Internal stable-key helper — used by source factories, not exposed as public API.\nexport const defaultKeyOf = hash;\n\n/** Extracts a user-facing error message from a caught exception. */\nexport const extractError = (reason: unknown): string => {\n  if (reason instanceof Error) return reason.message;\n\n  if (typeof reason === 'string' && reason.length > 0) return reason;\n\n  return 'Request failed';\n};\n\n/** Default exponential backoff: 1 s, 2 s, 4 s, … capped at 30 s. Receives a 0-indexed failure count. */\nexport const defaultRetryDelay = (attempt: number): number => backoff(attempt);\n"],"mappings":"mCAKA,IAAa,EAAe,EAAA,KAGf,EAAgB,GACvB,aAAkB,MAAc,EAAO,QAEvC,OAAO,GAAW,UAAY,EAAO,OAAS,EAAU,EAErD,iBAII,EAAqB,IAAA,EAAA,EAAA,QAAA,CAAoC,CAAO"}

package/dist/_utils.d.ts

@@ -0,0 +1,8 @@
+import { hash, retry } from '@vielzeug/arsenal';
+export { retry };
+export declare const defaultKeyOf: typeof hash;
+/** Extracts a user-facing error message from a caught exception. */
+export declare const extractError: (reason: unknown) => string;
+/** Default exponential backoff: 1 s, 2 s, 4 s, … capped at 30 s. Receives a 0-indexed failure count. */
+export declare const defaultRetryDelay: (attempt: number) => number;
+//# sourceMappingURL=_utils.d.ts.map

package/dist/_utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_utils.d.ts","sourceRoot":"","sources":["../src/_utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,IAAI,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,KAAK,EAAE,CAAC;AAGjB,eAAO,MAAM,YAAY,aAAO,CAAC;AAEjC,oEAAoE;AACpE,eAAO,MAAM,YAAY,GAAI,QAAQ,OAAO,KAAG,MAM9C,CAAC;AAEF,wGAAwG;AACxG,eAAO,MAAM,iBAAiB,GAAI,SAAS,MAAM,KAAG,MAA0B,CAAC"}

package/dist/_utils.js

@@ -0,0 +1,7 @@
+import { backoff as e, hash as t, retry as n } from "@vielzeug/arsenal";
+//#region src/_utils.ts
+var r = t, i = (e) => e instanceof Error ? e.message : typeof e == "string" && e.length > 0 ? e : "Request failed", a = (t) => e(t);
+//#endregion
+export { r as defaultKeyOf, a as defaultRetryDelay, i as extractError, n as retry };
+
+//# sourceMappingURL=_utils.js.map

package/dist/_utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_utils.js","names":[],"sources":["../src/_utils.ts"],"sourcesContent":["import { backoff, hash, retry } from '@vielzeug/arsenal';\n\nexport { retry };\n\n// Internal stable-key helper — used by source factories, not exposed as public API.\nexport const defaultKeyOf = hash;\n\n/** Extracts a user-facing error message from a caught exception. */\nexport const extractError = (reason: unknown): string => {\n  if (reason instanceof Error) return reason.message;\n\n  if (typeof reason === 'string' && reason.length > 0) return reason;\n\n  return 'Request failed';\n};\n\n/** Default exponential backoff: 1 s, 2 s, 4 s, … capped at 30 s. Receives a 0-indexed failure count. */\nexport const defaultRetryDelay = (attempt: number): number => backoff(attempt);\n"],"mappings":";;AAKA,IAAa,IAAe,GAGf,KAAgB,MACvB,aAAkB,QAAc,EAAO,UAEvC,OAAO,KAAW,YAAY,EAAO,SAAS,IAAU,IAErD,kBAII,KAAqB,MAA4B,EAAQ,CAAO"}

package/dist/applyQuery.cjs

@@ -0,0 +1,2 @@
+function e(e,t){return e.patch(t)}exports.applyQuery=e;
+//# sourceMappingURL=applyQuery.cjs.map

package/dist/applyQuery.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyQuery.cjs","names":[],"sources":["../src/applyQuery.ts"],"sourcesContent":["import type { SourceQuery } from './types';\n\n/**\n * Generic query applicator — delegates to `source.patch(changes)`.\n * Use this with `decodeQuery()` output to restore URL state onto any source:\n *\n * @example\n * ```ts\n * const q = decodeQuery(new URL(location.href).searchParams, { defaultLimit: 20 });\n * await applyQuery(source, q);\n * ```\n *\n * ⚠️ `CursorSource` and `InfiniteSource` have no page-number concept (keyset/append navigation) —\n * their `patch()` only reads `limit`/`search` and silently ignores a `page` field. This compiles\n * (both accept `Partial<SourceQuery>`-shaped input) but a `page` value from `decodeQuery()` is a\n * no-op on those two source types.\n */\nexport function applyQuery<T extends { patch(changes: Partial<SourceQuery>): Promise<void> }>(\n  source: T,\n  changes: Partial<SourceQuery>,\n): Promise<void> {\n  return source.patch(changes);\n}\n"],"mappings":"AAiBA,SAAgB,EACd,EACA,EACe,CACf,OAAO,EAAO,MAAM,CAAO,CAC7B"}

package/dist/applyQuery.d.ts

@@ -0,0 +1,20 @@
+import type { SourceQuery } from './types';
+/**
+ * Generic query applicator — delegates to `source.patch(changes)`.
+ * Use this with `decodeQuery()` output to restore URL state onto any source:
+ *
+ * @example
+ * ```ts
+ * const q = decodeQuery(new URL(location.href).searchParams, { defaultLimit: 20 });
+ * await applyQuery(source, q);
+ * ```
+ *
+ * ⚠️ `CursorSource` and `InfiniteSource` have no page-number concept (keyset/append navigation) —
+ * their `patch()` only reads `limit`/`search` and silently ignores a `page` field. This compiles
+ * (both accept `Partial<SourceQuery>`-shaped input) but a `page` value from `decodeQuery()` is a
+ * no-op on those two source types.
+ */
+export declare function applyQuery<T extends {
+    patch(changes: Partial<SourceQuery>): Promise<void>;
+}>(source: T, changes: Partial<SourceQuery>): Promise<void>;
+//# sourceMappingURL=applyQuery.d.ts.map

package/dist/applyQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyQuery.d.ts","sourceRoot":"","sources":["../src/applyQuery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS;IAAE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,EAC1F,MAAM,EAAE,CAAC,EACT,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/dist/applyQuery.js

@@ -0,0 +1,8 @@
+//#region src/applyQuery.ts
+function e(e, t) {
+	return e.patch(t);
+}
+//#endregion
+export { e as applyQuery };
+
+//# sourceMappingURL=applyQuery.js.map

package/dist/applyQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyQuery.js","names":[],"sources":["../src/applyQuery.ts"],"sourcesContent":["import type { SourceQuery } from './types';\n\n/**\n * Generic query applicator — delegates to `source.patch(changes)`.\n * Use this with `decodeQuery()` output to restore URL state onto any source:\n *\n * @example\n * ```ts\n * const q = decodeQuery(new URL(location.href).searchParams, { defaultLimit: 20 });\n * await applyQuery(source, q);\n * ```\n *\n * ⚠️ `CursorSource` and `InfiniteSource` have no page-number concept (keyset/append navigation) —\n * their `patch()` only reads `limit`/`search` and silently ignores a `page` field. This compiles\n * (both accept `Partial<SourceQuery>`-shaped input) but a `page` value from `decodeQuery()` is a\n * no-op on those two source types.\n */\nexport function applyQuery<T extends { patch(changes: Partial<SourceQuery>): Promise<void> }>(\n  source: T,\n  changes: Partial<SourceQuery>,\n): Promise<void> {\n  return source.patch(changes);\n}\n"],"mappings":";AAiBA,SAAgB,EACd,GACA,GACe;CACf,OAAO,EAAO,MAAM,CAAO;AAC7B"}

package/dist/asyncSource.cjs

@@ -0,0 +1,2 @@
+const e=require("./_utils.cjs"),t=require("./core.cjs"),n=require("./fetchManager.cjs");function r(r,i=e.defaultKeyOf,a){let o=t.createSourceCore({onBeforeNotify:a}),s=n.createFetchManager(i),c=r.debounceMs??300,l=r.retry?.attempts??0,u=r.retry?.delay??e.defaultRetryDelay,d=r.autoFetch!==!1,f,p=()=>{o.isDisposed||(f!==void 0&&(clearInterval(f),f=void 0),s.dispose(),o.dispose())};return{autoFetch:d,core:o,debounceMs:c,get disposalSignal(){return o.disposalSignal},dispose:p,get disposed(){return o.isDisposed},fetch(e,t,n){return s.run(e,t,n)},pendingCount:()=>s.pendingCount,ready(e){return o.ready(()=>s.pendingCount===0&&!o.isScheduled,e)},retryAttempts:l,retryDelay:u,startRefreshInterval(e){r.refreshInterval!==void 0&&r.refreshInterval>0&&(f=setInterval(()=>{o.isDisposed||e()},r.refreshInterval))},[Symbol.dispose]:p}}exports.createAsyncSource=r;
+//# sourceMappingURL=asyncSource.cjs.map

package/dist/asyncSource.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncSource.cjs","names":[],"sources":["../src/asyncSource.ts"],"sourcesContent":["import type { SourceCore } from './core';\n\nimport { defaultKeyOf, defaultRetryDelay } from './_utils';\nimport { createSourceCore } from './core';\nimport { createFetchManager } from './fetchManager';\n\n/**\n * Configuration subset common to all async source types.\n * Extracted to eliminate duplication across remote, cursor, and infinite sources.\n */\nexport type AsyncSourceConfig<TQuery> = Readonly<{\n  autoFetch?: boolean;\n  debounceMs?: number;\n  queryKey?: (q: TQuery) => string;\n  refreshInterval?: number;\n  retry?: { attempts?: number; delay?: (attempt: number) => number };\n}>;\n\nexport type FetchExecutor<TQuery> = (q: TQuery, signal: AbortSignal, isLatest: () => boolean) => Promise<void>;\n\nexport type AsyncSourceInfra<TQuery> = {\n  [Symbol.dispose](): void;\n  /** `true` when `autoFetch !== false`. */\n  readonly autoFetch: boolean;\n  /** The underlying SourceCore — use directly for subscribe, schedule, cancelTimer, flush, isScheduled. */\n  readonly core: SourceCore;\n  /** Debounce delay in ms. */\n  readonly debounceMs: number;\n  /** `AbortSignal` aborted when `dispose()` is called. */\n  readonly disposalSignal: AbortSignal;\n  /** Dispose lifecycle: cancel refresh interval, dispose FM, dispose core. Idempotent. */\n  dispose(): void;\n  /** `true` after `dispose()`. */\n  readonly disposed: boolean;\n  /**\n   * Run a deduplicated fetch for query `q`.\n   * Calls `onCommit()` whenever pending count changes (for subscriber notification).\n   */\n  fetch(q: TQuery, execute: FetchExecutor<TQuery>, onCommit: () => void): Promise<void>;\n  /** Number of currently in-flight requests. */\n  pendingCount(): number;\n  /** Resolves when idle (no in-flight requests, no pending debounce). */\n  ready(timeout?: number): Promise<void>;\n  /** Number of retry attempts after the first failure. */\n  readonly retryAttempts: number;\n  /** Returns the delay in ms before the nth retry. */\n  readonly retryDelay: (attempt: number) => number;\n  /**\n   * Wire the refresh interval. Must be called once after construction, passing\n   * the source-level `doUpdate` callback. Does nothing when `refreshInterval`\n   * is unset or ≤ 0.\n   */\n  startRefreshInterval(doUpdate: () => void): void;\n};\n\n/**\n * Creates the shared infrastructure used by `createRemoteSource`, `createCursorSource`,\n * and `createInfiniteSource`. Eliminates duplication of lifecycle, config-defaults,\n * fetch-manager setup, dispose, ready, flush, and refresh-interval logic.\n *\n * Each source factory composes this and adds its own query state, meta shape, and\n * source-specific methods. Pass `onBeforeNotify` to run `refreshMeta()` before\n * subscribers observe each notification — this eliminates the need for a parallel\n * listeners Set in each source factory.\n */\nexport function createAsyncSource<TQuery>(\n  cfg: AsyncSourceConfig<TQuery>,\n  keyOf: (q: TQuery) => string = defaultKeyOf as (q: TQuery) => string,\n  onBeforeNotify?: () => void,\n): AsyncSourceInfra<TQuery> {\n  const core = createSourceCore({ onBeforeNotify });\n  const fm = createFetchManager<TQuery>(keyOf);\n  const debounceMs = cfg.debounceMs ?? 300;\n  const retryAttempts = cfg.retry?.attempts ?? 0;\n  const retryDelay = cfg.retry?.delay ?? defaultRetryDelay;\n  const autoFetch = cfg.autoFetch !== false;\n\n  let refreshTimer: ReturnType<typeof setInterval> | undefined;\n\n  const dispose = (): void => {\n    if (core.isDisposed) return;\n\n    if (refreshTimer !== undefined) {\n      clearInterval(refreshTimer);\n      refreshTimer = undefined;\n    }\n\n    fm.dispose();\n    core.dispose();\n  };\n\n  return {\n    autoFetch,\n    core,\n    debounceMs,\n    get disposalSignal() {\n      return core.disposalSignal;\n    },\n\n    dispose,\n\n    get disposed() {\n      return core.isDisposed;\n    },\n\n    fetch(q, execute, onCommit) {\n      return fm.run(q, execute, onCommit);\n    },\n\n    pendingCount: () => fm.pendingCount,\n\n    ready(timeout) {\n      return core.ready(() => fm.pendingCount === 0 && !core.isScheduled, timeout);\n    },\n    retryAttempts,\n\n    retryDelay,\n\n    startRefreshInterval(doUpdate) {\n      if (cfg.refreshInterval !== undefined && cfg.refreshInterval > 0) {\n        refreshTimer = setInterval(() => {\n          if (!core.isDisposed) doUpdate();\n        }, cfg.refreshInterval);\n      }\n    },\n\n    [Symbol.dispose]: dispose,\n  };\n}\n"],"mappings":"wFAiEA,SAAgB,EACd,EACA,EAA+B,EAAA,aAC/B,EAC0B,CAC1B,IAAM,EAAO,EAAA,iBAAiB,CAAE,gBAAe,CAAC,EAC1C,EAAK,EAAA,mBAA2B,CAAK,EACrC,EAAa,EAAI,YAAc,IAC/B,EAAgB,EAAI,OAAO,UAAY,EACvC,EAAa,EAAI,OAAO,OAAS,EAAA,kBACjC,EAAY,EAAI,YAAc,GAEhC,EAEE,MAAsB,CACtB,EAAK,aAEL,IAAiB,IAAA,KACnB,cAAc,CAAY,EAC1B,EAAe,IAAA,IAGjB,EAAG,QAAQ,EACX,EAAK,QAAQ,EACf,EAEA,MAAO,CACL,YACA,OACA,aACA,IAAI,gBAAiB,CACnB,OAAO,EAAK,cACd,EAEA,UAEA,IAAI,UAAW,CACb,OAAO,EAAK,UACd,EAEA,MAAM,EAAG,EAAS,EAAU,CAC1B,OAAO,EAAG,IAAI,EAAG,EAAS,CAAQ,CACpC,EAEA,iBAAoB,EAAG,aAEvB,MAAM,EAAS,CACb,OAAO,EAAK,UAAY,EAAG,eAAiB,GAAK,CAAC,EAAK,YAAa,CAAO,CAC7E,EACA,gBAEA,aAEA,qBAAqB,EAAU,CACzB,EAAI,kBAAoB,IAAA,IAAa,EAAI,gBAAkB,IAC7D,EAAe,gBAAkB,CAC1B,EAAK,YAAY,EAAS,CACjC,EAAG,EAAI,eAAe,EAE1B,GAEC,OAAO,SAAU,CACpB,CACF"}

package/dist/asyncSource.d.ts

@@ -0,0 +1,62 @@
+import type { SourceCore } from './core';
+/**
+ * Configuration subset common to all async source types.
+ * Extracted to eliminate duplication across remote, cursor, and infinite sources.
+ */
+export type AsyncSourceConfig<TQuery> = Readonly<{
+    autoFetch?: boolean;
+    debounceMs?: number;
+    queryKey?: (q: TQuery) => string;
+    refreshInterval?: number;
+    retry?: {
+        attempts?: number;
+        delay?: (attempt: number) => number;
+    };
+}>;
+export type FetchExecutor<TQuery> = (q: TQuery, signal: AbortSignal, isLatest: () => boolean) => Promise<void>;
+export type AsyncSourceInfra<TQuery> = {
+    [Symbol.dispose](): void;
+    /** `true` when `autoFetch !== false`. */
+    readonly autoFetch: boolean;
+    /** The underlying SourceCore — use directly for subscribe, schedule, cancelTimer, flush, isScheduled. */
+    readonly core: SourceCore;
+    /** Debounce delay in ms. */
+    readonly debounceMs: number;
+    /** `AbortSignal` aborted when `dispose()` is called. */
+    readonly disposalSignal: AbortSignal;
+    /** Dispose lifecycle: cancel refresh interval, dispose FM, dispose core. Idempotent. */
+    dispose(): void;
+    /** `true` after `dispose()`. */
+    readonly disposed: boolean;
+    /**
+     * Run a deduplicated fetch for query `q`.
+     * Calls `onCommit()` whenever pending count changes (for subscriber notification).
+     */
+    fetch(q: TQuery, execute: FetchExecutor<TQuery>, onCommit: () => void): Promise<void>;
+    /** Number of currently in-flight requests. */
+    pendingCount(): number;
+    /** Resolves when idle (no in-flight requests, no pending debounce). */
+    ready(timeout?: number): Promise<void>;
+    /** Number of retry attempts after the first failure. */
+    readonly retryAttempts: number;
+    /** Returns the delay in ms before the nth retry. */
+    readonly retryDelay: (attempt: number) => number;
+    /**
+     * Wire the refresh interval. Must be called once after construction, passing
+     * the source-level `doUpdate` callback. Does nothing when `refreshInterval`
+     * is unset or ≤ 0.
+     */
+    startRefreshInterval(doUpdate: () => void): void;
+};
+/**
+ * Creates the shared infrastructure used by `createRemoteSource`, `createCursorSource`,
+ * and `createInfiniteSource`. Eliminates duplication of lifecycle, config-defaults,
+ * fetch-manager setup, dispose, ready, flush, and refresh-interval logic.
+ *
+ * Each source factory composes this and adds its own query state, meta shape, and
+ * source-specific methods. Pass `onBeforeNotify` to run `refreshMeta()` before
+ * subscribers observe each notification — this eliminates the need for a parallel
+ * listeners Set in each source factory.
+ */
+export declare function createAsyncSource<TQuery>(cfg: AsyncSourceConfig<TQuery>, keyOf?: (q: TQuery) => string, onBeforeNotify?: () => void): AsyncSourceInfra<TQuery>;
+//# sourceMappingURL=asyncSource.d.ts.map

package/dist/asyncSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncSource.d.ts","sourceRoot":"","sources":["../src/asyncSource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAMzC;;;GAGG;AACH,MAAM,MAAM,iBAAiB,CAAC,MAAM,IAAI,QAAQ,CAAC;IAC/C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACjC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;KAAE,CAAC;CACpE,CAAC,CAAC;AAEH,MAAM,MAAM,aAAa,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/G,MAAM,MAAM,gBAAgB,CAAC,MAAM,IAAI;IACrC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,yGAAyG;IACzG,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,4BAA4B;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC;IACrC,wFAAwF;IACxF,OAAO,IAAI,IAAI,CAAC;IAChB,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtF,8CAA8C;IAC9C,YAAY,IAAI,MAAM,CAAC;IACvB,uEAAuE;IACvE,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,wDAAwD;IACxD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACjD;;;;OAIG;IACH,oBAAoB,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAClD,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EACtC,GAAG,EAAE,iBAAiB,CAAC,MAAM,CAAC,EAC9B,KAAK,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAA8C,EACpE,cAAc,CAAC,EAAE,MAAM,IAAI,GAC1B,gBAAgB,CAAC,MAAM,CAAC,CA2D1B"}

package/dist/asyncSource.js

@@ -0,0 +1,40 @@
+import { defaultKeyOf as e, defaultRetryDelay as t } from "./_utils.js";
+import { createSourceCore as n } from "./core.js";
+import { createFetchManager as r } from "./fetchManager.js";
+//#region src/asyncSource.ts
+function i(i, a = e, o) {
+	let s = n({ onBeforeNotify: o }), c = r(a), l = i.debounceMs ?? 300, u = i.retry?.attempts ?? 0, d = i.retry?.delay ?? t, f = i.autoFetch !== !1, p, m = () => {
+		s.isDisposed || (p !== void 0 && (clearInterval(p), p = void 0), c.dispose(), s.dispose());
+	};
+	return {
+		autoFetch: f,
+		core: s,
+		debounceMs: l,
+		get disposalSignal() {
+			return s.disposalSignal;
+		},
+		dispose: m,
+		get disposed() {
+			return s.isDisposed;
+		},
+		fetch(e, t, n) {
+			return c.run(e, t, n);
+		},
+		pendingCount: () => c.pendingCount,
+		ready(e) {
+			return s.ready(() => c.pendingCount === 0 && !s.isScheduled, e);
+		},
+		retryAttempts: u,
+		retryDelay: d,
+		startRefreshInterval(e) {
+			i.refreshInterval !== void 0 && i.refreshInterval > 0 && (p = setInterval(() => {
+				s.isDisposed || e();
+			}, i.refreshInterval));
+		},
+		[Symbol.dispose]: m
+	};
+}
+//#endregion
+export { i as createAsyncSource };
+
+//# sourceMappingURL=asyncSource.js.map

package/dist/asyncSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncSource.js","names":[],"sources":["../src/asyncSource.ts"],"sourcesContent":["import type { SourceCore } from './core';\n\nimport { defaultKeyOf, defaultRetryDelay } from './_utils';\nimport { createSourceCore } from './core';\nimport { createFetchManager } from './fetchManager';\n\n/**\n * Configuration subset common to all async source types.\n * Extracted to eliminate duplication across remote, cursor, and infinite sources.\n */\nexport type AsyncSourceConfig<TQuery> = Readonly<{\n  autoFetch?: boolean;\n  debounceMs?: number;\n  queryKey?: (q: TQuery) => string;\n  refreshInterval?: number;\n  retry?: { attempts?: number; delay?: (attempt: number) => number };\n}>;\n\nexport type FetchExecutor<TQuery> = (q: TQuery, signal: AbortSignal, isLatest: () => boolean) => Promise<void>;\n\nexport type AsyncSourceInfra<TQuery> = {\n  [Symbol.dispose](): void;\n  /** `true` when `autoFetch !== false`. */\n  readonly autoFetch: boolean;\n  /** The underlying SourceCore — use directly for subscribe, schedule, cancelTimer, flush, isScheduled. */\n  readonly core: SourceCore;\n  /** Debounce delay in ms. */\n  readonly debounceMs: number;\n  /** `AbortSignal` aborted when `dispose()` is called. */\n  readonly disposalSignal: AbortSignal;\n  /** Dispose lifecycle: cancel refresh interval, dispose FM, dispose core. Idempotent. */\n  dispose(): void;\n  /** `true` after `dispose()`. */\n  readonly disposed: boolean;\n  /**\n   * Run a deduplicated fetch for query `q`.\n   * Calls `onCommit()` whenever pending count changes (for subscriber notification).\n   */\n  fetch(q: TQuery, execute: FetchExecutor<TQuery>, onCommit: () => void): Promise<void>;\n  /** Number of currently in-flight requests. */\n  pendingCount(): number;\n  /** Resolves when idle (no in-flight requests, no pending debounce). */\n  ready(timeout?: number): Promise<void>;\n  /** Number of retry attempts after the first failure. */\n  readonly retryAttempts: number;\n  /** Returns the delay in ms before the nth retry. */\n  readonly retryDelay: (attempt: number) => number;\n  /**\n   * Wire the refresh interval. Must be called once after construction, passing\n   * the source-level `doUpdate` callback. Does nothing when `refreshInterval`\n   * is unset or ≤ 0.\n   */\n  startRefreshInterval(doUpdate: () => void): void;\n};\n\n/**\n * Creates the shared infrastructure used by `createRemoteSource`, `createCursorSource`,\n * and `createInfiniteSource`. Eliminates duplication of lifecycle, config-defaults,\n * fetch-manager setup, dispose, ready, flush, and refresh-interval logic.\n *\n * Each source factory composes this and adds its own query state, meta shape, and\n * source-specific methods. Pass `onBeforeNotify` to run `refreshMeta()` before\n * subscribers observe each notification — this eliminates the need for a parallel\n * listeners Set in each source factory.\n */\nexport function createAsyncSource<TQuery>(\n  cfg: AsyncSourceConfig<TQuery>,\n  keyOf: (q: TQuery) => string = defaultKeyOf as (q: TQuery) => string,\n  onBeforeNotify?: () => void,\n): AsyncSourceInfra<TQuery> {\n  const core = createSourceCore({ onBeforeNotify });\n  const fm = createFetchManager<TQuery>(keyOf);\n  const debounceMs = cfg.debounceMs ?? 300;\n  const retryAttempts = cfg.retry?.attempts ?? 0;\n  const retryDelay = cfg.retry?.delay ?? defaultRetryDelay;\n  const autoFetch = cfg.autoFetch !== false;\n\n  let refreshTimer: ReturnType<typeof setInterval> | undefined;\n\n  const dispose = (): void => {\n    if (core.isDisposed) return;\n\n    if (refreshTimer !== undefined) {\n      clearInterval(refreshTimer);\n      refreshTimer = undefined;\n    }\n\n    fm.dispose();\n    core.dispose();\n  };\n\n  return {\n    autoFetch,\n    core,\n    debounceMs,\n    get disposalSignal() {\n      return core.disposalSignal;\n    },\n\n    dispose,\n\n    get disposed() {\n      return core.isDisposed;\n    },\n\n    fetch(q, execute, onCommit) {\n      return fm.run(q, execute, onCommit);\n    },\n\n    pendingCount: () => fm.pendingCount,\n\n    ready(timeout) {\n      return core.ready(() => fm.pendingCount === 0 && !core.isScheduled, timeout);\n    },\n    retryAttempts,\n\n    retryDelay,\n\n    startRefreshInterval(doUpdate) {\n      if (cfg.refreshInterval !== undefined && cfg.refreshInterval > 0) {\n        refreshTimer = setInterval(() => {\n          if (!core.isDisposed) doUpdate();\n        }, cfg.refreshInterval);\n      }\n    },\n\n    [Symbol.dispose]: dispose,\n  };\n}\n"],"mappings":";;;;AAiEA,SAAgB,EACd,GACA,IAA+B,GAC/B,GAC0B;CAC1B,IAAM,IAAO,EAAiB,EAAE,kBAAe,CAAC,GAC1C,IAAK,EAA2B,CAAK,GACrC,IAAa,EAAI,cAAc,KAC/B,IAAgB,EAAI,OAAO,YAAY,GACvC,IAAa,EAAI,OAAO,SAAS,GACjC,IAAY,EAAI,cAAc,IAEhC,GAEE,UAAsB;EACtB,EAAK,eAEL,MAAiB,KAAA,MACnB,cAAc,CAAY,GAC1B,IAAe,KAAA,IAGjB,EAAG,QAAQ,GACX,EAAK,QAAQ;CACf;CAEA,OAAO;EACL;EACA;EACA;EACA,IAAI,iBAAiB;GACnB,OAAO,EAAK;EACd;EAEA;EAEA,IAAI,WAAW;GACb,OAAO,EAAK;EACd;EAEA,MAAM,GAAG,GAAS,GAAU;GAC1B,OAAO,EAAG,IAAI,GAAG,GAAS,CAAQ;EACpC;EAEA,oBAAoB,EAAG;EAEvB,MAAM,GAAS;GACb,OAAO,EAAK,YAAY,EAAG,iBAAiB,KAAK,CAAC,EAAK,aAAa,CAAO;EAC7E;EACA;EAEA;EAEA,qBAAqB,GAAU;GAC7B,AAAI,EAAI,oBAAoB,KAAA,KAAa,EAAI,kBAAkB,MAC7D,IAAe,kBAAkB;IAC/B,AAAK,EAAK,cAAY,EAAS;GACjC,GAAG,EAAI,eAAe;EAE1B;GAEC,OAAO,UAAU;CACpB;AACF"}

package/dist/codecs.cjs

@@ -0,0 +1,2 @@
+const e=require("./errors.cjs");var t=e=>{let t={...e.search&&{search:e.search},limit:String(e.limit),page:String(e.page)},n=e;return n.filter!==void 0&&(t.filter=JSON.stringify(n.filter)),n.sort!==void 0&&(t.sort=JSON.stringify(n.sort)),t},n=(t,n={})=>{let r=t instanceof URLSearchParams?Object.fromEntries(t.entries()):t,{defaultLimit:i=20,strict:a=!1}=n,o=(e,t)=>{if(e===void 0)return t;let n=Array.isArray(e)?e[0]:e,r=Number(n);return Number.isInteger(r)&&r>0?r:t},s=(t,n)=>{if(n===void 0)return;let r=Array.isArray(n)?n[0]:n;try{return JSON.parse(r)}catch{if(a)throw new e.SourcererError(`Invalid query param "${t}": ${r}`);return}},c=r.limit,l=r.page,u=r.search,d=r.filter,f=r.sort,p=d===void 0?void 0:s(`filter`,d),m=f===void 0?void 0:s(`sort`,f);return{...p!==void 0&&{filter:p},...m!==void 0&&{sort:m},...u!==void 0&&{search:Array.isArray(u)?u[0]:u},limit:o(c,i),page:o(l,1)}};exports.decodeQuery=n,exports.encodeQuery=t;
+//# sourceMappingURL=codecs.cjs.map

package/dist/codecs.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"codecs.cjs","names":[],"sources":["../src/codecs.ts"],"sourcesContent":["import type { QueryParams, QueryParamsInput, RemoteSourceQuery, SourceQuery } from './types';\n\nimport { SourcererError } from './errors';\n\n/**\n * Serialises a `SourceQuery` or `RemoteSourceQuery` into plain URL-safe string params.\n *\n * ⚠️ `filter` and `sort` are JSON-stringified without a try/catch. A circular object reference\n * throws a native `TypeError` (\"Converting circular structure to JSON\") straight out of this\n * function — ensure filter/sort values are plain serialisable objects, or wrap the call yourself.\n *\n * ⚠️ Round-trip fidelity: `page` and `limit` must be positive integers. `encodeQuery` will\n * serialise any number (including 0), but `decodeQuery` clamps non-positive values to 1/defaultLimit.\n *\n * `encodeQuery` + `decodeQuery` form a round-trip pair: filter/sort values are JSON-stringified\n * on encode and JSON-parsed on decode.\n */\nexport const encodeQuery = <TFilter = unknown, TSort = unknown>(\n  query: RemoteSourceQuery<TFilter, TSort> | SourceQuery,\n): QueryParams => {\n  const base: QueryParams = {\n    ...(query.search && { search: query.search }),\n    limit: String(query.limit),\n    page: String(query.page),\n  };\n\n  const rq = query as RemoteSourceQuery<TFilter, TSort>;\n\n  if (rq.filter !== undefined) {\n    base['filter'] = JSON.stringify(rq.filter);\n  }\n\n  if (rq.sort !== undefined) {\n    base['sort'] = JSON.stringify(rq.sort);\n  }\n\n  return base;\n};\n\nexport type DecodeQueryOptions = Readonly<{\n  defaultLimit?: number;\n  strict?: boolean;\n}>;\n\n/**\n * Parses URL query params into a `Partial<RemoteSourceQuery<unknown, unknown>>`.\n * Accepts either a plain `Record<string, string | string[] | undefined>` or a `URLSearchParams` instance.\n *\n * - `filter` and `sort` are JSON-parsed and typed as `unknown` — validate and narrow them\n *   with a runtime schema (e.g. Zod) before passing to `applyQuery`.\n * - `search` is omitted from the result when the param is absent (rather than defaulting to `''`).\n * - `limit` and `page` are parsed as positive integers; invalid values fall back to defaults.\n */\nexport const decodeQuery = (\n  params: QueryParamsInput | URLSearchParams,\n  options: DecodeQueryOptions = {},\n): Partial<RemoteSourceQuery<unknown, unknown>> => {\n  const raw: QueryParamsInput =\n    params instanceof URLSearchParams ? (Object.fromEntries(params.entries()) as QueryParamsInput) : params;\n\n  const { defaultLimit = 20, strict = false } = options;\n\n  const parsePositiveInt = (value: string | string[] | undefined, fallback: number): number => {\n    if (value === undefined) return fallback;\n\n    const str = Array.isArray(value) ? value[0] : value;\n    const n = Number(str);\n\n    return Number.isInteger(n) && n > 0 ? n : fallback;\n  };\n\n  const parseJson = (key: string, value: string | string[] | undefined): unknown => {\n    if (value === undefined) return undefined;\n\n    const str = Array.isArray(value) ? value[0] : value;\n\n    try {\n      return JSON.parse(str) as unknown;\n    } catch {\n      if (strict) throw new SourcererError(`Invalid query param \"${key}\": ${str}`);\n\n      return undefined;\n    }\n  };\n\n  const rawLimit = raw['limit'];\n  const rawPage = raw['page'];\n  const rawSearch = raw['search'];\n  const rawFilter = raw['filter'];\n  const rawSort = raw['sort'];\n\n  const filter = rawFilter !== undefined ? parseJson('filter', rawFilter) : undefined;\n  const sort = rawSort !== undefined ? parseJson('sort', rawSort) : undefined;\n\n  const result: Partial<RemoteSourceQuery<unknown, unknown>> = {\n    ...(filter !== undefined && { filter }),\n    ...(sort !== undefined && { sort }),\n    ...(rawSearch !== undefined && { search: Array.isArray(rawSearch) ? rawSearch[0] : rawSearch }),\n    limit: parsePositiveInt(rawLimit, defaultLimit),\n    page: parsePositiveInt(rawPage, 1),\n  };\n\n  return result;\n};\n"],"mappings":"gCAiBA,IAAa,EACX,GACgB,CAChB,IAAM,EAAoB,CACxB,GAAI,EAAM,QAAU,CAAE,OAAQ,EAAM,MAAO,EAC3C,MAAO,OAAO,EAAM,KAAK,EACzB,KAAM,OAAO,EAAM,IAAI,CACzB,EAEM,EAAK,EAUX,OARI,EAAG,SAAW,IAAA,KAChB,EAAK,OAAY,KAAK,UAAU,EAAG,MAAM,GAGvC,EAAG,OAAS,IAAA,KACd,EAAK,KAAU,KAAK,UAAU,EAAG,IAAI,GAGhC,CACT,EAgBa,GACX,EACA,EAA8B,CAAC,IACkB,CACjD,IAAM,EACJ,aAAkB,gBAAmB,OAAO,YAAY,EAAO,QAAQ,CAAC,EAAyB,EAE7F,CAAE,eAAe,GAAI,SAAS,IAAU,EAExC,GAAoB,EAAsC,IAA6B,CAC3F,GAAI,IAAU,IAAA,GAAW,OAAO,EAEhC,IAAM,EAAM,MAAM,QAAQ,CAAK,EAAI,EAAM,GAAK,EACxC,EAAI,OAAO,CAAG,EAEpB,OAAO,OAAO,UAAU,CAAC,GAAK,EAAI,EAAI,EAAI,CAC5C,EAEM,GAAa,EAAa,IAAkD,CAChF,GAAI,IAAU,IAAA,GAAW,OAEzB,IAAM,EAAM,MAAM,QAAQ,CAAK,EAAI,EAAM,GAAK,EAE9C,GAAI,CACF,OAAO,KAAK,MAAM,CAAG,CACvB,MAAQ,CACN,GAAI,EAAQ,MAAM,IAAI,EAAA,eAAe,wBAAwB,EAAI,KAAK,GAAK,EAE3E,MACF,CACF,EAEM,EAAW,EAAI,MACf,EAAU,EAAI,KACd,EAAY,EAAI,OAChB,EAAY,EAAI,OAChB,EAAU,EAAI,KAEd,EAAS,IAAc,IAAA,GAA6C,IAAA,GAAjC,EAAU,SAAU,CAAS,EAChE,EAAO,IAAY,IAAA,GAAyC,IAAA,GAA7B,EAAU,OAAQ,CAAO,EAU9D,MAAO,CAPL,GAAI,IAAW,IAAA,IAAa,CAAE,QAAO,EACrC,GAAI,IAAS,IAAA,IAAa,CAAE,MAAK,EACjC,GAAI,IAAc,IAAA,IAAa,CAAE,OAAQ,MAAM,QAAQ,CAAS,EAAI,EAAU,GAAK,CAAU,EAC7F,MAAO,EAAiB,EAAU,CAAY,EAC9C,KAAM,EAAiB,EAAS,CAAC,CAG5B,CACT"}

package/dist/codecs.d.ts

@@ -0,0 +1,30 @@
+import type { QueryParams, QueryParamsInput, RemoteSourceQuery, SourceQuery } from './types';
+/**
+ * Serialises a `SourceQuery` or `RemoteSourceQuery` into plain URL-safe string params.
+ *
+ * ⚠️ `filter` and `sort` are JSON-stringified without a try/catch. A circular object reference
+ * throws a native `TypeError` ("Converting circular structure to JSON") straight out of this
+ * function — ensure filter/sort values are plain serialisable objects, or wrap the call yourself.
+ *
+ * ⚠️ Round-trip fidelity: `page` and `limit` must be positive integers. `encodeQuery` will
+ * serialise any number (including 0), but `decodeQuery` clamps non-positive values to 1/defaultLimit.
+ *
+ * `encodeQuery` + `decodeQuery` form a round-trip pair: filter/sort values are JSON-stringified
+ * on encode and JSON-parsed on decode.
+ */
+export declare const encodeQuery: <TFilter = unknown, TSort = unknown>(query: RemoteSourceQuery<TFilter, TSort> | SourceQuery) => QueryParams;
+export type DecodeQueryOptions = Readonly<{
+    defaultLimit?: number;
+    strict?: boolean;
+}>;
+/**
+ * Parses URL query params into a `Partial<RemoteSourceQuery<unknown, unknown>>`.
+ * Accepts either a plain `Record<string, string | string[] | undefined>` or a `URLSearchParams` instance.
+ *
+ * - `filter` and `sort` are JSON-parsed and typed as `unknown` — validate and narrow them
+ *   with a runtime schema (e.g. Zod) before passing to `applyQuery`.
+ * - `search` is omitted from the result when the param is absent (rather than defaulting to `''`).
+ * - `limit` and `page` are parsed as positive integers; invalid values fall back to defaults.
+ */
+export declare const decodeQuery: (params: QueryParamsInput | URLSearchParams, options?: DecodeQueryOptions) => Partial<RemoteSourceQuery<unknown, unknown>>;
+//# sourceMappingURL=codecs.d.ts.map

package/dist/codecs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codecs.d.ts","sourceRoot":"","sources":["../src/codecs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI7F;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO,EAC5D,OAAO,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,WAAW,KACrD,WAkBF,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,gBAAgB,GAAG,eAAe,EAC1C,UAAS,kBAAuB,KAC/B,OAAO,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CA+C7C,CAAC"}

package/dist/codecs.js

@@ -0,0 +1,36 @@
+import { SourcererError as e } from "./errors.js";
+//#region src/codecs.ts
+var t = (e) => {
+	let t = {
+		...e.search && { search: e.search },
+		limit: String(e.limit),
+		page: String(e.page)
+	}, n = e;
+	return n.filter !== void 0 && (t.filter = JSON.stringify(n.filter)), n.sort !== void 0 && (t.sort = JSON.stringify(n.sort)), t;
+}, n = (t, n = {}) => {
+	let r = t instanceof URLSearchParams ? Object.fromEntries(t.entries()) : t, { defaultLimit: i = 20, strict: a = !1 } = n, o = (e, t) => {
+		if (e === void 0) return t;
+		let n = Array.isArray(e) ? e[0] : e, r = Number(n);
+		return Number.isInteger(r) && r > 0 ? r : t;
+	}, s = (t, n) => {
+		if (n === void 0) return;
+		let r = Array.isArray(n) ? n[0] : n;
+		try {
+			return JSON.parse(r);
+		} catch {
+			if (a) throw new e(`Invalid query param "${t}": ${r}`);
+			return;
+		}
+	}, c = r.limit, l = r.page, u = r.search, d = r.filter, f = r.sort, p = d === void 0 ? void 0 : s("filter", d), m = f === void 0 ? void 0 : s("sort", f);
+	return {
+		...p !== void 0 && { filter: p },
+		...m !== void 0 && { sort: m },
+		...u !== void 0 && { search: Array.isArray(u) ? u[0] : u },
+		limit: o(c, i),
+		page: o(l, 1)
+	};
+};
+//#endregion
+export { n as decodeQuery, t as encodeQuery };
+
+//# sourceMappingURL=codecs.js.map

package/dist/codecs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codecs.js","names":[],"sources":["../src/codecs.ts"],"sourcesContent":["import type { QueryParams, QueryParamsInput, RemoteSourceQuery, SourceQuery } from './types';\n\nimport { SourcererError } from './errors';\n\n/**\n * Serialises a `SourceQuery` or `RemoteSourceQuery` into plain URL-safe string params.\n *\n * ⚠️ `filter` and `sort` are JSON-stringified without a try/catch. A circular object reference\n * throws a native `TypeError` (\"Converting circular structure to JSON\") straight out of this\n * function — ensure filter/sort values are plain serialisable objects, or wrap the call yourself.\n *\n * ⚠️ Round-trip fidelity: `page` and `limit` must be positive integers. `encodeQuery` will\n * serialise any number (including 0), but `decodeQuery` clamps non-positive values to 1/defaultLimit.\n *\n * `encodeQuery` + `decodeQuery` form a round-trip pair: filter/sort values are JSON-stringified\n * on encode and JSON-parsed on decode.\n */\nexport const encodeQuery = <TFilter = unknown, TSort = unknown>(\n  query: RemoteSourceQuery<TFilter, TSort> | SourceQuery,\n): QueryParams => {\n  const base: QueryParams = {\n    ...(query.search && { search: query.search }),\n    limit: String(query.limit),\n    page: String(query.page),\n  };\n\n  const rq = query as RemoteSourceQuery<TFilter, TSort>;\n\n  if (rq.filter !== undefined) {\n    base['filter'] = JSON.stringify(rq.filter);\n  }\n\n  if (rq.sort !== undefined) {\n    base['sort'] = JSON.stringify(rq.sort);\n  }\n\n  return base;\n};\n\nexport type DecodeQueryOptions = Readonly<{\n  defaultLimit?: number;\n  strict?: boolean;\n}>;\n\n/**\n * Parses URL query params into a `Partial<RemoteSourceQuery<unknown, unknown>>`.\n * Accepts either a plain `Record<string, string | string[] | undefined>` or a `URLSearchParams` instance.\n *\n * - `filter` and `sort` are JSON-parsed and typed as `unknown` — validate and narrow them\n *   with a runtime schema (e.g. Zod) before passing to `applyQuery`.\n * - `search` is omitted from the result when the param is absent (rather than defaulting to `''`).\n * - `limit` and `page` are parsed as positive integers; invalid values fall back to defaults.\n */\nexport const decodeQuery = (\n  params: QueryParamsInput | URLSearchParams,\n  options: DecodeQueryOptions = {},\n): Partial<RemoteSourceQuery<unknown, unknown>> => {\n  const raw: QueryParamsInput =\n    params instanceof URLSearchParams ? (Object.fromEntries(params.entries()) as QueryParamsInput) : params;\n\n  const { defaultLimit = 20, strict = false } = options;\n\n  const parsePositiveInt = (value: string | string[] | undefined, fallback: number): number => {\n    if (value === undefined) return fallback;\n\n    const str = Array.isArray(value) ? value[0] : value;\n    const n = Number(str);\n\n    return Number.isInteger(n) && n > 0 ? n : fallback;\n  };\n\n  const parseJson = (key: string, value: string | string[] | undefined): unknown => {\n    if (value === undefined) return undefined;\n\n    const str = Array.isArray(value) ? value[0] : value;\n\n    try {\n      return JSON.parse(str) as unknown;\n    } catch {\n      if (strict) throw new SourcererError(`Invalid query param \"${key}\": ${str}`);\n\n      return undefined;\n    }\n  };\n\n  const rawLimit = raw['limit'];\n  const rawPage = raw['page'];\n  const rawSearch = raw['search'];\n  const rawFilter = raw['filter'];\n  const rawSort = raw['sort'];\n\n  const filter = rawFilter !== undefined ? parseJson('filter', rawFilter) : undefined;\n  const sort = rawSort !== undefined ? parseJson('sort', rawSort) : undefined;\n\n  const result: Partial<RemoteSourceQuery<unknown, unknown>> = {\n    ...(filter !== undefined && { filter }),\n    ...(sort !== undefined && { sort }),\n    ...(rawSearch !== undefined && { search: Array.isArray(rawSearch) ? rawSearch[0] : rawSearch }),\n    limit: parsePositiveInt(rawLimit, defaultLimit),\n    page: parsePositiveInt(rawPage, 1),\n  };\n\n  return result;\n};\n"],"mappings":";;AAiBA,IAAa,KACX,MACgB;CAChB,IAAM,IAAoB;EACxB,GAAI,EAAM,UAAU,EAAE,QAAQ,EAAM,OAAO;EAC3C,OAAO,OAAO,EAAM,KAAK;EACzB,MAAM,OAAO,EAAM,IAAI;CACzB,GAEM,IAAK;CAUX,OARI,EAAG,WAAW,KAAA,MAChB,EAAK,SAAY,KAAK,UAAU,EAAG,MAAM,IAGvC,EAAG,SAAS,KAAA,MACd,EAAK,OAAU,KAAK,UAAU,EAAG,IAAI,IAGhC;AACT,GAgBa,KACX,GACA,IAA8B,CAAC,MACkB;CACjD,IAAM,IACJ,aAAkB,kBAAmB,OAAO,YAAY,EAAO,QAAQ,CAAC,IAAyB,GAE7F,EAAE,kBAAe,IAAI,YAAS,OAAU,GAExC,KAAoB,GAAsC,MAA6B;EAC3F,IAAI,MAAU,KAAA,GAAW,OAAO;EAEhC,IAAM,IAAM,MAAM,QAAQ,CAAK,IAAI,EAAM,KAAK,GACxC,IAAI,OAAO,CAAG;EAEpB,OAAO,OAAO,UAAU,CAAC,KAAK,IAAI,IAAI,IAAI;CAC5C,GAEM,KAAa,GAAa,MAAkD;EAChF,IAAI,MAAU,KAAA,GAAW;EAEzB,IAAM,IAAM,MAAM,QAAQ,CAAK,IAAI,EAAM,KAAK;EAE9C,IAAI;GACF,OAAO,KAAK,MAAM,CAAG;EACvB,QAAQ;GACN,IAAI,GAAQ,MAAM,IAAI,EAAe,wBAAwB,EAAI,KAAK,GAAK;GAE3E;EACF;CACF,GAEM,IAAW,EAAI,OACf,IAAU,EAAI,MACd,IAAY,EAAI,QAChB,IAAY,EAAI,QAChB,IAAU,EAAI,MAEd,IAAS,MAAc,KAAA,IAA6C,KAAA,IAAjC,EAAU,UAAU,CAAS,GAChE,IAAO,MAAY,KAAA,IAAyC,KAAA,IAA7B,EAAU,QAAQ,CAAO;CAU9D,OAAO;EAPL,GAAI,MAAW,KAAA,KAAa,EAAE,UAAO;EACrC,GAAI,MAAS,KAAA,KAAa,EAAE,QAAK;EACjC,GAAI,MAAc,KAAA,KAAa,EAAE,QAAQ,MAAM,QAAQ,CAAS,IAAI,EAAU,KAAK,EAAU;EAC7F,OAAO,EAAiB,GAAU,CAAY;EAC9C,MAAM,EAAiB,GAAS,CAAC;CAG5B;AACT"}

package/dist/core.cjs

@@ -0,0 +1,2 @@
+const e=require("./errors.cjs");function t(t){let n=new Set,r=new Set,i=new AbortController,a,o=!1;return{cancelTimer(){a&&=(clearTimeout(a),void 0)},get disposalSignal(){return i.signal},dispose(){a&&=(clearTimeout(a),void 0);for(let t of r)t.timeoutId!==void 0&&clearTimeout(t.timeoutId),t.reject(new e.SourceDisposedError);r.clear(),n.clear(),o=!0,i.abort()},flush(e){return a?(clearTimeout(a),a=void 0,e()):Promise.resolve()},get isDisposed(){return o},get isScheduled(){return a!==void 0},notify(e){if(!o){(e??t?.onBeforeNotify)?.();for(let e of n)e();for(let e of r)e.check()}},ready(t,n){return o?Promise.reject(new e.SourceDisposedError):t()?Promise.resolve():new Promise((i,a)=>{let o={check:()=>{t()&&(o.timeoutId!==void 0&&clearTimeout(o.timeoutId),r.delete(o),i())},reject:a};n!==void 0&&(o.timeoutId=setTimeout(()=>{r.delete(o),a(new e.SourceTimeoutError(n))},n)),r.add(o)})},schedule(e,t){o||(a&&clearTimeout(a),a=setTimeout(()=>{a=void 0,e()},t))},subscribe(e){return o?()=>{}:(n.add(e),()=>n.delete(e))}}}exports.createSourceCore=t;
+//# sourceMappingURL=core.cjs.map

package/dist/core.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.cjs","names":[],"sources":["../src/core.ts"],"sourcesContent":["import { SourceDisposedError, SourceTimeoutError } from './errors';\n\n/**\n * Shared source infrastructure: listener management, debounce scheduling, and ready() polling.\n * All source factories compose this core rather than duplicating the same patterns.\n */\nexport type SourceCore = {\n  /** Cancels any pending timer without invoking the callback. */\n  cancelTimer(): void;\n\n  /** `AbortSignal` that is aborted when `dispose()` is called. */\n  readonly disposalSignal: AbortSignal;\n\n  /**\n   * Clears all listeners, cancels any pending timer, and marks the core as disposed.\n   * Subsequent method calls on the core become no-ops.\n   */\n  dispose(): void;\n\n  /**\n   * If a timer is scheduled, cancels it and immediately invokes `fn`.\n   * Returns a resolved Promise when no timer is pending.\n   */\n  flush(fn: () => Promise<void>): Promise<void>;\n\n  /** Whether `dispose()` has been called. All methods become no-ops after disposal. */\n  readonly isDisposed: boolean;\n\n  /** Whether a debounce timer is currently scheduled (drives `meta.isSearchPending`). */\n  readonly isScheduled: boolean;\n\n  /**\n   * Fire all registered listeners and wake any `ready()` waiters.\n   * When provided, `onBefore` runs once before listeners are called — use it to\n   * refresh cached meta/current before subscribers observe the new state.\n   */\n  notify(onBefore?: () => void): void;\n\n  /**\n   * Returns a Promise that resolves when `isIdle()` returns true.\n   * Resolves synchronously if already idle.\n   * Rejects with a `TimeoutError` after `timeoutMs` ms if still not idle.\n   */\n  ready(isIdle: () => boolean, timeoutMs?: number): Promise<void>;\n\n  /**\n   * Schedules a debounced callback, replacing any pending timer.\n   * The callback is invoked after `delayMs` ms of inactivity.\n   */\n  schedule(fn: () => void, delayMs: number): void;\n\n  /** Subscribe to change notifications. Returns an unsubscribe function. */\n  subscribe(listener: () => void): () => void;\n};\n\nexport function createSourceCore(opts?: { onBeforeNotify?: () => void }): SourceCore {\n  const listeners = new Set<() => void>();\n  const readyWaiters = new Set<{\n    check: () => void;\n    reject: (err: unknown) => void;\n    timeoutId?: ReturnType<typeof setTimeout>;\n  }>();\n  const controller = new AbortController();\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  let disposed = false;\n\n  return {\n    cancelTimer() {\n      if (timer) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n    },\n\n    get disposalSignal() {\n      return controller.signal;\n    },\n\n    dispose() {\n      if (timer) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n\n      for (const waiter of readyWaiters) {\n        if (waiter.timeoutId !== undefined) clearTimeout(waiter.timeoutId);\n\n        waiter.reject(new SourceDisposedError());\n      }\n\n      readyWaiters.clear();\n      listeners.clear();\n      disposed = true;\n      controller.abort();\n    },\n\n    flush(fn) {\n      if (!timer) return Promise.resolve();\n\n      clearTimeout(timer);\n      timer = undefined;\n\n      return fn();\n    },\n\n    get isDisposed() {\n      return disposed;\n    },\n\n    get isScheduled() {\n      return timer !== undefined;\n    },\n\n    notify(onBefore?: () => void) {\n      if (disposed) return;\n\n      (onBefore ?? opts?.onBeforeNotify)?.();\n\n      for (const listener of listeners) {\n        listener();\n      }\n\n      for (const waiter of readyWaiters) {\n        waiter.check();\n      }\n    },\n\n    ready(isIdle, timeoutMs) {\n      if (disposed) return Promise.reject(new SourceDisposedError());\n\n      if (isIdle()) return Promise.resolve();\n\n      return new Promise<void>((resolve, reject) => {\n        const waiter: { check: () => void; reject: (err: unknown) => void; timeoutId?: ReturnType<typeof setTimeout> } =\n          {\n            check: () => {\n              if (isIdle()) {\n                if (waiter.timeoutId !== undefined) clearTimeout(waiter.timeoutId);\n\n                readyWaiters.delete(waiter);\n                resolve();\n              }\n            },\n            reject,\n          };\n\n        if (timeoutMs !== undefined) {\n          waiter.timeoutId = setTimeout(() => {\n            readyWaiters.delete(waiter);\n            reject(new SourceTimeoutError(timeoutMs));\n          }, timeoutMs);\n        }\n\n        readyWaiters.add(waiter);\n      });\n    },\n\n    schedule(fn, delayMs) {\n      if (disposed) return;\n\n      if (timer) clearTimeout(timer);\n\n      timer = setTimeout(() => {\n        timer = undefined;\n        fn();\n      }, delayMs);\n    },\n\n    subscribe(listener) {\n      if (disposed) return () => {};\n\n      listeners.add(listener);\n\n      return () => listeners.delete(listener);\n    },\n  };\n}\n"],"mappings":"gCAuDA,SAAgB,EAAiB,EAAoD,CACnF,IAAM,EAAY,IAAI,IAChB,EAAe,IAAI,IAKnB,EAAa,IAAI,gBACnB,EACA,EAAW,GAEf,MAAO,CACL,aAAc,CACZ,AAEE,KADA,aAAa,CAAK,EACV,IAAA,GAEZ,EAEA,IAAI,gBAAiB,CACnB,OAAO,EAAW,MACpB,EAEA,SAAU,CACR,AAEE,KADA,aAAa,CAAK,EACV,IAAA,IAGV,IAAK,IAAM,KAAU,EACf,EAAO,YAAc,IAAA,IAAW,aAAa,EAAO,SAAS,EAEjE,EAAO,OAAO,IAAI,EAAA,mBAAqB,EAGzC,EAAa,MAAM,EACnB,EAAU,MAAM,EAChB,EAAW,GACX,EAAW,MAAM,CACnB,EAEA,MAAM,EAAI,CAMR,OALK,GAEL,aAAa,CAAK,EAClB,EAAQ,IAAA,GAED,EAAG,GALS,QAAQ,QAAQ,CAMrC,EAEA,IAAI,YAAa,CACf,OAAO,CACT,EAEA,IAAI,aAAc,CAChB,OAAO,IAAU,IAAA,EACnB,EAEA,OAAO,EAAuB,CACxB,MAEJ,EAAC,GAAY,GAAM,eAAA,GAAkB,EAErC,IAAK,IAAM,KAAY,EACrB,EAAS,EAGX,IAAK,IAAM,KAAU,EACnB,EAAO,MAAM,CAPsB,CASvC,EAEA,MAAM,EAAQ,EAAW,CAKvB,OAJI,EAAiB,QAAQ,OAAO,IAAI,EAAA,mBAAqB,EAEzD,EAAO,EAAU,QAAQ,QAAQ,EAE9B,IAAI,SAAe,EAAS,IAAW,CAC5C,IAAM,EACJ,CACE,UAAa,CACP,EAAO,IACL,EAAO,YAAc,IAAA,IAAW,aAAa,EAAO,SAAS,EAEjE,EAAa,OAAO,CAAM,EAC1B,EAAQ,EAEZ,EACA,QACF,EAEE,IAAc,IAAA,KAChB,EAAO,UAAY,eAAiB,CAClC,EAAa,OAAO,CAAM,EAC1B,EAAO,IAAI,EAAA,mBAAmB,CAAS,CAAC,CAC1C,EAAG,CAAS,GAGd,EAAa,IAAI,CAAM,CACzB,CAAC,CACH,EAEA,SAAS,EAAI,EAAS,CAChB,IAEA,GAAO,aAAa,CAAK,EAE7B,EAAQ,eAAiB,CACvB,EAAQ,IAAA,GACR,EAAG,CACL,EAAG,CAAO,EACZ,EAEA,UAAU,EAAU,CAKlB,OAJI,MAAuB,CAAC,GAE5B,EAAU,IAAI,CAAQ,MAET,EAAU,OAAO,CAAQ,EACxC,CACF,CACF"}

package/dist/core.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared source infrastructure: listener management, debounce scheduling, and ready() polling.
+ * All source factories compose this core rather than duplicating the same patterns.
+ */
+export type SourceCore = {
+    /** Cancels any pending timer without invoking the callback. */
+    cancelTimer(): void;
+    /** `AbortSignal` that is aborted when `dispose()` is called. */
+    readonly disposalSignal: AbortSignal;
+    /**
+     * Clears all listeners, cancels any pending timer, and marks the core as disposed.
+     * Subsequent method calls on the core become no-ops.
+     */
+    dispose(): void;
+    /**
+     * If a timer is scheduled, cancels it and immediately invokes `fn`.
+     * Returns a resolved Promise when no timer is pending.
+     */
+    flush(fn: () => Promise<void>): Promise<void>;
+    /** Whether `dispose()` has been called. All methods become no-ops after disposal. */
+    readonly isDisposed: boolean;
+    /** Whether a debounce timer is currently scheduled (drives `meta.isSearchPending`). */
+    readonly isScheduled: boolean;
+    /**
+     * Fire all registered listeners and wake any `ready()` waiters.
+     * When provided, `onBefore` runs once before listeners are called — use it to
+     * refresh cached meta/current before subscribers observe the new state.
+     */
+    notify(onBefore?: () => void): void;
+    /**
+     * Returns a Promise that resolves when `isIdle()` returns true.
+     * Resolves synchronously if already idle.
+     * Rejects with a `TimeoutError` after `timeoutMs` ms if still not idle.
+     */
+    ready(isIdle: () => boolean, timeoutMs?: number): Promise<void>;
+    /**
+     * Schedules a debounced callback, replacing any pending timer.
+     * The callback is invoked after `delayMs` ms of inactivity.
+     */
+    schedule(fn: () => void, delayMs: number): void;
+    /** Subscribe to change notifications. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+};
+export declare function createSourceCore(opts?: {
+    onBeforeNotify?: () => void;
+}): SourceCore;
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,+DAA+D;IAC/D,WAAW,IAAI,IAAI,CAAC;IAEpB,gEAAgE;IAChE,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC;IAErC;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC;IAEhB;;;OAGG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C,qFAAqF;IACrF,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B,uFAAuF;IACvF,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAEpC;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhD,0EAA0E;IAC1E,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC7C,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,GAAG,UAAU,CAyHnF"}

package/dist/core.js

@@ -0,0 +1,59 @@
+import { SourceDisposedError as e, SourceTimeoutError as t } from "./errors.js";
+//#region src/core.ts
+function n(n) {
+	let r = /* @__PURE__ */ new Set(), i = /* @__PURE__ */ new Set(), a = new AbortController(), o, s = !1;
+	return {
+		cancelTimer() {
+			o &&= (clearTimeout(o), void 0);
+		},
+		get disposalSignal() {
+			return a.signal;
+		},
+		dispose() {
+			o &&= (clearTimeout(o), void 0);
+			for (let t of i) t.timeoutId !== void 0 && clearTimeout(t.timeoutId), t.reject(new e());
+			i.clear(), r.clear(), s = !0, a.abort();
+		},
+		flush(e) {
+			return o ? (clearTimeout(o), o = void 0, e()) : Promise.resolve();
+		},
+		get isDisposed() {
+			return s;
+		},
+		get isScheduled() {
+			return o !== void 0;
+		},
+		notify(e) {
+			if (!s) {
+				(e ?? n?.onBeforeNotify)?.();
+				for (let e of r) e();
+				for (let e of i) e.check();
+			}
+		},
+		ready(n, r) {
+			return s ? Promise.reject(new e()) : n() ? Promise.resolve() : new Promise((e, a) => {
+				let o = {
+					check: () => {
+						n() && (o.timeoutId !== void 0 && clearTimeout(o.timeoutId), i.delete(o), e());
+					},
+					reject: a
+				};
+				r !== void 0 && (o.timeoutId = setTimeout(() => {
+					i.delete(o), a(new t(r));
+				}, r)), i.add(o);
+			});
+		},
+		schedule(e, t) {
+			s || (o && clearTimeout(o), o = setTimeout(() => {
+				o = void 0, e();
+			}, t));
+		},
+		subscribe(e) {
+			return s ? () => {} : (r.add(e), () => r.delete(e));
+		}
+	};
+}
+//#endregion
+export { n as createSourceCore };
+
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","names":[],"sources":["../src/core.ts"],"sourcesContent":["import { SourceDisposedError, SourceTimeoutError } from './errors';\n\n/**\n * Shared source infrastructure: listener management, debounce scheduling, and ready() polling.\n * All source factories compose this core rather than duplicating the same patterns.\n */\nexport type SourceCore = {\n  /** Cancels any pending timer without invoking the callback. */\n  cancelTimer(): void;\n\n  /** `AbortSignal` that is aborted when `dispose()` is called. */\n  readonly disposalSignal: AbortSignal;\n\n  /**\n   * Clears all listeners, cancels any pending timer, and marks the core as disposed.\n   * Subsequent method calls on the core become no-ops.\n   */\n  dispose(): void;\n\n  /**\n   * If a timer is scheduled, cancels it and immediately invokes `fn`.\n   * Returns a resolved Promise when no timer is pending.\n   */\n  flush(fn: () => Promise<void>): Promise<void>;\n\n  /** Whether `dispose()` has been called. All methods become no-ops after disposal. */\n  readonly isDisposed: boolean;\n\n  /** Whether a debounce timer is currently scheduled (drives `meta.isSearchPending`). */\n  readonly isScheduled: boolean;\n\n  /**\n   * Fire all registered listeners and wake any `ready()` waiters.\n   * When provided, `onBefore` runs once before listeners are called — use it to\n   * refresh cached meta/current before subscribers observe the new state.\n   */\n  notify(onBefore?: () => void): void;\n\n  /**\n   * Returns a Promise that resolves when `isIdle()` returns true.\n   * Resolves synchronously if already idle.\n   * Rejects with a `TimeoutError` after `timeoutMs` ms if still not idle.\n   */\n  ready(isIdle: () => boolean, timeoutMs?: number): Promise<void>;\n\n  /**\n   * Schedules a debounced callback, replacing any pending timer.\n   * The callback is invoked after `delayMs` ms of inactivity.\n   */\n  schedule(fn: () => void, delayMs: number): void;\n\n  /** Subscribe to change notifications. Returns an unsubscribe function. */\n  subscribe(listener: () => void): () => void;\n};\n\nexport function createSourceCore(opts?: { onBeforeNotify?: () => void }): SourceCore {\n  const listeners = new Set<() => void>();\n  const readyWaiters = new Set<{\n    check: () => void;\n    reject: (err: unknown) => void;\n    timeoutId?: ReturnType<typeof setTimeout>;\n  }>();\n  const controller = new AbortController();\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  let disposed = false;\n\n  return {\n    cancelTimer() {\n      if (timer) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n    },\n\n    get disposalSignal() {\n      return controller.signal;\n    },\n\n    dispose() {\n      if (timer) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n\n      for (const waiter of readyWaiters) {\n        if (waiter.timeoutId !== undefined) clearTimeout(waiter.timeoutId);\n\n        waiter.reject(new SourceDisposedError());\n      }\n\n      readyWaiters.clear();\n      listeners.clear();\n      disposed = true;\n      controller.abort();\n    },\n\n    flush(fn) {\n      if (!timer) return Promise.resolve();\n\n      clearTimeout(timer);\n      timer = undefined;\n\n      return fn();\n    },\n\n    get isDisposed() {\n      return disposed;\n    },\n\n    get isScheduled() {\n      return timer !== undefined;\n    },\n\n    notify(onBefore?: () => void) {\n      if (disposed) return;\n\n      (onBefore ?? opts?.onBeforeNotify)?.();\n\n      for (const listener of listeners) {\n        listener();\n      }\n\n      for (const waiter of readyWaiters) {\n        waiter.check();\n      }\n    },\n\n    ready(isIdle, timeoutMs) {\n      if (disposed) return Promise.reject(new SourceDisposedError());\n\n      if (isIdle()) return Promise.resolve();\n\n      return new Promise<void>((resolve, reject) => {\n        const waiter: { check: () => void; reject: (err: unknown) => void; timeoutId?: ReturnType<typeof setTimeout> } =\n          {\n            check: () => {\n              if (isIdle()) {\n                if (waiter.timeoutId !== undefined) clearTimeout(waiter.timeoutId);\n\n                readyWaiters.delete(waiter);\n                resolve();\n              }\n            },\n            reject,\n          };\n\n        if (timeoutMs !== undefined) {\n          waiter.timeoutId = setTimeout(() => {\n            readyWaiters.delete(waiter);\n            reject(new SourceTimeoutError(timeoutMs));\n          }, timeoutMs);\n        }\n\n        readyWaiters.add(waiter);\n      });\n    },\n\n    schedule(fn, delayMs) {\n      if (disposed) return;\n\n      if (timer) clearTimeout(timer);\n\n      timer = setTimeout(() => {\n        timer = undefined;\n        fn();\n      }, delayMs);\n    },\n\n    subscribe(listener) {\n      if (disposed) return () => {};\n\n      listeners.add(listener);\n\n      return () => listeners.delete(listener);\n    },\n  };\n}\n"],"mappings":";;AAuDA,SAAgB,EAAiB,GAAoD;CACnF,IAAM,oBAAY,IAAI,IAAgB,GAChC,oBAAe,IAAI,IAItB,GACG,IAAa,IAAI,gBAAgB,GACnC,GACA,IAAW;CAEf,OAAO;EACL,cAAc;GACZ,AAEE,OADA,aAAa,CAAK,GACV,KAAA;EAEZ;EAEA,IAAI,iBAAiB;GACnB,OAAO,EAAW;EACpB;EAEA,UAAU;GACR,AAEE,OADA,aAAa,CAAK,GACV,KAAA;GAGV,KAAK,IAAM,KAAU,GAGnB,AAFI,EAAO,cAAc,KAAA,KAAW,aAAa,EAAO,SAAS,GAEjE,EAAO,OAAO,IAAI,EAAoB,CAAC;GAMzC,AAHA,EAAa,MAAM,GACnB,EAAU,MAAM,GAChB,IAAW,IACX,EAAW,MAAM;EACnB;EAEA,MAAM,GAAI;GAMR,OALK,KAEL,aAAa,CAAK,GAClB,IAAQ,KAAA,GAED,EAAG,KALS,QAAQ,QAAQ;EAMrC;EAEA,IAAI,aAAa;GACf,OAAO;EACT;EAEA,IAAI,cAAc;GAChB,OAAO,MAAU,KAAA;EACnB;EAEA,OAAO,GAAuB;GACxB,QAEJ;KAAC,KAAY,GAAM,eAAA,GAAkB;IAErC,KAAK,IAAM,KAAY,GACrB,EAAS;IAGX,KAAK,IAAM,KAAU,GACnB,EAAO,MAAM;GAPsB;EASvC;EAEA,MAAM,GAAQ,GAAW;GAKvB,OAJI,IAAiB,QAAQ,OAAO,IAAI,EAAoB,CAAC,IAEzD,EAAO,IAAU,QAAQ,QAAQ,IAE9B,IAAI,SAAe,GAAS,MAAW;IAC5C,IAAM,IACJ;KACE,aAAa;MACX,AAAI,EAAO,MACL,EAAO,cAAc,KAAA,KAAW,aAAa,EAAO,SAAS,GAEjE,EAAa,OAAO,CAAM,GAC1B,EAAQ;KAEZ;KACA;IACF;IASF,AAPI,MAAc,KAAA,MAChB,EAAO,YAAY,iBAAiB;KAElC,AADA,EAAa,OAAO,CAAM,GAC1B,EAAO,IAAI,EAAmB,CAAS,CAAC;IAC1C,GAAG,CAAS,IAGd,EAAa,IAAI,CAAM;GACzB,CAAC;EACH;EAEA,SAAS,GAAI,GAAS;GAChB,MAEA,KAAO,aAAa,CAAK,GAE7B,IAAQ,iBAAiB;IAEvB,AADA,IAAQ,KAAA,GACR,EAAG;GACL,GAAG,CAAO;EACZ;EAEA,UAAU,GAAU;GAKlB,OAJI,UAAuB,CAAC,KAE5B,EAAU,IAAI,CAAQ,SAET,EAAU,OAAO,CAAQ;EACxC;CACF;AACF"}

package/dist/cursorSource.cjs

@@ -0,0 +1,2 @@
+const e=require("./errors.cjs"),t=require("./_utils.cjs"),n=require("./asyncSource.cjs");let r=require("@vielzeug/arsenal");function i(i){let a=i.queryKey??t.defaultKeyOf,o=Math.max(1,Math.trunc(i.limit??20)),s=``,c,l,u,d,f=[],p=0,m=null,h=null,g=[],_={error:null,hasNextPage:!1,hasPrevPage:!1,isLoading:!1,isSearchPending:!1,pageSize:o,totalItems:0},v=()=>{g=f,_={error:m,hasNextPage:u!==void 0,hasPrevPage:d!==void 0,isLoading:y.pendingCount()>0,isSearchPending:y.core.isScheduled,pageSize:o,totalItems:p}},y=n.createAsyncSource(i,a,v),{autoFetch:b,debounceMs:x,retryAttempts:S,retryDelay:C}=y;v();let w=()=>{y.disposed||y.core.notify()},T=()=>{h&&=(h.resolve(),null)},E=()=>({...c!==void 0&&{after:c},...l!==void 0&&{before:l},...s&&{search:s},limit:o}),D=n=>(m=null,y.fetch(n,async(n,a,o)=>{let s=Date.now();try{let e=await(0,r.retry)(e=>i.fetch(n,e),{delay:C,signal:a,times:S+1});o()&&(f=e.items,p=e.total??e.items.length,u=e.nextCursor,d=e.prevCursor,m=null,i.onFetch?.({durationMs:Date.now()-s,query:n,status:`success`}))}catch(r){if(a.aborted)return;o()&&(f=[],p=0,u=void 0,d=void 0,m=new e.SourcererError(t.extractError(r),{cause:r,context:{kind:`cursor`,limit:n.limit,...n.search&&{search:n.search}}}),i.onFetch?.({durationMs:Date.now()-s,error:m,query:n,status:`error`}))}},()=>{w(),y.pendingCount()===0&&T()})),O=()=>D(E());return b&&O(),y.startRefreshInterval(()=>void O()),{get current(){return g},get disposalSignal(){return y.disposalSignal},dispose:()=>{T(),y.dispose()},get disposed(){return y.disposed},get meta(){return _},next(){return u?(c=u,l=void 0,O()):Promise.resolve()},patch(e){let t=!1;if(e.limit!==void 0){let n=Math.max(1,Math.trunc(e.limit));n!==o&&(o=n,c=void 0,l=void 0,t=!0)}return`search`in e&&(e.search!==s||y.core.isScheduled)&&(s=e.search??``,c=void 0,l=void 0,t=!0),t?(y.core.cancelTimer(),T(),O()):Promise.resolve()},prev(){return d?(l=d,c=void 0,O()):Promise.resolve()},get query(){return{...c!==void 0&&{after:c},...l!==void 0&&{before:l},...s&&{search:s},limit:o}},ready(e){return y.ready(e)},refresh(){return O()},reset(){return y.core.cancelTimer(),T(),s=``,c=void 0,l=void 0,O()},search(e,t){if(t?.immediate)return e===s&&!y.core.isScheduled?Promise.resolve():(y.core.cancelTimer(),T(),s=e,c=void 0,l=void 0,O());if(e===s)return Promise.resolve();T(),s=e,c=void 0,l=void 0;let n,r=new Promise(e=>{n=e});return h={promise:r,resolve:n},y.core.schedule(()=>void O(),x),w(),r},subscribe:e=>y.core.subscribe(e),[Symbol.dispose]:()=>{T(),y.dispose()}}}exports.createCursorSource=i;
+//# sourceMappingURL=cursorSource.cjs.map