@bearz/fs

Overview

The fs module provides a modern file system API that works in Deno, Bun, and NodeJs to promote creating cross-runtime packages/modules for TypeScript/JavaScript.

Documentation

Documentation is available on jsr.io

A list of other modules can be found at github.com/bearz-io/js

Usage

import { makeDir, writeTextFile, remove } from "@bearz/fs"


await makeDir("/home/my_user/test");
await writeTextFile("/home/my_user/test/log.txt",  "ello");
await remove("/home/my_user/test", { recursive: true });

Classes

• AlreadyExistsError - An error thrown when a file already exists.
• FsFile - The type returned by open and openSync.
• NotFoundError - An error thrown when a file or directory is not found.

Functions

• chmod & chmodSync - Changes the mode for the given file or directory on a posix system.
• chown & chownSync - Changes the owner for the given file or directory on a posix system.
• copyFile & copyFileSync - Copies a file from the current path to the desintation.
• copy & copySync - Copies a file, directory, or symlink to the destination.
• cwd - Gets the current working directory.
• emptyDir & emptyDirSync - Clears all the child items in a directory.
• ensureDir & ensureDirSync - Ensure that a directory exists or is created if needed.
• ensureFile & ensureFileSync - Ensure that a file exits or is created if needed.
• ensureSymlink & ensureSymlinkSync - Ensures that a symlink exists or is created if needed.
• exists & existsSync - Determines if a file or directory exists.
• isNotFoundError - Determines if an error is NotFoundError, NotFound, or node error with a code of ENOENT.
• isAlreadyExistsError - Determines if an error is an AlreadyExistsError, AlreadyExists, or node error with a code of EEXIST.
• expandGlob & expandGlobSync - Gets files and/or directories that matches the glob against the root direcory provided. root directory defaults to the current working directory.
• gid - Gets the group id for the current user for the process (posix only).
• isDir & isDirSync - Determines if a path exists and is a directory.
• isFile & isFile - Determines if a path exists and is a file.
• link & linkSync - Creates a hard link.
• lstat & lstatSync - Invokes link stat on path to get system system information.
• makeDir & makeDirSync - Creates a new directory.
• makeTempDir & makeTempDirSync - Creates a new temporary directory.
• makeTempFile & makeTempFileSync - Creates a new temporary file.
• move & moveSync - Moves a file, directory, or symlink to the destination.
• open & openSync - Opens a file and returns an instance of FsFile which includes multiple methods of working with a file such as seek, lock, read, write, stat, etc. Reand and write only reads/writes a chunk of data is more akin to to a stream.
• readDir & readDirSync - Reads a directory and returns an iterator of DirectoryInfo. This is not recursive.
• readFile & readFileSync - Reads the data of a file as Uint8Array (binary).
• readLink & readLinkSync - Reads the link and gets source path.
• readTextFile & readTextFile - Reads a file that is utf-8 and returns the contents as a string.
• remove & removeSync - Deletes a directory, file, or symlink from the file system.
• rename & renameSync - Renames a directory, file, or symlink.
• stat & statSync - Gets a file or directories file system information.
• symlink & symlinkSync - Creates a new symlink (soft) link.
• uid - Gets the user id for the current user of the process. (posix only).
• utime & utimeSync - Changes the creation and modfication dates for a file or directory.
• walk & walkSync - Iterates over a directory structure recursively.
• writeFile & writeFileSync - Writes Uint8Array (binary) to a given file path.
• writeTextFile & writeTextFileSync - Writes a string to a given file path as utf-8 encoded data.

Notes

The API is heavily influenced by Deno's file system APIs which are built on modern web standards which includes promises, iterator, and async iterator did not exist in node when the api was created. This module gets rid of the need to import "fs/promises".

The module will still load functions if called from the browser or runtimes outside of node, bun, and deno. However, the functions will throw errors when called.

To use the lock and seek methods on the File object returned from the open method in runtimes outside of Deno, you'll need to implement the methods by importing @bearz/fs/ext and setting the methods.

This was done to avoid a hard dependency on npm's fs-extra module. An additional bearz module may be created at a later date to handle that.

The module includes the same functions found in deno's @std/fs module but instead of only supporting deno file system calls, it uses the this module's abstraction layer which supports deno, bun, and node.

License

MIT License

Deno MIT License