@craft-ts/core 0.7.0-beta.13

package/src/lib/insert-entities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insert-entities.d.ts","sourceRoot":"","sources":["../../../../../libs/core/src/lib/insert-entities.ts"],"names":[],"mappings":"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"}

package/src/lib/insert-entities.js

@@ -0,0 +1,159 @@
+import { createNestedStateUpdate, getNestedStateValue, } from './util/update-state.util';
+/**
+ * Creates an insertion that adds entity collection management methods to state, query, or queryParams primitives.
+ *
+ * Provides type-safe manipulation of arrays of entities with operations like add, remove, update, and upsert.
+ * Supports nested properties via dot notation paths and custom entity identifiers.
+ *
+ * @template State - The state type (array or object containing arrays)
+ * @template K - The type of entity identifiers (string or number)
+ * @template PreviousInsertionsOutputs - Combined outputs from previous insertions
+ * @template EntityHelperFns - Tuple type of entity utility functions to expose
+ * @template StateIdentifier - Type of identifier function for parallel queries
+ * @template Path - Dot-notation path to nested array (inferred from state structure)
+ *
+ * @param config - Configuration object
+ * @param config.methods - Array of entity utility functions (addOne, removeOne, updateOne, etc.) to expose as methods
+ * @param config.identifier - Optional custom function to extract unique ID from entities.
+ *                            Defaults to `entity.id` for objects or `entity` for primitives
+ * @param config.path - Optional dot-notation path to nested array property (e.g., 'catalog.products').
+ *                      Method names are prefixed with camelCase path when provided
+ *
+ * @returns Insertion function that adds entity management methods to the primitive
+ *
+ * @example
+ * // Basic usage with primitives
+ * const tags = yield* state(
+ *   [] as string[],
+ *   insertEntities({
+ *     methods: [addOne, addMany, removeOne],
+ *   })
+ * ));
+ * yield* tags.addOne({ entity: 'typescript' });
+ * yield* tags.addMany({ newEntities: ['angular', 'signals'] });
+ *
+ * @example
+ * // With objects having default id property
+ * interface Product {
+ *   id: string;
+ *   name: string;
+ *   price: number;
+ * }
+ * const products = yield* state(
+ *   [] as Product[],
+ *   insertEntities({
+ *     methods: [addOne, setOne, removeOne],
+ *   })
+ * ));
+ * yield* products.addOne({ entity: { id: '1', name: 'Laptop', price: 999 } });
+ *
+ * @example
+ * // With custom identifier
+ * interface User {
+ *   uuid: string;
+ *   name: string;
+ * }
+ * const users = yield* state(
+ *   [] as User[],
+ *   insertEntities({
+ *     methods: [setOne, removeOne],
+ *     identifier: (user) => user.uuid,
+ *   })
+ * ));
+ *
+ * @example
+ * // With nested path
+ * interface Catalog {
+ *   total: number;
+ *   products: Array<{ id: string; name: string }>;
+ * }
+ * const catalog = yield* state(
+ *   { total: 0, products: [] } as Catalog,
+ *   insertEntities({
+ *     methods: [addMany, removeOne],
+ *     path: 'products',
+ *   })
+ * ));
+ * yield* catalog.productsAddMany({ newEntities: [{ id: '1', name: 'Item' }] });
+ *
+ * @example
+ * // With parallel queries
+ * const userQuery = yield* query(
+ *   {
+ *     params: () => 'userId',
+ *     identifier: (params) => params,
+ *     loader: async ({ params }) => fetchUserPosts(params),
+ *   },
+ *   insertEntities({
+ *     methods: [addOne],
+ *   })
+ * ));
+ * yield* userQuery.addOne({
+ *   select: 'user-123', // Target specific query instance
+ *   entity: { id: 'post-1', title: 'New Post' },
+ * });
+ *
+ * @see {@link https://github.com/craft-ts/craft-ts/blob/main/apps/docs/insertions/insert-entities.md | insertEntities Documentation}
+ */
+export function insertEntities(config) {
+    return (context) => {
+        const methods = {};
+        const hasPath = 'path' in config;
+        const path = hasPath ? config.path : undefined;
+        const pathKeys = path ? path.split('.') : undefined;
+        const pathMethodPrefix = pathKeys
+            ? pathKeys.reduce((acc, key, index) => index === 0 ? key : `${acc}${key[0].toUpperCase()}${key.slice(1)}`, '')
+            : undefined;
+        for (const helperFn of config.methods) {
+            const helperName = helperFn.name;
+            if (!helperName) {
+                continue;
+            }
+            const methodName = hasPath
+                ? `${pathMethodPrefix}${helperName[0].toUpperCase()}${helperName.slice(1)}`
+                : helperName;
+            methods[methodName] = (payload) => {
+                context.update((state) => {
+                    const hasSelect = 'select' in payload && payload.select;
+                    const targetState = hasSelect
+                        ? state[payload.select]
+                        : state;
+                    const entities = pathKeys
+                        ? getNestedStateValue({
+                            state: targetState,
+                            keysPath: pathKeys,
+                        })
+                        : targetState;
+                    const updatedEntities = helperFn({
+                        ...payload,
+                        entities,
+                        identifier: config.identifier,
+                    });
+                    if (hasSelect) {
+                        const updatedTargetState = pathKeys
+                            ? createNestedStateUpdate({
+                                state: targetState,
+                                keysPath: pathKeys,
+                                value: updatedEntities,
+                            })
+                            : updatedEntities;
+                        return {
+                            ...state,
+                            [payload.select]: updatedTargetState,
+                        };
+                    }
+                    if (pathKeys) {
+                        return createNestedStateUpdate({
+                            state,
+                            keysPath: pathKeys,
+                            value: updatedEntities,
+                        });
+                    }
+                    return updatedEntities;
+                });
+            };
+        }
+        return methods;
+    };
+}
+//# sourceMappingURL=insert-entities.js.map

package/src/lib/insert-entities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"insert-entities.js","sourceRoot":"","sources":["../../../../../libs/core/src/lib/insert-entities.ts"],"names":[],"mappings":"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","sourcesContent":["import { InsertionStateFactoryContext } from './query.core';\nimport { EntitiesUtilBrand, IdSelector } from './util/entities-util';\nimport {\n  AccessTypeObjectPropertyByDottedPath,\n  DottedPathPathToTuple,\n} from './util/types/access-type-object-property-by-dotted-path.type';\nimport {\n  createNestedStateUpdate,\n  getNestedStateValue,\n} from './util/update-state.util';\nimport { ObjectDeepPath } from './util/types/object-deep-path-mapper.type';\nimport { MergeObject, Prettify } from './util/util.type';\n\ntype ArrayObjectDeepPath<State extends object> =\n  ObjectDeepPath<State> extends infer Path\n    ? Path extends string\n      ? AccessTypeObjectPropertyByDottedPath<\n          State,\n          DottedPathPathToTuple<Path>\n        > extends Array<any>\n        ? Path\n        : never\n      : never\n    : never;\n\ntype DottedPathToCamel<Path extends string> =\n  Path extends `${infer Head}.${infer Tail}`\n    ? `${Head}${Capitalize<DottedPathToCamel<Tail>>}`\n    : Path;\n\ntype EntitiesUtilsToMap<\n  EntityHelperFns,\n  Entity,\n  K,\n  HasStateIdentifier,\n  StateIdentifier,\n  HasPath,\n  Path,\n  Acc = {},\n> = EntityHelperFns extends [infer First, ...infer Rest]\n  ? First extends (data: infer Payload) => infer R\n    ? R extends EntitiesUtilBrand<infer Name>\n      ? EntitiesUtilsToMap<\n          Rest,\n          Entity,\n          K,\n          HasStateIdentifier,\n          StateIdentifier,\n          HasPath,\n          Path,\n          Acc & {\n            [key in Name as `${HasPath extends true ? `${DottedPathToCamel<Path & string>}${Capitalize<string & key>}` : key & string}`]: (\n              payload: MergeObject<\n                {\n                  [key in Exclude<\n                    keyof Payload,\n                    'identifier'\n                  > as `${key extends 'entities' ? never : key & string}`]: key extends 'entity'\n                    ? Entity\n                    : key extends 'ids'\n                      ? K[]\n                      : key extends 'newEntities'\n                        ? Entity[]\n                        : `Not implemented mapping for ${key & string}`;\n                },\n                HasStateIdentifier extends true\n                  ? {\n                      select: StateIdentifier extends (...args: any) => infer R\n                        ? R\n                        : never;\n                    }\n                  : {}\n              >,\n            ) => void;\n          }\n        >\n      : 'No EntitiesBranded Name Detected'\n    : false\n  : Acc;\n\n/**\n * Creates an insertion that adds entity collection management methods to state, query, or queryParams primitives.\n *\n * Provides type-safe manipulation of arrays of entities with operations like add, remove, update, and upsert.\n * Supports nested properties via dot notation paths and custom entity identifiers.\n *\n * @template State - The state type (array or object containing arrays)\n * @template K - The type of entity identifiers (string or number)\n * @template PreviousInsertionsOutputs - Combined outputs from previous insertions\n * @template EntityHelperFns - Tuple type of entity utility functions to expose\n * @template StateIdentifier - Type of identifier function for parallel queries\n * @template Path - Dot-notation path to nested array (inferred from state structure)\n *\n * @param config - Configuration object\n * @param config.methods - Array of entity utility functions (addOne, removeOne, updateOne, etc.) to expose as methods\n * @param config.identifier - Optional custom function to extract unique ID from entities.\n *                            Defaults to `entity.id` for objects or `entity` for primitives\n * @param config.path - Optional dot-notation path to nested array property (e.g., 'catalog.products').\n *                      Method names are prefixed with camelCase path when provided\n *\n * @returns Insertion function that adds entity management methods to the primitive\n *\n * @example\n * // Basic usage with primitives\n * const tags = yield* state(\n *   [] as string[],\n *   insertEntities({\n *     methods: [addOne, addMany, removeOne],\n *   })\n * ));\n * yield* tags.addOne({ entity: 'typescript' });\n * yield* tags.addMany({ newEntities: ['angular', 'signals'] });\n *\n * @example\n * // With objects having default id property\n * interface Product {\n *   id: string;\n *   name: string;\n *   price: number;\n * }\n * const products = yield* state(\n *   [] as Product[],\n *   insertEntities({\n *     methods: [addOne, setOne, removeOne],\n *   })\n * ));\n * yield* products.addOne({ entity: { id: '1', name: 'Laptop', price: 999 } });\n *\n * @example\n * // With custom identifier\n * interface User {\n *   uuid: string;\n *   name: string;\n * }\n * const users = yield* state(\n *   [] as User[],\n *   insertEntities({\n *     methods: [setOne, removeOne],\n *     identifier: (user) => user.uuid,\n *   })\n * ));\n *\n * @example\n * // With nested path\n * interface Catalog {\n *   total: number;\n *   products: Array<{ id: string; name: string }>;\n * }\n * const catalog = yield* state(\n *   { total: 0, products: [] } as Catalog,\n *   insertEntities({\n *     methods: [addMany, removeOne],\n *     path: 'products',\n *   })\n * ));\n * yield* catalog.productsAddMany({ newEntities: [{ id: '1', name: 'Item' }] });\n *\n * @example\n * // With parallel queries\n * const userQuery = yield* query(\n *   {\n *     params: () => 'userId',\n *     identifier: (params) => params,\n *     loader: async ({ params }) => fetchUserPosts(params),\n *   },\n *   insertEntities({\n *     methods: [addOne],\n *   })\n * ));\n * yield* userQuery.addOne({\n *   select: 'user-123', // Target specific query instance\n *   entity: { id: 'post-1', title: 'New Post' },\n * });\n *\n * @see {@link https://github.com/craft-ts/craft-ts/blob/main/apps/docs/insertions/insert-entities.md | insertEntities Documentation}\n */\nexport function insertEntities<\n  State,\n  K extends string | number,\n  PreviousInsertionsOutputs,\n  const EntityHelperFns extends unknown[],\n  StateIdentifier,\n  const Path = State extends Array<infer Entity>\n    ? never\n    : State extends object\n      ? ArrayObjectDeepPath<State>\n      : never,\n  StateType = State extends Array<infer R>\n    ? R\n    : State extends object\n      ? Path extends string\n        ? AccessTypeObjectPropertyByDottedPath<\n            State,\n            DottedPathPathToTuple<Path>\n          > extends Array<infer Entity>\n          ? Entity\n          : never\n        : never\n      : never,\n  HasStateIdentifier = [unknown] extends [StateIdentifier]\n    ? false\n    : StateIdentifier extends (...args: any) => infer R\n      ? [unknown] extends [R]\n        ? false\n        : true\n      : false,\n  IsEntityIdentifierOptional = StateType extends { id: NoInfer<K> }\n    ? true\n    : StateType extends string | number\n      ? true\n      : false,\n>(\n  config: {\n    methods: EntityHelperFns;\n  } & MergeObject<\n    IsEntityIdentifierOptional extends true\n      ? {\n          identifier?: IdSelector<NoInfer<StateType>, NoInfer<K>>;\n        }\n      : {\n          identifier: IdSelector<NoInfer<StateType>, NoInfer<K>>;\n        },\n    [Path] extends [never]\n      ? {}\n      : {\n          path: Path;\n        }\n  >,\n) {\n  return (\n    context: InsertionStateFactoryContext<State, PreviousInsertionsOutputs> & {\n      identifier?: StateIdentifier;\n    },\n  ) => {\n    const methods: Record<string, (payload: unknown) => void> = {};\n    const hasPath = 'path' in config;\n    const path = hasPath ? (config as { path: string }).path : undefined;\n    const pathKeys = path ? path.split('.') : undefined;\n    const pathMethodPrefix = pathKeys\n      ? pathKeys.reduce(\n          (acc, key, index) =>\n            index === 0 ? key : `${acc}${key[0].toUpperCase()}${key.slice(1)}`,\n          '',\n        )\n      : undefined;\n\n    for (const helperFn of config.methods as Array<\n      ((data: Record<string, unknown>) => StateType[]) & { name: string }\n    >) {\n      const helperName = helperFn.name;\n      if (!helperName) {\n        continue;\n      }\n      const methodName = hasPath\n        ? `${pathMethodPrefix}${helperName[0].toUpperCase()}${helperName.slice(1)}`\n        : helperName;\n\n      methods[methodName] = (payload: any) => {\n        context.update((state) => {\n          const hasSelect = 'select' in payload && payload.select;\n          const targetState = hasSelect\n            ? (state as any)[payload.select as number]\n            : state;\n          const entities = pathKeys\n            ? getNestedStateValue({\n                state: targetState,\n                keysPath: pathKeys,\n              })\n            : targetState;\n          const updatedEntities = helperFn({\n            ...(payload as Record<string, unknown>),\n            entities,\n            identifier: config.identifier,\n          });\n\n          if (hasSelect) {\n            const updatedTargetState = pathKeys\n              ? createNestedStateUpdate({\n                  state: targetState,\n                  keysPath: pathKeys,\n                  value: updatedEntities,\n                })\n              : updatedEntities;\n            return {\n              ...(state as any),\n              [payload.select as number]: updatedTargetState,\n            } as any;\n          }\n\n          if (pathKeys) {\n            return createNestedStateUpdate({\n              state,\n              keysPath: pathKeys,\n              value: updatedEntities,\n            });\n          }\n\n          return updatedEntities;\n        });\n      };\n    }\n    return methods as Prettify<\n      EntitiesUtilsToMap<\n        EntityHelperFns,\n        StateType,\n        K,\n        HasStateIdentifier,\n        StateIdentifier,\n        'path' extends keyof typeof config ? true : false,\n        Path\n      >\n    > & {\n      testState: State;\n      testPath: Path;\n      testHasPath: 'path' extends keyof typeof config ? true : false;\n    };\n  };\n}\n"]}

package/src/lib/insert-noop-typing-anchor.d.ts

@@ -0,0 +1,15 @@
+import type { InsertionStateFactoryContext } from './query.core';
+/**
+ * No-op insertion used to preserve contextual typing in insertion chains of
+ * the form-tree helpers (`insertForm` / `insertSelectFormTree`), which keep a
+ * variadic signature.
+ *
+ * Usage:
+ * `insertSelectFormTree('name', insertNoopTypingAnchor, insertFormAttributes(...))`
+ *
+ * It is NOT needed with `insertSelect`: use
+ * `insertSelect('grid', (gridContext) => craftPipe(gridContext, ...))`,
+ * which preserves nested contextual typing by itself.
+ */
+export declare function insertNoopTypingAnchor<StateType, PreviousInsertionsOutputs = {}>(_context: InsertionStateFactoryContext<StateType, PreviousInsertionsOutputs>): {};
+//# sourceMappingURL=insert-noop-typing-anchor.d.ts.map

package/src/lib/insert-noop-typing-anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insert-noop-typing-anchor.d.ts","sourceRoot":"","sources":["../../../../../libs/core/src/lib/insert-noop-typing-anchor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAC;AAEjE;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EACT,yBAAyB,GAAG,EAAE,EAE9B,QAAQ,EAAE,4BAA4B,CAAC,SAAS,EAAE,yBAAyB,CAAC,GAC3E,EAAE,CAEJ"}

package/src/lib/insert-noop-typing-anchor.js

@@ -0,0 +1,16 @@
+/**
+ * No-op insertion used to preserve contextual typing in insertion chains of
+ * the form-tree helpers (`insertForm` / `insertSelectFormTree`), which keep a
+ * variadic signature.
+ *
+ * Usage:
+ * `insertSelectFormTree('name', insertNoopTypingAnchor, insertFormAttributes(...))`
+ *
+ * It is NOT needed with `insertSelect`: use
+ * `insertSelect('grid', (gridContext) => craftPipe(gridContext, ...))`,
+ * which preserves nested contextual typing by itself.
+ */
+export function insertNoopTypingAnchor(_context) {
+    return {};
+}
+//# sourceMappingURL=insert-noop-typing-anchor.js.map

package/src/lib/insert-noop-typing-anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"insert-noop-typing-anchor.js","sourceRoot":"","sources":["../../../../../libs/core/src/lib/insert-noop-typing-anchor.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAIpC,QAA4E;IAE5E,OAAO,EAAE,CAAC;AACZ,CAAC","sourcesContent":["import type { InsertionStateFactoryContext } from './query.core';\n\n/**\n * No-op insertion used to preserve contextual typing in insertion chains of\n * the form-tree helpers (`insertForm` / `insertSelectFormTree`), which keep a\n * variadic signature.\n *\n * Usage:\n * `insertSelectFormTree('name', insertNoopTypingAnchor, insertFormAttributes(...))`\n *\n * It is NOT needed with `insertSelect`: use\n * `insertSelect('grid', (gridContext) => craftPipe(gridContext, ...))`,\n * which preserves nested contextual typing by itself.\n */\nexport function insertNoopTypingAnchor<\n  StateType,\n  PreviousInsertionsOutputs = {},\n>(\n  _context: InsertionStateFactoryContext<StateType, PreviousInsertionsOutputs>,\n): {} {\n  return {};\n}\n"]}

package/src/lib/insert-pagination-placeholder-data.d.ts

@@ -0,0 +1,122 @@
+import { Signal } from './host/craft-compat';
+import { type CraftSettledBrand } from './craft-settled';
+import { InsertionByIdParams, ResourceExceptionConstraints, YieldableInsertionWrite } from './query.core';
+import { CraftResourceStatus } from './util/craft-resource-status';
+import { type YieldableReactiveValue } from './reactive-read';
+/**
+ * Base outputs produced by {@link insertPaginationPlaceholderData}.
+ *
+ * - `currentPageData`: the current page data, or the previous page data while the
+ *   next page is loading (placeholder). Never `undefined`: falls back to `initialValue`.
+ * - `currentPageStatus`: the `CraftResourceStatus` of the current page.
+ * - `isPlaceHolderData`: whether placeholder (previous page) data is currently shown.
+ * - `currentIdentifier`: the identifier of the current page.
+ */
+export type PaginationBaseOutputs<PageState, PrimitiveName extends string = string, SettledExceptions = never> = {
+    currentPageData: Signal<PageState>;
+    currentPageStatus: YieldableReactiveValue<CraftResourceStatus, 'currentPageStatus'> & CraftSettledBrand<PrimitiveName, SettledExceptions>;
+    isPlaceHolderData: Signal<boolean>;
+    currentIdentifier: Signal<string>;
+};
+type PublicPaginationBaseOutputs<PageState, PrimitiveName extends string = string, SettledExceptions = never> = {
+    currentPageData: YieldableReactiveValue<PageState, 'currentPageData'>;
+    currentPageStatus: YieldableReactiveValue<CraftResourceStatus, 'currentPageStatus'> & CraftSettledBrand<PrimitiveName, SettledExceptions>;
+    isPlaceHolderData: YieldableReactiveValue<boolean, 'isPlaceHolderData'>;
+    currentIdentifier: YieldableReactiveValue<string, 'currentIdentifier'>;
+};
+/**
+ * Passthrough pieces of the underlying insertion context exposed to the `build` callback.
+ */
+type PaginationContextPassthrough<PageState, PrimitiveName extends string = string, Exceptions extends ResourceExceptionConstraints = ResourceExceptionConstraints> = Pick<InsertionByIdParams<string, PageState & object, unknown, Exceptions, {}, PrimitiveName>, 'resourceById' | 'resourceParamsSrc' | 'identifier' | 'hasException' | 'exceptions' | 'settledState'>;
+/**
+ * Context passed to the optional `build` callback of {@link insertPaginationPlaceholderData}.
+ *
+ * In addition to the base pagination outputs, it exposes helpers scoped to the
+ * **current page** (the data displayed), so custom computed/methods act on the
+ * page the user is looking at rather than the global `Record<id, State>`.
+ */
+export type PaginationBuildContext<PageState, PrimitiveName extends string = string, Exceptions extends ResourceExceptionConstraints = ResourceExceptionConstraints> = PublicPaginationBaseOutputs<PageState, PrimitiveName, Exceptions['params'] | Exceptions['loader']> & {
+    /**
+     * The data on screen: the current page's, or the previous page's while the
+     * current one loads. Matches what `currentPageData` renders, so a derived
+     * count cannot disagree with the visible rows.
+     */
+    state: YieldableReactiveValue<PageState, 'state'>;
+    /** Current page data only when the current page has settled; suspends otherwise. */
+    settledState: PaginationContextPassthrough<PageState, PrimitiveName, Exceptions>['settledState'];
+    /** Replace the current page data. No-op if the page is not loaded yet. */
+    set: YieldableInsertionWrite<[newValue: PageState], PageState>;
+    /** Update the current page data from its previous value. */
+    update: YieldableInsertionWrite<[
+        updateFn: (current: PageState) => PageState
+    ], PageState>;
+    /** Patch the current page data with a partial value. */
+    patch: YieldableInsertionWrite<[
+        patchFn: (current: PageState) => Partial<PageState>
+    ], PageState>;
+} & PaginationContextPassthrough<PageState, PrimitiveName, Exceptions>;
+/**
+ * Provides placeholder data during pagination transitions for a smoother user experience.
+ *
+ * When navigating between pages, this insertion shows the previous page's data while
+ * the new page is loading, avoiding empty states during transitions.
+ *
+ * It is a **higher-order insertion**: call it with a `config` (and an optional `build`
+ * callback) and pass the result to `query(...)`.
+ *
+ * - `config.initialValue` is both the default value **and** the type of a page: thanks to
+ *   it, `currentPageData` is a yieldable reader for `PageState` and is never `undefined`.
+ * - The optional `build` callback lets you attach custom outputs (computed/methods)
+ *   alongside the pagination outputs. Its helpers (`state`, `set`, `update`, `patch`)
+ *   are scoped to the **current page** (the displayed data), never the global record.
+ *
+ * @example
+ * ```typescript
+ * const pagination = signal(1);
+ *
+ * const userQuery = yield* query(
+ *   {
+ *     params: pagination,
+ *     identifier: (params) => '' + params,
+ *     loader: async ({ params: page }) => fetchUsers(page),
+ *   },
+ *   insertPaginationPlaceholderData({ initialValue: [] as User[] }),
+ * ));
+ *
+ * // Access the data (or placeholder during loading) — never undefined
+ * const data = yield* userQuery.currentPageData();
+ * ```
+ *
+ * @example
+ * With custom outputs via `build`:
+ * ```typescript
+ * const usersQuery = yield* query(
+ *   {
+ *     params: pagination,
+ *     identifier: (params) => `${params.page}-${params.pageSize}`,
+ *     loader: function* ({ params }) {
+ *       return yield* ApiService.getDataList(params);
+ *     },
+ *   },
+ *   insertPaginationPlaceholderData(
+ *     { initialValue: [] as Data[] },
+ *     ({ state, set }) => ({
+ *       totalOfUnCompletedData: craftComputed(function* () {
+ *         return (yield* state()).filter((d) => !d.completed).length;
+ *       }),
+ *       markAsCompleted: function* (id: string) {
+ *         const current = yield* state();
+ *         return yield* set(
+ *           current.map((d) => (d.id === id ? { ...d, completed: true } : d)),
+ *         );
+ *       },
+ *     }),
+ *   ),
+ * ));
+ * ```
+ */
+export declare function insertPaginationPlaceholderData<PageState, ExtraOutputs extends Record<string, unknown> = {}>(config: {
+    initialValue: PageState;
+}, build?: (context: PaginationBuildContext<PageState>) => ExtraOutputs): <GroupIdentifier extends string, ResourceParams, Exceptions extends ResourceExceptionConstraints, PreviousInsertionsOutputs, PrimitiveName extends string>(context: InsertionByIdParams<GroupIdentifier, PageState & object, ResourceParams, Exceptions, NoInfer<PreviousInsertionsOutputs>, PrimitiveName>) => PaginationBaseOutputs<PageState, PrimitiveName, Exceptions["params"] | Exceptions["loader"]> & ExtraOutputs;
+export {};
+//# sourceMappingURL=insert-pagination-placeholder-data.d.ts.map

package/src/lib/insert-pagination-placeholder-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insert-pagination-placeholder-data.d.ts","sourceRoot":"","sources":["../../../../../libs/core/src/lib/insert-pagination-placeholder-data.ts"],"names":[],"mappings":"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"}

package/src/lib/insert-pagination-placeholder-data.js

@@ -0,0 +1,244 @@
+import { craftComputed } from './craft-computed';
+import { isGenerator } from './craft-generator-runtime';
+import { settled } from './craft-settled';
+import { toCraftStatus, } from './util/craft-resource-status';
+import { createYieldableReactiveFacade, rawReactiveFacade, } from './reactive-read';
+function* readPaginationReactive(reader) {
+    const value = reader();
+    return isGenerator(value) ? yield* value : value;
+}
+/**
+ * Provides placeholder data during pagination transitions for a smoother user experience.
+ *
+ * When navigating between pages, this insertion shows the previous page's data while
+ * the new page is loading, avoiding empty states during transitions.
+ *
+ * It is a **higher-order insertion**: call it with a `config` (and an optional `build`
+ * callback) and pass the result to `query(...)`.
+ *
+ * - `config.initialValue` is both the default value **and** the type of a page: thanks to
+ *   it, `currentPageData` is a yieldable reader for `PageState` and is never `undefined`.
+ * - The optional `build` callback lets you attach custom outputs (computed/methods)
+ *   alongside the pagination outputs. Its helpers (`state`, `set`, `update`, `patch`)
+ *   are scoped to the **current page** (the displayed data), never the global record.
+ *
+ * @example
+ * ```typescript
+ * const pagination = signal(1);
+ *
+ * const userQuery = yield* query(
+ *   {
+ *     params: pagination,
+ *     identifier: (params) => '' + params,
+ *     loader: async ({ params: page }) => fetchUsers(page),
+ *   },
+ *   insertPaginationPlaceholderData({ initialValue: [] as User[] }),
+ * ));
+ *
+ * // Access the data (or placeholder during loading) — never undefined
+ * const data = yield* userQuery.currentPageData();
+ * ```
+ *
+ * @example
+ * With custom outputs via `build`:
+ * ```typescript
+ * const usersQuery = yield* query(
+ *   {
+ *     params: pagination,
+ *     identifier: (params) => `${params.page}-${params.pageSize}`,
+ *     loader: function* ({ params }) {
+ *       return yield* ApiService.getDataList(params);
+ *     },
+ *   },
+ *   insertPaginationPlaceholderData(
+ *     { initialValue: [] as Data[] },
+ *     ({ state, set }) => ({
+ *       totalOfUnCompletedData: craftComputed(function* () {
+ *         return (yield* state()).filter((d) => !d.completed).length;
+ *       }),
+ *       markAsCompleted: function* (id: string) {
+ *         const current = yield* state();
+ *         return yield* set(
+ *           current.map((d) => (d.id === id ? { ...d, completed: true } : d)),
+ *         );
+ *       },
+ *     }),
+ *   ),
+ * ));
+ * ```
+ */
+export function insertPaginationPlaceholderData(config, build) {
+    // The returned factory is generic over the query's shape (GroupIdentifier,
+    // ResourceParams, Exceptions, PreviousInsertionsOutputs) so it adapts to any
+    // query and its context stays precisely typed. Note: since the primitives
+    // wrap every shape generic of their insertion slot in `NoInfer` (including
+    // `Exceptions`), a factory can no longer degrade the primitive's inference —
+    // the generic shape here is about the factory's own context typing. Only
+    // `ResourceState` is fixed, to `PageState` (inferred from `config.initialValue`).
+    return (context) => {
+        const { resourceById, resourceParamsSrc, identifier, hasException, exceptions, settledState, } = context;
+        /**
+         * The rows currently on screen, whichever page they came from.
+         *
+         * This used to be tracked as a previous page KEY, which could not survive
+         * the case it exists for: on a page change the incoming page has no
+         * resource yet, so there was no 'loading' status to recognise, the
+         * placeholder branch was skipped, and the key was overwritten with the new
+         * page before it could ever be used — the list blanked on every
+         * navigation. Holding the VALUE needs neither the old resource to still be
+         * cached nor the new one to exist yet.
+         */
+        let lastShownValue;
+        const currentPageValue = function* () {
+            const page = yield* readPaginationReactive(resourceParamsSrc);
+            const resources = (yield* readPaginationReactive(resourceById));
+            const pageKey = page != null ? identifier(page) : undefined;
+            return {
+                pageKey,
+                hasOwnValue: pageKey !== undefined && resources[pageKey]?.value() !== undefined,
+            };
+        };
+        const showPlaceHolderData = craftComputed('showPlaceHolderData', function* () {
+            const { pageKey, hasOwnValue } = yield* currentPageValue();
+            if (!pageKey) {
+                return false;
+            }
+            // Placeholder: the page in the URL has nothing of its own yet, and
+            // rows from an earlier one are still on screen.
+            return !hasOwnValue && lastShownValue !== undefined;
+        });
+        const currentPageData = craftComputed('currentPageData', function* () {
+            const { pageKey, hasOwnValue } = yield* currentPageValue();
+            if (pageKey !== undefined && hasOwnValue) {
+                const settled = (yield* settledState());
+                lastShownValue = settled;
+                return settled;
+            }
+            if (lastShownValue === undefined) {
+                const resources = (yield* readPaginationReactive(resourceById));
+                // A page can change before its rows were read (for example, a store
+                // test can wait only for the loader). Recover the most recently
+                // inserted resolved page so the placeholder still has something to
+                // display while the new page is loading.
+                for (const resource of Object.values(resources).reverse()) {
+                    const value = resource?.value();
+                    if (value !== undefined) {
+                        lastShownValue = value;
+                        break;
+                    }
+                }
+            }
+            // Nothing for this page yet: keep what is already on screen instead of
+            // blanking the list, which is the entire point of the placeholder.
+            return lastShownValue ?? config.initialValue;
+        });
+        const currentPageStatus = craftComputed('currentPageStatus', function* () {
+            const page = yield* readPaginationReactive(resourceParamsSrc);
+            const resources = (yield* readPaginationReactive(resourceById));
+            if (page == null) {
+                return 'idle'; // avoid to handle the undefined check
+            }
+            const pageKey = identifier(page);
+            const currentResource = resources[pageKey];
+            const currentExceptions = yield* readPaginationReactive(exceptions);
+            const hasCurrentPageException = Object.keys(currentExceptions.params ?? {}).length > 0 ||
+                currentExceptions.loader?.[pageKey] !== undefined;
+            // Status is also a settled read while the current page has no value.
+            // This makes the status binding suspend during the initial/page load,
+            // while preserving the visible exception status and stale status during
+            // reloads of an already resolved page.
+            if (!hasCurrentPageException && currentResource?.value() === undefined) {
+                yield* settled({ settledValue: settledState });
+            }
+            return toCraftStatus(currentResource?.status() ?? 'idle', hasCurrentPageException);
+        });
+        const currentIdentifier = craftComputed('currentIdentifier', function* () {
+            const page = yield* readPaginationReactive(resourceParamsSrc);
+            if (page == null) {
+                return '';
+            }
+            return identifier(page);
+        });
+        const baseOutputs = {
+            currentPageData,
+            currentPageStatus,
+            isPlaceHolderData: showPlaceHolderData,
+            currentIdentifier,
+        };
+        if (!build) {
+            return baseOutputs;
+        }
+        // Helpers scoped to the current page (the displayed data), not the global record.
+        const currentPageKey = () => {
+            const params = rawReactiveFacade(resourceParamsSrc)();
+            return params != null ? identifier(params) : undefined;
+        };
+        /**
+         * What the page in the URL holds by itself — no placeholder.
+         *
+         * Writes are anchored here rather than on `state`: `set` targets the
+         * current page, so basing an update on rows that still belong to the
+         * PREVIOUS one would compute the new value from the wrong page.
+         */
+        const currentPageOwnValue = () => {
+            const params = rawReactiveFacade(resourceParamsSrc)();
+            const resources = rawReactiveFacade(resourceById)();
+            const key = params != null ? identifier(params) : undefined;
+            const res = key ? resources[key] : undefined;
+            return res?.hasValue() ? res.value() : config.initialValue;
+        };
+        /**
+         * What the reader SEES, placeholder included — the same value the rows are
+         * rendered from.
+         *
+         * It used to report the current page's own data, which is `initialValue`
+         * for as long as that page is loading. Anything derived from it — a count,
+         * a summary — then contradicted the list still on screen: "0 on page"
+         * above four visible rows. `settledState` stays the strict reading for
+         * code that must wait for the page it actually asked for.
+         */
+        const state = craftComputed('state', function* () {
+            return yield* currentPageData();
+        });
+        const set = function* (newValue) {
+            const key = currentPageKey();
+            if (key) {
+                // Use the page's CraftResourceRef directly. Do NOT use resourceById.set({...}),
+                // which is destructive: it resets keys absent from the payload.
+                // No-op if the page is not loaded yet (we only act on a displayed page).
+                const resources = rawReactiveFacade(resourceById)();
+                resources[key]?.set(newValue);
+            }
+            return newValue;
+        };
+        const update = function* (updateFn) {
+            return yield* set(updateFn(currentPageOwnValue()));
+        };
+        const patch = function* (patchFn) {
+            return yield* update((current) => ({ ...current, ...patchFn(current) }));
+        };
+        const publicBaseOutputs = createYieldableReactiveFacade(baseOutputs, {
+            name: 'pagination',
+            primitive: 'insertPaginationPlaceholderData',
+            path: 'pagination',
+        });
+        const extra = build({
+            ...publicBaseOutputs,
+            state,
+            settledState,
+            set,
+            update,
+            patch,
+            resourceById,
+            resourceParamsSrc,
+            identifier,
+            hasException,
+            exceptions,
+        });
+        return {
+            ...baseOutputs,
+            ...extra,
+        };
+    };
+}
+//# sourceMappingURL=insert-pagination-placeholder-data.js.map