@objectql/types 1.8.2 → 1.8.3

package/README.md

@@ -66,6 +66,17 @@ npm install @objectql/types
 - `Driver` - Database driver interface
 - `DriverConfig` - Driver configuration
 
+### Migration & Schema Evolution Types
+- `SchemaChangeType` - Types of schema change operations
+- `SchemaChangeInstruction` - Union of all schema change instructions
+- `FieldUpdateInstruction` - Instruction to update/modify a field
+- `FieldDeleteInstruction` - Instruction to delete/remove a field
+- `ObjectUpdateInstruction` - Instruction to update/modify an object
+- `ObjectDeleteInstruction` - Instruction to delete/remove an object
+- `MigrationConfig` - Complete migration configuration
+- `MigrationStep` - Single step in a migration
+- `MigrationStatus` - Execution status of a migration
+
 ## Usage Examples
 
 ### Object Definition with Validation
@@ -253,6 +264,128 @@ interface FieldValidation {
 }
 ```
 
+### Migration & Schema Evolution
+
+Define schema changes declaratively for object and field updates/deletions:
+
+```typescript
+import { 
+    MigrationConfig, 
+    FieldUpdateInstruction, 
+    FieldDeleteInstruction,
+    ObjectUpdateInstruction,
+    ObjectDeleteInstruction 
+} from '@objectql/types';
+
+// Define a migration with multiple schema changes
+const migration: MigrationConfig = {
+    id: 'v1.2_refactor_user_fields',
+    version: '1.2.0',
+    name: 'Refactor User Fields',
+    description: 'Update user object schema and remove deprecated fields',
+    author: 'dev-team',
+    created_at: '2026-01-14T00:00:00Z',
+    steps: [
+        {
+            id: 'rename_username_field',
+            name: 'Rename username to user_name',
+            instruction: {
+                type: 'field_update',
+                object_name: 'users',
+                field_name: 'username',
+                new_field_name: 'user_name',
+                changes: {
+                    label: 'User Name',
+                    description: 'Updated field name for consistency'
+                },
+                data_migration_strategy: 'auto'
+            } as FieldUpdateInstruction,
+            reversible: true
+        },
+        {
+            id: 'update_email_field',
+            name: 'Make email field required',
+            instruction: {
+                type: 'field_update',
+                object_name: 'users',
+                field_name: 'email',
+                changes: {
+                    required: true,
+                    unique: true
+                },
+                data_migration_strategy: 'auto'
+            } as FieldUpdateInstruction,
+            reversible: true
+        },
+        {
+            id: 'delete_legacy_field',
+            name: 'Remove deprecated legacy_id field',
+            instruction: {
+                type: 'field_delete',
+                object_name: 'users',
+                field_name: 'legacy_id',
+                deletion_strategy: 'archive',
+                archive_location: 'backup/users_legacy_id'
+            } as FieldDeleteInstruction,
+            reversible: true
+        },
+        {
+            id: 'update_object_label',
+            name: 'Update Users object label',
+            instruction: {
+                type: 'object_update',
+                object_name: 'users',
+                changes: {
+                    label: 'System Users',
+                    description: 'Updated to reflect new naming convention'
+                }
+            } as ObjectUpdateInstruction,
+            reversible: true
+        }
+    ],
+    reversible: true,
+    tags: ['schema', 'refactor']
+};
+```
+
+**Field Update Example (Type Change):**
+
+```typescript
+const changeFieldType: FieldUpdateInstruction = {
+    type: 'field_update',
+    object_name: 'products',
+    field_name: 'price',
+    changes: {
+        type: 'currency',  // Changed from 'number' to 'currency'
+        defaultValue: 0
+    },
+    data_migration_strategy: 'manual',
+    transform_script: `
+        // Custom transformation for price field
+        return {
+            amount: oldValue,
+            currency: 'USD'
+        };
+    `,
+    description: 'Convert price from number to currency type',
+    reason: 'Support multi-currency pricing'
+};
+```
+
+**Object Deletion Example:**
+
+```typescript
+const deleteObject: ObjectDeleteInstruction = {
+    type: 'object_delete',
+    object_name: 'temp_imports',
+    deletion_strategy: 'archive',
+    archive_location: 'backups/temp_imports_archive',
+    cascade_strategy: 'nullify',
+    description: 'Remove temporary import table',
+    reason: 'No longer needed after migration to new import system'
+};
+```
+
 ## See Also
 
 - [@objectql/core](../core) - Core engine with Validator class

package/dist/app.d.ts

@@ -8,6 +8,7 @@ export interface IObjectQL {
     getConfigs(): Record<string, ObjectConfig>;
     datasource(name: string): Driver;
     init(): Promise<void>;
+    close?(): Promise<void>;
     removePackage(name: string): void;
     metadata: MetadataRegistry;
     registerObject(object: ObjectConfig): void;

package/dist/index.d.ts

@@ -16,4 +16,5 @@ export * from './page';
 export * from './loader';
 export * from './application';
 export * from './menu';
+export * from './migration';
 export * from './api';

package/dist/index.js

@@ -32,5 +32,6 @@ __exportStar(require("./page"), exports);
 __exportStar(require("./loader"), exports);
 __exportStar(require("./application"), exports);
 __exportStar(require("./menu"), exports);
+__exportStar(require("./migration"), exports);
 __exportStar(require("./api"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,2CAAyB;AACzB,2CAAyB;AACzB,0CAAwB;AACxB,6CAA2B;AAC3B,yCAAuB;AACvB,2CAAyB;AACzB,+CAA6B;AAC7B,wCAAsB;AACtB,2CAAyB;AACzB,2CAAyB;AACzB,4CAA0B;AAC1B,+CAA6B;AAC7B,+CAA6B;AAC7B,yCAAuB;AACvB,2CAAyB;AACzB,gDAA8B;AAC9B,yCAAuB;AACvB,wCAAsB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,2CAAyB;AACzB,2CAAyB;AACzB,0CAAwB;AACxB,6CAA2B;AAC3B,yCAAuB;AACvB,2CAAyB;AACzB,+CAA6B;AAC7B,wCAAsB;AACtB,2CAAyB;AACzB,2CAAyB;AACzB,4CAA0B;AAC1B,+CAA6B;AAC7B,+CAA6B;AAC7B,yCAAuB;AACvB,2CAAyB;AACzB,gDAA8B;AAC9B,yCAAuB;AACvB,8CAA4B;AAC5B,wCAAsB"}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectql/types",
-  "version": "1.8.2",
+  "version": "1.8.3",
   "description": "Pure TypeScript type definitions and interfaces for the ObjectQL protocol - The Contract",
   "keywords": [
     "objectql",