shelving 1.236.0 → 1.236.2

package/util/dispose.d.ts

@@ -9,6 +9,8 @@ import { type Nullish } from "./null.js";
  * - `Nullish` values are skipped (for convenience).
  *
  * @throws {Errors} Error that aggregates all the disposal errors.
+ * @example dispose(resource, () => clearTimeout(id)) // disposes both, even if one throws
+ * @see https://dhoulb.github.io/shelving/util/dispose/dispose
  */
 export declare function dispose(...values: Nullish<Disposable | Callback>[]): void;
 /**
@@ -21,12 +23,27 @@ export declare function dispose(...values: Nullish<Disposable | Callback>[]): vo
  *
  * @throws {Errors} Error that aggregates all the disposal errors.
  *
+ * @example await awaitDispose(asyncResource, promise, () => cleanup()) // disposes all in parallel
+ * @see https://dhoulb.github.io/shelving/util/dispose/awaitDispose
+ *
  * @todo Potentially rewrite this to use `AsyncDisposableStack` internally.
  */
 export declare function awaitDispose(...values: Nullish<AsyncDisposable | Disposable | Callback | Promise<unknown>>[]): Promise<void>;
-/** Is an unknown value a disposable object? */
+/**
+ * Is an unknown value a disposable object?
+ *
+ * @param v The value to test.
+ * @returns `true` if `v` has a `[Symbol.dispose]` method, narrowing its type to `Disposable`.
+ * @see https://dhoulb.github.io/shelving/util/dispose/isDisposable
+ */
 export declare function isDisposable(v: unknown): v is Disposable;
-/** Is an unknown value an async disposable object? */
+/**
+ * Is an unknown value an async disposable object?
+ *
+ * @param v The value to test.
+ * @returns `true` if `v` has a `[Symbol.asyncDispose]` method, narrowing its type to `AsyncDisposable`.
+ * @see https://dhoulb.github.io/shelving/util/dispose/isAsyncDisposable
+ */
 export declare function isAsyncDisposable(v: unknown): v is AsyncDisposable;
 /**
  * Version of `Map` that has disposable values.
@@ -34,11 +51,43 @@ export declare function isAsyncDisposable(v: unknown): v is AsyncDisposable;
  * - Values are disposed when they're deleted from the map.
  * - Values are disposed when all items are cleared.
  * - All items are cleared and their values are disposed when this map itself is disposed.
+ *
+ * @see https://dhoulb.github.io/shelving/util/dispose/DisposableMap
  */
 export declare class DisposableMap<K, T extends Disposable> extends Map<K, T> implements Disposable {
+    /**
+     * Set a key to a value, disposing any previous value stored under that key.
+     *
+     * @param key The key to set.
+     * @param value The disposable value to store.
+     * @returns This map, for chaining.
+     * @example map.set("a", resource) // disposes the old "a" value if it differs
+     * @see https://dhoulb.github.io/shelving/util/dispose/DisposableMap/set
+     */
     set(key: K, value: T): this;
+    /**
+     * Delete a key, disposing its value.
+     *
+     * @param key The key to delete.
+     * @returns `true` if a value existed and was deleted, otherwise `false`.
+     * @example map.delete("a") // disposes the "a" value
+     * @see https://dhoulb.github.io/shelving/util/dispose/DisposableMap/delete
+     */
     delete(key: K): boolean;
+    /**
+     * Clear all items, disposing every value.
+     *
+     * @returns Nothing.
+     * @example map.clear() // disposes every value
+     * @see https://dhoulb.github.io/shelving/util/dispose/DisposableMap/clear
+     */
     clear(): void;
+    /**
+     * Dispose this map by clearing all items and disposing their values.
+     *
+     * @returns Nothing.
+     * @see https://dhoulb.github.io/shelving/util/dispose/DisposableMap/dispose
+     */
     [Symbol.dispose](): void;
 }
 /**
@@ -46,9 +95,32 @@ export declare class DisposableMap<K, T extends Disposable> extends Map<K, T> im
  * - Values are disposed when they're deleted from the map.
  * - Values are disposed when all items are cleared.
  * - All items are cleared (and disposed) when this map itself is disposed.
+ *
+ * @see https://dhoulb.github.io/shelving/util/dispose/DisposableSet
  */
 export declare class DisposableSet<T extends Disposable> extends Set<T> implements Disposable {
+    /**
+     * Delete an item, disposing it.
+     *
+     * @param item The item to delete.
+     * @returns `true` if the item existed and was deleted, otherwise `false`.
+     * @example set.delete(resource) // disposes the item
+     * @see https://dhoulb.github.io/shelving/util/dispose/DisposableSet/delete
+     */
     delete(item: T): boolean;
+    /**
+     * Clear all items, disposing each one.
+     *
+     * @returns Nothing.
+     * @example set.clear() // disposes every item
+     * @see https://dhoulb.github.io/shelving/util/dispose/DisposableSet/clear
+     */
     clear(): void;
+    /**
+     * Dispose this set by clearing all items and disposing each one.
+     *
+     * @returns Nothing.
+     * @see https://dhoulb.github.io/shelving/util/dispose/DisposableSet/dispose
+     */
     [Symbol.dispose](): void;
 }

package/util/dispose.js

@@ -18,6 +18,8 @@ Symbol.asyncDispose ??= Symbol("Symbol.asyncDispose");
  * - `Nullish` values are skipped (for convenience).
  *
  * @throws {Errors} Error that aggregates all the disposal errors.
+ * @example dispose(resource, () => clearTimeout(id)) // disposes both, even if one throws
+ * @see https://dhoulb.github.io/shelving/util/dispose/dispose
  */
 export function dispose(...values) {
     const errors = [];
@@ -47,6 +49,9 @@ export function dispose(...values) {
  *
  * @throws {Errors} Error that aggregates all the disposal errors.
  *
+ * @example await awaitDispose(asyncResource, promise, () => cleanup()) // disposes all in parallel
+ * @see https://dhoulb.github.io/shelving/util/dispose/awaitDispose
+ *
  * @todo Potentially rewrite this to use `AsyncDisposableStack` internally.
  */
 export async function awaitDispose(...values) {
@@ -64,11 +69,23 @@ async function _disposeAsync(value) {
     else if (isFunction(value))
         value();
 }
-/** Is an unknown value a disposable object? */
+/**
+ * Is an unknown value a disposable object?
+ *
+ * @param v The value to test.
+ * @returns `true` if `v` has a `[Symbol.dispose]` method, narrowing its type to `Disposable`.
+ * @see https://dhoulb.github.io/shelving/util/dispose/isDisposable
+ */
 export function isDisposable(v) {
     return isObject(v) && typeof v[Symbol.dispose] === "function";
 }
-/** Is an unknown value an async disposable object? */
+/**
+ * Is an unknown value an async disposable object?
+ *
+ * @param v The value to test.
+ * @returns `true` if `v` has a `[Symbol.asyncDispose]` method, narrowing its type to `AsyncDisposable`.
+ * @see https://dhoulb.github.io/shelving/util/dispose/isAsyncDisposable
+ */
 export function isAsyncDisposable(v) {
     return isObject(v) && typeof v[Symbol.asyncDispose] === "function";
 }
@@ -78,24 +95,56 @@ export function isAsyncDisposable(v) {
  * - Values are disposed when they're deleted from the map.
  * - Values are disposed when all items are cleared.
  * - All items are cleared and their values are disposed when this map itself is disposed.
+ *
+ * @see https://dhoulb.github.io/shelving/util/dispose/DisposableMap
  */
 export class DisposableMap extends Map {
+    /**
+     * Set a key to a value, disposing any previous value stored under that key.
+     *
+     * @param key The key to set.
+     * @param value The disposable value to store.
+     * @returns This map, for chaining.
+     * @example map.set("a", resource) // disposes the old "a" value if it differs
+     * @see https://dhoulb.github.io/shelving/util/dispose/DisposableMap/set
+     */
     set(key, value) {
         const previous = this.get(key);
         if (previous && previous !== value)
             dispose(previous);
         return super.set(key, value);
     }
+    /**
+     * Delete a key, disposing its value.
+     *
+     * @param key The key to delete.
+     * @returns `true` if a value existed and was deleted, otherwise `false`.
+     * @example map.delete("a") // disposes the "a" value
+     * @see https://dhoulb.github.io/shelving/util/dispose/DisposableMap/delete
+     */
     delete(key) {
         const value = this.get(key);
         if (value)
             dispose(value);
         return super.delete(key);
     }
+    /**
+     * Clear all items, disposing every value.
+     *
+     * @returns Nothing.
+     * @example map.clear() // disposes every value
+     * @see https://dhoulb.github.io/shelving/util/dispose/DisposableMap/clear
+     */
     clear() {
         dispose(...this.values());
         super.clear();
     }
+    /**
+     * Dispose this map by clearing all items and disposing their values.
+     *
+     * @returns Nothing.
+     * @see https://dhoulb.github.io/shelving/util/dispose/DisposableMap/dispose
+     */
     [Symbol.dispose]() {
         this.clear();
     }
@@ -105,17 +154,40 @@ export class DisposableMap extends Map {
  * - Values are disposed when they're deleted from the map.
  * - Values are disposed when all items are cleared.
  * - All items are cleared (and disposed) when this map itself is disposed.
+ *
+ * @see https://dhoulb.github.io/shelving/util/dispose/DisposableSet
  */
 export class DisposableSet extends Set {
+    /**
+     * Delete an item, disposing it.
+     *
+     * @param item The item to delete.
+     * @returns `true` if the item existed and was deleted, otherwise `false`.
+     * @example set.delete(resource) // disposes the item
+     * @see https://dhoulb.github.io/shelving/util/dispose/DisposableSet/delete
+     */
     delete(item) {
         if (this.has(item))
             dispose(item);
         return super.delete(item);
     }
+    /**
+     * Clear all items, disposing each one.
+     *
+     * @returns Nothing.
+     * @example set.clear() // disposes every item
+     * @see https://dhoulb.github.io/shelving/util/dispose/DisposableSet/clear
+     */
     clear() {
         dispose(...this);
         super.clear();
     }
+    /**
+     * Dispose this set by clearing all items and disposing each one.
+     *
+     * @returns Nothing.
+     * @see https://dhoulb.github.io/shelving/util/dispose/DisposableSet/dispose
+     */
     [Symbol.dispose]() {
         this.clear();
     }

package/util/duration.d.ts

@@ -3,101 +3,316 @@ import type { FormatOptions, UnitFormatOptions } from "./format.js";
 import type { AnyCaller } from "./function.js";
 import type { MapKey } from "./map.js";
 import { type Unit, UnitList } from "./units.js";
-/** Duration data object. */
+/**
+ * Duration data object keyed by `Intl.DurationFormatUnit`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/duration/DurationData
+ */
 export type DurationData = {
     [K in Intl.DurationFormatUnit]?: number;
 };
-/** Get the millisecond difference between two dates. */
+/**
+ * Get the millisecond difference between two dates.
+ *
+ * @param from Date the duration is measured from (defaults to now).
+ * @param to Date the duration is measured to (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getMilliseconds` itself).
+ * @returns Number of milliseconds from `from` to `to` (negative if `to` is before `from`).
+ * @throws {RequiredError} If `from` or `to` cannot be converted to a valid date.
+ * @example getMilliseconds("2025-01-01", "2025-01-02") // 86400000
+ * @see https://dhoulb.github.io/shelving/util/duration/getMilliseconds
+ */
 export declare function getMilliseconds(from?: PossibleDate, to?: PossibleDate, caller?: AnyCaller): number;
-/** Count the various time units between two dates and return a `Duration` format. */
+/**
+ * Count the various time units between two dates and return a `Duration` format.
+ *
+ * @param from Date the duration is measured from (defaults to now).
+ * @param to Date the duration is measured to (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getDuration` itself).
+ * @returns `DurationData` object breaking the span down into years, months, weeks, days, hours, minutes, seconds, and milliseconds.
+ * @throws {RequiredError} If `from` or `to` cannot be converted to a valid date.
+ * @example getDuration("2025-01-01", "2025-01-02") // { years: 0, months: 0, weeks: 0, days: 1, ... }
+ * @see https://dhoulb.github.io/shelving/util/duration/getDuration
+ */
 export declare function getDuration(from?: PossibleDate, to?: PossibleDate, caller?: AnyCaller): DurationData;
-/** Get the various time units until a certain date. */
+/**
+ * Get the various time units until a certain date.
+ *
+ * @param target Date the duration counts up to.
+ * @param current Date the duration counts from (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getUntil` itself).
+ * @returns `DurationData` object for the span from `current` to `target`.
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getUntil("2099-01-01") // { years: 73, ... }
+ * @see https://dhoulb.github.io/shelving/util/duration/getUntil
+ */
 export declare function getUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): DurationData;
-/** Get the various time units since a certain date. */
+/**
+ * Get the various time units since a certain date.
+ *
+ * @param target Date the duration counts back from.
+ * @param current Date the duration counts to (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getAgo` itself).
+ * @returns `DurationData` object for the span from `target` to `current`.
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getAgo("2000-01-01") // { years: 26, ... }
+ * @see https://dhoulb.github.io/shelving/util/duration/getAgo
+ */
 export declare function getAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): DurationData;
-/** Count the milliseconds until a date. */
+/**
+ * Count the milliseconds until a date.
+ *
+ * @param target Date to count up to.
+ * @param current Date to count from (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getMillisecondsUntil` itself).
+ * @returns Number of milliseconds from `current` to `target` (negative if `target` is in the past).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getMillisecondsUntil("2099-01-01") // 2303683200000
+ * @see https://dhoulb.github.io/shelving/util/duration/getMillisecondsUntil
+ */
 export declare function getMillisecondsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
-/** Count the milliseconds since a date. */
+/**
+ * Count the milliseconds since a date.
+ *
+ * @param target Date to count back from.
+ * @param current Date to count to (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getMillisecondsAgo` itself).
+ * @returns Number of milliseconds from `target` to `current` (negative if `target` is in the future).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getMillisecondsAgo("2000-01-01") // 833587200000
+ * @see https://dhoulb.github.io/shelving/util/duration/getMillisecondsAgo
+ */
 export declare function getMillisecondsAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /**
  * Count the whole seconds until a date.
  * - Rounds to the nearest whole second, i.e. `1 second 499 ms` returns `1`
+ *
+ * @param target Date to count up to.
+ * @param current Date to count from (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getSecondsUntil` itself).
+ * @returns Number of whole seconds from `current` to `target` (negative if `target` is in the past).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getSecondsUntil(target) // 90
+ * @see https://dhoulb.github.io/shelving/util/duration/getSecondsUntil
  */
 export declare function getSecondsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /**
  * Count the whole seconds since a date.
  * - Rounds to the nearest whole second, i.e. `1 second 499 ms` returns `1`
+ *
+ * @param target Date to count back from.
+ * @param current Date to count to (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getSecondsAgo` itself).
+ * @returns Number of whole seconds from `target` to `current` (negative if `target` is in the future).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getSecondsAgo(target) // 90
+ * @see https://dhoulb.github.io/shelving/util/duration/getSecondsAgo
  */
 export declare function getSecondsAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /**
  * Count the whole minutes until a date.
  * - Rounds to the nearest whole minute, i.e. `1 min 29 seconds` returns `1`
+ *
+ * @param target Date to count up to.
+ * @param current Date to count from (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getMinutesUntil` itself).
+ * @returns Number of whole minutes from `current` to `target` (negative if `target` is in the past).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getMinutesUntil(target) // 5
+ * @see https://dhoulb.github.io/shelving/util/duration/getMinutesUntil
  */
 export declare function getMinutesUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /**
  * Count the whole minutes since a date.
  * - Rounds to the nearest whole minute, i.e. `1 min 29 seconds` returns `1`
+ *
+ * @param target Date to count back from.
+ * @param current Date to count to (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getMinutesAgo` itself).
+ * @returns Number of whole minutes from `target` to `current` (negative if `target` is in the future).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getMinutesAgo(target) // 5
+ * @see https://dhoulb.github.io/shelving/util/duration/getMinutesAgo
  */
 export declare function getMinutesAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /**
  * Count the whole hours until a date.
  * - Rounds to the nearest whole hour, i.e. `1 hour 29 minutes` returns `1`
+ *
+ * @param target Date to count up to.
+ * @param current Date to count from (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getHoursUntil` itself).
+ * @returns Number of whole hours from `current` to `target` (negative if `target` is in the past).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getHoursUntil(target) // 3
+ * @see https://dhoulb.github.io/shelving/util/duration/getHoursUntil
  */
 export declare function getHoursUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /**
  * Count the whole hours since a date.
  * - Rounds to the nearest whole hour, i.e. `1 hour 29 minutes` returns `1`
+ *
+ * @param target Date to count back from.
+ * @param current Date to count to (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getHoursAgo` itself).
+ * @returns Number of whole hours from `target` to `current` (negative if `target` is in the future).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getHoursAgo(target) // 3
+ * @see https://dhoulb.github.io/shelving/util/duration/getHoursAgo
  */
 export declare function getHoursAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /**
  * Count the calendar days until a date.
  * - e.g. from 23:59 to 00:01 is 1 day, even though it's only 1 minutes.
+ *
+ * @param target Date to count up to.
+ * @param current Date to count from (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getDaysUntil` itself).
+ * @returns Number of calendar days from `current` to `target` (negative if `target` is in the past).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getDaysUntil(target) // 13
+ * @see https://dhoulb.github.io/shelving/util/duration/getDaysUntil
  */
 export declare function getDaysUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /**
  * Count the calendar days since a date.
  * - Rounds to the nearest whole days.
+ *
+ * @param target Date to count back from.
+ * @param current Date to count to (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getDaysAgo` itself).
+ * @returns Number of calendar days from `target` to `current` (negative if `target` is in the future).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getDaysAgo(target) // 13
+ * @see https://dhoulb.github.io/shelving/util/duration/getDaysAgo
  */
 export declare function getDaysAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /**
  * Count the whole weeks until a date.
  * - Rounds down to the nearest whole week, i.e.
+ *
+ * @param target Date to count up to.
+ * @param current Date to count from (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getWeeksUntil` itself).
+ * @returns Number of whole weeks from `current` to `target` (negative if `target` is in the past).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getWeeksUntil(target) // 9
+ * @see https://dhoulb.github.io/shelving/util/duration/getWeeksUntil
  */
 export declare function getWeeksUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /**
  * Count the whole weeks since a date.
  * - Rounds to the nearest whole week.
+ *
+ * @param target Date to count back from.
+ * @param current Date to count to (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getWeeksAgo` itself).
+ * @returns Number of whole weeks from `target` to `current` (negative if `target` is in the future).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getWeeksAgo(target) // 9
+ * @see https://dhoulb.github.io/shelving/util/duration/getWeeksAgo
  */
 export declare function getWeeksAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /**
  * Count the calendar months until a date.
  * - e.g. from March 31st to April 1st is 1 month, even though it's only 1 day.
+ *
+ * @param target Date to count up to.
+ * @param current Date to count from (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getMonthsUntil` itself).
+ * @returns Number of calendar months from `current` to `target` (negative if `target` is in the past).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getMonthsUntil(target) // 14
+ * @see https://dhoulb.github.io/shelving/util/duration/getMonthsUntil
  */
 export declare function getMonthsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /**
  * Count the calendar months since a date.
  * - e.g. from March 31st to April 1st is 1 month, even though it's only 1 day.
+ *
+ * @param target Date to count back from.
+ * @param current Date to count to (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getMonthsAgo` itself).
+ * @returns Number of calendar months from `target` to `current` (negative if `target` is in the future).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getMonthsAgo(target) // 14
+ * @see https://dhoulb.github.io/shelving/util/duration/getMonthsAgo
  */
 export declare function getMonthsAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /**
  * Count the calendar years until a date.
  * - e.g. from December 31st to January 1st is 1 year, even though it's only 1 day.
+ *
+ * @param target Date to count up to.
+ * @param current Date to count from (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getYearsUntil` itself).
+ * @returns Number of calendar years from `current` to `target` (negative if `target` is in the past).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getYearsUntil(target) // 2
+ * @see https://dhoulb.github.io/shelving/util/duration/getYearsUntil
  */
 export declare function getYearsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
 /**
  * Count the calendar years since a date.
  * - Note this counts calendar years, not 365-day periods.
  * - e.g. from December 31st to January 1st is -1 years, even though it's only 1 day.
+ *
+ * @param target Date to count back from.
+ * @param current Date to count to (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `getYearsAgo` itself).
+ * @returns Number of calendar years from `target` to `current` (negative if `target` is in the future).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example getYearsAgo(target) // 2
+ * @see https://dhoulb.github.io/shelving/util/duration/getYearsAgo
  */
 export declare function getYearsAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
-/** Is a date in the past? */
+/**
+ * Is a date in the past?
+ *
+ * @param target Date to test.
+ * @param current Date to test against (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `isPast` itself).
+ * @returns `true` if `target` is before `current`.
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example isPast("2000-01-01") // true
+ * @see https://dhoulb.github.io/shelving/util/duration/isPast
+ */
 export declare function isPast(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
-/** Is a date in the future? */
+/**
+ * Is a date in the future?
+ *
+ * @param target Date to test.
+ * @param current Date to test against (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `isFuture` itself).
+ * @returns `true` if `target` is after `current`.
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example isFuture("2099-01-01") // true
+ * @see https://dhoulb.github.io/shelving/util/duration/isFuture
+ */
 export declare function isFuture(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
-/** Is a date today (taking into account midnight). */
+/**
+ * Is a date today (taking into account midnight).
+ *
+ * @param target Date to test.
+ * @param current Date to test against (defaults to now).
+ * @param caller Function to attribute a thrown error to (defaults to `isToday` itself).
+ * @returns `true` if `target` falls on the same calendar day as `current`.
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example isToday(new Date()) // true
+ * @see https://dhoulb.github.io/shelving/util/duration/isToday
+ */
 export declare function isToday(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
-/** Duration units. */
+/**
+ * List of duration units (`millisecond` through `year`) keyed by unit reference.
+ *
+ * @see https://dhoulb.github.io/shelving/util/duration/DURATION_UNITS
+ */
 export declare const DURATION_UNITS: UnitList<"day" | "hour" | "millisecond" | "minute" | "month" | "second" | "week" | "year">;
+/**
+ * Key for one of the duration units in `DURATION_UNITS`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/duration/DurationUnitKey
+ */
 export type DurationUnitKey = MapKey<typeof DURATION_UNITS>;
 /**
  * Get a best-fit duration unit based on an amount in milliseconds.
@@ -109,20 +324,67 @@ export type DurationUnitKey = MapKey<typeof DURATION_UNITS>;
  * - Hours will be used for anything 1 hour or more, e.g. `in 23 hours`
  * - Minutes will be used for anything 1 minute or more, e.g. `1 minute ago` or `in 59 minutes`
  * - Seconds will be used for anything 1000 milliseconds or more, e.g. `in 59 seconds`
+ *
+ * @param ms Amount of time in milliseconds (the sign is ignored, only the magnitude matters).
+ * @returns The best-fit `Unit` from `DURATION_UNITS` for the given magnitude.
+ * @example getBestDurationUnit(90000).key // "minute"
+ * @see https://dhoulb.github.io/shelving/util/duration/getBestDurationUnit
  */
 export declare function getBestDurationUnit(ms: number): Unit<DurationUnitKey>;
 /**
- * Compact best-fit when a date happens/happened, e.g. `in 10d` or `2h ago` or `in 1w` or `just now`
- * - See `getBestTimeUnit()` for details on how the best-fit unit is chosen.
+ * Format a compact best-fit description of when a date happens or happened, e.g. `in 10d` or `2h ago` or `in 1w` or `just now`
+ * - See `getBestDurationUnit()` for details on how the best-fit unit is chosen.
  * - But: anything under 30 seconds will show `just now`, which makes more sense in most UIs.
+ *
+ * @param target Date the duration is measured to.
+ * @param current Date the duration is measured from (defaults to now).
+ * @param options Formatting options for the chosen duration unit.
+ * @param caller Function to attribute a thrown error to (defaults to `formatWhen` itself).
+ * @returns Compact string like `in 10d`, `2h ago`, or `just now`.
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example formatWhen("2099-01-01") // "in 73 years"
+ * @see https://dhoulb.github.io/shelving/util/duration/formatWhen
  */
 export declare function formatWhen(target: PossibleDate, current?: PossibleDate, options?: UnitFormatOptions, caller?: AnyCaller): string;
-/** Compact when a date happens, e.g. `10d` or `2h` or `-1w` */
+/**
+ * Format a compact best-fit description of how long until a date, e.g. `10d` or `2h` or `-1w`
+ * - See `getBestDurationUnit()` for details on how the best-fit unit is chosen.
+ *
+ * @param target Date to count up to.
+ * @param current Date to count from (defaults to now).
+ * @param options Formatting options for the chosen duration unit.
+ * @param caller Function to attribute a thrown error to (defaults to `formatUntil` itself).
+ * @returns Compact string like `10d` or `2h` (negative if `target` is in the past).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example formatUntil("2099-01-01") // "73y"
+ * @see https://dhoulb.github.io/shelving/util/duration/formatUntil
+ */
 export declare function formatUntil(target: PossibleDate, current?: PossibleDate, options?: UnitFormatOptions, caller?: AnyCaller): string;
-/** Compact when a date will happen, e.g. `10d` or `2h` or `-1w` */
+/**
+ * Format a compact best-fit description of how long since a date, e.g. `10d` or `2h` or `-1w`
+ * - See `getBestDurationUnit()` for details on how the best-fit unit is chosen.
+ *
+ * @param target Date to count back from.
+ * @param current Date to count to (defaults to now).
+ * @param options Formatting options for the chosen duration unit.
+ * @param caller Function to attribute a thrown error to (defaults to `formatAgo` itself).
+ * @returns Compact string like `10d` or `2h` (negative if `target` is in the future).
+ * @throws {RequiredError} If `target` or `current` cannot be converted to a valid date.
+ * @example formatAgo("2000-01-01") // "26y"
+ * @see https://dhoulb.github.io/shelving/util/duration/formatAgo
+ */
 export declare function formatAgo(target: PossibleDate, current?: PossibleDate, options?: UnitFormatOptions, caller?: AnyCaller): string;
+/** Options for formatting a `DurationData` object with `formatDuration()`. */
 interface DurationFormatOptions extends FormatOptions, Intl.DurationFormatOptions {
 }
-/** Format a duration as a string, e.g. `1 year, 2 months, 3 days` or `1y 2m 3d` */
+/**
+ * Format a duration as a string, e.g. `1 year, 2 months, 3 days` or `1y 2m 3d`
+ *
+ * @param duration `DurationData` object to format.
+ * @param options Formatting options passed through to `Intl.DurationFormat`.
+ * @returns Human-readable string describing the duration.
+ * @example formatDuration({ years: 1, months: 2, days: 3 }) // "1 yr, 2 mths, 3 days"
+ * @see https://dhoulb.github.io/shelving/util/duration/formatDuration
+ */
 export declare function formatDuration(duration: DurationData, options?: DurationFormatOptions): string;
 export {};