🤖 Merge PR #53614 update(oracledb): Add QueryStream interface by @Chrisp1tv

* add QueryStream to oracledb

* clean up with prettier

* add tests from connorjayfitzgerald suggestions

types/oracledb/index.d.ts

@@ -1057,9 +1057,9 @@ declare namespace OracleDB {
          * @since 1.8
          * @see https://oracle.github.io/node-oracledb/doc/api.html#streamingresults
          */
-        queryStream(sql: string, bindParams: BindParameters, options: ExecuteOptions): Readable;
-        queryStream(sql: string, bindParams: BindParameters): Readable;
-        queryStream(sql: string): Readable;
+        queryStream<T>(sql: string, bindParams: BindParameters, options: ExecuteOptions): QueryStream<T>;
+        queryStream<T>(sql: string, bindParams: BindParameters): QueryStream<T>;
+        queryStream<T>(sql: string): QueryStream<T>;
 
         /**
          * Releases a connection.
@@ -2364,6 +2364,29 @@ declare namespace OracleDB {
         visibility: number;
     }
 
+    /**
+     * Extends Readable and provides access to data and metadata of the query. The end event indicates the end of the query results.
+     * After the end event has been received, the Stream destroy() function should be called to clean up resources properly.
+     * Any further end-of-fetch logic, in particular the connection release, should be in the close event.
+     */
+    type QueryStream<T> = Readable & QueryStreamEvents<T>;
+
+    interface QueryStreamEvents<T> {
+        addListener(event: 'metadata', listener: (metadata: Metadata<T>[]) => void): this;
+
+        emit(event: 'metadata', metadata: Metadata<T>[]): boolean;
+
+        on(event: 'metadata', listener: (metadata: Metadata<T>[]) => void): this;
+
+        once(event: 'metadata', listener: (metadata: Metadata<T>[]) => void): this;
+
+        prependListener(event: 'metadata', listener: (metadata: Metadata<T>[]) => void): this;
+
+        prependOnceListener(event: 'metadata', listener: (metadata: Metadata<T>[]) => void): this;
+
+        removeListener(event: 'metadata', listener: (metadata: Metadata<T>[]) => void): this;
+    }
+
     /**
      * Contains information regarding the outcome of a successful connection.execute().
      */

types/oracledb/oracledb-tests.ts

@@ -444,17 +444,8 @@ const version4Tests = async () => {
 
     const { name, deqOptions, enqOptions, payloadType, payloadTypeClass, payloadTypeName } = queue;
 
-    const {
-        condition,
-        consumerName,
-        correlation,
-        mode,
-        msgId,
-        navigation,
-        transformation,
-        visibility,
-        wait,
-    } = deqOptions;
+    const { condition, consumerName, correlation, mode, msgId, navigation, transformation, visibility, wait } =
+        deqOptions;
 
     const messages = await queue.deqMany(5);
 
@@ -568,6 +559,37 @@ const testGenerics = async () => {
     console.log(result3.outBinds[0].firstColumn);
 };
 
+export const testQueryStreamGenerics = (connection: oracledb.Connection): void => {
+    interface MyStream {
+        streamTest: string;
+    }
+
+    const stream = connection.queryStream<MyStream>('SELECT 1 FROM DUAL WHERE 10 < :myValue', {
+        myValue: {
+            dir: oracledb.BIND_IN,
+            maxSize: 50,
+            type: oracledb.NUMBER,
+            val: 20,
+        },
+        anotherValue: {
+            dir: oracledb.BIND_INOUT,
+            type: oracledb.DB_TYPE_NCLOB,
+        },
+    });
+
+    stream.on('data', data => {
+        console.log(data);
+    });
+
+    stream.on('metadata', metadata => {
+        const streamClass = metadata[0].dbTypeClass;
+
+        const streamClassInstance = new streamClass({
+            streamTest: 'success',
+        });
+    });
+};
+
 const test4point1 = async (): Promise<void> => {
     defaultOracledb.poolMaxPerShard = 45;