@kubb/core 2.0.0-beta.6 → 2.0.0-beta.7

package/dist/utils.d.cts

@@ -1,6 +1,6 @@
-import { Ora } from 'ora';
-import { PossiblePromise } from '@kubb/types';
+import { PossiblePromise, GreaterThan } from '@kubb/types';
 import { DirectoryTreeOptions } from 'directory-tree';
+import { Ora } from 'ora';
 export { default as pc } from 'picocolors';
 
 declare function getRelativePath(rootDir?: string | null, filePath?: string | null, platform?: 'windows' | 'mac' | 'linux'): string;
@@ -9,6 +9,25 @@ declare function readSync(path: string): string;
 
 declare function write(data: string, path: string): Promise<string | undefined>;
 
+type TreeNodeOptions = DirectoryTreeOptions;
+type BarrelData = {
+    type: KubbFile.Mode;
+    path: KubbFile.Path;
+    name: string;
+};
+declare class TreeNode<T = BarrelData> {
+    data: T;
+    parent?: TreeNode<T>;
+    children: Array<TreeNode<T>>;
+    constructor(data: T, parent?: TreeNode<T>);
+    addChild(data: T): TreeNode<T>;
+    find(data?: T): TreeNode<T> | null;
+    get leaves(): TreeNode<T>[];
+    get root(): TreeNode<T>;
+    forEach(callback: (treeNode: TreeNode<T>) => void): this;
+    static build(path: string, options?: TreeNodeOptions): TreeNode | null;
+}
+
 declare class EventEmitter<TEvents extends Record<string, any>> {
     #private;
     constructor();
@@ -26,13 +45,13 @@ type RunOptions = {
     name?: string;
     description?: string;
 };
-type Events = {
+type Events$1 = {
     jobDone: [result: unknown];
     jobFailed: [error: Error];
 };
 declare class Queue {
     #private;
-    readonly eventEmitter: EventEmitter<Events>;
+    readonly eventEmitter: EventEmitter<Events$1>;
     constructor(maxParallel: number, debug?: boolean);
     run<T>(job: QueueJob<T>, options?: RunOptions): Promise<T>;
     runSync<T>(job: QueueJob<T>, options?: RunOptions): void;
@@ -66,7 +85,497 @@ type Props = {
 };
 declare function createLogger({ logLevel, name, spinner }: Props): Logger;
 
+type RequiredPluginLifecycle = Required<PluginLifecycle>;
+/**
+ * Get the type of the first argument in a function.
+ * @example Arg0<(a: string, b: number) => void> -> string
+ */
+type Argument0<H extends keyof PluginLifecycle> = Parameters<RequiredPluginLifecycle[H]>[0];
+type Strategy = 'hookFirst' | 'hookForPlugin' | 'hookParallel' | 'hookReduceArg0' | 'hookSeq';
+type Executer<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
+    strategy: Strategy;
+    hookName: H;
+    plugin: KubbPlugin;
+    parameters?: unknown[] | undefined;
+    output?: unknown;
+};
+type ParseResult<H extends PluginLifecycleHooks> = RequiredPluginLifecycle[H];
+type SafeParseResult<H extends PluginLifecycleHooks, Result = ReturnType<ParseResult<H>>> = {
+    result: Result;
+    plugin: KubbPlugin;
+};
+type Options$1 = {
+    logger: Logger;
+    /**
+     * Task for the FileManager
+     */
+    task: QueueJob<KubbFile.ResolvedFile>;
+    /**
+     * Timeout between writes in the FileManager
+     */
+    writeTimeout?: number;
+};
+type Events = {
+    execute: [executer: Executer];
+    executed: [executer: Executer];
+    error: [error: Error];
+};
+declare class PluginManager {
+    #private;
+    readonly plugins: KubbPluginWithLifeCycle[];
+    readonly fileManager: FileManager;
+    readonly eventEmitter: EventEmitter<Events>;
+    readonly queue: Queue;
+    readonly config: KubbConfig;
+    readonly executed: Executer[];
+    readonly logger: Logger;
+    constructor(config: KubbConfig, options: Options$1);
+    resolvePath: <TOptions = object>(params: ResolvePathParams<TOptions>) => KubbFile.OptionalPath;
+    resolveName: (params: ResolveNameParams) => string;
+    on<TEventName extends keyof Events & string>(eventName: TEventName, handler: (...eventArg: Events[TEventName]) => void): void;
+    /**
+     * Run only hook for a specific plugin name
+     */
+    hookForPlugin<H extends PluginLifecycleHooks>({ pluginKey, hookName, parameters, }: {
+        pluginKey: KubbPlugin['key'];
+        hookName: H;
+        parameters: PluginParameter<H>;
+    }): Promise<Array<ReturnType<ParseResult<H>> | null>> | null;
+    hookForPluginSync<H extends PluginLifecycleHooks>({ pluginKey, hookName, parameters, }: {
+        pluginKey: KubbPlugin['key'];
+        hookName: H;
+        parameters: PluginParameter<H>;
+    }): Array<ReturnType<ParseResult<H>>> | null;
+    /**
+     * Chains, first non-null result stops and returns
+     */
+    hookFirst<H extends PluginLifecycleHooks>({ hookName, parameters, skipped, }: {
+        hookName: H;
+        parameters: PluginParameter<H>;
+        skipped?: ReadonlySet<KubbPlugin> | null;
+    }): Promise<SafeParseResult<H>>;
+    /**
+     * Chains, first non-null result stops and returns
+     */
+    hookFirstSync<H extends PluginLifecycleHooks>({ hookName, parameters, skipped, }: {
+        hookName: H;
+        parameters: PluginParameter<H>;
+        skipped?: ReadonlySet<KubbPlugin> | null;
+    }): SafeParseResult<H>;
+    /**
+     * Parallel, runs all plugins
+     */
+    hookParallel<H extends PluginLifecycleHooks, TOuput = void>({ hookName, parameters, }: {
+        hookName: H;
+        parameters?: Parameters<RequiredPluginLifecycle[H]> | undefined;
+    }): Promise<Awaited<TOuput>[]>;
+    /**
+     * Chains, reduces returned value, handling the reduced value as the first hook argument
+     */
+    hookReduceArg0<H extends PluginLifecycleHooks>({ hookName, parameters, reduce, }: {
+        hookName: H;
+        parameters: PluginParameter<H>;
+        reduce: (reduction: Argument0<H>, result: ReturnType<ParseResult<H>>, plugin: KubbPlugin) => PossiblePromise<Argument0<H> | null>;
+    }): Promise<Argument0<H>>;
+    /**
+     * Chains plugins
+     */
+    hookSeq<H extends PluginLifecycleHooks>({ hookName, parameters }: {
+        hookName: H;
+        parameters?: PluginParameter<H>;
+    }): Promise<void>;
+    getPluginsByKey(hookName: keyof PluginLifecycle, pluginKey: KubbPlugin['key']): KubbPlugin[];
+    static getDependedPlugins<T1 extends PluginFactoryOptions, T2 extends PluginFactoryOptions = never, T3 extends PluginFactoryOptions = never, TOutput = T3 extends never ? T2 extends never ? [T1: KubbPlugin<T1>] : [T1: KubbPlugin<T1>, T2: KubbPlugin<T2>] : [T1: KubbPlugin<T1>, T2: KubbPlugin<T2>, T3: KubbPlugin<T3>]>(plugins: Array<KubbPlugin>, dependedPluginNames: string | string[]): TOutput;
+    static get hooks(): readonly ["buildStart", "resolvePath", "resolveName", "load", "transform", "writeFile", "buildEnd"];
+}
+
+type BarrelManagerOptions = {
+    treeNode?: DirectoryTreeOptions;
+    isTypeOnly?: boolean;
+    /**
+     * Add .ts or .js
+     */
+    includeExt?: boolean;
+};
+
+type BasePath<T extends string = string> = `${T}/`;
+declare namespace KubbFile {
+    type Import = {
+        /**
+         * Import name to be used
+         * @example ["useState"]
+         * @example "React"
+         */
+        name: string | Array<string | {
+            propertyName: string;
+            name?: string;
+        }>;
+        /**
+         * Path for the import
+         * @xample '@kubb/core'
+         */
+        path: string;
+        /**
+         * Add `type` prefix to the import, this will result in: `import type { Type } from './path'`.
+         */
+        isTypeOnly?: boolean;
+        /**
+         * Add `* as` prefix to the import, this will result in: `import * as path from './path'`.
+         */
+        isNameSpace?: boolean;
+        /**
+         * When root is set it will get the path with relative getRelativePath(root, path).
+         */
+        root?: string;
+    };
+    type Export = {
+        /**
+         * Export name to be used.
+         * @example ["useState"]
+         * @example "React"
+         */
+        name?: string | Array<string>;
+        /**
+         * Path for the import.
+         * @xample '@kubb/core'
+         */
+        path: string;
+        /**
+         * Add `type` prefix to the export, this will result in: `export type { Type } from './path'`.
+         */
+        isTypeOnly?: boolean;
+        /**
+         * Make it possible to override the name, this will result in: `export * as aliasName from './path'`.
+         */
+        asAlias?: boolean;
+    };
+    const dataTagSymbol: unique symbol;
+    type DataTag<Type, Value> = Type & {
+        [dataTagSymbol]: Value;
+    };
+    type UUID = string;
+    type Source = string;
+    type Extname = '.ts' | '.js' | '.tsx' | '.json' | `.${string}`;
+    type Mode = 'file' | 'directory';
+    /**
+     * Name to be used to dynamicly create the baseName(based on input.path)
+     * Based on UNIX basename
+     * @link https://nodejs.org/api/path.html#pathbasenamepath-suffix
+     */
+    type BaseName = `${string}${Extname}`;
+    /**
+     * Path will be full qualified path to a specified file
+     */
+    type Path = string;
+    type AdvancedPath<T extends BaseName = BaseName> = `${BasePath}${T}`;
+    type OptionalPath = Path | undefined | null;
+    type FileMetaBase = {
+        pluginKey?: KubbPlugin['key'];
+    };
+    type File<TMeta extends FileMetaBase = FileMetaBase, TBaseName extends BaseName = BaseName> = {
+        /**
+         * Unique identifier to reuse later
+         * @default crypto.randomUUID()
+         */
+        id?: string;
+        /**
+         * Name to be used to create the path
+         * Based on UNIX basename, `${name}.extName`
+         * @link https://nodejs.org/api/path.html#pathbasenamepath-suffix
+         */
+        baseName: TBaseName;
+        /**
+         * Path will be full qualified path to a specified file
+         */
+        path: AdvancedPath<TBaseName> | Path;
+        source: Source;
+        imports?: Import[];
+        exports?: Export[];
+        /**
+         * This will call fileManager.add instead of fileManager.addOrAppend, adding the source when the files already exists
+         * This will also ignore the combinefiles utils
+         * @default `false`
+         */
+        override?: boolean;
+        /**
+         * Use extra meta, this is getting used to generate the barrel/index files.
+         */
+        meta?: TMeta;
+        /**
+         * This will override `process.env[key]` inside the `source`, see `getFileSource`.
+         */
+        env?: NodeJS.ProcessEnv;
+    };
+    type ResolvedFile<TMeta extends FileMetaBase = FileMetaBase, TBaseName extends BaseName = BaseName> = KubbFile.File<TMeta, TBaseName> & {
+        /**
+         * @default crypto.randomUUID()
+         */
+        id: UUID;
+        /**
+         * Contains the first part of the baseName, generated based on baseName
+         * @link  https://nodejs.org/api/path.html#pathformatpathobject
+         */
+        name: string;
+    };
+}
+type AddResult<T extends Array<KubbFile.File>> = Promise<Awaited<GreaterThan<T['length'], 1> extends true ? Promise<KubbFile.ResolvedFile[]> : Promise<KubbFile.ResolvedFile>>>;
+type AddIndexesProps = {
+    /**
+     * Root based on root and output.path specified in the config
+     */
+    root: string;
+    /**
+     * Output for plugin
+     */
+    output: string | {
+        path: string;
+        exportAs?: string;
+    };
+    extName?: KubbFile.Extname;
+    options?: BarrelManagerOptions;
+    meta?: KubbFile.File['meta'];
+};
+type Options = {
+    queue?: Queue;
+    task?: QueueJob<KubbFile.ResolvedFile>;
+    /**
+     * Timeout between writes
+     */
+    timeout?: number;
+};
+declare class FileManager {
+    #private;
+    constructor(options?: Options);
+    get files(): Array<KubbFile.File>;
+    get isExecuting(): boolean;
+    add<T extends Array<KubbFile.File> = Array<KubbFile.File>>(...files: T): AddResult<T>;
+    addIndexes({ root, output, extName, meta, options }: AddIndexesProps): Promise<Array<KubbFile.File> | undefined>;
+    getCacheByUUID(UUID: KubbFile.UUID): KubbFile.File | undefined;
+    get(path: KubbFile.Path): Array<KubbFile.File> | undefined;
+    remove(path: KubbFile.Path): void;
+    write(...params: Parameters<typeof write>): Promise<string | undefined>;
+    read(...params: Parameters<typeof read>): Promise<string>;
+    static getSource<TMeta extends KubbFile.FileMetaBase = KubbFile.FileMetaBase>(file: KubbFile.File<TMeta>): string;
+    static combineFiles<TMeta extends KubbFile.FileMetaBase = KubbFile.FileMetaBase>(files: Array<KubbFile.File<TMeta> | null>): Array<KubbFile.File<TMeta>>;
+    static getMode(path: string | undefined | null): KubbFile.Mode;
+    static get extensions(): Array<KubbFile.Extname>;
+    static isExtensionAllowed(baseName: string): boolean;
+}
+
+type InputPath = {
+    /**
+     * Path to be used as the input. This can be an absolute path or a path relative to the `root`.
+     */
+    path: string;
+};
+type InputData = {
+    /**
+     * `string` or `object` containing the data.
+     */
+    data: string | unknown;
+};
+type Input = InputPath | InputData;
+/**
+ * @private
+ */
+type KubbConfig<TInput = Input> = {
+    /**
+     * Optional config name to show in CLI output
+     */
+    name?: string;
+    /**
+     * Project root directory. Can be an absolute path, or a path relative from
+     * the location of the config file itself.
+     * @default process.cwd()
+     */
+    root: string;
+    input: TInput;
+    output: {
+        /**
+         * Path to be used to export all generated files.
+         * This can be an absolute path, or a path relative based of the defined `root` option.
+         */
+        path: string;
+        /**
+         * Clean output directory before each build.
+         */
+        clean?: boolean;
+        /**
+         * Write files to the fileSystem
+         * This is being used for the playground.
+         * @default true
+         */
+        write?: boolean;
+    };
+    /**
+     * Array of Kubb plugins to use.
+     * The plugin/package can forsee some options that you need to pass through.
+     * Sometimes a plugin is depended on another plugin, if that's the case you will get an error back from the plugin you installed.
+     */
+    plugins?: Array<KubbPlugin>;
+    /**
+     * Hooks that will be called when a specific action is triggered in Kubb.
+     */
+    hooks?: {
+        /**
+         * Hook that will be triggered at the end of all executions.
+         * Useful for running Prettier or ESLint to format/lint your code.
+         */
+        done?: string | Array<string>;
+    };
+};
+type PluginFactoryOptions<
+/**
+ * Name to be used for the plugin, this will also be used for they key.
+ */
+TName extends string = string, 
+/**
+ * Options of the plugin.
+ */
+TOptions extends object = object, 
+/**
+ * Options of the plugin that can be used later on, see `options` inside your plugin config.
+ */
+TResolvedOptions extends object = TOptions, 
+/**
+ * API that you want to expose to other plugins.
+ */
+TAPI = any, 
+/**
+ * When calling `resolvePath` you can specify better types.
+ */
+TResolvePathOptions extends object = object, 
+/**
+ * When using @kubb/react(based on React) you can specify here which types should be used when calling render.
+ * Always extend from `AppMeta` of the core.
+ */
+TAppMeta = unknown> = {
+    name: TName;
+    /**
+     * Same behaviour like what has been done with `QueryKey` in `@tanstack/react-query`
+     */
+    key: [name: TName | string, identifier?: string | number];
+    options: TOptions;
+    resolvedOptions: TResolvedOptions;
+    api: TAPI;
+    resolvePathOptions: TResolvePathOptions;
+    appMeta: {
+        pluginManager: PluginManager;
+        plugin: KubbPlugin<PluginFactoryOptions<TName, TOptions, TResolvedOptions, TAPI, TResolvePathOptions, TAppMeta>>;
+    } & TAppMeta;
+};
+type KubbPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+    /**
+     * Unique name used for the plugin
+     * @example @kubb/typescript
+     */
+    name: TOptions['name'];
+    /**
+     * Internal key used when a developer uses more than one of the same plugin
+     * @private
+     */
+    key: TOptions['key'];
+    /**
+     * Specifies the preceding plugins for the current plugin. You can pass an array of preceding plugin names, and the current plugin will be executed after these plugins.
+     * Can be used to validate depended plugins.
+     */
+    pre?: Array<string>;
+    /**
+     * Specifies the succeeding plugins for the current plugin. You can pass an array of succeeding plugin names, and the current plugin will be executed before these plugins.
+     */
+    post?: Array<string>;
+    /**
+     * Options set for a specific plugin(see kubb.config.js), passthrough of options.
+     */
+    options: TOptions['resolvedOptions'];
+} & (TOptions['api'] extends never ? {
+    api?: never;
+} : {
+    api: TOptions['api'];
+});
+type KubbPluginWithLifeCycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = KubbPlugin<TOptions> & PluginLifecycle<TOptions>;
+type PluginLifecycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+    /**
+     * Start of the lifecycle of a plugin.
+     * @type hookParallel
+     */
+    buildStart?: (this: PluginContext<TOptions>, kubbConfig: KubbConfig) => PossiblePromise<void>;
+    /**
+     * Resolve to a Path based on a baseName(example: `./Pet.ts`) and directory(example: `./models`).
+     * Options can als be included.
+     * @type hookFirst
+     * @example ('./Pet.ts', './src/gen/') => '/src/gen/Pet.ts'
+     */
+    resolvePath?: (this: PluginContext<TOptions>, baseName: string, directory?: string, options?: TOptions['resolvePathOptions']) => KubbFile.OptionalPath;
+    /**
+     * Resolve to a name based on a string.
+     * Useful when converting to PascalCase or camelCase.
+     * @type hookFirst
+     * @example ('pet') => 'Pet'
+     */
+    resolveName?: (this: PluginContext<TOptions>, name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string;
+    /**
+     * Makes it possible to run async logic to override the path defined previously by `resolvePath`.
+     * @type hookFirst
+     */
+    load?: (this: Omit<PluginContext<TOptions>, 'addFile'>, path: KubbFile.Path) => PossiblePromise<TransformResult | null>;
+    /**
+     * Transform the source-code.
+     * @type hookReduceArg0
+     */
+    transform?: (this: Omit<PluginContext<TOptions>, 'addFile'>, source: string, path: KubbFile.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<TOptions>, 'addFile'>, source: string | undefined, path: KubbFile.Path) => PossiblePromise<string | void>;
+    /**
+     * End of the plugin lifecycle.
+     * @type hookParallel
+     */
+    buildEnd?: (this: PluginContext<TOptions>) => PossiblePromise<void>;
+};
+type PluginLifecycleHooks = keyof PluginLifecycle;
+type PluginParameter<H extends PluginLifecycleHooks> = Parameters<Required<PluginLifecycle>[H]>;
 type PluginCache = Record<string, [number, unknown]>;
+type ResolvePathParams<TOptions = object> = {
+    pluginKey?: KubbPlugin['key'];
+    baseName: string;
+    directory?: string | undefined;
+    /**
+     * Options to be passed to 'resolvePath' 3th parameter
+     */
+    options?: TOptions;
+};
+type ResolveNameParams = {
+    name: string;
+    pluginKey?: KubbPlugin['key'];
+    /**
+     * `file` will be used to customize the name of the created file(use of camelCase)
+     * `function` can be used used to customize the exported functions(use of camelCase)
+     * `type` is a special type for TypeScript(use of PascalCase)
+     */
+    type?: 'file' | 'function' | 'type';
+};
+type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+    config: KubbConfig;
+    cache: Cache<PluginCache>;
+    fileManager: FileManager;
+    pluginManager: PluginManager;
+    addFile: (...file: Array<KubbFile.File>) => Promise<Array<KubbFile.File>>;
+    resolvePath: (params: ResolvePathParams<TOptions['resolvePathOptions']>) => KubbFile.OptionalPath;
+    resolveName: (params: ResolveNameParams) => string;
+    logger: Logger;
+    /**
+     * All plugins
+     */
+    plugins: KubbPlugin[];
+    /**
+     * Current plugin
+     */
+    plugin: KubbPlugin<TOptions>;
+};
+type TransformResult = string | null;
 
 interface Cache<TStore extends object = object> {
     delete(id: keyof TStore): boolean;
@@ -128,20 +637,6 @@ declare const throttle: <R, A extends any[]>(fn: (...args: A) => R, delay: numbe
 
 declare function timeout(ms: number): Promise<unknown>;
 
-type TreeNodeOptions = DirectoryTreeOptions;
-declare class TreeNode<T = unknown> {
-    data: T;
-    parent?: TreeNode<T>;
-    children: Array<TreeNode<T>>;
-    constructor(data: T, parent?: TreeNode<T>);
-    addChild(data: T): TreeNode<T>;
-    find(data?: T): TreeNode<T> | null;
-    get leaves(): TreeNode<T>[];
-    get root(): TreeNode<T>;
-    forEach(callback: (treeNode: TreeNode<T>) => void): this;
-    static build<T = unknown>(path: string, options?: TreeNodeOptions): TreeNode<T> | null;
-}
-
 declare function getUniqueName(originalName: string, data: Record<string, number>): string;
 declare function setUniqueName(originalName: string, data: Record<string, number>): string;