Transactions

Transactions in Collect allow you to execute multiple operations in a way that either all succeed or none are applied, ensuring data integrity.

Typescript Definition

declare class CollectTransaction extends CollectRestApiProxy {
    // id of transaction
    readonly id: string;
    constructor(id: string);

    // message about transaction status when creating or rolling back transaction
    rollback(): Promise<{
        message: string;
    }>;
    commit(): Promise<{
        message: string;
    }>;
}

Data Example

{
    "id": "0191f150-752c-7dd9-8884-078ed5dae03a"
}

How it works

It's easiest to explain how transactions work without diving into code. Think of a transaction like a delivery truck. You can load many packages (operations) onto the truck and send them to their destination all at once. If the customer cancels the order, you simply unload the truck and cancel the delivery. Without transactions, you'd have to send each package individually, and if something went wrong, you'd have to retrieve each one from its destination, which can be a lot of extra work. Transactions ensure that all your packages either reach their destination together or not at all, maintaining the integrity of the process.

While this analogy helps to understand transactions conceptually, it's essential to see how they function within the code flow. Below is a comprehensive example of how to use transactions in chaining operations, where various logical pieces of code are created in parallel. In such cases, the developer decides when to consider the result of the operation successful and when to roll back everything that was written within the current transaction.

// Begin a transaction before processing complex operations with chained actions
const tx = await collect.tx.begin();

try {
    const product = await collect.records.create("Product", {
        title: "Nike Air Max 270",
        price: 150,
        description: "Nike's stylish and comfortable sneakers with Max Air cushioning for all-day wear.",
        category: "Footwear",
        stock: 50,
    }, tx);

    const owner = await collect.records.create("Client", {
        name: "Jane Smith",
        username: "janesmith99",
        email: "janesmith@example.com",
    }, tx);

    await collect.records.attach(owner.data.__id, product, {
        direction: "out",
        type: "owner",
    }, tx);

    // Commit the transaction if all operations succeed
    await tx.commit();
} catch (e) {
    // If any records or relationships creation failed, roll back the entire operation
    await tx.rollback();
}

---

Create Transaction

Endpoints

Create a Transaction

POST /api/v1/transactions

To create a new transaction in Collect, simply call the .begin method on the tx object.

Request

const tx = await collect.tx.begin();

Example with TTL:

const tx = await collect.tx.begin({
    ttl: 500
});

Response

{
    "id": "0191f150-752c-7dd9-8884-078ed5dae03a"
}

---

Get Transaction

Endpoints

Get a specific Transaction

GET /api/v1/transactions/:txId

info

Note: Replace :txId with the actual ID of the Transaction.

To retrieve a specific transaction in Collect, simply call the .get method on the tx object.

Request

const tx = await collect.tx.get(id);

Example with TTL:

Response

{
    "id": "0191f150-752c-7dd9-8884-078ed5dae03a"
}

---

Commit Transaction

Endpoints

Commit a Transaction

POST /api/v1/transactions/:txId

info

Note: Replace :txId with the actual ID of the Transaction.

To commit a transaction, indicating that all operations within the transaction should be applied:

Request

await tx.commit();

Response

{
    "message": "Transaction (0191f150-752c-7dd9-8884-078ed5dae03a) has been successfully committed."
}

---

Rollback Transaction

Endpoints

Rollback a Transaction

POST /api/v1/transactions/:txId/rollback

info

Note: Replace :txId with the actual ID of the Transaction.

To roll back a transaction, undoing all operations performed within it:

Request

await tx.rollback();

Response

{
    "message": "Transaction (0191f150-752c-7dd9-8884-078ed5dae03a) has been rolled back."
}

---

Endpoints Overview

The Transaction API provides several endpoints to work with transactions. Here's an overview of all available endpoints in this section:

Method	Endpoint	Description
POST	/api/v1/transactions	Create a new transaction
GET	/api/v1/transactions/:txId	Retrieve a single Transaction
POST	/api/v1/transactions/:txId/commit	Commit the specified transaction
POST	/api/v1/transactions/:txId/rollback	Rollback the specified transaction