Skip to content

METADATA_TYPES_IMPLEMENTATION.md

Latest commit

 

History

History
457 lines (383 loc) · 12.2 KB

METADATA_TYPES_IMPLEMENTATION.md

File metadata and controls

457 lines (383 loc) · 12.2 KB

Metadata Type Definitions - Implementation Summary

Overview

This PR implements complete TypeScript type definitions for all ObjectQL metadata formats. Previously, only some metadata types (Object, Validation, Permission, etc.) had TypeScript definitions. This implementation adds the missing types to achieve 100% coverage.

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