@purposeinplay/payload-version-retention 0.1.1

package/dist/lib/retention-plan.js

@@ -0,0 +1,158 @@
+import { deepEqual } from './snapshot-compare.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 const PROTECTED_STATUSES = [
+    'published',
+    'draft'
+];
+/**
+ * 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 function readStatus(version) {
+    return version?._status;
+}
+/**
+ * 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 function hasStatus(version, status) {
+    const raw = readStatus(version);
+    if (typeof raw === 'string') {
+        return raw === status;
+    }
+    if (typeof raw === 'object' && raw !== null && !Array.isArray(raw)) {
+        return Object.values(raw).includes(status);
+    }
+    return false;
+}
+/**
+ * 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 function sameStatus(a, b) {
+    return deepEqual(readStatus(a), readStatus(b));
+}
+/** Narrows a raw version row to the facts the plan is built from. */ export function toCandidate(row) {
+    return {
+        id: row.id,
+        isDraft: hasStatus(row.version, 'draft'),
+        isPublished: hasStatus(row.version, 'published'),
+        latest: row.latest === true,
+        snapshot: row.snapshot === true,
+        updatedAt: row.updatedAt
+    };
+}
+function sortNewestFirst(candidates) {
+    return [
+        ...candidates
+    ].sort((a, b)=>new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+}
+/**
+ * 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 function collectProtectedIds(candidates) {
+    const protectedIds = new Set();
+    if (candidates.length === 0) {
+        return protectedIds;
+    }
+    const newestFirst = sortNewestFirst(candidates);
+    const visible = newestFirst.filter((candidate)=>!candidate.snapshot);
+    const latest = newestFirst.find((candidate)=>candidate.latest);
+    if (latest) {
+        protectedIds.add(latest.id);
+    }
+    const newestPublished = visible.find((candidate)=>candidate.isPublished);
+    if (newestPublished) {
+        protectedIds.add(newestPublished.id);
+    }
+    const newestDraft = visible.find((candidate)=>candidate.isDraft);
+    if (newestDraft) {
+        protectedIds.add(newestDraft.id);
+    }
+    // Never leave a document with zero versions. Reached when the entity has no
+    // drafts and nothing carries `latest` — the newest visible row stands in, or
+    // the newest row of any kind if every row is a snapshot.
+    if (protectedIds.size === 0) {
+        const newest = visible[0] ?? newestFirst[0];
+        if (newest) {
+            protectedIds.add(newest.id);
+        }
+    }
+    return protectedIds;
+}
+/**
+ * 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 function planVersionDeletions(candidates, cutoff, minVersions = 0) {
+    if (candidates.length <= 1) {
+        return [];
+    }
+    const protectedIds = collectProtectedIds(candidates);
+    const cutoffMs = cutoff.getTime();
+    const deletable = sortNewestFirst(candidates).filter((candidate)=>{
+        if (protectedIds.has(candidate.id)) {
+            return false;
+        }
+        const updatedAtMs = new Date(candidate.updatedAt).getTime();
+        // An unparseable timestamp must not read as "infinitely old".
+        return Number.isFinite(updatedAtMs) && updatedAtMs < cutoffMs;
+    });
+    const visibleTotal = candidates.filter((candidate)=>!candidate.snapshot).length;
+    const visibleDeletable = deletable.filter((candidate)=>!candidate.snapshot).length;
+    let shortfall = Math.max(0, minVersions - (visibleTotal - visibleDeletable));
+    // `deletable` is newest-first, so walking from the head holds back the
+    // newest rows — and only visible ones count against the floor.
+    const doomed = deletable.filter((candidate)=>{
+        if (shortfall > 0 && !candidate.snapshot) {
+            shortfall--;
+            return false;
+        }
+        return true;
+    });
+    return doomed.map((candidate)=>candidate.id).reverse();
+}
+/** `now` minus `days`, as the exclusive upper bound on a deletable row's age. */ export function retentionCutoff(days, now = new Date()) {
+    const cutoff = new Date(now.getTime());
+    cutoff.setDate(cutoff.getDate() - days);
+    return cutoff;
+}
+/** Splits ids into `IN (...)`-sized chunks. */ export function chunkIds(ids, size) {
+    const chunks = [];
+    for(let index = 0; index < ids.length; index += size){
+        chunks.push(ids.slice(index, index + size));
+    }
+    return chunks;
+}

package/dist/lib/run-lock.d.ts

@@ -0,0 +1,25 @@
+import type { PayloadRequest } from 'payload';
+export interface RunLockArgs {
+    now?: Date;
+    ownJob: unknown;
+    req: PayloadRequest;
+    /** Age past which a `processing` job is treated as debris. */
+    ttlMs: number;
+}
+/**
+ * True when another janitor job is genuinely still running.
+ *
+ * Two janitors at once would split the run budget between them and race each
+ * other for the dedup cursor, with the loser's position overwriting the
+ * winner's — easy to hit by queueing one by hand while the schedule fires.
+ * Cheaper to skip the second than to make the pass reentrant.
+ *
+ * The lock is **time-bounded**, and that is the important part. Payload sets
+ * `processing` when a job starts and never clears it if the process dies —
+ * nothing in its queue code sweeps abandoned jobs — so an unbounded lock turns
+ * one OOM into a janitor that never runs again. A `processing` row older than
+ * `ttlMs` is therefore ignored, loudly.
+ *
+ * Never throws: if the jobs collection cannot be read, the run proceeds.
+ */
+export declare function anotherJanitorIsRunning({ now, ownJob, req, ttlMs, }: RunLockArgs): Promise<boolean>;

package/dist/lib/run-lock.js

@@ -0,0 +1,105 @@
+import { JANITOR_TASK_SLUG, JOBS_COLLECTION_SLUG, LOG_PREFIX } from '../defaults.js';
+function idOf(value) {
+    if (typeof value === 'number' || typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'object' && value !== null && 'id' in value) {
+        const { id } = value;
+        return typeof id === 'number' || typeof id === 'string' ? id : undefined;
+    }
+    return undefined;
+}
+/** Most recent sign of life on a job row. */ function lastSeen(job) {
+    if (typeof job !== 'object' || job === null) {
+        return Number.NaN;
+    }
+    const record = job;
+    for (const value of [
+        record.updatedAt,
+        record.createdAt
+    ]){
+        if (typeof value === 'string' || value instanceof Date) {
+            const time = new Date(value).getTime();
+            if (Number.isFinite(time)) {
+                return time;
+            }
+        }
+    }
+    return Number.NaN;
+}
+/**
+ * True when another janitor job is genuinely still running.
+ *
+ * Two janitors at once would split the run budget between them and race each
+ * other for the dedup cursor, with the loser's position overwriting the
+ * winner's — easy to hit by queueing one by hand while the schedule fires.
+ * Cheaper to skip the second than to make the pass reentrant.
+ *
+ * The lock is **time-bounded**, and that is the important part. Payload sets
+ * `processing` when a job starts and never clears it if the process dies —
+ * nothing in its queue code sweeps abandoned jobs — so an unbounded lock turns
+ * one OOM into a janitor that never runs again. A `processing` row older than
+ * `ttlMs` is therefore ignored, loudly.
+ *
+ * Never throws: if the jobs collection cannot be read, the run proceeds.
+ */ export async function anotherJanitorIsRunning({ now = new Date(), ownJob, req, ttlMs }) {
+    const ownId = idOf(ownJob);
+    try {
+        const { docs } = await req.payload.find({
+            collection: JOBS_COLLECTION_SLUG,
+            depth: 0,
+            limit: 10,
+            overrideAccess: true,
+            pagination: false,
+            select: {
+                createdAt: true,
+                updatedAt: true
+            },
+            where: {
+                and: [
+                    {
+                        taskSlug: {
+                            equals: JANITOR_TASK_SLUG
+                        }
+                    },
+                    {
+                        processing: {
+                            equals: true
+                        }
+                    },
+                    ...ownId === undefined ? [] : [
+                        {
+                            id: {
+                                not_equals: ownId
+                            }
+                        }
+                    ]
+                ]
+            }
+        });
+        if (docs.length === 0) {
+            return false;
+        }
+        const staleBefore = now.getTime() - ttlMs;
+        // A row with no readable timestamp is treated as live: refusing to run is
+        // recoverable, two concurrent janitors are messier.
+        const live = docs.filter((job)=>{
+            const seen = lastSeen(job);
+            return !Number.isFinite(seen) || seen > staleBefore;
+        });
+        const stale = docs.length - live.length;
+        if (stale > 0) {
+            req.payload.logger.warn(`${LOG_PREFIX} Ignoring ${stale} \`${JANITOR_TASK_SLUG}\` job(s) still marked ` + `\`processing\` after ${Math.round(ttlMs / 60_000)} minutes — Payload never clears ` + 'that flag when a run dies, so they are treated as debris from a crash.');
+        }
+        if (live.length === 0) {
+            return false;
+        }
+        req.payload.logger.warn(`${LOG_PREFIX} Another \`${JANITOR_TASK_SLUG}\` job is already processing; skipping this ` + 'run so the two do not split the budget or fight over the dedup cursor.');
+        return true;
+    } catch (error) {
+        req.payload.logger.warn({
+            err: error
+        }, `${LOG_PREFIX} Could not check for a concurrent janitor run; proceeding.`);
+        return false;
+    }
+}

package/dist/lib/snapshot-compare.d.ts

@@ -0,0 +1,37 @@
+import type { VersionBody } from '../types.js';
+/**
+ * Keys stripped from the *top level* of a version body before comparing.
+ *
+ * - `createdAt` / `updatedAt` — Payload backfills these into the body from the
+ *   version row (see `getLatestGlobalVersion`), and the document row's
+ *   `updatedAt` is bumped on every save. They differ between two consecutive
+ *   saves even when nothing the editor typed changed.
+ * - `id` — the parent document id, identical for both rows by construction;
+ *   stripping it keeps the comparison about content only.
+ *
+ * Nothing else is stripped. In particular:
+ *
+ * - `_status` stays in. The hook refuses to compare across differing statuses
+ *   before it gets here, so leaving `_status` in the body is a second line of
+ *   defence: a publish that follows a byte-identical draft keeps both rows.
+ * - Nested `id` / `updatedAt` / `createdAt` (array rows, blocks, a relationship
+ *   embedded at depth > 0) are left alone. The comparison runs on the
+ *   assembled `version` object `findVersions` returns at depth 0, where blocks
+ *   arrive as nested arrays with their own stable row ids and relationships
+ *   are plain ids — there are no adapter-side `_path` columns to see, so
+ *   nothing there is treated as noise.
+ */
+export declare const NOISE_KEYS: readonly string[];
+/** A copy of the body without the top-level noise keys. */
+export declare function normalizeVersionBody(body: VersionBody): VersionBody;
+/**
+ * Structural equality for version bodies. Dates are compared by instant so a
+ * `Date` and its ISO string do not read as different; everything else is
+ * compared by value, recursively.
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * True when two version bodies carry the same content once the documented
+ * noise keys are removed.
+ */
+export declare function versionBodiesMatch(a: VersionBody | undefined, b: VersionBody | undefined): boolean;

package/dist/lib/snapshot-compare.js

@@ -0,0 +1,86 @@
+/**
+ * Keys stripped from the *top level* of a version body before comparing.
+ *
+ * - `createdAt` / `updatedAt` — Payload backfills these into the body from the
+ *   version row (see `getLatestGlobalVersion`), and the document row's
+ *   `updatedAt` is bumped on every save. They differ between two consecutive
+ *   saves even when nothing the editor typed changed.
+ * - `id` — the parent document id, identical for both rows by construction;
+ *   stripping it keeps the comparison about content only.
+ *
+ * Nothing else is stripped. In particular:
+ *
+ * - `_status` stays in. The hook refuses to compare across differing statuses
+ *   before it gets here, so leaving `_status` in the body is a second line of
+ *   defence: a publish that follows a byte-identical draft keeps both rows.
+ * - Nested `id` / `updatedAt` / `createdAt` (array rows, blocks, a relationship
+ *   embedded at depth > 0) are left alone. The comparison runs on the
+ *   assembled `version` object `findVersions` returns at depth 0, where blocks
+ *   arrive as nested arrays with their own stable row ids and relationships
+ *   are plain ids — there are no adapter-side `_path` columns to see, so
+ *   nothing there is treated as noise.
+ */ export const NOISE_KEYS = [
+    'createdAt',
+    'id',
+    'updatedAt'
+];
+/** A copy of the body without the top-level noise keys. */ export function normalizeVersionBody(body) {
+    const normalized = {};
+    for (const [key, value] of Object.entries(body)){
+        if (NOISE_KEYS.includes(key)) {
+            continue;
+        }
+        normalized[key] = value;
+    }
+    return normalized;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Keys with an `undefined` value are treated as absent: a JSON column
+ * round-trips a missing key and an explicit `undefined` identically, so
+ * counting them as a difference would suppress every legitimate dedup.
+ */ function definedKeys(value) {
+    return Object.keys(value).filter((key)=>value[key] !== undefined);
+}
+/**
+ * Structural equality for version bodies. Dates are compared by instant so a
+ * `Date` and its ISO string do not read as different; everything else is
+ * compared by value, recursively.
+ */ export function deepEqual(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (a instanceof Date || b instanceof Date) {
+        const aTime = a instanceof Date ? a.getTime() : new Date(String(a)).getTime();
+        const bTime = b instanceof Date ? b.getTime() : new Date(String(b)).getTime();
+        return Number.isFinite(aTime) && Number.isFinite(bTime) && aTime === bTime;
+    }
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!(Array.isArray(a) && Array.isArray(b)) || a.length !== b.length) {
+            return false;
+        }
+        return a.every((item, index)=>deepEqual(item, b[index]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const aKeys = definedKeys(a).sort();
+        const bKeys = definedKeys(b).sort();
+        if (aKeys.length !== bKeys.length || aKeys.some((key, index)=>key !== bKeys[index])) {
+            return false;
+        }
+        return aKeys.every((key)=>deepEqual(a[key], b[key]));
+    }
+    // Mixed primitive types, functions, symbols: only reference equality would
+    // have matched, and that was checked first.
+    return false;
+}
+/**
+ * True when two version bodies carry the same content once the documented
+ * noise keys are removed.
+ */ export function versionBodiesMatch(a, b) {
+    if (!(a && b)) {
+        return false;
+    }
+    return deepEqual(normalizeVersionBody(a), normalizeVersionBody(b));
+}

package/dist/lib/startup-checks.d.ts

@@ -0,0 +1,55 @@
+import type { Payload } from 'payload';
+/**
+ * Slug of the global Payload injects into the config as soon as any task or
+ * workflow declares a `schedule` (`jobs.scheduling` is flipped on during
+ * config sanitization). Its table is `payload_jobs_stats`.
+ */
+export declare const JOB_STATS_GLOBAL_SLUG = "payload-jobs-stats";
+/**
+ * Startup probe for the jobs-stats table. Logs an error and resolves `false`
+ * when the global cannot be read; never throws and never creates tables.
+ */
+export declare function checkJobStatsTable(payload: Payload): Promise<boolean>;
+/**
+ * Probe for the `payload_jobs.meta` column. Selecting the field is enough — the
+ * adapter names the column in the query, so a missing one throws. No raw SQL.
+ */
+export declare function checkJobsMetaColumn(payload: Payload): Promise<boolean>;
+/**
+ * Startup probe for the plugin's own state table. Logs an error and resolves
+ * `false` when the global cannot be read; never throws.
+ */
+export declare function checkStateGlobal(payload: Payload): Promise<boolean>;
+/** The two enums Payload derives from the registered task slugs on Postgres. */
+export declare const TASK_SLUG_ENUMS: readonly ["enum_payload_jobs_task_slug", "enum_payload_jobs_log_task_slug"];
+/**
+ * Verifies the janitor's slug is a member of both jobs task-slug enums.
+ *
+ * Postgres only, and only when the adapter exposes a pool — every other
+ * adapter stores the slug as text, and an adapter this cannot inspect is left
+ * alone rather than warned about. Logs an error and resolves `false` when the
+ * slug is missing; never throws.
+ */
+export declare function checkTaskSlugEnum(payload: Payload): Promise<boolean>;
+/**
+ * Warns when nothing in `jobs.autoRun` drains a queue the plugin schedules onto.
+ * `handleSchedules` silently skips every queue the running autoRun entry does
+ * not name (unless it sets `allQueues`), so a schedule on an undrained queue
+ * never fires and produces no error of its own.
+ *
+ * A warning, not an error: the consumer may instead run a dedicated worker with
+ * `payload jobs:run --handle-schedules`, which this cannot see. Returns false
+ * when a warning was emitted.
+ */
+export declare function checkScheduleIsDrained(payload: Payload, scheduledQueues: string[]): boolean;
+/**
+ * The boot-time checks that only matter once a schedule exists. The state
+ * global is checked separately, because a manually queued janitor needs it
+ * just as much. Logs; never throws.
+ */
+export declare function runSchedulingStartupChecks(payload: Payload, scheduledQueues: string[]): Promise<void>;
+/**
+ * One-liner for `janitor: { schedule: [] }` — the task is registered but
+ * nothing will ever queue it, which is easy to reach by accident.
+ */
+export declare function warnScheduleDisabled(payload: Payload): void;