# hooks The resolution hook that loads a workspace's TypeScript from source: the path aliases of `tsconfig.base.json`, and extensionless relative imports completed the way the compiler does. Importing the entry installs the hook for the workspace above the working directory, so one flag is all a script needs: ```bash node --import @hyperfrontend/workspace/hooks tools/scripts/report.ts ``` The command line installs the hook itself for the root it finds, which is how an executor or generator a workspace writes in TypeScript loads without any flag. [`installAliases`](https://www.hyperfrontend.dev/docs/libraries/workspace/hooks/#api-installAliases) adds another workspace root at run time, and [`installFrom`](https://www.hyperfrontend.dev/docs/libraries/workspace/hooks/#api-installFrom) finds the root above a directory first. The hook imports nothing but Node's own modules, so it works before the aliases it installs exist. ## API Reference ### Functions #### aliasTarget ```typescript function aliasTarget(sources: WorkspaceSources, specifier: string): string ``` The file an alias names. **Parameters** | Name | Type | Description | | --- | --- | --- | | `sources` | `WorkspaceSources` | The workspace whose aliases are read | | `specifier` | `string` | An import specifier | **Returns** `string`: The absolute file the alias maps to, or null when the specifier is no alias #### completeRelative ```typescript function completeRelative(specifier: string, parentFile: string): string ``` Completes an extensionless relative import the way the compiler does: the file with `.ts` or `.tsx` appended, or the directory's `index.ts`. **Parameters** | Name | Type | Description | | --- | --- | --- | | `specifier` | `string` | The import specifier | | `parentFile` | `string` | The absolute path of the importing file | **Returns** `string`: The completed absolute path, or null when the specifier is not relative, names a file as written, or completes to nothing **Example: The three completions, and the cases the hook leaves to Node** ```typescript const parent = '/repo/libs/features/src/index.ts' completeRelative('./host/open', parent) // => '/repo/libs/features/src/host/open.ts' completeRelative('./host', parent) // => '/repo/libs/features/src/host/index.ts', when host/ is a directory completeRelative('./host/open.ts', parent) // => null, the file exists as written completeRelative('@hyperfrontend/nexus', parent) // => null, not relative ``` #### formatOf ```typescript function formatOf(root: string, url: string): string ``` The module format of a URL, when this module knows it: workspace TypeScript is always an ES module, which saves Node from parsing each file twice to find out. **Parameters** | Name | Type | Description | | --- | --- | --- | | `root` | `string` | The workspace root, absolute | | `url` | `string` | The module's URL | **Returns** `string`: `module-typescript` for workspace sources, null otherwise #### homeOf ```typescript function homeOf(directory: string): string ``` The workspace a module of this package lives in as source: the one above its directory, unless the package is installed, when it belongs to no workspace's sources. **Parameters** | Name | Type | Description | | --- | --- | --- | | `directory` | `string` | The directory of the module, absolute | **Returns** `string`: The workspace root, or null for an installed package or a directory with no workspace above it #### installAliases ```typescript function installAliases(root: string): void ``` Installs the hooks for a workspace. A workspace installed twice is resolved once, and one installed after another is asked after it. **Parameters** | Name | Type | Description | | --- | --- | --- | | `root` | `string` | The workspace root, absolute | **Example: Running a workspace's TypeScript from source** ```bash node --import @hyperfrontend/workspace/hooks tools/scripts/report.ts ``` Importing the module installs the hooks for the workspace above the working directory; call `installAliases` only for a second workspace, which is asked after the first. **Example: Lending a script the aliases of another workspace** ```typescript import { installAliases } from '@hyperfrontend/workspace/hooks' installAliases('/repos/other-workspace') installAliases('/repos/other-workspace') // a second call for the same root changes nothing const { buildGraph } = await import('@other/graph') // an alias of the other workspace's tsconfig.base.json ``` #### installFrom ```typescript function installFrom(directory: string): void ``` Installs the hooks for the workspace above a directory, when there is one. **Parameters** | Name | Type | Description | | --- | --- | --- | | `directory` | `string` | Where to look from, absolute | **Example: Installing for the workspace a file belongs to** ```typescript installFrom(dirname(fileURLToPath(import.meta.url))) // finds the nearest hf.json above this file installFrom('/tmp') // does nothing: no workspace above ``` #### isWorkspaceSource ```typescript function isWorkspaceSource(root: string, file: string): boolean ``` Whether a file is workspace TypeScript whose relative imports are completed. **Parameters** | Name | Type | Description | | --- | --- | --- | | `root` | `string` | The workspace root, absolute | | `file` | `string` | An absolute path | **Returns** `boolean`: True for `.ts` and `.tsx` files inside the workspace and outside `node_modules` #### readSources ```typescript function readSources(root: string): WorkspaceSources ``` The sources of a workspace. **Parameters** | Name | Type | Description | | --- | --- | --- | | `root` | `string` | The workspace root, absolute | **Returns** `WorkspaceSources`: The root with the path aliases of its base tsconfig, none when it has no such file or the file declares none #### resolveWorkspace ```typescript function resolveWorkspace(sources: WorkspaceSources, specifier: string, parentURL: string): string ``` Resolves one specifier the way the hook does. **Parameters** | Name | Type | Description | | --- | --- | --- | | `sources` | `WorkspaceSources` | The workspace whose sources are resolved | | `specifier` | `string` | The import specifier | | `parentURL` | `string` | The importing module's URL, when there is one | **Returns** `string`: The file URL to load, or null when the hook has nothing to say **Example: An alias resolves from anywhere, a relative import only from workspace TypeScript** ```typescript const sources = readSources('/repo') resolveWorkspace(sources, '@hyperfrontend/nexus', undefined) // => 'file:///repo/libs/nexus/src/index.ts' resolveWorkspace(sources, './host', 'file:///repo/libs/features/src/index.ts') // => 'file:///repo/libs/features/src/host/index.ts' resolveWorkspace(sources, './host', 'file:///repo/node_modules/pkg/index.js') // => null resolveWorkspace(sources, 'typescript', 'file:///repo/libs/features/src/index.ts') // => null, Node resolves it ``` #### workspaceRootFrom ```typescript function workspaceRootFrom(directory: string): string ``` The workspace root above a directory. **Parameters** | Name | Type | Description | | --- | --- | --- | | `directory` | `string` | Where to start, absolute | **Returns** `string`: The nearest directory at or above it that holds the workspace file, or null when none does ### Interfaces #### WorkspaceSources The sources of one workspace, as the hook resolves them. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly root` | `string` | The workspace root, absolute. | | `readonly aliases` | `Readonly>` | The path aliases, each mapped to the source files it names, workspace-relative. | --- Canonical page: https://www.hyperfrontend.dev/docs/libraries/workspace/hooks/ This file: https://www.hyperfrontend.dev/docs/libraries/workspace/hooks.md Documentation index: https://www.hyperfrontend.dev/llms.txt