# @stackline/fstream 1.0.0

Canonical documentation: https://alexandro.net/docs/vanilla/fstream/
Repository: https://github.com/alexandroit/stackline-fstream
Registry: https://www.npmjs.com/package/@stackline/fstream
License: ISC
Runtime: Node.js >=14.15.1
Browser support: none
Compatibility baseline: fstream@1.0.12
Production dependencies: graceful-fs@4.2.11 only

## Purpose

@stackline/fstream exposes stat-bearing filesystem object streams for files,
directories, links, sockets, and recursive trees. Reader objects can be piped
to Writer objects to recreate a tree and supported metadata.

## Install and alias

Scoped dependency: npm install @stackline/fstream
Compatibility alias: "fstream": "npm:@stackline/fstream@1.0.0"

The alias preserves existing require('fstream') and supported historical deep
imports. A clean install and consumer filesystem tests are required.

## Root API

The CommonJS namespace has exactly these enumerable keys in order: Abstract,
Reader, Writer, File, Dir, Link, Proxy, DirReader, FileReader, LinkReader,
ProxyReader, DirWriter, FileWriter, LinkWriter, ProxyWriter, collect.

Reader(pathOrOptions[, currentStat]) is callable/newable and selects a File,
Directory, SymbolicLink, Link, Socket, or Proxy reader. It exposes stat metadata
through props plus path, type, size, basename, dirname, depth, parent, root,
ready, and applicable link fields.

Writer(pathOrOptions[, currentStat]) is callable/newable and selects a File,
Directory, Link, or Proxy writer. Writers create missing parents, replace
incompatible destinations by default, and apply requested mode, ownership, and
timestamps when supported by the platform and caller permissions.

collect(stream) pauses and stages a compatible legacy stream until its
replacement pipe() is called. It buffers data/end and directory entries,
pauses a later proxy, and supports destinationless replay.

## Methods and events

Reader methods: pipe, pause, resume, abort, destroy, warn, info, error.
Directory Reader methods: disown, getChildProps, emitEntry.
Writer methods: write, end, add as supported by the selected writer type.

Reader events include stat, ready, entries, entry, child, entryStat, socket,
data, linkpath, pause, resume, warn, error, end, and close as applicable.
Writer events include proxy, ready, entry, drain, warn, error, end, and close.
Always attach error listeners before filesystem work begins.

## Common options

path is required. Recognized properties include type and type flags, filter,
sort, follow, hardlinks, size, mode, uid, gid, atime, mtime, flags, linkpath,
clobber, depth, parent, root, and stat metadata fields.

## Deep modules

The supported historical names beneath @stackline/fstream/lib/, with and
without .js, are: abstract, collect, dir-reader, dir-writer, file-reader,
file-writer, get-type, link-reader, link-writer, proxy-reader, proxy-writer,
reader, socket-reader, writer.

Maintenance helpers for recursive mkdir, removal, and traversal state are
private and are not supported package exports.

## ESM and TypeScript

The default ESM export is identical to the CommonJS namespace. All 16 root
members are named ESM exports. Historical deep ESM imports provide a default
export. CommonJS declarations support TypeScript 3.9; modern ESM declarations
provide named types including EntryType, EntryProperties, ReaderOptions, and
WriterOptions.

## Preserved behavior

The maintained contract includes the ordered namespace, constructor identity,
metadata, event flow, filters, sorting, pause/resume/disown/abort, symbolic
links, hard-link output, size checks, decorated errors, Writer clobber and
metadata behavior, and collect staging from fstream@1.0.12.

## Intentional corrections

- Typed Readers start unready; metadata and ready=true precede ready listeners.
- follow:true propagates to descendants. An ancestor cycle remains observable,
  warns once with ELOOP, and terminates only that branch. Sibling aliases may
  each traverse the same target.
- Hard-link identity is root-traversal-local. Reader.hardLinks remains present
  but inert, and caller options do not retain ownership state.
- Successful Writer close is terminal and no metadata operation begins later;
  valid errors detected before close remain observable.
- ProxyWriter drain signaling respects selected-delegate backpressure.
- Destinationless collect replay removes its collector before re-emitting
  entries, preserves order, and terminates.
- Deprecated Buffer construction and the obsolete inherits/mkdirp/rimraf
  production paths are removed; native helpers stay private.

## Trust boundary

Writers mutate caller-selected filesystem paths, may clobber destinations, and
are not transactional. follow:true can reach a non-cyclic target outside the
lexical source directory. Validate paths, enforce an allowed root, decide link
and clobber policy, and add size/depth/count/time limits around untrusted input.
Ancestor-cycle detection is not a filesystem sandbox or archive extraction
policy. Reject unsafe archive paths, links, special files, and resource inputs
before passing entries to a Writer.

## References

README: https://alexandro.net/docs/vanilla/fstream/README.md
API: https://alexandro.net/docs/vanilla/fstream/API.md
Compatibility: https://alexandro.net/docs/vanilla/fstream/COMPATIBILITY_CONTRACT.md
Migration: https://alexandro.net/docs/vanilla/fstream/MIGRATION.md
Security: https://alexandro.net/docs/vanilla/fstream/SECURITY.md
Licenses: https://alexandro.net/docs/vanilla/fstream/THIRD_PARTY_LICENSES.md
CommonJS example: https://alexandro.net/docs/vanilla/fstream/examples/commonjs.cjs
ESM example: https://alexandro.net/docs/vanilla/fstream/examples/esm.mjs
Metadata: https://alexandro.net/docs/vanilla/fstream/package-meta.json