@opensaas/stack-core 0.6.1 → 0.7.0

package/src/fields/index.ts

@@ -539,6 +539,58 @@ export function json<
   }
 }
 
+/**
+ * Convert a TypeDescriptor to a TypeScript type string
+ * Handles three formats:
+ * 1. Primitive string: 'string', 'number', 'boolean' -> returned as-is
+ * 2. Import string: "import('decimal.js').Decimal" -> returned as-is
+ * 3. Type object: { value: Decimal, from: 'decimal.js' } -> "import('decimal.js').Decimal"
+ */
+function typeDescriptorToString(descriptor: import('../config/types.js').TypeDescriptor): string {
+  if (typeof descriptor === 'string') {
+    return descriptor
+  }
+
+  // Extract type name from constructor or use provided name
+  const typeName = descriptor.name || descriptor.value.name
+
+  // Generate import string
+  return `import('${descriptor.from}').${typeName}`
+}
+
+/**
+ * Extract TypeScript imports from a TypeDescriptor
+ * Returns array of import statements needed for type generation
+ */
+function typeDescriptorToImports(
+  descriptor: import('../config/types.js').TypeDescriptor,
+): Array<{ names: string[]; from: string; typeOnly?: boolean }> {
+  // If it's a string, check if it's an import string
+  if (typeof descriptor === 'string') {
+    const importMatch = descriptor.match(/import\('([^']+)'\)\.(\w+)/)
+    if (importMatch) {
+      return [
+        {
+          names: [importMatch[2]],
+          from: importMatch[1],
+          typeOnly: true,
+        },
+      ]
+    }
+    return []
+  }
+
+  // Type object descriptor
+  const typeName = descriptor.name || descriptor.value.name
+  return [
+    {
+      names: [typeName],
+      from: descriptor.from,
+      typeOnly: true,
+    },
+  ]
+}
+
 /**
  * Virtual field - not stored in database, computed via hooks
  *
@@ -548,10 +600,11 @@ export function json<
  * - Optionally uses resolveInput hook for write side effects (e.g., sync to external API)
  * - Only computed when explicitly selected/included in queries
  * - Supports both read and write operations via hooks
+ * - Supports custom scalar types (e.g., Decimal) for financial precision
  *
- * **Usage Example:**
+ * **Usage Examples:**
  * ```typescript
- * // Read-only computed field
+ * // Read-only computed field with primitive type
  * fields: {
  *   firstName: text(),
  *   lastName: text(),
@@ -563,6 +616,28 @@ export function json<
  *   })
  * }
  *
+ * // Custom scalar type using import string
+ * fields: {
+ *   totalPrice: virtual({
+ *     type: "import('decimal.js').Decimal",
+ *     hooks: {
+ *       resolveOutput: ({ item }) => new Decimal(item.price).times(item.quantity)
+ *     }
+ *   })
+ * }
+ *
+ * // Custom scalar type using type descriptor (recommended)
+ * import Decimal from 'decimal.js'
+ *
+ * fields: {
+ *   totalPrice: virtual({
+ *     type: { value: Decimal, from: 'decimal.js' },
+ *     hooks: {
+ *       resolveOutput: ({ item }) => new Decimal(item.price).times(item.quantity)
+ *     }
+ *   })
+ * }
+ *
  * // Write side effects (e.g., sync to external API)
  * fields: {
  *   externalSync: virtual({
@@ -576,16 +651,10 @@ export function json<
  *     }
  *   })
  * }
- *
- * // Query with select
- * const user = await context.db.user.findUnique({
- *   where: { id },
- *   select: { firstName: true, lastName: true, fullName: true } // fullName computed
- * })
  * ```
  *
  * **Requirements:**
- * - Must provide `type` (TypeScript type string)
+ * - Must provide `type` (TypeScript type string, import string, or type descriptor)
  * - Must provide `resolveOutput` hook (for reads)
  * - Optional `resolveInput` hook (for write side effects)
  *
@@ -593,7 +662,9 @@ export function json<
  * @returns Virtual field configuration
  */
 export function virtual<TTypeInfo extends import('../config/types.js').TypeInfo>(
-  options: Omit<VirtualField<TTypeInfo>, 'virtual' | 'outputType' | 'type'> & { type: string },
+  options: Omit<VirtualField<TTypeInfo>, 'virtual' | 'outputType' | 'type'> & {
+    type: import('../config/types.js').TypeDescriptor
+  },
 ): VirtualField<TTypeInfo> {
   // Validate that resolveOutput is provided
   if (!options.hooks?.resolveOutput) {
@@ -603,7 +674,11 @@ export function virtual<TTypeInfo extends import('../config/types.js').TypeInfo>
     )
   }
 
-  const { type: outputType, ...rest } = options
+  // Convert type descriptor to string
+  const outputType = typeDescriptorToString(options.type)
+  const imports = typeDescriptorToImports(options.type)
+
+  const { type: _, ...rest } = options
 
   return {
     type: 'virtual',
@@ -616,10 +691,12 @@ export function virtual<TTypeInfo extends import('../config/types.js').TypeInfo>
     // Virtual fields appear in output types with their specified type
     getTypeScriptType: () => {
       return {
-        type: options.type,
+        type: outputType,
         optional: false, // Virtual fields always compute a value
       }
     },
+    // Add import statements if needed
+    getTypeScriptImports: imports.length > 0 ? () => imports : undefined,
     // Virtual fields never validate input (they don't accept database input)
     getZodSchema: () => {
       return z.never()

package/src/index.ts

@@ -14,6 +14,7 @@ export type {
   RelationshipField,
   JsonField,
   VirtualField,
+  TypeDescriptor,
   TypeInfo,
   OperationAccess,
   Hooks,

package/tests/virtual-fields.test.ts

@@ -0,0 +1,421 @@
+import { describe, test, expect } from 'vitest'
+import { virtual } from '../src/fields/index.js'
+
+// Mock Decimal class for testing
+class Decimal {
+  value: number
+
+  constructor(value: number | string) {
+    this.value = typeof value === 'string' ? parseFloat(value) : value
+  }
+
+  times(other: Decimal | number): Decimal {
+    const otherValue = other instanceof Decimal ? other.value : other
+    return new Decimal(this.value * otherValue)
+  }
+
+  plus(other: Decimal | number): Decimal {
+    const otherValue = other instanceof Decimal ? other.value : other
+    return new Decimal(this.value + otherValue)
+  }
+
+  toString(): string {
+    return this.value.toString()
+  }
+
+  static get name() {
+    return 'Decimal'
+  }
+}
+
+// Mock custom class for testing
+class CustomType {
+  data: string
+
+  constructor(data: string) {
+    this.data = data
+  }
+
+  static get name() {
+    return 'CustomType'
+  }
+}
+
+describe('Virtual Fields with TypeDescriptor', () => {
+  describe('primitive type strings', () => {
+    test('accepts string type', () => {
+      const field = virtual({
+        type: 'string',
+        hooks: {
+          resolveOutput: ({ item }) => `${item.firstName} ${item.lastName}`,
+        },
+      })
+
+      expect(field.type).toBe('virtual')
+      expect(field.virtual).toBe(true)
+      expect(field.outputType).toBe('string')
+    })
+
+    test('accepts number type', () => {
+      const field = virtual({
+        type: 'number',
+        hooks: {
+          resolveOutput: ({ item }) => item.count * 2,
+        },
+      })
+
+      expect(field.outputType).toBe('number')
+    })
+
+    test('accepts boolean type', () => {
+      const field = virtual({
+        type: 'boolean',
+        hooks: {
+          resolveOutput: ({ item }) => item.isActive,
+        },
+      })
+
+      expect(field.outputType).toBe('boolean')
+    })
+
+    test('accepts Date type', () => {
+      const field = virtual({
+        type: 'Date',
+        hooks: {
+          resolveOutput: ({ item }) => new Date(item.createdAt),
+        },
+      })
+
+      expect(field.outputType).toBe('Date')
+    })
+
+    test('accepts array types', () => {
+      const field = virtual({
+        type: 'string[]',
+        hooks: {
+          resolveOutput: ({ item }) => item.tags.split(','),
+        },
+      })
+
+      expect(field.outputType).toBe('string[]')
+    })
+  })
+
+  describe('import string types', () => {
+    test('accepts import string format', () => {
+      const field = virtual({
+        type: "import('decimal.js').Decimal",
+        hooks: {
+          resolveOutput: ({ item }) => new Decimal(item.price),
+        },
+      })
+
+      expect(field.outputType).toBe("import('decimal.js').Decimal")
+    })
+
+    test('generates TypeScript imports from import string', () => {
+      const field = virtual({
+        type: "import('decimal.js').Decimal",
+        hooks: {
+          resolveOutput: ({ item }) => new Decimal(item.price),
+        },
+      })
+
+      expect(field.getTypeScriptImports).toBeDefined()
+      const imports = field.getTypeScriptImports!()
+      expect(imports).toHaveLength(1)
+      expect(imports[0]).toEqual({
+        names: ['Decimal'],
+        from: 'decimal.js',
+        typeOnly: true,
+      })
+    })
+
+    test('handles complex import paths', () => {
+      const field = virtual({
+        type: "import('@myorg/custom-types').MyCustomType",
+        hooks: {
+          resolveOutput: ({ item }) => item.customData,
+        },
+      })
+
+      expect(field.outputType).toBe("import('@myorg/custom-types').MyCustomType")
+      const imports = field.getTypeScriptImports!()
+      expect(imports[0]).toEqual({
+        names: ['MyCustomType'],
+        from: '@myorg/custom-types',
+        typeOnly: true,
+      })
+    })
+  })
+
+  describe('type descriptor objects', () => {
+    test('accepts type descriptor with class constructor', () => {
+      const field = virtual({
+        type: { value: Decimal, from: 'decimal.js' },
+        hooks: {
+          resolveOutput: ({ item }) => new Decimal(item.price).times(item.quantity),
+        },
+      })
+
+      expect(field.outputType).toBe("import('decimal.js').Decimal")
+    })
+
+    test('generates TypeScript imports from type descriptor', () => {
+      const field = virtual({
+        type: { value: Decimal, from: 'decimal.js' },
+        hooks: {
+          resolveOutput: ({ item }) => new Decimal(item.price),
+        },
+      })
+
+      expect(field.getTypeScriptImports).toBeDefined()
+      const imports = field.getTypeScriptImports!()
+      expect(imports).toHaveLength(1)
+      expect(imports[0]).toEqual({
+        names: ['Decimal'],
+        from: 'decimal.js',
+        typeOnly: true,
+      })
+    })
+
+    test('uses custom name when provided', () => {
+      const field = virtual({
+        type: { value: Decimal, from: 'decimal.js', name: 'CustomDecimal' },
+        hooks: {
+          resolveOutput: ({ item }) => new Decimal(item.value),
+        },
+      })
+
+      expect(field.outputType).toBe("import('decimal.js').CustomDecimal")
+      const imports = field.getTypeScriptImports!()
+      expect(imports[0]).toEqual({
+        names: ['CustomDecimal'],
+        from: 'decimal.js',
+        typeOnly: true,
+      })
+    })
+
+    test('works with custom classes', () => {
+      const field = virtual({
+        type: { value: CustomType, from: './types' },
+        hooks: {
+          resolveOutput: ({ item }) => new CustomType(item.data),
+        },
+      })
+
+      expect(field.outputType).toBe("import('./types').CustomType")
+      const imports = field.getTypeScriptImports!()
+      expect(imports[0]).toEqual({
+        names: ['CustomType'],
+        from: './types',
+        typeOnly: true,
+      })
+    })
+  })
+
+  describe('getTypeScriptType', () => {
+    test('returns correct type for primitive string', () => {
+      const field = virtual({
+        type: 'string',
+        hooks: {
+          resolveOutput: ({ item }) => item.name,
+        },
+      })
+
+      const tsType = field.getTypeScriptType!()
+      expect(tsType.type).toBe('string')
+      expect(tsType.optional).toBe(false)
+    })
+
+    test('returns correct type for import string', () => {
+      const field = virtual({
+        type: "import('decimal.js').Decimal",
+        hooks: {
+          resolveOutput: ({ item }) => new Decimal(item.value),
+        },
+      })
+
+      const tsType = field.getTypeScriptType!()
+      expect(tsType.type).toBe("import('decimal.js').Decimal")
+      expect(tsType.optional).toBe(false)
+    })
+
+    test('returns correct type for type descriptor', () => {
+      const field = virtual({
+        type: { value: Decimal, from: 'decimal.js' },
+        hooks: {
+          resolveOutput: ({ item }) => new Decimal(item.value),
+        },
+      })
+
+      const tsType = field.getTypeScriptType!()
+      expect(tsType.type).toBe("import('decimal.js').Decimal")
+      expect(tsType.optional).toBe(false)
+    })
+
+    test('virtual fields are never optional', () => {
+      const field = virtual({
+        type: 'string',
+        hooks: {
+          resolveOutput: ({ item }) => item.value || 'default',
+        },
+      })
+
+      const tsType = field.getTypeScriptType!()
+      expect(tsType.optional).toBe(false)
+    })
+  })
+
+  describe('validation', () => {
+    test('throws error when resolveOutput hook is missing', () => {
+      expect(() => {
+        virtual({
+          type: 'string',
+          // @ts-expect-error - Testing missing hook
+          hooks: {},
+        })
+      }).toThrow('Virtual fields must provide a resolveOutput hook')
+    })
+
+    test('throws error when hooks are completely missing', () => {
+      expect(() => {
+        // @ts-expect-error - Testing missing hooks
+        virtual({
+          type: 'string',
+        })
+      }).toThrow('Virtual fields must provide a resolveOutput hook')
+    })
+  })
+
+  describe('getPrismaType', () => {
+    test('returns undefined to skip database column creation', () => {
+      const field = virtual({
+        type: 'string',
+        hooks: {
+          resolveOutput: ({ item }) => item.computed,
+        },
+      })
+
+      expect(field.getPrismaType).toBeUndefined()
+    })
+  })
+
+  describe('getZodSchema', () => {
+    test('returns z.never() to prevent input validation', () => {
+      const field = virtual({
+        type: 'string',
+        hooks: {
+          resolveOutput: ({ item }) => item.computed,
+        },
+      })
+
+      const schema = field.getZodSchema!()
+      expect(() => schema.parse('anything')).toThrow()
+    })
+  })
+
+  describe('real-world use cases', () => {
+    test('Decimal type for financial calculations', () => {
+      const field = virtual({
+        type: { value: Decimal, from: 'decimal.js' },
+        hooks: {
+          resolveOutput: ({ item }) => {
+            // Calculate total from price and quantity with decimal precision
+            return new Decimal(item.price).times(item.quantity)
+          },
+        },
+      })
+
+      expect(field.type).toBe('virtual')
+      expect(field.outputType).toBe("import('decimal.js').Decimal")
+
+      const imports = field.getTypeScriptImports!()
+      expect(imports).toEqual([
+        {
+          names: ['Decimal'],
+          from: 'decimal.js',
+          typeOnly: true,
+        },
+      ])
+    })
+
+    test('Complex computed field with multiple operations', () => {
+      const field = virtual({
+        type: { value: Decimal, from: 'decimal.js' },
+        hooks: {
+          resolveOutput: ({ item }) => {
+            // Calculate tax amount
+            const subtotal = new Decimal(item.subtotal)
+            const taxRate = new Decimal(item.taxRate)
+            return subtotal.times(taxRate)
+          },
+        },
+      })
+
+      expect(field.outputType).toBe("import('decimal.js').Decimal")
+    })
+
+    test('Full name concatenation (primitive type)', () => {
+      const field = virtual({
+        type: 'string',
+        hooks: {
+          resolveOutput: ({ item }) => `${item.firstName} ${item.lastName}`,
+        },
+      })
+
+      expect(field.outputType).toBe('string')
+      expect(field.getTypeScriptImports).toBeUndefined()
+    })
+
+    test('Array transformation', () => {
+      const field = virtual({
+        type: 'string[]',
+        hooks: {
+          resolveOutput: ({ item }) => {
+            // Split comma-separated tags into array
+            return item.tags ? item.tags.split(',').map((t: string) => t.trim()) : []
+          },
+        },
+      })
+
+      expect(field.outputType).toBe('string[]')
+    })
+  })
+
+  describe('backwards compatibility', () => {
+    test('existing primitive type strings still work', () => {
+      const field = virtual({
+        type: 'string',
+        hooks: {
+          resolveOutput: ({ item }) => item.value,
+        },
+      })
+
+      expect(field.type).toBe('virtual')
+      expect(field.outputType).toBe('string')
+      expect(field.getTypeScriptImports).toBeUndefined()
+    })
+
+    test('existing field configuration is preserved', () => {
+      const field = virtual({
+        type: 'number',
+        hooks: {
+          resolveOutput: ({ item }) => item.count,
+          resolveInput: async ({ inputValue }) => inputValue,
+        },
+        access: {
+          read: () => true,
+        },
+        ui: {
+          displayMode: 'readonly',
+        },
+      })
+
+      expect(field.hooks?.resolveOutput).toBeDefined()
+      expect(field.hooks?.resolveInput).toBeDefined()
+      expect(field.access).toBeDefined()
+      expect(field.ui).toBeDefined()
+    })
+  })
+})