The fs facade

One object, the whole filesystem. fs groups everything you reach for — reading, writing, editing, walking, hashing — into a small, discoverable surface. It’s the main way you use @warlock.js/fs; this page is the 60-second tour, with a link to go deep on each area.

the whole shape, at a glance

import { fs } from "@warlock.js/fs";

await fs.files.putJson("config.json", { port: 3000 });   // files
await fs.dirs.ensure("storage/uploads");                 // directories
const pkg = fs.file("package.json");                     // a lazy handle
const digest = await fs.hash.file("bundle.js");          // hashing

Async by design

Every facade method returns a Promise. Synchronous callers (CLI tools, code generators) drop to the low-level primitives — that’s the one escape hatch. And fs never sandboxes paths; containment is the storage layer’s job.

Files — fs.files.*

Read, write, and edit in place. getJson can validate against a schema and fall back when a file is missing; edit / mergeJson patch a file without the read-then-write dance.

const cfg = await fs.files.getJson("config.json", { default: {} });
await fs.files.editJson("package.json", (p) => ({ ...p, version: "4.7.0" }));

Directories — fs.dirs.*

Ensure, empty, copy, and walk — recursively, with a constant-memory async iterator.

for await (const entry of fs.dirs.walk("src")) {
  // { path, name, type: "file" | "directory" }
}

Handles — fs.file() / fs.dir()

Prefer an object over a path string? fs.file(path) and fs.dir(path) are lazy, immutable handles with pure-path helpers and the same verbs.

const file = fs.file("src/app/user.model.ts");
file.extension;        // ".ts"
await file.size();     // bytes

Hashing — fs.hash.*

SHA-256 by default. string / buffer are synchronous (in-memory); file / dir are async (they read from disk).

fs.hash.string("hello");         // sync
await fs.hash.dir("dist");       // async — a stable tree fingerprint

Go deeper

Read and write files get / put, JSON, schema validation, existence and stats.

Edit files in place edit / editJson / mergeJson / ensureJson — read-modify-write, done for you.

Manage directories ensure / empty / walk / list, recursive listing, tree size and hash.

File & Directory handles fs.file() / fs.dir() objects, path helpers, child handles.

Hash files fs.hash.* and checksum verification.

API reference Every method, option type, and the low-level primitives.