release: v0.1.2 - custom module resolving

Author: sambacha

README.md

@@ -1,6 +1,6 @@
 # `std.module.format` 
 
-> version 0.1.1
+> version 0.1.2
 
 - [`std.module.format`](#-stdmoduleformat-)
   * [Overview](#overview)
@@ -23,11 +23,14 @@
         * [Note](#note)
     + [Needs two lines for non-class / non-function](#needs-two-lines-for-non-class---non-function)
     + [React.js - Named Exports](#reactjs---named-exports)
-  * [The {} type](#---type)
+  * [{} type](#---type)
     + [If you want a type that means "empty object"](#if-you-want-a-type-that-means--empty-object-)
     + [If you are using React, and you want to define `type Props = {}`.](#if-you-are-using-react--and-you-want-to-define--type-props------)
     + [`GenericObject`](#-genericobject-)
     + [Module-related host hooks](#module-related-host-hooks)
+  * [Customizing module resolution](#customizing-module-resolution)
+    + [parserOptions.moduleResolver](#parseroptionsmoduleresolver)
+  * [License](#license)
 
 <small><i><a href='#'>This is a work in progress</a></i></small>
 
@@ -596,6 +599,127 @@ The following are not valid module specifiers according to the above algorithm:
 -   `.\yam.es`
 
 
+## Customizing module resolution
+
+> [source, https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API#customizing-module-resolution]
+
+You can override the standard way the compiler resolves modules by implementing optional method: CompilerHost.resolveModuleNames:
+
+```typescript
+CompilerHost.resolveModuleNames(moduleNames: string[], containingFile: string): string[].
+```
+
+The method is given a list of module names in a file, and is expected to return an array of size moduleNames.length, each element of the array stores either:
+
+an instance of ResolvedModule with non-empty property resolvedFileName - resolution for corresponding name from moduleNames array or undefined if module name cannot be resolved.
+
+You can invoke the standard module resolution process via calling resolveModuleName:
+
+```typescript
+resolveModuleName(moduleName: string, containingFile: string, options: CompilerOptions, moduleResolutionHost: ModuleResolutionHost): ResolvedModuleNameWithFallbackLocations.
+```
+
+This function returns an object that stores result of module resolution (value of resolvedModule property) as well as list of file names that were considered candidates before making current decision.
+
+```typescript
+import * as ts from "typescript";
+import * as path from "path";
+
+function createCompilerHost(options: ts.CompilerOptions, moduleSearchLocations: string[]): ts.CompilerHost {
+  return {
+    getSourceFile,
+    getDefaultLibFileName: () => "lib.d.ts",
+    writeFile: (fileName, content) => ts.sys.writeFile(fileName, content),
+    getCurrentDirectory: () => ts.sys.getCurrentDirectory(),
+    getDirectories: path => ts.sys.getDirectories(path),
+    getCanonicalFileName: fileName =>
+      ts.sys.useCaseSensitiveFileNames ? fileName : fileName.toLowerCase(),
+    getNewLine: () => ts.sys.newLine,
+    useCaseSensitiveFileNames: () => ts.sys.useCaseSensitiveFileNames,
+    fileExists,
+    readFile,
+    resolveModuleNames
+  };
+
+  function fileExists(fileName: string): boolean {
+    return ts.sys.fileExists(fileName);
+  }
+
+  function readFile(fileName: string): string | undefined {
+    return ts.sys.readFile(fileName);
+  }
+
+  function getSourceFile(fileName: string, languageVersion: ts.ScriptTarget, onError?: (message: string) => void) {
+    const sourceText = ts.sys.readFile(fileName);
+    return sourceText !== undefined
+      ? ts.createSourceFile(fileName, sourceText, languageVersion)
+      : undefined;
+  }
+
+  function resolveModuleNames(
+    moduleNames: string[],
+    containingFile: string
+  ): ts.ResolvedModule[] {
+    const resolvedModules: ts.ResolvedModule[] = [];
+    for (const moduleName of moduleNames) {
+      // try to use standard resolution
+      let result = ts.resolveModuleName(moduleName, containingFile, options, {
+        fileExists,
+        readFile
+      });
+      if (result.resolvedModule) {
+        resolvedModules.push(result.resolvedModule);
+      } else {
+        // check fallback locations, for simplicity assume that module at location
+        // should be represented by '.d.ts' file
+        for (const location of moduleSearchLocations) {
+          const modulePath = path.join(location, moduleName + ".d.ts");
+          if (fileExists(modulePath)) {
+            resolvedModules.push({ resolvedFileName: modulePath });
+          }
+        }
+      }
+    }
+    return resolvedModules;
+  }
+}
+
+function compile(sourceFiles: string[], moduleSearchLocations: string[]): void {
+  const options: ts.CompilerOptions = {
+    module: ts.ModuleKind.AMD,
+    target: ts.ScriptTarget.ES5
+  };
+  const host = createCompilerHost(options, moduleSearchLocations);
+  const program = ts.createProgram(sourceFiles, options, host);
+
+  /// do something with program...
+}
+```
+
+### parserOptions.moduleResolver
+
+> [source, https://www.npmjs.com/package/@typescript-eslint/parser](https://www.npmjs.com/package/@typescript-eslint/parser)
+
+Default: `undefined`
+
+This option allows you to provide a custom module resolution. The value should point to a JS file that default exports (`export default`, or `module.exports =`, or `export =`) a file with the following interface:
+
+```
+interface ModuleResolver {
+  version: 1;
+  resolveModuleNames(
+    moduleNames: string[],
+    containingFile: string,
+    reusedNames: string[] | undefined,
+    redirectedReference: ts.ResolvedProjectReference | undefined,
+    options: ts.CompilerOptions,
+  ): (ts.ResolvedModule | undefined)[];
+}
+```
+Refer to the TypeScript Wiki for an example on how to write the resolveModuleNames function.
+
+Note that if you pass custom programs via options.programs this option will not have any effect over them (you can simply add the custom resolution on them directly).
+
 ## License
 
 CC-SA-2.5