@nixxie-cms/core 1.0.3 → 1.1.0

package/src/types/config/lists.ts

@@ -1,565 +1,606 @@
-import type { CacheHint } from '@apollo/cache-control-types'
-import type { allIcons as KeystarIcons } from '@keystar/ui/icon/all'
-import type { GArg, InferValueFromArgs } from '@graphql-ts/schema'
-
-import type { NixxieContext } from '../context'
-import type { BaseListTypeInfo } from '../type-info'
-import type { MaybePromise } from '../utils'
-import type { ListAccessControl, ActionAccessControlFunction } from './access-control'
-import type { BaseFields, BaseFieldTypeInfo } from './fields'
-import type { ListHooks } from './hooks'
-
-export type ActionArgumentsConfig = Record<string, GArg<any, any>>
-
-export type ActionArgsConfig<ListTypeInfo extends BaseListTypeInfo> = Record<
-  string,
-  {
-    graphql: GArg<any, any>
-    ui?: {
-      source?: {
-        itemField: ListTypeInfo['fields']
-      }
-    }
-  }
->
-
-type ActionArgs<Args extends ActionArgsConfig<any> | undefined> =
-  Args extends ActionArgsConfig<any>
-    ? InferValueFromArgs<{ [K in keyof Args]: Args[K]['graphql'] }>
-    : Record<string, never>
-
-export type DeclaredAction<ListTypeInfo extends BaseListTypeInfo> = {
-  ___defineActionsWithActionFunction: true
-} & Action<ListTypeInfo, ActionArgsConfig<ListTypeInfo> | undefined>
-
-export type Action<
-  ListTypeInfo extends BaseListTypeInfo,
-  Args extends ActionArgsConfig<ListTypeInfo> | undefined,
-> = {
-  /**
-   * Controls who or what can use this action
-   * @see https://www.nixxieinternational.com/guides/auth-and-access-control
-   */
-  access: ActionAccessControlFunction<ListTypeInfo>
-  resolve: (
-    args: {
-      listKey: ListTypeInfo['key']
-      actionKey: ListTypeInfo['actions']
-      where: ListTypeInfo['inputs']['uniqueWhere']
-      args: ActionArgs<Args>
-    },
-    context: NixxieContext<ListTypeInfo['all']>
-  ) => MaybePromise<ListTypeInfo['item'] | null>
-  graphql?: {
-    /**
-     * The name of the singular mutation in the GraphQL schema
-     * @default {action}{list.graphql.singular}
-     */
-    singular?: string
-    /**
-     * The name of the plural mutation in the GraphQL schema
-     * @default {action}{list.graphql.plural}
-     */
-    plural?: string
-    /**
-     * The description added to the GraphQL schema
-     * @default empty
-     */
-    description?: string
-  }
-  /**
-   * Defines what arguments the action should accept as input.
-   * @experimental This feature is not yet stable.
-   */
-  args?: Args
-  ui: {
-    /**
-     * The label used to identify the action in the Admin UI.
-     */
-    label: string
-
-    /**
-     * The icon name used to represent the action in the Admin UI.
-     * @default null
-     */
-    icon?: keyof typeof KeystarIcons | null
-
-    /**
-     * The style used for the success message in the Admin UI.
-     * @default 'neutral'
-     */
-    // TODO: ? maybe ?
-    // result?: 'positive' | 'info' | 'neutral' | 'critical'
-
-    /**
-     * The locale messages used in the Admin UI, with support for the following template tags:
-     * - {label}: The action label in lowercase
-     * - {Label}: The action label as-is
-     * - {singular}: Uses {list}.ui.singular
-     * - {plural}: Uses {list}.ui.plural
-     * - {singular|plural}: Uses {list}.ui.singular if {count} is 1, otherwise uses {list}.ui.plural
-     * - {itemLabel}: The label of the item being acted upon
-     * - {count}: The number of items being acted upon
-     * - {countSuccess}: The number of items successfully acted upon
-     * - {countFail}: The number of items that failed to be acted upon
-     */
-    messages?: {
-      promptTitle?: string
-      promptTitleMany?: string
-      prompt?: string
-      promptMany?: string
-      promptConfirmLabel?: string
-      promptConfirmLabelMany?: string
-      fail?: string
-      failMany?: string
-      success?: string
-      successMany?: string
-    }
-
-    itemView?: {
-      /**
-       * Controls the action mode for this action in the item view in the Admin UI.
-       * @default 'enabled'
-       */
-      actionMode?: MaybeItemActionFunctionWithFilter<
-        'enabled' | 'disabled' | 'hidden',
-        'disabled' | 'hidden',
-        ListTypeInfo
-      >
-      /**
-       * Controls the navigation behaviour after the action completes in the item view in the Admin UI.
-       * @default 'follow'
-       */
-      navigation?: 'follow' | 'refetch' | 'return'
-
-      /**
-       * Controls whether to show a prompt prior to the action in the item view in the Admin UI.
-       * @default false
-       */
-      hidePrompt?: boolean
-
-      /**
-       * Controls whether to show a toast notification after completing the action in the item view in the Admin UI.
-       * @default false
-       */
-      hideToast?: boolean
-    }
-    listView?: {
-      /**
-       * Controls the action mode for this action in the list view in the Admin UI.
-       * @default 'enabled'
-       */
-      actionMode?: MaybeSessionFunctionWithFilter<
-        'enabled' | 'disabled' | 'hidden',
-        'disabled' | 'hidden',
-        ListTypeInfo
-      >
-    }
-  }
-}
-
-export type BaseActions<ListTypeInfo extends BaseListTypeInfo> = {
-  /**
-   * The key of the action, by default this is used to prefix the mutation in the GraphQL schema
-   */
-  [action: string]: DeclaredAction<ListTypeInfo>
-}
-
-export type ListConfig<ListTypeInfo extends BaseListTypeInfo> = {
-  /**
-   * Controls what data users of the Admin UI and GraphQL can access and change
-   * @see https://nixxieinternational.com/guides/auth-and-access-control
-   */
-  access: ListAccessControl<ListTypeInfo>
-
-  fields: BaseFields<ListTypeInfo>
-  actions?: BaseActions<ListTypeInfo>
-
-  /** Options for how this list should show in the Admin UI */
-  ui?: ListAdminUIConfig<ListTypeInfo>
-
-  /**
-   * Hooks to modify the behaviour of GraphQL operations at certain points
-   * @see https://nixxieinternational.com/guides/hooks
-   */
-  hooks?: ListHooks<ListTypeInfo>
-
-  graphql?: ListGraphQLConfig<ListTypeInfo>
-
-  db?: ListDBConfig
-
-  /**
-   * Controls if this list is a singleton
-   * @see https://nixxieinternational.com/docs/config/lists#is-singleton
-   */
-  isSingleton?: boolean
-
-  /**
-   * The default value to use for graphql.isEnabled.filter on all fields for this list
-   */
-  defaultIsFilterable?: MaybeFieldFunction<ListTypeInfo>
-
-  /**
-   * The default value to use for graphql.isEnabled.orderBy on all fields for this list
-   */
-  defaultIsOrderable?: MaybeFieldFunction<ListTypeInfo>
-}
-
-export type ListSortDescriptor<Fields extends string> = {
-  field: 'id' | Fields
-  direction: 'ASC' | 'DESC'
-}
-
-export type ListAdminUIConfig<ListTypeInfo extends BaseListTypeInfo> = {
-  /**
-   * The label used to identify the list in navigation and etc.
-   * @default listKey.replace(/([a-z])([A-Z])/g, '$1 $2').split(/\s|_|\-/).filter(i => i).map(upcase).join(' ');
-   */
-  label?: string
-
-  /**
-   * The singular form of the list key.
-   *
-   * It is used in sentences like `Are you sure you want to delete these {plural}?`
-   * @default pluralize.singular(label)
-   */
-  singular?: string
-
-  /**
-   * The plural form of the list key.
-   *
-   * It is used in sentences like `Are you sure you want to delete this {singular}?`.
-   * @default pluralize.plural(label)
-   */
-  plural?: string
-
-  /**
-   * The path segment to identify the list in URLs.
-   *
-   * It must match the pattern `/^[a-z-_][a-z0-9-_]*$/`.
-   * @default label.split(' ').join('-').toLowerCase()
-   */
-  path?: string
-
-  /**
-   * The field to use as a label in the Admin UI. If you want to base the label off more than a single field, use a virtual field and reference that field here.
-   * @default 'label', if it exists, falling back to 'name', then 'title', and finally 'id', which is guaranteed to exist.
-   */
-  labelField?: 'id' | Exclude<ListTypeInfo['fields'], number>
-
-  /**
-   * The fields used by the Admin UI when searching this list.
-   * It is always possible to search by id and `id` should not be specified in this option.
-   * @default The `labelField` if it has a string `contains` filter, otherwise none.
-   */
-  searchFields?: ListTypeInfo['fields'][]
-
-  /**
-   * Hides this list from the Admin UI navigation, it only hides the list, you can still navigate directly.
-   * @default false
-   */
-  hideNavigation?: MaybeSessionFunction<boolean, ListTypeInfo>
-  /**
-   * Hides the create button in the Admin UI.
-   * Note that this does **not** disable creating items through the GraphQL API, it only hides the button to create an item for this list in the Admin UI.
-   * @default false
-   */
-  hideCreate?: MaybeSessionFunction<boolean, ListTypeInfo>
-  /**
-   * Hides the delete button in the Admin UI.
-   * Note that this does **not** disable deleting items through the GraphQL API, it only hides the button to delete an item for this list in the Admin UI.
-   * @default false
-   */
-  hideDelete?: MaybeSessionFunction<boolean, ListTypeInfo>
-  /**
-   * Configuration specific to the create view in the Admin UI
-   */
-  createView?: {
-    /**
-     * The default field mode for fields on the create view for this list.
-     * Specific field modes on a per-field basis via a field's config.
-     * @default 'edit'
-     */
-    defaultFieldMode?: MaybeSessionFunctionWithFilter<'edit' | 'hidden', 'hidden', ListTypeInfo>
-  }
-
-  /**
-   * Configuration specific to the item view in the Admin UI
-   */
-  itemView?: {
-    /**
-     * The default field mode for fields on the item view for this list.
-     * This controls what people can do for fields
-     * Specific field modes on a per-field basis via a field's config.
-     * @default 'edit'
-     */
-    defaultFieldMode?: MaybeItemFunctionWithFilter<
-      'edit' | 'read' | 'hidden',
-      'read' | 'hidden',
-      ListTypeInfo
-    >
-  }
-
-  /**
-   * Configuration specific to the list view in the Admin UI
-   */
-  listView?: {
-    /**
-     * The default field mode for fields on the list view for this list.
-     * Specific field modes on a per-field basis via a field's config.
-     * @default 'read'
-     */
-    defaultFieldMode?: MaybeSessionFunction<'read' | 'hidden', ListTypeInfo>
-    /**
-     * The columns(which refer to fields) that should be shown to users of the Admin UI.
-     * Users of the Admin UI can select different columns to show in the UI.
-     * @default the first three fields in the list
-     */
-    initialColumns?: readonly ('id' | ListTypeInfo['fields'])[]
-    initialFilter?: MaybeSessionFunction<
-      Omit<ListTypeInfo['inputs']['where'], 'AND' | 'OR' | 'NOT'>,
-      ListTypeInfo
-    >
-    initialSort?: ListSortDescriptor<ListTypeInfo['fields']>
-
-    // TODO: rename to initialItemsPerPage or initialPageSize?
-    pageSize?: number // default number of items to display per page on the list screen
-  }
-}
-
-export type MaybeFieldFunction<ListTypeInfo extends BaseListTypeInfo> =
-  | boolean
-  | ((args: {
-      context: NixxieContext<ListTypeInfo['all']>
-      session?: ListTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
-      listKey: ListTypeInfo['key']
-      fieldKey: ListTypeInfo['fields']
-    }) => MaybePromise<boolean>)
-
-export type MaybeSessionFunction<T, ListTypeInfo extends BaseListTypeInfo> =
-  | T
-  | ((args: {
-      context: NixxieContext<ListTypeInfo['all']>
-      session?: ListTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
-    }) => MaybePromise<T>)
-
-type ConditionalFilterFieldValue<Value> = {
-  equals?: Value
-  in?: Value[]
-  not?: {
-    equals?: Value
-    in?: Value[]
-  }
-}
-
-// this conditional type is to avoid inconvenient type errors
-// [] is just a placeholder for something that is never a valid BaseListTypeInfo so
-// ListTypeInfo must be `any`
-type ConditionalFilterObject<ListTypeInfo extends BaseListTypeInfo> = ListTypeInfo extends []
-  ? any
-  : {
-      AND?: ReadonlyArray<ConditionalFilterObject<ListTypeInfo>>
-      OR?: ReadonlyArray<ConditionalFilterObject<ListTypeInfo>>
-      NOT?: ConditionalFilterObject<ListTypeInfo>
-    } & {
-      [K in keyof ListTypeInfo['inputs']['update']]?: ConditionalFilterFieldValue<
-        ListTypeInfo['inputs']['update'][K]
-      >
-    }
-
-export type ConditionalFilterCase<ListTypeInfo extends BaseListTypeInfo> =
-  | boolean
-  | ConditionalFilterObject<ListTypeInfo>
-
-export type ConditionalFilter<
-  StaticState extends string,
-  Filterable extends string,
-  ListTypeInfo extends BaseListTypeInfo,
-> = StaticState | { [_ in Filterable]?: ConditionalFilterCase<ListTypeInfo> }
-
-export type MaybeSessionFunctionWithFilter<
-  StaticState extends string,
-  Filterable extends string,
-  ListTypeInfo extends BaseListTypeInfo,
-> =
-  | ConditionalFilter<StaticState, Filterable, ListTypeInfo>
-  | ((args: {
-      context: NixxieContext<ListTypeInfo['all']>
-      session?: NixxieContext<ListTypeInfo['all']>['session']
-    }) => MaybePromise<ConditionalFilter<StaticState, Filterable, ListTypeInfo>>)
-
-export type MaybeBooleanSessionFunctionWithFilter<ListTypeInfo extends BaseListTypeInfo> =
-  | ConditionalFilterCase<ListTypeInfo>
-  | ((args: {
-      context: NixxieContext<ListTypeInfo['all']>
-      session?: ListTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
-    }) => MaybePromise<ConditionalFilterCase<ListTypeInfo>>)
-
-export type MaybeBooleanItemFunctionWithFilter<
-  ListTypeInfo extends BaseListTypeInfo,
-  FieldTypeInfo extends BaseFieldTypeInfo,
-> =
-  | ConditionalFilterCase<ListTypeInfo>
-  | ((args: {
-      context: NixxieContext<ListTypeInfo['all']>
-      listKey: ListTypeInfo['key']
-      fieldKey: ListTypeInfo['fields']
-      item: ListTypeInfo['item'] | null
-      itemField: FieldTypeInfo['item'] | null
-      session?: ListTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
-    }) => MaybePromise<ConditionalFilterCase<ListTypeInfo>>)
-
-export type MaybeItemFieldFunctionWithFilter<
-  StaticState extends string,
-  Filterable extends string,
-  ListTypeInfo extends BaseListTypeInfo,
-  FieldTypeInfo extends BaseFieldTypeInfo,
-> =
-  | ConditionalFilter<StaticState, Filterable, ListTypeInfo>
-  | ((args: {
-      context: NixxieContext<ListTypeInfo['all']>
-      session?: ListTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
-      listKey: ListTypeInfo['key']
-      fieldKey: ListTypeInfo['fields']
-      item: ListTypeInfo['item'] | null
-      itemField: FieldTypeInfo['item'] | null
-    }) => MaybePromise<ConditionalFilter<StaticState, Filterable, ListTypeInfo>>)
-
-export type MaybeItemFieldFunction<
-  T,
-  ListTypeInfo extends BaseListTypeInfo,
-  FieldTypeInfo extends BaseFieldTypeInfo,
-> =
-  | T
-  | ((args: {
-      context: NixxieContext<ListTypeInfo['all']>
-      session?: ListTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
-      listKey: ListTypeInfo['key']
-      fieldKey: ListTypeInfo['fields']
-      item: ListTypeInfo['item'] | null
-      itemField: FieldTypeInfo['item'] | null
-    }) => MaybePromise<T>)
-
-export type MaybeItemFunctionWithFilter<
-  StaticState extends string,
-  Filterable extends string,
-  ListTypeInfo extends BaseListTypeInfo,
-> =
-  | ConditionalFilter<StaticState, Filterable, ListTypeInfo>
-  | ((args: {
-      context: NixxieContext<ListTypeInfo['all']>
-      session?: ListTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
-      listKey: ListTypeInfo['key']
-      item: ListTypeInfo['item'] | null
-    }) => MaybePromise<ConditionalFilter<StaticState, Filterable, ListTypeInfo>>)
-
-export type MaybeItemActionFunction<
-  T extends string,
-  ListTypeInfo extends BaseListTypeInfo,
-> = (args: {
-  context: NixxieContext<ListTypeInfo['all']>
-  session?: ListTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
-  listKey: ListTypeInfo['key']
-  actionKey: ListTypeInfo['actions']
-  item: ListTypeInfo['item'] | null
-}) => MaybePromise<T>
-
-export type MaybeItemActionFunctionWithFilter<
-  StaticState extends string,
-  Filterable extends string,
-  ListTypeInfo extends BaseListTypeInfo,
-> =
-  | ConditionalFilter<StaticState, Filterable, ListTypeInfo>
-  | ((args: {
-      context: NixxieContext<ListTypeInfo['all']>
-      session?: ListTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
-      listKey: ListTypeInfo['key']
-      actionKey: ListTypeInfo['actions']
-      item: ListTypeInfo['item'] | null
-    }) => MaybePromise<ConditionalFilter<StaticState, Filterable, ListTypeInfo>>)
-
-export type ListGraphQLConfig<ListTypeInfo extends BaseListTypeInfo> = {
-  /**
-   * The description added to the GraphQL schema
-   * @default empty
-   */
-  description?: string
-  /**
-   * The singular form of the list key to use in the generated GraphQL schema.
-   */
-  singular?: string
-  /**
-   * The plural form of the list key to use in the generated GraphQL schema.
-   */
-  plural?: string
-  /**
-   * The maximum value for the take parameter when querying this list
-   */
-  maxTake?: number
-  cacheHint?: ((args: CacheHintArgs<ListTypeInfo>) => CacheHint) | CacheHint
-  // Setting any of these values will remove the corresponding operations from the GraphQL schema.
-  // Queries:
-  //   'query':  Does item()/items() exist?
-  // Mutations:
-  //   'create': Does createItem/createItems exist? Does `create` exist on the RelationshipInput types?
-  //   'update': Does updateItem/updateItems exist?
-  //   'delete': Does deleteItem/deleteItems exist?
-  // If `true`, then everything will be omitted, including the output type. This makes it a DB only list,
-  // including from the point of view of relationships to this list.
-  //
-  // Default: undefined
-  omit?:
-    | boolean
-    | {
-        query?: boolean
-        create?: boolean
-        update?: boolean
-        delete?: boolean
-      }
-}
-
-export type CacheHintArgs<ListTypeInfo extends BaseListTypeInfo> =
-  | {
-      results: ListTypeInfo['item'][]
-      operationName?: string
-      meta: false
-    }
-  | {
-      results: number
-      operationName?: string
-      meta: true
-    }
-
-// TODO: duplicate, merge with next-fields?
-export type IdFieldConfig =
-  | {
-      kind: 'random'
-      type?: 'String'
-      bytes?: number
-      encoding?: 'hex' | 'base64url'
-    }
-  | { kind: 'string' | 'ulid'; type?: 'String' }
-  | { kind: 'cuid'; version?: 1 | 2; type?: 'String' }
-  | { kind: 'uuid'; version?: 4 | 7; type?: 'String' }
-  | { kind: 'nanoid'; length?: number; type?: 'String' }
-  | { kind: 'autoincrement'; type?: 'Int' | 'BigInt' }
-  | { kind: 'number'; type: 'Int' | 'BigInt' }
-
-export type ListDBConfig = {
-  /**
-   * The kind of id to use.
-   * @default { kind: "cuid" }
-   */
-  idField?: IdFieldConfig
-  /**
-   * Specifies an alternative name name for the table to use, if you don't want
-   * the default (derived from the list key)
-   */
-  map?: string
-  /**
-   * Customise the Prisma Schema for this list. This function is passed the
-   * Prisma Model for this list and should return a string containing the valid
-   * Prisma Model definition.
-   */
-  extendPrismaSchema?: (schema: string) => string
-}
+import type { CacheHint } from '@apollo/cache-control-types'
+import type { allIcons as KeystarIcons } from '@keystar/ui/icon/all'
+import type { GArg, InferValueFromArgs } from '@graphql-ts/schema'
+
+import type { NixxieContext } from '../context'
+import type { BaseCollectionTypeInfo } from '../type-info'
+import type { MaybePromise } from '../utils'
+import type { CollectionAccessControl, ActionAccessControlFunction } from './access-control'
+import type { BaseFields, BaseFieldTypeInfo } from './fields'
+import type { CollectionHooks } from './hooks'
+
+export type ActionArgumentsConfig = Record<string, GArg<any, any>>
+
+export type ActionArgsConfig<CollectionTypeInfo extends BaseCollectionTypeInfo> = Record<
+  string,
+  {
+    graphql: GArg<any, any>
+    ui?: {
+      source?: {
+        itemField: CollectionTypeInfo['fields']
+      }
+    }
+  }
+>
+
+type ActionArgs<Args extends ActionArgsConfig<any> | undefined> =
+  Args extends ActionArgsConfig<any>
+    ? InferValueFromArgs<{ [K in keyof Args]: Args[K]['graphql'] }>
+    : Record<string, never>
+
+export type DeclaredAction<CollectionTypeInfo extends BaseCollectionTypeInfo> = {
+  ___defineActionsWithActionFunction: true
+} & Action<CollectionTypeInfo, ActionArgsConfig<CollectionTypeInfo> | undefined>
+
+export type Action<
+  CollectionTypeInfo extends BaseCollectionTypeInfo,
+  Args extends ActionArgsConfig<CollectionTypeInfo> | undefined,
+> = {
+  /**
+   * Controls who or what can use this action
+   * @see https://www.nixxieinternational.com/guides/auth-and-access-control
+   */
+  access: ActionAccessControlFunction<CollectionTypeInfo>
+  resolve: (
+    args: {
+      listKey: CollectionTypeInfo['key']
+      actionKey: CollectionTypeInfo['actions']
+      where: CollectionTypeInfo['inputs']['uniqueWhere']
+      args: ActionArgs<Args>
+    },
+    context: NixxieContext<CollectionTypeInfo['all']>
+  ) => MaybePromise<CollectionTypeInfo['item'] | null>
+  graphql?: {
+    /**
+     * The name of the singular mutation in the GraphQL schema
+     * @default {action}{list.graphql.singular}
+     */
+    singular?: string
+    /**
+     * The name of the plural mutation in the GraphQL schema
+     * @default {action}{list.graphql.plural}
+     */
+    plural?: string
+    /**
+     * The description added to the GraphQL schema
+     * @default empty
+     */
+    description?: string
+  }
+  /**
+   * Defines what arguments the action should accept as input.
+   * @experimental This feature is not yet stable.
+   */
+  args?: Args
+  ui: {
+    /**
+     * The label used to identify the action in the Admin UI.
+     */
+    label: string
+
+    /**
+     * The icon name used to represent the action in the Admin UI.
+     * @default null
+     */
+    icon?: keyof typeof KeystarIcons | null
+
+    /**
+     * The style used for the success message in the Admin UI.
+     * @default 'neutral'
+     */
+    // TODO: ? maybe ?
+    // result?: 'positive' | 'info' | 'neutral' | 'critical'
+
+    /**
+     * The locale messages used in the Admin UI, with support for the following template tags:
+     * - {label}: The action label in lowercase
+     * - {Label}: The action label as-is
+     * - {singular}: Uses {list}.ui.singular
+     * - {plural}: Uses {list}.ui.plural
+     * - {singular|plural}: Uses {list}.ui.singular if {count} is 1, otherwise uses {list}.ui.plural
+     * - {itemLabel}: The label of the item being acted upon
+     * - {count}: The number of items being acted upon
+     * - {countSuccess}: The number of items successfully acted upon
+     * - {countFail}: The number of items that failed to be acted upon
+     */
+    messages?: {
+      promptTitle?: string
+      promptTitleMany?: string
+      prompt?: string
+      promptMany?: string
+      promptConfirmLabel?: string
+      promptConfirmLabelMany?: string
+      fail?: string
+      failMany?: string
+      success?: string
+      successMany?: string
+    }
+
+    itemView?: {
+      /**
+       * Controls the action mode for this action in the item view in the Admin UI.
+       * @default 'enabled'
+       */
+      actionMode?: MaybeItemActionFunctionWithFilter<
+        'enabled' | 'disabled' | 'hidden',
+        'disabled' | 'hidden',
+        CollectionTypeInfo
+      >
+      /**
+       * Controls the navigation behaviour after the action completes in the item view in the Admin UI.
+       * @default 'follow'
+       */
+      navigation?: 'follow' | 'refetch' | 'return'
+
+      /**
+       * Controls whether to show a prompt prior to the action in the item view in the Admin UI.
+       * @default false
+       */
+      hidePrompt?: boolean
+
+      /**
+       * Controls whether to show a toast notification after completing the action in the item view in the Admin UI.
+       * @default false
+       */
+      hideToast?: boolean
+    }
+    listView?: {
+      /**
+       * Controls the action mode for this action in the list view in the Admin UI.
+       * @default 'enabled'
+       */
+      actionMode?: MaybeSessionFunctionWithFilter<
+        'enabled' | 'disabled' | 'hidden',
+        'disabled' | 'hidden',
+        CollectionTypeInfo
+      >
+    }
+  }
+}
+
+export type BaseActions<CollectionTypeInfo extends BaseCollectionTypeInfo> = {
+  /**
+   * The key of the action, by default this is used to prefix the mutation in the GraphQL schema
+   */
+  [action: string]: DeclaredAction<CollectionTypeInfo>
+}
+
+/** What to do with related records when an item in this collection is deleted. */
+export type CascadeAction = 'delete' | 'setNull' | 'restrict' | 'softDelete'
+
+/**
+ * A referential-integrity rule enacted when an item of this collection is deleted.
+ * Rules run inside the delete pipeline through the normal mutation APIs, so the target
+ * collections' own hooks, events and cascade rules all fire (cascades recurse, with
+ * cycle protection).
+ *
+ * @example
+ * cascade: [
+ *   { collection: 'Comment', field: 'post', action: 'delete' },
+ *   { collection: 'Draft', field: 'original', action: 'setNull' },
+ *   { collection: 'Order', field: 'product', action: 'restrict' },
+ * ]
+ */
+export type CascadeRule = {
+  /** Target collection holding the related records. */
+  collection: string
+  /** Relationship field on the target collection that points at this collection. */
+  field: string
+  /**
+   * - `'delete'` — delete the related records (recursing into their own cascade rules)
+   * - `'setNull'` — disconnect the relationship, keeping the records
+   * - `'restrict'` — refuse the delete while related records exist
+   * - `'softDelete'` — stamp the records' `softDeleteField` instead of deleting
+   * @default 'delete'
+   */
+  action?: CascadeAction
+  /** Set when `field` on the target collection is a many-relationship. @default false */
+  many?: boolean
+  /** Timestamp field stamped by `'softDelete'`. @default 'deletedAt' */
+  softDeleteField?: string
+}
+
+export type CollectionConfig<CollectionTypeInfo extends BaseCollectionTypeInfo> = {
+  /**
+   * Controls what data users of the Admin UI and GraphQL can access and change
+   * @see https://nixxieinternational.com/guides/auth-and-access-control
+   */
+  access: CollectionAccessControl<CollectionTypeInfo>
+
+  /**
+   * Referential-integrity rules enacted when items of this collection are deleted.
+   * Use `previewDelete()` to compute what a delete would affect before running it.
+   */
+  cascade?: CascadeRule[]
+
+  fields: BaseFields<CollectionTypeInfo>
+  actions?: BaseActions<CollectionTypeInfo>
+
+  /** Options for how this list should show in the Admin UI */
+  ui?: CollectionAdminUIConfig<CollectionTypeInfo>
+
+  /**
+   * Hooks to modify the behaviour of GraphQL operations at certain points
+   * @see https://nixxieinternational.com/guides/hooks
+   */
+  hooks?: CollectionHooks<CollectionTypeInfo>
+
+  graphql?: CollectionGraphQLConfig<CollectionTypeInfo>
+
+  db?: CollectionDBConfig
+
+  /**
+   * Controls if this list is a singleton
+   * @see https://nixxieinternational.com/docs/config/lists#is-singleton
+   */
+  isSingleton?: boolean
+
+  /**
+   * The default value to use for graphql.isEnabled.filter on all fields for this list
+   */
+  defaultIsFilterable?: MaybeFieldFunction<CollectionTypeInfo>
+
+  /**
+   * The default value to use for graphql.isEnabled.orderBy on all fields for this list
+   */
+  defaultIsOrderable?: MaybeFieldFunction<CollectionTypeInfo>
+}
+
+export type CollectionSortDescriptor<Fields extends string> = {
+  field: 'id' | Fields
+  direction: 'ASC' | 'DESC'
+}
+
+export type CollectionAdminUIConfig<CollectionTypeInfo extends BaseCollectionTypeInfo> = {
+  /**
+   * The label used to identify the list in navigation and etc.
+   * @default listKey.replace(/([a-z])([A-Z])/g, '$1 $2').split(/\s|_|\-/).filter(i => i).map(upcase).join(' ');
+   */
+  label?: string
+
+  /**
+   * The singular form of the list key.
+   *
+   * It is used in sentences like `Are you sure you want to delete these {plural}?`
+   * @default pluralize.singular(label)
+   */
+  singular?: string
+
+  /**
+   * The plural form of the list key.
+   *
+   * It is used in sentences like `Are you sure you want to delete this {singular}?`.
+   * @default pluralize.plural(label)
+   */
+  plural?: string
+
+  /**
+   * The path segment to identify the list in URLs.
+   *
+   * It must match the pattern `/^[a-z-_][a-z0-9-_]*$/`.
+   * @default label.split(' ').join('-').toLowerCase()
+   */
+  path?: string
+
+  /**
+   * The field to use as a label in the Admin UI. If you want to base the label off more than a single field, use a virtual field and reference that field here.
+   * @default 'label', if it exists, falling back to 'name', then 'title', and finally 'id', which is guaranteed to exist.
+   */
+  labelField?: 'id' | Exclude<CollectionTypeInfo['fields'], number>
+
+  /**
+   * The fields used by the Admin UI when searching this list.
+   * It is always possible to search by id and `id` should not be specified in this option.
+   * @default The `labelField` if it has a string `contains` filter, otherwise none.
+   */
+  searchFields?: CollectionTypeInfo['fields'][]
+
+  /**
+   * Hides this list from the Admin UI navigation, it only hides the list, you can still navigate directly.
+   * @default false
+   */
+  hideNavigation?: MaybeSessionFunction<boolean, CollectionTypeInfo>
+  /**
+   * Hides the create button in the Admin UI.
+   * Note that this does **not** disable creating items through the GraphQL API, it only hides the button to create an item for this list in the Admin UI.
+   * @default false
+   */
+  hideCreate?: MaybeSessionFunction<boolean, CollectionTypeInfo>
+  /**
+   * Hides the delete button in the Admin UI.
+   * Note that this does **not** disable deleting items through the GraphQL API, it only hides the button to delete an item for this list in the Admin UI.
+   * @default false
+   */
+  hideDelete?: MaybeSessionFunction<boolean, CollectionTypeInfo>
+  /**
+   * Configuration specific to the create view in the Admin UI
+   */
+  createView?: {
+    /**
+     * The default field mode for fields on the create view for this list.
+     * Specific field modes on a per-field basis via a field's config.
+     * @default 'edit'
+     */
+    defaultFieldMode?: MaybeSessionFunctionWithFilter<'edit' | 'hidden', 'hidden', CollectionTypeInfo>
+  }
+
+  /**
+   * Configuration specific to the item view in the Admin UI
+   */
+  itemView?: {
+    /**
+     * The default field mode for fields on the item view for this list.
+     * This controls what people can do for fields
+     * Specific field modes on a per-field basis via a field's config.
+     * @default 'edit'
+     */
+    defaultFieldMode?: MaybeItemFunctionWithFilter<
+      'edit' | 'read' | 'hidden',
+      'read' | 'hidden',
+      CollectionTypeInfo
+    >
+  }
+
+  /**
+   * Configuration specific to the list view in the Admin UI
+   */
+  listView?: {
+    /**
+     * The default field mode for fields on the list view for this list.
+     * Specific field modes on a per-field basis via a field's config.
+     * @default 'read'
+     */
+    defaultFieldMode?: MaybeSessionFunction<'read' | 'hidden', CollectionTypeInfo>
+    /**
+     * The columns(which refer to fields) that should be shown to users of the Admin UI.
+     * Users of the Admin UI can select different columns to show in the UI.
+     * @default the first three fields in the list
+     */
+    initialColumns?: readonly ('id' | CollectionTypeInfo['fields'])[]
+    initialFilter?: MaybeSessionFunction<
+      Omit<CollectionTypeInfo['inputs']['where'], 'AND' | 'OR' | 'NOT'>,
+      CollectionTypeInfo
+    >
+    initialSort?: CollectionSortDescriptor<CollectionTypeInfo['fields']>
+
+    // TODO: rename to initialItemsPerPage or initialPageSize?
+    pageSize?: number // default number of items to display per page on the list screen
+  }
+}
+
+export type MaybeFieldFunction<CollectionTypeInfo extends BaseCollectionTypeInfo> =
+  | boolean
+  | ((args: {
+      context: NixxieContext<CollectionTypeInfo['all']>
+      session?: CollectionTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
+      listKey: CollectionTypeInfo['key']
+      fieldKey: CollectionTypeInfo['fields']
+    }) => MaybePromise<boolean>)
+
+export type MaybeSessionFunction<T, CollectionTypeInfo extends BaseCollectionTypeInfo> =
+  | T
+  | ((args: {
+      context: NixxieContext<CollectionTypeInfo['all']>
+      session?: CollectionTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
+    }) => MaybePromise<T>)
+
+type ConditionalFilterFieldValue<Value> = {
+  equals?: Value
+  in?: Value[]
+  not?: {
+    equals?: Value
+    in?: Value[]
+  }
+}
+
+// this conditional type is to avoid inconvenient type errors
+// [] is just a placeholder for something that is never a valid BaseCollectionTypeInfo so
+// CollectionTypeInfo must be `any`
+type ConditionalFilterObject<CollectionTypeInfo extends BaseCollectionTypeInfo> = CollectionTypeInfo extends []
+  ? any
+  : {
+      AND?: ReadonlyArray<ConditionalFilterObject<CollectionTypeInfo>>
+      OR?: ReadonlyArray<ConditionalFilterObject<CollectionTypeInfo>>
+      NOT?: ConditionalFilterObject<CollectionTypeInfo>
+    } & {
+      [K in keyof CollectionTypeInfo['inputs']['update']]?: ConditionalFilterFieldValue<
+        CollectionTypeInfo['inputs']['update'][K]
+      >
+    }
+
+export type ConditionalFilterCase<CollectionTypeInfo extends BaseCollectionTypeInfo> =
+  | boolean
+  | ConditionalFilterObject<CollectionTypeInfo>
+
+export type ConditionalFilter<
+  StaticState extends string,
+  Filterable extends string,
+  CollectionTypeInfo extends BaseCollectionTypeInfo,
+> = StaticState | { [_ in Filterable]?: ConditionalFilterCase<CollectionTypeInfo> }
+
+export type MaybeSessionFunctionWithFilter<
+  StaticState extends string,
+  Filterable extends string,
+  CollectionTypeInfo extends BaseCollectionTypeInfo,
+> =
+  | ConditionalFilter<StaticState, Filterable, CollectionTypeInfo>
+  | ((args: {
+      context: NixxieContext<CollectionTypeInfo['all']>
+      session?: NixxieContext<CollectionTypeInfo['all']>['session']
+    }) => MaybePromise<ConditionalFilter<StaticState, Filterable, CollectionTypeInfo>>)
+
+export type MaybeBooleanSessionFunctionWithFilter<CollectionTypeInfo extends BaseCollectionTypeInfo> =
+  | ConditionalFilterCase<CollectionTypeInfo>
+  | ((args: {
+      context: NixxieContext<CollectionTypeInfo['all']>
+      session?: CollectionTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
+    }) => MaybePromise<ConditionalFilterCase<CollectionTypeInfo>>)
+
+export type MaybeBooleanItemFunctionWithFilter<
+  CollectionTypeInfo extends BaseCollectionTypeInfo,
+  FieldTypeInfo extends BaseFieldTypeInfo,
+> =
+  | ConditionalFilterCase<CollectionTypeInfo>
+  | ((args: {
+      context: NixxieContext<CollectionTypeInfo['all']>
+      listKey: CollectionTypeInfo['key']
+      fieldKey: CollectionTypeInfo['fields']
+      item: CollectionTypeInfo['item'] | null
+      itemField: FieldTypeInfo['item'] | null
+      session?: CollectionTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
+    }) => MaybePromise<ConditionalFilterCase<CollectionTypeInfo>>)
+
+export type MaybeItemFieldFunctionWithFilter<
+  StaticState extends string,
+  Filterable extends string,
+  CollectionTypeInfo extends BaseCollectionTypeInfo,
+  FieldTypeInfo extends BaseFieldTypeInfo,
+> =
+  | ConditionalFilter<StaticState, Filterable, CollectionTypeInfo>
+  | ((args: {
+      context: NixxieContext<CollectionTypeInfo['all']>
+      session?: CollectionTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
+      listKey: CollectionTypeInfo['key']
+      fieldKey: CollectionTypeInfo['fields']
+      item: CollectionTypeInfo['item'] | null
+      itemField: FieldTypeInfo['item'] | null
+    }) => MaybePromise<ConditionalFilter<StaticState, Filterable, CollectionTypeInfo>>)
+
+export type MaybeItemFieldFunction<
+  T,
+  CollectionTypeInfo extends BaseCollectionTypeInfo,
+  FieldTypeInfo extends BaseFieldTypeInfo,
+> =
+  | T
+  | ((args: {
+      context: NixxieContext<CollectionTypeInfo['all']>
+      session?: CollectionTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
+      listKey: CollectionTypeInfo['key']
+      fieldKey: CollectionTypeInfo['fields']
+      item: CollectionTypeInfo['item'] | null
+      itemField: FieldTypeInfo['item'] | null
+    }) => MaybePromise<T>)
+
+export type MaybeItemFunctionWithFilter<
+  StaticState extends string,
+  Filterable extends string,
+  CollectionTypeInfo extends BaseCollectionTypeInfo,
+> =
+  | ConditionalFilter<StaticState, Filterable, CollectionTypeInfo>
+  | ((args: {
+      context: NixxieContext<CollectionTypeInfo['all']>
+      session?: CollectionTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
+      listKey: CollectionTypeInfo['key']
+      item: CollectionTypeInfo['item'] | null
+    }) => MaybePromise<ConditionalFilter<StaticState, Filterable, CollectionTypeInfo>>)
+
+export type MaybeItemActionFunction<
+  T extends string,
+  CollectionTypeInfo extends BaseCollectionTypeInfo,
+> = (args: {
+  context: NixxieContext<CollectionTypeInfo['all']>
+  session?: CollectionTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
+  listKey: CollectionTypeInfo['key']
+  actionKey: CollectionTypeInfo['actions']
+  item: CollectionTypeInfo['item'] | null
+}) => MaybePromise<T>
+
+export type MaybeItemActionFunctionWithFilter<
+  StaticState extends string,
+  Filterable extends string,
+  CollectionTypeInfo extends BaseCollectionTypeInfo,
+> =
+  | ConditionalFilter<StaticState, Filterable, CollectionTypeInfo>
+  | ((args: {
+      context: NixxieContext<CollectionTypeInfo['all']>
+      session?: CollectionTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
+      listKey: CollectionTypeInfo['key']
+      actionKey: CollectionTypeInfo['actions']
+      item: CollectionTypeInfo['item'] | null
+    }) => MaybePromise<ConditionalFilter<StaticState, Filterable, CollectionTypeInfo>>)
+
+export type CollectionGraphQLConfig<CollectionTypeInfo extends BaseCollectionTypeInfo> = {
+  /**
+   * The description added to the GraphQL schema
+   * @default empty
+   */
+  description?: string
+  /**
+   * The singular form of the list key to use in the generated GraphQL schema.
+   */
+  singular?: string
+  /**
+   * The plural form of the list key to use in the generated GraphQL schema.
+   */
+  plural?: string
+  /**
+   * The maximum value for the take parameter when querying this list
+   */
+  maxTake?: number
+  cacheHint?: ((args: CacheHintArgs<CollectionTypeInfo>) => CacheHint) | CacheHint
+  // Setting any of these values will remove the corresponding operations from the GraphQL schema.
+  // Queries:
+  //   'query':  Does item()/items() exist?
+  // Mutations:
+  //   'create': Does createItem/createItems exist? Does `create` exist on the RelationshipInput types?
+  //   'update': Does updateItem/updateItems exist?
+  //   'delete': Does deleteItem/deleteItems exist?
+  // If `true`, then everything will be omitted, including the output type. This makes it a DB only list,
+  // including from the point of view of relationships to this list.
+  //
+  // Default: undefined
+  omit?:
+    | boolean
+    | {
+        query?: boolean
+        create?: boolean
+        update?: boolean
+        delete?: boolean
+      }
+}
+
+export type CacheHintArgs<CollectionTypeInfo extends BaseCollectionTypeInfo> =
+  | {
+      results: CollectionTypeInfo['item'][]
+      operationName?: string
+      meta: false
+    }
+  | {
+      results: number
+      operationName?: string
+      meta: true
+    }
+
+// TODO: duplicate, merge with next-fields?
+export type IdFieldConfig =
+  | {
+      kind: 'random'
+      type?: 'String'
+      bytes?: number
+      encoding?: 'hex' | 'base64url'
+    }
+  | { kind: 'string' | 'ulid'; type?: 'String' }
+  | { kind: 'cuid'; version?: 1 | 2; type?: 'String' }
+  | { kind: 'uuid'; version?: 4 | 7; type?: 'String' }
+  | { kind: 'nanoid'; length?: number; type?: 'String' }
+  | { kind: 'autoincrement'; type?: 'Int' | 'BigInt' }
+  | { kind: 'number'; type: 'Int' | 'BigInt' }
+
+export type CollectionDBConfig = {
+  /**
+   * The kind of id to use.
+   * @default { kind: "cuid" }
+   */
+  idField?: IdFieldConfig
+  /**
+   * Specifies an alternative name name for the table to use, if you don't want
+   * the default (derived from the list key)
+   */
+  map?: string
+  /**
+   * Customise the Prisma Schema for this list. This function is passed the
+   * Prisma Model for this list and should return a string containing the valid
+   * Prisma Model definition.
+   */
+  extendPrismaSchema?: (schema: string) => string
+}