Generate TypeScript type definitions

.gitignore

@@ -6,3 +6,4 @@ dist/
 docs/api/
 coverage/
 .DS_Store
+.vscode

build/all.py

@@ -25,6 +25,7 @@
 import docs
 import gendeps
 import generateLocalizations
+import logging
 import shakaBuildHelpers
 
 import os
@@ -143,6 +144,13 @@ def main(args):
     is_debug = mode == 'debug'
     if not apps.build_all(parsed_args.force, is_debug):
       return 1
+
+  if 'release' in modes:
+    # Check if the generated Typescript typings are correct
+    logging.info('Checking generated Typescript typings...')
+    tsc = compiler.TypescriptCompiler("test/typescript/tsconfig.json")
+    if not tsc.compile():
+      return 1
 
   return 0
 

build/build.py

@@ -65,6 +65,7 @@
     '--extra_annotation_name=listens',
     '--extra_annotation_name=exportDoc',
     '--extra_annotation_name=exportInterface',
+    '--extra_annotation_name=exportTypescript',
 
     '--conformance_configs',
     ('%s/build/conformance.textproto' %
@@ -278,6 +279,7 @@ def build_library(self, name, locales, force, is_debug):
     # Don't pass node modules to the extern generator.
     local_include = set([f for f in self.include if 'node_modules' not in f])
     generator = compiler.ExternGenerator(local_include, build_name)
+    ts_generator = compiler.TypescriptGenerator(local_include, build_name)
 
     closure_opts = common_closure_opts + common_closure_defines
     if is_debug:
@@ -290,6 +292,9 @@ def build_library(self, name, locales, force, is_debug):
 
     if not generator.generate(force):
       return False
+
+    if not ts_generator.generate(force):
+      return False
 
     return True
 

build/compiler.py

@@ -222,6 +222,61 @@ def generate(self, force=False):
     return True
 
 
+class TypescriptGenerator(object):
+  def __init__(self, source_files, build_name):
+    self.source_files = _canonicalize_source_files(source_files)
+    self.output = _get_source_path('dist/' + build_name + '.d.ts')
+
+  def generate(self, force=False):
+    """Generates TypeScript definitions for the files in |self.source_files|.
+
+    Args:
+      force: Generate the output even if the inputs have not changed.
+
+    Returns:
+      True on success; False on failure.
+    """
+    if not force and not _must_build(self.output, self.source_files):
+      return True
+
+    ts_generator = _get_source_path('build/typescript/main.ts')
+    tsconfig = _get_source_path('build/typescript/tsconfig.json')
+
+    ts_node = shakaBuildHelpers.get_node_binary('ts-node')
+    ts_options = ['-P', tsconfig, ts_generator, '--output', self.output]
+
+    cmd_line = ts_node + ts_options + self.source_files
+
+    if shakaBuildHelpers.execute_get_code(cmd_line) != 0:
+      logging.error('TypeScript generation failed')
+      return False
+
+    return True
+
+
+class TypescriptCompiler(object):
+  def __init__(self, project):
+    self.project = _get_source_path(project)
+
+  def compile(self):
+    """Compiles the TypeScript project defined by the tsconfig in |self.project|.
+
+    Returns:
+      True on success; False on failure.
+    """
+
+    tsc = shakaBuildHelpers.get_node_binary('typescript', 'tsc')
+    tsc_options = ['-p', self.project]
+    cmd_line = tsc + tsc_options
+
+    if shakaBuildHelpers.execute_get_code(cmd_line) != 0:
+      logging.error('TypeScript compiler failed')
+      return False
+
+    return True
+
+
+
 class Less(object):
   def __init__(self, main_source_file, all_source_files, output):
     # Less only takes one input file, but that input may import others.

build/typescript/assert.ts

@@ -0,0 +1,11 @@
+import { strict } from "assert";
+
+export const fail = strict.fail;
+
+// Workaround for node.js "assert" module missing the new TypeScript "asserts" syntax
+const assert: (
+  condition: unknown,
+  message?: string | Error
+) => asserts condition = strict.ok;
+
+export default assert;

build/typescript/base.ts

@@ -0,0 +1,159 @@
+import * as doctrine from "@teppeis/doctrine";
+
+/**
+ * Type of "@" annotation in Closure block comment
+ */
+export enum AnnotationType {
+  Const = "const",
+  Enum = "enum",
+  Class = "class",
+  Interface = "interface",
+  Function = "function",
+  Property = "property",
+  Typedef = "typedef",
+  Namespace = "namespace",
+  Event = "event"
+}
+
+/**
+ * A property defined by the @property annotation
+ */
+export interface Props {
+  name: string;
+  type: doctrine.Type;
+  description?: string;
+}
+
+/**
+ * Metadata defined by annotations in closure block comment
+ */
+export interface Attributes {
+  type?: AnnotationType;
+  description?: string;
+  identifier?: string[];
+  comments: string[];
+  export: boolean;
+
+  props?: Props[];
+  constType?: doctrine.Type;
+  enumType?: doctrine.Type;
+  typedefType?: doctrine.Type;
+  propType?: doctrine.Type;
+  paramTypes?: doctrine.Type[];
+  returnType?: doctrine.Type;
+  eventType?: string; // Not a real type, but a string identifier
+
+  implements?: doctrine.Type;
+  extends?: doctrine.Type;
+  template?: string[];
+}
+
+/**
+ * Type of JS value assigned to the definition.
+ * Comment definitions are block comments that are not followed by a
+ * JS statement.
+ */
+export enum DefinitionType {
+  Function = "function",
+  Object = "object",
+  Class = "class",
+  Property = "property",
+  Comment = "comment"
+}
+
+/**
+ * Common definition properties
+ */
+export interface BaseDefinition {
+  identifier: string[];
+  attributes?: Attributes;
+}
+
+/**
+ * JavaScript function declarations
+ */
+export interface FunctionDefinition extends BaseDefinition {
+  type: DefinitionType.Function;
+  params: string[];
+
+  isMethod?: boolean;
+  isStatic?: boolean;
+  isConstructor?: boolean;
+  definitions?: Definition[];
+}
+
+/**
+ * JavaScript object literals
+ */
+export interface ObjectDefinition extends BaseDefinition {
+  type: DefinitionType.Object;
+  props: string[];
+}
+
+/**
+ * ES2015 class declarations
+ */
+export interface ClassDefinition extends BaseDefinition {
+  type: DefinitionType.Class;
+  superClass?: string[];
+  methods: FunctionDefinition[];
+}
+
+/**
+ * All other values or member expressions without assignment
+ */
+export interface PropertyDefinition extends BaseDefinition {
+  type: DefinitionType.Property;
+}
+
+/**
+ * Block comments without following JavaScript statement
+ */
+export interface CommentDefinition extends BaseDefinition {
+  type: DefinitionType.Comment;
+}
+
+/**
+ * Definitions parsed from the incoming Closure code
+ */
+export type Definition =
+  | FunctionDefinition
+  | ObjectDefinition
+  | ClassDefinition
+  | PropertyDefinition
+  | CommentDefinition;
+
+/**
+ * Type for definition tree nodes
+ */
+export interface Node {
+  name: string;
+  definition?: Definition;
+  children: Map<string, Node>;
+}
+
+/**
+ * Base type used for building the definition tree
+ */
+export type NodeMap = Map<string, Node>;
+
+/**
+ * Must be implemented by output targets for writing type definitions
+ */
+export interface Writer {
+  increaseLevel(): void;
+  decreaseLevel(): void;
+  getIndentation(): string;
+
+  write(str: string): void;
+  writeLine(str: string): void;
+  writeComments(comments: string[]): void;
+  writePrefix(): void;
+}
+
+/**
+ * Must be implemented by nodes that should be written to the output
+ */
+export interface Writable {
+  write(writer: Writer): void;
+}