@objectstack/metadata 3.0.6 → 3.0.7

package/dist/index.d.ts

@@ -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 };