@kisaragi-hiu/cached-fetch 0.0.1

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2025 Kisaragi Hiu
+
+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,50 @@
+# @kisaragi-hiu/cached-fetch
+
+A cacheing function designed for cacheing fetch GET responses on disk in a command line program.
+
+I keep rewriting this logic in multiple projects, so I'm making it a package.
+
+## Usage
+
+```typescript
+import { cached } from "@kisaragi-hiu/cached-fetch";
+
+const text = await cached(
+  "myCacheKey",
+  () => fetch("https://example.com")
+)
+```
+
+This persists the text response in `os.tmpdir` and should stay around until the next reboot.
+
+Arguments:
+
+```typescript
+/**
+ * The key of the value.
+ * Subsequent calls with the same key will return the cached value.
+ */
+key: string,
+/**
+ * A fetcher function, called when the value isn't cached.
+ *
+ * Should return a promise, which resolves to an object whose text key is a
+ * Promise<string> --- usually a Response, but the ProcessPromise from the
+ * zx library are also supported.
+ */
+fetcher: () => Promise<{ text: () => Promise<string> }>
+```
+
+## Bonus usage
+
+This also works:
+
+```typescript
+import { $ } from "zx";
+import { cached } from "@kisaragi-hiu/cached-fetch";
+
+const text = await cached(
+  "myCacheKey",
+  () => $`sleep 1 && echo "demo for a slow process"`
+)
+```

package/index.ts

@@ -0,0 +1,32 @@
+// -*- lsp-disabled-clients: (ts-ls); -*-
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+
+/**
+ * A cache designed to cache some text.
+ */
+export async function cached(
+  /**
+   * The key of the value.
+   * Subsequent calls with the same key will return the cached value.
+   */
+  key: string,
+  /**
+   * A fetcher function, called when the value isn't cached.
+   *
+   * Should return a Promise<{ text: () => Promise<string> }>. This is usually a
+   * Response, but the ProcessPromise from the zx library also fits this signature.
+   */
+  fetcher: () => Promise<{ text: () => Promise<string> }>
+) {
+  const cacheFile = join(tmpdir(), key);
+  const cacheHit = existsSync(cacheFile);
+  const text = cacheHit
+    ? readFileSync(cacheFile, { encoding: "utf-8" })
+    : await (await fetcher()).text();
+  if (!cacheHit) {
+    mkdirSync(dirname(cacheFile), { recursive: true });
+    writeFileSync(cacheFile, text, { encoding: "utf-8" });
+  }
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@kisaragi-hiu/cached-fetch",
+  "version": "0.0.1",
+  "description": "A cache in OS tmpdir useful for fetch()",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kisaragi-hiu/cached-fetch.git"
+  },
+  "funding": {
+    "type": "buymeacoffee",
+    "url": "https://www.buymeacoffee.com/kisaragihiu"
+  },
+  "homepage": "https://github.com/kisaragi-hiu/cached-fetch",
+  "author": "Kisaragi Hiu <mail@kisaragi-hiu.com>",
+  "license": "MIT",
+  "files": ["index.ts"]
+}