feat: Support replacing async without streams

.github/workflows/node.js.yml

@@ -5,9 +5,9 @@ name: CI
 
 on:
   pull_request:
-    branches: [ "*" ]
+    branches: ["*"]
   push:
-    branches: [ "main" ]
+    branches: ["main"]
 
 jobs:
   build:
@@ -19,13 +19,13 @@ jobs:
       - name: Use Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20.x
-          cache: 'npm'
+          node-version: 24.x
+          cache: "npm"
       - name: npm install, build, and test
         run: |
           npm ci
           npm run build:all
-          npm test
+          npm run test:ci
       - name: Archive build
         uses: actions/upload-artifact@v4
         with:
@@ -44,18 +44,21 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [ 16.x, 18.x, 20.x, 22.x ]
+        node-version: [20.x, 22.x, 24.x]
 
     steps:
       - uses: actions/checkout@v4
       - name: Use Node.js
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
-      - name: npm install and test
+          cache: "npm"
+      - name: Download build
+        uses: actions/download-artifact@v4
+        with:
+          name: build
+          path: dist
+      - name: Run tests against build
         run: |
           npm ci
-          cd tests
-          npm ci
-          npm run test:ci
+          npm run test:build

.prettierignore

@@ -0,0 +1,6 @@
+dist
+node_modules
+coverage
+benchmarks/plots
+package-lock.json
+*.md

.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["esbenp.prettier-vscode"]
+}

.vscode/settings.json

@@ -0,0 +1,22 @@
+{
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.formatOnSave": true,
+  "editor.formatOnPaste": true,
+  "files.eol": "\n",
+  "prettier.useEditorConfig": true,
+  "[markdown]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[jsonc]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
+}

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Louis Wilke
+Copyright (c) 2025 Louis Wilke
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -7,7 +7,7 @@
 
 A high performance `{{ template }}` replace stream working on binary or string streams.
 
-This module is written in pure TypeScript, consists of only 191 lines of code (including type
+This module is written in pure TypeScript, consists of only 226 lines of code (including type
 definitions) and has no other dependencies. It is flexible and allows replacing an arbitrary wide
 range of template variables while being extremely fast (we reached over 20GiB/s,
 see [Benchmarks](#benchmarks)).
@@ -22,11 +22,10 @@ This module contains type definitions and also an `.mjs` file for maximum compat
 
 ### Supported Node.js Versions
 
-The following Node.js versions are tested to work with the package. Older versions are not tested
-but should still be able to use it.
+The following Node.js versions are tested to work with the package. Older versions are not tested but should still be able to use it.
 
-| 16.x                                                                                                                                                                                            | 18.x                                                                                                                                                                                            | 20.x                                                                                                                                                                                            | 22.x                                                                                                                                                                                            |
-|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 18.x | 20.x | 22.x | 24.x |
+| --- | --- | --- | --- |
 | [![CI](https://github.com/SoulKa/template-replace-stream/actions/workflows/node.js.yml/badge.svg?branch=main)](https://github.com/SoulKa/template-replace-stream/actions/workflows/node.js.yml) | [![CI](https://github.com/SoulKa/template-replace-stream/actions/workflows/node.js.yml/badge.svg?branch=main)](https://github.com/SoulKa/template-replace-stream/actions/workflows/node.js.yml) | [![CI](https://github.com/SoulKa/template-replace-stream/actions/workflows/node.js.yml/badge.svg?branch=main)](https://github.com/SoulKa/template-replace-stream/actions/workflows/node.js.yml) | [![CI](https://github.com/SoulKa/template-replace-stream/actions/workflows/node.js.yml/badge.svg?branch=main)](https://github.com/SoulKa/template-replace-stream/actions/workflows/node.js.yml) |
 
 ## Usage
@@ -38,7 +37,7 @@ returns a replacement value for a given template string.
 ### JavaScript
 
 ```js
-const {TemplateReplaceStream} = require("template-replace-stream");
+const { TemplateReplaceStream } = require("template-replace-stream");
 const fs = require("node:fs");
 const path = require("node:path");
 
@@ -53,12 +52,13 @@ const templateReplaceStream = new TemplateReplaceStream(variables);
 // connect the streams and put the template replace stream in the middle
 readStream.pipe(templateReplaceStream).pipe(writeStream);
 writeStream.on("finish", () => console.log("Finished writing example.txt"));
+
 ```
 
 ### TypeScript
 
 ```ts
-import {TemplateReplaceStream} from "template-replace-stream";
+import { TemplateReplaceStream } from "template-replace-stream";
 import fs from "node:fs";
 import path from "node:path";
 
@@ -73,6 +73,7 @@ const templateReplaceStream = new TemplateReplaceStream(variables);
 // connect the streams and put the template replace stream in the middle
 readStream.pipe(templateReplaceStream).pipe(writeStream);
 writeStream.on("finish", () => console.log("Finished writing example.txt"));
+
 ```
 
 ### Advanced
@@ -88,11 +89,11 @@ into a stream before.
 <summary>Advanced Example Code</summary>
 
 ```ts
-import {StringSource, TemplateReplaceStream} from "template-replace-stream";
+import { StringSource, TemplateReplaceStream } from "template-replace-stream";
 import fs from "node:fs";
 import path from "node:path";
 import sloc from "sloc";
-import {Project, ts} from "ts-morph";
+import { Project, ts } from "ts-morph";
 
 const rootDir = path.join(__dirname, "..");
 const exampleFiles = ["javascript-example.js", "typescript-example.ts", "generate-readme.ts"];
@@ -104,7 +105,9 @@ const loc = codeInfo.total - codeInfo.comment - codeInfo.empty;
 const optionsDefinition = extractTypeDefinition("TemplateReplaceStreamOptions", sourceFilePath);
 
 // the map of example files and their read streams and further template variables
-const templateMap = new Map<string, StringSource>(exampleFiles.map((file) => [file, openExampleStream(file)]));
+const templateMap = new Map<string, StringSource>(
+  exampleFiles.map((file) => [file, openExampleStream(file)])
+);
 templateMap.set("loc", loc.toString());
 templateMap.set("options-definition", optionsDefinition);
 
@@ -135,9 +138,10 @@ function extractTypeDefinition(typeName: string, filePath: string) {
   const sourceFile = new Project().addSourceFileAtPath(filePath);
   const typeNode = sourceFile.getTypeAlias(typeName)?.compilerNode;
   if (!typeNode) throw new Error(`Type alias ${typeName} not found.`);
-  const printer = ts.createPrinter({removeComments: false});
+  const printer = ts.createPrinter({ removeComments: false });
   return printer.printNode(ts.EmitHint.Unspecified, typeNode, sourceFile.compilerNode);
 }
+
 ```
 
 </details>
@@ -149,26 +153,26 @@ function extractTypeDefinition(typeName: string, filePath: string) {
  * Options for the template replace stream.
  */
 export type TemplateReplaceStreamOptions = {
-  /** Default: `false`. If true, the stream creates logs on debug level */
-  log: boolean;
-  /**
-   * Default: `false`. If true, the stream throws an error when a template variable has no
-   * replacement value. Takes precedence over `removeUnmatchedTemplate`.
-   */
-  throwOnUnmatchedTemplate: boolean;
-  /**
-   * Default: `100`. The maximum length of a variable name between a start and end pattern including
-   * whitespaces around it. Any variable name longer than this length is ignored, i.e. the search
-   * for the end pattern canceled and the stream looks for the next start pattern.
-   * Note that a shorter length improves performance but may not find all variables.
-   */
-  maxVariableNameLength: number;
-  /** Default: `'{{'`. The start pattern of a template string either as string or buffer */
-  startPattern: string | Buffer;
-  /** Default: `'}}'`. The end pattern of a template string either as string or buffer */
-  endPattern: string | Buffer;
-  /** Any options for the lower level {@link Transform} stream. Do not replace transform or flush */
-  streamOptions?: TransformOptions;
+    /** Default: `false`. If true, the stream creates logs on debug level */
+    log: boolean;
+    /**
+     * Default: `false`. If true, the stream throws an error when a template variable has no
+     * replacement value. Takes precedence over `removeUnmatchedTemplate`.
+     */
+    throwOnUnmatchedTemplate: boolean;
+    /**
+     * Default: `100`. The maximum length of a variable name between a start and end pattern including
+     * whitespaces around it. Any variable name longer than this length is ignored, i.e. the search
+     * for the end pattern canceled and the stream looks for the next start pattern.
+     * Note that a shorter length improves performance but may not find all variables.
+     */
+    maxVariableNameLength: number;
+    /** Default: `'{{'`. The start pattern of a template string either as string or buffer */
+    startPattern: string | Buffer;
+    /** Default: `'}}'`. The end pattern of a template string either as string or buffer */
+    endPattern: string | Buffer;
+    /** Any options for the lower level {@link Transform} stream. Do not replace transform or flush */
+    streamOptions?: TransformOptions;
 };
 ```
 
@@ -210,12 +214,16 @@ perform too well in the 1MiB file. We will keep optimizing for that.
 
 ## Changelog
 
-### Latest
+### 2.2.0
 
-- Support `async` replacement value functions (`Promise<StringSource>` as return value)
+- Add `TemplateReplaceStream.replaceAsync()` that directly returns a `Promise<Buffer>` with the result
+- Add `TemplateReplaceStream.replaceStringAsync()` that directly returns a `Promise<string>` with the result
+- Drop support for Node.js 16
+- Add CI on Node.js 24
 
 ### 2.1.2
 
+- Support `async` replacement value functions (`Promise<StringSource>` as return value)
 - Add CI to repository
 - Update README
 

benchmarks/benchmark.test.ts

@@ -1,36 +1,39 @@
-import {Readable} from 'stream';
-import {describe, expect, it} from "@jest/globals";
-import {FixedChunkSizeReadStream} from "../tests/stream";
+import { Readable } from "stream";
+import { describe, expect, it } from "vitest";
+import { FixedChunkSizeReadStream } from "../tests/stream";
 
 async function stringStreamToString(stream: Readable) {
   return await new Promise<string>((resolve, reject) => {
     let string = "";
-    stream.on('data', (chunk: string) => string += chunk);
-    stream.on('end', () => resolve(string));
-    stream.on('error', reject);
+    stream.on("data", (chunk: string) => (string += chunk));
+    stream.on("end", () => resolve(string));
+    stream.on("error", reject);
   });
 }
 
-describe('replacestream', () => {
-  it('should replace variables in a stream', async () => {
+describe("replacestream", () => {
+  it("should replace variables in a stream", async () => {
     // Arrange
-    const replaceStream = (await import('replacestream')).default;
-    const templateString = 'Hello, {{ name }}!';
-    const variableMap = new Map([['name', 'World']]);
+    const replaceStream = (await import("replacestream")).default;
+    const templateString = "Hello, {{ name }}!";
+    const variableMap = new Map([["name", "World"]]);
     const readable: Readable = new FixedChunkSizeReadStream(templateString, 1);
-    const transformStream = replaceStream(new RegExp(`\\{\\{(.*)}}`), (match, key) => variableMap.get(key.trim()) ?? match);
+    const transformStream = replaceStream(
+      new RegExp(`\\{\\{(.*)}}`),
+      (match, key) => variableMap.get(key.trim()) ?? match
+    );
 
     // Act
     const result = await stringStreamToString(readable.pipe(transformStream));
 
     // Assert
-    expect(result).toBe('Hello, World!');
+    expect(result).toBe("Hello, World!");
   });
 
-  it('should not modify the stream if there are no template variables', async () => {
+  it("should not modify the stream if there are no template variables", async () => {
     // Arrange
-    const replaceStream = (await import('replacestream')).default;
-    const templateString = 'Hello, World!';
+    const replaceStream = (await import("replacestream")).default;
+    const templateString = "Hello, World!";
     const readable: Readable = new FixedChunkSizeReadStream(templateString, 1);
     const transformStream = replaceStream(new RegExp(`\\{\\{(.*)}}`), (match, key) => match);
 
@@ -41,10 +44,10 @@ describe('replacestream', () => {
     expect(result).toBe(templateString);
   });
 
-  it('should not modify the string if the template variables are unresolved', async () => {
+  it("should not modify the string if the template variables are unresolved", async () => {
     // Arrange
-    const replaceStream = (await import('replacestream')).default;
-    const templateString = 'Hello, {{ name }}!';
+    const replaceStream = (await import("replacestream")).default;
+    const templateString = "Hello, {{ name }}!";
     const readable: Readable = new FixedChunkSizeReadStream(templateString, 1);
     const transformStream = replaceStream(new RegExp(`\\{\\{(.*)}}`), (match, key) => match);
 
@@ -54,4 +57,4 @@ describe('replacestream', () => {
     // Assert
     expect(result).toBe(templateString);
   });
-});
+});