juisy 2.0.0-beta.0

package/dist/templater/index.js

@@ -0,0 +1,330 @@
+/*!
+ * juisy v1.4.0
+ * Copyright © 2022-Present Hervé Perchec
+ */
+
+import ejs from 'ejs';
+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 fs from 'fs-extra';
+import chalk from 'chalk';
+import merge from 'lodash.merge';
+import mdu from 'markdown-utils';
+import { markdownTable } from 'markdown-table';
+import asciitree from 'ascii-tree';
+import GithubSlugger from 'github-slugger';
+
+class Templater {
+  constructor(engine, options) {
+    this.engine = engine;
+    options = options || {};
+    switch (engine) {
+      case "handlebars":
+        this.engine = handlebars;
+        this.methodsMap.compile = async (template) => {
+          return handlebars.compile(template, options.engineOptions);
+        };
+        this.methodsMap.render = async (template, data = void 0, opts = void 0) => {
+          return this.methodsMap.compile(template).template(data);
+        };
+        break;
+      case "ejs":
+        this.engine = ejs;
+        this.methodsMap.compile = async (template) => {
+          return ejs.compile(template, options.engineOptions);
+        };
+        this.methodsMap.render = async (template, data = void 0, opts) => {
+          return ejs.render(template, data, {
+            ...options.engineOptions,
+            ...opts || {}
+          });
+        };
+        break;
+      case "pug":
+        this.engine = (template, options2) => () => "";
+        break;
+      default:
+        throw new Error(`Unsupported templating engine: ${engine}`);
+    }
+    if (options.defaultData) {
+      this.defaultData = options.defaultData;
+    }
+  }
+  engine;
+  defaultData;
+  methodsMap = {};
+  /**
+   * @returns Get the engine
+   */
+  getEngine() {
+    return this.engine;
+  }
+  /**
+   * Renders a template with the given context.
+   */
+  async render(template, data = void 0, options = void 0) {
+    const mergedData = { ...this.defaultData, ...data || {} };
+    return await this.methodsMap.render(template, mergedData, options);
+  }
+  /**
+   * Renders a template file with the given context.
+   * @todo not yet implemented
+   */
+  renderFile(filePath, context = {}) {
+    return "";
+  }
+}
+
+class MarkdownTemplater extends Templater {
+  constructor(engine = "ejs", options) {
+    super(engine, options);
+    this.processor = options?.processor ? options.processor === "remark" ? remark() : options.processor : remark();
+    this.processorOptions = this.buildProcessorOptions(options?.processorOptions || {});
+    this.initProcessor();
+  }
+  processor;
+  processorOptions;
+  buildProcessorOptions(options) {
+    options = options || {};
+    const defaultRemarkTocOptions = {};
+    const defaultRemarkFrontmatterOptions = {
+      type: "yaml",
+      marker: "-"
+    };
+    return {
+      use: [
+        ...options.use || []
+      ],
+      toc: options.toc === true ? defaultRemarkTocOptions : options.toc !== void 0 ? options.toc : defaultRemarkTocOptions,
+      frontmatter: options.frontmatter === true ? defaultRemarkFrontmatterOptions : options.frontmatter !== void 0 ? options.frontmatter : defaultRemarkFrontmatterOptions
+    };
+  }
+  initProcessor() {
+    const processorPlugins = [];
+    if (this.processorOptions.toc)
+      processorPlugins.push([remarkToc, this.processorOptions.toc]);
+    if (this.processorOptions.frontmatter)
+      processorPlugins.push([remarkFrontmatter, this.processorOptions.frontmatter]);
+    for (const plugin of processorPlugins.concat(this.processorOptions.use)) {
+      this.processor.use(...plugin);
+    }
+  }
+  /**
+   * Renders a template with the given context.
+   */
+  async render(template, data = void 0, options = void 0) {
+    const content = await super.render(template, data, options);
+    return (await this.processor.process(content)).toString();
+  }
+}
+
+const __filename = fileURLToPath(import.meta.url);
+dirname(__filename);
+const slugger = new GithubSlugger();
+const DEFAULT_INIT_TARGET_RELATIVE_PATH = "./docs/readme";
+class ReadmeTemplater {
+  constructor(config) {
+    this.config = config;
+    this.templater = new MarkdownTemplater("ejs", {});
+  }
+  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
+   * @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
+   * })
+   */
+  async generate(options = {}) {
+    const processedConfig = await ReadmeTemplater.processConfig(this.config);
+    const targetFilePath = path.join(processedConfig.destFolder, processedConfig.fileName);
+    console.log(`Auto-generating "${processedConfig.fileName}" file`);
+    console.log();
+    console.log("- Syntax: " + chalk.yellow("ejs"));
+    const renderResult = await this.render(options);
+    try {
+      fs.writeFileSync(targetFilePath, renderResult);
+    } catch (error) {
+      console.log("- Status:", chalk.red("✘ FAILED"));
+      throw error;
+    }
+    console.log("- Status:", chalk.green("✔ OK"));
+    console.log('- Written to: "' + chalk.cyan(targetFilePath) + '"');
+    console.log();
+  }
+  /**
+   * Render README markdown
+   * @param options - Options object
+   * @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
+   * })
+   */
+  async render(options = {}) {
+    const processedConfig = await ReadmeTemplater.processConfig(this.config);
+    const data = processedConfig.ejsDataPath ? await import(pathToFileURL(processedConfig.ejsDataPath).toString()).then((mod) => mod.default || mod) : {};
+    options.data = options.data || {};
+    const ejsData = merge(merge({
+      ...ReadmeTemplater.defaultEjsData,
+      $config: processedConfig
+    }, data), options.data);
+    let template = await fs.readFile(processedConfig.templatePath, { encoding: "utf8" });
+    if (processedConfig.appendAutoGenMessage) {
+      template += "\n----\n\n*<%= $config.fileName %> - this file was auto generated with [juisy](https://www.npmjs.com/package/juisy) README templater. Don't edit it.*\n";
+    }
+    return await this.templater.render(template, ejsData, processedConfig.ejsOptions);
+  }
+  /**
+   * Static methods
+   */
+  /**
+   * Takes a custom config as unique parameter and merges it with the default configuration object.
+   * @param config - The config object to process. Can be path to config file as string.
+   * @returns Returns the processed configuration. Promise is immediately resolved except if module is async.
+   * @example
+   * readmeGenerator.processConfig({ ... }) // pass object
+   * readmeGenerator.processConfig('./.docs/readme/config.js') // pass path as string
+   * // If module.exports is a promise
+   * await readmeGenerator.processConfig('./.docs/readme/config.js') // async module
+   */
+  static async processConfig(config) {
+    let customConfig;
+    if (typeof config === "string") {
+      const configPath = pathToFileURL(path.isAbsolute(config) ? config : path.resolve(process.cwd(), config));
+      customConfig = (await import(configPath.toString())).default;
+    } else if (typeof config !== "object") {
+      throw new TypeError("config parameter must be object or string. Received " + typeof config);
+    } else {
+      customConfig = config;
+    }
+    const result = {};
+    result.fileName = customConfig.fileName || ReadmeTemplater.defaultConfig.fileName;
+    result.destFolder = customConfig.destFolder || ReadmeTemplater.defaultConfig.destFolder;
+    result.templatePath = customConfig.templatePath || ReadmeTemplater.defaultConfig.templatePath;
+    result.ejsDataPath = customConfig.ejsDataPath || customConfig.ejsDataPath === null ? customConfig.ejsDataPath : ReadmeTemplater.defaultConfig.ejsDataPath;
+    if (customConfig.ejsOptions) {
+      result.ejsOptions = {
+        async: ReadmeTemplater.defaultConfig.ejsOptions.async,
+        // async prop see below
+        root: ReadmeTemplater.defaultConfig.ejsOptions.root,
+        // root prop see below (always array)
+        views: ReadmeTemplater.defaultConfig.ejsOptions.views,
+        // views prop see below (always array)
+        ...customConfig.ejsOptions
+      };
+    } else {
+      result.ejsOptions = ReadmeTemplater.defaultConfig.ejsOptions;
+    }
+    result.appendAutoGenMessage = customConfig.appendAutoGenMessage !== void 0 ? customConfig.appendAutoGenMessage : ReadmeTemplater.defaultConfig.appendAutoGenMessage;
+    result.autoToc = customConfig.autoToc !== void 0 ? customConfig.autoToc : ReadmeTemplater.defaultConfig.autoToc;
+    result.slugify = customConfig.slugify !== void 0 ? customConfig.slugify : ReadmeTemplater.defaultConfig.slugify;
+    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",
+    destFolder: process.cwd(),
+    templatePath: path.resolve(process.cwd(), DEFAULT_INIT_TARGET_RELATIVE_PATH, "template.md"),
+    ejsDataPath: path.resolve(process.cwd(), DEFAULT_INIT_TARGET_RELATIVE_PATH, "data.js"),
+    ejsOptions: {
+      /**
+       * Always render in async mode
+       * @since v3.0.0
+       */
+      async: true,
+      /**
+       * Set project root for includes with an absolute path (e.g, /file.ejs).
+       * Can be array to try to resolve include from multiple directories.
+       */
+      root: [
+        // User template path
+        // path.resolve(process.cwd(), DEFAULT_INIT_TARGET_RELATIVE_PATH)
+      ],
+      /**
+       *  An array of paths to use when resolving includes with relative paths.
+       */
+      views: [
+        // // User template path
+        // path.resolve(process.cwd(), DEFAULT_INIT_TARGET_RELATIVE_PATH)
+      ]
+    },
+    appendAutoGenMessage: true,
+    autoToc: true,
+    slugify: slugger.slug.bind(slugger)
+  };
+  /**
+   * The default EJS data object.
+   * This base EJS data object is used by `render` methods and merged with user provided EJS data.
+   */
+  static defaultEjsData = {
+    /**
+     * Contains the default configuration by default.
+     * Will be merged with custom configuration when using `generate` or `render` method.
+     * @example
+     * // Access configuration
+     * $config.fileName // => README.md
+     */
+    $config: {},
+    /**
+     * Contains the following methods:
+     *
+     * - `table`: generates a markdown table
+     * - `asciiTree`: generates an "ASCII" tree
+     * - ... all methods from `markdown-utils` package
+     *
+     * > Please check the following package documentations:
+     * > - [markdown-utils](https://github.com/jonschlinkert/markdown-utils)
+     * > - [markdown-table](https://www.npmjs.com/package/markdown-table)
+     * > - [ascii-tree](https://www.npmjs.com/package/ascii-tree)
+     * @example
+     * // Generates a blockquote
+     * $utils.blockquote('This is a blockquote')
+     * // Generates a table
+     * $utils.table([
+     *   [ 'Column 1', 'Column 2' ],
+     *   [ 'Value 1', 'Value 2' ]
+     * ])
+     * // Generates an ascii tree
+     * $utils.asciiTree('*.\n**a\n**b\n*...')
+     */
+    $utils: {
+      // markdown-utils
+      ...mdu,
+      // markdown-table
+      table: markdownTable,
+      // ascii-tree
+      asciiTree: asciitree.generate
+    }
+  };
+}
+
+export { MarkdownTemplater, ReadmeTemplater, Templater };

package/dist/templater/markdown-templater/ReadmeTemplater.d.ts

@@ -0,0 +1,154 @@
+import { default as ejs } from 'ejs';
+type Configuration = {
+    /**
+     * Output file name: `README.md` by default. Only for **generate** method
+     */
+    fileName: string;
+    /**
+     * Output path, default is `process.cwd` (project root). Only for **generate** method
+     */
+    destFolder: string;
+    /**
+     * Template path: default is `.docs/readme/template.md`
+     */
+    templatePath: string;
+    /**
+     * Path to EJS data file: default is `.docs/readme/data.js`. If null, no file will be required
+     */
+    ejsDataPath: string;
+    /**
+     * EJS options: see also {@link https://www.npmjs.com/package/ejs#options EJS documentation}.
+     * @property {string[]} [ejsOptions.root] - The path of template folder is automatically included.
+     * @property {string[]} [ejsOptions.views] - The path of template folder and the path of internal partials are automatically included.
+     */
+    ejsOptions: ejs.Options & {
+        root: string[];
+        views: string[];
+    };
+    /**
+     * If true, append "don't edit" message to rendered markdown. Default is **true**.
+     */
+    appendAutoGenMessage: boolean;
+    /**
+     * If true, parse `<!-- toc -->` special comment to automatically inject generated table of contents. Default is **true**.
+     * The `markdown-toc` package is used for this feature, check the {@link https://www.npmjs.com/package/markdown-toc documentation}.
+     */
+    autoToc: boolean;
+    /**
+     * If provided, will be used by `markdown-toc` to slugify headings id.
+     * Default uses `github-slugger`: see [**slug** method documentation](https://github.com/Flet/github-slugger#usage).
+     */
+    slugify: Function;
+};
+export type UserConfiguration = {
+    fileName?: Configuration['fileName'];
+    destFolder?: Configuration['destFolder'];
+    templatePath?: Configuration['templatePath'];
+    ejsDataPath?: Configuration['ejsDataPath'];
+    ejsOptions?: Configuration['ejsOptions'];
+    appendAutoGenMessage?: Configuration['appendAutoGenMessage'];
+    autoToc?: Configuration['autoToc'];
+    slugify?: Configuration['slugify'];
+};
+export declare class ReadmeTemplater {
+    constructor(config: Parameters<typeof ReadmeTemplater.processConfig>[0]);
+    private config;
+    private 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
+     * @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
+     * })
+     */
+    generate(options?: {}): Promise<void>;
+    /**
+     * Render README markdown
+     * @param options - Options object
+     * @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
+     * })
+     */
+    render(options?: {
+        data?: Record<any, any>;
+    }): Promise<string>;
+    /**
+     * Static methods
+     */
+    /**
+     * Takes a custom config as unique parameter and merges it with the default configuration object.
+     * @param config - The config object to process. Can be path to config file as string.
+     * @returns Returns the processed configuration. Promise is immediately resolved except if module is async.
+     * @example
+     * readmeGenerator.processConfig({ ... }) // pass object
+     * readmeGenerator.processConfig('./.docs/readme/config.js') // pass path as string
+     * // If module.exports is a promise
+     * await readmeGenerator.processConfig('./.docs/readme/config.js') // async module
+     */
+    static processConfig(config: UserConfiguration | string): Promise<Configuration>;
+    /**
+     * @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: Configuration;
+    /**
+     * The default EJS data object.
+     * This base EJS data object is used by `render` methods and merged with user provided EJS data.
+     */
+    static defaultEjsData: {
+        /**
+         * Contains the default configuration by default.
+         * Will be merged with custom configuration when using `generate` or `render` method.
+         * @example
+         * // Access configuration
+         * $config.fileName // => README.md
+         */
+        $config: {};
+        /**
+         * Contains the following methods:
+         *
+         * - `table`: generates a markdown table
+         * - `asciiTree`: generates an "ASCII" tree
+         * - ... all methods from `markdown-utils` package
+         *
+         * > Please check the following package documentations:
+         * > - [markdown-utils](https://github.com/jonschlinkert/markdown-utils)
+         * > - [markdown-table](https://www.npmjs.com/package/markdown-table)
+         * > - [ascii-tree](https://www.npmjs.com/package/ascii-tree)
+         * @example
+         * // Generates a blockquote
+         * $utils.blockquote('This is a blockquote')
+         * // Generates a table
+         * $utils.table([
+         *   [ 'Column 1', 'Column 2' ],
+         *   [ 'Value 1', 'Value 2' ]
+         * ])
+         * // Generates an ascii tree
+         * $utils.asciiTree('*.\n**a\n**b\n*...')
+         */
+        $utils: any;
+    };
+}
+export {};

package/dist/templater/markdown-templater/index.d.ts

@@ -0,0 +1,25 @@
+import { remark } from 'remark';
+import { Templater } from '../Templater';
+import { TemplaterOptions } from '../types';
+export type MarkdownTemplaterOptions = TemplaterOptions<any> & {
+    processor?: 'remark' | typeof remark;
+    /**
+     * Options to pass to remark
+     */
+    processorOptions?: {
+        use?: MarkdownTemplater['processorOptions']['use'];
+        toc?: MarkdownTemplater['processorOptions']['toc'];
+        frontmatter?: MarkdownTemplater['processorOptions']['frontmatter'];
+    };
+};
+export declare class MarkdownTemplater extends Templater {
+    constructor(engine?: ConstructorParameters<typeof Templater>[0], options?: MarkdownTemplaterOptions);
+    private processor;
+    private processorOptions;
+    private buildProcessorOptions;
+    private initProcessor;
+    /**
+     * Renders a template with the given context.
+     */
+    render(template: string, data?: undefined, options?: any): Promise<string>;
+}

package/dist/templater/types.d.ts

@@ -0,0 +1,10 @@
+import { Options as EJSOptions } from 'ejs';
+import { compile as HandlebarsCompiler } from 'handlebars';
+export type SupportedEngines = ['handlebars', 'ejs', 'pug'];
+export type TemplaterOptions<E extends SupportedEngines[number]> = {
+    engineOptions?: E extends 'handlebars' ? Parameters<typeof HandlebarsCompiler>[1] : E extends 'ejs' ? EJSOptions : unknown;
+    /**
+     * Default data to be merged with template context.
+     */
+    defaultData?: Record<string, any>;
+};

package/dist/utils/misc.d.ts

@@ -0,0 +1,21 @@
+import { GlobOptions } from 'glob';
+/**
+ * @param pattern - Same as node-glob pattern argument
+ * @param options - Same as gloab options argument
+ * @returns {string[]} Returns an array of file path
+ * @description
+ * Get file urls that match glob (see: https://github.com/isaacs/node-glob)
+ * @example
+ * utils.getFileUrls('path/to/*.js') // => [ 'path/to/file1.js', 'path/to/file2.js', ... ]
+ */
+export declare function getFileUrls(pattern: string, options?: GlobOptions): string[] | import('path-scurry').Path[];
+/**
+ * @param dir - The directory path
+ * @returns Returns an array of file path
+ * @yields {string[]} The next found files.
+ * @description
+ * Get all files in a directory (recursively)
+ * @example
+ * utils.getFiles(path) // => [ 'path/to/file1', 'path/to/file2', ... ]
+ */
+export declare function getFiles(dir: string): AsyncGenerator<string[]>;