alepha/server/cache.d.ts

Alepha is a convention-driven TypeScript framework for building robust, end-to-end type-safe applications, from serverless APIs to full-stack React apps.

import * as _alepha_cache0 from "alepha/cache";
import { CacheDescriptorOptions } from "alepha/cache";
import * as _alepha_core1 from "alepha";
import { Alepha } from "alepha";
import { DateTimeProvider, DurationLike } from "alepha/datetime";
import * as _alepha_logger0 from "alepha/logger";
import { RequestConfigSchema, ServerRequest, ServerRoute } from "alepha/server";

//#region src/providers/ServerCacheProvider.d.ts
declare module "alepha/server" {
  interface ServerRoute {
    /**
     * Enable caching for this route.
     * - If true: enables both store and etag
     * - If object: fine-grained control over store, etag, and cache-control headers
     *
     * @default false
     */
    cache?: ServerRouteCache;
  }
  interface ActionDescriptor<TConfig extends RequestConfigSchema> {
    invalidate: () => Promise<void>;
  }
}
declare class ServerCacheProvider {
  protected readonly log: _alepha_logger0.Logger;
  protected readonly alepha: Alepha;
  protected readonly time: DateTimeProvider;
  protected readonly cache: _alepha_cache0.CacheDescriptorFn<RouteCacheEntry, any[]>;
  generateETag(content: string): string;
  invalidate(route: ServerRoute): Promise<void>;
  protected readonly onActionRequest: _alepha_core1.HookDescriptor<"action:onRequest">;
  protected readonly onActionResponse: _alepha_core1.HookDescriptor<"action:onResponse">;
  protected readonly onRequest: _alepha_core1.HookDescriptor<"server:onRequest">;
  protected readonly onSend: _alepha_core1.HookDescriptor<"server:onSend">;
  protected readonly onResponse: _alepha_core1.HookDescriptor<"server:onResponse">;
  buildCacheControlHeader(cache?: ServerRouteCache): string | undefined;
  protected durationToSeconds(duration: number | DurationLike): number;
  protected shouldStore(cache?: ServerRouteCache): boolean;
  protected shouldUseEtag(cache?: ServerRouteCache): boolean;
  protected createCacheKey(route: ServerRoute, config?: ServerRequest): string;
}
type ServerRouteCache =
/**
 * If true, enables caching with:
 * - store: true
 * - etag: true
 */
boolean
/**
 * Object configuration for fine-grained cache control.
 *
 * If empty, no caching will be applied.
 */ | {
  /**
   * If true, enables storing cached responses. (in-memory, Redis, @see @alepha/cache for other providers)
   * If a DurationLike is provided, it will be used as the TTL for the cache.
   * If CacheDescriptorOptions is provided, it will be used to configure the cache storage.
   *
   * @default false
   */
  store?: true | DurationLike | CacheDescriptorOptions;
  /**
   * If true, enables ETag support for the cached responses.
   */
  etag?: true;
  /**
   * - If true, sets Cache-Control to "public, max-age=300" (5 minutes).
   * - If string, sets Cache-Control to the provided value directly.
   * - If object, configures Cache-Control directives.
   */
  control?: true
  /**
   * If string, sets Cache-Control to the provided value directly.
   */ | string
  /**
   * If object, configures Cache-Control directives.
   */ | {
    /**
     * Indicates that the response may be cached by any cache.
     */
    public?: boolean;
    /**
     * Indicates that the response is intended for a single user and must not be stored by a shared cache.
     */
    private?: boolean;
    /**
     * Forces caches to submit the request to the origin server for validation before releasing a cached copy.
     */
    noCache?: boolean;
    /**
     * Instructs caches not to store the response.
     */
    noStore?: boolean;
    /**
     * Maximum amount of time a resource is considered fresh.
     * Can be specified as a number (seconds) or as a DurationLike object.
     *
     * @example 300 // 5 minutes in seconds
     * @example { minutes: 5 } // 5 minutes
     * @example { hours: 1 } // 1 hour
     */
    maxAge?: number | DurationLike;
    /**
     * Overrides max-age for shared caches (e.g., CDNs).
     * Can be specified as a number (seconds) or as a DurationLike object.
     */
    sMaxAge?: number | DurationLike;
    /**
     * Indicates that once a resource becomes stale, caches must not use it without successful validation.
     */
    mustRevalidate?: boolean;
    /**
     * Similar to must-revalidate, but only for shared caches.
     */
    proxyRevalidate?: boolean;
    /**
     * Indicates that the response can be stored but must be revalidated before each use.
     */
    immutable?: boolean;
  };
};
interface RouteCacheEntry {
  contentType?: string;
  body: any;
  status?: number;
  lastModified: string;
  hash: string;
}
//#endregion
//#region src/index.d.ts
/**
 * Plugin for Alepha Server that provides server-side caching capabilities.
 * It uses the Alepha Cache module to cache responses from server actions ($action).
 * It also provides a ETag-based cache invalidation mechanism.
 *
 * @example
 * ```ts
 * import { Alepha } from "alepha";
 * import { $action } from "alepha/server";
 * import { AlephaServerCache } from "alepha/server/cache";
 *
 * class ApiServer {
 *   hello = $action({
 *     cache: true,
 *     handler: () => "Hello, World!",
 *   });
 * }
 *
 * const alepha = Alepha.create()
 *   .with(AlephaServerCache)
 *   .with(ApiServer);
 *
 * run(alepha);
 * ```
 *
 * @see {@link ServerCacheProvider}
 * @module alepha.server.cache
 */
declare const AlephaServerCache: _alepha_core1.Service<_alepha_core1.Module<{}>>;
//#endregion
export { AlephaServerCache, ServerCacheProvider, ServerRouteCache };
//# sourceMappingURL=index.d.ts.map