jg-fs 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.1.0
+
+A fresh start: breaking changes in a minor version, once, because nothing depended on 1.0.x.
+
+### Added
+
+- A `schema` option for `readJsonFile`, in the async and sync APIs, which validates the parsed content and types the result. Its errors propagate unchanged. `ISchema` and `IReadJsonFileOptions` are exported.
+- `API.md`, the full API reference, generated from the TSDoc of the version it ships with, so it can be read from `node_modules` without a browser.
+
+### Changed
+
+- Errors are `Exception`s from `jg-exception` 1.1.0: the code, the data, and the cause each have their own field, nothing is encoded into the message, and `toJSON()` and `toString()` follow `jg-exception`.
+- Error messages say what failed at that step and keep the error underneath as `cause`, instead of repeating its message, so `extractMessage` prints each layer of the chain once.
+- `readJsonFile` returns `unknown` without a schema or a type argument, instead of `Record<string, unknown>`.
+- `readJSONFile` and `writeJSONFile` are `readJsonFile` and `writeJsonFile`, in the async and sync APIs, so acronyms are cased as words, like every other name in the packages.
+
 ## 1.0.1
 
 ### Changed
@@ -8,23 +24,11 @@
 
 ## 1.0.0
 
-The first release of `jg-fs`, which replaces `fs-utils-async` 1.0.1 and, at `jg-fs/sync`, `fs-utils-sync` 1.2.0.
+The first release.
 
 ### Added
 
-- The `jg-fs/sync` entry, with the same functions as the async root entry.
+- Async functions for paths, directories, and files, such as `getDirectoryElements`, `readJSONFile`, `writeFileAtomic`, and `readBoundedFile`.
+- The `jg-fs/sync` entry, with the same functions, synchronous.
 - `ERRORS`, the codes of every error the package throws.
-
-### Changed
-
-- Empty content is allowed when reading and writing text and binary files.
-- `createDirectory` succeeds when the directory already exists.
-- `includeExts` matches extensions case-insensitively.
-- The sync `readDirectory` joins paths with the platform's separator, and the sync `getDirectoryElements` skips entries removed while it reads.
-- The async `getDirectoryElements` reads at most 32 entries at once.
-- `readFile` returns `string` with an encoding and `Buffer` without one.
-- Errors are `Exception`s from `jg-exception`.
-
-### Fixed
-
-- Typos in several error messages.
+- Empty content is allowed when reading and writing text and binary files, and `createDirectory` succeeds when the directory already exists.

package/README.md

@@ -13,11 +13,14 @@ npm install jg-fs
 The root entry is async, and `jg-fs/sync` has the same functions, synchronous:
 
 ```ts
-import { readJSONFile, writeFileAtomic, writeTextFile } from 'jg-fs';
+import { readJsonFile, writeFileAtomic, writeTextFile } from 'jg-fs';
 import { readTextFile } from 'jg-fs/sync';
+import { z } from 'zod';
+
+const Config = z.object({ port: z.number() });
 
 await writeTextFile('notes/today.md', '# Today'); // creates notes/ when it's missing
-const config = await readJSONFile<{ port: number }>('config.json');
+const config = await readJsonFile('config.json', { schema: Config }); // validated, and typed by the schema
 await writeFileAtomic('state.json', JSON.stringify(state)); // readers never see a partial file
 
 const readme = readTextFile('README.md');
@@ -47,27 +50,9 @@ if (isPathWithin(uploadsDirectory, path)) {
 
 Failures throw `Exception`s from `jg-exception`, with the codes in `ERRORS`.
 
-## Coming from `fs-utils-async` and `fs-utils-sync`
-
-| Old                              | `jg-fs`                      |
-| -------------------------------- | ---------------------------- |
-| `import … from 'fs-utils-async'` | `import … from 'jg-fs'`      |
-| `import … from 'fs-utils-sync'`  | `import … from 'jg-fs/sync'` |
-| the codes, not exported          | `ERRORS`                     |
-
-Changed behavior:
-
-- Empty content is allowed. `readTextFile`, `readBufferFile`, and `readFile` return empty content instead of throwing, and `writeTextFile('')` and `writeBufferFile` with an empty Buffer write empty files. `FILE_CONTENT_IS_EMPTY_OR_INVALID` now means data of the wrong type, or JSON that is empty or can't be parsed or stringified. Code that relied on the throw to detect empty files needs its own check.
-- `createDirectory` succeeds when the directory already exists, keeping its contents. It throws `DIRECTORY_ALREADY_EXISTS` only when a file or something else that isn't a directory is at the path.
-- `includeExts` matches extensions case-insensitively, so `.JSON` and `.json` are the same.
-- The sync `readDirectory` joins paths with the platform's separator, and the sync `getDirectoryElements` skips entries removed while it reads the directory, as the async one already did.
-- The async `getDirectoryElements` reads at most 32 entries at once.
-- `readFile` returns `string` when given an encoding and `Buffer` otherwise, instead of `string | Buffer`.
-- Errors are `Exception`s from `jg-exception`, with the same codes.
-
 ## Documentation
 
-The full API reference is at https://jg-packages.jesusgraterol.dev/packages/jg-fs/.
+The full API reference ships in the package as `API.md`, generated from its TSDoc for the installed version, and is at https://jg-packages.jesusgraterol.dev/packages/jg-fs/.
 
 ## License
 

package/dist/async/directories/directories.d.ts

@@ -4,6 +4,8 @@ import { type IDirectoryElementsOptions, type IDirectoryPathElements } from '../
  * @param path The path.
  * @returns A promise that resolves to whether the path is a directory.
  * @example
+ * import { isDirectory } from 'jg-fs';
+ *
  * await isDirectory('dist'); // true
  */
 export declare const isDirectory: (path: string) => Promise<boolean>;
@@ -12,6 +14,8 @@ export declare const isDirectory: (path: string) => Promise<boolean>;
  * @param path The directory's path.
  * @returns A promise that resolves once the directory is gone.
  * @example
+ * import { deleteDirectory } from 'jg-fs';
+ *
  * await deleteDirectory('dist');
  */
 export declare const deleteDirectory: (path: string) => Promise<void>;
@@ -22,6 +26,8 @@ export declare const deleteDirectory: (path: string) => Promise<void>;
  * @param deleteIfExists Whether to delete an existing directory and its contents first.
  * @returns A promise that resolves once the directory exists.
  * @example
+ * import { createDirectory } from 'jg-fs';
+ *
  * await createDirectory('dist/assets'); // creates missing parents too
  * await createDirectory('dist', true); // replaces it with an empty directory
  * @throws
@@ -34,6 +40,8 @@ export declare const createDirectory: (path: string, deleteIfExists?: boolean) =
  * @param destPath Where to copy it.
  * @returns A promise that resolves once the copy is complete.
  * @example
+ * import { copyDirectory } from 'jg-fs';
+ *
  * await copyDirectory('templates', 'dist/templates');
  * @throws
  * - NOT_A_DIRECTORY: if the srcPath is not a directory
@@ -45,6 +53,8 @@ export declare const copyDirectory: (srcPath: string, destPath: string) => Promi
  * @param path Where to create the link.
  * @returns A promise that resolves once the link exists.
  * @example
+ * import { createDirectorySymLink } from 'jg-fs';
+ *
  * await createDirectorySymLink('releases/1.4.0', 'current');
  * @throws
  * - NON_EXISTENT_DIRECTORY: if the target directory doesn't exist
@@ -57,6 +67,8 @@ export declare const createDirectorySymLink: (target: string, path: string) => P
  * @param recursive Whether to include the contents of subdirectories.
  * @returns A promise that resolves to the content paths.
  * @example
+ * import { readDirectory } from 'jg-fs';
+ *
  * await readDirectory('dist'); // ['dist/index.js', 'dist/assets']
  * await readDirectory('dist', true); // includes the contents of dist/assets
  * @throws
@@ -71,6 +83,8 @@ export declare const readDirectory: (path: string, recursive?: boolean) => Promi
  * @param options The extensions to include and how to sort.
  * @returns A promise that resolves to the grouped elements.
  * @example
+ * import { getDirectoryElements } from 'jg-fs';
+ *
  * const { files } = await getDirectoryElements('content', { includeExts: ['.md'], sortByKey: 'creation', sortOrder: 'desc' });
  * @throws
  * - NOT_A_DIRECTORY: if the path doesn't exist or is not a directory

package/dist/async/directories/directories.js

@@ -9,6 +9,8 @@ import { mapWithConcurrency } from './utilities.js';
  * @param path The path.
  * @returns A promise that resolves to whether the path is a directory.
  * @example
+ * import { isDirectory } from 'jg-fs';
+ *
  * await isDirectory('dist'); // true
  */
 export const isDirectory = async (path) => (await getPathElement(path))?.isDirectory ?? false;
@@ -17,6 +19,8 @@ export const isDirectory = async (path) => (await getPathElement(path))?.isDirec
  * @param path The directory's path.
  * @returns A promise that resolves once the directory is gone.
  * @example
+ * import { deleteDirectory } from 'jg-fs';
+ *
  * await deleteDirectory('dist');
  */
 export const deleteDirectory = (path) => rm(path, { recursive: true, force: true });
@@ -27,6 +31,8 @@ export const deleteDirectory = (path) => rm(path, { recursive: true, force: true
  * @param deleteIfExists Whether to delete an existing directory and its contents first.
  * @returns A promise that resolves once the directory exists.
  * @example
+ * import { createDirectory } from 'jg-fs';
+ *
  * await createDirectory('dist/assets'); // creates missing parents too
  * await createDirectory('dist', true); // replaces it with an empty directory
  * @throws
@@ -35,7 +41,9 @@ export const deleteDirectory = (path) => rm(path, { recursive: true, force: true
 export const createDirectory = async (path, deleteIfExists) => {
     const element = await getPathElement(path);
     if (element !== null && !element.isDirectory) {
-        throw new Exception(`The path '${path}' already exists and is not a directory.`, ERRORS.DIRECTORY_ALREADY_EXISTS);
+        throw new Exception(`The path '${path}' already exists and is not a directory.`, {
+            code: ERRORS.DIRECTORY_ALREADY_EXISTS,
+        });
     }
     if (element !== null && deleteIfExists) {
         await deleteDirectory(path);
@@ -48,6 +56,8 @@ export const createDirectory = async (path, deleteIfExists) => {
  * @param destPath Where to copy it.
  * @returns A promise that resolves once the copy is complete.
  * @example
+ * import { copyDirectory } from 'jg-fs';
+ *
  * await copyDirectory('templates', 'dist/templates');
  * @throws
  * - NOT_A_DIRECTORY: if the srcPath is not a directory
@@ -65,6 +75,8 @@ export const copyDirectory = async (srcPath, destPath) => {
  * @param path Where to create the link.
  * @returns A promise that resolves once the link exists.
  * @example
+ * import { createDirectorySymLink } from 'jg-fs';
+ *
  * await createDirectorySymLink('releases/1.4.0', 'current');
  * @throws
  * - NON_EXISTENT_DIRECTORY: if the target directory doesn't exist
@@ -73,7 +85,9 @@ export const copyDirectory = async (srcPath, destPath) => {
 export const createDirectorySymLink = async (target, path) => {
     const element = await getPathElement(target);
     if (element === null) {
-        throw new Exception(`The target directory '${target}' does not exist.`, ERRORS.NON_EXISTENT_DIRECTORY);
+        throw new Exception(`The target directory '${target}' does not exist.`, {
+            code: ERRORS.NON_EXISTENT_DIRECTORY,
+        });
     }
     if (!element.isDirectory) {
         throw notADirectory(target);
@@ -86,6 +100,8 @@ export const createDirectorySymLink = async (target, path) => {
  * @param recursive Whether to include the contents of subdirectories.
  * @returns A promise that resolves to the content paths.
  * @example
+ * import { readDirectory } from 'jg-fs';
+ *
  * await readDirectory('dist'); // ['dist/index.js', 'dist/assets']
  * await readDirectory('dist', true); // includes the contents of dist/assets
  * @throws
@@ -106,6 +122,8 @@ export const readDirectory = async (path, recursive = false) => {
  * @param options The extensions to include and how to sort.
  * @returns A promise that resolves to the grouped elements.
  * @example
+ * import { getDirectoryElements } from 'jg-fs';
+ *
  * const { files } = await getDirectoryElements('content', { includeExts: ['.md'], sortByKey: 'creation', sortOrder: 'desc' });
  * @throws
  * - NOT_A_DIRECTORY: if the path doesn't exist or is not a directory

package/dist/async/directories/directories.js.map

@@ -1 +1 @@
-{"version":3,"file":"directories.js","sourceRoot":"","sources":["../../../src/async/directories/directories.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EACL,6BAA6B,EAC7B,8BAA8B,EAC9B,MAAM,EACN,sBAAsB,EACtB,aAAa,GAId,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAAE,IAAY,EAAoB,EAAE,CAClE,CAAC,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC,EAAE,WAAW,IAAI,KAAK,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAY,EAAiB,EAAE,CAC7D,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAE7C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAAE,IAAY,EAAE,cAAwB,EAAiB,EAAE;IAC7F,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,OAAO,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QAC7C,MAAM,IAAI,SAAS,CACjB,aAAa,IAAI,0CAA0C,EAC3D,MAAM,CAAC,wBAAwB,CAChC,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,KAAK,IAAI,IAAI,cAAc,EAAE,CAAC;QACvC,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IACD,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AACzC,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAAE,OAAe,EAAE,QAAgB,EAAiB,EAAE;IACtF,IAAI,CAAC,CAAC,MAAM,WAAW,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QAClC,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IACD,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAC;IAChC,MAAM,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AACnD,CAAC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,KAAK,EAAE,MAAc,EAAE,IAAY,EAAiB,EAAE;IAC1F,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,MAAM,IAAI,SAAS,CACjB,yBAAyB,MAAM,mBAAmB,EAClD,MAAM,CAAC,sBAAsB,CAC9B,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QACzB,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IACD,MAAM,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;AACrC,CAAC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAChC,IAAY,EACZ,YAAqB,KAAK,EACP,EAAE;IACrB,IAAI,CAAC,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAC/B,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;IAC3E,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC;AACpE,CAAC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,EACvC,IAAY,EACZ,OAA4C,EACX,EAAE;IACnC,MAAM,YAAY,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,CACf,MAAM,kBAAkB,CAAC,YAAY,EAAE,8BAA8B,EAAE,cAAc,CAAC,CACvF,CAAC,MAAM,CAAC,CAAC,OAAO,EAA2B,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC;IACjE,OAAO,sBAAsB,CAAC,QAAQ,EAAE,6BAA6B,CAAC,OAAO,CAAC,CAAC,CAAC;AAClF,CAAC,CAAC","sourcesContent":["import { cp, mkdir, readdir, rm, symlink } from 'node:fs/promises';\nimport { join } from 'node:path';\nimport { Exception } from 'jg-exception';\n\nimport {\n  buildDirectoryElementsOptions,\n  DIRECTORY_ELEMENTS_CONCURRENCY,\n  ERRORS,\n  groupDirectoryElements,\n  notADirectory,\n  type IDirectoryElementsOptions,\n  type IDirectoryPathElements,\n  type IPathElement,\n} from '../../shared/index.js';\nimport { getPathElement } from '../general/index.js';\n\nimport { mapWithConcurrency } from './utilities.js';\n\n/**\n * Checks whether a path exists and is a directory.\n * @param path The path.\n * @returns A promise that resolves to whether the path is a directory.\n * @example\n * await isDirectory('dist'); // true\n */\nexport const isDirectory = async (path: string): Promise<boolean> =>\n  (await getPathElement(path))?.isDirectory ?? false;\n\n/**\n * Deletes a directory and everything in it. A missing directory is not an error.\n * @param path The directory's path.\n * @returns A promise that resolves once the directory is gone.\n * @example\n * await deleteDirectory('dist');\n */\nexport const deleteDirectory = (path: string): Promise<void> =>\n  rm(path, { recursive: true, force: true });\n\n/**\n * Creates a directory, with any missing parents. An existing directory is kept, or replaced with\n * an empty one when `deleteIfExists` is set.\n * @param path The directory's path.\n * @param deleteIfExists Whether to delete an existing directory and its contents first.\n * @returns A promise that resolves once the directory exists.\n * @example\n * await createDirectory('dist/assets'); // creates missing parents too\n * await createDirectory('dist', true); // replaces it with an empty directory\n * @throws\n * - DIRECTORY_ALREADY_EXISTS: if something other than a directory exists at the path\n */\nexport const createDirectory = async (path: string, deleteIfExists?: boolean): Promise<void> => {\n  const element = await getPathElement(path);\n  if (element !== null && !element.isDirectory) {\n    throw new Exception(\n      `The path '${path}' already exists and is not a directory.`,\n      ERRORS.DIRECTORY_ALREADY_EXISTS,\n    );\n  }\n  if (element !== null && deleteIfExists) {\n    await deleteDirectory(path);\n  }\n  await mkdir(path, { recursive: true });\n};\n\n/**\n * Copies a directory and everything in it, replacing the destination completely.\n * @param srcPath The directory to copy.\n * @param destPath Where to copy it.\n * @returns A promise that resolves once the copy is complete.\n * @example\n * await copyDirectory('templates', 'dist/templates');\n * @throws\n * - NOT_A_DIRECTORY: if the srcPath is not a directory\n */\nexport const copyDirectory = async (srcPath: string, destPath: string): Promise<void> => {\n  if (!(await isDirectory(srcPath))) {\n    throw notADirectory(srcPath);\n  }\n  await deleteDirectory(destPath);\n  await cp(srcPath, destPath, { recursive: true });\n};\n\n/**\n * Creates a symbolic link to a directory.\n * @param target The directory the link points to.\n * @param path Where to create the link.\n * @returns A promise that resolves once the link exists.\n * @example\n * await createDirectorySymLink('releases/1.4.0', 'current');\n * @throws\n * - NON_EXISTENT_DIRECTORY: if the target directory doesn't exist\n * - NOT_A_DIRECTORY: if the target directory is not considered a directory by the OS\n */\nexport const createDirectorySymLink = async (target: string, path: string): Promise<void> => {\n  const element = await getPathElement(target);\n  if (element === null) {\n    throw new Exception(\n      `The target directory '${target}' does not exist.`,\n      ERRORS.NON_EXISTENT_DIRECTORY,\n    );\n  }\n  if (!element.isDirectory) {\n    throw notADirectory(target);\n  }\n  await symlink(target, path, 'dir');\n};\n\n/**\n * Lists a directory's contents as paths joined to the directory's path.\n * @param path The directory's path.\n * @param recursive Whether to include the contents of subdirectories.\n * @returns A promise that resolves to the content paths.\n * @example\n * await readDirectory('dist'); // ['dist/index.js', 'dist/assets']\n * await readDirectory('dist', true); // includes the contents of dist/assets\n * @throws\n * - NOT_A_DIRECTORY: if the path doesn't exist or is not a directory\n */\nexport const readDirectory = async (\n  path: string,\n  recursive: boolean = false,\n): Promise<string[]> => {\n  if (!(await isDirectory(path))) {\n    throw notADirectory(path);\n  }\n  const contentPaths = await readdir(path, { encoding: 'utf-8', recursive });\n  return contentPaths.map((contentPath) => join(path, contentPath));\n};\n\n/**\n * Lists a directory's elements grouped by kind: directories, files (filtered by extension), and\n * symbolic links, each group sorted. Entries removed while the directory is read are left out, and\n * at most 32 entries are read at once.\n * @param path The directory's path.\n * @param options The extensions to include and how to sort.\n * @returns A promise that resolves to the grouped elements.\n * @example\n * const { files } = await getDirectoryElements('content', { includeExts: ['.md'], sortByKey: 'creation', sortOrder: 'desc' });\n * @throws\n * - NOT_A_DIRECTORY: if the path doesn't exist or is not a directory\n */\nexport const getDirectoryElements = async (\n  path: string,\n  options?: Partial<IDirectoryElementsOptions>,\n): Promise<IDirectoryPathElements> => {\n  const contentPaths = await readDirectory(path);\n  const elements = (\n    await mapWithConcurrency(contentPaths, DIRECTORY_ELEMENTS_CONCURRENCY, getPathElement)\n  ).filter((element): element is IPathElement => element !== null);\n  return groupDirectoryElements(elements, buildDirectoryElementsOptions(options));\n};\n"]}
+{"version":3,"file":"directories.js","sourceRoot":"","sources":["../../../src/async/directories/directories.ts"],"names":[],"mappings":"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","sourcesContent":["import { cp, mkdir, readdir, rm, symlink } from 'node:fs/promises';\nimport { join } from 'node:path';\nimport { Exception } from 'jg-exception';\n\nimport {\n  buildDirectoryElementsOptions,\n  DIRECTORY_ELEMENTS_CONCURRENCY,\n  ERRORS,\n  groupDirectoryElements,\n  notADirectory,\n  type IDirectoryElementsOptions,\n  type IDirectoryPathElements,\n  type IPathElement,\n} from '../../shared/index.js';\nimport { getPathElement } from '../general/index.js';\n\nimport { mapWithConcurrency } from './utilities.js';\n\n/**\n * Checks whether a path exists and is a directory.\n * @param path The path.\n * @returns A promise that resolves to whether the path is a directory.\n * @example\n * import { isDirectory } from 'jg-fs';\n *\n * await isDirectory('dist'); // true\n */\nexport const isDirectory = async (path: string): Promise<boolean> =>\n  (await getPathElement(path))?.isDirectory ?? false;\n\n/**\n * Deletes a directory and everything in it. A missing directory is not an error.\n * @param path The directory's path.\n * @returns A promise that resolves once the directory is gone.\n * @example\n * import { deleteDirectory } from 'jg-fs';\n *\n * await deleteDirectory('dist');\n */\nexport const deleteDirectory = (path: string): Promise<void> =>\n  rm(path, { recursive: true, force: true });\n\n/**\n * Creates a directory, with any missing parents. An existing directory is kept, or replaced with\n * an empty one when `deleteIfExists` is set.\n * @param path The directory's path.\n * @param deleteIfExists Whether to delete an existing directory and its contents first.\n * @returns A promise that resolves once the directory exists.\n * @example\n * import { createDirectory } from 'jg-fs';\n *\n * await createDirectory('dist/assets'); // creates missing parents too\n * await createDirectory('dist', true); // replaces it with an empty directory\n * @throws\n * - DIRECTORY_ALREADY_EXISTS: if something other than a directory exists at the path\n */\nexport const createDirectory = async (path: string, deleteIfExists?: boolean): Promise<void> => {\n  const element = await getPathElement(path);\n  if (element !== null && !element.isDirectory) {\n    throw new Exception(`The path '${path}' already exists and is not a directory.`, {\n      code: ERRORS.DIRECTORY_ALREADY_EXISTS,\n    });\n  }\n  if (element !== null && deleteIfExists) {\n    await deleteDirectory(path);\n  }\n  await mkdir(path, { recursive: true });\n};\n\n/**\n * Copies a directory and everything in it, replacing the destination completely.\n * @param srcPath The directory to copy.\n * @param destPath Where to copy it.\n * @returns A promise that resolves once the copy is complete.\n * @example\n * import { copyDirectory } from 'jg-fs';\n *\n * await copyDirectory('templates', 'dist/templates');\n * @throws\n * - NOT_A_DIRECTORY: if the srcPath is not a directory\n */\nexport const copyDirectory = async (srcPath: string, destPath: string): Promise<void> => {\n  if (!(await isDirectory(srcPath))) {\n    throw notADirectory(srcPath);\n  }\n  await deleteDirectory(destPath);\n  await cp(srcPath, destPath, { recursive: true });\n};\n\n/**\n * Creates a symbolic link to a directory.\n * @param target The directory the link points to.\n * @param path Where to create the link.\n * @returns A promise that resolves once the link exists.\n * @example\n * import { createDirectorySymLink } from 'jg-fs';\n *\n * await createDirectorySymLink('releases/1.4.0', 'current');\n * @throws\n * - NON_EXISTENT_DIRECTORY: if the target directory doesn't exist\n * - NOT_A_DIRECTORY: if the target directory is not considered a directory by the OS\n */\nexport const createDirectorySymLink = async (target: string, path: string): Promise<void> => {\n  const element = await getPathElement(target);\n  if (element === null) {\n    throw new Exception(`The target directory '${target}' does not exist.`, {\n      code: ERRORS.NON_EXISTENT_DIRECTORY,\n    });\n  }\n  if (!element.isDirectory) {\n    throw notADirectory(target);\n  }\n  await symlink(target, path, 'dir');\n};\n\n/**\n * Lists a directory's contents as paths joined to the directory's path.\n * @param path The directory's path.\n * @param recursive Whether to include the contents of subdirectories.\n * @returns A promise that resolves to the content paths.\n * @example\n * import { readDirectory } from 'jg-fs';\n *\n * await readDirectory('dist'); // ['dist/index.js', 'dist/assets']\n * await readDirectory('dist', true); // includes the contents of dist/assets\n * @throws\n * - NOT_A_DIRECTORY: if the path doesn't exist or is not a directory\n */\nexport const readDirectory = async (\n  path: string,\n  recursive: boolean = false,\n): Promise<string[]> => {\n  if (!(await isDirectory(path))) {\n    throw notADirectory(path);\n  }\n  const contentPaths = await readdir(path, { encoding: 'utf-8', recursive });\n  return contentPaths.map((contentPath) => join(path, contentPath));\n};\n\n/**\n * Lists a directory's elements grouped by kind: directories, files (filtered by extension), and\n * symbolic links, each group sorted. Entries removed while the directory is read are left out, and\n * at most 32 entries are read at once.\n * @param path The directory's path.\n * @param options The extensions to include and how to sort.\n * @returns A promise that resolves to the grouped elements.\n * @example\n * import { getDirectoryElements } from 'jg-fs';\n *\n * const { files } = await getDirectoryElements('content', { includeExts: ['.md'], sortByKey: 'creation', sortOrder: 'desc' });\n * @throws\n * - NOT_A_DIRECTORY: if the path doesn't exist or is not a directory\n */\nexport const getDirectoryElements = async (\n  path: string,\n  options?: Partial<IDirectoryElementsOptions>,\n): Promise<IDirectoryPathElements> => {\n  const contentPaths = await readDirectory(path);\n  const elements = (\n    await mapWithConcurrency(contentPaths, DIRECTORY_ELEMENTS_CONCURRENCY, getPathElement)\n  ).filter((element): element is IPathElement => element !== null);\n  return groupDirectoryElements(elements, buildDirectoryElementsOptions(options));\n};\n"]}

package/dist/async/files/files.d.ts

@@ -1,11 +1,13 @@
 import { Buffer } from 'node:buffer';
 import type { WriteFileOptions } from 'node:fs';
-import { type IReadBufferFileOptions, type IReadFileOptions, type IReadStringFileOptions } from '../../shared/index.js';
+import { type IReadBufferFileOptions, type IReadFileOptions, type IReadJsonFileOptions, type IReadStringFileOptions } from '../../shared/index.js';
 /**
  * Checks whether a path exists and is a regular file.
  * @param path The path.
  * @returns A promise that resolves to whether the path is a file.
  * @example
+ * import { isFile } from 'jg-fs';
+ *
  * await isFile('package.json'); // true
  */
 export declare const isFile: (path: string) => Promise<boolean>;
@@ -16,6 +18,9 @@ export declare const isFile: (path: string) => Promise<boolean>;
  * @param options Node.js's writeFile options, such as the encoding or mode.
  * @returns A promise that resolves once the file is written.
  * @example
+ * import { writeFile } from 'jg-fs';
+ *
+ * const csv = 'id,name\n1,Ada\n';
  * await writeFile('out/report.csv', csv, { encoding: 'utf-8' });
  */
 export declare const writeFile: (path: string, data: string | NodeJS.ArrayBufferView, options?: WriteFileOptions) => Promise<void>;
@@ -25,6 +30,8 @@ export declare const writeFile: (path: string, data: string | NodeJS.ArrayBuffer
  * @param data The text.
  * @returns A promise that resolves once the file is written.
  * @example
+ * import { writeTextFile } from 'jg-fs';
+ *
  * await writeTextFile('notes/today.md', '# Today');
  * @throws
  * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if the data isn't a string
@@ -37,17 +44,22 @@ export declare const writeTextFile: (path: string, data: string) => Promise<void
  * @param space The indentation for stringified values.
  * @returns A promise that resolves once the file is written.
  * @example
- * await writeJSONFile('config.json', { port: 8080 });
+ * import { writeJsonFile } from 'jg-fs';
+ *
+ * await writeJsonFile('config.json', { port: 8080 });
  * @throws
  * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if the JSON content cannot be stringified or is empty
  */
-export declare const writeJSONFile: <T = Record<string, unknown>>(path: string, data: T | string, space?: number) => Promise<void>;
+export declare const writeJsonFile: <T = Record<string, unknown>>(path: string, data: T | string, space?: number) => Promise<void>;
 /**
  * Writes a binary file. An empty Buffer writes an empty file.
  * @param path The file's path.
  * @param data The content.
  * @returns A promise that resolves once the file is written.
  * @example
+ * import { writeBufferFile } from 'jg-fs';
+ *
+ * const imageBuffer = Buffer.from('iVBORw0KGgo=', 'base64');
  * await writeBufferFile('avatar.png', imageBuffer);
  * @throws
  * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if the data isn't a Buffer
@@ -59,6 +71,8 @@ export declare const writeBufferFile: (path: string, data: Buffer) => Promise<vo
  * @param options Node.js's readFile options, such as the encoding.
  * @returns A promise that resolves to the content.
  * @example
+ * import { readFile } from 'jg-fs';
+ *
  * await readFile('notes.md', 'utf-8'); // a string
  * await readFile('avatar.png'); // a Buffer
  * @throws
@@ -72,27 +86,39 @@ export declare function readFile(path: string, options?: IReadFileOptions): Prom
  * @param path The file's path.
  * @returns A promise that resolves to the text.
  * @example
+ * import { readTextFile } from 'jg-fs';
+ *
  * const markdown = await readTextFile('README.md');
  * @throws
  * - NOT_A_FILE: if the path doesn't exist or is not a file
  */
 export declare const readTextFile: (path: string) => Promise<string>;
 /**
- * Reads and parses a JSON file.
+ * Reads and parses a JSON file, and validates it with the schema when there is one. Without a
+ * schema, the value is `unknown`, or the type you pass.
  * @param path The file's path.
+ * @param options The schema, such as a Zod schema, whose errors propagate unchanged.
  * @returns A promise that resolves to the parsed value.
  * @example
- * const config = await readJSONFile<{ port: number }>('config.json');
+ * import { readJsonFile } from 'jg-fs';
+ *
+ * const config = await readJsonFile('config.json', { schema: Config }); // Config's type
+ * @example
+ * import { readJsonFile } from 'jg-fs';
+ *
+ * const value = await readJsonFile('data.json'); // unknown
  * @throws
  * - NOT_A_FILE: if the path doesn't exist or is not a file
  * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if the file's JSON content cannot be parsed
  */
-export declare const readJSONFile: <T = Record<string, unknown>>(path: string) => Promise<T>;
+export declare const readJsonFile: <T = unknown>(path: string, options?: IReadJsonFileOptions<T>) => Promise<T>;
 /**
  * Reads a binary file. An empty file reads as an empty Buffer.
  * @param path The file's path.
  * @returns A promise that resolves to the content.
  * @example
+ * import { readBufferFile } from 'jg-fs';
+ *
  * const image = await readBufferFile('avatar.png');
  * @throws
  * - NOT_A_FILE: if the path doesn't exist or is not a file
@@ -104,6 +130,8 @@ export declare const readBufferFile: (path: string) => Promise<Buffer>;
  * @param destPath Where to copy it.
  * @returns A promise that resolves once the copy exists.
  * @example
+ * import { copyFile } from 'jg-fs';
+ *
  * await copyFile('config.example.json', 'config.json');
  * @throws
  * - NOT_A_FILE: if the srcPath doesn't exist or is not a file
@@ -114,6 +142,8 @@ export declare const copyFile: (srcPath: string, destPath: string) => Promise<vo
  * @param path The file's path.
  * @returns A promise that resolves once the file is gone.
  * @example
+ * import { deleteFile } from 'jg-fs';
+ *
  * await deleteFile('cache.json');
  * @throws
  * - NOT_A_FILE: if the path doesn't exist or is not a file
@@ -125,6 +155,8 @@ export declare const deleteFile: (path: string) => Promise<void>;
  * @param path Where to create the link.
  * @returns A promise that resolves once the link exists.
  * @example
+ * import { createFileSymLink } from 'jg-fs';
+ *
  * await createFileSymLink('config.production.json', 'config.json');
  * @throws
  * - NON_EXISTENT_FILE: if the target file does not exist
@@ -143,8 +175,11 @@ export declare const createFileSymLink: (target: string, path: string) => Promis
  * @param mode The permission bits of the written file, such as `0o600`.
  * @returns A promise that resolves once the file is written and flushed.
  * @example
+ * import { writeFileAtomic } from 'jg-fs';
+ *
+ * const state = { step: 2 };
  * await writeFileAtomic('state.json', JSON.stringify(state)); // readers never see a partial file
- * await writeFileAtomic('secrets.env', contents, 0o600);
+ * await writeFileAtomic('secrets.env', 'TOKEN=abc\n', 0o600); // only the owner can read it
  */
 export declare const writeFileAtomic: (path: string, data: string | NodeJS.ArrayBufferView, mode?: number) => Promise<void>;
 /**
@@ -156,7 +191,10 @@ export declare const writeFileAtomic: (path: string, data: string | NodeJS.Array
  * @param maxBytes The largest size accepted, in bytes.
  * @returns A promise that resolves to the content.
  * @example
- * const upload = await readBoundedFile(join(uploadsDirectory, name), 5 * 1024 * 1024); // at most 5 MB
+ * import { join } from 'node:path';
+ * import { readBoundedFile } from 'jg-fs';
+ *
+ * const upload = await readBoundedFile(join('uploads', 'avatar.png'), 5 * 1024 * 1024); // at most 5 MB
  * @throws
  * - NOT_A_FILE: if the path doesn't exist, its final component is a symbolic link, or it isn't a regular file
  * - FILE_TOO_LARGE: if the file holds more than maxBytes bytes

package/dist/async/files/files.js

@@ -3,7 +3,7 @@ import { randomUUID } from 'node:crypto';
 import { copyFile as copyFileNode, mkdir, open, readFile as readFileNode, rename, rm, symlink, unlink, writeFile as writeFileNode, } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { Exception } from 'jg-exception';
-import { assertBufferData, assertTextData, BOUNDED_READ_CHUNK_SIZE, ERRORS, fileTooLarge, notAFile, parseJSONContent, serializeJSONData, } from '../../shared/index.js';
+import { assertBufferData, assertTextData, BOUNDED_READ_CHUNK_SIZE, ERRORS, fileTooLarge, notAFile, parseJsonContent, serializeJsonData, } from '../../shared/index.js';
 import { getPathElement } from '../general/index.js';
 import { openWithoutFollowing, readPermissionBits, syncDirectory } from './utilities.js';
 /**
@@ -11,6 +11,8 @@ import { openWithoutFollowing, readPermissionBits, syncDirectory } from './utili
  * @param path The path.
  * @returns A promise that resolves to whether the path is a file.
  * @example
+ * import { isFile } from 'jg-fs';
+ *
  * await isFile('package.json'); // true
  */
 export const isFile = async (path) => (await getPathElement(path))?.isFile ?? false;
@@ -21,6 +23,9 @@ export const isFile = async (path) => (await getPathElement(path))?.isFile ?? fa
  * @param options Node.js's writeFile options, such as the encoding or mode.
  * @returns A promise that resolves once the file is written.
  * @example
+ * import { writeFile } from 'jg-fs';
+ *
+ * const csv = 'id,name\n1,Ada\n';
  * await writeFile('out/report.csv', csv, { encoding: 'utf-8' });
  */
 export const writeFile = async (path, data, options) => {
@@ -34,6 +39,8 @@ export const writeFile = async (path, data, options) => {
  * @param data The text.
  * @returns A promise that resolves once the file is written.
  * @example
+ * import { writeTextFile } from 'jg-fs';
+ *
  * await writeTextFile('notes/today.md', '# Today');
  * @throws
  * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if the data isn't a string
@@ -49,12 +56,14 @@ export const writeTextFile = async (path, data) => {
  * @param space The indentation for stringified values.
  * @returns A promise that resolves once the file is written.
  * @example
- * await writeJSONFile('config.json', { port: 8080 });
+ * import { writeJsonFile } from 'jg-fs';
+ *
+ * await writeJsonFile('config.json', { port: 8080 });
  * @throws
  * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if the JSON content cannot be stringified or is empty
  */
-export const writeJSONFile = async (path, data, space = 2) => {
-    await writeFile(path, serializeJSONData(path, data, space), { encoding: 'utf-8' });
+export const writeJsonFile = async (path, data, space = 2) => {
+    await writeFile(path, serializeJsonData(path, data, space), { encoding: 'utf-8' });
 };
 /**
  * Writes a binary file. An empty Buffer writes an empty file.
@@ -62,6 +71,9 @@ export const writeJSONFile = async (path, data, space = 2) => {
  * @param data The content.
  * @returns A promise that resolves once the file is written.
  * @example
+ * import { writeBufferFile } from 'jg-fs';
+ *
+ * const imageBuffer = Buffer.from('iVBORw0KGgo=', 'base64');
  * await writeBufferFile('avatar.png', imageBuffer);
  * @throws
  * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if the data isn't a Buffer
@@ -81,27 +93,39 @@ export async function readFile(path, options = null) {
  * @param path The file's path.
  * @returns A promise that resolves to the text.
  * @example
+ * import { readTextFile } from 'jg-fs';
+ *
  * const markdown = await readTextFile('README.md');
  * @throws
  * - NOT_A_FILE: if the path doesn't exist or is not a file
  */
 export const readTextFile = (path) => readFile(path, { encoding: 'utf-8' });
 /**
- * Reads and parses a JSON file.
+ * Reads and parses a JSON file, and validates it with the schema when there is one. Without a
+ * schema, the value is `unknown`, or the type you pass.
  * @param path The file's path.
+ * @param options The schema, such as a Zod schema, whose errors propagate unchanged.
  * @returns A promise that resolves to the parsed value.
  * @example
- * const config = await readJSONFile<{ port: number }>('config.json');
+ * import { readJsonFile } from 'jg-fs';
+ *
+ * const config = await readJsonFile('config.json', { schema: Config }); // Config's type
+ * @example
+ * import { readJsonFile } from 'jg-fs';
+ *
+ * const value = await readJsonFile('data.json'); // unknown
  * @throws
  * - NOT_A_FILE: if the path doesn't exist or is not a file
  * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if the file's JSON content cannot be parsed
  */
-export const readJSONFile = async (path) => parseJSONContent(path, await readTextFile(path));
+export const readJsonFile = async (path, options = {}) => parseJsonContent(path, await readTextFile(path), options.schema);
 /**
  * Reads a binary file. An empty file reads as an empty Buffer.
  * @param path The file's path.
  * @returns A promise that resolves to the content.
  * @example
+ * import { readBufferFile } from 'jg-fs';
+ *
  * const image = await readBufferFile('avatar.png');
  * @throws
  * - NOT_A_FILE: if the path doesn't exist or is not a file
@@ -113,6 +137,8 @@ export const readBufferFile = (path) => readFile(path, null);
  * @param destPath Where to copy it.
  * @returns A promise that resolves once the copy exists.
  * @example
+ * import { copyFile } from 'jg-fs';
+ *
  * await copyFile('config.example.json', 'config.json');
  * @throws
  * - NOT_A_FILE: if the srcPath doesn't exist or is not a file
@@ -128,6 +154,8 @@ export const copyFile = async (srcPath, destPath) => {
  * @param path The file's path.
  * @returns A promise that resolves once the file is gone.
  * @example
+ * import { deleteFile } from 'jg-fs';
+ *
  * await deleteFile('cache.json');
  * @throws
  * - NOT_A_FILE: if the path doesn't exist or is not a file
@@ -144,6 +172,8 @@ export const deleteFile = async (path) => {
  * @param path Where to create the link.
  * @returns A promise that resolves once the link exists.
  * @example
+ * import { createFileSymLink } from 'jg-fs';
+ *
  * await createFileSymLink('config.production.json', 'config.json');
  * @throws
  * - NON_EXISTENT_FILE: if the target file does not exist
@@ -152,7 +182,9 @@ export const deleteFile = async (path) => {
 export const createFileSymLink = async (target, path) => {
     const element = await getPathElement(target);
     if (element === null) {
-        throw new Exception(`The target file '${target}' does not exist.`, ERRORS.NON_EXISTENT_FILE);
+        throw new Exception(`The target file '${target}' does not exist.`, {
+            code: ERRORS.NON_EXISTENT_FILE,
+        });
     }
     if (!element.isFile) {
         throw notAFile(target);
@@ -171,8 +203,11 @@ export const createFileSymLink = async (target, path) => {
  * @param mode The permission bits of the written file, such as `0o600`.
  * @returns A promise that resolves once the file is written and flushed.
  * @example
+ * import { writeFileAtomic } from 'jg-fs';
+ *
+ * const state = { step: 2 };
  * await writeFileAtomic('state.json', JSON.stringify(state)); // readers never see a partial file
- * await writeFileAtomic('secrets.env', contents, 0o600);
+ * await writeFileAtomic('secrets.env', 'TOKEN=abc\n', 0o600); // only the owner can read it
  */
 export const writeFileAtomic = async (path, data, mode) => {
     const directory = dirname(path);
@@ -214,7 +249,10 @@ export const writeFileAtomic = async (path, data, mode) => {
  * @param maxBytes The largest size accepted, in bytes.
  * @returns A promise that resolves to the content.
  * @example
- * const upload = await readBoundedFile(join(uploadsDirectory, name), 5 * 1024 * 1024); // at most 5 MB
+ * import { join } from 'node:path';
+ * import { readBoundedFile } from 'jg-fs';
+ *
+ * const upload = await readBoundedFile(join('uploads', 'avatar.png'), 5 * 1024 * 1024); // at most 5 MB
  * @throws
  * - NOT_A_FILE: if the path doesn't exist, its final component is a symbolic link, or it isn't a regular file
  * - FILE_TOO_LARGE: if the file holds more than maxBytes bytes