jg-fs 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 1.0.1
+
+### Changed
+
+- 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 of `jg-fs`, which replaces `fs-utils-async` 1.0.1 and, at `jg-fs/sync`, `fs-utils-sync` 1.2.0.
+
+### Added
+
+- The `jg-fs/sync` entry, with the same functions as the async root entry.
+- `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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesus Graterol
+
+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

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# jg-fs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Filesystem helpers for Node.js, async at the root and sync at `jg-fs/sync`: paths, directories, text, JSON, atomic and bounded files.
+
+## Install
+
+```bash
+npm install jg-fs
+```
+
+## Usage
+
+The root entry is async, and `jg-fs/sync` has the same functions, synchronous:
+
+```ts
+import { readJSONFile, writeFileAtomic, writeTextFile } from 'jg-fs';
+import { readTextFile } from 'jg-fs/sync';
+
+await writeTextFile('notes/today.md', '# Today'); // creates notes/ when it's missing
+const config = await readJSONFile<{ port: number }>('config.json');
+await writeFileAtomic('state.json', JSON.stringify(state)); // readers never see a partial file
+
+const readme = readTextFile('README.md');
+```
+
+List, filter, and sort a directory:
+
+```ts
+import { getDirectoryElements } from 'jg-fs';
+
+const { files, directories } = await getDirectoryElements('content', {
+  includeExts: ['.md'],
+  sortByKey: 'creation',
+  sortOrder: 'desc',
+});
+```
+
+Read files from untrusted paths with a size limit, without following a symbolic link:
+
+```ts
+import { isPathWithin, readBoundedFile } from 'jg-fs';
+
+if (isPathWithin(uploadsDirectory, path)) {
+  const upload = await readBoundedFile(path, 5 * 1024 * 1024);
+}
+```
+
+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/.
+
+## License
+
+[MIT](https://github.com/jesusgraterol/jg-packages/blob/main/packages/jg-fs/LICENSE)

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

@@ -0,0 +1,78 @@
+import { type IDirectoryElementsOptions, type IDirectoryPathElements } from '../../shared/index.js';
+/**
+ * Checks whether a path exists and is a directory.
+ * @param path The path.
+ * @returns A promise that resolves to whether the path is a directory.
+ * @example
+ * await isDirectory('dist'); // true
+ */
+export declare const isDirectory: (path: string) => Promise<boolean>;
+/**
+ * Deletes a directory and everything in it. A missing directory is not an error.
+ * @param path The directory's path.
+ * @returns A promise that resolves once the directory is gone.
+ * @example
+ * await deleteDirectory('dist');
+ */
+export declare const deleteDirectory: (path: string) => Promise<void>;
+/**
+ * Creates a directory, with any missing parents. An existing directory is kept, or replaced with
+ * an empty one when `deleteIfExists` is set.
+ * @param path The directory's path.
+ * @param deleteIfExists Whether to delete an existing directory and its contents first.
+ * @returns A promise that resolves once the directory exists.
+ * @example
+ * await createDirectory('dist/assets'); // creates missing parents too
+ * await createDirectory('dist', true); // replaces it with an empty directory
+ * @throws
+ * - DIRECTORY_ALREADY_EXISTS: if something other than a directory exists at the path
+ */
+export declare const createDirectory: (path: string, deleteIfExists?: boolean) => Promise<void>;
+/**
+ * Copies a directory and everything in it, replacing the destination completely.
+ * @param srcPath The directory to copy.
+ * @param destPath Where to copy it.
+ * @returns A promise that resolves once the copy is complete.
+ * @example
+ * await copyDirectory('templates', 'dist/templates');
+ * @throws
+ * - NOT_A_DIRECTORY: if the srcPath is not a directory
+ */
+export declare const copyDirectory: (srcPath: string, destPath: string) => Promise<void>;
+/**
+ * Creates a symbolic link to a directory.
+ * @param target The directory the link points to.
+ * @param path Where to create the link.
+ * @returns A promise that resolves once the link exists.
+ * @example
+ * await createDirectorySymLink('releases/1.4.0', 'current');
+ * @throws
+ * - NON_EXISTENT_DIRECTORY: if the target directory doesn't exist
+ * - NOT_A_DIRECTORY: if the target directory is not considered a directory by the OS
+ */
+export declare const createDirectorySymLink: (target: string, path: string) => Promise<void>;
+/**
+ * Lists a directory's contents as paths joined to the directory's path.
+ * @param path The directory's path.
+ * @param recursive Whether to include the contents of subdirectories.
+ * @returns A promise that resolves to the content paths.
+ * @example
+ * await readDirectory('dist'); // ['dist/index.js', 'dist/assets']
+ * await readDirectory('dist', true); // includes the contents of dist/assets
+ * @throws
+ * - NOT_A_DIRECTORY: if the path doesn't exist or is not a directory
+ */
+export declare const readDirectory: (path: string, recursive?: boolean) => Promise<string[]>;
+/**
+ * Lists a directory's elements grouped by kind: directories, files (filtered by extension), and
+ * symbolic links, each group sorted. Entries removed while the directory is read are left out, and
+ * at most 32 entries are read at once.
+ * @param path The directory's path.
+ * @param options The extensions to include and how to sort.
+ * @returns A promise that resolves to the grouped elements.
+ * @example
+ * 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
+ */
+export declare const getDirectoryElements: (path: string, options?: Partial<IDirectoryElementsOptions>) => Promise<IDirectoryPathElements>;

package/dist/async/directories/directories.js

@@ -0,0 +1,118 @@
+import { cp, mkdir, readdir, rm, symlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Exception } from 'jg-exception';
+import { buildDirectoryElementsOptions, DIRECTORY_ELEMENTS_CONCURRENCY, ERRORS, groupDirectoryElements, notADirectory, } from '../../shared/index.js';
+import { getPathElement } from '../general/index.js';
+import { mapWithConcurrency } from './utilities.js';
+/**
+ * Checks whether a path exists and is a directory.
+ * @param path The path.
+ * @returns A promise that resolves to whether the path is a directory.
+ * @example
+ * await isDirectory('dist'); // true
+ */
+export const isDirectory = async (path) => (await getPathElement(path))?.isDirectory ?? false;
+/**
+ * Deletes a directory and everything in it. A missing directory is not an error.
+ * @param path The directory's path.
+ * @returns A promise that resolves once the directory is gone.
+ * @example
+ * await deleteDirectory('dist');
+ */
+export const deleteDirectory = (path) => rm(path, { recursive: true, force: true });
+/**
+ * Creates a directory, with any missing parents. An existing directory is kept, or replaced with
+ * an empty one when `deleteIfExists` is set.
+ * @param path The directory's path.
+ * @param deleteIfExists Whether to delete an existing directory and its contents first.
+ * @returns A promise that resolves once the directory exists.
+ * @example
+ * await createDirectory('dist/assets'); // creates missing parents too
+ * await createDirectory('dist', true); // replaces it with an empty directory
+ * @throws
+ * - DIRECTORY_ALREADY_EXISTS: if something other than a directory exists at the path
+ */
+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);
+    }
+    if (element !== null && deleteIfExists) {
+        await deleteDirectory(path);
+    }
+    await mkdir(path, { recursive: true });
+};
+/**
+ * Copies a directory and everything in it, replacing the destination completely.
+ * @param srcPath The directory to copy.
+ * @param destPath Where to copy it.
+ * @returns A promise that resolves once the copy is complete.
+ * @example
+ * await copyDirectory('templates', 'dist/templates');
+ * @throws
+ * - NOT_A_DIRECTORY: if the srcPath is not a directory
+ */
+export const copyDirectory = async (srcPath, destPath) => {
+    if (!(await isDirectory(srcPath))) {
+        throw notADirectory(srcPath);
+    }
+    await deleteDirectory(destPath);
+    await cp(srcPath, destPath, { recursive: true });
+};
+/**
+ * Creates a symbolic link to a directory.
+ * @param target The directory the link points to.
+ * @param path Where to create the link.
+ * @returns A promise that resolves once the link exists.
+ * @example
+ * await createDirectorySymLink('releases/1.4.0', 'current');
+ * @throws
+ * - NON_EXISTENT_DIRECTORY: if the target directory doesn't exist
+ * - NOT_A_DIRECTORY: if the target directory is not considered a directory by the OS
+ */
+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);
+    }
+    if (!element.isDirectory) {
+        throw notADirectory(target);
+    }
+    await symlink(target, path, 'dir');
+};
+/**
+ * Lists a directory's contents as paths joined to the directory's path.
+ * @param path The directory's path.
+ * @param recursive Whether to include the contents of subdirectories.
+ * @returns A promise that resolves to the content paths.
+ * @example
+ * await readDirectory('dist'); // ['dist/index.js', 'dist/assets']
+ * await readDirectory('dist', true); // includes the contents of dist/assets
+ * @throws
+ * - NOT_A_DIRECTORY: if the path doesn't exist or is not a directory
+ */
+export const readDirectory = async (path, recursive = false) => {
+    if (!(await isDirectory(path))) {
+        throw notADirectory(path);
+    }
+    const contentPaths = await readdir(path, { encoding: 'utf-8', recursive });
+    return contentPaths.map((contentPath) => join(path, contentPath));
+};
+/**
+ * Lists a directory's elements grouped by kind: directories, files (filtered by extension), and
+ * symbolic links, each group sorted. Entries removed while the directory is read are left out, and
+ * at most 32 entries are read at once.
+ * @param path The directory's path.
+ * @param options The extensions to include and how to sort.
+ * @returns A promise that resolves to the grouped elements.
+ * @example
+ * 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
+ */
+export const getDirectoryElements = async (path, options) => {
+    const contentPaths = await readDirectory(path);
+    const elements = (await mapWithConcurrency(contentPaths, DIRECTORY_ELEMENTS_CONCURRENCY, getPathElement)).filter((element) => element !== null);
+    return groupDirectoryElements(elements, buildDirectoryElementsOptions(options));
+};
+//# sourceMappingURL=directories.js.map

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

@@ -0,0 +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"]}

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

@@ -0,0 +1 @@
+export { copyDirectory, createDirectory, createDirectorySymLink, deleteDirectory, getDirectoryElements, isDirectory, readDirectory, } from './directories.js';

package/dist/async/directories/index.js

@@ -0,0 +1,3 @@
+// directory actions
+export { copyDirectory, createDirectory, createDirectorySymLink, deleteDirectory, getDirectoryElements, isDirectory, readDirectory, } from './directories.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/async/directories/index.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB,OAAO,EACL,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,eAAe,EACf,oBAAoB,EACpB,WAAW,EACX,aAAa,GACd,MAAM,kBAAkB,CAAC","sourcesContent":["// directory actions\nexport {\n  copyDirectory,\n  createDirectory,\n  createDirectorySymLink,\n  deleteDirectory,\n  getDirectoryElements,\n  isDirectory,\n  readDirectory,\n} from './directories.js';\n"]}

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

@@ -0,0 +1,9 @@
+/**
+ * Maps items with an async function, running at most a fixed number of calls at once, and keeps
+ * the results in the items' order.
+ * @param items The items.
+ * @param concurrency The most calls running at once.
+ * @param mapper The async function.
+ * @returns A promise that resolves to the results.
+ */
+export declare const mapWithConcurrency: <TItem, TResult>(items: TItem[], concurrency: number, mapper: (item: TItem) => Promise<TResult>) => Promise<TResult[]>;

package/dist/async/directories/utilities.js

@@ -0,0 +1,22 @@
+/**
+ * Maps items with an async function, running at most a fixed number of calls at once, and keeps
+ * the results in the items' order.
+ * @param items The items.
+ * @param concurrency The most calls running at once.
+ * @param mapper The async function.
+ * @returns A promise that resolves to the results.
+ */
+export const mapWithConcurrency = async (items, concurrency, mapper) => {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const worker = async () => {
+        while (nextIndex < items.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            results[index] = await mapper(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+    return results;
+};
+//# sourceMappingURL=utilities.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../../../src/async/directories/utilities.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,EACrC,KAAc,EACd,WAAmB,EACnB,MAAyC,EACrB,EAAE;IACtB,MAAM,OAAO,GAAc,IAAI,KAAK,CAAU,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5D,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,MAAM,MAAM,GAAG,KAAK,IAAmB,EAAE;QACvC,OAAO,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAChC,MAAM,KAAK,GAAG,SAAS,CAAC;YACxB,SAAS,IAAI,CAAC,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,CAAU,CAAC,CAAC;QACvD,CAAC;IACH,CAAC,CAAC;IACF,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;IACvF,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC","sourcesContent":["/**\n * Maps items with an async function, running at most a fixed number of calls at once, and keeps\n * the results in the items' order.\n * @param items The items.\n * @param concurrency The most calls running at once.\n * @param mapper The async function.\n * @returns A promise that resolves to the results.\n */\nexport const mapWithConcurrency = async <TItem, TResult>(\n  items: TItem[],\n  concurrency: number,\n  mapper: (item: TItem) => Promise<TResult>,\n): Promise<TResult[]> => {\n  const results: TResult[] = new Array<TResult>(items.length);\n  let nextIndex = 0;\n  const worker = async (): Promise<void> => {\n    while (nextIndex < items.length) {\n      const index = nextIndex;\n      nextIndex += 1;\n      results[index] = await mapper(items[index] as TItem);\n    }\n  };\n  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));\n  return results;\n};\n"]}

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

@@ -0,0 +1,164 @@
+import { Buffer } from 'node:buffer';
+import type { WriteFileOptions } from 'node:fs';
+import { type IReadBufferFileOptions, type IReadFileOptions, 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
+ * await isFile('package.json'); // true
+ */
+export declare const isFile: (path: string) => Promise<boolean>;
+/**
+ * Writes a file, creating its directory first when it doesn't exist.
+ * @param path The file's path.
+ * @param data The content.
+ * @param options Node.js's writeFile options, such as the encoding or mode.
+ * @returns A promise that resolves once the file is written.
+ * @example
+ * await writeFile('out/report.csv', csv, { encoding: 'utf-8' });
+ */
+export declare const writeFile: (path: string, data: string | NodeJS.ArrayBufferView, options?: WriteFileOptions) => Promise<void>;
+/**
+ * Writes a UTF-8 text file. An empty string writes an empty file.
+ * @param path The file's path.
+ * @param data The text.
+ * @returns A promise that resolves once the file is written.
+ * @example
+ * await writeTextFile('notes/today.md', '# Today');
+ * @throws
+ * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if the data isn't a string
+ */
+export declare const writeTextFile: (path: string, data: string) => Promise<void>;
+/**
+ * Writes a JSON file. A string is written as given; anything else is stringified.
+ * @param path The file's path.
+ * @param data The value, or its JSON text.
+ * @param space The indentation for stringified values.
+ * @returns A promise that resolves once the file is written.
+ * @example
+ * 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>;
+/**
+ * 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
+ * await writeBufferFile('avatar.png', imageBuffer);
+ * @throws
+ * - FILE_CONTENT_IS_EMPTY_OR_INVALID: if the data isn't a Buffer
+ */
+export declare const writeBufferFile: (path: string, data: Buffer) => Promise<void>;
+/**
+ * Reads a file as a string when an encoding is given, or as a Buffer otherwise.
+ * @param path The file's path.
+ * @param options Node.js's readFile options, such as the encoding.
+ * @returns A promise that resolves to the content.
+ * @example
+ * await readFile('notes.md', 'utf-8'); // a string
+ * await readFile('avatar.png'); // a Buffer
+ * @throws
+ * - NOT_A_FILE: if the path doesn't exist or is not a file
+ */
+export declare function readFile(path: string, options: IReadStringFileOptions): Promise<string>;
+export declare function readFile(path: string, options?: IReadBufferFileOptions): Promise<Buffer>;
+export declare function readFile(path: string, options?: IReadFileOptions): Promise<string | Buffer>;
+/**
+ * Reads a UTF-8 text file. An empty file reads as an empty string.
+ * @param path The file's path.
+ * @returns A promise that resolves to the text.
+ * @example
+ * 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.
+ * @param path The file's path.
+ * @returns A promise that resolves to the parsed value.
+ * @example
+ * const config = await readJSONFile<{ port: number }>('config.json');
+ * @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>;
+/**
+ * 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
+ * const image = await readBufferFile('avatar.png');
+ * @throws
+ * - NOT_A_FILE: if the path doesn't exist or is not a file
+ */
+export declare const readBufferFile: (path: string) => Promise<Buffer>;
+/**
+ * Copies a file, replacing the destination when it exists.
+ * @param srcPath The file to copy.
+ * @param destPath Where to copy it.
+ * @returns A promise that resolves once the copy exists.
+ * @example
+ * await copyFile('config.example.json', 'config.json');
+ * @throws
+ * - NOT_A_FILE: if the srcPath doesn't exist or is not a file
+ */
+export declare const copyFile: (srcPath: string, destPath: string) => Promise<void>;
+/**
+ * Deletes a file.
+ * @param path The file's path.
+ * @returns A promise that resolves once the file is gone.
+ * @example
+ * await deleteFile('cache.json');
+ * @throws
+ * - NOT_A_FILE: if the path doesn't exist or is not a file
+ */
+export declare const deleteFile: (path: string) => Promise<void>;
+/**
+ * Creates a symbolic link to a file.
+ * @param target The file the link points to.
+ * @param path Where to create the link.
+ * @returns A promise that resolves once the link exists.
+ * @example
+ * await createFileSymLink('config.production.json', 'config.json');
+ * @throws
+ * - NON_EXISTENT_FILE: if the target file does not exist
+ * - NOT_A_FILE: if the target is not a file
+ */
+export declare const createFileSymLink: (target: string, path: string) => Promise<void>;
+/**
+ * Writes a file atomically: readers see either the previous content or the complete new content,
+ * never a partial write. The data goes to a temporary file in the same directory, which is flushed
+ * to disk and renamed over the path; on POSIX, the directory is flushed too. An explicit mode wins;
+ * without one, a replaced file keeps its permission bits and a new file gets the platform default.
+ * The temporary file is never more widely readable than the final mode. When writing fails before
+ * the rename, the temporary file is removed and the destination is untouched.
+ * @param path The file's path.
+ * @param data The content.
+ * @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
+ * await writeFileAtomic('state.json', JSON.stringify(state)); // readers never see a partial file
+ * await writeFileAtomic('secrets.env', contents, 0o600);
+ */
+export declare const writeFileAtomic: (path: string, data: string | NodeJS.ArrayBufferView, mode?: number) => Promise<void>;
+/**
+ * Reads a regular file of at most `maxBytes` bytes. It never follows a symbolic link in the
+ * path's last component, though links in parent directories are followed, so callers that need
+ * containment combine it with `isPathWithin`. It reads at most `maxBytes + 1` bytes, even when the
+ * file grows while it's read.
+ * @param path The file's path.
+ * @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
+ * @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
+ */
+export declare const readBoundedFile: (path: string, maxBytes: number) => Promise<Buffer>;