@humanfs/core

by Nicholas C. Zakas

If you find this useful, please consider supporting my work with a donation or nominate me 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:

1npm install @humanfs/core
2
3# or
4
5pnpm install @humanfs/core
6
7# or
8
9yarn add @humanfs/core
10
11# or
12
13bun install @humanfs/core

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

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

Deno

Install using JSR:

1deno add @humanfs/core
2
3# or
4
5jsr add @humanfs/core

Then you can import the Hfs class like this:

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

Browser

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

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

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

1import { 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:

1const 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:

1class MyHfs extends Hfs {
2	constructor() {
3		super({
4			impl: myImpl
5		});
6	}
7}

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.

1const myPath = new Path(["dir", "subdir"]);
2console.log(myPath.toString());		// "dir/subdir"
3
4// add another step
5myPath.push("file.txt");
6console.log(myPath.toString());		// "dir/subdir/file.txt"
7
8// get just the last step
9console.log(myPath.name);			// "file.txt"
10
11// change just the last step
12myPath.name = "file.json";
13console.log(myPath.name);			// "file.json"
14console.log(myPath.toString());		// "dir/subdir/file.json"
15
16// get the size of the path
17console.log(myPath.size);			// 3
18
19// remove the last step
20myPath.pop();
21console.log(myPath.toString());		// "dir/subdir"
22
23// iterate over the steps
24for (const step of myPath) {
25	// do something
26}
27
28// create a new path from a string
29const newPath = Path.fromString("/foo/bar");

License

Apache 2.0