@itrocks/parameter-name
Version:
Runtime parameter name reflection from TypeScript declaration files
143 lines (107 loc) • 5.19 kB
Markdown
[](https://www.npmjs.org/package/@itrocks/parameter-name)
[](https://www.npmjs.org/package/@itrocks/parameter-name)
[](https://github.com/itrocks-ts/parameter-name)
[](https://github.com/itrocks-ts/parameter-name/issues)
[](https://25.re/ditr)
# parameter-name
Runtime parameter name reflection from TypeScript declaration files.
*This documentation was written by an artificial intelligence and may contain errors or approximations.
It has not yet been fully reviewed by a human. If anything seems unclear or incomplete,
please feel free to contact the author of this package.*
## Installation
```bash
npm i @itrocks/parameter-name
```
## Usage
`@itrocks/parameter-name` provides a single function
`parameterNamesFromFile(fileName, className, methodName)` that reads the
corresponding TypeScript declaration file (`.d.ts`) and returns the list
of parameter names for a given class constructor or method.
It is typically used by other `@itrocks/*` packages to implement
decorators that need to know the **names** of constructor parameters at
runtime (for example to bind data, build forms, or perform dependency
injection), but you can also call it directly in your own code.
> **Important:** the function expects a `.d.ts` file to exist next to the
> runtime file, with the same base name. For example, if
> `fileName` is `/dist/user.js`, then a matching
> `/dist/user.d.ts` file must be present.
### Minimal example
```ts
import { parameterNamesFromFile } from '@itrocks/parameter-name'
const parameterNames = parameterNamesFromFile(
'/absolute/path/to/dist/user.js',
'User',
'constructor'
)
// e.g. ['id', 'email', 'displayName']
console.log(parameterNames)
```
With the following declaration in the TypeScript `.d.ts` file:
```ts
declare class User {
constructor(id: number, email: string, displayName?: string)
}
```
the call above will return `['id', 'email', 'displayName']`.
### Complete example with runtime resolution
In a more realistic scenario, you compute the file name from the
location of the running module and use the parameter names inside your
own reflection or binding logic.
```ts
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { parameterNamesFromFile } from '@itrocks/parameter-name'
// Example class defined in this module
export class User {
constructor(id: number, email: string, isAdmin = false) {}
}
function parameterNamesOfUserConstructor(): string[] {
// Compute the compiled file path (e.g. dist/user.js)
const fileName = fileURLToPath(import.meta.url)
return parameterNamesFromFile(
fileName,
'User',
'constructor'
)
}
const names = parameterNamesOfUserConstructor()
// ['id', 'email', 'isAdmin']
console.log('User constructor parameters:', names)
```
You can then reuse `names` to automatically map user input, define
validation rules, or build a debug/logging helper that displays argument
names alongside their values.
## API
### `function parameterNamesFromFile(fileName: string, className: string, methodName: string): string[]`
Reads the TypeScript declaration file (`.d.ts`) corresponding to the
given `fileName` and extracts the parameter names of a specific class
constructor or method.
#### Parameters
- `fileName` – path to the compiled JavaScript file whose declaration
file you want to inspect. The function automatically replaces the
extension with `.d.ts` and reads that file. A matching declaration file
must exist.
- `className` – the exact name of the class as it appears in the
declaration file.
- `methodName` – name of the method whose parameters you want to read.
Use `'constructor'` to retrieve constructor parameter names.
#### Return value
- `string[]` – ordered list of parameter names. If a parameter does not
have a simple identifier name (for example a destructured parameter),
its entry in the array will be an empty string.
#### Notes and limitations
- Only **class declarations** are supported; free functions are not
inspected.
- The package relies on `.d.ts` files generated by the TypeScript
compiler. If those files are missing or out of sync with the runtime
code, the result may be incomplete or empty.
## Typical use cases
- Implement decorators that infer constructor parameter names at runtime
to bind values or perform dependency injection.
- Generate forms or validation schemas by matching parameter names with
metadata or user input fields.
- Build debugging helpers that log both parameter names and values when
methods or constructors are called.
- Create small reflection utilities in other `@itrocks/*` packages or in
your own framework code, without having to manually parse TypeScript
declaration files yourself.