@keeex/utils 7.5.0 → 7.6.0

package/lib/array.d.ts

@@ -26,3 +26,5 @@ export declare const arrayEqual: <T1 = unknown, T2 = unknown>(op1: ArrayLike<T1>
  * @public
  */
 export declare const asArray: <T>(data: Array<T> | (T extends Array<unknown> ? never : T)) => Array<T>;
+/** Return a new array with its string sorted */
+export declare const toSortedStringArray: (array: Array<string>) => Array<string>;

package/lib/array.js

@@ -13,6 +13,7 @@
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  * 
  */
+import { alphaSort } from "./string.js";
 const useEqOp = (op1, op2) => op1 === op2;
 /**
  * Compare two array-like structure for equal content
@@ -34,3 +35,5 @@ export const arrayEqual = (op1, op2, eqFunc = useEqOp) => {
  * @public
  */
 export const asArray = (data) => Array.isArray(data) ? data : [data];
+/** Return a new array with its string sorted */
+export const toSortedStringArray = (array) => array.toSorted(alphaSort);

package/lib/dict.d.ts

@@ -54,3 +54,35 @@ export type PrimitiveTypeObject = Record<string, unknown> | Array<unknown> | str
  * @public
  */
 export declare const deepCopyPrimitive: (source: unknown) => unknown;
+/**
+ * Perform the merge operation between two values.
+ *
+ * If the new value have no changes from the initial value, this should always return `initial`.
+ * If there is any change, this should always return a new reference.
+ *
+ * TODO: The function returns unknown because I can't work around the requirements for TypeScript to
+ * be happy using `DataType | null`.
+ */
+type RefMergeDefFn<DataType> = (initial: DataType | null, newValue: DataType | null) => unknown;
+type RefMergeDef<DataType> = DataType extends string ? "string" : DataType extends number ? "number" : DataType extends boolean ? "boolean" : DataType extends Array<string> ? "string[]" : RefMergeDefFn<DataType>;
+type RefMergeProfile<ObjectType> = Required<{
+    [key in keyof ObjectType]: RefMergeDef<NonNullable<ObjectType[key]>>;
+}>;
+/**
+ * Examine each props on both `initial` and `newValue`, and if there is any change, return a new
+ * reference with all values.
+ *
+ * @param initial - The source object. If no changes are detected, returns it.
+ * @param newValue - Values to update in `initial`. `undefined` values are skipped.
+ * @param profile - Describe the expected properties and how to merge them.
+ *
+ * @returns
+ * If there is some change from `initial`, will return a new reference with all new values.
+ * This property extends to values that are object; all objects in this hierarchy that have an
+ * update belows it is replaced with a new reference.
+ *
+ * This is made to help with libraries like React that depends on state reference actually getting
+ * changed on update.
+ */
+export declare const refMergeObjects: <ObjectType>(initial: ObjectType, newValue: Partial<ObjectType>, profile: RefMergeProfile<ObjectType>) => ObjectType;
+export {};

package/lib/dict.js

@@ -13,6 +13,7 @@
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  * 
  */
+import { arrayEqual } from "./array.js";
 /**
  * Copy all properties from secondary into primary.
  *
@@ -72,3 +73,65 @@ export const deepCopyPrimitive = (source) => {
         return res;
     }
 };
+const refMergeStringArray = (initial, newValue) => {
+    if (newValue === null)
+        return null;
+    if (initial !== null && arrayEqual(initial, newValue))
+        return initial;
+    return [...newValue];
+};
+/**
+ * Merge a new value and an old value according to the provided merger.
+ *
+ * If `newValue` is undefined, `initial` is always returned.
+ * If `newValue` is defined AND have difference from `initial`, a new object should be returned.
+ * If there is no change, `initial` is returned.
+ */
+const getMergedRef = (initial, newValue, merger) => {
+    if (newValue === undefined)
+        return initial;
+    switch (merger) {
+        case "string":
+        case "number":
+        case "boolean":
+            return newValue;
+        case "string[]":
+            return refMergeStringArray(initial, newValue);
+        default: {
+            return merger(initial, newValue);
+        }
+    }
+};
+/**
+ * Examine each props on both `initial` and `newValue`, and if there is any change, return a new
+ * reference with all values.
+ *
+ * @param initial - The source object. If no changes are detected, returns it.
+ * @param newValue - Values to update in `initial`. `undefined` values are skipped.
+ * @param profile - Describe the expected properties and how to merge them.
+ *
+ * @returns
+ * If there is some change from `initial`, will return a new reference with all new values.
+ * This property extends to values that are object; all objects in this hierarchy that have an
+ * update belows it is replaced with a new reference.
+ *
+ * This is made to help with libraries like React that depends on state reference actually getting
+ * changed on update.
+ */
+export const refMergeObjects = (initial, newValue, profile) => {
+    let anyChange = false;
+    const newValues = Object.entries(profile).map(([key, merger]) => {
+        const initialValue = initial[key];
+        const merged = getMergedRef(initialValue, newValue[key], merger);
+        anyChange ||= merged !== initialValue;
+        return { key, merged };
+    });
+    // Can't statically detect changes in map() callback
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (!anyChange)
+        return initial;
+    return newValues.reduce((acc, { key, merged }) => {
+        acc[key] = merged;
+        return acc;
+    }, {});
+};

package/lib/string.d.ts

@@ -63,3 +63,11 @@ export declare const encodeUTF8: (str: string) => string;
 export declare const decodeUTF8: (str: string, skipErrors?: boolean) => string;
 /** Capitalize (or uncapitalize) the first character of a string */
 export declare const capitalize: (str: string, upperFirstLetter: boolean) => string;
+/** Ensure the string ends with one newline */
+export declare const enforceNewlineEnd: (str: string) => string;
+/** Format the text as a single line or multiline JS comment */
+export declare const jsComment: (text: string, jsDoc?: boolean) => string;
+/** Make sure the string starts with a capital, and all other letters are lowercase */
+export declare const uncapitalize: (str: string) => string;
+/** Helper to use with `Array.sort()` and similar */
+export declare const alphaSort: (a: string, b: string) => number;

package/lib/string.js

@@ -106,3 +106,35 @@ export const capitalize = (str, upperFirstLetter) => {
     const rest = str.slice(1);
     return `${transformedFirstLetter}${rest}`;
 };
+/** Return the last index of a character that pass the needle test, or -1 if it never happens */
+const findLastIndexOf = (hay, needle) => {
+    for (let index = hay.length - 1; --index; index >= 0) {
+        if (needle(hay.at(index)))
+            return index;
+    }
+    return -1;
+};
+/** Ensure the string ends with one newline */
+export const enforceNewlineEnd = (str) => {
+    if (str.endsWith("\n")) {
+        const firstNonNewline = findLastIndexOf(str, (c) => c !== "\n");
+        if (firstNonNewline === -1)
+            return "\n";
+        return `${str.slice(0, firstNonNewline + 1)}\n`;
+    }
+    return `${str}\n`;
+};
+/** Format the text as a single line or multiline JS comment */
+export const jsComment = (text, jsDoc = false) => {
+    const lines = text.split("\n");
+    if (lines.length === 1 && !jsDoc)
+        return `// ${lines[0]}`;
+    const prefix = jsDoc ? "/**" : "/*";
+    if (lines.length === 1)
+        return `${prefix} ${lines[0].replaceAll("*/", "* /")} */`;
+    return [prefix, ...lines.map((c) => ` * ${c.trimEnd().replaceAll("*/", "* /")}`), " */"].join("\n");
+};
+/** Make sure the string starts with a capital, and all other letters are lowercase */
+export const uncapitalize = (str) => str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
+/** Helper to use with `Array.sort()` and similar */
+export const alphaSort = (a, b) => a.localeCompare(b);

package/package.json

@@ -1 +1 @@
-{"name":"@keeex/utils","version":"7.5.0","description":"Various utility functions for pure JavaScript","scripts":{},"author":"KeeeX SAS","contributors":[{"name":"Gabriel Paul \"Cley Faye\" Risterucci","email":"gabriel@keeex.net"}],"homepage":"https://keeex.me/oss","keywords":["utility"],"type":"module","license":"MIT","dependencies":{"@keeex/bubble_babble":"^3.0.1","@keeex/log":"^1.7.2","base64-arraybuffer":"^1.0.2","cron-parser":"^5.4.0","ms":"^2.1.3","text-encoding-shim":"^1.0.5"},"exports":{"./array.js":{"node":"./lib/array.js","browser":"./web/array.js","react-native":"./web/array.js","default":"./lib/array.js"},"./arraybuffer.js":{"node":"./lib/arraybuffer.js","browser":"./web/arraybuffer.js","react-native":"./web/arraybuffer.js","default":"./lib/arraybuffer.js"},"./async/asynctrigger.js":{"node":"./lib/async/asynctrigger.js","browser":"./web/async/asynctrigger.js","react-native":"./web/async/asynctrigger.js","default":"./lib/async/asynctrigger.js"},"./async/deferredpromise.js":{"node":"./lib/async/deferredpromise.js","browser":"./web/async/deferredpromise.js","react-native":"./web/async/deferredpromise.js","default":"./lib/async/deferredpromise.js"},"./async/eventqueue.js":{"node":"./lib/async/eventqueue.js","browser":"./web/async/eventqueue.js","react-native":"./web/async/eventqueue.js","default":"./lib/async/eventqueue.js"},"./async/keycache.js":{"node":"./lib/async/keycache.js","browser":"./web/async/keycache.js","react-native":"./web/async/keycache.js","default":"./lib/async/keycache.js"},"./async/queues.js":{"node":"./lib/async/queues.js","browser":"./web/async/queues.js","react-native":"./web/async/queues.js","default":"./lib/async/queues.js"},"./async/timecache.js":{"node":"./lib/async/timecache.js","browser":"./web/async/timecache.js","react-native":"./web/async/timecache.js","default":"./lib/async/timecache.js"},"./base58.js":{"node":"./lib/base58.js","browser":"./web/base58.js","react-native":"./web/base58.js","default":"./lib/base58.js"},"./base64.js":{"node":"./lib/base64.js","browser":"./web/base64.js","react-native":"./web/base64.js","default":"./lib/base64.js"},"./benchmark.js":{"node":"./lib/benchmark.js","browser":"./web/benchmark.js","react-native":"./web/benchmark.js","default":"./lib/benchmark.js"},"./bytebuffer.js":{"node":"./lib/bytebuffer.js","browser":"./web/bytebuffer.js","react-native":"./web/bytebuffer.js","default":"./lib/bytebuffer.js"},"./consts.js":{"node":"./lib/consts.js","browser":"./web/consts.js","react-native":"./web/consts.js","default":"./lib/consts.js"},"./cron.js":{"node":"./lib/cron.js","browser":"./web/cron.js","react-native":"./web/cron.js","default":"./lib/cron.js"},"./dataview.js":{"node":"./lib/dataview.js","browser":"./web/dataview.js","react-native":"./web/dataview.js","default":"./lib/dataview.js"},"./dict.js":{"node":"./lib/dict.js","browser":"./web/dict.js","react-native":"./web/dict.js","default":"./lib/dict.js"},"./error.js":{"node":"./lib/error.js","browser":"./web/error.js","react-native":"./web/error.js","default":"./lib/error.js"},"./global.js":{"node":"./lib/global.js","browser":"./web/global.js","react-native":"./web/global.js","default":"./lib/global.js"},"./hex.js":{"node":"./lib/hex.js","browser":"./web/hex.js","react-native":"./web/hex.js","default":"./lib/hex.js"},"./idx.js":{"node":"./lib/idx.js","browser":"./web/idx.js","react-native":"./web/idx.js","default":"./lib/idx.js"},"./json.js":{"node":"./lib/json.js","browser":"./web/json.js","react-native":"./web/json.js","default":"./lib/json.js"},"./linebuffer.js":{"node":"./lib/linebuffer.js","browser":"./web/linebuffer.js","react-native":"./web/linebuffer.js","default":"./lib/linebuffer.js"},"./marshalling/marshaller.js":{"node":"./lib/marshalling/marshaller.js","browser":"./web/marshalling/marshaller.js","react-native":"./web/marshalling/marshaller.js","default":"./lib/marshalling/marshaller.js"},"./marshalling/unmarshaller.js":{"node":"./lib/marshalling/unmarshaller.js","browser":"./web/marshalling/unmarshaller.js","react-native":"./web/marshalling/unmarshaller.js","default":"./lib/marshalling/unmarshaller.js"},"./number.js":{"node":"./lib/number.js","browser":"./web/number.js","react-native":"./web/number.js","default":"./lib/number.js"},"./path.js":{"node":"./lib/path.js","browser":"./web/path.js","react-native":"./web/path.js","default":"./lib/path.js"},"./promise.js":{"node":"./lib/promise.js","browser":"./web/promise.js","react-native":"./web/promise.js","default":"./lib/promise.js"},"./starttime.js":{"node":"./lib/starttime.js","browser":"./web/starttime.js","react-native":"./web/starttime.js","default":"./lib/starttime.js"},"./string.js":{"node":"./lib/string.js","browser":"./web/string.js","react-native":"./web/string.js","default":"./lib/string.js"},"./triggers.js":{"node":"./lib/triggers.js","browser":"./web/triggers.js","react-native":"./web/triggers.js","default":"./lib/triggers.js"},"./types/array.js":{"node":"./lib/types/array.js","browser":"./web/types/array.js","react-native":"./web/types/array.js","default":"./lib/types/array.js"},"./types/enum.js":{"node":"./lib/types/enum.js","browser":"./web/types/enum.js","react-native":"./web/types/enum.js","default":"./lib/types/enum.js"},"./types/predicateerror.js":{"node":"./lib/types/predicateerror.js","browser":"./web/types/predicateerror.js","react-native":"./web/types/predicateerror.js","default":"./lib/types/predicateerror.js"},"./types/primitive.js":{"node":"./lib/types/primitive.js","browser":"./web/types/primitive.js","react-native":"./web/types/primitive.js","default":"./lib/types/primitive.js"},"./types/record.js":{"node":"./lib/types/record.js","browser":"./web/types/record.js","react-native":"./web/types/record.js","default":"./lib/types/record.js"},"./types/types.js":{"node":"./lib/types/types.js","browser":"./web/types/types.js","react-native":"./web/types/types.js","default":"./lib/types/types.js"},"./types/utils.js":{"node":"./lib/types/utils.js","browser":"./web/types/utils.js","react-native":"./web/types/utils.js","default":"./lib/types/utils.js"},"./uint8array.js":{"node":"./lib/uint8array.js","browser":"./web/uint8array.js","react-native":"./web/uint8array.js","default":"./lib/uint8array.js"},"./units.js":{"node":"./lib/units.js","browser":"./web/units.js","react-native":"./web/units.js","default":"./lib/units.js"}},"files":["/lib","/web"]}
+{"name":"@keeex/utils","version":"7.6.0","description":"Various utility functions for pure JavaScript","scripts":{},"author":"KeeeX SAS","contributors":[{"name":"Gabriel Paul \"Cley Faye\" Risterucci","email":"gabriel@keeex.net"}],"homepage":"https://keeex.me/oss","keywords":["utility"],"type":"module","license":"MIT","dependencies":{"@keeex/bubble_babble":"^3.0.1","@keeex/log":"^1.7.2","base64-arraybuffer":"^1.0.2","cron-parser":"^5.4.0","ms":"^2.1.3","text-encoding-shim":"^1.0.5"},"exports":{"./array.js":{"node":"./lib/array.js","browser":"./web/array.js","react-native":"./web/array.js","default":"./lib/array.js"},"./arraybuffer.js":{"node":"./lib/arraybuffer.js","browser":"./web/arraybuffer.js","react-native":"./web/arraybuffer.js","default":"./lib/arraybuffer.js"},"./async/asynctrigger.js":{"node":"./lib/async/asynctrigger.js","browser":"./web/async/asynctrigger.js","react-native":"./web/async/asynctrigger.js","default":"./lib/async/asynctrigger.js"},"./async/deferredpromise.js":{"node":"./lib/async/deferredpromise.js","browser":"./web/async/deferredpromise.js","react-native":"./web/async/deferredpromise.js","default":"./lib/async/deferredpromise.js"},"./async/eventqueue.js":{"node":"./lib/async/eventqueue.js","browser":"./web/async/eventqueue.js","react-native":"./web/async/eventqueue.js","default":"./lib/async/eventqueue.js"},"./async/keycache.js":{"node":"./lib/async/keycache.js","browser":"./web/async/keycache.js","react-native":"./web/async/keycache.js","default":"./lib/async/keycache.js"},"./async/queues.js":{"node":"./lib/async/queues.js","browser":"./web/async/queues.js","react-native":"./web/async/queues.js","default":"./lib/async/queues.js"},"./async/timecache.js":{"node":"./lib/async/timecache.js","browser":"./web/async/timecache.js","react-native":"./web/async/timecache.js","default":"./lib/async/timecache.js"},"./base58.js":{"node":"./lib/base58.js","browser":"./web/base58.js","react-native":"./web/base58.js","default":"./lib/base58.js"},"./base64.js":{"node":"./lib/base64.js","browser":"./web/base64.js","react-native":"./web/base64.js","default":"./lib/base64.js"},"./benchmark.js":{"node":"./lib/benchmark.js","browser":"./web/benchmark.js","react-native":"./web/benchmark.js","default":"./lib/benchmark.js"},"./bytebuffer.js":{"node":"./lib/bytebuffer.js","browser":"./web/bytebuffer.js","react-native":"./web/bytebuffer.js","default":"./lib/bytebuffer.js"},"./consts.js":{"node":"./lib/consts.js","browser":"./web/consts.js","react-native":"./web/consts.js","default":"./lib/consts.js"},"./cron.js":{"node":"./lib/cron.js","browser":"./web/cron.js","react-native":"./web/cron.js","default":"./lib/cron.js"},"./dataview.js":{"node":"./lib/dataview.js","browser":"./web/dataview.js","react-native":"./web/dataview.js","default":"./lib/dataview.js"},"./dict.js":{"node":"./lib/dict.js","browser":"./web/dict.js","react-native":"./web/dict.js","default":"./lib/dict.js"},"./error.js":{"node":"./lib/error.js","browser":"./web/error.js","react-native":"./web/error.js","default":"./lib/error.js"},"./global.js":{"node":"./lib/global.js","browser":"./web/global.js","react-native":"./web/global.js","default":"./lib/global.js"},"./hex.js":{"node":"./lib/hex.js","browser":"./web/hex.js","react-native":"./web/hex.js","default":"./lib/hex.js"},"./idx.js":{"node":"./lib/idx.js","browser":"./web/idx.js","react-native":"./web/idx.js","default":"./lib/idx.js"},"./json.js":{"node":"./lib/json.js","browser":"./web/json.js","react-native":"./web/json.js","default":"./lib/json.js"},"./linebuffer.js":{"node":"./lib/linebuffer.js","browser":"./web/linebuffer.js","react-native":"./web/linebuffer.js","default":"./lib/linebuffer.js"},"./marshalling/marshaller.js":{"node":"./lib/marshalling/marshaller.js","browser":"./web/marshalling/marshaller.js","react-native":"./web/marshalling/marshaller.js","default":"./lib/marshalling/marshaller.js"},"./marshalling/unmarshaller.js":{"node":"./lib/marshalling/unmarshaller.js","browser":"./web/marshalling/unmarshaller.js","react-native":"./web/marshalling/unmarshaller.js","default":"./lib/marshalling/unmarshaller.js"},"./number.js":{"node":"./lib/number.js","browser":"./web/number.js","react-native":"./web/number.js","default":"./lib/number.js"},"./path.js":{"node":"./lib/path.js","browser":"./web/path.js","react-native":"./web/path.js","default":"./lib/path.js"},"./promise.js":{"node":"./lib/promise.js","browser":"./web/promise.js","react-native":"./web/promise.js","default":"./lib/promise.js"},"./starttime.js":{"node":"./lib/starttime.js","browser":"./web/starttime.js","react-native":"./web/starttime.js","default":"./lib/starttime.js"},"./string.js":{"node":"./lib/string.js","browser":"./web/string.js","react-native":"./web/string.js","default":"./lib/string.js"},"./triggers.js":{"node":"./lib/triggers.js","browser":"./web/triggers.js","react-native":"./web/triggers.js","default":"./lib/triggers.js"},"./types/array.js":{"node":"./lib/types/array.js","browser":"./web/types/array.js","react-native":"./web/types/array.js","default":"./lib/types/array.js"},"./types/enum.js":{"node":"./lib/types/enum.js","browser":"./web/types/enum.js","react-native":"./web/types/enum.js","default":"./lib/types/enum.js"},"./types/predicateerror.js":{"node":"./lib/types/predicateerror.js","browser":"./web/types/predicateerror.js","react-native":"./web/types/predicateerror.js","default":"./lib/types/predicateerror.js"},"./types/primitive.js":{"node":"./lib/types/primitive.js","browser":"./web/types/primitive.js","react-native":"./web/types/primitive.js","default":"./lib/types/primitive.js"},"./types/record.js":{"node":"./lib/types/record.js","browser":"./web/types/record.js","react-native":"./web/types/record.js","default":"./lib/types/record.js"},"./types/types.js":{"node":"./lib/types/types.js","browser":"./web/types/types.js","react-native":"./web/types/types.js","default":"./lib/types/types.js"},"./types/utils.js":{"node":"./lib/types/utils.js","browser":"./web/types/utils.js","react-native":"./web/types/utils.js","default":"./lib/types/utils.js"},"./uint8array.js":{"node":"./lib/uint8array.js","browser":"./web/uint8array.js","react-native":"./web/uint8array.js","default":"./lib/uint8array.js"},"./units.js":{"node":"./lib/units.js","browser":"./web/units.js","react-native":"./web/units.js","default":"./lib/units.js"}},"files":["/lib","/web"]}

package/web/array.d.ts

@@ -26,3 +26,5 @@ export declare const arrayEqual: <T1 = unknown, T2 = unknown>(op1: ArrayLike<T1>
  * @public
  */
 export declare const asArray: <T>(data: Array<T> | (T extends Array<unknown> ? never : T)) => Array<T>;
+/** Return a new array with its string sorted */
+export declare const toSortedStringArray: (array: Array<string>) => Array<string>;

package/web/array.js

@@ -13,6 +13,7 @@
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  * 
  */
+import { alphaSort } from "./string.js";
 const useEqOp = (op1, op2) => op1 === op2;
 /**
  * Compare two array-like structure for equal content
@@ -31,4 +32,6 @@ export const arrayEqual = (op1, op2, eqFunc = useEqOp) => {
  *
  * @public
  */
-export const asArray = data => Array.isArray(data) ? data : [data];
+export const asArray = data => Array.isArray(data) ? data : [data];
+/** Return a new array with its string sorted */
+export const toSortedStringArray = array => array.toSorted(alphaSort);

package/web/dict.d.ts

@@ -54,3 +54,35 @@ export type PrimitiveTypeObject = Record<string, unknown> | Array<unknown> | str
  * @public
  */
 export declare const deepCopyPrimitive: (source: unknown) => unknown;
+/**
+ * Perform the merge operation between two values.
+ *
+ * If the new value have no changes from the initial value, this should always return `initial`.
+ * If there is any change, this should always return a new reference.
+ *
+ * TODO: The function returns unknown because I can't work around the requirements for TypeScript to
+ * be happy using `DataType | null`.
+ */
+type RefMergeDefFn<DataType> = (initial: DataType | null, newValue: DataType | null) => unknown;
+type RefMergeDef<DataType> = DataType extends string ? "string" : DataType extends number ? "number" : DataType extends boolean ? "boolean" : DataType extends Array<string> ? "string[]" : RefMergeDefFn<DataType>;
+type RefMergeProfile<ObjectType> = Required<{
+    [key in keyof ObjectType]: RefMergeDef<NonNullable<ObjectType[key]>>;
+}>;
+/**
+ * Examine each props on both `initial` and `newValue`, and if there is any change, return a new
+ * reference with all values.
+ *
+ * @param initial - The source object. If no changes are detected, returns it.
+ * @param newValue - Values to update in `initial`. `undefined` values are skipped.
+ * @param profile - Describe the expected properties and how to merge them.
+ *
+ * @returns
+ * If there is some change from `initial`, will return a new reference with all new values.
+ * This property extends to values that are object; all objects in this hierarchy that have an
+ * update belows it is replaced with a new reference.
+ *
+ * This is made to help with libraries like React that depends on state reference actually getting
+ * changed on update.
+ */
+export declare const refMergeObjects: <ObjectType>(initial: ObjectType, newValue: Partial<ObjectType>, profile: RefMergeProfile<ObjectType>) => ObjectType;
+export {};

package/web/dict.js

@@ -13,6 +13,7 @@
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  * 
  */
+import { arrayEqual } from "./array.js";
 /**
  * Copy all properties from secondary into primary.
  *
@@ -64,4 +65,69 @@ export const deepCopyPrimitive = source => {
     }
     return res;
   }
+};
+const refMergeStringArray = (initial, newValue) => {
+  if (newValue === null) return null;
+  if (initial !== null && arrayEqual(initial, newValue)) return initial;
+  return [...newValue];
+};
+/**
+ * Merge a new value and an old value according to the provided merger.
+ *
+ * If `newValue` is undefined, `initial` is always returned.
+ * If `newValue` is defined AND have difference from `initial`, a new object should be returned.
+ * If there is no change, `initial` is returned.
+ */
+const getMergedRef = (initial, newValue, merger) => {
+  if (newValue === undefined) return initial;
+  switch (merger) {
+    case "string":
+    case "number":
+    case "boolean":
+      return newValue;
+    case "string[]":
+      return refMergeStringArray(initial, newValue);
+    default:
+      {
+        return merger(initial, newValue);
+      }
+  }
+};
+/**
+ * Examine each props on both `initial` and `newValue`, and if there is any change, return a new
+ * reference with all values.
+ *
+ * @param initial - The source object. If no changes are detected, returns it.
+ * @param newValue - Values to update in `initial`. `undefined` values are skipped.
+ * @param profile - Describe the expected properties and how to merge them.
+ *
+ * @returns
+ * If there is some change from `initial`, will return a new reference with all new values.
+ * This property extends to values that are object; all objects in this hierarchy that have an
+ * update belows it is replaced with a new reference.
+ *
+ * This is made to help with libraries like React that depends on state reference actually getting
+ * changed on update.
+ */
+export const refMergeObjects = (initial, newValue, profile) => {
+  let anyChange = false;
+  const newValues = Object.entries(profile).map(([key, merger]) => {
+    const initialValue = initial[key];
+    const merged = getMergedRef(initialValue, newValue[key], merger);
+    anyChange ||= merged !== initialValue;
+    return {
+      key,
+      merged
+    };
+  });
+  // Can't statically detect changes in map() callback
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (!anyChange) return initial;
+  return newValues.reduce((acc, {
+    key,
+    merged
+  }) => {
+    acc[key] = merged;
+    return acc;
+  }, {});
 };

package/web/string.d.ts

@@ -63,3 +63,11 @@ export declare const encodeUTF8: (str: string) => string;
 export declare const decodeUTF8: (str: string, skipErrors?: boolean) => string;
 /** Capitalize (or uncapitalize) the first character of a string */
 export declare const capitalize: (str: string, upperFirstLetter: boolean) => string;
+/** Ensure the string ends with one newline */
+export declare const enforceNewlineEnd: (str: string) => string;
+/** Format the text as a single line or multiline JS comment */
+export declare const jsComment: (text: string, jsDoc?: boolean) => string;
+/** Make sure the string starts with a capital, and all other letters are lowercase */
+export declare const uncapitalize: (str: string) => string;
+/** Helper to use with `Array.sort()` and similar */
+export declare const alphaSort: (a: string, b: string) => number;

package/web/string.js

@@ -98,4 +98,32 @@ export const capitalize = (str, upperFirstLetter) => {
   const transformedFirstLetter = upperFirstLetter ? firstLetter.toUpperCase() : firstLetter.toLowerCase();
   const rest = str.slice(1);
   return `${transformedFirstLetter}${rest}`;
-};
+};
+/** Return the last index of a character that pass the needle test, or -1 if it never happens */
+const findLastIndexOf = (hay, needle) => {
+  for (let index = hay.length - 1; --index; index >= 0) {
+    if (needle(hay.at(index))) return index;
+  }
+  return -1;
+};
+/** Ensure the string ends with one newline */
+export const enforceNewlineEnd = str => {
+  if (str.endsWith("\n")) {
+    const firstNonNewline = findLastIndexOf(str, c => c !== "\n");
+    if (firstNonNewline === -1) return "\n";
+    return `${str.slice(0, firstNonNewline + 1)}\n`;
+  }
+  return `${str}\n`;
+};
+/** Format the text as a single line or multiline JS comment */
+export const jsComment = (text, jsDoc = false) => {
+  const lines = text.split("\n");
+  if (lines.length === 1 && !jsDoc) return `// ${lines[0]}`;
+  const prefix = jsDoc ? "/**" : "/*";
+  if (lines.length === 1) return `${prefix} ${lines[0].replaceAll("*/", "* /")} */`;
+  return [prefix, ...lines.map(c => ` * ${c.trimEnd().replaceAll("*/", "* /")}`), " */"].join("\n");
+};
+/** Make sure the string starts with a capital, and all other letters are lowercase */
+export const uncapitalize = str => str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
+/** Helper to use with `Array.sort()` and similar */
+export const alphaSort = (a, b) => a.localeCompare(b);