sovrium 0.0.2

package/src/domain/models/app/table/table-permissions-validation.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 { findDuplicate } from './field-types/validation-utils'
+
+/**
+ * Validate that field permissions reference existing fields and don't have duplicates.
+ *
+ * @param fieldPermissions - Array of field permissions to validate
+ * @param fieldNames - Set of valid field names in the table
+ * @returns Error object if validation fails, undefined if valid
+ */
+export const validateFieldPermissions = (
+  fieldPermissions: ReadonlyArray<{ readonly field: string }>,
+  fieldNames: ReadonlySet<string>
+): { readonly message: string; readonly path: ReadonlyArray<string> } | undefined => {
+  // Check for duplicate field permissions
+  const fieldPermissionNames = fieldPermissions.map((fp) => fp.field)
+  const duplicateField = findDuplicate(fieldPermissionNames)
+
+  if (duplicateField) {
+    return {
+      message: `Duplicate field permission for field '${duplicateField}' - conflicting permission definitions`,
+      path: ['permissions', 'fields'],
+    }
+  }
+
+  // Check for non-existent field references
+  const invalidFieldPermission = fieldPermissions.find(
+    (fieldPermission) => !fieldNames.has(fieldPermission.field)
+  )
+
+  if (invalidFieldPermission) {
+    return {
+      message: `Field permission references non-existent field '${invalidFieldPermission.field}' - field does not exist in table`,
+      path: ['permissions', 'fields'],
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Validate table permissions including field permissions.
+ *
+ * With the simplified 3-format permission system ('all', 'authenticated', role array),
+ * table-level CRUD permissions are validated by the schema itself.
+ * This function handles cross-field validation (field permissions referencing table fields).
+ *
+ * @param permissions - Table permissions to validate
+ * @param _fields - Table fields (unused, kept for interface compatibility)
+ * @param fieldNames - Set of valid field names
+ * @returns Validation error object if invalid, undefined if valid
+ */
+export const validateTablePermissions = (
+  permissions: {
+    readonly fields?: ReadonlyArray<{
+      readonly field: string
+    }>
+  },
+  _fields: ReadonlyArray<{ readonly name: string; readonly type: string }>,
+  fieldNames: ReadonlySet<string>
+): { readonly message: string; readonly path: ReadonlyArray<string> } | undefined => {
+  // Validate field permissions reference existing fields
+  if (permissions.fields) {
+    const fieldPermissionsError = validateFieldPermissions(permissions.fields, fieldNames)
+    if (fieldPermissionsError) {
+      return fieldPermissionsError
+    }
+  }
+
+  return undefined
+}

package/src/domain/models/app/table/table-primary-key-validation.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 { findDuplicate } from './field-types/validation-utils'
+import { SPECIAL_FIELDS } from './table-formula-validation'
+
+/**
+ * Validate primary key configuration (field references, duplicates).
+ *
+ * @param primaryKey - Primary key configuration to validate
+ * @param fieldNames - Set of valid field names in the table
+ * @returns Error object if validation fails, undefined if valid
+ */
+export const validatePrimaryKey = (
+  primaryKey: { readonly type: string; readonly fields?: ReadonlyArray<string> } | undefined,
+  fieldNames: ReadonlySet<string>
+): { readonly message: string; readonly path: ReadonlyArray<string> } | undefined => {
+  if (!primaryKey || primaryKey.type !== 'composite' || !primaryKey.fields) {
+    return undefined
+  }
+
+  // Check for duplicate field references
+  const duplicateField = findDuplicate(primaryKey.fields)
+
+  if (duplicateField) {
+    return {
+      message: `Primary key field '${duplicateField}' is not unique - duplicate field references in composite primary key`,
+      path: ['primaryKey', 'fields'],
+    }
+  }
+
+  // Check for non-existent field references (allow special fields)
+  const invalidField = primaryKey.fields.find(
+    (field) => !fieldNames.has(field) && !SPECIAL_FIELDS.has(field)
+  )
+
+  if (invalidField) {
+    return {
+      message: `Primary key references non-existent field '${invalidField}' - field not found in table`,
+      path: ['primaryKey', 'fields'],
+    }
+  }
+
+  return undefined
+}

package/src/domain/models/app/table/table-views-validation.ts

@@ -0,0 +1,408 @@
+/**
+ * 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 { findDuplicate } from './field-types/validation-utils'
+import { SPECIAL_FIELDS } from './table-formula-validation'
+
+/**
+ * Validate that view IDs are unique within a table.
+ *
+ * @param views - Array of views to validate
+ * @returns Error object if validation fails, undefined if valid
+ */
+const validateViewIds = (
+  views: ReadonlyArray<{ readonly id: string | number }>
+): { readonly message: string; readonly path: ReadonlyArray<string> } | undefined => {
+  // Convert all view IDs to strings for comparison (ViewId can be number or string)
+  const viewIds = views.map((view) => String(view.id))
+
+  // Find duplicate view ID
+  const duplicateId = findDuplicate(viewIds)
+
+  if (duplicateId) {
+    return {
+      message: `Duplicate view id '${duplicateId}' - view id must be unique within the table`,
+      path: ['views'],
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Validate that only one view is marked as default within a table.
+ *
+ * @param views - Array of views to validate
+ * @returns Error object if validation fails, undefined if valid
+ */
+const validateDefaultViews = (
+  views: ReadonlyArray<{ readonly id: string | number; readonly isDefault?: boolean }>
+): { readonly message: string; readonly path: ReadonlyArray<string> } | undefined => {
+  const defaultViews = views.filter((view) => view.isDefault === true)
+
+  if (defaultViews.length > 1) {
+    return {
+      message: 'Only one default view is allowed per table - multiple default views found',
+      path: ['views'],
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Extract field references from a filter node recursively.
+ * Handles single conditions, AND groups, and OR groups.
+ *
+ * @param filterNode - The filter node to extract fields from
+ * @returns Array of field names referenced in the filter
+ */
+const extractFieldReferencesFromFilter = (
+  filterNode:
+    | { readonly field: string; readonly operator: string; readonly value: unknown }
+    | { readonly and: ReadonlyArray<unknown> }
+    | { readonly or: ReadonlyArray<unknown> }
+): ReadonlyArray<string> => {
+  // Single condition - extract field name
+  if ('field' in filterNode) {
+    return [filterNode.field]
+  }
+
+  // AND group - recursively extract from all conditions
+  if ('and' in filterNode && Array.isArray(filterNode.and)) {
+    return filterNode.and.flatMap((node) =>
+      extractFieldReferencesFromFilter(
+        node as
+          | { readonly field: string; readonly operator: string; readonly value: unknown }
+          | { readonly and: ReadonlyArray<unknown> }
+          | { readonly or: ReadonlyArray<unknown> }
+      )
+    )
+  }
+
+  // OR group - recursively extract from all conditions
+  if ('or' in filterNode && Array.isArray(filterNode.or)) {
+    return filterNode.or.flatMap((node) =>
+      extractFieldReferencesFromFilter(
+        node as
+          | { readonly field: string; readonly operator: string; readonly value: unknown }
+          | { readonly and: ReadonlyArray<unknown> }
+          | { readonly or: ReadonlyArray<unknown> }
+      )
+    )
+  }
+
+  return []
+}
+
+/**
+ * Extract filter conditions from a filter node recursively.
+ * Returns array of conditions with field, operator, and value.
+ *
+ * @param filterNode - The filter node to extract conditions from
+ * @returns Array of filter conditions
+ */
+const extractFilterConditions = (
+  filterNode:
+    | { readonly field: string; readonly operator: string; readonly value: unknown }
+    | { readonly and: ReadonlyArray<unknown> }
+    | { readonly or: ReadonlyArray<unknown> }
+): ReadonlyArray<{
+  readonly field: string
+  readonly operator: string
+  readonly value: unknown
+}> => {
+  // Single condition - return as array
+  if ('field' in filterNode) {
+    return [filterNode]
+  }
+
+  // AND group - recursively extract from all conditions
+  if ('and' in filterNode && Array.isArray(filterNode.and)) {
+    return filterNode.and.flatMap((node) =>
+      extractFilterConditions(
+        node as
+          | { readonly field: string; readonly operator: string; readonly value: unknown }
+          | { readonly and: ReadonlyArray<unknown> }
+          | { readonly or: ReadonlyArray<unknown> }
+      )
+    )
+  }
+
+  // OR group - recursively extract from all conditions
+  if ('or' in filterNode && Array.isArray(filterNode.or)) {
+    return filterNode.or.flatMap((node) =>
+      extractFilterConditions(
+        node as
+          | { readonly field: string; readonly operator: string; readonly value: unknown }
+          | { readonly and: ReadonlyArray<unknown> }
+          | { readonly or: ReadonlyArray<unknown> }
+      )
+    )
+  }
+
+  return []
+}
+
+/**
+ * Operator compatibility rules for field types.
+ * Maps field types to their valid operators.
+ * Only enforces restrictions for specific field types (e.g., checkbox cannot use 'contains').
+ * Other operators are allowed by default to avoid breaking valid use cases.
+ */
+const FIELD_TYPE_OPERATORS: ReadonlyMap<string, ReadonlySet<string>> = new Map([
+  // Checkbox: only boolean operators allowed
+  ['checkbox', new Set(['equals', 'isTrue', 'isFalse'])],
+])
+
+/**
+ * Validate that filter operators are compatible with field types.
+ *
+ * @param views - Array of views to validate
+ * @param fields - Array of fields in the table
+ * @returns Error object if validation fails, undefined if valid
+ */
+const validateFilterOperatorCompatibility = (
+  views: ReadonlyArray<{
+    readonly id: string | number
+    readonly filters?:
+      | { readonly field: string; readonly operator: string; readonly value: unknown }
+      | { readonly and: ReadonlyArray<unknown> }
+      | { readonly or: ReadonlyArray<unknown> }
+  }>,
+  fields: ReadonlyArray<{ readonly name: string; readonly type: string }>
+): { readonly message: string; readonly path: ReadonlyArray<string> } | undefined => {
+  const fieldTypeMap = new Map(fields.map((field) => [field.name, field.type]))
+
+  const incompatibleFilter = views
+    .filter((view) => view.filters !== undefined)
+    .flatMap((view) => {
+      const conditions = extractFilterConditions(view.filters!)
+      return conditions.flatMap((condition) => {
+        const fieldType = fieldTypeMap.get(condition.field)
+        if (!fieldType) {
+          return []
+        }
+
+        const validOperators = FIELD_TYPE_OPERATORS.get(fieldType)
+        if (!validOperators) {
+          // No restrictions defined for this field type
+          return []
+        }
+
+        if (!validOperators.has(condition.operator)) {
+          return [{ view, condition, fieldType }]
+        }
+
+        return []
+      })
+    })
+    .at(0)
+
+  if (incompatibleFilter) {
+    return {
+      message: `Incompatible operator '${incompatibleFilter.condition.operator}' for field '${incompatibleFilter.condition.field}' with type '${incompatibleFilter.fieldType}' - operator is invalid for checkbox field type`,
+      path: ['views'],
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Validate that view filters reference existing fields in the table.
+ *
+ * @param views - Array of views to validate
+ * @param fieldNames - Set of valid field names in the table
+ * @returns Error object if validation fails, undefined if valid
+ */
+const validateViewFilters = (
+  views: ReadonlyArray<{
+    readonly id: string | number
+    readonly filters?:
+      | { readonly field: string; readonly operator: string; readonly value: unknown }
+      | { readonly and: ReadonlyArray<unknown> }
+      | { readonly or: ReadonlyArray<unknown> }
+  }>,
+  fieldNames: ReadonlySet<string>
+): { readonly message: string; readonly path: ReadonlyArray<string> } | undefined => {
+  const invalidView = views
+    .filter((view) => view.filters !== undefined)
+    .flatMap((view) => {
+      const referencedFields = extractFieldReferencesFromFilter(view.filters!)
+      const invalidFields = referencedFields.filter(
+        (fieldName) => !fieldNames.has(fieldName) && !SPECIAL_FIELDS.has(fieldName)
+      )
+      return invalidFields.map((invalidField) => ({ view, invalidField }))
+    })
+    .at(0)
+
+  if (invalidView) {
+    return {
+      message: `Filter references non-existent field '${invalidView.invalidField}' - field not found in table`,
+      path: ['views'],
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Validate that view fields reference existing fields in the table.
+ *
+ * @param views - Array of views to validate
+ * @param fieldNames - Set of valid field names in the table
+ * @returns Error object if validation fails, undefined if valid
+ */
+const validateViewFields = (
+  views: ReadonlyArray<{ readonly id: string | number; readonly fields?: ReadonlyArray<string> }>,
+  fieldNames: ReadonlySet<string>
+): { readonly message: string; readonly path: ReadonlyArray<string> } | undefined => {
+  const invalidView = views
+    .filter(
+      (view): view is typeof view & { readonly fields: ReadonlyArray<string> } =>
+        view.fields !== undefined && view.fields.length > 0
+    )
+    .flatMap((view) => {
+      const invalidFields = view.fields.filter(
+        (fieldName) => !fieldNames.has(fieldName) && !SPECIAL_FIELDS.has(fieldName)
+      )
+      return invalidFields.map((invalidField) => ({ view, invalidField }))
+    })
+    .at(0)
+
+  if (invalidView) {
+    return {
+      message: `View field '${invalidView.invalidField}' not found - view fields must reference existing table fields (non-existent field in view)`,
+      path: ['views'],
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Validate that view groupBy references existing fields in the table.
+ *
+ * @param views - Array of views to validate
+ * @param fieldNames - Set of valid field names in the table
+ * @returns Error object if validation fails, undefined if valid
+ */
+const validateViewGroupBy = (
+  views: ReadonlyArray<{
+    readonly id: string | number
+    readonly groupBy?: { readonly field: string }
+  }>,
+  fieldNames: ReadonlySet<string>
+): { readonly message: string; readonly path: ReadonlyArray<string> } | undefined => {
+  const invalidView = views
+    .filter(
+      (view): view is typeof view & { readonly groupBy: { readonly field: string } } =>
+        view.groupBy !== undefined
+    )
+    .find((view) => !fieldNames.has(view.groupBy.field) && !SPECIAL_FIELDS.has(view.groupBy.field))
+
+  if (invalidView) {
+    return {
+      message: `groupBy references non-existent field '${invalidView.groupBy.field}' - field not found in table`,
+      path: ['views'],
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Validate that view sorts reference existing fields in the table.
+ *
+ * @param views - Array of views to validate
+ * @param fieldNames - Set of valid field names in the table
+ * @returns Error object if validation fails, undefined if valid
+ */
+const validateViewSorts = (
+  views: ReadonlyArray<{
+    readonly id: string | number
+    readonly sorts?: ReadonlyArray<{ readonly field: string; readonly direction: string }>
+  }>,
+  fieldNames: ReadonlySet<string>
+): { readonly message: string; readonly path: ReadonlyArray<string> } | undefined => {
+  const invalidView = views
+    .filter(
+      (
+        view
+      ): view is typeof view & {
+        readonly sorts: ReadonlyArray<{ readonly field: string; readonly direction: string }>
+      } => view.sorts !== undefined && view.sorts.length > 0
+    )
+    .flatMap((view) => {
+      const invalidFields = view.sorts.filter(
+        (sort) => !fieldNames.has(sort.field) && !SPECIAL_FIELDS.has(sort.field)
+      )
+      return invalidFields.map((sort) => ({ view, invalidField: sort.field }))
+    })
+    .at(0)
+
+  if (invalidView) {
+    return {
+      message: `Sort references non-existent field '${invalidView.invalidField}' - field not found in table`,
+      path: ['views'],
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Validate views configuration (IDs, default views, field references, filter references).
+ *
+ * @param views - Array of views to validate
+ * @param fields - Array of fields in the table
+ * @param fieldNames - Set of valid field names in the table
+ * @returns Error object if validation fails, undefined if valid
+ */
+export const validateViews = (
+  views: ReadonlyArray<{ readonly id: string | number; readonly isDefault?: boolean }>,
+  fields: ReadonlyArray<{ readonly name: string; readonly type: string }>,
+  fieldNames: ReadonlySet<string>
+): { readonly message: string; readonly path: ReadonlyArray<string> } | undefined => {
+  const viewsValidationError = validateViewIds(views)
+  if (viewsValidationError) {
+    return viewsValidationError
+  }
+
+  const defaultViewsValidationError = validateDefaultViews(views)
+  if (defaultViewsValidationError) {
+    return defaultViewsValidationError
+  }
+
+  const viewFieldsValidationError = validateViewFields(views, fieldNames)
+  if (viewFieldsValidationError) {
+    return viewFieldsValidationError
+  }
+
+  const viewFiltersValidationError = validateViewFilters(views, fieldNames)
+  if (viewFiltersValidationError) {
+    return viewFiltersValidationError
+  }
+
+  const viewSortsValidationError = validateViewSorts(views, fieldNames)
+  if (viewSortsValidationError) {
+    return viewSortsValidationError
+  }
+
+  const viewGroupByValidationError = validateViewGroupBy(views, fieldNames)
+  if (viewGroupByValidationError) {
+    return viewGroupByValidationError
+  }
+
+  const operatorCompatibilityError = validateFilterOperatorCompatibility(views, fields)
+  if (operatorCompatibilityError) {
+    return operatorCompatibilityError
+  }
+
+  return undefined
+}

package/src/domain/models/app/table/unique-constraints.ts

@@ -0,0 +1,79 @@
+/**
+ * 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'
+
+/**
+ * Unique Constraints
+ *
+ * Composite unique constraints ensure that combinations of multiple field values are unique across all rows. Use this when you need uniqueness across multiple fields (e.g., email + tenant_id must be unique together).
+ *
+ * @example
+ * ```typescript
+ * [
+ *   {
+ *     "name": "uq_user_email_tenant",
+ *     "fields": [
+ *       "email",
+ *       "tenant_id"
+ *     ]
+ *   },
+ *   {
+ *     "name": "uq_product_sku_variant",
+ *     "fields": [
+ *       "sku",
+ *       "variant_id"
+ *     ]
+ *   }
+ * ]
+ * ```
+ */
+export const UniqueConstraintsSchema = Schema.Array(
+  Schema.Struct({
+    name: Schema.String.pipe(
+      Schema.minLength(1, { message: () => 'This field is required' }),
+      Schema.pattern(/^[a-zA-Z][a-zA-Z0-9_]*$/, {
+        message: () =>
+          "Name of the unique constraint. Use descriptive names like 'uq_tablename_field1_field2'",
+      }),
+      Schema.transform(Schema.String, {
+        decode: (name) => name.toLowerCase(),
+        encode: (name) => name,
+      }),
+      Schema.annotations({
+        description:
+          "Name of the unique constraint. Use descriptive names like 'uq_tablename_field1_field2'",
+        examples: ['uq_users_email_tenant', 'uq_products_sku_variant', 'uq_orders_number_year'],
+      })
+    ),
+    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' })),
+  })
+).pipe(
+  Schema.filter((constraints) => {
+    const names = constraints.map((constraint) => constraint.name)
+    const uniqueNames = new Set(names)
+    return (
+      names.length === uniqueNames.size ||
+      'Duplicate constraint name - constraint name must be unique within the table'
+    )
+  }),
+  Schema.annotations({
+    title: 'Unique Constraints',
+    description:
+      'Composite unique constraints ensure that combinations of multiple field values are unique across all rows. Use this when you need uniqueness across multiple fields (e.g., email + tenant_id must be unique together).',
+    examples: [
+      [
+        { name: 'uq_user_email_tenant', fields: ['email', 'tenant_id'] },
+        { name: 'uq_product_sku_variant', fields: ['sku', 'variant_id'] },
+      ],
+    ],
+  })
+)
+
+export type UniqueConstraints = Schema.Schema.Type<typeof UniqueConstraintsSchema>

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

@@ -0,0 +1,28 @@
+/**
+ * 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'
+
+/**
+ * View Fields Schema
+ *
+ * Array of field names to include in the view.
+ * Fields are included in the order specified.
+ *
+ * @example
+ * ```typescript
+ * ['name', 'email', 'created_at']
+ * ```
+ */
+export const ViewFieldsSchema = Schema.Array(Schema.String).pipe(
+  Schema.annotations({
+    title: 'View Fields',
+    description: 'Array of field names to include in the view.',
+  })
+)
+
+export type ViewFields = Schema.Schema.Type<typeof ViewFieldsSchema>