@objectstack/metadata 4.0.5 → 4.1.0

package/dist/index.d.cts

@@ -156,6 +156,8 @@ declare class MetadataManager implements IMetadataService {
     private overlays;
     private typeRegistry;
     private dependencies;
+    private listCache;
+    private static readonly LIST_CACHE_TTL_MS;
     private realtimeService?;
     constructor(config: MetadataManagerOptions);
     /**
@@ -209,6 +211,9 @@ declare class MetadataManager implements IMetadataService {
      * List all metadata items of a given type
      */
     list(type: string): Promise<unknown[]>;
+    private cacheListResult;
+    /** Internal helper: drop the cached `list()` result for a type. */
+    private invalidateListCache;
     /**
      * Unregister/remove a metadata item by type and name.
      * Deletes from database-backed loaders only (same rationale as register()).
@@ -425,14 +430,17 @@ interface MetadataPluginOptions {
     artifactSource?: {
         mode: 'local-file';
         path: string;
+        fetchTimeoutMs?: number;
     } | {
         mode: 'artifact-api';
         url: string;
+        token?: string;
+        commitId?: string;
+        fetchTimeoutMs?: number;
     };
     /**
-     * Register the queryable system metadata-storage objects
-     * (`sys_object`, `sys_view`, `sys_flow`, `sys_agent`, `sys_tool`) on this
-     * kernel. Default `true` for backward compatibility.
+     * Register the `sys_metadata` + `sys_metadata_history` storage objects
+     * on this kernel. Default `true` for backward compatibility.
      *
      * Set to `false` for **per-project** kernels: in cloud / project mode the
      * control plane is the sole owner of metadata storage tables — exposing
@@ -450,89 +458,21 @@ declare class MetadataPlugin implements Plugin {
     constructor(options?: MetadataPluginOptions);
     init: (ctx: PluginContext) => Promise<void>;
     start: (ctx: PluginContext) => Promise<void>;
-    private _loadFromLocalFile;
-    private _loadFromFileSystem;
-}
-
-/**
- * Metadata Projection Service
- *
- * Implements the dual-table architecture pattern:
- * - sys_metadata: Source of truth for package management, versioning
- * - Type-specific tables (sys_object, sys_view, etc.): Queryable projections
- *
- * When metadata is saved to sys_metadata, this service projects it into
- * the appropriate type-specific table so Studio can query it via Object Protocol.
- */
-
-/**
- * Configuration for the MetadataProjector
- */
-interface MetadataProjectorOptions {
-    /** The IDataDriver instance to use for database operations */
-    driver?: IDataDriver;
-    /** The IDataEngine (ObjectQL) instance — preferred over raw driver */
-    engine?: IDataEngine;
-    /** Organization ID for multi-tenant isolation */
-    organizationId?: string;
-    /** Project ID — null = platform-global, set = project-scoped */
-    projectId?: string;
-}
-/**
- * MetadataProjector
- *
- * Handles projection from sys_metadata to type-specific tables.
- */
-declare class MetadataProjector {
-    private driver?;
-    private engine?;
-    /** Reserved for future multi-tenant projection scoping */
-    readonly scope: {
-        organizationId?: string;
-        projectId?: string;
-    };
-    private readonly typeTableMap;
-    constructor(options: MetadataProjectorOptions);
-    /**
-     * Project metadata to type-specific table
-     */
-    project(type: string, name: string, data: any): Promise<void>;
-    /**
-     * Delete projection from type-specific table
-     */
-    deleteProjection(type: string, name: string): Promise<void>;
     /**
-     * Transform metadata into projection record
+     * Fetch JSON content from a URL with configurable timeout.
      */
-    private transformToProjection;
+    private _fetchJson;
     /**
-     * Project object metadata to sys_object
+     * Parse raw artifact JSON (envelope or bare definition) and register all
+     * metadata items into the MetadataManager.
      */
-    private projectObject;
-    /**
-     * Project view metadata to sys_view
-     */
-    private projectView;
-    /**
-     * Project agent metadata to sys_agent
-     */
-    private projectAgent;
-    /**
-     * Project tool metadata to sys_tool
-     */
-    private projectTool;
-    /**
-     * Project flow metadata to sys_flow
-     */
-    private projectFlow;
-    private _findOne;
-    private _create;
-    private _update;
-    private _delete;
+    private _parseAndRegisterArtifact;
+    private _loadFromLocalFile;
     /**
-     * Generate a simple unique ID
+     * P2: Load metadata from the cloud artifact API endpoint.
      */
-    private generateId;
+    private _loadFromArtifactApi;
+    private _loadFromFileSystem;
 }
 
 /**
@@ -578,6 +518,52 @@ declare class RemoteLoader implements MetadataLoader {
     save(type: string, name: string, data: any, _options?: MetadataSaveOptions): Promise<MetadataSaveResult>;
 }
 
+/**
+ * Generic LRU (Least Recently Used) cache with optional TTL.
+ *
+ * Implementation notes:
+ * - Backed by a `Map`, which preserves insertion order. We promote entries on
+ *   read by deleting and re-inserting, so the oldest entry is always
+ *   `map.keys().next()`.
+ * - TTL is checked lazily on `get` / `has`. Expired entries are evicted on
+ *   access; we do not run a background sweeper to keep the implementation
+ *   side-effect free in serverless / edge runtimes.
+ * - Set `maxSize <= 0` to disable the size cap; set `ttl <= 0` (or omit) to
+ *   disable expiration.
+ *
+ * Designed for `DatabaseLoader` read-path caching — see
+ * `packages/metadata/src/loaders/database-loader.ts`.
+ */
+interface LRUCacheOptions {
+    /** Maximum number of entries; when exceeded, the LRU entry is evicted. */
+    maxSize?: number;
+    /** Time-to-live in milliseconds. Zero or undefined disables TTL. */
+    ttl?: number;
+}
+declare class LRUCache<K, V> {
+    private readonly map;
+    private readonly maxSize;
+    private readonly ttl;
+    private hits;
+    private misses;
+    constructor(options?: LRUCacheOptions);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    clear(): void;
+    get size(): number;
+    /** Diagnostic counters — useful for `metrics` endpoints. */
+    stats(): {
+        size: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+    /** Resets hit/miss counters without dropping cached entries. */
+    resetStats(): void;
+}
+
 /**
  * Database Metadata Loader
  *
@@ -587,6 +573,28 @@ declare class RemoteLoader implements MetadataLoader {
  * MetadataRecordSchema envelope defined in @objectstack/spec.
  */
 
+/**
+ * Cache configuration for `DatabaseLoader`.
+ *
+ * The cache sits in front of `load()`, `loadMany()`, `exists()`, `stat()`,
+ * and `list()` so that hot read paths (REST `/meta/*`, ObjectQL plan
+ * resolution, runtime overlay merges) do not hit the database on every
+ * request. All write paths (`save`, `delete`, `registerRollback`) invalidate
+ * the relevant entries.
+ *
+ * Defaults are conservative: 500 entries, 60s TTL — chosen so that single-
+ * tenant Studio usage does not burn memory and so that an external write
+ * (out-of-band SQL update) becomes visible within a minute even without
+ * realtime invalidation.
+ */
+interface DatabaseLoaderCacheOptions {
+    /** Whether the cache is active. Default: `true`. */
+    enabled?: boolean;
+    /** Max number of cached `(type, name)` entries. Default: `500`. */
+    maxSize?: number;
+    /** TTL in milliseconds. Set to `0` to disable expiry. Default: `60_000`. */
+    ttl?: number;
+}
 /**
  * Configuration for the DatabaseLoader.
  *
@@ -610,8 +618,12 @@ interface DatabaseLoaderOptions {
     projectId?: string;
     /** Enable history tracking (default: true) */
     trackHistory?: boolean;
-    /** Enable metadata projection to type-specific tables (default: true) */
-    enableProjection?: boolean;
+    /**
+     * Read-through cache configuration. Pass `{ enabled: false }` to disable
+     * caching outright (useful in tests or when the caller wants the loader to
+     * always read fresh from the database).
+     */
+    cache?: DatabaseLoaderCacheOptions;
 }
 /**
  * DatabaseLoader — Datasource-backed metadata persistence.
@@ -631,9 +643,32 @@ declare class DatabaseLoader implements MetadataLoader {
     private trackHistory;
     private schemaReady;
     private historySchemaReady;
-    private enableProjection;
-    private projector?;
+    /** (type, name) → metadata payload — primes `load()` */
+    private readonly loadCache?;
+    /** type → array of payloads — primes `loadMany()` */
+    private readonly loadManyCache?;
+    /** type → list of names — primes `list()` */
+    private readonly listCache?;
+    /** (type, name) → MetadataStats — primes `stat()` */
+    private readonly statCache?;
     constructor(options: DatabaseLoaderOptions);
+    private cacheKey;
+    /**
+     * Invalidate all cached entries for a specific (type, name) pair plus
+     * the type-level aggregates (`loadMany`, `list`). Called from every write
+     * path (`save`, `delete`, `registerRollback`).
+     */
+    private invalidate;
+    /** Drop the entire cache — useful after bulk imports or schema changes. */
+    invalidateAll(): void;
+    /** Diagnostic: aggregated cache statistics for `metrics` endpoints. */
+    getCacheStats(): {
+        enabled: boolean;
+        load: ReturnType<LRUCache<string, unknown>['stats']> | null;
+        loadMany: ReturnType<LRUCache<string, unknown>['stats']> | null;
+        list: ReturnType<LRUCache<string, unknown>['stats']> | null;
+        stat: ReturnType<LRUCache<string, unknown>['stats']> | null;
+    };
     private _find;
     private _findOne;
     private _count;
@@ -887,4 +922,4 @@ declare class TypeScriptSerializer implements MetadataSerializer {
     getFormat(): MetadataFormat;
 }
 
-export { DatabaseLoader, type DatabaseLoaderOptions, HistoryCleanupManager, JSONSerializer, MemoryLoader, type MetadataLoader, MetadataManager, type MetadataManagerOptions, MetadataPlugin, MetadataProjector, type MetadataProjectorOptions, type MetadataSerializer, index as Migration, RemoteLoader, type SerializeOptions, TypeScriptSerializer, type WatchCallback, YAMLSerializer, calculateChecksum, generateDiffSummary, generateSimpleDiff, registerMetadataHistoryRoutes };
+export { DatabaseLoader, type DatabaseLoaderOptions, HistoryCleanupManager, JSONSerializer, MemoryLoader, type MetadataLoader, MetadataManager, type MetadataManagerOptions, MetadataPlugin, type MetadataSerializer, index as Migration, RemoteLoader, type SerializeOptions, TypeScriptSerializer, type WatchCallback, YAMLSerializer, calculateChecksum, generateDiffSummary, generateSimpleDiff, registerMetadataHistoryRoutes };

package/dist/index.d.ts

@@ -156,6 +156,8 @@ declare class MetadataManager implements IMetadataService {
     private overlays;
     private typeRegistry;
     private dependencies;
+    private listCache;
+    private static readonly LIST_CACHE_TTL_MS;
     private realtimeService?;
     constructor(config: MetadataManagerOptions);
     /**
@@ -209,6 +211,9 @@ declare class MetadataManager implements IMetadataService {
      * List all metadata items of a given type
      */
     list(type: string): Promise<unknown[]>;
+    private cacheListResult;
+    /** Internal helper: drop the cached `list()` result for a type. */
+    private invalidateListCache;
     /**
      * Unregister/remove a metadata item by type and name.
      * Deletes from database-backed loaders only (same rationale as register()).
@@ -425,14 +430,17 @@ interface MetadataPluginOptions {
     artifactSource?: {
         mode: 'local-file';
         path: string;
+        fetchTimeoutMs?: number;
     } | {
         mode: 'artifact-api';
         url: string;
+        token?: string;
+        commitId?: string;
+        fetchTimeoutMs?: number;
     };
     /**
-     * Register the queryable system metadata-storage objects
-     * (`sys_object`, `sys_view`, `sys_flow`, `sys_agent`, `sys_tool`) on this
-     * kernel. Default `true` for backward compatibility.
+     * Register the `sys_metadata` + `sys_metadata_history` storage objects
+     * on this kernel. Default `true` for backward compatibility.
      *
      * Set to `false` for **per-project** kernels: in cloud / project mode the
      * control plane is the sole owner of metadata storage tables — exposing
@@ -450,89 +458,21 @@ declare class MetadataPlugin implements Plugin {
     constructor(options?: MetadataPluginOptions);
     init: (ctx: PluginContext) => Promise<void>;
     start: (ctx: PluginContext) => Promise<void>;
-    private _loadFromLocalFile;
-    private _loadFromFileSystem;
-}
-
-/**
- * Metadata Projection Service
- *
- * Implements the dual-table architecture pattern:
- * - sys_metadata: Source of truth for package management, versioning
- * - Type-specific tables (sys_object, sys_view, etc.): Queryable projections
- *
- * When metadata is saved to sys_metadata, this service projects it into
- * the appropriate type-specific table so Studio can query it via Object Protocol.
- */
-
-/**
- * Configuration for the MetadataProjector
- */
-interface MetadataProjectorOptions {
-    /** The IDataDriver instance to use for database operations */
-    driver?: IDataDriver;
-    /** The IDataEngine (ObjectQL) instance — preferred over raw driver */
-    engine?: IDataEngine;
-    /** Organization ID for multi-tenant isolation */
-    organizationId?: string;
-    /** Project ID — null = platform-global, set = project-scoped */
-    projectId?: string;
-}
-/**
- * MetadataProjector
- *
- * Handles projection from sys_metadata to type-specific tables.
- */
-declare class MetadataProjector {
-    private driver?;
-    private engine?;
-    /** Reserved for future multi-tenant projection scoping */
-    readonly scope: {
-        organizationId?: string;
-        projectId?: string;
-    };
-    private readonly typeTableMap;
-    constructor(options: MetadataProjectorOptions);
-    /**
-     * Project metadata to type-specific table
-     */
-    project(type: string, name: string, data: any): Promise<void>;
-    /**
-     * Delete projection from type-specific table
-     */
-    deleteProjection(type: string, name: string): Promise<void>;
     /**
-     * Transform metadata into projection record
+     * Fetch JSON content from a URL with configurable timeout.
      */
-    private transformToProjection;
+    private _fetchJson;
     /**
-     * Project object metadata to sys_object
+     * Parse raw artifact JSON (envelope or bare definition) and register all
+     * metadata items into the MetadataManager.
      */
-    private projectObject;
-    /**
-     * Project view metadata to sys_view
-     */
-    private projectView;
-    /**
-     * Project agent metadata to sys_agent
-     */
-    private projectAgent;
-    /**
-     * Project tool metadata to sys_tool
-     */
-    private projectTool;
-    /**
-     * Project flow metadata to sys_flow
-     */
-    private projectFlow;
-    private _findOne;
-    private _create;
-    private _update;
-    private _delete;
+    private _parseAndRegisterArtifact;
+    private _loadFromLocalFile;
     /**
-     * Generate a simple unique ID
+     * P2: Load metadata from the cloud artifact API endpoint.
      */
-    private generateId;
+    private _loadFromArtifactApi;
+    private _loadFromFileSystem;
 }
 
 /**
@@ -578,6 +518,52 @@ declare class RemoteLoader implements MetadataLoader {
     save(type: string, name: string, data: any, _options?: MetadataSaveOptions): Promise<MetadataSaveResult>;
 }
 
+/**
+ * Generic LRU (Least Recently Used) cache with optional TTL.
+ *
+ * Implementation notes:
+ * - Backed by a `Map`, which preserves insertion order. We promote entries on
+ *   read by deleting and re-inserting, so the oldest entry is always
+ *   `map.keys().next()`.
+ * - TTL is checked lazily on `get` / `has`. Expired entries are evicted on
+ *   access; we do not run a background sweeper to keep the implementation
+ *   side-effect free in serverless / edge runtimes.
+ * - Set `maxSize <= 0` to disable the size cap; set `ttl <= 0` (or omit) to
+ *   disable expiration.
+ *
+ * Designed for `DatabaseLoader` read-path caching — see
+ * `packages/metadata/src/loaders/database-loader.ts`.
+ */
+interface LRUCacheOptions {
+    /** Maximum number of entries; when exceeded, the LRU entry is evicted. */
+    maxSize?: number;
+    /** Time-to-live in milliseconds. Zero or undefined disables TTL. */
+    ttl?: number;
+}
+declare class LRUCache<K, V> {
+    private readonly map;
+    private readonly maxSize;
+    private readonly ttl;
+    private hits;
+    private misses;
+    constructor(options?: LRUCacheOptions);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    clear(): void;
+    get size(): number;
+    /** Diagnostic counters — useful for `metrics` endpoints. */
+    stats(): {
+        size: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+    /** Resets hit/miss counters without dropping cached entries. */
+    resetStats(): void;
+}
+
 /**
  * Database Metadata Loader
  *
@@ -587,6 +573,28 @@ declare class RemoteLoader implements MetadataLoader {
  * MetadataRecordSchema envelope defined in @objectstack/spec.
  */
 
+/**
+ * Cache configuration for `DatabaseLoader`.
+ *
+ * The cache sits in front of `load()`, `loadMany()`, `exists()`, `stat()`,
+ * and `list()` so that hot read paths (REST `/meta/*`, ObjectQL plan
+ * resolution, runtime overlay merges) do not hit the database on every
+ * request. All write paths (`save`, `delete`, `registerRollback`) invalidate
+ * the relevant entries.
+ *
+ * Defaults are conservative: 500 entries, 60s TTL — chosen so that single-
+ * tenant Studio usage does not burn memory and so that an external write
+ * (out-of-band SQL update) becomes visible within a minute even without
+ * realtime invalidation.
+ */
+interface DatabaseLoaderCacheOptions {
+    /** Whether the cache is active. Default: `true`. */
+    enabled?: boolean;
+    /** Max number of cached `(type, name)` entries. Default: `500`. */
+    maxSize?: number;
+    /** TTL in milliseconds. Set to `0` to disable expiry. Default: `60_000`. */
+    ttl?: number;
+}
 /**
  * Configuration for the DatabaseLoader.
  *
@@ -610,8 +618,12 @@ interface DatabaseLoaderOptions {
     projectId?: string;
     /** Enable history tracking (default: true) */
     trackHistory?: boolean;
-    /** Enable metadata projection to type-specific tables (default: true) */
-    enableProjection?: boolean;
+    /**
+     * Read-through cache configuration. Pass `{ enabled: false }` to disable
+     * caching outright (useful in tests or when the caller wants the loader to
+     * always read fresh from the database).
+     */
+    cache?: DatabaseLoaderCacheOptions;
 }
 /**
  * DatabaseLoader — Datasource-backed metadata persistence.
@@ -631,9 +643,32 @@ declare class DatabaseLoader implements MetadataLoader {
     private trackHistory;
     private schemaReady;
     private historySchemaReady;
-    private enableProjection;
-    private projector?;
+    /** (type, name) → metadata payload — primes `load()` */
+    private readonly loadCache?;
+    /** type → array of payloads — primes `loadMany()` */
+    private readonly loadManyCache?;
+    /** type → list of names — primes `list()` */
+    private readonly listCache?;
+    /** (type, name) → MetadataStats — primes `stat()` */
+    private readonly statCache?;
     constructor(options: DatabaseLoaderOptions);
+    private cacheKey;
+    /**
+     * Invalidate all cached entries for a specific (type, name) pair plus
+     * the type-level aggregates (`loadMany`, `list`). Called from every write
+     * path (`save`, `delete`, `registerRollback`).
+     */
+    private invalidate;
+    /** Drop the entire cache — useful after bulk imports or schema changes. */
+    invalidateAll(): void;
+    /** Diagnostic: aggregated cache statistics for `metrics` endpoints. */
+    getCacheStats(): {
+        enabled: boolean;
+        load: ReturnType<LRUCache<string, unknown>['stats']> | null;
+        loadMany: ReturnType<LRUCache<string, unknown>['stats']> | null;
+        list: ReturnType<LRUCache<string, unknown>['stats']> | null;
+        stat: ReturnType<LRUCache<string, unknown>['stats']> | null;
+    };
     private _find;
     private _findOne;
     private _count;
@@ -887,4 +922,4 @@ declare class TypeScriptSerializer implements MetadataSerializer {
     getFormat(): MetadataFormat;
 }
 
-export { DatabaseLoader, type DatabaseLoaderOptions, HistoryCleanupManager, JSONSerializer, MemoryLoader, type MetadataLoader, MetadataManager, type MetadataManagerOptions, MetadataPlugin, MetadataProjector, type MetadataProjectorOptions, type MetadataSerializer, index as Migration, RemoteLoader, type SerializeOptions, TypeScriptSerializer, type WatchCallback, YAMLSerializer, calculateChecksum, generateDiffSummary, generateSimpleDiff, registerMetadataHistoryRoutes };
+export { DatabaseLoader, type DatabaseLoaderOptions, HistoryCleanupManager, JSONSerializer, MemoryLoader, type MetadataLoader, MetadataManager, type MetadataManagerOptions, MetadataPlugin, type MetadataSerializer, index as Migration, RemoteLoader, type SerializeOptions, TypeScriptSerializer, type WatchCallback, YAMLSerializer, calculateChecksum, generateDiffSummary, generateSimpleDiff, registerMetadataHistoryRoutes };