@boperators/webpack-loader 0.1.4

package/README.md

@@ -0,0 +1,139 @@
+# @boperators/webpack-loader
+
+![Sym.JS logo](https://github.com/DiefBell/boperators/blob/653ea138f4dcd1e6b4dd112133a4942f70e91fb3/logo.png)
+
+Webpack loader for [boperators](https://www.npmjs.com/package/boperators) that transforms operator overloads during the webpack build. Runs as a pre-loader before your TypeScript loader, replacing operator expressions with function calls and generating source maps.
+
+## Installation
+
+```sh
+npm install -D boperators @boperators/webpack-loader ts-loader webpack
+```
+
+## Configuration
+
+Add the boperators loader as an `enforce: "pre"` rule in your `webpack.config.js`, alongside your TypeScript loader:
+
+```js
+module.exports = {
+  devtool: "source-map",
+  module: {
+    rules: [
+      {
+        test: /\.ts$/,
+        loader: "ts-loader",
+        options: { transpileOnly: true },
+        exclude: /node_modules/,
+      },
+      {
+        test: /\.ts$/,
+        enforce: "pre",
+        loader: "@boperators/webpack-loader",
+        exclude: /node_modules/,
+      },
+    ],
+  },
+};
+```
+
+The `enforce: "pre"` ensures boperators transforms your source before `ts-loader` compiles it.
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `project` | `string` | `"tsconfig.json"` | Path to `tsconfig.json`, relative to webpack's root context |
+| `errorOnWarning` | `boolean` | `false` | Treat conflicting overload warnings as errors |
+
+Options are passed via the loader options:
+
+```js
+{
+  test: /\.ts$/,
+  enforce: "pre",
+  loader: "@boperators/webpack-loader",
+  options: {
+    project: "./tsconfig.build.json",
+  },
+  exclude: /node_modules/,
+}
+```
+
+## Next.js
+
+### Webpack (default)
+
+Next.js exposes webpack config via `next.config.js`. Add boperators as a pre-loader before `ts-loader` handles your TypeScript:
+
+```js
+// next.config.js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  webpack(config) {
+    config.module.rules.push({
+      test: /\.tsx?$/,
+      enforce: "pre",
+      loader: "@boperators/webpack-loader",
+      exclude: /node_modules/,
+    });
+    return config;
+  },
+};
+
+module.exports = nextConfig;
+```
+
+You don't need to add a separate `ts-loader` rule — Next.js already configures TypeScript compilation internally.
+
+### Turbopack (Next.js 15+)
+
+Turbopack supports webpack loaders via `turbopack.rules`. The boperators loader is likely compatible, but note that Turbopack's webpack loader API is partial and `this.rootContext` (used for tsconfig discovery) may not be populated. Use the `project` option to specify the tsconfig path explicitly:
+
+```js
+// next.config.js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  turbopack: {
+    rules: {
+      "*.{ts,tsx}": {
+        loaders: [
+          {
+            loader: "@boperators/webpack-loader",
+            options: { project: "./tsconfig.json" },
+          },
+        ],
+        as: "*.tsx",
+      },
+    },
+  },
+};
+
+module.exports = nextConfig;
+```
+
+> **Note:** Turbopack support is best-effort. If you encounter issues, fall back to the webpack config above (removing the `--turbopack` flag from your `next dev` command).
+
+## How It Works
+
+The loader runs as a webpack pre-loader, executing before TypeScript compilation:
+
+1. Creates a [ts-morph](https://ts-morph.com) Project from your tsconfig
+2. Scans all source files for operator overload definitions
+3. Transforms expressions in the current file (e.g. `v1 + v2` becomes `Vector3["+"][0](v1, v2)`)
+4. Generates a V3 source map so stack traces and debugger breakpoints map back to your original source
+5. Passes the transformed code to the next loader (e.g. `ts-loader`)
+
+## Comparison with Other Approaches
+
+| Approach | When it runs | Use case |
+|----------|-------------|----------|
+| **`@boperators/cli`** | Before compilation | Batch transform to disk, then compile normally |
+| **`@boperators/plugin-tsc`** | During compilation | Seamless `tsc` integration, no intermediate files |
+| **`@boperators/webpack-loader`** | During bundling | Webpack projects, integrates into existing build pipeline |
+| **`@boperators/plugin-vite`** | During bundling | Vite projects, integrates into Rollup-based pipeline |
+| **`@boperators/plugin-esbuild`** | During bundling | ESBuild projects, fast bundler integration |
+| **`@boperators/plugin-bun`** | At runtime | Bun-only, transforms on module load |
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = __importDefault(require("node:path"));
+const boperators_1 = require("boperators");
+function normalizePath(p) {
+    return p.replace(/\\/g, "/");
+}
+const loader = function (source, _map) {
+    var _a;
+    const callback = this.async();
+    if (!callback)
+        return;
+    try {
+        const resourcePath = normalizePath(this.resourcePath);
+        // Resolve tsconfig path: explicit option, or default to rootContext/tsconfig.json
+        const projectOption = (_a = this.getOptions()) === null || _a === void 0 ? void 0 : _a.project;
+        const tsconfigPath = projectOption
+            ? node_path_1.default.resolve(this.rootContext, projectOption)
+            : node_path_1.default.join(this.rootContext, "tsconfig.json");
+        const bopConfig = (0, boperators_1.loadConfig)({
+            searchDir: node_path_1.default.dirname(tsconfigPath),
+        });
+        // Create ts-morph project from tsconfig
+        const tsMorphProject = new boperators_1.Project({
+            tsConfigFilePath: tsconfigPath,
+        });
+        const errorManager = new boperators_1.ErrorManager(bopConfig);
+        const overloadStore = new boperators_1.OverloadStore(tsMorphProject, errorManager, bopConfig.logger);
+        const overloadInjector = new boperators_1.OverloadInjector(tsMorphProject, overloadStore, bopConfig.logger);
+        // Parse all files for overload definitions
+        const allFiles = tsMorphProject.getSourceFiles();
+        for (const file of allFiles) {
+            overloadStore.addOverloadsFromFile(file);
+        }
+        errorManager.throwIfErrorsElseLogWarnings();
+        // Only transform this file
+        const sourceFile = tsMorphProject.getSourceFile(resourcePath);
+        if (!sourceFile) {
+            return callback(null, source, null);
+        }
+        const originalText = sourceFile.getFullText();
+        const result = overloadInjector.overloadFile(sourceFile);
+        if (result.text === originalText) {
+            return callback(null, source, null);
+        }
+        const sourceMap = (0, boperators_1.toV3SourceMap)(result.edits, originalText, result.text, resourcePath);
+        return callback(null, result.text, sourceMap);
+    }
+    catch (err) {
+        callback(err);
+    }
+};
+exports.default = loader;

package/dist/toRawSourceMap.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toRawSourceMap = toRawSourceMap;
+/**
+ * Convert boperators EditRecord[] into a V3 RawSourceMap.
+ *
+ * Generates line-level mappings: unchanged regions map 1:1, and edit
+ * boundaries map back to the start of the original edit region.
+ */
+function toRawSourceMap(edits, originalText, transformedText, fileName) {
+    const origLineStarts = buildLineStarts(originalText);
+    const transLineStarts = buildLineStarts(transformedText);
+    // Each segment is [transCol, sourceIndex, origLine, origCol]
+    // We only have one source (index 0), so sourceIndex is always 0.
+    const mappingLines = [];
+    const transLineCount = transLineStarts.length;
+    // Initialise empty lines
+    for (let i = 0; i < transLineCount; i++) {
+        mappingLines.push([]);
+    }
+    // For positions outside any edit, the mapping is identity + accumulated delta.
+    // For positions inside an edit's transformed region, map to the original edit start.
+    // We generate one segment per transformed line start.
+    for (let transLine = 0; transLine < transLineCount; transLine++) {
+        const transOffset = transLineStarts[transLine];
+        const origOffset = transformedToOriginal(edits, transOffset);
+        const { line: origLine, col: origCol } = offsetToLineCol(origLineStarts, origOffset);
+        mappingLines[transLine].push([0, 0, origLine, origCol]);
+    }
+    return {
+        version: 3,
+        file: fileName,
+        sources: [fileName],
+        sourcesContent: [originalText],
+        names: [],
+        mappings: encodeMappings(mappingLines),
+    };
+}
+/** Map a transformed-source offset back to the original source. */
+function transformedToOriginal(edits, pos) {
+    let delta = 0;
+    for (const edit of edits) {
+        if (pos < edit.transStart) {
+            break;
+        }
+        if (pos < edit.transEnd) {
+            return edit.origStart;
+        }
+        delta = edit.origEnd - edit.transEnd;
+    }
+    return pos + delta;
+}
+/** Build an array where index i is the character offset of line i. */
+function buildLineStarts(text) {
+    const starts = [0];
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] === "\n") {
+            starts.push(i + 1);
+        }
+    }
+    return starts;
+}
+/** Convert a character offset to 0-based line and column. */
+function offsetToLineCol(lineStarts, offset) {
+    // Binary search for the line containing this offset
+    let lo = 0;
+    let hi = lineStarts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >>> 1;
+        if (lineStarts[mid] <= offset) {
+            lo = mid;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return { line: lo, col: offset - lineStarts[lo] };
+}
+/** Encode segment arrays into a VLQ mappings string. */
+function encodeMappings(lines) {
+    let prevTransCol = 0;
+    let prevOrigLine = 0;
+    let prevOrigCol = 0;
+    let prevSourceIdx = 0;
+    const lineStrings = [];
+    for (const segments of lines) {
+        prevTransCol = 0; // reset column tracking per line
+        const segStrings = [];
+        for (const seg of segments) {
+            const [transCol, sourceIdx, origLine, origCol] = seg;
+            segStrings.push(encodeVLQ(transCol - prevTransCol) +
+                encodeVLQ(sourceIdx - prevSourceIdx) +
+                encodeVLQ(origLine - prevOrigLine) +
+                encodeVLQ(origCol - prevOrigCol));
+            prevTransCol = transCol;
+            prevSourceIdx = sourceIdx;
+            prevOrigLine = origLine;
+            prevOrigCol = origCol;
+        }
+        lineStrings.push(segStrings.join(","));
+    }
+    return lineStrings.join(";");
+}
+const VLQ_BASE = 32;
+const VLQ_BASE_MASK = VLQ_BASE - 1;
+const VLQ_CONTINUATION = VLQ_BASE;
+const BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/** Encode a single integer as a VLQ base64 string. */
+function encodeVLQ(value) {
+    let vlq = value < 0 ? (-value << 1) | 1 : value << 1;
+    let result = "";
+    do {
+        let digit = vlq & VLQ_BASE_MASK;
+        vlq >>>= 5;
+        if (vlq > 0) {
+            digit |= VLQ_CONTINUATION;
+        }
+        result += BASE64_CHARS[digit];
+    } while (vlq > 0);
+    return result;
+}

package/license.txt

@@ -0,0 +1,8 @@
+Copyright 2025 Dief Bell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@boperators/webpack-loader",
+	"version": "0.1.4",
+	"license": "MIT",
+	"description": "webpack loader for boperators",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/DiefBell/boperators",
+		"directory": "plugins/webpack"
+	},
+	"bugs": {
+		"url": "https://github.com/DiefBell/boperators/issues"
+	},
+	"homepage": "https://github.com/DiefBell/boperators/tree/main/plugins/webpack",
+	"type": "commonjs",
+	"main": "./dist/index.js",
+	"keywords": [
+		"boperators",
+		"typescript",
+		"operator",
+		"overload",
+		"operator-overloading",
+		"webpack",
+		"transform"
+	],
+	"scripts": {
+		"build": "tsc",
+		"watch": "tsc -w",
+		"test": "bun test",
+		"test:watch": "bun test --watch",
+		"prepublish": "bun run build"
+	},
+	"files": [
+		"package.json",
+		"README.md",
+		"license.txt",
+		"dist"
+	],
+	"peerDependencies": {
+		"boperators": "0.1.4",
+		"typescript": ">=5.0.0 <5.10.0"
+	},
+	"devDependencies": {
+		"@types/node": "^25.2.3",
+		"@types/webpack": "^5.28.5",
+		"boperators": "file:../../package",
+		"webpack": "^5.105.2"
+	}
+}