@nixxie-cms/core 1.0.3 → 1.1.0

package/src/lib/core/cascade.ts

@@ -0,0 +1,236 @@
+/**
+ * Cascade deletion: enacts a collection's `cascade` rules inside the delete pipeline.
+ *
+ * Cascaded operations go through the normal mutation APIs (`context.sudo().db`), so the
+ * target collections' hooks, access events and their OWN cascade rules all run — deletes
+ * recurse naturally. A visited-set carried through AsyncLocalStorage guards against
+ * cycles (A → B → A) across the recursive mutation calls, which derive fresh context
+ * objects and therefore can't carry the state themselves.
+ *
+ * Note on atomicity: each cascaded operation commits independently (the hook pipeline
+ * is not transactional). `restrict` rules are checked up front, before anything is
+ * deleted, so refusals are always clean; a mid-cascade failure aborts the remaining
+ * cascade and the root delete, but already-cascaded operations stay committed.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { NixxieContext } from '../../types'
+import type { CascadeAction, CascadeRule } from '../../types/config/lists'
+import type { InitialisedList } from './initialise-lists'
+
+const cascadeStack = new AsyncLocalStorage<Set<string>>()
+
+/** Page size for fetching related records. */
+const PAGE = 100
+/** Safety cap on preview tree size. */
+const PREVIEW_LIMIT = 1000
+
+const visitKey = (listKey: string, id: unknown) => `${listKey}:${id}`
+
+/** Where-filter matching the target collection's records that point at `itemId`. */
+function matchWhere(rule: CascadeRule, itemId: string): Record<string, unknown> {
+  return rule.many
+    ? { [rule.field]: { some: { id: { equals: itemId } } } }
+    : { [rule.field]: { id: { equals: itemId } } }
+}
+
+function ruleAction(rule: CascadeRule): CascadeAction {
+  return rule.action ?? 'delete'
+}
+
+/**
+ * Check `restrict` rules for an item about to be deleted. Runs before any cascade work,
+ * so a refused delete leaves the database untouched. Records that are already part of
+ * the in-flight cascade (visited) don't count — they are being deleted too.
+ */
+export async function enforceCascadeRestrictions(
+  list: InitialisedList,
+  context: NixxieContext,
+  item: { id: unknown; [key: string]: unknown }
+): Promise<void> {
+  const rules = (list.cascade ?? []).filter(rule => ruleAction(rule) === 'restrict')
+  if (!rules.length) return
+
+  const visited = cascadeStack.getStore()
+  const sudo = context.sudo()
+  for (const rule of rules) {
+    const matches = await sudo.db[rule.collection].findMany({
+      where: matchWhere(rule, String(item.id)) as any,
+      take: PAGE,
+    })
+    const blocking = visited
+      ? matches.filter(match => !visited.has(visitKey(rule.collection, match.id)))
+      : matches
+    if (blocking.length) {
+      throw new Error(
+        `Cannot delete this ${list.listKey} item: ${blocking.length}${matches.length === PAGE ? '+' : ''} related ` +
+          `${rule.collection} record(s) reference it through "${rule.field}" (cascade rule: restrict). ` +
+          `Delete or reassign them first.`
+      )
+    }
+  }
+}
+
+/**
+ * Enact the non-restrict cascade rules for an item that is about to be deleted.
+ * Called from the delete pipeline after hooks, immediately before the database delete.
+ */
+export async function runCascade(
+  list: InitialisedList,
+  context: NixxieContext,
+  item: { id: unknown; [key: string]: unknown }
+): Promise<void> {
+  const rules = (list.cascade ?? []).filter(rule => ruleAction(rule) !== 'restrict')
+  // Mark the root as visited even when it has no rules itself — an ancestor cascade may
+  // be in flight, and other branches must know this item is already being handled.
+  const visited = cascadeStack.getStore() ?? new Set<string>()
+  visited.add(visitKey(list.listKey, item.id))
+  if (!rules.length) return
+
+  await cascadeStack.run(visited, async () => {
+    const sudo = context.sudo()
+    const itemId = String(item.id)
+
+    for (const rule of rules) {
+      const action = ruleAction(rule)
+      if (!sudo.db[rule.collection]) {
+        throw new Error(
+          `Cascade rule on ${list.listKey} points at unknown collection "${rule.collection}"`
+        )
+      }
+
+      // softDelete'd records still reference the deleted item, so the match query must
+      // exclude already-stamped rows or this loop would never drain.
+      const softDeleteField = rule.softDeleteField ?? 'deletedAt'
+      const where =
+        action === 'softDelete'
+          ? { ...matchWhere(rule, itemId), [softDeleteField]: null }
+          : matchWhere(rule, itemId)
+
+      for (;;) {
+        const matches = await sudo.db[rule.collection].findMany({ where: where as any, take: PAGE })
+        const pending = matches.filter(match => !visited.has(visitKey(rule.collection, match.id)))
+        if (!pending.length) break
+
+        for (const match of pending) {
+          const matchId = String(match.id)
+          if (action === 'delete') {
+            // Recurses into the target's own pipeline (hooks + its cascade rules).
+            await sudo.db[rule.collection].deleteOne({ where: { id: matchId } })
+          } else if (action === 'setNull') {
+            visited.add(visitKey(rule.collection, match.id))
+            await sudo.db[rule.collection].updateOne({
+              where: { id: matchId },
+              data: {
+                [rule.field]: rule.many ? { disconnect: [{ id: itemId }] } : { disconnect: true },
+              } as any,
+            })
+          } else if (action === 'softDelete') {
+            visited.add(visitKey(rule.collection, match.id))
+            await sudo.db[rule.collection].updateOne({
+              where: { id: matchId },
+              data: { [softDeleteField]: new Date().toISOString() } as any,
+            })
+          }
+        }
+
+        if (matches.length < PAGE) break
+      }
+    }
+  })
+}
+
+// ── Dry-run preview ──
+
+export type CascadePreviewNode = {
+  collection: string
+  id: string
+  /** The item's label-field value, when readable. */
+  label?: string
+  /** What would happen to this record. */
+  action: CascadeAction
+  children: CascadePreviewNode[]
+}
+
+export type CascadePreview = {
+  root: CascadePreviewNode
+  /** Per collection, how many records each action would touch (excluding the root). */
+  totals: Record<string, Partial<Record<CascadeAction, number>>>
+  /** True when the walk stopped early at the safety cap — totals are then lower bounds. */
+  truncated: boolean
+}
+
+/**
+ * Compute — without changing anything — the full tree of records a delete would touch,
+ * following cascade rules recursively. Surface this in delete confirmations:
+ * "This will delete 1 Post, 47 Comments and disconnect 3 Drafts."
+ *
+ * @example
+ * const preview = await previewDelete(context, 'Post', postId)
+ * console.log(preview.totals) // { Comment: { delete: 47 }, Draft: { setNull: 3 } }
+ */
+export async function previewDelete(
+  context: NixxieContext,
+  listKey: string,
+  itemId: string
+): Promise<CascadePreview> {
+  const lists = context.__internal.lists
+  if (!lists[listKey]) throw new Error(`previewDelete: unknown collection "${listKey}"`)
+
+  const sudo = context.sudo()
+  const totals: CascadePreview['totals'] = {}
+  const visited = new Set<string>()
+  let nodes = 0
+  let truncated = false
+
+  const count = (collection: string, action: CascadeAction) => {
+    const slot = (totals[collection] ??= {})
+    slot[action] = (slot[action] ?? 0) + 1
+  }
+
+  async function walk(currentKey: string, id: string, action: CascadeAction): Promise<CascadePreviewNode> {
+    visited.add(visitKey(currentKey, id))
+    const list = lists[currentKey]
+    const node: CascadePreviewNode = { collection: currentKey, id, action, children: [] }
+
+    const labelField = list.ui.labelField
+    try {
+      const item: any = await sudo.db[currentKey].findOne({ where: { id } })
+      const label = item?.[labelField]
+      if (label != null && labelField !== 'id') node.label = String(label)
+    } catch {
+      // label is cosmetic — never fail the preview over it
+    }
+
+    // Only deletes propagate further cascades.
+    if (action !== 'delete') return node
+
+    for (const rule of list.cascade ?? []) {
+      const childAction = ruleAction(rule)
+      if (!lists[rule.collection]) continue
+      let skip = 0
+      for (;;) {
+        const matches = await sudo.db[rule.collection].findMany({
+          where: matchWhere(rule, id) as any,
+          take: PAGE,
+          skip,
+        })
+        for (const match of matches) {
+          if (visited.has(visitKey(rule.collection, match.id))) continue
+          if (nodes >= PREVIEW_LIMIT) {
+            truncated = true
+            return node
+          }
+          nodes++
+          count(rule.collection, childAction)
+          node.children.push(await walk(rule.collection, String(match.id), childAction))
+        }
+        if (matches.length < PAGE) break
+        skip += PAGE
+      }
+    }
+    return node
+  }
+
+  const root = await walk(listKey, itemId, 'delete')
+  return { root, totals, truncated }
+}

package/src/lib/core/initialise-lists.ts

@@ -1,5 +1,6 @@
 import type { CacheHint } from '@apollo/cache-control-types'
-import { GInputObjectType, type GArg, type GInputType } from '@graphql-ts/schema'
+import type { GInputObjectType } from '@graphql-ts/schema'
+import { type GArg, type GInputType } from '@graphql-ts/schema'
 import { GNonNull } from '@graphql-ts/schema'
 import {
   GraphQLList,
@@ -17,21 +18,26 @@ import type {
   ActionMeta,
   BaseFieldTypeInfo,
   BaseItem,
-  BaseListTypeInfo,
+  BaseCollectionTypeInfo,
   CacheHintArgs,
   FieldTypeFunc,
   FindManyArgs,
-  GraphQLTypesForList,
+  GraphQLTypesForCollection,
   NixxieConfig,
-  ListGraphQLTypes,
-  ListHooks,
+  CollectionGraphQLTypes,
+  CollectionHooks,
   MaybeFieldFunction,
   NextFieldType,
 } from '../../types'
 import { QueryMode } from '../../types'
-import type { FieldHooks, ResolvedFieldHooks, ResolvedListHooks } from '../../types/config/hooks'
+import type {
+  FieldHooks,
+  ResolvedFieldHooks,
+  ResolvedCollectionHooks,
+} from '../../types/config/hooks'
 import type {
   BaseActions,
+  CascadeRule,
   MaybeBooleanItemFunctionWithFilter,
   MaybeBooleanSessionFunctionWithFilter,
   MaybeItemActionFunctionWithFilter,
@@ -44,7 +50,7 @@ import { type GraphQLNames, __getNames } from '../../types/utils'
 import {
   type ResolvedActionAccessControl,
   type ResolvedFieldAccessControl,
-  type ResolvedListAccessControl,
+  type ResolvedCollectionAccessControl,
   parseFieldAccessControl,
   parseListAccessControl,
 } from './access-control'
@@ -57,7 +63,7 @@ export type InitialisedAction = {
   actionKey: string
 
   access: ResolvedActionAccessControl
-  resolve: BaseActions<BaseListTypeInfo>[keyof BaseActions<BaseListTypeInfo>]['resolve']
+  resolve: BaseActions<BaseCollectionTypeInfo>[keyof BaseActions<BaseCollectionTypeInfo>]['resolve']
   graphql: {
     arguments: { name: string; type: string; source: { itemField: string } | null }[]
     names: {
@@ -79,14 +85,14 @@ export type InitialisedAction = {
       actionMode: MaybeItemActionFunctionWithFilter<
         'enabled' | 'disabled' | 'hidden',
         'disabled' | 'hidden',
-        BaseListTypeInfo
+        BaseCollectionTypeInfo
       >
     }
     listView: {
       actionMode: MaybeSessionFunctionWithFilter<
         'enabled' | 'disabled' | 'hidden',
         'disabled' | 'hidden',
-        BaseListTypeInfo
+        BaseCollectionTypeInfo
       >
     }
     argSources: Record<string, { itemField: string }>
@@ -116,14 +122,14 @@ export type InitialisedField = {
 
   access: ResolvedFieldAccessControl
   dbField: ResolvedDBField
-  hooks: ResolvedFieldHooks<BaseListTypeInfo, BaseFieldTypeInfo>
+  hooks: ResolvedFieldHooks<BaseCollectionTypeInfo, BaseFieldTypeInfo>
   graphql: {
     isEnabled: {
       read: boolean
       create: boolean
       update: boolean
-      filter: MaybeFieldFunction<BaseListTypeInfo>
-      orderBy: MaybeFieldFunction<BaseListTypeInfo>
+      filter: MaybeFieldFunction<BaseCollectionTypeInfo>
+      orderBy: MaybeFieldFunction<BaseCollectionTypeInfo>
     }
     isNonNull: {
       read: boolean
@@ -137,21 +143,25 @@ export type InitialisedField = {
     description: string
     views: string | null
     createView: {
-      fieldMode: MaybeSessionFunctionWithFilter<'edit' | 'hidden', 'hidden', BaseListTypeInfo>
-      isRequired: MaybeBooleanSessionFunctionWithFilter<BaseListTypeInfo>
+      fieldMode: MaybeSessionFunctionWithFilter<'edit' | 'hidden', 'hidden', BaseCollectionTypeInfo>
+      isRequired: MaybeBooleanSessionFunctionWithFilter<BaseCollectionTypeInfo>
     }
     itemView: {
       fieldMode: MaybeItemFieldFunctionWithFilter<
         'read' | 'edit' | 'hidden',
         'read' | 'hidden',
-        BaseListTypeInfo,
+        BaseCollectionTypeInfo,
+        BaseFieldTypeInfo
+      >
+      fieldPosition: MaybeItemFieldFunction<
+        'form' | 'sidebar',
+        BaseCollectionTypeInfo,
         BaseFieldTypeInfo
       >
-      fieldPosition: MaybeItemFieldFunction<'form' | 'sidebar', BaseListTypeInfo, BaseFieldTypeInfo>
-      isRequired: MaybeBooleanItemFunctionWithFilter<BaseListTypeInfo, BaseFieldTypeInfo>
+      isRequired: MaybeBooleanItemFunctionWithFilter<BaseCollectionTypeInfo, BaseFieldTypeInfo>
     }
     listView: {
-      fieldMode: MaybeSessionFunction<'read' | 'hidden', BaseListTypeInfo>
+      fieldMode: MaybeSessionFunction<'read' | 'hidden', BaseCollectionTypeInfo>
     }
   }
 } & Pick<
@@ -168,20 +178,23 @@ export type InitialisedField = {
 export type InitialisedList = {
   listKey: string
 
-  access: ResolvedListAccessControl
+  access: ResolvedCollectionAccessControl
+
+  /** Referential-integrity rules enacted on delete (see CascadeRule). */
+  cascade: CascadeRule[]
 
   fields: Record<string, InitialisedField>
   actions: InitialisedAction[]
-  groups: GroupInfo<BaseListTypeInfo>[]
+  groups: GroupInfo<BaseCollectionTypeInfo>[]
 
-  hooks: ResolvedListHooks<BaseListTypeInfo>
+  hooks: ResolvedCollectionHooks<BaseCollectionTypeInfo>
 
   /** This will include the opposites to one-sided relationships */
   resolvedDbFields: Record<string, ResolvedDBField>
   lists: Record<string, InitialisedList>
 
   graphql: {
-    types: GraphQLTypesForList
+    types: GraphQLTypesForCollection
     names: GraphQLNames
     isEnabled: {
       type: boolean
@@ -189,8 +202,8 @@ export type InitialisedList = {
       create: boolean
       update: boolean
       delete: boolean
-      filter: MaybeFieldFunction<BaseListTypeInfo>
-      orderBy: MaybeFieldFunction<BaseListTypeInfo>
+      filter: MaybeFieldFunction<BaseCollectionTypeInfo>
+      orderBy: MaybeFieldFunction<BaseCollectionTypeInfo>
     }
   }
 
@@ -210,7 +223,7 @@ export type InitialisedList = {
   }
 
   isSingleton: boolean
-  cacheHint: ((args: CacheHintArgs<BaseListTypeInfo>) => CacheHint) | undefined
+  cacheHint: ((args: CacheHintArgs<BaseCollectionTypeInfo>) => CacheHint) | undefined
 }
 
 function throwIfNotAFilter(x: unknown, listKey: string, fieldKey: string) {
@@ -312,7 +325,9 @@ function defaultListHooksResolveInput({ resolvedData }: { resolvedData: any }) {
   return resolvedData
 }
 
-function parseListHooks(hooks: ListHooks<BaseListTypeInfo>): ResolvedListHooks<BaseListTypeInfo> {
+function parseListHooks(
+  hooks: CollectionHooks<BaseCollectionTypeInfo>
+): ResolvedCollectionHooks<BaseCollectionTypeInfo> {
   return {
     resolveInput: {
       create:
@@ -341,8 +356,8 @@ function defaultFieldHooksResolveInput({
 }
 
 function parseFieldHooks(
-  hooks: FieldHooks<BaseListTypeInfo, BaseFieldTypeInfo>
-): ResolvedFieldHooks<BaseListTypeInfo, BaseFieldTypeInfo> {
+  hooks: FieldHooks<BaseCollectionTypeInfo, BaseFieldTypeInfo>
+): ResolvedFieldHooks<BaseCollectionTypeInfo, BaseFieldTypeInfo> {
   return {
     resolveInput: {
       create:
@@ -379,7 +394,7 @@ function getListsWithInitialisedFields(
     ])
   )
 
-  const listGraphqlTypes: Record<string, ListGraphQLTypes<BaseListTypeInfo>> = {}
+  const listGraphqlTypes: Record<string, CollectionGraphQLTypes<BaseCollectionTypeInfo>> = {}
 
   for (const listConfig of Object.values(listsConfig)) {
     const { listKey } = listConfig
@@ -466,7 +481,7 @@ function getListsWithInitialisedFields(
       },
     })
 
-    const where: GraphQLTypesForList['where'] = g.inputObject({
+    const where: GraphQLTypesForCollection['where'] = g.inputObject({
       name: names.whereInputName,
       fields: () => {
         const { fields } = listsRef[listKey]
@@ -667,10 +682,10 @@ function getListsWithInitialisedFields(
     const { listKey } = listConfig
     const intermediateList = intermediateLists[listKey]
     const resultFields: Record<string, InitialisedField> = {}
-    const groups: GroupInfo<BaseListTypeInfo>[] = []
+    const groups: GroupInfo<BaseCollectionTypeInfo>[] = []
     const fieldKeys = Object.keys(listConfig.fields)
 
-    const fieldKeysToGroup: Record<string, GroupInfo<BaseListTypeInfo>> = {}
+    const fieldKeysToGroup: Record<string, GroupInfo<BaseCollectionTypeInfo>> = {}
     for (const [idx, [fieldKey, fieldFunc]] of Object.entries(listConfig.fields).entries()) {
       if (fieldKey.startsWith('__group')) {
         const group__ = fieldFunc as any
@@ -798,6 +813,7 @@ function getListsWithInitialisedFields(
     const names = __getNames(listKey, listConfig)
     result[listKey] = {
       access: parseListAccessControl(listConfig.access),
+      cascade: listConfig.cascade ?? [],
 
       fields: resultFields,
       groups,

package/src/lib/core/mutations/index.ts

@@ -20,6 +20,7 @@ import {
   relationshipError,
   resolverError,
 } from '../graphql-errors'
+import { enforceCascadeRestrictions, runCascade } from '../cascade'
 import { runSideEffectOnlyHook, validate } from '../hooks'
 import type { InitialisedAction, InitialisedList } from '../initialise-lists'
 import { mapUniqueWhereToWhere, traverse } from '../queries/resolvers'
@@ -218,9 +219,15 @@ async function deleteSingle__(
       // hooks
       await validate({ list, hookArgs })
 
+      // cascade rules: check `restrict` rules before any side effects
+      await enforceCascadeRestrictions(list, context, item)
+
       // before operation
       await runSideEffectOnlyHook(list, 'beforeOperation', hookArgs)
 
+      // cascade rules: delete / disconnect / soft-delete related records
+      await runCascade(list, context, item)
+
       // operation
       const result = await context.prisma[list.listKey].delete({ where: { id: item.id } })
       span.setAttribute('nixxie.result.id', result?.id ?? '')