@little-nebulae/node-fs 0.1.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Luong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# Node fs library

package/dist/index.d.mts

@@ -0,0 +1,53 @@
+import { UnexpectedError } from "@little-nebulae/error";
+import { Result } from "@little-nebulae/result";
+import { AccessDeniedSystemError, FileTooBigSystemError, IsDirectorySystemError, NameTooLongSystemError, NoEntrySystemError, NotDirectorySystemError, OutOfMemorySystemError, OverflowSystemError, PermissionDeniedSystemError } from "@little-nebulae/system-error";
+//#region src/constants.d.ts
+export declare const DEFAULT_CHARACTER_ENCODING = "utf-8";
+//#endregion
+//#region src/ops/dir/make.d.ts
+export declare function makeDirectory({ path }: {
+  path: string;
+}): Promise<Result<undefined, UnexpectedError>>;
+//#endregion
+//#region src/ops/dir/make-recursively.d.ts
+export declare function makeDirectoryRecursively({ path }: {
+  path: string;
+}): Promise<Result<string | undefined, UnexpectedError>>;
+//#endregion
+//#region src/ops/dir/read.d.ts
+export declare function readDirectory({ path, recursive }: {
+  path: string;
+  recursive?: boolean;
+}): Promise<Result<string[], UnexpectedError>>;
+//#endregion
+//#region src/ops/file/read-text.d.ts
+export declare function readTextFile({ path, signal }: {
+  path: string;
+  signal?: AbortSignal;
+}): Promise<Result<string, AccessDeniedSystemError | FileTooBigSystemError | IsDirectorySystemError | NameTooLongSystemError | NoEntrySystemError | NotDirectorySystemError | OutOfMemorySystemError | OverflowSystemError | PermissionDeniedSystemError | UnexpectedError>>;
+//#endregion
+//#region src/ops/file/write-text.d.ts
+export declare function writeTextFile({ path, text }: {
+  path: string;
+  text: string;
+}): Promise<Result<undefined, UnexpectedError>>;
+//#endregion
+//#region src/ops/remove-fs-entry.d.ts
+export declare function removeFsEntry({ path, recursive, force, retry }: {
+  path: string;
+  recursive?: boolean;
+  force?: boolean;
+  retry?: {
+    enabled: false;
+  } | {
+    enabled: true;
+    maxTimes: number;
+    delay: number;
+  };
+}): Promise<import("@little-nebulae/result").Failure<UnexpectedError<unknown, null>> | import("@little-nebulae/result").Success<undefined>>;
+//#endregion
+//#region src/ops/resolve-real-path.d.ts
+export declare function resolveRealPath({ path }: {
+  path: string;
+}): Promise<Result<string, UnexpectedError>>;
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,186 @@
+import { UnexpectedError, composeErrorMessage } from "@little-nebulae/error";
+import { fail, succeed } from "@little-nebulae/result";
+import { mkdir, readFile, readdir, realpath, rm, writeFile } from "node:fs/promises";
+import { AccessDeniedSystemError, FileTooBigSystemError, IsDirectorySystemError, NameTooLongSystemError, NoEntrySystemError, NotDirectorySystemError, OutOfMemorySystemError, OverflowSystemError, PermissionDeniedSystemError, SYSTEM_ERROR_RECORD, isErrnoException } from "@little-nebulae/system-error";
+//#region src/constants.ts
+const DEFAULT_CHARACTER_ENCODING = "utf-8";
+//#endregion
+//#region src/ops/dir/make.ts
+async function makeDirectory({ path }) {
+	try {
+		await mkdir(path);
+		return succeed(void 0);
+	} catch (error) {
+		return fail(new UnexpectedError({
+			message: composeErrorMessage({
+				operation: "make directory",
+				reason: "some unexpected error"
+			}),
+			cause: error,
+			meta: null
+		}));
+	}
+}
+//#endregion
+//#region src/ops/dir/make-recursively.ts
+async function makeDirectoryRecursively({ path }) {
+	try {
+		const createdDirPath = await mkdir(path, { recursive: true });
+		return succeed(createdDirPath);
+	} catch (error) {
+		return fail(new UnexpectedError({
+			message: composeErrorMessage({
+				operation: "make directory recursively",
+				reason: "some unexpected error"
+			}),
+			cause: error,
+			meta: null
+		}));
+	}
+}
+//#endregion
+//#region src/ops/dir/read.ts
+async function readDirectory({ path, recursive = false }) {
+	try {
+		const entryPaths = await readdir(path, {
+			encoding: DEFAULT_CHARACTER_ENCODING,
+			recursive
+		});
+		return succeed(entryPaths);
+	} catch (error) {
+		return fail(new UnexpectedError({
+			message: composeErrorMessage({
+				operation: "read directory",
+				reason: "some unexpected error"
+			}),
+			cause: error,
+			meta: null
+		}));
+	}
+}
+//#endregion
+//#region src/ops/file/read-text.ts
+async function readTextFile({ path, signal }) {
+	try {
+		const text = await readFile(path, {
+			encoding: DEFAULT_CHARACTER_ENCODING,
+			signal
+		});
+		return succeed(text);
+	} catch (error) {
+		if (isErrnoException(error)) switch (-(error.errno ?? 0)) {
+			case SYSTEM_ERROR_RECORD.PERMISSION_DENIED_SYSTEM_ERROR.errno.number: return fail(new PermissionDeniedSystemError({
+				message: `The operation to read file at ${path} was prevented by a file seal.`,
+				cause: error,
+				meta: null
+			}));
+			case SYSTEM_ERROR_RECORD.NO_ENTRY_SYSTEM_ERROR.errno.number: return fail(new NoEntrySystemError({
+				message: `${path} does not exist or is a
+              dangling symbolic link.`,
+				cause: error,
+				meta: null
+			}));
+			case SYSTEM_ERROR_RECORD.OUT_OF_MEMORY_SYSTEM_ERROR.errno.number: return fail(new OutOfMemorySystemError({
+				message: "Insufficient kernel memory was available.",
+				cause: error,
+				meta: null
+			}));
+			case SYSTEM_ERROR_RECORD.ACCESS_DENIED_SYSTEM_ERROR.errno.number: return fail(new AccessDeniedSystemError({
+				message: `The requested access to the file is not allowed, or search permission is denied for one of the directories in the path prefix of ${path}`,
+				cause: error,
+				meta: null
+			}));
+			case SYSTEM_ERROR_RECORD.NOT_DIRECTORY_SYSTEM_ERROR.errno.number: return fail(new NotDirectorySystemError({
+				message: `A component used as a directory in ${path} is not a directory.`,
+				cause: error,
+				meta: null
+			}));
+			case SYSTEM_ERROR_RECORD.IS_DIRECTORY_SYSTEM_ERROR.errno.number: return fail(new IsDirectorySystemError({
+				message: `${path} is a directory, not a file.`,
+				cause: error,
+				meta: null
+			}));
+			case SYSTEM_ERROR_RECORD.FILE_TOO_BIG_SYSTEM_ERROR.errno.number: return fail(new FileTooBigSystemError({
+				message: `${path} refers to a file that is too big to be opened.`,
+				cause: error,
+				meta: null
+			}));
+			case SYSTEM_ERROR_RECORD.NAME_TOO_LONG_SYSTEM_ERROR.errno.number: return fail(new NameTooLongSystemError({
+				message: `${path} or one of its components is too long.`,
+				cause: error,
+				meta: null
+			}));
+			case SYSTEM_ERROR_RECORD.OVERFLOW_SYSTEM_ERROR.errno.number: return fail(new OverflowSystemError({
+				message: `${path} refers to a regular file that is too large to be opened.`,
+				cause: error,
+				meta: null
+			}));
+		}
+		return fail(new UnexpectedError({
+			message: composeErrorMessage({
+				operation: "read text file",
+				reason: "some unexpected error"
+			}),
+			cause: error,
+			meta: null
+		}));
+	}
+}
+//#endregion
+//#region src/ops/file/write-text.ts
+async function writeTextFile({ path, text }) {
+	try {
+		await writeFile(path, text, { encoding: DEFAULT_CHARACTER_ENCODING });
+		return succeed(void 0);
+	} catch (error) {
+		return fail(new UnexpectedError({
+			message: composeErrorMessage({
+				operation: "write text file",
+				reason: "some unexpected error"
+			}),
+			cause: error,
+			meta: null
+		}));
+	}
+}
+//#endregion
+//#region src/ops/remove-fs-entry.ts
+async function removeFsEntry({ path, recursive = false, force = false, retry = { enabled: false } }) {
+	try {
+		await rm(path, {
+			recursive,
+			force,
+			maxRetries: retry.enabled ? retry.maxTimes : void 0,
+			retryDelay: retry.enabled ? retry.delay : void 0
+		});
+		return succeed(void 0);
+	} catch (error) {
+		return fail(new UnexpectedError({
+			message: composeErrorMessage({
+				operation: `remove fs entry at ${path}`,
+				reason: "some unexpected error"
+			}),
+			cause: error,
+			meta: null
+		}));
+	}
+}
+//#endregion
+//#region src/ops/resolve-real-path.ts
+async function resolveRealPath({ path }) {
+	try {
+		const realPath = await realpath(path, { encoding: DEFAULT_CHARACTER_ENCODING });
+		return succeed(realPath);
+	} catch (error) {
+		return fail(new UnexpectedError({
+			message: composeErrorMessage({
+				operation: "resolve real path",
+				reason: "some unexpected error"
+			}),
+			cause: error,
+			meta: null
+		}));
+	}
+}
+//#endregion
+export { DEFAULT_CHARACTER_ENCODING, makeDirectory, makeDirectoryRecursively, readDirectory, readTextFile, removeFsEntry, resolveRealPath, writeTextFile };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@little-nebulae/node-fs",
+  "version": "0.1.0",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/core": "0.18.5",
+    "@little-nebulae/error": "1.1.0",
+    "@little-nebulae/result": "1.0.0",
+    "@little-nebulae/system-error": "2.0.0",
+    "@little-nebulae/type-utils": "1.1.0",
+    "@types/node": "26.6.2",
+    "oxfmt": "0.68.0",
+    "oxlint": "1.83.0",
+    "oxlint-tsgolint": "7.0.2002",
+    "publint": "0.3.24",
+    "tsdown": "0.23.0",
+    "tsx": "4.23.13",
+    "typescript": "7.0.2",
+    "vitest": "5.0.1"
+  },
+  "peerDependencies": {
+    "@little-nebulae/error": "^1.0.0",
+    "@little-nebulae/result": "^1.0.0",
+    "@little-nebulae/system-error": "^1.0.0",
+    "@little-nebulae/type-utils": "^1.0.0"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "12.4.2",
+      "onFail": "warn"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "try": "tsx ./src/try.ts",
+    "fmt": "oxfmt --disable-nested-config",
+    "fmt:check": "oxfmt --check --disable-nested-config",
+    "lint": "oxlint --disable-nested-config",
+    "lint:fix": "oxlint --fix --disable-nested-config",
+    "check": "pnpm run lint && pnpm run fmt:check",
+    "fix": "pnpm run lint:fix && pnpm run fmt",
+    "test": "vitest run"
+  }
+}