first commit
This commit is contained in:
76
docs/api-stack/api/api-loader/README.md
Normal file
76
docs/api-stack/api/api-loader/README.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# @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.
|
||||
Reference in New Issue
Block a user