@dbx-tools/appkit 0.9.117 → 0.9.119

package/package.json

@@ -20,7 +20,7 @@
   },
   "devDependencies": {
     "@databricks/appkit": "0.81.0",
-    "@dbx-tools/projen": "^0.9.117",
+    "@dbx-tools/projen": "^0.9.119",
     "@types/node": "^24.6.0",
     "typescript": "^5.9.3",
     "vitest": "3.2.4"
@@ -30,13 +30,13 @@
   },
   "dependencies": {
     "@databricks/sdk-experimental": "^0.17.0",
-    "@dbx-tools/auth": "^0.9.117",
-    "@dbx-tools/core": "^0.9.117",
-    "@dbx-tools/lakebase": "^0.9.117",
-    "@dbx-tools/postgres": "^0.9.117",
-    "@dbx-tools/shared-core": "^0.9.117",
-    "@dbx-tools/shared-fs": "^0.9.117",
-    "lru-cache": "11.5.3",
+    "@dbx-tools/auth": "^0.9.119",
+    "@dbx-tools/cache": "^0.9.119",
+    "@dbx-tools/core": "^0.9.119",
+    "@dbx-tools/lakebase": "^0.9.119",
+    "@dbx-tools/postgres": "^0.9.119",
+    "@dbx-tools/shared-core": "^0.9.119",
+    "@dbx-tools/shared-fs": "^0.9.119",
     "zod": "4.3.6"
   },
   "main": "./lib/index.js",
@@ -62,6 +62,10 @@
         "types": "./lib/src/bundle.d.ts",
         "default": "./lib/src/bundle.js"
       },
+      "./cache-storage": {
+        "types": "./lib/src/cache-storage.d.ts",
+        "default": "./lib/src/cache-storage.js"
+      },
       "./child-process": {
         "types": "./lib/src/child-process.d.ts",
         "default": "./lib/src/child-process.js"
@@ -125,7 +129,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.117",
+  "version": "0.9.119",
   "types": "./lib/index.d.ts",
   "dbxToolsConfig": {
     "tags": [
@@ -150,6 +154,10 @@
       "types": "./lib/src/bundle.d.ts",
       "default": "./lib/src/bundle.js"
     },
+    "./cache-storage": {
+      "types": "./lib/src/cache-storage.d.ts",
+      "default": "./lib/src/cache-storage.js"
+    },
     "./child-process": {
       "types": "./lib/src/child-process.d.ts",
       "default": "./lib/src/child-process.js"

package/src/appkit.ts

@@ -39,8 +39,8 @@ import { profile as authProfile } from "@dbx-tools/auth";
 import { asyncUtils, environmentUtils, log } from "@dbx-tools/shared-core";
 
 import { resolveAutoConfigurePolicy } from "./_auto-configure.ts";
-import { createSoftPersistentStorage } from "./_cache-storage.ts";
 import { loadBrandContext } from "./brand-context.ts";
+import { createAppKitCacheStorage } from "./cache-storage.ts";
 import {
   createInterceptorContext,
   type Interceptor,
@@ -244,20 +244,12 @@ function applyDefaultProfile(): string | undefined {
   return resolved.name;
 }
 
-/**
- * Whether `createApp` should inject soft-fail Lakebase cache storage.
- *
- * Skips when the caller disabled the cache, already supplied a storage
- * backend (including in-memory), or Lakebase is not in play.
- */
-function shouldInjectSoftPersistentCache(
-  config: CreateAppConfig | undefined,
-  lakebase: LakebaseConnection | undefined,
-): boolean {
+/** Whether `createApp` should inject the default memory-first cache storage. */
+function shouldInjectCacheStorage(config: CreateAppConfig | undefined): boolean {
   const cache = config?.cache;
   if (cache?.enabled === false) return false;
   if (cache?.storage) return false;
-  return Boolean(lakebase) || usesPlugin(config, LAKEBASE_PLUGIN);
+  return true;
 }
 
 function redactLakebaseConnection(resolved: LakebaseConnection): Record<string, unknown> {
@@ -328,15 +320,16 @@ export async function createApp<T extends AppKitPlugins>(
   delete appConfig.autoConfigure;
   delete appConfig.interceptor;
 
-  if (shouldInjectSoftPersistentCache(config, lakebase)) {
-    logger.debug("createApp: inject soft persistent cache storage");
-    const storage = await createSoftPersistentStorage(config?.cache);
-    if (storage) {
-      appConfig.cache = { ...config?.cache, storage };
-      logger.debug("createApp: soft persistent cache storage ready");
-    } else {
-      logger.debug("createApp: soft persistent cache storage unavailable");
-    }
+  if (shouldInjectCacheStorage(config)) {
+    logger.debug("createApp: inject memory-first cache storage");
+    const storage = await createAppKitCacheStorage({
+      cache: config?.cache,
+      preferLakebase: Boolean(lakebase) || usesPlugin(config, LAKEBASE_PLUGIN),
+    });
+    appConfig.cache = { ...config?.cache, storage };
+    logger.debug("createApp: memory-first cache storage ready", {
+      persistent: storage.isPersistent(),
+    });
   }
 
   if (interceptors.length === 0) {

package/src/{_cache-storage.ts → cache-storage.ts}

@@ -1,5 +1,5 @@
 /**
- * Soft-fail Lakebase cache storage for AppKit's persistent cache.
+ * Memory-first AppKit cache storage with soft-fail Lakebase persistence.
  *
  * AppKit's `PersistentStorage.initialize()` runs DDL migrations and throws on
  * any step failure. With `cache.strictPersistence: true` that throw makes
@@ -8,18 +8,25 @@
  * usable table keeps serving.
  *
  * `PersistentStorage` is not on AppKit's public export map. The deep load is
- * lazy and best-effort: if the installed AppKit layout changes, this returns
- * `undefined` and `createApp` leaves AppKit on its default cache path.
+ * lazy and best-effort: if the installed AppKit layout changes, Lakebase is
+ * skipped and the adapter keeps its project-scoped disk persistence.
  *
  * @module
  */
 
+import { EventEmitter } from "node:events";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { createLakebasePool, getWorkspaceClient, type CacheConfig } from "@databricks/appkit";
+import {
+  closeCache,
+  createCache,
+  flushCache,
+  projectCache,
+  type CacheOptions,
+} from "@dbx-tools/cache/cache";
 import { postgresConnectionOptions } from "@dbx-tools/postgres";
 import { errorUtils, hash, log } from "@dbx-tools/shared-core";
-import { LRUCache } from "lru-cache";
 import { handleOwnershipMigrationError } from "./migration.ts";
 
 const logger = log.logger("cache-storage");
@@ -32,9 +39,17 @@ interface CacheEntry<T = unknown> {
   value: T;
 }
 
-/** Bounds for the process-local cache layered over persistent AppKit storage. */
-export interface L1CacheStorageOptions {
-  maxBytes?: number;
+/** Options for AppKit's memory-first cache storage adapter. */
+export interface AppKitCacheStorageOptions {
+  /** Native AppKit cache configuration. */
+  cache?: CacheConfig;
+  /** Whether to attempt AppKit's Lakebase PersistentStorage. Defaults to true. */
+  preferLakebase?: boolean;
+  /** Portable disk scope used when Lakebase is unavailable. */
+  diskScope?: string;
+  /** Write-behind coalescing delay in milliseconds. */
+  writeDelayMs?: number;
+  /** Maximum entries retained in the process-local memory primary. */
   maxEntries?: number;
 }
 
@@ -54,95 +69,126 @@ type PersistentStorageConstructor = new (
 
 let persistentStorageCtor: PersistentStorageConstructor | undefined | null = null;
 
-/** Process-local LRU that avoids a persistent cache query on every warm hit. */
-export class L1CacheStorage implements CacheStorage {
-  private readonly entries: LRUCache<string, CacheEntry>;
+class AppKitStorageLevel extends EventEmitter {
+  readonly opts = {};
+
+  constructor(private readonly storage: CacheStorage) {
+    super();
+  }
+
+  async get<T>(key: string): Promise<T | undefined> {
+    const entry = await this.storage.get<T>(key);
+    if (!entry) return undefined;
+    if (entry.expiry <= Date.now()) {
+      await this.storage.delete(key);
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  async set(key: string, value: unknown, ttl?: number): Promise<void> {
+    await this.storage.set(key, {
+      value,
+      expiry: Date.now() + (ttl ?? 60_000),
+    });
+  }
+
+  async delete(key: string): Promise<boolean> {
+    await this.storage.delete(key);
+    return true;
+  }
+
+  clear(): Promise<void> {
+    return this.storage.clear();
+  }
+
+  has(key: string): Promise<boolean> {
+    return this.storage.has(key);
+  }
+
+  disconnect(): Promise<void> {
+    return this.storage.close();
+  }
+}
+
+/** Memory-first AppKit CacheStorage backed by @dbx-tools/cache. */
+export class AppKitCacheStorage implements CacheStorage {
+  private readonly cache: ReturnType<typeof createCache>;
+  private readonly keys = new Set<string>();
+  private closed = false;
 
   constructor(
-    private readonly storage: CacheStorage,
-    options: L1CacheStorageOptions = {},
+    cache: ReturnType<typeof createCache>,
+    private readonly persistent: CacheStorage | undefined,
   ) {
-    this.entries = new LRUCache({
-      max: positiveBound(options.maxEntries, 1_000, "maxEntries"),
-      maxSize: positiveBound(options.maxBytes, 64 * 1024 * 1024, "maxBytes"),
-      sizeCalculation: (entry, key) => retainedSize(key, entry),
-    });
+    this.cache = cache;
   }
 
   async get<T>(key: string): Promise<CacheEntry<T> | null> {
-    const local = this.entries.get(key);
-    if (local) return local as CacheEntry<T>;
-    const persisted = await this.storage.get<T>(key);
-    if (persisted && persisted.expiry > Date.now()) this.retain(key, persisted);
-    return persisted;
+    const entry = await this.cache.get<CacheEntry<T>>(key);
+    if (!entry) return null;
+    this.keys.add(key);
+    return entry;
   }
 
   async set<T>(key: string, entry: CacheEntry<T>): Promise<void> {
-    await this.storage.set(key, entry);
-    this.retain(key, entry);
+    const ttl = entry.expiry - Date.now();
+    if (ttl <= 0) {
+      await this.delete(key);
+      return;
+    }
+    await this.cache.set(key, entry, { ttl });
+    this.keys.add(key);
   }
 
   async delete(key: string): Promise<void> {
-    await this.storage.delete(key);
-    this.entries.delete(key);
+    await this.cache.delete(key);
+    this.keys.delete(key);
   }
 
   async clear(): Promise<void> {
-    await this.storage.clear();
-    this.entries.clear();
+    await this.cache.clear();
+    this.keys.clear();
   }
 
   async has(key: string): Promise<boolean> {
-    if (this.entries.has(key)) return true;
-    return this.storage.has(key);
+    return this.cache.has(key);
   }
 
-  size(): Promise<number> {
-    return this.storage.size();
+  async size(): Promise<number> {
+    return this.persistent ? this.persistent.size() : this.keys.size;
   }
 
   isPersistent(): boolean {
-    return this.storage.isPersistent();
+    return true;
   }
 
-  healthCheck(): Promise<boolean> {
-    return this.storage.healthCheck();
+  async healthCheck(): Promise<boolean> {
+    return this.persistent ? this.persistent.healthCheck() : true;
+  }
+
+  /** Drain tracked write-behind persistence without closing the storage. */
+  flush(): Promise<void> {
+    return flushCache(this.cache);
   }
 
   async close(): Promise<void> {
-    this.entries.clear();
-    await this.storage.close();
+    if (this.closed) return;
+    await closeCache(this.cache);
+    this.closed = true;
+    this.keys.clear();
   }
 
   /** Forward AppKit's runtime-only persistent cleanup hook when available. */
   async cleanupExpired(): Promise<number> {
     const cleanup = (
-      this.storage as CacheStorage & {
-        cleanupExpired?: () => Promise<number>;
-      }
-    ).cleanupExpired;
-    return cleanup ? cleanup.call(this.storage) : 0;
-  }
-
-  private retain<T>(key: string, entry: CacheEntry<T>): void {
-    const ttl = entry.expiry - Date.now();
-    if (ttl > 0) this.entries.set(key, entry, { ttl });
-  }
-}
-
-function positiveBound(value: number | undefined, fallback: number, name: string): number {
-  const resolved = value ?? fallback;
-  if (!Number.isFinite(resolved) || resolved <= 0) {
-    throw new RangeError(`${name} must be a finite positive number`);
-  }
-  return Math.floor(resolved);
-}
-
-function retainedSize(key: string, entry: CacheEntry): number {
-  try {
-    return Buffer.byteLength(key) + Buffer.byteLength(JSON.stringify(entry));
-  } catch {
-    return Number.MAX_SAFE_INTEGER;
+      this.persistent as
+        | (CacheStorage & {
+            cleanupExpired?: () => Promise<number>;
+          })
+        | undefined
+    )?.cleanupExpired;
+    return cleanup && this.persistent ? cleanup.call(this.persistent) : 0;
   }
 }
 
@@ -257,9 +303,9 @@ export async function probeStorage(storage: PersistentStorageBase): Promise<void
 /**
  * Build a soft-fail Lakebase cache storage when a pool can be created and
  * AppKit's PersistentStorage can be loaded. Returns `undefined` otherwise so
- * AppKit can fall through to its normal cache path.
+ * the caller can use portable disk persistence.
  */
-export async function createSoftPersistentStorage(
+async function createPersistentStorage(
   cache: CacheConfig | undefined,
 ): Promise<CacheStorage | undefined> {
   const PersistentStorage = loadPersistentStorage();
@@ -281,10 +327,7 @@ export async function createSoftPersistentStorage(
     }
     await storage.initialize();
     await probeStorage(storage);
-    return new L1CacheStorage(storage, {
-      maxBytes: cache?.maxBytes,
-      maxEntries: cache?.maxSize,
-    });
+    return storage;
   } catch (err) {
     logger.debug("soft persistent cache unavailable", {
       error: errorUtils.errorMessage(err),
@@ -295,3 +338,27 @@ export async function createSoftPersistentStorage(
     return undefined;
   }
 }
+
+/**
+ * Create AppKit CacheStorage with bounded memory first and tracked persistence.
+ * Lakebase remains AppKit's persistent owner when available; otherwise the
+ * shared project-scoped portable disk level is used.
+ */
+export async function createAppKitCacheStorage(
+  options: AppKitCacheStorageOptions = {},
+): Promise<AppKitCacheStorage> {
+  const nativeCache = options.cache;
+  const persistent =
+    options.preferLakebase === false ? undefined : await createPersistentStorage(nativeCache);
+  const common: CacheOptions = {
+    maxEntries: options.maxEntries ?? nativeCache?.maxSize,
+    writeDelayMs: options.writeDelayMs,
+  };
+  const cache = persistent
+    ? createCache({
+        ...common,
+        levels: [{ name: "appkit-persistent", store: new AppKitStorageLevel(persistent) }],
+      })
+    : projectCache(options.diskScope ?? "appkit", common);
+  return new AppKitCacheStorage(cache, persistent);
+}

package/src/files-cache.ts

@@ -1,28 +1,23 @@
 /**
- * AppKit-global filesystem cache with user-isolated process-local LRU values.
+ * AppKit-global filesystem cache with user-isolated process-local values.
  *
  * @module
  */
 
 import { Plugin, toPlugin, type BasePluginConfig, type PluginManifest } from "@databricks/appkit";
+import { cacheKeys, closeCache, createCache, getOrSet } from "@dbx-tools/cache/cache";
 import { errorUtils, log, object } from "@dbx-tools/shared-core";
 import { posixPath, type CacheValue, type FileSystemCache } from "@dbx-tools/shared-fs";
-import { LRUCache } from "lru-cache";
 
 const DEFAULT_TTL_MS = 60_000;
 const DEFAULT_INVALIDATION_BATCH_MS = 25;
 const DEFAULT_MAX_ENTRIES = 1_000;
-const DEFAULT_MAX_BYTES = 64 * 1024 * 1024;
 const DEFAULT_MAX_SCOPES = 256;
 const logger = log.logger("files-cache");
 
-interface RetainedEntry {
-  value: CacheValue;
-}
-
 interface ScopeState {
   cache: FileSystemCache;
-  entries: LRUCache<string, RetainedEntry>;
+  entries: ReturnType<typeof createCache>;
   group: GroupState;
   scope: ResolvedFilesCacheScope;
   sources: Map<string, Promise<object>>;
@@ -36,7 +31,6 @@ interface GroupState {
 
 interface ResolvedFilesCacheConfig {
   invalidationBatchMs: number;
-  maxBytes: number;
   maxEntries: number;
   maxScopes: number;
   ttlMs: number;
@@ -57,8 +51,6 @@ export interface FilesCachePluginConfig extends BasePluginConfig {
   invalidationBatchMs?: number;
   /** Maximum entries retained in each user L1. Defaults to 1,000. */
   maxEntries?: number;
-  /** Maximum retained bytes in each user L1. Defaults to 64 MiB. */
-  maxBytes?: number;
   /** Maximum active user scopes retained by the process. Defaults to 256. */
   maxScopes?: number;
 }
@@ -101,7 +93,7 @@ export interface FilesCacheExports {
 export class FilesCacheManager {
   private readonly config: ResolvedFilesCacheConfig;
   private readonly groups = new Map<string, GroupState>();
-  private readonly scopes: LRUCache<string, ScopeState>;
+  private readonly scopes: ReturnType<typeof createCache>;
 
   constructor(config: FilesCachePluginConfig = {}) {
     this.config = {
@@ -112,15 +104,9 @@ export class FilesCacheManager {
         "invalidationBatchMs",
       ),
       maxEntries: positiveInteger(config.maxEntries, DEFAULT_MAX_ENTRIES, "maxEntries"),
-      maxBytes: positiveInteger(config.maxBytes, DEFAULT_MAX_BYTES, "maxBytes"),
       maxScopes: positiveInteger(config.maxScopes, DEFAULT_MAX_SCOPES, "maxScopes"),
     };
-    this.scopes = new LRUCache({
-      max: this.config.maxScopes,
-      dispose: (state) => {
-        state.group.scopes.delete(state);
-      },
-    });
+    this.scopes = createCache({ maxEntries: this.config.maxScopes, useClone: false });
   }
 
   /** Return one user-isolated cache within a host/workspace invalidation group. */
@@ -158,12 +144,23 @@ export class FilesCacheManager {
       userKey: scope.userKey,
       workspaceId: scope.workspaceId,
     });
-    let state = this.scopes.get(scopeKey);
+    let state = await this.scopes.get<ScopeState>(scopeKey);
     if (!state) {
+      if ([...cacheKeys(this.scopes)].length >= this.config.maxScopes) {
+        const oldestKey = cacheKeys(this.scopes).next().value;
+        if (oldestKey) {
+          const oldest = await this.scopes.get<ScopeState>(oldestKey);
+          if (oldest) {
+            oldest.group.scopes.delete(oldest);
+            await closeCache(oldest.entries);
+          }
+          await this.scopes.delete(oldestKey);
+        }
+      }
       const group = this.group(scope);
       state = this.createScope(scope, group);
       group.scopes.add(state);
-      this.scopes.set(scopeKey, state);
+      await this.scopes.set(scopeKey, state);
     }
     return state;
   }
@@ -180,7 +177,11 @@ export class FilesCacheManager {
       group.timer = undefined;
     }
     await this.flush();
-    this.scopes.clear();
+    for (const key of cacheKeys(this.scopes)) {
+      const state = await this.scopes.get<ScopeState>(key);
+      if (state) await closeCache(state.entries);
+    }
+    await closeCache(this.scopes);
     this.groups.clear();
   }
 
@@ -203,11 +204,7 @@ export class FilesCacheManager {
     const state = {} as ScopeState;
     state.scope = scope;
     state.group = group;
-    state.entries = new LRUCache({
-      max: this.config.maxEntries,
-      maxSize: this.config.maxBytes,
-      sizeCalculation: (entry, cacheKey) => retainedSize(cacheKey, entry),
-    });
+    state.entries = createCache({ maxEntries: this.config.maxEntries, useClone: false });
     state.sources = new Map();
     state.cache = {
       read: <T extends CacheValue>(cacheKey: string, load: () => T | Promise<T>) =>
@@ -224,16 +221,21 @@ export class FilesCacheManager {
     load: () => T | Promise<T>,
   ): Promise<T> {
     if (!state.group.pending.has(key)) {
-      const retained = state.entries.get(key);
-      if (retained) return retained.value as T;
+      const retained = await state.entries.get<T>(key);
+      if (retained !== undefined) return retained;
     }
-    const value = await load();
-    state.entries.set(key, { value }, { ttl: state.scope.ttlMs });
-    return value;
+    if (state.group.pending.has(key)) {
+      const value = await load();
+      await state.entries.set(key, value, { ttl: state.scope.ttlMs });
+      return value;
+    }
+    return (await getOrSet(state.entries, key, () => Promise.resolve(load()), {
+      ttl: state.scope.ttlMs,
+    })) as T;
   }
 
   private *keys(state: ScopeState): Iterable<string> {
-    for (const key of state.entries.keys()) {
+    for (const key of cacheKeys(state.entries)) {
       if (!state.group.pending.has(key)) yield key;
     }
   }
@@ -259,12 +261,12 @@ export class FilesCacheManager {
     const keys = [...group.pending];
     group.pending.clear();
     for (const state of group.scopes) {
-      for (const key of keys) state.entries.delete(key);
+      await Promise.all(keys.map((key) => state.entries.delete(key)));
     }
   }
 }
 
-/** AppKit plugin that owns process-local filesystem LRU caches. */
+/** AppKit plugin that owns process-local filesystem caches. */
 export class FilesCachePlugin extends Plugin<FilesCachePluginConfig> {
   static manifest = {
     name: "files-cache",
@@ -324,11 +326,3 @@ function positiveDuration(value: number | undefined, fallback: number, name: str
 function positiveInteger(value: number | undefined, fallback: number, name: string): number {
   return Math.floor(positiveDuration(value, fallback, name));
 }
-
-function retainedSize(key: string, entry: RetainedEntry): number {
-  try {
-    return Buffer.byteLength(key) + Buffer.byteLength(JSON.stringify(entry.value));
-  } catch {
-    return Number.MAX_SAFE_INTEGER;
-  }
-}