runtime-type-inspector 1.0.0 → 2.0.1

package/rollup.config.mjs

@@ -0,0 +1,183 @@
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+// 1st party Rollup plugins
+import { createFilter } from '@rollup/pluginutils';
+import { babel } from '@rollup/plugin-babel';
+import { nodeResolve } from '@rollup/plugin-node-resolve';
+import terser from '@rollup/plugin-terser';
+// 3rd party Rollup plugins
+import dts from 'rollup-plugin-dts';
+import { visualizer } from 'rollup-plugin-visualizer';
+import json from '@rollup/plugin-json';
+//import { addTypeChecks } from "./src-transpiler/typeInserter.mjs";
+//const { addTypeChecks } = await import("runtime-type-inspector/src-transpiler/typeInserter.mjs");
+import commonjs from '@rollup/plugin-commonjs';
+import { runtimeTypeInspector } from './plugin-rollup/index.mjs';
+/** @typedef {import('rollup').RollupOptions} RollupOptions */
+/** @typedef {import('rollup').Plugin} Plugin */
+/** @typedef {import('rollup').OutputOptions} OutputOptions */
+/** @typedef {import('@rollup/plugin-babel').RollupBabelInputPluginOptions} RollupBabelInputPluginOptions */
+/**
+ * The ES5 options for babel(...) plugin.
+ *
+ * @param {string} buildType - Only 'debug' requires special handling so far.
+ * @returns {RollupBabelInputPluginOptions} The babel options.
+ */
+const es5Options = buildType => ({
+  babelHelpers: 'bundled',
+  babelrc: false,
+  comments: buildType === 'debug' || buildType === 'rti',
+  compact: false,
+  minified: false,
+  presets: [
+    [
+      '@babel/preset-env', {
+        loose: !true,
+        modules: false,
+        targets: {
+          ie: '11'
+        }
+      }
+    ]
+  ]
+});
+/**
+ * The ES6 options for babel(...) plugin.
+ *
+ * @param {string} buildType - Only 'debug' requires special handling so far.
+ * @returns {RollupBabelInputPluginOptions} The babel options.
+ */
+const moduleOptions = buildType => ({
+  babelHelpers: 'bundled',
+  babelrc: false,
+  comments: buildType === 'debug',
+  compact: false,
+  minified: false,
+  presets: [
+    [
+      '@babel/preset-env', {
+        bugfixes: true,
+        loose: true,
+        modules: false,
+        targets: {
+          esmodules: true
+        }
+      }
+    ]
+  ]
+});
+/**
+ * Build a target that rollup is supposed to build.
+ *
+ * @param {'debug'|'release'|'profiler'|'min'} buildType - The build type.
+ * @param {'es5'|'es6'} moduleFormat - The module format.
+ * @returns {RollupOptions} One rollup target.
+ */
+function buildTarget(buildType, moduleFormat) {
+  const banner = {
+    debug: ' (DEBUG)',
+    release: ' (RELEASE)',
+    profiler: ' (PROFILE)',
+    min: ' (RELEASE)'
+  };
+  const outputPlugins = {
+    release: [],
+    min: [
+      terser()
+    ]
+  };
+  if (process.env.treemap) {
+    outputPlugins.min.push(visualizer({
+      filename: 'treemap.html',
+      brotliSize: true,
+      gzipSize: true
+    }));
+  }
+  if (process.env.treenet) {
+    outputPlugins.min.push(visualizer({
+      filename: 'treenet.html',
+      template: 'network'
+    }));
+  }
+  if (process.env.treesun) {
+    outputPlugins.min.push(visualizer({
+      filename: 'treesun.html',
+      template: 'sunburst'
+    }));
+  }
+  const name = 'rti-transpiler';
+  const outputFile = {
+    release:  `build/${name}`,
+    debug:    `build/${name}.dbg`,
+    profiler: `build/${name}.prf`,
+    min:      `build/${name}.min`,
+    rti:      `build/${name}.rti`,
+  };
+  const outputExtension = {
+    es5: '.js',
+    es6: '.mjs'
+  };
+  /** @type {OutputOptions} */
+  const outputOptions = {
+    plugins: outputPlugins[buildType || outputPlugins.release],
+    format: 'es',
+    indent: '\t',
+    sourcemap: false,
+    name: 'pc',
+    preserveModules: false,
+    file: `${outputFile[buildType]}${outputExtension[moduleFormat]}`
+  };
+  const babelOptions = {
+    es5: es5Options(buildType),
+    es6: moduleOptions(buildType)
+  };
+  const rootFile = 'src-transpiler/index.mjs';
+  console.log("buildType", buildType);
+  return {
+    input: rootFile,
+    output: outputOptions,
+    plugins: [
+      //runtimeTypeInspector(buildType === 'debug'),
+      babel(babelOptions[moduleFormat]),
+      //nodeResolve({
+      //  browser: true
+      //}),
+      //commonjs(),
+      //json(),
+    ],
+    ///external: ['fs', 'path', 'url', 'sharp', 'onnxruntime-node', 'onnxruntime-web', 'stream/web'],
+  };
+}
+/** @type {RollupOptions} */
+const target_types = {
+  input: 'types/index.d.ts',
+  output: [{
+    file: 'build/runtime-type-inspector.d.ts',
+    footer: 'export as namespace pc;',
+    format: 'es'
+  }],
+  plugins: [
+    dts()
+  ]
+};
+export default (args) => {
+  /** @type {RollupOptions[]} */
+  let targets = [];
+  const envTarget = process.env.target ? process.env.target.toLowerCase() : null;
+  if (envTarget === 'types') {
+    targets.push(target_types);
+  } else if (envTarget === 'extras') {
+    targets = targets.concat(target_extras);
+  } else {
+    ['release', 'debug', 'profiler', 'min', 'rti'].forEach((t) => {
+      ['es5', 'es6'].forEach((m) => {
+        console.log("envTarget", envTarget);
+        if (envTarget === null || envTarget === t || envTarget === m || envTarget === `${t}_${m}`) {
+          targets.push(buildTarget(t, m));
+        }
+      });
+    });
+  }
+  return targets;
+};

package/src-runtime/assertType.mjs

@@ -0,0 +1,54 @@
+import {typecheckOptions    } from "./typecheckOptions.mjs";
+import {typecheckWarnedTable} from "./typecheckTable.mjs";
+import {typecheckWarn       } from "./typecheckWarn.mjs";
+import {validateType        } from "./validateType.mjs";
+/**
+ * @param {*} value - The actual value that we need to validate.
+ * @param {*} expect - The supposed type information of said value.
+ * @param {string} loc - String like `BoundingBox#compute`
+ * @param {string} name - Name of the argument
+ * @param {boolean} critical - Only `false` for unions.
+ * @returns {boolean} - Boolean indicating if a type is correct.
+ */
+export function assertType(value, expect, loc, name, critical = true) {
+  if (!expect) {
+    typecheckWarn("assertType> 'expect' always should be set");
+    return false;
+  }
+  const ret = validateType(value, expect, loc, name, critical);
+  if (!ret && critical) {
+    typecheckOptions.count++;
+    let expectStr = ', expected: ' + JSON.stringify(expect);
+    if (expectStr.length >= 40) {
+      expectStr = ', expected: ';
+    }
+    expectStr = '';
+    const msg = `${loc}> type of '${name}' is invalid${expectStr}`;
+    typecheckWarn(msg, { expect, value });
+    const warnObj = typecheckOptions.warned[msg];
+    if (!warnObj.tr) {
+      const tr = document.createElement('tr');
+      const dbg = document.createElement('td');
+      const dbgInput = document.createElement("input");
+      dbgInput.type = "checkbox";
+      dbgInput.onchange = () => {
+        warnObj.dbg = dbgInput.checked;
+      }
+      const count = document.createElement('td');
+      const desc = document.createElement('td');
+      desc.innerText = msg;
+      tr.append(dbg, count, desc);
+      dbg.append(dbgInput);
+      typecheckWarnedTable.append(tr);
+      warnObj.tr = tr;
+    }
+    const {tr, dbg} = warnObj;
+    if (dbg) {
+      debugger;
+      warnObj.dbg = false; // trigger only once to quickly get app running again
+      tr.children[0].children[0].checked = false; // update ui state
+    }
+    tr.children[1].textContent = warnObj.hits;
+  }
+  return ret;
+}

package/src-runtime/createDiv.mjs

@@ -0,0 +1,69 @@
+import {typecheckOptions    } from "./typecheckOptions.mjs";
+import {typecheckWarnedTable} from "./typecheckTable.mjs";
+/**
+ * @param {HTMLDivElement} div - The <div>.
+ */
+function niceDiv(div) {
+  div.style.border  = "1px solid #C1C1C1";
+  div.style.margin = "10px";
+  div.style.padding = "10px";
+  div.style.textAlign = "left";
+  div.style.lineHeight = "25px";
+  div.style.backgroundColor = "#F3F3F3";
+  div.style.borderRadius = "4px";
+}
+/**
+ * @todo
+ * Show number of validations too? Might be too noisy.
+ * @returns {HTMLDivElement}
+ */
+function createDiv() {
+  const div = document.createElement("div");
+  div.style.position = "absolute";
+  div.style.bottom = "0px";
+  div.style.right = "0px";
+  div.style.zIndex = "1";
+  niceDiv(div);
+  const spanErrors = document.createElement("span");
+  const span = document.createElement("span");
+  span.innerText = " Spam type reports:";
+  const input = document.createElement("input");
+  input.type = "checkbox";
+  const spamTypeReports = localStorage.getItem('rti-spam-type-reports');
+  input.checked = true;
+  if (spamTypeReports !== null) {
+    input.checked = spamTypeReports === 'spam' ? true : false;
+  }
+  const onchange = () => {
+    localStorage.setItem('rti-spam-type-reports', input.checked ? 'spam' : 'once');
+    if (input.checked) {
+      typecheckOptions.mode = "spam";
+    } else {
+      typecheckOptions.mode = "once";
+    }
+  };
+  input.onchange = onchange;
+  onchange(); // update mode from localStorage
+  input.checked = true;
+  const buttonHide = document.createElement("button");
+  buttonHide.textContent = 'Hide';
+  buttonHide.onclick = () => {
+    div.style.display = 'none';
+  };
+  div.append(spanErrors, span, input, buttonHide, typecheckWarnedTable);
+  div.style.maxHeight = '200px';
+  div.style.overflow = 'scroll';
+  const finalFunc = () => document.body.append(div);
+  // Add our <div> to <body> when possible
+  if (document.readyState === "complete") {
+    finalFunc();
+  } else {
+    // add when page is loaded
+    document.addEventListener("DOMContentLoaded", finalFunc);
+  }
+  setInterval(() => {
+    spanErrors.innerText = `Type validation errors: ${typecheckOptions.count}`;
+  }, 100);
+  return div;
+}
+export {createDiv};

package/src-runtime/index.mjs

@@ -0,0 +1,21 @@
+export * from './assertType.mjs';
+export * from './createDiv.mjs';
+export * from './makeJSDoc.mjs';
+export * from './registerClass.mjs';
+export * from './registerTypedef.mjs';
+export * from './typecheckDiv.mjs';
+export * from './typecheckEvery.mjs';
+export * from './typecheckOptions.mjs';
+export * from './typecheckTable.mjs';
+export * from './typecheckWarn.mjs';
+export * from './validateArray.mjs';
+export * from './validateDivision.mjs';
+export * from './validateMap.mjs';
+export * from './validateNumber.mjs';
+export * from './validateObject.mjs';
+export * from './validateRecord.mjs';
+export * from './validateTuple.mjs';
+export * from './validateType.mjs';
+export * from './validateTypedef.mjs';
+export * from './validateUnion.mjs';
+export * from './youCanAddABreakpointHere.mjs';

package/src-runtime/makeJSDoc.mjs

@@ -0,0 +1,40 @@
+/**
+ * @type {Record<string, string>}
+ */
+const jsdocCache = {};
+/**
+ * @todo
+ * update jsdoc cache if it changes or keep all possible version to generate maybe multiple function signatures
+ * @example
+ * pc.makeJSDoc('VignetteEffect#render', ["inputTarget", "outputTarget", "rect"], [inputTarget, outputTarget, rect])
+ * @param {string} loc - The location.
+ * @param {string[]} names - The names
+ * @param {any[]} values - The values
+ */
+function makeJSDoc(loc, names, values) {
+  const n = names.length;
+  let jsdoc = '    /**\n';
+  for (var i = 0; i < n; i++) {
+    const name = names[i];
+    const value = values[i];
+    /** @type {string} */
+    let type = typeof value;
+    if (value === null) {
+      type = 'null';
+    } else if (value instanceof Object) {
+      type = value.constructor.name;
+    }
+    if (type !== 'string' && pc[type]) {
+      type = 'pc.' + type;
+    }
+    //debugger;
+    jsdoc += `     * @param {${type}} ${name} - todo/jsdoc\n`
+  }
+  jsdoc += '     */';
+  if (!jsdocCache[loc]) {
+    jsdocCache[loc] = jsdoc;
+    console.log(loc);
+    console.log(jsdoc);
+  }
+}
+export {jsdocCache, makeJSDoc};

package/src-runtime/registerClass.mjs

@@ -0,0 +1,11 @@
+/**
+ * @type {Record<string, Function>}
+ */
+const classes = {};
+/**
+ * @param {Function} theClass - The class.
+ */
+function registerClass(theClass) {
+  classes[theClass.name] = theClass;
+}
+export {classes, registerClass};

package/src-runtime/registerTypedef.mjs

@@ -0,0 +1,12 @@
+/**
+ * @type {Record<string, object>}
+ */
+const typedefs = {};
+/**
+ * @param {string} name - Name of typedef.
+ * @param {Record<string, object>} typedef - The parsed typedef from source.
+ */
+function registerTypedef(name, typedef) {
+  typedefs[name] = typedef;
+}
+export {typedefs, registerTypedef};

package/src-runtime/typecheckDiv.mjs

@@ -0,0 +1,3 @@
+import {createDiv} from "./createDiv.mjs";
+const typecheckDiv = createDiv();
+export {typecheckDiv};

package/src-runtime/typecheckEvery.mjs

@@ -0,0 +1,21 @@
+/**
+ * This also works for an empty array, unlike `Array#every`.
+ * @example
+ * const a = [];
+ * a.length = 10;
+ * typecheckEvery(a, (e, i) => { console.log(e); return true; }
+ * @param {*[]} arr - The array to test.
+ * @param {Function} fn - The callback function to test each element with.
+ * @returns {boolean} True if every callback call is true aswell.
+ */
+function typecheckEvery(arr, fn) {
+  const n = arr.length;
+  for (let i = 0; i < n; i++) {
+    const ret = fn(arr[i], i, arr);
+    if (!ret) {
+      return false;
+    }
+  }
+  return true;
+}
+export {typecheckEvery};

package/src-runtime/typecheckOptions.mjs

@@ -0,0 +1,60 @@
+function typecheckReport() {
+  console.table(typecheckOptions.warned);
+}
+/**
+ * @param {Object<string, any>} obj - The object to clear.
+ */
+function clearObject(obj) {
+  Object.keys(obj).forEach(_ => delete obj[_]);
+}
+function typecheckReset() {
+  clearObject(typecheckOptions.warned);
+}
+const typecheckOptions = {
+  /**
+   * @type {'spam'|'once'} - In spam-mode every message is printed. In once-mode a cache is
+   * looked up to check if it was printed already. Spam can be too noisy if there are too
+   * many type errors, so the best way to keep it quiet is to fix the noisiest type issues first.
+   * Spam-mode basically retains the order, which mentally helps to figure out the actual issues.
+   */
+  mode: 'spam',
+  /**
+   * @type {Record<string, {hits: number, tr: HTMLTableRowElement, dbg: boolean}>}
+   */
+  warned: {},
+  logSuperfluousProperty: false,
+  /**
+   * @todo integrate PC/Transformers Examples browser + custom config for each project
+   */
+  customTypes: {
+    AnimSetter(value) {
+      //console.log("@todo Is AnimSetter?", value);
+      return true;
+    },
+    AnimBinder(value) {
+      //console.log("@todo Is AnimBinder?", value);
+      return true;
+    },
+    AnimCurvePath(value) {
+      //console.log("@todo Is AnimCurvePath?", value);
+      return true;
+    },
+    ComponentData(value) {
+      //console.log("@todo Is ComponentData?", value);
+      return true;
+    },
+    Renderer(value) {
+      // E.g. instance of `ForwardRenderer`
+      //debugger;
+      return value?.constructor?.name?.endsWith("Renderer");
+    },
+    IArguments(value) {
+      //console.log("@todo Is IArguments?", value);
+      return true;
+    },
+    // @todo validate textures having width != 0 and height != 0
+    // @todo validate integers
+  },
+  count: 0,
+};
+export {typecheckReport, clearObject, typecheckReset, typecheckOptions};

package/src-runtime/typecheckTable.mjs

@@ -0,0 +1,14 @@
+const typecheckWarnedTable = document.createElement('table');
+const tr = document.createElement('tr');
+const th_0 = document.createElement('th');
+const th_1 = document.createElement('th');
+const th_2 = document.createElement('th');
+th_0.innerText = 'dbg;';
+th_1.innerText = 'Hits';
+th_2.innerText = 'Message';
+tr.append(th_0, th_1, th_2);
+typecheckWarnedTable.append(tr);
+//typecheckWarnedTable.style.maxHeight = '200px';
+//typecheckWarnedTable.style.overflow = 'scroll';
+//typecheckWarnedTable.style.textWrap = 'nowrap';
+export {typecheckWarnedTable};

package/src-runtime/typecheckWarn.mjs

@@ -0,0 +1,23 @@
+import {typecheckOptions} from "./typecheckOptions.mjs";
+/**
+ * @param {string} msg - The main message.
+ * @param  {...any} extra - Extra strings or objects etc.
+ */
+function typecheckWarn(msg, ...extra) {
+  const { mode, warned } = typecheckOptions;
+  warned[msg] = warned[msg] || { hits: 0 };
+  warned[msg].hits++;
+  switch (mode) {
+    case 'spam':
+      console.error(msg, ...extra);
+      break;
+    case 'once':
+      if (warned[msg].hits === 1) {
+        console.error(msg, ...extra);
+      }
+      break;
+    default:
+      console.error("typecheckWarn> unsupported mode:", mode);
+  }
+}
+export {typecheckWarn};

package/src-runtime/validateArray.mjs

@@ -0,0 +1,26 @@
+import {assertType    } from "./assertType.mjs";
+import {typecheckEvery} from "./typecheckEvery.mjs";
+/**
+ * @param {*} value 
+ * @param {*} expect 
+ * @param {*} loc 
+ * @param {*} name 
+ * @param {*} critical 
+ * @returns {boolean}
+ */
+function validateArray(value, expect, loc, name, critical) {
+  if (value && value instanceof Array) {
+    const { elementType } = expect;
+    // some that not validate -> type error
+    return typecheckEvery(value, (_, i) => assertType(
+      _,
+      elementType,
+      loc,
+      `${name}[${i}]`,
+      critical
+    ));
+  }
+  // if it's not even an array -> type error
+  return false;
+}
+export {validateArray};

package/src-runtime/validateDivision.mjs

@@ -0,0 +1,31 @@
+import {typecheckWarn} from "./typecheckWarn.mjs";
+/**
+ * @param {number} lhs - The left hand side.
+ * @param {number} rhs - The right hand side.
+ * @example
+ * validateDivision( 1 ,  2 ); // Outputs: 0.5
+ * validateDivision( 1 , "2"); // Warns: validateDivision> incompatible type pair
+ * validateDivision(10n,  2n); // Outputs: 5n
+ * @returns {number}
+ */
+function validateDivision(lhs, rhs) {
+  const ret = lhs / rhs;
+  const twoNumbers = typeof lhs === 'number' && typeof rhs === 'number';
+  const twoBigInts = typeof lhs === 'bigint' && typeof rhs === 'bigint';
+  const valid = twoNumbers || twoBigInts;
+  if (!valid) {
+    typecheckWarn(`validateDivision> incompatible type pair`, { lhs, rhs, twoNumbers, twoBigInts });
+  }
+  // If we got two bigint's, we are done, as isNaN and isFinite is only for "normal" numbers.
+  if (twoBigInts) {
+    return ret;
+  }
+  if (isNaN(ret)) {
+    typecheckWarn(`validateDivision> NaN`, { lhs, rhs });
+  }
+  if (!isFinite(ret)) {
+    typecheckWarn(`validateDivision> +-Infinity`, { lhs, rhs });
+  }
+  return ret;
+}
+export {validateDivision};

package/src-runtime/validateMap.mjs

@@ -0,0 +1,36 @@
+import {assertType   } from "./assertType.mjs";
+import {typecheckWarn} from "./typecheckWarn.mjs";
+/**
+ * @param {*} value 
+ * @param {*} expect 
+ * @param {*} loc 
+ * @param {*} name 
+ * @param {*} critical 
+ * @returns {boolean}
+ */
+function validateMap(value, expect, loc, name, critical) {
+  const { key, val } = expect;
+  if (key !== 'string') {
+    typecheckWarn(`${loc}> validateType> map> unhandled key '${key}'`);
+    return false;
+  }
+  if (val !== 'any') {
+    typecheckWarn(`${loc}> validateType> map> expected any, not '${value}'`);
+    return false;
+  }
+  let ret = true;
+  for (const [k, v] of value) {
+    const good = assertType(
+      v,
+      val,
+      loc,
+      `${name}.get('${key}')`,
+      critical
+    );
+    if (!good) {
+      ret = false;
+    }
+  }
+  return ret;
+}
+export {validateMap};

package/src-runtime/validateNumber.mjs

@@ -0,0 +1,29 @@
+import {typecheckWarn} from "./typecheckWarn.mjs";
+/**
+ * Validates if a given property is neither NaN nor +-Infinity
+ * @param {Object<string|number, number>} obj - The object to test a property of.
+ * @param {string|number} prop - Name or index or property.
+ * @returns {boolean} True if property is a "proper" number (neither Nan nor Infinity)
+ */
+function validateNumber(obj, prop) {
+  const val = obj[prop];
+  const type = typeof obj;
+  if (val === null) {
+    typecheckWarn(`${type}#${prop} null`, { obj });
+    return false;
+  }
+  if (val === undefined) {
+    typecheckWarn(`${type}#${prop} undefined`, { obj });
+    return false;
+  }
+  if (isNaN(val)) {
+    typecheckWarn(`${type}#${prop} NaN`, { obj });
+    return false;
+  }
+  if (!isFinite(val)) {
+    typecheckWarn(`${type}#${prop} +-Infinity`, { obj });
+    return false;
+  }
+  return true;
+}
+export {validateNumber};