@probitas/client-sql

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.

// Example of SQL error handling (requires database-specific client)
import {
  SqlQueryResult,
  SqlError,
  ConstraintError,
} from "@probitas/client-sql";
import type { SqlTransaction, SqlIsolationLevel } from "@probitas/client-sql";

// Error types are available for use with database-specific clients
const isolationLevel: SqlIsolationLevel = "read_committed";
console.log("Isolation level:", isolationLevel);

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.

Name	Description
`name`	—
`kind`	—
`constraint`	—

Constructor

new ConstraintError(
  message: string,
  constraint: string,
  options?: SqlErrorOptions,
)

Properties

readonlynamestring
readonlykind"constraint"
readonlyconstraintstring

class

#DeadlockError

class DeadlockError extends SqlError

ExtendsSqlError

Error thrown when a deadlock is detected.

Name	Description
`name`	—
`kind`	—

Constructor

new DeadlockError(message: string, options?: SqlErrorOptions)

Properties

readonlynamestring
readonlykind"deadlock"

class

#QuerySyntaxError

class QuerySyntaxError extends SqlError

ExtendsSqlError

Error thrown when a SQL query has syntax errors.

Name	Description
`name`	—
`kind`	—

Constructor

new QuerySyntaxError(message: string, options?: SqlErrorOptions)

Properties

readonlynamestring
readonlykind"query"

class

#SqlConnectionError

class SqlConnectionError extends SqlError

ExtendsSqlError

Error thrown when a connection or network-level error occurs.

This includes:

Connection refused (server not running)
Authentication failure
Connection timeout
Pool exhaustion
TLS handshake failure
DNS resolution failure

Name	Description
`name`	—
`kind`	—

Constructor

new SqlConnectionError(message: string, options?: SqlErrorOptions)

Properties

readonlynamestring
readonlykind"connection"

class

#SqlError

class SqlError extends ClientError

ExtendsClientError

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

Name	Description
`name`	—
`kind`	—
`sqlState`	—

Constructor

new SqlError(message: string, kind: SqlErrorKind, options?: SqlErrorOptions)

Properties

readonlynamestring
readonlykindSqlErrorKind
readonlysqlStatestring | null

Interfaces

interface

#SqlErrorOptions

interface SqlErrorOptions extends ErrorOptions

Options for SqlError constructor.

Name	Description
`sqlState`	SQL State code (e.g., "23505" for unique violation)

Properties

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

interface

#SqlQueryOptions

interface SqlQueryOptions extends CommonOptions

Options for individual SQL queries.

Name	Description
`throwOnError`	Whether to throw an error for query failures.

Properties

readonlythrowOnError?boolean
Whether to throw an error for query failures. When false, failures are returned as SqlQueryResultError or SqlQueryResultFailure.

interface

#SqlQueryResultError

interface SqlQueryResultError<T = any> extends SqlQueryResultBase<T>

SQL query result for query errors (syntax errors, constraint violations, etc.).

Server received and processed the query, but it failed due to a SQL error.

Name	Description
`processed`	Server processed the query.
`ok`	Query failed.
`error`	Error describing the SQL error.
`rows`	Empty rows for failed queries.
`rowCount`	Zero affected rows for failed queries.
`lastInsertId`	No lastInsertId for failed queries.
`warnings`	No warnings for failed queries.

Properties

readonlyprocessedtrue
Server processed the query.
readonlyokfalse
Query failed.
readonlyerrorSqlError
Error describing the SQL error.
readonlyrowsreadonly never[]
Empty rows for failed queries.
readonlyrowCount0
Zero affected rows for failed queries.
readonlylastInsertIdnull
No lastInsertId for failed queries.
readonlywarningsnull
No warnings for failed queries.

interface

#SqlQueryResultFailure

interface SqlQueryResultFailure<T = any> extends SqlQueryResultBase<T>

SQL query result for connection failures (network errors, timeouts, etc.).

Query could not be processed by the server (connection refused, timeout, pool exhausted, authentication failure, etc.).

Name	Description
`processed`	Server did not process the query.
`ok`	Query failed.
`error`	Error describing the failure.
`rows`	No rows (query didn't reach server).
`rowCount`	No row count (query didn't reach server).
`lastInsertId`	No lastInsertId (query didn't reach server).
`warnings`	No warnings (query didn't reach server).

Properties

readonlyprocessedfalse
Server did not process the query.
readonlyokfalse
Query failed.
readonlyerrorSqlFailureError
Error describing the failure.
readonlyrowsnull
No rows (query didn't reach server).
readonlyrowCountnull
No row count (query didn't reach server).
readonlylastInsertIdnull
No lastInsertId (query didn't reach server).
readonlywarningsnull
No warnings (query didn't reach server).

interface

#SqlQueryResultSuccess

interface SqlQueryResultSuccess<T = any> extends SqlQueryResultBase<T>

SQL query result for successful queries.

The query was executed successfully and returned results.

Name	Description
`processed`	Server processed the query.
`ok`	Query succeeded.
`error`	No error for successful queries.
`rows`	Query result rows.
`rowCount`	Number of affected rows.
`lastInsertId`	Last inserted ID (for INSERT statements).
`warnings`	Warning messages from the database.

Properties

readonlyprocessedtrue
Server processed the query.
readonlyoktrue
Query succeeded.
readonlyerrornull
No error for successful queries.
readonlyrowsreadonly T[]
Query result rows.
readonlyrowCountnumber
Number of affected rows.
readonlylastInsertIdbigint | string | null
Last inserted ID (for INSERT statements).
readonlywarningsunknown | null
Warning messages from the database.

interface

#SqlQueryResultSuccessParams

interface SqlQueryResultSuccessParams<T = any>

Parameters for creating a SqlQueryResultSuccess.

Name	Description
`rows`	The result rows
`rowCount`	Number of affected rows (for INSERT/UPDATE/DELETE)
`duration`	Query execution duration in milliseconds
`lastInsertId`	Last inserted ID (for INSERT statements)
`warnings`	Warning messages from the database

Properties

readonlyrowsreadonly T[]
The result rows
readonlyrowCountnumber
Number of affected rows (for INSERT/UPDATE/DELETE)
readonlydurationnumber
Query execution duration in milliseconds
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.

Name	Description
`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[],
  options?: SqlQueryOptions,
): Promise<SqlQueryResult<T>>

Execute a query within the transaction.

Parameters

sqlstring
- SQL query string
params?unknown[]
- Optional query parameters
options?SqlQueryOptions
- Optional query options

queryOne<T = Record<string, any>>(
  sql: string,
  params?: unknown[],
  options?: SqlQueryOptions,
): Promise<T | undefined>

Execute a query and return the first row or undefined.

Parameters

sqlstring
- SQL query string
params?unknown[]
- Optional query parameters
options?SqlQueryOptions
- Optional query options

commit(): Promise<void>

Commit the transaction.

rollback(): Promise<void>

Rollback the transaction.

interface

#SqlTransactionOptions

interface SqlTransactionOptions

Options for starting a transaction.

Name	Description
`isolationLevel`	Isolation level for the transaction

Properties

readonlyisolationLevel?SqlIsolationLevel
Isolation level for the transaction

Types

type

#SqlErrorKind

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

SQL-specific error kinds.

type

#SqlFailureError

type SqlFailureError = SqlConnectionError | AbortError | TimeoutError

Error types that indicate the operation was not processed. These are errors that occur before the query reaches the SQL server.

type

#SqlIsolationLevel

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

Transaction isolation level.

type

#SqlOperationError

type SqlOperationError = QuerySyntaxError | ConstraintError | DeadlockError | SqlError

Error types that indicate an operation was processed by the server. These errors occur after the query reaches the SQL server.

type

#SqlQueryResult

type SqlQueryResult<T = any> = SqlQueryResultSuccess<T> | SqlQueryResultError<T> | SqlQueryResultFailure<T>

SQL query result union type representing all possible result states.

Success: processed: true, ok: true, error: null
Error: processed: true, ok: false, error: SqlError
Failure: processed: false, ok: false, error: SqlConnectionError

Features

Installation

Usage

Database-Specific Packages

Links

Installation

Classes

#ConstraintError

Constructor

Properties

Links

#DeadlockError

Constructor

Properties

Links

#QuerySyntaxError

Constructor

Properties

Links

#SqlConnectionError

Constructor

Properties

Links

#SqlError

Constructor

Properties

Links

Interfaces

#SqlErrorOptions

Properties

#SqlQueryOptions

Properties

Links

#SqlQueryResultError

Properties

Links

#SqlQueryResultFailure

Properties

Links

#SqlQueryResultSuccess

Properties

#SqlQueryResultSuccessParams

Properties

#SqlTransaction

Methods

Parameters

Parameters

Links

#SqlTransactionOptions

Properties

Links

Types

#SqlErrorKind

#SqlFailureError

Links

#SqlIsolationLevel

#SqlOperationError

Links

#SqlQueryResult

Links