refactor(vanillin): more async reads where possible

Author: Sebastian Schürmann

packages/vanillin/src/compiler.ts

@@ -1,6 +1,6 @@
 import { createProgram, CompilerOptions, Program, CustomTransformers, getPreEmitDiagnostics, Diagnostic, EmitResult, CompilerHost, ModuleKind, ModuleResolutionKind, ScriptTarget }  from "typescript";
 import transformer from './transformer.js';
-import { readFileSync } from "fs";
+import { readFile } from "fs/promises";
 import { createVirtualCompilerHost } from "./virtual-fs.js";
 import { resolve, dirname } from "path";
 import { fileURLToPath } from "url";
@@ -13,12 +13,21 @@ import { fileURLToPath } from "url";
 const loadTypeScriptLibFiles = async () => {
     const tsPath = await import.meta.resolve('typescript');
     const tsLibPath = resolve(dirname(fileURLToPath(tsPath)), '');
-    const libFiles = {
-        'lib.es2015.d.ts': readFileSync(resolve(tsLibPath, 'lib.es2015.d.ts'), 'utf-8'),
-        'lib.dom.d.ts': readFileSync(resolve(tsLibPath, 'lib.dom.d.ts'), 'utf-8'),
-        'lib.es5.d.ts': readFileSync(resolve(tsLibPath, 'lib.es5.d.ts'), 'utf-8'),
+    
+    const libFilePaths = {
+        'lib.es2015.d.ts': resolve(tsLibPath, 'lib.es2015.d.ts'),
+        'lib.dom.d.ts': resolve(tsLibPath, 'lib.dom.d.ts'),
+        'lib.es5.d.ts': resolve(tsLibPath, 'lib.es5.d.ts'),
     };
-    return libFiles;
+
+    const fileContents = await Promise.all(
+        Object.entries(libFilePaths).map(async ([fileName, filePath]) => {
+            const content = await readFile(filePath, 'utf-8');
+            return [fileName, content] as const;
+        })
+    );
+
+    return Object.fromEntries(fileContents);
 };
 
 /**
@@ -130,16 +139,18 @@ export class Compiler {
      */
     static async withVirtualFs(fileNames: string[], options: CompilerOptions): Promise<Compiler> {
         // Load source files
-        const sourceFiles = fileNames.reduce((acc, fileName) => {
-            acc[fileName] = readFileSync(fileName, 'utf-8');
-            return acc;
-        }, {} as { [path: string]: string });
+        const sourceFiles = await Promise.all(
+            fileNames.map(async (fileName) => {
+                const content = await readFile(fileName, 'utf-8');
+                return [fileName, content] as const;
+            })
+        );
 
         // Load TypeScript lib files
         const libFiles = await loadTypeScriptLibFiles();
 
         // Combine source files and lib files
-        const files = { ...sourceFiles, ...libFiles };
+        const files = { ...Object.fromEntries(sourceFiles), ...libFiles };
 
         const host = createVirtualCompilerHost({ 
             files, 

packages/vanillin/src/doc-gen.ts

@@ -1,6 +1,6 @@
 import { TSDocParser, type ParserContext, type DocComment, TSDocConfiguration, TSDocTagDefinition, TSDocTagSyntaxKind } from '@microsoft/tsdoc';
 import * as path from 'path';
-import * as fs from 'fs';
+import { readFile } from 'fs/promises';
 import { Formatter } from './formatter';
 
 /**
@@ -23,11 +23,11 @@ export class DocGen {
      * Parses a TypeScript source file to extract its documentation.
      * 
      * @param doc - The path to the TypeScript source file to parse
-     * @returns A ParserContext containing the parsed documentation
+     * @returns A Promise that resolves to a ParserContext containing the parsed documentation
      */
-    parseDoc(doc: string): ParserContext {
+    async parseDoc(doc: string): Promise<ParserContext> {
         const inputFilename: string = path.resolve(doc);
-        const inputBuffer: string = fs.readFileSync(inputFilename).toString();
+        const inputBuffer: string = await readFile(inputFilename, 'utf-8');
 
         const customConfiguration: TSDocConfiguration = new TSDocConfiguration();
 
@@ -58,8 +58,12 @@ export class DocGen {
      * 
      * @param context - The parsed documentation context to render
      * @returns A formatted string containing only the custom documentation blocks
+     * @throws Error if the context or docComment is undefined
      */
-    renderDocs(context: ParserContext) {
+    renderDocs(context: ParserContext): string {
+        if (!context || !context.docComment) {
+            throw new Error('Invalid parser context: docComment is undefined');
+        }
         const docComment: DocComment = context.docComment;
         const result = Formatter.renderDocNodes(docComment.customBlocks);
         return result;

packages/vanillin/test/doc-gen.test.ts

@@ -3,21 +3,21 @@ import assert from "node:assert";
 import { DocGen } from '../src/doc-gen';
 
 describe('DocGen', () => {
-    it('should parse a typescript file and return a ParserContext', () => {
+    it('should parse a typescript file and return a ParserContext', async () => {
         const docGen = new DocGen();
-        const result = docGen.parseDoc('./test/fixtures/my-circle.ts');
+        const result = await docGen.parseDoc('./test/fixtures/my-circle.ts');
         assert.ok(result, 'ParserContext should be returned');
     });
 
-    it('returns the demo tag', () => {
+    it('returns the demo tag', async () => {
         const docGen = new DocGen();
-        const result = docGen.parseDoc('./test/fixtures/my-circle.ts');
+        const result = await docGen.parseDoc('./test/fixtures/my-circle.ts');
         assert.equal(result.docComment.customBlocks.length, 1);
     });
 
-    it('rendered result contains tag', () => {
+    it('rendered result contains tag', async () => {
         const docGen = new DocGen();
-        const result = docGen.parseDoc('./test/fixtures/my-circle.ts');
+        const result = await docGen.parseDoc('./test/fixtures/my-circle.ts');
         const doc = docGen.renderDocs(result);
         assert.match(doc, /my-circle/);
     });