shelving 1.115.0 → 1.116.0

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.115.0",
+	"version": "1.116.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",

package/schema/DateSchema.d.ts

@@ -1,17 +1,18 @@
 import type { SchemaOptions } from "./Schema.js";
-import type { PossibleDate, PossibleOptionalDate } from "../util/date.js";
+import type { PossibleDate } from "../util/date.js";
+import type { Optional } from "../util/optional.js";
 import { Schema } from "./Schema.js";
 /** Allowed options for `DateSchema` */
 export type DateSchemaOptions = SchemaOptions & {
     readonly value?: PossibleDate | undefined;
-    readonly min?: PossibleOptionalDate | undefined;
-    readonly max?: PossibleOptionalDate | undefined;
+    readonly min?: Optional<PossibleDate> | undefined;
+    readonly max?: Optional<PossibleDate> | undefined;
 };
 /** Define a valid date in YMD format, e.g. `2005-09-12` */
 export declare class DateSchema extends Schema<string> {
     readonly value: PossibleDate;
-    readonly min: Date | null;
-    readonly max: Date | null;
+    readonly min: Date | undefined;
+    readonly max: Date | undefined;
     constructor(options: DateSchemaOptions);
     validate(unsafeValue?: unknown): string;
 }

package/schema/LinkSchema.d.ts

@@ -1,9 +1,10 @@
 import type { StringSchemaOptions } from "./StringSchema.js";
+import type { ImmutableArray } from "../util/array.js";
 import { StringSchema } from "./StringSchema.js";
 /** Allowed options for `LinkSchema` */
 export type LinkSchemaOptions = Omit<StringSchemaOptions, "type" | "min" | "max" | "multiline"> & {
-    readonly schemes?: string[] | undefined;
-    readonly hosts?: string[] | undefined;
+    readonly schemes?: ImmutableArray<string> | undefined;
+    readonly hosts?: ImmutableArray<string> | undefined;
 };
 /**
  * Type of `StringSchema` that defines a valid URL.
@@ -12,8 +13,8 @@ export type LinkSchemaOptions = Omit<StringSchemaOptions, "type" | "min" | "max"
  * - Falsy values are converted to `""` empty string.
  */
 export declare class LinkSchema extends StringSchema {
-    readonly schemes: string[];
-    readonly hosts: string[] | undefined;
+    readonly schemes: ImmutableArray<string>;
+    readonly hosts: ImmutableArray<string> | undefined;
     constructor(options: LinkSchemaOptions);
     validate(unsafeValue: unknown): string;
 }

package/schema/NumberSchema.d.ts

@@ -5,14 +5,14 @@ export type NumberSchemaOptions = SchemaOptions & {
     readonly value?: number | undefined;
     readonly min?: number | undefined;
     readonly max?: number | undefined;
-    readonly step?: number | null | undefined;
+    readonly step?: number | undefined;
 };
 /** Schema that defines a valid number. */
 export declare class NumberSchema extends Schema<number> {
     readonly value: number;
     readonly min: number;
     readonly max: number;
-    readonly step: number | null;
+    readonly step: number | undefined;
     constructor(options: NumberSchemaOptions);
     validate(unsafeValue?: unknown): number;
 }

package/schema/NumberSchema.js

@@ -9,7 +9,7 @@ export class NumberSchema extends Schema {
     step;
     constructor(options) {
         super({ title: "Number", value: 0, ...options });
-        const { min = -Infinity, max = Infinity, step = null } = options;
+        const { min = -Infinity, max = Infinity, step } = options;
         this.min = min;
         this.max = max;
         this.step = step;

package/schema/TimeSchema.d.ts

@@ -1,24 +1,25 @@
 import type { SchemaOptions } from "./Schema.js";
-import type { PossibleOptionalTime, PossibleTime } from "../util/time.js";
+import type { Optional } from "../util/optional.js";
+import type { PossibleTime } from "../util/time.js";
 import { Time } from "../util/time.js";
 import { Schema } from "./Schema.js";
 /** Allowed options for `TimeSchama` */
 export type TimeSchemaOptions = SchemaOptions & {
     readonly value?: PossibleTime | undefined;
-    readonly min?: PossibleOptionalTime | undefined;
-    readonly max?: PossibleOptionalTime | undefined;
-    readonly step?: number | null | undefined;
+    readonly min?: Optional<PossibleTime> | undefined;
+    readonly max?: Optional<PossibleTime> | undefined;
+    readonly step?: number | undefined;
 };
 /** Define a valid time in 24h hh:mm:ss.fff format, e.g. `23:59` or `24:00 */
 export declare class TimeSchema extends Schema<string> {
     readonly value: PossibleTime;
-    readonly min: Time | null;
-    readonly max: Time | null;
+    readonly min: Time | undefined;
+    readonly max: Time | undefined;
     /**
      * Rounding step (in milliseconds, because that's the base unit for time), e.g. `60000` will round to the nearest second.
      * - Note: `<input type="time">` elements expect `step=""` to be  in _seconds_ so you need to multiply this by `1000`
      */
-    readonly step: number | null;
+    readonly step: number | undefined;
     constructor(options: TimeSchemaOptions);
     validate(unsafeValue?: unknown): string;
 }

package/store/PathStore.d.ts

@@ -3,12 +3,12 @@ import type { PossibleStarter } from "../util/start.js";
 import { Store } from "./Store.js";
 /** Store an absolute path, e.g. `/a/b/c` */
 export declare class PathStore extends Store<AbsolutePath> {
-    constructor(path?: AbsolutePath, time?: number, start?: PossibleStarter<[Store<AbsolutePath>]>);
+    constructor(path?: string, time?: number, start?: PossibleStarter<[Store<AbsolutePath>]>);
     /** Based on the current store path, is a path active? */
     isActive(path: AbsolutePath): boolean;
     /** Based on the current store path, is a path proud (i.e. a child of the current store path)? */
     isProud(path: AbsolutePath): boolean;
-    /** Get an absolute path from a path relative to the current navigation path. */
-    getAbsolute(path: string): AbsolutePath;
+    /** Get an absolute path from a path relative to the current store path. */
+    getPath(path: string): AbsolutePath;
     set(path: string): void;
 }

package/store/PathStore.js

@@ -2,8 +2,8 @@ import { getPath, isPathActive, isPathProud } from "../util/path.js";
 import { Store } from "./Store.js";
 /** Store an absolute path, e.g. `/a/b/c` */
 export class PathStore extends Store {
-    constructor(path = window.location.pathname, time, start) {
-        super(path, time, start);
+    constructor(path = ".", time, start) {
+        super(getPath(path), time, start);
     }
     /** Based on the current store path, is a path active? */
     isActive(path) {
@@ -13,8 +13,8 @@ export class PathStore extends Store {
     isProud(path) {
         return isPathProud(path, this.value);
     }
-    /** Get an absolute path from a path relative to the current navigation path. */
-    getAbsolute(path) {
+    /** Get an absolute path from a path relative to the current store path. */
+    getPath(path) {
         return getPath(path, this.value);
     }
     // Override to clean the path.

package/util/color.d.ts

@@ -2,11 +2,10 @@ export declare const HEX3_REGEXP: RegExp;
 export declare const HEX6_REGEXP: RegExp;
 /** Things that can be converted to a `Color` instance. */
 export type PossibleColor = Color | string;
-export type PossibleOptionalColor = PossibleColor | null;
 /** Represent a color. */
 export declare class Color {
-    /** Make a `Color` from a 3 or 6 or 8 byte hex string. */
-    static fromHex(str: string): Color | null;
+    /** Make a `Color` from an unknown value. */
+    static from(possible: unknown): Color | undefined;
     readonly r: number;
     readonly g: number;
     readonly b: number;
@@ -30,7 +29,7 @@ export declare class Color {
 export declare const 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 `null` */
-export declare function getOptionalColor(possible: unknown): Color | null;
+/** Convert a possible color to a `Color` instance or `undefined` */
+export declare function getOptionalColor(possible: unknown): Color | undefined;
 /** Convert a possible color to a `Color` instance */
 export declare function getColor(possible: PossibleColor): Color;

package/util/color.js

@@ -7,13 +7,17 @@ export const HEX3_REGEXP = /^#?([0-F])([0-F])([0-F])$/i;
 export const HEX6_REGEXP = /^#?([0-F]{2})([0-F]{2})([0-F]{2})([0-F]{2})?$/i;
 /** Represent a color. */
 export class Color {
-    /** Make a `Color` from a 3 or 6 or 8 byte hex string. */
-    static fromHex(str) {
-        const matches = (str.match(HEX3_REGEXP) || str.match(HEX6_REGEXP));
-        if (!matches)
-            return null;
-        const [, r, g, b, a] = matches;
-        return new Color(_parse(r), _parse(g), _parse(b), typeof a === "string" ? _parse(a) : undefined);
+    /** Make a `Color` from an unknown value. */
+    static from(possible) {
+        if (isColor(possible))
+            return possible;
+        if (typeof possible === "string") {
+            const matches = (possible.match(HEX3_REGEXP) || possible.match(HEX6_REGEXP));
+            if (matches) {
+                const [, r, g, b, a] = matches;
+                return new Color(_parse(r), _parse(g), _parse(b), typeof a === "string" ? _parse(a) : undefined);
+            }
+        }
     }
     r;
     g;
@@ -63,13 +67,9 @@ export function assertColor(value) {
     if (!isColor(value))
         throw new AssertionError("Invalid color", value);
 }
-/** Convert a possible color to a `Color` instance or `null` */
+/** Convert a possible color to a `Color` instance or `undefined` */
 export function getOptionalColor(possible) {
-    if (isColor(possible))
-        return possible;
-    if (typeof possible === "string")
-        return Color.fromHex(possible);
-    return null;
+    return Color.from(possible);
 }
 /** Convert a possible color to a `Color` instance */
 export function getColor(possible) {

package/util/date.d.ts

@@ -1,7 +1,5 @@
 /** Things that converted to dates. */
 export type PossibleDate = Date | number | string;
-/** Things that converted to dates or `null` */
-export type PossibleOptionalDate = Date | number | string | null;
 /** Is a value a date? */
 export declare function isDate(value: unknown): value is Date;
 /** Assert that a value is a `Date` instance. */
@@ -12,7 +10,7 @@ export declare function assertDate(value: unknown): asserts value is Date;
  *
  * Conversion rules:
  * - `Date` instance returns unchanged (BUT if the date isn't valid, `null` is returned).
- * - `null` returns `null`
+ * - `null` or `""` empty string or the string `"none"` returns `undefined`
  * - `undefined` returns the current date (e.g. `new Date()`).
  * - The string `"now"` returns the current date (e.g. `new Date()`).
  * - The string `"today"` returns the current date at midnight (e.g. `getMidnight()`).
@@ -25,15 +23,15 @@ export declare function assertDate(value: unknown): asserts value is Date;
  * @param possible Any value that we want to parse as a valid date.
  * @returns `Date` instance if the value could be converted to a valid date, and `null` if not.
  */
-export declare function getOptionalDate(possible: unknown): Date | null;
+export declare function getOptionalDate(possible?: unknown): Date | undefined;
 /** Convert a possible date to a `Date` instance, or throw `AssertionError` if it couldn't be converted. */
 export declare function getDate(possible?: PossibleDate): Date;
-/** Convert an unknown value to a timestamp (milliseconds past Unix epoch), or `null` if it couldn't be converted. */
-export declare function getOptionalTimestamp(possible: unknown): number | null;
+/** Convert an unknown value to a timestamp (milliseconds past Unix epoch), or `undefined` if it couldn't be converted. */
+export declare function getOptionalTimestamp(possible: unknown): number | undefined;
 /** Convert a possible date to a timestamp (milliseconds past Unix epoch), or throw `AssertionError` if it couldn't be converted. */
 export declare function getTimestamp(possible?: PossibleDate): number;
-/** Convert an unknown value to a YMD date string like "2015-09-12", or `null` if it couldn't be converted. */
-export declare function getOptionalYMD(possible: unknown): string | null;
+/** Convert an unknown value to a YMD date string like "2015-09-12", or `undefined` if it couldn't be converted. */
+export declare function getOptionalYMD(possible: unknown): string | undefined;
 /** Convert a `Date` instance to a YMD string like "2015-09-12", or throw `AssertionError` if it couldn't be converted.  */
 export declare function getYMD(possible?: PossibleDate): string;
 /** List of day-of-week strings. */
@@ -78,4 +76,4 @@ export declare function isToday(target: PossibleDate, current?: PossibleDate): b
 /** Format a date in the browser locale. */
 export declare function formatDate(date: PossibleDate): string;
 /** Format an optional time as a string. */
-export declare function formatOptionalDate(date?: unknown): string | null;
+export declare function formatOptionalDate(date?: unknown): string | undefined;

package/util/date.js

@@ -1,7 +1,7 @@
 import { AssertionError } from "../error/AssertionError.js";
 /** Is a value a date? */
 export function isDate(value) {
-    return value instanceof Date;
+    return value instanceof Date && Number.isFinite(value.getTime());
 }
 /** Assert that a value is a `Date` instance. */
 export function assertDate(value) {
@@ -14,7 +14,7 @@ export function assertDate(value) {
  *
  * Conversion rules:
  * - `Date` instance returns unchanged (BUT if the date isn't valid, `null` is returned).
- * - `null` returns `null`
+ * - `null` or `""` empty string or the string `"none"` returns `undefined`
  * - `undefined` returns the current date (e.g. `new Date()`).
  * - The string `"now"` returns the current date (e.g. `new Date()`).
  * - The string `"today"` returns the current date at midnight (e.g. `getMidnight()`).
@@ -27,46 +27,45 @@ export function assertDate(value) {
  * @param possible Any value that we want to parse as a valid date.
  * @returns `Date` instance if the value could be converted to a valid date, and `null` if not.
  */
-export function getOptionalDate(possible) {
-    if (possible === undefined || possible === "now")
+export function getOptionalDate(possible = "now") {
+    if (possible === null)
+        return undefined;
+    if (possible === "now")
         return new Date();
-    if (isDate(possible))
-        return _getValidDate(possible);
     if (possible === "today")
         return getMidnight();
     if (possible === "tomorrow")
         return addDays(1, getMidnight());
     if (possible === "yesterday")
         return addDays(-1, getMidnight());
-    if (possible === null || possible === "")
-        return null; // We know empty string is always an invalid date.
-    if (typeof possible === "string" || typeof possible === "number")
-        return _getValidDate(new Date(possible));
-    return null;
-}
-function _getValidDate(date) {
-    return Number.isFinite(date.getTime()) ? date : null;
+    if (isDate(possible))
+        return possible;
+    if (typeof possible === "string" || typeof possible === "number") {
+        const date = new Date(possible);
+        if (Number.isFinite(date.getTime()))
+            return date;
+    }
 }
 /** Convert a possible date to a `Date` instance, or throw `AssertionError` if it couldn't be converted. */
-export function getDate(possible = "now") {
+export function getDate(possible) {
     const date = getOptionalDate(possible);
     if (!date)
         throw new AssertionError(`Must be date`, possible);
     return date;
 }
-/** Convert an unknown value to a timestamp (milliseconds past Unix epoch), or `null` if it couldn't be converted. */
+/** Convert an unknown value to a timestamp (milliseconds past Unix epoch), or `undefined` if it couldn't be converted. */
 export function getOptionalTimestamp(possible) {
-    const date = getOptionalDate(possible);
-    return date ? date.getTime() : null;
+    return getOptionalDate(possible)?.getTime();
 }
 /** Convert a possible date to a timestamp (milliseconds past Unix epoch), or throw `AssertionError` if it couldn't be converted. */
 export function getTimestamp(possible) {
     return getDate(possible).getTime();
 }
-/** Convert an unknown value to a YMD date string like "2015-09-12", or `null` if it couldn't be converted. */
+/** Convert an unknown value to a YMD date string like "2015-09-12", or `undefined` if it couldn't be converted. */
 export function getOptionalYMD(possible) {
     const date = getOptionalDate(possible);
-    return date ? _ymd(date) : null;
+    if (date)
+        return _ymd(date);
 }
 /** Convert a `Date` instance to a YMD string like "2015-09-12", or throw `AssertionError` if it couldn't be converted.  */
 export function getYMD(possible) {
@@ -166,5 +165,5 @@ export function formatDate(date) {
 }
 /** Format an optional time as a string. */
 export function formatOptionalDate(date) {
-    return getOptionalDate(date)?.toLocaleDateString() || null;
+    return getOptionalDate(date)?.toLocaleDateString();
 }

package/util/number.d.ts

@@ -19,16 +19,16 @@ export declare function assertMax(value: unknown, max: number): asserts value is
 /** Assert that a value is a number less than. */
 export declare function assertMin(value: unknown, min: number): asserts value is number;
 /**
- * Convert an unknown value to a finite number or `null`
- * - Note: numbers can be non-finite numbers like `NaN` or `Infinity`. These are detected and will always return `null`
+ * Convert an unknown value to a finite number or `undefined`
+ * - Note: numbers can be non-finite numbers like `NaN` or `Infinity`. These are detected and will always return `undefined`
  *
  * Conversion rules:
- * - Numbers (except `NaN` and `+Infinity` and `-Infinity`) return numbers.
+ * - Finite numbers return numbers.
  * - Strings are parsed as numbers.
- * - Dates return their milliseconds (e.g. `date.getTime()`)
- * - Everything else returns `null`
+ * - Dates return their milliseconds (e.g. `date.getTime()`).
+ * - Everything else returns `undefined`
  */
-export declare function getOptionalNumber(value: unknown): number | null;
+export declare function getOptionalNumber(value: unknown): number | undefined;
 /**
  * Assertively convert an unknown value to a finite number.
  * @throws `AssertionError` if the value cannot be converted.

package/util/number.js

@@ -36,23 +36,22 @@ export function assertMin(value, min) {
         throw new AssertionError(`Must be number with minimum ${min}`, value);
 }
 /**
- * Convert an unknown value to a finite number or `null`
- * - Note: numbers can be non-finite numbers like `NaN` or `Infinity`. These are detected and will always return `null`
+ * Convert an unknown value to a finite number or `undefined`
+ * - Note: numbers can be non-finite numbers like `NaN` or `Infinity`. These are detected and will always return `undefined`
  *
  * Conversion rules:
- * - Numbers (except `NaN` and `+Infinity` and `-Infinity`) return numbers.
+ * - Finite numbers return numbers.
  * - Strings are parsed as numbers.
- * - Dates return their milliseconds (e.g. `date.getTime()`)
- * - Everything else returns `null`
+ * - Dates return their milliseconds (e.g. `date.getTime()`).
+ * - Everything else returns `undefined`
  */
 export function getOptionalNumber(value) {
-    if (typeof value === "number")
-        return !Number.isFinite(value) ? null : value === 0 ? 0 : value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value === 0 ? 0 : value; // Convert `-0` to `0`
     else if (typeof value === "string")
         return getOptionalNumber(parseFloat(value.replace(NOT_NUMERIC_REGEXP, "")));
     else if (value instanceof Date)
         return getOptionalNumber(value.getTime());
-    return null;
 }
 const NOT_NUMERIC_REGEXP = /[^0-9-.]/g;
 /**

package/util/path.d.ts

@@ -2,6 +2,8 @@
 export type AbsolutePath = `/` | `/${string}`;
 /** Relative path starts with `./` or `../` */
 export type RelativePath = `.` | `./${string}` | `..` | `../${string}`;
+/** Absolute path or relative path. */
+export type Path = AbsolutePath | RelativePath;
 /** Is a string path an absolute path? */
 export declare const isAbsolutePath: (path: string) => path is `/${string}`;
 /** Is a string path an absolute path? */
@@ -23,7 +25,7 @@ export declare function cleanPath(path: string): string;
  * @param base Absolute path or `URL` instance used for resolving relative paths in `path`
  * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
  */
-export declare function getPath(path: string | URL, base?: AbsolutePath | URL): AbsolutePath;
+export declare function getPath(path: string | URL, base?: AbsolutePath | URL | Location): AbsolutePath;
 /** Is a target path active? */
 export declare function isPathActive(target: AbsolutePath, current: AbsolutePath): boolean;
 /** Is a target path proud (i.e. is the current path, or is a child of the current path)? */

package/util/path.js

@@ -17,14 +17,15 @@ export function cleanPath(path) {
  * @param base Absolute path or `URL` instance used for resolving relative paths in `path`
  * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
  */
-export function getPath(path, base = "/") {
+export function getPath(path, base = _LOCATION) {
     try {
-        return cleanPath(new URL(path, `http://j.com${base instanceof URL ? base.pathname : base}/`).pathname);
+        return cleanPath(new URL(path, `http://j.com${typeof base === "string" ? base : base.pathname}/`).pathname);
     }
     catch {
         throw new AssertionError("Invalid path", path);
     }
 }
+const _LOCATION = typeof window === "object" ? window.location : "/";
 /** Is a target path active? */
 export function isPathActive(target, current) {
     return target === current;

package/util/string.d.ts

@@ -67,12 +67,12 @@ export declare const sanitizeLines: (str: string) => string;
  * @todo Convert letter-like characters (e.g. `ℝ`) to their ASCII equivalent (e.g. `R`).
  */
 export declare const simplifyString: (str: string) => string;
-/** Convert a string to a `kebab-case` URL slug, or throw `AssertionError` */
-export declare const getOptionalSlug: (str: string) => string | null;
+/** Convert a string to a `kebab-case` URL slug, or return `undefined` if conversion resulted in an empty ref. */
+export declare const getOptionalSlug: (str: string) => string | undefined;
 export declare function getSlug(str: string): string;
-/** Convert a string to a unique ref e.g. `abc123`, or `null` */
-export declare const getOptionalRef: (str: string) => string | null;
-/** Convert a string to a unique ref e.g. `abc123`, or throw `AssertionError` */
+/** Convert a string to a unique ref e.g. `abc123`, or return `undefined` if conversion resulted in an empty ref. */
+export declare const getOptionalRef: (str: string) => string | undefined;
+/** Convert a string to a unique ref e.g. `abc123`, or throw `AssertionError` if conversion resulted in an empty ref. */
 export declare function getRef(str: string): string;
 /**
  * Return an array of the separate words and "quoted phrases" found in a string.

package/util/string.js

@@ -108,23 +108,23 @@ export const simplifyString = (str) => str
     .replace(/[^\p{L}\p{N} ]+/gu, "") // Strip characters that aren't letters, numbers, spaces.
     .trim()
     .toLowerCase();
-/** Convert a string to a `kebab-case` URL slug, or throw `AssertionError` */
-export const getOptionalSlug = (str) => simplifyString(str).replace(/ /g, "-") || null;
-/* Convert a string to a `kebab-case` URL slug, or throw `AssertionError` */
+/** Convert a string to a `kebab-case` URL slug, or return `undefined` if conversion resulted in an empty ref. */
+export const getOptionalSlug = (str) => simplifyString(str).replace(/ /g, "-") || undefined;
+/* Convert a string to a `kebab-case` URL slug, or throw `AssertionError` if conversion resulted in an empty ref. */
 export function getSlug(str) {
     const slug = getOptionalSlug(str);
     if (slug)
         return slug;
-    throw new AssertionError(`String slug cannot be empty (received "${str}")`);
+    throw new AssertionError("Invalid slug", str);
 }
-/** Convert a string to a unique ref e.g. `abc123`, or `null` */
-export const getOptionalRef = (str) => simplifyString(str).replace(/ /g, "") || null;
-/** Convert a string to a unique ref e.g. `abc123`, or throw `AssertionError` */
+/** Convert a string to a unique ref e.g. `abc123`, or return `undefined` if conversion resulted in an empty ref. */
+export const getOptionalRef = (str) => simplifyString(str).replace(/ /g, "") || undefined;
+/** Convert a string to a unique ref e.g. `abc123`, or throw `AssertionError` if conversion resulted in an empty ref. */
 export function getRef(str) {
     const ref = getOptionalRef(str);
     if (ref)
         return ref;
-    throw new AssertionError(`String ref cannot be empty (received "${str}")`);
+    throw new AssertionError("Invalid string ref", str);
 }
 /**
  * Return an array of the separate words and "quoted phrases" found in a string.

package/util/time.d.ts

@@ -1,9 +1,7 @@
 /** Class representing a time in the day in 24 hour format in the user's current locale. */
 export declare class Time {
-    /** Make a new `Time` instance from a date (or any value that can be converted to a date). */
-    static fromDate(possible?: unknown): Time | null;
     /** Make a new `Time` instance from a time string. */
-    static fromString(str: string): Time | null;
+    static from(possible?: unknown): Time | undefined;
     readonly time: number;
     constructor(time: number);
     /** Get the number of hours in this time. */
@@ -34,16 +32,14 @@ export declare class Time {
 export declare const TIME_REGEXP: RegExp;
 /** Things that converted to times. */
 export type PossibleTime = Time | Date | number | string;
-/** Things that converted to times or `null` */
-export type PossibleOptionalTime = Time | Date | number | string | null;
 /** Is an unknown value a `Time` instance. */
 export declare const isTime: (value: unknown) => value is Time;
 /**
- * Convert a value to a `Time` instance or `null`
+ * Convert a value to a `Time` instance or `undefined`
  * - Works with possible dates, e.g. `now` or `Date` or `2022-09-12 18:32` or `19827263567`
  * - Works with time strings, e.g. `18:32` or `23:59:59.999`
  */
-export declare function getOptionalTime(possible: unknown): Time | null;
+export declare function getOptionalTime(possible: unknown): Time | undefined;
 /** Convert a possible time to a `Time` instance, or throw `AssertionError` if it couldn't be converted. */
 export declare function getTime(possible?: PossibleTime): Time;
 /** Get the time as in `hh:mm` format (hours, minutes), e.g. `13.59` */
@@ -55,4 +51,4 @@ export declare const getLongTime: (time?: PossibleTime) => string;
 /** Format a time as a string based on the browser locale settings. */
 export declare const formatTime: (time?: PossibleTime, precision?: 2 | 3 | 4 | 5 | 6) => string;
 /** Format an optional time as a string based on the browser locale settings. */
-export declare const formatOptionalTime: (time?: unknown, precision?: 2 | 3 | 4 | 5 | 6) => string | null;
+export declare const formatOptionalTime: (time?: unknown, precision?: 2 | 3 | 4 | 5 | 6) => string | undefined;

package/util/time.js

@@ -4,18 +4,22 @@ import { getOptionalDate } from "./date.js";
 import { wrapNumber } from "./number.js";
 /** Class representing a time in the day in 24 hour format in the user's current locale. */
 export class Time {
-    /** Make a new `Time` instance from a date (or any value that can be converted to a date). */
-    static fromDate(possible) {
-        const date = getOptionalDate(possible);
-        return date ? new Time(date.getHours() * HOUR + date.getMinutes() * MINUTE + date.getSeconds() * SECOND + date.getMilliseconds()) : null;
-    }
     /** Make a new `Time` instance from a time string. */
-    static fromString(str) {
-        const matches = str.match(TIME_REGEXP);
-        if (!matches)
-            return null;
-        const [, h, m, s, ms] = matches;
-        return new Time(parseInt(h, 10) * HOUR + parseInt(m, 10) * MINUTE + (typeof s === "string" ? parseInt(s, 10) * SECOND : 0) + (typeof ms === "string" ? parseInt(ms, 10) : 0));
+    static from(possible = "now") {
+        if (possible === null)
+            return undefined;
+        if (isTime(possible))
+            return possible;
+        if (typeof possible === "string") {
+            const matches = possible.match(TIME_REGEXP);
+            if (matches) {
+                const [, h, m, s, ms] = matches;
+                return new Time(parseInt(h, 10) * HOUR + parseInt(m, 10) * MINUTE + (typeof s === "string" ? parseInt(s, 10) * SECOND : 0) + (typeof ms === "string" ? parseInt(ms, 10) : 0));
+            }
+        }
+        const date = getOptionalDate(possible);
+        if (date)
+            return new Time(date.getHours() * HOUR + date.getMinutes() * MINUTE + date.getSeconds() * SECOND + date.getMilliseconds());
     }
     /* Total number of milliseconds in this time (always a number between `0` and `86400000` because higher/lower numbers wrap into the next/previous day). */
     time;
@@ -53,7 +57,7 @@ export class Time {
     /** Get a date corresponding to this time. */
     get date() {
         const date = new Date();
-        date.setHours(0, 0, 0, 0);
+        date.setHours(this.h, this.m, this.s, this.ms);
         return date;
     }
     /**
@@ -83,17 +87,15 @@ export const TIME_REGEXP = /([0-9]+):([0-9]+)(?::([0-9]+)(?:.([0-9]+))?)?/;
 /** Is an unknown value a `Time` instance. */
 export const isTime = (value) => value instanceof Time;
 /**
- * Convert a value to a `Time` instance or `null`
+ * Convert a value to a `Time` instance or `undefined`
  * - Works with possible dates, e.g. `now` or `Date` or `2022-09-12 18:32` or `19827263567`
  * - Works with time strings, e.g. `18:32` or `23:59:59.999`
  */
 export function getOptionalTime(possible) {
-    if (isTime(possible))
-        return possible;
-    return (typeof possible === "string" && Time.fromString(possible)) || Time.fromDate(possible) || null;
+    return Time.from(possible);
 }
 /** Convert a possible time to a `Time` instance, or throw `AssertionError` if it couldn't be converted. */
-export function getTime(possible = "now") {
+export function getTime(possible) {
     const time = getOptionalTime(possible);
     if (!time)
         throw new AssertionError(`Must be time`, possible);
@@ -108,4 +110,4 @@ export const getLongTime = (time) => getTime(time).long;
 /** Format a time as a string based on the browser locale settings. */
 export const formatTime = (time, precision = 2) => getTime(time).format(precision);
 /** Format an optional time as a string based on the browser locale settings. */
-export const formatOptionalTime = (time, precision = 2) => getOptionalTime(time)?.format(precision) || null;
+export const formatOptionalTime = (time, precision = 2) => getOptionalTime(time)?.format(precision);

package/util/url.d.ts

@@ -1,13 +1,13 @@
+import { type Optional } from "./optional.js";
 /** Things that can be converted to a URL instance. */
 export type PossibleURL = string | URL;
-export type PossibleOptionalURL = PossibleURL | null;
 /** Is an unknown value a URL? */
 export declare const isURL: (value: unknown) => value is URL;
 /** Assert that an unknown value is a URL. */
 export declare function assertURL(value: unknown): asserts value is URL;
 /** Convert a possible URL to a URL or return `null` if conversion fails. */
-export declare function getOptionalURL(url: PossibleOptionalURL, base?: PossibleOptionalURL): URL | null;
+export declare function getOptionalURL(url: Optional<PossibleURL>, base?: PossibleURL | Location | undefined): URL | undefined;
 /** Convert a possible URL to a URL but throw `AssertionError` if conversion fails. */
-export declare function getURL(possibleURL: PossibleURL, base?: PossibleOptionalURL): URL;
+export declare function getURL(possibleURL: PossibleURL, base?: PossibleURL): URL;
 /** Just get important part of a URL, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
-export declare function formatURL(possibleURL: PossibleURL, base?: PossibleOptionalURL): string;
+export declare function formatURL(possibleURL: PossibleURL, base?: PossibleURL): string;

package/util/url.js

@@ -1,4 +1,5 @@
 import { AssertionError } from "../error/AssertionError.js";
+import { notOptional } from "./optional.js";
 /** Is an unknown value a URL? */
 export const isURL = (value) => value instanceof URL;
 /** Assert that an unknown value is a URL. */
@@ -7,18 +8,19 @@ export function assertURL(value) {
         throw new AssertionError("Invalid URL", value);
 }
 /** Convert a possible URL to a URL or return `null` if conversion fails. */
-export function getOptionalURL(url, base = typeof window === "object" ? window.location.href : null) {
-    if (!url)
-        return null;
-    if (isURL(url))
-        return url;
-    try {
-        return new URL(url, base || undefined);
-    }
-    catch (e) {
-        return null;
+export function getOptionalURL(url, base = _LOCATION) {
+    if (notOptional(url)) {
+        if (isURL(url))
+            return url;
+        try {
+            return new URL(url, base); // DH: We know `Location` works in URL constructor.
+        }
+        catch (e) {
+            //
+        }
     }
 }
+const _LOCATION = typeof window === "object" ? window.location : undefined;
 /** Convert a possible URL to a URL but throw `AssertionError` if conversion fails. */
 export function getURL(possibleURL, base) {
     const url = getOptionalURL(possibleURL, base);