sovrium 0.0.2

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

@@ -0,0 +1,290 @@
+/**
+ * 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 { TableIdSchema } from '@/domain/models/app/common/branded-ids'
+import { CheckConstraintsSchema } from './check-constraints'
+import { FieldsSchema } from './fields'
+import { ForeignKeySchema } from './foreign-keys'
+import { IndexesSchema } from './indexes'
+import { NameSchema } from './name'
+import { TablePermissionsSchema } from './permissions'
+import { PrimaryKeySchema } from './primary-key'
+import { SPECIAL_FIELDS, validateFormulaFields } from './table-formula-validation'
+import { validateIndexes } from './table-indexes-validation'
+import { validateTablePermissions } from './table-permissions-validation'
+import { validatePrimaryKey } from './table-primary-key-validation'
+import { validateViews } from './table-views-validation'
+import { UniqueConstraintsSchema } from './unique-constraints'
+import { ViewSchema } from './views'
+
+// Re-export SPECIAL_FIELDS for external use
+export { SPECIAL_FIELDS }
+
+/**
+ * Table Schema
+ *
+ * Defines a single database table entity with its structure, fields, and constraints.
+ * Each table represents a distinct entity (e.g., users, products, orders) with fields
+ * that define the data schema. Tables support primary keys, unique constraints, and
+ * indexes for efficient data access and integrity.
+ *
+ * @example
+ * ```typescript
+ * const userTable = {
+ *   id: 1,
+ *   name: 'users',
+ *   fields: [
+ *     { id: 1, name: 'email', type: 'email', required: true },
+ *     { id: 2, name: 'name', type: 'single-line-text', required: true }
+ *   ],
+ *   primaryKey: { fields: ['id'] },
+ *   uniqueConstraints: [{ fields: ['email'] }]
+ * }
+ * ```
+ *
+ * @see docs/specifications/roadmap/tables.md for full specification
+ */
+
+/**
+ * Validate table schema including fields, permissions, views, and roles.
+ * Orchestrates all validation functions from extracted modules.
+ *
+ * IMPORTANT: This function uses a generic type parameter instead of an inline type annotation
+ * to avoid narrowing the Table type when used with Schema.filter(). Inline type annotations
+ * would cause TypeScript to narrow the schema's output type, removing properties like `id`,
+ * `required`, etc. from fields — cascading errors to all downstream consumers.
+ *
+ * @param table - Table to validate (type inferred from Schema.filter)
+ * @returns Validation error object if invalid, true if valid
+ */
+type ValidationError = { readonly message: string; readonly path: ReadonlyArray<string> }
+
+const validateStructure = (
+  table: Record<string, unknown>,
+  fieldNames: ReadonlySet<string>
+): ValidationError | undefined => {
+  if (table.primaryKey) {
+    const primaryKey = table.primaryKey as {
+      readonly type: string
+      readonly fields?: ReadonlyArray<string>
+    }
+    const primaryKeyError = validatePrimaryKey(primaryKey, fieldNames)
+    if (primaryKeyError) return primaryKeyError
+  }
+
+  const indexes = table.indexes as
+    | ReadonlyArray<{ readonly name: string; readonly fields: ReadonlyArray<string> }>
+    | undefined
+  if (indexes && indexes.length > 0) {
+    const indexError = validateIndexes(indexes, fieldNames)
+    if (indexError) return indexError
+  }
+
+  return undefined
+}
+
+const validateAccessAndViews = (
+  table: Record<string, unknown>,
+  fields: ReadonlyArray<{
+    readonly name: string
+    readonly type: string
+    readonly formula?: string
+  }>,
+  fieldNames: ReadonlySet<string>
+): ValidationError | undefined => {
+  if (table.permissions) {
+    const permissions = table.permissions as {
+      readonly fields?: ReadonlyArray<{ readonly field: string }>
+    }
+    const permissionsError = validateTablePermissions(permissions, fields, fieldNames)
+    if (permissionsError) return permissionsError
+  }
+
+  const views = table.views as
+    | ReadonlyArray<{ readonly id: string | number; readonly isDefault?: boolean }>
+    | undefined
+  if (views && views.length > 0) {
+    const viewsError = validateViews(views, fields, fieldNames)
+    if (viewsError) return viewsError
+  }
+
+  return undefined
+}
+
+const validateTableSchema = (table: Record<string, unknown>): ValidationError | true => {
+  const fields = table.fields as ReadonlyArray<{
+    readonly name: string
+    readonly type: string
+    readonly formula?: string
+  }>
+  const fieldNames = new Set(fields.map((field) => field.name))
+
+  // Validate formula fields (always required)
+  const formulaError = validateFormulaFields(fields)
+  if (formulaError) return formulaError
+
+  // Validate structural constraints (primaryKey, indexes)
+  const structureError = validateStructure(table, fieldNames)
+  if (structureError) return structureError
+
+  // Validate access control and views (permissions, views)
+  const accessError = validateAccessAndViews(table, fields, fieldNames)
+  if (accessError) return accessError
+
+  return true
+}
+
+export const TableSchema = Schema.Struct({
+  id: Schema.optional(TableIdSchema),
+  name: NameSchema,
+  fields: FieldsSchema,
+  primaryKey: Schema.optional(PrimaryKeySchema),
+  uniqueConstraints: Schema.optional(UniqueConstraintsSchema),
+  indexes: Schema.optional(IndexesSchema),
+  views: Schema.optional(Schema.Array(ViewSchema)),
+
+  /**
+   * Composite foreign key constraints.
+   *
+   * Used for multi-column foreign keys where multiple fields together reference
+   * a composite primary key in another table. Single-column foreign keys are
+   * automatically created from relationship fields.
+   *
+   * @example Composite foreign key
+   * ```typescript
+   * foreignKeys: [{
+   *   name: 'fk_permissions_tenant_user',
+   *   fields: ['tenant_id', 'user_id'],
+   *   referencedTable: 'tenant_users',
+   *   referencedFields: ['tenant_id', 'user_id']
+   * }]
+   * ```
+   *
+   * @see ForeignKeySchema for full configuration options
+   */
+  foreignKeys: Schema.optional(Schema.Array(ForeignKeySchema)),
+
+  /**
+   * Custom CHECK constraints for complex business rules.
+   *
+   * Used to enforce conditional validation at the database level beyond
+   * simple field-level constraints. Useful for cross-field validation,
+   * conditional requirements, and complex business logic.
+   *
+   * @example Conditional requirement
+   * ```typescript
+   * constraints: [{
+   *   name: 'chk_active_members_have_email',
+   *   check: '(is_active = false) OR (email IS NOT NULL)'
+   * }]
+   * ```
+   *
+   * @example Range validation
+   * ```typescript
+   * constraints: [{
+   *   name: 'chk_end_after_start',
+   *   check: 'end_date > start_date'
+   * }]
+   * ```
+   *
+   * @see CheckConstraintsSchema for full configuration options
+   */
+  constraints: Schema.optional(CheckConstraintsSchema),
+
+  /**
+   * Table-level permissions (high-level RBAC abstraction).
+   *
+   * Configures application-layer permission enforcement.
+   * Supports public, authenticated, and role-based access control.
+   *
+   * @example Role-based permissions
+   * ```typescript
+   * permissions: {
+   *   read: 'all',
+   *   comment: 'authenticated',
+   *   create: ['admin', 'editor'],
+   *   update: ['admin', 'editor'],
+   *   delete: ['admin'],
+   * }
+   * ```
+   *
+   * @see TablePermissionsSchema for full configuration options
+   */
+  permissions: Schema.optional(TablePermissionsSchema),
+
+  /**
+   * Allow destructive operations (column drops, table drops) without confirmation.
+   *
+   * When set to true, migrations are allowed to drop columns that exist in the database
+   * but are not present in the schema. This can result in data loss.
+   *
+   * When false or undefined, migrations will throw an error if a column needs to be dropped,
+   * requiring explicit confirmation to proceed with data loss operations.
+   *
+   * @default false
+   *
+   * @example Allow column drops
+   * ```typescript
+   * {
+   *   name: 'users',
+   *   fields: [{ id: 1, name: 'email', type: 'email' }],
+   *   allowDestructive: true // Allows dropping columns not in schema
+   * }
+   * ```
+   */
+  allowDestructive: Schema.optional(Schema.Boolean),
+}).pipe(
+  Schema.filter(validateTableSchema),
+  Schema.annotations({
+    title: 'Table',
+    description:
+      'A database table that defines the structure of an entity in your application. Contains fields, constraints, and indexes to organize and validate data.',
+    examples: [
+      {
+        id: 1,
+        name: 'users',
+        fields: [
+          { id: 1, name: 'email', type: 'email' as const, required: true },
+          { id: 2, name: 'name', type: 'single-line-text' as const, required: true },
+        ],
+      },
+      {
+        id: 2,
+        name: 'products',
+        fields: [
+          { id: 1, name: 'title', type: 'single-line-text' as const, required: true },
+          {
+            id: 2,
+            name: 'price',
+            type: 'currency' as const,
+            required: true,
+            currency: 'USD',
+          },
+          { id: 3, name: 'description', type: 'long-text' as const, required: false },
+        ],
+        primaryKey: { type: 'composite', fields: ['id'] },
+      },
+    ],
+  })
+)
+
+export type Table = Schema.Schema.Type<typeof TableSchema>
+
+// Re-export all table model schemas and types for convenient imports
+export * from './check-constraints'
+export * from './field-name'
+export * from './field-types'
+export * from './fields'
+export * from './foreign-keys'
+export * from './id'
+export * from './indexes'
+export * from './name'
+export * from './permissions'
+export * from './primary-key'
+export * from './unique-constraints'
+export * from './views'

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

@@ -0,0 +1,80 @@
+/**
+ * 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'
+
+/**
+ * Database Indexes
+ *
+ * Custom database indexes for query optimization. Indexes improve query performance by creating efficient lookup structures for specified fields.
+ *
+ * @example
+ * ```typescript
+ * [
+ *   {
+ *     "name": "idx_user_email",
+ *     "fields": [
+ *       "email"
+ *     ]
+ *   },
+ *   {
+ *     "name": "idx_user_created",
+ *     "fields": [
+ *       "created_at"
+ *     ],
+ *     "unique": false
+ *   }
+ * ]
+ * ```
+ */
+export const IndexesSchema = Schema.Array(
+  Schema.Struct({
+    name: Schema.String.pipe(
+      Schema.minLength(1, { message: () => 'This field is required' }),
+      Schema.pattern(/^[a-z][a-z0-9_]*$/, {
+        message: () => "Name of the index. Use descriptive names like 'idx_tablename_fieldname'",
+      }),
+      Schema.annotations({
+        description: "Name of the index. Use descriptive names like 'idx_tablename_fieldname'",
+        examples: ['idx_users_email', 'idx_products_sku', 'idx_orders_status'],
+      })
+    ),
+    fields: Schema.Array(
+      Schema.String.pipe(Schema.minLength(1, { message: () => 'This field is required' }))
+    ).pipe(Schema.minItems(1, { message: () => 'At least one field is required' })),
+    unique: Schema.optional(Schema.Boolean),
+    where: Schema.optional(
+      Schema.String.pipe(
+        Schema.minLength(1, { message: () => 'This field is required' }),
+        Schema.annotations({
+          description:
+            'WHERE clause for partial indexes. Creates an index that includes only rows satisfying the condition. Useful for enforcing uniqueness only on non-NULL values.',
+          examples: ['username IS NOT NULL', "status = 'active'", 'deleted_at IS NULL'],
+        })
+      )
+    ),
+  })
+).pipe(
+  Schema.filter((indexes) => {
+    const names = indexes.map((index) => index.name)
+    const uniqueNames = new Set(names)
+    return names.length === uniqueNames.size || 'Index names must be unique within the table'
+  }),
+  Schema.annotations({
+    title: 'Database Indexes',
+    description:
+      'Custom database indexes for query optimization. Indexes improve query performance by creating efficient lookup structures for specified fields.',
+    examples: [
+      [
+        { name: 'idx_user_email', fields: ['email'] },
+        { name: 'idx_user_created', fields: ['created_at'], unique: false },
+      ],
+    ],
+  })
+)
+
+export type Indexes = Schema.Schema.Type<typeof IndexesSchema>

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

@@ -0,0 +1,37 @@
+/**
+ * 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'
+
+/**
+ * Table Name
+ *
+ * Name of the database table
+ *
+ * @example
+ * ```typescript
+ * "users"
+ * ```
+ */
+export const NameSchema = createDatabaseIdentifierSchema('table').pipe(
+  Schema.annotations({
+    title: 'Name',
+    description:
+      'User-friendly name for the table. Can contain spaces, mixed case, and special characters. Will be automatically sanitized for database use (lowercase with underscores). Maximum 63 characters. Choose descriptive names that clearly indicate the purpose.',
+    examples: [
+      'Person',
+      'Product',
+      'Invoice Item',
+      'Customer Email',
+      'Shipping Address',
+      'My Projects',
+    ],
+  })
+)
+
+export type Name = Schema.Schema.Type<typeof NameSchema>

package/src/domain/models/app/table/permissions/field-permission.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 { TablePermissionSchema } from './permission'
+
+/**
+ * Field Permission Schema
+ *
+ * Defines granular permissions for a specific field within a table.
+ * Allows restricting read/write access to individual columns based on roles.
+ * Uses the same 3-format permission system as table-level operations.
+ *
+ * @example Restrict salary field to admins only
+ * ```yaml
+ * - field: salary
+ *   read: ['admin', 'hr']
+ *   write: ['admin']
+ * ```
+ *
+ * @example Make department readable by all, writable by admins
+ * ```yaml
+ * - field: department
+ *   read: all
+ *   write: ['admin']
+ * ```
+ */
+export const FieldPermissionSchema = Schema.Struct({
+  /**
+   * The name of the field this permission applies to.
+   */
+  field: Schema.String,
+
+  /**
+   * Who can read (SELECT) this field.
+   * If not specified, inherits from table-level read permission.
+   */
+  read: Schema.optional(TablePermissionSchema),
+
+  /**
+   * Who can write (INSERT/UPDATE) this field.
+   * If not specified, inherits from table-level create/update permission.
+   */
+  write: Schema.optional(TablePermissionSchema),
+}).pipe(
+  Schema.annotations({
+    title: 'Field Permission',
+    description:
+      "Granular permission for a specific field. Uses same format as table-level: 'all', 'authenticated', or role array.",
+    examples: [
+      {
+        field: 'salary',
+        read: ['admin', 'hr'] as readonly string[],
+        write: ['admin'] as readonly string[],
+      },
+      {
+        field: 'department',
+        read: 'all' as const,
+        write: ['admin'] as readonly string[],
+      },
+    ],
+  })
+)
+
+export type FieldPermission = Schema.Schema.Type<typeof FieldPermissionSchema>
+
+/**
+ * Table Field Permissions Array Schema
+ *
+ * Array of field-level permission configurations for table permissions.
+ */
+export const TableFieldPermissionsSchema = Schema.Array(FieldPermissionSchema).pipe(
+  Schema.annotations({
+    title: 'Table Field Permissions',
+    description: 'Array of field-level permission configurations for table permissions.',
+  })
+)
+
+export type TableFieldPermissions = Schema.Schema.Type<typeof TableFieldPermissionsSchema>

package/src/domain/models/app/table/permissions/index.ts

@@ -0,0 +1,167 @@
+/**
+ * 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 { TableFieldPermissionsSchema } from './field-permission'
+import { TablePermissionSchema } from './permission'
+
+/**
+ * Table Permissions Schema
+ *
+ * Permissions for table operations using a simplified 3-format system.
+ * Each operation accepts one of:
+ * - `'all'` — Everyone (including unauthenticated users)
+ * - `'authenticated'` — Any logged-in user
+ * - `['admin', 'editor']` — Specific role names (array)
+ *
+ * Operations:
+ * - `read` — Who can view records
+ * - `comment` — Who can add comments to records
+ * - `create` — Who can create new records
+ * - `update` — Who can modify existing records
+ * - `delete` — Who can remove records
+ *
+ * Omitted operations default to deny (no access).
+ *
+ * @example Role-based permissions
+ * ```yaml
+ * permissions:
+ *   read: all
+ *   comment: authenticated
+ *   create: ['admin', 'editor']
+ *   update: ['admin', 'editor']
+ *   delete: ['admin']
+ * ```
+ *
+ * @example Minimal read-only public table
+ * ```yaml
+ * permissions:
+ *   read: all
+ * ```
+ */
+export const TablePermissionsSchema = Schema.Struct({
+  /**
+   * READ permission — who can view records from this table.
+   */
+  read: Schema.optional(TablePermissionSchema),
+
+  /**
+   * COMMENT permission — who can add comments to records.
+   */
+  comment: Schema.optional(TablePermissionSchema),
+
+  /**
+   * CREATE permission — who can create new records in this table.
+   */
+  create: Schema.optional(TablePermissionSchema),
+
+  /**
+   * UPDATE permission — who can modify existing records in this table.
+   */
+  update: Schema.optional(TablePermissionSchema),
+
+  /**
+   * DELETE permission — who can remove records from this table.
+   */
+  delete: Schema.optional(TablePermissionSchema),
+
+  /**
+   * Field-level permissions for granular column access control.
+   *
+   * Allows restricting read/write access to specific fields based on roles.
+   * Uses the same 3-format permission system as table-level operations.
+   *
+   * @example Restrict salary field to admins
+   * ```yaml
+   * fields:
+   *   - field: salary
+   *     read: ['admin', 'hr']
+   *     write: ['admin']
+   * ```
+   */
+  fields: Schema.optional(TableFieldPermissionsSchema),
+
+  /**
+   * INHERIT — inherit permissions from a parent table by name.
+   *
+   * When set, this table inherits all permissions from the specified parent table.
+   * Any explicitly defined permissions on this table take precedence over inherited ones.
+   * Circular inheritance chains are detected and rejected at configuration time.
+   *
+   * @example Inherit permissions from parent table
+   * ```yaml
+   * permissions:
+   *   inherit: articles
+   * ```
+   *
+   * @future Not yet implemented — target design for permission inheritance feature.
+   */
+  inherit: Schema.optional(
+    Schema.String.pipe(
+      Schema.nonEmptyString({ message: () => 'inherit table name must not be empty' }),
+      Schema.annotations({
+        description: 'Name of the parent table to inherit permissions from',
+      })
+    )
+  ),
+
+  /**
+   * OVERRIDE — override specific inherited permissions.
+   *
+   * Only meaningful when `inherit` is set. Allows overriding specific
+   * permission operations from the parent table while inheriting the rest.
+   *
+   * @example Override read permission from inherited parent
+   * ```yaml
+   * permissions:
+   *   inherit: articles
+   *   override:
+   *     read: ['admin']
+   * ```
+   *
+   * @future Not yet implemented — target design for permission inheritance feature.
+   */
+  override: Schema.optional(
+    Schema.Struct({
+      read: Schema.optional(TablePermissionSchema),
+      comment: Schema.optional(TablePermissionSchema),
+      create: Schema.optional(TablePermissionSchema),
+      update: Schema.optional(TablePermissionSchema),
+      delete: Schema.optional(TablePermissionSchema),
+    })
+  ),
+}).pipe(
+  Schema.annotations({
+    title: 'Table Permissions',
+    description:
+      "Permissions for table operations. Each operation accepts 'all', 'authenticated', or a role array. Omitted operations default to deny.",
+    examples: [
+      // Public read, admin-only write
+      {
+        read: 'all' as const,
+        comment: 'authenticated' as const,
+        create: ['admin'] as readonly string[],
+        update: ['admin'] as readonly string[],
+        delete: ['admin'] as readonly string[],
+      },
+      // Role-based with field restrictions
+      {
+        read: 'all' as const,
+        create: ['admin', 'editor'] as readonly string[],
+        update: ['admin', 'editor'] as readonly string[],
+        delete: ['admin'] as readonly string[],
+      },
+    ],
+  })
+)
+
+export type TablePermissions = Schema.Schema.Type<typeof TablePermissionsSchema>
+
+// Re-export sub-schemas for external use
+export * from './permission'
+export * from './field-permission'
+export * from './permission-evaluator'