@emmett-community/emmett-google-services-bootstrap 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,307 +1,31 @@
-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 { S as ServiceBootstrapContext, L as Logger, F as FirebaseAdminLike } from './ServiceBootstrap-Cn1LJQgC.js';
+export { C as CreateAppOptions, e as DependencyCheck, k as DependencyCheckResult, l as DependencyCheckSummary, m as DependencyChecker, j as DependencyTimeoutError, D as DependencyUnavailableError, d as FirebaseConfig, r as GracefulShutdown, G as GracefulShutdownConfig, q as GracefulShutdownResult, c as LogLevel, M as MessageBusWithLifecycle, O as ObservabilityConfig, P as PubSubConfig, R as ResolvedFirebaseConfig, h as ResolvedPubSubConfig, i as ResolvedServiceBootstrapConfig, b as ServiceBootstrap, g as ServiceBootstrapConfig, f as ServiceBootstrapOverrides, o as ShutdownTask, p as ShutdownTaskResult, n as ShutdownTimeoutError, a as StartApiOptions, s as startDependency } from './ServiceBootstrap-Cn1LJQgC.js';
+import * as express from 'express';
+import * as qs from 'qs';
+import * as express_serve_static_core from 'express-serve-static-core';
 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 { PubSub } from '@google-cloud/pubsub';
+import { FirestoreEventStoreOptions } from '@emmett-community/emmett-google-firestore';
 import { RealtimeDBInlineProjectionDefinition } from '@emmett-community/emmett-google-realtime-db';
 export { realtimeDBInlineProjection } from '@emmett-community/emmett-google-realtime-db';
+import { EventStore } from '@event-driven-io/emmett';
+export { ImportedHandlerModules, NoContent, OK, createFirebaseAuthSecurityHandlers, lazyApplication, on } from '@emmett-community/emmett-expressjs-with-openapi';
+import '@emmett-community/emmett-google-pubsub';
 
-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.
+ * Handler for `GET /health` (liveness): the process is up and serving requests.
+ * Wire it to the `getHealth` operation of the service contract.
  */
-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>;
-};
+declare const getHealth: (request: express.Request<express_serve_static_core.ParamsDictionary, any, any, qs.ParsedQs, Record<string, any>>, response: express.Response, _next: express.NextFunction) => Promise<void>;
 /**
- * Orchestrates Firebase, PubSub, event store, and lifecycle utilities.
+ * Handler for `GET /ready` (readiness): answers 200 when the stores, the message bus and the
+ * configured dependencies answer, and 503 with the failed checks otherwise.
+ * Wire it to the `getReady` operation of the service contract.
  */
-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;
-}
+declare const getReady: (ctx: Pick<ServiceBootstrapContext, "checkReadiness">) => (request: express.Request<express_serve_static_core.ParamsDictionary, any, any, qs.ParsedQs, Record<string, any>>, response: express.Response, _next: express.NextFunction) => Promise<void>;
 
 type FirebaseInitializationOptions = {
     projectId: string;
@@ -373,10 +97,11 @@ type EventStoreFactoryOptions = {
     database: Database;
     projections?: RealtimeDBInlineProjectionDefinition[];
     logger?: Logger;
+    collections?: FirestoreEventStoreOptions['collections'];
 };
 /**
  * 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 };
+export { type EventStoreFactoryOptions, FirebaseAdminLike, type FirebaseInitResult, type FirebaseInitializationOptions, FirebaseInitializer, Logger, type PubSubInitializationOptions, PubSubInitializer, ServiceBootstrapContext, type SignalHandlerOptions, createEventStore, getHealth, getReady, registerSignalHandlers };