obix-core-modules

Previous name: @obinexusltd/obix-core-modules — OBIX packages are named without an npm scope since decision D-102 (2026-09-29); the package, its version and its exports are unchanged.

Portable ES-module resolution, loading and package-set validation for the OBIX CLI. The portable root touches no filesystem — it composes the host's own import() and import.meta.resolve; the /node subpath adds disk-backed asset copying.

The problem it owns

A CLI needs to resolve and load user modules (config files, plugins, job modules) the same way on Node, Deno and Bun, classify "not found" vs "no such export" without leaking host stack traces, and confirm that an installed family of packages (@scope/foo-*) is at one exact version. It must not promise synchronous CommonJS require — only the asynchronous import() baseline is implemented.

API

import {
  createModuleResolver, modules,
  type ModuleResolverAPI, type ResolvedSpecifier, type LoadResult,
  type InstalledManifest, type PackageSetReport,
} from "obix-core-modules";
import { createNodeModuleResolver, copyAssets } from "obix-core-modules/node";

| Export | Description | |--------|-------------| | createModuleResolver(hooks?) | Resolver bound to injected importImpl / resolveImpl, else the host's import() and import.meta.resolve. | | modules | A ready resolver bound to this host. | | resolveModule(specifier, parentURL) | Relative specifiers → a concrete file: URL (#/? in a path are percent-encoded first); bare specifiers → import.meta.resolve when the host honours the 2nd arg, else kind:"bare" passthrough for the host loader. | | loadModule(specifier, parentURL) | Resolve then await import(). Classifies module/resolve (not found) vs module/load (found, failed to evaluate / missing export). | | resolveAsset(assetSpecifier, ownerURL) | Resolve a data file relative to the module that owns it, never process.cwd(). | | validatePackageSet(manifests, { familyPrefix, expectedVersion }) | Reports version-mismatch, range-not-exact, missing, duplicate-version. | | createNodeModuleResolver() / copyAssets(specs) | /node — same resolver plus real asset copying (fs). |

Example (JavaScript)

import { modules } from "obix-core-modules";

const here = import.meta.url;
const r = modules.resolveModule("./plugins/logger.js", here);
console.log(r.kind, r.resolved); // "url" file:///…/plugins/logger.js

const { namespace } = await modules.loadModule("./plugins/logger.js", here);
namespace.register?.();

Example (TypeScript)

import { modules, type PackageSetReport } from "obix-core-modules";

const report: PackageSetReport = modules.validatePackageSet(
  [
    { name: "@acme/ui-core", version: "2.1.0", dependencies: { "@acme/ui-theme": "2.1.0" } },
    { name: "@acme/ui-theme", version: "2.1.0" },
  ],
  { familyPrefix: "@acme/ui-", expectedVersion: "2.1.0" },
);
if (!report.ok) for (const p of report.problems) console.error(p.kind, p.package, "-", p.detail);

Host support (verified 2026-09-07)

| Runtime | resolveModule bare kind | Notes | |---------|--------------------------|-------| | Node 26.7.0 / Win x64 | url | import.meta.resolve(spec, parentURL) honours the parent arg | | Deno 2.9.6 / Win x64 | bare (passthrough) | 2-arg import.meta.resolve not honoured — the host loader resolves | | Bun 1.4.2 / Win x64 | bare (passthrough) | same as Deno | | browser / web worker | authored, not run here | relative → URL works; bare needs an import map |

Linux/macOS and Node 22/24 LTS: authored, not-tested.

Fallbacks

• Bare specifier where the host cannot resolve against parentURL → kind:"bare"; the value is handed to the host loader unchanged (documented, not an error).
• resolveAsset always resolves against the owner URL, so a CLI run from any cwd finds a package's bundled data.

Errors

CompatError only: module/resolve (specifier did not resolve / file absent), module/load (resolved but failed to evaluate, or the named export is missing). The host's own error is attached as cause.

Boundary

No filesystem in the portable root. It does not implement CommonJS require, a bundler, or a plugin lifecycle — only resolve + load + validate.

MIT — OBINexus Computing

Installation

npm install obix-core-modules

API surface

• obix-core-modules — 3 value exports: CompatError, createModuleResolver, modules
• obix-core-modules/node — 2 value exports: copyAssets, createNodeModuleResolver
• Type declarations: ./dist/index.d.ts (and a declaration next to every JS entry point).

Architecture role

obix-core-modules is a lower-level core package: an implementation building block of OBIX; applications normally reach OBIX through the umbrella obix, and install this package directly only for what it alone provides.

The architecture of OBIX — the package families and which packages are public API — is indexed in the umbrella: docs/architecture.md.

Package relationships

• Depends on (OBIX): obix-core-capabilities.
• Used by (OBIX): obix-core-workers.

Testing

• 1 test file ships in the npm package (test/): the evidence of the package's contract, published so that its verification can be inspected — not runtime code (no entry point reaches it).
• Standalone: 1 of 1 — it reads nothing outside the package.
• Run them with npm test (node --test "test/*.test.mjs") in the OBIX monorepo, which provides the test tooling (Node's test runner, TypeScript) and the harness.

Documentation

• docs/resolution.md
• CHANGELOG.md
• The OBIX architecture index: obix/docs/architecture.md

Repository

• https://github.com/obinexus/obix-core-modules — [email protected]:obinexus/obix-core-modules.git
• Issues: https://github.com/obinexus/obix-core-modules/issues
• The repository is a clean export of the package from the OBIX monorepo. Its lineage — the sources it was recovered from and its earlier names — is PROVENANCE.json, shipped in this package; the repository's copy also records the monorepo commit it was exported from.

License

MIT — see LICENSE.