@holo-js/cache 0.1.8 → 0.2.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CacheFacade, CacheRepository, CacheFlexibleTtlInput, CacheFallback, CacheValueResolver, CacheDriverContract, CacheOptionalPackageError, CacheDependencyIndex, CacheQueryBridge, CacheKeyInput, CacheDependencyDescriptor, CacheRuntimeBindings, CacheKey, CacheTtlInput, CacheLockContract, defineCacheKey, normalizeCacheTtl, serializeCacheValue, deserializeCacheValue } from './contracts.js';
+import { CacheFlexibleTtlInput, CacheFacade, CacheRepository, CacheFallback, CacheValueResolver, CacheOptionalPackageError, CacheDriverContract, CacheDependencyIndex, CacheQueryBridge, CacheKeyInput, CacheDependencyDescriptor, CacheRuntimeBindings, CacheKey, CacheTtlInput, CacheLockContract, defineCacheKey, normalizeCacheTtl, serializeCacheValue, deserializeCacheValue } from './contracts.js';
 export { CacheConfigError, CacheDriverGetResult, CacheDriverPutInput, CacheDriverResolutionError, CacheError, CacheErrorCode, CacheFallbackResolver, CacheInvalidNumericMutationError, CacheInvalidTtlError, CacheLockAcquisitionError, CacheQueryIntegrationError, CacheRuntimeNotConfiguredError, CacheSerializationError, NormalizedCacheTtl, cacheContractsInternals, isCacheKey, resolveCacheKey } from './contracts.js';
 import { HoloDatabaseConfig, NormalizedHoloDatabaseConfig, HoloDatabaseConnectionConfig, HoloRedisConfig, NormalizedHoloRedisConfig, NormalizedHoloRedisConnectionConfig, NormalizedHoloCacheConfig, HoloCacheConfig } from '@holo-js/config';
 export { CacheDatabaseDriverConfig, CacheDriver, CacheDriverConfig, CacheFileDriverConfig, CacheMemoryDriverConfig, CacheRedisDriverConfig, HoloCacheConfig, NormalizedCacheDatabaseDriverConfig, NormalizedCacheDriverConfig, NormalizedCacheFileDriverConfig, NormalizedCacheMemoryDriverConfig, NormalizedCacheRedisDriverConfig, NormalizedHoloCacheConfig, defineCacheConfig } from '@holo-js/config';
@@ -13,11 +13,12 @@ type NormalizedFlexibleTtl = {
     readonly freshSeconds: number;
     readonly staleSeconds: number;
 };
+declare function normalizeFlexibleTtl(ttl: CacheFlexibleTtlInput): NormalizedFlexibleTtl;
+declare function isFlexibleEnvelope<TValue>(value: unknown): value is FlexibleEnvelope<TValue>;
+
 declare function resolveFallback<TValue>(fallback: CacheFallback<TValue>): Promise<TValue> | TValue;
 declare function resolveValue<TValue>(callback: CacheValueResolver<TValue>): Promise<Awaited<TValue>>;
 declare function resolveDriverKey(driverName?: string): string;
-declare function normalizeFlexibleTtl(ttl: CacheFlexibleTtlInput): NormalizedFlexibleTtl;
-declare function isFlexibleEnvelope<TValue>(value: unknown): value is FlexibleEnvelope<TValue>;
 declare function getOrCreateRepository(driverName?: string): CacheRepository;
 declare const cacheFacade: CacheFacade;
 declare const cacheFacadeInternals: {
@@ -30,6 +31,9 @@ declare const cacheFacadeInternals: {
     resolveValue: typeof resolveValue;
 };
 
+type OptionalDriverModuleLoader<TModule> = () => Promise<TModule>;
+declare function normalizeOptionalDriverModuleLoadError(error: unknown, expectedSpecifier: string, message: string): CacheOptionalPackageError | unknown;
+
 type DatabaseCacheDriverOptions = {
     readonly name: string;
     readonly connectionName: string;
@@ -41,19 +45,18 @@ type DatabaseCacheDriverOptions = {
 type DatabaseCacheDriverModule = {
     createDatabaseCacheDriver(options: DatabaseCacheDriverOptions): CacheDriverContract;
 };
-type DatabaseDriverModuleLoader = () => Promise<DatabaseCacheDriverModule>;
+type DatabaseDriverModuleLoader = OptionalDriverModuleLoader<DatabaseCacheDriverModule>;
 declare function isNormalizedDatabaseConfig(config: HoloDatabaseConfig | NormalizedHoloDatabaseConfig): config is NormalizedHoloDatabaseConfig;
 declare function normalizeRuntimeDatabaseConfig(config: HoloDatabaseConfig | NormalizedHoloDatabaseConfig | undefined): NormalizedHoloDatabaseConfig | undefined;
 declare function resolveSharedDatabaseConnection(databaseConfig: NormalizedHoloDatabaseConfig | undefined, connectionName: string): HoloDatabaseConnectionConfig | string;
 declare function isModuleNotFoundError$1(error: unknown, expectedSpecifier?: string): boolean;
-declare function normalizeDatabaseModuleLoadError(error: unknown, expectedSpecifier?: string): CacheOptionalPackageError | unknown;
-declare function loadDatabaseDriverModule(): Promise<DatabaseCacheDriverModule>;
+declare function normalizeDatabaseModuleLoadError(error: unknown, expectedSpecifier?: string): ReturnType<typeof normalizeOptionalDriverModuleLoadError>;
 declare function setDatabaseDriverModuleLoader(loader: DatabaseDriverModuleLoader): void;
 declare function resetDatabaseDriverModuleLoader(): void;
 declare const cacheDbInternals: {
     isModuleNotFoundError: typeof isModuleNotFoundError$1;
     isNormalizedDatabaseConfig: typeof isNormalizedDatabaseConfig;
-    loadDatabaseDriverModule: typeof loadDatabaseDriverModule;
+    loadDatabaseDriverModule: OptionalDriverModuleLoader<DatabaseCacheDriverModule>;
     normalizeDatabaseModuleLoadError: typeof normalizeDatabaseModuleLoadError;
     normalizeRuntimeDatabaseConfig: typeof normalizeRuntimeDatabaseConfig;
     resolveSharedDatabaseConnection: typeof resolveSharedDatabaseConnection;
@@ -119,19 +122,18 @@ type RedisCacheDriverOptions = {
 type RedisCacheDriverModule = {
     createRedisCacheDriver(options: RedisCacheDriverOptions): CacheDriverContract;
 };
-type RedisDriverModuleLoader = () => Promise<RedisCacheDriverModule>;
+type RedisDriverModuleLoader = OptionalDriverModuleLoader<RedisCacheDriverModule>;
 declare function isNormalizedRedisConfig(config: HoloRedisConfig | NormalizedHoloRedisConfig): config is NormalizedHoloRedisConfig;
 declare function normalizeRuntimeRedisConfig(config: HoloRedisConfig | NormalizedHoloRedisConfig | undefined): NormalizedHoloRedisConfig | undefined;
 declare function resolveSharedRedisConnection(redisConfig: NormalizedHoloRedisConfig | undefined, connectionName: string): NormalizedHoloRedisConnectionConfig;
 declare function isModuleNotFoundError(error: unknown, expectedSpecifier?: string): boolean;
-declare function normalizeRedisModuleLoadError(error: unknown, expectedSpecifier?: string): CacheOptionalPackageError | unknown;
-declare function loadRedisDriverModule(): Promise<RedisCacheDriverModule>;
+declare function normalizeRedisModuleLoadError(error: unknown, expectedSpecifier?: string): ReturnType<typeof normalizeOptionalDriverModuleLoadError>;
 declare function setRedisDriverModuleLoader(loader: RedisDriverModuleLoader): void;
 declare function resetRedisDriverModuleLoader(): void;
 declare const cacheRedisInternals: {
     isModuleNotFoundError: typeof isModuleNotFoundError;
     isNormalizedRedisConfig: typeof isNormalizedRedisConfig;
-    loadRedisDriverModule: typeof loadRedisDriverModule;
+    loadRedisDriverModule: OptionalDriverModuleLoader<RedisCacheDriverModule>;
     normalizeRedisModuleLoadError: typeof normalizeRedisModuleLoadError;
     normalizeRuntimeRedisConfig: typeof normalizeRuntimeRedisConfig;
     resolveSharedRedisConnection: typeof resolveSharedRedisConnection;

package/dist/index.mjs

@@ -21,6 +21,78 @@ import {
 // src/index.ts
 import { defineCacheConfig } from "@holo-js/config";
 
+// src/flexible.ts
+function normalizeFlexibleTtl(ttl) {
+  const freshSeconds = "fresh" in ttl ? ttl.fresh : ttl[0];
+  const staleSeconds = "stale" in ttl ? ttl.stale : ttl[1];
+  if (!Number.isInteger(freshSeconds) || freshSeconds < 0) {
+    throw new CacheInvalidTtlError("[@holo-js/cache] Flexible fresh TTL must be an integer greater than or equal to 0.");
+  }
+  if (!Number.isInteger(staleSeconds) || staleSeconds < freshSeconds) {
+    throw new CacheInvalidTtlError("[@holo-js/cache] Flexible stale TTL must be an integer greater than or equal to the fresh TTL.");
+  }
+  return Object.freeze({
+    freshSeconds,
+    staleSeconds
+  });
+}
+function createFlexibleEnvelope(ttl, value, now = Date.now()) {
+  return Object.freeze({
+    __holo_cache_flexible: true,
+    value,
+    freshUntil: now + ttl.freshSeconds * 1e3,
+    staleUntil: now + ttl.staleSeconds * 1e3
+  });
+}
+function isFlexibleEnvelope(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const envelope = value;
+  return envelope.__holo_cache_flexible === true && typeof envelope.freshUntil === "number" && Number.isFinite(envelope.freshUntil) && typeof envelope.staleUntil === "number" && Number.isFinite(envelope.staleUntil) && "value" in envelope;
+}
+function resolveFlexibleEnvelopeState(envelope, now = Date.now()) {
+  if (now <= envelope.freshUntil) {
+    return "fresh";
+  }
+  if (now <= envelope.staleUntil) {
+    return "stale";
+  }
+  return "expired";
+}
+async function resolveFlexibleCachedValue(options) {
+  const normalizedTtl = normalizeFlexibleTtl(options.ttl);
+  const cached = await options.read();
+  const now = options.now?.() ?? Date.now();
+  if (isFlexibleEnvelope(cached)) {
+    const state = resolveFlexibleEnvelopeState(cached, now);
+    if (state === "fresh") {
+      return cached.value;
+    }
+    if (state === "stale") {
+      const refreshLock2 = options.createLock(normalizedTtl);
+      void refreshLock2.get(async () => {
+        await options.refresh(normalizedTtl);
+        return true;
+      }).catch(() => void 0);
+      return cached.value;
+    }
+  }
+  const refreshLock = options.createLock(normalizedTtl);
+  const refreshed = await refreshLock.block(
+    options.blockSeconds?.(normalizedTtl) ?? 1,
+    async () => options.refresh(normalizedTtl)
+  );
+  if (refreshed !== false) {
+    return refreshed;
+  }
+  const retried = await options.read();
+  if (isFlexibleEnvelope(retried) && resolveFlexibleEnvelopeState(retried, now) !== "expired") {
+    return retried.value;
+  }
+  return options.refresh(normalizedTtl);
+}
+
 // src/runtime-shared.ts
 import {
   holoCacheDefaults,
@@ -28,36 +100,19 @@ import {
 } from "@holo-js/config";
 
 // src/db.ts
-import { createRequire } from "module";
-import { join } from "path";
-import { pathToFileURL } from "url";
 import {
   normalizeDatabaseConfig
 } from "@holo-js/config";
+
+// src/optional-driver.ts
+import { createRequire } from "module";
+import { join } from "path";
+import { pathToFileURL } from "url";
+var CACHE_DRIVER_DISPOSE_SYMBOL = /* @__PURE__ */ Symbol.for("holo.cache.driver.dispose");
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function isNormalizedDatabaseConfig(config) {
-  return typeof config === "object" && config !== null && typeof config.connections === "object" && config.connections !== null;
-}
-function normalizeRuntimeDatabaseConfig(config) {
-  if (!config) return void 0;
-  return normalizeDatabaseConfig(config);
-}
-function resolveSharedDatabaseConnection(databaseConfig, connectionName) {
-  if (!databaseConfig) {
-    throw new CacheDriverResolutionError(
-      `[@holo-js/cache] Database cache driver "${connectionName}" requires a top-level database config from config/database.ts.`
-    );
-  }
-  const connection = databaseConfig.connections[connectionName];
-  if (connection) return connection;
-  const availableConnections = Object.keys(databaseConfig.connections);
-  throw new CacheDriverResolutionError(
-    `[@holo-js/cache] Database cache connection "${connectionName}" was not found in config/database.ts. Available connections: ${availableConnections.join(", ") || "(none)"}.`
-  );
-}
-function isModuleNotFoundError(error, expectedSpecifier = "@holo-js/cache-db") {
+function isOptionalDriverModuleNotFoundError(error, expectedSpecifier) {
   if (!error || typeof error !== "object") {
     return false;
   }
@@ -73,63 +128,60 @@ function isModuleNotFoundError(error, expectedSpecifier = "@holo-js/cache-db") {
     return true;
   }
   if ("cause" in error) {
-    return isModuleNotFoundError(error.cause, expectedSpecifier);
+    return isOptionalDriverModuleNotFoundError(error.cause, expectedSpecifier);
   }
   return false;
 }
-function normalizeDatabaseModuleLoadError(error, expectedSpecifier = "@holo-js/cache-db") {
-  if (isModuleNotFoundError(error, expectedSpecifier)) {
-    return new CacheOptionalPackageError(
-      "[@holo-js/cache] Database cache support requires @holo-js/cache-db to be installed.",
-      { cause: error }
-    );
+function normalizeOptionalDriverModuleLoadError(error, expectedSpecifier, message) {
+  if (isOptionalDriverModuleNotFoundError(error, expectedSpecifier)) {
+    return new CacheOptionalPackageError(message, { cause: error });
   }
   return error;
 }
-async function importDatabaseDriverModuleFromProject(specifier) {
+async function importOptionalDriverModuleFromProject(specifier) {
   const projectRequire = createRequire(join(process.cwd(), "package.json"));
   return await import(pathToFileURL(projectRequire.resolve(specifier)).href);
 }
-async function loadDatabaseDriverModule() {
-  const specifier = "@holo-js/cache-db";
-  try {
-    return await import(
-      /* webpackIgnore: true */
-      specifier
-    );
-  } catch (error) {
-    if (!isModuleNotFoundError(error, specifier)) {
-      throw normalizeDatabaseModuleLoadError(error, specifier);
-    }
+function createOptionalDriverModuleLoader(specifier, missingPackageMessage) {
+  return async () => {
     try {
-      return await importDatabaseDriverModuleFromProject(specifier);
-    } catch (fallbackError) {
-      throw normalizeDatabaseModuleLoadError(fallbackError, specifier);
+      return await import(
+        /* webpackIgnore: true */
+        specifier
+      );
+    } catch (error) {
+      if (!isOptionalDriverModuleNotFoundError(error, specifier)) {
+        throw normalizeOptionalDriverModuleLoadError(error, specifier, missingPackageMessage);
+      }
+      try {
+        return await importOptionalDriverModuleFromProject(specifier);
+      } catch (fallbackError) {
+        throw normalizeOptionalDriverModuleLoadError(fallbackError, specifier, missingPackageMessage);
+      }
     }
-  }
-}
-var databaseDriverModuleLoader = loadDatabaseDriverModule;
-function setDatabaseDriverModuleLoader(loader) {
-  databaseDriverModuleLoader = loader;
-}
-function resetDatabaseDriverModuleLoader() {
-  databaseDriverModuleLoader = loadDatabaseDriverModule;
+  };
 }
-var LazyDatabaseCacheDriver = class {
-  constructor(options) {
-    this.options = options;
+var LazyOptionalCacheDriver = class {
+  constructor(lazyOptions) {
+    this.lazyOptions = lazyOptions;
   }
-  driver = "database";
   driverInstance;
   pending;
+  disposalGeneration = 0;
   get name() {
-    return this.options.name;
+    return this.lazyOptions.name;
+  }
+  get driver() {
+    return this.lazyOptions.driver;
   }
   async resolveDriver() {
     if (this.driverInstance) return this.driverInstance;
-    this.pending ??= databaseDriverModuleLoader().then((module) => {
-      const driver = module.createDatabaseCacheDriver(this.options);
-      this.driverInstance = driver;
+    const pendingGeneration = this.disposalGeneration;
+    this.pending ??= this.lazyOptions.loadModule().then((module) => {
+      const driver = this.lazyOptions.createDriver(module, this.lazyOptions.options);
+      if (this.disposalGeneration === pendingGeneration) {
+        this.driverInstance = driver;
+      }
       return driver;
     }).finally(() => {
       this.pending = void 0;
@@ -139,6 +191,26 @@ var LazyDatabaseCacheDriver = class {
   async withDriver(callback) {
     return callback(await this.resolveDriver());
   }
+  [CACHE_DRIVER_DISPOSE_SYMBOL]() {
+    if (this.lazyOptions.disposeDriver !== true) {
+      return;
+    }
+    const pending = this.pending;
+    const driverInstance = this.driverInstance;
+    this.disposalGeneration += 1;
+    this.driverInstance = void 0;
+    this.pending = void 0;
+    if (driverInstance) {
+      const disposable = driverInstance;
+      disposable[CACHE_DRIVER_DISPOSE_SYMBOL]?.();
+      return;
+    }
+    pending?.then((driver) => {
+      const disposable = driver;
+      disposable[CACHE_DRIVER_DISPOSE_SYMBOL]?.();
+    }).catch(() => {
+    });
+  }
   createLockProxy(name, seconds) {
     let lockPromise;
     const resolveLock = async () => {
@@ -183,8 +255,58 @@ var LazyDatabaseCacheDriver = class {
     return this.createLockProxy(name, seconds);
   }
 };
+function createLazyOptionalCacheDriver(options) {
+  return new LazyOptionalCacheDriver(options);
+}
+
+// src/db.ts
+var DATABASE_CACHE_PACKAGE = "@holo-js/cache-db";
+var DATABASE_CACHE_MISSING_MESSAGE = "[@holo-js/cache] Database cache support requires @holo-js/cache-db to be installed.";
+function isNormalizedDatabaseConfig(config) {
+  return typeof config === "object" && config !== null && typeof config.connections === "object" && config.connections !== null;
+}
+function normalizeRuntimeDatabaseConfig(config) {
+  if (!config) return void 0;
+  return normalizeDatabaseConfig(config);
+}
+function resolveSharedDatabaseConnection(databaseConfig, connectionName) {
+  if (!databaseConfig) {
+    throw new CacheDriverResolutionError(
+      `[@holo-js/cache] Database cache driver "${connectionName}" requires a top-level database config from config/database.ts.`
+    );
+  }
+  const connection = databaseConfig.connections[connectionName];
+  if (connection) return connection;
+  const availableConnections = Object.keys(databaseConfig.connections);
+  throw new CacheDriverResolutionError(
+    `[@holo-js/cache] Database cache connection "${connectionName}" was not found in config/database.ts. Available connections: ${availableConnections.join(", ") || "(none)"}.`
+  );
+}
+function isModuleNotFoundError(error, expectedSpecifier = "@holo-js/cache-db") {
+  return isOptionalDriverModuleNotFoundError(error, expectedSpecifier);
+}
+function normalizeDatabaseModuleLoadError(error, expectedSpecifier = "@holo-js/cache-db") {
+  return normalizeOptionalDriverModuleLoadError(error, expectedSpecifier, DATABASE_CACHE_MISSING_MESSAGE);
+}
+var loadDatabaseDriverModule = createOptionalDriverModuleLoader(
+  DATABASE_CACHE_PACKAGE,
+  DATABASE_CACHE_MISSING_MESSAGE
+);
+var databaseDriverModuleLoader = loadDatabaseDriverModule;
+function setDatabaseDriverModuleLoader(loader) {
+  databaseDriverModuleLoader = loader;
+}
+function resetDatabaseDriverModuleLoader() {
+  databaseDriverModuleLoader = loadDatabaseDriverModule;
+}
 function createDatabaseCacheDriver(options) {
-  return new LazyDatabaseCacheDriver(options);
+  return createLazyOptionalCacheDriver({
+    name: options.name,
+    driver: "database",
+    options,
+    loadModule: databaseDriverModuleLoader,
+    createDriver: (module, driverOptions) => module.createDatabaseCacheDriver(driverOptions)
+  });
 }
 var cacheDbInternals = {
   isModuleNotFoundError,
@@ -845,13 +967,11 @@ function createMemoryCacheDriver(options) {
 }
 
 // src/redis.ts
-import { createRequire as createRequire2 } from "module";
-import { join as join3 } from "path";
-import { pathToFileURL as pathToFileURL2 } from "url";
 import {
   normalizeRedisConfig
 } from "@holo-js/config";
-var CACHE_DRIVER_DISPOSE_SYMBOL = /* @__PURE__ */ Symbol.for("holo.cache.driver.dispose");
+var REDIS_CACHE_PACKAGE = "@holo-js/cache-redis";
+var REDIS_CACHE_MISSING_MESSAGE = "[@holo-js/cache] Redis cache support requires @holo-js/cache-redis to be installed.";
 function isNormalizedRedisConfig(config) {
   return typeof config.default === "string" && typeof config.connections === "object" && config.connections !== null && Object.values(config.connections).every((connection) => {
     return typeof connection === "object" && connection !== null && "name" in connection && "host" in connection && "port" in connection && typeof connection.name === "string" && typeof connection.host === "string" && typeof connection.port === "number";
@@ -861,9 +981,6 @@ function normalizeRuntimeRedisConfig(config) {
   if (!config) return void 0;
   return isNormalizedRedisConfig(config) ? config : normalizeRedisConfig(config);
 }
-function escapeRegExp2(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 function resolveSharedRedisConnection(redisConfig, connectionName) {
   if (!redisConfig) {
     throw new CacheDriverResolutionError(
@@ -878,56 +995,15 @@ function resolveSharedRedisConnection(redisConfig, connectionName) {
   );
 }
 function isModuleNotFoundError2(error, expectedSpecifier = "@holo-js/cache-redis") {
-  if (!error || typeof error !== "object") {
-    return false;
-  }
-  const message = "message" in error && typeof error.message === "string" ? error.message : "";
-  const code = "code" in error ? error.code : void 0;
-  const escapedSpecifier = escapeRegExp2(expectedSpecifier);
-  if ((code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") && [
-    new RegExp(`Cannot find package ['"]${escapedSpecifier}['"]`),
-    new RegExp(`Cannot find module ['"]${escapedSpecifier}['"]`),
-    new RegExp(`Could not resolve ['"]${escapedSpecifier}['"]`),
-    new RegExp(`Failed to load url\\s+(?:['"\`]${escapedSpecifier}['"\`]|${escapedSpecifier}(?=[\\s(]|$))`)
-  ].some((pattern) => pattern.test(message))) {
-    return true;
-  }
-  if ("cause" in error) {
-    return isModuleNotFoundError2(error.cause, expectedSpecifier);
-  }
-  return false;
+  return isOptionalDriverModuleNotFoundError(error, expectedSpecifier);
 }
 function normalizeRedisModuleLoadError(error, expectedSpecifier = "@holo-js/cache-redis") {
-  if (isModuleNotFoundError2(error, expectedSpecifier)) {
-    return new CacheOptionalPackageError(
-      "[@holo-js/cache] Redis cache support requires @holo-js/cache-redis to be installed.",
-      { cause: error }
-    );
-  }
-  return error;
-}
-async function importRedisDriverModuleFromProject(specifier) {
-  const projectRequire = createRequire2(join3(process.cwd(), "package.json"));
-  return await import(pathToFileURL2(projectRequire.resolve(specifier)).href);
-}
-async function loadRedisDriverModule() {
-  const specifier = "@holo-js/cache-redis";
-  try {
-    return await import(
-      /* webpackIgnore: true */
-      specifier
-    );
-  } catch (error) {
-    if (!isModuleNotFoundError2(error, specifier)) {
-      throw normalizeRedisModuleLoadError(error, specifier);
-    }
-    try {
-      return await importRedisDriverModuleFromProject(specifier);
-    } catch (fallbackError) {
-      throw normalizeRedisModuleLoadError(fallbackError, specifier);
-    }
-  }
+  return normalizeOptionalDriverModuleLoadError(error, expectedSpecifier, REDIS_CACHE_MISSING_MESSAGE);
 }
+var loadRedisDriverModule = createOptionalDriverModuleLoader(
+  REDIS_CACHE_PACKAGE,
+  REDIS_CACHE_MISSING_MESSAGE
+);
 var redisDriverModuleLoader = loadRedisDriverModule;
 function setRedisDriverModuleLoader(loader) {
   redisDriverModuleLoader = loader;
@@ -935,97 +1011,15 @@ function setRedisDriverModuleLoader(loader) {
 function resetRedisDriverModuleLoader() {
   redisDriverModuleLoader = loadRedisDriverModule;
 }
-var LazyRedisCacheDriver = class {
-  constructor(options) {
-    this.options = options;
-  }
-  driver = "redis";
-  driverInstance;
-  pending;
-  disposalGeneration = 0;
-  get name() {
-    return this.options.name;
-  }
-  async resolveDriver() {
-    if (this.driverInstance) return this.driverInstance;
-    const pendingGeneration = this.disposalGeneration;
-    this.pending ??= redisDriverModuleLoader().then((module) => {
-      const driver = module.createRedisCacheDriver(this.options);
-      if (this.disposalGeneration === pendingGeneration) {
-        this.driverInstance = driver;
-      }
-      return driver;
-    }).finally(() => {
-      this.pending = void 0;
-    });
-    return this.pending;
-  }
-  async withDriver(callback) {
-    return callback(await this.resolveDriver());
-  }
-  [CACHE_DRIVER_DISPOSE_SYMBOL]() {
-    const pending = this.pending;
-    const driverInstance = this.driverInstance;
-    this.disposalGeneration += 1;
-    this.driverInstance = void 0;
-    this.pending = void 0;
-    if (driverInstance) {
-      const disposable = driverInstance;
-      disposable[CACHE_DRIVER_DISPOSE_SYMBOL]?.();
-      return;
-    }
-    pending?.then((driver) => {
-      const disposable = driver;
-      disposable[CACHE_DRIVER_DISPOSE_SYMBOL]?.();
-    }).catch(() => {
-    });
-  }
-  createLockProxy(name, seconds) {
-    let lockPromise;
-    const resolveLock = async () => {
-      lockPromise ??= this.withDriver((driver) => driver.lock(name, seconds));
-      return lockPromise;
-    };
-    return {
-      name,
-      async get(callback) {
-        return (await resolveLock()).get(callback);
-      },
-      async release() {
-        return (await resolveLock()).release();
-      },
-      async block(waitSeconds, callback) {
-        return (await resolveLock()).block(waitSeconds, callback);
-      }
-    };
-  }
-  async get(key) {
-    return this.withDriver((driver) => driver.get(key));
-  }
-  async put(input) {
-    return this.withDriver((driver) => driver.put(input));
-  }
-  async add(input) {
-    return this.withDriver((driver) => driver.add(input));
-  }
-  async forget(key) {
-    return this.withDriver((driver) => driver.forget(key));
-  }
-  async flush() {
-    await this.withDriver((driver) => driver.flush());
-  }
-  async increment(key, amount) {
-    return this.withDriver((driver) => driver.increment(key, amount));
-  }
-  async decrement(key, amount) {
-    return this.withDriver((driver) => driver.decrement(key, amount));
-  }
-  lock(name, seconds) {
-    return this.createLockProxy(name, seconds);
-  }
-};
 function createRedisCacheDriver(options) {
-  return new LazyRedisCacheDriver(options);
+  return createLazyOptionalCacheDriver({
+    name: options.name,
+    driver: "redis",
+    options,
+    loadModule: redisDriverModuleLoader,
+    createDriver: (module, driverOptions) => module.createRedisCacheDriver(driverOptions),
+    disposeDriver: true
+  });
 }
 var cacheRedisInternals = {
   isModuleNotFoundError: isModuleNotFoundError2,
@@ -1226,27 +1220,6 @@ function resolveNormalizedKey(key, driverName) {
   const context = resolveDriverContext(driverName);
   return `${context.normalizedKeyPrefix}${resolveCacheKey(key)}`;
 }
-function normalizeFlexibleTtl(ttl) {
-  const freshSeconds = "fresh" in ttl ? ttl.fresh : ttl[0];
-  const staleSeconds = "stale" in ttl ? ttl.stale : ttl[1];
-  if (!Number.isInteger(freshSeconds) || freshSeconds < 0) {
-    throw new CacheInvalidTtlError("[@holo-js/cache] Flexible fresh TTL must be an integer greater than or equal to 0.");
-  }
-  if (!Number.isInteger(staleSeconds) || staleSeconds < freshSeconds) {
-    throw new CacheInvalidTtlError("[@holo-js/cache] Flexible stale TTL must be an integer greater than or equal to the fresh TTL.");
-  }
-  return Object.freeze({
-    freshSeconds,
-    staleSeconds
-  });
-}
-function isFlexibleEnvelope(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return false;
-  }
-  const envelope = value;
-  return envelope.__holo_cache_flexible === true && typeof envelope.freshUntil === "number" && Number.isFinite(envelope.freshUntil) && typeof envelope.staleUntil === "number" && Number.isFinite(envelope.staleUntil) && "value" in envelope;
-}
 async function getCachedValue(key, driverName) {
   const context = resolveDriverContext(driverName);
   const entry = await context.driver.get(resolveNormalizedKey(key, driverName));
@@ -1313,18 +1286,9 @@ function createCacheQueryBridge(dependencyIndex = getOrCreateDependencyIndex())
     },
     async flexible(key, ttl, callback, options = {}) {
       const indexedKey = createIndexedKey(key, options.driver);
-      const normalizedTtl = normalizeFlexibleTtl(ttl);
-      const now = Date.now();
-      const cached = await getCachedValue(key, options.driver);
-      const refreshValue = async () => {
+      const refreshValue = async (normalizedTtl) => {
         const value = await callback();
-        const refreshedAt = Date.now();
-        const envelope = {
-          __holo_cache_flexible: true,
-          value,
-          freshUntil: refreshedAt + normalizedTtl.freshSeconds * 1e3,
-          staleUntil: refreshedAt + normalizedTtl.staleSeconds * 1e3
-        };
+        const envelope = createFlexibleEnvelope(normalizedTtl, value);
         await putCachedValue(
           key,
           envelope,
@@ -1334,31 +1298,12 @@ function createCacheQueryBridge(dependencyIndex = getOrCreateDependencyIndex())
         await syncDependencies(indexedKey, options.dependencies);
         return value;
       };
-      if (isFlexibleEnvelope(cached)) {
-        if (now <= cached.freshUntil) {
-          return cached.value;
-        }
-        if (now <= cached.staleUntil) {
-          const refreshLock2 = createFlexibleLock(key, normalizedTtl, options.driver);
-          void refreshLock2.get(async () => {
-            await refreshValue();
-            return true;
-          }).catch(() => void 0);
-          return cached.value;
-        }
-      }
-      const refreshLock = createFlexibleLock(key, normalizedTtl, options.driver);
-      const refreshed = await refreshLock.block(1, async () => refreshValue());
-      if (refreshed !== false) {
-        return refreshed;
-      }
-      const retried = await getCachedValue(key, options.driver);
-      if (isFlexibleEnvelope(retried)) {
-        if (Date.now() <= retried.staleUntil) {
-          return retried.value;
-        }
-      }
-      return refreshValue();
+      return resolveFlexibleCachedValue({
+        ttl,
+        read: async () => getCachedValue(key, options.driver),
+        refresh: (normalizedTtl) => refreshValue(normalizedTtl),
+        createLock: (normalizedTtl) => createFlexibleLock(key, normalizedTtl, options.driver)
+      });
     },
     async forget(key, options) {
       const indexedKey = createIndexedKey(key, options?.driver);
@@ -1445,27 +1390,6 @@ function resolveDriverKey(driverName) {
   const normalized = driverName?.trim();
   return normalized || "__default__";
 }
-function normalizeFlexibleTtl2(ttl) {
-  const freshSeconds = "fresh" in ttl ? ttl.fresh : ttl[0];
-  const staleSeconds = "stale" in ttl ? ttl.stale : ttl[1];
-  if (!Number.isInteger(freshSeconds) || freshSeconds < 0) {
-    throw new CacheInvalidTtlError("[@holo-js/cache] Flexible fresh TTL must be an integer greater than or equal to 0.");
-  }
-  if (!Number.isInteger(staleSeconds) || staleSeconds < freshSeconds) {
-    throw new CacheInvalidTtlError("[@holo-js/cache] Flexible stale TTL must be an integer greater than or equal to the fresh TTL.");
-  }
-  return Object.freeze({
-    freshSeconds,
-    staleSeconds
-  });
-}
-function isFlexibleEnvelope2(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return false;
-  }
-  const envelope = value;
-  return envelope.__holo_cache_flexible === true && typeof envelope.freshUntil === "number" && Number.isFinite(envelope.freshUntil) && typeof envelope.staleUntil === "number" && Number.isFinite(envelope.staleUntil) && "value" in envelope;
-}
 function createCacheRepository(driverName) {
   function resolveDriverContext2() {
     const runtime = getCacheRuntime();
@@ -1511,13 +1435,7 @@ function createCacheRepository(driverName) {
     });
   }
   async function putFlexibleEnvelope(key, ttl, value) {
-    const now = Date.now();
-    const envelope = {
-      __holo_cache_flexible: true,
-      value,
-      freshUntil: now + ttl.freshSeconds * 1e3,
-      staleUntil: now + ttl.staleSeconds * 1e3
-    };
+    const envelope = createFlexibleEnvelope(ttl, value);
     await putSerializedValue(key, serializeCacheValue(envelope), ttl.staleSeconds);
     return value;
   }
@@ -1617,40 +1535,19 @@ function createCacheRepository(driverName) {
       return value;
     },
     async flexible(key, ttl, callback) {
-      const normalizedTtl = normalizeFlexibleTtl2(ttl);
-      const now = Date.now();
-      const cached = await getCachedValue2(key);
-      if (cached.hit && isFlexibleEnvelope2(cached.value)) {
-        if (now <= cached.value.freshUntil) {
-          return cached.value.value;
-        }
-        if (now <= cached.value.staleUntil) {
-          const refreshLock2 = createRefreshLock(key, normalizedTtl.staleSeconds);
-          void refreshLock2.get(async () => {
-            await refreshFlexibleValue(key, normalizedTtl, callback);
-            return true;
-          }).catch(() => void 0);
-          return cached.value.value;
-        }
-      }
-      const refreshLock = createRefreshLock(key, normalizedTtl.staleSeconds);
-      const refreshed = await refreshLock.block(
-        Math.min(
+      return resolveFlexibleCachedValue({
+        ttl,
+        read: async () => {
+          const cached = await getCachedValue2(key);
+          return cached.hit ? cached.value : void 0;
+        },
+        refresh: (normalizedTtl) => refreshFlexibleValue(key, normalizedTtl, callback),
+        createLock: (normalizedTtl) => createRefreshLock(key, normalizedTtl.staleSeconds),
+        blockSeconds: (normalizedTtl) => Math.min(
           MAX_REFRESH_BLOCK_SECONDS,
           Math.max(1, Math.ceil(normalizedTtl.staleSeconds / 300))
-        ),
-        async () => refreshFlexibleValue(key, normalizedTtl, callback)
-      );
-      if (refreshed !== false) {
-        return refreshed;
-      }
-      const retried = await getCachedValue2(key);
-      if (retried.hit && isFlexibleEnvelope2(retried.value)) {
-        if (Date.now() <= retried.value.staleUntil) {
-          return retried.value.value;
-        }
-      }
-      return refreshFlexibleValue(key, normalizedTtl, callback);
+        )
+      });
     },
     lock(name, seconds) {
       const { driver } = resolveDriverContext2();
@@ -1685,8 +1582,8 @@ var cacheFacadeInternals = {
     return `__flexible__:${resolveCacheKey(key)}`;
   },
   getOrCreateRepository,
-  isFlexibleEnvelope: isFlexibleEnvelope2,
-  normalizeFlexibleTtl: normalizeFlexibleTtl2,
+  isFlexibleEnvelope,
+  normalizeFlexibleTtl,
   resolveDriverKey,
   resolveFallback,
   resolveValue

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holo-js/cache",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Holo-JS Framework - cache contracts, config helpers, serialization, and runtime seams",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,7 @@
     "test": "vitest --run"
   },
   "dependencies": {
-    "@holo-js/config": "^0.1.8"
+    "@holo-js/config": "^0.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",