@sourceacademy/runner-module-loader 0.0.1

package/README.md

@@ -0,0 +1,46 @@
+<h1 align="center">Module Loader</h1>
+
+<p align="center">Runner-side plugin for loading Source Academy modules</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@sourceacademy/runner-module-loader"><img src="https://img.shields.io/npm/v/@sourceacademy/runner-module-loader?color=1a2530&label=npm"></a>
+  <a href="https://github.com/source-academy/plugins/tree/main/src/runner/module-loader"><img src="https://img.shields.io/badge/github-repo-blue?logo=github"></a>
+</p>
+
+## Features
+The plugin provides an interface to load modules with a module ID
+
+## Installation
+```bash
+yarn add @sourceacademy/runner-module-loader
+# OR
+npm i @sourceacademy/runner-module-loader
+# OR
+pnpm add @sourceacademy/runner-module-loader
+```
+
+## Structure
+This package ([`@sourceacademy/runner-module-loader`](https://github.com/source-academy/plugins/tree/main/src/runner/module-loader)) contains the `ModuleLoaderRunnerPlugin` class — a Conductor runner plugin that an evaluator can call to load modules.
+
+### API Reference
+| Name | Description |
+|------|-------------|
+| `instance` | The singleton instance of the plugin. | 
+| `async requestModule(moduleName: string): Promise<IModulePlugin>` | Request a module by name from the host plugin. Rejects with an error if the module is not found. |
+
+## Usage
+After installation, import `ModuleLoaderRunnerPlugin` and register it with the Conductor evaluator. When evaluating `import` statements, call `requestModule` to load the module.
+
+```ts
+...
+const pluginObj = await ModuleLoaderRunnerPlugin.instance.requestModule(moduleName);
+context.nativeStorage.loadedModules[moduleName] = Object.fromEntries(
+    pluginObj?.exports.map(t => [t.symbol, t]) || [],
+);
+...
+```
+
+## Further reading
+- For the shared protocol types and IDs, see [`@sourceacademy/common-module-loader`](https://github.com/source-academy/plugins/tree/main/src/common/module-loader)
+- For the host-side plugin that accepts the module directory URL, see [`@sourceacademy/web-module-loader`](https://github.com/source-academy/plugins/tree/main/src/web/module-loader)
+- The [plugins wiki](https://github.com/source-academy/plugins/wiki) covers how Conductor plugins communicate

package/dist/__tests__/runner.test.d.ts

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

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";function e(e,t,n,o){return new(n||(n=Promise))(function(_,u){function i(e){try{s(o.next(e))}catch(e){u(e)}}function r(e){try{s(o.throw(e))}catch(e){u(e)}}function s(e){var t;e.done?_(e.value):(t=e.value,t instanceof n?t:new n(function(e){e(t)})).then(i,r)}s((o=o.apply(e,t||[])).next())})}"function"==typeof SuppressedError&&SuppressedError;var t,n,o,_,u;(n=t||(t={})).REQUEST_MODULE="request_module",n.MODULE_RESPONSE="module_response",n.MODULE_ERROR="module_error",function(e){e[e.CALL=0]="CALL",e[e.RETURN=1]="RETURN",e[e.RETURN_ERR=2]="RETURN_ERR"}(o||(o={})),function(e){e.UNKNOWN="__unknown",e.INTERNAL="__internal",e.EVALUATOR="__evaluator",e.EVALUATOR_SYNTAX="__evaluator_syntax",e.EVALUATOR_TYPE="__evaluator_type",e.EVALUATOR_RUNTIME="__evaluator_runtime"}(_||(_={})),function(e){e[e.PROTOCOL_VERSION=0]="PROTOCOL_VERSION",e[e.PROTOCOL_MIN_VERSION=0]="PROTOCOL_MIN_VERSION",e[e.SETUP_MESSAGES_BUFFER_SIZE=10]="SETUP_MESSAGES_BUFFER_SIZE"}(u||(u={}));class i{constructor(e,[t],n,o){this.id="__runner_module_loader",this.__loadedPlugins=new Map,this.__moduleRequestChannel=t,this.__conductor=n,this.__evaluator=o,i.instance=this}requestModule(n){return e(this,void 0,void 0,function*(){return this.__loadedPlugins.has(n)||this.__loadedPlugins.set(n,new Promise((o,_)=>{const u=i=>e(this,void 0,void 0,function*(){try{if(i.moduleName!==n)return;if(this.__moduleRequestChannel.unsubscribe(u),i.type===t.MODULE_RESPONSE){const e=yield import(i.moduleURL).then(e=>e.default(()=>{}).default),t=this.__conductor.registerPlugin(e,this.__evaluator,{tabs:i.tabs,loadTab:e=>{if(!i.tabs.includes(e))throw new Error(`Tab ${e} not found in module ${n}`);this.__conductor.hostLoadPlugin(e)}});yield t.initialise(),o(t)}else if(i.type===t.MODULE_ERROR)throw Error(i.error)}catch(e){this.__loadedPlugins.delete(n),_(e)}});this.__moduleRequestChannel.subscribe(u),this.__moduleRequestChannel.send({type:t.REQUEST_MODULE,moduleName:n})})),this.__loadedPlugins.get(n)})}}i.channelAttach=["module_config"],i.instance=null,exports.ModuleLoaderRunnerPlugin=i;

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { type IChannel, type IConduit, type IPlugin } from "@sourceacademy/conductor/conduit";
+import type { IModulePlugin } from "@sourceacademy/conductor/module";
+import type { IInterfacableEvaluator, IRunnerPlugin } from "@sourceacademy/conductor/runner";
+export declare class ModuleLoaderRunnerPlugin implements IPlugin {
+    readonly id: string;
+    static readonly channelAttach: string[];
+    private readonly __moduleRequestChannel;
+    private readonly __conductor;
+    private readonly __evaluator;
+    private readonly __loadedPlugins;
+    static instance: ModuleLoaderRunnerPlugin | null;
+    constructor(conduit: IConduit, [moduleRequestChannel]: IChannel<any>[], conductor: IRunnerPlugin, evaluator: IInterfacableEvaluator);
+    requestModule(moduleName: string): Promise<IModulePlugin>;
+}

package/dist/index.mjs

@@ -0,0 +1 @@
+function e(e,t,n,o){return new(n||(n=Promise))(function(_,u){function i(e){try{s(o.next(e))}catch(e){u(e)}}function r(e){try{s(o.throw(e))}catch(e){u(e)}}function s(e){var t;e.done?_(e.value):(t=e.value,t instanceof n?t:new n(function(e){e(t)})).then(i,r)}s((o=o.apply(e,t||[])).next())})}"function"==typeof SuppressedError&&SuppressedError;var t,n,o,_,u;(n=t||(t={})).REQUEST_MODULE="request_module",n.MODULE_RESPONSE="module_response",n.MODULE_ERROR="module_error",function(e){e[e.CALL=0]="CALL",e[e.RETURN=1]="RETURN",e[e.RETURN_ERR=2]="RETURN_ERR"}(o||(o={})),function(e){e.UNKNOWN="__unknown",e.INTERNAL="__internal",e.EVALUATOR="__evaluator",e.EVALUATOR_SYNTAX="__evaluator_syntax",e.EVALUATOR_TYPE="__evaluator_type",e.EVALUATOR_RUNTIME="__evaluator_runtime"}(_||(_={})),function(e){e[e.PROTOCOL_VERSION=0]="PROTOCOL_VERSION",e[e.PROTOCOL_MIN_VERSION=0]="PROTOCOL_MIN_VERSION",e[e.SETUP_MESSAGES_BUFFER_SIZE=10]="SETUP_MESSAGES_BUFFER_SIZE"}(u||(u={}));class i{constructor(e,[t],n,o){this.id="__runner_module_loader",this.__loadedPlugins=new Map,this.__moduleRequestChannel=t,this.__conductor=n,this.__evaluator=o,i.instance=this}requestModule(n){return e(this,void 0,void 0,function*(){return this.__loadedPlugins.has(n)||this.__loadedPlugins.set(n,new Promise((o,_)=>{const u=i=>e(this,void 0,void 0,function*(){try{if(i.moduleName!==n)return;if(this.__moduleRequestChannel.unsubscribe(u),i.type===t.MODULE_RESPONSE){const e=yield import(i.moduleURL).then(e=>e.default(()=>{}).default),t=this.__conductor.registerPlugin(e,this.__evaluator,{tabs:i.tabs,loadTab:e=>{if(!i.tabs.includes(e))throw new Error(`Tab ${e} not found in module ${n}`);this.__conductor.hostLoadPlugin(e)}});yield t.initialise(),o(t)}else if(i.type===t.MODULE_ERROR)throw Error(i.error)}catch(e){this.__loadedPlugins.delete(n),_(e)}});this.__moduleRequestChannel.subscribe(u),this.__moduleRequestChannel.send({type:t.REQUEST_MODULE,moduleName:n})})),this.__loadedPlugins.get(n)})}}i.channelAttach=["module_config"],i.instance=null;export{i as ModuleLoaderRunnerPlugin};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@sourceacademy/runner-module-loader",
+  "version": "0.0.1",
+  "packageManager": "yarn@4.6.0",
+  "description": "The runner plugin for the module loader in Source Academy",
+  "scripts": {
+    "build": "rollup -c",
+    "prepack": "yarn build"
+  },
+  "license": "ISC",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "@sourceacademy/conductor": ">=0.3.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-terser": "^1.0.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@sourceacademy/common-module-loader": "workspace:*",
+    "@sourceacademy/conductor": ">=0.3.0",
+    "@sourceacademy/runner-remote-execution": "workspace:*",
+    "@vitest/coverage-istanbul": "^4.1.9",
+    "rollup": "^4.60.2",
+    "tslib": "^2.8.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}