@opensaas/stack-core 0.20.1 → 0.21.0

package/src/internal.ts

@@ -0,0 +1,49 @@
+// ───────────────────────────────────────────────────────────────
+// @opensaas/stack-core/internal
+//
+// @internal — plumbing shared between the @opensaas/* packages and the
+// code emitted by the generator (`.opensaas/`). NOT a public API: these
+// exports carry NO semver guarantees and may change or disappear in any
+// release. Application authors should never import from this path; use
+// the root entry point, `/fields`, or `/extend` instead.
+// ───────────────────────────────────────────────────────────────
+
+// Runtime context internals consumed by generated `.opensaas/` code
+export type { ServerActionProps } from './context/index.js'
+export type {
+  PrismaClientLike,
+  AccessControlledDB,
+  StorageUtils,
+  AugmentedFindMany,
+  AugmentedFindUnique,
+  FindManyQueryArgs,
+} from './access/types.js'
+
+// Typed-query internals (Fragment/FieldSelection appear in generated types)
+export type { Fragment, FieldSelection } from './query/index.js'
+
+// Password hashing internals (the password field emits HashedPassword into generated types)
+export {
+  hashPassword,
+  comparePassword,
+  isHashedPassword,
+  HashedPassword,
+} from './utils/password.js'
+
+// Case conversion helpers used by sibling packages
+export { pascalToCamel, pascalToKebab, kebabToPascal, kebabToCamel } from './lib/case-utils.js'
+
+// Zod schema helpers used internally for validation
+export { validateWithZod, generateZodSchema } from './validation/schema.js'
+
+// Config-shape sub-types consumed by sibling packages (not part of the consumer surface)
+export type {
+  DatabaseConfig,
+  SessionConfig,
+  ThemeConfig,
+  ThemePreset,
+  ThemeColors,
+  FileMetadata,
+  ImageMetadata,
+  ImageTransformationResult,
+} from './config/index.js'

package/src/validation/field-config.test.ts

@@ -0,0 +1,199 @@
+import { describe, it, expect } from 'vitest'
+import { validateFieldConfig, validateConfigFields } from './field-config.js'
+import {
+  text,
+  integer,
+  checkbox,
+  timestamp,
+  password,
+  select,
+  json,
+  relationship,
+  virtual,
+} from '../fields/index.js'
+import type { FieldConfig, OpenSaasConfig } from '../config/types.js'
+
+describe('validateFieldConfig', () => {
+  describe('well-formed fields pass', () => {
+    it.each([
+      ['text', text()],
+      ['integer', integer()],
+      ['checkbox', checkbox()],
+      ['timestamp', timestamp()],
+      ['password', password()],
+      ['select', select({ options: [{ label: 'A', value: 'a' }] })],
+      ['json', json()],
+    ])('a built-in %s field is self-contained', (_name, field) => {
+      expect(validateFieldConfig(field as FieldConfig, 'myField', 'MyList')).toEqual([])
+    })
+
+    it('a relationship field is self-contained via getPrismaRelation', () => {
+      const field = relationship({ ref: 'User.posts' })
+      expect(validateFieldConfig(field as FieldConfig, 'author', 'Post')).toEqual([])
+    })
+
+    it('a virtual field is self-contained without getPrismaType', () => {
+      const field = virtual({
+        type: 'string',
+        hooks: { resolveOutput: () => 'x' },
+      })
+      expect(validateFieldConfig(field as FieldConfig, 'fullName', 'User')).toEqual([])
+    })
+  })
+
+  describe('missing scalar contract methods fail', () => {
+    it('reports a missing getPrismaType naming the list, field, and method', () => {
+      const field = text()
+      delete field.getPrismaType
+
+      const errors = validateFieldConfig(field as FieldConfig, 'title', 'Post')
+
+      expect(errors).toHaveLength(1)
+      expect(errors[0]).toMatchObject({
+        listKey: 'Post',
+        fieldKey: 'title',
+        fieldType: 'text',
+        missingMethod: 'getPrismaType',
+      })
+      expect(errors[0].message).toContain('Post.title')
+      expect(errors[0].message).toContain('getPrismaType')
+      expect(errors[0].message).toContain('not self-contained')
+    })
+
+    it('reports a missing getTypeScriptType naming the method', () => {
+      const field = text()
+      delete field.getTypeScriptType
+
+      const errors = validateFieldConfig(field as FieldConfig, 'title', 'Post')
+
+      expect(errors).toHaveLength(1)
+      expect(errors[0].missingMethod).toBe('getTypeScriptType')
+      expect(errors[0].message).toContain('getTypeScriptType')
+    })
+
+    it('reports a missing getZodSchema naming the method', () => {
+      const field = text()
+      delete field.getZodSchema
+
+      const errors = validateFieldConfig(field as FieldConfig, 'title', 'Post')
+
+      expect(errors).toHaveLength(1)
+      expect(errors[0].missingMethod).toBe('getZodSchema')
+      expect(errors[0].message).toContain('getZodSchema')
+    })
+
+    it('reports every missing method when a field implements none', () => {
+      const field: FieldConfig = { type: 'custom' }
+
+      const errors = validateFieldConfig(field, 'mystery', 'Widget')
+
+      expect(errors.map((e) => e.missingMethod).sort()).toEqual([
+        'getPrismaType',
+        'getTypeScriptType',
+        'getZodSchema',
+      ])
+      for (const error of errors) {
+        expect(error.message).toContain('Widget.mystery')
+        expect(error.message).toContain('custom')
+      }
+    })
+
+    it('works without a listKey (bare field validation)', () => {
+      const field: FieldConfig = { type: 'custom' }
+      const errors = validateFieldConfig(field, 'mystery')
+      expect(errors).toHaveLength(3)
+      expect(errors[0].listKey).toBeUndefined()
+      expect(errors[0].message).toContain('Field "mystery"')
+    })
+  })
+
+  describe('relationship and virtual variants', () => {
+    it('reports a relationship missing getPrismaRelation', () => {
+      const field: FieldConfig = { type: 'relationship' }
+
+      const errors = validateFieldConfig(field, 'author', 'Post')
+
+      expect(errors).toHaveLength(1)
+      expect(errors[0].missingMethod).toBe('getPrismaRelation')
+      expect(errors[0].message).toContain('Post.author')
+    })
+
+    it('reports a virtual field missing getTypeScriptType and getZodSchema', () => {
+      const field: FieldConfig = { type: 'virtual', virtual: true }
+
+      const errors = validateFieldConfig(field, 'fullName', 'User')
+
+      expect(errors.map((e) => e.missingMethod).sort()).toEqual([
+        'getTypeScriptType',
+        'getZodSchema',
+      ])
+    })
+
+    it('does not require getPrismaType for virtual fields', () => {
+      const field: FieldConfig = { type: 'virtual', virtual: true }
+      const errors = validateFieldConfig(field, 'fullName', 'User')
+      expect(errors.some((e) => e.missingMethod === 'getPrismaType')).toBe(false)
+    })
+  })
+})
+
+describe('validateConfigFields', () => {
+  it('returns no errors for a fully compliant config', () => {
+    const config: OpenSaasConfig = {
+      db: {
+        provider: 'sqlite',
+        prismaClientConstructor: () => null as never,
+      },
+      lists: {
+        User: {
+          fields: {
+            name: text({ validation: { isRequired: true } }),
+            posts: relationship({ ref: 'Post.author', many: true }),
+          },
+        },
+        Post: {
+          fields: {
+            title: text(),
+            author: relationship({ ref: 'User.posts' }),
+          },
+        },
+      },
+    }
+
+    expect(validateConfigFields(config)).toEqual([])
+  })
+
+  it('collects per-field errors across every list and names each location', () => {
+    const brokenTitle = text()
+    delete brokenTitle.getPrismaType
+
+    const brokenName = text()
+    delete brokenName.getZodSchema
+
+    const config: OpenSaasConfig = {
+      db: {
+        provider: 'sqlite',
+        prismaClientConstructor: () => null as never,
+      },
+      lists: {
+        User: {
+          fields: {
+            name: brokenName,
+          },
+        },
+        Post: {
+          fields: {
+            title: brokenTitle,
+          },
+        },
+      },
+    }
+
+    const errors = validateConfigFields(config)
+
+    expect(errors).toHaveLength(2)
+    const byField = Object.fromEntries(errors.map((e) => [`${e.listKey}.${e.fieldKey}`, e]))
+    expect(byField['User.name'].missingMethod).toBe('getZodSchema')
+    expect(byField['Post.title'].missingMethod).toBe('getPrismaType')
+  })
+})

package/src/validation/field-config.ts

@@ -0,0 +1,145 @@
+import type { FieldConfig, OpenSaasConfig } from '../config/types.js'
+
+/**
+ * A single self-containment violation found on a field.
+ *
+ * Field builders advertise a self-containment contract: every field provides
+ * the generation hooks the schema/type generators delegate to. When a field
+ * (often a third-party one) fails to implement a required method, the
+ * generators historically threw deep inside generation with an opaque stack
+ * trace. This structured error lets the contract be checked up front and
+ * reported per-field with enough context to act on.
+ */
+export interface FieldConfigValidationError {
+  /** The list the offending field belongs to (`undefined` when validating a bare field). */
+  listKey?: string
+  /** The field key (property name) within the list. */
+  fieldKey: string
+  /** The field's declared `type` discriminator (e.g. `'text'`, `'virtual'`). */
+  fieldType: string
+  /** The contract method that is missing. */
+  missingMethod: 'getPrismaType' | 'getTypeScriptType' | 'getZodSchema' | 'getPrismaRelation'
+  /** A human-readable, ready-to-print message naming the list, field, and method. */
+  message: string
+}
+
+/**
+ * Describe a field for an error message. Falls back to a literal when a
+ * `type`-less value slips through (e.g. a malformed third-party field).
+ */
+function describeFieldType(field: FieldConfig): string {
+  return typeof field.type === 'string' && field.type.length > 0 ? field.type : 'unknown'
+}
+
+/**
+ * Type-safe probe for a function-valued property on a field config.
+ *
+ * The three scalar contract methods live on `BaseFieldConfig` and are checked
+ * directly. `getPrismaRelation` only exists on the relationship field variant,
+ * so it is probed structurally here without widening the public type or
+ * reaching for a cast.
+ */
+function hasFieldMethod(field: FieldConfig, method: string): boolean {
+  const value: unknown = Reflect.get(field, method)
+  return typeof value === 'function'
+}
+
+/**
+ * Build the canonical error message for a missing contract method.
+ */
+function buildMessage(
+  fieldType: string,
+  method: FieldConfigValidationError['missingMethod'],
+  fieldKey: string,
+  listKey?: string,
+): string {
+  const location = listKey ? `Field "${listKey}.${fieldKey}"` : `Field "${fieldKey}"`
+  return (
+    `${location} (type "${fieldType}") is not self-contained: it does not implement ` +
+    `${method}(). Field builders must provide this method so the generator can ` +
+    `produce schema and types without inspecting field internals.`
+  )
+}
+
+/**
+ * Validate a single field against the self-containment contract.
+ *
+ * The contract is conditional on field kind, mirroring exactly where the
+ * generators delegate:
+ *
+ *   - `relationship` fields contribute schema via `getPrismaRelation` and are
+ *     skipped by the scalar Prisma/TypeScript/Zod paths, so only
+ *     `getPrismaRelation` is required.
+ *   - `virtual` fields are not stored in the database, so `getPrismaType` is
+ *     legitimately absent; they must still provide `getTypeScriptType` and
+ *     `getZodSchema`.
+ *   - every other (stored scalar) field must provide `getPrismaType`,
+ *     `getTypeScriptType`, and `getZodSchema`.
+ *
+ * @param field - The field config produced by a field builder.
+ * @param fieldKey - The field's key within its list (for messages).
+ * @param listKey - The owning list's key (optional, for messages).
+ * @returns Zero or more structured errors; empty means the field is compliant.
+ */
+export function validateFieldConfig(
+  field: FieldConfig,
+  fieldKey: string,
+  listKey?: string,
+): FieldConfigValidationError[] {
+  const errors: FieldConfigValidationError[] = []
+  const fieldType = describeFieldType(field)
+
+  const requireMethod = (method: FieldConfigValidationError['missingMethod']): void => {
+    if (!hasFieldMethod(field, method)) {
+      errors.push({
+        listKey,
+        fieldKey,
+        fieldType,
+        missingMethod: method,
+        message: buildMessage(fieldType, method, fieldKey, listKey),
+      })
+    }
+  }
+
+  if (field.type === 'relationship') {
+    // Relationships render through the relationship path only.
+    requireMethod('getPrismaRelation')
+    return errors
+  }
+
+  if (field.virtual === true || field.type === 'virtual') {
+    // Virtual fields are not persisted, so getPrismaType is intentionally absent.
+    requireMethod('getTypeScriptType')
+    requireMethod('getZodSchema')
+    return errors
+  }
+
+  // Stored scalar fields must implement the full generation contract.
+  requireMethod('getPrismaType')
+  requireMethod('getTypeScriptType')
+  requireMethod('getZodSchema')
+
+  return errors
+}
+
+/**
+ * Validate every field across every list in a config.
+ *
+ * Intended to run once, before any generation, so a misimplemented field
+ * surfaces a clear per-field message instead of a deep generator stack trace.
+ *
+ * @param config - The fully resolved OpenSaas config.
+ * @returns All self-containment violations, flattened across lists and fields.
+ */
+export function validateConfigFields(config: OpenSaasConfig): FieldConfigValidationError[] {
+  const errors: FieldConfigValidationError[] = []
+
+  for (const [listKey, listConfig] of Object.entries(config.lists)) {
+    if (!listConfig?.fields) continue
+    for (const [fieldKey, fieldConfig] of Object.entries(listConfig.fields)) {
+      errors.push(...validateFieldConfig(fieldConfig, fieldKey, listKey))
+    }
+  }
+
+  return errors
+}

package/tests/access-relationships.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { filterReadableFields, getRelatedListConfig } from '../src/access/engine.js'
+import { filterReadableFields, getRelatedListConfig } from '../src/access/index.js'
 import type { OpenSaasConfig, AccessContext } from '../src/index.js'
 
 describe('Relationship Access Control', () => {
@@ -153,7 +153,7 @@ describe('Relationship Access Control', () => {
         }
 
         // Test that buildIncludeWithAccessControl excludes the denied relationship
-        const { buildIncludeWithAccessControl } = await import('../src/access/engine.js')
+        const { buildIncludeWithAccessControl } = await import('../src/access/index.js')
 
         const include = await buildIncludeWithAccessControl(
           config.lists.Post.fields,
@@ -319,7 +319,7 @@ describe('Relationship Access Control', () => {
         }
 
         // Test that buildIncludeWithAccessControl creates the right where clause
-        const { buildIncludeWithAccessControl } = await import('../src/access/engine.js')
+        const { buildIncludeWithAccessControl } = await import('../src/access/index.js')
 
         const include = await buildIncludeWithAccessControl(
           config.lists.User.fields,
@@ -486,7 +486,7 @@ describe('Relationship Access Control', () => {
         }
 
         // Test that buildIncludeWithAccessControl creates session-based where clause
-        const { buildIncludeWithAccessControl } = await import('../src/access/engine.js')
+        const { buildIncludeWithAccessControl } = await import('../src/access/index.js')
 
         const include = await buildIncludeWithAccessControl(
           config.lists.User.fields,

package/tests/access.test.ts

@@ -7,7 +7,7 @@ import {
   filterWritableFields,
   isBoolean,
   isPrismaFilter,
-} from '../src/access/engine.js'
+} from '../src/access/index.js'
 import type { AccessControl, FieldAccess, AccessContext } from '../src/access/types.js'
 
 describe('Access Control', () => {