feat: add metadata management demo with loading, saving, and backup features; include example objects and configuration

Author: hotlong

examples/metadata-demo/README.md

@@ -0,0 +1,41 @@
+# Metadata Management Demo
+
+This example demonstrates how to use the `@objectstack/metadata` package to manage application metadata (Objects, Views, Flows, etc.).
+
+## Key Features Demonstrated
+
+1.  **Metadata Manager**: Initialization and configuration.
+2.  **Loading**: Reading metadata from the filesystem (`json`, `yaml`, `ts`).
+3.  **Saving API**:
+    *   **Atomic Writes**: Safe file updates.
+    *   **Backups**: Automatic `.bak` creation.
+    *   **Format Control**: Saving as JSON or YAML.
+4.  **Registry Pattern**: How the manager handles multiple loaders (FileSystem, etc.).
+
+## Project Structure
+
+```text
+├── metadata/             # Metadata Repository
+│   └── objects/          # Object Definitions
+│       └── demo.object.json
+├── src/
+│   └── index.ts          # Demo Script
+└── package.json
+```
+
+## Running the Demo
+
+Make sure you have installed dependencies in the root workspace.
+
+```bash
+# Run the demo script
+pnpm start
+```
+
+## Expected Output
+
+The script will:
+1. Load `demo_object` from JSON.
+2. Add a timestamp description and save it back (creating a backup).
+3. Create a new `generated_object` as a YAML file.
+4. List all available objects.

examples/metadata-demo/metadata/object/demo_object.json

@@ -0,0 +1,16 @@
+{
+  "name": "demo_object",
+  "label": "Demo Object",
+  "type": "object",
+  "fields": {
+    "name": {
+      "type": "text",
+      "label": "Name",
+      "required": true
+    },
+    "status": {
+      "type": "select",
+      "options": ["Draft", "Active"]
+    }
+  }
+}

examples/metadata-demo/metadata/object/demo_object.ts

@@ -0,0 +1,24 @@
+import type { ServiceObject } from '@objectstack/spec/data';
+
+export const metadata: ServiceObject = {
+  "name": "demo_object",
+  "label": "Demo Object",
+  "type": "object",
+  "fields": {
+    "name": {
+      "type": "text",
+      "label": "Name",
+      "required": true
+    },
+    "status": {
+      "type": "select",
+      "options": [
+        "Draft",
+        "Active"
+      ]
+    }
+  },
+  "description": "Updated at 2026-02-04T15:41:55.800Z"
+};
+
+export default metadata;

examples/metadata-demo/metadata/object/generated_object.yaml

@@ -0,0 +1,6 @@
+name: generated_object
+label: Generated Object
+type: object
+fields:
+  auto_field:
+    type: text

examples/metadata-demo/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@example/metadata-demo",
+  "version": "0.1.0",
+  "description": "Demonstration of Metadata Manager capabilities (Load/Save/Watch)",
+  "private": true,
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "dirty-read": "tsx src/dirty-read.ts"
+  },
+  "dependencies": {
+    "@objectstack/metadata": "workspace:*",
+    "@objectstack/spec": "workspace:*",
+    "@objectstack/core": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "tsx": "^4.21.0",
+    "@types/node": "^22.0.0"
+  }
+}

examples/metadata-demo/src/index.ts

@@ -0,0 +1,68 @@
+import { MetadataManager } from '@objectstack/metadata';
+import * as path from 'node:path';
+// import { fileURLToPath } from 'node:url';
+
+// const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, '../metadata');
+
+async function main() {
+  console.log('🚀 Starting Metadata Demo...');
+  console.log(`📂 Root Directory: ${rootDir}`);
+
+  // 1. Initialize Manager
+  const manager = new MetadataManager({
+    rootDir,
+    formats: ['json', 'yaml', 'typescript'],
+    watch: false
+  });
+
+  // 2. List initial items
+  console.log('\n2. Listing "object" items:');
+  const objects = await manager.list('object');
+  console.log('   Found:', objects);
+
+  // 3. Load an item
+  console.log('\n3. Loading "demo_object":');
+  const demoObject = await manager.load('object', 'demo_object');
+  console.log('   Loaded:', demoObject?.label);
+
+  if (demoObject) {
+    // 4. Modify and Save (Update)
+    console.log('\n4. Updating "demo_object" (adding description)...');
+    demoObject.description = `Updated at ${new Date().toISOString()}`;
+    
+    // Explicitly using filesystem loader, using atomic writes
+    const saveResult = await manager.save('object', 'demo_object', demoObject, {
+      loader: 'filesystem',
+      atomic: true,
+      backup: true // Create .bak file
+    });
+    console.log('   Save Result:', saveResult.success ? 'Success' : 'Failed');
+    console.log('   Path:', saveResult.path);
+  }
+
+  // 5. Create a NEW item programmatically
+  console.log('\n5. Creating new "generated_object"...');
+  const newObject = {
+    name: 'generated_object',
+    label: 'Generated Object',
+    type: 'object',
+    fields: {
+      auto_field: { type: 'text' }
+    }
+  };
+
+  const createResult = await manager.save('object', 'generated_object', newObject, {
+    format: 'yaml', // Save as YAML
+    create: true
+  });
+  console.log('   Created Result:', createResult.success ? 'Success' : 'Failed');
+  console.log('   Path:', createResult.path);
+
+  // 6. Verify List again
+  console.log('\n6. Final List:');
+  const finalObjects = await manager.list('object');
+  console.log('   Found:', finalObjects);
+}
+
+main().catch(console.error);

examples/metadata-demo/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "paths": {
+      "@objectstack/metadata": ["../../packages/metadata/src/index.ts"],
+      "@objectstack/spec": ["../../packages/spec/src/index.ts"],
+      "@objectstack/core": ["../../packages/core/src/index.ts"]
+    }
+  },
+  "include": ["src/**/*"]
+}

packages/metadata/src/loaders/filesystem-loader.ts

@@ -342,7 +342,7 @@ export class FilesystemLoader implements MetadataLoader {
       return {
         success: true,
         path: filePath,
-        format,
+        // format, // Not in schema
         size: Buffer.byteLength(content, 'utf-8'),
         backupPath,
         saveTime: Date.now() - startTime,
@@ -353,14 +353,7 @@ export class FilesystemLoader implements MetadataLoader {
         name,
         error: error instanceof Error ? error.message : String(error),
       });
-
-      return {
-        success: false,
-        path: '', // TODO: Should this be optional in result?
-        format,
-        error: error instanceof Error ? error : new Error(String(error)),
-        saveTime: Date.now() - startTime,
-      };
+      throw error;
     }
   }
 

packages/metadata/src/metadata-manager.ts

@@ -4,9 +4,7 @@
  * Main orchestrator for metadata loading, saving, and persistence
  */
 
-import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { createHash } from 'node:crypto';
 import { watch as chokidarWatch, type FSWatcher } from 'chokidar';
 import type {
   MetadataManagerConfig,
@@ -111,7 +109,6 @@ export class MetadataManager {
     options?: MetadataLoadOptions
   ): Promise<T[]> {
     const results: T[] = [];
-    const seen = new Set<string>(); // De-duplication key needed? For now, simple aggregation
 
     for (const loader of this.loaders.values()) {
         try {
@@ -318,14 +315,4 @@ export class MetadataManager {
       }
     }
   }
-
-  /**
-   * Generate ETag for content
-   * Uses SHA-256 hash truncated to 32 characters for reasonable collision resistance
-   * while keeping ETag headers compact (full 64-char hash is overkill for this use case)
-   */
-  private generateETag(content: string): string {
-    const hash = createHash('sha256').update(content).digest('hex').substring(0, 32);
-    return `"${hash}"`;
-  }
 }

packages/spec/json-schema/system/MetadataLoadOptions.json

@@ -42,6 +42,10 @@
           "items": {
             "type": "string"
           }
+        },
+        "loader": {
+          "type": "string",
+          "description": "Specific loader to use (e.g. filesystem, database)"
         }
       },
       "additionalProperties": false