@dereekb/firebase-server 13.2.2 → 13.3.1

package/test/src/lib/firebase/firebase.admin.nest.d.ts

@@ -1,30 +1,80 @@
 import { AbstractChildTestContextFixture, type BuildTestsWithContextFunction, type TestContextFactory, type TestContextFixture } from '@dereekb/util/test';
 import { AbstractFirebaseAdminTestContextInstanceChild, type FirebaseAdminTestContextInstance } from './firebase.admin';
-import { type Abstract, type INestApplicationContext, type Provider, type Type } from '@nestjs/common';
+import { INestApplication, type Abstract, type INestApplicationContext, type Provider, type Type } from '@nestjs/common';
 import { type StorageBucketId } from '@dereekb/firebase';
-import { type NestAppPromiseGetter } from '@dereekb/firebase-server';
+import { type FirebaseServerEnvironmentConfig, type NestAppPromiseGetter, type NestServerInstanceConfig } from '@dereekb/firebase-server';
 import { type TestingModule } from '@nestjs/testing';
-import { type ArrayOrValue, type ClassType, type Getter } from '@dereekb/util';
-import { type ServerEnvironmentConfig } from '@dereekb/nestjs';
+import { type ArrayOrValue, type ClassType, type Getter, Maybe } from '@dereekb/util';
+/**
+ * NestJS injection token used to provide the {@link NestServerInstanceConfig} to the test's
+ * {@link TestingModule}. The instance is injected during nest application creation so that
+ * production configuration (global prefix, webhooks, etc.) can be applied in tests.
+ */
+export declare const FIREBASE_ADMIN_NEST_TEST_SERVER_INSTANCE_CONFIG_TOKEN = "FIREBASE_ADMIN_NEST_TEST_SERVER_INSTANCE_CONFIG_TOKEN";
+/**
+ * Extends the Firebase Admin test context with NestJS {@link TestingModule} access.
+ *
+ * Provides the compiled NestJS module, a way to resolve providers via `get()`,
+ * and helpers for creating / initializing a full {@link INestApplication} for
+ * integration tests that need HTTP or middleware support.
+ */
 export interface FirebaseAdminNestTestContext {
     readonly nest: TestingModule;
     readonly nestAppPromiseGetter: NestAppPromiseGetter;
+    /**
+     * Returns the configured nest application singleton for this context.
+     *
+     * If it does not exist, calls `createNewNestApplication` and returns the result.
+     */
+    loadInitializedNestApplication(): Promise<INestApplication>;
+    /**
+     * Creates a new blank nest application.
+     */
+    createNewNestApplication(): INestApplication;
     get<TInput = any, TResult = TInput>(typeOrToken: Type<TInput> | Abstract<TInput> | string | symbol, options?: {
         strict: boolean;
     }): TResult;
 }
+/**
+ * Utility intersection type combining {@link FirebaseAdminNestTestContext} with a
+ * {@link TestContextFixture} parameterized by the parent instance type.
+ *
+ * Useful as a type constraint when a helper needs both NestJS context methods and
+ * fixture lifecycle access.
+ */
 export type FirebaseAdminNestTestContextFixtureType<PI extends FirebaseAdminTestContextInstance> = FirebaseAdminNestTestContext & TestContextFixture<PI>;
+/**
+ * Child fixture that wraps a {@link FirebaseAdminNestTestContextInstance} and forwards
+ * all {@link FirebaseAdminNestTestContext} members to the underlying instance.
+ *
+ * Created by {@link firebaseAdminNestContextWithFixture} during test setup. Tests receive
+ * this fixture and use it to access the NestJS {@link TestingModule}, resolve providers,
+ * and create application instances.
+ */
 export declare class FirebaseAdminNestTestContextFixture<PI extends FirebaseAdminTestContextInstance = FirebaseAdminTestContextInstance, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends FirebaseAdminNestTestContextInstance<PI> = FirebaseAdminNestTestContextInstance<PI>> extends AbstractChildTestContextFixture<I, PF> implements FirebaseAdminNestTestContext {
     get nest(): TestingModule;
     get nestAppPromiseGetter(): Getter<Promise<INestApplicationContext>>;
+    createNewNestApplication(): INestApplication;
+    loadInitializedNestApplication(): Promise<INestApplication>;
     get<TInput = any, TResult = TInput>(typeOrToken: Type<TInput> | Abstract<TInput> | string | symbol, options?: {
         strict: boolean;
     }): TResult;
 }
+/**
+ * Concrete instance that holds the compiled NestJS {@link TestingModule} and provides
+ * methods for creating and initializing a full {@link INestApplication}.
+ *
+ * Applies production-like configuration (global route prefix, server instance hooks)
+ * from {@link FIREBASE_ADMIN_NEST_TEST_SERVER_INSTANCE_CONFIG_TOKEN} when creating applications,
+ * ensuring test applications mirror production setup.
+ */
 export declare class FirebaseAdminNestTestContextInstance<PI extends FirebaseAdminTestContextInstance = FirebaseAdminTestContextInstance> extends AbstractFirebaseAdminTestContextInstanceChild<PI> implements FirebaseAdminNestTestContext {
     readonly nest: TestingModule;
     readonly nestAppPromiseGetter: Getter<Promise<INestApplicationContext>>;
+    readonly _loadInitializedNestApplication: import("@dereekb/util").CachedFactoryWithInput<Promise<INestApplication<any>>, unknown>;
     constructor(parent: PI, nest: TestingModule);
+    createNewNestApplication(): INestApplication;
+    loadInitializedNestApplication(): Promise<INestApplication>;
     get<TInput = any, TResult = TInput>(typeOrToken: Type<TInput> | Abstract<TInput> | string | symbol, options?: {
         strict?: boolean | undefined;
         each?: undefined | false;
@@ -34,53 +84,111 @@ export interface FirebaseAdminNestTestConfig<PI extends FirebaseAdminTestContext
     /**
      * Creates a new fixture.
      */
-    makeFixture?: (f: PF) => C;
+    readonly makeFixture?: (f: PF) => C;
     /**
      * Root module to import.
      */
-    nestModules: ArrayOrValue<ClassType>;
+    readonly nestModules: ArrayOrValue<ClassType>;
+    /**
+     * Optional `NestServerInstanceConfig` from the production app setup.
+     *
+     * When provided, shared configuration (global prefix, webhooks, AppCheck, storage, etc.)
+     * is derived from this config via `buildNestServerRootModule`, ensuring tests match production.
+     *
+     * Fields like `moduleClass` and `applicationOptions` are ignored — the test uses `nestModules` instead.
+     * Test-specific overrides (e.g., `injectFirebaseServerAppTokenProvider`, `envConfig`) still take precedence.
+     */
+    readonly serverInstanceConfig?: Maybe<NestServerInstanceConfig<any>>;
     /**
      * Whether or not to inject the env service provider (and serverEnvTokenProvider()) by default.
      *
      * If false will affect the default envConfig value.
      */
-    injectServerEnvServiceProvider?: boolean;
+    readonly injectServerEnvServiceProvider?: boolean;
     /**
-     * (Optional) ServerEnvironmentServiceConfig. Overrides the default which sets production=false.
+     * (Optional) FirebaseServerEnvironmentConfig. Overrides the default which sets production=false.
      *
      * If injectFirebaseServerEnvServiceProvider is false then this requires a value to be provided in order to be injected.
      */
-    envConfig?: ServerEnvironmentConfig;
+    readonly envConfig?: FirebaseServerEnvironmentConfig;
     /**
      * Whether or not to inject the firebase server provider (firebaseServerAppTokenProvider()).
      *
      * This makes FIREBASE_APP_TOKEN available globally and provides the app configured for this test.
      */
-    injectFirebaseServerAppTokenProvider?: boolean;
+    readonly injectFirebaseServerAppTokenProvider?: boolean;
     /**
      * Default storage bucket to use for tests.
      */
-    defaultStorageBucket?: StorageBucketId;
+    readonly defaultStorageBucket?: StorageBucketId;
     /**
      * Whether or not to force using the storage bucket.
      */
-    forceStorageBucket?: boolean;
+    readonly forceStorageBucket?: boolean;
     /**
      * Optional providers to pass to the TestingModule initialization.
      */
-    makeProviders?: (instance: PI) => Provider<any>[];
+    readonly makeProviders?: (instance: PI) => Provider<any>[];
     /**
      * Creates a new instance.
      */
-    makeInstance?: (instance: PI, nest: TestingModule) => I;
+    readonly makeInstance?: (instance: PI, nest: TestingModule) => I;
     /**
      * Optional function to initialize the instance.
      */
-    initInstance?: (instance: I) => Promise<void>;
+    readonly initInstance?: (instance: I) => Promise<void>;
 }
+/**
+ * Factory type that produces a {@link FirebaseAdminNestTestContextFixture} for each test suite.
+ * Pass a {@link BuildTestsWithContextFunction} to register tests that run against the fixture.
+ */
 export type FirebaseAdminNestTestContextFactory<PI extends FirebaseAdminTestContextInstance = FirebaseAdminTestContextInstance, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends FirebaseAdminNestTestContextInstance<PI> = FirebaseAdminNestTestContextInstance<PI>, C extends FirebaseAdminNestTestContextFixture<PI, PF, I> = FirebaseAdminNestTestContextFixture<PI, PF, I>> = TestContextFactory<C>;
+/**
+ * Composes a NestJS test context on top of an existing parent test context factory.
+ *
+ * Use this when the parent context is _not_ the default {@link firebaseAdminTestContextFactory} --
+ * for example, when layering NestJS onto a custom Firebase Admin function context.
+ * For the common case, prefer {@link firebaseAdminNestContextFactory}.
+ *
+ * @param config - NestJS module, provider, and fixture configuration.
+ * @param factory - The parent context factory that provides the Firebase Admin instance.
+ * @returns A new factory that nests the NestJS context inside the parent.
+ */
 export declare function firebaseAdminNestContextFixture<PI extends FirebaseAdminTestContextInstance = FirebaseAdminTestContextInstance, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends FirebaseAdminNestTestContextInstance<PI> = FirebaseAdminNestTestContextInstance<PI>, C extends FirebaseAdminNestTestContextFixture<PI, PF, I> = FirebaseAdminNestTestContextFixture<PI, PF, I>>(config: FirebaseAdminNestTestConfig<PI, PF, I, C>, factory: TestContextFactory<PF>): FirebaseAdminNestTestContextFactory<PI, PF, I, C>;
-export declare class FirebaseAdminNestRootModule {
-}
+/** @deprecated Use `FirebaseNestServerRootModule` from `@dereekb/firebase-server` instead. */
+export { FirebaseNestServerRootModule as FirebaseAdminNestRootModule } from '@dereekb/firebase-server';
+/**
+ * Wires up a NestJS {@link TestingModule} inside an already-created parent fixture.
+ *
+ * This is the core integration point: it builds the root module via {@link buildNestServerRootModule},
+ * compiles the testing module, creates the instance, and registers Jest lifecycle hooks
+ * (via {@link useTestContextFixture}) to tear down the module after tests complete.
+ *
+ * Typically called indirectly through {@link firebaseAdminNestContextFixture} or
+ * {@link firebaseAdminNestContextFactory}. Call directly only when composing custom fixture hierarchies.
+ *
+ * @param config - NestJS module, provider, and fixture configuration.
+ * @param f - The parent fixture that is already set up.
+ * @param buildTests - Callback that receives the child fixture and registers test cases.
+ */
 export declare function firebaseAdminNestContextWithFixture<PI extends FirebaseAdminTestContextInstance = FirebaseAdminTestContextInstance, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends FirebaseAdminNestTestContextInstance<PI> = FirebaseAdminNestTestContextInstance<PI>, C extends FirebaseAdminNestTestContextFixture<PI, PF, I> = FirebaseAdminNestTestContextFixture<PI, PF, I>>(config: FirebaseAdminNestTestConfig<PI, PF, I, C>, f: PF, buildTests: BuildTestsWithContextFunction<C>): void;
+/**
+ * Convenience factory that layers a NestJS test context on top of the default
+ * {@link firebaseAdminTestContextFactory}. This is the simplest way to get a
+ * fully configured Firebase Admin + NestJS test context.
+ *
+ * @example
+ * ```ts
+ * const f = firebaseAdminNestContextFactory({
+ *   nestModules: [MyAppModule]
+ * });
+ *
+ * f((c) => {
+ *   it('should resolve service', () => {
+ *     const svc = c.get(MyService);
+ *     expect(svc).toBeDefined();
+ *   });
+ * });
+ * ```
+ */
 export declare function firebaseAdminNestContextFactory<I extends FirebaseAdminNestTestContextInstance<FirebaseAdminTestContextInstance> = FirebaseAdminNestTestContextInstance<FirebaseAdminTestContextInstance>>(config: FirebaseAdminNestTestConfig<FirebaseAdminTestContextInstance, TestContextFixture<FirebaseAdminTestContextInstance>, I>): FirebaseAdminNestTestContextFactory<FirebaseAdminTestContextInstance, TestContextFixture<FirebaseAdminTestContextInstance>, I>;

package/test/src/lib/firebase/firebase.admin.nest.function.callable.context.d.ts

@@ -1,23 +1,67 @@
 import { type FirebaseAdminFunctionNestTestContext, type WrapCallableRequestForNestTestsInput } from './firebase.admin.nest.function';
 import { type WrappedCallableRequest } from './firebase.function';
+/**
+ * Base configuration shared by both single and multiple callable request test builders.
+ * Provides the {@link FirebaseAdminFunctionNestTestContext} that supplies NestJS and
+ * Cloud Function wrapping capabilities.
+ */
 export interface CallableRequestTestBaseConfig {
+    /** The test context fixture providing NestJS module and function wrapping access. */
     readonly f: FirebaseAdminFunctionNestTestContext;
 }
+/**
+ * Configuration for testing a single callable request function.
+ * The `fn` factory is wrapped and provided to the test callback as a {@link WrappedCallableRequest}.
+ */
 export interface CallableRequestTestSingleConfig<I, O = unknown> extends CallableRequestTestBaseConfig {
+    /** The callable HTTP function factory to wrap for testing. */
     readonly fn: WrapCallableRequestForNestTestsInput<I, O>;
 }
+/**
+ * Test callback for a single callable request. Receives the wrapped callable function
+ * and should register test cases (e.g., `it(...)` blocks) inside the callback body.
+ */
 export type CallableRequestTestSingleFunction<I, O = unknown> = (fn: WrappedCallableRequest<I, O>) => void;
+/**
+ * Map of named callable request function factories.
+ *
+ * Each key becomes a fixture property (with a {@link CallableRequestTestMultipleFixtureSuffix} suffix)
+ * containing the corresponding {@link WrappedCallableRequest}.
+ */
 export type CallableRequestTestConfigMapObject = {
     [key: string]: WrapCallableRequestForNestTestsInput<any>;
 };
+/**
+ * Configuration for testing multiple callable request functions simultaneously.
+ * Each entry in `fns` is independently wrapped and exposed via a {@link CallableRequestTestMultipleFixture}.
+ */
 export interface CallableRequestTestMultipleConfig<I, T extends CallableRequestTestConfigMapObject> extends CallableRequestTestBaseConfig {
+    /** Map of named callable function factories to wrap for testing. */
     fns: T;
 }
+/**
+ * Suffix appended to each key in a {@link CallableRequestTestConfigMapObject} when building
+ * the {@link CallableRequestTestMultipleFixture}. For example, a key `"createUser"` produces
+ * a fixture property named `"createUserWrappedFn"`.
+ */
 export declare const CallableRequestTestMultipleFixtureSuffix = "WrappedFn";
+/**
+ * Mapped type that transforms a {@link CallableRequestTestConfigMapObject} into an object
+ * whose keys are the original keys suffixed with {@link CallableRequestTestMultipleFixtureSuffix}
+ * and whose values are the corresponding {@link WrappedCallableRequest} instances.
+ */
 export type CallableRequestTestMultipleFixture<T extends CallableRequestTestConfigMapObject> = {
     [K in keyof T as K extends string ? `${K}${typeof CallableRequestTestMultipleFixtureSuffix}` : never]: T[K] extends WrapCallableRequestForNestTestsInput<infer I, infer O> ? WrappedCallableRequest<I, O> : never;
 };
+/**
+ * Test callback for multiple callable requests. Receives a {@link CallableRequestTestMultipleFixture}
+ * containing all wrapped functions, keyed by their suffixed names.
+ */
 export type CallableRequestTestMultipleFunction<T extends CallableRequestTestConfigMapObject> = (fn: CallableRequestTestMultipleFixture<T>) => void;
+/**
+ * Type guard that distinguishes a {@link CallableRequestTestSingleConfig} from a
+ * {@link CallableRequestTestMultipleConfig} by checking for the presence of the `fn` property.
+ */
 export declare function isCallableRequestTestSingleConfig<I, T extends CallableRequestTestConfigMapObject>(config: CallableRequestTestSingleConfig<I> | CallableRequestTestMultipleConfig<I, T>): config is CallableRequestTestSingleConfig<I>;
 /**
  * Used to provide a test builder that exposes a WrappedCallableRequest using the input configuration.

package/test/src/lib/firebase/firebase.admin.nest.function.cloud.context.d.ts

@@ -1,23 +1,64 @@
 import { type FirebaseAdminFunctionNestTestContext, type WrapCloudFunctionForNestTestsInput } from './firebase.admin.nest.function';
 import { type WrappedCloudFunction } from './firebase.function';
+/**
+ * Alias for {@link WrappedCloudFunction} used within cloud function test builders.
+ * Provides a semantic name specific to the test context.
+ */
 export type CloudFunctionTestWrappedCloudFunction<I extends object> = WrappedCloudFunction<I>;
+/**
+ * Base configuration shared by both single and multiple cloud function test builders.
+ * Provides the {@link FirebaseAdminFunctionNestTestContext} that supplies NestJS and
+ * Cloud Function wrapping capabilities.
+ */
 export interface CloudFunctionTestBaseConfig {
+    /** The test context fixture providing NestJS module and function wrapping access. */
     f: FirebaseAdminFunctionNestTestContext;
 }
+/**
+ * Configuration for testing a single cloud function (v1 schedule, blocking, or cloud event).
+ * The `fn` factory is wrapped and provided to the test callback as a {@link WrappedCloudFunction}.
+ */
 export interface CloudFunctionTestSingleConfig<I extends object> extends CloudFunctionTestBaseConfig {
+    /** The cloud function factory to wrap for testing. */
     fn: WrapCloudFunctionForNestTestsInput<I>;
 }
+/**
+ * Test callback for a single cloud function. Receives the wrapped function and should
+ * register test cases (e.g., `it(...)` blocks) inside the callback body.
+ */
 export type CloudFunctionTestSingleFunction<I extends object> = (fn: WrappedCloudFunction<I>) => void;
+/**
+ * Map of named cloud function factories. Each key becomes a fixture property
+ * (suffixed with `"CloudFn"`) containing the corresponding {@link WrappedCloudFunction}.
+ */
 export type CloudFunctionTestConfigMapObject = {
     [key: string]: WrapCloudFunctionForNestTestsInput<any>;
 };
+/**
+ * Configuration for testing multiple cloud functions simultaneously.
+ * Each entry in `fns` is independently wrapped and exposed via a {@link CloudFunctionTestMultipleFixture}.
+ */
 export interface CloudFunctionTestMultipleConfig<I extends object, T extends CloudFunctionTestConfigMapObject> extends CloudFunctionTestBaseConfig {
+    /** Map of named cloud function factories to wrap for testing. */
     fns: T;
 }
+/**
+ * Mapped type that transforms a {@link CloudFunctionTestConfigMapObject} into an object
+ * whose keys are the original keys suffixed with `"CloudFn"` and whose values are the
+ * corresponding {@link WrappedCloudFunction} instances.
+ */
 export type CloudFunctionTestMultipleFixture<T extends CloudFunctionTestConfigMapObject> = {
     [K in keyof T as K extends string ? `${K}CloudFn` : never]: T[K] extends WrapCloudFunctionForNestTestsInput<infer I> ? WrappedCloudFunction<I> : never;
 };
+/**
+ * Test callback for multiple cloud functions. Receives a {@link CloudFunctionTestMultipleFixture}
+ * containing all wrapped functions, keyed by their suffixed names.
+ */
 export type CloudFunctionTestMultipleFunction<T extends CloudFunctionTestConfigMapObject> = (fn: CloudFunctionTestMultipleFixture<T>) => void;
+/**
+ * Type guard that distinguishes a {@link CloudFunctionTestSingleConfig} from a
+ * {@link CloudFunctionTestMultipleConfig} by checking for the presence of the `fn` property.
+ */
 export declare function isCloudFunctionTestSingleConfig<I extends object, T extends CloudFunctionTestConfigMapObject>(config: CloudFunctionTestSingleConfig<I> | CloudFunctionTestMultipleConfig<I, T>): config is CloudFunctionTestSingleConfig<I>;
 /**
  * Used to provide a test builder that exposes a WrappedCloudFunction using the input configuration.

package/test/src/lib/firebase/firebase.admin.nest.function.d.ts

@@ -6,12 +6,57 @@ import { type NestApplicationBlockingFunctionFactory, type NestApplicationCallab
 import { type FirebaseAdminCloudFunctionWrapper, type FirebaseAdminCloudFunctionWrapperSource, type WrappedCloudFunctionV1, type WrappedCallableRequest } from './firebase.function';
 import { type CloudEvent } from 'firebase-functions/v2';
 type WrapCloudFunctionForNestTestsInputNonEventTypes = NestApplicationScheduleFunctionFactory | NestApplicationBlockingFunctionFactory<any, unknown>;
+/**
+ * Input type for {@link wrapCloudFunctionForNestTestsGetter} that resolves to the appropriate
+ * NestJS application function factory based on the event type `I`.
+ *
+ * When `I` is a {@link CloudEvent}, cloud event factories are also accepted; otherwise only
+ * schedule and blocking function factories are valid.
+ */
 export type WrapCloudFunctionForNestTestsInput<I extends object> = I extends CloudEvent<any> ? NestApplicationCloudEventFunctionFactory<I> | WrapCloudFunctionForNestTestsInputNonEventTypes : WrapCloudFunctionForNestTestsInputNonEventTypes;
+/**
+ * Creates a lazy getter that wraps a NestJS-hosted Cloud Function (v1) for testing.
+ *
+ * The returned getter defers wrapping until first invocation, so the NestJS application
+ * is resolved at call time rather than at setup time.
+ *
+ * @param wrapper - The test context providing the function wrapper and NestJS app promise.
+ * @param fn - The NestJS application function factory to wrap.
+ * @returns A getter that produces a {@link WrappedCloudFunctionV1} on each call.
+ */
 export declare function wrapCloudFunctionForNestTestsGetter<I extends object>(wrapper: FirebaseAdminFunctionNestTestContext, fn: WrapCloudFunctionForNestTestsInput<I>): Getter<WrappedCloudFunctionV1<I>>;
+/**
+ * Input type for {@link wrapCallableRequestForNestTestsGetter}. Accepts a NestJS application
+ * callable HTTP function factory that produces a gen-2 callable function from a NestJS app promise.
+ */
 export type WrapCallableRequestForNestTestsInput<I, O = unknown> = NestApplicationCallableHttpFunctionFactory<I, O>;
+/**
+ * Creates a lazy getter that wraps a NestJS-hosted callable request function for testing.
+ *
+ * Similar to {@link wrapCloudFunctionForNestTestsGetter} but targets gen-2 callable HTTP
+ * functions. The getter defers resolution so the NestJS app is available at call time.
+ *
+ * @param wrapper - The test context providing the function wrapper and NestJS app promise.
+ * @param fn - The NestJS callable HTTP function factory to wrap.
+ * @returns A getter that produces a {@link WrappedCallableRequest} on each call.
+ */
 export declare function wrapCallableRequestForNestTestsGetter<I, O = unknown>(wrapper: FirebaseAdminFunctionNestTestContext, fn: WrapCallableRequestForNestTestsInput<I, O>): Getter<WrappedCallableRequest<I, O>>;
+/**
+ * Combined test context that merges {@link FirebaseAdminNestTestContext} (NestJS module access)
+ * with {@link FirebaseAdminCloudFunctionWrapperSource} (Cloud Function wrapping).
+ *
+ * Implementations provide both the NestJS {@link TestingModule} and the `fnWrapper` needed
+ * to wrap and invoke Cloud Functions within integration tests.
+ */
 export interface FirebaseAdminFunctionNestTestContext extends FirebaseAdminNestTestContext, FirebaseAdminCloudFunctionWrapperSource {
 }
+/**
+ * Fixture that combines NestJS testing module access with Cloud Function wrapping capabilities.
+ *
+ * Extends {@link FirebaseAdminNestTestContextFixture} and adds convenience methods for wrapping
+ * both v1 cloud functions and gen-2 callable requests directly from the fixture, delegating
+ * to the standalone {@link wrapCloudFunctionForNestTestsGetter} and {@link wrapCallableRequestForNestTestsGetter} helpers.
+ */
 export declare class FirebaseAdminFunctionNestTestContextFixture<PI extends FirebaseAdminFunctionTestContextInstance = FirebaseAdminFunctionTestContextInstance, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends FirebaseAdminFunctionNestTestContextInstance<PI> = FirebaseAdminFunctionNestTestContextInstance<PI>> extends FirebaseAdminNestTestContextFixture<PI, PF, I> implements FirebaseAdminFunctionNestTestContext {
     wrapCloudFunctionForNestTests<I extends object>(fn: WrapCloudFunctionForNestTestsInput<I>): WrappedCloudFunctionV1<I>;
     wrapCloudFunctionForNestTestsGetter<I extends object>(fn: WrapCloudFunctionForNestTestsInput<I>): Getter<WrappedCloudFunctionV1<I>>;
@@ -19,14 +64,67 @@ export declare class FirebaseAdminFunctionNestTestContextFixture<PI extends Fire
     wrapCallableRequestForNestTestsGetter<I, O = unknown>(fn: WrapCallableRequestForNestTestsInput<I, O>): Getter<WrappedCallableRequest<I, O>>;
     get fnWrapper(): FirebaseAdminCloudFunctionWrapper;
 }
+/**
+ * Concrete instance that extends {@link FirebaseAdminNestTestContextInstance} with the
+ * {@link FirebaseAdminCloudFunctionWrapperSource} interface, delegating `fnWrapper` to
+ * the parent {@link FirebaseAdminFunctionTestContextInstance}.
+ */
 export declare class FirebaseAdminFunctionNestTestContextInstance<PI extends FirebaseAdminFunctionTestContextInstance = FirebaseAdminFunctionTestContextInstance> extends FirebaseAdminNestTestContextInstance<PI> implements FirebaseAdminFunctionNestTestContext {
     get fnWrapper(): FirebaseAdminCloudFunctionWrapper;
 }
+/**
+ * Configuration type for NestJS + Cloud Function test contexts.
+ * Alias for {@link FirebaseAdminNestTestConfig} parameterized with function-aware types.
+ */
 export type FirebaseAdminFunctionNestTestConfig<PI extends FirebaseAdminFunctionTestContextInstance = FirebaseAdminFunctionTestContextInstance, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends FirebaseAdminFunctionNestTestContextInstance<PI> = FirebaseAdminFunctionNestTestContextInstance<PI>, C extends FirebaseAdminFunctionNestTestContextFixture<PI, PF, I> = FirebaseAdminFunctionNestTestContextFixture<PI, PF, I>> = FirebaseAdminNestTestConfig<PI, PF, I, C>;
+/**
+ * Factory type that produces a {@link FirebaseAdminFunctionNestTestContextFixture} for each test suite.
+ */
 export type FirebaseAdminFunctionNestTestContextFactory<PI extends FirebaseAdminFunctionTestContextInstance = FirebaseAdminFunctionTestContextInstance, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends FirebaseAdminFunctionNestTestContextInstance<PI> = FirebaseAdminFunctionNestTestContextInstance<PI>, C extends FirebaseAdminFunctionNestTestContextFixture<PI, PF, I> = FirebaseAdminFunctionNestTestContextFixture<PI, PF, I>> = TestContextFactory<C>;
+/**
+ * Composes a NestJS + Cloud Function test context on top of an existing parent factory.
+ *
+ * Use when the parent factory is custom; for the common case with default parent, prefer
+ * {@link firebaseAdminFunctionNestContextFactory}.
+ *
+ * @param config - NestJS module, provider, and fixture configuration.
+ * @param factory - The parent context factory providing the Firebase Admin function instance.
+ * @returns A new factory combining NestJS and Cloud Function wrapping capabilities.
+ */
 export declare function firebaseAdminFunctionNestContextFixture<PI extends FirebaseAdminFunctionTestContextInstance = FirebaseAdminFunctionTestContextInstance, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends FirebaseAdminFunctionNestTestContextInstance<PI> = FirebaseAdminFunctionNestTestContextInstance<PI>, C extends FirebaseAdminFunctionNestTestContextFixture<PI, PF, I> = FirebaseAdminFunctionNestTestContextFixture<PI, PF, I>>(config: FirebaseAdminFunctionNestTestConfig<PI, PF, I, C>, factory: TestContextFactory<PF>): FirebaseAdminFunctionNestTestContextFactory<PI, PF, I, C>;
+/**
+ * Empty NestJS module class used as a placeholder root module for function nest test contexts.
+ */
 export declare class FirebaseAdminFunctionNestRootModule {
 }
+/**
+ * Wires up a NestJS {@link TestingModule} with Cloud Function wrapping inside an existing parent fixture.
+ *
+ * Merges default `makeFixture` / `makeInstance` implementations that produce function-aware
+ * fixture and instance classes, then delegates to {@link firebaseAdminNestContextWithFixture}.
+ *
+ * @param config - NestJS module, provider, and fixture configuration.
+ * @param f - The parent fixture that is already set up.
+ * @param buildTests - Callback that receives the child fixture and registers test cases.
+ */
 export declare function firebaseAdminFunctionNestContextWithFixture<PI extends FirebaseAdminFunctionTestContextInstance = FirebaseAdminFunctionTestContextInstance, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends FirebaseAdminFunctionNestTestContextInstance<PI> = FirebaseAdminFunctionNestTestContextInstance<PI>, C extends FirebaseAdminFunctionNestTestContextFixture<PI, PF, I> = FirebaseAdminFunctionNestTestContextFixture<PI, PF, I>>(config: FirebaseAdminFunctionNestTestConfig<PI, PF, I, C>, f: PF, buildTests: BuildTestsWithContextFunction<C>): void;
+/**
+ * Convenience factory that layers a NestJS + Cloud Function test context on top of the
+ * default {@link firebaseAdminFunctionTestContextFactory}. This is the simplest entry point
+ * for tests that need both NestJS module access and Cloud Function wrapping.
+ *
+ * @example
+ * ```ts
+ * const f = firebaseAdminFunctionNestContextFactory({
+ *   nestModules: [MyAppModule]
+ * });
+ *
+ * f((c) => {
+ *   describeCallableRequestTest('myCallable', { f: c, fn: myCallableFactory }, (wrappedFn) => {
+ *     it('should succeed', async () => { ... });
+ *   });
+ * });
+ * ```
+ */
 export declare function firebaseAdminFunctionNestContextFactory<I extends FirebaseAdminFunctionNestTestContextInstance<FirebaseAdminFunctionTestContextInstance> = FirebaseAdminFunctionNestTestContextInstance<FirebaseAdminFunctionTestContextInstance>>(config: FirebaseAdminFunctionNestTestConfig<FirebaseAdminFunctionTestContextInstance, TestContextFixture<FirebaseAdminFunctionTestContextInstance>, I>): FirebaseAdminFunctionNestTestContextFactory<FirebaseAdminFunctionTestContextInstance, TestContextFixture<FirebaseAdminFunctionTestContextInstance>, I>;
 export {};

package/test/src/lib/firebase/firebase.admin.test.server.d.ts

@@ -1,3 +1,29 @@
 import { type TestFirestoreContextFixture, type TestFirestoreInstance } from '@dereekb/firebase/test';
+/**
+ * Initializes the Firebase Admin test environment with the default emulator ports
+ * used by the `@dereekb/firebase-server` test suite.
+ *
+ * This is a convenience wrapper around {@link initFirebaseAdminTestEnvironment} that
+ * pre-configures auth (9903), firestore (9904), and storage (9906) on `0.0.0.0`.
+ * Call this once at the top of each test file (or in a global setup) before any
+ * Firebase Admin SDK calls are made.
+ *
+ * @example
+ * ```ts
+ * beforeAll(() => {
+ *   initFirebaseServerAdminTestEnvironment();
+ * });
+ * ```
+ */
 export declare function initFirebaseServerAdminTestEnvironment(): void;
+/**
+ * Registers a smoke-test `describe` block that verifies basic Firestore connectivity
+ * against the emulator.
+ *
+ * Creates a {@link MockItemFirestoreCollection}, writes a document, and asserts it exists.
+ * Useful as a sanity check inside larger test suites to confirm the emulator is reachable
+ * and the fixture is wired up correctly.
+ *
+ * @param s - The firestore context fixture providing the active {@link TestFirestoreContext}.
+ */
 export declare function describeFirestoreTest(s: TestFirestoreContextFixture<TestFirestoreInstance>): void;

package/test/src/lib/firebase/firebase.d.ts

@@ -1,21 +1,76 @@
 /**
- * Host url:port combo.
+ * A `host:port` string used to connect to a Firebase emulator.
  *
- * I.E. localhost:8080
+ * @example
+ * ```ts
+ * const host: FirebaseAdminTestEnvironmentHost = 'localhost:8080';
+ * ```
  */
 export type FirebaseAdminTestEnvironmentHost = string;
+/**
+ * Configuration for Firebase emulator host addresses.
+ *
+ * Each emulator can be set to a {@link FirebaseAdminTestEnvironmentHost} string to enable it,
+ * or `null` to skip that emulator. If the firestore emulator is non-null and another emulator
+ * is left undefined (not null), {@link initFirebaseAdminTestEnvironment} will throw to prevent
+ * accidental connections to production services.
+ */
 export interface FirebaseAdminTestEnvironmentEmulatorsConfig {
     auth: FirebaseAdminTestEnvironmentHost | null;
     storage: FirebaseAdminTestEnvironmentHost | null;
     firestore: FirebaseAdminTestEnvironmentHost | null;
 }
+/**
+ * Top-level configuration for initializing the Firebase Admin test environment.
+ *
+ * Passed to {@link initFirebaseAdminTestEnvironment} to configure which emulators the test suite connects to.
+ */
 export interface FirebaseAdminTestEnvironmentConfig {
     emulators: FirebaseAdminTestEnvironmentEmulatorsConfig;
 }
+/**
+ * Returns whether {@link initFirebaseAdminTestEnvironment} has already been called.
+ *
+ * Useful for guarding against double-initialization or verifying that setup has completed
+ * before creating test contexts.
+ */
 export declare function isAdminEnvironmentInitialized(): boolean;
+/**
+ * Generates a unique GCloud project ID based on the current timestamp.
+ *
+ * The generated ID has the format `firebase-test-<epoch-millis>`, ensuring each test run
+ * operates against an isolated project namespace in the emulators.
+ *
+ * @example
+ * ```ts
+ * const projectId = generateNewProjectId();
+ * // => 'firebase-test-1710000000000'
+ * ```
+ */
 export declare function generateNewProjectId(): string;
+/**
+ * Generates a new project ID and writes it to the `GCLOUD_PROJECT` and `GCLOUD_TEST_PROJECT`
+ * environment variables. Also updates `FIREBASE_CONFIG` via {@link applyFirebaseGCloudTestProjectIdToFirebaseConfigEnv}.
+ *
+ * This ensures all Firebase Admin SDK calls within the current process use an isolated project,
+ * preventing cross-test data contamination when running against emulators.
+ *
+ * @returns The newly generated project ID.
+ */
 export declare function rollNewGCloudProjectEnvironmentVariable(): string;
+/**
+ * Reads the current `GCLOUD_PROJECT` environment variable.
+ *
+ * This is the "active" project ID that the Firebase Admin SDK resolves at runtime.
+ */
 export declare function getGCloudProjectId(): string | undefined;
+/**
+ * Reads the current `GCLOUD_TEST_PROJECT` environment variable.
+ *
+ * This holds the canonical test project ID set during {@link rollNewGCloudProjectEnvironmentVariable},
+ * and is used by {@link applyFirebaseGCloudTestProjectIdToFirebaseConfigEnv} as the source of truth
+ * when re-applying the project ID after external libraries overwrite `FIREBASE_CONFIG`.
+ */
 export declare function getGCloudTestProjectId(): string | undefined;
 /**
  * Applies the current GCLOUD_PROJECT to FIREBASE_CONFIG.