@boperators/plugin-esbuild 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +72 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# @boperators/plugin-esbuild
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
ESBuild plugin for [boperators](https://www.npmjs.com/package/boperators) that transforms operator overloads during the ESBuild bundling step, replacing operator expressions with function calls before ESBuild compiles TypeScript.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install -D boperators @boperators/plugin-esbuild
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Configuration
|
|
14
|
+
|
|
15
|
+
ESBuild plugins can only be used via the **JavaScript API** — the ESBuild CLI does not support plugins. Create a build script (e.g. `build.cjs`) and run it with Node:
|
|
16
|
+
|
|
17
|
+
```javascript
|
|
18
|
+
const { build } = require("esbuild");
|
|
19
|
+
const { boperators } = require("@boperators/plugin-esbuild");
|
|
20
|
+
|
|
21
|
+
build({
|
|
22
|
+
entryPoints: ["src/index.ts"],
|
|
23
|
+
outfile: "dist/bundle.js",
|
|
24
|
+
bundle: true,
|
|
25
|
+
platform: "node",
|
|
26
|
+
absWorkingDir: __dirname,
|
|
27
|
+
plugins: [boperators()],
|
|
28
|
+
}).catch(process.exit);
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
> **Important:** Set `absWorkingDir` to your project root (typically `__dirname`). The plugin uses this to resolve `tsconfig.json`.
|
|
32
|
+
|
|
33
|
+
### Options
|
|
34
|
+
|
|
35
|
+
| Option | Type | Default | Description |
|
|
36
|
+
|--------|------|---------|-------------|
|
|
37
|
+
| `project` | `string` | `"tsconfig.json"` | Path to `tsconfig.json`, relative to `absWorkingDir` |
|
|
38
|
+
| `include` | `RegExp` | `/\.tsx?$/` | File filter — only matching files are transformed |
|
|
39
|
+
|
|
40
|
+
Options are passed to the plugin factory:
|
|
41
|
+
|
|
42
|
+
```javascript
|
|
43
|
+
plugins: [
|
|
44
|
+
boperators({
|
|
45
|
+
project: "./tsconfig.build.json",
|
|
46
|
+
}),
|
|
47
|
+
]
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## How It Works
|
|
51
|
+
|
|
52
|
+
The plugin initialises once inside `setup(build)`, then transforms files on demand:
|
|
53
|
+
|
|
54
|
+
1. **Setup** — creates a [ts-morph](https://ts-morph.com) Project from your tsconfig and scans all source files for operator overload definitions
|
|
55
|
+
2. **`build.onLoad`** — for each `.ts`/`.tsx` file that matches the filter, replaces operator expressions (e.g. `v1 + v2` becomes `Vector3["+"](v1, v2)`) and returns the transformed source to ESBuild with the correct `ts`/`tsx` loader
|
|
56
|
+
|
|
57
|
+
If a file contains no overloaded operators it is returned as-is with no overhead.
|
|
58
|
+
|
|
59
|
+
## Comparison with Other Approaches
|
|
60
|
+
|
|
61
|
+
| Approach | When it runs | Use case |
|
|
62
|
+
|----------|-------------|----------|
|
|
63
|
+
| **`@boperators/cli`** | Before compilation | Batch transform to disk, then compile normally |
|
|
64
|
+
| **`@boperators/plugin-tsc`** | During compilation | Seamless `tsc` integration, no intermediate files |
|
|
65
|
+
| **`@boperators/webpack-loader`** | During bundling | Webpack projects, integrates into existing build pipeline |
|
|
66
|
+
| **`@boperators/plugin-vite`** | During bundling | Vite projects, integrates into Rollup-based pipeline |
|
|
67
|
+
| **`@boperators/plugin-esbuild`** | During bundling | ESBuild projects, fast bundler integration |
|
|
68
|
+
| **`@boperators/plugin-bun`** | At runtime | Bun-only, transforms on module load |
|
|
69
|
+
|
|
70
|
+
## License
|
|
71
|
+
|
|
72
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@boperators/plugin-esbuild",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"description": "esbuild plugin for boperators - transforms operator overloads at build time.",
|
|
6
6
|
"repository": {
|
|
@@ -39,7 +39,7 @@
|
|
|
39
39
|
"dist"
|
|
40
40
|
],
|
|
41
41
|
"peerDependencies": {
|
|
42
|
-
"boperators": "0.
|
|
42
|
+
"boperators": "0.3.0",
|
|
43
43
|
"esbuild": ">=0.17.0",
|
|
44
44
|
"typescript": ">=5.0.0 <5.10.0"
|
|
45
45
|
},
|