Updated TypeScript definitions

.gitignore

@@ -3,4 +3,4 @@
 .esm-cache
 node_modules
 package-lock.json
-
+test/src/ts/dist/*

Gruntfile.js

@@ -154,6 +154,15 @@ module.exports = function(grunt) {
           outputSourceFiles: false,
         },
       },
+      ts: {
+        src: docsFiles,
+        options: {
+          destination: 'dist/4.x',
+          configure: 'build/jsdoc.conf.json',
+          template: './node_modules/tsd-jsdoc/dist',
+          outputSourceFiles: false,
+        },
+      },
     },
     webpack: {
       full: {
@@ -264,6 +273,11 @@ module.exports = function(grunt) {
       dist: [ `dist/${verDir}` ],
       docs: [ 'docs' ],
     },
+    ts: {
+      example: {
+        src: ['examples/*.ts'],
+      },
+    },
   });
 
   grunt.registerTask('makeindex', function() {
@@ -343,16 +357,101 @@ module.exports = function(grunt) {
     fs.writeFileSync("npm/base/package.json", JSON.stringify(p, null, 2), {encoding: "utf8"});
   });
 
+  grunt.registerTask('tsmunge', function() {
+    // Fix up syntax and content issues with the auto-generated
+    // TypeScript definitions.
+    let content = fs.readFileSync('dist/4.x/types.d.ts', {encoding: 'utf8'});
+    // These strings will be useful later
+    const glEnumToString = `
+    export function glEnumToString(gl: WebGLRenderingContext, value: number): string;
+    `;
+    const creationAttributes = `export interface WebGLContextCreationAttributes {
+        alpha?: boolean;
+        antialias?: boolean;
+        depth?: boolean;
+        failIfMajorPerformanceCaveat?: boolean;
+        powerPreference?: string;
+        premultipliedAlpha?: boolean;
+        preserveDrawingBuffer?: boolean;
+        stencil?: boolean;
+    }`.replace(/^ {4}/mg, '');
+    // Remove docstrings (Declarations do not by convention include these)
+    content = content.replace(/\/\*\*.*?\*\/\s*/sg, '');
+    // Docs use "?" to represent an arbitrary type; TS uses "any"
+    content = content.replace(/\]: \?/g, ']: any');
+    // Docs use "constructor"; TS expects something more like "Function"
+    content = content.replace(/: constructor/g, ': Function');
+    // Docs use "ArrayBufferViewType" to describe a TypedArray constructor
+    content = content.replace(/\bArrayBufferViewType\b/g, 'Function');
+    // What docs call "TypedArray", lib.d.ts calls "ArrayBufferView"
+    content = content.replace(/\bTypedArray\b/g, 'ArrayBufferView');
+    // What docs call an "augmentedTypedArray" is technically an "ArrayBufferView"
+    // albeit with a patched-in "push" method.
+    content = content.replace(/\baugmentedTypedArray\b/g, 'ArrayBufferView');
+    // Docs use "enum"; TS expects "GLenum"
+    // https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/Types
+    content = content.replace(/: enum/g, ': GLenum');
+    // Remove every instance of "module:twgl" and "module:twgl/whatever"
+    // Except for "module:twgl.(m4|v3|primitives)" which become just "m4.", etc.
+    content = content.replace(/module:twgl(\/(m4|v3|primitives))\./g, '$2.');
+    content = content.replace(/module:twgl(\/\w+)?\./g, '');
+    // Replace "function", "type" declarations with "export function", "export type"
+    content = content.replace(/^(\s*)(function|type) /mg, '$1export $2 ');
+    // Fixup dynamically generated glEnumToString function signature
+    content = content.replace(/var glEnumToString: any;/g, glEnumToString);
+    // Break the file down into a list of modules
+    const modules = content.match(/^declare module twgl(\/(\w+))? \{.*?^\}/msg);
+    // Split into core modules and extra (only in twgl-full) modules
+    const coreModules = modules.filter(
+      (code) => !code.match(/^declare module twgl\/(m4|v3|primitives)/)
+    );
+    const extraModules = modules.filter(
+      (code) => code.match(/^declare module twgl\/(m4|v3|primitives)/)
+    );
+    // Build code for the core twgl.js output
+    let coreContent = coreModules.map((code) => {
+      // Get rid of "declare module twgl/whatever" scope
+      code = code.replace(/^declare module twgl(\/\w+)? \{(.*?)^\}/msg, "$2");
+      // De-indent the contents of that scope
+      code = code.replace(/^ {4}/mg, '');
+      // All done
+      return code;
+    }).join("\n");
+    // Include type describing canvas.getContext input attributes
+    // https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext
+    coreContent = [creationAttributes, coreContent].join("\n");
+    // Build additional code for the extended twgl-full.js output
+    let extraContent = extraModules.map((code) => {
+      // Fix "declare module twgl/whatever" statements
+      return code.replace(/^declare module twgl(\/(\w+))? \{/m,
+        "declare module $2 {"
+      );
+    }).join("\n");
+    // Write twgl-full declarations to destination file
+    const fullContent = [coreContent, extraContent].join("\n");
+    fs.writeFileSync('dist/4.x/twgl-full.d.ts', fullContent);
+    // Write core declarations to destination file
+    fs.writeFileSync('dist/4.x/twgl.d.ts', coreContent);
+    // Remove the auto-generated input file
+    fs.unlinkSync('dist/4.x/types.d.ts');
+  });
+
   grunt.registerTask('docs', [
       'eslint:examples',
       'clean:docs',
-      'jsdoc',
+      'jsdoc:docs',
       'makeindex',
   ]);
+  grunt.registerTask('buildts', [
+      'jsdoc:ts',
+      'tsmunge',
+  ]);
   grunt.registerTask('build', [
       'eslint:lib',
       'clean:dist',
       'webpack',
+      'buildts',
+      'ts',
       'copy',
       'npmpackage',
   ]);