API: dynamic imports with ns.dynamicImport() (#2036)

markdown/bitburner.ns.dynamicimport.md

@@ -0,0 +1,47 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [bitburner](./bitburner.md) &gt; [NS](./bitburner.ns.md) &gt; [dynamicImport](./bitburner.ns.dynamicimport.md)
+
+## NS.dynamicImport() method
+
+Dynamically import a script. Only scripts located on the same server can be imported. A dynamic import will not adjust RAM usage. This must be done manually with [ramOverride](./bitburner.ns.ramoverride.md)<!-- -->.
+
+**Signature:**
+
+```typescript
+dynamicImport(path: string): Promise<any>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  path | string |  |
+
+**Returns:**
+
+Promise&lt;any&gt;
+
+## Remarks
+
+RAM cost: 0 GB
+
+## Example
+
+File: script.js
+
+```js
+export async function main(ns){
+   const script = await ns.dynamicImport("./scriptToImport.js");
+   script.log(ns, "Message from an imported script!")
+}
+
+```
+File: scriptToImport.js
+
+```js
+export async function log(ns, message){
+   ns.tprint(message);
+}
+```
+

markdown/bitburner.ns.md

@@ -64,6 +64,7 @@ export async function main(ns) {
 |  [closeTail(pid)](./bitburner.ns.closetail.md) | Close the tail window of a script. This function is deprecated and will be removed in a later version. |
 |  [deleteServer(host)](./bitburner.ns.deleteserver.md) | Delete a purchased server. |
 |  [disableLog(fn)](./bitburner.ns.disablelog.md) | Disables logging for the given NS function. |
+|  [dynamicImport(path)](./bitburner.ns.dynamicimport.md) | Dynamically import a script. Only scripts located on the same server can be imported. A dynamic import will not adjust RAM usage. This must be done manually with [ramOverride](./bitburner.ns.ramoverride.md)<!-- -->. |
 |  [enableLog(fn)](./bitburner.ns.enablelog.md) | Enables logging for the given NS function. |
 |  [exec(script, hostname, threadOrOptions, args)](./bitburner.ns.exec.md) | Start another script on any server. |
 |  [exit()](./bitburner.ns.exit.md) | Terminates the current script immediately. |

src/Netscript/RamCostGenerator.ts

@@ -628,6 +628,7 @@ export const RamCosts: RamCostTree<NSFull> = {
   heart: { break: 0 },
   tprintRaw: 0,
   printRaw: 0,
+  dynamicImport: 0,
 
   formulas: {
     mockServer: 0,

src/NetscriptFunctions.ts

@@ -112,6 +112,8 @@ import { assertFunctionWithNSContext } from "./Netscript/TypeAssertion";
 import { Router } from "./ui/GameRoot";
 import { Page } from "./ui/Router";
 import { canAccessBitNodeFeature, validBitNodes } from "./BitNode/BitNodeUtils";
+import { compile } from "./NetscriptJSEvaluator";
+import { Script } from "./Script/Script";
 
 export const enums: NSEnums = {
   CityName,
@@ -1836,6 +1838,17 @@ export const ns: InternalAPI<NSFull> = {
   printRaw: (ctx) => (value) => {
     ctx.workerScript.print(wrapUserNode(value));
   },
+  dynamicImport: (ctx) => async (value) => {
+    const path = helpers.scriptPath(ctx, "path", value);
+    const server = helpers.getServer(ctx, ctx.workerScript.hostname);
+    const script = server.getContentFile(path);
+
+    if (!script) throw helpers.errorMessage(ctx, `Script was not found\nPath: ${path}`);
+
+    //We validated the path as ScriptFilePath and made sure script is not null
+    //Script **must** be a script at this point
+    return compile(script as Script, server.scripts);
+  },
   flags: Flags,
   heart: { break: () => () => Player.karma },
   ...NetscriptExtra(),

src/ScriptEditor/NetscriptDefinitions.d.ts

@@ -8370,6 +8370,34 @@ export interface NS {
    */
   getSharePower(): number;
 
+  /**
+   * Dynamically import a script.
+   * Only scripts located on the same server can be imported.
+   * A dynamic import will not adjust RAM usage. This must be done manually with {@link NS.ramOverride|ramOverride}.
+   *
+   * @example
+   *
+   * File: script.js
+   * ```js
+   * export async function main(ns){
+   *    const script = await ns.dynamicImport("./scriptToImport.js");
+   *    script.log(ns, "Message from an imported script!")
+   * }
+   *
+   * ```
+   *
+   * File: scriptToImport.js
+   * ```js
+   * export async function log(ns, message){
+   *    ns.tprint(message);
+   * }
+   * ```
+   *
+   * @remarks
+   * RAM cost: 0 GB
+   */
+  dynamicImport(path: string): Promise<any>;
+
   enums: NSEnums;
 }