@bildit-platform/engine

@bildit-platform/engine

@bildit-platform/engine is a dynamic module engine that allows you to evaluate and interpret module code on the fly in a controlled environment. It automatically registers a global module creator and injects specific dependencies into dynamically evaluated modules.

Features

• Global Module Registration: Automatically registers a global define function (and sets React) so that evaluated modules can access controlled dependencies.
• Dynamic Module Interpretation: Provides a safe way to evaluate module code strings and retrieve specific exports.
• Dependency Injection: Uses a dependency injection mechanism to supply controlled dependencies (such as React and jsx-runtime) to your module factory functions.

Installation

Install via npm:

npm install @bildit-platform/engine

Or via yarn:

yarn add @bildit-platform/engine

Usage

When you import @bildit-platform/engine, it automatically registers a global module creator on globalThis (or window in browsers) and sets up the React dependency. The library provides two main functions: interpretModuleString and createModuleWithDependencies.

Global Registration & Module Interpretation

The library registers a global define function that you can use for dynamic module creation. The helper function interpretModuleString evaluates a module code string and returns the desired export.

Example

import {interpretModuleString} from '@bildit-platform/engine/react';

const moduleCode = `
  ({
    default: function hello() { return 'Hello, world!'; },
    extra: 'Additional export'
  })
`;

const helloFunction = interpretModuleString(moduleCode); // Defaults to 'default'
console.log(helloFunction()); // Outputs: Hello, world!

const extraExport = interpretModuleString(moduleCode, 'extra');
console.log(extraExport); // Outputs: Additional export

Dependency Injection with createModuleWithDependencies

import {createModuleWithDependencies} from '@bildit-platform/engine/react';

const moduleExports = createModuleWithDependencies(
  ['exports', 'react', 'react/jsx-runtime'],
  (exports, React, jsxRuntime) => {
    // Example: Attach a React component to the module exports.
    exports.MyComponent = () => React.createElement('div', null, 'Hello from MyComponent');
  }
);

console.log(moduleExports.MyComponent()); // Renders your component

API Reference

interpretModuleString

Interprets JavaScript module code from a string and returns the specified export.

Signature:

function interpretModuleString<T = unknown>(
  moduleCode: string, 
  exportName?: string, 
  extraDependenciesConfig: Record<string, ExtraDependencyConfig>
): T | null;

Parameters:

• moduleCode: The JavaScript module code as a string.
• exportName (optional): The name of the export to retrieve. Defaults to 'default'.
• extraDependenciesConfig (optional): Additional customer-specific dependencies.

Returns:

• The specified export from the module code, or null if not found.

createModuleWithDependencies

Creates a module context with controlled dependencies.

Signature:

function createModuleWithDependencies<T extends Record<string, unknown>>(
  dependencies: string[],
  moduleFactory: (...args: unknown[]) => void,
  extraDependenciesConfig: Record<string, ExtraDependencyConfig>
): T;

Parameters:

• dependencies: An array of dependency names required by the module.
• moduleFactory: A factory function that receives the resolved dependencies as arguments and populates the module’s exports.
• extraDependenciesConfig (optional): Extra dependencies configuration to set global name and module.

Returns:

• An object containing the module exports.

Types

export type ExtraDependencyConfig = {
  module: any;
  globalName?: string;
};