@objectstack/metadata 3.0.6 → 3.0.8

package/dist/index.mjs

@@ -174,6 +174,395 @@ export default metadata;
   }
 };
 
+// src/objects/sys-metadata.object.ts
+import { ObjectSchema, Field } from "@objectstack/spec/data";
+var SysMetadataObject = ObjectSchema.create({
+  name: "sys_metadata",
+  label: "System Metadata",
+  pluralLabel: "System Metadata",
+  icon: "settings",
+  isSystem: true,
+  description: "Stores platform and user-scope metadata records (objects, views, flows, etc.)",
+  fields: {
+    /** Primary Key (UUID) */
+    id: Field.text({
+      label: "ID",
+      required: true,
+      readonly: true
+    }),
+    /** Machine name — unique identifier used in code references */
+    name: Field.text({
+      label: "Name",
+      required: true,
+      searchable: true,
+      maxLength: 255
+    }),
+    /** Metadata type (e.g. "object", "view", "flow") */
+    type: Field.text({
+      label: "Metadata Type",
+      required: true,
+      searchable: true,
+      maxLength: 100
+    }),
+    /** Namespace / module grouping (e.g. "crm", "core") */
+    namespace: Field.text({
+      label: "Namespace",
+      required: false,
+      defaultValue: "default",
+      maxLength: 100
+    }),
+    /** Package that owns/delivered this metadata */
+    package_id: Field.text({
+      label: "Package ID",
+      required: false,
+      maxLength: 255
+    }),
+    /** Who manages this record: package, platform, or user */
+    managed_by: Field.select(["package", "platform", "user"], {
+      label: "Managed By",
+      required: false
+    }),
+    /** Scope: system (code), platform (admin DB), user (personal DB) */
+    scope: Field.select(["system", "platform", "user"], {
+      label: "Scope",
+      required: true,
+      defaultValue: "platform"
+    }),
+    /** JSON payload — the actual metadata configuration */
+    metadata: Field.textarea({
+      label: "Metadata",
+      required: true,
+      description: "JSON-serialized metadata payload"
+    }),
+    /** Parent metadata name for extension/override */
+    extends: Field.text({
+      label: "Extends",
+      required: false,
+      maxLength: 255
+    }),
+    /** Merge strategy when extending parent metadata */
+    strategy: Field.select(["merge", "replace"], {
+      label: "Strategy",
+      required: false,
+      defaultValue: "merge"
+    }),
+    /** Owner user ID (for user-scope items) */
+    owner: Field.text({
+      label: "Owner",
+      required: false,
+      maxLength: 255
+    }),
+    /** Lifecycle state */
+    state: Field.select(["draft", "active", "archived", "deprecated"], {
+      label: "State",
+      required: false,
+      defaultValue: "active"
+    }),
+    /** Tenant ID for multi-tenant isolation */
+    tenant_id: Field.text({
+      label: "Tenant ID",
+      required: false,
+      maxLength: 255
+    }),
+    /** Version number for optimistic concurrency */
+    version: Field.number({
+      label: "Version",
+      required: false,
+      defaultValue: 1
+    }),
+    /** Content checksum for change detection */
+    checksum: Field.text({
+      label: "Checksum",
+      required: false,
+      maxLength: 64
+    }),
+    /** Origin of this metadata record */
+    source: Field.select(["filesystem", "database", "api", "migration"], {
+      label: "Source",
+      required: false
+    }),
+    /** Classification tags (JSON array) */
+    tags: Field.textarea({
+      label: "Tags",
+      required: false,
+      description: "JSON-serialized array of classification tags"
+    }),
+    /** Audit fields */
+    created_by: Field.text({
+      label: "Created By",
+      required: false,
+      readonly: true,
+      maxLength: 255
+    }),
+    created_at: Field.datetime({
+      label: "Created At",
+      required: false,
+      readonly: true
+    }),
+    updated_by: Field.text({
+      label: "Updated By",
+      required: false,
+      maxLength: 255
+    }),
+    updated_at: Field.datetime({
+      label: "Updated At",
+      required: false
+    })
+  },
+  indexes: [
+    { fields: ["type", "name"], unique: true },
+    { fields: ["type", "scope"] },
+    { fields: ["tenant_id"] },
+    { fields: ["state"] },
+    { fields: ["namespace"] }
+  ],
+  enable: {
+    trackHistory: true,
+    searchable: false,
+    apiEnabled: true,
+    apiMethods: ["get", "list", "create", "update", "delete"],
+    trash: false
+  }
+});
+
+// src/loaders/database-loader.ts
+var DatabaseLoader = class {
+  constructor(options) {
+    this.contract = {
+      name: "database",
+      protocol: "datasource:",
+      capabilities: {
+        read: true,
+        write: true,
+        watch: false,
+        list: true
+      }
+    };
+    this.schemaReady = false;
+    this.driver = options.driver;
+    this.tableName = options.tableName ?? "sys_metadata";
+    this.tenantId = options.tenantId;
+  }
+  /**
+   * Ensure the metadata table exists.
+   * Uses IDataDriver.syncSchema with the SysMetadataObject definition
+   * to idempotently create/update the table.
+   */
+  async ensureSchema() {
+    if (this.schemaReady) return;
+    try {
+      await this.driver.syncSchema(this.tableName, {
+        ...SysMetadataObject,
+        name: this.tableName
+      });
+      this.schemaReady = true;
+    } catch {
+      this.schemaReady = true;
+    }
+  }
+  /**
+   * Build base filter conditions for queries.
+   * Always includes tenantId when configured.
+   */
+  baseFilter(type, name) {
+    const filter = { type };
+    if (name !== void 0) {
+      filter.name = name;
+    }
+    if (this.tenantId) {
+      filter.tenant_id = this.tenantId;
+    }
+    return filter;
+  }
+  /**
+   * Convert a database row to a metadata payload.
+   * Parses the JSON `metadata` column back into an object.
+   */
+  rowToData(row) {
+    if (!row || !row.metadata) return null;
+    const payload = typeof row.metadata === "string" ? JSON.parse(row.metadata) : row.metadata;
+    return payload;
+  }
+  /**
+   * Convert a database row to a MetadataRecord-like object.
+   */
+  rowToRecord(row) {
+    return {
+      id: row.id,
+      name: row.name,
+      type: row.type,
+      namespace: row.namespace ?? "default",
+      packageId: row.package_id,
+      managedBy: row.managed_by,
+      scope: row.scope ?? "platform",
+      metadata: this.rowToData(row) ?? {},
+      extends: row.extends,
+      strategy: row.strategy ?? "merge",
+      owner: row.owner,
+      state: row.state ?? "active",
+      tenantId: row.tenant_id,
+      version: row.version ?? 1,
+      checksum: row.checksum,
+      source: row.source,
+      tags: row.tags ? typeof row.tags === "string" ? JSON.parse(row.tags) : row.tags : void 0,
+      createdBy: row.created_by,
+      createdAt: row.created_at,
+      updatedBy: row.updated_by,
+      updatedAt: row.updated_at
+    };
+  }
+  // ==========================================
+  // MetadataLoader Interface Implementation
+  // ==========================================
+  async load(type, name, _options) {
+    const startTime = Date.now();
+    await this.ensureSchema();
+    try {
+      const row = await this.driver.findOne(this.tableName, {
+        object: this.tableName,
+        where: this.baseFilter(type, name)
+      });
+      if (!row) {
+        return {
+          data: null,
+          loadTime: Date.now() - startTime
+        };
+      }
+      const data = this.rowToData(row);
+      const record = this.rowToRecord(row);
+      return {
+        data,
+        source: "database",
+        format: "json",
+        etag: record.checksum,
+        loadTime: Date.now() - startTime
+      };
+    } catch {
+      return {
+        data: null,
+        loadTime: Date.now() - startTime
+      };
+    }
+  }
+  async loadMany(type, _options) {
+    await this.ensureSchema();
+    try {
+      const rows = await this.driver.find(this.tableName, {
+        object: this.tableName,
+        where: this.baseFilter(type)
+      });
+      return rows.map((row) => this.rowToData(row)).filter((data) => data !== null);
+    } catch {
+      return [];
+    }
+  }
+  async exists(type, name) {
+    await this.ensureSchema();
+    try {
+      const count = await this.driver.count(this.tableName, {
+        object: this.tableName,
+        where: this.baseFilter(type, name)
+      });
+      return count > 0;
+    } catch {
+      return false;
+    }
+  }
+  async stat(type, name) {
+    await this.ensureSchema();
+    try {
+      const row = await this.driver.findOne(this.tableName, {
+        object: this.tableName,
+        where: this.baseFilter(type, name)
+      });
+      if (!row) return null;
+      const record = this.rowToRecord(row);
+      const metadataStr = typeof row.metadata === "string" ? row.metadata : JSON.stringify(row.metadata);
+      return {
+        size: metadataStr.length,
+        mtime: record.updatedAt ?? record.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+        format: "json",
+        etag: record.checksum
+      };
+    } catch {
+      return null;
+    }
+  }
+  async list(type) {
+    await this.ensureSchema();
+    try {
+      const rows = await this.driver.find(this.tableName, {
+        object: this.tableName,
+        where: this.baseFilter(type),
+        fields: ["name"]
+      });
+      return rows.map((row) => row.name).filter((name) => typeof name === "string");
+    } catch {
+      return [];
+    }
+  }
+  async save(type, name, data, _options) {
+    const startTime = Date.now();
+    await this.ensureSchema();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const metadataJson = JSON.stringify(data);
+    try {
+      const existing = await this.driver.findOne(this.tableName, {
+        object: this.tableName,
+        where: this.baseFilter(type, name)
+      });
+      if (existing) {
+        const version = (existing.version ?? 0) + 1;
+        await this.driver.update(this.tableName, existing.id, {
+          metadata: metadataJson,
+          version,
+          updated_at: now,
+          state: "active"
+        });
+        return {
+          success: true,
+          path: `datasource://${this.tableName}/${type}/${name}`,
+          size: metadataJson.length,
+          saveTime: Date.now() - startTime
+        };
+      } else {
+        const id = generateId();
+        await this.driver.create(this.tableName, {
+          id,
+          name,
+          type,
+          namespace: "default",
+          scope: data?.scope ?? "platform",
+          metadata: metadataJson,
+          strategy: "merge",
+          state: "active",
+          version: 1,
+          source: "database",
+          ...this.tenantId ? { tenant_id: this.tenantId } : {},
+          created_at: now,
+          updated_at: now
+        });
+        return {
+          success: true,
+          path: `datasource://${this.tableName}/${type}/${name}`,
+          size: metadataJson.length,
+          saveTime: Date.now() - startTime
+        };
+      }
+    } catch (error) {
+      throw new Error(
+        `DatabaseLoader save failed for ${type}/${name}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+};
+function generateId() {
+  if (typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return `meta_${Date.now()}_${Math.random().toString(36).substring(2, 10)}`;
+}
+
 // src/metadata-manager.ts
 var MetadataManager = class {
   constructor(config) {
@@ -206,6 +595,9 @@ var MetadataManager = class {
     if (config.loaders && config.loaders.length > 0) {
       config.loaders.forEach((loader) => this.registerLoader(loader));
     }
+    if (config.datasource && config.driver) {
+      this.setDatabaseDriver(config.driver);
+    }
   }
   /**
    * Set the type registry for metadata type discovery.
@@ -213,6 +605,21 @@ var MetadataManager = class {
   setTypeRegistry(entries) {
     this.typeRegistry = entries;
   }
+  /**
+   * 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) {
+    const tableName = this.config.tableName ?? "sys_metadata";
+    const dbLoader = new DatabaseLoader({
+      driver,
+      tableName
+    });
+    this.registerLoader(dbLoader);
+    this.logger.info("DatabaseLoader configured", { datasource: this.config.datasource, tableName });
+  }
   /**
    * Register a new metadata loader (data source)
    */
@@ -1577,12 +1984,14 @@ var MigrationExecutor = class {
   }
 };
 export {
+  DatabaseLoader,
   JSONSerializer,
   MemoryLoader,
   MetadataManager,
   MetadataPlugin,
   migration_exports as Migration,
   RemoteLoader,
+  SysMetadataObject,
   TypeScriptSerializer,
   YAMLSerializer
 };