feature: add cloudflare @effect/sql-d1 package (#3045)

.changeset/clever-walls-smoke.md

@@ -0,0 +1,5 @@
+---
+"@effect/sql-d1": minor
+---
+
+Add new cloudflare @effect/sql-d1 package

packages/sql-d1/CHANGELOG.md

@@ -0,0 +1 @@
+# @effect/sql-d1

packages/sql-d1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-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-d1/README.md

@@ -0,0 +1,5 @@
+# Effect SQL - Cloudflare D1
+
+An @effect/sql implementation using cloudflare D1.
+
+See here for more information: https://github.com/Effect-TS/effect/tree/main/packages/sql

packages/sql-d1/docgen.json

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

packages/sql-d1/package.json

@@ -0,0 +1,60 @@
+{
+ "name": "@effect/sql-d1",
+ "version": "0.0.1",
+ "type": "module",
+ "license": "MIT",
+ "description": "A Cloudflare D1 integration for Effect",
+ "homepage": "https://effect.website",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/Effect-TS/effect.git",
+ "directory": "packages/sql-d1"
+ },
+ "bugs": {
+ "url": "https://github.com/Effect-TS/effect/issues"
+ },
+ "tags": [
+ "typescript",
+ "sql",
+ "database",
+ "cloudflare",
+ "D1"
+ ],
+ "keywords": [
+ "typescript",
+ "sql",
+ "database",
+ "cloudflare",
+ "D1"
+ ],
+ "publishConfig": {
+ "access": "public",
+ "directory": "dist",
+ "provenance": true
+ },
+ "scripts": {
+ "codegen": "build-utils prepare-v2",
+ "build": "pnpm build-esm && pnpm build-cjs && pnpm build-annotate && 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 --plugins annotate-pure-calls --out-dir build --source-maps",
+ "check": "tsc -b tsconfig.json",
+ "test": "vitest",
+ "coverage": "vitest --coverage"
+ },
+ "devDependencies": {
+ "@effect/platform": "workspace:^",
+ "@effect/sql": "workspace:^",
+ "effect": "workspace:^",
+ "miniflare": "^3.20240610.1"
+ },
+ "peerDependencies": {
+ "@effect/platform": "workspace:^",
+ "@effect/sql": "workspace:^",
+ "effect": "workspace:^"
+ },
+ "dependencies": {
+ "@cloudflare/workers-types": "^4.20240620.0",
+ "@opentelemetry/semantic-conventions": "^1.24.1"
+ }
+}

packages/sql-d1/src/D1Client.ts

@@ -0,0 +1,194 @@
+/**
+ * @since 1.0.0
+ */
+import type { D1Database, D1PreparedStatement } from "@cloudflare/workers-types"
+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 Otel from "@opentelemetry/semantic-conventions"
+import * as Cache from "effect/Cache"
+import * as Config from "effect/Config"
+import type { ConfigError } from "effect/ConfigError"
+import * as Context from "effect/Context"
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import { identity } from "effect/Function"
+import * as Layer from "effect/Layer"
+import type * as Scope from "effect/Scope"
+
+/**
+ * @category type ids
+ * @since 1.0.0
+ */
+export const TypeId: unique symbol = Symbol.for("@effect/sql-d1/D1Client")
+
+/**
+ * @category type ids
+ * @since 1.0.0
+ */
+export type TypeId = typeof TypeId
+
+/**
+ * @category models
+ * @since 1.0.0
+ */
+export interface D1Client extends Client.SqlClient {
+ readonly [TypeId]: TypeId
+ readonly config: D1ClientConfig
+
+ /** Not supported in d1 */
+ readonly updateValues: never
+}
+
+/**
+ * @category tags
+ * @since 1.0.0
+ */
+export const D1Client = Context.GenericTag<D1Client>("@effect/sql-d1/D1Client")
+
+/**
+ * @category models
+ * @since 1.0.0
+ */
+export interface D1ClientConfig {
+ readonly db: D1Database
+ readonly prepareCacheSize?: number | undefined
+ readonly prepareCacheTTL?: Duration.DurationInput | undefined
+ readonly spanAttributes?: Record<string, unknown> | undefined
+
+ readonly transformResultNames?: ((str: string) => string) | undefined
+ readonly transformQueryNames?: ((str: string) => string) | undefined
+}
+
+/**
+ * @category constructor
+ * @since 1.0.0
+ */
+export const make = (
+ options: D1ClientConfig
+): Effect.Effect<D1Client, 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 = options.db
+
+ const prepareCache = yield* Cache.make({
+ capacity: options.prepareCacheSize ?? 200,
+ timeToLive: options.prepareCacheTTL ?? Duration.minutes(10),
+ lookup: (sql: string) =>
+ Effect.try({
+ try: () => db.prepare(sql),
+ catch: (error) => new SqlError({ error })
+ })
+ })
+
+ const runStatement = (
+ statement: D1PreparedStatement,
+ params: ReadonlyArray<Statement.Primitive> = []
+ ) =>
+ Effect.tryPromise({
+ try: async () => {
+ const response = await statement.bind(...params).all()
+ if (response.error) {
+ throw response.error
+ }
+ return response.results || []
+ },
+ catch: (error) => new SqlError({ error })
+ })
+
+ const run = (
+ sql: string,
+ params: ReadonlyArray<Statement.Primitive> = []
+ ) => Effect.flatMap(prepareCache.get(sql), (s) => runStatement(s, params))
+
+ const runRaw = (
+ sql: string,
+ params: ReadonlyArray<Statement.Primitive> = []
+ ) => Effect.map(runStatement(db.prepare(sql), params), transformRows)
+
+ const runTransform = options.transformResultNames
+ ? (sql: string, params?: ReadonlyArray<Statement.Primitive>) => Effect.map(run(sql, params), transformRows)
+ : run
+
+ const runValues = (
+ sql: string,
+ params: ReadonlyArray<Statement.Primitive>
+ ) =>
+ Effect.flatMap(
+ prepareCache.get(sql),
+ (statement) =>
+ Effect.tryPromise({
+ try: () => {
+ return statement.bind(...params).raw() as Promise<
+ ReadonlyArray<
+ ReadonlyArray<Statement.Primitive>
+ >
+ >
+ },
+ catch: (error) => new SqlError({ error })
+ })
+ )
+
+ return identity<Connection>({
+ execute(sql, params) {
+ return runTransform(sql, params)
+ },
+ executeValues(sql, params) {
+ return runValues(sql, params)
+ },
+ executeWithoutTransform(sql, params) {
+ return run(sql, params)
+ },
+ executeRaw(sql, params) {
+ return runRaw(sql, params)
+ },
+ executeStream(_sql, _params) {
+ return Effect.dieMessage("executeStream not implemented")
+ }
+ })
+ })
+
+ const connection = yield* makeConnection
+ const acquirer = Effect.succeed(connection)
+ const transactionAcquirer = Effect.dieMessage("transactions are not supported in D1")
+
+ return Object.assign(
+ Client.make({
+ acquirer,
+ compiler,
+ transactionAcquirer,
+ spanAttributes: [
+ ...(options.spanAttributes ? Object.entries(options.spanAttributes) : []),
+ [Otel.SEMATTRS_DB_SYSTEM, Otel.DBSYSTEMVALUES_SQLITE]
+ ]
+ }) as D1Client,
+ {
+ [TypeId]: TypeId as TypeId,
+ config: options
+ }
+ )
+ })
+
+/**
+ * @category layers
+ * @since 1.0.0
+ */
+export const layer = (
+ config: Config.Config.Wrap<D1ClientConfig>
+): Layer.Layer<D1Client | Client.SqlClient, ConfigError> =>
+ Layer.scopedContext(
+ Config.unwrap(config).pipe(
+ Effect.flatMap(make),
+ Effect.map((client) =>
+ Context.make(D1Client, client).pipe(
+ Context.add(Client.SqlClient, client)
+ )
+ )
+ )
+ )

packages/sql-d1/src/index.ts

@@ -0,0 +1,4 @@
+/**
+ * @since 1.0.0
+ */
+export * as D1Client from "./D1Client.js"

packages/sql-d1/test/Client.test.ts

@@ -0,0 +1,43 @@
+import { D1Client } from "@effect/sql-d1"
+import { assert, describe, it } from "@effect/vitest"
+import { Cause, Effect } from "effect"
+import { D1Miniflare } from "./utils.js"
+
+describe("Client", () => {
+ it.scoped("should handle queries without transactions", () =>
+ Effect.gen(function*() {
+ const sql = yield* D1Client.D1Client
+ yield* sql`CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)`
+ yield* sql`INSERT INTO test (name) VALUES ('hello')`
+ let rows = yield* sql`SELECT * FROM test`
+ assert.deepStrictEqual(rows, [{ id: 1, name: "hello" }])
+ yield* sql`INSERT INTO test (name) VALUES ('world')`
+ rows = yield* sql`SELECT * FROM test`
+ assert.deepStrictEqual(rows, [
+ { id: 1, name: "hello" },
+ { id: 2, name: "world" }
+ ])
+ }).pipe(Effect.provide(D1Miniflare.ClientLive)))
+
+ it.scoped("should handle queries with params without transactions", () =>
+ Effect.gen(function*() {
+ const sql = yield* D1Client.D1Client
+ yield* sql`CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)`
+ yield* sql`INSERT INTO test ${sql.insert({ name: "hello" })}`
+ const rows = yield* sql`SELECT * FROM test WHERE name = ${"hello"}`
+ assert.deepStrictEqual(rows, [{ id: 1, name: "hello" }])
+ }).pipe(Effect.provide(D1Miniflare.ClientLive)))
+
+ it.scoped("should defect on transactions", () =>
+ Effect.gen(function*() {
+ const sql = yield* D1Client.D1Client
+ yield* sql`CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)`
+ const res = yield* sql`INSERT INTO test ${sql.insert({ name: "hello" })}`.pipe(
+ sql.withTransaction,
+ Effect.catchAllDefect((defect) => Effect.succeed(defect))
+ )
+ const rows = yield* sql`SELECT * FROM test`
+ assert.deepStrictEqual(rows, [])
+ assert.equal(Cause.isRuntimeException(res), true)
+ }).pipe(Effect.provide(D1Miniflare.ClientLive)))
+})