shelving 1.236.0 → 1.236.2

package/schema/DataSchema.js

@@ -6,28 +6,75 @@ import { validateData } from "../util/validate.js";
 import { NULLABLE } from "./NullableSchema.js";
 import { OPTIONAL } from "./OptionalSchema.js";
 import { Schema } from "./Schema.js";
-/** 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 class DataSchema extends Schema {
     props;
+    /**
+     * Create a new `DataSchema`.
+     *
+     * @param options Options for the schema, including the `props` schemas and an optional partial `value`.
+     */
     constructor({ one = "item", title = "Item", props, value: partialValue, ...options }) {
         // Build default value from props and partial value.
         const value = { ...mapProps(props, _getSchemaValue), ...partialValue };
         super({ one, title, value, ...options });
         this.props = props;
     }
+    /**
+     * 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 = this.value) {
         if (!isData(unsafeValue))
             throw "Must be object";
         return validateData(unsafeValue, this.props);
     }
-    /** 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(...keys) {
         return new DataSchema({ ...this, props: pickProps(this.props, ...keys) });
     }
-    /** 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(...keys) {
         return new DataSchema({ ...this, props: omitProps(this.props, ...keys) });
     }
+    /**
+     * 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) {
         return formatObject(value);
     }
@@ -35,10 +82,32 @@ export class DataSchema extends Schema {
 function _getSchemaValue([, { value }]) {
     return value;
 }
-/** Create a `DataSchema` for a set of properties. */
-export const DATA = (props) => new DataSchema({ props });
-/** Valid data object with specifed properties, or `null` */
-export const NULLABLE_DATA = (props) => NULLABLE(new DataSchema({ props }));
+/**
+ * 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 function DATA(props) {
+    return new DataSchema({ props });
+}
+/**
+ * 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 function NULLABLE_DATA(props) {
+    return NULLABLE(new DataSchema({ props }));
+}
 export function PARTIAL(source) {
     const props = source instanceof DataSchema ? source.props : source;
     return new DataSchema({
@@ -48,7 +117,17 @@ export function PARTIAL(source) {
 function _optionalProp([, v]) {
     return OPTIONAL(v);
 }
-/** 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 function ITEM(id, schemas) {
     const props = schemas instanceof DataSchema ? schemas.props : schemas;
     return new DataSchema({

package/schema/DateSchema.d.ts

@@ -2,9 +2,22 @@ import type { PossibleDate } from "../util/date.js";
 import type { Nullish } from "../util/null.js";
 import type { SchemaOptions } from "./Schema.js";
 import { Schema } from "./Schema.js";
-/** `type=""` prop for HTML `<input />` tags that are relevant for dates. */
+/**
+ * `type=""` prop for HTML `<input />` tags that are relevant for dates.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/DateSchema/DateInputType
+ */
 export type DateInputType = "time" | "date" | "datetime-local";
-/** Allowed options for `DateSchema` */
+/**
+ * Options for `DateSchema`.
+ *
+ * - `value` — default date used when the input is `undefined`.
+ * - `min`/`max` — earliest and latest allowed dates (`null` for no bound).
+ * - `input` — HTML `<input />` `type=""` hint for downstream UIs.
+ * - `step` — rounding step in milliseconds.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/DateSchema/DateSchemaOptions
+ */
 export interface DateSchemaOptions extends SchemaOptions {
     readonly value?: PossibleDate | undefined;
     readonly min?: Nullish<PossibleDate>;
@@ -17,18 +30,74 @@ export interface DateSchemaOptions extends SchemaOptions {
      */
     readonly step?: number | undefined;
 }
+/**
+ * Schema that defines a valid date stored as a `YYYY-MM-DD` string, e.g. `2005-09-12`.
+ *
+ * - Validates an abstract date without a timezone; use `DateTimeSchema` for UTC datetimes and `TimeSchema` for times.
+ * - The input is coerced to a `Date`, optionally rounded to `step`, range-checked against `min`/`max`, then stringified.
+ *
+ * @example
+ *  const schema = new DateSchema({ min: "2000-01-01" });
+ *  schema.validate("2005-09-12"); // "2005-09-12"
+ * @see https://dhoulb.github.io/shelving/schema/DateSchema/DateSchema
+ */
 export declare class DateSchema extends Schema<string> {
+    /** Default date used when `validate()` is called with an `undefined` value. */
     readonly value: PossibleDate | undefined;
+    /** Earliest allowed date, or `undefined` for no minimum. */
     readonly min: Date | undefined;
+    /** Latest allowed date, or `undefined` for no maximum. */
     readonly max: Date | undefined;
+    /** HTML `<input />` `type=""` hint for downstream UIs. */
     readonly input: DateInputType;
+    /** Rounding step in milliseconds, or `undefined` for no rounding. */
     readonly step: number | undefined;
+    /**
+     * Create a new `DateSchema`.
+     *
+     * @param options Options for the schema (`min`, `max`, `value`, `input`, `step`, plus base `SchemaOptions`).
+     */
     constructor({ one, min, max, value, input, step, ...options }: DateSchemaOptions);
+    /**
+     * Validate an unknown input value and return a valid date string.
+     *
+     * @param value The value to validate (defaults to this schema's `value`).
+     * @returns The validated date as a `YYYY-MM-DD` string.
+     * @throws `string` `"Required"` if the value is empty, `` `Invalid ${one} format` `` if it is not a date, or `` `Minimum…` `` / `` `Maximum…` `` if outside the allowed range.
+     * @example schema.validate("2005-09-12") // "2005-09-12"
+     * @see https://dhoulb.github.io/shelving/schema/DateSchema/DateSchema/validate
+     */
     validate(value?: unknown): string;
+    /**
+     * Convert a `Date` object to the string representation used by this schema.
+     *
+     * @param value The `Date` to convert.
+     * @returns The date as a `YYYY-MM-DD` string.
+     * @example schema.stringify(new Date("2005-09-12")) // "2005-09-12"
+     * @see https://dhoulb.github.io/shelving/schema/DateSchema/DateSchema/stringify
+     */
     stringify(value: Date): string;
+    /**
+     * Format a validated date string as a human-readable string for display.
+     *
+     * @param value The validated date string to format.
+     * @returns The date formatted for display.
+     * @example schema.format("2005-09-12") // "12 Sep 2005"
+     * @see https://dhoulb.github.io/shelving/schema/DateSchema/DateSchema/format
+     */
     format(value: string): string;
 }
-/** Valid date, e.g. `2005-09-12` (required because falsy values are invalid). */
+/**
+ * Valid date, e.g. `2005-09-12` (required because falsy values are invalid).
+ *
+ * @example DATE.validate("2005-09-12") // "2005-09-12"
+ * @see https://dhoulb.github.io/shelving/schema/DateSchema/DATE
+ */
 export declare const DATE: DateSchema;
-/** Valid date, e.g. `2005-09-12`, or `null` */
+/**
+ * Valid date, e.g. `2005-09-12`, or `null`.
+ *
+ * @example NULLABLE_DATE.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/DateSchema/NULLABLE_DATE
+ */
 export declare const NULLABLE_DATE: import("./NullableSchema.js").NullableSchema<string>;

package/schema/DateSchema.js

@@ -3,11 +3,31 @@ import { formatDate } from "../util/format.js";
 import { roundStep } from "../util/number.js";
 import { NULLABLE } from "./NullableSchema.js";
 import { Schema } from "./Schema.js";
+/**
+ * Schema that defines a valid date stored as a `YYYY-MM-DD` string, e.g. `2005-09-12`.
+ *
+ * - Validates an abstract date without a timezone; use `DateTimeSchema` for UTC datetimes and `TimeSchema` for times.
+ * - The input is coerced to a `Date`, optionally rounded to `step`, range-checked against `min`/`max`, then stringified.
+ *
+ * @example
+ *  const schema = new DateSchema({ min: "2000-01-01" });
+ *  schema.validate("2005-09-12"); // "2005-09-12"
+ * @see https://dhoulb.github.io/shelving/schema/DateSchema/DateSchema
+ */
 export class DateSchema extends Schema {
+    /** Earliest allowed date, or `undefined` for no minimum. */
     min;
+    /** Latest allowed date, or `undefined` for no maximum. */
     max;
+    /** HTML `<input />` `type=""` hint for downstream UIs. */
     input;
+    /** Rounding step in milliseconds, or `undefined` for no rounding. */
     step;
+    /**
+     * Create a new `DateSchema`.
+     *
+     * @param options Options for the schema (`min`, `max`, `value`, `input`, `step`, plus base `SchemaOptions`).
+     */
     constructor({ one = "date", min, max, value, input = "date", step, ...options }) {
         super({ one, title: "Date", value, ...options });
         this.min = getDate(min);
@@ -15,6 +35,15 @@ export class DateSchema extends Schema {
         this.input = input;
         this.step = step;
     }
+    /**
+     * Validate an unknown input value and return a valid date string.
+     *
+     * @param value The value to validate (defaults to this schema's `value`).
+     * @returns The validated date as a `YYYY-MM-DD` string.
+     * @throws `string` `"Required"` if the value is empty, `` `Invalid ${one} format` `` if it is not a date, or `` `Minimum…` `` / `` `Maximum…` `` if outside the allowed range.
+     * @example schema.validate("2005-09-12") // "2005-09-12"
+     * @see https://dhoulb.github.io/shelving/schema/DateSchema/DateSchema/validate
+     */
     validate(value = this.value) {
         const date = getDate(value);
         if (!date)
@@ -26,14 +55,40 @@ export class DateSchema extends Schema {
             throw `Maximum ${this.format(this.stringify(this.max))}`;
         return this.stringify(stepped);
     }
+    /**
+     * Convert a `Date` object to the string representation used by this schema.
+     *
+     * @param value The `Date` to convert.
+     * @returns The date as a `YYYY-MM-DD` string.
+     * @example schema.stringify(new Date("2005-09-12")) // "2005-09-12"
+     * @see https://dhoulb.github.io/shelving/schema/DateSchema/DateSchema/stringify
+     */
     stringify(value) {
         return requireDateString(value);
     }
+    /**
+     * Format a validated date string as a human-readable string for display.
+     *
+     * @param value The validated date string to format.
+     * @returns The date formatted for display.
+     * @example schema.format("2005-09-12") // "12 Sep 2005"
+     * @see https://dhoulb.github.io/shelving/schema/DateSchema/DateSchema/format
+     */
     format(value) {
         return formatDate(value, undefined, this.format);
     }
 }
-/** Valid date, e.g. `2005-09-12` (required because falsy values are invalid). */
+/**
+ * Valid date, e.g. `2005-09-12` (required because falsy values are invalid).
+ *
+ * @example DATE.validate("2005-09-12") // "2005-09-12"
+ * @see https://dhoulb.github.io/shelving/schema/DateSchema/DATE
+ */
 export const DATE = new DateSchema({});
-/** Valid date, e.g. `2005-09-12`, or `null` */
+/**
+ * Valid date, e.g. `2005-09-12`, or `null`.
+ *
+ * @example NULLABLE_DATE.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/DateSchema/NULLABLE_DATE
+ */
 export const NULLABLE_DATE = NULLABLE(DATE);

package/schema/DateTimeSchema.d.ts

@@ -1,16 +1,53 @@
 import { DateSchema, type DateSchemaOptions } from "./DateSchema.js";
 /**
- * Define a valid UTC date in ISO 8601 format, e.g. `2005-09-12T18:15:00.000Z`
+ * Schema that defines a valid UTC datetime in ISO 8601 format, e.g. `2005-09-12T18:15:00.000Z`.
+ *
  * - The date includes the `Z` suffix to indicate UTC time, this ensures consistent transfer of the date between client and server.
  * - If you wish to define an _abstract_ date without a timezone, e.g. a birthday or anniversary, use `DateSchema` instead.
  * - If you wish to define an _abstract_ time without a timezone, e.g. a daily alarm, use `TimeSchema` instead.
+ *
+ * @example
+ *  const schema = new DateTimeSchema({});
+ *  schema.validate("2005-09-12T18:15:00Z"); // "2005-09-12T18:15:00.000Z"
+ * @see https://dhoulb.github.io/shelving/schema/DateTimeSchema/DateTimeSchema
  */
 export declare class DateTimeSchema extends DateSchema {
+    /**
+     * Create a new `DateTimeSchema`.
+     *
+     * @param options Options for the schema (same as `DateSchemaOptions`).
+     */
     constructor({ one, title, input, ...options }: DateSchemaOptions);
+    /**
+     * Convert a `Date` object to an ISO 8601 UTC string.
+     *
+     * @param value The `Date` to convert.
+     * @returns The datetime as an ISO 8601 string with `Z` suffix.
+     * @example schema.stringify(new Date("2005-09-12T18:15:00Z")) // "2005-09-12T18:15:00.000Z"
+     * @see https://dhoulb.github.io/shelving/schema/DateTimeSchema/DateTimeSchema/stringify
+     */
     stringify(value: Date): string;
+    /**
+     * Format a validated datetime string as a human-readable string for display.
+     *
+     * @param value The validated datetime string to format.
+     * @returns The datetime formatted for display.
+     * @example schema.format("2005-09-12T18:15:00Z") // "12 Sep 2005, 18:15"
+     * @see https://dhoulb.github.io/shelving/schema/DateTimeSchema/DateTimeSchema/format
+     */
     format(value: string): string;
 }
-/** Valid datetime, e.g. `2005-09-12T08:00:00Z` (required because falsy values are invalid). */
+/**
+ * Valid datetime, e.g. `2005-09-12T08:00:00Z` (required because falsy values are invalid).
+ *
+ * @example DATETIME.validate("2005-09-12T08:00:00Z") // "2005-09-12T08:00:00.000Z"
+ * @see https://dhoulb.github.io/shelving/schema/DateTimeSchema/DATETIME
+ */
 export declare const DATETIME: DateTimeSchema;
-/** Valid datetime, e.g. `2005-09-12T21:30:00Z`, or `null` */
+/**
+ * Valid datetime, e.g. `2005-09-12T21:30:00Z`, or `null`.
+ *
+ * @example NULLABLE_DATETIME.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/DateTimeSchema/NULLABLE_DATETIME
+ */
 export declare const NULLABLE_DATETIME: import("./NullableSchema.js").NullableSchema<string>;

package/schema/DateTimeSchema.js

@@ -2,23 +2,60 @@ import { formatDateTime } from "../util/format.js";
 import { DateSchema } from "./DateSchema.js";
 import { NULLABLE } from "./NullableSchema.js";
 /**
- * Define a valid UTC date in ISO 8601 format, e.g. `2005-09-12T18:15:00.000Z`
+ * Schema that defines a valid UTC datetime in ISO 8601 format, e.g. `2005-09-12T18:15:00.000Z`.
+ *
  * - The date includes the `Z` suffix to indicate UTC time, this ensures consistent transfer of the date between client and server.
  * - If you wish to define an _abstract_ date without a timezone, e.g. a birthday or anniversary, use `DateSchema` instead.
  * - If you wish to define an _abstract_ time without a timezone, e.g. a daily alarm, use `TimeSchema` instead.
+ *
+ * @example
+ *  const schema = new DateTimeSchema({});
+ *  schema.validate("2005-09-12T18:15:00Z"); // "2005-09-12T18:15:00.000Z"
+ * @see https://dhoulb.github.io/shelving/schema/DateTimeSchema/DateTimeSchema
  */
 export class DateTimeSchema extends DateSchema {
+    /**
+     * Create a new `DateTimeSchema`.
+     *
+     * @param options Options for the schema (same as `DateSchemaOptions`).
+     */
     constructor({ one = "time", title = "Time", input = "datetime-local", ...options }) {
         super({ one, title, input, ...options });
     }
+    /**
+     * Convert a `Date` object to an ISO 8601 UTC string.
+     *
+     * @param value The `Date` to convert.
+     * @returns The datetime as an ISO 8601 string with `Z` suffix.
+     * @example schema.stringify(new Date("2005-09-12T18:15:00Z")) // "2005-09-12T18:15:00.000Z"
+     * @see https://dhoulb.github.io/shelving/schema/DateTimeSchema/DateTimeSchema/stringify
+     */
     stringify(value) {
         return value.toISOString();
     }
+    /**
+     * Format a validated datetime string as a human-readable string for display.
+     *
+     * @param value The validated datetime string to format.
+     * @returns The datetime formatted for display.
+     * @example schema.format("2005-09-12T18:15:00Z") // "12 Sep 2005, 18:15"
+     * @see https://dhoulb.github.io/shelving/schema/DateTimeSchema/DateTimeSchema/format
+     */
     format(value) {
         return formatDateTime(value, undefined, this.format);
     }
 }
-/** Valid datetime, e.g. `2005-09-12T08:00:00Z` (required because falsy values are invalid). */
+/**
+ * Valid datetime, e.g. `2005-09-12T08:00:00Z` (required because falsy values are invalid).
+ *
+ * @example DATETIME.validate("2005-09-12T08:00:00Z") // "2005-09-12T08:00:00.000Z"
+ * @see https://dhoulb.github.io/shelving/schema/DateTimeSchema/DATETIME
+ */
 export const DATETIME = new DateTimeSchema({});
-/** Valid datetime, e.g. `2005-09-12T21:30:00Z`, or `null` */
+/**
+ * Valid datetime, e.g. `2005-09-12T21:30:00Z`, or `null`.
+ *
+ * @example NULLABLE_DATETIME.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/DateTimeSchema/NULLABLE_DATETIME
+ */
 export const NULLABLE_DATETIME = NULLABLE(DATETIME);

package/schema/DictionarySchema.d.ts

@@ -1,22 +1,72 @@
 import type { ImmutableDictionary } from "../util/dictionary.js";
 import type { SchemaOptions } from "./Schema.js";
 import { Schema } from "./Schema.js";
-/** Allowed options for `DictionarySchema` */
+/**
+ * Options for `DictionarySchema`.
+ *
+ * - `items` — schema every entry value in the dictionary must conform to.
+ * - `value` — default dictionary used when the input is `undefined`.
+ * - `min`/`max` — minimum and maximum number of entries.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/DictionarySchema/DictionarySchemaOptions
+ */
 export interface DictionarySchemaOptions<T> extends SchemaOptions {
     readonly items: Schema<T>;
     readonly value?: ImmutableDictionary | undefined;
     readonly min?: number | undefined;
     readonly max?: number | undefined;
 }
-/** Validate a dictionary object (whose props are all the same with string keys). */
+/**
+ * Schema that validates a dictionary object whose entries all share the same value schema and have string keys.
+ *
+ * - Every entry value is validated by the `items` schema.
+ * - Entry count is checked against `min` and `max`.
+ *
+ * @example
+ *  const schema = new DictionarySchema({ items: NUMBER });
+ *  schema.validate({ a: 1, b: 2 }); // { a: 1, b: 2 }
+ *
+ * @see https://dhoulb.github.io/shelving/schema/DictionarySchema/DictionarySchema
+ */
 export declare class DictionarySchema<T> extends Schema<ImmutableDictionary<T>> {
     readonly value: ImmutableDictionary<T>;
     readonly items: Schema<T>;
     readonly min: number;
     readonly max: number;
+    /**
+     * Create a new `DictionarySchema`.
+     *
+     * @param options Options for the schema, including the `items` schema and `min`/`max` entry counts.
+     */
     constructor({ items, one, many, placeholder, min, max, title, value, ...options }: DictionarySchemaOptions<T>);
+    /**
+     * Validate an unknown value as a dictionary whose entries all match the `items` schema.
+     *
+     * @param unsafeValue The unknown input value to validate (defaults to this schema's `value`).
+     * @returns The valid dictionary with each entry value validated by the `items` schema.
+     * @throws `string` `"Must be object"` if not a dictionary, `"Required"` or `` `Minimum ${min} ${many}` `` if too few entries, or `` `Maximum ${max} ${many}` `` if too many.
+     * @example schema.validate({ a: 1, b: 2 }) // { a: 1, b: 2 }
+     * @see https://dhoulb.github.io/shelving/schema/DictionarySchema/DictionarySchema/validate
+     */
     validate(unsafeValue?: unknown): ImmutableDictionary<T>;
+    /**
+     * Format a validated dictionary as a string for display.
+     *
+     * @param dict The valid dictionary to format.
+     * @returns The dictionary's values formatted as a human-readable string.
+     * @example schema.format({ a: 1, b: 2 }) // "1, 2"
+     * @see https://dhoulb.github.io/shelving/schema/DictionarySchema/DictionarySchema/format
+     */
     format(dict: ImmutableDictionary<T>): string;
 }
-/** Valid dictionary object with specifed items. */
-export declare const DICTIONARY: <T>(items: Schema<T>) => DictionarySchema<T>;
+/**
+ * Create a schema for a valid dictionary object with specified entry values.
+ *
+ * *Factory for `DictionarySchema`.*
+ *
+ * @param items Schema every entry value in the dictionary must conform to.
+ * @returns A `DictionarySchema` validating dictionaries of the given item type.
+ * @example DICTIONARY(NUMBER) // DictionarySchema<number>
+ * @see https://dhoulb.github.io/shelving/schema/DictionarySchema/DICTIONARY
+ */
+export declare function DICTIONARY<T>(items: Schema<T>): DictionarySchema<T>;

package/schema/DictionarySchema.js

@@ -2,17 +2,42 @@ import { isDictionary } from "../util/dictionary.js";
 import { formatArray } from "../util/format.js";
 import { validateDictionary } from "../util/validate.js";
 import { Schema } from "./Schema.js";
-/** Validate a dictionary object (whose props are all the same with string keys). */
+/**
+ * Schema that validates a dictionary object whose entries all share the same value schema and have string keys.
+ *
+ * - Every entry value is validated by the `items` schema.
+ * - Entry count is checked against `min` and `max`.
+ *
+ * @example
+ *  const schema = new DictionarySchema({ items: NUMBER });
+ *  schema.validate({ a: 1, b: 2 }); // { a: 1, b: 2 }
+ *
+ * @see https://dhoulb.github.io/shelving/schema/DictionarySchema/DictionarySchema
+ */
 export class DictionarySchema extends Schema {
     items;
     min;
     max;
+    /**
+     * Create a new `DictionarySchema`.
+     *
+     * @param options Options for the schema, including the `items` schema and `min`/`max` entry counts.
+     */
     constructor({ items, one = items.one, many = items.many, placeholder = `No ${many}`, min = 0, max = Number.POSITIVE_INFINITY, title = "Items", value = {}, ...options }) {
         super({ one, many, title, placeholder, value, ...options });
         this.items = items;
         this.min = min;
         this.max = max;
     }
+    /**
+     * Validate an unknown value as a dictionary whose entries all match the `items` schema.
+     *
+     * @param unsafeValue The unknown input value to validate (defaults to this schema's `value`).
+     * @returns The valid dictionary with each entry value validated by the `items` schema.
+     * @throws `string` `"Must be object"` if not a dictionary, `"Required"` or `` `Minimum ${min} ${many}` `` if too few entries, or `` `Maximum ${max} ${many}` `` if too many.
+     * @example schema.validate({ a: 1, b: 2 }) // { a: 1, b: 2 }
+     * @see https://dhoulb.github.io/shelving/schema/DictionarySchema/DictionarySchema/validate
+     */
     validate(unsafeValue = this.value) {
         if (!isDictionary(unsafeValue))
             throw "Must be object";
@@ -24,9 +49,28 @@ export class DictionarySchema extends Schema {
             throw `Maximum ${this.max} ${this.many}`;
         return validDictionary;
     }
+    /**
+     * Format a validated dictionary as a string for display.
+     *
+     * @param dict The valid dictionary to format.
+     * @returns The dictionary's values formatted as a human-readable string.
+     * @example schema.format({ a: 1, b: 2 }) // "1, 2"
+     * @see https://dhoulb.github.io/shelving/schema/DictionarySchema/DictionarySchema/format
+     */
     format(dict) {
         return formatArray(Object.values(dict).map(v => this.items.format(v)), undefined, this.format);
     }
 }
-/** Valid dictionary object with specifed items. */
-export const DICTIONARY = (items) => new DictionarySchema({ items });
+/**
+ * Create a schema for a valid dictionary object with specified entry values.
+ *
+ * *Factory for `DictionarySchema`.*
+ *
+ * @param items Schema every entry value in the dictionary must conform to.
+ * @returns A `DictionarySchema` validating dictionaries of the given item type.
+ * @example DICTIONARY(NUMBER) // DictionarySchema<number>
+ * @see https://dhoulb.github.io/shelving/schema/DictionarySchema/DICTIONARY
+ */
+export function DICTIONARY(items) {
+    return new DictionarySchema({ items });
+}

package/schema/EmailSchema.d.ts

@@ -1,7 +1,7 @@
 import type { StringSchemaOptions } from "./StringSchema.js";
 import { StringSchema } from "./StringSchema.js";
 /**
- * Define a valid email address.
+ * Schema that defines a valid email address.
  *
  * - Falsy values are converted to `""` empty string.
  * - Total length must be 254 characters or fewer (in SMTP email is encoded with `<` and `>` to make 256 characters).
@@ -16,12 +16,43 @@ import { StringSchema } from "./StringSchema.js";
  *     - Limited to `[a-z0-9]` with mid-word hyphens only.
  *     - Up to 10 segments of up to 63 characters each, separated by `.`
  *     - TLD is a segment of 2-63 characters, possibly in `xn--` international format.
+ *
+ * @example EMAIL.validate("Test@Test.com"); // Returns "test@test.com"
+ * @see https://dhoulb.github.io/shelving/schema/EmailSchema/EmailSchema
  */
 export declare class EmailSchema extends StringSchema {
+    /**
+     * Create a new `EmailSchema`.
+     *
+     * @param options Options for the schema (inherits `StringSchema` options except `type`, `min`, `max`, `match`, and `rows`, which are fixed for emails).
+     * @param options.one Singular noun describing one value, used in error messages (defaults to `"email address"`).
+     * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Email"`).
+     */
     constructor({ one, title, ...options }: Omit<StringSchemaOptions, "type" | "min" | "max" | "match" | "rows">);
+    /**
+     * Sanitize the string into a valid email address.
+     *
+     * - Strips all whitespace (email addresses never contain whitespace).
+     * - Lowercases the result (RFC says addresses should be case-insensitive).
+     *
+     * @param str String to sanitize.
+     * @returns The sanitized, lowercased email address.
+     * @example EMAIL.sanitize(" Test@Test.com "); // Returns "test@test.com"
+     * @see https://dhoulb.github.io/shelving/schema/EmailSchema/EmailSchema/sanitize
+     */
     sanitize(str: string): string;
 }
-/** Valid email, e.g. `test@test.com` */
+/**
+ * Valid email, e.g. `test@test.com`
+ *
+ * @example EMAIL.validate("test@test.com"); // Returns "test@test.com"
+ * @see https://dhoulb.github.io/shelving/schema/EmailSchema/EMAIL
+ */
 export declare const EMAIL: EmailSchema;
-/** Valid optional email, e.g. `test@test.com`, or `null` */
+/**
+ * Valid optional email, e.g. `test@test.com`, or `null`
+ *
+ * @example NULLABLE_EMAIL.validate(null); // Returns null
+ * @see https://dhoulb.github.io/shelving/schema/EmailSchema/NULLABLE_EMAIL
+ */
 export declare const NULLABLE_EMAIL: import("./NullableSchema.js").NullableSchema<string>;