@probitas-test/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

npm install @probitas-test/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-test/client-sql";
import type { SqlTransaction, SqlIsolationLevel } from "@probitas-test/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

Links

• GitHub Repository
• Probitas Framework

npm install @probitas-test/client-sql

class ConstraintError extends SqlError

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

class DeadlockError extends SqlError

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

class QuerySyntaxError extends SqlError

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

class SqlConnectionError extends SqlError

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

class SqlError extends ClientError

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

interface SqlErrorOptions extends ErrorOptions

interface SqlQueryOptions extends CommonOptions

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

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

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

interface SqlQueryResultSuccessParams<T = any>

interface SqlTransaction

commit(): Promise<void>

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

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

rollback(): Promise<void>

interface SqlTransactionOptions

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

type SqlFailureError = SqlConnectionError | AbortError | TimeoutError

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

type SqlOperationError = QuerySyntaxError | ConstraintError | DeadlockError | SqlError

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

import { createPostgresClient } from "@probitas-test/client-sql-postgres";

await using client = await createPostgresClient({ url: "postgres://localhost/db" });
const result = await client.query("SELECT * FROM users");
if (result.ok) {
  // TypeScript knows: SqlQueryResultSuccess
  console.log(result.rows[0]);
} else {
  // TypeScript knows: SqlQueryResultError | SqlQueryResultFailure
  console.log(result.error.message);
}

import { createPostgresClient } from "@probitas-test/client-sql-postgres";

await using client = await createPostgresClient({ url: "postgres://localhost/db" });
const result = await client.query("SELECT * FROM users");
if (result.processed) {
  // TypeScript knows: SqlQueryResultSuccess | SqlQueryResultError
  console.log(result.rowCount);
} else {
  // TypeScript knows: SqlQueryResultFailure
  console.log(result.error.message); // Connection error
}