warpzone

Slip into the warp and erase the tedious parts from time and space—

warpzone is a light toolbelt with an emphasis on visually semantic code, focused on the most common verbose tasks in file handling—especially tasks like those found in build pipelines.

How Does a Pattern Go Into the Warpzone?

A pattern belongs in warpzone if:

• It reduces verbosity by magnitudes.
• It simplifies a cognitively overwhelming pattern.
• It improves the semantic readability of a document.
• It meaningfully aids in refactoring or experimentation.

Semantic and Minimal

warpzone is a highly curated toolbelt, built to speed up the tasks you repeat across file handling, content transformation, and pipeline work. Its design emphasizes clear, approachable wording and structure—so when you read a document, the meaning is visible on the surface, not buried in complexity.

Features

sweep( baseDir , globExt )

A wrapper around glob(), designed to simplify path handling by automatically prepending the root directory to all results.

Think of it as a "smart glob." I called this pattern sweep to avoid confusion with raw glob terminology and to highlight its enhanced output.

glob( globExt )

A passthrough to fast-glob, included to support sweep() and provide a default globbing utility.

merge( files )

Takes a list of files and concatenates their contents, with optional delineators between each file.

Supports:

• Sequential merging
• Parallel merging
• Parallel merging with guaranteed order

Semantic Iterative Hooks

These may seem trivial at a glance, but they carry real philosophical weight.
Working with loops—especially async loops—often introduces structural friction. Switching from synchronous to asynchronous patterns or from sequential to parallel requires not just changing the logic but refactoring brackets and control flow.

each( array, ( item ) => {...} )

Synchronous iteration.

sequential( items, async ( item ) => {...})

Async sequential iteration.

parallel(array, async ( item ) => {...})

Async parallel iteration.

Why this matters:

• Different iteration patterns create different bracket structures, complicating refactoring.
• Async behavior in loops is often unclear, especially in nested code.
• With warpzone, changing from sequential to parallel (or adding/removing async) only requires changing the function name—not reworking the control flow.
• Semantic naming makes intent obvious at a glance.

hash ( string )

SHA-256 hash of input string.

setExt ( path, ext )

Replace a file's extension.

noExt (path)

Strip a file's extension.

template ( string, replacements )

Apply multiple replacements to a string.

Install

npm install warpzone

Example Usage

Here's an example from one of my own build pipelines, which I hope helps demonstrate the value of warpzone.

import fs from "fs/promises";
import path from "path";
import { minify as minifyJs } from "terser";
import wz from "warpzone";

const replacements = [
  { search: "{{COLOR_THEME}}", replace: btoa('#F23A90') },
  { search: "{{EMAIL_64}}", replace: btoa('awesome-email@gmail.com') }
];

export async function buildJs(inputDir, outputDir, minify) {

  const jsAssets = [];
  const batchJsDir = inputDir;
  const jsFiles = await wz.sweep(batchJsDir, '**/*.{mjs,js}');

// This step stays sequential to prepare assets before handoff to the HTML builder.
  wz.each(jsFiles, (file) => {
    const relativePath = path.relative(batchJsDir, file);
    jsAssets.push({
      src: `/gen/js/${relativePath}`,
      id: relativePath,
      loadMode: "defer",
      ...(relativePath.endsWith(".mjs") && { isModule: true })
    });
  });

  // Heavy file processing can happen in parallel
  const pipelinePromise = wz.parallel(jsFiles, async (file) => {
    const relativePath = path.relative(batchJsDir, file);
    const outputPath = path.join(outputDir, relativePath);
    await fs.mkdir(path.dirname(outputPath), { recursive: true });
    let content = await fs.readFile(file, 'utf-8');
    content = wz.template(content, replacements);
    if (minify) content = (await minifyJs(content)).code;
    await fs.writeFile(outputPath, content);
  });

  return { jsAssets, pipelinePromise };
}

warpzone handles the repetitive structure so even complex build logic stays clear.

Why the name?

You know why...

License

MIT