npm package: @salama/hot-import
Description: Pure hot module reloading for TypeScript/JavaScript projects
Author: Extracted from WebdriverIO Hot Reload Service
Latest version: 1.1.2

# @salama/hot-import

Pure hot module reloading for TypeScript/JavaScript projects with zero framework dependencies.

## Features

- ✅ **Zero Dependencies** - Only uses Node.js built-ins
- ✅ **Framework Agnostic** - Works with any TS/JS project  
- ✅ **Transparent Proxies** - Always reference latest module versions
- ✅ **Circular Import Safe** - Handles circular dependencies properly
- ✅ **Cross Platform** - Windows and Unix path handling
- ✅ **Cache Busting** - Automatic timestamp-based cache invalidation
- ✅ **TypeScript Support** - Runtime TypeScript compilation with full type safety
- ✅ **Direct .ts imports** - No pre-compilation required

## Installation

```bash
npm install @salama/hot-import
```

## Basic Usage

```typescript
import { hotImport } from '@salama/hot-import';

// Your imports automatically become "hot" - they always reference the latest version
const { MyClass } = await hotImport('./myModule.js', import.meta.url);

// MyClass always points to the latest version when file changes
const instance = new MyClass();
```

## API

### `hotImport<T>(modulePath: string, importerMetaUrl: string): Promise<T>`

Import a module with hot reloading capability.

- `modulePath` - Relative path to the module
- `importerMetaUrl` - Use `import.meta.url` from the calling file
- Returns a proxy that always references the latest module exports

### `refreshModule(modulePath: string, importerMetaUrl: string): Promise<void>`

Manually refresh a specific module.

### `notifyFileChanged(filePath: string): Promise<void>`

Notify the system that a file has changed (for file watcher integration).

### `moduleRegistry: Map<string, ModuleInfo>`

Access to the internal module registry for debugging.

## Example

### JavaScript Files
```typescript
// math.js
export class Calculator {
  add(a, b) {
    return a + b;
  }
}

// main.js
import { hotImport } from '@salama/hot-import';

const { Calculator } = await hotImport('./math.js', import.meta.url);
const calc = new Calculator();

// When you modify math.js, Calculator automatically uses the new version
console.log(calc.add(2, 3)); // Always uses latest implementation
```

### TypeScript Files (NEW!)
```typescript
// math.ts
export class Calculator {
  add(a: number, b: number): number {
    return a + b;
  }
  
  multiply(a: number, b: number): number {
    return a * b;
  }
}

// main.ts
import { hotImport } from '@salama/hot-import';

// Direct .ts import - compiles automatically!
const { Calculator } = await hotImport('./math.ts', import.meta.url);
const calc = new Calculator();

// When you modify math.ts, Calculator automatically recompiles and updates
console.log(calc.add(2, 3)); // 5
console.log(calc.multiply(4, 5)); // 20
```

## File Watcher Integration

```typescript
import { notifyFileChanged } from '@salama/hot-import';
import { watch } from 'fs';

watch('./src', { recursive: true }, (eventType, filename) => {
  if (filename && (filename.endsWith('.js') || filename.endsWith('.ts'))) {
    notifyFileChanged(filename);
  }
});
```

## License

MIT