@webjsdev/server 0.8.10 → 0.8.12

package/index.js

@@ -2,6 +2,7 @@ export { startServer, createRequestHandler } from './src/dev.js';
 export { assertNodeVersion, checkNodeVersion, requiredNodeMajor, parseMajor, parseRequiredMajor } from './src/node-version.js';
 export { validateEnv, formatEnvErrors, loadEnvSchema, applyEnvValidation } from './src/env-schema.js';
 export { buildRouteTable, matchPage, matchApi } from './src/router.js';
+export { generateRouteTypes } from './src/route-types.js';
 export { ssrPage, ssrNotFound } from './src/ssr.js';
 export { handleApi } from './src/api.js';
 export {
@@ -34,12 +35,14 @@ export {
 } from './src/vendor.js';
 export { buildModuleGraph, transitiveDeps } from './src/module-graph.js';
 export { scanComponents, primeComponentRegistry, extractComponents, findOrphanComponents } from './src/component-scanner.js';
-export { headers, cookies, getRequest, withRequest, cspNonce } from './src/context.js';
+export { headers, cookies, getRequest, withRequest, cspNonce, requestId } from './src/context.js';
 export { defaultLogger } from './src/logger.js';
 export { rateLimit, parseWindow, clientIp, stampRemoteIp } from './src/rate-limit.js';
 export { cors, resolveOrigin, applyCorsHeaders } from './src/cors.js';
 export { memoryStore, redisStore, getStore, setStore } from './src/cache.js';
 export { cache } from './src/cache-fn.js';
+export { revalidateTag, revalidateTags } from './src/cache-tags.js';
+export { revalidatePath, revalidateAll } from './src/html-cache.js';
 export { Session, session, cookieSessionStorage, storeSessionStorage, cookieSession, storeSession, getSession } from './src/session.js';
 export { broadcast } from './src/broadcast.js';
 export { json, readBody } from './src/json.js';

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.10",
+  "version": "0.8.12",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",
   "exports": {
     ".": "./index.js",
-    "./check": "./src/check.js"
+    "./check": "./src/check.js",
+    "./webjs-config.schema.json": "./webjs-config.schema.json"
   },
   "files": [
     "index.js",
     "src",
+    "webjs-config.schema.json",
     "README.md"
   ],
   "dependencies": {

package/src/actions.js

@@ -9,6 +9,8 @@ import { getSerializer } from './serializer.js';
 import { resolveOrigin } from './cors.js';
 import { readTextBounded, payloadTooLarge, DEFAULT_MAX_BODY_BYTES } from './body-limit.js';
 import { getBodyLimits } from './context.js';
+import { basePath } from './importmap.js';
+import { withBasePath } from './base-path.js';
 
 /**
  * The JSON / RPC body cap in effect for the current request: the per-request
@@ -257,6 +259,12 @@ export async function serveActionStub(idx, absFile) {
   if (typeof mod.default === 'function' && !fnNames.includes('default')) {
     fnNames.push('default');
   }
+  // The RPC endpoint is a framework-emitted same-origin URL, so it must
+  // carry the basePath prefix under a sub-path deploy (#256), exactly like
+  // the importmap targets and the boot module specifiers. Without this the
+  // stub would POST to a bare /__webjs/action/... that the ingress strip
+  // 404s, breaking every server action when webjs.basePath is set.
+  const actionUrl = withBasePath(`/__webjs/action/${hash}/`, basePath());
   const body = `// webjs: generated server-action stub for ${relative(idx.appDir, absFile)}\n` +
     `import { stringify as __wjStringify, parse as __wjParse } from '@webjsdev/core';\n` +
     `function __csrf() {\n` +
@@ -265,7 +273,7 @@ export async function serveActionStub(idx, absFile) {
     `}\n` +
     `async function __rpc(fn, args) {\n` +
     `  const body = await __wjStringify(args);\n` +
-    `  const res = await fetch(${JSON.stringify(`/__webjs/action/${hash}/`)} + fn, {\n` +
+    `  const res = await fetch(${JSON.stringify(actionUrl)} + fn, {\n` +
     `    method: 'POST',\n` +
     `    headers: {\n` +
     `      'content-type': ${JSON.stringify(RPC_CONTENT_TYPE)},\n` +
@@ -301,8 +309,12 @@ export async function serveActionStub(idx, absFile) {
  * @param {string} hash
  * @param {string} fnName
  * @param {Request} req
+ * @param {(error: unknown) => void} [onError] best-effort sink (issue #239)
+ *   invoked when the action throws unexpectedly, BEFORE the sanitized 500 is
+ *   returned, so an APM integration sees the original error. The caller wraps
+ *   it so a throwing sink can never affect the response.
  */
-export async function invokeAction(idx, hash, fnName, req) {
+export async function invokeAction(idx, hash, fnName, req, onError) {
   if (!verifyCsrf(req)) {
     return rpcResponse({ error: 'CSRF validation failed' }, { status: 403 });
   }
@@ -327,6 +339,7 @@ export async function invokeAction(idx, hash, fnName, req) {
     const result = await fn(...args);
     return rpcResponse(result ?? null);
   } catch (e) {
+    if (typeof onError === 'function') onError(e);
     return actionErrorResponse(e, idx.dev);
   }
 }
@@ -432,8 +445,12 @@ function matchOrigin(configured, origin) {
  * @param {ExposedRoute} route
  * @param {Record<string,string>} params
  * @param {Request} req
+ * @param {(error: unknown) => void} [onError] best-effort sink (issue #239)
+ *   invoked when the exposed REST handler throws unexpectedly, BEFORE the
+ *   sanitized 500 is returned, so an APM integration sees the original error.
+ *   The caller wraps it so a throwing sink can never affect the response.
  */
-export async function invokeExposedAction(idx, route, params, req) {
+export async function invokeExposedAction(idx, route, params, req, onError) {
   const url = new URL(req.url);
   const query = Object.fromEntries(url.searchParams.entries());
   let body = {};
@@ -473,6 +490,7 @@ export async function invokeExposedAction(idx, route, params, req) {
     if (result instanceof Response) return result;
     return Response.json(result ?? null);
   } catch (e) {
+    if (typeof onError === 'function') onError(e);
     return actionErrorResponse(e, idx.dev);
   }
 }

package/src/auth.js

@@ -8,7 +8,7 @@
  */
 
 import { getStore } from './cache.js';
-import { getRequest, getBodyLimits } from './context.js';
+import { getRequest, getBodyLimits, markDynamicAccess } from './context.js';
 import { readTextBounded, readFormDataBounded, payloadTooLarge, DEFAULT_MAX_BODY_BYTES } from './body-limit.js';
 
 const enc = new TextEncoder();
@@ -220,6 +220,13 @@ export function createAuth(config) {
   // -- Session read/write ---------------------------------------------------
 
   async function readSession(req) {
+    // Reading the auth session is per-user (the body branches on the logged-in
+    // user), so mark the request dynamic so the server HTML cache excludes the
+    // page even when it wrongly set `revalidate`, mirroring getSession() /
+    // cookies() / headers(). This closes the auth-path leak (#241): `auth()`
+    // reaches here, reads the auth cookie raw, and would otherwise leave the
+    // page cacheable so a logged-in body could be served to the next visitor.
+    markDynamicAccess();
     const cookies = parseCookies(req.headers.get('cookie') || '');
     const raw = cookies[AUTH_COOKIE];
     if (!raw) return null;

package/src/base-path.js

@@ -0,0 +1,149 @@
+/**
+ * Sub-path deployment support: `webjs.basePath` (issue #256).
+ *
+ * An app deployed under a sub-path (example.com/app/) behind a proxy that
+ * does NOT strip the prefix is broken without this: every
+ * framework-emitted absolute URL (the importmap targets, the modulepreload
+ * hints, the boot script's `/__webjs/core/*` specifiers and per-route
+ * module URLs, the dev reload `src`) assumes the app sits at the origin
+ * root, so they point at `/__webjs/core/*` instead of
+ * `/app/__webjs/core/*`, module resolution 404s, and the page never
+ * hydrates. `createRequestHandler` explicitly targets embedding, where a
+ * sub-path mount is the norm.
+ *
+ * The model is strip-at-ingress + prefix-on-emit, two seams only:
+ *
+ *   1. STRIP AT INGRESS. At the very start of request handling, when the
+ *      request pathname starts with the basePath, strip it so all
+ *      downstream logic (route matching, the `/__webjs/*` checks, the
+ *      source-file gate, redirects, trailing-slash) sees a ROOT-relative
+ *      path and works UNCHANGED. This single strip is why the rest of the
+ *      framework needs no per-site changes. `stripBasePath` does the path
+ *      computation; `dev.js` rewrites the Request URL with it.
+ *
+ *   2. PREFIX ON EMIT. Every framework-emitted same-origin absolute URL
+ *      (begins with a single `/`) gets the basePath prepended via the one
+ *      `withBasePath` helper. Applied to the importmap targets
+ *      (`importmap.js`), the modulepreload hrefs + boot module specifiers +
+ *      dev reload `src` (`ssr.js`). A cross-origin URL (a `https://` CDN
+ *      vendor target) is absolute and is left untouched.
+ *
+ * Empty basePath (the default) makes both seams pure no-ops, so an
+ * unconfigured app is byte-identical to before this feature. That
+ * invariant is the #1 risk and is guarded differentially in the tests.
+ *
+ * OUT OF SCOPE (a documented follow-up, the same boundary Next draws):
+ * rewriting AUTHOR-written `<a href="/about">` links and client-router
+ * navigation prefixing. This module covers framework-emitted URLs and the
+ * ingress match only.
+ */
+
+/**
+ * Normalize a raw `webjs.basePath` value to the canonical internal form:
+ * either `''` (the no-op default) or a string with exactly one leading
+ * `/` and no trailing `/`. So `'app'`, `'/app'`, and `'/app/'` all map to
+ * `'/app'`, and a nested `'/foo/bar'` is preserved.
+ *
+ * Empty / undefined / non-string / `'/'` all map to `''` (no base path).
+ * A value that cannot be a safe, single-origin path prefix is rejected to
+ * `''`: anything containing `..` (path traversal), a protocol (`://`), a
+ * backslash, whitespace, or a network-path `//host` reference. So a typo
+ * or a hostile value fails safe to "no base path" rather than poisoning
+ * every emitted URL.
+ *
+ * @param {unknown} raw the configured value
+ * @returns {string} `''` or `/segment[/segment...]`
+ */
+export function normalizeBasePath(raw) {
+  if (typeof raw !== 'string') return '';
+  let v = raw.trim();
+  if (v === '' || v === '/') return '';
+  // Reject anything that is not a plain same-origin path prefix.
+  if (v.includes('..')) return '';
+  if (v.includes('://')) return '';
+  if (v.includes('\\')) return '';
+  if (/\s/.test(v)) return '';
+  // Reject a network-path reference (`//host`) BEFORE collapsing leading
+  // slashes: such a value would emit a protocol-relative, cross-origin URL
+  // once prefixed (an open redirect / origin escape), so it fails safe to
+  // "no base path" rather than being collapsed to `/host`.
+  if (v.startsWith('//')) return '';
+  // Ensure exactly one leading slash.
+  v = '/' + v.replace(/^\/+/, '');
+  // Strip any trailing slash(es).
+  v = v.replace(/\/+$/, '');
+  // A leading-slash-only value collapses to '' here (already handled as
+  // '/' above, but guard a value like '//' that slipped a different path).
+  if (v === '' || v === '/') return '';
+  return v;
+}
+
+/**
+ * Read and normalize the `webjs.basePath` config from a parsed
+ * package.json (or any object). Pure; `dev.js` wraps it with the
+ * package.json read like the other `webjs.*` readers.
+ *
+ * @param {unknown} pkg parsed package.json (or any object)
+ * @returns {string} the normalized base path (`''` when unset)
+ */
+export function readBasePath(pkg) {
+  const raw =
+    pkg &&
+    typeof pkg === 'object' &&
+    /** @type {any} */ (pkg).webjs &&
+    /** @type {any} */ (pkg).webjs.basePath;
+  return normalizeBasePath(raw);
+}
+
+/**
+ * Prefix a framework-emitted same-origin absolute URL with the base path.
+ * Returns the URL unchanged when basePath is empty (the no-op default) or
+ * when the URL is not a same-origin absolute path (a cross-origin
+ * `https://` CDN target, a protocol-relative `//host` reference, or a
+ * relative URL), so only the framework's own `/`-rooted paths are moved.
+ *
+ * @param {string} url the URL to (maybe) prefix
+ * @param {string} basePath the normalized base path (`''` = no-op)
+ * @returns {string}
+ */
+export function withBasePath(url, basePath) {
+  if (!basePath) return url;
+  if (typeof url !== 'string') return url;
+  // Only a single-leading-slash same-origin path is prefixed. A
+  // protocol-relative `//host` or an absolute `scheme://` URL is left
+  // alone (a vendor CDN target), as is a relative URL.
+  if (url[0] !== '/' || url[1] === '/') return url;
+  return basePath + url;
+}
+
+/**
+ * Compute the root-relative pathname for an incoming request pathname
+ * under the base path (the ingress strip). Returns:
+ *   - the stripped, root-relative pathname (always begins with `/`) when
+ *     the request is for this app, OR
+ *   - `null` when the request path is NOT under the base path, so the
+ *     caller can 404 it (the request is not for this mounted app).
+ *
+ * Mapping: `<basePath>` and `<basePath>/` both map to the root `/`.
+ * `<basePath>/foo` maps to `/foo`. A path that merely shares a prefix but
+ * is not a real segment boundary (e.g. `/application` under basePath
+ * `/app`) is NOT under the base path and returns null. When basePath is
+ * empty this is a pure pass-through (returns the input unchanged).
+ *
+ * @param {string} pathname the incoming request pathname (begins with `/`)
+ * @param {string} basePath the normalized base path (`''` = no-op)
+ * @returns {string | null}
+ */
+export function stripBasePath(pathname, basePath) {
+  if (!basePath) return pathname;
+  if (pathname === basePath) return '/';
+  const withSlash = basePath + '/';
+  if (pathname.startsWith(withSlash)) {
+    // Slice off the base path; keep the leading slash of the remainder.
+    const rest = pathname.slice(basePath.length);
+    return rest || '/';
+  }
+  // Not under the base path (`/application` vs basePath `/app`, or an
+  // unrelated path): not this app.
+  return null;
+}

package/src/build-info.js

@@ -0,0 +1,59 @@
+import { createRequire } from 'node:module';
+import { publishedBuildId } from './importmap.js';
+
+/**
+ * Build-info / version probe (issue #239).
+ *
+ * `GET /__webjs/version` returns a small JSON object a deploy can curl to
+ * verify which build is live, alongside the existing `/__webjs/health` and
+ * `/__webjs/ready` probes. It carries NO secrets: only the framework version,
+ * the published importmap build id (the same value the client router reads
+ * from `data-webjs-build` to detect a deploy), the running node version, and
+ * process uptime. Served before `ensureReady()` like the other probes, so it
+ * answers on a cold instance without blocking on the whole-app analysis.
+ *
+ * The framework version is read once from this package's own `package.json`,
+ * the same single-source pattern `requiredNodeMajor()` uses, so it never drifts
+ * from the published version.
+ */
+
+/** @type {string} */
+let _frameworkVersion = '';
+function frameworkVersion() {
+  if (_frameworkVersion) return _frameworkVersion;
+  try {
+    const require = createRequire(import.meta.url);
+    const pkg = require('../package.json');
+    _frameworkVersion = String(pkg?.version || '');
+  } catch {
+    _frameworkVersion = '';
+  }
+  return _frameworkVersion;
+}
+
+/**
+ * Compose the build-info payload. Pure (takes the moment as an argument) so a
+ * test can assert the shape without mocking the clock; the handler calls it
+ * with `process.uptime()`.
+ *
+ * @param {{ uptime?: number }} [opts]
+ * @returns {{ version: string, build: string, node: string, uptime: number }}
+ */
+export function buildInfo(opts = {}) {
+  return {
+    version: frameworkVersion(),
+    build: publishedBuildId(),
+    node: process.version,
+    uptime: typeof opts.uptime === 'number' ? opts.uptime : process.uptime(),
+  };
+}
+
+/**
+ * Build the `GET /__webjs/version` response. `no-store` so a proxy / browser
+ * never caches a stale build fingerprint.
+ *
+ * @returns {Response}
+ */
+export function buildInfoResponse() {
+  return Response.json(buildInfo(), { headers: { 'cache-control': 'no-store' } });
+}

package/src/cache-fn.js

@@ -24,6 +24,7 @@
  */
 
 import { getStore } from './cache.js';
+import { addKeyToTags } from './cache-tags.js';
 
 /**
  * Wrap an async function with server-side caching.
@@ -33,9 +34,18 @@ import { getStore } from './cache.js';
  * @param {{
  *   key: string,
  *   ttl?: number,
+ *   tags?: string[] | ((...args: Parameters<T>) => string[]),
  * }} opts
  *   - `key`: cache key prefix. Combined with serialized args to form the full key.
  *   - `ttl`: time-to-live in seconds. Default: 60.
+ *   - `tags`: optional tags this cached result belongs to, for cross-module
+ *     invalidation via `revalidateTag(tag)`. Either a static `string[]`
+ *     (every cached entry of this function shares them) or a function
+ *     `(...args) => string[]` so a per-arg read tags with the entity id
+ *     (e.g. `tags: (id) => ['post:' + id]`). The result is also recorded
+ *     under each tag's thin key index so `revalidateTag` can find and
+ *     evict it later, including arg-specific entries that the no-args
+ *     `invalidate()` cannot reach.
  * @returns {T & { invalidate: () => Promise<void> }}
  *   The cached function with the same signature, plus an `invalidate()`
  *   method to manually clear the cache.
@@ -43,6 +53,19 @@ import { getStore } from './cache.js';
 export function cache(fn, opts) {
   const prefix = opts.key;
   const ttlMs = (opts.ttl ?? 60) * 1000;
+  const tagsOpt = opts.tags;
+
+  /**
+   * Resolve the tag list for one call. A function form receives the call
+   * args (so a per-entity read can tag with the id); a static array is
+   * returned as-is. Anything else yields no tags.
+   * @param {any[]} args
+   * @returns {string[]}
+   */
+  function tagsFor(args) {
+    const raw = typeof tagsOpt === 'function' ? tagsOpt(...args) : tagsOpt;
+    return Array.isArray(raw) ? raw.filter((t) => typeof t === 'string' && t) : [];
+  }
 
   const wrapped = /** @type {T & { invalidate: () => Promise<void> }} */ (
     async function (...args) {
@@ -58,6 +81,23 @@ export function cache(fn, opts) {
 
       const result = await fn(...args);
       await store.set(cacheKey, JSON.stringify(result), ttlMs);
+      // Record tag -> cacheKey in the thin tag index so a later
+      // revalidateTag can find and evict this entry (including
+      // arg-specific keys the no-args invalidate() cannot reach).
+      // Best-effort: the value is already stored, so taggability must
+      // never break the cached call. A user tags() function that throws
+      // (e.g. reading post.id off a null arg), or an index write that
+      // fails, leaves the value cached (just untagged) and returns
+      // normally. tagsFor() is INSIDE the try because it runs the
+      // user-supplied function.
+      try {
+        await addKeyToTags(tagsFor(args), cacheKey, ttlMs);
+      } catch (err) {
+        console.warn(
+          `[webjs] cache(${prefix}): tag indexing failed, value is cached ` +
+          `but untagged (revalidateTag will not reach it): ${err && err.message ? err.message : err}`
+        );
+      }
       return result;
     }
   );

package/src/cache-tags.js

@@ -0,0 +1,147 @@
+/**
+ * Tag-based invalidation for server `cache()` (the Next.js revalidateTag
+ * model), built as a THIN key-index over the existing pluggable store
+ * (`get` / `set` / `delete` in `cache.js`), NOT a new subsystem.
+ *
+ * The problem it solves: `cache(fn, { key, ttl })` can only be invalidated
+ * by calling `wrapped.invalidate()` from the module that owns the wrapper,
+ * and even then only the no-args base key (arg-specific keys leak until
+ * their TTL). There was no way for an unrelated mutation (createComment)
+ * to invalidate a related read (postById) without importing every wrapper.
+ *
+ * The index: when a cached result is stored, `cache-fn.js` also records the
+ * mapping `tag -> cacheKey` here. Each tag holds a JSON array of the cache
+ * keys tagged with it, under the namespaced store key `cache:tag:<tag>`.
+ * `revalidateTag(tag)` reads that array, deletes every cache key in it, then
+ * clears the index entry. A mutation in ANY module can therefore evict every
+ * read tagged `'posts'` across modules with one explicit call.
+ *
+ * It stays a thin index over `store.get/set/delete`: no new store method, a
+ * plain JSON array (a Set is trivial in the memory store; the same get/set of
+ * a JSON array works for Redis). The cohesive companion for HTML paths is
+ * `revalidatePath` in `html-cache.js`; together they are the server cache
+ * invalidation surface (this one for `cache()` DATA, that one for cached HTML).
+ *
+ * MULTI-INSTANCE CAVEAT (mirrors #241): the index is a plain read-modify-write
+ * of a JSON array, NOT atomic across processes. With a shared Redis store,
+ * `revalidateTag` deletes the keys it can see and reaches every instance for
+ * those keys, but two instances appending to the same tag concurrently can
+ * lose an append (last write wins), so a freshly-stored key on a peer might
+ * miss eviction and live until its TTL. The tag index entry itself also
+ * carries the cache TTL, so the index self-prunes and never grows unbounded.
+ * For strict cross-instance invalidation, prefer a short `ttl` as the floor.
+ *
+ * @module cache-tags
+ */
+
+import { getStore } from './cache.js';
+
+/** Namespace prefix for every tag-index key, parallel to `cache:` entries. */
+const TAG_PREFIX = 'cache:tag:';
+
+/** @param {string} tag @returns {string} */
+function tagKey(tag) {
+  return `${TAG_PREFIX}${tag}`;
+}
+
+/**
+ * Read the cache-key set stored under one tag. Returns a plain array (empty
+ * on a miss / parse error, failing open). The store holds a JSON array.
+ *
+ * @param {string} tag
+ * @returns {Promise<string[]>}
+ */
+async function readTagKeys(tag) {
+  try {
+    const raw = await getStore().get(tagKey(tag));
+    if (!raw) return [];
+    const arr = JSON.parse(raw);
+    return Array.isArray(arr) ? arr : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Append a cache key to every given tag's index (deduped). Called by
+ * `cache-fn.js` right after it stores a cached result. The index entry
+ * carries the same TTL as the cached value so it self-prunes and the tag
+ * index never outgrows the data it points at.
+ *
+ * Best-effort: a store failure here never affects the cached result that was
+ * already written (the value is still served; only its taggability is lost).
+ *
+ * @param {string[]} tags
+ * @param {string} cacheKey
+ * @param {number} [ttlMs]
+ * @returns {Promise<void>}
+ */
+export async function addKeyToTags(tags, cacheKey, ttlMs) {
+  if (!Array.isArray(tags) || tags.length === 0) return;
+  const store = getStore();
+  for (const tag of tags) {
+    if (typeof tag !== 'string' || !tag) continue;
+    try {
+      const keys = await readTagKeys(tag);
+      if (keys.includes(cacheKey)) continue;
+      keys.push(cacheKey);
+      await store.set(tagKey(tag), JSON.stringify(keys), ttlMs);
+    } catch {
+      /* a tag-index write failure must never affect the cached value */
+    }
+  }
+}
+
+/**
+ * Evict every cached entry tagged with `tag`, then clear the tag index.
+ * A mutating server action calls this after a write so the next read of any
+ * tagged query recomputes. Works across modules: the read tagged `'posts'`
+ * in one module is invalidated by a `revalidateTag('posts')` issued from
+ * any other.
+ *
+ * ```js
+ * // modules/comments/actions/create-comment.server.ts
+ * 'use server';
+ * import { revalidateTag } from '@webjsdev/server';
+ * export async function createComment(input) {
+ *   await prisma.comment.create({ data: input });
+ *   await revalidateTag('post:' + input.postId); // postById(postId) recomputes
+ *   return { success: true };
+ * }
+ * ```
+ *
+ * @param {string} tag
+ * @returns {Promise<void>}
+ */
+export async function revalidateTag(tag) {
+  if (typeof tag !== 'string' || !tag) return;
+  const store = getStore();
+  const keys = await readTagKeys(tag);
+  for (const k of keys) {
+    try {
+      await store.delete(k);
+    } catch {
+      /* a delete failure is non-fatal: the entry still expires via its TTL */
+    }
+  }
+  try {
+    await store.delete(tagKey(tag));
+  } catch {
+    /* non-fatal */
+  }
+}
+
+/**
+ * Convenience: `revalidateTag` for several tags in one call. A mutation that
+ * touches multiple cached surfaces (e.g. a post AND the post list) evicts
+ * them together.
+ *
+ * @param {string[]} tags
+ * @returns {Promise<void>}
+ */
+export async function revalidateTags(tags) {
+  if (!Array.isArray(tags)) return;
+  for (const tag of tags) {
+    await revalidateTag(tag);
+  }
+}