boperators 0.1.0

package/README.md

@@ -0,0 +1,202 @@
+<center>
+
+# boperators
+### Operator overloading JavaScript and TypeScript.
+
+</center>
+
+Operator overloading is a common programming feature that JavaScript lacks. Just something as simple as adding two vectors, we've got to create a `.Add` method or add elements one-at-a-time.
+
+`boperators` finally brings operator overloading to JavaScript by leveraging TypeScript typings. You define one or more overload functions on a class for whichever operators you want, and with magic we search for anywhere you've used overloaded operators and substitute in your functions.
+
+This is the core library and API, and isn't designed to be used directly. Instead, you can use the [Boperators CLI](https://www.npmjs.com/package/@boperators/cli) or our plugins for [compiling with `tsc`](https://www.npmjs.com/package/@boperators/plugin-tsc) or for [running directly with Bun](https://www.npmjs.com/package/@boperators/plugin-bun).
+
+We also offer a [TypeScript Language Server plugin](https://www.npmjs.com/package/@boperators/plugin-ts-language-server) for real-time type hinting and intellisense in your IDE, and an [MCP server](https://www.npmjs.com/package/@boperators/mcp-server) to optimize your vibe coding experience.
+
+
+## Installation
+
+```sh
+npm install -D boperators @boperators/cli @boperators/plugin-ts-language-server
+```
+
+
+## Defining Overloads
+
+Define overloads as property arrays on your classes, using the operator string as the property name. Overload fields are readonly arrays (with `as const` at the end) so you can define multiple overloads for different types. As long as you don't have overlapping typings between any functions, we can work out which one to use in a given situation. 
+
+### Static Operators
+
+Static operators (`+`, `-`, `*`, `/`, `%`, comparisons, logical) are `static readonly` fields with two-parameter functions (LHS and RHS). At least one parameter must match the class type.
+
+Arrow functions or function expressions both work for static operators.
+
+```typescript
+class Vector3 {
+    static readonly "+" = [
+        (a: Vector3, b: Vector3) => new Vector3(a.x + b.x, a.y + b.y, a.z + b.z),
+    ] as const;
+
+    // Multiple overloads for different RHS types
+    static readonly "*" = [
+        function (a: Vector3, b: Vector3): Vector3 {
+            return new Vector3(
+                a.y * b.z - a.z * b.y,
+                a.z * b.x - a.x * b.z,
+                a.x * b.y - a.y * b.x,
+            );
+		},
+        function mutliplyByScalar(a: Vector3, b: number): Vector3 {
+            return new Vector3(a.x * b, a.y * b, a.z * b);
+		}
+    ] as const;
+
+    // Comparison operators must return boolean
+    static readonly "==" = [
+        (a: Vector3, b: Vector3): boolean => a.length() === b.length(),
+    ] as const;
+}
+```
+
+### Instance Operators
+
+Instance operators (`+=`, `-=`, `*=`, `/=`, `%=`, `&&=`, `||=`) are `readonly` instance fields with a single parameter (the RHS). They use `this` to mutate the LHS object and must return `void`.
+
+Instance operators **must** use function expressions (not arrow functions), because arrow functions cannot bind `this`.
+
+```typescript
+class Vector3 {
+    readonly "+=" = [
+        function (this: Vector3, rhs: Vector3): void {
+            this.x += rhs.x;
+            this.y += rhs.y;
+            this.z += rhs.z;
+        },
+    ];
+}
+```
+
+Unlike with JavaScript primitives, you can declare a variable as `const` and still use assignment operators with this, as they're only mutating the object.
+
+```typescript
+const vec3 = new Vector3(3, 4, 5);
+vec3 += new Vector3(6, 7, 8);
+```
+
+### Prefix Unary Operators
+
+Prefix unary operators (`-`, `+`, `!`, `~`) are `static readonly` fields with one-parameter functions. The parameter must match the class type. For operators that also have binary forms (`-`, `+`), both binary and unary overloads can coexist in the same array, distinguished by parameter count.
+
+```typescript
+class Vector3 {
+    static readonly "-" = [
+		// two parameters means binary operation: `a - b`
+        (a: Vector3, b: Vector3) =>
+            new Vector3(a.x - b.x, a.y - b.y, a.z - b.z),
+		// single parameter means unary operation, e.g. making a value "negative"
+        (a: Vector3) =>
+            new Vector3(-a.x, -a.y, -a.z), // unary: -a
+    ] as const;
+
+    static readonly "!" = [
+        (a: Vector3): boolean =>
+            a.x === 0 && a.y === 0 && a.z === 0,
+    ] as const;
+}
+```
+
+### Postfix Unary Operators
+
+Postfix unary operators (`++`, `--`) are `readonly` instance fields with zero-parameter functions (only `this`). They mutate the object and must return `void`. Must use function expressions, not arrow functions.
+
+```typescript
+class Counter {
+    value = 0;
+
+    readonly "++" = [
+        function (this: Counter): void {
+            this.value++;
+        },
+    ] as const;
+}
+```
+
+### Using Overloaded Operators Within Definitions
+
+The transform only applies to **consuming code**, not to the overload definitions themselves. If you need to call an overloaded operator inside an overload body (including on the same class), reference the overload array directly:
+
+```typescript
+class Expr {
+    static readonly "-" = [
+        // unary negation
+        (inner: Expr): Expr => new Expr.Neg(inner),
+
+        // binary minus — calls the unary overload and the + overload directly
+        (lhs: Expr, rhs: Expr): Expr =>
+            lhs + Expr["-"][0](rhs),
+
+        (lhs: Expr, rhs: number): Expr =>
+            lhs + Expr["-"][0](new Expr.Num(rhs)),
+
+        (lhs: number, rhs: Expr): Expr =>
+            new Expr.Num(lhs) + Expr["-"][0](rhs),
+    ] as const;
+}
+```
+
+Writing `lhs + -rhs` inside the overload body would **not** be transformed, since the source transform has not yet run on this code. Use `ClassName["op"][index](args)` for static overloads and `obj["op"][index].call(obj, args)` for instance overloads.
+
+## How It Works
+
+`boperators` has a two-phase pipeline:
+
+1. **Parse**: `OverloadStore` scans all source files for classes with operator-named properties and indexes them by `(operatorKind, lhsType, rhsType)`.
+2. **Transform**: `OverloadInjector` finds binary and unary expressions, looks up matching overloads, and replaces them:
+   - **Binary static**: `a + b` becomes `ClassName["+"][0](a, b)`
+   - **Binary instance**: `a += b` becomes `a["+="][0].call(a, b)`
+   - **Prefix unary**: `-a` becomes `ClassName["-"][1](a)`
+   - **Postfix unary**: `x++` becomes `x["++"][0].call(x)`
+
+Imports for referenced classes are automatically added where needed.
+
+## Supported Operators
+
+| Operator | Type | Notes |
+|----------|------|-------|
+| `+` | static | |
+| `-` | static | |
+| `*` | static | |
+| `/` | static | |
+| `%` | static | |
+| `+=` | instance | Must return `void` |
+| `-=` | instance | Must return `void` |
+| `*=` | instance | Must return `void` |
+| `/=` | instance | Must return `void` |
+| `%=` | instance | Must return `void` |
+| `>` | static | Must return `boolean` |
+| `>=` | static | Must return `boolean` |
+| `<` | static | Must return `boolean` |
+| `<=` | static | Must return `boolean` |
+| `==` | static | Must return `boolean` |
+| `===` | static | Must return `boolean` |
+| `!=` | static | Must return `boolean` |
+| `!==` | static | Must return `boolean` |
+| `&&` | static | |
+| `\|\|` | static | |
+| `??` | static | |
+| `&&=` | instance | Must return `void` |
+| `\|\|=` | instance | Must return `void` |
+| `-` (unary) | static | Prefix negation (1 param) |
+| `+` (unary) | static | Prefix plus (1 param) |
+| `!` | static | Prefix logical NOT (1 param) |
+| `~` | static | Prefix bitwise NOT (1 param) |
+| `++` | instance | Postfix increment, must return `void` |
+| `--` | instance | Postfix decrement, must return `void` |
+
+## Conflict Detection
+
+When parsing overload definitions, if there are duplicate overloads with matching `(operator, lhsType, rhsType)`, a warning is shown (or an error if `--error-on-warning` is set via the CLI).
+
+## License
+
+MIT

package/dist/cjs/core/BopConfig.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleLogger = void 0;
+exports.loadConfig = loadConfig;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const CONFIG_FILE_NAME = ".bopconf.json";
+// ----- ConsoleLogger -----
+class ConsoleLogger {
+    debug(msg) {
+        console.debug(`[boperators] ${msg}`);
+    }
+    info(msg) {
+        console.log(`[boperators] ${msg}`);
+    }
+    warn(msg) {
+        console.warn(`[boperators] ${msg}`);
+    }
+    error(msg) {
+        console.error(`[boperators] ${msg}`);
+    }
+}
+exports.ConsoleLogger = ConsoleLogger;
+// ----- Filtered logger -----
+const LOG_LEVELS = ["debug", "info", "warn", "error", "silent"];
+function createFilteredLogger(inner, level) {
+    const minIndex = LOG_LEVELS.indexOf(level);
+    const noop = () => { };
+    return {
+        debug: minIndex <= 0 ? inner.debug.bind(inner) : noop,
+        info: minIndex <= 1 ? inner.info.bind(inner) : noop,
+        warn: minIndex <= 2 ? inner.warn.bind(inner) : noop,
+        error: minIndex <= 3 ? inner.error.bind(inner) : noop,
+    };
+}
+// ----- Config file discovery -----
+function findConfigFile(startDir) {
+    let dir = node_path_1.default.resolve(startDir);
+    while (true) {
+        const candidate = node_path_1.default.join(dir, CONFIG_FILE_NAME);
+        try {
+            const content = node_fs_1.default.readFileSync(candidate, "utf-8");
+            return JSON.parse(content);
+        }
+        catch (_a) {
+            // File not found or invalid JSON — keep walking up
+        }
+        const parent = node_path_1.default.dirname(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+    return {};
+}
+const DEFAULTS = {
+    errorOnWarning: false,
+    logLevel: "info",
+};
+function loadConfig(options) {
+    var _a, _b;
+    const fileConfig = findConfigFile((_a = options === null || options === void 0 ? void 0 : options.searchDir) !== null && _a !== void 0 ? _a : process.cwd());
+    const merged = Object.assign(Object.assign(Object.assign({}, DEFAULTS), fileConfig), options === null || options === void 0 ? void 0 : options.overrides);
+    const baseLogger = (_b = options === null || options === void 0 ? void 0 : options.logger) !== null && _b !== void 0 ? _b : new ConsoleLogger();
+    const logger = createFilteredLogger(baseLogger, merged.logLevel);
+    return {
+        errorOnWarning: merged.errorOnWarning,
+        logLevel: merged.logLevel,
+        logger,
+    };
+}

package/dist/cjs/core/ErrorManager.js

@@ -0,0 +1,126 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorManager = exports.ErrorDescription = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Stores information about an error or warning for later use.
+ */
+class ErrorDescription {
+    /**
+     * Create an ErrorDescription.
+     *
+     * @param errorMessage Custom message text describing the error.
+     * @param filePath Error file path.
+     * @param lineNumber Error line number in its file.
+     * @param codeText Code relevant to the error.q
+     */
+    constructor(errorMessage, filePath, lineNumber, codeText) {
+        this.errorMessage = errorMessage;
+        this.filePath = filePath;
+        this.lineNumber = lineNumber;
+        this.codeText = codeText;
+        this.fileName = node_path_1.default.basename(filePath);
+    }
+    toString() {
+        return `${this.fileName}:${this.lineNumber}: ${this.errorMessage}\n${this.codeText}\n`;
+    }
+}
+exports.ErrorDescription = ErrorDescription;
+/**
+ * Stores errors and warnings in a way that means
+ * they can be logged or thrown at a later point.
+ */
+class ErrorManager {
+    constructor(config) {
+        /**
+         * Array of warnings.
+         */
+        this._warnings = [];
+        /**
+         * Array of errors.
+         */
+        this._errors = [];
+        this._config = config;
+        this._errorOnWarning = config.errorOnWarning;
+    }
+    /**
+     * Add an ErrorDescription or a string as a "warning",
+     * meaning it will not throw unless `errorOnWarning` is true.
+     * @param description Either a string describing the error or a {@link ErrorDescription} instance.
+     */
+    addWarning(description) {
+        this._warnings.push(description);
+    }
+    /**
+     * Add an ErrorDescription or a string as an "error",
+     * meaning it will throw when checked.
+     * @param description Either a string describing the error or a {@link ErrorDescription} instance.
+     */
+    addError(description) {
+        this._errors.push(description);
+    }
+    /**
+     * Gets all warnings as a single string, separated by newlines.
+     * @returns String of all warnings.
+     */
+    getWarningString() {
+        return this._warnings.map((warning) => warning.toString()).join("\n");
+    }
+    /**
+     * Gets all errors as a single string, separated by newlines.
+     * @returns String of all errors.
+     */
+    getErrorsString() {
+        return this._errors.map((error) => error.toString()).join("\n");
+    }
+    /**
+     * Throws if there are any errors currently registered in the ErrorManager.
+     * If `errorOnWarning` is true then it will also throw if there are warnings.
+     */
+    throwIfErrors() {
+        const shouldThrow = this._errors.length > 0 ||
+            (this._errorOnWarning && this._warnings.length > 0);
+        if (!shouldThrow)
+            return;
+        const errorString = this.getErrorsString() +
+            (this._errorOnWarning ? this.getWarningString() : "");
+        throw new Error(errorString);
+    }
+    /**
+     * Will throw if there are any errors, or if there are warnings and `errorOnWarning` is true.
+     * If it does not throw then it will log all wanrnings to the console.
+     * @param clearSelf If true, all warnings will be cleared after logging.
+     */
+    throwIfErrorsElseLogWarnings(clearSelf = true) {
+        this.throwIfErrors();
+        if (this._warnings.length > 0) {
+            this._config.logger.warn(this.getWarningString());
+        }
+        if (clearSelf) {
+            this.clearWarnings();
+        }
+    }
+    /**
+     * Clear out registered warnings to prevent duplicate logging.
+     */
+    clearWarnings() {
+        this._warnings = [];
+    }
+    /**
+     * Clear out registered errors.
+     */
+    clearErrors() {
+        this._errors = [];
+    }
+    /**
+     * Clear all registered errors and warnings.
+     */
+    clear() {
+        this._errors = [];
+        this._warnings = [];
+    }
+}
+exports.ErrorManager = ErrorManager;

package/dist/cjs/core/OverloadInjector.js

@@ -0,0 +1,136 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OverloadInjector = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const ts_morph_1 = require("ts-morph");
+const ensureImportedName_1 = require("./helpers/ensureImportedName");
+const getModuleSpecifier_1 = require("./helpers/getModuleSpecifier");
+const resolveExpressionType_1 = require("./helpers/resolveExpressionType");
+const operatorMap_1 = require("./operatorMap");
+const SourceMap_1 = require("./SourceMap");
+class OverloadInjector {
+    constructor(
+    /**
+     * TS Morph project.
+     */
+    _project, 
+    /**
+     * Overload store.
+     */
+    _overloadStore, logger) {
+        this._project = _project;
+        this._overloadStore = _overloadStore;
+        this._logger = logger;
+    }
+    overloadFile(file) {
+        const sourceFile = file instanceof ts_morph_1.SourceFile
+            ? file
+            : this._project.getSourceFileOrThrow(file);
+        const fileName = node_path_1.default.basename(sourceFile.getFilePath());
+        const originalText = sourceFile.getFullText();
+        let transformCount = 0;
+        // Process one innermost binary expression per iteration,
+        // re-fetching descendants each time so types resolve correctly
+        // after each transformation and AST references stay fresh.
+        let changed = true;
+        while (changed) {
+            changed = false;
+            // Reverse DFS pre-order → innermost expressions first
+            const binaryExpressions = sourceFile
+                .getDescendantsOfKind(ts_morph_1.SyntaxKind.BinaryExpression)
+                .reverse();
+            for (const expression of binaryExpressions) {
+                const operatorKind = expression.getOperatorToken().getKind();
+                if (!(0, operatorMap_1.isOperatorSyntaxKind)(operatorKind))
+                    continue;
+                const lhs = expression.getLeft();
+                const leftType = (0, resolveExpressionType_1.resolveExpressionType)(lhs);
+                const rhs = expression.getRight();
+                const rightType = (0, resolveExpressionType_1.resolveExpressionType)(rhs);
+                const overloadDesc = this._overloadStore.findOverload(operatorKind, leftType, rightType);
+                if (!overloadDesc)
+                    continue;
+                const { className: classNameRaw, classFilePath, operatorString, index, isStatic, } = overloadDesc;
+                // Look up the fresh ClassDeclaration from the project
+                const classSourceFile = this._project.getSourceFileOrThrow(classFilePath);
+                const classDecl = classSourceFile.getClassOrThrow(classNameRaw);
+                // Ensure class is imported, get its textual name
+                const classModuleSpecifier = (0, getModuleSpecifier_1.getModuleSpecifier)(sourceFile, classSourceFile);
+                const className = (0, ensureImportedName_1.ensureImportedName)(sourceFile, classDecl.getSymbol(), classModuleSpecifier);
+                // Build the text code to replace the binary operator with the overload call
+                const overloadCall = isStatic
+                    ? `${className}["${operatorString}"][${index}](${lhs.getText()}, ${rhs.getText()})`
+                    : `${lhs.getText()}["${operatorString}"][${index}].call(${lhs.getText()}, ${rhs.getText()})`;
+                this._logger.debug(`${fileName}: ${expression.getText()} => ${overloadCall}`);
+                expression.replaceWithText(overloadCall);
+                transformCount++;
+                changed = true;
+                break; // re-fetch descendants after each mutation
+            }
+        }
+        // Process prefix unary expressions (-x, +x, !x, ~x)
+        changed = true;
+        while (changed) {
+            changed = false;
+            const prefixExpressions = sourceFile
+                .getDescendantsOfKind(ts_morph_1.SyntaxKind.PrefixUnaryExpression)
+                .reverse();
+            for (const expression of prefixExpressions) {
+                const operatorKind = expression.getOperatorToken();
+                if (!(0, operatorMap_1.isPrefixUnaryOperatorSyntaxKind)(operatorKind))
+                    continue;
+                const operand = expression.getOperand();
+                const operandType = (0, resolveExpressionType_1.resolveExpressionType)(operand);
+                const overloadDesc = this._overloadStore.findPrefixUnaryOverload(operatorKind, operandType);
+                if (!overloadDesc)
+                    continue;
+                const { className: classNameRaw, classFilePath, operatorString, index, } = overloadDesc;
+                const classSourceFile = this._project.getSourceFileOrThrow(classFilePath);
+                const classDecl = classSourceFile.getClassOrThrow(classNameRaw);
+                const classModuleSpecifier = (0, getModuleSpecifier_1.getModuleSpecifier)(sourceFile, classSourceFile);
+                const className = (0, ensureImportedName_1.ensureImportedName)(sourceFile, classDecl.getSymbol(), classModuleSpecifier);
+                const overloadCall = `${className}["${operatorString}"][${index}](${operand.getText()})`;
+                this._logger.debug(`${fileName}: ${expression.getText()} => ${overloadCall}`);
+                expression.replaceWithText(overloadCall);
+                transformCount++;
+                changed = true;
+                break;
+            }
+        }
+        // Process postfix unary expressions (x++, x--)
+        changed = true;
+        while (changed) {
+            changed = false;
+            const postfixExpressions = sourceFile
+                .getDescendantsOfKind(ts_morph_1.SyntaxKind.PostfixUnaryExpression)
+                .reverse();
+            for (const expression of postfixExpressions) {
+                const operatorKind = expression.getOperatorToken();
+                if (!(0, operatorMap_1.isPostfixUnaryOperatorSyntaxKind)(operatorKind))
+                    continue;
+                const operand = expression.getOperand();
+                const operandType = (0, resolveExpressionType_1.resolveExpressionType)(operand);
+                const overloadDesc = this._overloadStore.findPostfixUnaryOverload(operatorKind, operandType);
+                if (!overloadDesc)
+                    continue;
+                const { operatorString, index } = overloadDesc;
+                const overloadCall = `${operand.getText()}["${operatorString}"][${index}].call(${operand.getText()})`;
+                this._logger.debug(`${fileName}: ${expression.getText()} => ${overloadCall}`);
+                expression.replaceWithText(overloadCall);
+                transformCount++;
+                changed = true;
+                break;
+            }
+        }
+        if (transformCount > 0) {
+            this._logger.debug(`${fileName}: ${transformCount} expression${transformCount === 1 ? "" : "s"} transformed`);
+        }
+        const text = sourceFile.getFullText();
+        const sourceMap = new SourceMap_1.SourceMap(originalText, text);
+        return { sourceFile, text, sourceMap };
+    }
+}
+exports.OverloadInjector = OverloadInjector;