@dereekb/util 13.0.7 → 13.2.0

package/src/lib/string/url.d.ts

@@ -10,13 +10,17 @@ import { type Maybe } from '../value/maybe.type';
  * I.E. http, https, etc.
  */
 export type WebsiteProtocol = string;
+/** The HTTP protocol string literal type. */
 export type HttpWebsiteProtocol = 'http';
+/** The HTTPS protocol string literal type. */
 export type HttpsWebsiteProtocol = 'https';
+/** Known HTTP protocols: `"http"` or `"https"`. */
 export type KnownHttpWebsiteProtocol = HttpWebsiteProtocol | HttpsWebsiteProtocol;
 /**
- * Returns true if the input string is a KnownHttpWebsiteProtocol.
+ * Returns true if the input string is a known HTTP protocol (`"http"` or `"https"`).
  *
- * @param input
+ * @param input - The protocol string to check.
+ * @returns Whether the input is `"http"` or `"https"`.
  */
 export declare function isKnownHttpWebsiteProtocol(input: string): input is KnownHttpWebsiteProtocol;
 /**
@@ -32,7 +36,7 @@ export type WebsiteDomain = string;
  */
 export declare const HAS_WEBSITE_DOMAIN_NAME_REGEX: RegExp;
 /**
- * Returns true if the input probably has a website domain in it.
+ * Returns true if the input probably contains a website domain (has at least one period separating parts).
  *
  * Examples where it will return true:
  * - dereekb.com
@@ -41,8 +45,8 @@ export declare const HAS_WEBSITE_DOMAIN_NAME_REGEX: RegExp;
  * - https://components.dereekb.com/
  * - https://components.dereekb.com/doc/home
  *
- * @param input
- * @returns
+ * @param input - The string to check for a domain.
+ * @returns Whether the input appears to contain a website domain.
  */
 export declare function hasWebsiteDomain(input: string): input is WebsiteDomain;
 /**
@@ -62,10 +66,13 @@ export declare const WEBSITE_TLD_DETECTION_REGEX: RegExp;
  * Returns true if the input url has a website top level domain.
  *
  * It does not check whether or not the tld is a recognized tld.
+ *
+ * @param input - The URL string to check.
+ * @returns Whether the input appears to have a top-level domain.
  */
 export declare function hasWebsiteTopLevelDomain(input: string): boolean;
 /**
- * Simple website domain regex that looks for a period in the string between the domain and the tld
+ * Regex that matches a colon followed by digits, used to detect port numbers in URLs.
  */
 export declare const HAS_PORT_NUMBER_REGEX: RegExp;
 /**
@@ -77,7 +84,7 @@ export declare const HAS_PORT_NUMBER_REGEX: RegExp;
  */
 export type PortNumber = number;
 /**
- * Returns true if the input has a port number attached to it
+ * Returns true if the input string contains a port number (e.g., `:8080`).
  *
  * Examples where it will return true:
  * - localhost:8080
@@ -86,14 +93,15 @@ export type PortNumber = number;
  * - https://components.dereekb.com:8080/
  * - https://components.dereekb.com:8080/doc/home
  *
- * @param input
- * @returns
+ * @param input - The string to check for a port number.
+ * @returns Whether the input contains a port number.
  */
 export declare function hasPortNumber(input: string): boolean;
 /**
- * Reads the port number from the input, if possible.
+ * Extracts the port number from the input string, if one is present.
  *
- * @param input
+ * @param input - The string to extract a port number from.
+ * @returns The port number, or `undefined` if none is found.
  */
 export declare function readPortNumber(input: string): Maybe<PortNumber>;
 /**
@@ -107,10 +115,12 @@ export type BaseWebsiteUrl<D extends WebsiteDomain = WebsiteDomain> = `http://${
  */
 export type BaseWebsiteUrlInput = string | WebsiteUrl | WebsiteDomain;
 /**
- * Creates a base website url from the input domain or url.
+ * Creates a base website URL (with `http://` or `https://` prefix) from the input domain or URL.
+ * If the input lacks a TLD and port, the default TLD is appended.
  *
- * @param input
- * @returns
+ * @param input - A domain, URL, or partial URL string.
+ * @param defaultTld - The TLD to append if none is detected. Defaults to `"com"`.
+ * @returns A fully-qualified base website URL.
  */
 export declare function baseWebsiteUrl(input: BaseWebsiteUrlInput, defaultTld?: string): BaseWebsiteUrl;
 /**
@@ -125,32 +135,42 @@ export declare function baseWebsiteUrl(input: BaseWebsiteUrlInput, defaultTld?:
  */
 export type WebsiteUrl = string;
 /**
- * Returns true if the input string is probably a website url.
+ * Returns true if the input string is probably a website URL.
+ *
+ * Checks that it has a domain and the path is a valid slash path. Query parameters are ignored.
  *
- * Checks that it has the http/https prefix, has a domain, and the path is a slash path. The query parameters are ignored.
+ * @param input - The string to check.
+ * @returns Whether the input appears to be a valid website URL.
  */
 export declare function isWebsiteUrl(input: string): input is WebsiteUrl;
 /**
- * Details about an input string.
- *
- * Is tested if it is a website url.
+ * Detailed analysis of whether an input string is a valid website URL, including its parsed components.
  */
 export interface WebsiteUrlDetails {
+    /** The original input string. */
     readonly input: string;
+    /** Whether the input is a valid website URL. */
     readonly isWebsiteUrl: boolean;
+    /** Whether the input has an `http://` or `https://` prefix. */
     readonly hasHttpPrefix: boolean;
+    /** Whether the input contains a website domain. */
     readonly hasWebsiteDomain: boolean;
+    /** The domain and path split pair. */
     readonly splitPair: WebsiteDomainAndPathPair;
+    /** The extracted domain. */
     readonly domain: WebsiteDomain;
+    /** The full website path including query string. */
     readonly websitePath: WebsitePath;
+    /** The path portion without query parameters. */
     readonly path: string;
+    /** The query string portion, or undefined if none. */
     readonly query: string | undefined;
 }
 /**
- * Returns details about the input string, considering it a WebsiteUrl and returning details.
+ * Parses the input string as a website URL and returns detailed information about its components.
  *
- * @param input string to test
- * @returns WebsiteUrlDetails
+ * @param input - The string to analyze as a URL.
+ * @returns An object containing parsed URL components and validation flags.
  */
 export declare function websiteUrlDetails(input: string): WebsiteUrlDetails;
 /**
@@ -158,9 +178,10 @@ export declare function websiteUrlDetails(input: string): WebsiteUrlDetails;
  */
 export type WebsiteUrlWithPrefix = string;
 /**
- * Returns true if the input string is probably a website url.
+ * Returns true if the input string is probably a website URL and has an `http://` or `https://` prefix.
  *
- * Checks that it has the http/https prefix, has a domain, and the path is a slash path. The query parameters are ignored.
+ * @param input - The string to check.
+ * @returns Whether the input is a website URL with an HTTP prefix.
  */
 export declare function isWebsiteUrlWithPrefix(input: string): input is WebsiteUrl;
 /**
@@ -181,9 +202,10 @@ export declare function isWebsiteUrlWithPrefix(input: string): input is WebsiteU
  */
 export type StandardInternetAccessibleWebsiteUrl = string;
 /**
- * Returns true if the input is a StandardInternetAccessibleWebsiteUrl.
+ * Returns true if the input is a standard internet-accessible website URL with a recognized TLD and optionally an HTTP/HTTPS protocol.
  *
- * @param input
+ * @param input - The string to check.
+ * @returns Whether the input is a standard internet-accessible website URL.
  */
 export declare function isStandardInternetAccessibleWebsiteUrl(input: string): input is StandardInternetAccessibleWebsiteUrl;
 /**
@@ -205,10 +227,12 @@ export type WebsiteDomainAndPath = string;
  */
 export type WebsitePath = `/${string}`;
 /**
- * Creates a WebsiteUrl from the input
- * @param basePath
- * @param paths
- * @returns
+ * Creates a {@link WebsiteUrl} by merging the base path with additional path segments, preserving the original protocol.
+ *
+ * @param basePath - The base URL or domain to build upon.
+ * @param paths - One or more path segments to append.
+ * @param defaultProtocol - Optional protocol to use if the base path has none.
+ * @returns The constructed website URL.
  */
 export declare function websiteUrlFromPaths(basePath: BaseWebsiteUrlInput, paths: ArrayOrValue<Maybe<WebsitePath>>, defaultProtocol?: WebsiteProtocol): WebsiteUrl;
 /**
@@ -216,9 +240,12 @@ export declare function websiteUrlFromPaths(basePath: BaseWebsiteUrlInput, paths
  */
 export type WebsiteQueryString = `?${string}`;
 /**
- * Maps the input WebsitePath to remove the configured base path.
+ * Function that extracts and isolates a specific path portion from a website URL, domain-and-path, or path string.
  */
 export type IsolateWebsitePathFunction = MapFunction<WebsitePath | WebsiteDomainAndPath | WebsiteUrl, WebsitePath>;
+/**
+ * Configuration for creating an {@link IsolateWebsitePathFunction}.
+ */
 export interface IsolateWebsitePathFunctionConfig {
     /**
      * Optional range of paths to isolate.
@@ -245,99 +272,157 @@ export interface IsolateWebsitePathFunctionConfig {
     readonly removeTrailingSlash?: boolean;
 }
 /**
- * Creates a new ExcludeBaseWebsitePathFunction that excludes the base path from the input website path if it exists.
+ * Creates an {@link IsolateWebsitePathFunction} that extracts and transforms a path from a website URL based on the configuration.
  *
- * @param basePath
+ * @param config - Configuration for path isolation, including base path removal, component range, query handling, and trailing slash behavior.
+ * @returns A function that isolates the configured portion of a website path.
  */
 export declare function isolateWebsitePathFunction(config?: IsolateWebsitePathFunctionConfig): IsolateWebsitePathFunction;
+/**
+ * A pair containing the path and optional query string components of a website URL.
+ */
 export interface WebsitePathAndQueryPair {
+    /** The path portion of the URL (before the `?`). */
     path: WebsitePath;
+    /** The query string portion of the URL (including the leading `?`), if present. */
     query?: Maybe<WebsiteQueryString>;
 }
+/**
+ * Splits a website path string into its path and query string components.
+ *
+ * @param inputPath - The path string to split.
+ * @returns A pair containing the path and optional query string.
+ */
 export declare function websitePathAndQueryPair(inputPath: string | WebsitePath): WebsitePathAndQueryPair;
 /**
- * Replaces any extra query parameter "?" characters with an "&" character.
+ * Replaces extra `?` characters in a query string with `&` to fix malformed query parameters.
  *
- * Can also choose to replace all instead, incase the input string should be considered the query without.
+ * By default, preserves the first `?` and replaces subsequent ones. If `replaceAll` is true, all `?` characters are replaced.
  *
- * @param input
+ * @param input - The query string to fix.
+ * @param replaceAll - If true, replaces all `?` characters (useful when the input is already past the initial `?`).
+ * @returns The fixed query string.
  */
 export declare function fixExtraQueryParameters(input: string, replaceAll?: boolean): string;
 /**
- * Reads the website path from the input.
+ * Extracts the path component from a website URL, stripping the protocol and domain.
  *
- * @param input
- * @returns
+ * @param inputUrl - The URL to extract the path from.
+ * @returns The website path component.
  */
 export declare function websitePathFromWebsiteUrl(inputUrl: WebsiteUrl | WebsiteDomainAndPath): WebsitePath;
+/**
+ * Splits a website URL into its domain and path components after removing the protocol prefix.
+ *
+ * @param inputUrl - The URL to split.
+ * @returns A pair containing the domain and path.
+ */
 export declare function websiteDomainAndPathPairFromWebsiteUrl(inputUrl: WebsiteUrl | WebsiteDomainAndPath): WebsiteDomainAndPathPair;
 /**
- * Reads the website path from the input WebsiteDomainAndPath.
+ * Extracts the path component from a domain-and-path string.
  *
- * @param input
- * @returns
+ * @param input - The domain-and-path string to extract the path from.
+ * @returns The website path component.
  */
 export declare function websitePathFromWebsiteDomainAndPath(input: WebsiteDomainAndPath): WebsitePath;
+/**
+ * A pair containing the domain and path components of a website URL.
+ */
 export interface WebsiteDomainAndPathPair {
+    /** The domain portion of the URL. */
     domain: WebsiteDomain;
+    /** The path portion of the URL. */
     path: WebsitePath;
 }
+/**
+ * Splits a domain-and-path string into its domain and path components at the first slash.
+ *
+ * @param input - The domain-and-path string to split.
+ * @returns A pair containing the domain and path.
+ */
 export declare function websiteDomainAndPathPair(input: WebsiteDomainAndPath): WebsiteDomainAndPathPair;
+/**
+ * Regex that matches `http://` or `https://` at the start of a string.
+ */
 export declare const HTTP_OR_HTTPS_REGEX: RegExp;
+/**
+ * Regex that captures any protocol prefix (e.g., `http`, `https`, `ftp`) before `://`.
+ */
 export declare const WEB_PROTOCOL_PREFIX_REGEX: RegExp;
 /**
  * Reads the website protocol from the input string, if it exists.
+ * Does not include the `://` separator.
  *
- * Does not include the "://" components.
- *
- * @param input
+ * @param input - The URL string to extract the protocol from.
+ * @returns The protocol string (e.g., `"https"`), or `undefined` if no protocol is present.
  */
 export declare function readWebsiteProtocol(input: string): Maybe<WebsiteProtocol>;
 /**
- * Removes any existing protocol and sets the protocol to match the input.
+ * Replaces the existing protocol prefix with the specified one, or removes it if no protocol is provided.
  *
- * If no protcol is input, then it is removed from the input.
- *
- * @param url
- * @param protocol
+ * @param input - The URL string to modify.
+ * @param protocol - The protocol to set (e.g., `"https"`), or `undefined`/`null` to remove the protocol.
+ * @returns The URL with the updated protocol prefix.
  */
 export declare function setWebProtocolPrefix(input: string, protocol?: Maybe<WebsiteProtocol>): string;
 /**
- * Removes any existing protocol prefix from the input.
+ * Removes any protocol prefix (e.g., `http://`, `https://`, `ftp://`) from the input string.
  *
- * @param input
+ * @param input - The URL string to strip the protocol from.
+ * @returns The URL without the protocol prefix.
  */
 export declare function removeWebProtocolPrefix(input: string): string;
 /**
- * Adds both https:// to the url.
+ * Adds an HTTP or HTTPS protocol prefix to the URL, replacing any existing protocol.
  *
- * @param url
- * @returns
+ * @param url - The URL or domain string to add the prefix to.
+ * @param prefix - The HTTP protocol to use. Defaults to `"https"`.
+ * @returns The URL with the specified HTTP protocol prefix.
  */
 export declare function addHttpToUrl(url: BaseWebsiteUrl | WebsiteDomainAndPath | string, prefix?: KnownHttpWebsiteProtocol): BaseWebsiteUrl;
 /**
- * Removes the prefixes http:// and https:// from the url. If these protocols are not used, nothing is removed.
+ * Removes `http://` or `https://` from the URL. Other protocols are not affected.
  *
- * @param url
- * @returns
+ * @param url - The URL to strip the HTTP prefix from.
+ * @returns The URL without the HTTP/HTTPS prefix.
  */
 export declare function removeHttpFromUrl(url: BaseWebsiteUrl | string): WebsiteDomainAndPath;
 /**
- * Returns true if the input string starts with http/https
+ * Returns true if the input string starts with `http://` or `https://`.
  *
- * @param input
+ * @param input - The string to check.
+ * @returns Whether the input has an HTTP/HTTPS prefix.
  */
 export declare function hasHttpPrefix(input: string): input is BaseWebsiteUrl;
+/**
+ * Object representation of a `mailto:` URL.
+ */
 export interface MailToUrl {
+    /** The email address for the mailto link. */
     email: string;
 }
+/**
+ * Input for creating a mailto URL string. Can be an email address string or a {@link MailToUrl} object.
+ */
 export type MailToUrlInput = EmailAddress | MailToUrl;
+/**
+ * Creates a `mailto:` URL string from the input email address or object.
+ *
+ * @param input - An email address or MailToUrl object.
+ * @returns A `mailto:` URL string.
+ */
 export declare function mailToUrlString(input: MailToUrlInput): string;
+/**
+ * Creates a `tel:` URL string from a phone number, handling E.164 format and extensions.
+ *
+ * @param phone - The phone number to create a tel URL for.
+ * @returns A `tel:` URL string, with extension appended if present.
+ */
 export declare function telUrlString(phone: PhoneNumber | E164PhoneNumberWithOptionalExtension): string;
 /**
- * Creates a tel url string for the input E164PhoneNumberExtensionPair.
+ * Creates a `tel:` URL string for an E.164 phone number with an optional extension.
  *
- * @param pair
- * @returns
+ * @param pair - The phone number and extension pair.
+ * @returns A `tel:` URL string with the extension appended using `;` if present.
  */
 export declare function telUrlStringForE164PhoneNumberPair(pair: E164PhoneNumberExtensionPair): string;

package/src/lib/tree/tree.explore.d.ts

@@ -24,56 +24,123 @@ export declare const ExploreTreeVisitNodeDecision: {
 };
 export type ExploreTreeVisitNodeDecision = (typeof ExploreTreeVisitNodeDecision)[keyof typeof ExploreTreeVisitNodeDecision];
 /**
- * A function that determines if a node should be visited.
+ * Function that determines how a node should be handled during tree exploration.
  *
- * The mapped value is also present.
+ * Receives both the original node and its mapped value, allowing filtering decisions
+ * based on either the raw tree structure or a transformed representation.
+ *
+ * @template N - The tree node type.
+ * @template V - The mapped value type, defaults to N if no mapping is applied.
  */
 export type ExploreTreeVisitNodeDecisionFunction<N extends TreeNode<unknown>, V = N> = (node: N, nodeMappedValue: V) => ExploreTreeVisitNodeDecision;
 /**
- * A function that visits a node.
+ * Callback invoked when a node is visited during tree exploration.
+ *
+ * Receives the mapped value (or the node itself if no mapping) and the original node,
+ * allowing side effects such as accumulating results or modifying external state.
+ *
+ * @template N - The tree node type.
+ * @template V - The mapped value type passed to the callback.
  */
 export type ExploreTreeVisitNodeFunction<N extends TreeNode<unknown>, V> = (value: V, node: N) => void;
 /**
- * Creates a traversal function that can be used to visit nodes.
+ * Factory that creates a traversal strategy for tree exploration.
+ *
+ * Controls the order in which nodes are visited (e.g., depth-first vs breadth-first).
+ * Receives the visit callback and a recursive traversal function, and returns a function
+ * that handles a single node based on its visit decision.
+ *
+ * @template N - The tree node type.
+ * @template V - The mapped value type.
  */
 export type ExploreTreeTraversalFactoryFunction<N extends TreeNode<unknown>, V> = (visit: ExploreTreeVisitNodeFunction<N, V>, traverseTree: (tree: N) => void) => (node: N, nodeMappedValue: V, visitDecision: ExploreTreeVisitNodeDecision) => void;
+/**
+ * Configuration for creating an {@link ExploreTreeFunction}.
+ *
+ * Allows customizing node mapping, visit filtering, and traversal order.
+ * All options can also be overridden at call time.
+ *
+ * @template N - The tree node type.
+ * @template V - The mapped value type, defaults to N.
+ */
 export interface ExploreTreeFunctionConfig<N extends TreeNode<unknown>, V = N> {
     /**
-     * A custom traversal function to use instead of the default traversal function.
+     * Custom traversal strategy (e.g., breadth-first). Defaults to depth-first.
      */
     traverseFunctionFactory?: ExploreTreeTraversalFactoryFunction<N, V>;
     /**
-     * A function that maps a node to a specific value before visiting it.
+     * Transforms each node into a value before visiting. Defaults to identity.
      */
     mapNodeFunction?: (node: N) => V;
     /**
-     * A function that determines if a node should be visited.
+     * Controls whether each node is visited, skipped, or has only its children visited.
+     * Defaults to visiting all nodes.
      */
     shouldVisitNodeFunction?: Maybe<ExploreTreeVisitNodeDecisionFunction<N, V>>;
 }
 /**
- * Explores the input trees.
+ * Traverses one or more trees, invoking a visit callback on each node.
+ *
+ * Supports runtime overrides of mapping, filtering, and traversal strategy.
+ *
+ * @template N - The tree node type.
+ * @template V - The mapped value type passed to the visit callback.
  */
 export type ExploreTreeFunction<N extends TreeNode<unknown, N>, V> = (trees: ArrayOrValue<N>, visit: ExploreTreeVisitNodeFunction<N, V>, override?: ExploreTreeFunctionConfig<N, V>) => void;
 /**
- * Convenience function for exploring the input trees
- 
- * @param trees
- * @param visitNodeFn
- * @returns
+ * Creates a reusable tree exploration function with configurable traversal, mapping, and filtering.
+ *
+ * The returned function traverses one or more trees, applying a visit callback to each node.
+ * By default uses depth-first traversal, identity mapping, and visits all nodes. All options
+ * can be overridden per-call.
+ *
+ * @param config - Optional default configuration for mapping, filtering, and traversal strategy.
+ * @returns A reusable function that explores trees with the configured behavior.
+ *
+ * @example
+ * ```typescript
+ * const exploreFn = exploreTreeFunction<TestNode, string>({
+ *   mapNodeFunction: (node) => node.value.id
+ * });
+ * const visited: string[] = [];
+ *
+ * exploreFn(rootNode, (id) => {
+ *   visited.push(id);
+ * });
+ * ```
  */
 export declare function exploreTreeFunction<N extends TreeNode<unknown, N>, V>(config?: Maybe<ExploreTreeFunctionConfig<N, V>>): ExploreTreeFunction<N, V>;
 /**
- * A depth-first traversal factory function.
+ * Creates a depth-first traversal strategy for tree exploration.
+ *
+ * Visits each node before its children (pre-order). This is the default traversal
+ * strategy used by {@link exploreTreeFunction}.
  *
- * @returns A ExploreTreeTraversalFactoryFunction<N, V>.
+ * @returns A traversal factory that processes nodes in depth-first order.
+ *
+ * @example
+ * ```typescript
+ * const exploreFn = exploreTreeFunction<TestNode, TestNode>({
+ *   traverseFunctionFactory: depthFirstExploreTreeTraversalFactoryFunction()
+ * });
+ * // Visits: root -> child1 -> leaf1 -> leaf2 -> child2 -> leaf3
+ * ```
  */
 export declare function depthFirstExploreTreeTraversalFactoryFunction<N extends TreeNode<unknown, N>, V>(): ExploreTreeTraversalFactoryFunction<N, V>;
 /**
- * A breadth-first traversal factory function.
+ * Creates a breadth-first traversal strategy for tree exploration.
  *
  * Visits nodes level by level, processing all nodes at depth N before moving to depth N+1.
+ * Uses an internal queue to defer child processing until the current level is complete.
+ *
+ * @returns A traversal factory that processes nodes in breadth-first order.
  *
- * @returns A ExploreTreeTraversalFactoryFunction<N, V>.
+ * @example
+ * ```typescript
+ * const exploreFn = exploreTreeFunction<TestNode, TestNode>({
+ *   traverseFunctionFactory: breadthFirstExploreTreeTraversalFactoryFunction()
+ * });
+ * // Visits: root -> child1, child2, child3 -> leaf1, leaf2, leaf3
+ * ```
  */
 export declare function breadthFirstExploreTreeTraversalFactoryFunction<N extends TreeNode<unknown, N>, V>(): ExploreTreeTraversalFactoryFunction<N, V>;

package/src/lib/tree/tree.flatten.d.ts

@@ -36,24 +36,61 @@ export declare const FlattenTreeAddNodeDecision: {
 };
 export type FlattenTreeAddNodeDecision = ExploreTreeVisitNodeDecision;
 /**
- * A function that determines if a node should be visited.
+ * Function that determines whether a node should be included in the flattened output.
  *
- * The mapped value is also present.
+ * Alias for {@link ExploreTreeVisitNodeDecisionFunction} in the context of tree flattening.
+ * Receives both the original node and its mapped value for filtering decisions.
+ *
+ * @template N - The tree node type.
+ * @template V - The mapped value type, defaults to N.
  */
 export type FlattenTreeAddNodeDecisionFunction<N extends TreeNode<unknown>, V = N> = ExploreTreeVisitNodeDecisionFunction<N, V>;
 /**
- * Traverses the tree and flattens it into all tree nodes.
+ * Flattens a tree into an array containing all its nodes using depth-first traversal.
+ *
+ * @param tree - The root node to flatten.
+ * @param addNodeFn - Optional filter controlling which nodes and subtrees are included.
+ * @returns An array of all nodes in the tree that pass the filter.
+ *
+ * @example
+ * ```typescript
+ * const nodes = flattenTree(rootNode);
+ * // Returns [root, child1, leaf1, leaf2, child2, leaf3, child3]
+ * ```
  */
 export declare function flattenTree<N extends TreeNode<unknown> = TreeNode<unknown>>(tree: N, addNodeFn?: Maybe<FlattenTreeAddNodeDecisionFunction<N>>): N[];
 /**
- * Traverses the tree and pushes the nodes into the input array.
+ * Flattens a tree and appends the resulting nodes to an existing array.
  *
- * @param tree
- * @param array
- * @returns
+ * Useful for accumulating nodes from multiple trees into a single collection.
+ *
+ * @param tree - The root node to flatten.
+ * @param array - The target array to push flattened nodes into.
+ * @param addNodeFn - Optional filter controlling which nodes and subtrees are included.
+ * @returns The same array reference, now containing the appended nodes.
+ *
+ * @example
+ * ```typescript
+ * const existing: TreeNode[] = [someNode];
+ * flattenTreeToArray(rootNode, existing);
+ * // existing now contains [someNode, root, child1, ...]
+ * ```
  */
 export declare function flattenTreeToArray<N extends TreeNode<unknown> = TreeNode<unknown>>(tree: N, array: N[], addNodeFn?: Maybe<FlattenTreeAddNodeDecisionFunction<N>>): N[];
+/**
+ * Configuration for creating a {@link FlattenTreeFunction} via {@link flattenTreeToArrayFunction}.
+ *
+ * Extends the exploration config but replaces `shouldVisitNodeFunction` with `shouldAddNodeFunction`
+ * to use flattening-specific terminology.
+ *
+ * @template N - The tree node type.
+ * @template V - The mapped value type collected in the output array.
+ */
 export interface FlattenTreeToArrayFunctionConfig<N extends TreeNode<unknown>, V> extends Omit<ExploreTreeFunctionConfig<N, V>, 'shouldVisitNodeFunction'> {
+    /**
+     * Controls whether each node's mapped value is added to the output array.
+     * Defaults to adding all nodes.
+     */
     readonly shouldAddNodeFunction?: Maybe<FlattenTreeAddNodeDecisionFunction<N, V>>;
 }
 /**

package/src/lib/type.d.ts

@@ -14,32 +14,35 @@ export type ObjectWithConstructor = {
     constructor: Function;
 };
 /**
- * Returns true if the input object is an object with a constructor.
+ * Returns true if the input is a function-like value with a prototype and constructor (i.e., a class or named function declaration).
+ * Returns false for arrow functions, class instances, plain objects, and primitives.
  *
- * @param obj
- * @returns
+ * @param obj - The value to check.
+ * @returns Whether the value is a function with a constructor.
  */
 export declare function isObjectWithConstructor(obj: any): obj is ObjectWithConstructor;
 /**
- * Returns true if the input object is a class type that requires using "new".
+ * Returns true if the input is a class (requires `new` to instantiate). Distinguishes classes from regular functions
+ * by checking that the prototype is non-writable.
  *
- * @param obj
- * @returns
+ * @param obj - The value to check.
+ * @returns Whether the value is a class type.
  */
 export declare function isClassLikeType(obj: unknown): obj is ClassLikeType;
 export type FunctionType = 'function' | 'class' | 'arrow';
 /**
- * Returns the input value's function type, or null if not a function.
+ * Determines the function type of the input value: `'class'`, `'function'`, or `'arrow'`.
+ * Returns `null` if the input is not a function.
  *
- * @param x
- * @returns
+ * @param x - The value to inspect.
+ * @returns The {@link FunctionType}, or `null` for non-functions.
  */
 export declare function getFunctionType(x: unknown): Maybe<FunctionType>;
 /**
- * Returns true if the input is a non-class function.
+ * Returns true if the input is a function but not a class (i.e., a regular function or arrow function).
  *
- * @param x
- * @returns
+ * @param x - The value to check.
+ * @returns Whether the value is a non-class function.
  */
 export declare function isNonClassFunction(x: unknown): x is Function;
 /**