@purposeinplay/payload-version-retention 0.1.1

package/dist/defaults.js

@@ -0,0 +1,74 @@
+/** Default retention window in days for version rows. */ export const DEFAULT_RETENTION_DAYS = 30;
+/**
+ * Floor on version rows left behind per document, whatever their age.
+ *
+ * Measured on the wild copy: 75 of 96 `pages` documents have their entire
+ * version history older than 30 days and 51 sit at the 25-version cap. Age
+ * plus the protected rows alone would leave most of them with a single
+ * version after one night, so a floor keeps a usable tail of recent history.
+ */ export const DEFAULT_MIN_VERSIONS_PER_DOCUMENT = 5;
+/** Default cron schedule for the janitor task: daily at 03:00. */ export const DEFAULT_JANITOR_CRON = '0 3 * * *';
+/**
+ * Queue the janitor is scheduled onto. `handleSchedules` skips queues the
+ * running autoRun config does not drain, so this must be a queue the consumer
+ * actually drains — `default` is the one every consumer has.
+ */ export const DEFAULT_JANITOR_QUEUE = 'default';
+/**
+ * How long a `processing` janitor job is believed before the lock it holds is
+ * treated as debris.
+ *
+ * Payload never resets `processing` after a crash — nothing in its queue code
+ * sweeps abandoned jobs — so an OOM mid-run would otherwise wedge every future
+ * run behind one warning, for good.
+ */ export const DEFAULT_RUN_LOCK_TTL_MS = 6 * 60 * 60 * 1000;
+/** Retries so one transient error does not skip the day's retention pass. */ export const DEFAULT_JANITOR_RETRIES = 3;
+/** Slug of the janitor task, as registered in `jobs.tasks`. */ export const JANITOR_TASK_SLUG = 'version-retention-janitor';
+/**
+ * Slug of the tiny global this plugin owns to persist its dedup cursor across
+ * runs. Its table is `version_retention_state`.
+ *
+ * A store of our own is not a nicety: Payload's `deleteJobOnComplete` defaults
+ * to `true` and hard-deletes the job row the moment it finishes, so a cursor
+ * kept only in a job's output is gone before the next run can read it.
+ */ export const STATE_GLOBAL_SLUG = 'version-retention-state';
+/**
+ * Slug of Payload's jobs collection. The same sanitize branch that injects the
+ * jobs-stats global adds a `meta` JSON field to this collection (`jobs.stats`),
+ * so its column is part of the very same migration.
+ */ export const JOBS_COLLECTION_SLUG = 'payload-jobs';
+/** Ceiling on version rows deleted per invocation, across every entity. */ export const DEFAULT_MAX_DELETIONS_PER_RUN = 5_000;
+/** Ceiling on documents examined per invocation, across every entity. */ export const DEFAULT_MAX_DOCUMENTS_PER_RUN = 20_000;
+/**
+ * Rows per page when walking the stale-version index to discover which parent
+ * documents still hold deletable history.
+ */ export const PARENT_PAGE_SIZE = 500;
+/**
+ * Newest-first window of version rows inspected per document. Must exceed the
+ * collection's `maxPerDoc` (25 in the wild consumer, 100 by Payload default)
+ * or the oldest rows fall outside the window and are never reached.
+ */ export const MAX_VERSIONS_PER_DOCUMENT = 1_000;
+/**
+ * Ids per `deleteVersions` call.
+ *
+ * Deliberately small: drizzle's `deleteVersions` runs a `findMany` with **no
+ * select** over the chunk before deleting, so every row in the chunk is
+ * materialised as a full version body first. 25 bounds that peak at 25 bodies
+ * — see the README's "Memory" note.
+ */ export const DELETE_CHUNK_SIZE = 25;
+/**
+ * Rows per page when the nested-select fallback has to read full bodies. Keeps
+ * the peak at 50 bodies instead of `MAX_VERSIONS_PER_DOCUMENT` of them; each
+ * page is reduced to the retention columns before the next is fetched.
+ */ export const FULL_BODY_PAGE_SIZE = 50;
+/** Dedup runs inside the janitor sweep by default. */ export const DEFAULT_DEDUP_MODE = 'sweep';
+/**
+ * Ceiling on version bodies the sweep reads for dedup in one invocation.
+ * Bodies are the expensive thing in these tables, so this is a separate
+ * budget from the deletion cap.
+ */ export const DEFAULT_MAX_DEDUP_BODIES_PER_RUN = 2_000;
+/**
+ * Request-context key the ai-translate plugin sets while a translation run is
+ * in flight. That plugin collapses a whole run into a single version row of
+ * its own, so the dedup hook must keep its hands off those writes.
+ */ export const AI_TRANSLATE_RUN_CONTEXT_KEY = 'aiTranslateRunId';
+/** Log prefix shared by every message this plugin emits. */ export const LOG_PREFIX = '[version-retention]';

package/dist/exports/index.d.ts

@@ -0,0 +1,2 @@
+export { versionRetentionPlugin } from '../plugin.js';
+export type { ResolvedEntity, VersionBody, VersionRetentionDedupCursor, VersionRetentionDedupMode, VersionRetentionDedupOptions, VersionRetentionJanitorInput, VersionRetentionJanitorOptions, VersionRetentionJanitorOutput, VersionRetentionOverride, VersionRetentionPluginOptions, VersionRetentionScheduleConfig, VersionRow, } from '../types.js';

package/dist/exports/index.js

@@ -0,0 +1 @@
+export { versionRetentionPlugin } from '../plugin.js';

package/dist/hooks/dedup-versions.d.ts

@@ -0,0 +1,28 @@
+import type { CollectionAfterChangeHook } from 'payload';
+/**
+ * **Experimental — `dedup: { mode: 'onSave' }` only, off by default.**
+ *
+ * Collapses a version row that is byte-identical to the one before it, at
+ * write time. Runs `afterChange`, which Payload invokes after `saveVersion`,
+ * so the row this write produced already exists and is the newest. When it
+ * matches its predecessor, the predecessor is re-flagged `latest: true` and
+ * the newer row is deleted — keeping the earlier `createdAt` (the moment the
+ * content actually first appeared) and the earlier `updatedAt` (so a no-op
+ * save does not silently reset the retention window).
+ *
+ * Why it is not the default, and why `mode: 'sweep'` is:
+ *
+ * - it runs **inside the editor's save transaction**. Catching an error here
+ *   does not make the hook non-fatal: in Postgres a failed statement aborts
+ *   the surrounding transaction (25P02), so every later statement in the save
+ *   fails and the editor sees a cryptic error from an unrelated place;
+ * - it reads two full version bodies on every single save of every tracked
+ *   document, on the write path;
+ * - a mistake in the re-flag payload rewrites the survivor row through the
+ *   full `upsertRow` path — delete + reinsert of its `_locales`, block and
+ *   relationship rows — inside that same transaction.
+ *
+ * The sweep does the same work off the write path, where a failure costs a
+ * log line instead of an editor's save.
+ */
+export declare function createDedupVersionsHook(slug: string): CollectionAfterChangeHook;

package/dist/hooks/dedup-versions.js

@@ -0,0 +1,123 @@
+import { AI_TRANSLATE_RUN_CONTEXT_KEY, LOG_PREFIX } from '../defaults.js';
+import { sameStatus } from '../lib/retention-plan.js';
+import { versionBodiesMatch } from '../lib/snapshot-compare.js';
+import { toVersionRows } from '../lib/version-row.js';
+/**
+ * A version row this hook refuses to touch.
+ *
+ * Autosave rows carry an `autosave` column that `UpdateVersionArgs` has no
+ * slot for, so rewriting one to restore `latest` would clear the flag. They
+ * are also Payload's own churn-management path and already collapse into a
+ * single row per editing session.
+ */ function isAutosave(row) {
+    return row.autosave === true;
+}
+/**
+ * **Experimental — `dedup: { mode: 'onSave' }` only, off by default.**
+ *
+ * Collapses a version row that is byte-identical to the one before it, at
+ * write time. Runs `afterChange`, which Payload invokes after `saveVersion`,
+ * so the row this write produced already exists and is the newest. When it
+ * matches its predecessor, the predecessor is re-flagged `latest: true` and
+ * the newer row is deleted — keeping the earlier `createdAt` (the moment the
+ * content actually first appeared) and the earlier `updatedAt` (so a no-op
+ * save does not silently reset the retention window).
+ *
+ * Why it is not the default, and why `mode: 'sweep'` is:
+ *
+ * - it runs **inside the editor's save transaction**. Catching an error here
+ *   does not make the hook non-fatal: in Postgres a failed statement aborts
+ *   the surrounding transaction (25P02), so every later statement in the save
+ *   fails and the editor sees a cryptic error from an unrelated place;
+ * - it reads two full version bodies on every single save of every tracked
+ *   document, on the write path;
+ * - a mistake in the re-flag payload rewrites the survivor row through the
+ *   full `upsertRow` path — delete + reinsert of its `_locales`, block and
+ *   relationship rows — inside that same transaction.
+ *
+ * The sweep does the same work off the write path, where a failure costs a
+ * log line instead of an editor's save.
+ */ export function createDedupVersionsHook(slug) {
+    return async ({ doc, req })=>{
+        // ai-translate collapses a whole translation run into one version row of
+        // its own; a second opinion from here would fight that bookkeeping.
+        if (req.context?.[AI_TRANSLATE_RUN_CONTEXT_KEY] !== undefined) {
+            return doc;
+        }
+        const parentId = doc?.id;
+        if (typeof parentId !== 'number' && typeof parentId !== 'string') {
+            return doc;
+        }
+        try {
+            const { docs } = await req.payload.db.findVersions({
+                collection: slug,
+                limit: 2,
+                pagination: false,
+                req,
+                sort: '-updatedAt',
+                where: {
+                    parent: {
+                        equals: parentId
+                    }
+                }
+            });
+            const [newer, older] = toVersionRows(docs);
+            if (!(newer && older)) {
+                return doc;
+            }
+            if (isAutosave(newer) || isAutosave(older)) {
+                return doc;
+            }
+            // A publish that follows a byte-identical draft must keep both rows:
+            // they are the same content in two different states, and dropping one
+            // loses either the draft or the publish.
+            if (!sameStatus(newer.version, older.version)) {
+                return doc;
+            }
+            if (!versionBodiesMatch(newer.version, older.version)) {
+                return doc;
+            }
+            // `createVersion` clears `latest` on every other row when it inserts,
+            // so deleting the row it just flagged would leave the document with
+            // none — and `getLatestCollectionVersion` resolves the admin view from
+            // exactly that flag.
+            //
+            // Order matters: flag the survivor FIRST, delete second. Both statements
+            // run on the write's `req`, so they share its transaction and normally
+            // commit together; if the pair is ever torn (a non-transactional req, a
+            // connection lost between the two), the failure mode is two rows briefly
+            // flagged `latest` — which resolves to the newest of two identical
+            // bodies — rather than zero, which would blank the document in admin.
+            if (newer.latest === true) {
+                // ONLY `latest`. Drizzle's `shouldUseOptimizedUpsertRow` then takes
+                // the plain `UPDATE ... SET latest` path; adding `version`, `parent`
+                // or `createdAt` would rewrite the entire row, deleting and
+                // reinserting its `_locales`, block and relationship rows inside the
+                // editor's own transaction.
+                await req.payload.db.updateVersion({
+                    collection: slug,
+                    id: older.id,
+                    req,
+                    versionData: {
+                        latest: true
+                    }
+                });
+            }
+            await req.payload.db.deleteVersions({
+                collection: slug,
+                req,
+                where: {
+                    id: {
+                        equals: newer.id
+                    }
+                }
+            });
+            req.payload.logger.debug(`${LOG_PREFIX} ${slug} ${String(parentId)}: collapsed a version identical to its ` + 'predecessor');
+        } catch (error) {
+            req.payload.logger.error({
+                err: error
+            }, `${LOG_PREFIX} ${slug} ${String(parentId)}: identical-snapshot dedup failed; the ` + 'duplicate version row was left in place.');
+        }
+        return doc;
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { versionRetentionPlugin } from './plugin.js';
+export type { ResolvedEntity, VersionBody, VersionRetentionDedupCursor, VersionRetentionDedupMode, VersionRetentionDedupOptions, VersionRetentionJanitorInput, VersionRetentionJanitorOptions, VersionRetentionJanitorOutput, VersionRetentionOverride, VersionRetentionPluginOptions, VersionRetentionScheduleConfig, VersionRow, } from './types.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { versionRetentionPlugin } from './plugin.js';

package/dist/lib/dedup-cursor.d.ts

@@ -0,0 +1,34 @@
+import type { PayloadRequest } from 'payload';
+import type { VersionRetentionDedupCursor, VersionRetentionJanitorInput } from '../types.js';
+/**
+ * Narrows a stored value to a dedup cursor, or `undefined` when it is not one.
+ *
+ * Anything unrecognised — including the `slug -> parentId` map an older
+ * version of this plugin wrote — restarts the cycle from the beginning, which
+ * is always safe.
+ */
+export declare function toDedupCursor(value: unknown): undefined | VersionRetentionDedupCursor;
+/** Digs the janitor's `dedupCursor` out of a finished job document. */
+export declare function readCursorFromJob(job: unknown): undefined | VersionRetentionDedupCursor;
+/**
+ * **Legacy fallback only.** The dedup resume point left in the last completed
+ * janitor job's output.
+ *
+ * The cursor lives in the plugin's own state global now, because Payload's
+ * `deleteJobOnComplete` defaults to `true` and hard deletes the job row the
+ * moment it finishes — so under the default configuration there is usually
+ * nothing here to read. It is still consulted for consumers who turned job
+ * deletion off and have a cursor from an earlier version of this plugin.
+ *
+ * Never throws: a consumer whose jobs collection is shaped differently, or who
+ * has pruned its history, simply starts from the beginning.
+ */
+export declare function readPreviousDedupCursor(req: PayloadRequest): Promise<undefined | VersionRetentionDedupCursor>;
+/**
+ * Narrows a task's `input` to the shape the janitor understands.
+ *
+ * An absent or empty cursor comes back as `undefined` rather than `{}`, so the
+ * handler can tell "no cursor was supplied" (a manual `payload.jobs.queue()`
+ * passes `input: {}`) from "the previous run finished its walk".
+ */
+export declare function toJanitorInput(input: unknown): VersionRetentionJanitorInput;

package/dist/lib/dedup-cursor.js

@@ -0,0 +1,94 @@
+import { JANITOR_TASK_SLUG, JOBS_COLLECTION_SLUG, LOG_PREFIX } from '../defaults.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Narrows a stored value to a dedup cursor, or `undefined` when it is not one.
+ *
+ * Anything unrecognised — including the `slug -> parentId` map an older
+ * version of this plugin wrote — restarts the cycle from the beginning, which
+ * is always safe.
+ */ export function toDedupCursor(value) {
+    if (!isRecord(value) || typeof value.slug !== 'string' || value.slug.length === 0) {
+        return undefined;
+    }
+    const { parentId } = value;
+    return typeof parentId === 'number' || typeof parentId === 'string' ? {
+        parentId,
+        slug: value.slug
+    } : {
+        slug: value.slug
+    };
+}
+/** Digs the janitor's `dedupCursor` out of a finished job document. */ export function readCursorFromJob(job) {
+    if (!isRecord(job)) {
+        return undefined;
+    }
+    const log = Array.isArray(job.log) ? job.log : [];
+    for(let index = log.length - 1; index >= 0; index--){
+        const entry = log[index];
+        if (isRecord(entry) && entry.taskSlug === JANITOR_TASK_SLUG && isRecord(entry.output)) {
+            return toDedupCursor(entry.output.dedupCursor);
+        }
+    }
+    return undefined;
+}
+/**
+ * **Legacy fallback only.** The dedup resume point left in the last completed
+ * janitor job's output.
+ *
+ * The cursor lives in the plugin's own state global now, because Payload's
+ * `deleteJobOnComplete` defaults to `true` and hard deletes the job row the
+ * moment it finishes — so under the default configuration there is usually
+ * nothing here to read. It is still consulted for consumers who turned job
+ * deletion off and have a cursor from an earlier version of this plugin.
+ *
+ * Never throws: a consumer whose jobs collection is shaped differently, or who
+ * has pruned its history, simply starts from the beginning.
+ */ export async function readPreviousDedupCursor(req) {
+    try {
+        const { docs } = await req.payload.find({
+            collection: JOBS_COLLECTION_SLUG,
+            depth: 0,
+            limit: 1,
+            overrideAccess: true,
+            pagination: false,
+            sort: '-completedAt',
+            where: {
+                and: [
+                    {
+                        taskSlug: {
+                            equals: JANITOR_TASK_SLUG
+                        }
+                    },
+                    {
+                        completedAt: {
+                            exists: true
+                        }
+                    }
+                ]
+            }
+        });
+        return readCursorFromJob(docs[0]);
+    } catch (error) {
+        req.payload.logger.warn({
+            err: error
+        }, `${LOG_PREFIX} Could not read the previous run's dedup cursor; starting from the ` + 'beginning. Dedup still runs, it just re-reads documents it may have already seen.');
+        return undefined;
+    }
+}
+/**
+ * Narrows a task's `input` to the shape the janitor understands.
+ *
+ * An absent or empty cursor comes back as `undefined` rather than `{}`, so the
+ * handler can tell "no cursor was supplied" (a manual `payload.jobs.queue()`
+ * passes `input: {}`) from "the previous run finished its walk".
+ */ export function toJanitorInput(input) {
+    if (!isRecord(input)) {
+        return {};
+    }
+    const dedupCursor = toDedupCursor(input.dedupCursor);
+    return dedupCursor === undefined ? {} : {
+        dedupCursor
+    };
+}

package/dist/lib/entities.d.ts

@@ -0,0 +1,43 @@
+import type { ResolvedEntity, VersionRetentionDedupMode, VersionRetentionPluginOptions } from '../types.js';
+/**
+ * The shape both the incoming (`Config`) and the sanitized (`payload.config`)
+ * entity carry. Payload's own configs are structurally assignable to this;
+ * declaring it here keeps the resolver testable without a real config.
+ */
+export interface VersionedEntityConfig {
+    slug: string;
+    versions?: unknown;
+}
+/**
+ * True when the entity keeps versions at all. Incoming configs may carry
+ * `versions: true`; sanitize rewrites that to an object and deletes the key
+ * when versions are off, so both forms have to be handled.
+ */
+export declare function hasVersionsEnabled(entity: VersionedEntityConfig): boolean;
+/**
+ * True when the entity has drafts, which is what puts `_status` into the
+ * version body. `versions: true` (the shorthand) means versions without
+ * drafts. Mirrors Payload's own `hasDraftsEnabled`.
+ */
+export declare function hasDraftsEnabled(entity: VersionedEntityConfig): boolean;
+/** Where dedup runs, with `true`/`false` normalised to a mode. */
+export declare function resolveDedupMode(options: VersionRetentionPluginOptions): VersionRetentionDedupMode;
+/** Ceiling on version bodies the sweep may read for dedup in one run. */
+export declare function resolveMaxDedupBodies(options: VersionRetentionPluginOptions): number;
+/**
+ * Every versioned collection the janitor should sweep, with the retention
+ * window that applies to it.
+ */
+export declare function resolveVersionedCollections(collections: VersionedEntityConfig[], options: VersionRetentionPluginOptions): ResolvedEntity[];
+/** Every versioned global the janitor should sweep. */
+export declare function resolveVersionedGlobals(globals: VersionedEntityConfig[], options: VersionRetentionPluginOptions): ResolvedEntity[];
+/**
+ * Collections that get the experimental on-save dedup hook: versioned,
+ * selected, drafts enabled, and not opted out per slug — and only when the
+ * consumer asked for `dedup: { mode: 'onSave' }`.
+ *
+ * Without drafts there is no `_status`, every save is the same kind of row and
+ * the janitor's sweep is the right tool — the hook would only add a read to
+ * every write.
+ */
+export declare function resolveOnSaveDedupCollections(collections: VersionedEntityConfig[], options: VersionRetentionPluginOptions): string[];

package/dist/lib/entities.js

@@ -0,0 +1,98 @@
+import { DEFAULT_DEDUP_MODE, DEFAULT_MAX_DEDUP_BODIES_PER_RUN, DEFAULT_MIN_VERSIONS_PER_DOCUMENT, DEFAULT_RETENTION_DAYS } from '../defaults.js';
+/**
+ * True when the entity keeps versions at all. Incoming configs may carry
+ * `versions: true`; sanitize rewrites that to an object and deletes the key
+ * when versions are off, so both forms have to be handled.
+ */ export function hasVersionsEnabled(entity) {
+    return Boolean(entity.versions);
+}
+/**
+ * True when the entity has drafts, which is what puts `_status` into the
+ * version body. `versions: true` (the shorthand) means versions without
+ * drafts. Mirrors Payload's own `hasDraftsEnabled`.
+ */ export function hasDraftsEnabled(entity) {
+    const { versions } = entity;
+    if (typeof versions !== 'object' || versions === null) {
+        return false;
+    }
+    return Boolean(versions.drafts);
+}
+function applyIncludeExclude(slugs, include, exclude) {
+    const included = include ? slugs.filter((slug)=>include.includes(slug)) : slugs;
+    if (!exclude?.length) {
+        return included;
+    }
+    return included.filter((slug)=>!exclude.includes(slug));
+}
+function daysFor(slug, options) {
+    return options.overrides?.[slug]?.days ?? options.days ?? DEFAULT_RETENTION_DAYS;
+}
+function minVersionsFor(slug, options) {
+    return options.overrides?.[slug]?.minVersionsPerDocument ?? options.minVersionsPerDocument ?? DEFAULT_MIN_VERSIONS_PER_DOCUMENT;
+}
+/** Where dedup runs, with `true`/`false` normalised to a mode. */ export function resolveDedupMode(options) {
+    const { dedup } = options;
+    if (dedup === undefined) {
+        return DEFAULT_DEDUP_MODE;
+    }
+    if (dedup === true) {
+        return 'sweep';
+    }
+    if (dedup === false) {
+        return 'off';
+    }
+    return dedup.mode ?? DEFAULT_DEDUP_MODE;
+}
+/** Ceiling on version bodies the sweep may read for dedup in one run. */ export function resolveMaxDedupBodies(options) {
+    const { dedup } = options;
+    if (typeof dedup === 'object' && dedup.maxDedupBodiesPerRun !== undefined) {
+        return dedup.maxDedupBodiesPerRun;
+    }
+    return DEFAULT_MAX_DEDUP_BODIES_PER_RUN;
+}
+function dedupFor(slug, options) {
+    return resolveDedupMode(options) === 'sweep' && options.overrides?.[slug]?.dedup !== false;
+}
+/**
+ * Every versioned collection the janitor should sweep, with the retention
+ * window that applies to it.
+ */ export function resolveVersionedCollections(collections, options) {
+    const versioned = collections.filter(hasVersionsEnabled);
+    const selected = applyIncludeExclude(versioned.map((collection)=>collection.slug), options.collections, options.excludeCollections);
+    return versioned.filter((collection)=>selected.includes(collection.slug)).map((collection)=>({
+            days: daysFor(collection.slug, options),
+            dedup: dedupFor(collection.slug, options),
+            hasDrafts: hasDraftsEnabled(collection),
+            minVersionsPerDocument: minVersionsFor(collection.slug, options),
+            slug: collection.slug
+        }));
+}
+/** Every versioned global the janitor should sweep. */ export function resolveVersionedGlobals(globals, options) {
+    const versioned = globals.filter(hasVersionsEnabled);
+    const selected = applyIncludeExclude(versioned.map((global)=>global.slug), options.globals, options.excludeGlobals);
+    return versioned.filter((global)=>selected.includes(global.slug)).map((global)=>({
+            days: daysFor(global.slug, options),
+            dedup: dedupFor(global.slug, options),
+            hasDrafts: hasDraftsEnabled(global),
+            minVersionsPerDocument: minVersionsFor(global.slug, options),
+            slug: global.slug
+        }));
+}
+/**
+ * Collections that get the experimental on-save dedup hook: versioned,
+ * selected, drafts enabled, and not opted out per slug — and only when the
+ * consumer asked for `dedup: { mode: 'onSave' }`.
+ *
+ * Without drafts there is no `_status`, every save is the same kind of row and
+ * the janitor's sweep is the right tool — the hook would only add a read to
+ * every write.
+ */ export function resolveOnSaveDedupCollections(collections, options) {
+    if (resolveDedupMode(options) !== 'onSave') {
+        return [];
+    }
+    const draftsBySlug = new Map(collections.map((collection)=>[
+            collection.slug,
+            hasDraftsEnabled(collection)
+        ]));
+    return resolveVersionedCollections(collections, options).filter((entity)=>draftsBySlug.get(entity.slug) === true).filter((entity)=>options.overrides?.[entity.slug]?.dedup !== false).map((entity)=>entity.slug);
+}

package/dist/lib/retention-plan.d.ts

@@ -0,0 +1,72 @@
+import type { RetentionCandidate, VersionBody, VersionRow } from '../types.js';
+/**
+ * The `_status` values Payload writes into a version body when drafts are on.
+ * Anything else (a custom status, or no `_status` at all on a drafts-less
+ * entity) is not separately protected.
+ */
+export declare const PROTECTED_STATUSES: readonly ["published", "draft"];
+export type ProtectedStatus = (typeof PROTECTED_STATUSES)[number];
+/**
+ * The raw `_status` value, whatever shape it has.
+ *
+ * With `drafts.localizeStatus` Payload writes an **object** keyed by locale
+ * (`{ en: 'published', de: 'draft' }`) rather than a string, so this cannot be
+ * narrowed to `string` — use `hasStatus` / `sameStatus` instead of comparing
+ * the return value directly.
+ */
+export declare function readStatus(version: undefined | VersionBody): unknown;
+/**
+ * True when the row carries `status` — as the plain string, or, under
+ * `localizeStatus`, for at least one locale.
+ *
+ * A row published in any locale still holds a publish worth protecting, so
+ * "any locale" is the right test for the protected rows.
+ */
+export declare function hasStatus(version: undefined | VersionBody, status: ProtectedStatus): boolean;
+/**
+ * True when two rows carry the same `_status`. Under `localizeStatus` that
+ * means the same status in every locale, so publishing one locale never looks
+ * like a no-op against a draft of another.
+ */
+export declare function sameStatus(a: undefined | VersionBody, b: undefined | VersionBody): boolean;
+/** Narrows a raw version row to the facts the plan is built from. */
+export declare function toCandidate(row: VersionRow): RetentionCandidate;
+/**
+ * The rows a retention pass must never delete, whatever their age:
+ *
+ * - the row flagged `latest: true` — the one `getLatestCollectionVersion`
+ *   resolves the admin document from;
+ * - the newest non-snapshot published row — **the last good publish**, which a
+ *   count cap happily evicts and this plugin does not;
+ * - the newest non-snapshot draft row — the work in progress;
+ * - the newest row overall, when none of the above matched (an entity with
+ *   versions but no drafts has no `_status` at all).
+ *
+ * Snapshot rows are Payload's pre-publish copies. The admin hides them, so
+ * they are never chosen as the protected publish or draft — but a snapshot row
+ * that somehow carries `latest` is still protected by the first rule.
+ */
+export declare function collectProtectedIds(candidates: RetentionCandidate[]): Set<number | string>;
+/**
+ * Ids of the version rows that are both older than the cutoff and unprotected,
+ * minus whatever the floor holds back — **oldest first**.
+ *
+ * The order is load-bearing: when the caller truncates the plan to fit a
+ * per-run deletion budget it takes a prefix, and the oldest rows are the ones
+ * that should go first.
+ *
+ * Age is read from the version row's own `updatedAt`, the same column
+ * Payload's `enforceMaxVersions` orders by.
+ *
+ * `minVersions` is the floor on rows left behind for this document. On the
+ * wild copy most `pages` documents have their *entire* history older than 30
+ * days, so age alone would leave them with a single row; the floor keeps a
+ * usable tail. Only non-snapshot rows count toward it (the admin hides the
+ * others), the protected rows count toward it, and the rows held back to reach
+ * it are the newest of the deletable ones.
+ */
+export declare function planVersionDeletions(candidates: RetentionCandidate[], cutoff: Date, minVersions?: number): (number | string)[];
+/** `now` minus `days`, as the exclusive upper bound on a deletable row's age. */
+export declare function retentionCutoff(days: number, now?: Date): Date;
+/** Splits ids into `IN (...)`-sized chunks. */
+export declare function chunkIds<T>(ids: T[], size: number): T[][];