alepha 0.20.4 → 0.20.6

package/src/cache/database/__tests__/DatabaseCacheProvider.spec.ts

@@ -0,0 +1,110 @@
+import type { Alepha } from "alepha";
+import { afterEach, beforeEach, describe, it, vi } from "vitest";
+import {
+  testCacheBasic,
+  testCacheClear,
+  testCacheCompress,
+  testCacheCompressTypes,
+  testCacheDisabled,
+  testCacheFalsyValues,
+  testCacheIncr,
+  testCacheInvalidateAll,
+  testCacheInvalidateByArgs,
+  testCacheInvalidateByKey,
+  testCacheKeys,
+  testCacheMissingProvider,
+  testCachePrimitiveIncr,
+  testCacheProviderClear,
+  testCacheReturnTypes,
+  testCacheSetDisabled,
+  testSimpleKeyMappingHandler,
+} from "../../core/__tests__/shared.ts";
+import { DatabaseCacheProvider } from "../index.ts";
+
+const provider = DatabaseCacheProvider;
+
+// Override DATABASE_URL via process.env BEFORE Alepha.create() runs in each
+// shared test. The shared `testSimpleKeyMappingHandler` instantiates the app
+// (and therefore the SQLite provider) inside the .with() chain, BEFORE the
+// `configure` callback runs — so we can't rely on `app.store.set("env", ...)`
+// to flip the URL fast enough; the env schema has already been parsed and
+// cached by the time configure fires.
+const sqlite = () => (_app: Alepha) => {};
+
+describe("$cache - database (sqlite)", () => {
+  beforeEach(() => {
+    vi.stubEnv("DATABASE_URL", "sqlite://:memory:");
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("should handle basic caching", async () => {
+    await testCacheBasic(sqlite(), provider);
+  });
+
+  it("should handle missing provider", async () => {
+    await testCacheMissingProvider(sqlite(), provider);
+  });
+
+  it("should handle disabled cache", async () => {
+    await testCacheDisabled(sqlite(), provider);
+  });
+
+  it("should invalidate by key", async () => {
+    await testCacheInvalidateByKey(sqlite(), provider);
+  });
+
+  it("should invalidate by args", async () => {
+    await testCacheInvalidateByArgs(sqlite(), provider);
+  });
+
+  it("should invalidate all entries", async () => {
+    await testCacheInvalidateAll(sqlite(), provider);
+  });
+
+  it("should clear cache", async () => {
+    await testCacheClear(sqlite(), provider);
+  });
+
+  it("should handle different return types", async () => {
+    await testCacheReturnTypes(sqlite(), provider);
+  });
+
+  it("should generate cache keys correctly", async () => {
+    await testCacheKeys(sqlite(), provider);
+  });
+
+  it("should handle unique key with args", async () => {
+    await testSimpleKeyMappingHandler(sqlite(), provider);
+  });
+
+  it("should clear provider cache", async () => {
+    await testCacheProviderClear(sqlite(), provider);
+  });
+
+  it("should increment values atomically", async () => {
+    await testCacheIncr(sqlite(), provider);
+  });
+
+  it("should cache falsy values (0, empty string, false, null)", async () => {
+    await testCacheFalsyValues(sqlite(), provider);
+  });
+
+  it("should not write to provider when cache is disabled", async () => {
+    await testCacheSetDisabled(sqlite(), provider);
+  });
+
+  it("should increment via primitive", async () => {
+    await testCachePrimitiveIncr(sqlite(), provider);
+  });
+
+  it("should compress cached values with gzip", async () => {
+    await testCacheCompress(sqlite(), provider);
+  });
+
+  it("should handle different types with compression", async () => {
+    await testCacheCompressTypes(sqlite(), provider);
+  });
+});

package/src/cache/database/entities/cacheEntries.ts

@@ -0,0 +1,55 @@
+import { type Static, t } from "alepha";
+import { $entity, db } from "alepha/orm";
+
+/**
+ * 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).
+ */
+export const cacheEntries = $entity({
+  name: "cache_entries",
+  schema: t.object({
+    id: db.primaryKey(t.uuid()),
+
+    createdAt: db.createdAt(),
+
+    container: t.text({
+      description: "Cache container name, set by the $cache primitive.",
+    }),
+
+    cacheKey: t.text({
+      description: "Per-container key chosen by the caller.",
+    }),
+
+    value: t.optional(
+      // No maxLength: cache values are arbitrary-sized (especially when
+      // `compress: true` is enabled on the $cache primitive, which can
+      // produce blobs well above the default 255-char `t.text()` cap). This
+      // resolves to TEXT in both Postgres and SQLite, which have no
+      // practical length limit either.
+      t.string({
+        description: "Base64-encoded bytes. Used by set/get.",
+      }),
+    ),
+
+    count: t.optional(
+      t.integer({
+        description: "Counter value. Used by atomic incr().",
+      }),
+    ),
+
+    expiresAt: t.optional(
+      t.datetime({
+        description: "Null means no expiration.",
+      }),
+    ),
+  }),
+  indexes: [{ columns: ["container", "cacheKey"], unique: true }, "expiresAt"],
+});
+
+export type CacheEntry = Static<typeof cacheEntries.schema>;

package/src/cache/database/index.ts

@@ -0,0 +1,36 @@
+import { $module } from "alepha";
+import { AlephaCache } from "alepha/cache";
+import { DatabaseCacheProvider } from "./providers/DatabaseCacheProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./entities/cacheEntries.ts";
+export * from "./providers/DatabaseCacheProvider.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
+ */
+export const AlephaCacheDatabase = $module({
+  name: "alepha.cache.database",
+  services: [DatabaseCacheProvider],
+  register: (alepha) => alepha.with(AlephaCache),
+});

package/src/cache/database/providers/DatabaseCacheProvider.ts

@@ -0,0 +1,348 @@
+import { $atom, $hook, $inject, $state, Alepha, type Static, t } from "alepha";
+import { CacheProvider } from "alepha/cache";
+import { DateTimeProvider } from "alepha/datetime";
+import { $logger } from "alepha/logger";
+import { $repository, sql } from "alepha/orm";
+import { cacheEntries } from "../entities/cacheEntries.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Configuration atom for {@link DatabaseCacheProvider}.
+ */
+export const databaseCacheOptions = $atom({
+  name: "alepha.cache.database.options",
+  schema: t.object({
+    sweepProbability: t.number({
+      description:
+        "Probability (0..1) that a write operation triggers a sweep of expired rows. Set to 0 to disable opportunistic sweeping.",
+      default: 0.01,
+      minimum: 0,
+      maximum: 1,
+    }),
+    sweepBatchSize: t.integer({
+      description:
+        "Maximum number of expired rows deleted per opportunistic sweep.",
+      default: 100,
+      minimum: 1,
+    }),
+  }),
+  default: {
+    sweepProbability: 0.01,
+    sweepBatchSize: 100,
+  },
+});
+
+export 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}
+ */
+export class DatabaseCacheProvider extends CacheProvider {
+  protected readonly log = $logger();
+  protected readonly alepha = $inject(Alepha);
+  protected readonly dateTimeProvider = $inject(DateTimeProvider);
+  protected readonly repository = $repository(cacheEntries);
+  protected readonly options = $state(databaseCacheOptions);
+
+  /**
+   * Total writes performed since startup. Useful for tests and metrics.
+   */
+  public writes = 0;
+
+  /**
+   * Total opportunistic sweep cycles executed. Useful for tests.
+   */
+  public sweeps = 0;
+
+  /**
+   * Last error caught while sweeping (sweeps must never throw).
+   */
+  public lastSweepError?: unknown;
+
+  // -------------------------------------------------------------------------------------------------------------------
+
+  protected readonly onStart = $hook({
+    on: "start",
+    handler: () => {
+      this.log.debug("DatabaseCacheProvider ready");
+    },
+  });
+
+  // -------------------------------------------------------------------------------------------------------------------
+
+  public async get(name: string, key: string): Promise<Uint8Array | undefined> {
+    if (!this.alepha.isStarted()) {
+      return undefined;
+    }
+
+    const row = await this.repository.findOne({
+      where: this.unexpiredWhere(name, key) as any,
+    });
+
+    if (!row) {
+      return undefined;
+    }
+
+    if (row.value != null) {
+      return this.fromBase64(row.value);
+    }
+
+    if (row.count != null) {
+      // The caller wrote the entry through `incr()`. Surface the count via
+      // the same byte format that MemoryCacheProvider uses, so `getTyped`
+      // returns the number transparently.
+      return this.serialize(row.count);
+    }
+
+    return undefined;
+  }
+
+  public async set(
+    name: string,
+    key: string,
+    value: Uint8Array,
+    ttl?: number,
+  ): Promise<Uint8Array> {
+    if (!this.alepha.isStarted()) {
+      return value;
+    }
+
+    const expiresAt = this.computeExpiresAt(ttl);
+
+    await this.repository.upsert(
+      {
+        container: name,
+        cacheKey: key,
+        value: this.toBase64(value),
+        count: null,
+        expiresAt,
+      } as any,
+      {
+        target: ["container", "cacheKey"],
+        set: {
+          value: this.toBase64(value),
+          count: null,
+          expiresAt,
+        },
+      },
+    );
+
+    this.writes++;
+    this.maybeSweep();
+
+    return value;
+  }
+
+  public async del(name: string, ...keys: string[]): Promise<void> {
+    if (keys.length === 0) {
+      await this.repository.deleteMany({
+        container: { eq: name },
+      });
+      return;
+    }
+
+    await this.repository.deleteMany({
+      container: { eq: name },
+      cacheKey: { inArray: keys },
+    });
+  }
+
+  public async has(name: string, key: string): Promise<boolean> {
+    const row = await this.repository.findOne({
+      where: this.unexpiredWhere(name, key) as any,
+    });
+    return row != null;
+  }
+
+  public async keys(name: string, filter?: string): Promise<string[]> {
+    const baseAnd: any[] = [
+      { container: { eq: name } },
+      this.unexpiredOrClause(),
+    ];
+    if (filter) {
+      baseAnd.push({ cacheKey: { startsWith: filter } });
+    }
+
+    const rows = await this.repository.findMany({
+      where: { and: baseAnd } as any,
+    });
+
+    return rows.map((row) => row.cacheKey);
+  }
+
+  public async clear(): Promise<void> {
+    await this.repository.deleteMany({});
+  }
+
+  public async incr(
+    name: string,
+    key: string,
+    amount: number,
+  ): Promise<number> {
+    if (!this.alepha.isStarted()) {
+      return amount;
+    }
+
+    // Atomic upsert via `INSERT ... ON CONFLICT (container, cacheKey) DO UPDATE
+    // SET count = COALESCE(cache_entries.count, 0) + excluded.count`.
+    // Both Postgres and SQLite (incl. D1) support this in a single statement,
+    // so concurrent callers can never observe an interleaved read/write.
+    const table = this.repository.table;
+
+    const updated = await this.repository.upsert(
+      {
+        container: name,
+        cacheKey: key,
+        count: amount,
+        value: null,
+        expiresAt: null,
+      } as any,
+      {
+        target: ["container", "cacheKey"],
+        set: {
+          // `excluded.count` references the value being inserted on conflict.
+          count: sql`coalesce(${table.count}, 0) + ${amount}`,
+          value: null,
+        },
+      },
+    );
+
+    this.writes++;
+    this.maybeSweep();
+
+    return Number(updated.count ?? amount);
+  }
+
+  // -------------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Sweep all expired rows in one shot. Useful for tests and for users who
+   * want to schedule their own cleanup job.
+   */
+  public async sweepExpired(): Promise<number> {
+    const nowIso = this.dateTimeProvider.nowISOString();
+    const ids = await this.repository.deleteMany({
+      expiresAt: { lt: nowIso },
+    });
+    return ids.length;
+  }
+
+  // -------------------------------------------------------------------------------------------------------------------
+
+  protected unexpiredOrClause(): Record<string, any> {
+    const nowIso = this.dateTimeProvider.nowISOString();
+    return {
+      or: [{ expiresAt: { isNull: true } }, { expiresAt: { gt: nowIso } }],
+    };
+  }
+
+  protected unexpiredWhere(name: string, key: string): Record<string, any> {
+    return {
+      and: [
+        { container: { eq: name } },
+        { cacheKey: { eq: key } },
+        this.unexpiredOrClause(),
+      ],
+    };
+  }
+
+  protected computeExpiresAt(ttl?: number): string | null {
+    if (!ttl || ttl <= 0) {
+      return null;
+    }
+    return this.dateTimeProvider
+      .of(this.dateTimeProvider.nowMillis() + ttl)
+      .toISOString();
+  }
+
+  protected toBase64(value: Uint8Array): string {
+    return Buffer.from(
+      value.buffer as ArrayBuffer,
+      value.byteOffset,
+      value.byteLength,
+    ).toString("base64");
+  }
+
+  protected fromBase64(value: string): Uint8Array {
+    return new Uint8Array(Buffer.from(value, "base64"));
+  }
+
+  /**
+   * 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 {
+    const probability = this.options.sweepProbability;
+    if (probability <= 0) {
+      return;
+    }
+
+    if (Math.random() >= probability) {
+      return;
+    }
+
+    this.runSweep().catch((err) => {
+      this.lastSweepError = err;
+      this.log.warn("DatabaseCacheProvider sweep failed", err);
+    });
+  }
+
+  protected async runSweep(): Promise<void> {
+    this.sweeps++;
+    const nowIso = this.dateTimeProvider.nowISOString();
+
+    // Drizzle does not expose a portable LIMIT on DELETE, so we select first
+    // and then delete by ID. Two roundtrips, but only on the ~1% sweep path.
+    const expired = await this.repository.findMany({
+      where: { expiresAt: { lt: nowIso } },
+      columns: ["id"],
+      limit: this.options.sweepBatchSize,
+    });
+
+    if (expired.length === 0) {
+      return;
+    }
+
+    await this.repository.deleteMany({
+      id: { inArray: expired.map((it) => it.id) },
+    });
+  }
+}

package/src/cli/core/services/ProjectScaffolder.ts

@@ -700,8 +700,6 @@ export class ProjectScaffolder {
     //   --no-monorepo   skip the monorepo prompt — we ship a single-app
     //                   layout; users opt into monorepo via `--monorepo`
     //                   on the alepha side later
-    //   --silent        suppress shadcn's own progress output; alepha's
-    //                   runner already prints a status line
     //
     // We deliberately do NOT pass `--defaults` (would force Next.js +
     // base-nova preset) or `--template` (only applies to scratch projects;

package/src/cli/core/tasks/BuildCloudflareTask.ts

@@ -235,11 +235,23 @@ export class BuildCloudflareTask extends BuildTask {
     const workerCode = `
 import "./index.js";
 
+// Stash the per-invocation \`executionCtx.waitUntil\` in the Alepha store
+// so background work (notably $job direct dispatch) can keep the isolate
+// alive past the response.
+const setWaitUntil = (executionCtx) => {
+  if (executionCtx && typeof executionCtx.waitUntil === "function") {
+    __alepha.set("cloudflare.waitUntil", (p) => executionCtx.waitUntil(p));
+  } else {
+    __alepha.set("cloudflare.waitUntil", undefined);
+  }
+};
+
 export default {
-  fetch: async (request, env) => {
+  fetch: async (request, env, executionCtx) => {
     const ctx = { req: request, res: undefined };
 
     __alepha.set("cloudflare.env", env);
+    setWaitUntil(executionCtx);
 
     try {
       await __alepha.start();
@@ -253,8 +265,9 @@ export default {
     return ctx.res;
   },
 
-  scheduled: async (event, env, ctx) => {
+  scheduled: async (event, env, executionCtx) => {
     __alepha.set("cloudflare.env", env);
+    setWaitUntil(executionCtx);
 
     try {
       await __alepha.start();
@@ -269,8 +282,9 @@ export default {
     });
   },
 
-  queue: async (batch, env) => {
+  queue: async (batch, env, executionCtx) => {
     __alepha.set("cloudflare.env", env);
+    setWaitUntil(executionCtx);
 
     try {
       await __alepha.start();

package/src/cli/core/tasks/BuildSitemapTask.ts

@@ -39,9 +39,16 @@ export class BuildSitemapTask extends BuildTask {
     const pages = ctx.alepha.primitives("page") as any[];
     return pages.filter((page) => {
       const options = page.options;
+      const path: string = options.path ?? "";
       if (options.children) {
         return false;
       }
+      if (path.includes("*")) {
+        return false;
+      }
+      if (path === "/404") {
+        return false;
+      }
       if (!options.schema?.params) {
         return true;
       }