@cogenta/schema 0.1.2 → 0.2.0

package/dist/store/store.js

@@ -1,5 +1,6 @@
 import { CogentaError, identifier, sql, limit as sqlLimit, } from '@cogenta/core';
 import { newId as uuidv7 } from '../id.js';
+import { DEFAULT_TRASH_RETAIN_DAYS, } from '../types.js';
 import { isColumnless } from './columns.js';
 import { decodeCursor, encodeCursor } from './cursor.js';
 import { diffContent } from './diff.js';
@@ -12,6 +13,7 @@ const MAX_PAGE_SIZE = 200;
 const DEFAULT_SORT = { field: 'id', direction: 'desc' };
 /** Enough history to answer "what changed last week" without unbounded growth. */
 const DEFAULT_KEEP = 20;
+const DAY_MS = 24 * 60 * 60 * 1000;
 const SORT_COLUMNS = { id: 'id', createdAt: 'created_at', updatedAt: 'updated_at' };
 function notFound(collection, id) {
     return new CogentaError({
@@ -43,7 +45,100 @@ export function createContentStore(options) {
         .map(([name]) => name);
     const keep = Math.max(2, collection.versioning?.history === true ? (collection.versioning.keep ?? DEFAULT_KEEP) : 2);
     const draftsEnabled = collection.versioning?.drafts === true;
+    /** `trash: false` opts back out; absent means the default window is on. */
+    const trashEnabled = collection.trash !== false;
+    const retainDays = collection.trash === false || collection.trash === undefined
+        ? DEFAULT_TRASH_RETAIN_DAYS
+        : collection.trash.retainDays;
     const stamp = () => now().toISOString();
+    // -------------------------------------------------------------- the trash
+    const deletedAt = identifier('deleted_at', dialect);
+    /**
+     * The one place the trash filter is spelled out.
+     *
+     * Returning `null` for `'include'` rather than a `1 = 1` fragment keeps the
+     * generated SQL identical to what it was before 2.0 whenever the caller
+     * wanted everything — nothing to explain in a query plan.
+     */
+    function trashPredicate(filter) {
+        const effective = filter ?? 'exclude';
+        if (effective === 'include')
+            return null;
+        return effective === 'only' ? sql `${deletedAt} is not null` : sql `${deletedAt} is null`;
+    }
+    function isTrashed(row) {
+        return row['deleted_at'] !== null && row['deleted_at'] !== undefined;
+    }
+    /** True when this row is invisible to a caller asking for `filter`. */
+    function hiddenBy(row, filter) {
+        const effective = filter ?? 'exclude';
+        if (effective === 'include')
+            return false;
+        return effective === 'only' ? !isTrashed(row) : isTrashed(row);
+    }
+    /**
+     * Every `restrict` relation pointing at this collection, from any collection
+     * the store was told about — including this one, whose self-references it
+     * would otherwise miss.
+     */
+    const restrictingRelations = (options.siblings ?? [collection]).flatMap((sibling) => relationsOf(sibling)
+        .filter((relation) => relation.kind === 'relation' &&
+        relation.to === collection.name &&
+        relation.onDelete === 'restrict')
+        .map((relation) => ({ sibling, relation })));
+    async function referencesTo(tx, id) {
+        const blocking = [];
+        for (const { sibling, relation } of restrictingRelations) {
+            const siblingEntries = identifier(entriesTable(sibling.name), dialect);
+            const count = relation.many
+                ? await countJoinReferences(tx, sibling, relation.field, siblingEntries, id)
+                : await countColumnReferences(tx, relation.field, siblingEntries, id);
+            if (count > 0) {
+                blocking.push({ collection: sibling.name, field: relation.field, count });
+            }
+        }
+        return blocking;
+    }
+    async function isReferenced(tx, id) {
+        return (await referencesTo(tx, id)).length > 0;
+    }
+    async function assertNotReferenced(tx, id) {
+        const blocking = await referencesTo(tx, id);
+        if (blocking.length === 0)
+            return;
+        const naming = blocking
+            .map(({ count, collection: name }) => `${count} ${count === 1 ? 'entry' : 'entries'} of "${name}"`)
+            .join(', ');
+        throw new CogentaError({
+            code: 'CONTENT_REFERENCED',
+            message: `"${id}" cannot be removed from "${collection.name}": ${naming} still reference it.`,
+            hint: "Point those entries somewhere else first, or declare the relation with onDelete: 'cascade' if losing them along with their target is really what you want.",
+            details: { collection: collection.name, id, blocking },
+        });
+    }
+    /** The real `DELETE`. Cascades take the versions, blocks and join rows. */
+    async function hardDelete(tx, id) {
+        const removed = await tx.query(sql `delete from ${entries} where ${identifier('id', dialect)} = ${id}`);
+        return removed.rowsAffected > 0;
+    }
+    async function countColumnReferences(tx, field, table, id) {
+        // A referrer that is itself in the trash does not block: it is not visible
+        // content any more, and blocking on it would make the trash a place
+        // entries can enter but never leave in the right order.
+        const found = await tx.query(sql `select ${identifier('id', dialect)} from ${table}
+          where ${identifier(columnFor(field), dialect)} = ${id}
+            and ${identifier('deleted_at', dialect)} is null`);
+        return found.rows.length;
+    }
+    async function countJoinReferences(tx, sibling, field, siblingEntries, id) {
+        const join = identifier(relationTable(sibling.name, field), dialect);
+        const found = await tx.query(sql `select ${join}.${identifier('entry_id', dialect)} from ${join}
+          join ${siblingEntries}
+            on ${siblingEntries}.${identifier('id', dialect)} = ${join}.${identifier('entry_id', dialect)}
+          where ${join}.${identifier('target_id', dialect)} = ${id}
+            and ${siblingEntries}.${identifier('deleted_at', dialect)} is null`);
+        return found.rows.length;
+    }
     // ---------------------------------------------------------------- reading
     async function loadRow(tx, id) {
         const found = await tx.query(sql `select * from ${entries} where ${identifier('id', dialect)} = ${id}`);
@@ -166,6 +261,7 @@ export function createContentStore(options) {
             createdBy: nullableText(row['created_by']),
             updatedBy: nullableText(row['updated_by']),
             status,
+            deletedAt: nullableText(row['deleted_at']),
             locale: text(row['locale']),
             translationOf: nullableText(row['translation_of']),
             version: Number(overrides.version ?? row['version']),
@@ -348,68 +444,181 @@ export function createContentStore(options) {
         return encodeCursor({ field: order.field, direction: order.direction, value, id: entry.id });
     }
     // ------------------------------------------------------------------- API
+    /**
+     * The whole of `create`, minus the transaction.
+     *
+     * Split out so `duplicate` can read the source and write the copy inside a
+     * single transaction: the free-slug probe it does between the two would
+     * otherwise be a read outside the write's transaction, and a concurrent
+     * insert could take the slug it had just found free.
+     */
+    async function insertEntry(tx, input) {
+        const id = input.id ?? newId();
+        const status = input.status ?? 'draft';
+        const at = stamp();
+        const author = input.createdBy ?? null;
+        const normalised = normaliseValues(collection, input.values ?? {}, {
+            partial: false,
+            enforceRequired: status === 'published',
+        });
+        const zones = normaliseBlocks(collection, input.blocks ?? {}, newId);
+        const values = { ...normalised.values };
+        if (status === 'published' && collection.fields['publishedAt'] !== undefined) {
+            values['publishedAt'] ??= at;
+            normalised.columns['publishedAt'] ??= at;
+        }
+        const columns = [
+            'id',
+            'created_at',
+            'updated_at',
+            'created_by',
+            'updated_by',
+            'status',
+            'locale',
+            'translation_of',
+            'version',
+            'provenance',
+            'provenance_detail',
+        ];
+        const bound = [
+            id,
+            at,
+            at,
+            author,
+            author,
+            status,
+            input.locale ?? defaultLocale,
+            input.translationOf ?? null,
+            1,
+            input.provenance ?? 'human',
+            input.provenanceDetail === undefined || input.provenanceDetail === null
+                ? null
+                : JSON.stringify(input.provenanceDetail),
+        ];
+        for (const [name, value] of Object.entries(normalised.columns)) {
+            columns.push(columnFor(name));
+            bound.push(value);
+        }
+        await tx.query(sql `insert into ${entries} (${joinFragments(columns.map((column) => identifier(column, dialect)), ', ')}) values (${valueList(bound)})`);
+        await writeRelations(tx, id, normalised.relations);
+        await writeBlocks(tx, id, 1, zones);
+        await writeVersion(tx, id, 1, status, { ...values, ...normalised.relations }, author);
+        const row = await loadRow(tx, id);
+        if (row === null)
+            throw notFound(collection.name, id);
+        return liveEntry(tx, row);
+    }
+    // ------------------------------------------------------------ duplication
+    const uniqueFields = Object.entries(collection.fields).filter(([, field]) => field.unique === true && !isColumnless(field));
+    async function isTaken(tx, field, locale, candidate) {
+        // Uniqueness is per locale, exactly as the index in `tables.ts` declares
+        // it: the same slug in French and in English is the normal case.
+        const found = await tx.query(sql `select ${identifier('id', dialect)} from ${entries}
+          where ${identifier('locale', dialect)} = ${locale}
+            and ${identifier(columnFor(field), dialect)} = ${candidate}
+          limit ${sqlLimit(1)}`);
+        return found.rows.length > 0;
+    }
+    /**
+     * A value for a `unique` field that no row holds yet, derived from the one
+     * being copied: `hello` becomes `hello-copy`, then `hello-copy-2`.
+     *
+     * The unique index stays the enforcement point — this only spares the caller
+     * a raw constraint violation on the single most common shape there is (an
+     * article with a unique slug).
+     */
+    async function freeUniqueValue(tx, field, locale, source) {
+        for (let attempt = 1; attempt <= 1000; attempt++) {
+            const candidate = attempt === 1 ? `${source}-copy` : `${source}-copy-${attempt}`;
+            if (!(await isTaken(tx, field, locale, candidate)))
+                return candidate;
+        }
+        throw new CogentaError({
+            code: 'CONTENT_INVALID',
+            message: `Could not derive a free value for the unique field "${field}".`,
+            hint: 'A thousand copies of this value already exist. Pass an explicit value for the field instead.',
+            details: { collection: collection.name, field },
+        });
+    }
     return {
-        create: async (input) => db.transaction(async (tx) => {
-            const id = input.id ?? newId();
-            const status = input.status ?? 'draft';
-            const at = stamp();
-            const author = input.createdBy ?? null;
-            const normalised = normaliseValues(collection, input.values ?? {}, {
-                partial: false,
-                enforceRequired: status === 'published',
-            });
-            const zones = normaliseBlocks(collection, input.blocks ?? {}, newId);
-            const values = { ...normalised.values };
-            if (status === 'published' && collection.fields['publishedAt'] !== undefined) {
-                values['publishedAt'] ??= at;
-                normalised.columns['publishedAt'] ??= at;
-            }
-            const columns = [
-                'id',
-                'created_at',
-                'updated_at',
-                'created_by',
-                'updated_by',
-                'status',
-                'locale',
-                'translation_of',
-                'version',
-                'provenance',
-                'provenance_detail',
-            ];
-            const bound = [
-                id,
-                at,
-                at,
-                author,
-                author,
-                status,
-                input.locale ?? defaultLocale,
-                input.translationOf ?? null,
-                1,
-                input.provenance ?? 'human',
-                input.provenanceDetail === undefined || input.provenanceDetail === null
-                    ? null
-                    : JSON.stringify(input.provenanceDetail),
-            ];
-            for (const [name, value] of Object.entries(normalised.columns)) {
-                columns.push(columnFor(name));
-                bound.push(value);
-            }
-            await tx.query(sql `insert into ${entries} (${joinFragments(columns.map((column) => identifier(column, dialect)), ', ')}) values (${valueList(bound)})`);
-            await writeRelations(tx, id, normalised.relations);
-            await writeBlocks(tx, id, 1, zones);
-            await writeVersion(tx, id, 1, status, { ...values, ...normalised.relations }, author);
+        create: async (input) => db.transaction((tx) => insertEntry(tx, input), { immediate: true }),
+        /**
+         * Copies one entry into a new draft.
+         *
+         * Three decisions are worth stating, because each could reasonably have
+         * gone the other way:
+         *
+         * 1. **The copy starts its own translation family** — `translationOf` is
+         *    always null, even when the source is itself a translation. Two rows
+         *    of the same family sharing a locale would make `resolveLocale` pick
+         *    between them arbitrarily (it takes the first match) and would show
+         *    the copy in `translations()` as if it were another language. A copy
+         *    is a new piece of content, not a new language of an old one.
+         * 2. **Blocks get fresh keys.** A `_key` anchors comments and RAG chunks;
+         *    the same key living in two entries would make "which entry does this
+         *    block belong to" answerable only with the entry id alongside it.
+         * 3. **Provenance is carried over, not reset to `human`.** Copying
+         *    generated content does not make it human-written, and pressing
+         *    duplicate must not launder it. Pass `provenance` to override.
+         *
+         * The copy is always a `draft`, its version count restarts at 1 and it
+         * inherits none of the source's history — the source's past is the
+         * source's.
+         */
+        duplicate: async (id, duplicateOptions) => db.transaction(async (tx) => {
             const row = await loadRow(tx, id);
             if (row === null)
                 throw notFound(collection.name, id);
-            return liveEntry(tx, row);
+            // The working state, not the published one: the admin's duplicate
+            // button copies what the editor is looking at.
+            const source = await workingEntry(tx, row);
+            const overrides = duplicateOptions?.values ?? {};
+            const locale = source.locale;
+            const values = { ...source.values };
+            // Never carried over: a copy has never been published.
+            if (collection.fields['publishedAt'] !== undefined)
+                values['publishedAt'] = null;
+            for (const [field] of uniqueFields) {
+                if (Object.hasOwn(overrides, field))
+                    continue;
+                const current = values[field];
+                if (current === null || current === undefined || current === '')
+                    continue;
+                if (typeof current !== 'string') {
+                    throw new CogentaError({
+                        code: 'CONTENT_INVALID',
+                        message: `"${field}" is unique and is not text, so a copy of it cannot be derived.`,
+                        hint: 'Pass a value for the field in duplicate()’s values, so the copy has its own.',
+                        details: { collection: collection.name, field },
+                    });
+                }
+                values[field] = await freeUniqueValue(tx, field, locale, current);
+            }
+            const blocks = {};
+            for (const [zone, list] of Object.entries(source.blocks)) {
+                blocks[zone] = list.map((block) => ({ ...block, key: '' }));
+            }
+            return insertEntry(tx, {
+                ...(duplicateOptions?.id === undefined ? {} : { id: duplicateOptions.id }),
+                locale,
+                translationOf: null,
+                status: 'draft',
+                createdBy: duplicateOptions?.createdBy ?? null,
+                provenance: duplicateOptions?.provenance ?? source.provenance,
+                provenanceDetail: duplicateOptions?.provenanceDetail ?? source.provenanceDetail,
+                values: { ...values, ...overrides },
+                blocks,
+            });
         }, { immediate: true }),
         read: async (id, readOptions) => {
             const state = readOptions?.state ?? 'published';
             const row = await loadRow(db, id);
             if (row === null)
                 return null;
+            // The trash is invisible unless it is asked for by name (ADR-0022) —
+            // the same safe-by-default posture as `state` on the line below.
+            if (hiddenBy(row, readOptions?.trashed))
+                return null;
             // The safe default: a caller that says nothing gets the published state,
             // never a draft. The public role has no way to ask for one.
             if (state === 'published') {
@@ -457,15 +666,82 @@ export function createContentStore(options) {
             await prune(tx, id, Number(after['version']));
             return workingEntry(tx, after);
         }, { immediate: true }),
-        delete: async (id) => {
-            const removed = await db.query(sql `delete from ${entries} where ${identifier('id', dialect)} = ${id}`);
+        delete: async (id) => db.transaction(async (tx) => {
+            const row = await loadRow(tx, id);
+            if (row === null)
+                return false;
+            // Already in the trash: nothing to do, and saying so with `false`
+            // matches what the method meant before 2.0 for a missing row.
+            if (isTrashed(row))
+                return false;
+            await assertNotReferenced(tx, id);
+            if (!trashEnabled)
+                return hardDelete(tx, id);
+            const removed = await tx.query(sql `update ${entries} set ${deletedAt} = ${stamp()}
+                where ${identifier('id', dialect)} = ${id}`);
             return removed.rowsAffected > 0;
+        }, { immediate: true }),
+        untrash: async (id) => db.transaction(async (tx) => {
+            const row = await loadRow(tx, id);
+            if (row === null)
+                throw notFound(collection.name, id);
+            if (!isTrashed(row)) {
+                throw new CogentaError({
+                    code: 'CONTENT_NOT_TRASHED',
+                    message: `"${id}" is not in the "${collection.name}" trash.`,
+                    hint: 'Only an entry that was trashed can be taken back out. Nothing was changed.',
+                    details: { collection: collection.name, id },
+                });
+            }
+            // `status` is deliberately untouched: an article that was published
+            // when it was trashed comes back published (ADR-0022). Restoring it
+            // as a draft would lose information and invite a second, accidental
+            // publication.
+            await tx.query(sql `update ${entries} set ${deletedAt} = ${null}
+                where ${identifier('id', dialect)} = ${id}`);
+            const after = await loadRow(tx, id);
+            if (after === null)
+                throw notFound(collection.name, id);
+            return { ...(await liveEntry(tx, after)), state: 'working' };
+        }, { immediate: true }),
+        purge: async (id) => db.transaction(async (tx) => {
+            const row = await loadRow(tx, id);
+            if (row === null)
+                return false;
+            await assertNotReferenced(tx, id);
+            return hardDelete(tx, id);
+        }, { immediate: true }),
+        purgeExpired: async () => {
+            const olderThan = new Date(now().getTime() - retainDays * DAY_MS).toISOString();
+            if (!trashEnabled)
+                return { purged: 0, olderThan };
+            return db.transaction(async (tx) => {
+                const expired = await tx.query(sql `select ${identifier('id', dialect)} from ${entries}
+                where ${deletedAt} is not null and ${deletedAt} < ${olderThan}`);
+                let purged = 0;
+                for (const row of expired.rows) {
+                    const id = text(row['id']);
+                    // Each one is still checked — a sweep that quietly broke a
+                    // `restrict` relation would be the hole the trash exists to close
+                    // — but one blocked entry is **skipped**, not fatal: a scheduled
+                    // sweep that dies on the first stuck row purges nothing ever
+                    // again, and nobody would notice.
+                    if (await isReferenced(tx, id))
+                        continue;
+                    if (await hardDelete(tx, id))
+                        purged += 1;
+                }
+                return { purged, olderThan };
+            }, { immediate: true });
         },
         list: async (listOptions = {}) => {
             const order = sortOrder(listOptions);
             const state = listOptions.state ?? 'published';
             const size = Math.min(Math.max(listOptions.limit ?? DEFAULT_PAGE_SIZE, 1), MAX_PAGE_SIZE);
             const predicates = [];
+            const trash = trashPredicate(listOptions.trashed);
+            if (trash !== null)
+                predicates.push(trash);
             if (listOptions.status !== undefined) {
                 predicates.push(sql `${identifier('status', dialect)} = ${listOptions.status}`);
             }
@@ -572,10 +848,15 @@ export function createContentStore(options) {
                 throw notFound(collection.name, id);
             return { ...(await liveEntry(tx, after)), state: 'working' };
         }, { immediate: true }),
-        history: async (id) => {
+        history: async (id, historyOptions) => {
             const row = await loadRow(db, id);
             if (row === null)
                 throw notFound(collection.name, id);
+            // A trashed entry has no history as far as an ordinary caller is
+            // concerned: it does not exist for them, and saying "not found" is the
+            // same answer `read()` gives.
+            if (hiddenBy(row, historyOptions?.trashed))
+                throw notFound(collection.name, id);
             const found = await db.query(sql `select * from ${versions}
             where ${identifier('entry_id', dialect)} = ${id}
             order by ${identifier('version', dialect)} desc`);
@@ -660,22 +941,30 @@ export function createContentStore(options) {
             };
             return diffContent(await load(from), await load(to));
         },
-        translations: async (id) => {
+        translations: async (id, translationsOptions) => {
             const row = await loadRow(db, id);
             if (row === null)
                 return [];
+            if (hiddenBy(row, translationsOptions?.trashed))
+                return [];
             const sourceId = nullableText(row['translation_of']) ?? text(row['id']);
             const found = await db.query(sql `select * from ${entries}
             where ${identifier('id', dialect)} = ${sourceId}
                or ${identifier('translation_of', dialect)} = ${sourceId}
             order by ${identifier('locale', dialect)} asc`);
-            return liveEntries(db, found.rows);
+            // A trashed member of the family is filtered out here rather than in the
+            // query, so that the family is still found through *any* of its members
+            // — including one whose source is in the trash.
+            const visible = found.rows.filter((member) => !hiddenBy(member, translationsOptions?.trashed));
+            return liveEntries(db, visible);
         },
         resolveLocale: async (id, locale, resolveOptions) => {
             const state = resolveOptions.state ?? 'published';
             const row = await loadRow(db, id);
             if (row === null)
                 return { outcome: 'notFound' };
+            if (hiddenBy(row, resolveOptions.trashed))
+                return { outcome: 'notFound' };
             const sourceId = nullableText(row['translation_of']) ?? text(row['id']);
             const found = await db.query(sql `select * from ${entries}
             where ${identifier('id', dialect)} = ${sourceId}
@@ -683,7 +972,8 @@ export function createContentStore(options) {
             // Publication is per language (ADR-0014): a French entry can be live while
             // its English translation is still a draft, and the renderer must treat
             // the draft as if it did not exist.
-            const visible = found.rows.filter((member) => state === 'working' || text(member['status']) === 'published');
+            const visible = found.rows.filter((member) => !hiddenBy(member, resolveOptions.trashed) &&
+                (state === 'working' || text(member['status']) === 'published'));
             const match = visible.find((member) => text(member['locale']) === locale);
             if (match !== undefined) {
                 const entry = state === 'published' ? await liveEntry(db, match) : await workingEntry(db, match);