@chelone/core 0.5.0 → 0.7.0

package/dist/controller/record-controllers.js

@@ -1,274 +1,305 @@
-import { MutationObserver, QueryObserver } from "@tanstack/query-core";
 import { ValidationError } from "../data/errors.js";
 import { createMutationOptions, deleteMutationOptions, updateMutationOptions } from "../data/mutation-options.js";
 import { getOneOptions } from "../data/query-options.js";
 import { createMicroStore } from "../store/micro-store.js";
 import { resolveNotificationKey } from "./translate-fallback.js";
+import { MutationObserver, QueryObserver } from "@tanstack/query-core";
+// src/controller/record-controllers.ts
+/**
+* THE shared save/delete flow (behaviors 9 + 10) for the edit, create and
+* delete controllers — one implementation of: the `saving` flag (counter-
+* guarded so overlapping mutations cannot flicker it false early), attached
+* vs transient observer selection, `ValidationError` RESOLVING with
+* `fieldErrors` (no notify), other errors notifying
+* `chelone.notification.http_error`, caller onSuccess/onError REPLACING the
+* defaults, the success notify, and MutationObserver release.
+*
+* MutationObserver RELEASE is explicit: mutate() attaches the observer to the
+* built Mutation (clearing its GC timeout) and query-core only detaches an
+* observer via onUnsubscribe (needs listeners), reset(), or a later mutate().
+* An unsubscribed observer therefore pins its last mutation (full data +
+* previousData) in the MutationCache forever unless we reset() — done in the
+* attach-cycle teardown and after each mutation settles (the finally block).
+*/
 function createMutationFlow(config) {
-  let pending = 0;
-  return async function run(variables, handlers = {}) {
-    if (config.isDestroyed()) return void 0;
-    const observer = config.attachedObserver() ?? config.makeObserver();
-    pending += 1;
-    config.store.setState({ saving: true });
-    let result;
-    try {
-      result = await observer.mutate(variables);
-    } catch (error) {
-      if (handlers.onError) {
-        await handlers.onError(error);
-      } else if (!(error instanceof ValidationError)) {
-        config.ctx.notifications?.notify("chelone.notification.http_error", {
-          type: "error",
-          messageArgs: { _: String(error) }
-        });
-      }
-      return error instanceof ValidationError ? error.fieldErrors : void 0;
-    } finally {
-      pending -= 1;
-      if (pending === 0) config.store.setState({ saving: false });
-      if (observer !== config.attachedObserver() || pending === 0) {
-        observer.reset();
-      }
-    }
-    if (handlers.onSaved) await handlers.onSaved(result);
-    if (handlers.onSuccess) {
-      await handlers.onSuccess(result);
-      return void 0;
-    }
-    config.ctx.notifications?.notify(
-      resolveNotificationKey(
-        config.ctx.translate,
-        config.resource,
-        config.successEvent
-      ),
-      { type: "success", messageArgs: { smart_count: 1 } }
-    );
-    config.onDefaultSuccess(result, variables);
-    return void 0;
-  };
+	/** Overlapping mutations: `saving` goes false only when the LAST one settles. */
+	let pending = 0;
+	return async function run(variables, handlers = {}) {
+		if (config.isDestroyed()) return void 0;
+		const observer = config.attachedObserver() ?? config.makeObserver();
+		pending += 1;
+		config.store.setState({ saving: true });
+		let result;
+		try {
+			result = await observer.mutate(variables);
+		} catch (error) {
+			if (handlers.onError) await handlers.onError(error);
+			else if (!(error instanceof ValidationError)) config.ctx.notifications?.notify("chelone.notification.http_error", {
+				type: "error",
+				messageArgs: { _: String(error) }
+			});
+			return error instanceof ValidationError ? error.fieldErrors : void 0;
+		} finally {
+			pending -= 1;
+			if (pending === 0) config.store.setState({ saving: false });
+			if (observer !== config.attachedObserver() || pending === 0) observer.reset();
+		}
+		if (handlers.onSaved) await handlers.onSaved(result);
+		if (handlers.onSuccess) {
+			await handlers.onSuccess(result);
+			return;
+		}
+		config.ctx.notifications?.notify(resolveNotificationKey(config.ctx.translate, config.resource, config.successEvent), {
+			type: "success",
+			messageArgs: { smart_count: 1 }
+		});
+		config.onDefaultSuccess(result, variables);
+	};
 }
+/**
+* Shared getOne wiring for the edit + show controllers: returns the acquire()
+* used as the micro-store's `onSubscribed` (post-4R pattern — construction is
+* INERT; the QueryObserver exists only while the store has subscribers).
+*
+* ra-core behavior 8: `retry: false`; a fetched record whose id does not
+* LOOSELY match the requested id becomes an error state (a local consistency
+* error — no notify); an actual fetch error notifies
+* `chelone.notification.item_doesnt_exist` and requests a list redirect.
+*/
 function createRecordFetch(ctx, resource, options, store) {
-  let lastNotifiedError = null;
-  let mismatchError = null;
-  const onResult = (result) => {
-    const record = result.data;
-    const recordId = record === void 0 ? void 0 : record.id;
-    if (record !== void 0 && String(recordId) !== String(options.id)) {
-      mismatchError ??= new Error(
-        `createRecordFetch: fetched record id (${String(recordId)}) does not match the requested id (${String(options.id)})`
-      );
-      store.setState({
-        record: void 0,
-        isPending: false,
-        isFetching: result.isFetching,
-        error: mismatchError
-      });
-      return;
-    }
-    mismatchError = null;
-    store.setState({
-      record,
-      isPending: result.isPending,
-      isFetching: result.isFetching,
-      error: result.error ?? null
-    });
-    if (result.error) {
-      if (result.error !== lastNotifiedError) {
-        lastNotifiedError = result.error;
-        ctx.notifications?.notify("chelone.notification.item_doesnt_exist", {
-          type: "error"
-        });
-        options.onRedirect?.("list", resource);
-      }
-    } else {
-      lastNotifiedError = null;
-    }
-  };
-  return function acquire() {
-    const observer = new QueryObserver(ctx.queryClient, {
-      ...getOneOptions(ctx, resource, { id: options.id }),
-      retry: false,
-      enabled: options.enabled ?? true
-    });
-    const unsubscribe = observer.subscribe(onResult);
-    onResult(observer.getCurrentResult());
-    return unsubscribe;
-  };
+	let lastNotifiedError = null;
+	/** Cached so repeated observer emissions keep a STABLE error reference. */
+	let mismatchError = null;
+	const onResult = (result) => {
+		const record = result.data;
+		const recordId = record === void 0 ? void 0 : record.id;
+		if (record !== void 0 && String(recordId) !== String(options.id)) {
+			mismatchError ??= /* @__PURE__ */ new Error(`createRecordFetch: fetched record id (${String(recordId)}) does not match the requested id (${String(options.id)})`);
+			store.setState({
+				record: void 0,
+				isPending: false,
+				isFetching: result.isFetching,
+				error: mismatchError
+			});
+			return;
+		}
+		mismatchError = null;
+		store.setState({
+			record,
+			isPending: result.isPending,
+			isFetching: result.isFetching,
+			error: result.error ?? null
+		});
+		if (result.error) {
+			if (result.error !== lastNotifiedError) {
+				lastNotifiedError = result.error;
+				ctx.notifications?.notify("chelone.notification.item_doesnt_exist", { type: "error" });
+				options.onRedirect?.("list", resource);
+			}
+		} else lastNotifiedError = null;
+	};
+	return function acquire() {
+		const observer = new QueryObserver(ctx.queryClient, {
+			...getOneOptions(ctx, resource, { id: options.id }),
+			retry: false,
+			enabled: options.enabled ?? true
+		});
+		const unsubscribe = observer.subscribe(onResult);
+		onResult(observer.getCurrentResult());
+		return unsubscribe;
+	};
 }
+/**
+* Vanilla show controller: one getOne QueryObserver mapped into a micro-store.
+* Construction is INERT; acquisition on first subscribe, release on last
+* unsubscribe AND on destroy-while-attached (micro-store lifecycle).
+*/
 function createShowController(ctx, resource, options) {
-  function acquire() {
-    return acquireFetch();
-  }
-  const store = createMicroStore(
-    { record: void 0, isPending: true, isFetching: false, error: null },
-    { onSubscribed: acquire }
-  );
-  const acquireFetch = createRecordFetch(ctx, resource, options, store);
-  return store;
+	function acquire() {
+		return acquireFetch();
+	}
+	const store = createMicroStore({
+		record: void 0,
+		isPending: true,
+		isFetching: false,
+		error: null
+	}, { onSubscribed: acquire });
+	const acquireFetch = createRecordFetch(ctx, resource, options, store);
+	return store;
 }
+/**
+* Vanilla edit controller: the show-shaped record fetch plus a `save` flow
+* backed by a MutationObserver over `updateMutationOptions`.
+*
+* Lifecycle: both observers are ACQUIRED in the micro-store's onSubscribed
+* and released on last-unsubscribe/destroy. The MutationObserver is not
+* subscribed — `saving` has a single writer (the shared mutation flow), which
+* also keeps the flag truthful for detached imperative saves. Save semantics
+* (validation errors, notify, release) live in `createMutationFlow`.
+*/
 function createEditController(ctx, resource, options) {
-  const store = createMicroStore(
-    {
-      record: void 0,
-      isPending: true,
-      isFetching: false,
-      error: null,
-      saving: false
-    },
-    { onSubscribed: acquire }
-  );
-  let destroyed = false;
-  store.onDestroy(() => {
-    destroyed = true;
-  });
-  const acquireFetch = createRecordFetch(ctx, resource, options, store);
-  const makeMutationObserver = () => new MutationObserver(
-    ctx.queryClient,
-    updateMutationOptions(ctx, resource, {
-      mutationMode: options.mutationMode
-    })
-  );
-  let mutationObserver = null;
-  function acquire() {
-    const observer = makeMutationObserver();
-    mutationObserver = observer;
-    const releaseFetch = acquireFetch();
-    return () => {
-      releaseFetch();
-      observer.reset();
-      mutationObserver = null;
-    };
-  }
-  const runSave = createMutationFlow({
-    ctx,
-    resource,
-    store,
-    isDestroyed: () => destroyed,
-    attachedObserver: () => mutationObserver,
-    makeObserver: makeMutationObserver,
-    successEvent: "updated",
-    onDefaultSuccess: (result) => {
-      options.onRedirect?.("list", resource, options.id, result);
-    }
-  });
-  const save = async (data, saveOptions = {}) => {
-    if (destroyed) return void 0;
-    const previousData = store.getSnapshot().record;
-    const transform = saveOptions.transform ?? options.transform;
-    const transformed = transform ? await transform(data, { previousData }) : data;
-    return runSave(
-      {
-        id: options.id,
-        data: transformed,
-        previousData,
-        meta: saveOptions.meta
-      },
-      saveOptions
-    );
-  };
-  return { ...store, save };
+	const store = createMicroStore({
+		record: void 0,
+		isPending: true,
+		isFetching: false,
+		error: null,
+		saving: false
+	}, { onSubscribed: acquire });
+	let destroyed = false;
+	store.onDestroy(() => {
+		destroyed = true;
+	});
+	const acquireFetch = createRecordFetch(ctx, resource, options, store);
+	const makeMutationObserver = () => new MutationObserver(ctx.queryClient, updateMutationOptions(ctx, resource, { mutationMode: options.mutationMode }));
+	/** Non-null exactly while attached. */
+	let mutationObserver = null;
+	function acquire() {
+		const observer = makeMutationObserver();
+		mutationObserver = observer;
+		const releaseFetch = acquireFetch();
+		return () => {
+			releaseFetch();
+			observer.reset();
+			mutationObserver = null;
+		};
+	}
+	const runSave = createMutationFlow({
+		ctx,
+		resource,
+		store,
+		isDestroyed: () => destroyed,
+		attachedObserver: () => mutationObserver,
+		makeObserver: makeMutationObserver,
+		successEvent: "updated",
+		onDefaultSuccess: (result) => {
+			options.onRedirect?.("list", resource, options.id, result);
+		}
+	});
+	const save = async (data, saveOptions = {}) => {
+		if (destroyed) return void 0;
+		const previousData = store.getSnapshot().record;
+		const transform = saveOptions.transform ?? options.transform;
+		const transformed = transform ? await transform(data, { previousData }) : data;
+		return runSave({
+			id: options.id,
+			data: transformed,
+			previousData,
+			meta: saveOptions.meta
+		}, saveOptions);
+	};
+	return {
+		...store,
+		save
+	};
 }
+/**
+* Vanilla create controller: no fetch AT ALL — construction is trivially
+* inert and `isPending` is false from birth. The only acquired resource is
+* the shared MutationObserver (onSubscribed attach / last-unsubscribe or
+* destroy release); detached saves use a transient observer, exactly like
+* edit. Save semantics live in `createMutationFlow`.
+*/
 function createCreateController(ctx, resource, options = {}) {
-  const store = createMicroStore(
-    { record: options.record ?? {}, saving: false, isPending: false },
-    { onSubscribed: acquire }
-  );
-  let destroyed = false;
-  store.onDestroy(() => {
-    destroyed = true;
-  });
-  const makeMutationObserver = () => new MutationObserver(ctx.queryClient, createMutationOptions(ctx, resource));
-  let mutationObserver = null;
-  function acquire() {
-    const observer = makeMutationObserver();
-    mutationObserver = observer;
-    return () => {
-      observer.reset();
-      mutationObserver = null;
-    };
-  }
-  const runSave = createMutationFlow({
-    ctx,
-    resource,
-    store,
-    isDestroyed: () => destroyed,
-    attachedObserver: () => mutationObserver,
-    makeObserver: makeMutationObserver,
-    successEvent: "created",
-    onDefaultSuccess: (result) => {
-      options.onRedirect?.(
-        "edit",
-        resource,
-        result.id,
-        result
-      );
-    }
-  });
-  const save = async (data, saveOptions = {}) => {
-    if (destroyed) return void 0;
-    const transform = saveOptions.transform ?? options.transform;
-    const transformed = transform ? await transform(data) : data;
-    return runSave({ data: transformed, meta: saveOptions.meta }, saveOptions);
-  };
-  return { ...store, save };
+	const store = createMicroStore({
+		record: options.record ?? {},
+		saving: false,
+		isPending: false
+	}, { onSubscribed: acquire });
+	let destroyed = false;
+	store.onDestroy(() => {
+		destroyed = true;
+	});
+	const makeMutationObserver = () => new MutationObserver(ctx.queryClient, createMutationOptions(ctx, resource));
+	/** Non-null exactly while attached. */
+	let mutationObserver = null;
+	function acquire() {
+		const observer = makeMutationObserver();
+		mutationObserver = observer;
+		return () => {
+			observer.reset();
+			mutationObserver = null;
+		};
+	}
+	const runSave = createMutationFlow({
+		ctx,
+		resource,
+		store,
+		isDestroyed: () => destroyed,
+		attachedObserver: () => mutationObserver,
+		makeObserver: makeMutationObserver,
+		successEvent: "created",
+		onDefaultSuccess: (result) => {
+			options.onRedirect?.("edit", resource, result.id, result);
+		}
+	});
+	const save = async (data, saveOptions = {}) => {
+		if (destroyed) return void 0;
+		const transform = saveOptions.transform ?? options.transform;
+		const transformed = transform ? await transform(data) : data;
+		return runSave({
+			data: transformed,
+			meta: saveOptions.meta
+		}, saveOptions);
+	};
+	return {
+		...store,
+		save
+	};
 }
+/**
+* Vanilla delete controller: no fetch — like create, construction is
+* trivially inert and the only acquired resource is the shared
+* MutationObserver. Delete semantics live in `createMutationFlow`; the
+* delete-specific default success additionally cleans the KV selection so a
+* deleted row cannot linger selected in list views.
+*/
 function createDeleteController(ctx, resource, options = {}) {
-  const store = createMicroStore(
-    { saving: false },
-    { onSubscribed: acquire }
-  );
-  let destroyed = false;
-  store.onDestroy(() => {
-    destroyed = true;
-  });
-  const makeMutationObserver = () => new MutationObserver(ctx.queryClient, deleteMutationOptions(ctx, resource));
-  let mutationObserver = null;
-  function acquire() {
-    const observer = makeMutationObserver();
-    mutationObserver = observer;
-    return () => {
-      observer.reset();
-      mutationObserver = null;
-    };
-  }
-  const stripSelection = (id) => {
-    const kv = ctx.store;
-    if (!kv) return;
-    const key = `${resource}.selectedIds`;
-    const selection = kv.getItem(key);
-    if (!selection?.includes(id)) return;
-    kv.setItem(
-      key,
-      selection.filter((existing) => existing !== id)
-    );
-  };
-  const runDelete = createMutationFlow({
-    ctx,
-    resource,
-    store,
-    isDestroyed: () => destroyed,
-    attachedObserver: () => mutationObserver,
-    makeObserver: makeMutationObserver,
-    successEvent: "deleted",
-    onDefaultSuccess: (_result, variables) => {
-      options.onRedirect?.("list", resource);
-      stripSelection(variables.id);
-    }
-  });
-  const deleteOne = async (id, deleteOptions = {}) => runDelete(
-    {
-      id,
-      previousData: deleteOptions.previousData,
-      meta: deleteOptions.meta
-    },
-    deleteOptions
-  );
-  return { ...store, deleteOne };
+	const store = createMicroStore({ saving: false }, { onSubscribed: acquire });
+	let destroyed = false;
+	store.onDestroy(() => {
+		destroyed = true;
+	});
+	const makeMutationObserver = () => new MutationObserver(ctx.queryClient, deleteMutationOptions(ctx, resource));
+	/** Non-null exactly while attached. */
+	let mutationObserver = null;
+	function acquire() {
+		const observer = makeMutationObserver();
+		mutationObserver = observer;
+		return () => {
+			observer.reset();
+			mutationObserver = null;
+		};
+	}
+	/** Strips the REQUESTED id from the KV selection — immutably (fresh array). */
+	const stripSelection = (id) => {
+		const kv = ctx.store;
+		if (!kv) return;
+		const key = `${resource}.selectedIds`;
+		const selection = kv.getItem(key);
+		if (!selection?.includes(id)) return;
+		kv.setItem(key, selection.filter((existing) => existing !== id));
+	};
+	const runDelete = createMutationFlow({
+		ctx,
+		resource,
+		store,
+		isDestroyed: () => destroyed,
+		attachedObserver: () => mutationObserver,
+		makeObserver: makeMutationObserver,
+		successEvent: "deleted",
+		onDefaultSuccess: (_result, variables) => {
+			options.onRedirect?.("list", resource);
+			stripSelection(variables.id);
+		}
+	});
+	const deleteOne = async (id, deleteOptions = {}) => runDelete({
+		id,
+		previousData: deleteOptions.previousData,
+		meta: deleteOptions.meta
+	}, deleteOptions);
+	return {
+		...store,
+		deleteOne
+	};
 }
-export {
-  createCreateController,
-  createDeleteController,
-  createEditController,
-  createShowController
-};
+export { createCreateController, createDeleteController, createEditController, createShowController };

package/dist/controller/record-diff.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Pure rules for a record diff. No react, no vue: both DiffViewer adapters
+ * mark the same field the same way and print the same default text.
+ */
+import type { SourcePath } from "../resource/source-path.js";
+export type DiffStatus = "unchanged" | "added" | "removed" | "changed";
+export interface RecordDiffRow {
+    source: string;
+    status: DiffStatus;
+    before: unknown;
+    after: unknown;
+}
+/**
+ * One row per source, in the order given. Without `sources` the rows are the
+ * top-level keys of `before` in its order, then the keys only `after` has.
+ * `null` and `undefined` both count as missing; an empty string is a value.
+ * Neither record is changed.
+ */
+export declare function diffRecords<R>(before: R, after: R, sources?: readonly SourcePath<R>[]): RecordDiffRow[];
+/** The text a viewer shows for a value when the app gives no renderer. */
+export declare function formatDiffValue(value: unknown): string;

package/dist/controller/record-diff.js

@@ -0,0 +1,50 @@
+import { isPlainObject, isRecord } from "../guards.js";
+import { getAtPath } from "../resource/get-at-path.js";
+import { deepEqual } from "./deep-equal.js";
+// src/controller/record-diff.ts
+/**
+* Pure rules for a record diff. No react, no vue: both DiffViewer adapters
+* mark the same field the same way and print the same default text.
+*/
+function topLevelKeys(record) {
+	return isRecord(record) ? Object.keys(record) : [];
+}
+function statusOf(before, after) {
+	const hadBefore = before != null;
+	const hasAfter = after != null;
+	if (!hadBefore && !hasAfter) return "unchanged";
+	if (!hadBefore) return "added";
+	if (!hasAfter) return "removed";
+	return deepEqual(before, after) ? "unchanged" : "changed";
+}
+/**
+* One row per source, in the order given. Without `sources` the rows are the
+* top-level keys of `before` in its order, then the keys only `after` has.
+* `null` and `undefined` both count as missing; an empty string is a value.
+* Neither record is changed.
+*/
+function diffRecords(before, after, sources) {
+	const beforeKeys = topLevelKeys(before);
+	return (sources ?? [...beforeKeys, ...topLevelKeys(after).filter((key) => !beforeKeys.includes(key))]).map((source) => {
+		const was = getAtPath(before, source);
+		const now = getAtPath(after, source);
+		return {
+			source,
+			status: statusOf(was, now),
+			before: was,
+			after: now
+		};
+	});
+}
+/** The text a viewer shows for a value when the app gives no renderer. */
+function formatDiffValue(value) {
+	if (value == null) return "";
+	if (value instanceof Date && !Number.isNaN(value.getTime())) return value.toISOString();
+	if (Array.isArray(value) || isPlainObject(value)) try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+	return String(value);
+}
+export { diffRecords, formatDiffValue };