@objectql/types 1.8.1 → 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/api.d.ts

@@ -0,0 +1,427 @@
+/**
+ * API Type Definitions for ObjectQL
+ *
+ * This file contains TypeScript interfaces for Data API and Metadata API endpoints.
+ * These types enable frontend applications to make type-safe API calls.
+ */
+import { UnifiedQuery, FilterExpression } from './query';
+import { ObjectConfig } from './object';
+import { FieldConfig } from './field';
+import { ActionConfig } from './action';
+/**
+ * Standardized error codes for ObjectQL API responses
+ */
+export declare enum ApiErrorCode {
+    INVALID_REQUEST = "INVALID_REQUEST",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    UNAUTHORIZED = "UNAUTHORIZED",
+    FORBIDDEN = "FORBIDDEN",
+    NOT_FOUND = "NOT_FOUND",
+    CONFLICT = "CONFLICT",
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    DATABASE_ERROR = "DATABASE_ERROR",
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
+}
+/**
+ * Error details structure with optional field-specific information
+ */
+export interface ApiErrorDetails {
+    field?: string;
+    reason?: string;
+    fields?: Record<string, string>;
+    required_permission?: string;
+    user_roles?: string[];
+    retry_after?: number;
+    [key: string]: unknown;
+}
+/**
+ * Standard error response structure
+ */
+export interface ApiError {
+    code: ApiErrorCode | string;
+    message: string;
+    details?: ApiErrorDetails;
+}
+/**
+ * ObjectQL Error class for throwing structured errors
+ */
+export declare class ObjectQLError extends Error {
+    code: ApiErrorCode | string;
+    details?: ApiErrorDetails;
+    constructor(error: {
+        code: ApiErrorCode | string;
+        message: string;
+        details?: ApiErrorDetails;
+    });
+}
+/**
+ * Pagination metadata for list responses
+ */
+export interface PaginationMeta {
+    /** Total number of records */
+    total: number;
+    /** Current page number (1-indexed) */
+    page?: number;
+    /** Number of items per page */
+    size?: number;
+    /** Total number of pages */
+    pages?: number;
+    /** Whether there is a next page */
+    has_next?: boolean;
+}
+/**
+ * Base response structure for Data API operations
+ */
+export interface DataApiResponse<T = unknown> {
+    /** Error information if the operation failed */
+    error?: ApiError;
+    /** Additional response fields for successful operations */
+    [key: string]: unknown;
+}
+/**
+ * Response for list operations (find)
+ */
+export interface DataApiListResponse<T = unknown> extends DataApiResponse<T> {
+    /** Array of retrieved items */
+    items?: T[];
+    /** Pagination metadata */
+    meta?: PaginationMeta;
+}
+/**
+ * Response for single item operations (findOne, create, update)
+ */
+export interface DataApiItemResponse<T = unknown> extends DataApiResponse<T> {
+    /** The item ID */
+    _id?: string | number;
+    /** Object type identifier */
+    '@type'?: string;
+    /** Timestamp when created */
+    created_at?: string | Date;
+    /** Timestamp when last updated */
+    updated_at?: string | Date;
+}
+/**
+ * Query parameters for GET /api/data/:object (list records)
+ */
+export interface DataApiListParams {
+    /** Filter expression (can be FilterExpression array or JSON string) */
+    filter?: FilterExpression | string;
+    /** Fields to return (array or comma-separated string) */
+    fields?: string[] | string;
+    /** Sort criteria - array of [field, direction] tuples */
+    sort?: [string, 'asc' | 'desc'][] | string;
+    /** Maximum number of records to return */
+    limit?: number;
+    /** Number of records to skip (for pagination) */
+    skip?: number;
+    /** Offset alias for skip */
+    offset?: number;
+    /** OData-style top parameter (alias for limit) */
+    top?: number;
+    /** Expand related records */
+    expand?: Record<string, UnifiedQuery>;
+}
+/**
+ * Request body for POST /api/data/:object (create single record)
+ */
+export interface DataApiCreateRequest {
+    [key: string]: unknown;
+}
+/**
+ * Request body for POST /api/data/:object (create multiple records)
+ */
+export type DataApiCreateManyRequest = Array<Record<string, unknown>>;
+/**
+ * Request body for PUT /api/data/:object/:id (update record)
+ */
+export interface DataApiUpdateRequest {
+    [key: string]: unknown;
+}
+/**
+ * Request body for POST /api/data/:object/bulk-update (update many records)
+ */
+export interface DataApiBulkUpdateRequest {
+    /** Filter criteria to select records to update */
+    filters: FilterExpression;
+    /** Data to update */
+    data: Record<string, unknown>;
+}
+/**
+ * Request body for POST /api/data/:object/bulk-delete (delete many records)
+ */
+export interface DataApiBulkDeleteRequest {
+    /** Filter criteria to select records to delete */
+    filters: FilterExpression;
+}
+/**
+ * Response for count operations
+ */
+export interface DataApiCountResponse extends DataApiResponse {
+    /** Number of records matching the criteria */
+    count?: number;
+}
+/**
+ * Response for delete operations
+ */
+export interface DataApiDeleteResponse extends DataApiResponse {
+    /** Whether the operation was successful */
+    success?: boolean;
+    /** Number of deleted records (for bulk operations) */
+    deleted_count?: number;
+}
+/**
+ * Base response structure for Metadata API operations
+ */
+export interface MetadataApiResponse<T = unknown> {
+    /** Error information if the operation failed */
+    error?: ApiError;
+    /** Additional response fields */
+    [key: string]: unknown;
+}
+/**
+ * Response for list metadata operations
+ */
+export interface MetadataApiListResponse<T = unknown> extends MetadataApiResponse<T> {
+    /** Array of metadata items */
+    items: T[];
+}
+/**
+ * Simplified object metadata for list views
+ */
+export interface ObjectMetadataSummary {
+    /** Object name (internal identifier) */
+    name: string;
+    /** Display label */
+    label?: string;
+    /** Icon identifier */
+    icon?: string;
+    /** Object description */
+    description?: string;
+    /** Field definitions (simplified) */
+    fields?: Record<string, FieldConfig>;
+}
+/**
+ * Detailed object metadata for single object view
+ */
+export interface ObjectMetadataDetail extends ObjectConfig {
+    /** Formatted fields with name property populated */
+    fields: Record<string, FieldConfig & {
+        name: string;
+    }>;
+}
+/**
+ * Response for GET /api/metadata/objects (list all objects)
+ */
+export interface MetadataApiObjectListResponse extends MetadataApiListResponse<ObjectMetadataSummary> {
+    items: ObjectMetadataSummary[];
+}
+/**
+ * Response for GET /api/metadata/object/:name (get single object)
+ */
+export interface MetadataApiObjectDetailResponse extends MetadataApiResponse<ObjectMetadataDetail> {
+    /** Object name */
+    name: string;
+    /** Display label */
+    label?: string;
+    /** Icon identifier */
+    icon?: string;
+    /** Description */
+    description?: string;
+    /** Field definitions with populated names */
+    fields: Record<string, FieldConfig & {
+        name: string;
+    }>;
+    /** Available actions */
+    actions?: Record<string, ActionConfig>;
+    /** Validation rules */
+    validation?: ObjectConfig['validation'];
+    /** AI configuration */
+    ai?: ObjectConfig['ai'];
+}
+/**
+ * Field metadata response
+ */
+export interface FieldMetadataResponse extends MetadataApiResponse<FieldConfig> {
+    /** Field name */
+    name: string;
+    /** Field type */
+    type: string;
+    /** Display label */
+    label?: string;
+    /** Whether field is required */
+    required?: boolean;
+    /** Whether field must be unique */
+    unique?: boolean;
+    /** Default value */
+    defaultValue?: unknown;
+    /** Options for select/radio fields */
+    options?: unknown[];
+    /** Minimum value (for number fields) */
+    min?: number;
+    /** Maximum value (for number fields) */
+    max?: number;
+    /** Minimum length (for text fields) */
+    min_length?: number;
+    /** Maximum length (for text fields) */
+    max_length?: number;
+    /** Regular expression pattern */
+    regex?: string;
+}
+/**
+ * Action metadata summary
+ */
+export interface ActionMetadataSummary {
+    /** Action name (internal identifier) */
+    name: string;
+    /** Action type (record or global) */
+    type: 'record' | 'global';
+    /** Display label */
+    label?: string;
+    /** Action parameters */
+    params?: Record<string, unknown>;
+    /** Action description */
+    description?: string;
+}
+/**
+ * Response for GET /api/metadata/object/:name/actions (list object actions)
+ */
+export interface MetadataApiActionsResponse extends MetadataApiListResponse<ActionMetadataSummary> {
+    items: ActionMetadataSummary[];
+}
+/**
+ * Generic metadata entry
+ */
+export interface MetadataEntry {
+    /** Metadata type (e.g., 'object', 'view', 'form', 'page') */
+    type: string;
+    /** Unique identifier */
+    id: string;
+    /** File path (if loaded from file) */
+    path?: string;
+    /** Package name (if from a plugin) */
+    package?: string;
+    /** Actual metadata content */
+    content: unknown;
+}
+/**
+ * Configuration for Data API client
+ */
+export interface DataApiClientConfig {
+    /** Base URL of the ObjectQL server */
+    baseUrl: string;
+    /** Optional authentication token */
+    token?: string;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Configuration for Metadata API client
+ */
+export interface MetadataApiClientConfig {
+    /** Base URL of the ObjectQL server */
+    baseUrl: string;
+    /** Optional authentication token */
+    token?: string;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Interface for Data API client operations
+ */
+export interface IDataApiClient {
+    /**
+     * List records from an object
+     * @param objectName - Name of the object
+     * @param params - Query parameters
+     */
+    list<T = unknown>(objectName: string, params?: DataApiListParams): Promise<DataApiListResponse<T>>;
+    /**
+     * Get a single record by ID
+     * @param objectName - Name of the object
+     * @param id - Record ID
+     */
+    get<T = unknown>(objectName: string, id: string | number): Promise<DataApiItemResponse<T>>;
+    /**
+     * Create a new record
+     * @param objectName - Name of the object
+     * @param data - Record data
+     */
+    create<T = unknown>(objectName: string, data: DataApiCreateRequest): Promise<DataApiItemResponse<T>>;
+    /**
+     * Create multiple records
+     * @param objectName - Name of the object
+     * @param data - Array of record data
+     */
+    createMany<T = unknown>(objectName: string, data: DataApiCreateManyRequest): Promise<DataApiListResponse<T>>;
+    /**
+     * Update a record
+     * @param objectName - Name of the object
+     * @param id - Record ID
+     * @param data - Updated data
+     */
+    update<T = unknown>(objectName: string, id: string | number, data: DataApiUpdateRequest): Promise<DataApiItemResponse<T>>;
+    /**
+     * Update multiple records
+     * @param objectName - Name of the object
+     * @param request - Bulk update request
+     */
+    updateMany(objectName: string, request: DataApiBulkUpdateRequest): Promise<DataApiResponse>;
+    /**
+     * Delete a record
+     * @param objectName - Name of the object
+     * @param id - Record ID
+     */
+    delete(objectName: string, id: string | number): Promise<DataApiDeleteResponse>;
+    /**
+     * Delete multiple records
+     * @param objectName - Name of the object
+     * @param request - Bulk delete request
+     */
+    deleteMany(objectName: string, request: DataApiBulkDeleteRequest): Promise<DataApiDeleteResponse>;
+    /**
+     * Count records
+     * @param objectName - Name of the object
+     * @param filters - Filter criteria
+     */
+    count(objectName: string, filters?: FilterExpression): Promise<DataApiCountResponse>;
+}
+/**
+ * Interface for Metadata API client operations
+ */
+export interface IMetadataApiClient {
+    /**
+     * List all objects
+     */
+    listObjects(): Promise<MetadataApiObjectListResponse>;
+    /**
+     * Get detailed metadata for a specific object
+     * @param objectName - Name of the object
+     */
+    getObject(objectName: string): Promise<MetadataApiObjectDetailResponse>;
+    /**
+     * Get field metadata for a specific object field
+     * @param objectName - Name of the object
+     * @param fieldName - Name of the field
+     */
+    getField(objectName: string, fieldName: string): Promise<FieldMetadataResponse>;
+    /**
+     * List actions for a specific object
+     * @param objectName - Name of the object
+     */
+    listActions(objectName: string): Promise<MetadataApiActionsResponse>;
+    /**
+     * List metadata entries by type
+     * @param metadataType - Type of metadata (e.g., 'view', 'form', 'page')
+     */
+    listByType<T = unknown>(metadataType: string): Promise<MetadataApiListResponse<T>>;
+    /**
+     * Get a specific metadata entry
+     * @param metadataType - Type of metadata
+     * @param id - Unique identifier
+     */
+    getMetadata<T = unknown>(metadataType: string, id: string): Promise<MetadataApiResponse<T>>;
+}

package/dist/api.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * API Type Definitions for ObjectQL
+ *
+ * This file contains TypeScript interfaces for Data API and Metadata API endpoints.
+ * These types enable frontend applications to make type-safe API calls.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObjectQLError = exports.ApiErrorCode = void 0;
+// ============================================================================
+// Error Handling Types
+// ============================================================================
+/**
+ * Standardized error codes for ObjectQL API responses
+ */
+var ApiErrorCode;
+(function (ApiErrorCode) {
+    ApiErrorCode["INVALID_REQUEST"] = "INVALID_REQUEST";
+    ApiErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    ApiErrorCode["UNAUTHORIZED"] = "UNAUTHORIZED";
+    ApiErrorCode["FORBIDDEN"] = "FORBIDDEN";
+    ApiErrorCode["NOT_FOUND"] = "NOT_FOUND";
+    ApiErrorCode["CONFLICT"] = "CONFLICT";
+    ApiErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+    ApiErrorCode["DATABASE_ERROR"] = "DATABASE_ERROR";
+    ApiErrorCode["RATE_LIMIT_EXCEEDED"] = "RATE_LIMIT_EXCEEDED";
+})(ApiErrorCode || (exports.ApiErrorCode = ApiErrorCode = {}));
+/**
+ * ObjectQL Error class for throwing structured errors
+ */
+class ObjectQLError extends Error {
+    constructor(error) {
+        super(error.message);
+        this.name = 'ObjectQLError';
+        this.code = error.code;
+        this.details = error.details;
+        // Preserve proper stack traces in Node.js environments
+        const ErrorConstructor = Error;
+        if (typeof ErrorConstructor.captureStackTrace === 'function') {
+            ErrorConstructor.captureStackTrace(this, ObjectQLError);
+        }
+    }
+}
+exports.ObjectQLError = ObjectQLError;
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAOH,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E;;GAEG;AACH,IAAY,YAUX;AAVD,WAAY,YAAY;IACpB,mDAAmC,CAAA;IACnC,qDAAqC,CAAA;IACrC,6CAA6B,CAAA;IAC7B,uCAAuB,CAAA;IACvB,uCAAuB,CAAA;IACvB,qCAAqB,CAAA;IACrB,iDAAiC,CAAA;IACjC,iDAAiC,CAAA;IACjC,2DAA2C,CAAA;AAC/C,CAAC,EAVW,YAAY,4BAAZ,YAAY,QAUvB;AAwBD;;GAEG;AACH,MAAa,aAAc,SAAQ,KAAK;IAIpC,YAAY,KAAkF;QAC1F,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAE7B,uDAAuD;QACvD,MAAM,gBAAgB,GAAG,KAA2F,CAAC;QACrH,IAAI,OAAO,gBAAgB,CAAC,iBAAiB,KAAK,UAAU,EAAE,CAAC;YAC3D,gBAAgB,CAAC,iBAAiB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QAC5D,CAAC;IACL,CAAC;CACJ;AAhBD,sCAgBC"}

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/driver.d.ts

@@ -1,3 +1,55 @@
+/**
+ * Column metadata from database introspection.
+ */
+export interface IntrospectedColumn {
+    /** Column name */
+    name: string;
+    /** Native database type (e.g., 'varchar', 'integer', 'timestamp') */
+    type: string;
+    /** Whether the column is nullable */
+    nullable: boolean;
+    /** Default value if any */
+    defaultValue?: any;
+    /** Whether this is a primary key */
+    isPrimary?: boolean;
+    /** Whether this column has a unique constraint */
+    isUnique?: boolean;
+    /** Maximum length for string types */
+    maxLength?: number;
+}
+/**
+ * Foreign key relationship metadata.
+ */
+export interface IntrospectedForeignKey {
+    /** Column name in the source table */
+    columnName: string;
+    /** Referenced table name */
+    referencedTable: string;
+    /** Referenced column name */
+    referencedColumn: string;
+    /** Constraint name */
+    constraintName?: string;
+}
+/**
+ * Table metadata from database introspection.
+ */
+export interface IntrospectedTable {
+    /** Table name */
+    name: string;
+    /** List of columns */
+    columns: IntrospectedColumn[];
+    /** List of foreign key relationships */
+    foreignKeys: IntrospectedForeignKey[];
+    /** Primary key columns */
+    primaryKeys: string[];
+}
+/**
+ * Complete database schema introspection result.
+ */
+export interface IntrospectedSchema {
+    /** Map of table name to table metadata */
+    tables: Record<string, IntrospectedTable>;
+}
 export interface Driver {
     find(objectName: string, query: any, options?: any): Promise<any[]>;
     findOne(objectName: string, id: string | number, query?: any, options?: any): Promise<any>;
@@ -6,6 +58,12 @@ export interface Driver {
     delete(objectName: string, id: string | number, options?: any): Promise<any>;
     count(objectName: string, filters: any, options?: any): Promise<number>;
     init?(objects: any[]): Promise<void>;
+    /**
+     * Introspect the database schema to discover existing tables, columns, and relationships.
+     * This allows connecting to an existing database without defining metadata.
+     * @returns Complete schema information including tables, columns, and foreign keys
+     */
+    introspectSchema?(): Promise<IntrospectedSchema>;
     aggregate?(objectName: string, query: any, options?: any): Promise<any>;
     distinct?(objectName: string, field: string, filters?: any, options?: any): Promise<any[]>;
     createMany?(objectName: string, data: any[], options?: any): Promise<any>;

package/dist/index.d.ts

@@ -16,3 +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,4 +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"}
+{"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,19 @@
 {
   "name": "@objectql/types",
-  "version": "1.8.1",
+  "version": "1.8.3",
+  "description": "Pure TypeScript type definitions and interfaces for the ObjectQL protocol - The Contract",
+  "keywords": [
+    "objectql",
+    "types",
+    "typescript",
+    "interfaces",
+    "protocol",
+    "schema",
+    "metadata",
+    "ai-native",
+    "orm",
+    "database"
+  ],
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",