npm package: @scriptdb/pmr
Description: Plugins module resolver for script database
Latest version: 1.0.0

# @scriptdb/pmr

Plugins Module Resolver for the script database, providing dynamic plugin loading and resolution capabilities.

## Features

- **Dynamic plugin loading**: Load plugins from directories at runtime
- **Module resolution**: Automatically resolve and import plugin modules
- **Plugin discovery**: Discover plugins in specified directories
- **Type-safe**: Full TypeScript support with type definitions

## Installation

```bash
bun add @scriptdb/pmr
```

## Quick Start

```typescript
import { PluginModuleResolver } from '@scriptdb/pmr';

// Resolve plugins from a directory
const plugins = await PluginModuleResolver('./plugins');

// Use the loaded plugins
console.log(plugins);
```

## API Reference

### PluginModuleResolver(basePath)

Resolves and loads plugins from the specified directory.

```typescript
await PluginModuleResolver(basePath: string): Promise<any>
```

- `basePath` (string): The base directory path where plugins are located

Returns a promise that resolves with the loaded plugins.

## Plugin Structure

To be compatible with the Plugin Module Resolver, your plugin directory should follow this structure:

```
plugins/
├── index.ts          # Main plugin entry point
└── plugin-files...   # Additional plugin files
```

The `index.ts` file should export a `plugins()` function:

```typescript
// plugins/index.ts
export async function plugins() {
  return {
    // Plugin exports
    hello: () => console.log('Hello from plugin!'),
    add: (a: number, b: number) => a + b
  };
}
```

## Examples

### Basic Plugin Loading

```typescript
import { PluginModuleResolver } from '@scriptdb/pmr';

// Load plugins from the ./my-plugins directory
const plugins = await PluginModuleResolver('./my-plugins');

// Use plugin functions
if (plugins.hello) {
  plugins.hello(); // "Hello from plugin!"
}

if (plugins.add) {
  const sum = plugins.add(5, 3); // 8
  console.log(sum);
}
```

### Plugin with Dependencies

```typescript
// plugins/calculator/index.ts
export async function plugins() {
  return {
    add: (a: number, b: number) => a + b,
    subtract: (a: number, b: number) => a - b,
    multiply: (a: number, b: number) => a * b,
    divide: (a: number, b: number) => a / b
  };
}

// main.ts
import { PluginModuleResolver } from '@scriptdb/pmr';

const calc = await PluginModuleResolver('./plugins/calculator');

console.log(calc.add(5, 3));       // 8
console.log(calc.subtract(5, 3));  // 2
console.log(calc.multiply(5, 3));  // 15
console.log(calc.divide(15, 3));   // 5
```

### Advanced Plugin with Configuration

```typescript
// plugins/database/index.ts
interface DatabaseConfig {
  host: string;
  port: number;
  name: string;
}

let config: DatabaseConfig | null = null;

export async function plugins() {
  return {
    configure: (options: DatabaseConfig) => {
      config = options;
    },
    connect: () => {
      if (!config) {
        throw new Error('Database not configured. Call configure() first.');
      }
      // Database connection logic here
      return `Connected to ${config.host}:${config.port}/${config.name}`;
    }
  };
}

// main.ts
import { PluginModuleResolver } from '@scriptdb/pmr';

const db = await PluginModuleResolver('./plugins/database');

db.configure({
  host: 'localhost',
  port: 5432,
  name: 'mydb'
});

console.log(db.connect()); // "Connected to localhost:5432/mydb"
```

## Error Handling

The Plugin Module Resolver will throw an error if:

- The specified directory doesn't exist
- The index.ts file is not found
- The plugins() function is not exported
- There are syntax errors in the plugin code

```typescript
import { PluginModuleResolver } from '@scriptdb/pmr';

try {
  const plugins = await PluginModuleResolver('./non-existent-directory');
} catch (error) {
  console.error('Failed to load plugins:', error.message);
}
```

## Security Considerations

- Only load plugins from trusted sources
- Validate plugin functionality before use
- Consider implementing a sandboxed environment for untrusted plugins
- Limit plugin access to sensitive resources

## License

MIT