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

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

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:

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.

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.