@nixxie-cms/core 1.0.3 → 1.1.0

package/src/helpers.ts

@@ -1,15 +1,23 @@
-import { list, config, action } from './schema'
+import { randomBytes } from 'node:crypto'
+import { collection, buildConfig, createAction } from './schema'
+import { applyAccessFeatures, compileFeatureHooks } from './list-features'
+import type { ListFeaturesConfig } from './list-features'
 import { timestamp } from './fields/types/timestamp'
 import { relationship } from './fields/types/relationship'
+import { text } from './fields/types/text'
+import { select } from './fields/types/select'
+import { integer } from './fields/types/integer'
+import { json } from './fields/types/json'
 import { merge } from './fields/resolve-hooks'
 import type {
-  BaseListTypeInfo,
+  BaseCollectionTypeInfo,
   BaseNixxieTypeInfo,
-  ListConfig,
+  CollectionConfig,
   BaseFields,
   NixxieConfigPre,
   NixxieConfig,
-  ListHooks,
+  CollectionHooks,
+  CollectionAccessControl,
   ActionArgsConfig,
   Action,
   DeclaredAction,
@@ -63,22 +71,98 @@ export const validators = {
   required: { isRequired: true } as const,
 } as const
 
+// ================================================================
+// Access presets — readable shorthands for common access patterns
+// ================================================================
+//
+// Spelling out an access-control object on every list gets repetitive. In
+// practice 90% of lists fall into a handful of patterns, so we name them.
+// Anything more bespoke can still drop down to a raw access object.
+
+type AnyAccessArgs = { session?: any; context?: any }
+
+const isSignedIn = ({ session }: AnyAccessArgs) => !!session
+
+export const accessPresets: {
+  /** Everyone can do everything (equivalent to `allowAll`). */
+  public: CollectionAccessControl<any>
+  /** Any signed-in user can read & write; anonymous requests are denied. */
+  authenticated: CollectionAccessControl<any>
+  /** Anyone can read; only signed-in users can create/update/delete. */
+  publicReadAuthenticatedWrite: CollectionAccessControl<any>
+  /** Anyone can read; nothing can be written through the API. */
+  readOnly: CollectionAccessControl<any>
+  /**
+   * Rows are scoped to their owner. Signed-in users may create items, and may
+   * only read/update/delete rows whose `<field>` relationship points at the
+   * current session's `itemId`.
+   *
+   * @param field the relationship field linking a row to its owning user (default `'user'`)
+   */
+  owner: (field?: string) => CollectionAccessControl<any>
+} = {
+  public: () => true,
+  authenticated: {
+    operation: {
+      query: isSignedIn,
+      create: isSignedIn,
+      update: isSignedIn,
+      delete: isSignedIn,
+    },
+  },
+  publicReadAuthenticatedWrite: {
+    operation: {
+      query: () => true,
+      create: isSignedIn,
+      update: isSignedIn,
+      delete: isSignedIn,
+    },
+  },
+  readOnly: {
+    operation: {
+      query: () => true,
+      create: () => false,
+      update: () => false,
+      delete: () => false,
+    },
+  },
+  owner(field = 'user') {
+    const scopeToOwner = ({ session }: AnyAccessArgs) => {
+      if (!session?.itemId) return false
+      return { [field]: { id: { equals: session.itemId } } }
+    }
+    return {
+      operation: {
+        query: isSignedIn,
+        create: isSignedIn,
+        update: isSignedIn,
+        delete: isSignedIn,
+      },
+      filter: {
+        query: scopeToOwner,
+        update: scopeToOwner,
+        delete: scopeToOwner,
+      },
+    } as CollectionAccessControl<any>
+  },
+}
+
 // ================================================================
 // Mixin system
 // ================================================================
 
-export type ListMixin<ListTypeInfo extends BaseListTypeInfo = BaseListTypeInfo> = {
+export type CollectionMixin<CollectionTypeInfo extends BaseCollectionTypeInfo = BaseCollectionTypeInfo> = {
   /** Fields added by this mixin — user fields take precedence on key conflicts */
   fields?: Record<string, any>
   /** Hooks merged with existing list hooks */
-  hooks?: Partial<ListHooks<ListTypeInfo>>
+  hooks?: Partial<CollectionHooks<CollectionTypeInfo>>
 }
 
 /**
  * Adds `createdAt` and `updatedAt` timestamp fields.
  * Both are hidden on create forms and read-only in item views.
  */
-export function withTimestamps(): ListMixin {
+export function withTimestamps(): CollectionMixin {
   return {
     fields: {
       createdAt: timestamp({
@@ -107,7 +191,7 @@ export function withTimestamps(): ListMixin {
  * Items are not physically deleted — set `deletedAt` to the current time instead.
  * Note: you must manually filter `deletedAt: null` in your queries/access control.
  */
-export function withSoftDelete(): ListMixin {
+export function withSoftDelete(): CollectionMixin {
   return {
     fields: {
       deletedAt: timestamp({
@@ -130,7 +214,7 @@ export function withSoftDelete(): ListMixin {
  *
  * @param userListKey - The list key for your user model (default: 'User')
  */
-export function withAudit(userListKey = 'User'): ListMixin {
+export function withAudit(userListKey = 'User'): CollectionMixin {
   return {
     fields: {
       createdBy: relationship({
@@ -171,6 +255,611 @@ export function withAudit(userListKey = 'User'): ListMixin {
   }
 }
 
+/**
+ * Turn an arbitrary string into a URL-safe slug. Pure, dependency-free.
+ */
+function slugify(input: string): string {
+  return input
+    .toString()
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '') // strip accents
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-') // non-alphanumerics → dashes
+    .replace(/^-+|-+$/g, '') // trim leading/trailing dashes
+}
+
+/**
+ * Adds a URL-friendly `slug` field that is auto-generated from another field
+ * (e.g. `title`) when left blank, and normalised when provided.
+ *
+ * Solves a perennial papercut: there's no built-in slug field, so everyone
+ * re-implements the same `resolveInput` hook by hand.
+ *
+ * @example
+ * defineCollection({ mixins: [withSlug({ from: 'title' })], fields: { title: text() } })
+ */
+export function withSlug(
+  opts: { from: string; field?: string; isIndexed?: 'unique' | true } = { from: 'title' }
+): CollectionMixin {
+  const fieldKey = opts.field ?? 'slug'
+  const from = opts.from
+  return {
+    fields: {
+      [fieldKey]: text({
+        isIndexed: opts.isIndexed ?? 'unique',
+        ui: {
+          description: `URL slug — auto-generated from "${from}" when left blank.`,
+        },
+      }),
+    },
+    hooks: {
+      resolveInput: ({ resolvedData, inputData }) => {
+        const provided = (resolvedData as any)[fieldKey]
+        if (typeof provided === 'string' && provided.length > 0) {
+          return { ...resolvedData, [fieldKey]: slugify(provided) }
+        }
+        const source = (inputData as any)?.[from] ?? (resolvedData as any)?.[from]
+        if (typeof source === 'string' && source.length > 0) {
+          return { ...resolvedData, [fieldKey]: slugify(source) }
+        }
+        return resolvedData
+      },
+    },
+  }
+}
+
+/**
+ * Adds a draft → published → archived workflow: a `status` select plus a
+ * `publishedAt` timestamp that is stamped automatically the first time an item
+ * transitions to `published`.
+ *
+ * Publishing is otherwise left entirely to the developer; this bakes in the
+ * common content lifecycle so a blog/news/docs list works out of the box.
+ */
+export function withPublishing(
+  opts: { defaultStatus?: 'draft' | 'published' | 'archived' } = {}
+): CollectionMixin {
+  const defaultStatus = opts.defaultStatus ?? 'draft'
+  return {
+    fields: {
+      status: select({
+        type: 'enum',
+        options: [
+          { label: 'Draft', value: 'draft' },
+          { label: 'Published', value: 'published' },
+          { label: 'Archived', value: 'archived' },
+        ],
+        defaultValue: defaultStatus,
+        ui: { displayMode: 'segmented-control' },
+      }),
+      publishedAt: timestamp({
+        ui: {
+          createView: { fieldMode: 'hidden' },
+          itemView: { fieldMode: 'read' },
+          listView: { fieldMode: 'read' },
+        },
+      }),
+    },
+    hooks: {
+      resolveInput: ({ resolvedData, item }) => {
+        const nextStatus = (resolvedData as any).status ?? (item as any)?.status
+        const alreadyPublished = (item as any)?.publishedAt
+        const incomingPublishedAt = (resolvedData as any).publishedAt
+        if (nextStatus === 'published' && !alreadyPublished && incomingPublishedAt == null) {
+          return { ...resolvedData, publishedAt: new Date().toISOString() }
+        }
+        return resolvedData
+      },
+    },
+  }
+}
+
+/**
+ * Adds standard SEO metadata fields, grouped together in the Admin UI.
+ * Drop-in for any content list that needs search/social previews.
+ */
+export function withSEO(): CollectionMixin {
+  return {
+    fields: {
+      metaTitle: text({
+        ui: { description: 'Title used by search engines and social previews.' },
+      }),
+      metaDescription: text({
+        ui: { displayMode: 'textarea', description: 'Short summary (~155 characters).' },
+      }),
+      ogImage: text({
+        ui: { description: 'Absolute URL to the social sharing image.' },
+      }),
+    },
+  }
+}
+
+/**
+ * Adds an integer `order` field for manual sorting/drag-ordering of items.
+ */
+export function withSortable(opts: { field?: string } = {}): CollectionMixin {
+  const fieldKey = opts.field ?? 'order'
+  return {
+    fields: {
+      [fieldKey]: integer({
+        defaultValue: 0,
+        ui: { description: 'Manual sort position (lower comes first).' },
+      }),
+    },
+  }
+}
+
+/**
+ * Adds self-referential `parent` / `children` relationships for tree-shaped content
+ * (categories, menus, pages), with cycle prevention: an item can never be moved under
+ * one of its own descendants.
+ *
+ * @param listKey - The key of the collection this mixin is applied to (needed for the
+ *   self-referencing relationship and ancestor checks).
+ *
+ * @example
+ * defineCollection({ mixins: [withTreeStructure('Category')], fields: { name: text() } })
+ */
+export function withTreeStructure(
+  listKey: string,
+  opts: { parentField?: string; childrenField?: string } = {}
+): CollectionMixin {
+  const parentField = opts.parentField ?? 'parent'
+  const childrenField = opts.childrenField ?? 'children'
+  return {
+    fields: {
+      [parentField]: relationship({
+        ref: `${listKey}.${childrenField}`,
+        ui: { description: 'Parent item in the tree (leave empty for a root item).' },
+      }),
+      [childrenField]: relationship({
+        ref: `${listKey}.${parentField}`,
+        many: true,
+        ui: { displayMode: 'count', itemView: { fieldMode: 'read' } },
+      }),
+    },
+    hooks: {
+      validate: async args => {
+        const { operation, resolvedData, item, context, addValidationError } = args as any
+        if (operation !== 'update') return
+        const parentOp = resolvedData?.[parentField]
+        const newParentId = parentOp?.connect?.id
+        if (newParentId == null) return
+
+        if (String(newParentId) === String(item.id)) {
+          addValidationError(`"${parentField}" cannot point at the item itself`)
+          return
+        }
+        // Walk up from the new parent — finding the item means we'd create a cycle.
+        const sudo = context.sudo()
+        let cursor: any = newParentId
+        for (let depth = 0; depth < 100 && cursor != null; depth++) {
+          const ancestor = await sudo.query[listKey].findOne({
+            where: { id: String(cursor) },
+            query: `id ${parentField} { id }`,
+          })
+          if (!ancestor) return
+          cursor = ancestor[parentField]?.id ?? null
+          if (cursor != null && String(cursor) === String(item.id)) {
+            addValidationError(
+              `"${parentField}" would create a cycle — the new parent is a descendant of this item`
+            )
+            return
+          }
+        }
+      },
+    },
+  }
+}
+
+/**
+ * Multi-tenancy: adds a required `tenant` relationship that is auto-assigned from the
+ * session on create. Combine with `tenantAccessFilter()` in the collection's
+ * `access.filter` rules to scope every query/update/delete to the session's tenant.
+ *
+ * @example
+ * defineCollection({
+ *   mixins: [withTenant({ ref: 'Tenant' })],
+ *   access: {
+ *     filter: {
+ *       query: tenantAccessFilter(),
+ *       update: tenantAccessFilter(),
+ *       delete: tenantAccessFilter(),
+ *     },
+ *   },
+ *   fields: { ... },
+ * })
+ */
+export function withTenant(
+  opts: {
+    /** Collection that holds tenants. @default 'Tenant' */
+    ref?: string
+    /** Field key for the tenant relationship. @default 'tenant' */
+    field?: string
+    /** Extract the tenant id from the session. @default session.data?.tenant?.id ?? session.tenantId */
+    getTenantId?: (session: any) => string | undefined
+    /** Allow items without a tenant (e.g. global records). @default false */
+    optional?: boolean
+  } = {}
+): CollectionMixin {
+  const ref = opts.ref ?? 'Tenant'
+  const field = opts.field ?? 'tenant'
+  const getTenantId = opts.getTenantId ?? defaultGetTenantId
+  return {
+    fields: {
+      [field]: relationship({
+        ref,
+        ui: {
+          createView: { fieldMode: 'hidden' },
+          itemView: { fieldMode: 'read' },
+        },
+      }),
+    },
+    hooks: {
+      resolveInput: ({ operation, resolvedData, context }) => {
+        if (operation !== 'create') return resolvedData
+        if ((resolvedData as any)[field]) return resolvedData
+        const tenantId = getTenantId((context as any).session)
+        if (!tenantId) return resolvedData
+        return { ...resolvedData, [field]: { connect: { id: tenantId } } }
+      },
+      validate: async args => {
+        const { operation, resolvedData, addValidationError } = args as any
+        if (opts.optional || operation !== 'create') return
+        if (!resolvedData?.[field]) {
+          addValidationError(`"${field}" is required — no tenant found on the session`)
+        }
+      },
+    },
+  }
+}
+
+function defaultGetTenantId(session: any): string | undefined {
+  return session?.data?.tenant?.id ?? session?.tenantId
+}
+
+/**
+ * Access-control filter companion to `withTenant()`: limits matched items to the
+ * session's tenant. Returns `false` (no access) when the session has no tenant.
+ */
+export function tenantAccessFilter(
+  opts: {
+    field?: string
+    getTenantId?: (session: any) => string | undefined
+  } = {}
+) {
+  const field = opts.field ?? 'tenant'
+  const getTenantId = opts.getTenantId ?? defaultGetTenantId
+  return ({ session }: { session?: any }) => {
+    const tenantId = getTenantId(session)
+    if (!tenantId) return false
+    return { [field]: { id: { equals: tenantId } } }
+  }
+}
+
+/**
+ * Adds `publishAt` / `unpublishAt` timestamps for scheduled publishing. Composes with
+ * `withPublishing()` (which provides the `status` field). The schedule is enacted by
+ * `applyScheduledPublishing()` — run it from a cron job:
+ *
+ * @example
+ * jobs: createJobs({ jobs: [{
+ *   name: 'scheduled-publishing',
+ *   schedule: '* * * * *',
+ *   handler: async () => { await applyScheduledPublishing(getContext(), 'Post') },
+ * }]})
+ */
+export function withScheduledPublishing(): CollectionMixin {
+  return {
+    fields: {
+      publishAt: timestamp({
+        ui: { description: 'Automatically publish at this time (requires the scheduled-publishing job).' },
+      }),
+      unpublishAt: timestamp({
+        ui: { description: 'Automatically archive at this time (requires the scheduled-publishing job).' },
+      }),
+    },
+  }
+}
+
+/**
+ * Enact `withScheduledPublishing()` schedules for one collection: publishes drafts whose
+ * `publishAt` has passed and archives published items whose `unpublishAt` has passed.
+ * Designed to be called from a cron job (see `withScheduledPublishing`).
+ */
+export async function applyScheduledPublishing(
+  context: any,
+  listKey: string,
+  opts: {
+    statusField?: string
+    draftValue?: string
+    publishedValue?: string
+    archivedValue?: string
+  } = {}
+): Promise<{ published: number; archived: number }> {
+  const statusField = opts.statusField ?? 'status'
+  const draftValue = opts.draftValue ?? 'draft'
+  const publishedValue = opts.publishedValue ?? 'published'
+  const archivedValue = opts.archivedValue ?? 'archived'
+  const sudo = context.sudo()
+  const now = new Date()
+
+  const toPublish = await sudo.db[listKey].findMany({
+    where: { [statusField]: { equals: draftValue }, publishAt: { lte: now } },
+  })
+  for (const item of toPublish) {
+    await sudo.db[listKey].updateOne({
+      where: { id: String(item.id) },
+      data: { [statusField]: publishedValue },
+    })
+  }
+
+  const toArchive = await sudo.db[listKey].findMany({
+    where: { [statusField]: { equals: publishedValue }, unpublishAt: { lte: now } },
+  })
+  for (const item of toArchive) {
+    await sudo.db[listKey].updateOne({
+      where: { id: String(item.id) },
+      data: { [statusField]: archivedValue },
+    })
+  }
+
+  return { published: toPublish.length, archived: toArchive.length }
+}
+
+/**
+ * i18n: adds a `locale` select plus a shared `translationKey` that groups an item with
+ * its translations (auto-generated on create when blank). Query an item's variants with
+ * `{ translationKey: { equals }, locale: { not: ... } }` — and once compound uniqueness
+ * is configured, pair (`translationKey`, `locale`) should be unique.
+ *
+ * @example
+ * defineCollection({ mixins: [withLocale({ locales: ['en', 'ur', 'ar'] })], fields: { ... } })
+ */
+export function withLocale(opts: {
+  locales: readonly string[]
+  defaultLocale?: string
+  /** Field key for the grouping id. @default 'translationKey' */
+  groupField?: string
+}): CollectionMixin {
+  if (!opts.locales?.length) throw new Error('withLocale requires at least one locale')
+  const groupField = opts.groupField ?? 'translationKey'
+  const defaultLocale = opts.defaultLocale ?? opts.locales[0]
+  return {
+    fields: {
+      locale: select({
+        type: 'enum',
+        options: opts.locales.map(locale => ({ label: locale, value: locale })),
+        defaultValue: defaultLocale,
+        validation: { isRequired: true },
+      }),
+      [groupField]: text({
+        isIndexed: true,
+        ui: {
+          description: 'Shared id linking this item with its translations.',
+          createView: { fieldMode: 'hidden' },
+          itemView: { fieldMode: 'read' },
+        },
+      }),
+    },
+    hooks: {
+      resolveInput: ({ operation, resolvedData }) => {
+        if (operation !== 'create') return resolvedData
+        if ((resolvedData as any)[groupField]) return resolvedData
+        return { ...resolvedData, [groupField]: randomBytes(8).toString('hex') }
+      },
+    },
+  }
+}
+
+/**
+ * Editorial approval: adds an approval status + a `pendingChanges` buffer where proposed
+ * edits wait for review instead of going live. Drive it with `submitForApproval()`,
+ * `approveChanges()` and `rejectChanges()` from custom mutations or the Admin UI.
+ */
+export function withApproval(): CollectionMixin {
+  return {
+    fields: {
+      approvalStatus: select({
+        type: 'enum',
+        options: [
+          { label: 'None', value: 'none' },
+          { label: 'Pending', value: 'pending' },
+          { label: 'Approved', value: 'approved' },
+          { label: 'Rejected', value: 'rejected' },
+        ],
+        defaultValue: 'none',
+        ui: { createView: { fieldMode: 'hidden' }, itemView: { fieldMode: 'read' } },
+      }),
+      pendingChanges: json({
+        ui: {
+          createView: { fieldMode: 'hidden' },
+          itemView: { fieldMode: 'hidden' },
+          listView: { fieldMode: 'hidden' },
+        },
+      }),
+      approvalSubmittedAt: timestamp({
+        ui: { createView: { fieldMode: 'hidden' }, itemView: { fieldMode: 'read' } },
+      }),
+      approvalReviewedAt: timestamp({
+        ui: { createView: { fieldMode: 'hidden' }, itemView: { fieldMode: 'read' } },
+      }),
+    },
+  }
+}
+
+/** Park proposed changes on an item for review (see `withApproval`). */
+export async function submitForApproval(
+  context: any,
+  args: { listKey: string; itemId: string; changes: Record<string, unknown> }
+): Promise<void> {
+  await context.sudo().db[args.listKey].updateOne({
+    where: { id: args.itemId },
+    data: {
+      pendingChanges: args.changes,
+      approvalStatus: 'pending',
+      approvalSubmittedAt: new Date().toISOString(),
+    },
+  })
+}
+
+/**
+ * Apply an item's `pendingChanges` (running normal hooks/validation) and mark it
+ * approved. The buffered changes must be a valid update input for the collection.
+ */
+export async function approveChanges(
+  context: any,
+  args: { listKey: string; itemId: string }
+): Promise<void> {
+  const sudo = context.sudo()
+  const item = await sudo.query[args.listKey].findOne({
+    where: { id: args.itemId },
+    query: 'id pendingChanges approvalStatus',
+  })
+  if (!item?.pendingChanges) throw new Error('approveChanges: the item has no pending changes')
+  await sudo.db[args.listKey].updateOne({
+    where: { id: args.itemId },
+    data: {
+      ...item.pendingChanges,
+      pendingChanges: null,
+      approvalStatus: 'approved',
+      approvalReviewedAt: new Date().toISOString(),
+    },
+  })
+}
+
+/** Discard an item's `pendingChanges` and mark it rejected. */
+export async function rejectChanges(
+  context: any,
+  args: { listKey: string; itemId: string }
+): Promise<void> {
+  await context.sudo().db[args.listKey].updateOne({
+    where: { id: args.itemId },
+    data: {
+      pendingChanges: null,
+      approvalStatus: 'rejected',
+      approvalReviewedAt: new Date().toISOString(),
+    },
+  })
+}
+
+/**
+ * Adds an `expiresAt` timestamp for content with a shelf life. Pair with
+ * `purgeExpired()` in a cron job to physically remove (or just count) expired items.
+ */
+export function withExpiry(opts: { field?: string } = {}): CollectionMixin {
+  const field = opts.field ?? 'expiresAt'
+  return {
+    fields: {
+      [field]: timestamp({
+        ui: { description: 'After this time the item is considered expired.' },
+      }),
+    },
+  }
+}
+
+/**
+ * Delete every item whose expiry has passed (runs normal delete hooks). Returns the
+ * number deleted. Designed for a cron job; see `withExpiry`.
+ */
+export async function purgeExpired(
+  context: any,
+  listKey: string,
+  opts: { field?: string } = {}
+): Promise<number> {
+  const field = opts.field ?? 'expiresAt'
+  const sudo = context.sudo()
+  const expired = await sudo.db[listKey].findMany({ where: { [field]: { lte: new Date() } } })
+  for (const item of expired) {
+    await sudo.db[listKey].deleteOne({ where: { id: String(item.id) } })
+  }
+  return expired.length
+}
+
+/**
+ * Adds a read-only `viewCount` integer. Increment it with `recordView()` — a direct,
+ * race-safe Prisma increment that bypasses hooks (a view is not an editorial change).
+ */
+export function withViewCount(opts: { field?: string } = {}): CollectionMixin {
+  const field = opts.field ?? 'viewCount'
+  return {
+    fields: {
+      [field]: integer({
+        defaultValue: 0,
+        ui: {
+          createView: { fieldMode: 'hidden' },
+          itemView: { fieldMode: 'read' },
+        },
+      }),
+    },
+  }
+}
+
+/** Increment an item's view counter (see `withViewCount`). */
+export async function recordView(
+  context: any,
+  listKey: string,
+  itemId: string,
+  opts: { field?: string } = {}
+): Promise<void> {
+  const field = opts.field ?? 'viewCount'
+  const model = (context.prisma as any)?.[listKey[0].toLowerCase() + listKey.slice(1)]
+  if (!model) throw new Error(`recordView: collection "${listKey}" was not found in the Prisma client`)
+  await model.update({ where: { id: itemId }, data: { [field]: { increment: 1 } } })
+}
+
+/**
+ * Companion to cascade rules: sweep records whose to-one relationship points at
+ * nothing (e.g. rows that pre-date a cascade rule, or were orphaned by `setNull`).
+ * Runs normal delete hooks (so cascade rules fire too). Designed for a cron job.
+ *
+ * @example
+ * jobs: createJobs({ jobs: [{
+ *   name: 'orphan-cleanup',
+ *   schedule: '0 4 * * *',
+ *   handler: async () => { await cleanupOrphans(getContext(), { collection: 'Comment', field: 'post' }) },
+ * }]})
+ */
+export async function cleanupOrphans(
+  context: any,
+  options: {
+    /** Collection to sweep. */
+    collection: string
+    /** To-one relationship field that must be connected for the record to be kept. */
+    field: string
+    /** 'delete' removes orphans; 'softDelete' stamps `softDeleteField`. @default 'delete' */
+    action?: 'delete' | 'softDelete'
+    /** @default 'deletedAt' */
+    softDeleteField?: string
+  }
+): Promise<number> {
+  const { collection, field, action = 'delete' } = options
+  const softDeleteField = options.softDeleteField ?? 'deletedAt'
+  const sudo = context.sudo()
+  const where =
+    action === 'softDelete' ? { [field]: null, [softDeleteField]: null } : { [field]: null }
+
+  let total = 0
+  for (;;) {
+    const orphans = await sudo.db[collection].findMany({ where, take: 100 })
+    if (!orphans.length) break
+    for (const orphan of orphans) {
+      if (action === 'delete') {
+        await sudo.db[collection].deleteOne({ where: { id: String(orphan.id) } })
+      } else {
+        await sudo.db[collection].updateOne({
+          where: { id: String(orphan.id) },
+          data: { [softDeleteField]: new Date().toISOString() },
+        })
+      }
+      total++
+    }
+    if (orphans.length < 100) break
+  }
+  return total
+}
+
 /**
  * Factory for building reusable field group mixins.
  *
@@ -183,28 +872,38 @@ export function withAudit(userListKey = 'User'): ListMixin {
  */
 export function createMixin(
   fields: Record<string, any>,
-  hooks?: Partial<ListHooks<any>>
-): ListMixin {
+  hooks?: Partial<CollectionHooks<any>>
+): CollectionMixin {
   return { fields, hooks }
 }
 
 // ================================================================
-// defineList — a typed wrapper around list() with mixin support
+// defineCollection — a typed wrapper around list() with mixin support
 // ================================================================
 
-type DefineListConfig<ListTypeInfo extends BaseListTypeInfo> = ListConfig<ListTypeInfo> & {
+type DefineListConfig<CollectionTypeInfo extends BaseCollectionTypeInfo> = Omit<
+  CollectionConfig<CollectionTypeInfo>,
+  'access'
+> & {
+  /**
+   * Controls what data can be read and changed. Optional here — unlike
+   * the lower-level `list()`, `defineCollection` defaults to `accessPresets.public`
+   * so a minimal list is genuinely one line. Set an explicit preset or access
+   * object the moment you need real rules.
+   */
+  access?: CollectionConfig<CollectionTypeInfo>['access']
   /**
    * Mixins to apply to this list. Mixin fields are merged before user fields,
    * so user fields always take precedence on key conflicts.
    */
-  mixins?: ListMixin[]
-}
+  mixins?: CollectionMixin[]
+} & ListFeaturesConfig
 
 /**
  * Defines a list with optional mixins for reusable field groups and hooks.
  *
  * @example
- * export const Post = defineList({
+ * export const Post = defineCollection({
  *   mixins: [withTimestamps()],
  *   fields: {
  *     title: text({ validation: validators.required }),
@@ -212,29 +911,60 @@ type DefineListConfig<ListTypeInfo extends BaseListTypeInfo> = ListConfig<ListTy
  *   },
  * })
  */
-export function defineList<ListTypeInfo extends BaseListTypeInfo>(
-  config: DefineListConfig<ListTypeInfo>
-): ListConfig<ListTypeInfo> {
-  const { mixins = [], ...listConfig } = config
+export function defineCollection<CollectionTypeInfo extends BaseCollectionTypeInfo>(
+  config: DefineListConfig<CollectionTypeInfo>
+): CollectionConfig<CollectionTypeInfo> {
+  const {
+    mixins = [],
+    access,
+    computed,
+    constraints,
+    defaultFilter,
+    stateMachine,
+    policies,
+    events,
+    searchable,
+    versioned,
+    ...listConfig
+  } = config
 
   const mixinFields: Record<string, any> = {}
-  const mixinHooksList: Array<Partial<ListHooks<any>>> = []
+  const mixinHooksList: Array<Partial<CollectionHooks<any>>> = []
 
   for (const mixin of mixins) {
     if (mixin.fields) Object.assign(mixinFields, mixin.fields)
     if (mixin.hooks) mixinHooksList.push(mixin.hooks)
   }
 
-  const mergedHooks = mergeMixinHooks(mixinHooksList, listConfig.hooks as Partial<ListHooks<any>>)
+  // Feature hooks run AFTER mixin + user hooks so computed fields and constraint checks
+  // observe the final resolved data, and events/search/version snapshots fire last.
+  const featureHooks = compileFeatureHooks({
+    computed,
+    constraints,
+    stateMachine,
+    events,
+    searchable,
+    versioned,
+  })
+
+  const mergedHooks = mergeMixinHooks(
+    mixinHooksList,
+    listConfig.hooks as Partial<CollectionHooks<any>>,
+    featureHooks
+  )
+
+  const baseAccess = access ?? accessPresets.public
+  const finalAccess = applyAccessFeatures(baseAccess, { defaultFilter, policies })
 
-  return list({
+  return collection({
     ...listConfig,
+    access: finalAccess as CollectionConfig<CollectionTypeInfo>['access'],
     fields: {
       ...mixinFields,
       ...listConfig.fields,
-    } as BaseFields<ListTypeInfo>,
-    hooks: mergedHooks as ListConfig<ListTypeInfo>['hooks'],
-  } as ListConfig<ListTypeInfo>)
+    } as BaseFields<CollectionTypeInfo>,
+    hooks: mergedHooks as CollectionConfig<CollectionTypeInfo>['hooks'],
+  } as CollectionConfig<CollectionTypeInfo>)
 }
 
 type AnyResolveInput =
@@ -275,33 +1005,34 @@ function mergeResolveInput(
 }
 
 /**
- * Merge mixin hooks with the list's own hooks. Each Keystone hook may be either a function or a
+ * Merge mixin hooks with the list's own hooks. Each list hook may be either a function or a
  * `{ create, update, delete }` object — `merge` (from resolve-hooks) handles both forms for the
  * void hooks, and `mergeResolveInput` handles the data-threading `resolveInput` hook.
  */
 function mergeMixinHooks(
-  mixinHooks: Array<Partial<ListHooks<any>>>,
-  listHooks: Partial<ListHooks<any>> | undefined
-): Partial<ListHooks<any>> {
-  if (mixinHooks.length === 0) return listHooks ?? {}
+  mixinHooks: Array<Partial<CollectionHooks<any>>>,
+  listHooks: Partial<CollectionHooks<any>> | undefined,
+  featureHooks: Array<Partial<CollectionHooks<any>>> = []
+): Partial<CollectionHooks<any>> {
+  if (mixinHooks.length === 0 && featureHooks.length === 0) return listHooks ?? {}
 
-  const all = [...mixinHooks, ...(listHooks ? [listHooks] : [])]
-  const merged: Partial<ListHooks<any>> = {}
+  const all = [...mixinHooks, ...(listHooks ? [listHooks] : []), ...featureHooks]
+  const merged: Partial<CollectionHooks<any>> = {}
 
   for (const hooks of all) {
     merged.resolveInput = mergeResolveInput(
       merged.resolveInput as AnyResolveInput | undefined,
       hooks.resolveInput as AnyResolveInput | undefined
-    ) as ListHooks<any>['resolveInput']
-    merged.validate = merge(merged.validate as any, hooks.validate as any) as ListHooks<any>['validate']
+    ) as CollectionHooks<any>['resolveInput']
+    merged.validate = merge(merged.validate as any, hooks.validate as any) as CollectionHooks<any>['validate']
     merged.beforeOperation = merge(
       merged.beforeOperation as any,
       hooks.beforeOperation as any
-    ) as ListHooks<any>['beforeOperation']
+    ) as CollectionHooks<any>['beforeOperation']
     merged.afterOperation = merge(
       merged.afterOperation as any,
       hooks.afterOperation as any
-    ) as ListHooks<any>['afterOperation']
+    ) as CollectionHooks<any>['afterOperation']
   }
 
   return merged
@@ -324,7 +1055,7 @@ function mergeMixinHooks(
 export function defineConfig<TypeInfo extends BaseNixxieTypeInfo>(
   nixxieConfig: NixxieConfigPre<TypeInfo>
 ): NixxieConfig<TypeInfo> {
-  return config(nixxieConfig)
+  return buildConfig(nixxieConfig)
 }
 
 // ================================================================
@@ -335,8 +1066,8 @@ export function defineConfig<TypeInfo extends BaseNixxieTypeInfo>(
  * Defines a list action. Typed alias for `action()`.
  */
 export function defineAction<
-  ListTypeInfo extends BaseListTypeInfo,
-  Args extends ActionArgsConfig<ListTypeInfo> | undefined = undefined,
->(actionConfig: Action<ListTypeInfo, Args>): DeclaredAction<ListTypeInfo> {
-  return action(actionConfig)
+  CollectionTypeInfo extends BaseCollectionTypeInfo,
+  Args extends ActionArgsConfig<CollectionTypeInfo> | undefined = undefined,
+>(actionConfig: Action<CollectionTypeInfo, Args>): DeclaredAction<CollectionTypeInfo> {
+  return createAction(actionConfig)
 }