@happyvertical/sql 0.111.4 → 0.111.5

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.
package/README.md CHANGED
@@ -473,20 +473,46 @@ Two consequences worth knowing:
473
473
  connection for the life of the process, and every later transaction on it
474
474
  fails with the queue timeout.
475
475
  - Inside a `transaction()` callback, use the `tx` you were handed. With secure
476
- SQLite, calling a top-level `db.*` or `db.client.execute()` method is rejected
476
+ SQLite and remote LibSQL, calling a top-level `db.*` or `db.client.execute()`
477
+ method is rejected
477
478
  immediately so detached work cannot escape into autocommit after the callback
478
479
  ends. While a manual transaction handle is open, top-level calls wait on its
479
480
  connection and reject at `transactionQueueTimeout` rather than hang forever.
480
481
 
481
482
  Nested SQLite and PostgreSQL scopes use savepoints. If sibling nested scopes are
482
483
  started concurrently on one transaction, they serialize so the stack-ordered
483
- savepoint lifecycle remains intact. While a secure SQLite child savepoint is
484
- open, operations invoked through its parent scope queue behind that child; a
484
+ savepoint lifecycle remains intact. On secure SQLite and remote LibSQL,
485
+ operations invoked through a parent handle from outside an open child
486
+ savepoint queue behind that child; a
485
487
  child rollback therefore cannot silently remove a successful parent operation.
486
488
  The enclosing commit or rollback drains all
487
489
  accepted child scopes before ending the transaction. PostgreSQL pools separate
488
490
  connections, so top-level transactions there run concurrently and never queue;
489
491
  PGlite has one connection and queues them like SQLite does.
492
+ Remote LibSQL uses a dedicated write transaction for each callback or manual
493
+ handle. It acquires the write transaction before invoking the callback or
494
+ returning the handle, and never replays a callback. Use `tx.client.execute()`
495
+ for raw driver statements within that transaction; native operations on the root
496
+ `db.client` use separate streams. If a statement ends the transaction (for
497
+ example, `INSERT OR ROLLBACK` hits a conflict), the handle rejects later
498
+ statements and commit rather than letting work continue in autocommit.
499
+ An ordinary handled constraint failure can still leave the transaction active.
500
+
501
+ In remote SQLite queries with positional
502
+ arguments, `$1`, `$2`, and so on refer to the same argument slots as SQLite's
503
+ `?1`, `?2`, including repeated or reordered references. Named parameters with
504
+ an argument object are available through `client.execute()`.
505
+
506
+ The remote transaction integration test is opt-in. Point one or both variables
507
+ at a disposable writable sqld database. For a server that requires
508
+ authentication, also set `SDK_TEST_SQLITE_AUTH_TOKEN`.
509
+
510
+ ```bash
511
+ SDK_TEST_SQLITE_HTTP_URL='http://127.0.0.1:8080' \
512
+ SDK_TEST_SQLITE_LIBSQL_URL='libsql://127.0.0.1:8080?tls=0' \
513
+ pnpm --filter @happyvertical/sql exec vitest --config ../../vitest.package.config.ts run src/sqlite-remote-transaction.spec.ts
514
+ ```
515
+
490
516
  PostgreSQL CRUD helpers apply the same value serialization both inside and
491
517
  outside a transaction: objects and arrays are encoded for JSON/JSONB columns,
492
518
  dates use ISO timestamps, binary buffers and views retain their native `bytea`
@@ -684,6 +684,75 @@ function prepareManagedStatement(statement) {
684
684
  }
685
685
  return statement;
686
686
  }
687
+ var remoteParameterToken = /--[^\n]*|\/\*[\s\S]*?(?:\*\/|$)|'(?:''|[^'])*(?:'|$)|"(?:""|[^"])*(?:"|$)|`(?:``|[^`])*(?:`|$)|\[[^\]]*(?:\]|$)|[a-zA-Z_\u0080-\uFFFF][\w$\u0080-\uFFFF]*|[$:@][\w$\u0080-\uFFFF]+(?:::[\w$\u0080-\uFFFF]+)*(?:\([^)]*\))?/g;
688
+ function prepareRemoteStatement(statement) {
689
+ if (typeof statement !== "object" || !Array.isArray(statement.args)) return statement;
690
+ return {
691
+ ...statement,
692
+ sql: statement.sql.replace(remoteParameterToken, (token) => /^\$[1-9]\d*$/.test(token) ? `?${token.slice(1)}` : token)
693
+ };
694
+ }
695
+ async function guardRemoteTransaction(tx) {
696
+ const savepoint = "SAVEPOINT hv_remote_statement";
697
+ const release = `RELEASE ${savepoint}`;
698
+ await tx.execute(savepoint);
699
+ let aborted;
700
+ const assertActive = () => {
701
+ if (aborted) throw aborted.error;
702
+ };
703
+ const abort = (error) => {
704
+ aborted = { error };
705
+ tx.close();
706
+ };
707
+ return {
708
+ get closed() {
709
+ return tx.closed;
710
+ },
711
+ async execute(statement) {
712
+ assertActive();
713
+ try {
714
+ const [, result] = await tx.batch([
715
+ release,
716
+ statement,
717
+ savepoint
718
+ ]);
719
+ return result;
720
+ } catch (error) {
721
+ abort(error);
722
+ throw error;
723
+ }
724
+ },
725
+ async executeScoped(statement) {
726
+ assertActive();
727
+ try {
728
+ const [, , result] = await tx.batch([
729
+ release,
730
+ savepoint,
731
+ statement
732
+ ]);
733
+ return result;
734
+ } catch (error) {
735
+ if (error?.statementIndex === 2) try {
736
+ await tx.batch([release, savepoint]);
737
+ } catch {
738
+ abort(error);
739
+ }
740
+ else abort(error);
741
+ throw error;
742
+ }
743
+ },
744
+ async commit() {
745
+ assertActive();
746
+ await tx.commit();
747
+ },
748
+ rollback: () => tx.rollback(),
749
+ close: () => tx.close()
750
+ };
751
+ }
752
+ function remoteLibSqlUrl(url) {
753
+ const normalized = url.replace(/[\t\n\r]/g, "").trim();
754
+ return /^(?:https?|libsql):/i.test(normalized) ? normalized : void 0;
755
+ }
687
756
  /**
688
757
  * Orders secure adapter calls at public invocation time.
689
758
  *
@@ -1124,9 +1193,8 @@ function generateDbId() {
1124
1193
  async function createLibSQLClient(options) {
1125
1194
  const { url = ":memory:", authToken, encryptionKey } = options;
1126
1195
  let libsqlUrl = url;
1127
- const remoteUrl = url.replace(/[\t\n\r]/g, "").trim();
1128
- const hasRemoteScheme = /^(?:https?|libsql):/i.test(remoteUrl);
1129
- if (hasRemoteScheme) {
1196
+ const remoteUrl = remoteLibSqlUrl(url);
1197
+ if (remoteUrl) {
1130
1198
  libsqlUrl = remoteUrl;
1131
1199
  let parsedRemoteUrl;
1132
1200
  try {
@@ -1140,7 +1208,7 @@ async function createLibSQLClient(options) {
1140
1208
  throw new DatabaseError(`Invalid remote database URL: ${safeUrl}`, { url: safeUrl });
1141
1209
  }
1142
1210
  }
1143
- if (url !== ":memory:" && !hasRemoteScheme && !url.startsWith("file:")) {
1211
+ if (url !== ":memory:" && !remoteUrl && !url.startsWith("file:")) {
1144
1212
  const { resolve } = await import("node:path");
1145
1213
  libsqlUrl = `file://${resolve(url)}`;
1146
1214
  }
@@ -1154,7 +1222,7 @@ async function createLibSQLClient(options) {
1154
1222
  authToken,
1155
1223
  encryptionKey
1156
1224
  });
1157
- if (!hasRemoteScheme && url !== ":memory:") {
1225
+ if (!remoteUrl && url !== ":memory:") {
1158
1226
  const dispose = client.close.bind(client);
1159
1227
  let invalidated;
1160
1228
  const guard = async (operation) => {
@@ -1274,6 +1342,30 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
1274
1342
  return (async () => {
1275
1343
  const connectionLock = createTransactionLock("sqlite", options.transactionQueueTimeout);
1276
1344
  const client = await clientFactory();
1345
+ const remote = remoteLibSqlUrl(url) !== void 0;
1346
+ const reservesTransaction = remote || client.transactionReservation === "exclusive";
1347
+ const prepareStatement = (statement) => {
1348
+ const managed = prepareManagedStatement(remote && Array.isArray(statement) ? {
1349
+ sql: statement[0],
1350
+ args: statement[1]
1351
+ } : statement);
1352
+ return remote ? prepareRemoteStatement(managed) : managed;
1353
+ };
1354
+ const withExecuteArgs = (statement, args) => remote && typeof statement === "string" && args !== void 0 ? {
1355
+ sql: statement,
1356
+ args
1357
+ } : statement;
1358
+ const alreadyRolledBack = (error) => remote && error?.code === "TRANSACTION_TIMEOUT";
1359
+ const acquireTransaction = async () => {
1360
+ if (!remote) return client.transaction("write");
1361
+ const tx = await client.transaction("write");
1362
+ try {
1363
+ return await guardRemoteTransaction(tx);
1364
+ } catch (error) {
1365
+ tx.close();
1366
+ throw error;
1367
+ }
1368
+ };
1277
1369
  const executorContext = new AsyncLocalStorage();
1278
1370
  const transactionCallbackContext = new AsyncLocalStorage();
1279
1371
  const currentExecutor = () => executorContext.getStore() ?? client;
@@ -1831,7 +1923,7 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
1831
1923
  } catch (drainError) {
1832
1924
  if (drainError !== error) failure = combineTransactionFailures(error, drainError);
1833
1925
  }
1834
- try {
1926
+ if (!remote || !transactionClient.closed) try {
1835
1927
  await transactionClient.execute({
1836
1928
  sql: `ROLLBACK TO SAVEPOINT ${name}`,
1837
1929
  args: []
@@ -1841,7 +1933,7 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
1841
1933
  args: []
1842
1934
  });
1843
1935
  } catch (teardownError) {
1844
- if (teardownError !== failure) failure = combineTransactionFailures(failure, teardownError);
1936
+ if (teardownError !== failure && !alreadyRolledBack(teardownError)) failure = combineTransactionFailures(failure, teardownError);
1845
1937
  }
1846
1938
  throw failure;
1847
1939
  }
@@ -1893,7 +1985,7 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
1893
1985
  const transaction = async (callback, preAcquiredLock) => {
1894
1986
  const releaseConnection = await (preAcquiredLock ?? connectionLock.acquire());
1895
1987
  try {
1896
- if (client.transactionReservation !== "exclusive") {
1988
+ if (!reservesTransaction) {
1897
1989
  let nestedTransaction;
1898
1990
  let transactionScope;
1899
1991
  try {
@@ -1933,7 +2025,7 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
1933
2025
  throw failure;
1934
2026
  }
1935
2027
  }
1936
- const transactionClient = await client.transaction("write");
2028
+ const transactionClient = await acquireTransaction();
1937
2029
  let nestedTransaction;
1938
2030
  let transactionScope;
1939
2031
  try {
@@ -1960,7 +2052,7 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
1960
2052
  if (!transactionClient.closed) try {
1961
2053
  await transactionClient.rollback();
1962
2054
  } catch (rollbackError) {
1963
- failure = combineTransactionFailures(failure, rollbackError);
2055
+ if (!alreadyRolledBack(rollbackError)) failure = combineTransactionFailures(failure, rollbackError);
1964
2056
  }
1965
2057
  throw failure;
1966
2058
  } finally {
@@ -1982,9 +2074,9 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
1982
2074
  * transaction's work while later writes silently committed in autocommit.
1983
2075
  */
1984
2076
  const createTransactionScope = (transactionClient, nestedTransaction, runOperation = nestedTransaction.runOperation, runNested = nestedTransaction.runNested) => {
1985
- const isSecureTransaction = client.transactionReservation === "exclusive";
1986
- const scopedExecutor = isSecureTransaction ? { execute: (statement) => {
1987
- return transactionClient.execute(prepareManagedStatement(statement));
2077
+ const scopedExecutor = reservesTransaction ? { execute: (statement) => {
2078
+ const prepared = prepareStatement(statement);
2079
+ return transactionClient.executeScoped ? transactionClient.executeScoped(prepared) : transactionClient.execute(prepared);
1988
2080
  } } : transactionClient;
1989
2081
  let accepting = true;
1990
2082
  const pending = /* @__PURE__ */ new Set();
@@ -1993,7 +2085,7 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
1993
2085
  const bind = (fn, trackFailure = true) => ((...args) => {
1994
2086
  if (!accepting) return Promise.reject(new DatabaseError("Transaction scope is ending or ended", {}));
1995
2087
  const run = () => Promise.resolve(executorContext.run(scopedExecutor, () => fn(...args)));
1996
- const operation = isSecureTransaction ? runOperation(run) : run();
2088
+ const operation = reservesTransaction ? runOperation(run) : run();
1997
2089
  const tracked = {
1998
2090
  observed: false,
1999
2091
  handlers: /* @__PURE__ */ new Set(),
@@ -2045,14 +2137,14 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
2045
2137
  });
2046
2138
  const scopedClient = {
2047
2139
  transactionReservation: "exclusive",
2048
- execute: bind((statement) => scopedExecutor.execute(statement)),
2140
+ execute: bind((statement, args) => scopedExecutor.execute(withExecuteArgs(statement, args))),
2049
2141
  transaction: () => Promise.reject(new DatabaseError("Use the transaction scope transaction() method instead of client.transaction()", {})),
2050
2142
  close: () => Promise.reject(new DatabaseError("Transaction-scoped SQLite clients cannot be closed directly", {}))
2051
2143
  };
2052
2144
  return {
2053
2145
  database: {
2054
2146
  url,
2055
- client: client.transactionReservation === "exclusive" ? scopedClient : transactionClient,
2147
+ client: reservesTransaction ? scopedClient : transactionClient,
2056
2148
  insert: scopedInsert,
2057
2149
  get: scopedGet,
2058
2150
  list: scopedList,
@@ -2101,7 +2193,7 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
2101
2193
  const releaseConnection = await (preAcquiredLock ?? connectionLock.acquire());
2102
2194
  let transactionClient;
2103
2195
  try {
2104
- if (client.transactionReservation === "exclusive") transactionClient = await client.transaction("write");
2196
+ if (reservesTransaction) transactionClient = await acquireTransaction();
2105
2197
  else await client.execute({
2106
2198
  sql: "BEGIN TRANSACTION",
2107
2199
  args: []
@@ -2140,7 +2232,7 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
2140
2232
  if (transactionClient && !transactionClient.closed) try {
2141
2233
  await transactionClient.rollback();
2142
2234
  } catch (rollbackError) {
2143
- failure = combineTransactionFailures(failure, rollbackError);
2235
+ if (!alreadyRolledBack(rollbackError)) failure = combineTransactionFailures(failure, rollbackError);
2144
2236
  }
2145
2237
  else if (!transactionClient) try {
2146
2238
  await client.execute({
@@ -2527,10 +2619,10 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
2527
2619
  alterTable,
2528
2620
  close: rawClose
2529
2621
  };
2530
- if (client.transactionReservation !== "exclusive") return db;
2622
+ if (!reservesTransaction) return db;
2531
2623
  const barrier = createInvocationBarrier();
2532
2624
  const managedRootExecutor = { execute: (statement) => {
2533
- return client.execute(prepareManagedStatement(statement));
2625
+ return client.execute(prepareStatement(statement));
2534
2626
  } };
2535
2627
  const rootCallbackError = (operation) => operation === "close" ? new DatabaseError("Cannot close the SQLite database from inside its active transaction callback", { hint: "Finish the transaction callback before closing the database." }) : new DatabaseError("Cannot use the root SQLite database from inside its active transaction callback", { hint: "Use the transaction-scoped database passed to the callback." });
2536
2628
  const reservedClose = () => {
@@ -2620,15 +2712,18 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
2620
2712
  const reservedBeginTransaction = () => reserveTransactionEntry((preAcquiredLock) => beginTransaction(preAcquiredLock));
2621
2713
  const reservedClient = {
2622
2714
  transactionReservation: "exclusive",
2623
- execute: reserveManaged(async (statement) => {
2624
- return client.execute(prepareManagedStatement(statement));
2625
- }),
2715
+ execute: reserveManaged((statement, args) => managedRootExecutor.execute(withExecuteArgs(statement, args))),
2626
2716
  transaction: () => Promise.reject(new DatabaseError("Use database.transaction() or database.beginTransaction() instead of client.transaction()", {})),
2627
2717
  close: reservedClose
2628
2718
  };
2719
+ const publicClient = remote ? new Proxy(client, { get(target, property) {
2720
+ if (property === "execute" || property === "close") return reservedClient[property];
2721
+ const value = Reflect.get(target, property, target);
2722
+ return typeof value === "function" ? reserveManaged(value.bind(target)) : value;
2723
+ } }) : reservedClient;
2629
2724
  return {
2630
2725
  ...db,
2631
- client: reservedClient,
2726
+ client: publicClient,
2632
2727
  query: reserveManaged(query),
2633
2728
  insert: reserveManaged(insert),
2634
2729
  update: reserveManaged(update),
@@ -2661,4 +2756,4 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
2661
2756
  //#endregion
2662
2757
  export { getDatabase };
2663
2758
 
2664
- //# sourceMappingURL=sqlite-BKjTvVf3.js.map
2759
+ //# sourceMappingURL=sqlite-BVpWPLcf.js.map