@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

bun add @scriptdb/pmr

Quick Start

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.

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:

// 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

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

// 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

// 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

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