@kubb/core 1.1.13 → 1.2.1

package/dist/index.d.ts

@@ -1,7 +1,23 @@
 import { Ora } from 'ora';
 import { DirectoryTreeOptions } from 'directory-tree';
+export { default as pc } from 'picocolors';
+
+type LogType = 'error' | 'info' | 'warning';
+type Logger = {
+    log: (message: string | null) => void;
+    error: (message: string | null) => void;
+    info: (message: string | null) => void;
+    warn: (message: string | null) => void;
+    spinner?: Ora;
+};
+declare function createLogger(spinner?: Ora): Logger;
+declare function canLogHierarchy(input: LogLevels | undefined, compareTo: LogLevels): boolean;
 
-declare function isPromise<T>(result: MaybePromise<T>): result is Promise<T>;
+declare function isPromise<T>(result: PossiblePromise<T>): result is Promise<T>;
+declare function isPromiseFulfilledResult<T = unknown>(result: PromiseSettledResult<unknown>): result is PromiseFulfilledResult<T>;
+declare function isPromiseRejectedResult<T>(result: PromiseSettledResult<unknown>): result is Omit<PromiseRejectedResult, 'reason'> & {
+    reason: T;
+};
 
 declare function write(data: string, path: string): Promise<void>;
 
@@ -45,12 +61,17 @@ declare function timeout(ms: number): Promise<unknown>;
 type QueueTask<T = unknown> = {
     (...args: unknown[]): Promise<T> | Promise<void>;
 };
+type RunOptions = {
+    name: string;
+    description: string;
+};
 declare class Queue {
     private readonly queue;
     workerCount: number;
     private maxParallel;
-    constructor(maxParallel: number);
-    run<T>(task: QueueTask<T>): Promise<T>;
+    private debug;
+    constructor(maxParallel: number, debug?: boolean);
+    run<T>(task: QueueTask<T>, options?: RunOptions): Promise<T>;
     private work;
 }
 
@@ -80,8 +101,43 @@ declare function getStackTrace(belowFn?: Function): NodeJS.CallSite[];
 
 declare const uniqueId: (str?: string) => string;
 
+/**
+ * Normalizes directories to have a trailing slash.
+ * Resolve is pretty finicky -- if the directory name doesn't have
+ * a trailing slash then it tries to look in the parent directory.
+ * i.e., if the directory is "/usr/nzakas/foo" it will start the
+ * search in /usr/nzakas. However, if the directory is "/user/nzakas/foo/",
+ * then it will start the search in /user/nzakas/foo.
+ * @param {string} directory The directory to check.
+ * @returns {string} The normalized directory.
+ */
+declare function normalizeDirectory(directory: string): string;
+declare function getLocation(path: string, cwd?: string): string;
+declare function importModule(path: string, cwd?: string): Promise<any | undefined>;
+
 declare const throttle: <R, A extends any[]>(fn: (...args: A) => R, delay: number) => [(...args: A) => R | undefined, () => void];
 
+declare class SummaryError extends Error {
+    summary: string[];
+    constructor(message: string, options: {
+        cause: Error;
+        summary?: string[];
+    });
+}
+
+/**
+ * Behaves as an Error to log a warning in the console(still stops the execution)
+ */
+declare class Warning extends Error {
+    constructor(message?: string, options?: {
+        cause: Error;
+    });
+}
+
+declare const defaultColours: readonly ["black", "blue", "darkBlue", "cyan", "gray", "green", "darkGreen", "magenta", "red", "darkRed", "yellow", "darkYellow"];
+declare function randomColour(text?: string, colours?: readonly ["black", "blue", "darkBlue", "cyan", "gray", "green", "darkGreen", "magenta", "red", "darkRed", "yellow", "darkYellow"]): string;
+declare function randomPicoColour(text?: string, colors?: readonly ["black", "blue", "darkBlue", "cyan", "gray", "green", "darkGreen", "magenta", "red", "darkRed", "yellow", "darkYellow"]): string;
+
 type Import = {
     name: string | string[];
     path: string;
@@ -93,6 +149,8 @@ type Export = {
     isTypeOnly?: boolean;
     asAlias?: boolean;
 };
+type UUID = string;
+type Source = string;
 type File = {
     /**
      * Name to be used to dynamicly create the fileName(based on input.path)
@@ -101,8 +159,8 @@ type File = {
     /**
      * Path will be full qualified path to a specified file
      */
-    path: string;
-    source: string;
+    path: Path;
+    source: Source;
     imports?: Import[];
     exports?: Export[];
     /**
@@ -113,40 +171,45 @@ type File = {
     meta?: {
         pluginName?: string;
     };
+    /**
+     * This will override `process.env[key]` inside the `source`, see `getFileSource`.
+     */
+    env?: NodeJS.ProcessEnv;
 };
-type UUID = string;
-type CacheStore = {
+type ResolvedFile = File & {
+    /**
+     * crypto.randomUUID()
+     */
     id: UUID;
-    file: File;
-    status: Status;
 };
 type Status = 'new' | 'success' | 'removed';
 
+declare function writeIndexes(root: string, options?: TreeNodeOptions): File[] | null;
+declare function combineFiles(files: Array<File | null>): File[];
+type Extension = '.ts' | '.js';
+declare const extensions: Array<Extension>;
+declare function getFileSource(file: File): string;
+
 declare class FileManager {
     private cache;
     private task?;
     private queue?;
     constructor(options?: {
         queue: Queue;
-        task?: QueueTask<File>;
+        task?: QueueTask<ResolvedFile>;
     });
-    private getCache;
-    getCacheByPath(path: string | undefined): CacheStore | undefined;
+    get extensions(): Extension[];
     get files(): File[];
-    get cachedFiles(): CacheStore[];
-    add(file: File): Promise<File>;
-    addOrAppend(file: File): Promise<File>;
-    setStatus(id: UUID, status: Status): void;
-    get(id: UUID): File | undefined;
-    remove(id: UUID): void;
+    add(file: File): Promise<ResolvedFile>;
+    addOrAppend(file: File): Promise<ResolvedFile>;
+    private append;
+    getCacheByUUID(UUID: UUID): File | undefined;
+    get(path: Path): File[] | undefined;
+    remove(path: Path): void;
     write(...params: Parameters<typeof write>): Promise<void>;
     read(...params: Parameters<typeof read>): Promise<string>;
 }
 
-declare function writeIndexes(root: string, options?: TreeNodeOptions): File[] | null;
-declare function combineFiles(files: Array<File | null>): File[];
-declare function getFileSource(file: File): string;
-
 /**
  * Get the type of the first argument in a function.
  * @example Arg0<(a: string, b: number) => void> -> string
@@ -157,6 +220,8 @@ type Executer<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
     strategy: Strategy;
     hookName: H;
     plugin: KubbPlugin;
+    input?: unknown[] | undefined;
+    output?: unknown;
 };
 type OnExecute<H extends PluginLifecycleHooks = PluginLifecycleHooks> = (this: PluginManager, executer: Executer<H> | undefined, pluginManager: PluginManager) => void;
 type ParseResult<H extends PluginLifecycleHooks> = PluginLifecycle[H];
@@ -165,9 +230,11 @@ type SafeParseResult<H extends PluginLifecycleHooks, Result = ReturnType<ParseRe
     plugin: KubbPlugin;
 };
 
-declare const hooks: [keyof PluginLifecycle<PluginFactoryOptions<unknown, false, any, Record<string, any>>>];
+declare const hooks: [keyof PluginLifecycle<PluginFactoryOptions<string, unknown, false, any, Record<string, any>>>];
 type Options$1 = {
-    task: QueueTask<File>;
+    debug?: boolean;
+    task: QueueTask<ResolvedFile>;
+    logger: Logger;
     onExecute?: OnExecute<PluginLifecycleHooks>;
 };
 declare class PluginManager {
@@ -176,10 +243,9 @@ declare class PluginManager {
     private readonly onExecute?;
     private readonly core;
     queue: Queue;
-    executer: Executer | undefined;
     executed: Executer[];
+    logger: Logger;
     constructor(config: KubbConfig, options: Options$1);
-    getExecuter(): Executer | undefined;
     resolvePath: (params: ResolvePathParams) => OptionalPath;
     resolveName: (params: ResolveNameParams) => string | null;
     load: (id: string) => Promise<SafeParseResult<"load">>;
@@ -230,7 +296,7 @@ declare class PluginManager {
     hookReduceArg0<H extends PluginLifecycleHooks>({ hookName, parameters, reduce, }: {
         hookName: H;
         parameters: Parameters<PluginLifecycle[H]>;
-        reduce: (reduction: Argument0<H>, result: ReturnType<ParseResult<H>>, plugin: KubbPlugin) => MaybePromise<Argument0<H> | null>;
+        reduce: (reduction: Argument0<H>, result: ReturnType<ParseResult<H>>, plugin: KubbPlugin) => PossiblePromise<Argument0<H> | null>;
     }): Promise<Argument0<H>>;
     /**
      * Chains plugins
@@ -241,7 +307,7 @@ declare class PluginManager {
     }): Promise<void>;
     private getSortedPlugins;
     getPlugin(hookName: keyof PluginLifecycle, pluginName: string): KubbPlugin;
-    private addExecuter;
+    private addExecutedToCallStack;
     /**
      * Run an async plugin hook and return the result.
      * @param hookName Name of the plugin hook. Must be either in `PluginHooks` or `OutputPluginValueHooks`.
@@ -266,8 +332,9 @@ declare function validatePlugins(plugins: KubbPlugin[], dependedPluginNames: str
 
 declare class PluginError extends Error {
     pluginManager: PluginManager;
+    cause: Error;
     constructor(message: string, options: {
-        cause?: Error;
+        cause: Error;
         pluginManager: PluginManager;
     });
 }
@@ -280,19 +347,12 @@ declare class ParallelPluginError extends Error {
         errors: PluginError[];
         pluginManager: PluginManager;
     });
-}
-
-declare class SummaryError extends Error {
-    summary: string[];
-    constructor(message: string, options: {
-        cause: Error;
-        summary?: string[];
-    });
+    findError<T extends Error = Error>(searchError: T): T | undefined;
 }
 
 interface Register {
 }
-type MaybePromise<T> = Promise<T> | T;
+type PossiblePromise<T> = Promise<T> | T;
 /**
  * Config used in `kubb.config.js`
  *
@@ -313,7 +373,7 @@ type KubbUserConfig = Omit<KubbConfig, 'root' | 'plugins'> & {
      * Example: ['@kubb/swagger', { output: false }]
      * Or: createSwagger({ output: false })
      */
-    plugins?: KubbPlugin[] | KubbJSONPlugin[] | KubbObjectPlugin;
+    plugins?: KubbPlugin[] | KubbJSONPlugins[] | KubbObjectPlugins;
 };
 /**
  * Global/internal config used through out the full generation.
@@ -365,10 +425,15 @@ type KubbConfig = {
     };
     /**
      * Log level to report when using the CLI
-     * Under construction, only info is implemented.
+     *
+     * `silent` will hide all information that is not relevant
+     *
+     * `info` will show all information possible(not related to the PluginManager)
+     *
+     * `stacktrace` will show all information possible(related to the PluginManager), handy for seeing logs
      * @default `silent`
      */
-    logLevel?: LogLevel;
+    logLevel?: LogLevels;
 };
 type CLIOptions = {
     /**
@@ -391,7 +456,7 @@ type CLIOptions = {
      * Override `logLevel` defined in `kubb.config.js`
      * @default `'silent'`
      */
-    logLevel?: LogLevel;
+    logLevel?: LogLevels;
     init?: unknown;
 };
 type BuildOutput = {
@@ -399,16 +464,21 @@ type BuildOutput = {
     pluginManager: PluginManager;
 };
 type KubbPluginKind = 'schema' | 'controller';
-type KubbJSONPlugin = [plugin: keyof Register | string, options: Register[keyof Register] | object];
-type KubbObjectPlugin = {
+type KubbJSONPlugins = [plugin: keyof Register | string, options: Register[keyof Register] | object];
+type KubbObjectPlugin = keyof Register;
+type KubbObjectPlugins = {
     [K in keyof Register]: Register[K] | object;
 };
-type KubbPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+type KubbUserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
     /**
      * Unique name used for the plugin
      * @example @kubb/typescript
      */
-    name: string;
+    name: PluginFactoryOptions['name'];
+    /**
+     * Options set for a specific plugin(see kubb.config.js), passthrough of options.
+     */
+    options?: TOptions['options'];
     /**
      * Kind/type for the plugin
      * Type 'schema' can be used for JSON schema's, TypeScript types, ...
@@ -417,15 +487,34 @@ type KubbPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> =
      */
     kind?: KubbPluginKind;
     /**
-     * Defined an api that can be used by other plugins
+     * Define an api that can be used by other plugins, see `PluginManager' where we convert from `KubbUserPlugin` to `KubbPlugin`(used when calling `createPlugin`).
      */
-    api?: TOptions['api'];
+    api?: (this: Omit<PluginContext, 'addFile'>) => TOptions['api'];
+} & Partial<PluginLifecycle<TOptions>>;
+type KubbPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
     /**
-     * Options set for a specific plugin(see kubb.config.js)
+     * Unique name used for the plugin
+     * @example @kubb/typescript
+     */
+    name: PluginFactoryOptions['name'];
+    /**
+     * Options set for a specific plugin(see kubb.config.js), passthrough of options.
      */
     options?: TOptions['options'];
+    /**
+     * Kind/type for the plugin
+     * Type 'schema' can be used for JSON schema's, TypeScript types, ...
+     * Type 'controller' can be used to create generate API calls, React-Query hooks, Axios controllers, ...
+     * @default undefined
+     */
+    kind?: KubbPluginKind;
+    /**
+     * Define an api that can be used by other plugins, see `PluginManager' where we convert from `KubbUserPlugin` to `KubbPlugin`(used when calling `createPlugin`).
+     */
+    api?: TOptions['api'];
 } & Partial<PluginLifecycle<TOptions>>;
-type PluginFactoryOptions<Options = unknown, Nested extends boolean = false, API = any, resolvePathOptions = Record<string, any>> = {
+type PluginFactoryOptions<Name = string, Options = unknown, Nested extends boolean = false, API = any, resolvePathOptions = Record<string, any>> = {
+    name: Name;
     options: Options;
     nested: Nested;
     api: API;
@@ -436,12 +525,12 @@ type PluginLifecycle<TOptions extends PluginFactoryOptions = PluginFactoryOption
      * Valdiate all plugins to see if their depended plugins are installed and configured.
      * @type hookParallel
      */
-    validate: (this: Omit<PluginContext, 'addFile'>, plugins: KubbPlugin[]) => MaybePromise<true>;
+    validate: (this: Omit<PluginContext, 'addFile'>, plugins: KubbPlugin[]) => PossiblePromise<true>;
     /**
      * Start of the lifecycle of a plugin.
      * @type hookParallel
      */
-    buildStart: (this: PluginContext, kubbConfig: KubbConfig) => MaybePromise<void>;
+    buildStart: (this: PluginContext, kubbConfig: KubbConfig) => PossiblePromise<void>;
     /**
      * Resolve to a Path based on a fileName(example: `./Pet.ts`) and directory(example: `./models`).
      * Options can als be included.
@@ -460,22 +549,22 @@ type PluginLifecycle<TOptions extends PluginFactoryOptions = PluginFactoryOption
      * Makes it possible to run async logic to override the path defined previously by `resolvePath`.
      * @type hookFirst
      */
-    load: (this: Omit<PluginContext, 'addFile'>, path: Path) => MaybePromise<TransformResult | null>;
+    load: (this: Omit<PluginContext, 'addFile'>, path: Path) => PossiblePromise<TransformResult | null>;
     /**
      * Transform the source-code.
      * @type hookReduceArg0
      */
-    transform: (this: Omit<PluginContext, 'addFile'>, source: string, path: Path) => MaybePromise<TransformResult>;
+    transform: (this: Omit<PluginContext, 'addFile'>, source: string, path: Path) => PossiblePromise<TransformResult>;
     /**
      * Write the result to the file-system based on the id(defined by `resolvePath` or changed by `load`).
      * @type hookParallel
      */
-    writeFile: (this: Omit<PluginContext, 'addFile'>, source: string | undefined, path: Path) => MaybePromise<void>;
+    writeFile: (this: Omit<PluginContext, 'addFile'>, source: string | undefined, path: Path) => PossiblePromise<void>;
     /**
      * End of the plugin lifecycle.
      * @type hookParallel
      */
-    buildEnd: (this: PluginContext) => MaybePromise<void>;
+    buildEnd: (this: PluginContext) => PossiblePromise<void>;
 };
 type PluginLifecycleHooks = keyof PluginLifecycle;
 type ResolvePathParams<TOptions = Record<string, any>> = {
@@ -507,6 +596,7 @@ type PluginContext<TOptions = Record<string, any>> = {
     resolvePath: (params: ResolvePathParams<TOptions>) => OptionalPath;
     resolveName: (params: ResolveNameParams) => string | null | undefined;
     load: (id: string) => Promise<SafeParseResult<'load'>>;
+    logger: Logger;
 };
 type TransformResult = string | null;
 /**
@@ -515,18 +605,20 @@ type TransformResult = string | null;
 type Path = string;
 type OptionalPath = Path | null | undefined;
 type FileName = string | null | undefined;
-type LogLevel = 'error' | 'info' | 'silent';
-
-type Logger<TParams = Record<string, any>> = {
-    log: (message: string | null, options: {
-        logLevel: LogLevel;
-        params?: TParams;
-    }) => void;
-    spinner?: Ora;
+declare const LogLevel: {
+    readonly silent: "silent";
+    readonly info: "info";
+    readonly stacktrace: "stacktrace";
 };
+type LogLevels = keyof typeof LogLevel;
+
 type BuildOptions = {
     config: PluginContext['config'];
+    /**
+     * @default Logger without the spinner
+     */
     logger?: Logger;
+    debug?: boolean;
 };
 declare function build(options: BuildOptions): Promise<BuildOutput>;
 
@@ -535,20 +627,20 @@ declare function build(options: BuildOptions): Promise<BuildOutput>;
  * accepts a direct {@link KubbConfig} object, or a function that returns it.
  * The function receives a {@link ConfigEnv} object that exposes two properties:
  */
-declare const defineConfig: (options: MaybePromise<KubbUserConfig> | ((cliOptions: CLIOptions) => MaybePromise<KubbUserConfig>)) => MaybePromise<KubbUserConfig> | ((cliOptions: CLIOptions) => MaybePromise<KubbUserConfig>);
+declare const defineConfig: (options: PossiblePromise<KubbUserConfig> | ((cliOptions: CLIOptions) => PossiblePromise<KubbUserConfig>)) => PossiblePromise<KubbUserConfig> | ((cliOptions: CLIOptions) => PossiblePromise<KubbUserConfig>);
 
-type KubbPluginFactory<T extends PluginFactoryOptions = PluginFactoryOptions> = (options: T['options']) => T['nested'] extends true ? Array<KubbPlugin<T>> : KubbPlugin<T>;
-declare function createPlugin<T extends PluginFactoryOptions = PluginFactoryOptions>(factory: KubbPluginFactory<T>): (options: T['options']) => T["nested"] extends true ? KubbPlugin<T>[] : KubbPlugin<T>;
+type KubbPluginFactory<T extends PluginFactoryOptions = PluginFactoryOptions> = (options: T['options']) => T['nested'] extends true ? Array<KubbUserPlugin<T>> : KubbUserPlugin<T>;
+declare function createPlugin<T extends PluginFactoryOptions = PluginFactoryOptions>(factory: KubbPluginFactory<T>): (options: T['options']) => T["nested"] extends true ? KubbUserPlugin<T>[] : KubbUserPlugin<T>;
 type Options = {
     config: PluginContext['config'];
     fileManager: FileManager;
     resolvePath: PluginContext['resolvePath'];
     resolveName: PluginContext['resolveName'];
     load: PluginContext['load'];
-    getExecuter: () => Executer<PluginLifecycleHooks> | undefined;
+    logger: PluginContext['logger'];
 };
-type CorePluginOptions = PluginFactoryOptions<Options, false, PluginContext>;
-declare const name: "core";
+type CorePluginOptions = PluginFactoryOptions<'core', Options, false, PluginContext>;
+declare const pluginName: CorePluginOptions['name'];
 
 /**
  * Abstract class that contains the building blocks for plugins to create their own Generator
@@ -568,4 +660,4 @@ declare abstract class SchemaGenerator<TOptions extends object, TInput, TOutput>
     abstract build(schema: TInput, name: string, description?: string): TOutput;
 }
 
-export { Argument0, BuildOutput, CLIOptions, Cache, CacheStore, CorePluginOptions, Executer, File, FileManager, FileName, Generator, KubbConfig, KubbJSONPlugin, KubbObjectPlugin, KubbPlugin, KubbPluginKind, KubbUserConfig, LogLevel, Logger, MaybePromise, OnExecute, OptionalPath, ParallelPluginError, ParseResult, Path, PathMode, PluginContext, PluginError, PluginFactoryOptions, PluginLifecycle, PluginLifecycleHooks, PluginManager, Queue, QueueTask, Register, ResolveNameParams, ResolvePathParams, SafeParseResult, SchemaGenerator, Status, Strategy, SummaryError, TransformResult, TreeNode, TreeNodeOptions, UUID, ValidationPluginError, build, clean, combineFiles, createJSDocBlockText, createPlugin, createPluginCache, build as default, defineConfig, getEncodedText, getFileSource, getPathMode, getRelativePath, getStackTrace, getUniqueName, hooks, isPromise, isURL, name, nameSorter, objectToParameters, read, renderTemplate, throttle, timeout, transformReservedWord, uniqueId, validatePlugins, write, writeIndexes };
+export { Argument0, BuildOutput, CLIOptions, Cache, CorePluginOptions, Executer, Extension, File, FileManager, FileName, Generator, KubbConfig, KubbJSONPlugins, KubbObjectPlugin, KubbObjectPlugins, KubbPlugin, KubbPluginKind, KubbUserConfig, KubbUserPlugin, LogLevel, LogLevels, LogType, Logger, OnExecute, OptionalPath, ParallelPluginError, ParseResult, Path, PathMode, PluginContext, PluginError, PluginFactoryOptions, PluginLifecycle, PluginLifecycleHooks, PluginManager, PossiblePromise, Queue, QueueTask, Register, ResolveNameParams, ResolvePathParams, ResolvedFile, SafeParseResult, SchemaGenerator, Source, Status, Strategy, SummaryError, TransformResult, TreeNode, TreeNodeOptions, UUID, ValidationPluginError, Warning, build, canLogHierarchy, clean, combineFiles, createJSDocBlockText, createLogger, createPlugin, createPluginCache, build as default, defaultColours, defineConfig, extensions, getEncodedText, getFileSource, getLocation, getPathMode, getRelativePath, getStackTrace, getUniqueName, hooks, importModule, isPromise, isPromiseFulfilledResult, isPromiseRejectedResult, isURL, pluginName as name, nameSorter, normalizeDirectory, objectToParameters, pluginName, randomColour, randomPicoColour, read, renderTemplate, throttle, timeout, transformReservedWord, uniqueId, validatePlugins, write, writeIndexes };