sdk/effect/db

Classes

AstroDB

Defined in: studiocms/packages/studiocms/src/sdk/effect/db.ts:167^

Provides an Effect-based service wrapper for interacting with an AstroDB database client.

Remarks

This service exposes utility functions for executing queries, managing transactions, and composing database effects using the Effect system. It handles error mapping for LibSQL client errors and supports transactional execution with proper error propagation.

Example

const result = await AstroDB.execute((client) => client.query('SELECT * FROM users'));

Extends

• any

Constructors

Constructor

new AstroDB(): AstroDB

Returns

AstroDB

Inherited from

Effect.Service<AstroDB>()('studiocms/sdk/effect/db/AstroDB', {
  effect: Effect.gen(function () {
    const db = client;

    /
      Executes a provided asynchronous function with a database client, handling errors using a custom matcher.

      @template T The return type of the asynchronous function.
      @param fn - A function that receives a Client instance and returns a Promise<T>.
      @returns An Effect that resolves with the result of the function or a matched error.

      If the function throws an error, it attempts to match the error using LibSQLmatchClientError.
      If a match is found, the matched error is returned; otherwise, the original error is rethrown.
     /
    const execute = Effect.fn(<T>(fn: (client: Client) => Promise<T>) =>
      Effect.tryPromise({
        try: () => fn(db),
        catch: (cause) => {
          const error = LibSQLmatchClientError(cause);
          if (error !== null) {
            return error;
          }
          throw cause;
        },
      })
    );

    /
      Creates a query function that executes within an optional transaction context.

      @template A - The type of the result produced by the query function.
      @template E - The type of error that may be thrown by the query function.
      @template R - The type of environment required by the query function.
      @template Input - The type of input accepted by the query function (defaults to never).

      @param queryFn - A function that takes an ExecuteFn and an input, returning an Effect.Effect.
                       The ExecuteFn is either the current transaction context or a default executor.

      @returns A function that accepts an input (if required) and returns an Effect.Effect representing the query.
               If a transaction context is available, it is used; otherwise, the default executor is used.
     /
    const makeQuery =
      <A, E, R, Input = never>(
        queryFn: (execute: ExecuteFn, input: Input) => Effect.Effect<A, E, R>
      ) =>
      (...args: [Input] extends [never] ? [] : [input: Input]): Effect.Effect<A, E, R> => {
        const input = args[0] as Input;
        return Effect.serviceOption(TransactionContext).pipe(
          Effect.map(Option.getOrNull),
          Effect.flatMap((txOrNull) => queryFn(txOrNull ?? execute, input))
        );
      };

    /
      Creates an Effect-based transaction wrapper for database operations.

      This function provides a transactional context for executing effects against a database,
      ensuring that all operations within the transaction are either committed or rolled back atomically.
      It handles error mapping using LibSQLmatchClientError and propagates errors through the Effect system.

      @template T - The type of the successful result.
      @template E - The type of the error that may be thrown.
      @template R - The environment required by the effect.
      @param txExecute - A function that receives a transaction context and returns an Effect to be executed within the transaction.
      @returns An Effect that executes the provided effect within a database transaction, handling commit/rollback and error propagation.
     /
    const transaction = Effect.fn('studiocms/sdk/effect/db/Database.transaction')(
      <T, E, R>(txExecute: (tx: TransactionContextShape) => Effect.Effect<T, E, R>) =>
        Effect.runtime<R>().pipe(
          Effect.map((runtime) => Runtime.runPromiseExit(runtime)),
          Effect.flatMap((runPromiseExit) =>
            Effect.async<T, LibSQLDatabaseError | E, R>((resume) => {
              db.transaction(async (tx: TransactionClient) => {
                // biome-ignore lint/suspicious/noExplicitAny: This is a valid use case for explicit any.
                const txWrapper = (fn: (client: TransactionClient) => Promise<any>) =>
                  Effect.tryPromise({
                    try: () => fn(tx),
                    catch: (cause) => {
                      const error = LibSQLmatchClientError(cause);
                      if (error !== null) {
                        return error;
                      }
                      throw cause;
                    },
                  });

                const result = await runPromiseExit(txExecute(txWrapper));
                Exit.match(result, {
                  onSuccess: (value) => {
                    resume(Effect.succeed(value));
                  },
                  onFailure: (cause) => {
                    if (Cause.isFailure(cause)) {
                      resume(Effect.fail(Cause.originalError(cause) as E));
                    } else {
                      resume(Effect.die(cause));
                    }
                  },
                });
              }).catch((cause) => {
                const error = LibSQLmatchClientError(cause);
                resume(error !== null ? Effect.fail(error) : Effect.die(cause));
              });
            })
          )
        )
    );

    return {
      db,
      execute,
      makeQuery,
      transaction,
    };
  }),
}).constructor

---

LibSQLDatabaseError

Defined in: studiocms/packages/studiocms/src/sdk/effect/db.ts:22^

Represents an error thrown by the LibSQL database integration.

This error class is tagged for identification and provides a set of error types that describe various failure scenarios encountered when interacting with the database.

Remarks

The error includes a cause property containing the underlying error, and overrides the toString and message properties for improved error reporting.

Type Param

The specific type of database error, such as ‘URL_INVALID’, ‘TRANSACTION_CLOSED’, etc.

Extends

• any

Constructors

Constructor

new LibSQLDatabaseError(): LibSQLDatabaseError

Returns

LibSQLDatabaseError

Inherited from

Data.TaggedError(
  'studiocms/sdk/effect/db/LibSQLDatabaseError'
)<{
  readonly type:
    | 'URL_INVALID'
    | 'URL_PARAM_NOT_SUPPORTED'
    | 'URL_SCHEME_NOT_SUPPORTED'
    | 'TRANSACTION_CLOSED'
    | 'CLIENT_CLOSED'
    | 'ENCRYPTION_KEY_NOT_SUPPORTED'
    | 'SYNC_NOT_SUPPORTED'
    | 'HRANA_PROTO_ERROR'
    | 'HRANA_CLOSED_ERROR'
    | 'HRANA_WEBSOCKET_ERROR'
    | 'SERVER_ERROR'
    | 'PROTOCOL_VERSION_ERROR'
    | 'INTERNAL_ERROR'
    | 'UNKNOWN'
    | 'WEBSOCKETS_NOT_SUPPORTED';
  readonly cause: Error;
}>.constructor

Accessors

message

Get Signature

get message(): any

Defined in: studiocms/packages/studiocms/src/sdk/effect/db.ts:47^

Returns

any

Methods

toString()

toString(): string

Defined in: studiocms/packages/studiocms/src/sdk/effect/db.ts:43^

Returns

string

---

TransactionContext

Defined in: studiocms/packages/studiocms/src/sdk/effect/db.ts:137^

Represents a transaction context for database operations within the Studiocms SDK.

This class extends a tagged context, allowing it to be used as a dependency in effectful computations.

Remarks

The context is tagged with 'studiocms/sdk/effect/db/TransactionContext' for identification.

Template

The type of the transaction context.

Template

The shape of the transaction context.

Example

const transactionContext = new TransactionContext(...);
const effectWithTransaction = TransactionContext.provide(transactionContext)(someEffect);

Extends

• any

Constructors

Constructor

new TransactionContext(): TransactionContext

Returns

TransactionContext

Inherited from

Context.Tag('studiocms/sdk/effect/db/TransactionContext')<
  TransactionContext,
  TransactionContextShape
>().constructor

Methods

provide()

readonly static provide(transaction: TransactionContextShape): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, TransactionContext>>

Defined in: studiocms/packages/studiocms/src/sdk/effect/db.ts:141^

Parameters

transaction

TransactionContextShape

Returns

Function

Type Parameters

A

A

E

E

R

R

Parameters

self

Effect<A, E, R>

Returns

Effect<A, E, Exclude<R, TransactionContext>>

Type Aliases

ExecuteFn()

type ExecuteFn = <T>(fn: (client:
  | Client
| TransactionClient) => Promise<T>) => Effect.Effect<T, LibSQLDatabaseError>;

Defined in: studiocms/packages/studiocms/src/sdk/effect/db.ts:116^

Represents a function that executes a database operation within an effect context.

Type Parameters

T

T

The type of the result returned by the database operation.

Parameters

fn

(client: | Client | TransactionClient) => Promise<T>

A function that receives a database client or transaction client and returns a promise of type T.

Returns

Effect.Effect<T, LibSQLDatabaseError>

An Effect that resolves to the result of type T or fails with a LibSQLDatabaseError.

---

TransactionClient

type TransactionClient = dual<"async", dual, Record<string, never>, dual<Record<string, never>>>;

Defined in: studiocms/packages/studiocms/src/sdk/effect/db.ts:91^

Represents a SQLite transaction client with asynchronous operations.

Template

Specifies that the transaction is asynchronous.

Template

The type representing the result set returned by queries.

Template

never> - The type for the database schema, currently an empty record.

Template

never>> - Extracts tables with relations from the schema.

---

TransactionContextShape()

type TransactionContextShape = <U>(fn: (client: TransactionClient) => Promise<U>) => Effect.Effect<U, LibSQLDatabaseError>;

Defined in: studiocms/packages/studiocms/src/sdk/effect/db.ts:105^

Represents the shape of a transaction context function.

Type Parameters

U

U

The type of the value returned by the transaction.

Parameters

fn

(client: TransactionClient) => Promise<U>

A function that receives a TransactionClient and returns a Promise of type U.

Returns

Effect.Effect<U, LibSQLDatabaseError>

An Effect that resolves to U or fails with a LibSQLDatabaseError.

Functions

LibSQLmatchClientError()

function LibSQLmatchClientError(error: unknown):
  | null
  | LibSQLDatabaseError

Defined in: studiocms/packages/studiocms/src/sdk/effect/db.ts:59^

Matches a given error against known LibSQL client error codes and returns a LibSQLDatabaseError if a match is found. If the error does not match any known codes, returns null.

Parameters

error

unknown

The error object to match against known LibSQL client error codes.

Returns

| null | LibSQLDatabaseError

A LibSQLDatabaseError instance if the error code matches, otherwise null.