@craft-ts/core 0.7.0-beta.13

package/src/lib/query.js

@@ -0,0 +1,971 @@
+import { assertInInjectionContext, 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 { preservedResource } from './preserved-resource';
+import { craftResource } from './craft-resource';
+import { isCraftException, } from './craft-exception';
+import { createResourceExceptionsRuntime, enrichResourceException, } from './resource-exception';
+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';
+import { createSchemaValidationRuntime, useSchemaValidationPolicy, } from './schema-validation';
+const QUERY_INVALID_YIELD_ERROR_MESSAGE = 'query generators can only yield craftService dependencies or exposed dependency helpers.';
+const QUERY_APP_START_ERROR_MESSAGE = 'query generators do not support onAppStart(...).';
+/**
+ * Creates a reactive query manager that handles data fetching with automatic state tracking.
+ *
+ * This function manages query state by:
+ * - Executing asynchronous fetch operations (loader or stream) automatically when params change
+ * - Tracking operation status (idle, loading, resolved, exception)
+ * - Providing reactive signals for value, status, exceptions, and loading state
+ * - Supporting both params-based automatic execution and method-based manual triggers
+ * - Optionally enabling parallel query execution by grouping instances with an identifier
+ * - Caching and reusing query results based on params
+ *
+ * @remarks
+ * **Important:** This function must be called within an injection context.
+ *
+ * **Query Modes:**
+ * - **Params-based (automatic):** Define a `params` function. The query executes automatically when params change.
+ * - **Method-based (manual):** Define a `method` function that returns params. Call `call()` to trigger execution.
+ * - **Source-based (reactive):** Bind to a `ReadonlySource` for automatic execution when the source changes.
+ * - **Resource-based (derived):** Bind to another `ResourceByIdRef` using `fromResourceById` to create derived queries.
+ *
+ * **With Identifier:**
+ * When an `identifier` function is provided, queries are grouped by ID enabling parallel execution and individual result tracking.
+ * Use `select(id)` to access individual query instances.
+ * Use `selectOrCreate(id)` to access an instance, creating it when it does not exist yet.
+ *
+ * **Caching & Performance:**
+ * - Use `preservePreviousValue: () => true` to prevent flickering by keeping previous data while loading
+ * - Use `equalParams` to control when queries should re-execute based on params comparison
+ *
+ * @param name - The query name. Used for host tagging and reactive branding
+ *   (`const userQuery = yield* query('userQuery', config)`) and as the
+ *   injector host tag (`query:userQuery`), so the query is precisely locatable
+ *   in snapshots and logs.
+ * @param config - Configuration object containing:
+ *   - `params`: Function that returns params for automatic execution, or undefined for method-based queries
+ *   - `method`: Function that takes args and returns params for manual execution, or a `ReadonlySource` for reactive execution
+ *   - `loader`: Async function that performs the query 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 queries
+ *   - `fromResourceById` (optional): Bind to another ResourceByIdRef for derived queries
+ *   - `preservePreviousValue` (optional): Function returning boolean to keep previous value while reloading
+ *   - `equalParams` (optional): Controls params comparison ('default' | 'useIdentifier' | custom function)
+ *   - Additional ResourceOptions like `equal`, `injector`, etc.
+ * @param insertion1 - Optional single insertion factory to add custom methods, computed values or side effects to the query.
+ *   The insertion receives a context with resource signals (`state`, `exceptions`, `hasException`, `resource`) and mutators (`set`, `update`, `patch`).
+ *   To attach several insertions, compose them with `insertQueryPipe`:
+ *   `query('name', config, insertQueryPipe(insertion1, insertion2))` —
+ *   each member then also sees the previous members' outputs on `context.insertions`.
+ * @returns A single-use primitive generator resolving to a query reference
+ *   object with:
+ *   - `value`: Signal containing the query 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 query is currently executing
+ *   - `hasValue()`: Method to check if a value is available
+ *   - `call(args)`: Method to trigger the query manually (only for method-based queries)
+ *   - `source`: The connected source (only for source-based queries)
+ *   - `select(id)`: Method to access a specific query instance by ID (only when identifier is provided)
+ *   - `selectOrCreate(id)`: Method to access or create a specific query instance (only when identifier is provided)
+ *   - `resourceParamsSrc`: The underlying params signal
+ *   - Custom methods from insertions
+ *
+ *   Consume it with `yield*` inside a generator host (craftService factory,
+ *   craftGen, …) or with `craftUse(...)` elsewhere (typically a component field).
+ *
+ * @example
+ * Basic params-based automatic query
+ * ```ts
+ * const userIdSignal = signal('user-123');
+ *
+ * const userQuery = craftUse(query('userQuery', {
+ *   params: () => userIdSignal(),
+ *   loader: function* ({ params }) {
+ *     return yield* CraftHttpClient.get(({ response }) => ({
+ *       url: `/api/users/${params}`,
+ *       success: response<{ id: string; name: string }>(),
+ *     }));
+ *   },
+ * }));
+ *
+ * // Query executes automatically when created and when userIdSignal changes
+ * console.log(userQuery.status()); // 'loading'
+ * // After completion
+ * console.log(userQuery.value()); // { id: 'user-123', name: '...' }
+ * console.log(userQuery.status()); // 'resolved'
+ *
+ * // Changing the signal triggers a new query
+ * userIdSignal.set('user-456');
+ * ```
+ *
+ * @example
+ * Method-based manual query
+ * ```ts
+ * const searchQuery = craftUse(query('searchQuery', {
+ *   method: (searchTerm: string) => ({ term: searchTerm }),
+ *   loader: function* ({ params }) {
+ *     return yield* CraftHttpClient.get(({ response }) => ({
+ *       url: `/api/search?q=${params.term}`,
+ *       success: response<Array<{ id: string; title: string }>>(),
+ *     }));
+ *   },
+ * }));
+ *
+ * // Query doesn't execute automatically
+ * console.log(searchQuery.status()); // 'idle'
+ *
+ * // Manually trigger the query
+ * searchQuery.call('angular');
+ * console.log(searchQuery.status()); // 'loading'
+ * ```
+ *
+ * @example
+ * Business exceptions with `craftException`
+ * ```ts
+ * import { craftException, query } from '@craft-ts/core';
+ *
+ * const userQuery = craftUse(query('userQuery', {
+ *   method: (value: string) =>
+ *     value.length < 3
+ *       ? craftException(
+ *           { code: 'SEARCH_TERM_TOO_SHORT' },
+ *           { min: 3, received: value.length },
+ *         )
+ *       : value,
+ *   loader: function* ({ params }) {
+ *     return params === 'forbidden'
+ *       ? craftException(
+ *           { code: 'USER_ACCESS_FORBIDDEN' },
+ *           { id: params },
+ *         )
+ *       : { id: params, name: 'John Doe' };
+ *   },
+ * }));
+ *
+ * userQuery.call('ab');
+ * console.log(userQuery.hasException()); // true
+ * console.log(userQuery.exceptions().params?.SEARCH_TERM_TOO_SHORT);
+ *
+ * userQuery.call('forbidden');
+ * console.log(userQuery.exceptions().loader?.USER_ACCESS_FORBIDDEN);
+ * ```
+ *
+ * @example
+ * Query with identifier for parallel execution
+ * ```ts
+ * const userDetailsQuery = craftUse(query('userDetailsQuery', {
+ *   params: () => currentUserId(),
+ *   identifier: (userId) => userId,
+ *   loader: function* ({ params }) {
+ *     return yield* CraftHttpClient.get(({ response }) => ({
+ *       url: `/api/users/${params}`,
+ *       success: response<{ id: string; name: string }>(),
+ *     }));
+ *   },
+ * }));
+ *
+ * // Multiple users can be queried in parallel
+ * // Each has its own state tracked by identifier
+ * const user1 = userDetailsQuery.select('user-1');
+ * const user2 = userDetailsQuery.select('user-2');
+ *
+ * console.log(user1?.status()); // 'resolved'
+ * console.log(user1?.value()); // { id: 'user-1', ... }
+ * console.log(user2?.status()); // 'loading'
+ * ```
+ *
+ * @example
+ * With custom methods via insertions
+ * ```ts
+ * const todosQuery = craftUse(query(
+ *   'todosQuery',
+ *   {
+ *     params: () => ({ completed: showCompleted() }),
+ *     loader: function* ({ params }) {
+ *       return yield* CraftHttpClient.get(({ response }) => ({
+ *         url: `/api/todos?completed=${params.completed}`,
+ *         success: response<Array<{ id: string; completed: boolean }>>(),
+ *       }));
+ *     },
+ *   },
+ *   ({ value, isLoading }) => ({
+ *     count: computed(() => value()?.length ?? 0),
+ *     isEmpty: computed(() => !isLoading() && value()?.length === 0),
+ *   })
+ * ));
+ *
+ * console.log(todosQuery.count()); // Custom computed from insertion
+ * console.log(todosQuery.isEmpty()); // true/false
+ * ```
+ *
+ * @example
+ * Streaming query
+ * ```ts
+ * const liveDataQuery = craftUse(query('liveDataQuery', {
+ *   params: () => ({ channel: currentChannel() }),
+ *   stream: async ({ params }) => {
+ *     const response = await fetch(`/api/stream/${params.channel}`);
+ *
+ *     // Return a signal that updates as stream data arrives
+ *     const resultSignal = signal([]);
+ *     const reader = response.body?.getReader();
+ *     // ... process stream and update resultSignal
+ *     return resultSignal;
+ *   },
+ * }));
+ *
+ * // value() updates continuously as stream data arrives
+ * ```
+ *
+ * @example
+ * Derived query from another ResourceByIdRef
+ * ```ts
+ * // First query fetches basic user data
+ * const usersQuery = craftUse(query('usersQuery', {
+ *   params: () => currentUserId(),
+ *   identifier: (userId) => userId,
+ *   loader: function* ({ params }) {
+ *     return yield* CraftHttpClient.get(({ response }) => ({
+ *       url: `/api/users/${params}`,
+ *       success: response<{ id: string; name: string }>(),
+ *     }));
+ *   },
+ * }));
+ *
+ * // Derived query enriches user data with additional info
+ * const enrichedUsersQuery = craftUse(query('enrichedUsersQuery', {
+ *   fromResourceById: usersQuery,
+ *   params: ({ value, status }) => {
+ *     // Only process when source is resolved
+ *     return status() === 'resolved' ? value() : undefined;
+ *   },
+ *   identifier: (user) => user.id,
+ *   loader: function* ({ params }) {
+ *     const details = yield* CraftHttpClient.get(({ response }) => ({
+ *       url: `/api/users/${params.id}/details`,
+ *       success: response<{ bio: string }>(),
+ *     }));
+ *     return { ...params, ...details };
+ *   },
+ * }));
+ *
+ * // Derived query executes automatically when usersQuery resolves
+ * const enrichedUser = enrichedUsersQuery.select('user-123');
+ * console.log(enrichedUser?.value()); // { ...userData, ...details }
+ * ```
+ */
+export function query(name, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+queryConfig, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+...insertions
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+) {
+    return createNamedPrimitiveGen(name, createQueryRef(name, queryConfig, ...insertions));
+}
+function createQueryRef(name, queryConfig, ...insertions) {
+    const insertionSnapshotRegistry = new InsertionSnapshotRegistry();
+    const queryExtraProviders = [
+        {
+            provide: INSERTION_SNAPSHOT_REGISTRY,
+            useValue: insertionSnapshotRegistry,
+        },
+        ...(queryConfig.providers ?? []),
+    ];
+    let injector;
+    if ([
+        queryConfig.params,
+        queryConfig.method,
+        queryConfig.loader,
+        queryConfig.stream,
+        ...insertions,
+    ].some((value) => isGeneratorFunction(value))) {
+        assertInInjectionContext(query);
+        injector = ɵcreateHostTaggedInjector(inject(Injector), `query:${name}`, queryExtraProviders);
+    }
+    else {
+        // Capture the injector eagerly whenever `query()` is constructed inside an
+        // injection context (the normal case: a component field initializer or a
+        // craft-service factory). The resource's reactive `params`/`loader`
+        // computeds may FIRST run while driven from OUTSIDE an injection context —
+        // e.g. a non-blocking route guard awaiting the resource via
+        // `craftUntilSettled(...)`, which subscribes outside one. Without an eagerly
+        // captured injector, `getInjector()` below would fall back to the (absent)
+        // ambient context and throw.
+        //
+        // There is no `isInInjectionContext` on the Craft injector, so probe by
+        // attempting `inject(Injector)` and fall back to the lazy `getInjector()`
+        // if `query()` was genuinely constructed out of context.
+        try {
+            injector = ɵcreateHostTaggedInjector(inject(Injector), `query:${name}`, queryExtraProviders);
+        }
+        catch {
+            injector = undefined;
+        }
+    }
+    const getInjector = () => {
+        if (!injector) {
+            assertInInjectionContext(query);
+            injector = ɵcreateHostTaggedInjector(inject(Injector), `query:${name}`, queryExtraProviders);
+        }
+        return injector;
+    };
+    const hasMethodFn = typeof queryConfig.method === 'function' && !isSignal(queryConfig.method);
+    const queryResourceParamsFnSignal = queryConfig.params ?? signal(undefined);
+    // Incremented on every explicit call() 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 isConnectedToSource = isSignal(queryConfig.method);
+    const isUsingIdentifier = 'identifier' in queryConfig;
+    const methodParamsException = signal(undefined);
+    const schemaParseExceptions = signal({});
+    const configuredSchemas = {
+        method: queryConfig.methodSchema,
+        params: queryConfig.paramsSchema,
+        loader: queryConfig.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(), queryConfig.schemaValidationPolicy);
+    const schemaValidation = {
+        method: createSchemaValidationRuntime({
+            schema: configuredSchemas.method,
+            primitive: 'query',
+            name,
+            policy: schemaPolicy,
+            setException: setSchemaException,
+        }),
+        params: createSchemaValidationRuntime({
+            schema: configuredSchemas.params,
+            primitive: 'query',
+            name,
+            policy: schemaPolicy,
+            setException: setSchemaException,
+        }),
+        loader: createSchemaValidationRuntime({
+            schema: configuredSchemas.loader,
+            primitive: 'query',
+            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 queryConfig) ||
+            !queryConfig.identifier) {
+            return undefined;
+        }
+        if (params === undefined || params === null) {
+            return undefined;
+        }
+        return queryConfig.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 && queryConfig.method) {
+            const sourceValue = queryConfig.method();
+            return isCraftException(sourceValue)
+                ? enrichResourceException(sourceValue, { scope: 'params' })
+                : undefined;
+        }
+        if ('params' in queryConfig &&
+            queryConfig.params &&
+            !('fromResourceById' in queryConfig && queryConfig.fromResourceById)) {
+            const paramsValue = executeGeneratorCompatibleFactory({
+                factory: queryConfig.params,
+                thisArg: undefined,
+                getInjector,
+                args: [],
+                invalidYieldErrorMessage: QUERY_INVALID_YIELD_ERROR_MESSAGE,
+                multipleAppStartErrorMessage: QUERY_APP_START_ERROR_MESSAGE,
+                onAppStartNotSupportedErrorMessage: QUERY_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 queryConfig && queryConfig.params
+        ? ((...args) => {
+            const value = executeGeneratorCompatibleFactory({
+                factory: queryConfig.params,
+                thisArg: undefined,
+                getInjector,
+                args,
+                invalidYieldErrorMessage: QUERY_INVALID_YIELD_ERROR_MESSAGE,
+                multipleAppStartErrorMessage: QUERY_APP_START_ERROR_MESSAGE,
+                onAppStartNotSupportedErrorMessage: QUERY_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 && queryConfig.method
+        ? (() => (() => {
+            const value = sanitizeParamsResult(queryConfig.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 queryConfig && queryConfig.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: queryConfig.loader,
+                    thisArg: undefined,
+                    getInjector,
+                    args: [loaderParam],
+                    invalidYieldErrorMessage: QUERY_INVALID_YIELD_ERROR_MESSAGE,
+                    appStartNotSupportedErrorMessage: QUERY_APP_START_ERROR_MESSAGE,
+                    // Query reloads cancel temporal awaits from the superseded load.
+                    abortSignal: loaderParam.abortSignal,
+                });
+                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 (param.abortSignal.aborted) {
+                    return undefined;
+                }
+                if (!isCraftException(error)) {
+                    injector.get(TAKE_APP_SNAPSHOT, null)?.();
+                }
+                throw error;
+            }
+            finally {
+                if (operationId)
+                    correlationSvc?.endOperation(operationId);
+            }
+        })
+        : undefined;
+    const wrappedStream = 'stream' in queryConfig && queryConfig.stream
+        ? ((...args) => {
+            const result = executeGeneratorCompatibleFactory({
+                factory: queryConfig.stream,
+                thisArg: undefined,
+                getInjector,
+                args,
+                invalidYieldErrorMessage: QUERY_INVALID_YIELD_ERROR_MESSAGE,
+                multipleAppStartErrorMessage: QUERY_APP_START_ERROR_MESSAGE,
+                onAppStartNotSupportedErrorMessage: QUERY_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 ?? queryResourceParamsFnSignal);
+    // Method-based, non-grouped: feed the resource a nonce-tagged request so every
+    // explicit call() 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
+        // In method mode this is always the plain signal (no params fn), but its union
+        // type includes the fromResourceById params function — narrow with a cast.
+        return wrapMethodParams(queryResourceParamsFnSignal(), seq);
+    });
+    const nonGroupedParams = hasMethodFn
+        ? methodTaggedParams
+        : resourceParamsSrc;
+    const nonGroupedEqual = hasMethodFn
+        ? methodParamsWrapperEqual(queryConfig.equal)
+        : queryConfig.equal;
+    const resourceTarget = isUsingIdentifier
+        ? resourceById({
+            ...queryConfig,
+            ssrSourceName: name,
+            params: resourceParamsSrc,
+            loader: wrappedLoader,
+            stream: wrappedStream,
+            identifier: queryConfig.identifier,
+            equalParams: queryConfig.equalParams ?? 'useIdentifier',
+        })
+        : !queryConfig.preservePreviousValue || queryConfig.preservePreviousValue()
+            ? preservedResource({
+                ...queryConfig,
+                ssrSourceName: name,
+                params: nonGroupedParams,
+                equal: nonGroupedEqual,
+                loader: wrappedLoader,
+                stream: wrappedStream,
+            })
+            : craftResource({
+                ...queryConfig,
+                ssrSourceName: name,
+                params: nonGroupedParams,
+                equal: nonGroupedEqual,
+                loader: wrappedLoader,
+                stream: wrappedStream,
+            });
+    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('query', resourceTarget)
+        : ɵcreatePrimitiveResourceRuntimeContext('query', resourceTarget), name));
+    // Capture the raw resource status BEFORE `Object.assign` overrides
+    // `resourceTarget.status` with the craft computed below (otherwise the craft
+    // status computed would read itself and form a computation cycle).
+    const rawResourceStatus = resourceTarget.status;
+    const publicExceptions = hasConfiguredSchema
+        ? computed(() => ({ ...exceptions(), parse: schemaParse() }))
+        : exceptions;
+    const queryOutputWithoutInsertions = 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;
+            },
+        }
+        : {}, {
+        ...(isUsingIdentifier
+            ? {}
+            : {
+                status: computed(() => toCraftStatus(rawResourceStatus(), hasException())),
+                exception: computed(() => exceptions().list[0]),
+            }),
+        hasException,
+        hasSchema: signal(hasConfiguredSchema),
+        exceptions: publicExceptions,
+        resourceParamsSrc: resourceParamsSrc,
+        call: !hasMethodFn
+            ? 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 = executeGeneratorCompatibleFactory({
+                    factory: queryConfig.method,
+                    thisArg: undefined,
+                    getInjector,
+                    args: [methodArg],
+                    invalidYieldErrorMessage: QUERY_INVALID_YIELD_ERROR_MESSAGE,
+                    multipleAppStartErrorMessage: QUERY_APP_START_ERROR_MESSAGE,
+                    onAppStartNotSupportedErrorMessage: QUERY_APP_START_ERROR_MESSAGE,
+                });
+                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);
+                }
+                if (isUsingIdentifier) {
+                    const id = queryConfig.identifier?.(paramsResult);
+                    resourceTarget.addById(id);
+                }
+                //@ts-expect-error exposed method params cannot use the from-resource entity callback shape
+                queryResourceParamsFnSignal.set(paramsResult);
+                // Set the params while the trigger is still inactive. The trigger
+                // is intentionally bumped last: Craft watches run synchronously,
+                // so bumping it first would briefly expose the previous params
+                // (undefined on the first call) and start an extra request.
+                methodTriggerSeq.update((n) => n + 1);
+                return yieldableInvocation(paramsResult);
+            },
+    });
+    if (!isUsingIdentifier) {
+        attachCraftSettledValue(name, queryOutputWithoutInsertions);
+    }
+    const publicQueryContext = createYieldableReactiveFacade(queryOutputWithoutInsertions, { name, primitive: 'query', path: name });
+    const insertionSettledState = isUsingIdentifier
+        ? createYieldableSettledValue(computed(() => {
+            const params = craftUse(publicQueryContext.resourceParamsSrc());
+            if (params == null)
+                throw new CraftNotSettled(name);
+            const id = queryConfig.identifier?.(params);
+            if (id == null)
+                throw new CraftNotSettled(name);
+            const selected = publicQueryContext.select(id);
+            if (!selected)
+                throw new CraftNotSettled(name);
+            return craftUse(selected.settledValue());
+        }), {
+            primitive: 'query',
+            insertion: 'settledState',
+            path: `${name}.settledState`,
+        })
+        : createYieldableSettledValue(computed(() => craftUse(publicQueryContext.settledValue())), {
+            primitive: 'query',
+            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: 'query',
+                                path: `${name}.resourceById`,
+                            }),
+                            identifier: queryConfig.identifier,
+                        }
+                        : { resource: publicQueryContext }),
+                    resourceParamsSrc: publicQueryContext.resourceParamsSrc,
+                    hasException: publicQueryContext.hasException,
+                    exceptions: publicQueryContext.exceptions,
+                    insertions: acc,
+                    state: publicQueryContext.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: 'query',
+                },
+            ],
+            invalidYieldErrorMessage: QUERY_INVALID_YIELD_ERROR_MESSAGE,
+            multipleAppStartErrorMessage: QUERY_APP_START_ERROR_MESSAGE,
+            onAppStartNotSupportedErrorMessage: QUERY_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('query', {
+                        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: QUERY_INVALID_YIELD_ERROR_MESSAGE,
+                    multipleAppStartErrorMessage: QUERY_APP_START_ERROR_MESSAGE,
+                    onAppStartNotSupportedErrorMessage: QUERY_APP_START_ERROR_MESSAGE,
+                });
+            }
+            else {
+                const namedValue = nameInsertedReactiveValue(value, key, 'query', `${name}.${key}`);
+                wrappedAcc[key] = createYieldableReactiveFacade(namedValue, {
+                    name: key,
+                    primitive: 'query',
+                    insertion: key,
+                    path: `${name}.${key}`,
+                });
+            }
+            return wrappedAcc;
+        }, {});
+        return { ...acc, ...wrappedResult };
+    }, {});
+    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 destroyRefQuery = injector
+        ? injector.get(DestroyRef, null)
+        : (() => {
+            try {
+                return inject(DestroyRef, { optional: true });
+            }
+            catch {
+                return null;
+            }
+        })();
+    if (snapshotRegistry && destroyRefQuery) {
+        snapshotRegistry.triggerSnapshot$
+            .pipe(takeUntilDestroyed(destroyRefQuery))
+            .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: 'query',
+                from: hostTagList,
+                state: stateSnapshot,
+            });
+        });
+    }
+    const queryOutput = Object.assign(queryOutputWithoutInsertions, insertionsResult);
+    if (!('resource' in queryOutput)) {
+        Object.defineProperty(queryOutput, 'resource', {
+            value: queryOutput,
+            enumerable: false,
+            configurable: true,
+        });
+    }
+    const publicQuery = createYieldableReactiveFacade(queryOutput, {
+        name,
+        primitive: 'query',
+        path: name,
+    });
+    return (hasDeepYieldableInsertion(insertions)
+        ? deepYieldable(publicQuery)
+        : publicQuery);
+}
+//# sourceMappingURL=query.js.map