@plugjs/plug 0.1.4 → 0.2.1

package/extra/ts-loader.mts

@@ -0,0 +1,545 @@
+/* ========================================================================== *
+ * HACK BEYOND REDEMPTION: TRANSPILE .ts FILES (the esm loader)               *
+ * -------------------------------------------------------------------------- *
+ * This relies on the Node's `--experimental-loader` feature, and uses        *
+ * ESBuild build magic to quickly transpile TypeScript files into JavaScript. *
+ *                                                                            *
+ * The plan as it stands is as follows:                                       *
+ * - `.mts` files always get transpiled to ESM modules                        *
+ * - `.cts` files always get transpiled to CJS modules                        *
+ * - `.ts` files are treanspiled according to what's in `package.json`        *
+ *                                                                            *
+ * Additionally, when transpiling to ESM modules, we can't rely on the magic  *
+ * that Node's `require(...)` call uses to figure out which file to import.   *
+ * We need to _actually verify_ on disk what's the correct file to import.    *
+ *                                                                            *
+ * This is a single module, only available as ESM, and it will _both_ behave  *
+ * as a NodeJS' loader, _and_ inject the CJS extension handlers (hack) found  *
+ * in the `_extensions` of `node:module` (same as `require.extensions`).      *
+ * ========================================================================== */
+
+// NodeJS dependencies
+import _fs from 'node:fs'
+import _module from 'node:module'
+import _path from 'node:path'
+import _url from 'node:url'
+import _util from 'node:util'
+
+// ESBuild is the only external dependency
+import _esbuild from 'esbuild'
+
+// Local imports
+import { isDirectory, isFile } from './utils.js'
+
+/* ========================================================================== *
+ * DEBUGGING AND ERRORS                                                       *
+ * ========================================================================== */
+
+/** Supported types from `package.json` */
+export type Type = 'commonjs' | 'module'
+/** Constant identifying a `commonjs` module */
+const CJS = 'commonjs'
+/** Constant identifying an ESM `module` */
+const ESM = 'module'
+
+/** Setup debugging */
+const _debugLog = _util.debuglog('plug:ts-loader')
+const _debug = _debugLog.enabled
+
+/** Emit some logs if `DEBUG_TS_LOADER` is set to `true` */
+function _log(type: Type | null, arg: string, ...args: any []): void {
+  if (! _debug) return
+
+  const t = type === ESM ? 'esm' : type === CJS ? 'cjs' : '---'
+  _debugLog(`[${t}] ${arg}`, ...args)
+}
+
+/** Fail miserably */
+function _throw(
+    type: Type | null,
+    message: string,
+    options: { start?: Function, code?: string, cause?: any } = {},
+): never {
+  const t = type === ESM ? 'esm' : type === CJS ? 'cjs' : '---'
+  const prefix = `[ts-loader|${t}|pid=${process.pid}]`
+
+  const { start = _throw, ...extra } = options
+  const error = new Error(`${prefix} ${message}`)
+  Error.captureStackTrace(error, start)
+  Object.assign(error, extra)
+
+  throw error
+}
+
+
+/* ========================================================================== *
+ * MODULE TYPES AND FORCING TYPE                                              *
+ * ========================================================================== */
+
+function _checkType(type: string): Type {
+  if (type === CJS) return CJS
+  if (type === ESM) return ESM
+  _throw(null, `Invalid type "${process.env.__TS_LOADER_FORCE_TYPE}"`)
+}
+
+let _type: Type = ((): Type => {
+  if (process.env.__TS_LOADER_FORCE_TYPE) {
+    const type = process.env.__TS_LOADER_FORCE_TYPE
+    _log(null, `Forcing type to "${type}" from environment`)
+    return _checkType(type)
+  }
+
+  const findType = (directory: string): Type => {
+    const packageFile = _path.join(directory, 'package.json')
+    try {
+      const packageData = _fs.readFileSync(packageFile, 'utf-8')
+      const packageJson = JSON.parse(packageData)
+      const packageType = packageJson.type
+      switch (packageType) {
+        case undefined:
+          _log(null, `File "${packageFile}" does not declare a default type`)
+          return CJS
+
+        case CJS:
+        case ESM:
+          _log(null, `File "${packageFile}" declares type as "${CJS}"`)
+          return packageType
+
+        default:
+          _log(null, `File "${packageFile}" specifies unknown type "${packageType}"`)
+          return CJS
+      }
+    } catch (cause: any) {
+      if ((cause.code !== 'ENOENT') && (cause.code !== 'EISDIR')) {
+        _throw(null, `Unable to read or parse "${packageFile}"`, { cause, start: findType })
+      }
+    }
+
+    const parent = _path.dirname(directory)
+    if (directory !== parent) return findType(directory)
+
+    _log(null, `Type defaulted to "${CJS}"`)
+    return CJS
+  }
+
+  return findType(process.cwd())
+})()
+
+/* The `tsLoaderMarker` (symbol in global) will be a setter/getter for type */
+const tsLoaderMarker = Symbol.for('plugjs:tsLoader')
+
+Object.defineProperty(globalThis, tsLoaderMarker, {
+  set(type: string): void {
+    _log(null, `Setting type to "${type}"`)
+    process.env.__TS_LOADER_FORCE_TYPE = _type = _checkType(type)
+  },
+  get(): Type {
+    return _type
+  },
+})
+
+
+/* ========================================================================== *
+ * ESBUILD HELPERS                                                            *
+ * ========================================================================== */
+
+/**
+ * Take an ESBuild `BuildResult` or `BuildFailure` (they both have arrays
+ * of `Message` in both `warnings` and `errors`), format them and print them
+ * out nicely. Then fail if any error was detected.
+ */
+function _esbReport(
+    kind: 'error' | 'warning',
+    messages: _esbuild.Message[] = [],
+): void {
+  const output = process.stderr
+  const options = { color: !!output.isTTY, terminalWidth: output.columns || 80 }
+
+  const array = _esbuild.formatMessagesSync(messages, { kind, ...options })
+  array.forEach((message) => output.write(`${message}\n`))
+}
+
+/**
+ * Transpile with ESBuild
+ */
+function _esbTranpile(filename: string, type: Type): string {
+  _log(type, `Transpiling "${filename}`)
+
+  const [ format, __fileurl ] = type === ESM ?
+    [ 'esm', 'import.meta.url' ] as const :
+    [ 'cjs', '__filename' ] as const
+
+  /* ESbuild options */
+  const options: _esbuild.TransformOptions = {
+    sourcefile: filename, // the original filename we're parsing
+    format, // what are we actually transpiling to???
+    loader: 'ts', // the format is always "typescript"
+    sourcemap: 'inline', // always inline source maps
+    sourcesContent: false, // do not include sources content in sourcemap
+    platform: 'node', // d'oh! :-)
+    logLevel: 'silent', // catching those in our _esbReport below
+    target: `node${process.versions['node']}`, // target _this_ version
+    define: { __fileurl }, // from "globals.d.ts"
+  }
+
+  /* Emit a line on the console when loading in debug mode */
+  if (_debug) {
+    if (format === 'esm') {
+      options.banner = `;(await import('node:util')).debuglog('plug:ts-loader')('[esm] Loaded "%s"', ${__fileurl});`
+    } else if (format === 'cjs') {
+      options.banner = `;require('node:util').debuglog('plug:ts-loader')('[cjs] Loaded "%s"', ${__fileurl});`
+    }
+  }
+
+  /* Transpile our TypeScript file into some JavaScript stuff */
+  let result
+  try {
+    const source = _fs.readFileSync(filename, 'utf-8')
+    result = _esbuild.transformSync(source, options)
+  } catch (cause: any) {
+    _esbReport('error', (cause as _esbuild.TransformFailure).errors)
+    _esbReport('warning', (cause as _esbuild.TransformFailure).warnings)
+    _throw(type, `ESBuild error transpiling "${filename}"`, { cause, start: _esbTranpile })
+  }
+
+  /* Log transpile warnings if debugging */
+  if (_debug) _esbReport('warning', result.warnings)
+
+  /* Done! */
+  return result.code
+}
+
+
+/* ========================================================================== *
+ * ESM VERSION                                                                *
+ * ========================================================================== */
+
+/** The formats that can be handled by NodeJS' loader */
+type Format = 'builtin' | 'commonjs' | 'json' | 'module' | 'wasm'
+
+/* ========================================================================== */
+
+/** The type identifying a NodeJS' loader `resolve` hook. */
+type ResolveHook = (
+  /** Whatever was requested to be imported (module, relative file, ...). */
+  specifier: string,
+  /** Context information around this `resolve` hook call. */
+  context: ResolveContext,
+  /** The subsequent resolve hook in the chain, or the Node.js default one. */
+  nextResolve: ResolveNext,
+) => ResolveResult | Promise<ResolveResult>
+
+/** Context information around a `resolve` hook call. */
+interface ResolveContext {
+  importAssertions: object
+  /** Export conditions of the relevant `package.json`. */
+  conditions: string[]
+  /** The module importing this one, or undefined if this is the entry point. */
+  parentURL?: string | undefined
+}
+
+/** The subsequent resolve hook in the chain, or the Node.js default one. */
+type ResolveNext = (specifier: string, context: ResolveContext) => ResolveResult | Promise<ResolveResult>
+
+/** A type describing the required results from a `resolve` hook */
+interface ResolveResult {
+  /** The absolute URL to which this input resolves. */
+  url: string
+  /** A format hint to the `load` hook (it might be ignored). */
+  format?: Format | null | undefined
+  /** A signal that this hook intends to terminate the chain of resolve hooks. */
+  shortCircuit?: boolean | undefined
+}
+
+/* ========================================================================== */
+
+/** The type identifying a NodeJS' loader `load` hook. */
+type LoadHook = (
+  /** The URL returned by the resolve chain. */
+  url: string,
+  /** Context information around this `load` hook call. */
+  context: LoadContext,
+  /** The subsequent load hook in the chain, or the Node.js default one. */
+  nextLoad: LoadNext,
+) => LoadResult | Promise<LoadResult>
+
+/** Context information around a `load` hook call. */
+interface LoadContext {
+  importAssertions: object
+  /** Export conditions of the relevant `package.json` */
+  conditions: string[]
+  /** The format hint from the `resolve` hook. */
+  format?: ResolveResult['format']
+}
+
+/** The subsequent load hook in the chain, or the Node.js default one. */
+type LoadNext = (url: string, context: LoadContext) => LoadResult | Promise<LoadResult>
+
+/** A type describing the required results from a `resolve` hook */
+type LoadResult = {
+  /** The format of the code being loaded. */
+  format: Format
+  /** A signal that this hook intends to terminate the chain of load hooks. */
+  shortCircuit?: boolean | undefined
+} & ({
+  format: 'builtin' | 'commonjs'
+  /** When the source is `builtin` or `commonjs` no source must be returned */
+  source?: never | undefined
+} | {
+  format: 'json' | 'module'
+  /** When the source is `json` or `module` the source can include strings */
+  source: string | ArrayBuffer | NodeJS.TypedArray
+} | {
+  format: 'wasm'
+  /** When the source is `wasm` the source must not be a string */
+  source: ArrayBuffer | NodeJS.TypedArray
+})
+
+/* ========================================================================== */
+
+/**
+ * Our main `resolve` hook: here we need to check for a couple of options
+ * when importing ""
+ */
+export const resolve: ResolveHook = (specifier, context, nextResolve): ResolveResult | Promise<ResolveResult> => {
+  _log(ESM, `Resolving "${specifier}" from "${context.parentURL}"`)
+
+  /* We only resolve relative paths ("./xxx" or "../xxx") */
+  if (! specifier.match(/^\.\.?\//)) return nextResolve(specifier, context)
+
+  /* We only resolve if we _do_ have a parent URL and it's a file */
+  const parentURL = context.parentURL
+  if (! parentURL) return nextResolve(specifier, context)
+  if (! parentURL.startsWith('file:')) return nextResolve(specifier, context)
+
+  /* We only resolve here if the importer is a ".ts" or ".mts" file */
+  if (! parentURL.match(/\.m?ts$/)) return nextResolve(specifier, context)
+
+  /* The resolved URL is the specifier resolved against the parent */
+  const url = new URL(specifier, parentURL).href
+  const path = _url.fileURLToPath(url)
+
+  /*
+   * Here we are sure that:
+   *
+   * 1) we are resolving a local path (not a module)
+   * 2) the importer is a file, ending with ".ts" or ".mts"
+   *
+   * Now we can check if "import 'foo'" resolves to:
+   *
+   * 1) directly to a file, e.g. "import './foo.js'" or "import './foo.mts'"
+   * 2) import a "pseudo-JS file", e.g. "import './foo.js'" becomes "import './foo.ts'"
+   * 3) imports a file without extension as if it were "import './foo.ts'"
+   * 4) imports a directory  as in "import './foo/index.ts'"
+   *
+   * We resolve the _final_ specifier that will be passed to the next resolver
+   * for further potential resolution accordingly.
+   *
+   * We start with the easiest case: is this a real file on the disk?
+   */
+  if (isFile(path)) {
+    _log(ESM, `Positive match for "${specifier}" as "${path}" (1)`)
+    return nextResolve(specifier, context) // straight on
+  }
+
+  /*
+   * TypeScript allows us to import "./foo.js", and internally resolves this to
+   * "./foo.ts" (yeah, nice, right?) and while we normally wouldn't want to deal
+   * with this kind of stuff, the "node16" module resolution mode _forces_ us to
+   * use this syntax.
+   */
+  const match = specifier.match(/(.*)(\.[mc]?js$)/)
+  if (match) {
+    const [ , base, ext ] = match
+    const tsspecifier = base + ext!.replace('js', 'ts')
+    const tsurl = new URL(tsspecifier, parentURL).href
+    const tspath = _url.fileURLToPath(tsurl)
+
+    if (isFile(tspath)) {
+      _log(ESM, `Positive match for "${specifier}" as "${tspath}" (2)`)
+      return nextResolve(tsspecifier, context) // straight on
+    }
+  }
+
+  /* Check if the import is actually a file with a ".ts" extension */
+  if (isFile(`${path}.ts`)) {
+    _log(ESM, `Positive match for "${specifier}.ts" as "${path}.ts" (3)`)
+    return nextResolve(`${specifier}.ts`, context)
+  }
+
+  /* If the file is a directory, then see if we have an "index.ts" in there */
+  if (isDirectory(path)) {
+    const file = _path.resolve(path, 'index.ts') // resolve, as path is absolute
+    if (isFile(file)) {
+      _log(ESM, `Positive match for "${specifier}" as "${file}"  (4)`)
+      const spec = _url.pathToFileURL(file).pathname
+      return nextResolve(spec, context)
+    }
+  }
+
+  /* There's really nothing else we can do */
+  return nextResolve(specifier, context)
+}
+
+/** Our main `load` hook */
+export const load: LoadHook = (url, context, nextLoad): LoadResult | Promise<LoadResult> => {
+  _log(ESM, `Attempting to load "${url}"`)
+
+  /* We only load from disk, so ignore everything else */
+  if (! url.startsWith('file:')) return nextLoad(url, context)
+
+  /* Figure our the extension (especially ".ts", ".mts" or ".cts")... */
+  const ext = url.match(/\.[cm]?ts$/)?.[0]
+
+  /* Quick and easy bail-outs for non-TS or ".cts" (always `commonjs`) */
+  if (! ext) return nextLoad(url, context)
+
+  if (ext === '.cts') {
+    if (_debug) {
+      _log(null, `Switching type from "module" to "commonjs" for "${url}"`)
+      _log(null, 'Please note that named import WILL NOT WORK in this case, as Node.js performs a')
+      _log(null, 'static analisys on the CommonJS source code, and this file is transpiled from.')
+      _log(null, 'TypeScript to CommonJS dynamically.')
+    }
+    return { format: CJS, shortCircuit: true }
+  }
+
+  /* Convert the url into a file name, any error gets ignored */
+  const filename = _url.fileURLToPath(url)
+
+  /* If the file is a ".ts", we need to figure out the default type */
+  if (ext === '.ts') {
+    if (_type === CJS) {
+      if (_debug) {
+        _log(null, `Switching type from "module" to "commonjs" for "${url}"`)
+        _log(null, 'Please note that named import WILL NOT WORK in this case, as Node.js performs a')
+        _log(null, 'static analisys on the CommonJS source code, and this file is transpiled from.')
+        _log(null, 'TypeScript to CommonJS dynamically.')
+      }
+      return { format: CJS, shortCircuit: true }
+    }
+  }
+
+  /* Transpile with ESBuild and return our source code */
+  const source = _esbTranpile(filename, ESM)
+  return { source, format: ESM, shortCircuit: true }
+}
+
+
+/* ========================================================================== *
+ * CJS VERSION                                                                *
+ * ========================================================================== */
+
+/** The extension handler type, loading CJS modules */
+type ExtensionHandler = (module: NodeJS.Module, filename: string) => void
+
+/* Add the `_compile(...)` method to NodeJS' `Module` interface */
+declare global {
+  namespace NodeJS {
+    interface Module {
+      _compile: (contents: string, filename: string) => void
+    }
+  }
+}
+
+/**
+ * Add the `_extensions[...]` and `resolveFilename(...)` members to the
+ * definition of `node:module`.
+ */
+declare module 'node:module' {
+  const _extensions: Record<`.${string}`, ExtensionHandler>
+  function _resolveFilename(
+    request: string,
+    parent: _module | undefined,
+    isMain: boolean,
+    options?: any,
+  ): string
+}
+
+/* ========================================================================== */
+
+const loader: ExtensionHandler = (module, filename): void => {
+  _log(CJS, `Attempting to load "${filename}"`)
+
+  /* Figure our the extension (".ts" or ".cts")... */
+  const ext = _path.extname(filename)
+
+  /* If the file is a ".ts", we need to figure out the default type */
+  if (ext === '.ts') {
+    /* If the _default_ module type is CJS then load as such! */
+    if (_type === ESM) {
+      _throw(CJS, `Must use import to load ES Module: ${filename}`, { code: 'ERR_REQUIRE_ESM' })
+    }
+  } else if (ext !== '.cts') {
+    _throw(CJS, `Unsupported filename "${filename}"`)
+  }
+
+  const source = _esbTranpile(filename, CJS)
+
+  /* Let node do its thing, but wrap any error it throws */
+  try {
+    module._compile(source, filename)
+  } catch (cause) {
+    // eslint-disable-next-line no-console
+    console.error(`Error compiling module "${filename}"`, cause)
+  }
+}
+
+/* Remember to load our loader for .TS/.CTS as CommonJS modules */
+_module._extensions['.ts'] = _module._extensions['.cts'] = loader
+
+/**
+ * Replace _module._resolveFilename with our own.
+ *
+ * This is a _HACK BEYOND REDEMPTION_ and I'm ashamed of even _thinking_ about
+ * it, but, well, it makes things work.
+ *
+ * TypeScript allows us to import "./foo.js", and internally resolves this to
+ * "./foo.ts" (yeah, nice, right?) and while we normally wouldn't want to deal
+ * with this kind of stuff, the "node16" module resolution mode _forces_ us to
+ * use this syntax.
+ *
+ * And we _need_ the "node16" module resolution to properly consume "export
+ * conditions" from other packages. Since ESBuild's plugins only work in async
+ * mode, changing those import statements on the fly is out of the question, so
+ * we need to hack our way into Node's own resolver.
+ *
+ * See my post: https://twitter.com/ianosh/status/1559484168685379590
+ * ESBuild related fix: https://github.com/evanw/esbuild/commit/0cdc005e3d1c765a084f206741bc4bff78e30ec4
+ */
+const _oldResolveFilename = _module._resolveFilename
+_module._resolveFilename = function(
+    request: string,
+    parent: _module | undefined,
+    ...args: [ isMain: boolean, options: any ]
+): any {
+  try {
+    /* First call the old _resolveFilename to see what Node thinks */
+    return _oldResolveFilename.call(this, request, parent, ...args)
+  } catch (error: any) {
+    /* If the error was anything but "MODULE_NOT_FOUND" bail out */
+    if (error.code !== 'MODULE_NOT_FOUND') throw error
+
+    /* Check if the "request" ends with ".js", ".mjs" or ".cjs" */
+    const match = request.match(/(.*)(\.[mc]?js$)/)
+
+    /*
+     * If the file matches our extension, _and_ we have a parent, we simply
+     * try with a new extension (e.g. ".js" becomes ".ts")...
+     */
+    if (parent && match) {
+      const [ , name, ext ] = match
+      const tsrequest = name + ext!.replace('js', 'ts')
+      try {
+        const result = _oldResolveFilename.call(this, tsrequest, parent, ...args)
+        _log(CJS, `Resolution for "${request}" intercepted as "${tsrequest}`)
+        return result
+      } catch (discard) {
+        throw error // throw the _original_ error in this case
+      }
+    }
+
+    /* We have no parent, or we don't match our extension, throw! */
+    throw error
+  }
+}

package/extra/tsrun.mts

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+import _path from 'node:path'
+
+import { $blu, $gry, $rst, $und, $wht, main, version } from './utils.js'
+
+/** Our minimalistic help */
+function help(): never {
+  console.log(`${$blu}${$und}Usage:${$rst}
+
+  ${$wht}tsrun${$rst} ${$gry}[${$rst}--options${$gry}] script.ts [...${$rst}script args${$gry}]${$rst}
+
+  ${$blu}${$und}Options:${$rst}
+
+      ${$wht}-h --help${$rst}       Help! You're reading it now!
+      ${$wht}-v --version${$rst}    Version! This one: ${version()}!
+      ${$wht}   --force-esm${$rst}  Force transpilation of ".ts" files to EcmaScript modules
+      ${$wht}   --force-cjs${$rst}  Force transpilation of ".ts" files to CommonJS modules
+
+  ${$blu}${$und}Description:${$rst}
+
+      ${$wht}tsrun${$rst} is a minimalistic TypeScript loader, using "esbuild" to transpile TS
+      code to JavaScript, and running it. Being extremely un-sofisticated, it's
+      not meant to to be in any way a replacement for more complete alternatives
+      like "ts-node".
+`)
+
+  process.exit(1)
+}
+
+/** Process the command line */
+main((args: string[]): void => {
+  let script: string | undefined
+  let scriptArgs: string[] = []
+
+  // Parse options, leaving script and scriptArgs with our code to run
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+
+    if ((arg === '-h') || (arg === '--help')) help()
+    if ((arg === '-v') || (arg === '--version')) {
+      console.log(`v${version()}`)
+      process.exit(1)
+    }
+
+    if (arg!.startsWith('-')) {
+      console.log(`${$wht}tsrun${$rst}: Uknown option "${$wht}${arg}${$rst}"`)
+      process.exit(1)
+    }
+
+    ([ script, ...scriptArgs ] = args.slice(i))
+    break
+  }
+
+  // No script? Then help
+  if (! script) help()
+
+  // Resolve the _full_ path of the script, and tweak our process.argv
+  // arguments, them simply import the script and let Node do its thing...
+  script = _path.resolve(process.cwd(), script)
+  process.argv = [ process.argv0, script, ...scriptArgs ]
+  import(script)
+})