@dotpress/cache 0.0.0-stage → 2.0.0-alpha.1

package/dist/index.js

@@ -0,0 +1,696 @@
+import {
+  CacheError,
+  CacheStoreError,
+  CacheTimeoutError,
+  MemoBatchError,
+  createMemo,
+  defineMemo,
+  keyOf
+} from "./chunk-6ZNJJARH.js";
+import {
+  toMilliseconds
+} from "./chunk-2IEBMYSF.js";
+
+// src/logger.ts
+var noop = () => void 0;
+var silentLogger = {
+  debug: noop,
+  info: noop,
+  warn: noop,
+  error: noop
+};
+var checkLogger = (label, logger) => {
+  for (const level of ["info", "warn", "error"]) {
+    if (typeof logger?.[level] !== "function") {
+      throw new TypeError(
+        `${label}: logger must have info(), warn() and error() methods.`
+      );
+    }
+  }
+  return logger;
+};
+
+// src/store.ts
+var isStore = (value) => {
+  const store = value;
+  return typeof store?.name === "string" && typeof store.get === "function" && typeof store.set === "function" && typeof store.delete === "function";
+};
+var createMemoryStore = (options = {}) => {
+  const label = "createMemoryStore()";
+  if (typeof options !== "object" || options === null) {
+    throw new TypeError(`${label}: expected an object of options.`);
+  }
+  for (const key of Object.keys(options)) {
+    if (key !== "maxEntries") {
+      throw new TypeError(`${label}: unknown option "${key}".`);
+    }
+  }
+  const { maxEntries = 1e4 } = options;
+  if (!Number.isInteger(maxEntries) || maxEntries < 1) {
+    throw new TypeError(`${label}: maxEntries must be a positive integer.`);
+  }
+  const entries2 = /* @__PURE__ */ new Map();
+  const locks = /* @__PURE__ */ new Map();
+  const read = (key) => {
+    const entry = entries2.get(key);
+    if (!entry) return void 0;
+    entries2.delete(key);
+    if (entry.expiresAt <= Date.now()) return void 0;
+    entries2.set(key, entry);
+    return entry.value;
+  };
+  return Object.freeze({
+    name: "memory",
+    get size() {
+      return entries2.size;
+    },
+    get: async (key) => read(key),
+    getMany: async (keys) => keys.map(read),
+    set: async (key, value, ttl) => {
+      entries2.delete(key);
+      entries2.set(key, { value, expiresAt: Date.now() + ttl });
+      for (const oldest of entries2.keys()) {
+        if (entries2.size <= maxEntries) break;
+        entries2.delete(oldest);
+      }
+    },
+    delete: async (key) => {
+      entries2.delete(key);
+    },
+    lock: async (key, ttl) => {
+      const held = locks.get(key);
+      if (held && held.expiresAt > Date.now()) return void 0;
+      const token = crypto.randomUUID();
+      locks.set(key, { token, expiresAt: Date.now() + ttl });
+      return token;
+    },
+    unlock: async (key, token) => {
+      if (locks.get(key)?.token === token) locks.delete(key);
+    },
+    clear: () => {
+      entries2.clear();
+      locks.clear();
+    }
+  });
+};
+
+// src/cache.ts
+var entries = /* @__PURE__ */ new WeakMap();
+var NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+var POLICY = [
+  "ttl",
+  "grace",
+  "graceBackoff",
+  "staleWhileRevalidate",
+  "timeout",
+  "hardTimeout",
+  "lock"
+];
+var ENTRY_OPTIONS = /* @__PURE__ */ new Set([
+  "name",
+  "key",
+  "schema",
+  "version",
+  "tags",
+  ...POLICY
+]);
+var policyOf = (label, values) => {
+  const policy = {};
+  for (const option of POLICY) {
+    const value = values[option];
+    if (value === void 0) continue;
+    policy[option] = option === "ttl" || option === "timeout" || option === "hardTimeout" || option === "lock" ? positive(`${label}: ${option}`, value) : toMilliseconds(`${label}: ${option}`, value);
+  }
+  return policy;
+};
+function defineCacheEntry(options) {
+  const label = "defineCacheEntry()";
+  if (typeof options !== "object" || options === null) {
+    throw new TypeError(`${label}: expected an object of options.`);
+  }
+  const values = options;
+  const { name, key, schema, tags, version = 1 } = values;
+  if (typeof name !== "string" || !NAME.test(name)) {
+    throw new TypeError(
+      `${label}: name must have 1 to 128 letters, digits, ".", "_" or "-", starting with a letter or a digit.`
+    );
+  }
+  const named = `defineCacheEntry("${name}")`;
+  for (const option of Object.keys(values)) {
+    if (!ENTRY_OPTIONS.has(option)) {
+      throw new TypeError(`${named}: unknown option "${option}".`);
+    }
+  }
+  if (key !== void 0 && typeof key !== "function") {
+    throw new TypeError(`${named}: key must be a function.`);
+  }
+  if (schema !== void 0 && typeof schema?.safeParseAsync !== "function") {
+    throw new TypeError(
+      `${named}: schema must have a safeParseAsync() method, like a Zod schema.`
+    );
+  }
+  if (!Number.isInteger(version) || version < 0) {
+    throw new TypeError(`${named}: version must be a non-negative integer.`);
+  }
+  if (tags !== void 0 && typeof tags !== "function") {
+    throw new TypeError(`${named}: tags must be a function.`);
+  }
+  const entry = Object.freeze({ name, version });
+  entries.set(entry, {
+    name,
+    version,
+    key,
+    schema,
+    tags,
+    policy: policyOf(named, values)
+  });
+  return entry;
+}
+var positive = (label, value) => {
+  const ms = toMilliseconds(label, value);
+  if (ms < 1) throw new TypeError(`${label} must be at least 1 millisecond.`);
+  return ms;
+};
+var CACHE_OPTIONS = /* @__PURE__ */ new Set([
+  "store",
+  "prefix",
+  "ttl",
+  "serializer",
+  "logger",
+  "onError",
+  "failOpen",
+  "storeTimeout",
+  "onEvent",
+  ...POLICY
+]);
+var jsonSerializer = {
+  serialize: (value) => JSON.stringify(value),
+  deserialize: (text) => JSON.parse(text)
+};
+var parseStored = (text) => {
+  try {
+    const stored = JSON.parse(text);
+    if (stored?.v === 1 && typeof stored.c === "number" && typeof stored.e === "number" && typeof stored.d === "string" && (stored.t === void 0 || typeof stored.t === "object" && stored.t !== null)) {
+      return stored;
+    }
+  } catch {
+  }
+  return void 0;
+};
+var encoder = new TextEncoder();
+var TAG_LIFETIME = 30 * 864e5;
+var LOCK_POLL = 50;
+var sha256 = async (text) => {
+  const digest = await crypto.subtle.digest("SHA-256", encoder.encode(text));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+var createCache = (options) => {
+  const label = "createCache()";
+  if (typeof options !== "object" || options === null) {
+    throw new TypeError(`${label}: expected an object of options.`);
+  }
+  for (const key of Object.keys(options)) {
+    if (!CACHE_OPTIONS.has(key)) {
+      throw new TypeError(`${label}: unknown option "${key}".`);
+    }
+  }
+  const {
+    store,
+    prefix,
+    serializer = jsonSerializer,
+    onError,
+    onEvent,
+    failOpen = true
+  } = options;
+  if (!isStore(store)) {
+    throw new TypeError(
+      `${label}: store must be a cache store (createMemoryStore(), createRedisStore()\u2026).`
+    );
+  }
+  if (prefix !== void 0 && (typeof prefix !== "string" || prefix === "")) {
+    throw new TypeError(`${label}: prefix must be a non-empty string.`);
+  }
+  const defaults = policyOf(
+    label,
+    options
+  );
+  if (typeof serializer?.serialize !== "function" || typeof serializer.deserialize !== "function") {
+    throw new TypeError(
+      `${label}: serializer must have serialize() and deserialize() methods.`
+    );
+  }
+  if (onError !== void 0 && typeof onError !== "function") {
+    throw new TypeError(`${label}: onError must be a function.`);
+  }
+  if (onEvent !== void 0 && typeof onEvent !== "function") {
+    throw new TypeError(`${label}: onEvent must be a function.`);
+  }
+  if (typeof failOpen !== "boolean") {
+    throw new TypeError(`${label}: failOpen must be a boolean.`);
+  }
+  const storeTimeout = options.storeTimeout === void 0 ? void 0 : positive(`${label}: storeTimeout`, options.storeTimeout);
+  const rootLogger = options.logger === void 0 ? silentLogger : checkLogger(label, options.logger);
+  const loading = /* @__PURE__ */ new Map();
+  const backoffs = /* @__PURE__ */ new Map();
+  const configOf = (method, entry) => {
+    const config = typeof entry === "object" && entry !== null ? entries.get(entry) : void 0;
+    if (!config) {
+      throw new TypeError(
+        `cache.${method}(): expected an entry created by defineCacheEntry().`
+      );
+    }
+    return config;
+  };
+  const policyFor = (config) => {
+    const value = (option) => config.policy[option] ?? defaults[option];
+    return {
+      ttl: value("ttl") ?? 36e5,
+      grace: value("grace") ?? 0,
+      graceBackoff: value("graceBackoff") ?? 1e4,
+      staleWhileRevalidate: value("staleWhileRevalidate") ?? 0,
+      timeout: value("timeout"),
+      hardTimeout: value("hardTimeout"),
+      lock: value("lock")
+    };
+  };
+  const fit = async (base, part) => {
+    const key = `${base}:${part}`;
+    return encoder.encode(key).length > (store.maxKeyLength ?? Infinity) ? `${base}:#${await sha256(part)}` : key;
+  };
+  const keyFor = async (config, args) => {
+    const raw = config.key ? config.key(...args) : args.length === 1 ? args[0] : args;
+    const base = [prefix, config.name, `v${config.version}`].filter((item) => item !== void 0).join(":");
+    if (!config.key && args.length === 0) return base;
+    return fit(
+      base,
+      typeof raw === "string" ? raw : keyOf(`Cache entry "${config.name}"`, raw)
+    );
+  };
+  const checkTags = (label2, tags) => {
+    if (!Array.isArray(tags) || !tags.every((tag) => typeof tag === "string" && tag !== "")) {
+      throw new TypeError(
+        `${label2}: tags must be an array of non-empty strings.`
+      );
+    }
+    return [...new Set(tags)];
+  };
+  const tagKeysOf = (tags) => {
+    const base = prefix === void 0 ? "_tag" : `${prefix}:_tag`;
+    return Promise.all(
+      tags.map(async (tag) => ({ tag, key: await fit(base, tag) }))
+    );
+  };
+  const create = (logger) => {
+    const describe = (error) => error instanceof Error ? error.message : String(error);
+    const guard = async (operation, key, entry, run, fallback) => {
+      let timer;
+      try {
+        const running = run();
+        return storeTimeout === void 0 ? await running : await Promise.race([
+          running,
+          new Promise((_, reject) => {
+            timer = setTimeout(
+              () => reject(
+                new Error(`no answer within ${storeTimeout} milliseconds`)
+              ),
+              storeTimeout
+            );
+          })
+        ]);
+      } catch (cause) {
+        const error = new CacheStoreError(store.name, operation, key, {
+          cause
+        });
+        const data = {
+          store: store.name,
+          operation,
+          key,
+          entry,
+          error: error.message
+        };
+        if (operation === "delete" || operation === "invalidate") {
+          logger.error(data, "Cache store failed");
+        } else {
+          logger.warn(data, "Cache store failed");
+        }
+        if (onError) {
+          try {
+            await onError(error, { operation, key, entry });
+          } catch (hookError) {
+            logger.error(
+              { error: describe(hookError) },
+              "Cache onError hook failed"
+            );
+          }
+        }
+        if (!failOpen) throw error;
+        return fallback;
+      } finally {
+        clearTimeout(timer);
+      }
+    };
+    const report = (event) => {
+      const { type, reason, entry, key } = event;
+      logger.debug?.(
+        { entry, key, ...reason ? { reason } : {} },
+        type === "hit" ? "Cache hit" : type === "miss" ? "Cache miss" : "Cache served a stale value"
+      );
+      if (!onEvent) return;
+      try {
+        onEvent(event);
+      } catch (error) {
+        logger.error({ error: describe(error) }, "Cache onEvent hook failed");
+      }
+    };
+    const tokensOf = async (entry, tagKeys) => {
+      const keys = tagKeys.map(({ key }) => key);
+      const values = await guard(
+        "get",
+        keys.join(" "),
+        entry,
+        () => store.getMany ? store.getMany(keys) : Promise.all(keys.map((key) => store.get(key))),
+        void 0
+      );
+      return values?.map((token, index) => ({
+        tag: tagKeys[index].tag,
+        token
+      }));
+    };
+    const decode = async (config, key, data) => {
+      let value;
+      try {
+        value = serializer.deserialize(data);
+      } catch (error) {
+        logger.warn(
+          { entry: config.name, key, error: describe(error) },
+          "Cache value cannot be deserialized"
+        );
+        return void 0;
+      }
+      if (!config.schema) return { value };
+      const result = await config.schema.safeParseAsync(value);
+      return result.success ? { value: result.data } : void 0;
+    };
+    const lookup = async (config, policy, key) => {
+      const text = await guard(
+        "get",
+        key,
+        config.name,
+        () => store.get(key),
+        void 0
+      );
+      if (text === void 0) return void 0;
+      const stored = parseStored(text);
+      const now = Date.now();
+      if (!stored || stored.e + Math.max(policy.grace, policy.staleWhileRevalidate) <= now) {
+        return void 0;
+      }
+      const decoded = await decode(config, key, stored.d);
+      if (!decoded) return void 0;
+      const tags = Object.entries(stored.t ?? {});
+      let tagsValid = true;
+      if (tags.length > 0) {
+        const current = await tokensOf(
+          config.name,
+          await tagKeysOf(tags.map(([tag]) => tag))
+        );
+        tagsValid = current?.every(({ tag, token }) => token === stored.t?.[tag]) ?? false;
+      }
+      return {
+        value: decoded.value,
+        expiresAt: stored.e,
+        fresh: stored.e > now && tagsValid,
+        tagsValid
+      };
+    };
+    const write = async (config, key, args, value) => {
+      if (value === void 0) return void 0;
+      let data;
+      try {
+        data = serializer.serialize(value);
+        if (typeof data !== "string") throw new TypeError("not a string");
+      } catch (error) {
+        logger.warn(
+          { entry: config.name, key, error: describe(error) },
+          "Cache value cannot be serialized"
+        );
+        return void 0;
+      }
+      const checked = config.schema ? await decode(config, key, data) : { value };
+      if (!checked) {
+        logger.warn(
+          { entry: config.name, key },
+          "Cache value does not match the schema of the entry: not cached"
+        );
+        return void 0;
+      }
+      const policy = policyFor(config);
+      const lifetime = policy.ttl + Math.max(policy.grace, policy.staleWhileRevalidate);
+      const now = Date.now();
+      const stored = {
+        v: 1,
+        c: now,
+        e: now + policy.ttl,
+        d: data
+      };
+      if (config.tags) {
+        const tags = checkTags(
+          `defineCacheEntry("${config.name}")`,
+          config.tags(...args)
+        );
+        if (tags.length > 0) {
+          const tagKeys = await tagKeysOf(tags);
+          const current = await tokensOf(config.name, tagKeys);
+          if (!current) return checked;
+          stored.t = {};
+          for (const [index, { tag, token }] of current.entries()) {
+            if (token !== void 0) {
+              stored.t[tag] = token;
+              continue;
+            }
+            const created = crypto.randomUUID();
+            const tagKey = tagKeys[index].key;
+            await guard(
+              "set",
+              tagKey,
+              config.name,
+              () => store.set(tagKey, created, Math.max(lifetime, TAG_LIFETIME)),
+              void 0
+            );
+            stored.t[tag] = created;
+          }
+        }
+      }
+      await guard(
+        "set",
+        key,
+        config.name,
+        () => store.set(key, JSON.stringify(stored), lifetime),
+        void 0
+      );
+      return checked;
+    };
+    const load = (config, key, args, loader) => {
+      const running = loading.get(key);
+      if (running) return running;
+      const loaded = (async () => {
+        const policy = policyFor(config);
+        const lockKey = `${key}:lock`;
+        let token;
+        if (policy.lock !== void 0 && store.lock) {
+          const lock = store.lock.bind(store);
+          const ttl = policy.lock;
+          const taken = await guard(
+            "lock",
+            lockKey,
+            config.name,
+            () => lock(lockKey, ttl),
+            null
+          );
+          if (taken === void 0) {
+            const until = Date.now() + ttl;
+            while (Date.now() < until) {
+              await new Promise((resolve) => setTimeout(resolve, LOCK_POLL));
+              const found = await lookup(config, policy, key);
+              if (found?.fresh) return found.value;
+            }
+            logger.warn(
+              { entry: config.name, key, lock: ttl },
+              "Cache lock not released in time: loading anyway"
+            );
+          } else if (taken !== null) {
+            token = taken;
+          }
+        }
+        try {
+          const value = await loader();
+          const written = await write(config, key, args, value);
+          backoffs.delete(key);
+          return written ? written.value : value;
+        } finally {
+          if (token !== void 0 && store.unlock) {
+            const unlock = store.unlock.bind(store);
+            const held = token;
+            await guard(
+              "unlock",
+              lockKey,
+              config.name,
+              () => unlock(lockKey, held),
+              void 0
+            );
+          }
+        }
+      })();
+      loading.set(key, loaded);
+      void loaded.then(
+        () => loading.delete(key),
+        () => loading.delete(key)
+      );
+      return loaded;
+    };
+    const inBackground = (config, key, loaded) => {
+      loaded.catch((error) => {
+        logger.warn(
+          { entry: config.name, key, error: describe(error) },
+          "Cache refresh failed"
+        );
+      });
+    };
+    const deadline = (ms, error) => {
+      let timer;
+      const promise = new Promise((_, reject) => {
+        if (ms !== void 0) timer = setTimeout(() => reject(error()), ms);
+      });
+      return { promise, clear: () => clearTimeout(timer) };
+    };
+    const cache = {
+      get: (async (entry, ...args) => {
+        const config = configOf("get", entry);
+        const key = await keyFor(config, args);
+        const found = await lookup(config, policyFor(config), key);
+        report({ type: found?.fresh ? "hit" : "miss", entry: config.name, key });
+        return found?.fresh ? found.value : void 0;
+      }),
+      set: (async (entry, ...argsAndValue) => {
+        const config = configOf("set", entry);
+        const args = argsAndValue.slice(0, -1);
+        const key = await keyFor(config, args);
+        await write(config, key, args, argsAndValue.at(-1));
+      }),
+      delete: (async (entry, ...args) => {
+        const config = configOf("delete", entry);
+        const key = await keyFor(config, args);
+        await guard(
+          "delete",
+          key,
+          config.name,
+          () => store.delete(key),
+          void 0
+        );
+      }),
+      getOrSet: (async (entry, ...argsAndLoader) => {
+        const config = configOf("getOrSet", entry);
+        const loader = argsAndLoader.at(-1);
+        if (typeof loader !== "function") {
+          throw new TypeError(
+            "cache.getOrSet(): the last argument must be the function that loads the value."
+          );
+        }
+        const args = argsAndLoader.slice(0, -1);
+        const key = await keyFor(config, args);
+        const policy = policyFor(config);
+        const found = await lookup(config, policy, key);
+        const event = { entry: config.name, key };
+        if (found?.fresh) {
+          report({ type: "hit", ...event });
+          return found.value;
+        }
+        const now = Date.now();
+        if (found?.tagsValid && found.expiresAt + policy.staleWhileRevalidate > now) {
+          report({ type: "stale", reason: "revalidate", ...event });
+          inBackground(
+            config,
+            key,
+            load(config, key, args, loader)
+          );
+          return found.value;
+        }
+        const stale = found && policy.grace > 0 && found.expiresAt + policy.grace > now ? found : void 0;
+        if (stale && (backoffs.get(key) ?? 0) > now) {
+          report({ type: "stale", reason: "backoff", ...event });
+          return stale.value;
+        }
+        report({ type: "miss", ...event });
+        const loaded = load(config, key, args, loader);
+        const slow = /* @__PURE__ */ Symbol("slow");
+        const soft = deadline(stale ? policy.timeout : void 0, () => slow);
+        const hard = deadline(
+          policy.hardTimeout,
+          () => new CacheTimeoutError(
+            config.name,
+            key,
+            policy.hardTimeout
+          )
+        );
+        try {
+          return await Promise.race([loaded, soft.promise, hard.promise]);
+        } catch (error) {
+          if (error === slow || error instanceof CacheTimeoutError) {
+            inBackground(config, key, loaded);
+          }
+          if (!stale) throw error;
+          if (error === slow) {
+            logger.warn(
+              { ...event, timeout: policy.timeout },
+              "Cache served a stale value: the loader is slow"
+            );
+            report({ type: "stale", reason: "timeout", ...event });
+            return stale.value;
+          }
+          backoffs.set(key, Date.now() + policy.graceBackoff);
+          logger.warn(
+            { ...event, error: describe(error) },
+            "Cache served a stale value: the loader failed"
+          );
+          report({ type: "stale", reason: "error", ...event });
+          return stale.value;
+        } finally {
+          soft.clear();
+          hard.clear();
+        }
+      }),
+      invalidateTags: async (tags) => {
+        const tagKeys = await tagKeysOf(
+          checkTags("cache.invalidateTags()", tags)
+        );
+        await Promise.all(
+          tagKeys.map(
+            ({ tag, key }) => guard(
+              "invalidate",
+              key,
+              `tag:${tag}`,
+              () => store.set(key, crypto.randomUUID(), TAG_LIFETIME),
+              void 0
+            )
+          )
+        );
+        logger.debug?.({ tags }, "Cache tags invalidated");
+      },
+      withLogger: (other) => create(checkLogger("withLogger()", other))
+    };
+    return Object.freeze(cache);
+  };
+  return create(rootLogger);
+};
+export {
+  CacheError,
+  CacheStoreError,
+  CacheTimeoutError,
+  MemoBatchError,
+  createCache,
+  createMemo,
+  createMemoryStore,
+  defineCacheEntry,
+  defineMemo
+};
+//# sourceMappingURL=index.js.map