@opensaas/stack-core 0.29.0 → 0.31.0

package/src/filter/serialize.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect } from 'vitest'
+import { parseFilterQuery } from './parse.js'
+import { serializeFilterQuery } from './serialize.js'
+import type { FilterToken } from './types.js'
+
+// ─────────────────────────────────────────────────────────────
+// serializeFilterQuery — the pure tokens → query-string boundary
+// (ADR-0017). The exact inverse of parseFilterQuery; this is the
+// grammar the Filter builder UI produces into the `?search=` param.
+// ─────────────────────────────────────────────────────────────
+
+const token = (partial: Partial<FilterToken>): FilterToken => ({
+  field: null,
+  operator: 'eq',
+  value: '',
+  raw: '',
+  ...partial,
+})
+
+describe('serializeFilterQuery', () => {
+  it('serialises a bare free-text word', () => {
+    expect(serializeFilterQuery([token({ field: null, value: 'beta' })])).toBe('beta')
+  })
+
+  it('serialises a field:value token with the default eq operator', () => {
+    expect(serializeFilterQuery([token({ field: 'role', value: 'Editor' })])).toBe('role:Editor')
+  })
+
+  it('serialises each comparison operator as its prefix', () => {
+    expect(serializeFilterQuery([token({ field: 'orders', operator: 'gt', value: '5' })])).toBe(
+      'orders:>5',
+    )
+    expect(serializeFilterQuery([token({ field: 'orders', operator: 'gte', value: '5' })])).toBe(
+      'orders:>=5',
+    )
+    expect(serializeFilterQuery([token({ field: 'orders', operator: 'lt', value: '5' })])).toBe(
+      'orders:<5',
+    )
+    expect(serializeFilterQuery([token({ field: 'orders', operator: 'lte', value: '5' })])).toBe(
+      'orders:<=5',
+    )
+  })
+
+  it('quotes a field value containing whitespace', () => {
+    expect(serializeFilterQuery([token({ field: 'name', value: 'Ada Lovelace' })])).toBe(
+      'name:"Ada Lovelace"',
+    )
+  })
+
+  it('quotes a bare word containing whitespace', () => {
+    expect(serializeFilterQuery([token({ field: null, value: 'multi word' })])).toBe('"multi word"')
+  })
+
+  it('quotes an eq value that would otherwise read as a comparison operator', () => {
+    // Without the guard, `field:>5` would re-parse as gt, not eq of ">5".
+    expect(serializeFilterQuery([token({ field: 'note', operator: 'eq', value: '>5' })])).toBe(
+      'note:">5"',
+    )
+  })
+
+  it('does NOT quote a leading > on a bare word (parser keeps it literal)', () => {
+    expect(serializeFilterQuery([token({ field: null, value: '>5' })])).toBe('>5')
+  })
+
+  it('joins tokens with the grammar implicit AND (a single space)', () => {
+    expect(
+      serializeFilterQuery([
+        token({ field: 'role', value: 'Editor' }),
+        token({ field: 'orders', operator: 'gt', value: '5' }),
+        token({ field: null, value: 'beta' }),
+      ]),
+    ).toBe('role:Editor orders:>5 beta')
+  })
+
+  it('omits tokens with an empty value (no dangling field: or stray quotes)', () => {
+    expect(
+      serializeFilterQuery([
+        token({ field: 'role', value: '' }),
+        token({ field: null, value: '' }),
+        token({ field: 'name', value: 'Ada' }),
+      ]),
+    ).toBe('name:Ada')
+  })
+})
+
+// ─────────────────────────────────────────────────────────────
+// Round-trip: parse ∘ serialize is stable, and serialize ∘ parse
+// reproduces the meaning the engine assigns.
+// ─────────────────────────────────────────────────────────────
+
+describe('parse/serialize round-trip', () => {
+  const queries = [
+    'beta',
+    'role:Editor',
+    'orders:>5',
+    'orders:>=5',
+    'orders:<10',
+    'name:"Ada Lovelace"',
+    'role:Editor orders:>5 name:"Ada Lovelace" beta',
+    '"multi word" gamma',
+  ]
+
+  it.each(queries)('serialize(parse(%s)) reproduces the query', (query) => {
+    expect(serializeFilterQuery(parseFilterQuery(query))).toBe(query)
+  })
+
+  it.each(queries)('parse is idempotent through a serialize round-trip: %s', (query) => {
+    const once = parseFilterQuery(query)
+    const twice = parseFilterQuery(serializeFilterQuery(once))
+    // Compare on the semantic fields (raw differs after re-serialisation).
+    const strip = (tokens: FilterToken[]) =>
+      tokens.map(({ field, operator, value }) => ({ field, operator, value }))
+    expect(strip(twice)).toEqual(strip(once))
+  })
+})

package/src/filter/serialize.ts

@@ -0,0 +1,75 @@
+import type { FilterOperator, FilterToken } from './types.js'
+
+/**
+ * The comparison-operator prefix each {@link FilterOperator} serialises to. The
+ * exact inverse of the prefixes {@link parseFilterQuery} recognises (`eq` has no
+ * prefix — a plain `field:value`).
+ */
+const OPERATOR_PREFIX: Record<FilterOperator, string> = {
+  eq: '',
+  gt: '>',
+  gte: '>=',
+  lt: '<',
+  lte: '<=',
+}
+
+/**
+ * Whether a value must be wrapped in double quotes to survive re-parsing.
+ *
+ * A value is quoted when it contains whitespace (so `parseFilterQuery` keeps it
+ * as one token) or an embedded quote. When `guardOperatorChars` is set (an `eq`
+ * field token, where a leading `>`/`<` would otherwise be read as a comparison
+ * operator), a value starting with `<`/`>` is also quoted so it round-trips as a
+ * literal value rather than an operator.
+ */
+function quoteIfNeeded(value: string, guardOperatorChars: boolean): string {
+  const needsQuote =
+    /\s/.test(value) ||
+    value.includes('"') ||
+    (guardOperatorChars && (value.startsWith('>') || value.startsWith('<')))
+  return needsQuote ? `"${value}"` : value
+}
+
+/**
+ * Serialise {@link FilterToken}s back into a filter query string — the exact
+ * inverse of {@link parseFilterQuery} (ADR-0017). This is the grammar-producing
+ * half the Filter builder UI relies on: the builder turns UI state into tokens
+ * and serialises them into the `?search=` URL param the engine already consumes,
+ * so the same quoting and operator-prefix rules live next to the parser and can
+ * never drift.
+ *
+ * Pure and field-agnostic (no DB/Prisma imports). Tokens are joined with the
+ * grammar's implicit AND (a single space). A token with an empty value carries
+ * no filter and is omitted, so `serializeFilterQuery` never emits a dangling
+ * `field:` or a stray quote pair.
+ *
+ * @example
+ * serializeFilterQuery([
+ *   { field: 'role',   operator: 'eq', value: 'Editor',       raw: '' },
+ *   { field: 'orders', operator: 'gt', value: '5',            raw: '' },
+ *   { field: 'name',   operator: 'eq', value: 'Ada Lovelace', raw: '' },
+ *   { field: null,     operator: 'eq', value: 'beta',         raw: '' },
+ * ])
+ * // 'role:Editor orders:>5 name:"Ada Lovelace" beta'
+ */
+export function serializeFilterQuery(tokens: FilterToken[]): string {
+  const parts: string[] = []
+
+  for (const token of tokens) {
+    // An empty value is not a filter — skip it rather than emit `field:` / `""`.
+    if (token.value === '') continue
+
+    if (token.field === null) {
+      // Bare free-text word. A leading `>`/`<` stays literal for bare words
+      // (the parser only treats them as operators after a `field:`), so no
+      // operator guard is needed here.
+      parts.push(quoteIfNeeded(token.value, false))
+      continue
+    }
+
+    const prefix = OPERATOR_PREFIX[token.operator]
+    parts.push(`${token.field}:${prefix}${quoteIfNeeded(token.value, prefix === '')}`)
+  }
+
+  return parts.join(' ')
+}

package/src/filter/types.ts

@@ -0,0 +1,120 @@
+/**
+ * Filter engine types (ADR-0017).
+ *
+ * The admin UI's Filter builder turns a URL query string into scoped,
+ * server-executed filtering. The grammar is an AND-only URL contract:
+ * implicit-AND tokens, quoted multi-word values, comparison operators on
+ * numeric/date fields, and bare words as free text. Fields participate by
+ * declaring a {@link FilterSpec} (a self-contained field-builder method, peer
+ * of `getPrismaType` et al.); a field without one is not filterable.
+ *
+ * These types are the pure boundary — no Prisma / DB imports — so the
+ * `parse → tokens` and `tokens + specs → conditions` seam is unit-testable.
+ */
+
+/**
+ * A Filter operator. `eq` is the default operator for a plain `field:value`
+ * token (each field's spec decides what equality means — `contains` for text,
+ * `equals` for a select); the comparisons are produced by the `>`/`>=`/`<`/`<=`
+ * prefixes on numeric and date tokens.
+ */
+export type FilterOperator = 'eq' | 'gt' | 'gte' | 'lt' | 'lte'
+
+/**
+ * One parsed unit of a filter query — a field, an operator, and a value.
+ *
+ * A bare free-text word parses to a token with `field: null`. `raw` is the
+ * original source substring, retained so a token that can't map to a condition
+ * degrades to free text without re-tokenising.
+ */
+export interface FilterToken {
+  /** Field key the token targets, or `null` for a bare free-text word. */
+  field: string | null
+  /** The operator; `eq` for a plain `field:value`, comparisons for prefixed values. */
+  operator: FilterOperator
+  /** The unquoted value. */
+  value: string
+  /** The original source substring for this token (used when degrading to free text). */
+  raw: string
+}
+
+/**
+ * A Prisma `where` fragment produced by a Filter spec's `toCondition` mapper.
+ * Kept as an opaque record so this module carries no Prisma type dependency;
+ * the secured context ANDs it with the access filter when the fragment reaches
+ * `context.db.*`.
+ */
+export type FilterCondition = Record<string, unknown>
+
+/**
+ * Serializable description of what the suggestion dropdown may offer for a
+ * field's values. Structure only — never data-derived values for unbounded
+ * fields (ADR-0017): `none` for text/number/date, enumerated `options` for
+ * select/checkbox, and `relationship` for label search via the existing
+ * access-controlled lookup.
+ */
+export type FilterValueSource =
+  | { kind: 'none' }
+  | { kind: 'enum'; options: Array<{ value: string; label: string }> }
+  | { kind: 'relationship'; listKey: string; many: boolean }
+
+/**
+ * Marker key a to-many relationship's Filter spec emits for a count comparison
+ * (`orders:>5`). Prisma cannot express a relation-count comparison in a `where`
+ * (there is no `{ orders: { _count: { gt: 5 } } }`), so the pure spec can only
+ * emit a structured marker; `resolveRelationshipCountFilters` later turns each
+ * marker into an access-scoped `{ id: { in | notIn } }` before the query runs.
+ * Kept here (the pure boundary) so the field builder and the resolver agree on
+ * the shape without depending on each other.
+ */
+export const RELATIONSHIP_COUNT_FILTER_KEY = '_countFilter' as const
+
+/**
+ * The payload a {@link RELATIONSHIP_COUNT_FILTER_KEY} marker carries: the
+ * numeric comparison to apply to a to-many relationship's access-visible count.
+ */
+export interface RelationshipCountFilterMarker {
+  operator: FilterOperator
+  value: number
+}
+
+/**
+ * A field's self-declared filtering capability. Returned by the optional
+ * `getFilterSpec` field-builder method.
+ */
+export interface FilterSpec {
+  /** Operators this field supports. A token using any other operator degrades to free text. */
+  operators: FilterOperator[]
+  /**
+   * Whether this field participates in bare-word free-text search. Bare words
+   * are OR-matched across every free-text field via each field's `eq` mapping.
+   */
+  freeText?: boolean
+  /**
+   * Pure map from a supported `(operator, value)` to a Prisma `where` fragment,
+   * or `null` when the value can't be interpreted (e.g. a non-numeric value on
+   * a numeric field, or an unknown select option) — in which case the token
+   * degrades to free text. MUST stay free of DB/Prisma imports.
+   */
+  toCondition: (operator: FilterOperator, value: string) => FilterCondition | null
+  /** Serializable suggestion metadata for the client. */
+  suggestions: {
+    valueSource: FilterValueSource
+  }
+}
+
+/**
+ * Collected, client-serializable suggestion metadata for one filterable field.
+ * The union of every list field's Filter spec suggestions; carries no
+ * functions, so it crosses the server/client boundary.
+ */
+export interface FilterFieldSuggestion {
+  /** The field key. */
+  field: string
+  /** Operators the field supports. */
+  operators: FilterOperator[]
+  /** Whether the field participates in bare-word free-text search. */
+  freeText: boolean
+  /** How the suggestion dropdown may offer values for this field. */
+  valueSource: FilterValueSource
+}

package/src/hooks/index.ts

@@ -481,6 +481,15 @@ export async function executeFieldAfterTransactionHooks(
 /**
  * Execute field-level resolveInput hooks
  * Allows fields to transform their input values before database write
+ *
+ * NOTE (#789): multi-column fields (e.g. storage image()/file() in
+ * Keystone-parity mode) are NOT split here. This phase only resolves each
+ * field's value under its LOGICAL key, so that phases 2-3 (list/field
+ * `validate` → `validateFieldRules`) run against the same shape a
+ * single-column field would present — including an unrecognised/invalid value
+ * a field's `resolveInput` chose to pass through for validation to catch. The
+ * split into physical columns happens strictly AFTER validation passes; see
+ * {@link splitMultiColumnFields}.
  */
 export async function executeFieldResolveInputHooks(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -497,69 +506,90 @@ export async function executeFieldResolveInputHooks(
   let result = { ...resolvedData }
 
   for (const [fieldKey, fieldConfig] of Object.entries(fields)) {
-    // Skip if field not in data
+    // Skip if field not in data, or if there's nothing to resolve
     if (!(fieldKey in result)) continue
+    if (!fieldConfig.hooks?.resolveInput) continue
 
-    // A field's resolveInput produces its resolved value; for most fields that
-    // value is stored back under the same key. Multi-column fields additionally
-    // split that value across their physical columns below.
-    let resolvedValue: unknown = result[fieldKey]
+    // Execute field hook
+    // Type assertion is safe here because hooks are typed correctly in field definitions
+    // and we're working with runtime values that match those types
+    const resolvedValue = await fieldConfig.hooks.resolveInput({
+      listKey,
+      fieldKey,
+      operation,
+      inputData,
+      item,
+      resolvedData: { ...result }, // Pass a copy to avoid mutation affecting recorded args
+      context,
+    } as Parameters<typeof fieldConfig.hooks.resolveInput>[0])
+
+    // Create new object with updated field to avoid mutating the passed reference
+    result = { ...result, [fieldKey]: resolvedValue }
+  }
 
-    if (fieldConfig.hooks?.resolveInput) {
-      // Execute field hook
-      // Type assertion is safe here because hooks are typed correctly in field definitions
-      // and we're working with runtime values that match those types
-      resolvedValue = await fieldConfig.hooks.resolveInput({
-        listKey,
-        fieldKey,
-        operation,
-        inputData,
-        item,
-        resolvedData: { ...result }, // Pass a copy to avoid mutation affecting recorded args
-        context,
-      } as Parameters<typeof fieldConfig.hooks.resolveInput>[0])
-    } else if (!fieldConfig.splitColumns) {
-      // No resolveInput and not a multi-column field — nothing to do.
+  return result
+}
+
+/**
+ * Split multi-column fields' resolved LOGICAL values into their physical
+ * per-part columns (e.g. storage image()/file() in Keystone-parity mode — see
+ * ADR-0006).
+ *
+ * Runs AFTER `validateFieldRules` has passed (#789): a multi-column field's
+ * `getZodSchema` gets a genuine chance to reject an unrecognised/invalid
+ * logical value BEFORE it is split into `null`/`undefined` physical columns
+ * and silently written. Previously this split ran inline inside
+ * `executeFieldResolveInputHooks` (Phase 1.5, BEFORE validation), which let an
+ * unrecognised value bypass validation entirely.
+ *
+ * Preserves the field-level write-access gate exactly as before: the raw
+ * per-part column keys are not declared in `fieldConfigs`, so
+ * `filterWritableFields`'s undeclared-key reject cannot enforce this field's
+ * own write access — enforce it HERE, using the canonical field-access
+ * evaluator with the same arguments the write pipeline uses. A denied field
+ * drops its logical key and contributes NONE of its per-part columns (sudo
+ * bypasses via `checkFieldAccess`).
+ */
+export async function splitMultiColumnFields(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  inputData: Record<string, any>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  resolvedData: Record<string, any>,
+  fields: Record<string, FieldConfig>,
+  operation: 'create' | 'update',
+  context: AccessContext,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  item?: any,
+): Promise<Record<string, unknown>> {
+  let result = { ...resolvedData }
+
+  for (const [fieldKey, fieldConfig] of Object.entries(fields)) {
+    if (!fieldConfig.splitColumns) continue
+    if (!(fieldKey in result)) continue
+
+    const resolvedValue = result[fieldKey]
+
+    const canWrite = await checkFieldAccess(fieldConfig.access, operation, {
+      session: context.session,
+      item,
+      context,
+      inputData,
+    })
+
+    // Drop the logical key (it is not a real column) regardless of outcome —
+    // a denied field must not leave its logical key behind either.
+    const next = { ...result }
+    delete next[fieldKey]
+    result = next
+
+    if (!canWrite) {
+      // Denied: write none of its per-part columns — exactly as
+      // filterWritableFields drops a denied single-column field.
       continue
     }
 
-    if (fieldConfig.splitColumns) {
-      // Multi-column field (e.g. storage image()/file() in Keystone-parity
-      // mode): replace the single logical key with its per-part columns so the
-      // write payload targets the live columns instead of a single one.
-      //
-      // The split removes the logical key from the payload BEFORE the
-      // canonical writable-field filter (`filterWritableFields`) runs, and the
-      // raw per-part column keys are not in `fieldConfigs` — so that later
-      // filter cannot enforce this field's own write access. Enforce it HERE,
-      // using the canonical field-access evaluator with the SAME arguments the
-      // write pipeline uses. A single-column field denied by `update`/`create`
-      // is simply omitted from the write; a denied multi-column field must
-      // likewise contribute NONE of its per-part columns. (sudo bypasses via
-      // `checkFieldAccess`.)
-      const canWrite = await checkFieldAccess(fieldConfig.access, operation, {
-        session: context.session,
-        item,
-        context,
-        inputData,
-      })
-      if (!canWrite) {
-        // Denied: drop the logical key and write none of its columns — exactly
-        // as filterWritableFields drops a denied single-column field.
-        const next = { ...result }
-        delete next[fieldKey]
-        result = next
-        continue
-      }
-      const columns = fieldConfig.splitColumns(fieldKey, resolvedValue)
-      // Drop the logical key (it is not a real column) and merge the columns.
-      const next = { ...result, ...columns }
-      delete next[fieldKey]
-      result = next
-    } else {
-      // Create new object with updated field to avoid mutating the passed reference
-      result = { ...result, [fieldKey]: resolvedValue }
-    }
+    const columns = fieldConfig.splitColumns(fieldKey, resolvedValue)
+    result = { ...result, ...columns }
   }
 
   return result

package/src/index.ts

@@ -21,6 +21,13 @@ export type {
   DatabaseConfig,
   FieldConfig,
   OperationAccess,
+  // Custom Bulk actions (issue #736) — declared per list in
+  // `ui.listView.bulkActions`; the handler runs server-side over the selected
+  // ids through the secured context.
+  BulkAction,
+  BulkActionContext,
+  BulkActionResult,
+  BulkActionVariant,
 } from './config/index.js'
 
 // Access control — the types a consumer writes against
@@ -48,6 +55,10 @@ export { getDbKey, getUrlKey, getListKeyFromUrl } from './lib/case-utils.js'
 // relationship cells, dropdown options, and page headings.
 export { getLabelFieldName, getItemLabel } from './config/label.js'
 
+// Access-scoped nav counts — resolves per-list record counts (opt-in via
+// `ui.navCount`) through the secured context for the admin chrome (issue #735).
+export { resolveNavCounts, isListQueryStaticallyDenied } from './config/nav-count.js'
+
 // Validation error surfaced by write operations
 export { ValidationError } from './hooks/index.js'
 
@@ -72,3 +83,46 @@ export type { ResultOf, RelationSelector, QueryArgs } from './query/index.js'
 // op; also callable directly wherever a full context is already in hand.
 export { getRelationshipOptions } from './query/relationship-options.js'
 export type { RelationshipOption, RelationshipOptionsArgs } from './query/relationship-options.js'
+
+// Filter engine (ADR-0017) — the admin UI's Filter builder. The pure seam
+// (`parseFilterQuery`, `buildFilterWhere`) plus config-aware helpers that
+// collect each field's Filter spec and compose a list's server-side `where`.
+// The produced fragment is ANDed with the access filter through the secured
+// context, so the filter can only ever narrow visibility.
+export {
+  parseFilterQuery,
+  serializeFilterQuery,
+  buildFilterWhere,
+  collectFilterSpecs,
+  buildListFilterWhere,
+  collectFilterSuggestions,
+  RELATIONSHIP_COUNT_FILTER_KEY,
+} from './filter/index.js'
+export type {
+  FilterOperator,
+  FilterToken,
+  FilterCondition,
+  FilterSpec,
+  FilterValueSource,
+  FilterFieldSuggestion,
+  RelationshipCountFilterMarker,
+} from './filter/index.js'
+
+// Access-scoped to-many relationship counts for the admin list view (#732):
+// build the filtered `_count` select for count cells/sort, and resolve the
+// count Filter spec's markers into `{ id: { in } }` — all through the secured
+// context, so counts never include related rows the session cannot read.
+export {
+  buildRelationshipCountSelect,
+  resolveRelationshipCountFilters,
+  isToManyRelationshipField,
+} from './access/relationship-count.js'
+
+// Access-scoped to-one relationship label filters for the admin list view
+// (#749): fold the related list's `query` access into a to-one relationship
+// Filter spec's nested `is` clause so a session can never use a relationship
+// filter token to distinguish rows by a related field it cannot itself read.
+export {
+  resolveRelationshipLabelFilters,
+  isToOneRelationshipField,
+} from './access/relationship-label-filter.js'

package/src/internal.ts

@@ -36,6 +36,11 @@ export { pascalToCamel, pascalToKebab, kebabToPascal, kebabToCamel } from './lib
 // Zod schema helpers used internally for validation
 export { validateWithZod, generateZodSchema } from './validation/schema.js'
 
+// Canonical field-level access evaluator, reused by @opensaas/stack-ui to decide
+// whether a Relationship-table cell may show an inline-edit affordance (#737).
+// This is the single field-access evaluator — the UI must not re-implement it.
+export { checkFieldAccess } from './access/index.js'
+
 // Config-shape sub-types consumed by sibling packages (not part of the consumer surface)
 export type {
   DatabaseConfig,