@noresources/command 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @noresources/command
+
+A lightweight command line interface definition package focusing on reusability, extensibility and a clean API.
+
+## Installation
+
+```
+npm install --save @noresources/command
+```
+
+## Features
+
+* Plain object based command component descriptors
+	* Program
+	* Command, subcommands
+	* Option
+	* Positional
+	* Parameter (option and positional argument value type)
+* Chain-based program builder API
+* Exporter to well-known command packages
+	* [Commander.js](https://github.com/tj/commander.js/)
+
+## Examples
+
+### Component descriptors
+
+Commands, options and positional arguments can be declared using a simple plain javascript object.
+
+```javascript
+export const Verbosity = {
+	'type': 'counter',
+	'documentation': 'Verbosity level',
+	'initial': 0,
+	'names': ['verbosity', 'v']
+};
+```
+
+Then, a factory function will creates the correct class instance.
+
+```javascript
+import { createOption } from "@noresources/command"
+const option = createOption(Verbosity);
+```
+### Builder API
+
+The `ProgramBuilder` class provides a fluent interface to define the whole program interface using method chaining.
+
+```javascript
+import { ProgramBuilder } from "@noresources/command"
+
+const builder = new ProgramBuilder;
+builder.name('chatbot')
+	.version('1.2.3')
+	.option(Verbosity) // out option descriptor presented above.
+	.positional({
+		documentation: 'Some text to insert in conversation'
+	}).handler(function (input) {
+			if (input.options.verbosity > 2) console.log('Bark bark')
+			if (input.arguments.length)
+				console.log (input.arguments[0])
+			console.log ('This program is not really meaningful'),
+	})
+```
+### Exporter to commander.js
+
+For now, this package does not provide a command line parser by itself. It relies on well established parser [Commander.js](https://www.npmjs.com/package/commander)a to for parsing. 
+
+Converting a `@noresources/command` program to a `Commander.js` command is made with a simple function call.
+
+```javascript
+import {	createCommand } from '@noresources/command/commander'
+
+const command = createCommand(builder.program); // assuming builder is the ProgramBuilder instance defined above.
+command.parse ();
+``` 
+Note that the `commander` package is not included in `@noresources/command` package dependencies. You have to install it manually to usie this feature.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/package.json

@@ -1,6 +1,46 @@
 {
-  "name": "@noresources/command",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+	"name": "@noresources/command",
+	"version": "0.1.1",
+	"description": "A lightweight command line interface definition package focusing on reusability, extensibility and a clean API",
+	"main": "index.js",
+	"scripts": {
+		"test": "tape tests/tape/*.mjs",
+		"lint": "eslint --fix",
+		"doc": "jsdoc --recurse -c resources/jsdoc/configuration.json --readme README.md --tutorials resources/jsdoc/tutorials --destination doc src/"
+	},
+	"keywords": [
+
+	],
+	"author": "",
+	"license": "ISC",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/noresources/js-command.git"
+	},
+	"dependencies": {
+		"@noresources/core": "^0.2.0"
+	},
+	"devDependencies": {
+		"commander": "^15.0.0",
+		"tape": "^5.10.2"
+	},
+	"type": "module",
+	"files": [
+		"./src"
+	],
+	"module": "./index.mjs",
+	"exports": {
+		".": [
+			{
+				"import": "./index.mjs"
+			},
+			"./index.mjs"
+		],
+		"./src/lib/options": [
+			{
+				"import": "./src/lib/options/index.mjs"
+			},
+			"./src/lib/options/index.mjs"
+		]
+	}
 }

package/src/Builders.mjs

@@ -0,0 +1,368 @@
+'use strict';
+
+import {
+	merge
+} from '@noresources/core';
+
+import {
+	createOption,
+	Option
+} from './Options.mjs';
+
+import {
+	Parameter,
+	createParameter
+} from './Parameters.mjs';
+
+import {
+	createPositional,
+	Positional,
+	PositionalValue
+} from './Positionals.mjs';
+
+import {
+	Command,
+	Program
+} from './Command.mjs';
+
+
+/**
+ * Internal function to process and register a command descriptor with the builder.
+ * This method abstracts the logic of determining if the input is a Command object
+ * or a raw descriptor object before adding it to the builder's structure.
+ * @param {CommandBaseBuilder} builder - The CommandBuilder instance managing the current context.
+ * @param {object} descriptor - The raw or instantiated command definition object.
+ * @private
+ */
+function addCommand (builder, descriptor) {
+	let c;
+	let b;
+	if (descriptor instanceof Command) {
+		c = descriptor;
+		b = new CommandBuilder(c, builder.parent);
+	} else {
+		const argument = merge ({}, descriptor);
+
+		delete argument.options;
+		delete argument.positionals;
+		delete argument.commands;
+
+		c = new Command(argument);
+		b = new CommandBuilder(c, builder.parent);
+
+		if ( Array.isArray(descriptor.options) ) {
+			for (const o of descriptor.options) {
+				addOption(b, o);
+			}
+		}
+
+		if ( Array.isArray(descriptor.positionals) ) {
+			for (const p of descriptor.positionals) {
+				addParameter(b, p);
+			}
+		}
+
+		if ( Array.isArray(descriptor.commands) ) {
+			for (const cd of descriptor.commands) {
+				addCommand(b, cd);
+			}
+		}
+
+	}
+	builder._object.commands.push (c);
+	builder._commands.push (b);
+	return b;
+}
+
+function addOption (builder, descriptor) {
+	const o = (descriptor instanceof Option)
+		? descriptor
+		: builder.optionFactory(descriptor);
+	builder._object.options.push (o);
+}
+
+function addParameter (builder, descriptor) {
+	let p;
+	if (descriptor instanceof Parameter) {
+		descriptor = new PositionalValue({
+			'parameter': descriptor
+		});
+	}
+
+	p = (descriptor instanceof Positional)
+		? descriptor
+		: builder.positionalFactory(descriptor);
+
+	builder._object.positionals.push (p);
+}
+
+/**
+ * @class CommandBaseBuilder
+ * @description Base class providing common chaining methods (like `command`, `option`, `positional`)
+ * and property accessors for command structures. It is designed to be extended by
+ * `CommandBuilder` or `ProgramBuilder` to define specific program or command behavior.
+ * @property {object} _object - The underlying representation (Command or Program) being configured.
+ * @property {Array<CommandBuilder|ProgramBuilder>} _commands - Internal array tracking child builders.
+ */
+class CommandBaseBuilder {
+	/**
+	 * @constructor
+	 * @param {object} object - The root data structure (e.g., Command object) that this builder is manipulating.
+	 */
+	constructor(object) {
+		this._object = object;
+		this._commands = [];
+	}
+
+
+	/**
+	 * @command
+	 * @description Attaches a new command definition to the current builder's context.
+	 * This method allows for the creation of nested commands (subcommands) within the current scope.
+	 * @param {Command | object} descriptor - The definition of the new command. This can be a fully
+	 * instantiated Command object or a raw configuration object containing options, positionals, and subcommands.
+	 * @returns {CommandBuilder} A new instance of the builder specifically for the newly created subcommand, allowing for further configuration chaining.
+ */
+	command (descriptor) {
+		return addCommand(this, descriptor);
+	}
+
+	/**
+	 * @option
+	 * @description Configures and registers an option (flag or argument) on the current command definition.
+	 * Options define optional arguments that the command can consume.
+	 * @param {object} descriptor - The option definition object. This object dictates the name, type, and optionality of the argument.
+	 * @returns {CommandBaseBuilder} The current instance of the builder, enabling method chaining.
+	 */
+	option (descriptor) {
+		addOption(this, descriptor);
+		return this;
+	}
+
+	/**
+	 * @positional
+	 * @description Configures and registers a required positional parameter for the current command.
+	 * Positional parameters are arguments provided by the user that do not have a name (e.g., file names in 'git checkout <file>').
+	 * @param {object} descriptor - The positional parameter definition. This defines constraints like type or description.
+	 * @returns {CommandBaseBuilder} The current instance of the builder, enabling method chaining.
+	 */
+	positional (descriptor) {
+		addParameter(this, descriptor);
+		return this;
+	}
+
+	/**
+	 * @handler
+	 * @description Sets the primary execution handler for this command structure.
+	 * This function will be invoked by the runtime when the command is executed.
+	 * @param {function(object): void} callback - The callback function that receives the parsed arguments/context and performs the core logic. It is expected to not return a value.
+	* @returns {CommandBaseBuilder} The current builder instance, allowing for method chaining.
+	 * @notes If the handler is set, it provides the final action for this command chain.
+	 */
+	handler (callback) {
+		this._object.handler = callback;
+		return this;
+	}
+
+	/**
+	 * @property {function(): function} parameterFactory
+	 * @description The function used internally to create Parameter objects.
+	 * @returns {function} The parameter creation function.
+	 */
+	get parameterFactory () {
+		return this._parameterFactory || createParameter;
+	}
+
+	/**
+	 * @property {function(): function} optionFactory
+	 * @description The function used internally to create Option objects.
+	 * @returns {function} The option creation function.
+	 */
+	get optionFactory () {
+		return this._optionFactory;
+	}
+
+	/**
+	 * @property {function(): function} positionalFactory
+	 * @description The function used internally to create PositionalValue objects.
+	 * @returns {function} The positional value creation function.
+	 */
+	get positionalFactory () {
+		return this._positionalFactory;
+	}
+
+	/**
+	 * @setter
+	 * @description Overrides the default parameter creation mechanism, allowing advanced customization of parameter behavior.
+	 * @param {function} parameterFactory - The custom function to be used by the builder to construct parameters.
+	 * @throws {Error} If the provided `parameterFactory` is not a function.
+	 */
+	set parameterFactory (parameterFactory) {
+		if (typeof parameterFactory !== 'function') {
+			throw new Error ('Invalid parameter factory. Parameter is not a function');
+		}
+		this._parameterFactory = parameterFactory;
+		const thisArg = {parameterFactory};
+		this._optionFactory = createOption.bind (thisArg);
+		this._positionalFactory = createPositional.bind(thisArg);
+	}
+}
+
+/**
+ * @class CommandBuilder
+ * @extends CommandBaseBuilder
+ * @description Represents a single, specific command within the overall application structure.
+ * This builder manages the configuration (name, aliases, options, subcommands) of one command
+ * and provides the interface to manipulate it before it is instantiated.
+ */
+export class CommandBuilder extends CommandBaseBuilder {
+	/**
+	 * @constructor
+	 * @param {Command | CommandBuilder | ProgramBuilder} command - The existing Command or builder object this context is operating on.
+	 * @param {CommandBuilder|ProgramBuilder} parent - The parent builder context that contains this command.
+	 * @description Initializes the command builder. The parent reference is critical for hierarchical traversal (e.g., finding the root Program).
+	 */
+	constructor (command, parent) {
+		super (command || new Command );
+		this._parent = parent;
+		this.parameterFactory = (parent)
+			? (parent.parameterFactory || createParameter)
+			: createParameter;
+
+	}
+
+	/**
+	 * @property {Command} object
+	 * @description Getter that exposes the underlying Command object that this builder is configuring.
+	 * @returns {Command} The actual Command instance, allowing inspection or modification of its state.
+	 */
+	get object () {
+		return this._object;
+	}
+
+	/**
+	 * @property {ProgramBuilder|null} program
+	 * @description Traverses up the chain of builders (CommandBuilder -> ProgramBuilder) to locate the root ProgramBuilder.
+	 * @returns {ProgramBuilder|null} The root ProgramBuilder instance, or null if the command has no ancestor program.
+	 */
+	get program () {
+		let p = this.parent;
+		while (p && p.parent) {
+			p = p.parent;
+		}
+		return p;
+	}
+
+	/**
+	 * @property {CommandBuilder|ProgramBuilder|null} parent
+	 * @description Getter that provides a reference to the immediate parent builder in the hierarchy.
+	 * @returns {CommandBuilder|ProgramBuilder|null} The parent builder instance, used for traversing up the command structure.
+	 */
+	get parent () {
+		return this._parent;
+	}
+
+	/**
+	 * @description Sets the main executable name for this command. If a command with this name already exists, it will be overwritten.
+	 * @param {string} name - The desired, primary name for this command.
+	 * @returns {CommandBuilder} The current CommandBuilder instance, facilitating method chaining.
+	 * @throws {Error} Throws an error if the provided name is not a string or is an empty string.
+	 */
+	name (name) {
+		if (typeof name !== 'string') {
+			throw new Error ('String expected. Got ' + (typeof name));
+		}
+		if (name.length == 0) {
+			throw new Error ('Invalid empty name');
+		}
+		const i = this._object.names.indexOf (name);
+		if (i == 0) {
+			return this;
+		}
+		if (i > 0) {
+			this._object.names.splice(i, 1);
+		}
+		this._object.names.unshift(name);
+		return this;
+	}
+
+	/**
+	 * @description Adds one or more aliases (alternative keywords) to the command, allowing multiple ways to invoke the same functionality.
+	 * @param {...string} aliases - A variable list of alternative names (aliases) that can map to this command.
+	* @returns {CommandBuilder} The current CommandBuilder instance, allowing for continuous method calls.
+	 * @throws {Error} Throws an error if any provided alias is not a string or is an empty string.
+	 */
+	aliases () {
+		for (const a of arguments) {
+			if (Array.isArray(a)) {
+				this.aliases(...a);
+				continue;
+			}
+			if (typeof a !== 'string') {
+				throw new Error ('String expected. Got ' + (typeof a));
+			}
+			if (a.length == 0) {
+				throw new Error ('Invalid empty name.');
+			}
+			if (this._object.names.includes (a)) {
+				continue;
+			}
+
+			this._object.names.push (a);
+		}
+		return this;
+	}
+
+
+} /* CommandBuilder */
+
+/**
+ * @class ProgramBuilder
+ * @extends CommandBaseBuilder
+ * @description Represents the root configuration object for the entire application.
+ * This builder is used to set global properties of the program, such as the name and version.
+ */
+export class ProgramBuilder extends CommandBaseBuilder {
+	/**
+	 * @constructor
+	 * @description Initializes the ProgramBuilder, setting up the root Program object.
+	 */
+	constructor () {
+		super ( new Program );
+		this.parameterFactory = createParameter;
+	}
+
+	/**
+	 * @property {Program} program
+	 * @description Getter that exposes the underlying Program object that this builder is configuring.
+	 * @returns {Program} The actual Program instance, representing the application's definition.
+	 */
+	get program () {
+		return this._object;
+	}
+
+	/**
+	 * @description Sets the main name under which the application is recognized.
+	 * @param {string} name - The name of the application program.
+	 * @returns {ProgramBuilder} The current ProgramBuilder instance, enabling method chaining.
+	 */
+	name (name) {
+		this._object.name = name;
+		return this;
+	}
+
+	/**
+	 * @description Sets the version number metadata for the program, which is used in version reporting.
+	 * @param {number|string} version - The version identifier for the program (e.g., "1.0.0" or 1).
+	 * @returns {ProgramBuilder} The current ProgramBuilder instance, allowing for method chaining.
+	 */
+	version (version) {
+		this._object.version = version;
+		return this;
+	}
+} /* Program Builder */
+
+export default {
+	CommandBuilder,
+	ProgramBuilder
+};

package/src/Command.mjs

@@ -0,0 +1,159 @@
+'use strict';
+
+/**
+ * @file Defines the core structural components for building command-line interface (CLI) applications.
+ * This module provides the foundational classes (CommandBase, Command, Program) necessary to manage
+ * command hierarchy, configure metadata, and handle command execution logic within a robust JS application.
+ * It centralizes the management of command names, aliases, and execution handlers.
+ */
+
+import { createDocumentation } from './Documentation.mjs';
+
+/**
+ * @class CommandBase
+ * @description Provides a foundational base class for defining command structures within the CLI.
+ * This base class handles common utilities such as documentation caching, managing command arguments,
+ * and attaching specific command execution handlers.
+ */
+class CommandBase {
+	/**
+	 * Creates an instance of CommandBase.
+	 * @param {object} [options] - Initialization options provided during construction.
+	 * @param {object} [options.documentation] - Optional initial, raw documentation string. This string is processed to create the internal documentation object.
+	 * @param {function} [options.handler] - The primary function object responsible for handling command execution. This function contains the actual business logic.
+	 */
+	constructor (options) {
+		if (!options) {
+			options = {};
+		}
+		this.documentation = options.documentation;
+		this.options = [];
+		this.commands = [];
+		this.positionals = [];
+
+		if (typeof options.handler === 'function') {
+			this.handler = options.handler;
+		}
+	}
+
+	/**
+	 * Gets the command documentation.
+	 *
+	 * @returns {Documentation}
+	 */
+	get documentation () {
+		return this._documentation;
+	}
+
+	/**
+	* Sets the command documentation.
+	*
+	* The input value is normalized to a {Documentation} object.
+	*
+	* @param {Documentation|string|undefined value - User-defined documentation.
+	* 	If undefined, the documentation object is cleared.
+	*/
+	set documentation (value) {
+		if (!value) {
+			this._documentation = undefined;
+			return;
+		}
+
+		this._documentation = createDocumentation(value);
+	}
+	
+	get handler () {
+		return this._handler;
+	}
+
+
+	/**
+	 * Attaches the primary handler function responsible for executing the command logic.
+	 * This handler is the core logic execution entry point that dictates the command's behavior when invoked.
+	 * @param {function} handler - The callable function object that encapsulates the complete command execution logic.
+	 * @returns {void}
+	 * @throws {Error} Throws an Error if the provided 'handler' argument is not a valid function type.
+	 */
+	set handler (handler) {
+		if (typeof handler !== 'function') {
+			throw new Error ('Invalid handler argument. A function object is expected.');
+		}
+		this._handler = handler;
+	}
+}
+
+/**
+ * @class Command
+ * @extends {CommandBase}
+ * @description Represents a single, executable command unit within the CLI program structure.
+ * This class is responsible for defining the command's unique identifier(s), managing aliases,
+ * and providing a specialized interface on top of CommandBase.  larger application ecosystem.
+ */
+export class Command extends CommandBase {
+	/**
+	 * Creates an instance of Command, setting up its formal primary name and registering callable aliases.
+	 * @param {object} options - Command initialization options.
+	 * @param {Array<string>} [options.names] - An optional array of names. The first element MUST be the primary command name, while subsequent elements serve as secondary aliases for execution convenience.
+	 */
+	constructor (options) {
+		if (!options) {
+			options = {};
+		}
+		super (options);
+		this.names = [];
+		if (Array.isArray (options.names)) {
+			options.names.forEach(n => {
+				this.names.push (n);
+			});
+		}
+	}
+
+	/**
+	 * Retrieves the primary, canonical name of the command.
+	 * This name is defined by the first element provided during construction and is the primary identifier used for invocation.
+	 * @returns {string} The main name used to execute the command (e.g., 'user'). This string cannot be empty.
+	 */
+	get name () {
+		return this.names[0];
+	}
+
+	/**
+	 * Retrieves an array of recognized aliases for this command.
+	 * These are supplementary names that can be used interchangeably with the main command name.
+	 * @returns {Array<string>} An array containing all secondary aliases registered for this command. This array may be empty.
+	 */
+	get aliases () {
+		return this.names.slice (1);
+	}
+}
+
+/**
+ * @class Program
+ *
+ * @extends {CommandBase}
+ * @description Represents the root executable container for the entire CLI application.
+ * This class establishes the global context of the application, holding critical metadata
+ * such as the application name and version. It functions as the primary organizational entry point
+ * from which all sub-commands are registered, managed, and ultimately executed.
+ */
+export class Program extends CommandBase {
+	/**
+	 * Creates an instance of Program, setting up the global application metadata that defines the CLI interface.
+	 * @param {object} [options] - Program configuration options.
+	 * @param {string} [options.name] - The official, user-facing name of the entire program (e.g., 'mytool'). This is used in help output.
+	 * @param {string} [options.version] - The current, semantic version string of the application (e.g., '1.0.0').
+	 */
+	constructor (options) {
+		if (!options) {
+			options = {};
+		}
+		super (options);
+		this.name = (typeof options.name === 'string') ? options.name : 'undefined';
+		this.version = (typeof options.version === 'string') ? options.version :  '1.0.0';
+	}
+}
+
+export default {
+	Command,
+	Program
+};

package/src/CommandHandler.mjs

@@ -0,0 +1,14 @@
+'use strict';
+
+/**
+ *
+ * The expected Command handler function signature.
+ *
+ * @param {Input} input - The parsed command structure provided by the CLI parser. This object must contain all necessary arguments and flags required for command execution.
+ *
+ * @returns {number} The process exit code. A return value of 0 indicates successful execution, while non-zero values signal specific failure modes (e.g., missing arguments, invalid state).
+ * @throws {Error} Throws an Error if the input data is fundamentally malformed or an expected command dependency is not available.
+ */
+export function CommandHandler ( /* input */ ) {
+	;
+}