Add an intrinsic "module reference" types that allow definition of type-checked module path strings and return types

[bradzacher]

Suggestion

🔍 Search Terms

module reference intrinsic type

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

Background

In the ecmascript ecosystem it's not uncommon to have tools that accept one or more paths to TS module files. For example when working with jest mocks you might define a mock to patch some behaviour and require the non-mocked module to maintain the rest of the module:

jest.mock('../my-module', () => {
  const originalModule = jest.requireActual('../my-module');
  return {
    ...originalModule,
    getRandom: jest.fn(() => 10),
  };
});

There is also usecases outside outside of tests for custom wrapper APIs to do manage importing of files. For example one could create an API like importDeferred which causes a bundler to bundle the dependency in a specific way.

The unfortunate problem with these sorts of APIs in TS is that there's no way to statically type the input or output - the module paths are typed as string and the return values are typed as any/unknown, or even worse they leverage the "type parameter in a return location only" antipattern (function importDeferred<T>(string): T -> importDeferred<{ trustMe: 'lol' }>('./module')).

Instead these patterns just rely upon bundle-time or runtime validation to catch mistakes - which is a frustrating break in the workflow.

There are some difficulties that exist in ensuring return types are also correct. For example in the above jest mock case - if we were to refactor ../my-module so that it no longer exports a getRandom function - then our test will not fail, and our types will validate fine - the only way to get around this currently is to manually import the module type and then to explicitly type the return:

import type * as MyModuleType from '../my-module';

jest.mock('../my-module', (): MyModuleType => { /* ... */ });

Which works, but is a bit cumbersome.

Proposal

I propose that TypeScript add the following intrinsic type: type ModuleReference<T> = intrinsic;
This intrinsic type would accept string literals (or variables typed as ModuleReference<T>) and those string literals would be validated by the type system to be a valid path using the exact same logic used to validate import statements/expressions.

The generic type parameter specifies the expected module shape based on the resolution of the path. For example the import expression could be defined as follows:

declare function import<T>(ref: ModuleReference<T>): Promise<T>;

Use Cases

Jest

And the jest APIs could be defined as follows:

declare const jest: {
  requireActual: <T>(ref: ModuleReference<T>) => T;
  mock: <T>(ref: ModuleReference<T>, mockCb: () => T): void;
};

APIs that expect explicit module shapes

One could also define an API that expects a certain shape for the module:

async function requirePlugin<T extends { doThing: () => void }>(
  ref: ModuleReference<T>,
): void {
  const plugin = await import(ref);
  plugin.doThing();
}

Module APIs

It also opens the door for augmenting the module:

async function augmentModule<T extends object>(
  ref: ModuleReference<T>,
): Promise<T & { augmentation: string }> {
  const mod = await import(ref);
  return {
    ...mod,
    augmentation: 'woo hoo!',
  };
}

Feature Gating / Conditional Imports

At several companies I've also seen experimentation / feature gating implemented in tooling with APIs that look like this:

const module = await importGated('feature_gate_name', {
  pass: './module1',
  fail: './module2',
});

Which could be defined like:

declare function importGated<T>(featureGateName: string, modules: {
  pass: ModuleReference<T>,
  fail: ModuleReference<NoInfer<T>>,
}): Promise<T>;

Or they have APIs that look like this:

const maybeModule = featureGate('feature_gate_name') ? await import('./module') : null;

Which could be improved with these types to

declare function conditionalImport<T>(
  featureGateName: string,
  ref: ModuleReference<T>,
): Promise<T> | null;

const maybeModule = await conditionalImport('feature_gate_name', './module');

A big win I see from this is that it would allow TS to type NodeJS's require function - which would be a big win for codebases that leverage require as an "inline synchronous import" (which is still a very common pattern).

Finally the TypeScript LSP could also recognise strings that are typed with ModuleRef and provide "go to definition" for these string literals, just like they would with import statements/expressions. This would be a big win for DevX.

Prior Art

Whilst it's not documented externally there is an existing system built into flow.
Flow declares the $Flow$ModuleRef type which pairs with the haste_module_ref_prefix config flag to allow you to do the same thing (specifically when using the haste module resolver).

For example internally at Meta the codebase declares various "require" functions that do different things in the build system and accept string literals that are checked by flow to be valid module references.

The haste_module_ref_prefix option defines a prefix that must exist on the string literals before flow will validate them. IIRC this exists because the build tools that predated flow are single-file only and the prefix allowed them explicitly pick out the module path strings and validate them.
For example in the Meta codebase haste_module_ref_prefix='m#' - so you see code like requireDeferred('m#MyModule').

It's up to the team as to whether such a system would be required - it does have the added bonus of making it trivial for tools to understand what string literals are module reference purely based on quick regex check as opposed to needing to be fully type-aware.

[RyanCavanaugh]

This seems like an enormous lift compared to the workaround (which looks pretty straightforward as far as things go). The current roadblocks as I see them:

• Compilation in TS is phased; we cannot get new source files mid-compilation. Once the set of files is fixed, there's no mechanism to change them
• The above is not just a technical problem, it's a determinism problem, since answers to type questions can change as a result of new files appearing
• There are at least 4 different kinds of module resolution ([CJS, ESM] <-> [CJS, ESM]) that can be kicked off by something we'd all call an "import" and there'd probably have to be direct forms for each of them plus forms that infer from the current file context (what is the current file context?)
• Many build tools take a dependency on the fact that the list of input files can be statically determined without having to write an entire typechecker, which this would violate
• Interpretation of relative paths in indirected situations seems extremely difficult to reason about. If I call require<"./foo">() from "./src but require is defined in "./utils", am I looking for ./src/foo or ./utils/foo ? Seems like there are strong arguments for both. But what happens if "./foo", the string literal type, is from another file? Double-indirection would work differently in that case?

[bradzacher]

Compilation in TS is phased; we cannot get new source files mid-compilation. Once the set of files is fixed, there's no mechanism to change them

Ah - so to clarify:
This means that once you determine the set of files by parsing and scanning for imports, the set of files is fixed. However this system (as specified) would not be statically determinable from the AST and would require type info - which means the dependencies added by the ModuleReference strings can currently only be resolved later in the pipeline.

I guess that using a flow-style prefix would then make it statically determinable and thus allow us to hoist the resolution to the earlier phase - but it wouldn't really let us describe existing APIs that don't expect some form of prefix.

There's probably a way to solve this using a new keyword or something - but I know the team wants to avoid adding new expression-level elided keywords where possible because it complicates the ecosystem.

---

Many build tools take a dependency on the fact that the list of input files can be statically determined without having to write an entire typechecker, which this would violate

Would this technically violate that requirement?
I would say no because technically this creates a type-only dependency (which is more like an implicit dependency) and the tools will or won't continue handling these custom dependency APIs in the same way they were in the past.

Put another way - if I define an API like this with the new types:
declare function customRequire<T>(ref: ModuleRef<T>): T
I could similarly declare the same function like this without it:
declare function customRequire<T>(ref: string): T

I wouldn't expect a build tool would treat that custom API as introducing a dependency in either case because it's a non-standard API - types or otherwise.

Put another way - if I design a webpack plugin around my customRequire function - I wouldn't expect I'd be able to switch to esbuild and have it "just work".

---

There are at least 4 different kinds of module resolution ([CJS, ESM] <-> [CJS, ESM]) that can be kicked off by something we'd all call an "import" and there'd probably have to be direct forms for each of them plus forms that infer from the current file context

To clarify - right now the choice of resolution style comes from the "import style" (import from vs import =) plus the file context (cts vs mts).

That's an interesting thing to consider - I wonder if adding two intrinsics would help so that authors could explicitly choose the type of resolution they expect base on the low-level APIs they use.
For example you might use ESMModuleReference<T> if you are passing to import(), but CJSModuleReference<T> if you are passing to require().
That would add some complexity to the solution but would remove the ambiguity, at least.

---

Interpretation of relative paths in indirected situations seems extremely difficult to reason about.

My personal take is KISS and it's all relative to the current module, just like it would if I was using the current import statement/expressions.
I guess I could understand that people might like it to be relative to the function declaration's module instead - and maybe that's something that could be encoded into the types somehow.

I could probably see value in separating out "relative paths" from "module system paths" (eg node_modules paths) from "tsconfig paths" with separate types and then having consumers do unions of the types to declare the spaces they care about.
You could probably also define a type like ModuleReferenceRelativeTo<TBaseDir, TMod> that allows authors to strictly define what TS should use as the base to resolve from.

I think for this first iteration we could look to keep it simple and just say "this type solely uses import semantics and we'll gather feedback and usecases for additional functionality to expand the system in a future version". But I also understand you'd want to nut out a solid baseline to start with to prevent breaking changes.

[fatcerberus]

nut out a solid baseline

Phrasing!

[LeonxLJX]

I'd like to take this one. This is the missing sibling of import('x') — TS already has call/construct signatures ((...args)=>Promise<T>), construct (new (...)), and import (import(...)), but no first-class string-literal module path type. The proposal wants import.meta.resolve / import x from 'y' to bind the literal at the type level so a typo or refactor breaks the build.

Root cause (design gap). TS treats module specifiers as opaque strings; the only typing comes from the resolver (which produces typeof import('x')). If x is a string variable, TS resolves it via paths/baseUrl and you lose all editor tooling — go-to-def, rename, find-refs. An intrinsic type ModuleReference<'./foo'> would let you write const x: ModuleReference<'./foo'> = './foo' and get full tooling for the literal portion, while still being usable as a value.

Alternatives I considered: (a) Branded primitive type ModulePath<T extends string> = T & { __modulePath: never } (works without compiler changes, no tooling). (b) The intrinsic (full tooling, requires a PR to checker.ts). (c) Const-template helper in ts-toolbelt (userland only).

Suggestion to maintainer: I'd go (a) as a stopgap for ts-toolbelt, then (b) as a separate proposal. (b) is a ~50-line checker change plus LSP plumbing. Two questions: (i) does the type need to be callable as () => typeof import(T) (lazy import), or just a value-level string with tooling? (ii) Should it propagate across import.meta.hot.accept / import() — i.e. is the type strictly 'string literal', or does it need to support the dynamic-import shape? (claiming via LeonxLJX)

[vikr01]

The AI generated comments above are annoying...

But I do think this is a much needed feature and long past due. Flow has supported this for years.

Now in the age of AI agents, we keep seeing slop code with broken module paths or paths that break because a future agent decided to move modules around without updating reference files.

Ryan Cavanaugh (@RyanCavanaugh) - what can we do to get this feature change accepted? I think a plugin architecture for this would be great.

I can also vouch that Brad Zacher (@bradzacher) was the static analysis guru at Facebook, and if he were still there would integrate it across the typescript codebases. If this feature gets in, I plan to get Snowflake to integrate it fully