node-firebird-driver 2.3.0 → 2.4.0

package/src/lib/impl/statement.ts

@@ -14,6 +14,8 @@ import {
 export abstract class AbstractStatement implements Statement {
 	resultSet?: AbstractResultSet;
 
+	abstract getExecPathText(): Promise<string | undefined>;
+
 	/** Gets the query's result columns labels. Returns empty array for queries without result. */
 	abstract get columnLabels(): Promise<string[]>
 
@@ -63,7 +65,7 @@ export abstract class AbstractStatement implements Statement {
 	}
 
 	/** Executes a statement that returns a single record as [col1, col2, ..., colN]. */
-	async executeReturning(transaction: AbstractTransaction, parameters?: any[], options?: ExecuteOptions): Promise<any[]> {
+	async executeSingleton(transaction: AbstractTransaction, parameters?: any[], options?: ExecuteOptions): Promise<any[]> {
 		this.check();
 
 		//// TODO: check opened resultSet.
@@ -72,11 +74,11 @@ export abstract class AbstractStatement implements Statement {
 	}
 
 	/** Executes a statement that returns a single record as an object. */
-	async executeReturningAsObject<T extends object>(transaction: AbstractTransaction, parameters?: any[],
+	async executeSingletonAsObject<T extends object>(transaction: AbstractTransaction, parameters?: any[],
 			options?: ExecuteOptions): Promise<T> {
 		this.check();
 
-		const row = await this.executeReturning(transaction, parameters, options);
+		const row = await this.executeSingleton(transaction, parameters, options);
 		const cols = (await this?.columnLabels) || [];
 
 		const obj = {} as T;
@@ -90,6 +92,17 @@ export abstract class AbstractStatement implements Statement {
 		return obj;
 	}
 
+	/** Executes a statement that returns a single record as [col1, col2, ..., colN]. */
+	async executeReturning(transaction: AbstractTransaction, parameters?: any[], options?: ExecuteOptions): Promise<any[]> {
+		return await this.executeSingleton(transaction, parameters, options);
+	}
+
+	/** Executes a statement that returns a single record as an object. */
+	async executeReturningAsObject<T extends object>(transaction: AbstractTransaction, parameters?: any[],
+			options?: ExecuteOptions): Promise<T> {
+		return await this.executeSingletonAsObject<T>(transaction, parameters, options);
+	}
+
 	/** Executes a prepared statement that has result set. */
 	async executeQuery(transaction: AbstractTransaction, parameters?: any[], options?: ExecuteQueryOptions):
 			Promise<AbstractResultSet> {
@@ -102,8 +115,12 @@ export abstract class AbstractStatement implements Statement {
 		return resultSet;
 	}
 
+	get isValid(): boolean {
+		return !!this.attachment;
+	}
+
 	private check() {
-		if (!this.attachment)
+		if (!this.isValid)
 			throw new Error('Statement is already disposed.');
 	}
 

package/src/lib/impl/transaction.ts

@@ -42,8 +42,12 @@ export abstract class AbstractTransaction implements Transaction {
 		return await this.internalRollbackRetaining();
 	}
 
+	get isValid(): boolean {
+		return !!this.attachment;
+	}
+
 	private check() {
-		if (!this.attachment)
+		if (!this.isValid)
 			throw new Error('Transaction is already committed or rolled back.');
 	}
 

package/src/lib/index.ts

@@ -9,6 +9,9 @@ export interface Client {
 	/** Creates a database. */
 	createDatabase(uri: string, options?: CreateDatabaseOptions): Promise<Attachment>;
 
+	/** True if the client has not been disposed. */
+	readonly isValid: boolean;
+
 	/** Default connect options. */
 	defaultConnectOptions?: ConnectOptions;
 
@@ -121,13 +124,33 @@ export interface Attachment {
 		}): Promise<void>;
 
 	/** Executes a statement that returns a single record as [col1, col2, ..., colN]. */
-	executeReturning(transaction: Transaction, sqlStmt: string, parameters?: any[],
+	executeSingleton(transaction: Transaction, sqlStmt: string, parameters?: any[],
 		options?: {
 			prepareOptions?: PrepareOptions,
 			executeOptions?: ExecuteOptions
 		}): Promise<any[]>;
 
 	/** Executes a statement that returns a single record as an object. */
+	executeSingletonAsObject<T extends object>(transaction: Transaction, sqlStmt: string, parameters?: any[],
+		options?: {
+			prepareOptions?: PrepareOptions,
+			executeOptions?: ExecuteOptions
+		}): Promise<T>;
+
+	/**
+	 * Executes a statement that returns a single record as [col1, col2, ..., colN].
+	 * @deprecated since version 2.4.0 and will be removed in next major version. Replaced by executeSingleton.
+	 */
+	executeReturning(transaction: Transaction, sqlStmt: string, parameters?: any[],
+		options?: {
+			prepareOptions?: PrepareOptions,
+			executeOptions?: ExecuteOptions
+		}): Promise<any[]>;
+
+	/**
+	 * Executes a statement that returns a single record as an object.
+	 * @deprecated since version 2.4.0 and will be removed in next major version. Replaced by executeSingletonAsObject.
+	 */
 	executeReturningAsObject<T extends object>(transaction: Transaction, sqlStmt: string, parameters?: any[],
 		options?: {
 			prepareOptions?: PrepareOptions,
@@ -143,6 +166,9 @@ export interface Attachment {
 
 	queueEvents(names: string[], callBack: (counters: [string, number][]) => Promise<void>): Promise<Events>;
 
+	/** True if the attachment is connected. */
+	readonly isValid: boolean;
+
 	/** Default transaction options. */
 	defaultTransactionOptions?: TransactionOptions;
 
@@ -172,6 +198,9 @@ export interface Transaction {
 
 	/** Rollbacks and maintains this transaction object for subsequent work. */
 	rollbackRetaining(): Promise<void>;
+
+	/** True if the transaction is active. */
+	readonly isValid: boolean;
 }
 
 /** Statement interface. */
@@ -186,9 +215,21 @@ export interface Statement {
 	execute(transaction: Transaction, parameters?: any[], options?: ExecuteOptions): Promise<void>;
 
 	/** Executes a statement that returns a single record as [col1, col2, ..., colN]. */
-	executeReturning(transaction: Transaction, parameters?: any[], executeOptions?: ExecuteOptions): Promise<any[]>;
+	executeSingleton(transaction: Transaction, parameters?: any[], executeOptions?: ExecuteOptions): Promise<any[]>;
 
 	/** Executes a statement that returns a single record as an object. */
+	executeSingletonAsObject<T extends object>(transaction: Transaction, parameters?: any[], executeOptions?: ExecuteOptions): Promise<T>;
+
+	/**
+	 * Executes a statement that returns a single record as [col1, col2, ..., colN].
+	 * @deprecated since version 2.4.0 and will be removed in next major version. Replaced by executeSingleton.
+	 */
+	executeReturning(transaction: Transaction, parameters?: any[], executeOptions?: ExecuteOptions): Promise<any[]>;
+
+	/**
+	 * Executes a statement that returns a single record as an object.
+	 * @deprecated since version 2.4.0 and will be removed in next major version. Replaced by executeSingletonAsObject.
+	 */
 	executeReturningAsObject<T extends object>(transaction: Transaction, parameters?: any[],
 		options?: ExecuteOptions): Promise<T>;
 
@@ -202,6 +243,11 @@ export interface Statement {
 	 */
 	setCursorName(cursorName: string): Promise<void>;
 
+	getExecPathText(): Promise<string | undefined>;
+
+	/** True if the statement has not been disposed. */
+	readonly isValid: boolean;
+
 	/** Gets the query's result columns labels. Returns empty array for queries without result. */
 	readonly columnLabels: Promise<string[]>;
 
@@ -242,12 +288,18 @@ export interface ResultSet {
 	 */
 	fetchAsObject<T extends object>(options?: FetchOptions): Promise<T[]>;
 
+	/** True if the ResultSet is open. */
+	readonly isValid: boolean;
+
 	/** Default result set's fetch options. */
 	defaultFetchOptions?: FetchOptions;
 }
 
 export interface Events {
 	cancel(): Promise<void>;
+
+	/** True if the events' attachment is valid. */
+	readonly isValid: boolean;
 }
 
 /** Blob class. */
@@ -262,6 +314,11 @@ export class Blob {
 		this.attachment = attachment;
 		this.id.set(id);
 	}
+
+	/** True if the blob's attachment is valid. */
+	get isValid(): boolean {
+		return this.attachment.isValid;
+	}
 }
 
 /** BlobStream class. */
@@ -290,6 +347,9 @@ export abstract class BlobStream {
 
 	/** Writes data to the blob. */
 	abstract write(buffer: Buffer): Promise<void>;
+
+	/** True if the blob stream is open. */
+	abstract get isValid(): boolean;
 }
 
 /** TIME WITH TIME ZONE and TIMESTAMP WITH TIME ZONE to be sent as parameter */

package/src/test/tests.ts

@@ -74,6 +74,8 @@ export function runCommonTests(client: Client) {
 
 
 		beforeAll(() => {
+			expect(client.isValid).toBeTruthy();
+
 			if (isLocal() && !testConfig.tmpDir) {
 				testConfig.tmpDir = tmp.mkdirSync().path.toString();
 
@@ -99,6 +101,8 @@ export function runCommonTests(client: Client) {
 		afterAll(async () => {
 			await client.dispose();
 
+			expect(client.isValid).toBeFalsy();
+
 			if (isLocal())
 				fs.rmdirSync(testConfig.tmpDir!);
 		});
@@ -114,8 +118,14 @@ export function runCommonTests(client: Client) {
 				const attachment1 = await client.createDatabase(filename);
 				const attachment2 = await client.connect(filename);
 
+				expect(attachment1.isValid).toBeTruthy();
+				expect(attachment2.isValid).toBeTruthy();
+
 				await attachment2.disconnect();
 				await attachment1.dropDatabase();
+
+				expect(attachment1.isValid).toBeFalsy();
+				expect(attachment2.isValid).toBeFalsy();
 			});
 		});
 
@@ -126,16 +136,22 @@ export function runCommonTests(client: Client) {
 				const isolationQuery = 'select rdb$get_context(\'SYSTEM\', \'ISOLATION_LEVEL\') from rdb$database';
 
 				const transaction1 = await attachment.startTransaction();
-				expect((await attachment.executeReturning(transaction1, isolationQuery))[0]).toBe('SNAPSHOT');
+				expect(transaction1.isValid).toBeTruthy()
+				expect((await attachment.executeSingleton(transaction1, isolationQuery))[0]).toBe('SNAPSHOT');
 				await transaction1.commit();
+				expect(transaction1.isValid).toBeFalsy()
 
 				const transaction2 = await attachment.startTransaction({ isolation: TransactionIsolation.READ_COMMITTED });
-				expect((await attachment.executeReturning(transaction2, isolationQuery))[0]).toBe('READ COMMITTED');
+				expect(transaction2.isValid).toBeTruthy()
+				expect((await attachment.executeSingleton(transaction2, isolationQuery))[0]).toBe('READ COMMITTED');
 				await transaction2.commit();
+				expect(transaction2.isValid).toBeFalsy()
 
 				const transaction3 = await attachment.startTransaction({ isolation: TransactionIsolation.CONSISTENCY });
-				expect((await attachment.executeReturning(transaction3, isolationQuery))[0]).toBe('CONSISTENCY');
+				expect(transaction3.isValid).toBeTruthy()
+				expect((await attachment.executeSingleton(transaction3, isolationQuery))[0]).toBe('CONSISTENCY');
 				await transaction3.commit();
+				expect(transaction3.isValid).toBeFalsy()
 
 				await attachment.dropDatabase();
 			});
@@ -145,7 +161,9 @@ export function runCommonTests(client: Client) {
 				const transaction = await attachment.startTransaction();
 
 				const statement = await attachment.prepare(transaction, 'create table t1 (n1 integer)');
+				expect(statement.isValid).toBeTruthy();
 				await statement.dispose();
+				expect(statement.isValid).toBeFalsy();
 
 				let error: Error | undefined;
 				try {
@@ -189,7 +207,39 @@ export function runCommonTests(client: Client) {
 				await transaction.commitRetaining();
 
 				const resultSet = await attachment.executeQuery(transaction, 'select n1 from t1');
+				expect(resultSet.isValid).toBeTruthy();
 				await resultSet.close();
+				expect(resultSet.isValid).toBeFalsy();
+
+				await transaction.commit();
+				await attachment.dropDatabase();
+			});
+
+			test('#executeSingleton()', async () => {
+				const attachment = await client.createDatabase(getTempFile('Attachment-executeSingleton.fdb'));
+				const transaction = await attachment.startTransaction();
+
+				await attachment.execute(transaction, 'create table t1 (n1 integer)');
+				await transaction.commitRetaining();
+
+				const result = await attachment.executeSingleton(transaction, 'insert into t1 values (11) returning n1');
+				expect(result.length).toBe(1);
+				expect(result[0]).toBe(11);
+
+				await transaction.commit();
+				await attachment.dropDatabase();
+			});
+
+			test('#executeSingletonAsObject()', async () => {
+				const attachment = await client.createDatabase(getTempFile('Attachment-executeSingletonAsObject.fdb'));
+				const transaction = await attachment.startTransaction();
+
+				await attachment.execute(transaction, 'create table t1 (n1 integer)');
+				await transaction.commitRetaining();
+
+				const output = await attachment.executeSingletonAsObject<{ N1: number }>(transaction,
+					'insert into t1 values (11) returning n1');
+				expect(output.N1).toBe(11);
 
 				await transaction.commit();
 				await attachment.dropDatabase();
@@ -260,6 +310,7 @@ export function runCommonTests(client: Client) {
 					if (Array.from(eventsMap.values()).every(obj => obj.count >= obj.expected)) {
 						if (events) {
 							await events.cancel();
+							expect(events.isValid).toBeFalsy();
 							events = null!;
 						}
 					}
@@ -285,10 +336,12 @@ export function runCommonTests(client: Client) {
 						// Commit retaining to test internal event rescheduling
 						// after each handler dispatch.
 						await transaction.commitRetaining();
+						expect(transaction.isValid).toBeTruthy();
 					}
 				}
 				finally {
 					await transaction.commit();
+					expect(transaction.isValid).toBeFalsy();
 				}
 
 				await Promise.all(eventsObj.map(ev => ev.promise));
@@ -355,7 +408,9 @@ export function runCommonTests(client: Client) {
 				await statement2.execute(transaction, [null]);
 				await statement2.execute(transaction, [10]);
 				await statement2.execute(transaction, [100]);
+				expect(statement2.isValid).toBeTruthy();
 				await statement2.dispose();
+				expect(statement2.isValid).toBeFalsy();
 
 				const rs = await attachment.executeQuery(transaction,
 					`select sum(n1) || ', ' || count(n1) || ', ' || count(*) ret from t1`);
@@ -386,6 +441,26 @@ export function runCommonTests(client: Client) {
 				await attachment.dropDatabase();
 			});
 
+			test('#executeSingleton()', async () => {
+				const attachment = await client.createDatabase(getTempFile('Attachment-executeSingleton.fdb'));
+				const transaction = await attachment.startTransaction();
+
+				await attachment.execute(transaction, 'create table t1 (n1 integer)');
+				await transaction.commitRetaining();
+
+				const statement = await attachment.prepare(transaction, 'insert into t1 values (11) returning n1, n1 * 2');
+
+				const result = await statement.executeSingleton(transaction);
+				expect(result.length).toBe(2);
+				expect(result[0]).toBe(11);
+				expect(result[1]).toBe(11 * 2);
+
+				await statement.dispose();
+
+				await transaction.commit();
+				await attachment.dropDatabase();
+			});
+
 			test('#executeReturning()', async () => {
 				const attachment = await client.createDatabase(getTempFile('Attachment-executeReturning.fdb'));
 				const transaction = await attachment.startTransaction();
@@ -467,6 +542,7 @@ export function runCommonTests(client: Client) {
 		describe('ResultSet', () => {
 			test('#fetch()', async () => {
 				const attachment = await client.createDatabase(getTempFile('ResultSet-fetch.fdb'));
+
 				let transaction = await attachment.startTransaction();
 
 				const blobBuffer = Buffer.alloc(11, '12345678á9');
@@ -538,8 +614,11 @@ export function runCommonTests(client: Client) {
 					transaction = await attachment.startTransaction();
 
 					const blob = await attachment.createBlob(transaction);
+					expect(blob.isValid).toBeTruthy();
 					await blob.write(blobBuffer);
+					expect(blob.isValid).toBeTruthy();
 					await blob.close();
+					expect(blob.isValid).toBeFalsy();
 
 					parameters = [
 						-1,
@@ -667,6 +746,7 @@ export function runCommonTests(client: Client) {
 
 					for (const i = n + 2; n < i; ++n) {
 						const blob = columns[n] as Blob;
+						expect(blob.isValid).toBeTruthy();
 						const blobStream = await attachment.openBlob(transaction, blob);
 						const buffer = Buffer.alloc(await blobStream.length);
 						expect(await blobStream.read(buffer)).toBe(buffer.length);