balda 0.0.39 → 0.0.41

package/lib/index.d.cts

@@ -1,8 +1,8 @@
-import { schedule, TaskContext } from 'node-cron';
 import { TSchema, Static } from '@sinclair/typebox';
 import { ZodType, z } from 'zod';
 import { Ajv } from 'ajv';
 import { IncomingMessage, ServerResponse, Server as Server$2 } from 'node:http';
+import { schedule, TaskContext } from 'node-cron';
 import { Http2Server } from 'node:http2';
 import { Server as Server$1, ServerOptions as ServerOptions$1 } from 'node:https';
 import { ApolloServerOptions, BaseContext } from '@apollo/server';
@@ -19,103 +19,11 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { S3Client } from '@aws-sdk/client-s3';
 import { Transporter } from 'nodemailer';
 
-type CronSchedule = {
-    name: string;
-    args: Parameters<typeof schedule>;
-};
-type CronScheduleParams = Parameters<typeof schedule>;
-type CronUIOptions = {
-    path: string;
-};
-
-/**
- * Decorator to schedule a cron job. Must be applied to a class method. By default, the cron job will not overlap with other cron jobs of the same type.
- * ```ts
- * @cron('* * * * *', { timezone: 'Europe/Istanbul' })
- * async test() {
- *   console.log('test');
- * }
- * ```
- */
-declare const cron: (schedule: CronScheduleParams[0], options?: CronScheduleParams[2]) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
-
-type FlagType = "boolean" | "string" | "number" | "list";
-type InferFlagType<T extends FlagType> = T extends "boolean" ? boolean : T extends "string" ? string : T extends "number" ? number : T extends "list" ? string[] : never;
-type ArgOptions = {
-    /**
-     * The description of the argument.
-     */
-    description?: string;
-    /**
-     * Whether the argument is required.
-     * @default false
-     */
-    required?: boolean;
-    /**
-     * The default value of the argument.
-     */
-    defaultValue?: string;
-    /**
-     * A function to parse the argument value.
-     * @default The value is returned as is.
-     */
-    parse?: (value: string) => string;
-};
-type FlagOptions<T extends FlagType> = {
-    /**
-     * The description of the flag.
-     */
-    description?: string;
-    /**
-     * The type of the flag.
-     */
-    type: T;
-    /**
-     * The name of the flag.
-     * @default The name of the field.
-     */
-    name?: string;
-    /**
-     * The aliases of the flag.
-     */
-    aliases?: string[] | string;
-    /**
-     * The default value of the flag.
-     */
-    defaultValue?: InferFlagType<T>;
-    /**
-     * Whether the flag is required.
-     * @default false
-     */
-    required?: boolean;
-    /**
-     * A function to parse the flag value.
-     * @default The value is returned as is.
-     */
-    parse?: (value: any) => InferFlagType<T>;
-};
-
-/**
- * Decorator to mark a field of a command class as an argument.
- * @param options - The options for the argument.
- * @warning Arguments are evaluated in the order they are defined in the Command class.
- */
-declare const arg: (options: ArgOptions) => (target: any, propertyKey: string) => void;
-
-declare const flag: {
-    <T extends FlagType>(options: FlagOptions<T>): (target: any, propertyKey: string) => void;
-    boolean(options: Omit<FlagOptions<"boolean">, "type">): (target: any, propertyKey: string) => void;
-    string(options: Omit<FlagOptions<"string">, "type">): (target: any, propertyKey: string) => void;
-    number(options: Omit<FlagOptions<"number">, "type">): (target: any, propertyKey: string) => void;
-    list(options: Omit<FlagOptions<"list">, "type">): (target: any, propertyKey: string) => void;
-    array(options: Omit<FlagOptions<"list">, "type">): (target: any, propertyKey: string) => void;
-};
-
 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] ? any : any;
+type ValidatedData<T extends RequestSchema> = T extends ZodType ? z.infer<T> : T extends TSchema ? Static<T> : T extends AjvCompileParams[0] ? unknown : unknown;
 interface CustomValidationError {
     status?: number;
     message?: string;
@@ -141,192 +49,41 @@ interface ValidationOptions {
 }
 
 /**
- * Type of Swagger UI to use
- */
-type SwaggerUIType = "standard" | "rapidoc" | "scalar" | "elements" | "custom";
-type HTMLString = string;
-/**
- * Custom UI generator function that takes the spec URL and global options and returns HTML
- */
-type CustomUIGenerator = (specUrl: string, globalOptions: SwaggerGlobalOptions) => HTMLString;
-/**
- * Type of request body for a route
+ * Extracts parameter names from a path string and creates a typed object
+ * @example ExtractParams<"/users/:id/posts/:postId"> → { id: string; postId: string }
  */
-type SwaggerBodyType = "json" | "form-data" | "urlencoded";
+type ExtractParams<T extends string> = T extends `${infer _Start}:${infer Param}/${infer Rest}` ? {
+    [K in Param | keyof ExtractParams<Rest>]: string;
+} : T extends `${infer _Start}:${infer Param}` ? {
+    [K in Param]: string;
+} : Record<string, never>;
 /**
- * JSONSchema type for OpenAPI/AJV-compatible schemas
+ * Helper type to infer the output type from a Zod schema, TypeBox schema, or any schema with _output
  */
-type JSONSchema = {
-    $id?: string;
-    $schema?: string;
-    type?: string | string[];
-    properties?: Record<string, JSONSchema>;
-    items?: JSONSchema | JSONSchema[];
-    required?: string[];
-    enum?: any[];
-    allOf?: JSONSchema[];
-    oneOf?: JSONSchema[];
-    anyOf?: JSONSchema[];
-    not?: JSONSchema;
-    additionalProperties?: boolean | JSONSchema;
-    description?: string;
-    format?: string;
-    default?: any;
-    title?: string;
-    definitions?: Record<string, JSONSchema>;
-    [key: string]: any;
-};
+type InferSchemaType<T> = T extends ZodType ? z.infer<T> : T extends TSchema ? Static<T> : any;
 /**
- * Base options shared across all Swagger UI types
+ * Maps a responses object (e.g. { 200: ZodSchema, 404: TypeBoxSchema }) to
+ * an inferred type map (e.g. { 200: InferredType200, 404: InferredType404 }).
  */
-type SwaggerGlobalOptionsBase = {
-    /** The path to the swagger documentation, defaults to /docs for the UI and /docs/json for the raw json */
-    path?: string;
-    /** API title */
-    title?: string;
-    /** API description */
-    description?: string;
-    /** API version */
-    version?: string;
-    /** Server URLs */
-    servers?: string[];
-    /** Components (schemas, responses, parameters, etc.) */
-    components?: Record<string, any>;
-    /** Security schemes (OpenAPI 3.0 style) */
-    securitySchemes?: Record<string, Security>;
-    /** OpenID Connect configuration (discovery document) */
-    openIdConnect?: OpenIDConnectConfig;
-    /** API tags */
-    tags?: Record<string, any>;
-    /** Global security requirements */
-    security?: Security[];
-    /** External documentation */
-    externalDocs?: {
-        description?: string;
-        url: string;
-    };
-    /** Info object (detailed metadata) */
-    info?: {
-        title: string;
-        description?: string;
-        version: string;
-        termsOfService?: string;
-        contact?: {
-            name?: string;
-            url?: string;
-            email?: string;
-        };
-        license?: {
-            name: string;
-            url?: string;
-        };
-    };
-    /**
-     * OpenAPI models to be shown in the documentation. Must be valid OpenAPI/AJV JSONSchema objects.
-     */
-    models?: Record<string, JSONSchema> | JSONSchema[];
+type InferResponseMap<T extends Record<number, RequestSchema>> = {
+    [K in keyof T]: InferSchemaType<T[K]>;
 };
 /**
- * Global documentation options for the API (OpenAPI/Swagger style)
+ * Infers the typed body from a schema. Returns `unknown` if no schema is provided.
  */
-type SwaggerGlobalOptions = (SwaggerGlobalOptionsBase & {
-    /** Type of Swagger UI to use, one of 'standard', 'redoc', 'rapidoc', 'scalar', or 'elements'. Defaults to 'standard'. */
-    type?: Exclude<SwaggerUIType, "custom">;
-}) | (SwaggerGlobalOptionsBase & {
-    /** Type of Swagger UI to use. When set to 'custom', customUIGenerator is required. */
-    type: "custom";
-    /** Custom UI generator function. Required when type is 'custom'. Must return a string of HTML that uses the given specUrl. */
-    customUIGenerator: CustomUIGenerator;
-});
+type InferBodyType<T> = T extends RequestSchema ? ValidatedData<T> : unknown;
 /**
- * Route-specific documentation options (for individual endpoints)
+ * Infers the typed query from a schema. Returns `Record<string, string>` if no schema is provided.
  */
-type SwaggerRouteOptions<TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>> = {
-    /** Service category where the route belongs to */
-    service?: string;
-    /** Name of the route */
-    name?: string;
-    /** Responses for this route */
-    responses?: TResponses;
-    /** Errors for this route */
-    errors?: Record<number, RequestSchema>;
-    /** Security requirements for this route */
-    security?: Security[] | Security;
-    /** Description of the route */
-    description?: string;
-    /** Deprecated flag */
-    deprecated?: boolean;
-    /** Exclude from swagger */
-    excludeFromSwagger?: boolean;
-    /**
-     * The request body type for this route. Allowed values: 'json', 'form-data', 'urlencoded'. Defaults to 'json'.
-     */
-    bodyType?: SwaggerBodyType;
-};
-type OAuth2Flows = {
-    implicit?: OAuth2Flow;
-    authorizationCode?: OAuth2Flow;
-    clientCredentials?: OAuth2Flow;
-    password?: OAuth2Flow;
-};
-type OAuth2Flow = {
-    authorizationUrl?: string;
-    tokenUrl?: string;
-    refreshUrl?: string;
-    scopes: Record<string, string>;
-};
-type OpenIDConnectConfig = {
-    issuer: string;
-    authorizationEndpoint: string;
-    tokenEndpoint: string;
-    userinfoEndpoint?: string;
-    jwksUri: string;
-    endSessionEndpoint?: string;
-    introspectionEndpoint?: string;
-    revocationEndpoint?: string;
-    scopesSupported?: string[];
-    responseTypesSupported?: string[];
-    grantTypesSupported?: string[];
-    tokenEndpointAuthMethodsSupported?: string[];
-    subjectTypesSupported?: string[];
-    idTokenSigningAlgValuesSupported?: string[];
-    claimsSupported?: string[];
-    codeChallengeMethodsSupported?: string[];
-};
-type Security = BearerOptions | ApiKeyOptions | OAuth2Options | OpenIdConnectOptions;
-type BearerOptions = {
-    type: "bearer";
-    bearerFormat?: string;
-    description?: string;
-};
-type ApiKeyOptions = {
-    type: "apiKey";
-    name: string;
-    in: "header" | "query" | "cookie";
-    description?: string;
-};
-type OAuth2Options = {
-    type: "oauth2";
-    flows: OAuth2Flows;
-    description?: string;
-    name?: string;
-};
-type OpenIdConnectOptions = {
-    type: "openIdConnect";
-    openIdConnectUrl: string;
-    description?: string;
-    name?: string;
-};
-
+type InferQueryType<T> = T extends RequestSchema ? ValidatedData<T> : Record<string, string>;
 /**
- * Decorator to mark a class as a controller, routes defined in the controller will be registered at import time when calling the `listen` method.
- * You can customize the path pattern for controller imports in the server options `controllerPatterns`
- * @param path - The path pattern for the controller.
- * @param swaggerOptions - The swagger options for the controller that will be applied to all routes defined in the controller. Controller options will override route options.
- * @swagger If swagger is enabled, the default service name for all routes defined in the controller will be the controller name.
- * @swagger For naming commodity, the default service name will remove the "Controller" suffix if it exists. e.g. "UserController" -> "User"
+ * Extracts the body type for a specific HTTP status code from a response map.
+ * When the status code has a schema defined, enforces exact type matching.
+ * Defaults to `any` when the status code is not present in the map.
  */
-declare const controller: (path?: string, swaggerOptions?: SwaggerRouteOptions) => (target: any) => void;
+type ResponseBodyForStatus<TMap, TStatus extends number> = TStatus extends keyof TMap ? 0 extends 1 & TMap[TStatus] ? any : {
+    [K in keyof TMap[TStatus]]: TMap[TStatus][K];
+} : any;
 
 type SyncOrAsync<T = void> = T | Promise<T>;
 
@@ -398,8 +155,10 @@ type FilePluginOptions = {
  * It also contains the validation methods.
  *
  * @template Params - The path parameters type (automatically extracted from route)
+ * @template TBody - The typed body (inferred from body schema when provided)
+ * @template TQuery - The typed query (inferred from query schema when provided)
  */
-declare class Request<Params extends Record<string, string> = any> {
+declare class Request<Params extends Record<string, string> = any, TBody = unknown, TQuery extends Record<string, any> = Record<string, string>> {
     #private;
     /**
      * Creates a new request object from a Web API Request object.
@@ -489,22 +248,24 @@ declare class Request<Params extends Record<string, string> = any> {
      * The parsed body of the request from the body parser middleware.
      * If body parser middleware is not used, this will be undefined.
      *
-     * Type is `unknown` to enforce validation before use.
-     * Use validation methods or decorators to get typed body:
-     * - `req.validate(schema)` - Validates and returns typed body
-     * - `@validate.body(schema)` - Decorator for automatic validation
-     *
+     * Type is `unknown` by default to enforce validation or casting before use.
+     * @imperative while using router directly, when using body property, the type is inferred from the schema provided in the route options.
      * @example
+     * ```typescript
+     * router.post("/", { body: z.object({ name: z.string() }) }, async (req, res) => {
+     *   return res.json({ name: req.body.name });
+     * });
+     * ```
+     * @decorator When using the validate decorator, the validated data is appended to the function parameters.
      * ```ts
-     * // With validation
-     * const validBody = req.validate(mySchema);
-     * // Now validBody is properly typed
-     *
-     * // Without validation (not recommended)
-     * const unsafeBody = req.body as MyType; // Requires type assertion
+     * @post("/")
+     * @validate.body(z.object({ name: z.string() }))
+     * async createUser(req: Request, res: Response, body: z.infer<typeof z.object({ name: z.string() })>) {
+     *   return res.json({ name: body.name });
+     * }
      * ```
      */
-    body: unknown;
+    body: TBody;
     /**
      * Flag indicating if the body has been read/parsed
      */
@@ -616,25 +377,11 @@ declare class Request<Params extends Record<string, string> = any> {
      *
      * ## Type Safety
      *
-     * Query values are **untyped strings**. For type-safe query parameters:
-     * - Use `req.validateQuery(schema)` for runtime validation
-     * - Use `@validate.query(schema)` decorator for automatic validation
-     *
-     * @example
-     * ```ts
-     * // Basic usage
-     * req.query.name // string | undefined
-     *
-     * // With validation for type safety
-     * const validated = req.validateQuery(z.object({
-     *   page: z.coerce.number(),
-     *   limit: z.coerce.number(),
-     * }));
-     * validated.page // number
-     * ```
+     * When a `query` schema is provided in route options, the type is automatically
+     * inferred from the schema.
      */
-    get query(): Record<string, string>;
-    set query(value: Record<string, string>);
+    get query(): TQuery;
+    set query(value: TQuery);
     /**
      * Set the raw query string (called by server implementations)
      * @internal
@@ -658,19 +405,564 @@ declare class Request<Params extends Record<string, string> = any> {
      */
     validateQuery<T extends RequestSchema>(inputSchema: T, throwErrorOnValidationFail?: boolean): ValidatedData<T>;
     /**
-     * Validates the body and query string of the request.
-     * @param inputSchema - The schema to validate against (Zod schema or JSON Schema).
-     * @param throwErrorOnValidationFail - If true, throws ValidationError on validation failure. If false, returns the original data.
+     * Validates the body and query string of the request.
+     * @param inputSchema - The schema to validate against (Zod schema or JSON Schema).
+     * @param throwErrorOnValidationFail - If true, throws ValidationError on validation failure. If false, returns the original data.
+     */
+    validateAll<T extends RequestSchema>(inputSchema: T, throwErrorOnValidationFail?: boolean): ValidatedData<T>;
+    /**
+     * Sets the Node.js IncomingMessage for lazy body reading.
+     * Used internally by the Node.js server implementation.
+     * @param req - The Node.js IncomingMessage
+     * @internal
+     */
+    setNodeRequest(req: IncomingMessage): void;
+}
+
+/**
+ * Behavior when cache lock cannot be acquired (thundering herd protection).
+ * - `wait`: Poll for cache until timeout, then execute handler (default)
+ * - `bypass`: Execute handler immediately without waiting
+ * - `fail`: Return 503 Service Unavailable immediately
+ */
+type LockBehavior = "wait" | "bypass" | "fail";
+/**
+ * Specifies which request data to include in the cache key.
+ * - `true`: include all fields
+ * - `string[]`: include only the specified field names
+ *
+ * Params from the URL path are always included automatically.
+ */
+interface CacheKeyIncludes {
+    /** Include request body fields in cache key */
+    body?: boolean | string[];
+    /** Include query string fields in cache key */
+    query?: boolean | string[];
+    /** Include request headers in cache key */
+    headers?: boolean | string[];
+    /**
+     * Custom discriminator function. The return value is hashed and appended to
+     * the cache key, allowing arbitrary request data (e.g. auth context, tenant)
+     * to be used as a cache dimension.
+     *
+     * @example
+     * include: { fromRequest: (req) => req.headers.get("x-tenant-id") }
+     */
+    fromRequest?: (req: Request) => SyncOrAsync<unknown>;
+}
+/**
+ * Type-safe cache key includes when schemas are available (router inline config).
+ * Allows picking specific fields from body/query schemas.
+ * `fromRequest` receives a fully-typed Request so body and query fields are inferred.
+ */
+type TypedCacheKeyIncludes<TBody extends RequestSchema | unknown = unknown, TQuery extends RequestSchema | unknown = unknown, TPath extends string = string> = {
+    body?: TBody extends RequestSchema ? boolean | (keyof InferSchemaType<TBody>)[] : boolean | string[];
+    query?: TQuery extends RequestSchema ? boolean | (keyof InferSchemaType<TQuery>)[] : boolean | string[];
+    headers?: boolean | string[];
+    /**
+     * Custom discriminator function. Receives the fully-typed request and must
+     * return a value that is hashed into the cache key.
+     *
+     * @example
+     * include: { fromRequest: (req) => req.body.tenantId }
+     */
+    fromRequest?: (req: Request<ExtractParams<TPath>, InferBodyType<TBody>, InferQueryType<TQuery> extends Record<string, any> ? InferQueryType<TQuery> : Record<string, unknown>>) => SyncOrAsync<unknown>;
+};
+/**
+ * Cache configuration for a route.
+ *
+ * @example
+ * ```typescript
+ * // Decorator usage
+ * @cache({ ttl: 60, tags: ['chat-messages'] })
+ *
+ * // Inline router usage
+ * router.get('/users', {
+ *   cache: { ttl: 120, include: { query: ['page', 'limit'] } }
+ * }, handler)
+ * ```
+ */
+interface CacheRouteConfig {
+    /** Time-to-live in seconds (max 86400 = 24 hours) */
+    ttl: number;
+    /** Enable gzip compression for responses larger than compressionThreshold */
+    useCompression?: boolean;
+    /** Tags for bulk invalidation via server.cache.invalidate(tags) */
+    tags?: string[];
+    /** Behavior when lock cannot be acquired (default: 'wait') */
+    lockBehavior?: LockBehavior;
+    /**
+     * Specifies which request data to include in the cache key.
+     * Params are always included automatically.
+     * When omitted, body is included by default for backward compatibility.
+     */
+    include?: CacheKeyIncludes;
+}
+/**
+ * Type-safe cache route config for inline router usage with schema inference.
+ */
+type TypedCacheRouteConfig<TBody extends RequestSchema | unknown = unknown, TQuery extends RequestSchema | unknown = unknown, TPath extends string = string> = Omit<CacheRouteConfig, "include"> & {
+    include?: TypedCacheKeyIncludes<TBody, TQuery, TPath>;
+};
+/**
+ * Cache statistics for monitoring.
+ */
+interface CacheStats {
+    /** Total cache hits */
+    hits: number;
+    /** Total cache misses */
+    misses: number;
+    /** Hit rate (0.0 - 1.0) */
+    hitRate: number;
+    /** Total keys invalidated */
+    invalidations: number;
+}
+/**
+ * Cache service interface exposed on the server instance.
+ *
+ * Access via `server.cache` after cache is configured in server options.
+ *
+ * @example
+ * ```typescript
+ * // Get cached value
+ * const data = await server.cache.get<UserData>('cache:user:123:/api/users:abc')
+ *
+ * // Invalidate by tags
+ * await server.cache.invalidate(['user:123', 'chat-messages'])
+ *
+ * // Get stats
+ * const stats = server.cache.getStats()
+ * console.log(`Hit rate: ${(stats.hitRate * 100).toFixed(2)}%`)
+ * ```
+ */
+interface CacheServiceInterface {
+    /** Get a cached value by key */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /** Set a cached value */
+    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 (e.g., 'cache:user:123:*') */
+    invalidatePattern(pattern: string): Promise<number>;
+    /** Get cache statistics */
+    getStats(): CacheStats;
+}
+/**
+ * Options for configuring the cache system in ServerOptions.
+ */
+interface CachePluginOptions {
+    /**
+     * The cache provider to use.
+     * - `'memory'`: built-in in-memory cache (default)
+     * - `'redis'`: Redis-backed cache (requires ioredis peer dependency)
+     * - `CacheProvider`: custom provider instance
+     */
+    provider?: "memory" | "redis" | CacheProvider;
+    /** Redis connection options (only used when provider is 'redis') */
+    redis?: CacheRedisOptions;
+    /** Default TTL in seconds (default: 300) */
+    defaultTtl?: number;
+    /** Minimum response size in bytes to apply compression (default: 1024) */
+    compressionThreshold?: number;
+    /** Key prefix for all cache entries (default: 'cache') */
+    keyPrefix?: string;
+    /** Enable statistics tracking (default: true) */
+    enableStats?: boolean;
+    /** Lock timeout in milliseconds for thundering herd protection (default: 5000) */
+    lockTimeout?: number;
+    /** Default behavior when lock cannot be acquired (default: 'wait') */
+    lockBehavior?: LockBehavior;
+}
+/**
+ * Redis connection options for the Redis cache provider.
+ */
+interface CacheRedisOptions {
+    /** Redis host (default: 'localhost') */
+    host?: string;
+    /** Redis port (default: 6379) */
+    port?: number;
+    /** Redis password */
+    password?: string;
+    /** Redis database number (default: 0) */
+    db?: number;
+    /** Redis key prefix */
+    keyPrefix?: string;
+    /** Full Redis connection URL (overrides host/port/password/db) */
+    url?: string;
+}
+/**
+ * Internal resolved plugin options with defaults applied.
+ */
+interface CachePluginOptionsResolved {
+    defaultTtl: number;
+    compressionThreshold: number;
+    keyPrefix: string;
+    enableStats: boolean;
+    lockTimeout: number;
+    lockBehavior: LockBehavior;
+}
+/**
+ * Abstract cache provider interface.
+ * Implement this to create a custom cache backend.
+ *
+ * @example
+ * ```typescript
+ * class MyCustomProvider implements CacheProvider {
+ *   async get(key: string) { ... }
+ *   async set(key: string, value: string, ttlSeconds: number) { ... }
+ *   // ...
+ * }
+ *
+ * const server = new Server({
+ *   cache: { provider: new MyCustomProvider() }
+ * })
+ * ```
+ */
+interface CacheProvider {
+    /** Get a raw string value by key */
+    get(key: string): Promise<string | null>;
+    /** Set a raw string value with TTL in seconds */
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    /** Delete a single key, returns true if key existed */
+    del(key: string): Promise<boolean>;
+    /** Delete multiple keys, returns count of deleted keys */
+    delMany(keys: string[]): Promise<number>;
+    /** Add members to a set key with optional TTL */
+    addToSet(key: string, members: string[], ttlSeconds?: number): Promise<void>;
+    /** Get all members of a set */
+    getSetMembers(key: string): Promise<string[]>;
+    /** Acquire a lock (NX semantics), returns true if acquired */
+    acquireLock(key: string, ttlMs: number): Promise<boolean>;
+    /** Release a previously acquired lock */
+    releaseLock(key: string): Promise<void>;
+    /** Scan keys matching a glob pattern, yields batches */
+    scan(pattern: string): AsyncIterable<string[]>;
+    /** Disconnect and clean up resources */
+    disconnect(): Promise<void>;
+}
+
+/**
+ * Decorator to enable caching for a controller route handler.
+ *
+ * Stores cache configuration in MetadataStore, which is processed
+ * by the `@controller` decorator to inject cache middleware.
+ *
+ * **Note:** `include` field picks are not type-safe in decorators since
+ * the decorator doesn't have access to body/query schema types.
+ * Use the inline router config with schemas for type-safe picks.
+ *
+ * @param config - Cache configuration for the route
+ *
+ * @example
+ * ```typescript
+ * import { controller, get, cache } from "balda";
+ *
+ * @controller("/api/users")
+ * class UserController {
+ *   @get("/")
+ *   @cache({ ttl: 120 })
+ *   async listUsers(req, res) {
+ *     return await db.users.findAll();
+ *   }
+ *
+ *   @get("/:id")
+ *   @cache({
+ *     ttl: 60,
+ *     tags: ["users"],
+ *     include: { query: ["fields"] },
+ *   })
+ *   async getUser(req, res) {
+ *     return await db.users.findById(req.params.id);
+ *   }
+ * }
+ * ```
+ */
+declare const cache: (config: CacheRouteConfig) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+
+type CronSchedule = {
+    name: string;
+    args: Parameters<typeof schedule>;
+};
+type CronScheduleParams = Parameters<typeof schedule>;
+type CronUIOptions = {
+    path: string;
+};
+
+/**
+ * Decorator to schedule a cron job. Must be applied to a class method. By default, the cron job will not overlap with other cron jobs of the same type.
+ * ```ts
+ * @cron('* * * * *', { timezone: 'Europe/Istanbul' })
+ * async test() {
+ *   console.log('test');
+ * }
+ * ```
+ */
+declare const cron: (schedule: CronScheduleParams[0], options?: CronScheduleParams[2]) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+
+type FlagType = "boolean" | "string" | "number" | "list";
+type InferFlagType<T extends FlagType> = T extends "boolean" ? boolean : T extends "string" ? string : T extends "number" ? number : T extends "list" ? string[] : never;
+type ArgOptions = {
+    /**
+     * The description of the argument.
+     */
+    description?: string;
+    /**
+     * Whether the argument is required.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * The default value of the argument.
+     */
+    defaultValue?: string;
+    /**
+     * A function to parse the argument value.
+     * @default The value is returned as is.
+     */
+    parse?: (value: string) => string;
+};
+type FlagOptions<T extends FlagType> = {
+    /**
+     * The description of the flag.
+     */
+    description?: string;
+    /**
+     * The type of the flag.
+     */
+    type: T;
+    /**
+     * The name of the flag.
+     * @default The name of the field.
+     */
+    name?: string;
+    /**
+     * The aliases of the flag.
+     */
+    aliases?: string[] | string;
+    /**
+     * The default value of the flag.
+     */
+    defaultValue?: InferFlagType<T>;
+    /**
+     * Whether the flag is required.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * A function to parse the flag value.
+     * @default The value is returned as is.
+     */
+    parse?: (value: any) => InferFlagType<T>;
+};
+
+/**
+ * Decorator to mark a field of a command class as an argument.
+ * @param options - The options for the argument.
+ * @warning Arguments are evaluated in the order they are defined in the Command class.
+ */
+declare const arg: (options: ArgOptions) => (target: any, propertyKey: string) => void;
+
+declare const flag: {
+    <T extends FlagType>(options: FlagOptions<T>): (target: any, propertyKey: string) => void;
+    boolean(options: Omit<FlagOptions<"boolean">, "type">): (target: any, propertyKey: string) => void;
+    string(options: Omit<FlagOptions<"string">, "type">): (target: any, propertyKey: string) => void;
+    number(options: Omit<FlagOptions<"number">, "type">): (target: any, propertyKey: string) => void;
+    list(options: Omit<FlagOptions<"list">, "type">): (target: any, propertyKey: string) => void;
+    array(options: Omit<FlagOptions<"list">, "type">): (target: any, propertyKey: string) => void;
+};
+
+/**
+ * Type of Swagger UI to use
+ */
+type SwaggerUIType = "standard" | "rapidoc" | "scalar" | "elements" | "custom";
+type HTMLString = string;
+/**
+ * Custom UI generator function that takes the spec URL and global options and returns HTML
+ */
+type CustomUIGenerator = (specUrl: string, globalOptions: SwaggerGlobalOptions) => HTMLString;
+/**
+ * Type of request body for a route
+ */
+type SwaggerBodyType = "json" | "form-data" | "urlencoded";
+/**
+ * JSONSchema type for OpenAPI/AJV-compatible schemas
+ */
+type JSONSchema = {
+    $id?: string;
+    $schema?: string;
+    type?: string | string[];
+    properties?: Record<string, JSONSchema>;
+    items?: JSONSchema | JSONSchema[];
+    required?: string[];
+    enum?: any[];
+    allOf?: JSONSchema[];
+    oneOf?: JSONSchema[];
+    anyOf?: JSONSchema[];
+    not?: JSONSchema;
+    additionalProperties?: boolean | JSONSchema;
+    description?: string;
+    format?: string;
+    default?: any;
+    title?: string;
+    definitions?: Record<string, JSONSchema>;
+    [key: string]: any;
+};
+/**
+ * Base options shared across all Swagger UI types
+ */
+type SwaggerGlobalOptionsBase = {
+    /** The path to the swagger documentation, defaults to /docs for the UI and /docs/json for the raw json */
+    path?: string;
+    /** API title */
+    title?: string;
+    /** API description */
+    description?: string;
+    /** API version */
+    version?: string;
+    /** Server URLs */
+    servers?: string[];
+    /** Components (schemas, responses, parameters, etc.) */
+    components?: Record<string, any>;
+    /** Security schemes (OpenAPI 3.0 style) */
+    securitySchemes?: Record<string, Security>;
+    /** OpenID Connect configuration (discovery document) */
+    openIdConnect?: OpenIDConnectConfig;
+    /** API tags */
+    tags?: Record<string, any>;
+    /** Global security requirements */
+    security?: Security[];
+    /** External documentation */
+    externalDocs?: {
+        description?: string;
+        url: string;
+    };
+    /** Info object (detailed metadata) */
+    info?: {
+        title: string;
+        description?: string;
+        version: string;
+        termsOfService?: string;
+        contact?: {
+            name?: string;
+            url?: string;
+            email?: string;
+        };
+        license?: {
+            name: string;
+            url?: string;
+        };
+    };
+    /**
+     * OpenAPI models to be shown in the documentation. Must be valid OpenAPI/AJV JSONSchema objects.
      */
-    validateAll<T extends RequestSchema>(inputSchema: T, throwErrorOnValidationFail?: boolean): ValidatedData<T>;
+    models?: Record<string, JSONSchema> | JSONSchema[];
+};
+/**
+ * Global documentation options for the API (OpenAPI/Swagger style)
+ */
+type SwaggerGlobalOptions = (SwaggerGlobalOptionsBase & {
+    /** Type of Swagger UI to use, one of 'standard', 'redoc', 'rapidoc', 'scalar', or 'elements'. Defaults to 'standard'. */
+    type?: Exclude<SwaggerUIType, "custom">;
+}) | (SwaggerGlobalOptionsBase & {
+    /** Type of Swagger UI to use. When set to 'custom', customUIGenerator is required. */
+    type: "custom";
+    /** Custom UI generator function. Required when type is 'custom'. Must return a string of HTML that uses the given specUrl. */
+    customUIGenerator: CustomUIGenerator;
+});
+/**
+ * Route-specific documentation options (for individual endpoints)
+ */
+type SwaggerRouteOptions = {
+    /** Service category where the route belongs to */
+    service?: string;
+    /** Name of the route */
+    name?: string;
+    /** Responses for this route (used by decorators) */
+    responses?: Record<number, RequestSchema>;
+    /** Errors for this route */
+    errors?: Record<number, RequestSchema>;
+    /** Security requirements for this route */
+    security?: Security[] | Security;
+    /** Description of the route */
+    description?: string;
+    /** Deprecated flag */
+    deprecated?: boolean;
+    /** Exclude from swagger */
+    excludeFromSwagger?: boolean;
     /**
-     * Sets the Node.js IncomingMessage for lazy body reading.
-     * Used internally by the Node.js server implementation.
-     * @param req - The Node.js IncomingMessage
-     * @internal
+     * The request body type for this route. Allowed values: 'json', 'form-data', 'urlencoded'. Defaults to 'json'.
      */
-    setNodeRequest(req: IncomingMessage): void;
-}
+    bodyType?: SwaggerBodyType;
+};
+type OAuth2Flows = {
+    implicit?: OAuth2Flow;
+    authorizationCode?: OAuth2Flow;
+    clientCredentials?: OAuth2Flow;
+    password?: OAuth2Flow;
+};
+type OAuth2Flow = {
+    authorizationUrl?: string;
+    tokenUrl?: string;
+    refreshUrl?: string;
+    scopes: Record<string, string>;
+};
+type OpenIDConnectConfig = {
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    userinfoEndpoint?: string;
+    jwksUri: string;
+    endSessionEndpoint?: string;
+    introspectionEndpoint?: string;
+    revocationEndpoint?: string;
+    scopesSupported?: string[];
+    responseTypesSupported?: string[];
+    grantTypesSupported?: string[];
+    tokenEndpointAuthMethodsSupported?: string[];
+    subjectTypesSupported?: string[];
+    idTokenSigningAlgValuesSupported?: string[];
+    claimsSupported?: string[];
+    codeChallengeMethodsSupported?: string[];
+};
+type Security = BearerOptions | ApiKeyOptions | OAuth2Options | OpenIdConnectOptions;
+type BearerOptions = {
+    type: "bearer";
+    bearerFormat?: string;
+    description?: string;
+};
+type ApiKeyOptions = {
+    type: "apiKey";
+    name: string;
+    in: "header" | "query" | "cookie";
+    description?: string;
+};
+type OAuth2Options = {
+    type: "oauth2";
+    flows: OAuth2Flows;
+    description?: string;
+    name?: string;
+};
+type OpenIdConnectOptions = {
+    type: "openIdConnect";
+    openIdConnectUrl: string;
+    description?: string;
+    name?: string;
+};
+
+/**
+ * Decorator to mark a class as a controller, routes defined in the controller will be registered at import time when calling the `listen` method.
+ * You can customize the path pattern for controller imports in the server options `controllerPatterns`
+ * @param path - The path pattern for the controller.
+ * @param swaggerOptions - The swagger options for the controller that will be applied to all routes defined in the controller. Controller options will override route options.
+ * @swagger If swagger is enabled, the default service name for all routes defined in the controller will be the controller name.
+ * @swagger For naming commodity, the default service name will remove the "Controller" suffix if it exists. e.g. "UserController" -> "User"
+ */
+declare const controller: (path?: string, swaggerOptions?: SwaggerRouteOptions) => (target: any) => void;
 
 /**
  * Cookie options for setting cookies
@@ -747,35 +1039,9 @@ type CookieMiddlewareOptions = {
     sign?: boolean;
 };
 
-/**
- * Extracts parameter names from a path string and creates a typed object
- * @example ExtractParams<"/users/:id/posts/:postId"> → { id: string; postId: string }
- */
-type ExtractParams<T extends string> = T extends `${infer _Start}:${infer Param}/${infer Rest}` ? {
-    [K in Param | keyof ExtractParams<Rest>]: string;
-} : T extends `${infer _Start}:${infer Param}` ? {
-    [K in Param]: string;
-} : Record<string, never>;
-/**
- * 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;
-/**
- * Maps a responses object (e.g. { 200: ZodSchema, 404: TypeBoxSchema }) to
- * an inferred type map (e.g. { 200: InferredType200, 404: InferredType404 }).
- */
-type InferResponseMap<T extends Record<number, RequestSchema>> = {
-    [K in keyof T]: InferSchemaType<T[K]>;
-};
-/**
- * Extracts the body type for a specific HTTP status code from a response map.
- * Defaults to `any` when the status code is not present in the map.
- */
-type ResponseBodyForStatus<TMap, TStatus extends number> = TStatus extends keyof TMap ? TMap[TStatus] : any;
-
 /**
  * The response object with per-status-code type-safe response bodies.
- * When response schemas are provided (e.g. via swagger.responses), each shorthand
+ * When response schemas are provided (e.g. via the `responses` route option), each shorthand
  * method (ok, created, notFound, etc.) is typed to its corresponding status code schema.
  * @template TResponseMap - Maps HTTP status codes to their inferred body types (defaults to Record<number, any>)
  */
@@ -1291,7 +1557,7 @@ declare class Router {
         body?: RequestSchema;
         query?: RequestSchema;
         all?: RequestSchema;
-    }, swaggerOptions?: SwaggerRouteOptions): void;
+    }, swaggerOptions?: SwaggerRouteOptions, responses?: Record<number, RequestSchema>): void;
     /**
      * Find the matching route for the given HTTP method and path.
      * Returns the resolved middleware chain, handler, extracted params, and response schemas; or null if not found.
@@ -1313,37 +1579,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>>(path: TPath, options: StandardMethodOptions<TResponses>, handler: ControllerHandler<TPath, TResponses>): 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;
     /**
      * 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>>(path: TPath, options: StandardMethodOptions<TResponses>, handler: ControllerHandler<TPath, TResponses>): 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;
     /**
      * 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>>(path: TPath, options: StandardMethodOptions<TResponses>, handler: ControllerHandler<TPath, TResponses>): 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;
     /**
      * 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>>(path: TPath, options: StandardMethodOptions<TResponses>, handler: ControllerHandler<TPath, TResponses>): 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;
     /**
      * 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>>(path: TPath, options: StandardMethodOptions<TResponses>, handler: ControllerHandler<TPath, TResponses>): 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;
     /**
      * 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>>(path: TPath, options: StandardMethodOptions<TResponses>, handler: ControllerHandler<TPath, TResponses>): 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;
     /**
      * 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>>(path: TPath, options: StandardMethodOptions<TResponses>, handler: ControllerHandler<TPath, TResponses>): 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;
     /**
      * Create a grouped router that shares a base path and middlewares.
      * The callback receives a child router where routes are defined; routes
@@ -1379,7 +1645,12 @@ interface Route {
     handler: ServerRouteHandler;
     swaggerOptions?: SwaggerRouteOptions;
     /**
-     * Compiled response schemas from swagger.responses, indexed by status code.
+     * Response schemas from route options, indexed by status code.
+     * Used by swagger plugin for documentation and fast JSON serialization.
+     */
+    responses?: RouteResponseSchemas;
+    /**
+     * Compiled response schemas, indexed by status code.
      * Used for automatic fast JSON serialization in Response.json()
      */
     responseSchemas?: RouteResponseSchemas;
@@ -1398,6 +1669,74 @@ 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
  */
@@ -1429,6 +1768,7 @@ 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>;
@@ -1477,6 +1817,11 @@ 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
@@ -1496,7 +1841,7 @@ declare class Server<H extends NodeHttpClient = NodeHttpClient> implements Serve
 }
 
 declare class MockResponse<T = any> {
-    private readonly response;
+    readonly response: Response$1;
     constructor(response: Response$1);
     body(): T;
     statusCode(): number;
@@ -2064,6 +2409,22 @@ type ServerOptions<H extends NodeHttpClient = NodeHttpClient> = {
      * 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 = {
@@ -2077,6 +2438,7 @@ type ResolvedServerOptions = {
     graphql?: GraphQLOptions;
     abortSignal?: AbortSignal;
     cronUI?: CronUIOptions;
+    cache?: CachePluginOptions;
 };
 type ServerErrorHandler = (req: Request, res: Response$1, next: NextFunction, error: Error) => SyncOrAsync;
 interface ServerInterface {
@@ -2300,16 +2662,19 @@ interface ServerInterface {
      */
     exit: (code?: number) => void;
 }
-type StandardMethodOptions<TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>> = {
+type StandardMethodOptions<TResponses extends Record<number, RequestSchema> = Record<number, RequestSchema>, TBody extends RequestSchema | unknown = unknown, TQuery extends RequestSchema | unknown = unknown, TPath extends string = string> = {
     middlewares?: ServerRouteMiddleware[] | ServerRouteMiddleware;
-    body?: RequestSchema;
-    query?: RequestSchema;
+    body?: TBody;
+    query?: TQuery;
     all?: RequestSchema;
-    swagger?: SwaggerRouteOptions<TResponses>;
+    responses?: TResponses;
+    swagger?: SwaggerRouteOptions;
+    /** Cache configuration for this route. Requires cache to be configured in ServerOptions. */
+    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>> = (req: Request<ExtractParams<TPath>>, res: Response$1<InferResponseMap<TResponses>>, ...args: any[]) => 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> = (req: Request<ExtractParams<TPath>, InferBodyType<TBody>, InferQueryType<TQuery> extends Record<string, any> ? InferQueryType<TQuery> : Record<string, unknown>>, res: Response$1<InferResponseMap<TResponses>>) => ServerHandlerReturnType;
 
 type RunTimeType = "bun" | "node" | "deno";
 
@@ -4031,9 +4396,65 @@ declare class PolicyManager<T extends Record<string, PolicyProvider>> {
 
 declare const createPolicyDecorator: <T extends Record<string, PolicyProvider>>(manager: PolicyManager<T>) => PolicyDecorator<T>;
 
+/**
+ * In-memory cache provider using Map with TTL expiration.
+ * Suitable for development, testing, and single-instance deployments.
+ */
+declare class MemoryCacheProvider implements CacheProvider {
+    private store;
+    private sets;
+    private locks;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    del(key: string): Promise<boolean>;
+    delMany(keys: string[]): Promise<number>;
+    addToSet(key: string, members: string[], ttlSeconds?: number): Promise<void>;
+    getSetMembers(key: string): Promise<string[]>;
+    acquireLock(key: string, ttlMs: number): Promise<boolean>;
+    releaseLock(key: string): Promise<void>;
+    scan(pattern: string): AsyncIterable<string[]>;
+    disconnect(): Promise<void>;
+}
+
+/**
+ * Redis-backed cache provider using ioredis (dynamically imported).
+ * Requires `ioredis` as a peer dependency.
+ */
+declare class RedisCacheProvider implements CacheProvider {
+    private redis;
+    private options;
+    constructor(options?: CacheRedisOptions);
+    /** Lazily connect to Redis on first use */
+    private getClient;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    del(key: string): Promise<boolean>;
+    delMany(keys: string[]): Promise<number>;
+    addToSet(key: string, members: string[], ttlSeconds?: number): Promise<void>;
+    getSetMembers(key: string): Promise<string[]>;
+    acquireLock(key: string, ttlMs: number): Promise<boolean>;
+    releaseLock(key: string): Promise<void>;
+    scan(pattern: string): AsyncIterable<string[]>;
+    disconnect(): Promise<void>;
+}
+
+/**
+ * Response header name for cache status.
+ */
+declare const CACHE_STATUS_HEADER = "x-cache";
+/**
+ * Cache status values for response header.
+ */
+declare enum CacheStatus {
+    Hit = "HIT",
+    Miss = "MISS",
+    Wait = "WAIT",
+    Bypass = "BYPASS"
+}
+
 /**
  * Singleton main router instance that handles all route registrations inside the balda server
  */
 declare const router: ClientRouter;
 
-export { type AsyncLocalStorageContextSetters, AzureBlobStorageProvider, BaseCron, BasePlugin, type BaseStorageProviderOptions, type BlobStorageProviderOptions, BullMQConfiguration, type BullMQConfigurationOptions, BullMQPubSub, 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 LogOptions, type LoggerOptions, type MailOptions, MailOptionsBuilder, MailProvider, type MailProviderInterface, Mailer, type MailerInterface, type MailerOptions, type MailerProviderOptions, 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, 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 TypedHandler, TypedQueue, type TypedRouteMetadata, type ValidatedData, type ValidationOptions, arg, asyncLocalStorage, asyncStorage, bullmqQueue, 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 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 };