@bastani/atomic-storage-libsql 0.9.71-alpha.1 → 0.9.72-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +9 -0
  2. package/libsql.js +154 -23
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -2,6 +2,15 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [0.9.72-alpha.1] - 2026-11-08
6
+
7
+ ### Fixed
8
+
9
+ - A `file:` database stays usable after a statement fails. A statement that gave up part way, for example a write that waited out the busy timeout while another process held the lock, stayed active on its connection until garbage collection. After that, every transaction on the database failed with `SQLITE_BUSY: cannot commit transaction - SQL statements in progress`, and a write outside a transaction reported success but was never committed. The adapter now replaces its local connections after any failed statement, before the next call, and turns foreign keys on again on the new one.
10
+ - Closing a `file:` database now releases its files before `close()` resolves, so they can be deleted or moved right away, including on Windows. libsql 0.5 keeps a closed connection open until its statements are garbage-collected; the adapter now runs two full garbage collections, shared by closes that arrive together, and waits for the driver to release its handles ([#4433](https://github.com/bastani-inc/atomic/issues/4433))
11
+ - When opening a database fails and closing it afterwards fails too, the close failure is attached to the open error as `cleanupCause` instead of being discarded ([#4433](https://github.com/bastani-inc/atomic/issues/4433))
12
+ - A remote database no longer fails a write because the process stalled in the middle of it. When a process was stopped (by a signal, starved of CPU, or asleep) longer than the server keeps an idle stream, its next statement failed with `STREAM_EXPIRED` and the write was lost to a `StorageUnavailableError`. The adapter now recognizes an expired stream, a transaction the server timed out, a refused connection and a broken connection by their codes and reports them as `StorageTransientError`; a statement, batch, or workflow journal or session write that they ended before it wrote anything runs again, up to five times over about four seconds. A write whose connection broke after the server may have applied it is not sent again and fails with `outcome: "unknown"` ([#4383](https://github.com/bastani-inc/atomic/issues/4383))
13
+
5
14
  ## [0.9.71] - 2026-11-03
6
15
 
7
16
  ### Fixed
package/libsql.js CHANGED
@@ -1,4 +1,6 @@
1
1
  // @ts-check
2
+ import { setFlagsFromString } from "node:v8";
3
+ import { runInNewContext } from "node:vm";
2
4
  import { createSqliteDatabase, redactSecrets, StorageAdapterLoadError, switchToWriteAheadLog } from "@bastani/atomic/storage";
3
5
 
4
6
  /**
@@ -75,15 +77,15 @@ function urlCredentials(url) {
75
77
  }
76
78
 
77
79
  /**
78
- * @param {() => import("@libsql/client").Client | import("@libsql/client").Transaction} connection
80
+ * @param {() => Promise<import("@libsql/client").Client | import("@libsql/client").Transaction>} connection
81
+ * @param {<T>(operation: () => Promise<T>) => Promise<T>} watch
79
82
  * @returns {import("@bastani/atomic/storage").SqliteDriverExecutor}
80
83
  */
81
- function statements(connection) {
84
+ function statements(connection, watch) {
82
85
  return {
83
- async execute(sql, params) {
84
- return driverResult(await connection().execute({ sql, args: [...params] }));
85
- },
86
- executeMultiple: (sql) => connection().executeMultiple(sql),
86
+ execute: (sql, params) =>
87
+ watch(async () => driverResult(await (await connection()).execute({ sql, args: [...params] }))),
88
+ executeMultiple: (sql) => watch(async () => (await connection()).executeMultiple(sql)),
87
89
  };
88
90
  }
89
91
 
@@ -102,6 +104,100 @@ function driverResult(result) {
102
104
  */
103
105
  const FILE_BUSY_TIMEOUT_MS = 5000;
104
106
 
107
+ /** V8's `gc`, taken from a context created while `--expose-gc` is set; the flag is off again for code that runs later. */
108
+ function exposeGc() {
109
+ setFlagsFromString("--expose-gc");
110
+ try {
111
+ return /** @type {() => void} */ (runInNewContext("gc"));
112
+ } finally {
113
+ setFlagsFromString("--no-expose-gc");
114
+ }
115
+ }
116
+
117
+ function collectGarbage() {
118
+ if (globalThis.gc) globalThis.gc();
119
+ else if (typeof Bun !== "undefined") Bun.gc(true);
120
+ else exposeGc()();
121
+ }
122
+
123
+ /**
124
+ * Consecutive full collections one close runs. One forced collection occasionally leaves a statement uncollected, about
125
+ * once in several thousand closes in a loop that opens, uses and closes a file database, and a further event-loop turn
126
+ * does not collect it; a second collection does.
127
+ */
128
+ const COLLECTION_PASSES = 2;
129
+
130
+ /** @type {Promise<void>} */
131
+ let collection = Promise.resolve();
132
+ /** @type {Promise<void> | undefined} */
133
+ let pendingCollection;
134
+
135
+ /**
136
+ * libsql 0.5 finalizes a statement only when the statement is garbage-collected, and a connection stays open until
137
+ * its last statement is finalized, so the client's `close()` leaves a `file:` database's files open and Windows
138
+ * refuses to delete them. This resolves after `COLLECTION_PASSES` full collections that started after the call, each
139
+ * followed by the event-loop turn in which the runtime runs the native finalizers it queued. Calls made before those
140
+ * collections start share them.
141
+ * @returns {Promise<void>}
142
+ */
143
+ function releaseClosedConnections() {
144
+ if (!pendingCollection) {
145
+ pendingCollection = collection.then(collectAndFinalize, collectAndFinalize);
146
+ collection = pendingCollection;
147
+ }
148
+ return pendingCollection;
149
+ }
150
+
151
+ async function collectAndFinalize() {
152
+ pendingCollection = undefined;
153
+ for (let pass = 0; pass < COLLECTION_PASSES; pass++) {
154
+ collectGarbage();
155
+ await new Promise((resolve) => setImmediate(resolve));
156
+ }
157
+ }
158
+
159
+ /** How far `transientFailure` follows `cause`: a driver error wraps the network error that fetch wraps. */
160
+ const MAX_CAUSE_DEPTH = 8;
161
+ /**
162
+ * Codes sqld answers for a stream or transaction it ended and rolled back: nothing of it was written.
163
+ * @type {ReadonlyMap<unknown, import("@bastani/atomic/storage").StorageTransientErrorCode>}
164
+ */
165
+ const ENDED_BY_SERVER = new Map([
166
+ ["STREAM_EXPIRED", "stream-expired"],
167
+ ["TRANSACTION_TIMEOUT", "transaction-timeout"],
168
+ ]);
169
+ /**
170
+ * Network codes of a request that never reached the server, from Node's fetch and from Bun's.
171
+ * @type {ReadonlySet<unknown>}
172
+ */
173
+ const NOT_SENT = new Set(["ECONNREFUSED", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT"]);
174
+ /**
175
+ * Network codes of a connection that broke after a request may have reached the server.
176
+ * @type {ReadonlySet<unknown>}
177
+ */
178
+ const CONNECTION_LOST = new Set(["ECONNRESET", "EPIPE", "ETIMEDOUT", "UND_ERR_SOCKET"]);
179
+
180
+ /**
181
+ * The failure, as one that passes, when the server ended the stream or transaction of a process that stalled, or the
182
+ * connection to the server could not be made or broke; read from each error's `code` along the cause chain, never
183
+ * from its message.
184
+ * @param {import("@bastani/atomic/storage").StorageFailureCause} failure
185
+ * @returns {import("@bastani/atomic/storage").SqliteDriverTransientFailure | undefined}
186
+ */
187
+ function transientFailure(failure) {
188
+ /** @type {unknown} */
189
+ let current = failure;
190
+ for (let depth = 0; depth < MAX_CAUSE_DEPTH && typeof current === "object" && current !== null; depth++) {
191
+ const { code, cause } = /** @type {{ readonly code?: unknown, readonly cause?: unknown }} */ (current);
192
+ const ended = ENDED_BY_SERVER.get(code);
193
+ if (ended !== undefined) return { code: ended, outcome: "not-applied" };
194
+ if (NOT_SENT.has(code)) return { code: "connection-refused", outcome: "not-applied" };
195
+ if (CONNECTION_LOST.has(code)) return { code: "connection-lost", outcome: "unknown" };
196
+ current = cause;
197
+ }
198
+ return undefined;
199
+ }
200
+
105
201
  /**
106
202
  * @param {LibsqlDatabaseOptions} options
107
203
  * @returns {Promise<import("@bastani/atomic/storage").SqliteDatabase>}
@@ -121,36 +217,67 @@ export async function openLibsqlDatabase({ url, authToken, namespace, headers })
121
217
  // Create the client inside a driver call, so the facade redacts credentials from its failures. The busy timeout is a
122
218
  // client option, not a PRAGMA, because the client opens more connections than the one that ran the PRAGMA, and
123
219
  // each needs it; a connection waits for a lock on the calling thread.
124
- const connection = () =>
125
- (client ??= createClient({
220
+ const create = () =>
221
+ createClient({
126
222
  url,
127
223
  authToken,
128
224
  intMode: "bigint",
129
225
  ...(local ? { timeout: FILE_BUSY_TIMEOUT_MS } : {}),
130
226
  ...(added.length > 0 ? { fetch: fetchWith(added) } : {}),
131
- }));
227
+ });
228
+ // A local statement that fails part way, as a write does when another process holds the lock past the busy timeout,
229
+ // stays active on its connection: the driver resets and finalizes a statement only when it is garbage collected.
230
+ // Until then that connection commits nothing ("cannot commit transaction - SQL statements in progress"), and a
231
+ // write outside a transaction reports success but is never committed. So after a local failure the next call gets
232
+ // new connections. The facade runs one call at a time, so no call is still using the old ones.
233
+ let replace = false;
234
+ /** @type {<T>(operation: () => Promise<T>) => Promise<T>} */
235
+ const watch = async (operation) => {
236
+ try {
237
+ return await operation();
238
+ } catch (error) {
239
+ if (local) replace = true;
240
+ throw error;
241
+ }
242
+ };
243
+ const connection = async () => {
244
+ if (replace) {
245
+ replace = false;
246
+ client?.close();
247
+ const fresh = create();
248
+ client = fresh;
249
+ // A new connection does not have the PRAGMA the open ran on the one it replaces.
250
+ await watch(() => fresh.execute("PRAGMA foreign_keys = ON"));
251
+ }
252
+ return (client ??= create());
253
+ };
132
254
  const database = createSqliteDatabase({
133
255
  descriptor: { adapter: "libsql", location: url },
134
256
  redact: redactSecrets([authToken ?? "", ...urlCredentials(url), ...Object.values(headers ?? {})]),
135
- ...statements(connection),
257
+ transientFailure,
258
+ ...statements(connection, watch),
136
259
  // One request for the whole batch, in a write transaction: the journal sends a batch of appends this way.
137
- async batch(batched) {
138
- const results = await connection().batch(
139
- batched.map(({ sql, params }) => ({ sql, args: [...params] })),
140
- "write",
141
- );
142
- return results.map(driverResult);
143
- },
260
+ batch: (batched) =>
261
+ watch(async () => {
262
+ const results = await (await connection()).batch(
263
+ batched.map(({ sql, params }) => ({ sql, args: [...params] })),
264
+ "write",
265
+ );
266
+ return results.map(driverResult);
267
+ }),
144
268
  async beginTransaction() {
145
- const transaction = await connection().transaction("write");
269
+ const transaction = await watch(async () => (await connection()).transaction("write"));
146
270
  return {
147
- ...statements(() => transaction),
148
- commit: () => transaction.commit(),
149
- rollback: () => transaction.rollback(),
271
+ ...statements(async () => transaction, watch),
272
+ commit: () => watch(() => transaction.commit()),
273
+ rollback: () => watch(() => transaction.rollback()),
150
274
  close: () => transaction.close(),
151
275
  };
152
276
  },
153
- close: () => client?.close(),
277
+ async close() {
278
+ client?.close();
279
+ if (local) await releaseClosedConnections();
280
+ },
154
281
  });
155
282
  try {
156
283
  await database.exec("PRAGMA foreign_keys = ON");
@@ -162,7 +289,11 @@ export async function openLibsqlDatabase({ url, authToken, namespace, headers })
162
289
  if (local) await switchToWriteAheadLog((sql) => database.exec(sql), FILE_BUSY_TIMEOUT_MS);
163
290
  return database;
164
291
  } catch (error) {
165
- await database.close().catch(() => {});
292
+ await database
293
+ .close()
294
+ .catch((cleanupCause) =>
295
+ Object.defineProperty(/** @type {Error} */ (error), "cleanupCause", { value: cleanupCause, configurable: true }),
296
+ );
166
297
  throw error;
167
298
  }
168
299
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bastani/atomic-storage-libsql",
3
- "version": "0.9.71-alpha.1",
3
+ "version": "0.9.72-alpha.1",
4
4
  "description": "libSQL / Turso storage adapter for Atomic sessions, workflow journals, and Intercom.",
5
5
  "contributors": [
6
6
  "Norin Lavaee",