SkinnnyJay/file.utils

[](https://www.npmjs.com/package/@simpill/file.utils) [](https://github.com/SkinnnyJay/simpill-utils/tree/main/utils/@simpill-file.utils)

npm

npm install @simpill/file.utils

GitHub (from monorepo)

git clone https://github.com/SkinnnyJay/simpill-utils.git && cd simpill-utils/utils/@simpill-file.utils && npm install && npm run build

Then in your project: npm install /path/to/simpill-utils/utils/@simpill-file.utils or npm link from that directory.

import {
  readFileUtf8,
  writeFileUtf8,
  readFileJson,
  writeFileJson,
  ensureDir,
} from "@simpill/file.utils/server";

await ensureDir("./data");
await writeFileUtf8("./data/hello.txt", "Hello");
const text = await readFileUtf8("./data/hello.txt");
await writeFileJson("./data/config.json", { port: 3000 });
const config = await readFileJson<{ port: number }>("./data/config.json");

Read and write APIs live in the same module; if the file grows, consider splitting into read vs write. For now:

import { ... } from "@simpill/file.utils";         // Everything
import { ... } from "@simpill/file.utils/server";  // Node.js file I/O
import { ... } from "@simpill/file.utils/client"; // Empty (no fs in browser)
import { ... } from "@simpill/file.utils/shared"; // Shared only

• readFileUtf8(path) → Promise<string> — readFileUtf8Sync for sync.
• writeFileUtf8(path, content) → Promise<void> — writeFileUtf8Sync for sync. Creates parent directory if needed.
• readFileJson<T>(path, options?) → Promise<T> — readFileJsonSync for sync. T is not validated unless options.validate is provided (e.g. (d) => configSchema.parse(d)). No Zod dependency; pass your schema’s parse in validate.
• writeFileJson<T>(path, data, options?) → Promise<void> — writeFileJsonSync for sync.
• readFileAsync(path, encoding?) → Promise<string | Buffer> — Encoding: one argument → UTF-8 string. Two arguments: encoding as FileEncoding → string; encoding as undefined → Buffer. Use readFileSync for the sync variant.
• writeFileAsync(path, data, encoding?) → Promise<void> — writeFileSync for sync. Parent directories are created automatically (via ensureDir on the path’s directory) before writing.
• ensureDir(path) → Promise<void> — ensureDirSync for sync. Recursive directory creation.
• Path helpers (server): basename, dirname, extname, isAbsolutePath, joinPath, normalizePath, resolvePath — same semantics as Node path module.
• FileEncoding, ReadFileJsonOptions, WriteFileJsonOptions

Use async variants (readFileUtf8, readFileJson, etc.) in normal application code to avoid blocking the event loop. Use sync variants (readFileUtf8Sync, etc.) in build scripts or one-off CLI code where async is not needed. All write helpers create parent directories before writing; missing or permission errors throw.

• fs-extra-style helpers — No copy, move, remove, or symlink helpers. Use fs.promises or the fs-extra package for those.
• Atomic write — Writes are direct; no write-to-temp-then-rename. For atomic updates, write to a temp path then rename with fs.rename (or use a library).
• Streaming — No stream helpers; use fs.createReadStream / createWriteStream or a streaming library.
• Glob / traverse — No glob or directory-walk APIs. Use fast-glob, globby, or fs.readdir with recursion.
• JSON validation — readFileJson uses JSON.parse only by default. Pass options.validate (e.g. (d) => myZodSchema.parse(d)) for runtime validation without this package depending on Zod.
• Stable stringify — writeFileJson uses JSON.stringify; key order is not guaranteed. For deterministic output, use a custom replacer or sort keys before stringifying.

npx ts-node examples/01-basic-usage.ts

• CONTRIBUTING — Monorepo package guide.

ISC