shelving 1.236.0 → 1.236.2

package/schema/EmailSchema.js

@@ -3,7 +3,7 @@ import { NULLABLE } from "./NullableSchema.js";
 import { StringSchema } from "./StringSchema.js";
 const R_MATCH = /^[a-z0-9](?:[a-zA-Z0-9._+-]{0,62}[a-zA-Z0-9])?@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.){1,3}(?:[a-z]{2,63}|xn--[a-z0-9-]{0,58}[a-z0-9])$/;
 /**
- * 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).
@@ -18,8 +18,18 @@ const R_MATCH = /^[a-z0-9](?:[a-zA-Z0-9._+-]{0,62}[a-zA-Z0-9])?@(?:[a-z0-9](?:[a
  *     - 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 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 = "email address", title = "Email", ...options }) {
         super({
             one,
@@ -32,12 +42,33 @@ export class EmailSchema extends StringSchema {
             match: R_MATCH,
         });
     }
+    /**
+     * 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) {
         // Email addresses never contain whitespace, so strip it entirely, then lowercase (RFC says addresses should be case-insensitive).
         return sanitizeWord(str).toLowerCase();
     }
 }
-/** 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 const EMAIL = new 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 const NULLABLE_EMAIL = NULLABLE(EMAIL);

package/schema/EntitySchema.d.ts

@@ -1,17 +1,58 @@
 import { type ImmutableArray } from "../util/array.js";
 import { type Entity } from "../util/entity.js";
 import { StringSchema, type StringSchemaOptions } from "./StringSchema.js";
-/** Allowed options for `EntitySchema` with specific types */
+/**
+ * Options for `EntitySchema`.
+ *
+ * - `types` — restrict the allowed entity types; any other type is rejected.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/EntitySchema/EntitySchemaOptions
+ */
 export interface EntitySchemaOptions<T extends string> extends StringSchemaOptions {
     readonly types?: ImmutableArray<T> | undefined;
 }
-/** Validate a file name matching one or more extensions. */
+/**
+ * Schema that validates an `Entity` string combining a type and ID, e.g. `challenge:a1b2c3`.
+ *
+ * - The input must contain both a type and an ID separated by `:`, otherwise it is rejected.
+ * - When `types` is set, the entity's type must be one of the allowed types.
+ *
+ * @example
+ *  const schema = new EntitySchema({ types: ["challenge"] });
+ *  schema.validate("challenge:a1b2c3"); // "challenge:a1b2c3"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/EntitySchema/EntitySchema
+ */
 export declare class EntitySchema<T extends string> extends StringSchema {
     readonly types: ImmutableArray<T> | undefined;
+    /**
+     * Create a new `EntitySchema`.
+     *
+     * @param options Options for the schema, including an optional `types` allow-list.
+     */
     constructor({ one, title, types, ...options }: EntitySchemaOptions<T>);
+    /**
+     * Validate an unknown value as an `Entity` string with a valid type and ID.
+     *
+     * @param unsafeValue The unknown input value to validate (defaults to this schema's `value`).
+     * @returns The valid `Entity` string.
+     * @throws `string` `"Must be entity"` if the value lacks a type and ID, or `"Invalid entity type"` if its type is not in the allowed `types`. Also throws any `string` from the underlying `StringSchema`.
+     * @example schema.validate("challenge:a1b2c3") // "challenge:a1b2c3"
+     * @see https://dhoulb.github.io/shelving/schema/EntitySchema/EntitySchema/validate
+     */
     validate(unsafeValue?: unknown): Entity<T>;
 }
-/** Valid file, e.g. `challenge:a1b2c3` */
+/**
+ * Valid entity, e.g. `challenge:a1b2c3`
+ *
+ * @example ENTITY.validate("challenge:a1b2c3") // "challenge:a1b2c3"
+ * @see https://dhoulb.github.io/shelving/schema/EntitySchema/ENTITY
+ */
 export declare const ENTITY: EntitySchema<string>;
-/** Valid optional file, e.g. `file.txt`, or `null` */
+/**
+ * Valid optional entity, e.g. `challenge:a1b2c3`, or `null`
+ *
+ * @example NULLABLE_ENTITY.validate("") // null
+ * @see https://dhoulb.github.io/shelving/schema/EntitySchema/NULLABLE_ENTITY
+ */
 export declare const NULLABLE_ENTITY: import("./NullableSchema.js").NullableSchema<string>;

package/schema/EntitySchema.js

@@ -2,13 +2,38 @@ import { isArrayItem } from "../util/array.js";
 import { getEntity } from "../util/entity.js";
 import { NULLABLE } from "./NullableSchema.js";
 import { StringSchema } from "./StringSchema.js";
-/** Validate a file name matching one or more extensions. */
+/**
+ * Schema that validates an `Entity` string combining a type and ID, e.g. `challenge:a1b2c3`.
+ *
+ * - The input must contain both a type and an ID separated by `:`, otherwise it is rejected.
+ * - When `types` is set, the entity's type must be one of the allowed types.
+ *
+ * @example
+ *  const schema = new EntitySchema({ types: ["challenge"] });
+ *  schema.validate("challenge:a1b2c3"); // "challenge:a1b2c3"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/EntitySchema/EntitySchema
+ */
 export class EntitySchema extends StringSchema {
     types;
+    /**
+     * Create a new `EntitySchema`.
+     *
+     * @param options Options for the schema, including an optional `types` allow-list.
+     */
     constructor({ one = "entity", title = "Entity", types, ...options }) {
         super({ one, title, ...options });
         this.types = types;
     }
+    /**
+     * Validate an unknown value as an `Entity` string with a valid type and ID.
+     *
+     * @param unsafeValue The unknown input value to validate (defaults to this schema's `value`).
+     * @returns The valid `Entity` string.
+     * @throws `string` `"Must be entity"` if the value lacks a type and ID, or `"Invalid entity type"` if its type is not in the allowed `types`. Also throws any `string` from the underlying `StringSchema`.
+     * @example schema.validate("challenge:a1b2c3") // "challenge:a1b2c3"
+     * @see https://dhoulb.github.io/shelving/schema/EntitySchema/EntitySchema/validate
+     */
     validate(unsafeValue = this.value) {
         const entity = super.validate(unsafeValue);
         const [type] = getEntity(entity);
@@ -19,7 +44,17 @@ export class EntitySchema extends StringSchema {
         return entity;
     }
 }
-/** Valid file, e.g. `challenge:a1b2c3` */
+/**
+ * Valid entity, e.g. `challenge:a1b2c3`
+ *
+ * @example ENTITY.validate("challenge:a1b2c3") // "challenge:a1b2c3"
+ * @see https://dhoulb.github.io/shelving/schema/EntitySchema/ENTITY
+ */
 export const ENTITY = new EntitySchema({});
-/** Valid optional file, e.g. `file.txt`, or `null` */
+/**
+ * Valid optional entity, e.g. `challenge:a1b2c3`, or `null`
+ *
+ * @example NULLABLE_ENTITY.validate("") // null
+ * @see https://dhoulb.github.io/shelving/schema/EntitySchema/NULLABLE_ENTITY
+ */
 export const NULLABLE_ENTITY = NULLABLE(ENTITY);

package/schema/FileSchema.d.ts

@@ -1,16 +1,57 @@
 import type { FileTypes } from "../util/file.js";
 import { StringSchema, type StringSchemaOptions } from "./StringSchema.js";
-/** Allowed options for `FileSchema` */
+/**
+ * Allowed options for `FileSchema`.
+ *
+ * @see https://dhoulb.github.io/shelving/schema/FileSchema/FileSchemaOptions
+ */
 export interface FileSchemaOptions extends StringSchemaOptions {
+    /** Set of allowed file extensions; when set, the file name's extension must be one of these. */
     readonly types?: FileTypes | undefined;
 }
-/** Validate a file name matching one or more extensions. */
+/**
+ * Schema that validates a file name matching one or more extensions.
+ *
+ * - Requires the file name to have an extension.
+ * - When `types` is set, the extension must be one of the allowed `FileTypes`.
+ *
+ * @example FILE.validate("photo.jpg"); // Returns "photo.jpg"
+ * @see https://dhoulb.github.io/shelving/schema/FileSchema/FileSchema
+ */
 export declare class FileSchema extends StringSchema {
+    /** Set of allowed file extensions; when set, the file name's extension must be one of these. */
     readonly types: FileTypes | undefined;
+    /**
+     * Create a new `FileSchema`.
+     *
+     * @param options Options for the schema (inherits all `StringSchema` options plus `types`).
+     * @param options.one Singular noun describing one value, used in error messages (defaults to `"file"`).
+     * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"File"`).
+     * @param options.types Set of allowed file extensions; when set, the extension must be one of these.
+     */
     constructor({ one, title, types, ...options }: FileSchemaOptions);
+    /**
+     * Validate an unknown value as a file name with a valid extension.
+     *
+     * @param unsafeValue Value to validate (defaults to this schema's `value`).
+     * @returns The validated file name.
+     * @throws `string` `` `Must have extension` `` if the file name has no extension, or `` `Invalid extension` `` if its extension isn't in `types`. Also throws the `string` messages from `StringSchema.validate()`.
+     * @example FILE.validate("photo.jpg"); // Returns "photo.jpg"
+     * @see https://dhoulb.github.io/shelving/schema/FileSchema/FileSchema/validate
+     */
     validate(unsafeValue?: unknown): string;
 }
-/** Valid file, e.g. `file.txt` */
+/**
+ * Valid file, e.g. `file.txt`
+ *
+ * @example FILE.validate("file.txt"); // Returns "file.txt"
+ * @see https://dhoulb.github.io/shelving/schema/FileSchema/FILE
+ */
 export declare const FILE: FileSchema;
-/** Valid optional file, e.g. `file.txt`, or `null` */
+/**
+ * Valid optional file, e.g. `file.txt`, or `null`
+ *
+ * @example NULLABLE_FILE.validate(null); // Returns null
+ * @see https://dhoulb.github.io/shelving/schema/FileSchema/NULLABLE_FILE
+ */
 export declare const NULLABLE_FILE: import("./NullableSchema.js").NullableSchema<string>;

package/schema/FileSchema.js

@@ -2,13 +2,39 @@ import { getFileExtension } from "../util/file.js";
 import { isProp } from "../util/object.js";
 import { NULLABLE } from "./NullableSchema.js";
 import { StringSchema } from "./StringSchema.js";
-/** Validate a file name matching one or more extensions. */
+/**
+ * Schema that validates a file name matching one or more extensions.
+ *
+ * - Requires the file name to have an extension.
+ * - When `types` is set, the extension must be one of the allowed `FileTypes`.
+ *
+ * @example FILE.validate("photo.jpg"); // Returns "photo.jpg"
+ * @see https://dhoulb.github.io/shelving/schema/FileSchema/FileSchema
+ */
 export class FileSchema extends StringSchema {
+    /** Set of allowed file extensions; when set, the file name's extension must be one of these. */
     types;
+    /**
+     * Create a new `FileSchema`.
+     *
+     * @param options Options for the schema (inherits all `StringSchema` options plus `types`).
+     * @param options.one Singular noun describing one value, used in error messages (defaults to `"file"`).
+     * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"File"`).
+     * @param options.types Set of allowed file extensions; when set, the extension must be one of these.
+     */
     constructor({ one = "file", title = "File", types, ...options }) {
         super({ one, title, ...options });
         this.types = types;
     }
+    /**
+     * Validate an unknown value as a file name with a valid extension.
+     *
+     * @param unsafeValue Value to validate (defaults to this schema's `value`).
+     * @returns The validated file name.
+     * @throws `string` `` `Must have extension` `` if the file name has no extension, or `` `Invalid extension` `` if its extension isn't in `types`. Also throws the `string` messages from `StringSchema.validate()`.
+     * @example FILE.validate("photo.jpg"); // Returns "photo.jpg"
+     * @see https://dhoulb.github.io/shelving/schema/FileSchema/FileSchema/validate
+     */
     validate(unsafeValue = this.value) {
         const path = super.validate(unsafeValue);
         const extension = getFileExtension(path);
@@ -19,7 +45,17 @@ export class FileSchema extends StringSchema {
         return path;
     }
 }
-/** Valid file, e.g. `file.txt` */
+/**
+ * Valid file, e.g. `file.txt`
+ *
+ * @example FILE.validate("file.txt"); // Returns "file.txt"
+ * @see https://dhoulb.github.io/shelving/schema/FileSchema/FILE
+ */
 export const FILE = new FileSchema({});
-/** Valid optional file, e.g. `file.txt`, or `null` */
+/**
+ * Valid optional file, e.g. `file.txt`, or `null`
+ *
+ * @example NULLABLE_FILE.validate(null); // Returns null
+ * @see https://dhoulb.github.io/shelving/schema/FileSchema/NULLABLE_FILE
+ */
 export const NULLABLE_FILE = NULLABLE(FILE);

package/schema/KeySchema.d.ts

@@ -1,17 +1,46 @@
 import { StringSchema, type StringSchemaOptions } from "./StringSchema.js";
 /**
- * Define a valid database key.
+ * Schema that validates a database key string, stripping any non-alphanumeric characters.
  *
  * - Characters that are not a-z, A-Z, 0-9 are removed.
  * - Default minimum key length is 1 character.
  * - Default maximum key length is 32 characters.
  * - 32 characters is enough for UUIDs, as the 4 `-` hyphens are removed.
+ *
+ * @example
+ *  const schema = new KeySchema({});
+ *  schema.validate("a1b2-c3d4"); // "a1b2c3d4"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/KeySchema/KeySchema
  */
 export declare class KeySchema extends StringSchema {
+    /**
+     * Create a new `KeySchema`.
+     *
+     * @param options Options for the schema (defaults `min` to `1` and `max` to `32`).
+     */
     constructor({ one, title, min, max, ...options }: StringSchemaOptions);
+    /**
+     * Sanitize the string by removing all characters that are not a-z, A-Z, or 0-9.
+     *
+     * @param str String to sanitize.
+     * @returns The sanitized key with non-alphanumeric characters removed.
+     * @example schema.sanitize("a1b2-c3d4") // "a1b2c3d4"
+     * @see https://dhoulb.github.io/shelving/schema/KeySchema/KeySchema/sanitize
+     */
     sanitize(str: string): string;
 }
-/** Valid database key. */
+/**
+ * Valid database key.
+ *
+ * @example KEY.validate("a1b2c3") // "a1b2c3"
+ * @see https://dhoulb.github.io/shelving/schema/KeySchema/KEY
+ */
 export declare const KEY: KeySchema;
-/** Valid optional database key. */
+/**
+ * Valid optional database key, or `null`.
+ *
+ * @example NULLABLE_KEY.validate("") // null
+ * @see https://dhoulb.github.io/shelving/schema/KeySchema/NULLABLE_KEY
+ */
 export declare const NULLABLE_KEY: import("./NullableSchema.js").NullableSchema<string>;

package/schema/KeySchema.js

@@ -2,22 +2,51 @@ import { NULLABLE } from "./NullableSchema.js";
 import { StringSchema } from "./StringSchema.js";
 const R_NOT_CHAR = /[^a-zA-Z0-9]/g;
 /**
- * Define a valid database key.
+ * Schema that validates a database key string, stripping any non-alphanumeric characters.
  *
  * - Characters that are not a-z, A-Z, 0-9 are removed.
  * - Default minimum key length is 1 character.
  * - Default maximum key length is 32 characters.
  * - 32 characters is enough for UUIDs, as the 4 `-` hyphens are removed.
+ *
+ * @example
+ *  const schema = new KeySchema({});
+ *  schema.validate("a1b2-c3d4"); // "a1b2c3d4"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/KeySchema/KeySchema
  */
 export class KeySchema extends StringSchema {
+    /**
+     * Create a new `KeySchema`.
+     *
+     * @param options Options for the schema (defaults `min` to `1` and `max` to `32`).
+     */
     constructor({ one = "key", title = "Key", min = 1, max = 32, ...options }) {
         super({ one, title, min, max, ...options });
     }
+    /**
+     * Sanitize the string by removing all characters that are not a-z, A-Z, or 0-9.
+     *
+     * @param str String to sanitize.
+     * @returns The sanitized key with non-alphanumeric characters removed.
+     * @example schema.sanitize("a1b2-c3d4") // "a1b2c3d4"
+     * @see https://dhoulb.github.io/shelving/schema/KeySchema/KeySchema/sanitize
+     */
     sanitize(str) {
         return str.replace(R_NOT_CHAR, "");
     }
 }
-/** Valid database key. */
+/**
+ * Valid database key.
+ *
+ * @example KEY.validate("a1b2c3") // "a1b2c3"
+ * @see https://dhoulb.github.io/shelving/schema/KeySchema/KEY
+ */
 export const KEY = new KeySchema({ title: "ID" });
-/** Valid optional database key. */
+/**
+ * Valid optional database key, or `null`.
+ *
+ * @example NULLABLE_KEY.validate("") // null
+ * @see https://dhoulb.github.io/shelving/schema/KeySchema/NULLABLE_KEY
+ */
 export const NULLABLE_KEY = NULLABLE(KEY);

package/schema/NullableSchema.d.ts

@@ -1,16 +1,76 @@
 import type { Schema } from "./Schema.js";
 import { ThroughSchema, type ThroughSchemaOptions } from "./ThroughSchema.js";
-/** Allowed options for `NullableSchema` */
+/**
+ * Allowed options for `NullableSchema`.
+ *
+ * - `value` — default value used when the input is `undefined` (defaults to `null`).
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NullableSchema/NullableSchemaOptions
+ */
 export interface NullableSchemaOptions<T> extends ThroughSchemaOptions<T | null> {
     /** Default value (defaults to `null`). */
     readonly value?: T | null;
 }
-/** Validate a value of a specific type or `null`. */
+/**
+ * Schema that wraps a source schema and additionally allows `null`.
+ *
+ * - Empty-ish inputs (`null`, `undefined`, `""`, `NaN`) validate to `null` instead of being passed to the source schema.
+ * - Any other value is delegated to the source schema for validation.
+ *
+ * @example
+ *  const schema = new NullableSchema({ source: STRING });
+ *  schema.validate(""); // Returns null
+ *  schema.validate("abc"); // Returns "abc"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NullableSchema/NullableSchema
+ */
 export declare class NullableSchema<T> extends ThroughSchema<T | null> {
     readonly value: T | null;
+    /**
+     * Create a new `NullableSchema`.
+     *
+     * @param options Options for the schema, including the `source` schema to wrap.
+     * @param options.value Default value used when the input is `undefined` (defaults to `null`).
+     */
     constructor({ value, ...options }: NullableSchemaOptions<T>);
+    /**
+     * Validate an unknown value, returning `null` for empty-ish input or delegating to the source schema.
+     *
+     * @param unsafeValue Value to validate (defaults to this schema's `value`).
+     * @returns The valid value of type `T`, or `null` for empty-ish input.
+     * @throws `string` error message if the source schema rejects the value.
+     *
+     * @example
+     *  NULLABLE(STRING).validate(""); // Returns null
+     *
+     * @see https://dhoulb.github.io/shelving/schema/NullableSchema/NullableSchema/validate
+     */
     validate(unsafeValue?: unknown): T | null;
+    /**
+     * Format a nullable value as a human-readable string for display.
+     *
+     * @param value Value to format, or `null`.
+     * @returns The formatted string, or `` `No ${one}` `` when the value is `null`.
+     *
+     * @example
+     *  NULLABLE(STRING).format(null); // Returns "No string"
+     *
+     * @see https://dhoulb.github.io/shelving/schema/NullableSchema/NullableSchema/format
+     */
     format(value: T | null): string;
 }
-/** Create a new nullable schema from a source schema. */
-export declare const NULLABLE: <T>(source: Schema<T>) => NullableSchema<T>;
+/**
+ * Create a `NullableSchema` that wraps a source schema and also allows `null`.
+ *
+ * *Factory for `NullableSchema`.*
+ *
+ * @param source Source schema to wrap.
+ * @returns A `NullableSchema` wrapping `source`.
+ *
+ * @example
+ *  const schema = NULLABLE(STRING);
+ *  schema.validate(""); // Returns null
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NullableSchema/NULLABLE
+ */
+export declare function NULLABLE<T>(source: Schema<T>): NullableSchema<T>;

package/schema/NullableSchema.js

@@ -1,17 +1,73 @@
 import { ThroughSchema } from "./ThroughSchema.js";
-/** Validate a value of a specific type or `null`. */
+/**
+ * Schema that wraps a source schema and additionally allows `null`.
+ *
+ * - Empty-ish inputs (`null`, `undefined`, `""`, `NaN`) validate to `null` instead of being passed to the source schema.
+ * - Any other value is delegated to the source schema for validation.
+ *
+ * @example
+ *  const schema = new NullableSchema({ source: STRING });
+ *  schema.validate(""); // Returns null
+ *  schema.validate("abc"); // Returns "abc"
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NullableSchema/NullableSchema
+ */
 export class NullableSchema extends ThroughSchema {
+    /**
+     * Create a new `NullableSchema`.
+     *
+     * @param options Options for the schema, including the `source` schema to wrap.
+     * @param options.value Default value used when the input is `undefined` (defaults to `null`).
+     */
     constructor({ value = null, ...options }) {
         super({ value, ...options });
     }
+    /**
+     * Validate an unknown value, returning `null` for empty-ish input or delegating to the source schema.
+     *
+     * @param unsafeValue Value to validate (defaults to this schema's `value`).
+     * @returns The valid value of type `T`, or `null` for empty-ish input.
+     * @throws `string` error message if the source schema rejects the value.
+     *
+     * @example
+     *  NULLABLE(STRING).validate(""); // Returns null
+     *
+     * @see https://dhoulb.github.io/shelving/schema/NullableSchema/NullableSchema/validate
+     */
     validate(unsafeValue = this.value) {
         if (unsafeValue === null || unsafeValue === undefined || unsafeValue === "" || Number.isNaN(unsafeValue))
             return null;
         return super.validate(unsafeValue);
     }
+    /**
+     * Format a nullable value as a human-readable string for display.
+     *
+     * @param value Value to format, or `null`.
+     * @returns The formatted string, or `` `No ${one}` `` when the value is `null`.
+     *
+     * @example
+     *  NULLABLE(STRING).format(null); // Returns "No string"
+     *
+     * @see https://dhoulb.github.io/shelving/schema/NullableSchema/NullableSchema/format
+     */
     format(value) {
         return value === null ? `No ${this.source.one}` : super.format(value);
     }
 }
-/** Create a new nullable schema from a source schema. */
-export const NULLABLE = (source) => new NullableSchema({ source });
+/**
+ * Create a `NullableSchema` that wraps a source schema and also allows `null`.
+ *
+ * *Factory for `NullableSchema`.*
+ *
+ * @param source Source schema to wrap.
+ * @returns A `NullableSchema` wrapping `source`.
+ *
+ * @example
+ *  const schema = NULLABLE(STRING);
+ *  schema.validate(""); // Returns null
+ *
+ * @see https://dhoulb.github.io/shelving/schema/NullableSchema/NULLABLE
+ */
+export function NULLABLE(source) {
+    return new NullableSchema({ source });
+}