bob-core 1.0.0 → 1.2.0

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/Cli.d.ts

@@ -0,0 +1,26 @@
+import { CommandRegistry } from "@/src/CommandRegistry.js";
+import { Command } from "@/src/Command.js";
+import HelpCommand from "@/src/commands/HelpCommand.js";
+import { ExceptionHandler } from "@/src/ExceptionHandler.js";
+export type CliOptions<C> = {
+    ctx?: C;
+    name?: string;
+    version?: string;
+};
+export declare class Cli<C> {
+    readonly commandRegistry: CommandRegistry;
+    private readonly exceptionHandler;
+    private readonly ctx?;
+    private readonly helpCommand;
+    get CommandRegistryClass(): typeof CommandRegistry;
+    get HelpCommandClass(): typeof HelpCommand;
+    get ExceptionHandlerClass(): typeof ExceptionHandler;
+    constructor(opts?: CliOptions<C>);
+    setCommandResolver(resolver: (path: string) => Promise<Command<C>>): void;
+    withCommands(...commands: Array<Command<C> | {
+        new (): Command<C>;
+    } | string>): Promise<void>;
+    runCommand(command: string | Command, ...args: any[]): Promise<number>;
+    runHelpCommand(): Promise<number>;
+    protected registerCommand(command: Command<C>): void;
+}

package/dist/esm/Cli.js

@@ -0,0 +1,59 @@
+import { CommandRegistry } from "@/src/CommandRegistry.js";
+import HelpCommand from "@/src/commands/HelpCommand.js";
+import { ExceptionHandler } from "@/src/ExceptionHandler.js";
+export class Cli {
+    commandRegistry;
+    exceptionHandler;
+    ctx;
+    helpCommand;
+    get CommandRegistryClass() {
+        return CommandRegistry;
+    }
+    get HelpCommandClass() {
+        return HelpCommand;
+    }
+    get ExceptionHandlerClass() {
+        return ExceptionHandler;
+    }
+    constructor(opts = {}) {
+        this.ctx = opts.ctx;
+        this.commandRegistry = new this.CommandRegistryClass();
+        this.exceptionHandler = new this.ExceptionHandlerClass();
+        this.helpCommand = new this.HelpCommandClass({
+            cliName: opts.name,
+            cliVersion: opts.version,
+            commandRegistry: this.commandRegistry
+        });
+    }
+    setCommandResolver(resolver) {
+        this.commandRegistry.setCommandResolver(resolver);
+    }
+    async withCommands(...commands) {
+        for (const command of commands) {
+            if (typeof command === 'string') {
+                await this.commandRegistry.loadCommandsPath(command);
+            }
+            else {
+                if (typeof command === 'function') {
+                    this.registerCommand(new command());
+                }
+                else {
+                    this.registerCommand(command);
+                }
+            }
+        }
+    }
+    async runCommand(command, ...args) {
+        if (!command) {
+            return await this.runHelpCommand();
+        }
+        return await this.commandRegistry.runCommand(this.ctx, command, ...args)
+            .catch(this.exceptionHandler.handle);
+    }
+    async runHelpCommand() {
+        return await this.runCommand(this.helpCommand);
+    }
+    registerCommand(command) {
+        this.commandRegistry.registerCommand(command);
+    }
+}

package/dist/esm/Command.d.ts

@@ -0,0 +1,34 @@
+import { CommandParser } from "@/src/CommandParser.js";
+import { CommandOption } from "@/src/contracts/index.js";
+export type CommandExample = {
+    description: string;
+    command: string;
+};
+export declare abstract class Command<C = any> {
+    abstract signature: string;
+    abstract description: string;
+    protected ctx: C;
+    protected helperDefinitions: {
+        [key: string]: string;
+    };
+    protected commandsExamples: CommandExample[];
+    protected parser: CommandParser;
+    protected abstract handle(): Promise<void | number>;
+    private get CommandParserClass();
+    protected defaultOptions(): CommandOption<Command<C>>[];
+    get command(): string;
+    run(ctx: C, ...args: any[]): Promise<number>;
+    protected setOption(name: string, value: any): void;
+    protected setArgument(name: string, value: any): void;
+    protected option<T = string>(key: string): T | null;
+    protected option<T = string>(key: string, defaultValue: T): NoInfer<T>;
+    protected optionBoolean(key: string, defaultValue?: boolean): boolean;
+    protected optionArray<T = string>(key: string, defaultValue?: Array<T>): Array<NoInfer<T>>;
+    protected optionNumber(key: string): number | null;
+    protected optionNumber(key: string, defaultValue: number): number;
+    protected argument<T = string>(key: string): T | null;
+    protected argument<T = string>(key: string, defaultValue: T): NoInfer<T>;
+    protected argumentArray<T = string>(key: string, defaultValue?: Array<any>): Array<T>;
+    protected argumentBoolean(key: string, defaultValue?: boolean): boolean;
+    protected argumentNumber(key: string, defaultValue?: number | null): number | null;
+}

package/dist/esm/Command.js

@@ -0,0 +1,93 @@
+import { CommandParser } from "@/src/CommandParser.js";
+import { HelpOption } from "@/src/options/index.js";
+export class Command {
+    ctx;
+    helperDefinitions = {};
+    commandsExamples = [];
+    parser;
+    get CommandParserClass() {
+        return CommandParser;
+    }
+    defaultOptions() {
+        return [new HelpOption];
+    }
+    get command() {
+        if (this.parser) {
+            return this.parser.command;
+        }
+        return this.signature.split(' ')[0];
+    }
+    async run(ctx, ...args) {
+        this.ctx = ctx;
+        const defaultOptions = this.defaultOptions();
+        this.parser = new this.CommandParserClass(this.signature, this.helperDefinitions, defaultOptions, ...args);
+        for (const option of defaultOptions) {
+            if (this.parser.option(option.option)) {
+                const code = await option.handler.call(this);
+                if (code && code !== 0) {
+                    return code;
+                }
+            }
+        }
+        this.parser.validate();
+        return (await this.handle()) ?? 0;
+    }
+    setOption(name, value) {
+        this.parser.setOption(name, value);
+    }
+    setArgument(name, value) {
+        this.parser.setArgument(name, value);
+    }
+    option(key, defaultValue = null) {
+        return this.parser.option(key) ?? defaultValue;
+    }
+    optionBoolean(key, defaultValue = false) {
+        return this.parser.option(key) ?? defaultValue;
+    }
+    optionArray(key, defaultValue = []) {
+        const values = this.parser.option(key);
+        if (!Array.isArray(values)) {
+            throw new Error(`Option ${key} is not an array`);
+        }
+        if (values.length) {
+            return values;
+        }
+        return defaultValue;
+    }
+    optionNumber(key, defaultValue = null) {
+        const value = this.parser.option(key);
+        if (!value) {
+            return defaultValue;
+        }
+        if (typeof value === 'number') {
+            return value;
+        }
+        return parseInt(value);
+    }
+    argument(key, defaultValue = null) {
+        return this.parser.argument(key) ?? defaultValue;
+    }
+    argumentArray(key, defaultValue = []) {
+        const values = this.parser.argument(key);
+        if (!Array.isArray(values)) {
+            throw new Error(`Argument ${key} is not an array`);
+        }
+        if (values?.length) {
+            return values;
+        }
+        return defaultValue;
+    }
+    argumentBoolean(key, defaultValue = false) {
+        return this.parser.argument(key) ?? defaultValue;
+    }
+    argumentNumber(key, defaultValue = null) {
+        const value = this.parser.argument(key);
+        if (!value) {
+            return defaultValue;
+        }
+        if (typeof value === 'number') {
+            return value;
+        }
+        return parseInt(value);
+    }
+}

package/dist/esm/Command.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/Command.test.js

@@ -0,0 +1,50 @@
+import { Command } from '@/src/Command.js';
+import { MissingRequiredArgumentValue } from "@/src/errors/MissingRequiredArgumentValue.js";
+class MockCommand extends Command {
+    signature = 'mockCommand {argument} {--option}';
+    description = 'This is a mock command for testing';
+    handle() {
+        const opts = this.option('option');
+        const arg = this.argument('argument');
+        if (opts) {
+            return Promise.resolve(11);
+        }
+        if (arg === 'value') {
+            return Promise.resolve(1);
+        }
+        else if (arg) {
+            return Promise.resolve(-1);
+        }
+        return Promise.resolve(0);
+    }
+}
+describe('Command', () => {
+    let command;
+    beforeEach(() => {
+        command = new MockCommand();
+    });
+    it('should have a command', () => {
+        expect(command.command).toBe('mockCommand');
+    });
+    it('should have a signature', () => {
+        expect(command.signature).toBe('mockCommand {argument} {--option}');
+    });
+    it('should have a description', () => {
+        expect(command.description).toBe('This is a mock command for testing');
+    });
+    it('should handle command with argument', async () => {
+        const result = await command.run(undefined, 'value');
+        expect(result).toBe(1);
+    });
+    it('should handle command with argument', async () => {
+        const result = await command.run(undefined, 'badValue');
+        expect(result).toBe(-1);
+    });
+    it('should throw error if argument is missing', async () => {
+        await expect(command.run(undefined)).rejects.toThrowError(MissingRequiredArgumentValue);
+    });
+    it('should handle command with option', async () => {
+        const result = await command.run(undefined, 'value', '--option');
+        expect(result).toBe(11);
+    });
+});

package/dist/esm/CommandParser.d.ts

@@ -0,0 +1,46 @@
+import { CommandOption } from "@/src/contracts/index.js";
+export type ArgSignature = {
+    name: string;
+    type: string;
+    optional?: boolean;
+    variadic?: boolean;
+    alias?: string[];
+    help?: string;
+    defaultValue: string | boolean | Array<string> | null;
+    isOption?: boolean;
+};
+export declare class CommandParser {
+    protected readonly signature: string;
+    protected readonly helperDefinitions: {
+        [key: string]: string;
+    };
+    protected readonly defaultCommandOptions: CommandOption<any>[];
+    command: string;
+    private arguments;
+    private options;
+    private argumentsSignature;
+    private optionSignatures;
+    private optionAliases;
+    constructor(signature: string, helperDefinitions: {
+        [key: string]: string;
+    }, defaultCommandOptions: CommandOption<any>[], ...args: any[]);
+    option(name: string): any;
+    setOption(name: string, value: any): void;
+    optionHelp(name: string): string | undefined;
+    argument(name: string): any;
+    setArgument(name: string, value: any): void;
+    argumentHelp(name: string): string | undefined;
+    getArgumentSignatures(): {
+        [argument: string]: ArgSignature;
+    };
+    getOptionSignatures(): {
+        [option: string]: ArgSignature;
+    };
+    private getParamValue;
+    private handleArguments;
+    private handleOptions;
+    private parseSignature;
+    private parseDefaultOptions;
+    private parseParamSignature;
+    validate(): void;
+}

package/dist/esm/CommandParser.js

@@ -0,0 +1,232 @@
+import minimist from 'minimist';
+import { MissingRequiredArgumentValue } from "@/src/errors/MissingRequiredArgumentValue.js";
+import { MissingSignatureOption } from "@/src/errors/MissingSignatureOption.js";
+import { MissingSignatureArgument } from "@/src/errors/MissingSignatureArgument.js";
+import { InvalidOption } from "@/src/errors/InvalidOption.js";
+export class CommandParser {
+    signature;
+    helperDefinitions;
+    defaultCommandOptions;
+    command;
+    arguments = {};
+    options = {};
+    argumentsSignature = {};
+    optionSignatures = {};
+    optionAliases = {};
+    constructor(signature, helperDefinitions, defaultCommandOptions, ...args) {
+        this.signature = signature;
+        this.helperDefinitions = helperDefinitions;
+        this.defaultCommandOptions = defaultCommandOptions;
+        const [command, ...signatureParams] = signature.split(/\{(.*?)\}/g).map(param => param.trim()).filter(Boolean);
+        const { _: paramValues, ...optionValues } = minimist(args);
+        this.command = command;
+        this.parseSignature(signatureParams);
+        this.parseDefaultOptions();
+        this.handleArguments(paramValues);
+        this.handleOptions(optionValues);
+    }
+    option(name) {
+        if (!this.optionSignatures[name]) {
+            throw new MissingSignatureOption(name, Object.values(this.optionSignatures));
+        }
+        return this.options[name];
+    }
+    setOption(name, value) {
+        if (!this.optionSignatures[name]) {
+            throw new MissingSignatureOption(name, Object.values(this.optionSignatures));
+        }
+        this.options[name] = value;
+    }
+    optionHelp(name) {
+        const optionSignature = this.optionSignatures[name];
+        if (!optionSignature) {
+            throw new MissingSignatureOption(name, Object.values(this.optionSignatures));
+        }
+        return this.optionSignatures[name].help;
+    }
+    argument(name) {
+        if (!this.argumentsSignature[name]) {
+            throw new MissingSignatureArgument(name, Object.values(this.argumentsSignature));
+        }
+        return this.arguments[name];
+    }
+    setArgument(name, value) {
+        if (!this.argumentsSignature[name]) {
+            throw new MissingSignatureArgument(name, Object.values(this.argumentsSignature));
+        }
+        this.arguments[name] = value;
+    }
+    argumentHelp(name) {
+        const argumentSignature = this.argumentsSignature[name];
+        if (!argumentSignature) {
+            throw new MissingSignatureArgument(name, Object.values(this.argumentsSignature));
+        }
+        return this.argumentsSignature[name].help;
+    }
+    getArgumentSignatures() {
+        return this.argumentsSignature;
+    }
+    getOptionSignatures() {
+        return this.optionSignatures;
+    }
+    getParamValue(value, signature) {
+        if (signature.type === 'boolean') {
+            if (value === 'true' || value === '1') {
+                return true;
+            }
+            else if (value === 'false' || value === '0') {
+                return false;
+            }
+            return Boolean(value);
+        }
+        if (signature.type === 'array') {
+            if (!value) {
+                return [];
+            }
+            return Array.isArray(value) ? value : [value];
+        }
+        return value ?? signature.defaultValue;
+    }
+    handleArguments(paramValues) {
+        for (const [argument, value] of Object.entries(this.arguments)) {
+            const argSignature = this.argumentsSignature[argument];
+            if (argSignature.variadic) {
+                this.arguments[argument] = paramValues;
+            }
+            else {
+                const paramValue = paramValues.shift();
+                this.arguments[argument] = this.getParamValue(paramValue, argSignature);
+            }
+        }
+    }
+    handleOptions(optionValues) {
+        for (const [option, value] of Object.entries(optionValues)) {
+            const optionAlias = this.optionAliases[option];
+            const optionSignature = this.optionSignatures[option] ?? this.optionSignatures[optionAlias];
+            if (!optionSignature) {
+                throw new InvalidOption(option, Object.values(this.optionSignatures));
+            }
+            this.options[option] = this.getParamValue(value, optionSignature);
+            for (const alias of optionSignature.alias ?? []) {
+                if (optionValues[alias]) {
+                    this.options[optionSignature.name] = optionValues[alias];
+                }
+            }
+        }
+    }
+    parseSignature(params) {
+        for (const paramSignature of params) {
+            const param = this.parseParamSignature(paramSignature);
+            if (param.isOption) {
+                this.options[param.name] = param.defaultValue ?? null;
+                this.optionSignatures[param.name] = param;
+                for (const alias of param.alias ?? []) {
+                    this.optionAliases[alias] = param.name;
+                }
+            }
+            else {
+                this.arguments[param.name] = param.defaultValue ?? null;
+                this.argumentsSignature[param.name] = param;
+            }
+        }
+    }
+    parseDefaultOptions() {
+        if (this.defaultCommandOptions.length) {
+            for (const option of this.defaultCommandOptions) {
+                this.optionSignatures[option.option] = {
+                    name: option.option,
+                    type: option.defaultValue == null ? 'string' : typeof option.defaultValue,
+                    optional: true,
+                    alias: option.alias,
+                    variadic: false,
+                    help: option.description,
+                    defaultValue: option.defaultValue ?? null,
+                    isOption: true
+                };
+                this.options[option.option] = option.defaultValue;
+                if (option.alias) {
+                    for (const alias of option.alias) {
+                        this.optionAliases[alias] = option.option;
+                    }
+                }
+            }
+        }
+    }
+    parseParamSignature(argument) {
+        const arg = {
+            name: argument,
+            optional: false,
+            type: 'string',
+            help: undefined,
+            defaultValue: null,
+            variadic: false,
+            isOption: false
+        };
+        if (arg.name.includes(':')) {
+            const [name, help] = arg.name.split(':');
+            arg.name = name.trim();
+            arg.help = help.trim();
+        }
+        if (arg.name.includes('=')) {
+            const [name, defaultValue] = arg.name.split('=');
+            arg.name = name.trim();
+            arg.defaultValue = defaultValue.trim();
+            arg.optional = true;
+            if (!arg.defaultValue.length) {
+                arg.defaultValue = null;
+            }
+            else if (arg.defaultValue === 'true') {
+                arg.defaultValue = true;
+                arg.type = 'boolean';
+            }
+            else if (arg.defaultValue === 'false') {
+                arg.defaultValue = false;
+                arg.type = 'boolean';
+            }
+        }
+        else {
+            if (arg.name.startsWith('--')) {
+                arg.optional = true;
+                arg.defaultValue = false;
+                arg.type = 'boolean';
+            }
+        }
+        if (arg.name.includes('|')) {
+            const [name, ...alias] = arg.name.split('|');
+            arg.name = name.trim();
+            arg.alias = alias.map(a => a.trim());
+        }
+        if (arg.name.startsWith('--')) {
+            arg.isOption = true;
+            arg.name = arg.name.slice(2);
+        }
+        if (arg.defaultValue === '*') {
+            arg.defaultValue = [];
+            arg.type = 'array';
+        }
+        if (arg.name.endsWith('?')) {
+            arg.optional = true;
+            arg.name = arg.name.slice(0, -1);
+        }
+        if (arg.name.endsWith('*')) {
+            arg.type = 'array';
+            arg.variadic = true;
+            arg.defaultValue = [];
+            arg.name = arg.name.slice(0, -1);
+        }
+        arg.help = arg.help ?? this.helperDefinitions[arg.name] ?? this.helperDefinitions[`--${arg.name}`];
+        return arg;
+    }
+    validate() {
+        // validate arguments
+        for (const [argument, value] of Object.entries(this.arguments)) {
+            const argSignature = this.argumentsSignature[argument];
+            if (!value && !argSignature.optional) {
+                throw new MissingRequiredArgumentValue(argSignature);
+            }
+            if (!value?.length && argSignature.variadic && !argSignature.optional) {
+                throw new MissingRequiredArgumentValue(argSignature);
+            }
+        }
+    }
+}

package/dist/esm/CommandParser.test.d.ts

@@ -0,0 +1 @@
+export {};