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

test/test.node.ts

@@ -0,0 +1,58 @@
+import { finished } from 'node:stream/promises';
+
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import gulp from 'gulp';
+import * as gulpFunction from '../ts/index.js';
+
+interface ITestVinylFile {
+  relative: string;
+}
+
+tap.test('should run through smoothly with forEach', async () => {
+  const processedFiles: string[] = [];
+  const stream = gulp.src('./test/testfiles/*.md').pipe(
+    gulpFunction.forEach<ITestVinylFile>(async (fileArg) => {
+      if (fileArg) {
+        processedFiles.push(fileArg.relative);
+      }
+    })
+  );
+
+  stream.resume();
+  await finished(stream);
+  expect(processedFiles).toHaveLength(18);
+});
+
+tap.test('should run only once with forFirst', async () => {
+  const processedFiles: string[] = [];
+  const stream = gulp.src('./test/testfiles/*.md').pipe(
+    gulpFunction.forFirst<ITestVinylFile>(async (fileArg) => {
+      if (fileArg) {
+        processedFiles.push(fileArg.relative);
+      }
+    })
+  );
+
+  stream.resume();
+  await finished(stream);
+  expect(processedFiles).toHaveLength(1);
+});
+
+tap.test('should run once after all files with atEnd', async () => {
+  let atEndCounter = 0;
+  let passthroughCounter = 0;
+  const stream = gulp.src('./test/testfiles/*.md').pipe(
+    gulpFunction.atEnd(async () => {
+      atEndCounter++;
+    })
+  );
+
+  stream.on('data', () => {
+    passthroughCounter++;
+  });
+  await finished(stream);
+  expect(atEndCounter).toEqual(1);
+  expect(passthroughCounter).toEqual(18);
+});
+
+export default tap.start();