@hyperfrontend/workspace/hooks

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:

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 adds another workspace root at run time, and 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

§function

aliasTarget(sources: WorkspaceSources, specifier: string): string

The file an alias names.
Parameters
NameTypeDescription
§sources
WorkspaceSourcesThe workspace whose aliases are read
§specifier
stringAn import specifier
Returns
string
The absolute file the alias maps to, or null when the specifier is no alias
§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
NameTypeDescription
§specifier
stringThe import specifier
§parentFile
stringThe 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

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
§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
NameTypeDescription
§root
stringThe workspace root, absolute
§url
stringThe module's URL
Returns
string
module-typescript for workspace sources, null otherwise
§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
NameTypeDescription
§directory
stringThe directory of the module, absolute
Returns
string
The workspace root, or null for an installed package or a directory with no workspace above it
§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
NameTypeDescription
§root
stringThe workspace root, absolute
Examples

Running a workspace's TypeScript from source

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.

Lending a script the aliases of another workspace

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
§function

installFrom(directory: string): void

Installs the hooks for the workspace above a directory, when there is one.
Parameters
NameTypeDescription
§directory
stringWhere to look from, absolute
Example

Installing for the workspace a file belongs to

installFrom(dirname(fileURLToPath(import.meta.url))) // finds the nearest hf.json above this file
installFrom('/tmp') // does nothing: no workspace above
§function

isWorkspaceSource(root: string, file: string): boolean

Whether a file is workspace TypeScript whose relative imports are completed.
Parameters
NameTypeDescription
§root
stringThe workspace root, absolute
§file
stringAn absolute path
Returns
boolean
True for .ts and .tsx files inside the workspace and outside node_modules
§function

readSources(root: string): WorkspaceSources

The sources of a workspace.
Parameters
NameTypeDescription
§root
stringThe 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
§function

resolveWorkspace(sources: WorkspaceSources, specifier: string, parentURL: string): string

Resolves one specifier the way the hook does.
Parameters
NameTypeDescription
§sources
WorkspaceSourcesThe workspace whose sources are resolved
§specifier
stringThe import specifier
§parentURL
stringThe 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

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
§function

workspaceRootFrom(directory: string): string

The workspace root above a directory.
Parameters
NameTypeDescription
§directory
stringWhere to start, absolute
Returns
string
The nearest directory at or above it that holds the workspace file, or null when none does

◈ Interfaces

§interface

WorkspaceSources

The sources of one workspace, as the hook resolves them.
Properties
§readonly root:stringThe workspace root, absolute.
§readonly aliases:Readonly<Record<string, unknown>>The path aliases, each mapped to the source files it names, workspace-relative.