Sylvain Duchesne
bb2d9c3e59
Generic polyfill layer that makes a single NextGraph broker behave like the not-yet-shipped multi-user NextGraph (emulated capabilities + inbox). Zero app domain. @ng-eventually/client exposes an SDK-identical surface (ng, useShape, inbox); the polyfill bootstrap (configure + capability helpers) is isolated under /polyfill, so the main entry stays a drop-in for @ng-org/web|orm. The real SDK is injected at configure() (no hard import → build-alias safe + testable). Scaffold: NextGraph wiring stubbed with TODO; capability helpers implemented and unit-tested (4 tests, typecheck clean). The global-index curator is deferred — in NextGraph apps/services are mono-user with no global data. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
51 lines
2.6 KiB
Markdown
51 lines
2.6 KiB
Markdown
# ng-eventually
|
|
|
|
A **generic polyfill layer** over the [NextGraph](https://nextgraph.org) JS SDK.
|
|
|
|
NextGraph's JS SDK does not yet expose cross-wallet reads, capabilities, inboxes
|
|
or group stores. `ng-eventually` lets an app behave as if those existed today, by
|
|
emulating them on top of a **single shared wallet / broker**. It is **generic**:
|
|
it contains **no application domain** — the consumer injects its shapes and the
|
|
*acts* of granting access.
|
|
|
|
The name: *eventually* NextGraph will ship these features; until then this layer
|
|
fills the gap (and nods at eventual consistency / events).
|
|
|
|
## Packages
|
|
|
|
| Package | Role | At migration |
|
|
|---|---|---|
|
|
| **`@ng-eventually/client`** | **SDK-identical** wrapper the app imports instead of `@ng-org/web` / `@ng-org/orm`. Adds the polyfills the broker/verifier will do natively (shared-wallet login, capability enforcement, anticipated cap/inbox methods). | Disappears: the app points back at the real SDK (build alias removed). |
|
|
|
|
> **A global-index curator package is deferred.** NextGraph is **mono-user with
|
|
> no global data** (apps/services see only what the user shares; there is no
|
|
> multi-user backend). A global index would come from a **singleton app**
|
|
> (a global document administered by the developer) — **not implemented and
|
|
> uncertain**, and simpler paths may exist. So no second package for now; it will
|
|
> be (re)introduced once the global-index mechanism is decided. The curator must
|
|
> never be bundled in the client → it will be a separate package when it lands.
|
|
|
|
## Design principle
|
|
|
|
The application code is written **as if the target NextGraph existed**. All
|
|
compensation lives here, *beside* the app. Migration = remove this layer; the
|
|
app code (SDK-shaped) is unchanged.
|
|
|
|
- **SDK-identical surface**: the client wraps the real `ng` (a Proxy that
|
|
forwards everything and overrides only what must be emulated) and `useShape`.
|
|
The real SDK is **injected** via `configure()` (no hard import → build-alias
|
|
safe + testable).
|
|
- **Authorization = emulated capabilities**: documents carry grants; the client
|
|
enforces them generically (read filter + write guard). The app *attaches*
|
|
grants via cap operations — same as it will in the target. No policy is
|
|
injected.
|
|
- **Inbox**: the client `inbox.post()` deposits; materialization (the curator)
|
|
is deferred with the global-index mechanism — see the note above.
|
|
- **Tests** of the polyfill (against a real broker) live **in this repo**, so
|
|
the consuming app can test its features against a mocked, clean API.
|
|
|
|
## Status
|
|
|
|
Scaffold. Mechanisms are stubbed with `TODO(broker)` / `TODO(polyfill)` where
|
|
real NextGraph wiring is required.
|