@objectql/types 1.8.2 → 1.8.4

package/dist/migration.d.ts

@@ -0,0 +1,327 @@
+import { FieldConfig } from './field';
+/**
+ * Represents the type of schema change operation.
+ */
+export type SchemaChangeType = 'field_update' | 'field_delete' | 'object_update' | 'object_delete';
+/**
+ * Base interface for all schema change instructions.
+ */
+export interface BaseSchemaChangeInstruction {
+    /** Type of schema change operation */
+    type: SchemaChangeType;
+    /** Human-readable description of the change */
+    description?: string;
+    /** Reason for the change (for audit trail) */
+    reason?: string;
+    /** Timestamp when the change was defined (ISO 8601) */
+    timestamp?: string;
+    /** Author of the change (username or ID) */
+    author?: string;
+}
+/**
+ * Database impact assessment for a field change.
+ * Describes how the change affects the underlying database schema.
+ */
+export interface DatabaseImpact {
+    /**
+     * Type of database operation required.
+     * - 'alter_column': Modify column properties (type, constraints, default)
+     * - 'rename_column': Rename a column
+     * - 'drop_column': Remove a column
+     * - 'add_column': Add a new column
+     * - 'rebuild_table': Requires full table rebuild (complex changes)
+     * - 'no_change': Schema-level only, no database changes
+     */
+    operation: 'alter_column' | 'rename_column' | 'drop_column' | 'add_column' | 'rebuild_table' | 'no_change';
+    /**
+     * Whether this change requires data migration.
+     * If true, existing records must be updated.
+     */
+    requires_data_migration: boolean;
+    /**
+     * Whether this change may cause data loss.
+     * Examples: type narrowing, dropping columns, shortening text length
+     */
+    may_cause_data_loss: boolean;
+    /**
+     * Estimated risk level for this change.
+     * - 'low': Safe, reversible change (e.g., adding nullable field)
+     * - 'medium': May affect queries or require downtime (e.g., adding index)
+     * - 'high': Requires careful planning (e.g., type change with data migration)
+     * - 'critical': May cause data loss or extended downtime (e.g., dropping column)
+     */
+    risk_level?: 'low' | 'medium' | 'high' | 'critical';
+    /**
+     * Expected downtime for this change.
+     * Format: ISO 8601 duration (e.g., 'PT5M' for 5 minutes, 'PT2H' for 2 hours)
+     */
+    estimated_downtime?: string;
+    /**
+     * Notes about the database impact for human review.
+     */
+    notes?: string;
+}
+/**
+ * Database upgrade script information.
+ * Contains the generated DDL/DML statements for applying the migration.
+ */
+export interface UpgradeScript {
+    /**
+     * Target database dialect.
+     * Examples: 'postgresql', 'mysql', 'sqlite', 'mongodb', 'mssql'
+     */
+    dialect: string;
+    /**
+     * SQL or database-specific statements to apply the change (forward migration).
+     * For SQL: DDL statements (ALTER TABLE, CREATE INDEX, etc.)
+     * For MongoDB: Update operations
+     */
+    up_statements: string[];
+    /**
+     * SQL or database-specific statements to rollback the change (reverse migration).
+     * Only present if the change is reversible.
+     */
+    down_statements?: string[];
+    /**
+     * Pre-migration checks or validations to run before applying changes.
+     * Examples: Check for data integrity, verify no duplicate values before adding UNIQUE constraint
+     */
+    pre_checks?: string[];
+    /**
+     * Post-migration validations to ensure the change was successful.
+     * Examples: Verify column exists, check data was migrated correctly
+     */
+    post_checks?: string[];
+    /**
+     * Estimated execution time for this script.
+     * Format: ISO 8601 duration
+     */
+    estimated_execution_time?: string;
+}
+/**
+ * Instruction to update (modify) a field in an object.
+ * Can rename, change type, or update properties of an existing field.
+ */
+export interface FieldUpdateInstruction extends BaseSchemaChangeInstruction {
+    type: 'field_update';
+    /** Name of the object containing the field */
+    object_name: string;
+    /** Current name of the field to update */
+    field_name: string;
+    /** New name for the field (if renaming) */
+    new_field_name?: string;
+    /** Updated field configuration (partial) */
+    changes: Partial<FieldConfig>;
+    /**
+     * Strategy for handling existing data during type changes.
+     * - 'auto': Attempt automatic conversion
+     * - 'manual': Requires custom data migration script
+     * - 'preserve': Keep data as-is (may cause validation errors)
+     * - 'clear': Set field to null/default for all existing records
+     */
+    data_migration_strategy?: 'auto' | 'manual' | 'preserve' | 'clear';
+    /**
+     * Custom data transformation function (for manual strategy).
+     * Should be a valid JavaScript expression or function body.
+     */
+    transform_script?: string;
+    /**
+     * Database impact assessment for this field change.
+     * Describes the effect on the underlying database schema.
+     */
+    database_impact?: DatabaseImpact;
+    /**
+     * Generated upgrade scripts for different database dialects.
+     * Maps dialect name to upgrade script.
+     * Example: { postgresql: {...}, mysql: {...} }
+     */
+    upgrade_scripts?: Record<string, UpgradeScript>;
+}
+/**
+ * Instruction to delete (remove) a field from an object.
+ */
+export interface FieldDeleteInstruction extends BaseSchemaChangeInstruction {
+    type: 'field_delete';
+    /** Name of the object containing the field */
+    object_name: string;
+    /** Name of the field to delete */
+    field_name: string;
+    /**
+     * Strategy for handling existing data in the field.
+     * - 'drop': Remove the field and its data (irreversible)
+     * - 'archive': Move data to an archive/backup location
+     * - 'soft': Mark as deleted but keep data (for rollback)
+     */
+    deletion_strategy?: 'drop' | 'archive' | 'soft';
+    /** Backup location if using 'archive' strategy */
+    archive_location?: string;
+    /**
+     * Database impact assessment for this field deletion.
+     * Describes the effect on the underlying database schema.
+     */
+    database_impact?: DatabaseImpact;
+    /**
+     * Generated upgrade scripts for different database dialects.
+     * Maps dialect name to upgrade script.
+     * Example: { postgresql: {...}, mysql: {...} }
+     */
+    upgrade_scripts?: Record<string, UpgradeScript>;
+}
+/**
+ * Configuration changes that can be applied to an object.
+ * Used by ObjectUpdateInstruction to modify object metadata.
+ */
+export interface ObjectUpdateChanges {
+    /** Updated human-readable label */
+    label?: string;
+    /** Updated icon string */
+    icon?: string;
+    /** Updated description */
+    description?: string;
+    /** Updated datasource name */
+    datasource?: string;
+}
+/**
+ * Instruction to update (modify) an object definition.
+ * Can rename or change properties of an existing object.
+ */
+export interface ObjectUpdateInstruction extends BaseSchemaChangeInstruction {
+    type: 'object_update';
+    /** Current name of the object to update */
+    object_name: string;
+    /** New name for the object (if renaming) */
+    new_object_name?: string;
+    /** Updated properties (label, description, icon, etc.) */
+    changes: ObjectUpdateChanges;
+    /**
+     * Database impact assessment for this object change.
+     * Describes the effect on the underlying database schema.
+     */
+    database_impact?: DatabaseImpact;
+    /**
+     * Generated upgrade scripts for different database dialects.
+     * Maps dialect name to upgrade script.
+     * Example: { postgresql: {...}, mysql: {...} }
+     */
+    upgrade_scripts?: Record<string, UpgradeScript>;
+}
+/**
+ * Instruction to delete (remove) an entire object.
+ */
+export interface ObjectDeleteInstruction extends BaseSchemaChangeInstruction {
+    type: 'object_delete';
+    /** Name of the object to delete */
+    object_name: string;
+    /**
+     * Strategy for handling existing data in the object.
+     * - 'drop': Remove the object and all its data (irreversible)
+     * - 'archive': Move all data to an archive/backup location
+     * - 'soft': Mark as deleted but keep data (for rollback)
+     */
+    deletion_strategy?: 'drop' | 'archive' | 'soft';
+    /** Backup location if using 'archive' strategy */
+    archive_location?: string;
+    /**
+     * Handle dependent objects/relationships.
+     * - 'cascade': Also delete related records in other objects
+     * - 'fail': Fail if there are dependent records
+     * - 'nullify': Set foreign key references to null
+     */
+    cascade_strategy?: 'cascade' | 'fail' | 'nullify';
+    /**
+     * Database impact assessment for this object deletion.
+     * Describes the effect on the underlying database schema.
+     */
+    database_impact?: DatabaseImpact;
+    /**
+     * Generated upgrade scripts for different database dialects.
+     * Maps dialect name to upgrade script.
+     * Example: { postgresql: {...}, mysql: {...} }
+     */
+    upgrade_scripts?: Record<string, UpgradeScript>;
+}
+/**
+ * Union type for all schema change instructions.
+ */
+export type SchemaChangeInstruction = FieldUpdateInstruction | FieldDeleteInstruction | ObjectUpdateInstruction | ObjectDeleteInstruction;
+/**
+ * Represents a single migration step in a migration sequence.
+ */
+export interface MigrationStep {
+    /** Unique identifier for this step */
+    id: string;
+    /** Human-readable name for this step */
+    name: string;
+    /** Description of what this step does */
+    description?: string;
+    /** Schema change instruction to execute */
+    instruction: SchemaChangeInstruction;
+    /**
+     * Whether this step can be automatically rolled back.
+     * Default: true
+     */
+    reversible?: boolean;
+    /**
+     * Optional rollback instruction (if different from automatic inverse).
+     */
+    rollback_instruction?: SchemaChangeInstruction;
+    /**
+     * Dependencies on other migration steps (by step ID).
+     * This step will only execute after dependencies are complete.
+     */
+    depends_on?: string[];
+}
+/**
+ * Configuration for a complete migration.
+ * Groups multiple schema changes into a versioned migration.
+ */
+export interface MigrationConfig {
+    /** Unique identifier for this migration (e.g., 'v1.0_add_user_fields') */
+    id: string;
+    /** Semantic version number (e.g., '1.2.0') */
+    version: string;
+    /** Human-readable name for this migration */
+    name: string;
+    /** Detailed description of the migration purpose */
+    description?: string;
+    /** Author of the migration */
+    author?: string;
+    /** Timestamp when the migration was created (ISO 8601) */
+    created_at?: string;
+    /** Ordered list of migration steps to execute */
+    steps: MigrationStep[];
+    /**
+     * Whether this migration can be automatically rolled back.
+     * Default: true if all steps are reversible
+     */
+    reversible?: boolean;
+    /**
+     * Dependencies on other migrations (by migration ID).
+     * This migration will only run after dependencies are applied.
+     */
+    depends_on?: string[];
+    /**
+     * Tags for categorization and filtering.
+     * Examples: ['schema', 'data', 'hotfix', 'feature']
+     */
+    tags?: string[];
+}
+/**
+ * Represents the execution status of a migration.
+ */
+export interface MigrationStatus {
+    /** Migration ID */
+    migration_id: string;
+    /** Execution status */
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'rolled_back';
+    /** Timestamp when execution started */
+    started_at?: string;
+    /** Timestamp when execution completed */
+    completed_at?: string;
+    /** Error message if failed */
+    error?: string;
+    /** Number of steps completed */
+    steps_completed?: number;
+    /** Total number of steps */
+    steps_total?: number;
+}

package/dist/migration.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=migration.js.map

package/dist/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.js","sourceRoot":"","sources":["../src/migration.ts"],"names":[],"mappings":""}

package/dist/report.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Report Metadata Definition
+ *
+ * Defines the structure for reports, data summaries, and analytics in ObjectQL.
+ * Reports aggregate and visualize data from objects with grouping, filtering, and calculations.
+ *
+ * Based on patterns from Salesforce Reports, Tableau, and similar BI platforms.
+ */
+import { ViewFilter, ViewFilterGroup, ViewColumn } from './view';
+/**
+ * Types of reports supported by ObjectQL
+ */
+export type ReportType = 'tabular' | 'summary' | 'matrix' | 'chart' | 'dashboard' | 'custom';
+/**
+ * Chart types for visualization
+ */
+export type ChartType = 'bar' | 'column' | 'line' | 'area' | 'pie' | 'donut' | 'scatter' | 'bubble' | 'funnel' | 'gauge' | 'radar' | 'heatmap' | 'treemap' | 'waterfall' | 'custom';
+/**
+ * Aggregation functions for report calculations
+ */
+export type AggregationFunction = 'count' | 'sum' | 'avg' | 'min' | 'max' | 'median' | 'mode' | 'stddev' | 'variance' | 'distinct_count' | 'first' | 'last' | 'custom';
+/**
+ * Grouping configuration for reports
+ */
+export interface ReportGrouping {
+    /** Field to group by */
+    field: string;
+    /** Display label */
+    label?: string;
+    /** Sort order for groups */
+    sort?: 'asc' | 'desc';
+    /** Group by date interval (for date fields) */
+    date_interval?: 'day' | 'week' | 'month' | 'quarter' | 'year';
+    /** Group by numeric range (for numeric fields) */
+    numeric_range?: {
+        /** Range size */
+        size: number;
+        /** Starting value */
+        start?: number;
+    };
+    /** Show subtotals for this grouping */
+    show_subtotals?: boolean;
+    /** Limit number of groups */
+    limit?: number;
+}
+/**
+ * Aggregation/calculation configuration
+ */
+export interface ReportAggregation {
+    /** Field to aggregate */
+    field: string;
+    /** Aggregation function */
+    function: AggregationFunction;
+    /** Display label */
+    label?: string;
+    /** Display format */
+    format?: string;
+    /** Custom aggregation expression */
+    expression?: string;
+    /** Show in totals row */
+    show_in_total?: boolean;
+}
+/**
+ * Formula field for calculated columns
+ */
+export interface ReportFormula {
+    /** Formula name */
+    name: string;
+    /** Display label */
+    label?: string;
+    /** Formula expression */
+    expression: string;
+    /** Data type of result */
+    type?: 'number' | 'text' | 'date' | 'boolean';
+    /** Display format */
+    format?: string;
+    /** Description of what this formula calculates */
+    description?: string;
+}
+/**
+ * Chart configuration for report visualization
+ */
+export interface ReportChartConfig {
+    /** Chart type */
+    type: ChartType;
+    /** Chart title */
+    title?: string;
+    /** Field for X-axis */
+    x_axis?: string;
+    /** Field(s) for Y-axis */
+    y_axis?: string | string[];
+    /** Field for chart series/legend */
+    series_field?: string;
+    /** Chart colors */
+    colors?: string[];
+    /** Show legend */
+    show_legend?: boolean;
+    /** Legend position */
+    legend_position?: 'top' | 'bottom' | 'left' | 'right';
+    /** Show data labels */
+    show_data_labels?: boolean;
+    /** Chart height in pixels */
+    height?: number;
+    /** Chart width in pixels */
+    width?: number;
+    /** Enable drill-down */
+    enable_drill_down?: boolean;
+    /** Custom chart configuration */
+    custom_config?: Record<string, any>;
+}
+/**
+ * Matrix report dimension configuration
+ */
+export interface MatrixDimension {
+    /** Field for this dimension */
+    field: string;
+    /** Display label */
+    label?: string;
+    /** Sort order */
+    sort?: 'asc' | 'desc';
+    /** Show totals */
+    show_totals?: boolean;
+}
+/**
+ * Export configuration for reports
+ */
+export interface ReportExportConfig {
+    /** Enabled export formats */
+    formats?: ('pdf' | 'xlsx' | 'csv' | 'json' | 'html')[];
+    /** Include charts in export */
+    include_charts?: boolean;
+    /** Export filename template */
+    filename_template?: string;
+    /** Page orientation for PDF */
+    page_orientation?: 'portrait' | 'landscape';
+    /** Paper size for PDF */
+    paper_size?: 'A4' | 'Letter' | 'Legal';
+}
+/**
+ * Scheduling configuration for automated reports
+ */
+export interface ReportScheduleConfig {
+    /** Enable scheduled execution */
+    enabled: boolean;
+    /** Cron expression for schedule */
+    cron?: string;
+    /** Timezone for schedule */
+    timezone?: string;
+    /** Email recipients for scheduled reports */
+    recipients?: string[];
+    /** Email subject template */
+    email_subject?: string;
+    /** Email body template */
+    email_body?: string;
+    /** Export format for scheduled report */
+    format?: 'pdf' | 'xlsx' | 'csv';
+}
+/**
+ * Complete report configuration
+ */
+export interface ReportConfig {
+    /** Unique report identifier */
+    name: string;
+    /** Display label */
+    label: string;
+    /** Report type */
+    type: ReportType;
+    /** Primary object for the report */
+    object: string;
+    /** Report description */
+    description?: string;
+    /** Icon for the report */
+    icon?: string;
+    /** Columns to display */
+    columns?: ViewColumn[];
+    /** Filters to apply */
+    filters?: (ViewFilter | ViewFilterGroup)[];
+    /** Grouping configuration */
+    groupings?: ReportGrouping[];
+    /** Aggregations/calculations */
+    aggregations?: ReportAggregation[];
+    /** Formula fields */
+    formulas?: ReportFormula[];
+    /** Chart configuration */
+    chart?: ReportChartConfig;
+    /** Matrix report row dimension */
+    row_dimension?: MatrixDimension;
+    /** Matrix report column dimension */
+    column_dimension?: MatrixDimension;
+    /** Limit number of rows */
+    limit?: number;
+    /** Enable drill-down to records */
+    enable_drill_down?: boolean;
+    /** Show record count */
+    show_record_count?: boolean;
+    /** Show grand totals */
+    show_grand_total?: boolean;
+    /** Export configuration */
+    export?: ReportExportConfig;
+    /** Scheduling configuration */
+    schedule?: ReportScheduleConfig;
+    /** Cache configuration */
+    cache?: {
+        /** Enable caching */
+        enabled?: boolean;
+        /** Cache duration in seconds */
+        duration?: number;
+    };
+    /** Access control */
+    permissions?: {
+        /** Roles that can view this report */
+        view?: string[];
+        /** Roles that can edit report configuration */
+        edit?: string[];
+        /** Roles that can export */
+        export?: string[];
+    };
+    /** Whether this report is shared with all users */
+    is_public?: boolean;
+    /** Owner of the report (for personal reports) */
+    owner?: string;
+    /** Folder/category for organization */
+    folder?: string;
+    /** Custom report configuration */
+    config?: Record<string, any>;
+    /** AI context for report generation */
+    ai_context?: {
+        /** Business question this report answers */
+        intent?: string;
+        /** Target audience */
+        audience?: string;
+        /** Key insights to highlight */
+        insights?: string[];
+        /** Recommended visualizations */
+        visualizations?: string[];
+    };
+}
+/**
+ * Report execution result
+ */
+export interface ReportResult {
+    /** Report name */
+    report_name: string;
+    /** Execution timestamp */
+    executed_at: string;
+    /** Data rows */
+    rows: any[];
+    /** Total record count */
+    total_count: number;
+    /** Aggregation results */
+    aggregations?: Record<string, any>;
+    /** Grand totals */
+    grand_total?: Record<string, any>;
+    /** Chart data */
+    chart_data?: any;
+    /** Execution time in milliseconds */
+    execution_time?: number;
+    /** Whether result was from cache */
+    from_cache?: boolean;
+}
+/**
+ * Lightweight report reference
+ * Used in navigation, dropdowns, and report selectors
+ */
+export interface ReportReference {
+    /** Report name/identifier */
+    name: string;
+    /** Display label */
+    label?: string;
+    /** Icon */
+    icon?: string;
+    /** Report type */
+    type?: ReportType;
+    /** Folder/category */
+    folder?: string;
+}

package/dist/report.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Report Metadata Definition
+ *
+ * Defines the structure for reports, data summaries, and analytics in ObjectQL.
+ * Reports aggregate and visualize data from objects with grouping, filtering, and calculations.
+ *
+ * Based on patterns from Salesforce Reports, Tableau, and similar BI platforms.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG"}