@forumone/throughline-workflows 0.3.1 → 0.5.0

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iCAAiC,EAAE,MAAM,4BAA4B,CAAA;AAC9E,OAAO,EAAE,uCAAuC,EAAE,MAAM,kCAAkC,CAAA;AAC1F,OAAO,EAAE,kCAAkC,EAAE,MAAM,6BAA6B,CAAA;AAChF,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAA;AACpE,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C,YAAY,EACV,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,gCAAgC,EAChC,2BAA2B,EAC3B,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iCAAiC,EAAE,MAAM,4BAA4B,CAAA;AAC9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAA;AACtE,YAAY,EACV,wBAAwB,EACxB,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,GACZ,MAAM,2BAA2B,CAAA;AAKlC,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACnE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChE,OAAO,EAAE,uCAAuC,EAAE,MAAM,kCAAkC,CAAA;AAC1F,OAAO,EAAE,oCAAoC,EAAE,MAAM,gCAAgC,CAAA;AACrF,OAAO,EAAE,kCAAkC,EAAE,MAAM,6BAA6B,CAAA;AAChF,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAA;AACpE,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EACL,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACV,qBAAqB,EACrB,gCAAgC,GACjC,MAAM,sBAAsB,CAAA;AAE7B,YAAY,EACV,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,gCAAgC,EAChC,6BAA6B,EAC7B,uBAAuB,EACvB,sBAAsB,EACtB,2BAA2B,EAC3B,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -1,8 +1,15 @@
-// Other factory exports land in subsequent commits.
 export { createRevalidateOnPublishFunction } from './revalidate-on-publish.js';
+export { createTagRevalidationHooks } from './revalidate-tag-hooks.js';
+/*
+Also on `@forumone/throughline-workflows/cache-tags`, which imports nothing —
+readers in frontend code should import it from there.
+*/
+export { createCacheTags, defaultCacheTags } from './cache-tags.js';
 export { createExecuteScheduledPublishesFunction } from './execute-scheduled-publishes.js';
+export { createPublishAtScheduledTimeFunction } from './publish-at-scheduled-time.js';
 export { createExpireStaleApprovalsFunction } from './expire-stale-approvals.js';
 export { createAuditEventEchoFunction } from './audit-event-echo.js';
 export { createHealthcheckFunction, createPayloadReachableCheck, createManifestReachableCheck, } from './healthcheck.js';
 export { failureOptions } from './types.js';
+export { createHealthcheckFailureHandler, createTerminalFailureHandler, } from './failure-handler.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oDAAoD;AAEpD,OAAO,EAAE,iCAAiC,EAAE,MAAM,4BAA4B,CAAA;AAC9E,OAAO,EAAE,uCAAuC,EAAE,MAAM,kCAAkC,CAAA;AAC1F,OAAO,EAAE,kCAAkC,EAAE,MAAM,6BAA6B,CAAA;AAChF,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAA;AACpE,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iCAAiC,EAAE,MAAM,4BAA4B,CAAA;AAC9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAA;AAStE;;;EAGE;AACF,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAEnE,OAAO,EAAE,uCAAuC,EAAE,MAAM,kCAAkC,CAAA;AAC1F,OAAO,EAAE,oCAAoC,EAAE,MAAM,gCAAgC,CAAA;AACrF,OAAO,EAAE,kCAAkC,EAAE,MAAM,6BAA6B,CAAA;AAChF,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAA;AACpE,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EACL,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,sBAAsB,CAAA"}

package/dist/next-revalidate.d.ts

@@ -0,0 +1,43 @@
+import type * as NextCacheModule from 'next/cache';
+type NextCache = typeof NextCacheModule;
+/**
+ * How stale a caller may find a tag after it is dropped: not at all.
+ *
+ * Next 16 made `revalidateTag`'s second argument required — it is a cache-life
+ * profile — and one-argument calls log a deprecation warning on every call.
+ * `{ expire: 0 }` is the immediate expiry the one-argument form used to mean,
+ * and it is what an editor pressing Publish or Save expects.
+ *
+ * Passed unconditionally rather than behind a version check. The peer range is
+ * `next >= 15`, and Next 15's `revalidateTag` takes one parameter and ignores a
+ * second, so the two-argument call is correct on both.
+ *
+ * `updateTag`, which Next offers as the other way out of the deprecation, is
+ * not usable here: it throws outside a Server Action, and these run in an
+ * Inngest step or in Payload's route handler.
+ */
+export declare const IMMEDIATE: {
+    readonly expire: 0;
+};
+/**
+ * `next/cache`, loaded on first use.
+ *
+ * Dynamic so the package can be imported where Next is not installed (test
+ * runners, a non-Next frontend that passes its own revalidator). `next` is an
+ * optional peer.
+ */
+export declare function loadNextCache(): Promise<NextCache>;
+/**
+ * Whether `error` is Next saying there is no request to revalidate for.
+ *
+ * Seeds, migrations and the Payload CLI write through the same hooks under
+ * `tsx` rather than inside a Next server. `revalidateTag` then throws
+ * `Invariant: static generation store missing in revalidateTag ...`. Nothing is
+ * stale in that case — there is no server to be stale — so it is the one
+ * failure that is not a fault.
+ *
+ * Matched on the message, the only stable surface Next gives it.
+ */
+export declare function isOutsideNextRequest(error: unknown): boolean;
+export {};
+//# sourceMappingURL=next-revalidate.d.ts.map

package/dist/next-revalidate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-revalidate.d.ts","sourceRoot":"","sources":["../src/next-revalidate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,eAAe,MAAM,YAAY,CAAA;AAElD,KAAK,SAAS,GAAG,OAAO,eAAe,CAAA;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,SAAS;;CAAyB,CAAA;AAE/C;;;;;;GAMG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,SAAS,CAAC,CAExD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D"}

package/dist/next-revalidate.js

@@ -0,0 +1,42 @@
+/**
+ * How stale a caller may find a tag after it is dropped: not at all.
+ *
+ * Next 16 made `revalidateTag`'s second argument required — it is a cache-life
+ * profile — and one-argument calls log a deprecation warning on every call.
+ * `{ expire: 0 }` is the immediate expiry the one-argument form used to mean,
+ * and it is what an editor pressing Publish or Save expects.
+ *
+ * Passed unconditionally rather than behind a version check. The peer range is
+ * `next >= 15`, and Next 15's `revalidateTag` takes one parameter and ignores a
+ * second, so the two-argument call is correct on both.
+ *
+ * `updateTag`, which Next offers as the other way out of the deprecation, is
+ * not usable here: it throws outside a Server Action, and these run in an
+ * Inngest step or in Payload's route handler.
+ */
+export const IMMEDIATE = { expire: 0 };
+/**
+ * `next/cache`, loaded on first use.
+ *
+ * Dynamic so the package can be imported where Next is not installed (test
+ * runners, a non-Next frontend that passes its own revalidator). `next` is an
+ * optional peer.
+ */
+export async function loadNextCache() {
+    return await import('next/cache');
+}
+/**
+ * Whether `error` is Next saying there is no request to revalidate for.
+ *
+ * Seeds, migrations and the Payload CLI write through the same hooks under
+ * `tsx` rather than inside a Next server. `revalidateTag` then throws
+ * `Invariant: static generation store missing in revalidateTag ...`. Nothing is
+ * stale in that case — there is no server to be stale — so it is the one
+ * failure that is not a fault.
+ *
+ * Matched on the message, the only stable surface Next gives it.
+ */
+export function isOutsideNextRequest(error) {
+    return error instanceof Error && error.message.includes('static generation store missing');
+}
+//# sourceMappingURL=next-revalidate.js.map

package/dist/next-revalidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-revalidate.js","sourceRoot":"","sources":["../src/next-revalidate.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,MAAM,EAAE,CAAC,EAAW,CAAA;AAE/C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,OAAO,MAAM,MAAM,CAAC,YAAY,CAAC,CAAA;AACnC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,iCAAiC,CAAC,CAAA;AAC5F,CAAC"}

package/dist/publish-at-scheduled-time.d.ts

@@ -0,0 +1,23 @@
+import type { InngestFunction } from 'inngest';
+import type { PublishAtScheduledTimeOptions } from './types.js';
+/**
+ * Publishes a document at the moment it was scheduled for, by sleeping until
+ * then — rather than polling for due documents.
+ *
+ * Triggered by `content/page.scheduled`, which the publishing plugin sends
+ * whenever a document's scheduled time changes to a new value. The event is a
+ * wake-up call and nothing more: **the document is the source of truth.** On
+ * waking, the run re-reads the document's latest version and publishes only if
+ * it still carries this exact time. So a reschedule, a cancellation, a manual
+ * publish in the meantime or an unpublish — each of which changes or clears
+ * the field — leaves the old run to wake, find nothing to do, and end. No
+ * cancellation event has to arrive for that to be correct, and a duplicate
+ * event cannot publish twice (the `idempotency` key drops the second anyway).
+ *
+ * `publish` must go through the publishing pipeline, exactly as for
+ * `createExecuteScheduledPublishesFunction`: a scheduled publish gets the same
+ * composition / accessibility / approval checks as an interactive one, and a
+ * refusal is logged, not retried.
+ */
+export declare function createPublishAtScheduledTimeFunction(options: PublishAtScheduledTimeOptions): InngestFunction.Any;
+//# sourceMappingURL=publish-at-scheduled-time.d.ts.map

package/dist/publish-at-scheduled-time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-at-scheduled-time.d.ts","sourceRoot":"","sources":["../src/publish-at-scheduled-time.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC9C,OAAO,KAAK,EAAE,6BAA6B,EAA6B,MAAM,YAAY,CAAA;AA8B1F;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oCAAoC,CAClD,OAAO,EAAE,6BAA6B,GACrC,eAAe,CAAC,GAAG,CA4FrB"}

package/dist/publish-at-scheduled-time.js

@@ -0,0 +1,133 @@
+import { failureOptions } from './types.js';
+const SCHEDULED_EVENT = 'content/page.scheduled';
+const REASONING = 'Scheduled publish executed at its scheduled time';
+/*
+Six days, under the seven Inngest's free plan allows a single sleep.
+
+A schedule further out than one hop is carried by a relay: the run sleeps a
+hop, then re-sends the event and ends, so each leg is its own run. That also
+keeps every run far inside the free plan's thirty-day run duration, which a
+loop of sleeps inside one run would not — a post scheduled for next quarter
+would simply be killed.
+*/
+const DEFAULT_MAX_SLEEP_MS = 6 * 24 * 60 * 60 * 1000;
+/**
+ * Publishes a document at the moment it was scheduled for, by sleeping until
+ * then — rather than polling for due documents.
+ *
+ * Triggered by `content/page.scheduled`, which the publishing plugin sends
+ * whenever a document's scheduled time changes to a new value. The event is a
+ * wake-up call and nothing more: **the document is the source of truth.** On
+ * waking, the run re-reads the document's latest version and publishes only if
+ * it still carries this exact time. So a reschedule, a cancellation, a manual
+ * publish in the meantime or an unpublish — each of which changes or clears
+ * the field — leaves the old run to wake, find nothing to do, and end. No
+ * cancellation event has to arrive for that to be correct, and a duplicate
+ * event cannot publish twice (the `idempotency` key drops the second anyway).
+ *
+ * `publish` must go through the publishing pipeline, exactly as for
+ * `createExecuteScheduledPublishesFunction`: a scheduled publish gets the same
+ * composition / accessibility / approval checks as an interactive one, and a
+ * refusal is logged, not retried.
+ */
+export function createPublishAtScheduledTimeFunction(options) {
+    const maxSleepMs = options.maxSleepMs ?? DEFAULT_MAX_SLEEP_MS;
+    const collections = new Map(options.collections.map((c) => [c.slug, c]));
+    return options.inngest.createFunction({
+        id: options.id ?? 'publish-at-scheduled-time',
+        /*
+        One run per schedule. The plugin sends once per change, but an MCP
+        schedule and the field hook seeing the same write, or a retried send,
+        would otherwise start two sleepers that both wake and both publish.
+        Inngest keeps this key for 24 hours, and a relay is six days after the
+        event that started its leg, so a relay is never mistaken for a duplicate.
+        */
+        idempotency: 'event.data.collection + ":" + event.data.id + ":" + event.data.scheduledFor',
+        ...failureOptions(options),
+        triggers: [{ event: SCHEDULED_EVENT }],
+    }, async ({ event, step, logger }) => {
+        const data = event.data;
+        const config = data.collection ? collections.get(data.collection) : undefined;
+        const target = typeof data.scheduledFor === 'string' ? Date.parse(data.scheduledFor) : NaN;
+        if (!config || !data.id || !data.scheduledFor || Number.isNaN(target)) {
+            return { outcome: 'ignored', reason: 'not a scheduled publish this function handles' };
+        }
+        const request = { collection: config.slug, id: data.id, scheduledFor: data.scheduledFor };
+        /*
+        Measured from the event's own timestamp, not the clock. Inngest replays
+        the handler from the top after every step, so a `Date.now()` here would
+        give a different answer on each replay — and flipping from the relay
+        branch to the direct branch halfway through a run is a run whose steps
+        no longer match its history.
+        */
+        const startedAt = typeof event.ts === 'number' ? event.ts : Date.now();
+        if (target - startedAt > maxSleepMs) {
+            const hopUntil = new Date(startedAt + maxSleepMs);
+            await step.sleepUntil('wait-one-hop', hopUntil);
+            // Only relay a schedule that still stands, or a cancelled one would
+            // keep re-sending itself every six days until its date came round.
+            const current = await step.run('check-still-scheduled', () => isStillScheduled(options, config, request));
+            if (!current)
+                return { outcome: 'superseded' };
+            await step.sendEvent('relay', { name: SCHEDULED_EVENT, data: request });
+            return { outcome: 'relayed', hopUntil: hopUntil.toISOString() };
+        }
+        await step.sleepUntil('wait-until-due', new Date(target));
+        const due = await step.run('check-still-scheduled', () => isStillScheduled(options, config, request));
+        if (!due) {
+            logger.info('Scheduled publish superseded', request);
+            return { outcome: 'superseded' };
+        }
+        return step.run('publish', async () => {
+            try {
+                const result = await options.publish({
+                    collection: config.slug,
+                    id: request.id,
+                    reasoning: REASONING,
+                });
+                if (!result.published) {
+                    logger.warn('Scheduled publish blocked by policy', {
+                        ...request,
+                        reason: result.reason,
+                    });
+                    return { outcome: 'blocked', reason: result.reason };
+                }
+                logger.info('Scheduled publish succeeded', request);
+                return { outcome: 'published' };
+            }
+            catch (error) {
+                /*
+                Not rethrown. A retry would re-run the pipeline against the same
+                document, and the daily backstop in
+                `createExecuteScheduledPublishesFunction` already comes back for a
+                document that is still a draft past its time.
+                */
+                const reason = error instanceof Error ? error.message : String(error);
+                logger.error('Scheduled publish threw', { ...request, error: reason });
+                return { outcome: 'error', reason };
+            }
+        });
+    });
+}
+/**
+ * Whether the document's latest version still carries this schedule.
+ *
+ * `draft: true`, because a schedule is written by a draft save and Payload
+ * writes a draft save to the versions table only — the main row is not
+ * touched, so a read without it would see a document with no schedule at all.
+ */
+async function isStillScheduled(options, config, request) {
+    const field = config.scheduledField ?? 'scheduledPublishAt';
+    const doc = (await options.payload.findByID({
+        collection: config.slug,
+        id: request.id,
+        draft: true,
+        depth: 0,
+        disableErrors: true,
+    }));
+    const value = doc?.[field];
+    if (typeof value !== 'string')
+        return false;
+    return Date.parse(value) === Date.parse(request.scheduledFor);
+}
+//# sourceMappingURL=publish-at-scheduled-time.js.map

package/dist/publish-at-scheduled-time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-at-scheduled-time.js","sourceRoot":"","sources":["../src/publish-at-scheduled-time.ts"],"names":[],"mappings":"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"}

package/dist/revalidate-on-publish.d.ts

@@ -5,6 +5,16 @@ import type { RevalidateOnPublishOptions } from './types.js';
  * publishing taxonomy and revalidates Next.js cache entries for the affected
  * page, the listing routes, and the sitemap.
  *
+ * The page path comes from `options.urlBuilders`, which is required: only the
+ * site knows where a collection's documents are served. A collection with no
+ * builder gets its tags dropped and no path revalidated, with a warning —
+ * there used to be built-in builders (`pages` → `/<slug>`, `posts` →
+ * `/blog/<slug>`, anything else → `/<slug>`), and a site whose routes differed
+ * revalidated the wrong path without a word.
+ *
+ * Tags default to `cacheTags.collection(<collection>)`. Pass the same
+ * `cacheTags` your readers and your tag hooks use.
+ *
  * The default revalidate function dynamically imports `next/cache`, so the
  * package is safe to install in non-Next.js contexts. Pass `options.revalidate`
  * to use a different cache invalidation strategy.

package/dist/revalidate-on-publish.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"revalidate-on-publish.d.ts","sourceRoot":"","sources":["../src/revalidate-on-publish.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC9C,OAAO,KAAK,EAAgB,0BAA0B,EAAwB,MAAM,YAAY,CAAA;AAOhG;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,0BAA0B,GAClC,eAAe,CAAC,GAAG,CA6CrB"}
+{"version":3,"file":"revalidate-on-publish.d.ts","sourceRoot":"","sources":["../src/revalidate-on-publish.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAG9C,OAAO,KAAK,EAAgB,0BAA0B,EAAwB,MAAM,YAAY,CAAA;AAEhG;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,0BAA0B,GAClC,eAAe,CAAC,GAAG,CAqDrB"}

package/dist/revalidate-on-publish.js

@@ -1,19 +1,28 @@
 import { failureOptions } from './types.js';
-const DEFAULT_URL_BUILDERS = {
-    pages: (slug) => (slug === 'home' || slug === '' ? '/' : `/${slug}`),
-    posts: (slug) => `/blog/${slug}`,
-};
+import { defaultCacheTags } from './cache-tags.js';
+import { IMMEDIATE, loadNextCache } from './next-revalidate.js';
 /**
  * Builds the `revalidate-on-publish` Inngest function. Subscribes to the
  * publishing taxonomy and revalidates Next.js cache entries for the affected
  * page, the listing routes, and the sitemap.
  *
+ * The page path comes from `options.urlBuilders`, which is required: only the
+ * site knows where a collection's documents are served. A collection with no
+ * builder gets its tags dropped and no path revalidated, with a warning —
+ * there used to be built-in builders (`pages` → `/<slug>`, `posts` →
+ * `/blog/<slug>`, anything else → `/<slug>`), and a site whose routes differed
+ * revalidated the wrong path without a word.
+ *
+ * Tags default to `cacheTags.collection(<collection>)`. Pass the same
+ * `cacheTags` your readers and your tag hooks use.
+ *
  * The default revalidate function dynamically imports `next/cache`, so the
  * package is safe to install in non-Next.js contexts. Pass `options.revalidate`
  * to use a different cache invalidation strategy.
  */
 export function createRevalidateOnPublishFunction(options) {
-    const urlBuilders = { ...DEFAULT_URL_BUILDERS, ...options.urlBuilders };
+    const urlBuilders = options.urlBuilders;
+    const cacheTags = options.cacheTags ?? defaultCacheTags;
     const collectionTags = options.collectionTags ?? {};
     const revalidate = options.revalidate ?? defaultRevalidate;
     return options.inngest.createFunction({
@@ -34,9 +43,13 @@ export function createRevalidateOnPublishFunction(options) {
         const data = (event.data ?? {});
         const collection = data.collection ?? 'pages';
         const slug = data.slug ?? data.id ?? '';
-        const tags = collectionTags[collection] ?? [collection];
+        const tags = collectionTags[collection] ?? [cacheTags.collection(collection)];
         await step.run('revalidate-page-path', async () => {
-            const builder = urlBuilders[collection] ?? ((s) => `/${s}`);
+            const builder = Object.hasOwn(urlBuilders, collection) ? urlBuilders[collection] : undefined;
+            if (!builder) {
+                logger.warn('No urlBuilders entry for this collection, so no page path was revalidated. Add one to createRevalidateOnPublishFunction.', { collection, slug });
+                return;
+            }
             const path = builder(slug);
             await revalidate({ path, tags });
             logger.info('Revalidated page path', { path, tags });
@@ -50,23 +63,6 @@ export function createRevalidateOnPublishFunction(options) {
         return { collection, slug, revalidated: true };
     });
 }
-/**
- * How stale a caller may find a tag after this runs: not at all.
- *
- * Next 16 made `revalidateTag`'s second argument required — it is a cache-life
- * profile — and one-argument calls log a deprecation warning on every publish.
- * `{ expire: 0 }` is the immediate expiry the one-argument form used to mean,
- * and it is what an editor pressing Publish expects.
- *
- * Passed unconditionally rather than behind a version check. The peer range is
- * `next >= 15`, and Next 15's `revalidateTag` takes one parameter and ignores a
- * second, so the two-argument call is correct on both.
- *
- * `updateTag`, which Next offers as the other way out of the deprecation, is
- * not usable here: it throws outside a Server Action, and this runs in an
- * Inngest step behind a route handler.
- */
-const IMMEDIATE = { expire: 0 };
 /**
  * Default revalidator: dynamic-imports `next/cache` so the package can be
  * imported in environments without Next.js (e.g. test runners that don't
@@ -74,7 +70,7 @@ const IMMEDIATE = { expire: 0 };
  * because `revalidatePath('')` triggers a noisy Next.js warning.
  */
 const defaultRevalidate = async ({ path, tags }) => {
-    const { revalidatePath, revalidateTag } = (await import('next/cache'));
+    const { revalidatePath, revalidateTag } = await loadNextCache();
     if (path)
         revalidatePath(path);
     for (const tag of tags)

package/dist/revalidate-on-publish.js.map

@@ -1 +1 @@
-{"version":3,"file":"revalidate-on-publish.js","sourceRoot":"","sources":["../src/revalidate-on-publish.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"revalidate-on-publish.js","sourceRoot":"","sources":["../src/revalidate-on-publish.ts"],"names":[],"mappings":"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"}

package/dist/revalidate-tag-hooks.d.ts

@@ -0,0 +1,80 @@
+import type { CollectionAfterChangeHook, CollectionAfterDeleteHook, GlobalAfterChangeHook } from 'payload';
+import { type CacheTags } from './cache-tags.js';
+/** Drops one tag. Return a promise to have it awaited. */
+export type RevalidateTagFn = (tag: string) => void | Promise<void>;
+export interface TagRevalidationOptions {
+    /**
+     * The tag scheme. Pass the same object your readers build their tags from —
+     * that is the whole point of it. Default: `defaultCacheTags`.
+     */
+    cacheTags?: CacheTags;
+    /**
+     * How to drop a tag. Default: Next's `revalidateTag(tag, { expire: 0 })`,
+     * loaded from `next/cache` on first use. Supply your own for a non-Next
+     * frontend or a CDN.
+     */
+    revalidateTag?: RevalidateTagFn;
+}
+/** Which tags a hook drops, built from the scheme. */
+export type TagSelector = (cacheTags: CacheTags, slug: string) => readonly string[];
+export interface CollectionTagHookOptions {
+    /**
+     * The tags to drop. Default: the collection's own tag,
+     * `cacheTags.collection(slug)`. Use it to drop a tag a *different* reader
+     * owns — a navigation global that links to pages caches the pages' slugs:
+     *
+     * ```ts
+     * tags: (t, slug) => [t.collection(slug), t.global('navigation')]
+     * ```
+     */
+    tags?: TagSelector;
+    /**
+     * Which `afterChange` operations drop. Default: both. An upload collection
+     * can pass `['update']`: nothing can reference a document that did not exist
+     * a moment ago, so creating one makes no cached page untrue.
+     */
+    operations?: ReadonlyArray<'create' | 'update'>;
+}
+export interface GlobalTagHookOptions {
+    /** The tags to drop. Default: the global's own tag, `cacheTags.global(slug)`. */
+    tags?: TagSelector;
+}
+export interface TagRevalidationHooks {
+    /** `afterChange` for a collection. Skips draft writes. */
+    afterCollectionChange(options?: CollectionTagHookOptions): CollectionAfterChangeHook;
+    /** `afterDelete` for a collection. */
+    afterCollectionDelete(options?: Pick<CollectionTagHookOptions, 'tags'>): CollectionAfterDeleteHook;
+    /** `afterChange` for a global. */
+    afterGlobalChange(options?: GlobalTagHookOptions): GlobalAfterChangeHook;
+}
+/**
+ * Builds the tag-revalidation hooks for one tag scheme.
+ *
+ * ```ts
+ * import { createTagRevalidationHooks } from '@forumone/throughline-workflows'
+ * import { cacheTags } from './lib/cache-tags'
+ *
+ * const revalidation = createTagRevalidationHooks({ cacheTags })
+ *
+ * const Pages: CollectionConfig = {
+ *   slug: 'pages',
+ *   hooks: {
+ *     afterChange: [revalidation.afterCollectionChange()],
+ *     afterDelete: [revalidation.afterCollectionDelete()],
+ *   },
+ *   ...
+ * }
+ * const Navigation: GlobalConfig = {
+ *   slug: 'navigation',
+ *   hooks: { afterChange: [revalidation.afterGlobalChange()] },
+ *   ...
+ * }
+ * ```
+ *
+ * A hook never throws. Failing it would roll back the editor's save over a
+ * cache miss. A failure is logged at `error` instead, and the one expected
+ * failure — running outside a Next request, as seeds, migrations and the CLI
+ * do — at `debug`.
+ */
+export declare function createTagRevalidationHooks(options?: TagRevalidationOptions): TagRevalidationHooks;
+//# sourceMappingURL=revalidate-tag-hooks.d.ts.map

package/dist/revalidate-tag-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revalidate-tag-hooks.d.ts","sourceRoot":"","sources":["../src/revalidate-tag-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,yBAAyB,EACzB,yBAAyB,EACzB,qBAAqB,EAEtB,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,KAAK,SAAS,EAAoB,MAAM,iBAAiB,CAAA;AAgBlE,0DAA0D;AAC1D,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAEnE,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;;;;OAIG;IACH,aAAa,CAAC,EAAE,eAAe,CAAA;CAChC;AAED,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,CAAA;AAEnF,MAAM,WAAW,wBAAwB;IACvC;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAAA;CAChD;AAED,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,IAAI,CAAC,EAAE,WAAW,CAAA;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,qBAAqB,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,yBAAyB,CAAA;IACpF,sCAAsC;IACtC,qBAAqB,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,wBAAwB,EAAE,MAAM,CAAC,GAAG,yBAAyB,CAAA;IAClG,kCAAkC;IAClC,iBAAiB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,qBAAqB,CAAA;CACzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,sBAA2B,GACnC,oBAAoB,CA2DtB"}

package/dist/revalidate-tag-hooks.js

@@ -0,0 +1,116 @@
+import { isDraftWrite } from '@forumone/throughline-publishing';
+import { defaultCacheTags } from './cache-tags.js';
+import { IMMEDIATE, isOutsideNextRequest, loadNextCache } from './next-revalidate.js';
+/**
+ * Builds the tag-revalidation hooks for one tag scheme.
+ *
+ * ```ts
+ * import { createTagRevalidationHooks } from '@forumone/throughline-workflows'
+ * import { cacheTags } from './lib/cache-tags'
+ *
+ * const revalidation = createTagRevalidationHooks({ cacheTags })
+ *
+ * const Pages: CollectionConfig = {
+ *   slug: 'pages',
+ *   hooks: {
+ *     afterChange: [revalidation.afterCollectionChange()],
+ *     afterDelete: [revalidation.afterCollectionDelete()],
+ *   },
+ *   ...
+ * }
+ * const Navigation: GlobalConfig = {
+ *   slug: 'navigation',
+ *   hooks: { afterChange: [revalidation.afterGlobalChange()] },
+ *   ...
+ * }
+ * ```
+ *
+ * A hook never throws. Failing it would roll back the editor's save over a
+ * cache miss. A failure is logged at `error` instead, and the one expected
+ * failure — running outside a Next request, as seeds, migrations and the CLI
+ * do — at `debug`.
+ */
+export function createTagRevalidationHooks(options = {}) {
+    const cacheTags = options.cacheTags ?? defaultCacheTags;
+    const revalidateTag = options.revalidateTag ?? nextRevalidateTag;
+    async function drop(tags, req) {
+        for (const tag of new Set(tags)) {
+            try {
+                await revalidateTag(tag);
+            }
+            catch (error) {
+                /*
+                Outside Next there is no server to be stale, so that one is noise.
+                Anything else means the cache did *not* clear while a server was
+                running — a real fault, so it is logged loudly. It is still not
+                thrown: an `afterChange` that throws fails the editor's save.
+                */
+                if (isOutsideNextRequest(error)) {
+                    req.payload.logger.debug({ tag }, 'Skipped cache revalidation: not inside a Next request.');
+                }
+                else {
+                    req.payload.logger.error({ err: error, tag }, 'Failed to revalidate a cache tag; the cached copy is stale.');
+                }
+            }
+        }
+    }
+    return {
+        afterCollectionChange(hookOptions = {}) {
+            const select = hookOptions.tags ?? ((t, slug) => [t.collection(slug)]);
+            const operations = new Set(hookOptions.operations ?? ['create', 'update']);
+            return async ({ collection, doc, operation, req }) => {
+                if (!operations.has(operation))
+                    return doc;
+                if (isUnpublishedWrite(req, collection.slug, doc, operation))
+                    return doc;
+                await drop(select(cacheTags, collection.slug), req);
+                return doc;
+            };
+        },
+        afterCollectionDelete(hookOptions = {}) {
+            const select = hookOptions.tags ?? ((t, slug) => [t.collection(slug)]);
+            return async ({ collection, doc, req }) => {
+                await drop(select(cacheTags, collection.slug), req);
+                return doc;
+            };
+        },
+        afterGlobalChange(hookOptions = {}) {
+            const select = hookOptions.tags ?? ((t, slug) => [t.global(slug)]);
+            return async ({ doc, global, req }) => {
+                await drop(select(cacheTags, global.slug), req);
+                return doc;
+            };
+        },
+    };
+}
+/*
+A write the public cannot see changes nothing cached, so there is nothing to
+drop — and with autosave on, "a draft save" is every few seconds of an open
+editor. Without this, one editing session evicts the tag over and over and every
+request in between pays a cold read for content that did not change.
+
+`isDraftWrite` is publishing's own predicate, the one its trust boundary uses.
+An `afterChange` hook cannot answer this for itself: Payload sets
+`data._status = 'draft'` on any `draft: true` update before hooks run, and
+`previousDoc` is the latest *version*, so a draft save of a published document
+and an unpublish of it look the same from in here. The publishing plugin records
+the operation's real `draft` argument in `beforeOperation`. That is recorded for
+the collections the plugin manages; on any other collection `isDraftWrite` is
+false and the hook drops, which is the safe direction.
+
+An unpublish is not a draft write and still drops — it is the case that would
+otherwise leave a cached link pointing at a 404.
+
+A *create* that lands as a draft is unambiguous on its own: nothing published
+existed a moment ago, so nothing cached can be about it.
+*/
+function isUnpublishedWrite(req, collectionSlug, doc, operation) {
+    if (operation === 'create')
+        return doc?._status === 'draft';
+    return isDraftWrite(req, collectionSlug, doc?.id);
+}
+async function nextRevalidateTag(tag) {
+    const { revalidateTag } = await loadNextCache();
+    revalidateTag(tag, IMMEDIATE);
+}
+//# sourceMappingURL=revalidate-tag-hooks.js.map

package/dist/revalidate-tag-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revalidate-tag-hooks.js","sourceRoot":"","sources":["../src/revalidate-tag-hooks.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAA;AAC/D,OAAO,EAAkB,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAClE,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAoErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,0BAA0B,CACxC,UAAkC,EAAE;IAEpC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,gBAAgB,CAAA;IACvD,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,iBAAiB,CAAA;IAEhE,KAAK,UAAU,IAAI,CAAC,IAAuB,EAAE,GAAmB;QAC9D,KAAK,MAAM,GAAG,IAAI,IAAI,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAChC,IAAI,CAAC;gBACH,MAAM,aAAa,CAAC,GAAG,CAAC,CAAA;YAC1B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf;;;;;kBAKE;gBACF,IAAI,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;oBAChC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CACtB,EAAE,GAAG,EAAE,EACP,wDAAwD,CACzD,CAAA;gBACH,CAAC;qBAAM,CAAC;oBACN,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CACtB,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,EACnB,6DAA6D,CAC9D,CAAA;gBACH,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,qBAAqB,CAAC,WAAW,GAAG,EAAE;YACpC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACtE,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,UAAU,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAA;YAE1E,OAAO,KAAK,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,EAAE;gBACnD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC;oBAAE,OAAO,GAAG,CAAA;gBAC1C,IAAI,kBAAkB,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,CAAC;oBAAE,OAAO,GAAG,CAAA;gBACxE,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAA;gBACnD,OAAO,GAAG,CAAA;YACZ,CAAC,CAAA;QACH,CAAC;QAED,qBAAqB,CAAC,WAAW,GAAG,EAAE;YACpC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACtE,OAAO,KAAK,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE;gBACxC,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAA;gBACnD,OAAO,GAAG,CAAA;YACZ,CAAC,CAAA;QACH,CAAC;QAED,iBAAiB,CAAC,WAAW,GAAG,EAAE;YAChC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YAClE,OAAO,KAAK,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE;gBACpC,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAA;gBAC/C,OAAO,GAAG,CAAA;YACZ,CAAC,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;EAoBE;AACF,SAAS,kBAAkB,CACzB,GAAmB,EACnB,cAAsB,EACtB,GAAoD,EACpD,SAA8B;IAE9B,IAAI,SAAS,KAAK,QAAQ;QAAE,OAAO,GAAG,EAAE,OAAO,KAAK,OAAO,CAAA;IAC3D,OAAO,YAAY,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,EAAE,CAAC,CAAA;AACnD,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,GAAW;IAC1C,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,aAAa,EAAE,CAAA;IAC/C,aAAa,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;AAC/B,CAAC"}