shelving 1.236.0 → 1.236.2

package/util/async.js

@@ -1,40 +1,83 @@
 import { Errors } from "../error/Errors.js";
 import { RequiredError } from "../error/RequiredError.js";
 import { BLACKHOLE } from "./function.js";
-/** Is a value an asynchronous value implementing a `then()` function. */
+/**
+ * Is a value an asynchronous value implementing a `then()` function.
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a `PromiseLike`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/async/isAsync
+ */
 export function isAsync(value) {
     return typeof value === "object" && value !== null && typeof value.then === "function";
 }
-/** Is a value a synchronous value. */
+/**
+ * Is a value a synchronous value.
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is not a `PromiseLike`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/async/notAsync
+ */
 export function notAsync(value) {
     return !isAsync(value);
 }
 /**
  * Throw the value if it's an async (promised) value.
+ *
+ * @param value The value to unwrap.
  * @returns Synchronous (not promised) value.
  * @throws Promise if value is an asynchronous (promised) value.
+ * @example throwAsync(123) // 123
+ * @see https://dhoulb.github.io/shelving/util/async/throwAsync
  */
 export function throwAsync(value) {
     if (isAsync(value))
         throw value;
     return value;
 }
-/** Assert an unknown value is synchronous (i.e. does not have a `.then()` method). */
+/**
+ * Assert an unknown value is synchronous (i.e. does not have a `.then()` method).
+ *
+ * @param value The value to assert.
+ * @throws {RequiredError} If `value` is a `PromiseLike`.
+ * @example assertNotAsync(123); // passes
+ * @see https://dhoulb.github.io/shelving/util/async/assertNotAsync
+ */
 export function assertNotAsync(value) {
     if (isAsync(value))
         throw new RequiredError("Must be synchronous", { received: value, caller: assertNotAsync });
 }
-/** Assert an unknown value is asynchronous (i.e. has a `.then()` method). */
+/**
+ * Assert an unknown value is asynchronous (i.e. has a `.then()` method).
+ *
+ * @param value The value to assert.
+ * @throws {RequiredError} If `value` is not a `PromiseLike`.
+ * @example assertAsync(Promise.resolve(1)); // passes
+ * @see https://dhoulb.github.io/shelving/util/async/assertAsync
+ */
 export function assertAsync(value) {
     if (!isAsync(value))
         throw new RequiredError("Must be asynchronous", { received: value, caller: assertAsync });
 }
-/** Assert that an unknown value is a `Promise` */
+/**
+ * Assert that an unknown value is a `Promise`.
+ *
+ * @param value The value to assert.
+ * @throws {RequiredError} If `value` is not a `Promise` instance.
+ * @example assertPromise(Promise.resolve(1)); // passes
+ * @see https://dhoulb.github.io/shelving/util/async/assertPromise
+ */
 export function assertPromise(value) {
     if (!(value instanceof Promise))
         throw new RequiredError("Must be promise", { received: value, caller: assertPromise });
 }
-/** Run any queued microtasks now. */
+/**
+ * Run any queued microtasks now.
+ *
+ * @returns A promise that resolves after all currently-queued microtasks have run.
+ * @example await runMicrotasks();
+ * @see https://dhoulb.github.io/shelving/util/async/runMicrotasks
+ */
 export function runMicrotasks() {
     // Timeouts are part of the main event queue, and events in the main queue are run _after_ all microtasks complete.
     return new Promise(resolve => setTimeout(resolve));
@@ -57,6 +100,8 @@ export async function awaitValues(...promises) {
  *
  * @param promises Values (usually async, but not necessarily) that we need to wait for.
  * @returns Array of rejection reasons of all promises (or empty array if no promises threw).
+ * @example const errors = await awaitErrors(getA(), getB());
+ * @see https://dhoulb.github.io/shelving/util/async/awaitErrors
  */
 export async function awaitErrors(...promises) {
     const errors = [];
@@ -65,7 +110,15 @@ export async function awaitErrors(...promises) {
             errors.push(result.reason);
     return errors;
 }
-/** `Promise` designed for extending with `._resolve()` and `._reject()` methods that can be accessed by subclasses. */
+/**
+ * `Promise` designed for extending with `._resolve()` and `._reject()` methods that can be accessed by subclasses.
+ *
+ * @example
+ * class MyPromise extends BasePromise<number> {
+ * 	done() { this._resolve(123); }
+ * }
+ * @see https://dhoulb.github.io/shelving/util/async/BasePromise
+ */
 export class BasePromise extends Promise {
     // Make `this.then()` create a `Promise` not a `Deferred`
     // Done with a getter because some implementations implement this with a getter and we need to override it.
@@ -92,6 +145,10 @@ export class BasePromise extends Promise {
 /**
  * Create a deferred to access the `resolve()` and `reject()` functions of a promise.
  * - See https://github.com/tc39/proposal-promise-with-resolvers/
+ *
+ * @returns A `Deferred` exposing the promise and its `resolve()`/`reject()` functions.
+ * @example const { promise, resolve } = createDeferred<number>();
+ * @see https://dhoulb.github.io/shelving/util/async/createDeferred
  */
 export function createDeferred() {
     let resolve;
@@ -107,7 +164,14 @@ export function createDeferred() {
         reject: reject,
     };
 }
-/** Get a promise that automatically resolves after a delay. */
+/**
+ * Get a promise that automatically resolves after a delay.
+ *
+ * @param ms The delay in milliseconds before the promise resolves.
+ * @returns A promise that resolves with `undefined` after `ms` milliseconds.
+ * @example await getDelay(300); // resolves after 300ms
+ * @see https://dhoulb.github.io/shelving/util/async/getDelay
+ */
 export function getDelay(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -116,7 +180,11 @@ export function getDelay(ms) {
  * - Rejects immediately if the signal is already aborted.
  * - Use with `awaitRace()` to cancel a concurrent operation when a signal fires.
  *
+ * @param signal The `AbortSignal` to watch.
+ * @returns A promise that never resolves and rejects with the signal's reason when it fires.
+ * @throws The signal's `reason` when the signal aborts.
  * @example await awaitRace(getDelay(300), awaitAbort(signal));
+ * @see https://dhoulb.github.io/shelving/util/async/awaitAbort
  */
 export function awaitAbort(signal) {
     const promise = new Promise((_, reject) => {
@@ -134,7 +202,11 @@ export function awaitAbort(signal) {
  * - The losing inputs keep running (Promises cannot be cancelled), but their eventual rejection — if any — is silently absorbed instead of bubbling up as an unhandled rejection.
  * - Built for cancellation/timeout patterns, where the loser's eventual fate is genuinely uninteresting once another arm has settled. Do not use when both arms might surface meaningful errors that the caller should see.
  *
+ * @param promises The promises to race against each other.
+ * @returns A promise that settles with the first input to settle.
+ * @throws The rejection reason of the first input to settle, if it rejects.
  * @example await awaitRace(getDelay(300), awaitAbort(signal)); // delay or abort, no leaked ABORT rejection if delay wins
+ * @see https://dhoulb.github.io/shelving/util/async/awaitRace
  */
 export function awaitRace(...promises) {
     for (const promise of promises)

package/util/base64.d.ts

@@ -1,13 +1,63 @@
 import { type Bytes, type PossibleBytes } from "./bytes.js";
-/** Encode a string or binary data to Base64 string. */
+/**
+ * Encode a string or binary data to a Base64 string.
+ *
+ * @param input The string or byte data to encode.
+ * @param pad Whether to append `=` padding characters (defaults to `true`).
+ * @returns The Base64-encoded string.
+ * @throws {RequiredError} If `input` cannot be converted to a byte sequence.
+ * @example encodeBase64("abc") // "YWJj"
+ * @see https://dhoulb.github.io/shelving/util/base64/encodeBase64
+ */
 export declare function encodeBase64(input: PossibleBytes, pad?: boolean): string;
-/** Decode Base64 string to string (decodes Base64URL too). */
+/**
+ * Decode a Base64 string to a string (decodes Base64URL too).
+ *
+ * @param base64 The Base64 (or Base64URL) string to decode.
+ * @returns The decoded UTF-8 string.
+ * @throws {ValueError} If `base64` contains an invalid character.
+ * @example decodeBase64String("YWJj") // "abc"
+ * @see https://dhoulb.github.io/shelving/util/base64/decodeBase64String
+ */
 export declare function decodeBase64String(base64: string): string;
-/** Decode URL-safe Base64 string to byte sequence (decodes Base64URL too). */
+/**
+ * Decode a Base64 string to a byte sequence (decodes Base64URL too).
+ *
+ * @param base64 The Base64 (or Base64URL) string to decode.
+ * @returns The decoded byte sequence.
+ * @throws {ValueError} If `base64` contains an invalid character.
+ * @example decodeBase64Bytes("YWJj") // Uint8Array([97, 98, 99])
+ * @see https://dhoulb.github.io/shelving/util/base64/decodeBase64Bytes
+ */
 export declare function decodeBase64Bytes(base64: string): Bytes;
-/** Encode a string or binary data to URL-safe Base64 */
+/**
+ * Encode a string or binary data to a URL-safe Base64 string.
+ *
+ * @param input The string or byte data to encode.
+ * @param pad Whether to append `=` padding characters (defaults to `false`).
+ * @returns The Base64URL-encoded string.
+ * @throws {RequiredError} If `input` cannot be converted to a byte sequence.
+ * @example encodeBase64URL("abc") // "YWJj"
+ * @see https://dhoulb.github.io/shelving/util/base64/encodeBase64URL
+ */
 export declare function encodeBase64URL(input: PossibleBytes, pad?: boolean): string;
-/** Decode a string from URL-safe Base64 (decodes Base64 too). */
+/**
+ * Decode a string from a URL-safe Base64 string (decodes Base64 too).
+ *
+ * @param base64 The Base64URL (or Base64) string to decode.
+ * @returns The decoded UTF-8 string.
+ * @throws {ValueError} If `base64` contains an invalid character.
+ * @example decodeBase64URLString("YWJj") // "abc"
+ * @see https://dhoulb.github.io/shelving/util/base64/decodeBase64URLString
+ */
 export declare function decodeBase64URLString(base64: string): string;
-/** Decode URL-safe Base64 string to byte sequence (decodes Base64 too). */
+/**
+ * Decode a URL-safe Base64 string to a byte sequence (decodes Base64 too).
+ *
+ * @param base64 The Base64URL (or Base64) string to decode.
+ * @returns The decoded byte sequence.
+ * @throws {ValueError} If `base64` contains an invalid character.
+ * @example decodeBase64URLBytes("YWJj") // Uint8Array([97, 98, 99])
+ * @see https://dhoulb.github.io/shelving/util/base64/decodeBase64URLBytes
+ */
 export declare function decodeBase64URLBytes(base64: string): Bytes;

package/util/base64.js

@@ -60,27 +60,77 @@ function _lookup(base64, index, caller) {
         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. */
+/**
+ * Encode a string or binary data to a Base64 string.
+ *
+ * @param input The string or byte data to encode.
+ * @param pad Whether to append `=` padding characters (defaults to `true`).
+ * @returns The Base64-encoded string.
+ * @throws {RequiredError} If `input` cannot be converted to a byte sequence.
+ * @example encodeBase64("abc") // "YWJj"
+ * @see https://dhoulb.github.io/shelving/util/base64/encodeBase64
+ */
 export function encodeBase64(input, pad = true) {
     return _encode(requireBytes(input), BASE64_CHARS, pad ? "=" : "");
 }
-/** Decode Base64 string to string (decodes Base64URL too). */
+/**
+ * Decode a Base64 string to a string (decodes Base64URL too).
+ *
+ * @param base64 The Base64 (or Base64URL) string to decode.
+ * @returns The decoded UTF-8 string.
+ * @throws {ValueError} If `base64` contains an invalid character.
+ * @example decodeBase64String("YWJj") // "abc"
+ * @see https://dhoulb.github.io/shelving/util/base64/decodeBase64String
+ */
 export function decodeBase64String(base64) {
     return new TextDecoder("utf-8").decode(_decode(base64, decodeBase64String));
 }
-/** Decode URL-safe Base64 string to byte sequence (decodes Base64URL too). */
+/**
+ * Decode a Base64 string to a byte sequence (decodes Base64URL too).
+ *
+ * @param base64 The Base64 (or Base64URL) string to decode.
+ * @returns The decoded byte sequence.
+ * @throws {ValueError} If `base64` contains an invalid character.
+ * @example decodeBase64Bytes("YWJj") // Uint8Array([97, 98, 99])
+ * @see https://dhoulb.github.io/shelving/util/base64/decodeBase64Bytes
+ */
 export function decodeBase64Bytes(base64) {
     return _decode(base64, decodeBase64Bytes);
 }
-/** Encode a string or binary data to URL-safe Base64 */
+/**
+ * Encode a string or binary data to a URL-safe Base64 string.
+ *
+ * @param input The string or byte data to encode.
+ * @param pad Whether to append `=` padding characters (defaults to `false`).
+ * @returns The Base64URL-encoded string.
+ * @throws {RequiredError} If `input` cannot be converted to a byte sequence.
+ * @example encodeBase64URL("abc") // "YWJj"
+ * @see https://dhoulb.github.io/shelving/util/base64/encodeBase64URL
+ */
 export function encodeBase64URL(input, pad = false) {
     return _encode(requireBytes(input), BASE64URL_CHARS, pad ? "=" : "");
 }
-/** Decode a string from URL-safe Base64 (decodes Base64 too). */
+/**
+ * Decode a string from a URL-safe Base64 string (decodes Base64 too).
+ *
+ * @param base64 The Base64URL (or Base64) string to decode.
+ * @returns The decoded UTF-8 string.
+ * @throws {ValueError} If `base64` contains an invalid character.
+ * @example decodeBase64URLString("YWJj") // "abc"
+ * @see https://dhoulb.github.io/shelving/util/base64/decodeBase64URLString
+ */
 export function decodeBase64URLString(base64) {
     return new TextDecoder("utf-8").decode(_decode(base64, decodeBase64URLString));
 }
-/** Decode URL-safe Base64 string to byte sequence (decodes Base64 too). */
+/**
+ * Decode a URL-safe Base64 string to a byte sequence (decodes Base64 too).
+ *
+ * @param base64 The Base64URL (or Base64) string to decode.
+ * @returns The decoded byte sequence.
+ * @throws {ValueError} If `base64` contains an invalid character.
+ * @example decodeBase64URLBytes("YWJj") // Uint8Array([97, 98, 99])
+ * @see https://dhoulb.github.io/shelving/util/base64/decodeBase64URLBytes
+ */
 export function decodeBase64URLBytes(base64) {
     return _decode(base64, decodeBase64URLBytes);
 }

package/util/boolean.d.ts

@@ -1,21 +1,86 @@
 import type { AnyCaller } from "./function.js";
-/** Is a value a boolean? */
+/**
+ * Is an unknown value a boolean?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a `boolean`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/boolean/isBoolean
+ */
 export declare function isBoolean(value: unknown): value is boolean;
-/** Is a value true? */
+/**
+ * Is an unknown value exactly `true`?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is the literal `true`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/boolean/isTrue
+ */
 export declare function isTrue(value: unknown): value is true;
-/** Is a value false? */
+/**
+ * Is an unknown value exactly `false`?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is the literal `false`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/boolean/isFalse
+ */
 export declare function isFalse(value: unknown): value is false;
-/** Is a value truthy? */
+/**
+ * Is an unknown value truthy?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` coerces to `true`.
+ * @see https://dhoulb.github.io/shelving/util/boolean/isTruthy
+ */
 export declare function isTruthy(value: unknown): boolean;
-/** Is a value falsey? */
+/**
+ * Is an unknown value falsey?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` coerces to `false`.
+ * @see https://dhoulb.github.io/shelving/util/boolean/isFalsey
+ */
 export declare function isFalsey(value: unknown): boolean;
-/** Assert that a value is a boolean. */
+/**
+ * Assert that an unknown value is a boolean.
+ *
+ * @param value The value to assert.
+ * @param caller Function to attribute a thrown error to (defaults to `assertBoolean` itself).
+ * @throws {RequiredError} If `value` is not a `boolean`.
+ * @see https://dhoulb.github.io/shelving/util/boolean/assertBoolean
+ */
 export declare function assertBoolean(value: unknown, caller?: AnyCaller): asserts value is boolean;
-/** Assert that a value is true. */
+/**
+ * Assert that an unknown value is exactly `true`.
+ *
+ * @param value The value to assert.
+ * @param caller Function to attribute a thrown error to (defaults to `assertTrue` itself).
+ * @throws {RequiredError} If `value` is not the literal `true`.
+ * @see https://dhoulb.github.io/shelving/util/boolean/assertTrue
+ */
 export declare function assertTrue(value: unknown, caller?: AnyCaller): asserts value is true;
-/** Assert that a value is false. */
+/**
+ * Assert that an unknown value is exactly `false`.
+ *
+ * @param value The value to assert.
+ * @param caller Function to attribute a thrown error to (defaults to `assertFalse` itself).
+ * @throws {RequiredError} If `value` is not the literal `false`.
+ * @see https://dhoulb.github.io/shelving/util/boolean/assertFalse
+ */
 export declare function assertFalse(value: unknown, caller?: AnyCaller): asserts value is false;
-/** Assert that a value is truthy. */
+/**
+ * Assert that an unknown value is truthy.
+ *
+ * @param value The value to assert.
+ * @param caller Function to attribute a thrown error to (defaults to `assertTruthy` itself).
+ * @throws {RequiredError} If `value` is falsey.
+ * @see https://dhoulb.github.io/shelving/util/boolean/assertTruthy
+ */
 export declare function assertTruthy(value: unknown, caller?: AnyCaller): asserts value is true;
-/** Assert that a value is falsy. */
+/**
+ * Assert that an unknown value is falsy.
+ *
+ * @param value The value to assert.
+ * @param caller Function to attribute a thrown error to (defaults to `assertFalsy` itself).
+ * @throws {RequiredError} If `value` is truthy.
+ * @see https://dhoulb.github.io/shelving/util/boolean/assertFalsy
+ */
 export declare function assertFalsy(value: unknown, caller?: AnyCaller): asserts value is false;

package/util/boolean.js

@@ -1,45 +1,110 @@
 import { RequiredError } from "../error/RequiredError.js";
-/** Is a value a boolean? */
+/**
+ * Is an unknown value a boolean?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a `boolean`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/boolean/isBoolean
+ */
 export function isBoolean(value) {
     return typeof value === "boolean";
 }
-/** Is a value true? */
+/**
+ * Is an unknown value exactly `true`?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is the literal `true`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/boolean/isTrue
+ */
 export function isTrue(value) {
     return value === true;
 }
-/** Is a value false? */
+/**
+ * Is an unknown value exactly `false`?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is the literal `false`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/boolean/isFalse
+ */
 export function isFalse(value) {
     return value === false;
 }
-/** Is a value truthy? */
+/**
+ * Is an unknown value truthy?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` coerces to `true`.
+ * @see https://dhoulb.github.io/shelving/util/boolean/isTruthy
+ */
 export function isTruthy(value) {
     return !!value;
 }
-/** Is a value falsey? */
+/**
+ * Is an unknown value falsey?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` coerces to `false`.
+ * @see https://dhoulb.github.io/shelving/util/boolean/isFalsey
+ */
 export function isFalsey(value) {
     return !value;
 }
-/** Assert that a value is a boolean. */
+/**
+ * Assert that an unknown value is a boolean.
+ *
+ * @param value The value to assert.
+ * @param caller Function to attribute a thrown error to (defaults to `assertBoolean` itself).
+ * @throws {RequiredError} If `value` is not a `boolean`.
+ * @see https://dhoulb.github.io/shelving/util/boolean/assertBoolean
+ */
 export function assertBoolean(value, caller = assertBoolean) {
     if (typeof value !== "boolean")
         throw new RequiredError("Must be boolean", { received: value, caller });
 }
-/** Assert that a value is true. */
+/**
+ * Assert that an unknown value is exactly `true`.
+ *
+ * @param value The value to assert.
+ * @param caller Function to attribute a thrown error to (defaults to `assertTrue` itself).
+ * @throws {RequiredError} If `value` is not the literal `true`.
+ * @see https://dhoulb.github.io/shelving/util/boolean/assertTrue
+ */
 export function assertTrue(value, caller = assertTrue) {
     if (value !== true)
         throw new RequiredError("Must be true", { received: value, caller });
 }
-/** Assert that a value is false. */
+/**
+ * Assert that an unknown value is exactly `false`.
+ *
+ * @param value The value to assert.
+ * @param caller Function to attribute a thrown error to (defaults to `assertFalse` itself).
+ * @throws {RequiredError} If `value` is not the literal `false`.
+ * @see https://dhoulb.github.io/shelving/util/boolean/assertFalse
+ */
 export function assertFalse(value, caller = assertFalse) {
     if (value !== false)
         throw new RequiredError("Must be false", { received: value, caller });
 }
-/** Assert that a value is truthy. */
+/**
+ * Assert that an unknown value is truthy.
+ *
+ * @param value The value to assert.
+ * @param caller Function to attribute a thrown error to (defaults to `assertTruthy` itself).
+ * @throws {RequiredError} If `value` is falsey.
+ * @see https://dhoulb.github.io/shelving/util/boolean/assertTruthy
+ */
 export function assertTruthy(value, caller = assertTruthy) {
     if (!value)
         throw new RequiredError("Must be truthy", { received: value, caller });
 }
-/** Assert that a value is falsy. */
+/**
+ * Assert that an unknown value is falsy.
+ *
+ * @param value The value to assert.
+ * @param caller Function to attribute a thrown error to (defaults to `assertFalsy` itself).
+ * @throws {RequiredError} If `value` is truthy.
+ * @see https://dhoulb.github.io/shelving/util/boolean/assertFalsy
+ */
 export function assertFalsy(value, caller = assertFalsy) {
     if (value)
         throw new RequiredError("Must be falsy", { received: value, caller });

package/util/buffer.d.ts

@@ -1,7 +1,30 @@
+/**
+ * Union of the numeric `TypedArray` views over an `ArrayBufferLike` (excludes `DataView`).
+ *
+ * @see https://dhoulb.github.io/shelving/util/buffer/TypedArray
+ */
 export type TypedArray<T extends ArrayBufferLike = ArrayBufferLike> = Uint8Array<T> | Uint16Array<T> | Uint32Array<T> | Int8Array<T> | Int16Array<T> | Int32Array<T> | Float32Array<T> | Float64Array<T>;
-/** Detect if an unknown value is an `ArrayBuffer` (not a view like `Uint8Array` or `Float32Array` or `DataView`). */
+/**
+ * Detect if an unknown value is an `ArrayBuffer` (not a view like `Uint8Array` or `Float32Array` or `DataView`).
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is an `ArrayBuffer`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/buffer/isBuffer
+ */
 export declare function isBuffer(value: unknown): value is ArrayBuffer;
-/** Detect if an unknown value is an `ArrayBufferView`, like `Uint8Array` or `Float32Array` or `DataView` */
+/**
+ * Detect if an unknown value is an `ArrayBufferView`, like `Uint8Array` or `Float32Array` or `DataView`.
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is an `ArrayBufferView`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/buffer/isBufferView
+ */
 export declare function isBufferView(value: unknown): value is ArrayBufferView;
-/** Detect if an unknown value is a `TypedArray`, like `Uint8Array` or `Float32Array` (not including `DataView`). */
+/**
+ * Detect if an unknown value is a `TypedArray`, like `Uint8Array` or `Float32Array` (not including `DataView`).
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a numeric `TypedArray`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/buffer/isTypedArray
+ */
 export declare function isTypedArray(value: unknown): value is TypedArray;

package/util/buffer.js

@@ -1,12 +1,30 @@
-/** Detect if an unknown value is an `ArrayBuffer` (not a view like `Uint8Array` or `Float32Array` or `DataView`). */
+/**
+ * Detect if an unknown value is an `ArrayBuffer` (not a view like `Uint8Array` or `Float32Array` or `DataView`).
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is an `ArrayBuffer`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/buffer/isBuffer
+ */
 export function isBuffer(value) {
     return value instanceof ArrayBuffer;
 }
-/** Detect if an unknown value is an `ArrayBufferView`, like `Uint8Array` or `Float32Array` or `DataView` */
+/**
+ * Detect if an unknown value is an `ArrayBufferView`, like `Uint8Array` or `Float32Array` or `DataView`.
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is an `ArrayBufferView`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/buffer/isBufferView
+ */
 export function isBufferView(value) {
     return ArrayBuffer.isView(value);
 }
-/** Detect if an unknown value is a `TypedArray`, like `Uint8Array` or `Float32Array` (not including `DataView`). */
+/**
+ * Detect if an unknown value is a `TypedArray`, like `Uint8Array` or `Float32Array` (not including `DataView`).
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a numeric `TypedArray`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/buffer/isTypedArray
+ */
 export function isTypedArray(value) {
     return value instanceof Object.getPrototypeOf(Uint8Array);
 }

package/util/bytes.d.ts

@@ -1,11 +1,35 @@
 import type { AnyCaller } from "./function.js";
-/** We store a sets of bytes as a `Uint8Array` byte sequence. */
+/**
+ * A set of bytes stored as a `Uint8Array` byte sequence backed by an `ArrayBuffer`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/bytes/Bytes
+ */
 export type Bytes = Uint8Array<ArrayBuffer>;
-/** Types that can be converted to a `Uint8Array` byte sequence. */
+/**
+ * Types that can be converted to a `Uint8Array` byte sequence.
+ *
+ * @see https://dhoulb.github.io/shelving/util/bytes/PossibleBytes
+ */
 export type PossibleBytes = Bytes | ArrayBuffer | string;
-/** 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 declare function isBytes(value: unknown): value is Bytes;
-/** 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 declare function assertBytes(value: unknown, min?: number, max?: number, caller?: AnyCaller): asserts value is Bytes;
 /**
  * Convert an unknown value to a `Uint8Array<ArrayBuffer>` byte sequence, or `undefined` if the value cannot be converted.
@@ -14,9 +38,23 @@ export declare function assertBytes(value: unknown, min?: number, max?: number,
  * - `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 declare function getBytes(value: unknown): Uint8Array<ArrayBuffer> | undefined;
 /**
  * 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 declare function requireBytes(value: PossibleBytes, min?: number, max?: number, caller?: AnyCaller): Uint8Array<ArrayBuffer>;