@keeex/utils 7.5.0 → 7.6.1

package/lib/array.d.ts

@@ -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 type { Arrayable } from "./types/array.js";
 export type EqualityFunction<T1, T2> = (op1: T1, op2: T2) => boolean;
 /**
  * Compare two array-like structure for equal content
@@ -25,4 +26,6 @@ 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>;
+export declare const asArray: <T>(data: Arrayable<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
@@ -33,4 +34,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/lib/async/deferredpromise.d.ts

@@ -17,6 +17,8 @@
  * Allows returning a promise and resolving it in another scope
  *
  * @public
+ *
+ * @deprecated Use `Promise.withResolvers()`
  */
 export declare class DeferredPromise<ResultType> {
     #private;

package/lib/async/deferredpromise.js

@@ -19,6 +19,8 @@
  * Allows returning a promise and resolving it in another scope
  *
  * @public
+ *
+ * @deprecated Use `Promise.withResolvers()`
  */
 export class DeferredPromise {
     /** The actual promise that can be awaited */

package/lib/bits/hex.d.ts

@@ -13,5 +13,12 @@
  * 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.
  * 
  */
-/** Clean an hex string input; make it even and remove 0x prefix if present */
+/** Remove the 0x prefix if present. */
+export declare const getHexNoPrefix: (input: string) => string;
+/** Ensure that the input is a valid hexadecimal string (only allow `[0-9a-fA-F]`) */
+export declare const isHexString: (input: string) => boolean;
+/**
+ * Clean an hex string input; make it even and remove 0x prefix if present.
+ * Also convert it to lowercase and check if the input is actually an hexadecimal string.
+ */
 export declare const clearHexInput: (input: string) => string;

package/lib/bits/hex.js

@@ -16,15 +16,33 @@
 const CHARACTER_PER_BYTE = 2;
 const HEX_PREFIX = "0x";
 const HEX_PREFIX_LENGTH = HEX_PREFIX.length;
-/** Clean an hex string input; make it even and remove 0x prefix if present */
+/** Remove the 0x prefix if present. */
+export const getHexNoPrefix = (input) => input.startsWith(HEX_PREFIX) ? input.substring(HEX_PREFIX_LENGTH) : input;
+const HEX_RANGES_NUMBERS = { min: "0".charCodeAt(0), max: "9".charCodeAt(0) };
+const HEX_RANGES_LOWERCASE = { min: "a".charCodeAt(0), max: "f".charCodeAt(0) };
+const HEX_RANGES_UPPERCASE = { min: "A".charCodeAt(0), max: "F".charCodeAt(0) };
+/** Ensure that the input is a valid hexadecimal string (only allow `[0-9a-fA-F]`) */
+export const isHexString = (input) => {
+    for (let i = 0; i < input.length; ++i) {
+        const charCode = input.charCodeAt(i);
+        if ((charCode < HEX_RANGES_NUMBERS.min || charCode > HEX_RANGES_NUMBERS.max) &&
+            (charCode < HEX_RANGES_LOWERCASE.min || charCode > HEX_RANGES_LOWERCASE.max) &&
+            (charCode < HEX_RANGES_UPPERCASE.min || charCode > HEX_RANGES_UPPERCASE.max)) {
+            return false;
+        }
+    }
+    return true;
+};
+/**
+ * Clean an hex string input; make it even and remove 0x prefix if present.
+ * Also convert it to lowercase and check if the input is actually an hexadecimal string.
+ */
 export const clearHexInput = (input) => {
-    const noprefix = !input.startsWith(HEX_PREFIX);
+    const withoutPrefix = getHexNoPrefix(input);
+    if (!isHexString(withoutPrefix))
+        throw new Error("Input is not a valid hexadecimal string");
     const even = input.length % CHARACTER_PER_BYTE === 0;
-    if (noprefix && even)
-        return input;
-    if (noprefix)
-        return `0${input}`;
     if (even)
-        return input.substring(HEX_PREFIX_LENGTH);
-    return `0${input.substring(HEX_PREFIX_LENGTH)}`;
+        return withoutPrefix.toLowerCase();
+    return `0${withoutPrefix.toLowerCase()}`;
 };

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.1","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.5.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

@@ -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 type { Arrayable } from "./types/array.js";
 export type EqualityFunction<T1, T2> = (op1: T1, op2: T2) => boolean;
 /**
  * Compare two array-like structure for equal content
@@ -25,4 +26,6 @@ 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>;
+export declare const asArray: <T>(data: Arrayable<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/async/deferredpromise.d.ts

@@ -17,6 +17,8 @@
  * Allows returning a promise and resolving it in another scope
  *
  * @public
+ *
+ * @deprecated Use `Promise.withResolvers()`
  */
 export declare class DeferredPromise<ResultType> {
     #private;

package/web/async/deferredpromise.js

@@ -19,6 +19,8 @@
  * Allows returning a promise and resolving it in another scope
  *
  * @public
+ *
+ * @deprecated Use `Promise.withResolvers()`
  */
 export class DeferredPromise {
   /** The actual promise that can be awaited */

package/web/bits/hex.d.ts

@@ -13,5 +13,12 @@
  * 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.
  * 
  */
-/** Clean an hex string input; make it even and remove 0x prefix if present */
+/** Remove the 0x prefix if present. */
+export declare const getHexNoPrefix: (input: string) => string;
+/** Ensure that the input is a valid hexadecimal string (only allow `[0-9a-fA-F]`) */
+export declare const isHexString: (input: string) => boolean;
+/**
+ * Clean an hex string input; make it even and remove 0x prefix if present.
+ * Also convert it to lowercase and check if the input is actually an hexadecimal string.
+ */
 export declare const clearHexInput: (input: string) => string;

package/web/bits/hex.js

@@ -16,12 +16,38 @@
 const CHARACTER_PER_BYTE = 2;
 const HEX_PREFIX = "0x";
 const HEX_PREFIX_LENGTH = HEX_PREFIX.length;
-/** Clean an hex string input; make it even and remove 0x prefix if present */
+/** Remove the 0x prefix if present. */
+export const getHexNoPrefix = input => input.startsWith(HEX_PREFIX) ? input.substring(HEX_PREFIX_LENGTH) : input;
+const HEX_RANGES_NUMBERS = {
+  min: "0".charCodeAt(0),
+  max: "9".charCodeAt(0)
+};
+const HEX_RANGES_LOWERCASE = {
+  min: "a".charCodeAt(0),
+  max: "f".charCodeAt(0)
+};
+const HEX_RANGES_UPPERCASE = {
+  min: "A".charCodeAt(0),
+  max: "F".charCodeAt(0)
+};
+/** Ensure that the input is a valid hexadecimal string (only allow `[0-9a-fA-F]`) */
+export const isHexString = input => {
+  for (let i = 0; i < input.length; ++i) {
+    const charCode = input.charCodeAt(i);
+    if ((charCode < HEX_RANGES_NUMBERS.min || charCode > HEX_RANGES_NUMBERS.max) && (charCode < HEX_RANGES_LOWERCASE.min || charCode > HEX_RANGES_LOWERCASE.max) && (charCode < HEX_RANGES_UPPERCASE.min || charCode > HEX_RANGES_UPPERCASE.max)) {
+      return false;
+    }
+  }
+  return true;
+};
+/**
+ * Clean an hex string input; make it even and remove 0x prefix if present.
+ * Also convert it to lowercase and check if the input is actually an hexadecimal string.
+ */
 export const clearHexInput = input => {
-  const noprefix = !input.startsWith(HEX_PREFIX);
+  const withoutPrefix = getHexNoPrefix(input);
+  if (!isHexString(withoutPrefix)) throw new Error("Input is not a valid hexadecimal string");
   const even = input.length % CHARACTER_PER_BYTE === 0;
-  if (noprefix && even) return input;
-  if (noprefix) return `0${input}`;
-  if (even) return input.substring(HEX_PREFIX_LENGTH);
-  return `0${input.substring(HEX_PREFIX_LENGTH)}`;
+  if (even) return withoutPrefix.toLowerCase();
+  return `0${withoutPrefix.toLowerCase()}`;
 };

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);