@chelone/core 0.6.0 → 0.9.0

package/dist/form/choices-controller.d.ts

@@ -2,7 +2,14 @@ import { type DataContext } from "../data/query-options.js";
 import type { FilterPayload, PageInfo, SortPayload } from "../data/types.js";
 import type { NotificationStore } from "../notification/notification-store.js";
 import type { RecordOf, ResourceMap } from "../resource/registry.js";
+import type { SourceKey } from "../resource/source-path.js";
 import { type MicroStore } from "../store/micro-store.js";
+/**
+ * An erased choice record: choices carry arbitrary shapes (`{id, name, ...}`),
+ * and an adapter's choice inputs are generic over one. Both adapters re-export
+ * this as their own `ChoiceRecord`.
+ */
+export type ChoiceRecord = Record<string, unknown>;
 /**
  * The choices-context state (§0b parity). A list-like base (page/perPage/sort/
  * filter) plus a status union over three record views:
@@ -31,7 +38,7 @@ export interface ChoicesControllerState<TRecord> {
     hasPreviousPage: boolean | undefined;
     isPending: boolean;
     isFetching: boolean;
-    error: unknown;
+    error: Error | null;
     /** The referenced resource name. */
     resource: string;
     /** The FK field on the referencing side (metadata for consumers). */
@@ -62,7 +69,7 @@ export interface ChoicesControllerOptions<TResources extends ResourceMap = Resou
      * `'id'` (default) resolves selected records via `getMany`; any other key
      * resolves via `getList({ filter: { [lookupKey]: value } })` (#16).
      */
-    lookupKey?: string;
+    lookupKey?: SourceKey<RecordOf<TResources, TName>>;
     /** Permanent filter — merged OVER the dynamic filter for every choices fetch. */
     filter?: FilterPayload;
     page?: number;
@@ -93,3 +100,16 @@ export interface ChoicesControllerOptions<TResources extends ResourceMap = Resou
  * observer result subscription — the subscription only maps results into state.
  */
 export declare function createChoicesController<TResources extends ResourceMap, TName extends keyof TResources & string>(ctx: ChoicesControllerContext<TResources>, options: ChoicesControllerOptions<TResources, TName>): ChoicesController<RecordOf<TResources, TName>>;
+/** The three choice views of a state, erased to `ChoiceRecord[]`. */
+export interface ChoiceLists {
+    allChoices: ChoiceRecord[];
+    availableChoices: ChoiceRecord[];
+    selectedChoices: ChoiceRecord[];
+}
+/**
+ * The state's three choice views as the erased lists an adapter's
+ * `ChoicesContextValue` carries — the one place a record becomes a
+ * `ChoiceRecord`, so neither adapter writes the cast. The arrays are the
+ * state's own, not copies.
+ */
+export declare function choiceListsOf<TRecord>(state: ChoicesControllerState<TRecord>): ChoiceLists;

package/dist/form/choices-controller.js

@@ -1,281 +1,321 @@
-import { QueryObserver, keepPreviousData } from "@tanstack/query-core";
+import { notifyFetchError } from "../controller/list-controller.js";
+import "../controller/reference-many-controller.js";
 import { getListOptions, getManyOptions } from "../data/query-options.js";
+import { removeEmpty } from "../data/remove-empty.js";
 import { createMicroStore } from "../store/micro-store.js";
-const DEFAULT_PAGE = 1;
-const DEFAULT_PER_PAGE = 25;
-const DEFAULT_DEBOUNCE_MS = 500;
-const DEFAULT_SORT = { field: "id", order: "DESC" };
-const SELECTED_LIST_PER_PAGE = 1e3;
-function removeEmpty(filter) {
-  const result = {};
-  for (const [key, value] of Object.entries(filter)) {
-    if (value === "" || value === null || value === void 0) continue;
-    result[key] = value;
-  }
-  return result;
-}
-function errorMessageKey(error) {
-  const message = error instanceof Error ? error.message : "";
-  return message || "chelone.notification.http_error";
-}
+import { QueryObserver, keepPreviousData } from "@tanstack/query-core";
+// src/form/choices-controller.ts
+var DEFAULT_PAGE = 1;
+var DEFAULT_SORT = {
+	field: "id",
+	order: "DESC"
+};
+/** perPage for the non-id selected getList — generous, real values sets are small. */
+var SELECTED_LIST_PER_PAGE = 1e3;
+/** Normalizes a value into a non-empty identifier list, or `[]` when there is nothing to resolve. */
 function toValueList(value) {
-  const raw = Array.isArray(value) ? value : [value];
-  return raw.filter(
-    (v) => v != null && v !== "" && (typeof v === "string" || typeof v === "number")
-  );
+	return (Array.isArray(value) ? value : [value]).filter((v) => v != null && v !== "" && (typeof v === "string" || typeof v === "number"));
 }
+/**
+* Vanilla choices controller: TWO QueryObservers (choices page + selected
+* resolution) mapped into one micro-store, closing charter §11 #16 — selected
+* records resolve by an arbitrary `lookupKey`, not just `id`.
+*
+* Lifecycle (P4 4R): construction is INERT — pure state + closures, zero
+* subscriptions, zero fetching. Acquisition (both observers + KV nothing) runs
+* on the micro-store's FIRST subscriber; the LAST unsubscribe releases both
+* observers and clears the debounce timer. Attach/detach cycles are
+* re-entrant; re-attach rebuilds both observers from CURRENT state.
+* `destroy()` remains the hard imperative teardown for non-React consumers.
+*
+* Loop-prevention: `observer.setOptions` is called ONLY from param-mutating
+* actions (`setPage`/`setSort`/`setFilters`/`setValue`), never from the
+* observer result subscription — the subscription only maps results into state.
+*/
 function createChoicesController(ctx, options) {
-  const reference = options.reference;
-  const lookupKey = options.lookupKey ?? "id";
-  const isIdLookup = lookupKey === "id";
-  const permanentFilter = options.filter ?? {};
-  const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
-  const store = createMicroStore(
-    {
-      page: options.page ?? DEFAULT_PAGE,
-      perPage: options.perPage ?? DEFAULT_PER_PAGE,
-      sort: { ...options.sort ?? DEFAULT_SORT },
-      filter: {},
-      allChoices: [],
-      availableChoices: [],
-      selectedChoices: [],
-      total: void 0,
-      pageInfo: void 0,
-      hasNextPage: void 0,
-      hasPreviousPage: void 0,
-      isPending: true,
-      isFetching: false,
-      error: null,
-      resource: reference,
-      source: options.source,
-      isFromReference: true
-    },
-    { onSubscribed: acquire }
-  );
-  let destroyed = false;
-  store.onDestroy(() => {
-    destroyed = true;
-  });
-  let choicesObserver = null;
-  let selectedObserver = null;
-  let selectedValues = [];
-  let pageData;
-  let pageTotal;
-  let pageInfo;
-  let selectedData = [];
-  const isGetChoicesEnabled = () => options.enableGetChoices ? options.enableGetChoices(store.getSnapshot().filter) : true;
-  const buildChoicesOptions = () => {
-    const s = store.getSnapshot();
-    return {
-      ...getListOptions(ctx, reference, {
-        pagination: { page: s.page, perPage: s.perPage },
-        sort: s.sort,
-        filter: { ...s.filter, ...permanentFilter },
-        meta: options.meta
-      }),
-      placeholderData: keepPreviousData,
-      retry: false,
-      enabled: isGetChoicesEnabled()
-    };
-  };
-  const buildSelectedOptions = () => {
-    const enabled = selectedValues.length > 0;
-    if (isIdLookup) {
-      return {
-        ...getManyOptions(ctx, reference, {
-          ids: selectedValues,
-          meta: options.meta
-        }),
-        retry: false,
-        enabled
-      };
-    }
-    const filterValue = selectedValues.length === 1 ? selectedValues[0] : selectedValues;
-    return {
-      ...getListOptions(ctx, reference, {
-        pagination: { page: 1, perPage: SELECTED_LIST_PER_PAGE },
-        filter: { [lookupKey]: filterValue },
-        meta: options.meta
-      }),
-      retry: false,
-      enabled
-    };
-  };
-  const readSelectedData = (result) => {
-    const data = result.data;
-    if (data == null) return [];
-    return Array.isArray(data) ? data : data.data;
-  };
-  const recompute = (patch) => {
-    const s = store.getSnapshot();
-    const page = pageData ?? [];
-    const selected = selectedData;
-    const keyOf = (record) => record[lookupKey];
-    const pageKeys = new Set(page.map(keyOf));
-    const missing = selected.filter((record) => !pageKeys.has(keyOf(record)));
-    const allChoices = missing.length > 0 ? [...missing, ...page] : page;
-    let total = pageTotal;
-    if (total !== void 0 && missing.length === 1 && selected.length === 1) {
-      total = total + 1;
-    }
-    let hasNextPage;
-    let hasPreviousPage;
-    if (pageInfo) {
-      hasNextPage = pageInfo.hasNextPage;
-      hasPreviousPage = pageInfo.hasPreviousPage;
-    } else if (pageTotal !== void 0) {
-      hasNextPage = s.page * s.perPage < pageTotal;
-      hasPreviousPage = s.page > 1;
-    }
-    store.setState({
-      allChoices,
-      availableChoices: page,
-      selectedChoices: selected,
-      total,
-      pageInfo,
-      hasNextPage,
-      hasPreviousPage,
-      isPending: patch.isPending,
-      isFetching: patch.isFetching,
-      error: patch.error
-    });
-  };
-  let lastNotifiedError = null;
-  const notifyError = (error) => {
-    if (error === lastNotifiedError) return;
-    lastNotifiedError = error;
-    if (error == null) return;
-    ctx.notifications?.notify(errorMessageKey(error), {
-      type: "error",
-      messageArgs: { _: String(error) }
-    });
-  };
-  const onChoicesResult = (result) => {
-    const list = result.data;
-    pageData = list?.data;
-    pageTotal = list?.total;
-    pageInfo = list?.pageInfo;
-    const selectedPending = selectedValues.length > 0 && selectedObserver ? selectedObserver.getCurrentResult().isPending : false;
-    const selectedFetching = selectedValues.length > 0 && selectedObserver ? selectedObserver.getCurrentResult().isFetching : false;
-    const error = result.error ?? selectedObserver?.getCurrentResult().error ?? null;
-    recompute({
-      isPending: result.isPending || selectedPending,
-      isFetching: result.isFetching || selectedFetching,
-      error
-    });
-    notifyError(result.error ?? null);
-  };
-  const onSelectedResult = (result) => {
-    selectedData = readSelectedData(result);
-    const choicesResult = choicesObserver?.getCurrentResult();
-    const choicesPending = choicesResult?.isPending ?? false;
-    const choicesFetching = choicesResult?.isFetching ?? false;
-    const selectedPending = selectedValues.length > 0 && result.isPending;
-    const selectedFetching = selectedValues.length > 0 && result.isFetching;
-    const error = choicesResult?.error ?? result.error ?? null;
-    recompute({
-      isPending: choicesPending || selectedPending,
-      isFetching: choicesFetching || selectedFetching,
-      error
-    });
-  };
-  const setPage = (page) => {
-    if (destroyed) return;
-    store.setState({ page });
-    choicesObserver?.setOptions(buildChoicesOptions());
-  };
-  const setPerPage = (perPage) => {
-    if (destroyed) return;
-    store.setState({ perPage, page: 1 });
-    choicesObserver?.setOptions(buildChoicesOptions());
-  };
-  const setSort = (sort) => {
-    if (destroyed) return;
-    store.setState({ sort: { ...sort }, page: 1 });
-    choicesObserver?.setOptions(buildChoicesOptions());
-  };
-  const applyFilters = (filter) => {
-    store.setState({ filter: removeEmpty(filter), page: 1 });
-    choicesObserver?.setOptions(buildChoicesOptions());
-  };
-  let debounceTimer;
-  const clearDebounce = () => {
-    if (debounceTimer !== void 0) {
-      clearTimeout(debounceTimer);
-      debounceTimer = void 0;
-    }
-  };
-  store.onDestroy(clearDebounce);
-  const setFilters = (filter, debounce = false) => {
-    if (destroyed) return;
-    clearDebounce();
-    if (!debounce) {
-      applyFilters(filter);
-      return;
-    }
-    debounceTimer = setTimeout(() => {
-      debounceTimer = void 0;
-      if (destroyed) return;
-      applyFilters(filter);
-    }, debounceMs);
-  };
-  const setValue = (value) => {
-    if (destroyed) return;
-    const next = toValueList(value);
-    if (next.length === selectedValues.length && next.every((v, i) => v === selectedValues[i])) {
-      return;
-    }
-    selectedValues = next;
-    if (next.length === 0) {
-      selectedData = [];
-    }
-    selectedObserver?.setOptions(buildSelectedOptions());
-    if (!selectedObserver && next.length === 0) {
-      recompute({
-        isPending: store.getSnapshot().isPending,
-        isFetching: store.getSnapshot().isFetching,
-        error: store.getSnapshot().error
-      });
-    }
-  };
-  const refetch = () => {
-    if (destroyed) return;
-    void choicesObserver?.refetch();
-    if (selectedValues.length > 0) void selectedObserver?.refetch();
-  };
-  function acquire() {
-    const choices = new QueryObserver(
-      ctx.queryClient,
-      buildChoicesOptions()
-    );
-    choicesObserver = choices;
-    const selected = new QueryObserver(
-      ctx.queryClient,
-      buildSelectedOptions()
-    );
-    selectedObserver = selected;
-    const unsubChoices = choices.subscribe(onChoicesResult);
-    const unsubSelected = selected.subscribe(onSelectedResult);
-    onSelectedResult(selected.getCurrentResult());
-    onChoicesResult(choices.getCurrentResult());
-    return () => {
-      unsubChoices();
-      unsubSelected();
-      choicesObserver = null;
-      selectedObserver = null;
-      clearDebounce();
-    };
-  }
-  return {
-    ...store,
-    setPage,
-    setPerPage,
-    setSort,
-    setFilters,
-    setValue,
-    refetch
-  };
+	const reference = options.reference;
+	const lookupKey = options.lookupKey ?? "id";
+	const isIdLookup = lookupKey === "id";
+	const permanentFilter = options.filter ?? {};
+	const debounceMs = options.debounceMs ?? 500;
+	const store = createMicroStore({
+		page: options.page ?? DEFAULT_PAGE,
+		perPage: options.perPage ?? 25,
+		sort: { ...options.sort ?? DEFAULT_SORT },
+		filter: {},
+		allChoices: [],
+		availableChoices: [],
+		selectedChoices: [],
+		total: void 0,
+		pageInfo: void 0,
+		hasNextPage: void 0,
+		hasPreviousPage: void 0,
+		isPending: true,
+		isFetching: false,
+		error: null,
+		resource: reference,
+		source: options.source,
+		isFromReference: true
+	}, { onSubscribed: acquire });
+	let destroyed = false;
+	store.onDestroy(() => {
+		destroyed = true;
+	});
+	/** Non-null exactly while attached. */
+	let choicesObserver = null;
+	/** Selected observer: getMany (id) OR getList (non-id). Rebuilt on setValue. */
+	let selectedObserver = null;
+	/** The value(s) currently driving selected resolution. */
+	let selectedValues = [];
+	/** Latest raw fetch results, cached so `recompute()` can re-merge on any change. */
+	let pageData;
+	let pageTotal;
+	let pageInfo;
+	let selectedData = [];
+	const isGetChoicesEnabled = () => options.enableGetChoices ? options.enableGetChoices(store.getSnapshot().filter) : true;
+	const buildChoicesOptions = () => {
+		const s = store.getSnapshot();
+		return {
+			...getListOptions(ctx, reference, {
+				pagination: {
+					page: s.page,
+					perPage: s.perPage
+				},
+				sort: s.sort,
+				filter: {
+					...s.filter,
+					...permanentFilter
+				},
+				meta: options.meta
+			}),
+			placeholderData: keepPreviousData,
+			retry: false,
+			enabled: isGetChoicesEnabled()
+		};
+	};
+	/**
+	* Options for the selected observer. `id` lookup batches through getMany;
+	* any other key resolves through a getList filter (single OR array value).
+	* Disabled when there is nothing to resolve so it never pins `isPending`.
+	*/
+	const buildSelectedOptions = () => {
+		const enabled = selectedValues.length > 0;
+		if (isIdLookup) return {
+			...getManyOptions(ctx, reference, {
+				ids: selectedValues,
+				meta: options.meta
+			}),
+			retry: false,
+			enabled
+		};
+		const filterValue = selectedValues.length === 1 ? selectedValues[0] : selectedValues;
+		return {
+			...getListOptions(ctx, reference, {
+				pagination: {
+					page: 1,
+					perPage: SELECTED_LIST_PER_PAGE
+				},
+				filter: { [lookupKey]: filterValue },
+				meta: options.meta
+			}),
+			retry: false,
+			enabled
+		};
+	};
+	/** Records from the selected observer result, whichever shape it is. */
+	const readSelectedData = (result) => {
+		const data = result.data;
+		if (data == null) return [];
+		return Array.isArray(data) ? data : data.data;
+	};
+	/**
+	* Merge the page + selected records into the three views (§0b parity), then
+	* write the derived state. Called from BOTH result subscriptions.
+	*/
+	const recompute = (patch) => {
+		const s = store.getSnapshot();
+		const page = pageData ?? [];
+		const selected = selectedData;
+		const keyOf = (record) => record[lookupKey];
+		const pageKeys = new Set(page.map(keyOf));
+		const missing = selected.filter((record) => !pageKeys.has(keyOf(record)));
+		const allChoices = missing.length > 0 ? [...missing, ...page] : page;
+		let total = pageTotal;
+		if (total !== void 0 && missing.length === 1 && selected.length === 1) total = total + 1;
+		let hasNextPage;
+		let hasPreviousPage;
+		if (pageInfo) {
+			hasNextPage = pageInfo.hasNextPage;
+			hasPreviousPage = pageInfo.hasPreviousPage;
+		} else if (pageTotal !== void 0) {
+			hasNextPage = s.page * s.perPage < pageTotal;
+			hasPreviousPage = s.page > 1;
+		}
+		store.setState({
+			allChoices,
+			availableChoices: page,
+			selectedChoices: selected,
+			total,
+			pageInfo,
+			hasNextPage,
+			hasPreviousPage,
+			isPending: patch.isPending,
+			isFetching: patch.isFetching,
+			error: patch.error
+		});
+	};
+	let lastNotifiedError = null;
+	const notifyError = (error) => {
+		if (error === lastNotifiedError) return;
+		lastNotifiedError = error;
+		if (error === null) return;
+		notifyFetchError(ctx.notifications, error);
+	};
+	/**
+	* The combined status union. `isPending` reflects the choices query and the
+	* selected query ONLY when a value is being resolved — a valueless selected
+	* query is disabled and must never pin `isPending` (§0b).
+	*/
+	const onChoicesResult = (result) => {
+		const list = result.data;
+		pageData = list?.data;
+		pageTotal = list?.total;
+		pageInfo = list?.pageInfo;
+		const selectedPending = selectedValues.length > 0 && selectedObserver ? selectedObserver.getCurrentResult().isPending : false;
+		const selectedFetching = selectedValues.length > 0 && selectedObserver ? selectedObserver.getCurrentResult().isFetching : false;
+		const error = result.error ?? selectedObserver?.getCurrentResult().error ?? null;
+		recompute({
+			isPending: result.isPending || selectedPending,
+			isFetching: result.isFetching || selectedFetching,
+			error
+		});
+		notifyError(result.error ?? null);
+	};
+	const onSelectedResult = (result) => {
+		selectedData = readSelectedData(result);
+		const choicesResult = choicesObserver?.getCurrentResult();
+		const choicesPending = choicesResult?.isPending ?? false;
+		const choicesFetching = choicesResult?.isFetching ?? false;
+		const selectedPending = selectedValues.length > 0 && result.isPending;
+		const selectedFetching = selectedValues.length > 0 && result.isFetching;
+		const error = choicesResult?.error ?? result.error ?? null;
+		recompute({
+			isPending: choicesPending || selectedPending,
+			isFetching: choicesFetching || selectedFetching,
+			error
+		});
+	};
+	const setPage = (page) => {
+		if (destroyed) return;
+		store.setState({ page });
+		choicesObserver?.setOptions(buildChoicesOptions());
+	};
+	const setPerPage = (perPage) => {
+		if (destroyed) return;
+		store.setState({
+			perPage,
+			page: 1
+		});
+		choicesObserver?.setOptions(buildChoicesOptions());
+	};
+	const setSort = (sort) => {
+		if (destroyed) return;
+		store.setState({
+			sort: { ...sort },
+			page: 1
+		});
+		choicesObserver?.setOptions(buildChoicesOptions());
+	};
+	const applyFilters = (filter) => {
+		store.setState({
+			filter: removeEmpty(filter),
+			page: 1
+		});
+		choicesObserver?.setOptions(buildChoicesOptions());
+	};
+	let debounceTimer;
+	const clearDebounce = () => {
+		if (debounceTimer !== void 0) {
+			clearTimeout(debounceTimer);
+			debounceTimer = void 0;
+		}
+	};
+	store.onDestroy(clearDebounce);
+	const setFilters = (filter, debounce = false) => {
+		if (destroyed) return;
+		clearDebounce();
+		if (!debounce) {
+			applyFilters(filter);
+			return;
+		}
+		debounceTimer = setTimeout(() => {
+			debounceTimer = void 0;
+			if (destroyed) return;
+			applyFilters(filter);
+		}, debounceMs);
+	};
+	const setValue = (value) => {
+		if (destroyed) return;
+		const next = toValueList(value);
+		if (next.length === selectedValues.length && next.every((v, i) => v === selectedValues[i])) return;
+		selectedValues = next;
+		if (next.length === 0) selectedData = [];
+		selectedObserver?.setOptions(buildSelectedOptions());
+		if (!selectedObserver && next.length === 0) recompute({
+			isPending: store.getSnapshot().isPending,
+			isFetching: store.getSnapshot().isFetching,
+			error: store.getSnapshot().error
+		});
+	};
+	const refetch = () => {
+		if (destroyed) return;
+		choicesObserver?.refetch();
+		if (selectedValues.length > 0) selectedObserver?.refetch();
+	};
+	/**
+	* Attach: runs on the micro-store's FIRST subscriber. Creates and subscribes
+	* BOTH observers with options built from CURRENT state, and returns the
+	* teardown the micro-store runs on last-unsubscribe AND destroy-while-attached.
+	*/
+	function acquire() {
+		const choices = new QueryObserver(ctx.queryClient, buildChoicesOptions());
+		choicesObserver = choices;
+		const selected = new QueryObserver(ctx.queryClient, buildSelectedOptions());
+		selectedObserver = selected;
+		const unsubChoices = choices.subscribe(onChoicesResult);
+		const unsubSelected = selected.subscribe(onSelectedResult);
+		onSelectedResult(selected.getCurrentResult());
+		onChoicesResult(choices.getCurrentResult());
+		return () => {
+			unsubChoices();
+			unsubSelected();
+			choicesObserver = null;
+			selectedObserver = null;
+			clearDebounce();
+		};
+	}
+	return {
+		...store,
+		setPage,
+		setPerPage,
+		setSort,
+		setFilters,
+		setValue,
+		refetch
+	};
 }
-export {
-  createChoicesController
-};
+/**
+* The state's three choice views as the erased lists an adapter's
+* `ChoicesContextValue` carries — the one place a record becomes a
+* `ChoiceRecord`, so neither adapter writes the cast. The arrays are the
+* state's own, not copies.
+*/
+function choiceListsOf(state) {
+	const { allChoices, availableChoices, selectedChoices } = state;
+	return {
+		allChoices,
+		availableChoices,
+		selectedChoices
+	};
+}
+export { choiceListsOf, createChoicesController };