@objectstack/metadata 15.1.1 → 16.0.0-rc.1

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as System from '@objectstack/spec/system';
 import { MetadataFormat, MetadataLoaderContract, MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataSaveOptions, MetadataSaveResult, MetadataWatchEvent, MetadataManagerConfig, PackagePublishResult, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataDiffResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy } from '@objectstack/spec/system';
 export { MetadataCollectionInfo, MetadataDiffResult, MetadataExportOptions, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
-import { IMetadataService, IDataDriver, IDataEngine, IRealtimeService, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, IPubSub, ISchemaDriver } from '@objectstack/spec/contracts';
+import { IMetadataService, IDataDriver, IDataEngine, IRealtimeService, MetadataWriteOptions, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, IPubSub, 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';
@@ -208,8 +208,15 @@ declare class MetadataManager implements IMetadataService {
      * Stores in-memory registry and persists to database-backed loaders only.
      * FilesystemLoader (protocol 'file:') is read-only for static metadata and
      * should not be written to during runtime registration.
+     *
+     * Announces the write to {@link subscribe} watchers as an `added` /
+     * `changed` {@link MetadataWatchEvent}, so consumers that cache metadata
+     * (ObjectQL's SchemaRegistry bridge, the HMR SSE stream) refresh instead of
+     * serving the pre-write definition until restart. Pass `{ notify: false }`
+     * for bulk ingest that announces by other means — read
+     * {@link MetadataWriteOptions.notify} before doing so.
      */
-    register(type: string, name: string, data: unknown): Promise<void>;
+    register(type: string, name: string, data: unknown, options?: MetadataWriteOptions): Promise<void>;
     /**
      * Register a metadata item into the in-memory registry ONLY, never persisting
      * to a writable loader. Used for GitOps-managed artefacts that must be
@@ -218,6 +225,13 @@ declare class MetadataManager implements IMetadataService {
      * Addendum) declared in `*.datasource.ts` and owned by source control. Writing
      * them through `register()` would persist them to `sys_metadata` and create
      * drift between the artefact and the DB; this method avoids that.
+     *
+     * Deliberately silent: it does NOT announce to {@link subscribe} watchers.
+     * This is a boot-time seeding primitive for artefacts that source control
+     * owns — callers that mutate metadata mid-run want {@link register}, which
+     * announces. If you add a mid-run caller here, announce the change yourself
+     * (as the artifact reload path does via `metadata:reloaded`) or its
+     * consumers will read the pre-write definition until restart.
      */
     registerInMemory(type: string, name: string, data: unknown): void;
     /**
@@ -235,8 +249,13 @@ declare class MetadataManager implements IMetadataService {
     /**
      * Unregister/remove a metadata item by type and name.
      * Deletes from database-backed loaders only (same rationale as register()).
+     *
+     * Announces the removal to {@link subscribe} watchers as a `deleted`
+     * {@link MetadataWatchEvent} — the delete half of the {@link register}
+     * contract. Pass `{ notify: false }` only for teardown that announces by
+     * other means.
      */
-    unregister(type: string, name: string): Promise<void>;
+    unregister(type: string, name: string, options?: MetadataWriteOptions): Promise<void>;
     /**
      * Check if a metadata item exists
      */
@@ -313,7 +332,11 @@ declare class MetadataManager implements IMetadataService {
      */
     query(query: MetadataQuery): Promise<MetadataQueryResult>;
     /**
-     * Register multiple metadata items in a single batch
+     * Register multiple metadata items in a single batch.
+     *
+     * Announces one event per item, like {@link register}. Pass
+     * `{ notify: false }` when the batch is boot-time ingest or when the caller
+     * announces the whole set once — see {@link MetadataWriteOptions.notify}.
      */
     bulkRegister(items: Array<{
         type: string;
@@ -322,14 +345,16 @@ declare class MetadataManager implements IMetadataService {
     }>, options?: {
         continueOnError?: boolean;
         validate?: boolean;
-    }): Promise<MetadataBulkResult>;
+    } & MetadataWriteOptions): Promise<MetadataBulkResult>;
     /**
-     * Unregister multiple metadata items in a single batch
+     * Unregister multiple metadata items in a single batch.
+     *
+     * Announces one `deleted` event per item, like {@link unregister}.
      */
     bulkUnregister(items: Array<{
         type: string;
         name: string;
-    }>): Promise<MetadataBulkResult>;
+    }>, options?: MetadataWriteOptions): Promise<MetadataBulkResult>;
     private overlayKey;
     /**
      * Get the active overlay for a metadata item
@@ -595,6 +620,14 @@ declare class MetadataPlugin implements Plugin {
     private repository?;
     /** Chokidar watcher on the artifact file (local-file mode) — ADR-0008 PR-8. */
     private artifactWatcher?;
+    /**
+     * The most recently parsed artifact metadata (the plural-field record:
+     * `objects`, `views`, `data`, …). Carried on the `metadata:reloaded`
+     * payload so runtime consumers can react to collections that never enter
+     * the MetadataManager — notably seeds (`data`), whose items have no
+     * `name` and are skipped by `_parseAndRegisterArtifact`'s register loop.
+     */
+    private lastParsedMetadata?;
     constructor(options?: MetadataPluginOptions);
     init: (ctx: PluginContext) => Promise<void>;
     start: (ctx: PluginContext) => Promise<void>;
@@ -606,6 +639,14 @@ declare class MetadataPlugin implements Plugin {
     /**
      * Parse raw artifact JSON (envelope or bare definition) and register all
      * metadata items into the MetadataManager.
+     *
+     * Registers with `{ notify: false }` — one announcement per artifact, not
+     * one per item. Both callers cover the whole set already: the boot load
+     * runs before consumers have cached anything, and the reload path
+     * (`_reloadAndAnnounce`) fires `metadata:reloaded` carrying the parsed
+     * artifact once the ingest is complete. Announcing here too would emit N
+     * duplicate events per reload, each racing the batch that is still
+     * landing.
      */
     private _parseAndRegisterArtifact;
     /**

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as System from '@objectstack/spec/system';
 import { MetadataFormat, MetadataLoaderContract, MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataSaveOptions, MetadataSaveResult, MetadataWatchEvent, MetadataManagerConfig, PackagePublishResult, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataDiffResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy } from '@objectstack/spec/system';
 export { MetadataCollectionInfo, MetadataDiffResult, MetadataExportOptions, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
-import { IMetadataService, IDataDriver, IDataEngine, IRealtimeService, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, IPubSub, ISchemaDriver } from '@objectstack/spec/contracts';
+import { IMetadataService, IDataDriver, IDataEngine, IRealtimeService, MetadataWriteOptions, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, IPubSub, 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';
@@ -208,8 +208,15 @@ declare class MetadataManager implements IMetadataService {
      * Stores in-memory registry and persists to database-backed loaders only.
      * FilesystemLoader (protocol 'file:') is read-only for static metadata and
      * should not be written to during runtime registration.
+     *
+     * Announces the write to {@link subscribe} watchers as an `added` /
+     * `changed` {@link MetadataWatchEvent}, so consumers that cache metadata
+     * (ObjectQL's SchemaRegistry bridge, the HMR SSE stream) refresh instead of
+     * serving the pre-write definition until restart. Pass `{ notify: false }`
+     * for bulk ingest that announces by other means — read
+     * {@link MetadataWriteOptions.notify} before doing so.
      */
-    register(type: string, name: string, data: unknown): Promise<void>;
+    register(type: string, name: string, data: unknown, options?: MetadataWriteOptions): Promise<void>;
     /**
      * Register a metadata item into the in-memory registry ONLY, never persisting
      * to a writable loader. Used for GitOps-managed artefacts that must be
@@ -218,6 +225,13 @@ declare class MetadataManager implements IMetadataService {
      * Addendum) declared in `*.datasource.ts` and owned by source control. Writing
      * them through `register()` would persist them to `sys_metadata` and create
      * drift between the artefact and the DB; this method avoids that.
+     *
+     * Deliberately silent: it does NOT announce to {@link subscribe} watchers.
+     * This is a boot-time seeding primitive for artefacts that source control
+     * owns — callers that mutate metadata mid-run want {@link register}, which
+     * announces. If you add a mid-run caller here, announce the change yourself
+     * (as the artifact reload path does via `metadata:reloaded`) or its
+     * consumers will read the pre-write definition until restart.
      */
     registerInMemory(type: string, name: string, data: unknown): void;
     /**
@@ -235,8 +249,13 @@ declare class MetadataManager implements IMetadataService {
     /**
      * Unregister/remove a metadata item by type and name.
      * Deletes from database-backed loaders only (same rationale as register()).
+     *
+     * Announces the removal to {@link subscribe} watchers as a `deleted`
+     * {@link MetadataWatchEvent} — the delete half of the {@link register}
+     * contract. Pass `{ notify: false }` only for teardown that announces by
+     * other means.
      */
-    unregister(type: string, name: string): Promise<void>;
+    unregister(type: string, name: string, options?: MetadataWriteOptions): Promise<void>;
     /**
      * Check if a metadata item exists
      */
@@ -313,7 +332,11 @@ declare class MetadataManager implements IMetadataService {
      */
     query(query: MetadataQuery): Promise<MetadataQueryResult>;
     /**
-     * Register multiple metadata items in a single batch
+     * Register multiple metadata items in a single batch.
+     *
+     * Announces one event per item, like {@link register}. Pass
+     * `{ notify: false }` when the batch is boot-time ingest or when the caller
+     * announces the whole set once — see {@link MetadataWriteOptions.notify}.
      */
     bulkRegister(items: Array<{
         type: string;
@@ -322,14 +345,16 @@ declare class MetadataManager implements IMetadataService {
     }>, options?: {
         continueOnError?: boolean;
         validate?: boolean;
-    }): Promise<MetadataBulkResult>;
+    } & MetadataWriteOptions): Promise<MetadataBulkResult>;
     /**
-     * Unregister multiple metadata items in a single batch
+     * Unregister multiple metadata items in a single batch.
+     *
+     * Announces one `deleted` event per item, like {@link unregister}.
      */
     bulkUnregister(items: Array<{
         type: string;
         name: string;
-    }>): Promise<MetadataBulkResult>;
+    }>, options?: MetadataWriteOptions): Promise<MetadataBulkResult>;
     private overlayKey;
     /**
      * Get the active overlay for a metadata item
@@ -595,6 +620,14 @@ declare class MetadataPlugin implements Plugin {
     private repository?;
     /** Chokidar watcher on the artifact file (local-file mode) — ADR-0008 PR-8. */
     private artifactWatcher?;
+    /**
+     * The most recently parsed artifact metadata (the plural-field record:
+     * `objects`, `views`, `data`, …). Carried on the `metadata:reloaded`
+     * payload so runtime consumers can react to collections that never enter
+     * the MetadataManager — notably seeds (`data`), whose items have no
+     * `name` and are skipped by `_parseAndRegisterArtifact`'s register loop.
+     */
+    private lastParsedMetadata?;
     constructor(options?: MetadataPluginOptions);
     init: (ctx: PluginContext) => Promise<void>;
     start: (ctx: PluginContext) => Promise<void>;
@@ -606,6 +639,14 @@ declare class MetadataPlugin implements Plugin {
     /**
      * Parse raw artifact JSON (envelope or bare definition) and register all
      * metadata items into the MetadataManager.
+     *
+     * Registers with `{ notify: false }` — one announcement per artifact, not
+     * one per item. Both callers cover the whole set already: the boot load
+     * runs before consumers have cached anything, and the reload path
+     * (`_reloadAndAnnounce`) fires `metadata:reloaded` carrying the parsed
+     * artifact once the ingest is complete. Announcing here too would emit N
+     * duplicate events per reload, each racing the batch that is still
+     * landing.
      */
     private _parseAndRegisterArtifact;
     /**

package/dist/index.js

@@ -1410,8 +1410,15 @@ var _MetadataManager = class _MetadataManager {
    * Stores in-memory registry and persists to database-backed loaders only.
    * FilesystemLoader (protocol 'file:') is read-only for static metadata and
    * should not be written to during runtime registration.
-   */
-  async register(type, name, data) {
+   *
+   * Announces the write to {@link subscribe} watchers as an `added` /
+   * `changed` {@link MetadataWatchEvent}, so consumers that cache metadata
+   * (ObjectQL's SchemaRegistry bridge, the HMR SSE stream) refresh instead of
+   * serving the pre-write definition until restart. Pass `{ notify: false }`
+   * for bulk ingest that announces by other means — read
+   * {@link MetadataWriteOptions.notify} before doing so.
+   */
+  async register(type, name, data, options) {
     if (this.config.persistence?.writable === false) {
       const msg = `MetadataManager is read-only (persistence.writable=false); refusing to register ${type}/${name}`;
       if (this.config.validation?.throwOnError) {
@@ -1420,6 +1427,7 @@ var _MetadataManager = class _MetadataManager {
       this.logger.warn(msg);
       return;
     }
+    const existed = this.registry.get(type)?.has(name) ?? false;
     if (!this.registry.has(type)) {
       this.registry.set(type, /* @__PURE__ */ new Map());
     }
@@ -1449,6 +1457,16 @@ var _MetadataManager = class _MetadataManager {
         this.logger.warn(`Failed to publish metadata event`, { type, name, error });
       }
     }
+    if (options?.notify !== false) {
+      this.notifyWatchers(type, {
+        type: existed ? "changed" : "added",
+        metadataType: type,
+        name,
+        path: "",
+        data,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
   }
   /**
    * Register a metadata item into the in-memory registry ONLY, never persisting
@@ -1458,6 +1476,13 @@ var _MetadataManager = class _MetadataManager {
    * Addendum) declared in `*.datasource.ts` and owned by source control. Writing
    * them through `register()` would persist them to `sys_metadata` and create
    * drift between the artefact and the DB; this method avoids that.
+   *
+   * Deliberately silent: it does NOT announce to {@link subscribe} watchers.
+   * This is a boot-time seeding primitive for artefacts that source control
+   * owns — callers that mutate metadata mid-run want {@link register}, which
+   * announces. If you add a mid-run caller here, announce the change yourself
+   * (as the artifact reload path does via `metadata:reloaded`) or its
+   * consumers will read the pre-write definition until restart.
    */
   registerInMemory(type, name, data) {
     if (!this.registry.has(type)) {
@@ -1520,8 +1545,13 @@ var _MetadataManager = class _MetadataManager {
   /**
    * Unregister/remove a metadata item by type and name.
    * Deletes from database-backed loaders only (same rationale as register()).
+   *
+   * Announces the removal to {@link subscribe} watchers as a `deleted`
+   * {@link MetadataWatchEvent} — the delete half of the {@link register}
+   * contract. Pass `{ notify: false }` only for teardown that announces by
+   * other means.
    */
-  async unregister(type, name) {
+  async unregister(type, name, options) {
     const typeStore = this.registry.get(type);
     if (typeStore) {
       typeStore.delete(name);
@@ -1557,6 +1587,16 @@ var _MetadataManager = class _MetadataManager {
         this.logger.warn(`Failed to publish metadata event`, { type, name, error });
       }
     }
+    if (options?.notify !== false) {
+      this.notifyWatchers(type, {
+        type: "deleted",
+        metadataType: type,
+        name,
+        path: "",
+        data: void 0,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
   }
   /**
    * Check if a metadata item exists
@@ -1893,16 +1933,20 @@ var _MetadataManager = class _MetadataManager {
   // Bulk Operations
   // ==========================================
   /**
-   * Register multiple metadata items in a single batch
+   * Register multiple metadata items in a single batch.
+   *
+   * Announces one event per item, like {@link register}. Pass
+   * `{ notify: false }` when the batch is boot-time ingest or when the caller
+   * announces the whole set once — see {@link MetadataWriteOptions.notify}.
    */
   async bulkRegister(items, options) {
-    const { continueOnError = false } = options ?? {};
+    const { continueOnError = false, notify } = options ?? {};
     let succeeded = 0;
     let failed = 0;
     const errors = [];
     for (const item of items) {
       try {
-        await this.register(item.type, item.name, item.data);
+        await this.register(item.type, item.name, item.data, { notify });
         succeeded++;
       } catch (e) {
         failed++;
@@ -1922,15 +1966,17 @@ var _MetadataManager = class _MetadataManager {
     };
   }
   /**
-   * Unregister multiple metadata items in a single batch
+   * Unregister multiple metadata items in a single batch.
+   *
+   * Announces one `deleted` event per item, like {@link unregister}.
    */
-  async bulkUnregister(items) {
+  async bulkUnregister(items, options) {
     let succeeded = 0;
     let failed = 0;
     const errors = [];
     for (const item of items) {
       try {
-        await this.unregister(item.type, item.name);
+        await this.unregister(item.type, item.name, options);
         succeeded++;
       } catch (e) {
         failed++;
@@ -3450,6 +3496,14 @@ var MetadataPlugin = class {
   /**
    * Parse raw artifact JSON (envelope or bare definition) and register all
    * metadata items into the MetadataManager.
+   *
+   * Registers with `{ notify: false }` — one announcement per artifact, not
+   * one per item. Both callers cover the whole set already: the boot load
+   * runs before consumers have cached anything, and the reload path
+   * (`_reloadAndAnnounce`) fires `metadata:reloaded` carrying the parsed
+   * artifact once the ingest is complete. Announcing here too would emit N
+   * duplicate events per reload, each racing the batch that is still
+   * landing.
    */
   async _parseAndRegisterArtifact(ctx, raw, label) {
     const { EnvironmentArtifactSchema } = await import("@objectstack/spec/cloud");
@@ -3476,6 +3530,7 @@ var MetadataPlugin = class {
       });
       metadata = def;
     }
+    this.lastParsedMetadata = metadata;
     const memLoader = new MemoryLoader();
     const manifestPackageId = metadata?.manifest?.id ?? metadata?.id ?? void 0;
     const manifestVersion = metadata?.manifest?.version ?? metadata?.version ?? void 0;
@@ -3492,7 +3547,7 @@ var MetadataPlugin = class {
             packageVersion: manifestVersion
           });
           await memLoader.save("view", viewObject, item);
-          await this.manager.register("view", viewObject, item);
+          await this.manager.register("view", viewObject, item, { notify: false });
           totalRegistered++;
           for (const vi of expandViewContainer2(viewObject, item)) {
             for (const w of vi._diagnostics?.warnings ?? []) {
@@ -3503,7 +3558,7 @@ var MetadataPlugin = class {
               packageVersion: manifestVersion
             });
             await memLoader.save("view", vi.name, vi);
-            await this.manager.register("view", vi.name, vi);
+            await this.manager.register("view", vi.name, vi, { notify: false });
             totalRegistered++;
           }
           continue;
@@ -3520,7 +3575,7 @@ var MetadataPlugin = class {
           packageVersion: manifestVersion
         });
         await memLoader.save(metaType, name, item);
-        await this.manager.register(metaType, name, item);
+        await this.manager.register(metaType, name, item, { notify: false });
         totalRegistered++;
       }
     }
@@ -3544,7 +3599,7 @@ var MetadataPlugin = class {
   async _reloadAndAnnounce(ctx, src, changed) {
     await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs);
     try {
-      await ctx.trigger("metadata:reloaded", { changed });
+      await ctx.trigger("metadata:reloaded", { changed, metadata: this.lastParsedMetadata });
     } catch (e) {
       ctx.logger.warn("[MetadataPlugin] metadata:reloaded subscriber failed", { error: e?.message });
     }
@@ -3609,7 +3664,7 @@ var MetadataPlugin = class {
               applyProtection(meta, {
                 packageId: this.options.packageId
               });
-              await this.manager.register(entry.type, meta.name, item);
+              await this.manager.register(entry.type, meta.name, item, { notify: false });
             }
           }
           ctx.logger.info(`Loaded ${items.length} ${entry.type} from file system`);