Skip to content

LOADING_PACKAGES.md

Latest commit

 

History

History
212 lines (160 loc) · 7.22 KB

LOADING_PACKAGES.md

File metadata and controls

212 lines (160 loc) · 7.22 KB
Raw

← Back to Usage Guide Index

📦 Loading Packages

The load() method is the primary way to bring packages, modules, and assets into your runtime environment. It handles dependency resolution, parallel downloading, and lifecycle hooks.

Syntax

const ok = await bootstrap.load(resources, options?);

Parameters:

Name Type Description
resources string | object | array One or more packageResource inputs — see Package Specifications
options object (optional) Loader configuration (see below).

Options

Options are passed as the second argument to load(). All provided options are also passed to any handlers executed, and can be accessed inside the ctx variable.

{
  "load": ["jobDone", "#runners.mount"],
  "error": "jobFail",
  "limit": 8,
  "package": {
    "limit": 5,
    "hooks": true,
    "load": "packageLoad",
    "error": "packageError"
  },
  "repo": {
    "limit": 5,
    "itemLoad": "repoItemLoad",
    "itemError": "repoItemError",
    "load": "repoLoad",
    "error": "repoError"
  },
  "module": {
    "limit": 5,
    "itemLoad": "moduleItemLoad",
    "itemError": "moduleItemError",
    "load": "moduleLoad",
    "error": "moduleError"
  },
  "asset": {
    "limit": 5,
    "itemLoad": "assetItemLoad",
    "itemError": "assetItemError",
    "load": "assetLoad",
    "error": "assetError"
  }
}

Fields

Path Type Default Notes
limit integer 8 Global concurrency cap for parallel loads.
package.hooks boolean true Run each package’s hooks after load.
repo.circuitbreaker integer 100 Safety cutoff for runaway or circular dependency traversal.
repo.limit integer limit Repo concurrency limit; falls back to global limit.
module.limit integer limit Module fetch/load concurrency limit.
asset.limit integer limit Asset fetch concurrency limit; falls back to global limit.
asset.awaitAll boolean true Wait for all assets to complete before returning control.

--------------------- | ------- | ------- | ----------------------------------------------------------- | | limit | integer | 8 | Global concurrency cap for parallel loads. | | package.hooks | boolean | true | Run each package’s hooks after load. | | repo.circuitbreaker | integer | 100 | Safety cutoff for runaway or circular dependency traversal. | | repo.limit | integer | limit | Repo concurrency limit; falls back to global limit. | | assets.limit | integer | limit | Asset fetch concurrency limit; falls back to global limit.| | assets.awaitAll | boolean | true | Wait for all assets to complete before returning control. |

Resource Forms

resources can be:

  1. Symbolic string — "scene:chess"
  2. Repo-wrapped — { resource: "scene:chess", repo: ["/repo"] }
  3. Inline package — { resource: { id: "...", assets: [...], modules: [...] } }

Function Resource Arguments in Handlers

Handler fields in options (e.g., load, error, and per-scope fields like repo.itemLoad/module.itemError) accept function resource arguments, normalized into functionResourceObject form.

Examples include:

  • Direct function reference

  • String references:

    • "@pkg.module.fn" → function inside a loaded package
    • "~module.fn" or "~fn" → package-local reference
    • "#runner.mount" → bootstrapper-local method reference
    • "myFunction" → global function name

  • Object form with { fn: ... } and optional flags/metadata.

Example — Basic Load

const resources = [
  { resource: "scene:chess", repo: ["/repo"] },
  "@resources.allpurposemounter"
];

const ok = await bootstrap.load(resources, {
  load: ["#runner.mount", (sys, ctx) => console.log("Loaded:", ctx.results)],
  error: [(sys, ctx) => console.error("Failed:", ctx.failed)],
  package: { hooks: true }
});

if (!ok) {
  console.error("One or more packages failed to load");
}

Dependency Resolution

  1. Build dependency graph.
  2. Add required packages (including transitive dependencies) to the queue.
  3. Download in parallel.
  4. Mount packages once all resources are retrieved.

Parallel loading means dependency execution order isn’t guaranteed — wait for the load handler in options.

Hooks & Handlers

Specify handlers via the options object (e.g., load, error, repo.itemLoad, repo.itemError, module.itemLoad, asset.load, etc.).

Handler types:

  • Function — (sys, ctx) => { ... }
  • Global function name — "myFunction"
  • Symbolic module ref — "@pkg.module.fn"
  • Package-local ref — "~module.fn" or "~fn"
  • Bootstrap method — "#runner.mount"
  • functionResourceObject

Common Patterns

Multiple Repos

await bootstrap.load({
  resource: "scene:chess",
  repo: ["/primary-repo", "/backup-repo"]
});

Inline Packages

await bootstrap.load({
  resource: {
    id: "allpurposemounter",
    assets: [{ id: "mountinstructions", inline: true, content: { a: "b" } }],
    modules: [],
    hooks: {packageLoad: ["mountusMaximus"] }
  }
});

Unload

async unload(resources, options?): Promise<boolean>

Options:

Option Type Default Description
ignoreMissing boolean true Ignore missing packages.
cascade boolean false Remove dependencies as well as specified packages.
keepAssets boolean false Keep assets mounted/registered instead of removing them.
keepModules boolean false Keep modules registered instead of clearing them.
hooks boolean | undefined undefined run any hooks associated with the package. undefined = use whatever hooks value used when loading package
error fnResource `null function resource list to handle errors
load fnResource `null function reousrce list to run have unload complete

To unmount assets, include "#runner.unmount" in onDone. ex: bootstrap.unload('my:module', {load:'#runners.unmount'}

Related Topics: