@vimpak/args 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# @vimpak/args
+
+CLI argument and configuration loader for TypeScript.
+
+## Installation
+
+```bash
+bun add @vimpak/args
+```
+
+## Features
+
+- Load config from environment variables (`app__` prefix → dot notation)
+- Load from `etc/env`, `etc/argv`, `etc/config.json`, `etc/secret.json`
+- Command/subcommand support
+- Type-safe config with runtime validation
+
+## Usage
+
+### main()
+
+When multiple commands created in one file.
+
+```typescript
+import {main} from "@vimpak/args";
+
+interface Config {
+	port: number;
+	host: string;
+}
+
+await main({
+	config: {port: 3000, host: "localhost"},
+	commands: {
+		start: async (config) => {
+			console.log(`Starting on ${config.host}:${config.port}`);
+		},
+	},
+	defaultCommand: ["start"],
+});
+```
+
+### run()
+
+When each command is created in different file.
+
+```typescript
+import {run} from "@vimpak/args";
+
+interface Config {
+	port: number;
+	host: string;
+}
+
+await run(
+	async (config, options) => {
+		console.log(`Starting on ${config.host}:${config.port}`);
+	},
+	{port: 3000, host: "localhost"},
+);
+```
+
+## Configuration Sources
+
+| Source      | Format                   | Example                          |
+| ----------- | ------------------------ | -------------------------------- |
+| Environment | `app__key__nested=value` | `app__port=3000` → `config.port` |
+| CLI args    | `--key value`            | `--port 3000` → `config.port`    |
+| Config file | JSON                     | `{"port": 3000}`                 |

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export declare function applyOptions<T>(config: T, options: Map<string, string[]>, prefix?: string): void;
+export interface Args {
+    cmd: string[];
+    options: Map<string, string[]>;
+}
+export declare function loadArgs<T>(config: unknown, defaultCommand?: string[]): Promise<Args>;
+export type Command<T> = (config: T, options: Map<string, string[]>, ...args: string[]) => Promise<void>;
+export interface CommandMap<T> {
+    [cmd: string]: undefined | Command<T> | CommandMap<T>;
+}
+export interface Main<T> {
+    config: T;
+    commands: CommandMap<T>;
+    defaultCommand: string[];
+}
+export declare function main<T>({ commands, config, defaultCommand }: Main<T>): Promise<void>;
+export declare function run<T>(command: Command<T>, config: T): Promise<void>;
+export declare function finalizeOptions<T>(config: T, options: Map<string, string[]>): T;
+export declare function doNotUseUnknownOptions(options: Map<string, string[]>): void;

package/dist/index.js

@@ -0,0 +1,220 @@
+import fs from "node:fs/promises";
+function invariant(condition, message) {
+    if (!condition) {
+        throw new Error(message);
+    }
+}
+async function readFile(filename) {
+    return fs.readFile(filename, "utf-8");
+}
+async function loadEnv() {
+    let content = "";
+    try {
+        content = await readFile("etc/env");
+    }
+    catch {
+        return;
+    }
+    const lines = content
+        .split("\n")
+        .map((item) => item.trim())
+        .filter((item) => !item.startsWith("#") && lines.length !== 0);
+    for (const line of lines) {
+        const parts = line.split("=");
+        invariant(parts.length === 2);
+        const key = parts[0].trim();
+        const value = parts[1].trim();
+        if (!process.env[key])
+            process.env[key] = value;
+    }
+}
+async function readArgv() {
+    const argv = process.argv.slice(2);
+    let content = "";
+    try {
+        content = await readFile("etc/argv");
+    }
+    catch {
+        return argv;
+    }
+    const lines = content
+        .split("\n")
+        .map((item) => item.trim())
+        .filter((item) => !item.startsWith("#") && item.length !== 0);
+    for (let i = argv.length; i < lines.length; i++) {
+        argv.push(lines[i]);
+    }
+    return argv;
+}
+async function readOptions() {
+    const envPrefix = "app__";
+    const optionPredix = "--";
+    const configKeyValues = new Map();
+    for (const envVar in process.env) {
+        if (envVar.startsWith(envPrefix)) {
+            const key = envVar.substring(envPrefix.length).replaceAll("__", ".");
+            const value = process.env[envVar];
+            configKeyValues.set(key, [value]);
+        }
+    }
+    let option = ".";
+    const args = await readArgv();
+    for (const arg of args) {
+        if (arg.startsWith(optionPredix)) {
+            option = arg.replace("--", ".");
+        }
+        else {
+            const options = configKeyValues.get(option);
+            if (options) {
+                options.push(arg);
+            }
+            else {
+                configKeyValues.set(option, [arg]);
+            }
+        }
+    }
+    return configKeyValues;
+}
+export function applyOptions(config, options, prefix = "") {
+    for (const key in config) {
+        const path = `${prefix}.${key}`;
+        const configValue = config[key];
+        const configType = typeof configValue;
+        const values = options.get(path) || [];
+        let parsedValue = undefined;
+        invariant(configValue !== null);
+        if (configType === "object") {
+            applyOptions(config[key], options, path);
+        }
+        else {
+            invariant(values.length <= 1);
+            const value = values[0];
+            if (value === undefined) {
+                parsedValue = undefined;
+            }
+            else if (configType === "number") {
+                parsedValue = Number.parseFloat(value);
+            }
+            else if (configType === "string") {
+                parsedValue = value;
+            }
+            else if (configType === "boolean") {
+                if (value === "true") {
+                    parsedValue = true;
+                }
+                else if (value === "false") {
+                    parsedValue = false;
+                }
+                else {
+                    throw new Error("Invalid value for boolean");
+                }
+            }
+        }
+        if (parsedValue !== undefined) {
+            // eslint-disable-next-line
+            // @ts-ignore type is checked, but typescript is unable to infer
+            config[key] = parsedValue;
+        }
+        options.delete(path);
+    }
+}
+async function applyConfigFile(config, filename) {
+    let content;
+    try {
+        content = await readFile(filename);
+    }
+    catch {
+        return config;
+    }
+    const values = JSON.parse(content);
+    merge(config, values);
+    return config;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function merge(config, values) {
+    invariant(typeof config === typeof values);
+    for (const key in config) {
+        if (typeof values[key] === "undefined")
+            continue;
+        invariant(typeof config[key] === typeof values[key]);
+        if (values[key] &&
+            typeof values[key] === "object" &&
+            !Array.isArray(values[key])) {
+            merge(config[key], values[key]);
+        }
+        else {
+            config[key] = values[key];
+        }
+    }
+}
+export async function loadArgs(config, defaultCommand = []) {
+    await loadEnv();
+    const options = await readOptions();
+    const cmd = options.get(".") || defaultCommand;
+    options.delete(".");
+    const configfiles = options.get(".config");
+    if (configfiles) {
+        for (const filename of configfiles) {
+            await applyConfigFile(config, filename);
+        }
+    }
+    else {
+        try {
+            await applyConfigFile(config, "etc/config.json");
+        }
+        catch {
+            // pass
+        }
+    }
+    const secretfiles = options.get(".secret");
+    options.delete(".secret");
+    if (secretfiles) {
+        for (const filename of secretfiles) {
+            await applyConfigFile(config, filename);
+        }
+    }
+    else {
+        try {
+            await applyConfigFile(config, "etc/secret.json");
+        }
+        catch {
+            // pass
+        }
+    }
+    applyOptions(config, options);
+    return { cmd, options };
+}
+export async function main({ commands, config, defaultCommand }) {
+    const { cmd, options } = await loadArgs(config, defaultCommand);
+    for (let index = 0; index < cmd.length; index++) {
+        const next = commands[cmd[index]];
+        if (typeof next === "undefined") {
+            throw new Error(`${cmd} is not a valid command`);
+        }
+        else if (typeof next === "function") {
+            await next(config, options, ...cmd);
+        }
+        else {
+            commands = next;
+        }
+    }
+    throw new Error("subcommand is not specfied");
+}
+export async function run(command, config) {
+    const { cmd, options } = await loadArgs(config, []);
+    await command(config, options, ...cmd);
+    doNotUseUnknownOptions(options);
+}
+export function finalizeOptions(config, options) {
+    applyOptions(config, options);
+    doNotUseUnknownOptions(options);
+    return config;
+}
+export function doNotUseUnknownOptions(options) {
+    if (options.size === 0)
+        return;
+    for (const option of options.keys()) {
+        console.error(`Unknown option ${option}`);
+    }
+    throw new Error();
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+	"type": "module",
+	"version": "0.1.0",
+	"name": "@vimpak/args",
+	"collaborators": [
+		"Sudesh Yadav <sudeshyadav955@gmail.com>"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://gitlab.com/vimpak/args"
+	},
+	"files": [
+		"./dist"
+	],
+	"main": "./dist/index.js",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"scripts": {
+		"prettify": "prettier --write --ignore-unknown ."
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.11",
+		"prettier": "^3.8.1",
+		"typescript": "^6.0.2"
+	},
+	"prettier": {
+		"useTabs": true,
+		"proseWrap": "always",
+		"trailingComma": "all",
+		"bracketSpacing": false
+	}
+}