@slonik/driver 43.0.6

package/README.md

@@ -0,0 +1,5 @@
+# Slonik Driver
+
+Slonik driver is an abstraction layer that provides a consistent API for interacting using different PostgreSQL clients.
+
+This package is made available for developers who wish to create their own Slonik driver.

package/dist/Logger.d.ts

@@ -0,0 +1,2 @@
+export declare const Logger: import("roarr").Logger<import("roarr/dist/types").JsonObject>;
+//# sourceMappingURL=Logger.d.ts.map

package/dist/Logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../src/Logger.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,MAAM,+DAEjB,CAAC"}

package/dist/Logger.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+const roarr_1 = require("roarr");
+exports.Logger = roarr_1.Roarr.child({
+    package: '@slonik/driver',
+});
+//# sourceMappingURL=Logger.js.map

package/dist/Logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.js","sourceRoot":"","sources":["../src/Logger.ts"],"names":[],"mappings":";;;AAAA,iCAA8B;AAEjB,QAAA,MAAM,GAAG,aAAK,CAAC,KAAK,CAAC;IAChC,OAAO,EAAE,gBAAgB;CAC1B,CAAC,CAAC"}

package/dist/factories/createDriverFactory.d.ts

@@ -0,0 +1,109 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import { type Field } from '@slonik/types';
+import EventEmitter from 'node:events';
+import { type Readable } from 'node:stream';
+import { type ConnectionOptions as TlsConnectionOptions } from 'node:tls';
+import { type StrictEventEmitter } from 'strict-event-emitter-types';
+type StreamDataEvent<T> = {
+    data: T;
+    fields: readonly Field[];
+};
+export interface DriverStream<T> extends Readable {
+    on(event: 'data', listener: (chunk: StreamDataEvent<T>) => void): this;
+    on(event: string | symbol, listener: (...args: any[]) => void): this;
+    [Symbol.asyncIterator]: () => AsyncIterableIterator<StreamDataEvent<T>>;
+}
+type BasicConnection = {
+    readonly query: (query: string) => Promise<void>;
+};
+/**
+ * @property name Value of "pg_type"."typname" (e.g. "int8", "timestamp", "timestamptz").
+ */
+export type DriverTypeParser<T = unknown> = {
+    readonly name: string;
+    readonly parse: (value: string) => T;
+};
+export type DriverConfiguration = {
+    readonly connectionTimeout: number | 'DISABLE_TIMEOUT';
+    readonly connectionUri: string;
+    readonly gracefulTerminationTimeout?: number;
+    readonly idleInTransactionSessionTimeout: number | 'DISABLE_TIMEOUT';
+    readonly idleTimeout?: number | 'DISABLE_TIMEOUT';
+    readonly maximumPoolSize?: number;
+    readonly resetConnection?: (connection: BasicConnection) => Promise<void>;
+    readonly ssl?: TlsConnectionOptions;
+    readonly statementTimeout: number | 'DISABLE_TIMEOUT';
+    readonly typeParsers: readonly DriverTypeParser[];
+};
+export type DriverNotice = {
+    message: string;
+};
+export type DriverEventEmitter = StrictEventEmitter<EventEmitter, {
+    error: (error: Error) => void;
+}>;
+export type DriverClientEventEmitter = StrictEventEmitter<EventEmitter, {
+    acquire: () => void;
+    destroy: () => void;
+    error: (error: Error) => void;
+    notice: (event: DriverNotice) => void;
+    release: () => void;
+}>;
+export type DriverClientState = 'ACQUIRED' | 'DESTROYED' | 'IDLE' | 'PENDING_DESTROY' | 'PENDING_RELEASE';
+export type DriverClient = {
+    acquire: () => void;
+    destroy: () => Promise<void>;
+    id: () => string;
+    off: DriverClientEventEmitter['off'];
+    on: DriverClientEventEmitter['on'];
+    query: (query: string, values?: unknown[]) => Promise<DriverQueryResult>;
+    release: () => Promise<void>;
+    removeListener: DriverClientEventEmitter['removeListener'];
+    state: () => DriverClientState;
+    stream: (query: string, values?: unknown[]) => DriverStream<DriverStreamResult>;
+};
+export type Driver = {
+    createClient: () => Promise<DriverClient>;
+};
+export type DriverFactory = ({ driverConfiguration, }: {
+    driverConfiguration: DriverConfiguration;
+}) => Promise<Driver>;
+type DriverField = {
+    dataTypeId: number;
+    name: string;
+};
+export type DriverCommand = 'COPY' | 'DELETE' | 'INSERT' | 'SELECT' | 'UPDATE';
+export type DriverQueryResult = {
+    readonly command: DriverCommand;
+    readonly fields: DriverField[];
+    readonly rowCount: number | null;
+    readonly rows: Array<Record<string, unknown>>;
+};
+export type DriverStreamResult = {
+    readonly fields: DriverField[];
+    readonly row: Record<string, unknown>;
+};
+type DriverSetup = ({ driverEventEmitter, driverConfiguration, }: {
+    driverConfiguration: DriverConfiguration;
+    driverEventEmitter: DriverEventEmitter;
+}) => Promise<InternalPoolClientFactory>;
+/**
+ * @property {Function} connect - Connect to the database. The client must not be used before this method is called.
+ * @property {Function} end - Disconnect from the database. The client must not be used after this method is called.
+ * @property {Function} query - Execute a SQL query.
+ */
+type InternalPoolClient = {
+    connect: () => Promise<void>;
+    end: () => Promise<void>;
+    query: (query: string, values?: unknown[]) => Promise<DriverQueryResult>;
+    stream: (query: string, values?: unknown[]) => DriverStream<DriverStreamResult>;
+};
+type InternalPoolClientFactory = {
+    createPoolClient: ({ clientEventEmitter, }: {
+        clientEventEmitter: DriverClientEventEmitter;
+    }) => Promise<InternalPoolClient>;
+};
+export declare const createDriverFactory: (setup: DriverSetup) => DriverFactory;
+export {};
+//# sourceMappingURL=createDriverFactory.d.ts.map

package/dist/factories/createDriverFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createDriverFactory.d.ts","sourceRoot":"","sources":["../../src/factories/createDriverFactory.ts"],"names":[],"mappings":"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"}

package/dist/factories/createDriverFactory.js

@@ -0,0 +1,227 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDriverFactory = void 0;
+const Logger_1 = require("../Logger");
+const utilities_1 = require("@slonik/utilities");
+const node_events_1 = __importDefault(require("node:events"));
+const promises_1 = require("node:timers/promises");
+const serialize_error_1 = require("serialize-error");
+const createDriverFactory = (setup) => {
+    return async ({ driverConfiguration }) => {
+        const { resetConnection } = driverConfiguration;
+        const driverEventEmitter = new node_events_1.default();
+        const { createPoolClient } = await setup({
+            driverConfiguration,
+            driverEventEmitter,
+        });
+        return {
+            createClient: async () => {
+                const clientEventEmitter = new node_events_1.default();
+                // eslint-disable-next-line prefer-const
+                let destroy;
+                const onError = (error) => {
+                    if (destroy) {
+                        // eslint-disable-next-line promise/prefer-await-to-then
+                        void destroy().catch(() => {
+                            // Do nothing. The error has been emitted already.
+                            // See "handles unexpected backend termination" test.
+                        });
+                    }
+                    Logger_1.Logger.warn({
+                        error: (0, serialize_error_1.serializeError)(error),
+                        namespace: 'driverClient',
+                    }, 'unhandled driver client error');
+                };
+                clientEventEmitter.on('error', onError);
+                const { query, stream, connect, end } = await createPoolClient({
+                    clientEventEmitter,
+                });
+                let isAcquired = false;
+                let isDestroyed = false;
+                let idleTimeout = null;
+                let activeQueryPromise = null;
+                let destroyPromise = null;
+                let releasePromise = null;
+                const id = (0, utilities_1.generateUid)();
+                const clearIdleTimeout = () => {
+                    if (idleTimeout) {
+                        clearTimeout(idleTimeout);
+                        idleTimeout = null;
+                    }
+                };
+                const state = () => {
+                    if (destroyPromise) {
+                        return 'PENDING_DESTROY';
+                    }
+                    if (releasePromise) {
+                        return 'PENDING_RELEASE';
+                    }
+                    if (isDestroyed) {
+                        return 'DESTROYED';
+                    }
+                    if (isAcquired) {
+                        return 'ACQUIRED';
+                    }
+                    return 'IDLE';
+                };
+                const internalDestroy = async () => {
+                    const currentState = state();
+                    if (currentState === 'PENDING_DESTROY') {
+                        throw new Error('Client is pending destroy.');
+                    }
+                    if (currentState === 'DESTROYED') {
+                        throw new Error('Client is destroyed.');
+                    }
+                    clearIdleTimeout();
+                    if (activeQueryPromise) {
+                        await Promise.race([
+                            (0, promises_1.setTimeout)(driverConfiguration.gracefulTerminationTimeout),
+                            activeQueryPromise,
+                        ]);
+                    }
+                    if (releasePromise) {
+                        await releasePromise;
+                    }
+                    isDestroyed = true;
+                    clientEventEmitter.emit('destroy');
+                    await end();
+                    clientEventEmitter.off('error', onError);
+                };
+                destroy = async () => {
+                    if (destroyPromise) {
+                        return destroyPromise;
+                    }
+                    destroyPromise = internalDestroy();
+                    return destroyPromise;
+                };
+                const internalRelease = async () => {
+                    const currentState = state();
+                    if (currentState === 'PENDING_DESTROY') {
+                        throw new Error('Client is pending destroy.');
+                    }
+                    if (currentState === 'DESTROYED') {
+                        throw new Error('Client is destroyed.');
+                    }
+                    if (currentState !== 'ACQUIRED') {
+                        throw new Error('Client is not acquired.');
+                    }
+                    if (activeQueryPromise) {
+                        throw new Error('Client has an active query.');
+                    }
+                    if (resetConnection) {
+                        await resetConnection({
+                            query: async (sql) => {
+                                await query(sql);
+                            },
+                        });
+                    }
+                    if (driverConfiguration.idleTimeout !== 'DISABLE_TIMEOUT') {
+                        clearIdleTimeout();
+                        idleTimeout = setTimeout(() => {
+                            void destroy();
+                            idleTimeout = null;
+                        }, driverConfiguration.idleTimeout).unref();
+                    }
+                    // eslint-disable-next-line require-atomic-updates
+                    isAcquired = false;
+                    releasePromise = null;
+                    clientEventEmitter.emit('release');
+                };
+                const release = () => {
+                    if (destroyPromise) {
+                        return destroyPromise;
+                    }
+                    if (releasePromise) {
+                        return releasePromise;
+                    }
+                    releasePromise = internalRelease();
+                    return releasePromise;
+                };
+                const client = {
+                    acquire: () => {
+                        const currentState = state();
+                        if (currentState === 'PENDING_DESTROY') {
+                            throw new Error('Client is pending destroy.');
+                        }
+                        if (currentState === 'PENDING_RELEASE') {
+                            throw new Error('Client is pending release.');
+                        }
+                        if (currentState === 'DESTROYED') {
+                            throw new Error('Client is destroyed.');
+                        }
+                        if (currentState === 'ACQUIRED') {
+                            throw new Error('Client is already acquired.');
+                        }
+                        clearIdleTimeout();
+                        isAcquired = true;
+                        clientEventEmitter.emit('acquire');
+                    },
+                    destroy,
+                    id: () => id,
+                    off: (event, listener) => {
+                        return clientEventEmitter.off(event, listener);
+                    },
+                    on: (event, listener) => {
+                        return clientEventEmitter.on(event, listener);
+                    },
+                    query: async (sql, values) => {
+                        const currentState = state();
+                        if (currentState === 'PENDING_DESTROY') {
+                            throw new Error('Client is pending destroy.');
+                        }
+                        if (currentState === 'PENDING_RELEASE') {
+                            throw new Error('Client is pending release.');
+                        }
+                        if (currentState === 'DESTROYED') {
+                            throw new Error('Client is destroyed.');
+                        }
+                        if (currentState !== 'ACQUIRED') {
+                            throw new Error('Client is not acquired.');
+                        }
+                        try {
+                            activeQueryPromise = query(sql, values);
+                            const result = await activeQueryPromise;
+                            if (!activeQueryPromise) {
+                                throw new Error('Expected `activeQueryPromise` to be set.');
+                            }
+                            return result;
+                        }
+                        finally {
+                            // eslint-disable-next-line require-atomic-updates
+                            activeQueryPromise = null;
+                        }
+                    },
+                    release,
+                    removeListener: (event, listener) => {
+                        return clientEventEmitter.removeListener(event, listener);
+                    },
+                    state,
+                    stream: (sql, values) => {
+                        const currentState = state();
+                        if (currentState === 'PENDING_DESTROY') {
+                            throw new Error('Client is pending destroy.');
+                        }
+                        if (currentState === 'PENDING_RELEASE') {
+                            throw new Error('Client is pending release.');
+                        }
+                        if (currentState === 'DESTROYED') {
+                            throw new Error('Client is destroyed.');
+                        }
+                        if (currentState !== 'ACQUIRED') {
+                            throw new Error('Client is not acquired.');
+                        }
+                        // TODO determine if streaming and do not allow to release the client until the stream is finished
+                        return stream(sql, values);
+                    },
+                };
+                await connect();
+                return client;
+            },
+        };
+    };
+};
+exports.createDriverFactory = createDriverFactory;
+//# sourceMappingURL=createDriverFactory.js.map

package/dist/factories/createDriverFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createDriverFactory.js","sourceRoot":"","sources":["../../src/factories/createDriverFactory.ts"],"names":[],"mappings":"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"}

package/dist/factories/createDriverFactory.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=createDriverFactory.test.d.ts.map

package/dist/factories/createDriverFactory.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createDriverFactory.test.d.ts","sourceRoot":"","sources":["../../src/factories/createDriverFactory.test.ts"],"names":[],"mappings":""}

package/dist/factories/createDriverFactory.test.js

@@ -0,0 +1,10 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const ava_1 = __importDefault(require("ava"));
+(0, ava_1.default)('ok', (t) => {
+    t.pass();
+});
+//# sourceMappingURL=createDriverFactory.test.js.map

package/dist/factories/createDriverFactory.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createDriverFactory.test.js","sourceRoot":"","sources":["../../src/factories/createDriverFactory.test.ts"],"names":[],"mappings":";;;;;AAAA,8CAAuB;AAEvB,IAAA,aAAI,EAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE;IACf,CAAC,CAAC,IAAI,EAAE,CAAC;AACX,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createDriverFactory, type Driver, type DriverClient, type DriverClientEventEmitter, type DriverClientState, type DriverCommand, type DriverConfiguration, type DriverEventEmitter, type DriverFactory, type DriverNotice, type DriverQueryResult, type DriverStream, type DriverStreamResult, type DriverTypeParser, } from './factories/createDriverFactory';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDriverFactory = void 0;
+var createDriverFactory_1 = require("./factories/createDriverFactory");
+Object.defineProperty(exports, "createDriverFactory", { enumerable: true, get: function () { return createDriverFactory_1.createDriverFactory; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,uEAeyC;AAdvC,0HAAA,mBAAmB,OAAA"}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "author": {
+    "email": "gajus@gajus.com",
+    "name": "Gajus Kuizinas",
+    "url": "http://gajus.com"
+  },
+  "ava": {
+    "extensions": [
+      "ts"
+    ],
+    "files": [
+      "src/**/*.test.ts"
+    ],
+    "require": [
+      "ts-node/register/transpile-only"
+    ]
+  },
+  "dependencies": {
+    "@slonik/utilities": "^43.0.6",
+    "@slonik/types": "^43.0.6",
+    "serialize-error": "^8.0.0",
+    "roarr": "^7.21.1",
+    "strict-event-emitter-types": "^2.0.0"
+  },
+  "description": "A Node.js PostgreSQL client with strict types, detailed logging and assertions.",
+  "devDependencies": {
+    "@types/node": "^18.15.3",
+    "ava": "^5.3.1",
+    "cspell": "^8.6.0",
+    "eslint": "^8.57.0",
+    "eslint-config-canonical": "^42.8.1",
+    "nyc": "^15.1.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.4.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "./src",
+    "./dist"
+  ],
+  "keywords": [
+    "postgresql",
+    "promise",
+    "types"
+  ],
+  "license": "BSD-3-Clause",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "name": "@slonik/driver",
+  "nyc": {
+    "all": true,
+    "exclude": [
+      "**/*.d.ts"
+    ],
+    "include": [
+      "src/**/*.ts"
+    ],
+    "reporter": [
+      "html",
+      "text-summary"
+    ],
+    "require": [
+      "ts-node/register/transpile-only"
+    ],
+    "silent": true,
+    "sourceMap": false
+  },
+  "peerDependencies": {
+    "zod": "^3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gajus/slonik"
+  },
+  "scripts": {
+    "build": "rm -fr ./dist && tsc --project ./tsconfig.json",
+    "lint": "npm run lint:cspell && npm run lint:eslint && npm run lint:tsc",
+    "lint:cspell": "cspell . --no-progress --gitignore",
+    "lint:eslint": "eslint --cache ./src",
+    "lint:tsc": "tsc --noEmit",
+    "test": "nyc ava --verbose --serial"
+  },
+  "types": "./dist/index.d.ts",
+  "version": "43.0.6"
+}

package/src/Logger.ts

@@ -0,0 +1,5 @@
+import { Roarr } from 'roarr';
+
+export const Logger = Roarr.child({
+  package: '@slonik/driver',
+});

package/src/factories/createDriverFactory.test.ts

@@ -0,0 +1,5 @@
+import test from 'ava';
+
+test('ok', (t) => {
+  t.pass();
+});

package/src/factories/createDriverFactory.ts

@@ -0,0 +1,439 @@
+import { Logger } from '../Logger';
+import { type Field } from '@slonik/types';
+import { generateUid } from '@slonik/utilities';
+import EventEmitter from 'node:events';
+import { type Readable } from 'node:stream';
+import { setTimeout as delay } from 'node:timers/promises';
+import { type ConnectionOptions as TlsConnectionOptions } from 'node:tls';
+import { serializeError } from 'serialize-error';
+import { type StrictEventEmitter } from 'strict-event-emitter-types';
+
+type StreamDataEvent<T> = { data: T; fields: readonly Field[] };
+
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export interface DriverStream<T> extends Readable {
+  // eslint-disable-next-line @typescript-eslint/method-signature-style
+  on(event: 'data', listener: (chunk: StreamDataEvent<T>) => void): this;
+  // eslint-disable-next-line @typescript-eslint/method-signature-style
+  on(event: string | symbol, listener: (...args: any[]) => void): this;
+
+  [Symbol.asyncIterator]: () => AsyncIterableIterator<StreamDataEvent<T>>;
+}
+
+type BasicConnection = {
+  readonly query: (query: string) => Promise<void>;
+};
+
+/**
+ * @property name Value of "pg_type"."typname" (e.g. "int8", "timestamp", "timestamptz").
+ */
+export type DriverTypeParser<T = unknown> = {
+  readonly name: string;
+  readonly parse: (value: string) => T;
+};
+
+export type DriverConfiguration = {
+  readonly connectionTimeout: number | 'DISABLE_TIMEOUT';
+  readonly connectionUri: string;
+  readonly gracefulTerminationTimeout?: number;
+  readonly idleInTransactionSessionTimeout: number | 'DISABLE_TIMEOUT';
+  readonly idleTimeout?: number | 'DISABLE_TIMEOUT';
+  readonly maximumPoolSize?: number;
+  readonly resetConnection?: (connection: BasicConnection) => Promise<void>;
+  readonly ssl?: TlsConnectionOptions;
+  readonly statementTimeout: number | 'DISABLE_TIMEOUT';
+  readonly typeParsers: readonly DriverTypeParser[];
+};
+
+export type DriverNotice = {
+  message: string;
+};
+
+export type DriverEventEmitter = StrictEventEmitter<
+  EventEmitter,
+  {
+    error: (error: Error) => void;
+  }
+>;
+
+export type DriverClientEventEmitter = StrictEventEmitter<
+  EventEmitter,
+  {
+    acquire: () => void;
+    destroy: () => void;
+    error: (error: Error) => void;
+    notice: (event: DriverNotice) => void;
+    release: () => void;
+  }
+>;
+
+export type DriverClientState =
+  | 'ACQUIRED'
+  | 'DESTROYED'
+  | 'IDLE'
+  | 'PENDING_DESTROY'
+  | 'PENDING_RELEASE';
+
+export type DriverClient = {
+  acquire: () => void;
+  destroy: () => Promise<void>;
+  id: () => string;
+  off: DriverClientEventEmitter['off'];
+  on: DriverClientEventEmitter['on'];
+  query: (query: string, values?: unknown[]) => Promise<DriverQueryResult>;
+  release: () => Promise<void>;
+  removeListener: DriverClientEventEmitter['removeListener'];
+  state: () => DriverClientState;
+  stream: (
+    query: string,
+    values?: unknown[],
+  ) => DriverStream<DriverStreamResult>;
+};
+
+export type Driver = {
+  createClient: () => Promise<DriverClient>;
+};
+
+export type DriverFactory = ({
+  driverConfiguration,
+}: {
+  driverConfiguration: DriverConfiguration;
+}) => Promise<Driver>;
+
+type DriverField = {
+  dataTypeId: number;
+  name: string;
+};
+
+export type DriverCommand = 'COPY' | 'DELETE' | 'INSERT' | 'SELECT' | 'UPDATE';
+
+export type DriverQueryResult = {
+  readonly command: DriverCommand;
+  readonly fields: DriverField[];
+  readonly rowCount: number | null;
+  readonly rows: Array<Record<string, unknown>>;
+};
+
+export type DriverStreamResult = {
+  readonly fields: DriverField[];
+  readonly row: Record<string, unknown>;
+};
+
+type DriverSetup = ({
+  driverEventEmitter,
+  driverConfiguration,
+}: {
+  driverConfiguration: DriverConfiguration;
+  driverEventEmitter: DriverEventEmitter;
+}) => Promise<InternalPoolClientFactory>;
+
+/**
+ * @property {Function} connect - Connect to the database. The client must not be used before this method is called.
+ * @property {Function} end - Disconnect from the database. The client must not be used after this method is called.
+ * @property {Function} query - Execute a SQL query.
+ */
+type InternalPoolClient = {
+  connect: () => Promise<void>;
+  end: () => Promise<void>;
+  query: (query: string, values?: unknown[]) => Promise<DriverQueryResult>;
+  stream: (
+    query: string,
+    values?: unknown[],
+  ) => DriverStream<DriverStreamResult>;
+};
+
+type InternalPoolClientFactory = {
+  createPoolClient: ({
+    clientEventEmitter,
+  }: {
+    clientEventEmitter: DriverClientEventEmitter;
+  }) => Promise<InternalPoolClient>;
+};
+
+export const createDriverFactory = (setup: DriverSetup): DriverFactory => {
+  return async ({ driverConfiguration }): Promise<Driver> => {
+    const { resetConnection } = driverConfiguration;
+
+    const driverEventEmitter: DriverEventEmitter = new EventEmitter();
+
+    const { createPoolClient } = await setup({
+      driverConfiguration,
+      driverEventEmitter,
+    });
+
+    return {
+      createClient: async () => {
+        const clientEventEmitter: DriverClientEventEmitter = new EventEmitter();
+
+        // eslint-disable-next-line prefer-const
+        let destroy: () => Promise<void>;
+
+        const onError = (error: Error) => {
+          if (destroy) {
+            // eslint-disable-next-line promise/prefer-await-to-then
+            void destroy().catch(() => {
+              // Do nothing. The error has been emitted already.
+              // See "handles unexpected backend termination" test.
+            });
+          }
+
+          Logger.warn(
+            {
+              error: serializeError(error),
+              namespace: 'driverClient',
+            },
+            'unhandled driver client error',
+          );
+        };
+
+        clientEventEmitter.on('error', onError);
+
+        const { query, stream, connect, end } = await createPoolClient({
+          clientEventEmitter,
+        });
+
+        let isAcquired = false;
+        let isDestroyed = false;
+        let idleTimeout: NodeJS.Timeout | null = null;
+
+        let activeQueryPromise: Promise<DriverQueryResult> | null = null;
+        let destroyPromise: Promise<void> | null = null;
+        let releasePromise: Promise<void> | null = null;
+
+        const id = generateUid();
+
+        const clearIdleTimeout = () => {
+          if (idleTimeout) {
+            clearTimeout(idleTimeout);
+
+            idleTimeout = null;
+          }
+        };
+
+        const state = () => {
+          if (destroyPromise) {
+            return 'PENDING_DESTROY';
+          }
+
+          if (releasePromise) {
+            return 'PENDING_RELEASE';
+          }
+
+          if (isDestroyed) {
+            return 'DESTROYED';
+          }
+
+          if (isAcquired) {
+            return 'ACQUIRED';
+          }
+
+          return 'IDLE';
+        };
+
+        const internalDestroy = async () => {
+          const currentState = state();
+
+          if (currentState === 'PENDING_DESTROY') {
+            throw new Error('Client is pending destroy.');
+          }
+
+          if (currentState === 'DESTROYED') {
+            throw new Error('Client is destroyed.');
+          }
+
+          clearIdleTimeout();
+
+          if (activeQueryPromise) {
+            await Promise.race([
+              delay(driverConfiguration.gracefulTerminationTimeout),
+              activeQueryPromise,
+            ]);
+          }
+
+          if (releasePromise) {
+            await releasePromise;
+          }
+
+          isDestroyed = true;
+
+          clientEventEmitter.emit('destroy');
+
+          await end();
+
+          clientEventEmitter.off('error', onError);
+        };
+
+        destroy = async () => {
+          if (destroyPromise) {
+            return destroyPromise;
+          }
+
+          destroyPromise = internalDestroy();
+
+          return destroyPromise;
+        };
+
+        const internalRelease = async () => {
+          const currentState = state();
+
+          if (currentState === 'PENDING_DESTROY') {
+            throw new Error('Client is pending destroy.');
+          }
+
+          if (currentState === 'DESTROYED') {
+            throw new Error('Client is destroyed.');
+          }
+
+          if (currentState !== 'ACQUIRED') {
+            throw new Error('Client is not acquired.');
+          }
+
+          if (activeQueryPromise) {
+            throw new Error('Client has an active query.');
+          }
+
+          if (resetConnection) {
+            await resetConnection({
+              query: async (sql) => {
+                await query(sql);
+              },
+            });
+          }
+
+          if (driverConfiguration.idleTimeout !== 'DISABLE_TIMEOUT') {
+            clearIdleTimeout();
+
+            idleTimeout = setTimeout(() => {
+              void destroy();
+
+              idleTimeout = null;
+            }, driverConfiguration.idleTimeout).unref();
+          }
+
+          // eslint-disable-next-line require-atomic-updates
+          isAcquired = false;
+
+          releasePromise = null;
+
+          clientEventEmitter.emit('release');
+        };
+
+        const release = () => {
+          if (destroyPromise) {
+            return destroyPromise;
+          }
+
+          if (releasePromise) {
+            return releasePromise;
+          }
+
+          releasePromise = internalRelease();
+
+          return releasePromise;
+        };
+
+        const client = {
+          acquire: () => {
+            const currentState = state();
+
+            if (currentState === 'PENDING_DESTROY') {
+              throw new Error('Client is pending destroy.');
+            }
+
+            if (currentState === 'PENDING_RELEASE') {
+              throw new Error('Client is pending release.');
+            }
+
+            if (currentState === 'DESTROYED') {
+              throw new Error('Client is destroyed.');
+            }
+
+            if (currentState === 'ACQUIRED') {
+              throw new Error('Client is already acquired.');
+            }
+
+            clearIdleTimeout();
+
+            isAcquired = true;
+
+            clientEventEmitter.emit('acquire');
+          },
+          destroy,
+          id: () => id,
+          off: (event, listener) => {
+            return clientEventEmitter.off(event, listener);
+          },
+          on: (event, listener) => {
+            return clientEventEmitter.on(event, listener);
+          },
+          query: async (sql, values) => {
+            const currentState = state();
+
+            if (currentState === 'PENDING_DESTROY') {
+              throw new Error('Client is pending destroy.');
+            }
+
+            if (currentState === 'PENDING_RELEASE') {
+              throw new Error('Client is pending release.');
+            }
+
+            if (currentState === 'DESTROYED') {
+              throw new Error('Client is destroyed.');
+            }
+
+            if (currentState !== 'ACQUIRED') {
+              throw new Error('Client is not acquired.');
+            }
+
+            try {
+              activeQueryPromise = query(sql, values);
+
+              const result = await activeQueryPromise;
+
+              if (!activeQueryPromise) {
+                throw new Error('Expected `activeQueryPromise` to be set.');
+              }
+
+              return result;
+            } finally {
+              // eslint-disable-next-line require-atomic-updates
+              activeQueryPromise = null;
+            }
+          },
+          release,
+          removeListener: (event, listener) => {
+            return clientEventEmitter.removeListener(event, listener);
+          },
+          state,
+          stream: (sql, values) => {
+            const currentState = state();
+
+            if (currentState === 'PENDING_DESTROY') {
+              throw new Error('Client is pending destroy.');
+            }
+
+            if (currentState === 'PENDING_RELEASE') {
+              throw new Error('Client is pending release.');
+            }
+
+            if (currentState === 'DESTROYED') {
+              throw new Error('Client is destroyed.');
+            }
+
+            if (currentState !== 'ACQUIRED') {
+              throw new Error('Client is not acquired.');
+            }
+
+            // TODO determine if streaming and do not allow to release the client until the stream is finished
+
+            return stream(sql, values);
+          },
+        };
+
+        await connect();
+
+        return client;
+      },
+    };
+  };
+};

package/src/index.ts

@@ -0,0 +1,16 @@
+export {
+  createDriverFactory,
+  type Driver,
+  type DriverClient,
+  type DriverClientEventEmitter,
+  type DriverClientState,
+  type DriverCommand,
+  type DriverConfiguration,
+  type DriverEventEmitter,
+  type DriverFactory,
+  type DriverNotice,
+  type DriverQueryResult,
+  type DriverStream,
+  type DriverStreamResult,
+  type DriverTypeParser,
+} from './factories/createDriverFactory';