@objectstack/metadata 0.8.2 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @objectstack/metadata
 
+## 0.9.1
+
+### Patch Changes
+
+- Patch release for maintenance and stability improvements. All packages updated with unified versioning.
+- Updated dependencies
+  - @objectstack/spec@0.9.1
+  - @objectstack/core@0.9.1
+  - @objectstack/types@0.9.1
+
 ## 0.8.2
 
 ### Patch Changes

package/README.md

@@ -196,6 +196,256 @@ The metadata package is designed as a Layer 3 package in the ObjectStack archite
     └── @objectstack/objectql (registry persistence)
 ```
 
+## Common Workflows
+
+### Development Workflow with File Watching
+
+```typescript
+import { MetadataManager } from '@objectstack/metadata';
+
+const manager = new MetadataManager({
+  rootDir: './metadata',
+  watch: true, // Enable file watching
+  cache: { enabled: true, ttl: 3600 }
+});
+
+// Watch for changes and reload
+manager.watch('object', async (event) => {
+  if (event.type === 'modified' || event.type === 'added') {
+    console.log(`Reloading object: ${event.name}`);
+    const updated = await manager.load('object', event.name);
+    
+    // Notify the system to reload
+    await objectQL.reloadObject(event.name, updated);
+  }
+});
+
+// Hot module replacement for development
+console.log('Watching metadata files for changes...');
+```
+
+### Metadata Migration Workflow
+
+```typescript
+import { MetadataManager } from '@objectstack/metadata';
+
+async function migrateMetadata() {
+  const manager = new MetadataManager({
+    rootDir: './metadata'
+  });
+  
+  // 1. Load all existing objects
+  const objects = await manager.loadMany('object');
+  
+  // 2. Transform metadata (e.g., rename field)
+  const transformed = objects.map(obj => ({
+    ...obj,
+    fields: Object.entries(obj.fields).reduce((acc, [key, field]) => {
+      // Rename 'description' to 'notes'
+      const newKey = key === 'description' ? 'notes' : key;
+      acc[newKey] = field;
+      return acc;
+    }, {})
+  }));
+  
+  // 3. Save with backup
+  for (const obj of transformed) {
+    await manager.save('object', obj.name, obj, {
+      format: 'typescript',
+      backup: true, // Create .bak file
+      prettify: true
+    });
+  }
+  
+  console.log(`Migrated ${objects.length} objects`);
+}
+```
+
+### Multi-Format Support Workflow
+
+```typescript
+import { MetadataManager } from '@objectstack/metadata';
+
+const manager = new MetadataManager({
+  rootDir: './metadata',
+  formats: ['typescript', 'json', 'yaml']
+});
+
+// Load from any format - manager auto-detects
+const customer = await manager.load('object', 'customer');
+// Tries: customer.object.ts, customer.object.json, customer.object.yaml
+
+// Save in preferred format
+await manager.save('object', 'customer', customer, {
+  format: 'typescript' // Convert to TypeScript
+});
+
+// Generate documentation from metadata
+const allObjects = await manager.loadMany('object');
+const docs = allObjects.map(obj => `
+## ${obj.label}
+
+**Name:** ${obj.name}
+
+**Fields:**
+${Object.entries(obj.fields).map(([name, field]) => 
+  `- **${field.label}** (\`${name}\`): ${field.type}`
+).join('\n')}
+`).join('\n\n');
+
+fs.writeFileSync('docs/objects.md', docs);
+```
+
+### Validation and Testing Workflow
+
+```typescript
+import { MetadataManager } from '@objectstack/metadata';
+import { ObjectSchema } from '@objectstack/spec/data';
+
+async function validateAllMetadata() {
+  const manager = new MetadataManager({
+    rootDir: './metadata'
+  });
+  
+  const objects = await manager.loadMany('object');
+  const errors = [];
+  
+  for (const obj of objects) {
+    const result = ObjectSchema.safeParse(obj);
+    
+    if (!result.success) {
+      errors.push({
+        name: obj.name,
+        issues: result.error.issues
+      });
+    }
+  }
+  
+  if (errors.length > 0) {
+    console.error('Validation errors found:');
+    errors.forEach(({ name, issues }) => {
+      console.error(`\n${name}:`);
+      issues.forEach(issue => {
+        console.error(`  - ${issue.path.join('.')}: ${issue.message}`);
+      });
+    });
+    process.exit(1);
+  }
+  
+  console.log(`✅ All ${objects.length} objects validated successfully`);
+}
+```
+
+### Metadata Versioning Workflow
+
+```typescript
+import { MetadataManager } from '@objectstack/metadata';
+import { execSync } from 'child_process';
+
+async function versionMetadata() {
+  const manager = new MetadataManager({
+    rootDir: './metadata'
+  });
+  
+  const objects = await manager.loadMany('object');
+  
+  // Get git user name safely
+  let modifiedBy = 'unknown';
+  try {
+    modifiedBy = execSync('git config user.name', { encoding: 'utf-8' }).trim();
+  } catch (error) {
+    console.warn('Could not get git user name, using "unknown"');
+  }
+  
+  // Add version metadata
+  const versioned = objects.map(obj => ({
+    ...obj,
+    metadata: {
+      ...obj.metadata,
+      version: '2.0.0',
+      lastModified: new Date().toISOString(),
+      modifiedBy
+    }
+  }));
+  
+  // Save versioned metadata
+  for (const obj of versioned) {
+    await manager.save('object', obj.name, obj, {
+      format: 'typescript',
+      prettify: true
+    });
+  }
+  
+  // Commit to version control (if git is available)
+  try {
+    execSync('git add metadata/', { stdio: 'inherit' });
+    execSync('git commit -m "Version bump to 2.0.0"', { stdio: 'inherit' });
+  } catch (error) {
+    console.warn('Git commit failed, changes are staged but not committed');
+  }
+}
+```
+
+### Import/Export Workflow
+
+```typescript
+import { MetadataManager } from '@objectstack/metadata';
+
+async function exportToJSON() {
+  const manager = new MetadataManager({
+    rootDir: './metadata'
+  });
+  
+  // Load all metadata
+  const [objects, views, apps] = await Promise.all([
+    manager.loadMany('object'),
+    manager.loadMany('view'),
+    manager.loadMany('app')
+  ]);
+  
+  // Create unified export
+  const exportData = {
+    version: '1.0.0',
+    exported: new Date().toISOString(),
+    objects,
+    views,
+    apps
+  };
+  
+  // Save as single JSON file
+  fs.writeFileSync(
+    'export/metadata-export.json',
+    JSON.stringify(exportData, null, 2)
+  );
+  
+  console.log('Export complete!');
+}
+
+async function importFromJSON(filePath: string) {
+  const manager = new MetadataManager({
+    rootDir: './metadata'
+  });
+  
+  const importData = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  
+  // Import objects
+  for (const obj of importData.objects) {
+    await manager.save('object', obj.name, obj, {
+      format: 'typescript'
+    });
+  }
+  
+  // Import views
+  for (const view of importData.views) {
+    await manager.save('view', view.name, view, {
+      format: 'typescript'
+    });
+  }
+  
+  console.log('Import complete!');
+}
+```
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export { FilesystemLoader } from './loaders/filesystem-loader.js';
 export { type MetadataSerializer, type SerializeOptions } from './serializers/serializer-interface.js';
 export { JSONSerializer } from './serializers/json-serializer.js';
 export { YAMLSerializer } from './serializers/yaml-serializer.js';
+export * as Migration from './migration/index.js';
 export { TypeScriptSerializer } from './serializers/typescript-serializer.js';
 export type { MetadataFormat, MetadataStats, MetadataLoadOptions, MetadataSaveOptions, MetadataExportOptions, MetadataImportOptions, MetadataLoadResult, MetadataSaveResult, MetadataWatchEvent, MetadataCollectionInfo, MetadataLoaderContract, MetadataManagerConfig, } from '@objectstack/spec/system';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG5E,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAGlE,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AACvG,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAG9E,YAAY,EACV,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG5E,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAGlE,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AACvG,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAG9E,YAAY,EACV,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -10,4 +10,5 @@ export { MetadataPlugin } from './plugin.js';
 export { FilesystemLoader } from './loaders/filesystem-loader.js';
 export { JSONSerializer } from './serializers/json-serializer.js';
 export { YAMLSerializer } from './serializers/yaml-serializer.js';
+export * as Migration from './migration/index.js';
 export { TypeScriptSerializer } from './serializers/typescript-serializer.js';

package/dist/migration/executor.d.ts

@@ -0,0 +1,9 @@
+import { System } from '@objectstack/spec';
+import { ISchemaDriver } from '@objectstack/spec/contracts';
+export declare class MigrationExecutor {
+    private driver;
+    constructor(driver: ISchemaDriver);
+    executeChangeSet(changeSet: System.ChangeSet): Promise<void>;
+    private executeOperation;
+}
+//# sourceMappingURL=executor.d.ts.map

package/dist/migration/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/migration/executor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,qBAAa,iBAAiB;IAChB,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAEnC,gBAAgB,CAAC,SAAS,EAAE,MAAM,CAAC,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;YAapD,gBAAgB;CAgC/B"}

package/dist/migration/executor.js

@@ -0,0 +1,49 @@
+export class MigrationExecutor {
+    constructor(driver) {
+        this.driver = driver;
+    }
+    async executeChangeSet(changeSet) {
+        console.log(`Executing ChangeSet: ${changeSet.name} (${changeSet.id})`);
+        for (const op of changeSet.operations) {
+            try {
+                await this.executeOperation(op);
+            }
+            catch (e) {
+                console.error(`Failed to execute operation ${op.type}:`, e);
+                throw e;
+            }
+        }
+    }
+    async executeOperation(op) {
+        switch (op.type) {
+            case 'create_object':
+                console.log(`  > Create Object: ${op.object.name}`);
+                await this.driver.createCollection(op.object.name, op.object);
+                break;
+            case 'add_field':
+                console.log(`  > Add Field: ${op.objectName}.${op.fieldName}`);
+                await this.driver.addColumn(op.objectName, op.fieldName, op.field);
+                break;
+            case 'remove_field':
+                console.log(`  > Remove Field: ${op.objectName}.${op.fieldName}`);
+                await this.driver.dropColumn(op.objectName, op.fieldName);
+                break;
+            case 'delete_object':
+                console.log(`  > Delete Object: ${op.objectName}`);
+                await this.driver.dropCollection(op.objectName);
+                break;
+            case 'execute_sql':
+                console.log(`  > Execute SQL`);
+                await this.driver.executeRaw(op.sql);
+                break;
+            case 'modify_field':
+                console.warn(`  ! Modify Field: ${op.objectName}.${op.fieldName} (Not fully implemented)`);
+                break;
+            case 'rename_object':
+                console.warn(`  ! Rename Object: ${op.oldName} -> ${op.newName} (Not fully implemented)`);
+                break;
+            default:
+                throw new Error(`Unknown operation type`);
+        }
+    }
+}

package/dist/migration/index.d.ts

@@ -0,0 +1,2 @@
+export * from './executor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/migration/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migration/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC"}

package/dist/migration/index.js

@@ -0,0 +1 @@
+export * from './executor.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/metadata",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Metadata loading, saving, and persistence for ObjectStack",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -16,9 +16,9 @@
     "js-yaml": "^4.1.0",
     "chokidar": "^3.5.3",
     "zod": "^4.3.6",
-    "@objectstack/core": "0.8.2",
-    "@objectstack/spec": "0.8.2",
-    "@objectstack/types": "0.8.2"
+    "@objectstack/core": "0.9.1",
+    "@objectstack/spec": "0.9.1",
+    "@objectstack/types": "0.9.1"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/src/index.ts

@@ -18,6 +18,7 @@ export { FilesystemLoader } from './loaders/filesystem-loader.js';
 export { type MetadataSerializer, type SerializeOptions } from './serializers/serializer-interface.js';
 export { JSONSerializer } from './serializers/json-serializer.js';
 export { YAMLSerializer } from './serializers/yaml-serializer.js';
+export * as Migration from './migration/index.js';
 export { TypeScriptSerializer } from './serializers/typescript-serializer.js';
 
 // Re-export types from spec

package/src/migration/executor.ts

@@ -0,0 +1,52 @@
+import { System } from '@objectstack/spec';
+import { ISchemaDriver } from '@objectstack/spec/contracts';
+
+export class MigrationExecutor {
+  constructor(private driver: ISchemaDriver) {}
+
+  async executeChangeSet(changeSet: System.ChangeSet): Promise<void> {
+    console.log(`Executing ChangeSet: ${changeSet.name} (${changeSet.id})`);
+    
+    for (const op of changeSet.operations) {
+      try {
+        await this.executeOperation(op);
+      } catch (e) {
+        console.error(`Failed to execute operation ${op.type}:`, e);
+        throw e;
+      }
+    }
+  }
+
+  private async executeOperation(op: System.MigrationOperation): Promise<void> {
+    switch (op.type) {
+      case 'create_object':
+        console.log(`  > Create Object: ${op.object.name}`);
+        await this.driver.createCollection(op.object.name, op.object);
+        break;
+      case 'add_field':
+        console.log(`  > Add Field: ${op.objectName}.${op.fieldName}`);
+        await this.driver.addColumn(op.objectName, op.fieldName, op.field);
+        break;
+      case 'remove_field':
+        console.log(`  > Remove Field: ${op.objectName}.${op.fieldName}`);
+        await this.driver.dropColumn(op.objectName, op.fieldName);
+        break;
+      case 'delete_object':
+        console.log(`  > Delete Object: ${op.objectName}`);
+        await this.driver.dropCollection(op.objectName);
+        break;
+      case 'execute_sql':
+        console.log(`  > Execute SQL`);
+        await this.driver.executeRaw(op.sql);
+        break;
+      case 'modify_field':
+        console.warn(`  ! Modify Field: ${op.objectName}.${op.fieldName} (Not fully implemented)`);
+        break;
+      case 'rename_object':
+        console.warn(`  ! Rename Object: ${op.oldName} -> ${op.newName} (Not fully implemented)`);
+        break;
+      default:
+        throw new Error(`Unknown operation type`);
+    }
+  }
+}

package/src/migration/index.ts

@@ -0,0 +1 @@
+export * from './executor.js';