@dereekb/firebase-server 13.2.2 → 13.3.0

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

@@ -6,10 +6,19 @@ import { type FeaturesList } from 'firebase-functions-test/lib/features';
 import { type BlockingFunctionMaybeWithHandler, type CallableHttpFunction } from '@dereekb/firebase-server';
 /**
  * Type fix used for compatability with firebase-functions/v2 the CloudFunction types in unions.
+ *
+ * The v1 `CloudFunction` type includes a `__trigger` property whose shape conflicts with the v2
+ * `CloudFunction` type, making them impossible to use in the same union. This type omits the
+ * conflicting property and replaces it with an optional `any`, allowing v1 functions to participate
+ * in shared union types alongside v2 functions.
  */
 export type CloudFunctionV1TypeFix<T> = Omit<CloudFunctionV1Input<T>, '__trigger'> & {
     __trigger?: any;
 };
+/**
+ * Alias for {@link CloudFunctionV1TypeFix} representing a gen 1 Firebase Cloud Function
+ * with the union-compatibility fix applied.
+ */
 export type CloudFunctionV1<T> = CloudFunctionV1TypeFix<T>;
 /**
  * @deprecated deprecated gen 1 firebase function type
@@ -27,7 +36,19 @@ export type WrapCloudFunctionV1Input<T> = CloudFunctionV1<T>;
  * Wrapped callable function that only takes in data and options that are used to simulate a Firebase request, then returns the result.
  */
 export type WrappedCallableRequest<I, O = unknown> = (data: I, options: CallableContextOptions) => PromiseOrValue<O>;
+/**
+ * Extracts the input (params) type from a {@link WrappedCallableRequest}.
+ *
+ * Useful when you need to derive the request payload type from an already-wrapped callable
+ * without importing the original input type separately.
+ */
 export type WrappedCallableRequestParams<W extends WrappedCallableRequest<any, any>> = W extends WrappedCallableRequest<infer I> ? I : unknown | undefined | void;
+/**
+ * Extracts the output (return) type from a {@link WrappedCallableRequest}.
+ *
+ * Useful when you need to derive the response type from an already-wrapped callable
+ * without importing the original output type separately.
+ */
 export type WrappedCallableRequestOutput<W extends WrappedCallableRequest<any, any>> = W extends WrappedCallableRequest<infer _, infer O> ? O : unknown;
 /**
  * WrapCallableRequestV2 input.
@@ -43,13 +64,52 @@ export type WrapCallableRequest = <I, O>(callable: WrapCallableRequestInput<I, O
 export type WrapCloudFunctionV2 = <T extends CloudEvent<any>>(cloudFunction: CloudFunctionV2<T>) => WrappedV2Function<T>;
 export type WrapCloudFunctionV2Input<E extends CloudEvent<unknown>> = CloudFunctionV2<E>;
 export type WrappedCloudFunctionV2<E extends CloudEvent<unknown>> = WrappedV2Function<E>;
+/**
+ * A wrapped gen 2 blocking function that accepts an event input and returns a result.
+ *
+ * This is the test-time representation of a blocking function that includes a handler
+ * (e.g., `beforeUserCreated` with a handler callback).
+ */
 export type WrappedBlockingFunctionWithHandler<E extends object, O> = (input: E) => Promise<O>;
+/**
+ * A wrapped gen 2 blocking function with no handler — invocation simply triggers side effects.
+ *
+ * This is the test-time representation of a blocking function registered without a handler callback.
+ */
 export type WrappedBlockingFunction = () => Promise<void>;
+/**
+ * Wrapping function for a {@link BlockingFunctionMaybeWithHandler} that has a handler.
+ *
+ * Infers the event and output types from the blocking function and returns a
+ * correspondingly typed {@link WrappedBlockingFunctionWithHandler}.
+ */
 export type WrapBlockingFunctionWithHandlerFunction = <T extends BlockingFunctionMaybeWithHandler<any, any>>(blockingFunction: T) => T extends BlockingFunctionMaybeWithHandler<infer E, infer O> ? WrappedBlockingFunctionWithHandler<E, O> : never;
+/**
+ * Wrapping function for a gen 1 {@link BlockingFunction} (no handler).
+ *
+ * Returns a {@link WrappedBlockingFunction} that can be invoked in tests.
+ */
 export type WrapBlockingFunctionWithoutHandlerFunction = (blockingFunction: BlockingFunction) => WrappedBlockingFunction;
+/**
+ * Combined wrapping function interface for blocking functions.
+ *
+ * Overloaded to handle both blocking functions with handlers
+ * ({@link WrapBlockingFunctionWithHandlerFunction}) and without
+ * ({@link WrapBlockingFunctionWithoutHandlerFunction}), allowing a single
+ * `wrapBlockingFunction` call to wrap either variant.
+ */
 export interface WrapBlockingFunction extends WrapBlockingFunctionWithHandlerFunction, WrapBlockingFunctionWithoutHandlerFunction {
 }
+/**
+ * Union of all possible wrapped gen 2 function types for a given input.
+ *
+ * When `I` extends `CloudEvent`, the result may be a wrapped cloud function or a wrapped
+ * blocking function (with or without handler). Otherwise it is restricted to blocking function variants.
+ */
 export type WrappedGen2CloudOrBlockingFunction<I extends object> = I extends CloudEvent<unknown> ? WrappedCloudFunctionV2<I> | WrappedBlockingFunctionWithHandler<I, unknown> | WrappedBlockingFunction : WrappedBlockingFunction | WrappedBlockingFunctionWithHandler<I, unknown>;
+/**
+ * Union of wrapping function types for gen 2 cloud functions and blocking functions.
+ */
 export type WrapGen2CloudOrBlockingFunction = WrapCloudFunctionV2 | WrapBlockingFunction;
 /**
  * A common interface for a all known types of wrapped cloud functions that excludes WrappedCallableRequest.
@@ -57,7 +117,19 @@ export type WrapGen2CloudOrBlockingFunction = WrapCloudFunctionV2 | WrapBlocking
  * All of these functions are wrapped by FirebaseAdminCloudFunctionWrapper.
  */
 export type WrappedCloudFunction<I extends object, O = unknown> = (input: I, context?: CallableContextOptions) => Promise<O>;
+/**
+ * Unified wrapping function type that can wrap any generation of cloud function.
+ *
+ * Combines {@link WrapGen2CloudOrBlockingFunction} (gen 2 / blocking) with
+ * {@link WrapCloudFunctionV1} (gen 1) into a single callable type.
+ */
 export type WrapCloudFunction = WrapGen2CloudOrBlockingFunction & WrapCloudFunctionV1;
+/**
+ * Provides access to a {@link FirebaseAdminCloudFunctionWrapper} via the `fnWrapper` property.
+ *
+ * Implemented by test fixture classes that need to expose cloud function wrapping capabilities
+ * to their consumers.
+ */
 export interface FirebaseAdminCloudFunctionWrapperSource {
     readonly fnWrapper: FirebaseAdminCloudFunctionWrapper;
 }
@@ -87,10 +159,76 @@ export interface FirebaseAdminCloudFunctionWrapper {
      */
     readonly wrapCloudFunction: WrapCloudFunction;
 }
+/**
+ * Creates a {@link FirebaseAdminCloudFunctionWrapper} from a `firebase-functions-test` {@link FeaturesList} instance.
+ *
+ * The returned wrapper provides methods to wrap gen 1 cloud functions, gen 2 cloud functions,
+ * callable requests, and blocking functions for use in integration tests. Each method delegates
+ * to the underlying `FeaturesList.wrap()` with appropriate type coercion.
+ *
+ * @example
+ * ```ts
+ * const testEnv = functionsTest();
+ * const wrapper = firebaseAdminCloudFunctionWrapper(testEnv);
+ * const wrapped = wrapper.wrapCallableRequest(myCallable);
+ * const result = await wrapped({ foo: 'bar' }, { auth: { uid: 'test-user' } });
+ * ```
+ */
 export declare function firebaseAdminCloudFunctionWrapper(instance: FeaturesList): FirebaseAdminCloudFunctionWrapper;
+/**
+ * Creates a lazy getter that wraps a gen 1 cloud function for testing each time it is called.
+ *
+ * The returned getter re-wraps on every invocation, so it always reflects the latest function
+ * reference from the provided getter — useful when the function under test is re-created between tests.
+ *
+ * @example
+ * ```ts
+ * const getWrapped = wrapCloudFunctionV1ForTests(wrapper, () => myV1Function);
+ * const result = await getWrapped()({ /* event data *\/ });
+ * ```
+ *
+ * @deprecated Prefer gen 2 functions and {@link wrapCloudFunctionV2ForTests} or {@link wrapCloudFunctionTests}.
+ */
 export declare function wrapCloudFunctionV1ForTests<I, T extends WrapCloudFunctionV1Input<I> = WrapCloudFunctionV1Input<I>>(wrapper: FirebaseAdminCloudFunctionWrapper, getter: Getter<T>): Getter<WrappedCloudFunctionV1<I>>;
+/**
+ * Creates a lazy getter that wraps a gen 2 cloud function for testing each time it is called.
+ *
+ * Re-wraps on every invocation so it always reflects the latest function reference,
+ * which is important when the function under test is re-created between test cases.
+ *
+ * @example
+ * ```ts
+ * const getWrapped = wrapCloudFunctionV2ForTests(wrapper, () => myV2CloudFunction);
+ * const result = await getWrapped()({ data: payload });
+ * ```
+ */
 export declare function wrapCloudFunctionV2ForTests<E extends CloudEvent<unknown>, T extends WrapCloudFunctionV2Input<E> = WrapCloudFunctionV2Input<E>>(wrapper: FirebaseAdminCloudFunctionWrapper, getter: Getter<T>): Getter<WrappedCloudFunctionV2<E>>;
+/**
+ * Creates a lazy getter that wraps any cloud function (gen 1 or gen 2) for testing using
+ * the unified {@link WrapCloudFunction} interface.
+ *
+ * This is the most general wrapper — use it when you do not need to distinguish between
+ * function generations in your test setup.
+ *
+ * @example
+ * ```ts
+ * const getWrapped = wrapCloudFunctionTests(wrapper, () => myFunction);
+ * const result = await getWrapped()(eventInput);
+ * ```
+ */
 export declare function wrapCloudFunctionTests<I extends object>(wrapper: FirebaseAdminCloudFunctionWrapper, getter: Getter<any>): Getter<WrappedCloudFunction<I>>;
+/**
+ * Creates a lazy getter that wraps a {@link CallableHttpFunction} for testing each time it is called.
+ *
+ * The wrapped callable accepts raw data and {@link CallableContextOptions} (e.g., auth context),
+ * simulating an incoming HTTP callable request without needing a running server.
+ *
+ * @example
+ * ```ts
+ * const getWrapped = wrapCallableRequestForTests(wrapper, () => myCallable);
+ * const result = await getWrapped()({ input: 'value' }, { auth: { uid: 'user-1' } });
+ * ```
+ */
 export declare function wrapCallableRequestForTests<I, O = unknown, T extends WrapCallableRequestInput<I, O> = WrapCallableRequestInput<I, O>>(wrapper: FirebaseAdminCloudFunctionWrapper, getter: Getter<T>): Getter<WrappedCallableRequest<I, O>>;
 /**
  * @deprecated use WrappedCallableRequest instead.

package/test/src/lib/firestore/firestore.admin.d.ts

@@ -1,5 +1,11 @@
 import { type TestContextFactory } from '@dereekb/util/test';
 import { type GoogleCloudTestFirestoreContextFixture } from './firestore';
+/**
+ * A {@link TestContextFactory} that produces {@link GoogleCloudTestFirestoreContextFixture} instances.
+ *
+ * Use this type when declaring or accepting pre-configured Firestore test factories
+ * (e.g., {@link adminFirestoreFactory}) that manage fixture lifecycle automatically.
+ */
 export type GoogleFirebaseFirestoreTestContextFactory = TestContextFactory<GoogleCloudTestFirestoreContextFixture>;
 /**
  * Default firestore admin factory.

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

@@ -1,14 +1,44 @@
 import { Firestore } from '@google-cloud/firestore';
 import { type TestFirestoreContext, TestFirestoreInstance, TestFirestoreContextFixture, type TestingFirestoreDrivers } from '@dereekb/firebase/test';
+/**
+ * Configuration for connecting to a Google Cloud Firestore emulator in tests.
+ */
 export interface GoogleCloudTestFirestoreConfig {
     host: string;
     port: number;
 }
+/**
+ * A {@link TestFirestoreContext} backed by `@google-cloud/firestore`.
+ *
+ * Alias provided for clarity when working within the Google Cloud test context builders.
+ */
 export type GoogleCloudTestFirestoreContext = TestFirestoreContext;
+/**
+ * Creates a {@link TestFirestoreContext} wired to a `@google-cloud/firestore` {@link Firestore} instance.
+ *
+ * The returned context has its `drivers` property set to the provided testing drivers,
+ * which enables test-specific behaviors (e.g., subcollection queries, batch operations)
+ * backed by the Google Cloud Firestore driver.
+ *
+ * @param drivers - Testing-aware Firestore driver set to attach to the context.
+ * @param firestore - The `@google-cloud/firestore` Firestore instance (typically pointed at an emulator).
+ */
 export declare function makeGoogleFirestoreContext(drivers: TestingFirestoreDrivers, firestore: Firestore): TestFirestoreContext;
+/**
+ * A {@link TestFirestoreInstance} backed by `@google-cloud/firestore`.
+ *
+ * Each instance is constructed with its own {@link Firestore} instance and testing drivers,
+ * providing an isolated Firestore context for a single test run.
+ */
 export declare class GoogleCloudTestFirestoreInstance extends TestFirestoreInstance {
     constructor(drivers: TestingFirestoreDrivers, firestore: Firestore);
 }
+/**
+ * Test context fixture for `@google-cloud/firestore`-backed Firestore tests.
+ *
+ * Manages the lifecycle of a {@link GoogleCloudTestFirestoreInstance}, setting it up
+ * before each test and tearing it down afterward via the {@link testContextBuilder} infrastructure.
+ */
 export declare class GoogleCloudTestFirestoreContextFixture extends TestFirestoreContextFixture<GoogleCloudTestFirestoreInstance> {
 }
 /**

package/test/src/lib/storage/storage.admin.d.ts

@@ -1,15 +1,21 @@
 import { type TestContextFactory } from '@dereekb/util/test';
 import { type GoogleCloudTestFirebaseStorageContextFixture } from './storage';
+/**
+ * A {@link TestContextFactory} that produces {@link GoogleCloudTestFirebaseStorageContextFixture} instances.
+ *
+ * Use this type when declaring or accepting pre-configured storage test factories
+ * (e.g., {@link adminFirebaseStorageFactory}) that manage fixture lifecycle automatically.
+ */
 export type GoogleFirebaseStorageTestContextFactory = TestContextFactory<GoogleCloudTestFirebaseStorageContextFixture>;
 /**
- * Default firestore admin factory.
+ * Default Firebase Storage admin factory.
  *
- * Host of localhost, port 9906
+ * Host of 0.0.0.0, port 9906
  */
 export declare const adminFirebaseStorageFactory: GoogleFirebaseStorageTestContextFactory;
 /**
  * Convenience mock instance for tests within an authorized context.
  *
- * Uses @google-cloud/firestore
+ * Uses @google-cloud/storage
  */
 export declare const dbxComponentsAdminTestWithMockItemStorage: TestContextFactory<import("@dereekb/firebase/test").MockItemStorageFixture>;

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

@@ -1,14 +1,44 @@
 import { type TestFirebaseStorageContext, TestFirebaseStorageInstance, TestFirebaseStorageContextFixture, type TestingFirebaseStorageDrivers } from '@dereekb/firebase/test';
 import { type FirebaseStorage } from '@dereekb/firebase';
+/**
+ * Configuration for connecting to a Google Cloud Storage emulator in tests.
+ */
 export interface GoogleCloudTestFirebaseStorageConfig {
     host: string;
     port: number;
 }
+/**
+ * A {@link TestFirebaseStorageContext} backed by `@google-cloud/storage`.
+ *
+ * Alias provided for clarity when working within the Google Cloud test context builders.
+ */
 export type GoogleCloudTestFirebaseStorageContext = TestFirebaseStorageContext;
+/**
+ * Creates a {@link TestFirebaseStorageContext} wired to a `@google-cloud/storage` instance.
+ *
+ * The returned context has its `drivers` property set to the provided testing drivers,
+ * enabling test-specific behaviors backed by the Google Cloud Storage driver.
+ *
+ * @param drivers - Testing-aware storage driver set to attach to the context.
+ * @param firebaseStorage - The `@google-cloud/storage` Storage instance (typically pointed at an emulator).
+ * @param defaultBucketId - Optional default bucket name; when provided, storage operations that omit a bucket will use this.
+ */
 export declare function makeGoogleFirebaseStorageContext(drivers: TestingFirebaseStorageDrivers, firebaseStorage: FirebaseStorage, defaultBucketId?: string): TestFirebaseStorageContext;
+/**
+ * A {@link TestFirebaseStorageInstance} backed by `@google-cloud/storage`.
+ *
+ * Each instance is constructed with its own Storage instance, testing drivers, and optional
+ * default bucket ID, providing an isolated storage context for a single test run.
+ */
 export declare class GoogleCloudTestFirebaseStorageInstance extends TestFirebaseStorageInstance {
     constructor(drivers: TestingFirebaseStorageDrivers, firebaseStorage: FirebaseStorage, defaultBucketId?: string);
 }
+/**
+ * Test context fixture for `@google-cloud/storage`-backed Firebase Storage tests.
+ *
+ * Manages the lifecycle of a {@link GoogleCloudTestFirebaseStorageInstance}, setting it up
+ * before each test and tearing it down afterward via the {@link testContextBuilder} infrastructure.
+ */
 export declare class GoogleCloudTestFirebaseStorageContextFixture extends TestFirebaseStorageContextFixture<GoogleCloudTestFirebaseStorageInstance> {
 }
 /**