jg-fs 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -1,30 +1,40 @@
 # Changelog
 
-## 1.0.1
+## 1.1.1
 
-### Changed
+### Added
 
-- Published by CI from `jesusgraterol/jg-packages`, with npm provenance. The code is the same as 1.0.0.
+- `RECIPES.md`, patterns for apps that use the package: a config file that's never half-written, and reading uploads with a size limit. Each block is typechecked against the release.
 
-## 1.0.0
+## 1.1.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.
+A fresh start: breaking changes in a minor version, once, because nothing depended on 1.0.x.
 
 ### Added
 
-- The `jg-fs/sync` entry, with the same functions as the async root entry.
-- `ERRORS`, the codes of every error the package throws.
+- 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
 
-- 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`.
+- 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
 
-### Fixed
+### Changed
 
-- Typos in several error messages.
+- Published by CI from `jesusgraterol/jg-packages`, with npm provenance. The code is the same as 1.0.0.
+
+## 1.0.0
+
+The first release.
+
+### Added
+
+- 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.
+- 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,11 @@ 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/.
+
+Recipes for common jobs ship as `RECIPES.md`, with every block typechecked against the release, and are at https://jg-packages.jesusgraterol.dev/packages/jg-fs/recipes/.
 
 ## License
 

package/RECIPES.md

@@ -0,0 +1,125 @@
+# jg-fs recipes
+
+Patterns for Node.js apps that keep their files whole through crashes, and read files from users within a size limit.
+
+## A config file that's never half-written
+
+Use this for a file the app reads at startup and rewrites while it runs, such as settings changed from an admin page. A plain write that's cut short, by a crash or a full disk, leaves a truncated file that won't parse at the next start. `writeFileAtomic` writes a temporary file next to it, flushes it to disk, and renames it over the old one, so the file holds either the old config or the new one:
+
+```ts
+import { hasErrorCode } from 'jg-exception';
+import { ERRORS, readJsonFile, writeFileAtomic } from 'jg-fs';
+
+// the config's type, from your schema
+type IConfig = ReturnType<typeof Config.parse>;
+
+const CONFIG_PATH = 'data/config.json';
+
+// what the app runs with until someone saves a change
+const DEFAULT_CONFIG: IConfig = { port: 8080 };
+
+export const loadConfig = async (): Promise<IConfig> => {
+  try {
+    // Config is your schema, such as a Zod object, so a file edited by hand into a wrong shape
+    // fails here, at startup, instead of somewhere later
+    return await readJsonFile(CONFIG_PATH, { schema: Config });
+  } catch (error) {
+    // nothing was saved yet
+    if (hasErrorCode(error, ERRORS.NOT_A_FILE)) {
+      return DEFAULT_CONFIG;
+    }
+    throw error;
+  }
+};
+
+// the update in progress, which the next one waits for
+let pendingUpdate: Promise<unknown> = Promise.resolve();
+
+// reads, changes, and saves the config one update at a time, so two updates never start from
+// the same version and lose one of the changes
+export const updateConfig = (change: (config: IConfig) => IConfig): Promise<IConfig> => {
+  const update = pendingUpdate.then(async () => {
+    const config = change(await loadConfig());
+    await writeFileAtomic(CONFIG_PATH, `${JSON.stringify(config, undefined, 2)}\n`);
+    return config;
+  });
+
+  // a failed update rejects for its caller, and the next one still runs
+  pendingUpdate = update.catch(() => undefined);
+  return update;
+};
+
+await updateConfig((config) => ({ ...config, port: 3000 }));
+```
+
+`writeJsonFile` is a plain write, so a file that must survive a crash goes through `writeFileAtomic` with `JSON.stringify` instead. Any error other than a missing file propagates, such as `FILE_CONTENT_IS_EMPTY_OR_INVALID` for a file that isn't JSON, or the schema's own error, so the app never starts from a config it can't trust. The atomic write keeps each save whole, but doesn't order saves: the queue does that inside one process, and when several processes write the file, give it one owner. A crash during a save can leave a temporary `.<random>.tmp` file next to the config, which is safe to delete.
+
+`jg-fs/sync` has the same functions without promises, for code that can't await, such as an `exit` handler or a short CLI command. An explicit mode keeps a secret private from the first byte written:
+
+```ts
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { writeFileAtomic } from 'jg-fs/sync';
+
+// the token your CLI's login command received
+declare const token: string;
+
+// kept outside any project, so it's never committed with one
+const credentialsPath = join(homedir(), '.my-cli', 'credentials.json');
+
+// on POSIX, only the owner can read it, and the temporary file is never more widely readable
+writeFileAtomic(credentialsPath, JSON.stringify({ token }), 0o600);
+```
+
+Without a mode, a replaced file keeps its permission bits, so a config someone restricted with `chmod` stays restricted after the app saves it.
+
+## Reading uploads with a size limit
+
+Use this when a request names a file that someone uploaded earlier, such as an import or an attachment, and the app reads it into memory. The name comes from a client, and the file can be larger than you expect, so the read checks three things: the path stays inside the uploads directory, the file is a regular file and not a symbolic link, and its size is within a limit:
+
+```ts
+import { join, resolve } from 'node:path';
+import { Exception, hasErrorCode } from 'jg-exception';
+import { ERRORS, isPathWithin, readBoundedFile } from 'jg-fs';
+
+// where your upload handler saves files, a directory that only the app writes to
+const UPLOADS_DIRECTORY = resolve('uploads');
+
+// the largest upload the app loads into memory
+const MAX_UPLOAD_BYTES = 5 * 1024 * 1024;
+
+// reads an upload by the name a request gave, such as 'report.csv'. The messages name the upload
+// and not the server's path, and the cause keeps jg-fs's error for the logs
+export const readUpload = async (name: string): Promise<Buffer> => {
+  // a name such as '../.env' leads outside the directory, which counts as not found
+  const path = join(UPLOADS_DIRECTORY, name);
+  if (!isPathWithin(UPLOADS_DIRECTORY, path)) {
+    throw new Exception('The upload was not found.', {
+      code: 'UPLOAD_NOT_FOUND',
+      data: { name },
+    });
+  }
+  try {
+    return await readBoundedFile(path, MAX_UPLOAD_BYTES);
+  } catch (error) {
+    // a missing file, a directory, or a symbolic link someone planted
+    if (hasErrorCode(error, ERRORS.NOT_A_FILE)) {
+      throw new Exception('The upload was not found.', {
+        code: 'UPLOAD_NOT_FOUND',
+        data: { name },
+        cause: error,
+      });
+    }
+    if (hasErrorCode(error, ERRORS.FILE_TOO_LARGE)) {
+      throw new Exception('The upload is too large to read.', {
+        code: 'UPLOAD_TOO_LARGE',
+        data: { name, maxBytes: MAX_UPLOAD_BYTES },
+        cause: error,
+      });
+    }
+    throw error;
+  }
+};
+```
+
+`readBoundedFile` checks the size before it reads, and reads at most one byte past the limit, so a file that grows during the read can't make it load more. It refuses a symbolic link as the last part of the path, but follows links in the directories above it, which is why the uploads go in a directory that only the app writes to. A request handler can answer `UPLOAD_NOT_FOUND` with a 404, and `jg-fs/sync` has the same `readBoundedFile` for code that can't await.

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":"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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 * 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":"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;;;;;;;;GAQG;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;;;;;;;;GAQG;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;;;;;;;;;;;;;GAaG;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,CAAC,aAAa,IAAI,0CAA0C,EAAE;YAC/E,IAAI,EAAE,MAAM,CAAC,wBAAwB;SACtC,CAAC,CAAC;IACL,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;;;;;;;;;;;GAWG;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;;;;;;;;;;;;GAYG;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,CAAC,yBAAyB,MAAM,mBAAmB,EAAE;YACtE,IAAI,EAAE,MAAM,CAAC,sBAAsB;SACpC,CAAC,CAAC;IACL,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;;;;;;;;;;;;GAYG;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;;;;;;;;;;;;;GAaG;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 * 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