@vielzeug/sourcerer 1.0.6 → 2.0.0

package/dist/applyQuery.cjs

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

package/dist/applyQuery.cjs.map

@@ -1 +0,0 @@
-{"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

@@ -1,20 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,8 +0,0 @@
-//#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

@@ -1 +0,0 @@
-{"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/asyncSearch.cjs

@@ -1,2 +0,0 @@
-function e(e,t){let n=null,r=()=>{n&&=(n(),null)};return{cancel(){e.cancelTimer(),r()},dispose(){r()},schedule(i,a){r();let o=new Promise(e=>{n=e});return e.schedule(i,a),t(),o},settleIfIdle(e){e===0&&r()}}}exports.createAsyncSearchCoordinator=e;
-//# sourceMappingURL=asyncSearch.cjs.map

package/dist/asyncSearch.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"asyncSearch.cjs","names":[],"sources":["../src/asyncSearch.ts"],"sourcesContent":["import type { SourceCore } from './core';\n\nexport type AsyncSearchCoordinator = Readonly<{\n  cancel(): void;\n  dispose(): void;\n  schedule(run: () => void, delayMs: number): Promise<void>;\n  settleIfIdle(pendingCount: number): void;\n}>;\n\n/**\n * Shared debounced-search promise orchestration for async sources.\n * Keeps search() promise lifecycles consistent across remote/cursor/infinite sources.\n */\nexport function createAsyncSearchCoordinator(core: SourceCore, notify: () => void): AsyncSearchCoordinator {\n  let pendingResolve: (() => void) | null = null;\n\n  const resolvePending = () => {\n    if (pendingResolve) {\n      pendingResolve();\n      pendingResolve = null;\n    }\n  };\n\n  return {\n    cancel() {\n      core.cancelTimer();\n      resolvePending();\n    },\n\n    dispose() {\n      resolvePending();\n    },\n\n    schedule(run, delayMs) {\n      resolvePending();\n\n      const promise = new Promise<void>((resolve) => {\n        pendingResolve = resolve;\n      });\n\n      core.schedule(run, delayMs);\n      notify();\n\n      return promise;\n    },\n\n    settleIfIdle(pendingCount) {\n      if (pendingCount === 0) resolvePending();\n    },\n  };\n}\n"],"mappings":"AAaA,SAAgB,EAA6B,EAAkB,EAA4C,CACzG,IAAI,EAAsC,KAEpC,MAAuB,CAC3B,AAEE,KADA,EAAe,EACE,KAErB,EAEA,MAAO,CACL,QAAS,CACP,EAAK,YAAY,EACjB,EAAe,CACjB,EAEA,SAAU,CACR,EAAe,CACjB,EAEA,SAAS,EAAK,EAAS,CACrB,EAAe,EAEf,IAAM,EAAU,IAAI,QAAe,GAAY,CAC7C,EAAiB,CACnB,CAAC,EAKD,OAHA,EAAK,SAAS,EAAK,CAAO,EAC1B,EAAO,EAEA,CACT,EAEA,aAAa,EAAc,CACrB,IAAiB,GAAG,EAAe,CACzC,CACF,CACF"}

package/dist/asyncSearch.d.ts

@@ -1,13 +0,0 @@
-import type { SourceCore } from './core';
-export type AsyncSearchCoordinator = Readonly<{
-    cancel(): void;
-    dispose(): void;
-    schedule(run: () => void, delayMs: number): Promise<void>;
-    settleIfIdle(pendingCount: number): void;
-}>;
-/**
- * Shared debounced-search promise orchestration for async sources.
- * Keeps search() promise lifecycles consistent across remote/cursor/infinite sources.
- */
-export declare function createAsyncSearchCoordinator(core: SourceCore, notify: () => void): AsyncSearchCoordinator;
-//# sourceMappingURL=asyncSearch.d.ts.map

package/dist/asyncSearch.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"asyncSearch.d.ts","sourceRoot":"","sources":["../src/asyncSearch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,MAAM,IAAI,IAAI,CAAC;IACf,OAAO,IAAI,IAAI,CAAC;IAChB,QAAQ,CAAC,GAAG,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C,CAAC,CAAC;AAEH;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,IAAI,GAAG,sBAAsB,CAqCzG"}

package/dist/asyncSearch.js

@@ -1,28 +0,0 @@
-//#region src/asyncSearch.ts
-function e(e, t) {
-	let n = null, r = () => {
-		n &&= (n(), null);
-	};
-	return {
-		cancel() {
-			e.cancelTimer(), r();
-		},
-		dispose() {
-			r();
-		},
-		schedule(i, a) {
-			r();
-			let o = new Promise((e) => {
-				n = e;
-			});
-			return e.schedule(i, a), t(), o;
-		},
-		settleIfIdle(e) {
-			e === 0 && r();
-		}
-	};
-}
-//#endregion
-export { e as createAsyncSearchCoordinator };
-
-//# sourceMappingURL=asyncSearch.js.map

package/dist/asyncSearch.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"asyncSearch.js","names":[],"sources":["../src/asyncSearch.ts"],"sourcesContent":["import type { SourceCore } from './core';\n\nexport type AsyncSearchCoordinator = Readonly<{\n  cancel(): void;\n  dispose(): void;\n  schedule(run: () => void, delayMs: number): Promise<void>;\n  settleIfIdle(pendingCount: number): void;\n}>;\n\n/**\n * Shared debounced-search promise orchestration for async sources.\n * Keeps search() promise lifecycles consistent across remote/cursor/infinite sources.\n */\nexport function createAsyncSearchCoordinator(core: SourceCore, notify: () => void): AsyncSearchCoordinator {\n  let pendingResolve: (() => void) | null = null;\n\n  const resolvePending = () => {\n    if (pendingResolve) {\n      pendingResolve();\n      pendingResolve = null;\n    }\n  };\n\n  return {\n    cancel() {\n      core.cancelTimer();\n      resolvePending();\n    },\n\n    dispose() {\n      resolvePending();\n    },\n\n    schedule(run, delayMs) {\n      resolvePending();\n\n      const promise = new Promise<void>((resolve) => {\n        pendingResolve = resolve;\n      });\n\n      core.schedule(run, delayMs);\n      notify();\n\n      return promise;\n    },\n\n    settleIfIdle(pendingCount) {\n      if (pendingCount === 0) resolvePending();\n    },\n  };\n}\n"],"mappings":";AAaA,SAAgB,EAA6B,GAAkB,GAA4C;CACzG,IAAI,IAAsC,MAEpC,UAAuB;EAC3B,AAEE,OADA,EAAe,GACE;CAErB;CAEA,OAAO;EACL,SAAS;GAEP,AADA,EAAK,YAAY,GACjB,EAAe;EACjB;EAEA,UAAU;GACR,EAAe;EACjB;EAEA,SAAS,GAAK,GAAS;GACrB,EAAe;GAEf,IAAM,IAAU,IAAI,SAAe,MAAY;IAC7C,IAAiB;GACnB,CAAC;GAKD,OAHA,EAAK,SAAS,GAAK,CAAO,GAC1B,EAAO,GAEA;EACT;EAEA,aAAa,GAAc;GACzB,AAAI,MAAiB,KAAG,EAAe;EACzC;CACF;AACF"}

package/dist/codecs.cjs

@@ -1,2 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,30 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,36 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,2 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,47 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,59 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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/derive.cjs

@@ -1,2 +0,0 @@
-const e=require("./core.cjs");function t(t,n){let r=e.createSourceCore(),i=[],a=()=>{i=n(t.current)};a();let o=t.subscribe(()=>{a(),r.notify()});`disposalSignal`in t&&t.disposalSignal instanceof AbortSignal&&t.disposalSignal.addEventListener(`abort`,()=>r.dispose(),{once:!0});let s={get current(){return i},get disposalSignal(){return r.disposalSignal},dispose(){r.isDisposed||(o(),r.dispose())},get disposed(){return r.isDisposed},get meta(){return t.meta},subscribe(e){return r.subscribe(e)},[Symbol.dispose](){s.dispose()}};return s}exports.deriveSource=t;
-//# sourceMappingURL=derive.cjs.map

package/dist/derive.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"derive.cjs","names":[],"sources":["../src/derive.ts"],"sourcesContent":["import type { DerivedSource } from './types';\n\nimport { createSourceCore } from './core';\n\n/**\n * Creates a reactive read-only projection derived from a parent source.\n *\n * The derived source mirrors the parent's `meta` and applies `transform` to `current`\n * whenever the parent changes. This is useful for client-side projections (e.g. additional\n * filtering, mapping, or sorting) over a remote source without re-fetching.\n *\n * Call `dispose()` to stop listening to the parent.\n *\n * @example\n * ```ts\n * const source = createRemoteSource<User>({ fetch: fetchUsers, limit: 20 });\n *\n * // Show only active users without re-fetching.\n * const activeUsers = deriveSource(source, (items) => items.filter((u) => u.active));\n *\n * activeUsers.subscribe(() => {\n *   console.log(activeUsers.current, activeUsers.meta.totalItems);\n * });\n * ```\n */\nexport function deriveSource<T, U, TMeta>(\n  parent: {\n    readonly current: readonly T[];\n    readonly meta: TMeta;\n    subscribe(listener: () => void): () => void;\n  },\n  transform: (items: readonly T[]) => readonly U[],\n): DerivedSource<U, TMeta> {\n  const core = createSourceCore();\n  let cachedCurrent: readonly U[] = [];\n\n  const applyTransform = () => {\n    cachedCurrent = transform(parent.current);\n  };\n\n  applyTransform();\n\n  const unsubscribeParent = parent.subscribe(() => {\n    applyTransform();\n    core.notify();\n  });\n\n  if ('disposalSignal' in parent && parent.disposalSignal instanceof AbortSignal) {\n    parent.disposalSignal.addEventListener('abort', () => core.dispose(), { once: true });\n  }\n\n  const source: DerivedSource<U, TMeta> = {\n    get current() {\n      return cachedCurrent;\n    },\n\n    get disposalSignal() {\n      return core.disposalSignal;\n    },\n\n    dispose() {\n      if (core.isDisposed) return;\n\n      unsubscribeParent();\n      core.dispose();\n    },\n\n    get disposed() {\n      return core.isDisposed;\n    },\n\n    get meta() {\n      return parent.meta;\n    },\n\n    subscribe(listener) {\n      return core.subscribe(listener);\n    },\n\n    [Symbol.dispose]() {\n      source.dispose();\n    },\n  };\n\n  return source;\n}\n"],"mappings":"8BAyBA,SAAgB,EACd,EAKA,EACyB,CACzB,IAAM,EAAO,EAAA,iBAAiB,EAC1B,EAA8B,CAAC,EAE7B,MAAuB,CAC3B,EAAgB,EAAU,EAAO,OAAO,CAC1C,EAEA,EAAe,EAEf,IAAM,EAAoB,EAAO,cAAgB,CAC/C,EAAe,EACf,EAAK,OAAO,CACd,CAAC,EAEG,mBAAoB,GAAU,EAAO,0BAA0B,aACjE,EAAO,eAAe,iBAAiB,YAAe,EAAK,QAAQ,EAAG,CAAE,KAAM,EAAK,CAAC,EAGtF,IAAM,EAAkC,CACtC,IAAI,SAAU,CACZ,OAAO,CACT,EAEA,IAAI,gBAAiB,CACnB,OAAO,EAAK,cACd,EAEA,SAAU,CACJ,EAAK,aAET,EAAkB,EAClB,EAAK,QAAQ,EACf,EAEA,IAAI,UAAW,CACb,OAAO,EAAK,UACd,EAEA,IAAI,MAAO,CACT,OAAO,EAAO,IAChB,EAEA,UAAU,EAAU,CAClB,OAAO,EAAK,UAAU,CAAQ,CAChC,EAEA,CAAC,OAAO,UAAW,CACjB,EAAO,QAAQ,CACjB,CACF,EAEA,OAAO,CACT"}

package/dist/derive.d.ts

@@ -1,28 +0,0 @@
-import type { DerivedSource } from './types';
-/**
- * Creates a reactive read-only projection derived from a parent source.
- *
- * The derived source mirrors the parent's `meta` and applies `transform` to `current`
- * whenever the parent changes. This is useful for client-side projections (e.g. additional
- * filtering, mapping, or sorting) over a remote source without re-fetching.
- *
- * Call `dispose()` to stop listening to the parent.
- *
- * @example
- * ```ts
- * const source = createRemoteSource<User>({ fetch: fetchUsers, limit: 20 });
- *
- * // Show only active users without re-fetching.
- * const activeUsers = deriveSource(source, (items) => items.filter((u) => u.active));
- *
- * activeUsers.subscribe(() => {
- *   console.log(activeUsers.current, activeUsers.meta.totalItems);
- * });
- * ```
- */
-export declare function deriveSource<T, U, TMeta>(parent: {
-    readonly current: readonly T[];
-    readonly meta: TMeta;
-    subscribe(listener: () => void): () => void;
-}, transform: (items: readonly T[]) => readonly U[]): DerivedSource<U, TMeta>;
-//# sourceMappingURL=derive.d.ts.map

package/dist/derive.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAI7C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EACtC,MAAM,EAAE;IACN,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC7C,EACD,SAAS,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,KAAK,SAAS,CAAC,EAAE,GAC/C,aAAa,CAAC,CAAC,EAAE,KAAK,CAAC,CAqDzB"}

package/dist/derive.js

@@ -1,40 +0,0 @@
-import { createSourceCore as e } from "./core.js";
-//#region src/derive.ts
-function t(t, n) {
-	let r = e(), i = [], a = () => {
-		i = n(t.current);
-	};
-	a();
-	let o = t.subscribe(() => {
-		a(), r.notify();
-	});
-	"disposalSignal" in t && t.disposalSignal instanceof AbortSignal && t.disposalSignal.addEventListener("abort", () => r.dispose(), { once: !0 });
-	let s = {
-		get current() {
-			return i;
-		},
-		get disposalSignal() {
-			return r.disposalSignal;
-		},
-		dispose() {
-			r.isDisposed || (o(), r.dispose());
-		},
-		get disposed() {
-			return r.isDisposed;
-		},
-		get meta() {
-			return t.meta;
-		},
-		subscribe(e) {
-			return r.subscribe(e);
-		},
-		[Symbol.dispose]() {
-			s.dispose();
-		}
-	};
-	return s;
-}
-//#endregion
-export { t as deriveSource };
-
-//# sourceMappingURL=derive.js.map

package/dist/derive.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"derive.js","names":[],"sources":["../src/derive.ts"],"sourcesContent":["import type { DerivedSource } from './types';\n\nimport { createSourceCore } from './core';\n\n/**\n * Creates a reactive read-only projection derived from a parent source.\n *\n * The derived source mirrors the parent's `meta` and applies `transform` to `current`\n * whenever the parent changes. This is useful for client-side projections (e.g. additional\n * filtering, mapping, or sorting) over a remote source without re-fetching.\n *\n * Call `dispose()` to stop listening to the parent.\n *\n * @example\n * ```ts\n * const source = createRemoteSource<User>({ fetch: fetchUsers, limit: 20 });\n *\n * // Show only active users without re-fetching.\n * const activeUsers = deriveSource(source, (items) => items.filter((u) => u.active));\n *\n * activeUsers.subscribe(() => {\n *   console.log(activeUsers.current, activeUsers.meta.totalItems);\n * });\n * ```\n */\nexport function deriveSource<T, U, TMeta>(\n  parent: {\n    readonly current: readonly T[];\n    readonly meta: TMeta;\n    subscribe(listener: () => void): () => void;\n  },\n  transform: (items: readonly T[]) => readonly U[],\n): DerivedSource<U, TMeta> {\n  const core = createSourceCore();\n  let cachedCurrent: readonly U[] = [];\n\n  const applyTransform = () => {\n    cachedCurrent = transform(parent.current);\n  };\n\n  applyTransform();\n\n  const unsubscribeParent = parent.subscribe(() => {\n    applyTransform();\n    core.notify();\n  });\n\n  if ('disposalSignal' in parent && parent.disposalSignal instanceof AbortSignal) {\n    parent.disposalSignal.addEventListener('abort', () => core.dispose(), { once: true });\n  }\n\n  const source: DerivedSource<U, TMeta> = {\n    get current() {\n      return cachedCurrent;\n    },\n\n    get disposalSignal() {\n      return core.disposalSignal;\n    },\n\n    dispose() {\n      if (core.isDisposed) return;\n\n      unsubscribeParent();\n      core.dispose();\n    },\n\n    get disposed() {\n      return core.isDisposed;\n    },\n\n    get meta() {\n      return parent.meta;\n    },\n\n    subscribe(listener) {\n      return core.subscribe(listener);\n    },\n\n    [Symbol.dispose]() {\n      source.dispose();\n    },\n  };\n\n  return source;\n}\n"],"mappings":";;AAyBA,SAAgB,EACd,GAKA,GACyB;CACzB,IAAM,IAAO,EAAiB,GAC1B,IAA8B,CAAC,GAE7B,UAAuB;EAC3B,IAAgB,EAAU,EAAO,OAAO;CAC1C;CAEA,EAAe;CAEf,IAAM,IAAoB,EAAO,gBAAgB;EAE/C,AADA,EAAe,GACf,EAAK,OAAO;CACd,CAAC;CAED,AAAI,oBAAoB,KAAU,EAAO,0BAA0B,eACjE,EAAO,eAAe,iBAAiB,eAAe,EAAK,QAAQ,GAAG,EAAE,MAAM,GAAK,CAAC;CAGtF,IAAM,IAAkC;EACtC,IAAI,UAAU;GACZ,OAAO;EACT;EAEA,IAAI,iBAAiB;GACnB,OAAO,EAAK;EACd;EAEA,UAAU;GACJ,EAAK,eAET,EAAkB,GAClB,EAAK,QAAQ;EACf;EAEA,IAAI,WAAW;GACb,OAAO,EAAK;EACd;EAEA,IAAI,OAAO;GACT,OAAO,EAAO;EAChB;EAEA,UAAU,GAAU;GAClB,OAAO,EAAK,UAAU,CAAQ;EAChC;EAEA,CAAC,OAAO,WAAW;GACjB,EAAO,QAAQ;EACjB;CACF;CAEA,OAAO;AACT"}

package/dist/errors.cjs

@@ -1,2 +0,0 @@
-var e=class e extends Error{#e;constructor(e,t={}){super(e,t.cause===void 0?void 0:{cause:t.cause}),this.name=new.target.name,Object.setPrototypeOf(this,new.target.prototype),this.#e=t}get attempt(){return this.#e.attempt??0}get context(){return this.#e.context}static is(t){return t instanceof e}},t=class extends e{timeoutMs;constructor(e){super(`Source.ready() timed out after ${e}ms`),this.timeoutMs=e}},n=class extends e{constructor(){super(`Source disposed while waiting for ready()`)}};exports.SourceDisposedError=n,exports.SourceTimeoutError=t,exports.SourcererError=e;
-//# sourceMappingURL=errors.cjs.map

package/dist/errors.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.cjs","names":["#opts"],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Structured context carried by `SourcererError`.\n * Discriminated on `kind` — narrow with `error.context?.kind` to access typed fields.\n *\n * @example\n * ```ts\n * if (source.meta.error?.context?.kind === 'remote') {\n *   console.log('Failed page', source.meta.error.context.page);\n * }\n * ```\n */\nexport type SourcererErrorContext =\n  | Readonly<{ kind: 'cursor'; limit: number; search?: string }>\n  | Readonly<{ kind: 'infinite'; limit: number; page: number; search?: string }>\n  | Readonly<{ kind: 'remote'; limit: number; page: number; search?: string }>;\n\n/**\n * Base class for all sourcerer errors. Catch with `instanceof SourcererError` to handle any\n * sourcerer-originated error regardless of specific subtype.\n *\n * Carries the original cause, structured context, and the attempt number.\n *\n * @example\n * ```ts\n * if (source.meta.error) {\n *   console.error(source.meta.error.message, source.meta.error.context);\n * }\n * ```\n */\nexport class SourcererError extends Error {\n  readonly #opts: {\n    readonly attempt?: number;\n    readonly cause?: unknown;\n    readonly context?: SourcererErrorContext;\n  };\n\n  constructor(\n    message: string,\n    opts: {\n      readonly attempt?: number;\n      readonly cause?: unknown;\n      readonly context?: SourcererErrorContext;\n    } = {},\n  ) {\n    super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);\n    this.name = new.target.name;\n    Object.setPrototypeOf(this, new.target.prototype);\n    this.#opts = opts;\n  }\n\n  get attempt(): number {\n    return this.#opts.attempt ?? 0;\n  }\n\n  /** Context bag for the error — safe to log. */\n  get context(): SourcererErrorContext | undefined {\n    return this.#opts.context;\n  }\n\n  static is(err: unknown): err is SourcererError {\n    return err instanceof SourcererError;\n  }\n}\n\n/** Thrown by `ready()` when the source timed out waiting for the first successful fetch. */\nexport class SourceTimeoutError extends SourcererError {\n  /** The configured timeout in milliseconds. */\n  readonly timeoutMs: number;\n\n  constructor(timeoutMs: number) {\n    super(`Source.ready() timed out after ${timeoutMs}ms`);\n    this.timeoutMs = timeoutMs;\n  }\n}\n\n/** Thrown by `ready()` when the source is disposed while waiting. */\nexport class SourceDisposedError extends SourcererError {\n  constructor() {\n    super('Source disposed while waiting for ready()');\n  }\n}\n"],"mappings":"AA6BA,IAAa,EAAb,MAAa,UAAuB,KAAM,CACxC,GAMA,YACE,EACA,EAII,CAAC,EACL,CACA,MAAM,EAAS,EAAK,QAAU,IAAA,GAAoC,IAAA,GAAxB,CAAE,MAAO,EAAK,KAAM,CAAa,EAC3E,KAAK,KAAO,IAAI,OAAO,KACvB,OAAO,eAAe,KAAM,IAAI,OAAO,SAAS,EAChD,KAAKA,GAAQ,CACf,CAEA,IAAI,SAAkB,CACpB,OAAO,KAAKA,GAAM,SAAW,CAC/B,CAGA,IAAI,SAA6C,CAC/C,OAAO,KAAKA,GAAM,OACpB,CAEA,OAAO,GAAG,EAAqC,CAC7C,OAAO,aAAe,CACxB,CACF,EAGa,EAAb,cAAwC,CAAe,CAErD,UAEA,YAAY,EAAmB,CAC7B,MAAM,kCAAkC,EAAU,GAAG,EACrD,KAAK,UAAY,CACnB,CACF,EAGa,EAAb,cAAyC,CAAe,CACtD,aAAc,CACZ,MAAM,2CAA2C,CACnD,CACF"}

package/dist/errors.d.ts

@@ -1,62 +0,0 @@
-/**
- * Structured context carried by `SourcererError`.
- * Discriminated on `kind` — narrow with `error.context?.kind` to access typed fields.
- *
- * @example
- * ```ts
- * if (source.meta.error?.context?.kind === 'remote') {
- *   console.log('Failed page', source.meta.error.context.page);
- * }
- * ```
- */
-export type SourcererErrorContext = Readonly<{
-    kind: 'cursor';
-    limit: number;
-    search?: string;
-}> | Readonly<{
-    kind: 'infinite';
-    limit: number;
-    page: number;
-    search?: string;
-}> | Readonly<{
-    kind: 'remote';
-    limit: number;
-    page: number;
-    search?: string;
-}>;
-/**
- * Base class for all sourcerer errors. Catch with `instanceof SourcererError` to handle any
- * sourcerer-originated error regardless of specific subtype.
- *
- * Carries the original cause, structured context, and the attempt number.
- *
- * @example
- * ```ts
- * if (source.meta.error) {
- *   console.error(source.meta.error.message, source.meta.error.context);
- * }
- * ```
- */
-export declare class SourcererError extends Error {
-    #private;
-    constructor(message: string, opts?: {
-        readonly attempt?: number;
-        readonly cause?: unknown;
-        readonly context?: SourcererErrorContext;
-    });
-    get attempt(): number;
-    /** Context bag for the error — safe to log. */
-    get context(): SourcererErrorContext | undefined;
-    static is(err: unknown): err is SourcererError;
-}
-/** Thrown by `ready()` when the source timed out waiting for the first successful fetch. */
-export declare class SourceTimeoutError extends SourcererError {
-    /** The configured timeout in milliseconds. */
-    readonly timeoutMs: number;
-    constructor(timeoutMs: number);
-}
-/** Thrown by `ready()` when the source is disposed while waiting. */
-export declare class SourceDisposedError extends SourcererError {
-    constructor();
-}
-//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qBAAqB,GAC7B,QAAQ,CAAC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAC5D,QAAQ,CAAC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAC5E,QAAQ,CAAC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE/E;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAe,SAAQ,KAAK;;gBAQrC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;QACJ,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;KACrC;IAQR,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,+CAA+C;IAC/C,IAAI,OAAO,IAAI,qBAAqB,GAAG,SAAS,CAE/C;IAED,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc;CAG/C;AAED,4FAA4F;AAC5F,qBAAa,kBAAmB,SAAQ,cAAc;IACpD,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM;CAI9B;AAED,qEAAqE;AACrE,qBAAa,mBAAoB,SAAQ,cAAc;;CAItD"}

package/dist/errors.js

@@ -1,29 +0,0 @@
-//#region src/errors.ts
-var e = class e extends Error {
-	#e;
-	constructor(e, t = {}) {
-		super(e, t.cause === void 0 ? void 0 : { cause: t.cause }), this.name = new.target.name, Object.setPrototypeOf(this, new.target.prototype), this.#e = t;
-	}
-	get attempt() {
-		return this.#e.attempt ?? 0;
-	}
-	get context() {
-		return this.#e.context;
-	}
-	static is(t) {
-		return t instanceof e;
-	}
-}, t = class extends e {
-	timeoutMs;
-	constructor(e) {
-		super(`Source.ready() timed out after ${e}ms`), this.timeoutMs = e;
-	}
-}, n = class extends e {
-	constructor() {
-		super("Source disposed while waiting for ready()");
-	}
-};
-//#endregion
-export { n as SourceDisposedError, t as SourceTimeoutError, e as SourcererError };
-
-//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.js","names":["#opts"],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Structured context carried by `SourcererError`.\n * Discriminated on `kind` — narrow with `error.context?.kind` to access typed fields.\n *\n * @example\n * ```ts\n * if (source.meta.error?.context?.kind === 'remote') {\n *   console.log('Failed page', source.meta.error.context.page);\n * }\n * ```\n */\nexport type SourcererErrorContext =\n  | Readonly<{ kind: 'cursor'; limit: number; search?: string }>\n  | Readonly<{ kind: 'infinite'; limit: number; page: number; search?: string }>\n  | Readonly<{ kind: 'remote'; limit: number; page: number; search?: string }>;\n\n/**\n * Base class for all sourcerer errors. Catch with `instanceof SourcererError` to handle any\n * sourcerer-originated error regardless of specific subtype.\n *\n * Carries the original cause, structured context, and the attempt number.\n *\n * @example\n * ```ts\n * if (source.meta.error) {\n *   console.error(source.meta.error.message, source.meta.error.context);\n * }\n * ```\n */\nexport class SourcererError extends Error {\n  readonly #opts: {\n    readonly attempt?: number;\n    readonly cause?: unknown;\n    readonly context?: SourcererErrorContext;\n  };\n\n  constructor(\n    message: string,\n    opts: {\n      readonly attempt?: number;\n      readonly cause?: unknown;\n      readonly context?: SourcererErrorContext;\n    } = {},\n  ) {\n    super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);\n    this.name = new.target.name;\n    Object.setPrototypeOf(this, new.target.prototype);\n    this.#opts = opts;\n  }\n\n  get attempt(): number {\n    return this.#opts.attempt ?? 0;\n  }\n\n  /** Context bag for the error — safe to log. */\n  get context(): SourcererErrorContext | undefined {\n    return this.#opts.context;\n  }\n\n  static is(err: unknown): err is SourcererError {\n    return err instanceof SourcererError;\n  }\n}\n\n/** Thrown by `ready()` when the source timed out waiting for the first successful fetch. */\nexport class SourceTimeoutError extends SourcererError {\n  /** The configured timeout in milliseconds. */\n  readonly timeoutMs: number;\n\n  constructor(timeoutMs: number) {\n    super(`Source.ready() timed out after ${timeoutMs}ms`);\n    this.timeoutMs = timeoutMs;\n  }\n}\n\n/** Thrown by `ready()` when the source is disposed while waiting. */\nexport class SourceDisposedError extends SourcererError {\n  constructor() {\n    super('Source disposed while waiting for ready()');\n  }\n}\n"],"mappings":";AA6BA,IAAa,IAAb,MAAa,UAAuB,MAAM;CACxC;CAMA,YACE,GACA,IAII,CAAC,GACL;EAIA,AAHA,MAAM,GAAS,EAAK,UAAU,KAAA,IAAoC,KAAA,IAAxB,EAAE,OAAO,EAAK,MAAM,CAAa,GAC3E,KAAK,OAAO,IAAI,OAAO,MACvB,OAAO,eAAe,MAAM,IAAI,OAAO,SAAS,GAChD,KAAKA,KAAQ;CACf;CAEA,IAAI,UAAkB;EACpB,OAAO,KAAKA,GAAM,WAAW;CAC/B;CAGA,IAAI,UAA6C;EAC/C,OAAO,KAAKA,GAAM;CACpB;CAEA,OAAO,GAAG,GAAqC;EAC7C,OAAO,aAAe;CACxB;AACF,GAGa,IAAb,cAAwC,EAAe;CAErD;CAEA,YAAY,GAAmB;EAE7B,AADA,MAAM,kCAAkC,EAAU,GAAG,GACrD,KAAK,YAAY;CACnB;AACF,GAGa,IAAb,cAAyC,EAAe;CACtD,cAAc;EACZ,MAAM,2CAA2C;CACnD;AACF"}

package/dist/fetchManager.cjs

@@ -1,2 +0,0 @@
-function e(e){let t=new Map,n=``,r=0;return{dispose(){for(let e of t.values())e.controller.abort();t.clear(),r=0},get pendingCount(){return r},async run(i,a,o){let s=e(i);n=s;for(let[e,n]of t)e!==s&&(n.controller.abort(),t.delete(e));let c=t.get(s);if(c){r++,o();try{await c.promise}finally{r--,o()}return}let l=new AbortController;r++,o();let u=a(i,l.signal,()=>s===n).finally(()=>{t.delete(s),r--,o()});t.set(s,{controller:l,promise:u}),await u}}}exports.createFetchManager=e;
-//# sourceMappingURL=fetchManager.cjs.map

package/dist/fetchManager.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"fetchManager.cjs","names":[],"sources":["../src/fetchManager.ts"],"sourcesContent":["/**\n * Internal fetch deduplication and in-flight request manager.\n *\n * - Deduplicates identical concurrent queries: joiners await the existing in-flight promise.\n * - Aborts superseded in-flight requests when a new query key arrives.\n * - Tracks pending count so callers can reflect loading state.\n *\n * Not exported from the public API — consumed via `asyncSource.ts` by remoteSource,\n * cursorSource, and infiniteSource.\n */\n\ntype InFlightEntry = { controller: AbortController; promise: Promise<void> };\n\nexport type FetchManager<TQuery> = {\n  /** Abort all in-flight requests and clear the registry. */\n  dispose(): void;\n  /** Number of currently in-flight requests (including joiners). */\n  readonly pendingCount: number;\n  /**\n   * Run a fetch for query `q`.\n   *\n   * - If an identical key is already in-flight, joins as a waiter.\n   * - If a different key is in-flight, aborts it and starts a new request.\n   * - Calls `onPendingChange()` whenever `pendingCount` changes.\n   * - Passes an `isLatest()` predicate to `execute` so it can skip stale responses.\n   */\n  run(\n    q: TQuery,\n    execute: (q: TQuery, signal: AbortSignal, isLatest: () => boolean) => Promise<void>,\n    onPendingChange: () => void,\n  ): Promise<void>;\n};\n\nexport function createFetchManager<TQuery>(keyOf: (q: TQuery) => string): FetchManager<TQuery> {\n  const inflight = new Map<string, InFlightEntry>();\n  let latestKey = '';\n  let _pendingCount = 0;\n\n  return {\n    dispose() {\n      for (const entry of inflight.values()) {\n        entry.controller.abort();\n      }\n\n      inflight.clear();\n      _pendingCount = 0;\n    },\n\n    get pendingCount() {\n      return _pendingCount;\n    },\n\n    async run(q, execute, onPendingChange) {\n      const key = keyOf(q);\n\n      latestKey = key;\n\n      // Abort and remove all superseded in-flight requests.\n      for (const [k, entry] of inflight) {\n        if (k !== key) {\n          entry.controller.abort();\n          inflight.delete(k);\n        }\n      }\n\n      // Join an identical in-flight request rather than issuing a duplicate.\n      const existing = inflight.get(key);\n\n      if (existing) {\n        _pendingCount++;\n        onPendingChange();\n\n        try {\n          await existing.promise;\n        } finally {\n          _pendingCount--;\n          onPendingChange();\n        }\n\n        return;\n      }\n\n      // New request.\n      const controller = new AbortController();\n\n      _pendingCount++;\n      onPendingChange();\n\n      const promise = execute(q, controller.signal, () => key === latestKey).finally(() => {\n        inflight.delete(key);\n        _pendingCount--;\n        onPendingChange();\n      });\n\n      inflight.set(key, { controller, promise });\n      await promise;\n    },\n  };\n}\n"],"mappings":"AAiCA,SAAgB,EAA2B,EAAoD,CAC7F,IAAM,EAAW,IAAI,IACjB,EAAY,GACZ,EAAgB,EAEpB,MAAO,CACL,SAAU,CACR,IAAK,IAAM,KAAS,EAAS,OAAO,EAClC,EAAM,WAAW,MAAM,EAGzB,EAAS,MAAM,EACf,EAAgB,CAClB,EAEA,IAAI,cAAe,CACjB,OAAO,CACT,EAEA,MAAM,IAAI,EAAG,EAAS,EAAiB,CACrC,IAAM,EAAM,EAAM,CAAC,EAEnB,EAAY,EAGZ,IAAK,GAAM,CAAC,EAAG,KAAU,EACnB,IAAM,IACR,EAAM,WAAW,MAAM,EACvB,EAAS,OAAO,CAAC,GAKrB,IAAM,EAAW,EAAS,IAAI,CAAG,EAEjC,GAAI,EAAU,CACZ,IACA,EAAgB,EAEhB,GAAI,CACF,MAAM,EAAS,OACjB,QAAU,CACR,IACA,EAAgB,CAClB,CAEA,MACF,CAGA,IAAM,EAAa,IAAI,gBAEvB,IACA,EAAgB,EAEhB,IAAM,EAAU,EAAQ,EAAG,EAAW,WAAc,IAAQ,CAAS,CAAC,CAAC,YAAc,CACnF,EAAS,OAAO,CAAG,EACnB,IACA,EAAgB,CAClB,CAAC,EAED,EAAS,IAAI,EAAK,CAAE,aAAY,SAAQ,CAAC,EACzC,MAAM,CACR,CACF,CACF"}