Hrana client for TypeScript

API docs | Github | npm

This package implements a Hrana client for TypeScript. Hrana is the protocol for connecting to sqld using WebSocket or HTTP.

This package is intended mostly for internal use. Consider using the @libsql/client package, which will use Hrana automatically.

Usage

1import * as hrana from "@libsql/hrana-client";
2
3// Open a `hrana.Client`, which works like a connection pool in standard SQL
4// databases. 
5const url = process.env.URL ?? "ws://localhost:8080"; // Address of the sqld server
6const jwt = process.env.JWT; // JWT token for authentication
7// Here we are using Hrana over WebSocket:
8const client = hrana.openWs(url, jwt);
9// But we can also use Hrana over HTTP:
10// const client = hrana.openHttp(url, jwt);
11
12// Open a `hrana.Stream`, which is an interactive SQL stream. This corresponds
13// to a "connection" from other SQL databases
14const stream = client.openStream();
15
16// Fetch all rows returned by a SQL statement
17const books = await stream.query("SELECT title, year FROM book WHERE author = 'Jane Austen'");
18// The rows are returned in an Array...
19for (const book of books.rows) {
20    // every returned row works as an array (`book[1]`) and as an object (`book.year`)
21    console.log(`${book.title} from ${book.year}`);
22}
23
24// Fetch a single row
25const book = await stream.queryRow("SELECT title, MIN(year) FROM book");
26if (book.row !== undefined) {
27    console.log(`The oldest book is ${book.row.title} from year ${book.row[1]}`);
28}
29
30// Fetch a single value, using a bound parameter
31const year = await stream.queryValue(["SELECT MAX(year) FROM book WHERE author = ?", ["Jane Austen"]]);
32if (year.value !== undefined) {
33    console.log(`Last book from Jane Austen was published in ${year.value}`);
34}
35
36// Execute a statement that does not return any rows
37const res = await stream.run(["DELETE FROM book WHERE author = ?", ["J. K. Rowling"]])
38console.log(`${res.affectedRowCount} books have been cancelled`);
39
40// When you are done, remember to close the client
41client.close();