@homedev/objector 1.3.8 → 1.3.10

package/dist/index.d.ts

@@ -1,3 +1,81 @@
+/**
+ * Parses and queries command-line arguments.
+ *
+ * Accepts argv-like arrays and parses only the provided tokens.
+ *
+ * @public
+ */
+export declare class CommandLineArgs {
+    #private;
+    /**
+     * Creates a parser for the provided command-line tokens.
+     *
+     * @param args - Argument tokens to parse.
+     * @param definitions - Known argument definitions used by usage output.
+     */
+    constructor(args: string[], definitions?: CommandLineArgumentDefinition[]);
+    /**
+     * Returns normalized parsed argument tokens.
+     */
+    get args(): string[];
+    /**
+     * Returns non-option positional values.
+     */
+    get positionals(): string[];
+    /**
+     * Returns true if a flag was provided.
+     *
+     * @param flag - Option name with or without `-`/`--` prefix.
+     */
+    has(flag: string): boolean;
+    /**
+     * Returns values for a flag.
+     *
+     * @param flag - Option name with or without `-`/`--` prefix.
+     */
+    getArgs(flag: string): string[];
+    /**
+     * Returns true for boolean flags, first value for valued flags, or undefined.
+     *
+     * @param flag - Option name with or without `-`/`--` prefix.
+     */
+    get(flag: string): string | true | undefined;
+    /**
+     * Returns all options as a plain object.
+     */
+    toObject(): Record<string, string[] | true>;
+    /**
+     * Builds usage output from provided argument definitions.
+     *
+     * @param command - Command name shown in usage output.
+     */
+    usage(command?: string): string;
+}
+
+/**
+ * Defines an argument for usage output.
+ *
+ * @public
+ */
+export declare interface CommandLineArgumentDefinition {
+    name: string;
+    alias?: string;
+    description?: string;
+    takesValue?: boolean;
+    multiple?: boolean;
+    valueName?: string;
+}
+
+/**
+ * Parsed representation of a single CLI option.
+ *
+ * @public
+ */
+export declare interface CommandLineOption {
+    values: string[];
+    sawEqualsStyle: boolean;
+}
+
 /**
  * @public
  */
@@ -20,6 +98,13 @@ declare interface EncoderOptions {
 
 declare type EncoderOptions_2 = ObjectorDecoratorOptions;
 
+/**
+ * Checks whether a file is readable.
+ *
+ * @param fileName - File path to check.
+ * @returns True when the file can be accessed for reading.
+ * @public
+ */
 export declare const exists: (fileName: string) => Promise<boolean>;
 
 export declare interface FieldContext {
@@ -131,12 +216,32 @@ export declare type FieldProcessorTypedFunc = FieldProcessorFunc | (FieldProcess
 
 declare type FieldProcessorTypedFunc_2 = FieldProcessorFunc_2 | (FieldProcessorOptions_2 & { fn: FieldProcessorFunc_2 })
 
-declare interface FilePatternOptions {
+/**
+ * @public
+ */
+export declare interface FilePatternOptions {
     cwd: string;
     filter?: (fileName: string, index: number, array: string[]) => boolean;
     map: (fileName: string, index: number, array: string[]) => Promise<any>;
 }
 
+/**
+ * Resolves the working directory used by file utilities.
+ *
+ * @param cwd - Optional absolute or relative directory override.
+ * @returns Absolute working directory path.
+ * @public
+ */
+export declare const getCwd: (cwd?: string) => string;
+
+/**
+ * Maps files matching a glob pattern (or a single path) with async projection.
+ *
+ * @param pattern - Glob pattern(s) or direct file path.
+ * @param options - Mapping options including cwd, optional filter, and map function.
+ * @returns Mapped result for a direct path, or mapped array for glob patterns.
+ * @public
+ */
 export declare const globMap: <T>(pattern: string | string[], options: FilePatternOptions) => Promise<T[] | T>;
 
 /**
@@ -174,9 +279,10 @@ export declare interface LoadContext {
 
 /**
  * @public
- * @param fileName
- * @param options
- * @returns
+ * @param fileName - Name or path of the file to load.
+ * @param options - Loading options including parser selection and lookup directories.
+ * @returns Parsed file content and path metadata.
+ * @throws - When no parser is resolved or locating/reading/parsing fails.
  */
 export declare const loadFormat: <T = any>(fileName: string, options?: LoadOptions) => Promise<LoadResult<T>>;
 
@@ -206,27 +312,87 @@ export declare interface LoadOptions {
     format?: string;
 }
 
+/**
+ * Result of loading and parsing a file.
+ *
+ * @typeParam T - Parsed content type.
+ * @public
+ */
 export declare interface LoadResult<T> {
     fullPath: string;
     folderPath: string;
     content: T;
 }
 
+/**
+ * Resolves a file path by searching the provided directories.
+ *
+ * @param fileName - File name or path to locate.
+ * @param dirs - Optional directories to search when fileName is relative.
+ * @returns Absolute path to the first matching file.
+ * @throws - When no matching file is found.
+ * @public
+ */
 export declare const locate: (fileName: string, dirs?: string[]) => Promise<string>;
 
+/**
+ * @public
+ */
 export declare type LogFunction = (className: string, ...args: any[]) => void;
 
+/**
+ * @public
+ */
 export declare class Logger {
     options: LoggerOptions;
+    /**
+     * Creates a logger with optional configuration overrides.
+     *
+     * @param options - Partial logger options to merge with defaults.
+     */
     constructor(options?: Partial<LoggerOptions>);
+    /**
+     * Writes a log entry when the message level passes the configured filter.
+     *
+     * @param className - Log level name.
+     * @param args - Log payload values.
+     */
     write(className: string, ...args: any[]): void;
+    /**
+     * Writes an INFO level log entry.
+     *
+     * @param args - Log payload values.
+     */
     info(...args: any[]): void;
+    /**
+     * Writes an ERROR level log entry.
+     *
+     * @param args - Log payload values.
+     */
     error(...args: any[]): void;
+    /**
+     * Writes a WARN level log entry.
+     *
+     * @param args - Log payload values.
+     */
     warn(...args: any[]): void;
+    /**
+     * Writes a DEBUG level log entry.
+     *
+     * @param args - Log payload values.
+     */
     debug(...args: any[]): void;
+    /**
+     * Writes a VERBOSE level log entry.
+     *
+     * @param args - Log payload values.
+     */
     verbose(...args: any[]): void;
 }
 
+/**
+ * @public
+ */
 export declare interface LoggerOptions {
     level: string;
     showClass: boolean;
@@ -252,32 +418,74 @@ export declare const makeFieldProcessorMap: <T = unknown>(source: Record<keyof T
     keys?: (keyof T)[];
 }) => FieldProcessorMap;
 
+/**
+ * Fluent markdown content builder.
+ *
+ * @public
+ */
 export declare class Markdown extends StringBuilder {
     #private;
+    /**
+     * Writes a markdown heading and trailing blank line.
+     *
+     * @param text - Heading text.
+     * @param level - Heading level from 1 to 6.
+     */
     header(text: string, level?: number): this;
+    /**
+     * Starts a fenced code block and optionally writes code and closes it.
+     *
+     * @param code - Optional code content.
+     * @param language - Optional code language id.
+     */
     codeBlock(code?: string, language?: string): this;
+    /** Closes the current fenced code block. */
     endCodeBlock(): this;
-    link(text: string, url: string): this;
+    /** Writes an inline markdown link. */
+    link(text: string, url: string, title?: string): this;
+    /** Writes a markdown table from headers and rows. */
     table(headers: string[], rows: string[][]): this;
+    /** Writes one or more quoted lines. */
     blockquote(text: string): this;
+    /** Writes bold text. */
     bold(text: string): this;
+    /** Writes italic text. */
     italic(text: string): this;
+    /** Writes a bullet item line. */
     item(text: string): this;
+    /** Writes bullet items from an array or key-value map. */
     items(items: string[] | Record<string, any>): this;
+    /** Writes an ordered list starting from the provided number. */
     orderedList(items: string[], start?: number): this;
+    /** Writes inline code text. */
     code(text: string): this;
+    /** Writes a horizontal rule. */
     horizontalRule(): this;
+    /** Writes an image markdown line. */
     image(alt: string, url: string): this;
+    /** Writes strikethrough text. */
     strikethrough(text: string): this;
+    /** Writes highlighted text using == syntax. */
     highlight(text: string): this;
+    /** Writes subscript text using ~ syntax. */
     subscript(text: string): this;
+    /** Writes superscript text using ^ syntax. */
     superscript(text: string): this;
+    /** Writes a markdown task list. */
     taskList(items: {
         text: string;
         checked: boolean;
     }[]): this;
+    /**
+     * Starts a section heading and increments internal nesting level.
+     *
+     * @param text - Section title.
+     * @param level - Optional explicit heading level baseline.
+     */
     section(text: string, level?: number): this;
+    /** Decrements section nesting level by one. */
     endSection(): this;
+    /** Sets the internal section nesting level directly. */
     setSectionLevel(level: number): this;
 }
 
@@ -425,6 +633,9 @@ export declare type ObjectorPluginConstructor = new (o: Objector, ...args: any[]
 
 declare type ObjectorPluginFunction = (o: Objector) => void;
 
+/**
+ * @public
+ */
 export declare interface Output {
     name: string;
     type?: 'json' | 'yaml' | 'text';
@@ -491,24 +702,74 @@ declare type SharedFunctionOptions = ObjectorDecoratorOptions;
 
 declare type SourceFunc = (...args: any[]) => any;
 
+/**
+ * @public
+ */
 export declare class StringBuilder {
     #private;
     options: StringBuilderOptions;
+    /**
+     * Creates a new StringBuilder instance.
+     *
+     * @param initial - Optional initial content.
+     * @param options - Builder formatting options.
+     */
     constructor(initial?: string | string[] | StringBuilder, options?: StringBuilderOptions);
+    /**
+     * Replaces current formatting options.
+     *
+     * @param options - New builder options.
+     * @returns Current builder instance.
+     */
     setOptions(options: StringBuilderOptions): this;
+    /** Clears all buffered blocks. */
     clear(): this;
+    /** Returns true when no content is buffered. */
     isEmpty(): boolean;
+    /** Returns concatenated content. */
     toString(): string;
+    /** Increases indentation level by one. */
     indent(): this;
+    /** Decreases indentation level by one when possible. */
     dedent(): this;
+    /** Returns current indentation level. */
     getCurrentIndent(): number;
+    /** Returns current content split by newline. */
     getLines(): string[];
+    /**
+     * Formats a line according to indentation and line options.
+     *
+     * @param line - Input line to format.
+     * @returns Formatted line including line separator.
+     */
     formatLine(line?: string): string;
+    /**
+     * Appends one or more values to the buffer.
+     *
+     * @param args - Values to append.
+     * @returns Current builder instance.
+     */
     write(...args: any[]): this;
+    /**
+     * Writes one or more formatted lines.
+     *
+     * @param args - Values to write as lines.
+     * @returns Current builder instance.
+     */
     writeLine(...args: any[]): this;
+    /**
+     * Maps input items to writes using a callback.
+     *
+     * @param items - Source items.
+     * @param fn - Mapping callback.
+     * @returns Current builder instance.
+     */
     writeMap<T>(items: T[], fn: (item: T, index: number, builder: this) => string | this): this;
 }
 
+/**
+ * @public
+ */
 export declare interface StringBuilderOptions {
     indentChar?: string;
     indentSize?: number;
@@ -522,6 +783,16 @@ export declare const variable: (options?: VariableOptions) => (_: any, ctx: Clas
 
 declare type VariableOptions = ObjectorDecoratorOptions;
 
+/**
+ * Encodes and writes content to a file path using the selected format encoder.
+ *
+ * @param filePath - Destination file path.
+ * @param content - Data to encode and write.
+ * @param options - Encoder selection options.
+ * @returns Promise resolved when writing completes.
+ * @throws - When no encoder can be resolved.
+ * @public
+ */
 export declare const writeFormat: (filePath: string, content: any, options?: WriteFormatOptions) => Promise<void>;
 
 /**
@@ -540,8 +811,20 @@ export declare interface WriteFormatOptions {
     encoders?: Record<string, WriteFormatEncoder>;
 }
 
+/**
+ * Writes a single output entry to disk.
+ *
+ * @param o - Output entry to write.
+ * @param options - Writing behavior configuration.
+ * @returns Promise resolved when output is processed.
+ * @throws - When class requirements fail or file operations fail.
+ * @public
+ */
 export declare const writeOutput: (o: Output, options?: WriteOutputOption) => Promise<void>;
 
+/**
+ * @public
+ */
 export declare interface WriteOutputOption {
     targetDirectory?: string;
     writing?: (output: Output) => boolean | undefined | void;
@@ -549,8 +832,19 @@ export declare interface WriteOutputOption {
     classRequired?: boolean;
 }
 
+/**
+ * Writes multiple outputs to disk.
+ *
+ * @param outputs - Output definitions to write.
+ * @param options - Writing behavior configuration.
+ * @returns Promise resolved when all outputs are processed.
+ * @public
+ */
 export declare const writeOutputs: (outputs: Output[], options?: WriteOutputsOption) => Promise<void>;
 
+/**
+ * @public
+ */
 export declare interface WriteOutputsOption extends WriteOutputOption {
     removeFirst?: boolean;
 }
@@ -579,28 +873,6 @@ declare global {
     }
 }
 
-declare global {
-    interface Array<T> {
-        mapAsync<U>(callback: (value: T, index: number, array: T[]) => Promise<U>): Promise<U[]>;
-        forEachAsync(callback: (value: T, index: number, array: T[]) => Promise<void>): Promise<void>;
-        sortBy<K extends keyof T>(selector: (item: T) => T[K], ascending?: boolean): T[];
-        unique(): T[];
-        uniqueBy<K extends keyof T>(selector: (item: T) => T[K]): T[];
-        groupBy<K extends keyof T>(selector: (item: T) => T[K]): Record<T[K] & (string | number | symbol), T[]>;
-        toObject<K extends keyof T, V>(keySelector: (item: T) => T[K], valueSelector?: (item: T) => V): Record<T[K] & (string | number | symbol), V>;
-        toObjectWithKey<K extends keyof T>(key: K): Record<string, T>;
-        nonNullMap<U>(callback: (value: T, index: number, array: T[]) => U | null | undefined): U[];
-        nonNullMapAsync<U>(callback: (value: T, index: number, array: T[]) => Promise<U | null | undefined>): Promise<U[]>;
-        findOrFail(predicate: (value: T, index: number, array: T[]) => boolean, message?: string, thisArg?: any): T;
-        selectFor<K>(predicate: (value: T, index: number, array: T[]) => boolean, selector: (value: T) => K, message?: string, thisArg?: any): K;
-        createInstances<TTarget>(targetConstructor: new (...args: any[]) => TTarget, ...args: any[]): TTarget[];
-        mergeAll(options?: MergeOptions): any;
-    }
-    interface ArrayConstructor {
-        flat<T>(v: T | T[] | T[][]): T[];
-    }
-}
-
 declare global {
     interface String {
         capitalize(): string;
@@ -628,3 +900,25 @@ declare global {
     }
 }
 
+declare global {
+    interface Array<T> {
+        mapAsync<U>(callback: (value: T, index: number, array: T[]) => Promise<U>): Promise<U[]>;
+        forEachAsync(callback: (value: T, index: number, array: T[]) => Promise<void>): Promise<void>;
+        sortBy<K extends keyof T>(selector: (item: T) => T[K], ascending?: boolean): T[];
+        unique(): T[];
+        uniqueBy<K extends keyof T>(selector: (item: T) => T[K]): T[];
+        groupBy<K extends keyof T>(selector: (item: T) => T[K]): Record<T[K] & (string | number | symbol), T[]>;
+        toObject<K extends keyof T, V>(keySelector: (item: T) => T[K], valueSelector?: (item: T) => V): Record<T[K] & (string | number | symbol), V>;
+        toObjectWithKey<K extends keyof T>(key: K): Record<string, T>;
+        nonNullMap<U>(callback: (value: T, index: number, array: T[]) => U | null | undefined): U[];
+        nonNullMapAsync<U>(callback: (value: T, index: number, array: T[]) => Promise<U | null | undefined>): Promise<U[]>;
+        findOrFail(predicate: (value: T, index: number, array: T[]) => boolean, message?: string, thisArg?: any): T;
+        selectFor<K>(predicate: (value: T, index: number, array: T[]) => boolean, selector: (value: T) => K, message?: string, thisArg?: any): K;
+        createInstances<TTarget>(targetConstructor: new (...args: any[]) => TTarget, ...args: any[]): TTarget[];
+        mergeAll(options?: MergeOptions): any;
+    }
+    interface ArrayConstructor {
+        flat<T>(v: T | T[] | T[][]): T[];
+    }
+}
+