@briklab/lib 1.0.0

package/README.md

@@ -0,0 +1,16 @@
+# @briklab/lib
+
+### @briklab/lib is the core package for briklab packages
+
+**It Introduces:**
+- **@briklab/cli-john:** Generate a [CLI](https://en.wikipedia.org/wiki/Command-line_interface) with ease.
+- **@briklab/jstc:** Add Type Checking for JavaScript.
+
+## Installation
+Normally, the format is:
+```bash
+[packageManager] install/add/i @briklab/lib
+```
+**Examples:**
+- **pnpm:**`pnpm add @briklab/lib`
+- **npm:**`npm i @briklab/lib`

package/dist/cli-john/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @packageDocumentation
+ *
+ * # CLI John
+ *
+ * **CLI John** is a **Node.js CLI framework** designed to create **fully functional CLIs** quickly.
+ * It hooks into a given NodeJS process, automatically listens for commands, parses arguments,
+ * and allows beautiful console messages. Its design is **modular**, using Commands and Options as sub-classes.
+ *
+ * ## Features
+ * - Auto-listening to commands
+ * - Command parsing
+ * - Beautiful console messages
+ * - One CLI per file
+ * - Add your file to `bin` in package.json → CLI works seamlessly
+ * - Event-driven command handling
+ *
+ * ## Usage
+ * ```ts
+ * import { CLI as CLI } from "@briklab/lib/cli-john"
+ * import * as process from "node:process"
+ *
+ * const cli = new CLI(process);
+ *
+ * const cmd = cli.command("myCommand");
+ * const opt = cmd.option("force");
+ *
+ * cmd.on("run", ({commandArgs}) => {
+ *   CJ.notice("Hey, this is my CLI!");
+ *   CJ.message("Do you like it?");
+ *   CJ.error("Invalid args:", ...commandArgs.map(a => a.name));
+ * });
+ *
+ * cli.run();
+ * ```
+ *
+ * ## Limitations
+ * - Only **one CLI per file** is allowed (CLI enforces this)
+ * - CLI file must be manually added to `bin` in package.json
+ *
+ * ## Hierarchy
+ * ```
+ * CLI
+ * ├─ Command
+ * │   └─ Option
+ * └─ CLIErrors
+ * ```
+ *
+ * ## Error Handling
+ * - All errors are instances of `CLIErrors`
+ * - Dynamic names allow easy identification of which part of the CLI threw the error
+ *
+ * @module cli-john
+ */
+/**
+ * # CLI
+ * @classdesc The main class for **CLI**.
+ * @example
+ * import * as process from "node:process"
+ * import {CLI} from "@briklab/lib/cli-john"
+ * const cli = new CLI(process)
+ * cli.run()
+ */
+export declare class CLI {
+    #private;
+    /**
+     * ## CLI: Constructor
+     * @param {NodeJS.Process} process - **The main process**
+     * @constructor
+     * @constructs CLI
+     * @example
+     * import * as process from "node:process"
+     * import {CLI} from "@briklab/lib/cli-john"
+     * const cli = new CLI(process)
+     * cli.run()
+     */
+    constructor(process: NodeJS.Process);
+    /**
+     * ### CLI.command
+     * create a new command in a CLI.
+     *
+     * @param {string} name
+     */
+    command(name: string): CLI.Command;
+    on(event: CLI.ValidEvent, func: Function): void;
+    run(): void;
+}
+export declare namespace CLI {
+    const ValidEvents: readonly ["command"];
+    type ValidEvent = typeof ValidEvents[number];
+    /**
+     * ## CLI.Command
+     * A command in a CLI Command
+     */
+    class Command {
+        #private;
+        /**
+         * ### Command Constructor
+         * @param name The name of the command
+         * @constructor
+         */
+        constructor(name: string);
+        /**
+         * The name of the Command
+         * @returns {string}
+         */
+        get name(): String;
+        /**
+         * the metadata of the Command
+         * @returns {object}
+         */
+        get metadata(): Object;
+        option(name: string): Command.Option;
+    }
+}
+export declare namespace CLI.Command {
+    /**
+     * ## CLI.Command.Option
+     * A option for a CLI.Command
+     */
+    class Option {
+        #private;
+        get metadata(): {
+            name: string;
+        };
+        constructor(name: string);
+        get name(): string;
+    }
+}
+/**
+ * Will be implemented in v1.2.0
+ * @experimental v1.2.0
+ */
+export declare namespace Utilities {
+}

package/dist/cli-john/index.js

@@ -0,0 +1,308 @@
+/**
+ * @packageDocumentation
+ *
+ * # CLI John
+ *
+ * **CLI John** is a **Node.js CLI framework** designed to create **fully functional CLIs** quickly.
+ * It hooks into a given NodeJS process, automatically listens for commands, parses arguments,
+ * and allows beautiful console messages. Its design is **modular**, using Commands and Options as sub-classes.
+ *
+ * ## Features
+ * - Auto-listening to commands
+ * - Command parsing
+ * - Beautiful console messages
+ * - One CLI per file
+ * - Add your file to `bin` in package.json → CLI works seamlessly
+ * - Event-driven command handling
+ *
+ * ## Usage
+ * ```ts
+ * import { CLI as CLI } from "@briklab/lib/cli-john"
+ * import * as process from "node:process"
+ *
+ * const cli = new CLI(process);
+ *
+ * const cmd = cli.command("myCommand");
+ * const opt = cmd.option("force");
+ *
+ * cmd.on("run", ({commandArgs}) => {
+ *   CJ.notice("Hey, this is my CLI!");
+ *   CJ.message("Do you like it?");
+ *   CJ.error("Invalid args:", ...commandArgs.map(a => a.name));
+ * });
+ *
+ * cli.run();
+ * ```
+ *
+ * ## Limitations
+ * - Only **one CLI per file** is allowed (CLI enforces this)
+ * - CLI file must be manually added to `bin` in package.json
+ *
+ * ## Hierarchy
+ * ```
+ * CLI
+ * ├─ Command
+ * │   └─ Option
+ * └─ CLIErrors
+ * ```
+ *
+ * ## Error Handling
+ * - All errors are instances of `CLIErrors`
+ * - Dynamic names allow easy identification of which part of the CLI threw the error
+ *
+ * @module cli-john
+ */
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _CLI_instances, _CLI_commands, _CLI_onCmdFunctions, _CLI_figureOutCommand, _CLI_process, _CLI_ErrorClass, _CLI_createErr, _CLI_createWarn;
+import JSTC from "../jstc";
+JSTC.addCustomHandler("NodeJS Process", (p) => {
+    return (p &&
+        typeof p === "object" &&
+        typeof p.pid === "number" &&
+        typeof p.cwd === "function" &&
+        typeof p.exit === "function");
+});
+//#endregion
+// -------------------------------------------------------------------------------------------------------
+//#region The Main Class
+/**
+ * # CLI
+ * @classdesc The main class for **CLI**.
+ * @example
+ * import * as process from "node:process"
+ * import {CLI} from "@briklab/lib/cli-john"
+ * const cli = new CLI(process)
+ * cli.run()
+ */
+export class CLI {
+    /**
+     * ## CLI: Constructor
+     * @param {NodeJS.Process} process - **The main process**
+     * @constructor
+     * @constructs CLI
+     * @example
+     * import * as process from "node:process"
+     * import {CLI} from "@briklab/lib/cli-john"
+     * const cli = new CLI(process)
+     * cli.run()
+     */
+    constructor(process) {
+        _CLI_instances.add(this);
+        _CLI_commands.set(this, []);
+        _CLI_onCmdFunctions.set(this, []);
+        _CLI_process.set(this, void 0);
+        _CLI_ErrorClass.set(this, class extends CLIErrors {
+            constructor(message) {
+                super(message);
+                this.setName = "CLI";
+            }
+        });
+        if (!JSTC.for([process]).check(["NodeJS Process"])) {
+            throw __classPrivateFieldGet(this, _CLI_instances, "m", _CLI_createErr).call(this, "Invalid First Argument!", "You must pass a valid NodeJS process (imported from node:process) while constructing a CLI Class!");
+        }
+        __classPrivateFieldSet(this, _CLI_process, process, "f");
+    }
+    /**
+     * ### CLI.command
+     * create a new command in a CLI.
+     *
+     * @param {string} name
+     */
+    command(name) {
+        if (!JSTC.for([name]).check(["string"])) {
+            __classPrivateFieldGet(this, _CLI_instances, "m", _CLI_createWarn).call(this, "Invalid First Argument!", "CLI.option expects a string as the first argument.", "Using String(given argument) as fallback.");
+            name = String(name);
+        }
+        let c = new CLI.Command(name);
+        let f = __classPrivateFieldGet(this, _CLI_commands, "f").findIndex((a) => a.name === name);
+        if (f !== -1)
+            __classPrivateFieldGet(this, _CLI_commands, "f")[f] = c;
+        else
+            __classPrivateFieldGet(this, _CLI_commands, "f").push(c);
+        return c;
+    }
+    on(event, func) {
+        if (!JSTC.for([event, func]).check(["string", "function"]))
+            throw __classPrivateFieldGet(this, _CLI_instances, "m", _CLI_createErr).call(this, "Arguments in CLI.on are invalid!", "The first argument must be a string, and the second argument must be a function.");
+        switch (event.toLowerCase()) {
+            case "command":
+                __classPrivateFieldGet(this, _CLI_onCmdFunctions, "f").push(func);
+                break;
+            default:
+                __classPrivateFieldGet(this, _CLI_instances, "m", _CLI_createWarn).call(this, "Invalid event in CLI.on", "Please enter a valid event from CLI.ValidEvents (array)");
+        }
+    }
+    run() {
+        let { options, commandArgs, command, failed } = __classPrivateFieldGet(this, _CLI_instances, "m", _CLI_figureOutCommand).call(this);
+        if (failed)
+            return;
+        for (let i = 0; i < __classPrivateFieldGet(this, _CLI_onCmdFunctions, "f").length; i++) {
+            __classPrivateFieldGet(this, _CLI_onCmdFunctions, "f")[i]({ options, commandArgs, command });
+        }
+    }
+}
+_CLI_commands = new WeakMap(), _CLI_onCmdFunctions = new WeakMap(), _CLI_process = new WeakMap(), _CLI_ErrorClass = new WeakMap(), _CLI_instances = new WeakSet(), _CLI_figureOutCommand = function _CLI_figureOutCommand() {
+    // for eg. we have nodepath filepath cli build
+    let [, , ...commands] = __classPrivateFieldGet(this, _CLI_process, "f").argv; // now its cli build. clear
+    if (commands.length === 0)
+        return { options: [], command: "", commandArgs: [], failed: true };
+    let command = __classPrivateFieldGet(this, _CLI_commands, "f").find((a) => a.name === commands[0]); // find the command
+    if (!command)
+        return { options: [], command: "", commandArgs: [], failed: true }; // command not found?
+    let commandArgs = [];
+    const args = commands.slice(1);
+    for (let i = 0; i < args.length; i++) {
+        let arg = args[i];
+        if (arg.startsWith("--"))
+            break;
+        commandArgs.push(arg);
+    }
+    let leftover = args.slice(commandArgs.length); // args = [1,2,3]; command args = [1,2] command args length is 2, therefore .slice(2) results in [3]
+    let options = [];
+    for (let i = 0; i < leftover.length; i++) {
+        const opt = leftover[i];
+        if (!opt.startsWith("--"))
+            continue;
+        const values = [];
+        for (let j = i + 1; j < leftover.length; j++) {
+            if (leftover[j].startsWith("--"))
+                break;
+            values.push(leftover[j]);
+        }
+        options.push({ option: opt, arguments: values });
+    }
+    return {
+        options,
+        commandArgs,
+        command,
+        failed: false,
+    };
+}, _CLI_createErr = function _CLI_createErr(message, hint) {
+    return new (__classPrivateFieldGet(this, _CLI_ErrorClass, "f"))(`${message}
+        Hint: ${hint}`);
+}, _CLI_createWarn = function _CLI_createWarn(message, hint, otherMessage) {
+    return console.warn(`[Class CLI] ${message}
+        Hint: ${hint}
+        ${otherMessage}`);
+};
+//#endregion
+// -------------------------------------------------------------------------------------------------------
+//#region Error Class
+class CLIErrors extends Error {
+    constructor(message) {
+        super(message);
+        this.name = `[] @briklab/lib/cli-john`;
+        Error.captureStackTrace(this, CLIErrors);
+    }
+    set setName(name) {
+        this.name = `[${name}] @briklab/lib/cli-john`;
+    }
+}
+(function (CLI) {
+    var _Command_instances, _Command_name, _Command_createWarn, _Command_options;
+    CLI.ValidEvents = [
+        "command"
+    ];
+    /**
+     * ## CLI.Command
+     * A command in a CLI Command
+     */
+    class Command {
+        /**
+         * ### Command Constructor
+         * @param name The name of the command
+         * @constructor
+         */
+        constructor(name) {
+            _Command_instances.add(this);
+            _Command_name.set(this, void 0);
+            _Command_options.set(this, []);
+            __classPrivateFieldSet(this, _Command_name, name, "f");
+            return this;
+        }
+        /**
+         * The name of the Command
+         * @returns {string}
+         */
+        get name() {
+            return __classPrivateFieldGet(this, _Command_name, "f");
+        }
+        /**
+         * the metadata of the Command
+         * @returns {object}
+         */
+        get metadata() {
+            let metadata = {
+                options: __classPrivateFieldGet(this, _Command_options, "f").map((a) => a.metadata),
+                name: this.name,
+            };
+            return metadata;
+        }
+        option(name) {
+            if (!JSTC.for([name]).check(["string"])) {
+                __classPrivateFieldGet(this, _Command_instances, "m", _Command_createWarn).call(this, "First argument is invalid!", "The first argument must be a string", "Using String(argument) as fallback");
+                name = String(name);
+            }
+            let o = new CLI.Command.Option(name);
+            let f = __classPrivateFieldGet(this, _Command_options, "f").findIndex((a) => a.name === name);
+            if (f !== -1)
+                __classPrivateFieldGet(this, _Command_options, "f")[f] = o;
+            else
+                __classPrivateFieldGet(this, _Command_options, "f").push(o);
+            return o;
+        }
+    }
+    _Command_name = new WeakMap(), _Command_options = new WeakMap(), _Command_instances = new WeakSet(), _Command_createWarn = function _Command_createWarn(message, hint, otherMessage) {
+        return console.warn(`[Class CLI.Command] ${message}
+        Hint: ${hint}
+        ${otherMessage}`);
+    };
+    CLI.Command = Command;
+})(CLI || (CLI = {}));
+//#endregion
+// -------------------------------------------------------------------------------------------------------
+//#region CLI.Command.Option
+(function (CLI) {
+    var Command;
+    (function (Command) {
+        var _Option_name;
+        /**
+         * ## CLI.Command.Option
+         * A option for a CLI.Command
+         */
+        class Option {
+            get metadata() {
+                let metadata = {
+                    name: `${__classPrivateFieldGet(this, _Option_name, "f")}`, // <-- Templates TO NOT reference the actual variable
+                };
+                return metadata;
+            }
+            constructor(name) {
+                _Option_name.set(this, void 0);
+                __classPrivateFieldSet(this, _Option_name, name, "f");
+                return this;
+            }
+            get name() {
+                return __classPrivateFieldGet(this, _Option_name, "f");
+            }
+        }
+        _Option_name = new WeakMap();
+        Command.Option = Option;
+    })(Command = CLI.Command || (CLI.Command = {}));
+})(CLI || (CLI = {}));
+//#endregion
+// -------------------------------------------------------------------------------------------------------
+//#region TODO
+// TODO: Wire Options to Commands
+// TODO: Create metadata getter-s in both commands and options
+//#endregion

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @packageDocumentation
+ * The main library for briklab packages
+ */
+export {};

package/dist/index.js

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

package/dist/jstc/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @packageDocumentation
+ * Runtime JS Type Checker
+ * @module JSTC
+ */
+type PrimitiveType = "string" | "number" | "boolean" | "object" | "function" | "undefined" | "symbol" | "bigint";
+type ConstructorType = Function;
+export type JSType = PrimitiveType | ConstructorType | string;
+export type JSTypeOrArray = JSType | JSType[];
+export declare class JSTypeChecker {
+    #private;
+    /**
+     * check if specific arguments are of a specific type, class, etc.
+     * @param {unknown[]} args
+     */
+    for(args: unknown[]): {
+        check: (types: JSTypeOrArray[]) => boolean;
+    };
+    addCustomHandler(name: string, handler: (value: unknown) => boolean): void;
+}
+declare const JSTC: JSTypeChecker;
+export default JSTC;

package/dist/jstc/index.js

@@ -0,0 +1,69 @@
+/**
+ * @packageDocumentation
+ * Runtime JS Type Checker
+ * @module JSTC
+ */
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _JSTypeChecker___CustomHandler;
+export class JSTypeChecker {
+    constructor() {
+        _JSTypeChecker___CustomHandler.set(this, {
+            Array: (value) => Array.isArray(value),
+            "string[]": (value) => Array.isArray(value) && value.every((v) => typeof v === "string"),
+        });
+    }
+    /**
+     * check if specific arguments are of a specific type, class, etc.
+     * @param {unknown[]} args
+     */
+    for(args) {
+        return {
+            check: (types) => {
+                if (args.length < types.length)
+                    return false;
+                for (let i = 0; i < types.length; i++) {
+                    const value = args[i];
+                    const expected = types[i];
+                    const expectedTypes = Array.isArray(expected) ? expected : [expected];
+                    let matched = false;
+                    for (const tRaw of expectedTypes) {
+                        const unionTypes = typeof tRaw === "string" ? tRaw.split("|") : [tRaw];
+                        for (const t of unionTypes) {
+                            if (typeof t === "function") {
+                                if (value instanceof t) {
+                                    matched = true;
+                                    break;
+                                }
+                            }
+                            else if (typeof t === "string" && __classPrivateFieldGet(this, _JSTypeChecker___CustomHandler, "f")[t]) {
+                                if (__classPrivateFieldGet(this, _JSTypeChecker___CustomHandler, "f")[t](value)) {
+                                    matched = true;
+                                    break;
+                                }
+                            }
+                            else if (typeof value === t) {
+                                matched = true;
+                                break;
+                            }
+                        }
+                        if (matched)
+                            break;
+                    }
+                    if (!matched)
+                        return false;
+                }
+                return true;
+            },
+        };
+    }
+    addCustomHandler(name, handler) {
+        __classPrivateFieldGet(this, _JSTypeChecker___CustomHandler, "f")[name] = handler;
+    }
+}
+_JSTypeChecker___CustomHandler = new WeakMap();
+const JSTC = new JSTypeChecker();
+export default JSTC;

package/dist/stylesheet/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * SOON
+ * @experimental v1.1.0
+ */
+export {};

package/dist/stylesheet/index.js

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

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@briklab/lib",
+  "author": {
+    "email": "ekaanshagarwal19554@gmail.com",
+    "name": "ObiloxYT",
+    "url": "https://youtube.com/@ObiloxYT"
+  },
+  "contributors": [
+    "ObiloxYT"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "markdown": "github",
+  "type": "module",
+  "description": "@briklab/lib is the core library for all @briklab packages.",
+  "homepage": "https://github.com/EkaanshPC/briklab-stdlib",
+  "keywords": [
+    "helpers",
+    "typescript",
+    "types"
+  ],
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "private": false,
+  "readme": "README.md",
+  "repository": {
+    "url": "https://github.com/EkaanshPC/briklab-stdlib"
+  },
+  "version": "1.0.0",
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./cli-john": {
+      "import": "./dist/cli-john/index.js",
+      "types": "./dist/cli-john/index.d.ts"
+    },
+    "./jstc": {
+      "import": "./dist/jstc/index.js",
+      "types": "./dist/jstc/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+
+    "rootDir": "src",
+    "outDir": "dist",
+
+    "declaration": true,  
+    "strict": true,
+
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": [
+        "Node"
+    ]
+  },
+  "include": ["src"],
+"experimentalDecorators": true
+}