# @humanfs/core

> The core of the humanfs library.

Latest version **0.20.0** (published 2026-09-10) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @humanfs/core
pnpm add @humanfs/core
yarn add @humanfs/core
bun add @humanfs/core
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.20.0 |
| Published | 2026-09-10 |
| First published | 2024-01-30 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=24.0.0 |
| Dependencies | 1 |
| Unpacked size | 65.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 552 |
| Author | Nicholas C. Zakas |
| Maintainers | nzakas |
| Keywords | filesystem, fs, hfs, files |

## Links

- npm: https://www.npmjs.com/package/@humanfs/core
- Repository: https://github.com/humanwhocodes/humanfs
- Homepage: https://github.com/humanwhocodes/humanfs#readme
- Issues: https://github.com/humanwhocodes/humanfs/issues
- npm.io page: https://npm.io/package/@humanfs/core

## Dependencies (1)

- [@humanfs/types](https://npm.io/package/@humanfs/types.md) ^0.16.0

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 0.20.0 (latest) — 2026-09-10
- 0.19.2 — 2026-04-17
- 0.19.1 — 2024-10-28
- 0.19.0 — 2024-09-09
- 0.18.2 — 2024-06-13
- 0.18.1 — 2024-06-12
- 0.18.0 — 2024-06-12
- 0.17.0 — 2024-03-20
- 0.16.1 — 2024-03-14
- 0.16.0 — 2024-03-13
- 0.15.0 — 2024-02-29
- 0.14.0 — 2024-02-27
- 0.13.0 — 2024-02-24
- 0.12.0 — 2024-02-19
- 0.11.0 — 2024-02-14
- … 5 more at https://npm.io/package/@humanfs/core/versions

## README

# `@humanfs/core`

by [Nicholas C. Zakas](https://humanwhocodes.com)

If you find this useful, please consider supporting my work with a [donation](https://humanwhocodes.com/donate) or [nominate me](https://stars.github.com/nominate/) for a GitHub Star.

## Description

The core functionality for humanfs that is shared across all implementations for all runtimes. The contents of this package are intentionally runtime agnostic and are not intended to be used alone.

Currently, this package simply exports the `Hfs` class, which is an abstract base class intended to be inherited from in runtime-specific hfs packages (like `@humanfs/node`).

> [!WARNING]
> This project is **experimental** and may change significantly before v1.0.0. Use at your own caution and definitely not in production!

## Installation

### Node.js

Install using your favorite package manager for Node.js:

```shell
npm install @humanfs/core

# or

pnpm install @humanfs/core

# or

yarn add @humanfs/core

# or

bun install @humanfs/core
```

Then you can import the `Hfs` and `Path` classes like this:

```js
import { Hfs, Path } from "@humanfs/core";
```

### Deno

Install using [JSR](https://jsr.io):

```shell
deno add @humanfs/core

# or

jsr add @humanfs/core
```

Then you can import the `Hfs` class like this:

```js
import { Hfs, Path } from "@humanfs/core";
```

### Browser

It's recommended to import the minified version to save bandwidth:

```js
import { Hfs, Path } from "https://cdn.skypack.dev/@humanfs/core?min";
```

However, you can also import the unminified version for debugging purposes:

```js
import { Hfs, Path } from "https://cdn.skypack.dev/@humanfs/core";
```

## Usage

### `Hfs` Class

The `Hfs` class contains all of the basic functionality for an `Hfs` instance *without* a predefined impl. This class is mostly used for creating runtime-specific impls, such as `NodeHfs` and `DenoHfs`.

You can create your own instance by providing an `impl` directly:

```js
const hfs = new Hfs({ impl: { async text() {} }});
```

The specified `impl` becomes the base impl for the instance, meaning you can always reset back to it using `resetImpl()`.

You can also inherit from `Hfs` to create your own class with a preconfigured impl, such as:

```js
class MyHfs extends Hfs {
	constructor() {
		super({
			impl: myImpl
		});
	}
}
```

### `Path` Class

The `Path` class represents the path to a directory or file within a file system. It's an abstract representation that can be used even outside of traditional file systems where string paths might not make sense.

```js
const myPath = new Path(["dir", "subdir"]);
console.log(myPath.toString());		// "dir/subdir"

// add another step
myPath.push("file.txt");
console.log(myPath.toString());		// "dir/subdir/file.txt"

// get just the last step
console.log(myPath.name);			// "file.txt"

// change just the last step
myPath.name = "file.json";
console.log(myPath.name);			// "file.json"
console.log(myPath.toString());		// "dir/subdir/file.json"

// get the size of the path
console.log(myPath.size);			// 3

// remove the last step
myPath.pop();
console.log(myPath.toString());		// "dir/subdir"

// iterate over the steps
for (const step of myPath) {
	// do something
}

// create a new path from a string
const newPath = Path.fromString("/foo/bar");
```

## License

Apache 2.0

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