sovrium 0.0.2

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

@@ -0,0 +1,162 @@
+/**
+ * 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 Filter Condition Schema
+ *
+ * A single filter condition for filtering records.
+ *
+ * @example
+ * ```typescript
+ * { field: 'status', operator: 'equals', value: 'active' }
+ * { field: 'age', operator: 'greaterThan', value: 18 }
+ * ```
+ */
+export const ViewFilterConditionSchema = Schema.Struct({
+  field: Schema.String,
+  operator: Schema.String,
+  value: Schema.Unknown,
+}).pipe(
+  Schema.annotations({
+    title: 'Filter Condition',
+    description: 'A single filter condition specifying field, operator, and value.',
+  })
+)
+
+export type ViewFilterCondition = Schema.Schema.Type<typeof ViewFilterConditionSchema>
+
+/**
+ * View Filter Node
+ *
+ * Recursive type for filter expressions. Can be either:
+ * - A condition: `{ field, operator, value }`
+ * - An AND group: `{ and: [...] }`
+ * - An OR group: `{ or: [...] }`
+ */
+export type ViewFilterNode =
+  | ViewFilterCondition
+  | { readonly and: ReadonlyArray<ViewFilterNode> }
+  | { readonly or: ReadonlyArray<ViewFilterNode> }
+
+/**
+ * View Filter Node Schema
+ *
+ * Recursive schema for nested filter expressions.
+ * Uses a simple `{ and: [...] }` or `{ or: [...] }` format.
+ *
+ * @example Simple condition
+ * ```typescript
+ * { field: 'status', operator: 'equals', value: 'active' }
+ * ```
+ *
+ * @example AND group
+ * ```typescript
+ * {
+ *   and: [
+ *     { field: 'status', operator: 'equals', value: 'active' },
+ *     { field: 'archived', operator: 'equals', value: false }
+ *   ]
+ * }
+ * ```
+ *
+ * @example Nested groups (Prisma/MongoDB style)
+ * ```typescript
+ * // (status = 'active') AND ((priority = 'high') OR (priority = 'urgent'))
+ * {
+ *   and: [
+ *     { field: 'status', operator: 'equals', value: 'active' },
+ *     {
+ *       or: [
+ *         { field: 'priority', operator: 'equals', value: 'high' },
+ *         { field: 'priority', operator: 'equals', value: 'urgent' }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * @example Complex nested logic
+ * ```typescript
+ * {
+ *   or: [
+ *     {
+ *       and: [
+ *         { field: 'type', operator: 'equals', value: 'task' },
+ *         { field: 'status', operator: 'equals', value: 'completed' }
+ *       ]
+ *     },
+ *     {
+ *       and: [
+ *         { field: 'type', operator: 'equals', value: 'bug' },
+ *         { field: 'severity', operator: 'equals', value: 'critical' }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export const ViewFilterNodeSchema: Schema.Schema<ViewFilterNode> = Schema.Union(
+  ViewFilterConditionSchema,
+  Schema.Struct({
+    and: Schema.Array(Schema.suspend((): Schema.Schema<ViewFilterNode> => ViewFilterNodeSchema)),
+  }),
+  Schema.Struct({
+    or: Schema.Array(Schema.suspend((): Schema.Schema<ViewFilterNode> => ViewFilterNodeSchema)),
+  })
+).pipe(
+  Schema.annotations({
+    identifier: 'ViewFilterNode',
+    title: 'Filter Node',
+    description: 'A filter condition or a logical group (and/or) of filter nodes.',
+  })
+)
+
+/**
+ * View Filters Schema
+ *
+ * Root filter configuration for views. Can be a single condition or a logical group.
+ *
+ * @example Single condition (implicit)
+ * ```typescript
+ * { field: 'status', operator: 'equals', value: 'active' }
+ * ```
+ *
+ * @example Multiple conditions with AND
+ * ```typescript
+ * {
+ *   and: [
+ *     { field: 'status', operator: 'equals', value: 'active' },
+ *     { field: 'archived', operator: 'equals', value: false }
+ *   ]
+ * }
+ * ```
+ *
+ * @example Complex nested filters
+ * ```typescript
+ * {
+ *   and: [
+ *     { field: 'status', operator: 'equals', value: 'active' },
+ *     {
+ *       or: [
+ *         { field: 'priority', operator: 'equals', value: 'high' },
+ *         { field: 'priority', operator: 'equals', value: 'urgent' }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export const ViewFiltersSchema = ViewFilterNodeSchema.pipe(
+  Schema.annotations({
+    title: 'View Filters',
+    description: 'Filter configuration using nested and/or groups.',
+  })
+)
+
+export type ViewFilters = Schema.Schema.Type<typeof ViewFiltersSchema>

package/src/domain/models/app/table/views/group-by.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 Group By Schema
+ *
+ * Grouping configuration for the view. Specifies which field to group records by.
+ *
+ * @example
+ * ```typescript
+ * { field: 'status' }
+ * { field: 'category', direction: 'asc' }
+ * { field: 'priority', direction: 'desc' }
+ * ```
+ */
+export const ViewGroupBySchema = Schema.Struct({
+  field: Schema.String,
+  direction: Schema.optional(Schema.Literal('asc', 'desc')),
+}).pipe(
+  Schema.annotations({
+    title: 'View Group By',
+    description: 'Grouping configuration specifying which field to group by.',
+  })
+)
+
+export type ViewGroupBy = Schema.Schema.Type<typeof ViewGroupBySchema>

package/src/domain/models/app/table/views/id.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'
+
+/**
+ * Valid View ID String Pattern
+ *
+ * String view IDs must follow snake_case or kebab-case pattern:
+ * - Only lowercase letters (a-z)
+ * - Numbers (0-9)
+ * - Underscores (_) and hyphens (-)
+ * - No spaces, no uppercase letters
+ */
+const ViewIdStringSchema = Schema.String.pipe(
+  Schema.pattern(/^[a-z0-9_-]+$/, {
+    message: () => 'must be one of the allowed values',
+  }),
+  Schema.annotations({
+    description: 'View ID as string (lowercase, numbers, underscores, hyphens only)',
+  })
+)
+
+/**
+ * View ID Schema
+ *
+ * Unique identifier for a view. Can be either a numeric ID or a string identifier.
+ * String IDs must follow snake_case or kebab-case pattern (lowercase, numbers, underscores, hyphens only).
+ *
+ * @example
+ * ```typescript
+ * 1
+ * 'default_view'
+ * 'kanban-view'
+ * ```
+ */
+export const ViewIdSchema = Schema.Union(Schema.Number, ViewIdStringSchema).pipe(
+  Schema.annotations({
+    title: 'View ID',
+    description:
+      'Unique identifier for the view. Can be a number or string (lowercase, numbers, underscores, hyphens only).',
+    examples: [1, 2, 'default', 'kanban_view'],
+  })
+)
+
+export type ViewId = Schema.Schema.Type<typeof ViewIdSchema>

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

@@ -0,0 +1,177 @@
+/**
+ * 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 { ViewFieldsSchema } from './fields'
+import { ViewFiltersSchema } from './filters'
+import { ViewGroupBySchema } from './group-by'
+import { ViewIdSchema } from './id'
+import { ViewNameSchema } from './name'
+import { ViewPermissionsSchema } from './permissions'
+import { ViewSortSchema } from './sorts'
+
+/**
+ * View Schema
+ *
+ * Represents a database view configuration for a table.
+ * Views can be defined in two modes:
+ *
+ * 1. **SQL Query Mode**: Define a raw SQL query that creates a PostgreSQL VIEW
+ * 2. **JSON Config Mode**: Define filters, sorts, fields, and groupBy declaratively
+ *
+ * Views support materialized views for caching aggregations with optional refresh on migration.
+ *
+ * @example SQL Query Mode (PostgreSQL VIEW)
+ * ```typescript
+ * const activeUsersView = {
+ *   id: 'active_users',
+ *   name: 'Active Users',
+ *   query: 'SELECT * FROM users WHERE active = true',
+ * }
+ * ```
+ *
+ * @example Materialized View
+ * ```typescript
+ * const orderStatsView = {
+ *   id: 'order_stats',
+ *   name: 'Order Statistics',
+ *   query: 'SELECT customer_id, COUNT(*) as order_count FROM orders GROUP BY customer_id',
+ *   materialized: true,
+ *   refreshOnMigration: true,
+ * }
+ * ```
+ *
+ * @example JSON Config Mode
+ * ```typescript
+ * const activeTasks = {
+ *   id: 'active_tasks',
+ *   name: 'Active Tasks',
+ *   isDefault: true,
+ *   filters: {
+ *     and: [{ field: 'status', operator: 'equals', value: 'active' }]
+ *   },
+ *   sorts: [{ field: 'priority', direction: 'desc' }],
+ * }
+ * ```
+ */
+export const ViewSchema = Schema.Struct({
+  id: ViewIdSchema,
+  name: ViewNameSchema,
+
+  /**
+   * SQL query for creating a PostgreSQL VIEW or MATERIALIZED VIEW.
+   * When provided, the view is created using CREATE VIEW statement.
+   * When omitted, JSON config mode is used (filters, sorts, fields, groupBy).
+   */
+  query: Schema.optional(Schema.String),
+
+  /**
+   * Whether this is a materialized view (PostgreSQL MATERIALIZED VIEW).
+   * Only applicable when `query` is provided.
+   * Materialized views cache query results for faster access.
+   */
+  materialized: Schema.optional(Schema.Boolean),
+
+  /**
+   * Whether to refresh the materialized view during migrations.
+   * Only applicable when `materialized` is true.
+   */
+  refreshOnMigration: Schema.optional(Schema.Boolean),
+
+  /**
+   * Whether this view is the default view for the table.
+   * The default view's configuration is applied when no specific view is requested.
+   */
+  isDefault: Schema.optional(Schema.Boolean),
+
+  /**
+   * Filter conditions for the view (JSON config mode).
+   * Defines which records are included in the view.
+   */
+  filters: Schema.optional(ViewFiltersSchema),
+
+  /**
+   * Sort configuration for the view (JSON config mode).
+   * Defines the order of records in the view.
+   */
+  sorts: Schema.optional(Schema.Array(ViewSortSchema)),
+
+  /**
+   * Fields to include in the view (JSON config mode).
+   * Array of field names in the order they should appear.
+   */
+  fields: Schema.optional(ViewFieldsSchema),
+
+  /**
+   * Group by configuration for the view (JSON config mode).
+   * Defines how records are grouped.
+   */
+  groupBy: Schema.optional(ViewGroupBySchema),
+
+  /**
+   * Role-based access permissions for the view.
+   */
+  permissions: Schema.optional(ViewPermissionsSchema),
+}).pipe(
+  Schema.annotations({
+    title: 'View',
+    description:
+      'A database view configuration for a table. Supports both SQL query mode (PostgreSQL VIEW) and JSON config mode (declarative filters, sorts, grouping).',
+    examples: [
+      // SQL query mode - simple view
+      {
+        id: 'active_users',
+        name: 'Active Users',
+        query: 'SELECT * FROM users WHERE active = true',
+      },
+      // SQL query mode - materialized view
+      {
+        id: 'order_stats',
+        name: 'Order Statistics',
+        query:
+          'SELECT customer_id, COUNT(*) as order_count, SUM(amount) as total FROM orders GROUP BY customer_id',
+        materialized: true,
+        refreshOnMigration: true,
+      },
+      // JSON config mode
+      {
+        id: 1,
+        name: 'Active Tasks',
+        isDefault: true,
+        filters: {
+          and: [{ field: 'status', operator: 'equals', value: 'active' }],
+        },
+        sorts: [{ field: 'priority', direction: 'desc' as const }],
+      },
+    ],
+  })
+)
+
+export type View = Schema.Schema.Type<typeof ViewSchema>
+
+/**
+ * Views Array Schema
+ *
+ * Array of views for a table.
+ */
+export const ViewsSchema = Schema.Array(ViewSchema).pipe(
+  Schema.annotations({
+    title: 'Views',
+    description: 'Collection of saved views for a table.',
+  })
+)
+
+export type Views = Schema.Schema.Type<typeof ViewsSchema>
+
+// Re-export all sub-schemas for external use
+export * from './id'
+export * from './name'
+export * from './filters'
+export * from './sorts'
+export * from './fields'
+export * from './group-by'
+export * from './permissions'

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

@@ -0,0 +1,32 @@
+/**
+ * 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 Name Schema
+ *
+ * Human-readable name for the view.
+ *
+ * @example
+ * ```typescript
+ * 'All Records'
+ * 'Active Tasks'
+ * 'Completed Orders'
+ * ```
+ */
+export const ViewNameSchema = Schema.String.pipe(
+  Schema.minLength(1),
+  Schema.maxLength(100),
+  Schema.annotations({
+    title: 'View Name',
+    description: 'Human-readable name for the view. Must be non-empty.',
+    examples: ['All Records', 'Active Tasks', 'Completed Orders'],
+  })
+)
+
+export type ViewName = Schema.Schema.Type<typeof ViewNameSchema>

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

@@ -0,0 +1,98 @@
+/**
+ * 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 { FlexibleRolesSchema } from '@/domain/models/app/permissions'
+
+/**
+ * Role-Based View Permissions Schema
+ *
+ * Defines view access control using role arrays for read and write operations.
+ * Uses FlexibleRolesSchema to support both standard and custom roles.
+ *
+ * @example
+ * ```typescript
+ * { read: ['admin', 'member'], write: ['admin'] }
+ * ```
+ */
+export const RoleBasedViewPermissionsSchema = Schema.Struct({
+  /**
+   * Roles that can read (view) this view.
+   */
+  read: Schema.optional(FlexibleRolesSchema),
+
+  /**
+   * Roles that can write (modify settings of) this view.
+   */
+  write: Schema.optional(FlexibleRolesSchema),
+}).pipe(
+  Schema.annotations({
+    title: 'Role-Based View Permissions',
+    description: 'View access control using role arrays.',
+    examples: [
+      { read: ['admin', 'member'], write: ['admin'] },
+      { read: ['admin', 'member', 'viewer'] },
+    ],
+  })
+)
+
+/**
+ * Public View Permissions Schema
+ *
+ * Marks a view as publicly accessible (no authentication required).
+ *
+ * @example
+ * ```typescript
+ * { public: true }
+ * ```
+ */
+export const PublicViewPermissionsSchema = Schema.Struct({
+  /**
+   * When true, the view is accessible without authentication.
+   */
+  public: Schema.Literal(true),
+}).pipe(
+  Schema.annotations({
+    title: 'Public View Permissions',
+    description: 'View is publicly accessible without authentication.',
+    examples: [{ public: true as const }],
+  })
+)
+
+/**
+ * View Permissions Schema
+ *
+ * Permissions configuration for the view, defining who can access or modify it.
+ * Supports two modes:
+ * 1. Role-based: `{ read: ['admin', 'member'], write: ['admin'] }`
+ * 2. Public access: `{ public: true }`
+ *
+ * @example Role-based permissions
+ * ```typescript
+ * { read: ['admin', 'user'], write: ['admin'] }
+ * ```
+ *
+ * @example Public view
+ * ```typescript
+ * { public: true }
+ * ```
+ */
+export const ViewPermissionsSchema = Schema.Union(
+  RoleBasedViewPermissionsSchema,
+  PublicViewPermissionsSchema
+).pipe(
+  Schema.annotations({
+    title: 'View Permissions',
+    description:
+      'Permission configuration for the view. Use role-based ({ read, write }) or public ({ public: true }).',
+    examples: [{ read: ['admin', 'member'], write: ['admin'] }, { public: true as const }],
+  })
+)
+
+export type ViewPermissions = Schema.Schema.Type<typeof ViewPermissionsSchema>
+export type RoleBasedViewPermissions = Schema.Schema.Type<typeof RoleBasedViewPermissionsSchema>
+export type PublicViewPermissions = Schema.Schema.Type<typeof PublicViewPermissionsSchema>

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

@@ -0,0 +1,31 @@
+/**
+ * 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 Sort Schema
+ *
+ * Sort configuration for a single field.
+ *
+ * @example
+ * ```typescript
+ * { field: 'createdAt', direction: 'desc' }
+ * { field: 'name', direction: 'asc' }
+ * ```
+ */
+export const ViewSortSchema = Schema.Struct({
+  field: Schema.String,
+  direction: Schema.Literal('asc', 'desc'),
+}).pipe(
+  Schema.annotations({
+    title: 'View Sort',
+    description: 'Sort configuration for a single field.',
+  })
+)
+
+export type ViewSort = Schema.Schema.Type<typeof ViewSortSchema>