@trenskow/arguments-parser 0.3.115 → 0.3.117

package/.vscode/settings.json

@@ -1,8 +1,8 @@
 {
-    "cSpell.words": [
-        "caseit",
-        "isvalid",
-        "Kristian",
-        "trenskow"
-    ]
+	"cSpell.words": [
+		"caseit",
+		"isvalid",
+		"Kristian",
+		"trenskow"
+	]
 }

package/eslint.config.js

@@ -36,8 +36,9 @@ export default [...compat.extends('eslint:recommended'), {
 			allow: ['warn', 'error', 'info'],
 		}],
 
-		'no-unused-vars': ['error', {
+		'no-unused-vars': ['warn', {
 			argsIgnorePattern: '^_',
+			caughtErrors: 'none'
 		}],
 
 		'no-empty': ['error', {

package/index.js

@@ -6,4 +6,68 @@
 // See license in LICENSE.
 //
 
-export { default } from './lib/index.js';
+import { plugins } from 'isvalid';
+
+import argumentsParser from './lib/index.js';
+import autocomplete from './lib/autocomplete/index.js';
+
+plugins.use('argumentsParser.dummies', () => ({
+	phase: 'pre',
+	supportsType: () => true,
+	validatorsForType: () => ({
+		description: ['string'],
+		defaultDescription: ['string'],
+		secret: ['boolean'],
+		short: ['string']
+	}),
+	validate: (data) => data,
+	formalize: (schema) => schema
+}));
+
+plugins.use('argumentsParser.hints', () => ({
+	phase: 'pre',
+	supportsType: () => true,
+	validatorsForType: () => ({
+		hints: ['array', 'string']
+	}),
+	validate: (data) => data,
+	formalize: (data, _, schema) => {
+
+		if (!Array.isArray(data)) data = [data];
+
+		if (schema.errors.hints) {
+			data.push(schema.errors.hints);
+			delete schema.errors.hints;
+		}
+
+		if (data.some((data) => typeof data !== 'string')) throw new Error('Must be a string.');
+
+		return data;
+
+	}
+}));
+
+plugins.use('argumentsParser.autocomplete', () => ({
+	phase: 'pre',
+	supportsType: () => true,
+	validatorsForType: () => ({
+		autocomplete: ['array', 'string']
+	}),
+	validate: (data) => data,
+	formalize: (data, _, schema) => {
+
+		if (!Array.isArray(data)) data = [data];
+
+		if (schema.errors.autocomplete) {
+			data.push(schema.errors.autocomplete);
+			delete schema.errors.autocomplete;
+		}
+
+		if (data.some((data) => typeof data !== 'string')) throw new Error('Must be a string.');
+
+		return data;
+
+	}
+}));
+
+export default autocomplete(process.env.AUTOCOMPLETE) || argumentsParser;

package/lib/autocomplete/build-ins/files.js

@@ -0,0 +1,64 @@
+//
+// files.js
+// @trenskow/arguments-parser
+//
+// Created by Kristian Trenskow on 2026/08/02
+// See license in LICENSE.
+//
+
+import {
+	join,
+	resolve
+} from 'path';
+
+import {
+	stat,
+	readdir
+} from 'fs/promises';
+
+import parallel from '@trenskow/parallel';
+
+const safeStat = async (path) => {
+	try {
+		return await stat(path);
+	} catch (_) {
+		return undefined;
+	}
+};
+
+export default async (current = '') => {
+
+	const stat = await safeStat(
+		resolve(
+			process.cwd(),
+			current));
+
+	if (stat?.isDirectory()) {
+
+		current = current.endsWith('/') ? current : `${current}/`;
+
+		return (await parallel((await readdir(
+			resolve(
+				process.cwd(),
+				current)))
+			.map(async (file) => {
+
+				if ((await safeStat(resolve(process.cwd(), current, file)))?.isDirectory()) {
+					return `${file}/`;
+				}
+
+				return file;
+
+			})))
+			.filter((file) => !file.startsWith('.'))
+			.map((file) => `${current}${file}`);
+
+	} else if (stat) {
+		return [];
+	}
+
+	return (await readdir(join(current, '../')))
+		.filter((file) => !file.startsWith('.'))
+		.map((file) => join(current, '../', file));
+
+};

package/lib/autocomplete/build-ins/index.js

@@ -0,0 +1,15 @@
+//
+// index.js
+// @trenskow/arguments-parser
+//
+// Created by Kristian Trenskow on 2026/08/02
+// See license in LICENSE.
+//
+
+import files from './files.js';
+
+export { files };
+
+export default {
+	files
+};

package/lib/autocomplete/index.js

@@ -0,0 +1,281 @@
+//
+// index.js
+// @trenskow/arguments-parser
+//
+// Created by Kristian Trenskow on 2026/08/02
+// See license in LICENSE.
+//
+
+import {
+	basename
+} from 'path';
+
+import {
+	keyPaths,
+	merge
+} from 'isvalid';
+
+import caseit from '@trenskow/caseit';
+
+import buildIns from './build-ins/index.js';
+
+import zsh from './zsh.js';
+
+const supported = {
+	zsh
+};
+
+const argumentsParser = (output) => {
+
+	output = supported[output];
+
+	if (!output) return undefined;
+
+	const argumentsParser = (
+		{
+			args = process.argv.slice(output.argsOffset || 2),
+			argvLevel = 0,
+			placeholder = '<>',
+			command,
+			onCommand,
+			onParameter,
+			options = {
+				schema: {},
+				data: {},
+				validationOptions: {}
+			},
+			parameters = {}
+		} = {}
+	) => {
+
+		const base = `${process.argv.slice(1, argvLevel + 2).map(((arg) => basename(arg))).join(' ')}`;
+
+		const next = async (identifier, command) => {
+
+			return await command({
+				args: args.slice(1),
+				argumentsParser: argumentsParser({
+					args: args.slice(1),
+					argvLevel: argvLevel + 1,
+					onCommand,
+					onParameter,
+					placeholder,
+					command: command,
+					options,
+					parameters
+				}),
+				parameters
+			});
+
+		};
+
+		const result = {
+			get base() {
+				return base;
+			},
+			command: async (commands) => {
+
+				const tool = caseit(args[0] || '');
+
+				if (commands[tool]) {
+
+					onCommand?.(tool, args.slice(1));
+
+					return await next(
+						tool,
+						commands[tool]);
+
+				}
+
+				return output(Object.keys(commands)
+					.filter((command) => command.startsWith(tool))
+					.map((command) => ({
+						command,
+						description: commands[command].description
+					})));
+
+			},
+			parameter: async ({
+				identifier,
+				autocomplete
+			}, command) => {
+
+				const available = (await autocomplete?.(args[0] || '') || [])
+					.filter((item) => item !== args[0] && item.startsWith(args[0] || ''));
+
+				if (available.length) {
+					return output(available);
+				}
+
+				parameters[identifier] = args[0];
+
+				(onParameter || onCommand)?.(identifier, args.slice(1));
+
+				return await next(
+					identifier,
+					command);
+
+			},
+			options: (schema, validationOptions = {}) => {
+
+				validationOptions.command = validationOptions.command || command;
+
+				Object.assign(
+					options.validationOptions,
+					validationOptions);
+
+				options.schema = merge(
+					schema, {
+						transform: {
+							post: (key, validator) => {
+								if (key === 'enum') {
+									return validator.map((value) => caseit(value, 'kebab'));
+								}
+							}
+						}
+					})
+					.with(options.schema);
+
+				return result;
+
+			},
+			then: (
+				...resultArguments
+			) => {
+				return (async () => {
+
+					const {
+						variadic,
+						autocomplete = buildIns.files
+					} = options.validationOptions;
+
+					const allKeyPaths = keyPaths(options.schema)
+						.all()
+						.filter((keyPath) => keyPath);
+
+					let idx;
+					let schemas = {};
+					let spent = [];
+
+					const complete = async (idx, current = '') => {
+
+						let key = current;
+
+						while (key.startsWith('-')) {
+							key = key.slice(1);
+						}
+
+						key = caseit(key);
+
+						if (schemas[idx]) {
+
+							if (schemas[idx].enum) {
+								return Object.keys(schemas[idx].enum)
+									.filter((item) => caseit(key, 'kebab') !== item && item.startsWith(current))
+									.map((item) => caseit(item, 'kebab'));
+							}
+
+							if (schemas[idx].type === String && !schemas[idx].autocomplete) {
+								return await (buildIns.files(
+									current))
+									.filter((item) => key !== item && item.startsWith(current));
+							}
+
+							return (await schemas[idx].autocomplete?.(current) || [])
+								.filter((item) => key !== item && item.startsWith(current));
+
+						} else {
+
+							let items = [];
+
+							if (!current.startsWith('--')) {
+
+								if (!current.startsWith('-')) {
+									if (variadic === 'allow') {
+										items = items.concat(
+											(await autocomplete?.(current) || [])
+												.filter((item) => current !== item && item.startsWith(current)));
+									}
+								}
+
+								items = items.concat(
+									allKeyPaths
+										.filter((keyPath) => !spent.includes(keyPath))
+										.filter((keyPath) => key !== keyPath && keyPath.startsWith(key) && keyPaths(options.schema).get(keyPath).short)
+										.map((keyPath) => ({
+											command: caseit(keyPaths(options.schema).get(keyPath).short, 'kebab'),
+											description: keyPaths(options.schema).get(keyPath).description,
+											prefix: '-'
+										})));
+
+							}
+
+							items = items.concat(
+								allKeyPaths
+									.filter((keyPath) => !spent.includes(keyPath))
+									.filter((keyPath) => key !== keyPath && keyPath.startsWith(key))
+									.map((keyPath) => ({
+										command: caseit(keyPath, 'kebab'),
+										description: keyPaths(options.schema).get(keyPath).description,
+										prefix: '--'
+									})));
+
+							return items;
+
+						}
+
+					};
+
+					if (args.length === 0) {
+						return output(
+							await complete(-1));
+					}
+
+					for (idx = 0; idx < args.length; idx++) {
+
+						if (!schemas[idx]) {
+
+							if (!args[idx].startsWith('-')) {
+								return output(
+									await complete(idx, args[idx]));
+							}
+
+							const [keyPath, schema] = allKeyPaths
+								.filter((keyPath) => !spent.includes(keyPath))
+								.map((keyPath) => [keyPath, keyPaths(options.schema).get(keyPath)])
+								.filter(([keyPath, schema]) => keyPath === args[idx] || `--${caseit(keyPath, 'kebab')}` === args[idx] || (schema.short && `-${schema.short}` === args[idx]))[0] || [];
+
+							spent.push(keyPath);
+
+							if (schema && schema.type !== Boolean) {
+								schemas[idx + 1] = schema;
+							}
+
+						}
+
+					}
+
+					const current = await complete(idx - 1, args[idx - 1]);
+
+					if (current.length) {
+						return output(current);
+					}
+
+					return output(
+						await complete(idx));
+
+
+				})().then(...resultArguments);
+			}
+		};
+
+		return result;
+
+	};
+
+	return argumentsParser;
+
+};
+
+export default argumentsParser;
+export * as buildIns from './build-ins/index.js';

package/lib/autocomplete/zsh.js

@@ -0,0 +1,39 @@
+//
+// zsh.js
+// @trenskow/arguments-parser
+//
+// Created by Kristian Trenskow on 2026/08/02
+// See license in LICENSE.
+//
+
+import caseit from '@trenskow/caseit';
+
+const zsh = (items) => {
+
+	if (items.length === 0) {
+		process.exit(0);
+	}
+
+	process.stdout.write('_describe \'commands\' \'(\n');
+
+	items
+		.forEach((command) => {
+
+			if (typeof command === 'string') {
+				process.stdout.write(`  "${command}"\n`);
+				return;
+			}
+
+			process.stdout.write(`  "${command.prefix || ''}${command.command}:${(command.description || '').replaceAll('`', '\\`')}"\n`);
+
+		});
+
+	process.stdout.write(')\'\n');
+
+	process.exit(0);
+
+};
+
+zsh.argsOffset = 3;
+
+export default zsh;

package/lib/index.js

@@ -9,40 +9,9 @@
 import { basename } from 'path';
 
 import caseit from '@trenskow/caseit';
-import { default as isvalid, merge, keyPaths, plugins } from 'isvalid';
+import { default as isvalid, merge, keyPaths } from 'isvalid';
 import print from '@trenskow/print';
 
-plugins.use('argumentsParser.default', () => ({
-	phase: 'pre',
-	supportsType: () => true,
-	validatorsForType: () => ({
-		description: ['string'],
-		defaultDescription: ['string'],
-		secret: ['boolean'],
-		short: ['string'],
-	}),
-	validate: (data) => data,
-	formalize: (schema) => schema
-}));
-
-plugins.use('argumentsParser.hints', () => ({
-	phase: 'pre',
-	supportsType: () => true,
-	validatorsForType: () => ({
-		hints: ['array', 'string']
-	}),
-	validate: (data) => data,
-	formalize: (data, _, schema) => {
-		if (!Array.isArray(data)) data = [data];
-		if (schema.errors.hints) {
-			data.push(schema.errors.hints);
-			delete schema.errors.hints;
-		}
-		if (data.some((data) => typeof data !== 'string')) throw new Error('Must be a string.');
-		return data;
-	}
-}));
-
 const argumentsParser = (
 	{
 		args = process.argv.slice(2),
@@ -65,7 +34,7 @@ const argumentsParser = (
 	} = {}
 ) => {
 
-	const [ opening, closing ] = placeholder.split('');
+	const [opening, closing] = placeholder.split('');
 
 	const base = `${process.argv.slice(1, argvLevel + 2).map(((arg) => basename(arg))).join(' ')}`;
 
@@ -174,6 +143,7 @@ const argumentsParser = (
 			print.err(`${error.stack}`);
 			process.exit(1);
 		}
+
 	};
 
 	const result = {
@@ -191,15 +161,7 @@ const argumentsParser = (
 				print();
 
 				const tools = Object.entries(commands).map(([key, command]) => ({
-					name: `${
-						caseit(key, 'kebab')
-					}${
-						Array.isArray(command.parameters) ? ` ${
-							command.parameters
-								.map((parameter) => `${opening}${caseit(parameter, 'kebab')}${closing}`)
-								.join(' ')
-						}` : ''
-					}`,
+					name: `${caseit(key, 'kebab')}${Array.isArray(command.parameters) ? ` ${command.parameters.map((parameter) => `${opening}${caseit(parameter, 'kebab')}${closing}`).join(' ')}` : ''}`,
 					description: commands[key].description
 				}));
 
@@ -279,7 +241,7 @@ const argumentsParser = (
 				command);
 
 		},
-		options: (schema, validationOptions = { }) => {
+		options: (schema, validationOptions = {}) => {
 
 			validationOptions.command = validationOptions.command || command;
 
@@ -288,7 +250,15 @@ const argumentsParser = (
 				validationOptions);
 
 			options.schema = merge(
-				schema)
+				schema, {
+					transform: {
+						post: (key, validator) => {
+							if (key === 'enum') {
+								return validator.map((value) => caseit(value, 'kebab'));
+							}
+						}
+					}
+				})
 				.with(options.schema);
 
 			return result;
@@ -365,7 +335,7 @@ const argumentsParser = (
 								}
 
 								if (typeof keyPathSchema.enum !== 'undefined') {
-									description.push(`(${opening}${keyPath}${closing}: ${Object.keys(keyPathSchema.enum).map((value) => `\`${value}\``).join(', ')})`);
+									description.push(`(${opening}${keyPath}${closing}: ${Object.keys(keyPathSchema.enum).map((value) => `\`${caseit(value, 'kebab')}\``).join(', ')})`);
 								}
 
 								if (keyPathSchema.type === Array) {
@@ -418,7 +388,7 @@ const argumentsParser = (
 
 				checkHelp();
 
-				for (idx = 0 ; idx < args.length ; idx++) {
+				for (idx = 0; idx < args.length; idx++) {
 
 					if (args[idx].slice(0, 1) !== '-') {
 						rest.push(args[idx]);
@@ -514,3 +484,4 @@ const argumentsParser = (
 };
 
 export default argumentsParser;
+export { buildIns as autocompleteBuildIns } from './autocomplete/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@trenskow/arguments-parser",
-	"version": "0.3.115",
+	"version": "0.3.117",
 	"description": "Yet another arguments parser.",
 	"main": "index.js",
 	"type": "module",
@@ -25,6 +25,7 @@
 	"homepage": "https://github.com/trenskow/arguments-parser#readme",
 	"dependencies": {
 		"@trenskow/caseit": "^1.4.29",
+		"@trenskow/parallel": "^0.1.132",
 		"@trenskow/print": "^0.1.72",
 		"isvalid": "^5.0.19"
 	},