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

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,77 @@
+"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_react2 = __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/hooks/useLatest.ts
+var import_react = require("react");
+
+// 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_react2.createContext)(void 0);
+var useCommitEffect = typeof globalThis.window === "undefined" ? import_react2.useEffect : import_react2.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_react2.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","../src/hooks/useLatest.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';\nimport { useLatest } from './hooks/useLatest';\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 = useLatest({ options, callbackCtx });\n  const fetchAbortControllersRef = React.useRef<Set<AbortController>>(new Set());\n\n  // Effect event: reads abortOnUnmount from the most recent render, not\n  // whatever option value was current when the unmount effect was set up.\n  const abortFetchesOnUnmount = React.useEffectEvent(() => {\n    if (options.abortOnUnmount) {\n      for (const controller of fetchAbortControllersRef.current) {\n        controller.abort();\n      }\n      fetchAbortControllersRef.current.clear();\n    }\n  });\n\n  React.useEffect(() => {\n    return () => {\n      abortFetchesOnUnmount();\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    // latestRef's identity never changes (useLatest returns a stable ref\n    // object) — listing it satisfies exhaustive-deps without recreating this\n    // callback on every render.\n  }, [latestRef]);\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    // latestRef's identity never changes — see mutationFn above.\n  }, [latestRef]);\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    // latestRef's identity never changes — see mutationFn above.\n  }, [latestRef]);\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    // latestRef's identity never changes — see mutationFn above.\n  }, [latestRef]);\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    // latestRef's identity never changes — see mutationFn above.\n  }, [latestRef]);\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 * useLatest - keeps a ref pinned to the most recently rendered value\n *\n * A handful of hooks/components in this package need to read the current\n * value of a prop or option from inside a callback or effect-cleanup closure\n * that must NOT re-run every time that value changes (e.g. a stable\n * useCallback with `[]` deps, or a mount/unmount effect keyed on identity\n * rather than on every option). Stashing the value in a ref sidesteps the\n * closure staleness without pulling the value into the dependency array.\n *\n * The write happens inside a deps-less effect (runs after every commit)\n * rather than during render, because refs must not be mutated while\n * rendering: render can be invoked more than once per commit (React\n * StrictMode's double-invoke, and future concurrent-rendering paths that\n * may discard a render), so a render-time write can leave the ref out of\n * sync with what was actually committed to the DOM. A deps-less effect\n * runs exactly once per real commit, so the ref always reflects the value\n * that was last rendered.\n */\n\nimport { useEffect, useRef, type RefObject } from 'react';\n\n/**\n * Returns a ref that always holds the most recently rendered `value`.\n *\n * The ref identity is stable across renders (same object returned every\n * time), so it is safe to add to a `useCallback`/`useEffect` dependency\n * array without causing the callback/effect to be recreated.\n */\nexport function useLatest<T>(value: T): RefObject<T> {\n  const ref = useRef(value);\n\n  // Deps-less: must run after every render so `ref.current` never lags\n  // behind the value that was just committed. See module doc for why this\n  // write cannot happen during render itself.\n  useEffect(() => {\n    ref.current = value;\n  });\n\n  return ref;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,IAAAA,gBAOO;AACP,yBAUO;AACP,IAAAC,oBAIO;;;ACVP,uBAAyB;;;ACOzB,mBAAkD;;;AF6I1C;AAzHR,IAAM,0BAA0B,uBAAO,IAAI,+BAA+B;AAC1E,IAAM,mCAAmC,uBAAO,IAAI,wCAAwC;AAS5F,IAAM,+BAA2B,6BAAuC,MAAS;AAajF,IAAM,kBAAkB,OAAO,WAAW,WAAW,cAAc,0BAAY;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,0BAAW,wBAAwB;AAC5C;;;ADhKA,qBAA6C;","names":["import_react","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,54 @@
+// src/queryClient.tsx
+import React, {
+  createContext,
+  useContext,
+  useEffect as useEffect2,
+  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/hooks/useLatest.ts
+import { useEffect, useRef } from "react";
+
+// 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" ? useEffect2 : 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/hooks/useLatest.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';\nimport { useLatest } from './hooks/useLatest';\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 = useLatest({ options, callbackCtx });\n  const fetchAbortControllersRef = React.useRef<Set<AbortController>>(new Set());\n\n  // Effect event: reads abortOnUnmount from the most recent render, not\n  // whatever option value was current when the unmount effect was set up.\n  const abortFetchesOnUnmount = React.useEffectEvent(() => {\n    if (options.abortOnUnmount) {\n      for (const controller of fetchAbortControllersRef.current) {\n        controller.abort();\n      }\n      fetchAbortControllersRef.current.clear();\n    }\n  });\n\n  React.useEffect(() => {\n    return () => {\n      abortFetchesOnUnmount();\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    // latestRef's identity never changes (useLatest returns a stable ref\n    // object) — listing it satisfies exhaustive-deps without recreating this\n    // callback on every render.\n  }, [latestRef]);\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    // latestRef's identity never changes — see mutationFn above.\n  }, [latestRef]);\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    // latestRef's identity never changes — see mutationFn above.\n  }, [latestRef]);\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    // latestRef's identity never changes — see mutationFn above.\n  }, [latestRef]);\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    // latestRef's identity never changes — see mutationFn above.\n  }, [latestRef]);\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 * useLatest - keeps a ref pinned to the most recently rendered value\n *\n * A handful of hooks/components in this package need to read the current\n * value of a prop or option from inside a callback or effect-cleanup closure\n * that must NOT re-run every time that value changes (e.g. a stable\n * useCallback with `[]` deps, or a mount/unmount effect keyed on identity\n * rather than on every option). Stashing the value in a ref sidesteps the\n * closure staleness without pulling the value into the dependency array.\n *\n * The write happens inside a deps-less effect (runs after every commit)\n * rather than during render, because refs must not be mutated while\n * rendering: render can be invoked more than once per commit (React\n * StrictMode's double-invoke, and future concurrent-rendering paths that\n * may discard a render), so a render-time write can leave the ref out of\n * sync with what was actually committed to the DOM. A deps-less effect\n * runs exactly once per real commit, so the ref always reflects the value\n * that was last rendered.\n */\n\nimport { useEffect, useRef, type RefObject } from 'react';\n\n/**\n * Returns a ref that always holds the most recently rendered `value`.\n *\n * The ref identity is stable across renders (same object returned every\n * time), so it is safe to add to a `useCallback`/`useEffect` dependency\n * array without causing the callback/effect to be recreated.\n */\nexport function useLatest<T>(value: T): RefObject<T> {\n  const ref = useRef(value);\n\n  // Deps-less: must run after every render so `ref.current` never lags\n  // behind the value that was just committed. See module doc for why this\n  // write cannot happen during render itself.\n  useEffect(() => {\n    ref.current = value;\n  });\n\n  return ref;\n}\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,aAAAA;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;;;ACOzB,SAAS,WAAW,cAA8B;;;AF6I1C;AAzHR,IAAM,0BAA0B,uBAAO,IAAI,+BAA+B;AAC1E,IAAM,mCAAmC,uBAAO,IAAI,wCAAwC;AAS5F,IAAM,2BAA2B,cAAuC,MAAS;AAajF,IAAM,kBAAkB,OAAO,WAAW,WAAW,cAAcC,aAAY;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;;;AGhKA,SAAS,oCAAoC;","names":["useEffect","useEffect"]}

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 };