@opensaas/stack-core 0.26.0 → 0.27.1

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))
+      },
+    )
+  })
+})