shelving 1.248.0 → 1.249.1

package/api/provider/ClientAPIProvider.d.ts

@@ -68,7 +68,6 @@ export declare class ClientAPIProvider<P = unknown, R = unknown> extends APIProv
     /**
      * Create a `ClientAPIProvider` from a base URL and request options.
      *
-     * @param options The `ClientAPIProviderOptions` configuring the base `url`, default request `options`, and `timeout`.
      * @throws {RequiredError} if `url` cannot be resolved to a valid base URL.
      * @example new ClientAPIProvider({ url: "https://api.example.com" })
      * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider

package/api/provider/ClientAPIProvider.js

@@ -42,7 +42,6 @@ export class ClientAPIProvider extends APIProvider {
     /**
      * Create a `ClientAPIProvider` from a base URL and request options.
      *
-     * @param options The `ClientAPIProviderOptions` configuring the base `url`, default request `options`, and `timeout`.
      * @throws {RequiredError} if `url` cannot be resolved to a valid base URL.
      * @example new ClientAPIProvider({ url: "https://api.example.com" })
      * @see https://dhoulb.github.io/shelving/api/provider/ClientAPIProvider/ClientAPIProvider

package/db/collection/Collection.d.ts

@@ -66,7 +66,6 @@ export declare class Collection<N extends string = string, I extends Identifier
  * @param name Collection name used as the table/collection key.
  * @param id Schema for the identifier type.
  * @param data Data schema, or the `Schemas` props used to construct one.
- * @returns A new `Collection` instance.
  * @example COLLECTION("users", ID, { name: STRING, age: NUMBER }) // Collection<"users", number, { name: string; age: number }>
  * @see https://dhoulb.github.io/shelving/db/collection/Collection/COLLECTION
  */

package/db/collection/Collection.js

@@ -77,7 +77,6 @@ export class Collection extends DataSchema {
  * @param name Collection name used as the table/collection key.
  * @param id Schema for the identifier type.
  * @param data Data schema, or the `Schemas` props used to construct one.
- * @returns A new `Collection` instance.
  * @example COLLECTION("users", ID, { name: STRING, age: NUMBER }) // Collection<"users", number, { name: string; age: number }>
  * @see https://dhoulb.github.io/shelving/db/collection/Collection/COLLECTION
  */

package/error/Errors.d.ts

@@ -15,7 +15,6 @@ export declare class Errors extends AggregateError implements BaseError {
      *
      * @param errors Iterable of the individual errors being aggregated.
      * @param message Optional human-readable message describing the aggregate failure.
-     * @param options Optional `BaseErrorOptions` — `caller` and contextual fields are applied via `setBaseErrorOptions()`.
      */
     constructor(errors: Iterable<unknown>, message?: string, options?: BaseErrorOptions);
 }

package/error/Errors.js

@@ -13,7 +13,6 @@ export class Errors extends AggregateError {
      *
      * @param errors Iterable of the individual errors being aggregated.
      * @param message Optional human-readable message describing the aggregate failure.
-     * @param options Optional `BaseErrorOptions` — `caller` and contextual fields are applied via `setBaseErrorOptions()`.
      */
     constructor(errors, message, options = {}) {
         super(errors, message, options);

package/error/NetworkError.d.ts

@@ -13,7 +13,6 @@ export declare class NetworkError extends Error implements BaseError {
      * Create a new `NetworkError`.
      *
      * @param message Optional human-readable description of the network problem.
-     * @param options Optional `BaseErrorOptions` — `caller` and contextual fields are applied via `setBaseErrorOptions()`.
      */
     constructor(message?: string, options?: BaseErrorOptions);
 }

package/error/NetworkError.js

@@ -11,7 +11,6 @@ export class NetworkError extends Error {
      * Create a new `NetworkError`.
      *
      * @param message Optional human-readable description of the network problem.
-     * @param options Optional `BaseErrorOptions` — `caller` and contextual fields are applied via `setBaseErrorOptions()`.
      */
     constructor(message, options = {}) {
         super(message, options);

package/error/RequiredError.d.ts

@@ -14,7 +14,6 @@ export declare class RequiredError extends Error implements BaseError {
      * Create a new `RequiredError`.
      *
      * @param message Optional human-readable description of what was required but missing.
-     * @param options Optional `BaseErrorOptions` — `caller` and contextual fields are applied via `setBaseErrorOptions()`.
      */
     constructor(message?: string, options?: BaseErrorOptions);
 }

package/error/RequiredError.js

@@ -12,7 +12,6 @@ export class RequiredError extends Error {
      * Create a new `RequiredError`.
      *
      * @param message Optional human-readable description of what was required but missing.
-     * @param options Optional `BaseErrorOptions` — `caller` and contextual fields are applied via `setBaseErrorOptions()`.
      */
     constructor(message, options = {}) {
         super(message, options);

package/error/UnexpectedError.d.ts

@@ -14,7 +14,6 @@ export declare class UnexpectedError extends Error implements BaseError {
      * Create a new `UnexpectedError`.
      *
      * @param message Optional human-readable description of the unexpected condition.
-     * @param options Optional `BaseErrorOptions` — `caller` and contextual fields are applied via `setBaseErrorOptions()`.
      */
     constructor(message?: string, options?: BaseErrorOptions);
 }

package/error/UnexpectedError.js

@@ -12,7 +12,6 @@ export class UnexpectedError extends Error {
      * Create a new `UnexpectedError`.
      *
      * @param message Optional human-readable description of the unexpected condition.
-     * @param options Optional `BaseErrorOptions` — `caller` and contextual fields are applied via `setBaseErrorOptions()`.
      */
     constructor(message, options = {}) {
         super(message, options);

package/error/UnimplementedError.d.ts

@@ -13,7 +13,6 @@ export declare class UnimplementedError extends Error implements BaseError {
      * Create a new `UnimplementedError`.
      *
      * @param message Optional human-readable description of the missing implementation.
-     * @param options Optional `BaseErrorOptions` — `caller` and contextual fields are applied via `setBaseErrorOptions()`.
      */
     constructor(message?: string, options?: BaseErrorOptions);
 }

package/error/UnimplementedError.js

@@ -11,7 +11,6 @@ export class UnimplementedError extends Error {
      * Create a new `UnimplementedError`.
      *
      * @param message Optional human-readable description of the missing implementation.
-     * @param options Optional `BaseErrorOptions` — `caller` and contextual fields are applied via `setBaseErrorOptions()`.
      */
     constructor(message, options = {}) {
         super(message, options);

package/error/ValueError.d.ts

@@ -14,7 +14,6 @@ export declare class ValueError extends Error implements BaseError {
      * Create a new `ValueError`.
      *
      * @param message Optional human-readable description of why the value is wrong.
-     * @param options Optional `BaseErrorOptions` — `caller` and contextual fields are applied via `setBaseErrorOptions()`.
      */
     constructor(message?: string, options?: BaseErrorOptions);
 }

package/error/ValueError.js

@@ -12,7 +12,6 @@ export class ValueError extends Error {
      * Create a new `ValueError`.
      *
      * @param message Optional human-readable description of why the value is wrong.
-     * @param options Optional `BaseErrorOptions` — `caller` and contextual fields are applied via `setBaseErrorOptions()`.
      */
     constructor(message, options = {}) {
         super(message, options);

package/extract/DirectoryExtractor.d.ts

@@ -43,8 +43,6 @@ export declare class DirectoryExtractor extends Extractor<Path, TreeElement> {
     /**
      * Create a directory extractor with optional extractor dispatch, base path, and ignore patterns.
      *
-     * @param options Options including the `extractors` dispatch table, `base` path, and `ignore` patterns.
-     *
      * @example const extractor = new DirectoryExtractor({ base: "/repo/modules" });
      */
     constructor({ extractors, base, ignore }?: DirectoryExtractorOptions);

package/extract/DirectoryExtractor.js

@@ -38,8 +38,6 @@ export class DirectoryExtractor extends Extractor {
     /**
      * Create a directory extractor with optional extractor dispatch, base path, and ignore patterns.
      *
-     * @param options Options including the `extractors` dispatch table, `base` path, and `ignore` patterns.
-     *
      * @example const extractor = new DirectoryExtractor({ base: "/repo/modules" });
      */
     constructor({ extractors = DEFAULT_EXTRACTORS, base, ignore = DEFAULT_IGNORE } = {}) {

package/extract/IndexExtractor.d.ts

@@ -31,7 +31,6 @@ export declare class IndexExtractor<I> extends ThroughExtractor<I, TreeElement>
      * Wrap a source extractor so each element's index child is absorbed into the element itself.
      *
      * @param source Upstream extractor that produces the `tree-element` tree to process.
-     * @param options Options including the `index` filename patterns.
      *
      * @example const extractor = new IndexExtractor(new DirectoryExtractor());
      */

package/extract/IndexExtractor.js

@@ -25,7 +25,6 @@ export class IndexExtractor extends ThroughExtractor {
      * Wrap a source extractor so each element's index child is absorbed into the element itself.
      *
      * @param source Upstream extractor that produces the `tree-element` tree to process.
-     * @param options Options including the `index` filename patterns.
      *
      * @example const extractor = new IndexExtractor(new DirectoryExtractor());
      */

package/extract/MergingExtractor.d.ts

@@ -36,7 +36,6 @@ export declare class MergingExtractor<I> extends ThroughExtractor<I, TreeElement
      * Wrap a source extractor so its produced tree has same-template sibling elements merged.
      *
      * @param source Upstream extractor that produces the `tree-element` tree to merge.
-     * @param options Options including the `merges` template map.
      *
      * @example const extractor = new MergingExtractor(new DirectoryExtractor());
      */

package/extract/MergingExtractor.js

@@ -31,7 +31,6 @@ export class MergingExtractor extends ThroughExtractor {
      * Wrap a source extractor so its produced tree has same-template sibling elements merged.
      *
      * @param source Upstream extractor that produces the `tree-element` tree to merge.
-     * @param options Options including the `merges` template map.
      *
      * @example const extractor = new MergingExtractor(new DirectoryExtractor());
      */

package/extract/PackageExtractor.d.ts

@@ -48,8 +48,6 @@ export declare class PackageExtractor extends Extractor<Path, TreeElement> {
     /**
      * Create a package extractor bound to a pre-extracted source tree.
      *
-     * @param options Options including the source `tree`, `extensions` mapping, `module` extractor, and `base` path.
-     *
      * @example const extractor = new PackageExtractor({ tree: sourceTree });
      */
     constructor({ tree, extensions, module, base }: PackageExtractorOptions);

package/extract/PackageExtractor.js

@@ -32,8 +32,6 @@ export class PackageExtractor extends Extractor {
     /**
      * Create a package extractor bound to a pre-extracted source tree.
      *
-     * @param options Options including the source `tree`, `extensions` mapping, `module` extractor, and `base` path.
-     *
      * @example const extractor = new PackageExtractor({ tree: sourceTree });
      */
     constructor({ tree, extensions = DEFAULT_EXTENSIONS, module = new ModuleExtractor(), base }) {

package/extract/TypescriptExtractor.d.ts

@@ -4,7 +4,8 @@ import { FileExtractor } from "./FileExtractor.js";
  * File extractor that parses a TypeScript source file into a tree element.
  * - Uses the TypeScript compiler API to parse the AST.
  * - Extracts exported, public, non-`_`-prefixed declarations as `tree-documentation` children.
- * - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`.
+ * - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`. When a function (or constructor) is overloaded, the implementation declaration (the "base definition") is dropped entirely — only the overload signatures are documented.
+ * - A `@param name {Type}` (or `@returns {Type}`) whose `{Type}` is given is canonical: it supersedes the inferred type from the base definition and any overloads. Multiple `@param name` tags for one parameter each emit a row, letting a single parameter be documented as several typed variants.
  * - Class declarations synthesise their `signatures`, `params`, and `returns` from the constructor — `new ClassName<…>(…)` including generics, one signature per constructor overload, with `returns` set to the class type. Param descriptions come from the constructor's `@param` first, then the class's `@param`.
  * - A `@kind` tag in a symbol's JSDoc overrides the inferred kind — e.g. `@kind component` relabels a React component (otherwise a `function`) so the docs site groups and colours it as a component. The override also drops the trailing `()` from the title, since a non-function kind reads as a bare name.
  * - Sets `description` (a plain-text summary from the first JSDoc paragraph) on every `tree-documentation` child.

package/extract/TypescriptExtractor.js

@@ -5,7 +5,8 @@ import { extractMarkdownProps } from "./MarkupExtractor.js";
  * File extractor that parses a TypeScript source file into a tree element.
  * - Uses the TypeScript compiler API to parse the AST.
  * - Extracts exported, public, non-`_`-prefixed declarations as `tree-documentation` children.
- * - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`.
+ * - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`. When a function (or constructor) is overloaded, the implementation declaration (the "base definition") is dropped entirely — only the overload signatures are documented.
+ * - A `@param name {Type}` (or `@returns {Type}`) whose `{Type}` is given is canonical: it supersedes the inferred type from the base definition and any overloads. Multiple `@param name` tags for one parameter each emit a row, letting a single parameter be documented as several typed variants.
  * - Class declarations synthesise their `signatures`, `params`, and `returns` from the constructor — `new ClassName<…>(…)` including generics, one signature per constructor overload, with `returns` set to the class type. Param descriptions come from the constructor's `@param` first, then the class's `@param`.
  * - A `@kind` tag in a symbol's JSDoc overrides the inferred kind — e.g. `@kind component` relabels a React component (otherwise a `function`) so the docs site groups and colours it as a component. The override also drops the trailing `()` from the title, since a non-function kind reads as a bare name.
  * - Sets `description` (a plain-text summary from the first JSDoc paragraph) on every `tree-documentation` child.
@@ -35,9 +36,18 @@ export class TypescriptExtractor extends FileExtractor {
      */
     extractProps(name, text) {
         const source = ts.createSourceFile(name, text, ts.ScriptTarget.Latest, true);
+        // Names with one or more overload signatures (bodyless function declarations). When a function is overloaded, the
+        // implementation declaration (the one with a body — the "base definition") is dropped entirely; only the overloads are documented.
+        const overloaded = new Set();
+        for (const statement of source.statements)
+            if (ts.isFunctionDeclaration(statement) && !statement.body && statement.name)
+                overloaded.add(statement.name.text);
         // Collect elements by key, merging overloads (same name) by appending signatures.
         const byKey = new Map();
         for (const statement of source.statements) {
+            // Skip the implementation of an overloaded function — overloads supersede the base definition.
+            if (ts.isFunctionDeclaration(statement) && statement.body && statement.name && overloaded.has(statement.name.text))
+                continue;
             const element = _extractStatement(statement, source);
             if (!element)
                 continue;
@@ -304,9 +314,11 @@ function _getTypeParamNames(statement, source) {
         return "";
     return `<${typeParameters.map(t => t.name.getText(source)).join(", ")}>`;
 }
-/** Get a class's constructor declarations (overload signatures + implementation), in source order. */
+/** Get a class's constructor declarations in source order — when overloaded, only the overload signatures (the implementation, i.e. the base definition, is dropped). */
 function _getConstructors(statement) {
-    return statement.members.filter(ts.isConstructorDeclaration);
+    const constructors = statement.members.filter(ts.isConstructorDeclaration);
+    // When overload signatures exist, drop the implementation constructor (the one with a body) — overloads supersede the base definition.
+    return constructors.some(c => !c.body) ? constructors.filter(c => !c.body) : constructors;
 }
 /**
  * Synthesise `new ClassName<…>(…)` signatures from a class's constructor declaration(s).
@@ -327,15 +339,37 @@ function _getParams(statement, source, jsDocParams) {
         return _getConstructorParams(statement, source, jsDocParams);
     if (!ts.isFunctionDeclaration(statement))
         return;
-    const params = statement.parameters.map(p => {
+    const params = _buildParams(statement.parameters, source, jsDocParams);
+    return params.length ? params : undefined;
+}
+/**
+ * Build documentation params from a declaration's AST parameters, applying JSDoc `@param` overrides.
+ * - A `@param name {Type}` whose `{Type}` is given is canonical: it supersedes the parameter's inferred type from the base definition and any overloads.
+ * - Multiple `@param name` tags for the same parameter each emit a row, so a single parameter can be documented as several typed variants.
+ * - A `@param name` with no `{Type}` only supplies the description; the inferred type stands.
+ * - `primaryJsDocParams` win over `fallbackJsDocParams` per name (used by constructors: the constructor's own `@param` beats the class-level `@param`).
+ */
+function _buildParams(parameters, source, primaryJsDocParams, fallbackJsDocParams) {
+    const params = [];
+    for (const p of parameters) {
         const name = p.name.getText(source);
         const type = p.type?.getText(source);
         const optional = !!p.questionToken || !!p.initializer;
-        const description = jsDocParams?.find(d => d.name === name)?.description;
         const def = p.initializer?.getText(source);
-        return { name, type, description, optional, default: def };
-    });
-    return params.length ? params : undefined;
+        // JSDoc `@param` entries for this name — the declaration's own take priority over the fallback (class-level) ones.
+        const primary = primaryJsDocParams?.filter(d => d.name === name) ?? [];
+        const matched = primary.length ? primary : (fallbackJsDocParams?.filter(d => d.name === name) ?? []);
+        // A `@param` carrying a `{Type}` is canonical — emit one row per typed entry, its type overriding the inferred type.
+        const typed = matched.filter(d => d.type);
+        if (typed.length) {
+            for (const d of typed)
+                params.push({ name, type: d.type, description: d.description, optional, default: def });
+        }
+        else {
+            params.push({ name, type, description: matched[0]?.description, optional, default: def });
+        }
+    }
+    return params;
 }
 /**
  * Extract a class's constructor parameters as `params`, mirroring the function shape.
@@ -346,15 +380,8 @@ function _getConstructorParams(statement, source, classJsDocParams) {
     let params;
     for (const ctor of _getConstructors(statement)) {
         const ctorJsDocParams = _getJSDoc(ctor, source)?.params;
-        const next = ctor.parameters.map(p => {
-            const name = p.name.getText(source);
-            const type = p.type?.getText(source);
-            const optional = !!p.questionToken || !!p.initializer;
-            // Constructor-level `@param` wins over the class-level `@param` on collision.
-            const description = ctorJsDocParams?.find(d => d.name === name)?.description ?? classJsDocParams?.find(d => d.name === name)?.description;
-            const def = p.initializer?.getText(source);
-            return { name, type, description, optional, default: def };
-        });
+        // Constructor-level `@param` wins over the class-level `@param` on collision; a `@param {Type}` is canonical (see `_buildParams`).
+        const next = _buildParams(ctor.parameters, source, ctorJsDocParams, classJsDocParams);
         params = _concatUnique(params, next, p => `${p.name}\0${p.type}\0${p.description}\0${p.optional}\0${p.default}`);
     }
     return params?.length ? params : undefined;

package/markup/MarkupParser.d.ts

@@ -97,8 +97,6 @@ export declare class MarkupParser implements Parser<string, ReactNode> {
     /**
      * Create a new `MarkupParser` from a set of options.
      *
-     * @param options Options configuring the rules, link resolution, and default context (all optional).
-     * @returns A `MarkupParser` instance.
      * @example new MarkupParser({ rel: "nofollow ugc" })
      * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser
      */

package/markup/MarkupParser.js

@@ -55,8 +55,6 @@ export class MarkupParser {
     /**
      * Create a new `MarkupParser` from a set of options.
      *
-     * @param options Options configuring the rules, link resolution, and default context (all optional).
-     * @returns A `MarkupParser` instance.
      * @example new MarkupParser({ rel: "nofollow ugc" })
      * @see https://dhoulb.github.io/shelving/markup/MarkupParser/MarkupParser
      */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.248.0",
+	"version": "1.249.1",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/schema/AddressSchema.d.ts

@@ -1,13 +1,18 @@
 import { type AddressData, formatAddress } from "../util/geo.js";
-import { DataSchema, type DataSchemaOptions } from "./DataSchema.js";
+import { DataSchema } from "./DataSchema.js";
+import type { SchemaOptions } from "./Schema.js";
 export type { AddressData };
 export { formatAddress };
 /**
  * Allowed options for `AddressSchema`.
  *
+ * - The `props` are fixed to the postal-address fields internally, so only the default `value` and base schema options are exposed.
+ *
  * @see https://dhoulb.github.io/shelving/schema/AddressSchema/AddressSchemaOptions
  */
-export interface AddressSchemaOptions extends Omit<DataSchemaOptions<AddressData>, "props"> {
+export interface AddressSchemaOptions extends SchemaOptions {
+    /** Partial default value merged over the per-field defaults. */
+    readonly value?: Partial<AddressData> | undefined;
 }
 /**
  * Schema that validates a postal address.
@@ -21,10 +26,6 @@ export interface AddressSchemaOptions extends Omit<DataSchemaOptions<AddressData
 export declare class AddressSchema extends DataSchema<AddressData> {
     /**
      * Create a new `AddressSchema`.
-     *
-     * @param options Options for the schema (inherits `DataSchema` options except `props`, which is fixed to the postal-address fields).
-     * @param options.one Singular noun describing one value, used in error messages (defaults to `"address"`).
-     * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Address"`).
      */
     constructor({ one, title, ...options }?: AddressSchemaOptions);
     /**

package/schema/AddressSchema.js

@@ -24,10 +24,6 @@ const ADDRESS_PROPS = {
 export class AddressSchema extends DataSchema {
     /**
      * Create a new `AddressSchema`.
-     *
-     * @param options Options for the schema (inherits `DataSchema` options except `props`, which is fixed to the postal-address fields).
-     * @param options.one Singular noun describing one value, used in error messages (defaults to `"address"`).
-     * @param options.title Title of the schema, e.g. for a corresponding field (defaults to `"Address"`).
      */
     constructor({ one = "address", title = "Address", ...options } = {}) {
         super({ one, title, props: ADDRESS_PROPS, ...options });

package/schema/ArraySchema.d.ts

@@ -4,25 +4,35 @@ import { Schema } from "./Schema.js";
 /**
  * Options for `ArraySchema`.
  *
- * - `items` — schema every item in the array must conform to.
- * - `min`/`max` — minimum and maximum number of items.
- * - `unique` — deduplicate the items when set.
- * - `separator` — string or `RegExp` used to split a string input into items.
- *
  * @see https://dhoulb.github.io/shelving/schema/ArraySchema/ArraySchemaOptions
  */
 export interface ArraySchemaOptions<T> extends SchemaOptions {
-    /** The default value */
+    /**
+     * Default value used when the input is `undefined`.
+     * @default []
+     */
     readonly value?: ImmutableArray;
-    /** A schema all the array items in the value must conform to */
+    /** Schema every item in the array must conform to. */
     readonly items: Schema<T>;
-    /** Minimum number of items. */
+    /**
+     * Minimum number of items.
+     * @default 0
+     */
     readonly min?: number;
-    /** Maximum number of items. */
+    /**
+     * Maximum number of items.
+     * @default Number.POSITIVE_INFINITY
+     */
     readonly max?: number;
-    /** Whether to deduplicate the items. */
+    /**
+     * Whether to deduplicate the items.
+     * @default false
+     */
     readonly unique?: boolean;
-    /** Separator is used */
+    /**
+     * String or `RegExp` used to split a string input into items.
+     * @default ","
+     */
     readonly separator?: string | RegExp;
 }
 /**
@@ -56,8 +66,6 @@ export declare class ArraySchema<T> extends Schema<ImmutableArray<T>> {
     readonly separator: string | RegExp;
     /**
      * Create a new `ArraySchema`.
-     *
-     * @param options Options for the schema, including the `items` schema, `min`/`max` counts, `unique`, and `separator`.
      */
     constructor({ items, one, many, title, placeholder, unique, min, max, separator, value, ...options }: ArraySchemaOptions<T>);
     /**
@@ -86,7 +94,6 @@ export declare class ArraySchema<T> extends Schema<ImmutableArray<T>> {
  * Sugar factory for [`ArraySchema`](/schema/ArraySchema).
  *
  * @param items Schema every item in the array must conform to.
- * @returns An `ArraySchema` validating arrays of the given item type.
  * @example ARRAY(NUMBER) // ArraySchema<number>
  * @see https://dhoulb.github.io/shelving/schema/ArraySchema/ARRAY
  */

package/schema/ArraySchema.js

@@ -32,8 +32,6 @@ export class ArraySchema extends Schema {
     separator;
     /**
      * Create a new `ArraySchema`.
-     *
-     * @param options Options for the schema, including the `items` schema, `min`/`max` counts, `unique`, and `separator`.
      */
     constructor({ items, one = items.one, many = items.many, title = "Items", placeholder = `No ${many}`, unique = false, min = 0, max = Number.POSITIVE_INFINITY, separator = ",", value = [], ...options }) {
         super({ one, many, title, placeholder, value, ...options });
@@ -82,7 +80,6 @@ export class ArraySchema extends Schema {
  * Sugar factory for [`ArraySchema`](/schema/ArraySchema).
  *
  * @param items Schema every item in the array must conform to.
- * @returns An `ArraySchema` validating arrays of the given item type.
  * @example ARRAY(NUMBER) // ArraySchema<number>
  * @see https://dhoulb.github.io/shelving/schema/ArraySchema/ARRAY
  */

package/schema/BooleanSchema.d.ts

@@ -3,13 +3,18 @@ import { Schema } from "./Schema.js";
 /**
  * Allowed options for `BooleanSchema`.
  *
- * - `value` — default boolean value used when the input is `undefined`.
- * - `required` — when `true`, a falsy result is rejected as invalid.
- *
  * @see https://dhoulb.github.io/shelving/schema/BooleanSchema/BooleanSchemaOptions
  */
 export interface BooleanSchemaOptions extends SchemaOptions {
+    /**
+     * Default boolean value used when the input is `undefined`.
+     * @default false
+     */
     readonly value?: boolean | undefined;
+    /**
+     * When `true`, a falsy result is rejected as invalid.
+     * @default false
+     */
     readonly required?: boolean | undefined;
 }
 /**
@@ -30,10 +35,6 @@ export declare class BooleanSchema extends Schema<boolean> {
     readonly required: boolean;
     /**
      * Create a new `BooleanSchema`.
-     *
-     * @param options Options for the schema.
-     * @param options.value Default boolean value used when the input is `undefined` (defaults to `false`).
-     * @param options.required When `true`, a falsy result is rejected as invalid (defaults to `false`).
      */
     constructor({ value, required, ...options }: BooleanSchemaOptions);
     /**

package/schema/BooleanSchema.js

@@ -17,10 +17,6 @@ const NEGATIVE = ["", "false", "0", "no", "n", "off"];
 export class BooleanSchema extends Schema {
     /**
      * Create a new `BooleanSchema`.
-     *
-     * @param options Options for the schema.
-     * @param options.value Default boolean value used when the input is `undefined` (defaults to `false`).
-     * @param options.required When `true`, a falsy result is rejected as invalid (defaults to `false`).
      */
     constructor({ value = false, required = false, ...options }) {
         super({ value, ...options });

package/schema/ChoiceSchema.d.ts

@@ -26,7 +26,7 @@ export type PossibleChoiceOptions<K extends string> = ImmutableArray<K> | Choice
  *
  * @see https://dhoulb.github.io/shelving/schema/ChoiceSchema/ChoiceSchemaOptions
  */
-export interface ChoiceSchemaOptions<O extends string, I = never> extends Omit<SchemaOptions, "value"> {
+export interface ChoiceSchemaOptions<O extends string, I = never> extends SchemaOptions {
     /** Specify correct options using a dictionary of entries. */
     readonly options: PossibleChoiceOptions<O>;
     /** Default option for the value. */
@@ -49,8 +49,6 @@ export declare class ChoiceSchema<O extends string, I = never> extends Schema<O>
     readonly options: ChoiceOptions<O>;
     /**
      * Create a new `ChoiceSchema`.
-     *
-     * @param options Options for the schema, including the allowed `options` and an optional default `value`.
      */
     constructor({ one, title, placeholder, options, value, ...rest }: ChoiceSchemaOptions<O, I>);
     /**
@@ -79,7 +77,6 @@ export declare class ChoiceSchema<O extends string, I = never> extends Schema<O>
  * Sugar factory for [`ChoiceSchema`](/schema/ChoiceSchema).
  *
  * @param options The allowed choices, as a `{ key: title }` dictionary or an array of keys.
- * @returns A `ChoiceSchema` validating the given choices.
  * @example CHOICE({ yes: "Yes", no: "No" }) // ChoiceSchema<"yes" | "no">
  * @see https://dhoulb.github.io/shelving/schema/ChoiceSchema/CHOICE
  */

package/schema/ChoiceSchema.js

@@ -24,8 +24,6 @@ export class ChoiceSchema extends Schema {
     options;
     /**
      * Create a new `ChoiceSchema`.
-     *
-     * @param options Options for the schema, including the allowed `options` and an optional default `value`.
      */
     constructor({ one = "choice", title = "Choice", placeholder = `No ${one}`, options, value, ...rest }) {
         super({ one, title, value, placeholder, ...rest });
@@ -63,7 +61,6 @@ export class ChoiceSchema extends Schema {
  * Sugar factory for [`ChoiceSchema`](/schema/ChoiceSchema).
  *
  * @param options The allowed choices, as a `{ key: title }` dictionary or an array of keys.
- * @returns A `ChoiceSchema` validating the given choices.
  * @example CHOICE({ yes: "Yes", no: "No" }) // ChoiceSchema<"yes" | "no">
  * @see https://dhoulb.github.io/shelving/schema/ChoiceSchema/CHOICE
  */