@nixxie-cms/core 1.0.0 → 1.0.1

package/src/helpers.ts

@@ -1,316 +1,342 @@
-import { list, config, action } from './schema'
-import { timestamp } from './fields/types/timestamp'
-import { relationship } from './fields/types/relationship'
-import type {
-  BaseListTypeInfo,
-  BaseNixxieTypeInfo,
-  ListConfig,
-  BaseFields,
-  NixxieConfigPre,
-  NixxieConfig,
-  ListHooks,
-  ActionArgsConfig,
-  Action,
-  DeclaredAction,
-} from './types'
-
-// ================================================================
-// Validators — use inside field `validation` config
-// ================================================================
-
-export const validators = {
-  /** Validates a string is a well-formed email address */
-  email: {
-    match: {
-      regex: /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/,
-      explanation: 'Must be a valid email address',
-    },
-  },
-
-  /** Validates a string starts with http:// or https:// */
-  url: {
-    match: {
-      regex: /^https?:\/\/.+/,
-      explanation: 'Must be a valid URL starting with http:// or https://',
-    },
-  },
-
-  /** Validates a string has at least `min` characters */
-  minLength: (min: number) => ({
-    length: { min } as const,
-  }),
-
-  /** Validates a string has at most `max` characters */
-  maxLength: (max: number) => ({
-    length: { max } as const,
-  }),
-
-  /** Validates a string has between `min` and `max` characters */
-  length: (min: number, max: number) => ({
-    length: { min, max } as const,
-  }),
-
-  /** Validates a string matches the given regex pattern */
-  regex: (regex: RegExp, explanation?: string) => ({
-    match: {
-      regex,
-      explanation: explanation ?? `Must match pattern ${regex}`,
-    },
-  }),
-
-  /** Marks a field as required */
-  required: { isRequired: true } as const,
-} as const
-
-// ================================================================
-// Mixin system
-// ================================================================
-
-export type ListMixin<ListTypeInfo extends BaseListTypeInfo = BaseListTypeInfo> = {
-  /** 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>>
-}
-
-/**
- * Adds `createdAt` and `updatedAt` timestamp fields.
- * Both are hidden on create forms and read-only in item views.
- */
-export function withTimestamps(): ListMixin {
-  return {
-    fields: {
-      createdAt: timestamp({
-        defaultValue: { kind: 'now' },
-        db: { isNullable: false },
-        ui: {
-          createView: { fieldMode: 'hidden' },
-          itemView: { fieldMode: 'read' },
-          listView: { fieldMode: 'read' },
-        },
-      }),
-      updatedAt: timestamp({
-        db: { updatedAt: true, isNullable: false },
-        ui: {
-          createView: { fieldMode: 'hidden' },
-          itemView: { fieldMode: 'read' },
-          listView: { fieldMode: 'read' },
-        },
-      }),
-    },
-  }
-}
-
-/**
- * Adds a `deletedAt` field for soft-delete support.
- * 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 {
-  return {
-    fields: {
-      deletedAt: timestamp({
-        db: { isNullable: true },
-        ui: {
-          createView: { fieldMode: 'hidden' },
-          itemView: { fieldMode: 'read' },
-          listView: { fieldMode: 'read' },
-        },
-      }),
-    },
-  }
-}
-
-/**
- * Adds `createdBy` and `updatedBy` relationship fields that automatically
- * track which user performed each write operation.
- *
- * Requires session to have an `itemId` (standard Nixxie auth).
- *
- * @param userListKey - The list key for your user model (default: 'User')
- */
-export function withAudit(userListKey = 'User'): ListMixin {
-  return {
-    fields: {
-      createdBy: relationship({
-        ref: userListKey,
-        ui: {
-          createView: { fieldMode: 'hidden' },
-          itemView: { fieldMode: 'read' },
-        },
-      }),
-      updatedBy: relationship({
-        ref: userListKey,
-        ui: {
-          createView: { fieldMode: 'hidden' },
-          itemView: { fieldMode: 'read' },
-        },
-      }),
-    },
-    hooks: {
-      resolveInput: async ({ operation, resolvedData, context }) => {
-        const userId = (context as any).session?.itemId
-        if (!userId) return resolvedData
-        if (operation === 'create') {
-          return {
-            ...resolvedData,
-            createdBy: { connect: { id: userId } },
-            updatedBy: { connect: { id: userId } },
-          }
-        }
-        if (operation === 'update') {
-          return {
-            ...resolvedData,
-            updatedBy: { connect: { id: userId } },
-          }
-        }
-        return resolvedData
-      },
-    },
-  }
-}
-
-/**
- * Factory for building reusable field group mixins.
- *
- * @example
- * const withAddress = createMixin({
- *   street: text(),
- *   city: text(),
- *   postcode: text({ validation: validators.regex(/^\d{4}$/, 'Must be a 4-digit postcode') }),
- * })
- */
-export function createMixin(
-  fields: Record<string, any>,
-  hooks?: Partial<ListHooks<any>>
-): ListMixin {
-  return { fields, hooks }
-}
-
-// ================================================================
-// defineList — a typed wrapper around list() with mixin support
-// ================================================================
-
-type DefineListConfig<ListTypeInfo extends BaseListTypeInfo> = ListConfig<ListTypeInfo> & {
-  /**
-   * Mixins to apply to this list. Mixin fields are merged before user fields,
-   * so user fields always take precedence on key conflicts.
-   */
-  mixins?: ListMixin[]
-}
-
-/**
- * Defines a list with optional mixins for reusable field groups and hooks.
- *
- * @example
- * export const Post = defineList({
- *   mixins: [withTimestamps()],
- *   fields: {
- *     title: text({ validation: validators.required }),
- *     content: text(),
- *   },
- * })
- */
-export function defineList<ListTypeInfo extends BaseListTypeInfo>(
-  config: DefineListConfig<ListTypeInfo>
-): ListConfig<ListTypeInfo> {
-  const { mixins = [], ...listConfig } = config
-
-  const mixinFields: Record<string, any> = {}
-  const mixinHooksList: Array<Partial<ListHooks<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>>)
-
-  return list({
-    ...listConfig,
-    fields: {
-      ...mixinFields,
-      ...listConfig.fields,
-    } as BaseFields<ListTypeInfo>,
-    hooks: mergedHooks as ListConfig<ListTypeInfo>['hooks'],
-  } as ListConfig<ListTypeInfo>)
-}
-
-function mergeMixinHooks(
-  mixinHooks: Array<Partial<ListHooks<any>>>,
-  listHooks: Partial<ListHooks<any>> | undefined
-): Partial<ListHooks<any>> {
-  if (mixinHooks.length === 0) return listHooks ?? {}
-
-  const hookNames: Array<keyof ListHooks<any>> = [
-    'resolveInput',
-    'validate',
-    'beforeOperation',
-    'afterOperation',
-  ]
-  const merged: Partial<ListHooks<any>> = {}
-
-  for (const hookName of hookNames) {
-    const fns = [
-      ...mixinHooks.map(h => h[hookName]).filter(Boolean),
-      ...(listHooks?.[hookName] ? [listHooks[hookName]] : []),
-    ] as ((...args: any[]) => any)[]
-
-    if (fns.length === 0) continue
-    if (fns.length === 1) {
-      ;(merged as any)[hookName] = fns[0]
-      continue
-    }
-    // Run all hooks in sequence; for resolveInput, pass the output of each as input to the next
-    if (hookName === 'resolveInput') {
-      ;(merged as any)[hookName] = async (args: any) => {
-        let result = args.resolvedData
-        for (const fn of fns) {
-          const out = await fn({ ...args, resolvedData: result })
-          if (out !== undefined) result = out
-        }
-        return result
-      }
-    } else {
-      ;(merged as any)[hookName] = async (args: any) => {
-        for (const fn of fns) await fn(args)
-      }
-    }
-  }
-
-  return merged
-}
-
-// ================================================================
-// defineConfig — typed alias for config()
-// ================================================================
-
-/**
- * Defines the Nixxie configuration. This is a typed alias for `config()` that
- * provides the same functionality with a more declarative name.
- *
- * @example
- * export default defineConfig({
- *   db: { provider: 'sqlite', url: 'file:./nixxie.db' },
- *   lists: { Post, User },
- * })
- */
-export function defineConfig<TypeInfo extends BaseNixxieTypeInfo>(
-  nixxieConfig: NixxieConfigPre<TypeInfo>
-): NixxieConfig<TypeInfo> {
-  return config(nixxieConfig)
-}
-
-// ================================================================
-// defineAction — typed alias for action()
-// ================================================================
-
-/**
- * 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)
-}
+import { list, config, action } from './schema'
+import { timestamp } from './fields/types/timestamp'
+import { relationship } from './fields/types/relationship'
+import { merge } from './fields/resolve-hooks'
+import type {
+  BaseListTypeInfo,
+  BaseNixxieTypeInfo,
+  ListConfig,
+  BaseFields,
+  NixxieConfigPre,
+  NixxieConfig,
+  ListHooks,
+  ActionArgsConfig,
+  Action,
+  DeclaredAction,
+} from './types'
+
+// ================================================================
+// Validators — use inside field `validation` config
+// ================================================================
+
+export const validators = {
+  /** Validates a string is a well-formed email address */
+  email: {
+    match: {
+      regex: /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/,
+      explanation: 'Must be a valid email address',
+    },
+  },
+
+  /** Validates a string starts with http:// or https:// */
+  url: {
+    match: {
+      regex: /^https?:\/\/.+/,
+      explanation: 'Must be a valid URL starting with http:// or https://',
+    },
+  },
+
+  /** Validates a string has at least `min` characters */
+  minLength: (min: number) => ({
+    length: { min } as const,
+  }),
+
+  /** Validates a string has at most `max` characters */
+  maxLength: (max: number) => ({
+    length: { max } as const,
+  }),
+
+  /** Validates a string has between `min` and `max` characters */
+  length: (min: number, max: number) => ({
+    length: { min, max } as const,
+  }),
+
+  /** Validates a string matches the given regex pattern */
+  regex: (regex: RegExp, explanation?: string) => ({
+    match: {
+      regex,
+      explanation: explanation ?? `Must match pattern ${regex}`,
+    },
+  }),
+
+  /** Marks a field as required */
+  required: { isRequired: true } as const,
+} as const
+
+// ================================================================
+// Mixin system
+// ================================================================
+
+export type ListMixin<ListTypeInfo extends BaseListTypeInfo = BaseListTypeInfo> = {
+  /** 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>>
+}
+
+/**
+ * Adds `createdAt` and `updatedAt` timestamp fields.
+ * Both are hidden on create forms and read-only in item views.
+ */
+export function withTimestamps(): ListMixin {
+  return {
+    fields: {
+      createdAt: timestamp({
+        defaultValue: { kind: 'now' },
+        db: { isNullable: false },
+        ui: {
+          createView: { fieldMode: 'hidden' },
+          itemView: { fieldMode: 'read' },
+          listView: { fieldMode: 'read' },
+        },
+      }),
+      updatedAt: timestamp({
+        db: { updatedAt: true, isNullable: false },
+        ui: {
+          createView: { fieldMode: 'hidden' },
+          itemView: { fieldMode: 'read' },
+          listView: { fieldMode: 'read' },
+        },
+      }),
+    },
+  }
+}
+
+/**
+ * Adds a `deletedAt` field for soft-delete support.
+ * 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 {
+  return {
+    fields: {
+      deletedAt: timestamp({
+        db: { isNullable: true },
+        ui: {
+          createView: { fieldMode: 'hidden' },
+          itemView: { fieldMode: 'read' },
+          listView: { fieldMode: 'read' },
+        },
+      }),
+    },
+  }
+}
+
+/**
+ * Adds `createdBy` and `updatedBy` relationship fields that automatically
+ * track which user performed each write operation.
+ *
+ * Requires session to have an `itemId` (standard Nixxie auth).
+ *
+ * @param userListKey - The list key for your user model (default: 'User')
+ */
+export function withAudit(userListKey = 'User'): ListMixin {
+  return {
+    fields: {
+      createdBy: relationship({
+        ref: userListKey,
+        ui: {
+          createView: { fieldMode: 'hidden' },
+          itemView: { fieldMode: 'read' },
+        },
+      }),
+      updatedBy: relationship({
+        ref: userListKey,
+        ui: {
+          createView: { fieldMode: 'hidden' },
+          itemView: { fieldMode: 'read' },
+        },
+      }),
+    },
+    hooks: {
+      resolveInput: async ({ operation, resolvedData, context }) => {
+        const userId = (context as any).session?.itemId
+        if (!userId) return resolvedData
+        if (operation === 'create') {
+          return {
+            ...resolvedData,
+            createdBy: resolvedData.createdBy ?? { connect: { id: userId } },
+            updatedBy: resolvedData.updatedBy ?? { connect: { id: userId } },
+          }
+        }
+        if (operation === 'update') {
+          return {
+            ...resolvedData,
+            updatedBy: resolvedData.updatedBy ?? { connect: { id: userId } },
+          }
+        }
+        return resolvedData
+      },
+    },
+  }
+}
+
+/**
+ * Factory for building reusable field group mixins.
+ *
+ * @example
+ * const withAddress = createMixin({
+ *   street: text(),
+ *   city: text(),
+ *   postcode: text({ validation: validators.regex(/^\d{4}$/, 'Must be a 4-digit postcode') }),
+ * })
+ */
+export function createMixin(
+  fields: Record<string, any>,
+  hooks?: Partial<ListHooks<any>>
+): ListMixin {
+  return { fields, hooks }
+}
+
+// ================================================================
+// defineList — a typed wrapper around list() with mixin support
+// ================================================================
+
+type DefineListConfig<ListTypeInfo extends BaseListTypeInfo> = ListConfig<ListTypeInfo> & {
+  /**
+   * Mixins to apply to this list. Mixin fields are merged before user fields,
+   * so user fields always take precedence on key conflicts.
+   */
+  mixins?: ListMixin[]
+}
+
+/**
+ * Defines a list with optional mixins for reusable field groups and hooks.
+ *
+ * @example
+ * export const Post = defineList({
+ *   mixins: [withTimestamps()],
+ *   fields: {
+ *     title: text({ validation: validators.required }),
+ *     content: text(),
+ *   },
+ * })
+ */
+export function defineList<ListTypeInfo extends BaseListTypeInfo>(
+  config: DefineListConfig<ListTypeInfo>
+): ListConfig<ListTypeInfo> {
+  const { mixins = [], ...listConfig } = config
+
+  const mixinFields: Record<string, any> = {}
+  const mixinHooksList: Array<Partial<ListHooks<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>>)
+
+  return list({
+    ...listConfig,
+    fields: {
+      ...mixinFields,
+      ...listConfig.fields,
+    } as BaseFields<ListTypeInfo>,
+    hooks: mergedHooks as ListConfig<ListTypeInfo>['hooks'],
+  } as ListConfig<ListTypeInfo>)
+}
+
+type AnyResolveInput =
+  | ((args: any) => any)
+  | { create?: (args: any) => any; update?: (args: any) => any }
+
+function expandResolveInput(hook: AnyResolveInput) {
+  return typeof hook === 'function' ? { create: hook, update: hook } : hook
+}
+
+/**
+ * Compose two `resolveInput` hooks so the second runs on the `resolvedData` produced by the first.
+ * Handles both the function form and the `{ create, update }` object form, and treats a hook that
+ * returns `undefined` as "no change" (keeps the prior resolvedData) so chained mixins don't wipe data.
+ */
+function mergeResolveInput(
+  a: AnyResolveInput | undefined,
+  b: AnyResolveInput | undefined
+): AnyResolveInput | undefined {
+  if (!a) return b
+  if (!b) return a
+  const ea = expandResolveInput(a)
+  const eb = expandResolveInput(b)
+  const chain = (f?: (args: any) => any, g?: (args: any) => any) => {
+    if (!f) return g
+    if (!g) return f
+    return async (args: any) => {
+      const first = await f(args)
+      const resolvedData = first === undefined ? args.resolvedData : first
+      const second = await g({ ...args, resolvedData })
+      return second === undefined ? resolvedData : second
+    }
+  }
+  return {
+    create: chain(ea.create, eb.create),
+    update: chain(ea.update, eb.update),
+  }
+}
+
+/**
+ * Merge mixin hooks with the list's own hooks. Each Keystone 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 ?? {}
+
+  const all = [...mixinHooks, ...(listHooks ? [listHooks] : [])]
+  const merged: Partial<ListHooks<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']
+    merged.beforeOperation = merge(
+      merged.beforeOperation as any,
+      hooks.beforeOperation as any
+    ) as ListHooks<any>['beforeOperation']
+    merged.afterOperation = merge(
+      merged.afterOperation as any,
+      hooks.afterOperation as any
+    ) as ListHooks<any>['afterOperation']
+  }
+
+  return merged
+}
+
+// ================================================================
+// defineConfig — typed alias for config()
+// ================================================================
+
+/**
+ * Defines the Nixxie configuration. This is a typed alias for `config()` that
+ * provides the same functionality with a more declarative name.
+ *
+ * @example
+ * export default defineConfig({
+ *   db: { provider: 'sqlite', url: 'file:./nixxie.db' },
+ *   lists: { Post, User },
+ * })
+ */
+export function defineConfig<TypeInfo extends BaseNixxieTypeInfo>(
+  nixxieConfig: NixxieConfigPre<TypeInfo>
+): NixxieConfig<TypeInfo> {
+  return config(nixxieConfig)
+}
+
+// ================================================================
+// defineAction — typed alias for action()
+// ================================================================
+
+/**
+ * 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)
+}