Lab Transform TypeScript

Common errors

• Error: Cannot find module 'typescript' from 'node_modules/lab-transform-typescript'

  cause `typescript` is a peer dependency and was not installed in the consuming project.
  fix `npm install typescript --save-dev` to add `typescript` to your project's development dependencies.

• SyntaxError: Unexpected token 'import' (or 'export') when running tests.

  cause This typically occurs if `lab` is trying to run a TypeScript file directly without the transform, or if the transform is misconfigured.
  fix Ensure `lab --transform node_modules/lab-transform-typescript` is correctly specified in your test command and that the path to the transform is accurate. Also, ensure `lab` itself is configured to process the correct file extensions (e.g., `.ts`).

• TSCONFIG environment variable ignored or tsconfig.json not found.

  cause The `TSCONFIG` environment variable might be incorrectly set, or TypeScript's default `tsconfig.json` search (which the transform uses since v3.0.0) isn't finding the desired file.
  fix Double-check the path provided to `TSCONFIG`. Ensure the `tsconfig.json` file exists at the specified path or in a location where TypeScript's default search mechanism would find it (e.g., project root). Ensure you are on `lab-transform-typescript` v3 or newer for this feature.

Warnings

• breaking Version 3.0.0 switched to TypeScript's official configuration loader and parser. This might affect how `tsconfig.json` files are resolved and parsed, especially in complex project setups.
  Fix: Review your `tsconfig.json` and ensure it's compatible with TypeScript's standard parsing. The `TSCONFIG` environment variable can be used to explicitly override the `tsconfig.json` location.
• breaking Version 2.0.0 moved `typescript` from `dependencies` to `peerDependencies`. This means `typescript` is no longer automatically installed by `lab-transform-typescript` and must be explicitly installed by the consuming project.
  Fix: Ensure `typescript` is installed as a `devDependency` in your project (`npm install typescript --save-dev`). The version of `typescript` used will be the one from your project's `node_modules`.
• gotcha When using `lab --coverage` with `lab-transform-typescript`, the coverage report may display transpiled JavaScript code instead of the original TypeScript source, making it harder to interpret results in terms of the original source.
  Fix: There is no direct fix for this known issue (#1 in the project's issue tracker, linked to `hapijs/lab#614`). It's a limitation of how `lab` processes transformed output for coverage.
• gotcha The version of `typescript` used by the transform depends on how `lab-transform-typescript` itself is installed. If linked via `npm link`, it uses its own `node_modules` `typescript` version; otherwise, it uses the `typescript` from the project's `node_modules`.
  Fix: For consistent behavior, install `lab-transform-typescript` directly via `npm install --save-dev` rather than `npm link` in production or shared development environments, ensuring `typescript` is a direct `devDependency` of your project.

Install

• npm install lab-transform-typescript npm
• yarn add lab-transform-typescript yarn
• pnpm add lab-transform-typescript pnpm

Imports

• transformFunction
  wrong:

  import transform from 'lab-transform-typescript';

  correct:

  const transform = require('lab-transform-typescript');

  The package's main export is a CommonJS function, directly assignable to a variable. While Node.js ESM can often import CJS defaults, explicit `require` is the guaranteed correct way for direct programmatic usage in CJS environments.
• LabCLIUsage

  /* No JS import; used via CLI: */
  lab --sourcemaps --transform node_modules/lab-transform-typescript

  The primary and most common way developers 'use' this package is by configuring the `lab` CLI to apply it as a transform, not by importing its symbols into userland JavaScript/TypeScript code.
• TypeScriptTypes
  wrong:

  import { LabTypings } from 'lab-transform-typescript/typings-local/lab.d.ts'

  correct:

  /* No direct JS import for these types; they are installed separately */

  While `lab-transform-typescript` provides typings for `lab` and `code`, these are installed via `typings install` from specific GitHub paths and are not directly imported from the `lab-transform-typescript` npm package itself. This entry highlights the *availability* of these types, not a direct programmatic import from this package.

Quickstart

Demonstrates installation and configuration of `lab-transform-typescript` to enable direct execution of TypeScript test files using the `lab` CLI.

npm install --save-dev lab-transform-typescript typescript

// In a TypeScript test file (e.g., test/example.test.ts):
// import { expect } from '@hapi/code';
// import { describe, it } from '@hapi/lab';

// describe('My Test Suite', () => {
//   it('should pass', () => {
//     expect(1 + 1).to.equal(2);
//   });
// });

// To run tests, execute in your terminal:
// (Ensure 'lab' is installed globally or in node_modules/.bin)
process.env.TSCONFIG = process.env.TSCONFIG ?? './tsconfig.json'; // Optional: specify tsconfig path
console.log(`Running tests with lab transform and TSCONFIG: ${process.env.TSCONFIG}`);
// Execute this command via package.json 'test' script or directly if lab is global:
// lab --sourcemaps --transform node_modules/lab-transform-typescript --verbose
// To make it runnable in a script: 
// const { spawn } = require('child_process');
// const lab = spawn('npx', [
//   'lab',
//   '--sourcemaps',
//   '--transform',
//   'node_modules/lab-transform-typescript',
//   '--verbose',
//   'test/**/*.ts' // Example glob for test files
// ], { stdio: 'inherit' });
// lab.on('close', (code) => process.exit(code));