Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

OfflineExecutor.dispose() never settles pendingTransactionPromises

Open Beginner friendly
  • Is something wrong?
#2,254 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
node.js, typescript
Domain
backend, databases

Research direction

Start with packages/offline-transactions/src/OfflineExecutor.ts, especially waitForTransactionCompletion, resolveTransaction/rejectTransaction, and dispose() as linked in the issue. Trace how pending deferreds correspond to transactions and inspect the package's disposal and transaction tests. Reproduce the offline commit, dispose, and replay sequence from the issue; done means the original transaction reaches a settled state and its isPersisted.promise no longer hangs.

Written by the indexing model from the issue text.

Description

  • I've validated the bug against the latest version of DB packages

Describe the bug
OfflineExecutor keeps a pendingTransactionPromises map of deferreds, created by waitForTransactionCompletion and settled by resolveTransaction / rejectTransaction. dispose() pauses the executor and tears down the collection refresh hooks, the online listener, leadership, and the online detector, but it never touches the map. Every deferred in it is abandoned, so a transaction committed on a disposed executor never leaves persisting, and its isPersisted.promise never settles.

To Reproduce

  1. npm i @tanstack/[email protected] @tanstack/db and save the script below as repro.mjs. It runs in plain Node: in-memory storage stands in for IndexedDB and is shared by both executors, and connectivity and leader election are stubbed.
  2. Start an executor offline and commit a transaction. It persists to the outbox, and the mutation fn does not run.
  3. Call dispose() on that executor and start a successor on the same storage, online.
  4. The successor replays the row, runs the mutation fn once, and empties the outbox.
  5. See that the original transaction still reads persisting and its isPersisted.promise is unsettled (node repro.mjs --dispose). The control run without the dispose resolves (node repro.mjs).
repro.mjs 
import { createCollection, localOnlyCollectionOptions } from "@tanstack/db";
import { startOfflineExecutor } from "@tanstack/offline-transactions";

const withDispose = process.argv.includes("--dispose");

// Shared in-memory storage, standing in for IndexedDB across both executors.
const store = new Map();
const storage = {
  get: async (k) => store.get(k) ?? null,
  set: async (k, v) => void store.set(k, v),
  delete: async (k) => void store.delete(k),
  keys: async () => [...store.keys()],
  clear: async () => void store.clear(),
};

// Always-leader election: no Web Locks in Node.
const leaderElection = {
  requestLeadership: async () => true,
  releaseLeadership: () => {},
  isLeader: () => true,
  onLeadershipChange: () => () => {},
};

// Manually toggled connectivity.
function makeDetector(initiallyOnline) {
  let online = initiallyOnline;
  const listeners = new Set();
  return {
    subscribe: (cb) => (listeners.add(cb), () => listeners.delete(cb)),
    notifyOnline: () => listeners.forEach((cb) => cb()),
    isOnline: () => online,
    dispose: () => listeners.clear(),
    goOnline() {
      online = true;
      listeners.forEach((cb) => cb());
    },
  };
}

const todos = createCollection(
  localOnlyCollectionOptions({ id: "todos", getKey: (t) => t.id }),
);

const calls = [];
const mutationFns = {
  syncTodos: async ({ transaction }) => {
    calls.push(transaction.id);
  },
};

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const settledWithin = (promise, ms) =>
  Promise.race([
    promise.then(
      () => "resolved",
      (e) => `rejected: ${e?.message}`,
    ),
    sleep(ms).then(() => "STILL PENDING"),
  ]);

// 1. Start offline and commit a transaction; it persists to the outbox.
const detector1 = makeDetector(false);
const executor1 = startOfflineExecutor({
  collections: { todos },
  mutationFns,
  storage,
  leaderElection,
  onlineDetector: detector1,
});
await executor1.waitForInit();

const tx = executor1.createOfflineTransaction({ mutationFnName: "syncTodos" });
// autoCommit defaults to true, so mutate() commits.
const transaction = tx.mutate(() => todos.insert({ id: "1", text: "hello" }));
const isPersisted = transaction.isPersisted.promise;
await sleep(100);
console.log("outbox rows after offline commit:", store.size);
console.log("mutationFn calls while offline:", calls.length);

let completer;
if (withDispose) {
  // 2. Dispose (the recreate pattern) and start a successor on the same storage.
  executor1.dispose();
  const detector2 = makeDetector(true);
  completer = startOfflineExecutor({
    collections: { todos },
    mutationFns,
    storage,
    leaderElection,
    onlineDetector: detector2,
  });
  await completer.waitForInit();
} else {
  // Control: no dispose, just come back online on the same executor.
  detector1.goOnline();
  completer = executor1;
}

// 3. Let the outbox drain.
await sleep(500);
console.log("mutationFn calls after replay:", calls.length);
console.log("outbox rows after replay:", store.size);
console.log("pending count on completing executor:", completer.getPendingCount());

// 4. The promises the first executor handed out.
console.log("transaction.state:", transaction.state);
console.log("isPersisted.promise:", await settledWithin(isPersisted, 2000));
process.exit(0);

Output:

== node repro.mjs  (control: no dispose)
outbox rows after offline commit: 1
mutationFn calls while offline: 0
mutationFn calls after replay: 1
outbox rows after replay: 0
pending count on completing executor: 0
transaction.state: completed
isPersisted.promise: resolved

== node repro.mjs --dispose
outbox rows after offline commit: 1
mutationFn calls while offline: 0
mutationFn calls after replay: 1
outbox rows after replay: 0
pending count on completing executor: 0
transaction.state: persisting
isPersisted.promise: STILL PENDING

Expected behavior
dispose() settles every deferred in pendingTransactionPromises, so no caller is left awaiting a transaction from a disposed executor. Either of these would work:

  • Reject each deferred with a disposal error the caller can treat as retriable.
  • Expose the pending ids so a successor executor can re-bridge them, and resolve them when it completes the replayed transaction.

Screenshots
N/A. The repro's console output is above.

Desktop (please complete the following information):

  • OS: Linux (kernel 6.18)
  • Browser: N/A. Reproduced in Node v24.22.1. The executor code path is environment-independent.
  • Version: @tanstack/offline-transactions 1.1.4, @tanstack/db 0.15.2. dispose() is unchanged on main at d2935d0.

Smartphone (please complete the following information):

  • N/A

Additional context
I first hit this on 1.0.42 in an app whose outbox recreates its executor whenever a new collection registers. I work around it with a completion ledger that carries isPersisted settlement across the recreate, but an upstream fix would let me delete this workaround.

Dominant language
TypeScript
Stars
4k
Forks
277
Avg merge
17h 40m
Merged PRs (30d)
223

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from TanStack/db

All issues in TanStack/db

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.