GitHub

@probitas/client-sql

v0.2.0 View on JSR

Common SQL types and utilities for Probitas SQL client packages.

This package provides shared types, result classes, and errors used across all SQL-related client packages.

Features

  • Query Results: SqlQueryResult class with row iteration and metadata
  • Transactions: Common transaction interface with isolation levels
  • Error Hierarchy: SQL-specific errors (SqlError, QuerySyntaxError, ConstraintError, DeadlockError)

Installation

deno add jsr:@probitas/client-sql

Usage

This package is typically used as a dependency by database-specific packages. End users should import from the specific database client packages instead.

import {
  SqlQueryResult,
  SqlError,
  ConstraintError,
} from "@probitas/client-sql";
import type { SqlTransaction, SqlIsolationLevel } from "@probitas/client-sql";

// Handle SQL errors
try {
  await client.query("INSERT INTO users (email) VALUES ($1)", ["duplicate@example.com"]);
} catch (error) {
  if (error instanceof ConstraintError) {
    console.log("Constraint violation:", error.constraint);
  }
}

Database-Specific Packages

Package Description
@probitas/client-sql-postgres PostgreSQL client
@probitas/client-sql-mysql MySQL client
@probitas/client-sql-sqlite SQLite client
@probitas/client-sql-duckdb DuckDB client

Installation

deno add jsr:@probitas/client-sql

Classes

class

#ConstraintError

class ConstraintError extends SqlError
ExtendsSqlError

Error thrown when a constraint violation occurs.

NameDescription
name—
kind—
constraint—
Constructor
new ConstraintError(message: string, constraint: string, options?: SqlErrorOptions)
Properties
  • readonlynamestring
  • readonlykind"constraint"
  • readonlyconstraintstring
Links
class

#DeadlockError

class DeadlockError extends SqlError
ExtendsSqlError

Error thrown when a deadlock is detected.

NameDescription
name—
kind—
Constructor
new DeadlockError(message: string, options?: SqlErrorOptions)
Properties
  • readonlynamestring
  • readonlykind"deadlock"
Links
class

#QuerySyntaxError

class QuerySyntaxError extends SqlError
ExtendsSqlError

Error thrown when a SQL query has syntax errors.

NameDescription
name—
kind—
Constructor
new QuerySyntaxError(message: string, options?: SqlErrorOptions)
Properties
  • readonlynamestring
  • readonlykind"query"
Links
class

#SqlError

class SqlError extends ClientError
ExtendsClientError

Base error class for SQL-specific errors. Extends ClientError with SQL-specific properties.

NameDescription
name—
kind—
sqlState—
Constructor
new SqlError(message: string, kind: SqlErrorKind, options?: SqlErrorOptions)
Properties
  • readonlynamestring
  • readonlykindSqlErrorKind
  • readonlysqlState?string
Links
class

#SqlQueryResult

class SqlQueryResult<T = Record<string, any>>

SQL query result with rows, metadata, and transformation methods.

NameDescription
type—
ok—
rows—
rowCount—
duration—
metadata—
map()Map rows to a new type.
as()Create class instances from rows.
Constructor
new SqlQueryResult(init: SqlQueryResultInit<T>)
Properties
Methods
map(): unknown

Map rows to a new type.

as(): unknown

Create class instances from rows.

Links
class

#SqlRows

class SqlRows<T> extends Array<T>
ExtendsArray<T>

Row array with first/last helper methods. Implements ReadonlyArray by extending Array.

NameDescription
first()Get the first row, or undefined if empty.
firstOrThrow()Get the first row, or throw if empty.
last()Get the last row, or undefined if empty.
lastOrThrow()Get the last row, or throw if empty.
Constructor
new SqlRows(items: readonly T[])
Methods
first(): unknown

Get the first row, or undefined if empty.

firstOrThrow(): unknown

Get the first row, or throw if empty.

last(): unknown

Get the last row, or undefined if empty.

lastOrThrow(): unknown

Get the last row, or throw if empty.

Interfaces

interface

#SqlErrorOptions

interface SqlErrorOptions extends ErrorOptions

Options for SqlError constructor.

NameDescription
sqlStateSQL State code (e.g., "23505" for unique violation)
Properties
  • readonlysqlState?string

    SQL State code (e.g., "23505" for unique violation)

interface

#SqlQueryResultInit

interface SqlQueryResultInit<T>

Options for creating a SqlQueryResult.

NameDescription
okWhether the query succeeded
rowsThe result rows
rowCountNumber of affected rows (for INSERT/UPDATE/DELETE)
durationQuery execution duration in milliseconds
metadataAdditional metadata
Properties
  • readonlyokboolean

    Whether the query succeeded

  • readonlyrowsreadonly T[]

    The result rows

  • readonlyrowCountnumber

    Number of affected rows (for INSERT/UPDATE/DELETE)

  • readonlydurationnumber

    Query execution duration in milliseconds

  • readonlymetadataSqlQueryResultMetadata

    Additional metadata

Links
interface

#SqlQueryResultMetadata

interface SqlQueryResultMetadata

Metadata for SQL query results.

NameDescription
lastInsertIdLast inserted ID (for INSERT statements)
warningsWarning messages from the database
Properties
  • readonlylastInsertId?bigint | string

    Last inserted ID (for INSERT statements)

  • readonlywarnings?readonly string[]

    Warning messages from the database

interface

#SqlTransaction

interface SqlTransaction

SQL transaction interface. Implementations should provide actual database-specific transaction handling.

NameDescription
query()Execute a query within the transaction.
queryOne()Execute a query and return the first row or undefined.
commit()Commit the transaction.
rollback()Rollback the transaction.
Methods
query<T = Record<string, any>>(sql: string, params?: unknown[]): Promise<SqlQueryResult<T>>

Execute a query within the transaction.

Parameters
  • sqlstring
    • SQL query string
  • params?unknown[]
    • Optional query parameters
queryOne<T = Record<string, any>>(sql: string, params?: unknown[]): Promise<T | undefined>

Execute a query and return the first row or undefined.

Parameters
  • sqlstring
    • SQL query string
  • params?unknown[]
    • Optional query parameters
commit(): Promise<void>

Commit the transaction.

rollback(): Promise<void>

Rollback the transaction.

Links
interface

#SqlTransactionOptions

interface SqlTransactionOptions

Options for starting a transaction.

NameDescription
isolationLevelIsolation level for the transaction
Properties
Links

Type Aliases

type

#SqlErrorKind

type SqlErrorKind = "query" | "constraint" | "deadlock" | "unknown"

SQL-specific error kinds.

type

#SqlIsolationLevel

type SqlIsolationLevel = "read_uncommitted" | "read_committed" | "repeatable_read" | "serializable"

Transaction isolation level.

Search Documentation