runtime-type-inspector 4.0.5 → 5.0.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.
Files changed (2) hide show
  1. package/README.md +63 -0
  2. package/package.json +13 -13
package/README.md CHANGED
@@ -32,6 +32,69 @@ https://www.youtube.com/watch?v=xOp3YWU6M1g
32
32
 
33
33
  [![volumetric video bug fixing](https://img.youtube.com/vi/xOp3YWU6M1g/0.jpg)](https://www.youtube.com/watch?v=xOp3YWU6M1g)
34
34
 
35
+ # Migrate legacy TypeScript to ESM once and for all: `ts2js`
36
+
37
+ `ts2js` migrates legacy TypeScript projects to plain ESM JavaScript in one pass. The types are moved into JSDoc comments, TypeScript is removed from the pipeline entirely, and you then continue with beautiful modern ESM + import maps - no transpilation step, no build step, no `tsconfig` to feed it.
38
+
39
+ ```sh
40
+ npx ts2js src/player.ts > src/player.js
41
+ ```
42
+
43
+ For example, this TypeScript:
44
+
45
+ ```ts
46
+ import type {Vec3} from './math';
47
+ export function add(a: Vec3, b: Vec3): Vec3 {
48
+ return {x: a.x + b.x, ...};
49
+ }
50
+ ```
51
+
52
+ becomes this plain JavaScript:
53
+
54
+ ```js
55
+ /** @import { Vec3 } from './math.js' */
56
+ /**
57
+ * @param {Vec3} a
58
+ * @param {Vec3} b
59
+ * @returns {Vec3}
60
+ */
61
+ export function add(a, b) {
62
+ return {x: a.x + b.x, ...};
63
+ }
64
+ ```
65
+
66
+ Type-only imports are preserved as `@import` comments instead of runtime imports, so no code is emitted for them, and `.ts` extensions in relative import paths are rewritten to `.js`.
67
+
68
+ Being honest about what it is:
69
+
70
+ - It converts the common TypeScript surface: functions with parameters/returns, interfaces and type aliases (`@typedef`), enums, generics (`@template`), classes including parameter properties and `implements` (`@implements`), tuples, unions, rest parameters, default-value inference, TSX, `import x = require('...')` and `import('./x').T` type references. `namespace` blocks become the classic IIFE pattern with `Namespace.member = member` assignments and namespace-qualified types reduced to their local identifier.
71
+ - It is **not** a complete TypeScript compiler. The snapshot suite in `test/ts2js.mjs` documents exactly what is currently covered.
72
+ - `ts2js` preserves types, it does not verify them. Runtime validation via `addTypeChecks` / `@runtime-type-inspector/runtime` is a separate, optional development-time aid - a crutch for live debugging, not something you ship.
73
+ - You can keep authoring in TypeScript for as long as you like and still run `tsc --noEmit` for static checking; `ts2js` simply makes that optional. The migration can happen file by file or full-project, and after it completes the `.ts` sources are just historical artifacts.
74
+
75
+ The point of the one-time migration: a legacy TypeScript library becomes native ESM JavaScript that runs directly in the browser, while the JSDoc types keep all the editor hints and documentation (and keep working for TypeScript consumers, who can still get their types from the existing `.d.ts` files). From then on, no transpilation is ever needed again.
76
+
77
+ The runtime assertions (`transpiler`) are a development-time aid and are not meant to be shipped. For example, static checking is blind to this bug:
78
+
79
+ ```js
80
+ const arr = [10, 20, 1, 2, 3]; // number[]
81
+ arr.length = 10; // still number[] according to static types
82
+ let sum = 0;
83
+ for (let i = 0; i < arr.length; i++) {
84
+ sum += arr[i]; // arr[3] and beyond are now undefined -> NaN
85
+ }
86
+ console.log('sum', sum);
87
+ ```
88
+
89
+ The `ts2js` rewriting phase obviously cannot catch this - it is a runtime-semantics problem, not a syntax or type-level one. That is exactly what the dev loop is for: convert the file, eval it with runtime assertions, and the inspector flags the offending calls as they happen:
90
+
91
+ ```text
92
+ add b "number" undefined The 'b' argument has an invalid type.
93
+ add a "number" NaN The 'a' argument has an invalid type. value is NaN
94
+ ```
95
+
96
+ Static checking trusts both `arr.length = 10` and `arr[i]`; the bug only emerges when real values flow through at runtime. Every loop iteration passing `undefined` or `NaN` into `add` is reported live in the debugging session - the kind of thing static file-based checking is blind to.
97
+
35
98
  # Installation
36
99
 
37
100
  Please take my two Pull Requests for [Transformers.js](https://github.com/xenova/transformers.js/pull/409) (using Webpack) and [PlayCanvas](https://github.com/playcanvas/engine/pull/5817) (using Rollup) as example.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "runtime-type-inspector",
3
- "version": "4.0.5",
3
+ "version": "5.0.0",
4
4
  "description": "Validating JSDoc types at runtime for high-quality types - Trust is good, control is better.",
5
5
  "scripts": {
6
6
  "build": "rollup -c",
@@ -11,7 +11,7 @@
11
11
  "docs": "jsdoc -c jsdoc.json",
12
12
  "lint": "eslint --ext .js,.mjs,.cjs src-transpiler src-runtime",
13
13
  "watch": "rollup -c -w",
14
- "test": "npm run test:update && node test.js && node test_runtime.js",
14
+ "test": "npm run test:update && node test.js && node test_runtime.js && node test/jsdoc-annotation/run.js && node test/ts2js.mjs && node test/wat-converter.mjs",
15
15
  "test:update": "node gen_tests.js > test/typechecking.json"
16
16
  },
17
17
  "repository": {
@@ -35,25 +35,25 @@
35
35
  "@rollup/plugin-strip": "^3.0.2",
36
36
  "@rollup/plugin-terser": "^0.4.3",
37
37
  "@rollup/pluginutils": "^5.0.4",
38
+ "@runtime-type-inspector/parcel-transformer": "^5.0.0",
39
+ "@runtime-type-inspector/plugin-parcel1": "^5.0.0",
40
+ "@runtime-type-inspector/plugin-rollup": "^5.0.0",
41
+ "@runtime-type-inspector/plugin-webpack": "^5.0.0",
42
+ "@runtime-type-inspector/plugin-webpack4": "^5.0.0",
43
+ "@runtime-type-inspector/plugin-webpack5": "^5.0.0",
44
+ "@runtime-type-inspector/repl": "^5.0.0",
45
+ "@runtime-type-inspector/runtime": "^5.0.0",
46
+ "@runtime-type-inspector/transpiler": "^5.0.0",
38
47
  "catharsis": "github:xenova/catharsis",
39
48
  "eslint": "^8.44.0",
40
49
  "eslint-plugin-import": "^2.28.1",
41
50
  "eslint-plugin-jsdoc": "^46.6.0",
42
- "jsdoc": "^4.0.2",
51
+ "jsdoc": "^4.0.5",
43
52
  "jsdoc-tsimport-plugin": "^1.0.5",
44
53
  "rollup": "^3.29.0",
45
54
  "rollup-plugin-dts": "^6.0.1",
46
55
  "rollup-plugin-jscc": "^2.0.0",
47
56
  "rollup-plugin-visualizer": "^5.9.2",
48
- "to-fast-properties": "^4.0.0",
49
- "@runtime-type-inspector/runtime": "^4.0.5",
50
- "@runtime-type-inspector/transpiler": "^4.0.5",
51
- "@runtime-type-inspector/plugin-parcel1": "^4.0.5",
52
- "@runtime-type-inspector/parcel-transformer": "^4.0.5",
53
- "@runtime-type-inspector/plugin-rollup": "^4.0.5",
54
- "@runtime-type-inspector/plugin-webpack": "^4.0.5",
55
- "@runtime-type-inspector/plugin-webpack4": "^4.0.5",
56
- "@runtime-type-inspector/plugin-webpack5": "^4.0.5",
57
- "@runtime-type-inspector/repl": "^4.0.5"
57
+ "to-fast-properties": "^4.0.0"
58
58
  }
59
59
  }