@mll-lab/js-utils 2.39.0 → 2.41.0

package/dist/array.d.ts

@@ -65,9 +65,9 @@ export declare function makeBooleanCompareFn<TSortable>(map: (sortable: TSortabl
  * Takes a function that maps the values to sort to Dates and returns a compare function
  * using their timestamps, usable in `Array.toSorted` or similar APIs.
  *
- * null and undefined are coalesced to 0 and thus not distinguished and first in sort order.
+ * null and undefined are coalesced to the oldest possible date and thus not distinguished and first in sort order.
  */
-export declare function makeDateCompareFn<TSortable>(map: (sortable: TSortable) => Maybe<Date>): (a: TSortable, b: TSortable) => number;
+export declare function makeDateCompareFn<TSortable>(map: (sortable: TSortable) => Maybe<Date>, fallbackValue?: Date): (a: TSortable, b: TSortable) => number;
 /**
  * Returns a compare function for values that are string, null or undefined,
  * using `String.prototype.localeCompare`, usable in `Array.toSorted` or similar APIs.

package/dist/assert.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Asserts that a value is a string at runtime.
+ * Throws an error if the value is not a string.
+ *
+ * Use this function instead of unsafe type casts like `as string` when you need
+ * to ensure a value is actually a string at runtime.
+ *
+ * @param value - The value to check
+ * @returns The value as a string if it passes the check
+ * @throws Error if the value is not a string
+ *
+ * @example
+ * const id = assertString(someUnknownValue);
+ * // Now id is safely typed as string and verified at runtime
+ */
+export declare function assertString(value: unknown): string;

package/dist/assert.test.d.ts

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

package/dist/index.common.js

@@ -9598,10 +9598,13 @@ function makeBooleanCompareFn(map) {
  * Takes a function that maps the values to sort to Dates and returns a compare function
  * using their timestamps, usable in `Array.toSorted` or similar APIs.
  *
- * null and undefined are coalesced to 0 and thus not distinguished and first in sort order.
+ * null and undefined are coalesced to the oldest possible date and thus not distinguished and first in sort order.
  */
-function makeDateCompareFn(map) {
-    return makeNumberCompareFn((sortable) => { var _a; return (_a = map(sortable)) === null || _a === void 0 ? void 0 : _a.getTime(); });
+function makeDateCompareFn(map, 
+// See https://stackoverflow.com/a/11526569 for an explanation of this value.
+fallbackValue = new Date(-8640000000000000)) {
+    const fallbackTime = fallbackValue.getTime();
+    return makeNumberCompareFn((sortable) => { var _a, _b; return (_b = (_a = map(sortable)) === null || _a === void 0 ? void 0 : _a.getTime()) !== null && _b !== void 0 ? _b : fallbackTime; });
 }
 /**
  * Returns a compare function for values that are string, null or undefined,
@@ -9620,6 +9623,28 @@ function soleItem(array) {
     return array[0];
 }
 
+/**
+ * Asserts that a value is a string at runtime.
+ * Throws an error if the value is not a string.
+ *
+ * Use this function instead of unsafe type casts like `as string` when you need
+ * to ensure a value is actually a string at runtime.
+ *
+ * @param value - The value to check
+ * @returns The value as a string if it passes the check
+ * @throws Error if the value is not a string
+ *
+ * @example
+ * const id = assertString(someUnknownValue);
+ * // Now id is safely typed as string and verified at runtime
+ */
+function assertString(value) {
+    if (typeof value !== 'string') {
+        throw new Error(`Expected a string, but got ${typeof value}`);
+    }
+    return value;
+}
+
 /**
  * @name toDate
  * @category Common Helpers
@@ -16303,6 +16328,7 @@ exports.GERMAN_THOUSAND_SEPARATOR = GERMAN_THOUSAND_SEPARATOR;
 exports.ISO_DATE_FORMAT = ISO_DATE_FORMAT;
 exports.ISO_DATE_TIME_FORMAT = ISO_DATE_TIME_FORMAT;
 exports.SECONDLESS_DATE_TIME_FORMAT = SECONDLESS_DATE_TIME_FORMAT;
+exports.assertString = assertString;
 exports.callSequentially = callSequentially;
 exports.ceil = ceil;
 exports.containSameValues = containSameValues;