@chelone/core 0.1.0 → 0.1.1

package/dist/controller/list-controller.d.ts

@@ -39,6 +39,8 @@ export interface ListParamsPatch {
     page?: number;
 }
 export interface ListController<TRecord> extends MicroStore<ListControllerState<TRecord>> {
+    /** The `perPage` the list starts at when nothing is persisted or in the URL. Optional so other list controllers and fakes need not set it. */
+    readonly defaultPerPage?: number;
     setPage(page: number): void;
     setPerPage(perPage: number): void;
     /** Single payload on the SAME single-sorted field toggles order; anything else replaces. */
@@ -136,4 +138,24 @@ export declare function resetPageTarget(s: Pick<ListControllerState<unknown>, "p
  * action path and are guarded to run only on SETTLED results, so they
  * cannot ping-pong.
  */
+/**
+ * The actions of a list controller, for an adapter to spread next to its own
+ * reactive state. They are the same functions across state changes.
+ */
+export declare function listControllerActions(controller: Omit<ListController<unknown>, keyof MicroStore<ListControllerState<unknown>> | "defaultPerPage">): {
+    setPage: (page: number) => void;
+    setPerPage: (perPage: number) => void;
+    setSort: (sort: SortPayload | SortPayload[]) => void;
+    setFilters: (filter: FilterPayload, displayedFilters?: Record<string, boolean>, debounced?: boolean) => void;
+    setParams: (patch: ListParamsPatch) => void;
+    showFilter: (name: string, defaultValue?: unknown) => void;
+    hideFilter: (name: string) => void;
+    select: (ids: Identifier[]) => void;
+    toggleItem: (id: Identifier) => void;
+    unselectAll: () => void;
+    selectAll: (options?: {
+        limit?: number;
+    }) => Promise<void>;
+    refetch: () => void;
+};
 export declare function createListController<TResources extends ResourceMap, TName extends keyof TResources & string>(ctx: ListControllerContext<TResources>, resource: TName, options?: ListControllerOptions): ListController<RecordOf<TResources, TName>>;

package/dist/controller/list-controller.js

@@ -121,6 +121,22 @@ function resetPageTarget(s) {
   if (s.page > 1 && s.data !== void 0 && s.data.length === 0) return 1;
   return void 0;
 }
+function listControllerActions(controller) {
+  return {
+    setPage: controller.setPage,
+    setPerPage: controller.setPerPage,
+    setSort: controller.setSort,
+    setFilters: controller.setFilters,
+    setParams: controller.setParams,
+    showFilter: controller.showFilter,
+    hideFilter: controller.hideFilter,
+    select: controller.select,
+    toggleItem: controller.toggleItem,
+    unselectAll: controller.unselectAll,
+    selectAll: controller.selectAll,
+    refetch: controller.refetch
+  };
+}
 function createListController(ctx, resource, options = {}) {
   const storeKey = options.storeKey === false ? null : options.storeKey ?? resource;
   const paramsKey = storeKey ? `${storeKey}.listParams` : null;
@@ -377,6 +393,7 @@ function createListController(ctx, resource, options = {}) {
   }
   return {
     ...store,
+    defaultPerPage: defaults.perPage,
     setPage,
     setPerPage,
     setSort,
@@ -397,6 +414,7 @@ export {
   createErrorAnnouncer,
   createListController,
   errorMessageKey,
+  listControllerActions,
   listParamsFromPatch,
   notifyFetchError,
   notifySelectAllLimit,

package/dist/data/undoable.d.ts

@@ -1,4 +1,7 @@
 import { type QueryClient, type QueryKey } from "@tanstack/query-core";
+import type { Identifier } from "../resource/identifier.js";
+import type { ResourceRecord } from "../resource/record.js";
+import type { DeleteParams, UpdateManyParams, UpdateParams } from "./types.js";
 /**
  * A snapshot of the query cache taken BEFORE an optimistic apply: an array of
  * `[query key, data-at-that-key]` tuples. Rolling back writes each value back.
@@ -57,6 +60,53 @@ export interface UndoableHandle<TResult = unknown> {
  * `commit()` settle it. React/Vue-free — pure query-core.
  */
 export declare function startUndoableMutation<TResult = unknown>(config: UndoableMutationConfig<TResult>): UndoableHandle<TResult>;
+/**
+ * The callbacks an undoable `mutate` takes as its second argument. They are
+ * not TanStack Query's: the server call is deferred, so `onSuccess` fires with
+ * the optimistic result and `onError`/`onSettled` follow the deferred commit.
+ */
+export interface UndoableCallbacks<TData, TParams> {
+    /** Runs right after the optimistic cache change, not after the undo window. */
+    onSuccess?: (data: TData, params: TParams) => void;
+    /** Runs when the deferred commit fails, after the rollback and error notification. */
+    onError?: (error: unknown, params: TParams) => void;
+    /** Runs once the commit ends, whether it succeeded or failed. Never after an Undo. */
+    onSettled?: (params: TParams) => void;
+}
+/** What an undoable `useUpdate` hands `onSuccess`: the patched record. */
+export type UndoableUpdateCallbacks<TRecord extends ResourceRecord> = UndoableCallbacks<TRecord, UpdateParams<TRecord>>;
+/** What an undoable `useDelete` hands `onSuccess`: the previous record, when given. */
+export type UndoableDeleteCallbacks<TRecord extends ResourceRecord> = UndoableCallbacks<TRecord | undefined, DeleteParams<TRecord>>;
+/** What an undoable `useUpdateMany` hands `onSuccess`: the ids. */
+export type UndoableUpdateManyCallbacks<TRecord extends ResourceRecord> = UndoableCallbacks<Identifier[], UpdateManyParams<TRecord>>;
+/** The calls an undoable `mutate` makes for its callbacks; see {@link undoableCallbacks}. */
+export interface UndoableSettler<TData> {
+    /** Wraps the deferred `commit` so `onError` and `onSettled` run when it ends. */
+    commit<TResult>(commit: () => Promise<TResult>): () => Promise<TResult>;
+    /** Runs `onSuccess`: call it once the optimistic change is applied. */
+    success(data: TData): void;
+}
+/**
+ * Bind an undoable `mutate`'s callbacks to its `params`. The wrapped commit
+ * rethrows a failure, so the handle still rolls back and the adapter still
+ * notifies; the callbacks wait a macrotask to run after both.
+ */
+export declare function undoableCallbacks<TData, TParams>(params: TParams, callbacks?: UndoableCallbacks<TData, TParams>): UndoableSettler<TData>;
+/** What an adapter's `runUndoable` needs besides the deferred `commit`. */
+export interface UndoableCacheOptions {
+    queryKeys: QueryKey[];
+    applyOptimistic: () => void;
+    message: string;
+    messageArgs: {
+        smart_count: number;
+    };
+}
+/** Patch `ids` in the `resource` caches now; the notification reads "updated". */
+export declare function undoableUpdateOptions(queryClient: QueryClient, resource: string, ids: Identifier[], data: object): UndoableCacheOptions;
+/** Remove `ids` from the `resource` caches now; the notification reads "deleted". */
+export declare function undoableDeleteOptions(queryClient: QueryClient, resource: string, ids: Identifier[]): UndoableCacheOptions;
+/** The record an undoable update shows at once: the previous one with the patch on top. */
+export declare function patchedRecord<TRecord extends ResourceRecord>(params: UpdateParams<TRecord>): TRecord;
 /** True while at least one undoable mutation is still awaiting commit/undo. */
 export declare function hasPendingUndoables(): boolean;
 /** True while an undoable is pending or its committed server call is still in flight. */

package/dist/data/undoable.js

@@ -1,4 +1,5 @@
 import { partialMatchKey } from "@tanstack/query-core";
+import { removeRecordsFromCache, updateRecordsInCache } from "./cache-ops.js";
 const pendingUndoables = /* @__PURE__ */ new Set();
 const settledListeners = /* @__PURE__ */ new Set();
 let inFlightCommits = 0;
@@ -23,10 +24,10 @@ function keysOverlap(a, b) {
     (x) => b.some((y) => partialMatchKey(x, y) || partialMatchKey(y, x))
   );
 }
-function entriesToReplay(later, entry) {
+function entriesToReplay(later2, entry) {
   const affectedKeys = [...entry.queryKeys];
   const affected = [];
-  for (const other of later) {
+  for (const other of later2) {
     if (!keysOverlap(affectedKeys, other.queryKeys)) continue;
     affected.push(other);
     affectedKeys.push(...other.queryKeys);
@@ -59,12 +60,12 @@ function startUndoableMutation(config) {
   const rollback = () => {
     const open = order;
     const index = open.indexOf(entry);
-    const later = entriesToReplay(open.slice(index + 1), entry);
+    const later2 = entriesToReplay(open.slice(index + 1), entry);
     open.splice(index, 1);
-    for (const other of [...later].reverse())
+    for (const other of [...later2].reverse())
       restore(queryClient, other.snapshot);
     restore(queryClient, entry.snapshot);
-    for (const other of later) {
+    for (const other of later2) {
       other.snapshot = takeSnapshot(queryClient, other.queryKeys);
       other.applyOptimistic();
     }
@@ -111,6 +112,61 @@ function startUndoableMutation(config) {
   pendingUndoables.add(handle);
   return handle;
 }
+function later(run) {
+  setTimeout(() => {
+    try {
+      run();
+    } catch (error) {
+      console.error(error);
+    }
+  }, 0);
+}
+function undoableCallbacks(params, callbacks = {}) {
+  const { onSuccess, onError, onSettled } = callbacks;
+  return {
+    success: (data) => onSuccess?.(data, params),
+    // The callbacks run in a timer, never inside the commit's promise: one that
+    // throws must not read as a failed commit and roll the cache back.
+    commit: (commit) => async () => {
+      let result;
+      try {
+        result = await commit();
+      } catch (error) {
+        later(() => {
+          onError?.(error, params);
+          onSettled?.(params);
+        });
+        throw error;
+      }
+      later(() => onSettled?.(params));
+      return result;
+    }
+  };
+}
+function undoableUpdateOptions(queryClient, resource, ids, data) {
+  return {
+    queryKeys: [[resource]],
+    applyOptimistic: () => updateRecordsInCache(
+      queryClient,
+      resource,
+      ids,
+      data
+    ),
+    message: "chelone.notification.updated",
+    messageArgs: { smart_count: ids.length }
+  };
+}
+function undoableDeleteOptions(queryClient, resource, ids) {
+  return {
+    queryKeys: [[resource]],
+    applyOptimistic: () => removeRecordsFromCache(queryClient, resource, ids),
+    message: "chelone.notification.deleted",
+    messageArgs: { smart_count: ids.length }
+  };
+}
+function patchedRecord(params) {
+  return { ...params.previousData, ...params.data, id: params.id };
+}
 function hasPendingUndoables() {
   return pendingUndoables.size > 0;
 }
@@ -132,5 +188,9 @@ export {
   hasPendingUndoables,
   hasUnsettledUndoables,
   onUndoablesSettled,
-  startUndoableMutation
+  patchedRecord,
+  startUndoableMutation,
+  undoableCallbacks,
+  undoableDeleteOptions,
+  undoableUpdateOptions
 };

package/dist/index.d.ts

@@ -22,7 +22,7 @@ export { isFilterSelected, toggleFilterValue, } from "./controller/filter-toggle
 export type { InfiniteListController, InfiniteListControllerState, } from "./controller/infinite-list-controller.js";
 export { createInfiniteListController } from "./controller/infinite-list-controller.js";
 export type { ListController, ListControllerContext, ListControllerOptions, ListControllerState, ListParamsPatch, } from "./controller/list-controller.js";
-export { createListController } from "./controller/list-controller.js";
+export { createListController, listControllerActions, } from "./controller/list-controller.js";
 export type { ListParamsQuery, ListUrlState, } from "./controller/list-params.js";
 export { hasCustomParams, listPatchFromSearch, parseListParams, serializeListParams, serializeListState, } from "./controller/list-params.js";
 export type { PrevNextOptions, PrevNextPage, PrevNextParams, PrevNextResolution, PrevNextStoredParams, } from "./controller/prev-next.js";
@@ -61,8 +61,8 @@ export { createMutationOptions, deleteMutationOptions, updateMutationOptions, }
 export type { DataContext } from "./data/query-options.js";
 export { getInfiniteListOptions, getListOptions, getManyOptions, getManyReferenceOptions, getOneOptions, } from "./data/query-options.js";
 export type { CreateParams, CreateResult, CursorPagination, DataProvider, DeleteManyParams, DeleteManyResult, DeleteParams, DeleteResult, FilterPayload, GetListParams, GetListResult, GetManyParams, GetManyReferenceParams, GetManyReferenceResult, GetManyResult, GetOneParams, GetOneResult, InfiniteListParams, PageInfo, PagePagination, Pagination, SortPayload, UpdateManyParams, UpdateManyResult, UpdateParams, UpdateResult, } from "./data/types.js";
-export type { UndoableHandle, UndoableMutationConfig, UndoableSnapshot, } from "./data/undoable.js";
-export { commitAllUndoables, hasPendingUndoables, startUndoableMutation, } from "./data/undoable.js";
+export type { UndoableCacheOptions, UndoableCallbacks, UndoableDeleteCallbacks, UndoableHandle, UndoableMutationConfig, UndoableSettler, UndoableSnapshot, UndoableUpdateCallbacks, UndoableUpdateManyCallbacks, } from "./data/undoable.js";
+export { commitAllUndoables, hasPendingUndoables, patchedRecord, startUndoableMutation, undoableCallbacks, undoableDeleteOptions, undoableUpdateOptions, } from "./data/undoable.js";
 export type { LifecycleCallbacks, LifecycleHandler, } from "./data/with-lifecycle-callbacks.js";
 export { withLifecycleCallbacks } from "./data/with-lifecycle-callbacks.js";
 export type { ApplicationUpdateSnapshot, ApplicationUpdateStoreOptions, } from "./environment/application-update-store.js";

package/dist/index.js

@@ -10,7 +10,7 @@ import { createClientListController } from "./controller/client-list-controller.
 import { arrangeColumns, columnLabelMatches, dataTableColumnKeys, defaultDataTableStoreKey, getDataTableColumnId, moveColumn, toggleHiddenColumn } from "./controller/data-table-columns.js";
 import { isFilterSelected, toggleFilterValue } from "./controller/filter-toggle.js";
 import { createInfiniteListController } from "./controller/infinite-list-controller.js";
-import { createListController } from "./controller/list-controller.js";
+import { createListController, listControllerActions } from "./controller/list-controller.js";
 import { hasCustomParams, listPatchFromSearch, parseListParams, serializeListParams, serializeListState } from "./controller/list-params.js";
 import { canUseCachedPage, getPrevNextParams, resolvePrevNext } from "./controller/prev-next.js";
 import { createCreateController, createDeleteController, createEditController, createShowController } from "./controller/record-controllers.js";
@@ -36,7 +36,7 @@ import { HttpError } from "./data/http-error.js";
 import { infiniteListKey, listKey, lockKey, locksKey, manyKey, manyReferenceKey, oneKey, resourceKey } from "./data/keys.js";
 import { createMutationOptions, deleteMutationOptions, updateMutationOptions } from "./data/mutation-options.js";
 import { getInfiniteListOptions, getListOptions, getManyOptions, getManyReferenceOptions, getOneOptions } from "./data/query-options.js";
-import { commitAllUndoables, hasPendingUndoables, startUndoableMutation } from "./data/undoable.js";
+import { commitAllUndoables, hasPendingUndoables, patchedRecord, startUndoableMutation, undoableCallbacks, undoableDeleteOptions, undoableUpdateOptions } from "./data/undoable.js";
 import { withLifecycleCallbacks } from "./data/with-lifecycle-callbacks.js";
 import { createApplicationUpdateStore } from "./environment/application-update-store.js";
 import { createOfflineStore } from "./environment/offline-store.js";
@@ -246,6 +246,7 @@ export {
   joinBasename,
   latLngToLngLat,
   latitude,
+  listControllerActions,
   listKey,
   listPatchFromSearch,
   lngLatToLatLng,
@@ -283,6 +284,7 @@ export {
   parseCsvWith,
   parseListParams,
   parseLocation,
+  patchedRecord,
   permissionsQueryOptions,
   polygonToBBox,
   presenceTopic,
@@ -330,6 +332,9 @@ export {
   toPresenceUser,
   toggleFilterValue,
   toggleHiddenColumn,
+  undoableCallbacks,
+  undoableDeleteOptions,
+  undoableUpdateOptions,
   unreadKey,
   updateMutationOptions,
   updateRecordsInCache,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chelone/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "repository": {
     "type": "git",