tessl/npm-stream-transform

Object transformations implementing the Node.js stream.Transform API

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Stream Transform

Name: tessl/npm-stream-transform
Author: tessl

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.