@emmett-community/emmett-google-services-bootstrap 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,382 @@
+import { Application } from 'express';
+import { ImportedHandlerModules, OpenApiValidatorOptions, ApplicationOptions, startAPI } from '@emmett-community/emmett-expressjs-with-openapi';
+export { ApiE2ESpecification, ApiSpecification, ImportedHandlerModules, NoContent, OK, TestRequest, createFirebaseAuthSecurityHandlers, existingStream, expectNewEvents, expectResponse, on } from '@emmett-community/emmett-expressjs-with-openapi';
+import { MessageBus, EventSubscription, CommandProcessor, ScheduledMessageProcessor, EventStore } from '@event-driven-io/emmett';
+import { Firestore } from '@google-cloud/firestore';
+import { PubSub } from '@google-cloud/pubsub';
+import { Auth } from 'firebase-admin/auth';
+import { app } from 'firebase-admin';
+import { Database } from 'firebase-admin/database';
+import { PubSubMessageBusLifecycle, SubscriptionOptions } from '@emmett-community/emmett-google-pubsub';
+import { RealtimeDBInlineProjectionDefinition } from '@emmett-community/emmett-google-realtime-db';
+export { realtimeDBInlineProjection } from '@emmett-community/emmett-google-realtime-db';
+
+type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'silent';
+/**
+ * Canonical logger contract used across Emmett packages.
+ * Matches Pino style (context, message).
+ */
+interface Logger {
+    debug(context: Record<string, unknown>, message?: string): void;
+    info(context: Record<string, unknown>, message?: string): void;
+    warn(context: Record<string, unknown>, message?: string): void;
+    error(context: Record<string, unknown>, message?: string): void;
+}
+type ObservabilityConfig = {
+    logger?: Logger;
+    logLevel?: LogLevel;
+    environment?: string;
+    createLogger?: boolean;
+};
+type FirebaseConfig = {
+    projectId?: string;
+    databaseURL?: string;
+    firestoreEmulatorHost?: string;
+    databaseEmulatorHost?: string;
+};
+type PubSubConfig = {
+    projectId?: string;
+    emulatorHost?: string;
+    topicPrefix?: string;
+    subscriptionOptions?: SubscriptionOptions;
+    autoCreateResources?: boolean;
+    cleanupOnClose?: boolean;
+    closePubSubClient?: boolean;
+};
+type DependencyCheck = {
+    name: string;
+    check: () => Promise<void>;
+    successMessage?: string;
+    timeoutMs?: number;
+    required?: boolean;
+};
+type GracefulShutdownConfig = {
+    timeoutMs?: number;
+    exitOnComplete?: boolean;
+    exitFn?: (code: number) => void;
+};
+type MessageBusWithLifecycle = MessageBus & EventSubscription & CommandProcessor & ScheduledMessageProcessor & PubSubMessageBusLifecycle;
+interface FirebaseAdminLike {
+    initializeApp(options: {
+        projectId: string;
+        databaseURL?: string;
+    }, name?: string): app.App;
+    app?: () => app.App;
+    apps?: Array<app.App | null>;
+}
+type ServiceBootstrapOverrides = {
+    firebaseAdmin?: FirebaseAdminLike;
+    firestore?: Firestore;
+    database?: Database;
+    auth?: Auth;
+    pubsub?: PubSub;
+    eventStore?: EventStore;
+    messageBus?: MessageBusWithLifecycle;
+};
+/**
+ * Main configuration for ServiceBootstrap.
+ * Values can be provided explicitly or via environment variables.
+ */
+type ServiceBootstrapConfig = {
+    serviceName: string;
+    firebase?: FirebaseConfig;
+    pubsub?: PubSubConfig;
+    observability?: ObservabilityConfig;
+    projections?: RealtimeDBInlineProjectionDefinition[];
+    getCurrentTime?: () => Date;
+    dependencies?: DependencyCheck[];
+    includeDefaultDependencyChecks?: boolean;
+    autoStartMessageBus?: boolean;
+    shutdownOnDependencyFailure?: boolean;
+    shutdown?: GracefulShutdownConfig;
+    _testOverrides?: ServiceBootstrapOverrides;
+};
+type ResolvedFirebaseConfig = {
+    projectId: string;
+    databaseURL: string;
+    firestoreEmulatorHost?: string;
+    databaseEmulatorHost?: string;
+};
+type ResolvedPubSubConfig = {
+    projectId: string;
+    emulatorHost?: string;
+    topicPrefix: string;
+    subscriptionOptions?: SubscriptionOptions;
+    autoCreateResources: boolean;
+    cleanupOnClose: boolean;
+    closePubSubClient: boolean;
+};
+type ResolvedServiceBootstrapConfig = {
+    serviceName: string;
+    firebase: ResolvedFirebaseConfig;
+    pubsub: ResolvedPubSubConfig;
+    observability: ObservabilityConfig;
+    projections: RealtimeDBInlineProjectionDefinition[];
+    getCurrentTime: () => Date;
+    dependencies: DependencyCheck[];
+    includeDefaultDependencyChecks: boolean;
+    autoStartMessageBus: boolean;
+    shutdownOnDependencyFailure: boolean;
+    shutdown: GracefulShutdownConfig;
+    _testOverrides?: ServiceBootstrapOverrides;
+};
+
+declare class DependencyTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+type DependencyCheckResult = {
+    name: string;
+    ok: boolean;
+    required: boolean;
+    durationMs: number;
+    timedOut: boolean;
+    error?: unknown;
+};
+type DependencyCheckSummary = {
+    ok: boolean;
+    results: DependencyCheckResult[];
+};
+/**
+ * Helper for one-off dependency checks with optional logging.
+ */
+declare const startDependency: (dependency: string, startFn: () => Promise<void>, options?: {
+    logger?: Logger;
+    successMessage?: string;
+    timeoutMs?: number;
+}) => Promise<boolean>;
+/**
+ * Executes dependency checks with optional timeouts.
+ */
+declare class DependencyChecker {
+    private readonly logger?;
+    private readonly defaultTimeoutMs?;
+    constructor(options?: {
+        logger?: Logger;
+        defaultTimeoutMs?: number;
+    });
+    check(dependency: DependencyCheck): Promise<DependencyCheckResult>;
+    checkAll(dependencies: DependencyCheck[]): Promise<DependencyCheckSummary>;
+}
+
+declare class ShutdownTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+type ShutdownTask = {
+    name: string;
+    close: () => Promise<void>;
+    timeoutMs?: number;
+};
+type ShutdownTaskResult = {
+    name: string;
+    ok: boolean;
+    timedOut: boolean;
+    durationMs: number;
+    error?: unknown;
+};
+type GracefulShutdownResult = {
+    reason: string;
+    exitCode: number;
+    tasks: ShutdownTaskResult[];
+};
+/**
+ * Runs shutdown tasks with timeout handling and optional exit.
+ */
+declare class GracefulShutdown {
+    private readonly logger?;
+    private readonly timeoutMs?;
+    private readonly exitOnComplete;
+    private readonly exitFn;
+    private readonly tasks;
+    private shuttingDown;
+    private lastResult?;
+    constructor(options?: GracefulShutdownConfig & {
+        logger?: Logger;
+    });
+    /**
+     * Register a shutdown task.
+     */
+    register(task: ShutdownTask): void;
+    /**
+     * Execute all shutdown tasks and return the aggregated result.
+     */
+    shutdown(reason: string, exitCode?: number): Promise<GracefulShutdownResult>;
+}
+
+/**
+ * Runtime context produced by ServiceBootstrap.
+ */
+type ServiceBootstrapContext = {
+    serviceName: string;
+    firebase: {
+        app: app.App;
+        firestore: Firestore;
+        database: Database;
+        auth: Auth;
+    };
+    firestore: Firestore;
+    database: Database;
+    auth: Auth;
+    pubsub: PubSub;
+    eventStore: EventStore;
+    messageBus: MessageBusWithLifecycle;
+    logger?: Logger;
+    getCurrentTime: () => Date;
+    config: ResolvedServiceBootstrapConfig;
+};
+/**
+ * Error thrown when required dependencies fail health checks.
+ */
+declare class DependencyUnavailableError extends Error {
+    readonly summary: DependencyCheckSummary;
+    constructor(summary: DependencyCheckSummary);
+}
+type CreateAppOptions = {
+    openApiPath: string;
+    handlersPath: string;
+    initializeHandlers: (handlers?: ImportedHandlerModules) => void | Promise<void>;
+    openApiOptions?: Partial<Omit<OpenApiValidatorOptions, 'apiSpec' | 'operationHandlers' | 'initializeHandlers'>>;
+    appOptions?: Omit<ApplicationOptions, 'openApiValidator' | 'observability'>;
+};
+type StartApiOptions = Omit<CreateAppOptions, 'initializeHandlers'> & {
+    initializeHandlers: (handlers: ImportedHandlerModules | undefined, ctx: ServiceBootstrapContext) => void | Promise<void>;
+    port?: number;
+    registerSignalHandlers?: boolean;
+    beforeStart?: (ctx: ServiceBootstrapContext) => void | Promise<void>;
+};
+/**
+ * Orchestrates Firebase, PubSub, event store, and lifecycle utilities.
+ */
+declare class ServiceBootstrap {
+    private readonly config;
+    private resolvedConfig?;
+    private logger?;
+    private context?;
+    private dependencyChecker?;
+    private shutdownManager?;
+    constructor(config: ServiceBootstrapConfig);
+    /**
+     * Resolve configuration with defaults and environment variables.
+     */
+    getConfig(): ResolvedServiceBootstrapConfig;
+    /**
+     * Return the initialized context if available.
+     */
+    getContext(): ServiceBootstrapContext | undefined;
+    /**
+     * Register process signal handlers that trigger shutdown.
+     */
+    registerSignalHandlers(options?: {
+        signals?: NodeJS.Signals[];
+        exitCode?: number;
+    }): () => void;
+    /**
+     * Create an Express app using emmett-expressjs-with-openapi defaults.
+     */
+    createApp(options: CreateAppOptions): Promise<Application>;
+    /**
+     * Initialize, run dependency checks, create the app, and start the HTTP server.
+     */
+    startApi(options: StartApiOptions): Promise<{
+        app: Application;
+        server: ReturnType<typeof startAPI>;
+        context: ServiceBootstrapContext;
+    }>;
+    /**
+     * Initialize Firebase, PubSub, and event store wiring.
+     * Does not execute dependency checks.
+     */
+    initialize(): Promise<ServiceBootstrapContext>;
+    /**
+     * Initialize and run dependency checks before returning context.
+     */
+    start(): Promise<ServiceBootstrapContext>;
+    /**
+     * Execute graceful shutdown tasks and return the shutdown result.
+     */
+    shutdown(reason: string, exitCode?: number): Promise<GracefulShutdownResult>;
+    private getLogger;
+    private resolveConfig;
+    private getDatabaseURL;
+    private getDependencyChecker;
+    private getShutdownManager;
+    private registerDefaultShutdownTasks;
+    private buildDefaultDependencyChecks;
+}
+
+type FirebaseInitializationOptions = {
+    projectId: string;
+    databaseURL?: string;
+    firestoreEmulatorHost?: string;
+    databaseEmulatorHost?: string;
+    logger?: Logger;
+    _firebaseAdmin?: FirebaseAdminLike;
+};
+type FirebaseInitResult = {
+    app: app.App;
+    firestore: Firestore;
+    database: Database;
+    auth: Auth;
+};
+/**
+ * Initializes Firebase Admin SDK with emulator support.
+ */
+declare class FirebaseInitializer {
+    private readonly options;
+    constructor(options: FirebaseInitializationOptions);
+    /**
+     * Returns true if emulator hosts are configured.
+     */
+    isEmulatorMode(): boolean;
+    /**
+     * Initialize Firebase Admin and return service handles.
+     */
+    initialize(): Promise<FirebaseInitResult>;
+    private getOrCreateApp;
+    private getDatabaseURL;
+}
+
+type PubSubInitializationOptions = {
+    projectId: string;
+    emulatorHost?: string;
+    logger?: Logger;
+    _pubsub?: PubSub;
+};
+/**
+ * Initializes PubSub client with optional emulator support.
+ */
+declare class PubSubInitializer {
+    private readonly options;
+    constructor(options: PubSubInitializationOptions);
+    /**
+     * Returns true if emulator host is configured.
+     */
+    isEmulatorMode(): boolean;
+    /**
+     * Initialize PubSub client or return injected instance.
+     */
+    initialize(): Promise<PubSub>;
+}
+
+type SignalHandlerOptions = {
+    shutdown: (reason: string, exitCode?: number) => void | Promise<void>;
+    signals?: NodeJS.Signals[];
+    logger?: Logger;
+    exitCode?: number;
+};
+/**
+ * Register process signal handlers and return an unregister function.
+ */
+declare const registerSignalHandlers: (options: SignalHandlerOptions) => (() => void);
+
+type EventStoreFactoryOptions = {
+    firestore: Firestore;
+    database: Database;
+    projections?: RealtimeDBInlineProjectionDefinition[];
+    logger?: Logger;
+};
+/**
+ * Create a Firestore-backed event store and wire RealtimeDB projections if provided.
+ */
+declare const createEventStore: <T extends EventStore = EventStore>(options: EventStoreFactoryOptions) => T;
+
+export { type CreateAppOptions, type DependencyCheck, type DependencyCheckResult, type DependencyCheckSummary, DependencyChecker, DependencyTimeoutError, DependencyUnavailableError, type EventStoreFactoryOptions, type FirebaseAdminLike, type FirebaseConfig, type FirebaseInitResult, type FirebaseInitializationOptions, FirebaseInitializer, GracefulShutdown, type GracefulShutdownConfig, type GracefulShutdownResult, type LogLevel, type Logger, type MessageBusWithLifecycle, type ObservabilityConfig, type PubSubConfig, type PubSubInitializationOptions, PubSubInitializer, type ResolvedFirebaseConfig, type ResolvedPubSubConfig, type ResolvedServiceBootstrapConfig, ServiceBootstrap, type ServiceBootstrapConfig, type ServiceBootstrapContext, type ServiceBootstrapOverrides, type ShutdownTask, type ShutdownTaskResult, ShutdownTimeoutError, type SignalHandlerOptions, type StartApiOptions, createEventStore, registerSignalHandlers, startDependency };