alepha/dist/cache/database/index.d.ts

Easy-to-use modern TypeScript framework for building many kind of applications.

import { Alepha, Static } from "alepha";
import { CacheProvider } from "alepha/cache";
import { DateTimeProvider } from "alepha/datetime";
//#region ../../src/cache/database/entities/cacheEntries.d.ts
/**
 * Storage table for the {@link DatabaseCacheProvider}.
 *
 * Each row represents one cache entry:
 * - `(container, cacheKey)` is the logical key (uniqueness enforced by index).
 * - `value` holds base64-encoded bytes for `set/get/setTyped/getTyped`.
 * - `count` holds an integer counter for atomic `incr` operations.
 * - `expiresAt` is null for entries that never expire, or a timestamp after
 *   which the entry is considered gone (filtered out at read time).
 */
declare const cacheEntries: import("alepha/orm").EntityPrimitive<import("zod").ZodObject<{
  id: import("alepha/orm").PgAttr<import("alepha/orm").PgAttr<import("zod").ZodString, typeof import("alepha/orm").PG_PRIMARY_KEY>, typeof import("alepha/orm").PG_DEFAULT>;
  createdAt: import("alepha/orm").PgAttr<import("alepha/orm").PgAttr<import("zod").ZodString, typeof import("alepha/orm").PG_CREATED_AT>, typeof import("alepha/orm").PG_DEFAULT>;
  container: import("zod").ZodString;
  cacheKey: import("zod").ZodString;
  value: import("zod").ZodOptional<import("zod").ZodString>;
  count: import("zod").ZodOptional<import("zod").ZodInt>;
  expiresAt: import("zod").ZodOptional<import("zod").ZodString>;
}, import("zod/v4/core").$strip>>;
type CacheEntry = Static<typeof cacheEntries.schema>;
//#endregion
//#region ../../src/cache/database/providers/DatabaseCacheProvider.d.ts
/**
 * Configuration atom for {@link DatabaseCacheProvider}.
 */
declare const databaseCacheOptions: import("alepha").Atom<import("zod").ZodObject<{
  sweepProbability: import("zod").ZodDefault<import("zod").ZodNumber>;
  sweepBatchSize: import("zod").ZodDefault<import("zod").ZodInt>;
}, import("zod/v4/core").$strip>, "alepha.cache.database.options">;
type DatabaseCacheOptions = Static<typeof databaseCacheOptions.schema>;
declare module "alepha" {
  interface State {
    [databaseCacheOptions.key]: DatabaseCacheOptions;
  }
}
/**
 * Cache provider backed by the application's SQL database.
 *
 * Uses the `cache_entries` table as a generic key/value store with optional
 * TTL. Works on every database supported by Alepha's ORM (Postgres, SQLite,
 * Cloudflare D1, Bun SQLite).
 *
 * **Why use this over Cloudflare KV / Redis ?**
 *
 * - You already have a SQL database, no extra resource to provision/secure.
 * - `incr()` is **atomic** through `INSERT ... ON CONFLICT DO UPDATE`.
 * - Reads/writes are **strongly consistent** (KV is eventually consistent).
 * - Phase-2 flows (registration, password reset) become transactional with
 *   the user-creation INSERT.
 *
 * **When to prefer Cloudflare KV / Redis instead ?**
 *
 * - Hot read paths where DB latency matters.
 * - Very high write rates where DB pressure becomes a concern.
 *
 * **Storage layout**
 *
 * - `value` column: base64-encoded bytes for `set/get/setTyped/getTyped`.
 * - `count` column: integer counter for atomic `incr()`.
 * - `expiresAt` column: nullable timestamp; expired rows are filtered at read
 *   time and reaped opportunistically on writes.
 *
 * @see {@link CacheProvider}
 */
declare class DatabaseCacheProvider extends CacheProvider {
  protected readonly log: import("alepha/logger").Logger;
  protected readonly alepha: Alepha;
  protected readonly dateTimeProvider: DateTimeProvider;
  protected readonly repository: import("alepha/orm").Repository<import("zod").ZodObject<{
    id: import("alepha/orm").PgAttr<import("alepha/orm").PgAttr<import("zod").ZodString, typeof import("alepha/orm").PG_PRIMARY_KEY>, typeof import("alepha/orm").PG_DEFAULT>;
    createdAt: import("alepha/orm").PgAttr<import("alepha/orm").PgAttr<import("zod").ZodString, typeof import("alepha/orm").PG_CREATED_AT>, typeof import("alepha/orm").PG_DEFAULT>;
    container: import("zod").ZodString;
    cacheKey: import("zod").ZodString;
    value: import("zod").ZodOptional<import("zod").ZodString>;
    count: import("zod").ZodOptional<import("zod").ZodInt>;
    expiresAt: import("zod").ZodOptional<import("zod").ZodString>;
  }, import("zod/v4/core").$strip>>;
  protected readonly options: Readonly<{
    sweepProbability: number;
    sweepBatchSize: number;
  }>;
  /**
   * Total writes performed since startup. Useful for tests and metrics.
   */
  writes: number;
  /**
   * Total opportunistic sweep cycles executed. Useful for tests.
   */
  sweeps: number;
  /**
   * Last error caught while sweeping (sweeps must never throw).
   */
  lastSweepError?: unknown;
  protected readonly onStart: import("alepha").HookPrimitive<"start">;
  get(name: string, key: string): Promise<Uint8Array | undefined>;
  set(name: string, key: string, value: Uint8Array, ttl?: number): Promise<Uint8Array>;
  del(name: string, ...keys: string[]): Promise<void>;
  has(name: string, key: string): Promise<boolean>;
  keys(name: string, filter?: string): Promise<string[]>;
  clear(): Promise<void>;
  incr(name: string, key: string, amount: number): Promise<number>;
  /**
   * Sweep all expired rows in one shot. Useful for tests and for users who
   * want to schedule their own cleanup job.
   */
  sweepExpired(): Promise<number>;
  protected unexpiredOrClause(): Record<string, any>;
  protected unexpiredWhere(name: string, key: string): Record<string, any>;
  protected computeExpiresAt(ttl?: number): string | null;
  protected toBase64(value: Uint8Array): string;
  protected fromBase64(value: string): Uint8Array;
  /**
   * Run an opportunistic sweep with `sweepProbability` chance per write.
   *
   * Sweep failures are swallowed: cleanup is best-effort, lazy expiration on
   * read keeps correctness regardless. Errors are logged once on `lastSweepError`
   * so tests can assert on them.
   */
  protected maybeSweep(): void;
  protected runSweep(): Promise<void>;
}
//#endregion
//#region ../../src/cache/database/index.d.ts
/**
 * Plugin for Alepha Cache that stores entries in the application's SQL database.
 *
 * Adds a `cache_entries` table and a {@link DatabaseCacheProvider}
 * implementation of {@link CacheProvider} that:
 *
 * - reads/writes through the framework's ORM (Postgres, SQLite, D1, Bun);
 * - exposes an **atomic** `incr()` via `INSERT ... ON CONFLICT DO UPDATE`;
 * - filters expired rows on every read (lazy expiration);
 * - opportunistically sweeps a small batch of expired rows on writes
 *   (configurable via {@link databaseCacheOptions}).
 *
 * **Module is opt-in.** Importing this module does not change the default
 * `CacheProvider` binding — pass `provider: DatabaseCacheProvider` explicitly
 * to the relevant `$cache(...)` calls, or rebind globally via
 * `alepha.with({ provide: CacheProvider, use: DatabaseCacheProvider })`.
 *
 * @see {@link DatabaseCacheProvider}
 * @module alepha.cache.database
 */
declare const AlephaCacheDatabase: import("alepha").Service<import("alepha").Module>;
//#endregion
export { AlephaCacheDatabase, CacheEntry, DatabaseCacheOptions, DatabaseCacheProvider, cacheEntries, databaseCacheOptions };
//# sourceMappingURL=index.d.ts.map