@objectstack/metadata 2.0.6 → 3.0.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/metadata@2.0.6 build /home/runner/work/spec/spec/packages/metadata
+> @objectstack/metadata@3.0.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
-CJS dist/index.js     30.61 KB
-CJS dist/index.js.map 62.34 KB
-CJS ⚡️ Build success in 115ms
-ESM dist/index.mjs     28.81 KB
-ESM dist/index.mjs.map 60.95 KB
-ESM ⚡️ Build success in 115ms
+ESM dist/index.mjs     43.87 KB
+ESM dist/index.mjs.map 88.95 KB
+ESM ⚡️ Build success in 135ms
+CJS dist/index.js     45.68 KB
+CJS dist/index.js.map 90.92 KB
+CJS ⚡️ Build success in 133ms
 DTS Build start
-DTS ⚡️ Build success in 10940ms
-DTS dist/index.d.mts 9.83 KB
-DTS dist/index.d.ts  9.83 KB
+DTS ⚡️ Build success in 12517ms
+DTS dist/index.d.mts 14.80 KB
+DTS dist/index.d.ts  14.80 KB

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @objectstack/metadata
 
+## 3.0.0
+
+### Major Changes
+
+- Release v3.0.0 — unified version bump for all ObjectStack packages.
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectstack/spec@3.0.0
+  - @objectstack/core@3.0.0
+  - @objectstack/types@3.0.0
+
+## 2.0.7
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectstack/spec@2.0.7
+  - @objectstack/core@2.0.7
+  - @objectstack/types@2.0.7
+
 ## 2.0.6
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,9 +1,12 @@
 import { MetadataFormat, MetadataLoaderContract, MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataSaveOptions, MetadataSaveResult, MetadataWatchEvent, MetadataManagerConfig } from '@objectstack/spec/system';
 export { MetadataCollectionInfo, MetadataExportOptions, MetadataFormat, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
+import { IMetadataService, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, ISchemaDriver } from '@objectstack/spec/contracts';
+export { IMetadataService, MetadataImportResult, MetadataTypeInfo, MetadataWatchCallback, MetadataWatchHandle } from '@objectstack/spec/contracts';
+import { MetadataTypeRegistryEntry, MetadataQuery, MetadataQueryResult, MetadataBulkResult, MetadataOverlay, MetadataValidationResult, MetadataDependency, MetadataPluginConfig } from '@objectstack/spec/kernel';
+export { MetadataBulkResult, MetadataDependency, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel';
 import { Logger, Plugin, PluginContext } from '@objectstack/core';
 import { z } from 'zod';
 import { System } from '@objectstack/spec';
-import { ISchemaDriver } from '@objectstack/spec/contracts';
 
 /**
  * Metadata Serializer Interface
@@ -125,63 +128,179 @@ interface MetadataLoader {
  * Metadata Manager
  *
  * Main orchestrator for metadata loading, saving, and persistence.
+ * Implements the IMetadataService contract from @objectstack/spec.
  * Browser-compatible (Pure).
  */
 
 /**
- * Watch callback function
+ * Watch callback function (legacy)
  */
 type WatchCallback = (event: MetadataWatchEvent) => void | Promise<void>;
 interface MetadataManagerOptions extends MetadataManagerConfig {
     loaders?: MetadataLoader[];
 }
 /**
- * Main metadata manager class
+ * Main metadata manager class.
+ * Implements IMetadataService contract for unified metadata management.
  */
-declare class MetadataManager {
+declare class MetadataManager implements IMetadataService {
     private loaders;
     protected serializers: Map<MetadataFormat, MetadataSerializer>;
     protected logger: Logger;
     protected watchCallbacks: Map<string, Set<WatchCallback>>;
     protected config: MetadataManagerOptions;
+    private registry;
+    private overlays;
+    private typeRegistry;
+    private dependencies;
     constructor(config: MetadataManagerOptions);
+    /**
+     * Set the type registry for metadata type discovery.
+     */
+    setTypeRegistry(entries: MetadataTypeRegistryEntry[]): void;
     /**
      * Register a new metadata loader (data source)
      */
     registerLoader(loader: MetadataLoader): void;
     /**
-     * Load a single metadata item
-     * Iterates through registered loaders until found
+     * Register/save a metadata item by type
      */
-    load<T = any>(type: string, name: string, options?: MetadataLoadOptions): Promise<T | null>;
+    register(type: string, name: string, data: unknown): Promise<void>;
     /**
-     * Load multiple metadata items
-     * Aggregates results from all loaders
+     * Get a metadata item by type and name.
+     * Checks in-memory registry first, then falls back to loaders.
      */
-    loadMany<T = any>(type: string, options?: MetadataLoadOptions): Promise<T[]>;
+    get(type: string, name: string): Promise<unknown | undefined>;
     /**
-     * Save metadata to disk
+     * List all metadata items of a given type
      */
+    list(type: string): Promise<unknown[]>;
     /**
-     * Save metadata item
+     * Unregister/remove a metadata item by type and name
      */
-    save<T = any>(type: string, name: string, data: T, options?: MetadataSaveOptions): Promise<MetadataSaveResult>;
+    unregister(type: string, name: string): Promise<void>;
     /**
-     * Check if metadata item exists
+     * Check if a metadata item exists
      */
     exists(type: string, name: string): Promise<boolean>;
     /**
-     * List all items of a type
+     * List all names of metadata items of a given type
      */
-    list(type: string): Promise<string[]>;
+    listNames(type: string): Promise<string[]>;
+    /**
+     * Convenience: get an object definition by name
+     */
+    getObject(name: string): Promise<unknown | undefined>;
+    /**
+     * Convenience: list all object definitions
+     */
+    listObjects(): Promise<unknown[]>;
+    /**
+     * Unregister all metadata items from a specific package
+     */
+    unregisterPackage(packageName: string): Promise<void>;
+    /**
+     * Query metadata items with filtering, sorting, and pagination
+     */
+    query(query: MetadataQuery): Promise<MetadataQueryResult>;
+    /**
+     * Register multiple metadata items in a single batch
+     */
+    bulkRegister(items: Array<{
+        type: string;
+        name: string;
+        data: unknown;
+    }>, options?: {
+        continueOnError?: boolean;
+        validate?: boolean;
+    }): Promise<MetadataBulkResult>;
+    /**
+     * Unregister multiple metadata items in a single batch
+     */
+    bulkUnregister(items: Array<{
+        type: string;
+        name: string;
+    }>): Promise<MetadataBulkResult>;
+    private overlayKey;
+    /**
+     * Get the active overlay for a metadata item
+     */
+    getOverlay(type: string, name: string, scope?: 'platform' | 'user'): Promise<MetadataOverlay | undefined>;
+    /**
+     * Save/update an overlay for a metadata item
+     */
+    saveOverlay(overlay: MetadataOverlay): Promise<void>;
+    /**
+     * Remove an overlay, reverting to the base definition
+     */
+    removeOverlay(type: string, name: string, scope?: 'platform' | 'user'): Promise<void>;
+    /**
+     * Get the effective (merged) metadata after applying all overlays.
+     * Resolution order: system ← merge(platform) ← merge(user)
+     */
+    getEffective(type: string, name: string): Promise<unknown | undefined>;
+    /**
+     * Watch for metadata changes (IMetadataService contract).
+     * Returns a handle for unsubscribing.
+     */
+    watchService(type: string, callback: MetadataWatchCallback): MetadataWatchHandle;
+    /**
+     * Export metadata as a portable bundle
+     */
+    exportMetadata(options?: MetadataExportOptions): Promise<unknown>;
+    /**
+     * Import metadata from a portable bundle
+     */
+    importMetadata(data: unknown, options?: MetadataImportOptions): Promise<MetadataImportResult>;
+    /**
+     * Validate a metadata item against its type schema.
+     * Returns validation result with errors and warnings.
+     */
+    validate(_type: string, data: unknown): Promise<MetadataValidationResult>;
+    /**
+     * Get all registered metadata types
+     */
+    getRegisteredTypes(): Promise<string[]>;
+    /**
+     * Get detailed information about a metadata type
+     */
+    getTypeInfo(type: string): Promise<MetadataTypeInfo | undefined>;
+    /**
+     * Get metadata items that this item depends on
+     */
+    getDependencies(type: string, name: string): Promise<MetadataDependency[]>;
+    /**
+     * Get metadata items that depend on this item
+     */
+    getDependents(type: string, name: string): Promise<MetadataDependency[]>;
+    /**
+     * Register a dependency between two metadata items.
+     * Used internally to track cross-references.
+     * Duplicate dependencies (same source, target, and kind) are ignored.
+     */
+    addDependency(dep: MetadataDependency): void;
+    /**
+     * Load a single metadata item from loaders.
+     * Iterates through registered loaders until found.
+     */
+    load<T = any>(type: string, name: string, options?: MetadataLoadOptions): Promise<T | null>;
+    /**
+     * Load multiple metadata items from loaders.
+     * Aggregates results from all loaders.
+     */
+    loadMany<T = any>(type: string, options?: MetadataLoadOptions): Promise<T[]>;
+    /**
+     * Save metadata item to a loader
+     */
+    save<T = any>(type: string, name: string, data: T, options?: MetadataSaveOptions): Promise<MetadataSaveResult>;
     /**
-     * Watch for metadata changes
+     * Register a watch callback for metadata changes
      */
-    watch(type: string, callback: WatchCallback): void;
+    protected addWatchCallback(type: string, callback: WatchCallback): void;
     /**
-     * Unwatch metadata changes
+     * Remove a watch callback for metadata changes
      */
-    unwatch(type: string, callback: WatchCallback): void;
+    protected removeWatchCallback(type: string, callback: WatchCallback): void;
     /**
      * Stop all watching
      */
@@ -192,6 +311,7 @@ declare class MetadataManager {
 interface MetadataPluginOptions {
     rootDir?: string;
     watch?: boolean;
+    config?: Partial<MetadataPluginConfig>;
 }
 declare class MetadataPlugin implements Plugin {
     name: string;

package/dist/index.d.ts

@@ -1,9 +1,12 @@
 import { MetadataFormat, MetadataLoaderContract, MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataSaveOptions, MetadataSaveResult, MetadataWatchEvent, MetadataManagerConfig } from '@objectstack/spec/system';
 export { MetadataCollectionInfo, MetadataExportOptions, MetadataFormat, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
+import { IMetadataService, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, ISchemaDriver } from '@objectstack/spec/contracts';
+export { IMetadataService, MetadataImportResult, MetadataTypeInfo, MetadataWatchCallback, MetadataWatchHandle } from '@objectstack/spec/contracts';
+import { MetadataTypeRegistryEntry, MetadataQuery, MetadataQueryResult, MetadataBulkResult, MetadataOverlay, MetadataValidationResult, MetadataDependency, MetadataPluginConfig } from '@objectstack/spec/kernel';
+export { MetadataBulkResult, MetadataDependency, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel';
 import { Logger, Plugin, PluginContext } from '@objectstack/core';
 import { z } from 'zod';
 import { System } from '@objectstack/spec';
-import { ISchemaDriver } from '@objectstack/spec/contracts';
 
 /**
  * Metadata Serializer Interface
@@ -125,63 +128,179 @@ interface MetadataLoader {
  * Metadata Manager
  *
  * Main orchestrator for metadata loading, saving, and persistence.
+ * Implements the IMetadataService contract from @objectstack/spec.
  * Browser-compatible (Pure).
  */
 
 /**
- * Watch callback function
+ * Watch callback function (legacy)
  */
 type WatchCallback = (event: MetadataWatchEvent) => void | Promise<void>;
 interface MetadataManagerOptions extends MetadataManagerConfig {
     loaders?: MetadataLoader[];
 }
 /**
- * Main metadata manager class
+ * Main metadata manager class.
+ * Implements IMetadataService contract for unified metadata management.
  */
-declare class MetadataManager {
+declare class MetadataManager implements IMetadataService {
     private loaders;
     protected serializers: Map<MetadataFormat, MetadataSerializer>;
     protected logger: Logger;
     protected watchCallbacks: Map<string, Set<WatchCallback>>;
     protected config: MetadataManagerOptions;
+    private registry;
+    private overlays;
+    private typeRegistry;
+    private dependencies;
     constructor(config: MetadataManagerOptions);
+    /**
+     * Set the type registry for metadata type discovery.
+     */
+    setTypeRegistry(entries: MetadataTypeRegistryEntry[]): void;
     /**
      * Register a new metadata loader (data source)
      */
     registerLoader(loader: MetadataLoader): void;
     /**
-     * Load a single metadata item
-     * Iterates through registered loaders until found
+     * Register/save a metadata item by type
      */
-    load<T = any>(type: string, name: string, options?: MetadataLoadOptions): Promise<T | null>;
+    register(type: string, name: string, data: unknown): Promise<void>;
     /**
-     * Load multiple metadata items
-     * Aggregates results from all loaders
+     * Get a metadata item by type and name.
+     * Checks in-memory registry first, then falls back to loaders.
      */
-    loadMany<T = any>(type: string, options?: MetadataLoadOptions): Promise<T[]>;
+    get(type: string, name: string): Promise<unknown | undefined>;
     /**
-     * Save metadata to disk
+     * List all metadata items of a given type
      */
+    list(type: string): Promise<unknown[]>;
     /**
-     * Save metadata item
+     * Unregister/remove a metadata item by type and name
      */
-    save<T = any>(type: string, name: string, data: T, options?: MetadataSaveOptions): Promise<MetadataSaveResult>;
+    unregister(type: string, name: string): Promise<void>;
     /**
-     * Check if metadata item exists
+     * Check if a metadata item exists
      */
     exists(type: string, name: string): Promise<boolean>;
     /**
-     * List all items of a type
+     * List all names of metadata items of a given type
      */
-    list(type: string): Promise<string[]>;
+    listNames(type: string): Promise<string[]>;
+    /**
+     * Convenience: get an object definition by name
+     */
+    getObject(name: string): Promise<unknown | undefined>;
+    /**
+     * Convenience: list all object definitions
+     */
+    listObjects(): Promise<unknown[]>;
+    /**
+     * Unregister all metadata items from a specific package
+     */
+    unregisterPackage(packageName: string): Promise<void>;
+    /**
+     * Query metadata items with filtering, sorting, and pagination
+     */
+    query(query: MetadataQuery): Promise<MetadataQueryResult>;
+    /**
+     * Register multiple metadata items in a single batch
+     */
+    bulkRegister(items: Array<{
+        type: string;
+        name: string;
+        data: unknown;
+    }>, options?: {
+        continueOnError?: boolean;
+        validate?: boolean;
+    }): Promise<MetadataBulkResult>;
+    /**
+     * Unregister multiple metadata items in a single batch
+     */
+    bulkUnregister(items: Array<{
+        type: string;
+        name: string;
+    }>): Promise<MetadataBulkResult>;
+    private overlayKey;
+    /**
+     * Get the active overlay for a metadata item
+     */
+    getOverlay(type: string, name: string, scope?: 'platform' | 'user'): Promise<MetadataOverlay | undefined>;
+    /**
+     * Save/update an overlay for a metadata item
+     */
+    saveOverlay(overlay: MetadataOverlay): Promise<void>;
+    /**
+     * Remove an overlay, reverting to the base definition
+     */
+    removeOverlay(type: string, name: string, scope?: 'platform' | 'user'): Promise<void>;
+    /**
+     * Get the effective (merged) metadata after applying all overlays.
+     * Resolution order: system ← merge(platform) ← merge(user)
+     */
+    getEffective(type: string, name: string): Promise<unknown | undefined>;
+    /**
+     * Watch for metadata changes (IMetadataService contract).
+     * Returns a handle for unsubscribing.
+     */
+    watchService(type: string, callback: MetadataWatchCallback): MetadataWatchHandle;
+    /**
+     * Export metadata as a portable bundle
+     */
+    exportMetadata(options?: MetadataExportOptions): Promise<unknown>;
+    /**
+     * Import metadata from a portable bundle
+     */
+    importMetadata(data: unknown, options?: MetadataImportOptions): Promise<MetadataImportResult>;
+    /**
+     * Validate a metadata item against its type schema.
+     * Returns validation result with errors and warnings.
+     */
+    validate(_type: string, data: unknown): Promise<MetadataValidationResult>;
+    /**
+     * Get all registered metadata types
+     */
+    getRegisteredTypes(): Promise<string[]>;
+    /**
+     * Get detailed information about a metadata type
+     */
+    getTypeInfo(type: string): Promise<MetadataTypeInfo | undefined>;
+    /**
+     * Get metadata items that this item depends on
+     */
+    getDependencies(type: string, name: string): Promise<MetadataDependency[]>;
+    /**
+     * Get metadata items that depend on this item
+     */
+    getDependents(type: string, name: string): Promise<MetadataDependency[]>;
+    /**
+     * Register a dependency between two metadata items.
+     * Used internally to track cross-references.
+     * Duplicate dependencies (same source, target, and kind) are ignored.
+     */
+    addDependency(dep: MetadataDependency): void;
+    /**
+     * Load a single metadata item from loaders.
+     * Iterates through registered loaders until found.
+     */
+    load<T = any>(type: string, name: string, options?: MetadataLoadOptions): Promise<T | null>;
+    /**
+     * Load multiple metadata items from loaders.
+     * Aggregates results from all loaders.
+     */
+    loadMany<T = any>(type: string, options?: MetadataLoadOptions): Promise<T[]>;
+    /**
+     * Save metadata item to a loader
+     */
+    save<T = any>(type: string, name: string, data: T, options?: MetadataSaveOptions): Promise<MetadataSaveResult>;
     /**
-     * Watch for metadata changes
+     * Register a watch callback for metadata changes
      */
-    watch(type: string, callback: WatchCallback): void;
+    protected addWatchCallback(type: string, callback: WatchCallback): void;
     /**
-     * Unwatch metadata changes
+     * Remove a watch callback for metadata changes
      */
-    unwatch(type: string, callback: WatchCallback): void;
+    protected removeWatchCallback(type: string, callback: WatchCallback): void;
     /**
      * Stop all watching
      */
@@ -192,6 +311,7 @@ declare class MetadataManager {
 interface MetadataPluginOptions {
     rootDir?: string;
     watch?: boolean;
+    config?: Partial<MetadataPluginConfig>;
 }
 declare class MetadataPlugin implements Plugin {
     name: string;