@objectstack/objectql 7.8.0 → 7.9.0

package/dist/index.d.mts

@@ -719,6 +719,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         type: string;
         packageId?: string;
         organizationId?: string;
+        previewDrafts?: boolean;
     }): Promise<{
         type: string;
         items: any[];
@@ -729,10 +730,11 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         packageId?: string;
         organizationId?: string;
         state?: 'active' | 'draft';
+        previewDrafts?: boolean;
     }): Promise<{
         type: string;
         name: string;
-        item: {} | null;
+        item: any;
     } | {
         editable: boolean;
         deletable: boolean;
@@ -1155,6 +1157,23 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * simply no-op, and a sync failure must not abort the publish.
      */
     private ensureObjectStorage;
+    /**
+     * Inverse of {@link ensureObjectStorage}: drop an object's physical table.
+     * DESTRUCTIVE — deletes the table and all its rows. Only invoked when a
+     * delete explicitly opts into storage teardown (see {@link deleteMetaItem}'s
+     * `dropStorage`), so publishing an object solely to preview it can be undone
+     * without leaving an orphan table. Best-effort: a failure is logged, not
+     * thrown — the metadata delete already succeeded, and a stray table is
+     * reclaimed by the next sync/drop rather than blocking the delete.
+     */
+    private dropObjectStorage;
+    /**
+     * Guard for storage teardown on delete. Drops a physical table only when
+     * the caller opted in AND it is safe: object types only (others have no
+     * table), active state only (drafts were never materialised), and never a
+     * `sys_`-prefixed platform table.
+     */
+    private shouldDropStorage;
     saveMetaItem(request: {
         type: string;
         name: string;
@@ -1263,6 +1282,69 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             code?: string;
         }>;
     }>;
+    /**
+     * Discard every pending DRAFT bound to a package — the NON-destructive
+     * inverse of {@link publishPackageDrafts}. Drops only `state='draft'` rows
+     * (via the per-item delete primitive), reverting the package to its last
+     * published baseline; active/published metadata and physical tables are
+     * left untouched.
+     *
+     * Use case: "I edited this app for a while and it turned out worse than
+     * before — abandon all my changes." Routes through the sys_metadata path
+     * (no metadata-service dependency, unlike `POST /packages/:id/revert`).
+     */
+    discardPackageDrafts(request: {
+        packageId: string;
+        organizationId?: string;
+        actor?: string;
+    }): Promise<{
+        success: boolean;
+        discardedCount: number;
+        failedCount: number;
+        discarded: Array<{
+            type: string;
+            name: string;
+        }>;
+        failed: Array<{
+            type: string;
+            name: string;
+            error: string;
+            code?: string;
+        }>;
+    }>;
+    /**
+     * Delete an ENTIRE package: every `sys_metadata` row bound to it (active
+     * AND draft) and — by default — the physical table of each object it
+     * defined. DESTRUCTIVE: removes the app and its data. Use case: "I don't
+     * want this package anymore."
+     *
+     * Set `keepData: true` to remove the metadata but preserve object tables.
+     * The `sys_`-table guard in {@link deleteMetaItem} still applies, so
+     * platform storage is never dropped. Drafts are removed before active rows
+     * so each object's table is torn down once. Per-item failures are collected
+     * without aborting the rest.
+     */
+    deletePackage(request: {
+        packageId: string;
+        organizationId?: string;
+        actor?: string;
+        keepData?: boolean;
+    }): Promise<{
+        success: boolean;
+        deletedCount: number;
+        failedCount: number;
+        deleted: Array<{
+            type: string;
+            name: string;
+            state: string;
+        }>;
+        failed: Array<{
+            type: string;
+            name: string;
+            error: string;
+            code?: string;
+        }>;
+    }>;
     /**
      * Restore the body recorded at history `toVersion` as the new
      * live row. Writes a history event with `op='revert'`. 404
@@ -1331,6 +1413,13 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         parentVersion?: string | null;
         actor?: string;
         state?: 'active' | 'draft';
+        /**
+         * When true, also drop the object's physical table after the metadata
+         * is removed (object + active only; never `sys_`). Default false keeps
+         * delete non-destructive to data. Used by the "discard a previewed
+         * object" flow so a publish-to-preview leaves no orphan table.
+         */
+        dropStorage?: boolean;
     }): Promise<{
         success: boolean;
         message?: string;
@@ -2163,6 +2252,16 @@ declare class ObjectQL implements IDataEngine {
      * table when absent (and alters to add new columns).
      */
     syncObjectSchema(objectName: string): Promise<void>;
+    /**
+     * Drop the physical storage (table/collection) backing an object — the
+     * inverse of {@link syncObjectSchema}. DESTRUCTIVE: deletes all rows in the
+     * table. Used by the protocol delete path when the caller explicitly opts
+     * into storage teardown (e.g. discarding an object that was published only
+     * to preview it). No-op when the object's driver does not expose `dropTable`.
+     * Resolves the physical table name from the registered definition, falling
+     * back to the bare name if the def was already removed.
+     */
+    dropObjectSchema(objectName: string): Promise<void>;
     /**
      * Get a registered driver by datasource name.
      * Alias matching @objectql/core datasource() API.

package/dist/index.d.ts

@@ -719,6 +719,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         type: string;
         packageId?: string;
         organizationId?: string;
+        previewDrafts?: boolean;
     }): Promise<{
         type: string;
         items: any[];
@@ -729,10 +730,11 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         packageId?: string;
         organizationId?: string;
         state?: 'active' | 'draft';
+        previewDrafts?: boolean;
     }): Promise<{
         type: string;
         name: string;
-        item: {} | null;
+        item: any;
     } | {
         editable: boolean;
         deletable: boolean;
@@ -1155,6 +1157,23 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * simply no-op, and a sync failure must not abort the publish.
      */
     private ensureObjectStorage;
+    /**
+     * Inverse of {@link ensureObjectStorage}: drop an object's physical table.
+     * DESTRUCTIVE — deletes the table and all its rows. Only invoked when a
+     * delete explicitly opts into storage teardown (see {@link deleteMetaItem}'s
+     * `dropStorage`), so publishing an object solely to preview it can be undone
+     * without leaving an orphan table. Best-effort: a failure is logged, not
+     * thrown — the metadata delete already succeeded, and a stray table is
+     * reclaimed by the next sync/drop rather than blocking the delete.
+     */
+    private dropObjectStorage;
+    /**
+     * Guard for storage teardown on delete. Drops a physical table only when
+     * the caller opted in AND it is safe: object types only (others have no
+     * table), active state only (drafts were never materialised), and never a
+     * `sys_`-prefixed platform table.
+     */
+    private shouldDropStorage;
     saveMetaItem(request: {
         type: string;
         name: string;
@@ -1263,6 +1282,69 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             code?: string;
         }>;
     }>;
+    /**
+     * Discard every pending DRAFT bound to a package — the NON-destructive
+     * inverse of {@link publishPackageDrafts}. Drops only `state='draft'` rows
+     * (via the per-item delete primitive), reverting the package to its last
+     * published baseline; active/published metadata and physical tables are
+     * left untouched.
+     *
+     * Use case: "I edited this app for a while and it turned out worse than
+     * before — abandon all my changes." Routes through the sys_metadata path
+     * (no metadata-service dependency, unlike `POST /packages/:id/revert`).
+     */
+    discardPackageDrafts(request: {
+        packageId: string;
+        organizationId?: string;
+        actor?: string;
+    }): Promise<{
+        success: boolean;
+        discardedCount: number;
+        failedCount: number;
+        discarded: Array<{
+            type: string;
+            name: string;
+        }>;
+        failed: Array<{
+            type: string;
+            name: string;
+            error: string;
+            code?: string;
+        }>;
+    }>;
+    /**
+     * Delete an ENTIRE package: every `sys_metadata` row bound to it (active
+     * AND draft) and — by default — the physical table of each object it
+     * defined. DESTRUCTIVE: removes the app and its data. Use case: "I don't
+     * want this package anymore."
+     *
+     * Set `keepData: true` to remove the metadata but preserve object tables.
+     * The `sys_`-table guard in {@link deleteMetaItem} still applies, so
+     * platform storage is never dropped. Drafts are removed before active rows
+     * so each object's table is torn down once. Per-item failures are collected
+     * without aborting the rest.
+     */
+    deletePackage(request: {
+        packageId: string;
+        organizationId?: string;
+        actor?: string;
+        keepData?: boolean;
+    }): Promise<{
+        success: boolean;
+        deletedCount: number;
+        failedCount: number;
+        deleted: Array<{
+            type: string;
+            name: string;
+            state: string;
+        }>;
+        failed: Array<{
+            type: string;
+            name: string;
+            error: string;
+            code?: string;
+        }>;
+    }>;
     /**
      * Restore the body recorded at history `toVersion` as the new
      * live row. Writes a history event with `op='revert'`. 404
@@ -1331,6 +1413,13 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         parentVersion?: string | null;
         actor?: string;
         state?: 'active' | 'draft';
+        /**
+         * When true, also drop the object's physical table after the metadata
+         * is removed (object + active only; never `sys_`). Default false keeps
+         * delete non-destructive to data. Used by the "discard a previewed
+         * object" flow so a publish-to-preview leaves no orphan table.
+         */
+        dropStorage?: boolean;
     }): Promise<{
         success: boolean;
         message?: string;
@@ -2163,6 +2252,16 @@ declare class ObjectQL implements IDataEngine {
      * table when absent (and alters to add new columns).
      */
     syncObjectSchema(objectName: string): Promise<void>;
+    /**
+     * Drop the physical storage (table/collection) backing an object — the
+     * inverse of {@link syncObjectSchema}. DESTRUCTIVE: deletes all rows in the
+     * table. Used by the protocol delete path when the caller explicitly opts
+     * into storage teardown (e.g. discarding an object that was published only
+     * to preview it). No-op when the object's driver does not expose `dropTable`.
+     * Resolves the physical table name from the registered definition, falling
+     * back to the bare name if the def was already removed.
+     */
+    dropObjectSchema(objectName: string): Promise<void>;
     /**
      * Get a registered driver by datasource name.
      * Alias matching @objectql/core datasource() API.

package/dist/index.js

@@ -2450,6 +2450,44 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       }
     } catch {
     }
+    if (request.previewDrafts) {
+      try {
+        const orgId = request.organizationId;
+        const queryDrafts = async (oid) => {
+          const whereClause = { type: request.type, state: "draft", organization_id: oid };
+          if (packageId) whereClause.package_id = packageId;
+          let rs = await this.engine.find("sys_metadata", { where: whereClause });
+          if (!rs || rs.length === 0) {
+            const alt = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? import_shared4.SINGULAR_TO_PLURAL[request.type];
+            if (alt) {
+              const altWhere = { type: alt, state: "draft", organization_id: oid };
+              if (packageId) altWhere.package_id = packageId;
+              rs = await this.engine.find("sys_metadata", { where: altWhere });
+            }
+          }
+          return rs ?? [];
+        };
+        const draftRecords = [...await queryDrafts(null), ...orgId ? await queryDrafts(orgId) : []];
+        if (draftRecords.length > 0) {
+          const byName = /* @__PURE__ */ new Map();
+          for (const existing of items) {
+            const entry = existing;
+            if (entry && typeof entry === "object" && "name" in entry) byName.set(entry.name, entry);
+          }
+          for (const record of draftRecords) {
+            const data = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
+            if (data && typeof data === "object" && "name" in data) {
+              const recPkg = record.package_id ?? void 0;
+              if (recPkg && data._packageId === void 0) data._packageId = recPkg;
+              data._draft = true;
+              byName.set(data.name, data);
+            }
+          }
+          items = Array.from(byName.values());
+        }
+      } catch {
+      }
+    }
     try {
       const services = this.getServicesRegistry?.();
       const metadataService = services?.get("metadata");
@@ -2508,6 +2546,34 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     let item;
     const orgId = request.organizationId;
     const readState = request.state === "draft" ? "draft" : "active";
+    if (request.previewDrafts && readState !== "draft") {
+      try {
+        const findDraft = async (oid) => {
+          const rec = await this.engine.findOne("sys_metadata", {
+            where: { type: request.type, name: request.name, state: "draft", organization_id: oid }
+          });
+          if (rec) return rec;
+          const alt = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? import_shared4.SINGULAR_TO_PLURAL[request.type];
+          if (alt) {
+            return await this.engine.findOne("sys_metadata", {
+              where: { type: alt, name: request.name, state: "draft", organization_id: oid }
+            });
+          }
+          return void 0;
+        };
+        const draftRec = (orgId ? await findDraft(orgId) : void 0) ?? await findDraft(null);
+        if (draftRec) {
+          const draftItem = typeof draftRec.metadata === "string" ? JSON.parse(draftRec.metadata) : draftRec.metadata;
+          if (draftItem && typeof draftItem === "object") {
+            const recPkg = draftRec.package_id ?? void 0;
+            if (recPkg && draftItem._packageId === void 0) draftItem._packageId = recPkg;
+            draftItem._draft = true;
+          }
+          return { type: request.type, name: request.name, item: decorateMetadataItem(request.type, draftItem) };
+        }
+      } catch {
+      }
+    }
     try {
       const findOverlay = async (oid) => {
         const where = {
@@ -3882,6 +3948,37 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       console.warn(`[Protocol] table sync failed for object '${name}': ${err?.message ?? err}`);
     }
   }
+  /**
+   * Inverse of {@link ensureObjectStorage}: drop an object's physical table.
+   * DESTRUCTIVE — deletes the table and all its rows. Only invoked when a
+   * delete explicitly opts into storage teardown (see {@link deleteMetaItem}'s
+   * `dropStorage`), so publishing an object solely to preview it can be undone
+   * without leaving an orphan table. Best-effort: a failure is logged, not
+   * thrown — the metadata delete already succeeded, and a stray table is
+   * reclaimed by the next sync/drop rather than blocking the delete.
+   */
+  async dropObjectStorage(type, name) {
+    if (type !== "object" && type !== "objects") return;
+    try {
+      await this.engine.dropObjectSchema(name);
+    } catch (err) {
+      console.warn(`[Protocol] table drop failed for object '${name}': ${err?.message ?? err}`);
+    }
+  }
+  /**
+   * Guard for storage teardown on delete. Drops a physical table only when
+   * the caller opted in AND it is safe: object types only (others have no
+   * table), active state only (drafts were never materialised), and never a
+   * `sys_`-prefixed platform table.
+   */
+  shouldDropStorage(type, name, dropStorage, state) {
+    if (!dropStorage) return false;
+    const singular = import_shared4.PLURAL_TO_SINGULAR[type] ?? type;
+    if (singular !== "object") return false;
+    if (state !== "active") return false;
+    if (name.startsWith("sys_")) return false;
+    return true;
+  }
   async saveMetaItem(request) {
     if (!request.item) {
       throw new Error("Item data is required");
@@ -4262,6 +4359,100 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       failed
     };
   }
+  /**
+   * Discard every pending DRAFT bound to a package — the NON-destructive
+   * inverse of {@link publishPackageDrafts}. Drops only `state='draft'` rows
+   * (via the per-item delete primitive), reverting the package to its last
+   * published baseline; active/published metadata and physical tables are
+   * left untouched.
+   *
+   * Use case: "I edited this app for a while and it turned out worse than
+   * before — abandon all my changes." Routes through the sys_metadata path
+   * (no metadata-service dependency, unlike `POST /packages/:id/revert`).
+   */
+  async discardPackageDrafts(request) {
+    await this.ensureOverlayIndex();
+    const orgId = request.organizationId ?? null;
+    const repo = this.getOverlayRepo(orgId);
+    const drafts = await repo.listDrafts({ packageId: request.packageId });
+    const discarded = [];
+    const failed = [];
+    for (const d of drafts) {
+      try {
+        await this.deleteMetaItem({
+          type: d.type,
+          name: d.name,
+          state: "draft",
+          ...request.organizationId ? { organizationId: request.organizationId } : {},
+          ...request.actor ? { actor: request.actor } : {}
+        });
+        discarded.push({ type: d.type, name: d.name });
+      } catch (e) {
+        failed.push({
+          type: d.type,
+          name: d.name,
+          error: e?.message ?? "discard failed",
+          ...e?.code ? { code: e.code } : {}
+        });
+      }
+    }
+    return {
+      success: failed.length === 0 && discarded.length > 0,
+      discardedCount: discarded.length,
+      failedCount: failed.length,
+      discarded,
+      failed
+    };
+  }
+  /**
+   * Delete an ENTIRE package: every `sys_metadata` row bound to it (active
+   * AND draft) and — by default — the physical table of each object it
+   * defined. DESTRUCTIVE: removes the app and its data. Use case: "I don't
+   * want this package anymore."
+   *
+   * Set `keepData: true` to remove the metadata but preserve object tables.
+   * The `sys_`-table guard in {@link deleteMetaItem} still applies, so
+   * platform storage is never dropped. Drafts are removed before active rows
+   * so each object's table is torn down once. Per-item failures are collected
+   * without aborting the rest.
+   */
+  async deletePackage(request) {
+    const where = { package_id: request.packageId };
+    if (request.organizationId) where.organization_id = request.organizationId;
+    const rows = await this.engine.find("sys_metadata", { where });
+    const dropStorage = request.keepData !== true;
+    const ordered = [...rows].sort((a, b) => (a.state === "draft" ? 0 : 1) - (b.state === "draft" ? 0 : 1));
+    const deleted = [];
+    const failed = [];
+    for (const row of ordered) {
+      const state = row.state === "draft" ? "draft" : "active";
+      try {
+        await this.deleteMetaItem({
+          type: row.type,
+          name: row.name,
+          state,
+          ...row.organization_id ? { organizationId: row.organization_id } : {},
+          ...request.actor ? { actor: request.actor } : {},
+          ...dropStorage ? { dropStorage: true } : {}
+        });
+        deleted.push({ type: row.type, name: row.name, state });
+      } catch (e) {
+        failed.push({
+          type: row.type,
+          name: row.name,
+          error: e?.message ?? "delete failed",
+          ...e?.code ? { code: e.code } : {}
+        });
+      }
+    }
+    return {
+      success: failed.length === 0 && deleted.length > 0,
+      deletedCount: deleted.length,
+      failedCount: failed.length,
+      deleted,
+      failed
+    };
+  }
   /**
    * Restore the body recorded at history `toVersion` as the new
    * live row. Writes a history event with `op='revert'`. 404
@@ -4494,6 +4685,9 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
           } catch {
           }
         }
+        if (this.shouldDropStorage(request.type, request.name, request.dropStorage, targetState)) {
+          await this.dropObjectStorage(singularTypeForRepo, request.name);
+        }
         await this.recordMetadataAudit({
           type: request.type,
           name: request.name,
@@ -4542,6 +4736,12 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         };
       }
       await this.engine.delete("sys_metadata", { where: { id: existing.id } });
+      {
+        const targetState = request.state === "draft" ? "draft" : "active";
+        if (this.shouldDropStorage(request.type, request.name, request.dropStorage, targetState)) {
+          await this.dropObjectStorage(import_shared4.PLURAL_TO_SINGULAR[request.type] ?? request.type, request.name);
+        }
+      }
       if (this.environmentId === void 0) {
         try {
           const services = this.getServicesRegistry?.();
@@ -7643,6 +7843,22 @@ var _ObjectQL = class _ObjectQL {
     const tableName = import_system2.StorageNameMapping.resolveTableName(obj);
     await driver.syncSchema(tableName, obj);
   }
+  /**
+   * Drop the physical storage (table/collection) backing an object — the
+   * inverse of {@link syncObjectSchema}. DESTRUCTIVE: deletes all rows in the
+   * table. Used by the protocol delete path when the caller explicitly opts
+   * into storage teardown (e.g. discarding an object that was published only
+   * to preview it). No-op when the object's driver does not expose `dropTable`.
+   * Resolves the physical table name from the registered definition, falling
+   * back to the bare name if the def was already removed.
+   */
+  async dropObjectSchema(objectName) {
+    const obj = this._registry.getObject(objectName);
+    const driver = this.getDriverForObject(objectName);
+    if (!driver || typeof driver.dropTable !== "function") return;
+    const tableName = import_system2.StorageNameMapping.resolveTableName(obj ?? { name: objectName });
+    await driver.dropTable(tableName);
+  }
   /**
    * Get a registered driver by datasource name.
    * Alias matching @objectql/core datasource() API.