shelving 1.236.0 → 1.236.2

package/schema/StringSchema.js

@@ -4,17 +4,16 @@ import { Schema } from "./Schema.js";
 /**
  * Schema that defines a valid string.
  *
+ * - Numbers are coerced to strings; all other non-string values are rejected.
+ * - The value is sanitized (and optionally case-folded), then checked against `match`, `min`, and `max`.
+ *
  * @example
- *  const schema = new StringSchema({ default: 'abc', required: true, min: 2, max: 6, match: /^[a-z0-9]+$/, trim: true });
- *  schema.validate('def'); // Returns 'def'
- *  schema.validate('abcdefghijk'); // Returns 'abcdef' (due to max)
- *  schema.validate(undefined); // Returns 'abc' (due to value)
- *  schema.validate('   ghi   '); // Returns 'ghi' (due to schema.trim, defaults to true)
- *  schema.validate(1234); // Returns '1234' (numbers are converted to strings)
- *  schema.validate('---'); // Throws 'Incorrect)
- *  schema.validate(true); // Throws 'Must be)
- *  schema.validate(''); // Throws Required
- *  schema.validate('j'); // Throws 'Minimum 3 chaacters'
+ *  const schema = new StringSchema({ min: 2, max: 6, match: /^[a-z0-9]+$/ });
+ *  schema.validate("def"); // Returns "def"
+ *  schema.validate(1234); // Returns "1234" (numbers are coerced)
+ *  schema.validate("j"); // Throws "Minimum 2 characters"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/StringSchema/StringSchema
  */
 export class StringSchema extends Schema {
     input;
@@ -23,6 +22,19 @@ export class StringSchema extends Schema {
     rows;
     match;
     case;
+    /**
+     * Create a new `StringSchema`.
+     *
+     * @param options Options for the schema.
+     * @param options.one Singular noun describing one value, used in error messages (defaults to `"string"`).
+     * @param options.min Minimum allowed character length (defaults to `0`).
+     * @param options.max Maximum allowed character length (defaults to `Number.POSITIVE_INFINITY`).
+     * @param options.value Default string value used when the input is `undefined` (defaults to `""`).
+     * @param options.rows Number of rows; more than one enables multiline sanitization (defaults to `1`).
+     * @param options.match Regular expression the sanitized string must match.
+     * @param options.case Force the result to `"upper"` or `"lower"` case.
+     * @param options.input HTML `<input />` `type=""` hint for downstream UIs (defaults to `"text"`).
+     */
     constructor({ one = "string", min = 0, max = Number.POSITIVE_INFINITY, value = "", rows = 1, match, case: _case, input = "text", ...options }) {
         super({ one, value, ...options });
         this.min = min;
@@ -32,6 +44,18 @@ export class StringSchema extends Schema {
         this.case = _case;
         this.input = input;
     }
+    /**
+     * Validate an unknown value and coerce it to a sanitized string.
+     *
+     * @param value Value to validate (defaults to this schema's `value`).
+     * @returns The sanitized string value.
+     * @throws `string` `"Required"` if the value is empty or missing, `` `Must be ${one}` `` if it is not a string or number, `` `Invalid ${one}` `` if it fails `match`, `` `Minimum ${min} characters` `` if too short, or `` `Maximum ${max} characters` `` if too long.
+     *
+     * @example
+     *  STRING.validate(123); // Returns "123"
+     *
+     * @see https://dhoulb.github.io/shelving/schema/StringSchema/StringSchema/validate
+     */
     validate(value = this.value) {
         const str = typeof value === "number" ? value.toString() : value;
         if (typeof str !== "string")
@@ -45,7 +69,20 @@ export class StringSchema extends Schema {
             throw `Maximum ${this.max} characters`;
         return sane;
     }
-    /** Sanitize the string by removing unwanted characters. */
+    /**
+     * Sanitize the string by removing unwanted characters.
+     *
+     * - Uses multiline sanitization when `rows` is greater than one, otherwise single-line sanitization.
+     * - Applies the configured `case` folding (`"upper"` or `"lower"`) if set.
+     *
+     * @param str String to sanitize.
+     * @returns The sanitized (and optionally case-folded) string.
+     *
+     * @example
+     *  STRING.sanitize("  hello  "); // Returns "hello"
+     *
+     * @see https://dhoulb.github.io/shelving/schema/StringSchema/StringSchema/sanitize
+     */
     sanitize(str) {
         const sane = this.rows > 1 ? sanitizeMultilineText(str) : sanitizeText(str);
         if (this.case === "upper")
@@ -54,19 +91,72 @@ export class StringSchema extends Schema {
             return sane.toLowerCase();
         return sane;
     }
+    /**
+     * Format a string value for display (returns the string unchanged).
+     *
+     * @param str String value to format.
+     * @returns The same string value.
+     *
+     * @example
+     *  STRING.format("abc"); // Returns "abc"
+     *
+     * @see https://dhoulb.github.io/shelving/schema/StringSchema/StringSchema/format
+     */
     format(str) {
         return str;
     }
 }
-/** Valid string, e.g. `Hello there!` */
+/**
+ * Valid string, e.g. `Hello there!`
+ *
+ * @example
+ *  STRING.validate(123); // Returns "123"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/StringSchema/STRING
+ */
 export const STRING = new StringSchema({});
-/** Valid string, `Hello there!`, with more than one character. */
+/**
+ * Valid string, `Hello there!`, with more than one character.
+ *
+ * @example
+ *  REQUIRED_STRING.validate(""); // Throws "Required"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/StringSchema/REQUIRED_STRING
+ */
 export const REQUIRED_STRING = new StringSchema({ min: 1 });
-/** Title string, e.g. `Title of something` */
+/**
+ * Title string, e.g. `Title of something` (1–100 characters).
+ *
+ * @example
+ *  TITLE.validate("My Title"); // Returns "My Title"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/StringSchema/TITLE
+ */
 export const TITLE = new StringSchema({ one: "title", title: "Title", min: 1, max: 100 });
-/** Optional name string, e.g. `Title of something` or `null` */
+/**
+ * Optional title string, e.g. `Title of something` or `null`.
+ *
+ * @example
+ *  NULLABLE_TITLE.validate(null); // Returns null
+ *
+ * @see https://dhoulb.github.io/shelving/schema/StringSchema/NULLABLE_TITLE
+ */
 export const NULLABLE_TITLE = NULLABLE(TITLE);
-/** Name string, e.g. `Name of Something` */
+/**
+ * Name string, e.g. `Name of Something` (1–100 characters).
+ *
+ * @example
+ *  NAME.validate("Dave"); // Returns "Dave"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/StringSchema/NAME
+ */
 export const NAME = new StringSchema({ one: "name", title: "Name", min: 1, max: 100 });
-/** Optional name string, e.g. `Name of Something` or `null` */
+/**
+ * Optional name string, e.g. `Name of Something` or `null`.
+ *
+ * @example
+ *  NULLABLE_NAME.validate(null); // Returns null
+ *
+ * @see https://dhoulb.github.io/shelving/schema/StringSchema/NULLABLE_NAME
+ */
 export const NULLABLE_NAME = NULLABLE(NAME);

package/schema/ThroughSchema.d.ts

@@ -1,14 +1,47 @@
 import type { Sourceable } from "../util/source.js";
 import type { SchemaOptions } from "./Schema.js";
 import { Schema } from "./Schema.js";
-/** Allowed options for `ThroughSchema` */
+/**
+ * Allowed options for `ThroughSchema`.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/ThroughSchema/ThroughSchemaOptions
+ */
 export interface ThroughSchemaOptions<T> extends SchemaOptions {
     source: Schema<T>;
 }
-/** Schema that passes through to a source schema. */
+/**
+ * Schema that wraps and passes through to a source schema, used as a base for schemas that augment another schema's behaviour (e.g. `NullableSchema`, `OptionalSchema`, `RequiredSchema`).
+ *
+ * @example
+ *  class WrapSchema<T> extends ThroughSchema<T> {} // Delegates `validate()` to `this.source`.
+ * @see https://dhoulb.github.io/shelving/schema/ThroughSchema/ThroughSchema
+ */
 export declare abstract class ThroughSchema<T> extends Schema<T> implements Sourceable<Schema<T>> {
+    /** The source schema this schema passes through to. */
     readonly source: Schema<T>;
+    /**
+     * Create a new `ThroughSchema`.
+     *
+     * @param options Options for the schema, including the `source` schema to wrap.
+     */
     constructor({ source, ...options }: ThroughSchemaOptions<T>);
+    /**
+     * Validate an unknown input value by passing it through to the source schema.
+     *
+     * @param unsafeValue The unknown input value to validate.
+     * @returns The valid value of type `T`.
+     * @throws `string` error message if the value is invalid.
+     * @example schema.validate(input) // Delegates to source schema.
+     * @see https://dhoulb.github.io/shelving/schema/ThroughSchema/ThroughSchema/validate
+     */
     validate(unsafeValue: unknown): T;
+    /**
+     * Format a valid value by passing it through to the source schema.
+     *
+     * @param value The valid value to format.
+     * @returns The value formatted as a human-readable string.
+     * @example schema.format(value) // Delegates to source schema.
+     * @see https://dhoulb.github.io/shelving/schema/ThroughSchema/ThroughSchema/format
+     */
     format(value: T): string;
 }

package/schema/ThroughSchema.js

@@ -1,14 +1,43 @@
 import { Schema } from "./Schema.js";
-/** Schema that passes through to a source schema. */
+/**
+ * Schema that wraps and passes through to a source schema, used as a base for schemas that augment another schema's behaviour (e.g. `NullableSchema`, `OptionalSchema`, `RequiredSchema`).
+ *
+ * @example
+ *  class WrapSchema<T> extends ThroughSchema<T> {} // Delegates `validate()` to `this.source`.
+ * @see https://dhoulb.github.io/shelving/schema/ThroughSchema/ThroughSchema
+ */
 export class ThroughSchema extends Schema {
+    /** The source schema this schema passes through to. */
     source;
+    /**
+     * Create a new `ThroughSchema`.
+     *
+     * @param options Options for the schema, including the `source` schema to wrap.
+     */
     constructor({ source, ...options }) {
         super(source instanceof Schema ? { ...source, ...options } : options);
         this.source = source;
     }
+    /**
+     * Validate an unknown input value by passing it through to the source schema.
+     *
+     * @param unsafeValue The unknown input value to validate.
+     * @returns The valid value of type `T`.
+     * @throws `string` error message if the value is invalid.
+     * @example schema.validate(input) // Delegates to source schema.
+     * @see https://dhoulb.github.io/shelving/schema/ThroughSchema/ThroughSchema/validate
+     */
     validate(unsafeValue) {
         return this.source.validate(unsafeValue);
     }
+    /**
+     * Format a valid value by passing it through to the source schema.
+     *
+     * @param value The valid value to format.
+     * @returns The value formatted as a human-readable string.
+     * @example schema.format(value) // Delegates to source schema.
+     * @see https://dhoulb.github.io/shelving/schema/ThroughSchema/ThroughSchema/format
+     */
     format(value) {
         return this.source.format(value);
     }

package/schema/TimeSchema.d.ts

@@ -1,11 +1,51 @@
 import { DateSchema, type DateSchemaOptions } from "./DateSchema.js";
-/** Define a valid time in 24h hh:mm:ss.fff format, e.g. `23:59` or `24:00 */
+/**
+ * Schema that defines a valid abstract time in 24h `hh:mm:ss.fff` format, e.g. `23:59` or `24:00`.
+ *
+ * - Validates a time without a timezone, e.g. a daily alarm; use `DateSchema` for dates and `DateTimeSchema` for UTC datetimes.
+ *
+ * @example
+ *  const schema = new TimeSchema({});
+ *  schema.validate("23:59"); // "23:59:00.000"
+ * @see https://dhoulb.github.io/shelving/schema/TimeSchema/TimeSchema
+ */
 export declare class TimeSchema extends DateSchema {
+    /**
+     * Create a new `TimeSchema`.
+     *
+     * @param options Options for the schema (same as `DateSchemaOptions`).
+     */
     constructor({ one, title, input, ...options }: DateSchemaOptions);
+    /**
+     * Convert a `Date` object to a `hh:mm:ss.fff` time string.
+     *
+     * @param value The `Date` to convert.
+     * @returns The time portion as a `hh:mm:ss.fff` string.
+     * @example schema.stringify(new Date("2005-09-12T23:59:00Z")) // "23:59:00.000"
+     * @see https://dhoulb.github.io/shelving/schema/TimeSchema/TimeSchema/stringify
+     */
     stringify(value: Date): string;
+    /**
+     * Format a validated time string as a human-readable string for display.
+     *
+     * @param value The validated time string to format.
+     * @returns The time formatted for display.
+     * @example schema.format("23:59") // "23:59"
+     * @see https://dhoulb.github.io/shelving/schema/TimeSchema/TimeSchema/format
+     */
     format(value: string): string;
 }
-/** Valid time, e.g. `2005-09-12` (required because falsy values are invalid). */
+/**
+ * Valid time, e.g. `23:59` (required because falsy values are invalid).
+ *
+ * @example TIME.validate("23:59") // "23:59:00.000"
+ * @see https://dhoulb.github.io/shelving/schema/TimeSchema/TIME
+ */
 export declare const TIME: TimeSchema;
-/** Valid time, e.g. `2005-09-12`, or `null` */
+/**
+ * Valid time, e.g. `23:59`, or `null`.
+ *
+ * @example NULLABLE_TIME.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/TimeSchema/NULLABLE_TIME
+ */
 export declare const NULLABLE_TIME: import("./NullableSchema.js").NullableSchema<string>;

package/schema/TimeSchema.js

@@ -2,19 +2,59 @@ import { requireTimeString } from "../util/date.js";
 import { formatTime } from "../util/format.js";
 import { DateSchema } from "./DateSchema.js";
 import { NULLABLE } from "./NullableSchema.js";
-/** Define a valid time in 24h hh:mm:ss.fff format, e.g. `23:59` or `24:00 */
+/**
+ * Schema that defines a valid abstract time in 24h `hh:mm:ss.fff` format, e.g. `23:59` or `24:00`.
+ *
+ * - Validates a time without a timezone, e.g. a daily alarm; use `DateSchema` for dates and `DateTimeSchema` for UTC datetimes.
+ *
+ * @example
+ *  const schema = new TimeSchema({});
+ *  schema.validate("23:59"); // "23:59:00.000"
+ * @see https://dhoulb.github.io/shelving/schema/TimeSchema/TimeSchema
+ */
 export class TimeSchema extends DateSchema {
+    /**
+     * Create a new `TimeSchema`.
+     *
+     * @param options Options for the schema (same as `DateSchemaOptions`).
+     */
     constructor({ one = "time", title = "Time", input = "time", ...options }) {
         super({ one, title, input, ...options });
     }
+    /**
+     * Convert a `Date` object to a `hh:mm:ss.fff` time string.
+     *
+     * @param value The `Date` to convert.
+     * @returns The time portion as a `hh:mm:ss.fff` string.
+     * @example schema.stringify(new Date("2005-09-12T23:59:00Z")) // "23:59:00.000"
+     * @see https://dhoulb.github.io/shelving/schema/TimeSchema/TimeSchema/stringify
+     */
     stringify(value) {
         return requireTimeString(value);
     }
+    /**
+     * Format a validated time string as a human-readable string for display.
+     *
+     * @param value The validated time string to format.
+     * @returns The time formatted for display.
+     * @example schema.format("23:59") // "23:59"
+     * @see https://dhoulb.github.io/shelving/schema/TimeSchema/TimeSchema/format
+     */
     format(value) {
         return formatTime(value, undefined, this.format);
     }
 }
-/** Valid time, e.g. `2005-09-12` (required because falsy values are invalid). */
+/**
+ * Valid time, e.g. `23:59` (required because falsy values are invalid).
+ *
+ * @example TIME.validate("23:59") // "23:59:00.000"
+ * @see https://dhoulb.github.io/shelving/schema/TimeSchema/TIME
+ */
 export const TIME = new TimeSchema({});
-/** Valid time, e.g. `2005-09-12`, or `null` */
+/**
+ * Valid time, e.g. `23:59`, or `null`.
+ *
+ * @example NULLABLE_TIME.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/TimeSchema/NULLABLE_TIME
+ */
 export const NULLABLE_TIME = NULLABLE(TIME);

package/schema/URISchema.d.ts

@@ -1,23 +1,84 @@
 import { type URISchemes, type URIString } from "../util/uri.js";
 import type { StringSchemaOptions } from "./StringSchema.js";
 import { StringSchema } from "./StringSchema.js";
-/** Allowed options for `URISchema` */
+/**
+ * Options for `URISchema`.
+ *
+ * - `schemes` — whitelist of allowed URI schemes (defaults to HTTP/HTTPS).
+ *
+ * @see https://dhoulb.github.io/shelving/schema/URISchema/URISchemaOptions
+ */
 export interface URISchemaOptions extends Omit<StringSchemaOptions, "input" | "min" | "max" | "rows"> {
     readonly schemes?: URISchemes | undefined;
 }
 /**
- * Type of `StringSchema` that defines a valid URI string.
- * - Checks URI scheme against a whitelist (always).
- * - URIs are limited to 512 characters, but generally these won't be data: URIs so this is a reasonable limit.
+ * Schema that defines a valid absolute URI string.
+ *
+ * - Checks the URI scheme against a whitelist (always).
+ * - URIs are limited to 512 characters, but generally these won't be `data:` URIs so this is a reasonable limit.
+ *
+ * @example
+ * 	const schema = new URISchema({});
+ * 	schema.validate("https://www.google.com") // "https://www.google.com/"
+ * @see https://dhoulb.github.io/shelving/schema/URISchema/URISchema
  */
 export declare class URISchema extends StringSchema {
+    /** Whitelist of allowed URI schemes, e.g. `["https:", "http:"]`. */
     readonly schemes: URISchemes;
+    /**
+     * Create a new `URISchema`.
+     *
+     * @param options Options for the schema (`schemes`, plus inherited string options like `one`, `title`, `value`).
+     */
     constructor({ one, title, schemes, ...options }: URISchemaOptions);
+    /**
+     * Validate an unknown input value and return a normalised absolute URI string.
+     *
+     * - Override to validate the URI and check the scheme against the whitelist.
+     *
+     * @param unsafeValue The unknown input value to validate.
+     * @returns The valid, normalised URI string.
+     * @throws `string` error message if the value is empty, malformed, or uses a disallowed scheme.
+     * @example schema.validate("https://www.google.com") // "https://www.google.com/"
+     * @see https://dhoulb.github.io/shelving/schema/URISchema/URISchema/validate
+     */
     validate(unsafeValue: unknown): URIString;
+    /**
+     * Sanitize a string before validation by stripping all whitespace.
+     *
+     * - URIs never contain whitespace (a real space must be `%20`-encoded), so strip it entirely.
+     *
+     * @param str The raw string to sanitize.
+     * @returns The sanitized string with all whitespace removed.
+     * @example schema.sanitize(" https://a.com ") // "https://a.com"
+     * @see https://dhoulb.github.io/shelving/schema/URISchema/URISchema/sanitize
+     */
     sanitize(str: string): string;
+    /**
+     * Format a validated URI string for display.
+     *
+     * @param value The valid URI string to format.
+     * @returns The URI formatted as a human-readable string.
+     * @example schema.format("https://www.google.com/") // "www.google.com"
+     * @see https://dhoulb.github.io/shelving/schema/URISchema/URISchema/format
+     */
     format(value: string): string;
 }
-/** Valid URI string, e.g. `https://www.google.com` */
+/**
+ * Valid URI string, e.g. `https://www.google.com`.
+ *
+ * *Factory for `URISchema`.*
+ *
+ * @example URI_SCHEMA.validate("https://www.google.com") // "https://www.google.com/"
+ * @see https://dhoulb.github.io/shelving/schema/URISchema/URI_SCHEMA
+ */
 export declare const URI_SCHEMA: URISchema;
-/** Valid URI string, e.g. `https://www.google.com`, or `null` */
+/**
+ * Valid URI string, e.g. `https://www.google.com`, or `null`.
+ *
+ * *Factory for `NullableSchema`.*
+ *
+ * @example NULLABLE_URI_SCHEMA.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/URISchema/NULLABLE_URI_SCHEMA
+ */
 export declare const NULLABLE_URI_SCHEMA: import("./NullableSchema.js").NullableSchema<string>;

package/schema/URISchema.js

@@ -4,12 +4,24 @@ import { getURI, HTTP_SCHEMES } from "../util/uri.js";
 import { NULLABLE } from "./NullableSchema.js";
 import { StringSchema } from "./StringSchema.js";
 /**
- * Type of `StringSchema` that defines a valid URI string.
- * - Checks URI scheme against a whitelist (always).
- * - URIs are limited to 512 characters, but generally these won't be data: URIs so this is a reasonable limit.
+ * Schema that defines a valid absolute URI string.
+ *
+ * - Checks the URI scheme against a whitelist (always).
+ * - URIs are limited to 512 characters, but generally these won't be `data:` URIs so this is a reasonable limit.
+ *
+ * @example
+ * 	const schema = new URISchema({});
+ * 	schema.validate("https://www.google.com") // "https://www.google.com/"
+ * @see https://dhoulb.github.io/shelving/schema/URISchema/URISchema
  */
 export class URISchema extends StringSchema {
+    /** Whitelist of allowed URI schemes, e.g. `["https:", "http:"]`. */
     schemes;
+    /**
+     * Create a new `URISchema`.
+     *
+     * @param options Options for the schema (`schemes`, plus inherited string options like `one`, `title`, `value`).
+     */
     constructor({ one = "URI", title = "URI", schemes = HTTP_SCHEMES, ...options }) {
         super({
             one,
@@ -22,7 +34,17 @@ export class URISchema extends StringSchema {
         });
         this.schemes = schemes;
     }
-    // Override to validate the URI and check the schemes and hosts against the whitelists.
+    /**
+     * Validate an unknown input value and return a normalised absolute URI string.
+     *
+     * - Override to validate the URI and check the scheme against the whitelist.
+     *
+     * @param unsafeValue The unknown input value to validate.
+     * @returns The valid, normalised URI string.
+     * @throws `string` error message if the value is empty, malformed, or uses a disallowed scheme.
+     * @example schema.validate("https://www.google.com") // "https://www.google.com/"
+     * @see https://dhoulb.github.io/shelving/schema/URISchema/URISchema/validate
+     */
     validate(unsafeValue) {
         const str = super.validate(unsafeValue);
         const uri = getURI(str);
@@ -32,15 +54,47 @@ export class URISchema extends StringSchema {
             throw `Invalid ${this.one} scheme`;
         return uri.href;
     }
+    /**
+     * Sanitize a string before validation by stripping all whitespace.
+     *
+     * - URIs never contain whitespace (a real space must be `%20`-encoded), so strip it entirely.
+     *
+     * @param str The raw string to sanitize.
+     * @returns The sanitized string with all whitespace removed.
+     * @example schema.sanitize(" https://a.com ") // "https://a.com"
+     * @see https://dhoulb.github.io/shelving/schema/URISchema/URISchema/sanitize
+     */
     sanitize(str) {
         // URIs never contain whitespace (a real space must be `%20`-encoded), so strip it entirely.
         return sanitizeWord(str);
     }
+    /**
+     * Format a validated URI string for display.
+     *
+     * @param value The valid URI string to format.
+     * @returns The URI formatted as a human-readable string.
+     * @example schema.format("https://www.google.com/") // "www.google.com"
+     * @see https://dhoulb.github.io/shelving/schema/URISchema/URISchema/format
+     */
     format(value) {
         return formatURI(value, this.format);
     }
 }
-/** Valid URI string, e.g. `https://www.google.com` */
+/**
+ * Valid URI string, e.g. `https://www.google.com`.
+ *
+ * *Factory for `URISchema`.*
+ *
+ * @example URI_SCHEMA.validate("https://www.google.com") // "https://www.google.com/"
+ * @see https://dhoulb.github.io/shelving/schema/URISchema/URI_SCHEMA
+ */
 export const URI_SCHEMA = new URISchema({});
-/** Valid URI string, e.g. `https://www.google.com`, or `null` */
+/**
+ * Valid URI string, e.g. `https://www.google.com`, or `null`.
+ *
+ * *Factory for `NullableSchema`.*
+ *
+ * @example NULLABLE_URI_SCHEMA.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/URISchema/NULLABLE_URI_SCHEMA
+ */
 export const NULLABLE_URI_SCHEMA = NULLABLE(URI_SCHEMA);

package/schema/URLSchema.d.ts

@@ -2,25 +2,88 @@ import { type URISchemes } from "../util/uri.js";
 import { type URLString } from "../util/url.js";
 import type { StringSchemaOptions } from "./StringSchema.js";
 import { StringSchema } from "./StringSchema.js";
-/** Allowed options for `URLSchema` */
+/**
+ * Options for `URLSchema`.
+ *
+ * - `base` — base URL that relative URLs are resolved against.
+ * - `schemes` — whitelist of allowed URL schemes (defaults to HTTP/HTTPS).
+ *
+ * @see https://dhoulb.github.io/shelving/schema/URLSchema/URLSchemaOptions
+ */
 export interface URLSchemaOptions extends Omit<StringSchemaOptions, "input" | "min" | "max" | "rows"> {
     readonly base?: URL | URLString | undefined;
     readonly schemes?: URISchemes | undefined;
 }
 /**
- * Type of `StringSchema` that defines a valid URL string.
- * - Checks URL scheme against a whitelist (always), and checks URL domain against a whitelist (optional).
- * - URLs are limited to 512 characters, but generally these won't be data: URIs so this is a reasonable limit.
+ * Schema that defines a valid absolute or relative URL string.
+ *
+ * - Checks the URL scheme against a whitelist (always), and resolves relative URLs against `base` when set.
+ * - URLs are limited to 512 characters, but generally these won't be `data:` URIs so this is a reasonable limit.
+ *
+ * @example
+ * 	const schema = new URLSchema({ base: "https://example.com" });
+ * 	schema.validate("/page") // "https://example.com/page"
+ * @see https://dhoulb.github.io/shelving/schema/URLSchema/URLSchema
  */
 export declare class URLSchema extends StringSchema {
+    /** Base URL that relative URLs are resolved against, or `undefined` when not set. */
     readonly base: URLString | undefined;
+    /** Whitelist of allowed URL schemes, e.g. `["https:", "http:"]`. */
     readonly schemes: URISchemes;
+    /**
+     * Create a new `URLSchema`.
+     *
+     * @param options Options for the schema (`base`, `schemes`, plus inherited string options like `one`, `title`, `value`).
+     */
     constructor({ one, title, base, schemes, ...options }: URLSchemaOptions);
+    /**
+     * Validate an unknown input value and return a normalised absolute URL string.
+     *
+     * - Override to validate the URL and check the scheme and host against the whitelists.
+     *
+     * @param unsafeValue The unknown input value to validate.
+     * @returns The valid, fully-resolved URL string.
+     * @throws `string` error message if the value is empty, malformed, or uses a disallowed scheme.
+     * @example schema.validate("https://www.google.com") // "https://www.google.com/"
+     * @see https://dhoulb.github.io/shelving/schema/URLSchema/URLSchema/validate
+     */
     validate(unsafeValue: unknown): URLString;
+    /**
+     * Sanitize a string before validation by stripping all whitespace.
+     *
+     * - URLs never contain whitespace (a real space must be `%20`-encoded), so strip it entirely.
+     *
+     * @param str The raw string to sanitize.
+     * @returns The sanitized string with all whitespace removed.
+     * @example schema.sanitize(" https://a.com ") // "https://a.com"
+     * @see https://dhoulb.github.io/shelving/schema/URLSchema/URLSchema/sanitize
+     */
     sanitize(str: string): string;
+    /**
+     * Format a validated URL string for display.
+     *
+     * @param value The valid URL string to format.
+     * @returns The URL formatted as a human-readable string.
+     * @example schema.format("https://www.google.com/") // "www.google.com"
+     * @see https://dhoulb.github.io/shelving/schema/URLSchema/URLSchema/format
+     */
     format(value: string): string;
 }
-/** Valid URL string, e.g. `https://www.google.com` */
+/**
+ * Valid URL string, e.g. `https://www.google.com`.
+ *
+ * *Factory for `URLSchema`.*
+ *
+ * @example URL_SCHEMA.validate("https://www.google.com") // "https://www.google.com/"
+ * @see https://dhoulb.github.io/shelving/schema/URLSchema/URL_SCHEMA
+ */
 export declare const URL_SCHEMA: URLSchema;
-/** Valid URL string, e.g. `https://www.google.com`, or `null` */
+/**
+ * Valid URL string, e.g. `https://www.google.com`, or `null`.
+ *
+ * *Factory for `NullableSchema`.*
+ *
+ * @example NULLABLE_URL_SCHEMA.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/URLSchema/NULLABLE_URL_SCHEMA
+ */
 export declare const NULLABLE_URL_SCHEMA: import("./NullableSchema.js").NullableSchema<string>;