@push.rocks/smartgulp is a tiny, modern Gulp-style file pipeline for TypeScript and Node.js projects. It gives you the familiar src(...).pipe(...).pipe(dest(...)) workflow without pulling in the full Gulp task runner: read files by glob, process them as SmartFile objects, write them somewhere else, or replace them in place.

Use it when you want stream-based build steps that stay small, explicit, and easy to compose with regular Node streams.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Installation

Install it as a development dependency:

pnpm add -D @push.rocks/smartgulp

What It Provides

@push.rocks/smartgulp exports three pipeline primitives:

API	Purpose
`src(patterns)`	Reads matching files from disk and emits `SmartFile` objects into an object-mode stream.
`dest(directory)`	Writes incoming `SmartFile` objects to a target directory.
`replace()`	Writes incoming `SmartFile` objects back to their original location.

The files flowing through a smartgulp pipeline are SmartFile instances from @push.rocks/smartfile. That means transforms can inspect paths, read or mutate contents, and then pass each file along to the next stream.

Quick Start

Copy Markdown files from one directory to another:

import { src, dest } from '@push.rocks/smartgulp';

src(['./docs/**/*.md']).pipe(dest('./dist/docs'));

src() accepts an array of glob patterns. Each matching file is emitted as a SmartFile, and dest() writes every received file to the target directory.

Transform Files

Because smartgulp uses object-mode streams, you can use any transform that accepts and emits SmartFile objects. The companion package @push.rocks/gulp-function is a convenient fit:

import { src, dest } from '@push.rocks/smartgulp';
import * as gulpFunction from '@push.rocks/gulp-function';
import type { SmartFile } from '@push.rocks/smartfile';

src(['./src/**/*.txt'])
  .pipe(
    gulpFunction.forEach(async (fileArg: SmartFile) => {
      const currentContent = fileArg.contents.toString();
      fileArg.contents = Buffer.from(`Processed by smartgulp\n\n${currentContent}`);
    })
  )
  .pipe(dest('./dist'));

This pattern keeps transformations focused: read files with src(), mutate or inspect each SmartFile, then write the result with dest().

Replace Files In Place

Use replace() when a transform should update the original files instead of writing to a new output directory:

import { src, replace } from '@push.rocks/smartgulp';
import * as gulpFunction from '@push.rocks/gulp-function';
import type { SmartFile } from '@push.rocks/smartfile';

src(['./content/**/*.md'])
  .pipe(
    gulpFunction.forEach(async (fileArg: SmartFile) => {
      fileArg.contents = Buffer.from(
        fileArg.contents.toString().replaceAll('http://', 'https://')
      );
    })
  )
  .pipe(replace());

replace() calls write() on each incoming SmartFile, so it persists the modified contents back to the file's known path.

Wait For A Pipeline To Finish

Node streams are asynchronous. If your script needs to wait for the final file before exiting or starting the next step, add an end-of-stream transform:

import { src, dest } from '@push.rocks/smartgulp';
import * as gulpFunction from '@push.rocks/gulp-function';
import * as smartpromise from '@push.rocks/smartpromise';

const done = smartpromise.defer<void>();

src(['./test/testfiles/**/*.md'])
  .pipe(dest('./dist/testfiles'))
  .pipe(
    gulpFunction.atEnd(async () => {
      done.resolve();
    })
  );

await done.promise;

This is useful in tests, build scripts, and one-off automation where the surrounding code needs a promise.

Glob Behavior

src() resolves each provided pattern from the current working directory. It derives the static base directory before the first glob segment, loads that directory, and filters files with minimatch.

Examples:

Pattern	Base directory	Matched portion
`./src/*/.ts`	`./src`	`*/.ts`
`./docs/*.md`	`./docs`	`*.md`
`./package.json`	`.`	`package.json`

Dotfiles are included in matching, so patterns can pick up files such as .config.json when the glob allows them.

Typical Use Cases

Copy assets into build directories.
Run text or metadata transformations across many files.
Update generated files in place.
Build small project-specific pipelines without a full task runner.
Compose SmartFile-aware transforms with regular Node stream flow.

API Reference

`src(patterns: string[])`

Creates an object-mode Transform stream and asynchronously pushes every matching SmartFile into it. The stream ends after all matched files have been pushed.

`dest(directory: string)`

Creates an object-mode writable stream. Each incoming SmartFile is written to directory through SmartFile.writeToDir().

`replace()`

Creates an object-mode writable stream. Each incoming SmartFile is persisted through SmartFile.write().

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@push.rocks/smartgulp