@ezez/utils 1.9.0 → 2.1.0

package/src/deserialize.spec.ts

@@ -0,0 +1,69 @@
+import type { CustomDeserializers } from "./deserialize";
+
+import { deserialize } from "./deserialize";
+
+class Person {
+    public name: string;
+
+    public constructor(name: string) {
+        this.name = name;
+    }
+}
+
+describe("deserialize", () => {
+    it("can deserialize primitives", async () => {
+        must(deserialize(`"s:test"`)).equal("test");
+        must(deserialize(`"n:123"`)).equal(123);
+        must(deserialize(`"i:123"`)).equal(123n);
+        must(deserialize(`"u:"`)).equal(undefined);
+        must(deserialize(`"b:1"`)).equal(true);
+        must(deserialize(`"b:"`)).equal(false);
+        must(deserialize(`"l:"`)).equal(null);
+    });
+
+    it("can deserialize arrays", () => {
+        must(deserialize(`["s:a","s:b","s:c"]`)).eql(["a", "b", "c"]);
+        must(deserialize(`["n:1","i:2","u:","b:1","b:","l:"]`)).eql([1, 2n, undefined, true, false, null]);
+
+        // deep arrays:
+        must(deserialize(`["n:1",["n:2",["n:3",["n:4",["n:5"]]]]]`)).eql([1, [2, [3, [4, [5]]]]]);
+    });
+
+    it("can deserialize objects", () => {
+        must(deserialize(`{"a":"s:a","b":"s:b","c":"s:c"}`)).eql({ a: "a", b: "b", c: "c" });
+    });
+
+    it("supports custom deserializers", () => {
+        const customDeserializers: CustomDeserializers = {
+            p: (value) => {
+                return new Person(value);
+            },
+        };
+
+        const p1 = deserialize<Person>(`"p:John"`, customDeserializers);
+        must(p1).be.instanceOf(Person);
+        must(p1.name).equal("John");
+
+        const res = deserialize<{ a: Person }>(`{"a":"p:John"}`, customDeserializers);
+        const p2 = res.a;
+        must(p2).be.instanceOf(Person);
+        must(p2.name).equal("John");
+
+        must(res).eql({ a: p2 });
+    });
+
+    it("allows custom deserializers to support primitives", () => {
+        const customSerializers: CustomDeserializers = {
+            sym: (value) => {
+                return Symbol.for(value);
+            },
+        };
+
+        // must(serialize(Symbol("x"), customSerializers)).equal(`"sym:x"`);
+        must(deserialize(`"sym:x"`, customSerializers)).equal(Symbol.for("x"));
+    });
+
+    it("throws on unknown data type", () => {
+        must(() => deserialize(`"v:test"`)).throw("Unsupported data type: v");
+    });
+});

package/src/deserialize.ts

@@ -0,0 +1,74 @@
+import { replaceDeep } from "./replaceDeep.js";
+
+// if JSON.parse, even via replacer will return `undefined` the value will be eaten out, all other values
+// are fine, so we can use this symbol to simulate `undefined` when parsing, then replace it in the result if needed
+const UNDEFINED = Symbol("undefined");
+
+type CustomDeserializers = {
+    [key: string]: (data: string) => unknown;
+    s?: never;
+    n?: never;
+    u?: never;
+    l?: never;
+    b?: never;
+    i?: never;
+};
+
+/**
+ * Deserializes a string serialized with `serialize` into a value.
+ *
+ * You will need to specify deserializers if custom data types are serialized. See `serialize` for more information.
+ *
+ * @see {@link serialize}.
+ *
+ * @param serializedString - the serialized string
+ * @param customDeserializers - an object with custom deserializers
+ */
+const deserialize = <T>(serializedString: string, customDeserializers?: CustomDeserializers): T => {
+    let hasUndefined = false;
+    const replacer = (_key: string, value: unknown) => { // eslint-disable-line max-statements
+        if (typeof value === "string") {
+            if (value.startsWith("s:")) {
+                // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+                return value.slice(2);
+            }
+            if (value.startsWith("n:")) {
+                // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+                return Number(value.slice(2));
+            }
+            if (value.startsWith("i:")) {
+                // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+                return BigInt(value.slice(2));
+            }
+            if (value === "u:") {
+                hasUndefined = true;
+                return UNDEFINED;
+            }
+            if (value === "l:") {
+                return null;
+            }
+            if (value.startsWith("b:")) {
+                // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+                return value.slice(2) === "1";
+            }
+
+            const semiColonIndex = value.indexOf(":");
+            const type = value.slice(0, semiColonIndex);
+            if (customDeserializers && type in customDeserializers) {
+                return customDeserializers[type]!(value.slice(semiColonIndex + 1));
+            }
+
+            throw new Error(`Unsupported data type: ${type}`);
+        }
+        return value;
+    };
+
+    const parsed = JSON.parse(serializedString, replacer) as T;
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    return hasUndefined ? replaceDeep(parsed, UNDEFINED, undefined) : parsed;
+};
+
+export { deserialize };
+
+export type { CustomDeserializers };

package/src/index.ts

@@ -6,6 +6,7 @@ export * from "./capitalize.js";
 export * from "./coalesce.js";
 export * from "./compareArrays.js";
 export * from "./compareProps.js";
+export * from "./deserialize.js";
 export * from "./ensureArray.js";
 export * from "./ensureDate.js";
 export * from "./ensureError.js";
@@ -33,10 +34,13 @@ export * from "./pull.js";
 export * from "./remove.js";
 export * from "./removeCommonProperties.js";
 export * from "./replace.js";
+export * from "./replaceDeep.js";
 export * from "./rethrow.js";
+export * from "./round.js";
 export * from "./safe.js";
 export * from "./scale.js";
 export * from "./seq.js";
+export * from "./serialize.js";
 export * from "./set.js";
 export * from "./setImmutable.js";
 export * from "./sortBy.js";

package/src/replace.ts

@@ -1,4 +1,3 @@
-/* eslint-disable max-len */
 import { escapeRegExp } from "./escapeRegExp.js";
 
 /**

package/src/replaceDeep.spec.ts

@@ -0,0 +1,71 @@
+import { replaceDeep } from "./replaceDeep";
+
+describe("replaceDeep", () => {
+    it("should replace given value in a deep object", () => {
+        const source = [
+            99,
+            100,
+            {
+                favouriteBook: {
+                    title: "The Ring of The Lord",
+                    price: 100,
+                },
+                otherBooks: [
+                    {
+                        title: "Parry Hotter",
+                        price: 50,
+                        tag: "100",
+                    },
+                    {
+                        title: "The Hobbyte 100",
+                        price: [100],
+                    },
+                ],
+            },
+        ];
+
+        must(replaceDeep(source, 100, 200)).eql([
+            99,
+            200,
+            {
+                favouriteBook: {
+                    title: "The Ring of The Lord",
+                    price: 200,
+                },
+                otherBooks: [
+                    {
+                        title: "Parry Hotter",
+                        price: 50,
+                        tag: "100",
+                    },
+                    {
+                        title: "The Hobbyte 100",
+                        price: [200],
+                    },
+                ],
+            },
+        ]);
+    });
+
+    it("should leave primitives as-is unless they equal to the search value", () => {
+        must(replaceDeep(100, 200, 300)).equal(100);
+        must(replaceDeep(200, 200, 300)).equal(300);
+        must(replaceDeep("100", 200, 300)).equal("100");
+        // ESLINT BUG:
+        // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+        must(replaceDeep(undefined, 200, 300)).equal(undefined);
+        must(replaceDeep(null, 200, 300)).equal(null);
+        must(replaceDeep(true, 200, 300)).equal(true);
+        must(replaceDeep(666n, 200, 300)).equal(666n);
+    });
+
+    it("should work with nans", async () => {
+        must(replaceDeep({
+            a: NaN,
+            b: 123,
+        }, NaN, 300)).eql({
+            a: 300,
+            b: 123,
+        });
+    });
+});

package/src/replaceDeep.ts

@@ -0,0 +1,44 @@
+/**
+ * Replaces all occurrences of `search` with `value` in `source` object/array. Comparison is done with `Object.is`.
+ * If `source` is exactly the `search` a `value` will be returned. It does not do a substring replacements.
+ *
+ * It mutates the `source` object/array!
+ *
+ * TypeScript users: This is way too dynamic to type properly, therefore, typing assumes the most basic form of
+ * replacement where search and value are of the same type. If that's not the case for you - you'll have to typecast.
+ *
+ * @param source - source object/array/value
+ * @param search - value to search for
+ * @param value - value to replace with
+ */
+const replaceDeep = <T>(source: T, search: unknown, value: unknown): T => {
+    if (Object.is(source, search)) {
+        return value as T;
+    }
+
+    if (source == null) {
+        return source;
+    }
+
+    if (typeof source === "object") {
+        if (Array.isArray(source)) {
+            for (let i = 0; i < source.length; i++) {
+                // eslint-disable-next-line no-param-reassign,@typescript-eslint/no-unsafe-assignment
+                source[i] = replaceDeep(source[i], search, value);
+            }
+            return source;
+        }
+
+        return Object.keys(source).reduce<Record<string, unknown>>((acc, key) => {
+            // eslint-disable-next-line no-param-reassign
+            acc[key] = replaceDeep((source as Record<string, unknown>)[key], search, value);
+            return acc;
+        }, {}) as T;
+    }
+
+    return source;
+};
+
+export {
+    replaceDeep,
+};

package/src/round.spec.ts

@@ -0,0 +1,27 @@
+import { round } from "./round";
+
+describe("round", () => {
+    it("rounds the values without precision", async () => {
+        round(1.23).must.equal(1);
+        round(1.55).must.equal(2);
+        round(1.5).must.equal(2);
+        round(1.49999).must.equal(1);
+    });
+
+    it("rounds the values with precision", async () => {
+        round(1.23, 1).must.equal(1.2);
+        round(1.55, 1).must.equal(1.6);
+        round(1.5, 1).must.equal(1.5);
+        round(1.49999, 1).must.equal(1.5);
+
+        round(1.5, 2).must.equal(1.5);
+    });
+
+    it("rounds the tricky values", async () => {
+        round(0.1 + 0.2, 1).must.equal(0.3);
+    });
+
+    it("rounds with higher precision", async () => {
+        round(1.2, 6).must.equal(1.2);
+    });
+});

package/src/round.ts

@@ -0,0 +1,21 @@
+/**
+ * Rounds a number to a given precision
+ *
+ * @example
+ * round(1.23) // 1
+ * round(1.55) // 2
+ * round(1.333, 2) // 1.33
+ * round(1.2345, 3) // 1.234
+ *
+ * @param value - value to round
+ * @param precision - precision to round to
+ */
+const round = (value: number, precision?: number) => {
+    // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+    const multiplier = Math.pow(10, precision || 0);
+    return Math.round(value * multiplier) / multiplier;
+};
+
+export {
+    round,
+};

package/src/safe.ts

@@ -1,7 +1,6 @@
 function safe<T>(fn: () => T): T | undefined;
 function safe<T, Y>(fn: () => T, def: Y): T | Y;
 
-/* eslint-disable max-len */
 /**
  * Safely execute a function, return its return value or default value if the function throws.
  * @param fn - function to run

package/src/serialize.spec.ts

@@ -0,0 +1,83 @@
+import type { CustomSerializers } from "./serialize";
+
+import { serialize } from "./serialize";
+
+interface Test {
+    a: string;
+}
+
+class Person {
+    public name: string;
+
+    public constructor(name: string) {
+        this.name = name;
+    }
+}
+
+describe("serialize", () => {
+    it("can serialize primitives", async () => {
+        must(serialize("test")).equal(`"s:test"`);
+        must(serialize(123)).equal(`"n:123"`);
+        must(serialize(123n)).equal(`"i:123"`);
+        must(serialize(undefined)).equal(`"u:"`);
+        must(serialize(true)).equal(`"b:1"`);
+        must(serialize(false)).equal(`"b:"`);
+        must(serialize(null)).equal(`"l:"`);
+    });
+
+    it("can serialize arrays", async () => {
+        must(serialize(["a", "b", "c"])).equal(`["s:a","s:b","s:c"]`);
+        must(serialize([1, 2n, undefined, true, false, null])).equal(`["n:1","i:2","u:","b:1","b:","l:"]`);
+
+        // deep arrays:
+        must(serialize([1, [2, [3, [4, [5]]]]])).equal(`["n:1",["n:2",["n:3",["n:4",["n:5"]]]]]`);
+    });
+
+    it("can serialize objects", async () => {
+        must(serialize({ a: "a", b: "b", c: "c" })).equal(`{"a":"s:a","b":"s:b","c":"s:c"}`);
+
+        const a: Test = { a: "a" };
+        must(serialize(a)).equal(`{"a":"s:a"}`);
+    });
+
+    it("supports custom serializers", async () => {
+        const customSerializers: CustomSerializers = {
+            p: (value) => {
+                if (value instanceof Person) {
+                    return value.name;
+                }
+                return null;
+            },
+        };
+
+        must(serialize(new Person("John"), customSerializers)).equal(`"p:John"`);
+        must(serialize({ a: new Person("John") }, customSerializers)).equal(`{"a":"p:John"}`);
+    });
+
+    it("throws on unknown data type", () => {
+        const x = Symbol("x");
+
+        must(() => serialize(x)).throw("Unsupported data type: symbol");
+    });
+
+    it("allows custom serializers to support primitives", () => {
+        const customSerializers: CustomSerializers = {
+            sym: (value) => {
+                if (typeof value === "symbol") {
+                    return String(value);
+                }
+                return null;
+            },
+        };
+
+        must(serialize(Symbol("x"), customSerializers)).equal(`"sym:Symbol(x)"`);
+        must(serialize({ a: Symbol("x") }, customSerializers)).equal(`{"a":"sym:Symbol(x)"}`);
+    });
+
+    it("returns the same for any order of props", () => {
+        const a = { a: 1, b: 2 };
+        const b = { b: 2, a: 1 };
+
+        must(serialize(a)).equal(serialize(b));
+    });
+});

package/src/serialize.ts

@@ -0,0 +1,102 @@
+import { sortProps } from "./sortProps.js";
+
+type CustomSerializers = {
+    [key: string]: (data: unknown) => (string | null);
+    s?: never;
+    n?: never;
+    u?: never;
+    l?: never;
+    b?: never;
+    i?: never;
+};
+
+type Options = {
+    sortProps?: boolean;
+};
+
+/**
+ * Serializes the data into a string. Think of it as a JSON.stringify on steroids.
+ * In opposite to JSON.stringify it supports serializing undefined.
+ *
+ * It also supports custom serializers, which can be used to serialize custom data types. Each value has a prefix which
+ * specifies the type of the value, custom serializers is a map of these prefixes to functions which can serialize the
+ * value into a string. IMPORTANT: Because this is using JSON.serialize under the hood if a value to serialize includes
+ * `toJSON` it won't trigger custom serializer but will be serialized as string. `Date` class defines `toJSON` method!
+ *
+ * The extra aim of this function is to produce the same output for "the same" data, regardless of the order of the keys
+ * (which is not guaranteed by JS spec, but in practice it is guaranteed by current implementations of all JS engines),
+ * so it sorts the keys and when serializing data by default, you can opt-out of this behavior by passing
+ * `{ sortProps: false }` as the third argument.
+ *
+ * @param data - the data to serialize
+ * @param customSerializers - an object with custom serializers
+ * @param options - options
+ */
+const serialize = (data: unknown, customSerializers?: CustomSerializers, options?: Options) => { // eslint-disable-line max-lines-per-function,max-len
+    const replacer = (_key: string, value: unknown) => { // eslint-disable-line max-statements
+        if (typeof value === "string") {
+            return `s:${value}`;
+        }
+        if (typeof value === "number") {
+            return `n:${value}`;
+        }
+        if (typeof value === "bigint") {
+            return `i:${value}`;
+        }
+        if (typeof value === "undefined") {
+            return "u:";
+        }
+        if (typeof value === "boolean") {
+            return "b:" + (value ? "1" : "");
+        }
+        if (value === null) {
+            return "l:";
+        }
+        const serializerKeys = Object.keys(customSerializers ?? {});
+        for (const key of serializerKeys) {
+            const serialized = customSerializers![key]!(value);
+            if (typeof serialized === "string") {
+                return `${key}:${serialized}`;
+            }
+        }
+        if (typeof value === "object") {
+            return value;
+        }
+
+        throw new Error(`Unsupported data type: ${typeof value}`);
+    };
+
+    if (
+        data == null
+        || typeof data === "string"
+        || typeof data === "number"
+        || typeof data === "bigint"
+        || typeof data === "undefined"
+        || typeof data === "boolean"
+        || Array.isArray(data)
+    ) {
+        return JSON.stringify(data, replacer);
+    }
+
+    const serializerKeysGlobal = Object.keys(customSerializers ?? {});
+    for (const key of serializerKeysGlobal) {
+        const serialized = customSerializers![key]!(data);
+        if (typeof serialized === "string") {
+            return `"${key}:${serialized}"`;
+        }
+    }
+
+    if (typeof data === "object") {
+        return JSON.stringify(
+            options?.sortProps === false
+                ? data
+                : sortProps(data as Record<string, unknown>),
+            replacer,
+        );
+    }
+
+    throw new Error(`Unsupported data type: ${typeof data}`);
+};
+
+export type { CustomSerializers };
+export { serialize };

package/src/sortProps.ts

@@ -1,6 +1,9 @@
 /**
  * Sorts the properties of an object alphabetically, ascending or descending.
- * REMEMBER: In theory JS engines do not guarantee the order of object properties. In practice most popular engines do.
+ * It does not mutate the original object.
+ *
+ * REMEMBER: In theory, JS engines do not guarantee the order of object properties.
+ * In practice most of the popular engines do.
  * @param object - source object
  * @param asc - sort ascending?
  * @example sortProps({ b: 2, a: 1, z: 26 }) // { a: 1, b: 2, z: 26 }

package/babel.config.cjs

@@ -1,6 +0,0 @@
-module.exports = {
-    presets: [
-        ['@babel/preset-env', { targets: { node: 'current' } }],
-        '@babel/preset-typescript',
-    ],
-};