<a id="dads-frameworkpath-aliases"></a>

# `@dads-framework/path-aliases`

`@dads-framework/path-aliases` resolves the TypeScript `paths` aliases declared by one explicit tsconfig — its own, or any it inherits through `extends` — to absolute paths of files that exist. It reads through a file system port with two providers: `nodeFileSystem`, which is the disk, and `inMemoryFileSystem`, which is a map. Both are put through the same conformance suite.

<a id="what-dad-does-for-you"></a>

## What Dad does for you

Dad wants the resolution boundary written down where you can read it. You hand him one tsconfig; every alias he honors comes from that file's `paths`, and an alias shape he cannot honor exactly is a startup failure, not a quiet miss.

<a id="try-it"></a>

## Try it

The npm install below is for the public release.

From an npm project on Node.js 22 or newer, install the resolver.

```sh
npm install @dads-framework/path-aliases
```

Save the following as `resolve-alias.mts`. The in-memory file system includes both the tsconfig and its target, so the example needs no other files.

```ts
import { relative, resolve } from "node:path";
import {
  createAliasResolver,
  inMemoryFileSystem,
} from "@dads-framework/path-aliases";

const tsconfig = resolve("tsconfig.json");
const source = resolve("src/ui/button.ts");
const fileSystem = inMemoryFileSystem({
  [tsconfig]: JSON.stringify({
    compilerOptions: { paths: { "@app/*": ["./src/*"] } },
  }),
  [source]: 'export const label = "Save";',
});
const resolveAlias = createAliasResolver({ tsconfig, fileSystem });

const button = resolveAlias("@app/ui/button");
console.log(button && relative(".", button).split("\\").join("/"));
console.log(resolveAlias("react"));
```

```sh
node --experimental-strip-types resolve-alias.mts
```

The first line is `src/ui/button.ts`. The second is `null` because `react` has no entry in the alias map. For an on-disk project, pass the path of your tsconfig and `nodeFileSystem` to the same resolver.

For a disk-backed example, the repository's [domain boundaries fixture](https://dadsframework.dev/docs/source/fixtures/domain-boundaries/tsconfig.json) maps `@app/product-id` to `libraries/product-id/src/index.ts`. Pass the fixture's `tsconfig.json` and `nodeFileSystem` to resolve that import from its declared alias.

<a id="use-it"></a>

## Use it

| Export | What it is |
| --- | --- |
| `createAliasResolver({ tsconfig, fileSystem })` | builds the resolver, and refuses every configuration it cannot honor |
| `AliasResolver` | `(specifier: string) => string \| null` |
| `AliasFileSystem` | the port: `isFile`, `readText`, `resolvePackage` |
| `nodeFileSystem` | the provider over `node:fs` and `node:module` |
| `inMemoryFileSystem(files)` | the provider over a map of absolute paths to text |
| `runAliasResolverConformance({ root, fileSystem })` | the suite every provider is run through; an empty finding list is passing |
| `aliasResolverConformanceLaws()` | the twenty-five law names the suite reports under, in run order |
| `AliasFileSystemFactory`, `AliasResolverConformanceSubject`, `AliasResolverConformanceFinding` | the shapes that suite takes and answers |

Aliases may be declared on the given tsconfig or inherited through its `extends` chain, which may be a string or an array of strings and may name a relative file or a package. The config that declares `paths` is the nearest one in the chain; its targets resolve against the `baseUrl` of that config, or of the nearest config after it that sets one, or against its own directory.

Resolution probes an alias target as a file, then as a package directory whose entry point is the first of `exports`, `module`, and `main` that names an existing file, then with each supported extension and as `index.<extension>` inside it: `.ts`, `.tsx`, `.js`, `.jsx`, `.json`, `.mts`, `.mjs`, `.cts`, `.cjs`, `.css`, `.scss`, and `.less`. A specifier written with an explicit extension falls back to the matching source file, so `@app/source.js` finds `src/source.ts`. A `?suffix` query is stripped before matching.

`exports` contributes `exports["."]` when that is a string, otherwise its `import` condition and then its `default` condition; any other `exports` shape, an unreadable `package.json`, and no `package.json` at all leave `module` and `main` to answer, and then the extension and `index.<extension>` probes.

<a id="what-it-refuses-to-do"></a>

## What it refuses to do

*   **It does not load the TypeScript compiler.** The tsconfig dialect — comments, trailing commas, and strings containing either — is read by this package, so your compiler version is yours to choose, or to skip.
*   **It does not touch a disk of its own.** Every file question goes through the port, which is why the in-memory stand-in exists and why both providers run one suite.
*   **It does not discover a tsconfig.** There is no search up the directory tree and no default: the config that owns resolution is the one you named.
*   **It does not guess at an alias shape it does not support.** Two targets for one alias, more than one `*`, or a wildcard count that differs between pattern and target is a configuration-time error rather than a weaker match.
*   **It does not claim a specifier it cannot prove.** A bare specifier, an absolute path, and an alias whose target names no existing file all answer `null` and stay the caller's to resolve.
*   **It does not resolve every specifier under `baseUrl`.** An alias is honored because `paths` declares it, not because a file happens to sit beside the ones that are declared.

<a id="contract"></a>

## Contract

`createAliasResolver(options: AliasResolverOptions): AliasResolver`, where `AliasResolverOptions` is `{ readonly tsconfig: string; readonly fileSystem: AliasFileSystem }`. The resolver answers an absolute file path for a specifier it owns and `null` for everything else.

Every failure below is thrown while the resolver is being built — configuration time, not resolve time — so a broken alias map fails the run instead of silently resolving less:

| Message | When |
| --- | --- |
| `Dads path aliases requires a non-empty tsconfig path.` | `tsconfig` is blank |
| `Dads path aliases tsconfig is not a readable file: <path>` | The named tsconfig is not a readable file |
| `Unable to read Dads path aliases tsconfig <path>: <detail> at line <l>, column <c>` | A config in the chain is unreadable or is not valid JSONC |
| `Dads path aliases tsconfig <path> does not declare or inherit compilerOptions.paths.` | No aliases were found |
| `Dads path alias <pattern> in <path> must have exactly one target.` | An alias maps to zero, several, or one unusable target |
| `Dads path alias <pattern> in <path> must use zero or one matching wildcard.` | Wildcards exceed one, or do not match |
| `Dads path aliases supports tsconfig extends only as a string or string array.` | `extends` is some other shape |
| `Dads path aliases cannot resolve tsconfig extends <target> from <path>.` | A relative `extends` names no file |
| `Dads path aliases cannot resolve tsconfig package <name> from <path>.` | A package `extends` cannot be resolved |
| `Dads path aliases found a circular tsconfig extends chain at <path>.` | The `extends` chain revisits a config |

`runAliasResolverConformance` answers a list of findings and throws nothing; an empty list is conformance. Each finding names the case, the law, and what the provider did instead. A subject is `{ root, fileSystem }`, where `root` is an absolute directory the suite builds its fixtures under and `fileSystem` builds a provider serving exactly the files it is handed.

The package requires Node.js 22 or newer and has no dependencies at all.

<a id="daddy-issues-this-prevents"></a>

## Daddy issues this prevents

Alias resolution is where a build quietly stops matching the type checker: the compiler follows one map, the test runner follows another, and the disagreement only shows up as an import that works everywhere except in CI. One named config, one map, and a loud failure when it cannot be honored.

Canonical page: <https://dadsframework.dev/docs/package-path-aliases>
