diff --git a/lib/index.js b/lib/index.js index 5c39681..b460201 100644 --- a/lib/index.js +++ b/lib/index.js @@ -1,15 +1,35 @@ 'use strict'; +/** + * @typedef {import("./types.ts").BabelParseError} BabelParseError + * @typedef {import("./types.ts").Config} Config + * @typedef {import("./types.ts").ArgsConfig} ArgsConfig + * @typedef {import("./types.ts").BabelOptions} BabelOptions + * @typedef {import("./types.ts").KarmaFile} KarmaFile + * @typedef {import("./types.ts").KarmaNextFn} KarmaNextFn + * @typedef {import("./types.ts").KarmaLogger} KarmaLogger + * @typedef {import("./types.ts").KarmaHelperFns} KarmaHelperFns + */ + var babel = require('@babel/core'); -// @param args {Object} - Config object of custom preprocessor. -// @param config {Object} - Config object of babelPreprocessor. -// @param logger {Object} - Karma's logger. -// @helper helper {Object} - Karma's helper functions. +/** + * @param {ArgsConfig} args - Config object of custom preprocessor. + * @param {Config} config - Config object of babelPreprocessor. + * @param {KarmaLogger} logger - Karma's logger. + * @param {KarmaHelperFns} helper - Karma's helper functions. + */ function createPreprocessor(args, config, logger, helper) { var log = logger.create('preprocessor.babel'); config = config || {}; + /** + * @see http://karma-runner.github.io/6.4/dev/plugins.html + * + * @param {string} content of the file being processed + * @param {KarmaFile} file object describing the file being processed + * @param {KarmaNextFn} done function to be called when preprocessing is complete + */ function preprocess(content, file, done) { log.debug('Processing "%s".', file.originalPath); @@ -33,6 +53,15 @@ function createPreprocessor(args, config, logger, helper) { return preprocess; } +/** + * Create Babel options from Karma config of this plugin. + * + * @param {ArgsConfig} customConfig + * @param {Config} baseConfig + * @param {KarmaHelperFns} helper + * @param {KarmaFile} file + * @return {BabelOptions} + */ function createOptions(customConfig, baseConfig, helper, file) { // Ignore 'base' property of custom preprocessor's config. customConfig = helper.merge({}, customConfig); @@ -50,6 +79,15 @@ function createOptions(customConfig, baseConfig, helper, file) { return options; } +/** + * Create Babel options from file-specific callbacks + * in the Karma config of this plugin. + * + * @param {Config} config + * @param {KarmaHelperFns} helper + * @param {KarmaFile} file + * @return {BabelOptions} + */ function createPerFileOptions(config, helper, file) { return Object.keys(config) .filter(function (optionName) { return optionName !== 'options'; }) diff --git a/lib/types.ts b/lib/types.ts new file mode 100644 index 0000000..4078772 --- /dev/null +++ b/lib/types.ts @@ -0,0 +1,79 @@ +/** + * Babel options @see https://babeljs.io/docs/options + */ +export type BabelOptions = Record + +/** + * Babel options @see https://babeljs.io/docs/options, but the value + * is a callback that receives a file and returns the Babel config value. + */ +export type PerFileOptions = Record any> + +/** + * Config of this plugin. + */ +export type Config = { + options?: BabelOptions +} & PerFileOptions + +/** + * Custom-preprocessor config of this plugin. + */ +export type ArgsConfig = { + base: 'babel' + options?: BabelOptions +} & PerFileOptions + +/** + * Babel parse error. + */ +export type BabelParseError = { + code: string + reasonCode: string + loc: { + line: number + column: number + } +} + +/** + * Karma File. + * + * @see http://karma-runner.github.io/6.4/dev/plugins.html + */ +export type KarmaFile = { + /** + * the original, unmutated path + */ + originalPath: string + /** + * the current file, mutable file path. + */ + path: string + /** + * determines how to include a file, when serving + */ + type: string + /** + * A mutable, keyed object where the keys are a valid + * encoding type ('gzip', 'compress', 'br', etc.) and + * the values are the encoded content. Encoded content + * should be stored here and not resolved using + * next(null, encodedContent) + */ + encodings: Record +} + +/** + * Karma Next Function. + * + * @see http://karma-runner.github.io/6.4/dev/plugins.html + * + * function to be called when preprocessing is complete, should be called as + * next(null, processedContent) or next(error) + */ +export type KarmaNextFn = (error: Error | null, content?: string | null) => void; + +export type KarmaLogger = any; + +export type KarmaHelperFns = any;