js-build-tools 4.0.12 → 4.1.1

package/functions/partials/tsFor.mjs

@@ -1,22 +1,86 @@
-import { dest, parallel, src } from 'gulp'
+import { dest, src } from 'gulp'
+import path from 'node:path'
 import * as gulpConfig from '../../gulp.config.mjs'
-import ts from 'gulp-typescript'
+import ts from 'typescript'
+
+// gulp-ts-compile ships ESM-only (no CJS build - see its own package.json) since it's meant to be consumed by
+// gulpfiles running under a real ESM loader, same as this project's own gulpfile.mjs does. This project also
+// compiles itself to a CommonJS build (dist/*.js, this file's own compiled counterpart) for consumers using
+// require() though, and even a dynamic `import()` gets downleveled by babel's CommonJS transform into a
+// require() call - which can't load a real ES module. Hiding the import() call inside a Function constructor is
+// the standard escape hatch: babel can't see (and so can't rewrite) an import expression that only exists as a
+// runtime-evaluated string, so it survives as a genuine dynamic import, capable of loading gulp-ts-compile from
+// either build.
+const importGulpTsCompile = new Function('return import(\'gulp-ts-compile\')')
+
+/**
+ * Wrap a stream in a promise that resolves once it finishes writing.
+ * @memberOf module:partials
+ * @param {import('node:stream').Stream} stream
+ * @returns {Promise<void>}
+ */
+const streamToPromise = (stream) => new Promise((resolve, reject) => {
+  stream.on('finish', resolve)
+  stream.on('error', reject)
+})
+
+/**
+ * Read a tsconfig.json file into real typescript.CompilerOptions values, using only TypeScript's stable, current,
+ * public config-reading API (the same one `tsc --project` itself uses internally) - never
+ * `ts.convertCompilerOptionsFromJson`, which is exactly the kind of internal/legacy surface that broke
+ * gulp-typescript when a removed API call started throwing under TypeScript 7.
+ * @memberOf module:partials
+ * @param {string} configPath - Path to a tsconfig.json file.
+ * @returns {import('typescript').CompilerOptions}
+ */
+const readCompilerOptions = (configPath) => {
+  const configFile = ts.readConfigFile(configPath, ts.sys.readFile)
+  const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path.dirname(configPath))
+  return parsedConfig.options
+}
 
 /**
  * Starting at the source directory, find all the ts files and convert them into the distribution directory.
  * @memberOf module:partials
  * @param {string|array} [srcPath='']
  * @param {string} [distPath='']
+ * @param {function(): Promise<Function>} [loadTsCompile] - Resolves the `gulp-ts-compile` default export. Real
+ * callers should never need to pass this - it exists so tests can inject a stand-in compiler, sidestepping the
+ * genuine dynamic `import()` above that this project's current CommonJS-transform-based Jest setup cannot
+ * execute without a broader (and riskier) migration to Jest's native ESM support. gulp-ts-compile's own test
+ * suite already covers real TypeScript-compile correctness - this function's own tests only need to verify its
+ * config resolution and stream wiring.
  * @returns {Function}
- * @see `https://www.typescriptlang.org/docs/handbook/gulp.html` for more info
  */
-export const tsFor = (srcPath = gulpConfig.get('typescript.from'), distPath = gulpConfig.get('typescript.to')) => {
+export const tsFor = (
+  srcPath = gulpConfig.get('typescript.from'),
+  distPath = gulpConfig.get('typescript.to'),
+  loadTsCompile = () => importGulpTsCompile().then(({ default: tsCompile }) => tsCompile)
+) => {
   if (gulpConfig.get('typescript.enabled') === false) {
     return () => {}
   }
-  const declarationProject = ts.createProject(gulpConfig.get('typescript.config'))
-  const tsProject = ts.createProject(gulpConfig.get('typescript.config'))
-  const makeDeclarations = () => src(srcPath).pipe(declarationProject()).dts.pipe(dest(distPath))
-  const compileJS = () => src(srcPath).pipe(tsProject()).js.pipe(dest(distPath))
-  return parallel(makeDeclarations, compileJS)
+  const configPath = gulpConfig.get('typescript.config')
+  // When no tsconfig.json is configured, target/module are pinned explicitly rather than left for TypeScript's
+  // own compiler defaults - those defaults have already shifted once across a TypeScript version bump in this
+  // project's own history (silently changing whether output keeps `const`/`let` or downlevels to `var`), and
+  // pinning them keeps this task's output stable across future TypeScript upgrades too. ES5/CommonJS matches
+  // what the downstream babel/browserify bundling pipeline has always assumed it receives.
+  const compilerOptions = configPath
+    ? readCompilerOptions(configPath)
+    : { declaration: true, target: ts.ScriptTarget.ES5, module: ts.ModuleKind.CommonJS, esModuleInterop: false }
+  // Accepts gulp's own callback-style task convention (an optional `done`, called once finished) rather than
+  // just returning a Promise, since callers may invoke the returned function directly with a callback instead
+  // of relying on gulp's own runner to observe a returned Promise.
+  return (done) => {
+    const compile = async () => {
+      const tsCompile = await loadTsCompile()
+      const tsResult = src(srcPath).pipe(tsCompile(compilerOptions))
+      await Promise.all([
+        streamToPromise(tsResult.dts.pipe(dest(distPath))),
+        streamToPromise(tsResult.js.pipe(dest(distPath)))
+      ])
+    }
+    return typeof done === 'function' ? compile().then(() => done(), done) : compile()
+  }
 }

package/functions/partials/tsFor.test.mjs

@@ -1,4 +1,7 @@
 import fs from 'fs'
+import { Transform, PassThrough } from 'node:stream'
+import ts from 'typescript'
+import File from 'vinyl'
 import * as setUp from '../test-helpers/setUp.mjs'
 import { tsFor } from './tsFor.mjs'
 import { countMatches } from 'test-filesystem'
@@ -10,6 +13,33 @@ const rawContents = 'export function sayHello(name: string) {\n' +
   '  return `Hello from ${name}`;\n' +
   '}'
 
+// tsFor's real implementation loads gulp-ts-compile (a genuine ESM-only package) via a dynamic import() hidden
+// from babel's static analysis - necessary for production correctness (see tsFor.mjs's own comments), but not
+// something this project's current CommonJS-transform-based Jest setup can execute without a much bigger
+// migration to Jest's native ESM support. This fake stands in for it here, doing real (not mocked-away)
+// TypeScript transpilation via `ts.transpileModule` so this test still exercises genuine compile behavior -
+// gulp-ts-compile's own test suite separately covers its whole-program/cross-file-import compile behavior.
+const fakeLoadTsCompile = () => Promise.resolve((options) => {
+  const transform = new Transform({
+    objectMode: true,
+    transform (file, enc, callback) {
+      const { outputText } = ts.transpileModule(file.contents.toString(), { compilerOptions: options })
+      jsStream.push(new File({ cwd: file.cwd, base: file.base, path: file.path.replace(/\.ts$/, '.js'), contents: Buffer.from(outputText) }))
+      callback()
+    },
+    flush (callback) {
+      jsStream.end()
+      dtsStream.end()
+      callback()
+    }
+  })
+  const jsStream = new PassThrough({ objectMode: true })
+  const dtsStream = new PassThrough({ objectMode: true })
+  transform.js = jsStream
+  transform.dts = dtsStream
+  return transform
+})
+
 beforeEach(
   () => setUp.beforeEach()
     .then(
@@ -31,7 +61,7 @@ describe('tsFor', () => {
     expect.assertions(3)
     const oldContents = fs.readFileSync(srcFile).toString()
     expect(countMatches(oldContents, 'sayHello(name: string)')).toEqual(1)
-    tsFor(srcFile, distPath)(() => {
+    tsFor(srcFile, distPath, fakeLoadTsCompile)(() => {
       expect(fs.existsSync(distPath)).toBeTruthy()
       const compiledContents = fs.readFileSync(`${distPath}/typeScript.js`).toString()
       expect(countMatches(compiledContents, 'sayHello(name)')).toEqual(1)

package/functions/testFull.mjs

@@ -1,5 +1,5 @@
 import * as gulpConfig from '../gulp.config.mjs'
-import { default as jest } from 'jest'
+import { runCLI } from 'jest'
 
 /**
  * Run all tests with jest.
@@ -13,5 +13,5 @@ export const testFull = () => {
     // The testPath must be an array of strings
     testPath = [testPath]
   }
-  return jest.runCLI(gulpConfig.get('test.options'), testPath)
+  return runCLI(gulpConfig.get('test.options'), testPath)
 }

package/functions/testFull.test.mjs

@@ -1,5 +1,5 @@
 import { testHelpers } from './testHelpers.mjs'
-import { default as jestImport } from 'jest'
+import { runCLI } from 'jest'
 import { testFull } from './testFull.mjs'
 
 const gulpConfig = testHelpers.gulpConfig
@@ -12,6 +12,6 @@ describe('testFull', () => {
   test('runs the Jest CLI with the configured options', () => {
     expect.assertions(1)
     testFull()
-    expect(jestImport.runCLI).toHaveBeenCalledWith(gulpConfig.get('test.options'), [gulpConfig.get('test.path')])
+    expect(runCLI).toHaveBeenCalledWith(gulpConfig.get('test.options'), [gulpConfig.get('test.path')])
   })
 })

package/functions/testQuick.mjs

@@ -1,5 +1,5 @@
 import * as gulpConfig from '../gulp.config.mjs'
-import { default as jest } from 'jest'
+import { runCLI } from 'jest'
 
 /**
  * Run the Jest tests for files which have been modified (based on git status).
@@ -13,5 +13,5 @@ export const testQuick = () => {
     // The testPath must be an array of strings
     testPath = [testPath]
   }
-  return jest.runCLI({ onlyChanged: true }, testPath)
+  return runCLI({ onlyChanged: true }, testPath)
 }

package/functions/testQuick.test.mjs

@@ -1,5 +1,5 @@
 import { testHelpers } from './testHelpers.mjs'
-import { default as jestImport } from 'jest'
+import { runCLI } from 'jest'
 import { testQuick } from './testQuick.mjs'
 
 const gulpConfig = testHelpers.gulpConfig
@@ -12,6 +12,6 @@ describe('testQuick', () => {
   test('runs the jest CLI with onlyChanged option', () => {
     expect.assertions(1)
     testQuick()
-    expect(jestImport.runCLI).toHaveBeenCalledWith({ onlyChanged: true }, [gulpConfig.get('test.path')])
+    expect(runCLI).toHaveBeenCalledWith({ onlyChanged: true }, [gulpConfig.get('test.path')])
   })
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-build-tools",
-  "version": "4.0.12",
+  "version": "4.1.1",
   "description": "Standardised build process with gulp.",
   "main": "gulpfile.base.js",
   "exports": {
@@ -50,28 +50,27 @@
     "@babel/plugin-transform-modules-commonjs": "^7.29.7",
     "@babel/preset-env": "^7.29.7",
     "@babel/preset-typescript": "^7.29.7",
-    "@babel/runtime-corejs3": "^7.29.7",
+    "@babel/runtime-corejs3": "^8.0.6",
     "babel-jest": "^30.4.1",
     "browserify": "^17.0.1",
     "core-js": "^3.49.0",
-    "fs": "^0.0.2",
     "glob": "^13.0.6",
     "gulp": "^5.0.1",
     "gulp-babel": "^8.1.0",
     "gulp-cache": "^1.1.3",
     "gulp-cssnano": "^2.1.3",
-    "gulp-imagemin": "^9.2.0",
+    "gulp-imagemin": "github:jheagle/gulp-imagemin#common-js-compatibility",
     "gulp-rename": "^2.1.0",
     "gulp-sass": "^6.0.1",
     "gulp-standard": "^14.0.0",
-    "gulp-typescript": "^6.0.0-alpha.1",
+    "gulp-ts-compile": "^1.0.0",
     "gulp-uglify-es": "^3.0.0",
-    "jest": "^29.7.0",
+    "jest": "^30.5.2",
     "jest-environment-jsdom": "^30.4.1",
     "jsdoc-to-markdown": "^9.1.3",
     "regenerator-runtime": "^0.14.1",
     "sass": "^1.101.0",
-    "test-filesystem": "^1.3.14",
+    "test-filesystem": "^1.5.0",
     "through2": "^4.0.2",
     "vinyl-source-stream": "^2.0.0"
   },
@@ -85,5 +84,8 @@
     "gulp.config.mjs",
     "jsdoc.base.js"
   ],
-  "funding": "https://www.paypal.com/donate/?business=LRYR6SZRWKXVY&no_recurring=0&item_name=Let%27s+build+together+today+to+simplify+our+jobs+tomorrow.&currency_code=CAD"
+  "funding": "https://www.paypal.com/donate/?business=LRYR6SZRWKXVY&no_recurring=0&item_name=Let%27s+build+together+today+to+simplify+our+jobs+tomorrow.&currency_code=CAD",
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
 }