@gears-frontx/react 0.1.0 → 0.2.0-alpha.0

package/dist/testing-Dlmfu6tE.d.cts

@@ -0,0 +1,56 @@
+import { QueryClient } from '@tanstack/react-query';
+import { EndpointDescriptor, FrontXApp } from '@gears-frontx/framework';
+import '@gears-frontx/framework/testing';
+
+/**
+ * QueryCache — restricted interface for interacting with the shared QueryClient.
+ *
+ * MFEs and screen-set components access the cache only through this sanctioned
+ * public interface. It is injected as { queryCache } into useApiMutation
+ * callbacks and also returned by useQueryCache() for controlled imperative
+ * cache access.
+ */
+
+type QueryCacheKey = readonly unknown[];
+type QueryCacheRefetchMode = 'active' | 'inactive' | 'all' | 'none';
+type QueryCacheInvalidateTarget = EndpointDescriptor<unknown> | QueryCacheKey | null | undefined;
+interface QueryCacheState<TData = unknown, TError = Error> {
+    data: TData | undefined;
+    dataUpdatedAt: number;
+    error: TError | null;
+    errorUpdatedAt: number;
+    fetchFailureCount: number;
+    fetchFailureReason: TError | null;
+    fetchStatus: 'fetching' | 'paused' | 'idle';
+    isInvalidated: boolean;
+    status: 'pending' | 'error' | 'success';
+}
+type QueryCacheInvalidateFilters = {
+    queryKey?: QueryCacheInvalidateTarget;
+    exact?: boolean;
+    refetchType?: QueryCacheRefetchMode;
+};
+interface QueryCache {
+    get<T>(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): T | undefined;
+    getState<TData = unknown, TError = Error>(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): QueryCacheState<TData, TError> | undefined;
+    set<T>(queryKey: EndpointDescriptor<unknown> | QueryCacheKey, dataOrUpdater: T | ((old: T | undefined) => T | undefined)): void;
+    cancel(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): Promise<void>;
+    invalidate(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): Promise<void>;
+    invalidateMany(filters?: QueryCacheInvalidateFilters | null): Promise<void>;
+    remove(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): void;
+}
+interface MutationCallbackContext {
+    queryCache: QueryCache;
+}
+
+declare function resolveFrontXQueryClient(app: FrontXApp): QueryClient | undefined;
+/**
+ * Imperatively invalidates cache entries for `target` on the QueryClient bound to `app`.
+ * Use from non-React code (e.g. MFE actions); in components prefer `useQueryCache().invalidate`.
+ */
+declare function invalidateQueryCacheForApp(app: FrontXApp, target: EndpointDescriptor<unknown> | QueryCacheKey): Promise<void>;
+/** Resolves the app-bound QueryClient without triggering plugin activation during render. */
+declare function bootstrapFrontXQueryClient(app: FrontXApp): QueryClient | undefined;
+declare function useOptionalFrontXQueryClient(): QueryClient | undefined;
+
+export { type MutationCallbackContext as M, type QueryCache as Q, type QueryCacheInvalidateFilters as a, type QueryCacheState as b, bootstrapFrontXQueryClient as c, invalidateQueryCacheForApp as i, resolveFrontXQueryClient as r, useOptionalFrontXQueryClient as u };

package/dist/testing-Dlmfu6tE.d.ts

@@ -0,0 +1,56 @@
+import { QueryClient } from '@tanstack/react-query';
+import { EndpointDescriptor, FrontXApp } from '@gears-frontx/framework';
+import '@gears-frontx/framework/testing';
+
+/**
+ * QueryCache — restricted interface for interacting with the shared QueryClient.
+ *
+ * MFEs and screen-set components access the cache only through this sanctioned
+ * public interface. It is injected as { queryCache } into useApiMutation
+ * callbacks and also returned by useQueryCache() for controlled imperative
+ * cache access.
+ */
+
+type QueryCacheKey = readonly unknown[];
+type QueryCacheRefetchMode = 'active' | 'inactive' | 'all' | 'none';
+type QueryCacheInvalidateTarget = EndpointDescriptor<unknown> | QueryCacheKey | null | undefined;
+interface QueryCacheState<TData = unknown, TError = Error> {
+    data: TData | undefined;
+    dataUpdatedAt: number;
+    error: TError | null;
+    errorUpdatedAt: number;
+    fetchFailureCount: number;
+    fetchFailureReason: TError | null;
+    fetchStatus: 'fetching' | 'paused' | 'idle';
+    isInvalidated: boolean;
+    status: 'pending' | 'error' | 'success';
+}
+type QueryCacheInvalidateFilters = {
+    queryKey?: QueryCacheInvalidateTarget;
+    exact?: boolean;
+    refetchType?: QueryCacheRefetchMode;
+};
+interface QueryCache {
+    get<T>(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): T | undefined;
+    getState<TData = unknown, TError = Error>(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): QueryCacheState<TData, TError> | undefined;
+    set<T>(queryKey: EndpointDescriptor<unknown> | QueryCacheKey, dataOrUpdater: T | ((old: T | undefined) => T | undefined)): void;
+    cancel(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): Promise<void>;
+    invalidate(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): Promise<void>;
+    invalidateMany(filters?: QueryCacheInvalidateFilters | null): Promise<void>;
+    remove(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): void;
+}
+interface MutationCallbackContext {
+    queryCache: QueryCache;
+}
+
+declare function resolveFrontXQueryClient(app: FrontXApp): QueryClient | undefined;
+/**
+ * Imperatively invalidates cache entries for `target` on the QueryClient bound to `app`.
+ * Use from non-React code (e.g. MFE actions); in components prefer `useQueryCache().invalidate`.
+ */
+declare function invalidateQueryCacheForApp(app: FrontXApp, target: EndpointDescriptor<unknown> | QueryCacheKey): Promise<void>;
+/** Resolves the app-bound QueryClient without triggering plugin activation during render. */
+declare function bootstrapFrontXQueryClient(app: FrontXApp): QueryClient | undefined;
+declare function useOptionalFrontXQueryClient(): QueryClient | undefined;
+
+export { type MutationCallbackContext as M, type QueryCache as Q, type QueryCacheInvalidateFilters as a, type QueryCacheState as b, bootstrapFrontXQueryClient as c, invalidateQueryCacheForApp as i, resolveFrontXQueryClient as r, useOptionalFrontXQueryClient as u };

package/dist/testing.cjs

@@ -0,0 +1,74 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/testing.ts
+var testing_exports = {};
+__export(testing_exports, {
+  bootstrapFrontXQueryClient: () => bootstrapFrontXQueryClient,
+  describeBootstrapMfeContract: () => import_testing.describeBootstrapMfeContract,
+  resolveFrontXQueryClient: () => resolveFrontXQueryClient,
+  useOptionalFrontXQueryClient: () => useOptionalFrontXQueryClient
+});
+module.exports = __toCommonJS(testing_exports);
+
+// src/queryClient.tsx
+var import_react = __toESM(require("react"), 1);
+var import_react_query = require("@tanstack/react-query");
+var import_framework2 = require("@gears-frontx/framework");
+
+// src/hooks/QueryCache.ts
+var import_framework = require("@gears-frontx/framework");
+
+// src/queryClient.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var APP_QUERY_CLIENT_SYMBOL = /* @__PURE__ */ Symbol.for("frontx:query-cache:app-client");
+var APP_QUERY_CLIENT_RESOLVER_SYMBOL = /* @__PURE__ */ Symbol.for("frontx:query-cache:app-client-resolver");
+var FrontXQueryClientContext = (0, import_react.createContext)(void 0);
+var useCommitEffect = typeof globalThis.window === "undefined" ? import_react.useEffect : import_react.useLayoutEffect;
+function resolveFrontXQueryClient(app) {
+  const clientApp = app;
+  return clientApp[APP_QUERY_CLIENT_SYMBOL] ?? clientApp[APP_QUERY_CLIENT_RESOLVER_SYMBOL]?.();
+}
+function bootstrapFrontXQueryClient(app) {
+  return resolveFrontXQueryClient(app);
+}
+function useOptionalFrontXQueryClient() {
+  return (0, import_react.useContext)(FrontXQueryClientContext);
+}
+
+// src/testing.ts
+var import_testing = require("@gears-frontx/framework/testing");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  bootstrapFrontXQueryClient,
+  describeBootstrapMfeContract,
+  resolveFrontXQueryClient,
+  useOptionalFrontXQueryClient
+});
+//# sourceMappingURL=testing.cjs.map

package/dist/testing.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/testing.ts","../src/queryClient.tsx","../src/hooks/QueryCache.ts"],"sourcesContent":["/**\n * Test-only entry for @gears-frontx/react.\n *\n * Utilities here are intended for Vitest (or similar) suites that need access\n * to query-client wiring without importing package internals directly.\n */\n\n// @cpt-dod:cpt-frontx-dod-react-bindings-provider:p1\n\n// @cpt-begin:cpt-frontx-dod-react-bindings-provider:p1:inst-react-testing-reexports\nexport {\n  bootstrapFrontXQueryClient,\n  resolveFrontXQueryClient,\n  useOptionalFrontXQueryClient,\n} from './queryClient';\n\n/** App-layer tests must import this from `@gears-frontx/react/testing`, not `@gears-frontx/framework/testing`. */\nexport { describeBootstrapMfeContract } from '@gears-frontx/framework/testing';\nexport type {\n  BootstrapMfeResolveArgs,\n  BootstrapMfeTestSpecOptions,\n} from '@gears-frontx/framework/testing';\n// @cpt-end:cpt-frontx-dod-react-bindings-provider:p1:inst-react-testing-reexports\n","import React, {\n  createContext,\n  useContext,\n  useEffect,\n  useLayoutEffect,\n  useMemo,\n  useState,\n} from 'react';\nimport {\n  QueryClientContext,\n  QueryClientProvider,\n  type QueryClient,\n  useInfiniteQuery,\n  useMutation,\n  useQuery,\n  useSuspenseInfiniteQuery,\n  useSuspenseQuery,\n  type MutationFunctionContext,\n} from '@tanstack/react-query';\nimport {\n  subscribeQueryCacheRuntimeChanged,\n  type EndpointDescriptor,\n  type FrontXApp,\n} from '@gears-frontx/framework';\nimport type { ApiQueryOverrides } from './hooks/useApiQuery';\nimport type {\n  ApiInfiniteQueryOptions,\n  ApiInfiniteQueryPageContext,\n} from './hooks/useApiInfiniteQuery';\nimport type { UseApiMutationOptions } from './hooks/useApiMutation';\nimport { createQueryCache, type MutationCallbackContext, type QueryCacheKey } from './hooks/QueryCache';\n\n// @cpt-FEATURE:implement-endpoint-descriptors:p3\n// @cpt-dod:cpt-frontx-dod-request-lifecycle-query-provider:p2\n// @cpt-flow:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2\n// @cpt-flow:cpt-frontx-flow-request-lifecycle-use-api-query:p2\n// @cpt-flow:cpt-frontx-flow-request-lifecycle-use-api-mutation:p2\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2:inst-react-query-client-symbols\nconst APP_QUERY_CLIENT_SYMBOL = Symbol.for('frontx:query-cache:app-client');\nconst APP_QUERY_CLIENT_RESOLVER_SYMBOL = Symbol.for('frontx:query-cache:app-client-resolver');\nconst APP_QUERY_CLIENT_ACTIVATOR_SYMBOL = Symbol.for('frontx:query-cache:app-client-activator');\n\ntype QueryClientApp = FrontXApp & {\n  [APP_QUERY_CLIENT_SYMBOL]?: QueryClient;\n  [APP_QUERY_CLIENT_RESOLVER_SYMBOL]?: () => QueryClient | undefined;\n  [APP_QUERY_CLIENT_ACTIVATOR_SYMBOL]?: () => QueryClient | undefined;\n};\n\nconst FrontXQueryClientContext = createContext<QueryClient | undefined>(undefined);\n// @cpt-end:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2:inst-react-query-client-symbols\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2:inst-resolve-app-query-client\ntype RuntimeAwareEndpointDescriptor<TData> = EndpointDescriptor<TData> & {\n  fetch(options?: { signal?: AbortSignal; staleTime?: number }): Promise<TData>;\n};\n\ntype AppResolvedQueryClient = {\n  app: FrontXApp;\n  queryClient: QueryClient;\n};\n\nconst useCommitEffect = typeof globalThis.window === 'undefined' ? useEffect : useLayoutEffect;\n\nexport function resolveFrontXQueryClient(app: FrontXApp): QueryClient | undefined {\n  const clientApp = app as QueryClientApp;\n  return clientApp[APP_QUERY_CLIENT_SYMBOL] ?? clientApp[APP_QUERY_CLIENT_RESOLVER_SYMBOL]?.();\n}\n\nexport function hasFrontXQueryClientActivator(app: FrontXApp): boolean {\n  return typeof (app as QueryClientApp)[APP_QUERY_CLIENT_ACTIVATOR_SYMBOL] === 'function';\n}\n\nexport function activateFrontXQueryClient(app: FrontXApp): QueryClient | undefined {\n  const clientApp = app as QueryClientApp;\n  return clientApp[APP_QUERY_CLIENT_SYMBOL] ?? clientApp[APP_QUERY_CLIENT_ACTIVATOR_SYMBOL]?.();\n}\n// @cpt-end:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2:inst-resolve-app-query-client\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2:inst-imperative-cache-bootstrap\n/**\n * Imperatively invalidates cache entries for `target` on the QueryClient bound to `app`.\n * Use from non-React code (e.g. MFE actions); in components prefer `useQueryCache().invalidate`.\n */\nexport async function invalidateQueryCacheForApp(\n  app: FrontXApp,\n  target: EndpointDescriptor<unknown> | QueryCacheKey\n): Promise<void> {\n  const queryClient = resolveFrontXQueryClient(app) ?? activateFrontXQueryClient(app);\n  if (!queryClient) {\n    throw new Error(\n      '[invalidateQueryCacheForApp] No QueryClient on app. Ensure queryCache() or queryCacheShared() is in the plugin chain.'\n    );\n  }\n  await createQueryCache(queryClient).invalidate(target);\n}\n\n/** Resolves the app-bound QueryClient without triggering plugin activation during render. */\nexport function bootstrapFrontXQueryClient(app: FrontXApp): QueryClient | undefined {\n  return resolveFrontXQueryClient(app);\n}\n// @cpt-end:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2:inst-imperative-cache-bootstrap\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2:inst-use-bootstrapped-query-client\nexport function useBootstrappedFrontXQueryClient(app: FrontXApp): QueryClient | undefined {\n  const fromApp = useMemo(() => bootstrapFrontXQueryClient(app), [app]);\n  const [eventResolvedClient, setEventResolvedClient] = useState<AppResolvedQueryClient | undefined>(\n    undefined\n  );\n  const queryClient =\n    fromApp ?? (eventResolvedClient?.app === app ? eventResolvedClient.queryClient : undefined);\n\n  useCommitEffect(() => {\n    if (fromApp || !hasFrontXQueryClientActivator(app)) {\n      return;\n    }\n\n    const tryResolveQueryClient = () => {\n      const nextQueryClient = resolveFrontXQueryClient(app) ?? activateFrontXQueryClient(app);\n      if (nextQueryClient) {\n        setEventResolvedClient((current) => {\n          if (current?.app === app && current.queryClient === nextQueryClient) {\n            return current;\n          }\n\n          return {\n            app,\n            queryClient: nextQueryClient,\n          };\n        });\n      }\n    };\n\n    // Only activate after commit so abandoned renders cannot leak retainers/listeners.\n    tryResolveQueryClient();\n\n    const subscription = subscribeQueryCacheRuntimeChanged(() => {\n      tryResolveQueryClient();\n    });\n\n    return () => {\n      subscription.unsubscribe();\n    };\n  }, [app, fromApp]);\n\n  return queryClient;\n}\n// @cpt-end:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2:inst-use-bootstrapped-query-client\n\n// @cpt-begin:cpt-frontx-dod-request-lifecycle-query-provider:p2:inst-frontx-query-client-provider\nexport function FrontXQueryClientProvider({\n  queryClient,\n  children,\n}: Readonly<{\n  queryClient: QueryClient | undefined;\n  children: React.ReactNode;\n}>) {\n  if (!queryClient) {\n    return (\n      <FrontXQueryClientContext.Provider value={undefined}>\n        <QueryClientContext.Provider value={undefined}>{children}</QueryClientContext.Provider>\n      </FrontXQueryClientContext.Provider>\n    );\n  }\n\n  return (\n    <FrontXQueryClientContext.Provider value={queryClient}>\n      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>\n    </FrontXQueryClientContext.Provider>\n  );\n}\n// @cpt-end:cpt-frontx-dod-request-lifecycle-query-provider:p2:inst-frontx-query-client-provider\n\n// @cpt-begin:cpt-frontx-dod-request-lifecycle-query-provider:p2:inst-query-client-context-hooks\nexport function useOptionalFrontXQueryClient(): QueryClient | undefined {\n  return useContext(FrontXQueryClientContext);\n}\n\nexport function useRequiredFrontXQueryClient(): QueryClient {\n  const queryClient = useOptionalFrontXQueryClient();\n  if (!queryClient) {\n    throw new Error(\n      '[FrontXProvider] No query cache available. Add queryCache() or queryCacheShared() to your plugin composition.'\n    );\n  }\n\n  return queryClient;\n}\n// @cpt-end:cpt-frontx-dod-request-lifecycle-query-provider:p2:inst-query-client-context-hooks\n\n// @cpt-begin:implement-endpoint-descriptors:p3:inst-descriptor-fetch-stale-helpers\nfunction buildPageContext<TPage>(\n  page: TPage,\n  pages: readonly TPage[],\n  descriptor: EndpointDescriptor<TPage>,\n  descriptors: readonly EndpointDescriptor<TPage>[]\n): ApiInfiniteQueryPageContext<TPage> {\n  return {\n    page,\n    pages,\n    descriptor,\n    descriptors,\n  };\n}\n\nfunction normalizeFetchStaleTime(staleTime: unknown): number | undefined {\n  if (staleTime === 'static') {\n    return Number.POSITIVE_INFINITY;\n  }\n\n  return typeof staleTime === 'number' ? staleTime : undefined;\n}\n\nfunction resolveFetchStaleTime<TData>(\n  queryClient: QueryClient,\n  descriptor: EndpointDescriptor<TData>,\n  overrideStaleTime?: number\n): number | undefined {\n  return normalizeFetchStaleTime(\n    overrideStaleTime ??\n      descriptor.staleTime ??\n      queryClient.getDefaultOptions().queries?.staleTime\n  );\n}\n\nfunction fetchDescriptor<TData>(\n  descriptor: EndpointDescriptor<TData>,\n  options?: { signal?: AbortSignal; staleTime?: number }\n): Promise<TData> {\n  return (descriptor as RuntimeAwareEndpointDescriptor<TData>).fetch(options);\n}\n// @cpt-end:implement-endpoint-descriptors:p3:inst-descriptor-fetch-stale-helpers\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-use-api-query:p2:inst-delegate-frontx-use-query\nexport function useFrontXQuery<TData = unknown, TError = Error>(\n  descriptor: EndpointDescriptor<TData>,\n  overrides?: ApiQueryOverrides\n) {\n  const queryClient = useRequiredFrontXQueryClient();\n  const staleTime = resolveFetchStaleTime(queryClient, descriptor, overrides?.staleTime);\n  const result = useQuery<TData, TError>({\n    queryKey: descriptor.key as unknown[],\n    queryFn: ({ signal }) => fetchDescriptor(descriptor, { signal, staleTime }),\n    staleTime: overrides?.staleTime ?? descriptor.staleTime,\n    gcTime: overrides?.gcTime ?? descriptor.gcTime,\n  });\n\n  return {\n    data: result.data,\n    error: result.error,\n    isLoading: result.isLoading,\n    isFetching: result.isFetching,\n    isError: result.isError,\n    refetch: result.refetch,\n  };\n}\n// @cpt-end:cpt-frontx-flow-request-lifecycle-use-api-query:p2:inst-delegate-frontx-use-query\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-use-api-query:p2:inst-delegate-frontx-use-suspense-query\nexport function useFrontXSuspenseQuery<TData = unknown, TError = Error>(\n  descriptor: EndpointDescriptor<TData>,\n  overrides?: ApiQueryOverrides\n) {\n  const queryClient = useRequiredFrontXQueryClient();\n  const staleTime = resolveFetchStaleTime(queryClient, descriptor, overrides?.staleTime);\n  const result = useSuspenseQuery<TData, TError>({\n    queryKey: descriptor.key as unknown[],\n    queryFn: ({ signal }) => fetchDescriptor(descriptor, { signal, staleTime }),\n    staleTime: overrides?.staleTime ?? descriptor.staleTime,\n    gcTime: overrides?.gcTime ?? descriptor.gcTime,\n  });\n\n  return {\n    data: result.data,\n    error: result.error,\n    isFetching: result.isFetching,\n    refetch: async () => {\n      await result.refetch();\n    },\n  };\n}\n// @cpt-end:cpt-frontx-flow-request-lifecycle-use-api-query:p2:inst-delegate-frontx-use-suspense-query\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-use-api-query:p2:inst-delegate-frontx-use-infinite-query\nexport function useFrontXInfiniteQuery<TPage = unknown, TError = Error>(\n  options: ApiInfiniteQueryOptions<TPage>\n) {\n  const queryClient = useRequiredFrontXQueryClient();\n  const result = useInfiniteQuery<\n    TPage,\n    TError,\n    readonly TPage[],\n    readonly unknown[],\n    EndpointDescriptor<TPage>\n  >({\n    queryKey: options.initialPage.key,\n    initialPageParam: options.initialPage,\n    queryFn: ({ pageParam, signal }) =>\n      fetchDescriptor(pageParam, {\n        signal,\n        staleTime: resolveFetchStaleTime(queryClient, pageParam, options.staleTime),\n      }),\n    getNextPageParam: (\n      lastPage,\n      allPages,\n      lastPageDescriptor,\n      allPageDescriptors\n    ) =>\n      options.getNextPage(\n        buildPageContext(\n          lastPage,\n          allPages,\n          lastPageDescriptor,\n          allPageDescriptors\n        )\n      ),\n    getPreviousPageParam: options.getPreviousPage\n      ? (firstPage, allPages, firstPageDescriptor, allPageDescriptors) =>\n          options.getPreviousPage?.(\n            buildPageContext(\n              firstPage,\n              allPages,\n              firstPageDescriptor,\n              allPageDescriptors\n            )\n          )\n      : undefined,\n    select: (data) => data.pages,\n    staleTime: options.staleTime ?? options.initialPage.staleTime,\n    gcTime: options.gcTime ?? options.initialPage.gcTime,\n    maxPages: options.maxPages,\n  });\n\n  return {\n    data: result.data,\n    error: result.error,\n    isLoading: result.isLoading,\n    isFetching: result.isFetching,\n    isError: result.isError,\n    hasNextPage: result.hasNextPage ?? false,\n    hasPreviousPage: result.hasPreviousPage ?? false,\n    isFetchingNextPage: result.isFetchingNextPage,\n    isFetchingPreviousPage: result.isFetchingPreviousPage,\n    fetchNextPage: async () => {\n      await result.fetchNextPage();\n    },\n    fetchPreviousPage: async () => {\n      await result.fetchPreviousPage();\n    },\n    refetch: async () => {\n      await result.refetch();\n    },\n  };\n}\n// @cpt-end:cpt-frontx-flow-request-lifecycle-use-api-query:p2:inst-delegate-frontx-use-infinite-query\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-use-api-query:p2:inst-delegate-frontx-use-suspense-infinite-query\nexport function useFrontXSuspenseInfiniteQuery<TPage = unknown, TError = Error>(\n  options: ApiInfiniteQueryOptions<TPage>\n) {\n  const queryClient = useRequiredFrontXQueryClient();\n  const result = useSuspenseInfiniteQuery<\n    TPage,\n    TError,\n    readonly TPage[],\n    readonly unknown[],\n    EndpointDescriptor<TPage>\n  >({\n    queryKey: options.initialPage.key,\n    initialPageParam: options.initialPage,\n    queryFn: ({ pageParam, signal }) =>\n      fetchDescriptor(pageParam, {\n        signal,\n        staleTime: resolveFetchStaleTime(queryClient, pageParam, options.staleTime),\n      }),\n    getNextPageParam: (\n      lastPage,\n      allPages,\n      lastPageDescriptor,\n      allPageDescriptors\n    ) =>\n      options.getNextPage(\n        buildPageContext(\n          lastPage,\n          allPages,\n          lastPageDescriptor,\n          allPageDescriptors\n        )\n      ),\n    getPreviousPageParam: options.getPreviousPage\n      ? (firstPage, allPages, firstPageDescriptor, allPageDescriptors) =>\n          options.getPreviousPage?.(\n            buildPageContext(\n              firstPage,\n              allPages,\n              firstPageDescriptor,\n              allPageDescriptors\n            )\n          )\n      : undefined,\n    select: (data) => data.pages,\n    staleTime: options.staleTime ?? options.initialPage.staleTime,\n    gcTime: options.gcTime ?? options.initialPage.gcTime,\n    maxPages: options.maxPages,\n  });\n\n  return {\n    data: result.data,\n    error: result.error,\n    isFetching: result.isFetching,\n    hasNextPage: result.hasNextPage ?? false,\n    hasPreviousPage: result.hasPreviousPage ?? false,\n    isFetchingNextPage: result.isFetchingNextPage,\n    isFetchingPreviousPage: result.isFetchingPreviousPage,\n    fetchNextPage: async () => {\n      await result.fetchNextPage();\n    },\n    fetchPreviousPage: async () => {\n      await result.fetchPreviousPage();\n    },\n    refetch: async () => {\n      await result.refetch();\n    },\n  };\n}\n// @cpt-end:cpt-frontx-flow-request-lifecycle-use-api-query:p2:inst-delegate-frontx-use-suspense-infinite-query\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-use-api-mutation:p2:inst-delegate-frontx-use-mutation\nexport function useFrontXMutation<\n  TData = unknown,\n  TError = Error,\n  TVariables = void,\n  TContext = unknown,\n>(\n  options: UseApiMutationOptions<TData, TError, TVariables, TContext>,\n  callbackCtx: MutationCallbackContext\n) {\n  useRequiredFrontXQueryClient();\n\n  const latestRef = React.useRef({ options, callbackCtx });\n  latestRef.current = { options, callbackCtx };\n  const fetchAbortControllersRef = React.useRef<Set<AbortController>>(new Set());\n\n  React.useEffect(() => {\n    const fetchAbortControllers = fetchAbortControllersRef.current;\n    return () => {\n      if (latestRef.current.options.abortOnUnmount) {\n        for (const controller of fetchAbortControllers) {\n          controller.abort();\n        }\n        fetchAbortControllers.clear();\n      }\n    };\n  }, []);\n\n  const mutationFn = React.useCallback((variables: TVariables, context: MutationFunctionContext) => {\n    const cancelOnSupersede = latestRef.current.options.cancelOnSupersede;\n    if (cancelOnSupersede) {\n      for (const controller of fetchAbortControllersRef.current) {\n        controller.abort();\n      }\n      fetchAbortControllersRef.current.clear();\n    }\n\n    const controller = new AbortController();\n    fetchAbortControllersRef.current.add(controller);\n\n    const librarySignal = (context as MutationFunctionContext & { signal?: AbortSignal }).signal;\n    if (cancelOnSupersede && librarySignal) {\n      if (librarySignal.aborted) {\n        controller.abort();\n      } else {\n        librarySignal.addEventListener('abort', () => controller.abort(), { once: true });\n      }\n    }\n\n    return latestRef.current.options.endpoint\n      .fetch(variables, { signal: controller.signal })\n      .finally(() => {\n        fetchAbortControllersRef.current.delete(controller);\n      });\n  }, []);\n\n  const onMutate = React.useCallback((variables: TVariables, _context: MutationFunctionContext) => {\n    const current = latestRef.current;\n    if (!current.options.onMutate) {\n      return undefined as TContext;\n    }\n\n    return current.options.onMutate(variables, current.callbackCtx);\n  }, []);\n\n  const onSuccess = React.useCallback((data: TData, variables: TVariables, context: TContext | undefined) => {\n    const current = latestRef.current;\n    return current.options.onSuccess?.(data, variables, context, current.callbackCtx);\n  }, []);\n\n  const onError = React.useCallback((error: TError, variables: TVariables, context: TContext | undefined) => {\n    const current = latestRef.current;\n    return current.options.onError?.(error, variables, context, current.callbackCtx);\n  }, []);\n\n  const onSettled = React.useCallback((\n    data: TData | undefined,\n    error: TError | null,\n    variables: TVariables,\n    context: TContext | undefined\n  ) => {\n    const current = latestRef.current;\n    return current.options.onSettled?.(\n      data,\n      error,\n      variables,\n      context,\n      current.callbackCtx\n    );\n  }, []);\n\n  const mutation = useMutation<TData, TError, TVariables, TContext>({\n    mutationFn,\n    onMutate: options.onMutate ? onMutate : undefined,\n    onSuccess: options.onSuccess ? onSuccess : undefined,\n    onError: options.onError ? onError : undefined,\n    onSettled: options.onSettled ? onSettled : undefined,\n  });\n\n  return {\n    mutate: mutation.mutate as (variables: TVariables) => void,\n    mutateAsync: mutation.mutateAsync as (variables: TVariables) => Promise<TData>,\n    isPending: mutation.isPending,\n    error: mutation.error,\n    data: mutation.data,\n    reset: mutation.reset,\n  };\n}\n// @cpt-end:cpt-frontx-flow-request-lifecycle-use-api-mutation:p2:inst-delegate-frontx-use-mutation\n","/**\n * QueryCache — restricted interface for interacting with the shared QueryClient.\n *\n * MFEs and screen-set components access the cache only through this sanctioned\n * public interface. It is injected as { queryCache } into useApiMutation\n * callbacks and also returned by useQueryCache() for controlled imperative\n * cache access.\n */\n// @cpt-dod:cpt-frontx-dod-request-lifecycle-use-api-mutation:p2\n// @cpt-flow:cpt-frontx-flow-request-lifecycle-use-api-mutation:p2:inst-create-query-cache\n// @cpt-FEATURE:implement-endpoint-descriptors:p3\n\nimport type { EndpointDescriptor } from '@gears-frontx/framework';\nimport { eventBus } from '@gears-frontx/framework';\nimport { type QueryClient, type QueryState } from '@tanstack/react-query';\n\nexport type QueryCacheKey = readonly unknown[];\nexport type QueryCacheRefetchMode = 'active' | 'inactive' | 'all' | 'none';\nexport type QueryCacheInvalidateTarget =\n  | EndpointDescriptor<unknown>\n  | QueryCacheKey\n  | null\n  | undefined;\n\nexport interface QueryCacheState<TData = unknown, TError = Error> {\n  data: TData | undefined;\n  dataUpdatedAt: number;\n  error: TError | null;\n  errorUpdatedAt: number;\n  fetchFailureCount: number;\n  fetchFailureReason: TError | null;\n  fetchStatus: 'fetching' | 'paused' | 'idle';\n  isInvalidated: boolean;\n  status: 'pending' | 'error' | 'success';\n}\n\nexport type QueryCacheInvalidateFilters = {\n  queryKey?: QueryCacheInvalidateTarget;\n  exact?: boolean;\n  refetchType?: QueryCacheRefetchMode;\n};\n\ntype QueryCacheUpdater<T> = T | ((old: T | undefined) => T | undefined);\n\ntype CacheInvalidateEvent = {\n  queryKey: QueryCacheKey;\n  exact?: boolean;\n  refetchType?: QueryCacheRefetchMode;\n  source?: string;\n};\n\ntype CacheSetEvent = {\n  queryKey: QueryCacheKey;\n  dataOrUpdater: QueryCacheUpdater<unknown>;\n  source?: string;\n};\n\ntype CacheRemoveEvent = {\n  queryKey: QueryCacheKey;\n  source?: string;\n};\n\nconst QUERY_CLIENT_BROADCAST_TARGET = Symbol.for('frontx:query-cache:broadcast-target');\nconst QUERY_CLIENT_BROADCAST_COUNTER = Symbol.for('frontx:query-cache:broadcast-counter');\n\ntype QueryClientWithMetadata = QueryClient & {\n  [QUERY_CLIENT_BROADCAST_TARGET]?: string;\n};\n\ntype QueryClientCounterHost = typeof globalThis & {\n  [QUERY_CLIENT_BROADCAST_COUNTER]?: number;\n};\n\nfunction emitCacheEvent(event: string, payload: unknown): void {\n  (eventBus.emit as (eventType: string, payload: unknown) => void)(event, payload);\n}\n\nfunction ensureBroadcastSource(queryClient: QueryClient): string {\n  const clientWithMetadata = queryClient as QueryClientWithMetadata;\n  const existingSource = clientWithMetadata[QUERY_CLIENT_BROADCAST_TARGET];\n  if (typeof existingSource === 'string' && existingSource.length > 0) {\n    return existingSource;\n  }\n\n  const host = globalThis as QueryClientCounterHost;\n  const nextCounter = (host[QUERY_CLIENT_BROADCAST_COUNTER] ?? 0) + 1;\n  host[QUERY_CLIENT_BROADCAST_COUNTER] = nextCounter;\n\n  const source = `query-cache-${nextCounter}`;\n  clientWithMetadata[QUERY_CLIENT_BROADCAST_TARGET] = source;\n  return source;\n}\n\n// @cpt-begin:implement-endpoint-descriptors:p3:inst-resolve-key\nexport function resolveKey(target: EndpointDescriptor<unknown> | QueryCacheKey): readonly unknown[] {\n  if (\n    target !== null &&\n    typeof target === 'object' &&\n    !Array.isArray(target) &&\n    'key' in target &&\n    'fetch' in target &&\n    Array.isArray(target.key) &&\n    typeof target.fetch === 'function'\n  ) {\n    return target.key;\n  }\n\n  return target as readonly unknown[];\n}\n// @cpt-end:implement-endpoint-descriptors:p3:inst-resolve-key\n\n// @cpt-begin:cpt-frontx-dod-request-lifecycle-use-api-mutation:p2:inst-query-cache-interface\nexport interface QueryCache {\n  get<T>(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): T | undefined;\n  getState<TData = unknown, TError = Error>(\n    queryKey: EndpointDescriptor<unknown> | QueryCacheKey\n  ): QueryCacheState<TData, TError> | undefined;\n  set<T>(\n    queryKey: EndpointDescriptor<unknown> | QueryCacheKey,\n    dataOrUpdater: T | ((old: T | undefined) => T | undefined)\n  ): void;\n  cancel(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): Promise<void>;\n  invalidate(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): Promise<void>;\n  invalidateMany(filters?: QueryCacheInvalidateFilters | null): Promise<void>;\n  remove(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): void;\n}\n// @cpt-end:cpt-frontx-dod-request-lifecycle-use-api-mutation:p2:inst-query-cache-interface\n\n// @cpt-begin:cpt-frontx-dod-request-lifecycle-use-api-mutation:p2:inst-mutation-callback-context\nexport interface MutationCallbackContext {\n  queryCache: QueryCache;\n}\n// @cpt-end:cpt-frontx-dod-request-lifecycle-use-api-mutation:p2:inst-mutation-callback-context\n\nfunction toQueryUpdater<T>(\n  dataOrUpdater: QueryCacheUpdater<T>\n): (old: T | undefined) => T | undefined {\n  if (typeof dataOrUpdater === 'function') {\n    return dataOrUpdater as (old: T | undefined) => T | undefined;\n  }\n\n  return () => dataOrUpdater;\n}\n\nfunction mapQueryState<TData, TError = Error>(\n  state: QueryState<TData, TError>\n): QueryCacheState<TData, TError> {\n  return {\n    data: state.data,\n    dataUpdatedAt: state.dataUpdatedAt,\n    error: state.error,\n    errorUpdatedAt: state.errorUpdatedAt,\n    fetchFailureCount: state.fetchFailureCount,\n    fetchFailureReason: state.fetchFailureReason,\n    fetchStatus: state.fetchStatus,\n    isInvalidated: state.isInvalidated,\n    status: state.status,\n  };\n}\n\n// @cpt-begin:implement-endpoint-descriptors:p3:inst-create-query-cache\nexport function createQueryCache(queryClient: QueryClient): QueryCache {\n  return {\n    get: <T,>(key: EndpointDescriptor<unknown> | QueryCacheKey): T | undefined => {\n      return queryClient.getQueryData<T>(resolveKey(key));\n    },\n    getState: <TData = unknown, TError = Error>(key: EndpointDescriptor<unknown> | QueryCacheKey) => {\n      const state = queryClient.getQueryState<TData, TError>(resolveKey(key));\n      return state ? mapQueryState(state) : undefined;\n    },\n    set: <T,>(key: EndpointDescriptor<unknown> | QueryCacheKey, dataOrUpdater: QueryCacheUpdater<T>): void => {\n      const resolvedKey = resolveKey(key);\n      queryClient.setQueryData<T>(resolvedKey, toQueryUpdater(dataOrUpdater));\n      emitCacheEvent('cache/set', {\n        queryKey: resolvedKey,\n        dataOrUpdater: dataOrUpdater as QueryCacheUpdater<unknown>,\n        source: ensureBroadcastSource(queryClient),\n      } satisfies CacheSetEvent);\n    },\n    cancel: (key: EndpointDescriptor<unknown> | QueryCacheKey): Promise<void> => {\n      return queryClient.cancelQueries({ queryKey: resolveKey(key) });\n    },\n    invalidate: (key: EndpointDescriptor<unknown> | QueryCacheKey): Promise<void> => {\n      const resolvedKey = resolveKey(key);\n      const result = queryClient.invalidateQueries({ queryKey: resolvedKey });\n      emitCacheEvent('cache/invalidate', {\n        queryKey: resolvedKey,\n        source: ensureBroadcastSource(queryClient),\n      } satisfies CacheInvalidateEvent);\n      return result;\n    },\n    invalidateMany: (filters): Promise<void> => {\n      if (filters?.queryKey == null) {\n        return Promise.resolve();\n      }\n\n      const resolvedKey = resolveKey(filters.queryKey);\n      if (!Array.isArray(resolvedKey) || resolvedKey.length === 0) {\n        return Promise.resolve();\n      }\n\n      const payload = {\n        ...filters,\n        queryKey: resolvedKey,\n      };\n      const result = queryClient.invalidateQueries(payload);\n      emitCacheEvent('cache/invalidate', {\n        ...payload,\n        source: ensureBroadcastSource(queryClient),\n      } satisfies CacheInvalidateEvent);\n      return result;\n    },\n    remove: (key: EndpointDescriptor<unknown> | QueryCacheKey): void => {\n      const resolvedKey = resolveKey(key);\n      queryClient.removeQueries({ queryKey: resolvedKey });\n      emitCacheEvent('cache/remove', {\n        queryKey: resolvedKey,\n        source: ensureBroadcastSource(queryClient),\n      } satisfies CacheRemoveEvent);\n    },\n  };\n}\n// @cpt-end:implement-endpoint-descriptors:p3:inst-create-query-cache\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAOO;AACP,yBAUO;AACP,IAAAA,oBAIO;;;ACVP,uBAAyB;;;ADmJjB;AAzHR,IAAM,0BAA0B,uBAAO,IAAI,+BAA+B;AAC1E,IAAM,mCAAmC,uBAAO,IAAI,wCAAwC;AAS5F,IAAM,+BAA2B,4BAAuC,MAAS;AAajF,IAAM,kBAAkB,OAAO,WAAW,WAAW,cAAc,yBAAY;AAExE,SAAS,yBAAyB,KAAyC;AAChF,QAAM,YAAY;AAClB,SAAO,UAAU,uBAAuB,KAAK,UAAU,gCAAgC,IAAI;AAC7F;AA+BO,SAAS,2BAA2B,KAAyC;AAClF,SAAO,yBAAyB,GAAG;AACrC;AA0EO,SAAS,+BAAwD;AACtE,aAAO,yBAAW,wBAAwB;AAC5C;;;AD/JA,qBAA6C;","names":["import_framework"]}

package/dist/testing.d.cts

@@ -0,0 +1,4 @@
+export { c as bootstrapFrontXQueryClient, r as resolveFrontXQueryClient, u as useOptionalFrontXQueryClient } from './testing-Dlmfu6tE.cjs';
+export { BootstrapMfeResolveArgs, BootstrapMfeTestSpecOptions, describeBootstrapMfeContract } from '@gears-frontx/framework/testing';
+import '@tanstack/react-query';
+import '@gears-frontx/framework';

package/dist/testing.d.ts

@@ -0,0 +1,4 @@
+export { c as bootstrapFrontXQueryClient, r as resolveFrontXQueryClient, u as useOptionalFrontXQueryClient } from './testing-Dlmfu6tE.js';
+export { BootstrapMfeResolveArgs, BootstrapMfeTestSpecOptions, describeBootstrapMfeContract } from '@gears-frontx/framework/testing';
+import '@tanstack/react-query';
+import '@gears-frontx/framework';

package/dist/testing.js

@@ -0,0 +1,51 @@
+// src/queryClient.tsx
+import React, {
+  createContext,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useState
+} from "react";
+import {
+  QueryClientContext,
+  QueryClientProvider,
+  useInfiniteQuery,
+  useMutation,
+  useQuery,
+  useSuspenseInfiniteQuery,
+  useSuspenseQuery
+} from "@tanstack/react-query";
+import {
+  subscribeQueryCacheRuntimeChanged
+} from "@gears-frontx/framework";
+
+// src/hooks/QueryCache.ts
+import { eventBus } from "@gears-frontx/framework";
+
+// src/queryClient.tsx
+import { jsx } from "react/jsx-runtime";
+var APP_QUERY_CLIENT_SYMBOL = /* @__PURE__ */ Symbol.for("frontx:query-cache:app-client");
+var APP_QUERY_CLIENT_RESOLVER_SYMBOL = /* @__PURE__ */ Symbol.for("frontx:query-cache:app-client-resolver");
+var FrontXQueryClientContext = createContext(void 0);
+var useCommitEffect = typeof globalThis.window === "undefined" ? useEffect : useLayoutEffect;
+function resolveFrontXQueryClient(app) {
+  const clientApp = app;
+  return clientApp[APP_QUERY_CLIENT_SYMBOL] ?? clientApp[APP_QUERY_CLIENT_RESOLVER_SYMBOL]?.();
+}
+function bootstrapFrontXQueryClient(app) {
+  return resolveFrontXQueryClient(app);
+}
+function useOptionalFrontXQueryClient() {
+  return useContext(FrontXQueryClientContext);
+}
+
+// src/testing.ts
+import { describeBootstrapMfeContract } from "@gears-frontx/framework/testing";
+export {
+  bootstrapFrontXQueryClient,
+  describeBootstrapMfeContract,
+  resolveFrontXQueryClient,
+  useOptionalFrontXQueryClient
+};
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/queryClient.tsx","../src/hooks/QueryCache.ts","../src/testing.ts"],"sourcesContent":["import React, {\n  createContext,\n  useContext,\n  useEffect,\n  useLayoutEffect,\n  useMemo,\n  useState,\n} from 'react';\nimport {\n  QueryClientContext,\n  QueryClientProvider,\n  type QueryClient,\n  useInfiniteQuery,\n  useMutation,\n  useQuery,\n  useSuspenseInfiniteQuery,\n  useSuspenseQuery,\n  type MutationFunctionContext,\n} from '@tanstack/react-query';\nimport {\n  subscribeQueryCacheRuntimeChanged,\n  type EndpointDescriptor,\n  type FrontXApp,\n} from '@gears-frontx/framework';\nimport type { ApiQueryOverrides } from './hooks/useApiQuery';\nimport type {\n  ApiInfiniteQueryOptions,\n  ApiInfiniteQueryPageContext,\n} from './hooks/useApiInfiniteQuery';\nimport type { UseApiMutationOptions } from './hooks/useApiMutation';\nimport { createQueryCache, type MutationCallbackContext, type QueryCacheKey } from './hooks/QueryCache';\n\n// @cpt-FEATURE:implement-endpoint-descriptors:p3\n// @cpt-dod:cpt-frontx-dod-request-lifecycle-query-provider:p2\n// @cpt-flow:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2\n// @cpt-flow:cpt-frontx-flow-request-lifecycle-use-api-query:p2\n// @cpt-flow:cpt-frontx-flow-request-lifecycle-use-api-mutation:p2\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2:inst-react-query-client-symbols\nconst APP_QUERY_CLIENT_SYMBOL = Symbol.for('frontx:query-cache:app-client');\nconst APP_QUERY_CLIENT_RESOLVER_SYMBOL = Symbol.for('frontx:query-cache:app-client-resolver');\nconst APP_QUERY_CLIENT_ACTIVATOR_SYMBOL = Symbol.for('frontx:query-cache:app-client-activator');\n\ntype QueryClientApp = FrontXApp & {\n  [APP_QUERY_CLIENT_SYMBOL]?: QueryClient;\n  [APP_QUERY_CLIENT_RESOLVER_SYMBOL]?: () => QueryClient | undefined;\n  [APP_QUERY_CLIENT_ACTIVATOR_SYMBOL]?: () => QueryClient | undefined;\n};\n\nconst FrontXQueryClientContext = createContext<QueryClient | undefined>(undefined);\n// @cpt-end:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2:inst-react-query-client-symbols\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2:inst-resolve-app-query-client\ntype RuntimeAwareEndpointDescriptor<TData> = EndpointDescriptor<TData> & {\n  fetch(options?: { signal?: AbortSignal; staleTime?: number }): Promise<TData>;\n};\n\ntype AppResolvedQueryClient = {\n  app: FrontXApp;\n  queryClient: QueryClient;\n};\n\nconst useCommitEffect = typeof globalThis.window === 'undefined' ? useEffect : useLayoutEffect;\n\nexport function resolveFrontXQueryClient(app: FrontXApp): QueryClient | undefined {\n  const clientApp = app as QueryClientApp;\n  return clientApp[APP_QUERY_CLIENT_SYMBOL] ?? clientApp[APP_QUERY_CLIENT_RESOLVER_SYMBOL]?.();\n}\n\nexport function hasFrontXQueryClientActivator(app: FrontXApp): boolean {\n  return typeof (app as QueryClientApp)[APP_QUERY_CLIENT_ACTIVATOR_SYMBOL] === 'function';\n}\n\nexport function activateFrontXQueryClient(app: FrontXApp): QueryClient | undefined {\n  const clientApp = app as QueryClientApp;\n  return clientApp[APP_QUERY_CLIENT_SYMBOL] ?? clientApp[APP_QUERY_CLIENT_ACTIVATOR_SYMBOL]?.();\n}\n// @cpt-end:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2:inst-resolve-app-query-client\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2:inst-imperative-cache-bootstrap\n/**\n * Imperatively invalidates cache entries for `target` on the QueryClient bound to `app`.\n * Use from non-React code (e.g. MFE actions); in components prefer `useQueryCache().invalidate`.\n */\nexport async function invalidateQueryCacheForApp(\n  app: FrontXApp,\n  target: EndpointDescriptor<unknown> | QueryCacheKey\n): Promise<void> {\n  const queryClient = resolveFrontXQueryClient(app) ?? activateFrontXQueryClient(app);\n  if (!queryClient) {\n    throw new Error(\n      '[invalidateQueryCacheForApp] No QueryClient on app. Ensure queryCache() or queryCacheShared() is in the plugin chain.'\n    );\n  }\n  await createQueryCache(queryClient).invalidate(target);\n}\n\n/** Resolves the app-bound QueryClient without triggering plugin activation during render. */\nexport function bootstrapFrontXQueryClient(app: FrontXApp): QueryClient | undefined {\n  return resolveFrontXQueryClient(app);\n}\n// @cpt-end:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2:inst-imperative-cache-bootstrap\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2:inst-use-bootstrapped-query-client\nexport function useBootstrappedFrontXQueryClient(app: FrontXApp): QueryClient | undefined {\n  const fromApp = useMemo(() => bootstrapFrontXQueryClient(app), [app]);\n  const [eventResolvedClient, setEventResolvedClient] = useState<AppResolvedQueryClient | undefined>(\n    undefined\n  );\n  const queryClient =\n    fromApp ?? (eventResolvedClient?.app === app ? eventResolvedClient.queryClient : undefined);\n\n  useCommitEffect(() => {\n    if (fromApp || !hasFrontXQueryClientActivator(app)) {\n      return;\n    }\n\n    const tryResolveQueryClient = () => {\n      const nextQueryClient = resolveFrontXQueryClient(app) ?? activateFrontXQueryClient(app);\n      if (nextQueryClient) {\n        setEventResolvedClient((current) => {\n          if (current?.app === app && current.queryClient === nextQueryClient) {\n            return current;\n          }\n\n          return {\n            app,\n            queryClient: nextQueryClient,\n          };\n        });\n      }\n    };\n\n    // Only activate after commit so abandoned renders cannot leak retainers/listeners.\n    tryResolveQueryClient();\n\n    const subscription = subscribeQueryCacheRuntimeChanged(() => {\n      tryResolveQueryClient();\n    });\n\n    return () => {\n      subscription.unsubscribe();\n    };\n  }, [app, fromApp]);\n\n  return queryClient;\n}\n// @cpt-end:cpt-frontx-flow-request-lifecycle-query-client-lifecycle:p2:inst-use-bootstrapped-query-client\n\n// @cpt-begin:cpt-frontx-dod-request-lifecycle-query-provider:p2:inst-frontx-query-client-provider\nexport function FrontXQueryClientProvider({\n  queryClient,\n  children,\n}: Readonly<{\n  queryClient: QueryClient | undefined;\n  children: React.ReactNode;\n}>) {\n  if (!queryClient) {\n    return (\n      <FrontXQueryClientContext.Provider value={undefined}>\n        <QueryClientContext.Provider value={undefined}>{children}</QueryClientContext.Provider>\n      </FrontXQueryClientContext.Provider>\n    );\n  }\n\n  return (\n    <FrontXQueryClientContext.Provider value={queryClient}>\n      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>\n    </FrontXQueryClientContext.Provider>\n  );\n}\n// @cpt-end:cpt-frontx-dod-request-lifecycle-query-provider:p2:inst-frontx-query-client-provider\n\n// @cpt-begin:cpt-frontx-dod-request-lifecycle-query-provider:p2:inst-query-client-context-hooks\nexport function useOptionalFrontXQueryClient(): QueryClient | undefined {\n  return useContext(FrontXQueryClientContext);\n}\n\nexport function useRequiredFrontXQueryClient(): QueryClient {\n  const queryClient = useOptionalFrontXQueryClient();\n  if (!queryClient) {\n    throw new Error(\n      '[FrontXProvider] No query cache available. Add queryCache() or queryCacheShared() to your plugin composition.'\n    );\n  }\n\n  return queryClient;\n}\n// @cpt-end:cpt-frontx-dod-request-lifecycle-query-provider:p2:inst-query-client-context-hooks\n\n// @cpt-begin:implement-endpoint-descriptors:p3:inst-descriptor-fetch-stale-helpers\nfunction buildPageContext<TPage>(\n  page: TPage,\n  pages: readonly TPage[],\n  descriptor: EndpointDescriptor<TPage>,\n  descriptors: readonly EndpointDescriptor<TPage>[]\n): ApiInfiniteQueryPageContext<TPage> {\n  return {\n    page,\n    pages,\n    descriptor,\n    descriptors,\n  };\n}\n\nfunction normalizeFetchStaleTime(staleTime: unknown): number | undefined {\n  if (staleTime === 'static') {\n    return Number.POSITIVE_INFINITY;\n  }\n\n  return typeof staleTime === 'number' ? staleTime : undefined;\n}\n\nfunction resolveFetchStaleTime<TData>(\n  queryClient: QueryClient,\n  descriptor: EndpointDescriptor<TData>,\n  overrideStaleTime?: number\n): number | undefined {\n  return normalizeFetchStaleTime(\n    overrideStaleTime ??\n      descriptor.staleTime ??\n      queryClient.getDefaultOptions().queries?.staleTime\n  );\n}\n\nfunction fetchDescriptor<TData>(\n  descriptor: EndpointDescriptor<TData>,\n  options?: { signal?: AbortSignal; staleTime?: number }\n): Promise<TData> {\n  return (descriptor as RuntimeAwareEndpointDescriptor<TData>).fetch(options);\n}\n// @cpt-end:implement-endpoint-descriptors:p3:inst-descriptor-fetch-stale-helpers\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-use-api-query:p2:inst-delegate-frontx-use-query\nexport function useFrontXQuery<TData = unknown, TError = Error>(\n  descriptor: EndpointDescriptor<TData>,\n  overrides?: ApiQueryOverrides\n) {\n  const queryClient = useRequiredFrontXQueryClient();\n  const staleTime = resolveFetchStaleTime(queryClient, descriptor, overrides?.staleTime);\n  const result = useQuery<TData, TError>({\n    queryKey: descriptor.key as unknown[],\n    queryFn: ({ signal }) => fetchDescriptor(descriptor, { signal, staleTime }),\n    staleTime: overrides?.staleTime ?? descriptor.staleTime,\n    gcTime: overrides?.gcTime ?? descriptor.gcTime,\n  });\n\n  return {\n    data: result.data,\n    error: result.error,\n    isLoading: result.isLoading,\n    isFetching: result.isFetching,\n    isError: result.isError,\n    refetch: result.refetch,\n  };\n}\n// @cpt-end:cpt-frontx-flow-request-lifecycle-use-api-query:p2:inst-delegate-frontx-use-query\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-use-api-query:p2:inst-delegate-frontx-use-suspense-query\nexport function useFrontXSuspenseQuery<TData = unknown, TError = Error>(\n  descriptor: EndpointDescriptor<TData>,\n  overrides?: ApiQueryOverrides\n) {\n  const queryClient = useRequiredFrontXQueryClient();\n  const staleTime = resolveFetchStaleTime(queryClient, descriptor, overrides?.staleTime);\n  const result = useSuspenseQuery<TData, TError>({\n    queryKey: descriptor.key as unknown[],\n    queryFn: ({ signal }) => fetchDescriptor(descriptor, { signal, staleTime }),\n    staleTime: overrides?.staleTime ?? descriptor.staleTime,\n    gcTime: overrides?.gcTime ?? descriptor.gcTime,\n  });\n\n  return {\n    data: result.data,\n    error: result.error,\n    isFetching: result.isFetching,\n    refetch: async () => {\n      await result.refetch();\n    },\n  };\n}\n// @cpt-end:cpt-frontx-flow-request-lifecycle-use-api-query:p2:inst-delegate-frontx-use-suspense-query\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-use-api-query:p2:inst-delegate-frontx-use-infinite-query\nexport function useFrontXInfiniteQuery<TPage = unknown, TError = Error>(\n  options: ApiInfiniteQueryOptions<TPage>\n) {\n  const queryClient = useRequiredFrontXQueryClient();\n  const result = useInfiniteQuery<\n    TPage,\n    TError,\n    readonly TPage[],\n    readonly unknown[],\n    EndpointDescriptor<TPage>\n  >({\n    queryKey: options.initialPage.key,\n    initialPageParam: options.initialPage,\n    queryFn: ({ pageParam, signal }) =>\n      fetchDescriptor(pageParam, {\n        signal,\n        staleTime: resolveFetchStaleTime(queryClient, pageParam, options.staleTime),\n      }),\n    getNextPageParam: (\n      lastPage,\n      allPages,\n      lastPageDescriptor,\n      allPageDescriptors\n    ) =>\n      options.getNextPage(\n        buildPageContext(\n          lastPage,\n          allPages,\n          lastPageDescriptor,\n          allPageDescriptors\n        )\n      ),\n    getPreviousPageParam: options.getPreviousPage\n      ? (firstPage, allPages, firstPageDescriptor, allPageDescriptors) =>\n          options.getPreviousPage?.(\n            buildPageContext(\n              firstPage,\n              allPages,\n              firstPageDescriptor,\n              allPageDescriptors\n            )\n          )\n      : undefined,\n    select: (data) => data.pages,\n    staleTime: options.staleTime ?? options.initialPage.staleTime,\n    gcTime: options.gcTime ?? options.initialPage.gcTime,\n    maxPages: options.maxPages,\n  });\n\n  return {\n    data: result.data,\n    error: result.error,\n    isLoading: result.isLoading,\n    isFetching: result.isFetching,\n    isError: result.isError,\n    hasNextPage: result.hasNextPage ?? false,\n    hasPreviousPage: result.hasPreviousPage ?? false,\n    isFetchingNextPage: result.isFetchingNextPage,\n    isFetchingPreviousPage: result.isFetchingPreviousPage,\n    fetchNextPage: async () => {\n      await result.fetchNextPage();\n    },\n    fetchPreviousPage: async () => {\n      await result.fetchPreviousPage();\n    },\n    refetch: async () => {\n      await result.refetch();\n    },\n  };\n}\n// @cpt-end:cpt-frontx-flow-request-lifecycle-use-api-query:p2:inst-delegate-frontx-use-infinite-query\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-use-api-query:p2:inst-delegate-frontx-use-suspense-infinite-query\nexport function useFrontXSuspenseInfiniteQuery<TPage = unknown, TError = Error>(\n  options: ApiInfiniteQueryOptions<TPage>\n) {\n  const queryClient = useRequiredFrontXQueryClient();\n  const result = useSuspenseInfiniteQuery<\n    TPage,\n    TError,\n    readonly TPage[],\n    readonly unknown[],\n    EndpointDescriptor<TPage>\n  >({\n    queryKey: options.initialPage.key,\n    initialPageParam: options.initialPage,\n    queryFn: ({ pageParam, signal }) =>\n      fetchDescriptor(pageParam, {\n        signal,\n        staleTime: resolveFetchStaleTime(queryClient, pageParam, options.staleTime),\n      }),\n    getNextPageParam: (\n      lastPage,\n      allPages,\n      lastPageDescriptor,\n      allPageDescriptors\n    ) =>\n      options.getNextPage(\n        buildPageContext(\n          lastPage,\n          allPages,\n          lastPageDescriptor,\n          allPageDescriptors\n        )\n      ),\n    getPreviousPageParam: options.getPreviousPage\n      ? (firstPage, allPages, firstPageDescriptor, allPageDescriptors) =>\n          options.getPreviousPage?.(\n            buildPageContext(\n              firstPage,\n              allPages,\n              firstPageDescriptor,\n              allPageDescriptors\n            )\n          )\n      : undefined,\n    select: (data) => data.pages,\n    staleTime: options.staleTime ?? options.initialPage.staleTime,\n    gcTime: options.gcTime ?? options.initialPage.gcTime,\n    maxPages: options.maxPages,\n  });\n\n  return {\n    data: result.data,\n    error: result.error,\n    isFetching: result.isFetching,\n    hasNextPage: result.hasNextPage ?? false,\n    hasPreviousPage: result.hasPreviousPage ?? false,\n    isFetchingNextPage: result.isFetchingNextPage,\n    isFetchingPreviousPage: result.isFetchingPreviousPage,\n    fetchNextPage: async () => {\n      await result.fetchNextPage();\n    },\n    fetchPreviousPage: async () => {\n      await result.fetchPreviousPage();\n    },\n    refetch: async () => {\n      await result.refetch();\n    },\n  };\n}\n// @cpt-end:cpt-frontx-flow-request-lifecycle-use-api-query:p2:inst-delegate-frontx-use-suspense-infinite-query\n\n// @cpt-begin:cpt-frontx-flow-request-lifecycle-use-api-mutation:p2:inst-delegate-frontx-use-mutation\nexport function useFrontXMutation<\n  TData = unknown,\n  TError = Error,\n  TVariables = void,\n  TContext = unknown,\n>(\n  options: UseApiMutationOptions<TData, TError, TVariables, TContext>,\n  callbackCtx: MutationCallbackContext\n) {\n  useRequiredFrontXQueryClient();\n\n  const latestRef = React.useRef({ options, callbackCtx });\n  latestRef.current = { options, callbackCtx };\n  const fetchAbortControllersRef = React.useRef<Set<AbortController>>(new Set());\n\n  React.useEffect(() => {\n    const fetchAbortControllers = fetchAbortControllersRef.current;\n    return () => {\n      if (latestRef.current.options.abortOnUnmount) {\n        for (const controller of fetchAbortControllers) {\n          controller.abort();\n        }\n        fetchAbortControllers.clear();\n      }\n    };\n  }, []);\n\n  const mutationFn = React.useCallback((variables: TVariables, context: MutationFunctionContext) => {\n    const cancelOnSupersede = latestRef.current.options.cancelOnSupersede;\n    if (cancelOnSupersede) {\n      for (const controller of fetchAbortControllersRef.current) {\n        controller.abort();\n      }\n      fetchAbortControllersRef.current.clear();\n    }\n\n    const controller = new AbortController();\n    fetchAbortControllersRef.current.add(controller);\n\n    const librarySignal = (context as MutationFunctionContext & { signal?: AbortSignal }).signal;\n    if (cancelOnSupersede && librarySignal) {\n      if (librarySignal.aborted) {\n        controller.abort();\n      } else {\n        librarySignal.addEventListener('abort', () => controller.abort(), { once: true });\n      }\n    }\n\n    return latestRef.current.options.endpoint\n      .fetch(variables, { signal: controller.signal })\n      .finally(() => {\n        fetchAbortControllersRef.current.delete(controller);\n      });\n  }, []);\n\n  const onMutate = React.useCallback((variables: TVariables, _context: MutationFunctionContext) => {\n    const current = latestRef.current;\n    if (!current.options.onMutate) {\n      return undefined as TContext;\n    }\n\n    return current.options.onMutate(variables, current.callbackCtx);\n  }, []);\n\n  const onSuccess = React.useCallback((data: TData, variables: TVariables, context: TContext | undefined) => {\n    const current = latestRef.current;\n    return current.options.onSuccess?.(data, variables, context, current.callbackCtx);\n  }, []);\n\n  const onError = React.useCallback((error: TError, variables: TVariables, context: TContext | undefined) => {\n    const current = latestRef.current;\n    return current.options.onError?.(error, variables, context, current.callbackCtx);\n  }, []);\n\n  const onSettled = React.useCallback((\n    data: TData | undefined,\n    error: TError | null,\n    variables: TVariables,\n    context: TContext | undefined\n  ) => {\n    const current = latestRef.current;\n    return current.options.onSettled?.(\n      data,\n      error,\n      variables,\n      context,\n      current.callbackCtx\n    );\n  }, []);\n\n  const mutation = useMutation<TData, TError, TVariables, TContext>({\n    mutationFn,\n    onMutate: options.onMutate ? onMutate : undefined,\n    onSuccess: options.onSuccess ? onSuccess : undefined,\n    onError: options.onError ? onError : undefined,\n    onSettled: options.onSettled ? onSettled : undefined,\n  });\n\n  return {\n    mutate: mutation.mutate as (variables: TVariables) => void,\n    mutateAsync: mutation.mutateAsync as (variables: TVariables) => Promise<TData>,\n    isPending: mutation.isPending,\n    error: mutation.error,\n    data: mutation.data,\n    reset: mutation.reset,\n  };\n}\n// @cpt-end:cpt-frontx-flow-request-lifecycle-use-api-mutation:p2:inst-delegate-frontx-use-mutation\n","/**\n * QueryCache — restricted interface for interacting with the shared QueryClient.\n *\n * MFEs and screen-set components access the cache only through this sanctioned\n * public interface. It is injected as { queryCache } into useApiMutation\n * callbacks and also returned by useQueryCache() for controlled imperative\n * cache access.\n */\n// @cpt-dod:cpt-frontx-dod-request-lifecycle-use-api-mutation:p2\n// @cpt-flow:cpt-frontx-flow-request-lifecycle-use-api-mutation:p2:inst-create-query-cache\n// @cpt-FEATURE:implement-endpoint-descriptors:p3\n\nimport type { EndpointDescriptor } from '@gears-frontx/framework';\nimport { eventBus } from '@gears-frontx/framework';\nimport { type QueryClient, type QueryState } from '@tanstack/react-query';\n\nexport type QueryCacheKey = readonly unknown[];\nexport type QueryCacheRefetchMode = 'active' | 'inactive' | 'all' | 'none';\nexport type QueryCacheInvalidateTarget =\n  | EndpointDescriptor<unknown>\n  | QueryCacheKey\n  | null\n  | undefined;\n\nexport interface QueryCacheState<TData = unknown, TError = Error> {\n  data: TData | undefined;\n  dataUpdatedAt: number;\n  error: TError | null;\n  errorUpdatedAt: number;\n  fetchFailureCount: number;\n  fetchFailureReason: TError | null;\n  fetchStatus: 'fetching' | 'paused' | 'idle';\n  isInvalidated: boolean;\n  status: 'pending' | 'error' | 'success';\n}\n\nexport type QueryCacheInvalidateFilters = {\n  queryKey?: QueryCacheInvalidateTarget;\n  exact?: boolean;\n  refetchType?: QueryCacheRefetchMode;\n};\n\ntype QueryCacheUpdater<T> = T | ((old: T | undefined) => T | undefined);\n\ntype CacheInvalidateEvent = {\n  queryKey: QueryCacheKey;\n  exact?: boolean;\n  refetchType?: QueryCacheRefetchMode;\n  source?: string;\n};\n\ntype CacheSetEvent = {\n  queryKey: QueryCacheKey;\n  dataOrUpdater: QueryCacheUpdater<unknown>;\n  source?: string;\n};\n\ntype CacheRemoveEvent = {\n  queryKey: QueryCacheKey;\n  source?: string;\n};\n\nconst QUERY_CLIENT_BROADCAST_TARGET = Symbol.for('frontx:query-cache:broadcast-target');\nconst QUERY_CLIENT_BROADCAST_COUNTER = Symbol.for('frontx:query-cache:broadcast-counter');\n\ntype QueryClientWithMetadata = QueryClient & {\n  [QUERY_CLIENT_BROADCAST_TARGET]?: string;\n};\n\ntype QueryClientCounterHost = typeof globalThis & {\n  [QUERY_CLIENT_BROADCAST_COUNTER]?: number;\n};\n\nfunction emitCacheEvent(event: string, payload: unknown): void {\n  (eventBus.emit as (eventType: string, payload: unknown) => void)(event, payload);\n}\n\nfunction ensureBroadcastSource(queryClient: QueryClient): string {\n  const clientWithMetadata = queryClient as QueryClientWithMetadata;\n  const existingSource = clientWithMetadata[QUERY_CLIENT_BROADCAST_TARGET];\n  if (typeof existingSource === 'string' && existingSource.length > 0) {\n    return existingSource;\n  }\n\n  const host = globalThis as QueryClientCounterHost;\n  const nextCounter = (host[QUERY_CLIENT_BROADCAST_COUNTER] ?? 0) + 1;\n  host[QUERY_CLIENT_BROADCAST_COUNTER] = nextCounter;\n\n  const source = `query-cache-${nextCounter}`;\n  clientWithMetadata[QUERY_CLIENT_BROADCAST_TARGET] = source;\n  return source;\n}\n\n// @cpt-begin:implement-endpoint-descriptors:p3:inst-resolve-key\nexport function resolveKey(target: EndpointDescriptor<unknown> | QueryCacheKey): readonly unknown[] {\n  if (\n    target !== null &&\n    typeof target === 'object' &&\n    !Array.isArray(target) &&\n    'key' in target &&\n    'fetch' in target &&\n    Array.isArray(target.key) &&\n    typeof target.fetch === 'function'\n  ) {\n    return target.key;\n  }\n\n  return target as readonly unknown[];\n}\n// @cpt-end:implement-endpoint-descriptors:p3:inst-resolve-key\n\n// @cpt-begin:cpt-frontx-dod-request-lifecycle-use-api-mutation:p2:inst-query-cache-interface\nexport interface QueryCache {\n  get<T>(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): T | undefined;\n  getState<TData = unknown, TError = Error>(\n    queryKey: EndpointDescriptor<unknown> | QueryCacheKey\n  ): QueryCacheState<TData, TError> | undefined;\n  set<T>(\n    queryKey: EndpointDescriptor<unknown> | QueryCacheKey,\n    dataOrUpdater: T | ((old: T | undefined) => T | undefined)\n  ): void;\n  cancel(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): Promise<void>;\n  invalidate(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): Promise<void>;\n  invalidateMany(filters?: QueryCacheInvalidateFilters | null): Promise<void>;\n  remove(queryKey: EndpointDescriptor<unknown> | QueryCacheKey): void;\n}\n// @cpt-end:cpt-frontx-dod-request-lifecycle-use-api-mutation:p2:inst-query-cache-interface\n\n// @cpt-begin:cpt-frontx-dod-request-lifecycle-use-api-mutation:p2:inst-mutation-callback-context\nexport interface MutationCallbackContext {\n  queryCache: QueryCache;\n}\n// @cpt-end:cpt-frontx-dod-request-lifecycle-use-api-mutation:p2:inst-mutation-callback-context\n\nfunction toQueryUpdater<T>(\n  dataOrUpdater: QueryCacheUpdater<T>\n): (old: T | undefined) => T | undefined {\n  if (typeof dataOrUpdater === 'function') {\n    return dataOrUpdater as (old: T | undefined) => T | undefined;\n  }\n\n  return () => dataOrUpdater;\n}\n\nfunction mapQueryState<TData, TError = Error>(\n  state: QueryState<TData, TError>\n): QueryCacheState<TData, TError> {\n  return {\n    data: state.data,\n    dataUpdatedAt: state.dataUpdatedAt,\n    error: state.error,\n    errorUpdatedAt: state.errorUpdatedAt,\n    fetchFailureCount: state.fetchFailureCount,\n    fetchFailureReason: state.fetchFailureReason,\n    fetchStatus: state.fetchStatus,\n    isInvalidated: state.isInvalidated,\n    status: state.status,\n  };\n}\n\n// @cpt-begin:implement-endpoint-descriptors:p3:inst-create-query-cache\nexport function createQueryCache(queryClient: QueryClient): QueryCache {\n  return {\n    get: <T,>(key: EndpointDescriptor<unknown> | QueryCacheKey): T | undefined => {\n      return queryClient.getQueryData<T>(resolveKey(key));\n    },\n    getState: <TData = unknown, TError = Error>(key: EndpointDescriptor<unknown> | QueryCacheKey) => {\n      const state = queryClient.getQueryState<TData, TError>(resolveKey(key));\n      return state ? mapQueryState(state) : undefined;\n    },\n    set: <T,>(key: EndpointDescriptor<unknown> | QueryCacheKey, dataOrUpdater: QueryCacheUpdater<T>): void => {\n      const resolvedKey = resolveKey(key);\n      queryClient.setQueryData<T>(resolvedKey, toQueryUpdater(dataOrUpdater));\n      emitCacheEvent('cache/set', {\n        queryKey: resolvedKey,\n        dataOrUpdater: dataOrUpdater as QueryCacheUpdater<unknown>,\n        source: ensureBroadcastSource(queryClient),\n      } satisfies CacheSetEvent);\n    },\n    cancel: (key: EndpointDescriptor<unknown> | QueryCacheKey): Promise<void> => {\n      return queryClient.cancelQueries({ queryKey: resolveKey(key) });\n    },\n    invalidate: (key: EndpointDescriptor<unknown> | QueryCacheKey): Promise<void> => {\n      const resolvedKey = resolveKey(key);\n      const result = queryClient.invalidateQueries({ queryKey: resolvedKey });\n      emitCacheEvent('cache/invalidate', {\n        queryKey: resolvedKey,\n        source: ensureBroadcastSource(queryClient),\n      } satisfies CacheInvalidateEvent);\n      return result;\n    },\n    invalidateMany: (filters): Promise<void> => {\n      if (filters?.queryKey == null) {\n        return Promise.resolve();\n      }\n\n      const resolvedKey = resolveKey(filters.queryKey);\n      if (!Array.isArray(resolvedKey) || resolvedKey.length === 0) {\n        return Promise.resolve();\n      }\n\n      const payload = {\n        ...filters,\n        queryKey: resolvedKey,\n      };\n      const result = queryClient.invalidateQueries(payload);\n      emitCacheEvent('cache/invalidate', {\n        ...payload,\n        source: ensureBroadcastSource(queryClient),\n      } satisfies CacheInvalidateEvent);\n      return result;\n    },\n    remove: (key: EndpointDescriptor<unknown> | QueryCacheKey): void => {\n      const resolvedKey = resolveKey(key);\n      queryClient.removeQueries({ queryKey: resolvedKey });\n      emitCacheEvent('cache/remove', {\n        queryKey: resolvedKey,\n        source: ensureBroadcastSource(queryClient),\n      } satisfies CacheRemoveEvent);\n    },\n  };\n}\n// @cpt-end:implement-endpoint-descriptors:p3:inst-create-query-cache\n","/**\n * Test-only entry for @gears-frontx/react.\n *\n * Utilities here are intended for Vitest (or similar) suites that need access\n * to query-client wiring without importing package internals directly.\n */\n\n// @cpt-dod:cpt-frontx-dod-react-bindings-provider:p1\n\n// @cpt-begin:cpt-frontx-dod-react-bindings-provider:p1:inst-react-testing-reexports\nexport {\n  bootstrapFrontXQueryClient,\n  resolveFrontXQueryClient,\n  useOptionalFrontXQueryClient,\n} from './queryClient';\n\n/** App-layer tests must import this from `@gears-frontx/react/testing`, not `@gears-frontx/framework/testing`. */\nexport { describeBootstrapMfeContract } from '@gears-frontx/framework/testing';\nexport type {\n  BootstrapMfeResolveArgs,\n  BootstrapMfeTestSpecOptions,\n} from '@gears-frontx/framework/testing';\n// @cpt-end:cpt-frontx-dod-react-bindings-provider:p1:inst-react-testing-reexports\n"],"mappings":";AAAA,OAAO;AAAA,EACL;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AACP;AAAA,EACE;AAAA,OAGK;;;ACVP,SAAS,gBAAgB;;;ADmJjB;AAzHR,IAAM,0BAA0B,uBAAO,IAAI,+BAA+B;AAC1E,IAAM,mCAAmC,uBAAO,IAAI,wCAAwC;AAS5F,IAAM,2BAA2B,cAAuC,MAAS;AAajF,IAAM,kBAAkB,OAAO,WAAW,WAAW,cAAc,YAAY;AAExE,SAAS,yBAAyB,KAAyC;AAChF,QAAM,YAAY;AAClB,SAAO,UAAU,uBAAuB,KAAK,UAAU,gCAAgC,IAAI;AAC7F;AA+BO,SAAS,2BAA2B,KAAyC;AAClF,SAAO,yBAAyB,GAAG;AACrC;AA0EO,SAAS,+BAAwD;AACtE,SAAO,WAAW,wBAAwB;AAC5C;;;AE/JA,SAAS,oCAAoC;","names":[]}

package/dist/types-Cjd20AT-.d.cts

@@ -0,0 +1,231 @@
+import * as React from 'react';
+import { ReactNode } from 'react';
+import { ChildMfeBridge, AccessRecord, AccessQuery, FrontXConfig, FrontXApp, RootState, Formatters, Language } from '@gears-frontx/framework';
+
+/**
+ * MFE Context Value
+ * Contains bridge and metadata about the MFE instance.
+ */
+interface MfeContextValue {
+    /** Child bridge for communication with host */
+    bridge: ChildMfeBridge;
+    /** Extension ID */
+    extensionId: string;
+    /** Domain ID where MFE is mounted */
+    domainId: string;
+}
+/**
+ * MFE Context
+ * Holds the MFE bridge and metadata for child components.
+ */
+declare const MfeContext: React.Context<MfeContextValue | null>;
+/**
+ * Use the MFE context.
+ * Throws if used outside of MFE context.
+ *
+ * @returns The MFE context value
+ */
+declare function useMfeContext(): MfeContextValue;
+
+/**
+ * @gears-frontx/react - Type Definitions
+ *
+ * Core types for FrontX React bindings.
+ * Provides type-safe hooks and components.
+ *
+ * Now using real imports from @gears-frontx/framework since packages are built together.
+ */
+
+/**
+ * Gears FrontX-owned query result type.
+ * Returned by useApiQuery — callers depend on this contract, not on TanStack internals.
+ */
+interface ApiQueryResult<TData, TError = Error> {
+    data: TData | undefined;
+    error: TError | null;
+    isLoading: boolean;
+    isFetching: boolean;
+    isError: boolean;
+    refetch: () => Promise<unknown>;
+}
+/**
+ * Gears FrontX-owned suspense query result type.
+ * Returned by useApiSuspenseQuery — callers depend on this contract, not on TanStack internals.
+ */
+interface ApiSuspenseQueryResult<TData, TError = Error> {
+    data: TData;
+    error: TError | null;
+    isFetching: boolean;
+    refetch: () => Promise<void>;
+}
+/**
+ * Gears FrontX-owned infinite query result type.
+ * Returned by useApiInfiniteQuery for descriptor-driven pagination.
+ */
+interface ApiInfiniteQueryResult<TPage, TError = Error> {
+    data: readonly TPage[] | undefined;
+    error: TError | null;
+    isLoading: boolean;
+    isFetching: boolean;
+    isError: boolean;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    isFetchingNextPage: boolean;
+    isFetchingPreviousPage: boolean;
+    fetchNextPage: () => Promise<void>;
+    fetchPreviousPage: () => Promise<void>;
+    refetch: () => Promise<void>;
+}
+/**
+ * Gears FrontX-owned suspense infinite query result type.
+ * Returned by useApiSuspenseInfiniteQuery for descriptor-driven pagination.
+ */
+interface ApiSuspenseInfiniteQueryResult<TPage, TError = Error> {
+    data: readonly TPage[];
+    error: TError | null;
+    isFetching: boolean;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    isFetchingNextPage: boolean;
+    isFetchingPreviousPage: boolean;
+    fetchNextPage: () => Promise<void>;
+    fetchPreviousPage: () => Promise<void>;
+    refetch: () => Promise<void>;
+}
+/**
+ * Gears FrontX-owned mutation result type.
+ * Returned by useApiMutation — callers depend on this contract, not on TanStack internals.
+ */
+interface ApiMutationResult<TData, TError = Error, TVariables = void> {
+    mutate: (variables: TVariables) => void;
+    mutateAsync: (variables: TVariables) => Promise<TData>;
+    isPending: boolean;
+    error: TError | null;
+    data: TData | undefined;
+    reset: () => void;
+}
+type Selector<TResult, TState = RootState> = (state: TState) => TResult;
+type TranslationParams = Record<string, string | number | boolean>;
+/**
+ * FrontX Provider Props
+ * Props for the main FrontXProvider component.
+ *
+ * @example
+ * ```tsx
+ * <FrontXProvider config={{ devMode: true }}>
+ *   <App />
+ * </FrontXProvider>
+ *
+ * // With pre-built app
+ * const app = createFrontX().use(microfrontends()).build();
+ * <FrontXProvider app={app}>
+ *   <App />
+ * </FrontXProvider>
+ *
+ * // With MFE bridge (for MFE components)
+ * <FrontXProvider mfeBridge={{ bridge, extensionId, domainId }}>
+ *   <MyMfeApp />
+ * </FrontXProvider>
+ *
+ * // QueryCache is resolved from the app's plugin composition
+ * <FrontXProvider app={app}>
+ *   <MyMfeApp />
+ * </FrontXProvider>
+ * ```
+ */
+interface FrontXProviderProps {
+    /** Child components */
+    children: ReactNode;
+    /** FrontX configuration */
+    config?: FrontXConfig;
+    /** Pre-built FrontX app instance (optional) */
+    app?: FrontXApp;
+    /** MFE bridge context (for MFE components) */
+    mfeBridge?: MfeContextValue;
+}
+/**
+ * useFrontX Hook Return Type
+ * Returns the FrontX app instance from context.
+ */
+type UseFrontXReturn = FrontXApp;
+/**
+ * useAppSelector Hook
+ * Type-safe selector hook for Redux state.
+ *
+ * @template TResult - The result type of the selector
+ */
+type UseAppSelector = <TResult>(selector: Selector<TResult>) => TResult;
+/**
+ * useAppDispatch Hook Return Type
+ * Returns the typed dispatch function.
+ */
+type UseAppDispatchReturn = (action: unknown) => unknown;
+/**
+ * useTranslation Hook Return Type
+ * Translation utilities.
+ */
+interface UseTranslationReturn {
+    /** Translate a key */
+    t: (key: string, params?: TranslationParams) => string;
+    /** Current language */
+    language: Language | null;
+    /** Change language */
+    setLanguage: (language: Language) => void;
+    /** Check if current language is RTL */
+    isRTL: boolean;
+}
+/**
+ * useScreenTranslations Hook Return Type
+ * Screen-level translation loading state.
+ */
+interface UseScreenTranslationsReturn {
+    /** Whether translations are loaded */
+    isLoaded: boolean;
+    /** Loading error (if any) */
+    error: Error | null;
+}
+/**
+ * useTheme Hook Return Type
+ * Theme utilities.
+ */
+interface UseThemeReturn {
+    /** Current theme ID */
+    currentTheme: string | undefined;
+    /** All available themes */
+    themes: Array<{
+        id: string;
+        name: string;
+    }>;
+    /** Change theme */
+    setTheme: (themeId: string) => void;
+}
+/**
+ * useFormatters Hook Return Type
+ * Locale-aware formatters (locale from i18nRegistry.getLanguage()).
+ * References @gears-frontx/i18n Formatters so signatures stay in sync.
+ */
+type UseFormattersReturn = Formatters;
+/**
+ * useCanAccess Hook Return Type
+ * Result of an RBAC access check.
+ * allow is false until an explicit 'allow' decision arrives (pessimistic default).
+ */
+interface UseCanAccessResult {
+    allow: boolean;
+    isResolving: boolean;
+}
+/**
+ * CanAccess Component Props.
+ * Pessimistic: renders `denied` (or `loading`) until an authoritative 'allow' arrives.
+ */
+interface CanAccessProps<TRecord extends AccessRecord = AccessRecord> {
+    query: AccessQuery<TRecord>;
+    /** Content rendered when access is explicitly allowed. */
+    allowed: ReactNode;
+    /** Content rendered on deny or error. Defaults to null. */
+    denied?: ReactNode;
+    /** Optional slot shown while the decision is resolving. Falls back to `denied`. */
+    loading?: ReactNode;
+}
+
+export { type ApiQueryResult as A, type CanAccessProps as C, type FrontXProviderProps as F, type MfeContextValue as M, type UseTranslationReturn as U, type ApiInfiniteQueryResult as a, type ApiMutationResult as b, type UseScreenTranslationsReturn as c, type UseFormattersReturn as d, type UseThemeReturn as e, type ApiSuspenseQueryResult as f, type ApiSuspenseInfiniteQueryResult as g, type UseCanAccessResult as h, MfeContext as i, type UseAppDispatchReturn as j, type UseAppSelector as k, type UseFrontXReturn as l, useMfeContext as u };