shelving 1.236.0 → 1.236.2

package/schema/CurrencyAmountSchema.d.ts

@@ -1,6 +1,14 @@
 import { type CurrencyCode } from "../util/currency.js";
+import type { NullableSchema } from "./NullableSchema.js";
 import { NumberSchema, type NumberSchemaOptions } from "./NumberSchema.js";
-/** Allowed options for `CurrencyAmountSchema`. */
+/**
+ * Options for `CurrencyAmountSchema`.
+ *
+ * - `currency` — ISO 4217 currency code that determines the step and symbol.
+ * - `symbol` — override the currency symbol used when formatting.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/CurrencyAmountSchemaOptions
+ */
 export interface CurrencyAmountSchemaOptions extends NumberSchemaOptions {
     readonly symbol?: string | undefined;
     readonly currency: CurrencyCode;
@@ -15,21 +23,109 @@ export interface CurrencyAmountSchemaOptions extends NumberSchemaOptions {
  * const PRICE = new CurrencyAmountSchema({ currency: "GBP", min: 0 });
  * PRICE.validate("12.345"); // 12.35
  * PRICE.format(12.3); // "£12.30"
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/CurrencyAmountSchema
  */
 export declare class CurrencyAmountSchema extends NumberSchema {
+    /**
+     * Rounding step, always defined and inferred from the currency's minor units.
+     *
+     * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/CurrencyAmountSchema/step
+     */
     readonly step: number;
+    /**
+     * ISO 4217 currency code this schema validates amounts for.
+     *
+     * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/CurrencyAmountSchema/currency
+     */
     readonly currency: CurrencyCode;
+    /**
+     * Currency symbol used when formatting amounts.
+     *
+     * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/CurrencyAmountSchema/symbol
+     */
     readonly symbol: string;
+    /**
+     * Create a new `CurrencyAmountSchema`.
+     *
+     * @param options Options for the schema (`currency` required, optional `symbol`, `step`, plus base `NumberSchemaOptions`).
+     * @throws `string` if `currency` is not a valid ISO 4217 currency code.
+     */
     constructor({ currency, one, title, symbol, step, ...options }: CurrencyAmountSchemaOptions);
+    /**
+     * Format a validated amount as a currency string for display.
+     *
+     * - Decimal places are omitted when `step` is `1` or more.
+     *
+     * @param value The validated amount to format.
+     * @returns The amount formatted using the schema's currency and symbol.
+     * @example schema.format(12.3) // "£12.30"
+     * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/CurrencyAmountSchema/format
+     */
     format(value: number): string;
 }
-/** Valid non-negative monetary amount in the a currency. */
-export declare const CURRENCY_AMOUNT: (currency: CurrencyCode) => CurrencyAmountSchema;
+/**
+ * Create a `CurrencyAmountSchema` for a non-negative monetary amount in a currency.
+ *
+ * *Factory for `CurrencyAmountSchema`.*
+ *
+ * @param currency ISO 4217 currency code that determines the step and symbol.
+ * @returns A `CurrencyAmountSchema` validating amounts in `currency`.
+ * @throws `string` if `currency` is not a valid ISO 4217 currency code.
+ * @example CURRENCY_AMOUNT("GBP").validate("12.345") // 12.35
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/CURRENCY_AMOUNT
+ */
+export declare function CURRENCY_AMOUNT(currency: CurrencyCode): CurrencyAmountSchema;
+/**
+ * Valid US dollar amount, e.g. `12.35`.
+ *
+ * @example USD_AMOUNT.validate("12.345") // 12.35
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/USD_AMOUNT
+ */
 export declare const USD_AMOUNT: CurrencyAmountSchema;
+/**
+ * Valid pound sterling amount, e.g. `12.35`.
+ *
+ * @example GBP_AMOUNT.validate("12.345") // 12.35
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/GBP_AMOUNT
+ */
 export declare const GBP_AMOUNT: CurrencyAmountSchema;
+/**
+ * Valid euro amount, e.g. `12.35`.
+ *
+ * @example EUR_AMOUNT.validate("12.345") // 12.35
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/EUR_AMOUNT
+ */
 export declare const EUR_AMOUNT: CurrencyAmountSchema;
-/** Valid optional monetary amount in the default currency, or `null`. */
-export declare const NULLABLE_CURRENCY_AMOUNT: (currency: CurrencyCode) => import("./NullableSchema.js").NullableSchema<number>;
-export declare const NULLABLE_USD_AMOUNT: import("./NullableSchema.js").NullableSchema<number>;
-export declare const NULLABLE_GBP_AMOUNT: import("./NullableSchema.js").NullableSchema<number>;
-export declare const NULLABLE_EUR_AMOUNT: import("./NullableSchema.js").NullableSchema<number>;
+/**
+ * Create a `NullableSchema` for an optional monetary amount in a currency, or `null`.
+ *
+ * *Factory for `NullableSchema`.*
+ *
+ * @param currency ISO 4217 currency code that determines the step and symbol.
+ * @returns A `NullableSchema` validating amounts in `currency`, or `null`.
+ * @throws `string` if `currency` is not a valid ISO 4217 currency code.
+ * @example NULLABLE_CURRENCY_AMOUNT("GBP").validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/NULLABLE_CURRENCY_AMOUNT
+ */
+export declare function NULLABLE_CURRENCY_AMOUNT(currency: CurrencyCode): NullableSchema<number>;
+/**
+ * Valid US dollar amount, e.g. `12.35`, or `null`.
+ *
+ * @example NULLABLE_USD_AMOUNT.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/NULLABLE_USD_AMOUNT
+ */
+export declare const NULLABLE_USD_AMOUNT: NullableSchema<number>;
+/**
+ * Valid pound sterling amount, e.g. `12.35`, or `null`.
+ *
+ * @example NULLABLE_GBP_AMOUNT.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/NULLABLE_GBP_AMOUNT
+ */
+export declare const NULLABLE_GBP_AMOUNT: NullableSchema<number>;
+/**
+ * Valid euro amount, e.g. `12.35`, or `null`.
+ *
+ * @example NULLABLE_EUR_AMOUNT.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/NULLABLE_EUR_AMOUNT
+ */
+export declare const NULLABLE_EUR_AMOUNT: NullableSchema<number>;

package/schema/CurrencyAmountSchema.js

@@ -12,10 +12,27 @@ import { NumberSchema } from "./NumberSchema.js";
  * const PRICE = new CurrencyAmountSchema({ currency: "GBP", min: 0 });
  * PRICE.validate("12.345"); // 12.35
  * PRICE.format(12.3); // "£12.30"
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/CurrencyAmountSchema
  */
 export class CurrencyAmountSchema extends NumberSchema {
+    /**
+     * ISO 4217 currency code this schema validates amounts for.
+     *
+     * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/CurrencyAmountSchema/currency
+     */
     currency;
+    /**
+     * Currency symbol used when formatting amounts.
+     *
+     * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/CurrencyAmountSchema/symbol
+     */
     symbol;
+    /**
+     * Create a new `CurrencyAmountSchema`.
+     *
+     * @param options Options for the schema (`currency` required, optional `symbol`, `step`, plus base `NumberSchemaOptions`).
+     * @throws `string` if `currency` is not a valid ISO 4217 currency code.
+     */
     constructor({ currency, one = "amount", title = "Amount", symbol, step, ...options }) {
         const validCurrency = requireCurrencyCode(currency, CurrencyAmountSchema);
         super({
@@ -27,18 +44,88 @@ export class CurrencyAmountSchema extends NumberSchema {
         this.currency = validCurrency;
         this.symbol = symbol ?? getCurrencySymbol(validCurrency, CurrencyAmountSchema);
     }
+    /**
+     * Format a validated amount as a currency string for display.
+     *
+     * - Decimal places are omitted when `step` is `1` or more.
+     *
+     * @param value The validated amount to format.
+     * @returns The amount formatted using the schema's currency and symbol.
+     * @example schema.format(12.3) // "£12.30"
+     * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/CurrencyAmountSchema/format
+     */
     format(value) {
         const options = this.step >= 1 ? { maximumFractionDigits: 0 } : {}; // Skip showing decimal places if step is 1 or more.
         return formatCurrency(value, this.currency, options, this.format);
     }
 }
-/** Valid non-negative monetary amount in the a currency. */
-export const CURRENCY_AMOUNT = (currency) => new CurrencyAmountSchema({ currency });
+/**
+ * Create a `CurrencyAmountSchema` for a non-negative monetary amount in a currency.
+ *
+ * *Factory for `CurrencyAmountSchema`.*
+ *
+ * @param currency ISO 4217 currency code that determines the step and symbol.
+ * @returns A `CurrencyAmountSchema` validating amounts in `currency`.
+ * @throws `string` if `currency` is not a valid ISO 4217 currency code.
+ * @example CURRENCY_AMOUNT("GBP").validate("12.345") // 12.35
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/CURRENCY_AMOUNT
+ */
+export function CURRENCY_AMOUNT(currency) {
+    return new CurrencyAmountSchema({ currency });
+}
+/**
+ * Valid US dollar amount, e.g. `12.35`.
+ *
+ * @example USD_AMOUNT.validate("12.345") // 12.35
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/USD_AMOUNT
+ */
 export const USD_AMOUNT = new CurrencyAmountSchema({ currency: "USD" });
+/**
+ * Valid pound sterling amount, e.g. `12.35`.
+ *
+ * @example GBP_AMOUNT.validate("12.345") // 12.35
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/GBP_AMOUNT
+ */
 export const GBP_AMOUNT = new CurrencyAmountSchema({ currency: "GBP" });
+/**
+ * Valid euro amount, e.g. `12.35`.
+ *
+ * @example EUR_AMOUNT.validate("12.345") // 12.35
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/EUR_AMOUNT
+ */
 export const EUR_AMOUNT = new CurrencyAmountSchema({ currency: "EUR" });
-/** Valid optional monetary amount in the default currency, or `null`. */
-export const NULLABLE_CURRENCY_AMOUNT = (currency) => NULLABLE(CURRENCY_AMOUNT(currency));
+/**
+ * Create a `NullableSchema` for an optional monetary amount in a currency, or `null`.
+ *
+ * *Factory for `NullableSchema`.*
+ *
+ * @param currency ISO 4217 currency code that determines the step and symbol.
+ * @returns A `NullableSchema` validating amounts in `currency`, or `null`.
+ * @throws `string` if `currency` is not a valid ISO 4217 currency code.
+ * @example NULLABLE_CURRENCY_AMOUNT("GBP").validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/NULLABLE_CURRENCY_AMOUNT
+ */
+export function NULLABLE_CURRENCY_AMOUNT(currency) {
+    return NULLABLE(CURRENCY_AMOUNT(currency));
+}
+/**
+ * Valid US dollar amount, e.g. `12.35`, or `null`.
+ *
+ * @example NULLABLE_USD_AMOUNT.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/NULLABLE_USD_AMOUNT
+ */
 export const NULLABLE_USD_AMOUNT = NULLABLE(USD_AMOUNT);
+/**
+ * Valid pound sterling amount, e.g. `12.35`, or `null`.
+ *
+ * @example NULLABLE_GBP_AMOUNT.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/NULLABLE_GBP_AMOUNT
+ */
 export const NULLABLE_GBP_AMOUNT = NULLABLE(GBP_AMOUNT);
+/**
+ * Valid euro amount, e.g. `12.35`, or `null`.
+ *
+ * @example NULLABLE_EUR_AMOUNT.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyAmountSchema/NULLABLE_EUR_AMOUNT
+ */
 export const NULLABLE_EUR_AMOUNT = NULLABLE(EUR_AMOUNT);

package/schema/CurrencyCodeSchema.d.ts

@@ -2,20 +2,72 @@ import type { ImmutableArray } from "../util/array.js";
 import { type CurrencyCode } from "../util/currency.js";
 import type { StringSchemaOptions } from "./StringSchema.js";
 import { StringSchema } from "./StringSchema.js";
-/** Options for a `CurrencyCodeSchema` */
+/**
+ * Options for `CurrencyCodeSchema`.
+ *
+ * - `currencies` — set of allowed ISO 4217 currency codes (defaults to all known codes).
+ *
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/CurrencyCodeSchemaOptions
+ */
 export interface CurrencyCodeSchemaOptions extends Omit<StringSchemaOptions, "input" | "min" | "max" | "match" | "rows"> {
     currencies?: ImmutableArray<CurrencyCode>;
 }
 /**
- * Type of `StringSchema` that defines a valid currency code.
+ * Schema that defines a valid ISO 4217 currency code, e.g. `GBP`.
+ *
+ * - The input is sanitized to three uppercase letters, then checked against the allowed `currencies`.
+ *
+ * @example
+ *  const schema = new CurrencyCodeSchema({});
+ *  schema.validate("gbp"); // "GBP"
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/CurrencyCodeSchema
  */
 export declare class CurrencyCodeSchema extends StringSchema {
+    /**
+     * Set of allowed ISO 4217 currency codes.
+     *
+     * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/CurrencyCodeSchema/currencies
+     */
     readonly currencies: ImmutableArray<CurrencyCode>;
+    /**
+     * Create a new `CurrencyCodeSchema`.
+     *
+     * @param options Options for the schema (`currencies`, plus base `StringSchemaOptions` except `input`/`min`/`max`/`match`/`rows`).
+     * @example new CurrencyCodeSchema({ currencies: ["GBP", "USD"] })
+     * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/CurrencyCodeSchema
+     */
     constructor({ one, title, currencies, ...options }: CurrencyCodeSchemaOptions);
+    /**
+     * Sanitize an input string down to uppercase `A-Z` letters.
+     *
+     * @param insaneString The raw input string to sanitize.
+     * @returns The sanitized string with all non-`A-Z` characters stripped.
+     * @example schema.sanitize(" gb p ") // "GBP"
+     * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/CurrencyCodeSchema/sanitize
+     */
     sanitize(insaneString: string): string;
+    /**
+     * Validate an unknown input value and return a valid currency code.
+     *
+     * @param value The value to validate (defaults to this schema's `value`).
+     * @returns The validated three-letter uppercase currency code.
+     * @throws `string` if the value is not a valid string, or `"Unknown currency code"` if it is not in `currencies`.
+     * @example schema.validate("gbp") // "GBP"
+     * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/CurrencyCodeSchema/validate
+     */
     validate(value?: unknown): string;
 }
-/** Valid currency code, e.g. `GBP` */
+/**
+ * Valid currency code, e.g. `GBP` (required because falsy values are invalid).
+ *
+ * @example CURRENCY_CODE.validate("gbp") // "GBP"
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/CURRENCY_CODE
+ */
 export declare const CURRENCY_CODE: CurrencyCodeSchema;
-/** Valid currency code, e.g. `GBP`, or `null` */
+/**
+ * Valid currency code, e.g. `GBP`, or `null`.
+ *
+ * @example NULLABLE_CURRENCY_CODE.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/NULLABLE_CURRENCY_CODE
+ */
 export declare const NULLABLE_CURRENCY_CODE: import("./NullableSchema.js").NullableSchema<string>;

package/schema/CurrencyCodeSchema.js

@@ -2,10 +2,29 @@ import { CURRENCY_CODES } from "../util/currency.js";
 import { NULLABLE } from "./NullableSchema.js";
 import { StringSchema } from "./StringSchema.js";
 /**
- * Type of `StringSchema` that defines a valid currency code.
+ * Schema that defines a valid ISO 4217 currency code, e.g. `GBP`.
+ *
+ * - The input is sanitized to three uppercase letters, then checked against the allowed `currencies`.
+ *
+ * @example
+ *  const schema = new CurrencyCodeSchema({});
+ *  schema.validate("gbp"); // "GBP"
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/CurrencyCodeSchema
  */
 export class CurrencyCodeSchema extends StringSchema {
+    /**
+     * Set of allowed ISO 4217 currency codes.
+     *
+     * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/CurrencyCodeSchema/currencies
+     */
     currencies;
+    /**
+     * Create a new `CurrencyCodeSchema`.
+     *
+     * @param options Options for the schema (`currencies`, plus base `StringSchemaOptions` except `input`/`min`/`max`/`match`/`rows`).
+     * @example new CurrencyCodeSchema({ currencies: ["GBP", "USD"] })
+     * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/CurrencyCodeSchema
+     */
     constructor({ one = "currency", title = "Currency", currencies = CURRENCY_CODES, ...options }) {
         super({
             one,
@@ -19,10 +38,27 @@ export class CurrencyCodeSchema extends StringSchema {
         });
         this.currencies = currencies;
     }
+    /**
+     * Sanitize an input string down to uppercase `A-Z` letters.
+     *
+     * @param insaneString The raw input string to sanitize.
+     * @returns The sanitized string with all non-`A-Z` characters stripped.
+     * @example schema.sanitize(" gb p ") // "GBP"
+     * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/CurrencyCodeSchema/sanitize
+     */
     sanitize(insaneString) {
         // Strip characters that aren't A-Z (including whitespace).
         return super.sanitize(insaneString).replace(/[^A-Z+]/g, "");
     }
+    /**
+     * Validate an unknown input value and return a valid currency code.
+     *
+     * @param value The value to validate (defaults to this schema's `value`).
+     * @returns The validated three-letter uppercase currency code.
+     * @throws `string` if the value is not a valid string, or `"Unknown currency code"` if it is not in `currencies`.
+     * @example schema.validate("gbp") // "GBP"
+     * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/CurrencyCodeSchema/validate
+     */
     validate(value) {
         const currency = super.validate(value);
         if (!this.currencies.includes(currency))
@@ -30,7 +66,17 @@ export class CurrencyCodeSchema extends StringSchema {
         return currency;
     }
 }
-/** Valid currency code, e.g. `GBP` */
+/**
+ * Valid currency code, e.g. `GBP` (required because falsy values are invalid).
+ *
+ * @example CURRENCY_CODE.validate("gbp") // "GBP"
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/CURRENCY_CODE
+ */
 export const CURRENCY_CODE = new CurrencyCodeSchema({});
-/** Valid currency code, e.g. `GBP`, or `null` */
+/**
+ * Valid currency code, e.g. `GBP`, or `null`.
+ *
+ * @example NULLABLE_CURRENCY_CODE.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/CurrencyCodeSchema/NULLABLE_CURRENCY_CODE
+ */
 export const NULLABLE_CURRENCY_CODE = NULLABLE(CURRENCY_CODE);

package/schema/DataSchema.d.ts

@@ -4,28 +4,119 @@ import { type Key } from "../util/object.js";
 import type { NullableSchema } from "./NullableSchema.js";
 import type { SchemaOptions, Schemas } from "./Schema.js";
 import { Schema } from "./Schema.js";
-/** Allowed options for `PropsSchema` (a schema that has props). */
+/**
+ * Options for `DataSchema`.
+ *
+ * - `props` — a named schema for each property the data object must have.
+ * - `value` — partial default value merged over the per-prop defaults.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/DataSchema/DataSchemaOptions
+ */
 export interface DataSchemaOptions<T extends Data> extends SchemaOptions {
     readonly props: Schemas<T>;
     readonly value?: Partial<T> | undefined;
 }
-/** Validate a data object. */
+/**
+ * Schema that validates a data object against a fixed set of named property schemas.
+ *
+ * - Each property is validated by its own schema in `props`.
+ * - Excess keys are stripped and `undefined` outputs removed (via `validateData()`).
+ *
+ * @example
+ *  const schema = new DataSchema({ props: { name: STRING, age: NUMBER } });
+ *  schema.validate({ name: "Dave", age: 40 }); // { name: "Dave", age: 40 }
+ *
+ * @see https://dhoulb.github.io/shelving/schema/DataSchema/DataSchema
+ */
 export declare class DataSchema<T extends Data> extends Schema<unknown> {
     readonly value: T;
     readonly props: Schemas<T>;
+    /**
+     * Create a new `DataSchema`.
+     *
+     * @param options Options for the schema, including the `props` schemas and an optional partial `value`.
+     */
     constructor({ one, title, props, value: partialValue, ...options }: DataSchemaOptions<T>);
+    /**
+     * Validate an unknown value as a data object matching this schema's props.
+     *
+     * @param unsafeValue The unknown input value to validate (defaults to this schema's `value`).
+     * @returns The valid data object with each property validated by its schema.
+     * @throws `string` `"Must be object"` if the value is not a data object, or a `"key: message"` line per invalid property.
+     * @example schema.validate({ name: "Dave" }) // { name: "Dave" }
+     * @see https://dhoulb.github.io/shelving/schema/DataSchema/DataSchema/validate
+     */
     validate(unsafeValue?: unknown): T;
-    /** Make a new `DataSchema` that only uses a defined subset of the current props. */
+    /**
+     * Make a new `DataSchema` that only uses a defined subset of the current props.
+     *
+     * @param keys The property keys to keep.
+     * @returns A new `DataSchema` containing only the picked props.
+     * @example schema.pick("name", "age") // DataSchema<Pick<T, "name" | "age">>
+     * @see https://dhoulb.github.io/shelving/schema/DataSchema/DataSchema/pick
+     */
     pick<K extends Key<T>>(...keys: K[]): DataSchema<Pick<T, K>>;
-    /** Make a new `DataSchema` that omits one or more of the current props. */
+    /**
+     * Make a new `DataSchema` that omits one or more of the current props.
+     *
+     * @param keys The property keys to remove.
+     * @returns A new `DataSchema` without the omitted props.
+     * @example schema.omit("age") // DataSchema<Omit<T, "age">>
+     * @see https://dhoulb.github.io/shelving/schema/DataSchema/DataSchema/omit
+     */
     omit<K extends Key<T>>(...keys: K[]): DataSchema<Omit<T, K>>;
+    /**
+     * Format a validated data object as a string for display.
+     *
+     * @param value The valid data object to format.
+     * @returns The data object formatted as a human-readable string.
+     * @example schema.format({ name: "Dave" }) // "name: Dave"
+     * @see https://dhoulb.github.io/shelving/schema/DataSchema/DataSchema/format
+     */
     format(value: T): string;
 }
-/** Create a `DataSchema` for a set of properties. */
-export declare const DATA: <T extends Data>(props: Schemas<T>) => DataSchema<T>;
-/** Valid data object with specifed properties, or `null` */
-export declare const NULLABLE_DATA: <T extends Data>(props: Schemas<T>) => NullableSchema<T>;
-/** Create a `DataSchema` that validates partially, i.e. properties can be their value, or `undefined` */
+/**
+ * Create a `DataSchema` for a set of properties.
+ *
+ * *Factory for `DataSchema`.*
+ *
+ * @param props A named schema for each property of the data object.
+ * @returns A `DataSchema` validating data with the given props.
+ * @example DATA({ name: STRING, age: NUMBER }) // DataSchema<{ name: string; age: number }>
+ * @see https://dhoulb.github.io/shelving/schema/DataSchema/DATA
+ */
+export declare function DATA<T extends Data>(props: Schemas<T>): DataSchema<T>;
+/**
+ * Create a schema for a valid data object with specified properties, or `null`.
+ *
+ * *Factory for `NullableSchema`.*
+ *
+ * @param props A named schema for each property of the data object.
+ * @returns A `NullableSchema` wrapping a `DataSchema` with the given props.
+ * @example NULLABLE_DATA({ name: STRING }) // NullableSchema<{ name: string }>
+ * @see https://dhoulb.github.io/shelving/schema/DataSchema/NULLABLE_DATA
+ */
+export declare function NULLABLE_DATA<T extends Data>(props: Schemas<T>): NullableSchema<T>;
+/**
+ * Create a `DataSchema` that validates partially, i.e. every property can be its value or `undefined`.
+ *
+ * *Factory for `DataSchema`.*
+ *
+ * @param source The props schemas or an existing `DataSchema` to make partial.
+ * @returns A `DataSchema` whose every property is optional.
+ * @example PARTIAL({ name: STRING, age: NUMBER }) // DataSchema<{ name?: string; age?: number }>
+ * @see https://dhoulb.github.io/shelving/schema/DataSchema/PARTIAL
+ */
 export declare function PARTIAL<T extends Data>(source: Schemas<T> | DataSchema<T>): DataSchema<PartialData<T>>;
-/** Create a `DataSchema` that validates a data item, i.e. it has a string or number `.id` identifier property. */
+/**
+ * Create a `DataSchema` that validates a data item, i.e. it has a string or number `.id` identifier property.
+ *
+ * *Factory for `DataSchema`.*
+ *
+ * @param id Schema for the item's `id` identifier property.
+ * @param schemas The props schemas or an existing `DataSchema` for the rest of the item.
+ * @returns A `DataSchema` validating an item with an `id` property plus the given props.
+ * @example ITEM(NUMBER, { name: STRING }) // DataSchema<{ id: number; name: string }>
+ * @see https://dhoulb.github.io/shelving/schema/DataSchema/ITEM
+ */
 export declare function ITEM<I extends Identifier, T extends Data>(id: Schema<I>, schemas: Schemas<T> | DataSchema<T>): DataSchema<Item<I, T>>;