presetter 4.5.0 → 4.7.0

package/lib/resolution.js

@@ -1,13 +1,39 @@
+/*
+ *                            *** MIT LICENSE ***
+ * -------------------------------------------------------------------------
+ * This code may be modified and distributed under the MIT license.
+ * See the LICENSE file for details.
+ * -------------------------------------------------------------------------
+ *
+ * @summary   Collection of helpers for resolving content
+ *
+ * @author    Alvis HT Tang <alvis@hilbert.space>
+ * @license   MIT
+ * @copyright Copyright (c) 2022 - All Rights Reserved.
+ * -------------------------------------------------------------------------
+ */
 import { existsSync } from 'node:fs';
 import { basename, extname } from 'node:path';
 import { loadFile } from './io.js';
+/**
+ * compute the corresponding field within the config field of .presetterrc
+ * @param filename link name
+ * @returns field name in config
+ */
 export function getConfigKey(filename) {
     return basename(filename, extname(filename))
         .replace(/^\./, '')
         .replace(/rc$/, '')
         .replace(/\.config$/, '');
 }
+/**
+ * resolve a dynamic asset content
+ * @param map a dynamic map to be resolved
+ * @param context arguments to be passed to the generator function
+ * @returns content of the resolved field
+ */
 export async function loadDynamicMap(map, context) {
+    // load templated configuration from presets
     return Object.fromEntries(await Promise.all(Object.entries(map instanceof Function
         ? await map(context)
         : { ...map }).map(async ([relativePath, value]) => [
@@ -15,6 +41,12 @@ export async function loadDynamicMap(map, context) {
         await loadDynamic(value, context),
     ])));
 }
+/**
+ * load a potentially dynamic content
+ * @param value content to be loaded
+ * @param context context to be supplied to the generator
+ * @returns resolved content
+ */
 export async function loadDynamic(value, context) {
     if (typeof value === 'function') {
         return value(context);
@@ -26,4 +58,4 @@ export async function loadDynamic(value, context) {
         return value;
     }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVzb2x1dGlvbi5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NvdXJjZS9yZXNvbHV0aW9uLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQWVBLE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSxTQUFTLENBQUM7QUFDckMsT0FBTyxFQUFFLFFBQVEsRUFBRSxPQUFPLEVBQUUsTUFBTSxXQUFXLENBQUM7QUFFOUMsT0FBTyxFQUFFLFFBQVEsRUFBRSxNQUFNLE1BQU0sQ0FBQztBQWtCaEMsTUFBTSxVQUFVLFlBQVksQ0FBQyxRQUFnQjtJQUMzQyxPQUFPLFFBQVEsQ0FBQyxRQUFRLEVBQUUsT0FBTyxDQUFDLFFBQVEsQ0FBQyxDQUFDO1NBQ3pDLE9BQU8sQ0FBQyxLQUFLLEVBQUUsRUFBRSxDQUFDO1NBQ2xCLE9BQU8sQ0FBQyxLQUFLLEVBQUUsRUFBRSxDQUFDO1NBQ2xCLE9BQU8sQ0FBQyxXQUFXLEVBQUUsRUFBRSxDQUFDLENBQUM7QUFDOUIsQ0FBQztBQVFELE1BQU0sQ0FBQyxLQUFLLFVBQVUsY0FBYyxDQUNsQyxHQUFtQixFQUNuQixPQUFxRDtJQUdyRCxPQUFPLE1BQU0sQ0FBQyxXQUFXLENBQ3ZCLE1BQU0sT0FBTyxDQUFDLEdBQUcsQ0FDZixNQUFNLENBQUMsT0FBTyxDQUNaLEdBQUcsWUFBWSxRQUFRO1FBQ3JCLENBQUMsQ0FBQyxNQUFNLEdBQUcsQ0FBQyxPQUFnQyxDQUFDO1FBQzdDLENBQUMsQ0FBQyxFQUFFLEdBQUcsR0FBRyxFQUFFLENBQ2YsQ0FBQyxHQUFHLENBQ0gsS0FBSyxFQUFFLENBQUMsWUFBWSxFQUFFLEtBQUssQ0FBQyxFQUEwQixFQUFFLENBQUM7UUFDdkQsWUFBWTtRQUNaLE1BQU0sV0FBVyxDQUFDLEtBQUssRUFBRSxPQUFnQyxDQUFDO0tBQzNELENBQ0YsQ0FDRixDQUNGLENBQUM7QUFDSixDQUFDO0FBUUQsTUFBTSxDQUFDLEtBQUssVUFBVSxXQUFXLENBSS9CLEtBR21CLEVBQ25CLE9BQWlDO0lBRWpDLElBQUksT0FBTyxLQUFLLEtBQUssVUFBVSxFQUFFO1FBQy9CLE9BQU8sS0FBSyxDQUFDLE9BQU8sQ0FBQyxDQUFDO0tBQ3ZCO1NBQU0sSUFBSSxPQUFPLEtBQUssS0FBSyxRQUFRLElBQUksVUFBVSxDQUFDLEtBQUssQ0FBQyxFQUFFO1FBQ3pELE9BQU8sUUFBUSxDQUFDLEtBQUssQ0FBTSxDQUFDO0tBQzdCO1NBQU07UUFDTCxPQUFPLEtBQVUsQ0FBQztLQUNuQjtBQUNILENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVzb2x1dGlvbi5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NvdXJjZS9yZXNvbHV0aW9uLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7O0dBYUc7QUFFSCxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sU0FBUyxDQUFDO0FBQ3JDLE9BQU8sRUFBRSxRQUFRLEVBQUUsT0FBTyxFQUFFLE1BQU0sV0FBVyxDQUFDO0FBRTlDLE9BQU8sRUFBRSxRQUFRLEVBQUUsTUFBTSxNQUFNLENBQUM7QUFhaEM7Ozs7R0FJRztBQUNILE1BQU0sVUFBVSxZQUFZLENBQUMsUUFBZ0I7SUFDM0MsT0FBTyxRQUFRLENBQUMsUUFBUSxFQUFFLE9BQU8sQ0FBQyxRQUFRLENBQUMsQ0FBQztTQUN6QyxPQUFPLENBQUMsS0FBSyxFQUFFLEVBQUUsQ0FBQztTQUNsQixPQUFPLENBQUMsS0FBSyxFQUFFLEVBQUUsQ0FBQztTQUNsQixPQUFPLENBQUMsV0FBVyxFQUFFLEVBQUUsQ0FBQyxDQUFDO0FBQzlCLENBQUM7QUFFRDs7Ozs7R0FLRztBQUNILE1BQU0sQ0FBQyxLQUFLLFVBQVUsY0FBYyxDQUNsQyxHQUFtQixFQUNuQixPQUFxRDtJQUVyRCw0Q0FBNEM7SUFDNUMsT0FBTyxNQUFNLENBQUMsV0FBVyxDQUN2QixNQUFNLE9BQU8sQ0FBQyxHQUFHLENBQ2YsTUFBTSxDQUFDLE9BQU8sQ0FDWixHQUFHLFlBQVksUUFBUTtRQUNyQixDQUFDLENBQUMsTUFBTSxHQUFHLENBQUMsT0FBZ0MsQ0FBQztRQUM3QyxDQUFDLENBQUMsRUFBRSxHQUFHLEdBQUcsRUFBRSxDQUNmLENBQUMsR0FBRyxDQUNILEtBQUssRUFBRSxDQUFDLFlBQVksRUFBRSxLQUFLLENBQUMsRUFBMEIsRUFBRSxDQUFDO1FBQ3ZELFlBQVk7UUFDWixNQUFNLFdBQVcsQ0FBQyxLQUFLLEVBQUUsT0FBZ0MsQ0FBQztLQUMzRCxDQUNGLENBQ0YsQ0FDRixDQUFDO0FBQ0osQ0FBQztBQUVEOzs7OztHQUtHO0FBQ0gsTUFBTSxDQUFDLEtBQUssVUFBVSxXQUFXLENBSS9CLEtBR21CLEVBQ25CLE9BQWlDO0lBRWpDLElBQUksT0FBTyxLQUFLLEtBQUssVUFBVSxFQUFFO1FBQy9CLE9BQU8sS0FBSyxDQUFDLE9BQU8sQ0FBQyxDQUFDO0tBQ3ZCO1NBQU0sSUFBSSxPQUFPLEtBQUssS0FBSyxRQUFRLElBQUksVUFBVSxDQUFDLEtBQUssQ0FBQyxFQUFFO1FBQ3pELE9BQU8sUUFBUSxDQUFDLEtBQUssQ0FBTSxDQUFDO0tBQzdCO1NBQU07UUFDTCxPQUFPLEtBQVUsQ0FBQztLQUNuQjtBQUNILENBQUMifQ==

package/lib/run.d.ts

@@ -1,4 +1,11 @@
 import type { Task } from './task.js';
+/**
+ * run a task defined in the combined script definitions.
+ * @param tasks array of objects containing the selector and args for the task
+ * @param options collection of options
+ * @param options.parallel whether to run tasks concurrently
+ * @param options.templateOnly whether to resolve the task from the template only
+ */
 export declare function run(tasks: Task[], options?: {
     parallel?: boolean;
     templateOnly?: boolean;

package/lib/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../source/run.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAuJnC,wBAAsB,GAAG,CACvB,KAAK,EAAE,IAAI,EAAE,EACb,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GACvD,OAAO,CAAC,IAAI,CAAC,CA+Bf"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../source/run.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAgJnC;;;;;;GAMG;AACH,wBAAsB,GAAG,CACvB,KAAK,EAAE,IAAI,EAAE,EACb,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GACvD,OAAO,CAAC,IAAI,CAAC,CA+Bf"}

package/lib/run.js

@@ -1,3 +1,17 @@
+/*
+ *                            *** MIT LICENSE ***
+ * -------------------------------------------------------------------------
+ * This code may be modified and distributed under the MIT license.
+ * See the LICENSE file for details.
+ * -------------------------------------------------------------------------
+ *
+ * @summary   Run a task
+ *
+ * @author    Alvis HT Tang <alvis@hilbert.space>
+ * @license   MIT
+ * @copyright Copyright (c) 2019 - All Rights Reserved.
+ * -------------------------------------------------------------------------
+ */
 import { dirname } from 'node:path';
 import npmRunScript from '@npmcli/run-script';
 import { Listr } from 'listr2';
@@ -6,31 +20,57 @@ import { getPackage } from './package.js';
 import { getScripts } from './preset/index.js';
 import { composeScripts } from './scripts.js';
 import { parseGlobalArgs, parseTaskSpec, selectTasks } from './task.js';
+/**
+ * create an array of Listr tasks based on the provided inputs
+ * @param _ collection of arguments
+ * @param _.composed composed script object containing script definitions
+ * @param _.template template object containing script definitions
+ * @param _.pkg detail of package.json
+ * @param _.task task name
+ * @param _.args array of arguments
+ * @returns array of Listr tasks
+ */
 function createListrTask(_) {
     const { composed, template, task, args, pkg } = _;
     return {
         title: `Running ${task}...`,
         task: async (_, taskControl) => {
             const command = composed[task];
+            // parse the command and extract the executable and task specifications
             const argv = parse(command, {
+                // eslint-disable-next-line @typescript-eslint/naming-convention
                 configuration: { 'populate--': true, 'unknown-options-as-args': true },
             });
             const [executable, ...taskSpecs] = argv._.map((arg) => arg.toString());
+            // check if the executable is 'run-s' or 'run-p'
             if (['run-s', 'run-p'].includes(executable)) {
                 const globalArgs = [...parseGlobalArgs(argv), ...args];
+                // get subtasks based on the task specifications and global arguments
                 const subTasks = taskSpecs.flatMap((taskSpec) => getListrTasksBySpec({ template, pkg, taskSpec, globalArgs }));
                 const concurrent = executable === 'run-p';
                 return taskControl.newListr(subTasks, { concurrent });
             }
             else {
+                // run the npm script with the provided arguments and package information
                 return runWithNPM({ task, args, pkg, composedScript: composed });
             }
         },
     };
 }
+/**
+ * get Listr tasks based on the task specification and global arguments
+ * @param _ collection of arguments
+ * @param _.template template object containing script definitions
+ * @param _.pkg detail of package.json
+ * @param _.taskSpec task specification string
+ * @param _.globalArgs array of global arguments
+ * @returns array of Listr tasks
+ */
 function getListrTasksBySpec(_) {
     const { template, pkg, taskSpec, globalArgs } = _;
+    // parse the task specification and remove any quotes
     const task = parseTaskSpec(taskSpec.toString().replace(/^(['"])([^]*?)\1$/, '$2'), globalArgs);
+    // get Listr tasks based on the provided inputs
     return getListrTasks({
         template,
         pkg,
@@ -38,15 +78,38 @@ function getListrTasksBySpec(_) {
         args: task.args,
     });
 }
+/**
+ * create an array of Listr tasks based on the provided inputs
+ * @param _ collection of arguments
+ * @param _.template template object containing script definitions
+ * @param _.pkg detail of package.json
+ * @param _.selector task selector string
+ * @param _.args array of arguments
+ * @returns array of Listr tasks
+ */
 function getListrTasks(_) {
     const { template, pkg, selector, args } = _;
+    // clone the content for immutability
     const target = { ...pkg.json.scripts };
+    // compose the script using the provided template and target
     const composed = composeScripts({ template, target });
+    // select tasks based on the composed script and selector
     const tasks = selectTasks(Object.keys(composed), selector);
+    // create Listr tasks based on the selected tasks
     return tasks.map((task) => createListrTask({ composed, template, pkg, task, args }));
 }
+/**
+ * run a task defined in the combined script definitions using npm-run-script
+ * @param _ collection of arguments
+ * @param _.task task name
+ * @param _.args array of arguments
+ * @param _.pkg detail of package.json
+ * @param _.composedScript combined script definitions
+ * @returns a promise that will be resolved when the task is completed
+ */
 async function runWithNPM(_) {
     const { task, args, pkg, composedScript } = _;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
     return npmRunScript({
         event: task,
         args,
@@ -55,19 +118,32 @@ async function runWithNPM(_) {
         stdio: 'inherit',
     });
 }
+/**
+ * run a task defined in the combined script definitions.
+ * @param tasks array of objects containing the selector and args for the task
+ * @param options collection of options
+ * @param options.parallel whether to run tasks concurrently
+ * @param options.templateOnly whether to resolve the task from the template only
+ */
 export async function run(tasks, options) {
     const { parallel = false, templateOnly = false } = { ...options };
+    // find the target project's package.json information
     const pkg = await getPackage();
     if (templateOnly) {
+        // remove all scripts from the package.json
         pkg.json.scripts = {};
     }
+    // get the merged script definitions
     const template = await getScripts();
+    // get Listr tasks based on the provided tasks and package information
     const listTasks = tasks.flatMap((task) => getListrTasks({ template, pkg, ...task }));
+    // create a Listr instance with the list of tasks and configuration options
     const listr = new Listr(listTasks, {
         concurrent: parallel,
         exitOnError: true,
         renderer: 'simple',
     });
+    // run the Listr tasks
     try {
         await listr.run();
     }
@@ -75,4 +151,4 @@ export async function run(tasks, options) {
         process.exit(1);
     }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicnVuLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc291cmNlL3J1bi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFlQSxPQUFPLEVBQUUsT0FBTyxFQUFFLE1BQU0sV0FBVyxDQUFDO0FBRXBDLE9BQU8sWUFBWSxNQUFNLG9CQUFvQixDQUFDO0FBQzlDLE9BQU8sRUFBRSxLQUFLLEVBQUUsTUFBTSxRQUFRLENBQUM7QUFFL0IsT0FBTyxLQUFLLE1BQU0sY0FBYyxDQUFDO0FBRWpDLE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSxXQUFXLENBQUM7QUFDdkMsT0FBTyxFQUFFLFVBQVUsRUFBRSxNQUFNLFVBQVUsQ0FBQztBQUN0QyxPQUFPLEVBQUUsY0FBYyxFQUFFLE1BQU0sV0FBVyxDQUFDO0FBQzNDLE9BQU8sRUFBRSxlQUFlLEVBQUUsYUFBYSxFQUFFLFdBQVcsRUFBRSxNQUFNLFFBQVEsQ0FBQztBQWlCckUsU0FBUyxlQUFlLENBQUMsQ0FNeEI7SUFDQyxNQUFNLEVBQUUsUUFBUSxFQUFFLFFBQVEsRUFBRSxJQUFJLEVBQUUsSUFBSSxFQUFFLEdBQUcsRUFBRSxHQUFHLENBQUMsQ0FBQztJQUVsRCxPQUFPO1FBQ0wsS0FBSyxFQUFFLFdBQVcsSUFBSSxLQUFLO1FBQzNCLElBQUksRUFBRSxLQUFLLEVBQUUsQ0FBQyxFQUFFLFdBQVcsRUFBRSxFQUFFO1lBQzdCLE1BQU0sT0FBTyxHQUFHLFFBQVEsQ0FBQyxJQUFJLENBQUMsQ0FBQztZQUcvQixNQUFNLElBQUksR0FBRyxLQUFLLENBQUMsT0FBTyxFQUFFO2dCQUUxQixhQUFhLEVBQUUsRUFBRSxZQUFZLEVBQUUsSUFBSSxFQUFFLHlCQUF5QixFQUFFLElBQUksRUFBRTthQUN2RSxDQUFDLENBQUM7WUFDSCxNQUFNLENBQUMsVUFBVSxFQUFFLEdBQUcsU0FBUyxDQUFDLEdBQUcsSUFBSSxDQUFDLENBQUMsQ0FBQyxHQUFHLENBQUMsQ0FBQyxHQUFHLEVBQUUsRUFBRSxDQUFDLEdBQUcs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
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicnVuLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc291cmNlL3J1bi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7Ozs7Ozs7Ozs7OztHQWFHO0FBRUgsT0FBTyxFQUFFLE9BQU8sRUFBRSxNQUFNLFdBQVcsQ0FBQztBQUVwQyxPQUFPLFlBQVksTUFBTSxvQkFBb0IsQ0FBQztBQUM5QyxPQUFPLEVBQUUsS0FBSyxFQUFFLE1BQU0sUUFBUSxDQUFDO0FBRS9CLE9BQU8sS0FBSyxNQUFNLGNBQWMsQ0FBQztBQUVqQyxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sV0FBVyxDQUFDO0FBQ3ZDLE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSxVQUFVLENBQUM7QUFDdEMsT0FBTyxFQUFFLGNBQWMsRUFBRSxNQUFNLFdBQVcsQ0FBQztBQUMzQyxPQUFPLEVBQUUsZUFBZSxFQUFFLGFBQWEsRUFBRSxXQUFXLEVBQUUsTUFBTSxRQUFRLENBQUM7QUFPckU7Ozs7Ozs7OztHQVNHO0FBQ0gsU0FBUyxlQUFlLENBQUMsQ0FNeEI7SUFDQyxNQUFNLEVBQUUsUUFBUSxFQUFFLFFBQVEsRUFBRSxJQUFJLEVBQUUsSUFBSSxFQUFFLEdBQUcsRUFBRSxHQUFHLENBQUMsQ0FBQztJQUVsRCxPQUFPO1FBQ0wsS0FBSyxFQUFFLFdBQVcsSUFBSSxLQUFLO1FBQzNCLElBQUksRUFBRSxLQUFLLEVBQUUsQ0FBQyxFQUFFLFdBQVcsRUFBRSxFQUFFO1lBQzdCLE1BQU0sT0FBTyxHQUFHLFFBQVEsQ0FBQyxJQUFJLENBQUMsQ0FBQztZQUUvQix1RUFBdUU7WUFDdkUsTUFBTSxJQUFJLEdBQUcsS0FBSyxDQUFDLE9BQU8sRUFBRTtnQkFDMUIsZ0VBQWdFO2dCQUNoRSxhQUFhLEVBQUUsRUFBRSxZQUFZLEVBQUUsSUFBSSxFQUFFLHlCQUF5QixFQUFFLElBQUksRUFBRTthQUN2RSxDQUFDLENBQUM7WUFDSCxNQUFNLENBQUMsVUFBVSxFQUFFLEdBQUcsU0FBUyxDQUFD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

package/lib/scripts.d.ts

@@ -1,8 +1,20 @@
+/** pseudo type for representing the name of a script */
 type ScriptName = string;
+/** pseudo type for representing the command */
 type Command = string;
+/** collection of scripts */
 export type Script = Record<ScriptName, Command>;
+/**
+ * merge the script definitions from the template and the target package.json
+ * @param args template and customized scripts to be merged
+ * @param args.template scripts defined from the template
+ * @param args.target scripts defined from target's package.json
+ * @returns a dictionary of merged definitions
+ */
 export declare function composeScripts(args: {
+    /** scripts defined from the template */
     template: Script;
+    /** scripts defined from target's package.json */
     target: Script;
 }): Script;
 export {};

package/lib/scripts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scripts.d.ts","sourceRoot":"","sources":["../source/scripts.ts"],"names":[],"mappings":"AAyBA,KAAK,UAAU,GAAG,MAAM,CAAC;AAGzB,KAAK,OAAO,GAAG,MAAM,CAAC;AAGtB,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAyBjD,wBAAgB,cAAc,CAAC,IAAI,EAAE;IAEnC,QAAQ,EAAE,MAAM,CAAC;IAEjB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CA4BT"}
+{"version":3,"file":"scripts.d.ts","sourceRoot":"","sources":["../source/scripts.ts"],"names":[],"mappings":"AAwBA,wDAAwD;AACxD,KAAK,UAAU,GAAG,MAAM,CAAC;AAEzB,+CAA+C;AAC/C,KAAK,OAAO,GAAG,MAAM,CAAC;AAEtB,4BAA4B;AAC5B,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAkBjD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CA4BT"}

package/lib/scripts.js

@@ -1,20 +1,47 @@
+/*
+ *                            *** MIT LICENSE ***
+ * -------------------------------------------------------------------------
+ * This code may be modified and distributed under the MIT license.
+ * See the LICENSE file for details.
+ * -------------------------------------------------------------------------
+ *
+ * @summary   Handle script merging
+ *
+ * @author    Alvis HT Tang <alvis@hilbert.space>
+ * @license   MIT
+ * @copyright Copyright (c) 2019 - All Rights Reserved.
+ * -------------------------------------------------------------------------
+ */
 import { basename } from 'node:path';
 import mvdan from 'mvdan-sh';
 import parse from 'yargs-parser';
 import { mapValues } from './utilities/index.js';
 const { syntax } = mvdan;
+// shell command parser
 const parser = syntax.NewParser();
+// shell command generator
 const printer = syntax.NewPrinter();
+/**
+ * merge the script definitions from the template and the target package.json
+ * @param args template and customized scripts to be merged
+ * @param args.template scripts defined from the template
+ * @param args.target scripts defined from target's package.json
+ * @returns a dictionary of merged definitions
+ */
 export function composeScripts(args) {
     const { template, target } = args;
     return mapValues({ ...template, ...target }, (command) => {
         try {
+            // parse the shell command into its ast
             const ast = parser.Parse(command);
+            // walk through the tree and replace any call to the runner e.g. preset task1 task2 -- --help
             syntax.Walk(ast, (node) => replaceRunnerNode(node, { template, target }));
+            // remove any unnecessary subshell
             const [statement] = ast.Stmts;
             if (isNodeType(statement.Cmd, 'Subshell')) {
                 statement.Cmd = statement.Cmd.Stmts[0].Cmd;
             }
+            // generate the code from ast
             return printer.Print(ast).trim();
         }
         catch (error) {
@@ -22,6 +49,7 @@ export function composeScripts(args) {
                 throw error;
             }
             else {
+                // parser.Parse may throw an empty object as an error, catch here
                 throw new Error(`failed to parse command: ${command}`);
             }
         }
@@ -30,12 +58,21 @@ export function composeScripts(args) {
 function isNodeType(node, type) {
     return syntax.NodeType(node) === type;
 }
+/**
+ * resolve a runner command
+ * @param command the command to be replaced
+ * @param context resource context
+ * @returns the resolved command
+ */
 function resolveRunner(command, context) {
     const arg = parse(command, {
+        // eslint-disable-next-line @typescript-eslint/naming-convention
         configuration: { 'populate--': true, 'unknown-options-as-args': true },
     });
+    // extract tasks and their arguments
     const destinations = arg['_'].slice(1);
     const destinationArgs = arg['--'] ?? [];
+    // resolve tasks into its full form e.g. task1 task2
     return destinations
         .map((destination) => {
         const expandedCommand = context.template[destination] ||
@@ -49,15 +86,27 @@ function resolveRunner(command, context) {
     })
         .join(' && ');
 }
+/**
+ * replace a runner node with the actual command
+ * @param node an expression node
+ * @param context resource context
+ * @returns boolean true for no error
+ */
 function replaceRunnerNode(node, context) {
+    // replace only it's a runner call, not anything else
     if (isNodeType(node, 'Stmt') && isNodeType(node.Cmd, 'CallExpr')) {
+        // parse assigned arguments e.g. task1 args --help
         const parts = node.Cmd.Args.map((part) => part.Lit());
+        // only resolve if the `run` cli shipped in this package is invoke
         if (parts.length && basename(parts[0]) === 'run') {
+            // resolve tasks into its full form e.g. task1 task2
             const resolvedCommand = resolveRunner(parts.join(' '), context);
+            // replace the task definition with its expanded statement
             node.Cmd = parser.Parse(`(${resolvedCommand})`).Stmts[0].Cmd;
+            // recursively replace any runner call in the expanded statement
             replaceRunnerNode(node.Cmd, context);
         }
     }
     return true;
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2NyaXB0cy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NvdXJjZS9zY3JpcHRzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQWVBLE9BQU8sRUFBRSxRQUFRLEVBQUUsTUFBTSxXQUFXLENBQUM7QUFFckMsT0FBTyxLQUFLLE1BQU0sVUFBVSxDQUFDO0FBQzdCLE9BQU8sS0FBSyxNQUFNLGNBQWMsQ0FBQztBQUVqQyxPQUFPLEVBQUUsU0FBUyxFQUFFLE1BQU0sYUFBYSxDQUFDO0FBYXhDLE1BQU0sRUFBRSxNQUFNLEVBQUUsR0FBRyxLQUFLLENBQUM7QUFHekIsTUFBTSxNQUFNLEdBQUcsTUFBTSxDQUFDLFNBQVMsRUFBRSxDQUFDO0FBR2xDLE1BQU0sT0FBTyxHQUFHLE1BQU0sQ0FBQyxVQUFVLEVBQUUsQ0FBQztBQWlCcEMsTUFBTSxVQUFVLGNBQWMsQ0FBQyxJQUs5QjtJQUNDLE1BQU0sRUFBRSxRQUFRLEVBQUUsTUFBTSxFQUFFLEdBQUcsSUFBSSxDQUFDO0lBRWxDLE9BQU8sU0FBUyxDQUFDLEVBQUUsR0FBRyxRQUFRLEVBQUUsR0FBRyxNQUFNLEVBQUUsRUFBRSxDQUFDLE9BQU8sRUFBVSxFQUFFO1FBQy9ELElBQUk7WUFFRixNQUFNLEdBQUcsR0FBRyxNQUFNLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxDQUFDO1lBR2xDLE1BQU0sQ0FBQyxJQUFJLENBQUMsR0FBRyxFQUFFLENBQUMsSUFBSSxFQUFFLEVBQUUsQ0FBQyxpQkFBaUIsQ0FBQyxJQUFJLEVBQUUsRUFBRSxRQUFRLEVBQUUsTUFBTSxFQUFFLENBQUMsQ0FBQyxDQUFDO1lBRzFFLE1BQU0sQ0FBQyxTQUFTLENBQUMsR0FBRyxHQUFHLENBQUMsS0FBSyxDQUFDO1lBQzlCLElBQUksVUFBVSxDQUFDLFNBQVMsQ0FBQyxHQUFHLEVBQUUsVUFBVSxDQUFDLEVBQUU7Z0JBQ3pDLFNBQVMsQ0FBQyxHQUFHLEdBQUcsU0FBUyxDQUFDLEdBQUcsQ0FBQyxLQUFLLENBQUMs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
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2NyaXB0cy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NvdXJjZS9zY3JpcHRzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7O0dBYUc7QUFFSCxPQUFPLEVBQUUsUUFBUSxFQUFFLE1BQU0sV0FBVyxDQUFDO0FBRXJDLE9BQU8sS0FBSyxNQUFNLFVBQVUsQ0FBQztBQUM3QixPQUFPLEtBQUssTUFBTSxjQUFjLENBQUM7QUFFakMsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQWF4QyxNQUFNLEVBQUUsTUFBTSxFQUFFLEdBQUcsS0FBSyxDQUFDO0FBRXpCLHVCQUF1QjtBQUN2QixNQUFNLE1BQU0sR0FBRyxNQUFNLENBQUMsU0FBUyxFQUFFLENBQUM7QUFFbEMsMEJBQTBCO0FBQzFCLE1BQU0sT0FBTyxHQUFHLE1BQU0sQ0FBQyxVQUFVLEVBQUUsQ0FBQztBQVVwQzs7Ozs7O0dBTUc7QUFDSCxNQUFNLFVBQVUsY0FBYyxDQUFDLElBSzlCO0lBQ0MsTUFBTSxFQUFFLFFBQVEsRUFBRSxNQUFNLEVBQUUsR0FBRyxJQUFJLENBQUM7SUFFbEMsT0FBTyxTQUFTLENBQUMsRUFBRSxHQUFHLFFBQVEsRUFBRSxHQUFHLE1BQU0sRUFBRSxFQUFFLENBQUMsT0FBTyxFQUFVLEVBQUU7UUFDL0QsSUFBSTtZQUNGLHVDQUF1QztZQUN2QyxNQUFNLEdBQUcsR0FBRyxNQUFNLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxDQUFDO1lBRWxDLDZGQUE2RjtZQUM3RixNQUFNLENBQUMsSUFBSSxDQUFDLEdBQUcsRUFBRSxDQUFDLElBQUksRUFBRSxFQUFFLENBQUMsaUJBQWlCLENBQUMsSUFBSSxFQUFFLEVBQUUsUUFBUSxFQUFFLE1BQU0sRUFBRSxDQUFDLENBQUMsQ0FBQztZQUUxRSxrQ0FBa0M7WUFDbEMsTUFBTSxDQUFDLFNBQVMsQ0FBQyxHQUFHLEdBQUcsQ0FBQyxLQUFLLENBQUM7WUFDOUIsSUFBSSxV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

package/lib/task.d.ts

@@ -1,9 +1,27 @@
 import type { Arguments } from 'yargs-parser';
+/** parsed task object with selector and args */
 export interface Task {
     selector: string;
     args: string[];
 }
+/**
+ * parse global arguments from an argv object
+ * @param argv - an arguments object containing the command line arguments
+ * @returns an array of cleaned up global arguments as strings
+ */
 export declare function parseGlobalArgs(argv: Arguments): string[];
+/**
+ * parse task string and return a parsed task object with selector and args
+ * @param spec - the task string to parse
+ * @param globalArgs - the global arguments to be added to each task
+ * @returns parsed task object with selector and args
+ */
 export declare function parseTaskSpec(spec: string, globalArgs: string[]): Task;
+/**
+ * select tasks based on a pattern
+ * @param tasks array of available tasks in the format 'task:subtask:subsubtask'
+ * @param pattern pattern to match tasks ('*' wildcard for single level and '**' wildcard for multiple levels)
+ * @returns array of tasks that match the pattern
+ */
 export declare function selectTasks(tasks: string[], pattern: string): string[];
 //# sourceMappingURL=task.d.ts.map

package/lib/task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../source/task.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAG9C,MAAM,WAAW,IAAI;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAOD,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,EAAE,CAWzD;AAQD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,CAiBtE;AAQD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBtE"}
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../source/task.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,gDAAgD;AAChD,MAAM,WAAW,IAAI;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,EAAE,CAWzD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,CAiBtE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBtE"}

package/lib/task.js

@@ -1,15 +1,47 @@
+/*
+ *                            *** MIT LICENSE ***
+ * -------------------------------------------------------------------------
+ * This code may be modified and distributed under the MIT license.
+ * See the LICENSE file for details.
+ * -------------------------------------------------------------------------
+ *
+ * @summary   Helper functions for parsing task strings
+ *
+ * @author    Alvis HT Tang <alvis@hilbert.space>
+ * @license   MIT
+ * @copyright Copyright (c) 2019 - All Rights Reserved.
+ * -------------------------------------------------------------------------
+ */
 import parse from 'yargs-parser';
+/**
+ * parse global arguments from an argv object
+ * @param argv - an arguments object containing the command line arguments
+ * @returns an array of cleaned up global arguments as strings
+ */
 export function parseGlobalArgs(argv) {
+    // get the global arguments as an array of strings or numbers, or undefined if not present
     const globalArgs = argv['--'];
-    return (globalArgs?.map((arg) => arg.toString().replace(/^(['"])([^]*?)\1$/, '$2')) ?? []);
+    // if global arguments are present, map them to strings and clean up the quotes
+    return (globalArgs?.map((arg) => 
+    // replace the single or double quotes that wrap the argument
+    arg.toString().replace(/^(['"])([^]*?)\1$/, '$2')) ?? [] // if no global arguments are present, return an empty array
+    );
 }
+/**
+ * parse task string and return a parsed task object with selector and args
+ * @param spec - the task string to parse
+ * @param globalArgs - the global arguments to be added to each task
+ * @returns parsed task object with selector and args
+ */
 export function parseTaskSpec(spec, globalArgs) {
     const argv = parse(spec, {
+        // eslint-disable-next-line @typescript-eslint/naming-convention
         configuration: { 'populate--': true },
     });
     const selector = argv._[0];
     const args = parseGlobalArgs(argv).reduce((processedArgs, arg) => {
         if (arg === '{@}') {
+            // replace {@} with globalArgs
             return [...processedArgs, ...globalArgs];
         }
         else {
@@ -18,6 +50,12 @@ export function parseTaskSpec(spec, globalArgs) {
     }, []);
     return { selector, args };
 }
+/**
+ * select tasks based on a pattern
+ * @param tasks array of available tasks in the format 'task:subtask:subsubtask'
+ * @param pattern pattern to match tasks ('*' wildcard for single level and '**' wildcard for multiple levels)
+ * @returns array of tasks that match the pattern
+ */
 export function selectTasks(tasks, pattern) {
     const regexPattern = pattern
         .split(':')
@@ -34,4 +72,4 @@ export function selectTasks(tasks, pattern) {
     const regex = new RegExp(`^${regexPattern}$`);
     return tasks.filter((task) => regex.test(task));
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidGFzay5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NvdXJjZS90YXNrLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQWVBLE9BQU8sS0FBSyxNQUFNLGNBQWMsQ0FBQztBQWVqQyxNQUFNLFVBQVUsZUFBZSxDQUFDLElBQWU7SUFFN0MsTUFBTSxVQUFVLEdBQUcsSUFBSSxDQUFDLElBQUksQ0FBQyxDQUFDO0lBRzlCLE9BQU8sQ0FDTCxVQUFVLEVBQUUsR0FBRyxDQUFDLENBQUMsR0FBRyxFQUFFLEVBQUUsQ0FFdEIsR0FBRyxDQUFDLFFBQVEsRUFBRSxDQUFDLE9BQU8sQ0FBQyxtQkFBbUIsRUFBRSxJQUFJLENBQUMsQ0FDbEQsSUFBSSxFQUFFLENBQ1IsQ0FBQztBQUNKLENBQUM7QUFRRCxNQUFNLFVBQVUsYUFBYSxDQUFDLElBQVksRUFBRSxVQUFvQjtJQUM5RCxNQUFNLElBQUksR0FBRyxLQUFLLENBQUMsSUFBSSxFQUFFO1FBRXZCLGFBQWEsRUFBRSxFQUFFLFlBQVksRUFBRSxJQUFJLEVBQUU7S0FDdEMsQ0FBQyxDQUFDO0lBRUgsTUFBTSxRQUFRLEdBQUcsSUFBSSxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQVcsQ0FBQztJQUNyQyxNQUFNLElBQUksR0FBRyxlQUFlLENBQUMsSUFBSSxDQUFDLENBQUMsTUFBTSxDQUFDLENBQUMsYUFBYSxFQUFFLEdBQUcsRUFBRSxFQUFFO1FBQy9ELElBQUksR0FBRyxLQUFLLEtBQUssRUFBRTtZQUVqQixPQUFPLENBQUMsR0FBRyxhQUFhLEVBQUUsR0FBRyxVQUFVLENBQUMsQ0FBQztTQUMxQzthQUFNO1lBQ0wsT0FBTyxDQUFDLEdBQUcsYUFBYSxFQUFFLEdBQUcsQ0FBQyxDQUFDO1NBQ2hDO0lBQ0gsQ0FBQyxFQUFFLEVBQWMsQ0FBQyxDQUFDO0lBRW5CLE9BQU8sRUFBRSxRQUFRLEVBQUUsSUFBSSxFQUFFLENBQUM7QUFDNUIsQ0FBQztBQVFELE1BQU0sVUFBVSxXQUFXLENBQUMsS0FBZSxFQUFFLE9BQWU7SUFDMUQsTUFBTSxZQUFZLEdBQUcsT0FBTztTQUN6QixLQUFLLENBQUMsR0FBRyxDQUFDO1NBQ1YsR0FBRyxDQUFDLENBQUMsSUFBSSxFQUFFLEVBQUU7UUFDWixJQUFJLElBQUksS0FBSyxHQUFHLEVBQUU7WUFDaEIsT0FBTyxPQUFPLENBQUM7U0FDaEI7UUFDRCxJQUFJLElBQUksS0FBSyxJQUFJLEVBQUU7WUFDakIsT0FBTyxJQUFJLENBQUM7U0FDYjtRQUVELE9BQU8sSUFBSSxDQUFDO0lBQ2QsQ0FBQyxDQUFDO1NBQ0QsSUFBSSxDQUFDLEdBQUcsQ0FBQyxDQUFDO0lBRWIsTUFBTSxLQUFLLEdBQUcsSUFBSSxNQUFNLENBQUMsSUFBSSxZQUFZLEdBQUcsQ0FBQyxDQUFDO0lBRTlDLE9BQU8sS0FBSyxDQUFDLE1BQU0sQ0FBQyxDQUFDLElBQUksRUFBRSxFQUFFLENBQUMsS0FBSyxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDO0FBQ2xELENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidGFzay5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NvdXJjZS90YXNrLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7O0dBYUc7QUFFSCxPQUFPLEtBQUssTUFBTSxjQUFjLENBQUM7QUFVakM7Ozs7R0FJRztBQUNILE1BQU0sVUFBVSxlQUFlLENBQUMsSUFBZTtJQUM3QywwRkFBMEY7SUFDMUYsTUFBTSxVQUFVLEdBQUcsSUFBSSxDQUFDLElBQUksQ0FBQyxDQUFDO0lBRTlCLCtFQUErRTtJQUMvRSxPQUFPLENBQ0wsVUFBVSxFQUFFLEdBQUcsQ0FBQyxDQUFDLEdBQUcsRUFBRSxFQUFFO0lBQ3RCLDZEQUE2RDtJQUM3RCxHQUFHLENBQUMsUUFBUSxFQUFFLENBQUMsT0FBTyxDQUFDLG1CQUFtQixFQUFFLElBQUksQ0FBQyxDQUNsRCxJQUFJLEVBQUUsQ0FBQyw0REFBNEQ7S0FDckUsQ0FBQztBQUNKLENBQUM7QUFFRDs7Ozs7R0FLRztBQUNILE1BQU0sVUFBVSxhQUFhLENBQUMsSUFBWSxFQUFFLFVBQW9CO0lBQzlELE1BQU0sSUFBSSxHQUFHLEtBQUssQ0FBQyxJQUFJLEVBQUU7UUFDdkIsZ0VBQWdFO1FBQ2hFLGFBQWEsRUFBRSxFQUFFLFlBQVksRUFBRSxJQUFJLEVBQUU7S0FDdEMsQ0FBQyxDQUFDO0lBRUgsTUFBTSxRQUFRLEdBQUcsSUFBSSxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQVcsQ0FBQztJQUNyQyxNQUFNLElBQUksR0FBRyxlQUFlLENBQUMsSUFBSSxDQUFDLENBQUMsTUFBTSxDQUFDLENBQUMsYUFBYSxFQUFFLEdBQUcsRUFBRSxFQUFFO1FBQy9ELElBQUksR0FBRyxLQUFLLEtBQUssRUFBRTtZQUNqQiw4QkFBOEI7WUFDOUIsT0FBTyxDQUFDLEdBQUcsYUFBYSxFQUFFLEdBQUcsVUFBVSxDQUFDLENBQUM7U0FDMUM7YUFBTTtZQUNMLE9BQU8sQ0FBQyxHQUFHLGFBQWEsRUFBRSxHQUFHLENBQUMsQ0FBQztTQUNoQztJQUNILENBQUMsRUFBRSxFQUFjLENBQUMsQ0FBQztJQUVuQixPQUFPLEVBQUUsUUFBUSxFQUFFLElBQUksRUFBRSxDQUFDO0FBQzVCLENBQUM7QUFFRDs7Ozs7R0FLRztBQUNILE1BQU0sVUFBVSxXQUFXLENBQUMsS0FBZSxFQUFFLE9BQWU7SUFDMUQsTUFBTSxZQUFZLEdBQUcsT0FBTztTQUN6QixLQUFLLENBQUMsR0FBRyxDQUFDO1NBQ1YsR0FBRyxDQUFDLENBQUMsSUFBSSxFQUFFLEVBQUU7UUFDWixJQUFJLElBQUksS0FBSyxHQUFHLEVBQUU7WUFDaEIsT0FBTyxPQUFPLENBQUM7U0FDaEI7UUFDRCxJQUFJLElBQUksS0FBSyxJQUFJLEVBQUU7WUFDakIsT0FBTyxJQUFJLENBQUM7U0FDYjtRQUVELE9BQU8sSUFBSSxDQUFDO0lBQ2QsQ0FBQyxDQUFDO1NBQ0QsSUFBSSxDQUFDLEdBQUcsQ0FBQyxDQUFDO0lBRWIsTUFBTSxLQUFLLEdBQUcsSUFBSSxNQUFNLENBQUMsSUFBSSxZQUFZLEdBQUcsQ0FBQyxDQUFDO0lBRTlDLE9BQU8sS0FBSyxDQUFDLE1BQU0sQ0FBQyxDQUFDLElBQUksRUFBRSxFQUFFLENBQUMsS0FBSyxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDO0FBQ2xELENBQUMifQ==

package/lib/template.d.ts

@@ -2,14 +2,61 @@ import type { IgnoreRule, PrimitiveEntity } from 'presetter-types';
 import type { JsonObject, JsonValue } from 'type-fest';
 type MergedType<A, B> = A extends JsonObject ? B extends JsonObject ? A & B : MergedArray<A, B> : MergedArray<A, B>;
 type MergedArray<A, B> = A extends JsonValue[] ? B extends JsonValue[] ? Array<A[number] | B[number]> : keyof B extends `${number}` ? JsonValue[] : B : B;
+/**
+ * remove part of the template content according to the given rules
+ * @param subject an object to be filtered
+ * @param ignores a list of ignore rules
+ * @returns filtered content
+ */
 export declare function filter<C extends Record<string, unknown>>(subject: C, ...ignores: IgnoreRule[]): C;
 export declare function filter(subject: unknown[], ...ignores: IgnoreRule[]): unknown[];
+/**
+ * indicate whether the supplied value is a JSON object
+ * @param subject the subject to be tested
+ * @returns true if the subject is a JSON object
+ */
 export declare function isJSON(subject: unknown): subject is JsonObject;
+/**
+ * deep merge an object
+ * @param source default object if no additional property is supplied
+ * @param target properties to be merged with the default
+ * @returns merged object
+ */
 export declare function merge<S extends JsonValue, T extends PrimitiveEntity>(source: S, target?: T): MergedType<S, T>;
+/**
+ * merge an array with any value
+ * @param source the source array to be merged
+ * @param target new replacement
+ * @returns merged value
+ */
 export declare function mergeArray<S extends JsonValue, T extends PrimitiveEntity>(source: S[], target?: T): MergedArray<S[], T>;
+/**
+ * merge two arrays
+ * @param source the source array to be merged
+ * @param target new replacement
+ * @returns merged array
+ */
 export declare function mergeArrays<S extends JsonValue, T extends JsonValue>(source: S[], target: T[]): MergedArray<S[], T[]>;
+/**
+ * merge an object with any value
+ * @param source the source object to be merged
+ * @param target new replacement
+ * @returns merged value
+ */
 export declare function mergeObject<S extends JsonObject, T extends PrimitiveEntity>(source: S, target?: T): MergedType<S, T>;
+/**
+ * merge templates
+ * @param source current template
+ * @param target new template content
+ * @returns customized configuration
+ */
 export declare function mergeTemplate(source: Record<string, JsonObject | string>, target: Record<string, JsonObject | string>): Record<string, JsonObject | string>;
+/**
+ * replace parameters in the template
+ * @param content template content
+ * @param parameter variables to be substituted in the template
+ * @returns customized configuration
+ */
 export declare function template(content: string, parameter: Record<string, string>): string;
 export declare function template<Content extends Record<string, unknown> | unknown[]>(content: Content, parameter: Record<string, string>): Content;
 export declare function template(content: unknown, parameter: Record<string, string>): unknown;

package/lib/template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../source/template.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAc,UAAU,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEvD,KAAK,UAAU,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,UAAU,GACxC,CAAC,SAAS,UAAU,GAClB,CAAC,GAAG,CAAC,GACL,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GACnB,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAEtB,KAAK,WAAW,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,SAAS,EAAE,GAC1C,CAAC,SAAS,SAAS,EAAE,GACnB,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAC5B,MAAM,CAAC,SAAS,GAAG,MAAM,EAAE,GAC3B,SAAS,EAAE,GACX,CAAC,GACH,CAAC,CAAC;AAQN,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtD,OAAO,EAAE,CAAC,EACV,GAAG,OAAO,EAAE,UAAU,EAAE,GACvB,CAAC,CAAC;AACL,wBAAgB,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,EAAE,CAAC;AAgEhF,wBAAgB,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,UAAU,CAM9D;AAUD,wBAAgB,KAAK,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,eAAe,EAClE,MAAM,EAAE,CAAC,EACT,MAAM,CAAC,EAAE,CAAC,GACT,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAclB;AAQD,wBAAgB,UAAU,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,eAAe,EACvE,MAAM,EAAE,CAAC,EAAE,EACX,MAAM,CAAC,EAAE,CAAC,GACT,WAAW,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAmBrB;AAQD,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,SAAS,EAClE,MAAM,EAAE,CAAC,EAAE,EACX,MAAM,EAAE,CAAC,EAAE,GACV,WAAW,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAuBvB;AAQD,wBAAgB,WAAW,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,eAAe,EACzE,MAAM,EAAE,CAAC,EACT,MAAM,CAAC,EAAE,CAAC,GACT,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAmBlB;AAQD,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,EAC3C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,GAC1C,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,CAgCrC;AAQD,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,MAAM,CAAC;AACV,wBAAgB,QAAQ,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE,EAC1E,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,OAAO,CAAC;AACX,wBAAgB,QAAQ,CACtB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,OAAO,CAAC"}
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../source/template.ts"],"names":[],"mappings":"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"}