@vielzeug/sourcerer 1.0.2

package/dist/prefetch.js

@@ -0,0 +1,38 @@
+import { createRemoteSource as e } from "./remoteSource.js";
+//#region src/prefetch.ts
+var t = (e) => {
+	let t = e.query;
+	return {
+		items: e.current,
+		...t.search && { search: t.search },
+		page: e.meta.pageNumber,
+		total: e.meta.totalItems
+	};
+};
+async function n(n) {
+	let r = e({
+		...n,
+		autoFetch: !1
+	});
+	try {
+		if (await r.refresh(), r.meta.error) throw r.meta.error;
+		return t(r);
+	} finally {
+		r.dispose();
+	}
+}
+async function r(n) {
+	let r = e({
+		...n,
+		autoFetch: !1
+	});
+	if (await r.refresh(), r.meta.error) throw r.dispose(), r.meta.error;
+	return {
+		snapshot: t(r),
+		source: r
+	};
+}
+//#endregion
+export { n as prefetchSource, r as prefetchSourceAndKeep };
+
+//# sourceMappingURL=prefetch.js.map

package/dist/prefetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefetch.js","names":[],"sources":["../src/prefetch.ts"],"sourcesContent":["import type { RemoteConfig, RemoteSource, SourceSnapshot } from './types';\n\nimport { createRemoteSource } from './remoteSource';\n\ntype PrefetchConfig<T, TFilter, TSort> = Omit<RemoteConfig<T, TFilter, TSort>, 'autoFetch' | 'refreshInterval'>;\n\nconst buildSnapshot = <T, TFilter, TSort>(source: RemoteSource<T, TFilter, TSort>): SourceSnapshot<T> => {\n  const q = source.query;\n\n  return {\n    items: source.current,\n    ...(q.search && { search: q.search }),\n    page: source.meta.pageNumber,\n    total: source.meta.totalItems,\n  };\n};\n\n/**\n * Fetches a single page of data and returns a serialisable `SourceSnapshot`.\n * The underlying source is created, fetched, then immediately disposed.\n * Use for SSR / static-generation where you only need the data, not a live source.\n *\n * @example\n * ```ts\n * const snapshot = await prefetchSource({ fetch: fetchUsers, limit: 20 });\n * ```\n */\nexport async function prefetchSource<T, TFilter = unknown, TSort = unknown>(\n  cfg: PrefetchConfig<T, TFilter, TSort>,\n): Promise<SourceSnapshot<T>> {\n  const source = createRemoteSource<T, TFilter, TSort>({ ...cfg, autoFetch: false });\n\n  try {\n    await source.refresh();\n\n    if (source.meta.error) throw source.meta.error;\n\n    return buildSnapshot(source);\n  } finally {\n    source.dispose();\n  }\n}\n\n/**\n * Fetches a single page of data and returns both a serialisable `SourceSnapshot` and the\n * still-live `RemoteSource`. Useful when you need the snapshot for SSR serialisation\n * **and** the live source for subsequent client-side updates without a double-fetch.\n *\n * **The caller is responsible for disposing the returned source.**\n *\n * @example\n * ```ts\n * const { snapshot, source } = await prefetchSourceAndKeep({ fetch: fetchUsers, limit: 20 });\n * // hydrate HTML with snapshot, pass source to client\n * ```\n */\nexport async function prefetchSourceAndKeep<T, TFilter = unknown, TSort = unknown>(\n  cfg: PrefetchConfig<T, TFilter, TSort>,\n): Promise<{ snapshot: SourceSnapshot<T>; source: RemoteSource<T, TFilter, TSort> }> {\n  const source = createRemoteSource<T, TFilter, TSort>({ ...cfg, autoFetch: false });\n\n  await source.refresh();\n\n  if (source.meta.error) {\n    source.dispose();\n    throw source.meta.error;\n  }\n\n  return { snapshot: buildSnapshot(source), source };\n}\n"],"mappings":";;AAMA,IAAM,KAAoC,MAA+D;CACvG,IAAM,IAAI,EAAO;CAEjB,OAAO;EACL,OAAO,EAAO;EACd,GAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO;EACnC,MAAM,EAAO,KAAK;EAClB,OAAO,EAAO,KAAK;CACrB;AACF;AAYA,eAAsB,EACpB,GAC4B;CAC5B,IAAM,IAAS,EAAsC;EAAE,GAAG;EAAK,WAAW;CAAM,CAAC;CAEjF,IAAI;EAGF,IAFA,MAAM,EAAO,QAAQ,GAEjB,EAAO,KAAK,OAAO,MAAM,EAAO,KAAK;EAEzC,OAAO,EAAc,CAAM;CAC7B,UAAU;EACR,EAAO,QAAQ;CACjB;AACF;AAeA,eAAsB,EACpB,GACmF;CACnF,IAAM,IAAS,EAAsC;EAAE,GAAG;EAAK,WAAW;CAAM,CAAC;CAIjF,IAFA,MAAM,EAAO,QAAQ,GAEjB,EAAO,KAAK,OAEd,MADA,EAAO,QAAQ,GACT,EAAO,KAAK;CAGpB,OAAO;EAAE,UAAU,EAAc,CAAM;EAAG;CAAO;AACnD"}

package/dist/presets.cjs

@@ -0,0 +1,2 @@
+var e=(e,t,n=!1)=>{let r=n?t:t.toLowerCase();return t=>{let i=e(t)??``;return(n?i:i.toLowerCase()).includes(r)}},t=(e,t)=>n=>Object.is(e(n),t),n=(e,t)=>{let n=e=>e instanceof Date?e.getTime():e,r=t.min===void 0?void 0:n(t.min),i=t.max===void 0?void 0:n(t.max);return t=>{let a=n(e(t));return!(r!==void 0&&a<r||i!==void 0&&a>i)}},r=(e,t=`asc`)=>{let n=t===`asc`?1:-1;return(t,r)=>{let i=e(t),a=e(r);return i instanceof Date&&a instanceof Date?(i.getTime()-a.getTime())*n:i<a?-1*n:i>a?1*n:0}};exports.filterContains=e,exports.filterEquals=t,exports.filterRange=n,exports.sortBy=r;
+//# sourceMappingURL=presets.cjs.map

package/dist/presets.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.cjs","names":[],"sources":["../src/presets.ts"],"sourcesContent":["import type { Predicate, Sorter } from './types';\n\ntype Direction = 'asc' | 'desc';\n\ntype PrimitiveComparable = number | string | Date;\n\nexport const filterContains = <T>(\n  getValue: (item: T) => string | null | undefined,\n  query: string,\n  caseSensitive = false,\n): Predicate<T> => {\n  const needle = caseSensitive ? query : query.toLowerCase();\n\n  return (item) => {\n    const value = getValue(item) ?? '';\n    const haystack = caseSensitive ? value : value.toLowerCase();\n\n    return haystack.includes(needle);\n  };\n};\n\nexport const filterEquals = <T, V>(getValue: (item: T) => V, expected: V): Predicate<T> => {\n  return (item) => Object.is(getValue(item), expected);\n};\n\nexport const filterRange = <T>(\n  getValue: (item: T) => Date | number,\n  bounds: Readonly<{ max?: Date | number; min?: Date | number }>,\n): Predicate<T> => {\n  const toNum = (v: Date | number): number => (v instanceof Date ? v.getTime() : v);\n\n  const min = bounds.min !== undefined ? toNum(bounds.min) : undefined;\n  const max = bounds.max !== undefined ? toNum(bounds.max) : undefined;\n\n  return (item) => {\n    const value = toNum(getValue(item));\n\n    if (min !== undefined && value < min) return false;\n\n    if (max !== undefined && value > max) return false;\n\n    return true;\n  };\n};\n\nexport const sortBy = <T, V extends PrimitiveComparable>(\n  getValue: (item: T) => V,\n  direction: Direction = 'asc',\n): Sorter<T> => {\n  const sign = direction === 'asc' ? 1 : -1;\n\n  return (a, b) => {\n    const left = getValue(a);\n    const right = getValue(b);\n\n    if (left instanceof Date && right instanceof Date) {\n      return (left.getTime() - right.getTime()) * sign;\n    }\n\n    if (left < right) return -1 * sign;\n\n    if (left > right) return 1 * sign;\n\n    return 0;\n  };\n};\n"],"mappings":"AAMA,IAAa,GACX,EACA,EACA,EAAgB,KACC,CACjB,IAAM,EAAS,EAAgB,EAAQ,EAAM,YAAY,EAEzD,MAAQ,IAAS,CACf,IAAM,EAAQ,EAAS,CAAI,GAAK,GAGhC,OAFiB,EAAgB,EAAQ,EAAM,YAAY,EAAA,CAE3C,SAAS,CAAM,CACjC,CACF,EAEa,GAAsB,EAA0B,IACnD,GAAS,OAAO,GAAG,EAAS,CAAI,EAAG,CAAQ,EAGxC,GACX,EACA,IACiB,CACjB,IAAM,EAAS,GAA8B,aAAa,KAAO,EAAE,QAAQ,EAAI,EAEzE,EAAM,EAAO,MAAQ,IAAA,GAAgC,IAAA,GAApB,EAAM,EAAO,GAAG,EACjD,EAAM,EAAO,MAAQ,IAAA,GAAgC,IAAA,GAApB,EAAM,EAAO,GAAG,EAEvD,MAAQ,IAAS,CACf,IAAM,EAAQ,EAAM,EAAS,CAAI,CAAC,EAMlC,MAFA,EAFI,IAAQ,IAAA,IAAa,EAAQ,GAE7B,IAAQ,IAAA,IAAa,EAAQ,EAGnC,CACF,EAEa,GACX,EACA,EAAuB,QACT,CACd,IAAM,EAAO,IAAc,MAAQ,EAAI,GAEvC,OAAQ,EAAG,IAAM,CACf,IAAM,EAAO,EAAS,CAAC,EACjB,EAAQ,EAAS,CAAC,EAUxB,OARI,aAAgB,MAAQ,aAAiB,MACnC,EAAK,QAAQ,EAAI,EAAM,QAAQ,GAAK,EAG1C,EAAO,EAAc,GAAK,EAE1B,EAAO,EAAc,EAAI,EAEtB,CACT,CACF"}

package/dist/presets.d.ts

@@ -0,0 +1,12 @@
+import type { Predicate, Sorter } from './types';
+type Direction = 'asc' | 'desc';
+type PrimitiveComparable = number | string | Date;
+export declare const filterContains: <T>(getValue: (item: T) => string | null | undefined, query: string, caseSensitive?: boolean) => Predicate<T>;
+export declare const filterEquals: <T, V>(getValue: (item: T) => V, expected: V) => Predicate<T>;
+export declare const filterRange: <T>(getValue: (item: T) => Date | number, bounds: Readonly<{
+    max?: Date | number;
+    min?: Date | number;
+}>) => Predicate<T>;
+export declare const sortBy: <T, V extends PrimitiveComparable>(getValue: (item: T) => V, direction?: Direction) => Sorter<T>;
+export {};
+//# sourceMappingURL=presets.d.ts.map

package/dist/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../src/presets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEjD,KAAK,SAAS,GAAG,KAAK,GAAG,MAAM,CAAC;AAEhC,KAAK,mBAAmB,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAElD,eAAO,MAAM,cAAc,GAAI,CAAC,EAC9B,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,EAChD,OAAO,MAAM,EACb,uBAAqB,KACpB,SAAS,CAAC,CAAC,CASb,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,KAAG,SAAS,CAAC,CAAC,CAErF,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,CAAC,EAC3B,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,EACpC,QAAQ,QAAQ,CAAC;IAAE,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAA;CAAE,CAAC,KAC7D,SAAS,CAAC,CAAC,CAeb,CAAC;AAEF,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,CAAC,SAAS,mBAAmB,EACrD,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,EACxB,YAAW,SAAiB,KAC3B,MAAM,CAAC,CAAC,CAiBV,CAAC"}

package/dist/presets.js

@@ -0,0 +1,24 @@
+//#region src/presets.ts
+var e = (e, t, n = !1) => {
+	let r = n ? t : t.toLowerCase();
+	return (t) => {
+		let i = e(t) ?? "";
+		return (n ? i : i.toLowerCase()).includes(r);
+	};
+}, t = (e, t) => (n) => Object.is(e(n), t), n = (e, t) => {
+	let n = (e) => e instanceof Date ? e.getTime() : e, r = t.min === void 0 ? void 0 : n(t.min), i = t.max === void 0 ? void 0 : n(t.max);
+	return (t) => {
+		let a = n(e(t));
+		return !(r !== void 0 && a < r || i !== void 0 && a > i);
+	};
+}, r = (e, t = "asc") => {
+	let n = t === "asc" ? 1 : -1;
+	return (t, r) => {
+		let i = e(t), a = e(r);
+		return i instanceof Date && a instanceof Date ? (i.getTime() - a.getTime()) * n : i < a ? -1 * n : i > a ? 1 * n : 0;
+	};
+};
+//#endregion
+export { e as filterContains, t as filterEquals, n as filterRange, r as sortBy };
+
+//# sourceMappingURL=presets.js.map

package/dist/presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.js","names":[],"sources":["../src/presets.ts"],"sourcesContent":["import type { Predicate, Sorter } from './types';\n\ntype Direction = 'asc' | 'desc';\n\ntype PrimitiveComparable = number | string | Date;\n\nexport const filterContains = <T>(\n  getValue: (item: T) => string | null | undefined,\n  query: string,\n  caseSensitive = false,\n): Predicate<T> => {\n  const needle = caseSensitive ? query : query.toLowerCase();\n\n  return (item) => {\n    const value = getValue(item) ?? '';\n    const haystack = caseSensitive ? value : value.toLowerCase();\n\n    return haystack.includes(needle);\n  };\n};\n\nexport const filterEquals = <T, V>(getValue: (item: T) => V, expected: V): Predicate<T> => {\n  return (item) => Object.is(getValue(item), expected);\n};\n\nexport const filterRange = <T>(\n  getValue: (item: T) => Date | number,\n  bounds: Readonly<{ max?: Date | number; min?: Date | number }>,\n): Predicate<T> => {\n  const toNum = (v: Date | number): number => (v instanceof Date ? v.getTime() : v);\n\n  const min = bounds.min !== undefined ? toNum(bounds.min) : undefined;\n  const max = bounds.max !== undefined ? toNum(bounds.max) : undefined;\n\n  return (item) => {\n    const value = toNum(getValue(item));\n\n    if (min !== undefined && value < min) return false;\n\n    if (max !== undefined && value > max) return false;\n\n    return true;\n  };\n};\n\nexport const sortBy = <T, V extends PrimitiveComparable>(\n  getValue: (item: T) => V,\n  direction: Direction = 'asc',\n): Sorter<T> => {\n  const sign = direction === 'asc' ? 1 : -1;\n\n  return (a, b) => {\n    const left = getValue(a);\n    const right = getValue(b);\n\n    if (left instanceof Date && right instanceof Date) {\n      return (left.getTime() - right.getTime()) * sign;\n    }\n\n    if (left < right) return -1 * sign;\n\n    if (left > right) return 1 * sign;\n\n    return 0;\n  };\n};\n"],"mappings":";AAMA,IAAa,KACX,GACA,GACA,IAAgB,OACC;CACjB,IAAM,IAAS,IAAgB,IAAQ,EAAM,YAAY;CAEzD,QAAQ,MAAS;EACf,IAAM,IAAQ,EAAS,CAAI,KAAK;EAGhC,QAFiB,IAAgB,IAAQ,EAAM,YAAY,EAAA,CAE3C,SAAS,CAAM;CACjC;AACF,GAEa,KAAsB,GAA0B,OACnD,MAAS,OAAO,GAAG,EAAS,CAAI,GAAG,CAAQ,GAGxC,KACX,GACA,MACiB;CACjB,IAAM,KAAS,MAA8B,aAAa,OAAO,EAAE,QAAQ,IAAI,GAEzE,IAAM,EAAO,QAAQ,KAAA,IAAgC,KAAA,IAApB,EAAM,EAAO,GAAG,GACjD,IAAM,EAAO,QAAQ,KAAA,IAAgC,KAAA,IAApB,EAAM,EAAO,GAAG;CAEvD,QAAQ,MAAS;EACf,IAAM,IAAQ,EAAM,EAAS,CAAI,CAAC;EAMlC,OAFA,EAFI,MAAQ,KAAA,KAAa,IAAQ,KAE7B,MAAQ,KAAA,KAAa,IAAQ;CAGnC;AACF,GAEa,KACX,GACA,IAAuB,UACT;CACd,IAAM,IAAO,MAAc,QAAQ,IAAI;CAEvC,QAAQ,GAAG,MAAM;EACf,IAAM,IAAO,EAAS,CAAC,GACjB,IAAQ,EAAS,CAAC;EAUxB,OARI,aAAgB,QAAQ,aAAiB,QACnC,EAAK,QAAQ,IAAI,EAAM,QAAQ,KAAK,IAG1C,IAAO,IAAc,KAAK,IAE1B,IAAO,IAAc,IAAI,IAEtB;CACT;AACF"}

package/dist/remoteSource.cjs

@@ -0,0 +1,2 @@
+const e=require("./errors.cjs"),t=require("./_utils.cjs"),n=require("./asyncSource.cjs"),r=require("./pagination.cjs");let i=require("@vielzeug/arsenal");function a(a){let o=a.queryKey??t.defaultKeyOf,s=a.staleTime??0,c=Math.max(1,Math.trunc(a.limit??20)),l=1,u=``,d=a.filter,f=a.sort,p=[],m=0,h=null,g=0,_=``,v=null,y=null;a.snapshot&&(p=a.snapshot.items,m=a.snapshot.total,a.snapshot.page!==void 0&&(l=a.snapshot.page),a.snapshot.search&&(u=a.snapshot.search),g=Date.now());let b=[],x=r.createMeta({error:null,isLoading:!1,isSearchPending:!1,pageNumber:1,pageSize:c,totalItems:0}),S=()=>{let e=r.pageCount(m,c),t=r.clampPage(l,e);b=p,x=r.createMeta({error:h,isLoading:C.pendingCount()>0,isSearchPending:C.core.isScheduled,pageNumber:t,pageSize:c,totalItems:m})},C=n.createAsyncSource(a,o,S),{autoFetch:w,debounceMs:T,retryAttempts:E,retryDelay:D}=C;S();let O=()=>{C.disposed||C.core.notify()},k=e=>{y?.active&&(y.active=!1,y=null),p=e.items,m=e.total,l=r.clampPage(l,r.pageCount(m,c))},A=()=>{v&&=(v.resolve(),null)},j=()=>({...d!==void 0&&{filter:d},...f!==void 0&&{sort:f},...u&&{search:u},limit:c,page:l}),M=n=>{let r=o(n);return s>0&&r===_&&m>0&&Date.now()-g<s?Promise.resolve():(h=null,C.fetch(n,async(n,o,s)=>{let c=Date.now();try{let e=await(0,i.retry)(e=>a.fetch(n,e),{delay:D,signal:o,times:E+1});s()&&(k(e),h=null,_=r,g=Date.now(),a.onFetch?.({durationMs:Date.now()-c,query:n,status:`success`}))}catch(r){if(o.aborted)return;s()&&(y?.active?(y.active=!1,p=y.prevItems,m=y.prevTotal,y=null):(p=[],m=0),h=new e.SourcererError(t.extractError(r),{cause:r,context:{kind:`remote`,limit:n.limit,page:n.page,...n.search&&{search:n.search}}}),a.onFetch?.({durationMs:Date.now()-c,error:h,query:n,status:`error`}))}},()=>{O(),C.pendingCount()===0&&A()}))},N=()=>M(j());return w&&N(),C.startRefreshInterval(()=>void N()),{get current(){return b},get disposalSignal(){return C.disposalSignal},dispose:()=>{A(),C.dispose()},get disposed(){return C.disposed},goTo(e){let t=m>0?r.clampPage(e,r.pageCount(m,c)):Math.max(1,Math.trunc(e));return t===l?Promise.resolve():(l=t,N())},goToLast(){let e=r.pageCount(m,c);return l===e?Promise.resolve():(l=e,N())},get meta(){return x},next(){let e=r.pageCount(m,c);return l>=e?Promise.resolve():(l++,N())},optimisticUpdate(t,n){if(y?.active)throw new e.SourcererError(`An optimistic update is already active. Rollback the previous update before starting another.`);let r=p,i=m;y={active:!0,prevItems:r,prevTotal:i};try{p=t(p)}catch(e){throw y=null,e}return m=n?.total??m,O(),()=>{y?.active&&(y.active=!1,p=r,m=i,y=null,O())}},patch(e){let t=!1;if(e.limit!==void 0){let n=Math.max(1,Math.trunc(e.limit));n!==c&&(c=n,t=!0)}if(`filter`in e&&(d=e.filter,t=!0),`sort`in e&&(f=e.sort,t=!0),`search`in e&&(e.search!==u||C.core.isScheduled)&&(u=e.search??``,t=!0),e.page!==void 0){let n=m>0?r.clampPage(e.page,r.pageCount(m,c)):Math.max(1,Math.trunc(e.page));n!==l&&(l=n,t=!0)}return t?(C.core.cancelTimer(),A(),(e.limit!==void 0||`filter`in e||`sort`in e||`search`in e)&&e.page===void 0&&(l=1),N()):Promise.resolve()},prev(){return l<=1?Promise.resolve():(l--,N())},get query(){return{...d!==void 0&&{filter:d},...f!==void 0&&{sort:f},...u&&{search:u},limit:c,page:l}},ready(e){return C.ready(e)},refresh(){return N()},reset(){return C.core.cancelTimer(),A(),u=``,l=1,d=a.filter,f=a.sort,N()},search(e,t){if(t?.immediate)return e===u&&!C.core.isScheduled?Promise.resolve():(C.core.cancelTimer(),A(),u=e,l=1,N());if(e===u)return Promise.resolve();A(),u=e,l=1;let n,r=new Promise(e=>{n=e});return v={promise:r,resolve:n},C.core.schedule(()=>void N(),T),O(),r},subscribe:e=>C.core.subscribe(e),[Symbol.dispose]:()=>{A(),C.dispose()}}}exports.createRemoteSource=a;
+//# sourceMappingURL=remoteSource.cjs.map

package/dist/remoteSource.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"remoteSource.cjs","names":[],"sources":["../src/remoteSource.ts"],"sourcesContent":["import type { RemoteConfig, RemoteSource, RemoteSourceQuery, SearchOptions } from './types';\n\nimport { defaultKeyOf, extractError, retry } from './_utils';\nimport { createAsyncSource } from './asyncSource';\nimport { SourcererError } from './errors';\nimport { clampPage, createMeta, pageCount } from './pagination';\n\ntype PendingSearch = { promise: Promise<void>; resolve: () => void };\n\n/** Creates a remote page-based source that fetches data from a network endpoint. */\nexport function createRemoteSource<T, TFilter = unknown, TSort = unknown>(\n  cfg: RemoteConfig<T, TFilter, TSort>,\n): RemoteSource<T, TFilter, TSort> {\n  const keyOf = cfg.queryKey ?? defaultKeyOf;\n\n  // ── Config defaults ─────────────────────────────────────────────────────────\n  const staleTimeMs = cfg.staleTime ?? 0;\n\n  // ── Mutable state ───────────────────────────────────────────────────────────\n  let limit = Math.max(1, Math.trunc(cfg.limit ?? 20));\n  let page = 1;\n  let search = '';\n  let filter: TFilter | undefined = cfg.filter;\n  let sort: TSort | undefined = cfg.sort;\n  let items: readonly T[] = [];\n  let total = 0;\n  let error: SourcererError | null = null;\n  let lastFetchTime = 0;\n  let lastFetchKey = '';\n  let pendingSearch: PendingSearch | null = null;\n\n  // Optimistic update state.\n  let optimistic: { active: boolean; prevItems: readonly T[]; prevTotal: number } | null = null;\n\n  // ── Snapshot pre-population ─────────────────────────────────────────────────\n  if (cfg.snapshot) {\n    items = cfg.snapshot.items;\n    total = cfg.snapshot.total;\n\n    if (cfg.snapshot.page !== undefined) page = cfg.snapshot.page;\n\n    if (cfg.snapshot.search) search = cfg.snapshot.search;\n\n    lastFetchTime = Date.now();\n  }\n\n  // ── Cached accessors ────────────────────────────────────────────────────────\n  let cachedCurrent: readonly T[] = [];\n  let cachedMeta = createMeta({\n    error: null,\n    isLoading: false,\n    isSearchPending: false,\n    pageNumber: 1,\n    pageSize: limit,\n    totalItems: 0,\n  });\n\n  const refreshMeta = () => {\n    const pages = pageCount(total, limit);\n    const safePage = clampPage(page, pages);\n\n    // items is already the current page from the server — no local slicing needed.\n    cachedCurrent = items;\n    cachedMeta = createMeta({\n      error,\n      isLoading: base.pendingCount() > 0,\n      isSearchPending: base.core.isScheduled,\n      pageNumber: safePage,\n      pageSize: limit,\n      totalItems: total,\n    });\n  };\n\n  // onBeforeNotify ensures refreshMeta() runs before any subscriber observes the new state,\n  // eliminating the need for a parallel listeners Set.\n  const base = createAsyncSource<RemoteSourceQuery<TFilter, TSort>>(cfg, keyOf, refreshMeta);\n  const { autoFetch, debounceMs, retryAttempts, retryDelay } = base;\n\n  // Initialise cache before first fetch.\n  refreshMeta();\n\n  const notifyListeners = () => {\n    if (base.disposed) return;\n\n    base.core.notify();\n  };\n\n  // ── Assign result ───────────────────────────────────────────────────────────\n  const assign = (result: Readonly<{ items: readonly T[]; total: number }>) => {\n    if (optimistic?.active) {\n      optimistic.active = false;\n      optimistic = null;\n    }\n\n    items = result.items;\n    total = result.total;\n    page = clampPage(page, pageCount(total, limit));\n  };\n\n  const resolvePendingSearch = () => {\n    if (pendingSearch) {\n      pendingSearch.resolve();\n      pendingSearch = null;\n    }\n  };\n\n  // ── Core fetch ──────────────────────────────────────────────────────────────\n  const toRemoteQuery = (): RemoteSourceQuery<TFilter, TSort> => ({\n    ...(filter !== undefined && { filter }),\n    ...(sort !== undefined && { sort }),\n    ...(search && { search }),\n    limit,\n    page,\n  });\n\n  const fetchQuery = (q: RemoteSourceQuery<TFilter, TSort>): Promise<void> => {\n    const key = keyOf(q);\n\n    if (staleTimeMs > 0 && key === lastFetchKey && total > 0 && Date.now() - lastFetchTime < staleTimeMs) {\n      return Promise.resolve();\n    }\n\n    error = null;\n\n    return base.fetch(\n      q,\n      async (q: RemoteSourceQuery<TFilter, TSort>, signal, isLatest) => {\n        const startTime = Date.now();\n\n        try {\n          const result = await retry((sig) => cfg.fetch(q, sig!), {\n            delay: retryDelay,\n            signal,\n            times: retryAttempts + 1,\n          });\n\n          if (isLatest()) {\n            assign(result);\n            error = null;\n            lastFetchKey = key;\n            lastFetchTime = Date.now();\n            cfg.onFetch?.({ durationMs: Date.now() - startTime, query: q, status: 'success' });\n          }\n        } catch (reason: unknown) {\n          if (signal.aborted) return;\n\n          if (isLatest()) {\n            if (optimistic?.active) {\n              optimistic.active = false;\n              items = optimistic.prevItems;\n              total = optimistic.prevTotal;\n              optimistic = null;\n            } else {\n              items = [];\n              total = 0;\n            }\n\n            error = new SourcererError(extractError(reason), {\n              cause: reason,\n              context: { kind: 'remote', limit: q.limit, page: q.page, ...(q.search && { search: q.search }) },\n            });\n            cfg.onFetch?.({ durationMs: Date.now() - startTime, error, query: q, status: 'error' });\n          }\n        }\n      },\n      () => {\n        notifyListeners();\n\n        if (base.pendingCount() === 0) resolvePendingSearch();\n      },\n    );\n  };\n\n  const doUpdate = () => fetchQuery(toRemoteQuery());\n\n  // ── Auto-fetch + refresh interval ───────────────────────────────────────────\n  if (autoFetch) void doUpdate();\n\n  base.startRefreshInterval(() => void doUpdate());\n\n  // ── Public API ──────────────────────────────────────────────────────────────\n  return {\n    get current() {\n      return cachedCurrent;\n    },\n\n    get disposalSignal() {\n      return base.disposalSignal;\n    },\n\n    dispose: () => {\n      resolvePendingSearch();\n      base.dispose();\n    },\n\n    get disposed() {\n      return base.disposed;\n    },\n\n    goTo(target) {\n      const clamped = total > 0 ? clampPage(target, pageCount(total, limit)) : Math.max(1, Math.trunc(target));\n\n      if (clamped === page) return Promise.resolve();\n\n      page = clamped;\n\n      return doUpdate();\n    },\n\n    goToLast() {\n      const last = pageCount(total, limit);\n\n      if (page === last) return Promise.resolve();\n\n      page = last;\n\n      return doUpdate();\n    },\n\n    get meta() {\n      return cachedMeta;\n    },\n\n    next() {\n      const pages = pageCount(total, limit);\n\n      if (page >= pages) return Promise.resolve();\n\n      page++;\n\n      return doUpdate();\n    },\n\n    optimisticUpdate(mutator, options) {\n      if (optimistic?.active) {\n        throw new SourcererError(\n          'An optimistic update is already active. Rollback the previous update before starting another.',\n        );\n      }\n\n      const prevItems = items;\n      const prevTotal = total;\n\n      optimistic = { active: true, prevItems, prevTotal };\n\n      try {\n        items = mutator(items);\n      } catch (e: unknown) {\n        optimistic = null;\n        throw e;\n      }\n\n      total = options?.total ?? total;\n      notifyListeners();\n\n      return () => {\n        if (optimistic?.active) {\n          optimistic.active = false;\n          items = prevItems;\n          total = prevTotal;\n          optimistic = null;\n          notifyListeners();\n        }\n      };\n    },\n\n    patch(changes) {\n      let changed = false;\n\n      if (changes.limit !== undefined) {\n        const next = Math.max(1, Math.trunc(changes.limit));\n\n        if (next !== limit) {\n          limit = next;\n          changed = true;\n        }\n      }\n\n      if ('filter' in changes) {\n        filter = changes.filter;\n        changed = true;\n      }\n\n      if ('sort' in changes) {\n        sort = changes.sort;\n        changed = true;\n      }\n\n      // `|| base.core.isScheduled` also catches patching in the same search text as an already-pending\n      // debounced search() call — that still needs flushing, not silently dropping as a no-op.\n      if ('search' in changes && (changes.search !== search || base.core.isScheduled)) {\n        search = changes.search ?? '';\n        changed = true;\n      }\n\n      if (changes.page !== undefined) {\n        const next =\n          total > 0 ? clampPage(changes.page, pageCount(total, limit)) : Math.max(1, Math.trunc(changes.page));\n\n        if (next !== page) {\n          page = next;\n          changed = true;\n        }\n      }\n\n      if (!changed) return Promise.resolve();\n\n      // patch() is documented as a single atomic fetch — cancel any debounced search()\n      // still pending so it doesn't fire a second, redundant fetch afterwards.\n      base.core.cancelTimer();\n      resolvePendingSearch();\n\n      // Reset to page 1 when non-page query fields changed without explicit page\n      if (\n        (changes.limit !== undefined || 'filter' in changes || 'sort' in changes || 'search' in changes) &&\n        changes.page === undefined\n      ) {\n        page = 1;\n      }\n\n      return doUpdate();\n    },\n\n    prev() {\n      if (page <= 1) return Promise.resolve();\n\n      page--;\n\n      return doUpdate();\n    },\n\n    get query() {\n      return {\n        ...(filter !== undefined && { filter }),\n        ...(sort !== undefined && { sort }),\n        ...(search && { search }),\n        limit,\n        page,\n      };\n    },\n\n    ready(timeout) {\n      return base.ready(timeout);\n    },\n\n    refresh() {\n      return doUpdate();\n    },\n\n    reset() {\n      base.core.cancelTimer();\n      resolvePendingSearch();\n      search = '';\n      page = 1;\n      filter = cfg.filter;\n      sort = cfg.sort;\n\n      return doUpdate();\n    },\n\n    search(q, opts?: SearchOptions): Promise<void> {\n      if (opts?.immediate) {\n        // A pending debounced search for this same text still needs flushing —\n        // `q === search` alone doesn't mean the fetch already happened.\n        if (q === search && !base.core.isScheduled) return Promise.resolve();\n\n        base.core.cancelTimer();\n        resolvePendingSearch();\n        search = q;\n        page = 1;\n\n        return doUpdate();\n      }\n\n      if (q === search) return Promise.resolve();\n\n      resolvePendingSearch();\n\n      search = q;\n      page = 1;\n\n      let resolveSearch!: () => void;\n      const promise = new Promise<void>((res) => {\n        resolveSearch = res;\n      });\n\n      pendingSearch = { promise, resolve: resolveSearch };\n\n      base.core.schedule(() => void doUpdate(), debounceMs);\n      notifyListeners();\n\n      return promise;\n    },\n\n    subscribe: (listener) => base.core.subscribe(listener),\n\n    [Symbol.dispose]: () => {\n      resolvePendingSearch();\n      base.dispose();\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/remoteSource.d.ts

@@ -0,0 +1,4 @@
+import type { RemoteConfig, RemoteSource } from './types';
+/** Creates a remote page-based source that fetches data from a network endpoint. */
+export declare function createRemoteSource<T, TFilter = unknown, TSort = unknown>(cfg: RemoteConfig<T, TFilter, TSort>): RemoteSource<T, TFilter, TSort>;
+//# sourceMappingURL=remoteSource.d.ts.map

package/dist/remoteSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remoteSource.d.ts","sourceRoot":"","sources":["../src/remoteSource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAoC,MAAM,SAAS,CAAC;AAS5F,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO,EACtE,GAAG,EAAE,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,GACnC,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,CAqYjC"}

package/dist/remoteSource.js

@@ -0,0 +1,175 @@
+import { SourcererError as e } from "./errors.js";
+import { defaultKeyOf as t, extractError as n, retry as r } from "./_utils.js";
+import { createAsyncSource as i } from "./asyncSource.js";
+import { clampPage as a, createMeta as o, pageCount as s } from "./pagination.js";
+//#region src/remoteSource.ts
+function c(c) {
+	let l = c.queryKey ?? t, u = c.staleTime ?? 0, d = Math.max(1, Math.trunc(c.limit ?? 20)), f = 1, p = "", m = c.filter, h = c.sort, g = [], _ = 0, v = null, y = 0, b = "", x = null, S = null;
+	c.snapshot && (g = c.snapshot.items, _ = c.snapshot.total, c.snapshot.page !== void 0 && (f = c.snapshot.page), c.snapshot.search && (p = c.snapshot.search), y = Date.now());
+	let C = [], w = o({
+		error: null,
+		isLoading: !1,
+		isSearchPending: !1,
+		pageNumber: 1,
+		pageSize: d,
+		totalItems: 0
+	}), T = () => {
+		let e = s(_, d), t = a(f, e);
+		C = g, w = o({
+			error: v,
+			isLoading: E.pendingCount() > 0,
+			isSearchPending: E.core.isScheduled,
+			pageNumber: t,
+			pageSize: d,
+			totalItems: _
+		});
+	}, E = i(c, l, T), { autoFetch: D, debounceMs: O, retryAttempts: k, retryDelay: A } = E;
+	T();
+	let j = () => {
+		E.disposed || E.core.notify();
+	}, M = (e) => {
+		S?.active && (S.active = !1, S = null), g = e.items, _ = e.total, f = a(f, s(_, d));
+	}, N = () => {
+		x &&= (x.resolve(), null);
+	}, P = () => ({
+		...m !== void 0 && { filter: m },
+		...h !== void 0 && { sort: h },
+		...p && { search: p },
+		limit: d,
+		page: f
+	}), F = (t) => {
+		let i = l(t);
+		return u > 0 && i === b && _ > 0 && Date.now() - y < u ? Promise.resolve() : (v = null, E.fetch(t, async (t, a, o) => {
+			let s = Date.now();
+			try {
+				let e = await r((e) => c.fetch(t, e), {
+					delay: A,
+					signal: a,
+					times: k + 1
+				});
+				o() && (M(e), v = null, b = i, y = Date.now(), c.onFetch?.({
+					durationMs: Date.now() - s,
+					query: t,
+					status: "success"
+				}));
+			} catch (r) {
+				if (a.aborted) return;
+				o() && (S?.active ? (S.active = !1, g = S.prevItems, _ = S.prevTotal, S = null) : (g = [], _ = 0), v = new e(n(r), {
+					cause: r,
+					context: {
+						kind: "remote",
+						limit: t.limit,
+						page: t.page,
+						...t.search && { search: t.search }
+					}
+				}), c.onFetch?.({
+					durationMs: Date.now() - s,
+					error: v,
+					query: t,
+					status: "error"
+				}));
+			}
+		}, () => {
+			j(), E.pendingCount() === 0 && N();
+		}));
+	}, I = () => F(P());
+	return D && I(), E.startRefreshInterval(() => void I()), {
+		get current() {
+			return C;
+		},
+		get disposalSignal() {
+			return E.disposalSignal;
+		},
+		dispose: () => {
+			N(), E.dispose();
+		},
+		get disposed() {
+			return E.disposed;
+		},
+		goTo(e) {
+			let t = _ > 0 ? a(e, s(_, d)) : Math.max(1, Math.trunc(e));
+			return t === f ? Promise.resolve() : (f = t, I());
+		},
+		goToLast() {
+			let e = s(_, d);
+			return f === e ? Promise.resolve() : (f = e, I());
+		},
+		get meta() {
+			return w;
+		},
+		next() {
+			let e = s(_, d);
+			return f >= e ? Promise.resolve() : (f++, I());
+		},
+		optimisticUpdate(t, n) {
+			if (S?.active) throw new e("An optimistic update is already active. Rollback the previous update before starting another.");
+			let r = g, i = _;
+			S = {
+				active: !0,
+				prevItems: r,
+				prevTotal: i
+			};
+			try {
+				g = t(g);
+			} catch (e) {
+				throw S = null, e;
+			}
+			return _ = n?.total ?? _, j(), () => {
+				S?.active && (S.active = !1, g = r, _ = i, S = null, j());
+			};
+		},
+		patch(e) {
+			let t = !1;
+			if (e.limit !== void 0) {
+				let n = Math.max(1, Math.trunc(e.limit));
+				n !== d && (d = n, t = !0);
+			}
+			if ("filter" in e && (m = e.filter, t = !0), "sort" in e && (h = e.sort, t = !0), "search" in e && (e.search !== p || E.core.isScheduled) && (p = e.search ?? "", t = !0), e.page !== void 0) {
+				let n = _ > 0 ? a(e.page, s(_, d)) : Math.max(1, Math.trunc(e.page));
+				n !== f && (f = n, t = !0);
+			}
+			return t ? (E.core.cancelTimer(), N(), (e.limit !== void 0 || "filter" in e || "sort" in e || "search" in e) && e.page === void 0 && (f = 1), I()) : Promise.resolve();
+		},
+		prev() {
+			return f <= 1 ? Promise.resolve() : (f--, I());
+		},
+		get query() {
+			return {
+				...m !== void 0 && { filter: m },
+				...h !== void 0 && { sort: h },
+				...p && { search: p },
+				limit: d,
+				page: f
+			};
+		},
+		ready(e) {
+			return E.ready(e);
+		},
+		refresh() {
+			return I();
+		},
+		reset() {
+			return E.core.cancelTimer(), N(), p = "", f = 1, m = c.filter, h = c.sort, I();
+		},
+		search(e, t) {
+			if (t?.immediate) return e === p && !E.core.isScheduled ? Promise.resolve() : (E.core.cancelTimer(), N(), p = e, f = 1, I());
+			if (e === p) return Promise.resolve();
+			N(), p = e, f = 1;
+			let n, r = new Promise((e) => {
+				n = e;
+			});
+			return x = {
+				promise: r,
+				resolve: n
+			}, E.core.schedule(() => void I(), O), j(), r;
+		},
+		subscribe: (e) => E.core.subscribe(e),
+		[Symbol.dispose]: () => {
+			N(), E.dispose();
+		}
+	};
+}
+//#endregion
+export { c as createRemoteSource };
+
+//# sourceMappingURL=remoteSource.js.map

package/dist/remoteSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remoteSource.js","names":[],"sources":["../src/remoteSource.ts"],"sourcesContent":["import type { RemoteConfig, RemoteSource, RemoteSourceQuery, SearchOptions } from './types';\n\nimport { defaultKeyOf, extractError, retry } from './_utils';\nimport { createAsyncSource } from './asyncSource';\nimport { SourcererError } from './errors';\nimport { clampPage, createMeta, pageCount } from './pagination';\n\ntype PendingSearch = { promise: Promise<void>; resolve: () => void };\n\n/** Creates a remote page-based source that fetches data from a network endpoint. */\nexport function createRemoteSource<T, TFilter = unknown, TSort = unknown>(\n  cfg: RemoteConfig<T, TFilter, TSort>,\n): RemoteSource<T, TFilter, TSort> {\n  const keyOf = cfg.queryKey ?? defaultKeyOf;\n\n  // ── Config defaults ─────────────────────────────────────────────────────────\n  const staleTimeMs = cfg.staleTime ?? 0;\n\n  // ── Mutable state ───────────────────────────────────────────────────────────\n  let limit = Math.max(1, Math.trunc(cfg.limit ?? 20));\n  let page = 1;\n  let search = '';\n  let filter: TFilter | undefined = cfg.filter;\n  let sort: TSort | undefined = cfg.sort;\n  let items: readonly T[] = [];\n  let total = 0;\n  let error: SourcererError | null = null;\n  let lastFetchTime = 0;\n  let lastFetchKey = '';\n  let pendingSearch: PendingSearch | null = null;\n\n  // Optimistic update state.\n  let optimistic: { active: boolean; prevItems: readonly T[]; prevTotal: number } | null = null;\n\n  // ── Snapshot pre-population ─────────────────────────────────────────────────\n  if (cfg.snapshot) {\n    items = cfg.snapshot.items;\n    total = cfg.snapshot.total;\n\n    if (cfg.snapshot.page !== undefined) page = cfg.snapshot.page;\n\n    if (cfg.snapshot.search) search = cfg.snapshot.search;\n\n    lastFetchTime = Date.now();\n  }\n\n  // ── Cached accessors ────────────────────────────────────────────────────────\n  let cachedCurrent: readonly T[] = [];\n  let cachedMeta = createMeta({\n    error: null,\n    isLoading: false,\n    isSearchPending: false,\n    pageNumber: 1,\n    pageSize: limit,\n    totalItems: 0,\n  });\n\n  const refreshMeta = () => {\n    const pages = pageCount(total, limit);\n    const safePage = clampPage(page, pages);\n\n    // items is already the current page from the server — no local slicing needed.\n    cachedCurrent = items;\n    cachedMeta = createMeta({\n      error,\n      isLoading: base.pendingCount() > 0,\n      isSearchPending: base.core.isScheduled,\n      pageNumber: safePage,\n      pageSize: limit,\n      totalItems: total,\n    });\n  };\n\n  // onBeforeNotify ensures refreshMeta() runs before any subscriber observes the new state,\n  // eliminating the need for a parallel listeners Set.\n  const base = createAsyncSource<RemoteSourceQuery<TFilter, TSort>>(cfg, keyOf, refreshMeta);\n  const { autoFetch, debounceMs, retryAttempts, retryDelay } = base;\n\n  // Initialise cache before first fetch.\n  refreshMeta();\n\n  const notifyListeners = () => {\n    if (base.disposed) return;\n\n    base.core.notify();\n  };\n\n  // ── Assign result ───────────────────────────────────────────────────────────\n  const assign = (result: Readonly<{ items: readonly T[]; total: number }>) => {\n    if (optimistic?.active) {\n      optimistic.active = false;\n      optimistic = null;\n    }\n\n    items = result.items;\n    total = result.total;\n    page = clampPage(page, pageCount(total, limit));\n  };\n\n  const resolvePendingSearch = () => {\n    if (pendingSearch) {\n      pendingSearch.resolve();\n      pendingSearch = null;\n    }\n  };\n\n  // ── Core fetch ──────────────────────────────────────────────────────────────\n  const toRemoteQuery = (): RemoteSourceQuery<TFilter, TSort> => ({\n    ...(filter !== undefined && { filter }),\n    ...(sort !== undefined && { sort }),\n    ...(search && { search }),\n    limit,\n    page,\n  });\n\n  const fetchQuery = (q: RemoteSourceQuery<TFilter, TSort>): Promise<void> => {\n    const key = keyOf(q);\n\n    if (staleTimeMs > 0 && key === lastFetchKey && total > 0 && Date.now() - lastFetchTime < staleTimeMs) {\n      return Promise.resolve();\n    }\n\n    error = null;\n\n    return base.fetch(\n      q,\n      async (q: RemoteSourceQuery<TFilter, TSort>, signal, isLatest) => {\n        const startTime = Date.now();\n\n        try {\n          const result = await retry((sig) => cfg.fetch(q, sig!), {\n            delay: retryDelay,\n            signal,\n            times: retryAttempts + 1,\n          });\n\n          if (isLatest()) {\n            assign(result);\n            error = null;\n            lastFetchKey = key;\n            lastFetchTime = Date.now();\n            cfg.onFetch?.({ durationMs: Date.now() - startTime, query: q, status: 'success' });\n          }\n        } catch (reason: unknown) {\n          if (signal.aborted) return;\n\n          if (isLatest()) {\n            if (optimistic?.active) {\n              optimistic.active = false;\n              items = optimistic.prevItems;\n              total = optimistic.prevTotal;\n              optimistic = null;\n            } else {\n              items = [];\n              total = 0;\n            }\n\n            error = new SourcererError(extractError(reason), {\n              cause: reason,\n              context: { kind: 'remote', limit: q.limit, page: q.page, ...(q.search && { search: q.search }) },\n            });\n            cfg.onFetch?.({ durationMs: Date.now() - startTime, error, query: q, status: 'error' });\n          }\n        }\n      },\n      () => {\n        notifyListeners();\n\n        if (base.pendingCount() === 0) resolvePendingSearch();\n      },\n    );\n  };\n\n  const doUpdate = () => fetchQuery(toRemoteQuery());\n\n  // ── Auto-fetch + refresh interval ───────────────────────────────────────────\n  if (autoFetch) void doUpdate();\n\n  base.startRefreshInterval(() => void doUpdate());\n\n  // ── Public API ──────────────────────────────────────────────────────────────\n  return {\n    get current() {\n      return cachedCurrent;\n    },\n\n    get disposalSignal() {\n      return base.disposalSignal;\n    },\n\n    dispose: () => {\n      resolvePendingSearch();\n      base.dispose();\n    },\n\n    get disposed() {\n      return base.disposed;\n    },\n\n    goTo(target) {\n      const clamped = total > 0 ? clampPage(target, pageCount(total, limit)) : Math.max(1, Math.trunc(target));\n\n      if (clamped === page) return Promise.resolve();\n\n      page = clamped;\n\n      return doUpdate();\n    },\n\n    goToLast() {\n      const last = pageCount(total, limit);\n\n      if (page === last) return Promise.resolve();\n\n      page = last;\n\n      return doUpdate();\n    },\n\n    get meta() {\n      return cachedMeta;\n    },\n\n    next() {\n      const pages = pageCount(total, limit);\n\n      if (page >= pages) return Promise.resolve();\n\n      page++;\n\n      return doUpdate();\n    },\n\n    optimisticUpdate(mutator, options) {\n      if (optimistic?.active) {\n        throw new SourcererError(\n          'An optimistic update is already active. Rollback the previous update before starting another.',\n        );\n      }\n\n      const prevItems = items;\n      const prevTotal = total;\n\n      optimistic = { active: true, prevItems, prevTotal };\n\n      try {\n        items = mutator(items);\n      } catch (e: unknown) {\n        optimistic = null;\n        throw e;\n      }\n\n      total = options?.total ?? total;\n      notifyListeners();\n\n      return () => {\n        if (optimistic?.active) {\n          optimistic.active = false;\n          items = prevItems;\n          total = prevTotal;\n          optimistic = null;\n          notifyListeners();\n        }\n      };\n    },\n\n    patch(changes) {\n      let changed = false;\n\n      if (changes.limit !== undefined) {\n        const next = Math.max(1, Math.trunc(changes.limit));\n\n        if (next !== limit) {\n          limit = next;\n          changed = true;\n        }\n      }\n\n      if ('filter' in changes) {\n        filter = changes.filter;\n        changed = true;\n      }\n\n      if ('sort' in changes) {\n        sort = changes.sort;\n        changed = true;\n      }\n\n      // `|| base.core.isScheduled` also catches patching in the same search text as an already-pending\n      // debounced search() call — that still needs flushing, not silently dropping as a no-op.\n      if ('search' in changes && (changes.search !== search || base.core.isScheduled)) {\n        search = changes.search ?? '';\n        changed = true;\n      }\n\n      if (changes.page !== undefined) {\n        const next =\n          total > 0 ? clampPage(changes.page, pageCount(total, limit)) : Math.max(1, Math.trunc(changes.page));\n\n        if (next !== page) {\n          page = next;\n          changed = true;\n        }\n      }\n\n      if (!changed) return Promise.resolve();\n\n      // patch() is documented as a single atomic fetch — cancel any debounced search()\n      // still pending so it doesn't fire a second, redundant fetch afterwards.\n      base.core.cancelTimer();\n      resolvePendingSearch();\n\n      // Reset to page 1 when non-page query fields changed without explicit page\n      if (\n        (changes.limit !== undefined || 'filter' in changes || 'sort' in changes || 'search' in changes) &&\n        changes.page === undefined\n      ) {\n        page = 1;\n      }\n\n      return doUpdate();\n    },\n\n    prev() {\n      if (page <= 1) return Promise.resolve();\n\n      page--;\n\n      return doUpdate();\n    },\n\n    get query() {\n      return {\n        ...(filter !== undefined && { filter }),\n        ...(sort !== undefined && { sort }),\n        ...(search && { search }),\n        limit,\n        page,\n      };\n    },\n\n    ready(timeout) {\n      return base.ready(timeout);\n    },\n\n    refresh() {\n      return doUpdate();\n    },\n\n    reset() {\n      base.core.cancelTimer();\n      resolvePendingSearch();\n      search = '';\n      page = 1;\n      filter = cfg.filter;\n      sort = cfg.sort;\n\n      return doUpdate();\n    },\n\n    search(q, opts?: SearchOptions): Promise<void> {\n      if (opts?.immediate) {\n        // A pending debounced search for this same text still needs flushing —\n        // `q === search` alone doesn't mean the fetch already happened.\n        if (q === search && !base.core.isScheduled) return Promise.resolve();\n\n        base.core.cancelTimer();\n        resolvePendingSearch();\n        search = q;\n        page = 1;\n\n        return doUpdate();\n      }\n\n      if (q === search) return Promise.resolve();\n\n      resolvePendingSearch();\n\n      search = q;\n      page = 1;\n\n      let resolveSearch!: () => void;\n      const promise = new Promise<void>((res) => {\n        resolveSearch = res;\n      });\n\n      pendingSearch = { promise, resolve: resolveSearch };\n\n      base.core.schedule(() => void doUpdate(), debounceMs);\n      notifyListeners();\n\n      return promise;\n    },\n\n    subscribe: (listener) => base.core.subscribe(listener),\n\n    [Symbol.dispose]: () => {\n      resolvePendingSearch();\n      base.dispose();\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/sourcerer.cjs

@@ -0,0 +1,2 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@vielzeug/arsenal");function t(e,t){return e.patch(t)}var n=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}},r=class extends n{timeoutMs;constructor(e){super(`Source.ready() timed out after ${e}ms`),this.timeoutMs=e}},i=class extends n{constructor(){super(`Source disposed while waiting for ready()`)}},a=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},o=(e,t={})=>{let r=e instanceof URLSearchParams?Object.fromEntries(e.entries()):e,{defaultLimit:i=20,strict:a=!1}=t,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=(e,t)=>{if(t===void 0)return;let r=Array.isArray(t)?t[0]:t;try{return JSON.parse(r)}catch{if(a)throw new n(`Invalid query param "${e}": ${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)}},s=e.hash,c=e=>e instanceof Error?e.message:typeof e==`string`&&e.length>0?e:`Request failed`,l=t=>(0,e.backoff)(t);function u(e){let t=new Set,n=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 e of n)e.timeoutId!==void 0&&clearTimeout(e.timeoutId),e.reject(new i);n.clear(),t.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(r){if(!s){(r??e?.onBeforeNotify)?.();for(let e of t)e();for(let e of n)e.check()}},ready(e,t){return s?Promise.reject(new i):e()?Promise.resolve():new Promise((i,a)=>{let o={check:()=>{e()&&(o.timeoutId!==void 0&&clearTimeout(o.timeoutId),n.delete(o),i())},reject:a};t!==void 0&&(o.timeoutId=setTimeout(()=>{n.delete(o),a(new r(t))},t)),n.add(o)})},schedule(e,t){s||(o&&clearTimeout(o),o=setTimeout(()=>{o=void 0,e()},t))},subscribe(e){return s?()=>{}:(t.add(e),()=>t.delete(e))}}}function d(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}}}function f(e,t=s,n){let r=u({onBeforeNotify:n}),i=d(t),a=e.debounceMs??300,o=e.retry?.attempts??0,c=e.retry?.delay??l,f=e.autoFetch!==!1,p,m=()=>{r.isDisposed||(p!==void 0&&(clearInterval(p),p=void 0),i.dispose(),r.dispose())};return{autoFetch:f,core:r,debounceMs:a,get disposalSignal(){return r.disposalSignal},dispose:m,get disposed(){return r.isDisposed},fetch(e,t,n){return i.run(e,t,n)},pendingCount:()=>i.pendingCount,ready(e){return r.ready(()=>i.pendingCount===0&&!r.isScheduled,e)},retryAttempts:o,retryDelay:c,startRefreshInterval(t){e.refreshInterval!==void 0&&e.refreshInterval>0&&(p=setInterval(()=>{r.isDisposed||t()},e.refreshInterval))},[Symbol.dispose]:m}}function p(t){let r=t.queryKey??s,i=Math.max(1,Math.trunc(t.limit??20)),a=``,o,l,u,d,p=[],m=0,h=null,g=null,_=[],v={error:null,hasNextPage:!1,hasPrevPage:!1,isLoading:!1,isSearchPending:!1,pageSize:i,totalItems:0},y=()=>{_=p,v={error:h,hasNextPage:u!==void 0,hasPrevPage:d!==void 0,isLoading:b.pendingCount()>0,isSearchPending:b.core.isScheduled,pageSize:i,totalItems:m}},b=f(t,r,y),{autoFetch:x,debounceMs:S,retryAttempts:C,retryDelay:w}=b;y();let T=()=>{b.disposed||b.core.notify()},E=()=>{g&&=(g.resolve(),null)},D=()=>({...o!==void 0&&{after:o},...l!==void 0&&{before:l},...a&&{search:a},limit:i}),O=r=>(h=null,b.fetch(r,async(r,i,a)=>{let o=Date.now();try{let n=await(0,e.retry)(e=>t.fetch(r,e),{delay:w,signal:i,times:C+1});a()&&(p=n.items,m=n.total??n.items.length,u=n.nextCursor,d=n.prevCursor,h=null,t.onFetch?.({durationMs:Date.now()-o,query:r,status:`success`}))}catch(e){if(i.aborted)return;a()&&(p=[],m=0,u=void 0,d=void 0,h=new n(c(e),{cause:e,context:{kind:`cursor`,limit:r.limit,...r.search&&{search:r.search}}}),t.onFetch?.({durationMs:Date.now()-o,error:h,query:r,status:`error`}))}},()=>{T(),b.pendingCount()===0&&E()})),k=()=>O(D());return x&&k(),b.startRefreshInterval(()=>void k()),{get current(){return _},get disposalSignal(){return b.disposalSignal},dispose:()=>{E(),b.dispose()},get disposed(){return b.disposed},get meta(){return v},next(){return u?(o=u,l=void 0,k()):Promise.resolve()},patch(e){let t=!1;if(e.limit!==void 0){let n=Math.max(1,Math.trunc(e.limit));n!==i&&(i=n,o=void 0,l=void 0,t=!0)}return`search`in e&&(e.search!==a||b.core.isScheduled)&&(a=e.search??``,o=void 0,l=void 0,t=!0),t?(b.core.cancelTimer(),E(),k()):Promise.resolve()},prev(){return d?(l=d,o=void 0,k()):Promise.resolve()},get query(){return{...o!==void 0&&{after:o},...l!==void 0&&{before:l},...a&&{search:a},limit:i}},ready(e){return b.ready(e)},refresh(){return k()},reset(){return b.core.cancelTimer(),E(),a=``,o=void 0,l=void 0,k()},search(e,t){if(t?.immediate)return e===a&&!b.core.isScheduled?Promise.resolve():(b.core.cancelTimer(),E(),a=e,o=void 0,l=void 0,k());if(e===a)return Promise.resolve();E(),a=e,o=void 0,l=void 0;let n,r=new Promise(e=>{n=e});return g={promise:r,resolve:n},b.core.schedule(()=>void k(),S),T(),r},subscribe:e=>b.core.subscribe(e),[Symbol.dispose]:()=>{E(),b.dispose()}}}function m(e,t){let n=u(),r=[],i=()=>{r=t(e.current)};i();let a=e.subscribe(()=>{i(),n.notify()});`disposalSignal`in e&&e.disposalSignal instanceof AbortSignal&&e.disposalSignal.addEventListener(`abort`,()=>n.dispose(),{once:!0});let o={get current(){return r},get disposalSignal(){return n.disposalSignal},dispose(){n.isDisposed||(a(),n.dispose())},get disposed(){return n.isDisposed},get meta(){return e.meta},subscribe(e){return n.subscribe(e)},[Symbol.dispose](){o.dispose()}};return o}function h(t){let r=t.queryKey??s,i=Math.max(1,Math.trunc(t.limit??20)),a=``,o=1,l=0,u=[],d=0,p=null,m=!1,h=null,g=[],_={error:null,hasMore:!1,isLoading:!1,isLoadingMore:!1,isSearchPending:!1,loadedPages:0,pageSize:i,totalItems:0},v=()=>{g=u,_={error:p,hasMore:u.length<d,isLoading:y.pendingCount()>0&&!m,isLoadingMore:m,isSearchPending:y.core.isScheduled,loadedPages:l,pageSize:i,totalItems:d}},y=f(t,r,v),{autoFetch:b,debounceMs:x,retryAttempts:S,retryDelay:C}=y;v();let w=()=>{y.disposed||y.core.notify()},T=()=>{h&&=(h.resolve(),null)},E=(r,s)=>{let f={...a&&{search:a},limit:i,page:r};return p=null,y.fetch(f,async(i,a,f)=>{let h=Date.now();try{let n=await(0,e.retry)(e=>t.fetch(i,e),{delay:C,signal:a,times:S+1});f()&&(u=s?[...u,...n.items]:n.items,d=n.total,o=r,l=s?l+1:1,p=null,t.onFetch?.({durationMs:Date.now()-h,query:i,status:`success`}))}catch(e){if(a.aborted)return;f()&&(s||(u=[]),d=s?d:0,p=new n(c(e),{cause:e,context:{kind:`infinite`,limit:i.limit,page:i.page,...i.search&&{search:i.search}}}),t.onFetch?.({durationMs:Date.now()-h,error:p,query:i,status:`error`}))}finally{m=!1}},()=>{w(),y.pendingCount()===0&&T()})},D=()=>E(1,!1);return b&&D(),y.startRefreshInterval(()=>void D()),{get current(){return g},get disposalSignal(){return y.disposalSignal},dispose:()=>{T(),y.dispose()},get disposed(){return y.disposed},loadMore(){return!_.hasMore||y.pendingCount()>0||m?Promise.resolve():(m=!0,v(),E(o+1,!0))},get meta(){return _},patch(e){let t=!1;if(e.limit!==void 0){let n=Math.max(1,Math.trunc(e.limit));n!==i&&(i=n,t=!0)}return`search`in e&&(e.search!==a||y.core.isScheduled)&&(a=e.search??``,t=!0),t?(y.core.cancelTimer(),T(),u=[],d=0,o=1,l=0,D()):Promise.resolve()},get query(){return{...a&&{search:a},limit:i,page:o}},ready(e){return y.ready(e)},reset(){return y.core.cancelTimer(),T(),o=1,l=0,u=[],d=0,a=``,D()},search(e,t){if(t?.immediate)return e===a&&!y.core.isScheduled?Promise.resolve():(y.core.cancelTimer(),T(),a=e,u=[],d=0,l=0,o=1,D());if(e===a)return Promise.resolve();T(),a=e,u=[],d=0,l=0,o=1;let n,r=new Promise(e=>{n=e});return h={promise:r,resolve:n},y.core.schedule(()=>void D(),x),w(),r},subscribe:e=>y.core.subscribe(e),[Symbol.dispose]:()=>{T(),y.dispose()}}}var g=(e,t)=>{let n=Math.trunc(e);return Number.isFinite(n)?Math.max(t,n):t},_=(e,t)=>{let n=g(e,0),r=g(t,1);return Math.max(1,Math.ceil(n/r))},v=(e,t)=>Math.max(1,Math.min(g(e,1),Math.max(1,t))),y=e=>{let t=g(e.pageSize,1),n=g(e.totalItems,0),r=_(n,t),i=v(e.pageNumber,r);return{error:e.error,isLoading:e.isLoading,isSearchPending:e.isSearchPending,pageCount:r,pageNumber:i,pageSize:t,totalItems:n}};function b(e){if(e.totalItems===0)return{end:0,start:0};let t=(e.pageNumber-1)*e.pageSize+1;return{end:Math.min(e.pageNumber*e.pageSize,e.totalItems),start:t}}var x=20,S=300;function C(e,t){let n=t.toLowerCase();return e.filter(e=>JSON.stringify(e).toLowerCase().includes(n))}function w(e,t={}){let r=u(),i=t.filterAsync!==void 0||t.sortAsync!==void 0,a=t.debounceMs??S,o=t.initialData??e,s=``,l=t.filter,d=t.sort,f=t.limit??x,p=1,m=[],h=!1,g=!1,b=null,w=null,T=null,E=()=>r.notify(),D=()=>{T&&=(T.resolve(),null)},O=()=>{let e=o;return s&&(e=(t.searchFn??C)(e,s)),l&&(e=e.filter(l)),d&&(e=[...e].sort(d)),e},k=()=>{m=O();let e=_(m.length,f);p=v(p,e)},A=async()=>{w?.abort();let e=new AbortController;w=e,h=!0,b=null,E();try{let n=o;if(s&&(n=(t.searchFn??C)(n,s)),l&&(n=n.filter(l)),t.filterAsync&&!e.signal.aborted&&(n=await t.filterAsync(n,e.signal)),d&&(n=[...n].sort(d)),t.sortAsync&&!e.signal.aborted&&(n=await t.sortAsync(n,e.signal)),e.signal.aborted)return;m=n,h=!1,g=!1;let r=_(m.length,f);p=v(p,r)}catch(t){e.signal.aborted||(h=!1,g=!1,b=new n(c(t),{cause:t}))}finally{w===e&&(w=null)}E(),D()},j=()=>i?A():(g=!1,k(),E(),D(),Promise.resolve());i?(m=O(),A()):k();let M={get current(){let e=(p-1)*f;return m.slice(e,e+f)},get disposalSignal(){return r.disposalSignal},dispose(){r.isDisposed||(r.cancelTimer(),w?.abort(),w=null,D(),r.dispose())},get disposed(){return r.isDisposed},goTo(e){let t=v(e,_(m.length,f));return t===p?Promise.resolve():(p=t,E(),Promise.resolve())},goToLast(){return M.goTo(_(m.length,f))},get meta(){return y({error:b,isLoading:h,isSearchPending:g,pageNumber:p,pageSize:f,totalItems:m.length})},next(){return M.goTo(p+1)},patch(e){let t=!1;if(e.limit!==void 0){let n=Math.max(1,Math.trunc(e.limit));n!==f&&(f=n,t=!0)}if(`filter`in e&&(l=e.filter,t=!0),`sort`in e&&(d=e.sort,t=!0),`search`in e&&(e.search!==s||r.isScheduled)&&(s=e.search??``,t=!0),e.page!==void 0){let n=v(e.page,_(m.length,f));n!==p&&(p=n,t=!0)}return t?(r.cancelTimer(),D(),(e.limit!==void 0||`filter`in e||`sort`in e||`search`in e)&&e.page===void 0&&(p=1),j()):Promise.resolve()},prev(){return M.goTo(p-1)},get query(){return{limit:f,page:p,...s&&{search:s}}},ready(e){return r.ready(()=>!h&&!r.isScheduled,e)},reset(){return r.cancelTimer(),g=!1,s=``,l=t.filter,d=t.sort,p=1,D(),j()},search(e,t){if(t?.immediate)return e===s&&!r.isScheduled?Promise.resolve():(r.cancelTimer(),g=!1,s=e,p=1,D(),j());if(e===s)return Promise.resolve();D(),s=e,p=1,g=!0,E();let n,i=new Promise(e=>{n=e});return T={promise:i,resolve:n},r.schedule(()=>{g=!1,j()},a),i},setData(e){return o=e,p=1,j()},subscribe(e){return r.subscribe(e)},[Symbol.dispose](){M.dispose()}};return M}function T(e,t){let n=u(),r=t(e.map(e=>e.current)),i=e.map(i=>i.subscribe(()=>{r=t(e.map(e=>e.current)),n.notify()})),a={get current(){return r},get disposalSignal(){return n.disposalSignal},dispose(){if(!n.isDisposed){for(let e of i)e();n.dispose()}},get disposed(){return n.isDisposed},subscribe(e){return n.subscribe(e)},[Symbol.dispose](){a.dispose()}};return a}function E(t){let r=t.queryKey??s,i=t.staleTime??0,a=Math.max(1,Math.trunc(t.limit??20)),o=1,l=``,u=t.filter,d=t.sort,p=[],m=0,h=null,g=0,b=``,x=null,S=null;t.snapshot&&(p=t.snapshot.items,m=t.snapshot.total,t.snapshot.page!==void 0&&(o=t.snapshot.page),t.snapshot.search&&(l=t.snapshot.search),g=Date.now());let C=[],w=y({error:null,isLoading:!1,isSearchPending:!1,pageNumber:1,pageSize:a,totalItems:0}),T=()=>{let e=_(m,a),t=v(o,e);C=p,w=y({error:h,isLoading:E.pendingCount()>0,isSearchPending:E.core.isScheduled,pageNumber:t,pageSize:a,totalItems:m})},E=f(t,r,T),{autoFetch:D,debounceMs:O,retryAttempts:k,retryDelay:A}=E;T();let j=()=>{E.disposed||E.core.notify()},M=e=>{S?.active&&(S.active=!1,S=null),p=e.items,m=e.total,o=v(o,_(m,a))},N=()=>{x&&=(x.resolve(),null)},P=()=>({...u!==void 0&&{filter:u},...d!==void 0&&{sort:d},...l&&{search:l},limit:a,page:o}),F=a=>{let o=r(a);return i>0&&o===b&&m>0&&Date.now()-g<i?Promise.resolve():(h=null,E.fetch(a,async(r,i,a)=>{let s=Date.now();try{let n=await(0,e.retry)(e=>t.fetch(r,e),{delay:A,signal:i,times:k+1});a()&&(M(n),h=null,b=o,g=Date.now(),t.onFetch?.({durationMs:Date.now()-s,query:r,status:`success`}))}catch(e){if(i.aborted)return;a()&&(S?.active?(S.active=!1,p=S.prevItems,m=S.prevTotal,S=null):(p=[],m=0),h=new n(c(e),{cause:e,context:{kind:`remote`,limit:r.limit,page:r.page,...r.search&&{search:r.search}}}),t.onFetch?.({durationMs:Date.now()-s,error:h,query:r,status:`error`}))}},()=>{j(),E.pendingCount()===0&&N()}))},I=()=>F(P());return D&&I(),E.startRefreshInterval(()=>void I()),{get current(){return C},get disposalSignal(){return E.disposalSignal},dispose:()=>{N(),E.dispose()},get disposed(){return E.disposed},goTo(e){let t=m>0?v(e,_(m,a)):Math.max(1,Math.trunc(e));return t===o?Promise.resolve():(o=t,I())},goToLast(){let e=_(m,a);return o===e?Promise.resolve():(o=e,I())},get meta(){return w},next(){let e=_(m,a);return o>=e?Promise.resolve():(o++,I())},optimisticUpdate(e,t){if(S?.active)throw new n(`An optimistic update is already active. Rollback the previous update before starting another.`);let r=p,i=m;S={active:!0,prevItems:r,prevTotal:i};try{p=e(p)}catch(e){throw S=null,e}return m=t?.total??m,j(),()=>{S?.active&&(S.active=!1,p=r,m=i,S=null,j())}},patch(e){let t=!1;if(e.limit!==void 0){let n=Math.max(1,Math.trunc(e.limit));n!==a&&(a=n,t=!0)}if(`filter`in e&&(u=e.filter,t=!0),`sort`in e&&(d=e.sort,t=!0),`search`in e&&(e.search!==l||E.core.isScheduled)&&(l=e.search??``,t=!0),e.page!==void 0){let n=m>0?v(e.page,_(m,a)):Math.max(1,Math.trunc(e.page));n!==o&&(o=n,t=!0)}return t?(E.core.cancelTimer(),N(),(e.limit!==void 0||`filter`in e||`sort`in e||`search`in e)&&e.page===void 0&&(o=1),I()):Promise.resolve()},prev(){return o<=1?Promise.resolve():(o--,I())},get query(){return{...u!==void 0&&{filter:u},...d!==void 0&&{sort:d},...l&&{search:l},limit:a,page:o}},ready(e){return E.ready(e)},refresh(){return I()},reset(){return E.core.cancelTimer(),N(),l=``,o=1,u=t.filter,d=t.sort,I()},search(e,t){if(t?.immediate)return e===l&&!E.core.isScheduled?Promise.resolve():(E.core.cancelTimer(),N(),l=e,o=1,I());if(e===l)return Promise.resolve();N(),l=e,o=1;let n,r=new Promise(e=>{n=e});return x={promise:r,resolve:n},E.core.schedule(()=>void I(),O),j(),r},subscribe:e=>E.core.subscribe(e),[Symbol.dispose]:()=>{N(),E.dispose()}}}var D=e=>{let t=e.query;return{items:e.current,...t.search&&{search:t.search},page:e.meta.pageNumber,total:e.meta.totalItems}};async function O(e){let t=E({...e,autoFetch:!1});try{if(await t.refresh(),t.meta.error)throw t.meta.error;return D(t)}finally{t.dispose()}}async function k(e){let t=E({...e,autoFetch:!1});if(await t.refresh(),t.meta.error)throw t.dispose(),t.meta.error;return{snapshot:D(t),source:t}}var A=(e,t,n=!1)=>{let r=n?t:t.toLowerCase();return t=>{let i=e(t)??``;return(n?i:i.toLowerCase()).includes(r)}},j=(e,t)=>n=>Object.is(e(n),t),M=(e,t)=>{let n=e=>e instanceof Date?e.getTime():e,r=t.min===void 0?void 0:n(t.min),i=t.max===void 0?void 0:n(t.max);return t=>{let a=n(e(t));return!(r!==void 0&&a<r||i!==void 0&&a>i)}},N=(e,t=`asc`)=>{let n=t===`asc`?1:-1;return(t,r)=>{let i=e(t),a=e(r);return i instanceof Date&&a instanceof Date?(i.getTime()-a.getTime())*n:i<a?-1*n:i>a?1*n:0}};function P(e){return e.meta.isLoading||e.meta.isSearchPending?{status:`loading`}:e.meta.error?{error:e.meta.error,status:`error`}:{items:e.current,status:`success`}}exports.SourceDisposedError=i,exports.SourceTimeoutError=r,exports.SourcererError=n,exports.applyQuery=t,exports.createCursorSource=p,exports.createInfiniteSource=h,exports.createLocalSource=w,exports.createRemoteSource=E,exports.decodeQuery=o,exports.deriveSource=m,exports.encodeQuery=a,exports.filterContains=A,exports.filterEquals=j,exports.filterRange=M,exports.itemRange=b,exports.mergeSource=T,exports.prefetchSource=O,exports.prefetchSourceAndKeep=k,exports.sortBy=N,exports.sourceState=P;
+//# sourceMappingURL=sourcerer.cjs.map