or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

callback-api.mdindex.mdstream-api.mdsync-api.md
tile.json

tessl/npm-stream-transform

Object transformations implementing the Node.js stream.Transform API

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/stream-transform@3.4.x

To install, run

npx @tessl/cli install tessl/npm-stream-transform@3.4.0

index.mddocs/

Stream Transform

Stream Transform is a Node.js stream transformation framework that extends the native stream.Transform API to provide object transformations with multiple consumption patterns. It offers stream-based, callback-based, and synchronous APIs for scalable data processing.

Package Information

  • Package Name: stream-transform
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install stream-transform

Core Imports

ESM (ES Modules):

import { transform, Transformer } from "stream-transform";
import { transform as syncTransform } from "stream-transform/sync";

// Default export (same as named export)
import transform from "stream-transform";

CommonJS:

const { transform, Transformer } = require("stream-transform");
const { transform: syncTransform } = require("stream-transform/sync");

Browser ESM:

import { transform, Transformer } from "stream-transform/browser/esm";
import { transform as syncTransform } from "stream-transform/browser/esm/sync";

Basic Usage

import { transform } from "stream-transform";
import { transform as syncTransform } from "stream-transform/sync";

// Stream API - for scalable processing
const transformer = transform((record) => {
  record.push(record.shift()); // Move first element to end
  return record;
});

// Callback API - for convenience with small datasets
transform([
  ["a", "b", "c"],
  ["1", "2", "3"]
], (record) => record.join("|"), (err, results) => {
  console.log(results); // ["a|b|c", "1|2|3"]
});

// Sync API - for synchronous processing
const results = syncTransform([
  ["a", "b", "c"],
  ["1", "2", "3"]
], (record) => record.join("|"));
console.log(results); // ["a|b|c", "1|2|3"]

Architecture

Stream Transform is built around several key components:

  • Transform Stream: Extends Node.js stream.Transform for scalable data processing
  • Handler Functions: User-defined transformation logic supporting sync, async, and promise-based patterns
  • Execution Modes: Stream, callback, and synchronous APIs for different use cases
  • Parallel Processing: Configurable concurrency for asynchronous transformations
  • State Management: Built-in tracking of transformation progress and statistics
  • Multi-format Support: Available as ESM, CommonJS, UMD, IIFE, and browser builds

Capabilities

Stream API

Core streaming transformation functionality for scalable data processing. Ideal for large datasets and real-time processing pipelines.

function transform<T, U>(handler: Handler<T, U>, callback?: Callback): Transformer;
function transform<T, U>(options: Options, handler: Handler<T, U>, callback?: Callback): Transformer;

class Transformer extends stream.Transform {
  constructor(options: Options);
  readonly options: Options;
  readonly state: State;
}

Stream API

Callback API

Convenient callback-based API for processing data arrays with automatic result collection. Perfect for small to medium datasets where convenience is prioritized.

function transform<T, U>(
  records: Array<T>, 
  handler: Handler<T, U>, 
  callback?: Callback
): Transformer;
function transform<T, U>(
  records: Array<T>, 
  options: Options, 
  handler: Handler<T, U>, 
  callback?: Callback
): Transformer;

Callback API

Synchronous API

Synchronous data transformation for immediate processing of data arrays. Best for small datasets where blocking execution is acceptable.

function transform<T, U>(records: Array<T>, handler: Handler<T, U>): Array<U>;
function transform<T, U>(
  records: Array<T>, 
  options: Options, 
  handler: Handler<T, U>
): Array<U>;

Synchronous API

Types

Core Types

// Main API Handler - callback is required for async handlers
type Handler<T = any, U = any> = (
  record: T,
  callback: HandlerCallback,
  params?: any
) => U;

type HandlerCallback<T = any> = (err?: null | Error, record?: T) => void;

type Callback = (err?: null | Error, output?: any[]) => void;

interface Options extends stream.TransformOptions {
  /** Auto-consume stream when no consumer present */
  consume?: boolean;
  /** Number of parallel transformation callbacks (default: 100) */
  parallel?: number;
  /** User-defined parameters passed to handler */
  params?: any;
}

interface State {
  /** Number of completed transformations */
  finished: number;
  /** Number of currently running transformations */
  running: number;
  /** Number of started transformations */
  started: number;
  /** Whether the stream is currently paused due to backpressure */
  paused: boolean;
}

Handler Execution Patterns

Stream Transform supports multiple handler execution patterns detected by function signature:

  • Synchronous (1 param + optional params): (record) => result or (record, params) => result
  • Asynchronous (2 params + optional params): (record, callback) => void or (record, callback, params) => void
  • Promise-based (returns Promise): (record) => Promise<result> or (record, params) => Promise<result>

The library automatically detects the handler type based on function length and return value characteristics.