Skip to content

METADATA_TYPES_IMPLEMENTATION.md

Latest commit

 

History

History
455 lines (382 loc) · 12.2 KB

METADATA_TYPES_IMPLEMENTATION.md

File metadata and controls

455 lines (382 loc) · 12.2 KB

Metadata Type Definitions Implementation

Complete TypeScript type definitions for all ObjectQL metadata formats. This implementation document covers the 100% type coverage achievement, including views, forms, pages, reports, menus, apps, actions, hooks, and workflows—ensuring full type safety across the metadata system.

New Type Definitions Added

1. ViewConfig (packages/foundation/types/src/view.ts)

Purpose: Define list views, grid views, and other data visualization views.

File Pattern: *.view.yml

Example Usage:

# projects.view.yml
name: all_projects
label: "Active Projects"
type: list
object: projects
columns:
  - field: name
    width: 250
  - field: status
    width: 120
filters:
  - field: status
    operator: "!="
    value: "archived"

Key Types:

  • ViewConfig - Main configuration interface
  • ViewType - View types (list, kanban, calendar, timeline, gallery, map, pivot)
  • ViewColumn - Column display configuration
  • ViewFilter - Filter conditions
  • ViewSort - Sorting configuration
  • View-specific configs: KanbanViewConfig, CalendarViewConfig, TimelineViewConfig, GalleryViewConfig, MapViewConfig

Features:

  • Column formatting and display options
  • Complex filter conditions with logical grouping
  • Grouping and pagination
  • Export capabilities
  • Search configuration
  • Inline editing support

2. WorkflowConfig (packages/foundation/types/src/workflow.ts)

Purpose: Define workflows, approvals, and automation processes.

File Pattern: *.workflow.yml

Example Usage:

# project_approval.workflow.yml
name: project_approval
label: "High Budget Project Approval"
type: approval
object: projects
trigger:
  event: create_or_update
  conditions:
    - field: budget
      operator: ">"
      value: 50000
steps:
  - name: manager_review
    label: "Manager Review"
    type: approval
    assignee:
      type: role
      role: manager
    actions:
      approve:
        label: "Approve"
        next_step: finance_review

Key Types:

  • WorkflowConfig - Main configuration interface
  • WorkflowType - Workflow types (approval, automation, scheduled, sequential, parallel)
  • WorkflowTrigger - Trigger event configuration
  • WorkflowStep - Individual step definition
  • WorkflowStepType - Step types (approval, action, notification, field_update, etc.)
  • WorkflowAssignee - Assignee configuration for approvals
  • WorkflowInstance - Runtime execution tracking

Features:

  • Multi-step approval chains
  • Conditional branching
  • Field updates and record creation
  • Notifications (email, SMS, push, in-app)
  • Wait conditions and loops
  • Webhook integrations
  • Error handling and retry logic
  • Parallel execution support

3. ReportConfig (packages/foundation/types/src/report.ts)

Purpose: Define reports, data summaries, and analytics.

File Pattern: *.report.yml

Example Usage:

# project_status.report.yml
name: project_status_summary
label: "Project Status Report"
type: summary
object: projects
columns:
  - field: name
    label: Project Name
  - field: budget
    label: Budget
    format: currency
groupings:
  - field: status
    label: Status
aggregations:
  - field: budget
    function: sum
    label: Total Budget
  - field: _id
    function: count
    label: Project Count

Key Types:

  • ReportConfig - Main configuration interface
  • ReportType - Report types (tabular, summary, matrix, chart, dashboard)
  • ChartType - Chart types (bar, line, pie, scatter, funnel, gauge, etc.)
  • ReportGrouping - Grouping configuration
  • ReportAggregation - Aggregation/calculation configuration
  • AggregationFunction - Aggregation functions (count, sum, avg, min, max, etc.)
  • ReportChartConfig - Chart visualization configuration
  • ReportExportConfig - Export settings (PDF, XLSX, CSV)
  • ReportScheduleConfig - Automated report scheduling

Features:

  • Multiple grouping levels
  • Complex aggregations and formulas
  • Chart visualizations
  • Matrix/pivot reports
  • Export to multiple formats
  • Scheduled report generation
  • Drill-down capabilities
  • Caching support

4. FormConfig (packages/foundation/types/src/form.ts)

Purpose: Define forms, layouts, and field arrangements.

File Pattern: *.form.yml

Example Usage:

# project_form.form.yml
name: project_main_form
label: "Project Details"
type: edit
object: projects
layout:
  tabs:
    - label: "General Info"
      sections:
        - label: "Basic Details"
          columns: 2
          fields:
            - name
            - owner
            - status
            - priority
    - label: "Planning"
      sections:
        - label: "Schedule & Budget"
          columns: 2
          fields:
            - start_date
            - end_date
            - budget

Key Types:

  • FormConfig - Main configuration interface
  • FormType - Form types (create, edit, view, wizard, quick_create)
  • FormLayoutType - Layout types (single/two/three column, tabs, accordion)
  • FormField - Field display configuration
  • FormSection - Section grouping
  • FormTab - Tab configuration
  • WizardStep - Wizard step for multi-step forms
  • FormAction - Form buttons and actions
  • FormValidationConfig - Validation behavior
  • FormAutosaveConfig - Autosave configuration
  • FormState - Runtime form state

Features:

  • Multiple layout types
  • Tab and section organization
  • Multi-step wizard forms
  • Conditional visibility
  • Field-level overrides
  • Custom validation
  • Autosave functionality
  • Header and footer customization

Type System Architecture

Zero Dependencies Principle

All new types follow the "Constitution" rule:

  • Located in @objectql/types package
  • Zero dependencies on other packages
  • Pure TypeScript interfaces, types, and enums
  • Can be used by both Backend (@objectql/core) and Frontend (@object-ui/*)

Consistency with Existing Types

The new types follow the same patterns as existing metadata types:

  1. Config Interface Pattern: Main interface named *Config

    • ObjectConfig, ValidationConfig, PermissionConfig (existing)
    • ViewConfig, WorkflowConfig, ReportConfig, FormConfig (new)

  2. Comprehensive JSDoc: All interfaces and properties documented

  3. Nested Type Definitions: Complex configurations broken into sub-interfaces

  4. Enum-like Types: Use TypeScript union types for enums (e.g., type ViewType = 'list' | 'kanban' | ...)

  5. Optional AI Context: All main configs include optional ai_context for AI-assisted generation

Integration Points

// Object definition references validation
interface ObjectConfig {
  validation?: {
    rules?: AnyValidationRule[];
  };
}

// View references filters (similar to validation conditions)
interface ViewFilter {
  field: string;
  operator: ValidationOperator;
  value?: any;
}

// Workflow references validation conditions
interface WorkflowTrigger {
  conditions?: ValidationCondition[];
}

// Form uses field config for overrides
interface FormField {
  name: string;
  // ... can override FieldConfig properties
}

File Structure

packages/foundation/types/src/
├── index.ts              # Exports all types (updated)
├── view.ts              # NEW: View type definitions
├── workflow.ts          # NEW: Workflow type definitions
├── report.ts            # NEW: Report type definitions
├── form.ts              # NEW: Form type definitions
├── object.ts            # Existing
├── validation.ts        # Existing
├── permission.ts        # Existing
├── field.ts             # Existing
└── ... (other existing files)

Metadata Coverage

Metadata Type File Pattern TypeScript Type Status
Object *.object.yml ObjectConfig ✅ Existing
Validation *.validation.yml ValidationConfig ✅ Existing
Permission *.permission.yml PermissionConfig ✅ Existing
Hook *.hook.ts ObjectHookDefinition ✅ Existing
Action *.action.ts ActionConfig ✅ Existing
Page *.page.yml PageConfig ✅ Existing
Menu *.menu.yml MenuConfig ✅ Existing
App *.app.yml AppConfig ✅ Existing
Migration *.migration.yml MigrationConfig ✅ Existing
View *.view.yml ViewConfig ✅ NEW
Workflow *.workflow.yml WorkflowConfig ✅ NEW
Report *.report.yml ReportConfig ✅ NEW
Form *.form.yml FormConfig ✅ NEW

Result: 100% metadata type coverage achieved! 🎉

Build Verification

cd packages/foundation/types
npm run build
# ✓ TypeScript compilation successful
# ✓ All .d.ts files generated
# ✓ Types exported from index.ts

Compiled outputs:

  • dist/view.d.ts (8.5KB) + dist/view.js
  • dist/workflow.d.ts (11KB) + dist/workflow.js
  • dist/report.d.ts (7.9KB) + dist/report.js
  • dist/form.d.ts (8.7KB) + dist/form.js

Usage Examples

Using View Types in TypeScript

import { ViewConfig, ViewType } from '@objectql/types';

const userListView: ViewConfig = {
  name: 'active_users',
  label: 'Active Users',
  object: 'users',
  type: 'list',
  columns: [
    { field: 'name', width: 200, sortable: true },
    { field: 'email', width: 250, sortable: true },
    { field: 'status', width: 120, badge: true }
  ],
  filters: [
    { field: 'status', operator: '=', value: 'active' }
  ],
  enable_search: true,
  enable_export: true
};

Using Workflow Types in TypeScript

import { WorkflowConfig, WorkflowType } from '@objectql/types';

const approvalWorkflow: WorkflowConfig = {
  name: 'expense_approval',
  label: 'Expense Approval',
  type: 'approval',
  object: 'expenses',
  trigger: {
    event: 'create',
    conditions: [
      { field: 'amount', operator: '>', value: 1000 }
    ]
  },
  steps: [
    {
      name: 'manager_approval',
      type: 'approval',
      assignee: { type: 'field', field: 'manager_id' },
      actions: {
        approve: { label: 'Approve', outcome: 'approved' },
        reject: { label: 'Reject', outcome: 'rejected' }
      }
    }
  ]
};

Using Report Types in TypeScript

import { ReportConfig, ChartType } from '@objectql/types';

const salesReport: ReportConfig = {
  name: 'monthly_sales',
  label: 'Monthly Sales Report',
  type: 'summary',
  object: 'orders',
  groupings: [
    { field: 'status', label: 'Order Status' }
  ],
  aggregations: [
    { field: 'total', function: 'sum', label: 'Total Revenue' },
    { field: '_id', function: 'count', label: 'Order Count' }
  ],
  chart: {
    type: 'bar',
    x_axis: 'status',
    y_axis: 'total',
    show_legend: true
  }
};

Using Form Types in TypeScript

import { FormConfig, FormType } from '@objectql/types';

const userForm: FormConfig = {
  name: 'user_create_form',
  label: 'Create User',
  type: 'create',
  object: 'users',
  layout: 'two_column',
  sections: [
    {
      label: 'User Information',
      columns: 2,
      fields: [
        { name: 'name', required: true },
        { name: 'email', required: true },
        { name: 'phone' },
        { name: 'role', required: true }
      ]
    }
  ],
  actions: [
    { name: 'save', label: 'Save', type: 'submit', variant: 'primary' },
    { name: 'cancel', label: 'Cancel', type: 'cancel', variant: 'secondary' }
  ]
};

Benefits

  1. Type Safety: Full TypeScript support for all metadata formats
  2. IDE Support: IntelliSense, auto-completion, and inline documentation
  3. Validation: Catch errors at compile-time instead of runtime
  4. Consistency: Unified type system across the entire ObjectQL ecosystem
  5. Documentation: Types serve as living documentation
  6. AI-Friendly: Comprehensive types enable better AI code generation

Future Enhancements

The type system is designed to be extensible. Potential additions:

  • Dashboard layout types (composition of multiple pages/widgets)
  • Integration types (external API configurations)
  • Theme/styling types (UI customization metadata)
  • Deployment types (environment configurations)

Implementation Date: January 14-15, 2026
Author: ObjectQL Lead Architect
Package: @objectql/types@1.8.4