@craft-ts/core 0.7.0-beta.13

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

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

package/src/lib/insert-react-on-mutation.d.ts

@@ -0,0 +1,261 @@
+import { WritableSignal } from './host/craft-compat';
+import { InsertionParams, QueryDeclarativeEffect, ResourceExceptionConstraints } from './query.core';
+import { ResourceByIdRef } from './resource-by-id';
+import { InternalType } from './util/types/util.type';
+import { type YieldableReactiveSignal, type YieldableReactiveValue } from './reactive-read';
+type PublicMutation = {
+    readonly kind: 'mutation';
+    readonly resourceParamsSrc: YieldableReactiveValue<any>;
+    readonly value?: YieldableReactiveValue<any>;
+    readonly mutate?: (...args: any[]) => unknown;
+    readonly select?: (...args: any[]) => unknown;
+};
+type PublicMutationState<Mutation> = Mutation extends {
+    readonly value: YieldableReactiveValue<infer Value>;
+} ? Exclude<Value, undefined> : Mutation extends {
+    readonly select: (...args: any[]) => infer Selected;
+} ? NonNullable<Selected> extends {
+    readonly value: YieldableReactiveValue<infer Value>;
+} ? Exclude<Value, undefined> : unknown : unknown;
+type PublicMutationParams<Mutation> = Mutation extends {
+    readonly resourceParamsSrc: YieldableReactiveValue<infer Params>;
+} ? Exclude<Params, undefined> : unknown;
+type PublicMutationArgs<Mutation> = Mutation extends {
+    readonly mutate: (args: infer Args) => unknown;
+} ? Args : PublicMutationParams<Mutation>;
+type PublicMutationIdentifier<Mutation> = Mutation extends {
+    readonly select: (identifier: infer Identifier) => unknown;
+} ? Identifier : unknown;
+/**
+ * Creates an insertion function that makes a query react to mutation state changes.
+ *
+ * This insertion enables declarative synchronization between queries and mutations, allowing you to:
+ * - Optimistically update query data when a mutation starts (before server response)
+ * - Update query data when a mutation completes successfully
+ * - Patch specific fields in query data based on mutation parameters
+ * - Reload queries when mutations complete
+ * - Filter which query instances should react (when using identifiers)
+ *
+ * @remarks
+ * This is particularly useful for:
+ * - **Optimistic UI updates**: Show changes immediately while the mutation is processing
+ * - **Cache synchronization**: Keep local query cache in sync with server state after mutations
+ * - **Selective updates**: Update only relevant query instances based on identifiers
+ * - **Complex state management**: Coordinate multiple queries reacting to the same mutation
+ *
+ * @param mutation - The mutation to react to. Can be either:
+ *   - A standard mutation (ResourceLikeMutationRef)
+ *   - A mutation with identifier for grouped instances (ResourceByIdLikeMutationRef)
+ * @param mutationEffectOptions - Configuration for how the query should react:
+ *   - `optimisticUpdate`: Function to update query state immediately when mutation starts (loading state)
+ *   - `update`: Function to update query state when mutation completes (resolved state)
+ *   - `optimisticPatch`: Object mapping query fields to mutation values for optimistic updates
+ *   - `patch`: Object mapping query fields to mutation values for final updates
+ *   - `reload`: Configuration to reload the query when mutation reaches specific states
+ *   - `filter`: Function to determine which query instances should react (required when using identifiers)
+ *
+ * @returns An insertion function that can be passed to query() to enable the reactive behavior
+ *
+ * @example
+ * Basic optimistic update with patch
+ * ```ts
+ * const updateUserMutation = yield* mutation({
+ *   method: (data: { id: string; name: string }) => data,
+ *   loader: async ({ params }) => {
+ *     const response = await fetch(`/api/users/${params.id}`, {
+ *       method: 'PATCH',
+ *       body: JSON.stringify(params),
+ *     });
+ *     return response.json();
+ *   },
+ * }));
+ *
+ * const userQuery = yield* query(
+ *   {
+ *     params: () => ({ userId: currentUserId() }),
+ *     loader: async ({ params }) => {
+ *       const response = await fetch(`/api/users/${params.userId}`);
+ *       return response.json();
+ *     },
+ *   },
+ *   insertReactOnMutation(updateUserMutation, {
+ *     // Optimistically update the name while mutation is loading
+ *     optimisticPatch: {
+ *       name: ({ mutationParams }) => mutationParams.name,
+ *     },
+ *     // Apply final update when mutation resolves
+ *     patch: {
+ *       name: ({ mutationParams }) => mutationParams.name,
+ *     },
+ *   })
+ * ));
+ *
+ * // When mutation is triggered, query updates immediately (optimistic)
+ * yield* updateUserMutation.mutate({ id: '123', name: 'New Name' });
+ * // userQuery.value().name is now 'New Name' (optimistic)
+ *
+ * // When mutation completes, patch confirms the change
+ * // userQuery.value().name remains 'New Name' (confirmed)
+ * ```
+ *
+ * @example
+ * Full state update on mutation completion
+ * ```ts
+ * const deleteTodoMutation = yield* mutation({
+ *   method: (todoId: string) => ({ todoId }),
+ *   loader: async ({ params }) => {
+ *     await fetch(`/api/todos/${params.todoId}`, { method: 'DELETE' });
+ *     return { deleted: true };
+ *   },
+ * }));
+ *
+ * const todosQuery = yield* query(
+ *   {
+ *     params: () => ({}),
+ *     loader: async () => {
+ *       const response = await fetch('/api/todos');
+ *       return response.json(); // Returns Todo[]
+ *     },
+ *   },
+ *   insertReactOnMutation(deleteTodoMutation, {
+ *     // Remove the deleted todo from the list optimistically
+ *     optimisticUpdate: ({ queryResource, mutationParams }) => {
+ *       const currentTodos = queryResource.value() ?? [];
+ *       return currentTodos.filter(todo => todo.id !== mutationParams.todoId);
+ *     },
+ *     // Confirm the deletion when mutation resolves
+ *     update: ({ queryResource, mutationParams }) => {
+ *       const currentTodos = queryResource.value() ?? [];
+ *       return currentTodos.filter(todo => todo.id !== mutationParams.todoId);
+ *     },
+ *   })
+ * ));
+ * ```
+ *
+ * @example
+ * Reload query after mutation
+ * ```ts
+ * const createPostMutation = yield* mutation({
+ *   method: (data: { title: string; content: string }) => data,
+ *   loader: async ({ params }) => {
+ *     const response = await fetch('/api/posts', {
+ *       method: 'POST',
+ *       body: JSON.stringify(params),
+ *     });
+ *     return response.json();
+ *   },
+ * }));
+ *
+ * const postsQuery = yield* query(
+ *   {
+ *     params: () => ({ page: 1 }),
+ *     loader: async ({ params }) => {
+ *       const response = await fetch(`/api/posts?page=${params.page}`);
+ *       return response.json();
+ *     },
+ *   },
+ *   insertReactOnMutation(createPostMutation, {
+ *     // Reload the posts list when mutation completes
+ *     reload: {
+ *       onMutationResolved: true, // Reload on success
+ *     },
+ *   })
+ * ));
+ *
+ * // When mutation completes, postsQuery automatically reloads
+ * yield* createPostMutation.mutate({ title: 'New Post', content: 'Content' });
+ * ```
+ *
+ * @example
+ * Filtered updates with identifiers
+ * ```ts
+ * const updatePostMutation = yield* mutation({
+ *   method: (data: { postId: string; title: string }) => data,
+ *   loader: async ({ params }) => {
+ *     const response = await fetch(`/api/posts/${params.postId}`, {
+ *       method: 'PATCH',
+ *       body: JSON.stringify(params),
+ *     });
+ *     return response.json();
+ *   },
+ * }));
+ *
+ * const postsQuery = yield* query(
+ *   {
+ *     params: () => currentPostId(),
+ *     identifier: (params) => params, // params is the postId
+ *     loader: async ({ params }) => {
+ *       const response = await fetch(`/api/posts/${params}`);
+ *       return response.json();
+ *     },
+ *   },
+ *   insertReactOnMutation(updatePostMutation, {
+ *     // Only update the query instance that matches the mutation's postId
+ *     filter: ({ queryIdentifier, mutationParams }) =>
+ *       queryIdentifier === mutationParams.postId,
+ *     patch: {
+ *       title: ({ mutationParams }) => mutationParams.title,
+ *     },
+ *   })
+ * ));
+ *
+ * // Only the query instance for post '123' will be updated
+ * yield* updatePostMutation.mutate({ postId: '123', title: 'Updated Title' });
+ * console.log(postsQuery.select('123')?.value()?.title); // 'Updated Title'
+ * console.log(postsQuery.select('456')?.value()?.title); // unchanged
+ * ```
+ *
+ * @example
+ * Complex nested field updates
+ * ```ts
+ * const updateUserProfileMutation = yield* mutation({
+ *   method: (data: { userId: string; profile: { bio: string; avatar: string } }) => data,
+ *   loader: async ({ params }) => {
+ *     const response = await fetch(`/api/users/${params.userId}/profile`, {
+ *       method: 'PATCH',
+ *       body: JSON.stringify(params.profile),
+ *     });
+ *     return response.json();
+ *   },
+ * }));
+ *
+ * const userQuery = yield* query(
+ *   {
+ *     params: () => ({ userId: currentUserId() }),
+ *     loader: async ({ params }) => {
+ *       const response = await fetch(`/api/users/${params.userId}`);
+ *       return response.json(); // Returns { id, name, profile: { bio, avatar, ... } }
+ *     },
+ *   },
+ *   insertReactOnMutation(updateUserProfileMutation, {
+ *     optimisticPatch: {
+ *       'profile.bio': ({ mutationParams }) => mutationParams.profile.bio,
+ *       'profile.avatar': ({ mutationParams }) => mutationParams.profile.avatar,
+ *     },
+ *   })
+ * ));
+ *
+ * // Nested fields are updated optimistically
+ * yield* updateUserProfileMutation.mutate({
+ *   userId: '123',
+ *   profile: { bio: 'New bio', avatar: 'new-avatar.jpg' }
+ * });
+ * ```
+ */
+export declare function insertReactOnMutation<QueryResourceState extends object | undefined, QueryResourceParams, QueryResourceArgsParams, QueryIsMethod extends boolean, QuerySourceParams, QueryGroupIdentifier, QueryInsertions, Mutation extends PublicMutation, MutationResourceState = PublicMutationState<Mutation>, MutationResourceParams = PublicMutationParams<Mutation>, MutationResourceArgsParams = PublicMutationArgs<Mutation>, MutationIsMethod = Mutation extends {
+    readonly mutate: (...args: any[]) => unknown;
+} ? true : false, MutationSourceParams = unknown, MutationGroupIdentifier = PublicMutationIdentifier<Mutation>, MutationInsertions = unknown, MutationExceptions extends ResourceExceptionConstraints = ResourceExceptionConstraints, QueryExceptions extends ResourceExceptionConstraints = ResourceExceptionConstraints>(mutation: Mutation, mutationEffectOptions: QueryDeclarativeEffect<{
+    query: InternalType<NoInfer<QueryResourceState>, NoInfer<QueryResourceParams>, NoInfer<QueryResourceArgsParams>, [
+        unknown
+    ] extends [NoInfer<QueryGroupIdentifier>] ? false : true, NoInfer<QueryIsMethod>, NoInfer<QueryInsertions>, NoInfer<QueryGroupIdentifier>, NoInfer<QuerySourceParams>, NoInfer<QueryExceptions>>;
+    mutation: InternalType<NoInfer<MutationResourceState>, NoInfer<MutationResourceParams>, NoInfer<MutationResourceArgsParams>, [
+        unknown
+    ] extends [MutationGroupIdentifier] ? false : true, NoInfer<MutationIsMethod>, NoInfer<MutationInsertions>, NoInfer<MutationGroupIdentifier>, NoInfer<MutationSourceParams>, NoInfer<MutationExceptions>>;
+}>): (context: InsertionParams<QueryResourceState, QueryResourceParams, QueryExceptions, QueryInsertions> | {
+    resourceById: YieldableReactiveSignal<ResourceByIdRef<QueryGroupIdentifier & string, QueryResourceState, QueryResourceParams>, "resourceById">;
+    resourceParamsSrc: YieldableReactiveSignal<WritableSignal<QueryResourceParams | undefined>, "resourceParamsSrc">;
+    identifier: (params: NonNullable<QueryResourceParams>) => QueryGroupIdentifier;
+    insertions: keyof QueryInsertions extends string ? QueryInsertions : never;
+}) => import("..").EffectRef;
+export {};
+//# sourceMappingURL=insert-react-on-mutation.d.ts.map

package/src/lib/insert-react-on-mutation.d.ts.map

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

package/src/lib/insert-react-on-mutation.js

@@ -0,0 +1,227 @@
+import { reactOnMutationEffect } from './util/react-on-mutation-effect';
+import { rawReactiveFacade, } from './reactive-read';
+/**
+ * Creates an insertion function that makes a query react to mutation state changes.
+ *
+ * This insertion enables declarative synchronization between queries and mutations, allowing you to:
+ * - Optimistically update query data when a mutation starts (before server response)
+ * - Update query data when a mutation completes successfully
+ * - Patch specific fields in query data based on mutation parameters
+ * - Reload queries when mutations complete
+ * - Filter which query instances should react (when using identifiers)
+ *
+ * @remarks
+ * This is particularly useful for:
+ * - **Optimistic UI updates**: Show changes immediately while the mutation is processing
+ * - **Cache synchronization**: Keep local query cache in sync with server state after mutations
+ * - **Selective updates**: Update only relevant query instances based on identifiers
+ * - **Complex state management**: Coordinate multiple queries reacting to the same mutation
+ *
+ * @param mutation - The mutation to react to. Can be either:
+ *   - A standard mutation (ResourceLikeMutationRef)
+ *   - A mutation with identifier for grouped instances (ResourceByIdLikeMutationRef)
+ * @param mutationEffectOptions - Configuration for how the query should react:
+ *   - `optimisticUpdate`: Function to update query state immediately when mutation starts (loading state)
+ *   - `update`: Function to update query state when mutation completes (resolved state)
+ *   - `optimisticPatch`: Object mapping query fields to mutation values for optimistic updates
+ *   - `patch`: Object mapping query fields to mutation values for final updates
+ *   - `reload`: Configuration to reload the query when mutation reaches specific states
+ *   - `filter`: Function to determine which query instances should react (required when using identifiers)
+ *
+ * @returns An insertion function that can be passed to query() to enable the reactive behavior
+ *
+ * @example
+ * Basic optimistic update with patch
+ * ```ts
+ * const updateUserMutation = yield* mutation({
+ *   method: (data: { id: string; name: string }) => data,
+ *   loader: async ({ params }) => {
+ *     const response = await fetch(`/api/users/${params.id}`, {
+ *       method: 'PATCH',
+ *       body: JSON.stringify(params),
+ *     });
+ *     return response.json();
+ *   },
+ * }));
+ *
+ * const userQuery = yield* query(
+ *   {
+ *     params: () => ({ userId: currentUserId() }),
+ *     loader: async ({ params }) => {
+ *       const response = await fetch(`/api/users/${params.userId}`);
+ *       return response.json();
+ *     },
+ *   },
+ *   insertReactOnMutation(updateUserMutation, {
+ *     // Optimistically update the name while mutation is loading
+ *     optimisticPatch: {
+ *       name: ({ mutationParams }) => mutationParams.name,
+ *     },
+ *     // Apply final update when mutation resolves
+ *     patch: {
+ *       name: ({ mutationParams }) => mutationParams.name,
+ *     },
+ *   })
+ * ));
+ *
+ * // When mutation is triggered, query updates immediately (optimistic)
+ * yield* updateUserMutation.mutate({ id: '123', name: 'New Name' });
+ * // userQuery.value().name is now 'New Name' (optimistic)
+ *
+ * // When mutation completes, patch confirms the change
+ * // userQuery.value().name remains 'New Name' (confirmed)
+ * ```
+ *
+ * @example
+ * Full state update on mutation completion
+ * ```ts
+ * const deleteTodoMutation = yield* mutation({
+ *   method: (todoId: string) => ({ todoId }),
+ *   loader: async ({ params }) => {
+ *     await fetch(`/api/todos/${params.todoId}`, { method: 'DELETE' });
+ *     return { deleted: true };
+ *   },
+ * }));
+ *
+ * const todosQuery = yield* query(
+ *   {
+ *     params: () => ({}),
+ *     loader: async () => {
+ *       const response = await fetch('/api/todos');
+ *       return response.json(); // Returns Todo[]
+ *     },
+ *   },
+ *   insertReactOnMutation(deleteTodoMutation, {
+ *     // Remove the deleted todo from the list optimistically
+ *     optimisticUpdate: ({ queryResource, mutationParams }) => {
+ *       const currentTodos = queryResource.value() ?? [];
+ *       return currentTodos.filter(todo => todo.id !== mutationParams.todoId);
+ *     },
+ *     // Confirm the deletion when mutation resolves
+ *     update: ({ queryResource, mutationParams }) => {
+ *       const currentTodos = queryResource.value() ?? [];
+ *       return currentTodos.filter(todo => todo.id !== mutationParams.todoId);
+ *     },
+ *   })
+ * ));
+ * ```
+ *
+ * @example
+ * Reload query after mutation
+ * ```ts
+ * const createPostMutation = yield* mutation({
+ *   method: (data: { title: string; content: string }) => data,
+ *   loader: async ({ params }) => {
+ *     const response = await fetch('/api/posts', {
+ *       method: 'POST',
+ *       body: JSON.stringify(params),
+ *     });
+ *     return response.json();
+ *   },
+ * }));
+ *
+ * const postsQuery = yield* query(
+ *   {
+ *     params: () => ({ page: 1 }),
+ *     loader: async ({ params }) => {
+ *       const response = await fetch(`/api/posts?page=${params.page}`);
+ *       return response.json();
+ *     },
+ *   },
+ *   insertReactOnMutation(createPostMutation, {
+ *     // Reload the posts list when mutation completes
+ *     reload: {
+ *       onMutationResolved: true, // Reload on success
+ *     },
+ *   })
+ * ));
+ *
+ * // When mutation completes, postsQuery automatically reloads
+ * yield* createPostMutation.mutate({ title: 'New Post', content: 'Content' });
+ * ```
+ *
+ * @example
+ * Filtered updates with identifiers
+ * ```ts
+ * const updatePostMutation = yield* mutation({
+ *   method: (data: { postId: string; title: string }) => data,
+ *   loader: async ({ params }) => {
+ *     const response = await fetch(`/api/posts/${params.postId}`, {
+ *       method: 'PATCH',
+ *       body: JSON.stringify(params),
+ *     });
+ *     return response.json();
+ *   },
+ * }));
+ *
+ * const postsQuery = yield* query(
+ *   {
+ *     params: () => currentPostId(),
+ *     identifier: (params) => params, // params is the postId
+ *     loader: async ({ params }) => {
+ *       const response = await fetch(`/api/posts/${params}`);
+ *       return response.json();
+ *     },
+ *   },
+ *   insertReactOnMutation(updatePostMutation, {
+ *     // Only update the query instance that matches the mutation's postId
+ *     filter: ({ queryIdentifier, mutationParams }) =>
+ *       queryIdentifier === mutationParams.postId,
+ *     patch: {
+ *       title: ({ mutationParams }) => mutationParams.title,
+ *     },
+ *   })
+ * ));
+ *
+ * // Only the query instance for post '123' will be updated
+ * yield* updatePostMutation.mutate({ postId: '123', title: 'Updated Title' });
+ * console.log(postsQuery.select('123')?.value()?.title); // 'Updated Title'
+ * console.log(postsQuery.select('456')?.value()?.title); // unchanged
+ * ```
+ *
+ * @example
+ * Complex nested field updates
+ * ```ts
+ * const updateUserProfileMutation = yield* mutation({
+ *   method: (data: { userId: string; profile: { bio: string; avatar: string } }) => data,
+ *   loader: async ({ params }) => {
+ *     const response = await fetch(`/api/users/${params.userId}/profile`, {
+ *       method: 'PATCH',
+ *       body: JSON.stringify(params.profile),
+ *     });
+ *     return response.json();
+ *   },
+ * }));
+ *
+ * const userQuery = yield* query(
+ *   {
+ *     params: () => ({ userId: currentUserId() }),
+ *     loader: async ({ params }) => {
+ *       const response = await fetch(`/api/users/${params.userId}`);
+ *       return response.json(); // Returns { id, name, profile: { bio, avatar, ... } }
+ *     },
+ *   },
+ *   insertReactOnMutation(updateUserProfileMutation, {
+ *     optimisticPatch: {
+ *       'profile.bio': ({ mutationParams }) => mutationParams.profile.bio,
+ *       'profile.avatar': ({ mutationParams }) => mutationParams.profile.avatar,
+ *     },
+ *   })
+ * ));
+ *
+ * // Nested fields are updated optimistically
+ * yield* updateUserProfileMutation.mutate({
+ *   userId: '123',
+ *   profile: { bio: 'New bio', avatar: 'new-avatar.jpg' }
+ * });
+ * ```
+ */
+export function insertReactOnMutation(mutation, mutationEffectOptions) {
+    return (context) => {
+        return reactOnMutationEffect({
+            queryTargeted: rawReactiveFacade('resource' in context ? context.resource : context.resourceById),
+            mutationTargeted: rawReactiveFacade(mutation),
+        }, mutationEffectOptions);
+    };
+}
+//# sourceMappingURL=insert-react-on-mutation.js.map

package/src/lib/insert-react-on-mutation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"insert-react-on-mutation.js","sourceRoot":"","sources":["../../../../../libs/core/src/lib/insert-react-on-mutation.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAExE,OAAO,EACL,iBAAiB,GAGlB,MAAM,iBAAiB,CAAC;AA0CzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuNG;AACH,MAAM,UAAU,qBAAqB,CAyBnC,QAAkB,EAClB,qBAuBE;IAEF,OAAO,CACL,OA2BK,EACL,EAAE;QACF,OAAO,qBAAqB,CAC1B;YACE,aAAa,EAAE,iBAAiB,CAC9B,UAAU,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,CAoB5D;YACL,gBAAgB,EAAE,iBAAiB,CAAC,QAAQ,CAmBvC;SACN,EACD,qBAAqB,CACtB,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import { WritableSignal } from './host/craft-compat';\nimport {\n  ResourceByIdLikeMutationRef,\n  ResourceLikeMutationRef,\n} from './mutation';\nimport { ResourceByIdLikeQueryRef, ResourceLikeQueryRef } from './query';\nimport {\n  InsertionParams,\n  QueryDeclarativeEffect,\n  ResourceExceptionConstraints,\n} from './query.core';\nimport { ResourceByIdRef } from './resource-by-id';\nimport { reactOnMutationEffect } from './util/react-on-mutation-effect';\nimport { InternalType } from './util/types/util.type';\nimport {\n  rawReactiveFacade,\n  type YieldableReactiveSignal,\n  type YieldableReactiveValue,\n} from './reactive-read';\n\ntype PublicMutation = {\n  readonly kind: 'mutation';\n  readonly resourceParamsSrc: YieldableReactiveValue<any>;\n  readonly value?: YieldableReactiveValue<any>;\n  readonly mutate?: (...args: any[]) => unknown;\n  readonly select?: (...args: any[]) => unknown;\n};\n\ntype PublicMutationState<Mutation> = Mutation extends {\n  readonly value: YieldableReactiveValue<infer Value>;\n}\n  ? Exclude<Value, undefined>\n  : Mutation extends {\n        readonly select: (...args: any[]) => infer Selected;\n      }\n    ? NonNullable<Selected> extends {\n        readonly value: YieldableReactiveValue<infer Value>;\n      }\n      ? Exclude<Value, undefined>\n      : unknown\n    : unknown;\n\ntype PublicMutationParams<Mutation> = Mutation extends {\n  readonly resourceParamsSrc: YieldableReactiveValue<infer Params>;\n}\n  ? Exclude<Params, undefined>\n  : unknown;\n\ntype PublicMutationArgs<Mutation> = Mutation extends {\n  readonly mutate: (args: infer Args) => unknown;\n}\n  ? Args\n  : PublicMutationParams<Mutation>;\n\ntype PublicMutationIdentifier<Mutation> = Mutation extends {\n  readonly select: (identifier: infer Identifier) => unknown;\n}\n  ? Identifier\n  : unknown;\n\n/**\n * Creates an insertion function that makes a query react to mutation state changes.\n *\n * This insertion enables declarative synchronization between queries and mutations, allowing you to:\n * - Optimistically update query data when a mutation starts (before server response)\n * - Update query data when a mutation completes successfully\n * - Patch specific fields in query data based on mutation parameters\n * - Reload queries when mutations complete\n * - Filter which query instances should react (when using identifiers)\n *\n * @remarks\n * This is particularly useful for:\n * - **Optimistic UI updates**: Show changes immediately while the mutation is processing\n * - **Cache synchronization**: Keep local query cache in sync with server state after mutations\n * - **Selective updates**: Update only relevant query instances based on identifiers\n * - **Complex state management**: Coordinate multiple queries reacting to the same mutation\n *\n * @param mutation - The mutation to react to. Can be either:\n *   - A standard mutation (ResourceLikeMutationRef)\n *   - A mutation with identifier for grouped instances (ResourceByIdLikeMutationRef)\n * @param mutationEffectOptions - Configuration for how the query should react:\n *   - `optimisticUpdate`: Function to update query state immediately when mutation starts (loading state)\n *   - `update`: Function to update query state when mutation completes (resolved state)\n *   - `optimisticPatch`: Object mapping query fields to mutation values for optimistic updates\n *   - `patch`: Object mapping query fields to mutation values for final updates\n *   - `reload`: Configuration to reload the query when mutation reaches specific states\n *   - `filter`: Function to determine which query instances should react (required when using identifiers)\n *\n * @returns An insertion function that can be passed to query() to enable the reactive behavior\n *\n * @example\n * Basic optimistic update with patch\n * ```ts\n * const updateUserMutation = yield* mutation({\n *   method: (data: { id: string; name: string }) => data,\n *   loader: async ({ params }) => {\n *     const response = await fetch(`/api/users/${params.id}`, {\n *       method: 'PATCH',\n *       body: JSON.stringify(params),\n *     });\n *     return response.json();\n *   },\n * }));\n *\n * const userQuery = yield* query(\n *   {\n *     params: () => ({ userId: currentUserId() }),\n *     loader: async ({ params }) => {\n *       const response = await fetch(`/api/users/${params.userId}`);\n *       return response.json();\n *     },\n *   },\n *   insertReactOnMutation(updateUserMutation, {\n *     // Optimistically update the name while mutation is loading\n *     optimisticPatch: {\n *       name: ({ mutationParams }) => mutationParams.name,\n *     },\n *     // Apply final update when mutation resolves\n *     patch: {\n *       name: ({ mutationParams }) => mutationParams.name,\n *     },\n *   })\n * ));\n *\n * // When mutation is triggered, query updates immediately (optimistic)\n * yield* updateUserMutation.mutate({ id: '123', name: 'New Name' });\n * // userQuery.value().name is now 'New Name' (optimistic)\n *\n * // When mutation completes, patch confirms the change\n * // userQuery.value().name remains 'New Name' (confirmed)\n * ```\n *\n * @example\n * Full state update on mutation completion\n * ```ts\n * const deleteTodoMutation = yield* mutation({\n *   method: (todoId: string) => ({ todoId }),\n *   loader: async ({ params }) => {\n *     await fetch(`/api/todos/${params.todoId}`, { method: 'DELETE' });\n *     return { deleted: true };\n *   },\n * }));\n *\n * const todosQuery = yield* query(\n *   {\n *     params: () => ({}),\n *     loader: async () => {\n *       const response = await fetch('/api/todos');\n *       return response.json(); // Returns Todo[]\n *     },\n *   },\n *   insertReactOnMutation(deleteTodoMutation, {\n *     // Remove the deleted todo from the list optimistically\n *     optimisticUpdate: ({ queryResource, mutationParams }) => {\n *       const currentTodos = queryResource.value() ?? [];\n *       return currentTodos.filter(todo => todo.id !== mutationParams.todoId);\n *     },\n *     // Confirm the deletion when mutation resolves\n *     update: ({ queryResource, mutationParams }) => {\n *       const currentTodos = queryResource.value() ?? [];\n *       return currentTodos.filter(todo => todo.id !== mutationParams.todoId);\n *     },\n *   })\n * ));\n * ```\n *\n * @example\n * Reload query after mutation\n * ```ts\n * const createPostMutation = yield* mutation({\n *   method: (data: { title: string; content: string }) => data,\n *   loader: async ({ params }) => {\n *     const response = await fetch('/api/posts', {\n *       method: 'POST',\n *       body: JSON.stringify(params),\n *     });\n *     return response.json();\n *   },\n * }));\n *\n * const postsQuery = yield* query(\n *   {\n *     params: () => ({ page: 1 }),\n *     loader: async ({ params }) => {\n *       const response = await fetch(`/api/posts?page=${params.page}`);\n *       return response.json();\n *     },\n *   },\n *   insertReactOnMutation(createPostMutation, {\n *     // Reload the posts list when mutation completes\n *     reload: {\n *       onMutationResolved: true, // Reload on success\n *     },\n *   })\n * ));\n *\n * // When mutation completes, postsQuery automatically reloads\n * yield* createPostMutation.mutate({ title: 'New Post', content: 'Content' });\n * ```\n *\n * @example\n * Filtered updates with identifiers\n * ```ts\n * const updatePostMutation = yield* mutation({\n *   method: (data: { postId: string; title: string }) => data,\n *   loader: async ({ params }) => {\n *     const response = await fetch(`/api/posts/${params.postId}`, {\n *       method: 'PATCH',\n *       body: JSON.stringify(params),\n *     });\n *     return response.json();\n *   },\n * }));\n *\n * const postsQuery = yield* query(\n *   {\n *     params: () => currentPostId(),\n *     identifier: (params) => params, // params is the postId\n *     loader: async ({ params }) => {\n *       const response = await fetch(`/api/posts/${params}`);\n *       return response.json();\n *     },\n *   },\n *   insertReactOnMutation(updatePostMutation, {\n *     // Only update the query instance that matches the mutation's postId\n *     filter: ({ queryIdentifier, mutationParams }) =>\n *       queryIdentifier === mutationParams.postId,\n *     patch: {\n *       title: ({ mutationParams }) => mutationParams.title,\n *     },\n *   })\n * ));\n *\n * // Only the query instance for post '123' will be updated\n * yield* updatePostMutation.mutate({ postId: '123', title: 'Updated Title' });\n * console.log(postsQuery.select('123')?.value()?.title); // 'Updated Title'\n * console.log(postsQuery.select('456')?.value()?.title); // unchanged\n * ```\n *\n * @example\n * Complex nested field updates\n * ```ts\n * const updateUserProfileMutation = yield* mutation({\n *   method: (data: { userId: string; profile: { bio: string; avatar: string } }) => data,\n *   loader: async ({ params }) => {\n *     const response = await fetch(`/api/users/${params.userId}/profile`, {\n *       method: 'PATCH',\n *       body: JSON.stringify(params.profile),\n *     });\n *     return response.json();\n *   },\n * }));\n *\n * const userQuery = yield* query(\n *   {\n *     params: () => ({ userId: currentUserId() }),\n *     loader: async ({ params }) => {\n *       const response = await fetch(`/api/users/${params.userId}`);\n *       return response.json(); // Returns { id, name, profile: { bio, avatar, ... } }\n *     },\n *   },\n *   insertReactOnMutation(updateUserProfileMutation, {\n *     optimisticPatch: {\n *       'profile.bio': ({ mutationParams }) => mutationParams.profile.bio,\n *       'profile.avatar': ({ mutationParams }) => mutationParams.profile.avatar,\n *     },\n *   })\n * ));\n *\n * // Nested fields are updated optimistically\n * yield* updateUserProfileMutation.mutate({\n *   userId: '123',\n *   profile: { bio: 'New bio', avatar: 'new-avatar.jpg' }\n * });\n * ```\n */\nexport function insertReactOnMutation<\n  QueryResourceState extends object | undefined,\n  QueryResourceParams,\n  QueryResourceArgsParams,\n  QueryIsMethod extends boolean,\n  QuerySourceParams,\n  QueryGroupIdentifier,\n  QueryInsertions,\n  Mutation extends PublicMutation,\n  MutationResourceState = PublicMutationState<Mutation>,\n  MutationResourceParams = PublicMutationParams<Mutation>,\n  MutationResourceArgsParams = PublicMutationArgs<Mutation>,\n  MutationIsMethod = Mutation extends {\n    readonly mutate: (...args: any[]) => unknown;\n  }\n    ? true\n    : false,\n  MutationSourceParams = unknown,\n  MutationGroupIdentifier = PublicMutationIdentifier<Mutation>,\n  MutationInsertions = unknown,\n  MutationExceptions extends\n    ResourceExceptionConstraints = ResourceExceptionConstraints,\n  QueryExceptions extends\n    ResourceExceptionConstraints = ResourceExceptionConstraints,\n>(\n  mutation: Mutation,\n  mutationEffectOptions: QueryDeclarativeEffect<{\n    query: InternalType<\n      NoInfer<QueryResourceState>,\n      NoInfer<QueryResourceParams>,\n      NoInfer<QueryResourceArgsParams>,\n      [unknown] extends [NoInfer<QueryGroupIdentifier>] ? false : true,\n      NoInfer<QueryIsMethod>,\n      NoInfer<QueryInsertions>,\n      NoInfer<QueryGroupIdentifier>,\n      NoInfer<QuerySourceParams>,\n      NoInfer<QueryExceptions>\n    >;\n    mutation: InternalType<\n      NoInfer<MutationResourceState>,\n      NoInfer<MutationResourceParams>,\n      NoInfer<MutationResourceArgsParams>,\n      [unknown] extends [MutationGroupIdentifier] ? false : true,\n      NoInfer<MutationIsMethod>,\n      NoInfer<MutationInsertions>,\n      NoInfer<MutationGroupIdentifier>,\n      NoInfer<MutationSourceParams>,\n      NoInfer<MutationExceptions>\n    >;\n  }>,\n) {\n  return (\n    context:\n      | InsertionParams<\n          QueryResourceState,\n          QueryResourceParams,\n          QueryExceptions,\n          QueryInsertions\n        >\n      | {\n          // ! avoid to use InsertionByIdParams it is broking the typing inference\n          resourceById: YieldableReactiveSignal<\n            ResourceByIdRef<\n              QueryGroupIdentifier & string,\n              QueryResourceState,\n              QueryResourceParams\n            >,\n            'resourceById'\n          >;\n          resourceParamsSrc: YieldableReactiveSignal<\n            WritableSignal<QueryResourceParams | undefined>,\n            'resourceParamsSrc'\n          >;\n          identifier: (\n            params: NonNullable<QueryResourceParams>,\n          ) => QueryGroupIdentifier;\n          insertions: keyof QueryInsertions extends string\n            ? QueryInsertions\n            : never;\n        },\n  ) => {\n    return reactOnMutationEffect(\n      {\n        queryTargeted: rawReactiveFacade(\n          'resource' in context ? context.resource : context.resourceById,\n        ) as unknown as\n          | ResourceLikeQueryRef<\n              QueryResourceState,\n              QueryResourceParams,\n              QueryIsMethod,\n              QueryResourceArgsParams,\n              QuerySourceParams,\n              QueryInsertions,\n              QueryExceptions\n            >\n          | ResourceByIdLikeQueryRef<\n              QueryResourceState,\n              QueryResourceParams,\n              QueryIsMethod,\n              QueryResourceArgsParams,\n              QuerySourceParams,\n              QueryInsertions,\n              QueryGroupIdentifier,\n              QueryExceptions\n            >,\n        mutationTargeted: rawReactiveFacade(mutation) as unknown as\n          | ResourceLikeMutationRef<\n              MutationResourceState,\n              MutationResourceParams,\n              MutationIsMethod,\n              MutationResourceArgsParams,\n              MutationSourceParams,\n              MutationInsertions,\n              MutationExceptions\n            >\n          | ResourceByIdLikeMutationRef<\n              MutationResourceState,\n              MutationResourceParams,\n              MutationIsMethod,\n              MutationResourceArgsParams,\n              MutationSourceParams,\n              MutationInsertions,\n              MutationGroupIdentifier,\n              MutationExceptions\n            >,\n      },\n      mutationEffectOptions,\n    );\n  };\n}\n"]}

package/src/lib/insert-select-resource.d.ts

@@ -0,0 +1,31 @@
+import type { InsertionStateFactoryContext, InsertionsStateFactory } from './query.core';
+import { type InsertSelectOutput, type SelectedTarget } from './insert-select';
+type ResourceSelectAutoCompleteName<StateType> = NoInfer<StateType> extends readonly object[] ? string : keyof NoInfer<StateType>;
+type ResolveResourceState<StateType> = StateType extends readonly unknown[] ? StateType : StateType extends object ? {
+    [Key in keyof StateType]: StateType[Key];
+} : StateType;
+type ResourceSelectInsertionReturn<ResourceState extends object | undefined, Name extends string, Insertion, PreviousInsertionsOutputs = {}, Yielded = never> = ResourceSelectInsertionFactorySignature<ResourceState, ResourceState, Name, Insertion, PreviousInsertionsOutputs, Yielded> & ResourceSelectInsertionFactorySignature<object | undefined, ResourceState, Name, Insertion, PreviousInsertionsOutputs, Yielded>;
+type ResourceSelectInsertionFactorySignature<ContextState extends object | undefined, OutputState extends object | undefined, Name extends string, Insertion, PreviousInsertionsOutputs, Yielded> = (context: Pick<InsertionStateFactoryContext<ContextState, PreviousInsertionsOutputs>, 'state' | 'insertions'>) => InsertSelectOutput<ResolveResourceState<OutputState>, Name, [Insertion]> | Generator<Yielded, InsertSelectOutput<ResolveResourceState<OutputState>, Name, [Insertion]>, unknown>;
+/**
+ * Selects a nested property or an item in an array returned by a resource
+ * primitive and attaches state-style insertions to that selection.
+ *
+ * The resource must be non-grouped. Grouped resources expose a collection of
+ * resource refs through `resourceById`; selecting inside that collection needs
+ * to happen after `select(id)` and is intentionally rejected here rather than
+ * receiving an ambiguous state shape.
+ *
+ * The selected insertion deliberately receives the same context as
+ * `insertSelect`: `state`, `set`, `update`, `patch`, and previous insertions.
+ * The outer resource still keeps its query/mutation/asyncProcess runtime kind
+ * for method wrappers.
+ */
+export declare function insertSelectResource<ResourceState extends object | undefined, const Name extends ResourceSelectAutoCompleteName<ResourceState> & string, Insertion, PreviousInsertionsOutputs = {}, Yielded = never>(name: Name, insertion: InsertionsStateFactory<SelectedTarget<ResourceState, Name>, Insertion, PreviousInsertionsOutputs, Yielded>): ResourceSelectInsertionReturn<ResourceState, Name, Insertion, PreviousInsertionsOutputs, Yielded>;
+/** Alias semantically scoped to query resources. */
+export declare const insertQuerySelect: typeof insertSelectResource;
+/** Alias semantically scoped to mutation resources. */
+export declare const insertMutationSelect: typeof insertSelectResource;
+/** Alias semantically scoped to asyncProcess resources. */
+export declare const insertAsyncProcessSelect: typeof insertSelectResource;
+export {};
+//# sourceMappingURL=insert-select-resource.d.ts.map

package/src/lib/insert-select-resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insert-select-resource.d.ts","sourceRoot":"","sources":["../../../../../libs/core/src/lib/insert-select-resource.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,4BAA4B,EAC5B,sBAAsB,EACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACpB,MAAM,iBAAiB,CAAC;AAEzB,KAAK,8BAA8B,CAAC,SAAS,IAC3C,OAAO,CAAC,SAAS,CAAC,SAAS,SAAS,MAAM,EAAE,GACxC,MAAM,GACN,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC;AAE/B,KAAK,oBAAoB,CAAC,SAAS,IAAI,SAAS,SAAS,SAAS,OAAO,EAAE,GACvE,SAAS,GACT,SAAS,SAAS,MAAM,GACtB;KAAG,GAAG,IAAI,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC;CAAE,GAC5C,SAAS,CAAC;AAEhB,KAAK,6BAA6B,CAChC,aAAa,SAAS,MAAM,GAAG,SAAS,EACxC,IAAI,SAAS,MAAM,EACnB,SAAS,EACT,yBAAyB,GAAG,EAAE,EAC9B,OAAO,GAAG,KAAK,IACb,uCAAuC,CACzC,aAAa,EACb,aAAa,EACb,IAAI,EACJ,SAAS,EACT,yBAAyB,EACzB,OAAO,CACR,GACC,uCAAuC,CACrC,MAAM,GAAG,SAAS,EAClB,aAAa,EACb,IAAI,EACJ,SAAS,EACT,yBAAyB,EACzB,OAAO,CACR,CAAC;AAEJ,KAAK,uCAAuC,CAC1C,YAAY,SAAS,MAAM,GAAG,SAAS,EACvC,WAAW,SAAS,MAAM,GAAG,SAAS,EACtC,IAAI,SAAS,MAAM,EACnB,SAAS,EACT,yBAAyB,EACzB,OAAO,IACL,CACF,OAAO,EAAE,IAAI,CACX,4BAA4B,CAAC,YAAY,EAAE,yBAAyB,CAAC,EACrE,OAAO,GAAG,YAAY,CACvB,KAEC,kBAAkB,CAAC,oBAAoB,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC,SAAS,CAAC,CAAC,GACxE,SAAS,CACP,OAAO,EACP,kBAAkB,CAAC,oBAAoB,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC,SAAS,CAAC,CAAC,EACxE,OAAO,CACR,CAAC;AAEN;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,SAAS,MAAM,GAAG,SAAS,EACxC,KAAK,CAAC,IAAI,SAAS,8BAA8B,CAAC,aAAa,CAAC,GAAG,MAAM,EACzE,SAAS,EACT,yBAAyB,GAAG,EAAE,EAC9B,OAAO,GAAG,KAAK,EAEf,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,sBAAsB,CAC/B,cAAc,CAAC,aAAa,EAAE,IAAI,CAAC,EACnC,SAAS,EACT,yBAAyB,EACzB,OAAO,CACR,GACA,6BAA6B,CAC9B,aAAa,EACb,IAAI,EACJ,SAAS,EACT,yBAAyB,EACzB,OAAO,CACR,CAAC;AA8BF,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,6BAAuB,CAAC;AAEtD,uDAAuD;AACvD,eAAO,MAAM,oBAAoB,6BAAuB,CAAC;AAEzD,2DAA2D;AAC3D,eAAO,MAAM,wBAAwB,6BAAuB,CAAC"}

package/src/lib/insert-select-resource.js

@@ -0,0 +1,27 @@
+import { insertSelect, } from './insert-select';
+export function insertSelectResource(name, insertion) {
+    return (context) => {
+        if (context.resourceById) {
+            throw new Error('insertSelectResource does not support grouped resources; select the resource instance first.');
+        }
+        return insertSelect(name, insertion)({
+            state: context.state,
+            set: context.set,
+            update: context.update,
+            patch: context.patch ??
+                ((patchFn) => context.update((current) => ({
+                    ...current,
+                    ...patchFn(current),
+                }))),
+            insertions: context.insertions,
+            __primitiveKind: context.__primitiveKind,
+        });
+    };
+}
+/** Alias semantically scoped to query resources. */
+export const insertQuerySelect = insertSelectResource;
+/** Alias semantically scoped to mutation resources. */
+export const insertMutationSelect = insertSelectResource;
+/** Alias semantically scoped to asyncProcess resources. */
+export const insertAsyncProcessSelect = insertSelectResource;
+//# sourceMappingURL=insert-select-resource.js.map