juisy 2.0.0-beta.0 → 2.0.0-beta.10

package/dist/cli/types.d.ts

@@ -1,59 +1,84 @@
-import { Argv, CommandModule as YargsCommandModule, CommandBuilder, MiddlewareFunction } from 'yargs';
+import { Argv, CommandModule as YargsCommandModule, MiddlewareFunction } from 'yargs';
+import { Command } from './Command';
 /**
  * An object whose all properties have the same type.
  */
 type Dictionary<T = any> = {
     [key: string]: T;
 };
+/** ---------------------------- */
+/**
+ * @group Types
+ */
+export type DefaultCommandObject = {
+    fullSignature: string;
+    commandObject: Command;
+    children?: Array<DefaultCommandObject>;
+};
 /**
- * An array whose first element is not undefined.
+ * Provide a configuration object or an object with only "config" property
+ * @group Types
+ * @example
+ * {
+ *   config: 'path/to/config/file'
+ * }
  */
-type NotEmptyArray<T = any> = [T, ...T[]];
-/** Shims for private yargs types */
-interface Positional {
-    cmd: NotEmptyArray<string>;
-    variadic: boolean;
+export type UserProvidedConfigSetting<T> = {
+    /**
+     * The configuration file path
+     */
+    config: string;
+} | (T & {
+    config?: never;
+});
+/**
+ * CLI global settings
+ * @group Types
+ */
+export interface GlobalSettings {
+    [key: string]: any;
 }
-export interface YargsCommandHandler {
-    builder: CommandBuilder;
-    demanded: Positional[];
-    deprecated?: boolean;
-    description?: string | false;
-    handler: CommandModule['handler'];
-    middlewares: MiddlewareFunction[];
-    optional: Positional[];
-    original: string;
+/**
+ * The CLIFactory function options
+ * @group Types
+ */
+export interface CLIFactoryOptions {
+    /**
+     * The path to settings file
+     */
+    settingsPath?: string;
 }
-/** ---------------------------- */
 /**
  * Our custon extended Yargs type
+ * @group Types
  */
 export interface CLIEngine extends Argv {
     _isPrivate: boolean;
     _globalCommandVisitors: Record<string, CommandVisitor>;
     _globalCommandVisitorsEnabled: Set<string>;
-    _meta: Record<string, any> & {
-        private: boolean;
-    };
+    _disabledDefaultCommands: Set<string>;
+    _settings: Record<string, any>;
     originalCommand: Argv['command'];
-    globalCommandVisitor: (name: string, visitor: CommandVisitor, defaultOptions: any) => this;
-    globalCommandVisitorOptions: (name: string, options: Record<any, any>) => this;
-    hasGlobalCommandVisitor: (name: string) => boolean;
-    disableGlobalCommandVisitors: (visitors: string[]) => this;
-    enableGlobalCommandVisitors: (visitors: string[]) => this;
-    isPrivate: () => this['_isPrivate'];
-    getMeta: () => this['_meta'];
-    getDemandedCommands: () => Dictionary<{
+    disableDefaultCommand(signature: string): this;
+    hasDefaultCommand(signature: string): boolean;
+    globalCommandVisitor(name: string, visitor: CommandVisitor, defaultOptions: any): this;
+    globalCommandVisitorOptions(name: string, options: Record<any, any>): this;
+    hasGlobalCommandVisitor(name: string): boolean;
+    disableGlobalCommandVisitors(visitors: string[]): this;
+    enableGlobalCommandVisitors(visitors: string[]): this;
+    isPrivate(): this['_isPrivate'];
+    getSettings(path?: string): this['_settings'];
+    getDemandedCommands(): Dictionary<{
         min: number;
         max: number;
         minMsg?: string | null;
         maxMsg?: string | null;
     }>;
-    getDemandedOptions: () => Dictionary<string | undefined>;
-    getDeprecatedOptions: () => Dictionary<string | boolean | undefined>;
-    getGroups: () => Dictionary<string[]>;
-    getOptions: () => Record<string, any>;
-    getInternalMethods: () => {
+    getDemandedOptions(): Dictionary<string | undefined>;
+    getDeprecatedOptions(): Dictionary<string | boolean | undefined>;
+    getGroups(): Dictionary<string[]>;
+    getOptions(): Record<string, any>;
+    getInternalMethods(): {
         getCommandInstance(): any;
         getContext(): any;
         getHasOutput(): boolean;
@@ -72,27 +97,31 @@ export interface CLIEngine extends Argv {
         setHasOutput(): void;
     };
 }
-export type CommandModule = {
+/**
+ * @group Types
+ */
+export interface CommandObject {
     /** array of strings (or a single string) representing aliases of `exports.command`, positional args defined in an alias are ignored */
-    aliases: YargsCommandModule['aliases'];
+    aliases?: YargsCommandModule['aliases'];
     /** string (or array of strings) that executes this command when given on the command line, first string may contain positional args */
     command: YargsCommandModule['command'];
     /** boolean (or string) to show deprecation notice */
-    deprecated: YargsCommandModule['deprecated'];
+    deprecated?: YargsCommandModule['deprecated'];
     /** string used as the description for the command in help text, use `false` for a hidden command */
     describe: YargsCommandModule['describe'];
     /** a function which will be passed the parsed argv. */
-    handler: (this: YargsCommandHandler & {
-        engine?: CLIEngine;
-        log?: (msg?: string, options?: any) => void;
-    }, argv: Parameters<YargsCommandModule['handler']>[0]) => ReturnType<YargsCommandModule['handler']>;
+    handler: CommandHandler;
     /** object declaring the options the command accepts, or a function accepting and returning a yargs instance */
     builder: (cli: CLIEngine) => CLIEngine | PromiseLike<CLIEngine>;
-    meta: Record<string, any>;
-};
+    middlewares?: MiddlewareFunction[];
+}
+/**
+ * @group Types
+ */
 export type CLIBuilder = (cli: CLIEngine) => CLIEngine;
 /**
  * Custom global command visitor callback.
+ * @group Types
  */
 export type CommandVisitor = {
     options?: Record<any, any>;
@@ -100,7 +129,7 @@ export type CommandVisitor = {
 /**
  * The exported command object
  */
-commandObject: CommandModule, 
+commandObject: CommandObject, 
 /**
  * The current CLI instance
  */
@@ -108,5 +137,5 @@ engine: CLIEngine,
 /**
  * The default options to set
  */
-options: any) => false | CommandModule);
+options: any) => false | CommandObject);
 export {};

package/dist/cli/utils.d.ts

@@ -1,4 +1,4 @@
-import { CommandModule, CLIEngine } from './types';
+import { CommandObject, CLIEngine, CommandHandler } from './types';
 /**
  * @ignore
  * @param target - The target builder
@@ -7,7 +7,7 @@ import { CommandModule, CLIEngine } from './types';
  * Wrap command builder (target) with builder passed as second parameter
  * that will be called before target. Target can be undefined
  */
-export declare function wrapCommandBuilder(target: CommandModule['builder'], builder: (cli: CLIEngine) => CLIEngine): (cli: CLIEngine) => CLIEngine | PromiseLike<CLIEngine>;
+export declare function wrapCommandBuilder(target: CommandObject['builder'], builder: (cli: CLIEngine) => CLIEngine): (cli: CLIEngine) => CLIEngine | PromiseLike<CLIEngine>;
 /**
  * @ignore
  * @param target - The target handler
@@ -16,4 +16,4 @@ export declare function wrapCommandBuilder(target: CommandModule['builder'], bui
  * Wrap command handler (target) with handler passed as second parameter
  * that will be called before target. Target can be undefined
  */
-export declare function wrapCommandhandler(target: CommandModule['handler'], handler: CommandModule['handler']): CommandModule["handler"];
+export declare function wrapCommandhandler(target: CommandHandler, handler: CommandHandler): CommandHandler;

package/dist/eject.d.ts

@@ -1,15 +1,19 @@
 import { LogLevelDesc } from 'loglevel';
-type EjectOptions = {
+/**
+ * @group Types
+ */
+export type EjectOptions = {
     force?: boolean;
     targetDir?: string;
     logLevel?: LogLevelDesc;
+    ignoreFiles?: string[];
     processor?: (content: string, identifier: string) => string | Promise<string>;
     onError?: (identifier: string, fromPath: string, toPath: string, err: Error) => void | Promise<void>;
     onSuccess?: (identifier: string, fromPath: string, toPath: string) => void | Promise<void>;
 };
 /**
  * Eject from file from template to user project
- * @param identifier - The identifier of the file to eject (relative to juisy/template folder). Can be a glob pattern (ex: `bin\/**\/*`).
+ * @param identifier - The identifier of the file to eject (relative to templateDir folder). Can be a glob pattern (ex: `bin\/**\/*`).
  * @param options - The options object
  * @param options.force - If true, the target files will be overwritten
  * @param options.targetDir - The target directory absolute path
@@ -18,5 +22,8 @@ type EjectOptions = {
  * @param options.onError - The callback if an error occurs
  * @param options.onSuccess - The callback in of success
  */
-export default function eject(identifier: string, options?: EjectOptions): Promise<void>;
-export {};
+export default function eject(
+/**
+ * The absolute path to template directory. Default is juisy/template
+ */
+templateDir: string, identifier: string, options?: EjectOptions): Promise<void>;

package/dist/index.d.ts

@@ -4,8 +4,14 @@
  * @author Hervé Perchec
  */
 import * as utils from './utils/misc';
+export { DataExporter } from './DataExporter';
 export { default as eject } from './eject';
-export * from './DataExporter';
 export { default as getPackageInfo } from './get-package-info';
-export * from './project-globals';
+export { defineGlobals, getProjectGlobals } from './project-globals';
+/**
+ * @ignore
+ */
 export { utils };
+export type * from './DataExporter';
+export type * from './eject';
+export type * from './project-globals';

package/dist/index.js

@@ -1,19 +1,19 @@
 /*!
- * juisy v1.4.0
+ * juisy v2.0.0-beta.10
  * Copyright © 2022-Present Hervé Perchec
  */
 
 import path, { dirname } from 'node:path';
 import { readdir, readFileSync } from 'node:fs';
 import { glob } from 'glob';
+import yaml from 'yaml';
+import { json2csv } from 'json-2-csv';
+import jstoxml from 'jstoxml';
 import fs from 'fs-extra';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { packageDirectorySync } from 'pkg-dir';
 import log from 'loglevel';
 import { Templater } from 'juisy/templater';
-import yaml from 'yaml';
-import { json2csv } from 'json-2-csv';
-import jstoxml from 'jstoxml';
 import dotenv from '@dotenvx/dotenvx';
 import deepmerge from 'deepmerge';
 
@@ -39,8 +39,66 @@ const misc = /*#__PURE__*/Object.freeze(/*#__PURE__*/Object.defineProperty({
     getFiles
 }, Symbol.toStringTag, { value: 'Module' }));
 
+const xml = jstoxml.toXML;
+const SUPPORTED_FORMATS = [
+  "json",
+  "yaml",
+  "csv",
+  "xml"
+  // 'bson',
+  // 'msgpack',
+  // 'protobuf',
+  // 'avro'
+];
+const jsonExporter = function(data, options = {}) {
+  return JSON.stringify(data, options.replacer, options.space);
+};
+const yamlExporter = function(data, options = {}) {
+  return yaml.stringify(data, options.replacer, options.exporter);
+};
+const csvExporter = function(data, options) {
+  return json2csv(data, options);
+};
+const xmlExporter = function(data, options) {
+  return xml(data, options);
+};
+class DataExporter {
+  /**
+   * The target format
+   */
+  format;
+  /**
+   * Creates new instance of Costume
+   * @param options - Costume options
+   */
+  constructor(format) {
+    if (SUPPORTED_FORMATS.includes(format)) {
+      this.format = format;
+    } else {
+      throw new Error(`DataConverter: Unsupported "${format}" format`);
+    }
+  }
+  exportSync(data, options) {
+    switch (this.format) {
+      case "json":
+        return jsonExporter(data, options);
+      case "yaml":
+        return yamlExporter(data, options);
+      case "csv":
+        return csvExporter(data, options);
+      case "xml":
+        return xmlExporter(data, options);
+    }
+  }
+  export(...args) {
+    return new Promise((resolve, reject) => {
+      resolve(this.exportSync(...args));
+    });
+  }
+}
+
 const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+dirname(__filename);
 const templater = new Templater("ejs", {
   engineOptions: {
     // ...
@@ -88,33 +146,37 @@ async function ejectFile(from, to, identifier = null, options) {
     await onError(identifier, from, to, err);
   }
 }
-async function eject(identifier, options) {
+async function eject(templateDir, identifier, options) {
   const targetDir = options?.targetDir || packageDirectorySync() || process.cwd();
   const logLevel = options?.logLevel || "trace";
+  const ignoreFiles = options?.ignoreFiles || [];
   const originalLogLevel = log.getLevel();
   log.setLevel(logLevel);
   if (!identifier) {
     throw new Error("eject: identifier is required");
   } else {
     try {
-      const localTemplatePath = path.resolve(__dirname, "../template");
-      const fullPath = path.resolve(localTemplatePath, identifier);
+      const fullPath = path.resolve(templateDir, identifier);
       if (await isFile(fullPath)) {
-        await ejectFile(fullPath, path.resolve(targetDir, identifier), identifier, {
-          processor: options?.processor,
-          onSuccess: options?.onSuccess,
-          onError: options?.onError
-        });
-      } else {
-        const globPattern = await isDirectory(fullPath) ? identifier + "/**/*" : identifier;
-        for (const fileRelativePath of getFileUrls(globPattern, { cwd: localTemplatePath, nodir: true, posix: true })) {
-          const fullTemplateFilePath = path.resolve(localTemplatePath, fileRelativePath);
-          await ejectFile(fullTemplateFilePath, path.resolve(targetDir, fileRelativePath), fileRelativePath, {
+        if (!ignoreFiles.includes(identifier)) {
+          await ejectFile(fullPath, path.resolve(targetDir, identifier), identifier, {
             processor: options?.processor,
             onSuccess: options?.onSuccess,
             onError: options?.onError
           });
         }
+      } else {
+        const globPattern = await isDirectory(fullPath) ? identifier + "/**/*" : identifier;
+        for (const fileRelativePath of getFileUrls(globPattern, { cwd: templateDir, nodir: true, posix: true, dot: true })) {
+          const fullTemplateFilePath = path.resolve(templateDir, fileRelativePath);
+          if (!ignoreFiles.includes(fileRelativePath)) {
+            await ejectFile(fullTemplateFilePath, path.resolve(targetDir, fileRelativePath), fileRelativePath, {
+              processor: options?.processor,
+              onSuccess: options?.onSuccess,
+              onError: options?.onError
+            });
+          }
+        }
       }
       log.info(`Successfully ejected "${identifier}"`);
     } finally {
@@ -123,64 +185,6 @@ async function eject(identifier, options) {
   }
 }
 
-const xml = jstoxml.toXML;
-const SUPPORTED_FORMATS = [
-  "json",
-  "yaml",
-  "csv",
-  "xml"
-  // 'bson',
-  // 'msgpack',
-  // 'protobuf',
-  // 'avro'
-];
-const jsonExporter = function(data, options = {}) {
-  return JSON.stringify(data, options.replacer, options.space);
-};
-const yamlExporter = function(data, options = {}) {
-  return yaml.stringify(data, options.replacer, options.exporter);
-};
-const csvExporter = function(data, options) {
-  return json2csv(data, options);
-};
-const xmlExporter = function(data, options) {
-  return xml(data, options);
-};
-class DataExporter {
-  /**
-   * The target format
-   */
-  format;
-  /**
-   * Creates new instance of Costume
-   * @param options - Costume options
-   */
-  constructor(format) {
-    if (SUPPORTED_FORMATS.includes(format)) {
-      this.format = format;
-    } else {
-      throw new Error(`DataConverter: Unsupported "${format}" format`);
-    }
-  }
-  exportSync(data, options) {
-    switch (this.format) {
-      case "json":
-        return jsonExporter(data, options);
-      case "yaml":
-        return yamlExporter(data, options);
-      case "csv":
-        return csvExporter(data, options);
-      case "xml":
-        return xmlExporter(data, options);
-    }
-  }
-  export(...args) {
-    return new Promise((resolve, reject) => {
-      resolve(this.exportSync(...args));
-    });
-  }
-}
-
 function getPackageInfo() {
   const pkgPath = path.resolve(packageDirectorySync(), "./package.json");
   return JSON.parse(readFileSync(pkgPath, "utf8"));

package/dist/project-globals.d.ts

@@ -1,5 +1,8 @@
 import { DotenvConfigOptions } from '@dotenvx/dotenvx';
 import { IPackageJson as PackageJson, IAuthor as PackageJsonAuthor, IRepository as PackageJsonRepository, IBugs as PackageJsonBugs } from 'package-json-type';
+/**
+ * @group Types
+ */
 export type ProjectGlobals = Record<string, string | Record<string, unknown> | undefined> & {
     ENV: NodeJS.ProcessEnv;
     PACKAGE: {
@@ -19,7 +22,13 @@ export type ProjectGlobals = Record<string, string | Record<string, unknown> | u
     ISSUES_URL: PackageJsonBugs['url'];
     HOMEPAGE: PackageJson['homepage'];
 };
+/**
+ * @group Types
+ */
 export type DotenvOptions = Omit<DotenvConfigOptions, 'processEnv'>;
+/**
+ * @group Types
+ */
 export type DefineGlobalsBuilder = (ctx: {
     env: NodeJS.ProcessEnv;
     pkg: PackageJson;

package/dist/templater/index.d.ts

@@ -1,6 +1,11 @@
+/**
+ * Public API of juisy/templater library
+ * @module juisy\/templater
+ * @author Hervé Perchec
+ */
 export { Templater } from './Templater';
 export { MarkdownTemplater } from './markdown-templater';
 export { ReadmeTemplater } from './markdown-templater/ReadmeTemplater';
 export type * from './types';
 export type { MarkdownTemplaterOptions } from './markdown-templater';
-export type { UserConfiguration as ReadmeTemplaterUserConfiguration } from './markdown-templater/ReadmeTemplater';
+export type { UserConfiguration as ReadmeTemplaterUserConfig, Configuration as ReadmeTemplaterConfig } from './markdown-templater/ReadmeTemplater';

package/dist/templater/index.js

@@ -1,5 +1,5 @@
 /*!
- * juisy v1.4.0
+ * juisy v2.0.0-beta.10
  * Copyright © 2022-Present Hervé Perchec
  */
 
@@ -8,8 +8,8 @@ import handlebars from 'handlebars';
 import { remark } from 'remark';
 import remarkToc from 'remark-toc';
 import remarkFrontmatter from 'remark-frontmatter';
-import path, { dirname } from 'path';
-import { fileURLToPath, pathToFileURL } from 'url';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import fs from 'fs-extra';
 import chalk from 'chalk';
 import merge from 'lodash.merge';
@@ -122,11 +122,17 @@ class MarkdownTemplater extends Templater {
   }
 }
 
-const __filename = fileURLToPath(import.meta.url);
-dirname(__filename);
 const slugger = new GithubSlugger();
 const DEFAULT_INIT_TARGET_RELATIVE_PATH = "./docs/readme";
 class ReadmeTemplater {
+  /**
+   * @param config - The user configuration file path (as string) or object
+   * @example
+   * // Path as string
+   * const templater = new ReadmeTemplater('./.docs/readme/config.js')
+   * // Pass object. See configuration below
+   * const templater = new ReadmeTemplater({ /* ... *\/ })
+   */
   constructor(config) {
     this.config = config;
     this.templater = new MarkdownTemplater("ejs", {});
@@ -134,21 +140,13 @@ class ReadmeTemplater {
   config;
   templater;
   /**
-   * @param {Configuration|string} config - The config object to process. Can be path to config file as string.
-   * @param {object} [options] - Same as render
-   * @returns {void|Promise<void>} Promise is immediately resolved except if a module is async.
-   * @throws Throws error if render or file writing fails
-   * @description
    * Writes rendered README markdown to file
+   * @param config - The config object to process. Can be path to config file as string.
+   * @param options - Same as render
+   * @throws Throws error if render or file writing fails
    * @example
-   * readmeGenerator.generate(config) // => output to README.md file
-   * readmeGenerator.generate('./.docs/readme/config.js') // pass config path
-   * readmeGenerator.generate(config, { data: { foo: 'bar' } }) // pass options
-   * // Async
-   * await readmeGenerator.generate('./.docs/readme/config.js') // async module
-   * await readmeGenerator.generate({
-   *   ejsDataPath: '/path/to/ejs/data.js' // async module
-   * })
+   * await templater.generate() // => output to README.md file
+   * await templater.generate({ data: { foo: 'bar' } }) // pass options
    */
   async generate(options = {}) {
     const processedConfig = await ReadmeTemplater.processConfig(this.config);
@@ -173,14 +171,8 @@ class ReadmeTemplater {
    * @param options.data - Additionnal data object to merge with default EJS data
    * @returns Returns the rendered markdown as string. Promise is immediately resolved except if a module is async.
    * @example
-   * const result = readmeGenerator.render(config)
-   * const result = readmeGenerator.render('./.docs/readme/config.js')
-   * const result = readmeGenerator.render(config, { data: { foo: 'bar' } })
-   * // Async
-   * const result = await readmeGenerator.render('./.docs/readme/config.js') // async module
-   * const result = await readmeGenerator.render({
-   *   ejsDataPath: '/path/to/ejs/data.js' // async module
-   * })
+   * await templater.render()
+   * await templater.render({ data: { foo: 'bar' } })
    */
   async render(options = {}) {
     const processedConfig = await ReadmeTemplater.processConfig(this.config);
@@ -243,12 +235,8 @@ class ReadmeTemplater {
     return result;
   }
   /**
-   * @alias module:readme-generator.defaultConfig
-   * @type {Configuration}
-   * @description
    * Returns the default configuration object.
    * This base configuration is used by `processConfig` method and so `generate` and `render` methods.
-   * See also {@link module:readme-generator~Configuration Configuration} defaults.
    */
   static defaultConfig = {
     fileName: "README.md",
@@ -258,7 +246,6 @@ class ReadmeTemplater {
     ejsOptions: {
       /**
        * Always render in async mode
-       * @since v3.0.0
        */
       async: true,
       /**