@holo-js/cache 0.1.3

package/dist/chunk-KIYULZES.mjs

@@ -0,0 +1,253 @@
+// src/contracts.ts
+var CacheError = class extends Error {
+  code;
+  constructor(code, message, options = {}) {
+    super(message, options);
+    this.name = "CacheError";
+    this.code = code;
+  }
+};
+var CacheConfigError = class extends CacheError {
+  constructor(message, options = {}) {
+    super("CACHE_INVALID_CONFIG", message, options);
+    this.name = "CacheConfigError";
+  }
+};
+var CacheInvalidTtlError = class extends CacheError {
+  constructor(message, options = {}) {
+    super("CACHE_INVALID_TTL", message, options);
+    this.name = "CacheInvalidTtlError";
+  }
+};
+var CacheSerializationError = class extends CacheError {
+  constructor(message, options = {}) {
+    super("CACHE_UNSUPPORTED_VALUE", message, options);
+    this.name = "CacheSerializationError";
+  }
+};
+var CacheDriverResolutionError = class extends CacheError {
+  constructor(message, options = {}) {
+    super("CACHE_DRIVER_RESOLUTION_FAILED", message, options);
+    this.name = "CacheDriverResolutionError";
+  }
+};
+var CacheOptionalPackageError = class extends CacheError {
+  constructor(message, options = {}) {
+    super("CACHE_OPTIONAL_PACKAGE_MISSING", message, options);
+    this.name = "CacheOptionalPackageError";
+  }
+};
+var CacheInvalidNumericMutationError = class extends CacheError {
+  constructor(message, options = {}) {
+    super("CACHE_INVALID_NUMERIC_MUTATION", message, options);
+    this.name = "CacheInvalidNumericMutationError";
+  }
+};
+var CacheLockAcquisitionError = class extends CacheError {
+  constructor(message, options = {}) {
+    super("CACHE_LOCK_ACQUISITION_FAILED", message, options);
+    this.name = "CacheLockAcquisitionError";
+  }
+};
+var CacheQueryIntegrationError = class extends CacheError {
+  constructor(message, options = {}) {
+    super("CACHE_QUERY_INTEGRATION_MISUSE", message, options);
+    this.name = "CacheQueryIntegrationError";
+  }
+};
+var CacheRuntimeNotConfiguredError = class extends CacheError {
+  constructor() {
+    super("CACHE_RUNTIME_NOT_CONFIGURED", "[@holo-js/cache] Cache runtime is not configured yet.");
+    this.name = "CacheRuntimeNotConfiguredError";
+  }
+};
+function isPlainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function normalizeCacheStringKey(key) {
+  const normalized = key.trim();
+  if (!normalized) {
+    throw new CacheConfigError("[@holo-js/cache] Cache keys must be non-empty strings.");
+  }
+  return normalized;
+}
+function encodeFiniteNumber(value, path) {
+  if (!Number.isFinite(value)) {
+    throw new CacheSerializationError(`[@holo-js/cache] Cache value at ${path} must be JSON-safe.`);
+  }
+  return value;
+}
+function encodeDateValue(value, path) {
+  if (Number.isNaN(value.getTime())) {
+    throw new CacheSerializationError(`[@holo-js/cache] Cache value at ${path} contains an invalid Date.`);
+  }
+  return Object.freeze({
+    __holo_cache_type: "date",
+    value: value.toISOString()
+  });
+}
+function encodeArrayValue(value, path) {
+  const encodedEntries = [];
+  for (let index = 0; index < value.length; index += 1) {
+    if (!(index in value)) {
+      throw new CacheSerializationError(`[@holo-js/cache] Cache value at ${path}[${index}] must not be sparse.`);
+    }
+    encodedEntries.push(encodeCacheValue(value[index], `${path}[${index}]`));
+  }
+  return Object.freeze(encodedEntries);
+}
+function encodeObjectValue(value, path) {
+  const encodedEntries = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (key === "__holo_cache_type") {
+      throw new CacheSerializationError(`[@holo-js/cache] Cache value at ${path}.${key} uses a reserved key.`);
+    }
+    if (typeof entry === "undefined") {
+      throw new CacheSerializationError(`[@holo-js/cache] Cache value at ${path}.${key} must be JSON-safe.`);
+    }
+    encodedEntries[key] = encodeCacheValue(entry, `${path}.${key}`);
+  }
+  return Object.freeze(encodedEntries);
+}
+function encodeCacheValue(value, path) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return encodeFiniteNumber(value, path);
+  }
+  if (value instanceof Date) {
+    return encodeDateValue(value, path);
+  }
+  if (Array.isArray(value)) {
+    return encodeArrayValue(value, path);
+  }
+  if (isPlainObject(value)) {
+    return encodeObjectValue(value, path);
+  }
+  throw new CacheSerializationError(`[@holo-js/cache] Cache value at ${path} must be JSON-safe.`);
+}
+function decodeCacheValue(value, path) {
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return Object.freeze(value.map((entry, index) => decodeCacheValue(entry, `${path}[${index}]`)));
+  }
+  if (isPlainObject(value)) {
+    if (value.__holo_cache_type === "date") {
+      if (typeof value.value !== "string") {
+        throw new CacheSerializationError(`[@holo-js/cache] Cache payload at ${path} is malformed.`);
+      }
+      const decoded = new Date(value.value);
+      if (Number.isNaN(decoded.getTime())) {
+        throw new CacheSerializationError(`[@holo-js/cache] Cache payload at ${path} contains an invalid Date.`);
+      }
+      return decoded;
+    }
+    const decodedEntries = {};
+    for (const [key, entry] of Object.entries(value)) {
+      decodedEntries[key] = decodeCacheValue(entry, `${path}.${key}`);
+    }
+    return Object.freeze(decodedEntries);
+  }
+  throw new CacheSerializationError(`[@holo-js/cache] Cache payload at ${path} is malformed.`);
+}
+function defineCacheKey(key) {
+  return Object.freeze({
+    key: normalizeCacheStringKey(key)
+  });
+}
+function isCacheKey(value) {
+  return !!value && typeof value === "object" && "key" in value && typeof value.key === "string";
+}
+function resolveCacheKey(key) {
+  return normalizeCacheStringKey(typeof key === "string" ? key : key.key);
+}
+function normalizeCacheTtl(ttl, options = {}) {
+  const now = options.now instanceof Date ? (() => {
+    const timestamp = options.now.getTime();
+    if (Number.isNaN(timestamp)) {
+      throw new TypeError("[@holo-js/cache] Cache TTL options.now Date must be valid.");
+    }
+    return timestamp;
+  })() : typeof options.now === "number" ? (() => {
+    if (Number.isNaN(options.now) || !Number.isFinite(options.now)) {
+      throw new TypeError("[@holo-js/cache] Cache TTL options.now must be a valid finite number.");
+    }
+    return options.now;
+  })() : Date.now();
+  if (ttl instanceof Date) {
+    const expiresAt2 = ttl.getTime();
+    if (Number.isNaN(expiresAt2)) {
+      throw new CacheInvalidTtlError("[@holo-js/cache] Cache TTL Date must be valid.");
+    }
+    const remainingMilliseconds = Math.max(0, expiresAt2 - now);
+    return Object.freeze({
+      seconds: Math.floor(remainingMilliseconds / 1e3),
+      expiresAt: expiresAt2,
+      isExpired: expiresAt2 <= now
+    });
+  }
+  if (!Number.isInteger(ttl)) {
+    throw new CacheInvalidTtlError("[@holo-js/cache] Cache TTL seconds must be an integer.");
+  }
+  if (ttl < 0) {
+    throw new CacheInvalidTtlError("[@holo-js/cache] Cache TTL seconds must be > 0 or use a Date/forever option.");
+  }
+  if (ttl === 0) {
+    throw new CacheInvalidTtlError("[@holo-js/cache] Cache TTL seconds must be > 0 or use a Date/forever option.");
+  }
+  const expiresAt = now + ttl * 1e3;
+  return Object.freeze({
+    seconds: ttl,
+    expiresAt,
+    isExpired: expiresAt <= now
+  });
+}
+function serializeCacheValue(value) {
+  const payload = encodeCacheValue(value, "$");
+  return JSON.stringify(payload);
+}
+function deserializeCacheValue(payload) {
+  try {
+    return decodeCacheValue(JSON.parse(payload), "$");
+  } catch (error) {
+    if (error instanceof CacheSerializationError) {
+      throw error;
+    }
+    throw new CacheSerializationError("[@holo-js/cache] Cache payload is not valid JSON.", {
+      cause: error
+    });
+  }
+}
+var cacheContractsInternals = {
+  decodeCacheValue,
+  encodeCacheValue,
+  isPlainObject,
+  normalizeCacheStringKey
+};
+
+export {
+  CacheError,
+  CacheConfigError,
+  CacheInvalidTtlError,
+  CacheSerializationError,
+  CacheDriverResolutionError,
+  CacheOptionalPackageError,
+  CacheInvalidNumericMutationError,
+  CacheLockAcquisitionError,
+  CacheQueryIntegrationError,
+  CacheRuntimeNotConfiguredError,
+  defineCacheKey,
+  isCacheKey,
+  resolveCacheKey,
+  normalizeCacheTtl,
+  serializeCacheValue,
+  deserializeCacheValue,
+  cacheContractsInternals
+};

package/dist/contracts.d.ts

@@ -0,0 +1,196 @@
+import { HoloCacheConfig, NormalizedHoloCacheConfig, HoloDatabaseConfig, NormalizedHoloDatabaseConfig, HoloRedisConfig, NormalizedHoloRedisConfig } from '@holo-js/config';
+
+declare const cacheKeyBrand: unique symbol;
+type CacheKey<TValue> = Readonly<{
+    readonly key: string;
+    readonly [cacheKeyBrand]?: TValue;
+}>;
+type CacheKeyInput<TValue = unknown> = string | CacheKey<TValue>;
+type CacheDependencyDescriptor = string;
+type CacheTtlInput = number | Date;
+type CacheFallbackResolver<TValue> = () => TValue | Promise<TValue>;
+type CacheFallback<TValue> = TValue | CacheFallbackResolver<TValue>;
+type CacheValueResolver<TValue> = () => TValue | Promise<TValue>;
+type CacheFlexibleTtlInput = readonly [fresh: number, stale: number] | {
+    readonly fresh: number;
+    readonly stale: number;
+};
+interface NormalizedCacheTtl {
+    readonly seconds: number;
+    readonly expiresAt: number;
+    readonly isExpired: boolean;
+}
+type CacheErrorCode = 'CACHE_INVALID_CONFIG' | 'CACHE_INVALID_TTL' | 'CACHE_UNSUPPORTED_VALUE' | 'CACHE_DRIVER_RESOLUTION_FAILED' | 'CACHE_OPTIONAL_PACKAGE_MISSING' | 'CACHE_INVALID_NUMERIC_MUTATION' | 'CACHE_LOCK_ACQUISITION_FAILED' | 'CACHE_QUERY_INTEGRATION_MISUSE' | 'CACHE_RUNTIME_NOT_CONFIGURED';
+declare class CacheError extends Error {
+    readonly code: CacheErrorCode;
+    constructor(code: CacheErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class CacheConfigError extends CacheError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class CacheInvalidTtlError extends CacheError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class CacheSerializationError extends CacheError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class CacheDriverResolutionError extends CacheError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class CacheOptionalPackageError extends CacheError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class CacheInvalidNumericMutationError extends CacheError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class CacheLockAcquisitionError extends CacheError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class CacheQueryIntegrationError extends CacheError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class CacheRuntimeNotConfiguredError extends CacheError {
+    constructor();
+}
+interface CacheDriverGetResult {
+    readonly hit: boolean;
+    readonly payload?: string;
+    readonly expiresAt?: number;
+}
+interface CacheDriverPutInput {
+    readonly key: string;
+    readonly payload: string;
+    readonly expiresAt?: number;
+}
+interface CacheLockContract {
+    readonly name: string;
+    get<TValue>(callback?: () => TValue | Promise<TValue>): Promise<boolean | TValue>;
+    release(): Promise<boolean>;
+    block<TValue>(waitSeconds: number, callback?: () => TValue | Promise<TValue>): Promise<boolean | TValue>;
+}
+interface CacheDriverContract {
+    readonly name: string;
+    readonly driver: string;
+    get(key: string): Promise<CacheDriverGetResult>;
+    put(input: CacheDriverPutInput): Promise<boolean>;
+    add(input: CacheDriverPutInput): Promise<boolean>;
+    forget(key: string): Promise<boolean>;
+    flush(): Promise<void>;
+    increment(key: string, amount: number): Promise<number>;
+    decrement(key: string, amount: number): Promise<number>;
+    lock(name: string, seconds: number): CacheLockContract;
+}
+interface CacheDependencyIndex {
+    register(key: string, dependencies: readonly CacheDependencyDescriptor[]): Promise<void>;
+    listKeys(dependency: CacheDependencyDescriptor): Promise<readonly string[]>;
+    listRegisteredKeys(): Promise<readonly string[]>;
+    removeKey(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+interface CacheQueryBridge {
+    get<TValue>(key: CacheKeyInput<TValue>, options?: {
+        driver?: string;
+    }): Promise<TValue | null>;
+    put<TValue>(key: CacheKeyInput<TValue>, value: TValue, options: {
+        readonly driver?: string;
+        readonly ttl?: CacheTtlInput;
+        readonly flexible?: CacheFlexibleTtlInput;
+        readonly dependencies?: readonly CacheDependencyDescriptor[];
+    }): Promise<void>;
+    flexible<TValue>(key: CacheKeyInput<TValue>, ttl: CacheFlexibleTtlInput, callback: CacheValueResolver<TValue>, options?: {
+        readonly driver?: string;
+        readonly dependencies?: readonly CacheDependencyDescriptor[];
+    }): Promise<Awaited<TValue>>;
+    forget(key: CacheKeyInput<unknown>, options?: {
+        driver?: string;
+    }): Promise<boolean>;
+    invalidateDependencies(dependencies: readonly CacheDependencyDescriptor[], options?: {
+        driver?: string;
+    }): Promise<void>;
+}
+interface CacheRuntimeBindings {
+    readonly config: HoloCacheConfig | NormalizedHoloCacheConfig;
+    readonly databaseConfig?: HoloDatabaseConfig | NormalizedHoloDatabaseConfig;
+    readonly redisConfig?: HoloRedisConfig | NormalizedHoloRedisConfig;
+    readonly drivers?: ReadonlyMap<string, CacheDriverContract>;
+    readonly dependencyIndex?: CacheDependencyIndex;
+    readonly queryBridge?: CacheQueryBridge;
+}
+/**
+ * Cache reads return immutable snapshots.
+ * Arrays and plain objects returned by the cache are recursively frozen and
+ * must not be mutated in place.
+ */
+interface CacheRepository {
+    /**
+     * Returns the cached value or `null` when the key is missing.
+     * Arrays and plain objects in the returned value are frozen snapshots.
+     */
+    get<TValue>(key: CacheKey<TValue>): Promise<TValue | null>;
+    get<TValue>(key: CacheKeyInput<TValue>, fallback: CacheFallback<TValue>): Promise<TValue>;
+    get<TValue>(key: string, fallback: CacheFallback<TValue>): Promise<TValue>;
+    get(key: string): Promise<unknown | null>;
+    put<TValue>(key: CacheKeyInput<TValue>, value: TValue, ttl: CacheTtlInput): Promise<boolean>;
+    add<TValue>(key: CacheKeyInput<TValue>, value: TValue, ttl: CacheTtlInput): Promise<boolean>;
+    forever<TValue>(key: CacheKeyInput<TValue>, value: TValue): Promise<boolean>;
+    has(key: CacheKeyInput<unknown>): Promise<boolean>;
+    missing(key: CacheKeyInput<unknown>): Promise<boolean>;
+    forget(key: CacheKeyInput<unknown>): Promise<boolean>;
+    flush(): Promise<void>;
+    increment(key: CacheKeyInput<number>, amount?: number): Promise<number>;
+    decrement(key: CacheKeyInput<number>, amount?: number): Promise<number>;
+    /**
+     * Resolves and stores the value on a cache miss.
+     * Arrays and plain objects returned from the cache path are frozen snapshots.
+     */
+    remember<TValue>(key: CacheKeyInput<Awaited<TValue>>, ttl: CacheTtlInput, callback: CacheValueResolver<TValue>): Promise<Awaited<TValue>>;
+    rememberForever<TValue>(key: CacheKeyInput<Awaited<TValue>>, callback: CacheValueResolver<TValue>): Promise<Awaited<TValue>>;
+    flexible<TValue>(key: CacheKeyInput<Awaited<TValue>>, ttl: CacheFlexibleTtlInput, callback: CacheValueResolver<TValue>): Promise<Awaited<TValue>>;
+    lock(name: string, seconds: number): CacheLockContract;
+}
+interface CacheFacade extends CacheRepository {
+    driver(name?: string): CacheRepository;
+}
+type EncodedCacheValue = null | string | number | boolean | readonly EncodedCacheValue[] | {
+    readonly __holo_cache_type?: 'date';
+    readonly value?: string;
+    readonly [key: string]: EncodedCacheValue | 'date' | string | undefined;
+};
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+declare function normalizeCacheStringKey(key: string): string;
+declare function encodeCacheValue(value: unknown, path: string): EncodedCacheValue;
+declare function decodeCacheValue(value: unknown, path: string): unknown;
+declare function defineCacheKey<TValue>(key: string): CacheKey<TValue>;
+declare function isCacheKey(value: unknown): value is CacheKey<unknown>;
+declare function resolveCacheKey<TValue>(key: CacheKeyInput<TValue>): string;
+declare function normalizeCacheTtl(ttl: CacheTtlInput, options?: {
+    now?: number | Date;
+}): NormalizedCacheTtl;
+declare function serializeCacheValue<TValue>(value: TValue): string;
+declare function deserializeCacheValue<TValue>(payload: string): TValue;
+declare const cacheContractsInternals: {
+    decodeCacheValue: typeof decodeCacheValue;
+    encodeCacheValue: typeof encodeCacheValue;
+    isPlainObject: typeof isPlainObject;
+    normalizeCacheStringKey: typeof normalizeCacheStringKey;
+};
+
+export { CacheConfigError, type CacheDependencyDescriptor, type CacheDependencyIndex, type CacheDriverContract, type CacheDriverGetResult, type CacheDriverPutInput, CacheDriverResolutionError, CacheError, type CacheErrorCode, type CacheFacade, type CacheFallback, type CacheFallbackResolver, type CacheFlexibleTtlInput, CacheInvalidNumericMutationError, CacheInvalidTtlError, type CacheKey, type CacheKeyInput, CacheLockAcquisitionError, type CacheLockContract, CacheOptionalPackageError, type CacheQueryBridge, CacheQueryIntegrationError, type CacheRepository, type CacheRuntimeBindings, CacheRuntimeNotConfiguredError, CacheSerializationError, type CacheTtlInput, type CacheValueResolver, type NormalizedCacheTtl, cacheContractsInternals, defineCacheKey, deserializeCacheValue, isCacheKey, normalizeCacheTtl, resolveCacheKey, serializeCacheValue };

package/dist/contracts.mjs

@@ -0,0 +1,38 @@
+import {
+  CacheConfigError,
+  CacheDriverResolutionError,
+  CacheError,
+  CacheInvalidNumericMutationError,
+  CacheInvalidTtlError,
+  CacheLockAcquisitionError,
+  CacheOptionalPackageError,
+  CacheQueryIntegrationError,
+  CacheRuntimeNotConfiguredError,
+  CacheSerializationError,
+  cacheContractsInternals,
+  defineCacheKey,
+  deserializeCacheValue,
+  isCacheKey,
+  normalizeCacheTtl,
+  resolveCacheKey,
+  serializeCacheValue
+} from "./chunk-KIYULZES.mjs";
+export {
+  CacheConfigError,
+  CacheDriverResolutionError,
+  CacheError,
+  CacheInvalidNumericMutationError,
+  CacheInvalidTtlError,
+  CacheLockAcquisitionError,
+  CacheOptionalPackageError,
+  CacheQueryIntegrationError,
+  CacheRuntimeNotConfiguredError,
+  CacheSerializationError,
+  cacheContractsInternals,
+  defineCacheKey,
+  deserializeCacheValue,
+  isCacheKey,
+  normalizeCacheTtl,
+  resolveCacheKey,
+  serializeCacheValue
+};