RuntimeTypeInspector.js - your personal type-checking assistant 🕵️🐞🐛

RuntimeTypeInspector.js alongside JSDoc is a powerful tool which works in tandem with Babel.js and TypeScript to generate type-asserting JavaScript files. Assertion code is injected into debug builds to perform runtime type checking of each function and method at runtime - a step which is required beyond pure static typing to help emerge the Incident Management Lifecycle.

The Incident Management Lifecycle is:

• Identify - recognize the type incidents
• Respond - debugging in F12/DevTools
• Resolve - once the issue is cognized it's resolvable
• Learn - clarify the issue for yourself and share with others

RuntimeTypeInspector.js is supporting Identify and Respond of the IML.

Why is this technology critical?

This technology is critical because it provides developers with an organized method to ensure type safety with runtime type issue reports while improving code organization, type safety and documentation - making it easier for other developers to understand the code and enforce good coding standards.

RuntimeTypeInspector.js assists the debugging process, since it has a clear definition of what each function expects while issuing warnings, which can act as breakpoints in your source code (as shown in the example debugging session in my showcase video). Finally, good JSDoc can make the entire code base more maintainable, since it's easier for developers to find the specific parts of the code they need to change quickly and easily.

Watch our Example Usage Videos!

If you want to see how our product works, take a look at the videos we have prepared. They show you exactly how to use our product with ease.

Presentation hunting down a NaN bug in the PlayCanvas engine:

https://www.youtube.com/watch?v=o5ipQe2rVKQ

Another demonstration fixing NaN bugs in the PlayCanvas Volumetric Video project:

https://www.youtube.com/watch?v=xOp3YWU6M1g

Migrate legacy TypeScript to ESM once and for all: ts2js

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.

npx ts2js src/player.ts > src/player.js

For example, this TypeScript:

import type {Vec3} from './math';
export function add(a: Vec3, b: Vec3): Vec3 {
  return {x: a.x + b.x, ...};
}

becomes this plain JavaScript:

/** @import { Vec3 } from './math.js' */
/**
 * @param {Vec3} a
 * @param {Vec3} b
 * @returns {Vec3}
 */
export function add(a, b) {
  return {x: a.x + b.x, ...};
}

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.

Being honest about what it is:

• 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.
• It is not a complete TypeScript compiler. The snapshot suite in test/ts2js.mjs documents exactly what is currently covered.
• 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.
• 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.

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.

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:

const arr = [10, 20, 1, 2, 3]; // number[]
arr.length = 10;                // still number[] according to static types
let sum = 0;
for (let i = 0; i < arr.length; i++) {
  sum += arr[i];                // arr[3] and beyond are now undefined -> NaN
}
console.log('sum', sum);

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:

add  b  "number"  undefined   The 'b' argument has an invalid type.
add  a  "number"  NaN         The 'a' argument has an invalid type. value is NaN

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.

Installation

Please take my two Pull Requests for Transformers.js (using Webpack) and PlayCanvas (using Rollup) as example.

npm install @runtime-type-inspector/transpiler

Live demo: https://runtimetypeinspector.org/

Thank you for reading and testing! You can also open DevTools and run:

console.log(rtiTranspiler)

Available NPM packages

• https://www.npmjs.com/package/@runtime-type-inspector/runtime
• https://www.npmjs.com/package/@runtime-type-inspector/transpiler
• https://www.npmjs.com/package/@runtime-type-inspector/plugin-parcel1
• https://www.npmjs.com/package/@runtime-type-inspector/parcel-transformer (Parcel v2)
• https://www.npmjs.com/package/@runtime-type-inspector/plugin-rollup
• https://www.npmjs.com/package/@runtime-type-inspector/plugin-webpack (version independent)
• https://www.npmjs.com/package/@runtime-type-inspector/plugin-webpack4
• https://www.npmjs.com/package/@runtime-type-inspector/plugin-webpack5

Acknowledgements

We are incredibly grateful for the support and contribution of our funders, Sovereign Tech Fund. We would like to thank them for their support and contribution towards making this project possible. Their partnership and generous funding have been instrumental in the success and realization of RuntimeTypeInspector.js.

Open source, a treasure trove for all to embrace,

But its potential is limited, without financial grace.

Let's urge our governments, to invest in its light,

For a resilient digital infrastructure, shining bright.