creatium 0.0.5 → 0.1.0

package/dist/main.d.ts

@@ -9,6 +9,7 @@ import { globby, globbyStream } from 'globby';
 import { writeFile as writeFile$1, readFile as readFile$1 } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { Options as Options$2 } from 'yargs';
+import { UpdateNotifier } from 'update-notifier';
 
 /**
  * Any type
@@ -719,7 +720,12 @@ type CoreInterface<V = string> = {
      *
      * Used to validate initial value in prompt method
      */
-    validateInitialValue: () => Promise<V | undefined>;
+    validateInitialValue: (data: {
+        /** Show success message */
+        showSuccess?: boolean;
+        /** Show error message */
+        showError?: boolean;
+    }) => Promise<V | undefined>;
     /**
      * Method to set the cli option
      * @returns {Promise<CliOption | undefined>}
@@ -769,7 +775,10 @@ type OptionSelect<V extends Value$5 = Value$5> = OptionCommonWithPlaceholder<V>
 };
 declare class Select<V extends Value$5 = Value$5> extends Core<OptionSelect<V>, V> implements CoreInterface<Value$5> {
     cmd(): Promise<CliOption>;
-    validateInitialValue(): Promise<V | undefined>;
+    validateInitialValue(data?: {
+        showSuccess?: boolean;
+        showError?: boolean;
+    }): Promise<V | undefined>;
     prompt(): Promise<string>;
 }
 
@@ -797,20 +806,25 @@ type SelectBaseOptions<Value extends string = string> = Partial<Omit<OptionSelec
     };
 };
 
-declare const IDE: {
+/** Text editor values used in `openEditor` option. */
+declare const TEXT_EDITOR: {
     readonly VSCODE: "code";
     readonly SUBLIME: "subl";
     readonly WEBSTORM: "webstorm";
     readonly NONE: "none";
 };
-type TextEditor = ObjectValues<typeof IDE>;
+type TextEditor = ObjectValues<typeof TEXT_EDITOR>;
 type OptionEditor = SelectBaseOptions<TextEditor>;
 declare class Editor extends Select<TextEditor> {
     constructor(config: OptionEditor);
-    validateInitialValue(): Promise<TextEditor | undefined>;
+    validateInitialValue(data?: {
+        showSuccess?: boolean;
+        showError?: boolean;
+    }): Promise<TextEditor | undefined>;
     prompt(): Promise<TextEditor>;
 }
 
+/** installer values used in `install` option. */
 declare const INSTALLER: {
     readonly NONE: "none";
     readonly DENO: "deno";
@@ -819,12 +833,15 @@ declare const INSTALLER: {
     readonly PNPM: "pnpm";
     readonly YARN: "yarn";
 };
-type PkgManager = ObjectValues<typeof INSTALLER>;
-type OptionInstall = SelectBaseOptions<PkgManager>;
-declare class Install extends Select<PkgManager> {
+type Installer = ObjectValues<typeof INSTALLER>;
+type OptionInstall = SelectBaseOptions<Installer>;
+declare class Install extends Select<Installer> {
     constructor(config: OptionInstall);
-    validateInitialValue(): Promise<PkgManager | undefined>;
-    prompt(): Promise<PkgManager>;
+    validateInitialValue(data?: {
+        showSuccess?: boolean;
+        showError?: boolean;
+    }): Promise<Installer | undefined>;
+    prompt(): Promise<Installer>;
 }
 
 /** Object of the CREATIUM types */
@@ -855,7 +872,10 @@ type OptionArray = OptionCommonWithPlaceholder<Value$4> & {
 declare class Array extends Core<OptionArray, Value$4> implements CoreInterface<Value$4> {
     #private;
     cmd(): Promise<CliOption>;
-    validateInitialValue(): Promise<Value$4 | undefined>;
+    validateInitialValue(data?: {
+        showSuccess?: boolean;
+        showError?: boolean;
+    }): Promise<Value$4 | undefined>;
     prompt(): Promise<string[]>;
 }
 
@@ -863,7 +883,10 @@ type Value$3 = boolean;
 type OptionBoolean = OptionCommonWithPlaceholder<Value$3>;
 declare class Boolean extends Core<OptionBoolean, Value$3> implements CoreInterface<Value$3> {
     cmd(): Promise<CliOption>;
-    validateInitialValue(): Promise<boolean | undefined>;
+    validateInitialValue(data?: {
+        showSuccess?: boolean;
+        showError?: boolean;
+    }): Promise<boolean | undefined>;
     prompt(): Promise<boolean>;
 }
 
@@ -881,7 +904,10 @@ type OptionMultiselect<V extends Value$2 = Value$2> = OptionCommonWithPlaceholde
 };
 declare class Multiselect<V extends Value$2 = Value$2> extends Core<OptionMultiselect<V>, V[]> implements CoreInterface<V[]> {
     cmd(): Promise<CliOption>;
-    validateInitialValue(): Promise<V[] | undefined>;
+    validateInitialValue(data?: {
+        showSuccess?: boolean;
+        showError?: boolean;
+    }): Promise<V[] | undefined>;
     prompt(): Promise<string[]>;
 }
 
@@ -889,7 +915,10 @@ type Value$1 = number;
 type OptionNumber = OptionCommonWithPlaceholder<Value$1>;
 declare class Number extends Core<OptionNumber, Value$1> implements CoreInterface<Value$1> {
     cmd(): Promise<CliOption>;
-    validateInitialValue(): Promise<number | undefined>;
+    validateInitialValue(data?: {
+        showSuccess?: boolean;
+        showError?: boolean;
+    }): Promise<number | undefined>;
     prompt(): Promise<number>;
 }
 
@@ -897,7 +926,10 @@ type Value = string;
 type OptionText = OptionCommonWithPlaceholder<Value>;
 declare class Text extends Core<OptionText, Value> implements CoreInterface<Value> {
     cmd(): Promise<CliOption>;
-    validateInitialValue(): Promise<string | undefined>;
+    validateInitialValue(data?: {
+        showSuccess?: boolean;
+        showError?: boolean;
+    }): Promise<string | undefined>;
     prompt(): Promise<string>;
 }
 
@@ -913,7 +945,10 @@ declare class Void extends Core<OptionVoid, void> implements CoreInterface<void>
 type OptionName = Partial<Name['config']>;
 declare class Name extends Text {
     constructor(config: OptionName);
-    validateInitialValue(): Promise<string | undefined>;
+    validateInitialValue(data?: {
+        showSuccess?: boolean;
+        showError?: boolean;
+    }): Promise<string | undefined>;
     prompt(): Promise<string>;
 }
 
@@ -937,7 +972,10 @@ type OptionPath = Partial<Path['config']> & {
 declare class Path extends Text {
     #private;
     constructor(config: OptionPath);
-    validateInitialValue(): Promise<string | undefined>;
+    validateInitialValue(data?: {
+        showSuccess?: boolean;
+        showError?: boolean;
+    }): Promise<string | undefined>;
     prompt(): Promise<string>;
 }
 
@@ -1044,7 +1082,7 @@ type CreateTemplateOpts = {
     /** Set the name of the template */
     name?: string;
     /** Set the installer */
-    install?: PkgManager;
+    install?: Installer;
     /**
      * Open editor
      */
@@ -1137,6 +1175,69 @@ type CreateOpts = CliOpts & {
     activeCli?: boolean;
 };
 
+type ParamFn = (arg: string) => Promise<string>;
+type ParamsValue = string | number | Record<string, unknown> | unknown[] | unknown;
+type Params = Record<string, ParamsValue>;
+type Props = {
+    /** Content to be replaced */
+    content: string;
+    /**
+     * Parameters
+     * @example
+     * const params = {
+     *     name: 'Antonio',
+     *     lastName : 'Resines'
+     * }
+     */
+    params: Params;
+    /**
+     * Transform parameters insde placeholders.
+     * @example
+     * const transform = async ( param: string ) => {
+     *     if ( param === 'url' ) return 'https://pigeonposse.com',
+     *     else if ( param === 'http://pigeonposse.com' ) return 'https://pigeonposse.com'
+     *     return param
+     * }
+     */
+    transform?: ParamFn;
+    /** Options */
+    opts?: {
+        /**
+         * Throw an error if a placeholder is not found.
+         * @default false
+         */
+        throw?: boolean;
+        /**
+         * Throw an error if a parameter is not found.
+         * @default
+         * {
+         *   prefix : '{{',
+         *   suffix : '}}',
+         * }
+         */
+        mark?: {
+            prefix: string;
+            suffix: string;
+        };
+    };
+};
+/**
+ * Replace placeholders in a string with their corresponding values.
+ *
+ * The function takes a string with placeholders, an object with parameter values,
+ * and an optional custom parameter function.
+ *
+ * The function returns a Promise that resolves to the string with all placeholders
+ * replaced.
+ * @param {Props} props - Props for the function.
+ * @param {Props['content']} props.content - The string with placeholders.
+ * @param {Props['params']} props.params - An object with parameter values.
+ * @param {Props['transform']} [props.transform] - An optional custom parameter function.
+ * @param {Props['opts']} [props.opts] - Options to customize the behavior of the function.
+ * @returns {Promise<string>} - A Promise that resolves to the string with all placeholders replaced.
+ */
+declare const replacePlaceholders: (props: Props) => Promise<string>;
+
 type GetPromptValues<C extends Config> = Prettify<{
     [K in keyof C['prompt']]?: Prettify<(C['prompt'][K] extends {
         type: infer T;
@@ -1147,9 +1248,9 @@ type GetPromptValues<C extends Config> = Prettify<{
  * Customizable class of `Creatium` for create project templates (CLI and Library).
  * @template C
  * @example
- * //////////////// main.js ///////////////////
+ * //////////////// core.js ///////////////////
  *
- * const core = new CreatiumPrompt({
+ * export const core = new CreatiumCore({
  *   name: 'My Project',
  *   version: '1.0.0',
  *   prompts: {
@@ -1160,27 +1261,162 @@ type GetPromptValues<C extends Config> = Prettify<{
  *
  * //////////////// bin.js ///////////////////
  *
- * import { core } from './main.js'
+ * import { core } from './core.js'
  * const res = await core.cli()
  * // do something with res...
  * await core.createTemplate( res )
  *
  * //////////////// lib.js ///////////////////
  *
- * import { core } from './main.js'
+ * import { core } from './core.js'
  * export const create = async (args) => {
  *   const res = await core.build( args )
  *   // do something with res...
  *   await core.createTemplate( res )
  * }
  */
-declare class CreatiumPrompt<C extends Config = Config> {
+declare class CreatiumCore<C extends Config = Config> {
     #private;
     utils: typeof ___shared_utils;
     config: C;
     constructor(config: C);
     /** Force debug mode */
     set debugMode(value: boolean);
+    /**
+     * Shows a notification if the current package is outdated.
+     *
+     * **information**: If this 'custom' function is provided, the default
+     * notification will not be shown.
+     *
+     * ---
+     * @param {object} [opts] - Options for the update notification.
+     * @param {object} [opts.opts] - Options for the `update-notifier` package.
+     * @param {Function} [opts.custom] - A custom function to run with the update
+     * @example
+     * // With default options. Recommended for most use cases.
+     * await core.updateNotify()
+     * @example
+     * // With custom options
+     * await core.updateNotify({ opts: { ... } })
+     * @example
+     * // With custom function
+     * await core.updateNotify({ custom: () => {} })
+     */
+    updateNotify({ custom, opts, }?: {
+        opts?: Parameters<UpdateNotifier['notify']>[0];
+        custom?: (info?: UpdateNotifier['update']) => Response<void>;
+    }): Promise<void>;
+    /**
+     * Cancels the current process and exits with code 0.
+     *
+     * If a `message` is provided, it will be displayed in the console.
+     * If `onCancel` is set in the config, it will be called with the current data.
+     * If `onCancel` is not set, a default message will be displayed.
+     * @param {string} [message] - The message to display before exiting.
+     */
+    cancel(message?: string): Promise<void>;
+    /**
+     * Intro prompt line.
+     *
+     * If the parameter `message` is provided, it will be used as the intro message.
+     * If the `intro` option is a function, it will be called with the `this.#data` as the argument.
+     * If the `intro` option is undefined, the default intro message will be used.
+     * @param {string} [message] The intro message.
+     */
+    intro(message?: string): Promise<void>;
+    /**
+     * Outro prompt line.
+     *
+     * If the parameter `message` is provided, it will be used as the outro message.
+     * If the `outro` option is a function, it will be called with the `this.#data` as the argument.
+     * If the `outro` option is undefined, the default outro message will be used.
+     * @param {string} [message] The outro message.
+     */
+    outro(message?: string): Promise<void>;
+    /**
+     * Copy a directory from input path to output path.
+     * @param {object} data - Options object with input and output paths.
+     * @param {string} data.input  - The path to the directory to copy.
+     * @param {string} data.output - The path to the destination directory.
+     * @returns {Promise<void>}    - Resolves when the directory has been copied.
+     * @example
+     *
+     * const copyResult = await core.copyDir({
+     *   input : '/path/to/sourceDir',
+     *   output: '/path/to/destinationDir',
+     * })
+     */
+    copyDir(data: {
+        input: string;
+        output: string;
+    }): Promise<void>;
+    /**
+     * Installs the project with the given package manager.
+     * @param {object} [options] - The options to install.
+     * @param {Installer} [options.installer] - The package manager to use for the installation.
+     * @param {string} [options.input] - The path to the folder. If not provided, the current directory is used.
+     * @returns {Promise<void>}
+     * @example
+     * await core.install( {
+     *   installer : 'pnpm',
+     *   input     : 'my/project/path',
+     * } )
+     */
+    install({ installer, input, }?: {
+        installer?: Installer;
+        input?: string;
+    }): Promise<void>;
+    /**
+     * Open the project in the given editor.
+     * @param {object} params - The parameters for opening the editor.
+     * @param {TextEditor} params.editor - The editor to open the project in.
+     * @param {string} params.input - The input path. If not provided, the current directory is used.
+     * @returns {Promise<void>}
+     * @example
+     * await core.openEditor( {
+     *   editor : 'vscode',
+     *   input  : 'my/project/path',
+     *  })
+     */
+    openEditor({ editor, input, }?: {
+        editor?: TextEditor;
+        input?: string;
+    }): Promise<void>;
+    /**
+     * Replaces placeholders in files within the specified directory.
+     *
+     * This function searches for files in the provided input directory and replaces
+     * placeholders within those files using the specified parameters. The placeholders
+     * in the content are replaced with values from the `params` object.
+     * @param {object} args - The arguments object.
+     * @param {string} [args.input] - The directory path containing files with placeholders.
+     * @param {object} [args.params] - An object containing key-value pairs for replacing placeholders.
+     * @returns {Promise<void>} A Promise that resolves once all placeholders have been replaced.
+     * @example
+     * await core.replacePlaceholders( {
+     *   input  : 'my/project/path',
+     *   params : { placeholder1: 'value1', placeholder2: 'value2' },
+     * })
+     */
+    replacePlaceholders({ input, params, }?: {
+        input?: string;
+        params?: Parameters<typeof replacePlaceholders>[0]['params'];
+    }): Promise<void>;
+    /**
+     * Return the input path of a template by name or path.
+     * @param {string} [input] The name of the template or the path to the template.
+     * @returns {Promise<string | undefined>} The input path of the template or undefined if not found.
+     * @example
+     * // with template path
+     * const input = await core.getTemplateInput( { input : 'my/template/path' } )
+     * @example
+     * // With template key
+     * // template key must be specified in the config prompt secction.
+     * const input = await core.getTemplateInput( { input : 'templateKey' )
+     */
+    getTemplateInput({ input }?: {
+        input?: string;
+    }): Promise<string | undefined>;
     /**
      * Create a new project template.
      * @param {CreateTemplateOpts} values - The values to create the template.
@@ -1242,22 +1478,25 @@ declare class CreatiumPrompt<C extends Config = Config> {
 /**
  * Class of `Creatium` for create project templates (CLI and Library).
  * @example
- * // ./main.js
- * export const core = new CreatiumPrompt({
+ * //////////////// core.js ///////////////////
+ *
+ * import { Creatium } from 'creatium'
+ * export const core = new Creatium({
  *   name: 'My Project',
  *   version: '1.0.0',
- *   prompts: {
+ *   templates: {
  *     ...
  *   },
- *   ...
  * })
  *
- * // ./bin.js
- * import { core } from './main.js'
+ * //////////////// bin.js ///////////////////
+ *
+ * import { core } from './core.js'
  * core.cli()
  *
- * // ./lib.js
- * import { core } from './main.js'
+ * //////////////// lib.js ///////////////////
+ *
+ * import { core } from './core.js'
  * export const create = core.build
  */
 declare class Creatium {
@@ -1339,4 +1578,4 @@ declare class Creatium {
     }>;
 }
 
-export { type CliOpts, type Config, type CreateOpts, type CreateTemplateOpts, Creatium, CreatiumPrompt, IDE, INSTALLER, OPTION, env, prompt, style, sys };
+export { type CliOpts, type Config, type CreateOpts, type CreateTemplateOpts, Creatium, CreatiumCore, INSTALLER, OPTION, TEXT_EDITOR, env, prompt, style, sys };