@opensaas/stack-core 0.21.0 → 0.23.0

package/src/access/multi-column-read-write.test.ts

@@ -0,0 +1,255 @@
+import { describe, it, expect } from 'vitest'
+import { filterReadableFields } from './field-visibility.js'
+import { executeFieldResolveInputHooks } from '../hooks/index.js'
+import type { FieldConfig } from '../config/types.js'
+import type { AccessContext, FieldAccess } from './types.js'
+
+/**
+ * Generic core wiring for multi-column fields (the contract storage
+ * image()/file() use in Keystone-parity mode — see ADR-0006). These tests are
+ * field-agnostic: they assert that ANY field implementing
+ * getColumnNames/assembleColumns/splitColumns is assembled on read (raw columns
+ * stripped) and split on write.
+ */
+
+// A minimal multi-column field: two physical columns `m_url` and `m_size`
+// assembled into `{ url, size }` and split back. Optionally carries field-level
+// access so we can lock the write-access gate around the split.
+function multiColumnField(access?: FieldAccess): FieldConfig {
+  const COLUMNS = ['m_url', 'm_size']
+  return {
+    type: 'multiColumn',
+    access,
+    getColumnNames: () => COLUMNS,
+    assembleColumns: (_fieldName: string, row: Record<string, unknown>) => {
+      const url = row.m_url
+      if (url === null || url === undefined || url === '') return null
+      return { url, size: row.m_size ?? 0 }
+    },
+    splitColumns: (_fieldName: string, value: unknown) => {
+      if (value === null || value === undefined) {
+        return { m_url: null, m_size: null }
+      }
+      const v = value as { url?: unknown; size?: unknown }
+      return { m_url: v.url ?? null, m_size: v.size ?? null }
+    },
+    // Field's own resolveInput is identity here (the value is authoritative).
+    hooks: {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- generic test hook
+      resolveInput: async ({ resolvedData, fieldKey }: any) => resolvedData?.[fieldKey],
+    },
+  } as unknown as FieldConfig
+}
+
+function makeContext(overrides: { isSudo?: boolean } = {}): AccessContext {
+  return {
+    session: null,
+    _isSudo: overrides.isSudo ?? false,
+    _resolveOutputCounter: { depth: 0 },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal context for unit test
+  } as any
+}
+
+describe('multi-column read assembly (filterReadableFields)', () => {
+  const fields = { media: multiColumnField() }
+
+  it('assembles the per-part columns into the logical field and strips the raw columns', async () => {
+    const row = { id: 'a', m_url: 'https://x/y.jpg', m_size: 99, title: 'hi' }
+    const result = await filterReadableFields(
+      row,
+      // title is a plain field
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- inline field configs
+      { ...fields, title: { type: 'text' } as any },
+      { session: null, context: makeContext() },
+      undefined,
+      0,
+      'Post',
+    )
+    expect(result).toEqual({ id: 'a', title: 'hi', media: { url: 'https://x/y.jpg', size: 99 } })
+    // Raw columns must NOT leak.
+    expect('m_url' in result).toBe(false)
+    expect('m_size' in result).toBe(false)
+  })
+
+  it('assembles a partially-populated row (only m_url present)', async () => {
+    const row = { id: 'b', m_url: 'https://x/only.jpg' }
+    const result = await filterReadableFields(
+      row,
+      fields,
+      { session: null, context: makeContext() },
+      undefined,
+      0,
+      'Post',
+    )
+    expect(result).toEqual({ id: 'b', media: { url: 'https://x/only.jpg', size: 0 } })
+  })
+
+  it('yields a null logical value when the columns are empty', async () => {
+    const row = { id: 'c', m_url: null, m_size: null }
+    const result = await filterReadableFields(
+      row,
+      fields,
+      { session: null, context: makeContext() },
+      undefined,
+      0,
+      'Post',
+    )
+    expect(result).toEqual({ id: 'c', media: null })
+  })
+
+  it('leaves the field absent when its columns were not selected', async () => {
+    const row = { id: 'd', title: 'no media columns' }
+    const result = await filterReadableFields(
+      row,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- inline field configs
+      { ...fields, title: { type: 'text' } as any },
+      { session: null, context: makeContext() },
+      undefined,
+      0,
+      'Post',
+    )
+    expect(result).toEqual({ id: 'd', title: 'no media columns' })
+    expect('media' in result).toBe(false)
+  })
+})
+
+describe('multi-column write split (executeFieldResolveInputHooks)', () => {
+  const fields = { media: multiColumnField() }
+
+  it('splits the logical value into per-part columns and removes the logical key', async () => {
+    const inputData = { media: { url: 'https://x/y.jpg', size: 99 } }
+    const result = await executeFieldResolveInputHooks(
+      inputData,
+      { ...inputData },
+      fields,
+      'create',
+      makeContext(),
+      'Post',
+    )
+    expect(result).toEqual({ m_url: 'https://x/y.jpg', m_size: 99 })
+    expect('media' in result).toBe(false)
+  })
+
+  it('splitting null clears all per-part columns', async () => {
+    const inputData = { media: null }
+    const result = await executeFieldResolveInputHooks(
+      inputData,
+      { ...inputData },
+      fields,
+      'update',
+      makeContext(),
+      'Post',
+    )
+    expect(result).toEqual({ m_url: null, m_size: null })
+  })
+
+  it('does not touch the columns when the logical field is absent from the write', async () => {
+    const inputData = { title: 'no media in payload' }
+    const result = await executeFieldResolveInputHooks(
+      inputData,
+      { ...inputData },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- inline field configs
+      { ...fields, title: { type: 'text' } as any },
+      'update',
+      makeContext(),
+      'Post',
+    )
+    expect(result).toEqual({ title: 'no media in payload' })
+    expect('m_url' in result).toBe(false)
+  })
+})
+
+describe('multi-column write split respects field-level write access', () => {
+  it('does NOT write any per-part columns when update access is denied', async () => {
+    const fields = { media: multiColumnField({ update: () => false }) }
+    const inputData = { media: { url: 'https://x/y.jpg', size: 99 } }
+    const result = await executeFieldResolveInputHooks(
+      inputData,
+      { ...inputData },
+      fields,
+      'update',
+      makeContext(),
+      'Post',
+    )
+    // The logical key is dropped (it is not a real column) AND none of its
+    // per-part columns are written — identical to how filterWritableFields
+    // drops a denied single-column field.
+    expect(result).toEqual({})
+    expect('media' in result).toBe(false)
+    expect('m_url' in result).toBe(false)
+    expect('m_size' in result).toBe(false)
+  })
+
+  it('does NOT write any per-part columns when create access is denied', async () => {
+    const fields = { media: multiColumnField({ create: () => false }) }
+    const inputData = { media: { url: 'https://x/y.jpg', size: 99 } }
+    const result = await executeFieldResolveInputHooks(
+      inputData,
+      { ...inputData },
+      fields,
+      'create',
+      makeContext(),
+      'Post',
+    )
+    expect(result).toEqual({})
+    expect('m_url' in result).toBe(false)
+  })
+
+  it('still splits/writes the columns when write access is granted', async () => {
+    const fields = { media: multiColumnField({ update: () => true, create: () => true }) }
+    const inputData = { media: { url: 'https://x/y.jpg', size: 99 } }
+    const result = await executeFieldResolveInputHooks(
+      inputData,
+      { ...inputData },
+      fields,
+      'update',
+      makeContext(),
+      'Post',
+    )
+    expect(result).toEqual({ m_url: 'https://x/y.jpg', m_size: 99 })
+    expect('media' in result).toBe(false)
+  })
+
+  it('denying the OTHER operation does not block the write (update field, create op)', async () => {
+    // A field that denies `update` must still be writable on `create`.
+    const fields = { media: multiColumnField({ update: () => false }) }
+    const inputData = { media: { url: 'https://x/y.jpg', size: 99 } }
+    const result = await executeFieldResolveInputHooks(
+      inputData,
+      { ...inputData },
+      fields,
+      'create',
+      makeContext(),
+      'Post',
+    )
+    expect(result).toEqual({ m_url: 'https://x/y.jpg', m_size: 99 })
+  })
+
+  it('sudo bypasses the field-access gate and still splits', async () => {
+    const fields = { media: multiColumnField({ update: () => false }) }
+    const inputData = { media: { url: 'https://x/y.jpg', size: 99 } }
+    const result = await executeFieldResolveInputHooks(
+      inputData,
+      { ...inputData },
+      fields,
+      'update',
+      makeContext({ isSudo: true }),
+      'Post',
+    )
+    expect(result).toEqual({ m_url: 'https://x/y.jpg', m_size: 99 })
+  })
+
+  it('a multi-column field WITHOUT field-level access splits exactly as before', async () => {
+    const fields = { media: multiColumnField() }
+    const inputData = { media: { url: 'https://x/y.jpg', size: 99 } }
+    const result = await executeFieldResolveInputHooks(
+      inputData,
+      { ...inputData },
+      fields,
+      'update',
+      makeContext(),
+      'Post',
+    )
+    expect(result).toEqual({ m_url: 'https://x/y.jpg', m_size: 99 })
+  })
+})

package/src/config/index.ts

@@ -122,6 +122,7 @@ export function list<TTypeInfo extends import('./types.js').TypeInfo>(
 // Re-export all types
 export type {
   OpenSaasConfig,
+  OutputConfig,
   ListConfig,
   ListConfigInput,
   ListAccessControl,
@@ -135,6 +136,7 @@ export type {
   SelectField,
   RelationshipField,
   PrismaRelationResult,
+  MultiColumnPrismaResult,
   JsonField,
   VirtualField,
   TypeDescriptor,

package/src/config/types.ts

@@ -462,12 +462,16 @@ export type BaseFieldConfig<TTypeInfo extends TypeInfo> = {
    * @param fieldName - The name of the field (for generating modifiers)
    * @param provider - Optional database provider ('sqlite', 'postgresql', 'mysql', etc.)
    * @param listName - Optional list name (used for generating enum type names)
+   * @param keystoneCompat - Whether Keystone-compat mode is enabled (db.keystoneCompat).
+   *   When true, non-null text columns without an explicit defaultValue emit
+   *   `@default("")` to match Keystone 6's implicit empty-string text default.
    * @returns Prisma type string, optional modifiers, and optional enum values
    */
   getPrismaType?: (
     fieldName: string,
     provider?: string,
     listName?: string,
+    keystoneCompat?: boolean,
   ) => {
     type: string
     modifiers?: string
@@ -506,6 +510,72 @@ export type BaseFieldConfig<TTypeInfo extends TypeInfo> = {
      */
     typeOnly?: boolean
   }>
+  /**
+   * Multi-column Prisma emission.
+   *
+   * Most scalar fields back a single Prisma column via {@link getPrismaType}.
+   * A field that maps onto SEVERAL physical columns (e.g. the storage
+   * `image()`/`file()` fields in multi-column / Keystone-parity mode — see
+   * ADR-0006) implements this instead: it returns one descriptor per column,
+   * each becoming its own line in the generated model. When present, the
+   * generator emits these lines and skips the single-column `getPrismaType`
+   * path. The field itself owns the column layout — the generator stays a
+   * neutral coordinator (no field-type switches), mirroring how relationship
+   * fields emit FK + relation lines through `getPrismaRelation`.
+   *
+   * @param fieldName - The field's config key (used to derive default column names)
+   * @returns One descriptor per physical column, or `undefined` to fall back to
+   *   the single-column `getPrismaType` path.
+   */
+  getPrismaColumns?: (fieldName: string) => MultiColumnPrismaResult[] | undefined
+  /**
+   * The physical Prisma column names this field owns when it spans multiple
+   * columns (see {@link getPrismaColumns}). The read path uses this to strip the
+   * raw per-part columns from query results so only the assembled logical value
+   * (produced by {@link assembleColumns}) is exposed.
+   *
+   * @param fieldName - The field's config key
+   */
+  getColumnNames?: (fieldName: string) => string[]
+  /**
+   * Assemble the field's logical value from a database row's per-part columns
+   * (the read direction of a multi-column field). Pure transform — called by the
+   * read pipeline before field visibility. Receives the full row so it can read
+   * its sibling columns by name.
+   *
+   * @param fieldName - The field's config key
+   * @param row - The raw database row (contains the per-part columns)
+   */
+  assembleColumns?: (fieldName: string, row: Record<string, unknown>) => unknown
+  /**
+   * Split the field's logical value into per-part columns for writing (the write
+   * direction of a multi-column field). Pure transform — called by the write
+   * pipeline after `resolveInput`; the returned record is merged into the write
+   * payload in place of the single field key.
+   *
+   * @param fieldName - The field's config key
+   * @param value - The resolved logical value (metadata, or `null` to clear)
+   */
+  splitColumns?: (fieldName: string, value: unknown) => Record<string, unknown>
+}
+
+/**
+ * A single physical column contributed by a multi-column field
+ * (see {@link BaseFieldConfig.getPrismaColumns}).
+ */
+export type MultiColumnPrismaResult = {
+  /** The Prisma model field name (the property the column is declared as). */
+  name: string
+  /** The Prisma scalar type, e.g. `'String'` or `'Int'`. */
+  type: string
+  /**
+   * Field modifiers, e.g. `'?'` for nullable. A leading `'?'` attaches to the
+   * type; anything after it is treated as trailing attributes (matching the
+   * single-column `getPrismaType` modifier convention).
+   */
+  modifiers?: string
+  /** Physical column name for the `@map` attribute, when it differs from `name`. */
+  map?: string
 }
 
 export type TextField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
@@ -587,6 +657,46 @@ export type SelectField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig
      */
     type?: 'string' | 'enum'
     map?: string
+    /**
+     * Force the generated column to be nullable (`?`) even when a `defaultValue`
+     * is present. By default a select with a `defaultValue` generates NOT NULL;
+     * set this to `true` for an explicit opt-in to a nullable column with a
+     * default (e.g. `String? @default("X")` or `<Enum>? @default(X)`), so that
+     * a live column containing NULLs migrates without a NOT NULL failure.
+     *
+     * @default undefined (NOT NULL when a default is present — unchanged behaviour)
+     *
+     * @example
+     * ```typescript
+     * // Optional select with a default, but keep the column nullable
+     * status: select({
+     *   options: [{ label: 'Draft', value: 'draft' }],
+     *   defaultValue: 'draft',
+     *   db: { isNullable: true },
+     * })
+     * // Generates: String? @default("draft")
+     * ```
+     */
+    isNullable?: boolean
+    /**
+     * Override the generated Prisma enum type name for native-enum selects
+     * (only applies when `type: 'enum'`). By default the enum is named
+     * `<List><Field>` (e.g. `AccountNoteStatus`); set this to match a live DB
+     * enum type whose name differs (e.g. Keystone's `…Type` suffix).
+     *
+     * The custom name is applied to both the generated `enum` block and every
+     * reference to it in the owning model.
+     *
+     * @example
+     * ```typescript
+     * status: select({
+     *   options: [{ label: 'Open', value: 'open' }],
+     *   db: { type: 'enum', enumName: 'AccountNoteStatusType' },
+     * })
+     * // Generates: enum AccountNoteStatusType { ... } and the column references it
+     * ```
+     */
+    enumName?: string
   }
   validation?: {
     isRequired?: boolean
@@ -1199,6 +1309,65 @@ export type ListConfig<TTypeInfo extends TypeInfo> = {
     operation?: OperationAccess<TTypeInfo['item']>
   }
   hooks?: Hooks<TTypeInfo['item'], TTypeInfo['inputs']['create'], TTypeInfo['inputs']['update']>
+  /**
+   * Database configuration for this list (model level)
+   */
+  db?: {
+    /**
+     * Custom database table name.
+     * Adds a `@@map` attribute to the generated Prisma model.
+     *
+     * Useful when the Prisma model name (the list key) must differ from the
+     * physical table name — e.g. adopting an existing better-auth installation
+     * whose tables were created under a different name.
+     *
+     * @example
+     * ```typescript
+     * AuthUser: list({ fields: { ... }, db: { map: 'user' } })
+     * // Generates: model AuthUser { ... @@map("user") }
+     * ```
+     */
+    map?: string
+    /**
+     * Database schema for this model (Postgres multi-schema).
+     * Adds a `@@schema` attribute to the generated Prisma model.
+     *
+     * Requires the schema to be listed in the datasource `schemas` array (see
+     * {@link DatabaseConfig.schemas}) and the `multiSchema` preview feature,
+     * both of which the generator emits automatically when `db.schemas` is set.
+     *
+     * Useful when adopting an existing installation whose tables live in a
+     * non-`public` schema — e.g. a separate-schema better-auth layout.
+     *
+     * @example
+     * ```typescript
+     * AuthUser: list({ fields: { ... }, db: { schema: 'auth' } })
+     * // Generates: model AuthUser { ... @@schema("auth") }
+     * ```
+     */
+    schema?: string
+    /**
+     * Per-list override for auto-injected `createdAt`/`updatedAt` timestamp columns.
+     *
+     * Takes precedence over the global `db.timestamps` setting:
+     * - `true` forces auto-timestamps on for this list, even when the global default is off.
+     * - `false` forces them off for this list, even when enabled globally.
+     * - `undefined` (the default) falls back to the global `db.timestamps` setting.
+     *
+     * When timestamps resolve to on but the list already declares its own `createdAt`/
+     * `updatedAt` field, the auto column is skipped for the declared field(s) so Prisma
+     * never sees a duplicate (`P1012`).
+     *
+     * @example Opt a single list out of timestamps even when enabled globally
+     * ```typescript
+     * Production: list({
+     *   fields: { name: text() },
+     *   db: { timestamps: false },
+     * })
+     * ```
+     */
+    timestamps?: boolean
+  }
   /**
    * MCP server configuration for this list
    */
@@ -1331,6 +1500,86 @@ export type DatabaseConfig = {
    * ```
    */
   joinTableNaming?: 'prisma' | 'keystone'
+  /**
+   * Postgres multi-schema support.
+   *
+   * When set, the generator enables Prisma's `multiSchema` preview feature and
+   * emits the `schemas = [...]` array on the datasource block. Combine with a
+   * per-list `db.schema` (see {@link ListConfig}) to place models in a specific
+   * schema via `@@schema(...)`.
+   *
+   * Only applies to the `postgresql` provider. When unset, the generated schema
+   * is unchanged (single `public` schema, no `@@schema` attributes).
+   *
+   * @example Separate `auth` schema alongside the default `public`
+   * ```typescript
+   * db: {
+   *   provider: 'postgresql',
+   *   schemas: ['public', 'auth'],
+   *   // ...
+   * }
+   * ```
+   */
+  schemas?: string[]
+  /**
+   * Auto-inject `createdAt`/`updatedAt` timestamp columns into every generated model.
+   *
+   * Default: `false`. The generator does NOT add timestamps automatically — a list
+   * opts in either by declaring the fields itself or by enabling this flag. This matches
+   * Keystone 6, which never adds timestamps automatically, and keeps Keystone → stack
+   * migrations non-destructive (Schema parity). See ADR-0004.
+   *
+   * When `true`, every list receives:
+   * ```prisma
+   * createdAt DateTime @default(now())
+   * updatedAt DateTime @default(now()) @updatedAt
+   * ```
+   *
+   * A per-list `db.timestamps` override takes precedence over this global setting. When
+   * timestamps are enabled but a list already declares its own `createdAt`/`updatedAt`
+   * field, the auto column is skipped for the declared field(s) so Prisma never sees a
+   * duplicate (`P1012`).
+   *
+   * @default false
+   *
+   * @example Re-enable auto-timestamps globally
+   * ```typescript
+   * db: {
+   *   provider: 'postgresql',
+   *   timestamps: true,
+   *   // ... rest of config
+   * }
+   * ```
+   */
+  timestamps?: boolean
+  /**
+   * Opt into Keystone-compat mode for generated schema defaults.
+   *
+   * Keystone 6 gives every non-null text column an implicit empty-string
+   * default. With `keystoneCompat: true`, the generator mirrors that: any
+   * non-null `text()` column that has no explicit `defaultValue` emits
+   * `@default("")`, so a migrating project reaches Schema parity without
+   * hand-setting `defaultValue: ''` on dozens of columns.
+   *
+   * Stays opt-in (default `false`) because a greenfield project would not want
+   * implicit empty-string text defaults cluttering its schema. The flag never
+   * affects nullable text, fields with an explicit `defaultValue`, or any
+   * non-text field — an explicit `text({ defaultValue: 'x' })` always wins.
+   *
+   * @default false
+   *
+   * @example Reach Schema parity when migrating from Keystone
+   * ```typescript
+   * db: {
+   *   provider: 'postgresql',
+   *   keystoneCompat: true, // non-null text without a default → @default("")
+   *   // ... rest of config
+   * }
+   * ```
+   *
+   * @see ADR-0004 (Keystone-compatible generator defaults)
+   */
+  keystoneCompat?: boolean
   /**
    * Optional function to extend or modify the generated Prisma schema
    * Receives the generated schema as a string and should return the modified schema
@@ -1821,6 +2070,34 @@ export type Plugin = {
  * Main configuration type
  * Using interface instead of type to allow module augmentation
  */
+/**
+ * Configurable generator output locations.
+ *
+ * Lets a project relocate the generated Prisma schema and the `.opensaas`
+ * bundle directory. Paths are interpreted relative to the project root.
+ *
+ * @example
+ * ```typescript
+ * output: {
+ *   prismaSchema: 'prisma-opensaas/schema.prisma',
+ *   opensaasDir: '.opensaas',
+ * }
+ * ```
+ */
+export interface OutputConfig {
+  /**
+   * Path to the generated Prisma schema file.
+   * @default "prisma/schema.prisma"
+   */
+  prismaSchema?: string
+  /**
+   * Directory for the generated `.opensaas` bundle (types, lists, context,
+   * plugin-types, prisma-extensions, and the patched Prisma client).
+   * @default ".opensaas"
+   */
+  opensaasDir?: string
+}
+
 export interface OpenSaasConfig {
   db: DatabaseConfig
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Config must accept any list configuration
@@ -1841,6 +2118,20 @@ export interface OpenSaasConfig {
    * @default ".opensaas"
    */
   opensaasPath?: string
+  /**
+   * Relocate the generator's output so `opensaas generate` can coexist with an
+   * existing `prisma/` directory (e.g. during a Keystone → stack migration).
+   *
+   * Both fields are resolved relative to the project root (the directory the
+   * CLI runs in). When omitted, defaults are unchanged: the schema is written to
+   * `prisma/schema.prisma` and the `.opensaas` bundle to `.opensaas/`.
+   *
+   * The generated files' cross-references follow these locations — `context.ts`
+   * imports the generated types/lists from the resolved `.opensaas` dir, and the
+   * top-level `prisma.config.ts` points at the configured schema path so the
+   * `prisma` CLI keeps working.
+   */
+  output?: OutputConfig
   /**
    * Plugins to extend the stack
    * Executed in array order (or dependency order if dependencies specified)

package/src/context/index.ts

@@ -22,6 +22,41 @@ export type ServerActionProps =
   | { listKey: string; action: 'update'; id: string; data: Record<string, unknown> }
   | { listKey: string; action: 'delete'; id: string }
 
+/**
+ * Tracks which (listName, operation) pairs have already warned about an ignored
+ * `select` argument, so a misused read op warns once rather than on every call.
+ */
+const selectWarnings = new Set<string>()
+
+/**
+ * Warn (once per list+operation) when a caller passes a `select` argument to a
+ * read op that does not honour it.
+ *
+ * `context.db` reads never apply Prisma `select` semantics — narrowing is done
+ * via `include` or a fragment `query`. The op still runs and returns the full,
+ * access-filtered result, so this is a visible no-op rather than an error.
+ *
+ * Centralised here so every affected read op shares one implementation.
+ */
+function warnIfSelectIgnored(
+  args: { select?: unknown } | undefined,
+  listName: string,
+  operation: string,
+): void {
+  if (!args || args.select === undefined) return
+
+  const key = `${listName}.${operation}`
+  if (selectWarnings.has(key)) return
+  selectWarnings.add(key)
+
+  console.warn(
+    `[@opensaas/stack-core] \`select\` is ignored by context.db.${getDbKey(listName)}.${operation}() ` +
+      `and the full (access-filtered) record is returned. ` +
+      `Narrow a read with \`include\` or a fragment \`query\` instead. ` +
+      `See https://stack.opensaas.au/docs/core-concepts/queries`,
+  )
+}
+
 /**
  * Check if a list is configured as a singleton
  */
@@ -373,7 +408,12 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
     include?: Record<string, unknown>
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     query?: any
+    // `select` is not honoured — accepted only so the no-op can be made visible.
+    select?: Record<string, unknown>
   }) => {
+    // `select` is a visible no-op: warn, then proceed with include/query narrowing.
+    warnIfSelectIgnored(args, listName, 'findUnique')
+
     // Check query access (skip if sudo mode)
     let where: Record<string, unknown> = args.where
     if (!context._isSudo) {
@@ -471,7 +511,12 @@ function createFindMany<TPrisma extends PrismaClientLike>(
     include?: Record<string, unknown>
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     query?: any
+    // `select` is not honoured — accepted only so the no-op can be made visible.
+    select?: Record<string, unknown>
   }) => {
+    // `select` is a visible no-op: warn, then proceed with include/query narrowing.
+    warnIfSelectIgnored(args, listName, 'findMany')
+
     // Check singleton constraint (throw error instead of silently returning empty)
     if (isSingletonList(listConfig)) {
       throw new ValidationError(

package/src/extend.ts

@@ -11,4 +11,9 @@
 export type { Plugin, PluginContext, GeneratedFiles } from './config/index.js'
 
 // Third-party field authoring (implement BaseFieldConfig; see custom-field docs)
-export type { BaseFieldConfig, TypeInfo, TypeDescriptor } from './config/index.js'
+export type {
+  BaseFieldConfig,
+  TypeInfo,
+  TypeDescriptor,
+  MultiColumnPrismaResult,
+} from './config/index.js'