@objectstack/metadata 15.1.1 → 16.0.0-rc.0

package/dist/node.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`);