shelving 1.236.0 → 1.236.2

package/util/bytes.js

@@ -1,9 +1,25 @@
 import { RequiredError } from "../error/RequiredError.js";
-/** Is an unknown value a set of bytes? */
+/**
+ * Is an unknown value a set of bytes?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a `Uint8Array` backed by an `ArrayBuffer`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/bytes/isBytes
+ */
 export function isBytes(value) {
     return value instanceof Uint8Array && value.buffer instanceof ArrayBuffer;
 }
-/** Assert that an unknown value is a `Uint8Array` byte sequence. */
+/**
+ * Assert that an unknown value is a `Uint8Array` byte sequence (optionally with a min/max length).
+ *
+ * @param value The value to assert.
+ * @param min Minimum allowed length (defaults to `0`).
+ * @param max Maximum allowed length (defaults to `Infinity`).
+ * @param caller Function to attribute a thrown error to (defaults to `assertBytes` itself).
+ * @throws {RequiredError} If `value` is not a byte sequence within the allowed length range.
+ * @example assertBytes(new Uint8Array([1, 2, 3]), 1, 8);
+ * @see https://dhoulb.github.io/shelving/util/bytes/assertBytes
+ */
 export function assertBytes(value, min = 0, max = Number.POSITIVE_INFINITY, caller = assertBytes) {
     if (!isBytes(value) || 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 });
@@ -15,6 +31,11 @@ export function assertBytes(value, min = 0, max = Number.POSITIVE_INFINITY, call
  * - `ArrayBuffer` instances are converted to `Uint8Array`
  * - Strings are encoded as UTF-8 characters in a `Uint8Array`
  * - Everything else returns `undefined`
+ *
+ * @param value The value to convert.
+ * @returns The byte sequence, or `undefined` if `value` cannot be converted.
+ * @example getBytes("abc") // Uint8Array([97, 98, 99])
+ * @see https://dhoulb.github.io/shelving/util/bytes/getBytes
  */
 export function getBytes(value) {
     if (isBytes(value))
@@ -27,6 +48,15 @@ export function getBytes(value) {
 }
 /**
  * Convert a possible set of bytes to a `Uint8Array` byte sequence, or throw `RequiredError` if the value cannot be converted.
+ *
+ * @param value The possible bytes to convert.
+ * @param min Minimum allowed length (defaults to `0`).
+ * @param max Maximum allowed length (defaults to `Infinity`).
+ * @param caller Function to attribute a thrown error to (defaults to `requireBytes` itself).
+ * @returns The converted byte sequence.
+ * @throws {RequiredError} If `value` cannot be converted or is outside the allowed length range.
+ * @example requireBytes("abc") // Uint8Array([97, 98, 99])
+ * @see https://dhoulb.github.io/shelving/util/bytes/requireBytes
  */
 export function requireBytes(value, min = 0, max = Number.POSITIVE_INFINITY, caller = requireBytes) {
     const bytes = getBytes(value);

package/util/class.d.ts

@@ -1,17 +1,68 @@
 import type { Arguments } from "./function.js";
-/** Class that has a public `constructor()` function. */
+/**
+ * Class that has a public `constructor()` function.
+ *
+ * @see https://dhoulb.github.io/shelving/util/class/Constructor
+ */
 export type Constructor<T, A extends Arguments> = new (...args: A) => T;
-/** Any function arguments (designed for use with `extends Arguments` guards). */
+/**
+ * Any class constructor (designed for use with `extends AnyConstructor` guards).
+ *
+ * @see https://dhoulb.github.io/shelving/util/class/AnyConstructor
+ */
 export type AnyConstructor = new (...args: any) => any;
-/** Class prototype that can be used with `instanceof`. */
+/**
+ * Class prototype that can be used with `instanceof`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/class/Class
+ */
 export type Class<T> = new (...args: any) => T;
-/** Is a given value a class constructor? */
+/**
+ * Is a given value a class constructor?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a class constructor, narrowing its type.
+ * @example isConstructor(class {}) // true
+ * @see https://dhoulb.github.io/shelving/util/class/isConstructor
+ */
 export declare function isConstructor(value: unknown): value is AnyConstructor;
-/** Is a value an instance of a class? */
+/**
+ * Is a value an instance of a class?
+ *
+ * @param value The value to test.
+ * @param type The class to test `value` against.
+ * @returns `true` if `value` is an instance of `type`, narrowing its type.
+ * @example isInstance(new Date(), Date) // true
+ * @see https://dhoulb.github.io/shelving/util/class/isInstance
+ */
 export declare function isInstance<T>(value: unknown, type: Class<T>): value is T;
-/** Assert that a value is an instance of something. */
+/**
+ * Assert that a value is an instance of something.
+ *
+ * @param value The value to assert.
+ * @param type The class `value` must be an instance of.
+ * @throws {RequiredError} If `value` is not an instance of `type`.
+ * @example assertInstance(new Date(), Date); // passes
+ * @see https://dhoulb.github.io/shelving/util/class/assertInstance
+ */
 export declare function assertInstance<T>(value: unknown, type: Class<T>): asserts value is T;
-/** Get the 'getter' function for a given property, or `undefined` if it doesn't exist. */
+/**
+ * Get the 'getter' function for a given property, or `undefined` if it doesn't exist.
+ *
+ * @param obj The object to read the property descriptor from.
+ * @param prop The property name to look up.
+ * @returns The getter function bound to `T`, or `undefined` if the property has no getter.
+ * @example getGetter(obj, "size") // () => number | undefined
+ * @see https://dhoulb.github.io/shelving/util/class/getGetter
+ */
 export declare function getGetter<T extends Object, K extends keyof T>(obj: T, prop: K): ((this: T) => T[K]) | undefined;
-/** Get the 'setter' function for a given property, or `undefined` if it doesn't exist. */
+/**
+ * Get the 'setter' function for a given property, or `undefined` if it doesn't exist.
+ *
+ * @param obj The object whose prototype is searched for the property descriptor.
+ * @param prop The property name to look up.
+ * @returns The setter function bound to `T`, or `undefined` if the property has no setter.
+ * @example getSetter(obj, "size") // (value: number) => void | undefined
+ * @see https://dhoulb.github.io/shelving/util/class/getSetter
+ */
 export declare function getSetter<T extends Object, K extends keyof T>(obj: T, prop: K): ((this: T, value: T[K]) => void) | undefined;

package/util/class.js

@@ -1,24 +1,63 @@
 import { RequiredError } from "../error/RequiredError.js";
-/** Is a given value a class constructor? */
+/**
+ * Is a given value a class constructor?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a class constructor, narrowing its type.
+ * @example isConstructor(class {}) // true
+ * @see https://dhoulb.github.io/shelving/util/class/isConstructor
+ */
 export function isConstructor(value) {
     return typeof value === "function" && value.toString().startsWith("class");
 }
-/** Is a value an instance of a class? */
+/**
+ * Is a value an instance of a class?
+ *
+ * @param value The value to test.
+ * @param type The class to test `value` against.
+ * @returns `true` if `value` is an instance of `type`, narrowing its type.
+ * @example isInstance(new Date(), Date) // true
+ * @see https://dhoulb.github.io/shelving/util/class/isInstance
+ */
 export function isInstance(value, type) {
     return value instanceof type;
 }
-/** Assert that a value is an instance of something. */
+/**
+ * Assert that a value is an instance of something.
+ *
+ * @param value The value to assert.
+ * @param type The class `value` must be an instance of.
+ * @throws {RequiredError} If `value` is not an instance of `type`.
+ * @example assertInstance(new Date(), Date); // passes
+ * @see https://dhoulb.github.io/shelving/util/class/assertInstance
+ */
 export function assertInstance(value, type) {
     if (!(value instanceof type))
         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. */
+/**
+ * Get the 'getter' function for a given property, or `undefined` if it doesn't exist.
+ *
+ * @param obj The object to read the property descriptor from.
+ * @param prop The property name to look up.
+ * @returns The getter function bound to `T`, or `undefined` if the property has no getter.
+ * @example getGetter(obj, "size") // () => number | undefined
+ * @see https://dhoulb.github.io/shelving/util/class/getGetter
+ */
 // biome-ignore lint/complexity/noBannedTypes: This is correct here.
 export function getGetter(obj, prop) {
     const descriptor = Object.getOwnPropertyDescriptor(obj, prop);
     return descriptor && typeof descriptor.get === "function" ? descriptor.get : undefined;
 }
-/** Get the 'setter' function for a given property, or `undefined` if it doesn't exist. */
+/**
+ * Get the 'setter' function for a given property, or `undefined` if it doesn't exist.
+ *
+ * @param obj The object whose prototype is searched for the property descriptor.
+ * @param prop The property name to look up.
+ * @returns The setter function bound to `T`, or `undefined` if the property has no setter.
+ * @example getSetter(obj, "size") // (value: number) => void | undefined
+ * @see https://dhoulb.github.io/shelving/util/class/getSetter
+ */
 // biome-ignore lint/complexity/noBannedTypes: This is correct here.
 export function getSetter(obj, prop) {
     const descriptor = Object.getOwnPropertyDescriptor(obj.constructor.prototype, prop);

package/util/color.d.ts

@@ -1,36 +1,154 @@
 import type { AnyCaller } from "./function.js";
+/**
+ * Regular expression matching a three-digit hex color (e.g. `#F00`), capturing each channel.
+ *
+ * @see https://dhoulb.github.io/shelving/util/color/HEX3_REGEXP
+ */
 export declare const HEX3_REGEXP: RegExp;
+/**
+ * Regular expression matching a six or eight digit hex color (e.g. `#FF0000` or `#FF0000FF`), capturing each channel.
+ *
+ * @see https://dhoulb.github.io/shelving/util/color/HEX6_REGEXP
+ */
 export declare const HEX6_REGEXP: RegExp;
-/** Things that can be converted to a `Color` instance. */
+/**
+ * Things that can be converted to a `Color` instance.
+ *
+ * @see https://dhoulb.github.io/shelving/util/color/PossibleColor
+ */
 export type PossibleColor = Color | string;
-/** Represent a color. */
+/**
+ * Represents an RGBA color with red, green, blue, and alpha channels (each `0`–`255`).
+ *
+ * @example new Color(255, 0, 0).hex // "#FF0000"
+ * @see https://dhoulb.github.io/shelving/util/color/Color
+ */
 export declare class Color {
-    /** Make a `Color` from an unknown value. */
+    /**
+     * Make a `Color` from an unknown value, or `undefined` if it can't be parsed.
+     *
+     * @param possible The value to parse, typically a `Color` instance or a three/six/eight digit hex string.
+     * @returns The parsed `Color`, or `undefined` if `possible` cannot be converted.
+     * @example Color.from("#F00") // Color(255, 0, 0)
+     * @see https://dhoulb.github.io/shelving/util/color/Color/from
+     */
     static from(possible: unknown): Color | undefined;
+    /**
+     * Red channel, bounded to `0`–`255`.
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/r
+     */
     readonly r: number;
+    /**
+     * Green channel, bounded to `0`–`255`.
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/g
+     */
     readonly g: number;
+    /**
+     * Blue channel, bounded to `0`–`255`.
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/b
+     */
     readonly b: number;
+    /**
+     * Alpha channel, bounded to `0`–`255`.
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/a
+     */
     readonly a: number;
+    /**
+     * Create a new `Color` from red, green, blue, and alpha channel values.
+     *
+     * @param r Red channel, bounded to `0`–`255` (defaults to `255`).
+     * @param g Green channel, bounded to `0`–`255` (defaults to `255`).
+     * @param b Blue channel, bounded to `0`–`255` (defaults to `255`).
+     * @param a Alpha channel, bounded to `0`–`255` (defaults to `255`).
+     * @example new Color(255, 0, 0) // opaque red
+     * @see https://dhoulb.github.io/shelving/util/color/Color/constructor
+     */
     constructor(r?: number, g?: number, b?: number, a?: number);
-    /** Convert this color to a six or eight digit hex color. */
+    /**
+     * This color as a six or eight digit hex string (eight digits when the alpha channel is less than `255`).
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/hex
+     */
     get hex(): string;
-    /** Convert this color to an `rgb()` string. */
+    /**
+     * This color as a CSS `rgb()` string.
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/rgb
+     */
     get rgb(): string;
-    /** Convert this color to an `rgba()` string. */
+    /**
+     * This color as a CSS `rgba()` string.
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/rgba
+     */
     get rgba(): string;
-    /** Get the sRGB luminance of this color. */
+    /**
+     * The sRGB luminance of this color (`0`–`255`).
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/luminance
+     */
     get luminance(): number;
-    /** Is this color light. */
+    /**
+     * Whether this color is light (its luminance is above the dark/light threshold).
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/isLight
+     */
     get isLight(): boolean;
-    /** Is this color dark. */
+    /**
+     * Whether this color is dark (its luminance is at or below the dark/light threshold).
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/isDark
+     */
     get isDark(): boolean;
+    /**
+     * Return this color as an `rgba()` string.
+     *
+     * @returns This color formatted as a CSS `rgba()` string.
+     * @example String(new Color(255, 0, 0)) // "rgba(255, 0, 0, 1)"
+     * @see https://dhoulb.github.io/shelving/util/color/Color/toString
+     */
     toString(): string;
 }
-/** Is an unknown value a `Color` instance. */
+/**
+ * Is an unknown value a `Color` instance?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a `Color`, narrowing its type.
+ * @example isColor(new Color()) // true
+ * @see https://dhoulb.github.io/shelving/util/color/isColor
+ */
 export declare function isColor(value: unknown): value is Color;
-/** Assert that an unknown value is a `Color` instance. */
+/**
+ * Assert that an unknown value is a `Color` instance.
+ *
+ * @param value The value to assert.
+ * @param caller Function to attribute a thrown error to (defaults to `assertColor` itself).
+ * @throws {RequiredError} If `value` is not a `Color` instance.
+ * @example assertColor(new Color());
+ * @see https://dhoulb.github.io/shelving/util/color/assertColor
+ */
 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. */
+/**
+ * Convert an unknown value to a `Color` instance, or return `undefined` if conversion fails.
+ *
+ * @param value The value to convert.
+ * @returns The converted `Color`, or `undefined` if `value` cannot be converted.
+ * @example getColor("#F00") // Color(255, 0, 0)
+ * @see https://dhoulb.github.io/shelving/util/color/getColor
+ */
 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. */
+/**
+ * Convert a possible color to a `Color` instance, or throw `RequiredError` if it can't be converted.
+ *
+ * @param value The possible color to convert.
+ * @param caller Function to attribute a thrown error to (defaults to `requireColor` itself).
+ * @returns The converted `Color`.
+ * @throws {RequiredError} If `value` cannot be converted to a `Color`.
+ * @example requireColor("#F00") // Color(255, 0, 0)
+ * @see https://dhoulb.github.io/shelving/util/color/requireColor
+ */
 export declare function requireColor(value: PossibleColor, caller?: AnyCaller): Color;

package/util/color.js

@@ -3,11 +3,33 @@ import { boundNumber, roundNumber } from "./number.js";
 // Constants.
 const DARK = 140; // Anything with a luminance > 140 is considered light.
 // Regular expressions.
+/**
+ * Regular expression matching a three-digit hex color (e.g. `#F00`), capturing each channel.
+ *
+ * @see https://dhoulb.github.io/shelving/util/color/HEX3_REGEXP
+ */
 export const HEX3_REGEXP = /^#?([0-F])([0-F])([0-F])$/i;
+/**
+ * Regular expression matching a six or eight digit hex color (e.g. `#FF0000` or `#FF0000FF`), capturing each channel.
+ *
+ * @see https://dhoulb.github.io/shelving/util/color/HEX6_REGEXP
+ */
 export const HEX6_REGEXP = /^#?([0-F]{2})([0-F]{2})([0-F]{2})([0-F]{2})?$/i;
-/** Represent a color. */
+/**
+ * Represents an RGBA color with red, green, blue, and alpha channels (each `0`–`255`).
+ *
+ * @example new Color(255, 0, 0).hex // "#FF0000"
+ * @see https://dhoulb.github.io/shelving/util/color/Color
+ */
 export class Color {
-    /** Make a `Color` from an unknown value. */
+    /**
+     * Make a `Color` from an unknown value, or `undefined` if it can't be parsed.
+     *
+     * @param possible The value to parse, typically a `Color` instance or a three/six/eight digit hex string.
+     * @returns The parsed `Color`, or `undefined` if `possible` cannot be converted.
+     * @example Color.from("#F00") // Color(255, 0, 0)
+     * @see https://dhoulb.github.io/shelving/util/color/Color/from
+     */
     static from(possible) {
         if (isColor(possible))
             return possible;
@@ -19,41 +41,102 @@ export class Color {
             }
         }
     }
+    /**
+     * Red channel, bounded to `0`–`255`.
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/r
+     */
     r;
+    /**
+     * Green channel, bounded to `0`–`255`.
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/g
+     */
     g;
+    /**
+     * Blue channel, bounded to `0`–`255`.
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/b
+     */
     b;
+    /**
+     * Alpha channel, bounded to `0`–`255`.
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/a
+     */
     a;
+    /**
+     * Create a new `Color` from red, green, blue, and alpha channel values.
+     *
+     * @param r Red channel, bounded to `0`–`255` (defaults to `255`).
+     * @param g Green channel, bounded to `0`–`255` (defaults to `255`).
+     * @param b Blue channel, bounded to `0`–`255` (defaults to `255`).
+     * @param a Alpha channel, bounded to `0`–`255` (defaults to `255`).
+     * @example new Color(255, 0, 0) // opaque red
+     * @see https://dhoulb.github.io/shelving/util/color/Color/constructor
+     */
     constructor(r = 255, g = 255, b = 255, a = 255) {
         this.r = boundNumber(r, 0, 255);
         this.g = boundNumber(g, 0, 255);
         this.b = boundNumber(b, 0, 255);
         this.a = boundNumber(a, 0, 255);
     }
-    /** Convert this color to a six or eight digit hex color. */
+    /**
+     * This color as a six or eight digit hex string (eight digits when the alpha channel is less than `255`).
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/hex
+     */
     get hex() {
         return `#${_hex(this.r)}${_hex(this.g)}${_hex(this.b)}${this.a < 255 ? _hex(this.a) : ""}`;
     }
-    /** Convert this color to an `rgb()` string. */
+    /**
+     * This color as a CSS `rgb()` string.
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/rgb
+     */
     get rgb() {
         return `rgb(${this.r}, ${this.g}, ${this.b})`;
     }
-    /** Convert this color to an `rgba()` string. */
+    /**
+     * This color as a CSS `rgba()` string.
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/rgba
+     */
     get rgba() {
         return `rgba(${this.r}, ${this.g}, ${this.b}, ${roundNumber(this.a / 256, 4)})`;
     }
-    /** Get the sRGB luminance of this color. */
+    /**
+     * The sRGB luminance of this color (`0`–`255`).
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/luminance
+     */
     get luminance() {
         // Green is the largest component of the luminence, etc.
         return Math.round(0.2126 * this.r + 0.7152 * this.g + 0.0722 * this.b);
     }
-    /** Is this color light. */
+    /**
+     * Whether this color is light (its luminance is above the dark/light threshold).
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/isLight
+     */
     get isLight() {
         return this.luminance > DARK;
     }
-    /** Is this color dark. */
+    /**
+     * Whether this color is dark (its luminance is at or below the dark/light threshold).
+     *
+     * @see https://dhoulb.github.io/shelving/util/color/Color/isDark
+     */
     get isDark() {
         return this.luminance <= DARK;
     }
+    /**
+     * Return this color as an `rgba()` string.
+     *
+     * @returns This color formatted as a CSS `rgba()` string.
+     * @example String(new Color(255, 0, 0)) // "rgba(255, 0, 0, 1)"
+     * @see https://dhoulb.github.io/shelving/util/color/Color/toString
+     */
     toString() {
         return this.rgba;
     }
@@ -64,20 +147,51 @@ function _parse(hex) {
 function _hex(channel) {
     return channel.toString(16).padStart(2, "00");
 }
-/** Is an unknown value a `Color` instance. */
+/**
+ * Is an unknown value a `Color` instance?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a `Color`, narrowing its type.
+ * @example isColor(new Color()) // true
+ * @see https://dhoulb.github.io/shelving/util/color/isColor
+ */
 export function isColor(value) {
     return value instanceof Color;
 }
-/** Assert that an unknown value is a `Color` instance. */
+/**
+ * Assert that an unknown value is a `Color` instance.
+ *
+ * @param value The value to assert.
+ * @param caller Function to attribute a thrown error to (defaults to `assertColor` itself).
+ * @throws {RequiredError} If `value` is not a `Color` instance.
+ * @example assertColor(new Color());
+ * @see https://dhoulb.github.io/shelving/util/color/assertColor
+ */
 export function assertColor(value, caller = assertColor) {
     if (!isColor(value))
         throw new RequiredError("Must be color", { received: value, caller });
 }
-/** Convert an unknown value to a `Color` instance, or return `undefined` if conversion fails. */
+/**
+ * Convert an unknown value to a `Color` instance, or return `undefined` if conversion fails.
+ *
+ * @param value The value to convert.
+ * @returns The converted `Color`, or `undefined` if `value` cannot be converted.
+ * @example getColor("#F00") // Color(255, 0, 0)
+ * @see https://dhoulb.github.io/shelving/util/color/getColor
+ */
 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. */
+/**
+ * Convert a possible color to a `Color` instance, or throw `RequiredError` if it can't be converted.
+ *
+ * @param value The possible color to convert.
+ * @param caller Function to attribute a thrown error to (defaults to `requireColor` itself).
+ * @returns The converted `Color`.
+ * @throws {RequiredError} If `value` cannot be converted to a `Color`.
+ * @example requireColor("#F00") // Color(255, 0, 0)
+ * @see https://dhoulb.github.io/shelving/util/color/requireColor
+ */
 export function requireColor(value, caller = requireColor) {
     const color = getColor(value);
     assertColor(color, caller);