@forge-cms/runtime 0.5.0 → 0.7.0

package/dist/operations.d.ts

@@ -87,23 +87,62 @@ export declare function findByID(ctx: OperationContext, args: FindByIDArgs & {
 }): Promise<DatabaseRecord>;
 export declare function count(ctx: OperationContext, args: CountArgs): Promise<number>;
 export declare function create(ctx: OperationContext, args: CreateArgs): Promise<DatabaseRecord>;
+/**
+ * The multipart upload pipeline's create (spec 063 §5) — **package-private**: exported for
+ * `handlers.ts` only, never from the package entry point. `storageKey` is the key Forge itself just
+ * generated and stored the object under; it is merged into the persisted row only, outside caller
+ * `data` and hook `data`, so no caller of the public mutation surface can choose or rewrite it.
+ */
+export declare function createUpload(ctx: OperationContext, args: CreateArgs, upload: {
+    storageKey: string;
+    intentId: string;
+}): Promise<DatabaseRecord>;
+/**
+ * The whole upload create (spec 067) — **package-private**, called by `handleCreate` for a multipart
+ * body: records a durable storage intent, stores the object under a Forge-generated key, then creates
+ * the document with the key and the intent claim in one batch. Any failure after the intent exists
+ * settles it: the object is deleted only while the intent is still there (the document never
+ * committed); otherwise the intent stays for `reconcileStorage()`. The file's `filename`, `url`,
+ * `contentType` and `filesize` fill whichever of those fields the collection declares, under `args.data`.
+ */
+export declare function uploadFile(ctx: OperationContext, args: CreateArgs, file: File): Promise<DatabaseRecord>;
 export declare function update(ctx: OperationContext, args: UpdateArgs): Promise<DatabaseRecord>;
 /**
- * Restores a document to a specific historical version — spec 058 §2. Unlike the pre-058
- * implementation (which wrote through `ctx.adapters.database.update()` directly, bypassing access,
- * validation, and hooks), this fetches the raw version snapshot and then calls this module's own
- * `update()`, so a restore gets exactly the same update-access/row-policy/field-write/validation/hook
- * pipeline a normal update gets, and creates exactly one labeled version (via `versionLabel`) instead
- * of a second, bespoke version write.
+ * Restores a document to a specific historical version — spec 058 §2, made atomic by spec 062. The raw
+ * snapshot is read (trusted — restore's authorization gate is `update()`'s own update-access check on
+ * the *current* document, see spec 058 §2) and handed to this module's own update pipeline, which turns
+ * it into a patch of only the fields that differ from the current document (spec 062 §6) and then runs
+ * the normal update-access / row-policy / field-write / validation / hook pipeline. The patch and one
+ * snapshot labeled `Restored from version N` commit in one atomic batch, so a forbidden, invalid or
+ * conflicting restore leaves both the document and its history unchanged.
  *
- * The version snapshot itself is always fetched unfiltered (`overrideAccess: true` on the internal
- * `getVersion` call) — restore's authorization gate is `update()`'s own update-access check on the
- * *current* document, exactly like calling `update()` directly would behave; there is no separate
- * "can this caller read this document's history" gate for restore (see spec 058 §2 for the reasoning).
- * A forbidden or invalid restore throws before `update()` ever reaches the adapter write, so both the
- * current document and its history are left unchanged.
+ * System metadata (`id`, `created_at`, `updated_at`, `_storageKey`) is never restored. A full (spec 062)
+ * snapshot sets every currently declared field, so a snapshot that predates a now-required field fails
+ * current validation instead of producing an invalid document.
  */
 export declare function restoreVersion(ctx: OperationContext, args: RestoreVersionArgs): Promise<DatabaseRecord>;
+/**
+ * Deletes a document together with its whole relation graph (spec 064 §5) — plan, prepare, **one**
+ * `atomicWrite`, finalize:
+ *
+ * 1. **Plan** (reads only): root `beforeOperation`, read, access; then {@link planRelationDelete} walks
+ *    every cascade/set-null/restrict reference to its fixpoint, judges restrict and required set-null
+ *    against the final state, and refuses a plan that cannot fit in one batch — before any `before*`
+ *    hook of the graph and before any write.
+ * 2. **Prepare** (hooks, validation; no writes): root `beforeDelete`; each cascaded document's
+ *    `beforeOperation` + `beforeDelete`; each set-null document through the same {@link prepareUpdate}
+ *    `update()` uses. Dependents run with `overrideAccess: true` — a consequence of an authorized delete,
+ *    like a database's own `ON DELETE CASCADE` (spec 058 §5) — but never skip validation or hooks.
+ * 3. **Commit**: set-null patches (versioned: spec 062's update + snapshot), cascaded deletes guarded by
+ *    the `updated_at` they were planned with, the root delete, and finally one "no reference remains"
+ *    `assertCount` per referring field — all in one batch, so a late failure or a reference created
+ *    concurrently leaves every row unchanged.
+ * 4. **Finalize** (after commit): storage cleanup for deleted upload documents, then after-hooks —
+ *    dependents first, root last.
+ *
+ * Before-hooks are not transactional: a side effect they performed outside the database survives a
+ * rollback of the batch (roadmap D01).
+ */
 export declare function deleteDocument(ctx: OperationContext, args: DeleteArgs): Promise<DatabaseRecord>;
 export interface PreviewArgs extends BaseOperationArgs {
     data: Record<string, unknown>;

package/dist/operations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../src/operations.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,OAAO,EAAwB,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC/F,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AA0BrD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAaxD,6DAA6D;AAC7D,MAAM,WAAW,aAAa,CAAC,IAAI,GAAG,cAAc;IAClD,IAAI,EAAE,IAAI,EAAE,CAAC;IACb,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,wFAAwF;IACxF,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACd,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAS,SAAQ,iBAAiB;IACjD,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,+GAA+G;IAC/G,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CAC9B;AAED,MAAM,WAAW,YAAa,SAAQ,iBAAiB;IACrD,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,0FAA0F;AAC1F,MAAM,WAAW,WAAY,SAAQ,iBAAiB;IACpD,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CAC9B;AAED,MAAM,WAAW,SAAU,SAAQ,iBAAiB;IAClD,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CAC9B;AAED,MAAM,WAAW,UAAW,SAAQ,iBAAiB;IACnD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,UAAW,SAAQ,iBAAiB;IACnD,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAW,SAAQ,iBAAiB;IACnD,EAAE,EAAE,MAAM,CAAC;CACZ;AA8HD,wBAAsB,IAAI,CAAC,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,CA4BxF;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAC3B,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAuBhC;AAuBD,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,YAAY,GAAG;IAAE,MAAM,CAAC,EAAE,WAAW,GAAG,KAAK,CAAA;CAAE,GACpD,OAAO,CAAC,cAAc,CAAC,CAiCzB;AAED,wBAAsB,KAAK,CAAC,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAWnF;AAED,wBAAsB,MAAM,CAAC,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CA+F7F;AAED,wBAAsB,MAAM,CAAC,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAoH7F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,cAAc,CAAC,CAoBzB;AAqBD,wBAAsB,cAAc,CAClC,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,cAAc,CAAC,CAEzB;AA+FD,MAAM,WAAW,WAAY,SAAQ,iBAAiB;IACpD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAmF/F;AAED,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../src/operations.ts"],"names":[],"mappings":"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"}