@twasik4/pocket-service 1.0.0 → 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,700 @@
+import { Request, Response, NextFunction, Router, Express } from 'express';
+import { ZodSchema, output } from 'zod';
+import { RedisClientType } from 'redis';
+import { Logger } from 'winston';
+import * as _clickhouse_client from '@clickhouse/client';
+import { Document, Collection, Filter, WithId, MongoClient, Db } from 'mongodb';
+import { PeerCertificate } from 'tls';
+
+type RouteMeta = {
+    description?: string;
+    deprecated?: boolean;
+    tags?: string[];
+    authRequired?: boolean;
+    rateLimit?: "standard" | "strict" | "none";
+    version?: string;
+    [key: string]: any;
+};
+type AuthenticatedUser = {
+    userId: string;
+    [key: string]: string | string[] | number | boolean;
+};
+type AuthResolver = (req: Request, route: RouteDefinition<any, any, boolean>) => AuthenticatedUser | null | Promise<AuthenticatedUser | null>;
+type AuthStrategy = {
+    name: string;
+    canHandle?: (req: Request, route: RouteDefinition<any, any, boolean>) => boolean | Promise<boolean>;
+    authenticate: AuthResolver;
+};
+declare function defaultHeaderAuthResolver(req: Request): AuthenticatedUser | null;
+declare function createAuthResolver(strategies: AuthStrategy[], opts?: {
+    fallbackResolver?: AuthResolver;
+}): AuthResolver;
+type TypedRequest<TBody = unknown, TParams = unknown, TRequireAuth extends boolean = false> = Request<TParams extends ZodSchema ? output<TParams> : Record<string, string>, any, TBody extends ZodSchema ? output<TBody> : any> & (TRequireAuth extends true ? {
+    user: AuthenticatedUser;
+} : {
+    user?: AuthenticatedUser;
+});
+type TypedRequestHandler<TBody = unknown, TParams = unknown, TRequireAuth extends boolean = false> = (req: TypedRequest<TBody, TParams, TRequireAuth>, res: Response, next: NextFunction) => unknown;
+/**
+ * Defines a route with enhanced type safety and built-in support for request validation and authentication. This type is used in conjunction with the `addRoute` function to register routes on an Express router, allowing you to specify the HTTP method, path, authentication requirements, and Zod schemas for validating request bodies and URL parameters. The route definition also includes optional metadata that can be used for documentation or analytics purposes.
+ */
+type RouteDefinition<TBody extends ZodSchema | undefined = undefined, TParams extends ZodSchema | undefined = undefined, TRequireAuth extends boolean = false> = {
+    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    fullPath: string;
+    requireAuth?: TRequireAuth;
+    /**
+     * Optional Zod schema to validate the request body. Only applicable for non-GET requests. If provided, the middleware will automatically validate the request body against this schema and return a 400 error if validation fails.
+     */
+    bodyValidator?: TBody;
+    /**
+     * Optional Zod schema to validate URL parameters (e.g., :id in /users/:id). If provided, the middleware will automatically validate the URL parameters against this schema and return a 400 error if validation fails.
+     */
+    paramsValidator?: TParams;
+    /**
+     * Optional metadata for the route, which can be used for documentation, analytics, or other purposes.
+     */
+    meta?: RouteMeta;
+};
+declare function getRegisteredRoutes(): RouteDefinition<any, any, boolean>[];
+type CreateMetaRouterOptions = {
+    authResolver?: AuthResolver;
+    onUnauthorized?: (req: Request, res: Response) => void;
+    onAuthError?: (err: unknown, req: Request, res: Response) => void;
+};
+/**
+ * Utility function to create an Express router with enhanced type safety and built-in support for request validation and authentication. This function allows you to define routes with associated Zod schemas for validating request bodies and URL parameters, as well as specifying whether authentication is required for each route. The returned object includes the configured Express router, a list of registered routes for introspection, and a helper function to add new routes with the specified configurations.
+ */
+declare function createMetaRouter(): {
+    /**
+     * The Express router instance that can be used to register routes and middleware. This router is configured to work with the enhanced route definitions provided by the `addRoute` function, which supports request validation and authentication requirements.
+     */
+    router: Router;
+    /**
+     * List of registered routes with their configurations, which can be used for introspection, documentation generation, or analytics purposes. Each entry includes the HTTP method, full path, authentication requirement, validation schemas, and any additional metadata provided during route registration.
+     */
+    routes: RouteDefinition<any, any, boolean>[];
+    /**
+     * Adds a new route to the router with the specified configuration and request handler.
+     *
+     * - If `requireAuth` is set to true, the route will automatically include middleware to check for an authenticated user and return a 401 error if the user is not authenticated.
+     * - If `bodyValidator` or `paramsValidator` are provided, the route will include middleware to validate the request body and URL parameters against the provided Zod schemas, returning a 400 error if validation fails.
+     *
+     * The route definition is also stored in an internal list for introspection purposes.
+     *
+     * @param route The route definition, including method, path, validation schemas, and authentication requirements.
+     * @param handler The request handler function for the route.
+     * @returns void
+     *
+     * @example
+     * addRoute(
+     *   {
+     *     fullPath: "/me",
+     *     method: "GET",
+     *     requireAuth: true,
+     *     meta: {
+     *       description: "Get current authenticated user info",
+     *     },
+     *   },
+     *   async (req, res) => {
+     *     try {
+     *       ...fetch user info from database using req.user.userId...
+     *       res.status(200).json(...user info...);
+     *     } catch (err) {
+     *       console.error("Failed to fetch user info:", err);
+     *       res
+     *         .status(500)
+     *         .json({ isSuccess: false, message: "Internal server error" });
+     *     }
+     *   },
+     * );
+     */
+    addRoute: <TBody extends ZodSchema | undefined = undefined, TParams extends ZodSchema | undefined = undefined, TRequireAuth extends boolean = false>(route: RouteDefinition<TBody, TParams, TRequireAuth>, 
+    /** Request handler for the route */ handler: TypedRequestHandler<TBody, TParams, TRequireAuth>) => void;
+};
+declare function createMetaRouterWithAuth(options?: CreateMetaRouterOptions): {
+    /**
+     * The Express router instance that can be used to register routes and middleware. This router is configured to work with the enhanced route definitions provided by the `addRoute` function, which supports request validation and authentication requirements.
+     */
+    router: Router;
+    /**
+     * List of registered routes with their configurations, which can be used for introspection, documentation generation, or analytics purposes. Each entry includes the HTTP method, full path, authentication requirement, validation schemas, and any additional metadata provided during route registration.
+     */
+    routes: RouteDefinition<any, any, boolean>[];
+    /**
+     * Adds a new route to the router with the specified configuration and request handler.
+     *
+     * - If `requireAuth` is set to true, the route will automatically include middleware to check for an authenticated user and return a 401 error if the user is not authenticated.
+     * - If `bodyValidator` or `paramsValidator` are provided, the route will include middleware to validate the request body and URL parameters against the provided Zod schemas, returning a 400 error if validation fails.
+     *
+     * The route definition is also stored in an internal list for introspection purposes.
+     *
+     * @param route The route definition, including method, path, validation schemas, and authentication requirements.
+     * @param handler The request handler function for the route.
+     * @returns void
+     *
+     * @example
+     * addRoute(
+     *   {
+     *     fullPath: "/me",
+     *     method: "GET",
+     *     requireAuth: true,
+     *     meta: {
+     *       description: "Get current authenticated user info",
+     *     },
+     *   },
+     *   async (req, res) => {
+     *     try {
+     *       ...fetch user info from database using req.user.userId...
+     *       res.status(200).json(...user info...);
+     *     } catch (err) {
+     *       console.error("Failed to fetch user info:", err);
+     *       res
+     *         .status(500)
+     *         .json({ isSuccess: false, message: "Internal server error" });
+     *     }
+     *   },
+     * );
+     */
+    addRoute: <TBody extends ZodSchema | undefined = undefined, TParams extends ZodSchema | undefined = undefined, TRequireAuth extends boolean = false>(route: RouteDefinition<TBody, TParams, TRequireAuth>, 
+    /** Request handler for the route */ handler: TypedRequestHandler<TBody, TParams, TRequireAuth>) => void;
+};
+
+interface ClickhouseTable<TSchema extends Record<string, any>> {
+    name: string;
+    createSQL: string;
+    schema: () => TSchema;
+}
+interface ClickhouseConfig<TTables extends Record<string, ClickhouseTable<any>>> {
+    url: string;
+    username?: string;
+    password?: string;
+    tables: TTables;
+}
+declare function createTypedClickhouse<TTables extends Record<string, ClickhouseTable<any>>>(config: ClickhouseConfig<TTables>): {
+    client: _clickhouse_client.ClickHouseClient;
+    ensureTables: () => Promise<void>;
+} & { [K in keyof TTables]: {
+    select(where?: Partial<ReturnType<TTables[K]["schema"]>>): Promise<ReturnType<TTables[K]["schema"]>[]>;
+    insert(rows: ReturnType<TTables[K]["schema"]>[]): Promise<void>;
+}; };
+
+type SchemaParser<T extends Document> = {
+    parse: (input: unknown) => T;
+    shape?: unknown;
+    _def?: {
+        shape?: unknown | (() => unknown);
+    };
+};
+declare class CollectionWrapper<T extends Document> {
+    private readonly collection;
+    private readonly schema?;
+    private readonly revision?;
+    constructor(collection: Collection<T>, schema?: SchemaParser<T> | undefined, revision?: Collection<T> | undefined);
+    private parseWrite;
+    private parseRead;
+    private trackRevision;
+    /**
+     * Get all documents from the collection.
+     * @param filter - The filter to find documents to retrieve. If no filter is provided, it will return all documents in the collection.
+     * @returns
+     */
+    get(filter?: Filter<T>): Promise<WithId<T>[]>;
+    /**
+     * Get a single document from the collection.
+     * @param filter - The filter to find the document to retrieve. If no filter is provided, it will return the first document in the collection.
+     * @returns
+     */
+    getOne(filter?: Filter<T>): Promise<WithId<T> | null>;
+    /**
+     * Get all revisions for a document.
+     * @param filter - The filter to find revisions to retrieve. If no filter is provided, it will return all revisions in the revision collection.
+     * @returns An array of revision documents.
+     */
+    getRevisions(filter?: Filter<T>): Promise<WithId<T>[]>;
+    /**
+     * Get the most recent revision for a document.
+     * @returns Revision document or null if no revisions exist or if revision tracking is not enabled.
+     */
+    getMostRecentRevision(): Promise<WithId<T> | null>;
+    /**
+     * Insert a document into the collection.
+     *
+     * If this collection has revision tracking enabled, it will also insert the document into the revision collection.
+     *
+     * @param doc - The document to insert into the collection.
+     */
+    insert(doc: T): Promise<void>;
+    /**
+     * Update multiple documents by filter with a partial document.
+     * @param filter - The filter to find documents to update.
+     * @param update - The partial document to update.
+     */
+    update(filter: Filter<T>, update: Partial<T>): Promise<void>;
+    /**
+     * Update a single document by filter with a partial document. This will automatically set the `updatedAt` field to the current date if it exists in the schema, and increment the `revision` field by 1 if it exists in the schema. It will also insert the updated document into the revision collection if revision tracking is enabled.
+     * @param filter - The filter to find the document to update.
+     * @param update - The partial document to update.
+     */
+    updateOne(filter: Filter<T>, update: Partial<T>): Promise<void>;
+    /**
+     * Soft delete a document by setting the `deletedAt` field to the current date.
+     * If the schema does not have a `deletedAt` field, it will perform a hard delete.
+     * @param filter - The filter to find documents to delete.
+     */
+    delete(filter: Filter<T>): Promise<void>;
+    /**
+     * Checks if the schema has a given property.
+     * @param schema - The Zod schema to check against.
+     * @param property - The property to check for in the schema.
+     * @returns
+     */
+    private hasProperty;
+}
+
+type AnyMongoMethod = (...args: any[]) => any;
+type MongoCollectionMethods = Record<string, AnyMongoMethod>;
+type MongoIndexSpec = {
+    /**
+     * Index key specification. Example: { userId: 1 } for ascending, { userId: -1 } for descending
+     */
+    key: Record<string, 1 | -1>;
+    /**
+     * Optional name for the index. If not provided, MongoDB will auto-generate.
+     */
+    name?: string;
+    /**
+     * Whether the index should enforce uniqueness.
+     */
+    unique?: boolean;
+    /**
+     * Whether the index should be sparse (only index documents with the indexed field).
+     */
+    sparse?: boolean;
+    /**
+     * Whether to build the index in the background without blocking other operations.
+     */
+    background?: boolean;
+    /**
+     * The time-to-live (TTL) for documents in the collection, in seconds. Only applicable for TTL indexes.
+     */
+    expireAfterSeconds?: number;
+};
+type MongoCollectionMethodContext<TDocument extends Document> = {
+    /**
+     * The MongoDB client instance
+     */
+    client: MongoClient;
+    /**
+     * The MongoDB database instance
+     */
+    db: Db;
+    /**
+     * The MongoDB collection instance
+     */
+    collection: Collection<TDocument>;
+    /**
+     * The base collection wrapper instance
+     */
+    base: CollectionWrapper<TDocument>;
+};
+type MongoCollectionDefinition<TDocument extends Document = Document, TMethods extends MongoCollectionMethods = {}> = {
+    name?: string;
+    /**
+     * Whether to automatically track revisions of documents in this collection. If enabled, every update will insert a copy of the updated document into a separate revision collection, allowing you to keep a history of changes. The revision collection will have the same name as the main collection with `_revisions` appended to it (e.g. `users` -> `users_revisions`).
+     */
+    trackRevisions: boolean;
+    schema: SchemaParser<TDocument>;
+    /**
+     * Custom methods to add to the collection wrapper. These methods receive a context object with the MongoDB client, database, collection, and base wrapper instance, allowing you to build complex queries and operations while still benefiting from the schema validation and soft delete functionality provided by the base wrapper.
+     * @param ctx
+     * @returns
+     */
+    methods?: (ctx: MongoCollectionMethodContext<TDocument>) => TMethods;
+    /**
+     * Optional array of index specifications to create on this collection. Indexes are created idempotently on service startup, so duplicate indexes are safely ignored.
+     */
+    indexes?: MongoIndexSpec[];
+};
+type MongoCollectionsConfig = Record<string, MongoCollectionDefinition<any, MongoCollectionMethods>>;
+type InferDocument<TDefinition> = TDefinition extends {
+    schema: SchemaParser<infer TDocument>;
+} ? TDocument : Document;
+type NormalizeDocument<TDocument> = TDocument extends Document ? TDocument : Document;
+type InferMethods<TDefinition> = TDefinition extends {
+    methods: (...args: any[]) => infer TMethods;
+} ? TMethods : TDefinition extends {
+    methods?: (...args: any[]) => infer TMethods;
+} ? TMethods extends undefined ? {} : TMethods : {};
+type MongoBoundCollection<TDocument extends Document, TMethods extends MongoCollectionMethods = {}> = CollectionWrapper<TDocument> & TMethods;
+type InferMongoCollections<TCollections extends MongoCollectionsConfig> = {
+    [K in keyof TCollections]: MongoBoundCollection<NormalizeDocument<InferDocument<TCollections[K]>>, InferMethods<TCollections[K]>>;
+};
+type MongoDatabase<TCollections extends MongoCollectionsConfig> = {
+    client: MongoClient;
+    db: Db;
+    collections: InferMongoCollections<TCollections>;
+    disconnect: () => Promise<void>;
+    connect: () => Promise<MongoClient>;
+} & InferMongoCollections<TCollections>;
+type SchemaOutput<TSchema> = TSchema extends {
+    parse: (input: unknown) => infer TOutput;
+} ? NormalizeDocument<TOutput> : Document;
+/**
+ * Define a MongoDB collection with an associated Zod schema for validation and optional custom methods. The returned collection definition can then be used to create a MongoDatabase instance, which will automatically wrap the collection with the provided schema validation and methods.
+ * @param config The configuration object for the MongoDB collection, including the schema and optional custom methods.
+ */
+declare function defineMongoCollection<TSchema extends SchemaParser<any>>(config: {
+    /**
+     * Optional name for the collection. If not provided, the key used in the collections config will be used as the collection name. This allows you to have more control over the actual collection names in the database, while still using descriptive keys in your code.
+     */
+    name?: string;
+    /**
+     * Zod schema for validating documents in the collection. The schema will be used to parse and validate documents returned from the database, ensuring that they conform to the expected structure and types. If a document does not match the schema, an error will be thrown.
+     */
+    schema: TSchema;
+    methods?: undefined;
+    /**
+     * Optional array of index specifications to create on this collection.
+     */
+    indexes?: MongoIndexSpec[];
+}): MongoCollectionDefinition<SchemaOutput<TSchema>, {}>;
+/**
+ * Define a MongoDB collection with an associated Zod schema for validation and optional custom methods. The returned collection definition can then be used to create a MongoDatabase instance, which will automatically wrap the collection with the provided schema validation and methods.
+ * @param config The configuration object for the MongoDB collection, including the schema and optional custom methods.
+ */
+declare function defineMongoCollection<TSchema extends SchemaParser<any>, TMethods extends MongoCollectionMethods>(config: {
+    /**
+     * Optional name for the collection. If not provided, the key used in the collections config will be used as the collection name. This allows you to have more control over the actual collection names in the database, while still using descriptive keys in your code.
+     */
+    name?: string;
+    /**
+     * Zod schema for validating documents in the collection. The schema will be used to parse and validate documents returned from the database, ensuring that they conform to the expected structure and types. If a document does not match the schema, an error will be thrown.
+     */
+    schema: TSchema;
+    /**
+     * Optional custom methods for the collection. These methods will be added to the collection instance and can be used to implement custom queries or operations.
+     * @param ctx The context object containing the MongoDB client, database, collection, and base collection wrapper.
+     * @returns An object containing the custom methods to be added to the collection instance.
+     */
+    methods: (ctx: MongoCollectionMethodContext<SchemaOutput<TSchema>>) => TMethods;
+    /**
+     * Optional array of index specifications to create on this collection.
+     */
+    indexes?: MongoIndexSpec[];
+}): MongoCollectionDefinition<SchemaOutput<TSchema>, TMethods>;
+declare function createMongo<TCollections extends MongoCollectionsConfig>(dbName: string, config: TCollections, options?: {
+    uri?: string;
+}): MongoDatabase<TCollections>;
+
+type Message = {
+    type: string;
+    userId: string;
+    teamId: string;
+    timestamp: number;
+    payload: Record<string, string | number | boolean | null>;
+};
+type ExpressMiddleware = (req: Request, res: Response, next: NextFunction) => void;
+type BaseExpressOptions = {
+    /**
+     * Don't include the default health check and metrics routes.
+     */
+    omitDefaultRoutes?: boolean;
+    /**
+     * Whether to parse incoming request bodies as JSON.
+     */
+    asJson: boolean;
+    /**
+     * An array of custom Express middleware functions to apply to the Express app globally (before all routes).
+     */
+    customMiddleware?: ExpressMiddleware[];
+    /**
+     * Whether to allow CORS requests with credentials (cookies, authorization headers, etc.). This option is only relevant if CORS is enabled via either `corsFn` or `corsWhitelist`.
+     */
+    credentials?: boolean;
+};
+type ExpressOptionsWithCorsFn = BaseExpressOptions & {
+    /**
+     * A function to determine whether to allow CORS requests from a given origin.
+     * @param origin The origin of the request.
+     * @param callback A callback function to indicate whether the origin is allowed.
+     */
+    corsFn: (origin: string | undefined, callback: (err: Error | null, allow?: boolean) => void) => void;
+};
+type ExpressOptionsWithCorsWhitelist = BaseExpressOptions & {
+    /**
+     * An array of allowed origins for CORS requests. If the origin of an incoming request is in this whitelist, the request will be allowed.
+     */
+    corsWhitelist: string[];
+};
+type ExpressOptions = ExpressOptionsWithCorsFn | ExpressOptionsWithCorsWhitelist;
+type CustomModuleFactory = (log: Logger) => boolean | Promise<boolean>;
+type CustomModules = {
+    init: CustomModuleFactory;
+    shutdown?: CustomModuleFactory;
+    name: string;
+}[];
+
+declare class Service<TCollections extends MongoCollectionsConfig = {}> {
+    private name;
+    private url;
+    private port;
+    private workerCount;
+    private handlers;
+    private loadedEventListeners;
+    private routers;
+    private startedAt;
+    private dependencies;
+    private dependencyOrder;
+    private isWorkerRunning;
+    private serviceStreamSubscriptions;
+    private _status;
+    private readonly HEARTBEAT_INTERVAL;
+    private authStrategies;
+    private authResolverOverride?;
+    private useDefaultHeaderAuthFallback;
+    private expressOptions;
+    private getAuthResolver;
+    get streamKey(): string;
+    get simpleName(): string;
+    get fullUrl(): string;
+    get api(): Express;
+    get log(): Logger;
+    get routes(): {
+        path: string;
+        method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+        requireAuth: boolean;
+        meta: RouteMeta | undefined;
+    }[];
+    get status(): "starting" | "running" | "stopped" | "stopping";
+    /**
+     * MongoDB client instance.
+     *
+     * @requires MongoDB module to be added via withMongo()
+     */
+    get mongo(): MongoDatabase<TCollections>;
+    /**
+     * Typed MongoDB collection wrappers registered through `withMongo()`.
+     *
+     * @requires MongoDB module to be added via withMongo()
+     */
+    get db(): InferMongoCollections<TCollections>;
+    /**
+     * Clickhouse client instance. This will throw an error if Clickhouse module has not been added.
+     *
+     * @requires ClickhouseModule to be added via withClickhouse()
+     * @beta
+     */
+    get clickhouse(): ReturnType<typeof createTypedClickhouse>;
+    /**
+     * Redis client instance. This will throw an error if Redis module has not been added.
+     *
+     * @requires RedisModule to be added via withRedis()
+     */
+    get redis(): RedisClientType;
+    /**
+     * Registers the service in Redis for service discovery.
+     *
+     * @requires RedisModule to be added via withRedis()
+     */
+    register(): Promise<void>;
+    /**
+     * Periodically update the service registration in Redis.
+     *
+     * @requires RedisModule to be added via withRedis()
+     */
+    heartbeat(): Promise<void>;
+    /**
+     * Builds and starts the service by initializing dependencies, setting up routes, and starting the API server.
+     *
+     * The build process includes:
+     * 1. Initializing dependencies in the order they were added (MongoDB, Redis, Clickhouse). This includes the redis workers module if withWorkers() was called.
+     * 2. Initializing any custom modules provided through withModules().
+     * 3. Setting up Express middleware and CORS based on provided options.
+     * 4. Registering default routes like /health and /workers.
+     * 5. Registering any custom routers added through addRouter().
+     * 6. Starting the Express server on the configured port.
+     */
+    build(): this;
+    /**
+     * Reads all files in the src/handlers directory and imports them dynamically.
+     */
+    private loadHandlers;
+    /**
+     * Registers default routes like /health and /workers
+     */
+    private registerDefaultRoutes;
+    private initBaseRoutes;
+    /**
+     * Default worker routes under /workers
+     */
+    private initWorkerRoutes;
+    /**
+     * Spawns worker threads to process messages from Redis streams.
+     * Each worker thread runs the worker-thread.ts file.
+     * Each worker thread is passed the service name, redis URL, and handlers.
+     * Workers communicate back via parentPort to log messages.
+     */
+    private runWorkers;
+    /**
+     * The MongoDB module. This is initialized by calling withMongo() and provides access to the configured MongoDB collections through the `db` property. The MongoDB client will automatically connect when the service is built.
+     *
+     * @param config MongoDB configuration including URI, database name, and collections.
+     *
+     * @example
+     * const t = new Service()
+     *   .withMongo({
+     *     dbName: "test",
+     *     collections: {
+     *       users: { schema: z.object({ id: z.string(), name: z.string() }) },
+     *     },
+     *   })
+     *   .build();
+     *
+     * const l = await t.db.users.get({ id: "123" });
+     */
+    withMongo<TNextCollections extends MongoCollectionsConfig>(config: {
+        dbName: string;
+        uri?: string;
+        collections: TNextCollections;
+    }): Service<TNextCollections>;
+    /**
+     * The Clickhouse module. This is initialized by calling withClickhouse() and provides access to the configured Clickhouse tables through the `clickhouse` property. The Clickhouse client will automatically connect when the service is built.
+     *
+     * This module is a **WIP**.
+     *
+     * @param config Clickhouse configuration including tables.
+     * @beta
+     */
+    withClickhouse<TTables extends Record<string, any>>(config: ClickhouseConfig<TTables>): Service<TCollections> & {
+        clickhouse: ReturnType<typeof createTypedClickhouse<TTables>>;
+    };
+    /**
+     * Optional. Port number for the express server.
+     *
+     * Defaults in the following order:
+     * 1. PORT environment variable
+     * 2. 3100
+     *
+     * @param port port number
+     */
+    withPort(port?: number): this;
+    /**
+     * Optional. Base URL without port.
+     *
+     * Defaults in the following order:
+     * 1. SERVICE_URL environment variable
+     * 2. "http://localhost"
+     *
+     * @param url base url without port
+     */
+    withUrl(url: string): this;
+    /**
+     * Optional. Name of the service. Used for logging and service discovery.
+     *
+     * Defaults in the following order:
+     * 1. SERVICE_NAME environment variable
+     * 2. A random hex string
+     * @param name Name of the service
+     */
+    withName(name: string): this;
+    /**
+     * The Redis module. This is initialized by calling withRedis() and provides a Redis client instance through the `redis` property. The Redis client will automatically connect when the service is built.
+     * @param url Redis URL. Defaults to: redis://redis:6379
+     */
+    withRedis(url?: string): this;
+    /**
+     * Adds worker threads to the service. These are used to process messages from Redis streams. Worker threads will be spawned when build() is called. This must be called after withRedis() to work properly.
+     *
+     * **Note**: This will not initialize without at least one service stream.
+     * @param workerCount Defaults to 1
+     * @param serviceStreams Defaults to empty array
+     * @returns
+     */
+    withWorkers(workerCount: number, serviceStreams?: string[]): this;
+    /**
+     * Loads custom dependencies that can be used in the service. The factory functions will be called during build() after all other dependencies are loaded and can be used to initialize any custom logic or connections. The result of each factory function will be logged.
+     * @param dependencies Object where keys are dependency names and values are factory functions that return a boolean indicating success or failure of initialization.
+     */
+    withModules(dependencies: CustomModules): this;
+    withExpressOptions(options: Partial<ExpressOptions>): this;
+    withAuthStrategy(strategy: AuthStrategy): this;
+    withAuthStrategies(strategies: AuthStrategy[]): this;
+    withAuthResolver(resolver: AuthResolver): this;
+    withoutDefaultHeaderAuthFallback(): this;
+    private internalAddRouter;
+    /**
+     * Registers an express router under a base path.
+     * @param base Base path for this router.
+     * @param router Router instance.
+     * @param routes List of route definitions.
+     * @returns
+     */
+    addRouter(base: string, router: Router, routes?: RouteDefinition<any, any, boolean>[]): this;
+    /**
+     * Gracefully shuts down the service by closing all connections and active workers.
+     */
+    shutdown(opts?: {
+        /**
+         * Optional callback to run before shutdown. Can be used to perform cleanup tasks like closing database connections, etc.
+         */
+        beforeShutdown?: () => Promise<void>;
+        /**
+         * Optional callback to run after shutdown. Can be used to perform any final tasks before the process exits.
+         */
+        afterShutdown?: () => Promise<void>;
+    }): Promise<void>;
+    [Symbol.dispose](): void;
+    [Symbol.iterator](): Generator<any, void, unknown>;
+}
+
+type RedisStreamHandlerContext = {
+    service: string;
+    emit: (ev: {
+        type: string;
+        data: Record<string, string | number | boolean | null>;
+    }) => Promise<void>;
+    log: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+        error: (msg: string) => void;
+    };
+};
+type RedisStreamEventHandler = {
+    type: string;
+    execute: (ev: Record<string, any>, ctx: RedisStreamHandlerContext) => Promise<void>;
+};
+declare function redisStreamHandler(type: string, fn: RedisStreamEventHandler["execute"]): RedisStreamEventHandler;
+
+type JwtStrategyClaims = {
+    sub?: string;
+    [key: string]: unknown;
+};
+type JwtTokenVerifier = (token: string, req: Request, route: RouteDefinition<any, any, boolean>) => JwtStrategyClaims | null | Promise<JwtStrategyClaims | null>;
+type CreateJwtAuthStrategyOptions = {
+    name?: string;
+    headerName?: string;
+    tokenPrefix?: string;
+    verifyToken: JwtTokenVerifier;
+    mapPayloadToUser?: (claims: JwtStrategyClaims, req: Request, route: RouteDefinition<any, any, boolean>) => AuthenticatedUser | null | Promise<AuthenticatedUser | null>;
+    canHandle?: AuthStrategy["canHandle"];
+};
+type CreateJoseJwtVerifierOptions = {
+    jwksUri?: string;
+    secret?: string | Uint8Array;
+    issuer?: string | string[];
+    audience?: string | string[];
+    algorithms?: string[];
+    clockTolerance?: string | number;
+    requiredClaims?: string[];
+};
+type CreateMtlsAuthStrategyOptions = {
+    name?: string;
+    requireAuthorized?: boolean;
+    mapCertificateToUser?: (certificate: PeerCertificate, req: Request, route: RouteDefinition<any, any, boolean>) => AuthenticatedUser | null | Promise<AuthenticatedUser | null>;
+    canHandle?: AuthStrategy["canHandle"];
+};
+declare function createJoseJwtVerifier(options: CreateJoseJwtVerifierOptions): JwtTokenVerifier;
+declare function createJwtAuthStrategy(options: CreateJwtAuthStrategyOptions): AuthStrategy;
+declare function createMtlsAuthStrategy(options?: CreateMtlsAuthStrategyOptions): AuthStrategy;
+
+export { type AuthResolver, type AuthStrategy, type AuthenticatedUser, type BaseExpressOptions, CollectionWrapper, type CreateJoseJwtVerifierOptions, type CreateJwtAuthStrategyOptions, type CreateMtlsAuthStrategyOptions, type CustomModuleFactory, type CustomModules, type ExpressMiddleware, type ExpressOptions, type ExpressOptionsWithCorsFn, type ExpressOptionsWithCorsWhitelist, type InferMongoCollections, type JwtStrategyClaims, type JwtTokenVerifier, type Message, type MongoBoundCollection, type MongoCollectionDefinition, type MongoCollectionMethodContext, type MongoCollectionMethods, type MongoCollectionsConfig, type MongoDatabase, type MongoIndexSpec, type RedisStreamEventHandler, type RedisStreamHandlerContext, type RouteDefinition, type RouteMeta, type SchemaParser, Service, type TypedRequest, type TypedRequestHandler, createAuthResolver, createJoseJwtVerifier, createJwtAuthStrategy, createMetaRouter, createMetaRouterWithAuth, createMongo, createMtlsAuthStrategy, defaultHeaderAuthResolver, defineMongoCollection, getRegisteredRoutes, redisStreamHandler };