@nixxie-cms/core 1.0.0

package/src/helpers.ts

@@ -0,0 +1,316 @@
+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)
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export { list, config, group, action } from './schema'
+export type { ListConfig, BaseFields } from './types'
+export {
+  defineList,
+  defineConfig,
+  defineAction,
+  withTimestamps,
+  withSoftDelete,
+  withAudit,
+  createMixin,
+  validators,
+} from './helpers'
+export type { ListMixin } from './helpers'
+// this re-exports `g` and `graphql`
+// note the usage of export * over explicitly listing the exports
+// is intentional here so that users can use "Rename Symbol" to
+// change their usage of `graphql` to `g` in their project
+// if this was an explicit list, it would change the re-export here
+// rather than the usage in their project
+export * from './types/schema'