fix(gulp-function): correct forFirst execution behavior, improve async error handling, and modernize package metadata

ts/00_commitinfo_data.ts

@@ -1,8 +1,8 @@
 /**
- * autocreated commitinfo by @pushrocks/commitinfo
+ * autocreated commitinfo by @push.rocks/commitinfo
  */
 export const commitinfo = {
   name: '@push.rocks/gulp-function',
-  version: '3.0.7',
-  description: 'accepts a function call as parameter to execute in gulp pipeline'
+  version: '3.0.8',
+  description: 'A Gulp plugin to execute functions within a Gulp task pipeline.'
 }

ts/index.ts

@@ -1,86 +1,100 @@
-import * as smartpromise from '@push.rocks/smartpromise';
-import * as through2 from 'through2';
-import { Transform } from 'stream';
+import type { Transform } from 'node:stream';
+import through2 from 'through2';
 
 export type TExecutionMode = 'forEach' | 'forFirst' | 'atEnd';
+export type TGulpFunctionEncoding = BufferEncoding | string | null;
+export type TGulpFunctionResult = PromiseLike<unknown> | unknown;
 
-export interface IPromiseFunction {
-  (file?, enc?): PromiseLike<any>;
+export interface IPromiseFunction<TFile = unknown> {
+  (file?: TFile | null, enc?: TGulpFunctionEncoding): TGulpFunctionResult;
 }
 
-let defaultExport = (
-  functionsToExecuteArg: IPromiseFunction | IPromiseFunction[],
+type TTransformCallback = (errorArg?: Error | null, dataArg?: unknown) => void;
+type TFlushCallback = (errorArg?: Error | null) => void;
+
+const normalizeError = (errorArg: unknown): Error => {
+  return errorArg instanceof Error ? errorArg : new Error(String(errorArg));
+};
+
+const defaultExport = <TFile = unknown>(
+  functionsToExecuteArg: IPromiseFunction<TFile> | Array<IPromiseFunction<TFile>>,
   executionModeArg: TExecutionMode = 'forEach'
 ): Transform => {
-  let promiseArray = [];
-  let runFunction = function(functionArg, file, enc) {
-    let returnValue = functionArg(file, enc);
-    if (typeof returnValue !== 'undefined' && typeof returnValue.then !== 'undefined') {
-      promiseArray.push(returnValue);
-    }
+  const runFunction = async (
+    functionArg: IPromiseFunction<TFile>,
+    fileArg: TFile | null,
+    encArg: TGulpFunctionEncoding
+  ): Promise<void> => {
+    await functionArg(fileArg, encArg);
   };
 
-  let checkAndRunFunction = function(file, enc) {
+  const checkAndRunFunction = async (
+    fileArg: TFile | null,
+    encArg: TGulpFunctionEncoding
+  ): Promise<void> => {
     if (typeof functionsToExecuteArg === 'function') {
-      runFunction(functionsToExecuteArg, file, enc);
+      await runFunction(functionsToExecuteArg, fileArg, encArg);
     } else if (Array.isArray(functionsToExecuteArg)) {
-      for (let anyFunction in functionsToExecuteArg) {
-        runFunction(functionsToExecuteArg[anyFunction], file, enc);
-      }
+      await Promise.all(
+        functionsToExecuteArg.map(async (functionArg) => runFunction(functionArg, fileArg, encArg))
+      );
     } else {
       throw new Error('gulp-callfunction: something is strange with the given arguments');
     }
-    return Promise.all(promiseArray);
   };
 
   let hasExecutedOnce = false;
-  let forEach = function(file, enc, cb) {
-    // the forEach function is called for every chunk
+  const transformFunction = (fileArg: TFile, encArg: BufferEncoding, cbArg: TTransformCallback) => {
     switch (executionModeArg) {
       case 'forEach':
-        checkAndRunFunction(file, enc).then(function() {
-          cb(null, file);
-        });
+        checkAndRunFunction(fileArg, encArg).then(
+          () => cbArg(null, fileArg),
+          (errorArg) => cbArg(normalizeError(errorArg))
+        );
         break;
       case 'forFirst':
-        if (hasExecutedOnce) {
-          checkAndRunFunction(file, enc).then(function() {
-            cb(null, file);
-          });
+        if (!hasExecutedOnce) {
+          hasExecutedOnce = true;
+          checkAndRunFunction(fileArg, encArg).then(
+            () => cbArg(null, fileArg),
+            (errorArg) => cbArg(normalizeError(errorArg))
+          );
         } else {
-          cb(null, file);
+          cbArg(null, fileArg);
         }
-        hasExecutedOnce = true;
         break;
       case 'atEnd':
-        cb();
+        cbArg(null, fileArg);
         break;
       default:
+        cbArg(null, fileArg);
         break;
     }
   };
 
-  let atEnd = function(cb) {
+  const flushFunction = (cbArg: TFlushCallback) => {
     if (executionModeArg === 'atEnd') {
-      checkAndRunFunction(null, null).then(function() {
-        cb();
-      });
+      checkAndRunFunction(null, null).then(
+        () => cbArg(),
+        (errorArg) => cbArg(normalizeError(errorArg))
+      );
     } else {
-      cb();
+      cbArg();
     }
   };
-  return through2.obj(forEach, atEnd);
+
+  return through2.obj(transformFunction, flushFunction) as Transform;
 };
 
-export let forEach = (funcArg: IPromiseFunction) => {
+export const forEach = <TFile = unknown>(funcArg: IPromiseFunction<TFile>): Transform => {
   return defaultExport(funcArg, 'forEach');
 };
 
-export let forFirst = (funcArg: IPromiseFunction) => {
+export const forFirst = <TFile = unknown>(funcArg: IPromiseFunction<TFile>): Transform => {
   return defaultExport(funcArg, 'forFirst');
 };
 
-export let atEnd = (funcArg: IPromiseFunction) => {
+export const atEnd = <TFile = unknown>(funcArg: IPromiseFunction<TFile>): Transform => {
   return defaultExport(funcArg, 'atEnd');
 };