cachetta 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Scott
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,431 @@
+# Cachetta for JavaScript/TypeScript
+
+File-based JSON caching for JavaScript and TypeScript. Part of the [Cachetta](../../README.md) project, which provides the same caching API in both JS/TS and Python -- learn it once, use it in either language.
+
+## Install
+
+```bash
+pnpm add cachetta
+```
+
+## Features
+
+- **Local File Storage**: Supports local files with automatic directory creation
+- **JSON Serialization**: JSON-based caching (native JavaScript support)
+- **Async Support**: Works with both synchronous and asynchronous functions
+- **Automatic Expiration**: Cache expiration based on file modification time
+- **In-Memory LRU**: Optional in-memory LRU layer for fast repeated access
+- **Stale-While-Revalidate**: Serve stale data while refreshing in the background
+- **Conditional Caching**: Cache only when a condition is met
+- **Cache Inspection**: Check existence, age, and expiry state of cache entries
+- **Auto Cache Keys**: Automatic unique paths based on function arguments
+- **Flexible Paths**: Dynamic cache paths using functions
+- **Error Handling**: Graceful handling of corrupt cache files
+- **Logging**: Built-in logging for debugging
+
+## Usage
+
+### Basic Usage
+
+Create a cache object:
+
+```javascript
+import { Cachetta } from 'cachetta';
+
+const cache = new Cachetta({
+  read: true, // allow reading from local caches
+  write: true, // allow writing to local caches
+  path: './cache.json', // specify path to cache file
+  duration: 24 * 60 * 60 * 1000, // specify length of cache in milliseconds (1 day)
+});
+```
+
+Read and write to a cache object:
+
+```javascript
+import { readCache, writeCache } from 'cachetta';
+
+async function getData() {
+  const cachedData = await readCache(cache);
+  if (cachedData) {
+    return cachedData;
+  } else {
+    const data = await fetchData(); // some long running process
+    await writeCache(cache, data);
+    return data;
+  }
+}
+```
+
+### Specifying paths
+
+You can specify a base path for your cache folder and then quickly specify cache paths within that folder:
+
+```javascript
+import { readCache, writeCache, Cachetta } from 'cachetta';
+import path from 'path';
+
+const cache = new Cachetta({
+  path: './cache', // our base cache folder
+});
+
+async function getData() {
+  // specify your file path like below:
+  const cachePath = path.join(cache.path, 'my-data.json');
+  const cachedData = await readCache(cache.copy({ path: cachePath }));
+  // ...
+}
+```
+
+For modifying other attributes of a base `cache` object, use `copy`:
+
+```javascript
+const cache = new Cachetta({
+  path: './cache', // our base cache folder
+});
+
+const newCache = cache.copy({
+  read: false,
+  write: false,
+  duration: 2 * 24 * 60 * 60 * 1000, // 2 days
+});
+```
+
+**Note**: The `copy` method is the intended public API for creating variations of cache configurations. It creates a new `Cachetta` instance with the specified overrides while preserving the original configuration.
+
+### Decorators
+
+You can use `Cachetta` as a decorator (requires experimental decorators):
+
+```javascript
+import { Cachetta } from 'cachetta';
+
+class DataService {
+  @Cachetta({ path: '/my-cache.json' })
+  async getData() {
+    const parts = [];
+    for (let i = 0; i < 10; i++) {
+      parts.push(i);
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+    return parts;
+  }
+}
+```
+
+You can also use a specific cache object as a decorator:
+
+```javascript
+import { Cachetta } from 'cachetta';
+
+const cache = new Cachetta({ path: '/my-cache.json' });
+
+class DataService {
+  @cache
+  async getData() {
+    const parts = [];
+    for (let i = 0; i < 10; i++) {
+      parts.push(i);
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+    return parts;
+  }
+}
+```
+
+Or with arguments:
+
+```javascript
+import { Cachetta } from 'cachetta';
+
+const cache = new Cachetta({ path: '/my-cache.json' });
+
+class DataService {
+  @cache({ duration: 1000 })
+  async getData() {
+    const parts = [];
+    for (let i = 0; i < 10; i++) {
+      parts.push(i);
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+    return parts;
+  }
+}
+```
+
+**Important Note**: Decorated functions always return Promises, even if the original function is synchronous. This is because the caching mechanism involves async file operations. Always use `await` when calling decorated functions:
+
+```javascript
+const cache = new Cachetta({ path: './cache.json' });
+
+// Even though this is a sync function, the decorated version returns a Promise
+const cachedFunction = cache.call(() => {
+  return "Hello World";
+});
+
+// Must await the result
+const result = await cachedFunction();
+console.log(result); // "Hello World"
+```
+
+### Async Function Support
+
+Cachetta works seamlessly with async functions:
+
+```javascript
+import { Cachetta } from 'cachetta';
+
+@Cachetta({ path: './async-cache.json' })
+async function getAsyncData() {
+  // Simulate async API call
+  await new Promise(resolve => setTimeout(resolve, 2000));
+  return { status: "success", data: [1, 2, 3] };
+}
+
+// Usage
+async function main() {
+  const result = await getAsyncData();
+  console.log(result);
+}
+```
+
+### Auto Cache Keys
+
+When a wrapped function receives arguments, Cachetta automatically generates unique cache paths by hashing the arguments:
+
+```javascript
+const cache = new Cachetta({ path: './cache/users.json' });
+
+const getUser = cache((userId) => fetchUser(userId));
+
+await getUser(1);   // cached at ./cache/users-<hash1>.json
+await getUser(2);   // cached at ./cache/users-<hash2>.json
+```
+
+### In-Memory LRU
+
+Add an in-memory LRU layer that is checked before hitting disk:
+
+```javascript
+const cache = new Cachetta({
+  path: './cache.json',
+  lruSize: 100,  // keep up to 100 entries in memory
+});
+```
+
+LRU entries respect the same `duration` as disk entries and use lazy expiration (evicted on access, not via background timers).
+
+### Conditional Caching
+
+Cache results only when a condition function returns `true`:
+
+```javascript
+const cache = new Cachetta({
+  path: './cache.json',
+  condition: (result) => result !== null,  // don't cache null
+});
+```
+
+### Stale-While-Revalidate
+
+Return expired (stale) data immediately while refreshing the cache in the background:
+
+```javascript
+const cache = new Cachetta({
+  path: './cache.json',
+  duration: 60 * 60 * 1000,           // 1 hour
+  staleDuration: 30 * 60 * 1000,      // serve stale data up to 30min past expiry
+});
+```
+
+### Cache Invalidation
+
+Delete cache files on disk:
+
+```javascript
+const cache = new Cachetta({ path: './cache.json' });
+
+await cache.invalidate();  // or cache.clear()
+
+// With arguments (when using path functions)
+await cache.invalidate('userId');
+```
+
+### Cache Inspection
+
+Query cache state without reading the cached data:
+
+```javascript
+const cache = new Cachetta({ path: './cache.json' });
+
+await cache.exists();   // true if the cache file exists
+await cache.age();      // age in milliseconds, or null
+await cache.info();     // { exists: true, age: 1234, expired: false, stale: false, path: "..." }
+```
+
+### Dynamic Cache Paths
+
+You can specify a function for defining the path as well:
+
+```javascript
+function getCachePath(n) {
+  return `./cache/${n}.json`;
+}
+
+@Cachetta({ path: getCachePath })
+async function foo(n) {
+  const parts = [];
+  for (let i = 0; i < n; i++) {
+    parts.push(i);
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+  return parts;
+}
+```
+
+Or, using a pre-existing cache object:
+
+```javascript
+const cache = new Cachetta({ path: './cache' });
+
+function getCachePath(n) {
+  return path.join(cache.path, `${n}.json`);
+}
+
+@cache.copy({ path: getCachePath })
+async function foo(n) {
+  const parts = [];
+  for (let i = 0; i < n; i++) {
+    parts.push(i);
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+  return parts;
+}
+```
+
+### Function Wrapper (Alternative to Decorators)
+
+If you're not using decorators, you can wrap functions manually:
+
+```javascript
+import { Cachetta } from 'cachetta';
+
+const cache = new Cachetta({ path: './my-cache.json' });
+
+async function getData() {
+  const parts = [];
+  for (let i = 0; i < 10; i++) {
+    parts.push(i);
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+  return parts;
+}
+
+// Wrap the function with caching
+const cachedGetData = cache(getData);
+
+// Usage - always await the result, even for sync functions
+const result = await cachedGetData();
+```
+
+You can also pass configuration when wrapping:
+
+```javascript
+const cache = new Cachetta({ path: './cache' });
+
+function getData(id) {
+  return { id, data: 'some data' };
+}
+
+// Wrap with specific configuration
+const cachedGetData = cache(getData, {
+  path: (id) => `./cache/data-${id}.json`,
+  duration: 5000
+});
+
+// Usage
+const result = await cachedGetData(123);
+```
+
+**Note**: Wrapped functions always return Promises, even if the original function is synchronous, due to the async nature of file operations in the caching mechanism.
+
+### Error Handling
+
+Cachetta gracefully handles corrupt cache files:
+
+```javascript
+import { readCache, writeCache, Cachetta } from 'cachetta';
+
+const cache = new Cachetta({ path: './corrupt-cache.json' });
+
+// If the cache file is corrupt, readCache will return null
+async function getData() {
+  const data = await readCache(cache);
+  if (data === null) {
+    // Cache is missing or corrupt, regenerate data
+    const freshData = await fetchFreshData();
+    await writeCache(cache, freshData);
+    return freshData;
+  }
+  return data;
+}
+```
+
+### Logging
+
+Cachetta provides detailed logging for debugging. You can configure the log level:
+
+```javascript
+import { setLogLevel } from 'cachetta';
+
+// Enable debug logging
+setLogLevel('debug');
+
+// Available levels: 'error', 'warn', 'info', 'debug'
+// Default is 'warn'
+```
+
+Cachetta uses a simple logger that outputs to `console` by default, but you can also configure it to use your preferred logging library:
+
+```javascript
+import { setLogger } from 'cachetta';
+
+// Use a custom logger (e.g., winston, pino)
+setLogger({
+  debug: (msg) => console.debug(`[Cachetta] ${msg}`),
+  info: (msg) => console.info(`[Cachetta] ${msg}`),
+  warn: (msg) => console.warn(`[Cachetta] ${msg}`),
+  error: (msg) => console.error(`[Cachetta] ${msg}`),
+});
+```
+
+### TypeScript Support
+
+Cachetta includes full TypeScript support:
+
+```typescript
+import { Cachetta } from 'cachetta';
+
+interface UserData {
+  id: number;
+  name: string;
+  email: string;
+}
+
+const cache = new Cachetta<UserData>({
+  path: './user-cache.json',
+});
+
+@cache
+async function fetchUserData(id: number): Promise<UserData> {
+  // API call implementation
+  return { id, name: 'John Doe', email: 'john@example.com' };
+}
+```
+
+### Default Configuration
+
+- **Default duration**: 7 days (7 * 24 * 60 * 60 * 1000 milliseconds)
+- **Default read**: `true`
+- **Default write**: `true`
+- **Supported format**: JSON only

package/dist/index.js

@@ -0,0 +1,368 @@
+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";
+  }
+}
+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) {
+  try {
+    return (await c.stat(e)).mtime.getTime();
+  } catch (t) {
+    if (t.code === "ENOENT")
+      return null;
+    throw t;
+  }
+}
+function A(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) => {
+  switch (e) {
+    case "debug":
+      return console.debug;
+    case "info":
+      return console.info;
+    case "warn":
+      return console.warn;
+    case "error":
+      return console.error;
+  }
+}, p = (e) => (...t) => {
+  if (G(e)) {
+    const n = J(e);
+    n && n("[Cachetta]", ...t);
+  }
+};
+let a = {
+  debug: p("debug"),
+  info: p("info"),
+  warn: p("warn"),
+  error: p("error")
+};
+function Z(e) {
+  P = e;
+}
+function k(e) {
+  a = e;
+}
+async function T({ duration: e, read: t }, n) {
+  const i = e ?? 6048e5, r = await d(n);
+  if (r === null)
+    return a.debug(`Cache time is null for ${n}`), !1;
+  if (i <= 0)
+    return a.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(
+    `Cache is expired (${r}, expected ${r + i}) for ${n}`
+  ), !1) : (a.debug(
+    `Cache is not expired (${r}, expected ${r + i}) for ${n}`
+  ), t ?? !0);
+}
+function h(e) {
+  const t = I(e);
+  if (t.split(/[/\\]/).includes(".."))
+    throw new M(e);
+  return D(t);
+}
+const K = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+async function z(e) {
+  const t = v(e);
+  if (t !== "json")
+    throw new E(t);
+  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);
+  }
+}
+async function W(e, ...t) {
+  if (!j(e))
+    throw new m(`Invalid value provided, you must provide an instance of Cachetta: ${e}`);
+  const n = e._getPath(...t);
+  h(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;
+  } else
+    return a.debug("cache.read is false, skipping cache"), null;
+}
+async function H(e, ...t) {
+  if (!e.staleDuration || !e.read) return null;
+  const n = e._getPath(...t);
+  h(n);
+  const i = await d(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 b = /* @__PURE__ */ new Set();
+async function y(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`);
+    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;
+    }
+  } else
+    throw new E(r);
+}
+const w = /* @__PURE__ */ new Map(), S = /* @__PURE__ */ new Set(), g = (e, t) => {
+  async function n(...i) {
+    const r = await W(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 () => {
+          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}`);
+          } finally {
+            S.delete(s);
+          }
+        })()), l;
+    }
+    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;
+    })();
+    w.set(s, u);
+    try {
+      return await u;
+    } finally {
+      w.delete(s);
+    }
+  }
+  return n;
+}, Y = 10080 * 60 * 1e3;
+class L 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;
+    const n = this.call.bind(this), i = Object.assign(
+      n,
+      this,
+      {
+        copy: this.copy.bind(this),
+        wrap: this.wrap.bind(this),
+        invalidate: this.invalidate.bind(this),
+        clear: this.invalidate.bind(this),
+        // alias
+        exists: this.exists.bind(this),
+        age: this.age.bind(this),
+        info: this.info.bind(this),
+        _getPath: this._getPath.bind(this),
+        _lruGet: this._lruGet.bind(this),
+        _lruSet: this._lruSet.bind(this),
+        __cacheBuddy__: !0,
+        _lru: this._lru,
+        lruSize: this.lruSize,
+        condition: this.condition,
+        staleDuration: this.staleDuration
+      }
+    );
+    return i[O.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({
+      path: t.path ?? this.path,
+      write: t.write ?? this.write,
+      read: t.read ?? this.read,
+      duration: t.duration ?? this.duration,
+      lruSize: t.lruSize ?? this.lruSize,
+      condition: t.condition ?? this.condition,
+      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);
+  }
+  /**
+   * 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);
+    try {
+      await c.unlink(n);
+    } catch (i) {
+      if (i.code !== "ENOENT")
+        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
+   */
+  async exists(...t) {
+    const n = this._getPath(...t);
+    return h(n), await d(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;
+  }
+  /**
+   * 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);
+    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 };
+  }
+  /**
+   * 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(".");
+      if (s === -1)
+        return $(i, `${r}-${n}`);
+      const o = r.slice(0, s), u = r.slice(s);
+      return $(i, `${o}-${n}${u}`);
+    }
+    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 _;
+    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) : _;
+  }
+  /**
+   * 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)) {
+        const i = this._lru.keys().next().value;
+        i !== void 0 && this._lru.delete(i);
+      }
+      this._lru.set(t, { value: n, timestamp: Date.now() });
+    }
+  }
+  // Implementation signature
+  call(t, n, i) {
+    if (F(t)) {
+      const s = t;
+      return this.copy(s);
+    }
+    if (i) {
+      const s = i.value;
+      return i.value = g(this, s), i;
+    }
+    const r = t;
+    if (n) {
+      const s = n, o = this.copy(s);
+      return g(o, r);
+    }
+    return g(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
+};

package/dist/src/Cachetta.d.ts

@@ -0,0 +1,87 @@
+import { CacheConfig, CacheInfo, CachableFunction, PathFn } from './types.js';
+import { LRU_MISS } from './constants.js';
+interface LruEntry {
+    value: unknown;
+    timestamp: number;
+}
+export declare class Cachetta<Path extends string | PathFn<any> = string> extends Function {
+    protected __cacheBuddy__: boolean;
+    path: Path;
+    write: boolean;
+    read: boolean;
+    duration: number;
+    lruSize: number | undefined;
+    condition: ((result: unknown) => boolean) | undefined;
+    staleDuration: number | undefined;
+    /** Alias for {@link invalidate}. Deletes the cache file. */
+    clear: (...args: unknown[]) => Promise<void>;
+    /** @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)
+     */
+    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
+     */
+    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
+     */
+    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
+     */
+    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
+     */
+    _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;
+    call(config: Partial<CacheConfig>): Cachetta;
+}
+export {};

package/dist/src/Cachetta.test.d.ts

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

package/dist/src/constants.d.ts

@@ -0,0 +1,2 @@
+/** Sentinel value returned by _lruGet on cache miss, distinguishable from any cached value including undefined/null. */
+export declare const LRU_MISS: unique symbol;

package/dist/src/errors.d.ts

@@ -0,0 +1,9 @@
+export declare class CachettaError extends Error {
+    constructor(message: string);
+}
+export declare class InvalidPathError extends CachettaError {
+    constructor(cachePath: string);
+}
+export declare class UnsupportedFormatError extends CachettaError {
+    constructor(extension: string);
+}

package/dist/src/errors.test.d.ts

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

package/dist/src/index.d.ts

@@ -0,0 +1,6 @@
+export { Cachetta } from './Cachetta.js';
+export { writeCache } from './write-cache.js';
+export { readCache } 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';

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

@@ -0,0 +1,8 @@
+import { Cachetta } from './Cachetta.js';
+export declare function readCache<T>(cacheBuddy: Cachetta<any>, ...args: unknown[]): Promise<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>;

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

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

package/dist/src/type-guards.d.ts

@@ -0,0 +1,5 @@
+import { Cachetta } from './Cachetta.js';
+import { CacheConfig } from './types.js';
+export declare const isCacheConfig: (value: unknown) => value is CacheConfig;
+export declare const isPartialCacheConfig: (value: unknown) => value is Partial<CacheConfig>;
+export declare const isCachetta: (value: unknown) => value is Cachetta<any>;

package/dist/src/type-guards.test.d.ts

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

package/dist/src/types.d.ts

@@ -0,0 +1,27 @@
+export interface CacheConfig<Path extends string | PathFn<any> = string> {
+    path: Path;
+    write?: boolean;
+    read?: boolean;
+    duration?: number;
+    lruSize?: number;
+    /** Function that decides whether to cache a result. Return true to cache, false to skip. */
+    condition?: (result: unknown) => boolean;
+    /** Duration in ms after `duration` expires during which stale data is returned while a background refresh runs. */
+    staleDuration?: number;
+}
+export interface CacheInfo {
+    exists: boolean;
+    age: number | null;
+    expired: boolean;
+    stale: boolean;
+    path: string;
+}
+export type PathFn<T extends unknown[] = unknown[]> = (...args: T) => string;
+export type CachableFunction = (...args: unknown[]) => unknown;
+export interface Logger {
+    debug: (...messages: unknown[]) => void;
+    info: (...messages: unknown[]) => void;
+    warn: (...messages: unknown[]) => void;
+    error: (...messages: unknown[]) => void;
+}
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';

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

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

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

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

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

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

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

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

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

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

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

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

package/dist/src/utils/is-cache-expired.d.ts

@@ -0,0 +1 @@
+export declare function isCacheExpired(cacheTime: number, now: number, cacheLength: number): boolean;

package/dist/src/utils/is-cache-expired.test.d.ts

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

package/dist/src/utils/logger.d.ts

@@ -0,0 +1,4 @@
+import { Logger, LogLevel } from '../types.js';
+export declare let logger: Logger;
+export declare function setLogLevel(level: LogLevel): void;
+export declare function setLogger(customLogger: Logger): void;

package/dist/src/utils/logger.test.d.ts

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

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

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

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

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

package/dist/src/utils/validate-cache-path.d.ts

@@ -0,0 +1 @@
+export declare function validateCachePath(cachePath: string): string;

package/dist/src/utils/validate-cache-path.test.d.ts

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

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

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

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

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

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "cachetta",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "wireit": {
+    "test:unit": {
+      "command": "vitest run -c vitest.config.unit.ts"
+    },
+    "test:unit:watch": {
+      "command": "vitest watch -c vitest.config.unit.ts"
+    },
+    "test:integration": {
+      "command": "vitest run -c vitest.config.integration.ts",
+      "dependencies": [
+        "build"
+      ]
+    },
+    "test:integration:watch": {
+      "command": "vitest watch -c vitest.config.integration.ts",
+      "dependencies": [
+        "build"
+      ]
+    },
+    "build": {
+      "command": "vite build",
+      "dependencies": [],
+      "files": [
+        "./src/**/*.ts",
+        "./tsconfig.json",
+        "./package.json",
+        "./vite.config.ts"
+      ],
+      "output": [
+        "dist"
+      ]
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^2.1.6",
+    "wireit": "^0.14.9",
+    "cachetta": "0.1.0"
+  },
+  "dependencies": {},
+  "scripts": {
+    "test:unit": "wireit",
+    "test:unit:watch": "wireit",
+    "test:integration": "wireit",
+    "test:integration:watch": "wireit",
+    "build": "wireit"
+  }
+}