@itrocks/parameter-name 0.0.3 → 0.0.4

package/README.md

@@ -7,3 +7,136 @@
 # 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.

package/package.json

@@ -29,8 +29,11 @@
 	"keywords": [
 		"backend",
 		"constructor",
+		"decorator",
+		"dts",
 		"function",
 		"it.rocks",
+		"metadata",
 		"method",
 		"name",
 		"parameter",
@@ -38,6 +41,7 @@
 		"parse",
 		"parsing",
 		"reflection",
+		"typescript",
 		"utility"
 	],
 	"license": "ISC",
@@ -52,5 +56,5 @@
 		"build:esm": "tsc -p tsconfig.esm.json"
 	},
 	"types": "./esm/parameter-name.d.ts",
-	"version": "0.0.3"
+	"version": "0.0.4"
 }