Boilerplate for using TypeScript as a type checker on JavaScript files containing JSDoc annotations.

jsconfig.json

{
  "compilerOptions": {
    "noImplicitAny": true,
    "allowJS": true,
    "checkJS": true,
    "noEmit": true
  },
  "files": [
    "jsdoc-example.js"
  ]
}

jsdoc-example.js

// 11 May 2020
// My TypeScript Playground settings
// https://www.typescriptlang.org/play/index.html?noEmitHelpers=true&ssl=1&ssc=1&pln=32&pc=1&useJavaScript=true#code/PQKhFgCgAIWgBADgQwE7ILbQN4DsCuGARgKaoC+0yUsCK6WehpF0RNc8qJALvqrgDOOAsTLkOwKADN8uAMY8AlgHtc0AB4AKZABo2AShw1op7nwFVoAajYBuKBMhRgwaIIAWK-ABsAJtAogoJQ2gCM+gBMBg7OkK7uXr4B0shKPqFaEdAA5JE5BlAuYBx0aJg42FQAXNCiLPpEtfVk0OROtFy8-EIizOKSMnKKquoAnlpVemxtRtgmZt2WyDb2jkXxbp7e-oHIwVATU7XZTdCRs7EuW0m7qemHWVExGwnbydD3GZBHNdBhlygQA
// Online the TS playground will generate from JavaScript to TypeScript, but will not show errors in the JavaScript.
// Don't know if it's worth it. Really, I believe TS is BS.

/**
 * Function with 2 number parameters.
 *
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function x(a, b) {
    return a + b;
}

// should pass
x(1, 2);

// should fail
x(1, '2');

// should fail
x({ a: 1, b: 2 });

/**
 * Function with 2 destructured number parameters.
 *
 * @param {{ a: number, b: number }}
 * @returns {number}
 */
function y({ a, b }) {
    return a + b;
}

// should pass
y({ a: 1, b: 2 });

// should fail
y(1, 2);

// should fail
y({ a: 1 });

//

/**
 * 29 August 2020
 * It works on TS playground:
 * https://www.typescriptlang.org/play?strictNullChecks=true&useJavaScript=true#code/PQKhCgAIUgxBXAdgYwC4EsD2jIHd2oAWkATJACYCmAzqgE7xrx2XmSYBGAVpWpAA4BDOoIC2lVJTrUANFBiDEbRe34ZsggDaRaddIgDm7OpETxRHKQLqZ+U1AE92OIpR29sbTjz5CR4yToAOnlIUIABPzFIAG9vXlQAX0hhIwBaSBYAR3h0FnIIqNFY+LRk1KDyQVRBSAzs3PzC4Wi47gTyugMg5EJFAxo6zMocvNZQ5v9Y3X0jAB9Tc0s6ZIBtCt7+mkr0an5NQQcANS14SgBdIdt1RC1wCJZUZkRqEvay+WBwADMkNCwcOIupQABQxCjVQQySCbQyDRIASliUEgqOAwDgeVo0MoiG+mDoyDciicjjsOkE3wkTgaY3EiFQ1BRqPQ30gIIA5ORdvtDidNGcOZB9DC+nDqEiYszUTLYQNqDs9gdjqc3ABeSAAZXosxBcu23KVfNVCIA3NLEvcZZB0ZAALJSAairavbksNCaJz6VCYCE1ELWx7PSAAeXeqCCgmo1HQBkQIKqNWh+ol5st4Ft1EImHgmjYQmj4CBAzBfsEAC5Yolk2L5ZXwYbeSqBZRKwAiABuqrbkGSiPNxdBDch9erzvF9YoPOV-LOlYAjCQAMwAFl7vbN90z2dzbG+gnQmiLjqHZdHNZdk8bM9VlfoZ3X-fAQA
 *
 * Example code from the calcluator codepen:
 * https://codepen.io/dfkaye/pen/QWjdEZe
 *
 * Function with 2 destructured object parameters,
 * and an optional string or number property on the second object parameter.
 *
 * @param {object} arg - required
 * @param {object} arg.data - required
 * @param {object} arg.changes - required
 * 
 * @param {string | number} [arg.changes.displayValue] - optional

 * @returns {object}
 */
function merge({ data, changes }) {
    // First, enforce any type safety requirements
    if ('displayValue' in changes) {
        changes.displayValue = String(changes.displayValue);
    }

    // Merge changes directly into data.
    return Object.assign(data, changes);
}

// should pass
merge({ data: {}, changes: { displayValue: "value" } });
merge({ data: {}, changes: { displayValue: 1234 } });

// should fail
merge({ data: {}, changes: { displayValue: true } });

jsdoc-pull-request-example.md

Update 14 June 2020.

Just found this PR by @raynos using the /** @type ... */ and JSDoc strategy.

See https://github.com/Raynos/error/pull/24/files#diff-168726dbe96b3ce427e7fedce31bb0bc