Alexandro.Net

Download README · GitHub release

@stackline/fstream

Compatibility-first filesystem object streams with maintained packaging and first-party types.

npm version license GitHub repository Docs Reddit community

Documentation | npm | Issues | Repository

Current package version: 1.0.5

Why this package?

A compatibility-first maintained continuation of fstream@1.0.12. It provides stat-bearing filesystem object streams for files, directories, symbolic links, and directory trees.

This project is independent. It is not affiliated with or endorsed by Isaac Z. Schlueter, the npm organization, or the upstream project.

Compatibility

Item Value
Package @stackline/fstream@1.0.5
Node.js runtime >=14.15.1
CommonJS / primary entry ./fstream.js
ES module entry ./index.mjs
Type declarations ./index.d.ts

Compatibility target

This is a Node.js filesystem package. It has no browser contract or browser build.

Installation

Install

npm install @stackline/fstream

To retain an existing dependency key and unchanged CommonJS imports, use an npm alias:

Usage

npm install fstream@npm:@stackline/fstream

const fstream = require('fstream')

CommonJS

Copy a file or directory tree while retaining supported metadata:

const fstream = require('@stackline/fstream')

const reader = fstream.Reader({ path: 'source', sort: 'alpha' })
const writer = fstream.Writer('destination')

reader.on('error', (error) => console.error(error))
writer.on('error', (error) => console.error(error))
reader.pipe(writer)

Create a file with explicit metadata:

const writer = fstream.Writer({
  path: 'output.txt',
  type: 'File',
  mode: 0o644,
  size: 6
})

writer.on('error', (error) => console.error(error))
writer.end('hello\n')

ESM

The default export is the CommonJS namespace object. Every root member also has a named export.

import fstream, { Reader, Writer } from '@stackline/fstream'

const reader = Reader('source')
reader.pipe(Writer('destination'))

console.log(reader instanceof fstream.Abstract)

Runnable read-only examples are available in examples/commonjs.cjs and examples/esm.mjs.

Features and Integrations

Common options

See COMPATIBILITY_CONTRACT.md for the precise preserved and intentionally changed surfaces, and MIGRATION.md for an adoption checklist.

TypeScript prerequisite

The declarations use Node.js filesystem, stream, and buffer types. TypeScript consumers must provide compatible Node declarations:

npm install --save-dev @types/node

The TypeScript 3.9 gate uses @types/node@14.18.63 specifically. Newer TypeScript versions may use newer Node declaration releases. @types/node is an optional peer so JavaScript-only production installs do not receive a type package they cannot use.

Security

Filesystem and security boundary

Writer can replace paths and apply metadata, and follow: true traverses symbolic links. Validate untrusted paths, constrain destination roots, and use filters appropriate to the caller's trust model. Cycle prevention is a termination guarantee, not a filesystem sandbox. See SECURITY.md.

API Surface

API

fstream.Reader(pathOrOptions[, currentStat])

Callable with or without new. It returns the appropriate file, directory, link, socket, or proxy reader. A reader exposes filesystem metadata on reader.props and convenience fields such as path, type, size, basename, and dirname.

Directory readers emit entry for each direct entry and child for every recursive descendant. Relevant lifecycle events include stat, ready, entries, entry, child, warn, error, end, and close. Readers retain the historical pause(), resume(), abort(), and pipe() behavior.

fstream.Writer(pathOrOptions[, currentStat])

Callable with or without new. Writers create files, directories, and links, apply requested metadata where the host permits it, and accept readers piped from a directory tree. An incompatible existing destination is replaced by default; set clobber: false when the historical implementation supports rejecting that replacement for the selected writer path.

Always attach an error listener before writing. Filesystem changes are not transactional.

fstream.collect(stream)

Pauses and buffers a reader, including directory entries, until its replacement pipe() method is called. This legacy helper is preserved for consumers that stage entries before choosing a destination.

Constructors and aliases

The namespace exports Abstract, Reader, Writer, grouped File, Dir, Link, and Proxy constructors, the historical DirReader, FileReader, LinkReader, ProxyReader, DirWriter, FileWriter, LinkWriter, and ProxyWriter aliases, and collect.

The supported deep imports are abstract, collect, dir-reader, dir-writer, file-reader, file-writer, get-type, link-reader, link-writer, proxy-reader, proxy-writer, reader, socket-reader, and writer beneath @stackline/fstream/lib/. Both extensionless and .js forms are export-mapped.

Local Development

git clone https://github.com/alexandroit/stackline-fstream.git
cd stackline-fstream
npm ci
npm run verify

Release tooling uses Node.js 24.20.0 and npm 11.19.0. The consumer runtime contract remains the one documented above.

Consumer Smoke Test

Run the repository's existing consumer/package check after installing development dependencies:

npm run test:smoke

Release Checklist

Run npm run verify and inspect the package contents before release. Publish a new version through the GitHub Actions publishing workflow, using the SHA-512 digest of the reviewed tarball. Verify the exact published version, tarball integrity, and npm provenance after the run.

License

ISC. Upstream copyright and attribution are retained in LICENSE, NOTICE, and THIRD_PARTY_LICENSES.md.

Credits and original authors

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.