@objectstack/metadata 3.0.6 → 3.0.7

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/metadata@3.0.6 build /home/runner/work/spec/spec/packages/metadata
+> @objectstack/metadata@3.0.7 build /home/runner/work/spec/spec/packages/metadata
 > tsup --config ../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-CJS dist/index.js     46.91 KB
-CJS dist/index.js.map 93.62 KB
-CJS ⚡️ Build success in 110ms
-ESM dist/index.mjs     45.10 KB
-ESM dist/index.mjs.map 91.64 KB
-ESM ⚡️ Build success in 117ms
+ESM dist/index.mjs     56.54 KB
+ESM dist/index.mjs.map 115.11 KB
+ESM ⚡️ Build success in 177ms
+CJS dist/index.js     58.68 KB
+CJS dist/index.js.map 117.29 KB
+CJS ⚡️ Build success in 193ms
 DTS Build start
-DTS ⚡️ Build success in 10691ms
-DTS dist/index.d.mts 15.42 KB
-DTS dist/index.d.ts  15.42 KB
+DTS ⚡️ Build success in 18192ms
+DTS dist/index.d.mts 30.37 KB
+DTS dist/index.d.ts  30.37 KB

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @objectstack/metadata
 
+## 3.0.7
+
+### Patch Changes
+
+- Updated dependencies [0119bd7]
+- Updated dependencies [5426bdf]
+  - @objectstack/spec@3.0.7
+  - @objectstack/core@3.0.7
+  - @objectstack/types@3.0.7
+
 ## 3.0.6
 
 ### Patch Changes

package/ROADMAP.md

@@ -1,5 +1,6 @@
 # @objectstack/metadata — Roadmap
 
+> **Last Updated:** 2026-02-18  
 > Development roadmap for the ObjectStack Metadata Service.
 
 ## Current Status (v3.0)
@@ -13,6 +14,7 @@
 | `FilesystemLoader`               | File I/O with glob, caching, ETag, atomic writes |
 | `MemoryLoader`                   | In-memory storage for tests and overrides       |
 | `RemoteLoader`                   | HTTP API loader with Bearer auth                |
+| `DatabaseLoader`                 | Datasource-backed persistence via `IDataDriver` |
 | JSON / YAML / TypeScript serializers | Multi-format metadata serialization          |
 | Overlay system (in-memory)       | Three-scope delta patches (system/platform/user) |
 | Query / Search                   | Filtering, pagination, sorting by type/scope/state |
@@ -36,7 +38,7 @@
 
 ---
 
-## Phase 1: DatabaseLoader — Datasource-Backed Persistence 🔴
+## Phase 1: DatabaseLoader — Datasource-Backed Persistence ✅
 
 **Goal**: Enable metadata read/write via any configured `IDataDriver`, so that platform-scope and user-scope metadata can be stored in a database.
 
@@ -44,7 +46,7 @@
 
 ### Tasks
 
-- [ ] **Implement `DatabaseLoader`** (`src/loaders/database-loader.ts`)
+- [x] **Implement `DatabaseLoader`** (`src/loaders/database-loader.ts`)
   - Implement `MetadataLoader` interface with protocol `datasource:`
   - Accept an `IDataDriver` instance (injected at initialization)
   - Read/write to the `sys_metadata` table (configurable via `MetadataManagerConfig.tableName`)
@@ -58,21 +60,20 @@
   - Implement `save()` with upsert semantics (create or update)
   - Declare capabilities: `{ read: true, write: true, watch: false, list: true }`
 
-- [ ] **Integrate DatabaseLoader into MetadataManager**
-  - Auto-configure `DatabaseLoader` when `config.datasource` is set
-  - Resolve datasource → `IDataDriver` via kernel service registry (`driver.{name}`)
-  - Implement fallback strategy: if DB unavailable, fall back to filesystem or memory per config
+- [x] **Integrate DatabaseLoader into MetadataManager**
+  - Auto-configure `DatabaseLoader` when `config.datasource` + `config.driver` is set
+  - `setDatabaseDriver(driver)` for deferred setup via kernel service registry
   - Loader priority: DatabaseLoader for platform/user scope, FilesystemLoader for system scope
 
-- [ ] **Schema bootstrapping**
-  - Auto-create `sys_metadata` table on first use via `ISchemaDriver.createCollection()`
+- [x] **Schema bootstrapping**
+  - Auto-create `sys_metadata` table on first use via `IDataDriver.syncSchema()`
   - Define column schema: `id`, `name`, `type`, `namespace`, `scope`, `metadata` (JSON), `state`, `version`, `tenant_id`, audit fields
-  - Support schema migration for future column additions
+  - Idempotent — only calls syncSchema once per loader instance
 
-- [ ] **Tests**
-  - Unit tests with `MemoryLoader` as mock driver
-  - Integration test pattern for DatabaseLoader ↔ IDataDriver
-  - Fallback behavior tests (datasource unavailable → filesystem)
+- [x] **Tests**
+  - Unit tests with mock IDataDriver (31 tests)
+  - Integration tests for MetadataManager + DatabaseLoader (9 tests)
+  - Error handling and fallback behavior tests
 
 ### Spec Dependencies (Already Defined)
 

package/dist/index.d.mts

@@ -1,11 +1,12 @@
 import { MetadataFormat, MetadataLoaderContract, MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataSaveOptions, MetadataSaveResult, MetadataWatchEvent, MetadataManagerConfig } from '@objectstack/spec/system';
 export { MetadataCollectionInfo, MetadataExportOptions, MetadataFormat, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
-import { IMetadataService, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, ISchemaDriver } from '@objectstack/spec/contracts';
+import { IMetadataService, IDataDriver, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, 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';
 import { Logger, Plugin, PluginContext } from '@objectstack/core';
 import { z } from 'zod';
+import * as _objectstack_spec_data from '@objectstack/spec/data';
 import { System } from '@objectstack/spec';
 
 /**
@@ -138,6 +139,8 @@ interface MetadataLoader {
 type WatchCallback = (event: MetadataWatchEvent) => void | Promise<void>;
 interface MetadataManagerOptions extends MetadataManagerConfig {
     loaders?: MetadataLoader[];
+    /** Optional IDataDriver instance. When provided alongside config.datasource, auto-configures DatabaseLoader. */
+    driver?: IDataDriver;
 }
 /**
  * Main metadata manager class.
@@ -158,6 +161,13 @@ declare class MetadataManager implements IMetadataService {
      * Set the type registry for metadata type discovery.
      */
     setTypeRegistry(entries: MetadataTypeRegistryEntry[]): void;
+    /**
+     * Configure and register a DatabaseLoader for database-backed metadata persistence.
+     * Can be called at any time to enable database storage (e.g. after kernel resolves the driver).
+     *
+     * @param driver - An IDataDriver instance for database operations
+     */
+    setDatabaseDriver(driver: IDataDriver): void;
     /**
      * Register a new metadata loader (data source)
      */
@@ -384,6 +394,392 @@ declare class RemoteLoader implements MetadataLoader {
     save(type: string, name: string, data: any, _options?: MetadataSaveOptions): Promise<MetadataSaveResult>;
 }
 
+/**
+ * Database Metadata Loader
+ *
+ * Loads and persists metadata via an IDataDriver instance, enabling
+ * database-backed storage for platform and user scoped metadata.
+ * Uses the `sys_metadata` table (configurable) following the
+ * MetadataRecordSchema envelope defined in @objectstack/spec.
+ */
+
+/**
+ * Configuration for the DatabaseLoader.
+ */
+interface DatabaseLoaderOptions {
+    /** The IDataDriver instance to use for database operations */
+    driver: IDataDriver;
+    /** The table name to store metadata records (default: 'sys_metadata') */
+    tableName?: string;
+    /** Tenant ID for multi-tenant isolation */
+    tenantId?: string;
+}
+/**
+ * DatabaseLoader — Datasource-backed metadata persistence.
+ *
+ * Implements the MetadataLoader interface to provide database read/write
+ * for metadata records. Uses the MetadataRecordSchema envelope to persist
+ * metadata with scope, versioning, and audit fields.
+ */
+declare class DatabaseLoader implements MetadataLoader {
+    readonly contract: MetadataLoaderContract;
+    private driver;
+    private tableName;
+    private tenantId?;
+    private schemaReady;
+    constructor(options: DatabaseLoaderOptions);
+    /**
+     * Ensure the metadata table exists.
+     * Uses IDataDriver.syncSchema with the SysMetadataObject definition
+     * to idempotently create/update the table.
+     */
+    private ensureSchema;
+    /**
+     * Build base filter conditions for queries.
+     * Always includes tenantId when configured.
+     */
+    private baseFilter;
+    /**
+     * Convert a database row to a metadata payload.
+     * Parses the JSON `metadata` column back into an object.
+     */
+    private rowToData;
+    /**
+     * Convert a database row to a MetadataRecord-like object.
+     */
+    private rowToRecord;
+    load(type: string, name: string, _options?: MetadataLoadOptions): Promise<MetadataLoadResult>;
+    loadMany<T = any>(type: string, _options?: MetadataLoadOptions): Promise<T[]>;
+    exists(type: string, name: string): Promise<boolean>;
+    stat(type: string, name: string): Promise<MetadataStats | null>;
+    list(type: string): Promise<string[]>;
+    save(type: string, name: string, data: any, _options?: MetadataSaveOptions): Promise<MetadataSaveResult>;
+}
+
+/**
+ * XState-inspired State Machine Protocol
+ * Used to define strict business logic constraints and lifecycle management.
+ * Prevent AI "hallucinations" by enforcing valid valid transitions.
+ */
+/**
+ * References a named action (side effect)
+ * Can be a script, a webhook, or a field update.
+ */
+declare const ActionRefSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    type: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>]>;
+/**
+ * State Transition Definition
+ * "When EVENT happens, if GUARD is true, go to TARGET and run ACTIONS"
+ */
+declare const TransitionSchema: z.ZodObject<{
+    target: z.ZodOptional<z.ZodString>;
+    cond: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        type: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>]>>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        type: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>]>>>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ActionRef = z.infer<typeof ActionRefSchema>;
+type Transition = z.infer<typeof TransitionSchema>;
+type StateNodeConfig = {
+    type?: 'atomic' | 'compound' | 'parallel' | 'final' | 'history';
+    entry?: ActionRef[];
+    exit?: ActionRef[];
+    on?: Record<string, string | Transition | Transition[]>;
+    always?: Transition[];
+    initial?: string;
+    states?: Record<string, StateNodeConfig>;
+    meta?: {
+        label?: string;
+        description?: string;
+        color?: string;
+        aiInstructions?: string;
+    };
+};
+
+/**
+ * sys_metadata — System Metadata Object
+ *
+ * Canonical ObjectStack object definition for the metadata persistence table.
+ * Stores all platform-scope and user-scope metadata records (Objects, Views,
+ * Flows, etc.) using the MetadataRecordSchema envelope.
+ *
+ * This is a system object (isSystem: true) — protected from deletion and
+ * automatically provisioned by the DatabaseLoader on first use.
+ *
+ * @see MetadataRecordSchema in metadata-persistence.zod.ts
+ */
+declare const SysMetadataObject: {
+    name: string;
+    active: boolean;
+    isSystem: boolean;
+    abstract: boolean;
+    datasource: string;
+    fields: Record<string, {
+        type: "number" | "boolean" | "json" | "tags" | "date" | "lookup" | "file" | "text" | "textarea" | "email" | "url" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "datetime" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "master_detail" | "tree" | "image" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "code" | "color" | "rating" | "slider" | "signature" | "qrcode" | "progress" | "vector";
+        required: boolean;
+        searchable: boolean;
+        multiple: boolean;
+        unique: boolean;
+        deleteBehavior: "set_null" | "cascade" | "restrict";
+        auditTrail: boolean;
+        hidden: boolean;
+        readonly: boolean;
+        sortable: boolean;
+        index: boolean;
+        externalId: boolean;
+        name?: string | undefined;
+        label?: string | undefined;
+        description?: string | undefined;
+        format?: string | undefined;
+        defaultValue?: unknown;
+        maxLength?: number | undefined;
+        minLength?: number | undefined;
+        precision?: number | undefined;
+        scale?: number | undefined;
+        min?: number | undefined;
+        max?: number | undefined;
+        options?: {
+            label: string;
+            value: string;
+            color?: string | undefined;
+            default?: boolean | undefined;
+        }[] | undefined;
+        reference?: string | undefined;
+        referenceFilters?: string[] | undefined;
+        writeRequiresMasterRead?: boolean | undefined;
+        expression?: string | undefined;
+        summaryOperations?: {
+            object: string;
+            field: string;
+            function: "min" | "max" | "count" | "sum" | "avg";
+        } | undefined;
+        language?: string | undefined;
+        theme?: string | undefined;
+        lineNumbers?: boolean | undefined;
+        maxRating?: number | undefined;
+        allowHalf?: boolean | undefined;
+        displayMap?: boolean | undefined;
+        allowGeocoding?: boolean | undefined;
+        addressFormat?: "us" | "uk" | "international" | undefined;
+        colorFormat?: "hex" | "rgb" | "rgba" | "hsl" | undefined;
+        allowAlpha?: boolean | undefined;
+        presetColors?: string[] | undefined;
+        step?: number | undefined;
+        showValue?: boolean | undefined;
+        marks?: Record<string, string> | undefined;
+        barcodeFormat?: "qr" | "ean13" | "ean8" | "code128" | "code39" | "upca" | "upce" | undefined;
+        qrErrorCorrection?: "L" | "M" | "Q" | "H" | undefined;
+        displayValue?: boolean | undefined;
+        allowScanning?: boolean | undefined;
+        currencyConfig?: {
+            precision: number;
+            currencyMode: "dynamic" | "fixed";
+            defaultCurrency: string;
+        } | undefined;
+        vectorConfig?: {
+            dimensions: number;
+            distanceMetric: "cosine" | "euclidean" | "dotProduct" | "manhattan";
+            normalized: boolean;
+            indexed: boolean;
+            indexType?: "hnsw" | "ivfflat" | "flat" | undefined;
+        } | undefined;
+        fileAttachmentConfig?: {
+            virusScan: boolean;
+            virusScanOnUpload: boolean;
+            quarantineOnThreat: boolean;
+            allowMultiple: boolean;
+            allowReplace: boolean;
+            allowDelete: boolean;
+            requireUpload: boolean;
+            extractMetadata: boolean;
+            extractText: boolean;
+            versioningEnabled: boolean;
+            publicRead: boolean;
+            presignedUrlExpiry: number;
+            minSize?: number | undefined;
+            maxSize?: number | undefined;
+            allowedTypes?: string[] | undefined;
+            blockedTypes?: string[] | undefined;
+            allowedMimeTypes?: string[] | undefined;
+            blockedMimeTypes?: string[] | undefined;
+            virusScanProvider?: "custom" | "clamav" | "virustotal" | "metadefender" | undefined;
+            storageProvider?: string | undefined;
+            storageBucket?: string | undefined;
+            storagePrefix?: string | undefined;
+            imageValidation?: {
+                generateThumbnails: boolean;
+                preserveMetadata: boolean;
+                autoRotate: boolean;
+                minWidth?: number | undefined;
+                maxWidth?: number | undefined;
+                minHeight?: number | undefined;
+                maxHeight?: number | undefined;
+                aspectRatio?: string | undefined;
+                thumbnailSizes?: {
+                    name: string;
+                    width: number;
+                    height: number;
+                    crop: boolean;
+                }[] | undefined;
+            } | undefined;
+            maxVersions?: number | undefined;
+        } | undefined;
+        encryptionConfig?: {
+            enabled: boolean;
+            algorithm: "aes-256-gcm" | "aes-256-cbc" | "chacha20-poly1305";
+            keyManagement: {
+                provider: "local" | "aws-kms" | "azure-key-vault" | "gcp-kms" | "hashicorp-vault";
+                keyId?: string | undefined;
+                rotationPolicy?: {
+                    enabled: boolean;
+                    frequencyDays: number;
+                    retainOldVersions: number;
+                    autoRotate: boolean;
+                } | undefined;
+            };
+            scope: "field" | "table" | "record" | "database";
+            deterministicEncryption: boolean;
+            searchableEncryption: boolean;
+        } | undefined;
+        maskingRule?: {
+            field: string;
+            strategy: "hash" | "redact" | "partial" | "tokenize" | "randomize" | "nullify" | "substitute";
+            preserveFormat: boolean;
+            preserveLength: boolean;
+            pattern?: string | undefined;
+            roles?: string[] | undefined;
+            exemptRoles?: string[] | undefined;
+        } | undefined;
+        dependencies?: string[] | undefined;
+        cached?: {
+            enabled: boolean;
+            ttl: number;
+            invalidateOn: string[];
+        } | undefined;
+        dataQuality?: {
+            uniqueness: boolean;
+            completeness: number;
+            accuracy?: {
+                source: string;
+                threshold: number;
+            } | undefined;
+        } | undefined;
+        group?: string | undefined;
+        conditionalRequired?: string | undefined;
+        inlineHelpText?: string | undefined;
+        trackFeedHistory?: boolean | undefined;
+        caseSensitive?: boolean | undefined;
+        autonumberFormat?: string | undefined;
+    }>;
+    label?: string | undefined;
+    pluralLabel?: string | undefined;
+    description?: string | undefined;
+    icon?: string | undefined;
+    tags?: string[] | undefined;
+    tableName?: string | undefined;
+    indexes?: {
+        fields: string[];
+        type: "hash" | "btree" | "gin" | "gist" | "fulltext";
+        unique: boolean;
+        name?: string | undefined;
+        partial?: string | undefined;
+    }[] | undefined;
+    tenancy?: {
+        enabled: boolean;
+        strategy: "shared" | "isolated" | "hybrid";
+        tenantField: string;
+        crossTenantAccess: boolean;
+    } | undefined;
+    softDelete?: {
+        enabled: boolean;
+        field: string;
+        cascadeDelete: boolean;
+    } | undefined;
+    versioning?: {
+        enabled: boolean;
+        strategy: "snapshot" | "delta" | "event-sourcing";
+        versionField: string;
+        retentionDays?: number | undefined;
+    } | undefined;
+    partitioning?: {
+        enabled: boolean;
+        strategy: "hash" | "range" | "list";
+        key: string;
+        interval?: string | undefined;
+    } | undefined;
+    cdc?: {
+        enabled: boolean;
+        events: ("update" | "delete" | "insert")[];
+        destination: string;
+    } | undefined;
+    validations?: _objectstack_spec_data.BaseValidationRuleShape[] | undefined;
+    stateMachines?: Record<string, {
+        id: string;
+        initial: string;
+        states: Record<string, StateNodeConfig>;
+        description?: string | undefined;
+        contextSchema?: Record<string, unknown> | undefined;
+        on?: Record<string, string | {
+            target?: string | undefined;
+            cond?: string | {
+                type: string;
+                params?: Record<string, unknown> | undefined;
+            } | undefined;
+            actions?: (string | {
+                type: string;
+                params?: Record<string, unknown> | undefined;
+            })[] | undefined;
+            description?: string | undefined;
+        } | {
+            target?: string | undefined;
+            cond?: string | {
+                type: string;
+                params?: Record<string, unknown> | undefined;
+            } | undefined;
+            actions?: (string | {
+                type: string;
+                params?: Record<string, unknown> | undefined;
+            })[] | undefined;
+            description?: string | undefined;
+        }[]> | undefined;
+    }> | undefined;
+    displayNameField?: string | undefined;
+    recordName?: {
+        type: "text" | "autonumber";
+        displayFormat?: string | undefined;
+        startNumber?: number | undefined;
+    } | undefined;
+    titleFormat?: string | undefined;
+    compactLayout?: string[] | undefined;
+    search?: {
+        fields: string[];
+        displayFields?: string[] | undefined;
+        filters?: string[] | undefined;
+    } | undefined;
+    enable?: {
+        trackHistory: boolean;
+        searchable: boolean;
+        apiEnabled: boolean;
+        files: boolean;
+        feeds: boolean;
+        activities: boolean;
+        trash: boolean;
+        mru: boolean;
+        clone: boolean;
+        apiMethods?: ("create" | "search" | "list" | "update" | "delete" | "upsert" | "history" | "get" | "bulk" | "aggregate" | "restore" | "purge" | "import" | "export")[] | undefined;
+    } | undefined;
+    recordTypes?: string[] | undefined;
+    sharingModel?: "full" | "private" | "read" | "read_write" | undefined;
+    keyPrefix?: string | undefined;
+};
+
 /**
  * JSON Metadata Serializer
  *
@@ -439,4 +835,4 @@ declare class TypeScriptSerializer implements MetadataSerializer {
     getFormat(): MetadataFormat;
 }
 
-export { JSONSerializer, MemoryLoader, type MetadataLoader, MetadataManager, type MetadataManagerOptions, MetadataPlugin, type MetadataSerializer, index as Migration, RemoteLoader, type SerializeOptions, TypeScriptSerializer, type WatchCallback, YAMLSerializer };
+export { DatabaseLoader, type DatabaseLoaderOptions, JSONSerializer, MemoryLoader, type MetadataLoader, MetadataManager, type MetadataManagerOptions, MetadataPlugin, type MetadataSerializer, index as Migration, RemoteLoader, type SerializeOptions, SysMetadataObject, TypeScriptSerializer, type WatchCallback, YAMLSerializer };