@opensaas/stack-core 0.1.7 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensaas/stack-core",
-  "version": "0.1.7",
+  "version": "0.4.0",
   "description": "Core stack for OpenSaas - schema definition, access control, and runtime utilities",
   "type": "module",
   "main": "./dist/index.js",
@@ -41,19 +41,18 @@
     "url": "https://github.com/OpenSaasAU/stack/issues"
   },
   "peerDependencies": {
-    "@prisma/client": "^6.17.0"
+    "@prisma/client": "^6.17.0 || ^7.0.0"
   },
   "dependencies": {
-    "bcryptjs": "^3.0.2",
-    "zod": "^4.1.12"
+    "bcryptjs": "^3.0.3",
+    "zod": "^4.1.13"
   },
   "devDependencies": {
-    "@prisma/client": "^6.17.1",
-    "@types/bcryptjs": "^3.0.0",
-    "@types/node": "^24.7.2",
-    "@vitest/coverage-v8": "^4.0.4",
+    "@prisma/client": "^7.1.0",
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "^4.0.15",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.0"
+    "vitest": "^4.0.15"
   },
   "scripts": {
     "build": "tsc",

package/src/access/engine.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect } from 'vitest'
+import { filterWritableFields } from './engine.js'
+
+describe('filterWritableFields', () => {
+  it('should filter out foreign key fields when their corresponding relationship field exists', async () => {
+    // Setup: Define field configs with a relationship field
+    const fieldConfigs = {
+      title: {
+        type: 'text',
+      },
+      author: {
+        type: 'relationship',
+        many: false,
+      },
+      tags: {
+        type: 'relationship',
+        many: true, // Many-to-many relationships don't have foreign keys
+      },
+    }
+
+    // Data that includes both the foreign key (authorId) and other fields
+    const data = {
+      title: 'Test Post',
+      authorId: 'user-123', // This should be filtered out
+      tagsId: 'tag-456', // This should NOT be filtered (tags is many:true)
+      author: {
+        connect: { id: 'user-123' },
+      },
+    }
+
+    const filtered = await filterWritableFields(data, fieldConfigs, 'create', {
+      session: null,
+      context: {
+        session: null,
+        _isSudo: true, // Use sudo to bypass access control checks
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any,
+    })
+
+    // authorId should be filtered out
+    expect(filtered).not.toHaveProperty('authorId')
+
+    // title should remain
+    expect(filtered).toHaveProperty('title', 'Test Post')
+
+    // author relationship should remain
+    expect(filtered).toHaveProperty('author')
+    expect(filtered.author).toEqual({ connect: { id: 'user-123' } })
+
+    // tagsId should remain (tags is many:true, so no foreign key is created)
+    expect(filtered).toHaveProperty('tagsId', 'tag-456')
+  })
+
+  it('should filter out system fields', async () => {
+    const fieldConfigs = {
+      title: { type: 'text' },
+    }
+
+    const data = {
+      id: 'post-123',
+      title: 'Test',
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    }
+
+    const filtered = await filterWritableFields(data, fieldConfigs, 'create', {
+      session: null,
+      context: {
+        session: null,
+        _isSudo: true,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any,
+    })
+
+    // System fields should be filtered out
+    expect(filtered).not.toHaveProperty('id')
+    expect(filtered).not.toHaveProperty('createdAt')
+    expect(filtered).not.toHaveProperty('updatedAt')
+
+    // Regular fields should remain
+    expect(filtered).toHaveProperty('title', 'Test')
+  })
+
+  it('should handle update operation', async () => {
+    const fieldConfigs = {
+      title: { type: 'text' },
+      author: {
+        type: 'relationship',
+        many: false,
+      },
+    }
+
+    const data = {
+      title: 'Updated Title',
+      authorId: 'user-456', // Should be filtered out
+      author: {
+        connect: { id: 'user-456' },
+      },
+    }
+
+    const filtered = await filterWritableFields(data, fieldConfigs, 'update', {
+      session: null,
+      item: { id: 'post-123' },
+      context: {
+        session: null,
+        _isSudo: true,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any,
+    })
+
+    expect(filtered).not.toHaveProperty('authorId')
+    expect(filtered).toHaveProperty('title', 'Updated Title')
+    expect(filtered).toHaveProperty('author')
+  })
+
+  it('should not filter fields that happen to end with "Id" but are not foreign keys', async () => {
+    const fieldConfigs = {
+      trackingId: { type: 'text' }, // Regular field that happens to end with "Id"
+      author: {
+        type: 'relationship',
+        many: false,
+      },
+    }
+
+    const data = {
+      trackingId: 'track-123', // Should NOT be filtered (it's a regular field)
+      authorId: 'user-456', // SHOULD be filtered (it's a foreign key)
+    }
+
+    const filtered = await filterWritableFields(data, fieldConfigs, 'create', {
+      session: null,
+      context: {
+        session: null,
+        _isSudo: true,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any,
+    })
+
+    // trackingId is a defined field, so it should remain
+    expect(filtered).toHaveProperty('trackingId', 'track-123')
+
+    // authorId is a foreign key for author relationship, so it should be filtered
+    expect(filtered).not.toHaveProperty('authorId')
+  })
+})

package/src/access/engine.ts

@@ -40,7 +40,8 @@ export function isPrismaFilter(value: unknown): value is PrismaFilter {
 export function getRelatedListConfig(
   relationshipRef: string,
   config: OpenSaasConfig,
-): { listName: string; listConfig: ListConfig } | null {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): { listName: string; listConfig: ListConfig<any> } | null {
   // Parse ref format: "ListName.fieldName"
   const parts = relationshipRef.split('.')
   if (parts.length !== 2) {
@@ -63,7 +64,7 @@ export function getRelatedListConfig(
 export async function checkAccess<T = Record<string, unknown>>(
   accessControl: AccessControl<T> | undefined,
   args: {
-    session: Session
+    session: Session | null
     item?: T
     context: AccessContext
   },
@@ -114,7 +115,7 @@ export async function checkFieldAccess(
   fieldAccess: FieldAccess | undefined,
   operation: 'read' | 'create' | 'update',
   args: {
-    session: Session
+    session: Session | null
     item?: Record<string, unknown>
     context: AccessContext & { _isSudo?: boolean }
   },
@@ -190,7 +191,7 @@ function matchesFilter(item: Record<string, unknown>, filter: Record<string, unk
 export async function buildIncludeWithAccessControl(
   fieldConfigs: Record<string, FieldConfig>,
   args: {
-    session: Session
+    session: Session | null
     context: AccessContext
   },
   config: OpenSaasConfig,
@@ -209,7 +210,7 @@ export async function buildIncludeWithAccessControl(
   for (const [fieldName, fieldConfig] of Object.entries(fieldConfigs)) {
     if (fieldConfig?.type === 'relationship' && 'ref' in fieldConfig && fieldConfig.ref) {
       hasRelationships = true
-      const relatedConfig = getRelatedListConfig(fieldConfig.ref, config)
+      const relatedConfig = getRelatedListConfig(fieldConfig.ref as string, config)
 
       if (relatedConfig) {
         // Check query access for the related list
@@ -261,7 +262,7 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
   item: T,
   fieldConfigs: Record<string, FieldConfig>,
   args: {
-    session: Session
+    session: Session | null
     context: AccessContext & { _isSudo?: boolean }
   },
   config?: OpenSaasConfig,
@@ -271,6 +272,7 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
   const filtered: Record<string, unknown> = {}
   const MAX_DEPTH = 5 // Prevent infinite recursion
 
+  // Process existing fields from the database result
   for (const [fieldName, value] of Object.entries(item)) {
     const fieldConfig = fieldConfigs[fieldName]
 
@@ -302,7 +304,7 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
       value !== undefined &&
       depth < MAX_DEPTH
     ) {
-      const relatedConfig = getRelatedListConfig(fieldConfig.ref, config)
+      const relatedConfig = getRelatedListConfig(fieldConfig.ref as string, config)
 
       if (relatedConfig) {
         // For many relationships (arrays) - recursively filter fields in each item
@@ -357,6 +359,43 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
     }
   }
 
+  // Process virtual fields - compute values from other fields
+  // Virtual fields don't exist in the database result, so we need to compute them separately
+  for (const [fieldName, fieldConfig] of Object.entries(fieldConfigs)) {
+    // Skip if already processed (from database result)
+    if (fieldName in filtered) {
+      continue
+    }
+
+    // Only process virtual fields
+    if (!fieldConfig.virtual) {
+      continue
+    }
+
+    // Check field access
+    const canRead = await checkFieldAccess(fieldConfig.access, 'read', {
+      ...args,
+      item,
+    })
+
+    if (!canRead) {
+      continue
+    }
+
+    // Virtual fields must have resolveOutput hook to compute their value
+    if (fieldConfig.hooks?.resolveOutput && listKey) {
+      const hook = fieldConfig.hooks.resolveOutput as unknown as ResolveOutputHookRuntime
+      filtered[fieldName] = hook({
+        value: undefined, // Virtual fields don't have a database value
+        operation: 'query',
+        fieldName,
+        listKey,
+        item: filtered, // Pass filtered item so virtual field can access other fields
+        context: args.context,
+      })
+    }
+  }
+
   return filtered as Partial<T>
 }
 
@@ -365,16 +404,29 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
  */
 export async function filterWritableFields<T extends Record<string, unknown>>(
   data: T,
-  fieldConfigs: Record<string, { access?: FieldAccess }>,
+  fieldConfigs: Record<string, { access?: FieldAccess; type?: string }>,
   operation: 'create' | 'update',
   args: {
-    session: Session
+    session: Session | null
     item?: Record<string, unknown>
     context: AccessContext & { _isSudo?: boolean }
   },
 ): Promise<Partial<T>> {
   const filtered: Record<string, unknown> = {}
 
+  // Build a set of foreign key field names to exclude
+  // Foreign keys should not be in the data when using Prisma's relation syntax
+  const foreignKeyFields = new Set<string>()
+  for (const [fieldName, fieldConfig] of Object.entries(fieldConfigs)) {
+    if (fieldConfig.type === 'relationship') {
+      // For non-many relationships, Prisma creates a foreign key field named `${fieldName}Id`
+      const relConfig = fieldConfig as { many?: boolean }
+      if (!relConfig.many) {
+        foreignKeyFields.add(`${fieldName}Id`)
+      }
+    }
+  }
+
   for (const [fieldName, value] of Object.entries(data)) {
     const fieldConfig = fieldConfigs[fieldName]
 
@@ -383,6 +435,18 @@ export async function filterWritableFields<T extends Record<string, unknown>>(
       continue
     }
 
+    // Skip virtual fields - they don't store in database
+    // Virtual fields with resolveInput hooks handle side effects separately
+    if (fieldConfig && 'virtual' in fieldConfig && fieldConfig.virtual) {
+      continue
+    }
+
+    // Skip foreign key fields (e.g., authorId) when their corresponding relationship field exists
+    // This prevents conflicts when using Prisma's relation syntax (e.g., author: { connect: { id } })
+    if (foreignKeyFields.has(fieldName)) {
+      continue
+    }
+
     // Check field access (checkFieldAccess already handles sudo mode)
     const canWrite = await checkFieldAccess(fieldConfig?.access, operation, {
       ...args,

package/src/access/types.ts

@@ -1,10 +1,39 @@
 /**
- * Session type - can be extended by users
+ * Session interface - can be augmented by developers to add custom fields
+ *
+ * By default, Session is a permissive object that can contain any properties.
+ * To get type safety and autocomplete, use module augmentation:
+ *
+ * @example
+ * ```typescript
+ * // types/session.d.ts
+ * import '@opensaas/stack-core'
+ *
+ * declare module '@opensaas/stack-core' {
+ *   interface Session {
+ *     userId: string
+ *     email: string
+ *     role: 'admin' | 'user'
+ *   }
+ * }
+ * ```
+ *
+ * After augmentation, session will be fully typed everywhere:
+ * - Access control functions
+ * - Hooks (resolveInput, validateInput, etc.)
+ * - Context object
+ *
+ * @example
+ * ```typescript
+ * // With augmentation, this is fully typed:
+ * const isAdmin: AccessControl = ({ session }) => {
+ *   return session?.role === 'admin'  // ✅ Autocomplete works
+ * }
+ * ```
  */
-export type Session = {
-  userId?: string
+export interface Session {
   [key: string]: unknown
-} | null
+}
 
 /**
  * Generic Prisma model delegate type
@@ -113,14 +142,15 @@ export type StorageUtils = {
 
 /**
  * Context type (simplified for access control)
+ * Using interface instead of type to allow module augmentation
  */
-export type AccessContext<TPrisma extends PrismaClientLike = PrismaClientLike> = {
-  session: Session
+export interface AccessContext<TPrisma extends PrismaClientLike = PrismaClientLike> {
+  session: Session | null
   prisma: TPrisma
   db: AccessControlledDB<TPrisma>
   storage: StorageUtils
+  plugins: Record<string, unknown>
   _isSudo: boolean
-  [key: string]: unknown
 }
 
 /**
@@ -136,7 +166,7 @@ export type PrismaFilter<T = Record<string, unknown>> = Partial<Record<keyof T,
  * - PrismaFilter: Prisma where clause to filter results
  */
 export type AccessControl<T = Record<string, unknown>> = (args: {
-  session: Session
+  session: Session | null
   item?: T // Present for update/delete operations
   context: AccessContext
 }) => boolean | PrismaFilter<T> | Promise<boolean | PrismaFilter<T>>

package/src/config/index.ts

@@ -1,4 +1,4 @@
-import type { OpenSaasConfig, ListConfig, FieldConfig, OperationAccess, Hooks } from './types.js'
+import type { OpenSaasConfig, ListConfig, OperationAccess, Hooks } from './types.js'
 import { executePlugins } from './plugin-engine.js'
 
 /**
@@ -21,40 +21,59 @@ export function config(userConfig: OpenSaasConfig): OpenSaasConfig | Promise<Ope
 /**
  * Helper function to define a list with type safety
  *
- * Accepts raw field configs and transforms them to inject the item type T
- * This enables proper typing in field hooks where item: T
+ * Accepts raw field configs and transforms them to inject the item type
+ * This enables proper typing in field hooks where item is typed correctly
  *
  * @example
  * ```typescript
- * import type { User } from './.opensaas/types'
+ * // Basic usage (before generation)
+ * Post: list({
+ *   fields: { title: text() },
+ *   hooks: {
+ *     resolveInput: async ({ resolvedData }) => {
+ *       // resolvedData: Record<string, unknown>
+ *       return resolvedData
+ *     }
+ *   }
+ * })
+ *
+ * // With TypeInfo (after generation)
+ * import type { Lists } from './.opensaas/lists'
  *
- * User: list<User>({
- *   fields: {
- *     password: password({
- *       hooks: {
- *         resolveInput: async ({ inputValue, item }) => {
- *           // item is typed as User | undefined
- *           // inputValue is typed as string | undefined
- *           return hashPassword(inputValue)
- *         }
+ * Post: list<Lists.Post.TypeInfo>({
+ *   fields: { title: text() },
+ *   hooks: {
+ *     resolveInput: async ({ operation, resolvedData, item }) => {
+ *       if (operation === 'create') {
+ *         // resolvedData: Prisma.PostCreateInput
+ *         // item: undefined
+ *       } else {
+ *         // resolvedData: Prisma.PostUpdateInput
+ *         // item: Post
  *       }
- *     })
+ *       return resolvedData
+ *     }
  *   }
  * })
+ *
+ * // Or as a typed constant
+ * const Post: Lists.Post = list({
+ *   fields: { title: text() },
+ *   hooks: { ... }
+ * })
  * ```
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function list<T = any>(config: {
-  fields: Record<string, FieldConfig>
+export function list<TTypeInfo extends import('./types.js').TypeInfo>(config: {
+  fields: import('./types.js').FieldsWithTypeInfo<TTypeInfo>
   access?: {
-    operation?: OperationAccess<T>
+    operation?: OperationAccess<TTypeInfo['item']>
   }
-  hooks?: Hooks<T>
+  hooks?: Hooks<TTypeInfo['item'], TTypeInfo['inputs']['create'], TTypeInfo['inputs']['update']>
   mcp?: import('./types.js').ListMcpConfig
-}): ListConfig<T> {
+}): ListConfig<TTypeInfo> {
   // At runtime, field configs are unchanged
-  // At type level, they're transformed to inject T as the item type
-  return config as ListConfig<T>
+  // At type level, they're transformed to inject TypeInfo types
+  return config as ListConfig<TTypeInfo>
 }
 
 // Re-export all types
@@ -70,10 +89,13 @@ export type {
   PasswordField,
   SelectField,
   RelationshipField,
+  JsonField,
+  VirtualField,
+  TypeInfo,
   OperationAccess,
   Hooks,
   FieldHooks,
-  FieldsWithItemType,
+  FieldsWithTypeInfo,
   DatabaseConfig,
   SessionConfig,
   UIConfig,

package/src/config/plugin-engine.ts

@@ -168,7 +168,8 @@ export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasCo
   }
 
   // Field type registry (for third-party fields)
-  const fieldTypeRegistry = new Map<string, (options?: unknown) => BaseFieldConfig>()
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Registry must accept any field config builder
+  const fieldTypeRegistry = new Map<string, (options?: unknown) => BaseFieldConfig<any>>()
 
   // MCP tools registry
   const mcpToolsRegistry: McpCustomTool[] = []
@@ -178,7 +179,8 @@ export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasCo
     const context: PluginContext = {
       config: currentConfig,
 
-      addList: (name: string, listConfig: ListConfig) => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Plugin context must accept any list config
+      addList: (name: string, listConfig: ListConfig<any>) => {
         if (currentConfig.lists[name]) {
           throw new Error(
             `Plugin "${plugin.name}" tried to add list "${name}" but it already exists. Use extendList() to modify existing lists.`,
@@ -224,7 +226,8 @@ export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasCo
         }
       },
 
-      registerFieldType: (type: string, builder: (options?: unknown) => BaseFieldConfig) => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Field type registry must accept any field config
+      registerFieldType: (type: string, builder: (options?: unknown) => BaseFieldConfig<any>) => {
         if (fieldTypeRegistry.has(type)) {
           throw new Error(
             `Plugin "${plugin.name}" tried to register field type "${type}" but it's already registered`,
@@ -257,6 +260,13 @@ export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasCo
     currentConfig._pluginData.__mcpTools = mcpToolsRegistry
   }
 
+  // Store plugin instances in config for runtime access
+  // This allows context creation to call plugin.runtime() functions
+  if (!currentConfig._plugins) {
+    currentConfig._plugins = []
+  }
+  currentConfig._plugins = sortedPlugins
+
   return currentConfig
 }