@sourceacademy/web-module-loader 0.0.2

package/README.md

@@ -0,0 +1,67 @@
+<h1 align="center"> Module Loader </h1>
+
+<p align="center">Host-side plugin to load Source Academy modules</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@sourceacademy/web-module-loader"><img src="https://img.shields.io/npm/v/@sourceacademy/web-module-loader?color=1a2530&label=npm"></a>
+  <a href="https://github.com/source-academy/plugins/tree/main/src/web/module-loader"><img src="https://img.shields.io/badge/github-repo-blue?logo=github"></a>
+</p>
+
+## Features
+- Provides an interface to load modules with a module ID, as well as the location of tabs on the host-side
+- Accepts a module directory URL from the host app
+
+## Installation
+To install the package, use:
+```bash
+yarn add @sourceacademy/web-module-loader
+# OR
+npm i @sourceacademy/web-module-loader
+# OR
+pnpm add @sourceacademy/web-module-loader
+```
+
+## Structure
+This package ([`@sourceacademy/web-module-loader`](https://github.com/source-academy/plugins/tree/main/src/web/module-loader)) contains the `ModuleLoaderWebPlugin` class — a Conductor host plugin that subscribes to a Conductor channel and delivers module information to the host app.
+
+### API Reference
+| Name | Description |
+|------|-------------|
+| `instance` | The singleton instance of the plugin. |
+| `onModuleDirectoryURLChange(newUrl: string): void` | To be called during module directory URL changes. |
+| `getModuleTabLocation(tabName: string): string | null` | Returns the location of the specified module tab, or null if not found. |
+
+## Usage
+During the host-side Conductor initialisation, register the class with the conduit.
+
+```ts
+...
+hostPlugin.registerPlugin(ModuleLoaderWebPlugin);
+ModuleLoaderWebPlugin.instance.onModuleDirectoryURLChange(moduleDirectoryURL);
+...
+```
+
+Then, on module directory changes, call `onModuleDirectoryURLChange` to update the module directory URL. 
+
+```ts
+export const flagDirectoryModulesUrl = createFeatureFlag(
+  'directory.modules.url',
+  'https://source-academy.github.io/modules-conductor/modules.json',
+  'The URL where the module directory may be found.',
+  // eslint-disable-next-line require-yield
+  function* (url: string) {
+    ModuleLoaderWebPlugin.instance?.onModuleDirectoryURLChange(url);
+  },
+);
+```
+
+To receive the location of a module tab, call `getModuleTabLocation` with the tab name.
+
+```ts
+const tabLocation = ModuleLoaderWebPlugin.instance.getModuleTabLocation(tabName);
+```
+
+## 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 runner-side plugin that sends snapshots, see [`@sourceacademy/runner-module-loader`](https://github.com/source-academy/plugins/tree/main/src/runner/module-loader)
+- The [plugins wiki](https://github.com/source-academy/plugins/wiki) covers how Conductor plugins communicate

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

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

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";function e(e,t,o,r){return new(o||(o=Promise))(function(u,n){function l(e){try{d(r.next(e))}catch(e){n(e)}}function i(e){try{d(r.throw(e))}catch(e){n(e)}}function d(e){var t;e.done?u(e.value):(t=e.value,t instanceof o?t:new o(function(e){e(t)})).then(l,i)}d((r=r.apply(e,t||[])).next())})}"function"==typeof SuppressedError&&SuppressedError;var t,o,r,u;!function(e){e.REQUEST_MODULE="request_module",e.MODULE_RESPONSE="module_response",e.MODULE_ERROR="module_error"}(t||(t={})),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"}(r||(r={})),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 n{constructor(e,[o]){this.id="__web_module_loader",this.moduleDirectoryURL=null,this.moduleDirectory=null,this.__moduleRequestChannel=o,n.instance=this,this.__moduleRequestChannel.subscribe(e=>{if(e.type!==t.REQUEST_MODULE)return;if(null===this.moduleDirectory||null===this.moduleDirectoryURL)return this.__moduleRequestChannel.send({type:t.MODULE_ERROR,moduleName:e.moduleName,error:"Module directory not loaded yet"});if(!Object.hasOwn(this.moduleDirectory,e.moduleName))return this.__moduleRequestChannel.send({type:t.MODULE_ERROR,moduleName:e.moduleName,error:`Module not found: ${e.moduleName}`});if(!/^[a-zA-Z0-9_-]+$/.test(e.moduleName))return this.__moduleRequestChannel.send({type:t.MODULE_ERROR,moduleName:e.moduleName,error:`Invalid module name: ${e.moduleName}`});const o=this.moduleDirectoryURL.slice(0,this.moduleDirectoryURL.lastIndexOf("/")+1);return this.__moduleRequestChannel.send({type:t.MODULE_RESPONSE,moduleName:e.moduleName,moduleURL:o+"bundles/"+e.moduleName+".js",tabs:this.moduleDirectory[e.moduleName].tabs})})}onModuleDirectoryURLChange(t){return e(this,void 0,void 0,function*(){t===this.moduleDirectoryURL&&this.moduleDirectory||(this.moduleDirectoryURL=t,this.moduleDirectory=null,yield fetch(t).then(e=>e.json()).then(e=>{this.moduleDirectory=e}).catch(e=>{console.error("Failed to load module directory:",e)}))})}getModuleTabLocation(e){if(!this.moduleDirectory||!this.moduleDirectoryURL)return null;for(const t in this.moduleDirectory)if(this.moduleDirectory[t].tabs.includes(e)){return this.moduleDirectoryURL.slice(0,this.moduleDirectoryURL.lastIndexOf("/")+1)+"tabs/"+e+".js"}return null}}n.channelAttach=["module_config"],n.instance=null,exports.ModuleLoaderWebPlugin=n;

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { type IPlugin, type IChannel, type IConduit } from "@sourceacademy/conductor/conduit";
+export declare class ModuleLoaderWebPlugin implements IPlugin {
+    readonly id: string;
+    static readonly channelAttach: string[];
+    private readonly __moduleRequestChannel;
+    static instance: ModuleLoaderWebPlugin | null;
+    private moduleDirectoryURL;
+    private moduleDirectory;
+    constructor(_conduit: IConduit, [moduleRequestChannel]: IChannel<any>[]);
+    onModuleDirectoryURLChange(newURL: string): Promise<void>;
+    getModuleTabLocation(tabName: string): string | null;
+}

package/dist/index.mjs

@@ -0,0 +1 @@
+function e(e,t,o,r){return new(o||(o=Promise))(function(u,n){function l(e){try{d(r.next(e))}catch(e){n(e)}}function i(e){try{d(r.throw(e))}catch(e){n(e)}}function d(e){var t;e.done?u(e.value):(t=e.value,t instanceof o?t:new o(function(e){e(t)})).then(l,i)}d((r=r.apply(e,t||[])).next())})}"function"==typeof SuppressedError&&SuppressedError;var t,o,r,u;!function(e){e.REQUEST_MODULE="request_module",e.MODULE_RESPONSE="module_response",e.MODULE_ERROR="module_error"}(t||(t={})),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"}(r||(r={})),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 n{constructor(e,[o]){this.id="__web_module_loader",this.moduleDirectoryURL=null,this.moduleDirectory=null,this.__moduleRequestChannel=o,n.instance=this,this.__moduleRequestChannel.subscribe(e=>{if(e.type!==t.REQUEST_MODULE)return;if(null===this.moduleDirectory||null===this.moduleDirectoryURL)return this.__moduleRequestChannel.send({type:t.MODULE_ERROR,moduleName:e.moduleName,error:"Module directory not loaded yet"});if(!Object.hasOwn(this.moduleDirectory,e.moduleName))return this.__moduleRequestChannel.send({type:t.MODULE_ERROR,moduleName:e.moduleName,error:`Module not found: ${e.moduleName}`});if(!/^[a-zA-Z0-9_-]+$/.test(e.moduleName))return this.__moduleRequestChannel.send({type:t.MODULE_ERROR,moduleName:e.moduleName,error:`Invalid module name: ${e.moduleName}`});const o=this.moduleDirectoryURL.slice(0,this.moduleDirectoryURL.lastIndexOf("/")+1);return this.__moduleRequestChannel.send({type:t.MODULE_RESPONSE,moduleName:e.moduleName,moduleURL:o+"bundles/"+e.moduleName+".js",tabs:this.moduleDirectory[e.moduleName].tabs})})}onModuleDirectoryURLChange(t){return e(this,void 0,void 0,function*(){t===this.moduleDirectoryURL&&this.moduleDirectory||(this.moduleDirectoryURL=t,this.moduleDirectory=null,yield fetch(t).then(e=>e.json()).then(e=>{this.moduleDirectory=e}).catch(e=>{console.error("Failed to load module directory:",e)}))})}getModuleTabLocation(e){if(!this.moduleDirectory||!this.moduleDirectoryURL)return null;for(const t in this.moduleDirectory)if(this.moduleDirectory[t].tabs.includes(e)){return this.moduleDirectoryURL.slice(0,this.moduleDirectoryURL.lastIndexOf("/")+1)+"tabs/"+e+".js"}return null}}n.channelAttach=["module_config"],n.instance=null;export{n as ModuleLoaderWebPlugin};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@sourceacademy/web-module-loader",
+  "version": "0.0.2",
+  "packageManager": "yarn@4.6.0",
+  "description": "The web plugin for the module loader in Source Academy",
+  "scripts": {
+    "build": "rollup -c",
+    "prepack": "yarn build"
+  },
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "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-commonjs": "^29.0.3",
+    "@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/common-tabs": "workspace:^",
+    "@sourceacademy/conductor": ">=0.3.0",
+    "rollup": "^4.60.2",
+    "tslib": "^2.8.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}