libsql-stateless
Advanced tools
libsql-stateless - npm Package Compare versions
Comparing version 2.5.6 to 2.5.7
@@ -26,4 +26,4 @@ "use strict"; | ||
| * @description Executes exactly one (1) SQL statements. | ||
| * @param {libsqlConfig} conf libsql's config for DB connection {@link libsqlConfig} | ||
| * @param {libsqlSQLStatement} stmt libsql's raw API sql statement {@link libsqlSQLStatement} | ||
| * @param {libsqlConfig} conf libsql's config for DB connection: {@link libsqlConfig} | ||
| * @param {libsqlSQLStatement} stmt libsql's raw API sql statement: {@link libsqlSQLStatement} | ||
| */ | ||
@@ -58,4 +58,4 @@ async function libsqlExecute(conf, stmt) { | ||
| * @description Executes many SQL statements. Can be used to perform implicit transactions. | ||
| * @param {libsqlConfig} conf libsql's config for DB connection {@link libsqlConfig} | ||
| * @param {Array<BatchReqSteps>} batch_steps array of libsql's raw API sql batch steps {@link BatchReqSteps} | ||
| * @param {libsqlConfig} conf libsql's config for DB connection: {@link libsqlConfig} | ||
| * @param {Array<BatchReqSteps>} batch_steps array of libsql's raw API sql batch steps: {@link BatchReqSteps} | ||
| */ | ||
@@ -90,3 +90,3 @@ async function libsqlBatch(conf, batch_steps) { | ||
| * @description Check if the server supports this library | ||
| * @param {Config} conf libsql's config for DB connection {@link libsqlConfig} | ||
| * @param {Config} conf libsql's config for DB connection: {@link libsqlConfig} | ||
| */ | ||
@@ -93,0 +93,0 @@ async function libsqlServerCompatCheck(conf) { |
@@ -5,4 +5,4 @@ import { libsqlBatchReqStep, libsqlBatchStreamResOkData, libsqlConfig, libsqlPipelineResErr, libsqlResult, libsqlSQLStatement, libsqlStatementResOkData, libsqlStreamResErrData } from "./types"; | ||
| * @description Executes exactly one (1) SQL statements. | ||
| * @param {libsqlConfig} conf libsql's config for DB connection {@link libsqlConfig} | ||
| * @param {libsqlSQLStatement} stmt libsql's raw API sql statement {@link libsqlSQLStatement} | ||
| * @param {libsqlConfig} conf libsql's config for DB connection: {@link libsqlConfig} | ||
| * @param {libsqlSQLStatement} stmt libsql's raw API sql statement: {@link libsqlSQLStatement} | ||
| */ | ||
@@ -13,4 +13,4 @@ export declare function libsqlExecute(conf: libsqlConfig, stmt: libsqlSQLStatement): Promise<libsqlResult<libsqlStatementResOkData, libsqlStreamResErrData | libsqlPipelineResErr>>; | ||
| * @description Executes many SQL statements. Can be used to perform implicit transactions. | ||
| * @param {libsqlConfig} conf libsql's config for DB connection {@link libsqlConfig} | ||
| * @param {Array<BatchReqSteps>} batch_steps array of libsql's raw API sql batch steps {@link BatchReqSteps} | ||
| * @param {libsqlConfig} conf libsql's config for DB connection: {@link libsqlConfig} | ||
| * @param {Array<BatchReqSteps>} batch_steps array of libsql's raw API sql batch steps: {@link BatchReqSteps} | ||
| */ | ||
@@ -21,4 +21,4 @@ export declare function libsqlBatch(conf: libsqlConfig, batch_steps: Array<libsqlBatchReqStep>): Promise<libsqlResult<libsqlBatchStreamResOkData, libsqlStreamResErrData | libsqlPipelineResErr>>; | ||
| * @description Check if the server supports this library | ||
| * @param {Config} conf libsql's config for DB connection {@link libsqlConfig} | ||
| * @param {Config} conf libsql's config for DB connection: {@link libsqlConfig} | ||
| */ | ||
| export declare function libsqlServerCompatCheck(conf: libsqlConfig): Promise<libsqlResult<null, null>>; |
@@ -23,4 +23,4 @@ async function hranaFetch(s) { | ||
| * @description Executes exactly one (1) SQL statements. | ||
| * @param {libsqlConfig} conf libsql's config for DB connection {@link libsqlConfig} | ||
| * @param {libsqlSQLStatement} stmt libsql's raw API sql statement {@link libsqlSQLStatement} | ||
| * @param {libsqlConfig} conf libsql's config for DB connection: {@link libsqlConfig} | ||
| * @param {libsqlSQLStatement} stmt libsql's raw API sql statement: {@link libsqlSQLStatement} | ||
| */ | ||
@@ -54,4 +54,4 @@ export async function libsqlExecute(conf, stmt) { | ||
| * @description Executes many SQL statements. Can be used to perform implicit transactions. | ||
| * @param {libsqlConfig} conf libsql's config for DB connection {@link libsqlConfig} | ||
| * @param {Array<BatchReqSteps>} batch_steps array of libsql's raw API sql batch steps {@link BatchReqSteps} | ||
| * @param {libsqlConfig} conf libsql's config for DB connection: {@link libsqlConfig} | ||
| * @param {Array<BatchReqSteps>} batch_steps array of libsql's raw API sql batch steps: {@link BatchReqSteps} | ||
| */ | ||
@@ -85,3 +85,3 @@ export async function libsqlBatch(conf, batch_steps) { | ||
| * @description Check if the server supports this library | ||
| * @param {Config} conf libsql's config for DB connection {@link libsqlConfig} | ||
| * @param {Config} conf libsql's config for DB connection: {@link libsqlConfig} | ||
| */ | ||
@@ -88,0 +88,0 @@ export async function libsqlServerCompatCheck(conf) { |
@@ -109,3 +109,3 @@ export type libsqlResult<T, E> = { | ||
| export type libsqlStatementResOkData = { | ||
| cols: Array<libsqlSQLColumn>; | ||
| cols: Array<libsqlSQLColumnElm>; | ||
| rows: Array<Array<libsqlSQLValue>>; | ||
@@ -119,5 +119,5 @@ affected_row_count: number; | ||
| }; | ||
| export type libsqlSQLColumn = { | ||
| export type libsqlSQLColumnElm = { | ||
| name: string | null; | ||
| decltype: string | null; | ||
| }; |
| { | ||
| "name": "libsql-stateless", | ||
| "version": "2.5.6", | ||
| "version": "2.5.7", | ||
| "homepage": "https://github.com/DaBigBlob/libsql-stateless#readme", | ||
@@ -5,0 +5,0 @@ "repository": { |
366
README.md
| # libsql-stateless | ||
| > Thin libSQL stateless HTTP driver for TypeScript and JavaScript. | ||
| > Thin libSQL stateless HTTP driver for TypeScript and JavaScript for the edge 🚀 | ||
| - ✅ **Supported runtime environments:** Web API (browser, serverless), Bun, Node.js (>=18) | ||
| - ✅ **Extremely thin:** Has no dependency, only has a few functions that implement the [`Hrana v3 HTTP`](https://github.com/tursodatabase/libsql/blob/main/libsql-server/docs/HRANA_3_SPEC.md) protocol from scratch, and has no classes (tend to hog memory). | ||
| - ✅ **Extremely thin:** Has no dependency, only has a few functions that implement the [`Hrana v3 HTTP`](https://github.com/tursodatabase/libsql/blob/main/libsql-server/docs/HRANA_3_SPEC.md) protocol from scratch, and has no classes (tend to duplicate memory and/or perform long memory traversals). | ||
| - ✅ **Does no extra computation.** | ||
| - ✅ **Has no premature optimizations.** | ||
| - ✅ **Is built for:** Quick stateless query execution. (Mainly for serverless and edge functions.) | ||
| - ⚠️ **Supports everything in @libsql/client** except `transactions`. | ||
| - ⚠️ Supports everything in `@libsql/client` **except (explicit) `transactions` and local or in-memory DBs.** | ||
| - ⚠️ **The API provided by `libsql-stateless` is raw and explicit** for reducing (computational and memory) overheads. | ||
| **For easier DX, consider using [`libsql-stateless-easy`](https://github.com/DaBigBlob/libsql-stateless-easy) instead**: this, however, comes at the cost of non-zero-dependency and (computational and memory) overheads potentially unneeded by you. But is still very very very slim compared to `@libsql/client`. | ||
| # Why not just use `@libsql/client`? | ||
| 1. Not everyone needs stateful DB connection or the overheads that come with it. | ||
| 2. To provide a simpler API, `@libsql/client` does a lot of, I'd argue, unnecessary computation under the hood.\ | ||
| Many people would rather use a more complex API than have worse performance. | ||
| # Installation | ||
@@ -17,355 +25,7 @@ ```sh | ||
| ``` | ||
| ⚠️ **WARNING: The Docs are out of date. Give me a few days.** | ||
| # Goto [`WIKI`](https://github.com/DaBigBlob/libsql-stateless/wiki) for Specifications and Examples | ||
| ## The Result Type | ||
| Every function in this library returns a `Result<T, R>` type. | ||
| `Result<T, R>` is either: | ||
| ```ts | ||
| { | ||
| isOk: true, | ||
| val: T | ||
| } | ||
| ``` | ||
| or: | ||
| ```ts | ||
| { | ||
| isOk: false, | ||
| err: R | ||
| } | ||
| ``` | ||
| For example, the function `await libsqlExecute(conf: libsql_conf, stmt: libsql_statement)` returns `Result<libsql_statement_result, libsql_error>`, which is either: | ||
| ```ts | ||
| { | ||
| isOk: true, | ||
| val: libsql_statement_result | ||
| } | ||
| ``` | ||
| or: | ||
| ```ts | ||
| { | ||
| isOk: false, | ||
| err: libsql_error | ||
| } | ||
| ``` | ||
| ### Benefits of Result Type | ||
| - No need of ugly try { } catch { }. | ||
| - Elegant error handling: | ||
| ```ts | ||
| //you can do something like | ||
| const res = await libsqlExecute(conf, {sql: "SELECT * FROM mad_cats;"}); | ||
| if (res.isOk) { | ||
| //now res.val is guaranteed by typescript [js users, sorry] | ||
| console.log(res.val.rows); //the rows returned | ||
| console.log(res.val.affected_row_count) //affected rows | ||
| //... | ||
| } else { | ||
| //now res.err is guaranteed by typescript | ||
| console.log(res.err.message); //error message | ||
| doSomething(res.err.code) //do something with the error code | ||
| //... | ||
| } | ||
| ``` | ||
| ## The `libsqlExecute` Function | ||
| This function executes exactly one (1) SQL query. | ||
| ### Type | ||
| ```ts | ||
| async function libsqlExecute(conf: libsql_conf, stmt: libsql_statement): Promise<Result<libsql_statement_result, libsql_error>>; | ||
| ``` | ||
| ### Parameters | ||
| 1. `conf` of type `libsql_conf` | ||
| ```ts | ||
| import { libsql_conf } from "libsql-stateless"; | ||
| //sturucture of libsql_conf | ||
| { | ||
| db_url: string, | ||
| authToken?: string | ||
| } | ||
| ``` | ||
| 2. `stmt` of type `libsql_statement` | ||
| ```ts | ||
| import { libsql_statement, libsql_value } from "libsql-stateless"; | ||
| //sturucture of libsql_statement | ||
| { | ||
| "sql": string, | ||
| "args"?: Array<libsql_value>, | ||
| "named_args"?: Array<{ | ||
| "name": string, | ||
| "value": libsql_value, | ||
| }>, | ||
| "want_rows"?: boolean, | ||
| } | ||
| //structure of libsql_value | ||
| { "type": "null" } | | ||
| { "type": "integer", "value": string } | | ||
| { "type": "float", "value": number } | | ||
| { "type": "text", "value": string } | | ||
| { "type": "blob", "base64": string }; | ||
| ``` | ||
| ### Returns | ||
| This function returns a `Promise<Result<libsql_statement_result, libsql_error>>` therefore `await` is used before it to get `Result<libsql_statement_result, libsql_error>`. | ||
| `Result<T, R>` types have heen discussed above. | ||
| ```ts | ||
| import { libsql_statement_result, libsql_error, libsql_column, libsql_value } from "libsql-stateless"; | ||
| //structure of libsql_error | ||
| { | ||
| "message": string; | ||
| "code"?: string | null; | ||
| } | ||
| //structure of libsql_statement_result | ||
| { | ||
| "cols": Array<libsql_column>, | ||
| "rows": Array<Array<libsql_value>>, | ||
| "affected_row_count": number, //uint32 | ||
| "last_insert_rowid": string | null, | ||
| } | ||
| //structure of libsql_column | ||
| { | ||
| "name": string | null, | ||
| "decltype": string | null, | ||
| } | ||
| //structure of libsql_value | ||
| { "type": "null" } | | ||
| { "type": "integer", "value": string } | | ||
| { "type": "float", "value": number } | | ||
| { "type": "text", "value": string } | | ||
| { "type": "blob", "base64": string }; | ||
| ``` | ||
| ### Example | ||
| ```ts | ||
| import { libsqlExecute } from "libsql-stateless"; | ||
| //or | ||
| const { libsqlExecute } = require("libsql-stateless"); //for cjs | ||
| const res = await libsqlExecute(conf, {sql: "SELECT * FROM mad_cats;"}); | ||
| //or | ||
| const res = await libsqlExecute(conf, { | ||
| sql: "SELECT madness, power_level FROM mad_cats WHERE cat_id = ? AND owner_name = ?;", | ||
| args: [ | ||
| { | ||
| type: "integer", | ||
| value: "89342" | ||
| }, | ||
| { | ||
| type: "text", | ||
| value: "John Smith" | ||
| } | ||
| ] | ||
| }); | ||
| //or | ||
| const res = await libsqlExecute(conf, { | ||
| sql: "INSERT INTO mad_cats VALUES (:cat_name, :power_level, :madness);", //In SQLite, the names of arguments include the prefix sign (:, @ or $). | ||
| named_args: [ | ||
| { | ||
| name: "cat_name", | ||
| value: { | ||
| type: "text", | ||
| value: "Bgorthe, The Destroyer of Worlds" | ||
| } | ||
| }, | ||
| { | ||
| name: "power_level", | ||
| value: { | ||
| type: "integer", | ||
| value: "9105" | ||
| } | ||
| }, | ||
| { | ||
| name: "madness", | ||
| value: { | ||
| type: "float", | ||
| value: "32.5" | ||
| } | ||
| } | ||
| ] | ||
| }); | ||
| ``` | ||
| ## The `libsqlBatch` Function | ||
| This function executes SQL queries in a batch. | ||
| ### Type | ||
| ```ts | ||
| async function libsqlBatch(conf: libsql_conf, batch_steps: Array<libsql_batch_step>): Promise<Result<libsql_batch_statement_result, libsql_error>>; | ||
| ``` | ||
| ### Parameters | ||
| 1. `conf` of type `libsql_conf` | ||
| ```ts | ||
| import { libsql_conf } from "libsql-stateless"; | ||
| //sturucture of libsql_conf | ||
| { | ||
| db_url: string, | ||
| authToken?: string | ||
| } | ||
| ``` | ||
| 2. `batch_steps` of type `Array<libsql_batch_step>` | ||
| ```ts | ||
| import { libsql_batch_step, libsql_batch_execution_condition, libsql_statement } from "libsql-stateless"; | ||
| //sturucture of libsql_batch_step | ||
| { | ||
| "condition"?: libsql_batch_execution_condition | null; | ||
| "stmt": libsql_statement; | ||
| } | ||
| //structure of libsql_batch_execution_condition | ||
| { "type": "ok", "step": number } |//uint32 | ||
| { "type": "error", "step": number } |//uint32 | ||
| { "type": "not", "cond": libsql_batch_execution_condition } | | ||
| { "type": "and", "conds": Array<libsql_batch_execution_condition> } | | ||
| { "type": "or", "conds": Array<libsql_batch_execution_condition> } | | ||
| { "type": "is_autocommit" }; | ||
| //sturucture of libsql_statement | ||
| { | ||
| "sql": string, | ||
| "args"?: Array<libsql_value>, | ||
| "named_args"?: Array<{ | ||
| "name": string, | ||
| "value": libsql_value, | ||
| }>, | ||
| "want_rows"?: boolean, | ||
| } | ||
| ``` | ||
| ### Returns | ||
| This function returns a `Promise<Result<libsql_batch_statement_result, libsql_error>>` therefore `await` is used before it to get `Result<libsql_batch_statement_result, libsql_error>`. | ||
| `Result<T, R>` types have heen discussed above. | ||
| ```ts | ||
| import { libsql_batch_statement_result, libsql_error, libsql_statement_result, libsql_column, libsql_value } from "libsql-stateless"; | ||
| //structure of libsql_error | ||
| { | ||
| "message": string; | ||
| "code"?: string | null; | ||
| } | ||
| //structure of libsql_batch_statement_result | ||
| { | ||
| "step_results": Array<libsql_statement_result | null>; | ||
| "step_errors": Array<libsql_error | null>; | ||
| } | ||
| //structure of libsql_statement_result | ||
| { | ||
| "cols": Array<libsql_column>, | ||
| "rows": Array<Array<libsql_value>>, | ||
| "affected_row_count": number, //uint32 | ||
| "last_insert_rowid": string | null, | ||
| } | ||
| //structure of libsql_column | ||
| { | ||
| "name": string | null, | ||
| "decltype": string | null, | ||
| } | ||
| //structure of libsql_value | ||
| { "type": "null" } | | ||
| { "type": "integer", "value": string } | | ||
| { "type": "float", "value": number } | | ||
| { "type": "text", "value": string } | | ||
| { "type": "blob", "base64": string }; | ||
| ``` | ||
| ### Example | ||
| ```ts | ||
| import { libsqlBatch } from "libsql-stateless"; | ||
| //or | ||
| const { libsqlBatch } = require("libsql-stateless"); //for cjs | ||
| const res = await libsqlBatch(conf, [ | ||
| {stmt: {sql: "SELECT * FROM mad_cats;"}}, | ||
| {stmt: { | ||
| sql: "SELECT madness, power_level FROM mad_cats WHERE cat_id = ? AND owner_name = ?;", | ||
| args: [ | ||
| { | ||
| type: "integer", | ||
| value: "89342" | ||
| }, | ||
| { | ||
| type: "text", | ||
| value: "John Smith" | ||
| } | ||
| ] | ||
| }}, | ||
| {stmt: { | ||
| sql: "INSERT INTO mad_cats VALUES (:cat_name, :power_level, :madness);", //In SQLite, the names of arguments include the prefix sign (:, @ or $). | ||
| named_args: [ | ||
| { | ||
| name: "cat_name", | ||
| value: { | ||
| type: "text", | ||
| value: "Bgorthe, The Destroyer of Worlds" | ||
| } | ||
| }, | ||
| { | ||
| name: "power_level", | ||
| value: { | ||
| type: "integer", | ||
| value: "9105" | ||
| } | ||
| }, | ||
| { | ||
| name: "madness", | ||
| value: { | ||
| type: "float", | ||
| value: "32.5" | ||
| } | ||
| } | ||
| ] | ||
| }} | ||
| ]); | ||
| //or | ||
| const res = await libsqlBatch(conf, [ | ||
| {stmt: {sql: "SELECT * FROM mad_cats;"}, condition: { "type": "is_autocommit" }} | ||
| ]); | ||
| ``` | ||
| ## The `libsqlServerCompatCheck` Function | ||
| This function checks if the `db_url`'s server supports `Hrana HTTP API v3`. | ||
| ### Type | ||
| ```ts | ||
| async function libsqlServerCompatCheck(db_url: string): Promise<Result<null, null>>; | ||
| ``` | ||
| ### Parameters | ||
| 1. `db_url` of type `string` | ||
| ### Returns | ||
| This function returns a `Promise<Result<null, null>>` therefore `await` is used before it to get `Result<null, null>`. | ||
| `Result<T, R>` types have heen discussed above. | ||
| ### Example | ||
| ```ts | ||
| import { libsqlServerCompatCheck } from "libsql-stateless"; //for mjs | ||
| //or | ||
| const { libsqlServerCompatCheck } = require("libsql-stateless"); //for cjs | ||
| const res = await libsqlServerCompatCheck(conf.db_url); | ||
| ``` | ||
| # TODO | ||
| - Add JS/TS Docs along with example snippets. | ||
| - Add Drizzle ORM support? | ||
| - Switch to protobuf from json? (not really needed if not reading thousands of rows/s) | ||
| - Finding the purpose of my existence. | ||
@@ -372,0 +32,0 @@ |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Worsened metrics
- Total package byte prevSize
- decreased by-31.82%
16717
- Number of lines in readme file
- decreased by-91.15%
33
No dependency changes