shelving 1.236.0 → 1.236.2

package/util/validate.d.ts

@@ -2,52 +2,111 @@ import type { ImmutableArray, PossibleArray } from "./array.js";
 import type { Data } from "./data.js";
 import type { ImmutableDictionary, PossibleDictionary } from "./dictionary.js";
 import type { AnyCaller } from "./function.js";
-/** Object that can validate an unknown value with its `validate()` method. */
+/**
+ * Object that can validate an unknown value with its `validate()` method.
+ *
+ * @see https://dhoulb.github.io/shelving/util/validate/Validator
+ */
 export interface Validator<T> {
     /**
-     * `validate()` method accepts an unsafe value and returns a valid value.
+     * Validate an unsafe value and return a valid value.
      *
      * @param unsafeValue A potentially invalid value.
-     *
-     * @return Valid value.
-     *
+     * @returns Valid value.
      * @throws `Error` If the value is invalid and cannot be fixed.
      * @throws `string` If the value is invalid and cannot be fixed and we want to explain why to an end user.
+     * @example validator.validate(unsafeValue) // valid value (or throws)
+     * @see https://dhoulb.github.io/shelving/util/validate/Validator/validate
      */
     validate(unsafeValue: unknown): T;
 }
-/** Extract the type from a validator. */
+/**
+ * Extract the validated type from a `Validator`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/validate/ValidatorType
+ */
 export type ValidatorType<X> = X extends Validator<infer Y> ? Y : never;
-/** A set of named validators in `{ name: Validator }` format. */
+/**
+ * A set of named validators in `{ name: Validator }` format.
+ *
+ * @see https://dhoulb.github.io/shelving/util/validate/Validators
+ */
 export type Validators<T extends Data = Data> = {
     readonly [K in keyof T]: Validator<T[K]>;
 };
-/** Extract the type from a set of validators. */
+/**
+ * Extract the validated data type from a set of validators.
+ *
+ * @see https://dhoulb.github.io/shelving/util/validate/ValidatorsType
+ */
 export type ValidatorsType<T> = {
     readonly [K in keyof T]: ValidatorType<T[K]>;
 };
-/** Require a valid value for a given validator, or return `undefined` if the value could not be validated. */
+/**
+ * Validate a value with a given validator, or return `undefined` if the value could not be validated.
+ *
+ * - Non-string thrown errors (i.e. real `Error` instances) are rethrown — only string validation messages are swallowed into `undefined`.
+ *
+ * @param value The unsafe value to validate.
+ * @param validator The validator to validate the value with.
+ * @returns The valid value, or `undefined` if validation threw a string message.
+ * @throws `Error` if the validator throws a non-string error.
+ * @example getValid(unsafeValue, STRING) // valid string, or `undefined`
+ * @see https://dhoulb.github.io/shelving/util/validate/getValid
+ */
 export declare function getValid<T>(value: unknown, validator: Validator<T>): T | undefined;
-/** Require a valid value for a given validator, or throw `RequiredError` if the value could not be validated. */
+/**
+ * Validate a value with a given validator, or throw `RequiredError` if the value could not be validated.
+ *
+ * - String validation messages are wrapped in a `RequiredError`; non-string errors are rethrown as-is.
+ *
+ * @param value The unsafe value to validate.
+ * @param validator The validator to validate the value with.
+ * @param caller Function to attribute the thrown error to (defaults to `requireValid`).
+ * @returns The valid value.
+ * @throws `RequiredError` if validation threw a string message.
+ * @throws `Error` if the validator throws a non-string error.
+ * @example requireValid(unsafeValue, STRING) // valid string (or throws)
+ * @see https://dhoulb.github.io/shelving/util/validate/requireValid
+ */
 export declare function requireValid<T>(value: unknown, validator: Validator<T>, caller?: AnyCaller): T;
 /**
- * Validate an iterable set of items with a validator.
+ * Validate an iterable set of items with a validator, yielding each valid item.
  *
- * @yield Valid items.
- * @throw string if one or more items did not validate.
+ * - Validation messages for failing items are collected (keyed by index) and thrown together once iteration completes.
+ *
+ * @param unsafeItems The iterable of potentially invalid items.
+ * @param validator The validator to validate each item with.
+ * @yields Valid items.
+ * @throws `string` if one or more items did not validate (one `"index: message"` line per failure, joined by newlines).
+ * @example Array.from(validateItems(["a", "b"], STRING)) // ["a", "b"]
+ * @see https://dhoulb.github.io/shelving/util/validate/validateItems
  */
 export declare function validateItems<T>(unsafeItems: PossibleArray<unknown>, validator: Validator<T>): Iterable<T>;
 /**
- * Validate an array of items.
+ * Validate an array of items with a validator.
+ *
+ * - Returns the original array reference unchanged when every item was already valid (and the input was an array).
  *
- * @return Array with valid items.
- * @throw string if one or more entry values did not validate.
+ * @param unsafeArray The array (or iterable) of potentially invalid items.
+ * @param validator The validator to validate each item with.
+ * @returns Array with valid items.
+ * @throws `string` if one or more items did not validate (one `"index: message"` line per failure, joined by newlines).
+ * @example validateArray(["a", "b"], STRING) // ["a", "b"]
+ * @see https://dhoulb.github.io/shelving/util/validate/validateArray
  */
 export declare function validateArray<T>(unsafeArray: PossibleArray<unknown>, validator: Validator<T>): ImmutableArray<T>;
 /**
- * Validate the values of the entries in a dictionary object.
+ * Validate the values of the entries in a dictionary object with a validator.
+ *
+ * - Returns the original dictionary reference unchanged when every value was already valid (and the input was a plain dictionary, not an iterable).
  *
- * @throw string if one or more entry values did not validate.
+ * @param unsafeDictionary The dictionary (or iterable of entries) of potentially invalid values.
+ * @param validator The validator to validate each value with.
+ * @returns Dictionary with valid values.
+ * @throws `string` if one or more entry values did not validate (one `"key: message"` line per failure, joined by newlines).
+ * @example validateDictionary({ a: "1", b: "2" }, STRING) // { a: "1", b: "2" }
+ * @see https://dhoulb.github.io/shelving/util/validate/validateDictionary
  */
 export declare function validateDictionary<T>(unsafeDictionary: PossibleDictionary<unknown>, validator: Validator<T>): ImmutableDictionary<T>;
 /**
@@ -55,8 +114,14 @@ export declare function validateDictionary<T>(unsafeDictionary: PossibleDictiona
  * - Defined props in the object will be validated against the corresponding validator.
  * - `undefined` props in the object will be set to the default value of that prop.
  * - `undefined` props after validation will not be set in the output object.
+ * - Excess keys not present in `validators` are stripped from the output.
+ * - Returns the original `unsafeData` reference unchanged when nothing changed and no excess keys exist.
  *
- * @return Valid object.
- * @throw string if one or more props did not validate.
+ * @param unsafeData The potentially invalid data object.
+ * @param validators The set of named validators to validate each prop with.
+ * @returns Valid object.
+ * @throws `string` if one or more props did not validate (one `"key: message"` line per failure, joined by newlines).
+ * @example validateData({ name: "Alice" }, { name: STRING }) // { name: "Alice" }
+ * @see https://dhoulb.github.io/shelving/util/validate/validateData
  */
 export declare function validateData<T extends Data>(unsafeData: Data, validators: Validators<T>): T;

package/util/validate.js

@@ -4,7 +4,18 @@ import { getDataProps } from "./data.js";
 import { getDictionaryItems } from "./dictionary.js";
 import { getNamedMessage } from "./error.js";
 import { isIterable } from "./iterate.js";
-/** Require a valid value for a given validator, or return `undefined` if the value could not be validated. */
+/**
+ * Validate a value with a given validator, or return `undefined` if the value could not be validated.
+ *
+ * - Non-string thrown errors (i.e. real `Error` instances) are rethrown — only string validation messages are swallowed into `undefined`.
+ *
+ * @param value The unsafe value to validate.
+ * @param validator The validator to validate the value with.
+ * @returns The valid value, or `undefined` if validation threw a string message.
+ * @throws `Error` if the validator throws a non-string error.
+ * @example getValid(unsafeValue, STRING) // valid string, or `undefined`
+ * @see https://dhoulb.github.io/shelving/util/validate/getValid
+ */
 export function getValid(value, validator) {
     try {
         return validator.validate(value);
@@ -15,7 +26,20 @@ export function getValid(value, validator) {
         throw thrown;
     }
 }
-/** Require a valid value for a given validator, or throw `RequiredError` if the value could not be validated. */
+/**
+ * Validate a value with a given validator, or throw `RequiredError` if the value could not be validated.
+ *
+ * - String validation messages are wrapped in a `RequiredError`; non-string errors are rethrown as-is.
+ *
+ * @param value The unsafe value to validate.
+ * @param validator The validator to validate the value with.
+ * @param caller Function to attribute the thrown error to (defaults to `requireValid`).
+ * @returns The valid value.
+ * @throws `RequiredError` if validation threw a string message.
+ * @throws `Error` if the validator throws a non-string error.
+ * @example requireValid(unsafeValue, STRING) // valid string (or throws)
+ * @see https://dhoulb.github.io/shelving/util/validate/requireValid
+ */
 export function requireValid(value, validator, caller = requireValid) {
     try {
         return validator.validate(value);
@@ -27,10 +51,16 @@ export function requireValid(value, validator, caller = requireValid) {
     }
 }
 /**
- * Validate an iterable set of items with a validator.
+ * Validate an iterable set of items with a validator, yielding each valid item.
+ *
+ * - Validation messages for failing items are collected (keyed by index) and thrown together once iteration completes.
  *
- * @yield Valid items.
- * @throw string if one or more items did not validate.
+ * @param unsafeItems The iterable of potentially invalid items.
+ * @param validator The validator to validate each item with.
+ * @yields Valid items.
+ * @throws `string` if one or more items did not validate (one `"index: message"` line per failure, joined by newlines).
+ * @example Array.from(validateItems(["a", "b"], STRING)) // ["a", "b"]
+ * @see https://dhoulb.github.io/shelving/util/validate/validateItems
  */
 export function* validateItems(unsafeItems, validator) {
     let index = 0;
@@ -50,10 +80,16 @@ export function* validateItems(unsafeItems, validator) {
         throw messages.join("\n");
 }
 /**
- * Validate an array of items.
+ * Validate an array of items with a validator.
  *
- * @return Array with valid items.
- * @throw string if one or more entry values did not validate.
+ * - Returns the original array reference unchanged when every item was already valid (and the input was an array).
+ *
+ * @param unsafeArray The array (or iterable) of potentially invalid items.
+ * @param validator The validator to validate each item with.
+ * @returns Array with valid items.
+ * @throws `string` if one or more items did not validate (one `"index: message"` line per failure, joined by newlines).
+ * @example validateArray(["a", "b"], STRING) // ["a", "b"]
+ * @see https://dhoulb.github.io/shelving/util/validate/validateArray
  */
 export function validateArray(unsafeArray, validator) {
     let index = 0;
@@ -79,9 +115,16 @@ export function validateArray(unsafeArray, validator) {
     return changed || !isArray(unsafeArray) ? safeArray : unsafeArray;
 }
 /**
- * Validate the values of the entries in a dictionary object.
+ * Validate the values of the entries in a dictionary object with a validator.
+ *
+ * - Returns the original dictionary reference unchanged when every value was already valid (and the input was a plain dictionary, not an iterable).
  *
- * @throw string if one or more entry values did not validate.
+ * @param unsafeDictionary The dictionary (or iterable of entries) of potentially invalid values.
+ * @param validator The validator to validate each value with.
+ * @returns Dictionary with valid values.
+ * @throws `string` if one or more entry values did not validate (one `"key: message"` line per failure, joined by newlines).
+ * @example validateDictionary({ a: "1", b: "2" }, STRING) // { a: "1", b: "2" }
+ * @see https://dhoulb.github.io/shelving/util/validate/validateDictionary
  */
 export function validateDictionary(unsafeDictionary, validator) {
     let changed = false;
@@ -109,9 +152,15 @@ export function validateDictionary(unsafeDictionary, validator) {
  * - Defined props in the object will be validated against the corresponding validator.
  * - `undefined` props in the object will be set to the default value of that prop.
  * - `undefined` props after validation will not be set in the output object.
+ * - Excess keys not present in `validators` are stripped from the output.
+ * - Returns the original `unsafeData` reference unchanged when nothing changed and no excess keys exist.
  *
- * @return Valid object.
- * @throw string if one or more props did not validate.
+ * @param unsafeData The potentially invalid data object.
+ * @param validators The set of named validators to validate each prop with.
+ * @returns Valid object.
+ * @throws `string` if one or more props did not validate (one `"key: message"` line per failure, joined by newlines).
+ * @example validateData({ name: "Alice" }, { name: STRING }) // { name: "Alice" }
+ * @see https://dhoulb.github.io/shelving/util/validate/validateData
  */
 export function validateData(unsafeData, validators) {
     let changes = 0;

package/util/xml.d.ts

@@ -3,11 +3,12 @@ import type { AnyCaller } from "./function.js";
 /**
  * Escape a string for safe inclusion in XML text content or attribute values.
  *
+ * - Replaces `&`, `<`, `>`, `"`, and `'` with their XML entity equivalents.
+ *
  * @param value The raw string value.
  * @returns The escaped XML-safe string.
- *
- * @example
- * escapeXML(`Tom & "Jerry"`)
+ * @example escapeXML(`Tom & "Jerry"`) // "Tom &amp; &quot;Jerry&quot;"
+ * @see https://dhoulb.github.io/shelving/util/xml/escapeXML
  */
 export declare function escapeXML(value: string): string;
 /**
@@ -18,13 +19,11 @@ export declare function escapeXML(value: string): string;
  * - Nested data objects become nested XML elements.
  *
  * @param data The data object to serialize.
- * @param caller The calling function for error context.
+ * @param caller Function to attribute thrown errors to (defaults to `getXML`).
  * @returns The serialized XML string.
- *
- * @throws {RequiredError} If a key is not a valid XML element name.
- * @throws {RequiredError} If a value cannot be converted to XML.
- *
- * @example
- * getXML({ user: { name: "Alice", age: 30 } })
+ * @throws `RequiredError` if a key is not a valid XML element name.
+ * @throws `RequiredError` if a value cannot be converted to XML.
+ * @example getXML({ user: { name: "Alice", age: 30 } }) // "<user><name>Alice</name><age>30</age></user>"
+ * @see https://dhoulb.github.io/shelving/util/xml/getXML
  */
 export declare function getXML(data: Data, caller?: AnyCaller): string;

package/util/xml.js

@@ -5,11 +5,12 @@ import { isDefined } from "./undefined.js";
 /**
  * Escape a string for safe inclusion in XML text content or attribute values.
  *
+ * - Replaces `&`, `<`, `>`, `"`, and `'` with their XML entity equivalents.
+ *
  * @param value The raw string value.
  * @returns The escaped XML-safe string.
- *
- * @example
- * escapeXML(`Tom & "Jerry"`)
+ * @example escapeXML(`Tom & "Jerry"`) // "Tom &amp; &quot;Jerry&quot;"
+ * @see https://dhoulb.github.io/shelving/util/xml/escapeXML
  */
 export function escapeXML(value) {
     return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
@@ -22,14 +23,12 @@ export function escapeXML(value) {
  * - Nested data objects become nested XML elements.
  *
  * @param data The data object to serialize.
- * @param caller The calling function for error context.
+ * @param caller Function to attribute thrown errors to (defaults to `getXML`).
  * @returns The serialized XML string.
- *
- * @throws {RequiredError} If a key is not a valid XML element name.
- * @throws {RequiredError} If a value cannot be converted to XML.
- *
- * @example
- * getXML({ user: { name: "Alice", age: 30 } })
+ * @throws `RequiredError` if a key is not a valid XML element name.
+ * @throws `RequiredError` if a value cannot be converted to XML.
+ * @example getXML({ user: { name: "Alice", age: 30 } }) // "<user><name>Alice</name><age>30</age></user>"
+ * @see https://dhoulb.github.io/shelving/util/xml/getXML
  */
 export function getXML(data, caller = getXML) {
     return Array.from(_yieldXML(data, caller)).join("");