@gravito/stasis 1.0.0-beta.5 → 1.0.0

package/dist/index.js

@@ -0,0 +1,1321 @@
+// src/store.ts
+function isTaggableStore(store) {
+  return typeof store.flushTags === "function" && typeof store.tagKey === "function" && typeof store.tagIndexAdd === "function" && typeof store.tagIndexRemove === "function";
+}
+
+// src/types.ts
+function normalizeCacheKey(key) {
+  if (!key) {
+    throw new Error("Cache key cannot be empty.");
+  }
+  return key;
+}
+function ttlToExpiresAt(ttl, now = Date.now()) {
+  if (ttl === void 0) {
+    return void 0;
+  }
+  if (ttl === null) {
+    return null;
+  }
+  if (ttl instanceof Date) {
+    return ttl.getTime();
+  }
+  if (typeof ttl === "number") {
+    if (ttl <= 0) {
+      return now;
+    }
+    return now + ttl * 1e3;
+  }
+  return void 0;
+}
+function isExpired(expiresAt, now = Date.now()) {
+  if (expiresAt === null) {
+    return false;
+  }
+  if (expiresAt === void 0) {
+    return false;
+  }
+  return now > expiresAt;
+}
+
+// src/CacheRepository.ts
+var CacheRepository = class _CacheRepository {
+  constructor(store, options = {}) {
+    this.store = store;
+    this.options = options;
+  }
+  emit(event, payload = {}) {
+    const mode = this.options.eventsMode ?? "async";
+    if (mode === "off") {
+      return;
+    }
+    const fn = this.options.events?.[event];
+    if (!fn) {
+      return;
+    }
+    const invoke = () => {
+      if (event === "flush") {
+        return fn();
+      }
+      const key = payload.key ?? "";
+      return fn(key);
+    };
+    const reportError = (error) => {
+      try {
+        this.options.onEventError?.(error, event, payload);
+      } catch {
+      }
+    };
+    if (mode === "sync") {
+      try {
+        return Promise.resolve(invoke()).catch((error) => {
+          reportError(error);
+          if (this.options.throwOnEventError) {
+            throw error;
+          }
+        });
+      } catch (error) {
+        reportError(error);
+        if (this.options.throwOnEventError) {
+          throw error;
+        }
+      }
+      return;
+    }
+    queueMicrotask(() => {
+      try {
+        const result = invoke();
+        if (result && typeof result.catch === "function") {
+          void result.catch(reportError);
+        }
+      } catch (error) {
+        reportError(error);
+      }
+    });
+  }
+  key(key) {
+    const normalized = normalizeCacheKey(key);
+    const prefix = this.options.prefix ?? "";
+    return prefix ? `${prefix}${normalized}` : normalized;
+  }
+  flexibleFreshUntilKey(fullKey) {
+    return `__gravito:flexible:freshUntil:${fullKey}`;
+  }
+  async putMetaKey(metaKey, value, ttl) {
+    await this.store.put(metaKey, value, ttl);
+  }
+  async forgetMetaKey(metaKey) {
+    await this.store.forget(metaKey);
+  }
+  async get(key, defaultValue) {
+    const fullKey = this.key(key);
+    const value = await this.store.get(fullKey);
+    if (value !== null) {
+      const e2 = this.emit("hit", { key: fullKey });
+      if (e2) {
+        await e2;
+      }
+      return value;
+    }
+    const e = this.emit("miss", { key: fullKey });
+    if (e) {
+      await e;
+    }
+    if (defaultValue === void 0) {
+      return null;
+    }
+    if (typeof defaultValue === "function") {
+      return defaultValue();
+    }
+    return defaultValue;
+  }
+  async has(key) {
+    return await this.get(key) !== null;
+  }
+  async missing(key) {
+    return !await this.has(key);
+  }
+  async put(key, value, ttl) {
+    const fullKey = this.key(key);
+    await this.store.put(fullKey, value, ttl);
+    const e = this.emit("write", { key: fullKey });
+    if (e) {
+      await e;
+    }
+  }
+  async set(key, value, ttl) {
+    const resolved = ttl ?? this.options.defaultTtl;
+    await this.put(key, value, resolved);
+  }
+  async add(key, value, ttl) {
+    const fullKey = this.key(key);
+    const resolved = ttl ?? this.options.defaultTtl;
+    const ok = await this.store.add(fullKey, value, resolved);
+    if (ok) {
+      const e = this.emit("write", { key: fullKey });
+      if (e) {
+        await e;
+      }
+    }
+    return ok;
+  }
+  async forever(key, value) {
+    await this.put(key, value, null);
+  }
+  async remember(key, ttl, callback) {
+    const existing = await this.get(key);
+    if (existing !== null) {
+      return existing;
+    }
+    const value = await callback();
+    await this.put(key, value, ttl);
+    return value;
+  }
+  async rememberForever(key, callback) {
+    return this.remember(key, null, callback);
+  }
+  async many(keys) {
+    const out = {};
+    for (const key of keys) {
+      out[String(key)] = await this.get(key);
+    }
+    return out;
+  }
+  async putMany(values, ttl) {
+    await Promise.all(Object.entries(values).map(([k, v]) => this.put(k, v, ttl)));
+  }
+  /**
+   * Laravel-like flexible cache (stale-while-revalidate).
+   *
+   * - `ttlSeconds`: how long the value is considered fresh
+   * - `staleSeconds`: how long the stale value may be served while a refresh happens
+   */
+  async flexible(key, ttlSeconds, staleSeconds, callback) {
+    const fullKey = this.key(key);
+    const metaKey = this.flexibleFreshUntilKey(fullKey);
+    const now = Date.now();
+    const ttlMillis = Math.max(0, ttlSeconds) * 1e3;
+    const staleMillis = Math.max(0, staleSeconds) * 1e3;
+    const [freshUntil, cachedValue] = await Promise.all([
+      this.store.get(metaKey),
+      this.store.get(fullKey)
+    ]);
+    if (freshUntil !== null && cachedValue !== null) {
+      if (now <= freshUntil) {
+        const e2 = this.emit("hit", { key: fullKey });
+        if (e2) {
+          await e2;
+        }
+        return cachedValue;
+      }
+      if (now <= freshUntil + staleMillis) {
+        const e2 = this.emit("hit", { key: fullKey });
+        if (e2) {
+          await e2;
+        }
+        void this.refreshFlexible(fullKey, metaKey, ttlSeconds, staleSeconds, callback);
+        return cachedValue;
+      }
+    }
+    const e = this.emit("miss", { key: fullKey });
+    if (e) {
+      await e;
+    }
+    const value = await callback();
+    const totalTtl = ttlSeconds + staleSeconds;
+    await this.store.put(fullKey, value, totalTtl);
+    await this.putMetaKey(metaKey, now + ttlMillis, totalTtl);
+    {
+      const e2 = this.emit("write", { key: fullKey });
+      if (e2) {
+        await e2;
+      }
+    }
+    return value;
+  }
+  async refreshFlexible(fullKey, metaKey, ttlSeconds, staleSeconds, callback) {
+    if (!this.store.lock) {
+      return;
+    }
+    const lock = this.store.lock(`flexible:${metaKey}`, Math.max(1, ttlSeconds));
+    if (!lock || !await lock.acquire()) {
+      return;
+    }
+    try {
+      const value = await callback();
+      const totalTtl = ttlSeconds + staleSeconds;
+      const now = Date.now();
+      await this.store.put(fullKey, value, totalTtl);
+      await this.putMetaKey(metaKey, now + Math.max(0, ttlSeconds) * 1e3, totalTtl);
+      const e = this.emit("write", { key: fullKey });
+      if (e) {
+        await e;
+      }
+    } finally {
+      await lock.release();
+    }
+  }
+  async pull(key, defaultValue) {
+    const value = await this.get(key, defaultValue);
+    await this.forget(key);
+    return value;
+  }
+  async forget(key) {
+    const fullKey = this.key(key);
+    const metaKey = this.flexibleFreshUntilKey(fullKey);
+    const ok = await this.store.forget(fullKey);
+    await this.forgetMetaKey(metaKey);
+    if (ok) {
+      const e = this.emit("forget", { key: fullKey });
+      if (e) {
+        await e;
+      }
+    }
+    return ok;
+  }
+  async delete(key) {
+    return this.forget(key);
+  }
+  async flush() {
+    await this.store.flush();
+    const e = this.emit("flush");
+    if (e) {
+      await e;
+    }
+  }
+  async clear() {
+    return this.flush();
+  }
+  increment(key, value) {
+    return this.store.increment(this.key(key), value);
+  }
+  decrement(key, value) {
+    return this.store.decrement(this.key(key), value);
+  }
+  lock(name, seconds) {
+    return this.store.lock ? this.store.lock(this.key(name), seconds) : void 0;
+  }
+  tags(tags) {
+    if (!isTaggableStore(this.store)) {
+      throw new Error("This cache store does not support tags.");
+    }
+    return new _CacheRepository(new TaggedStore(this.store, tags), this.options);
+  }
+  /**
+   * Get the underlying store
+   */
+  getStore() {
+    return this.store;
+  }
+};
+var TaggedStore = class {
+  constructor(store, tags) {
+    this.store = store;
+    this.tags = tags;
+  }
+  tagged(key) {
+    return this.store.tagKey(normalizeCacheKey(key), this.tags);
+  }
+  async get(key) {
+    return this.store.get(this.tagged(key));
+  }
+  async put(key, value, ttl) {
+    const taggedKey = this.tagged(key);
+    await this.store.put(taggedKey, value, ttl);
+    this.store.tagIndexAdd(this.tags, taggedKey);
+  }
+  async add(key, value, ttl) {
+    const taggedKey = this.tagged(key);
+    const ok = await this.store.add(taggedKey, value, ttl);
+    if (ok) {
+      this.store.tagIndexAdd(this.tags, taggedKey);
+    }
+    return ok;
+  }
+  async forget(key) {
+    return this.store.forget(this.tagged(key));
+  }
+  async flush() {
+    return this.store.flushTags(this.tags);
+  }
+  async increment(key, value) {
+    const taggedKey = this.tagged(key);
+    const next = await this.store.increment(taggedKey, value);
+    this.store.tagIndexAdd(this.tags, taggedKey);
+    return next;
+  }
+  async decrement(key, value) {
+    const taggedKey = this.tagged(key);
+    const next = await this.store.decrement(taggedKey, value);
+    this.store.tagIndexAdd(this.tags, taggedKey);
+    return next;
+  }
+  lock(name, seconds) {
+    return this.store.lock ? this.store.lock(this.tagged(name), seconds) : void 0;
+  }
+};
+
+// src/RateLimiter.ts
+var RateLimiter = class {
+  constructor(store) {
+    this.store = store;
+  }
+  /**
+   * Attempt to acquire a lock
+   * @param key - The unique key (e.g., "ip:127.0.0.1")
+   * @param maxAttempts - Maximum number of attempts allowed
+   * @param decaySeconds - Time in seconds until the limit resets
+   */
+  async attempt(key, maxAttempts, decaySeconds) {
+    const current = await this.store.get(key);
+    const now = Math.floor(Date.now() / 1e3);
+    if (current === null) {
+      await this.store.put(key, 1, decaySeconds);
+      return {
+        allowed: true,
+        remaining: maxAttempts - 1,
+        reset: now + decaySeconds
+      };
+    }
+    if (current >= maxAttempts) {
+      return {
+        allowed: false,
+        remaining: 0,
+        reset: now + decaySeconds
+        // Approximation if we can't read TTL
+      };
+    }
+    const next = await this.store.increment(key);
+    return {
+      allowed: true,
+      remaining: maxAttempts - next,
+      reset: now + decaySeconds
+    };
+  }
+  /**
+   * Clear the limiter for a key
+   */
+  async clear(key) {
+    await this.store.forget(key);
+  }
+};
+
+// src/CacheManager.ts
+var CacheManager = class {
+  constructor(storeFactory, config = {}, events, eventOptions) {
+    this.storeFactory = storeFactory;
+    this.config = config;
+    this.events = events;
+    this.eventOptions = eventOptions;
+  }
+  stores = /* @__PURE__ */ new Map();
+  /**
+   * Get a rate limiter instance for a store
+   * @param name - Store name (optional, defaults to default store)
+   */
+  limiter(name) {
+    return new RateLimiter(this.store(name).getStore());
+  }
+  store(name) {
+    const storeName = name ?? this.config.default ?? "memory";
+    const existing = this.stores.get(storeName);
+    if (existing) {
+      return existing;
+    }
+    const repo = new CacheRepository(this.storeFactory(storeName), {
+      prefix: this.config.prefix,
+      defaultTtl: this.config.defaultTtl,
+      events: this.events,
+      eventsMode: this.eventOptions?.mode,
+      throwOnEventError: this.eventOptions?.throwOnError,
+      onEventError: this.eventOptions?.onError
+    });
+    this.stores.set(storeName, repo);
+    return repo;
+  }
+  // Laravel-like proxy methods (default store)
+  /**
+   * Retrieve an item from the cache.
+   *
+   * @param key - The unique cache key.
+   * @param defaultValue - The default value if the key is missing (can be a value or a closure).
+   * @returns The cached value or the default.
+   *
+   * @example
+   * ```typescript
+   * const value = await cache.get('user:1', { name: 'Guest' });
+   * ```
+   */
+  get(key, defaultValue) {
+    return this.store().get(key, defaultValue);
+  }
+  /**
+   * Check if an item exists in the cache.
+   */
+  has(key) {
+    return this.store().has(key);
+  }
+  /**
+   * Check if an item is missing from the cache.
+   */
+  missing(key) {
+    return this.store().missing(key);
+  }
+  /**
+   * Store an item in the cache.
+   *
+   * @param key - The unique cache key.
+   * @param value - The value to store.
+   * @param ttl - Time to live in seconds (or Date).
+   *
+   * @example
+   * ```typescript
+   * await cache.put('key', 'value', 60); // 60 seconds
+   * ```
+   */
+  put(key, value, ttl) {
+    return this.store().put(key, value, ttl);
+  }
+  /**
+   * Store an item in the cache (alias for put with optional TTL).
+   */
+  set(key, value, ttl) {
+    return this.store().set(key, value, ttl);
+  }
+  /**
+   * Store an item in the cache if it doesn't already exist.
+   *
+   * @returns True if added, false if it already existed.
+   */
+  add(key, value, ttl) {
+    return this.store().add(key, value, ttl);
+  }
+  /**
+   * Store an item in the cache indefinitely.
+   */
+  forever(key, value) {
+    return this.store().forever(key, value);
+  }
+  /**
+   * Get an item from the cache, or execute the callback and store the result.
+   *
+   * @param key - The cache key.
+   * @param ttl - Time to live if the item is missing.
+   * @param callback - Closure to execute on miss.
+   * @returns The cached or fetched value.
+   *
+   * @example
+   * ```typescript
+   * const user = await cache.remember('user:1', 60, async () => {
+   *   return await db.findUser(1);
+   * });
+   * ```
+   */
+  remember(key, ttl, callback) {
+    return this.store().remember(key, ttl, callback);
+  }
+  /**
+   * Get an item from the cache, or execute the callback and store the result forever.
+   */
+  rememberForever(key, callback) {
+    return this.store().rememberForever(key, callback);
+  }
+  /**
+   * Retrieve multiple items from the cache.
+   */
+  many(keys) {
+    return this.store().many(keys);
+  }
+  /**
+   * Store multiple items in the cache.
+   */
+  putMany(values, ttl) {
+    return this.store().putMany(values, ttl);
+  }
+  /**
+   * Get an item from the cache, allowing stale data while refreshing in background.
+   *
+   * @param key - Cache key.
+   * @param ttlSeconds - How long the value is considered fresh.
+   * @param staleSeconds - How long to serve stale data while refreshing.
+   * @param callback - Closure to refresh the data.
+   */
+  flexible(key, ttlSeconds, staleSeconds, callback) {
+    return this.store().flexible(key, ttlSeconds, staleSeconds, callback);
+  }
+  /**
+   * Retrieve an item from the cache and delete it.
+   */
+  pull(key, defaultValue) {
+    return this.store().pull(key, defaultValue);
+  }
+  /**
+   * Remove an item from the cache.
+   */
+  forget(key) {
+    return this.store().forget(key);
+  }
+  /**
+   * Remove an item from the cache (alias for forget).
+   */
+  delete(key) {
+    return this.store().delete(key);
+  }
+  /**
+   * Remove all items from the cache.
+   */
+  flush() {
+    return this.store().flush();
+  }
+  /**
+   * Clear the entire cache (alias for flush).
+   */
+  clear() {
+    return this.store().clear();
+  }
+  /**
+   * Increment an integer item in the cache.
+   */
+  increment(key, value) {
+    return this.store().increment(key, value);
+  }
+  /**
+   * Decrement an integer item in the cache.
+   */
+  decrement(key, value) {
+    return this.store().decrement(key, value);
+  }
+  /**
+   * Get a lock instance.
+   *
+   * @param name - Lock name.
+   * @param seconds - Lock duration.
+   * @returns CacheLock instance.
+   */
+  lock(name, seconds) {
+    return this.store().lock(name, seconds);
+  }
+  /**
+   * Access a tagged cache section (only supported by some stores).
+   */
+  tags(tags) {
+    return this.store().tags(tags);
+  }
+};
+
+// src/stores/FileStore.ts
+import { createHash, randomUUID } from "crypto";
+import { mkdir, open, readdir, readFile, rm, writeFile } from "fs/promises";
+import { join } from "path";
+
+// src/locks.ts
+var LockTimeoutError = class extends Error {
+  name = "LockTimeoutError";
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/stores/FileStore.ts
+function hashKey(key) {
+  return createHash("sha1").update(key).digest("hex");
+}
+var FileStore = class {
+  constructor(options) {
+    this.options = options;
+  }
+  async ensureDir() {
+    await mkdir(this.options.directory, { recursive: true });
+  }
+  filePathForKey(key) {
+    const hashed = hashKey(key);
+    return join(this.options.directory, `${hashed}.json`);
+  }
+  async get(key) {
+    const normalized = normalizeCacheKey(key);
+    await this.ensureDir();
+    const file = this.filePathForKey(normalized);
+    try {
+      const raw = await readFile(file, "utf8");
+      const data = JSON.parse(raw);
+      if (isExpired(data.expiresAt)) {
+        await this.forget(normalized);
+        return null;
+      }
+      return data.value;
+    } catch {
+      return null;
+    }
+  }
+  async put(key, value, ttl) {
+    const normalized = normalizeCacheKey(key);
+    await this.ensureDir();
+    const expiresAt = ttlToExpiresAt(ttl);
+    if (expiresAt !== null && expiresAt !== void 0 && expiresAt <= Date.now()) {
+      await this.forget(normalized);
+      return;
+    }
+    const file = this.filePathForKey(normalized);
+    const payload = { expiresAt: expiresAt ?? null, value };
+    await writeFile(file, JSON.stringify(payload), "utf8");
+  }
+  async add(key, value, ttl) {
+    const normalized = normalizeCacheKey(key);
+    const existing = await this.get(normalized);
+    if (existing !== null) {
+      return false;
+    }
+    await this.put(normalized, value, ttl);
+    return true;
+  }
+  async forget(key) {
+    const normalized = normalizeCacheKey(key);
+    await this.ensureDir();
+    const file = this.filePathForKey(normalized);
+    try {
+      await rm(file, { force: true });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async flush() {
+    await this.ensureDir();
+    const files = await readdir(this.options.directory);
+    await Promise.all(
+      files.filter((f) => f.endsWith(".json")).map((f) => rm(join(this.options.directory, f), { force: true }))
+    );
+  }
+  async increment(key, value = 1) {
+    const normalized = normalizeCacheKey(key);
+    const current = await this.get(normalized);
+    const next = (current ?? 0) + value;
+    await this.put(normalized, next, null);
+    return next;
+  }
+  async decrement(key, value = 1) {
+    return this.increment(key, -value);
+  }
+  lock(name, seconds = 10) {
+    const normalizedName = normalizeCacheKey(name);
+    const lockFile = join(this.options.directory, `.lock-${hashKey(normalizedName)}`);
+    const ttlMillis = Math.max(1, seconds) * 1e3;
+    const owner = randomUUID();
+    const tryAcquire = async () => {
+      await this.ensureDir();
+      try {
+        const handle = await open(lockFile, "wx");
+        await handle.writeFile(JSON.stringify({ owner, expiresAt: Date.now() + ttlMillis }), "utf8");
+        await handle.close();
+        return true;
+      } catch {
+        try {
+          const raw = await readFile(lockFile, "utf8");
+          const data = JSON.parse(raw);
+          if (!data.expiresAt || Date.now() > data.expiresAt) {
+            await rm(lockFile, { force: true });
+            return false;
+          }
+        } catch {
+        }
+        return false;
+      }
+    };
+    return {
+      async acquire() {
+        return tryAcquire();
+      },
+      async release() {
+        try {
+          const raw = await readFile(lockFile, "utf8");
+          const data = JSON.parse(raw);
+          if (data.owner === owner) {
+            await rm(lockFile, { force: true });
+          }
+        } catch {
+        }
+      },
+      async block(secondsToWait, callback, options) {
+        const deadline = Date.now() + Math.max(0, secondsToWait) * 1e3;
+        const sleepMillis = options?.sleepMillis ?? 150;
+        while (Date.now() <= deadline) {
+          if (await this.acquire()) {
+            try {
+              return await callback();
+            } finally {
+              await this.release();
+            }
+          }
+          await sleep(sleepMillis);
+        }
+        throw new LockTimeoutError(
+          `Failed to acquire lock '${name}' within ${secondsToWait} seconds.`
+        );
+      }
+    };
+  }
+};
+
+// src/stores/MemoryStore.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var MemoryStore = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  entries = /* @__PURE__ */ new Map();
+  locks = /* @__PURE__ */ new Map();
+  tagToKeys = /* @__PURE__ */ new Map();
+  keyToTags = /* @__PURE__ */ new Map();
+  touchLRU(key) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return;
+    }
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+  }
+  pruneIfNeeded() {
+    const maxItems = this.options.maxItems;
+    if (!maxItems || maxItems <= 0) {
+      return;
+    }
+    while (this.entries.size > maxItems) {
+      const oldest = this.entries.keys().next().value;
+      if (!oldest) {
+        return;
+      }
+      void this.forget(oldest);
+    }
+  }
+  cleanupExpired(key, now = Date.now()) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return;
+    }
+    if (isExpired(entry.expiresAt, now)) {
+      void this.forget(key);
+    }
+  }
+  async get(key) {
+    const normalized = normalizeCacheKey(key);
+    const entry = this.entries.get(normalized);
+    if (!entry) {
+      return null;
+    }
+    if (isExpired(entry.expiresAt)) {
+      await this.forget(normalized);
+      return null;
+    }
+    this.touchLRU(normalized);
+    return entry.value;
+  }
+  async put(key, value, ttl) {
+    const normalized = normalizeCacheKey(key);
+    const expiresAt = ttlToExpiresAt(ttl);
+    if (expiresAt !== null && expiresAt !== void 0 && expiresAt <= Date.now()) {
+      await this.forget(normalized);
+      return;
+    }
+    this.entries.set(normalized, { value, expiresAt: expiresAt ?? null });
+    this.pruneIfNeeded();
+  }
+  async add(key, value, ttl) {
+    const normalized = normalizeCacheKey(key);
+    this.cleanupExpired(normalized);
+    if (this.entries.has(normalized)) {
+      return false;
+    }
+    await this.put(normalized, value, ttl);
+    return true;
+  }
+  async forget(key) {
+    const normalized = normalizeCacheKey(key);
+    const existed = this.entries.delete(normalized);
+    this.tagIndexRemove(normalized);
+    return existed;
+  }
+  async flush() {
+    this.entries.clear();
+    this.tagToKeys.clear();
+    this.keyToTags.clear();
+  }
+  async increment(key, value = 1) {
+    const normalized = normalizeCacheKey(key);
+    const current = await this.get(normalized);
+    const next = (current ?? 0) + value;
+    await this.put(normalized, next, null);
+    return next;
+  }
+  async decrement(key, value = 1) {
+    return this.increment(key, -value);
+  }
+  lock(name, seconds = 10) {
+    const lockKey = `lock:${normalizeCacheKey(name)}`;
+    const ttlMillis = Math.max(1, seconds) * 1e3;
+    const locks = this.locks;
+    const acquire = async () => {
+      const now = Date.now();
+      const existing = locks.get(lockKey);
+      if (existing && existing.expiresAt > now) {
+        return { ok: false };
+      }
+      const owner2 = randomUUID2();
+      locks.set(lockKey, { owner: owner2, expiresAt: now + ttlMillis });
+      return { ok: true, owner: owner2 };
+    };
+    let owner;
+    return {
+      async acquire() {
+        const result = await acquire();
+        if (!result.ok) {
+          return false;
+        }
+        owner = result.owner;
+        return true;
+      },
+      async release() {
+        if (!owner) {
+          return;
+        }
+        const existing = locks.get(lockKey);
+        if (existing?.owner === owner) {
+          locks.delete(lockKey);
+        }
+        owner = void 0;
+      },
+      async block(secondsToWait, callback, options) {
+        const deadline = Date.now() + Math.max(0, secondsToWait) * 1e3;
+        const sleepMillis = options?.sleepMillis ?? 150;
+        while (Date.now() <= deadline) {
+          if (await this.acquire()) {
+            try {
+              return await callback();
+            } finally {
+              await this.release();
+            }
+          }
+          await sleep(sleepMillis);
+        }
+        throw new LockTimeoutError(
+          `Failed to acquire lock '${name}' within ${secondsToWait} seconds.`
+        );
+      }
+    };
+  }
+  tagKey(key, tags) {
+    const normalizedKey = normalizeCacheKey(key);
+    const normalizedTags = [...tags].map(String).filter(Boolean).sort();
+    if (normalizedTags.length === 0) {
+      return normalizedKey;
+    }
+    return `tags:${normalizedTags.join("|")}:${normalizedKey}`;
+  }
+  tagIndexAdd(tags, taggedKey) {
+    const normalizedTags = [...tags].map(String).filter(Boolean);
+    if (normalizedTags.length === 0) {
+      return;
+    }
+    for (const tag of normalizedTags) {
+      let keys = this.tagToKeys.get(tag);
+      if (!keys) {
+        keys = /* @__PURE__ */ new Set();
+        this.tagToKeys.set(tag, keys);
+      }
+      keys.add(taggedKey);
+    }
+    let tagSet = this.keyToTags.get(taggedKey);
+    if (!tagSet) {
+      tagSet = /* @__PURE__ */ new Set();
+      this.keyToTags.set(taggedKey, tagSet);
+    }
+    for (const tag of normalizedTags) {
+      tagSet.add(tag);
+    }
+  }
+  tagIndexRemove(taggedKey) {
+    const tags = this.keyToTags.get(taggedKey);
+    if (!tags) {
+      return;
+    }
+    for (const tag of tags) {
+      const keys = this.tagToKeys.get(tag);
+      if (!keys) {
+        continue;
+      }
+      keys.delete(taggedKey);
+      if (keys.size === 0) {
+        this.tagToKeys.delete(tag);
+      }
+    }
+    this.keyToTags.delete(taggedKey);
+  }
+  async flushTags(tags) {
+    const normalizedTags = [...tags].map(String).filter(Boolean);
+    if (normalizedTags.length === 0) {
+      return;
+    }
+    const keysToDelete = /* @__PURE__ */ new Set();
+    for (const tag of normalizedTags) {
+      const keys = this.tagToKeys.get(tag);
+      if (!keys) {
+        continue;
+      }
+      for (const k of keys) {
+        keysToDelete.add(k);
+      }
+    }
+    for (const key of keysToDelete) {
+      await this.forget(key);
+    }
+  }
+};
+
+// src/stores/NullStore.ts
+var NullStore = class {
+  async get(_key) {
+    return null;
+  }
+  async put(_key, _value, _ttl) {
+  }
+  async add(_key, _value, _ttl) {
+    return false;
+  }
+  async forget(_key) {
+    return false;
+  }
+  async flush() {
+  }
+  async increment(_key, _value = 1) {
+    return 0;
+  }
+  async decrement(_key, _value = 1) {
+    return 0;
+  }
+};
+
+// src/stores/RedisStore.ts
+import { randomUUID as randomUUID3 } from "crypto";
+import { Redis } from "@gravito/plasma";
+var RedisStore = class {
+  connectionName;
+  constructor(options = {}) {
+    this.connectionName = options.connection;
+  }
+  get client() {
+    return Redis.connection(this.connectionName);
+  }
+  async get(key) {
+    const normalized = normalizeCacheKey(key);
+    const value = await this.client.get(normalized);
+    if (value === null) {
+      return null;
+    }
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value;
+    }
+  }
+  async put(key, value, ttl) {
+    const normalized = normalizeCacheKey(key);
+    const serialized = JSON.stringify(value);
+    const expiresAt = ttlToExpiresAt(ttl);
+    const options = {};
+    if (expiresAt) {
+      const ttlMs = Math.max(1, expiresAt - Date.now());
+      options.px = ttlMs;
+    }
+    await this.client.set(normalized, serialized, options);
+  }
+  async add(key, value, ttl) {
+    const normalized = normalizeCacheKey(key);
+    const serialized = JSON.stringify(value);
+    const expiresAt = ttlToExpiresAt(ttl);
+    const options = { nx: true };
+    if (expiresAt) {
+      const ttlMs = Math.max(1, expiresAt - Date.now());
+      options.px = ttlMs;
+    }
+    const result = await this.client.set(normalized, serialized, options);
+    return result === "OK";
+  }
+  async forget(key) {
+    const normalized = normalizeCacheKey(key);
+    const count = await this.client.del(normalized);
+    return count > 0;
+  }
+  async flush() {
+    await this.client.flushdb();
+  }
+  async increment(key, value = 1) {
+    const normalized = normalizeCacheKey(key);
+    if (value === 1) {
+      return await this.client.incr(normalized);
+    }
+    return await this.client.incrby(normalized, value);
+  }
+  async decrement(key, value = 1) {
+    const normalized = normalizeCacheKey(key);
+    if (value === 1) {
+      return await this.client.decr(normalized);
+    }
+    return await this.client.decrby(normalized, value);
+  }
+  // ============================================================================
+  // Tags
+  // ============================================================================
+  tagKey(key, _tags) {
+    return key;
+  }
+  async tagIndexAdd(tags, taggedKey) {
+    if (tags.length === 0) {
+      return;
+    }
+    const pipeline = this.client.pipeline();
+    for (const tag of tags) {
+      const tagSetKey = `tag:${tag}`;
+      pipeline.sadd(tagSetKey, taggedKey);
+    }
+    await pipeline.exec();
+  }
+  async tagIndexRemove(_taggedKey) {
+  }
+  async flushTags(tags) {
+    if (tags.length === 0) {
+      return;
+    }
+    const tagKeys = tags.map((tag) => `tag:${tag}`);
+    const pipeline = this.client.pipeline();
+    for (const tagKey of tagKeys) {
+      pipeline.smembers(tagKey);
+    }
+    const results = await pipeline.exec();
+    const keysToDelete = /* @__PURE__ */ new Set();
+    for (const [err, keys] of results) {
+      if (!err && Array.isArray(keys)) {
+        for (const k of keys) {
+          keysToDelete.add(k);
+        }
+      }
+    }
+    if (keysToDelete.size > 0) {
+      await this.client.del(...Array.from(keysToDelete));
+    }
+    await this.client.del(...tagKeys);
+  }
+  // ============================================================================
+  // Locks
+  // ============================================================================
+  lock(name, seconds = 10) {
+    const lockKey = `lock:${normalizeCacheKey(name)}`;
+    const owner = randomUUID3();
+    const ttlMs = Math.max(1, seconds) * 1e3;
+    const client = this.client;
+    return {
+      async acquire() {
+        const result = await client.set(lockKey, owner, { nx: true, px: ttlMs });
+        return result === "OK";
+      },
+      async release() {
+        const current = await client.get(lockKey);
+        if (current === owner) {
+          await client.del(lockKey);
+        }
+      },
+      async block(secondsToWait, callback, options) {
+        const deadline = Date.now() + Math.max(0, secondsToWait) * 1e3;
+        const sleepMillis = options?.sleepMillis ?? 150;
+        while (Date.now() <= deadline) {
+          if (await this.acquire()) {
+            try {
+              return await callback();
+            } finally {
+              await this.release();
+            }
+          }
+          await sleep(sleepMillis);
+        }
+        throw new LockTimeoutError(
+          `Failed to acquire lock '${name}' within ${secondsToWait} seconds.`
+        );
+      }
+    };
+  }
+};
+
+// src/index.ts
+var MemoryCacheProvider = class {
+  store = new MemoryStore();
+  async get(key) {
+    return this.store.get(key);
+  }
+  async set(key, value, ttl = 60) {
+    await this.store.put(key, value, ttl);
+  }
+  async delete(key) {
+    await this.store.forget(key);
+  }
+  async clear() {
+    await this.store.flush();
+  }
+};
+function resolveStoreConfig(core, options) {
+  if (options) {
+    return options;
+  }
+  if (core.config.has("cache")) {
+    return core.config.get("cache");
+  }
+  return {};
+}
+function createStoreFactory(config) {
+  const stores = config.stores ?? {};
+  const defaultSeconds = typeof config.defaultTtl === "number" ? config.defaultTtl : 60;
+  return (name) => {
+    const storeConfig = stores[name];
+    const hasExplicitStores = Object.keys(stores).length > 0;
+    if (!storeConfig) {
+      if (name === "memory") {
+        return new MemoryStore();
+      }
+      if (name === "null") {
+        return new NullStore();
+      }
+      if (hasExplicitStores) {
+        throw new Error(`Cache store '${name}' is not defined.`);
+      }
+      return new MemoryStore();
+    }
+    if (storeConfig.driver === "memory") {
+      return new MemoryStore({ maxItems: storeConfig.maxItems });
+    }
+    if (storeConfig.driver === "file") {
+      return new FileStore({ directory: storeConfig.directory });
+    }
+    if (storeConfig.driver === "redis") {
+      return new RedisStore({ connection: storeConfig.connection, prefix: storeConfig.prefix });
+    }
+    if (storeConfig.driver === "null") {
+      return new NullStore();
+    }
+    if (storeConfig.driver === "custom") {
+      return storeConfig.store;
+    }
+    if (storeConfig.driver === "provider") {
+      const provider = storeConfig.provider;
+      if (!provider) {
+        throw new Error(`Cache store '${name}' is missing a provider.`);
+      }
+      return {
+        get: (key) => provider.get(key),
+        put: (key, value, ttl) => provider.set(key, value, typeof ttl === "number" ? ttl : defaultSeconds),
+        add: async (key, value, ttl) => {
+          const existing = await provider.get(key);
+          if (existing !== null) {
+            return false;
+          }
+          await provider.set(key, value, typeof ttl === "number" ? ttl : defaultSeconds);
+          return true;
+        },
+        forget: async (key) => {
+          await provider.delete(key);
+          return true;
+        },
+        flush: () => provider.clear(),
+        increment: async (key, value = 1) => {
+          const current = await provider.get(key);
+          const next = (current ?? 0) + value;
+          await provider.set(key, next, defaultSeconds);
+          return next;
+        },
+        decrement: async (key, value = 1) => {
+          const current = await provider.get(key);
+          const next = (current ?? 0) - value;
+          await provider.set(key, next, defaultSeconds);
+          return next;
+        }
+      };
+    }
+    throw new Error(`Unsupported cache driver '${storeConfig.driver}'.`);
+  };
+}
+var OrbitStasis = class {
+  constructor(options) {
+    this.options = options;
+  }
+  manager;
+  install(core) {
+    const resolvedConfig = resolveStoreConfig(core, this.options);
+    const exposeAs = resolvedConfig.exposeAs ?? "cache";
+    const defaultStore = resolvedConfig.default ?? (resolvedConfig.provider ? "default" : "memory");
+    const defaultTtl = resolvedConfig.defaultTtl ?? (typeof resolvedConfig.defaultTTL === "number" ? resolvedConfig.defaultTTL : void 0) ?? 60;
+    const prefix = resolvedConfig.prefix ?? "";
+    const logger = core.logger;
+    logger.info(`[OrbitCache] Initializing Cache (Exposed as: ${exposeAs})`);
+    const events = {
+      hit: (key) => core.hooks.doAction("cache:hit", { key }),
+      miss: (key) => core.hooks.doAction("cache:miss", { key }),
+      write: (key) => core.hooks.doAction("cache:write", { key }),
+      forget: (key) => core.hooks.doAction("cache:forget", { key }),
+      flush: () => core.hooks.doAction("cache:flush", {})
+    };
+    const onEventError = resolvedConfig.onEventError ?? ((error, event, payload) => {
+      const key = payload.key ? ` (key: ${payload.key})` : "";
+      logger.error(`[OrbitCache] cache event '${event}' failed${key}`, error);
+    });
+    const stores = resolvedConfig.stores ?? (resolvedConfig.provider ? { default: { driver: "provider", provider: resolvedConfig.provider } } : void 0);
+    const manager = new CacheManager(
+      createStoreFactory({ ...resolvedConfig, stores }),
+      {
+        default: defaultStore,
+        prefix,
+        defaultTtl
+      },
+      events,
+      {
+        mode: resolvedConfig.eventsMode ?? "async",
+        throwOnError: resolvedConfig.throwOnEventError,
+        onError: onEventError
+      }
+    );
+    this.manager = manager;
+    core.adapter.use("*", async (c, next) => {
+      c.set(exposeAs, manager);
+      await next();
+      return void 0;
+    });
+    core.services.set(exposeAs, manager);
+    core.hooks.doAction("cache:init", manager);
+  }
+  getCache() {
+    if (!this.manager) {
+      throw new Error("OrbitCache not installed yet.");
+    }
+    return this.manager;
+  }
+};
+function orbitCache(core, options = {}) {
+  const orbit = new OrbitStasis(options);
+  orbit.install(core);
+  return orbit.getCache();
+}
+var OrbitCache = OrbitStasis;
+export {
+  CacheManager,
+  CacheRepository,
+  FileStore,
+  LockTimeoutError,
+  MemoryCacheProvider,
+  MemoryStore,
+  NullStore,
+  OrbitCache,
+  OrbitStasis,
+  RateLimiter,
+  RedisStore,
+  orbitCache as default,
+  isExpired,
+  isTaggableStore,
+  normalizeCacheKey,
+  sleep,
+  ttlToExpiresAt
+};