@iterativeflow/mysql 2.0.0-alpha.5 → 2.0.0-alpha.6

package/dist/index.d.mts

@@ -48,4 +48,21 @@ declare const ddl: (prefix?: string) => string[];
 /** Apply the schema DDL (idempotent). Run once before use. */
 declare const applySchema: (sql: Sql, prefix?: string) => Promise<void>;
 //#endregion
-export { type MysqlBackendOpts, type Sql, applySchema, createMysqlBackend, ddl, mysqlPool };
+//#region src/tx.d.ts
+/**
+ * Run `fn` inside one MySQL transaction, handing it a {@link Backend} bound to that
+ * transaction plus the raw {@link Sql} for the caller's own writes. Every `submit` /
+ * `startRun` / `enqueue` on that backend commits ATOMICALLY with the caller's writes on
+ * `tx` — the transactional-enqueue guarantee: business work and workflow dispatch land
+ * together or not at all. A throw rolls back both, so a failed request never leaves an
+ * orphan run or a dangling job.
+ *
+ * @example
+ * await inTx(pool, async (backend, tx) => {
+ *   await tx.query("INSERT INTO orders (id) VALUES (?)", [orderId]);
+ *   await submit(backend, fulfilOrder, { orderId }); // enqueued iff the order commits
+ * });
+ */
+declare const inTx: <T>(pool: Pool, fn: (backend: Backend, tx: Sql) => Promise<T>, opts?: MysqlBackendOpts) => Promise<T>;
+//#endregion
+export { type MysqlBackendOpts, type Sql, applySchema, createMysqlBackend, ddl, inTx, mysqlPool };

package/dist/index.mjs

@@ -627,4 +627,21 @@ const mysqlPool = (pool) => {
 	};
 };
 //#endregion
-export { applySchema, createMysqlBackend, ddl, mysqlPool };
+//#region src/tx.ts
+/**
+* Run `fn` inside one MySQL transaction, handing it a {@link Backend} bound to that
+* transaction plus the raw {@link Sql} for the caller's own writes. Every `submit` /
+* `startRun` / `enqueue` on that backend commits ATOMICALLY with the caller's writes on
+* `tx` — the transactional-enqueue guarantee: business work and workflow dispatch land
+* together or not at all. A throw rolls back both, so a failed request never leaves an
+* orphan run or a dangling job.
+*
+* @example
+* await inTx(pool, async (backend, tx) => {
+*   await tx.query("INSERT INTO orders (id) VALUES (?)", [orderId]);
+*   await submit(backend, fulfilOrder, { orderId }); // enqueued iff the order commits
+* });
+*/
+const inTx = (pool, fn, opts) => mysqlPool(pool).tx((tx) => fn(createMysqlBackend(tx, opts), tx));
+//#endregion
+export { applySchema, createMysqlBackend, ddl, inTx, mysqlPool };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterativeflow/mysql",
-  "version": "2.0.0-alpha.5",
+  "version": "2.0.0-alpha.6",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
     "build": "tsdown"
   },
   "dependencies": {
-    "@iterativeflow/core": "2.0.0-alpha.5"
+    "@iterativeflow/core": "2.0.0-alpha.6"
   },
   "peerDependencies": {
     "mysql2": ">=3.0.0"