Add libSQL package (#3649)

Co-authored-by: Tim <[email protected]>

.changeset/blue-jokes-kneel.md

@@ -0,0 +1,5 @@
+---
+"@effect/sql-libsql": patch
+---
+
+Add sql-libsql package

packages/sql-libsql/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present The Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/sql-libsql/README.md

@@ -0,0 +1,5 @@
+# Effect SQL - libSQL
+
+An @effect/sql implementation using the `@libsql/client` library.
+
+See here for more information: https://github.com/Effect-TS/effect/tree/main/packages/sql

packages/sql-libsql/docgen.json

@@ -0,0 +1,6 @@
+{
+ "$schema": "../../node_modules/@effect/docgen/schema.json",
+ "exclude": [
+ "src/internal/**/*.ts"
+ ]
+}

packages/sql-libsql/package.json

@@ -0,0 +1,57 @@
+{
+ "name": "@effect/sql-libsql",
+ "version": "0.1.0",
+ "type": "module",
+ "license": "MIT",
+ "description": "A libSQL toolkit for Effect",
+ "homepage": "https://effect.website",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/Effect-TS/effect.git",
+ "directory": "packages/sql-libsql"
+ },
+ "bugs": {
+ "url": "https://github.com/Effect-TS/effect/issues"
+ },
+ "tags": [
+ "typescript",
+ "sql",
+ "libsql",
+ "database"
+ ],
+ "keywords": [
+ "typescript",
+ "sql",
+ "libsql",
+ "database"
+ ],
+ "publishConfig": {
+ "access": "public",
+ "directory": "dist",
+ "provenance": true
+ },
+ "scripts": {
+ "codegen": "build-utils prepare-v2",
+ "build": "pnpm build-esm && pnpm build-annotate && pnpm build-cjs && build-utils pack-v2",
+ "build-esm": "tsc -b tsconfig.build.json",
+ "build-cjs": "babel build/esm --plugins @babel/transform-export-namespace-from --plugins @babel/transform-modules-commonjs --out-dir build/cjs --source-maps",
+ "build-annotate": "babel build/esm --plugins annotate-pure-calls --out-dir build/esm --source-maps",
+ "check": "tsc -b tsconfig.json",
+ "test": "vitest",
+ "coverage": "vitest --coverage"
+ },
+ "devDependencies": {
+ "@effect/platform": "workspace:^",
+ "@effect/sql": "workspace:^",
+ "effect": "workspace:^"
+ },
+ "peerDependencies": {
+ "@effect/platform": "workspace:^",
+ "@effect/sql": "workspace:^",
+ "effect": "workspace:^"
+ },
+ "dependencies": {
+ "@libsql/client": "^0.12.0",
+ "@opentelemetry/semantic-conventions": "^1.25.1"
+ }
+}

packages/sql-libsql/src/LibsqlClient.ts

@@ -0,0 +1,207 @@
+/**
+ * @since 1.0.0
+ */
+import * as Client from "@effect/sql/SqlClient"
+import type { Connection } from "@effect/sql/SqlConnection"
+import { SqlError } from "@effect/sql/SqlError"
+import * as Statement from "@effect/sql/Statement"
+import * as Libsql from "@libsql/client"
+import * as Otel from "@opentelemetry/semantic-conventions"
+import * as Config from "effect/Config"
+import type { ConfigError } from "effect/ConfigError"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import { identity } from "effect/Function"
+import * as Layer from "effect/Layer"
+import * as Scope from "effect/Scope"
+
+/**
+ * @category type ids
+ * @since 1.0.0
+ */
+export const TypeId: unique symbol = Symbol.for("@effect/sql-libsql/LibsqlClient")
+
+/**
+ * @category type ids
+ * @since 1.0.0
+ */
+export type TypeId = typeof TypeId
+
+/**
+ * @category models
+ * @since 1.0.0
+ */
+export interface LibsqlClient extends Client.SqlClient {
+ readonly [TypeId]: TypeId
+ readonly config: LibsqlClientConfig
+}
+
+/**
+ * @category tags
+ * @since 1.0.0
+ */
+export const LibsqlClient = Context.GenericTag<LibsqlClient>("@effect/sql-libsql/LibsqlClient")
+
+/**
+ * @category models
+ * @since 1.0.0
+ */
+export interface LibsqlClientConfig {
+ /** The database URL.
+ *
+ * The client supports `libsql:`, `http:`/`https:`, `ws:`/`wss:` and `file:` URL. For more infomation,
+ * please refer to the project README:
+ *
+ * https://github.com/libsql/libsql-client-ts#supported-urls
+ */
+ readonly url: string
+ /** Authentication token for the database. */
+ readonly authToken?: string | undefined
+ /** Encryption key for the database. */
+ readonly encryptionKey?: string | undefined
+ /** URL of a remote server to synchronize database with. */
+ readonly syncUrl?: string | undefined
+ /** Sync interval in seconds. */
+ readonly syncInterval?: number | undefined
+ /** Enables or disables TLS for `libsql:` URLs.
+ *
+ * By default, `libsql:` URLs use TLS. You can set this option to `false` to disable TLS.
+ */
+ readonly tls?: boolean | undefined
+ /** How to convert SQLite integers to JavaScript values:
+ *
+ * - `"number"` (default): returns SQLite integers as JavaScript `number`-s (double precision floats).
+ * `number` cannot precisely represent integers larger than 2^53-1 in absolute value, so attempting to read
+ * larger integers will throw a `RangeError`.
+ * - `"bigint"`: returns SQLite integers as JavaScript `bigint`-s (arbitrary precision integers). Bigints can
+ * precisely represent all SQLite integers.
+ * - `"string"`: returns SQLite integers as strings.
+ */
+ readonly intMode?: "number" | "bigint" | "string" | undefined
+ /** Concurrency limit.
+ *
+ * By default, the client performs up to 20 concurrent requests. You can set this option to a higher
+ * number to increase the concurrency limit or set it to 0 to disable concurrency limits completely.
+ */
+ readonly concurrency?: number | undefined
+
+ readonly spanAttributes?: Record<string, unknown> | undefined
+
+ readonly transformResultNames?: ((str: string) => string) | undefined
+ readonly transformQueryNames?: ((str: string) => string) | undefined
+}
+
+interface LibsqlConnection extends Connection {}
+
+/**
+ * @category constructor
+ * @since 1.0.0
+ */
+export const make = (
+ options: LibsqlClientConfig
+): Effect.Effect<LibsqlClient, never, Scope.Scope> =>
+ Effect.gen(function*() {
+ const compiler = Statement.makeCompilerSqlite(options.transformQueryNames)
+ const transformRows = Statement.defaultTransforms(
+ options.transformResultNames!
+ ).array
+
+ const makeConnection = Effect.gen(function*() {
+ const db = Libsql.createClient(options as Libsql.Config)
+ yield* Effect.addFinalizer(() => Effect.sync(() => db.close()))
+
+ const run = (
+ sql: string,
+ params: ReadonlyArray<Statement.Primitive> = []
+ ) =>
+ Effect.tryPromise({
+ try: () => db.execute({ sql, args: params as Array<any> }).then((results) => results.rows),
+ catch: (cause) => new SqlError({ cause, message: "Failed to execute statement" })
+ })
+
+ const runRaw = (
+ sql: string,
+ params: ReadonlyArray<Statement.Primitive> = []
+ ) =>
+ Effect.tryPromise({
+ try: () => db.execute({ sql, args: params as Array<any> }),
+ catch: (cause) => new SqlError({ cause, message: "Failed to execute statement" })
+ })
+
+ const runTransform = options.transformResultNames
+ ? (sql: string, params?: ReadonlyArray<Statement.Primitive>) => Effect.map(run(sql, params), transformRows)
+ : run
+
+ return identity<LibsqlConnection>({
+ execute(sql, params) {
+ return runTransform(sql, params)
+ },
+ executeRaw(sql, params) {
+ return runRaw(sql, params)
+ },
+ executeValues(sql, params) {
+ return Effect.map(run(sql, params), (rows) => rows.map((row) => Array.from(row) as Array<any>))
+ },
+ executeWithoutTransform(sql, params) {
+ return run(sql, params)
+ },
+ executeUnprepared(sql, params) {
+ return run(sql, params)
+ },
+ executeStream(_sql, _params) {
+ return Effect.dieMessage("executeStream not implemented")
+ }
+ })
+ })
+
+ const semaphore = yield* Effect.makeSemaphore(1)
+ const connection = yield* makeConnection
+
+ const acquirer = semaphore.withPermits(1)(Effect.succeed(connection))
+ const transactionAcquirer = Effect.uninterruptibleMask((restore) =>
+ Effect.as(
+ Effect.zipRight(
+ restore(semaphore.take(1)),
+ Effect.tap(
+ Effect.scope,
+ (scope) => Scope.addFinalizer(scope, semaphore.release(1))
+ )
+ ),
+ connection
+ )
+ )
+
+ return Object.assign(
+ Client.make({
+ acquirer,
+ compiler,
+ transactionAcquirer,
+ spanAttributes: [
+ ...(options.spanAttributes ? Object.entries(options.spanAttributes) : []),
+ [Otel.SEMATTRS_DB_SYSTEM, Otel.DBSYSTEMVALUES_SQLITE]
+ ]
+ }) as LibsqlClient,
+ {
+ [TypeId]: TypeId as TypeId,
+ config: options
+ }
+ )
+ })
+
+/**
+ * @category layers
+ * @since 1.0.0
+ */
+export const layer = (
+ config: Config.Config.Wrap<LibsqlClientConfig>
+): Layer.Layer<LibsqlClient | Client.SqlClient, ConfigError> =>
+ Layer.scopedContext(
+ Config.unwrap(config).pipe(
+ Effect.flatMap(make),
+ Effect.map((client) =>
+ Context.make(LibsqlClient, client).pipe(
+ Context.add(Client.SqlClient, client)
+ )
+ )
+ )
+ )

packages/sql-libsql/src/LibsqlMigrator.ts

@@ -0,0 +1,38 @@
+/**
+ * @since 1.0.0
+ */
+import * as Migrator from "@effect/sql/Migrator"
+import type * as Client from "@effect/sql/SqlClient"
+import type { SqlError } from "@effect/sql/SqlError"
+import type * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+
+/**
+ * @since 1.0.0
+ */
+export * from "@effect/sql/Migrator"
+
+/**
+ * @since 1.0.0
+ */
+export * from "@effect/sql/Migrator/FileSystem"
+
+/**
+ * @category constructor
+ * @since 1.0.0
+ */
+export const run: <R2 = never>(
+ options: Migrator.MigratorOptions<R2>
+) => Effect.Effect<
+ ReadonlyArray<readonly [id: number, name: string]>,
+ Migrator.MigrationError | SqlError,
+ Client.SqlClient | R2
+> = Migrator.make({})
+
+/**
+ * @category constructor
+ * @since 1.0.0
+ */
+export const layer = <R>(
+ options: Migrator.MigratorOptions<R>
+): Layer.Layer<never, Migrator.MigrationError | SqlError, Client.SqlClient | R> => Layer.effectDiscard(run(options))

packages/sql-libsql/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @since 1.0.0
+ */
+export * as LibsqlClient from "./LibsqlClient.js"
+
+/**
+ * @since 1.0.0
+ */
+export * as LibsqlMigrator from "./LibsqlMigrator.js"