Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/DaBigBlob/libsql-stateless-easy

Thin libSQL stateless HTTP driver for TypeScript and JavaScript for the edge but easy 🚀
https://github.com/DaBigBlob/libsql-stateless-easy

bun cloudflare cloudflare-pages cloudflare-workers database http https lambda-functions libsql netlify node-js nodejs serverless serverless-functions sqlite vercel webapi

Last synced: about 2 months ago
JSON representation

Thin libSQL stateless HTTP driver for TypeScript and JavaScript for the edge but easy 🚀

Awesome Lists containing this project

README 

        
# libsql-stateless-easy



> Thin libSQL stateless HTTP driver for TypeScript and JavaScript for the edge but easy 🚀

- ✅ **Supported runtime environments:** Web API (browser, serverless), Bun, Node.js (>=18)

- ✅ **Is extremely light:** 8.82kB (unpacked)* / 3.8kB (gzipped)

- ✅ **Is built for:** Quick stateless query execution. (Mainly for serverless and edge functions.)

- ✅ Supports everything in `@libsql/client/web` **except `interactive transactions`.

- ✅ Unlike `@libsql/client/web`, **every function performs complete execution in exactly 1 roundtrip.**

- ✅ **`libsql-stateless-easy` is simply a drop-in replacement** and exactly same API as `@libsql/client/web`.



\* The actual js that is included with your project. (Excluding the type definitions and 2 copies of the main js for esm and cjs. (because you're gonna use one of them))  

\*\*Interactive transactions are not supported because this lib is stateless but [`transactions`](https://github.com/DaBigBlob/libsql-stateless/wiki/transactions) are supported.





# Installation

```sh

$ npm i libsql-stateless-easy #pnpm, yarn, etc.

# or

$ bun add libsql-stateless-easy

```



# Client Usage

`libsql-stateless-easy`'s `client` has the exact same API as [`@libsql/client/web`](https://docs.turso.tech/libsql/client-access/javascript-typescript-sdk#create-a-database-client-object-for-local-and-remote-access)'s `client`.

```ts

    import { createClient } from "libsql-stateless-easy";

    //or

    const { createClient } = require("libsql-stateless-easy");



    const client = createClient({

        url: "https://da-fish-mandible.turso.io",

        authToken: "fksdgfgksdgfksdg.javsdKDGKSBkgsdfg289374dg"

    });

    

    const res = await client.batch([

        {

            sql: "select * from contacts where contact_id = ?;",

            args: [3]

        },

        "select first_name, last_name, email from contacts where contact_id = 2",

        {

            sql: "insert into contacts (contact_id,first_name,last_name,email,phone) values (?,?,?,?,?);",

            args: [6,"glomm","feru","[email protected]","001"]

        },

        {

            sql: "delete from contacts where contact_id = :kkl",

            args: {kkl: 6}

        }

    ]);

    console.log(res);



    const res2 = await client.execute({

        sql: "select first_name, last_name, email, contact_id from contacts where contact_id = ?;",

        args: [1]

    });

    console.log(res2);

```



# Drizzle (and other ORMs)

**`libsql-stateless-easy`'s `client` works with drizzle (and other ORMs) out-of-the-box.**

This library implements the same Interface is the official client and therefore works with all the ORMs that the official client works with.

```ts

    import { createClient } from "libsql-stateless-easy";

    import { drizzle } from 'drizzle-orm/libsql';



    const client = createClient({

        url: "https://da-fish-mandible.turso.io",

        authToken: "fksdgfgksdgfksdg.javsdKDGKSBkgsdfg289374dg"

    });



    const db = drizzle(client);



    const result = await db.select().from(table_name).all();

    console.log(result);

```



- **This library has the exact `LibsqlError` API as `@libsql/client`**



## Performance

This library checks your configs, environments and server compatibility by default.  

However this is _kinda_ resource intensive if you're creating client instances often.  

So, **IF YOU ARE SURE YOUR CONFIGURATION, ENVIRONMENT AND SERVER VERSION ARE CORRECT, PLEASE DISABLE THE CHECKS FOR EVEN BETTER PERFORMANCE.**

```ts

    const client = createClient({

        url: "https://da-fish-mandible.turso.io",

        authToken: "fksdgfgksdgfksdg.javsdKDGKSBkgsdfg289374dg",

        disableCriticalChecks: true

    });

```



### List of other stuff in this library

Feel free to explore them (however you dont need to as they've been neatly packaged into the `client`)

```ts

import {

    libsqlValueBuilder, libsqlStatementBuilder, libsqlBatchReqStepsBuilder, libsqlBatchReqStepExecCondBuilder, libsqlTransactionBeginStatement,

    libsqlValueParser, libsqlStatementResParser, libsqlBatchStreamResParser, libsqlTransactionBatchStreamResParser,

    libsqlExecute, //has easier API than `libsql-stateless`'s function of the same name

    libsqlBatch, //has easier API than `libsql-stateless`'s function of the same name

    libsqlServerCompatCheck, //has easier API than `libsql-stateless`'s function of the same name,

    libsqlBatchTransaction, libsqlExecuteMultiple

    createClient //used above

} from "libsql-stateless-easy";

```

## API Level

> NOTE: current API level is that of latest stable [libsql-stateless](https://github.com/DaBigBlob/libsql-stateless).   

Read [this section](https://github.com/DaBigBlob/libsql-stateless/?tab=readme-ov-file#api-level).