diff --git a/src/bundle.ts b/src/bundle.ts index 202ba45..63939b1 100644 --- a/src/bundle.ts +++ b/src/bundle.ts @@ -3,14 +3,35 @@ import fs from 'fs' import { CreateEvaluateOptions, createEvaluateModule } from './module' import { createSourceMap } from './source-map' +/** + * Represents a collection of file contents where the key is the file name and the value is the file contents. + */ export type Files = { [name: string]: any } +/** + * Defines the options required to create a bundle. Inherits from {@link CreateEvaluateOptions}. + */ export type CreateBundleOptions = CreateEvaluateOptions export type Bundle = { + /** + * The base directory for the bundle. All file paths are relative to this directory. + */ basedir: string + + /** + * The entry point filename of the bundle. + */ entry: string + + /** + * A collection of file contents indexed by filename. See {@link files}. + */ files: { [filename: string]: string } + + /** + * A collection of source maps indexed by filename. + */ maps: { [filename: string]: string } } @@ -68,6 +89,13 @@ function loadBundle (bundle: Partial | string, basedir?: string): Bundle return bundle as Bundle } +/** + * Creates a bundle and prepares it for evaluation by setting up the necessary modules and error trace rewriters. + * + * @param {_bundle} Partial | string The partial bundle data or a path to the bundle file. See {@link Bundle}. + * @param {CreateBundleOptions} [options={}] Configuration options for creating the bundle, defaults to an empty object. See {@link CreateBundleOptions}. + * @returns {object} An object containing the fully prepared bundle, the module evaluator, the entry evaluator and the error trace rewriter. + */ export function createBundle (_bundle: Partial | string, options: CreateBundleOptions = {}) { const bundle = loadBundle(_bundle, options.basedir) const { rewriteErrorTrace } = createSourceMap(bundle.maps) diff --git a/src/module.ts b/src/module.ts index c81a976..cbdf721 100644 --- a/src/module.ts +++ b/src/module.ts @@ -18,11 +18,26 @@ const _global = { } export interface CreateEvaluateOptions { + /** + * The base directory from which modules should be resolved. + * @optional + */ basedir?: string, + /** + * Specifies whether the module should be run in a new VM context and whether it should be reused ('once') or not. + * @optional + */ runInNewContext?: 'once' | boolean, + /** + * Options for running scripts within a VM context. See {@link RunningScriptOptions}. + * @optional + */ runningScriptOptions?: RunningScriptOptions } +/** + * Represents a function that evaluates a module with a given filename and context, and returns the result of the evaluation. + */ export type EvaluateModule = (filename: string, context: Object) => any type Sandbox = typeof _global @@ -52,6 +67,13 @@ function createModule (options: Partial): NodeJS.Module { } } +/** + * Constructs a module evaluator function with given file mappings and evaluation options. + * + * @param {Files} files A mapping of file names to file contents. + * @param {CreateEvaluateOptions} options The options used to create the evaluator. + * @returns {EvaluateModule} A function capable of evaluating a module from its filename within a given context. + */ export function createEvaluateModule (files: Files, { basedir, runInNewContext, runningScriptOptions }: CreateEvaluateOptions): EvaluateModule { const _evalCache: { [key: string]: object } = {}