@crombolo/data 0.10.0 → 0.12.1

package/src/dialect.ts

@@ -36,6 +36,16 @@ export interface Dialect {
   /** Appended to a SELECT that must block a concurrent state change; empty where the engine is single-writer. */
   readonly forShare: string
   readonly forUpdate: string
+  /** Appended to a SELECT that claims rows, passing over any another connection holds. */
+  readonly forUpdateSkipLocked: string
+  /**
+   * The full-text match over `search_document`: a subquery of `node_id` and
+   * `score`, higher being better, for each item holding every term as a word
+   * prefix. Its one parameter is `fullTextQuery(terms)`. docs/search.md.
+   */
+  readonly fullTextHits: string
+  /** Terms are already folded words: letters and digits only. */
+  fullTextQuery(terms: readonly string[]): string
   /**
    * SQL that moves a table's identity past rows inserted with explicit ids, or
    * undefined where the engine does that itself.
@@ -71,6 +81,15 @@ export const sqliteDialect: Dialect = {
   boolValue: (value) => (value ? 1 : 0),
   forShare: '',
   forUpdate: '',
+  forUpdateSkipLocked: '',
+  // Name hits weigh ten times body hits; bm25 is lower-is-better, so negated.
+  // bm25 cannot be called under an aggregate, and `LIMIT -1` (no limit) keeps
+  // SQLite from flattening the inner query into the outer one, which would.
+  fullTextHits: `SELECT sd.node_id AS node_id, MAX(f.score) AS score
+    FROM (SELECT rowid AS id, -bm25(search_document_fts, 10.0, 1.0) AS score
+          FROM search_document_fts WHERE search_document_fts MATCH ? LIMIT -1) f
+    JOIN search_document sd ON sd.id = f.id GROUP BY sd.node_id`,
+  fullTextQuery: (terms) => terms.map((term) => `"${term}"*`).join(' AND '),
   syncIdentity: () => undefined,
 }
 
@@ -102,6 +121,11 @@ export const postgresDialect: Dialect = {
   boolValue: (value) => value,
   forShare: 'FOR SHARE',
   forUpdate: 'FOR UPDATE',
+  forUpdateSkipLocked: 'FOR UPDATE SKIP LOCKED',
+  fullTextHits: `SELECT sd.node_id AS node_id, MAX(ts_rank(sd.terms, q)) AS score
+    FROM search_document sd, to_tsquery('simple', ?) q
+    WHERE sd.terms @@ q GROUP BY sd.node_id`,
+  fullTextQuery: (terms) => terms.map((term) => `${term}:*`).join(' & '),
   syncIdentity: (table) =>
     `SELECT setval(pg_get_serial_sequence('${table}', 'id'), (SELECT COALESCE(MAX(id), 1) FROM ${table}))`,
 }

package/src/index.ts

@@ -1,4 +1,7 @@
+export { insideTransaction } from './ambient.ts'
+export * from './audit.ts'
 export * from './bundle-tables/index.ts'
+export * from './busy.ts'
 export * from './change-report.ts'
 export * from './cluster.ts'
 export * from './database.ts'
@@ -8,12 +11,15 @@ export * from './maintenance.ts'
 export * from './migrations.ts'
 export * from './node-ref.ts'
 export * from './pending.ts'
+export * from './relations.ts'
 export * from './repositories/bundles.ts'
 export * from './repositories/content-types.ts'
 export * from './repositories/data-types.ts'
+export * from './repositories/delivery-member-tokens.ts'
 export * from './repositories/dictionary.ts'
 export * from './repositories/documents.ts'
 export * from './repositories/domains.ts'
+export * from './repositories/dynamic-roots.ts'
 export * from './repositories/folders.ts'
 export * from './repositories/form-entries.ts'
 export * from './repositories/form-workflows.ts'
@@ -27,10 +33,13 @@ export * from './repositories/redirects.ts'
 export * from './repositories/references.ts'
 export * from './repositories/tags.ts'
 export * from './repositories/templates.ts'
+export * from './repositories/transfer-answers.ts'
 export * from './repositories/transfer-runs.ts'
 export * from './repositories/user-data.ts'
 export * from './repositories/users.ts'
+export * from './repositories/webhooks.ts'
 export * from './schema/assistant.ts'
+export * from './schema/audit-log.ts'
 export * from './schema/built-in-content-types.ts'
 export * from './schema/built-in-media-types.ts'
 export * from './schema/built-in-member-types.ts'
@@ -41,6 +50,8 @@ export * from './schema/client-id-prefix.ts'
 export * from './schema/content.ts'
 export * from './schema/content-seed.ts'
 export * from './schema/created-packages.ts'
+export * from './schema/delivery-member-tokens.ts'
+export * from './schema/diagnostics.ts'
 export * from './schema/elements.ts'
 export * from './schema/form-permission-prefix.ts'
 export * from './schema/group-permissions.ts'
@@ -49,15 +60,24 @@ export * from './schema/log-viewer.ts'
 export * from './schema/member-property-type.ts'
 export * from './schema/members.ts'
 export * from './schema/plan.ts'
+export * from './schema/property-searchable.ts'
 export * from './schema/public-access.ts'
 export * from './schema/recycle-bin.ts'
 export * from './schema/rich-text-ui.ts'
+export * from './schema/search-index.ts'
 export * from './schema/seed.ts'
 export * from './schema/since-version.ts'
+export * from './schema/transfer-answers.ts'
 export * from './schema/transfer-run-package.ts'
 export * from './schema/transfer-runs.ts'
 export * from './schema/upgrade-report.ts'
 export * from './schema/users-localisation.ts'
 export * from './schema/values.ts'
+export * from './schema/webhooks.ts'
 export * from './schema-ops.ts'
 export * from './schema-state.ts'
+export * from './search.ts'
+export * from './search-text.ts'
+export * from './setup.ts'
+export * from './tree-invariants.ts'
+export * from './url-options.ts'

package/src/locks.ts

@@ -4,8 +4,12 @@
  * and necessary, while Postgres uses advisory locks.
  */
 import { AsyncLocalStorage } from 'node:async_hooks'
+import { insideTransaction } from './ambient.ts'
+import { ContentBusyError, DEFAULT_RETRY, type RetryPolicy, retryContention } from './busy.ts'
 import type { Db } from './database.ts'
 
+export const DEFAULT_LOCK_TIMEOUT_MS = 15_000
+
 /** Mirrors Umbraco's Constants.Locks. */
 export const Locks = {
   Servers: -331,
@@ -55,49 +59,114 @@ async function reentrant<T>(
   })
 }
 
-class SqliteLockManager implements LockManager {
-  #queues = new Map<number, Promise<unknown>>()
+export interface LockOptions {
+  /** How long to wait for the lock before answering busy. */
+  timeoutMs?: number
+  retry?: RetryPolicy
+}
 
-  withLock<T>(id: LockId, fn: () => Promise<T>): Promise<T> {
-    return reentrant(id, fn, (run) => this.#acquire(id, run))
-  }
+/**
+ * An in-process FIFO per lock id with a bounded wait. Ownership passes straight
+ * to the next waiter on release, and a waiter that times out leaves the line.
+ */
+export class LockQueue {
+  #lines = new Map<number, Array<() => void>>()
 
-  async #acquire<T>(id: LockId, fn: () => Promise<T>): Promise<T> {
-    const previous = this.#queues.get(id) ?? Promise.resolve()
-    let release!: () => void
-    const gate = new Promise<void>((resolve) => {
-      release = resolve
-    })
-    this.#queues.set(
-      id,
-      previous.then(() => gate),
-    )
-    await previous
+  async hold<T>(id: number, timeoutMs: number, fn: () => Promise<T>): Promise<T> {
+    await this.#acquire(id, timeoutMs)
     try {
       return await fn()
     } finally {
-      release()
-      if (this.#queues.get(id) === gate) this.#queues.delete(id)
+      this.#release(id)
+    }
+  }
+
+  #acquire(id: number, timeoutMs: number): Promise<void> {
+    const line = this.#lines.get(id)
+    if (!line) {
+      this.#lines.set(id, [])
+      return Promise.resolve()
     }
+    return new Promise<void>((resolve, reject) => {
+      const grant = () => {
+        clearTimeout(timer)
+        resolve()
+      }
+      const timer = setTimeout(() => {
+        const at = line.indexOf(grant)
+        if (at >= 0) line.splice(at, 1)
+        reject(new ContentBusyError('lockTimeout'))
+      }, timeoutMs)
+      line.push(grant)
+    })
+  }
+
+  #release(id: number): void {
+    const next = this.#lines.get(id)?.shift()
+    if (next) next()
+    else this.#lines.delete(id)
   }
 }
 
+/** Retries only from outside any transaction: one the database aborted cannot be resumed. */
+function guarded<T>(fn: () => Promise<T>, retry: RetryPolicy): Promise<T> {
+  return retryContention(fn, insideTransaction() ? { ...retry, attempts: 1 } : retry)
+}
+
+class SqliteLockManager implements LockManager {
+  #queue = new LockQueue()
+  #timeoutMs: number
+  #retry: RetryPolicy
+
+  constructor(options: LockOptions) {
+    this.#timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS
+    this.#retry = options.retry ?? DEFAULT_RETRY
+  }
+
+  withLock<T>(id: LockId, fn: () => Promise<T>): Promise<T> {
+    return reentrant(id, fn, (run) =>
+      guarded(() => this.#queue.hold(id, this.#timeoutMs, run), this.#retry),
+    )
+  }
+}
+
+/**
+ * The in-process queue first, then the advisory lock, which orders the nodes.
+ * Without the queue every waiting request held a pooled connection blocked on
+ * the advisory lock, and a pool full of waiters left the holder none to work on.
+ */
 class PostgresLockManager implements LockManager {
   #db: Db
-  constructor(db: Db) {
+  #queue = new LockQueue()
+  #timeoutMs: number
+  #retry: RetryPolicy
+
+  constructor(db: Db, options: LockOptions) {
     this.#db = db
+    this.#timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS
+    this.#retry = options.retry ?? DEFAULT_RETRY
   }
 
   withLock<T>(id: LockId, fn: () => Promise<T>): Promise<T> {
+    const timeout = Math.max(1, Math.round(this.#timeoutMs))
     return reentrant(id, fn, (run) =>
-      this.#db.transaction(async (tx) => {
-        await tx.exec('SELECT pg_advisory_xact_lock(?)', [id])
-        return run()
-      }),
+      guarded(
+        () =>
+          this.#queue.hold(id, this.#timeoutMs, () =>
+            this.#db.transaction(async (tx) => {
+              await tx.exec(`SET LOCAL lock_timeout = ${timeout}`)
+              await tx.exec('SELECT pg_advisory_xact_lock(?)', [id])
+              return run()
+            }),
+          ),
+        this.#retry,
+      ),
     )
   }
 }
 
-export function createLockManager(db: Db): LockManager {
-  return db.dialect.name === 'postgres' ? new PostgresLockManager(db) : new SqliteLockManager()
+export function createLockManager(db: Db, options: LockOptions = {}): LockManager {
+  return db.dialect.name === 'postgres'
+    ? new PostgresLockManager(db, options)
+    : new SqliteLockManager(options)
 }

package/src/migrations.ts

@@ -349,6 +349,26 @@ export async function readLedger(db: Db): Promise<LedgerRow[]> {
   }))
 }
 
+/**
+ * A step failed and was rolled back; every step before it is applied. Says which,
+ * and that running the upgrade again carries on from there.
+ */
+export class MigrationStepError extends Error {
+  constructor(
+    readonly step: string,
+    readonly applied: readonly string[],
+    readonly bundle: string | undefined,
+    override readonly cause: unknown,
+  ) {
+    const reason = cause instanceof Error ? cause.message : String(cause)
+    super(
+      `The upgrade stopped at ${bundle ? `the bundle "${bundle}"'s step` : 'step'} ${step}: ${reason}. ` +
+        `Nothing from that step was kept${applied.length > 0 ? `; the ${applied.length} step(s) before it are applied` : ''}. ` +
+        'Fix the cause and run the upgrade again: it carries on from this step.',
+    )
+  }
+}
+
 /** The database is at a state this code's plan does not know: newer code wrote it. */
 export class UpgradeStateError extends Error {
   constructor(
@@ -440,23 +460,29 @@ export async function migrate(
     await verifyApplied(db, plan, state)
     for (const next of pending) {
       const started = performance.now()
-      await db.transaction(async (tx) => {
-        await next.up(tx)
-        await next.backfill?.(tx)
-      })
+      // The state and the ledger row commit with the step, so an interrupted
+      // run resumes at the first step that did not land and never repeats one.
+      await db
+        .transaction(async (tx) => {
+          await next.up(tx)
+          await next.backfill?.(tx)
+          await writeState(tx, next.to, plan.stateKey)
+          await recordInLedger(tx, {
+            name: next.name,
+            kind: next.kind ?? 'expand',
+            fromState: next.from,
+            toState: next.to,
+            durationMs: Math.round(performance.now() - started),
+            checksum: next.checksum ?? next.name,
+            appliedBy: options.by ?? null,
+            note: next.release ? `release ${next.release}` : null,
+            bundle: plan.bundle ?? null,
+          })
+        })
+        .catch((error: unknown) => {
+          throw new MigrationStepError(next.name, applied, plan.bundle, error)
+        })
       state = next.to
-      await writeState(db, state, plan.stateKey)
-      await recordInLedger(db, {
-        name: next.name,
-        kind: next.kind ?? 'expand',
-        fromState: next.from,
-        toState: next.to,
-        durationMs: Math.round(performance.now() - started),
-        checksum: next.checksum ?? next.name,
-        appliedBy: options.by ?? null,
-        note: next.release ? `release ${next.release}` : null,
-        bundle: plan.bundle ?? null,
-      })
       applied.push(next.name)
     }
     return { from, to: state, applied }

package/src/relations.ts

@@ -0,0 +1,346 @@
+/**
+ * Umbraco's built-in relation types, and their relations derived rather than
+ * stored. "Related …" comes from the current values, as references do (story
+ * 041). "Relate parent … on delete" comes from the original parent a trashed
+ * item remembers. Copies record no origin, so "Relate Document On Copy" has none.
+ * docs/data-model.md.
+ */
+import { createHash } from 'node:crypto'
+import { normaliseUuid, ObjectTypes } from '@crombolo/core'
+import type { Db } from './database.ts'
+import { DbDate, fromDbBool } from './dialect.ts'
+
+/** RFC 4122's URL namespace, which Umbraco's `string.ToGuid()` hashes in. */
+const URL_NAMESPACE = '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
+
+/** A name-based (version 3, MD5) UUID: the same input always gives the same key. */
+export function nameBasedUuid(name: string, namespace = URL_NAMESPACE): string {
+  const bytes = createHash('md5')
+    .update(Buffer.from(namespace.replaceAll('-', ''), 'hex'))
+    .update(name, 'utf8')
+    .digest()
+  bytes[6] = ((bytes[6] as number) & 0x0f) | 0x30
+  bytes[8] = ((bytes[8] as number) & 0x3f) | 0x80
+  const hex = bytes.subarray(0, 16).toString('hex')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}
+
+export type RelationDerivation = 'reference' | 'original-parent' | 'none'
+
+export interface RelationType {
+  key: string
+  alias: string
+  name: string
+  parentObjectType: string | null
+  childObjectType: string | null
+  isBidirectional: boolean
+  isDependency: boolean
+  derivation: RelationDerivation
+  /** For a reference type, what is referred to; for an original-parent type, what was trashed. */
+  target: string | null
+}
+
+const define = (
+  alias: string,
+  name: string,
+  parentObjectType: string | null,
+  childObjectType: string | null,
+  isBidirectional: boolean,
+  isDependency: boolean,
+  derivation: RelationDerivation,
+  target: string | null,
+): RelationType => ({
+  // Umbraco's `CreateUniqueRelationTypeId`, so the keys match a real install's.
+  key: nameBasedUuid(`${alias}____${name}`),
+  alias,
+  name,
+  parentObjectType,
+  childObjectType,
+  isBidirectional,
+  isDependency,
+  derivation,
+  target,
+})
+
+/** In Umbraco's install order. */
+export const RELATION_TYPES: readonly RelationType[] = [
+  define(
+    'relateDocumentOnCopy',
+    'Relate Document On Copy',
+    ObjectTypes.Document,
+    ObjectTypes.Document,
+    true,
+    false,
+    'none',
+    null,
+  ),
+  define(
+    'relateParentDocumentOnDelete',
+    'Relate Parent Document On Delete',
+    ObjectTypes.Document,
+    ObjectTypes.Document,
+    false,
+    false,
+    'original-parent',
+    ObjectTypes.Document,
+  ),
+  define(
+    'relateParentMediaFolderOnDelete',
+    'Relate Parent Media Folder On Delete',
+    ObjectTypes.Media,
+    ObjectTypes.Media,
+    false,
+    false,
+    'original-parent',
+    ObjectTypes.Media,
+  ),
+  define('umbMedia', 'Related Media', null, null, false, true, 'reference', ObjectTypes.Media),
+  define(
+    'umbDocument',
+    'Related Document',
+    null,
+    null,
+    false,
+    true,
+    'reference',
+    ObjectTypes.Document,
+  ),
+  define('umbMember', 'Related Member', null, null, false, true, 'reference', ObjectTypes.Member),
+  define(
+    'umbElement',
+    'Related Element',
+    null,
+    null,
+    false,
+    true,
+    'reference',
+    ObjectTypes.Element,
+  ),
+  define(
+    'relateParentElementContainerOnElementDelete',
+    'Relate Parent Element Container On Element Delete',
+    ObjectTypes.ElementContainer,
+    ObjectTypes.Element,
+    false,
+    false,
+    'original-parent',
+    ObjectTypes.Element,
+  ),
+  define(
+    'relateParentElementContainerOnContainerDelete',
+    'Relate Parent Element Container On Container Delete',
+    ObjectTypes.ElementContainer,
+    ObjectTypes.ElementContainer,
+    false,
+    false,
+    'none',
+    null,
+  ),
+]
+
+export function relationTypeByKey(key: string): RelationType | undefined {
+  const wanted = normaliseUuid(key)
+  return RELATION_TYPES.find((type) => type.key === wanted)
+}
+
+const UDI = /umb:\/\/[a-z-]+\/([0-9a-f]{32})/gi
+const UUID = /\b([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/gi
+
+/** Every key a stored value mentions, as a picker writes it: `umb://<type>/<hex>` or a bare uuid. */
+export function referencedKeysIn(text: string): string[] {
+  const keys = new Set<string>()
+  for (const match of text.matchAll(UDI)) {
+    const hex = (match[1] as string).toLowerCase()
+    keys.add(
+      `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`,
+    )
+  }
+  for (const match of text.matchAll(UUID)) keys.add(normaliseUuid(match[1] as string))
+  return [...keys]
+}
+
+export interface ValueText {
+  nodeId: number
+  text: string
+}
+
+export interface KnownNode {
+  id: number
+  key: string
+  objectType: string
+}
+
+export interface ReferenceEdge {
+  fromId: number
+  toId: number
+  toObjectType: string
+}
+
+/** Who refers to whom, once per pair, never a node to itself. Pure. */
+export function deriveReferences(
+  values: readonly ValueText[],
+  nodesByKey: ReadonlyMap<string, KnownNode>,
+): ReferenceEdge[] {
+  const seen = new Set<string>()
+  const edges: ReferenceEdge[] = []
+  for (const value of values) {
+    for (const key of referencedKeysIn(value.text)) {
+      const target = nodesByKey.get(key)
+      if (!target || target.id === value.nodeId) continue
+      const pair = `${value.nodeId}>${target.id}`
+      if (seen.has(pair)) continue
+      seen.add(pair)
+      edges.push({ fromId: value.nodeId, toId: target.id, toObjectType: target.objectType })
+    }
+  }
+  return edges
+}
+
+/** Every reference the current values make. A scan, which is the price of never going stale. */
+export async function loadReferences(db: Db): Promise<ReferenceEdge[]> {
+  const values = await db.query<{ node_id: number; v: string | null; t: string | null }>(
+    `SELECT node_id, varchar_value AS v, text_value AS t FROM property_value
+      WHERE is_current = ? AND (varchar_value LIKE '%-%-%-%-%' OR text_value LIKE '%-%-%-%-%'
+         OR varchar_value LIKE '%umb://%' OR text_value LIKE '%umb://%')`,
+    [db.dialect.boolValue(true)],
+  )
+  const texts: ValueText[] = []
+  for (const row of values) {
+    const text = `${row.v ?? ''} ${row.t ?? ''}`
+    texts.push({ nodeId: Number(row.node_id), text })
+  }
+  const wanted = new Set(texts.flatMap((value) => referencedKeysIn(value.text)))
+  if (wanted.size === 0) return []
+  const nodes = await db.query<{ id: number; unique_id: string; node_object_type: string }>(
+    'SELECT id, unique_id, node_object_type FROM node',
+  )
+  const byKey = new Map<string, KnownNode>()
+  for (const node of nodes) {
+    const key = normaliseUuid(String(node.unique_id))
+    if (wanted.has(key))
+      byKey.set(key, {
+        id: Number(node.id),
+        key,
+        objectType: String(node.node_object_type).toLowerCase(),
+      })
+  }
+  return deriveReferences(texts, byKey)
+}
+
+export interface Relation {
+  key: string
+  typeKey: string
+  parent: { key: string; name: string | null }
+  child: { key: string; name: string | null }
+  createDate: Date
+}
+
+interface NodeFacts {
+  key: string
+  name: string | null
+  date: Date
+}
+
+async function describeNodes(db: Db, ids: readonly number[]): Promise<Map<number, NodeFacts>> {
+  const facts = new Map<number, NodeFacts>()
+  if (ids.length === 0) return facts
+  const holes = ids.map(() => '?').join(', ')
+  const rows = await db.query<{ id: number; unique_id: string; text: string | null; d: unknown }>(
+    `SELECT n.id, n.unique_id, n.text,
+            COALESCE((SELECT MAX(cv.version_date) FROM content_version cv WHERE cv.node_id = n.id), n.create_date) AS d
+       FROM node n WHERE n.id IN (${holes})`,
+    [...ids],
+  )
+  for (const row of rows)
+    facts.set(Number(row.id), {
+      key: normaliseUuid(String(row.unique_id)),
+      name: row.text,
+      date: DbDate.fromDb(row.d) ?? new Date(0),
+    })
+  return facts
+}
+
+/** A stable key for a derived relation: its type and its two ends. */
+export const relationKey = (type: RelationType, parentKey: string, childKey: string) =>
+  nameBasedUuid(`${type.alias}|${parentKey}|${childKey}`)
+
+export class RelationRepository {
+  #db: Db
+
+  constructor(db: Db) {
+    this.#db = db
+  }
+
+  /** The relations of one type, ordered by the parent's name then the child's, paged. */
+  async relations(
+    type: RelationType,
+    skip: number,
+    take: number,
+  ): Promise<{ total: number; items: Relation[] }> {
+    const pairs = await this.#pairs(type)
+    const facts = await describeNodes(this.#db, [...new Set(pairs.flat())])
+    const relations: Relation[] = []
+    for (const [parentId, childId] of pairs) {
+      const parent = facts.get(parentId)
+      const child = facts.get(childId)
+      if (!parent || !child) continue
+      relations.push({
+        key: relationKey(type, parent.key, child.key),
+        typeKey: type.key,
+        parent: { key: parent.key, name: parent.name },
+        child: { key: child.key, name: child.name },
+        createDate: type.derivation === 'reference' ? parent.date : child.date,
+      })
+    }
+    relations.sort(
+      (a, b) =>
+        (a.parent.name ?? '').localeCompare(b.parent.name ?? '') ||
+        (a.child.name ?? '').localeCompare(b.child.name ?? ''),
+    )
+    return { total: relations.length, items: relations.slice(skip, skip + take) }
+  }
+
+  async #pairs(type: RelationType): Promise<Array<[number, number]>> {
+    if (type.derivation === 'reference')
+      return (await loadReferences(this.#db))
+        .filter((edge) => edge.toObjectType === type.target)
+        .map((edge) => [edge.fromId, edge.toId])
+    if (type.derivation === 'original-parent') {
+      const rows = await this.#db.query<{ id: number; parent: number; parent_type: string }>(
+        `SELECT n.id, d.original_parent_id AS parent, p.node_object_type AS parent_type
+           FROM node n
+           JOIN document d ON d.node_id = n.id
+           JOIN node p ON p.id = d.original_parent_id
+          WHERE n.trashed = ? AND n.node_object_type = ?`,
+        [this.#db.dialect.boolValue(true), type.target],
+      )
+      return rows
+        .filter(
+          (row) =>
+            !type.parentObjectType ||
+            String(row.parent_type).toLowerCase() === type.parentObjectType,
+        )
+        .map((row) => [Number(row.parent), Number(row.id)])
+    }
+    return []
+  }
+
+  /** Nodes that refer to anything of `objectType` in the recycle bin: what emptying it breaks. */
+  async referencingRecycleBin(objectType: string): Promise<number[]> {
+    const trashed = new Set(
+      (
+        await this.#db.query<{ id: number; trashed: unknown }>(
+          'SELECT id, trashed FROM node WHERE node_object_type = ? AND trashed = ?',
+          [objectType, this.#db.dialect.boolValue(true)],
+        )
+      )
+        .filter((row) => fromDbBool(row.trashed))
+        .map((row) => Number(row.id)),
+    )
+    if (trashed.size === 0) return []
+    const from = new Set<number>()
+    for (const edge of await loadReferences(this.#db))
+      if (trashed.has(edge.toId)) from.add(edge.fromId)
+    return [...from]
+  }
+}