@objectstack/metadata 4.1.1 → 5.0.0

package/dist/index.d.cts

@@ -7,6 +7,8 @@ import { MetadataTypeRegistryEntry, MetadataQuery, MetadataQueryResult, Metadata
 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 { MetadataRepository } from '@objectstack/metadata-core';
+export { HistoryOptions, MetaRef, MetadataEvent, MetadataItem, MetadataItemHeader, MetadataRepository, WatchFilter } from '@objectstack/metadata-core';
 export { SysMetadataHistoryObject, SysMetadataObject } from '@objectstack/platform-objects/metadata';
 
 /**
@@ -159,6 +161,9 @@ declare class MetadataManager implements IMetadataService {
     private listCache;
     private static readonly LIST_CACHE_TTL_MS;
     private realtimeService?;
+    protected repository?: MetadataRepository;
+    private repoWatchIter?;
+    private repoWatchClosed;
     constructor(config: MetadataManagerOptions);
     /**
      * Set the type registry for metadata type discovery.
@@ -327,6 +332,18 @@ declare class MetadataManager implements IMetadataService {
      * Returns a handle for unsubscribing.
      */
     watchService(type: string, callback: MetadataWatchCallback): MetadataWatchHandle;
+    /**
+     * Subscribe to raw metadata watch events for a given type.
+     *
+     * Unlike `watchService` (which maps to the IMetadataService contract and
+     * drops fields like `path`/`timestamp`), this returns the raw
+     * `MetadataWatchEvent` produced by the underlying watcher — useful for
+     * developer-facing tooling such as the HMR SSE endpoint that wants the
+     * source file path and original timestamp.
+     *
+     * @returns An unsubscribe function.
+     */
+    subscribe(type: string, callback: WatchCallback): () => void;
     /**
      * Export metadata as a portable bundle
      */
@@ -388,6 +405,34 @@ declare class MetadataManager implements IMetadataService {
      * Stop all watching
      */
     stopWatching(): Promise<void>;
+    /**
+     * Attach a {@link MetadataRepository} as a supplementary event source.
+     *
+     * The manager subscribes to `repo.watch({})` and re-emits each event
+     * through {@link notifyWatchers} as a legacy `MetadataWatchEvent`.
+     * Each event also invalidates the in-memory registry entry and the
+     * `list()` cache for the affected type so subsequent reads see fresh
+     * data.
+     *
+     * No write-through. `register()` / `unregister()` / `save()` are
+     * untouched in this PR (deferred to ADR-0008 M0 PR-10).
+     *
+     * Call {@link dispose} (or {@link stopRepositoryWatch}) to detach.
+     */
+    setRepository(repo: MetadataRepository): void;
+    /** Return the attached repository, if any. */
+    getRepository(): MetadataRepository | undefined;
+    /** Stop the active repo.watch() loop (best-effort). */
+    stopRepositoryWatch(): Promise<void>;
+    /**
+     * Best-effort cleanup. Stops the FS watcher (if any), drains the
+     * repository watch loop, and clears registry caches. Safe to call
+     * multiple times.
+     */
+    dispose(): Promise<void>;
+    private startRepositoryWatch;
+    /** Translate a repo event to the legacy MetadataWatchEvent + invalidate caches. */
+    private applyRepoEvent;
     protected notifyWatchers(type: string, event: MetadataWatchEvent): void;
     /**
      * Get the database loader for history operations.
@@ -416,7 +461,30 @@ declare class MetadataManager implements IMetadataService {
 
 interface MetadataPluginOptions {
     rootDir?: string;
+    /**
+     * When `true`, NodeMetadataManager scans `rootDir` for source-file metadata
+     * (yaml/json/ts/js loaders) AND attaches a chokidar watcher to react to
+     * filesystem changes. In **artifact-mode** (this is the normal path when
+     * a `defineStack()` config is compiled into `dist/objectstack.json`) this
+     * filesystem scan is redundant and expensive — leave `watch: false`.
+     *
+     * The artifact-file HMR watcher is controlled separately by
+     * {@link artifactWatch} so that the cheap, single-file polling watcher
+     * can be enabled in dev without paying the cost of scanning the entire
+     * project root.
+     *
+     * Default: `false` (post PR-10e — was previously `true`).
+     */
     watch?: boolean;
+    /**
+     * When `true` AND `artifactSource.mode === 'local-file'`, attach a
+     * polling chokidar watcher to the artifact file so the server reloads
+     * metadata when the CLI recompiles `dist/objectstack.json` in dev mode.
+     * Independent of {@link watch} (which controls the source-file scanner).
+     *
+     * Default: `true` when `artifactSource` is set, otherwise `false`.
+     */
+    artifactWatch?: boolean;
     config?: Partial<MetadataPluginConfig>;
     /** Organization ID for metadata-scoped consumers; MetadataPlugin itself does not persist runtime metadata. */
     organizationId?: string;
@@ -455,9 +523,13 @@ declare class MetadataPlugin implements Plugin {
     version: string;
     private manager;
     private options;
+    private repository?;
+    /** Chokidar watcher on the artifact file (local-file mode) — ADR-0008 PR-8. */
+    private artifactWatcher?;
     constructor(options?: MetadataPluginOptions);
     init: (ctx: PluginContext) => Promise<void>;
     start: (ctx: PluginContext) => Promise<void>;
+    stop: (ctx: PluginContext) => Promise<void>;
     /**
      * Fetch JSON content from a URL with configurable timeout.
      */
@@ -614,7 +686,13 @@ interface DatabaseLoaderOptions {
     historyTableName?: string;
     /** Organization ID for multi-tenant isolation */
     organizationId?: string;
-    /** Project ID — null = platform-global, set = project-scoped */
+    /**
+     * @deprecated since ADR-0008 §0 amendment (branch/project removal).
+     * The metadata layer is keyed by organization only. This option is
+     * accepted for back-compat but ignored — writes do not set
+     * `project_id` and filters do not constrain on it. Will be removed
+     * in the next major release.
+     */
     projectId?: string;
     /** Enable history tracking (default: true) */
     trackHistory?: boolean;
@@ -639,7 +717,6 @@ declare class DatabaseLoader implements MetadataLoader {
     private tableName;
     private historyTableName;
     private organizationId?;
-    private projectId?;
     private trackHistory;
     private schemaReady;
     private historySchemaReady;
@@ -675,6 +752,13 @@ declare class DatabaseLoader implements MetadataLoader {
     private _create;
     private _update;
     private _delete;
+    /**
+     * Compute the next per-org `event_seq` for `sys_metadata_history`.
+     * Reads `MAX(event_seq) + 1` for the configured `organization_id`.
+     * Legacy path — not transactional, so concurrent writes can collide.
+     * The canonical (transactional) producer is `SysMetadataRepository`.
+     */
+    private nextEventSeq;
     /**
      * Ensure the metadata table exists.
      * Uses IDataDriver.syncSchema with the SysMetadataObject definition
@@ -688,8 +772,9 @@ declare class DatabaseLoader implements MetadataLoader {
     private ensureHistorySchema;
     /**
      * Build base filter conditions for queries.
-     * Filters by organizationId when configured; project_id when projectId is set,
-     * or null (platform-global) when not set.
+     * Filters by organizationId when configured. `projectId` is accepted
+     * for back-compat but no longer constrains the query — see
+     * ADR-0008 §0 (branch/project removal).
      */
     private baseFilter;
     /**

package/dist/index.d.ts

@@ -7,6 +7,8 @@ import { MetadataTypeRegistryEntry, MetadataQuery, MetadataQueryResult, Metadata
 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 { MetadataRepository } from '@objectstack/metadata-core';
+export { HistoryOptions, MetaRef, MetadataEvent, MetadataItem, MetadataItemHeader, MetadataRepository, WatchFilter } from '@objectstack/metadata-core';
 export { SysMetadataHistoryObject, SysMetadataObject } from '@objectstack/platform-objects/metadata';
 
 /**
@@ -159,6 +161,9 @@ declare class MetadataManager implements IMetadataService {
     private listCache;
     private static readonly LIST_CACHE_TTL_MS;
     private realtimeService?;
+    protected repository?: MetadataRepository;
+    private repoWatchIter?;
+    private repoWatchClosed;
     constructor(config: MetadataManagerOptions);
     /**
      * Set the type registry for metadata type discovery.
@@ -327,6 +332,18 @@ declare class MetadataManager implements IMetadataService {
      * Returns a handle for unsubscribing.
      */
     watchService(type: string, callback: MetadataWatchCallback): MetadataWatchHandle;
+    /**
+     * Subscribe to raw metadata watch events for a given type.
+     *
+     * Unlike `watchService` (which maps to the IMetadataService contract and
+     * drops fields like `path`/`timestamp`), this returns the raw
+     * `MetadataWatchEvent` produced by the underlying watcher — useful for
+     * developer-facing tooling such as the HMR SSE endpoint that wants the
+     * source file path and original timestamp.
+     *
+     * @returns An unsubscribe function.
+     */
+    subscribe(type: string, callback: WatchCallback): () => void;
     /**
      * Export metadata as a portable bundle
      */
@@ -388,6 +405,34 @@ declare class MetadataManager implements IMetadataService {
      * Stop all watching
      */
     stopWatching(): Promise<void>;
+    /**
+     * Attach a {@link MetadataRepository} as a supplementary event source.
+     *
+     * The manager subscribes to `repo.watch({})` and re-emits each event
+     * through {@link notifyWatchers} as a legacy `MetadataWatchEvent`.
+     * Each event also invalidates the in-memory registry entry and the
+     * `list()` cache for the affected type so subsequent reads see fresh
+     * data.
+     *
+     * No write-through. `register()` / `unregister()` / `save()` are
+     * untouched in this PR (deferred to ADR-0008 M0 PR-10).
+     *
+     * Call {@link dispose} (or {@link stopRepositoryWatch}) to detach.
+     */
+    setRepository(repo: MetadataRepository): void;
+    /** Return the attached repository, if any. */
+    getRepository(): MetadataRepository | undefined;
+    /** Stop the active repo.watch() loop (best-effort). */
+    stopRepositoryWatch(): Promise<void>;
+    /**
+     * Best-effort cleanup. Stops the FS watcher (if any), drains the
+     * repository watch loop, and clears registry caches. Safe to call
+     * multiple times.
+     */
+    dispose(): Promise<void>;
+    private startRepositoryWatch;
+    /** Translate a repo event to the legacy MetadataWatchEvent + invalidate caches. */
+    private applyRepoEvent;
     protected notifyWatchers(type: string, event: MetadataWatchEvent): void;
     /**
      * Get the database loader for history operations.
@@ -416,7 +461,30 @@ declare class MetadataManager implements IMetadataService {
 
 interface MetadataPluginOptions {
     rootDir?: string;
+    /**
+     * When `true`, NodeMetadataManager scans `rootDir` for source-file metadata
+     * (yaml/json/ts/js loaders) AND attaches a chokidar watcher to react to
+     * filesystem changes. In **artifact-mode** (this is the normal path when
+     * a `defineStack()` config is compiled into `dist/objectstack.json`) this
+     * filesystem scan is redundant and expensive — leave `watch: false`.
+     *
+     * The artifact-file HMR watcher is controlled separately by
+     * {@link artifactWatch} so that the cheap, single-file polling watcher
+     * can be enabled in dev without paying the cost of scanning the entire
+     * project root.
+     *
+     * Default: `false` (post PR-10e — was previously `true`).
+     */
     watch?: boolean;
+    /**
+     * When `true` AND `artifactSource.mode === 'local-file'`, attach a
+     * polling chokidar watcher to the artifact file so the server reloads
+     * metadata when the CLI recompiles `dist/objectstack.json` in dev mode.
+     * Independent of {@link watch} (which controls the source-file scanner).
+     *
+     * Default: `true` when `artifactSource` is set, otherwise `false`.
+     */
+    artifactWatch?: boolean;
     config?: Partial<MetadataPluginConfig>;
     /** Organization ID for metadata-scoped consumers; MetadataPlugin itself does not persist runtime metadata. */
     organizationId?: string;
@@ -455,9 +523,13 @@ declare class MetadataPlugin implements Plugin {
     version: string;
     private manager;
     private options;
+    private repository?;
+    /** Chokidar watcher on the artifact file (local-file mode) — ADR-0008 PR-8. */
+    private artifactWatcher?;
     constructor(options?: MetadataPluginOptions);
     init: (ctx: PluginContext) => Promise<void>;
     start: (ctx: PluginContext) => Promise<void>;
+    stop: (ctx: PluginContext) => Promise<void>;
     /**
      * Fetch JSON content from a URL with configurable timeout.
      */
@@ -614,7 +686,13 @@ interface DatabaseLoaderOptions {
     historyTableName?: string;
     /** Organization ID for multi-tenant isolation */
     organizationId?: string;
-    /** Project ID — null = platform-global, set = project-scoped */
+    /**
+     * @deprecated since ADR-0008 §0 amendment (branch/project removal).
+     * The metadata layer is keyed by organization only. This option is
+     * accepted for back-compat but ignored — writes do not set
+     * `project_id` and filters do not constrain on it. Will be removed
+     * in the next major release.
+     */
     projectId?: string;
     /** Enable history tracking (default: true) */
     trackHistory?: boolean;
@@ -639,7 +717,6 @@ declare class DatabaseLoader implements MetadataLoader {
     private tableName;
     private historyTableName;
     private organizationId?;
-    private projectId?;
     private trackHistory;
     private schemaReady;
     private historySchemaReady;
@@ -675,6 +752,13 @@ declare class DatabaseLoader implements MetadataLoader {
     private _create;
     private _update;
     private _delete;
+    /**
+     * Compute the next per-org `event_seq` for `sys_metadata_history`.
+     * Reads `MAX(event_seq) + 1` for the configured `organization_id`.
+     * Legacy path — not transactional, so concurrent writes can collide.
+     * The canonical (transactional) producer is `SysMetadataRepository`.
+     */
+    private nextEventSeq;
     /**
      * Ensure the metadata table exists.
      * Uses IDataDriver.syncSchema with the SysMetadataObject definition
@@ -688,8 +772,9 @@ declare class DatabaseLoader implements MetadataLoader {
     private ensureHistorySchema;
     /**
      * Build base filter conditions for queries.
-     * Filters by organizationId when configured; project_id when projectId is set,
-     * or null (platform-global) when not set.
+     * Filters by organizationId when configured. `projectId` is accepted
+     * for back-compat but no longer constrains the query — see
+     * ADR-0008 §0 (branch/project removal).
      */
     private baseFilter;
     /**