fs-safe

> A simple fs wrapper that doesn't throw.

Philosophy

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)

Installation

``sh
yarn add fs-safe
`

`sh
npm install fs-safe
`

API

$3

- fileExists
- dirExists

$3

- readDir
- writeDir
- removeDir
- watchDir

$3

- readFile
- writeFile
- removeFile
- watchFile
- makeExecutable

$3

`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;
};
`

$3

`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;
};
`

$3

`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: true
*/
recursive?: boolean;
/**
* Whether to include directories in the results. Default: false
*/
includeDirectories?: boolean;
}
`

$3

`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
}
`

$3

`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;
}
`

$3

#### Usage
`ts
import { watchDir } from "fs-safe";

const watcher = watchDir("/path/to/dir");

watcher.onReady(() => {
console.log(Ready);
}).onAdd((path: string) => {
console.log(Added ${path});
}).onChange((path: string) => {
console.log(Changed ${path});
}).onRemove((path: string) => {
console.log(Removed ${path});
}).onAddDir((path: string) => {
console.log(Added dir ${path});
}).onRemoveDir((path: string) => {
console.log(Added dir ${path});
});

// 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;
}
`

$3

`ts
import { readFile, readFileSync } from "fs-safe";

readFile(path: string) => Promise;

readFileSync(path: string) => string | undefined;
`

$3

`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: true
*/
recursive?: boolean;
/**
* Ensure file ends with a newline. Default: true
*/
appendNewline?: boolean;
/**
* Write even if file already exists. Default: true
*/
overwrite?: boolean;
}
`

$3

`ts
import { removeFile, removeFileSync } from "fs-safe";

function removeFile(path: string): Promise;

function removeFileSync(path: string): boolean | undefined;
`

$3

#### Usage
`ts
import { watchFile } from "fs-safe";

const watcher = watchFile("/path/to/file.txt");

watcher.onReady(() => {
console.log(Ready);
}).onAdd((path: string) => {
console.log(Added ${path});
}).onChange((path: string) => {
console.log(Changed ${path});
}).onRemove((path: string) => {
console.log(Removed ${path});
});

// 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;
}
`

$3

`ts
import { makeExecutable, makeExecutableSync } from "make-executable";

function makeExecutable(path: string): Promise;

function makeExecutableSync(path: string): boolean | undefined;
`

$3

#### 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;
`

$3

`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: true
*/
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: true
*/
overwrite?: boolean;
}
`

$3

#### 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: true
*/
pretty?: boolean;
/**
* Recursively create parent directories if needed. Default: true
*/
recursive?: boolean;
/**
* Ensure file ends with a newline. Default: true
*/
appendNewline?: boolean;
}
``

Dependencies

- 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

Dev Dependencies

- @bconnorwhite/bob: Bob is a toolkit for TypeScript projects

License

MIT