@kubb/core 1.2.0 → 1.2.2

package/dist/index.d.ts

@@ -11,8 +11,9 @@ type Logger = {
     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;
@@ -26,7 +27,7 @@ interface Cache<TStore extends object = object> {
     has(id: keyof TStore): boolean;
     set(id: keyof TStore, value: unknown): void;
 }
-declare function createPluginCache<TStore extends Record<string, [number, unknown]>>(Store: TStore): Cache<TStore>;
+declare function createPluginCache<TStore extends PluginCache>(Store?: TStore): Cache<TStore>;
 
 declare function getRelativePath(rootDir?: string | null, filePath?: string | null, platform?: 'windows' | 'mac' | 'linux'): string;
 type PathMode = 'file' | 'directory';
@@ -47,7 +48,7 @@ declare function objectToParameters(data: Data, options?: Options$2): string;
 
 declare function nameSorter<T extends {
     name: string;
-}>(a: T, b: T): 1 | -1 | 0;
+}>(a: T, b: T): 0 | 1 | -1;
 
 declare function createJSDocBlockText({ comments }: {
     comments: Array<string>;
@@ -60,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;
 }
 
@@ -89,7 +95,7 @@ declare class TreeNode<T = unknown> {
     static build<T = unknown>(path: string, options?: TreeNodeOptions): TreeNode<T> | null;
 }
 
-declare function transformReservedWord(word?: string | null): string | null | undefined;
+declare function transformReservedWord(word: string): string;
 
 declare function getStackTrace(belowFn?: Function): NodeJS.CallSite[];
 
@@ -128,6 +134,10 @@ declare class Warning extends 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;
@@ -139,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)
@@ -147,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[];
     /**
@@ -164,11 +176,11 @@ type File = {
      */
     env?: NodeJS.ProcessEnv;
 };
-type UUID = string;
-type CacheStore = {
+type ResolvedFile = File & {
+    /**
+     * crypto.randomUUID()
+     */
     id: UUID;
-    file: File;
-    status: Status;
 };
 type Status = 'new' | 'success' | 'removed';
 
@@ -184,18 +196,16 @@ declare class FileManager {
     private queue?;
     constructor(options?: {
         queue: Queue;
-        task?: QueueTask<File>;
+        task?: QueueTask<ResolvedFile>;
     });
-    private getCache;
     get extensions(): Extension[];
-    getCacheByPath(path: string | undefined): CacheStore | undefined;
     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>;
 }
@@ -210,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];
@@ -218,9 +230,10 @@ type SafeParseResult<H extends PluginLifecycleHooks, Result = ReturnType<ParseRe
     plugin: KubbPlugin;
 };
 
-declare const hooks: [keyof PluginLifecycle<PluginFactoryOptions<string, unknown, false, any, Record<string, any>>>];
+declare const hooks: [keyof PluginLifecycle<PluginFactoryOptions<string, unknown, false, any, Record<string, unknown>>>];
 type Options$1 = {
-    task: QueueTask<File>;
+    debug?: boolean;
+    task: QueueTask<ResolvedFile>;
     logger: Logger;
     onExecute?: OnExecute<PluginLifecycleHooks>;
 };
@@ -230,14 +243,12 @@ 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">>;
+    resolveName: (params: ResolveNameParams) => string;
+    load: (id: string) => Promise<SafeParseResult<'load'>>;
     /**
      *
      * Run only hook for a specific plugin name
@@ -285,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
@@ -296,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`.
@@ -341,7 +352,7 @@ declare class ParallelPluginError extends Error {
 
 interface Register {
 }
-type MaybePromise<T> = Promise<T> | T;
+type PossiblePromise<T> = Promise<T> | T;
 /**
  * Config used in `kubb.config.js`
  *
@@ -414,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 = {
     /**
@@ -432,15 +448,11 @@ type CLIOptions = {
      * Watch changes on input
      */
     watch?: string;
-    /**
-     * Override `input` defined in `kubb.config.js`
-     */
-    input?: string;
     /**
      * Override `logLevel` defined in `kubb.config.js`
      * @default `'silent'`
      */
-    logLevel?: LogLevel;
+    logLevel?: LogLevels;
     init?: unknown;
 };
 type BuildOutput = {
@@ -453,6 +465,28 @@ type KubbObjectPlugin = keyof Register;
 type KubbObjectPlugins = {
     [K in keyof Register]: Register[K] | object;
 };
+type KubbUserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+    /**
+     * 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?: (this: Omit<PluginContext, 'addFile'>) => TOptions['api'];
+} & Partial<PluginLifecycle<TOptions>>;
 type KubbPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
     /**
      * Unique name used for the plugin
@@ -471,11 +505,11 @@ 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'];
 } & Partial<PluginLifecycle<TOptions>>;
-type PluginFactoryOptions<Name = string, 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, unknown>> = {
     name: Name;
     options: Options;
     nested: Nested;
@@ -487,12 +521,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.
@@ -511,25 +545,26 @@ 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>> = {
+type PluginCache = Record<string, [number, unknown]>;
+type ResolvePathParams<TOptions = Record<string, unknown>> = {
     /**
      * When set, resolvePath will only call resolvePath of the name of the plugin set here.
      * If not defined it will fall back on the resolvePath of the core plugin.
@@ -550,13 +585,13 @@ type ResolveNameParams = {
     pluginName?: string;
     name: string;
 };
-type PluginContext<TOptions = Record<string, any>> = {
+type PluginContext<TOptions = Record<string, unknown>> = {
     config: KubbConfig;
-    cache: Cache;
+    cache: Cache<PluginCache>;
     fileManager: FileManager;
     addFile: (...file: File[]) => Promise<File[]>;
     resolvePath: (params: ResolvePathParams<TOptions>) => OptionalPath;
-    resolveName: (params: ResolveNameParams) => string | null | undefined;
+    resolveName: (params: ResolveNameParams) => string;
     load: (id: string) => Promise<SafeParseResult<'load'>>;
     logger: Logger;
 };
@@ -567,7 +602,12 @@ type TransformResult = string | null;
 type Path = string;
 type OptionalPath = Path | null | undefined;
 type FileName = string | null | undefined;
-type LogLevel = LogType | 'silent';
+declare const LogLevel: {
+    readonly silent: "silent";
+    readonly info: "info";
+    readonly stacktrace: "stacktrace";
+};
+type LogLevels = keyof typeof LogLevel;
 
 type BuildOptions = {
     config: PluginContext['config'];
@@ -575,6 +615,7 @@ type BuildOptions = {
      * @default Logger without the spinner
      */
     logger?: Logger;
+    debug?: boolean;
 };
 declare function build(options: BuildOptions): Promise<BuildOutput>;
 
@@ -583,10 +624,12 @@ 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 function defineConfig(options: PossiblePromise<KubbUserConfig> | ((
+/** The options derived from the CLI flags */
+cliOptions: CLIOptions) => PossiblePromise<KubbUserConfig>)): typeof options;
 
-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']) => ReturnType<KubbPluginFactory<T>>;
 type Options = {
     config: PluginContext['config'];
     fileManager: FileManager;
@@ -594,7 +637,6 @@ type Options = {
     resolveName: PluginContext['resolveName'];
     load: PluginContext['load'];
     logger: PluginContext['logger'];
-    getExecuter: () => Executer<PluginLifecycleHooks> | undefined;
 };
 type CorePluginOptions = PluginFactoryOptions<'core', Options, false, PluginContext>;
 declare const pluginName: CorePluginOptions['name'];
@@ -617,4 +659,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, Extension, File, FileManager, FileName, Generator, KubbConfig, KubbJSONPlugins, KubbObjectPlugin, KubbObjectPlugins, KubbPlugin, KubbPluginKind, KubbUserConfig, LogLevel, LogType, 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, Warning, build, clean, combineFiles, createJSDocBlockText, createLogger, createPlugin, createPluginCache, build as default, defineConfig, extensions, getEncodedText, getFileSource, getLocation, getPathMode, getRelativePath, getStackTrace, getUniqueName, hooks, importModule, isPromise, isPromiseFulfilledResult, isPromiseRejectedResult, isURL, pluginName as name, nameSorter, normalizeDirectory, objectToParameters, pluginName, 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, PluginCache, 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 };