shelving 1.236.0 → 1.236.2

package/markup/util/regexp.d.ts

@@ -1,21 +1,98 @@
 import type { NamedRegExp, NamedRegExpData, PossibleRegExp } from "../../util/regexp.js";
+/**
+ * Regular expression source matching block content — the shortest run of any character.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/BLOCK_CONTENT_REGEXP
+ */
 export declare const BLOCK_CONTENT_REGEXP = "[\\s\\S]*?";
+/**
+ * Regular expression source matching block whitespace — any single whitespace character.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/BLOCK_SPACE_REGEXP
+ */
 export declare const BLOCK_SPACE_REGEXP = "\\s";
+/**
+ * Regular expression source matching the start of a block — the start of the string, or one linebreak.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/BLOCK_START_REGEXP
+ */
 export declare const BLOCK_START_REGEXP = "(?:\\s*\\n|^)";
+/**
+ * Regular expression source matching the end of a block — the end of the string, or two linebreaks, with trailing whitespace trimmed.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/BLOCK_END_REGEXP
+ */
 export declare const BLOCK_END_REGEXP = "\\s*(?:$|\\n\\s*\\n)";
+/**
+ * Regular expression source matching line content — the shortest run of any character except newline.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/LINE_CONTENT_REGEXP
+ */
 export declare const LINE_CONTENT_REGEXP = "[^\\n]*?";
+/**
+ * Regular expression source matching line whitespace — any single whitespace character except newline.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/LINE_SPACE_REGEXP
+ */
 export declare const LINE_SPACE_REGEXP = "[^\\n\\S]";
+/**
+ * Regular expression source matching the start of a line — the start of the string, or one linebreak.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/LINE_START_REGEXP
+ */
 export declare const LINE_START_REGEXP = "(?:\\s*\\n|^)";
+/**
+ * Regular expression source matching the end of a line — the end of the string, or one linebreak, with trailing whitespace trimmed.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/LINE_END_REGEXP
+ */
 export declare const LINE_END_REGEXP = "[^\\n\\S]*(?:\\s*\\n|$)";
+/**
+ * Regular expression source matching word content — at least one letter or number character.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/WORD_CONTENT_REGEXP
+ */
 export declare const WORD_CONTENT_REGEXP = "[\\p{L}\\p{N}]+";
+/**
+ * Regular expression source matching the start of a word — a zero-width assertion that the previous character is not a letter or number.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/WORD_START_REGEXP
+ */
 export declare const WORD_START_REGEXP = "(?<![\\p{L}\\p{N}])";
+/**
+ * Regular expression source matching the end of a word — a zero-width assertion that the next character is not a letter or number.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/WORD_END_REGEXP
+ */
 export declare const WORD_END_REGEXP = "(?![\\p{L}\\p{N}])";
-/** Create regular expression that matches a block of content. */
+/**
+ * Create a `RegExp` that matches a block of content, wrapped between block-start and block-end boundaries.
+ *
+ * *Factory for `RegExp`.*
+ *
+ * @param pattern The content pattern to match between the boundaries (a `NamedRegExp` to type the captured data).
+ * @param start The leading boundary pattern (defaults to `BLOCK_START_REGEXP`).
+ * @param end The trailing boundary pattern (defaults to `BLOCK_END_REGEXP`).
+ * @returns A `RegExp` (a `NamedRegExp<T>` when the content pattern names its capture groups).
+ * @example createBlockRegExp("(?<quote>>[\\s\\S]*?)")
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/createBlockRegExp
+ */
 export declare function createBlockRegExp<T extends NamedRegExpData>(pattern: NamedRegExp<T>, start?: PossibleRegExp, end?: PossibleRegExp): NamedRegExp<T>;
 export declare function createBlockRegExp<T extends NamedRegExpData | undefined = undefined>(pattern: PossibleRegExp, start?: PossibleRegExp, end?: PossibleRegExp): T extends NamedRegExpData ? NamedRegExp<T> : RegExp;
-/** Create regular expression that matches a line of content. */
+/**
+ * Create a `RegExp` that matches a single line of content, wrapped between line-start and line-end boundaries.
+ *
+ * *Factory for `RegExp`.*
+ *
+ * @param pattern The content pattern to match between the boundaries (a `NamedRegExp` to type the captured data).
+ * @param start The leading boundary pattern (defaults to `LINE_START_REGEXP`).
+ * @param end The trailing boundary pattern (defaults to `LINE_END_REGEXP`).
+ * @returns A `RegExp` (a `NamedRegExp<T>` when the content pattern names its capture groups).
+ * @example createLineRegExp("(?<prefix>#{1,6})")
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/createLineRegExp
+ */
 export declare function createLineRegExp<T extends NamedRegExpData>(pattern: NamedRegExp<T>, start?: PossibleRegExp, end?: PossibleRegExp): T extends NamedRegExpData ? NamedRegExp<T> : RegExp;
 export declare function createLineRegExp<T extends NamedRegExpData | undefined = undefined>(pattern: PossibleRegExp, start?: PossibleRegExp, end?: PossibleRegExp): T extends NamedRegExpData ? NamedRegExp<T> : RegExp;
-/** Create regular expression that matches a word of content. */
+/**
+ * Create a `RegExp` that matches a word of content, wrapped between word-start and word-end boundaries.
+ *
+ * *Factory for `RegExp`.*
+ *
+ * @param pattern The content pattern to match between the boundaries (a `NamedRegExp` to type the captured data).
+ * @param start The leading boundary pattern (defaults to `WORD_START_REGEXP`).
+ * @param end The trailing boundary pattern (defaults to `WORD_END_REGEXP`).
+ * @returns A `RegExp` (a `NamedRegExp<T>` when the content pattern names its capture groups).
+ * @example createWordRegExp("(?<char>[*_])+")
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/createWordRegExp
+ */
 export declare function createWordRegExp<T extends NamedRegExpData>(pattern: NamedRegExp<T>, start?: PossibleRegExp, end?: PossibleRegExp): T extends NamedRegExpData ? NamedRegExp<T> : RegExp;
 export declare function createWordRegExp<T extends NamedRegExpData | undefined = undefined>(pattern: PossibleRegExp, start?: PossibleRegExp, end?: PossibleRegExp): T extends NamedRegExpData ? NamedRegExp<T> : RegExp;

package/markup/util/regexp.js

@@ -1,14 +1,58 @@
 import { getRegExpSource } from "../../util/regexp.js";
+/**
+ * Regular expression source matching block content — the shortest run of any character.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/BLOCK_CONTENT_REGEXP
+ */
 export const BLOCK_CONTENT_REGEXP = "[\\s\\S]*?"; // Block content (shortest run of any character).
+/**
+ * Regular expression source matching block whitespace — any single whitespace character.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/BLOCK_SPACE_REGEXP
+ */
 export const BLOCK_SPACE_REGEXP = "\\s"; // Block whitespace (run of any whitespace character).
+/**
+ * Regular expression source matching the start of a block — the start of the string, or one linebreak.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/BLOCK_START_REGEXP
+ */
 export const BLOCK_START_REGEXP = "(?:\\s*\\n|^)"; // Start of block (start of string, or one linebreak).
+/**
+ * Regular expression source matching the end of a block — the end of the string, or two linebreaks, with trailing whitespace trimmed.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/BLOCK_END_REGEXP
+ */
 export const BLOCK_END_REGEXP = "\\s*(?:$|\\n\\s*\\n)"; // End of block (end of string, or two linebreaks, trimmed whitespace).
+/**
+ * Regular expression source matching line content — the shortest run of any character except newline.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/LINE_CONTENT_REGEXP
+ */
 export const LINE_CONTENT_REGEXP = "[^\\n]*?"; // Line content (shortest run of any character except newline).
+/**
+ * Regular expression source matching line whitespace — any single whitespace character except newline.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/LINE_SPACE_REGEXP
+ */
 export const LINE_SPACE_REGEXP = "[^\\n\\S]"; // Line whitespace (run of any whitespace character except newline).
+/**
+ * Regular expression source matching the start of a line — the start of the string, or one linebreak.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/LINE_START_REGEXP
+ */
 export const LINE_START_REGEXP = BLOCK_START_REGEXP; // Start of line (start of string, or one linebreak).
+/**
+ * Regular expression source matching the end of a line — the end of the string, or one linebreak, with trailing whitespace trimmed.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/LINE_END_REGEXP
+ */
 export const LINE_END_REGEXP = `${LINE_SPACE_REGEXP}*(?:\\s*\\n|$)`; // End of line (end of string, or one linebreak, trimmed whitespace).
+/**
+ * Regular expression source matching word content — at least one letter or number character.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/WORD_CONTENT_REGEXP
+ */
 export const WORD_CONTENT_REGEXP = "[\\p{L}\\p{N}]+"; // Word content (at least one character that is a letter or number).
+/**
+ * Regular expression source matching the start of a word — a zero-width assertion that the previous character is not a letter or number.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/WORD_START_REGEXP
+ */
 export const WORD_START_REGEXP = "(?<![\\p{L}\\p{N}])"; // Start of word (previous character is not a letter or number).
+/**
+ * Regular expression source matching the end of a word — a zero-width assertion that the next character is not a letter or number.
+ * @see https://dhoulb.github.io/shelving/markup/util/regexp/WORD_END_REGEXP
+ */
 export const WORD_END_REGEXP = "(?![\\p{L}\\p{N}])"; // End of word (next character is not a letter or number).
 export function createBlockRegExp(content, start = BLOCK_START_REGEXP, end = BLOCK_END_REGEXP) {
     return new RegExp(`${start}${getRegExpSource(content)}${end}`, "u");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.236.0",
+	"version": "1.236.2",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/react/createAPIContext.d.ts

@@ -3,6 +3,11 @@ import type { Endpoint } from "../api/endpoint/Endpoint.js";
 import type { APIProvider } from "../api/provider/APIProvider.js";
 import type { EndpointStore } from "../api/store/EndpointStore.js";
 import type { Nullish } from "../util/null.js";
+/**
+ * Bundle of hooks and a provider component returned by `createAPIContext()`.
+ *
+ * @see https://dhoulb.github.io/shelving/react/createAPIContext/APIContext
+ */
 export interface APIContext<P, R> {
     /** Get an `EndpointStore` for the specified endpoint/payload in the current `APIProvider` context. */
     useAPI<PP extends P, RR extends R>(this: void, endpoint: Endpoint<PP, RR>, payload: PP): EndpointStore<PP, RR>;
@@ -17,6 +22,16 @@ export interface APIContext<P, R> {
  * - Allows React elements to call `useAPI()` to access endpoint stores in an API provider.
  * - Each mounted `APIContext` gets its own in-memory store cache.
  *
+ * @param provider `APIProvider` the created context resolves endpoint stores against.
+ * @returns `APIContext` bundle containing the `useAPI()` hook and the `<APIContext>` wrapper component.
+ *
  * @todo Use and integreate our `EndpointCache` functionality and use it in this.
+ *
+ * @example
+ * ```tsx
+ * const { useAPI, APIContext } = createAPIContext(provider);
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/react/createAPIContext
  */
 export declare function createAPIContext<P, R>(provider: APIProvider<P, R>): APIContext<P, R>;

package/react/createAPIContext.js

@@ -9,7 +9,17 @@ import { useStore } from "./useStore.js";
  * - Allows React elements to call `useAPI()` to access endpoint stores in an API provider.
  * - Each mounted `APIContext` gets its own in-memory store cache.
  *
+ * @param provider `APIProvider` the created context resolves endpoint stores against.
+ * @returns `APIContext` bundle containing the `useAPI()` hook and the `<APIContext>` wrapper component.
+ *
  * @todo Use and integreate our `EndpointCache` functionality and use it in this.
+ *
+ * @example
+ * ```tsx
+ * const { useAPI, APIContext } = createAPIContext(provider);
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/react/createAPIContext
  */
 export function createAPIContext(provider) {
     const CacheContext = createContext(undefined);

package/react/createDBContext.d.ts

@@ -7,6 +7,11 @@ import type { Data } from "../util/data.js";
 import type { Identifier, Item } from "../util/item.js";
 import type { Nullish } from "../util/null.js";
 import type { Query } from "../util/query.js";
+/**
+ * Bundle of hooks and a provider component returned by `createDBContext()`.
+ *
+ * @see https://dhoulb.github.io/shelving/react/createDBContext/DBContext
+ */
 export interface DBContext<I extends Identifier, T extends Data> {
     /** Get an `ItemStore` for the specified collection item in the current `DataProvider` context and subscribe to any changes in it. */
     useItem<II extends I, TT extends T>(collection: Nullish<Collection<string, II, TT>>, //
@@ -27,5 +32,15 @@ export interface DBContext<I extends Identifier, T extends Data> {
  * Create a data context
  * - Allows React elements to call `useItem()` and `useQuery()` to access items/queries in a database provider.
  * - If the database has a `CacheDBProvider` in its chain then in-memory data will be used in the returned stores.
+ *
+ * @param provider `DBProvider` the created context resolves item and query stores against.
+ * @returns `DBContext` bundle containing the `useItem()` and `useQuery()` hooks and the `<DBContext>` wrapper component.
+ *
+ * @example
+ * ```tsx
+ * const { useItem, useQuery, DBContext } = createDBContext(provider);
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/react/createDBContext
  */
 export declare function createDBContext<I extends Identifier, T extends Data>(provider: DBProvider<I, T>): DBContext<I, T>;

package/react/createDBContext.js

@@ -8,6 +8,16 @@ import { useStore } from "./useStore.js";
  * Create a data context
  * - Allows React elements to call `useItem()` and `useQuery()` to access items/queries in a database provider.
  * - If the database has a `CacheDBProvider` in its chain then in-memory data will be used in the returned stores.
+ *
+ * @param provider `DBProvider` the created context resolves item and query stores against.
+ * @returns `DBContext` bundle containing the `useItem()` and `useQuery()` hooks and the `<DBContext>` wrapper component.
+ *
+ * @example
+ * ```tsx
+ * const { useItem, useQuery, DBContext } = createDBContext(provider);
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/react/createDBContext
  */
 export function createDBContext(provider) {
     const CacheContext = createContext(undefined);

package/react/useInstance.d.ts

@@ -3,5 +3,16 @@ import type { Arguments } from "../util/function.js";
  * Use a memoised class instance.
  * - Creates a new instance of `Constructor` using `args`
  * - Returns same instance for as long as `args` is equal to previous `args`.
+ *
+ * @param Constructor Class to instantiate with `args`.
+ * @param args Constructor arguments — a change in `args` constructs a fresh instance.
+ * @returns The memoised instance, reconstructed only when `args` changes.
+ *
+ * @example
+ * ```tsx
+ * const cache = useInstance(DBCache, provider);
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/react/useInstance
  */
 export declare function useInstance<T, A extends Arguments = []>(Constructor: new (...a: A) => T, ...args: A): T;

package/react/useInstance.js

@@ -4,6 +4,17 @@ import { isArrayEqual } from "../util/equal.js";
  * Use a memoised class instance.
  * - Creates a new instance of `Constructor` using `args`
  * - Returns same instance for as long as `args` is equal to previous `args`.
+ *
+ * @param Constructor Class to instantiate with `args`.
+ * @param args Constructor arguments — a change in `args` constructs a fresh instance.
+ * @returns The memoised instance, reconstructed only when `args` changes.
+ *
+ * @example
+ * ```tsx
+ * const cache = useInstance(DBCache, provider);
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/react/useInstance
  */
 export function useInstance(Constructor, ...args) {
     const _internals = (useRef(undefined).current ??= {

package/react/useLazy.d.ts

@@ -4,6 +4,17 @@ import { type Lazy } from "../util/lazy.js";
  * Use a memoised value with lazy initialisation.
  * - Returns `value` (if not a function) or the result of calling `value(...args)` (if a function).
  * - Returns same `value` for as long as `args` is equal to previous `args`.
+ *
+ * @param value Value to return, or a function called with `args` to lazily produce it.
+ * @param args Arguments passed to `value()` when it is a function — a change in `args` recomputes the value.
+ * @returns The memoised value, recomputed only when `args` changes.
+ *
+ * @example
+ * ```tsx
+ * const config = useLazy(() => expensiveConfig(id), id);
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/react/useLazy
  */
 export declare function useLazy<T, A extends Arguments = []>(value: (...args: A) => T, ...args: A): T;
 export declare function useLazy<T>(value: T, ...args: Arguments): T;

package/react/useMap.d.ts

@@ -1,2 +1,15 @@
-/** Create a mutable Map that persists for the lifetime of the component. */
+/**
+ * Create a mutable Map that persists for the lifetime of the component.
+ * - The same `Map` instance is returned on every render; mutations are not reactive (won't trigger a re-render).
+ *
+ * @returns Stable `Map` instance that lives for the lifetime of the component.
+ *
+ * @example
+ * ```tsx
+ * const cache = useMap<string, number>();
+ * cache.set("a", 1);
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/react/useMap
+ */
 export declare function useMap<K, V>(): Map<K, V>;

package/react/useMap.js

@@ -1,5 +1,18 @@
 import { useRef } from "react";
-/** Create a mutable Map that persists for the lifetime of the component. */
+/**
+ * Create a mutable Map that persists for the lifetime of the component.
+ * - The same `Map` instance is returned on every render; mutations are not reactive (won't trigger a re-render).
+ *
+ * @returns Stable `Map` instance that lives for the lifetime of the component.
+ *
+ * @example
+ * ```tsx
+ * const cache = useMap<string, number>();
+ * cache.set("a", 1);
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/react/useMap
+ */
 export function useMap() {
     return (useRef(undefined).current ??= new Map());
 }

package/react/useReduce.d.ts

@@ -5,6 +5,18 @@ import type { Arguments } from "../util/function.js";
  * - First argument `previous` is either `undefined` (on first render) or the value returned by `reduce()` on the previous render (on subsequent renders).
  * - `reduce()` can implement custom logic to decide whether to return the previous value or a new one.
  * - Returns whatever `reduce()` returns on this render.
+ *
+ * @param reduce Reducer called on every render with the previous result and `args`; returns this render's value.
+ * @param args Additional arguments forwarded to `reduce()` after `previous`.
+ * @returns Whatever `reduce()` returned on this render.
+ *
+ * @example
+ * ```tsx
+ * // Keep the highest count ever seen.
+ * const max = useReduce((previous = 0, next: number) => Math.max(previous, next), count);
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/react/useReduce
  */
 export declare function useReduce<T, A extends Arguments = []>(reduce: (previous: T | undefined, ...a: A) => T, ...args: A): T;
 export declare function useReduce<T, A extends Arguments = []>(reduce: (previous: T | undefined, ...a: A) => T | undefined, ...args: A): T | undefined;

package/react/useSequence.d.ts

@@ -1,8 +1,18 @@
 /**
  * Subscribe to an async iterable for the lifetime of the component.
+ * - Re-renders the component with each value yielded by the sequence.
  *
  * @param sequence An object implementing the `AsyncIterable` interface.
  * - Subscription is recreated every time this value changes.
  * - Memoise this value to persist the subscription for the lifetime of the component.
+ * @returns The most recent value yielded by `sequence`, or `undefined` before the first value arrives.
+ * @throws unknown Re-throws (during render) any error thrown by the sequence, for an error boundary to catch.
+ *
+ * @example
+ * ```tsx
+ * const value = useSequence(myAsyncIterable);
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/react/useSequence
  */
 export declare function useSequence<T>(sequence?: AsyncIterable<T>): T | undefined;

package/react/useSequence.js

@@ -2,10 +2,20 @@ import { useEffect, useState } from "react";
 import { runSequence } from "../util/sequence.js";
 /**
  * Subscribe to an async iterable for the lifetime of the component.
+ * - Re-renders the component with each value yielded by the sequence.
  *
  * @param sequence An object implementing the `AsyncIterable` interface.
  * - Subscription is recreated every time this value changes.
  * - Memoise this value to persist the subscription for the lifetime of the component.
+ * @returns The most recent value yielded by `sequence`, or `undefined` before the first value arrives.
+ * @throws unknown Re-throws (during render) any error thrown by the sequence, for an error boundary to catch.
+ *
+ * @example
+ * ```tsx
+ * const value = useSequence(myAsyncIterable);
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/react/useSequence
  */
 export function useSequence(sequence) {
     const [value, setValue] = useState(undefined);

package/react/useStore.d.ts

@@ -1,4 +1,19 @@
 import type { AnyStore } from "../store/Store.js";
-/** Subscribe to a Shelving `Store` instance to refresh this component when its value changes. */
+/**
+ * Subscribe to a Shelving `Store` instance to refresh this component when its value changes.
+ * - Re-renders the component whenever the store's value changes for as long as it is mounted.
+ * - Pass `undefined` to subscribe to nothing (e.g. for conditional subscriptions).
+ *
+ * @param store `Store` instance to subscribe to, or `undefined` to subscribe to nothing.
+ * @returns The same `store` that was passed in (or `undefined`).
+ *
+ * @example
+ * ```tsx
+ * const store = useStore(myStore);
+ * return <>{store.value}</>;
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/react/useStore
+ */
 export declare function useStore<T extends AnyStore>(store: T): T;
 export declare function useStore<T extends AnyStore>(store?: T | undefined): T | undefined;

package/schema/AddressSchema.d.ts

@@ -2,15 +2,52 @@ import { type AddressData, formatAddress } from "../util/geo.js";
 import { DataSchema, type DataSchemaOptions } from "./DataSchema.js";
 export type { AddressData };
 export { formatAddress };
-/** Allowed options for `AddressSchema` */
+/**
+ * Allowed options for `AddressSchema`.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/AddressSchema/AddressSchemaOptions
+ */
 export interface AddressSchemaOptions extends Omit<DataSchemaOptions<AddressData>, "props"> {
 }
-/** Schema that validates a postal address. */
+/**
+ * Schema that validates a postal address.
+ *
+ * - Validates the `address1`, `address2`, `city`, `state`, `postcode`, and `country` fields as a single `AddressData` object.
+ * - Formats validated values into a human-readable address string via `formatAddress()`.
+ *
+ * @example ADDRESS.validate({ address1: "1 High St", city: "London", postcode: "SW1A 1AA", country: "GB" });
+ * @see https://dhoulb.github.io/shelving/schema/AddressSchema/AddressSchema
+ */
 export declare class AddressSchema extends DataSchema<AddressData> {
+    /**
+     * Create a new `AddressSchema`.
+     *
+     * @param options Options for the schema (inherits `DataSchema` options except `props`, which is fixed to the postal-address fields).
+     * @param options.one Singular noun describing one value, used in error messages (defaults to `"address"`).
+     * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Address"`).
+     */
     constructor({ one, title, ...options }?: AddressSchemaOptions);
+    /**
+     * Format a validated address into a human-readable string.
+     *
+     * @param value The valid address data to format.
+     * @returns The address formatted as a single display string.
+     * @example ADDRESS.format({ address1: "1 High St", city: "London", postcode: "SW1A 1AA", country: "GB" });
+     * @see https://dhoulb.github.io/shelving/schema/AddressSchema/AddressSchema/format
+     */
     format(value: AddressData): string;
 }
-/** Valid postal address data. */
+/**
+ * Valid postal address data.
+ *
+ * @example ADDRESS.validate({ address1: "1 High St", city: "London", postcode: "SW1A 1AA", country: "GB" });
+ * @see https://dhoulb.github.io/shelving/schema/AddressSchema/ADDRESS
+ */
 export declare const ADDRESS: AddressSchema;
-/** Valid postal address data, or `null` */
+/**
+ * Valid postal address data, or `null`
+ *
+ * @example NULLABLE_ADDRESS.validate(null); // Returns null
+ * @see https://dhoulb.github.io/shelving/schema/AddressSchema/NULLABLE_ADDRESS
+ */
 export declare const NULLABLE_ADDRESS: import("./NullableSchema.js").NullableSchema<AddressData>;

package/schema/AddressSchema.js

@@ -12,16 +12,49 @@ const ADDRESS_PROPS = {
     postcode: new StringSchema({ title: "Postcode", min: 1, max: 12, case: "upper" }),
     country: COUNTRY,
 };
-/** Schema that validates a postal address. */
+/**
+ * Schema that validates a postal address.
+ *
+ * - Validates the `address1`, `address2`, `city`, `state`, `postcode`, and `country` fields as a single `AddressData` object.
+ * - Formats validated values into a human-readable address string via `formatAddress()`.
+ *
+ * @example ADDRESS.validate({ address1: "1 High St", city: "London", postcode: "SW1A 1AA", country: "GB" });
+ * @see https://dhoulb.github.io/shelving/schema/AddressSchema/AddressSchema
+ */
 export class AddressSchema extends DataSchema {
+    /**
+     * Create a new `AddressSchema`.
+     *
+     * @param options Options for the schema (inherits `DataSchema` options except `props`, which is fixed to the postal-address fields).
+     * @param options.one Singular noun describing one value, used in error messages (defaults to `"address"`).
+     * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Address"`).
+     */
     constructor({ one = "address", title = "Address", ...options } = {}) {
         super({ one, title, props: ADDRESS_PROPS, ...options });
     }
+    /**
+     * Format a validated address into a human-readable string.
+     *
+     * @param value The valid address data to format.
+     * @returns The address formatted as a single display string.
+     * @example ADDRESS.format({ address1: "1 High St", city: "London", postcode: "SW1A 1AA", country: "GB" });
+     * @see https://dhoulb.github.io/shelving/schema/AddressSchema/AddressSchema/format
+     */
     format(value) {
         return formatAddress(value);
     }
 }
-/** Valid postal address data. */
+/**
+ * Valid postal address data.
+ *
+ * @example ADDRESS.validate({ address1: "1 High St", city: "London", postcode: "SW1A 1AA", country: "GB" });
+ * @see https://dhoulb.github.io/shelving/schema/AddressSchema/ADDRESS
+ */
 export const ADDRESS = new AddressSchema({});
-/** Valid postal address data, or `null` */
+/**
+ * Valid postal address data, or `null`
+ *
+ * @example NULLABLE_ADDRESS.validate(null); // Returns null
+ * @see https://dhoulb.github.io/shelving/schema/AddressSchema/NULLABLE_ADDRESS
+ */
 export const NULLABLE_ADDRESS = NULLABLE(ADDRESS);

package/schema/ArraySchema.d.ts

@@ -1,7 +1,16 @@
 import type { ImmutableArray } from "../util/array.js";
 import type { SchemaOptions } from "./Schema.js";
 import { Schema } from "./Schema.js";
-/** Allowed options for `ArraySchema` */
+/**
+ * Options for `ArraySchema`.
+ *
+ * - `items` — schema every item in the array must conform to.
+ * - `min`/`max` — minimum and maximum number of items.
+ * - `unique` — deduplicate the items when set.
+ * - `separator` — string or `RegExp` used to split a string input into items.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/ArraySchema/ArraySchemaOptions
+ */
 export interface ArraySchemaOptions<T> extends SchemaOptions {
     /** The default value */
     readonly value?: ImmutableArray;
@@ -17,10 +26,10 @@ export interface ArraySchemaOptions<T> extends SchemaOptions {
     readonly separator?: string | RegExp;
 }
 /**
- * Define a valid array.
+ * Schema that validates an array and ensures every item matches a specified item schema.
  *
- * Validates arrays and ensures the array's items match a specified format.
- * Only returns a new instance of the object if it changes (for immutability).
+ * - A string input is split into items using `separator`.
+ * - Items are optionally deduplicated (`unique`), then the count is checked against `min` and `max`.
  *
  * @example
  *  const schema = new ArraySchema({ min: 1, max: 2, default: [10,11,12], required: true });
@@ -35,6 +44,8 @@ export interface ArraySchemaOptions<T> extends SchemaOptions {
  *  const schema = new ArraySchema({ schema: Array });
  *  schema.validate(["a", "a"], schema); // Returns ["a", "a"]
  *  schema.validate(["a", null], schema); // Throws Invalids({ "1": Invalid('Must be a string') });
+ *
+ * @see https://dhoulb.github.io/shelving/schema/ArraySchema/ArraySchema
  */
 export declare class ArraySchema<T> extends Schema<ImmutableArray<T>> {
     readonly value: ImmutableArray<T>;
@@ -43,9 +54,40 @@ export declare class ArraySchema<T> extends Schema<ImmutableArray<T>> {
     readonly min: number;
     readonly max: number;
     readonly separator: string | RegExp;
+    /**
+     * Create a new `ArraySchema`.
+     *
+     * @param options Options for the schema, including the `items` schema, `min`/`max` counts, `unique`, and `separator`.
+     */
     constructor({ items, one, many, title, placeholder, unique, min, max, separator, value, ...options }: ArraySchemaOptions<T>);
+    /**
+     * Validate an unknown value as an array whose items all match the `items` schema.
+     *
+     * @param unsafeValue The unknown input value to validate; a string is split using `separator` (defaults to this schema's `value`).
+     * @returns The valid array with each item validated by the `items` schema.
+     * @throws `string` `"Must be array"` if not an array, `"Required"` or `` `Minimum ${min} ${many}` `` if too few items, or `` `Maximum ${max} ${many}` `` if too many.
+     * @example schema.validate([1, 2, 3]) // [1, 2, 3]
+     * @see https://dhoulb.github.io/shelving/schema/ArraySchema/ArraySchema/validate
+     */
     validate(unsafeValue?: unknown): ImmutableArray<T>;
+    /**
+     * Format a validated array as a string for display.
+     *
+     * @param arr The valid array to format.
+     * @returns The array's items formatted as a human-readable string.
+     * @example schema.format([1, 2, 3]) // "1, 2, 3"
+     * @see https://dhoulb.github.io/shelving/schema/ArraySchema/ArraySchema/format
+     */
     format(arr: ImmutableArray<T>): string;
 }
-/** Valid array with specifed items. */
-export declare const ARRAY: <T>(items: Schema<T>) => ArraySchema<T>;
+/**
+ * Create a schema for a valid array with specified items.
+ *
+ * *Factory for `ArraySchema`.*
+ *
+ * @param items Schema every item in the array must conform to.
+ * @returns An `ArraySchema` validating arrays of the given item type.
+ * @example ARRAY(NUMBER) // ArraySchema<number>
+ * @see https://dhoulb.github.io/shelving/schema/ArraySchema/ARRAY
+ */
+export declare function ARRAY<T>(items: Schema<T>): ArraySchema<T>;