balda 0.0.41 → 0.0.43

package/lib/index.d.cts

@@ -1,4 +1,5 @@
 import { TSchema, Static } from '@sinclair/typebox';
+import { JSONSchema as JSONSchema$1, FromSchema } from 'json-schema-to-ts';
 import { ZodType, z } from 'zod';
 import { Ajv } from 'ajv';
 import { IncomingMessage, ServerResponse, Server as Server$2 } from 'node:http';
@@ -11,6 +12,7 @@ import { RequestHandler, Router as Router$1, IRouter } from 'express';
 import * as pino from 'pino';
 import pino__default, { pino as pino$1, Logger } from 'pino';
 import { glob } from 'node:fs/promises';
+import cronstrueType from 'cronstrue';
 import { IClientSubscribeOptions, IClientOptions, IClientPublishOptions, MqttClient } from 'mqtt';
 import { SQSClientConfig, SendMessageCommandInput } from '@aws-sdk/client-sqs';
 import { Queue, JobsOptions, Job } from 'bullmq';
@@ -23,7 +25,7 @@ type AjvInstance = InstanceType<typeof Ajv>;
 type AjvCompileParams = Parameters<AjvInstance["compile"]>;
 
 type RequestSchema = ZodType | TSchema | AjvCompileParams[0];
-type ValidatedData<T extends RequestSchema> = T extends ZodType ? z.infer<T> : T extends TSchema ? Static<T> : T extends AjvCompileParams[0] ? unknown : unknown;
+type ValidatedData<T extends RequestSchema> = T extends ZodType ? z.infer<T> : T extends TSchema ? Static<T> : T extends JSONSchema$1 ? JSONSchema$1 extends T ? Record<string, unknown> : FromSchema<T> : unknown;
 interface CustomValidationError {
     status?: number;
     message?: string;
@@ -60,7 +62,7 @@ type ExtractParams<T extends string> = T extends `${infer _Start}:${infer Param}
 /**
  * Helper type to infer the output type from a Zod schema, TypeBox schema, or any schema with _output
  */
-type InferSchemaType<T> = T extends ZodType ? z.infer<T> : T extends TSchema ? Static<T> : any;
+type InferSchemaType<T> = T extends ZodType ? z.infer<T> : T extends TSchema ? Static<T> : T extends JSONSchema$1 ? JSONSchema$1 extends T ? Record<string, unknown> : FromSchema<T> : any;
 /**
  * Maps a responses object (e.g. { 200: ZodSchema, 404: TypeBoxSchema }) to
  * an inferred type map (e.g. { 200: InferredType200, 404: InferredType404 }).
@@ -249,11 +251,27 @@ declare class Request<Params extends Record<string, string> = any, TBody = unkno
      * If body parser middleware is not used, this will be undefined.
      *
      * Type is `unknown` by default to enforce validation or casting before use.
+     * The body type is automatically inferred from the schema provided in the route options or decorator,
+     * supporting Zod (`z.infer<T>`), TypeBox (`Static<T>`), and plain JSON schemas (`FromSchema<T>` — requires `as const`).
      * @imperative while using router directly, when using body property, the type is inferred from the schema provided in the route options.
-     * @example
+     * @example Zod schema
      * ```typescript
      * router.post("/", { body: z.object({ name: z.string() }) }, async (req, res) => {
-     *   return res.json({ name: req.body.name });
+     *   return res.json({ name: req.body.name }); // req.body typed as { name: string }
+     * });
+     * ```
+     * @example TypeBox schema
+     * ```typescript
+     * import { Type } from "@sinclair/typebox";
+     * router.post("/", { body: Type.Object({ name: Type.String() }) }, async (req, res) => {
+     *   return res.json({ name: req.body.name }); // req.body typed as { name: string }
+     * });
+     * ```
+     * @example Plain JSON schema — `as const` is required for type inference
+     * ```typescript
+     * const bodySchema = { type: "object", properties: { name: { type: "string" } }, required: ["name"] } as const;
+     * router.post("/", { body: bodySchema }, async (req, res) => {
+     *   return res.json({ name: req.body.name }); // req.body typed as { name: string }
      * });
      * ```
      * @decorator When using the validate decorator, the validated data is appended to the function parameters.
@@ -1579,37 +1597,37 @@ declare class Router {
      * Register a GET route under this router's base path with type-safe path parameters.
      */
     get<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    get<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery>): void;
+    get<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll>): void;
     /**
      * Register a POST route under this router's base path with type-safe path parameters.
      */
     post<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    post<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery>): void;
+    post<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll>): void;
     /**
      * Register a PATCH route under this router's base path with type-safe path parameters.
      */
     patch<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    patch<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery>): void;
+    patch<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll>): void;
     /**
      * Register a PUT route under this router's base path with type-safe path parameters.
      */
     put<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    put<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery>): void;
+    put<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll>): void;
     /**
      * Register a DELETE route under this router's base path with type-safe path parameters.
      */
     delete<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    delete<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery>): void;
+    delete<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll>): void;
     /**
      * Register an OPTIONS route under this router's base path with type-safe path parameters.
      */
     options<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    options<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery>): void;
+    options<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll>): void;
     /**
      * Register an HEAD route under this router's base path with type-safe path parameters.
      */
     head<TPath extends string = string>(path: TPath, handler: ControllerHandler<TPath>): void;
-    head<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery>): void;
+    head<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | undefined = undefined, TQuery extends RequestSchema | undefined = undefined, TAll extends RequestSchema | undefined = undefined>(path: TPath, options: StandardMethodOptions<TResponses, TBody, TQuery, TPath, TAll>, handler: ControllerHandler<TPath, TResponses, TBody, TQuery, TAll>): void;
     /**
      * Create a grouped router that shares a base path and middlewares.
      * The callback receives a child router where routes are defined; routes
@@ -1669,74 +1687,6 @@ interface Route {
  */
 type ClientRouter = Omit<Router, "applyGlobalMiddlewaresToAllRoutes" | "addOrUpdate">;
 
-/**
- * Core cache service implementation wrapping a CacheProvider.
- *
- * Handles all cache operations including:
- * - Get/Set with optional compression
- * - Tag-based invalidation
- * - Pattern-based invalidation
- * - Thundering herd protection (lock acquisition)
- * - Statistics tracking
- */
-declare class CacheService implements CacheServiceInterface {
-    private readonly log;
-    private readonly provider;
-    private readonly options;
-    private stats;
-    constructor(provider: CacheProvider, options: CachePluginOptionsResolved);
-    /**
-     * Get a cached value by key.
-     * Handles decompression if the entry was stored compressed.
-     */
-    get<T = unknown>(key: string): Promise<T | null>;
-    /**
-     * Set a cached value with optional compression and tag registration.
-     */
-    set(key: string, value: unknown, ttl: number, opts?: {
-        compressed?: boolean;
-        tags?: string[];
-    }): Promise<void>;
-    /**
-     * Invalidate all cache entries with any of the given tags.
-     */
-    invalidate(tags: string[]): Promise<number>;
-    /**
-     * Invalidate a specific cache key.
-     */
-    invalidateKey(key: string): Promise<boolean>;
-    /**
-     * Invalidate all keys matching a pattern.
-     */
-    invalidatePattern(pattern: string): Promise<number>;
-    /**
-     * Acquire a lock for thundering herd protection.
-     * @returns true if lock was acquired, false if already held
-     */
-    acquireLock(key: string): Promise<boolean>;
-    /**
-     * Release a lock after cache population.
-     */
-    releaseLock(key: string): Promise<void>;
-    /**
-     * Wait for cache to be populated by another request.
-     */
-    waitForCache<T>(key: string, timeoutMs: number): Promise<T | null>;
-    /**
-     * Get current cache statistics.
-     */
-    getStats(): CacheStats;
-    /**
-     * Get the underlying cache provider.
-     */
-    getProvider(): CacheProvider;
-    /**
-     * Disconnect the underlying provider.
-     */
-    disconnect(): Promise<void>;
-    private updateHitRate;
-}
-
 /**
  * The server class that is used to create and manage the server
  */
@@ -1768,9 +1718,6 @@ declare class Server<H extends NodeHttpClient = NodeHttpClient> implements Serve
     get host(): string;
     get routes(): Route[];
     get fs(): typeof nativeFs;
-    get cache(): CacheService;
-    hash(data: string): Promise<string>;
-    compareHash(hash: string, data: string): Promise<boolean>;
     getEnvironment(): Record<string, string>;
     tmpDir(...append: string[]): string;
     getNodeServer(): RuntimeServerMap<"node", H>;
@@ -1804,11 +1751,6 @@ declare class Server<H extends NodeHttpClient = NodeHttpClient> implements Serve
      * @returns A promise that resolves when the server is disconnected
      */
     disconnect(): Promise<void>;
-    configureHash(options: {
-        iterations?: number;
-        saltLength?: number;
-        keyLength?: number;
-    }): void;
     getMockServer(options?: Pick<ServerOptions, "controllerPatterns">): Promise<MockServer>;
     private importControllers;
     private applyPlugins;
@@ -1817,11 +1759,6 @@ declare class Server<H extends NodeHttpClient = NodeHttpClient> implements Serve
      * @internal
      */
     private bootstrap;
-    /**
-     * Initialize the cache service and embed it on the server instance.
-     * @internal
-     */
-    private initializeCache;
     /**
      * Handles not found routes by delegating to custom handler or default error response
      * Checks if the path exists for other methods and returns 405 if so
@@ -2324,6 +2261,7 @@ type ServerPlugin = {
     methodOverride?: MethodOverrideOptions;
     compression?: CompressionOptions;
     asyncLocalStorage?: AsyncLocalStorageContextSetters;
+    cache?: CachePluginOptions;
 };
 type NodeHttpClient = "http" | "http2" | "https" | "http2-secure";
 type ServerOptions<H extends NodeHttpClient = NodeHttpClient> = {
@@ -2404,27 +2342,6 @@ type ServerOptions<H extends NodeHttpClient = NodeHttpClient> = {
      * ```
      */
     abortSignal?: AbortSignal;
-    /**
-     * The cronUI options to apply to the server.
-     * By passing the "path" option, the UI will be enabled at the given path.
-     */
-    cronUI?: CronUIOptions;
-    /**
-     * Cache configuration for the server.
-     * When provided, enables the cache system and exposes it via `server.cache`.
-     *
-     * @example
-     * ```ts
-     * const server = new Server({
-     *   cache: { provider: 'memory', defaultTtl: 300 }
-     * });
-     * // or with Redis
-     * const server = new Server({
-     *   cache: { provider: 'redis', redis: { host: 'localhost', port: 6379 } }
-     * });
-     * ```
-     */
-    cache?: CachePluginOptions;
 } & (H extends "https" | "http2-secure" ? HttpsOptions<H> : {});
 /** Internal resolved server options with all required properties */
 type ResolvedServerOptions = {
@@ -2437,8 +2354,6 @@ type ResolvedServerOptions = {
     swagger: Parameters<typeof swagger>[0] | boolean;
     graphql?: GraphQLOptions;
     abortSignal?: AbortSignal;
-    cronUI?: CronUIOptions;
-    cache?: CachePluginOptions;
 };
 type ServerErrorHandler = (req: Request, res: Response$1, next: NextFunction, error: Error) => SyncOrAsync;
 interface ServerInterface {
@@ -2479,19 +2394,6 @@ interface ServerInterface {
      * Main singleton router instance of the server
      */
     router: ClientRouter;
-    /**
-     * Hash the given data using the native hash function of the current runtime
-     * @param data - The data to hash
-     * @returns The hashed data
-     */
-    hash: (data: string) => Promise<string>;
-    /**
-     * Compare the given data with the given hash using the native hash function of the current runtime
-     * @param hash - The hash to compare the data with
-     * @param data - The data to compare with the hash
-     * @returns Whether the data matches the hash
-     */
-    compareHash: (hash: string, data: string) => Promise<boolean>;
     /**
      * Get the environment variables of the server using the native environment variables of the current runtime
      */
@@ -2632,18 +2534,6 @@ interface ServerInterface {
      * Subsequent calls after the first will have no effect
      */
     disconnect: () => Promise<void>;
-    /**
-     * Configure hash settings for password hashing
-     * @param options - Hash configuration options
-     * @param options.iterations - Number of PBKDF2 iterations (default: 600,000)
-     * @param options.saltLength - Salt length in bytes (default: 16)
-     * @param options.keyLength - Key length in bits (default: 256)
-     */
-    configureHash: (options: {
-        iterations?: number;
-        saltLength?: number;
-        keyLength?: number;
-    }) => void;
     /**
      * Returns a mock server instance that can be used to test the server without starting it
      * It will import the controllers and apply the plugins to the mock server
@@ -2662,19 +2552,19 @@ interface ServerInterface {
      */
     exit: (code?: number) => void;
 }
-type StandardMethodOptions<TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | unknown = unknown, TQuery extends RequestSchema | unknown = unknown, TPath extends string = string> = {
+type StandardMethodOptions<TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | unknown = unknown, TQuery extends RequestSchema | unknown = unknown, TPath extends string = string, TAll extends RequestSchema | unknown = unknown> = {
     middlewares?: ServerRouteMiddleware[] | ServerRouteMiddleware;
     body?: TBody;
     query?: TQuery;
-    all?: RequestSchema;
+    all?: TAll;
     responses?: TResponses;
     swagger?: SwaggerRouteOptions;
-    /** Cache configuration for this route. Requires cache to be configured in ServerOptions. */
+    /** Cache configuration for this route. Requires cache to be initialized via initCacheService(). */
     cache?: TypedCacheRouteConfig<TBody, TQuery, TPath>;
 };
 type ServerHook = () => SyncOrAsync;
 type SignalEvent = Deno.Signal | NodeJS.Signals;
-type ControllerHandler<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | unknown = unknown, TQuery extends RequestSchema | unknown = unknown> = (req: Request<ExtractParams<TPath>, InferBodyType<TBody>, InferQueryType<TQuery> extends Record<string, any> ? InferQueryType<TQuery> : Record<string, unknown>>, res: Response$1<InferResponseMap<TResponses>>) => ServerHandlerReturnType;
+type ControllerHandler<TPath extends string = string, TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | unknown = unknown, TQuery extends RequestSchema | unknown = unknown, TAll extends RequestSchema | unknown = unknown> = (req: Request<ExtractParams<TPath>, TBody extends RequestSchema ? InferBodyType<TBody> : InferBodyType<TAll>, InferQueryType<TQuery> extends Record<string, any> ? InferQueryType<TQuery> : Record<string, unknown>>, res: Response$1<InferResponseMap<TResponses>>) => ServerHandlerReturnType;
 
 type RunTimeType = "bun" | "node" | "deno";
 
@@ -2833,6 +2723,22 @@ declare class CronService {
     static massiveImportCronJobs(cronJobPatterns: string[]): Promise<void>;
 }
 declare const setCronGlobalErrorHandler: (globalErrorHandler: (...args: Parameters<(typeof CronService)["globalErrorHandler"]>) => void) => void;
+declare const cronUi: (cronUIOptions?: CronUIOptions) => Promise<void>;
+
+declare class CronUI {
+    static cronstrue: {
+        default: typeof cronstrueType;
+    } | null;
+    static getCronstrue(): Promise<{
+        default: typeof cronstrueType;
+    }>;
+    /**
+     * Generates an HTML UI displaying cron jobs in a modern dashboard style
+     */
+    generate(): Promise<string>;
+    private escapeHtml;
+}
+declare const cronUIInstance: CronUI;
 
 interface MqttTopics {
 }
@@ -4396,6 +4302,128 @@ declare class PolicyManager<T extends Record<string, PolicyProvider>> {
 
 declare const createPolicyDecorator: <T extends Record<string, PolicyProvider>>(manager: PolicyManager<T>) => PolicyDecorator<T>;
 
+/**
+ * Core cache service implementation wrapping a CacheProvider.
+ *
+ * Handles all cache operations including:
+ * - Get/Set with optional compression
+ * - Tag-based invalidation
+ * - Pattern-based invalidation
+ * - Thundering herd protection (lock acquisition)
+ * - Statistics tracking
+ */
+declare class CacheService implements CacheServiceInterface {
+    private readonly log;
+    private readonly provider;
+    private readonly options;
+    private stats;
+    constructor(provider: CacheProvider, options: CachePluginOptionsResolved);
+    /**
+     * Get a cached value by key.
+     * Handles decompression if the entry was stored compressed.
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Set a cached value with optional compression and tag registration.
+     */
+    set(key: string, value: unknown, ttl: number, opts?: {
+        compressed?: boolean;
+        tags?: string[];
+    }): Promise<void>;
+    /**
+     * Invalidate all cache entries with any of the given tags.
+     */
+    invalidate(tags: string[]): Promise<number>;
+    /**
+     * Invalidate a specific cache key.
+     */
+    invalidateKey(key: string): Promise<boolean>;
+    /**
+     * Invalidate all keys matching a pattern.
+     */
+    invalidatePattern(pattern: string): Promise<number>;
+    /**
+     * Acquire a lock for thundering herd protection.
+     * @returns true if lock was acquired, false if already held
+     */
+    acquireLock(key: string): Promise<boolean>;
+    /**
+     * Release a lock after cache population.
+     */
+    releaseLock(key: string): Promise<void>;
+    /**
+     * Wait for cache to be populated by another request.
+     */
+    waitForCache<T>(key: string, timeoutMs: number): Promise<T | null>;
+    /**
+     * Get current cache statistics.
+     */
+    getStats(): CacheStats;
+    /**
+     * Get the underlying cache provider.
+     */
+    getProvider(): CacheProvider;
+    /**
+     * Disconnect the underlying provider.
+     */
+    disconnect(): Promise<void>;
+    private updateHitRate;
+}
+
+/**
+ * Initialize the global cache service with a provider and options.
+ * Called during server bootstrap when `cache` is configured in ServerOptions.
+ * @internal
+ */
+declare function initCacheService(provider: CacheProvider, options: CachePluginOptionsResolved): CacheService;
+/**
+ * Get the global cache service instance.
+ * Returns null if cache has not been configured.
+ */
+declare function getCacheService(): CacheService | null;
+/**
+ * Reset the global cache service (for testing).
+ * @internal
+ */
+declare function resetCacheService(): void;
+
+/**
+ * Options for the cache middleware.
+ * Accepts the same configuration as CachePluginOptions but without provider/redis
+ * since the provider is passed directly as the first argument.
+ */
+type CacheMiddlewareOptions = Omit<CachePluginOptions, "provider" | "redis">;
+/**
+ * Creates a cache middleware that initializes the global CacheService.
+ *
+ * Use with `server.use()` to enable caching across your application.
+ * The `@cache()` decorator and `getCacheService()` will use the initialized service.
+ *
+ * @param provider - The cache provider instance (e.g. `new MemoryCacheProvider()` or `new RedisCacheProvider(...)`)
+ * @param options - Optional cache configuration (defaults are applied automatically)
+ * @returns A middleware compatible with `server.use()`
+ *
+ * @example
+ * ```typescript
+ * import { Server, cacheMiddleware, MemoryCacheProvider } from 'balda';
+ *
+ * const server = new Server({ port: 3000 });
+ * server.use(cacheMiddleware(new MemoryCacheProvider()));
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { Server, cacheMiddleware, RedisCacheProvider } from 'balda';
+ *
+ * const server = new Server({ port: 3000 });
+ * server.use(cacheMiddleware(new RedisCacheProvider({ host: 'localhost' }), {
+ *   defaultTtl: 600,
+ *   enableStats: true,
+ * }));
+ * ```
+ */
+declare function cacheMiddleware(provider: CacheProvider, options?: CacheMiddlewareOptions): ServerRouteMiddleware;
+
 /**
  * In-memory cache provider using Map with TTL expiration.
  * Suitable for development, testing, and single-instance deployments.
@@ -4438,6 +4466,10 @@ declare class RedisCacheProvider implements CacheProvider {
     disconnect(): Promise<void>;
 }
 
+/**
+ * Default cache plugin options.
+ */
+declare const DEFAULT_CACHE_OPTIONS: CachePluginOptionsResolved;
 /**
  * Response header name for cache status.
  */
@@ -4457,4 +4489,4 @@ declare enum CacheStatus {
  */
 declare const router: ClientRouter;
 
-export { type AsyncLocalStorageContextSetters, AzureBlobStorageProvider, BaseCron, BasePlugin, type BaseStorageProviderOptions, type BlobStorageProviderOptions, BullMQConfiguration, type BullMQConfigurationOptions, BullMQPubSub, CACHE_STATUS_HEADER, type CacheKeyIncludes, type CachePluginOptions, type CacheProvider, type CacheRedisOptions, type CacheRouteConfig, CacheService, type CacheServiceInterface, type CacheStats, CacheStatus, Command, type CommandOptions, CommandRegistry, type CompressionOptions, type CookieMiddlewareOptions, type CorsOptions, type CronSchedule, type CronScheduleParams, CronService, type CronUIOptions, CustomAdapter, type CustomQueueConfiguration, type CustomStorageProviderOptions, CustomTypedQueue, type CustomValidationError, EdgeAdapter, EjsAdapter, type ExtractParams, GraphQL, type GraphQLContext, type GraphQLOptions, type GraphQLResolverFunction, type GraphQLResolverMap, type GraphQLResolverType, type GraphQLResolvers, type GraphQLSchemaInput, type GraphQLTypeDef, HandlebarsAdapter, type HelmetOptions, type HttpMethod, type HttpsOptions, type InferResponseMap, type InferSchemaType, LocalStorageProvider, type LocalStorageProviderOptions, type LockBehavior, type LogOptions, type LoggerOptions, type MailOptions, MailOptionsBuilder, MailProvider, type MailProviderInterface, Mailer, type MailerInterface, type MailerOptions, type MailerProviderOptions, MemoryCacheProvider, MemoryPubSub, type MethodOverrideOptions, MockResponse, MockServer, type MockServerOptions, type MqttConnectionOptions, type MqttHandler, type MqttPublishOptions, MqttService, type MqttSubscribeOptions, type MqttSubscription, type MqttTopics, MustacheAdapter, type NextFunction, type NodeHttpClient, type NodeServer as NodeHttpServerClient, PGBossConfiguration, type PGBossConfigurationOptions, PGBossPubSub, type PolicyDecorator, PolicyManager, type PolicyProvider, type PublishTopic, QueueManager, QueueService, type RateLimiterKeyOptions, RedisCacheProvider, Request, type RequestSchema, Response$1 as Response, type ResponseBodyForStatus, type RuntimeServer, S3StorageProvider, type S3StorageProviderOptions, SQSConfiguration, type SQSConfigurationOptions, SQSPubSub, type CacheMetrics as SchemaCacheMetrics, type SerializeOptions, Server, type ServerConnectInput, type ServerErrorHandler, type ServerHook, type ServerInterface, type ServerListenCallback, type ServerOptions, type ServerRouteHandler, type ServerRouteMiddleware, type ServerTapOptions, type SessionOptions, type SignalEvent, type StaticPluginOptions, Storage, type StorageInterface, type StorageOptions, type StorageProviderOptions, type TemplateMailOptions, type TimeoutOptions, type TrustProxyOptions, type TypedCacheKeyIncludes, type TypedCacheRouteConfig, type TypedHandler, TypedQueue, type TypedRouteMetadata, type ValidatedData, type ValidationOptions, arg, asyncLocalStorage, asyncStorage, bullmqQueue, cache, clearAllCaches as clearAllSchemaCaches, commandRegistry, compression, controller, cookie, cors, createExpressAdapter, createPolicyDecorator, createQueue, cron, Server as default, defineQueueConfiguration, del, expressHandler, expressMiddleware, flag, get, getCacheMetrics as getSchemaCacheMetrics, hash, helmet, log, logCacheMetrics as logSchemaCacheMetrics, logger, memoryQueue, methodOverride, middleware, mountExpressRouter, mqtt, patch, pgbossQueue, post, put, rateLimiter, router, serialize, serveStatic, session, setCronGlobalErrorHandler, setMqttGlobalErrorHandler, sqsQueue, timeout as timeoutMw, trustProxy, validate };
+export { type AsyncLocalStorageContextSetters, AzureBlobStorageProvider, BaseCron, BasePlugin, type BaseStorageProviderOptions, type BlobStorageProviderOptions, BullMQConfiguration, type BullMQConfigurationOptions, BullMQPubSub, CACHE_STATUS_HEADER, type CacheKeyIncludes, type CacheMiddlewareOptions, type CachePluginOptions, type CacheProvider, type CacheRedisOptions, type CacheRouteConfig, CacheService, type CacheServiceInterface, type CacheStats, CacheStatus, Command, type CommandOptions, CommandRegistry, type CompressionOptions, type CookieMiddlewareOptions, type CorsOptions, type CronSchedule, type CronScheduleParams, CronService, type CronUIOptions, CustomAdapter, type CustomQueueConfiguration, type CustomStorageProviderOptions, CustomTypedQueue, type CustomValidationError, DEFAULT_CACHE_OPTIONS, EdgeAdapter, EjsAdapter, type ExtractParams, GraphQL, type GraphQLContext, type GraphQLOptions, type GraphQLResolverFunction, type GraphQLResolverMap, type GraphQLResolverType, type GraphQLResolvers, type GraphQLSchemaInput, type GraphQLTypeDef, HandlebarsAdapter, type HelmetOptions, type HttpMethod, type HttpsOptions, type InferResponseMap, type InferSchemaType, LocalStorageProvider, type LocalStorageProviderOptions, type LockBehavior, type LogOptions, type LoggerOptions, type MailOptions, MailOptionsBuilder, MailProvider, type MailProviderInterface, Mailer, type MailerInterface, type MailerOptions, type MailerProviderOptions, MemoryCacheProvider, MemoryPubSub, type MethodOverrideOptions, MockResponse, MockServer, type MockServerOptions, type MqttConnectionOptions, type MqttHandler, type MqttPublishOptions, MqttService, type MqttSubscribeOptions, type MqttSubscription, type MqttTopics, MustacheAdapter, type NextFunction, type NodeHttpClient, type NodeServer as NodeHttpServerClient, PGBossConfiguration, type PGBossConfigurationOptions, PGBossPubSub, type PolicyDecorator, PolicyManager, type PolicyProvider, type PublishTopic, QueueManager, QueueService, type RateLimiterKeyOptions, RedisCacheProvider, Request, type RequestSchema, Response$1 as Response, type ResponseBodyForStatus, type RuntimeServer, S3StorageProvider, type S3StorageProviderOptions, SQSConfiguration, type SQSConfigurationOptions, SQSPubSub, type CacheMetrics as SchemaCacheMetrics, type SerializeOptions, Server, type ServerConnectInput, type ServerErrorHandler, type ServerHook, type ServerInterface, type ServerListenCallback, type ServerOptions, type ServerRouteHandler, type ServerRouteMiddleware, type ServerTapOptions, type SessionOptions, type SignalEvent, type StaticPluginOptions, Storage, type StorageInterface, type StorageOptions, type StorageProviderOptions, type TemplateMailOptions, type TimeoutOptions, type TrustProxyOptions, type TypedCacheKeyIncludes, type TypedCacheRouteConfig, type TypedHandler, TypedQueue, type TypedRouteMetadata, type ValidatedData, type ValidationOptions, arg, asyncLocalStorage, asyncStorage, bullmqQueue, cache, cacheMiddleware, clearAllCaches as clearAllSchemaCaches, commandRegistry, compression, controller, cookie, cors, createExpressAdapter, createPolicyDecorator, createQueue, cron, cronUIInstance, cronUi, Server as default, defineQueueConfiguration, del, expressHandler, expressMiddleware, flag, get, getCacheService, getCacheMetrics as getSchemaCacheMetrics, hash, helmet, initCacheService, log, logCacheMetrics as logSchemaCacheMetrics, logger, memoryQueue, methodOverride, middleware, mountExpressRouter, mqtt, patch, pgbossQueue, post, put, rateLimiter, resetCacheService, router, serialize, serveStatic, session, setCronGlobalErrorHandler, setMqttGlobalErrorHandler, sqsQueue, timeout as timeoutMw, trustProxy, validate };