@lpdjs/firestore-repo-service 2.4.3 → 2.6.2-beta.0

package/dist/servers/hono/index.d.cts

@@ -1,7 +1,192 @@
-import { Env, MiddlewareHandler, Context, Hono } from 'hono';
+import { Env, Context, MiddlewareHandler, Hono } from 'hono';
 import { IncomingMessage, ServerResponse } from 'node:http';
+import { HttpsOptions } from 'firebase-functions/v2/https';
 import { z, ZodError } from 'zod';
 
+/**
+ * Global DI services container for the Hono server.
+ *
+ * Lets you declare all your singletons (repositories, SDK clients, useCases,
+ * loggers…) **once**, then inject them anywhere — routes, interceptors,
+ * cron jobs, Firestore triggers, tests.
+ *
+ * ## How it works
+ *
+ *  - Each service is constructed **lazily** on first access and cached for
+ *    the process lifetime (perfect for Cloud Functions cold-start).
+ *  - Providers may be **classes** (auto-injected: `new Class(services)`)
+ *    or **factories** (`(services) => instance`). Mix both freely.
+ *  - Inter-service dependencies are inferred either by destructuring the
+ *    factory argument (`postRepo: ({ db }) => new PostRepo(db)`) or by
+ *    reading `this.services.*` inside a class.
+ *  - A built-in `ctx` service exposes the **current request's** Hono
+ *    `Context` via `AsyncLocalStorage`. UseCases access
+ *    `this.services.ctx.c.get("user")` without any plumbing.
+ *  - Cycles are detected at first access with a clear error.
+ *
+ * @example
+ * ```ts
+ * // src/services.ts
+ * import { createServices } from "@lpdjs/firestore-repo-service/servers/hono";
+ * import { PostRepo } from "./domains/posts/PostRepo.js";
+ * import { CreatePostUseCase } from "./domains/posts/useCases/createPost/useCase.js";
+ *
+ * export const services = createServices({
+ *   postRepo: PostRepo,                   // class form (auto-injected)
+ *   createPostUseCase: CreatePostUseCase, // class form (auto-injected)
+ * });
+ *
+ * export type Services = typeof services;
+ * ```
+ *
+ * @example
+ * ```ts
+ * // src/apis.ts
+ * import { services } from "./services.js";
+ * export const apis = createApiRegistry(
+ *   { v1: { basePath: "/v1", ... } },
+ *   { services },
+ * );
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Inside a useCase registered as a class
+ * import type { Services } from "../../services.js";
+ *
+ * export class CreatePostUseCase {
+ *   constructor(private readonly services: Services) {}
+ *
+ *   async execute(input: { title: string }) {
+ *     const user = this.services.ctx.c.get("user");
+ *     return this.services.postRepo.create({ ...input, authorId: user.id });
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Per-request context exposed to every service / useCase.
+ * The instance is a **stable singleton** but its `c` getter resolves to the
+ * Hono `Context` of the currently-handled request via `AsyncLocalStorage`.
+ *
+ * Outside of a request (cron, manual scripts, tests), wrap your call in
+ * {@link withRequestContext} to supply a context, otherwise accessing `c`
+ * will throw.
+ */
+interface RequestContext<TEnv extends Env = Env> {
+    /** Hono `Context` of the currently-handled request. */
+    readonly c: Context<TEnv>;
+    /**
+     * Same as `c` but returns `undefined` instead of throwing when called
+     * outside a request scope. Useful for opportunistic logging.
+     */
+    readonly maybeC: Context<TEnv> | undefined;
+}
+/**
+ * Hono middleware installed automatically by `HonoServer` when a `services`
+ * container is provided. Populates the AsyncLocalStorage so the built-in
+ * `ctx` service resolves to the current request.
+ *
+ * Exported for advanced cases (custom server / non-Hono adapter); you do not
+ * need to call this manually in the standard flow.
+ */
+declare function createRequestContextMiddleware(): MiddlewareHandler;
+/**
+ * Run `fn` with a synthetic request context — required when invoking
+ * services outside an HTTP handler (cron jobs, Firestore triggers, scripts,
+ * unit tests). Inside `fn`, `services.ctx.c` resolves to the supplied `c`.
+ *
+ * @example
+ * ```ts
+ * // A cron that reuses a useCase
+ * export const dailyTask = onSchedule("every 24 hours", async () => {
+ *   await withRequestContext({ c: fakeContext() }, async () => {
+ *     await services.createPostUseCase.execute({ ... });
+ *   });
+ * });
+ * ```
+ */
+declare function withRequestContext<T>(ctx: {
+    c: Context;
+}, fn: () => Promise<T> | T): Promise<T>;
+/**
+ * Reserved service name — the built-in request context. User factories
+ * cannot override it.
+ */
+declare const CTX_KEY: "ctx";
+/**
+ * Helper that derives the public services type from an output map.
+ * Each entry in `TMap` is the instance type returned by its provider.
+ * The built-in `ctx` is always present.
+ */
+type ServicesOf<TMap> = {
+    readonly ctx: RequestContext;
+} & {
+    readonly [K in keyof TMap]: TMap[K];
+};
+/**
+ * A single provider entry — either a factory `(deps) => R` or a class
+ * `new (deps) => R`. `deps` is the *complete* services proxy
+ * (siblings + built-in `ctx`).
+ */
+type ServiceProvider<TMap, R> = ((deps: ServicesOf<TMap>) => R) | (new (deps: ServicesOf<TMap>) => R);
+/**
+ * A provider map — each value is either a factory or a class constructor.
+ */
+type ServiceProviderMap<TMap> = {
+    [K in keyof TMap]: K extends typeof CTX_KEY ? never : ServiceProvider<TMap, TMap[K]>;
+};
+/**
+ * Extract the instance/return type from a single provider value.
+ */
+type ProviderReturn<P> = P extends new (...args: any) => infer R ? R : P extends (...args: any) => infer R ? R : never;
+/**
+ * Compute the output service map from an inferred provider map.
+ */
+type MapFromProviders<P> = {
+    [K in keyof P]: ProviderReturn<P[K]>;
+};
+/**
+ * Container returned by {@link createServices}. Behaves like a plain object
+ * keyed by service name — accessing a key triggers lazy instantiation.
+ * Use `type Services = typeof services` to derive the public type.
+ */
+type ServicesContainer<TMap> = TMap;
+/**
+ * Build a lazy singleton DI container.
+ *
+ * @param providers  A map of service name → factory function **or** class
+ *                   constructor. The single argument (factory deps / first
+ *                   ctor param) receives a deps proxy typed as the full
+ *                   services map (siblings + the built-in `ctx`).
+ *
+ * @example Factory form
+ * ```ts
+ * db: () => getFirestore(),
+ * postRepo: ({ db }) => new PostRepo(db),
+ * ```
+ *
+ * @example Class form (zero-boilerplate auto-injection)
+ * ```ts
+ * class CreatePostUseCase {
+ *   constructor(private readonly services: Services) {}
+ *   async execute() { return this.services.postRepo.list(); }
+ * }
+ *
+ * createServices({
+ *   postRepo: PostRepo,                   // ← bare class
+ *   createPostUseCase: CreatePostUseCase, // ← bare class
+ * });
+ * ```
+ */
+declare function createServices<P extends Record<string, ((deps: any) => unknown) | (new (deps: any) => unknown)>>(providers: P): ServicesContainer<ServicesOf<MapFromProviders<P>>>;
+/**
+ * Opaque container type used by registry / server signatures that don't
+ * need to know the concrete services map.
+ */
+type AnyServicesContainer = ServicesContainer<Record<string, any>>;
+
 /**
  * Public types for the Hono file-based API server.
  *
@@ -16,11 +201,17 @@ type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
 /** Where the validated payload comes from. */
 type PayloadSource = "json" | "query" | "form" | "param";
 /** Handler signature — receives a single typed context object. */
-type RouteHandler<TIn, TOut, TEnv extends Env = Env> = (ctx: {
+type RouteHandler<TIn, TOut, TEnv extends Env = Env, TServices extends AnyServicesContainer = AnyServicesContainer> = (ctx: {
     /** Validated (and typed) request payload. `void` when no `input` schema is defined. */
     input: TIn;
     /** Raw Hono `Context` for headers, set status, redirect, etc. */
     c: Context<TEnv>;
+    /**
+     * Global DI services container — same instance shared by every handler.
+     * Empty `ServicesContainer` when the server was started without a
+     * `services` option.
+     */
+    services: TServices;
 }) => Promise<TOut | Response> | TOut | Response;
 /**
  * One route declaration. Default-exported by every `routes.ts` file inside the
@@ -123,7 +314,7 @@ declare class ValidationError extends Error {
  * }
  * ```
  */
-type RouteInterceptor<TEnv extends Env = Env> = (ctx: {
+type RouteInterceptor<TEnv extends Env = Env, TServices extends AnyServicesContainer = AnyServicesContainer> = (ctx: {
     /**
      * Calls validation + handler and returns the raw value.
      * Throws {@link ValidationError} on Zod failure or any error thrown by the handler.
@@ -133,6 +324,8 @@ type RouteInterceptor<TEnv extends Env = Env> = (ctx: {
     route: AnyRouteDef;
     /** Hono request context. */
     c: Context<TEnv>;
+    /** Global DI services container. See {@link RouteHandler}. */
+    services: TServices;
 }) => Promise<Response | unknown> | Response | unknown;
 /** OpenAPI document info (subset of the spec used by the helper). */
 interface OpenAPIInfo {
@@ -196,6 +389,18 @@ interface HonoServerOptions<TEnv extends Env = Env> {
      * See {@link RouteInterceptor}.
      */
     interceptor?: RouteInterceptor<TEnv>;
+    /**
+     * Global DI services container (see {@link createServices}).
+     *
+     * When provided:
+     *  - a middleware is installed automatically so the built-in `ctx`
+     *    service resolves to the current request via `AsyncLocalStorage`;
+     *  - `services` is passed into every handler and the interceptor.
+     *
+     * The same container instance should be shared across every API of your
+     * project — declare it once and pass it to {@link createApiRegistry}.
+     */
+    services?: AnyServicesContainer;
 }
 
 /**
@@ -235,7 +440,7 @@ declare class HonoServer<TEnv extends Env = Env> {
      * @param httpsOptions  Options forwarded as the first argument to
      *                      `onRequest()` (region, memory, invoker, etc.).
      */
-    toFunction(onRequest: OnRequestFn$1, httpsOptions?: Record<string, unknown>): any;
+    toFunction(onRequest: OnRequestFn$1, httpsOptions?: HttpsOptions): any;
     /** Generate (and cache) the OpenAPI 3.1 spec for the mounted routes. */
     buildOpenApiSpec(): Record<string, unknown>;
     private mountRoutes;
@@ -288,30 +493,37 @@ declare class HonoServer<TEnv extends Env = Env> {
 type OnRequestFn = (...args: any[]) => any;
 /**
  * Per-API configuration. Same shape as {@link HonoServerOptions} minus the
- * `routes` (resolved by the registry) and `api` (the registry key).
+ * `routes` (resolved by the registry), `api` (the registry key) and
+ * `services` (set globally on the registry — see
+ * {@link createApiRegistry}).
  */
-type ApiConfig<TEnv extends Env = Env> = Omit<HonoServerOptions<TEnv>, "routes" | "api">;
+type ApiConfig<TEnv extends Env = Env> = Omit<HonoServerOptions<TEnv>, "routes" | "api" | "services">;
 /** Map of API tag → its config. */
 type ApiConfigMap = Record<string, ApiConfig>;
-interface ApiRegistry<TMap extends ApiConfigMap> {
+/**
+ * Options accepted by {@link createApiRegistry} alongside the per-API
+ * configs.
+ */
+interface ApiRegistryOptions<TServices extends AnyServicesContainer = AnyServicesContainer> {
+    /**
+     * Global DI services container shared across every API. See
+     * {@link ServicesContainer} / `createServices`. When provided, every
+     * `HonoServer` mounted by the registry receives it and exposes
+     * `services` to every handler / interceptor.
+     */
+    services?: TServices;
+}
+interface ApiRegistry<TMap extends ApiConfigMap, TServices extends AnyServicesContainer = AnyServicesContainer> {
     /** The registered configs (read-only). */
     readonly configs: TMap;
     /**
-     * Typed `defineRoute` — the `api` field is constrained to `keyof TMap`.
-     *
-     * To expose the same logical endpoint under several APIs with different
-     * `input` / `output` schemas, call `defineRoute` once per route and wrap
-     * them in an array — per-call inference is preserved:
-     *
-     * ```ts
-     * export default [
-     *   defineRoute({ api: "v1", input: V1Input, handler: ({ input }) => ... }),
-     *   defineRoute({ api: "v2", input: V2Input, handler: ({ input }) => ... }),
-     * ];
-     * ```
+     * Typed `defineRoute` — the `api` field is constrained to `keyof TMap`,
+     * and `handler({ services })` is typed with the concrete services
+     * container passed to {@link createApiRegistry}.
      */
-    defineRoute<TIn extends z.ZodTypeAny | undefined = undefined, TOut extends z.ZodTypeAny | undefined = undefined>(def: Omit<RouteDef<TIn, TOut>, "api"> & {
+    defineRoute<TIn extends z.ZodTypeAny | undefined = undefined, TOut extends z.ZodTypeAny | undefined = undefined>(def: Omit<RouteDef<TIn, TOut>, "api" | "handler"> & {
         api: keyof TMap & string;
+        handler: RouteHandler<TIn extends z.ZodTypeAny ? z.infer<TIn> : void, TOut extends z.ZodTypeAny ? z.infer<TOut> : unknown, Env, TServices>;
     }): RouteDef<TIn, TOut> & {
         api: keyof TMap & string;
     };
@@ -325,8 +537,10 @@ interface ApiRegistry<TMap extends ApiConfigMap> {
      * @param opts Optional defaults and per-API overrides for `httpsOptions`.
      */
     toFunctions(routes: AnyRouteDef[], onRequest: OnRequestFn, opts?: {
-        defaults?: Record<string, unknown>;
-        per?: Partial<Record<keyof TMap & string, Record<string, unknown>>>;
+        /** Shared `HttpsOptions` applied to every generated function. */
+        defaults?: HttpsOptions;
+        /** Per-API overrides — merged on top of {@link defaults}. */
+        per?: Partial<Record<keyof TMap & string, HttpsOptions>>;
     }): {
         [K in keyof TMap & string]: ReturnType<OnRequestFn>;
     };
@@ -336,8 +550,11 @@ interface ApiRegistry<TMap extends ApiConfigMap> {
 /**
  * Factory — declare every API tag once and get back a typed `defineRoute`
  * + `toFunctions`. See the file-level example.
+ *
+ * @param configs  API-tag → per-API config.
+ * @param options  Cross-API options (shared services container, etc).
  */
-declare function createApiRegistry<const TMap extends ApiConfigMap>(configs: TMap): ApiRegistry<TMap>;
+declare function createApiRegistry<const TMap extends ApiConfigMap, TServices extends AnyServicesContainer = AnyServicesContainer>(configs: TMap, options?: ApiRegistryOptions<TServices>): ApiRegistry<TMap, TServices>;
 
 /**
  * OpenAPI 3.1 spec generator from {@link RouteDef} entries.
@@ -452,4 +669,4 @@ declare function generateRoutesManifest(routes: ScannedRoute[], opts: GeneratorO
 /** Convenience helper used by the CLI — combines scan + generate in one call. */
 declare function generateFromRoot(rootAbs: string, outFileRel: string, derive: PathDeriveOptions, importExtension: string, scan: (root: string) => ScannedRoute[]): GenerationResult;
 
-export { type AnyRouteDef, type ApiConfig, type ApiConfigMap, type ApiRegistry, DEFAULT_DERIVE, DEFAULT_GENERATOR_BANNER, DEFAULT_SCANNER, type GenerationResult, type GeneratorOptions, HonoServer, type HonoServerOptions, type HttpMethod, type OpenAPIConfig, type OpenAPIInfo, type PathDeriveOptions, type PayloadSource, type RouteDef, type RouteHandler, type RouteInterceptor, type RouteModuleDefault, type ScannedRoute, type ScannerOptions, ValidationError, buildOpenApiDocument, createApiRegistry, derivePath, generateFromRoot, generateRoutesManifest, renderDocsHtml, scanRoutes, toImportSpecifier };
+export { type AnyRouteDef, type AnyServicesContainer, type ApiConfig, type ApiConfigMap, type ApiRegistry, type ApiRegistryOptions, DEFAULT_DERIVE, DEFAULT_GENERATOR_BANNER, DEFAULT_SCANNER, type GenerationResult, type GeneratorOptions, HonoServer, type HonoServerOptions, type HttpMethod, type OpenAPIConfig, type OpenAPIInfo, type PathDeriveOptions, type PayloadSource, type RequestContext, type RouteDef, type RouteHandler, type RouteInterceptor, type RouteModuleDefault, type ScannedRoute, type ScannerOptions, type ServiceProvider, type ServiceProviderMap, type ServicesContainer, type ServicesOf, ValidationError, buildOpenApiDocument, createApiRegistry, createRequestContextMiddleware, createServices, derivePath, generateFromRoot, generateRoutesManifest, renderDocsHtml, scanRoutes, toImportSpecifier, withRequestContext };