Add modifiable() for array.map()

package.json

@@ -33,8 +33,9 @@
     "@biomejs/biome": "^1.8.3",
     "@phanect/configs": "latest",
     "@types/node": "^22.1.0",
+    "type-fest": "^4.25.0",
     "typescript": "^5.3.3",
-    "unbuild": "^2.0.0",
+    "unbuild": "3.0.0-rc.7",
     "vitest": "^2.0.2"
   },
   "engines": {

src/nodejs.ts

@@ -1 +1,2 @@
 export { cmd } from "./nodejs/cmd.ts";
+export { loadJSON } from "./nodejs/load-json.ts";

src/nodejs/load-json.ts

@@ -0,0 +1,22 @@
+import { readFile, stat } from "node:fs/promises";
+
+type LoadJsonOptions = {
+  encoding?: BufferEncoding;
+};
+
+export const loadJSON = async <LoadedJSON extends {[ key: string]: unknown }>(jsonPath: string, options?: LoadJsonOptions): Promise<LoadedJSON> => {
+  const { encoding = "utf8" } = options ?? {};
+
+  try {
+    if (!(await stat(jsonPath)).isFile()) {
+      throw new Error(`"${jsonPath}" does not exist of not a regular file.`);
+    }
+
+    const jsonFileContent = await readFile(jsonPath, { encoding });
+    const loadedJSON: LoadedJSON = JSON.parse(jsonFileContent);
+
+    return loadedJSON;
+  } catch (err) {
+    return Promise.reject(err);
+  }
+};

src/universal.ts

@@ -1,6 +1,7 @@
 export { deduplicate } from "./universal/deduplicate.ts";
 export { trimLines } from "./universal/trim-lines.ts";
 export { getLastElementOf } from "./universal/get-last-element-of.ts";
+export { modifiable } from "./universal/modifiable.ts";
 export { npmPackageExists } from "./universal/npm-package-exists.ts";
 export { random } from "./universal/random.ts";
 export { sleep } from "./universal/sleep.ts";

src/universal/modifiable.ts

@@ -0,0 +1,41 @@
+import { PartialDeep } from "type-fest";
+
+/** Return type of the first argument of the given function */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type FirstParam<T extends (...args: any[]) => any> = T extends (arg1: infer P1, ...args: any[]) => any ? P1 : never;
+/** Return types of the second and the following arguments of the given function */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type RestParams<T extends (...args: any[]) => any> = T extends (arg1: any, ...args: infer P2) => any ? P2 : never;
+
+type MapCallbackNonOptional<ReturnedElement> =
+  FirstParam<typeof Array.prototype.map<ReturnedElement>>;
+type MapCallback<ArrayElement extends FirstParam<MapCallbackNonOptional<ReturnedElement>>, ReturnedElement> = (
+  val: ArrayElement,
+  ...rest: Partial<RestParams<MapCallbackNonOptional<ReturnedElement>>>
+) => ReturnedElement;
+type OptionalizedArrayElement<ArrayElement, ReturnedElement> = PartialDeep<FirstParam<MapCallback<ArrayElement, ReturnedElement>>, {
+  recurseIntoArrays: true,
+}>;
+type ModifiableCallback<ArrayElement, ReturnedElement> = (
+  val: OptionalizedArrayElement<ArrayElement, ReturnedElement>,
+  ...rest: RestParams<MapCallback<ArrayElement, ReturnedElement>>
+) => ReturnedElement;
+
+/**
+ * Allow modifying the elements of the array given in `Array.prototype.map()`
+ * @param mapCallback - Callback function of `Array.prototype.map()`.
+ * @returns An alternative callback function for `Array.prototype.map()`.
+ * @example
+ * messages.map(modifiable((message) => {
+ *   delete message.prop;
+ *   return message;
+ * }));
+ */
+export const modifiable = <ArrayElement, ReturnedElement>(mapCallback: ModifiableCallback<ArrayElement, ReturnedElement>): MapCallback<ArrayElement, ReturnedElement> => {
+  const wrappedCallback: MapCallback<ArrayElement, ReturnedElement> = (val, ...rest) => mapCallback(
+    structuredClone(val) as OptionalizedArrayElement<ArrayElement, ReturnedElement>,
+    ...structuredClone(rest)
+  );
+
+  return wrappedCallback;
+};

test/universal/modifiable.test.ts

@@ -0,0 +1,26 @@
+import { expect, test } from "vitest";
+import { modifiable } from "../../src/universal.ts";
+
+test("modifiable", () => {
+  type Element = {
+    id: number;
+    msg: string;
+  };
+
+  const elements: Element[] = [
+    { id: 25, msg: "a" },
+    { id: 42, msg: "b" },
+    { id: 98, msg: "c" },
+  ];
+
+  const results = elements.map(modifiable((el) => {
+    delete el.id;
+    return el;
+  }));
+
+  expect(results).toStrictEqual([
+    { msg: "a" },
+    { msg: "b" },
+    { msg: "c" },
+  ]);
+});