shelving 1.236.0 → 1.236.2

package/schema/ArraySchema.js

@@ -3,10 +3,10 @@ import { formatArray } from "../util/format.js";
 import { validateArray } from "../util/validate.js";
 import { Schema } from "./Schema.js";
 /**
- * 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 });
@@ -21,6 +21,8 @@ import { Schema } from "./Schema.js";
  *  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 class ArraySchema extends Schema {
     items;
@@ -28,6 +30,11 @@ export class ArraySchema extends Schema {
     min;
     max;
     separator;
+    /**
+     * Create a new `ArraySchema`.
+     *
+     * @param options Options for the schema, including the `items` schema, `min`/`max` counts, `unique`, and `separator`.
+     */
     constructor({ items, one = items.one, many = items.many, title = "Items", placeholder = `No ${many}`, unique = false, min = 0, max = Number.POSITIVE_INFINITY, separator = ",", value = [], ...options }) {
         super({ one, many, title, placeholder, value, ...options });
         this.items = items;
@@ -36,6 +43,15 @@ export class ArraySchema extends Schema {
         this.max = max;
         this.separator = separator;
     }
+    /**
+     * 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 = this.value) {
         const unsafeArray = typeof unsafeValue === "string" ? unsafeValue.split(this.separator).filter(Boolean) : unsafeValue;
         if (!isArray(unsafeArray))
@@ -48,9 +64,28 @@ export class ArraySchema extends Schema {
             throw `Maximum ${this.max} ${this.many}`;
         return uniqueArray;
     }
+    /**
+     * 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) {
         return formatArray(arr.map(v => this.items.format(v)), undefined, this.format);
     }
 }
-/** Valid array with specifed items. */
-export const ARRAY = (items) => new ArraySchema({ items });
+/**
+ * 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 function ARRAY(items) {
+    return new ArraySchema({ items });
+}

package/schema/BooleanSchema.d.ts

@@ -1,17 +1,73 @@
 import type { SchemaOptions } from "./Schema.js";
 import { Schema } from "./Schema.js";
-/** Allowed options for `BooleanSchema` */
+/**
+ * Allowed options for `BooleanSchema`.
+ *
+ * - `value` — default boolean value used when the input is `undefined`.
+ * - `required` — when `true`, a falsy result is rejected as invalid.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/BooleanSchema/BooleanSchemaOptions
+ */
 export interface BooleanSchemaOptions extends SchemaOptions {
     readonly value?: boolean | undefined;
     readonly required?: boolean | undefined;
 }
-/** Define a valid boolean. */
+/**
+ * Schema that defines a valid boolean.
+ *
+ * - Strings are coerced: known negative strings (`""`, `"false"`, `"0"`, `"no"`, `"n"`, `"off"`) become `false`, everything else becomes `true`.
+ * - All other values are coerced with standard truthiness.
+ *
+ * @example
+ *  const schema = new BooleanSchema({ required: true });
+ *  schema.validate("yes"); // Returns true
+ *  schema.validate(""); // Throws "Required"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/BooleanSchema/BooleanSchema
+ */
 export declare class BooleanSchema extends Schema<boolean> {
     readonly value: boolean;
     readonly required: boolean;
+    /**
+     * Create a new `BooleanSchema`.
+     *
+     * @param options Options for the schema.
+     * @param options.value Default boolean value used when the input is `undefined` (defaults to `false`).
+     * @param options.required When `true`, a falsy result is rejected as invalid (defaults to `false`).
+     */
     constructor({ value, required, ...options }: BooleanSchemaOptions);
+    /**
+     * Validate an unknown value and coerce it to a boolean.
+     *
+     * @param unsafeValue Value to validate (defaults to this schema's `value`).
+     * @returns The coerced boolean value.
+     * @throws `string` `"Required"` if `required` is `true` and the coerced value is `false`.
+     *
+     * @example
+     *  BOOLEAN.validate("yes"); // Returns true
+     *
+     * @see https://dhoulb.github.io/shelving/schema/BooleanSchema/BooleanSchema/validate
+     */
     validate(unsafeValue?: unknown): boolean;
+    /**
+     * Format a boolean value as a human-readable string for display.
+     *
+     * @param value Boolean value to format.
+     * @returns The formatted string, e.g. `"Yes"` or `"No"`.
+     *
+     * @example
+     *  BOOLEAN.format(true); // Returns "Yes"
+     *
+     * @see https://dhoulb.github.io/shelving/schema/BooleanSchema/BooleanSchema/format
+     */
     format(value: boolean): string;
 }
-/** Valid boolean. */
+/**
+ * Valid boolean.
+ *
+ * @example
+ *  BOOLEAN.validate("yes"); // Returns true
+ *
+ * @see https://dhoulb.github.io/shelving/schema/BooleanSchema/BOOLEAN
+ */
 export declare const BOOLEAN: BooleanSchema;

package/schema/BooleanSchema.js

@@ -1,21 +1,70 @@
 import { formatBoolean } from "../util/format.js";
 import { Schema } from "./Schema.js";
 const NEGATIVE = ["", "false", "0", "no", "n", "off"];
-/** Define a valid boolean. */
+/**
+ * Schema that defines a valid boolean.
+ *
+ * - Strings are coerced: known negative strings (`""`, `"false"`, `"0"`, `"no"`, `"n"`, `"off"`) become `false`, everything else becomes `true`.
+ * - All other values are coerced with standard truthiness.
+ *
+ * @example
+ *  const schema = new BooleanSchema({ required: true });
+ *  schema.validate("yes"); // Returns true
+ *  schema.validate(""); // Throws "Required"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/BooleanSchema/BooleanSchema
+ */
 export class BooleanSchema extends Schema {
+    /**
+     * Create a new `BooleanSchema`.
+     *
+     * @param options Options for the schema.
+     * @param options.value Default boolean value used when the input is `undefined` (defaults to `false`).
+     * @param options.required When `true`, a falsy result is rejected as invalid (defaults to `false`).
+     */
     constructor({ value = false, required = false, ...options }) {
         super({ value, ...options });
         this.required = required;
     }
+    /**
+     * Validate an unknown value and coerce it to a boolean.
+     *
+     * @param unsafeValue Value to validate (defaults to this schema's `value`).
+     * @returns The coerced boolean value.
+     * @throws `string` `"Required"` if `required` is `true` and the coerced value is `false`.
+     *
+     * @example
+     *  BOOLEAN.validate("yes"); // Returns true
+     *
+     * @see https://dhoulb.github.io/shelving/schema/BooleanSchema/BooleanSchema/validate
+     */
     validate(unsafeValue = this.value) {
         const value = typeof unsafeValue === "string" ? !NEGATIVE.includes(unsafeValue.toLowerCase().trim()) : !!unsafeValue;
         if (this.required && !value)
             throw "Required";
         return value;
     }
+    /**
+     * Format a boolean value as a human-readable string for display.
+     *
+     * @param value Boolean value to format.
+     * @returns The formatted string, e.g. `"Yes"` or `"No"`.
+     *
+     * @example
+     *  BOOLEAN.format(true); // Returns "Yes"
+     *
+     * @see https://dhoulb.github.io/shelving/schema/BooleanSchema/BooleanSchema/format
+     */
     format(value) {
         return formatBoolean(value);
     }
 }
-/** Valid boolean. */
+/**
+ * Valid boolean.
+ *
+ * @example
+ *  BOOLEAN.validate("yes"); // Returns true
+ *
+ * @see https://dhoulb.github.io/shelving/schema/BooleanSchema/BOOLEAN
+ */
 export const BOOLEAN = new BooleanSchema({});

package/schema/ChoiceSchema.d.ts

@@ -2,31 +2,85 @@ import { type ImmutableArray } from "../util/array.js";
 import type { SchemaOptions } from "./Schema.js";
 import { Schema } from "./Schema.js";
 /**
- * Set of options for a `ChoiceSchema` can be either:
- * - Dictionary of string options in `{ key: title }` format.
+ * Dictionary of allowed options for a `ChoiceSchema` in `{ key: title }` format.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/ChoiceSchema/ChoiceOptions
  */
 export type ChoiceOptions<K extends string> = {
     readonly [KK in K]: string;
 };
 /**
- * Things that can be converted to a choice options dictionary.
- * - Array of string options in `[key]` format (`key` will be used as the `title` too).
+ * Things that can be converted to a `ChoiceOptions` dictionary.
+ *
+ * - Dictionary of string options in `{ key: title }` format.
+ * - Array of string options in `[key]` format (`key` is used as the `title` too).
+ *
+ * @see https://dhoulb.github.io/shelving/schema/ChoiceSchema/PossibleChoiceOptions
  */
 export type PossibleChoiceOptions<K extends string> = ImmutableArray<K> | ChoiceOptions<K>;
-/** Allowed options for `ChoiceSchema` */
+/**
+ * Options for `ChoiceSchema`.
+ *
+ * - `options` — the allowed choices, as a `{ key: title }` dictionary or an array of keys.
+ * - `value` — default option used when the input is `undefined`.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/ChoiceSchema/ChoiceSchemaOptions
+ */
 export interface ChoiceSchemaOptions<O extends string, I = never> extends Omit<SchemaOptions, "value"> {
     /** Specify correct options using a dictionary of entries. */
     readonly options: PossibleChoiceOptions<O>;
     /** Default option for the value. */
     readonly value?: O | I;
 }
-/** Choose from an allowed set of values. */
+/**
+ * Schema that validates a value against a fixed set of allowed string choices.
+ *
+ * - The input must be one of the keys in `options`, otherwise it is rejected.
+ * - Each choice has a human-readable title used by `format()`.
+ *
+ * @example
+ *  const schema = new ChoiceSchema({ options: { yes: "Yes", no: "No" } });
+ *  schema.validate("yes"); // "yes"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/ChoiceSchema/ChoiceSchema
+ */
 export declare class ChoiceSchema<O extends string, I = never> extends Schema<O> {
     readonly value: O | I | undefined;
     readonly options: ChoiceOptions<O>;
+    /**
+     * Create a new `ChoiceSchema`.
+     *
+     * @param options Options for the schema, including the allowed `options` and an optional default `value`.
+     */
     constructor({ one, title, placeholder, options, value, ...rest }: ChoiceSchemaOptions<O, I>);
+    /**
+     * Validate an unknown value as one of the allowed choices.
+     *
+     * @param unsafeValue The unknown input value to validate (defaults to this schema's `value`).
+     * @returns The valid choice key.
+     * @throws `string` `"Required"` if the value is empty or missing, or `` `Unknown ${one}` `` if it is not one of the allowed choices.
+     * @example schema.validate("yes") // "yes"
+     * @see https://dhoulb.github.io/shelving/schema/ChoiceSchema/ChoiceSchema/validate
+     */
     validate(unsafeValue?: unknown): O;
+    /**
+     * Format a validated choice as its human-readable title.
+     *
+     * @param value The valid choice key to format.
+     * @returns The choice's title from `options`.
+     * @example schema.format("yes") // "Yes"
+     * @see https://dhoulb.github.io/shelving/schema/ChoiceSchema/ChoiceSchema/format
+     */
     format(value: O): string;
 }
-/** Choose from an allowed set of values. */
+/**
+ * Create a schema for a valid choice from an allowed set of values.
+ *
+ * *Factory for `ChoiceSchema`.*
+ *
+ * @param options The allowed choices, as a `{ key: title }` dictionary or an array of keys.
+ * @returns A `ChoiceSchema` validating the given choices.
+ * @example CHOICE({ yes: "Yes", no: "No" }) // ChoiceSchema<"yes" | "no">
+ * @see https://dhoulb.github.io/shelving/schema/ChoiceSchema/CHOICE
+ */
 export declare function CHOICE<K extends string>(options: PossibleChoiceOptions<K>): ChoiceSchema<K>;

package/schema/ChoiceSchema.js

@@ -8,23 +8,65 @@ function _getChoiceOptions(options) {
 function _getChoiceOption(k) {
     return [k, k];
 }
-/** Choose from an allowed set of values. */
+/**
+ * Schema that validates a value against a fixed set of allowed string choices.
+ *
+ * - The input must be one of the keys in `options`, otherwise it is rejected.
+ * - Each choice has a human-readable title used by `format()`.
+ *
+ * @example
+ *  const schema = new ChoiceSchema({ options: { yes: "Yes", no: "No" } });
+ *  schema.validate("yes"); // "yes"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/ChoiceSchema/ChoiceSchema
+ */
 export class ChoiceSchema extends Schema {
     options;
+    /**
+     * Create a new `ChoiceSchema`.
+     *
+     * @param options Options for the schema, including the allowed `options` and an optional default `value`.
+     */
     constructor({ one = "choice", title = "Choice", placeholder = `No ${one}`, options, value, ...rest }) {
         super({ one, title, value, placeholder, ...rest });
         this.options = _getChoiceOptions(options);
     }
+    /**
+     * Validate an unknown value as one of the allowed choices.
+     *
+     * @param unsafeValue The unknown input value to validate (defaults to this schema's `value`).
+     * @returns The valid choice key.
+     * @throws `string` `"Required"` if the value is empty or missing, or `` `Unknown ${one}` `` if it is not one of the allowed choices.
+     * @example schema.validate("yes") // "yes"
+     * @see https://dhoulb.github.io/shelving/schema/ChoiceSchema/ChoiceSchema/validate
+     */
     validate(unsafeValue = this.value) {
         if (typeof unsafeValue === "string" && isProp(this.options, unsafeValue))
             return unsafeValue;
         throw unsafeValue ? `Unknown ${this.one}` : "Required";
     }
+    /**
+     * Format a validated choice as its human-readable title.
+     *
+     * @param value The valid choice key to format.
+     * @returns The choice's title from `options`.
+     * @example schema.format("yes") // "Yes"
+     * @see https://dhoulb.github.io/shelving/schema/ChoiceSchema/ChoiceSchema/format
+     */
     format(value) {
         return this.options[value];
     }
 }
-/** Choose from an allowed set of values. */
+/**
+ * Create a schema for a valid choice from an allowed set of values.
+ *
+ * *Factory for `ChoiceSchema`.*
+ *
+ * @param options The allowed choices, as a `{ key: title }` dictionary or an array of keys.
+ * @returns A `ChoiceSchema` validating the given choices.
+ * @example CHOICE({ yes: "Yes", no: "No" }) // ChoiceSchema<"yes" | "no">
+ * @see https://dhoulb.github.io/shelving/schema/ChoiceSchema/CHOICE
+ */
 export function CHOICE(options) {
     return new ChoiceSchema({ options });
 }

package/schema/ColorSchema.d.ts

@@ -1,21 +1,54 @@
 import { StringSchema, type StringSchemaOptions } from "./StringSchema.js";
-/** Options for a `ColorSchema` */
+/**
+ * Options for a `ColorSchema`.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/ColorSchema/ColorSchemaOptions
+ */
 export interface ColorSchemaOptions extends Omit<StringSchemaOptions, "type" | "min" | "max" | "match" | "rows"> {
 }
 /**
- * Define a valid color hex string, e.g `#00CCFF`
+ * Schema that defines a valid color hex string, e.g. `#00CCFF`
  *
- * Ensures value is a string, enforces that the string is a valid Color.
- * Checks Color scheme against a whitelist (always), and checks Color domain against a whitelist (optional).
- * `null` is also a valid value if this field is not required.
+ * - Coerces the value to a six-digit uppercase `#RRGGBB` hex string.
+ * - Rejects anything that isn't a valid hex color (use `NULLABLE_COLOR` to also allow `null`).
  *
- * Colors are limited to 512 characters (this can be changed with `max`), but generally these won't be data: URIs so this is a reasonable limit.
+ * @example COLOR.validate("00ccff"); // Returns "#00CCFF"
+ * @see https://dhoulb.github.io/shelving/schema/ColorSchema/ColorSchema
  */
 export declare class ColorSchema extends StringSchema {
+    /**
+     * Create a new `ColorSchema`.
+     *
+     * @param options Options for the schema (inherits `StringSchema` options except `type`, `min`, `max`, `match`, and `rows`, which are fixed for hex colors).
+     * @param options.one Singular noun describing one value, used in error messages (defaults to `"color"`).
+     * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Color"`).
+     * @param options.value Default hex value used when the input is `undefined` (defaults to `"#000000"`).
+     */
     constructor({ one, title, value, ...options }: ColorSchemaOptions);
+    /**
+     * Sanitize the string into a `#RRGGBB` hex color.
+     *
+     * - Uppercases the input and strips every non-hex character.
+     * - Prefixes the first six hex digits with `#`, or returns `""` when there are none.
+     *
+     * @param insaneString String to sanitize.
+     * @returns The sanitized hex color, or `""` if no hex digits are present.
+     * @example COLOR.sanitize("00ccff"); // Returns "#00CCFF"
+     * @see https://dhoulb.github.io/shelving/schema/ColorSchema/ColorSchema/sanitize
+     */
     sanitize(insaneString: string): string;
 }
-/** Valid color hex string, e.g. `#00CCFF` (required because empty string is invalid). */
+/**
+ * Valid color hex string, e.g. `#00CCFF` (required because empty string is invalid).
+ *
+ * @example COLOR.validate("#00CCFF"); // Returns "#00CCFF"
+ * @see https://dhoulb.github.io/shelving/schema/ColorSchema/COLOR
+ */
 export declare const COLOR: ColorSchema;
-/** Valid color hex string, e.g. `#00CCFF`, or `null` */
+/**
+ * Valid color hex string, e.g. `#00CCFF`, or `null`
+ *
+ * @example NULLABLE_COLOR.validate(null); // Returns null
+ * @see https://dhoulb.github.io/shelving/schema/ColorSchema/NULLABLE_COLOR
+ */
 export declare const NULLABLE_COLOR: import("./NullableSchema.js").NullableSchema<string>;

package/schema/ColorSchema.js

@@ -3,15 +3,23 @@ import { StringSchema } from "./StringSchema.js";
 const COLOR_REGEXP = /^#[0-9A-F]{6}$/;
 const NOT_HEX_REGEXP = /[^0-9A-F]/g;
 /**
- * Define a valid color hex string, e.g `#00CCFF`
+ * Schema that defines a valid color hex string, e.g. `#00CCFF`
  *
- * Ensures value is a string, enforces that the string is a valid Color.
- * Checks Color scheme against a whitelist (always), and checks Color domain against a whitelist (optional).
- * `null` is also a valid value if this field is not required.
+ * - Coerces the value to a six-digit uppercase `#RRGGBB` hex string.
+ * - Rejects anything that isn't a valid hex color (use `NULLABLE_COLOR` to also allow `null`).
  *
- * Colors are limited to 512 characters (this can be changed with `max`), but generally these won't be data: URIs so this is a reasonable limit.
+ * @example COLOR.validate("00ccff"); // Returns "#00CCFF"
+ * @see https://dhoulb.github.io/shelving/schema/ColorSchema/ColorSchema
  */
 export class ColorSchema extends StringSchema {
+    /**
+     * Create a new `ColorSchema`.
+     *
+     * @param options Options for the schema (inherits `StringSchema` options except `type`, `min`, `max`, `match`, and `rows`, which are fixed for hex colors).
+     * @param options.one Singular noun describing one value, used in error messages (defaults to `"color"`).
+     * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Color"`).
+     * @param options.value Default hex value used when the input is `undefined` (defaults to `"#000000"`).
+     */
     constructor({ one = "color", title = "Color", value = "#000000", ...options }) {
         super({
             one,
@@ -25,12 +33,33 @@ export class ColorSchema extends StringSchema {
             match: COLOR_REGEXP,
         });
     }
+    /**
+     * Sanitize the string into a `#RRGGBB` hex color.
+     *
+     * - Uppercases the input and strips every non-hex character.
+     * - Prefixes the first six hex digits with `#`, or returns `""` when there are none.
+     *
+     * @param insaneString String to sanitize.
+     * @returns The sanitized hex color, or `""` if no hex digits are present.
+     * @example COLOR.sanitize("00ccff"); // Returns "#00CCFF"
+     * @see https://dhoulb.github.io/shelving/schema/ColorSchema/ColorSchema/sanitize
+     */
     sanitize(insaneString) {
         const saneString = insaneString.toUpperCase().replace(NOT_HEX_REGEXP, "");
         return saneString ? `#${saneString.slice(0, 6)}` : "";
     }
 }
-/** Valid color hex string, e.g. `#00CCFF` (required because empty string is invalid). */
+/**
+ * Valid color hex string, e.g. `#00CCFF` (required because empty string is invalid).
+ *
+ * @example COLOR.validate("#00CCFF"); // Returns "#00CCFF"
+ * @see https://dhoulb.github.io/shelving/schema/ColorSchema/COLOR
+ */
 export const COLOR = new ColorSchema({});
-/** Valid color hex string, e.g. `#00CCFF`, or `null` */
+/**
+ * Valid color hex string, e.g. `#00CCFF`, or `null`
+ *
+ * @example NULLABLE_COLOR.validate(null); // Returns null
+ * @see https://dhoulb.github.io/shelving/schema/ColorSchema/NULLABLE_COLOR
+ */
 export const NULLABLE_COLOR = NULLABLE(COLOR);

package/schema/CountrySchema.d.ts

@@ -1,17 +1,57 @@
 import { type Country, type PossibleCountry } from "../util/geo.js";
 import { ChoiceSchema } from "./ChoiceSchema.js";
 import type { SchemaOptions } from "./Schema.js";
-/** Allowed options for `CountrySchema` */
+/**
+ * Options for `CountrySchema`.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/CountrySchema/CountrySchemaOptions
+ */
 export interface CountrySchemaOptions extends SchemaOptions {
     /** Country value, or `"detect"` to resolve from browser language. */
     readonly value?: PossibleCountry;
 }
-/** Schema that validates an ISO country code. */
+/**
+ * Schema that defines a valid ISO 3166 country code, e.g. `GB`.
+ *
+ * - The input is coerced with `getCountry`, then checked against the known set of `COUNTRIES`.
+ * - A `value` of `"detect"` resolves the default country from the browser language.
+ *
+ * @example
+ *  const schema = new CountrySchema({});
+ *  schema.validate("GB"); // "GB"
+ * @see https://dhoulb.github.io/shelving/schema/CountrySchema/CountrySchema
+ */
 export declare class CountrySchema extends ChoiceSchema<Country, PossibleCountry> {
+    /**
+     * Create a new `CountrySchema`.
+     *
+     * @param options Options for the schema (`value`, plus base `SchemaOptions`).
+     * @example new CountrySchema({ value: "GB" })
+     * @see https://dhoulb.github.io/shelving/schema/CountrySchema/CountrySchema
+     */
     constructor({ one, title, value, ...options }?: CountrySchemaOptions);
+    /**
+     * Validate an unknown input value and return a valid country code.
+     *
+     * @param unsafeValue The value to validate (defaults to this schema's `value`).
+     * @returns The validated ISO 3166 country code.
+     * @throws `string` `"Required"` if the value is empty, or `` `Unknown ${one}` `` if it is not a known country.
+     * @example schema.validate("GB") // "GB"
+     * @see https://dhoulb.github.io/shelving/schema/CountrySchema/CountrySchema/validate
+     */
     validate(unsafeValue?: unknown): Country;
 }
-/** Valid country code, e.g. `GB` (required because falsy values are invalid). */
+/**
+ * Valid country code, e.g. `GB` (required because falsy values are invalid).
+ *
+ * @example COUNTRY.validate("GB") // "GB"
+ * @see https://dhoulb.github.io/shelving/schema/CountrySchema/COUNTRY
+ */
 export declare const COUNTRY: CountrySchema;
-/** Valid country code, e.g. `GB`, or `null` */
+/**
+ * Valid country code, e.g. `GB`, or `null`.
+ *
+ * @example NULLABLE_COUNTRY.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/CountrySchema/NULLABLE_COUNTRY
+ */
 export declare const NULLABLE_COUNTRY: import("./NullableSchema.js").NullableSchema<"AD" | "AE" | "AF" | "AG" | "AI" | "AL" | "AM" | "AN" | "AO" | "AQ" | "AR" | "AS" | "AT" | "AU" | "AW" | "AX" | "AZ" | "BA" | "BB" | "BD" | "BE" | "BF" | "BG" | "BH" | "BI" | "BJ" | "BL" | "BM" | "BN" | "BO" | "BR" | "BS" | "BT" | "BV" | "BW" | "BY" | "BZ" | "CA" | "CC" | "CD" | "CF" | "CG" | "CH" | "CI" | "CK" | "CL" | "CM" | "CN" | "CO" | "CR" | "CU" | "CV" | "CX" | "CY" | "CZ" | "DE" | "DJ" | "DK" | "DM" | "DO" | "DZ" | "EC" | "EE" | "EG" | "EH" | "ER" | "ES" | "ET" | "FI" | "FJ" | "FK" | "FM" | "FO" | "FR" | "GA" | "GB" | "GD" | "GE" | "GF" | "GG" | "GH" | "GI" | "GL" | "GM" | "GN" | "GP" | "GQ" | "GR" | "GS" | "GT" | "GU" | "GW" | "GY" | "HK" | "HM" | "HN" | "HR" | "HT" | "HU" | "ID" | "IE" | "IL" | "IM" | "IN" | "IO" | "IQ" | "IR" | "IS" | "IT" | "JE" | "JM" | "JO" | "JP" | "KE" | "KG" | "KH" | "KI" | "KM" | "KN" | "KP" | "KR" | "KW" | "KY" | "KZ" | "LA" | "LB" | "LC" | "LI" | "LK" | "LR" | "LS" | "LT" | "LU" | "LV" | "LY" | "MA" | "MC" | "MD" | "ME" | "MF" | "MG" | "MH" | "MK" | "ML" | "MM" | "MN" | "MO" | "MP" | "MQ" | "MR" | "MS" | "MT" | "MU" | "MV" | "MW" | "MX" | "MY" | "MZ" | "NA" | "NC" | "NE" | "NF" | "NG" | "NI" | "NL" | "NO" | "NP" | "NR" | "NU" | "NZ" | "OM" | "PA" | "PE" | "PF" | "PG" | "PH" | "PK" | "PL" | "PM" | "PN" | "PR" | "PS" | "PT" | "PW" | "PY" | "QA" | "RE" | "RO" | "RS" | "RU" | "RW" | "SA" | "SB" | "SC" | "SD" | "SE" | "SG" | "SH" | "SI" | "SJ" | "SK" | "SL" | "SM" | "SN" | "SO" | "SR" | "ST" | "SV" | "SY" | "SZ" | "TC" | "TD" | "TF" | "TG" | "TH" | "TJ" | "TK" | "TL" | "TM" | "TN" | "TO" | "TR" | "TT" | "TV" | "TW" | "TZ" | "UA" | "UG" | "UM" | "US" | "UY" | "UZ" | "VA" | "VC" | "VE" | "VG" | "VI" | "VN" | "VU" | "WF" | "WS" | "YE" | "YT" | "ZA" | "ZM" | "ZW">;

package/schema/CountrySchema.js

@@ -1,11 +1,37 @@
 import { COUNTRIES, getCountry } from "../util/geo.js";
 import { ChoiceSchema } from "./ChoiceSchema.js";
 import { NULLABLE } from "./NullableSchema.js";
-/** Schema that validates an ISO country code. */
+/**
+ * Schema that defines a valid ISO 3166 country code, e.g. `GB`.
+ *
+ * - The input is coerced with `getCountry`, then checked against the known set of `COUNTRIES`.
+ * - A `value` of `"detect"` resolves the default country from the browser language.
+ *
+ * @example
+ *  const schema = new CountrySchema({});
+ *  schema.validate("GB"); // "GB"
+ * @see https://dhoulb.github.io/shelving/schema/CountrySchema/CountrySchema
+ */
 export class CountrySchema extends ChoiceSchema {
+    /**
+     * Create a new `CountrySchema`.
+     *
+     * @param options Options for the schema (`value`, plus base `SchemaOptions`).
+     * @example new CountrySchema({ value: "GB" })
+     * @see https://dhoulb.github.io/shelving/schema/CountrySchema/CountrySchema
+     */
     constructor({ one = "country", title = "Country", value = "detect", ...options } = {}) {
         super({ one, title, options: COUNTRIES, value, ...options });
     }
+    /**
+     * Validate an unknown input value and return a valid country code.
+     *
+     * @param unsafeValue The value to validate (defaults to this schema's `value`).
+     * @returns The validated ISO 3166 country code.
+     * @throws `string` `"Required"` if the value is empty, or `` `Unknown ${one}` `` if it is not a known country.
+     * @example schema.validate("GB") // "GB"
+     * @see https://dhoulb.github.io/shelving/schema/CountrySchema/CountrySchema/validate
+     */
     validate(unsafeValue = this.value) {
         const country = getCountry(unsafeValue);
         if (country)
@@ -13,7 +39,17 @@ export class CountrySchema extends ChoiceSchema {
         throw unsafeValue === "detect" ? "Required" : `Unknown ${this.one}`;
     }
 }
-/** Valid country code, e.g. `GB` (required because falsy values are invalid). */
+/**
+ * Valid country code, e.g. `GB` (required because falsy values are invalid).
+ *
+ * @example COUNTRY.validate("GB") // "GB"
+ * @see https://dhoulb.github.io/shelving/schema/CountrySchema/COUNTRY
+ */
 export const COUNTRY = new CountrySchema({});
-/** Valid country code, e.g. `GB`, or `null` */
+/**
+ * Valid country code, e.g. `GB`, or `null`.
+ *
+ * @example NULLABLE_COUNTRY.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/CountrySchema/NULLABLE_COUNTRY
+ */
 export const NULLABLE_COUNTRY = NULLABLE(COUNTRY);