Skip to content

@phonemyatt/squn


@phonemyatt/squn ​

Enumerations ​

ErrorCode ​

Defined in: src/errors/codes.ts:8

Every error code in the library. Grouped by domain, prefixed SQUN_.

Codes are string literals so they survive serialisation (JSON logs, structured error responses) without losing meaning. A const enum is used so TypeScript inlines the values at compile time — no runtime object is emitted.

Enumeration Members ​

ADAPTER_DRIVER_ERROR ​
ts
ADAPTER_DRIVER_ERROR: "SQUN_ADPT_002";

Defined in: src/errors/codes.ts:43

ADAPTER_NOT_SUPPORTED ​
ts
ADAPTER_NOT_SUPPORTED: "SQUN_ADPT_001";

Defined in: src/errors/codes.ts:42

AUTH_INVALID_CREDENTIALS ​
ts
AUTH_INVALID_CREDENTIALS: "SQUN_AUTH_002";

Defined in: src/errors/codes.ts:69

AUTH_MISSING ​
ts
AUTH_MISSING: "SQUN_AUTH_001";

Defined in: src/errors/codes.ts:68

AUTH_PROVIDER_FAILED ​
ts
AUTH_PROVIDER_FAILED: "SQUN_AUTH_005";

Defined in: src/errors/codes.ts:72

AUTH_TOKEN_EXPIRED ​
ts
AUTH_TOKEN_EXPIRED: "SQUN_AUTH_004";

Defined in: src/errors/codes.ts:71

AUTH_UNSUPPORTED_TYPE ​
ts
AUTH_UNSUPPORTED_TYPE: "SQUN_AUTH_003";

Defined in: src/errors/codes.ts:70

CONFIG_ENV_CONFLICT ​
ts
CONFIG_ENV_CONFLICT: "SQUN_CFG_005";

Defined in: src/errors/codes.ts:65

CONFIG_INVALID_VALUE ​
ts
CONFIG_INVALID_VALUE: "SQUN_CFG_002";

Defined in: src/errors/codes.ts:62

CONFIG_MISSING ​
ts
CONFIG_MISSING: "SQUN_CFG_001";

Defined in: src/errors/codes.ts:61

CONFIG_PRODUCTION_GUARD ​
ts
CONFIG_PRODUCTION_GUARD: "SQUN_CFG_003";

Defined in: src/errors/codes.ts:63

CONFIG_URL_MALFORMED ​
ts
CONFIG_URL_MALFORMED: "SQUN_CFG_004";

Defined in: src/errors/codes.ts:64

CONN_FAILOVER_EXHAUSTED ​
ts
CONN_FAILOVER_EXHAUSTED: "SQUN_CONN_004";

Defined in: src/errors/codes.ts:13

CONN_GROUP_NO_WRITE ​
ts
CONN_GROUP_NO_WRITE: "SQUN_CONN_003";

Defined in: src/errors/codes.ts:12

CONN_MULTI_INVALID ​
ts
CONN_MULTI_INVALID: "SQUN_CONN_002";

Defined in: src/errors/codes.ts:11

CONN_TENANT_NOT_FOUND ​
ts
CONN_TENANT_NOT_FOUND: "SQUN_CONN_005";

Defined in: src/errors/codes.ts:14

CONN_UNKNOWN ​
ts
CONN_UNKNOWN: "SQUN_CONN_001";

Defined in: src/errors/codes.ts:10

INJECTION_DETECTED ​
ts
INJECTION_DETECTED: "SQUN_SEC_001";

Defined in: src/errors/codes.ts:52

INTERNAL_ERROR ​
ts
INTERNAL_ERROR: "SQUN_INTERNAL_001";

Defined in: src/errors/codes.ts:75

INVALID_IDENTIFIER ​
ts
INVALID_IDENTIFIER: "SQUN_SEC_002";

Defined in: src/errors/codes.ts:53

MULTI_STATEMENT_BLOCKED ​
ts
MULTI_STATEMENT_BLOCKED: "SQUN_SEC_005";

Defined in: src/errors/codes.ts:56

MULTIPLE_ROWS_FOUND ​
ts
MULTIPLE_ROWS_FOUND: "SQUN_QUERY_004";

Defined in: src/errors/codes.ts:20

NO_ROWS_FOUND ​
ts
NO_ROWS_FOUND: "SQUN_QUERY_003";

Defined in: src/errors/codes.ts:19

NULL_VIOLATION ​
ts
NULL_VIOLATION: "SQUN_MAP_001";

Defined in: src/errors/codes.ts:23

PARAM_EXTRA ​
ts
PARAM_EXTRA: "SQUN_VAL_002";

Defined in: src/errors/codes.ts:29

PARAM_MISSING ​
ts
PARAM_MISSING: "SQUN_VAL_001";

Defined in: src/errors/codes.ts:28

PLACEHOLDER_MISMATCH ​
ts
PLACEHOLDER_MISMATCH: "SQUN_SEC_006";

Defined in: src/errors/codes.ts:57

POOL_QUEUE_FULL ​
ts
POOL_QUEUE_FULL: "SQUN_POOL_002";

Defined in: src/errors/codes.ts:39

QUERY_EXECUTION_FAILED ​
ts
QUERY_EXECUTION_FAILED: "SQUN_QUERY_001";

Defined in: src/errors/codes.ts:17

QUERY_TIMEOUT ​
ts
QUERY_TIMEOUT: "SQUN_QUERY_002";

Defined in: src/errors/codes.ts:18

RAW_SQL_BLOCKED ​
ts
RAW_SQL_BLOCKED: "SQUN_SEC_003";

Defined in: src/errors/codes.ts:54

READONLY_DDL_BLOCKED ​
ts
READONLY_DDL_BLOCKED: "SQUN_READONLY_004";

Defined in: src/errors/codes.ts:49

READONLY_EXECUTE_BLOCKED ​
ts
READONLY_EXECUTE_BLOCKED: "SQUN_READONLY_003";

Defined in: src/errors/codes.ts:48

READONLY_TX_WRITE ​
ts
READONLY_TX_WRITE: "SQUN_READONLY_002";

Defined in: src/errors/codes.ts:47

READONLY_WRITE_BLOCKED ​
ts
READONLY_WRITE_BLOCKED: "SQUN_READONLY_001";

Defined in: src/errors/codes.ts:46

SQL_VALIDATION_FAILED ​
ts
SQL_VALIDATION_FAILED: "SQUN_SEC_004";

Defined in: src/errors/codes.ts:55

TVP_EMPTY ​
ts
TVP_EMPTY: "SQUN_VAL_004";

Defined in: src/errors/codes.ts:31

TVP_SCHEMA_MISMATCH ​
ts
TVP_SCHEMA_MISMATCH: "SQUN_VAL_003";

Defined in: src/errors/codes.ts:30

TX_ALREADY_CLOSED ​
ts
TX_ALREADY_CLOSED: "SQUN_TX_003";

Defined in: src/errors/codes.ts:36

TX_COMMIT_FAILED ​
ts
TX_COMMIT_FAILED: "SQUN_TX_001";

Defined in: src/errors/codes.ts:34

TX_ROLLBACK_FAILED ​
ts
TX_ROLLBACK_FAILED: "SQUN_TX_002";

Defined in: src/errors/codes.ts:35

TYPE_CONVERSION_FAILED ​
ts
TYPE_CONVERSION_FAILED: "SQUN_MAP_003";

Defined in: src/errors/codes.ts:25

UNKNOWN_COLUMN ​
ts
UNKNOWN_COLUMN: "SQUN_MAP_002";

Defined in: src/errors/codes.ts:24

UNRESOLVED_TVP_SENTINEL ​
ts
UNRESOLVED_TVP_SENTINEL: "SQUN_SEC_007";

Defined in: src/errors/codes.ts:58


EventCode ​

Defined in: src/logging/logger.ts:5

Lifecycle event codes — used in debug/info/warn log entries with no associated error.

Enumeration Members ​

CONN_CLOSED ​
ts
CONN_CLOSED: "SQUN_EVT_004";

Defined in: src/logging/logger.ts:9

CONN_OPENED ​
ts
CONN_OPENED: "SQUN_EVT_003";

Defined in: src/logging/logger.ts:8

POOL_ACQUIRED ​
ts
POOL_ACQUIRED: "SQUN_EVT_010";

Defined in: src/logging/logger.ts:15

POOL_RELEASED ​
ts
POOL_RELEASED: "SQUN_EVT_011";

Defined in: src/logging/logger.ts:16

QUERY_END ​
ts
QUERY_END: "SQUN_EVT_002";

Defined in: src/logging/logger.ts:7

QUERY_START ​
ts
QUERY_START: "SQUN_EVT_001";

Defined in: src/logging/logger.ts:6

RAW_SQL_USED ​
ts
RAW_SQL_USED: "SQUN_EVT_009";

Defined in: src/logging/logger.ts:14

SLOW_QUERY ​
ts
SLOW_QUERY: "SQUN_EVT_008";

Defined in: src/logging/logger.ts:13

TVP_MATERIALISED ​
ts
TVP_MATERIALISED: "SQUN_EVT_012";

Defined in: src/logging/logger.ts:17

TX_COMMIT ​
ts
TX_COMMIT: "SQUN_EVT_006";

Defined in: src/logging/logger.ts:11

TX_ROLLBACK ​
ts
TX_ROLLBACK: "SQUN_EVT_007";

Defined in: src/logging/logger.ts:12

TX_START ​
ts
TX_START: "SQUN_EVT_005";

Defined in: src/logging/logger.ts:10


IsolationLevel ​

Defined in: src/transaction/isolation.ts:1

Enumeration Members ​

READ_COMMITTED ​
ts
READ_COMMITTED: "READ COMMITTED";

Defined in: src/transaction/isolation.ts:3

READ_UNCOMMITTED ​
ts
READ_UNCOMMITTED: "READ UNCOMMITTED";

Defined in: src/transaction/isolation.ts:2

REPEATABLE_READ ​
ts
REPEATABLE_READ: "REPEATABLE READ";

Defined in: src/transaction/isolation.ts:4

SERIALIZABLE ​
ts
SERIALIZABLE: "SERIALIZABLE";

Defined in: src/transaction/isolation.ts:5

SNAPSHOT ​
ts
SNAPSHOT: "SNAPSHOT";

Defined in: src/transaction/isolation.ts:6

Classes ​

AdapterError ​

Defined in: src/errors/types.ts:9

Base class for every error thrown by Squn.

Subclasses set a narrower code domain but never override the shape — every SqunError carries a code, structured context, a trace ID for log correlation, a timestamp, and an optional cause (the original driver error).

Extends ​

Constructors ​

Constructor ​
ts
new AdapterError(
   code, 
   message, 
   context, 
   cause?): AdapterError;

Defined in: src/errors/base.ts:18

Parameters ​
ParameterType
codeErrorCode
messagestring
contextErrorContext
cause?unknown
Returns ​

AdapterError

Inherited from ​

SqunError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
cause?readonlyunknownThe cause of the error.SqunError.causesrc/errors/base.ts:16
codereadonlyErrorCode-SqunError.codesrc/errors/base.ts:12
contextreadonlyErrorContext-SqunError.contextsrc/errors/base.ts:13
messagepublicstring-SqunError.messagenode_modules/typescript/lib/lib.es5.d.ts:1077
namepublicstring-SqunError.namenode_modules/typescript/lib/lib.es5.d.ts:1076
stack?publicstring-SqunError.stacknode_modules/typescript/lib/lib.es5.d.ts:1078
timestampreadonlyDate-SqunError.timestampsrc/errors/base.ts:15
traceIdreadonlystring-SqunError.traceIdsrc/errors/base.ts:14
stackTraceLimitstaticnumberThe Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.SqunError.stackTraceLimitnode_modules/@types/node/globals.d.ts:67

Methods ​

toJSON() ​
ts
toJSON(): Record<string, unknown>;

Defined in: src/errors/base.ts:31

Returns ​

Record<string, unknown>

Inherited from ​

SqunError.toJSON

captureStackTrace() ​
Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/bun-types/globals.d.ts:1042

Create .stack property on a target object

Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

isError() ​
Call Signature ​
ts
static isError(error): error is Error;

Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters ​
ParameterType
errorunknown
Returns ​

error is Error

Inherited from ​

SqunError.isError

Call Signature ​
ts
static isError(value): value is Error;

Defined in: node_modules/bun-types/globals.d.ts:1037

Check if a value is an instance of Error

Parameters ​
ParameterTypeDescription
valueunknownThe value to check
Returns ​

value is Error

True if the value is an instance of Error, false otherwise

Inherited from ​

SqunError.isError

prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from ​

SqunError.prepareStackTrace


AtomicNestingError ​

Defined in: src/transaction/atomic.ts:10

AtomicNestingError — a TransactionError with code TX_NESTING_FORBIDDEN.

Extends ​

Constructors ​

Constructor ​
ts
new AtomicNestingError(
   code, 
   message, 
   context, 
   cause?): AtomicNestingError;

Defined in: src/errors/base.ts:18

Parameters ​
ParameterType
codeErrorCode
messagestring
contextErrorContext
cause?unknown
Returns ​

AtomicNestingError

Inherited from ​

TransactionError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
cause?readonlyunknownThe cause of the error.TransactionError.causesrc/errors/base.ts:16
codereadonlyErrorCode-TransactionError.codesrc/errors/base.ts:12
contextreadonlyErrorContext-TransactionError.contextsrc/errors/base.ts:13
messagepublicstring-TransactionError.messagenode_modules/typescript/lib/lib.es5.d.ts:1077
namepublicstring-TransactionError.namenode_modules/typescript/lib/lib.es5.d.ts:1076
stack?publicstring-TransactionError.stacknode_modules/typescript/lib/lib.es5.d.ts:1078
timestampreadonlyDate-TransactionError.timestampsrc/errors/base.ts:15
traceIdreadonlystring-TransactionError.traceIdsrc/errors/base.ts:14
stackTraceLimitstaticnumberThe Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.TransactionError.stackTraceLimitnode_modules/@types/node/globals.d.ts:67

Methods ​

toJSON() ​
ts
toJSON(): Record<string, unknown>;

Defined in: src/errors/base.ts:31

Returns ​

Record<string, unknown>

Inherited from ​

TransactionError.toJSON

captureStackTrace() ​
Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

TransactionError.captureStackTrace

Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/bun-types/globals.d.ts:1042

Create .stack property on a target object

Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

TransactionError.captureStackTrace

isError() ​
Call Signature ​
ts
static isError(error): error is Error;

Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters ​
ParameterType
errorunknown
Returns ​

error is Error

Inherited from ​

TransactionError.isError

Call Signature ​
ts
static isError(value): value is Error;

Defined in: node_modules/bun-types/globals.d.ts:1037

Check if a value is an instance of Error

Parameters ​
ParameterTypeDescription
valueunknownThe value to check
Returns ​

value is Error

True if the value is an instance of Error, false otherwise

Inherited from ​

TransactionError.isError

prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from ​

TransactionError.prepareStackTrace


AuthError ​

Defined in: src/errors/types.ts:13

Base class for every error thrown by Squn.

Subclasses set a narrower code domain but never override the shape — every SqunError carries a code, structured context, a trace ID for log correlation, a timestamp, and an optional cause (the original driver error).

Extends ​

Constructors ​

Constructor ​
ts
new AuthError(
   code, 
   message, 
   context, 
   cause?): AuthError;

Defined in: src/errors/base.ts:18

Parameters ​
ParameterType
codeErrorCode
messagestring
contextErrorContext
cause?unknown
Returns ​

AuthError

Inherited from ​

SqunError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
cause?readonlyunknownThe cause of the error.SqunError.causesrc/errors/base.ts:16
codereadonlyErrorCode-SqunError.codesrc/errors/base.ts:12
contextreadonlyErrorContext-SqunError.contextsrc/errors/base.ts:13
messagepublicstring-SqunError.messagenode_modules/typescript/lib/lib.es5.d.ts:1077
namepublicstring-SqunError.namenode_modules/typescript/lib/lib.es5.d.ts:1076
stack?publicstring-SqunError.stacknode_modules/typescript/lib/lib.es5.d.ts:1078
timestampreadonlyDate-SqunError.timestampsrc/errors/base.ts:15
traceIdreadonlystring-SqunError.traceIdsrc/errors/base.ts:14
stackTraceLimitstaticnumberThe Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.SqunError.stackTraceLimitnode_modules/@types/node/globals.d.ts:67

Methods ​

toJSON() ​
ts
toJSON(): Record<string, unknown>;

Defined in: src/errors/base.ts:31

Returns ​

Record<string, unknown>

Inherited from ​

SqunError.toJSON

captureStackTrace() ​
Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/bun-types/globals.d.ts:1042

Create .stack property on a target object

Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

isError() ​
Call Signature ​
ts
static isError(error): error is Error;

Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters ​
ParameterType
errorunknown
Returns ​

error is Error

Inherited from ​

SqunError.isError

Call Signature ​
ts
static isError(value): value is Error;

Defined in: node_modules/bun-types/globals.d.ts:1037

Check if a value is an instance of Error

Parameters ​
ParameterTypeDescription
valueunknownThe value to check
Returns ​

value is Error

True if the value is an instance of Error, false otherwise

Inherited from ​

SqunError.isError

prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from ​

SqunError.prepareStackTrace


CachedDb ​

Defined in: src/cache/cached-db.ts:65

An IDbAdapter wrapper that caches the results of query() calls for the configured TTL. All other adapter methods are delegated to the underlying adapter without modification.

Obtain an instance via createCachedDb.

Implements ​

Properties ​

PropertyModifierTypeDefined in
typereadonlyAdapterTypesrc/cache/cached-db.ts:66

Methods ​

beginTransaction() ​
ts
beginTransaction(): Promise<IDbTransaction>;

Defined in: src/cache/cached-db.ts:133

Returns ​

Promise<IDbTransaction>

Implementation of ​

IDbAdapter.beginTransaction

close() ​
ts
close(): Promise<void>;

Defined in: src/cache/cached-db.ts:145

Returns ​

Promise<void>

Implementation of ​

IDbAdapter.close

execute() ​
ts
execute(sql, params): Promise<{
  rowsAffected: number;
}>;

Defined in: src/cache/cached-db.ts:116

Parameters ​
ParameterType
sqlstring
paramsreadonly unknown[]
Returns ​

Promise<{ rowsAffected: number; }>

Implementation of ​

IDbAdapter.execute

executeBatch() ​
ts
executeBatch(
   sql, 
   rows, 
   paramNames, 
   strategy?): Promise<{
  rowsAffected: number;
}>;

Defined in: src/cache/cached-db.ts:124

Executes the same prepared statement once per row using native batch/pipeline. paramNames maps column names to positional params in sql.

Parameters ​
ParameterType
sqlstring
rowsreadonly Record<string, unknown>[]
paramNamesreadonly string[]
strategy?"prepared-loop" | "copy" | "bulk-load"
Returns ​

Promise<{ rowsAffected: number; }>

Implementation of ​

IDbAdapter.executeBatch

hasCursorSupport() ​
ts
hasCursorSupport(): boolean;

Defined in: src/cache/cached-db.ts:137

Returns true if the adapter supports server-side cursors for streaming.

Returns ​

boolean

Implementation of ​

IDbAdapter.hasCursorSupport

invalidate() ​
ts
invalidate(keyOrPattern?): void;

Defined in: src/cache/cached-db.ts:178

Invalidates cache entries.

  • No argument → clears all entries.
  • string → removes the exact entry matching that key.
  • RegExp → removes all entries whose key matches the pattern.
Parameters ​
ParameterType
keyOrPattern?string | RegExp
Returns ​

void

materializeTvp() ​
ts
materializeTvp(tvp, index): Promise<TvpMaterialised>;

Defined in: src/cache/cached-db.ts:149

Parameters ​
ParameterType
tvpTvpValue
indexnumber
Returns ​

Promise<TvpMaterialised>

Implementation of ​

IDbAdapter.materializeTvp

ping() ​
ts
ping(): Promise<void>;

Defined in: src/cache/cached-db.ts:141

Returns ​

Promise<void>

Implementation of ​

IDbAdapter.ping

query() ​
ts
query(sql, params): Promise<Row[]>;

Defined in: src/cache/cached-db.ts:89

Parameters ​
ParameterType
sqlstring
paramsreadonly unknown[]
Returns ​

Promise<Row[]>

Implementation of ​

IDbAdapter.query

queryMultiple() ​
ts
queryMultiple(sql, params): Promise<Row[][]>;

Defined in: src/cache/cached-db.ts:120

Parameters ​
ParameterType
sqlstring
paramsreadonly unknown[]
Returns ​

Promise<Row[][]>

Implementation of ​

IDbAdapter.queryMultiple

stats() ​
ts
stats(): CacheStats;

Defined in: src/cache/cached-db.ts:161

Returns a snapshot of hit/miss counters and the current cache size.

Returns ​

CacheStats


ConnectionError ​

Defined in: src/errors/types.ts:3

Base class for every error thrown by Squn.

Subclasses set a narrower code domain but never override the shape — every SqunError carries a code, structured context, a trace ID for log correlation, a timestamp, and an optional cause (the original driver error).

Extends ​

Constructors ​

Constructor ​
ts
new ConnectionError(
   code, 
   message, 
   context, 
   cause?): ConnectionError;

Defined in: src/errors/base.ts:18

Parameters ​
ParameterType
codeErrorCode
messagestring
contextErrorContext
cause?unknown
Returns ​

ConnectionError

Inherited from ​

SqunError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
cause?readonlyunknownThe cause of the error.SqunError.causesrc/errors/base.ts:16
codereadonlyErrorCode-SqunError.codesrc/errors/base.ts:12
contextreadonlyErrorContext-SqunError.contextsrc/errors/base.ts:13
messagepublicstring-SqunError.messagenode_modules/typescript/lib/lib.es5.d.ts:1077
namepublicstring-SqunError.namenode_modules/typescript/lib/lib.es5.d.ts:1076
stack?publicstring-SqunError.stacknode_modules/typescript/lib/lib.es5.d.ts:1078
timestampreadonlyDate-SqunError.timestampsrc/errors/base.ts:15
traceIdreadonlystring-SqunError.traceIdsrc/errors/base.ts:14
stackTraceLimitstaticnumberThe Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.SqunError.stackTraceLimitnode_modules/@types/node/globals.d.ts:67

Methods ​

toJSON() ​
ts
toJSON(): Record<string, unknown>;

Defined in: src/errors/base.ts:31

Returns ​

Record<string, unknown>

Inherited from ​

SqunError.toJSON

captureStackTrace() ​
Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/bun-types/globals.d.ts:1042

Create .stack property on a target object

Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

isError() ​
Call Signature ​
ts
static isError(error): error is Error;

Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters ​
ParameterType
errorunknown
Returns ​

error is Error

Inherited from ​

SqunError.isError

Call Signature ​
ts
static isError(value): value is Error;

Defined in: node_modules/bun-types/globals.d.ts:1037

Check if a value is an instance of Error

Parameters ​
ParameterTypeDescription
valueunknownThe value to check
Returns ​

value is Error

True if the value is an instance of Error, false otherwise

Inherited from ​

SqunError.isError

prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from ​

SqunError.prepareStackTrace


ConnectionGroup ​

Defined in: src/connections/group.ts:11

Connection group with read/write routing. Reads are load-balanced across replicas. Writes and transactions always go to the write connection.

Type Parameters ​

Type ParameterDefault type
Names extends stringstring

Constructors ​

Constructor ​
ts
new ConnectionGroup<Names>(registry, config): ConnectionGroup<Names>;

Defined in: src/connections/group.ts:17

Parameters ​
ParameterType
registryConnectionRegistry<Names>
configGroupConfig
Returns ​

ConnectionGroup<Names>

Methods ​

getRead() ​
ts
getRead(): IDbAdapter;

Defined in: src/connections/group.ts:32

Returns a read adapter based on the configured readMode.

Returns ​

IDbAdapter

getWrite() ​
ts
getWrite(): IDbAdapter;

Defined in: src/connections/group.ts:27

Returns the write adapter. Transactions always use this.

Returns ​

IDbAdapter


ConnectionPool ​

Defined in: src/pool/pool.ts:33

Connection pool for MSSQL. Bun.SQL (PG/MySQL) manages its own pool internally.

Constructors ​

Constructor ​
ts
new ConnectionPool(config?): ConnectionPool;

Defined in: src/pool/pool.ts:46

Parameters ​
ParameterType
configPoolConfig
Returns ​

ConnectionPool

Methods ​

acquire() ​
ts
acquire(): Promise<PooledConnection>;

Defined in: src/pool/pool.ts:70

Acquires a connection from the pool.

Returns ​

Promise<PooledConnection>

drain() ​
ts
drain(options?): Promise<void>;

Defined in: src/pool/pool.ts:160

Gracefully drains the pool — stops new acquires, waits for in-flight, closes all.

Parameters ​
ParameterType
options?{ timeoutMs?: number; }
options.timeoutMs?number
Returns ​

Promise<void>

poolStats() ​
ts
poolStats(): PoolStatsSnapshot;

Defined in: src/pool/pool.ts:200

Returns a snapshot of current pool metrics.

Returns ​

PoolStatsSnapshot

release() ​
ts
release(conn): void;

Defined in: src/pool/pool.ts:131

Releases a connection back to the pool.

Parameters ​
ParameterType
connPooledConnection
Returns ​

void


ConnectionRegistry ​

Defined in: src/connections/registry.ts:8

Holds all named Database instances. get() throws CONN_UNKNOWN if name not found.

Type Parameters ​

Type ParameterDefault type
Names extends stringstring

Constructors ​

Constructor ​
ts
new ConnectionRegistry<Names>(connections, defaultName): ConnectionRegistry<Names>;

Defined in: src/connections/registry.ts:12

Parameters ​
ParameterType
connectionsRecord<Names, IDbAdapter>
defaultNameNames
Returns ​

ConnectionRegistry<Names>

Accessors ​

default ​
Get Signature ​
ts
get default(): Names;

Defined in: src/connections/registry.ts:79

Returns ​

Names

Methods ​

get() ​
ts
get(name?): IDbAdapter;

Defined in: src/connections/registry.ts:29

Parameters ​
ParameterType
name?Names
Returns ​

IDbAdapter

has() ​
ts
has(name): boolean;

Defined in: src/connections/registry.ts:50

Parameters ​
ParameterType
namestring
Returns ​

boolean

names() ​
ts
names(): string[];

Defined in: src/connections/registry.ts:46

Returns ​

string[]

ping() ​
ts
ping(name): Promise<void>;

Defined in: src/connections/registry.ts:54

Parameters ​
ParameterType
nameNames
Returns ​

Promise<void>

pingAll() ​
ts
pingAll(): Promise<void>;

Defined in: src/connections/registry.ts:59

Returns ​

Promise<void>


Cursor ​

Defined in: src/async/cursor.ts:12

AsyncIterableIterator<T> backed by either a native server cursor (when adapter.hasCursorSupport() is true, future work) or a full-fetch-then-slice fallback for all current adapters.

Consumers MUST call close() in a finally block to release resources.

Type Parameters ​

Type Parameter
T

Implements ​

  • AsyncIterableIterator<T>

Constructors ​

Constructor ​
ts
new Cursor<T>(
   adapter, 
   fragment, 
_batchSize): Cursor<T>;

Defined in: src/async/cursor.ts:22

Parameters ​
ParameterType
adapterIDbAdapter
fragmentSqlFragment
_batchSizenumber
Returns ​

Cursor<T>

Methods ​

[asyncDispose]() ​
ts
asyncDispose: Promise<void>;

Defined in: src/async/cursor.ts:56

Returns ​

Promise<void>

[asyncIterator]() ​
ts
asyncIterator: AsyncIterableIterator<T>;

Defined in: src/async/cursor.ts:60

Returns ​

AsyncIterableIterator<T>

Implementation of ​
ts
AsyncIterableIterator.[asyncIterator]
close() ​
ts
close(): Promise<void>;

Defined in: src/async/cursor.ts:51

Returns ​

Promise<void>

next() ​
ts
next(): Promise<IteratorResult<T, any>>;

Defined in: src/async/cursor.ts:27

Returns ​

Promise<IteratorResult<T, any>>

Implementation of ​
ts
AsyncIterableIterator.next

FailoverGroup ​

Defined in: src/connections/failover.ts:17

Failover group. When primary is unreachable, promotes first healthy standby.

Important caveats:

  • In-flight transactions are lost on failover — they cannot be replayed.
  • Replication lag creates a data loss window — reads from the new primary may return stale data until the standby catches up.
  • Split-brain is not automatically prevented — if the original primary recovers while a standby has been promoted, both may accept writes. Use external fencing (e.g. pg_rewind, STONITH) to prevent this.

Type Parameters ​

Type ParameterDefault type
Names extends stringstring

Constructors ​

Constructor ​
ts
new FailoverGroup<Names>(
   registry, 
   primaryName, 
standbyNames): FailoverGroup<Names>;

Defined in: src/connections/failover.ts:22

Parameters ​
ParameterType
registryConnectionRegistry<Names>
primaryNameNames
standbyNamesreadonly Names[]
Returns ​

FailoverGroup<Names>

Accessors ​

active ​
Get Signature ​
ts
get active(): Names;

Defined in: src/connections/failover.ts:62

Returns ​

Names

isOnPrimary ​
Get Signature ​
ts
get isOnPrimary(): boolean;

Defined in: src/connections/failover.ts:58

Whether the active connection is still the original primary.

Returns ​

boolean

Methods ​

failover() ​
ts
failover(): Promise<Names>;

Defined in: src/connections/failover.ts:38

Attempts to promote the first healthy standby. Throws if all unreachable.

Returns ​

Promise<Names>

getActive() ​
ts
getActive(): IDbAdapter;

Defined in: src/connections/failover.ts:33

Returns the currently active adapter (primary or promoted standby).

Returns ​

IDbAdapter


MapperRegistry ​

Defined in: src/mapping/mapper-registry.ts:9

Class → mapper registry. Instantiate your own for isolated test environments.

Constructors ​

Constructor ​
ts
new MapperRegistry(): MapperRegistry;
Returns ​

MapperRegistry

Methods ​

clear() ​
ts
clear(): void;

Defined in: src/mapping/mapper-registry.ts:24

Returns ​

void

get() ​
ts
get<T>(cls): MapperFn<T> | undefined;

Defined in: src/mapping/mapper-registry.ts:16

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
clsConstructor<T>
Returns ​

MapperFn<T> | undefined

has() ​
ts
has(cls): boolean;

Defined in: src/mapping/mapper-registry.ts:20

Parameters ​
ParameterType
clsConstructor<unknown>
Returns ​

boolean

register() ​
ts
register<T>(cls, mapper): void;

Defined in: src/mapping/mapper-registry.ts:12

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
clsConstructor<T>
mapperMapperFn<T>
Returns ​

void


MappingError ​

Defined in: src/errors/types.ts:5

Base class for every error thrown by Squn.

Subclasses set a narrower code domain but never override the shape — every SqunError carries a code, structured context, a trace ID for log correlation, a timestamp, and an optional cause (the original driver error).

Extends ​

Constructors ​

Constructor ​
ts
new MappingError(
   code, 
   message, 
   context, 
   cause?): MappingError;

Defined in: src/errors/base.ts:18

Parameters ​
ParameterType
codeErrorCode
messagestring
contextErrorContext
cause?unknown
Returns ​

MappingError

Inherited from ​

SqunError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
cause?readonlyunknownThe cause of the error.SqunError.causesrc/errors/base.ts:16
codereadonlyErrorCode-SqunError.codesrc/errors/base.ts:12
contextreadonlyErrorContext-SqunError.contextsrc/errors/base.ts:13
messagepublicstring-SqunError.messagenode_modules/typescript/lib/lib.es5.d.ts:1077
namepublicstring-SqunError.namenode_modules/typescript/lib/lib.es5.d.ts:1076
stack?publicstring-SqunError.stacknode_modules/typescript/lib/lib.es5.d.ts:1078
timestampreadonlyDate-SqunError.timestampsrc/errors/base.ts:15
traceIdreadonlystring-SqunError.traceIdsrc/errors/base.ts:14
stackTraceLimitstaticnumberThe Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.SqunError.stackTraceLimitnode_modules/@types/node/globals.d.ts:67

Methods ​

toJSON() ​
ts
toJSON(): Record<string, unknown>;

Defined in: src/errors/base.ts:31

Returns ​

Record<string, unknown>

Inherited from ​

SqunError.toJSON

captureStackTrace() ​
Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/bun-types/globals.d.ts:1042

Create .stack property on a target object

Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

isError() ​
Call Signature ​
ts
static isError(error): error is Error;

Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters ​
ParameterType
errorunknown
Returns ​

error is Error

Inherited from ​

SqunError.isError

Call Signature ​
ts
static isError(value): value is Error;

Defined in: node_modules/bun-types/globals.d.ts:1037

Check if a value is an instance of Error

Parameters ​
ParameterTypeDescription
valueunknownThe value to check
Returns ​

value is Error

True if the value is an instance of Error, false otherwise

Inherited from ​

SqunError.isError

prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from ​

SqunError.prepareStackTrace


MssqlAdapter ​

Defined in: src/adapters/mssql.ts:87

Database adapter contract — all database-specific behaviour lives here.

Implements ​

Constructors ​

Constructor ​
ts
new MssqlAdapter(options): MssqlAdapter;

Defined in: src/adapters/mssql.ts:92

Parameters ​
ParameterType
optionsMssqlAdapterOptions
Returns ​

MssqlAdapter

Properties ​

PropertyModifierTypeDefined in
typereadonly"mssql"src/adapters/mssql.ts:88

Methods ​

beginTransaction() ​
ts
beginTransaction(): Promise<IDbTransaction>;

Defined in: src/adapters/mssql.ts:169

Returns ​

Promise<IDbTransaction>

Implementation of ​

IDbAdapter.beginTransaction

close() ​
ts
close(): Promise<void>;

Defined in: src/adapters/mssql.ts:328

Returns ​

Promise<void>

Implementation of ​

IDbAdapter.close

execute() ​
ts
execute(sql, params): Promise<{
  rowsAffected: number;
}>;

Defined in: src/adapters/mssql.ts:117

Parameters ​
ParameterType
sqlstring
paramsunknown[]
Returns ​

Promise<{ rowsAffected: number; }>

Implementation of ​

IDbAdapter.execute

executeBatch() ​
ts
executeBatch(
   sql, 
   rows, 
   paramNames, 
   strategy?): Promise<{
  rowsAffected: number;
}>;

Defined in: src/adapters/mssql.ts:273

Executes the same prepared statement once per row using native batch/pipeline. paramNames maps column names to positional params in sql.

Parameters ​
ParameterType
sqlstring
rowsreadonly Record<string, unknown>[]
paramNamesreadonly string[]
strategy?"prepared-loop" | "copy" | "bulk-load"
Returns ​

Promise<{ rowsAffected: number; }>

Implementation of ​

IDbAdapter.executeBatch

hasCursorSupport() ​
ts
hasCursorSupport(): boolean;

Defined in: src/adapters/mssql.ts:310

Returns true if the adapter supports server-side cursors for streaming.

Returns ​

boolean

Implementation of ​

IDbAdapter.hasCursorSupport

materializeTvp() ​
ts
materializeTvp(_tvp, _index): Promise<TvpMaterialised>;

Defined in: src/adapters/mssql.ts:344

Parameters ​
ParameterType
_tvpTvpValue
_indexnumber
Returns ​

Promise<TvpMaterialised>

Implementation of ​

IDbAdapter.materializeTvp

ping() ​
ts
ping(): Promise<void>;

Defined in: src/adapters/mssql.ts:314

Returns ​

Promise<void>

Implementation of ​

IDbAdapter.ping

query() ​
ts
query(sql, params): Promise<Row[]>;

Defined in: src/adapters/mssql.ts:135

Parameters ​
ParameterType
sqlstring
paramsunknown[]
Returns ​

Promise<Row[]>

Implementation of ​

IDbAdapter.query

queryMultiple() ​
ts
queryMultiple(sql, params): Promise<Row[][]>;

Defined in: src/adapters/mssql.ts:152

Parameters ​
ParameterType
sqlstring
paramsunknown[]
Returns ​

Promise<Row[][]>

Implementation of ​

IDbAdapter.queryMultiple


MysqlAdapter ​

Defined in: src/adapters/mysql.ts:48

Database adapter contract — all database-specific behaviour lives here.

Implements ​

Constructors ​

Constructor ​
ts
new MysqlAdapter(options?): MysqlAdapter;

Defined in: src/adapters/mysql.ts:52

Parameters ​
ParameterType
optionsMysqlAdapterOptions
Returns ​

MysqlAdapter

Properties ​

PropertyModifierTypeDefined in
typereadonly"mysql"src/adapters/mysql.ts:49

Methods ​

beginTransaction() ​
ts
beginTransaction(): Promise<IDbTransaction>;

Defined in: src/adapters/mysql.ts:106

Returns ​

Promise<IDbTransaction>

Implementation of ​

IDbAdapter.beginTransaction

close() ​
ts
close(): Promise<void>;

Defined in: src/adapters/mysql.ts:257

Returns ​

Promise<void>

Implementation of ​

IDbAdapter.close

execute() ​
ts
execute(sql, params): Promise<{
  rowsAffected: number;
}>;

Defined in: src/adapters/mysql.ts:69

Parameters ​
ParameterType
sqlstring
paramsreadonly unknown[]
Returns ​

Promise<{ rowsAffected: number; }>

Implementation of ​

IDbAdapter.execute

executeBatch() ​
ts
executeBatch(
   sql, 
   rows, 
   paramNames, 
   _strategy?): Promise<{
  rowsAffected: number;
}>;

Defined in: src/adapters/mysql.ts:216

Executes the same prepared statement once per row using native batch/pipeline. paramNames maps column names to positional params in sql.

Parameters ​
ParameterType
sqlstring
rowsreadonly Record<string, unknown>[]
paramNamesreadonly string[]
_strategy?"prepared-loop" | "copy" | "bulk-load"
Returns ​

Promise<{ rowsAffected: number; }>

Implementation of ​

IDbAdapter.executeBatch

hasCursorSupport() ​
ts
hasCursorSupport(): boolean;

Defined in: src/adapters/mysql.ts:240

Returns true if the adapter supports server-side cursors for streaming.

Returns ​

boolean

Implementation of ​

IDbAdapter.hasCursorSupport

materializeTvp() ​
ts
materializeTvp(_tvp, _index): Promise<TvpMaterialised>;

Defined in: src/adapters/mysql.ts:270

Parameters ​
ParameterType
_tvpTvpValue
_indexnumber
Returns ​

Promise<TvpMaterialised>

Implementation of ​

IDbAdapter.materializeTvp

ping() ​
ts
ping(): Promise<void>;

Defined in: src/adapters/mysql.ts:244

Returns ​

Promise<void>

Implementation of ​

IDbAdapter.ping

query() ​
ts
query(sql, params): Promise<Row[]>;

Defined in: src/adapters/mysql.ts:87

Parameters ​
ParameterType
sqlstring
paramsreadonly unknown[]
Returns ​

Promise<Row[]>

Implementation of ​

IDbAdapter.query

queryMultiple() ​
ts
queryMultiple(sql, params): Promise<Row[][]>;

Defined in: src/adapters/mysql.ts:101

Parameters ​
ParameterType
sqlstring
paramsreadonly unknown[]
Returns ​

Promise<Row[][]>

Implementation of ​

IDbAdapter.queryMultiple


ParamBuffer ​

Defined in: src/cache/param-buffer.ts:8

Pre-allocated reusable array for param binding. Fills values in-place — no new Array() per query call. Grows automatically when the param count exceeds current capacity.

Constructors ​

Constructor ​
ts
new ParamBuffer(initialCapacity?): ParamBuffer;

Defined in: src/cache/param-buffer.ts:12

Parameters ​
ParameterTypeDefault value
initialCapacitynumberDEFAULT_CAPACITY
Returns ​

ParamBuffer

Accessors ​

capacity ​
Get Signature ​
ts
get capacity(): number;

Defined in: src/cache/param-buffer.ts:48

Current allocated capacity.

Returns ​

number

length ​
Get Signature ​
ts
get length(): number;

Defined in: src/cache/param-buffer.ts:43

Current number of values in the buffer.

Returns ​

number

Methods ​

push() ​
ts
push(value): number;

Defined in: src/cache/param-buffer.ts:27

Appends a value and returns its index. Grows the buffer if needed.

Parameters ​
ParameterType
valueunknown
Returns ​

number

reset() ​
ts
reset(): void;

Defined in: src/cache/param-buffer.ts:18

Resets the buffer for a new query without re-allocating.

Returns ​

void

toArray() ​
ts
toArray(): readonly unknown[];

Defined in: src/cache/param-buffer.ts:38

Returns a view of the filled portion. The returned array is reused — do not hold a reference.

Returns ​

readonly unknown[]


PooledConnection ​

Defined in: src/pool/connection.ts:7

Wraps a single database connection with lifecycle state tracking. State machine: CREATED → IDLE → ACQUIRED → IDLE → … → DEAD

Constructors ​

Constructor ​
ts
new PooledConnection(id): PooledConnection;

Defined in: src/pool/connection.ts:16

Parameters ​
ParameterType
idstring
Returns ​

PooledConnection

Properties ​

PropertyModifierTypeDefined in
idreadonlystringsrc/pool/connection.ts:14

Accessors ​

acquiredAt ​
Get Signature ​
ts
get acquiredAt(): number | null;

Defined in: src/pool/connection.ts:38

Returns ​

number | null

ageMs ​
Get Signature ​
ts
get ageMs(): number;

Defined in: src/pool/connection.ts:73

Age in milliseconds since creation.

Returns ​

number

createdAt ​
Get Signature ​
ts
get createdAt(): number;

Defined in: src/pool/connection.ts:30

Returns ​

number

idleMs ​
Get Signature ​
ts
get idleMs(): number;

Defined in: src/pool/connection.ts:78

Time in milliseconds since last acquired (or since creation if never acquired).

Returns ​

number

lastUsedAt ​
Get Signature ​
ts
get lastUsedAt(): number;

Defined in: src/pool/connection.ts:34

Returns ​

number

state ​
Get Signature ​
ts
get state(): ConnectionState;

Defined in: src/pool/connection.ts:22

Returns ​

ConnectionState

useCount ​
Get Signature ​
ts
get useCount(): number;

Defined in: src/pool/connection.ts:26

Returns ​

number

Methods ​

markAcquired() ​
ts
markAcquired(): void;

Defined in: src/pool/connection.ts:49

Transition to ACQUIRED — valid from IDLE.

Returns ​

void

markDead() ​
ts
markDead(): void;

Defined in: src/pool/connection.ts:57

Transition to DEAD — valid from any state.

Returns ​

void

markIdle() ​
ts
markIdle(): void;

Defined in: src/pool/connection.ts:43

Transition to IDLE — valid from CREATED or ACQUIRED.

Returns ​

void

shouldRecycle() ​
ts
shouldRecycle(maxAgeMs, maxUseCount): boolean;

Defined in: src/pool/connection.ts:62

Whether this connection should be recycled based on age or use count.

Parameters ​
ParameterType
maxAgeMsnumber | undefined
maxUseCountnumber | undefined
Returns ​

boolean


PoolStats ​

Defined in: src/pool/stats.ts:21

Tracks rolling averages for pool performance metrics. Uses exponential moving average for constant memory usage.

Constructors ​

Constructor ​
ts
new PoolStats(alpha?): PoolStats;

Defined in: src/pool/stats.ts:30

Parameters ​
ParameterTypeDefault value
alphanumber0.1
Returns ​

PoolStats

Methods ​

recordAcquire() ​
ts
recordAcquire(durationMs): void;

Defined in: src/pool/stats.ts:34

Parameters ​
ParameterType
durationMsnumber
Returns ​

void

recordCreated() ​
ts
recordCreated(): void;

Defined in: src/pool/stats.ts:47

Returns ​

void

recordDestroyed() ​
ts
recordDestroyed(): void;

Defined in: src/pool/stats.ts:51

Returns ​

void

recordIdle() ​
ts
recordIdle(durationMs): void;

Defined in: src/pool/stats.ts:39

Parameters ​
ParameterType
durationMsnumber
Returns ​

void

recordUse() ​
ts
recordUse(durationMs): void;

Defined in: src/pool/stats.ts:43

Parameters ​
ParameterType
durationMsnumber
Returns ​

void

snapshot() ​
ts
snapshot(
   idle, 
   acquired, 
   waiting, 
   min, 
   max): PoolStatsSnapshot;

Defined in: src/pool/stats.ts:55

Parameters ​
ParameterType
idlenumber
acquirednumber
waitingnumber
minnumber
maxnumber
Returns ​

PoolStatsSnapshot


PostgresAdapter ​

Defined in: src/adapters/postgres.ts:18

Database adapter contract — all database-specific behaviour lives here.

Implements ​

Constructors ​

Constructor ​
ts
new PostgresAdapter(options?): PostgresAdapter;

Defined in: src/adapters/postgres.ts:23

Parameters ​
ParameterType
optionsPostgresAdapterOptions
Returns ​

PostgresAdapter

Properties ​

PropertyModifierTypeDefined in
tvpCopyThresholdreadonlynumbersrc/adapters/postgres.ts:21
typereadonly"postgres"src/adapters/postgres.ts:19

Methods ​

beginTransaction() ​
ts
beginTransaction(): Promise<IDbTransaction>;

Defined in: src/adapters/postgres.ts:93

Uses Bun.SQL's sql.reserve() to pin a single connection from the pool. Raw BEGIN/COMMIT via unsafe() is rejected by Bun when pool max > 1 because queries could land on different connections.

The reserved connection is released when commit() or rollback() is called.

Returns ​

Promise<IDbTransaction>

Implementation of ​

IDbAdapter.beginTransaction

close() ​
ts
close(): Promise<void>;

Defined in: src/adapters/postgres.ts:254

Returns ​

Promise<void>

Implementation of ​

IDbAdapter.close

execute() ​
ts
execute(sql, params): Promise<{
  rowsAffected: number;
}>;

Defined in: src/adapters/postgres.ts:44

Parameters ​
ParameterType
sqlstring
paramsunknown[]
Returns ​

Promise<{ rowsAffected: number; }>

Implementation of ​

IDbAdapter.execute

executeBatch() ​
ts
executeBatch(
   sql, 
   rows, 
   paramNames, 
   _strategy?): Promise<{
  rowsAffected: number;
}>;

Defined in: src/adapters/postgres.ts:213

Executes the same prepared statement once per row using native batch/pipeline. paramNames maps column names to positional params in sql.

Parameters ​
ParameterType
sqlstring
rowsreadonly Record<string, unknown>[]
paramNamesreadonly string[]
_strategy?"prepared-loop" | "copy" | "bulk-load"
Returns ​

Promise<{ rowsAffected: number; }>

Implementation of ​

IDbAdapter.executeBatch

hasCursorSupport() ​
ts
hasCursorSupport(): boolean;

Defined in: src/adapters/postgres.ts:237

Returns true if the adapter supports server-side cursors for streaming.

Returns ​

boolean

Implementation of ​

IDbAdapter.hasCursorSupport

materializeTvp() ​
ts
materializeTvp(_tvp, _index): Promise<TvpMaterialised>;

Defined in: src/adapters/postgres.ts:267

Parameters ​
ParameterType
_tvpTvpValue
_indexnumber
Returns ​

Promise<TvpMaterialised>

Implementation of ​

IDbAdapter.materializeTvp

ping() ​
ts
ping(): Promise<void>;

Defined in: src/adapters/postgres.ts:241

Returns ​

Promise<void>

Implementation of ​

IDbAdapter.ping

query() ​
ts
query(sql, params): Promise<Row[]>;

Defined in: src/adapters/postgres.ts:58

Parameters ​
ParameterType
sqlstring
paramsunknown[]
Returns ​

Promise<Row[]>

Implementation of ​

IDbAdapter.query

queryMultiple() ​
ts
queryMultiple(sql, params): Promise<Row[][]>;

Defined in: src/adapters/postgres.ts:72

Parameters ​
ParameterType
sqlstring
paramsunknown[]
Returns ​

Promise<Row[][]>

Implementation of ​

IDbAdapter.queryMultiple


PreparedQuery ​

Defined in: src/api/prepared.ts:35

A prepared query. The SQL is parsed, validated, and normalised once. Each invocation only fills the ParamBuffer and calls the adapter.

For queries (SELECT): returns T[]. For single-row: use .first() or .single(). For writes: use .execute().

Type Parameters ​

Type ParameterDefault type
T-
P extends Record<string, unknown>Record<string, never>

Constructors ​

Constructor ​
ts
new PreparedQuery<T, P>(
   adapter, 
   fragment, 
paramNames): PreparedQuery<T, P>;

Defined in: src/api/prepared.ts:39

Parameters ​
ParameterType
adapterIDbAdapter
fragmentSqlFragment
paramNamesreadonly string[]
Returns ​

PreparedQuery<T, P>

Accessors ​

paramNames ​
Get Signature ​
ts
get paramNames(): readonly string[];

Defined in: src/api/prepared.ts:135

The ordered param names.

Returns ​

readonly string[]

rawSql ​
Get Signature ​
ts
get rawSql(): string;

Defined in: src/api/prepared.ts:130

The raw SQL text sent to the adapter.

Returns ​

string

sql ​
Get Signature ​
ts
get sql(): string;

Defined in: src/api/prepared.ts:125

The normalised SQL text — useful for logging and debugging.

Returns ​

string

Methods ​

all() ​
ts
all(params): Promise<T[]>;

Defined in: src/api/prepared.ts:63

Execute as a query — returns T[].

Parameters ​
ParameterType
paramsP
Returns ​

Promise<T[]>

execute() ​
ts
execute(params): Promise<{
  rowsAffected: number;
}>;

Defined in: src/api/prepared.ts:119

Execute as a write — returns { rowsAffected }.

Parameters ​
ParameterType
paramsP
Returns ​

Promise<{ rowsAffected: number; }>

first() ​
ts
first(params): Promise<T | null>;

Defined in: src/api/prepared.ts:70

Execute and return T | null — first row or null.

Parameters ​
ParameterType
paramsP
Returns ​

Promise<T | null>

scalar() ​
ts
scalar(params): Promise<T>;

Defined in: src/api/prepared.ts:98

Execute and return the first column of the first row.

Parameters ​
ParameterType
paramsP
Returns ​

Promise<T>

single() ​
ts
single(params): Promise<T>;

Defined in: src/api/prepared.ts:78

Execute and return exactly one T — throws on 0 or >1 rows.

Parameters ​
ParameterType
paramsP
Returns ​

Promise<T>


QueryBuilder ​

Defined in: src/api/query-builder.ts:14

Lazy, immutable, composable query builder. Nothing executes until db.run(q) is called. Each method returns a new builder — never mutates.

Type Parameters ​

Type ParameterDefault type
Names extends stringnever

Constructors ​

Constructor ​
ts
new QueryBuilder<Names>(
   tableName, 
   selectCols?, 
   whereClauses?, 
   orderClauses?, 
   limit?, 
   offset?, 
   connectionName?, 
isReadonly?): QueryBuilder<Names>;

Defined in: src/api/query-builder.ts:24

Parameters ​
ParameterTypeDefault value
tableNamestringundefined
selectColsreadonly string[][]
whereClausesreadonly SqlFragment[][]
orderClausesreadonly string[][]
limitnumber | nullnull
offsetnumber | nullnull
connectionNameNames | nullnull
isReadonlybooleanfalse
Returns ​

QueryBuilder<Names>

Accessors ​

connectionName ​
Get Signature ​
ts
get connectionName(): Names | null;

Defined in: src/api/query-builder.ts:166

Returns ​

Names | null

isReadonly ​
Get Signature ​
ts
get isReadonly(): boolean;

Defined in: src/api/query-builder.ts:170

Returns ​

boolean

tableName ​
Get Signature ​
ts
get tableName(): string;

Defined in: src/api/query-builder.ts:174

Returns ​

string

Methods ​

build() ​
ts
build(): SqlFragment;

Defined in: src/api/query-builder.ts:129

Builds the SqlFragment for execution.

Returns ​

SqlFragment

connection() ​
ts
connection<N>(name): QueryBuilder<N>;

Defined in: src/api/query-builder.ts:102

Type Parameters ​
Type Parameter
N extends string
Parameters ​
ParameterType
nameN
Returns ​

QueryBuilder<N>

orderBy() ​
ts
orderBy(column, direction?): QueryBuilder<Names>;

Defined in: src/api/query-builder.ts:75

Parameters ​
ParameterTypeDefault value
columnstringundefined
direction"ASC" | "DESC""ASC"
Returns ​

QueryBuilder<Names>

paginate() ​
ts
paginate(options): QueryBuilder<Names>;

Defined in: src/api/query-builder.ts:88

Parameters ​
ParameterType
optionsPaginateOptions
Returns ​

QueryBuilder<Names>

readonly() ​
ts
readonly(): QueryBuilder<Names>;

Defined in: src/api/query-builder.ts:115

Returns ​

QueryBuilder<Names>

select() ​
ts
select(...cols): QueryBuilder<Names>;

Defined in: src/api/query-builder.ts:44

Parameters ​
ParameterType
...colsstring[]
Returns ​

QueryBuilder<Names>

where() ​
ts
where(clause): QueryBuilder<Names>;

Defined in: src/api/query-builder.ts:57

Parameters ​
ParameterType
clauseSqlFragment
Returns ​

QueryBuilder<Names>

whereIf() ​
ts
whereIf(condition, clause): QueryBuilder<Names>;

Defined in: src/api/query-builder.ts:70

Parameters ​
ParameterType
conditionboolean
clauseSqlFragment
Returns ​

QueryBuilder<Names>


QueryCache ​

Defined in: src/cache/query-cache.ts:20

LRU query cache keyed on Bun.hash() of normalised SQL text. Entries are held via WeakRef so the GC can reclaim them under memory pressure. Supports TTL, max-age, LRU eviction, and a background reaper.

Constructors ​

Constructor ​
ts
new QueryCache(config?): QueryCache;

Defined in: src/cache/query-cache.ts:27

Parameters ​
ParameterType
configCacheConfig
Returns ​

QueryCache

Accessors ​

size ​
Get Signature ​
ts
get size(): number;

Defined in: src/cache/query-cache.ts:107

Current number of entries (including potentially GC'd WeakRefs).

Returns ​

number

Methods ​

clear() ​
ts
clear(): void;

Defined in: src/cache/query-cache.ts:112

Removes all entries and stops the background reaper.

Returns ​

void

get() ​
ts
get(sql): CompiledQuery | undefined;

Defined in: src/cache/query-cache.ts:43

Returns the cached CompiledQuery or undefined on miss / expiry / GC reclaim.

Parameters ​
ParameterType
sqlstring
Returns ​

CompiledQuery | undefined

set() ​
ts
set(sql, compiled): void;

Defined in: src/cache/query-cache.ts:80

Stores a CompiledQuery. Evicts the LRU entry if the cache is full.

Parameters ​
ParameterType
sqlstring
compiledCompiledQuery
Returns ​

void


QueryError ​

Defined in: src/errors/types.ts:4

Base class for every error thrown by Squn.

Subclasses set a narrower code domain but never override the shape — every SqunError carries a code, structured context, a trace ID for log correlation, a timestamp, and an optional cause (the original driver error).

Extends ​

Constructors ​

Constructor ​
ts
new QueryError(
   code, 
   message, 
   context, 
   cause?): QueryError;

Defined in: src/errors/base.ts:18

Parameters ​
ParameterType
codeErrorCode
messagestring
contextErrorContext
cause?unknown
Returns ​

QueryError

Inherited from ​

SqunError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
cause?readonlyunknownThe cause of the error.SqunError.causesrc/errors/base.ts:16
codereadonlyErrorCode-SqunError.codesrc/errors/base.ts:12
contextreadonlyErrorContext-SqunError.contextsrc/errors/base.ts:13
messagepublicstring-SqunError.messagenode_modules/typescript/lib/lib.es5.d.ts:1077
namepublicstring-SqunError.namenode_modules/typescript/lib/lib.es5.d.ts:1076
stack?publicstring-SqunError.stacknode_modules/typescript/lib/lib.es5.d.ts:1078
timestampreadonlyDate-SqunError.timestampsrc/errors/base.ts:15
traceIdreadonlystring-SqunError.traceIdsrc/errors/base.ts:14
stackTraceLimitstaticnumberThe Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.SqunError.stackTraceLimitnode_modules/@types/node/globals.d.ts:67

Methods ​

toJSON() ​
ts
toJSON(): Record<string, unknown>;

Defined in: src/errors/base.ts:31

Returns ​

Record<string, unknown>

Inherited from ​

SqunError.toJSON

captureStackTrace() ​
Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/bun-types/globals.d.ts:1042

Create .stack property on a target object

Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

isError() ​
Call Signature ​
ts
static isError(error): error is Error;

Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters ​
ParameterType
errorunknown
Returns ​

error is Error

Inherited from ​

SqunError.isError

Call Signature ​
ts
static isError(value): value is Error;

Defined in: node_modules/bun-types/globals.d.ts:1037

Check if a value is an instance of Error

Parameters ​
ParameterTypeDescription
valueunknownThe value to check
Returns ​

value is Error

True if the value is an instance of Error, false otherwise

Inherited from ​

SqunError.isError

prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from ​

SqunError.prepareStackTrace


ReadonlyViolationError ​

Defined in: src/errors/types.ts:10

Base class for every error thrown by Squn.

Subclasses set a narrower code domain but never override the shape — every SqunError carries a code, structured context, a trace ID for log correlation, a timestamp, and an optional cause (the original driver error).

Extends ​

Constructors ​

Constructor ​
ts
new ReadonlyViolationError(
   code, 
   message, 
   context, 
   cause?): ReadonlyViolationError;

Defined in: src/errors/base.ts:18

Parameters ​
ParameterType
codeErrorCode
messagestring
contextErrorContext
cause?unknown
Returns ​

ReadonlyViolationError

Inherited from ​

SqunError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
cause?readonlyunknownThe cause of the error.SqunError.causesrc/errors/base.ts:16
codereadonlyErrorCode-SqunError.codesrc/errors/base.ts:12
contextreadonlyErrorContext-SqunError.contextsrc/errors/base.ts:13
messagepublicstring-SqunError.messagenode_modules/typescript/lib/lib.es5.d.ts:1077
namepublicstring-SqunError.namenode_modules/typescript/lib/lib.es5.d.ts:1076
stack?publicstring-SqunError.stacknode_modules/typescript/lib/lib.es5.d.ts:1078
timestampreadonlyDate-SqunError.timestampsrc/errors/base.ts:15
traceIdreadonlystring-SqunError.traceIdsrc/errors/base.ts:14
stackTraceLimitstaticnumberThe Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.SqunError.stackTraceLimitnode_modules/@types/node/globals.d.ts:67

Methods ​

toJSON() ​
ts
toJSON(): Record<string, unknown>;

Defined in: src/errors/base.ts:31

Returns ​

Record<string, unknown>

Inherited from ​

SqunError.toJSON

captureStackTrace() ​
Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/bun-types/globals.d.ts:1042

Create .stack property on a target object

Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

isError() ​
Call Signature ​
ts
static isError(error): error is Error;

Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters ​
ParameterType
errorunknown
Returns ​

error is Error

Inherited from ​

SqunError.isError

Call Signature ​
ts
static isError(value): value is Error;

Defined in: node_modules/bun-types/globals.d.ts:1037

Check if a value is an instance of Error

Parameters ​
ParameterTypeDescription
valueunknownThe value to check
Returns ​

value is Error

True if the value is an instance of Error, false otherwise

Inherited from ​

SqunError.isError

prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from ​

SqunError.prepareStackTrace


Savepoint ​

Defined in: src/transaction/savepoint.ts:8

Savepoint within a transaction. Names use format: squn_sp_{txId}_{depth}.

Constructors ​

Constructor ​
ts
new Savepoint(
   tx, 
   txId, 
   depth): Savepoint;

Defined in: src/transaction/savepoint.ts:11

Parameters ​
ParameterType
txIDbTransaction
txIdstring
depthnumber
Returns ​

Savepoint

Properties ​

PropertyModifierTypeDefined in
namereadonlystringsrc/transaction/savepoint.ts:9

Methods ​

create() ​
ts
create(): Promise<void>;

Defined in: src/transaction/savepoint.ts:21

Creates the savepoint on the database.

Returns ​

Promise<void>

release() ​
ts
release(): Promise<void>;

Defined in: src/transaction/savepoint.ts:49

Releases this savepoint.

Returns ​

Promise<void>

rollback() ​
ts
rollback(): Promise<void>;

Defined in: src/transaction/savepoint.ts:35

Rolls back to this savepoint.

Returns ​

Promise<void>


SecurityError ​

Defined in: src/errors/types.ts:11

Base class for every error thrown by Squn.

Subclasses set a narrower code domain but never override the shape — every SqunError carries a code, structured context, a trace ID for log correlation, a timestamp, and an optional cause (the original driver error).

Extends ​

Constructors ​

Constructor ​
ts
new SecurityError(
   code, 
   message, 
   context, 
   cause?): SecurityError;

Defined in: src/errors/base.ts:18

Parameters ​
ParameterType
codeErrorCode
messagestring
contextErrorContext
cause?unknown
Returns ​

SecurityError

Inherited from ​

SqunError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
cause?readonlyunknownThe cause of the error.SqunError.causesrc/errors/base.ts:16
codereadonlyErrorCode-SqunError.codesrc/errors/base.ts:12
contextreadonlyErrorContext-SqunError.contextsrc/errors/base.ts:13
messagepublicstring-SqunError.messagenode_modules/typescript/lib/lib.es5.d.ts:1077
namepublicstring-SqunError.namenode_modules/typescript/lib/lib.es5.d.ts:1076
stack?publicstring-SqunError.stacknode_modules/typescript/lib/lib.es5.d.ts:1078
timestampreadonlyDate-SqunError.timestampsrc/errors/base.ts:15
traceIdreadonlystring-SqunError.traceIdsrc/errors/base.ts:14
stackTraceLimitstaticnumberThe Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.SqunError.stackTraceLimitnode_modules/@types/node/globals.d.ts:67

Methods ​

toJSON() ​
ts
toJSON(): Record<string, unknown>;

Defined in: src/errors/base.ts:31

Returns ​

Record<string, unknown>

Inherited from ​

SqunError.toJSON

captureStackTrace() ​
Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/bun-types/globals.d.ts:1042

Create .stack property on a target object

Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

isError() ​
Call Signature ​
ts
static isError(error): error is Error;

Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters ​
ParameterType
errorunknown
Returns ​

error is Error

Inherited from ​

SqunError.isError

Call Signature ​
ts
static isError(value): value is Error;

Defined in: node_modules/bun-types/globals.d.ts:1037

Check if a value is an instance of Error

Parameters ​
ParameterTypeDescription
valueunknownThe value to check
Returns ​

value is Error

True if the value is an instance of Error, false otherwise

Inherited from ​

SqunError.isError

prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from ​

SqunError.prepareStackTrace


SqliteAdapter ​

Defined in: src/adapters/sqlite.ts:12

Database adapter contract — all database-specific behaviour lives here.

Implements ​

Constructors ​

Constructor ​
ts
new SqliteAdapter(options?): SqliteAdapter;

Defined in: src/adapters/sqlite.ts:16

Parameters ​
ParameterType
optionsSqliteAdapterOptions
Returns ​

SqliteAdapter

Properties ​

PropertyModifierTypeDefined in
typereadonly"sqlite"src/adapters/sqlite.ts:13

Methods ​

beginTransaction() ​
ts
beginTransaction(): Promise<IDbTransaction>;

Defined in: src/adapters/sqlite.ts:86

Returns ​

Promise<IDbTransaction>

Implementation of ​

IDbAdapter.beginTransaction

close() ​
ts
close(): Promise<void>;

Defined in: src/adapters/sqlite.ts:262

Returns ​

Promise<void>

Implementation of ​

IDbAdapter.close

execute() ​
ts
execute(sql, params): Promise<{
  rowsAffected: number;
}>;

Defined in: src/adapters/sqlite.ts:31

Parameters ​
ParameterType
sqlstring
paramsunknown[]
Returns ​

Promise<{ rowsAffected: number; }>

Implementation of ​

IDbAdapter.execute

executeBatch() ​
ts
executeBatch(
   sql, 
   rows, 
   paramNames, 
   _strategy?): Promise<{
  rowsAffected: number;
}>;

Defined in: src/adapters/sqlite.ts:215

Executes the same prepared statement once per row using native batch/pipeline. paramNames maps column names to positional params in sql.

Parameters ​
ParameterType
sqlstring
rowsreadonly Record<string, unknown>[]
paramNamesreadonly string[]
_strategy?"prepared-loop" | "copy" | "bulk-load"
Returns ​

Promise<{ rowsAffected: number; }>

Implementation of ​

IDbAdapter.executeBatch

hasCursorSupport() ​
ts
hasCursorSupport(): boolean;

Defined in: src/adapters/sqlite.ts:242

Returns true if the adapter supports server-side cursors for streaming.

Returns ​

boolean

Implementation of ​

IDbAdapter.hasCursorSupport

materializeTvp() ​
ts
materializeTvp(tvp, _index): Promise<TvpMaterialised>;

Defined in: src/adapters/sqlite.ts:278

Parameters ​
ParameterType
tvpTvpValue
_indexnumber
Returns ​

Promise<TvpMaterialised>

Implementation of ​

IDbAdapter.materializeTvp

ping() ​
ts
ping(): Promise<void>;

Defined in: src/adapters/sqlite.ts:246

Returns ​

Promise<void>

Implementation of ​

IDbAdapter.ping

query() ​
ts
query(sql, params): Promise<Row[]>;

Defined in: src/adapters/sqlite.ts:50

Parameters ​
ParameterType
sqlstring
paramsunknown[]
Returns ​

Promise<Row[]>

Implementation of ​

IDbAdapter.query

queryMultiple() ​
ts
queryMultiple(sql, params): Promise<Row[][]>;

Defined in: src/adapters/sqlite.ts:66

Parameters ​
ParameterType
sqlstring
paramsunknown[]
Returns ​

Promise<Row[][]>

Implementation of ​

IDbAdapter.queryMultiple


SqunConfigError ​

Defined in: src/errors/types.ts:12

Base class for every error thrown by Squn.

Subclasses set a narrower code domain but never override the shape — every SqunError carries a code, structured context, a trace ID for log correlation, a timestamp, and an optional cause (the original driver error).

Extends ​

Constructors ​

Constructor ​
ts
new SqunConfigError(
   code, 
   message, 
   context, 
   cause?): SqunConfigError;

Defined in: src/errors/base.ts:18

Parameters ​
ParameterType
codeErrorCode
messagestring
contextErrorContext
cause?unknown
Returns ​

SqunConfigError

Inherited from ​

SqunError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
cause?readonlyunknownThe cause of the error.SqunError.causesrc/errors/base.ts:16
codereadonlyErrorCode-SqunError.codesrc/errors/base.ts:12
contextreadonlyErrorContext-SqunError.contextsrc/errors/base.ts:13
messagepublicstring-SqunError.messagenode_modules/typescript/lib/lib.es5.d.ts:1077
namepublicstring-SqunError.namenode_modules/typescript/lib/lib.es5.d.ts:1076
stack?publicstring-SqunError.stacknode_modules/typescript/lib/lib.es5.d.ts:1078
timestampreadonlyDate-SqunError.timestampsrc/errors/base.ts:15
traceIdreadonlystring-SqunError.traceIdsrc/errors/base.ts:14
stackTraceLimitstaticnumberThe Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.SqunError.stackTraceLimitnode_modules/@types/node/globals.d.ts:67

Methods ​

toJSON() ​
ts
toJSON(): Record<string, unknown>;

Defined in: src/errors/base.ts:31

Returns ​

Record<string, unknown>

Inherited from ​

SqunError.toJSON

captureStackTrace() ​
Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/bun-types/globals.d.ts:1042

Create .stack property on a target object

Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

isError() ​
Call Signature ​
ts
static isError(error): error is Error;

Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters ​
ParameterType
errorunknown
Returns ​

error is Error

Inherited from ​

SqunError.isError

Call Signature ​
ts
static isError(value): value is Error;

Defined in: node_modules/bun-types/globals.d.ts:1037

Check if a value is an instance of Error

Parameters ​
ParameterTypeDescription
valueunknownThe value to check
Returns ​

value is Error

True if the value is an instance of Error, false otherwise

Inherited from ​

SqunError.isError

prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from ​

SqunError.prepareStackTrace


abstract SqunError ​

Defined in: src/errors/base.ts:11

Base class for every error thrown by Squn.

Subclasses set a narrower code domain but never override the shape — every SqunError carries a code, structured context, a trace ID for log correlation, a timestamp, and an optional cause (the original driver error).

Extends ​

  • Error

Extended by ​

Constructors ​

Constructor ​
ts
new SqunError(
   code, 
   message, 
   context, 
   cause?): SqunError;

Defined in: src/errors/base.ts:18

Parameters ​
ParameterType
codeErrorCode
messagestring
contextErrorContext
cause?unknown
Returns ​

SqunError

Overrides ​
ts
Error.constructor

Properties ​

PropertyModifierTypeDescriptionOverridesInherited fromDefined in
cause?readonlyunknownThe cause of the error.Error.cause-src/errors/base.ts:16
codereadonlyErrorCode---src/errors/base.ts:12
contextreadonlyErrorContext---src/errors/base.ts:13
messagepublicstring--Error.messagenode_modules/typescript/lib/lib.es5.d.ts:1077
namepublicstring--Error.namenode_modules/typescript/lib/lib.es5.d.ts:1076
stack?publicstring--Error.stacknode_modules/typescript/lib/lib.es5.d.ts:1078
timestampreadonlyDate---src/errors/base.ts:15
traceIdreadonlystring---src/errors/base.ts:14
stackTraceLimitstaticnumberThe Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.-Error.stackTraceLimitnode_modules/@types/node/globals.d.ts:67

Methods ​

toJSON() ​
ts
toJSON(): Record<string, unknown>;

Defined in: src/errors/base.ts:31

Returns ​

Record<string, unknown>

captureStackTrace() ​
Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​
ts
Error.captureStackTrace
Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/bun-types/globals.d.ts:1042

Create .stack property on a target object

Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​
ts
Error.captureStackTrace
isError() ​
Call Signature ​
ts
static isError(error): error is Error;

Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters ​
ParameterType
errorunknown
Returns ​

error is Error

Inherited from ​
ts
Error.isError
Call Signature ​
ts
static isError(value): value is Error;

Defined in: node_modules/bun-types/globals.d.ts:1037

Check if a value is an instance of Error

Parameters ​
ParameterTypeDescription
valueunknownThe value to check
Returns ​

value is Error

True if the value is an instance of Error, false otherwise

Inherited from ​
ts
Error.isError
prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from ​
ts
Error.prepareStackTrace

TableType ​

Defined in: src/core/tvp/table-type.ts:5

Represents a Table-Valued Parameter type definition. Schema maps column names to database type strings (e.g. "nvarchar(100)", "int").

Type Parameters ​

Type Parameter
Schema extends Record<string, string>

Constructors ​

Constructor ​
ts
new TableType<Schema>(name, schema): TableType<Schema>;

Defined in: src/core/tvp/table-type.ts:9

Parameters ​
ParameterType
namestring
schemaSchema
Returns ​

TableType<Schema>

Properties ​

PropertyModifierTypeDefined in
namereadonlystringsrc/core/tvp/table-type.ts:6
schemareadonlySchemasrc/core/tvp/table-type.ts:7

TimeoutError ​

Defined in: src/errors/types.ts:8

Base class for every error thrown by Squn.

Subclasses set a narrower code domain but never override the shape — every SqunError carries a code, structured context, a trace ID for log correlation, a timestamp, and an optional cause (the original driver error).

Extends ​

Constructors ​

Constructor ​
ts
new TimeoutError(
   code, 
   message, 
   context, 
   cause?): TimeoutError;

Defined in: src/errors/base.ts:18

Parameters ​
ParameterType
codeErrorCode
messagestring
contextErrorContext
cause?unknown
Returns ​

TimeoutError

Inherited from ​

SqunError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
cause?readonlyunknownThe cause of the error.SqunError.causesrc/errors/base.ts:16
codereadonlyErrorCode-SqunError.codesrc/errors/base.ts:12
contextreadonlyErrorContext-SqunError.contextsrc/errors/base.ts:13
messagepublicstring-SqunError.messagenode_modules/typescript/lib/lib.es5.d.ts:1077
namepublicstring-SqunError.namenode_modules/typescript/lib/lib.es5.d.ts:1076
stack?publicstring-SqunError.stacknode_modules/typescript/lib/lib.es5.d.ts:1078
timestampreadonlyDate-SqunError.timestampsrc/errors/base.ts:15
traceIdreadonlystring-SqunError.traceIdsrc/errors/base.ts:14
stackTraceLimitstaticnumberThe Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.SqunError.stackTraceLimitnode_modules/@types/node/globals.d.ts:67

Methods ​

toJSON() ​
ts
toJSON(): Record<string, unknown>;

Defined in: src/errors/base.ts:31

Returns ​

Record<string, unknown>

Inherited from ​

SqunError.toJSON

captureStackTrace() ​
Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/bun-types/globals.d.ts:1042

Create .stack property on a target object

Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

isError() ​
Call Signature ​
ts
static isError(error): error is Error;

Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters ​
ParameterType
errorunknown
Returns ​

error is Error

Inherited from ​

SqunError.isError

Call Signature ​
ts
static isError(value): value is Error;

Defined in: node_modules/bun-types/globals.d.ts:1037

Check if a value is an instance of Error

Parameters ​
ParameterTypeDescription
valueunknownThe value to check
Returns ​

value is Error

True if the value is an instance of Error, false otherwise

Inherited from ​

SqunError.isError

prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from ​

SqunError.prepareStackTrace


Transaction ​

Defined in: src/transaction/transaction.ts:14

Transaction with state machine: ACTIVE → COMMITTED | ROLLED_BACK | TIMED_OUT | FAILED. Any operation on a non-ACTIVE transaction throws TX_ALREADY_CLOSED immediately.

Constructors ​

Constructor ​
ts
new Transaction(tx, id?): Transaction;

Defined in: src/transaction/transaction.ts:20

Parameters ​
ParameterType
txIDbTransaction
id?string
Returns ​

Transaction

Properties ​

PropertyModifierTypeDefined in
clockreadonlyTransactionClocksrc/transaction/transaction.ts:18
idreadonlystringsrc/transaction/transaction.ts:17

Accessors ​

state ​
Get Signature ​
ts
get state(): TransactionState;

Defined in: src/transaction/transaction.ts:28

Returns ​

TransactionState

Methods ​

[asyncDispose]() ​
ts
asyncDispose: Promise<void>;

Defined in: src/transaction/transaction.ts:90

Returns ​

Promise<void>

commit() ​
ts
commit(): Promise<void>;

Defined in: src/transaction/transaction.ts:42

Returns ​

Promise<void>

execute() ​
ts
execute(sql, params): Promise<{
  rowsAffected: number;
}>;

Defined in: src/transaction/transaction.ts:37

Parameters ​
ParameterType
sqlstring
paramsunknown[]
Returns ​

Promise<{ rowsAffected: number; }>

markFailed() ​
ts
markFailed(): void;

Defined in: src/transaction/transaction.ts:86

Returns ​

void

markTimedOut() ​
ts
markTimedOut(): void;

Defined in: src/transaction/transaction.ts:82

Returns ​

void

query() ​
ts
query(sql, params): Promise<Row[]>;

Defined in: src/transaction/transaction.ts:32

Parameters ​
ParameterType
sqlstring
paramsunknown[]
Returns ​

Promise<Row[]>

rollback() ​
ts
rollback(): Promise<void>;

Defined in: src/transaction/transaction.ts:58

Returns ​

Promise<void>

savepoint() ​
ts
savepoint(): Promise<Savepoint>;

Defined in: src/transaction/transaction.ts:74

Returns ​

Promise<Savepoint>


TransactionClock ​

Defined in: src/async/clock.ts:5

Tracks wall-clock elapsed time for a transaction. Each child query receives at most the remaining budget.

Constructors ​

Constructor ​
ts
new TransactionClock(): TransactionClock;

Defined in: src/async/clock.ts:8

Returns ​

TransactionClock

Methods ​

elapsed() ​
ts
elapsed(): number;

Defined in: src/async/clock.ts:13

Milliseconds elapsed since the clock started.

Returns ​

number

expired() ​
ts
expired(budgetMs): boolean;

Defined in: src/async/clock.ts:27

True if the elapsed time has exceeded the budget.

Parameters ​
ParameterType
budgetMsnumber
Returns ​

boolean

remaining() ​
ts
remaining(budgetMs): number | null;

Defined in: src/async/clock.ts:21

Milliseconds remaining in the budget, or null if no budget applies. Returns 0 (not negative) when the budget is exhausted.

Parameters ​
ParameterType
budgetMsnumber
Returns ​

number | null


TransactionError ​

Defined in: src/errors/types.ts:7

Base class for every error thrown by Squn.

Subclasses set a narrower code domain but never override the shape — every SqunError carries a code, structured context, a trace ID for log correlation, a timestamp, and an optional cause (the original driver error).

Extends ​

Extended by ​

Constructors ​

Constructor ​
ts
new TransactionError(
   code, 
   message, 
   context, 
   cause?): TransactionError;

Defined in: src/errors/base.ts:18

Parameters ​
ParameterType
codeErrorCode
messagestring
contextErrorContext
cause?unknown
Returns ​

TransactionError

Inherited from ​

SqunError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
cause?readonlyunknownThe cause of the error.SqunError.causesrc/errors/base.ts:16
codereadonlyErrorCode-SqunError.codesrc/errors/base.ts:12
contextreadonlyErrorContext-SqunError.contextsrc/errors/base.ts:13
messagepublicstring-SqunError.messagenode_modules/typescript/lib/lib.es5.d.ts:1077
namepublicstring-SqunError.namenode_modules/typescript/lib/lib.es5.d.ts:1076
stack?publicstring-SqunError.stacknode_modules/typescript/lib/lib.es5.d.ts:1078
timestampreadonlyDate-SqunError.timestampsrc/errors/base.ts:15
traceIdreadonlystring-SqunError.traceIdsrc/errors/base.ts:14
stackTraceLimitstaticnumberThe Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.SqunError.stackTraceLimitnode_modules/@types/node/globals.d.ts:67

Methods ​

toJSON() ​
ts
toJSON(): Record<string, unknown>;

Defined in: src/errors/base.ts:31

Returns ​

Record<string, unknown>

Inherited from ​

SqunError.toJSON

captureStackTrace() ​
Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/bun-types/globals.d.ts:1042

Create .stack property on a target object

Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

isError() ​
Call Signature ​
ts
static isError(error): error is Error;

Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters ​
ParameterType
errorunknown
Returns ​

error is Error

Inherited from ​

SqunError.isError

Call Signature ​
ts
static isError(value): value is Error;

Defined in: node_modules/bun-types/globals.d.ts:1037

Check if a value is an instance of Error

Parameters ​
ParameterTypeDescription
valueunknownThe value to check
Returns ​

value is Error

True if the value is an instance of Error, false otherwise

Inherited from ​

SqunError.isError

prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from ​

SqunError.prepareStackTrace


TypeHandlerRegistry ​

Defined in: src/core/type-handler.ts:112

Registers and looks up TypeHandlers by column type string. Built-in handlers cover all standard column types. Unknown types fall back to an identity handler that passes values through unchanged.

Constructors ​

Constructor ​
ts
new TypeHandlerRegistry(): TypeHandlerRegistry;
Returns ​

TypeHandlerRegistry

Methods ​

fromDb() ​
ts
fromDb(dbType, raw): unknown;

Defined in: src/core/type-handler.ts:126

Converts a raw database value to the TypeScript type for the given column type.

Parameters ​
ParameterType
dbTypestring
rawunknown
Returns ​

unknown

get() ​
ts
get(dbType): TypeHandler;

Defined in: src/core/type-handler.ts:121

Returns the handler for a column type. Falls back to identity for unknown types.

Parameters ​
ParameterType
dbTypestring
Returns ​

TypeHandler

register() ​
ts
register<T>(dbType, handler): void;

Defined in: src/core/type-handler.ts:116

Registers a custom handler for a column type, overriding any built-in.

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
dbTypestring
handlerTypeHandler<T>
Returns ​

void

toDb() ​
ts
toDb(dbType, value): unknown;

Defined in: src/core/type-handler.ts:132

Converts a TypeScript value to the database type for the given column type.

Parameters ​
ParameterType
dbTypestring
valueunknown
Returns ​

unknown


ValidationError ​

Defined in: src/errors/types.ts:6

Base class for every error thrown by Squn.

Subclasses set a narrower code domain but never override the shape — every SqunError carries a code, structured context, a trace ID for log correlation, a timestamp, and an optional cause (the original driver error).

Extends ​

Constructors ​

Constructor ​
ts
new ValidationError(
   code, 
   message, 
   context, 
   cause?): ValidationError;

Defined in: src/errors/base.ts:18

Parameters ​
ParameterType
codeErrorCode
messagestring
contextErrorContext
cause?unknown
Returns ​

ValidationError

Inherited from ​

SqunError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
cause?readonlyunknownThe cause of the error.SqunError.causesrc/errors/base.ts:16
codereadonlyErrorCode-SqunError.codesrc/errors/base.ts:12
contextreadonlyErrorContext-SqunError.contextsrc/errors/base.ts:13
messagepublicstring-SqunError.messagenode_modules/typescript/lib/lib.es5.d.ts:1077
namepublicstring-SqunError.namenode_modules/typescript/lib/lib.es5.d.ts:1076
stack?publicstring-SqunError.stacknode_modules/typescript/lib/lib.es5.d.ts:1078
timestampreadonlyDate-SqunError.timestampsrc/errors/base.ts:15
traceIdreadonlystring-SqunError.traceIdsrc/errors/base.ts:14
stackTraceLimitstaticnumberThe Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.SqunError.stackTraceLimitnode_modules/@types/node/globals.d.ts:67

Methods ​

toJSON() ​
ts
toJSON(): Record<string, unknown>;

Defined in: src/errors/base.ts:31

Returns ​

Record<string, unknown>

Inherited from ​

SqunError.toJSON

captureStackTrace() ​
Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

Call Signature ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/bun-types/globals.d.ts:1042

Create .stack property on a target object

Parameters ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​

SqunError.captureStackTrace

isError() ​
Call Signature ​
ts
static isError(error): error is Error;

Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters ​
ParameterType
errorunknown
Returns ​

error is Error

Inherited from ​

SqunError.isError

Call Signature ​
ts
static isError(value): value is Error;

Defined in: node_modules/bun-types/globals.d.ts:1037

Check if a value is an instance of Error

Parameters ​
ParameterTypeDescription
valueunknownThe value to check
Returns ​

value is Error

True if the value is an instance of Error, false otherwise

Inherited from ​

SqunError.isError

prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from ​

SqunError.prepareStackTrace

Interfaces ​

AtomicBlockOptions ​

Defined in: src/transaction/atomic.ts:25

Properties ​

PropertyModifierTypeDefined in
isolation?readonlyIsolationLevelsrc/transaction/atomic.ts:30
maxRetries?readonlynumbersrc/transaction/atomic.ts:28
retryDelayMs?readonlynumbersrc/transaction/atomic.ts:29
retryOnError?readonlybooleansrc/transaction/atomic.ts:27
timeoutMs?readonlynumbersrc/transaction/atomic.ts:26

AtomicExecutor ​

Defined in: src/transaction/atomic.ts:13

The limited API available inside an atomically() callback.

Methods ​

execute() ​
ts
execute(fragment): Promise<{
  rowsAffected: number;
}>;

Defined in: src/transaction/atomic.ts:18

Parameters ​
ParameterType
fragmentSqlFragment
Returns ​

Promise<{ rowsAffected: number; }>

executeBatch() ​
ts
executeBatch(fragment, rows): Promise<{
  rowsAffected: number;
}>;

Defined in: src/transaction/atomic.ts:19

Parameters ​
ParameterType
fragmentSqlFragment
rowsreadonly Record<string, unknown>[]
Returns ​

Promise<{ rowsAffected: number; }>

query() ​
ts
query<T>(fragment): Promise<T[]>;

Defined in: src/transaction/atomic.ts:14

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
Returns ​

Promise<T[]>

queryFirst() ​
ts
queryFirst<T>(fragment): Promise<T | null>;

Defined in: src/transaction/atomic.ts:15

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
Returns ​

Promise<T | null>

queryScalar() ​
ts
queryScalar<T>(fragment): Promise<T>;

Defined in: src/transaction/atomic.ts:17

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
Returns ​

Promise<T>

querySingle() ​
ts
querySingle<T>(fragment): Promise<T>;

Defined in: src/transaction/atomic.ts:16

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
Returns ​

Promise<T>


AzureAdConfig ​

Defined in: src/config/types.ts:64

Properties ​

PropertyModifierTypeDefined in
clientId?readonlystringsrc/config/types.ts:66
clientSecret?readonlystringsrc/config/types.ts:67
managedIdentity?readonlybooleansrc/config/types.ts:68
tenantId?readonlystringsrc/config/types.ts:65

CacheConfig ​

Defined in: src/config/types.ts:40

Properties ​

PropertyModifierTypeDefined in
maxAgeMs?readonlynumber | nullsrc/config/types.ts:43
maxSize?readonlynumbersrc/config/types.ts:41
reaperIntervalMs?readonlynumber | nullsrc/config/types.ts:44
ttlMs?readonlynumber | nullsrc/config/types.ts:42

CacheOptions ​

Defined in: src/cache/cached-db.ts:12

Options for createCachedDb.

Properties ​

PropertyModifierTypeDescriptionDefined in
keyFn?readonly(sql, params) => stringCustom cache-key function. Receives the raw SQL string and the parameter array and must return a stable string key. Defaults to sql + JSON.stringify(params).src/cache/cached-db.ts:30
maxSize?readonlynumberMaximum number of entries the cache may hold. Oldest-inserted entries are evicted when the limit is reached (FIFO order, since we keep insertion order in the underlying Map). Defaults to 500.src/cache/cached-db.ts:24
ttlreadonlynumberTime-to-live in milliseconds for each cached result. The entry is evicted when it has not been accessed within this window.src/cache/cached-db.ts:17

CacheStats ​

Defined in: src/cache/cached-db.ts:37

Hit/miss counters returned by CachedDb.stats.

Properties ​

PropertyModifierTypeDefined in
hitsreadonlynumbersrc/cache/cached-db.ts:38
missesreadonlynumbersrc/cache/cached-db.ts:39
sizereadonlynumbersrc/cache/cached-db.ts:40

ColumnDef ​

Defined in: src/types/col.ts:9

Column definition builder.

Captures column metadata as a plain object. Generic parameters encode the column's TypeScript type, nullability, and readonly status so that InferModel / InferInsert can read them at the type level.

Type Parameters ​

Type ParameterDefault type
Tunknown
Nullable extends booleanboolean
Readonly extends booleanboolean

Properties ​

PropertyModifierTypeDescriptionDefined in
__brandreadonly"ColumnDef"-src/types/col.ts:14
_typereadonlyNullable extends true ? T | null : TPhantom — carries the resolved TS type for inference.src/types/col.ts:24
computedExprreadonlystring | null-src/types/col.ts:21
dbMaxLengthreadonlynumber | "MAX" | null-src/types/col.ts:16
dbTypereadonlystring-src/types/col.ts:15
isComputedreadonlyboolean-src/types/col.ts:20
isNullablereadonlyNullable-src/types/col.ts:17
isPrimaryKeyreadonlyboolean-src/types/col.ts:19
isReadonlyreadonlyReadonly-src/types/col.ts:18
isUniquereadonlyboolean-src/types/col.ts:22

CompiledQuery ​

Defined in: src/cache/query-cache.ts:4

The compiled representation of a query stored in the cache.

Properties ​

PropertyModifierTypeDefined in
normalizedSqlreadonlystringsrc/cache/query-cache.ts:5
paramNamesreadonlyreadonly string[]src/cache/query-cache.ts:6

ConnectionConfig ​

Defined in: src/config/types.ts:11

Properties ​

PropertyModifierTypeDefined in
authType?readonlyAuthTypesrc/config/types.ts:19
database?readonlystringsrc/config/types.ts:15
domain?readonlystringsrc/config/types.ts:20
host?readonlystringsrc/config/types.ts:13
password?readonlystringsrc/config/types.ts:17
port?readonlynumbersrc/config/types.ts:14
readonly?readonlybooleansrc/config/types.ts:22
ssl?readonlyboolean | "require"src/config/types.ts:18
upn?readonlystringsrc/config/types.ts:21
url?readonlystringsrc/config/types.ts:12
user?readonlystringsrc/config/types.ts:16

CursorPage ​

Defined in: src/pagination/cursor.ts:64

Result of a cursor-based paginated query.

Type Parameters ​

Type Parameter
T

Properties ​

PropertyModifierTypeDefined in
hasNextreadonlybooleansrc/pagination/cursor.ts:68
nextCursorreadonlystring | nullsrc/pagination/cursor.ts:66
prevCursorreadonlystring | nullsrc/pagination/cursor.ts:67
rowsreadonlyT[]src/pagination/cursor.ts:65

CursorPageOptions ​

Defined in: src/pagination/cursor.ts:75

Options for cursor pagination.

Properties ​

PropertyModifierTypeDescriptionDefined in
cursor?readonlystringOpaque cursor string returned from a previous page (undefined = first page).src/pagination/cursor.ts:77
cursorColumnreadonlystringThe column used for cursor-based ordering (must be unique or near-unique).src/pagination/cursor.ts:81
direction?readonly"asc" | "desc"Sort direction. Defaults to 'asc'.src/pagination/cursor.ts:83
limitreadonlynumberMaximum number of rows to return.src/pagination/cursor.ts:79

Database ​

Defined in: src/db.ts:27

Properties ​

PropertyModifierTypeDefined in
adapterreadonlyIDbAdaptersrc/db.ts:28
configreadonlySqunConfigsrc/db.ts:29

Methods ​

atomically() ​
ts
atomically<T>(fn, options?): Promise<T>;

Defined in: src/db.ts:43

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fn(q) => Promise<T>
options?AtomicBlockOptions
Returns ​

Promise<T>

execute() ​
ts
execute(fragment): Promise<{
  rowsAffected: number;
}>;

Defined in: src/db.ts:36

Parameters ​
ParameterType
fragmentSqlFragment
Returns ​

Promise<{ rowsAffected: number; }>

executeBatch() ​
ts
executeBatch(
   fragment, 
   rows, 
   options?): Promise<{
  rowsAffected: number;
}>;

Defined in: src/db.ts:37

Parameters ​
ParameterType
fragmentSqlFragment
rowsreadonly Record<string, unknown>[]
options?{ strategy?: "prepared-loop" | "copy" | "bulk-load"; }
options.strategy?"prepared-loop" | "copy" | "bulk-load"
Returns ​

Promise<{ rowsAffected: number; }>

prepare() ​
ts
prepare<T, P>(fragment, paramNames): PreparedQuery<T, P>;

Defined in: src/db.ts:45

Type Parameters ​
Type Parameter
T
P extends Record<string, unknown>
Parameters ​
ParameterType
fragmentSqlFragment
paramNamesreadonly string[]
Returns ​

PreparedQuery<T, P>

query() ​
ts
query<T>(fragment): Promise<T[]>;

Defined in: src/db.ts:31

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
Returns ​

Promise<T[]>

queryFirst() ​
ts
queryFirst<T>(fragment): Promise<T | null>;

Defined in: src/db.ts:32

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
Returns ​

Promise<T | null>

queryMultiple() ​
ts
queryMultiple(fragment): Promise<Row[][]>;

Defined in: src/db.ts:35

Parameters ​
ParameterType
fragmentSqlFragment
Returns ​

Promise<Row[][]>

queryScalar() ​
ts
queryScalar<T>(fragment): Promise<T>;

Defined in: src/db.ts:34

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
Returns ​

Promise<T>

querySingle() ​
ts
querySingle<T>(fragment): Promise<T>;

Defined in: src/db.ts:33

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
Returns ​

Promise<T>

stream() ​
ts
stream<T>(fragment, batchSize?): AsyncIterableIterator<T>;

Defined in: src/db.ts:42

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
batchSize?number
Returns ​

AsyncIterableIterator<T>

transaction() ​
ts
transaction(fn): Promise<void>;

Defined in: src/db.ts:44

Parameters ​
ParameterType
fn(tx) => Promise<void>
Returns ​

Promise<void>


DetectionResult ​

Defined in: src/sql/injection-detector.ts:5

Properties ​

PropertyModifierTypeDefined in
detectedreadonlybooleansrc/sql/injection-detector.ts:6
patternreadonlystring | nullsrc/sql/injection-detector.ts:8
severityreadonlySeverity | nullsrc/sql/injection-detector.ts:7

ErrorContext ​

Defined in: src/errors/context.ts:8

Structured context attached to every SqunError.

All fields are optional — each error subclass populates only the fields relevant to its failure mode. Consumers should never assume a field is present without checking.

Properties ​

PropertyModifierTypeDescriptionDefined in
adapter?readonlystringWhich database adapter was in use ("sqlite""postgres"
column?readonlystringColumn name relevant to the error.src/errors/context.ts:25
durationMs?readonlynumberElapsed wall-clock time in milliseconds when the error occurred.src/errors/context.ts:34
operation?readonlystringThe high-level operation that failed (e.g. "query", "execute", "commit").src/errors/context.ts:10
paramKeys?readonlyreadonly string[]Param key names from the query (values are never logged).src/errors/context.ts:16
registeredNames?readonlyreadonly string[]Connection names currently registered — aids debugging CONN_UNKNOWN errors.src/errors/context.ts:43
requestedName?readonlystringConnection name that was requested but not found in the registry.src/errors/context.ts:40
rowIndex?readonlynumberRow index within a result set where mapping failed.src/errors/context.ts:31
sql?readonlystringSanitised SQL text — param values are never included.src/errors/context.ts:13
table?readonlystringTable name relevant to the error.src/errors/context.ts:22
tvpRowIndex?readonlynumberRow index within a TVP batch where validation failed.src/errors/context.ts:28
txId?readonlystringTransaction identifier — ties the error to a specific transaction scope.src/errors/context.ts:37

ExecuteOptions ​

Defined in: src/connections/types.ts:34

Type Parameters ​

Type ParameterDefault type
Names extends stringnever

Properties ​

PropertyModifierTypeDefined in
connection?readonly[Names] extends [never] ? never : Namessrc/connections/types.ts:35
timeoutMs?readonlynumbersrc/connections/types.ts:36

GroupConfig ​

Defined in: src/connections/types.ts:20

Properties ​

PropertyModifierTypeDefined in
readreadonlyreadonly string[]src/connections/types.ts:22
readMode?readonly"round-robin" | "least-load" | "random"src/connections/types.ts:23
writereadonlystringsrc/connections/types.ts:21

IDbAdapter ​

Defined in: src/adapters/base.ts:31

Database adapter contract — all database-specific behaviour lives here.

Properties ​

PropertyModifierTypeDefined in
typereadonlyAdapterTypesrc/adapters/base.ts:32

Methods ​

beginTransaction() ​
ts
beginTransaction(): Promise<IDbTransaction>;

Defined in: src/adapters/base.ts:46

Returns ​

Promise<IDbTransaction>

close() ​
ts
close(): Promise<void>;

Defined in: src/adapters/base.ts:50

Returns ​

Promise<void>

execute() ​
ts
execute(sql, params): Promise<{
  rowsAffected: number;
}>;

Defined in: src/adapters/base.ts:33

Parameters ​
ParameterType
sqlstring
paramsreadonly unknown[]
Returns ​

Promise<{ rowsAffected: number; }>

executeBatch() ​
ts
executeBatch(
   sql, 
   rows, 
   paramNames, 
   strategy?): Promise<{
  rowsAffected: number;
}>;

Defined in: src/adapters/base.ts:40

Executes the same prepared statement once per row using native batch/pipeline. paramNames maps column names to positional params in sql.

Parameters ​
ParameterType
sqlstring
rowsreadonly Record<string, unknown>[]
paramNamesreadonly string[]
strategy?"prepared-loop" | "copy" | "bulk-load"
Returns ​

Promise<{ rowsAffected: number; }>

hasCursorSupport() ​
ts
hasCursorSupport(): boolean;

Defined in: src/adapters/base.ts:48

Returns true if the adapter supports server-side cursors for streaming.

Returns ​

boolean

materializeTvp() ​
ts
materializeTvp(tvp, index): Promise<TvpMaterialised>;

Defined in: src/adapters/base.ts:51

Parameters ​
ParameterType
tvpTvpValue
indexnumber
Returns ​

Promise<TvpMaterialised>

ping() ​
ts
ping(): Promise<void>;

Defined in: src/adapters/base.ts:49

Returns ​

Promise<void>

query() ​
ts
query(sql, params): Promise<Row[]>;

Defined in: src/adapters/base.ts:34

Parameters ​
ParameterType
sqlstring
paramsreadonly unknown[]
Returns ​

Promise<Row[]>

queryMultiple() ​
ts
queryMultiple(sql, params): Promise<Row[][]>;

Defined in: src/adapters/base.ts:35

Parameters ​
ParameterType
sqlstring
paramsreadonly unknown[]
Returns ​

Promise<Row[][]>


IDbTransaction ​

Defined in: src/adapters/base.ts:20

Transaction handle returned by beginTransaction().

Methods ​

commit() ​
ts
commit(): Promise<void>;

Defined in: src/adapters/base.ts:23

Returns ​

Promise<void>

execute() ​
ts
execute(sql, params): Promise<{
  rowsAffected: number;
}>;

Defined in: src/adapters/base.ts:21

Parameters ​
ParameterType
sqlstring
paramsreadonly unknown[]
Returns ​

Promise<{ rowsAffected: number; }>

query() ​
ts
query(sql, params): Promise<Row[]>;

Defined in: src/adapters/base.ts:22

Parameters ​
ParameterType
sqlstring
paramsreadonly unknown[]
Returns ​

Promise<Row[]>

releaseSavepoint() ​
ts
releaseSavepoint(name): Promise<void>;

Defined in: src/adapters/base.ts:26

Parameters ​
ParameterType
namestring
Returns ​

Promise<void>

rollback() ​
ts
rollback(): Promise<void>;

Defined in: src/adapters/base.ts:24

Returns ​

Promise<void>

rollbackToSavepoint() ​
ts
rollbackToSavepoint(name): Promise<void>;

Defined in: src/adapters/base.ts:27

Parameters ​
ParameterType
namestring
Returns ​

Promise<void>

savepoint() ​
ts
savepoint(name): Promise<void>;

Defined in: src/adapters/base.ts:25

Parameters ​
ParameterType
namestring
Returns ​

Promise<void>


LogConfig ​

Defined in: src/config/types.ts:58

Properties ​

PropertyModifierTypeDefined in
level?readonly"debug" | "info" | "warn" | "error" | "fatal"src/config/types.ts:60
logger?readonlySqunLoggersrc/config/types.ts:59
slowQueryMs?readonlynumbersrc/config/types.ts:61

LogEntry ​

Defined in: src/logging/logger.ts:21

Structured log entry emitted by every logging call in the library.

Properties ​

PropertyModifierTypeDefined in
cause?readonlystringsrc/logging/logger.ts:29
codereadonlyErrorCode | EventCodesrc/logging/logger.ts:25
contextreadonlyErrorContextsrc/logging/logger.ts:27
durationMs?readonlynumbersrc/logging/logger.ts:30
levelreadonly"debug" | "info" | "warn" | "error" | "fatal"src/logging/logger.ts:22
messagereadonlystringsrc/logging/logger.ts:26
rowCount?readonlynumbersrc/logging/logger.ts:31
stack?readonlystringsrc/logging/logger.ts:28
timestampreadonlystringsrc/logging/logger.ts:23
traceIdreadonlystringsrc/logging/logger.ts:24

Migration ​

Defined in: src/migrations/types.ts:16

A single migration definition — up applies the change, down reverts it.

Properties ​

PropertyModifierTypeDefined in
down?readonlystringsrc/migrations/types.ts:19
idreadonlystringsrc/migrations/types.ts:17
upreadonlystringsrc/migrations/types.ts:18

MigrationOptions ​

Defined in: src/migrations/types.ts:26

Options for the migration runner.

Properties ​

PropertyModifierTypeDescriptionDefined in
logger?readonlySqunLoggerOptional logger for migration lifecycle events.src/migrations/types.ts:30
tableName?readonlystringName of the table used to track applied migrations. Defaults to _squn_migrations.src/migrations/types.ts:28

MigrationResult ​

Defined in: src/migrations/types.ts:37

Summary returned after running migrations.

Properties ​

PropertyModifierTypeDescriptionDefined in
appliedreadonlystring[]IDs of migrations that were applied in this run.src/migrations/types.ts:39
skippedreadonlystring[]IDs of migrations that were already recorded and skipped.src/migrations/types.ts:41

MultiAtomicOptions ​

Defined in: src/connections/types.ts:45

Type Parameters ​

Type ParameterDefault type
Names extends stringnever

Properties ​

PropertyModifierTypeDefined in
connection?readonly[Names] extends [never] ? never : Namessrc/connections/types.ts:46
isolation?readonlyIsolationLevelsrc/connections/types.ts:51
maxRetries?readonlynumbersrc/connections/types.ts:49
retryDelayMs?readonlynumbersrc/connections/types.ts:50
retryOnError?readonlybooleansrc/connections/types.ts:48
timeoutMs?readonlynumbersrc/connections/types.ts:47

MultiDatabase ​

Defined in: src/db.ts:125

Type Parameters ​

Type ParameterDefault type
Names extends stringstring

Properties ​

PropertyModifierTypeDefined in
configreadonlySqunConfigsrc/db.ts:127
registryreadonlyConnectionRegistry<Names>src/db.ts:126

Methods ​

atomically() ​
ts
atomically<T>(fn, options?): Promise<T>;

Defined in: src/db.ts:146

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fn(q) => Promise<T>
options?MultiAtomicOptions<Names>
Returns ​

Promise<T>

concurrent() ​
ts
concurrent<T>(...queries): Promise<{ [K in string | number | symbol]: Awaited<T[K]> }>;

Defined in: src/db.ts:154

Type Parameters ​
Type Parameter
T extends readonly Promise<unknown>[]
Parameters ​
ParameterType
...queriesT
Returns ​

Promise<{ [K in string | number | symbol]: Awaited<T[K]> }>

execute() ​
ts
execute(fragment, options?): Promise<{
  rowsAffected: number;
}>;

Defined in: src/db.ts:136

Parameters ​
ParameterType
fragmentSqlFragment
options?ExecuteOptions<Names>
Returns ​

Promise<{ rowsAffected: number; }>

executeBatch() ​
ts
executeBatch(
   fragment, 
   rows, 
   options?): Promise<{
  rowsAffected: number;
}>;

Defined in: src/db.ts:140

Parameters ​
ParameterType
fragmentSqlFragment
rowsreadonly Record<string, unknown>[]
options?ExecuteOptions<Names> & object
Returns ​

Promise<{ rowsAffected: number; }>

prepare() ​
ts
prepare<T, P>(
   fragment, 
   paramNames, 
options?): PreparedQuery<T, P>;

Defined in: src/db.ts:157

Type Parameters ​
Type Parameter
T
P extends Record<string, unknown>
Parameters ​
ParameterType
fragmentSqlFragment
paramNamesreadonly string[]
options?{ connection?: Names; }
options.connection?Names
Returns ​

PreparedQuery<T, P>

query() ​
ts
query<T>(fragment, options?): Promise<T[]>;

Defined in: src/db.ts:132

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
options?QueryOptions<Names>
Returns ​

Promise<T[]>

queryFirst() ​
ts
queryFirst<T>(fragment, options?): Promise<T | null>;

Defined in: src/db.ts:133

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
options?QueryOptions<Names>
Returns ​

Promise<T | null>

queryScalar() ​
ts
queryScalar<T>(fragment, options?): Promise<T>;

Defined in: src/db.ts:135

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
options?QueryOptions<Names>
Returns ​

Promise<T>

querySingle() ​
ts
querySingle<T>(fragment, options?): Promise<T>;

Defined in: src/db.ts:134

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
options?QueryOptions<Names>
Returns ​

Promise<T>

stream() ​
ts
stream<T>(fragment, options?): AsyncIterableIterator<T>;

Defined in: src/db.ts:145

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
options?StreamOptions<Names>
Returns ​

AsyncIterableIterator<T>

transaction() ​
ts
transaction(fn, options?): Promise<void>;

Defined in: src/db.ts:150

Parameters ​
ParameterType
fn(tx) => Promise<void>
options?{ connection?: Names; }
options.connection?Names
Returns ​

Promise<void>

use() ​
ts
use(name): ScopedDb<Names>;

Defined in: src/db.ts:130

Returns a ScopedDb with the named adapter pre-resolved — no connection option needed.

Parameters ​
ParameterType
nameNames
Returns ​

ScopedDb<Names>


MultiDbConfig ​

Defined in: src/connections/types.ts:13

Config for createConnections().

Properties ​

PropertyModifierTypeDefined in
connectionsreadonlyMultiConnectionMapsrc/connections/types.ts:14
defaultreadonlystringsrc/connections/types.ts:15
groups?readonlyRecord<string, GroupConfig>src/connections/types.ts:17
overrides?readonlyRecord<string, Partial<SqunConfig>>src/connections/types.ts:16

OffsetPage ​

Defined in: src/pagination/offset.ts:10

Result of an offset-based paginated query.

Type Parameters ​

Type Parameter
T

Properties ​

PropertyModifierTypeDefined in
hasNextreadonlybooleansrc/pagination/offset.ts:16
hasPrevreadonlybooleansrc/pagination/offset.ts:17
pagereadonlynumbersrc/pagination/offset.ts:13
pageSizereadonlynumbersrc/pagination/offset.ts:14
rowsreadonlyT[]src/pagination/offset.ts:11
totalreadonlynumbersrc/pagination/offset.ts:12
totalPagesreadonlynumbersrc/pagination/offset.ts:15

OffsetPageOptions ​

Defined in: src/pagination/offset.ts:24

Options for offset pagination.

Properties ​

PropertyModifierTypeDescriptionDefined in
pagereadonlynumber1-based page number.src/pagination/offset.ts:26
pageSizereadonlynumber-src/pagination/offset.ts:27

PoolConfig ​

Defined in: src/config/types.ts:25

Properties ​

PropertyModifierTypeDefined in
max?readonlynumbersrc/config/types.ts:27
maxConnectionAgeMs?readonlynumbersrc/config/types.ts:28
maxQueueSize?readonlynumbersrc/config/types.ts:30
maxUseCount?readonlynumbersrc/config/types.ts:29
min?readonlynumbersrc/config/types.ts:26

PoolStatsSnapshot ​

Defined in: src/pool/stats.ts:2

Snapshot of pool metrics at a point in time.

Properties ​

PropertyModifierTypeDefined in
acquiredreadonlynumbersrc/pool/stats.ts:5
avgAcquireMsreadonlynumbersrc/pool/stats.ts:12
avgIdleMsreadonlynumbersrc/pool/stats.ts:13
avgUseMsreadonlynumbersrc/pool/stats.ts:14
idlereadonlynumbersrc/pool/stats.ts:4
maxreadonlynumbersrc/pool/stats.ts:8
minreadonlynumbersrc/pool/stats.ts:7
totalreadonlynumbersrc/pool/stats.ts:3
totalAcquiredreadonlynumbersrc/pool/stats.ts:11
totalCreatedreadonlynumbersrc/pool/stats.ts:9
totalDestroyedreadonlynumbersrc/pool/stats.ts:10
waitingreadonlynumbersrc/pool/stats.ts:6

QueryOptions ​

Defined in: src/connections/types.ts:27

Query options — connection field uses Names union or never for single-db.

Type Parameters ​

Type ParameterDefault type
Names extends stringnever

Properties ​

PropertyModifierTypeDefined in
cache?readonlybooleansrc/connections/types.ts:30
connection?readonly[Names] extends [never] ? never : Namessrc/connections/types.ts:28
strict?readonlybooleansrc/connections/types.ts:31
timeoutMs?readonlynumbersrc/connections/types.ts:29

ScopedDb ​

Defined in: src/connections/types.ts:55

A scoped Database bound to a specific named connection via .use().

Type Parameters ​

Type ParameterDefault type
Names extends stringnever

Properties ​

PropertyModifierTypeDefined in
connectionNamereadonlyNamessrc/connections/types.ts:56

Methods ​

atomically() ​
ts
atomically<T>(fn, options?): Promise<T>;

Defined in: src/connections/types.ts:69

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fn(q) => Promise<T>
options?AtomicBlockOptions
Returns ​

Promise<T>

execute() ​
ts
execute(fragment): Promise<{
  rowsAffected: number;
}>;

Defined in: src/connections/types.ts:62

Parameters ​
ParameterType
fragmentSqlFragment
Returns ​

Promise<{ rowsAffected: number; }>

executeBatch() ​
ts
executeBatch(
   fragment, 
   rows, 
   options?): Promise<{
  rowsAffected: number;
}>;

Defined in: src/connections/types.ts:63

Parameters ​
ParameterType
fragmentSqlFragment
rowsreadonly Record<string, unknown>[]
options?{ strategy?: "prepared-loop" | "copy" | "bulk-load"; }
options.strategy?"prepared-loop" | "copy" | "bulk-load"
Returns ​

Promise<{ rowsAffected: number; }>

prepare() ​
ts
prepare<T, P>(fragment, paramNames): PreparedQuery<T, P>;

Defined in: src/connections/types.ts:71

Type Parameters ​
Type Parameter
T
P extends Record<string, unknown>
Parameters ​
ParameterType
fragmentSqlFragment
paramNamesreadonly string[]
Returns ​

PreparedQuery<T, P>

query() ​
ts
query<T>(fragment): Promise<T[]>;

Defined in: src/connections/types.ts:58

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
Returns ​

Promise<T[]>

queryFirst() ​
ts
queryFirst<T>(fragment): Promise<T | null>;

Defined in: src/connections/types.ts:59

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
Returns ​

Promise<T | null>

queryScalar() ​
ts
queryScalar<T>(fragment): Promise<T>;

Defined in: src/connections/types.ts:61

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
Returns ​

Promise<T>

querySingle() ​
ts
querySingle<T>(fragment): Promise<T>;

Defined in: src/connections/types.ts:60

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
Returns ​

Promise<T>

stream() ​
ts
stream<T>(fragment, batchSize?): AsyncIterableIterator<T>;

Defined in: src/connections/types.ts:68

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
fragmentSqlFragment
batchSize?number
Returns ​

AsyncIterableIterator<T>

transaction() ​
ts
transaction(fn): Promise<void>;

Defined in: src/connections/types.ts:70

Parameters ​
ParameterType
fn(tx) => Promise<void>
Returns ​

Promise<void>


SecurityConfig ​

Defined in: src/config/types.ts:47

Properties ​

PropertyModifierTypeDefined in
detectInjection?readonlybooleansrc/config/types.ts:48
format?readonlyobjectsrc/config/types.ts:52
format.normalizeKeywords?readonlybooleansrc/config/types.ts:53
format.normalizeWhitespace?readonlybooleansrc/config/types.ts:54
strictRaw?readonlybooleansrc/config/types.ts:49
validateSql?readonlybooleansrc/config/types.ts:50
warnOnRawString?readonlybooleansrc/config/types.ts:51

SqlFragment ​

Defined in: src/sql/fragment.ts:9

The return type of the sql tagged template and all composition helpers.

Properties ​

PropertyModifierTypeDefined in
__isSqlreadonlytruesrc/sql/fragment.ts:13
paramsreadonlyreadonly unknown[]src/sql/fragment.ts:11
textreadonlystringsrc/sql/fragment.ts:10
tvpValuesreadonlyreadonly TvpValue[]src/sql/fragment.ts:12

SqunConfig ​

Defined in: src/config/types.ts:71

Properties ​

PropertyModifierTypeDefined in
azure?readonlyAzureAdConfigsrc/config/types.ts:79
cache?readonlyCacheConfigsrc/config/types.ts:76
connection?readonlyConnectionConfigsrc/config/types.ts:73
deadlockRetries?readonlynumbersrc/config/types.ts:83
env?readonlyEnvironmentsrc/config/types.ts:72
errorVerbosity?readonlyErrorVerbositysrc/config/types.ts:80
log?readonlyLogConfigsrc/config/types.ts:78
maskSensitive?readonlybooleansrc/config/types.ts:81
pool?readonlyPoolConfigsrc/config/types.ts:74
security?readonlySecurityConfigsrc/config/types.ts:77
strict?readonlybooleansrc/config/types.ts:82
timeout?readonlyTimeoutConfigsrc/config/types.ts:75
tvpCopyThreshold?readonlynumbersrc/config/types.ts:84

SqunLogger ​

Defined in: src/logging/logger.ts:35

Logger contract — every built-in logger and user-provided logger must satisfy this.

Methods ​

debug() ​
ts
debug(entry): void;

Defined in: src/logging/logger.ts:36

Parameters ​
ParameterType
entryLogEntry
Returns ​

void

error() ​
ts
error(entry): void;

Defined in: src/logging/logger.ts:39

Parameters ​
ParameterType
entryLogEntry
Returns ​

void

fatal() ​
ts
fatal(entry): void;

Defined in: src/logging/logger.ts:40

Parameters ​
ParameterType
entryLogEntry
Returns ​

void

info() ​
ts
info(entry): void;

Defined in: src/logging/logger.ts:37

Parameters ​
ParameterType
entryLogEntry
Returns ​

void

warn() ​
ts
warn(entry): void;

Defined in: src/logging/logger.ts:38

Parameters ​
ParameterType
entryLogEntry
Returns ​

void


StreamOptions ​

Defined in: src/connections/types.ts:39

Type Parameters ​

Type ParameterDefault type
Names extends stringnever

Properties ​

PropertyModifierTypeDefined in
batchSize?readonlynumbersrc/connections/types.ts:42
connection?readonly[Names] extends [never] ? never : Namessrc/connections/types.ts:40
timeoutMs?readonlynumbersrc/connections/types.ts:41

TableDefinition ​

Defined in: src/types/table.ts:7

The shape returned by defineTable() — carries table name and column map at the type level.

Type Parameters ​

Type ParameterDefault type
Name extends stringstring
Columns extends ColumnMapColumnMap

Properties ​

PropertyModifierTypeDefined in
__brandreadonly"TableDefinition"src/types/table.ts:11
columnNamesreadonlyreadonly keyof Columns & string[]src/types/table.ts:14
columnsreadonlyColumnssrc/types/table.ts:13
tableNamereadonlyNamesrc/types/table.ts:12

TimeoutConfig ​

Defined in: src/config/types.ts:33

Properties ​

PropertyModifierTypeDefined in
acquire?readonlynumbersrc/config/types.ts:37
connect?readonlynumbersrc/config/types.ts:36
query?readonlynumbersrc/config/types.ts:34
transaction?readonlynumbersrc/config/types.ts:35

TvpMaterialised ​

Defined in: src/adapters/base.ts:6

Materialised TVP result — replaces a TVP_N sentinel in final SQL.

Properties ​

PropertyModifierTypeDefined in
cleanupreadonly() => Promise<void>src/adapters/base.ts:9
extraParamsreadonlyreadonly unknown[]src/adapters/base.ts:8
sqlExpressionreadonlystringsrc/adapters/base.ts:7

TvpValue ​

Defined in: src/sql/fragment.ts:2

TVP value extracted from a SqlFragment by the sql tag.

Properties ​

PropertyModifierTypeDefined in
__isTvpreadonlytruesrc/sql/fragment.ts:3
rowsreadonlyreadonly Record<string, unknown>[]src/sql/fragment.ts:5
tableTypereadonlyunknownsrc/sql/fragment.ts:4

TypeHandler ​

Defined in: src/core/type-handler.ts:2

Converts values between database driver types and TypeScript types.

Type Parameters ​

Type ParameterDefault type
Tunknown

Methods ​

fromDb() ​
ts
fromDb(raw): T;

Defined in: src/core/type-handler.ts:3

Parameters ​
ParameterType
rawunknown
Returns ​

T

toDb() ​
ts
toDb(value): unknown;

Defined in: src/core/type-handler.ts:4

Parameters ​
ParameterType
valueT
Returns ​

unknown

Type Aliases ​

AdapterType ​

ts
type AdapterType = "sqlite" | "postgres" | "mysql" | "mssql";

Defined in: src/config/types.ts:5


AuthConfig ​

ts
type AuthConfig = 
  | UserPassAuth
  | WindowsAuth
  | WindowsUpnAuth
  | ConnectionStringAuth
  | AzureAdAuth;

Defined in: src/auth/types.ts:32


AuthType ​

ts
type AuthType = 
  | "userpass"
  | "windows"
  | "windows-upn"
  | "connection-string"
  | "azure-ad";

Defined in: src/config/types.ts:7


ColumnMap ​

ts
type ColumnMap = Record<string, ColumnDef>;

Defined in: src/types/table.ts:4

A map of column names to their ColumnDef definitions.


ColumnValue ​

ts
type ColumnValue = string | number | boolean | null | Date | Buffer | unknown[];

Defined in: src/types/primitives.ts:8

The resolved database type for a single column value.


Environment ​

ts
type Environment = "development" | "production" | "test";

Defined in: src/config/types.ts:3


InferInsert ​

ts
type InferInsert<T> = { [K in MutableKeys<T>]: T["columns"][K]["_type"] };

Defined in: src/types/infer.ts:60

Insert shape — primaryKey and readonly columns excluded.

Type Parameters ​

Type Parameter
T extends HasColumnDefs

InferModel ​

ts
type InferModel<T> = { [K in keyof T["columns"] & string]: T["columns"][K]["_type"] };

Defined in: src/types/infer.ts:55

Full row type with nullability — every column included.

Type Parameters ​

Type Parameter
T extends HasColumns

InferReadonlyModel ​

ts
type InferReadonlyModel<T> = { [K in ReadonlyKeys<T>]: T["columns"][K]["_type"] };

Defined in: src/types/infer.ts:70

Only the fields marked readonly.

Type Parameters ​

Type Parameter
T extends HasColumnDefs

InferSelect ​

ts
type InferSelect<T, K> = { [P in K]: T["columns"][P]["_type"] };

Defined in: src/types/infer.ts:75

Narrowed shape — only the selected column keys.

Type Parameters ​

Type Parameter
T extends HasColumns
K extends keyof T["columns"] & string

InferTableType ​

ts
type InferTableType<T> = { [K in keyof T["columns"] & string]: T["columns"][K]["_type"] };

Defined in: src/types/infer.ts:84

TypeScript type from a TableType TVP definition. TableType shares the same column structure as TableDefinition, so this utility extracts the model shape identically.

Type Parameters ​

Type Parameter
T extends HasColumns

InferUpdate ​

ts
type InferUpdate<T> = { [K in MutableKeys<T>]?: T["columns"][K]["_type"] };

Defined in: src/types/infer.ts:65

Update shape — readonly columns excluded, all remaining fields optional.

Type Parameters ​

Type Parameter
T extends HasColumnDefs

IsNullable ​

ts
type IsNullable<T, K> = T["columns"][K] extends ColumnDef<infer _T, true, infer _R> ? true : false;

Defined in: src/types/infer.ts:49

true if column K is nullable, false otherwise.

Type Parameters ​

Type Parameter
T extends HasColumnDefs
K extends keyof T["columns"]

MultiConnectionMap ​

ts
type MultiConnectionMap = Record<string, IDbAdapter>;

Defined in: src/connections/types.ts:10

Map of named connections.


MutableKeys ​

ts
type MutableKeys<T> = { [K in keyof T["columns"] & string]: T["columns"][K] extends ColumnDef<infer _T, infer _N, true> ? never : K }[keyof T["columns"] & string];

Defined in: src/types/infer.ts:42

Union of column names where isReadonly is false (writable).

Type Parameters ​

Type Parameter
T extends HasColumnDefs

NotNullKeys ​

ts
type NotNullKeys<T> = { [K in keyof T["columns"] & string]: T["columns"][K] extends ColumnDef<infer _T, true, infer _R> ? never : K }[keyof T["columns"] & string];

Defined in: src/types/infer.ts:28

Union of column names where isNullable is false.

Type Parameters ​

Type Parameter
T extends HasColumnDefs

NullableKeys ​

ts
type NullableKeys<T> = { [K in keyof T["columns"] & string]: T["columns"][K] extends ColumnDef<infer _T, true, infer _R> ? K : never }[keyof T["columns"] & string];

Defined in: src/types/infer.ts:21

Union of column names where isNullable is true.

Type Parameters ​

Type Parameter
T extends HasColumnDefs

Params ​

ts
type Params = Record<string, unknown>;

Defined in: src/types/primitives.ts:5

A plain parameter object passed to executeBatch rows.


ReadonlyKeys ​

ts
type ReadonlyKeys<T> = { [K in keyof T["columns"] & string]: T["columns"][K] extends ColumnDef<infer _T, infer _N, true> ? K : never }[keyof T["columns"] & string];

Defined in: src/types/infer.ts:35

Union of column names where isReadonly is true.

Type Parameters ​

Type Parameter
T extends HasColumnDefs

Row ​

ts
type Row = Record<string, unknown>;

Defined in: src/types/primitives.ts:2

A raw row returned by the database driver before any mapping.


RowMapper ​

ts
type RowMapper<T> = (row) => T;

Defined in: src/core/type-mapper.ts:8

A compiled function that maps a raw Row to a typed T.

Type Parameters ​

Type Parameter
T

Parameters ​

ParameterType
rowRow

Returns ​

T


Severity ​

ts
type Severity = "critical" | "high" | "medium" | "low";

Defined in: src/sql/injection-detector.ts:3


TenantResolver ​

ts
type TenantResolver<Names> = (tenantId) => Names;

Defined in: src/connections/tenant-resolver.ts:4

A function that resolves a tenant ID to a connection name.

Type Parameters ​

Type ParameterDefault type
Names extends stringstring

Parameters ​

ParameterType
tenantIdstring

Returns ​

Names

Variables ​

col ​

ts
const col: object;

Defined in: src/types/col.ts:75

Column builder entry points — one per database type.

Type Declaration ​

NameTypeDescriptionDefined in
array()<T>() => ColumnBuilder<T[], false, false> & ColumnDef<T[], false, false>-src/types/col.ts:92
bigint()() => ColumnBuilder<number, false, false> & ColumnDef<number, false, false>-src/types/col.ts:77
blob()() => ColumnBuilder<Buffer<ArrayBufferLike>, false, false> & ColumnDef<Buffer<ArrayBufferLike>, false, false>-src/types/col.ts:90
boolean()() => ColumnBuilder<boolean, false, false> & ColumnDef<boolean, false, false>-src/types/col.ts:81
char()(len) => ColumnBuilder<string, false, false> & ColumnDef<string, false, false>-src/types/col.ts:85
date()() => ColumnBuilder<Date, false, false> & ColumnDef<Date, false, false>-src/types/col.ts:87
datetime()() => ColumnBuilder<Date, false, false> & ColumnDef<Date, false, false>-src/types/col.ts:86
decimal()(p?, _s?) => ColumnBuilder<number, false, false> & ColumnDef<number, false, false>-src/types/col.ts:80
float()() => ColumnBuilder<number, false, false> & ColumnDef<number, false, false>-src/types/col.ts:79
int()() => ColumnBuilder<number, false, false> & ColumnDef<number, false, false>-src/types/col.ts:76
json()<T>() => ColumnBuilder<T, false, false> & ColumnDef<T, false, false>-src/types/col.ts:91
number()() => ColumnBuilder<number, false, false> & ColumnDef<number, false, false>Shorthand: TypeScript number → FLOAT (IEEE 754 double, closest to JS number semantics).src/types/col.ts:96
nvarchar()(len) => ColumnBuilder<string, false, false> & ColumnDef<string, false, false>-src/types/col.ts:83
smallint()() => ColumnBuilder<number, false, false> & ColumnDef<number, false, false>-src/types/col.ts:78
string()(len) => ColumnBuilder<string, false, false> & ColumnDef<string, false, false>Shorthand: TypeScript string → NVARCHAR. Defaults to MAX length.src/types/col.ts:94
text()() => ColumnBuilder<string, false, false> & ColumnDef<string, false, false>-src/types/col.ts:82
time()() => ColumnBuilder<string, false, false> & ColumnDef<string, false, false>-src/types/col.ts:88
uuid()() => ColumnBuilder<string, false, false> & ColumnDef<string, false, false>-src/types/col.ts:89
varchar()(len) => ColumnBuilder<string, false, false> & ColumnDef<string, false, false>-src/types/col.ts:84

consoleLogger ​

ts
const consoleLogger: SqunLogger;

Defined in: src/logging/console-logger.ts:71

Development logger — colorised, human-readable, pretty-printed.


jsonLogger ​

ts
const jsonLogger: SqunLogger;

Defined in: src/logging/json-logger.ts:56

Production logger — structured JSON, one object per line, pino-compatible.


noopLogger ​

ts
const noopLogger: SqunLogger;

Defined in: src/logging/noop-logger.ts:6

Silent logger — does nothing. Used in test environments.


SQUN_ENV_VARS ​

ts
const SQUN_ENV_VARS: object;

Defined in: src/config/env-vars.ts:5

Every SQUN_* environment variable name used by the library. No magic strings — all env var access goes through this constant.

Type Declaration ​

NameTypeDefault valueDefined in
AZURE_CLIENT_ID"SQUN_AZURE_CLIENT_ID""SQUN_AZURE_CLIENT_ID"src/config/env-vars.ts:43
AZURE_CLIENT_SECRET"SQUN_AZURE_CLIENT_SECRET""SQUN_AZURE_CLIENT_SECRET"src/config/env-vars.ts:44
AZURE_MANAGED_IDENTITY"SQUN_AZURE_MANAGED_IDENTITY""SQUN_AZURE_MANAGED_IDENTITY"src/config/env-vars.ts:45
AZURE_TENANT_ID"SQUN_AZURE_TENANT_ID""SQUN_AZURE_TENANT_ID"src/config/env-vars.ts:42
CACHE_MAX_AGE_MS"SQUN_CACHE_MAX_AGE_MS""SQUN_CACHE_MAX_AGE_MS"src/config/env-vars.ts:64
CACHE_MAX_SIZE"SQUN_CACHE_MAX_SIZE""SQUN_CACHE_MAX_SIZE"src/config/env-vars.ts:62
CACHE_REAPER_MS"SQUN_CACHE_REAPER_MS""SQUN_CACHE_REAPER_MS"src/config/env-vars.ts:65
CACHE_TTL_MS"SQUN_CACHE_TTL_MS""SQUN_CACHE_TTL_MS"src/config/env-vars.ts:63
CONN_PREFIX"SQUN_CONN_""SQUN_CONN_"src/config/env-vars.ts:69
DEFAULT_CONNECTION"SQUN_DEFAULT_CONNECTION""SQUN_DEFAULT_CONNECTION"src/config/env-vars.ts:68
ENV"SQUN_ENV""SQUN_ENV"src/config/env-vars.ts:7
LOG_LEVEL"SQUN_LOG_LEVEL""SQUN_LOG_LEVEL"src/config/env-vars.ts:58
LOG_SLOW_QUERY_MS"SQUN_LOG_SLOW_QUERY_MS""SQUN_LOG_SLOW_QUERY_MS"src/config/env-vars.ts:59
MSSQL_AUTH_TYPE"SQUN_MSSQL_AUTH_TYPE""SQUN_MSSQL_AUTH_TYPE"src/config/env-vars.ts:34
MSSQL_DATABASE"SQUN_MSSQL_DATABASE""SQUN_MSSQL_DATABASE"src/config/env-vars.ts:31
MSSQL_DOMAIN"SQUN_MSSQL_DOMAIN""SQUN_MSSQL_DOMAIN"src/config/env-vars.ts:35
MSSQL_HOST"SQUN_MSSQL_HOST""SQUN_MSSQL_HOST"src/config/env-vars.ts:29
MSSQL_PASSWORD"SQUN_MSSQL_PASSWORD""SQUN_MSSQL_PASSWORD"src/config/env-vars.ts:33
MSSQL_PORT"SQUN_MSSQL_PORT""SQUN_MSSQL_PORT"src/config/env-vars.ts:30
MSSQL_UPN"SQUN_MSSQL_UPN""SQUN_MSSQL_UPN"src/config/env-vars.ts:36
MSSQL_URL"SQUN_MSSQL_URL""SQUN_MSSQL_URL"src/config/env-vars.ts:28
MSSQL_USER"SQUN_MSSQL_USER""SQUN_MSSQL_USER"src/config/env-vars.ts:32
MYSQL_DATABASE"SQUN_MYSQL_DATABASE""SQUN_MYSQL_DATABASE"src/config/env-vars.ts:23
MYSQL_HOST"SQUN_MYSQL_HOST""SQUN_MYSQL_HOST"src/config/env-vars.ts:21
MYSQL_PASSWORD"SQUN_MYSQL_PASSWORD""SQUN_MYSQL_PASSWORD"src/config/env-vars.ts:25
MYSQL_PORT"SQUN_MYSQL_PORT""SQUN_MYSQL_PORT"src/config/env-vars.ts:22
MYSQL_URL"SQUN_MYSQL_URL""SQUN_MYSQL_URL"src/config/env-vars.ts:20
MYSQL_USER"SQUN_MYSQL_USER""SQUN_MYSQL_USER"src/config/env-vars.ts:24
PG_DATABASE"SQUN_PG_DATABASE""SQUN_PG_DATABASE"src/config/env-vars.ts:13
PG_HOST"SQUN_PG_HOST""SQUN_PG_HOST"src/config/env-vars.ts:11
PG_PASSWORD"SQUN_PG_PASSWORD""SQUN_PG_PASSWORD"src/config/env-vars.ts:15
PG_PORT"SQUN_PG_PORT""SQUN_PG_PORT"src/config/env-vars.ts:12
PG_SSL"SQUN_PG_SSL""SQUN_PG_SSL"src/config/env-vars.ts:16
PG_TVP_COPY_THRESHOLD"SQUN_PG_TVP_COPY_THRESHOLD""SQUN_PG_TVP_COPY_THRESHOLD"src/config/env-vars.ts:17
PG_URL"SQUN_PG_URL""SQUN_PG_URL"src/config/env-vars.ts:10
PG_USER"SQUN_PG_USER""SQUN_PG_USER"src/config/env-vars.ts:14
POOL_MAX"SQUN_POOL_MAX""SQUN_POOL_MAX"src/config/env-vars.ts:49
POOL_MIN"SQUN_POOL_MIN""SQUN_POOL_MIN"src/config/env-vars.ts:48
SQLITE_FILE"SQUN_SQLITE_FILE""SQUN_SQLITE_FILE"src/config/env-vars.ts:39
TIMEOUT_ACQUIRE"SQUN_TIMEOUT_ACQUIRE""SQUN_TIMEOUT_ACQUIRE"src/config/env-vars.ts:55
TIMEOUT_CONNECT"SQUN_TIMEOUT_CONNECT""SQUN_TIMEOUT_CONNECT"src/config/env-vars.ts:54
TIMEOUT_QUERY"SQUN_TIMEOUT_QUERY""SQUN_TIMEOUT_QUERY"src/config/env-vars.ts:52
TIMEOUT_TX"SQUN_TIMEOUT_TX""SQUN_TIMEOUT_TX"src/config/env-vars.ts:53

Functions ​

assertWritable() ​

ts
function assertWritable(
   connection, 
   operation, 
   sql?): boolean;

Defined in: src/readonly/guard.ts:19

Throws ReadonlyViolationError if a write operation is attempted on a readonly connection. Called before any SQL is sent to the adapter.

In "strict" mode (default): throws immediately. In "warn" mode: returns false to signal a warning should be logged, but allows the write.

Parameters ​

ParameterType
connectionReadonlyConnection
operationstring
sql?string

Returns ​

boolean


compileMapper() ​

ts
function compileMapper<T>(
   schema, 
   registry?, 
strict?): RowMapper<T>;

Defined in: src/core/type-mapper.ts:30

Compiles a mapper function from a table schema at defineTable() time. All branching is resolved once during compilation — per-row mapping has zero runtime type inspection.

In strict mode (default), throws MappingError for null on notNull columns and for unknown columns in the result. In lenient mode, warns and continues.

Type Parameters ​

Type Parameter
T

Parameters ​

ParameterTypeDefault value
schemaSchemaLikeundefined
registryTypeHandlerRegistry...
strictbooleantrue

Returns ​

RowMapper<T>


concurrent() ​

ts
function concurrent<T>(...queries): Promise<T>;

Defined in: src/async/concurrent.ts:6

Runs multiple promises concurrently and returns a typed tuple of results. Wraps Promise.all with correct TypeScript tuple inference so callers get typed results per position rather than (T1 | T2 | ...)[].

Type Parameters ​

Type Parameter
T extends readonly unknown[]

Parameters ​

ParameterType
...queries{ [K in string | number | symbol]: Promise<T[K]> }

Returns ​

Promise<T>


createCachedDb() ​

ts
function createCachedDb(adapter, options): CachedDb;

Defined in: src/cache/cached-db.ts:236

Wraps an existing IDbAdapter with a result cache.

ts
const db = createCachedDb(adapter, { ttl: 5_000, maxSize: 200 });
// query() results are now cached for 5 seconds
db.cache.invalidate();  // clear all
db.cache.stats();       // { hits, misses, size }

Parameters ​

ParameterType
adapterIDbAdapter
optionsCacheOptions

Returns ​

CachedDb


createConnection() ​

ts
function createConnection(adapter, userConfig?): Database;

Defined in: src/db.ts:56

Single connection entry point. Calls validateProductionConfig() synchronously — app never starts in invalid state.

Parameters ​

ParameterType
adapterIDbAdapter
userConfigPartial<SqunConfig>

Returns ​

Database


createConnections() ​

ts
function createConnections<Config, Names>(multiConfig): MultiDatabase<Names>;

Defined in: src/db.ts:209

Multi-connection entry point. Infers Names = keyof Config["connections"] & string. Validates all connections together at startup.

Type Parameters ​

Type ParameterDefault type
Config extends MultiDbConfig-
Names extends stringkeyof Config["connections"] & string

Parameters ​

ParameterType
multiConfigConfig

Returns ​

MultiDatabase<Names>


createRouter() ​

ts
function createRouter(config): RouterResult;

Defined in: src/readonly/router.ts:28

Convenience wrapper — one writable primary, one read replica. Returns the config shape that createConnections() expects. Not a separate code path — just builds the standard multi-connection config.

Parameters ​

ParameterType
configRouterConfig

Returns ​

RouterResult


cursorPage() ​

ts
function cursorPage<T>(
   adapter, 
   fragment, 
options): Promise<CursorPage<T>>;

Defined in: src/pagination/cursor.ts:97

Executes a cursor-paginated query against adapter.

Decodes the incoming cursor (if any), appends a WHERE cursorColumn > $n clause (or < for desc), adds ORDER BY cursorColumn LIMIT limit+1, and trims the extra row to signal hasNext.

Returns a CursorPage<T> with nextCursor / prevCursor set when applicable.

Type Parameters ​

Type Parameter
T

Parameters ​

ParameterType
adapterIDbAdapter
fragmentSqlFragment
optionsCursorPageOptions

Returns ​

Promise<CursorPage<T>>


defineMapper() ​

ts
function defineMapper<T>(
   cls, 
   schema, 
factoryOrOptions?): MapperFn<T>;

Defined in: src/mapping/define-mapper.ts:26

Registers a class mapper globally. Any subsequent queryAs(cls, ...) resolves it.

  • No factory argument + strategy "property" (default): property injection
  • No factory argument + strategy "constructor": constructor args in column order
  • No factory argument + strategy "static": calls cls.fromDb(row)
  • Factory function provided: uses it directly

Type Parameters ​

Type Parameter
T

Parameters ​

ParameterType
clsConstructor<T>
schemaSchemaLike
factoryOrOptions?DefineMapperOptions | ((row) => T)

Returns ​

MapperFn<T>


defineTable() ​

ts
function defineTable<Name, Columns>(tableName, columns): TableDefinition<Name, Columns>;

Defined in: src/types/table.ts:24

Defines a table schema for use with Squn's type system.

The returned definition is used by InferModel, InferInsert, InferUpdate, and all query methods that accept a table reference. It carries the table name and the full column map at the type level.

Type Parameters ​

Type Parameter
Name extends string
Columns extends ColumnMap

Parameters ​

ParameterType
tableNameName
columnsColumns

Returns ​

TableDefinition<Name, Columns>


deleteRow() ​

ts
function deleteRow(
   adapter, 
   tableName, 
   pkColumn, 
   pkValue): Promise<{
  rowsAffected: number;
}>;

Defined in: src/api/execute.ts:65

Typed delete — removes a single row by primary key.

Parameters ​

ParameterType
adapterIDbAdapter
tableNamestring
pkColumnstring
pkValueunknown

Returns ​

Promise<{ rowsAffected: number; }>


detectInjection() ​

ts
function detectInjection(text): DetectionResult;

Defined in: src/sql/injection-detector.ts:52

Checks text against all SQUN_REGEX injection patterns. Returns the first match found (ordered by severity: critical → low).

Parameters ​

ParameterType
textstring

Returns ​

DetectionResult


Email() ​

ts
function Email(_target, context): void;

Defined in: src/mapping/decorators/validate.ts:33

Validates that a string property matches an email format.

Parameters ​

ParameterType
_targetundefined
contextClassFieldDecoratorContext

Returns ​

void


Entity() ​

ts
function Entity(schema): <T>(target, _context) => T;

Defined in: src/mapping/decorators/entity.ts:15

@Entity(schema) decorator — registers the class with propertyInjection strategy. Equivalent to defineMapper(cls, schema) with strategy: "property". Requires TC39 stage 3 decorators (TypeScript 5.0+ with target: "ESNext").

Parameters ​

ParameterType
schemaSchemaLike

Returns ​

<T>(target, _context) => T


execProc() ​

ts
function execProc<T, OutputParams>(
   adapter, 
   procName, 
   params?): Promise<{
  output: OutputParams;
  rows: T[];
}>;

Defined in: src/api/proc.ts:18

Stored procedure with OUTPUT params.

Type Parameters ​

Type Parameter
T
OutputParams extends Record<string, unknown>

Parameters ​

ParameterType
adapterIDbAdapter
procNamestring
params?Record<string, unknown>

Returns ​

Promise<{ output: OutputParams; rows: T[]; }>


execute() ​

ts
function execute(adapter, fragment): Promise<{
  rowsAffected: number;
}>;

Defined in: src/api/execute.ts:7

Returns { rowsAffected }.

Parameters ​

ParameterType
adapterIDbAdapter
fragmentSqlFragment

Returns ​

Promise<{ rowsAffected: number; }>


executeBatch() ​

ts
function executeBatch(
   adapter, 
   fragment, 
   rows, 
   options?): Promise<{
  rowsAffected: number;
}>;

Defined in: src/api/execute.ts:15

Single prepared statement executed once per row via adapter-native batch.

Parameters ​

ParameterType
adapterIDbAdapter
fragmentSqlFragment
rowsreadonly Record<string, unknown>[]
options?{ strategy?: "prepared-loop" | "copy" | "bulk-load"; }
options.strategy?"prepared-loop" | "copy" | "bulk-load"

Returns ​

Promise<{ rowsAffected: number; }>


formatSql() ​

ts
function formatSql(sql): string;

Defined in: src/sql/formatter.ts:72

Normalises SQL for cache keys and log output.

  • Collapses whitespace to single spaces
  • Uppercases SQL keywords
  • Trims leading/trailing whitespace

Parameters ​

ParameterType
sqlstring

Returns ​

string


forTenant() ​

ts
function forTenant<Names>(
   registry, 
   resolver, 
   tenantId): Names;

Defined in: src/connections/tenant-resolver.ts:10

Resolves a tenant ID to an adapter via the registry. The resolver function is called per-query — it can use caching internally.

Type Parameters ​

Type Parameter
Names extends string

Parameters ​

ParameterType
registryConnectionRegistry<Names>
resolverTenantResolver<Names>
tenantIdstring

Returns ​

Names


getValidationRules() ​

ts
function getValidationRules(target): Map<string, ValidationRule[]>;

Defined in: src/mapping/decorators/validate.ts:69

Retrieves all validation rules for a class instance's prototype.

Parameters ​

ParameterType
targetobject

Returns ​

Map<string, ValidationRule[]>


insert() ​

ts
function insert(
   adapter, 
   tableName, 
   columnNames, 
   data): Promise<{
  rowsAffected: number;
}>;

Defined in: src/api/execute.ts:32

Typed insert — data checked against InferInsert at the type level.

Parameters ​

ParameterType
adapterIDbAdapter
tableNamestring
columnNamesreadonly string[]
dataRecord<string, unknown>

Returns ​

Promise<{ rowsAffected: number; }>


isDeadlock() ​

ts
function isDeadlock(err, adapterType): boolean;

Defined in: src/transaction/deadlock.ts:10

Detects whether an error is a deadlock for the given adapter. MSSQL: error 1205, PostgreSQL: code 40P01, MySQL: 1213, SQLite: SQLITE_BUSY.

Parameters ​

ParameterType
errSqunError
adapterTypeAdapterType

Returns ​

boolean


isSqlFragment() ​

ts
function isSqlFragment(x): x is SqlFragment;

Defined in: src/sql/fragment.ts:17

Type guard for SqlFragment.

Parameters ​

ParameterType
xunknown

Returns ​

x is SqlFragment


isTvpValue() ​

ts
function isTvpValue(x): x is TvpValue;

Defined in: src/sql/fragment.ts:22

Type guard for TvpValue.

Parameters ​

ParameterType
xunknown

Returns ​

x is TvpValue


maskConnectionString() ​

ts
function maskConnectionString(s): string;

Defined in: src/auth/mask.ts:11

Strips passwords from both URL format and key=value connection strings. Passwords must never appear in any log output.

Parameters ​

ParameterType
sstring

Returns ​

string


maskUrl() ​

ts
function maskUrl(url): string;

Defined in: src/config/url-validator.ts:35

Masks the password portion of a connection URL for safe logging. postgresql://user:s3cret@host → postgresql://user:****@host

Parameters ​

ParameterType
urlstring

Returns ​

string


Max() ​

ts
function Max(value): (_target, context) => void;

Defined in: src/mapping/decorators/validate.ts:56

Validates that a numeric property is <= the specified maximum.

Parameters ​

ParameterType
valuenumber

Returns ​

(_target, context) => void


Min() ​

ts
function Min(value): (_target, context) => void;

Defined in: src/mapping/decorators/validate.ts:43

Validates that a numeric property is >= the specified minimum.

Parameters ​

ParameterType
valuenumber

Returns ​

(_target, context) => void


NotNull() ​

ts
function NotNull(_target, context): void;

Defined in: src/mapping/decorators/validate.ts:23

Marks a property as required — validates that the value is not null or undefined.

Parameters ​

ParameterType
_targetundefined
contextClassFieldDecoratorContext

Returns ​

void


offsetPage() ​

ts
function offsetPage<T>(
   adapter, 
   fragment, 
options): Promise<OffsetPage<T>>;

Defined in: src/pagination/offset.ts:38

Executes an offset-paginated query against adapter.

Appends LIMIT $n OFFSET $m to fragment, then runs a parallel SELECT COUNT(*) wrapping the same fragment as a subquery. Returns a fully-populated OffsetPage<T>.

Type Parameters ​

Type Parameter
T

Parameters ​

ParameterType
adapterIDbAdapter
fragmentSqlFragment
optionsOffsetPageOptions

Returns ​

Promise<OffsetPage<T>>


prepare() ​

ts
function prepare<T, P>(
   adapter, 
   fragment, 
paramNames): PreparedQuery<T, P>;

Defined in: src/api/prepared.ts:159

Creates a PreparedQuery. Call this once at startup or module scope.

The fragment's params are inspected to extract the param name order. At call time, only the ParamBuffer is filled — no parsing, no validation, no hashing, no array spreading.

Type Parameters ​

Type ParameterDefault type
T-
P extends Record<string, unknown>Record<string, never>

Parameters ​

ParameterType
adapterIDbAdapter
fragmentSqlFragment
paramNamesreadonly string[]

Returns ​

PreparedQuery<T, P>

Example ​

ts
const findUserById = prepare<User, { id: number }>(
  adapter,
  sql`SELECT * FROM users WHERE id = ${0}`,  // placeholder value, not used
  ["id"],
);

// Hot path — only param binding + adapter call
const user = await findUserById.first({ id: 42 });

query() ​

ts
function query<T>(adapter, fragment): Promise<T[]>;

Defined in: src/api/query.ts:10

Returns T[] — zero or more rows.

Type Parameters ​

Type Parameter
T

Parameters ​

ParameterType
adapterIDbAdapter
fragmentSqlFragment

Returns ​

Promise<T[]>


queryBuilder() ​

Call Signature ​

ts
function queryBuilder(tableName): QueryBuilder<never>;

Defined in: src/api/query-builder.ts:180

Creates a query builder for a table.

Parameters ​
ParameterType
tableNamestring
Returns ​

QueryBuilder<never>

Call Signature ​

ts
function queryBuilder(schema): QueryBuilder<never>;

Defined in: src/api/query-builder.ts:181

Creates a query builder for a table.

Parameters ​
ParameterType
schema{ tableName: string; }
schema.tableNamestring
Returns ​

QueryBuilder<never>


queryFirst() ​

ts
function queryFirst<T>(adapter, fragment): Promise<T | null>;

Defined in: src/api/query.ts:16

Returns T | null — first row or null.

Type Parameters ​

Type Parameter
T

Parameters ​

ParameterType
adapterIDbAdapter
fragmentSqlFragment

Returns ​

Promise<T | null>


queryMultiple() ​

ts
function queryMultiple(adapter, fragment): Promise<Row[][]>;

Defined in: src/api/query.ts:82

Returns multiple result sets.

Parameters ​

ParameterType
adapterIDbAdapter
fragmentSqlFragment

Returns ​

Promise<Row[][]>


queryProc() ​

ts
function queryProc<T>(
   adapter, 
   procName, 
params?): Promise<T[]>;

Defined in: src/api/proc.ts:4

Stored procedure → T[].

Type Parameters ​

Type Parameter
T

Parameters ​

ParameterType
adapterIDbAdapter
procNamestring
params?Record<string, unknown>

Returns ​

Promise<T[]>


queryScalar() ​

ts
function queryScalar<T>(adapter, fragment): Promise<T>;

Defined in: src/api/query.ts:61

Returns T — first column of first row.

Type Parameters ​

Type Parameter
T

Parameters ​

ParameterType
adapterIDbAdapter
fragmentSqlFragment

Returns ​

Promise<T>


querySingle() ​

Call Signature ​

ts
function querySingle<T>(
   adapter, 
   fragment, 
strict?): Promise<T>;

Defined in: src/api/query.ts:23

Returns T — exactly one row, throws on 0 or >1.

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
adapterIDbAdapter
fragmentSqlFragment
strict?true
Returns ​

Promise<T>

Call Signature ​

ts
function querySingle<T>(
   adapter, 
   fragment, 
strict): Promise<T | null>;

Defined in: src/api/query.ts:29

Returns T | null — first row or null (no error on empty result). Throws on >1 row.

Type Parameters ​
Type Parameter
T
Parameters ​
ParameterType
adapterIDbAdapter
fragmentSqlFragment
strictfalse
Returns ​

Promise<T | null>


Readonly() ​

ts
function Readonly(): <T>(target, _context) => T;

Defined in: src/readonly/freeze.ts:8

@Readonly() class decorator — freezes instances after construction. The returned instance is a Readonly<T> at the TypeScript level and Object.freeze()'d at runtime.

Requires TC39 stage 3 decorators (TypeScript 5.0+ with target: "ESNext").

Returns ​

<T>(target, _context) => T


resolveConfig() ​

ts
function resolveConfig(userConfig, env?): SqunConfig;

Defined in: src/config/resolve.ts:63

Resolves the final SqunConfig by detecting the environment and deep-merging the user's partial config on top of the matching preset.

Parameters ​

ParameterType
userConfigPartial<SqunConfig>
env?string

Returns ​

SqunConfig


resolveConnection() ​

ts
function resolveConnection<Names>(
   registry, 
   optionsConnection?, 
   useScope?, 
   builderConnection?): IDbAdapter;

Defined in: src/connections/resolve-connection.ts:10

Resolves the connection to use following the full precedence chain: options.connection → .use() scope → queryBuilder.connection() → default.

Throws ConnectionError(CONN_UNKNOWN) if the name is not found — handled by registry.get().

Type Parameters ​

Type Parameter
Names extends string

Parameters ​

ParameterType
registryConnectionRegistry<Names>
optionsConnection?Names
useScope?Names
builderConnection?Names

Returns ​

IDbAdapter


resolveTimeout() ​

ts
function resolveTimeout(
   callTimeout, 
   txClock, 
   globalConfig, 
   operation): number | null;

Defined in: src/async/timeout.ts:20

Resolves the effective timeout for a single database operation.

Precedence chain (PRD 12.2): per-call option → transaction budget remaining → operation global → null

The transaction budget acts as a hard ceiling — even if the call-site requests a longer timeout, it is capped to whatever budget the enclosing transaction has remaining.

Parameters ​

ParameterType
callTimeoutnumber | null | undefined
txClockClock | undefined
globalConfigTimeoutConfig
operationkeyof TimeoutConfig

Returns ​

number | null


retryWithDeadlockBackoff() ​

ts
function retryWithDeadlockBackoff<T>(
   fn, 
   adapterType, 
options): Promise<T>;

Defined in: src/transaction/deadlock.ts:37

Retries a function on deadlock with exponential backoff + random jitter.

Type Parameters ​

Type Parameter
T

Parameters ​

ParameterType
fn() => Promise<T>
adapterTypeAdapterType
optionsRetryOptions

Returns ​

Promise<T>


rollbackMigration() ​

ts
function rollbackMigration(
   adapter, 
   migrationId, 
   migrations, 
options?): Promise<void>;

Defined in: src/migrations/runner.ts:135

Rolls back a single migration by ID.

  • Runs the migration's down SQL inside a transaction.
  • Removes the record from the tracking table.
  • Throws QueryError if the migration has no down SQL or is not recorded as applied.

Parameters ​

ParameterType
adapterIDbAdapter
migrationIdstring
migrationsreadonly Migration[]
options?MigrationOptions

Returns ​

Promise<void>


runAtomically() ​

ts
function runAtomically<T>(
   adapter, 
   fn, 
options?): Promise<T>;

Defined in: src/transaction/atomic.ts:50

Runs a function inside a BEGIN/COMMIT block. Nesting is forbidden — throws AtomicNestingError. retryOnError only retries ConnectionError, never QueryError or MappingError.

Type Parameters ​

Type Parameter
T

Parameters ​

ParameterType
adapterIDbAdapter
fn(executor) => Promise<T>
optionsAtomicBlockOptions

Returns ​

Promise<T>


runMigrations() ​

ts
function runMigrations(
   adapter, 
   migrations, 
options?): Promise<MigrationResult>;

Defined in: src/migrations/runner.ts:61

Applies all pending migrations in the provided list order.

  • Creates the tracking table on first run (CREATE TABLE IF NOT EXISTS).
  • Skips migrations whose IDs are already recorded in the tracking table.
  • Runs each pending migration's up SQL inside a transaction.
  • Records each applied migration with an ISO timestamp.

Parameters ​

ParameterType
adapterIDbAdapter
migrationsreadonly Migration[]
options?MigrationOptions

Returns ​

Promise<MigrationResult>


splitAndMap() ​

ts
function splitAndMap(
   rows, 
   splitOn, 
   mappers): unknown[];

Defined in: src/mapping/nested-mapper.ts:9

Splits JOIN result rows at splitOn column boundaries and maps into nested objects. Deduplicates by the first column (primary key) of each segment. Left join sides become null when the splitOn column value is null.

Parameters ​

ParameterType
rowsRow[]
splitOnstring[]
mappersMapperFn<unknown>[]

Returns ​

unknown[]


sql() ​

ts
function sql(strings, ...values): SqlFragment;

Defined in: src/sql/tag.ts:23

Tagged template literal for SQL. Three interpolation paths:

  1. Scalar → appended to params[], placeholder inserted in text
  2. Nested SqlFragment → text merged inline, params spliced in order, placeholders renumbered
  3. TvpValue → extracted to tvpValues[], TVP_N sentinel in text

Parameters ​

ParameterType
stringsTemplateStringsArray
...valuesunknown[]

Returns ​

SqlFragment


sqlIdentifier() ​

ts
function sqlIdentifier(name): SqlFragment;

Defined in: src/sql/helpers.ts:103

Validates and double-quotes a SQL identifier. Max 128 chars.

Parameters ​

ParameterType
namestring

Returns ​

SqlFragment


sqlIf() ​

ts
function sqlIf(condition, fragment): SqlFragment;

Defined in: src/sql/helpers.ts:8

Includes fragment only if condition is true. Returns empty fragment otherwise.

Parameters ​

ParameterType
conditionboolean
fragmentSqlFragment

Returns ​

SqlFragment


sqlJoin() ​

ts
function sqlJoin(fragments, separator?): SqlFragment;

Defined in: src/sql/helpers.ts:14

Joins multiple fragments with a separator string.

Parameters ​

ParameterTypeDefault value
fragmentsreadonly SqlFragment[]undefined
separatorstring", "

Returns ​

SqlFragment


sqlQualifiedIdentifier() ​

ts
function sqlQualifiedIdentifier(schema, table): SqlFragment;

Defined in: src/sql/helpers.ts:128

Validates and double-quotes a qualified identifier: "schema"."table".

Parameters ​

ParameterType
schemastring
tablestring

Returns ​

SqlFragment


sqlRaw() ​

ts
function sqlRaw(text): SqlFragment;

Defined in: src/sql/helpers.ts:42

Raw SQL escape hatch. Injects text directly — no parameterization. Throws SecurityError on critical/high injection patterns.

Parameters ​

ParameterType
textstring

Returns ​

SqlFragment


stream() ​

ts
function stream<T>(
   adapter, 
   fragment, 
batchSize?): AsyncIterableIterator<T>;

Defined in: src/api/query.ts:87

AsyncIterableIterator<T> — streaming cursor with configurable batch size.

Type Parameters ​

Type Parameter
T

Parameters ​

ParameterTypeDefault value
adapterIDbAdapterundefined
fragmentSqlFragmentundefined
batchSizenumber100

Returns ​

AsyncIterableIterator<T>


tvp() ​

ts
function tvp<T>(tableType, rows): TvpValue;

Defined in: src/core/tvp/tvp-builder.ts:11

Builds a TvpValue from a TableType and rows. Validates every row has exactly the columns defined in tableType.schema. Throws ValidationError(TVP_SCHEMA_MISMATCH) on column mismatch.

Type Parameters ​

Type Parameter
T extends TableType<Record<string, string>>

Parameters ​

ParameterType
tableTypeT
rowsInferTableType<T>[]

Returns ​

TvpValue


update() ​

ts
function update(
   adapter, 
   tableName, 
   data, 
   pkColumn, 
   pkValue): Promise<{
  rowsAffected: number;
}>;

Defined in: src/api/execute.ts:46

Typed update — data checked against InferUpdate at the type level.

Parameters ​

ParameterType
adapterIDbAdapter
tableNamestring
dataRecord<string, unknown>
pkColumnstring
pkValueunknown

Returns ​

Promise<{ rowsAffected: number; }>


upsert() ​

ts
function upsert(
   adapter, 
   tableName, 
   data, 
   conflictColumns, 
   updateColumns?): Promise<{
  rowsAffected: number;
}>;

Defined in: src/api/execute.ts:87

Typed upsert — inserts or updates depending on conflict.

  • PostgreSQL: INSERT … ON CONFLICT (…) DO UPDATE SET …
  • MySQL: INSERT … ON DUPLICATE KEY UPDATE …
  • SQLite: INSERT OR REPLACE INTO …
  • MSSQL: MERGE INTO … USING (VALUES …) AS src ON … WHEN MATCHED THEN UPDATE … WHEN NOT MATCHED THEN INSERT …

Parameters ​

ParameterTypeDescription
adapterIDbAdapter-
tableNamestring-
dataRecord<string, unknown>-
conflictColumnsreadonly string[]Columns that uniquely identify the row (used by PG/MSSQL).
updateColumns?readonly string[]Columns to overwrite on conflict — defaults to all non-conflict columns.

Returns ​

Promise<{ rowsAffected: number; }>


validateAuth() ​

ts
function validateAuth(config): void;

Defined in: src/auth/validate-auth.ts:33

Validates an AuthConfig using the exact regex patterns from PRD section 14. Throws AuthError on any violation.

Parameters ​

ParameterType
configAuthConfig

Returns ​

void


validateConfig() ​

ts
function validateConfig(config): void;

Defined in: src/config/validate.ts:9

General config sanity checks that apply regardless of environment. Throws SqunConfigError on invalid values.

Parameters ​

ParameterType
configSqunConfig

Returns ​

void


validateProductionConfig() ​

ts
function validateProductionConfig(
   config, 
   adapter, 
   connection, 
   logger): void;

Defined in: src/config/validate-production.ts:60

Validates a connection config for production. Throws SqunConfigError listing ALL missing fields in one error. Warns (does not throw) for localhost, disabled SSL, and superuser connections.

Parameters ​

ParameterType
configSqunConfig
adapterAdapterType
connectionConnectionConfig
loggerSqunLogger

Returns ​

void


validateSql() ​

ts
function validateSql(fragment, options?): void;

Defined in: src/sql/validator.ts:19

Validates a SqlFragment before execution. Checks: placeholder/param count, unbalanced parens, unresolved TVP sentinels, multiple statements, write on readonly.

Parameters ​

ParameterType
fragmentSqlFragment
optionsValidateOptions

Returns ​

void


validateUrl() ​

ts
function validateUrl(url): void;

Defined in: src/config/url-validator.ts:11

Validates that a connection URL has a recognisable scheme and structure. Throws SqunConfigError if the URL is malformed.

Parameters ​

ParameterType
urlstring

Returns ​

void


withTenant() ​

ts
function withTenant<Names>(resolver, tenantId): Names;

Defined in: src/connections/tenant-resolver.ts:25

Creates a scoped connection name from a tenant ID. For use with QueryOptions.connection or .use().

Type Parameters ​

Type Parameter
Names extends string

Parameters ​

ParameterType
resolverTenantResolver<Names>
tenantIdstring

Returns ​

Names


withTimeout() ​

ts
function withTimeout<T>(
   fn, 
   ms, 
operation?): Promise<T>;

Defined in: src/async/timeout.ts:46

Runs an async function with a timeout deadline. Uses AbortController for cancellation. Timer is always cleared in a finally block.

Type Parameters ​

Type Parameter
T

Parameters ​

ParameterTypeDefault value
fn(signal) => Promise<T>undefined
msnumberundefined
operationstring"query"

Returns ​

Promise<T>

Released under the MIT License.