@bildit-platform/engine 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# @bildit/engine
+
+**@bildit/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:
+
+```bash
+npm install @bildit/engine
+```
+Or via yarn:
+```bash
+yarn add @bildit/engine
+```
+
+## Usage
+When you import @bildit/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
+```javascript
+import {interpretModuleString} from '@bildit/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
+```javascript
+import {createModuleWithDependencies} from '@bildit/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:**
+```javascript
+function interpretModuleString<T = unknown>(moduleCode: string, exportName?: string): T | null;
+```
+**Parameters:**
+- `moduleCode`: The JavaScript module code as a string.
+- `exportName` (optional): The name of the export to retrieve. Defaults to 'default'.
+
+**Returns:**
+- The specified export from the module code, or `null` if not found.
+
+### createModuleWithDependencies
+Creates a module context with controlled dependencies.
+
+**Signature:**
+```javascript
+function createModuleWithDependencies<T extends Record<string, unknown>>(
+  dependencies: string[],
+  moduleFactory: (...args: unknown[]) => void
+): 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.
+
+**Returns:**
+- An object containing the module exports.

package/dist/cjs/react/createModuleWithDependencies.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Creates a module context with controlled dependencies.
+ * This function is used internally by the dynamic code interpreter
+ * to provide specific dependencies to the interpreted module.
+ *
+ * @param dependencies - Array of dependency names required by the module
+ * @param moduleFactory - Factory function that creates the module using the dependencies
+ * @returns The exports object from the module
+ */
+export default function createModuleWithDependencies<T extends Record<string, unknown>>(dependencies: string[], moduleFactory: (...args: unknown[]) => void): T;

package/dist/cjs/react/createModuleWithDependencies.js

@@ -0,0 +1,54 @@
+/*
+   * Copyright (c) 2022 BILDIT, INC.
+   *
+   * This file, and the software contained herein, are the exclusive property of BILDIT, INC.
+   * Unauthorized copying, distribution, or modification of this software is strictly prohibited.
+   * All rights reserved.
+   *
+   * This file is licensed under the ENT License ("License"). Use of this file is subject to the
+   * terms and conditions specified in the License. You may obtain a copy of the License at:
+   *
+   *     https://bildit.co/ENTLicense
+   *
+   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+   * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+   * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   * DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+   * OUT OF, OR IN CONNECTION WITH, THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+   */
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ReactImport = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+/**
+ * Creates a module context with controlled dependencies.
+ * This function is used internally by the dynamic code interpreter
+ * to provide specific dependencies to the interpreted module.
+ *
+ * @param dependencies - Array of dependency names required by the module
+ * @param moduleFactory - Factory function that creates the module using the dependencies
+ * @returns The exports object from the module
+ */
+function createModuleWithDependencies(dependencies, moduleFactory) {
+    // Collect all data exported from the remote code.
+    const exports = {};
+    const availableDependencies = {
+        // Core dependencies
+        react: ReactImport,
+        // 'styled-components': styled,
+        'react/jsx-runtime': jsxRuntime
+    };
+    const resolvedDependencies = dependencies.map((dependencyName) => {
+        if (dependencyName === 'exports') {
+            return exports;
+        }
+        return availableDependencies[dependencyName];
+    });
+    moduleFactory(...resolvedDependencies);
+    return exports;
+}
+
+exports.default = createModuleWithDependencies;

package/dist/cjs/react/createModuleWithDependencies.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/react/index.d.ts

@@ -0,0 +1,2 @@
+export { default as interpretModuleString } from './interpretModuleString';
+export { default as createModuleWithDependencies } from './createModuleWithDependencies';

package/dist/cjs/react/interpretModuleString.d.ts

@@ -0,0 +1,27 @@
+import createModuleWithDependencies from './createModuleWithDependencies';
+type DefineFunction = typeof createModuleWithDependencies;
+declare global {
+    namespace NodeJS {
+        interface Global {
+            define: DefineFunction;
+            React: any;
+        }
+    }
+    interface Window {
+        define: DefineFunction;
+        React: any;
+    }
+}
+/**
+ * Interprets JavaScript module code from a string and returns the specified export.
+ *
+ * This function safely interprets module code in a controlled environment with
+ * limited access to dependencies. It's designed for dynamic code loading scenarios
+ * where the code comes from a trusted source.
+ *
+ * @param moduleCode - JavaScript module code to interpret
+ * @param exportName - Name of the export to return (defaults to 'default')
+ * @returns The requested module export or null if interpretation fails
+ */
+declare const interpretModuleString: <T = unknown>(moduleCode: string, exportName?: string) => T | null;
+export default interpretModuleString;

package/dist/cjs/react/interpretModuleString.js

@@ -0,0 +1,92 @@
+/*
+   * Copyright (c) 2022 BILDIT, INC.
+   *
+   * This file, and the software contained herein, are the exclusive property of BILDIT, INC.
+   * Unauthorized copying, distribution, or modification of this software is strictly prohibited.
+   * All rights reserved.
+   *
+   * This file is licensed under the ENT License ("License"). Use of this file is subject to the
+   * terms and conditions specified in the License. You may obtain a copy of the License at:
+   *
+   *     https://bildit.co/ENTLicense
+   *
+   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+   * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+   * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   * DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+   * OUT OF, OR IN CONNECTION WITH, THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+   */
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ReactImport = require('react');
+var createModuleWithDependencies = require('./createModuleWithDependencies.js');
+
+function _interopNamespaceDefault(e) {
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+var ReactImport__namespace = /*#__PURE__*/_interopNamespaceDefault(ReactImport);
+
+/**
+ * Registers the module creator in the global scope for use by evaluated code
+ */
+const registerGlobalModuleCreator = () => {
+    // Check if we're in a Node.js environment
+    if (typeof process !== 'undefined' &&
+        process.versions != null &&
+        process.versions.node != null) {
+        // We're in Node.js
+        globalThis.define = createModuleWithDependencies.default;
+        globalThis.React = ReactImport__namespace;
+    }
+    else {
+        // We're in a browser or other environment
+        window.define = createModuleWithDependencies.default;
+        window.React = ReactImport__namespace;
+    }
+};
+// Execute the registration
+registerGlobalModuleCreator();
+/**
+ * Interprets JavaScript module code from a string and returns the specified export.
+ *
+ * This function safely interprets module code in a controlled environment with
+ * limited access to dependencies. It's designed for dynamic code loading scenarios
+ * where the code comes from a trusted source.
+ *
+ * @param moduleCode - JavaScript module code to interpret
+ * @param exportName - Name of the export to return (defaults to 'default')
+ * @returns The requested module export or null if interpretation fails
+ */
+const interpretModuleString = (moduleCode, exportName = 'default') => {
+    try {
+        const compiledModule = eval === null || eval === void 0 ? void 0 : eval(`"use strict"; ${moduleCode}`);
+        if (!compiledModule)
+            return null;
+        if ((exportName === null || exportName === void 0 ? void 0 : exportName.length) > 0) {
+            return compiledModule[exportName];
+        }
+        return compiledModule;
+    }
+    catch (e) {
+        console.error('Evaluation error:', e);
+        return null;
+    }
+};
+
+exports.default = interpretModuleString;

package/dist/cjs/react/interpretModuleString.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/react.js

@@ -0,0 +1,27 @@
+/*
+   * Copyright (c) 2022 BILDIT, INC.
+   *
+   * This file, and the software contained herein, are the exclusive property of BILDIT, INC.
+   * Unauthorized copying, distribution, or modification of this software is strictly prohibited.
+   * All rights reserved.
+   *
+   * This file is licensed under the ENT License ("License"). Use of this file is subject to the
+   * terms and conditions specified in the License. You may obtain a copy of the License at:
+   *
+   *     https://bildit.co/ENTLicense
+   *
+   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+   * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+   * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   * DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+   * OUT OF, OR IN CONNECTION WITH, THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+   */
+'use strict';
+
+var interpretModuleString = require('./react/interpretModuleString.js');
+var createModuleWithDependencies = require('./react/createModuleWithDependencies.js');
+
+
+
+exports.interpretModuleString = interpretModuleString.default;
+exports.createModuleWithDependencies = createModuleWithDependencies.default;

package/dist/esm/react/createModuleWithDependencies.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Creates a module context with controlled dependencies.
+ * This function is used internally by the dynamic code interpreter
+ * to provide specific dependencies to the interpreted module.
+ *
+ * @param dependencies - Array of dependency names required by the module
+ * @param moduleFactory - Factory function that creates the module using the dependencies
+ * @returns The exports object from the module
+ */
+export default function createModuleWithDependencies<T extends Record<string, unknown>>(dependencies: string[], moduleFactory: (...args: unknown[]) => void): T;

package/dist/esm/react/createModuleWithDependencies.js

@@ -0,0 +1,50 @@
+/*
+   * Copyright (c) 2022 BILDIT, INC.
+   *
+   * This file, and the software contained herein, are the exclusive property of BILDIT, INC.
+   * Unauthorized copying, distribution, or modification of this software is strictly prohibited.
+   * All rights reserved.
+   *
+   * This file is licensed under the ENT License ("License"). Use of this file is subject to the
+   * terms and conditions specified in the License. You may obtain a copy of the License at:
+   *
+   *     https://bildit.co/ENTLicense
+   *
+   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+   * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+   * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   * DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+   * OUT OF, OR IN CONNECTION WITH, THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+   */
+import ReactImport__default from 'react';
+import jsxRuntime from 'react/jsx-runtime';
+
+/**
+ * Creates a module context with controlled dependencies.
+ * This function is used internally by the dynamic code interpreter
+ * to provide specific dependencies to the interpreted module.
+ *
+ * @param dependencies - Array of dependency names required by the module
+ * @param moduleFactory - Factory function that creates the module using the dependencies
+ * @returns The exports object from the module
+ */
+function createModuleWithDependencies(dependencies, moduleFactory) {
+    // Collect all data exported from the remote code.
+    const exports = {};
+    const availableDependencies = {
+        // Core dependencies
+        react: ReactImport__default,
+        // 'styled-components': styled,
+        'react/jsx-runtime': jsxRuntime
+    };
+    const resolvedDependencies = dependencies.map((dependencyName) => {
+        if (dependencyName === 'exports') {
+            return exports;
+        }
+        return availableDependencies[dependencyName];
+    });
+    moduleFactory(...resolvedDependencies);
+    return exports;
+}
+
+export { createModuleWithDependencies as default };

package/dist/esm/react/createModuleWithDependencies.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/react/index.d.ts

@@ -0,0 +1,2 @@
+export { default as interpretModuleString } from './interpretModuleString';
+export { default as createModuleWithDependencies } from './createModuleWithDependencies';

package/dist/esm/react/interpretModuleString.d.ts

@@ -0,0 +1,27 @@
+import createModuleWithDependencies from './createModuleWithDependencies';
+type DefineFunction = typeof createModuleWithDependencies;
+declare global {
+    namespace NodeJS {
+        interface Global {
+            define: DefineFunction;
+            React: any;
+        }
+    }
+    interface Window {
+        define: DefineFunction;
+        React: any;
+    }
+}
+/**
+ * Interprets JavaScript module code from a string and returns the specified export.
+ *
+ * This function safely interprets module code in a controlled environment with
+ * limited access to dependencies. It's designed for dynamic code loading scenarios
+ * where the code comes from a trusted source.
+ *
+ * @param moduleCode - JavaScript module code to interpret
+ * @param exportName - Name of the export to return (defaults to 'default')
+ * @returns The requested module export or null if interpretation fails
+ */
+declare const interpretModuleString: <T = unknown>(moduleCode: string, exportName?: string) => T | null;
+export default interpretModuleString;

package/dist/esm/react/interpretModuleString.js

@@ -0,0 +1,69 @@
+/*
+   * Copyright (c) 2022 BILDIT, INC.
+   *
+   * This file, and the software contained herein, are the exclusive property of BILDIT, INC.
+   * Unauthorized copying, distribution, or modification of this software is strictly prohibited.
+   * All rights reserved.
+   *
+   * This file is licensed under the ENT License ("License"). Use of this file is subject to the
+   * terms and conditions specified in the License. You may obtain a copy of the License at:
+   *
+   *     https://bildit.co/ENTLicense
+   *
+   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+   * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+   * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   * DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+   * OUT OF, OR IN CONNECTION WITH, THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+   */
+import * as ReactImport from 'react';
+import createModuleWithDependencies from './createModuleWithDependencies.js';
+
+/**
+ * Registers the module creator in the global scope for use by evaluated code
+ */
+const registerGlobalModuleCreator = () => {
+    // Check if we're in a Node.js environment
+    if (typeof process !== 'undefined' &&
+        process.versions != null &&
+        process.versions.node != null) {
+        // We're in Node.js
+        globalThis.define = createModuleWithDependencies;
+        globalThis.React = ReactImport;
+    }
+    else {
+        // We're in a browser or other environment
+        window.define = createModuleWithDependencies;
+        window.React = ReactImport;
+    }
+};
+// Execute the registration
+registerGlobalModuleCreator();
+/**
+ * Interprets JavaScript module code from a string and returns the specified export.
+ *
+ * This function safely interprets module code in a controlled environment with
+ * limited access to dependencies. It's designed for dynamic code loading scenarios
+ * where the code comes from a trusted source.
+ *
+ * @param moduleCode - JavaScript module code to interpret
+ * @param exportName - Name of the export to return (defaults to 'default')
+ * @returns The requested module export or null if interpretation fails
+ */
+const interpretModuleString = (moduleCode, exportName = 'default') => {
+    try {
+        const compiledModule = eval === null || eval === void 0 ? void 0 : eval(`"use strict"; ${moduleCode}`);
+        if (!compiledModule)
+            return null;
+        if ((exportName === null || exportName === void 0 ? void 0 : exportName.length) > 0) {
+            return compiledModule[exportName];
+        }
+        return compiledModule;
+    }
+    catch (e) {
+        console.error('Evaluation error:', e);
+        return null;
+    }
+};
+
+export { interpretModuleString as default };

package/dist/esm/react/interpretModuleString.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/react.js

@@ -0,0 +1,20 @@
+/*
+   * Copyright (c) 2022 BILDIT, INC.
+   *
+   * This file, and the software contained herein, are the exclusive property of BILDIT, INC.
+   * Unauthorized copying, distribution, or modification of this software is strictly prohibited.
+   * All rights reserved.
+   *
+   * This file is licensed under the ENT License ("License"). Use of this file is subject to the
+   * terms and conditions specified in the License. You may obtain a copy of the License at:
+   *
+   *     https://bildit.co/ENTLicense
+   *
+   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+   * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+   * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   * DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+   * OUT OF, OR IN CONNECTION WITH, THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+   */
+export { default as interpretModuleString } from './react/interpretModuleString.js';
+export { default as createModuleWithDependencies } from './react/createModuleWithDependencies.js';

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@bildit-platform/engine",
+  "version": "0.1.0",
+  "description": "Bildit Render Engine",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./react": {
+      "require": "./dist/cjs/react.js",
+      "types": "./dist/esm/react/index.d.ts",
+      "import": "./dist/esm/react.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "react": [
+        "dist/esm/react/index.d.ts"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "dev": "rollup -c -w",
+    "lint": "eslint src/**/*.{ts,tsx}",
+    "clean": "rimraf dist",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "bildit",
+    "cms",
+    "nextjs",
+    "react"
+  ],
+  "author": "BILDIT",
+  "contributors": [
+    "Wes Guirra"
+  ],
+  "license": "UNLICENSED",
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^24.0.0",
+    "@rollup/plugin-node-resolve": "^15.0.0",
+    "@rollup/plugin-typescript": "^11.0.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.13.14",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "@types/react-is": "^19.0.0",
+    "eslint": "^8.0.0",
+    "rimraf": "^4.0.0",
+    "rollup": "^3.0.0",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "react-is": "^19.0.0"
+  }
+}