cachetta 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,51 +1,39 @@
-import { promises as c } from "fs";
-import { normalize as I, resolve as D, dirname as C, join as $ } from "path";
-import { randomBytes as U, createHash as N } from "crypto";
-import { inspect as O } from "util";
-const R = (e) => typeof e == "object" && e !== null, F = (e) => R(e) && ("path" in e || "write" in e || "read" in e || "duration" in e || "lruSize" in e || "condition" in e || "staleDuration" in e), j = (e) => typeof e == "function" && "__cacheBuddy__" in e && e.__cacheBuddy__ === !0, _ = Symbol("LRU_MISS");
-class m extends Error {
-  constructor(t) {
-    super(t), this.name = "CachettaError";
-  }
-}
-class M extends m {
-  constructor(t) {
-    super(`Invalid cache path (path traversal detected): ${t}`), this.name = "InvalidPathError";
-  }
-}
-class E extends m {
-  constructor(t) {
-    super(`Unsupported cache format: ${t}`), this.name = "UnsupportedFormatError";
+import { promises as c, statSync as F, readFileSync as T, mkdirSync as G, writeFileSync as j, renameSync as A, unlinkSync as P } from "fs";
+import { deserialize as E, serialize as z } from "v8";
+import { normalize as W, resolve as b, dirname as x, join as S } from "path";
+import { randomBytes as L, createHash as H } from "crypto";
+import { inspect as J } from "util";
+const K = (e) => typeof e == "object" && e !== null, k = (e) => K(e) && ("path" in e || "write" in e || "read" in e || "duration" in e || "lruSize" in e || "condition" in e || "staleDuration" in e), I = (e) => typeof e == "function" && "__cacheBuddy__" in e && e.__cacheBuddy__ === !0, d = Symbol("LRU_MISS");
+async function f(e) {
+  try {
+    return (await c.stat(e)).mtime.getTime();
+  } catch (t) {
+    if (t.code === "ENOENT")
+      return null;
+    throw t;
   }
 }
-function v(e) {
-  var i;
-  const n = (i = String(e).split("/").pop()) == null ? void 0 : i.split(".");
-  if (!n || n.length === 1 || n[n.length - 1] === "")
-    throw new m(`Missing file extension: ${e}`);
-  return n[n.length - 1];
-}
-async function d(e) {
+function p(e) {
   try {
-    return (await c.stat(e)).mtime.getTime();
+    return F(e).mtime.getTime();
   } catch (t) {
     if (t.code === "ENOENT")
       return null;
     throw t;
   }
 }
-function A(e, t, n) {
+function N(e, t, n) {
   if (e > t)
     throw new Error(
       `Invalid arguments, cache time ${e} cannot be greater than now ${t}`
     );
   return t - e >= n;
 }
-let P = "warn";
-const x = ["error", "warn", "info", "debug"], G = (e) => {
-  const t = x.indexOf(P);
-  return x.indexOf(e) <= t;
-}, J = (e) => {
+let R = "warn";
+const D = ["error", "warn", "info", "debug"], q = (e) => {
+  const t = D.indexOf(R);
+  return D.indexOf(e) <= t;
+}, Q = (e) => {
   switch (e) {
     case "debug":
       return console.debug;
@@ -56,154 +44,239 @@ const x = ["error", "warn", "info", "debug"], G = (e) => {
     case "error":
       return console.error;
   }
-}, p = (e) => (...t) => {
-  if (G(e)) {
-    const n = J(e);
+}, w = (e) => (...t) => {
+  if (q(e)) {
+    const n = Q(e);
     n && n("[Cachetta]", ...t);
   }
 };
-let a = {
-  debug: p("debug"),
-  info: p("info"),
-  warn: p("warn"),
-  error: p("error")
+let o = {
+  debug: w("debug"),
+  info: w("info"),
+  warn: w("warn"),
+  error: w("error")
 };
-function Z(e) {
-  P = e;
+function ct(e) {
+  R = e;
 }
-function k(e) {
-  a = e;
+function ht(e) {
+  o = e;
 }
-async function T({ duration: e, read: t }, n) {
-  const i = e ?? 6048e5, r = await d(n);
+async function V({ duration: e, read: t }, n) {
+  const i = e ?? 6048e5, r = await f(n);
   if (r === null)
-    return a.debug(`Cache time is null for ${n}`), !1;
+    return o.debug(`Cache time is null for ${n}`), !1;
   if (i <= 0)
-    return a.debug(`Cache length is ${i}, considering expired for ${n}`), !1;
+    return o.debug(`Cache length is ${i}, considering expired for ${n}`), !1;
   const s = Date.now();
-  return r > s ? (a.debug(`Cache time ${r} is ahead of now ${s}, treating as valid cache for ${n}`), t ?? !0) : A(r, s, i) ? (a.debug(
+  return r > s ? (o.debug(`Cache time ${r} is ahead of now ${s}, treating as valid cache for ${n}`), t ?? !0) : N(r, s, i) ? (o.debug(
     `Cache is expired (${r}, expected ${r + i}) for ${n}`
-  ), !1) : (a.debug(
+  ), !1) : (o.debug(
     `Cache is not expired (${r}, expected ${r + i}) for ${n}`
   ), t ?? !0);
 }
-function h(e) {
-  const t = I(e);
+function X({ duration: e, read: t }, n) {
+  const i = e ?? 6048e5, r = p(n);
+  if (r === null)
+    return o.debug(`Cache time is null for ${n}`), !1;
+  if (i <= 0)
+    return o.debug(`Cache length is ${i}, considering expired for ${n}`), !1;
+  const s = Date.now();
+  return r > s ? (o.debug(`Cache time ${r} is ahead of now ${s}, treating as valid cache for ${n}`), t ?? !0) : N(r, s, i) ? (o.debug(
+    `Cache is expired (${r}, expected ${r + i}) for ${n}`
+  ), !1) : (o.debug(
+    `Cache is not expired (${r}, expected ${r + i}) for ${n}`
+  ), t ?? !0);
+}
+class C extends Error {
+  constructor(t) {
+    super(t), this.name = "CachettaError";
+  }
+}
+class Y extends C {
+  constructor(t) {
+    super(`Invalid cache path (path traversal detected): ${t}`), this.name = "InvalidPathError";
+  }
+}
+function u(e) {
+  const t = W(e);
   if (t.split(/[/\\]/).includes(".."))
-    throw new M(e);
-  return D(t);
+    throw new Y(e);
+  return b(t);
 }
-const K = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
-async function z(e) {
-  const t = v(e);
-  if (t !== "json")
-    throw new E(t);
+async function U(e) {
   try {
-    const n = await c.readFile(e, "utf8");
-    return JSON.parse(n, (i, r) => {
-      if (!K.has(i))
-        return r;
-    });
-  } catch (n) {
-    return n.code === "ENOENT" ? null : n instanceof SyntaxError ? (a.error(`Corrupt JSON: ${n}`), null) : (a.error(`Read error: ${n}`), null);
+    const t = await c.readFile(e);
+    return E(t);
+  } catch (t) {
+    return t.code === "ENOENT" || o.error(`Read error: ${t}`), null;
+  }
+}
+function M(e) {
+  try {
+    const t = T(e);
+    return E(t);
+  } catch (t) {
+    return t.code === "ENOENT" || o.error(`Read error: ${t}`), null;
   }
 }
-async function W(e, ...t) {
-  if (!j(e))
-    throw new m(`Invalid value provided, you must provide an instance of Cachetta: ${e}`);
+async function Z(e, ...t) {
+  if (!I(e))
+    throw new C(`Invalid value provided, you must provide an instance of Cachetta: ${e}`);
   const n = e._getPath(...t);
-  h(n);
+  u(n);
   const i = e._lruGet(n);
-  if (i !== _)
-    return a.debug(`LRU cache hit for ${n}`), i;
-  if (await T(e, n)) {
-    a.debug(`Using cache at ${n}`);
-    const r = await z(n);
-    return r !== null && (a.debug(`Used cache at ${n}`), e._lruSet(n, r)), r;
+  if (i !== d)
+    return o.debug(`LRU cache hit for ${n}`), i;
+  if (await V(e, n)) {
+    o.debug(`Using cache at ${n}`);
+    const r = await U(n);
+    return r !== null && (o.debug(`Used cache at ${n}`), e._lruSet(n, r)), r;
   } else
-    return a.debug("cache.read is false, skipping cache"), null;
+    return o.debug("cache.read is false, skipping cache"), null;
 }
-async function H(e, ...t) {
+function B(e, ...t) {
+  if (!I(e))
+    throw new C(`Invalid value provided, you must provide an instance of Cachetta: ${e}`);
+  const n = e._getPath(...t);
+  u(n);
+  const i = e._lruGet(n);
+  if (i !== d)
+    return o.debug(`LRU cache hit for ${n}`), i;
+  if (X(e, n)) {
+    o.debug(`Using cache at ${n}`);
+    const r = M(n);
+    return r !== null && (o.debug(`Used cache at ${n}`), e._lruSet(n, r)), r;
+  } else
+    return o.debug("cache.read is false, skipping cache"), null;
+}
+async function tt(e, ...t) {
+  if (!e.staleDuration || !e.read) return null;
+  const n = e._getPath(...t);
+  u(n);
+  const i = await f(n);
+  if (i === null) return null;
+  const r = Date.now() - i, s = r >= e.duration, a = r < e.duration + e.staleDuration;
+  return s && a ? (o.debug(`Returning stale cache for ${n} (age: ${r}ms)`), U(n)) : null;
+}
+function et(e, ...t) {
   if (!e.staleDuration || !e.read) return null;
   const n = e._getPath(...t);
-  h(n);
-  const i = await d(n);
+  u(n);
+  const i = p(n);
   if (i === null) return null;
-  const r = Date.now() - i, s = r >= e.duration, o = r < e.duration + e.staleDuration;
-  return s && o ? (a.debug(`Returning stale cache for ${n} (age: ${r}ms)`), z(n)) : null;
+  const r = Date.now() - i, s = r >= e.duration, a = r < e.duration + e.staleDuration;
+  return s && a ? (o.debug(`Returning stale cache for ${n} (age: ${r}ms)`), M(n)) : null;
 }
-const b = /* @__PURE__ */ new Set();
-async function y(e, t, ...n) {
+const y = /* @__PURE__ */ new Set();
+async function v(e, t, ...n) {
   if (!e || !e.write)
     return;
   const i = e._getPath(...n);
-  h(i);
-  const r = v(i), s = D(C(i));
-  if (b.has(s) || (await c.mkdir(s, { recursive: !0 }), b.add(s)), r === "json") {
-    const o = JSON.stringify(t), u = $(s, `.cachetta-${U(8).toString("hex")}.tmp`);
+  u(i);
+  const r = b(x(i));
+  y.has(r) || (await c.mkdir(r, { recursive: !0 }), y.add(r));
+  const s = z(t), a = S(r, `.cachetta-${L(8).toString("hex")}.tmp`);
+  try {
+    await c.writeFile(a, s), await c.rename(a, i), e._lruSet(i, t);
+  } catch (l) {
     try {
-      await c.writeFile(u, o, "utf8"), await c.rename(u, i), e._lruSet(i, t);
-    } catch (l) {
-      try {
-        await c.unlink(u);
-      } catch {
-      }
-      throw l;
+      await c.unlink(a);
+    } catch {
     }
-  } else
-    throw new E(r);
+    throw l;
+  }
+}
+function nt(e, t, ...n) {
+  if (!e || !e.write)
+    return;
+  const i = e._getPath(...n);
+  u(i);
+  const r = b(x(i));
+  y.has(r) || (G(r, { recursive: !0 }), y.add(r));
+  const s = z(t), a = S(r, `.cachetta-${L(8).toString("hex")}.tmp`);
+  try {
+    j(a, s), A(a, i), e._lruSet(i, t);
+  } catch (l) {
+    try {
+      P(a);
+    } catch {
+    }
+    throw l;
+  }
 }
-const w = /* @__PURE__ */ new Map(), S = /* @__PURE__ */ new Set(), g = (e, t) => {
+const m = /* @__PURE__ */ new Map(), $ = /* @__PURE__ */ new Set(), _ = (e, t) => {
   async function n(...i) {
-    const r = await W(e, ...i);
+    const r = await Z(e, ...i);
     if (r != null)
       return r;
     const s = e._getPath(...i);
     if (e.staleDuration) {
-      const l = await H(e, ...i);
-      if (l != null)
-        return !S.has(s) && !w.has(s) && (S.add(s), (async () => {
+      const h = await tt(e, ...i);
+      if (h != null)
+        return !$.has(s) && !m.has(s) && ($.add(s), (async () => {
           try {
-            const f = await t.apply(this, i);
-            (!e.condition || e.condition(f)) && await y(e, f, ...i);
-          } catch (f) {
-            a.error(`Background revalidation failed for ${s}: ${f}`);
+            const g = await t.apply(this, i);
+            (!e.condition || e.condition(g)) && await v(e, g, ...i);
+          } catch (g) {
+            o.error(`Background revalidation failed for ${s}: ${g}`);
           } finally {
-            S.delete(s);
+            $.delete(s);
           }
-        })()), l;
+        })()), h;
     }
-    const o = w.get(s);
-    if (o)
-      return o;
-    const u = (async () => {
-      const l = await t.apply(this, i);
-      return (!e.condition || e.condition(l)) && await y(e, l, ...i), l;
+    const a = m.get(s);
+    if (a)
+      return a;
+    const l = (async () => {
+      const h = await t.apply(this, i);
+      return (!e.condition || e.condition(h)) && await v(e, h, ...i), h;
     })();
-    w.set(s, u);
+    m.set(s, l);
     try {
-      return await u;
+      return await l;
     } finally {
-      w.delete(s);
+      m.delete(s);
+    }
+  }
+  return n;
+}, it = (e, t) => {
+  function n(...i) {
+    const r = B(e, ...i);
+    if (r != null)
+      return r;
+    if (e.staleDuration) {
+      const a = et(e, ...i);
+      if (a != null)
+        return a;
     }
+    const s = t.apply(this, i);
+    return (!e.condition || e.condition(s)) && nt(e, s, ...i), s;
   }
   return n;
-}, Y = 10080 * 60 * 1e3;
-class L extends Function {
+}, rt = 10080 * 60 * 1e3;
+class O extends Function {
   constructor(t) {
-    super(), this.__cacheBuddy__ = !0, this.path = t.path, this.write = t.write ?? !0, this.read = t.read ?? !0, this.duration = t.duration ?? Y, this.lruSize = t.lruSize, this.condition = t.condition, this.staleDuration = t.staleDuration, this._lru = this.lruSize ? /* @__PURE__ */ new Map() : void 0;
+    super(), this.__cacheBuddy__ = !0, this.path = t.path, this.write = t.write ?? !0, this.read = t.read ?? !0, this.duration = t.duration ?? rt, this.lruSize = t.lruSize, this.condition = t.condition, this.staleDuration = t.staleDuration, this._lru = this.lruSize ? /* @__PURE__ */ new Map() : void 0;
     const n = this.call.bind(this), i = Object.assign(
       n,
       this,
       {
         copy: this.copy.bind(this),
         wrap: this.wrap.bind(this),
+        wrapSync: this.wrapSync.bind(this),
         invalidate: this.invalidate.bind(this),
+        invalidateSync: this.invalidateSync.bind(this),
         clear: this.invalidate.bind(this),
         // alias
+        clearSync: this.invalidateSync.bind(this),
+        // alias
         exists: this.exists.bind(this),
+        existsSync: this.existsSync.bind(this),
         age: this.age.bind(this),
+        ageSync: this.ageSync.bind(this),
         info: this.info.bind(this),
+        infoSync: this.infoSync.bind(this),
         _getPath: this._getPath.bind(this),
         _lruGet: this._lruGet.bind(this),
         _lruSet: this._lruSet.bind(this),
@@ -214,17 +287,10 @@ class L extends Function {
         staleDuration: this.staleDuration
       }
     );
-    return i[O.custom] = () => `Cachetta { path: '${this.path}', write: ${this.write}, read: ${this.read}, duration: ${this.duration} }`, i;
+    return i[J.custom] = () => `Cachetta { path: '${this.path}', write: ${this.write}, read: ${this.read}, duration: ${this.duration} }`, i;
   }
-  /**
-   * Creates a copy of this Cachetta instance with overridden configuration.
-   * Useful for creating variations of a base cache configuration.
-   *
-   * @param kwargs - Partial configuration to override
-   * @returns A new Cachetta instance with the specified overrides
-   */
   copy(t) {
-    return new L({
+    return new O({
       path: t.path ?? this.path,
       write: t.write ?? this.write,
       read: t.read ?? this.read,
@@ -234,24 +300,15 @@ class L extends Function {
       staleDuration: t.staleDuration ?? this.staleDuration
     });
   }
-  /**
-   * Wraps a function with caching behavior. Alias for calling the cache instance directly.
-   *
-   * @param fn - The function to wrap
-   * @returns A cached version of the function
-   */
   wrap(t) {
-    return g(this, t);
+    return _(this, t);
+  }
+  wrapSync(t) {
+    return it(this, t);
   }
-  /**
-   * Deletes the cache file on disk and clears LRU entries for this path.
-   * No-op if the cache file does not exist.
-   *
-   * @param args - Arguments to resolve the cache path (when using a path function)
-   */
   async invalidate(...t) {
     const n = this._getPath(...t);
-    h(n), this._lru && this._lru.delete(n);
+    u(n), this._lru && this._lru.delete(n);
     try {
       await c.unlink(n);
     } catch (i) {
@@ -259,76 +316,71 @@ class L extends Function {
         throw i;
     }
   }
-  /**
-   * Checks whether the cache file exists on disk.
-   *
-   * @param args - Arguments to resolve the cache path (when using a path function)
-   * @returns true if the cache file exists
-   */
+  invalidateSync(...t) {
+    const n = this._getPath(...t);
+    u(n), this._lru && this._lru.delete(n);
+    try {
+      P(n);
+    } catch (i) {
+      if (i.code !== "ENOENT")
+        throw i;
+    }
+  }
   async exists(...t) {
     const n = this._getPath(...t);
-    return h(n), await d(n) !== null;
+    return u(n), await f(n) !== null;
+  }
+  existsSync(...t) {
+    const n = this._getPath(...t);
+    return u(n), p(n) !== null;
   }
-  /**
-   * Returns the age of the cache file in milliseconds, or null if it does not exist.
-   *
-   * @param args - Arguments to resolve the cache path (when using a path function)
-   * @returns Age in ms, or null
-   */
   async age(...t) {
     const n = this._getPath(...t);
-    h(n);
-    const i = await d(n);
-    return i === null ? null : Date.now() - i;
+    u(n);
+    const i = await f(n);
+    return i === null ? null : Math.max(0, Date.now() - i);
+  }
+  ageSync(...t) {
+    const n = this._getPath(...t);
+    u(n);
+    const i = p(n);
+    return i === null ? null : Math.max(0, Date.now() - i);
   }
-  /**
-   * Returns detailed information about the cache state.
-   *
-   * @param args - Arguments to resolve the cache path (when using a path function)
-   * @returns CacheInfo with exists, age, expired, stale, and path fields
-   */
   async info(...t) {
     const n = this._getPath(...t);
-    h(n);
-    const i = await d(n);
+    u(n);
+    const i = await f(n);
+    if (i === null)
+      return { exists: !1, age: null, expired: !1, stale: !1, path: n };
+    const r = Math.max(0, Date.now() - i), s = r >= this.duration, a = s && this.staleDuration != null && r < this.duration + this.staleDuration;
+    return { exists: !0, age: r, expired: s, stale: a, path: n };
+  }
+  infoSync(...t) {
+    const n = this._getPath(...t);
+    u(n);
+    const i = p(n);
     if (i === null)
       return { exists: !1, age: null, expired: !1, stale: !1, path: n };
-    const r = Date.now() - i, s = r >= this.duration, o = s && this.staleDuration != null && r < this.duration + this.staleDuration;
-    return { exists: !0, age: r, expired: s, stale: o, path: n };
+    const r = Math.max(0, Date.now() - i), s = r >= this.duration, a = s && this.staleDuration != null && r < this.duration + this.staleDuration;
+    return { exists: !0, age: r, expired: s, stale: a, path: n };
   }
-  /**
-   * Internal method to resolve the cache path.
-   * When path is a string and arguments are provided, auto-generates a unique
-   * cache path by hashing the arguments.
-   * @internal
-   */
   _getPath(...t) {
     if (typeof this.path == "string") {
       if (t.length === 0)
         return this.path;
-      const n = N("sha256").update(JSON.stringify(t)).digest("hex").slice(0, 16), i = C(this.path), r = this.path.split("/").pop(), s = r.lastIndexOf(".");
+      const n = H("sha256").update(JSON.stringify(t)).digest("hex").slice(0, 16), i = x(this.path), r = this.path.split("/").pop(), s = r.lastIndexOf(".");
       if (s === -1)
-        return $(i, `${r}-${n}`);
-      const o = r.slice(0, s), u = r.slice(s);
-      return $(i, `${o}-${n}${u}`);
+        return S(i, `${r}-${n}`);
+      const a = r.slice(0, s), l = r.slice(s);
+      return S(i, `${a}-${n}${l}`);
     }
     return this.path(...t);
   }
-  /**
-   * Get a value from the in-memory LRU cache.
-   * Returns undefined if LRU is disabled, key not found, or entry is expired.
-   * @internal
-   */
   _lruGet(t) {
-    if (!this._lru) return _;
+    if (!this._lru) return d;
     const n = this._lru.get(t);
-    return n ? Date.now() - n.timestamp > this.duration ? (this._lru.delete(t), _) : (this._lru.delete(t), this._lru.set(t, n), n.value) : _;
+    return n ? Date.now() - n.timestamp > this.duration ? (this._lru.delete(t), d) : (this._lru.delete(t), this._lru.set(t, n), n.value) : d;
   }
-  /**
-   * Set a value in the in-memory LRU cache.
-   * No-op if LRU is disabled.
-   * @internal
-   */
   _lruSet(t, n) {
     if (!(!this._lru || !this.lruSize)) {
       if (this._lru.size >= this.lruSize && !this._lru.has(t)) {
@@ -340,29 +392,30 @@ class L extends Function {
   }
   // Implementation signature
   call(t, n, i) {
-    if (F(t)) {
+    if (k(t)) {
       const s = t;
       return this.copy(s);
     }
     if (i) {
       const s = i.value;
-      return i.value = g(this, s), i;
+      return i.value = _(this, s), i;
     }
     const r = t;
     if (n) {
-      const s = n, o = this.copy(s);
-      return g(o, r);
+      const s = n, a = this.copy(s);
+      return _(a, r);
     }
-    return g(this, r);
+    return _(this, r);
   }
 }
 export {
-  L as Cachetta,
-  m as CachettaError,
-  M as InvalidPathError,
-  E as UnsupportedFormatError,
-  W as readCache,
-  Z as setLogLevel,
-  k as setLogger,
-  y as writeCache
+  O as Cachetta,
+  C as CachettaError,
+  Y as InvalidPathError,
+  Z as readCache,
+  B as readCacheSync,
+  ct as setLogLevel,
+  ht as setLogger,
+  v as writeCache,
+  nt as writeCacheSync
 };

package/dist/src/Cachetta.d.ts

@@ -1,4 +1,4 @@
-import { CacheConfig, CacheInfo, CachableFunction, PathFn } from './types.js';
+import { CacheConfig, CacheInfo, CachableFunction, CachableFunctionSync, PathFn } from './types.js';
 import { LRU_MISS } from './constants.js';
 interface LruEntry {
     value: unknown;
@@ -18,67 +18,19 @@ export declare class Cachetta<Path extends string | PathFn<any> = string> extend
     /** @internal */
     _lru: Map<string, LruEntry> | undefined;
     constructor(config: CacheConfig<Path>);
-    /**
-     * Creates a copy of this Cachetta instance with overridden configuration.
-     * Useful for creating variations of a base cache configuration.
-     *
-     * @param kwargs - Partial configuration to override
-     * @returns A new Cachetta instance with the specified overrides
-     */
     copy<NewPath extends string | PathFn<any> = string>(kwargs: Partial<CacheConfig<NewPath>>): Cachetta<NewPath>;
-    /**
-     * Wraps a function with caching behavior. Alias for calling the cache instance directly.
-     *
-     * @param fn - The function to wrap
-     * @returns A cached version of the function
-     */
     wrap(fn: CachableFunction): CachableFunction;
-    /**
-     * Deletes the cache file on disk and clears LRU entries for this path.
-     * No-op if the cache file does not exist.
-     *
-     * @param args - Arguments to resolve the cache path (when using a path function)
-     */
+    wrapSync(fn: CachableFunctionSync): CachableFunctionSync;
     invalidate(...args: unknown[]): Promise<void>;
-    /**
-     * Checks whether the cache file exists on disk.
-     *
-     * @param args - Arguments to resolve the cache path (when using a path function)
-     * @returns true if the cache file exists
-     */
+    invalidateSync(...args: unknown[]): void;
     exists(...args: unknown[]): Promise<boolean>;
-    /**
-     * Returns the age of the cache file in milliseconds, or null if it does not exist.
-     *
-     * @param args - Arguments to resolve the cache path (when using a path function)
-     * @returns Age in ms, or null
-     */
+    existsSync(...args: unknown[]): boolean;
     age(...args: unknown[]): Promise<number | null>;
-    /**
-     * Returns detailed information about the cache state.
-     *
-     * @param args - Arguments to resolve the cache path (when using a path function)
-     * @returns CacheInfo with exists, age, expired, stale, and path fields
-     */
+    ageSync(...args: unknown[]): number | null;
     info(...args: unknown[]): Promise<CacheInfo>;
-    /**
-     * Internal method to resolve the cache path.
-     * When path is a string and arguments are provided, auto-generates a unique
-     * cache path by hashing the arguments.
-     * @internal
-     */
+    infoSync(...args: unknown[]): CacheInfo;
     _getPath(...args: unknown[]): string;
-    /**
-     * Get a value from the in-memory LRU cache.
-     * Returns undefined if LRU is disabled, key not found, or entry is expired.
-     * @internal
-     */
     _lruGet(key: string): unknown | typeof LRU_MISS;
-    /**
-     * Set a value in the in-memory LRU cache.
-     * No-op if LRU is disabled.
-     * @internal
-     */
     _lruSet(key: string, value: unknown): void;
     call(target: CachableFunction, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor;
     call(target: CachableFunction): CachableFunction;

package/dist/src/errors.d.ts

@@ -4,6 +4,3 @@ export declare class CachettaError extends Error {
 export declare class InvalidPathError extends CachettaError {
     constructor(cachePath: string);
 }
-export declare class UnsupportedFormatError extends CachettaError {
-    constructor(extension: string);
-}

package/dist/src/index.d.ts

@@ -1,6 +1,6 @@
 export { Cachetta } from './Cachetta.js';
-export { writeCache } from './write-cache.js';
-export { readCache } from './read-cache.js';
+export { writeCache, writeCacheSync } from './write-cache.js';
+export { readCache, readCacheSync } from './read-cache.js';
 export { setLogLevel, setLogger } from './utils/logger.js';
-export { CachettaError, InvalidPathError, UnsupportedFormatError } from './errors.js';
-export type { CacheConfig, CacheInfo, PathFn, CachableFunction, Logger, LogLevel } from './types.js';
+export { CachettaError, InvalidPathError } from './errors.js';
+export type { CacheConfig, CacheInfo, PathFn, CachableFunction, CachableFunctionSync, Logger, LogLevel } from './types.js';

package/dist/src/read-cache.d.ts

@@ -1,8 +1,11 @@
 import { Cachetta } from './Cachetta.js';
 export declare function readCache<T>(cacheBuddy: Cachetta<any>, ...args: unknown[]): Promise<T | null>;
+export declare function readCacheSync<T>(cacheBuddy: Cachetta<any>, ...args: unknown[]): T | null;
 /**
  * Reads stale cache data: returns data only if the file exists and is within the
  * staleDuration window (expired but not yet past duration + staleDuration).
  * @internal
  */
 export declare function readStaleCache<T>(cacheBuddy: Cachetta<any>, ...args: unknown[]): Promise<T | null>;
+/** @internal */
+export declare function readStaleCacheSync<T>(cacheBuddy: Cachetta<any>, ...args: unknown[]): T | null;

package/dist/src/types.d.ts

@@ -18,6 +18,7 @@ export interface CacheInfo {
 }
 export type PathFn<T extends unknown[] = unknown[]> = (...args: T) => string;
 export type CachableFunction = (...args: unknown[]) => unknown;
+export type CachableFunctionSync = (...args: unknown[]) => unknown;
 export interface Logger {
     debug: (...messages: unknown[]) => void;
     info: (...messages: unknown[]) => void;

package/dist/src/utils/cache-fn.d.ts

@@ -1,3 +1,4 @@
 import { Cachetta } from '../Cachetta.js';
-import { CachableFunction } from '../types.js';
+import { CachableFunction, CachableFunctionSync } from '../types.js';
 export declare const cacheFn: (cache: Cachetta<any>, originalMethod: CachableFunction) => (this: ThisParameterType<typeof originalMethod>, ...args: Parameters<typeof originalMethod>) => Promise<unknown>;
+export declare const cacheFnSync: (cache: Cachetta<any>, originalMethod: CachableFunctionSync) => (this: any, ...args: unknown[]) => unknown;

package/dist/src/utils/get-last-updated.d.ts

@@ -1,2 +1,3 @@
 import { PathLike } from 'fs';
 export declare function getLastUpdated(filePath: string | PathLike): Promise<number | null>;
+export declare function getLastUpdatedSync(filePath: string | PathLike): number | null;

package/dist/src/utils/should-use-read-cache.d.ts

@@ -1,2 +1,3 @@
 import { CacheConfig } from '../types.js';
 export declare function shouldUseReadCache({ duration, read }: Pick<CacheConfig, 'duration' | 'read'>, cachePath: string): Promise<boolean>;
+export declare function shouldUseReadCacheSync({ duration, read }: Pick<CacheConfig, 'duration' | 'read'>, cachePath: string): boolean;

package/dist/src/write-cache.d.ts

@@ -1,2 +1,3 @@
 import { Cachetta } from './Cachetta.js';
 export declare function writeCache<T>(cache: Cachetta<any>, data: T, ...args: unknown[]): Promise<void>;
+export declare function writeCacheSync<T>(cache: Cachetta<any>, data: T, ...args: unknown[]): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cachetta",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -25,9 +25,25 @@
     "test:unit:watch": "wireit",
     "test:integration": "wireit",
     "test:integration:watch": "wireit",
+    "lint": "wireit",
+    "typecheck": "wireit",
     "build": "wireit"
   },
   "wireit": {
+    "lint": {
+      "command": "eslint src",
+      "files": [
+        "./src/**/*.ts",
+        "./eslint.config.js"
+      ]
+    },
+    "typecheck": {
+      "command": "tsc --noEmit",
+      "files": [
+        "./src/**/*.ts",
+        "./tsconfig.json"
+      ]
+    },
     "test:unit": {
       "command": "vitest run -c vitest.config.unit.ts"
     },
@@ -61,13 +77,15 @@
     }
   },
   "devDependencies": {
-    "cachetta": "workspace:*",
+    "@eslint/js": "^9.39.2",
     "@types/node": "^22.10.0",
+    "cachetta": "workspace:*",
+    "eslint": "^9.39.2",
     "typescript": "^5.7.2",
+    "typescript-eslint": "^8.55.0",
     "vite": "^6.0.0",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^2.1.6",
     "wireit": "^0.14.9"
-  },
-  "dependencies": {}
+  }
 }

package/dist/src/utils/get-extension.d.ts

@@ -1,2 +0,0 @@
-import { PathLike } from 'fs';
-export declare function getExtension(cachePath: string | PathLike): string;

package/dist/src/utils/get-extension.test.d.ts

@@ -1 +0,0 @@
-export {};