@chriscdn/file-cache 0.0.1

package/.gitattributes

@@ -0,0 +1 @@
+*.pdf filter=lfs diff=lfs merge=lfs -text

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Christopher Meyer
+
+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,98 @@
+# @chriscdn/file-cache
+
+`FileCache` is a node utility for caching generated and remote files. Common use cases include:
+
+- **Caching files stored in Amazon S3**: Keep a local cache of frequently accessed files to avoid repeatedly fetching them.
+- **Thumbnail caching**: Store generated thumbnails locally for quick access instead of regenerating them every time.
+
+`FileCache` does not store state in memory, meaning your cache remains unaffected by application restarts. Cached files are automatically expired using a time-to-live (TTL) policy and the file's modified date. The file's modified date is updated each time the file is accessed.
+
+## Installing
+
+Using npm:
+
+```bash
+npm install @chriscdn/file-cache
+```
+
+Using yarn:
+
+```bash
+yarn add @chriscdn/file-cache
+```
+
+## Usage
+
+The general approach is this:
+
+- **Create a callback** — Write an async function that takes a file path and your custom input (like a URL), then generates or downloads the file and saves it to the path.
+- **Set up the cache** — Initialize a `FileCache` with your callback and some options (like where to store files and how long to keep them).
+- **Get a file** — Call the cache with your input. It will:
+  - Hash the input to create a unique file name.
+  - If the file is already cached and still valid, return its path.
+  - If not, run your callback to create it, then cache and return the path.
+
+Here's an example of an image cache:
+
+```ts
+import { FileCache, type FileCacheOptions } from "@chriscdn/file-cache";
+
+// not required, but helps with duration calculations
+import { Duration } from "@chriscdn/duration";
+
+const downloadAndConvertToJPG = async (url: string, filePath: string) => {
+  // ...
+};
+
+type MyCallbackArgs = {
+  url: string;
+};
+
+const options: FileCacheOptions<MyCallbackArgs> = {
+  // The path to the cache directory. The directory must exist. Do not store
+  // anything else in this directory.
+  cachePath: "/some/path/on/your/filesystem/",
+
+  // An asynchronous callback function, which is executed if no matching cached
+  // file is found. It is the responsibility of this function to use `context`
+  // to write a file to `filePath`.
+  cb: async (filePath: string, context: MyCallbackArgs) => {
+    const { url } = context;
+    await downloadAndConvertToJPG(url, filePath);
+  },
+
+  // Specifies the file extension for each cached file.
+  // Currently, all files share the same extension (this may change in the future).
+  ext: ".jpg",
+
+  // Determines the time-to-live (TTL) of a cached file, in milliseconds,
+  // based on when it was last accessed.
+  ttl: Duration.toMilliseconds({ days: 7 }),
+
+  // How often the cleanup task should run to purge expired cached files, in milliseconds.
+  cleanupInterval: Duration.toMilliseconds({ hours: 4 }),
+};
+
+// create an instance
+const imageCache = new FileCache(options);
+
+const imageFilePath = await imageCache({
+  url: "https://example.com/some/file/path.jpg",
+});
+```
+
+## Cleanup
+
+`FileCache` instances are intended to be instantiated as singletons, persisting throughout the lifecycle of your app. If you need to deallocate an instance, be sure to call the `destroy()` method to prevent a memory leak.
+
+## Tests
+
+Run the tests using:
+
+```bash
+yarn test
+```
+
+## License
+
+[MIT](LICENSE)

package/__tests__/file-cache.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { FileCache } from "../src";
+import { Duration } from "@chriscdn/duration";
+import { promises as fs } from "fs";
+import temp from "temp";
+import { pathExists } from "path-exists";
+
+const pause = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const testPDFFile = "./__tests__/pdfs/lorem.pdf";
+
+describe("Cache Expiration", async () => {
+  const cache = new FileCache({
+    cachePath: await temp.mkdir("file-cache-test"),
+    cb: async (filePath, { a }: { a: number }) => {
+      await fs.copyFile(
+        testPDFFile,
+        filePath,
+      );
+    },
+    ext: "pdf",
+    ttl: Duration.toMilliseconds({ seconds: 1 }),
+    cleanupInterval: Duration.toMilliseconds({ seconds: 2 }),
+  });
+
+  it("sync", async () => {
+    //
+    const filePath3 = await cache.getFile({ a: 3 });
+
+    // test if filePath exists
+    expect(await pathExists(filePath3)).toBe(true);
+
+    // wait a second
+    await pause(Duration.toMilliseconds({ seconds: 1 }));
+
+    // should still exist
+    expect(await pathExists(filePath3)).toBe(true);
+
+    // wait 2 seconds
+    await pause(Duration.toMilliseconds({ seconds: 2 }));
+
+    // should not longer exist due to cleanup
+    expect(await pathExists(filePath3)).toBe(false);
+  });
+});

package/esbuild.mjs

@@ -0,0 +1,19 @@
+import { build } from "esbuild";
+
+import pkg from "./package.json" with { type: "json" };
+
+const external = [
+  ...Object.keys(pkg.dependencies || {}),
+  ...Object.keys(pkg.devDependencies || {}),
+];
+
+build({
+  entryPoints: ["./src/index.ts"],
+  bundle: true,
+  platform: "node",
+  format: "esm", // or 'esm' if you prefer
+  outfile: "./lib/index.js",
+  external,
+  minify: false,
+  sourcemap: true,
+}).catch(() => process.exit(1));

package/lib/index.d.ts

@@ -0,0 +1,67 @@
+type DirectoryPath = string;
+type FilePath = string;
+type Milliseconds = number;
+export type FileCacheOptions<T extends Record<string, any>> = {
+    cachePath: DirectoryPath;
+    cb: (filePath: FilePath, context: T, cache: FileCache<T>) => Promise<void>;
+    ext: string;
+    cleanupInterval?: Milliseconds;
+    ttl: Milliseconds;
+    resolveFileName?: (args: T) => FilePath;
+};
+declare class FileCache<T extends Record<string, any>> {
+    private _cachePath;
+    private _resolveFileName;
+    private _cb;
+    private _ext;
+    private _ttl;
+    private _cleanupInterval;
+    private _intervalId;
+    private _semaphore;
+    private _cleanupSemaphore;
+    constructor({ cachePath, resolveFileName, cb, ext, ttl, cleanupInterval }: FileCacheOptions<T>);
+    /**
+     * Runs a cleanup pass to remove files older than 1 day from the cache.
+     * This is called periodically, but can be triggered manually.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Retrieves a cached file for the given arguments.
+     * If the file doesn't exist, it is generated by the callback and stored.
+     *
+     * Concurrency-safe, ensuring no conflicts when multiple requests are made
+     * for the same file.
+     *
+     * @param args The arguments used to determine the file's identity and generation
+     * @returns The path to the cached or newly created file
+     */
+    getFile(args: T): Promise<FilePath>;
+    has(args: T): Promise<boolean>;
+    /**
+     * Deletes a file from the cache if it exists.
+     *
+     * @param args The arguments used to determine the file's identity
+     * @returns True if the file was deleted, false if it didn't exist
+     */
+    expire(args: T): Promise<boolean>;
+    /**
+     * Stops the background cleanup process, but does not delete any cached files.
+     */
+    destroy(): void;
+    /**
+     * Resolves the filename for the cache based on the provided arguments.
+     *
+     * Uses the provided `resolveFileName` function if available, or falls back to
+     * generating a hash from the arguments to create a unique file name.
+     */
+    private resolveFileName;
+    /**
+     * Resolves the full file path for the cached file based on the provided arguments.
+     *
+     * @param args The arguments used to resolve the file path
+     * @returns The full path to the cached file
+     */
+    resolveFilePath(args: T): FilePath;
+    resolveCreateFilePath(args: T): Promise<FilePath>;
+}
+export { FileCache, type FilePath };

package/lib/index.js

@@ -0,0 +1,152 @@
+import path from "path";
+import { promises as fs } from "fs";
+import { pathExists } from "path-exists";
+import sha1 from "sha1";
+import Semaphore from "@chriscdn/promise-semaphore";
+import touch from "touch";
+import { findNuke } from "@chriscdn/find-nuke";
+import { Duration } from "@chriscdn/duration";
+import { rimraf } from "rimraf";
+class FileCache {
+    _cachePath;
+    _resolveFileName;
+    _cb;
+    _ext;
+    _ttl;
+    _cleanupInterval;
+    _intervalId = null;
+    _semaphore = new Semaphore();
+    _cleanupSemaphore = new Semaphore();
+    constructor({ cachePath, resolveFileName, cb, ext, ttl, cleanupInterval }) {
+        this._cachePath = cachePath;
+        this._resolveFileName = resolveFileName;
+        this._cb = cb;
+        this._ext = ext;
+        this._ttl = ttl;
+        this._cleanupInterval = cleanupInterval ??
+            Duration.toMilliseconds({ days: 1 });
+        (async () => {
+            if (!(await pathExists(cachePath))) {
+                throw new Error("💥 FileCache error: cachePath does not exist.");
+                // process.exit(1); // or throw new Error() if you want to let it bubble
+            }
+        })();
+        // fire and forget
+        // fire and forget
+        this.cleanup();
+        this._intervalId = setInterval(this.cleanup.bind(this), this._cleanupInterval);
+    }
+    /**
+     * Runs a cleanup pass to remove files older than 1 day from the cache.
+     * This is called periodically, but can be triggered manually.
+     */
+    async cleanup() {
+        try {
+            await this._cleanupSemaphore.acquire();
+            await findNuke(this._cachePath, {
+                olderThan: this._ttl,
+                verbose: true,
+                deleteEmptyDirectories: true,
+            });
+        }
+        finally {
+            this._cleanupSemaphore.release();
+        }
+    }
+    /**
+     * Retrieves a cached file for the given arguments.
+     * If the file doesn't exist, it is generated by the callback and stored.
+     *
+     * Concurrency-safe, ensuring no conflicts when multiple requests are made
+     * for the same file.
+     *
+     * @param args The arguments used to determine the file's identity and generation
+     * @returns The path to the cached or newly created file
+     */
+    async getFile(args) {
+        const filePath = this.resolveFilePath(args);
+        try {
+            await Promise.all([
+                this._semaphore.acquire(filePath),
+                this._cleanupSemaphore.wait(),
+            ]);
+            if (await pathExists(filePath)) {
+                // fire and forget
+                touch(filePath);
+            }
+            else {
+                await fs.mkdir(path.dirname(filePath), { recursive: true });
+                await this._cb(filePath, args, this);
+            }
+        }
+        finally {
+            this._semaphore.release(filePath);
+        }
+        return filePath;
+    }
+    async has(args) {
+        const filePath = this.resolveFilePath(args);
+        return await pathExists(filePath);
+    }
+    /**
+     * Deletes a file from the cache if it exists.
+     *
+     * @param args The arguments used to determine the file's identity
+     * @returns True if the file was deleted, false if it didn't exist
+     */
+    async expire(args) {
+        const filePath = this.resolveFilePath(args);
+        if (await pathExists(filePath)) {
+            await rimraf(filePath);
+            return true;
+        }
+        else {
+            return false;
+        }
+    }
+    /**
+     * Stops the background cleanup process, but does not delete any cached files.
+     */
+    destroy() {
+        if (this._intervalId) {
+            clearInterval(this._intervalId);
+            this._intervalId = null;
+        }
+    }
+    /**
+     * Resolves the filename for the cache based on the provided arguments.
+     *
+     * Uses the provided `resolveFileName` function if available, or falls back to
+     * generating a hash from the arguments to create a unique file name.
+     */
+    resolveFileName(args) {
+        const baseName = sha1(JSON.stringify(args, Object.keys(args).sort()));
+        return path.format({
+            // dir: path.dirname(filePath),
+            name: baseName,
+            ext: this._ext,
+        });
+        // return this._resolveFileName
+        //   ? this._resolveFileName(args)
+        //   : `${sha1(JSON.stringify(args, Object.keys(args).sort()))}${this._ext}`;
+    }
+    /**
+     * Resolves the full file path for the cached file based on the provided arguments.
+     *
+     * @param args The arguments used to resolve the file path
+     * @returns The full path to the cached file
+     */
+    resolveFilePath(args) {
+        const fileName = this.resolveFileName(args);
+        const filePath = path.resolve(this._cachePath, fileName[0], fileName[1], fileName[2], 
+        // fileName[3],
+        fileName);
+        return filePath;
+    }
+    async resolveCreateFilePath(args) {
+        const filePath = this.resolveFilePath(args);
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        return filePath;
+    }
+}
+export { FileCache };

package/lib/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["import path from \"path\";\nimport { promises as fs } from \"fs\";\nimport { pathExists } from \"path-exists\";\nimport sha1 from \"sha1\";\nimport Semaphore from \"@chriscdn/promise-semaphore\";\nimport touch from \"touch\";\nimport { findNuke } from \"@chriscdn/find-nuke\";\nimport { Duration } from \"@chriscdn/duration\";\nimport { rimraf } from \"rimraf\";\n\ntype DirectoryPath = string;\ntype FilePath = string;\ntype Milliseconds = number;\n\nexport type FileCacheOptions<T extends Record<string, any>> = {\n  cachePath: DirectoryPath;\n  cb: (filePath: FilePath, context: T, cache: FileCache<T>) => Promise<void>;\n  ext: string;\n  cleanupInterval?: Milliseconds;\n  ttl: Milliseconds;\n  resolveFileName?: (args: T) => FilePath;\n};\n\nclass FileCache<T extends Record<string, any>> {\n  private _cachePath: FileCacheOptions<T>[\"cachePath\"];\n  private _resolveFileName: FileCacheOptions<T>[\"resolveFileName\"];\n  private _cb: FileCacheOptions<T>[\"cb\"];\n  private _ext: FileCacheOptions<T>[\"ext\"];\n  private _ttl: FileCacheOptions<T>[\"ttl\"];\n  private _cleanupInterval: FileCacheOptions<T>[\"cleanupInterval\"];\n\n  private _intervalId: ReturnType<typeof setInterval> | null = null;\n\n  private _semaphore: Semaphore = new Semaphore();\n  private _cleanupSemaphore: Semaphore = new Semaphore();\n\n  constructor(\n    { cachePath, resolveFileName, cb, ext, ttl, cleanupInterval }:\n      FileCacheOptions<T>,\n  ) {\n    this._cachePath = cachePath;\n    this._resolveFileName = resolveFileName;\n    this._cb = cb;\n    this._ext = ext;\n    this._ttl = ttl;\n    this._cleanupInterval = cleanupInterval ??\n      Duration.toMilliseconds({ days: 1 });\n\n    (async () => {\n      if (!(await pathExists(cachePath))) {\n        throw new Error(\"\uD83D\uDCA5 FileCache error: cachePath does not exist.\");\n        // process.exit(1); // or throw new Error() if you want to let it bubble\n      }\n    })();\n\n    // fire and forget\n    // fire and forget\n    this.cleanup();\n\n    this._intervalId = setInterval(\n      this.cleanup.bind(this),\n      this._cleanupInterval,\n    );\n  }\n\n  /**\n   * Runs a cleanup pass to remove files older than 1 day from the cache.\n   * This is called periodically, but can be triggered manually.\n   */\n  async cleanup() {\n    try {\n      await this._cleanupSemaphore.acquire();\n      await findNuke(this._cachePath, {\n        olderThan: this._ttl,\n        verbose: true,\n        deleteEmptyDirectories: true,\n      });\n    } finally {\n      this._cleanupSemaphore.release();\n    }\n  }\n\n  /**\n   * Retrieves a cached file for the given arguments.\n   * If the file doesn't exist, it is generated by the callback and stored.\n   *\n   * Concurrency-safe, ensuring no conflicts when multiple requests are made\n   * for the same file.\n   *\n   * @param args The arguments used to determine the file's identity and generation\n   * @returns The path to the cached or newly created file\n   */\n  async getFile(args: T): Promise<FilePath> {\n    const filePath = this.resolveFilePath(args);\n\n    try {\n      await Promise.all([\n        this._semaphore.acquire(filePath),\n        this._cleanupSemaphore.wait(),\n      ]);\n\n      if (await pathExists(filePath)) {\n        // fire and forget\n        touch(filePath);\n      } else {\n        await fs.mkdir(path.dirname(filePath), { recursive: true });\n        await this._cb(filePath, args, this);\n      }\n    } finally {\n      this._semaphore.release(filePath);\n    }\n\n    return filePath;\n  }\n\n  async has(args: T): Promise<boolean> {\n    const filePath = this.resolveFilePath(args);\n    return await pathExists(filePath);\n  }\n\n  /**\n   * Deletes a file from the cache if it exists.\n   *\n   * @param args The arguments used to determine the file's identity\n   * @returns True if the file was deleted, false if it didn't exist\n   */\n  async expire(args: T): Promise<boolean> {\n    const filePath = this.resolveFilePath(args);\n\n    if (await pathExists(filePath)) {\n      await rimraf(filePath);\n      return true;\n    } else {\n      return false;\n    }\n  }\n\n  /**\n   * Stops the background cleanup process, but does not delete any cached files.\n   */\n  destroy() {\n    if (this._intervalId) {\n      clearInterval(this._intervalId);\n      this._intervalId = null;\n    }\n  }\n\n  /**\n   * Resolves the filename for the cache based on the provided arguments.\n   *\n   * Uses the provided `resolveFileName` function if available, or falls back to\n   * generating a hash from the arguments to create a unique file name.\n   */\n  private resolveFileName(args: T): string {\n    const baseName = sha1(JSON.stringify(args, Object.keys(args).sort()));\n\n    return path.format({\n      // dir: path.dirname(filePath),\n      name: baseName,\n      ext: this._ext,\n    });\n\n    // return this._resolveFileName\n    //   ? this._resolveFileName(args)\n    //   : `${sha1(JSON.stringify(args, Object.keys(args).sort()))}${this._ext}`;\n  }\n\n  /**\n   * Resolves the full file path for the cached file based on the provided arguments.\n   *\n   * @param args The arguments used to resolve the file path\n   * @returns The full path to the cached file\n   */\n  resolveFilePath(args: T): FilePath {\n    const fileName = this.resolveFileName(args);\n\n    const filePath = path.resolve(\n      this._cachePath,\n      fileName[0],\n      fileName[1],\n      fileName[2],\n      // fileName[3],\n      fileName,\n    );\n\n    return filePath;\n  }\n\n  async resolveCreateFilePath(args: T): Promise<FilePath> {\n    const filePath = this.resolveFilePath(args);\n\n    await fs.mkdir(path.dirname(filePath), { recursive: true });\n\n    return filePath;\n  }\n}\n\nexport { FileCache, type FilePath };\n"],
+  "mappings": ";AAAA,OAAO,UAAU;AACjB,SAAS,YAAY,UAAU;AAC/B,SAAS,kBAAkB;AAC3B,OAAO,UAAU;AACjB,OAAO,eAAe;AACtB,OAAO,WAAW;AAClB,SAAS,gBAAgB;AACzB,SAAS,gBAAgB;AACzB,SAAS,cAAc;AAevB,IAAM,YAAN,MAA+C;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEA,cAAqD;AAAA,EAErD,aAAwB,IAAI,UAAU;AAAA,EACtC,oBAA+B,IAAI,UAAU;AAAA,EAErD,YACE,EAAE,WAAW,iBAAiB,IAAI,KAAK,KAAK,gBAAgB,GAE5D;AACA,SAAK,aAAa;AAClB,SAAK,mBAAmB;AACxB,SAAK,MAAM;AACX,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,mBAAmB,mBACtB,SAAS,eAAe,EAAE,MAAM,EAAE,CAAC;AAErC,KAAC,YAAY;AACX,UAAI,CAAE,MAAM,WAAW,SAAS,GAAI;AAClC,cAAM,IAAI,MAAM,sDAA+C;AAAA,MAEjE;AAAA,IACF,GAAG;AAIH,SAAK,QAAQ;AAEb,SAAK,cAAc;AAAA,MACjB,KAAK,QAAQ,KAAK,IAAI;AAAA,MACtB,KAAK;AAAA,IACP;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,UAAU;AACd,QAAI;AACF,YAAM,KAAK,kBAAkB,QAAQ;AACrC,YAAM,SAAS,KAAK,YAAY;AAAA,QAC9B,WAAW,KAAK;AAAA,QAChB,SAAS;AAAA,QACT,wBAAwB;AAAA,MAC1B,CAAC;AAAA,IACH,UAAE;AACA,WAAK,kBAAkB,QAAQ;AAAA,IACjC;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,MAAM,QAAQ,MAA4B;AACxC,UAAM,WAAW,KAAK,gBAAgB,IAAI;AAE1C,QAAI;AACF,YAAM,QAAQ,IAAI;AAAA,QAChB,KAAK,WAAW,QAAQ,QAAQ;AAAA,QAChC,KAAK,kBAAkB,KAAK;AAAA,MAC9B,CAAC;AAED,UAAI,MAAM,WAAW,QAAQ,GAAG;AAE9B,cAAM,QAAQ;AAAA,MAChB,OAAO;AACL,cAAM,GAAG,MAAM,KAAK,QAAQ,QAAQ,GAAG,EAAE,WAAW,KAAK,CAAC;AAC1D,cAAM,KAAK,IAAI,UAAU,MAAM,IAAI;AAAA,MACrC;AAAA,IACF,UAAE;AACA,WAAK,WAAW,QAAQ,QAAQ;AAAA,IAClC;AAEA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,IAAI,MAA2B;AACnC,UAAM,WAAW,KAAK,gBAAgB,IAAI;AAC1C,WAAO,MAAM,WAAW,QAAQ;AAAA,EAClC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,OAAO,MAA2B;AACtC,UAAM,WAAW,KAAK,gBAAgB,IAAI;AAE1C,QAAI,MAAM,WAAW,QAAQ,GAAG;AAC9B,YAAM,OAAO,QAAQ;AACrB,aAAO;AAAA,IACT,OAAO;AACL,aAAO;AAAA,IACT;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,UAAU;AACR,QAAI,KAAK,aAAa;AACpB,oBAAc,KAAK,WAAW;AAC9B,WAAK,cAAc;AAAA,IACrB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQQ,gBAAgB,MAAiB;AACvC,UAAM,WAAW,KAAK,KAAK,UAAU,MAAM,OAAO,KAAK,IAAI,EAAE,KAAK,CAAC,CAAC;AAEpE,WAAO,KAAK,OAAO;AAAA;AAAA,MAEjB,MAAM;AAAA,MACN,KAAK,KAAK;AAAA,IACZ,CAAC;AAAA,EAKH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,gBAAgB,MAAmB;AACjC,UAAM,WAAW,KAAK,gBAAgB,IAAI;AAE1C,UAAM,WAAW,KAAK;AAAA,MACpB,KAAK;AAAA,MACL,SAAS,CAAC;AAAA,MACV,SAAS,CAAC;AAAA,MACV,SAAS,CAAC;AAAA;AAAA,MAEV;AAAA,IACF;AAEA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,sBAAsB,MAA4B;AACtD,UAAM,WAAW,KAAK,gBAAgB,IAAI;AAE1C,UAAM,GAAG,MAAM,KAAK,QAAQ,QAAQ,GAAG,EAAE,WAAW,KAAK,CAAC;AAE1D,WAAO;AAAA,EACT;AACF;",
+  "names": []
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@chriscdn/file-cache",
+  "version": "0.0.1",
+  "description": "File cache ",
+  "repository": "https://github.com/chriscdn/file-cache",
+  "author": "Christopher Meyer <chris@schwiiz.org>",
+  "license": "MIT",
+  "type": "module",
+  "source": "./src/index.ts",
+  "module": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    "types": "./lib/index.d.ts",
+    "default": "./lib/index.js"
+  },
+  "scripts": {
+    "build": "rimraf ./lib/ && node ./esbuild.mjs && tsc --declaration",
+    "dev": "microbundle watch",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@chriscdn/duration": "^1.0.3",
+    "@chriscdn/find-nuke": "^0.0.4",
+    "@chriscdn/promise-semaphore": "^2.0.11",
+    "path-exists": "^5.0.0",
+    "rimraf": "^6.0.1",
+    "sha1": "^1.1.1",
+    "temp": "^0.9.4",
+    "touch": "^3.1.1"
+  },
+  "devDependencies": {
+    "@types/sha1": "^1.1.5",
+    "@types/touch": "^3.1.5",
+    "esbuild": "^0.25.3",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,198 @@
+import path from "path";
+import { promises as fs } from "fs";
+import { pathExists } from "path-exists";
+import sha1 from "sha1";
+import Semaphore from "@chriscdn/promise-semaphore";
+import touch from "touch";
+import { findNuke } from "@chriscdn/find-nuke";
+import { Duration } from "@chriscdn/duration";
+import { rimraf } from "rimraf";
+
+type DirectoryPath = string;
+type FilePath = string;
+type Milliseconds = number;
+
+export type FileCacheOptions<T extends Record<string, any>> = {
+  cachePath: DirectoryPath;
+  cb: (filePath: FilePath, context: T, cache: FileCache<T>) => Promise<void>;
+  ext: string;
+  cleanupInterval?: Milliseconds;
+  ttl: Milliseconds;
+  resolveFileName?: (args: T) => FilePath;
+};
+
+class FileCache<T extends Record<string, any>> {
+  private _cachePath: FileCacheOptions<T>["cachePath"];
+  private _resolveFileName: FileCacheOptions<T>["resolveFileName"];
+  private _cb: FileCacheOptions<T>["cb"];
+  private _ext: FileCacheOptions<T>["ext"];
+  private _ttl: FileCacheOptions<T>["ttl"];
+  private _cleanupInterval: FileCacheOptions<T>["cleanupInterval"];
+
+  private _intervalId: ReturnType<typeof setInterval> | null = null;
+
+  private _semaphore: Semaphore = new Semaphore();
+  private _cleanupSemaphore: Semaphore = new Semaphore();
+
+  constructor(
+    { cachePath, resolveFileName, cb, ext, ttl, cleanupInterval }:
+      FileCacheOptions<T>,
+  ) {
+    this._cachePath = cachePath;
+    this._resolveFileName = resolveFileName;
+    this._cb = cb;
+    this._ext = ext;
+    this._ttl = ttl;
+    this._cleanupInterval = cleanupInterval ??
+      Duration.toMilliseconds({ days: 1 });
+
+    (async () => {
+      if (!(await pathExists(cachePath))) {
+        throw new Error("💥 FileCache error: cachePath does not exist.");
+        // process.exit(1); // or throw new Error() if you want to let it bubble
+      }
+    })();
+
+    // fire and forget
+    // fire and forget
+    this.cleanup();
+
+    this._intervalId = setInterval(
+      this.cleanup.bind(this),
+      this._cleanupInterval,
+    );
+  }
+
+  /**
+   * Runs a cleanup pass to remove files older than 1 day from the cache.
+   * This is called periodically, but can be triggered manually.
+   */
+  async cleanup() {
+    try {
+      await this._cleanupSemaphore.acquire();
+      await findNuke(this._cachePath, {
+        olderThan: this._ttl,
+        verbose: true,
+        deleteEmptyDirectories: true,
+      });
+    } finally {
+      this._cleanupSemaphore.release();
+    }
+  }
+
+  /**
+   * Retrieves a cached file for the given arguments.
+   * If the file doesn't exist, it is generated by the callback and stored.
+   *
+   * Concurrency-safe, ensuring no conflicts when multiple requests are made
+   * for the same file.
+   *
+   * @param args The arguments used to determine the file's identity and generation
+   * @returns The path to the cached or newly created file
+   */
+  async getFile(args: T): Promise<FilePath> {
+    const filePath = this.resolveFilePath(args);
+
+    try {
+      await Promise.all([
+        this._semaphore.acquire(filePath),
+        this._cleanupSemaphore.wait(),
+      ]);
+
+      if (await pathExists(filePath)) {
+        // fire and forget
+        touch(filePath);
+      } else {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await this._cb(filePath, args, this);
+      }
+    } finally {
+      this._semaphore.release(filePath);
+    }
+
+    return filePath;
+  }
+
+  async has(args: T): Promise<boolean> {
+    const filePath = this.resolveFilePath(args);
+    return await pathExists(filePath);
+  }
+
+  /**
+   * Deletes a file from the cache if it exists.
+   *
+   * @param args The arguments used to determine the file's identity
+   * @returns True if the file was deleted, false if it didn't exist
+   */
+  async expire(args: T): Promise<boolean> {
+    const filePath = this.resolveFilePath(args);
+
+    if (await pathExists(filePath)) {
+      await rimraf(filePath);
+      return true;
+    } else {
+      return false;
+    }
+  }
+
+  /**
+   * Stops the background cleanup process, but does not delete any cached files.
+   */
+  destroy() {
+    if (this._intervalId) {
+      clearInterval(this._intervalId);
+      this._intervalId = null;
+    }
+  }
+
+  /**
+   * Resolves the filename for the cache based on the provided arguments.
+   *
+   * Uses the provided `resolveFileName` function if available, or falls back to
+   * generating a hash from the arguments to create a unique file name.
+   */
+  private resolveFileName(args: T): string {
+    const baseName = sha1(JSON.stringify(args, Object.keys(args).sort()));
+
+    return path.format({
+      // dir: path.dirname(filePath),
+      name: baseName,
+      ext: this._ext,
+    });
+
+    // return this._resolveFileName
+    //   ? this._resolveFileName(args)
+    //   : `${sha1(JSON.stringify(args, Object.keys(args).sort()))}${this._ext}`;
+  }
+
+  /**
+   * Resolves the full file path for the cached file based on the provided arguments.
+   *
+   * @param args The arguments used to resolve the file path
+   * @returns The full path to the cached file
+   */
+  resolveFilePath(args: T): FilePath {
+    const fileName = this.resolveFileName(args);
+
+    const filePath = path.resolve(
+      this._cachePath,
+      fileName[0],
+      fileName[1],
+      fileName[2],
+      // fileName[3],
+      fileName,
+    );
+
+    return filePath;
+  }
+
+  async resolveCreateFilePath(args: T): Promise<FilePath> {
+    const filePath = this.resolveFilePath(args);
+
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+
+    return filePath;
+  }
+}
+
+export { FileCache, type FilePath };

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext"],
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "strict": true,
+    "allowSyntheticDefaultImports": true,
+    "outDir": "./lib",
+    "declaration": true, // Generate declaration files
+    "declarationDir": "./lib",
+    "skipLibCheck": true
+  },
+  "include": ["./src/**/*"]
+}