@metamask-previews/utils 11.12.1-preview-9962b7e

package/dist/errors.js

@@ -0,0 +1,121 @@
+import { ErrorWithCause } from 'pony-cause';
+import { isNullOrUndefined, isObject } from './misc.js';
+/**
+ * Type guard for determining whether the given value is an instance of Error.
+ * For errors generated via `fs.promises`, `error instanceof Error` won't work,
+ * so we have to come up with another way of testing.
+ *
+ * @param error - The object to check.
+ * @returns A boolean.
+ */
+function isError(error) {
+    return (error instanceof Error ||
+        (isObject(error) && error.constructor.name === 'Error'));
+}
+/**
+ * Type guard for determining whether the given value is an error object with a
+ * `code` property such as the type of error that Node throws for filesystem
+ * operations, etc.
+ *
+ * @param error - The object to check.
+ * @returns A boolean.
+ */
+export function isErrorWithCode(error) {
+    return typeof error === 'object' && error !== null && 'code' in error;
+}
+/**
+ * Type guard for determining whether the given value is an error object with a
+ * `message` property, such as an instance of Error.
+ *
+ * @param error - The object to check.
+ * @returns A boolean.
+ */
+export function isErrorWithMessage(error) {
+    return typeof error === 'object' && error !== null && 'message' in error;
+}
+/**
+ * Type guard for determining whether the given value is an error object with a
+ * `stack` property, such as an instance of Error.
+ *
+ * @param error - The object to check.
+ * @returns A boolean.
+ */
+export function isErrorWithStack(error) {
+    return typeof error === 'object' && error !== null && 'stack' in error;
+}
+/**
+ * Attempts to obtain the message from a possible error object, defaulting to an
+ * empty string if it is impossible to do so.
+ *
+ * @param error - The possible error to get the message from.
+ * @returns The message if `error` is an object with a `message` property;
+ * the string version of `error` if it is not `undefined` or `null`; otherwise
+ * an empty string.
+ */
+export function getErrorMessage(error) {
+    if (isErrorWithMessage(error) && typeof error.message === 'string') {
+        return error.message;
+    }
+    if (isNullOrUndefined(error)) {
+        return '';
+    }
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string -- Stringifying an arbitrary value is the documented fallback here, so `[object Object]` is an accepted result rather than a mistake.
+    return String(error);
+}
+/**
+ * Builds a new error object, linking it to the original error via the `cause`
+ * property if it is an Error.
+ *
+ * This function is useful to reframe error messages in general, but is
+ * _critical_ when interacting with any of Node's filesystem functions as
+ * provided via `fs.promises`, because these do not produce stack traces in the
+ * case of an I/O error (see <https://github.com/nodejs/node/issues/30944>).
+ *
+ * @param originalError - The error to be wrapped (something throwable).
+ * @param message - The desired message of the new error.
+ * @returns A new error object.
+ */
+export function wrapError(originalError, message) {
+    if (isError(originalError)) {
+        let error;
+        if (Error.length === 2) {
+            // for some reason `tsserver` is not complaining that the
+            // Error constructor doesn't support a second argument in the editor,
+            // but `tsc` does. Error causes are not supported by our current tsc target (ES2020, we need ES2022 to make this work)
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore
+            error = new Error(message, { cause: originalError });
+        }
+        else {
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore
+            error = new ErrorWithCause(message, { cause: originalError });
+        }
+        if (isErrorWithCode(originalError)) {
+            error.code = originalError.code;
+        }
+        return error;
+    }
+    if (message.length > 0) {
+        return new Error(`${String(originalError)}: ${message}`);
+    }
+    return new Error(String(originalError));
+}
+/**
+ * Ensures we have a proper Error object.
+ * If the input is already an Error, returns it unchanged.
+ * Otherwise, converts to an Error with an appropriate message and preserves
+ * the original value as the cause.
+ *
+ * @param error - The caught error (could be Error, string, or unknown).
+ * @returns A proper Error instance.
+ */
+export function ensureError(error) {
+    if (isError(error)) {
+        return error;
+    }
+    const newError = new Error('Unknown error');
+    newError.cause = error;
+    return newError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAExD;;;;;;;GAOG;AACH,SAAS,OAAO,CAAC,KAAc;IAC7B,OAAO,CACL,KAAK,YAAY,KAAK;QACtB,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,WAAW,CAAC,IAAI,KAAK,OAAO,CAAC,CACxD,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,CAAC;AACxE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAc;IAEd,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,SAAS,IAAI,KAAK,CAAC;AAC3E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,CAAC;AACzE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,kBAAkB,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACnE,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IAED,IAAI,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,sMAAsM;IACtM,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CACvB,aAAwB,EACxB,OAAe;IAEf,IAAI,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;QAC3B,IAAI,KAAgC,CAAC;QACrC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,yDAAyD;YACzD,qEAAqE;YACrE,sHAAsH;YACtH,6DAA6D;YAC7D,aAAa;YACb,KAAK,GAAG,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,CAAC;QACvD,CAAC;aAAM,CAAC;YACN,6DAA6D;YAC7D,aAAa;YACb,KAAK,GAAG,IAAI,cAAc,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,CAAC;QAChE,CAAC;QAED,IAAI,eAAe,CAAC,aAAa,CAAC,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC;QAClC,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,IAAI,KAAK,CAAC,GAAG,MAAM,CAAC,aAAa,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,QAAQ,GAAgC,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;IACzE,QAAQ,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["import { ErrorWithCause } from 'pony-cause';\n\nimport { isNullOrUndefined, isObject } from './misc.js';\n\n/**\n * Type guard for determining whether the given value is an instance of Error.\n * For errors generated via `fs.promises`, `error instanceof Error` won't work,\n * so we have to come up with another way of testing.\n *\n * @param error - The object to check.\n * @returns A boolean.\n */\nfunction isError(error: unknown): error is Error {\n  return (\n    error instanceof Error ||\n    (isObject(error) && error.constructor.name === 'Error')\n  );\n}\n\n/**\n * Type guard for determining whether the given value is an error object with a\n * `code` property such as the type of error that Node throws for filesystem\n * operations, etc.\n *\n * @param error - The object to check.\n * @returns A boolean.\n */\nexport function isErrorWithCode(error: unknown): error is { code: string } {\n  return typeof error === 'object' && error !== null && 'code' in error;\n}\n\n/**\n * Type guard for determining whether the given value is an error object with a\n * `message` property, such as an instance of Error.\n *\n * @param error - The object to check.\n * @returns A boolean.\n */\nexport function isErrorWithMessage(\n  error: unknown,\n): error is { message: string } {\n  return typeof error === 'object' && error !== null && 'message' in error;\n}\n\n/**\n * Type guard for determining whether the given value is an error object with a\n * `stack` property, such as an instance of Error.\n *\n * @param error - The object to check.\n * @returns A boolean.\n */\nexport function isErrorWithStack(error: unknown): error is { stack: string } {\n  return typeof error === 'object' && error !== null && 'stack' in error;\n}\n\n/**\n * Attempts to obtain the message from a possible error object, defaulting to an\n * empty string if it is impossible to do so.\n *\n * @param error - The possible error to get the message from.\n * @returns The message if `error` is an object with a `message` property;\n * the string version of `error` if it is not `undefined` or `null`; otherwise\n * an empty string.\n */\nexport function getErrorMessage(error: unknown): string {\n  if (isErrorWithMessage(error) && typeof error.message === 'string') {\n    return error.message;\n  }\n\n  if (isNullOrUndefined(error)) {\n    return '';\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-base-to-string -- Stringifying an arbitrary value is the documented fallback here, so `[object Object]` is an accepted result rather than a mistake.\n  return String(error);\n}\n\n/**\n * Builds a new error object, linking it to the original error via the `cause`\n * property if it is an Error.\n *\n * This function is useful to reframe error messages in general, but is\n * _critical_ when interacting with any of Node's filesystem functions as\n * provided via `fs.promises`, because these do not produce stack traces in the\n * case of an I/O error (see <https://github.com/nodejs/node/issues/30944>).\n *\n * @param originalError - The error to be wrapped (something throwable).\n * @param message - The desired message of the new error.\n * @returns A new error object.\n */\nexport function wrapError<Throwable>(\n  originalError: Throwable,\n  message: string,\n): Error & { code?: string } {\n  if (isError(originalError)) {\n    let error: Error & { code?: string };\n    if (Error.length === 2) {\n      // for some reason `tsserver` is not complaining that the\n      // Error constructor doesn't support a second argument in the editor,\n      // but `tsc` does. Error causes are not supported by our current tsc target (ES2020, we need ES2022 to make this work)\n      // eslint-disable-next-line @typescript-eslint/ban-ts-comment\n      // @ts-ignore\n      error = new Error(message, { cause: originalError });\n    } else {\n      // eslint-disable-next-line @typescript-eslint/ban-ts-comment\n      // @ts-ignore\n      error = new ErrorWithCause(message, { cause: originalError });\n    }\n\n    if (isErrorWithCode(originalError)) {\n      error.code = originalError.code;\n    }\n\n    return error;\n  }\n\n  if (message.length > 0) {\n    return new Error(`${String(originalError)}: ${message}`);\n  }\n\n  return new Error(String(originalError));\n}\n\n/**\n * Ensures we have a proper Error object.\n * If the input is already an Error, returns it unchanged.\n * Otherwise, converts to an Error with an appropriate message and preserves\n * the original value as the cause.\n *\n * @param error - The caught error (could be Error, string, or unknown).\n * @returns A proper Error instance.\n */\nexport function ensureError(error: unknown): Error {\n  if (isError(error)) {\n    return error;\n  }\n\n  const newError: Error & { cause?: unknown } = new Error('Unknown error');\n  newError.cause = error;\n  return newError;\n}\n"]}

package/dist/fs.d.ts

@@ -0,0 +1,133 @@
+import type { Json } from './json.js';
+/**
+ * Information about the file sandbox provided to tests that need temporary
+ * access to the filesystem.
+ */
+export type FileSandbox = {
+    directoryPath: string;
+    withinSandbox: (test: (args: {
+        directoryPath: string;
+    }) => Promise<void>) => Promise<void>;
+};
+/**
+ * Read the file at the given path, assuming its content is encoded as UTF-8.
+ *
+ * @param filePath - The path to the file.
+ * @returns The content of the file.
+ * @throws An error with a stack trace if reading fails in any way.
+ */
+export declare function readFile(filePath: string): Promise<string>;
+/**
+ * Write content to the file at the given path, creating the directory structure
+ * for the file automatically if necessary.
+ *
+ * @param filePath - The path to the file.
+ * @param content - The new content of the file.
+ * @throws An error with a stack trace if writing fails in any way.
+ */
+export declare function writeFile(filePath: string, content: string): Promise<void>;
+/**
+ * Read the assumed JSON file at the given path, attempts to parse it, and
+ * get the resulting object. Supports a custom parser (in case you want to
+ * use the [JSON5](https://www.npmjs.com/package/json5) package instead).
+ *
+ * @param filePath - The path segments pointing to the JSON file. Will be passed
+ * to path.join().
+ * @param options - Options to this function.
+ * @param options.parser - The parser object to use. Defaults to `JSON`.
+ * @param options.parser.parse - A function that parses JSON data.
+ * @returns The object corresponding to the parsed JSON file, typed against the
+ * struct.
+ * @throws An error with a stack trace if reading fails in any way, or if the
+ * parsed value is not a plain object.
+ */
+export declare function readJsonFile<Value extends Json>(filePath: string, { parser, }?: {
+    parser?: {
+        parse: (text: Parameters<typeof JSON.parse>[0]) => ReturnType<typeof JSON.parse>;
+    };
+}): Promise<Value>;
+/**
+ * Attempt to write the given JSON-like value to the file at the given path,
+ * creating the directory structure for the file automatically if necessary.
+ * Adds a newline to the end of the file. Supports a custom parser (in case you
+ * want to use the [JSON5](https://www.npmjs.com/package/json5) package
+ * instead).
+ *
+ * @param filePath - The path to write the JSON file to, including the file
+ * itself.
+ * @param jsonValue - The JSON-like value to write to the file. Make sure that
+ * JSON.stringify can handle it.
+ * @param options - The options to this function.
+ * @param options.prettify - Whether to format the JSON as it is turned into a
+ * string such that it is broken up into separate lines (using 2 spaces as
+ * indentation).
+ * @param options.stringifier - The stringifier to use. Defaults to `JSON`.
+ * @param options.stringifier.stringify - A function that stringifies JSON.
+ * @returns The object corresponding to the parsed JSON file, typed against the
+ * struct.
+ * @throws An error with a stack trace if writing fails in any way.
+ */
+export declare function writeJsonFile(filePath: string, jsonValue: Json, { stringifier, prettify, }?: {
+    stringifier?: {
+        stringify: typeof JSON.stringify;
+    };
+    prettify?: boolean;
+}): Promise<void>;
+/**
+ * Test the given path to determine whether it represents a file.
+ *
+ * @param filePath - The path to a (supposed) file on the filesystem.
+ * @returns A promise for true if the file exists or false otherwise.
+ * @throws An error with a stack trace if reading fails in any way.
+ */
+export declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * Test the given path to determine whether it represents a directory.
+ *
+ * @param directoryPath - The path to a (supposed) directory on the filesystem.
+ * @returns A promise for true if the file exists or false otherwise.
+ * @throws An error with a stack trace if reading fails in any way.
+ */
+export declare function directoryExists(directoryPath: string): Promise<boolean>;
+/**
+ * Create the given directory along with any directories leading up to the
+ * directory, or do nothing if the directory already exists.
+ *
+ * @param directoryPath - The path to the desired directory.
+ * @throws An error with a stack trace if reading fails in any way.
+ */
+export declare function ensureDirectoryStructureExists(directoryPath: string): Promise<void>;
+/**
+ * Remove the given file or directory if it exists, or do nothing if it does
+ * not.
+ *
+ * @param entryPath - The path to the file or directory.
+ * @throws An error with a stack trace if removal fails in any way.
+ */
+export declare function forceRemove(entryPath: string): Promise<void>;
+/**
+ * Construct a sandbox object which can be used in tests that need temporary
+ * access to the filesystem.
+ *
+ * @param projectName - The name of the project.
+ * @returns The sandbox object. This contains a `withinSandbox` function which
+ * can be used in tests (see example).
+ * @example
+ * ```typescript
+ * const { withinSandbox } = createSandbox('utils');
+ *
+ * // ... later ...
+ *
+ * it('does something with the filesystem', async () => {
+ *   await withinSandbox(async ({ directoryPath }) => {
+ *     await fs.promises.writeFile(
+ *       path.join(directoryPath, 'some-file'),
+ *       'some content',
+ *       'utf8'
+ *     );
+ *   })
+ * });
+ * ```
+ */
+export declare function createSandbox(projectName: string): FileSandbox;
+//# sourceMappingURL=fs.d.ts.map

package/dist/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,CACb,IAAI,EAAE,CAAC,IAAI,EAAE;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,KACrD,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAMhE;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAAC,KAAK,SAAS,IAAI,EACnD,QAAQ,EAAE,MAAM,EAChB,EACE,MAAa,GACd,GAAE;IACD,MAAM,CAAC,EAAE;QACP,KAAK,EAAE,CACL,IAAI,EAAE,UAAU,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KACnC,UAAU,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;KACpC,CAAC;CACE,GACL,OAAO,CAAC,KAAK,CAAC,CAOhB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,IAAI,EACf,EACE,WAAkB,EAClB,QAAgB,GACjB,GAAE;IACD,WAAW,CAAC,EAAE;QACZ,SAAS,EAAE,OAAO,IAAI,CAAC,SAAS,CAAC;KAClC,CAAC;IACF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACf,GACL,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAWnE;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAc7E;AAED;;;;;;GAMG;AACH,wBAAsB,8BAA8B,CAClD,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASlE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAqB9D"}

package/dist/fs.js

@@ -0,0 +1,210 @@
+// This file is intended to be used only in a Node.js context.
+/* eslint-disable import-x/no-nodejs-modules */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import * as uuid from 'uuid';
+import { isErrorWithCode, wrapError } from './errors.js';
+/**
+ * Read the file at the given path, assuming its content is encoded as UTF-8.
+ *
+ * @param filePath - The path to the file.
+ * @returns The content of the file.
+ * @throws An error with a stack trace if reading fails in any way.
+ */
+export async function readFile(filePath) {
+    try {
+        return await fs.promises.readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        throw wrapError(error, `Could not read file '${filePath}'`);
+    }
+}
+/**
+ * Write content to the file at the given path, creating the directory structure
+ * for the file automatically if necessary.
+ *
+ * @param filePath - The path to the file.
+ * @param content - The new content of the file.
+ * @throws An error with a stack trace if writing fails in any way.
+ */
+export async function writeFile(filePath, content) {
+    try {
+        await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.promises.writeFile(filePath, content);
+    }
+    catch (error) {
+        throw wrapError(error, `Could not write file '${filePath}'`);
+    }
+}
+/**
+ * Read the assumed JSON file at the given path, attempts to parse it, and
+ * get the resulting object. Supports a custom parser (in case you want to
+ * use the [JSON5](https://www.npmjs.com/package/json5) package instead).
+ *
+ * @param filePath - The path segments pointing to the JSON file. Will be passed
+ * to path.join().
+ * @param options - Options to this function.
+ * @param options.parser - The parser object to use. Defaults to `JSON`.
+ * @param options.parser.parse - A function that parses JSON data.
+ * @returns The object corresponding to the parsed JSON file, typed against the
+ * struct.
+ * @throws An error with a stack trace if reading fails in any way, or if the
+ * parsed value is not a plain object.
+ */
+export async function readJsonFile(filePath, { parser = JSON, } = {}) {
+    try {
+        const content = await fs.promises.readFile(filePath, 'utf8');
+        return parser.parse(content);
+    }
+    catch (error) {
+        throw wrapError(error, `Could not read JSON file '${filePath}'`);
+    }
+}
+/**
+ * Attempt to write the given JSON-like value to the file at the given path,
+ * creating the directory structure for the file automatically if necessary.
+ * Adds a newline to the end of the file. Supports a custom parser (in case you
+ * want to use the [JSON5](https://www.npmjs.com/package/json5) package
+ * instead).
+ *
+ * @param filePath - The path to write the JSON file to, including the file
+ * itself.
+ * @param jsonValue - The JSON-like value to write to the file. Make sure that
+ * JSON.stringify can handle it.
+ * @param options - The options to this function.
+ * @param options.prettify - Whether to format the JSON as it is turned into a
+ * string such that it is broken up into separate lines (using 2 spaces as
+ * indentation).
+ * @param options.stringifier - The stringifier to use. Defaults to `JSON`.
+ * @param options.stringifier.stringify - A function that stringifies JSON.
+ * @returns The object corresponding to the parsed JSON file, typed against the
+ * struct.
+ * @throws An error with a stack trace if writing fails in any way.
+ */
+export async function writeJsonFile(filePath, jsonValue, { stringifier = JSON, prettify = false, } = {}) {
+    try {
+        await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+        const json = prettify
+            ? stringifier.stringify(jsonValue, null, '  ')
+            : stringifier.stringify(jsonValue);
+        await fs.promises.writeFile(filePath, json);
+    }
+    catch (error) {
+        throw wrapError(error, `Could not write JSON file '${filePath}'`);
+    }
+}
+/**
+ * Test the given path to determine whether it represents a file.
+ *
+ * @param filePath - The path to a (supposed) file on the filesystem.
+ * @returns A promise for true if the file exists or false otherwise.
+ * @throws An error with a stack trace if reading fails in any way.
+ */
+export async function fileExists(filePath) {
+    try {
+        const stats = await fs.promises.stat(filePath);
+        return stats.isFile();
+    }
+    catch (error) {
+        if (isErrorWithCode(error) && error.code === 'ENOENT') {
+            return false;
+        }
+        throw wrapError(error, `Could not determine if file exists '${filePath}'`);
+    }
+}
+/**
+ * Test the given path to determine whether it represents a directory.
+ *
+ * @param directoryPath - The path to a (supposed) directory on the filesystem.
+ * @returns A promise for true if the file exists or false otherwise.
+ * @throws An error with a stack trace if reading fails in any way.
+ */
+export async function directoryExists(directoryPath) {
+    try {
+        const stats = await fs.promises.stat(directoryPath);
+        return stats.isDirectory();
+    }
+    catch (error) {
+        if (isErrorWithCode(error) && error.code === 'ENOENT') {
+            return false;
+        }
+        throw wrapError(error, `Could not determine if directory exists '${directoryPath}'`);
+    }
+}
+/**
+ * Create the given directory along with any directories leading up to the
+ * directory, or do nothing if the directory already exists.
+ *
+ * @param directoryPath - The path to the desired directory.
+ * @throws An error with a stack trace if reading fails in any way.
+ */
+export async function ensureDirectoryStructureExists(directoryPath) {
+    try {
+        await fs.promises.mkdir(directoryPath, { recursive: true });
+    }
+    catch (error) {
+        throw wrapError(error, `Could not create directory structure '${directoryPath}'`);
+    }
+}
+/**
+ * Remove the given file or directory if it exists, or do nothing if it does
+ * not.
+ *
+ * @param entryPath - The path to the file or directory.
+ * @throws An error with a stack trace if removal fails in any way.
+ */
+export async function forceRemove(entryPath) {
+    try {
+        return await fs.promises.rm(entryPath, {
+            recursive: true,
+            force: true,
+        });
+    }
+    catch (error) {
+        throw wrapError(error, `Could not remove file or directory '${entryPath}'`);
+    }
+}
+/**
+ * Construct a sandbox object which can be used in tests that need temporary
+ * access to the filesystem.
+ *
+ * @param projectName - The name of the project.
+ * @returns The sandbox object. This contains a `withinSandbox` function which
+ * can be used in tests (see example).
+ * @example
+ * ```typescript
+ * const { withinSandbox } = createSandbox('utils');
+ *
+ * // ... later ...
+ *
+ * it('does something with the filesystem', async () => {
+ *   await withinSandbox(async ({ directoryPath }) => {
+ *     await fs.promises.writeFile(
+ *       path.join(directoryPath, 'some-file'),
+ *       'some content',
+ *       'utf8'
+ *     );
+ *   })
+ * });
+ * ```
+ */
+export function createSandbox(projectName) {
+    const directoryPath = path.join(os.tmpdir(), projectName, uuid.v4());
+    return {
+        directoryPath,
+        async withinSandbox(test) {
+            if (await directoryExists(directoryPath)) {
+                throw new Error(`${directoryPath} already exists. Cannot continue.`);
+            }
+            await ensureDirectoryStructureExists(directoryPath);
+            try {
+                await test({ directoryPath });
+            }
+            finally {
+                await forceRemove(directoryPath);
+            }
+        },
+    };
+}
+//# sourceMappingURL=fs.js.map

package/dist/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"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","sourcesContent":["// This file is intended to be used only in a Node.js context.\n/* eslint-disable import-x/no-nodejs-modules */\n\nimport fs from 'fs';\nimport os from 'os';\nimport path from 'path';\nimport * as uuid from 'uuid';\n\nimport { isErrorWithCode, wrapError } from './errors.js';\nimport type { Json } from './json.js';\n\n/**\n * Information about the file sandbox provided to tests that need temporary\n * access to the filesystem.\n */\nexport type FileSandbox = {\n  directoryPath: string;\n  withinSandbox: (\n    test: (args: { directoryPath: string }) => Promise<void>,\n  ) => Promise<void>;\n};\n\n/**\n * Read the file at the given path, assuming its content is encoded as UTF-8.\n *\n * @param filePath - The path to the file.\n * @returns The content of the file.\n * @throws An error with a stack trace if reading fails in any way.\n */\nexport async function readFile(filePath: string): Promise<string> {\n  try {\n    return await fs.promises.readFile(filePath, 'utf8');\n  } catch (error) {\n    throw wrapError(error, `Could not read file '${filePath}'`);\n  }\n}\n\n/**\n * Write content to the file at the given path, creating the directory structure\n * for the file automatically if necessary.\n *\n * @param filePath - The path to the file.\n * @param content - The new content of the file.\n * @throws An error with a stack trace if writing fails in any way.\n */\nexport async function writeFile(\n  filePath: string,\n  content: string,\n): Promise<void> {\n  try {\n    await fs.promises.mkdir(path.dirname(filePath), { recursive: true });\n    await fs.promises.writeFile(filePath, content);\n  } catch (error) {\n    throw wrapError(error, `Could not write file '${filePath}'`);\n  }\n}\n\n/**\n * Read the assumed JSON file at the given path, attempts to parse it, and\n * get the resulting object. Supports a custom parser (in case you want to\n * use the [JSON5](https://www.npmjs.com/package/json5) package instead).\n *\n * @param filePath - The path segments pointing to the JSON file. Will be passed\n * to path.join().\n * @param options - Options to this function.\n * @param options.parser - The parser object to use. Defaults to `JSON`.\n * @param options.parser.parse - A function that parses JSON data.\n * @returns The object corresponding to the parsed JSON file, typed against the\n * struct.\n * @throws An error with a stack trace if reading fails in any way, or if the\n * parsed value is not a plain object.\n */\nexport async function readJsonFile<Value extends Json>(\n  filePath: string,\n  {\n    parser = JSON,\n  }: {\n    parser?: {\n      parse: (\n        text: Parameters<typeof JSON.parse>[0],\n      ) => ReturnType<typeof JSON.parse>;\n    };\n  } = {},\n): Promise<Value> {\n  try {\n    const content = await fs.promises.readFile(filePath, 'utf8');\n    return parser.parse(content);\n  } catch (error) {\n    throw wrapError(error, `Could not read JSON file '${filePath}'`);\n  }\n}\n\n/**\n * Attempt to write the given JSON-like value to the file at the given path,\n * creating the directory structure for the file automatically if necessary.\n * Adds a newline to the end of the file. Supports a custom parser (in case you\n * want to use the [JSON5](https://www.npmjs.com/package/json5) package\n * instead).\n *\n * @param filePath - The path to write the JSON file to, including the file\n * itself.\n * @param jsonValue - The JSON-like value to write to the file. Make sure that\n * JSON.stringify can handle it.\n * @param options - The options to this function.\n * @param options.prettify - Whether to format the JSON as it is turned into a\n * string such that it is broken up into separate lines (using 2 spaces as\n * indentation).\n * @param options.stringifier - The stringifier to use. Defaults to `JSON`.\n * @param options.stringifier.stringify - A function that stringifies JSON.\n * @returns The object corresponding to the parsed JSON file, typed against the\n * struct.\n * @throws An error with a stack trace if writing fails in any way.\n */\nexport async function writeJsonFile(\n  filePath: string,\n  jsonValue: Json,\n  {\n    stringifier = JSON,\n    prettify = false,\n  }: {\n    stringifier?: {\n      stringify: typeof JSON.stringify;\n    };\n    prettify?: boolean;\n  } = {},\n): Promise<void> {\n  try {\n    await fs.promises.mkdir(path.dirname(filePath), { recursive: true });\n    const json = prettify\n      ? stringifier.stringify(jsonValue, null, '  ')\n      : stringifier.stringify(jsonValue);\n    await fs.promises.writeFile(filePath, json);\n  } catch (error) {\n    throw wrapError(error, `Could not write JSON file '${filePath}'`);\n  }\n}\n\n/**\n * Test the given path to determine whether it represents a file.\n *\n * @param filePath - The path to a (supposed) file on the filesystem.\n * @returns A promise for true if the file exists or false otherwise.\n * @throws An error with a stack trace if reading fails in any way.\n */\nexport async function fileExists(filePath: string): Promise<boolean> {\n  try {\n    const stats = await fs.promises.stat(filePath);\n    return stats.isFile();\n  } catch (error) {\n    if (isErrorWithCode(error) && error.code === 'ENOENT') {\n      return false;\n    }\n\n    throw wrapError(error, `Could not determine if file exists '${filePath}'`);\n  }\n}\n\n/**\n * Test the given path to determine whether it represents a directory.\n *\n * @param directoryPath - The path to a (supposed) directory on the filesystem.\n * @returns A promise for true if the file exists or false otherwise.\n * @throws An error with a stack trace if reading fails in any way.\n */\nexport async function directoryExists(directoryPath: string): Promise<boolean> {\n  try {\n    const stats = await fs.promises.stat(directoryPath);\n    return stats.isDirectory();\n  } catch (error) {\n    if (isErrorWithCode(error) && error.code === 'ENOENT') {\n      return false;\n    }\n\n    throw wrapError(\n      error,\n      `Could not determine if directory exists '${directoryPath}'`,\n    );\n  }\n}\n\n/**\n * Create the given directory along with any directories leading up to the\n * directory, or do nothing if the directory already exists.\n *\n * @param directoryPath - The path to the desired directory.\n * @throws An error with a stack trace if reading fails in any way.\n */\nexport async function ensureDirectoryStructureExists(\n  directoryPath: string,\n): Promise<void> {\n  try {\n    await fs.promises.mkdir(directoryPath, { recursive: true });\n  } catch (error) {\n    throw wrapError(\n      error,\n      `Could not create directory structure '${directoryPath}'`,\n    );\n  }\n}\n\n/**\n * Remove the given file or directory if it exists, or do nothing if it does\n * not.\n *\n * @param entryPath - The path to the file or directory.\n * @throws An error with a stack trace if removal fails in any way.\n */\nexport async function forceRemove(entryPath: string): Promise<void> {\n  try {\n    return await fs.promises.rm(entryPath, {\n      recursive: true,\n      force: true,\n    });\n  } catch (error) {\n    throw wrapError(error, `Could not remove file or directory '${entryPath}'`);\n  }\n}\n\n/**\n * Construct a sandbox object which can be used in tests that need temporary\n * access to the filesystem.\n *\n * @param projectName - The name of the project.\n * @returns The sandbox object. This contains a `withinSandbox` function which\n * can be used in tests (see example).\n * @example\n * ```typescript\n * const { withinSandbox } = createSandbox('utils');\n *\n * // ... later ...\n *\n * it('does something with the filesystem', async () => {\n *   await withinSandbox(async ({ directoryPath }) => {\n *     await fs.promises.writeFile(\n *       path.join(directoryPath, 'some-file'),\n *       'some content',\n *       'utf8'\n *     );\n *   })\n * });\n * ```\n */\nexport function createSandbox(projectName: string): FileSandbox {\n  const directoryPath = path.join(os.tmpdir(), projectName, uuid.v4());\n\n  return {\n    directoryPath,\n    async withinSandbox(\n      test: (args: { directoryPath: string }) => Promise<void>,\n    ) {\n      if (await directoryExists(directoryPath)) {\n        throw new Error(`${directoryPath} already exists. Cannot continue.`);\n      }\n\n      await ensureDirectoryStructureExists(directoryPath);\n\n      try {\n        await test({ directoryPath });\n      } finally {\n        await forceRemove(directoryPath);\n      }\n    },\n  };\n}\n"]}

package/dist/hashing.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Compute a SHA-256 digest for a given byte array.
+ *
+ * Uses the native crypto implementation and falls back to noble.
+ *
+ * @param bytes - A byte array.
+ * @returns The SHA-256 hash as a byte array.
+ */
+export declare function sha256(bytes: Uint8Array): Promise<Uint8Array>;
+/**
+ * Compute a SHA-512 digest for a given byte array.
+ *
+ * Uses the native crypto implementation and falls back to noble.
+ *
+ * @param bytes - A byte array.
+ * @returns The SHA-512 hash as a byte array.
+ */
+export declare function sha512(bytes: Uint8Array): Promise<Uint8Array>;
+/**
+ * Compute a SHA-384 digest for a given byte array.
+ *
+ * Uses the native crypto implementation and falls back to noble.
+ *
+ * @param bytes - A byte array.
+ * @returns The SHA-384 hash as a byte array.
+ */
+export declare function sha384(bytes: Uint8Array): Promise<Uint8Array>;
+//# sourceMappingURL=hashing.d.ts.map

package/dist/hashing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashing.d.ts","sourceRoot":"","sources":["../src/hashing.ts"],"names":[],"mappings":"AAMA;;;;;;;GAOG;AAMH,wBAAsB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAYnE;AAED;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAYnE;AAED;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAYnE"}

package/dist/hashing.js

@@ -0,0 +1,59 @@
+import { sha256 as nobleSha256 } from '@noble/hashes/sha256';
+import { sha512 as nobleSha512, sha384 as nobleSha384, } from '@noble/hashes/sha512';
+/**
+ * Compute a SHA-256 digest for a given byte array.
+ *
+ * Uses the native crypto implementation and falls back to noble.
+ *
+ * @param bytes - A byte array.
+ * @returns The SHA-256 hash as a byte array.
+ */
+// `crypto.subtle.digest` takes a `BufferSource`, which TypeScript 7 will not
+// accept a plain `Uint8Array` for: it is now generic over the buffer, so it
+// could be backed by a `SharedArrayBuffer`. Runtimes accept those, and
+// narrowing the exported signatures below would break callers, so the
+// assertion is kept at the call sites.
+export async function sha256(bytes) {
+    // Use crypto.subtle.digest whenever possible as it is faster.
+    if ('crypto' in globalThis &&
+        typeof globalThis.crypto === 'object' &&
+        globalThis.crypto.subtle?.digest) {
+        return new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', bytes));
+    }
+    return nobleSha256(bytes);
+}
+/**
+ * Compute a SHA-512 digest for a given byte array.
+ *
+ * Uses the native crypto implementation and falls back to noble.
+ *
+ * @param bytes - A byte array.
+ * @returns The SHA-512 hash as a byte array.
+ */
+export async function sha512(bytes) {
+    // Use crypto.subtle.digest whenever possible as it is faster.
+    if ('crypto' in globalThis &&
+        typeof globalThis.crypto === 'object' &&
+        globalThis.crypto.subtle?.digest) {
+        return new Uint8Array(await globalThis.crypto.subtle.digest('SHA-512', bytes));
+    }
+    return nobleSha512(bytes);
+}
+/**
+ * Compute a SHA-384 digest for a given byte array.
+ *
+ * Uses the native crypto implementation and falls back to noble.
+ *
+ * @param bytes - A byte array.
+ * @returns The SHA-384 hash as a byte array.
+ */
+export async function sha384(bytes) {
+    // Use crypto.subtle.digest whenever possible as it is faster.
+    if ('crypto' in globalThis &&
+        typeof globalThis.crypto === 'object' &&
+        globalThis.crypto.subtle?.digest) {
+        return new Uint8Array(await globalThis.crypto.subtle.digest('SHA-384', bytes));
+    }
+    return nobleSha384(bytes);
+}
+//# sourceMappingURL=hashing.js.map

package/dist/hashing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashing.js","sourceRoot":"","sources":["../src/hashing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EACL,MAAM,IAAI,WAAW,EACrB,MAAM,IAAI,WAAW,GACtB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;GAOG;AACH,6EAA6E;AAC7E,4EAA4E;AAC5E,uEAAuE;AACvE,sEAAsE;AACtE,uCAAuC;AACvC,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,KAAiB;IAC5C,8DAA8D;IAC9D,IACE,QAAQ,IAAI,UAAU;QACtB,OAAO,UAAU,CAAC,MAAM,KAAK,QAAQ;QACrC,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAChC,CAAC;QACD,OAAO,IAAI,UAAU,CACnB,MAAM,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,KAAqB,CAAC,CACxE,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,KAAiB;IAC5C,8DAA8D;IAC9D,IACE,QAAQ,IAAI,UAAU;QACtB,OAAO,UAAU,CAAC,MAAM,KAAK,QAAQ;QACrC,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAChC,CAAC;QACD,OAAO,IAAI,UAAU,CACnB,MAAM,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,KAAqB,CAAC,CACxE,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,KAAiB;IAC5C,8DAA8D;IAC9D,IACE,QAAQ,IAAI,UAAU;QACtB,OAAO,UAAU,CAAC,MAAM,KAAK,QAAQ;QACrC,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAChC,CAAC;QACD,OAAO,IAAI,UAAU,CACnB,MAAM,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,KAAqB,CAAC,CACxE,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC","sourcesContent":["import { sha256 as nobleSha256 } from '@noble/hashes/sha256';\nimport {\n  sha512 as nobleSha512,\n  sha384 as nobleSha384,\n} from '@noble/hashes/sha512';\n\n/**\n * Compute a SHA-256 digest for a given byte array.\n *\n * Uses the native crypto implementation and falls back to noble.\n *\n * @param bytes - A byte array.\n * @returns The SHA-256 hash as a byte array.\n */\n// `crypto.subtle.digest` takes a `BufferSource`, which TypeScript 7 will not\n// accept a plain `Uint8Array` for: it is now generic over the buffer, so it\n// could be backed by a `SharedArrayBuffer`. Runtimes accept those, and\n// narrowing the exported signatures below would break callers, so the\n// assertion is kept at the call sites.\nexport async function sha256(bytes: Uint8Array): Promise<Uint8Array> {\n  // Use crypto.subtle.digest whenever possible as it is faster.\n  if (\n    'crypto' in globalThis &&\n    typeof globalThis.crypto === 'object' &&\n    globalThis.crypto.subtle?.digest\n  ) {\n    return new Uint8Array(\n      await globalThis.crypto.subtle.digest('SHA-256', bytes as BufferSource),\n    );\n  }\n  return nobleSha256(bytes);\n}\n\n/**\n * Compute a SHA-512 digest for a given byte array.\n *\n * Uses the native crypto implementation and falls back to noble.\n *\n * @param bytes - A byte array.\n * @returns The SHA-512 hash as a byte array.\n */\nexport async function sha512(bytes: Uint8Array): Promise<Uint8Array> {\n  // Use crypto.subtle.digest whenever possible as it is faster.\n  if (\n    'crypto' in globalThis &&\n    typeof globalThis.crypto === 'object' &&\n    globalThis.crypto.subtle?.digest\n  ) {\n    return new Uint8Array(\n      await globalThis.crypto.subtle.digest('SHA-512', bytes as BufferSource),\n    );\n  }\n  return nobleSha512(bytes);\n}\n\n/**\n * Compute a SHA-384 digest for a given byte array.\n *\n * Uses the native crypto implementation and falls back to noble.\n *\n * @param bytes - A byte array.\n * @returns The SHA-384 hash as a byte array.\n */\nexport async function sha384(bytes: Uint8Array): Promise<Uint8Array> {\n  // Use crypto.subtle.digest whenever possible as it is faster.\n  if (\n    'crypto' in globalThis &&\n    typeof globalThis.crypto === 'object' &&\n    globalThis.crypto.subtle?.digest\n  ) {\n    return new Uint8Array(\n      await globalThis.crypto.subtle.digest('SHA-384', bytes as BufferSource),\n    );\n  }\n  return nobleSha384(bytes);\n}\n"]}