shelving 1.236.0 → 1.236.2

package/schema/NumberSchema.d.ts

@@ -1,7 +1,16 @@
 import { formatNumber } from "../util/format.js";
 import type { SchemaOptions } from "./Schema.js";
 import { Schema } from "./Schema.js";
-/** Allowed options for `NumberSchema` */
+/**
+ * Allowed options for `NumberSchema`.
+ *
+ * - `value` — default number value used when the input is `undefined`.
+ * - `min`/`max` — minimum and maximum allowed value.
+ * - `step` — rounding step the value is snapped to (e.g. `1` for integers).
+ * - `format` — function used to render the number for display in downstream UIs.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NumberSchemaOptions
+ */
 export interface NumberSchemaOptions extends SchemaOptions {
     readonly value?: number | undefined;
     readonly min?: number | undefined;
@@ -10,33 +19,149 @@ export interface NumberSchemaOptions extends SchemaOptions {
     /** Format the number for display in downstream UIs. */
     readonly format?: typeof formatNumber | undefined;
 }
-/** Schema that defines a valid number. */
+/**
+ * Schema that defines a valid number.
+ *
+ * - Values are coerced with `getNumber`; anything that cannot become a number is rejected.
+ * - The number is snapped to `step` (if set), then checked against `min` and `max`.
+ *
+ * @example
+ *  const schema = new NumberSchema({ min: 0, max: 100, step: 1 });
+ *  schema.validate("42"); // Returns 42
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NumberSchema
+ */
 export declare class NumberSchema extends Schema<number> {
     readonly value: number | undefined;
     readonly min: number;
     readonly max: number;
     readonly step: number | undefined;
+    /**
+     * Create a new `NumberSchema`.
+     *
+     * @param options Options for the schema.
+     * @param options.one Singular noun describing one value, used in error messages (defaults to `"number"`).
+     * @param options.title Human-readable title for the schema (defaults to `"Number"`).
+     * @param options.min Minimum allowed value (defaults to `Number.NEGATIVE_INFINITY`).
+     * @param options.max Maximum allowed value (defaults to `Number.POSITIVE_INFINITY`).
+     * @param options.step Rounding step the value is snapped to.
+     * @param options.format Function used to render the number for display (defaults to `formatNumber`).
+     * @param options.value Default number value used when the input is `undefined`.
+     */
     constructor({ one, title, min, max, step, format, value, ...options }: NumberSchemaOptions);
+    /**
+     * Validate an unknown value and coerce it to a number.
+     *
+     * @param value Value to validate (defaults to this schema's `value`).
+     * @returns The coerced (and optionally stepped) number value.
+     * @throws `string` `"Required"` if the value is empty or missing, `` `Must be ${one}` `` if it cannot be coerced to a number, `` `Minimum ${min}` `` if below `min`, or `` `Maximum ${max}` `` if above `max`.
+     *
+     * @example
+     *  NUMBER.validate("42"); // Returns 42
+     *
+     * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NumberSchema/validate
+     */
     validate(value?: unknown): number;
+    /**
+     * Format a number value as a human-readable string for display.
+     *
+     * @param value Number value to format.
+     * @returns The formatted string.
+     *
+     * @example
+     *  NUMBER.format(2048.5); // Returns "2,048.5"
+     *
+     * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NumberSchema/format
+     */
     format(value: number): string;
 }
-/** Valid number, e.g. `2048.12345` or `0` zero and a default value of zero. */
+/**
+ * Valid number, e.g. `2048.12345` or `0` zero and a default value of zero.
+ *
+ * @example
+ *  NUMBER.validate("42"); // Returns 42
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NUMBER
+ */
 export declare const NUMBER: NumberSchema;
-/** Valid optional number, e.g. `2048.12345` or `0` zero, or `null` */
+/**
+ * Valid optional number, e.g. `2048.12345` or `0` zero, or `null`.
+ *
+ * @example
+ *  NULLABLE_NUMBER.validate(null); // Returns null
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NULLABLE_NUMBER
+ */
 export declare const NULLABLE_NUMBER: import("./NullableSchema.js").NullableSchema<number>;
-/** Valid integer number, e.g. `2048` or `0` zero. */
+/**
+ * Valid integer number, e.g. `2048` or `0` zero.
+ *
+ * @example
+ *  INTEGER.validate("42.7"); // Returns 43 (rounded to step)
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/INTEGER
+ */
 export declare const INTEGER: NumberSchema;
-/** Valid positive integer number, e.g. `1,2,3` (not including zero). */
+/**
+ * Valid positive integer number, e.g. `1,2,3` (not including zero).
+ *
+ * @example
+ *  POSITIVE_INTEGER.validate(0); // Throws "Required"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/POSITIVE_INTEGER
+ */
 export declare const POSITIVE_INTEGER: NumberSchema;
-/** Valid non-negative integer number, e.g. `0,1,2,3` (including zero). */
+/**
+ * Valid non-negative integer number, e.g. `0,1,2,3` (including zero).
+ *
+ * @example
+ *  NON_NEGATIVE_INTEGER.validate(0); // Returns 0
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NON_NEGATIVE_INTEGER
+ */
 export declare const NON_NEGATIVE_INTEGER: NumberSchema;
-/** Valid negative integer number, e.g. `-1,-2,-3` (not including zero). */
+/**
+ * Valid negative integer number, e.g. `-1,-2,-3` (not including zero).
+ *
+ * @example
+ *  NEGATIVE_INTEGER.validate(-3); // Returns -3
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NEGATIVE_INTEGER
+ */
 export declare const NEGATIVE_INTEGER: NumberSchema;
-/** Valid non-positive integer number, e.g. `0,-1,-2,-3` (including zero). */
+/**
+ * Valid non-positive integer number, e.g. `0,-1,-2,-3` (including zero).
+ *
+ * @example
+ *  NON_POSITIVE_INTEGER.validate(0); // Returns 0
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NON_POSITIVE_INTEGER
+ */
 export declare const NON_POSITIVE_INTEGER: NumberSchema;
-/** Valid optional integer number, e.g. `2048` or `0` zero, or `null` */
+/**
+ * Valid optional integer number, e.g. `2048` or `0` zero, or `null`.
+ *
+ * @example
+ *  NULLABLE_INTEGER.validate(null); // Returns null
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NULLABLE_INTEGER
+ */
 export declare const NULLABLE_INTEGER: import("./NullableSchema.js").NullableSchema<number>;
-/** Valid Unix timestamp (including milliseconds). */
+/**
+ * Valid Unix timestamp (including milliseconds).
+ *
+ * @example
+ *  TIMESTAMP.validate(1700000000000); // Returns 1700000000000
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/TIMESTAMP
+ */
 export declare const TIMESTAMP: NumberSchema;
-/** Valid Unix timestamp (including milliseconds). */
+/**
+ * Valid optional Unix timestamp (including milliseconds), or `null`.
+ *
+ * @example
+ *  NULLABLE_TIMESTAMP.validate(null); // Returns null
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NULLABLE_TIMESTAMP
+ */
 export declare const NULLABLE_TIMESTAMP: import("./NullableSchema.js").NullableSchema<number>;

package/schema/NumberSchema.js

@@ -2,17 +2,52 @@ import { formatNumber } from "../util/format.js";
 import { getNumber, roundStep } from "../util/number.js";
 import { NULLABLE } from "./NullableSchema.js";
 import { Schema } from "./Schema.js";
-/** Schema that defines a valid number. */
+/**
+ * Schema that defines a valid number.
+ *
+ * - Values are coerced with `getNumber`; anything that cannot become a number is rejected.
+ * - The number is snapped to `step` (if set), then checked against `min` and `max`.
+ *
+ * @example
+ *  const schema = new NumberSchema({ min: 0, max: 100, step: 1 });
+ *  schema.validate("42"); // Returns 42
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NumberSchema
+ */
 export class NumberSchema extends Schema {
     min;
     max;
     step;
+    /**
+     * Create a new `NumberSchema`.
+     *
+     * @param options Options for the schema.
+     * @param options.one Singular noun describing one value, used in error messages (defaults to `"number"`).
+     * @param options.title Human-readable title for the schema (defaults to `"Number"`).
+     * @param options.min Minimum allowed value (defaults to `Number.NEGATIVE_INFINITY`).
+     * @param options.max Maximum allowed value (defaults to `Number.POSITIVE_INFINITY`).
+     * @param options.step Rounding step the value is snapped to.
+     * @param options.format Function used to render the number for display (defaults to `formatNumber`).
+     * @param options.value Default number value used when the input is `undefined`.
+     */
     constructor({ one = "number", title = "Number", min = Number.NEGATIVE_INFINITY, max = Number.POSITIVE_INFINITY, step, format = formatNumber, value, ...options }) {
         super({ one, title, value, ...options });
         this.min = min;
         this.max = max;
         this.step = step;
     }
+    /**
+     * Validate an unknown value and coerce it to a number.
+     *
+     * @param value Value to validate (defaults to this schema's `value`).
+     * @returns The coerced (and optionally stepped) number value.
+     * @throws `string` `"Required"` if the value is empty or missing, `` `Must be ${one}` `` if it cannot be coerced to a number, `` `Minimum ${min}` `` if below `min`, or `` `Maximum ${max}` `` if above `max`.
+     *
+     * @example
+     *  NUMBER.validate("42"); // Returns 42
+     *
+     * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NumberSchema/validate
+     */
     validate(value = this.value) {
         const number = getNumber(value);
         if (typeof number !== "number")
@@ -24,32 +59,113 @@ export class NumberSchema extends Schema {
             throw `Maximum ${this.format(this.max)}`;
         return stepped;
     }
+    /**
+     * Format a number value as a human-readable string for display.
+     *
+     * @param value Number value to format.
+     * @returns The formatted string.
+     *
+     * @example
+     *  NUMBER.format(2048.5); // Returns "2,048.5"
+     *
+     * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NumberSchema/format
+     */
     format(value) {
         return formatNumber(value);
     }
 }
-/** Valid number, e.g. `2048.12345` or `0` zero and a default value of zero. */
+/**
+ * Valid number, e.g. `2048.12345` or `0` zero and a default value of zero.
+ *
+ * @example
+ *  NUMBER.validate("42"); // Returns 42
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NUMBER
+ */
 export const NUMBER = new NumberSchema({ title: "Number" });
-/** Valid optional number, e.g. `2048.12345` or `0` zero, or `null` */
+/**
+ * Valid optional number, e.g. `2048.12345` or `0` zero, or `null`.
+ *
+ * @example
+ *  NULLABLE_NUMBER.validate(null); // Returns null
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NULLABLE_NUMBER
+ */
 export const NULLABLE_NUMBER = NULLABLE(NUMBER);
-/** Valid integer number, e.g. `2048` or `0` zero. */
+/**
+ * Valid integer number, e.g. `2048` or `0` zero.
+ *
+ * @example
+ *  INTEGER.validate("42.7"); // Returns 43 (rounded to step)
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/INTEGER
+ */
 export const INTEGER = new NumberSchema({ step: 1, min: Number.MIN_SAFE_INTEGER, max: Number.MAX_SAFE_INTEGER });
-/** Valid positive integer number, e.g. `1,2,3` (not including zero). */
+/**
+ * Valid positive integer number, e.g. `1,2,3` (not including zero).
+ *
+ * @example
+ *  POSITIVE_INTEGER.validate(0); // Throws "Required"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/POSITIVE_INTEGER
+ */
 export const POSITIVE_INTEGER = new NumberSchema({ step: 1, min: 1, max: Number.MAX_SAFE_INTEGER });
-/** Valid non-negative integer number, e.g. `0,1,2,3` (including zero). */
+/**
+ * Valid non-negative integer number, e.g. `0,1,2,3` (including zero).
+ *
+ * @example
+ *  NON_NEGATIVE_INTEGER.validate(0); // Returns 0
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NON_NEGATIVE_INTEGER
+ */
 export const NON_NEGATIVE_INTEGER = new NumberSchema({ step: 1, min: 0, max: Number.MAX_SAFE_INTEGER });
-/** Valid negative integer number, e.g. `-1,-2,-3` (not including zero). */
+/**
+ * Valid negative integer number, e.g. `-1,-2,-3` (not including zero).
+ *
+ * @example
+ *  NEGATIVE_INTEGER.validate(-3); // Returns -3
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NEGATIVE_INTEGER
+ */
 export const NEGATIVE_INTEGER = new NumberSchema({ step: 1, min: Number.MIN_SAFE_INTEGER, max: -1 });
-/** Valid non-positive integer number, e.g. `0,-1,-2,-3` (including zero). */
+/**
+ * Valid non-positive integer number, e.g. `0,-1,-2,-3` (including zero).
+ *
+ * @example
+ *  NON_POSITIVE_INTEGER.validate(0); // Returns 0
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NON_POSITIVE_INTEGER
+ */
 export const NON_POSITIVE_INTEGER = new NumberSchema({ step: 1, min: Number.MIN_SAFE_INTEGER, max: 0 });
-/** Valid optional integer number, e.g. `2048` or `0` zero, or `null` */
+/**
+ * Valid optional integer number, e.g. `2048` or `0` zero, or `null`.
+ *
+ * @example
+ *  NULLABLE_INTEGER.validate(null); // Returns null
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NULLABLE_INTEGER
+ */
 export const NULLABLE_INTEGER = NULLABLE(INTEGER);
-/** Valid Unix timestamp (including milliseconds). */
+/**
+ * Valid Unix timestamp (including milliseconds).
+ *
+ * @example
+ *  TIMESTAMP.validate(1700000000000); // Returns 1700000000000
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/TIMESTAMP
+ */
 export const TIMESTAMP = new NumberSchema({
     title: "Timestamp",
     step: 1,
     min: Number.MIN_SAFE_INTEGER,
     max: Number.MAX_SAFE_INTEGER,
 });
-/** Valid Unix timestamp (including milliseconds). */
+/**
+ * Valid optional Unix timestamp (including milliseconds), or `null`.
+ *
+ * @example
+ *  NULLABLE_TIMESTAMP.validate(null); // Returns null
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NumberSchema/NULLABLE_TIMESTAMP
+ */
 export const NULLABLE_TIMESTAMP = NULLABLE_INTEGER;

package/schema/OptionalSchema.d.ts

@@ -1,20 +1,77 @@
 import type { Schema } from "./Schema.js";
 import { ThroughSchema, type ThroughSchemaOptions } from "./ThroughSchema.js";
+/**
+ * Allowed options for `OptionalSchema`.
+ *
+ * - `value` — default value is always `undefined` (the default is only used when a value is `undefined`, so otherwise `undefined` could never be returned).
+ *
+ * @see https://dhoulb.github.io/shelving/schema/OptionalSchema/OptionalSchemaOptions
+ */
 export interface OptionalSchemaOptions<T> extends ThroughSchemaOptions<T | undefined> {
     /** Default value for an `OptionalSchema` can always `undefined` */
     readonly value?: undefined;
 }
 /**
- * Validate a property in an optional way, i.e. it can be the value, or `undefined`
- * - If the prop is `undefined`, then `undefined` is returned.
+ * Schema that wraps a source schema and additionally allows `undefined`.
+ *
+ * - `undefined` input validates to `undefined` instead of being passed to the source schema.
  * - When used with `validateData()` this means the prop can be silently skipped.
+ * - Any other value is delegated to the source schema for validation.
+ *
+ * @example
+ *  const schema = new OptionalSchema({ source: STRING });
+ *  schema.validate(undefined); // Returns undefined
+ *  schema.validate("abc"); // Returns "abc"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/OptionalSchema/OptionalSchema
  */
 export declare class OptionalSchema<T> extends ThroughSchema<T | undefined> {
     /** Default value for an `OptionalSchema` is always `undefined` (default value is only used when a value is `undefined`, so otherwise `undefined` could never be returned as a value). */
     readonly value: undefined;
+    /**
+     * Create a new `OptionalSchema`.
+     *
+     * @param options Options for the schema, including the `source` schema to wrap.
+     */
     constructor(options: OptionalSchemaOptions<T>);
+    /**
+     * Validate an unknown value, returning `undefined` for `undefined` input or delegating to the source schema.
+     *
+     * @param unsafeValue Value to validate.
+     * @returns The valid value of type `T`, or `undefined` when the input is `undefined`.
+     * @throws `string` error message if the source schema rejects the value.
+     *
+     * @example
+     *  OPTIONAL(STRING).validate(undefined); // Returns undefined
+     *
+     * @see https://dhoulb.github.io/shelving/schema/OptionalSchema/OptionalSchema/validate
+     */
     validate(unsafeValue: unknown): T | undefined;
+    /**
+     * Format an optional value as a human-readable string for display.
+     *
+     * @param value Value to format, or `undefined`.
+     * @returns The formatted string, or `` `No ${one}` `` when the value is `undefined`.
+     *
+     * @example
+     *  OPTIONAL(STRING).format(undefined); // Returns "No string"
+     *
+     * @see https://dhoulb.github.io/shelving/schema/OptionalSchema/OptionalSchema/format
+     */
     format(value: T | undefined): string;
 }
-/** Make a property of a set of data optional, i.e. it can be the value or `undefined` */
-export declare const OPTIONAL: <T>(source: Schema<T>) => OptionalSchema<T>;
+/**
+ * Create an `OptionalSchema` that wraps a source schema and also allows `undefined`.
+ *
+ * *Factory for `OptionalSchema`.*
+ *
+ * @param source Source schema to wrap.
+ * @returns An `OptionalSchema` wrapping `source`.
+ *
+ * @example
+ *  const schema = OPTIONAL(STRING);
+ *  schema.validate(undefined); // Returns undefined
+ *
+ * @see https://dhoulb.github.io/shelving/schema/OptionalSchema/OPTIONAL
+ */
+export declare function OPTIONAL<T>(source: Schema<T>): OptionalSchema<T>;

package/schema/OptionalSchema.js

@@ -1,21 +1,73 @@
 import { ThroughSchema } from "./ThroughSchema.js";
 /**
- * Validate a property in an optional way, i.e. it can be the value, or `undefined`
- * - If the prop is `undefined`, then `undefined` is returned.
+ * Schema that wraps a source schema and additionally allows `undefined`.
+ *
+ * - `undefined` input validates to `undefined` instead of being passed to the source schema.
  * - When used with `validateData()` this means the prop can be silently skipped.
+ * - Any other value is delegated to the source schema for validation.
+ *
+ * @example
+ *  const schema = new OptionalSchema({ source: STRING });
+ *  schema.validate(undefined); // Returns undefined
+ *  schema.validate("abc"); // Returns "abc"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/OptionalSchema/OptionalSchema
  */
 export class OptionalSchema extends ThroughSchema {
+    /**
+     * Create a new `OptionalSchema`.
+     *
+     * @param options Options for the schema, including the `source` schema to wrap.
+     */
     constructor(options) {
         super({ ...options, value: undefined });
     }
+    /**
+     * Validate an unknown value, returning `undefined` for `undefined` input or delegating to the source schema.
+     *
+     * @param unsafeValue Value to validate.
+     * @returns The valid value of type `T`, or `undefined` when the input is `undefined`.
+     * @throws `string` error message if the source schema rejects the value.
+     *
+     * @example
+     *  OPTIONAL(STRING).validate(undefined); // Returns undefined
+     *
+     * @see https://dhoulb.github.io/shelving/schema/OptionalSchema/OptionalSchema/validate
+     */
     validate(unsafeValue) {
         if (unsafeValue === undefined)
             return undefined;
         return super.validate(unsafeValue);
     }
+    /**
+     * Format an optional value as a human-readable string for display.
+     *
+     * @param value Value to format, or `undefined`.
+     * @returns The formatted string, or `` `No ${one}` `` when the value is `undefined`.
+     *
+     * @example
+     *  OPTIONAL(STRING).format(undefined); // Returns "No string"
+     *
+     * @see https://dhoulb.github.io/shelving/schema/OptionalSchema/OptionalSchema/format
+     */
     format(value) {
         return value === undefined ? `No ${this.source.one}` : super.format(value);
     }
 }
-/** Make a property of a set of data optional, i.e. it can be the value or `undefined` */
-export const OPTIONAL = (source) => new OptionalSchema({ source });
+/**
+ * Create an `OptionalSchema` that wraps a source schema and also allows `undefined`.
+ *
+ * *Factory for `OptionalSchema`.*
+ *
+ * @param source Source schema to wrap.
+ * @returns An `OptionalSchema` wrapping `source`.
+ *
+ * @example
+ *  const schema = OPTIONAL(STRING);
+ *  schema.validate(undefined); // Returns undefined
+ *
+ * @see https://dhoulb.github.io/shelving/schema/OptionalSchema/OPTIONAL
+ */
+export function OPTIONAL(source) {
+    return new OptionalSchema({ source });
+}

package/schema/PasswordSchema.d.ts

@@ -1,9 +1,45 @@
 import { StringSchema, type StringSchemaOptions } from "./StringSchema.js";
+/**
+ * Options for a `PasswordSchema`.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/PasswordSchema/PasswordSchemaOptions
+ */
 export interface PasswordSchemaOptions extends Omit<StringSchemaOptions, "input"> {
 }
+/**
+ * Schema that defines a valid password string.
+ *
+ * - Forces the `<input />` hint to `"password"` for downstream UIs.
+ * - Never formats the value for display (`format()` always returns `""`).
+ *
+ * @example new PasswordSchema({}).validate("hunter2"); // Returns "hunter2"
+ * @see https://dhoulb.github.io/shelving/schema/PasswordSchema/PasswordSchema
+ */
 export declare class PasswordSchema extends StringSchema {
+    /**
+     * Create a new `PasswordSchema`.
+     *
+     * @param options Options for the schema (inherits `StringSchema` options except `input`, which is fixed to `"password"`).
+     * @param options.one Singular noun describing one value, used in error messages (defaults to `"password"`).
+     * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Password"`).
+     * @param options.min Minimum allowed character length (defaults to `6`).
+     */
     constructor({ one, title, min, ...options }?: PasswordSchemaOptions);
+    /**
+     * Format a password value for display (always returns `""`).
+     *
+     * - Passwords are never shown, so this deliberately yields an empty string.
+     *
+     * @returns An empty string.
+     * @example new PasswordSchema({}).format("hunter2"); // Returns ""
+     * @see https://dhoulb.github.io/shelving/schema/PasswordSchema/PasswordSchema/format
+     */
     format(): string;
 }
-/** Password string. */
+/**
+ * Password string.
+ *
+ * @example PASSWORD.validate("hunter2"); // Returns "hunter2"
+ * @see https://dhoulb.github.io/shelving/schema/PasswordSchema/PASSWORD
+ */
 export declare const PASSWORD: StringSchema;

package/schema/PasswordSchema.js

@@ -1,11 +1,42 @@
 import { StringSchema } from "./StringSchema.js";
+/**
+ * Schema that defines a valid password string.
+ *
+ * - Forces the `<input />` hint to `"password"` for downstream UIs.
+ * - Never formats the value for display (`format()` always returns `""`).
+ *
+ * @example new PasswordSchema({}).validate("hunter2"); // Returns "hunter2"
+ * @see https://dhoulb.github.io/shelving/schema/PasswordSchema/PasswordSchema
+ */
 export class PasswordSchema extends StringSchema {
+    /**
+     * Create a new `PasswordSchema`.
+     *
+     * @param options Options for the schema (inherits `StringSchema` options except `input`, which is fixed to `"password"`).
+     * @param options.one Singular noun describing one value, used in error messages (defaults to `"password"`).
+     * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Password"`).
+     * @param options.min Minimum allowed character length (defaults to `6`).
+     */
     constructor({ one = "password", title = "Password", min = 6, ...options } = {}) {
         super({ one, title, min, ...options, input: "password" });
     }
+    /**
+     * Format a password value for display (always returns `""`).
+     *
+     * - Passwords are never shown, so this deliberately yields an empty string.
+     *
+     * @returns An empty string.
+     * @example new PasswordSchema({}).format("hunter2"); // Returns ""
+     * @see https://dhoulb.github.io/shelving/schema/PasswordSchema/PasswordSchema/format
+     */
     format() {
         return ""; // Never format a password for display.
     }
 }
-/** Password string. */
+/**
+ * Password string.
+ *
+ * @example PASSWORD.validate("hunter2"); // Returns "hunter2"
+ * @see https://dhoulb.github.io/shelving/schema/PasswordSchema/PASSWORD
+ */
 export const PASSWORD = new StringSchema({});

package/schema/PhoneSchema.d.ts

@@ -1,18 +1,54 @@
 import type { StringSchemaOptions } from "./StringSchema.js";
 import { StringSchema } from "./StringSchema.js";
-/** Options for a `PhoneSchema` */
+/**
+ * Options for a `PhoneSchema`.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/PhoneSchema/PhoneSchemaOptions
+ */
 export interface PhoneSchemaOptions extends Omit<StringSchemaOptions, "input" | "min" | "max" | "match" | "rows"> {
 }
 /**
- * Type of `StringSchema` that defines a valid phone number.
+ * Schema that defines a valid phone number.
+ *
  * - Multiple string formats are automatically converted to E.164 format (starting with `+` plus).
  * - Falsy values are converted to `""` empty string.
+ *
+ * @example PHONE.validate("+44 1234 567890"); // Returns "+441234567890"
+ * @see https://dhoulb.github.io/shelving/schema/PhoneSchema/PhoneSchema
  */
 export declare class PhoneSchema extends StringSchema {
+    /**
+     * Create a new `PhoneSchema`.
+     *
+     * @param options Options for the schema (inherits `StringSchema` options except `input`, `min`, `max`, `match`, and `rows`, which are fixed for phone numbers).
+     * @param options.one Singular noun describing one value, used in error messages (defaults to `"phone number"`).
+     * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Phone"`).
+     */
     constructor({ one, title, ...options }: PhoneSchemaOptions);
+    /**
+     * Sanitize the string into a valid E.164 phone number.
+     *
+     * - Strips every character that isn't `0`–`9` or `+` plus (including whitespace).
+     * - Keeps a `+` plus only when it is the first character.
+     *
+     * @param insaneString String to sanitize.
+     * @returns The sanitized phone number.
+     * @example PHONE.sanitize("+44 (1234) 567890"); // Returns "+441234567890"
+     * @see https://dhoulb.github.io/shelving/schema/PhoneSchema/PhoneSchema/sanitize
+     */
     sanitize(insaneString: string): string;
 }
-/** Valid phone number, e.g. `+441234567890` */
+/**
+ * Valid phone number, e.g. `+441234567890`
+ *
+ * @example PHONE.validate("+441234567890"); // Returns "+441234567890"
+ * @see https://dhoulb.github.io/shelving/schema/PhoneSchema/PHONE
+ */
 export declare const PHONE: PhoneSchema;
-/** Valid phone number, e.g. `+441234567890`, or `null` */
+/**
+ * Valid phone number, e.g. `+441234567890`, or `null`
+ *
+ * @example NULLABLE_PHONE.validate(null); // Returns null
+ * @see https://dhoulb.github.io/shelving/schema/PhoneSchema/NULLABLE_PHONE
+ */
 export declare const NULLABLE_PHONE: import("./NullableSchema.js").NullableSchema<string>;