@bastani/atomic-storage-libsql 0.9.48 → 0.9.49
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 +30 -0
- package/README.md +2 -1
- package/libsql.d.ts +4 -0
- package/libsql.js +73 -6
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,36 @@
|
|
|
2
2
|
|
|
3
3
|
## [Unreleased]
|
|
4
4
|
|
|
5
|
+
## [0.9.49] - 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
|
+
|
|
20
|
+
## [0.9.49-alpha.1] - 2026-10-27
|
|
21
|
+
|
|
22
|
+
Self-hosted sqld namespaces and faster remote workflow journals.
|
|
23
|
+
|
|
24
|
+
- **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))
|
|
25
|
+
- **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))
|
|
26
|
+
|
|
27
|
+
### Added
|
|
28
|
+
|
|
29
|
+
- 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))
|
|
30
|
+
|
|
31
|
+
### Changed
|
|
32
|
+
|
|
33
|
+
- 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))
|
|
34
|
+
|
|
5
35
|
## [0.9.42] - 2026-10-23
|
|
6
36
|
|
|
7
37
|
### 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
|
-
/**
|
|
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
|
-
|
|
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 = () =>
|
|
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
|
};
|