1
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2024-12-22 23:34:47 -05:00
denoland-deno/tools/ts_library_builder/build_library.ts
andy finch b0a23beb8f Add web worker JS API (#1993)
* Refactored the way worker polling is scheduled and errors are handled.
* Share the worker future as a Shared
2019-04-01 15:09:59 -04:00

612 lines
16 KiB
TypeScript

import { writeFileSync } from "fs";
import { join } from "path";
import * as prettier from "prettier";
import {
InterfaceDeclaration,
ExpressionStatement,
NamespaceDeclarationKind,
Project,
SourceFile,
ts,
Type,
TypeGuards
} from "ts-morph";
import {
addInterfaceDeclaration,
addInterfaceProperty,
addSourceComment,
addTypeAlias,
addVariableDeclaration,
checkDiagnostics,
flattenNamespace,
getSourceComment,
inlineFiles,
loadDtsFiles,
loadFiles,
log,
logDiagnostics,
namespaceSourceFile,
normalizeSlashes,
setSilent
} from "./ast_util";
export interface BuildLibraryOptions {
/**
* The path to the root of the deno repository
*/
basePath: string;
/**
* The path to the current build path
*/
buildPath: string;
/**
* Denotes if the library should be built with debug information (comments
* that indicate the source of the types)
*/
debug?: boolean;
/**
* An array of files that should be inlined into the library
*/
inline?: string[];
/** An array of input files to be provided to the input project, relative to
* the basePath. */
inputs?: string[];
/**
* Path to globals file to be used I.E. `js/globals.ts`
*/
additionalGlobals?: string[];
/**
* List of global variables to define as let instead of the default const.
*/
declareAsLet?: string[];
/**
* The path to the output library
*/
outFile: string;
/**
* Execute in silent mode or not
*/
silent?: boolean;
}
const { ModuleKind, ModuleResolutionKind, ScriptTarget } = ts;
/**
* A preamble which is appended to the start of the library.
*/
const libPreamble = `// Copyright 2018-2019 the Deno authors. All rights reserved. MIT license.
/// <reference no-default-lib="true" />
/// <reference lib="esnext" />
`;
// The path to the msg_generated file relative to the build path
const MSG_GENERATED_PATH = "/gen/cli/msg_generated.ts";
// An array of enums we want to expose pub
const MSG_GENERATED_ENUMS = ["ErrorKind"];
/** Extracts enums from a source file */
function extract(sourceFile: SourceFile, enumNames: string[]): string {
// Copy specified enums from msg_generated
let output = "";
for (const enumName of enumNames) {
const enumDeclaration = sourceFile.getEnumOrThrow(enumName);
enumDeclaration.setHasDeclareKeyword(false);
// we are not copying JSDocs or other trivia here because msg_generated only
// contains some non-useful JSDocs and comments that are not ideal to copy
// over
output += enumDeclaration.getText();
}
return output;
}
interface FlattenOptions {
basePath: string;
customSources: { [filePath: string]: string };
filePath: string;
debug?: boolean;
declarationProject: Project;
globalInterfaceName?: string;
moduleName?: string;
namespaceName?: string;
targetSourceFile: SourceFile;
}
/** Flatten a module */
export function flatten({
basePath,
customSources,
filePath,
debug,
declarationProject,
globalInterfaceName,
moduleName,
namespaceName,
targetSourceFile
}: FlattenOptions): void {
// Flatten the source file into a single set of statements
const statements = flattenNamespace({
sourceFile: declarationProject.getSourceFileOrThrow(filePath),
rootPath: basePath,
customSources,
debug
});
// If a module name is specified create the module in the target file
if (moduleName) {
const namespace = targetSourceFile.addNamespace({
name: moduleName,
hasDeclareKeyword: true,
declarationKind: NamespaceDeclarationKind.Module
});
// Add the output of the flattening to the namespace
namespace.addStatements(statements);
}
if (namespaceName) {
const namespace = targetSourceFile.insertNamespace(0, {
name: namespaceName,
hasDeclareKeyword: true,
declarationKind: NamespaceDeclarationKind.Namespace
});
// Add the output of the flattening to the namespace
namespace.addStatements(statements);
if (globalInterfaceName) {
// Retrieve the global interface
const interfaceDeclaration = targetSourceFile.getInterfaceOrThrow(
globalInterfaceName
);
// Add the namespace to the global interface
addInterfaceProperty(
interfaceDeclaration,
namespaceName,
`typeof ${namespaceName}`
);
}
}
}
interface PrepareFileForMergeOptions {
globalVarName: string;
interfaceName: string;
targetSourceFile: SourceFile;
}
interface PrepareFileForMergeReturn {
interfaceDeclaration: InterfaceDeclaration;
}
export function prepareFileForMerge({
globalVarName,
interfaceName,
targetSourceFile
}: PrepareFileForMergeOptions): PrepareFileForMergeReturn {
// Add the global object interface
const interfaceDeclaration = targetSourceFile.addInterface({
name: interfaceName,
hasDeclareKeyword: true
});
// Declare the global variable
addVariableDeclaration(
targetSourceFile,
globalVarName,
interfaceName,
true,
true
);
// `globalThis` accesses the global scope and is defined here:
// https://github.com/tc39/proposal-global
addVariableDeclaration(
targetSourceFile,
"globalThis",
interfaceName,
true,
true
);
// Add self reference to the global variable
addInterfaceProperty(interfaceDeclaration, globalVarName, interfaceName);
return {
interfaceDeclaration
};
}
interface MergeGlobalOptions extends PrepareFileForMergeOptions {
basePath: string;
debug?: boolean;
declarationProject: Project;
filePath: string;
ignore?: string[];
inputProject: Project;
prepareReturn: PrepareFileForMergeReturn;
declareAsLet?: string[];
}
/** Take a module and merge it into the global scope */
export function mergeGlobals({
basePath,
debug,
declarationProject,
filePath,
globalVarName,
ignore,
inputProject,
targetSourceFile,
declareAsLet,
prepareReturn: { interfaceDeclaration }
}: MergeGlobalOptions): void {
// Retrieve source file from the input project
const sourceFile = inputProject.getSourceFileOrThrow(filePath);
// we are going to create a map of variables
const globalVariables = new Map<
string,
{
type: Type;
node: ExpressionStatement;
}
>();
const globalInterfaces: InterfaceDeclaration[] = [];
// For every augmentation of the global variable in source file, we want
// to extract the type and add it to the global variable map
sourceFile.forEachChild(node => {
if (TypeGuards.isExpressionStatement(node)) {
const firstChild = node.getFirstChild();
if (!firstChild) {
return;
}
if (TypeGuards.isBinaryExpression(firstChild)) {
const leftExpression = firstChild.getLeft();
if (
TypeGuards.isPropertyAccessExpression(leftExpression) &&
leftExpression.getExpression().getText() === globalVarName
) {
const globalVarProperty = leftExpression.getName();
if (globalVarProperty !== globalVarName) {
globalVariables.set(globalVarProperty, {
type: firstChild.getType(),
node
});
}
}
}
} else if (TypeGuards.isInterfaceDeclaration(node) && node.isExported()) {
globalInterfaces.push(node);
}
});
// A set of source files that the types we are using are dependent on us
// importing
const dependentSourceFiles = new Set<SourceFile>();
// Create a global variable and add the property to the `Window` interface
// for each mutation of the `window` variable we observed in `globals.ts`
for (const [property, info] of globalVariables) {
if (!(ignore && ignore.includes(property))) {
const type = info.type.getText(info.node);
const typeSymbol = info.type.getSymbol();
if (typeSymbol) {
const valueDeclaration = typeSymbol.getValueDeclaration();
if (valueDeclaration) {
dependentSourceFiles.add(valueDeclaration.getSourceFile());
}
}
const isConst = !(declareAsLet && declareAsLet.includes(property));
addVariableDeclaration(targetSourceFile, property, type, isConst, true);
addInterfaceProperty(interfaceDeclaration, property, type);
}
}
// We need to copy over any type aliases
for (const typeAlias of sourceFile.getTypeAliases()) {
addTypeAlias(
targetSourceFile,
typeAlias.getName(),
typeAlias.getType().getText(sourceFile),
true
);
}
// We need to copy over any interfaces
for (const interfaceDeclaration of globalInterfaces) {
addInterfaceDeclaration(targetSourceFile, interfaceDeclaration);
}
// We need to ensure that we only namespace each source file once, so we
// will use this map for tracking that.
const sourceFileMap = new Map<SourceFile, string>();
// For each import declaration in source file we will want to convert the
// declaration source file into a namespace that exists within the merged
// namespace
const importDeclarations = sourceFile.getImportDeclarations();
const namespaces = new Set<string>();
for (const declaration of importDeclarations) {
const namespaceImport = declaration.getNamespaceImport();
if (namespaceImport) {
const declarationSourceFile = declaration.getModuleSpecifierSourceFile();
if (
declarationSourceFile &&
dependentSourceFiles.has(declarationSourceFile)
) {
// the source file will resolve to the original `.ts` file, but the
// information we really want is in the emitted `.d.ts` file, so we will
// resolve to that file
const dtsFilePath = declarationSourceFile
.getFilePath()
.replace(/\.ts$/, ".d.ts");
const dtsSourceFile = declarationProject.getSourceFileOrThrow(
dtsFilePath
);
targetSourceFile.addStatements(
namespaceSourceFile(dtsSourceFile, {
debug,
namespace: namespaceImport.getText(),
namespaces,
rootPath: basePath,
sourceFileMap
})
);
}
}
}
if (debug) {
addSourceComment(targetSourceFile, sourceFile, basePath);
}
}
/**
* Generate the runtime library for Deno and write it to the supplied out file
* name.
*/
export function main({
basePath,
buildPath,
inline,
inputs,
additionalGlobals,
declareAsLet,
debug,
outFile,
silent
}: BuildLibraryOptions): void {
setSilent(silent);
log("-----");
log("build_lib");
log();
log(`basePath: "${basePath}"`);
log(`buildPath: "${buildPath}"`);
if (inline && inline.length) {
log("inline:");
for (const filename of inline) {
log(` "${filename}"`);
}
}
if (inputs && inputs.length) {
log("inputs:");
for (const input of inputs) {
log(` "${input}"`);
}
}
log(`debug: ${!!debug}`);
log(`outFile: "${outFile}"`);
log();
// the inputProject will take in the TypeScript files that are internal
// to Deno to be used to generate the library
const inputProject = new Project({
compilerOptions: {
baseUrl: basePath,
declaration: true,
emitDeclarationOnly: true,
lib: ["esnext"],
module: ModuleKind.ESNext,
moduleResolution: ModuleResolutionKind.NodeJs,
paths: {
"*": ["*", `${buildPath}/*`]
},
preserveConstEnums: true,
strict: true,
stripInternal: true,
target: ScriptTarget.ESNext
}
});
// Add the input files we will need to generate the declarations, `globals`
// plus any modules that are importable in the runtime need to be added here
// plus the `lib.esnext` which is used as the base library
if (inputs) {
inputProject.addExistingSourceFiles(
inputs.map(input => join(basePath, input))
);
}
// emit the project, which will be only the declaration files
const inputEmitResult = inputProject.emitToMemory();
log("Emitted input project.");
const inputDiagnostics = inputEmitResult
.getDiagnostics()
.map(d => d.compilerObject);
logDiagnostics(inputDiagnostics);
if (inputDiagnostics.length) {
console.error("\nDiagnostics present during input project emit.\n");
process.exit(1);
}
// the declaration project will be the target for the emitted files from
// the input project, these will be used to transfer information over to
// the final library file
const declarationProject = new Project({
compilerOptions: {
baseUrl: basePath,
lib: ["esnext"],
moduleResolution: ModuleResolutionKind.NodeJs,
paths: {
"*": ["*", `${buildPath}/*`]
},
strict: true,
target: ScriptTarget.ESNext
},
useVirtualFileSystem: true
});
// we don't want to add to the declaration project any of the original
// `.ts` source files, so we need to filter those out
const jsPath = normalizeSlashes(`${basePath}/js`);
const inputProjectFiles = inputProject
.getSourceFiles()
.map(sourceFile => sourceFile.getFilePath())
.filter(filePath => !filePath.startsWith(jsPath));
loadFiles(declarationProject, inputProjectFiles);
// now we add the emitted declaration files from the input project
for (const { filePath, text } of inputEmitResult.getFiles()) {
declarationProject.createSourceFile(filePath, text);
}
// the outputProject will contain the final library file we are looking to
// build
const outputProjectCompilerOptions: ts.CompilerOptions = {
baseUrl: buildPath,
lib: ["esnext"],
moduleResolution: ModuleResolutionKind.NodeJs,
strict: true,
target: ScriptTarget.ESNext
};
const outputProject = new Project({
compilerOptions: outputProjectCompilerOptions,
useVirtualFileSystem: true
});
// There are files we need to load into memory, so that the project "compiles"
loadDtsFiles(outputProject, outputProjectCompilerOptions);
// libDts is the final output file we are looking to build and we are not
// actually creating it, only in memory at this stage.
const libDTs = outputProject.createSourceFile(outFile);
// Deal with `js/deno.ts`
// `gen/msg_generated.d.ts` contains too much exported information that is not
// part of the public API surface of Deno, so we are going to extract just the
// information we need.
const msgGeneratedDts = inputProject.getSourceFileOrThrow(
`${buildPath}${MSG_GENERATED_PATH}`
);
const msgGeneratedDtsText = extract(msgGeneratedDts, MSG_GENERATED_ENUMS);
// Generate a object hash of substitutions of modules to use when flattening
const customSources = {
[msgGeneratedDts.getFilePath().replace(/(\.d)?\.ts$/, "")]: `${
debug ? getSourceComment(msgGeneratedDts, basePath) : ""
}${msgGeneratedDtsText}\n`
};
const prepareForMergeOpts: PrepareFileForMergeOptions = {
globalVarName: "window",
interfaceName: "Window",
targetSourceFile: libDTs
};
const prepareReturn = prepareFileForMerge(prepareForMergeOpts);
mergeGlobals({
basePath,
debug,
declarationProject,
filePath: `${basePath}/js/globals.ts`,
inputProject,
ignore: ["Deno"],
declareAsLet,
...prepareForMergeOpts,
prepareReturn
});
log(`Merged "globals" into global scope.`);
if (additionalGlobals) {
for (const additionalGlobal of additionalGlobals) {
mergeGlobals({
basePath,
debug,
declarationProject,
filePath: `${basePath}/${additionalGlobal}`,
inputProject,
ignore: ["Deno"],
declareAsLet,
...prepareForMergeOpts,
prepareReturn
});
}
log(`Added additional "globals" into global scope.`);
}
flatten({
basePath,
customSources,
debug,
declarationProject,
filePath: `${basePath}/js/deno.d.ts`,
globalInterfaceName: "Window",
namespaceName: "Deno",
targetSourceFile: libDTs
});
log(`Created module "deno" and namespace Deno.`);
// Inline any files that were passed in, to be used to add additional libs
// which are not part of TypeScript.
if (inline && inline.length) {
inlineFiles({
basePath,
debug,
inline,
targetSourceFile: libDTs
});
}
// Add the preamble
libDTs.insertStatements(0, libPreamble);
// Check diagnostics
checkDiagnostics(outputProject);
// Output the final library file
libDTs.saveSync();
const libDTsText = prettier.format(
outputProject.getFileSystem().readFileSync(outFile, "utf8"),
{ parser: "typescript" }
);
if (!silent) {
console.log(`Outputting library to: "${outFile}"`);
console.log(` Length: ${libDTsText.length}`);
}
writeFileSync(outFile, libDTsText, { encoding: "utf8" });
if (!silent) {
console.log("-----");
console.log();
}
}