@opensaas/stack-core 0.26.0 → 0.27.0

package/src/query/relationship-options.test.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect, vi } from 'vitest'
+import { getRelationshipOptions } from './relationship-options.js'
+import type { QueryRunnerContext } from './index.js'
+import type { OpenSaasConfig } from '../config/types.js'
+
+function makeDelegate(rows: Array<Record<string, unknown>>) {
+  return {
+    findMany: vi.fn(async (_args?: unknown) => rows),
+    findFirst: vi.fn(async (_args?: unknown) => rows[0] ?? null),
+  }
+}
+
+function makeContext(
+  delegates: Record<string, ReturnType<typeof makeDelegate>>,
+): QueryRunnerContext {
+  return { db: delegates }
+}
+
+const authors = [
+  { id: 'a1', name: 'Ada Lovelace' },
+  { id: 'a2', name: 'Alan Turing' },
+  { id: 'a3', name: 'Grace Hopper' },
+]
+
+function makeConfig(): OpenSaasConfig {
+  return {
+    db: { provider: 'sqlite', url: 'file:./test.db' },
+    lists: {
+      Author: {
+        fields: {
+          name: { type: 'text' },
+        },
+        access: { operation: { query: () => true } },
+      },
+      NumericLabel: {
+        fields: {
+          rank: { type: 'integer' },
+        },
+        ui: { labelField: 'rank' },
+        access: { operation: { query: () => true } },
+      },
+    },
+  } as unknown as OpenSaasConfig
+}
+
+describe('getRelationshipOptions', () => {
+  it('returns { id, label }[] via a scalar-only fragment with no nested include', async () => {
+    const delegate = makeDelegate(authors)
+    const context = makeContext({ author: delegate })
+    const config = makeConfig()
+
+    const result = await getRelationshipOptions(context, config, 'Author', {})
+
+    expect(result).toEqual([
+      { id: 'a1', label: 'Ada Lovelace' },
+      { id: 'a2', label: 'Alan Turing' },
+      { id: 'a3', label: 'Grace Hopper' },
+    ])
+
+    const call = delegate.findMany.mock.calls[0][0] as Record<string, unknown>
+    expect(call.include).toBeUndefined()
+  })
+
+  it('bounds the result by take', async () => {
+    const delegate = makeDelegate(authors.slice(0, 2))
+    const context = makeContext({ author: delegate })
+    const config = makeConfig()
+
+    await getRelationshipOptions(context, config, 'Author', { take: 2 })
+
+    expect(delegate.findMany).toHaveBeenCalledWith(expect.objectContaining({ take: 2 }))
+  })
+
+  it('orders by the label field ascending and filters via contains on a text label field', async () => {
+    const delegate = makeDelegate([authors[0]])
+    const context = makeContext({ author: delegate })
+    const config = makeConfig()
+
+    await getRelationshipOptions(context, config, 'Author', { search: 'Ada' })
+
+    expect(delegate.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { name: { contains: 'Ada' } },
+        orderBy: { name: 'asc' },
+      }),
+    )
+  })
+
+  it('does not filter (first-N) when the label field is not a text field', async () => {
+    const rows = [{ id: 'n1', rank: 1 }]
+    const delegate = makeDelegate(rows)
+    const context = makeContext({ numericLabel: delegate })
+    const config = makeConfig()
+
+    await getRelationshipOptions(context, config, 'NumericLabel', { search: '1' })
+
+    const call = delegate.findMany.mock.calls[0][0] as Record<string, unknown>
+    expect(call.where).toBeUndefined()
+    expect(call.orderBy).toEqual({ rank: 'asc' })
+  })
+
+  it('unions currently-selected ids even when beyond take / not matching search', async () => {
+    // The bounded/search-scoped query only returns a1 (mimicking take:1 + search).
+    const primaryDelegate = makeDelegate([authors[0]])
+    const context = makeContext({ author: primaryDelegate })
+    const config = makeConfig()
+
+    // The selected-ids query (a separate findMany call) resolves a3, which fell
+    // outside the primary window.
+    primaryDelegate.findMany.mockImplementationOnce(async () => [authors[0]])
+    primaryDelegate.findMany.mockImplementationOnce(async () => [authors[2]])
+
+    const result = await getRelationshipOptions(context, config, 'Author', {
+      take: 1,
+      selectedIds: ['a3'],
+    })
+
+    expect(result).toEqual([
+      { id: 'a1', label: 'Ada Lovelace' },
+      { id: 'a3', label: 'Grace Hopper' },
+    ])
+
+    const selectedCall = primaryDelegate.findMany.mock.calls[1][0] as Record<string, unknown>
+    expect(selectedCall.where).toEqual({ id: { in: ['a3'] } })
+  })
+
+  it('does not re-query when the selected id is already within the primary window', async () => {
+    const delegate = makeDelegate([authors[0]])
+    const context = makeContext({ author: delegate })
+    const config = makeConfig()
+
+    await getRelationshipOptions(context, config, 'Author', { selectedIds: ['a1'] })
+
+    expect(delegate.findMany).toHaveBeenCalledTimes(1)
+  })
+
+  it('returns [] when the related list query access is denied (findMany returns [])', async () => {
+    const delegate = makeDelegate([])
+    const context = makeContext({ author: delegate })
+    const config = makeConfig()
+
+    const result = await getRelationshipOptions(context, config, 'Author', {
+      selectedIds: ['a1'],
+    })
+
+    expect(result).toEqual([])
+  })
+
+  it('returns [] when the related list does not exist in config', async () => {
+    const context = makeContext({})
+    const config = makeConfig()
+
+    const result = await getRelationshipOptions(context, config, 'Missing', {})
+
+    expect(result).toEqual([])
+  })
+})

package/src/query/relationship-options.ts

@@ -0,0 +1,70 @@
+import type { OpenSaasConfig } from '../config/types.js'
+import { getLabelFieldName, getItemLabel } from '../config/label.js'
+import { defineFragment, runQuery, type QueryRunnerContext } from './index.js'
+
+const DEFAULT_TAKE = 50
+
+export interface RelationshipOption {
+  id: string
+  label: string
+}
+
+export interface RelationshipOptionsArgs {
+  /** Filters the label field via `contains` when it is a text field. */
+  search?: string
+  /** Bounds the primary (search-scoped) window. @default 50 */
+  take?: number
+  /** Always unioned into the result, even outside the search/take window. */
+  selectedIds?: string[]
+}
+
+/**
+ * Bounded, projected fetch of `{ id, label }` options for a relationship
+ * editor — the read primitive behind the `relationshipOptions` serverAction
+ * op. Selects only `id` and the resolved label field (via
+ * {@link getLabelFieldName}), so the fragment carries no relation keys and
+ * `buildIncludeWithAccessControl`'s depth-5 auto-include never runs.
+ *
+ * Operation-level `query` access on `relatedListKey` still applies — a denied
+ * list resolves to `[]` (via the underlying access-controlled `findMany`).
+ */
+export async function getRelationshipOptions(
+  context: QueryRunnerContext,
+  config: OpenSaasConfig,
+  relatedListKey: string,
+  args: RelationshipOptionsArgs = {},
+): Promise<RelationshipOption[]> {
+  const relatedListConfig = config.lists[relatedListKey]
+  if (!relatedListConfig) return []
+
+  const labelField = getLabelFieldName(relatedListConfig)
+  const fragment = defineFragment<Record<string, unknown>>()({
+    id: true,
+    [labelField]: true,
+  })
+
+  const { search, take = DEFAULT_TAKE, selectedIds = [] } = args
+  const labelFieldConfig = relatedListConfig.fields[labelField] as { type?: string } | undefined
+  const where =
+    search && labelFieldConfig?.type === 'text' ? { [labelField]: { contains: search } } : undefined
+
+  const primary = await runQuery(context, relatedListKey, fragment, {
+    where,
+    orderBy: { [labelField]: 'asc' },
+    take,
+  })
+
+  const seenIds = new Set(primary.map((item) => (item as { id: string }).id))
+  const missingSelectedIds = selectedIds.filter((id) => !seenIds.has(id))
+
+  const selected = missingSelectedIds.length
+    ? await runQuery(context, relatedListKey, fragment, {
+        where: { id: { in: missingSelectedIds } },
+      })
+    : []
+
+  return [...primary, ...selected].map((item) => ({
+    id: (item as { id: string }).id,
+    label: getItemLabel(relatedListConfig, item as Record<string, unknown>),
+  }))
+}

package/tests/context.test.ts

@@ -57,6 +57,7 @@ describe('getContext', () => {
           fields: {
             title: { type: 'text' },
             content: { type: 'text' },
+            author: { type: 'relationship', ref: 'User.posts' },
           },
           access: {
             operation: {
@@ -200,6 +201,119 @@ describe('getContext', () => {
         error: 'Database connection failed',
       })
     })
+
+    describe('relationshipOptions', () => {
+      it('returns { id, label }[] for the related list, unfiltered/unincluded', async () => {
+        mockPrisma.user.findMany.mockResolvedValue([
+          { id: 'u1', name: 'Ada' },
+          { id: 'u2', name: 'Alan' },
+        ])
+
+        const context = await getContext(config, mockPrisma, null)
+        const result = await context.serverAction({
+          listKey: 'Post',
+          action: 'relationshipOptions',
+          field: 'author',
+        })
+
+        expect(result).toEqual({
+          success: true,
+          data: [
+            { id: 'u1', label: 'Ada' },
+            { id: 'u2', label: 'Alan' },
+          ],
+        })
+        const call = mockPrisma.user.findMany.mock.calls[0][0]
+        expect(call.include).toBeUndefined()
+      })
+
+      it('bounds the query by take', async () => {
+        mockPrisma.user.findMany.mockResolvedValue([{ id: 'u1', name: 'Ada' }])
+
+        const context = await getContext(config, mockPrisma, null)
+        await context.serverAction({
+          listKey: 'Post',
+          action: 'relationshipOptions',
+          field: 'author',
+          take: 1,
+        })
+
+        expect(mockPrisma.user.findMany).toHaveBeenCalledWith(expect.objectContaining({ take: 1 }))
+      })
+
+      it('unions selectedIds beyond the take/search window', async () => {
+        mockPrisma.user.findMany.mockResolvedValueOnce([{ id: 'u1', name: 'Ada' }])
+        mockPrisma.user.findMany.mockResolvedValueOnce([{ id: 'u9', name: 'Zed' }])
+
+        const context = await getContext(config, mockPrisma, null)
+        const result = await context.serverAction({
+          listKey: 'Post',
+          action: 'relationshipOptions',
+          field: 'author',
+          take: 1,
+          selectedIds: ['u9'],
+        })
+
+        expect(result).toEqual({
+          success: true,
+          data: [
+            { id: 'u1', label: 'Ada' },
+            { id: 'u9', label: 'Zed' },
+          ],
+        })
+      })
+
+      it('returns [] data when the related list query access is denied', async () => {
+        const deniedConfig: OpenSaasConfig = {
+          ...config,
+          lists: {
+            ...config.lists,
+            User: {
+              ...config.lists.User,
+              access: { operation: { query: () => false } },
+            },
+          },
+        }
+        mockPrisma.user.findMany.mockResolvedValue([{ id: 'u1', name: 'Ada' }])
+
+        const context = await getContext(deniedConfig, mockPrisma, null)
+        const result = await context.serverAction({
+          listKey: 'Post',
+          action: 'relationshipOptions',
+          field: 'author',
+        })
+
+        expect(result).toEqual({ success: true, data: [] })
+      })
+
+      it('returns an error when the field is not a relationship field', async () => {
+        const context = await getContext(config, mockPrisma, null)
+        const result = await context.serverAction({
+          listKey: 'Post',
+          action: 'relationshipOptions',
+          field: 'title',
+        })
+
+        expect(result).toEqual({
+          success: false,
+          error: 'Field "title" on list "Post" is not a relationship field',
+        })
+      })
+
+      it('returns an error when the field does not exist', async () => {
+        const context = await getContext(config, mockPrisma, null)
+        const result = await context.serverAction({
+          listKey: 'Post',
+          action: 'relationshipOptions',
+          field: 'nonexistent',
+        })
+
+        expect(result).toEqual({
+          success: false,
+          error: 'Field "nonexistent" on list "Post" is not a relationship field',
+        })
+      })
+    })
   })
 
   describe('db operations', () => {
@@ -705,6 +819,112 @@ describe('getContext', () => {
         // identical `accessControlledInclude === undefined` branch verified above,
         // so the resolveOutput probe covers all three non-denial cases.
       })
+
+      // Regression for #628: a virtual field named in `include` used to be
+      // forwarded straight through to Prisma, which throws "Unknown field"
+      // because virtual fields have no database column. The runtime must
+      // strip virtual keys from the include payload while still computing
+      // the virtual value (via resolveOutput) and leaving real relationship
+      // includes — access-controlled or not — untouched.
+      describe('virtual fields named in include no longer reach Prisma (#628)', () => {
+        function configWithVirtualDisplayName(): OpenSaasConfig {
+          return {
+            ...relConfig,
+            lists: {
+              ...relConfig.lists,
+              Author: {
+                ...relConfig.lists.Author,
+                fields: {
+                  ...relConfig.lists.Author.fields,
+                  displayName: virtual({
+                    type: 'string',
+                    hooks: {
+                      resolveOutput: ({ item }) => `Author: ${item.name}`,
+                    },
+                  }),
+                },
+              },
+            },
+          }
+        }
+
+        it('findMany: strips the virtual key from the Prisma include but keeps the real relationship include, and computes the virtual value', async () => {
+          const vConfig = configWithVirtualDisplayName()
+          relPrisma.author.findMany.mockResolvedValue([{ id: 'a1', name: 'Jo', posts: [] }])
+
+          const context = await getContext(vConfig, relPrisma, null)
+          const result = await context.db.author.findMany({
+            include: { displayName: true, posts: true },
+          })
+
+          const call = relPrisma.author.findMany.mock.calls[0][0]
+          expect(call.include).not.toHaveProperty('displayName')
+          expect(call.include.posts).toBeDefined()
+          expect(result[0].displayName).toBe('Author: Jo')
+        })
+
+        it('findUnique: strips the virtual key from the Prisma include but keeps the real relationship include, and computes the virtual value', async () => {
+          const vConfig = configWithVirtualDisplayName()
+          relPrisma.author.findFirst.mockResolvedValue({ id: 'a1', name: 'Jo', posts: [] })
+
+          const context = await getContext(vConfig, relPrisma, null)
+          const result = await context.db.author.findUnique({
+            where: { id: 'a1' },
+            include: { displayName: true, posts: true },
+          })
+
+          const call = relPrisma.author.findFirst.mock.calls[0][0]
+          expect(call.include).not.toHaveProperty('displayName')
+          expect(call.include.posts).toBeDefined()
+          expect(result.displayName).toBe('Author: Jo')
+        })
+
+        it('the virtual value is populated even when omitted from include', async () => {
+          const vConfig = configWithVirtualDisplayName()
+          relPrisma.author.findFirst.mockResolvedValue({ id: 'a1', name: 'Jo' })
+
+          const context = await getContext(vConfig, relPrisma, null)
+          const result = await context.db.author.findUnique({ where: { id: 'a1' } })
+
+          expect(result.displayName).toBe('Author: Jo')
+        })
+
+        it('sudo: the virtual key is stripped from the Prisma include even though it bypasses access control', async () => {
+          const vConfig = configWithVirtualDisplayName()
+          relPrisma.author.findMany.mockResolvedValue([{ id: 'a1', name: 'Jo' }])
+
+          const context = await getContext(vConfig, relPrisma, null).sudo()
+          const result = await context.db.author.findMany({
+            include: { displayName: true, posts: true },
+          })
+
+          const call = relPrisma.author.findMany.mock.calls[0][0]
+          expect(call.include).not.toHaveProperty('displayName')
+          // The real relationship is unaffected — sudo still passes it through as-is.
+          expect(call.include.posts).toBe(true)
+          expect(result[0].displayName).toBe('Author: Jo')
+        })
+
+        it('read access control on the virtual field is still enforced (denied field is omitted)', async () => {
+          const vConfig = configWithVirtualDisplayName()
+          vConfig.lists.Author.fields.displayName = virtual({
+            type: 'string',
+            access: { read: () => false },
+            hooks: {
+              resolveOutput: ({ item }) => `Author: ${item.name}`,
+            },
+          })
+          relPrisma.author.findFirst.mockResolvedValue({ id: 'a1', name: 'Jo' })
+
+          const context = await getContext(vConfig, relPrisma, null)
+          const result = await context.db.author.findUnique({
+            where: { id: 'a1' },
+            include: { displayName: true },
+          })
+
+          expect(result).not.toHaveProperty('displayName')
+        })
+      })
     })
 
     it('should delegate create to prisma with access control and hooks', async () => {

package/tests/label.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from 'vitest'
+import { getLabelFieldName, getItemLabel } from '../src/config/label.js'
+import type { ListConfig, TypeInfo } from '../src/config/types.js'
+
+function makeListConfig(
+  fields: ListConfig<TypeInfo>['fields'],
+  labelField?: string,
+): ListConfig<TypeInfo> {
+  return {
+    fields,
+    ui: labelField !== undefined ? { labelField } : undefined,
+  }
+}
+
+describe('label seam', () => {
+  describe('getLabelFieldName', () => {
+    it('uses the configured ui.labelField when it references a scalar field', () => {
+      const listConfig = makeListConfig(
+        { name: { type: 'text' }, email: { type: 'text' } },
+        'email',
+      )
+      expect(getLabelFieldName(listConfig)).toBe('email')
+    })
+
+    it('falls back to "name" when no ui.labelField is configured', () => {
+      const listConfig = makeListConfig({ name: { type: 'text' }, title: { type: 'text' } })
+      expect(getLabelFieldName(listConfig)).toBe('name')
+    })
+
+    it('falls back to "title" when "name" is not declared', () => {
+      const listConfig = makeListConfig({ title: { type: 'text' }, body: { type: 'text' } })
+      expect(getLabelFieldName(listConfig)).toBe('title')
+    })
+
+    it('falls back to "id" when neither "name" nor "title" is declared', () => {
+      const listConfig = makeListConfig({ body: { type: 'text' } })
+      expect(getLabelFieldName(listConfig)).toBe('id')
+    })
+
+    it('throws when ui.labelField references a field not declared on the list', () => {
+      const listConfig = makeListConfig({ name: { type: 'text' } }, 'nickname')
+      expect(() => getLabelFieldName(listConfig)).toThrow(
+        /ui.labelField "nickname" does not reference a field declared on this list/,
+      )
+    })
+
+    it('throws when ui.labelField references a relationship field', () => {
+      const listConfig = makeListConfig(
+        { name: { type: 'text' }, author: { type: 'relationship' } },
+        'author',
+      )
+      expect(() => getLabelFieldName(listConfig)).toThrow(
+        /ui.labelField "author" must reference a scalar field, not a relationship/,
+      )
+    })
+  })
+
+  describe('getItemLabel', () => {
+    it('reads the resolved label field off the row', () => {
+      const listConfig = makeListConfig({ name: { type: 'text' } })
+      expect(getItemLabel(listConfig, { id: '1', name: 'Ada Lovelace' })).toBe('Ada Lovelace')
+    })
+
+    it('falls back to id when the resolved field is missing from the row', () => {
+      const listConfig = makeListConfig({ name: { type: 'text' } })
+      // e.g. stripped by field-level access
+      expect(getItemLabel(listConfig, { id: 'row-1' })).toBe('row-1')
+    })
+
+    it('falls back to id when the resolved field is null on the row', () => {
+      const listConfig = makeListConfig({ name: { type: 'text' } })
+      expect(getItemLabel(listConfig, { id: 'row-2', name: null })).toBe('row-2')
+    })
+
+    it('respects a configured ui.labelField', () => {
+      const listConfig = makeListConfig(
+        { name: { type: 'text' }, email: { type: 'text' } },
+        'email',
+      )
+      expect(getItemLabel(listConfig, { id: '1', name: 'Ada', email: 'ada@example.com' })).toBe(
+        'ada@example.com',
+      )
+    })
+  })
+
+  describe('projection⇄render agreement', () => {
+    const cases: Array<{
+      description: string
+      labelField?: string
+      fields: ListConfig<TypeInfo>['fields']
+      row: Record<string, unknown>
+    }> = [
+      {
+        description: 'configured labelField, field present on row',
+        labelField: 'email',
+        fields: { name: { type: 'text' }, email: { type: 'text' } },
+        row: { id: '1', name: 'Ada', email: 'ada@example.com' },
+      },
+      {
+        description: 'no labelField, name present',
+        fields: { name: { type: 'text' }, title: { type: 'text' } },
+        row: { id: '2', name: 'Alan', title: 'Dr' },
+      },
+      {
+        description: 'no labelField, only title present',
+        fields: { title: { type: 'text' } },
+        row: { id: '3', title: 'Untitled Post' },
+      },
+      {
+        description: 'no labelField, no name/title, falls back to id',
+        fields: { body: { type: 'text' } },
+        row: { id: '4', body: 'hello' },
+      },
+      {
+        description: 'configured labelField, field stripped from row by access control',
+        labelField: 'email',
+        fields: { name: { type: 'text' }, email: { type: 'text' } },
+        row: { id: '5', name: 'Grace' },
+      },
+    ]
+
+    it.each(cases)(
+      'the field getLabelFieldName resolves is the field getItemLabel reads: $description',
+      ({ labelField, fields, row }) => {
+        const listConfig = makeListConfig(fields, labelField)
+        const resolvedFieldName = getLabelFieldName(listConfig)
+        const expectedLabel = Object.prototype.hasOwnProperty.call(row, resolvedFieldName)
+          ? (row[resolvedFieldName] ?? row.id)
+          : row.id
+
+        expect(getItemLabel(listConfig, row)).toBe(String(expectedLabel))
+      },
+    )
+  })
+})