shelving 1.138.0 → 1.139.1

package/util/base64.js

@@ -1,6 +1,13 @@
+import { ValueError } from "../error/ValueError.js";
 import { requireBytes } from "./bytes.js";
 const BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 const BASE64URL_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+/** Create a reverse lookup table for decoding in { charCode: asciiValue } format. Works for both alphabets. */
+const REVERSE_CHARS = new Uint8Array(128).fill(255);
+for (let i = 0; i < BASE64_CHARS.length; i++) {
+    REVERSE_CHARS[BASE64_CHARS.charCodeAt(i)] = i;
+    REVERSE_CHARS[BASE64URL_CHARS.charCodeAt(i)] = i;
+}
 /**
  * @todo DH: When it's well supported, use `Uint8Array.toBase64()`: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array/toBase64
  */
@@ -20,58 +27,60 @@ function _encode(bytes, alphabet, pad) {
     }
     return output;
 }
-function _decode(base64, alphabet) {
-    // Create a reverse lookup table: char -> 6-bit value
-    const values = new Uint8Array(128);
-    for (let i = 0; i < alphabet.length; i++)
-        values[alphabet.charCodeAt(i)] = i;
+function _decode(base64, caller) {
     // Remove padding.
     const cleaned = base64.replace(/=+$/, "");
     const length = cleaned.length;
     // Calculate output byte length
     // Every 4 base64 chars = 3 bytes; adjust for padding
-    const outputLength = Math.floor((length * 6) / 8);
-    const output = new Uint8Array(outputLength);
+    const byteLength = Math.floor((length * 6) / 8);
+    const bytes = new Uint8Array(byteLength);
     let j = 0;
     for (let i = 0; i < length; i += 4) {
-        // Get 4 characters (or less at the end)
-        const c1 = values[cleaned.charCodeAt(i)];
-        const c2 = values[cleaned.charCodeAt(i + 1)];
-        const c3 = i + 2 < length ? values[cleaned.charCodeAt(i + 2)] : 0;
-        const c4 = i + 3 < length ? values[cleaned.charCodeAt(i + 3)] : 0;
+        const l1 = _lookup(cleaned, i, caller);
+        const l2 = _lookup(cleaned, i + 1, caller);
+        const l3 = i + 2 < length ? _lookup(cleaned, i + 2, caller) : 0;
+        const l4 = i + 3 < length ? _lookup(cleaned, i + 3, caller) : 0;
         // Combine into 24 bits
-        const combined = (c1 << 18) | (c2 << 12) | (c3 << 6) | c4;
+        const combined = (l1 << 18) | (l2 << 12) | (l3 << 6) | l4;
         // Extract bytes and add to output if within range
-        if (j < outputLength)
-            output[j++] = (combined >> 16) & 0xff;
-        if (j < outputLength)
-            output[j++] = (combined >> 8) & 0xff;
-        if (j < outputLength)
-            output[j++] = combined & 0xff;
+        if (j < byteLength)
+            bytes[j++] = (combined >> 16) & 0xff;
+        if (j < byteLength)
+            bytes[j++] = (combined >> 8) & 0xff;
+        if (j < byteLength)
+            bytes[j++] = combined & 0xff;
     }
-    return output;
+    return bytes;
+}
+function _lookup(base64, index, caller) {
+    const code = base64.charCodeAt(index);
+    const value = REVERSE_CHARS[code];
+    if (value === undefined || value === 255)
+        throw new ValueError(`Invalid character "${code}" in Base64 string`, { received: base64, index: index, caller });
+    return value;
 }
 /** Encode a string or binary data to Base64 string. */
 export function encodeBase64(input, pad = true) {
     return _encode(requireBytes(input), BASE64_CHARS, pad ? "=" : "");
 }
-/** Decode Base64 string to string. */
+/** Decode Base64 string to string (decodes Base64URL too). */
 export function decodeBase64String(base64) {
-    return new TextDecoder("utf-8").decode(_decode(base64, BASE64_CHARS));
+    return new TextDecoder("utf-8").decode(_decode(base64, decodeBase64String));
 }
-/** Decode URL-safe Base64 string to binary data (as a UInt8Array). */
+/** Decode URL-safe Base64 string to byte sequence (decodes Base64URL too). */
 export function decodeBase64Bytes(base64) {
-    return _decode(base64, BASE64_CHARS);
+    return _decode(base64, decodeBase64Bytes);
 }
 /** Encode a string or binary data to URL-safe Base64 */
-export function encodeBase64Url(input, pad = false) {
+export function encodeBase64URL(input, pad = false) {
     return _encode(requireBytes(input), BASE64URL_CHARS, pad ? "=" : "");
 }
-/** Decode a string from URL-safe Base64. */
-export function decodeBase64UrlString(base64) {
-    return new TextDecoder("utf-8").decode(_decode(base64, BASE64URL_CHARS));
+/** Decode a string from URL-safe Base64 (decodes Base64 too). */
+export function decodeBase64URLString(base64) {
+    return new TextDecoder("utf-8").decode(_decode(base64, decodeBase64URLString));
 }
-/** Decode URL-safe Base64 string to binary data (as a UInt8Array). */
-export function decodeBase64UrlBytes(base64) {
-    return _decode(base64, BASE64URL_CHARS);
+/** Decode URL-safe Base64 string to byte sequence (decodes Base64 too). */
+export function decodeBase64URLBytes(base64) {
+    return _decode(base64, decodeBase64URLBytes);
 }

package/util/boolean.d.ts

@@ -1,3 +1,4 @@
+import type { AnyCaller } from "../error/BaseError.js";
 /** Is a value a boolean? */
 export declare function isBoolean(value: unknown): value is boolean;
 /** Is a value true? */
@@ -9,12 +10,12 @@ export declare function isTruthy(value: unknown): boolean;
 /** Is a value falsey? */
 export declare function isFalsey(value: unknown): boolean;
 /** Assert that a value is a boolean. */
-export declare function assertBoolean(value: unknown): asserts value is boolean;
+export declare function assertBoolean(value: unknown, caller?: AnyCaller): asserts value is boolean;
 /** Assert that a value is true. */
-export declare function assertTrue(value: unknown): asserts value is true;
+export declare function assertTrue(value: unknown, caller?: AnyCaller): asserts value is true;
 /** Assert that a value is false. */
-export declare function assertFalse(value: unknown): asserts value is false;
+export declare function assertFalse(value: unknown, caller?: AnyCaller): asserts value is false;
 /** Assert that a value is truthy. */
-export declare function assertTruthy(value: unknown): asserts value is true;
+export declare function assertTruthy(value: unknown, caller?: AnyCaller): asserts value is true;
 /** Assert that a value is falsy. */
-export declare function assertFalsy(value: unknown): asserts value is false;
+export declare function assertFalsy(value: unknown, caller?: AnyCaller): asserts value is false;

package/util/boolean.js

@@ -1,4 +1,4 @@
-import { AssertionError } from "../error/AssertionError.js";
+import { RequiredError } from "../error/RequiredError.js";
 /** Is a value a boolean? */
 export function isBoolean(value) {
     return typeof value === "boolean";
@@ -20,27 +20,27 @@ export function isFalsey(value) {
     return !value;
 }
 /** Assert that a value is a boolean. */
-export function assertBoolean(value) {
+export function assertBoolean(value, caller = assertBoolean) {
     if (typeof value !== "boolean")
-        throw new AssertionError("Must be boolean", { received: value, caller: assertBoolean });
+        throw new RequiredError("Must be boolean", { received: value, caller });
 }
 /** Assert that a value is true. */
-export function assertTrue(value) {
+export function assertTrue(value, caller = assertTrue) {
     if (value !== true)
-        throw new AssertionError("Must be true", { received: value, caller: assertTrue });
+        throw new RequiredError("Must be true", { received: value, caller });
 }
 /** Assert that a value is false. */
-export function assertFalse(value) {
+export function assertFalse(value, caller = assertFalse) {
     if (value !== false)
-        throw new AssertionError("Must be false", { received: value, caller: assertFalse });
+        throw new RequiredError("Must be false", { received: value, caller });
 }
 /** Assert that a value is truthy. */
-export function assertTruthy(value) {
+export function assertTruthy(value, caller = assertTruthy) {
     if (!value)
-        throw new AssertionError("Must be truthy", { received: value, caller: assertTruthy });
+        throw new RequiredError("Must be truthy", { received: value, caller });
 }
 /** Assert that a value is falsy. */
-export function assertFalsy(value) {
+export function assertFalsy(value, caller = assertFalsy) {
     if (value)
-        throw new AssertionError("Must be falsy", { received: value, caller: assertFalsy });
+        throw new RequiredError("Must be falsy", { received: value, caller });
 }

package/util/bytes.d.ts

@@ -1,5 +1,8 @@
+import type { AnyCaller } from "../error/BaseError.js";
 /** Types that can be converted to a `Uint8Array` byte sequence. */
 export type PossibleBytes = Uint8Array | ArrayBuffer | string;
+/** Assert that an unknown value is a `Uint8Array` byte sequence. */
+export declare function assertBytes(value: unknown, min?: number, max?: number, caller?: AnyCaller): asserts value is Uint8Array;
 /**
  * Convert an unknown value to a `Uint8Array` byte sequence, or `undefined` if the value cannot be converted.
  *
@@ -9,4 +12,4 @@ export type PossibleBytes = Uint8Array | ArrayBuffer | string;
  */
 export declare function getBytes(value: unknown): Uint8Array | undefined;
 /** Convert an unknown value to a `Uint8Array` byte sequence, or throw `RequiredError` if the value cannot be converted. */
-export declare function requireBytes(value: PossibleBytes): Uint8Array;
+export declare function requireBytes(value: PossibleBytes, min?: number, max?: number, caller?: AnyCaller): Uint8Array;

package/util/bytes.js

@@ -1,4 +1,9 @@
 import { RequiredError } from "../error/RequiredError.js";
+/** Assert that an unknown value is a `Uint8Array` byte sequence. */
+export function assertBytes(value, min = 0, max = Number.POSITIVE_INFINITY, caller = assertBytes) {
+    if (!(value instanceof Uint8Array) || value.length < min || value.length > max)
+        throw new RequiredError(`Value must be byte sequence${min > 0 || max < Number.POSITIVE_INFINITY ? ` with length between ${min} and ${max}` : ""}`, { received: value, caller });
+}
 /**
  * Convert an unknown value to a `Uint8Array` byte sequence, or `undefined` if the value cannot be converted.
  *
@@ -16,9 +21,8 @@ export function getBytes(value) {
     return undefined;
 }
 /** Convert an unknown value to a `Uint8Array` byte sequence, or throw `RequiredError` if the value cannot be converted. */
-export function requireBytes(value) {
+export function requireBytes(value, min = 0, max = Number.POSITIVE_INFINITY, caller = requireBytes) {
     const bytes = getBytes(value);
-    if (bytes === undefined)
-        throw new RequiredError("Value cannot be converted to byte array", { received: value, caller: requireBytes });
+    assertBytes(bytes, min, max, caller);
     return bytes;
 }

package/util/class.js

@@ -1,4 +1,4 @@
-import { AssertionError } from "../error/AssertionError.js";
+import { RequiredError } from "../error/RequiredError.js";
 /** Is a given value a class constructor? */
 export function isConstructor(value) {
     return typeof value === "function" && value.toString().startsWith("class");
@@ -10,7 +10,7 @@ export function isInstance(value, type) {
 /** Assert that a value is an instance of something. */
 export function assertInstance(value, type) {
     if (!(value instanceof type))
-        throw new AssertionError(`Must be instance of class "${type.name}"`, { received: value, expected: type, caller: assertInstance });
+        throw new RequiredError(`Must be instance of class "${type.name}"`, { received: value, expected: type, caller: assertInstance });
 }
 /** Get the 'getter' function for a given property, or `undefined` if it doesn't exist. */
 // biome-ignore lint/complexity/noBannedTypes: This is correct here.

package/util/color.d.ts

@@ -1,3 +1,4 @@
+import type { AnyCaller } from "../error/BaseError.js";
 export declare const HEX3_REGEXP: RegExp;
 export declare const HEX6_REGEXP: RegExp;
 /** Things that can be converted to a `Color` instance. */
@@ -28,8 +29,8 @@ export declare class Color {
 /** Is an unknown value a `Color` instance. */
 export declare function isColor(value: unknown): value is Color;
 /** Assert that an unknown value is a `Color` instance. */
-export declare function assertColor(value: unknown): asserts value is Color;
-/** Convert a possible color to a `Color` instance or `undefined` */
+export declare function assertColor(value: unknown, caller?: AnyCaller): asserts value is Color;
+/** Convert an unknown value to a `Color` instance, or return `undefined` if conversion fails. */
 export declare function getColor(value: unknown): Color | undefined;
 /** Convert a possible color to a `Color` instance, or throw `RequiredError` if it can't be converted. */
-export declare function requireColor(value: PossibleColor): Color;
+export declare function requireColor(value: PossibleColor, caller?: AnyCaller): Color;

package/util/color.js

@@ -69,18 +69,17 @@ export function isColor(value) {
     return value instanceof Color;
 }
 /** Assert that an unknown value is a `Color` instance. */
-export function assertColor(value) {
+export function assertColor(value, caller = assertColor) {
     if (!isColor(value))
-        throw new RequiredError("Must be color", { received: value, caller: assertColor });
+        throw new RequiredError("Must be color", { received: value, caller });
 }
-/** Convert a possible color to a `Color` instance or `undefined` */
+/** Convert an unknown value to a `Color` instance, or return `undefined` if conversion fails. */
 export function getColor(value) {
     return Color.from(value);
 }
 /** Convert a possible color to a `Color` instance, or throw `RequiredError` if it can't be converted. */
-export function requireColor(value) {
+export function requireColor(value, caller = requireColor) {
     const color = getColor(value);
-    if (!color)
-        throw new RequiredError("Invalid color", { received: value, caller: requireColor });
+    assertColor(color, requireColor);
     return color;
 }

package/util/crypto.d.ts

@@ -0,0 +1,21 @@
+/** Get random bytes from the crypto API. */
+export declare function getRandomBytes(length: number): Uint8Array;
+/**
+ * Hash a password using PBKDF2, generating a new salt, and return the combined salt$iterations$hash string.
+ *
+ * @param password The password to hash.
+ * @param iterations The number of iterations.
+ *
+ * @returns Hash in the format `salt$iterations$hash`, where `salt` and `hash` are base64-encoded.
+ * - Returned hash tring will be about 128 characters long (16 byte salt + iteration count + 64 byte hash + 2 separators = 116 characters once base64 encoded).
+ */
+export declare function hashPassword(password: string, iterations?: number): Promise<string>;
+/**
+ * Verify a password against a stored salt$iterations$hash string using PBKDF2.
+ *
+ * @param password The password to verify.
+ * @param hash String in the format `salt$iterations$hash`, where `salt` and `hash` are base64-encoded.
+ *
+ * @returns True if the password matches the hash, false otherwise.
+ */
+export declare function verifyPassword(password: string, hash: string): Promise<boolean>;

package/util/crypto.js

@@ -0,0 +1,80 @@
+import { ValueError } from "../error/ValueError.js";
+import { decodeBase64URLBytes, encodeBase64URL } from "./base64.js";
+import { requireBytes } from "./bytes.js";
+// Constants.
+const ALGORITHM = { name: "PBKDF2", hash: "SHA-512" };
+const ITERATIONS = 500000;
+const SALT_LENGTH = 16; // 16 bytes = 128 bits
+const HASH_LENGTH = 64; // 64 bytes = 512 bits
+const PASSWORD_LENGTH = 6;
+/** Import a key for PBKDF2 operations (deriveBits) using SHA-512. */
+function _getKey(password) {
+    return crypto.subtle.importKey("raw", requireBytes(password), ALGORITHM, false, ["deriveBits"]);
+}
+/** Get random bytes from the crypto API. */
+export function getRandomBytes(length) {
+    const bytes = new Uint8Array(length);
+    crypto.getRandomValues(bytes);
+    return bytes;
+}
+/**
+ * Hash a password using PBKDF2, generating a new salt, and return the combined salt$iterations$hash string.
+ *
+ * @param password The password to hash.
+ * @param iterations The number of iterations.
+ *
+ * @returns Hash in the format `salt$iterations$hash`, where `salt` and `hash` are base64-encoded.
+ * - Returned hash tring will be about 128 characters long (16 byte salt + iteration count + 64 byte hash + 2 separators = 116 characters once base64 encoded).
+ */
+export async function hashPassword(password, iterations = ITERATIONS) {
+    // Checks.
+    if (password.length < PASSWORD_LENGTH)
+        throw new ValueError(`Password must be at least ${PASSWORD_LENGTH} characters long`, {
+            received: password.length,
+            caller: hashPassword,
+        });
+    if (iterations < 1)
+        throw new ValueError("Iterations must be number greater than 0", { received: iterations, caller: hashPassword });
+    // Hash the password.
+    const key = await _getKey(password);
+    const salt = getRandomBytes(SALT_LENGTH);
+    const bits = HASH_LENGTH * 8;
+    const hash = await crypto.subtle.deriveBits({ ...ALGORITHM, salt, iterations }, key, bits);
+    // Return the combined string
+    return `${encodeBase64URL(salt)}$${iterations}$${encodeBase64URL(hash)}`;
+}
+/**
+ * Verify a password against a stored salt$iterations$hash string using PBKDF2.
+ *
+ * @param password The password to verify.
+ * @param hash String in the format `salt$iterations$hash`, where `salt` and `hash` are base64-encoded.
+ *
+ * @returns True if the password matches the hash, false otherwise.
+ */
+export async function verifyPassword(password, hash) {
+    // Check salthash.
+    const [s, i, h] = hash.split("$");
+    if (!s || !i || !h)
+        return false;
+    const hashBytes = decodeBase64URLBytes(h);
+    // Check iterations.
+    const iterations = Number.parseInt(i, 10);
+    if (!Number.isFinite(iterations) || iterations < 1)
+        return false;
+    // Derive the hash.
+    const key = await _getKey(password);
+    const salt = decodeBase64URLBytes(s);
+    const bits = hashBytes.length * 8;
+    const derivedBytes = new Uint8Array(await crypto.subtle.deriveBits({ ...ALGORITHM, salt, iterations }, key, bits));
+    // Compare the derived hash with the stored hash.
+    return _compareBytes(derivedBytes, hashBytes);
+}
+/** Compare two sets of bytes using constant time comparison. */
+function _compareBytes(left, right) {
+    if (left.length !== right.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < left.length; ++i)
+        result |= left[i] ^ right[i];
+    return result === 0;
+}

package/util/data.d.ts

@@ -1,3 +1,4 @@
+import type { AnyCaller } from "../error/BaseError.js";
 import type { ImmutableArray } from "./array.js";
 import type { EntryObject } from "./entry.js";
 import type { DeepPartial } from "./object.js";
@@ -46,14 +47,14 @@ export type LeafProp<T extends Data> = {
 /** Is an unknown value a data object? */
 export declare function isData(value: unknown): value is Data;
 /** Assert that an unknown value is a data object. */
-export declare function assertData(value: unknown): asserts value is Data;
-/** Is an unknown value the key for an own prop of a data object. */
-export declare const isDataProp: <T extends Data>(data: T, key: unknown) => key is DataKey<T>;
-/** Assert that an unknown value is the key for an own prop of a data object. */
-export declare function assertDataProp<T extends Data>(data: T, key: unknown): asserts key is DataKey<T>;
+export declare function assertData(value: unknown, caller?: AnyCaller): asserts value is Data;
 /** Convert a data object or set of `DataProp` props for that object back into the full object. */
 export declare function getData<T extends Data>(input: T): T;
 export declare function getData<T extends Data>(input: T | Iterable<DataProp<T>>): Partial<T>;
+/** Is an unknown value the key for an own prop of a data object. */
+export declare const isDataProp: <T extends Data>(data: T, key: unknown) => key is DataKey<T>;
+/** Assert that an unknown value is the key for an own prop of a data object. */
+export declare function assertDataProp<T extends Data>(data: T, key: unknown, caller?: AnyCaller): asserts key is DataKey<T>;
 /** Get the props of a data object as a set of entries. */
 export declare function getDataProps<T extends Data>(data: T): ImmutableArray<DataProp<T>>;
 export declare function getDataProps<T extends Data>(data: T | Partial<T>): ImmutableArray<DataProp<T>>;
@@ -64,11 +65,3 @@ export declare function getDataKeys<T extends Data>(data: T | Partial<T>): Immut
 export declare function getDataProp<T extends Data, K extends BranchKey<T> = BranchKey<T>>(data: T, key: K): BranchData<T>[K];
 export declare function getDataProp<T extends Data, K extends BranchKey<T> = BranchKey<T>>(data: DeepPartial<T>, key: K): BranchData<T>[K] | undefined;
 export declare function getDataProp(data: Data, key: string): unknown;
-/** Type that represents an empty data object. */
-export type EmptyData = {
-    readonly [K in never]: never;
-};
-/** An empty object. */
-export declare const EMPTY_DATA: EmptyData;
-/** Function that returns an an empty object. */
-export declare const getEmptyData: () => EmptyData;

package/util/data.js

@@ -1,4 +1,4 @@
-import { AssertionError } from "../error/AssertionError.js";
+import { RequiredError } from "../error/RequiredError.js";
 import { isIterable } from "./iterate.js";
 import { isObject, isPlainObject } from "./object.js";
 /** Is an unknown value a data object? */
@@ -6,19 +6,19 @@ export function isData(value) {
     return isPlainObject(value);
 }
 /** Assert that an unknown value is a data object. */
-export function assertData(value) {
+export function assertData(value, caller = assertData) {
     if (!isPlainObject(value))
-        throw new AssertionError("Must be data object", { received: value, caller: assertData });
+        throw new RequiredError("Must be data object", { received: value, caller });
+}
+export function getData(input) {
+    return isIterable(input) ? Object.fromEntries(input) : input;
 }
 /** Is an unknown value the key for an own prop of a data object. */
 export const isDataProp = (data, key) => typeof key === "string" && Object.hasOwn(data, key);
 /** Assert that an unknown value is the key for an own prop of a data object. */
-export function assertDataProp(data, key) {
+export function assertDataProp(data, key, caller = assertDataProp) {
     if (!isDataProp(data, key))
-        throw new AssertionError("Key must exist in data object", { key, data, caller: assertDataProp });
-}
-export function getData(input) {
-    return isIterable(input) ? Object.fromEntries(input) : input;
+        throw new RequiredError("Key must exist in data object", { key, data, caller });
 }
 export function getDataProps(data) {
     return Object.entries(data);
@@ -35,7 +35,3 @@ export function getDataProp(data, key) {
     }
     return current;
 }
-/** An empty object. */
-export const EMPTY_DATA = { __proto__: null };
-/** Function that returns an an empty object. */
-export const getEmptyData = () => EMPTY_DATA;

package/util/date.d.ts

@@ -1,10 +1,13 @@
-import type { AnyFunction } from "./function.js";
-/** Things that converted to dates. */
+import type { AnyCaller } from "../error/BaseError.js";
+/** Values that can be converted to dates. */
 export type PossibleDate = "now" | "today" | "tomorrow" | "yesterday" | Date | number | string;
-/** Is a value a date? */
+/**
+ * Is a value a valid date?
+ * - Note: `Date` instances can be invalid (e.g. `new Date("blah blah").getTime()` returns `NaN`). These are detected and will always return `false`
+ */
 export declare function isDate(value: unknown): value is Date;
 /** Assert that a value is a `Date` instance. */
-export declare function assertDate(value: unknown): asserts value is Date;
+export declare function assertDate(value: unknown, caller?: AnyCaller): asserts value is Date;
 /**
  * Convert an unknown value to a valid `Date` instance, or return `undefined` if it couldn't be converted.
  * - Note: `Date` instances can be invalid (e.g. `new Date("blah blah").getTime()` returns `NaN`). These are detected and will always return `null`
@@ -20,24 +23,31 @@ export declare function assertDate(value: unknown): asserts value is Date;
  * - Numbers are return the corresponding date (using `new Date(number)`, i.e. milliseconds since 01/01/1970).
  * - Anything else returns `undefined`
  *
- * @param possible Any value that we want to parse as a valid date (defaults to `undefined`).
+ * @param value Any value that we want to parse as a valid date (defaults to `undefined`).
  * @returns `Date` instance if the value could be converted to a valid date, and `null` if not.
  */
-export declare function getDate(possible: unknown): Date | undefined;
+export declare function getDate(value: unknown): Date | undefined;
+/** Get a date representing this exact moment. */
+export declare function getNow(): Date;
+/** Get a date representing midnight of the previous day. */
+export declare function getYesterday(): Date;
+/** Get a date representing midnight of the current day. */
+export declare function getToday(): Date;
+/** Get a date representing midnight of the next day. */
+export declare function getTomorrow(): Date;
 /**
  * Convert a possible date to a `Date` instance, or throw `RequiredError` if it couldn't be converted.
- * @param possible Any value that we want to parse as a valid date (defaults to `"now"`).
+ * @param value Any value that we want to parse as a valid date (defaults to `"now"`).
  */
-export declare function requireDate(possible?: PossibleDate): Date;
-export declare function _date(caller: AnyFunction, possible?: PossibleDate): Date;
+export declare function requireDate(value?: PossibleDate, caller?: AnyCaller): Date;
 /** Convert an unknown value to a timestamp (milliseconds past Unix epoch), or `undefined` if it couldn't be converted. */
-export declare function getTimestamp(possible?: unknown): number | undefined;
+export declare function getTimestamp(value?: unknown): number | undefined;
 /** Convert a possible date to a timestamp (milliseconds past Unix epoch), or throw `RequiredError` if it couldn't be converted. */
-export declare function requireTimestamp(possible?: PossibleDate): number;
+export declare function requireTimestamp(value?: PossibleDate): number;
 /** Convert an unknown value to a YMD date string like "2015-09-12", or `undefined` if it couldn't be converted. */
-export declare function getYMD(possible?: unknown): string | undefined;
+export declare function getYMD(value?: unknown): string | undefined;
 /** Convert a `Date` instance to a YMD string like "2015-09-12", or throw `RequiredError` if it couldn't be converted.  */
-export declare function requireYMD(possible?: PossibleDate): string;
+export declare function requireYMD(value?: PossibleDate, caller?: AnyCaller): string;
 /** List of day-of-week strings. */
 export declare const DAYS: readonly ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
 /** Type listing day-of-week strings. */
@@ -45,9 +55,9 @@ export type Day = (typeof DAYS)[number];
 /** Convert a `Date` instance to a day-of-week string like "monday" */
 export declare function getDay(target?: PossibleDate): Day;
 /** Get a Date representing exactly midnight of the specified date. */
-export declare function getMidnight(target?: PossibleDate): Date;
+export declare function getMidnight(target?: PossibleDate, caller?: AnyCaller): Date;
 /** Get a Date representing midnight on Monday of the specified week. */
-export declare function getMonday(target?: PossibleDate): Date;
+export declare function getMonday(target?: PossibleDate, caller?: AnyCaller): Date;
 /** Return a new date that increase or decreases the number of days based on an input date. */
 export declare function addDays(change: number, target?: PossibleDate): Date;
 /** Return a new date that increase or decreases the number of hours based on an input date. */
@@ -58,27 +68,25 @@ export declare function addHours(change: number, target?: PossibleDate): Date;
  * @param target The date when the thing will happen or did happen.
  * @param current Today's date (or a different date to measure from).
  */
-export declare function getMillisecondsUntil(target: PossibleDate, current?: PossibleDate): number;
+export declare function getMillisecondsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /** Count the number of seconds until a date. */
-export declare function getSecondsUntil(target: PossibleDate, current?: PossibleDate): number;
+export declare function getSecondsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /** Count the number of days ago a date was. */
-export declare function getSecondsAgo(target: PossibleDate, current?: PossibleDate): number;
+export declare function getSecondsAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /** Count the number of days until a date. */
-export declare function getDaysUntil(target: PossibleDate, current?: PossibleDate): number;
+export declare function getDaysUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /** Count the number of days ago a date was. */
-export declare function getDaysAgo(target: PossibleDate, current?: PossibleDate): number;
+export declare function getDaysAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /** Count the number of weeks until a date. */
-export declare function getWeeksUntil(target: PossibleDate, current?: PossibleDate): number;
+export declare function getWeeksUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /** Count the number of weeks ago a date was. */
-export declare function getWeeksAgo(target: PossibleDate, current?: PossibleDate): number;
+export declare function getWeeksAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /** Is a date in the past? */
-export declare function isPast(target: PossibleDate, current?: PossibleDate): boolean;
+export declare function isPast(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
 /** Is a date in the future? */
-export declare function isFuture(target: PossibleDate, current?: PossibleDate): boolean;
+export declare function isFuture(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
 /** Is a date today (taking into account midnight). */
-export declare function isToday(target: PossibleDate, current?: PossibleDate): boolean;
-/** Format a date in the browser locale. */
-export declare function formatDate(date?: PossibleDate): string;
+export declare function isToday(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
 /** Compact when a date happens/happened, e.g. `in 10d` or `2h ago` or `in 1w` or `just now` */
 export declare function formatWhen(target: PossibleDate, current?: PossibleDate, options?: Intl.NumberFormatOptions): string;
 /** Compact when a date happens, e.g. `10d` or `2h` or `-1w` */