alepha 0.20.4 → 0.20.6

package/src/api/users/services/SessionService.ts

@@ -17,6 +17,7 @@ import { UserAudits } from "../audits/UserAudits.ts";
 import type { UserEntity } from "../entities/users.ts";
 import { UserNotifications } from "../notifications/UserNotifications.ts";
 import { RealmProvider } from "../providers/RealmProvider.ts";
+import { UsernameSlugger } from "./UsernameSlugger.ts";
 
 export class SessionService {
   protected readonly alepha = $inject(Alepha);
@@ -27,6 +28,7 @@ export class SessionService {
   protected readonly realmProvider = $inject(RealmProvider);
   protected readonly fileController = $client<FileController>();
   protected readonly cacheProvider = $inject(CacheProvider);
+  protected readonly usernameSlugger = $inject(UsernameSlugger);
 
   protected userAudits(realmName?: string) {
     const realm = this.realmProvider.getRealm(realmName);
@@ -110,69 +112,24 @@ export class SessionService {
   /**
    * Generate a unique username from an OAuth profile.
    *
-   * 1. Extract candidate from email prefix
-   * 2. Sanitize against realm's usernameRegExp (strip invalid chars, truncate)
-   * 3. Check case-insensitive uniqueness, append suffix (2, 3, ...) if taken
-   * 4. Fall back to "user" + random 6-char alphanumeric if all else fails
+   * Routes through {@link UsernameSlugger}, which is the same code path as
+   * `username: "email"` registration. The OAuth profile's email is the
+   * primary signal; if absent (rare — most IDPs return one), we fall back
+   * to `profile.name`, then to a random handle. The slugger applies the
+   * realm's `usernameBlocklist` and retries on collision.
    */
   protected async generateUniqueUsername(
     profile: OAuth2Profile,
-    realmSettings: any,
-    users: any,
+    _realmSettings: any,
+    _users: any,
+    realmName?: string,
   ): Promise<string> {
-    const maxLength = 30;
-    const maxSuffixAttempts = 10;
-
-    // Extract candidate from email or profile name
-    let candidate = profile.email?.split("@")[0] ?? profile.name ?? "";
-
-    // Strip characters not allowed in usernames (keep alphanumeric, underscore, dot, hyphen)
-    candidate = candidate.replace(/[^a-zA-Z0-9_.-]/g, "");
-
-    // If realm has a custom regex, further sanitize
-    if (realmSettings?.usernameRegExp) {
-      try {
-        const regex = new RegExp(realmSettings.usernameRegExp);
-        if (!regex.test(candidate)) {
-          // Strip to basic alphanumeric as safe fallback
-          candidate = candidate.replace(/[^a-zA-Z0-9_]/g, "");
-        }
-      } catch {
-        // Invalid regex, continue with sanitized candidate
-      }
-    }
-
-    // Ensure minimum length
-    if (candidate.length < 3) {
-      candidate = `user${candidate}`;
-    }
-
-    // Truncate to leave room for suffix
-    candidate = candidate.slice(0, maxLength - 2);
-
-    // Check uniqueness (case-insensitive exact match)
-    const isAvailable = async (name: string) => {
-      const existing = await users.findOne({
-        where: { username: { ilike: name } },
-      });
-      return !existing;
-    };
-
-    if (await isAvailable(candidate)) {
-      return candidate;
-    }
-
-    // Try with numeric suffix
-    for (let i = 2; i <= maxSuffixAttempts + 1; i++) {
-      const withSuffix = `${candidate}${i}`;
-      if (withSuffix.length <= maxLength && (await isAvailable(withSuffix))) {
-        return withSuffix;
-      }
-    }
-
-    // Final fallback: random username
-    const random = Math.random().toString(36).slice(2, 8);
-    return `user${random}`;
+    const seed =
+      profile.email ??
+      profile.name ??
+      `user-${Math.random().toString(36).slice(2, 8)}`;
+    const base = this.usernameSlugger.slug(seed);
+    return this.usernameSlugger.pickAvailable(realmName, base);
   }
 
   /**
@@ -766,6 +723,7 @@ export class SessionService {
       profile,
       realmSettings,
       users,
+      userRealmName,
     );
 
     const user = await users.create({

package/src/api/users/services/UsernameSlugger.ts

@@ -0,0 +1,195 @@
+import { $inject, AlephaError } from "alepha";
+import { $logger } from "alepha/logger";
+import { RealmProvider } from "../providers/RealmProvider.ts";
+
+/**
+ * Derive stable, URL-safe usernames from email addresses.
+ *
+ * Used by the registration flow when `realm.settings.username === "email"`,
+ * and reusable from any custom user-creation site (e.g. an OAuth-only flow
+ * that wants the same handle convention).
+ *
+ * **Slug rule** — the local-part of the email is kept as-is (gmail
+ * `+suffix` retained for predictability). Everything outside `[a-z0-9]` is
+ * replaced with `-`, runs of `-` are collapsed, leading/trailing `-` are
+ * trimmed, lowercased. If the result is shorter than {@link MIN_LENGTH} it
+ * is padded with random alphanumerics. Result is clamped to
+ * {@link MAX_LENGTH}.
+ *
+ * **Collision retry** — `pickAvailable()` checks the realm's `users` table
+ * and the realm's `usernameBlocklist`. On hit, it appends `-<4 random>` and
+ * retries up to {@link MAX_RETRIES} times. Best-effort against concurrent
+ * registrations: the unique index on `(realm, lower(username))` is the
+ * authoritative race guard, callers that hit a unique-violation should
+ * call `pickAvailable` again with a fresh suffix.
+ *
+ * @see RegistrationService.createRegistrationIntent
+ */
+export class UsernameSlugger {
+  protected readonly realmProvider = $inject(RealmProvider);
+  protected readonly log = $logger();
+
+  /**
+   * Floor for derived usernames. Shorter slugs are padded with random
+   * alphanumerics. Matches the lower bound of the default `usernameRegExp`.
+   */
+  static readonly MIN_LENGTH = 3;
+
+  /**
+   * Ceiling for derived usernames. Matches the upper bound of the default
+   * `usernameRegExp` and gives enough headroom for the random suffix added
+   * on collisions.
+   */
+  static readonly MAX_LENGTH = 30;
+
+  /**
+   * Length of the random suffix appended on collision (e.g. `-3dp6`).
+   * 36⁴ ≈ 1.6M variants per base — plenty for a tiny number of retries.
+   */
+  static readonly SUFFIX_LENGTH = 4;
+
+  /**
+   * How many times `pickAvailable` retries before giving up.
+   */
+  static readonly MAX_RETRIES = 5;
+
+  /**
+   * Alphabet used for the random suffix and for padding short slugs.
+   */
+  static readonly ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+
+  /**
+   * Default replacement when the email's local-part contains no
+   * `[a-z0-9]` characters at all (rare but possible: `é@example.com`).
+   */
+  static readonly EMPTY_LOCAL_FALLBACK = "user";
+
+  /**
+   * Sanitize an email into a base username slug.
+   *
+   * Pure function — no DB access. Always returns a string that satisfies
+   * `^[a-z0-9-]{MIN_LENGTH,MAX_LENGTH}$`.
+   *
+   * @example
+   * slug("ni.foures+testkv@gmail.com") // "ni-foures-testkv"
+   * slug("john.doe@example.com")       // "john-doe"
+   * slug("é@example.com")              // "user-XXX" (padded)
+   */
+  public slug(email: string | null | undefined): string {
+    const raw = (email ?? "").trim();
+    const at = raw.indexOf("@");
+    const local = at > 0 ? raw.slice(0, at) : raw;
+
+    const cleaned = local
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "");
+
+    let result = cleaned || UsernameSlugger.EMPTY_LOCAL_FALLBACK;
+
+    if (result.length < UsernameSlugger.MIN_LENGTH) {
+      const needed = UsernameSlugger.MIN_LENGTH - result.length;
+      result += this.randomSuffix(needed);
+    }
+
+    return this.clamp(result);
+  }
+
+  /**
+   * Find an available username for the realm, starting from `base`.
+   *
+   * Returns `base` when nothing collides. On a hit (existing row OR
+   * blocklisted name) appends `-<4 random>` and tries again, up to
+   * {@link MAX_RETRIES} times.
+   *
+   * The check is best-effort: a concurrent registration may still claim
+   * the same value before the caller's INSERT runs, in which case the DB
+   * unique index throws and the caller should retry.
+   */
+  public async pickAvailable(
+    realmName: string | undefined,
+    base: string,
+  ): Promise<string> {
+    const blocklist = await this.getBlocklist(realmName);
+    const repo = this.realmProvider.userRepository(realmName);
+    const realm = this.realmProvider.getRealm(realmName);
+
+    const isAvailable = async (candidate: string): Promise<boolean> => {
+      if (this.isBlockedAgainst(candidate, blocklist)) {
+        return false;
+      }
+      const existing = await repo.findOne({
+        where: {
+          realm: { eq: realm.name },
+          username: { ilike: candidate },
+        },
+      });
+      return !existing;
+    };
+
+    if (await isAvailable(base)) {
+      return base;
+    }
+
+    // Reserve room for "-" + suffix at the end of the candidate.
+    const reserve = 1 + UsernameSlugger.SUFFIX_LENGTH;
+    const trimmedBase =
+      base.length > UsernameSlugger.MAX_LENGTH - reserve
+        ? base.slice(0, UsernameSlugger.MAX_LENGTH - reserve)
+        : base;
+
+    for (let i = 0; i < UsernameSlugger.MAX_RETRIES; i++) {
+      const candidate = `${trimmedBase}-${this.randomSuffix(
+        UsernameSlugger.SUFFIX_LENGTH,
+      )}`;
+      if (await isAvailable(candidate)) {
+        return candidate;
+      }
+    }
+
+    throw new AlephaError(
+      `Could not find an available username starting from "${base}" after ${UsernameSlugger.MAX_RETRIES} attempts.`,
+    );
+  }
+
+  /**
+   * Check a name against the realm's `usernameBlocklist`. Case-insensitive.
+   */
+  public async isBlocked(
+    realmName: string | undefined,
+    name: string,
+  ): Promise<boolean> {
+    const blocklist = await this.getBlocklist(realmName);
+    return this.isBlockedAgainst(name, blocklist);
+  }
+
+  // -------------------------------------------------------------------------
+
+  protected async getBlocklist(
+    realmName: string | undefined,
+  ): Promise<Set<string>> {
+    const realm = this.realmProvider.getRealm(realmName);
+    const settings = await realm.getSettings();
+    const list = settings?.usernameBlocklist ?? [];
+    return new Set(list.map((b) => b.toLowerCase()));
+  }
+
+  protected isBlockedAgainst(name: string, blocklist: Set<string>): boolean {
+    return blocklist.has(name.toLowerCase());
+  }
+
+  protected clamp(s: string): string {
+    return s.length > UsernameSlugger.MAX_LENGTH
+      ? s.slice(0, UsernameSlugger.MAX_LENGTH)
+      : s;
+  }
+
+  protected randomSuffix(length: number): string {
+    const chars = UsernameSlugger.ALPHABET;
+    let out = "";
+    for (let i = 0; i < length; i++) {
+      out += chars[Math.floor(Math.random() * chars.length)];
+    }
+    return out;
+  }
+}

package/src/bucket/primitives/$bucket.ts

@@ -277,6 +277,27 @@ export class BucketPrimitive extends Primitive<BucketPrimitiveOptions> {
     });
   }
 
+  /**
+   * Delete many files in one round-trip when the underlying provider supports
+   * batch (R2/S3 up to 1000 keys per call). Emits one `bucket:file:deleted`
+   * event per id unless `skipHook` is set.
+   */
+  public async deleteMany(fileIds: string[], skipHook = false): Promise<void> {
+    if (fileIds.length === 0) return;
+    await this.provider.deleteMany(this.name, fileIds);
+
+    if (skipHook) {
+      return;
+    }
+
+    for (const id of fileIds) {
+      await this.alepha.events.emit("bucket:file:deleted", {
+        id,
+        bucket: this,
+      });
+    }
+  }
+
   /**
    * Checks if a file exists in the bucket.
    */

package/src/bucket/providers/CloudflareR2Provider.ts

@@ -210,6 +210,21 @@ export class CloudflareR2Provider implements FileStorageProvider {
     await r2.delete(key);
   }
 
+  public async deleteMany(
+    bucketName: string,
+    fileIds: string[],
+  ): Promise<void> {
+    if (fileIds.length === 0) return;
+    const r2 = this.getR2();
+    const keys = fileIds.map((id) => this.key(bucketName, id));
+    this.log.trace(`Deleting ${keys.length} keys from '${bucketName}'`);
+    // R2 binding accepts a string[] and silently ignores missing keys.
+    // Chunk at 1000 to stay within the documented batch limit.
+    for (let i = 0; i < keys.length; i += 1000) {
+      await r2.delete(keys.slice(i, i + 1000));
+    }
+  }
+
   /**
    * Build the full R2 key: {prefix}/{bucketName}/{fileId}
    */

package/src/bucket/providers/FileStorageProvider.ts

@@ -40,4 +40,13 @@ export abstract class FileStorageProvider {
    * @param fileId - Identifier of the file to delete
    */
   abstract delete(bucketName: string, fileId: string): Promise<void>;
+
+  /**
+   * Delete multiple files in one round-trip where the provider supports
+   * batch (R2/S3, up to 1000 per call). Memory/Local fall back to a loop.
+   *
+   * @param bucketName - Container name
+   * @param fileIds - Identifiers of the files to delete
+   */
+  abstract deleteMany(bucketName: string, fileIds: string[]): Promise<void>;
 }

package/src/bucket/providers/LocalFileStorageProvider.ts

@@ -157,6 +157,20 @@ export class LocalFileStorageProvider implements FileStorageProvider {
     }
   }
 
+  public async deleteMany(
+    bucketName: string,
+    fileIds: string[],
+  ): Promise<void> {
+    await Promise.all(
+      fileIds.map((id) =>
+        unlink(this.path(bucketName, id)).catch((error) => {
+          if (this.isErrorNoEntry(error)) return;
+          throw new AlephaError("Error deleting file", { cause: error });
+        }),
+      ),
+    );
+  }
+
   protected stat(bucket: string, fileId: string): Promise<fs.Stats> {
     return stat(this.path(bucket, fileId));
   }

package/src/bucket/providers/MemoryFileStorageProvider.ts

@@ -70,6 +70,15 @@ export class MemoryFileStorageProvider implements FileStorageProvider {
     delete this.files[fileKey];
   }
 
+  public async deleteMany(
+    bucketName: string,
+    fileIds: string[],
+  ): Promise<void> {
+    for (const id of fileIds) {
+      delete this.files[`${bucketName}/${id}`];
+    }
+  }
+
   protected createId(): string {
     return randomUUID();
   }

package/src/bucket/providers/NodeS3BucketProvider.ts

@@ -215,4 +215,39 @@ export class NodeS3BucketProvider implements FileStorageProvider {
       throw error;
     }
   }
+
+  public async deleteMany(
+    bucketName: string,
+    fileIds: string[],
+  ): Promise<void> {
+    if (fileIds.length === 0) return;
+    this.log.trace(
+      `Deleting ${fileIds.length} files from bucket '${bucketName}'...`,
+    );
+    const client = this.getClient(bucketName);
+    // S3 DeleteObjects caps at 1000 keys per request.
+    for (let i = 0; i < fileIds.length; i += 1000) {
+      const chunk = fileIds.slice(i, i + 1000);
+      try {
+        // bun:s3 client exposes a per-key deleteObject; some SDKs also expose
+        // deleteObjects(keys: string[]). Prefer batch when available.
+        const batch = (
+          client as unknown as {
+            deleteObjects?: (keys: string[]) => Promise<unknown>;
+          }
+        ).deleteObjects;
+        if (typeof batch === "function") {
+          await batch.call(client, chunk);
+        } else {
+          await Promise.all(chunk.map((id) => client.deleteObject(id)));
+        }
+      } catch (error) {
+        this.log.error(`Failed to delete files: ${error}`);
+        if (error instanceof Error) {
+          throw new FileNotFoundError("Error deleting files", { cause: error });
+        }
+        throw error;
+      }
+    }
+  }
 }

package/src/cache/core/primitives/$cache.ts

@@ -4,11 +4,11 @@ import {
   $state,
   AlephaError,
   createPrimitive,
-  type InstantiableClass,
   KIND,
   type MiddlewareMetadata,
   OPTIONS,
   Primitive,
+  type Service,
   type Static,
   t,
 } from "alepha";
@@ -112,9 +112,26 @@ export interface CachePrimitiveOptions<
 
   /**
    * The store provider for the cache.
-   * If not provided, the default store provider will be used.
+   *
+   * Accepts:
+   * - `"memory"` — short-circuits to {@link MemoryCacheProvider} regardless
+   *   of the default `CacheProvider` binding. Useful for caches that must
+   *   stay process-local (e.g. ETag, HTTP client).
+   * - A {@link CacheProvider} class (concrete OR abstract) — resolved via
+   *   `alepha.inject(...)` at primitive construction. Use this to opt a
+   *   specific cache into a non-default backend (e.g.
+   *   `provider: DatabaseCacheProvider` to keep one cache in SQL while the
+   *   rest of the app uses Cloudflare KV).
+   * - `undefined` — falls back to whatever is bound to `CacheProvider` in
+   *   the container. On Cloudflare workers this is
+   *   {@link CloudflareKVProvider} by default; on Node it's
+   *   {@link MemoryCacheProvider}.
+   *
+   * Note: passing an *abstract* class works because Alepha's DI resolves
+   * through substitutions, e.g. `alepha.with({ provide: CacheProvider, use:
+   * MyCacheProvider })`.
    */
-  provider?: InstantiableClass<CacheProvider> | "memory";
+  provider?: Service<CacheProvider> | "memory";
 
   /**
    * The time-to-live for the cache in seconds.

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

@@ -0,0 +1,203 @@
+import { Alepha } from "alepha";
+import { $cache, CacheProvider } from "alepha/cache";
+import { describe, expect, it } from "vitest";
+import {
+  DatabaseCacheProvider,
+  databaseCacheOptions,
+} from "../providers/DatabaseCacheProvider.ts";
+
+const make = (
+  configure: (app: Alepha) => void = () => {},
+): { alepha: Alepha; provider: () => DatabaseCacheProvider } => {
+  const alepha = Alepha.create({
+    env: { DATABASE_URL: "sqlite://:memory:" },
+  }).with({
+    provide: CacheProvider,
+    use: DatabaseCacheProvider,
+  });
+  configure(alepha);
+  return {
+    alepha,
+    provider: () => alepha.inject(DatabaseCacheProvider),
+  };
+};
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+describe("DatabaseCacheProvider — atomic incr", () => {
+  it("increments through SQL upsert (no read/modify/write race)", async () => {
+    const { alepha, provider } = make();
+    await alepha.start();
+    const p = provider();
+
+    expect(await p.incr("counters", "k", 1)).toBe(1);
+    expect(await p.incr("counters", "k", 1)).toBe(2);
+    expect(await p.incr("counters", "k", 5)).toBe(7);
+    expect(await p.incr("counters", "k", -3)).toBe(4);
+  });
+
+  it("survives concurrent increments without losing updates", async () => {
+    const { alepha, provider } = make();
+    await alepha.start();
+    const p = provider();
+
+    // SQLite serializes writes; this proves that even concurrent .incr()
+    // calls all end up reflected in the final count, unlike the KV
+    // read-modify-write race we want to avoid.
+    const concurrent = 50;
+    await Promise.all(
+      Array.from({ length: concurrent }, () => p.incr("hits", "ip", 1)),
+    );
+
+    const bytes = await p.get("hits", "ip");
+    const value = JSON.parse(new TextDecoder().decode(bytes!.subarray(1)));
+    expect(value).toBe(concurrent);
+  });
+
+  it("reads back an incr'd value through get()", async () => {
+    const { alepha, provider } = make();
+    await alepha.start();
+    const p = provider();
+
+    await p.incr("counters", "k", 7);
+    const bytes = await p.get("counters", "k");
+    expect(bytes).toBeDefined();
+    // JSON-encoded number with the JSON marker byte (0x02).
+    expect(bytes![0]).toBe(0x02);
+    expect(new TextDecoder().decode(bytes!.subarray(1))).toBe("7");
+  });
+});
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+describe("DatabaseCacheProvider — lazy expiration on read", () => {
+  it("returns undefined for an expired entry without sweeping it first", async () => {
+    const { alepha, provider } = make();
+    await alepha.start();
+    const p = provider();
+
+    // Write directly with a TTL of 1ms so the row is already expired by the
+    // time we read it, regardless of clock granularity.
+    await p.set("c", "k", new TextEncoder().encode("hello"), 1);
+    await new Promise((r) => setTimeout(r, 5));
+
+    expect(await p.get("c", "k")).toBeUndefined();
+    expect(await p.has("c", "k")).toBe(false);
+  });
+
+  it("excludes expired entries from keys() and from get() but leaves them in storage until swept", async () => {
+    const { alepha, provider } = make();
+    await alepha.start();
+    const p = provider();
+
+    await p.set("c", "fresh", new TextEncoder().encode("a"));
+    await p.set("c", "stale", new TextEncoder().encode("b"), 1);
+    await new Promise((r) => setTimeout(r, 5));
+
+    expect(await p.keys("c")).toEqual(["fresh"]);
+    expect(await p.has("c", "stale")).toBe(false);
+
+    // The expired row is still on disk until sweep runs; correctness is
+    // preserved by the read-time filter, not by aggressive cleanup.
+    const rows = await (p as any).repository.findMany({});
+    expect(rows.length).toBe(2);
+  });
+});
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+describe("DatabaseCacheProvider — opportunistic sweep", () => {
+  it("does nothing when sweepProbability is 0", async () => {
+    const { alepha, provider } = make((app) => {
+      app.store.mut(databaseCacheOptions, (cur) => ({
+        ...cur,
+        sweepProbability: 0,
+      }));
+    });
+    await alepha.start();
+    const p = provider();
+
+    for (let i = 0; i < 30; i++) {
+      await p.set("c", `k${i}`, new TextEncoder().encode("x"));
+    }
+    expect(p.sweeps).toBe(0);
+  });
+
+  it("triggers a sweep on every write when sweepProbability is 1", async () => {
+    const { alepha, provider } = make((app) => {
+      app.store.mut(databaseCacheOptions, (cur) => ({
+        ...cur,
+        sweepProbability: 1,
+      }));
+    });
+    await alepha.start();
+    const p = provider();
+
+    await p.set("c", "fresh", new TextEncoder().encode("a"));
+    await p.set("c", "stale", new TextEncoder().encode("b"), 1);
+    await new Promise((r) => setTimeout(r, 5));
+
+    // Trigger another write; the stale row should be reaped during the sweep.
+    await p.set("c", "trigger", new TextEncoder().encode("c"));
+    expect(p.sweeps).toBeGreaterThan(0);
+
+    // Nothing references the swept row anymore.
+    expect(await p.has("c", "stale")).toBe(false);
+  });
+
+  it("sweepExpired() reaps every expired row in one shot", async () => {
+    const { alepha, provider } = make((app) => {
+      app.store.mut(databaseCacheOptions, (cur) => ({
+        ...cur,
+        sweepProbability: 0,
+      }));
+    });
+    await alepha.start();
+    const p = provider();
+
+    for (let i = 0; i < 5; i++) {
+      await p.set("c", `stale${i}`, new TextEncoder().encode("x"), 1);
+    }
+    await p.set("c", "fresh", new TextEncoder().encode("y"));
+    await new Promise((r) => setTimeout(r, 5));
+
+    const reaped = await p.sweepExpired();
+    expect(reaped).toBe(5);
+
+    // Sanity: the live entry is intact.
+    expect(await p.has("c", "fresh")).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+describe("DatabaseCacheProvider — provider option on $cache", () => {
+  it("$cache({ provider: DatabaseCacheProvider }) routes to the SQL backend even when the default CacheProvider is something else", async () => {
+    class App {
+      // Default fallback CacheProvider is MemoryCacheProvider in this test.
+      pinned = $cache<string>({
+        provider: DatabaseCacheProvider,
+      });
+    }
+
+    const alepha = Alepha.create({
+      env: { DATABASE_URL: "sqlite://:memory:" },
+    });
+    // Note: NO substitution of CacheProvider — the framework default is in
+    // play. The pinned `$cache` should still reach DatabaseCacheProvider via
+    // the explicit option.
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    await app.pinned.set("k", "v");
+    expect(await app.pinned.get("k")).toBe("v");
+
+    // The row really lives in the cache_entries table, not in
+    // MemoryCacheProvider's map.
+    const rows = await (
+      alepha.inject(DatabaseCacheProvider) as any
+    ).repository.findMany({});
+    expect(rows.length).toBe(1);
+    expect(rows[0].cacheKey).toBe("k");
+  });
+});