A simple fs wrapper that doesn't throw
npm install fs-safe> A simple fs wrapper that doesn't throw.
Throwing is bad. Instead, we should return a value correspondent to the success of an operation.
- Read operations should return the expected value, or undefined if unable to read.
- Write operations should return a boolean or undefined success value.
- true: Successful or unnecessary (ex: failing to create a directory that already exists)
- false: Unsuccessful
- undefined: Unsuccessful, but the desired state may already exist (ex: failing to create a directory but not knowing if that directory already exists)
``sh`
yarn add fs-safe
`sh`
npm install fs-safe
- readDir
- writeDir
- removeDir
- watchDir
- readFile
- writeFile
- removeFile
- watchFile
- makeExecutable
`ts
import { fileExists, fileExistsSync, FileExistsOptions } from "fs-safe";
function fileExists(path: string, options?: FileExistsOptions): Promise
function fileExistsSync(path: string, options?: FileExistsOptions): boolean | undefined;
type FileExistsOptions = {
/**
* Return true if path is directory. Default: false`
*/
includeDirectories?: boolean;
};
`ts
import { dirExists, dirExistsSync, DirExistsOptions } from "fs-safe";
function dirExists(path: string, options?: DirExistsOptions): Promise
function dirExistsSync(path: string, options?: DirExistsOptions): boolean | undefined;
type DirExistsOptions = {
/**
* Return true if path is file. Default: false`
*/
includeFiles?: boolean;
};
`ts
import { readDir, readDirSync, ReadDirOptions } from "fs-safe";
function readDir(path: string, options: ReadDirOptions): Promise
function readDirSync(path: string, options: ReadDirOptions): string[] | undefined;
type ReadDirOptions = {
/**
* Recursively read child directories as well. Default: truefalse
*/
recursive?: boolean;
/**
* Whether to include directories in the results. Default: `
*/
includeDirectories?: boolean;
}
`ts
import { writeDir, writeDirSync, WriteDirOptions } from "fs-safe";
function writeDir(path: string, options: WriteDirOptions): Promise
function writeDirSync(path: string, options: WriteDirOptions): boolean | undefined;
type WriteDirOptions = {
recursive?: boolean; // Default: true
}
`
`ts
import { removeDir, removeDirSync, RemoveDirOptions } from "fs-safe";
function removeDir(path: string, options: RemoveDirOptions): Promise
function removeDirSync(path: string, options: RemoveDirOptions): boolean | undefined;
type RemoveDirOptions = {
/**
* If true, perform a recursive directory removal. Default: true`
*/
recursive?: boolean;
}
#### Usage
`ts
import { watchDir } from "fs-safe";
const watcher = watchDir("/path/to/dir");
watcher.onReady(() => {
console.log(Ready);Added ${path}
}).onAdd((path: string) => {
console.log();Changed ${path}
}).onChange((path: string) => {
console.log();Removed ${path}
}).onRemove((path: string) => {
console.log();Added dir ${path}
}).onAddDir((path: string) => {
console.log();Added dir ${path}
}).onRemoveDir((path: string) => {
console.log();
});
// To stop watching:
watcher.stop();
`
#### Types
`ts
import { watchDir, DirWatcher, EventCallback } from "fs-safe";
function watchDir(path: string): DirWatcher;
type EventCallback = (path: string) => void;
type DirWatcher = {
onAdd: (cb: EventCallback) => DirWatcher;
onRemove: (cb: EventCallback) => DirWatcher;
onChange: (cb: EventCallback) => DirWatcher;
onAddDir: (cb: EventCallback) => DirWatcher;
onRemoveDir: (cb: EventCallback) => DirWatcher;
onReady: (cb: () => void) => DirWatcher;
stop: () => Promise
}
`
`ts
import { readFile, readFileSync } from "fs-safe";
readFile(path: string) => Promise
readFileSync(path: string) => string | undefined;
`
`ts
import { writeFile, writeFileSync, WriteFileOptions } from "fs-safe";
function writeFile(path: string, content?: string | Buffer): Promise
function writeFileSync(path: string, content?: string | Buffer): boolean;
type WriteFileOptions = {
/**
* Recursively create parent directories if needed. Default: truetrue
*/
recursive?: boolean;
/**
* Ensure file ends with a newline. Default: true
*/
appendNewline?: boolean;
/**
* Write even if file already exists. Default: `
*/
overwrite?: boolean;
}
`ts
import { removeFile, removeFileSync } from "fs-safe";
function removeFile(path: string): Promise
function removeFileSync(path: string): boolean | undefined;
`
#### Usage
`ts
import { watchFile } from "fs-safe";
const watcher = watchFile("/path/to/file.txt");
watcher.onReady(() => {
console.log(Ready);Added ${path}
}).onAdd((path: string) => {
console.log();Changed ${path}
}).onChange((path: string) => {
console.log();Removed ${path}
}).onRemove((path: string) => {
console.log();
});
// To stop watching:
watcher.stop();
`
#### Types
`ts
import { watchFile, FileWatcher, EventCallback } from "fs-safe";
function watchFile(path: string): FileWatcher;
type EventCallback = (path: string) => void;
type FileWatcher = {
onAdd: (cb: EventCallback) => FileWatcher;
onRemove: (cb: EventCallback) => FileWatcher;
onChange: (cb: EventCallback) => FileWatcher;
onReady: (cb: () => void) => FileWatcher;
stop: () => Promise
}
`
`ts
import { makeExecutable, makeExecutableSync } from "make-executable";
function makeExecutable(path: string): Promise
function makeExecutableSync(path: string): boolean | undefined;
`
#### Read a JSONValue:
`ts
import { readJSON, readJSONSync, JSONValue } from "read-json-safe";
function readJSON(path: string): Promise
function readJSONSync(path: string): JSONValue | undefined;
type JSONValue = string | number | boolean | JSONObject | JSONArray | null;
`
#### Read a JSONObject:
`ts
import { readJSONObject, readJSONObjectSync, JSONObject } from "read-json-safe";
function readJSONObject(path: string): Promise
function readJSONObjectSync(path: string): JSONObject| undefined;
type JSONObject = {
[key: string]: JSONValue;
}
`
#### Read a JSONArray:
`ts
import { readJSONArray, readJSONArraySync, JSONArray } from "read-json-safe";
function readJSONArray(path: string): Promise
function readJSONArraySync(path: string): JSONArray | undefined;
type JSONArray = Array
`
`ts
import { writeJSON, writeJSONSync, Options, JSONObject } from "write-json-safe";
function writeJSON(path: string, content?: JSONObject, options?: Options): Promise
function writeJSONSync(path: string, content?: JSONObject, options?: Options): boolean;
type Options = {
/**
* Output formatted JSON. Default: truetrue
*/
pretty?: boolean;
/**
* Recursively create parent directories if needed. Default: true
*/
recursive?: boolean;
/**
* Ensure file ends with a newline. Default: true
*/
appendNewline?: boolean;
/**
* Write even if file already exists. Default: `
*/
overwrite?: boolean;
}
#### Usage
##### For existing files:
`ts
import { mergeJSON } from "fs-safe";
// old-file.json (before):
// {
// "ok": true
// }
//
mergeJSON("old-file.json", { test: 1 });
// old-file.json (after):
// {
// "ok": true,
// "test": 1
// }
//
`
##### For new files:
`ts
import { mergeJSON } from "fs-safe";
mergeJSON("new-file.json", { test: 1 });
// new-file.json:
// {
// "test": 1
// }
//
`
#### Types
`ts
import { mergeJSON, mergeJSONSync, JSONObject } from "fs-safe";
function mergeJSON(path: string, object: JSONObject, options?: Options): Promise
function mergeJSONSync(path: string, object: JSONObject, options?: Options): boolean;
type Options = {
/**
* Output formatted JSON. Default: truetrue
*/
pretty?: boolean;
/**
* Recursively create parent directories if needed. Default: true
*/
recursive?: boolean;
/**
* Ensure file ends with a newline. Default: ``
*/
appendNewline?: boolean;
}
- dir-exists-safe: Check if a directory exists without try catch
- file-exists-safe: Check if a file exists without try catch
- make-executable: Set the executable bits on a file
- merge-json-file: Merge a JSON file with a JSON object
- read-dir-safe: Read directories recursively or non-recursively
- read-file-safe: Read files without try catch
- read-json-safe: Read JSON files without try catch
- remove-dir-safe: Remove directories recursively or non-recursively without try catch
- remove-file-safe: Remove files without try catch
- watch-dir-safe: Watch a directory for changes
- watch-file-safe: Watch a file for changes
- write-dir-safe: Create directories and their parents recursively without try catch
- write-file-safe: Write files and create parent directories if necessary
- write-json-safe: Write formatted JSON to a file
- @bconnorwhite/bob: Bob is a toolkit for TypeScript projects