@ohos-ports/libsql-client 0.18.0-beta.0

package/lib-esm/hrana.js

@@ -0,0 +1,341 @@
+import * as hrana from "@libsql/hrana-client";
+import { LibsqlError, LibsqlBatchError } from "@libsql/core/api";
+import { transactionModeToBegin, ResultSetImpl } from "@libsql/core/util";
+export class HranaTransaction {
+    #mode;
+    #version;
+    // Promise that is resolved when the BEGIN statement completes, or `undefined` if we haven't executed the
+    // BEGIN statement yet.
+    #started;
+    /** @private */
+    constructor(mode, version) {
+        this.#mode = mode;
+        this.#version = version;
+        this.#started = undefined;
+    }
+    execute(stmt) {
+        return this.batch([stmt]).then((results) => results[0]);
+    }
+    async batch(stmts) {
+        const stream = this._getStream();
+        if (stream.closed) {
+            throw new LibsqlError("Cannot execute statements because the transaction is closed", "TRANSACTION_CLOSED");
+        }
+        try {
+            const hranaStmts = stmts.map(stmtToHrana);
+            let rowsPromises;
+            if (this.#started === undefined) {
+                // The transaction hasn't started yet, so we need to send the BEGIN statement in a batch with
+                // `hranaStmts`.
+                this._getSqlCache().apply(hranaStmts);
+                const batch = stream.batch(this.#version >= 3);
+                const beginStep = batch.step();
+                const beginPromise = beginStep.run(transactionModeToBegin(this.#mode));
+                // Execute the `hranaStmts` only if the BEGIN succeeded, to make sure that we don't execute it
+                // outside of a transaction.
+                let lastStep = beginStep;
+                rowsPromises = hranaStmts.map((hranaStmt) => {
+                    const stmtStep = batch
+                        .step()
+                        .condition(hrana.BatchCond.ok(lastStep));
+                    if (this.#version >= 3) {
+                        // If the Hrana version supports it, make sure that we are still in a transaction
+                        stmtStep.condition(hrana.BatchCond.not(hrana.BatchCond.isAutocommit(batch)));
+                    }
+                    const rowsPromise = stmtStep.query(hranaStmt);
+                    rowsPromise.catch(() => undefined); // silence Node warning
+                    lastStep = stmtStep;
+                    return rowsPromise;
+                });
+                // `this.#started` is resolved successfully only if the batch and the BEGIN statement inside
+                // of the batch are both successful.
+                this.#started = batch
+                    .execute()
+                    .then(() => beginPromise)
+                    .then(() => undefined);
+                try {
+                    await this.#started;
+                }
+                catch (e) {
+                    // If the BEGIN failed, the transaction is unusable and we must close it. However, if the
+                    // BEGIN suceeds and `hranaStmts` fail, the transaction is _not_ closed.
+                    this.close();
+                    throw e;
+                }
+            }
+            else {
+                if (this.#version < 3) {
+                    // The transaction has started, so we must wait until the BEGIN statement completed to make
+                    // sure that we don't execute `hranaStmts` outside of a transaction.
+                    await this.#started;
+                }
+                else {
+                    // The transaction has started, but we will use `hrana.BatchCond.isAutocommit()` to make
+                    // sure that we don't execute `hranaStmts` outside of a transaction, so we don't have to
+                    // wait for `this.#started`
+                }
+                this._getSqlCache().apply(hranaStmts);
+                const batch = stream.batch(this.#version >= 3);
+                let lastStep = undefined;
+                rowsPromises = hranaStmts.map((hranaStmt) => {
+                    const stmtStep = batch.step();
+                    if (lastStep !== undefined) {
+                        stmtStep.condition(hrana.BatchCond.ok(lastStep));
+                    }
+                    if (this.#version >= 3) {
+                        stmtStep.condition(hrana.BatchCond.not(hrana.BatchCond.isAutocommit(batch)));
+                    }
+                    const rowsPromise = stmtStep.query(hranaStmt);
+                    rowsPromise.catch(() => undefined); // silence Node warning
+                    lastStep = stmtStep;
+                    return rowsPromise;
+                });
+                await batch.execute();
+            }
+            const resultSets = [];
+            for (let i = 0; i < rowsPromises.length; i++) {
+                try {
+                    const rows = await rowsPromises[i];
+                    if (rows === undefined) {
+                        throw new LibsqlBatchError("Statement in a transaction was not executed, " +
+                            "probably because the transaction has been rolled back", i, "TRANSACTION_CLOSED");
+                    }
+                    resultSets.push(resultSetFromHrana(rows));
+                }
+                catch (e) {
+                    if (e instanceof LibsqlBatchError) {
+                        throw e;
+                    }
+                    // Map hrana errors to LibsqlError first, then wrap in LibsqlBatchError
+                    const mappedError = mapHranaError(e);
+                    if (mappedError instanceof LibsqlError) {
+                        throw new LibsqlBatchError(mappedError.message, i, mappedError.code, mappedError.extendedCode, mappedError.rawCode, mappedError.cause instanceof Error
+                            ? mappedError.cause
+                            : undefined);
+                    }
+                    throw mappedError;
+                }
+            }
+            return resultSets;
+        }
+        catch (e) {
+            throw mapHranaError(e);
+        }
+    }
+    async executeMultiple(sql) {
+        const stream = this._getStream();
+        if (stream.closed) {
+            throw new LibsqlError("Cannot execute statements because the transaction is closed", "TRANSACTION_CLOSED");
+        }
+        try {
+            if (this.#started === undefined) {
+                // If the transaction hasn't started yet, start it now
+                this.#started = stream
+                    .run(transactionModeToBegin(this.#mode))
+                    .then(() => undefined);
+                try {
+                    await this.#started;
+                }
+                catch (e) {
+                    this.close();
+                    throw e;
+                }
+            }
+            else {
+                // Wait until the transaction has started
+                await this.#started;
+            }
+            await stream.sequence(sql);
+        }
+        catch (e) {
+            throw mapHranaError(e);
+        }
+    }
+    async rollback() {
+        try {
+            const stream = this._getStream();
+            if (stream.closed) {
+                return;
+            }
+            if (this.#started !== undefined) {
+                // We don't have to wait for the BEGIN statement to complete. If the BEGIN fails, we will
+                // execute a ROLLBACK outside of an active transaction, which should be harmless.
+            }
+            else {
+                // We did nothing in the transaction, so there is nothing to rollback.
+                return;
+            }
+            // Pipeline the ROLLBACK statement and the stream close.
+            const promise = stream.run("ROLLBACK").catch((e) => {
+                throw mapHranaError(e);
+            });
+            stream.closeGracefully();
+            await promise;
+        }
+        catch (e) {
+            throw mapHranaError(e);
+        }
+        finally {
+            // `this.close()` may close the `hrana.Client`, which aborts all pending stream requests, so we
+            // must call it _after_ we receive the ROLLBACK response.
+            // Also note that the current stream should already be closed, but we need to call `this.close()`
+            // anyway, because it may need to do more cleanup.
+            this.close();
+        }
+    }
+    async commit() {
+        // (this method is analogous to `rollback()`)
+        try {
+            const stream = this._getStream();
+            if (stream.closed) {
+                throw new LibsqlError("Cannot commit the transaction because it is already closed", "TRANSACTION_CLOSED");
+            }
+            if (this.#started !== undefined) {
+                // Make sure to execute the COMMIT only if the BEGIN was successful.
+                await this.#started;
+            }
+            else {
+                return;
+            }
+            const promise = stream.run("COMMIT").catch((e) => {
+                throw mapHranaError(e);
+            });
+            stream.closeGracefully();
+            await promise;
+        }
+        catch (e) {
+            throw mapHranaError(e);
+        }
+        finally {
+            this.close();
+        }
+    }
+}
+export async function executeHranaBatch(mode, version, batch, hranaStmts, disableForeignKeys = false) {
+    if (disableForeignKeys) {
+        batch.step().run("PRAGMA foreign_keys=off");
+    }
+    const beginStep = batch.step();
+    const beginPromise = beginStep.run(transactionModeToBegin(mode));
+    let lastStep = beginStep;
+    const stmtPromises = hranaStmts.map((hranaStmt) => {
+        const stmtStep = batch.step().condition(hrana.BatchCond.ok(lastStep));
+        if (version >= 3) {
+            stmtStep.condition(hrana.BatchCond.not(hrana.BatchCond.isAutocommit(batch)));
+        }
+        const stmtPromise = stmtStep.query(hranaStmt);
+        lastStep = stmtStep;
+        return stmtPromise;
+    });
+    const commitStep = batch.step().condition(hrana.BatchCond.ok(lastStep));
+    if (version >= 3) {
+        commitStep.condition(hrana.BatchCond.not(hrana.BatchCond.isAutocommit(batch)));
+    }
+    const commitPromise = commitStep.run("COMMIT");
+    const rollbackStep = batch
+        .step()
+        .condition(hrana.BatchCond.not(hrana.BatchCond.ok(commitStep)));
+    rollbackStep.run("ROLLBACK").catch((_) => undefined);
+    if (disableForeignKeys) {
+        batch.step().run("PRAGMA foreign_keys=on");
+    }
+    await batch.execute();
+    const resultSets = [];
+    await beginPromise;
+    for (let i = 0; i < stmtPromises.length; i++) {
+        try {
+            const hranaRows = await stmtPromises[i];
+            if (hranaRows === undefined) {
+                throw new LibsqlBatchError("Statement in a batch was not executed, probably because the transaction has been rolled back", i, "TRANSACTION_CLOSED");
+            }
+            resultSets.push(resultSetFromHrana(hranaRows));
+        }
+        catch (e) {
+            if (e instanceof LibsqlBatchError) {
+                throw e;
+            }
+            // Map hrana errors to LibsqlError first, then wrap in LibsqlBatchError
+            const mappedError = mapHranaError(e);
+            if (mappedError instanceof LibsqlError) {
+                throw new LibsqlBatchError(mappedError.message, i, mappedError.code, mappedError.extendedCode, mappedError.rawCode, mappedError.cause instanceof Error
+                    ? mappedError.cause
+                    : undefined);
+            }
+            throw mappedError;
+        }
+    }
+    await commitPromise;
+    return resultSets;
+}
+export function stmtToHrana(stmt) {
+    let sql;
+    let args;
+    if (Array.isArray(stmt)) {
+        [sql, args] = stmt;
+    }
+    else if (typeof stmt === "string") {
+        sql = stmt;
+    }
+    else {
+        sql = stmt.sql;
+        args = stmt.args;
+    }
+    const hranaStmt = new hrana.Stmt(sql);
+    if (args) {
+        if (Array.isArray(args)) {
+            hranaStmt.bindIndexes(args);
+        }
+        else {
+            for (const [key, value] of Object.entries(args)) {
+                hranaStmt.bindName(key, value);
+            }
+        }
+    }
+    return hranaStmt;
+}
+export function resultSetFromHrana(hranaRows) {
+    const columns = hranaRows.columnNames.map((c) => c ?? "");
+    const columnTypes = hranaRows.columnDecltypes.map((c) => c ?? "");
+    const rows = hranaRows.rows;
+    const rowsAffected = hranaRows.affectedRowCount;
+    const lastInsertRowid = hranaRows.lastInsertRowid !== undefined
+        ? hranaRows.lastInsertRowid
+        : undefined;
+    return new ResultSetImpl(columns, columnTypes, rows, rowsAffected, lastInsertRowid);
+}
+export function mapHranaError(e) {
+    if (e instanceof hrana.ClientError) {
+        const code = mapHranaErrorCode(e);
+        // TODO: Parse extendedCode once the SQL over HTTP protocol supports it
+        return new LibsqlError(e.message, code, undefined, undefined, e);
+    }
+    return e;
+}
+function mapHranaErrorCode(e) {
+    if (e instanceof hrana.ResponseError && e.code !== undefined) {
+        return e.code;
+    }
+    else if (e instanceof hrana.ProtoError) {
+        return "HRANA_PROTO_ERROR";
+    }
+    else if (e instanceof hrana.ClosedError) {
+        return e.cause instanceof hrana.ClientError
+            ? mapHranaErrorCode(e.cause)
+            : "HRANA_CLOSED_ERROR";
+    }
+    else if (e instanceof hrana.WebSocketError) {
+        return "HRANA_WEBSOCKET_ERROR";
+    }
+    else if (e instanceof hrana.HttpServerError) {
+        return "SERVER_ERROR";
+    }
+    else if (e instanceof hrana.ProtocolVersionError) {
+        return "PROTOCOL_VERSION_ERROR";
+    }
+    else if (e instanceof hrana.InternalError) {
+        return "INTERNAL_ERROR";
+    }
+    else {
+        return "UNKNOWN";
+    }
+}

package/lib-esm/http.d.ts

@@ -0,0 +1,39 @@
+/// <reference types="node" />
+import * as hrana from "@libsql/hrana-client";
+import type { Config, Client } from "@libsql/core/api";
+import type { InStatement, ResultSet, Transaction, IntMode, InArgs, Replicated } from "@libsql/core/api";
+import { TransactionMode } from "@libsql/core/api";
+import type { ExpandedConfig } from "@libsql/core/config";
+import { HranaTransaction } from "./hrana.js";
+import { SqlCache } from "./sql_cache.js";
+export * from "@libsql/core/api";
+export declare function createClient(config: Config): Client;
+/** @private */
+export declare function _createClient(config: ExpandedConfig): Client;
+export declare class HttpClient implements Client {
+    #private;
+    protocol: "http";
+    /** @private */
+    constructor(url: URL, authToken: string | undefined, intMode: IntMode, customFetch: Function | undefined, concurrency: number, remoteEncryptionKey: string | undefined);
+    private limit;
+    execute(stmtOrSql: InStatement | string, args?: InArgs): Promise<ResultSet>;
+    batch(stmts: Array<InStatement | [string, InArgs?]>, mode?: TransactionMode): Promise<Array<ResultSet>>;
+    migrate(stmts: Array<InStatement>): Promise<Array<ResultSet>>;
+    transaction(mode?: TransactionMode): Promise<HttpTransaction>;
+    executeMultiple(sql: string): Promise<void>;
+    sync(): Promise<Replicated>;
+    close(): void;
+    reconnect(): Promise<void>;
+    get closed(): boolean;
+}
+export declare class HttpTransaction extends HranaTransaction implements Transaction {
+    #private;
+    /** @private */
+    constructor(stream: hrana.HttpStream, mode: TransactionMode, version: hrana.ProtocolVersion);
+    /** @private */
+    _getStream(): hrana.Stream;
+    /** @private */
+    _getSqlCache(): SqlCache;
+    close(): void;
+    get closed(): boolean;
+}

package/lib-esm/http.js

@@ -0,0 +1,232 @@
+import * as hrana from "@libsql/hrana-client";
+import { LibsqlError } from "@libsql/core/api";
+import { expandConfig } from "@libsql/core/config";
+import { HranaTransaction, executeHranaBatch, stmtToHrana, resultSetFromHrana, mapHranaError, } from "./hrana.js";
+import { SqlCache } from "./sql_cache.js";
+import { encodeBaseUrl } from "@libsql/core/uri";
+import { supportedUrlLink } from "@libsql/core/util";
+import promiseLimit from "promise-limit";
+export * from "@libsql/core/api";
+export function createClient(config) {
+    return _createClient(expandConfig(config, true));
+}
+/** @private */
+export function _createClient(config) {
+    if (config.scheme !== "https" && config.scheme !== "http") {
+        throw new LibsqlError('The HTTP client supports only "libsql:", "https:" and "http:" URLs, ' +
+            `got ${JSON.stringify(config.scheme + ":")}. For more information, please read ${supportedUrlLink}`, "URL_SCHEME_NOT_SUPPORTED");
+    }
+    if (config.encryptionKey !== undefined) {
+        throw new LibsqlError("Encryption key is not supported by the remote client.", "ENCRYPTION_KEY_NOT_SUPPORTED");
+    }
+    if (config.scheme === "http" && config.tls) {
+        throw new LibsqlError(`A "http:" URL cannot opt into TLS by using ?tls=1`, "URL_INVALID");
+    }
+    else if (config.scheme === "https" && !config.tls) {
+        throw new LibsqlError(`A "https:" URL cannot opt out of TLS by using ?tls=0`, "URL_INVALID");
+    }
+    const url = encodeBaseUrl(config.scheme, config.authority, config.path);
+    return new HttpClient(url, config.authToken, config.intMode, config.fetch, config.concurrency, config.remoteEncryptionKey);
+}
+const sqlCacheCapacity = 30;
+export class HttpClient {
+    #client;
+    protocol;
+    #url;
+    #intMode;
+    #customFetch;
+    #concurrency;
+    #authToken;
+    #remoteEncryptionKey;
+    #promiseLimitFunction;
+    /** @private */
+    constructor(url, authToken, intMode, customFetch, concurrency, remoteEncryptionKey) {
+        this.#url = url;
+        this.#authToken = authToken;
+        this.#intMode = intMode;
+        this.#customFetch = customFetch;
+        this.#concurrency = concurrency;
+        this.#remoteEncryptionKey = remoteEncryptionKey;
+        this.#client = hrana.openHttp(this.#url, this.#authToken, this.#customFetch, remoteEncryptionKey);
+        this.#client.intMode = this.#intMode;
+        this.protocol = "http";
+        this.#promiseLimitFunction = promiseLimit(this.#concurrency);
+    }
+    async limit(fn) {
+        return this.#promiseLimitFunction(fn);
+    }
+    async execute(stmtOrSql, args) {
+        let stmt;
+        if (typeof stmtOrSql === "string") {
+            stmt = {
+                sql: stmtOrSql,
+                args: args || [],
+            };
+        }
+        else {
+            stmt = stmtOrSql;
+        }
+        return this.limit(async () => {
+            try {
+                const hranaStmt = stmtToHrana(stmt);
+                // Pipeline all operations, so `hrana.HttpClient` can open the stream, execute the statement and
+                // close the stream in a single HTTP request.
+                let rowsPromise;
+                const stream = this.#client.openStream();
+                try {
+                    rowsPromise = stream.query(hranaStmt);
+                }
+                finally {
+                    stream.closeGracefully();
+                }
+                const rowsResult = await rowsPromise;
+                return resultSetFromHrana(rowsResult);
+            }
+            catch (e) {
+                throw mapHranaError(e);
+            }
+        });
+    }
+    async batch(stmts, mode = "deferred") {
+        return this.limit(async () => {
+            try {
+                const normalizedStmts = stmts.map((stmt) => {
+                    if (Array.isArray(stmt)) {
+                        return {
+                            sql: stmt[0],
+                            args: stmt[1] || [],
+                        };
+                    }
+                    return stmt;
+                });
+                const hranaStmts = normalizedStmts.map(stmtToHrana);
+                const version = await this.#client.getVersion();
+                // Pipeline all operations, so `hrana.HttpClient` can open the stream, execute the batch and
+                // close the stream in a single HTTP request.
+                let resultsPromise;
+                const stream = this.#client.openStream();
+                try {
+                    // It makes sense to use a SQL cache even for a single batch, because it may contain the same
+                    // statement repeated multiple times.
+                    const sqlCache = new SqlCache(stream, sqlCacheCapacity);
+                    sqlCache.apply(hranaStmts);
+                    // TODO: we do not use a cursor here, because it would cause three roundtrips:
+                    // 1. pipeline request to store SQL texts
+                    // 2. cursor request
+                    // 3. pipeline request to close the stream
+                    const batch = stream.batch(false);
+                    resultsPromise = executeHranaBatch(mode, version, batch, hranaStmts);
+                }
+                finally {
+                    stream.closeGracefully();
+                }
+                const results = await resultsPromise;
+                return results;
+            }
+            catch (e) {
+                throw mapHranaError(e);
+            }
+        });
+    }
+    async migrate(stmts) {
+        return this.limit(async () => {
+            try {
+                const hranaStmts = stmts.map(stmtToHrana);
+                const version = await this.#client.getVersion();
+                // Pipeline all operations, so `hrana.HttpClient` can open the stream, execute the batch and
+                // close the stream in a single HTTP request.
+                let resultsPromise;
+                const stream = this.#client.openStream();
+                try {
+                    const batch = stream.batch(false);
+                    resultsPromise = executeHranaBatch("deferred", version, batch, hranaStmts, true);
+                }
+                finally {
+                    stream.closeGracefully();
+                }
+                const results = await resultsPromise;
+                return results;
+            }
+            catch (e) {
+                throw mapHranaError(e);
+            }
+        });
+    }
+    async transaction(mode = "write") {
+        return this.limit(async () => {
+            try {
+                const version = await this.#client.getVersion();
+                return new HttpTransaction(this.#client.openStream(), mode, version);
+            }
+            catch (e) {
+                throw mapHranaError(e);
+            }
+        });
+    }
+    async executeMultiple(sql) {
+        return this.limit(async () => {
+            try {
+                // Pipeline all operations, so `hrana.HttpClient` can open the stream, execute the sequence and
+                // close the stream in a single HTTP request.
+                let promise;
+                const stream = this.#client.openStream();
+                try {
+                    promise = stream.sequence(sql);
+                }
+                finally {
+                    stream.closeGracefully();
+                }
+                await promise;
+            }
+            catch (e) {
+                throw mapHranaError(e);
+            }
+        });
+    }
+    sync() {
+        throw new LibsqlError("sync not supported in http mode", "SYNC_NOT_SUPPORTED");
+    }
+    close() {
+        this.#client.close();
+    }
+    async reconnect() {
+        try {
+            if (!this.closed) {
+                // Abort in-flight ops and free resources
+                this.#client.close();
+            }
+        }
+        finally {
+            // Recreate the underlying hrana client
+            this.#client = hrana.openHttp(this.#url, this.#authToken, this.#customFetch, this.#remoteEncryptionKey);
+            this.#client.intMode = this.#intMode;
+        }
+    }
+    get closed() {
+        return this.#client.closed;
+    }
+}
+export class HttpTransaction extends HranaTransaction {
+    #stream;
+    #sqlCache;
+    /** @private */
+    constructor(stream, mode, version) {
+        super(mode, version);
+        this.#stream = stream;
+        this.#sqlCache = new SqlCache(stream, sqlCacheCapacity);
+    }
+    /** @private */
+    _getStream() {
+        return this.#stream;
+    }
+    /** @private */
+    _getSqlCache() {
+        return this.#sqlCache;
+    }
+    close() {
+        this.#stream.close();
+    }
+    get closed() {
+        return this.#stream.closed;
+    }
+}

package/lib-esm/node.d.ts

@@ -0,0 +1,7 @@
+import type { Config, Client } from "@libsql/core/api";
+export * from "@libsql/core/api";
+/** Creates a {@link Client} object.
+ *
+ * You must pass at least an `url` in the {@link Config} object.
+ */
+export declare function createClient(config: Config): Client;

package/lib-esm/node.js

@@ -0,0 +1,23 @@
+import { expandConfig } from "@libsql/core/config";
+import { _createClient as _createSqlite3Client } from "./sqlite3.js";
+import { _createClient as _createWsClient } from "./ws.js";
+import { _createClient as _createHttpClient } from "./http.js";
+export * from "@libsql/core/api";
+/** Creates a {@link Client} object.
+ *
+ * You must pass at least an `url` in the {@link Config} object.
+ */
+export function createClient(config) {
+    return _createClient(expandConfig(config, true));
+}
+function _createClient(config) {
+    if (config.scheme === "wss" || config.scheme === "ws") {
+        return _createWsClient(config);
+    }
+    else if (config.scheme === "https" || config.scheme === "http") {
+        return _createHttpClient(config);
+    }
+    else {
+        return _createSqlite3Client(config);
+    }
+}

package/lib-esm/sql_cache.d.ts

@@ -0,0 +1,7 @@
+import type * as hrana from "@libsql/hrana-client";
+export declare class SqlCache {
+    #private;
+    capacity: number;
+    constructor(owner: hrana.SqlOwner, capacity: number);
+    apply(hranaStmts: Array<hrana.Stmt>): void;
+}