node-firebird-driver 2.3.0 → 3.0.0

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;
 
@@ -87,6 +90,11 @@ export interface FetchOptions {
 	fetchSize?: number;
 }
 
+/** CreateBlobOptions interface. */
+export interface CreateBlobOptions {
+	type?: 'SEGMENTED' | 'STREAM';
+}
+
 /** Attachment interface. */
 export interface Attachment {
 	/** Disconnects this attachment. */
@@ -96,7 +104,7 @@ export interface Attachment {
 	dropDatabase(): Promise<void>;
 
 	/** Creates a blob and return its stream. */
-	createBlob(transaction: Transaction): Promise<BlobStream>;
+	createBlob(transaction: Transaction, options?: CreateBlobOptions): Promise<BlobStream>;
 
 	/** Opens a blob's stream. */
 	openBlob(transaction: Transaction, blob: Blob): Promise<BlobStream>;
@@ -121,13 +129,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 +171,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 +203,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 +220,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 +248,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 +293,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 +319,17 @@ 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;
+	}
+}
+
+export const enum BlobSeekWhence {
+	START = 0,
+	CURRENT = 1,
+	END = 2
 }
 
 /** BlobStream class. */
@@ -282,6 +350,9 @@ export abstract class BlobStream {
 	/** Cancels the blob's creation. */
 	abstract cancel(): Promise<void>;
 
+	/** Seeks into the blob stream and return the new position. */
+	abstract seek(offset: number, whence?: BlobSeekWhence): Promise<number>;
+
 	/**
 	 * Reads data from the blob and return the number of bytes read or -1 for end-of-stream.
 	 * The number of bytes read may be less than the buffer' size while more data to be read exists.
@@ -290,6 +361,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

@@ -1,5 +1,6 @@
 import {
 	Blob,
+	BlobSeekWhence,
 	Client,
 	TransactionIsolation,
 	ZonedDate,
@@ -74,6 +75,8 @@ export function runCommonTests(client: Client) {
 
 
 		beforeAll(() => {
+			expect(client.isValid).toBeTruthy();
+
 			if (isLocal() && !testConfig.tmpDir) {
 				testConfig.tmpDir = tmp.mkdirSync().path.toString();
 
@@ -99,6 +102,8 @@ export function runCommonTests(client: Client) {
 		afterAll(async () => {
 			await client.dispose();
 
+			expect(client.isValid).toBeFalsy();
+
 			if (isLocal())
 				fs.rmdirSync(testConfig.tmpDir!);
 		});
@@ -114,8 +119,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 +137,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 +162,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 +208,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 +311,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 +337,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 +409,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 +442,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 +543,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 +615,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 +747,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);
@@ -805,5 +886,44 @@ export function runCommonTests(client: Client) {
 				await attachment.dropDatabase();
 			});
 		});
+
+		describe('BlobStream', () => {
+			test('#seek()', async () => {
+				const attachment = await client.createDatabase(getTempFile('BlobStream-seek.fdb'));
+				const transaction = await attachment.startTransaction();
+
+				await attachment.execute(transaction, 'create table t1 (b blob)');
+				await transaction.commitRetaining();
+
+				const blobStream = await attachment.createBlob(transaction, { type: 'STREAM' });
+				await blobStream.write(Buffer.alloc(10, '1234567890'));
+				await blobStream.close();
+				await attachment.execute(transaction, 'insert into t1 (b) values (?)', [blobStream.blob]);
+
+				const blob = (await attachment.executeSingleton(transaction, 'select b from t1'))[0] as Blob;
+				const readBlobStream = await attachment.openBlob(transaction, blob);
+
+				const buffer = Buffer.alloc(3);
+
+				expect(await readBlobStream.seek(2)).toBe(2);
+				expect(await readBlobStream.read(buffer)).toBe(3);
+				expect(buffer.toString()).toBe('345');
+
+				expect(await readBlobStream.seek(-1, BlobSeekWhence.CURRENT)).toBe(4);
+				expect(await readBlobStream.read(buffer)).toBe(3);
+				expect(buffer.toString()).toBe('567');
+
+				expect(await readBlobStream.seek(1, BlobSeekWhence.START)).toBe(1);
+				expect(await readBlobStream.read(buffer)).toBe(3);
+				expect(buffer.toString()).toBe('234');
+
+				expect(await readBlobStream.seek(-2, BlobSeekWhence.END)).toBe(8);
+				expect(await readBlobStream.read(buffer)).toBe(2);
+				expect(buffer.slice(0, 2).toString()).toBe('90');
+
+				await transaction.commit();
+				await attachment.dropDatabase();
+			});
+		});
 	});
 }