@chelone/core 0.6.0 → 0.7.0

package/dist/controller/reference-many-controller.js

@@ -1,196 +1,202 @@
-import { QueryObserver } from "@tanstack/query-core";
 import { getManyReferenceOptions } from "../data/query-options.js";
 import { createMicroStore } from "../store/micro-store.js";
-import { createListController, createErrorAnnouncer, pageFlags, runSelectAll, DEFAULT_DEBOUNCE_MS, resetPageTarget } from "./list-controller.js";
-const DEFAULT_PER_PAGE = 25;
+import { createErrorAnnouncer, createListController, pageFlags, resetPageTarget, runSelectAll } from "./list-controller.js";
+import { QueryObserver } from "@tanstack/query-core";
+// src/controller/reference-many-controller.ts
+var DEFAULT_PER_PAGE = 25;
+/**
+* A server-paged list of the rows whose `target` equals `id`, read through
+* `getManyReference`. Params and selection live in an inner list controller
+* (which never fetches); this controller owns the data observer.
+*
+* Lifecycle (Task 4R) is the list controller's: construction is inert, the
+* first subscriber acquires the inner controller and the observer, the last
+* unsubscribe releases both. `observer.setOptions` runs only when the inner
+* params change, never from the result subscription; out-of-range page
+* resets go through the inner `setPage` and only on SETTLED results.
+*/
 function createReferenceManyController(ctx, reference, options) {
-  const { target, id } = options;
-  const targetValue = id ?? void 0;
-  const storeKey = options.storeKey ?? (targetValue === void 0 ? false : `${reference}.${target}.${targetValue}`);
-  const inner = createListController(
-    { ...ctx, notifications: void 0 },
-    reference,
-    {
-      perPage: options.perPage ?? DEFAULT_PER_PAGE,
-      sort: options.sort,
-      filterDefaultValues: options.filterDefaultValues,
-      storeKey,
-      enabled: false
-    }
-  );
-  const initial = inner.getSnapshot();
-  const store = createMicroStore(
-    {
-      ...initial,
-      data: targetValue === void 0 ? [] : void 0,
-      total: targetValue === void 0 ? 0 : void 0,
-      pageInfo: void 0,
-      isPending: targetValue !== void 0,
-      isFetching: false,
-      error: null,
-      hasNextPage: targetValue === void 0 ? false : void 0,
-      hasPreviousPage: targetValue === void 0 ? false : void 0
-    },
-    { onSubscribed: acquire }
-  );
-  let destroyed = false;
-  store.onDestroy(() => {
-    destroyed = true;
-    clearDebounce();
-    inner.destroy();
-  });
-  let observer = null;
-  let reconfigure = null;
-  const queryFor = (value, page, perPage) => {
-    const s = store.getSnapshot();
-    return getManyReferenceOptions(ctx, reference, {
-      target,
-      id: value,
-      pagination: { page, perPage },
-      // A single object when there is exactly one key (adapter compat).
-      sort: s.sort.length === 1 ? s.sort[0] : s.sort,
-      filter: { ...s.filter, ...options.filter ?? {} }
-    });
-  };
-  const buildOptions = (value) => {
-    const s = store.getSnapshot();
-    return {
-      ...queryFor(value, s.page, s.perPage),
-      placeholderData: (prev) => prev,
-      retry: false,
-      enabled: options.enabled ?? true
-    };
-  };
-  const mirror = () => {
-    const next = inner.getSnapshot();
-    const prev = store.getSnapshot();
-    const queryChanged = next.page !== prev.page || next.perPage !== prev.perPage || next.sort !== prev.sort || next.filter !== prev.filter;
-    store.setState({
-      page: next.page,
-      perPage: next.perPage,
-      sort: next.sort,
-      filter: next.filter,
-      displayedFilters: next.displayedFilters,
-      selectedIds: next.selectedIds
-    });
-    if (queryChanged) reconfigure?.();
-  };
-  const through = (action) => (...args) => {
-    if (destroyed) return;
-    action(...args);
-    mirror();
-  };
-  let debounceTimer;
-  function clearDebounce() {
-    if (debounceTimer === void 0) return;
-    clearTimeout(debounceTimer);
-    debounceTimer = void 0;
-  }
-  const setFilters = (filter, displayedFilters, debounced = false) => {
-    if (destroyed) return;
-    clearDebounce();
-    const apply = () => {
-      inner.setFilters(filter, displayedFilters);
-      mirror();
-    };
-    if (!debounced) {
-      apply();
-      return;
-    }
-    debounceTimer = setTimeout(() => {
-      debounceTimer = void 0;
-      apply();
-    }, options.debounceMs ?? DEFAULT_DEBOUNCE_MS);
-  };
-  const setParams = (patch) => {
-    if (patch.filter !== void 0) clearDebounce();
-    through(inner.setParams)(patch);
-  };
-  const selectAll = async (opts) => {
-    if (targetValue === void 0) return;
-    return runSelectAll(
-      ctx.notifications,
-      async (limit) => {
-        const result = await ctx.queryClient.fetchQuery({
-          ...queryFor(targetValue, 1, limit),
-          retry: false
-        });
-        return result.data;
-      },
-      (ids) => {
-        inner.select(ids);
-        mirror();
-      },
-      () => destroyed,
-      opts?.limit
-    );
-  };
-  const refetch = () => {
-    if (destroyed) return;
-    void observer?.refetch();
-  };
-  const maybeResetPage = () => {
-    const resetTo = resetPageTarget(store.getSnapshot());
-    if (resetTo === void 0) return;
-    inner.setPage(resetTo);
-    mirror();
-  };
-  const errors = createErrorAnnouncer(ctx.notifications);
-  const onResult = (result) => {
-    if (destroyed) return;
-    const list = result.data;
-    const { page, perPage } = store.getSnapshot();
-    store.setState({
-      data: list?.data,
-      total: list?.total,
-      pageInfo: list?.pageInfo,
-      isPending: result.isPending,
-      isFetching: result.isFetching,
-      error: result.error ?? null,
-      ...pageFlags(page, perPage, list?.total, list?.pageInfo)
-    });
-    errors.announce(result.error);
-    maybeResetPage();
-  };
-  function acquire() {
-    const unsubscribeInner = inner.subscribe(mirror);
-    mirror();
-    let unsubscribeObserver;
-    if (targetValue !== void 0) {
-      const value = targetValue;
-      const attached = new QueryObserver(
-        ctx.queryClient,
-        buildOptions(value)
-      );
-      observer = attached;
-      reconfigure = () => attached.setOptions(buildOptions(value));
-      unsubscribeObserver = attached.subscribe(onResult);
-      onResult(attached.getCurrentResult());
-    }
-    return () => {
-      unsubscribeObserver?.();
-      unsubscribeInner();
-      clearDebounce();
-      observer = null;
-      reconfigure = null;
-    };
-  }
-  return {
-    ...store,
-    setPage: through(inner.setPage),
-    setPerPage: through(inner.setPerPage),
-    setSort: through(inner.setSort),
-    setFilters,
-    setParams,
-    showFilter: through(inner.showFilter),
-    hideFilter: through(inner.hideFilter),
-    select: through(inner.select),
-    toggleItem: through(inner.toggleItem),
-    unselectAll: through(inner.unselectAll),
-    selectAll,
-    refetch
-  };
+	const { target, id } = options;
+	/** The value `target` must equal; undefined means "nothing to fetch". */
+	const targetValue = id ?? void 0;
+	const storeKey = options.storeKey ?? (targetValue === void 0 ? false : `${reference}.${target}.${targetValue}`);
+	const inner = createListController({
+		...ctx,
+		notifications: void 0
+	}, reference, {
+		perPage: options.perPage ?? DEFAULT_PER_PAGE,
+		sort: options.sort,
+		filterDefaultValues: options.filterDefaultValues,
+		storeKey,
+		enabled: false
+	});
+	const initial = inner.getSnapshot();
+	const store = createMicroStore({
+		...initial,
+		data: targetValue === void 0 ? [] : void 0,
+		total: targetValue === void 0 ? 0 : void 0,
+		pageInfo: void 0,
+		isPending: targetValue !== void 0,
+		isFetching: false,
+		error: null,
+		hasNextPage: targetValue === void 0 ? false : void 0,
+		hasPreviousPage: targetValue === void 0 ? false : void 0
+	}, { onSubscribed: acquire });
+	let destroyed = false;
+	store.onDestroy(() => {
+		destroyed = true;
+		clearDebounce();
+		inner.destroy();
+	});
+	/** Non-null exactly while attached to a record id. */
+	let observer = null;
+	/** Rebuilds the attached observer's options from current state. */
+	let reconfigure = null;
+	/** The one place sort and the permanent filter are folded into a query. */
+	const queryFor = (value, page, perPage) => {
+		const s = store.getSnapshot();
+		return getManyReferenceOptions(ctx, reference, {
+			target,
+			id: value,
+			pagination: {
+				page,
+				perPage
+			},
+			sort: s.sort.length === 1 ? s.sort[0] : s.sort,
+			filter: {
+				...s.filter,
+				...options.filter ?? {}
+			}
+		});
+	};
+	const buildOptions = (value) => {
+		const s = store.getSnapshot();
+		return {
+			...queryFor(value, s.page, s.perPage),
+			placeholderData: (prev) => prev,
+			retry: false,
+			enabled: options.enabled ?? true
+		};
+	};
+	const mirror = () => {
+		const next = inner.getSnapshot();
+		const prev = store.getSnapshot();
+		const queryChanged = next.page !== prev.page || next.perPage !== prev.perPage || next.sort !== prev.sort || next.filter !== prev.filter;
+		store.setState({
+			page: next.page,
+			perPage: next.perPage,
+			sort: next.sort,
+			filter: next.filter,
+			displayedFilters: next.displayedFilters,
+			selectedIds: next.selectedIds
+		});
+		if (queryChanged) reconfigure?.();
+	};
+	/** Runs an inner action, then mirrors, so detached snapshots stay truthful. */
+	const through = (action) => (...args) => {
+		if (destroyed) return;
+		action(...args);
+		mirror();
+	};
+	let debounceTimer;
+	function clearDebounce() {
+		if (debounceTimer === void 0) return;
+		clearTimeout(debounceTimer);
+		debounceTimer = void 0;
+	}
+	const setFilters = (filter, displayedFilters, debounced = false) => {
+		if (destroyed) return;
+		clearDebounce();
+		const apply = () => {
+			inner.setFilters(filter, displayedFilters);
+			mirror();
+		};
+		if (!debounced) {
+			apply();
+			return;
+		}
+		debounceTimer = setTimeout(() => {
+			debounceTimer = void 0;
+			apply();
+		}, options.debounceMs ?? 500);
+	};
+	const setParams = (patch) => {
+		if (patch.filter !== void 0) clearDebounce();
+		through(inner.setParams)(patch);
+	};
+	const selectAll = async (opts) => {
+		if (targetValue === void 0) return;
+		return runSelectAll(ctx.notifications, async (limit) => {
+			return (await ctx.queryClient.fetchQuery({
+				...queryFor(targetValue, 1, limit),
+				retry: false
+			})).data;
+		}, (ids) => {
+			inner.select(ids);
+			mirror();
+		}, () => destroyed, opts?.limit);
+	};
+	const refetch = () => {
+		if (destroyed) return;
+		observer?.refetch();
+	};
+	const maybeResetPage = () => {
+		const resetTo = resetPageTarget(store.getSnapshot());
+		if (resetTo === void 0) return;
+		inner.setPage(resetTo);
+		mirror();
+	};
+	const errors = createErrorAnnouncer(ctx.notifications);
+	const onResult = (result) => {
+		if (destroyed) return;
+		const list = result.data;
+		const { page, perPage } = store.getSnapshot();
+		store.setState({
+			data: list?.data,
+			total: list?.total,
+			pageInfo: list?.pageInfo,
+			isPending: result.isPending,
+			isFetching: result.isFetching,
+			error: result.error ?? null,
+			...pageFlags(page, perPage, list?.total, list?.pageInfo)
+		});
+		errors.announce(result.error);
+		maybeResetPage();
+	};
+	function acquire() {
+		const unsubscribeInner = inner.subscribe(mirror);
+		mirror();
+		let unsubscribeObserver;
+		if (targetValue !== void 0) {
+			const value = targetValue;
+			const attached = new QueryObserver(ctx.queryClient, buildOptions(value));
+			observer = attached;
+			reconfigure = () => attached.setOptions(buildOptions(value));
+			unsubscribeObserver = attached.subscribe(onResult);
+			onResult(attached.getCurrentResult());
+		}
+		return () => {
+			unsubscribeObserver?.();
+			unsubscribeInner();
+			clearDebounce();
+			observer = null;
+			reconfigure = null;
+		};
+	}
+	return {
+		...store,
+		setPage: through(inner.setPage),
+		setPerPage: through(inner.setPerPage),
+		setSort: through(inner.setSort),
+		setFilters,
+		setParams,
+		showFilter: through(inner.showFilter),
+		hideFilter: through(inner.hideFilter),
+		select: through(inner.select),
+		toggleItem: through(inner.toggleItem),
+		unselectAll: through(inner.unselectAll),
+		selectAll,
+		refetch
+	};
 }
-export {
-  createReferenceManyController
-};
+export { createReferenceManyController };

package/dist/controller/reference-one-controller.d.ts

@@ -23,7 +23,7 @@ export interface ReferenceOneControllerState<TRecord> {
     /** True during any fetch, the first one included. */
     isFetching: boolean;
     /** The provider error of the last fetch, else null. */
-    error: unknown;
+    error: Error | null;
 }
 export interface ReferenceOneController<TRecord> extends MicroStore<ReferenceOneControllerState<TRecord>> {
     refetch(): void;

package/dist/controller/reference-one-controller.js

@@ -1,60 +1,67 @@
-import { QueryObserver } from "@tanstack/query-core";
 import { getManyReferenceOptions } from "../data/query-options.js";
 import { createMicroStore } from "../store/micro-store.js";
+import { QueryObserver } from "@tanstack/query-core";
+// src/controller/reference-one-controller.ts
+/**
+* The first row whose `target` equals `id`, read through `getManyReference`
+* as a page of one. Errors are exposed in state and never notified: the field
+* shows an error node instead.
+*
+* Lifecycle (Task 4R): construction is inert; the observer is acquired on the
+* first subscriber and released on the last unsubscribe.
+*/
 function createReferenceOneController(ctx, reference, options) {
-  const targetValue = options.id ?? void 0;
-  const store = createMicroStore(
-    {
-      referenceRecord: void 0,
-      isPending: targetValue !== void 0,
-      isFetching: false,
-      error: null
-    },
-    { onSubscribed: acquire }
-  );
-  let destroyed = false;
-  store.onDestroy(() => {
-    destroyed = true;
-  });
-  let observer = null;
-  const onResult = (result) => {
-    store.setState({
-      referenceRecord: result.data?.data[0],
-      isPending: result.isPending,
-      isFetching: result.isFetching,
-      error: result.error ?? null
-    });
-  };
-  function acquire() {
-    if (targetValue === void 0) return void 0;
-    const attached = new QueryObserver(
-      ctx.queryClient,
-      {
-        ...getManyReferenceOptions(ctx, reference, {
-          target: options.target,
-          id: targetValue,
-          pagination: { page: 1, perPage: 1 },
-          ...options.sort === void 0 ? {} : { sort: options.sort },
-          filter: { ...options.filter ?? {} }
-        }),
-        retry: false,
-        enabled: options.enabled ?? true
-      }
-    );
-    observer = attached;
-    const unsubscribe = attached.subscribe(onResult);
-    onResult(attached.getCurrentResult());
-    return () => {
-      unsubscribe();
-      observer = null;
-    };
-  }
-  const refetch = () => {
-    if (destroyed) return;
-    void observer?.refetch();
-  };
-  return { ...store, refetch };
+	const targetValue = options.id ?? void 0;
+	const store = createMicroStore({
+		referenceRecord: void 0,
+		isPending: targetValue !== void 0,
+		isFetching: false,
+		error: null
+	}, { onSubscribed: acquire });
+	let destroyed = false;
+	store.onDestroy(() => {
+		destroyed = true;
+	});
+	let observer = null;
+	const onResult = (result) => {
+		store.setState({
+			referenceRecord: result.data?.data[0],
+			isPending: result.isPending,
+			isFetching: result.isFetching,
+			error: result.error ?? null
+		});
+	};
+	function acquire() {
+		if (targetValue === void 0) return void 0;
+		const attached = new QueryObserver(ctx.queryClient, {
+			...getManyReferenceOptions(ctx, reference, {
+				target: options.target,
+				id: targetValue,
+				pagination: {
+					page: 1,
+					perPage: 1
+				},
+				...options.sort === void 0 ? {} : { sort: options.sort },
+				filter: { ...options.filter ?? {} }
+			}),
+			retry: false,
+			enabled: options.enabled ?? true
+		});
+		observer = attached;
+		const unsubscribe = attached.subscribe(onResult);
+		onResult(attached.getCurrentResult());
+		return () => {
+			unsubscribe();
+			observer = null;
+		};
+	}
+	const refetch = () => {
+		if (destroyed) return;
+		observer?.refetch();
+	};
+	return {
+		...store,
+		refetch
+	};
 }
-export {
-  createReferenceOneController
-};
+export { createReferenceOneController };