@craft-ts/core 0.7.0-beta.13

package/src/lib/mutation.js

@@ -0,0 +1,923 @@
+import { assertInInjectionContext, batch, computed, DestroyRef, inject, Injector, isSignal, runInInjectionContext, signal, untracked, } from './host/craft-compat';
+import { takeUntilDestroyed } from './host/craft-compat';
+import { executeGeneratorCompatibleFactory, isGeneratorFunction, } from './craft-generator-runtime';
+import { executeGeneratorCompatibleFactoryAsync } from './craft-program-runtime';
+import { attachCraftSettledValue, createYieldableSettledValue, CraftNotSettled, } from './craft-settled';
+import { resourceById } from './resource-by-id';
+import { toCraftStatus, } from './util/craft-resource-status';
+import { methodParamsWrapperEqual, unwrapMethodParams, wrapMethodParams, } from './util/method-trigger-nonce';
+import { craftResource } from './craft-resource';
+import { preservedResource } from './preserved-resource';
+import { isCraftException, } from './craft-exception';
+import { createResourceExceptionsRuntime, enrichResourceException, } from './resource-exception';
+import { createSchemaValidationRuntime, useSchemaValidationPolicy, } from './schema-validation';
+import { CORRELATION_ID_SERVICE } from './correlation-id';
+import { createNamedPrimitiveGen, } from './craft-primitive-gen';
+import { APP_SNAPSHOT_REGISTRY, INSERTION_SNAPSHOT_REGISTRY, InsertionSnapshotRegistry, TAKE_APP_SNAPSHOT, triggerAndCollectInsertions, } from './take-app-snapshot';
+import { ɵcreateHostTaggedInjector, ɵHOST_TAG_LIST } from './craft-service';
+import { injectFnWrapper } from './fn-wrapper';
+import { ɵprovidePrimitiveMethodRuntimeContext } from './primitive-method-runtime-context';
+import { ɵcreatePrimitiveResourceByIdRuntimeContext, ɵcreatePrimitiveResourceRuntimeContext, ɵobservePrimitiveResourceRuntimeContext, } from './primitive-resource-runtime-context';
+import { createYieldableInsertionMethod, isNonYieldableInsertionMethod, yieldableInvocation, } from './yieldable';
+import { createYieldableReactiveFacade, deepYieldable, hasDeepYieldableInsertion, isYieldableReactiveValue, nameInsertedReactiveValue, } from './reactive-read';
+import { craftUse } from './craft-use';
+const MUTATION_INVALID_YIELD_ERROR_MESSAGE = 'mutation generators can only yield craftService dependencies or exposed dependency helpers.';
+const MUTATION_APP_START_ERROR_MESSAGE = 'mutation generators do not support onAppStart(...).';
+/**
+ * Creates a reactive mutation manager that handles asynchronous operations with state tracking.
+ *
+ * This function manages mutation state by:
+ * - Executing asynchronous operations (loader or stream) when triggered
+ * - Tracking operation status (idle, loading, resolved, exception)
+ * - Providing reactive signals for value, status, exceptions, and loading state
+ * - Supporting both method-based triggers and source-based automatic execution
+ * - Optionally enabling parallel mutation execution by grouping instances with an identifier
+ *
+ * @remarks
+ * **Important:** This function must be called within an injection context.
+ *
+ * **Mutation Modes:**
+ * - **Method-based:** Define a `method` function that returns params. Call `mutate()` to trigger the operation.
+ * - **Source-based:** Use `afterRecomputation()` to bind to a source signal. The mutation executes automatically when the source changes.
+ * - **Resource-based:** Bind to another `ResourceByIdRef` using `fromResourceById` to sync operations.
+ *
+ * **With Identifier:**
+ * When an `identifier` function is provided, mutations are grouped by ID. Use `select(id)` to access individual mutation instances.
+ * Use `selectOrCreate(id)` to access an instance, creating it when it does not exist yet.
+ *
+ * @param name - The mutation name. Used to key the returned record
+ *   (`const updateUser = yield* mutation('updateUser', config)`) and as the
+ *   injector host tag (`mutation:updateUser`), so the mutation is precisely
+ *   locatable in snapshots and logs.
+ * @param config - Configuration object containing:
+ *   - `method`: Function that takes args and returns params, or a `ReadonlySource` for automatic execution
+ *   - `loader`: Async function that performs the mutation and returns a Promise of the result
+ *   - `stream` (optional): Async function that returns a signal for streaming results
+ *   - `identifier` (optional): Function to derive a unique ID from params for grouping mutations
+ *   - `fromResourceById` (optional): Bind to another ResourceByIdRef for synced operations
+ *   - `params` (optional): Function to derive params from a resource entity
+ *   - `preservePreviousValue` (optional): Function returning boolean to keep the previous value while loading (default: false)
+ *   - Additional ResourceOptions like `equal`, `injector`, etc.
+ * @param insertion1 - Optional single insertion factory to add custom methods, computed values or side effects to the mutation.
+ *   The insertion receives a context with resource signals (`state`, `exceptions`, `hasException`, `resource`) and mutators (`set`, `update`, `patch`).
+ *   To attach several insertions, compose them with `insertMutationPipe`:
+ *   `mutation('name', config, insertMutationPipe(insertion1, insertion2))` —
+ *   each member then also sees the previous members' outputs on `context.insertions`.
+ *   Methods bound to a source using `afterRecomputation` (effectRef-like) are not exposed in the output.
+ * @returns A single-use primitive generator resolving to a mutation reference
+ *   object with:
+ *   - `value`: Signal containing the mutation result (undefined if not yet executed)
+ *   - `status`: Signal with the craft status ('idle' | 'loading' | 'reloading' | 'resolved' | 'local' | 'exception')
+ *   - `exception`: Signal with the primary `craftException` (or undefined)
+ *   - `exceptions`: Signal with the captured exceptions (`list` / `params` / `loader`)
+ *   - `hasException()`: Signal indicating whether an exception is captured
+ *   - `isLoading`: Signal indicating if the mutation is currently executing
+ *   - `hasValue()`: Method to check if a value is available
+ *   - `mutate(args)`: Method to trigger the mutation (only for method-based mutations)
+ *   - `source`: The connected source (only for source-based mutations)
+ *   - `select(id)`: Method to access a specific mutation instance by ID (only when identifier is provided)
+ *   - `selectOrCreate(id)`: Method to access or create a specific mutation instance (only when identifier is provided)
+ *   - Custom methods from insertions (excluding methods bound to sources)
+ *
+ *   Consume it with `yield*` inside a generator host (craftService factory,
+ *   craftGen, …) or with `craftUse(...)` elsewhere (typically a component field).
+ *
+ * @example
+ * Basic method-based mutation
+ * ```ts
+ * const updateUser = craftUse(mutation('updateUser', {
+ *   method: (userId: string) => ({ userId }),
+ *   loader: async ({ params }) => {
+ *     const response = await fetch(`/api/users/${params.userId}`, { method: 'PATCH' });
+ *     return response.json();
+ *   },
+ * }));
+ *
+ * // Check status
+ * console.log(updateUser.status()); // 'idle'
+ * console.log(updateUser.isLoading()); // false
+ *
+ * // Trigger mutation
+ * updateUser.mutate('user-123');
+ * console.log(updateUser.status()); // 'loading'
+ *
+ * // After completion
+ * console.log(updateUser.value()); // { id: 'user-123', name: '...' }
+ * console.log(updateUser.status()); // 'resolved'
+ * ```
+ *
+ * @example
+ * Source-based automatic mutation
+ * ```ts
+ *  todo change example for mutation
+ * const updateUserSource = source<{ userId: string, email: string }>();
+ *
+ *  const updateUser = craftUse(mutation('updateUser', {
+ *   method:  afterRecomputation(updateUserSource, (params) => params),
+ *   loader: async ({ params }) => {
+ *     const response = await fetch(`/api/users/${params.userId}`, { method: 'PATCH' });
+ *     return response.json();
+ *   },
+ * }));
+ *
+ * // Mutation executes automatically when source changes
+ * updateUserSource.set({ userId: 'user-123', email: 'newemail@example.com' });
+ * console.log(updateUser.status()); // 'loading'
+ * ```
+ *
+ * @example
+ * Business exceptions with `craftException`
+ * ```ts
+ * import { craftException, mutation } from '@craft-ts/core';
+ *
+ * const updateUser = craftUse(mutation('updateUser', {
+ *   method: (value: string) =>
+ *     value.length < 3
+ *       ? craftException(
+ *           { code: 'SEARCH_TERM_TOO_SHORT' },
+ *           { min: 3, received: value.length },
+ *         )
+ *       : value,
+ *   loader: async ({ params }) =>
+ *     params === 'blocked'
+ *       ? craftException(
+ *           { code: 'USER_ACCESS_FORBIDDEN' },
+ *           { id: params },
+ *         )
+ *       : { id: params, updated: true },
+ * }));
+ *
+ * updateUser.mutate('ab');
+ * console.log(updateUser.hasException()); // true
+ * console.log(updateUser.exceptions().params?.SEARCH_TERM_TOO_SHORT);
+ *
+ * updateUser.mutate('blocked');
+ * console.log(updateUser.exceptions().loader?.USER_ACCESS_FORBIDDEN);
+ * ```
+ *
+ * @example
+ * Mutation with identifier for grouping
+ * ```ts
+ * const deleteItem = craftUse(mutation('deleteItem', {
+ *   method: (itemId: string) => ({ itemId }),
+ *   identifier: (params) => params.itemId,
+ *   loader: async ({ params }) => {
+ *     await fetch(`/api/items/${params.itemId}`, { method: 'DELETE' });
+ *     return { deleted: true };
+ *   },
+ * }));
+ *
+ * // Trigger mutations for different items
+ * deleteItem.mutate('item-1');
+ * deleteItem.mutate('item-2');
+ *
+ * // Access individual mutation states
+ * const item1Mutation = deleteItem.select('item-1');
+ * console.log(item1Mutation?.status()); // 'loading' or 'resolved'
+ * console.log(item1Mutation?.value()); // { deleted: true }
+ * ```
+ *
+ * @example
+ * With custom methods via insertions
+ * ```ts
+ * const createPost = craftUse(mutation(
+ *   'createPost',
+ *   {
+ *     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();
+ *     },
+ *   },
+ *   ({ value, isLoading }) => ({
+ *     isSuccess: computed(() => value() !== undefined && !isLoading()),
+ *     reset: () => {
+ *       // Custom reset logic
+ *     },
+ *   })
+ * ));
+ *
+ * createPost.mutate({ title: 'Hello', content: 'World' });
+ * console.log(createPost.isSuccess()); // Custom computed from insertion
+ * ```
+ *
+ * @example
+ * Binding to another ResourceByIdRef
+ * ```ts
+ * // First, create a source mutation by ID
+ * const fetchUsers = craftUse(mutation('fetchUsers', {
+ *   method: (userId: string) => ({ userId }),
+ *   identifier: (params) => params.userId,
+ *   loader: async ({ params }) => {
+ *     const response = await fetch(`/api/users/${params.userId}`);
+ *     return response.json();
+ *   },
+ * }));
+ *
+ * // Then create a derived mutation that processes the results
+ * const processedUsers = craftUse(mutation('processedUsers', {
+ *   fromResourceById: fetchUsers,
+ *   params: ({ value, status }) => {
+ *     // Only process when the source is resolved
+ *     return status() === 'resolved' ? value() : undefined;
+ *   },
+ *   identifier: (params) => params.userId,
+ *   loader: async ({ params }) => {
+ *     // Process the user data
+ *     return {
+ *       ...params,
+ *       processed: true,
+ *       timestamp: Date.now(),
+ *     };
+ *   },
+ * }));
+ *
+ * // Trigger the source mutation
+ * fetchUsers.mutate('user-123');
+ *
+ * // The derived mutation automatically executes when fetchUsers resolves
+ * // Access the processed result
+ * const processed = processedUsers.select('user-123');
+ * console.log(processed?.value()); // { userId: 'user-123', processed: true, ... }
+ * ```
+ */
+export function mutation(name, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+mutationConfig, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+...insertions
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+) {
+    return createNamedPrimitiveGen(name, createMutationRef(name, mutationConfig, ...insertions));
+}
+function createMutationRef(name, mutationConfig, ...insertions) {
+    const insertionSnapshotRegistry = new InsertionSnapshotRegistry();
+    const mutationExtraProviders = [
+        {
+            provide: INSERTION_SNAPSHOT_REGISTRY,
+            useValue: insertionSnapshotRegistry,
+        },
+        ...(mutationConfig.providers ?? []),
+    ];
+    let injector;
+    if ([
+        'params' in mutationConfig ? mutationConfig.params : undefined,
+        'method' in mutationConfig ? mutationConfig.method : undefined,
+        'loader' in mutationConfig ? mutationConfig.loader : undefined,
+        'stream' in mutationConfig ? mutationConfig.stream : undefined,
+        ...insertions,
+    ].some((value) => isGeneratorFunction(value))) {
+        assertInInjectionContext(mutation);
+        injector = ɵcreateHostTaggedInjector(inject(Injector), `mutation:${name}`, mutationExtraProviders);
+    }
+    const getInjector = () => {
+        if (!injector) {
+            assertInInjectionContext(mutation);
+            injector = ɵcreateHostTaggedInjector(inject(Injector), `mutation:${name}`, mutationExtraProviders);
+        }
+        return injector;
+    };
+    const mutationResourceParamsFnSignal = 
+    //@ts-expect-error if no params, it will create a signal
+    mutationConfig.params ?? signal(undefined);
+    // Incremented on every explicit mutate() so the resource request always changes,
+    // forcing the loader to re-run even when the method returns the same value or
+    // `undefined`. Starts at 0 = "never called" to preserve idle.
+    const methodTriggerSeq = signal(0);
+    const isConnectedToAResourceById = 'fromResourceById' in mutationConfig;
+    const isConnectedToSource = 'method' in mutationConfig && isSignal(mutationConfig.method);
+    const hasMethodFn = 'method' in mutationConfig &&
+        typeof mutationConfig.method === 'function' &&
+        !isSignal(mutationConfig.method);
+    const isUsingIdentifier = 'identifier' in mutationConfig;
+    const methodParamsException = signal(undefined);
+    const schemaParseExceptions = signal({});
+    const configuredSchemas = {
+        method: mutationConfig.methodSchema,
+        params: mutationConfig.paramsSchema,
+        loader: mutationConfig.loaderSchema,
+    };
+    const hasConfiguredSchema = Object.values(configuredSchemas).some(Boolean);
+    const setSchemaException = (stage, exception) => {
+        untracked(() => {
+            schemaParseExceptions.update((current) => {
+                const next = { ...current };
+                if (exception)
+                    next[stage] = exception;
+                else
+                    delete next[stage];
+                return next;
+            });
+        });
+    };
+    const schemaPolicy = useSchemaValidationPolicy(getInjector(), mutationConfig.schemaValidationPolicy);
+    const schemaValidation = {
+        method: createSchemaValidationRuntime({
+            schema: configuredSchemas.method,
+            primitive: 'mutation',
+            name,
+            policy: schemaPolicy,
+            setException: setSchemaException,
+        }),
+        params: createSchemaValidationRuntime({
+            schema: configuredSchemas.params,
+            primitive: 'mutation',
+            name,
+            policy: schemaPolicy,
+            setException: setSchemaException,
+        }),
+        loader: createSchemaValidationRuntime({
+            schema: configuredSchemas.loader,
+            primitive: 'mutation',
+            name,
+            policy: schemaPolicy,
+            setException: setSchemaException,
+        }),
+    };
+    const schemaParse = computed(() => {
+        const values = schemaParseExceptions();
+        return {
+            ...(values['method'] ? { method: values['method'] } : {}),
+            ...(values['params'] ? { params: values['params'] } : {}),
+            ...(values['loader'] ? { loader: values['loader'] } : {}),
+        };
+    });
+    const getIdentifierFromParams = (params) => {
+        if (!isUsingIdentifier || !('identifier' in mutationConfig)) {
+            return undefined;
+        }
+        if (params === undefined || params === null) {
+            return undefined;
+        }
+        return mutationConfig.identifier?.(params);
+    };
+    const sanitizeParamsResult = (value) => {
+        if (isCraftException(value)) {
+            return undefined;
+        }
+        return value;
+    };
+    const reactiveParamsException = computed(() => {
+        if (hasMethodFn) {
+            return undefined;
+        }
+        const schemaParamsException = schemaParseExceptions()['params'];
+        if (schemaParamsException) {
+            return enrichResourceException(schemaParamsException, {
+                scope: 'params',
+            });
+        }
+        if (isConnectedToSource &&
+            'method' in mutationConfig &&
+            mutationConfig.method) {
+            const sourceValue = mutationConfig.method();
+            return isCraftException(sourceValue)
+                ? enrichResourceException(sourceValue, { scope: 'params' })
+                : undefined;
+        }
+        if ('params' in mutationConfig &&
+            !('fromResourceById' in mutationConfig && mutationConfig.fromResourceById)) {
+            const paramsValue = executeGeneratorCompatibleFactory({
+                factory: mutationConfig.params,
+                thisArg: undefined,
+                getInjector,
+                args: [],
+                invalidYieldErrorMessage: MUTATION_INVALID_YIELD_ERROR_MESSAGE,
+                multipleAppStartErrorMessage: MUTATION_APP_START_ERROR_MESSAGE,
+                onAppStartNotSupportedErrorMessage: MUTATION_APP_START_ERROR_MESSAGE,
+            });
+            return isCraftException(paramsValue)
+                ? enrichResourceException(paramsValue, { scope: 'params' })
+                : undefined;
+        }
+        return undefined;
+    });
+    const paramsException = computed(() => {
+        return hasMethodFn ? methodParamsException() : reactiveParamsException();
+    });
+    const { setLoaderException, exceptions, hasException, createSelectExceptions, createSelectHasException, } = createResourceExceptionsRuntime({
+        isUsingIdentifier,
+        paramsException,
+    });
+    const wrappedParamsFn = 'params' in mutationConfig
+        ? ((...args) => {
+            const value = executeGeneratorCompatibleFactory({
+                factory: mutationConfig.params,
+                thisArg: undefined,
+                getInjector,
+                args,
+                invalidYieldErrorMessage: MUTATION_INVALID_YIELD_ERROR_MESSAGE,
+                multipleAppStartErrorMessage: MUTATION_APP_START_ERROR_MESSAGE,
+                onAppStartNotSupportedErrorMessage: MUTATION_APP_START_ERROR_MESSAGE,
+            });
+            if (!configuredSchemas.params || isCraftException(value)) {
+                return sanitizeParamsResult(value);
+            }
+            const parsed = schemaValidation.params.parseSync(value, 'params', 'params');
+            return parsed.accepted ? parsed.value : undefined;
+        })
+        : undefined;
+    const wrappedSourceParams = isConnectedToSource && 'method' in mutationConfig && mutationConfig.method
+        ? (() => {
+            const value = sanitizeParamsResult(mutationConfig.method());
+            if (!configuredSchemas.params || isCraftException(value))
+                return value;
+            const parsed = schemaValidation.params.parseSync(value, 'params', 'source');
+            return parsed.accepted ? parsed.value : undefined;
+        })
+        : undefined;
+    const wrappedLoader = 'loader' in mutationConfig && mutationConfig.loader
+        ? (async (param) => {
+            const injector = getInjector();
+            const correlationSvc = injector.get(CORRELATION_ID_SERVICE, null);
+            const operationId = correlationSvc?.lastCorrelationId() ?? null;
+            if (operationId)
+                correlationSvc?.startOperation(operationId);
+            // Unwrap the method-trigger nonce so the user loader and identifier logic
+            // only ever see plain params (no-op for source / params-fn / byId modes).
+            const rawParams = unwrapMethodParams(param.params);
+            const loaderParam = { ...param, params: rawParams };
+            try {
+                const step = await executeGeneratorCompatibleFactoryAsync({
+                    factory: mutationConfig.loader,
+                    thisArg: undefined,
+                    getInjector,
+                    args: [loaderParam],
+                    invalidYieldErrorMessage: MUTATION_INVALID_YIELD_ERROR_MESSAGE,
+                    appStartNotSupportedErrorMessage: MUTATION_APP_START_ERROR_MESSAGE,
+                    // A retriggered mutation keeps its already-started operation
+                    // valid; unlike query, do not bind temporal awaits to the
+                    // resource's superseded-load abort signal.
+                });
+                if (step.kind === 'shortCircuit') {
+                    const exceptionId = getIdentifierFromParams(rawParams);
+                    setLoaderException(enrichResourceException(step.exception, {
+                        scope: 'loader',
+                        identifier: exceptionId,
+                    }), exceptionId);
+                    return undefined;
+                }
+                const result = step.value;
+                if (isCraftException(result)) {
+                    const exceptionId = getIdentifierFromParams(rawParams);
+                    setLoaderException(enrichResourceException(result, {
+                        scope: 'loader',
+                        identifier: exceptionId,
+                    }), exceptionId);
+                    return undefined;
+                }
+                let validatedResult = result;
+                if (configuredSchemas.loader) {
+                    const parsed = await schemaValidation.loader.parseAsync(result, 'loader', 'loader', getIdentifierFromParams(rawParams));
+                    if (!parsed.accepted) {
+                        const exceptionId = getIdentifierFromParams(rawParams);
+                        setLoaderException(enrichResourceException(parsed.exception, {
+                            scope: 'loader',
+                            identifier: exceptionId,
+                        }), exceptionId);
+                        return undefined;
+                    }
+                    validatedResult = parsed.value;
+                }
+                const successId = getIdentifierFromParams(rawParams);
+                setLoaderException(undefined, successId);
+                return validatedResult;
+            }
+            catch (error) {
+                if (!isCraftException(error)) {
+                    injector.get(TAKE_APP_SNAPSHOT, null)?.();
+                }
+                throw error;
+            }
+            finally {
+                if (operationId)
+                    correlationSvc?.endOperation(operationId);
+            }
+        })
+        : undefined;
+    const wrappedStream = 'stream' in mutationConfig && mutationConfig.stream
+        ? ((...args) => {
+            const result = executeGeneratorCompatibleFactory({
+                factory: mutationConfig.stream,
+                thisArg: undefined,
+                getInjector,
+                args,
+                invalidYieldErrorMessage: MUTATION_INVALID_YIELD_ERROR_MESSAGE,
+                multipleAppStartErrorMessage: MUTATION_APP_START_ERROR_MESSAGE,
+                onAppStartNotSupportedErrorMessage: MUTATION_APP_START_ERROR_MESSAGE,
+            });
+            const wrapStreamSignal = (streamSignal) => {
+                if (!configuredSchemas.loader || !isSignal(streamSignal)) {
+                    return streamSignal;
+                }
+                let lastValue;
+                return computed(() => {
+                    const streamItem = streamSignal();
+                    if (streamItem &&
+                        typeof streamItem === 'object' &&
+                        'error' in streamItem) {
+                        return streamItem;
+                    }
+                    const rawValue = streamItem &&
+                        typeof streamItem === 'object' &&
+                        'value' in streamItem
+                        ? streamItem.value
+                        : streamItem;
+                    const parsed = schemaValidation.loader.parseSync(rawValue, 'loader', 'stream');
+                    if (!parsed.accepted) {
+                        return lastValue === undefined
+                            ? undefined
+                            : { value: lastValue };
+                    }
+                    lastValue = parsed.value;
+                    return { value: lastValue };
+                });
+            };
+            if (result &&
+                typeof result.then === 'function') {
+                return Promise.resolve(result).then(wrapStreamSignal);
+            }
+            return wrapStreamSignal(result);
+        })
+        : undefined;
+    const resourceParamsSrc = isConnectedToSource
+        ? wrappedSourceParams
+        : (wrappedParamsFn ?? mutationResourceParamsFnSignal);
+    // Method-based, non-grouped: feed the resource a nonce-tagged request so every
+    // explicit mutate() re-runs the loader (even for identical / `undefined` params),
+    // while `resourceParamsSrc` stays the raw signal for all public consumers.
+    const methodTaggedParams = computed(() => {
+        const seq = methodTriggerSeq();
+        if (seq === 0)
+            return undefined; // idle until the first call
+        return wrapMethodParams(mutationResourceParamsFnSignal(), seq);
+    });
+    const mutationResourceOptions = {
+        ...mutationConfig,
+        params: hasMethodFn
+            ? methodTaggedParams
+            : resourceParamsSrc,
+        equal: hasMethodFn
+            ? methodParamsWrapperEqual(mutationConfig.equal)
+            : mutationConfig.equal,
+        loader: wrappedLoader,
+        stream: wrappedStream,
+    };
+    const resourceTarget = isUsingIdentifier
+        ? resourceById({
+            ...mutationConfig,
+            params: resourceParamsSrc,
+            loader: wrappedLoader,
+            stream: wrappedStream,
+            identifier: mutationConfig.identifier,
+        })
+        : mutationConfig.preservePreviousValue?.()
+            ? preservedResource(mutationResourceOptions)
+            : craftResource(mutationResourceOptions);
+    if (configuredSchemas.loader) {
+        const target = resourceTarget;
+        const originalResourceSet = target.set.bind(target);
+        const originalResourceUpdate = target.update.bind(target);
+        target.set = (value) => {
+            const parsed = schemaValidation.loader.parseSync(value, 'loader', 'set');
+            if (parsed.accepted)
+                originalResourceSet(parsed.value);
+        };
+        target.update = (updateFn) => originalResourceUpdate((current) => {
+            const parsed = schemaValidation.loader.parseSync(updateFn(current), 'loader', 'update');
+            return parsed.accepted ? parsed.value : current;
+        });
+    }
+    runInInjectionContext(getInjector(), () => ɵobservePrimitiveResourceRuntimeContext(isUsingIdentifier
+        ? ɵcreatePrimitiveResourceByIdRuntimeContext('mutation', resourceTarget)
+        : ɵcreatePrimitiveResourceRuntimeContext('mutation', resourceTarget), name));
+    // Capture the raw Angular status BEFORE `Object.assign` overrides
+    // `resourceTarget.status` with the craft computed (avoids a computation cycle).
+    const rawResourceStatus = resourceTarget.status;
+    const publicExceptions = hasConfiguredSchema
+        ? computed(() => ({ ...exceptions(), parse: schemaParse() }))
+        : exceptions;
+    const output = Object.assign(resourceTarget, 
+    // byId is used to helps TS to correctly infer the resourceByGroup
+    isUsingIdentifier
+        ? {
+            /**
+             * Only added to help TS inference (TS cannot infer ResourceByIdHandler without erasing the signal getter, () => ResourceByIdRef<...>) )
+             */
+            _resourceById: resourceTarget,
+            select: (id) => {
+                const selectExceptions = createSelectExceptions(id);
+                const selectHasException = createSelectHasException(id);
+                return computed(() => {
+                    const list = resourceTarget();
+                    //@ts-expect-error GroupIdentifier & string is not recognized correctly
+                    const resource = list[id];
+                    if (!resource) {
+                        return undefined;
+                    }
+                    const rawSelectStatus = resource.status;
+                    const result = Object.assign(resource, {
+                        status: computed(() => toCraftStatus(rawSelectStatus(), selectHasException())),
+                        exception: computed(() => selectExceptions().list[0]),
+                        hasException: selectHasException,
+                        hasSchema: signal(hasConfiguredSchema),
+                        exceptions: hasConfiguredSchema
+                            ? computed(() => ({
+                                ...selectExceptions(),
+                                parse: schemaParse(),
+                            }))
+                            : selectExceptions,
+                    });
+                    attachCraftSettledValue(name, result);
+                    return result;
+                })();
+            },
+            selectOrCreate: (id) => {
+                const selected = resourceTarget.addById(id);
+                const selectExceptions = createSelectExceptions(id);
+                const selectHasException = createSelectHasException(id);
+                const rawSelectStatus = selected.status;
+                const result = Object.assign(selected, {
+                    status: computed(() => toCraftStatus(rawSelectStatus(), selectHasException())),
+                    exception: computed(() => selectExceptions().list[0]),
+                    hasException: selectHasException,
+                    hasSchema: signal(hasConfiguredSchema),
+                    exceptions: hasConfiguredSchema
+                        ? computed(() => ({
+                            ...selectExceptions(),
+                            parse: schemaParse(),
+                        }))
+                        : selectExceptions,
+                });
+                attachCraftSettledValue(name, result);
+                return result;
+            },
+        }
+        : {}, {
+        type: isUsingIdentifier ? 'resourceByGroupLike' : 'resourceLike',
+        kind: 'mutation',
+        ...(isUsingIdentifier
+            ? {}
+            : {
+                status: computed(() => toCraftStatus(rawResourceStatus(), hasException())),
+                exception: computed(() => exceptions().list[0]),
+            }),
+        hasException,
+        hasSchema: signal(hasConfiguredSchema),
+        exceptions: publicExceptions,
+        resourceParamsSrc: resourceParamsSrc,
+        mutate: isConnectedToAResourceById ||
+            ('method' in mutationConfig && isSignal(mutationConfig.method))
+            ? undefined
+            : (arg) => {
+                let methodArg = arg;
+                if (configuredSchemas.method) {
+                    const parsedMethod = schemaValidation.method.parseSync(arg, 'method', 'method');
+                    if (!parsedMethod.accepted) {
+                        methodParamsException.set(enrichResourceException(parsedMethod.exception, {
+                            scope: 'params',
+                        }));
+                        return yieldableInvocation(parsedMethod.exception);
+                    }
+                    methodArg = parsedMethod.value;
+                }
+                const result = 'method' in mutationConfig
+                    ? executeGeneratorCompatibleFactory({
+                        factory: mutationConfig.method,
+                        thisArg: undefined,
+                        getInjector,
+                        args: [methodArg],
+                        invalidYieldErrorMessage: MUTATION_INVALID_YIELD_ERROR_MESSAGE,
+                        multipleAppStartErrorMessage: MUTATION_APP_START_ERROR_MESSAGE,
+                        onAppStartNotSupportedErrorMessage: MUTATION_APP_START_ERROR_MESSAGE,
+                    })
+                    : undefined;
+                if (isCraftException(result)) {
+                    methodParamsException.set(enrichResourceException(result, { scope: 'params' }));
+                    return yieldableInvocation(result);
+                }
+                let paramsResult = result;
+                if (configuredSchemas.params) {
+                    const parsedParams = schemaValidation.params.parseSync(result, 'params', 'method');
+                    if (!parsedParams.accepted) {
+                        methodParamsException.set(enrichResourceException(parsedParams.exception, {
+                            scope: 'params',
+                        }));
+                        return yieldableInvocation(parsedParams.exception);
+                    }
+                    paramsResult = parsedParams.value;
+                }
+                if (methodParamsException()) {
+                    methodParamsException.set(undefined);
+                }
+                // The nonce and the params it tags are ONE request. Published
+                // separately they are two: the resource would see the new nonce
+                // while the params signal still holds the previous call's value
+                // (`undefined` on the first one) and run the loader on it before
+                // running it again on the real params.
+                batch(() => {
+                    methodTriggerSeq.update((n) => n + 1);
+                    // set before calling addById below, which reads the params
+                    mutationResourceParamsFnSignal.set(paramsResult);
+                });
+                if (isUsingIdentifier) {
+                    const id = mutationConfig.identifier?.(paramsResult);
+                    resourceTarget.addById(id);
+                }
+                return yieldableInvocation(paramsResult);
+            },
+    });
+    if (!isUsingIdentifier) {
+        attachCraftSettledValue(name, output);
+    }
+    const publicMutationContext = createYieldableReactiveFacade(output, {
+        name,
+        primitive: 'mutation',
+        path: name,
+    });
+    const insertionSettledState = isUsingIdentifier
+        ? createYieldableSettledValue(computed(() => {
+            const params = craftUse(publicMutationContext.resourceParamsSrc());
+            if (params == null)
+                throw new CraftNotSettled(name);
+            const id = mutationConfig.identifier?.(params);
+            if (id == null)
+                throw new CraftNotSettled(name);
+            const selected = publicMutationContext.select(id);
+            if (!selected)
+                throw new CraftNotSettled(name);
+            return craftUse(selected.settledValue());
+        }), {
+            primitive: 'mutation',
+            insertion: 'settledState',
+            path: `${name}.settledState`,
+        })
+        : createYieldableSettledValue(computed(() => craftUse(publicMutationContext.settledValue())), {
+            primitive: 'mutation',
+            insertion: 'settledState',
+            path: `${name}.settledState`,
+        });
+    const insertionsResult = insertions?.reduce((acc, insert) => {
+        const rawResult = executeGeneratorCompatibleFactory({
+            factory: insert,
+            thisArg: undefined,
+            getInjector,
+            args: [
+                {
+                    ...(isUsingIdentifier
+                        ? {
+                            resourceById: createYieldableReactiveFacade(resourceTarget, {
+                                name: 'resourceById',
+                                primitive: 'mutation',
+                                path: `${name}.resourceById`,
+                            }),
+                            identifier: mutationConfig.identifier,
+                        }
+                        : { resource: publicMutationContext }),
+                    resourceParamsSrc: publicMutationContext.resourceParamsSrc,
+                    hasException: publicMutationContext.hasException,
+                    exceptions: publicMutationContext.exceptions,
+                    insertions: acc,
+                    state: publicMutationContext.state,
+                    settledState: insertionSettledState,
+                    set: (nextState) => yieldableInvocation(resourceTarget.set(nextState)),
+                    update: (updateFn) => yieldableInvocation(resourceTarget.update(updateFn)),
+                    patch: (patchFn) => yieldableInvocation(resourceTarget.update((current) => ({
+                        ...current,
+                        ...patchFn(current),
+                    }))),
+                    __primitiveKind: 'mutation',
+                },
+            ],
+            invalidYieldErrorMessage: MUTATION_INVALID_YIELD_ERROR_MESSAGE,
+            multipleAppStartErrorMessage: MUTATION_APP_START_ERROR_MESSAGE,
+            onAppStartNotSupportedErrorMessage: MUTATION_APP_START_ERROR_MESSAGE,
+        });
+        const wrappedResult = Object.entries(rawResult).reduce((wrappedAcc, [key, value]) => {
+            if (typeof value === 'function' &&
+                !isSignal(value) &&
+                !isYieldableReactiveValue(value) &&
+                !isNonYieldableInsertionMethod(value)) {
+                const injector = getInjector();
+                const methodInjector = ɵcreateHostTaggedInjector(injector, `method:${key}`, [
+                    ɵprovidePrimitiveMethodRuntimeContext('mutation', {
+                        state: resourceTarget.state,
+                        set: resourceTarget.set,
+                        update: resourceTarget.update,
+                        patch: (patchFn) => resourceTarget.update((current) => ({
+                            ...current,
+                            ...patchFn(current),
+                        })),
+                    }, value),
+                ]);
+                const wrappedFn = runInInjectionContext(methodInjector, () => injectFnWrapper()(value));
+                wrappedAcc[key] = createYieldableInsertionMethod(wrappedFn, {
+                    injector: methodInjector,
+                    invalidYieldErrorMessage: MUTATION_INVALID_YIELD_ERROR_MESSAGE,
+                    multipleAppStartErrorMessage: MUTATION_APP_START_ERROR_MESSAGE,
+                    onAppStartNotSupportedErrorMessage: MUTATION_APP_START_ERROR_MESSAGE,
+                });
+            }
+            else {
+                const namedValue = nameInsertedReactiveValue(value, key, 'mutation', `${name}.${key}`);
+                wrappedAcc[key] = createYieldableReactiveFacade(namedValue, {
+                    name: key,
+                    primitive: 'mutation',
+                    insertion: key,
+                    path: `${name}.${key}`,
+                });
+            }
+            return wrappedAcc;
+        }, {});
+        return { ...acc, ...wrappedResult };
+    }, {});
+    Object.assign(output, insertionsResult);
+    const snapshotRegistry = injector
+        ? injector.get(APP_SNAPSHOT_REGISTRY, null)
+        : (() => {
+            try {
+                return inject(APP_SNAPSHOT_REGISTRY, { optional: true });
+            }
+            catch {
+                return null;
+            }
+        })();
+    const hostTagList = injector
+        ? (injector.get(ɵHOST_TAG_LIST, null) ?? [])
+        : (() => {
+            try {
+                return inject(ɵHOST_TAG_LIST, { optional: true }) ?? [];
+            }
+            catch {
+                return [];
+            }
+        })();
+    const destroyRefMutation = injector
+        ? injector.get(DestroyRef, null)
+        : (() => {
+            try {
+                return inject(DestroyRef, { optional: true });
+            }
+            catch {
+                return null;
+            }
+        })();
+    if (snapshotRegistry && destroyRefMutation) {
+        snapshotRegistry.triggerSnapshot$
+            .pipe(takeUntilDestroyed(destroyRefMutation))
+            .subscribe(() => {
+            const insertionSnapshots = triggerAndCollectInsertions(insertionSnapshotRegistry);
+            let stateSnapshot;
+            try {
+                if (isUsingIdentifier) {
+                    const byId = resourceTarget();
+                    stateSnapshot = {
+                        params: resourceParamsSrc(),
+                        resources: Object.entries(byId ?? {}).reduce((acc, [id, res]) => {
+                            acc[id] = res?.state?.();
+                            return acc;
+                        }, {}),
+                        ...(insertionSnapshots ? { insertions: insertionSnapshots } : {}),
+                    };
+                }
+                else {
+                    const resourceState = resourceTarget.state();
+                    stateSnapshot = {
+                        params: resourceParamsSrc(),
+                        ...resourceState,
+                        ...(insertionSnapshots ? { insertions: insertionSnapshots } : {}),
+                    };
+                }
+            }
+            catch (error) {
+                stateSnapshot = {
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+            snapshotRegistry.allSnapShot$.next({
+                source: 'mutation',
+                from: hostTagList,
+                state: stateSnapshot,
+            });
+        });
+    }
+    if (!('resource' in output)) {
+        Object.defineProperty(output, 'resource', {
+            value: output,
+            enumerable: false,
+            configurable: true,
+        });
+    }
+    const publicMutation = createYieldableReactiveFacade(output, {
+        name,
+        primitive: 'mutation',
+        path: name,
+    });
+    return (hasDeepYieldableInsertion(insertions)
+        ? deepYieldable(publicMutation)
+        : publicMutation);
+}
+//# sourceMappingURL=mutation.js.map