@oliversalzburg/js-utils 0.7.0 → 0.8.0

package/lib/errors/InvalidOperationError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InvalidOperationError.js","sourceRoot":"","sources":["../../source/errors/InvalidOperationError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IACvD;;;;OAIG;IACH,YAAY,OAAe,EAAE,MAAM,GAAG,GAAG;QACxC,KAAK,CAAC,0BAA0B,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAEnD,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QAEpC,IAAI,OAAO,KAAK,CAAC,iBAAiB,KAAK,WAAW,EAAE,CAAC;YACpD,qEAAqE;YACrE,yEAAyE;YACzE,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC;QACtD,CAAC;IACF,CAAC;CACD"}

package/lib/errors/NotImplementedError.d.ts

@@ -0,0 +1,12 @@
+import { AbstractError } from "./AbstractError.js";
+/**
+ * Used when a called method actually hasn't been implemented yet (whoops).
+ */
+export declare class NotImplementedError extends AbstractError {
+    /**
+     * Constructs a new {@linkcode NotImplementedError}.
+     * @param message - The main error message.
+     * @param status - The HTTP status code to return.
+     */
+    constructor(message?: string, status?: number);
+}

package/lib/errors/NotImplementedError.js

@@ -0,0 +1,21 @@
+import { AbstractError } from "./AbstractError.js";
+/**
+ * Used when a called method actually hasn't been implemented yet (whoops).
+ */
+export class NotImplementedError extends AbstractError {
+    /**
+     * Constructs a new {@linkcode NotImplementedError}.
+     * @param message - The main error message.
+     * @param status - The HTTP status code to return.
+     */
+    constructor(message = "Not implemented.", status = 501) {
+        super("ERR_OS_NOT_IMPLEMENTED", message, status);
+        this.name = "NotImplementedError";
+        if (typeof Error.captureStackTrace !== "undefined") {
+            // Capture a new stacktrace, otherwise it will include our base-class
+            // constructor instead of the code location we're actually interested in.
+            Error.captureStackTrace(this, NotImplementedError);
+        }
+    }
+}
+//# sourceMappingURL=NotImplementedError.js.map

package/lib/errors/NotImplementedError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotImplementedError.js","sourceRoot":"","sources":["../../source/errors/NotImplementedError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,aAAa;IACrD;;;;OAIG;IACH,YAAY,OAAO,GAAG,kBAAkB,EAAE,MAAM,GAAG,GAAG;QACrD,KAAK,CAAC,wBAAwB,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAEjD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAElC,IAAI,OAAO,KAAK,CAAC,iBAAiB,KAAK,WAAW,EAAE,CAAC;YACpD,qEAAqE;YACrE,yEAAyE;YACzE,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;QACpD,CAAC;IACF,CAAC;CACD"}

package/lib/errors/PermissionViolationError.d.ts

@@ -0,0 +1,13 @@
+import { AbstractError } from "./AbstractError.js";
+/**
+ * An error used when access to a resource was requested, but the required
+ * permissions were not available.
+ */
+export declare class PermissionViolationError extends AbstractError {
+    /**
+     * Constructs a new {@linkcode PermissionViolationError}.
+     * @param message - The main error message.
+     * @param status - The HTTP status code to return.
+     */
+    constructor(message: string, status?: number);
+}

package/lib/errors/PermissionViolationError.js

@@ -0,0 +1,22 @@
+import { AbstractError } from "./AbstractError.js";
+/**
+ * An error used when access to a resource was requested, but the required
+ * permissions were not available.
+ */
+export class PermissionViolationError extends AbstractError {
+    /**
+     * Constructs a new {@linkcode PermissionViolationError}.
+     * @param message - The main error message.
+     * @param status - The HTTP status code to return.
+     */
+    constructor(message, status = 403) {
+        super("ERR_OS_PERMISSION_VIOLATION", message, status);
+        this.name = "PermissionViolationError";
+        if (typeof Error.captureStackTrace !== "undefined") {
+            // Capture a new stacktrace, otherwise it will include our base-class
+            // constructor instead of the code location we're actually interested in.
+            Error.captureStackTrace(this, PermissionViolationError);
+        }
+    }
+}
+//# sourceMappingURL=PermissionViolationError.js.map

package/lib/errors/PermissionViolationError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PermissionViolationError.js","sourceRoot":"","sources":["../../source/errors/PermissionViolationError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;GAGG;AACH,MAAM,OAAO,wBAAyB,SAAQ,aAAa;IAC1D;;;;OAIG;IACH,YAAY,OAAe,EAAE,MAAM,GAAG,GAAG;QACxC,KAAK,CAAC,6BAA6B,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAEtD,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QAEvC,IAAI,OAAO,KAAK,CAAC,iBAAiB,KAAK,WAAW,EAAE,CAAC;YACpD,qEAAqE;YACrE,yEAAyE;YACzE,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,CAAC,CAAC;QACzD,CAAC;IACF,CAAC;CACD"}

package/lib/errors/ResourceConflictError.d.ts

@@ -0,0 +1,12 @@
+import { AbstractError } from "./AbstractError.js";
+/**
+ * Used when a resource conflict was detected.
+ */
+export declare class ResourceConflictError extends AbstractError {
+    /**
+     * Constructs a new {@linkcode ResourceConflictError}.
+     * @param message - The main error message.
+     * @param status - The HTTP status code to return.
+     */
+    constructor(message: string, status?: number);
+}

package/lib/errors/ResourceConflictError.js

@@ -0,0 +1,21 @@
+import { AbstractError } from "./AbstractError.js";
+/**
+ * Used when a resource conflict was detected.
+ */
+export class ResourceConflictError extends AbstractError {
+    /**
+     * Constructs a new {@linkcode ResourceConflictError}.
+     * @param message - The main error message.
+     * @param status - The HTTP status code to return.
+     */
+    constructor(message, status = 409) {
+        super("ERR_OS_RESOURCE_CONFLICT", message, status);
+        this.name = "ResourceConflictError";
+        if (typeof Error.captureStackTrace !== "undefined") {
+            // Capture a new stacktrace, otherwise it will include our base-class
+            // constructor instead of the code location we're actually interested in.
+            Error.captureStackTrace(this, ResourceConflictError);
+        }
+    }
+}
+//# sourceMappingURL=ResourceConflictError.js.map

package/lib/errors/ResourceConflictError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResourceConflictError.js","sourceRoot":"","sources":["../../source/errors/ResourceConflictError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IACvD;;;;OAIG;IACH,YAAY,OAAe,EAAE,MAAM,GAAG,GAAG;QACxC,KAAK,CAAC,0BAA0B,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAEnD,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QAEpC,IAAI,OAAO,KAAK,CAAC,iBAAiB,KAAK,WAAW,EAAE,CAAC;YACpD,qEAAqE;YACrE,yEAAyE;YACzE,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC;QACtD,CAAC;IACF,CAAC;CACD"}

package/lib/errors/UnknownError.d.ts

@@ -0,0 +1,16 @@
+import { AbstractError } from "./AbstractError.js";
+/**
+ * Used when an unknown, non-{@linkcode !Error}-like object was caught and converted into a
+ * real {@linkcode !Error} instance.
+ * Like when you catch a `throw "boom"`, we will convert the caught `"boom"`
+ * into an {@linkcode UnknownError}.
+ * To enrich an {@linkcode !Error}-like object that was caught, use the {@linkcode InternalError}.
+ */
+export declare class UnknownError extends AbstractError {
+    /**
+     * Constructs a new {@linkcode UnknownError}.
+     * @param message - The main error message.
+     * @param status - The HTTP status code to return.
+     */
+    constructor(message: string, status?: number);
+}

package/lib/errors/UnknownError.js

@@ -0,0 +1,25 @@
+import { AbstractError } from "./AbstractError.js";
+/**
+ * Used when an unknown, non-{@linkcode !Error}-like object was caught and converted into a
+ * real {@linkcode !Error} instance.
+ * Like when you catch a `throw "boom"`, we will convert the caught `"boom"`
+ * into an {@linkcode UnknownError}.
+ * To enrich an {@linkcode !Error}-like object that was caught, use the {@linkcode InternalError}.
+ */
+export class UnknownError extends AbstractError {
+    /**
+     * Constructs a new {@linkcode UnknownError}.
+     * @param message - The main error message.
+     * @param status - The HTTP status code to return.
+     */
+    constructor(message, status = 500) {
+        super("ERR_OS_UNKNOWN", message, status);
+        this.name = "UnknownError";
+        if (typeof Error.captureStackTrace !== "undefined") {
+            // Capture a new stacktrace, otherwise it will include our base-class
+            // constructor instead of the code location we're actually interested in.
+            Error.captureStackTrace(this, UnknownError);
+        }
+    }
+}
+//# sourceMappingURL=UnknownError.js.map

package/lib/errors/UnknownError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UnknownError.js","sourceRoot":"","sources":["../../source/errors/UnknownError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,OAAO,YAAa,SAAQ,aAAa;IAC9C;;;;OAIG;IACH,YAAY,OAAe,EAAE,MAAM,GAAG,GAAG;QACxC,KAAK,CAAC,gBAAgB,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAEzC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAE3B,IAAI,OAAO,KAAK,CAAC,iBAAiB,KAAK,WAAW,EAAE,CAAC;YACpD,qEAAqE;YACrE,yEAAyE;YACzE,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QAC7C,CAAC;IACF,CAAC;CACD"}

package/lib/errors/console.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns a function that will receive errors (or anything else that was `throw`n)
+ * and prints it to a {@linkcode !console}.
+ * @param console - The console to print errors to.
+ * @returns A function that will print errors to the console.
+ */
+export declare const redirectErrorsToConsole: (console: Console) => ((error: unknown) => void);

package/lib/errors/console.js

@@ -0,0 +1,13 @@
+/**
+ * Returns a function that will receive errors (or anything else that was `throw`n)
+ * and prints it to a {@linkcode !console}.
+ * @param console - The console to print errors to.
+ * @returns A function that will print errors to the console.
+ */
+export const redirectErrorsToConsole = (console) => {
+    const printErrorsToConsole = (error) => {
+        console.error(error);
+    };
+    return printErrorsToConsole;
+};
+//# sourceMappingURL=console.js.map

package/lib/errors/console.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.js","sourceRoot":"","sources":["../../source/errors/console.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACtC,OAAgB,EACa,EAAE;IAC/B,MAAM,oBAAoB,GAAG,CAAC,KAAc,EAAQ,EAAE;QACrD,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC,CAAC;IACF,OAAO,oBAAoB,CAAC;AAC7B,CAAC,CAAC"}

package/lib/errors/error-serializer.d.ts

@@ -0,0 +1,45 @@
+import { AbstractError } from "./AbstractError.js";
+/**
+ * The shape of an {@linkcode !Error} instance, after it has been serialized into a simple hash.
+ */
+export type SerializedError = Record<string, Record<string, string> | string | undefined>;
+/**
+ * Determine if the given unknown subject is an {@linkcode !Error} instance.
+ * @param subject - The object to inspect.
+ * @returns `true` if the subject is an {@linkcode !Error}, `false` otherwise.
+ */
+export declare const isError: (subject: unknown) => subject is Error;
+/**
+ * Returns an {@linkcode AbstractError} that best represents the passed subject.
+ * If the passed subject is already an {@linkcode AbstractError}, it is returned as-is.
+ * Otherwise, it will be converted into an appropriate error type.
+ * @param subject - The subject to inspect
+ * @returns An {@linkcode AbstractError} instance.
+ */
+export declare const unknownToError: (subject: unknown) => AbstractError;
+/**
+ * Serializes an error into a string.
+ * @param error - The error to stringify.
+ * @returns A string representing the error.
+ */
+export declare const errorToString: (error: Error & {
+    toString?: () => string;
+}) => string;
+/**
+ * Serializes an error into a JSON string.
+ * @param error - The error to stringify.
+ * @returns A JSON string representing the error.
+ */
+export declare const errorToJSON: (error: Error) => string;
+/**
+ * Converts an error into a regular hash.
+ * @param error - The error to convert.
+ * @returns A new object that contains all the properties of the error.
+ */
+export declare const errorToRecord: (error: Error) => Record<string, unknown>;
+/**
+ * Serializes an error into a simpler shape.
+ * @param error - The error to serialize.
+ * @returns A simple representation of the error.
+ */
+export declare const errorToSimpleSerializable: (error: AbstractError) => SerializedError;

package/lib/errors/error-serializer.js

@@ -0,0 +1,74 @@
+import { isNil } from "../data/nil.js";
+import { AbstractError } from "./AbstractError.js";
+import { InternalError } from "./InternalError.js";
+import { UnknownError } from "./UnknownError.js";
+/**
+ * Determine if the given unknown subject is an {@linkcode !Error} instance.
+ * @param subject - The object to inspect.
+ * @returns `true` if the subject is an {@linkcode !Error}, `false` otherwise.
+ */
+export const isError = (subject) => {
+    return (subject instanceof Error ||
+        Object.prototype.toString.call(subject) === "[object Error]");
+};
+/**
+ * Returns an {@linkcode AbstractError} that best represents the passed subject.
+ * If the passed subject is already an {@linkcode AbstractError}, it is returned as-is.
+ * Otherwise, it will be converted into an appropriate error type.
+ * @param subject - The subject to inspect
+ * @returns An {@linkcode AbstractError} instance.
+ */
+export const unknownToError = (subject) => {
+    if (AbstractError.isAbstractError(subject)) {
+        return subject;
+    }
+    if (isError(subject)) {
+        return InternalError.fromError(subject);
+    }
+    return new UnknownError(String(subject));
+};
+/**
+ * Serializes an error into a string.
+ * @param error - The error to stringify.
+ * @returns A string representing the error.
+ */
+export const errorToString = (error) => {
+    return isNil(error.toString)
+        ? Object.prototype.toString.call(error)
+        : error.toString();
+};
+/**
+ * Serializes an error into a JSON string.
+ * @param error - The error to stringify.
+ * @returns A JSON string representing the error.
+ */
+export const errorToJSON = (error) => {
+    return JSON.stringify(error, Object.getOwnPropertyNames(error));
+};
+/**
+ * Converts an error into a regular hash.
+ * @param error - The error to convert.
+ * @returns A new object that contains all the properties of the error.
+ */
+export const errorToRecord = (error) => {
+    const record = {};
+    for (const propertyName of Object.getOwnPropertyNames(error)) {
+        record[propertyName] = error[propertyName];
+    }
+    return record;
+};
+/**
+ * Serializes an error into a simpler shape.
+ * @param error - The error to serialize.
+ * @returns A simple representation of the error.
+ */
+export const errorToSimpleSerializable = (error) => {
+    const serialized = {
+        code: error.code,
+        message: error.message,
+        name: error.name,
+        stack: error.stack,
+    };
+    return serialized;
+};
+//# sourceMappingURL=error-serializer.js.map

package/lib/errors/error-serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-serializer.js","sourceRoot":"","sources":["../../source/errors/error-serializer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAUjD;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,OAAgB,EAAoB,EAAE;IAC7D,OAAO,CACN,OAAO,YAAY,KAAK;QACxB,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,gBAAgB,CAC5D,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAgB,EAAiB,EAAE;IACjE,IAAI,aAAa,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5C,OAAO,OAAO,CAAC;IAChB,CAAC;IAED,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACtB,OAAO,aAAa,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,IAAI,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;AAC1C,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC5B,KAA0C,EACjC,EAAE;IACX,OAAO,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC3B,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;QACvC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;AACrB,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAY,EAAU,EAAE;IACnD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC;AACjE,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAY,EAA2B,EAAE;IACtE,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,YAAY,IAAI,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9D,MAAM,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,YAAkC,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACxC,KAAoB,EACF,EAAE;IACpB,MAAM,UAAU,GAAoB;QACnC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,KAAK,EAAE,KAAK,CAAC,KAAK;KAClB,CAAC;IAEF,OAAO,UAAU,CAAC;AACnB,CAAC,CAAC"}

package/lib/errors/error-serializer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/errors/error-serializer.test.js

@@ -0,0 +1,109 @@
+import assert from "node:assert";
+import { it } from "node:test";
+import { errorToJSON, errorToRecord, errorToSimpleSerializable, isError, unknownToError, } from "./error-serializer.js";
+import { InternalError } from "./InternalError.js";
+import { InvalidArgumentError } from "./InvalidArgumentError.js";
+function generateDefaultError() {
+    try {
+        throw new Error("oops");
+    }
+    catch (error) {
+        return error;
+    }
+}
+it("unknown to Error: AbstractError", () => {
+    const subjectError = new InvalidArgumentError("oops");
+    const serialized = unknownToError(subjectError);
+    assert.strictEqual(serialized.code, "ERR_OS_INVALID_ARGUMENT");
+    assert.strictEqual(serialized.message, "oops");
+    assert.strictEqual(serialized.name, "InvalidArgumentError");
+    assert.strictEqual(typeof serialized.stack, "string");
+});
+it("unknown to Error: Error", () => {
+    const subjectError = new Error("oops");
+    const serialized = unknownToError(subjectError);
+    assert.strictEqual(serialized.code, "ERR_OS_INTERNAL");
+    assert.strictEqual(serialized.message, "oops");
+    assert.strictEqual(serialized.name, "InternalError");
+    assert.strictEqual(typeof serialized.stack, "string");
+});
+it("unknown to Error: string", () => {
+    const subjectError = "oops";
+    const serialized = unknownToError(subjectError);
+    assert.strictEqual(serialized.code, "ERR_OS_UNKNOWN");
+    assert.strictEqual(serialized.message, "oops");
+    assert.strictEqual(serialized.name, "UnknownError");
+    assert.strictEqual(typeof serialized.stack, "string");
+});
+it("unknown to Error: null", () => {
+    const subjectError = null;
+    const serialized = unknownToError(subjectError);
+    assert.strictEqual(serialized.code, "ERR_OS_UNKNOWN");
+    assert.strictEqual(serialized.message, "null");
+    assert.strictEqual(serialized.name, "UnknownError");
+    assert.strictEqual(typeof serialized.stack, "string");
+});
+it("serializes an error to JSON", () => {
+    const subjectError = new Error("oops");
+    const plain = JSON.stringify(subjectError);
+    const serialized = errorToJSON(subjectError);
+    // We assert.strictEqual more properties to have been serialized into the string.
+    assert.notStrictEqual(serialized, plain);
+    assert.strictEqual(plain.length < serialized.length, true);
+});
+it("serializes an error to a record: Error", () => {
+    const subjectError = new Error("oops");
+    const serialized = errorToRecord(subjectError);
+    assert.strictEqual(isError(subjectError), true);
+    assert.strictEqual(isError(serialized), false);
+    assert.strictEqual(serialized.message, "oops");
+    assert.strictEqual(typeof serialized.stack, "string");
+});
+it("serializes an error to a record: Default Error", () => {
+    const subjectError = generateDefaultError();
+    const serialized = errorToRecord(subjectError);
+    assert.strictEqual(isError(subjectError), true);
+    assert.strictEqual(isError(serialized), false);
+    assert.strictEqual(serialized.code, undefined);
+    assert.strictEqual(serialized.message, "oops");
+    assert.strictEqual(serialized.name, undefined);
+    assert.strictEqual(typeof serialized.stack, "string");
+});
+it("serializes an error to a record: Node Error", async () => {
+    let error;
+    try {
+        assert(false, "oops");
+    }
+    catch (thrownError) {
+        error = thrownError;
+    }
+    const subjectError = error;
+    const serialized = errorToRecord(subjectError);
+    assert.strictEqual(isError(subjectError), true);
+    assert.strictEqual(isError(serialized), false);
+    assert.strictEqual(serialized.code, "ERR_ASSERTION");
+    assert.strictEqual(serialized.message, "oops");
+    assert.strictEqual(serialized.name, "AssertionError");
+    assert.strictEqual(typeof serialized.stack, "string");
+});
+it("serializes an error to a simple object for persistence: Error", () => {
+    const subjectError = InternalError.fromError(new Error("oops"));
+    const serialized = errorToSimpleSerializable(subjectError);
+    assert.strictEqual(isError(subjectError), true);
+    assert.strictEqual(isError(serialized), false);
+    assert.strictEqual(serialized.code, "ERR_OS_INTERNAL");
+    assert.strictEqual(serialized.message, "oops");
+    assert.strictEqual(serialized.name, "InternalError");
+    assert.strictEqual(typeof serialized.stack, "string");
+});
+it("serializes an error to a simple object for persistence: Node Error", () => {
+    const subjectError = InternalError.fromError(generateDefaultError());
+    const serialized = errorToSimpleSerializable(subjectError);
+    assert.strictEqual(isError(subjectError), true);
+    assert.strictEqual(isError(serialized), false);
+    assert.strictEqual(serialized.code, "ERR_OS_INTERNAL");
+    assert.strictEqual(serialized.message, "oops");
+    assert.strictEqual(serialized.name, "InternalError");
+    assert.strictEqual(typeof serialized.stack, "string");
+});
+//# sourceMappingURL=error-serializer.test.js.map

package/lib/errors/error-serializer.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-serializer.test.js","sourceRoot":"","sources":["../../source/errors/error-serializer.test.ts"],"names":[],"mappings":"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"}

package/lib/errors/stream.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns a function that will receive errors (or anything else that was `throw`n)
+ * and prints it to a {@linkcode NodeJS.WriteStream}.
+ * @param stream - The stream to print errors to.
+ * @returns A function that will print errors to the stream.
+ */
+export declare const redirectErrorsToStream: (stream: NodeJS.WriteStream) => ((error: unknown) => void);

package/lib/errors/stream.js

@@ -0,0 +1,15 @@
+import { errorToString, unknownToError } from "./error-serializer.js";
+/**
+ * Returns a function that will receive errors (or anything else that was `throw`n)
+ * and prints it to a {@linkcode NodeJS.WriteStream}.
+ * @param stream - The stream to print errors to.
+ * @returns A function that will print errors to the stream.
+ */
+export const redirectErrorsToStream = (stream) => {
+    const printErrorsToStream = (unknownError) => {
+        const error = unknownToError(unknownError);
+        stream.write(`${errorToString(error)}\n`);
+    };
+    return printErrorsToStream;
+};
+//# sourceMappingURL=stream.js.map

package/lib/errors/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../source/errors/stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACrC,MAA0B,EACG,EAAE;IAC/B,MAAM,mBAAmB,GAAG,CAAC,YAAqB,EAAQ,EAAE;QAC3D,MAAM,KAAK,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;QAC3C,MAAM,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC,CAAC;IACF,OAAO,mBAAmB,CAAC;AAC5B,CAAC,CAAC"}

package/lib/errors/tools.d.ts

@@ -0,0 +1,10 @@
+/**
+ * General error-related tooling that fits no other module.
+ * @module
+ */
+/**
+ * Throws the provided error.
+ * @param error - The error that will be thrown.
+ * @throws The provided error.
+ */
+export declare const rethrow: (error: unknown) => never;

package/lib/errors/tools.js

@@ -0,0 +1,13 @@
+/**
+ * General error-related tooling that fits no other module.
+ * @module
+ */
+/**
+ * Throws the provided error.
+ * @param error - The error that will be thrown.
+ * @throws The provided error.
+ */
+export const rethrow = (error) => {
+    throw error;
+};
+//# sourceMappingURL=tools.js.map

package/lib/errors/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../source/errors/tools.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAc,EAAE,EAAE;IACzC,MAAM,KAAK,CAAC;AACb,CAAC,CAAC"}

package/lib/events/event.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Creates a {@linkcode !CustomEvent} instance with the given arguments.
+ * @param type - The name of the type of the event.
+ * @param detail - The event details.
+ * @returns The requested event object.
+ */
+export declare const createEvent: <TEventType extends string, TDetail>(type: TEventType, detail: TDetail) => CustomEvent<TDetail> & {
+    type: TEventType;
+};

package/lib/events/event.js

@@ -0,0 +1,10 @@
+/**
+ * Creates a {@linkcode !CustomEvent} instance with the given arguments.
+ * @param type - The name of the type of the event.
+ * @param detail - The event details.
+ * @returns The requested event object.
+ */
+export const createEvent = (type, detail) => {
+    return new CustomEvent(type, { detail });
+};
+//# sourceMappingURL=event.js.map

package/lib/events/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../../source/events/event.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAC1B,IAAgB,EAChB,MAAe,EAC+B,EAAE;IAChD,OAAO,IAAI,WAAW,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,CAEtC,CAAC;AACH,CAAC,CAAC"}