@objectstack/metadata 3.0.11 → 3.1.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/metadata@3.0.11 build /home/runner/work/spec/spec/packages/metadata
+> @objectstack/metadata@3.1.0 build /home/runner/work/spec/spec/packages/metadata
 > tsup --config ../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     56.54 KB
-ESM dist/index.mjs.map 115.11 KB
-ESM ⚡️ Build success in 186ms
-CJS dist/index.js     58.68 KB
-CJS dist/index.js.map 117.29 KB
-CJS ⚡️ Build success in 203ms
+CJS dist/index.js     63.63 KB
+CJS dist/index.js.map 126.48 KB
+CJS ⚡️ Build success in 194ms
+ESM dist/index.mjs     61.49 KB
+ESM dist/index.mjs.map 124.30 KB
+ESM ⚡️ Build success in 199ms
 DTS Build start
-DTS ⚡️ Build success in 19997ms
-DTS dist/index.d.mts 30.41 KB
-DTS dist/index.d.ts  30.41 KB
+DTS ⚡️ Build success in 22968ms
+DTS dist/index.d.mts 31.26 KB
+DTS dist/index.d.ts  31.26 KB

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @objectstack/metadata
 
+## 3.1.0
+
+### Patch Changes
+
+- Updated dependencies [0088830]
+  - @objectstack/spec@3.1.0
+  - @objectstack/core@3.1.0
+  - @objectstack/types@3.1.0
+
 ## 3.0.11
 
 ### Patch Changes

package/README.md

@@ -86,6 +86,7 @@ The `MetadataManager` is the main orchestrator. It provides:
 - **Core CRUD**: `register`, `get`, `list`, `unregister`, `exists`, `listNames`
 - **Convenience**: `getObject`, `listObjects`
 - **Package Management**: `unregisterPackage` — unload all metadata from a package
+- **Package Publishing**: `publishPackage`, `revertPackage`, `getPublished` — atomic package-level metadata publishing
 - **Query / Search**: `query` with filtering, pagination, sorting by type/scope/state/tags
 - **Bulk Operations**: `bulkRegister`, `bulkUnregister` with error handling
 - **Import / Export**: `exportMetadata`, `importMetadata` with conflict resolution (skip/overwrite/merge)
@@ -201,6 +202,34 @@ const plugin = MetadataPlugin({
 kernel.use(plugin);
 ```
 
+## Package Publishing
+
+ObjectStack supports **package-level metadata publishing** — all metadata items within a package are published atomically.
+
+### Publish a Package
+
+```typescript
+const result = await manager.publishPackage('com.acme.crm', {
+  publishedBy: 'admin',
+  validate: true,
+});
+// result: { success: true, version: 2, itemsPublished: 5, publishedAt: '...' }
+```
+
+### Revert to Last Published State
+
+```typescript
+await manager.revertPackage('com.acme.crm');
+// All items restored to their publishedDefinition snapshots
+```
+
+### Get Published Version (Runtime Serving)
+
+```typescript
+const published = await manager.getPublished('object', 'opportunity');
+// Returns publishedDefinition if exists, else current definition
+```
+
 ## Package Structure
 
 ```

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { MetadataFormat, MetadataLoaderContract, MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataSaveOptions, MetadataSaveResult, MetadataWatchEvent, MetadataManagerConfig } from '@objectstack/spec/system';
+import { MetadataFormat, MetadataLoaderContract, MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataSaveOptions, MetadataSaveResult, MetadataWatchEvent, MetadataManagerConfig, PackagePublishResult } from '@objectstack/spec/system';
 export { MetadataCollectionInfo, MetadataExportOptions, MetadataFormat, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
 import { IMetadataService, IDataDriver, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, ISchemaDriver } from '@objectstack/spec/contracts';
 export { IMetadataService, MetadataImportResult, MetadataTypeInfo, MetadataWatchCallback, MetadataWatchHandle } from '@objectstack/spec/contracts';
@@ -225,6 +225,28 @@ declare class MetadataManager implements IMetadataService {
      * Unregister all metadata items from a specific package
      */
     unregisterPackage(packageName: string): Promise<void>;
+    /**
+     * Publish an entire package:
+     * 1. Validate all draft items
+     * 2. Snapshot all items in the package (publishedDefinition = clone(metadata))
+     * 3. Increment version
+     * 4. Set all items state → active
+     */
+    publishPackage(packageId: string, options?: {
+        changeNote?: string;
+        publishedBy?: string;
+        validate?: boolean;
+    }): Promise<PackagePublishResult>;
+    /**
+     * Revert entire package to last published state.
+     * Restores all metadata definitions from their published snapshots.
+     */
+    revertPackage(packageId: string): Promise<void>;
+    /**
+     * Get the published version of any metadata item (for runtime serving).
+     * Returns publishedDefinition if exists, else current definition.
+     */
+    getPublished(type: string, name: string): Promise<unknown | undefined>;
     /**
      * Query metadata items with filtering, sorting, and pagination
      */

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { MetadataFormat, MetadataLoaderContract, MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataSaveOptions, MetadataSaveResult, MetadataWatchEvent, MetadataManagerConfig } from '@objectstack/spec/system';
+import { MetadataFormat, MetadataLoaderContract, MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataSaveOptions, MetadataSaveResult, MetadataWatchEvent, MetadataManagerConfig, PackagePublishResult } from '@objectstack/spec/system';
 export { MetadataCollectionInfo, MetadataExportOptions, MetadataFormat, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
 import { IMetadataService, IDataDriver, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, ISchemaDriver } from '@objectstack/spec/contracts';
 export { IMetadataService, MetadataImportResult, MetadataTypeInfo, MetadataWatchCallback, MetadataWatchHandle } from '@objectstack/spec/contracts';
@@ -225,6 +225,28 @@ declare class MetadataManager implements IMetadataService {
      * Unregister all metadata items from a specific package
      */
     unregisterPackage(packageName: string): Promise<void>;
+    /**
+     * Publish an entire package:
+     * 1. Validate all draft items
+     * 2. Snapshot all items in the package (publishedDefinition = clone(metadata))
+     * 3. Increment version
+     * 4. Set all items state → active
+     */
+    publishPackage(packageId: string, options?: {
+        changeNote?: string;
+        publishedBy?: string;
+        validate?: boolean;
+    }): Promise<PackagePublishResult>;
+    /**
+     * Revert entire package to last published state.
+     * Restores all metadata definitions from their published snapshots.
+     */
+    revertPackage(packageId: string): Promise<void>;
+    /**
+     * Get the published version of any metadata item (for runtime serving).
+     * Returns publishedDefinition if exists, else current definition.
+     */
+    getPublished(type: string, name: string): Promise<unknown | undefined>;
     /**
      * Query metadata items with filtering, sorting, and pagination
      */

package/dist/index.js

@@ -825,6 +825,156 @@ var MetadataManager = class {
       }
     }
   }
+  /**
+   * Publish an entire package:
+   * 1. Validate all draft items
+   * 2. Snapshot all items in the package (publishedDefinition = clone(metadata))
+   * 3. Increment version
+   * 4. Set all items state → active
+   */
+  async publishPackage(packageId, options) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const shouldValidate = options?.validate !== false;
+    const publishedBy = options?.publishedBy;
+    const packageItems = [];
+    for (const [type, typeStore] of this.registry) {
+      for (const [name, data] of typeStore) {
+        const meta = data;
+        if (meta?.packageId === packageId || meta?.package === packageId) {
+          packageItems.push({ type, name, data: meta });
+        }
+      }
+    }
+    if (packageItems.length === 0) {
+      return {
+        success: false,
+        packageId,
+        version: 0,
+        publishedAt: now,
+        itemsPublished: 0,
+        validationErrors: [{ type: "", name: "", message: `No metadata items found for package '${packageId}'` }]
+      };
+    }
+    if (shouldValidate) {
+      const validationErrors = [];
+      for (const item of packageItems) {
+        const result = await this.validate(item.type, item.data);
+        if (!result.valid && result.errors) {
+          for (const err of result.errors) {
+            validationErrors.push({
+              type: item.type,
+              name: item.name,
+              message: err.message
+            });
+          }
+        }
+      }
+      const packageItemKeys = new Set(packageItems.map((i) => `${i.type}:${i.name}`));
+      for (const item of packageItems) {
+        const deps = await this.getDependencies(item.type, item.name);
+        for (const dep of deps) {
+          const depKey = `${dep.targetType}:${dep.targetName}`;
+          if (packageItemKeys.has(depKey)) continue;
+          const depItem = await this.get(dep.targetType, dep.targetName);
+          if (!depItem) {
+            validationErrors.push({
+              type: item.type,
+              name: item.name,
+              message: `Dependency '${dep.targetType}:${dep.targetName}' not found`
+            });
+          } else {
+            const depMeta = depItem;
+            if (depMeta.publishedDefinition === void 0 && depMeta.state !== "active") {
+              validationErrors.push({
+                type: item.type,
+                name: item.name,
+                message: `Dependency '${dep.targetType}:${dep.targetName}' is not published`
+              });
+            }
+          }
+        }
+      }
+      if (validationErrors.length > 0) {
+        return {
+          success: false,
+          packageId,
+          version: 0,
+          publishedAt: now,
+          itemsPublished: 0,
+          validationErrors
+        };
+      }
+    }
+    let maxVersion = 0;
+    for (const item of packageItems) {
+      const v = typeof item.data.version === "number" ? item.data.version : 0;
+      if (v > maxVersion) maxVersion = v;
+    }
+    const newVersion = maxVersion + 1;
+    for (const item of packageItems) {
+      const updated = {
+        ...item.data,
+        publishedDefinition: structuredClone(item.data.metadata ?? item.data),
+        publishedAt: now,
+        publishedBy: publishedBy ?? item.data.publishedBy,
+        version: newVersion,
+        state: "active"
+      };
+      await this.register(item.type, item.name, updated);
+    }
+    return {
+      success: true,
+      packageId,
+      version: newVersion,
+      publishedAt: now,
+      itemsPublished: packageItems.length
+    };
+  }
+  /**
+   * Revert entire package to last published state.
+   * Restores all metadata definitions from their published snapshots.
+   */
+  async revertPackage(packageId) {
+    const packageItems = [];
+    for (const [type, typeStore] of this.registry) {
+      for (const [name, data] of typeStore) {
+        const meta = data;
+        if (meta?.packageId === packageId || meta?.package === packageId) {
+          packageItems.push({ type, name, data: meta });
+        }
+      }
+    }
+    if (packageItems.length === 0) {
+      throw new Error(`No metadata items found for package '${packageId}'`);
+    }
+    const hasPublished = packageItems.some((item) => item.data.publishedDefinition !== void 0);
+    if (!hasPublished) {
+      throw new Error(`Package '${packageId}' has never been published`);
+    }
+    for (const item of packageItems) {
+      if (item.data.publishedDefinition !== void 0) {
+        const reverted = {
+          ...item.data,
+          metadata: structuredClone(item.data.publishedDefinition),
+          state: "active"
+        };
+        await this.register(item.type, item.name, reverted);
+      }
+    }
+  }
+  /**
+   * Get the published version of any metadata item (for runtime serving).
+   * Returns publishedDefinition if exists, else current definition.
+   */
+  async getPublished(type, name) {
+    const item = await this.get(type, name);
+    if (!item) return void 0;
+    const meta = item;
+    if (meta.publishedDefinition !== void 0) {
+      return meta.publishedDefinition;
+    }
+    return meta.metadata ?? item;
+  }
   // ==========================================
   // Query / Search
   // ==========================================