sovrium 0.0.2

package/src/domain/models/app/table/field-name.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 { createDatabaseIdentifierSchema } from './database-identifier'
+
+/**
+ * Field Name
+ *
+ * Internal identifier name used for database columns and programmatic references.
+ * Must follow database naming conventions: start with a letter, contain only lowercase
+ * letters, numbers, and underscores, maximum 63 characters (PostgreSQL limit).
+ * This name is used in SQL queries, API endpoints, and code generation.
+ * Choose descriptive names that clearly indicate the purpose (e.g., "email_address" not "ea").
+ *
+ * @example
+ * ```typescript
+ * 'email'
+ * 'user_status'
+ * 'created_at'
+ * ```
+ */
+export const FieldNameSchema = createDatabaseIdentifierSchema('field').pipe(
+  Schema.annotations({
+    title: 'Field Name',
+    description:
+      'Internal identifier name for database columns following PostgreSQL naming conventions. Must start with a letter, contain only lowercase letters, numbers, and underscores, maximum 63 characters.',
+    examples: ['email', 'person_status', 'invoice_item', 'customer_email', 'created_at'],
+  })
+)
+
+export type FieldName = Schema.Schema.Type<typeof FieldNameSchema>

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

@@ -0,0 +1,33 @@
+/**
+ * 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'
+
+export const ArrayFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('array'),
+      itemType: Schema.optional(
+        Schema.String.pipe(Schema.annotations({ description: 'Type of items in the array' }))
+      ),
+      maxItems: Schema.optional(
+        Schema.Int.pipe(
+          Schema.greaterThanOrEqualTo(1),
+          Schema.annotations({ description: 'Maximum number of items allowed' })
+        )
+      ),
+    })
+  ),
+  Schema.annotations({
+    title: 'Array Field',
+    description: 'Stores arrays of values with optional type and length constraints.',
+    examples: [{ id: 1, name: 'tags', type: 'array', itemType: 'string', maxItems: 10 }],
+  })
+)
+
+export type ArrayField = Schema.Schema.Type<typeof ArrayFieldSchema>

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

@@ -0,0 +1,54 @@
+/**
+ * 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'
+
+export const AutonumberFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('autonumber'),
+      prefix: Schema.optional(
+        Schema.String.pipe(
+          Schema.annotations({
+            description: 'Optional prefix for the autonumber',
+            examples: ['INV-', 'ORD-', ''],
+          })
+        )
+      ),
+      startFrom: Schema.optional(
+        Schema.Int.pipe(
+          Schema.greaterThanOrEqualTo(1),
+          Schema.annotations({ description: 'Starting number' })
+        )
+      ),
+      digits: Schema.optional(
+        Schema.Int.pipe(
+          Schema.greaterThanOrEqualTo(1),
+          Schema.lessThanOrEqualTo(10),
+          Schema.annotations({ description: 'Number of digits with zero padding' })
+        )
+      ),
+    })
+  ),
+  Schema.annotations({
+    title: 'Autonumber Field',
+    description: 'Auto-incrementing number field with optional prefix and zero padding.',
+    examples: [
+      {
+        id: 1,
+        name: 'invoice_number',
+        type: 'autonumber',
+        prefix: 'INV-',
+        startFrom: 1000,
+        digits: 5,
+      },
+    ],
+  })
+)
+
+export type AutonumberField = Schema.Schema.Type<typeof AutonumberFieldSchema>

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

@@ -0,0 +1,56 @@
+/**
+ * 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'
+import { validateButtonAction } from '../validation-utils'
+
+const ButtonFieldBaseSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('button'),
+      label: Schema.String.pipe(
+        Schema.nonEmptyString({ message: () => 'label is required' }),
+        Schema.annotations({ description: 'Button text label' })
+      ),
+      action: Schema.String.pipe(Schema.annotations({ description: 'Type of action to trigger' })),
+      url: Schema.optional(
+        Schema.String.pipe(
+          Schema.annotations({ description: "URL to open (when action is 'url')" })
+        )
+      ),
+      automation: Schema.optional(
+        Schema.String.pipe(
+          Schema.annotations({
+            description: "Automation name to trigger (when action is 'automation')",
+          })
+        )
+      ),
+    })
+  )
+)
+
+export const ButtonFieldSchema = ButtonFieldBaseSchema.pipe(
+  Schema.filter(validateButtonAction),
+  Schema.annotations({
+    title: 'Button Field',
+    description:
+      'Interactive button that triggers actions like opening URLs or running automations.',
+    examples: [
+      {
+        id: 1,
+        name: 'approve',
+        type: 'button',
+        label: 'Approve',
+        action: 'automation',
+        automation: 'approve_request',
+      },
+    ],
+  })
+)
+
+export type ButtonField = Schema.Schema.Type<typeof ButtonFieldSchema>

package/src/domain/models/app/table/field-types/advanced/color-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'
+
+/**
+ * Color Field
+ *
+ * Stores color values in hexadecimal format (#RRGGBB).
+ * Typically rendered with a color picker in the UI.
+ * Supports optional default color value.
+ *
+ * @example
+ * ```typescript
+ * const field = {
+ *   id: 1,
+ *   name: 'brand_color',
+ *   type: 'color',
+ *   required: true,
+ *   default: '#3B82F6'
+ * }
+ * ```
+ */
+export const ColorFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('color'),
+      default: Schema.optional(
+        Schema.String.pipe(
+          Schema.pattern(/^#[0-9a-fA-F]{6}$/, {
+            message: () => 'Invalid format',
+          })
+        )
+      ),
+    })
+  ),
+  Schema.annotations({
+    title: 'Color Field',
+    description: 'Stores color values in hexadecimal format. Rendered with color picker in UI.',
+    examples: [
+      {
+        id: 1,
+        name: 'brand_color',
+        type: 'color',
+        required: true,
+        default: '#3B82F6',
+      },
+    ],
+  })
+)
+
+export type ColorField = Schema.Schema.Type<typeof ColorFieldSchema>

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

@@ -0,0 +1,54 @@
+/**
+ * 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 { ViewFilterConditionSchema } from '../../views/filters'
+import { BaseFieldSchema } from '../base-field'
+
+export const CountFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('count'),
+      relationshipField: Schema.String.pipe(
+        Schema.nonEmptyString({ message: () => 'relationshipField is required' }),
+        Schema.annotations({
+          description:
+            'Name of the relationship field in the same table to count linked records from',
+        })
+      ),
+      conditions: Schema.optional(
+        Schema.Array(ViewFilterConditionSchema).pipe(
+          Schema.annotations({
+            description: 'Filter conditions to apply when counting linked records',
+          })
+        )
+      ),
+    })
+  ),
+  Schema.annotations({
+    title: 'Count Field',
+    description:
+      'Counts the number of linked records from a relationship field. Optionally filters records with conditions.',
+    examples: [
+      {
+        id: 1,
+        name: 'task_count',
+        type: 'count',
+        relationshipField: 'tasks',
+      },
+      {
+        id: 2,
+        name: 'completed_task_count',
+        type: 'count',
+        relationshipField: 'tasks',
+        conditions: [{ field: 'status', operator: 'equals', value: 'completed' }],
+      },
+    ],
+  })
+)
+
+export type CountField = Schema.Schema.Type<typeof CountFieldSchema>

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

@@ -0,0 +1,58 @@
+/**
+ * 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'
+
+export const FormulaFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('formula'),
+      formula: Schema.String.pipe(
+        Schema.nonEmptyString({ message: () => 'formula is required' }),
+        Schema.annotations({
+          description:
+            'Formula expression to compute the value. Supports field references, operators, and functions.',
+          examples: [
+            'price * quantity',
+            "CONCAT(first_name, ' ', last_name)",
+            "IF(status = 'active', 'Yes', 'No')",
+            'ROUND(total * 0.15, 2)',
+          ],
+        })
+      ),
+      resultType: Schema.optional(
+        Schema.String.pipe(
+          Schema.annotations({ description: 'Expected data type of the formula result' })
+        )
+      ),
+      format: Schema.optional(
+        Schema.String.pipe(
+          Schema.annotations({
+            description: 'Display format for the result (e.g., currency, percentage)',
+            examples: ['currency', 'percentage', 'decimal', 'date'],
+          })
+        )
+      ),
+    })
+  ),
+  Schema.annotations({
+    title: 'Formula Field',
+    description: 'Computed field that calculates values based on formula expressions.',
+    examples: [
+      {
+        id: 1,
+        name: 'total_price',
+        type: 'formula',
+        formula: 'price * quantity',
+        resultType: 'number',
+      },
+    ],
+  })
+)
+
+export type FormulaField = Schema.Schema.Type<typeof FormulaFieldSchema>

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

@@ -0,0 +1,49 @@
+/**
+ * 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'
+
+/**
+ * Geolocation Field
+ *
+ * Stores geographic coordinates (latitude and longitude).
+ * Used for location-based features like maps, distance calculations, and proximity searches.
+ * Typically rendered with a map picker in the UI.
+ *
+ * @example
+ * ```typescript
+ * const field = {
+ *   id: 1,
+ *   name: 'office_location',
+ *   type: 'geolocation',
+ *   required: true
+ * }
+ * ```
+ */
+export const GeolocationFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('geolocation'),
+    })
+  ),
+  Schema.annotations({
+    title: 'Geolocation Field',
+    description:
+      'Stores geographic coordinates (latitude and longitude). Used for location-based features.',
+    examples: [
+      {
+        id: 1,
+        name: 'office_location',
+        type: 'geolocation',
+        required: true,
+      },
+    ],
+  })
+)
+
+export type GeolocationField = Schema.Schema.Type<typeof GeolocationFieldSchema>

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

@@ -0,0 +1,16 @@
+/**
+ * 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 './formula-field'
+export * from './count-field'
+export * from './autonumber-field'
+export * from './button-field'
+export * from './json-field'
+export * from './color-field'
+export * from './geolocation-field'
+export * from './array-field'
+export * from './unknown-field'

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

@@ -0,0 +1,25 @@
+/**
+ * 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'
+
+export const JsonFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('json'),
+      schema: Schema.optional(Schema.Struct({})),
+    })
+  ),
+  Schema.annotations({
+    title: 'JSON Field',
+    description: 'Stores structured JSON data with optional schema validation.',
+    examples: [{ id: 1, name: 'metadata', type: 'json', required: false }],
+  })
+)
+
+export type JsonField = Schema.Schema.Type<typeof JsonFieldSchema>

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

@@ -0,0 +1,85 @@
+/**
+ * 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'
+
+/**
+ * Known field types that should NOT match UnknownFieldSchema
+ */
+const KNOWN_FIELD_TYPES = [
+  'array',
+  'autonumber',
+  'barcode',
+  'button',
+  'checkbox',
+  'color',
+  'count',
+  'created-at',
+  'created-by',
+  'currency',
+  'date',
+  'datetime',
+  'decimal',
+  'deleted-at',
+  'duration',
+  'email',
+  'formula',
+  'geolocation',
+  'integer',
+  'json',
+  'long-text',
+  'lookup',
+  'multi-select',
+  'multiple-attachments',
+  'percentage',
+  'phone-number',
+  'progress',
+  'rating',
+  'relationship',
+  'rich-text',
+  'rollup',
+  'single-attachment',
+  'single-line-text',
+  'single-select',
+  'status',
+  'time',
+  'updated-at',
+  'updated-by',
+  'url',
+  'user',
+] as const
+
+/**
+ * Unknown Field Type
+ *
+ * Represents a field with an unrecognized type that passes schema validation
+ * but will fail during SQL generation with "Unknown field type" error.
+ *
+ * This allows invalid field types to be caught during the migration phase
+ * where PostgreSQL transaction rollback can properly handle the error,
+ * rather than failing during schema validation before database operations begin.
+ *
+ * @example
+ * ```json
+ * {
+ *   "id": 1,
+ *   "name": "my_field",
+ *   "type": "INVALID_TYPE"
+ * }
+ * ```
+ */
+export const UnknownFieldSchema = Schema.Struct({
+  ...BaseFieldSchema.fields,
+  type: Schema.String.pipe(
+    Schema.filter((t) => !KNOWN_FIELD_TYPES.includes(t as (typeof KNOWN_FIELD_TYPES)[number]), {
+      message: () => 'Type must be an unknown field type (not a recognized field type)',
+    })
+  ),
+})
+
+export type UnknownField = Schema.Schema.Type<typeof UnknownFieldSchema>

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

@@ -0,0 +1,42 @@
+/**
+ * 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 { FieldIdSchema } from '@/domain/models/app/common/branded-ids'
+import { FieldNameSchema } from '@/domain/models/app/table/field-name'
+
+/**
+ * Base Field Schema
+ *
+ * Common properties shared across all field types.
+ * All field types should extend this base schema and add their specific properties.
+ *
+ * @example
+ * ```typescript
+ * export const CustomFieldSchema = BaseFieldSchema.pipe(
+ *   Schema.extend(
+ *     Schema.Struct({
+ *       type: Schema.Literal('custom'),
+ *       customProperty: Schema.String
+ *     })
+ *   )
+ * )
+ * ```
+ */
+export const BaseFieldSchema = Schema.Struct({
+  id: FieldIdSchema,
+  name: FieldNameSchema,
+  required: Schema.optional(Schema.Boolean),
+  unique: Schema.optional(Schema.Boolean),
+  indexed: Schema.optional(Schema.Boolean),
+}).pipe(
+  Schema.annotations({
+    description: 'Base field properties: id, name, required, unique, indexed',
+  })
+)
+
+export type BaseField = Schema.Schema.Type<typeof BaseFieldSchema>

package/src/domain/models/app/table/field-types/date-time/created-at-field.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 At Field
+ *
+ * Automatically captures the timestamp when a record is created.
+ * This field is system-managed and cannot be manually edited.
+ * Commonly used for audit trails and sorting by creation date.
+ *
+ * @example
+ * ```typescript
+ * const field = {
+ *   id: 1,
+ *   name: 'created_at',
+ *   type: 'created-at',
+ *   indexed: true
+ * }
+ * ```
+ */
+export const CreatedAtFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('created-at'),
+    })
+  ),
+  Schema.annotations({
+    title: 'Created At Field',
+    description:
+      'Automatically captures the timestamp when a record is created. System-managed field that cannot be manually edited.',
+    examples: [
+      {
+        id: 1,
+        name: 'created_at',
+        type: 'created-at',
+        indexed: true,
+      },
+    ],
+  })
+)
+
+export type CreatedAtField = Schema.Schema.Type<typeof CreatedAtFieldSchema>