Class: TransactionHandle

Defined in: packages/client/src/core/transaction-engine/handle.ts:40

One transaction: a private write journal plus a read view that overlays it on committed state (ADR-0039).

Writes through the handle are validated at the call site (the sweep - failing stages nothing) and stage in memory; nothing reaches the database until commit, which flushes the journal as one batch through the stack's full authoring pipeline. Reads through the handle see the journal; stack.db, other handles, replication and live subscriptions see only committed state.

Example

const t = stack.beginTransaction();
await t.createDoc(null, "Task", { title: "write-up" });
await t.db.put({ ...(await t.db.get("Task-77")), done: true });
const drafted = await t.findDocuments({ "~class": { $eq: "Task" } });
const report = await t.commit();   // or stack.commit(t)

Properties

Property	Modifier	Type	Description	Defined in
db	readonly	TransactionDb	The db-like surface: staged writes, overlaid reads.	packages/client/src/core/transaction-engine/handle.ts:58
id	readonly	string	-	packages/client/src/core/transaction-engine/handle.ts:41

Accessors

status

Get Signature

get status(): TransactionStatus;

Defined in: packages/client/src/core/transaction-engine/handle.ts:69

Returns

TransactionStatus

Methods

commit()

commit(): Promise<TransactionCommitReport>;

Defined in: packages/client/src/core/transaction-engine/handle.ts:226

Flushes the journal - sugar for stack.commit(t).

Returns

Promise<TransactionCommitReport>

---

createDoc()

createDoc(
   docId, 
   type, 
params): Promise<Document>;

Defined in: packages/client/src/core/transaction-engine/handle.ts:136

Creates or updates a document in the transaction - stack.createDoc's UX with a staged destination: docId: null mints an id, an existing id merges params over the overlay-visible document.

Parameters

Parameter	Type
docId	string
type	string
params	{ [key: string]: any; }

Returns

Promise<Document>

---

createDocs()

createDocs(docs, type): Promise<Document[]>;

Defined in: packages/client/src/core/transaction-engine/handle.ts:161

Batch counterpart of createDoc; validated sequentially, fail-fast.

Parameters

Parameter	Type
docs	object[]
type	string

Returns

Promise<Document[]>

---

deleteDocument()

deleteDocument(docId): Promise<boolean>;

Defined in: packages/client/src/core/transaction-engine/handle.ts:170

Soft-deletes in the transaction: the overlay stops showing the document under the default active: true.

Parameters

Parameter	Type
docId	string

Returns

Promise<boolean>

---

discard()

discard(): void;

Defined in: packages/client/src/core/transaction-engine/handle.ts:231

Drops the journal - sugar for stack.discardTransaction(t).

Returns

void

---

findDocuments()

findDocuments<T>(
   selector, 
   fields?, 
   skip?, 
   limit?, 
   sort?): Promise<{
[key: string]: any;
  docs: T[];
}>;

Defined in: packages/client/src/core/transaction-engine/handle.ts:179

The stack's polished read, against this transaction's view.

Type Parameters

Type Parameter	Default type
T extends Document	Document

Parameters

Parameter	Type
selector	{ [key: string]: any; }
fields?	string[]
skip?	number
limit?	number
sort?	MangoSort

Returns

Promise<{ [key: string]: any; docs: T[]; }>

---

query()

query(sql, ...params): Promise<{
  ast: (
     | SelectAST
    | UnionAST)[];
  rows: any;
}>;

Defined in: packages/client/src/core/transaction-engine/handle.ts:196

SQL against this transaction's view. The executor reaches data only through stack APIs, so a facade routes them at the overlay; LIMIT/OFFSET pushdown and sort indexes are disabled while staged - staged documents exist in no index, so windows and orderings must be computed after the merge.

Parameters

Parameter	Type
sql	string
...params	any[]

Returns

Promise<{ ast: ( | SelectAST | UnionAST)[]; rows: any; }>

---

stagedCount()

stagedCount(): number;

Defined in: packages/client/src/core/transaction-engine/handle.ts:78

Returns

number