@chelone/core 0.5.0 → 0.7.0

package/dist/data/cache-ops.js

@@ -1,212 +1,230 @@
-import { oneKey, infiniteListKeyPrefix, manyKeyPrefix } from "./keys.js";
+import { infiniteListKeyPrefix, manyKeyPrefix, oneKey } from "./keys.js";
+// src/data/cache-ops.ts
+/**
+* Vanilla (react/vue-free) query-cache mutations shared by the undoable
+* orchestration in BOTH adapters. They are the `applyOptimistic` bodies passed
+* to {@link startUndoableMutation}: an optimistic delete removes rows now, an
+* optimistic update patches them now, and the deferred dataProvider call is
+* withheld until commit. Rollback is handled by the undoable snapshot (these
+* never mutate an existing cache object in place — every write is a fresh
+* object — so the pre-apply snapshot stays a valid rollback target).
+*/
+/** Partial-match keys of the caches holding one `GetListResult` per query (not one per page). */
 function singleResultListKeyPrefixes(resource) {
-  return [
-    [resource, "getList"],
-    [resource, "getManyReference"]
-  ];
+	return [[resource, "getList"], [resource, "getManyReference"]];
 }
+function singleResultEntries(queryClient, queryKey) {
+	return queryClient.getQueriesData({ queryKey });
+}
+function infiniteEntries(queryClient, resource) {
+	return queryClient.getQueriesData({ queryKey: infiniteListKeyPrefix(resource) });
+}
+/** Filters ids out of a page; `undefined` when it holds none, so the cached object is kept. */
 function withoutIds(page, idSet) {
-  const kept = page.data.filter(
-    (record) => !idSet.has(String(record.id))
-  );
-  return kept.length === page.data.length ? void 0 : { ...page, data: kept };
+	const kept = page.data.filter((record) => !idSet.has(String(record.id)));
+	return kept.length === page.data.length ? void 0 : {
+		...page,
+		data: kept
+	};
 }
+/** Shallow-merges `data` into the matching rows; `undefined` when none match. */
 function withPatchedRows(page, idSet, data) {
-  let changed = false;
-  const nextData = page.data.map((record) => {
-    if (idSet.has(String(record.id))) {
-      changed = true;
-      return { ...record, ...data };
-    }
-    return record;
-  });
-  return changed ? { ...page, data: nextData } : void 0;
+	let changed = false;
+	const nextData = page.data.map((record) => {
+		if (idSet.has(String(record.id))) {
+			changed = true;
+			return {
+				...record,
+				...data
+			};
+		}
+		return record;
+	});
+	return changed ? {
+		...page,
+		data: nextData
+	} : void 0;
 }
+/** `total` after `removed` rows left; stays at 0 if a stale total is lower than the rows removed. */
 function lowerTotal(total, removed) {
-  return total == null ? total : Math.max(0, total - removed);
+	return total == null ? total : Math.max(0, total - removed);
 }
+/**
+* Optimistically remove records: drop each `getOne` entry and filter the id(s)
+* out of every cached `getList`, `getManyReference` and `getInfiniteList` page
+* (decrementing `total` when known) and `getMany` entry.
+*/
 function removeRecordsFromCache(queryClient, resource, ids) {
-  const idSet = new Set(ids.map(String));
-  for (const id of ids) {
-    queryClient.removeQueries({ queryKey: oneKey(resource, { id }) });
-  }
-  for (const queryKey of singleResultListKeyPrefixes(resource)) {
-    for (const [key, value] of queryClient.getQueriesData({
-      queryKey
-    })) {
-      if (!value) continue;
-      const next = withoutIds(value, idSet);
-      if (!next) continue;
-      const removed = value.data.length - next.data.length;
-      queryClient.setQueryData(key, {
-        ...next,
-        total: lowerTotal(value.total, removed)
-      });
-    }
-  }
-  const infinite = queryClient.getQueriesData({ queryKey: infiniteListKeyPrefix(resource) });
-  for (const [key, value] of infinite) {
-    if (!value) continue;
-    const kept = value.pages.map((page) => withoutIds(page, idSet) ?? page);
-    const removed = value.pages.reduce(
-      (n, page, i) => n + page.data.length - (kept[i]?.data.length ?? 0),
-      0
-    );
-    if (removed === 0) continue;
-    queryClient.setQueryData(key, {
-      ...value,
-      pages: kept.map((page) => ({
-        ...page,
-        total: lowerTotal(page.total, removed)
-      }))
-    });
-  }
-  removeManyEntries(queryClient, resource, idSet);
+	const idSet = new Set(ids.map(String));
+	for (const id of ids) queryClient.removeQueries({ queryKey: oneKey(resource, { id }) });
+	for (const queryKey of singleResultListKeyPrefixes(resource)) for (const [key, value] of singleResultEntries(queryClient, queryKey)) {
+		if (!value) continue;
+		const next = withoutIds(value, idSet);
+		if (!next) continue;
+		const removed = value.data.length - next.data.length;
+		queryClient.setQueryData(key, {
+			...next,
+			total: lowerTotal(value.total, removed)
+		});
+	}
+	const infinite = infiniteEntries(queryClient, resource);
+	for (const [key, value] of infinite) {
+		if (!value) continue;
+		const kept = value.pages.map((page) => withoutIds(page, idSet) ?? page);
+		const removed = value.pages.reduce((n, page, i) => n + page.data.length - (kept[i]?.data.length ?? 0), 0);
+		if (removed === 0) continue;
+		queryClient.setQueryData(key, {
+			...value,
+			pages: kept.map((page) => ({
+				...page,
+				total: lowerTotal(page.total, removed)
+			}))
+		});
+	}
+	removeManyEntries(queryClient, resource, idSet);
 }
+/**
+* Optimistically patch records: shallow-merge `data` into each matching
+* `getOne` entry and every matching row of every cached `getList`,
+* `getManyReference`, `getInfiniteList` page and `getMany` entry.
+*/
 function updateRecordsInCache(queryClient, resource, ids, data) {
-  const idSet = new Set(ids.map(String));
-  for (const id of ids) {
-    const key = oneKey(resource, { id });
-    const previous = queryClient.getQueryData(key);
-    if (previous !== void 0) {
-      queryClient.setQueryData(key, { ...previous, ...data });
-    }
-  }
-  for (const queryKey of singleResultListKeyPrefixes(resource)) {
-    for (const [key, value] of queryClient.getQueriesData({
-      queryKey
-    })) {
-      if (!value) continue;
-      const next = withPatchedRows(value, idSet, data);
-      if (next) queryClient.setQueryData(key, next);
-    }
-  }
-  const infinite = queryClient.getQueriesData({ queryKey: infiniteListKeyPrefix(resource) });
-  for (const [key, value] of infinite) {
-    if (!value) continue;
-    const pages = value.pages.map(
-      (page) => withPatchedRows(page, idSet, data) ?? page
-    );
-    if (pages.every((page, i) => page === value.pages[i])) continue;
-    queryClient.setQueryData(key, {
-      ...value,
-      pages
-    });
-  }
-  patchManyEntries(queryClient, resource, idSet, data);
+	const idSet = new Set(ids.map(String));
+	for (const id of ids) {
+		const key = oneKey(resource, { id });
+		const previous = queryClient.getQueryData(key);
+		if (previous !== void 0) queryClient.setQueryData(key, {
+			...previous,
+			...data
+		});
+	}
+	for (const queryKey of singleResultListKeyPrefixes(resource)) for (const [key, value] of singleResultEntries(queryClient, queryKey)) {
+		if (!value) continue;
+		const next = withPatchedRows(value, idSet, data);
+		if (next) queryClient.setQueryData(key, next);
+	}
+	const infinite = infiniteEntries(queryClient, resource);
+	for (const [key, value] of infinite) {
+		if (!value) continue;
+		const pages = value.pages.map((page) => withPatchedRows(page, idSet, data) ?? page);
+		if (pages.every((page, i) => page === value.pages[i])) continue;
+		queryClient.setQueryData(key, {
+			...value,
+			pages
+		});
+	}
+	patchManyEntries(queryClient, resource, idSet, data);
 }
-const ABSENT = /* @__PURE__ */ Symbol("absent");
+var ABSENT = Symbol("absent");
 function priorsOf(page, idSet, data) {
-  const priors = /* @__PURE__ */ new Map();
-  for (const row of page.data) {
-    const id = String(row.id);
-    if (!idSet.has(id)) continue;
-    const prior = {};
-    for (const field of Object.keys(data)) {
-      prior[field] = field in row ? row[field] : ABSENT;
-    }
-    priors.set(id, prior);
-  }
-  return priors;
+	const priors = /* @__PURE__ */ new Map();
+	for (const row of page.data) {
+		const id = String(row.id);
+		if (!idSet.has(id)) continue;
+		const prior = {};
+		for (const field in data) {
+			if (!Object.hasOwn(data, field)) continue;
+			prior[field] = field in row ? row[field] : ABSENT;
+		}
+		priors.set(id, prior);
+	}
+	return priors;
 }
+/** Puts the prior values back into the rows they were taken from. */
 function withRestoredRows(page, priors) {
-  return {
-    ...page,
-    data: page.data.map((record) => {
-      const prior = priors.get(String(record.id));
-      if (!prior) return record;
-      const restored = { ...record };
-      for (const [field, value] of Object.entries(prior)) {
-        if (value === ABSENT) delete restored[field];
-        else restored[field] = value;
-      }
-      return restored;
-    })
-  };
+	return {
+		...page,
+		data: page.data.map((record) => {
+			const prior = priors.get(String(record.id));
+			if (!prior) return record;
+			const restored = {
+				...record,
+				...prior
+			};
+			for (const field in prior) if (prior[field] === ABSENT) delete restored[field];
+			return restored;
+		})
+	};
 }
+/**
+* Shallow-merge `data` into the matching rows of every cached `getList`,
+* `getManyReference` and `getInfiniteList` page, and return a `rollback` that
+* puts back only the patched keys of those rows into whatever each entry holds
+* when it is called, so another update's patch to a different row survives.
+* An entry that holds none of the ids keeps its cached object.
+*/
 function patchListEntries(queryClient, resource, idSet, data) {
-  const rollbacks = [];
-  for (const queryKey of singleResultListKeyPrefixes(resource)) {
-    for (const [key, value] of queryClient.getQueriesData({
-      queryKey
-    })) {
-      if (!value) continue;
-      const next = withPatchedRows(value, idSet, data);
-      if (!next) continue;
-      const priors = priorsOf(value, idSet, data);
-      queryClient.setQueryData(key, next);
-      rollbacks.push(() => {
-        const current = queryClient.getQueryData(key);
-        if (current) {
-          queryClient.setQueryData(
-            key,
-            withRestoredRows(current, priors)
-          );
-        }
-      });
-    }
-  }
-  const infinite = queryClient.getQueriesData({ queryKey: infiniteListKeyPrefix(resource) });
-  for (const [key, value] of infinite) {
-    if (!value) continue;
-    const pages = value.pages.map(
-      (page) => withPatchedRows(page, idSet, data) ?? page
-    );
-    if (pages.every((page, i) => page === value.pages[i])) continue;
-    const priorsByPage = value.pages.map((page) => priorsOf(page, idSet, data));
-    queryClient.setQueryData(key, {
-      ...value,
-      pages
-    });
-    rollbacks.push(() => {
-      const current = queryClient.getQueryData(key);
-      if (!current) return;
-      queryClient.setQueryData(key, {
-        ...current,
-        pages: current.pages.map((page, i) => {
-          const priors = priorsByPage[i];
-          return priors && priors.size > 0 ? withRestoredRows(page, priors) : page;
-        })
-      });
-    });
-  }
-  return () => {
-    for (const rollback of rollbacks) rollback();
-  };
+	const rollbacks = [];
+	for (const queryKey of singleResultListKeyPrefixes(resource)) for (const [key, value] of singleResultEntries(queryClient, queryKey)) {
+		if (!value) continue;
+		const next = withPatchedRows(value, idSet, data);
+		if (!next) continue;
+		const priors = priorsOf(value, idSet, data);
+		queryClient.setQueryData(key, next);
+		rollbacks.push(() => {
+			const current = queryClient.getQueryData(key);
+			if (current) queryClient.setQueryData(key, withRestoredRows(current, priors));
+		});
+	}
+	const infinite = infiniteEntries(queryClient, resource);
+	for (const [key, value] of infinite) {
+		if (!value) continue;
+		const pages = value.pages.map((page) => withPatchedRows(page, idSet, data) ?? page);
+		if (pages.every((page, i) => page === value.pages[i])) continue;
+		const priorsByPage = value.pages.map((page) => priorsOf(page, idSet, data));
+		queryClient.setQueryData(key, {
+			...value,
+			pages
+		});
+		rollbacks.push(() => {
+			const current = queryClient.getQueryData(key);
+			if (!current) return;
+			queryClient.setQueryData(key, {
+				...current,
+				pages: current.pages.map((page, i) => {
+					const priors = priorsByPage[i];
+					return priors && priors.size > 0 ? withRestoredRows(page, priors) : page;
+				})
+			});
+		});
+	}
+	return () => {
+		for (const rollback of rollbacks) rollback();
+	};
 }
+/**
+* Shallow-merge `data` into the matching records of every cached `getMany`
+* entry (what `ReferenceField` and `ReferenceArrayField` read through).
+*/
 function patchManyEntries(queryClient, resource, idSet, data) {
-  const manys = queryClient.getQueriesData({
-    queryKey: manyKeyPrefix(resource)
-  });
-  for (const [key, value] of manys) {
-    if (!value) continue;
-    let changed = false;
-    const next = value.map((record) => {
-      if (idSet.has(String(record.id))) {
-        changed = true;
-        return { ...record, ...data };
-      }
-      return record;
-    });
-    if (changed) queryClient.setQueryData(key, next);
-  }
+	const manys = queryClient.getQueriesData({ queryKey: manyKeyPrefix(resource) });
+	for (const [key, value] of manys) {
+		if (!value) continue;
+		let changed = false;
+		const next = value.map((record) => {
+			if (idSet.has(String(record.id))) {
+				changed = true;
+				return {
+					...record,
+					...data
+				};
+			}
+			return record;
+		});
+		if (changed) queryClient.setQueryData(key, next);
+	}
 }
+/**
+* Drop the matching records from every cached `getMany` entry (what
+* `ReferenceField` and `ReferenceArrayField` read through). An entry that
+* holds none of the ids keeps its cached object.
+*/
 function removeManyEntries(queryClient, resource, idSet) {
-  const manys = queryClient.getQueriesData({
-    queryKey: manyKeyPrefix(resource)
-  });
-  for (const [key, value] of manys) {
-    if (!value) continue;
-    const kept = value.filter((record) => !idSet.has(String(record.id)));
-    if (kept.length !== value.length) {
-      queryClient.setQueryData(key, kept);
-    }
-  }
+	const manys = queryClient.getQueriesData({ queryKey: manyKeyPrefix(resource) });
+	for (const [key, value] of manys) {
+		if (!value) continue;
+		const kept = value.filter((record) => !idSet.has(String(record.id)));
+		if (kept.length !== value.length) queryClient.setQueryData(key, kept);
+	}
 }
-export {
-  patchListEntries,
-  patchManyEntries,
-  removeManyEntries,
-  removeRecordsFromCache,
-  updateRecordsInCache
-};
+export { patchListEntries, patchManyEntries, removeManyEntries, removeRecordsFromCache, updateRecordsInCache };

package/dist/data/combine-data-providers.js

@@ -1,25 +1,27 @@
+// src/data/combine-data-providers.ts
+/**
+* One provider for an app whose resources live in different backends.
+* `matcher` runs on every call (nothing is cached, so routing can change at
+* run time) and picks the provider that gets `(resource, params)`. A matcher
+* that returns nothing or throws rejects the call, and only the nine verbs of
+* the chosen provider are used.
+*/
 function combineDataProviders(matcher) {
-  const providerFor = (resource) => {
-    const provider = matcher(resource);
-    if (!provider) {
-      throw new Error(
-        `combineDataProviders: no data provider matches resource "${resource}"`
-      );
-    }
-    return provider;
-  };
-  return {
-    getList: async (resource, params) => providerFor(resource).getList(resource, params),
-    getOne: async (resource, params) => providerFor(resource).getOne(resource, params),
-    create: async (resource, params) => providerFor(resource).create(resource, params),
-    update: async (resource, params) => providerFor(resource).update(resource, params),
-    delete: async (resource, params) => providerFor(resource).delete(resource, params),
-    getMany: async (resource, params) => providerFor(resource).getMany(resource, params),
-    getManyReference: async (resource, params) => providerFor(resource).getManyReference(resource, params),
-    updateMany: async (resource, params) => providerFor(resource).updateMany(resource, params),
-    deleteMany: async (resource, params) => providerFor(resource).deleteMany(resource, params)
-  };
+	const providerFor = (resource) => {
+		const provider = matcher(resource);
+		if (!provider) throw new Error(`combineDataProviders: no data provider matches resource "${resource}"`);
+		return provider;
+	};
+	return {
+		getList: async (resource, params) => providerFor(resource).getList(resource, params),
+		getOne: async (resource, params) => providerFor(resource).getOne(resource, params),
+		create: async (resource, params) => providerFor(resource).create(resource, params),
+		update: async (resource, params) => providerFor(resource).update(resource, params),
+		delete: async (resource, params) => providerFor(resource).delete(resource, params),
+		getMany: async (resource, params) => providerFor(resource).getMany(resource, params),
+		getManyReference: async (resource, params) => providerFor(resource).getManyReference(resource, params),
+		updateMany: async (resource, params) => providerFor(resource).updateMany(resource, params),
+		deleteMany: async (resource, params) => providerFor(resource).deleteMany(resource, params)
+	};
 }
-export {
-  combineDataProviders
-};
+export { combineDataProviders };

package/dist/data/data-provider-log.d.ts

@@ -0,0 +1,45 @@
+import { type MicroStore } from "../store/micro-store.js";
+/** One settled data provider call. */
+export interface DataProviderLogEntry {
+    /** Starts at 1 and grows by one per call, in the order calls start. */
+    id: number;
+    /** The property name called on the provider: a verb or a custom method. */
+    method: string;
+    /** The first argument when it is a string, else `""`. */
+    resource: string;
+    /** The second argument as passed. */
+    params: unknown;
+    status: "ok" | "error";
+    durationMs: number;
+    /** ISO timestamp taken at the start of the call. */
+    at: string;
+    /** What the call resolved with. Present when `status` is `"ok"`. */
+    result?: unknown;
+    /** The error's message, or `String(err)` for a non-Error. Present when `status` is `"error"`. */
+    error?: string;
+}
+export interface DataProviderLogOptions {
+    /** How many of the newest entries to keep. A value below 1 reads as 1. */
+    maxEntries?: number;
+    /** Timer for `durationMs`. */
+    now?: () => number;
+    /** Wall clock for `at`. */
+    clock?: () => Date;
+}
+export interface DataProviderLog {
+    store: MicroStore<{
+        entries: readonly DataProviderLogEntry[];
+    }>;
+    /**
+     * Returns a copy of the provider whose every function property records its
+     * calls. The original is never modified.
+     */
+    wrap<TProvider extends object>(dataProvider: TProvider): TProvider;
+    /** Empties the entries. Ids keep counting. */
+    clear(): void;
+}
+/**
+ * A log of every call through a wrapped data provider, kept in a store both
+ * adapters subscribe to. Wrap once, as `withLifecycleCallbacks` does.
+ */
+export declare function createDataProviderLog({ maxEntries, now, clock, }?: DataProviderLogOptions): DataProviderLog;

package/dist/data/data-provider-log.js

@@ -0,0 +1,93 @@
+import { createMicroStore } from "../store/micro-store.js";
+// src/data/data-provider-log.ts
+/**
+* Runs `call` and returns a promise for it: a synchronous throw becomes a
+* rejection and a native promise is chained on directly, so entries land in
+* the order calls settle (resolving a new promise with it would defer them to
+* the order calls started).
+*/
+function settled(call) {
+	try {
+		return Promise.resolve(call());
+	} catch (err) {
+		return Promise.reject(err);
+	}
+}
+function isMethod(value) {
+	return typeof value === "function";
+}
+/**
+* The methods of a provider by name, own and inherited, so a class-based
+* provider's prototype methods are found. The nearest definition wins.
+*/
+function methodsOf(dataProvider) {
+	const methods = /* @__PURE__ */ new Map();
+	const seen = /* @__PURE__ */ new Set();
+	for (let level = dataProvider; level && level !== Object.prototype; level = Object.getPrototypeOf(level)) for (const [name, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(level))) {
+		if (name === "constructor" || seen.has(name)) continue;
+		seen.add(name);
+		if (isMethod(descriptor.value)) methods.set(name, descriptor.value);
+	}
+	return methods;
+}
+/**
+* A log of every call through a wrapped data provider, kept in a store both
+* adapters subscribe to. Wrap once, as `withLifecycleCallbacks` does.
+*/
+function createDataProviderLog({ maxEntries = 50, now = () => performance.now(), clock = () => /* @__PURE__ */ new Date() } = {}) {
+	const limit = maxEntries >= 1 ? Math.floor(maxEntries) : 1;
+	const store = createMicroStore({ entries: [] });
+	let lastId = 0;
+	const record = (entry) => {
+		store.setState((prev) => ({ entries: [...prev.entries, entry].slice(-limit) }));
+	};
+	const wrap = (dataProvider) => {
+		const copy = { ...dataProvider };
+		Object.setPrototypeOf(copy, Object.getPrototypeOf(dataProvider));
+		for (const [method, value] of methodsOf(dataProvider)) {
+			const logged = (...args) => {
+				const id = ++lastId;
+				const at = clock().toISOString();
+				const started = now();
+				const [resource, params] = args;
+				const base = {
+					id,
+					method,
+					resource: typeof resource === "string" ? resource : "",
+					params,
+					at
+				};
+				return settled(() => Reflect.apply(value, dataProvider, args)).then((result) => {
+					record({
+						...base,
+						status: "ok",
+						durationMs: now() - started,
+						result
+					});
+					return result;
+				}, (err) => {
+					record({
+						...base,
+						status: "error",
+						durationMs: now() - started,
+						error: err instanceof Error ? err.message : String(err)
+					});
+					throw err;
+				});
+			};
+			Object.defineProperty(copy, method, {
+				value: logged,
+				writable: true,
+				enumerable: true,
+				configurable: true
+			});
+		}
+		return copy;
+	};
+	return {
+		store,
+		wrap,
+		clear: () => store.setState({ entries: [] })
+	};
+}
+export { createDataProviderLog };

package/dist/data/errors.js

@@ -1,11 +1,15 @@
-class ValidationError extends Error {
-  name = "ValidationError";
-  fieldErrors;
-  constructor(message, fieldErrors) {
-    super(message);
-    this.fieldErrors = fieldErrors;
-  }
-}
-export {
-  ValidationError
+// src/data/errors.ts
+/**
+* Thrown/rejected by DataProvider mutations when the server rejects on
+* validation. `fieldErrors` maps field source paths to messages — P5 maps
+* this onto form state. Framework-free by design.
+*/
+var ValidationError = class extends Error {
+	name = "ValidationError";
+	fieldErrors;
+	constructor(message, fieldErrors) {
+		super(message);
+		this.fieldErrors = fieldErrors;
+	}
 };
+export { ValidationError };

package/dist/data/fake-provider.d.ts

@@ -1,6 +1,9 @@
 import type { RecordOf, ResourceMap } from "../resource/registry.js";
 import type { DataProvider } from "./types.js";
+/** One array of records per resource name, each typed by that resource's schema. */
+type FakeTables<TResources extends ResourceMap> = {
+    [N in keyof TResources & string]?: RecordOf<TResources, N>[];
+};
 /** In-memory DataProvider for tests and dogfooding. Mutates its own copy of the seed. */
-export declare function fakeDataProvider<TResources extends ResourceMap>(initialData: {
-    [K in keyof TResources]?: RecordOf<TResources, K>[];
-}): DataProvider<TResources>;
+export declare function fakeDataProvider<TResources extends ResourceMap>(initialData: FakeTables<TResources>): DataProvider<TResources>;
+export {};