@opensaas/stack-core 0.30.0 → 0.31.0

package/src/context/index.ts

@@ -24,6 +24,61 @@ export type ServerActionProps =
   | { listKey: string; action: 'create'; data: Record<string, unknown> }
   | { listKey: string; action: 'update'; id: string; data: Record<string, unknown> }
   | { listKey: string; action: 'delete'; id: string }
+  | { listKey: string; action: 'bulkDelete'; ids: string[] }
+  // Custom list-specific Bulk action (issue #736). `key` names an action
+  // declared in the list's `ui.listView.bulkActions`; the client only ever
+  // sends this serialisable `{ key, ids }` — the server-side `handler`
+  // (never serialised) is looked up by `key` and run with the rebuilt secured
+  // context over `ids`. Returns a distinct `{ bulkAction, message? }` shape so
+  // a redirect-on-`success` wrapper never hijacks it (same rationale as
+  // `bulkDelete`).
+  | { listKey: string; action: 'bulkAction'; key: string; ids: string[] }
+  // Relationship-table row removal (ADR-0018, #739). `listKey`/`id` target the
+  // RELATED row, so the related list's own access control + hooks apply (never
+  // the parent's). `mode: 'disconnect'` unlinks the row non-destructively by
+  // disconnecting its back-reference (`field`; `parentId` is the record being
+  // edited, needed only when that back-reference is to-many, e.g. a
+  // many-to-many join); `mode: 'delete'` truly deletes the row. Like
+  // `bulkDelete`, it returns a distinct `{ removed }` shape (never a
+  // single-op `success`) so a UI wrapper that redirects on `success` — the
+  // item-form pattern — does not hijack an in-place row removal.
+  | {
+      listKey: string
+      action: 'removeRelated'
+      mode: 'disconnect' | 'delete'
+      id: string
+      field?: string
+      parentId?: string
+    }
+  // Relationship-table inline cell edit (issue #737). `listKey`/`id` target the
+  // RELATED row and `field`/`value` a single scalar field on it, so the update
+  // runs through the related list's OWN operation- and field-level access +
+  // hooks/validation (never the parent's) — the same ADR-0018 boundary as
+  // `removeRelated`. It returns a distinct `{ updated }` shape (never a
+  // single-op `success`) so a UI wrapper that redirects on `success` — the
+  // item-form pattern — cannot hijack an in-place cell edit.
+  | {
+      listKey: string
+      action: 'updateRelated'
+      id: string
+      field: string
+      value: unknown
+    }
+  // Relationship-table pre-linked create (issue #738). `listKey` targets the
+  // RELATED list, so the related list's own create access control + hooks apply
+  // (never the parent's) — the same ADR-0018 boundary as `removeRelated`. The
+  // back-reference to the parent is set on the SERVER from `field`/`parentId`
+  // (never trusted from `data`), so the new row is linked to exactly the parent
+  // being edited. It returns a distinct `{ created }` shape (never a single-op
+  // `success`) so a UI wrapper that redirects on `success` — the item-form
+  // pattern — does not hijack an in-place create.
+  | {
+      listKey: string
+      action: 'createRelated'
+      data: Record<string, unknown>
+      field?: string
+      parentId?: string
+    }
   | {
       listKey: string
       action: 'relationshipOptions'
@@ -409,11 +464,33 @@ export function getContext<
 
   // Generic server action handler with discriminated union for type safety
   // Returns a result object instead of throwing to work properly in Next.js production
-  async function serverAction(
-    props: ServerActionProps,
-  ): Promise<
+  async function serverAction(props: ServerActionProps): Promise<
     | { success: true; data: unknown }
     | { success: false; error: string; fieldErrors?: Record<string, string> }
+    // Bulk actions report a count rather than a single-op `success` flag: the
+    // shape is deliberately distinct so a UI wrapper that redirects on a
+    // single-item `success` (the item-form pattern) does not hijack a
+    // list-level bulk operation.
+    | { deleted: number; total: number }
+    // Relationship-table row removal reports `removed` (with an optional reason)
+    // rather than `success` — same distinct-shape rationale as `bulkDelete`, so
+    // an in-place removal never triggers a redirect-on-success wrapper.
+    | { removed: boolean; error?: string }
+    // Relationship-table pre-linked create reports `created` (with the new row's
+    // id, or an error + fieldErrors for the drawer) rather than `success` — same
+    // distinct-shape rationale, so an in-place create never triggers a
+    // redirect-on-success wrapper.
+    | { created: boolean; id?: string; error?: string; fieldErrors?: Record<string, string> }
+    // Custom Bulk action (issue #736) reports `bulkAction` with the handler's
+    // optional `message` (success) or an `error` (not found / denied / threw) —
+    // again a distinct shape from single-op `success`.
+    | { bulkAction: true; message?: string }
+    | { bulkAction: false; error: string }
+    // Relationship-table inline cell edit reports `updated` (with an optional
+    // reason + fieldErrors for the edited cell) rather than `success` — same
+    // distinct-shape rationale, so an in-place cell edit never triggers a
+    // redirect-on-success wrapper.
+    | { updated: boolean; error?: string; fieldErrors?: Record<string, string> }
   > {
     const dbKey = getDbKey(props.listKey)
     const listConfig = config.lists[props.listKey]
@@ -431,6 +508,211 @@ export function getContext<
       delete: (args: { where: { id: string } }) => Promise<unknown>
     }
 
+    // Bulk delete: remove each id row-by-row through the secured context,
+    // honouring Silent failure — a denied (or missing) row returns `null` and is
+    // simply not counted. Returns "N of M" so partial denials are visible without
+    // revealing which rows were denied or why. One row's error never aborts the
+    // rest.
+    if (props.action === 'bulkDelete') {
+      let deleted = 0
+      for (const id of props.ids) {
+        try {
+          const result = await model.delete({ where: { id } })
+          if (result !== null && result !== undefined) deleted++
+        } catch {
+          // Skip this row (e.g. a DB constraint error); it is not counted.
+        }
+      }
+      return { deleted, total: props.ids.length }
+    }
+
+    // Custom Bulk action (issue #736). Look the declared action up by `key` and
+    // run its server-side `handler` over the selected ids with THIS secured
+    // context — the handler does its own row-by-row work through `context.db`,
+    // so per-id access control and hooks apply and denials stay Silent. The
+    // `hasAccess` visibility gate (if any) is re-checked here so a hidden action
+    // can never be invoked by a hand-crafted request; the client only ever sends
+    // the serialisable `{ key, ids }`, never the handler itself.
+    if (props.action === 'bulkAction') {
+      const bulkActions = listConfig.ui?.listView?.bulkActions ?? []
+      const action = bulkActions.find((a) => a.key === props.key)
+      if (!action) {
+        return {
+          bulkAction: false,
+          error: `Bulk action "${props.key}" not found on list "${props.listKey}"`,
+        }
+      }
+      if (action.hasAccess) {
+        const allowed = await action.hasAccess({
+          session: context.session,
+          context,
+          listKey: props.listKey,
+        })
+        if (!allowed) {
+          return { bulkAction: false, error: 'Access denied' }
+        }
+      }
+      try {
+        const result = await action.handler({
+          listKey: props.listKey,
+          ids: props.ids,
+          context,
+        })
+        return { bulkAction: true, message: result?.message }
+      } catch (error) {
+        if (error instanceof ValidationError || error instanceof DatabaseError) {
+          return { bulkAction: false, error: error.message }
+        }
+        const dbError = parsePrismaError(error, listConfig)
+        // A recognised Prisma error carries a user-safe, translated message.
+        if (dbError instanceof DatabaseError) {
+          return { bulkAction: false, error: dbError.message }
+        }
+        // Anything else is an unexpected handler bug whose raw `.message` could
+        // leak internal detail to the client — log it server-side and return a
+        // generic client-facing message instead.
+        console.error(`Bulk action "${props.key}" on list "${props.listKey}" failed:`, error)
+        return { bulkAction: false, error: 'Action failed' }
+      }
+    }
+
+    // Relationship-table row removal (ADR-0018, #739). Runs on the RELATED row
+    // through the secured context, so the related list's access + hooks apply.
+    // Honours Silent failure: an access-denied operation returns `null`, which
+    // becomes `{ removed: false }` with a generic reason — never leaking whether
+    // the row was denied or absent.
+    if (props.action === 'removeRelated') {
+      try {
+        let result: unknown = null
+        if (props.mode === 'delete') {
+          result = await model.delete({ where: { id: props.id } })
+        } else {
+          // Disconnect: an UPDATE on the related list nulling its back-reference,
+          // never a delete — the row itself survives. A to-one back-reference
+          // disconnects with `true`; a to-many back-reference (many-to-many)
+          // disconnects the specific parent by id.
+          if (!props.field) {
+            return { removed: false, error: 'Missing back-reference field for disconnect' }
+          }
+          const backRefField = listConfig.fields[props.field]
+          const backRefIsMany =
+            !!backRefField && 'many' in backRefField && backRefField.many === true
+          const disconnectValue = backRefIsMany
+            ? { disconnect: { id: props.parentId } }
+            : { disconnect: true }
+          result = await model.update({
+            where: { id: props.id },
+            data: { [props.field]: disconnectValue },
+          })
+        }
+        if (result === null || result === undefined) {
+          return { removed: false, error: 'Access denied or operation failed' }
+        }
+        return { removed: true }
+      } catch (error) {
+        if (error instanceof ValidationError || error instanceof DatabaseError) {
+          return { removed: false, error: error.message }
+        }
+        const dbError = parsePrismaError(error, listConfig)
+        return { removed: false, error: dbError.message }
+      }
+    }
+
+    // Relationship-table pre-linked create (ADR-0018, #738). Creates a row on
+    // the RELATED list through the secured context, so the related list's create
+    // access + hooks (and field-level access) apply — never the parent's. The
+    // back-reference to the parent is set here from `field`/`parentId` (a to-one
+    // back-ref connects a single parent; a to-many back-ref, e.g. many-to-many,
+    // connects the parent by id), so the client can never re-target the link.
+    // Honours Silent failure: an access-denied create returns `null`, surfaced
+    // as `{ created: false }` with a generic reason (no denied-vs-absent leak).
+    if (props.action === 'createRelated') {
+      try {
+        // Defensive guard (hardening; unreachable from the drawer, which always
+        // mounts on a valid back-reference and sends BOTH field and parentId).
+        // A lone field/parentId is a malformed direct call — reject it rather
+        // than silently skip back-reference injection and let a client-supplied
+        // data[field] slip through unguarded to the create.
+        if (!!props.field !== !!props.parentId) {
+          return {
+            created: false,
+            error: 'createRelated requires both field and parentId, or neither',
+          }
+        }
+        const data: Record<string, unknown> = { ...props.data }
+        if (props.field && props.parentId) {
+          const backRefField = listConfig.fields[props.field]
+          // The back-reference must name a relationship field on this list; a
+          // non-relationship field would otherwise receive a nonsensical
+          // { connect } value. Also hardening — the drawer only ever passes a
+          // real relationship back-reference here.
+          if (!backRefField || backRefField.type !== 'relationship') {
+            return {
+              created: false,
+              error: `Field "${props.field}" on list "${props.listKey}" is not a relationship field`,
+            }
+          }
+          const backRefIsMany = 'many' in backRefField && backRefField.many === true
+          // The back-reference is set on the SERVER from the trusted parentId,
+          // OVERWRITING any client-supplied data[field] spread in above, so a
+          // hostile client can never re-target the link (a to-many back-ref
+          // connects the parent by id).
+          data[props.field] = backRefIsMany
+            ? { connect: [{ id: props.parentId }] }
+            : { connect: { id: props.parentId } }
+        }
+        const result = await model.create({ data })
+        if (result === null || result === undefined) {
+          return { created: false, error: 'Access denied or operation failed' }
+        }
+        const id =
+          typeof result === 'object' && result !== null && 'id' in result
+            ? String((result as { id: unknown }).id)
+            : undefined
+        return { created: true, id }
+      } catch (error) {
+        if (error instanceof ValidationError || error instanceof DatabaseError) {
+          return { created: false, error: error.message, fieldErrors: error.fieldErrors }
+        }
+        const dbError = parsePrismaError(error, listConfig)
+        return {
+          created: false,
+          error: dbError.message,
+          fieldErrors: dbError instanceof DatabaseError ? dbError.fieldErrors : undefined,
+        }
+      }
+    }
+
+    // Relationship-table inline cell edit (ADR-0018, #737). Updates ONE scalar
+    // field on the RELATED row through the secured context, so the related list's
+    // operation- and field-level update access plus its hooks/validation apply —
+    // never the parent's. Honours Silent failure: an access-denied update returns
+    // `null`, surfaced as `{ updated: false }` with a generic reason (no
+    // denied-vs-absent leak); a validation/db error surfaces its message and
+    // fieldErrors so the cell can revert with a reason and show an inline error.
+    if (props.action === 'updateRelated') {
+      try {
+        const result = await model.update({
+          where: { id: props.id },
+          data: { [props.field]: props.value },
+        })
+        if (result === null || result === undefined) {
+          return { updated: false, error: 'Access denied or operation failed' }
+        }
+        return { updated: true }
+      } catch (error) {
+        if (error instanceof ValidationError || error instanceof DatabaseError) {
+          return { updated: false, error: error.message, fieldErrors: error.fieldErrors }
+        }
+        const dbError = parsePrismaError(error, listConfig)
+        return {
+          updated: false,
+          error: dbError.message,
+          fieldErrors: dbError instanceof DatabaseError ? dbError.fieldErrors : undefined,
+        }
+      }
+    }
+
     try {
       if (props.action === 'relationshipOptions') {
         const fieldConfig = listConfig.fields[props.field] as

package/src/context/nested-operations.ts

@@ -12,6 +12,7 @@ import {
   executeFieldAfterOperationHooks,
   executeFieldValidateHooks,
   validateFieldRules,
+  splitMultiColumnFields,
   ValidationError,
 } from '../hooks/index.js'
 import { getDbKey } from '../lib/case-utils.js'
@@ -306,6 +307,16 @@ async function processNestedCreate(
         throw new ValidationError(validation.errors, validation.fieldErrors)
       }
 
+      // 5.5 Split multi-column fields into physical columns (#789). Only
+      // reached once the logical value has passed validation above.
+      resolvedData = await splitMultiColumnFields(
+        item,
+        resolvedData,
+        relatedListConfig.fields,
+        'create',
+        context,
+      )
+
       // 6. Filter writable fields
       const filtered = await filterWritableFields(
         resolvedData,
@@ -645,6 +656,17 @@ async function processNestedUpdate(
         throw new ValidationError(validation.errors, validation.fieldErrors)
       }
 
+      // Split multi-column fields into physical columns (#789). Only reached
+      // once the logical value has passed validation above.
+      resolvedData = await splitMultiColumnFields(
+        updateData,
+        resolvedData,
+        relatedListConfig.fields,
+        'update',
+        context,
+        originalItem,
+      )
+
       // Filter writable fields
       const filtered = await filterWritableFields(
         resolvedData,

package/src/extend.ts

@@ -17,3 +17,12 @@ export type {
   TypeDescriptor,
   MultiColumnPrismaResult,
 } from './config/index.js'
+
+// Filter spec authoring — a field's optional `getFilterSpec` returns these
+// (ADR-0017). Additive: a field without one is simply not filterable.
+export type {
+  FilterSpec,
+  FilterOperator,
+  FilterCondition,
+  FilterValueSource,
+} from './filter/index.js'

package/src/fields/index.ts

@@ -17,6 +17,20 @@ import type {
 } from '../config/types.js'
 import { hashPassword, isHashedPassword, HashedPassword } from '../utils/password.js'
 import { formatPrismaDefault } from './format-prisma-default.js'
+import { getLabelFieldName } from '../config/label.js'
+import type { FilterOperator, FilterSpec } from '../filter/types.js'
+import { RELATIONSHIP_COUNT_FILTER_KEY } from '../filter/types.js'
+
+/**
+ * Operators shared by numeric/date fields: plain equality plus the four
+ * comparisons. `eq` maps to Prisma's `equals`; the comparisons pass through.
+ */
+const COMPARISON_OPERATORS: FilterOperator[] = ['eq', 'gt', 'gte', 'lt', 'lte']
+
+/** Map a Filter operator to its Prisma condition key (`eq` → `equals`). */
+function prismaComparisonKey(operator: FilterOperator): string {
+  return operator === 'eq' ? 'equals' : operator
+}
 
 // Field-config types live here, alongside the builders that produce them.
 // (The umbrella `FieldConfig` and authoring `BaseFieldConfig` stay on the root
@@ -30,6 +44,8 @@ export type {
   CalendarDayField,
   PasswordField,
   SelectField,
+  SelectOption,
+  SelectOptionVariant,
   RelationshipField,
   JsonField,
   VirtualField,
@@ -154,6 +170,16 @@ export function text<
         optional: !isRequired,
       }
     },
+    // Text fields drive free-text search: a bare word (or a `field:value`) maps
+    // to a case-preserving `contains`. This is what replaces the old hard-coded
+    // `type === 'text'` search in the admin list view.
+    getFilterSpec: (fieldName: string): FilterSpec => ({
+      operators: ['eq'],
+      freeText: true,
+      toCondition: (operator, value) =>
+        operator === 'eq' ? { [fieldName]: { contains: value } } : null,
+      suggestions: { valueSource: { kind: 'none' } },
+    }),
   }
 }
 
@@ -231,6 +257,17 @@ export function integer<
         optional: !isRequired,
       }
     },
+    // Integers support equality and comparisons (`orders:>5`). A non-integer
+    // value can't be interpreted, so its token degrades to free text.
+    getFilterSpec: (fieldName: string): FilterSpec => ({
+      operators: COMPARISON_OPERATORS,
+      toCondition: (operator, value) => {
+        const trimmed = value.trim()
+        if (!/^-?\d+$/.test(trimmed)) return null
+        return { [fieldName]: { [prismaComparisonKey(operator)]: Number(trimmed) } }
+      },
+      suggestions: { valueSource: { kind: 'none' } },
+    }),
   }
 }
 
@@ -397,6 +434,17 @@ export function decimal<
         },
       ]
     },
+    // Decimals compare like integers, but the value stays a string so Prisma's
+    // Decimal keeps full precision. A non-numeric value degrades to free text.
+    getFilterSpec: (fieldName: string): FilterSpec => ({
+      operators: COMPARISON_OPERATORS,
+      toCondition: (operator, value) => {
+        const trimmed = value.trim()
+        if (!/^-?\d+(\.\d+)?$/.test(trimmed)) return null
+        return { [fieldName]: { [prismaComparisonKey(operator)]: trimmed } }
+      },
+      suggestions: { valueSource: { kind: 'none' } },
+    }),
   }
 }
 
@@ -443,6 +491,27 @@ export function checkbox<
         optional: options?.defaultValue === undefined,
       }
     },
+    // Checkboxes filter by equality against the two enumerated values. Anything
+    // other than true/false can't be interpreted and degrades to free text.
+    getFilterSpec: (fieldName: string): FilterSpec => ({
+      operators: ['eq'],
+      toCondition: (operator, value) => {
+        if (operator !== 'eq') return null
+        const normalized = value.trim().toLowerCase()
+        if (normalized === 'true') return { [fieldName]: { equals: true } }
+        if (normalized === 'false') return { [fieldName]: { equals: false } }
+        return null
+      },
+      suggestions: {
+        valueSource: {
+          kind: 'enum',
+          options: [
+            { value: 'true', label: 'True' },
+            { value: 'false', label: 'False' },
+          ],
+        },
+      },
+    }),
   }
 }
 
@@ -508,6 +577,17 @@ export function timestamp<
         optional: !hasDefault,
       }
     },
+    // Timestamps support equality and comparisons (`joined:>2024-01-01`). An
+    // unparseable date degrades to free text.
+    getFilterSpec: (fieldName: string): FilterSpec => ({
+      operators: COMPARISON_OPERATORS,
+      toCondition: (operator, value) => {
+        const date = new Date(value.trim())
+        if (Number.isNaN(date.getTime())) return null
+        return { [fieldName]: { [prismaComparisonKey(operator)]: date } }
+      },
+      suggestions: { valueSource: { kind: 'none' } },
+    }),
   }
 }
 
@@ -696,6 +776,20 @@ export function calendarDay<
         optional: isNullable,
       }
     },
+    // Calendar days compare on the `YYYY-MM-DD` value (coerced to a UTC-midnight
+    // Date so it matches the `@db.Date` column). A malformed value degrades to
+    // free text.
+    getFilterSpec: (fieldName: string): FilterSpec => ({
+      operators: COMPARISON_OPERATORS,
+      toCondition: (operator, value) => {
+        const trimmed = value.trim()
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(trimmed)) return null
+        const date = new Date(`${trimmed}T00:00:00.000Z`)
+        if (Number.isNaN(date.getTime())) return null
+        return { [fieldName]: { [prismaComparisonKey(operator)]: date } }
+      },
+      suggestions: { valueSource: { kind: 'none' } },
+    }),
   }
 }
 
@@ -1014,6 +1108,28 @@ export function select<
         optional: !options.validation?.isRequired || options.defaultValue !== undefined,
       }
     },
+    // Selects filter by equality against their enumerated options. The token
+    // value is matched (case-insensitively) against option value or label and
+    // resolved to the canonical stored value; an unknown option degrades to
+    // free text.
+    getFilterSpec: (fieldName: string): FilterSpec => ({
+      operators: ['eq'],
+      toCondition: (operator, value) => {
+        if (operator !== 'eq') return null
+        const needle = value.trim().toLowerCase()
+        const match = options.options.find(
+          (opt) => opt.value.toLowerCase() === needle || opt.label.toLowerCase() === needle,
+        )
+        if (!match) return null
+        return { [fieldName]: { equals: match.value } }
+      },
+      suggestions: {
+        valueSource: {
+          kind: 'enum',
+          options: options.options.map((opt) => ({ value: opt.value, label: opt.label })),
+        },
+      },
+    }),
   }
 }
 
@@ -1344,6 +1460,58 @@ export function relationship<
     config: OpenSaasConfig,
   ) => getPrismaRelation(field as RelationshipField, fieldName, listKey, config)
 
+  // Relationships filter differently by cardinality (issue #732):
+  //  • to-one filters by the related Item's label — `author:"Ada Lovelace"`
+  //    becomes a nested `is` `contains` on the target list's Label field.
+  //  • to-many filters by the access-visible related COUNT with numeric
+  //    comparisons — `orders:>5`. Prisma cannot compare a relation count in a
+  //    `where`, so the mapper emits a structured count marker
+  //    (RELATIONSHIP_COUNT_FILTER_KEY) that `resolveRelationshipCountFilters`
+  //    later turns into an access-scoped `{ id: { in } }`.
+  // The mapper stays pure in both cases (no DB lookup). Suggestions point a
+  // to-one at the target list's label lookup; a to-many exposes no value source
+  // (a numeric compare, like an integer field).
+  field.getFilterSpec = (
+    _fieldName: string,
+    _listKey: string,
+    config: OpenSaasConfig,
+  ): FilterSpec | undefined => {
+    const { list: targetList } = parseRelationshipRef(field.ref)
+    const relatedListConfig = config.lists[targetList]
+    if (!relatedListConfig) return undefined
+
+    if (field.many === true) {
+      return {
+        operators: COMPARISON_OPERATORS,
+        toCondition: (operator, value) => {
+          const trimmed = value.trim()
+          // A non-integer count comparison can't be interpreted → degrade to
+          // free text (matching the integer field's behaviour).
+          if (!/^-?\d+$/.test(trimmed)) return null
+          return {
+            [_fieldName]: { [RELATIONSHIP_COUNT_FILTER_KEY]: { operator, value: Number(trimmed) } },
+          }
+        },
+        suggestions: { valueSource: { kind: 'none' } },
+      }
+    }
+
+    const labelField = getLabelFieldName(relatedListConfig)
+    const labelFieldConfig = relatedListConfig.fields[labelField]
+    // A virtual label field has no queryable column, so `contains` can't run
+    // against it — the relationship is then not filterable.
+    if (labelFieldConfig?.virtual === true) return undefined
+
+    return {
+      operators: ['eq'],
+      toCondition: (operator, value) => {
+        if (operator !== 'eq') return null
+        return { [_fieldName]: { is: { [labelField]: { contains: value } } } }
+      },
+      suggestions: { valueSource: { kind: 'relationship', listKey: targetList, many: false } },
+    }
+  }
+
   return field
 }
 

package/src/filter/collect.ts

@@ -0,0 +1,72 @@
+import type { ListConfig, OpenSaasConfig } from '../config/types.js'
+import { parseFilterQuery } from './parse.js'
+import { buildFilterWhere } from './map.js'
+import type { FilterCondition, FilterFieldSuggestion, FilterSpec } from './types.js'
+
+/**
+ * Resolve every field's {@link FilterSpec} for a list by delegating to each
+ * field's optional `getFilterSpec` method. A field without the method (or one
+ * whose method returns `undefined`) is simply not filterable — the absence
+ * degrades gracefully so third-party fields keep working.
+ *
+ * @param listConfig The list whose fields to inspect.
+ * @param listKey    The list's key (passed through to each field's spec).
+ * @param config     The full config (relationship specs resolve their target
+ *   list's label field from it).
+ */
+export function collectFilterSpecs(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  listConfig: ListConfig<any>,
+  listKey: string,
+  config: OpenSaasConfig,
+): Record<string, FilterSpec> {
+  const specs: Record<string, FilterSpec> = {}
+  for (const [fieldName, field] of Object.entries(listConfig.fields)) {
+    if (typeof field.getFilterSpec !== 'function') continue
+    const spec = field.getFilterSpec(fieldName, listKey, config)
+    if (spec) specs[fieldName] = spec
+  }
+  return specs
+}
+
+/**
+ * End-to-end helper for the list view: parse a raw URL query, collect the
+ * list's Filter specs, and build the merged Prisma `where` fragment. The
+ * fragment is meant to be handed to `context.db.<list>.findMany`/`count`, where
+ * the secured context ANDs it with the access filter — so the filter can only
+ * ever narrow, never widen, what a session may see.
+ *
+ * @returns A `where` fragment, or `undefined` when the query filters nothing.
+ */
+export function buildListFilterWhere(
+  query: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  listConfig: ListConfig<any>,
+  listKey: string,
+  config: OpenSaasConfig,
+): FilterCondition | undefined {
+  const specs = collectFilterSpecs(listConfig, listKey, config)
+  const tokens = parseFilterQuery(query)
+  return buildFilterWhere(tokens, specs)
+}
+
+/**
+ * Collect the client-serializable suggestion metadata for a list's filterable
+ * fields (field names, operators, enumerated values / relationship label
+ * search). Carries no functions, so it can cross the server/client boundary to
+ * drive the Filter builder's autocomplete.
+ */
+export function collectFilterSuggestions(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  listConfig: ListConfig<any>,
+  listKey: string,
+  config: OpenSaasConfig,
+): FilterFieldSuggestion[] {
+  const specs = collectFilterSpecs(listConfig, listKey, config)
+  return Object.entries(specs).map(([field, spec]) => ({
+    field,
+    operators: spec.operators,
+    freeText: spec.freeText ?? false,
+    valueSource: spec.suggestions.valueSource,
+  }))
+}