@objectstack/metadata 15.1.0 → 16.0.0-rc.0

package/dist/index.cjs

@@ -1453,8 +1453,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.
+   *
+   * 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) {
+  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) {
@@ -1463,6 +1470,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());
     }
@@ -1492,6 +1500,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
@@ -1501,6 +1519,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)) {
@@ -1563,8 +1588,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);
@@ -1600,6 +1630,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
@@ -1936,16 +1976,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++;
@@ -1965,15 +2009,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++;
@@ -3487,6 +3533,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");
@@ -3513,6 +3567,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;
@@ -3529,7 +3584,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 (0, import_spec2.expandViewContainer)(viewObject, item)) {
             for (const w of vi._diagnostics?.warnings ?? []) {
@@ -3540,7 +3595,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;
@@ -3557,7 +3612,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++;
       }
     }
@@ -3581,7 +3636,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 });
     }
@@ -3646,7 +3701,7 @@ var MetadataPlugin = class {
               (0, import_shared.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`);