Transactions

Create, serialize, and batch transactions for offline-first mutations in Strata Sync.

Every local change becomes a Transaction that flows through the outbox, travels to the server, and gets confirmed by the sync protocol.

Transaction interface

Every mutation conforms to this structure:


interface Transaction {
  clientTxId: string;
  clientId: string;
  modelName: string;
  modelId: string;
  action: TransactionAction;

Transactions: Create, serialize, and batch... · Strata Sync

Action	Code	Description
Insert	`"I"`	Creates a new model instance.
Update	`"U"`	Modifies fields on an existing model.
Delete	`"D"`	Permanently removes a model instance.
Archive	`"A"`	Soft-deletes by setting `archivedAt`.
Unarchive	`"V"`	Restores a soft-deleted model.

State	Description
`"queued"`	In the local outbox, not yet sent.
`"sent"`	Sent to the server, awaiting confirmation.
`"awaitingSync"`	Server confirmed, waiting for the sync ID via the delta stream.
`"completed"`	Fully synced.
`"failed"`	Failed permanently after all retries.


import { createTransaction } from "@stratasync/core";

const tx = createTransaction({
  clientId: "client-abc",
  modelName: "Task",
  modelId: "task-123",
  action: "U",
  payload: { title: "Updated title" },
  original: { title: "Original title" },
});

Field	Type	Required	Description
`clientId`	`string`	Yes	Client instance ID.
`modelName`	`string`	Yes	Registered model name.
`modelId`	`string`	Yes	Model instance ID.
`action`	`TransactionAction`	Yes	Mutation type.
`payload`	`Record<string, unknown>`	Yes	Changed data.
`original`	`Record<string, unknown>`	No	Original data for rollback.


import { createInsertTransaction } from "@stratasync/core";

const tx = createInsertTransaction("client-abc", "Task", "task-123", {
  title: "New Task",
  status: "todo",
  priority: 0,
  projectId: "project-456",
});


import { createUpdateTransaction } from "@stratasync/core";

const tx = createUpdateTransaction(
  "client-abc",
  "Task",
  "task-123",
  { title: "Updated title" },
  { title: "Original title" }
);


import {
  createArchiveTransaction,
  createUnarchiveTransaction,
} from "@stratasync/core";

// Soft-delete
const archiveTx = createArchiveTransaction("client-abc", "Task", "task-123", {
  original: { archivedAt: undefined },
  archivedAt: "2025-01-15T10:30:00.000Z",
});

// Restore
const unarchiveTx = createUnarchiveTransaction(
  "client-abc",
  "Task",
  "task-123",
  {
    original: { archivedAt: "2025-01-15T10:30:00.000Z" },
  }
);


import { createUndoTransaction } from "@stratasync/core";

const originalTx = createUpdateTransaction(
  "client-abc",
  "Task",
  "task-123",
  { title: "New" },
  { title: "Old" }
);

const undoTx = createUndoTransaction(originalTx);
// undoTx.action === "U"
// undoTx.payload === { title: "Old" }
// undoTx.original === { title: "New" }

Original action	Undo action	Notes
Insert (`"I"`)	Delete (`"D"`)	Deletes the inserted model.
Delete (`"D"`)	Insert (`"I"`)	Re-creates with original data. Returns `null` if no original.
Update (`"U"`)	Update (`"U"`)	Swaps payload and original. Returns `null` if no original.
Archive (`"A"`)	Unarchive (`"V"`)	Restores the model.
Unarchive (`"V"`)	Archive (`"A"`)	Re-archives the model.


import {
  createTransactionBatch,
  createInsertTransaction,
  createUpdateTransaction,
} from "@stratasync/core";

const batch = createTransactionBatch([
  createInsertTransaction("client-abc", "Task", "task-1", { title: "Task 1" }),
  createUpdateTransaction(
    "client-abc",
    "Project",
    "proj-1",
    { taskCount: 5 },
    { taskCount: 4 }
  ),
]);
// batch.batchId: string
// batch.transactions: Transaction[]
// batch.createdAt: number


import {
  serializeTransaction,
  deserializeTransaction,
  transactionToJson,
  transactionFromJson,
} from "@stratasync/core";

// To compact object
const serialized = serializeTransaction(tx);
const restored = deserializeTransaction(serialized);

// To/from JSON string
const json = transactionToJson(tx);
const parsed = transactionFromJson(json);


import {
  serializeBatch,
  deserializeBatch,
  batchToJson,
  batchFromJson,
} from "@stratasync/core";

// To compact object
const serialized = serializeBatch(batch);
const restored = deserializeBatch(serialized);

// To/from JSON string
const json = batchToJson(batch);
const parsed = batchFromJson(json);

Transaction field	Serialized key
`clientTxId`	`cid`
`clientId`	`cli`
`modelName`	`m`
`modelId`	`mid`
`action`	`a`
`payload`	`p`
`original`	`o`
`state`	`s`
`createdAt`	`t`
`retryCount`	`r`
`lastError`	`e`
`syncIdNeededForCompletion`	`s2`
`batchIndex`	`b`

Transactions

Transaction interface

Transactions

Transaction interface

TransactionAction

TransactionState

Creating transactions

createTransaction

createInsertTransaction

createUpdateTransaction

createDeleteTransaction

createArchiveTransaction and createUnarchiveTransaction

createUndoTransaction

Batching

createTransactionBatch

Serialization

Single transactions

Batches

Serialized format

Server result types

TransactionResult

MutateResult