# API reference

## Module forms

CommonJS returns the historical namespace:

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

ESM provides that same namespace as the default export and every root member
as a named export:

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

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])`

Callable with or without `new`. If no type is supplied, a ProxyReader stats the
path and delegates to the applicable specialized reader.

```js
const reader = Reader({
  path: '/srv/input',
  follow: false,
  hardlinks: true,
  sort: 'alpha',
  filter (entry, stat) {
    return !entry.basename.startsWith('.')
  }
})
```

Reader convenience properties include:

- `path` and `_path`: resolved ordinary and underlying filesystem paths;
- `type`: `Directory`, `File`, `SymbolicLink`, `Link`, or another recognized
  filesystem type;
- `props`: the mutable property/metadata object;
- `basename`, `dirname`, `depth`, `parent`, and `root`;
- `size`, `linkpath`, `readable`, `writable`, and `ready` where applicable.

### Reader methods

| Method | Behavior |
| --- | --- |
| `pipe(destination[, options])` | Pipes byte data and forwards directory entries to a compatible Writer. |
| `pause([who])` | Pauses the Reader and its active underlying stream or child. |
| `resume([who])` | Resumes traversal or byte flow. |
| `abort()` | Marks the Reader aborted and emits `abort`. |
| `destroy()` | Retains the historical no-op base method. |
| `warn(message[, code])` | Emits a decorated recoverable warning when observed. |
| `info(message[, code])` | Emits `info`. |
| `error(message[, code, throw])` | Emits or synchronously throws a decorated Error. |

Directory Readers also expose `entries`, `disown(entry)`,
`getChildProps(stat)`, and `emitEntry(entry)`.

### Reader events

| Event | Meaning |
| --- | --- |
| `stat` | Stat metadata has been copied to the entry. |
| `ready` | Metadata is complete; `ready` is already `true`. |
| `entries` | A DirectoryReader has obtained its list of names. |
| `entry` | One direct directory entry is ready. |
| `child` | Any recursive descendant is ready. |
| `entryStat` | A direct entry's stat metadata is available. |
| `socket` | A socket was observed but excluded from pipeable entries. |
| `data` | File byte data. |
| `linkpath` | A symbolic-link target was read. |
| `pause` / `resume` | Flow control changed. |
| `warn` | A recoverable decorated Error, including cycle `ELOOP`. |
| `error` | A terminal decorated Error. Always attach a listener. |
| `end` | No more entry or byte events. |
| `close` | Successful terminal completion. |

The successful typed-reader sequence is metadata/stat, `ready`, type-specific
activity, `end`, then `close`. A successful `close` is terminal.

## `Writer(pathOrOptions[, currentStat])`

Callable with or without `new`. With no explicit type, a ProxyWriter retains an
existing destination type or defaults a missing path to `File`.

```js
const writer = Writer({
  path: '/srv/output.txt',
  type: 'File',
  mode: 0o640,
  size: 6
})

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

Writers expose `path`, `type`, `props`, `parent`, `root`, `depth`, `basename`,
`dirname`, `linkpath`, `size`, `clobber`, `ready`, `readable`, and `writable`
as applicable.

### Writer methods

| Method | Behavior |
| --- | --- |
| `write(chunk)` | Writes a string or Buffer to a FileWriter; returns a backpressure boolean. |
| `end([chunk])` | Ends the selected Writer and applies requested metadata. |
| `add(entry)` | Adds a Reader entry to a DirWriter. |

A ProxyWriter buffers calls until it selects its delegate. If a buffered call
returns `false`, `drain` is emitted only when the delegate can accept more work.

Writer events include `proxy`, `ready`, `entry`, `drain`, `warn`, `error`,
`end`, and `close`.

## `collect(stream)`

`collect()` pauses a compatible legacy stream, buffers its `data`, `end`, and
`entry` events, pauses a later `proxy`, and replaces `pipe()` with a replaying
version. Calling that replacement with a destination forwards entries through
`destination.add(entry)` and then restores ordinary piping. Calling it without
a destination re-emits the buffered entries and data on the source.

Repeated calls are idempotent. A stream already paused is collected when it
next emits `resume`.

## Groups and aliases

The `File`, `Dir`, `Link`, and `Proxy` values each contain `Reader` and `Writer`
constructors. These identities are preserved:

```js
fstream.Reader.Dir === fstream.Dir.Reader
fstream.DirReader === fstream.Dir.Reader
fstream.Writer.File === fstream.File.Writer
fstream.FileWriter === fstream.File.Writer
```

The same identity rule applies to File, Directory, Link, and Proxy reader and
writer aliases.

## Historical deep imports

These 14 modules are supported beneath `@stackline/fstream/lib/`, with and
without `.js`:

- `abstract`, `collect`, `dir-reader`, `dir-writer`;
- `file-reader`, `file-writer`, `get-type`;
- `link-reader`, `link-writer`;
- `proxy-reader`, `proxy-writer`;
- `reader`, `socket-reader`, `writer`.

ESM deep entries provide a default export:

```js
import Reader from '@stackline/fstream/lib/reader.js'
```

Native mkdir/removal and traversal-state helpers are implementation details and
are not exported.

## Options and metadata

`path` is required. Other recognized properties include `type`, historical
type flags, `linkpath`, `depth`, `size`, `mode`, `uid`, `gid`, `atime`, `mtime`,
`dev`, `ino`, `nlink`, `blksize`, `flags`, `follow`, `hardlinks`, `clobber`,
`sort`, `filter`, `parent`, and `root`.

The filesystem, platform, mount, and caller permissions determine whether link
creation, ownership, timestamps, and modes can be reproduced. The package
preserves applicable upstream platform guards; it cannot emulate unsupported
host features.

## TypeScript

The package provides CommonJS declarations compatible with TypeScript 3.9 and
modern ESM declarations with named type exports including `EntryType`,
`EntryProperties`, `ReaderOptions`, and `WriterOptions`.

```ts
import fstream = require('@stackline/fstream')

const options: fstream.ReaderOptions = { path: 'input', sort: 'alpha' }
const reader: fstream.Reader = new fstream.Reader(options)
```

See [COMPATIBILITY_CONTRACT.md](./COMPATIBILITY_CONTRACT.md) for intentional
corrections and [SECURITY.md](./SECURITY.md) for the filesystem trust boundary.