3.2.5

changelog.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 2024-11-19 - 3.2.5 - fix(nodewebhelpers)
+Fix import and use correct module structure for Node.js streams in smartstream.nodewebhelpers.ts
+
+- Corrected the import statement for the fs module.
+- Updated the use of the fs.createReadStream method.
+
+## 2024-10-16 - 3.2.4 - fix(SmartDuplex)
+Fix stream termination when reading from a web readable stream
+
+- Resolved an issue in SmartDuplex where the stream did not properly terminate after reaching the end of a web readable stream.
+
+## 2024-10-16 - 3.2.3 - fix(smartduplex)
+Enhance documentation for read function in SmartDuplex
+
+- Added inline comments to clarify the behavior and importance of unlocking the reader in the readFunction of SmartDuplex.fromWebReadableStream.
+
+## 2024-10-16 - 3.2.2 - fix(SmartDuplex)
+Fix issue with SmartDuplex fromWebReadableStream method
+
+- Resolved a potential unhandled promise rejection in fromWebReadableStream method
+- Ensured proper release of stream reader lock in case of read completion
+
+## 2024-10-16 - 3.2.1 - fix(core)
+Fix the order of operations in SmartDuplex _read method to ensure proper waiting for items.
+
+- Adjusted the order of reading function execution and waiting for items in the SmartDuplex _read method.
+- Fixed potential issues with stream data processing timing.
+
+## 2024-10-16 - 3.2.0 - feat(SmartDuplex)
+Added method to create SmartDuplex from a WebReadableStream.
+
+- Implemented a static method in SmartDuplex to allow creating an instance from a WebReadableStream.
+- This addition enhances the capability of SmartDuplex to integrate with web streams, facilitating seamless stream manipulation across environments.
+
+## 2024-10-14 - 3.1.2 - fix(WebDuplexStream)
+Fix variable naming inconsistency in WebDuplexStream test
+
+- Changed variable names from 'transformStream' to 'webDuplexStream' for consistency.
+- Renamed 'writableStream' and 'readableStream' to 'writer' and 'reader' respectively.
+
+## 2024-10-13 - 3.1.1 - fix(WebDuplexStream)
+Improved read/write interface and error handling in WebDuplexStream
+
+- Enhanced the IStreamToolsRead and IStreamToolsWrite interfaces for better Promise handling
+- Refined readFunction and writeFunction handling to accommodate asynchronous data processing and error propagation
+- Added internal _startReading method to facilitate initial data handling if readFunction is present
+- Maintained backward compatibility while ensuring data continuity when no writeFunction is specified
+
+## 2024-10-13 - 3.1.0 - feat(core)
+Add support for creating Web ReadableStream from a file
+
+- Introduced a new helper function `createWebReadableStreamFromFile` that allows for creating a Web ReadableStream from a file path.
+- Updated exports in `ts/index.ts` to include `nodewebhelpers` which provides the new web stream feature.
+
 ## 2024-10-13 - 3.0.46 - fix(WebDuplexStream)
 Fix errors in WebDuplexStream transformation and test logic
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartstream",
-  "version": "3.0.46",
+  "version": "3.2.5",
   "private": false,
   "description": "A library to simplify the creation and manipulation of Node.js streams, providing utilities for handling transform, duplex, and readable/writable streams effectively in TypeScript.",
   "type": "module",

test/test.ts_web.both.ts

@@ -28,22 +28,22 @@ tap.test('WebDuplexStream should handle transform with a write function', async
   const input = [1, 2, 3, 4, 5];
   const expectedOutput = [2, 4, 6, 8, 10];
 
-  const transformStream = new webstream.WebDuplexStream<number, number>({
+  const webDuplexStream = new webstream.WebDuplexStream<number, number>({
     writeFunction: async (chunk, { push }) => {
       // Push the doubled number into the stream
       push(chunk * 2);
     },
   });
 
-  const writableStream = transformStream.writable.getWriter();
+  const writer = webDuplexStream.writable.getWriter();
-  const readableStream = transformStream.readable.getReader();
+  const reader = webDuplexStream.readable.getReader();
 
   const output: number[] = [];
 
   // Read from the stream asynchronously
   const readPromise = (async () => {
     while (true) {
-      const { value, done } = await readableStream.read();
+      const { value, done } = await reader.read();
       if (done) break;
       if (value !== undefined) {
         output.push(value);
@@ -53,9 +53,9 @@ tap.test('WebDuplexStream should handle transform with a write function', async
 
   // Write to the stream
   for (const num of input) {
-    await writableStream.write(num);
+    await writer.write(num);
   }
-  await writableStream.close();
+  await writer.close();
 
   // Wait for the reading to complete
   await readPromise;

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartstream',
-  version: '3.0.46',
+  version: '3.2.5',
   description: 'A library to simplify the creation and manipulation of Node.js streams, providing utilities for handling transform, duplex, and readable/writable streams effectively in TypeScript.'
 }

ts/index.ts

@@ -11,3 +11,7 @@ export * from './smartstream.functions.js';
 
 import * as plugins from './smartstream.plugins.js';
 export const webstream = plugins.webstream;
+import * as nodewebhelpers from './smartstream.nodewebhelpers.js';
+export {
+  nodewebhelpers,
+}

ts/smartstream.classes.smartduplex.ts

@@ -52,6 +52,29 @@ export class SmartDuplex<TInput = any, TOutput = any> extends Duplex {
     return smartDuplex;
   }
 
+  public static fromWebReadableStream<T = any>(
+    readableStream: ReadableStream<T>
+  ): SmartDuplex<T, T> {
+    const smartDuplex = new SmartDuplex<T, T>({
+      /**
+       * this function is called whenever the stream is being read from and at the same time if nothing is enqueued
+       * therefor it is important to always unlock the reader after reading
+       */
+      readFunction: async () => {
+        const reader = readableStream.getReader();
+        const { value, done } = await reader.read();
+        if (value !== undefined) {
+          smartDuplex.push(value);
+        }
+        reader.releaseLock();
+        if (done) {
+          smartDuplex.push(null);
+        }
+      },
+    });
+    return smartDuplex;
+  }
+
   // INSTANCE
   private backpressuredArray: plugins.lik.BackpressuredArray<TOutput>; // an array that only takes a defined amount of items
   public options: ISmartDuplexOptions<TInput, TOutput>;
@@ -80,11 +103,11 @@ export class SmartDuplex<TInput = any, TOutput = any> extends Duplex {
 
   public async _read(size: number): Promise<void> {
     this.debugLog(`${this.options.name}: read was called`);
-    await this.backpressuredArray.waitForItems();
-    this.debugLog(`${this.options.name}: successfully waited for items.`);
     if (this.options.readFunction) {
       await this.options.readFunction();
     }
+    await this.backpressuredArray.waitForItems();
+    this.debugLog(`${this.options.name}: successfully waited for items.`);
     let canPushMore = true;
     while (this.backpressuredArray.data.length > 0 && canPushMore) {
       const nextChunk = this.backpressuredArray.shift();

ts/smartstream.functions.ts

@@ -1,4 +1,4 @@
-import { Transform, type TransformCallback, type TransformOptions } from 'stream';
+import { type TransformOptions } from 'stream';
 import { SmartDuplex } from './smartstream.classes.smartduplex.js';
 
 export interface AsyncTransformFunction<TInput, TOutput> {

ts/smartstream.nodewebhelpers.ts

@@ -0,0 +1,151 @@
+import * as plugins from './smartstream.plugins.js';
+
+/**
+ * Creates a Web ReadableStream from a file.
+ *
+ * @param filePath - The path to the file to be read
+ * @returns A Web ReadableStream that reads the file in chunks
+ */
+export function createWebReadableStreamFromFile(filePath: string): ReadableStream<Uint8Array> {
+  const fileStream = plugins.fs.createReadStream(filePath);
+
+  return new ReadableStream({
+    start(controller) {
+      // When data is available, enqueue it into the Web ReadableStream
+      fileStream.on('data', (chunk) => {
+        controller.enqueue(chunk as Uint8Array);
+      });
+
+      // When the file stream ends, close the Web ReadableStream
+      fileStream.on('end', () => {
+        controller.close();
+      });
+
+      // If there's an error, error the Web ReadableStream
+      fileStream.on('error', (err) => {
+        controller.error(err);
+      });
+    },
+    cancel() {
+      // If the Web ReadableStream is canceled, destroy the file stream
+      fileStream.destroy();
+    }
+  });
+}
+
+/**
+ * Converts a Web ReadableStream to a Node.js Readable stream.
+ *
+ * @param webStream - The Web ReadableStream to convert
+ * @returns A Node.js Readable stream that reads data from the Web ReadableStream
+ */
+export function convertWebReadableToNodeReadable(webStream: ReadableStream<Uint8Array>): plugins.stream.Readable {
+  const reader = webStream.getReader();
+
+  return new plugins.stream.Readable({
+    async read() {
+      try {
+        const { value, done } = await reader.read();
+        if (done) {
+          this.push(null); // Signal end of stream
+        } else {
+          this.push(Buffer.from(value)); // Convert Uint8Array to Buffer for Node.js Readable
+        }
+      } catch (err) {
+        this.destroy(err); // Handle errors by destroying the stream
+      }
+    }
+  });
+}
+
+/**
+ * Converts a Node.js Readable stream to a Web ReadableStream.
+ *
+ * @param nodeStream - The Node.js Readable stream to convert
+ * @returns A Web ReadableStream that reads data from the Node.js Readable stream
+ */
+export function convertNodeReadableToWebReadable(nodeStream: plugins.stream.Readable): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      nodeStream.on('data', (chunk) => {
+        controller.enqueue(new Uint8Array(chunk));
+      });
+
+      nodeStream.on('end', () => {
+        controller.close();
+      });
+
+      nodeStream.on('error', (err) => {
+        controller.error(err);
+      });
+    },
+    cancel() {
+      nodeStream.destroy();
+    }
+  });
+}
+
+/**
+ * Converts a Web WritableStream to a Node.js Writable stream.
+ *
+ * @param webWritable - The Web WritableStream to convert
+ * @returns A Node.js Writable stream that writes data to the Web WritableStream
+ */
+export function convertWebWritableToNodeWritable(webWritable: WritableStream<Uint8Array>): plugins.stream.Writable {
+  const writer = webWritable.getWriter();
+
+  return new plugins.stream.Writable({
+    async write(chunk, encoding, callback) {
+      try {
+        await writer.write(new Uint8Array(chunk));
+        callback();
+      } catch (err) {
+        callback(err);
+      }
+    },
+    final(callback) {
+      writer.close().then(() => callback()).catch(callback);
+    },
+    destroy(err, callback) {
+      writer.abort(err).then(() => callback(err)).catch(callback);
+    }
+  });
+}
+
+/**
+ * Converts a Node.js Writable stream to a Web WritableStream.
+ *
+ * @param nodeWritable - The Node.js Writable stream to convert
+ * @returns A Web WritableStream that writes data to the Node.js Writable stream
+ */
+export function convertNodeWritableToWebWritable(nodeWritable: plugins.stream.Writable): WritableStream<Uint8Array> {
+  return new WritableStream({
+    write(chunk) {
+      return new Promise((resolve, reject) => {
+        nodeWritable.write(Buffer.from(chunk), (err) => {
+          if (err) {
+            reject(err);
+          } else {
+            resolve();
+          }
+        });
+      });
+    },
+    close() {
+      return new Promise((resolve, reject) => {
+        nodeWritable.end((err) => {
+          if (err) {
+            reject(err);
+          } else {
+            resolve();
+          }
+        });
+      });
+    },
+    abort(reason) {
+      return new Promise((resolve, reject) => {
+        nodeWritable.destroy(reason);
+      });
+    }
+  });
+}

ts/smartstream.plugins.ts

@@ -1,7 +1,8 @@
 // node native
+import * as fs from 'fs';
 import * as stream from 'stream';
 
-export { stream };
+export { fs, stream };
 
 // pushrocks scope
 import * as lik from '@push.rocks/lik';

ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartstream',
-  version: '3.0.46',
+  version: '3.2.5',
   description: 'A library to simplify the creation and manipulation of Node.js streams, providing utilities for handling transform, duplex, and readable/writable streams effectively in TypeScript.'
 }

ts_web/classes.webduplexstream.ts

@@ -1,25 +1,22 @@
 import * as plugins from './plugins.js';
 
-
 // ========================================
-// READ
+// Interfaces for Read functionality
 // ========================================
 export interface IStreamToolsRead<TInput, TOutput> {
   done: () => void;
-  write: (writeArg: TInput) => void;
+  write: (writeArg: TInput) => Promise<void>;
 }
 
 /**
- * the read function is called anytime
+ * The read function is called when data needs to be read into the stream.
- *   -> the WebDuplexStream is being read from
- *      and at the same time if nothing is enqueued
  */
 export interface IStreamReadFunction<TInput, TOutput> {
   (toolsArg: IStreamToolsRead<TInput, TOutput>): Promise<void>;
 }
 
 // ========================================
-// WRITE
+// Interfaces for Write functionality
 // ========================================
 export interface IStreamToolsWrite<TInput, TOutput> {
   truncate: () => void;
@@ -27,15 +24,14 @@ export interface IStreamToolsWrite<TInput, TOutput> {
 }
 
 /**
- * the write function can return something.
+ * The write function is called whenever a chunk is written to the stream.
- * It is called anytime a chunk is written to the stream.
  */
 export interface IStreamWriteFunction<TInput, TOutput> {
   (chunkArg: TInput, toolsArg: IStreamToolsWrite<TInput, TOutput>): Promise<any>;
 }
 
 export interface IStreamFinalFunction<TInput, TOutput> {
-  (toolsArg: IStreamToolsWrite<TInput, TOutput>): Promise<TOutput>;
+  (toolsArg: IStreamToolsWrite<TInput, TOutput>): Promise<TOutput | void>;
 }
 
 export interface WebDuplexStreamOptions<TInput, TOutput> {
@@ -45,12 +41,90 @@ export interface WebDuplexStreamOptions<TInput, TOutput> {
 }
 
 export class WebDuplexStream<TInput = any, TOutput = any> extends TransformStream<TInput, TOutput> {
+  // INSTANCE
+  options: WebDuplexStreamOptions<TInput, TOutput>;
+
+  constructor(optionsArg: WebDuplexStreamOptions<TInput, TOutput>) {
+    super({
+      async start(controller) {
+        // Optionally initialize any state here
+      },
+      async transform(chunk, controller) {
+        if (optionsArg?.writeFunction) {
+          const tools: IStreamToolsWrite<TInput, TOutput> = {
+            truncate: () => controller.terminate(),
+            push: (pushArg: TOutput) => controller.enqueue(pushArg),
+          };
+
+          try {
+            const writeReturnChunk = await optionsArg.writeFunction(chunk, tools);
+            if (writeReturnChunk !== undefined && writeReturnChunk !== null) {
+              controller.enqueue(writeReturnChunk);
+            }
+          } catch (err) {
+            controller.error(err);
+          }
+        } else {
+          // If no writeFunction is provided, pass the chunk through
+          controller.enqueue(chunk as unknown as TOutput);
+        }
+      },
+      async flush(controller) {
+        if (optionsArg?.finalFunction) {
+          const tools: IStreamToolsWrite<TInput, TOutput> = {
+            truncate: () => controller.terminate(),
+            push: (pushArg) => controller.enqueue(pushArg),
+          };
+
+          try {
+            const finalChunk = await optionsArg.finalFunction(tools);
+            if (finalChunk) {
+              controller.enqueue(finalChunk);
+            }
+          } catch (err) {
+            controller.error(err);
+          } finally {
+            controller.terminate();
+          }
+        } else {
+          controller.terminate();
+        }
+      },
+    });
+
+    this.options = optionsArg;
+
+    // Start producing data if readFunction is provided
+    if (this.options.readFunction) {
+      this._startReading();
+    }
+  }
+
+  private async _startReading() {
+    const writable = this.writable;
+    const writer = writable.getWriter();
+
+    const tools: IStreamToolsRead<TInput, TOutput> = {
+      done: () => writer.close(),
+      write: async (writeArg) => await writer.write(writeArg),
+    };
+
+    try {
+      await this.options.readFunction(tools);
+    } catch (err) {
+      writer.abort(err);
+    } finally {
+      writer.releaseLock();
+    }
+  }
+
+  // Static method example (adjust as needed)
   static fromUInt8Array(uint8Array: Uint8Array): WebDuplexStream<Uint8Array, Uint8Array> {
     const stream = new WebDuplexStream<Uint8Array, Uint8Array>({
       writeFunction: async (chunk, { push }) => {
         push(chunk); // Directly push the chunk as is
         return null;
-      }
+      },
     });
 
     const writer = stream.writable.getWriter();
@@ -58,99 +132,4 @@ export class WebDuplexStream<TInput = any, TOutput = any> extends TransformStrea
 
     return stream;
   }
-  
+}
-  // INSTANCE
-  options: WebDuplexStreamOptions<TInput, TOutput>;
-
-  constructor(optionsArg: WebDuplexStreamOptions<TInput, TOutput>) {
-    // here we call into the official web stream api
-    super({
-      async transform(chunk, controller) {
-        // Transformation logic remains unchanged
-        if (optionsArg?.writeFunction) {
-          const tools: IStreamToolsWrite<TInput, TOutput> = {
-            truncate: () => controller.terminate(),
-            push: (pushArg: TOutput) => controller.enqueue(pushArg),
-          };
-        
-          try {
-            const writeReturnChunk = await optionsArg.writeFunction(chunk, tools);
-            if (writeReturnChunk) { // return chunk is optional
-              controller.enqueue(writeReturnChunk);
-            }
-          } catch (err) {
-            controller.error(err);
-          }
-        } else {
-          controller.error(new Error('No write function provided'));
-        }
-      },
-      async flush(controller) {
-        // Flush logic remains unchanged
-        if (optionsArg?.finalFunction) {
-          const tools: IStreamToolsWrite<TInput, TOutput> = {
-            truncate: () => controller.terminate(),
-            push: (pipeObject) => controller.enqueue(pipeObject),
-          };
-      
-          optionsArg.finalFunction(tools)
-            .then(finalChunk => {
-              if (finalChunk) {
-                controller.enqueue(finalChunk);
-              }
-            })  
-            .catch(err => controller.error(err))
-            .finally(() => controller.terminate());
-        } else {
-          controller.terminate();
-        }
-      }
-    });
-
-    this.options = optionsArg;
-  }
-
-  // Method to create a custom readable stream that integrates the readFunction
-  // readFunction is executed whenever the stream is being read from and nothing is enqueued
-  getCustomReadableStream() {
-    const readableStream = this.readable;
-    const options = this.options;
-    const customReadable = new ReadableStream({
-      async pull(controller) {
-        const reader = readableStream.getReader();
-
-        // Check the current state of the original stream
-        const { value, done } = await reader.read();
-        reader.releaseLock();
-
-        if (done) {
-          // If the original stream is done, close the custom readable stream
-          controller.close();
-        } else {
-          if (value) {
-            // If there is data in the original stream, enqueue it and do not execute the readFunction
-            controller.enqueue(value);
-          } else if (options.readFunction) {
-            // If the original stream is empty, execute the readFunction and read again
-            await options.readFunction({
-              done: () => controller.close(),
-              write: (writeArg) => controller.enqueue(writeArg),
-            });
-            
-            const newReader = readableStream.getReader();
-            const { value: newValue, done: newDone } = await newReader.read();
-            newReader.releaseLock();
-
-            if (newDone) {
-              controller.close();
-            } else {
-              controller.enqueue(newValue);
-            }
-          }
-        }
-      }
-    });
-
-    return customReadable;
-  }
-}