# file-sink

> A slim abstraction over the file system to easily resolve relative paths

Latest version **1.0.15** (published 2026-01-05) · ISC license · 0 weekly downloads

## Install

```sh
npm install file-sink
pnpm add file-sink
yarn add file-sink
bun add file-sink
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.0.15 |
| Published | 2026-01-05 |
| First published | 2018-01-02 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 17.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Dan Kolz |
| Maintainers | dankolz |
| Keywords | file, system, abstraction, relative, path |

## Links

- npm: https://www.npmjs.com/package/file-sink
- Repository: https://github.com/EmergentIdeas/file-sink
- Homepage: https://github.com/EmergentIdeas/file-sink#readme
- Issues: https://github.com/EmergentIdeas/file-sink/issues
- npm.io page: https://npm.io/package/file-sink

## Dependencies (2)

- [filter-log](https://npm.io/package/filter-log.md) ^1.0.11
- [add-callback-to-promise](https://npm.io/package/add-callback-to-promise.md) ^1.0.2

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 1.0.15 (latest) — 2026-01-05
- 1.0.14 — 2025-12-02
- 1.0.13 — 2024-03-24
- 1.0.12 — 2023-11-27
- 1.0.11 — 2023-11-27
- 1.0.10 — 2023-10-12
- 1.0.9 — 2023-07-01
- 1.0.8 — 2023-06-21
- 1.0.7 — 2023-06-09
- 1.0.6 — 2023-05-26
- 1.0.5 — 2021-02-10
- 1.0.4 — 2018-06-27
- 1.0.3 — 2018-06-27
- 1.0.2 — 2018-02-13
- 1.0.1 — 2018-01-03
- … 1 more at https://npm.io/package/file-sink/versions

## README

# File Sink

A slim abstraction over the file system to easily resolve relative paths.

## Install

```bash
npm install file-sink
```


## Selected Methods Summary

- read(path) - Reads file info, returns promise resolving to buffer
- readStream(path) - Reads file info as utf-8 text stream
- write(path, data) - Where data is a string, Buffer, TypedArray or DataView. Lots of options
for writing partial data/files as well. Returns promise.
- rm(path) - removes file or directory (recursive by default), returns promise
- mkdir(path) - makes directory, returns promise
- getFullFileInfo(path) - returns a promise with info about a file or directory. See format below.
- createHash(path) - A promise with the has value of the file data (sha512 by default)
- findPaths(options) - A bit like `find`, allows searching for files and directories by name
- find - Like findPaths, but instead of a promise it returns an EventEmitter which emits `data`
and `done` events. Each `data` event has a file info object. 

## Use

```
const Sink = require('file-sink')
let tempSink = new Sink('/tmp')

// read /tmp/my-file.txt
tempSink.read('my-file.txt', function(err, data) {
	console.log(data.toString())
})

let data = await tempSink.read('my-file.txt')

// read /tmp/my-file.txt
let data = tempSink.readSync('my-file.txt')
// throws error if path does not exist or some other problem happens

// write to /tmp/my-file.txt
tempSink.write('my-file.txt', 'Hello, World!', function(err) {
	// log error if exists
})

try {
	await tempSink.write('my-file.txt')
}
catch(err) {
	// log error
}


// read the info for a file like mod time
let info = await tempSink.getFullFileInfo('my-file.txt')
console.log(info.stat.mtime)

// find the names of the children of a directory

let dirInfo = await tempSink.getFullFileInfo('.')
for(let child of dirInfo.children) {
	console.log((child.directory ? '(d) ': "") + child.name + ' - ' + child.stat.ctime)
}


```

## getFullFileInfo Data Format

Roughly, where `children` contains objects like this, but without the `children` attribute.

```
{
  name: 'testdir',
  parent: '/mnt/workingdata/node-repo/file-sink/test-data',
  stat: Stats {
    dev: 2097,
    mode: 16893,
    nlink: 2,
    uid: 1000,
    gid: 1000,
    rdev: 0,
    blksize: 4096,
    ino: 85729889,
    size: 4096,
    blocks: 8,
    atimeMs: 1701114609826.992,
    mtimeMs: 1701114609826.992,
    ctimeMs: 1701114609826.992,
    birthtimeMs: 1701114609826.992,
    atime: 2023-11-27T19:50:09.827Z,
    mtime: 2023-11-27T19:50:09.827Z,
    ctime: 2023-11-27T19:50:09.827Z,
    birthtime: 2023-11-27T19:50:09.827Z
  },
  directory: true,
  relPath: 'testdir',
  children: []
}
```




## Why?

I wanted to read and write to relative paths without the reader/writer having to
know what the root is or having to do a security check on the path. Essentially, 
it materializes a choice made in the configuration. The module also
does a couple checks to ensure that the final, resolved path is within the
initial root path. 

Additionally, in the code I'm writing, I'm not sure I want to assume a file 
system as the location of my data. I don't want to over-abstract, but this will 
ensure the code doesn't implicitly make those assumptions.

---
_Source: https://npm.io/package/file-sink · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._