@bastani/atomic-storage-libsql 0.9.48 → 0.9.49-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.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,21 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [0.9.49-alpha.1] - 2026-10-27
6
+
7
+ Self-hosted sqld namespaces and faster remote workflow journals.
8
+
9
+ - **sqld namespaces and custom headers:** a `namespace` option targets a self-hosted sqld namespace, and `openLibsqlDatabase` takes extra request `headers` that stay redacted in errors ([#4083](https://github.com/bastani-inc/atomic/issues/4083), [#4084](https://github.com/bastani-inc/atomic/pull/4084))
10
+ - **Faster remote journals:** a workflow journal's batch of appends reaches the database in one request instead of one per statement ([#4083](https://github.com/bastani-inc/atomic/issues/4083), [#4084](https://github.com/bastani-inc/atomic/pull/4084))
11
+
12
+ ### Added
13
+
14
+ - A `namespace` option selects a self-hosted sqld namespace (`sqld --enable-namespaces`), sent as the `x-namespace` header, and `openLibsqlDatabase` accepts extra request `headers`, whose values are redacted from errors ([#4083](https://github.com/bastani-inc/atomic/issues/4083))
15
+
16
+ ### Changed
17
+
18
+ - A workflow journal's batch of appends now reaches the database in one request instead of one per statement, so writing workflow progress to a remote database is much faster ([#4083](https://github.com/bastani-inc/atomic/issues/4083))
19
+
5
20
  ## [0.9.42] - 2026-10-23
6
21
 
7
22
  ### Added
package/README.md CHANGED
@@ -33,6 +33,7 @@ chmod 600 ~/.atomic/turso-token
33
33
  |---|---|---|
34
34
  | `url` | yes | A `libsql://`, `https://`, `wss://`, or `file:` URL. |
35
35
  | `authToken` | for remote databases | The database token. Pass it through `secrets` (`{ "file": ... }` or `{ "env": ... }`) so it stays out of settings. |
36
+ | `namespace` | no | A self-hosted sqld namespace (`sqld --enable-namespaces`), sent as the `x-namespace` header. Needs a `libsql:`, `https:`, or `http:` URL. |
36
37
 
37
38
  The token is redacted from error messages and diagnostics. Add a `prefix` to the `storage` block to keep projects or teams apart in one database. See [Storage](../coding-agent/docs/storage.md) for selection precedence, per-process overrides, and the other storage options.
38
39
 
@@ -44,7 +45,7 @@ import { openLibsqlDatabase } from "@bastani/atomic-storage-libsql";
44
45
  const database = await openLibsqlDatabase({ url: "libsql://<db>.turso.io", authToken });
45
46
  ```
46
47
 
47
- The returned `SqliteDatabase` can be passed as SDK `sessionStore: { kind: "database", database }` or workflow `journal: { database }`.
48
+ `openLibsqlDatabase` also accepts `namespace` and `headers` (extra request headers, redacted from errors), both for `libsql:`, `https:`, or `http:` URLs. The returned `SqliteDatabase` can be passed as SDK `sessionStore: { kind: "database", database }` or workflow `journal: { database }`; it sends a workflow journal's batch of appends to the database in one request.
48
49
 
49
50
  The package ships plain ESM JavaScript with TypeScript declarations. This import works in supported Node versions without a TypeScript loader.
50
51
 
package/libsql.d.ts CHANGED
@@ -3,6 +3,10 @@ import type { AdapterOptions, SqliteDatabase } from "@bastani/atomic/storage";
3
3
  export interface LibsqlDatabaseOptions {
4
4
  url: string;
5
5
  authToken?: string;
6
+ /** A self-hosted sqld namespace, sent as `x-namespace`. Needs a `libsql:`, `https:` or `http:` URL. */
7
+ namespace?: string;
8
+ /** Extra request headers, redacted from diagnostics. Needs a `libsql:`, `https:` or `http:` URL. */
9
+ headers?: Readonly<Record<string, string>>;
6
10
  }
7
11
 
8
12
  export function openLibsqlDatabase(options: LibsqlDatabaseOptions): Promise<SqliteDatabase>;
package/libsql.js CHANGED
@@ -1,7 +1,53 @@
1
1
  // @ts-check
2
2
  import { createSqliteDatabase, redactSecrets, StorageAdapterLoadError } from "@bastani/atomic/storage";
3
3
 
4
- /** @typedef {{ url: string, authToken?: string }} LibsqlDatabaseOptions */
4
+ /**
5
+ * @typedef {{ url: string, authToken?: string, namespace?: string, headers?: Readonly<Record<string, string>> }} LibsqlDatabaseOptions
6
+ */
7
+
8
+ /** Header names an HTTP request can carry: RFC 9110 tokens. */
9
+ const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
10
+
11
+ /**
12
+ * The request headers `namespace` and `headers` add, checked. A self-hosted sqld started with `--enable-namespaces`
13
+ * picks the database by `x-namespace`.
14
+ * @param {string} url
15
+ * @param {string | undefined} namespace
16
+ * @param {Readonly<Record<string, string>> | undefined} headers
17
+ * @returns {[string, string][]}
18
+ */
19
+ function requestHeaders(url, namespace, headers) {
20
+ /** @type {[string, string][]} */
21
+ const added = Object.entries(headers ?? {});
22
+ if (namespace !== undefined) {
23
+ if (typeof namespace !== "string" || namespace === "")
24
+ throw new TypeError('The libSQL storage adapter\'s "namespace" option must be a non-empty string');
25
+ added.push(["x-namespace", namespace]);
26
+ }
27
+ for (const [name, value] of added) {
28
+ if (!HEADER_NAME.test(name)) throw new TypeError(`The libSQL storage adapter can't send the header name ${JSON.stringify(name)}`);
29
+ if (typeof value !== "string" || /[\r\n\0]/.test(value))
30
+ throw new TypeError(`The libSQL storage adapter can't send the value of header ${JSON.stringify(name)}`);
31
+ }
32
+ if (added.length > 0 && !/^(libsql|https?):/i.test(url))
33
+ throw new TypeError(
34
+ 'The libSQL storage adapter sends "namespace" and "headers" only over HTTP: use a libsql:, https: or http: URL',
35
+ );
36
+ return added;
37
+ }
38
+
39
+ /**
40
+ * `fetch` that adds `headers` to every request the libSQL HTTP client sends.
41
+ * @param {[string, string][]} headers
42
+ * @returns {(input: RequestInfo | URL, init?: RequestInit) => Promise<Response>}
43
+ */
44
+ function fetchWith(headers) {
45
+ return (input, init) => {
46
+ const request = new Request(input, init);
47
+ for (const [name, value] of headers) request.headers.set(name, value);
48
+ return fetch(request);
49
+ };
50
+ }
5
51
 
6
52
  /**
7
53
  * Credentials a libSQL URL can carry: its userinfo and every `authToken` query value.
@@ -35,18 +81,26 @@ function urlCredentials(url) {
35
81
  function statements(connection) {
36
82
  return {
37
83
  async execute(sql, params) {
38
- const result = await connection().execute({ sql, args: [...params] });
39
- return { columns: result.columns, rows: result.rows, changes: result.rowsAffected };
84
+ return driverResult(await connection().execute({ sql, args: [...params] }));
40
85
  },
41
86
  executeMultiple: (sql) => connection().executeMultiple(sql),
42
87
  };
43
88
  }
44
89
 
90
+ /**
91
+ * @param {import("@libsql/client").ResultSet} result
92
+ * @returns {import("@bastani/atomic/storage").SqliteDriverResult}
93
+ */
94
+ function driverResult(result) {
95
+ return { columns: result.columns, rows: result.rows, changes: result.rowsAffected };
96
+ }
97
+
45
98
  /**
46
99
  * @param {LibsqlDatabaseOptions} options
47
100
  * @returns {Promise<import("@bastani/atomic/storage").SqliteDatabase>}
48
101
  */
49
- export async function openLibsqlDatabase({ url, authToken }) {
102
+ export async function openLibsqlDatabase({ url, authToken, namespace, headers }) {
103
+ const added = requestHeaders(url, namespace, headers);
50
104
  /** @type {typeof import("@libsql/client").createClient} */
51
105
  let createClient;
52
106
  try {
@@ -57,11 +111,20 @@ export async function openLibsqlDatabase({ url, authToken }) {
57
111
  /** @type {import("@libsql/client").Client | undefined} */
58
112
  let client;
59
113
  // Create the client inside a driver call, so the facade redacts credentials from its failures.
60
- const connection = () => (client ??= createClient({ url, authToken, intMode: "bigint" }));
114
+ const connection = () =>
115
+ (client ??= createClient({ url, authToken, intMode: "bigint", ...(added.length > 0 ? { fetch: fetchWith(added) } : {}) }));
61
116
  const database = createSqliteDatabase({
62
117
  descriptor: { adapter: "libsql", location: url },
63
- redact: redactSecrets([authToken ?? "", ...urlCredentials(url)]),
118
+ redact: redactSecrets([authToken ?? "", ...urlCredentials(url), ...Object.values(headers ?? {})]),
64
119
  ...statements(connection),
120
+ // One request for the whole batch, in a write transaction: the journal sends a batch of appends this way.
121
+ async batch(batched) {
122
+ const results = await connection().batch(
123
+ batched.map(({ sql, params }) => ({ sql, args: [...params] })),
124
+ "write",
125
+ );
126
+ return results.map(driverResult);
127
+ },
65
128
  async beginTransaction() {
66
129
  const transaction = await connection().transaction("write");
67
130
  return {
@@ -89,9 +152,13 @@ const adapter = {
89
152
  if (typeof options.url !== "string" || options.url === "") {
90
153
  throw new TypeError('The libSQL storage adapter requires a non-empty string "url" option');
91
154
  }
155
+ if (options.namespace !== undefined && typeof options.namespace !== "string") {
156
+ throw new TypeError('The libSQL storage adapter\'s "namespace" option must be a non-empty string');
157
+ }
92
158
  return openLibsqlDatabase({
93
159
  url: options.url,
94
160
  authToken: typeof options.authToken === "string" ? options.authToken : undefined,
161
+ ...(options.namespace === undefined ? {} : { namespace: options.namespace }),
95
162
  });
96
163
  },
97
164
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bastani/atomic-storage-libsql",
3
- "version": "0.9.48",
3
+ "version": "0.9.49-alpha.1",
4
4
  "description": "libSQL / Turso storage adapter for Atomic sessions, workflow journals, and Intercom.",
5
5
  "contributors": [
6
6
  "Norin Lavaee",