sovrium 0.0.2

package/src/domain/models/app/table/field-types/text/url-field.ts

@@ -0,0 +1,81 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Schema } from 'effect'
+import { BaseFieldSchema } from '../base-field'
+
+/**
+ * URL Field
+ *
+ * Text field with URL format validation. Stores web addresses (URLs) and validates
+ * them against standard URL format rules. Supports http://, https://, and other
+ * protocols. Can be marked as required, unique, or indexed. URL validation ensures
+ * data integrity and prevents malformed URLs from being stored. URLs are stored
+ * as plain text strings and can be used for links, API endpoints, and web resources.
+ *
+ * Business Rules:
+ * - URL format validation enforced at application level (protocol + domain + optional path)
+ * - Supports multiple protocols: http://, https://, ftp://, etc.
+ * - Unique constraint optional - useful for preventing duplicate resource links
+ * - Indexing recommended for search and lookup operations on URL fields
+ * - Constant value 'url' ensures type safety and enables discriminated unions
+ *
+ * @example
+ * ```typescript
+ * const field = {
+ *   id: 1,
+ *   name: 'website',
+ *   type: 'url',
+ *   required: true,
+ *   unique: false,
+ *   indexed: true,
+ *   default: 'https://example.com'
+ * }
+ * ```
+ */
+export const UrlFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('url').pipe(
+        Schema.annotations({
+          description: "Constant value 'url' for type discrimination in discriminated unions",
+        })
+      ),
+      default: Schema.optional(
+        Schema.String.pipe(
+          Schema.annotations({
+            description: 'Default URL value when creating new records',
+          })
+        )
+      ),
+    })
+  ),
+  Schema.annotations({
+    title: 'URL Field',
+    description:
+      'Text field with URL format validation. Validates web addresses and supports multiple protocols (http://, https://, ftp://, etc.).',
+    examples: [
+      {
+        id: 1,
+        name: 'website',
+        type: 'url',
+        required: true,
+        unique: false,
+        indexed: true,
+      },
+      {
+        id: 2,
+        name: 'profile_url',
+        type: 'url',
+        required: false,
+        default: 'https://example.com/profile',
+      },
+    ],
+  })
+)
+
+export type UrlField = Schema.Schema.Type<typeof UrlFieldSchema>

package/src/domain/models/app/table/field-types/user/created-by-field.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Schema } from 'effect'
+import { BaseFieldSchema } from '../base-field'
+
+/**
+ * Created By Field
+ *
+ * Automatically captures the user who created a record.
+ * This field is system-managed and cannot be manually edited.
+ * Stores a reference to the user ID from the authentication system.
+ * Commonly used for audit trails and user activity tracking.
+ *
+ * @example
+ * ```typescript
+ * const field = {
+ *   id: 1,
+ *   name: 'created_by',
+ *   type: 'created-by',
+ *   indexed: true
+ * }
+ * ```
+ */
+export const CreatedByFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('created-by'),
+    })
+  ),
+  Schema.annotations({
+    title: 'Created By Field',
+    description:
+      'Automatically captures the user who created a record. System-managed field that stores user ID reference.',
+    examples: [
+      {
+        id: 1,
+        name: 'created_by',
+        type: 'created-by',
+        indexed: true,
+      },
+    ],
+  })
+)
+
+export type CreatedByField = Schema.Schema.Type<typeof CreatedByFieldSchema>

package/src/domain/models/app/table/field-types/user/deleted-by-field.ts

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Schema } from 'effect'
+import { BaseFieldSchema } from '../base-field'
+
+/**
+ * Deleted By Field
+ *
+ * Automatically captures the user who soft-deleted a record.
+ * This field is system-managed and cannot be manually edited.
+ * Stores a reference to the user ID from the authentication system.
+ * Only populated when a record is soft-deleted (when deleted_at is set).
+ * NULL indicates the record has not been deleted or was deleted by a system process.
+ *
+ * Commonly used for:
+ * - Audit trails (who deleted what)
+ * - Compliance reporting
+ * - Accountability tracking
+ * - Deletion history
+ *
+ * @example
+ * ```typescript
+ * const field = {
+ *   id: 1,
+ *   name: 'deleted_by',
+ *   type: 'deleted-by',
+ *   indexed: true
+ * }
+ * ```
+ */
+export const DeletedByFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('deleted-by'),
+    })
+  ),
+  Schema.annotations({
+    title: 'Deleted By Field',
+    description:
+      'Automatically captures the user who soft-deleted a record. System-managed field that stores user ID reference. NULL when record is active or deleted by system process.',
+    examples: [
+      {
+        id: 1,
+        name: 'deleted_by',
+        type: 'deleted-by',
+        indexed: true,
+      },
+    ],
+  })
+)
+
+export type DeletedByField = Schema.Schema.Type<typeof DeletedByFieldSchema>

package/src/domain/models/app/table/field-types/user/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+export * from './user-field'
+export * from './created-by-field'
+export * from './updated-by-field'
+export * from './deleted-by-field'

package/src/domain/models/app/table/field-types/user/updated-by-field.ts

@@ -0,0 +1,51 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Schema } from 'effect'
+import { BaseFieldSchema } from '../base-field'
+
+/**
+ * Updated By Field
+ *
+ * Automatically captures the user who last modified a record.
+ * This field is system-managed and cannot be manually edited.
+ * Stores a reference to the user ID from the authentication system.
+ * Automatically updates on every record update operation.
+ * Commonly used for audit trails and tracking modification history.
+ *
+ * @example
+ * ```typescript
+ * const field = {
+ *   id: 1,
+ *   name: 'updated_by',
+ *   type: 'updated-by',
+ *   indexed: true
+ * }
+ * ```
+ */
+export const UpdatedByFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('updated-by'),
+    })
+  ),
+  Schema.annotations({
+    title: 'Updated By Field',
+    description:
+      'Automatically captures the user who last modified a record. System-managed field that stores user ID reference.',
+    examples: [
+      {
+        id: 1,
+        name: 'updated_by',
+        type: 'updated-by',
+        indexed: true,
+      },
+    ],
+  })
+)
+
+export type UpdatedByField = Schema.Schema.Type<typeof UpdatedByFieldSchema>

package/src/domain/models/app/table/field-types/user/user-field.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Schema } from 'effect'
+import { BaseFieldSchema } from '../base-field'
+
+/**
+ * User Field
+ *
+ * Reference field that links to users from the authentication system.
+ * Stores user IDs and can be used for assignments, ownership, or collaboration.
+ * Supports single or multiple user selection via allowMultiple flag.
+ *
+ * @example
+ * ```typescript
+ * const field = {
+ *   id: 1,
+ *   name: 'assigned_to',
+ *   type: 'user',
+ *   required: true,
+ *   allowMultiple: false
+ * }
+ * ```
+ */
+export const UserFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('user'),
+      allowMultiple: Schema.optional(Schema.Boolean),
+    })
+  ),
+  Schema.annotations({
+    title: 'User Field',
+    description:
+      'Reference field linking to users from authentication system. Supports single or multiple user selection.',
+    examples: [
+      {
+        id: 1,
+        name: 'assigned_to',
+        type: 'user',
+        required: true,
+        allowMultiple: false,
+      },
+    ],
+  })
+)
+
+export type UserField = Schema.Schema.Type<typeof UserFieldSchema>

package/src/domain/models/app/table/field-types/validation-utils.ts

@@ -0,0 +1,166 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Schema } from 'effect'
+
+/**
+ * Validates that min is less than or equal to max when both are specified.
+ *
+ * This validation is used by numeric field types (integer, decimal, currency, percentage)
+ * to ensure that range constraints are logically valid. Returns an error message if
+ * validation fails, or undefined if validation passes.
+ *
+ * @param field - Object containing optional min and max properties
+ * @returns Error message if min > max, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * validateMinMaxRange({ min: 0, max: 100 })  // undefined (valid)
+ * validateMinMaxRange({ min: 100, max: 10 }) // 'min cannot be greater than max'
+ * validateMinMaxRange({ min: 0 })            // undefined (only min specified)
+ * validateMinMaxRange({ max: 100 })          // undefined (only max specified)
+ * ```
+ */
+export const validateMinMaxRange = (field: {
+  readonly min?: number
+  readonly max?: number
+}): string | undefined => {
+  if (field.min !== undefined && field.max !== undefined && field.min > field.max) {
+    return 'min cannot be greater than max'
+  }
+  return undefined
+}
+
+/**
+ * Creates a reusable options array schema for select-type fields.
+ *
+ * This schema factory is used by single-select and multi-select field types
+ * to ensure consistent validation of options arrays. All select fields require
+ * at least one option to be meaningful, and option values must be unique.
+ *
+ * @param fieldType - The type of select field (for error messages)
+ * @returns Effect Schema for validating options arrays
+ *
+ * @example
+ * ```typescript
+ * // Used in single-select field
+ * const optionsSchema = createOptionsSchema('single-select')
+ * // Used in multi-select field
+ * const optionsSchema = createOptionsSchema('multi-select')
+ * ```
+ */
+export const createOptionsSchema = (fieldType: 'single-select' | 'multi-select') =>
+  Schema.Array(Schema.String).pipe(
+    Schema.minItems(1),
+    Schema.annotations({
+      message: () => `At least one option is required for ${fieldType} field`,
+    }),
+    Schema.filter((options) => {
+      const uniqueOptions = new Set(options)
+      return (
+        options.length === uniqueOptions.size || 'Options must be unique (duplicate option found)'
+      )
+    })
+  )
+
+/**
+ * Creates a reusable options array schema for status-type fields with complex option objects.
+ *
+ * This schema factory is used by status field type to ensure consistent validation
+ * of options arrays containing objects with value and optional color properties.
+ * Status fields require at least one option, and option values must be unique.
+ *
+ * @returns Effect Schema for validating status field options arrays
+ *
+ * @example
+ * ```typescript
+ * // Used in status field
+ * const optionsSchema = createStatusOptionsSchema()
+ * // Validates: [{ value: 'Draft', color: '#6B7280' }, { value: 'Published' }]
+ * ```
+ */
+export const createStatusOptionsSchema = () =>
+  Schema.Array(
+    Schema.Struct({
+      value: Schema.String.pipe(Schema.nonEmptyString({ message: () => 'value is required' })),
+      color: Schema.optional(
+        Schema.String.pipe(
+          Schema.pattern(/^#[0-9a-fA-F]{6}$/, {
+            message: () => 'Invalid color format - color must be a hex code (e.g., #3B82F6)',
+          }),
+          Schema.annotations({
+            description: 'Hex color code for the status',
+          })
+        )
+      ),
+    })
+  ).pipe(
+    Schema.minItems(1, { message: () => 'at least one option required' }),
+    Schema.filter((options) => {
+      const values = options.map((opt) => opt.value)
+      const uniqueValues = new Set(values)
+      return (
+        values.length === uniqueValues.size || 'Options must be unique (duplicate option found)'
+      )
+    })
+  )
+
+/**
+ * Validates that button fields have required properties based on their action type.
+ *
+ * This validation is used by button field types to ensure that action-specific
+ * properties are provided when needed. For example, buttons with action='url'
+ * must have a url property, and buttons with action='automation' must have an
+ * automation property.
+ *
+ * @param field - Object containing action and optional url/automation properties
+ * @returns Error message if validation fails, true if validation passes
+ *
+ * @example
+ * ```typescript
+ * validateButtonAction({ action: 'url', url: 'https://example.com' })  // true (valid)
+ * validateButtonAction({ action: 'url' })                              // 'url is required when action is url'
+ * validateButtonAction({ action: 'automation', automation: 'approve' }) // true (valid)
+ * validateButtonAction({ action: 'automation' })                       // 'automation is required when action is automation'
+ * validateButtonAction({ action: 'custom' })                           // true (no requirements)
+ * ```
+ */
+export const validateButtonAction = (field: {
+  readonly action: string
+  readonly url?: string
+  readonly automation?: string
+}): string | true => {
+  if (field.action === 'url' && !field.url) {
+    return 'url is required when action is url'
+  }
+  if (field.action === 'automation' && !field.automation) {
+    return 'automation is required when action is automation'
+  }
+  return true
+}
+
+/**
+ * Finds the first duplicate value in an array.
+ *
+ * This utility function is used for detecting duplicate IDs, field names, or other
+ * values that must be unique within a collection. Uses an efficient O(n) algorithm
+ * with indexOf to find the first duplicate.
+ *
+ * @param values - Array of values to check for duplicates
+ * @returns The first duplicate value found, or undefined if no duplicates exist
+ *
+ * @example
+ * ```typescript
+ * findDuplicate(['a', 'b', 'c'])        // undefined (no duplicates)
+ * findDuplicate(['a', 'b', 'a', 'c'])   // 'a' (first duplicate)
+ * findDuplicate([1, 2, 3, 2])           // 2 (works with numbers)
+ * findDuplicate(['x'])                  // undefined (single item)
+ * ```
+ */
+export const findDuplicate = <T>(values: ReadonlyArray<T>): T | undefined => {
+  return values.find((value, index) => values.indexOf(value) !== index)
+}

package/src/domain/models/app/table/fields.ts

@@ -0,0 +1,216 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Schema } from 'effect'
+import {
+  ArrayFieldSchema,
+  AutonumberFieldSchema,
+  BarcodeFieldSchema,
+  ButtonFieldSchema,
+  CheckboxFieldSchema,
+  ColorFieldSchema,
+  CountFieldSchema,
+  CreatedAtFieldSchema,
+  CreatedByFieldSchema,
+  CurrencyFieldSchema,
+  DateFieldSchema,
+  DecimalFieldSchema,
+  DeletedAtFieldSchema,
+  DeletedByFieldSchema,
+  DurationFieldSchema,
+  EmailFieldSchema,
+  FormulaFieldSchema,
+  GeolocationFieldSchema,
+  IntegerFieldSchema,
+  JsonFieldSchema,
+  LongTextFieldSchema,
+  LookupFieldSchema,
+  MultiSelectFieldSchema,
+  MultipleAttachmentsFieldSchema,
+  PercentageFieldSchema,
+  PhoneNumberFieldSchema,
+  ProgressFieldSchema,
+  RatingFieldSchema,
+  RelationshipFieldSchema,
+  RichTextFieldSchema,
+  RollupFieldSchema,
+  SingleAttachmentFieldSchema,
+  SingleLineTextFieldSchema,
+  SingleSelectFieldSchema,
+  StatusFieldSchema,
+  UnknownFieldSchema,
+  UpdatedAtFieldSchema,
+  UpdatedByFieldSchema,
+  UrlFieldSchema,
+  UserFieldSchema,
+} from './field-types'
+
+/**
+ * Table Fields
+ *
+ * Collection of all supported field types in a table.
+ * Each field type has specific properties and validation rules.
+ * Fields are the columns in your database tables and determine
+ * what data can be stored and how it is validated.
+ *
+ * @see docs/specifications/roadmap/tables/fields.md for full specification
+ */
+export const FieldsSchema = Schema.Array(
+  Schema.Union(
+    // Text field types (individual schemas)
+    SingleLineTextFieldSchema,
+    LongTextFieldSchema,
+    PhoneNumberFieldSchema,
+    EmailFieldSchema,
+    UrlFieldSchema,
+    // Number field types (individual schemas)
+    IntegerFieldSchema,
+    DecimalFieldSchema,
+    CurrencyFieldSchema,
+    PercentageFieldSchema,
+    // Other field types
+    DateFieldSchema,
+    CheckboxFieldSchema,
+    SingleSelectFieldSchema,
+    MultiSelectFieldSchema,
+    RelationshipFieldSchema,
+    SingleAttachmentFieldSchema,
+    MultipleAttachmentsFieldSchema,
+    FormulaFieldSchema,
+    RollupFieldSchema,
+    LookupFieldSchema,
+    CountFieldSchema,
+    UserFieldSchema,
+    CreatedAtFieldSchema,
+    CreatedByFieldSchema,
+    UpdatedAtFieldSchema,
+    UpdatedByFieldSchema,
+    DeletedAtFieldSchema,
+    DeletedByFieldSchema,
+    RatingFieldSchema,
+    DurationFieldSchema,
+    RichTextFieldSchema,
+    StatusFieldSchema,
+    ButtonFieldSchema,
+    AutonumberFieldSchema,
+    BarcodeFieldSchema,
+    ColorFieldSchema,
+    ProgressFieldSchema,
+    GeolocationFieldSchema,
+    JsonFieldSchema,
+    ArrayFieldSchema,
+    // Unknown field type (catch-all for invalid types that will fail during SQL generation)
+    UnknownFieldSchema
+  )
+).pipe(
+  Schema.minItems(1),
+  Schema.filter((fields) => {
+    const ids = fields.map((field) => field.id)
+    const uniqueIds = new Set(ids)
+    return ids.length === uniqueIds.size || 'Field IDs must be unique within the table'
+  }),
+  Schema.filter((fields) => {
+    const names = fields.map((field) => field.name)
+    const uniqueNames = new Set(names)
+    return names.length === uniqueNames.size || 'Field names must be unique within the table'
+  }),
+  Schema.filter((fields) => {
+    // Validate count fields reference existing relationship-type fields
+    const countFields = fields.filter((field) => field.type === 'count')
+
+    const invalidResult = countFields
+      .map((countField) => {
+        const { relationshipField } = countField as { relationshipField: string }
+        return validateComputedFieldRelationship({
+          fields,
+          computedFieldName: countField.name,
+          computedFieldType: 'count',
+          relationshipField,
+        })
+      })
+      .find((result) => result !== true)
+
+    return invalidResult !== undefined ? invalidResult : true
+  }),
+  Schema.filter((fields) => {
+    // Validate rollup fields reference existing relationship-type fields
+    const rollupFields = fields.filter((field) => field.type === 'rollup')
+
+    const invalidResult = rollupFields
+      .map((rollupField) => {
+        const { relationshipField } = rollupField as { relationshipField: string }
+        return validateComputedFieldRelationship({
+          fields,
+          computedFieldName: rollupField.name,
+          computedFieldType: 'rollup',
+          relationshipField,
+        })
+      })
+      .find((result) => result !== true)
+
+    return invalidResult !== undefined ? invalidResult : true
+  }),
+  Schema.annotations({
+    title: 'Table Fields',
+    description:
+      'Collection of all supported field types. Each field defines a column in the database table with specific validation and behavior.',
+    examples: [
+      [
+        {
+          id: 1,
+          name: 'email',
+          type: 'email' as const,
+          required: true,
+        },
+        {
+          id: 2,
+          name: 'age',
+          type: 'integer' as const,
+          min: 0,
+          max: 150,
+        },
+      ],
+    ],
+  })
+)
+
+export type Fields = Schema.Schema.Type<typeof FieldsSchema>
+
+/**
+ * Validate that a computed field (count or rollup) references a valid relationship field.
+ *
+ * This helper validates that:
+ * 1. The relationshipField exists in the current table's fields
+ * 2. The relationshipField is a relationship type
+ *
+ * Used by both count and rollup field validation to ensure they reference valid relationships.
+ *
+ * @param params - Validation parameters
+ * @returns Error message if validation fails, true if valid
+ */
+export const validateComputedFieldRelationship = (params: {
+  readonly fields: ReadonlyArray<{ readonly name: string; readonly type: string }>
+  readonly computedFieldName: string
+  readonly computedFieldType: 'count' | 'rollup'
+  readonly relationshipField: string
+}): string | true => {
+  const { fields, computedFieldName, computedFieldType, relationshipField } = params
+  const fieldsByName = new Map(fields.map((field) => [field.name, field]))
+  const referencedField = fieldsByName.get(relationshipField)
+
+  if (!referencedField) {
+    const capitalize = (str: string) => str.charAt(0).toUpperCase() + str.slice(1)
+    return `${capitalize(computedFieldType)} field "${computedFieldName}" references relationshipField "${relationshipField}" not found in the same table`
+  }
+
+  if (referencedField.type !== 'relationship') {
+    const capitalize = (str: string) => str.charAt(0).toUpperCase() + str.slice(1)
+    return `${capitalize(computedFieldType)} field "${computedFieldName}" relationshipField "${relationshipField}" must reference a relationship field`
+  }
+
+  return true
+}