class-file

Retrieve the absolute file path of an imported class.

Required setup depends on the module system:

• Automatic for CommonJS-compiled projects once the automation module is imported,
• Using an explicit @File decorator in ESM-compiled projects.

The file path can then be retrieved using fileOf(ClassName) or fileOf(object).

Installation

npm install @itrocks/class-file

Activation

This library associates each imported class with the absolute file path where it is defined. Its behavior differs depending on the module compilation mode:

CommonJS: Recommended for most use cases.
Add this line to the very start of your main file:

import '@itrocks/class-file/automation'

or:

require('@itrocks/class-file/automation')

This enables automatic file path resolution for all subsequently imported classes.

ESModule: Requires manual setup.
Due to the limitations of ESM, you must explicitly decorate classes with the @File(fileURLToPath(import.meta.url)) decorator to enable file path resolution. Without applying this decorator, fileOf(target) will return undefined.

Example

Given a file my-class.js, with CommonJS transpilation:

export class MyClass {}

Or when transpiled as an ESModule:

import { File }          from '@itrocks/class-file'
import { fileURLToPath } from 'node:url'

@File(fileURLToPath(import.meta.url))
export class MyClass {}

Retrieving the file path:

// Required only for CommonJS transpilation:
import '@itrocks/class-file/automation'

import { fileOf }  from '@itrocks/class-file'
import { MyClass } from './my-class.js'

console.log(fileOf(MyClass))       // Returns the absolute file path
console.log(fileOf(new MyClass))   // Also returns the absolute file path

API

@File

Decorator used to associate a class with its defining file path (required in ESM).

Parameters:

• path: string — typically fileURLToPath(import.meta.url).

Effect:

Registers the decorated class so that fileOf(target) can resolve its file path.

Example: (ESM)

import { File }          from '@itrocks/class-file'
import { fileURLToPath } from 'node:url'

@File(fileURLToPath(import.meta.url))
export class MyClass {}

fileOf

Returns the absolute file path of a class (constructor) or an instance (object).

Parameters:

• target: a class (constructor) or an object instance.

Returns:

• string | undefined: the absolute file path, or undefined when unavailable.

The file path is unavailable for an unregistered class, for example when the ESM decorator is missing.

Notes:

• In CommonJS, classes are registered automatically once @itrocks/class-file/automation is imported before other imports.
• In ESM, each class must be explicitly decorated with @File(...) (see above).

Example:

import '@itrocks/class-file/automation'
import { fileOf } from '@itrocks/class-file'

console.log(fileOf(MyClass))
console.log(fileOf(new MyClass()))

@itrocks/class-file/automation

(CommonJS only)

Side-effect module that enables automatic class registration for CommonJS builds.

Usage:

Must be imported (or required) before importing the classes you want to resolve.

Example:

import '@itrocks/class-file/automation'

or:

require('@itrocks/class-file/automation')