76 lines
5.7 KiB
Markdown
76 lines
5.7 KiB
Markdown
# @suaveplan/api-loader — contract package for the Suaveplan API plugin system. Owns the abstract ModuleResolver interface, the RollbackJournal ring-buffer contract (with a reference in-memory implementation), the canonical cache-bust algorithm (bustSpecifier), the persisted-entry Zod schema, the native-binding-detector contract, the LOADER.* error-code registry, and the runLoaderConformance / runRollbackJournalConformance harnesses. Concrete resolver and journal implementations .
|
|
|
|
Stage-1 contract package for the Suaveplan API plugin system.
|
|
|
|
This package owns the abstract types, algorithms, and conformance harnesses
|
|
the host (`@suaveplan/api-host`, Stage 2) implements. It carries no
|
|
file-watching, no admin-API wiring, and no concrete `ModuleResolver`
|
|
implementation — those land in the host. Keeping the contracts here makes
|
|
the loader testable in isolation, lets adapter packages depend on the
|
|
contract without pulling in the host runtime, and prevents the circular
|
|
dependency that would otherwise form between the host and its plugins.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [cache-bust](./src/cache-bust/cache-bust.md) — Compute the cache-busted ESM specifier used by the API plugin host during a hot reload. Bun's ESM cache is keyed on the…
|
|
- [cache-bust](./src/cache-bust/cache-bust.md) — Compute the cache-busted ESM specifier used by the API plugin host during a hot reload. Bun's ESM cache is keyed on the…
|
|
- [error-codes](./src/error-codes/error-codes.md) — Stable, frozen registry of every `LOADER.*` error code surfaced by the plugin-loader contract. Downstream consumers (`@…
|
|
- [error-codes](./src/error-codes/error-codes.md) — Stable, frozen registry of every `LOADER.*` error code surfaced by the plugin-loader contract. Downstream consumers (`@…
|
|
- [journal-entry](./src/journal-entry/journal-entry.md) — Zod schema covering the **persisted subset** of a `RollbackJournalEntry`. The full entry (defined in `@suaveplan/api-ty…
|
|
- [journal-entry](./src/journal-entry/journal-entry.md) — Zod schema covering the **persisted subset** of a `RollbackJournalEntry`. The full entry (defined in `@suaveplan/api-ty…
|
|
- [native-binding-detector](./src/native-binding-detector/native-binding-detector.md) — Hot reload is the heart of the API plugin system, but it has one non-negotiable boundary: native bindings (`.node`…
|
|
- [native-binding-detector](./src/native-binding-detector/native-binding-detector.md) — Hot reload is the heart of the API plugin system, but it has one non-negotiable boundary: native bindings (`.node`…
|
|
- [resolver](./src/resolver/resolver.md) — `ModuleResolver` is the API plugin host's abstraction over `import()`. It imports a plugin entry under a cache-busted E…
|
|
- [resolver](./src/resolver/resolver.md) — `ModuleResolver` is the API plugin host's abstraction over `import()`. It imports a plugin entry under a cache-busted E…
|
|
- [rollback-journal](./src/rollback-journal/rollback-journal.md) — `RollbackJournal` is the per-plugin bounded ring buffer the API plugin host uses to retain the last N known-good module…
|
|
- [rollback-journal](./src/rollback-journal/rollback-journal.md) — `RollbackJournal` is the per-plugin bounded ring buffer the API plugin host uses to retain the last N known-good module…
|
|
- [testing](./src/testing/loader-conformance.md) — Reusable conformance harnesses for downstream packages that ship concrete implementations of the loader's `ModuleResolv…
|
|
- [loader-conformance](./src/testing/loader-conformance.md) — Reusable conformance harnesses for downstream packages that ship concrete implementations of the loader's `ModuleResolv…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Modules
|
|
|
|
- [`cache-bust`](./src/cache-bust/cache-bust.md) — `bustSpecifier(url,
|
|
version)` pure helper that produces the cache-busted ESM specifier the
|
|
host uses on every reload (design §8.2).
|
|
- [`error-codes`](./src/error-codes/error-codes.md) — `LOADER_CODES`
|
|
registry: `NATIVE_BINDING_HELD`, `MODULE_IMPORT_FAILED`, `JOURNAL_FULL`,
|
|
`JOURNAL_ENTRY_INVALID`.
|
|
- [`journal-entry`](./src/journal-entry/journal-entry.md) — Zod schema for
|
|
the persisted subset of a `RollbackJournalEntry` (the fields that survive
|
|
host restart).
|
|
- [`native-binding-detector`](./src/native-binding-detector/native-binding-detector.md)
|
|
— `NativeBindingDetector` function type and `assertNoNativeBindings`
|
|
helper that throws `LOADER.NATIVE_BINDING_HELD` when a plugin's import
|
|
subgraph contains `.node` files.
|
|
- [`resolver`](./src/resolver/resolver.md) — types-only `ModuleResolver`
|
|
contract.
|
|
- [`rollback-journal`](./src/rollback-journal/rollback-journal.md) — the
|
|
`RollbackJournal` interface plus the reference in-memory
|
|
`createRollbackJournal(depth)` implementation (default depth 3).
|
|
- [`testing`](./src/testing/loader-conformance.md) — `runLoaderConformance`
|
|
and `runRollbackJournalConformance` reusable harnesses.
|
|
|
|
## Subpath exports
|
|
|
|
```ts
|
|
import { bustSpecifier } from "@suaveplan/api-loader/cache-bust";
|
|
import { LOADER_CODES } from "@suaveplan/api-loader/error-codes";
|
|
import { rollbackJournalEntryPersistedSchema } from "@suaveplan/api-loader/journal-entry";
|
|
import { assertNoNativeBindings } from "@suaveplan/api-loader/native-binding-detector";
|
|
import type { ModuleResolver } from "@suaveplan/api-loader/resolver";
|
|
import { createRollbackJournal } from "@suaveplan/api-loader/rollback-journal";
|
|
import { runLoaderConformance } from "@suaveplan/api-loader/testing";
|
|
```
|
|
|
|
## Design intent
|
|
|
|
Source: `docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md`,
|
|
sections 8 (Hot reload), 8.1a (RollbackJournal), 8.2 (cache busting).
|
|
|
|
## Status
|
|
|
|
- Version: `0.1.0`
|
|
- Wave: Stage 1 (Contracts)
|
|
- Consumers: `@suaveplan/api-host` (Stage 2) implements the contracts here. |