@sylwellsoftware/glue 0.1.0-alpha.1 → 0.3.0

package/README.md

@@ -1,11 +1,11 @@
 # Glue
 
-Glue is the platform-neutral reactive core used by Fray. The experimental
-`0.1.0-alpha.1` candidate is not yet published. Its implementation and tests
-are strict TypeScript; the ESM build includes declarations and declaration
-maps.
+Glue is a small, platform-neutral reactive value and live-query library. Fray
+uses it as its state/data-flow layer, but Glue does not depend on Fray, a DOM,
+or any UI framework. Its implementation and tests are strict TypeScript; the
+ESM build includes declarations and declaration maps.
 
-After publication, install it with pnpm:
+Install with pnpm:
 
 ```bash
 pnpm add @sylwellsoftware/glue
@@ -15,6 +15,73 @@ Glue is ESM-only. Core emitters, derived state, and diagnostics support Node 22+
 and modern ESM runtimes without a DOM. `LiveQuery` needs `AbortController`, and
 `RestQueryHandler` needs Fetch and URL capabilities unless they are injected.
 
+## Design model
+
+Glue models values that stay current rather than requests that callers must
+manually rerun and redistribute. The same small read-side protocol applies to
+local state, computed state, query inputs, and asynchronous results:
+
+```ts
+interface ReadableEmitter<TValue, TError = unknown> {
+    get(): TValue
+    getFetchState(): FetchStateValue
+    getError(): TError | null
+    subscribe(listener: (notification: {
+        value: TValue
+        fetchState: FetchStateValue
+        error: TError | null
+        event: EventBubble<unknown> | null
+    }) => void): () => void
+}
+```
+
+That uniformity is the central design constraint. It lets a consumer bind to a
+current value without knowing whether the value is mutable, derived, or backed
+by asynchronous retrieval. Richer responsibilities remain separate:
+
+| Concept | Responsibility |
+| --- | --- |
+| `BaseEmitter` | Synchronously readable value/snapshot, subscriptions, mapping, equality, diagnostics, and disposal |
+| `Emitter` | An explicitly writable leaf value |
+| `DerivedEmitter` | A cached value computed from one or more readable emitters |
+| `QueryArg` | A named query-input view over another emitter when a semantic name is useful |
+| `LiveQuery` | Reactive request timing, latest-request ownership, status/error state, and cached results |
+| `QueryHandler` | Non-reactive retrieval strategy over a plain named argument object |
+| `RestQueryHandler` | HTTP URL construction, wire serialization, Fetch execution, and JSON result retrieval |
+| `EventBubble` / `EventBus` | Optional cause-and-effect diagnostics without owning application history |
+
+The intended flow is explicit and one-directional:
+
+```text
+Emitter(s) ──► DerivedEmitter(s) ──► named query arguments
+                                           │
+                                           ▼
+                                      LiveQuery
+                                           │ current plain values
+                                           ▼
+                                      QueryHandler
+                                           │
+                                           ▼
+                           value + fetch state + error
+```
+
+This separation prevents several kinds of accidental coupling:
+
+- leaf values do not need to know that a distant consumer may use them in a
+  request;
+- derived values express semantic computation rather than transport encoding;
+- `LiveQuery` decides *when* the current inputs require retrieval, while its
+  handler decides *how* retrieval works;
+- REST-specific formats, base URLs, authentication wrappers, and response
+  validation remain at application/adapter boundaries;
+- one live query can be mapped into multiple local views without multiplying
+  network requests.
+
+Glue deliberately favors explicit graphs over hidden tracking, proxy-created
+state, hooks, or a global store. If a value can be computed, prefer a
+`DerivedEmitter` to manually mirroring it. Use callbacks for commands and
+emitters for state that other objects need to read, combine, or observe.
+
 ## Emitters
 
 ```ts
@@ -56,6 +123,42 @@ current ones.
 `emitter.map(fn)` transforms the complete value. `emitter.mapEach(fn)` requires
 an array and transforms its non-nullish members.
 
+### Ownership, equality, and disposal
+
+Emitters eagerly cache their current snapshot so reads are synchronous.
+`Object.is` is the default value equality rule; pass `equals` when the domain
+has a better equivalence relation. A derived emitter subscribes eagerly to its
+sources and releases those subscriptions when sources are replaced or the
+derived value is disposed.
+
+The object that creates a long-lived emitter/query normally owns its disposal.
+Disposal is idempotent, prevents new subscriptions, and releases owned source
+subscriptions. A UI or service lifecycle should therefore dispose the graph it
+constructs rather than relying on garbage collection to sever active edges.
+
+## Query arguments
+
+`LiveQuery` accepts a named record of any readable emitters, so wrapping every
+input in `QueryArg` is neither required nor desirable. Use `QueryArg` when a
+stable query-facing name and separately owned bridge clarify the boundary:
+
+```ts
+import {DerivedEmitter, Emitter, LiveQuery, QueryArg} from '@sylwellsoftware/glue'
+
+const firstName = new Emitter('Ada')
+const lastName = new Emitter('Lovelace')
+const searchText = new DerivedEmitter(
+    [firstName, lastName] as const,
+    ([first, last]) => `${first} ${last}`,
+)
+const search = new QueryArg('search', searchText)
+const users = new LiveQuery({handler, args: {search}})
+```
+
+Here the leaf emitters know nothing about querying, and the computation knows
+nothing about REST. Dispose `users`, `search`, and `searchText` at the lifetime
+boundary that created them.
+
 ## Live queries
 
 ```js
@@ -98,14 +201,47 @@ process-local IDs, timestamps, weak owner references where supported, and
 explicit parent/child causality. The bus retains neither event history nor
 owners; its unsubscribe function is idempotent.
 
-## Experimental commands
+Tracing follows the same design as data flow: mutation, derivation, query
+start, and query completion can retain explicit parent/child causality without
+turning diagnostics into a second execution system. Applications decide
+whether to retain, render, or export observed events.
+
+## Async commands
 
-`@sylwellsoftware/glue/experimental` exports `AsyncCommand`, an abortable
+`AsyncCommand` is exported from Glue's package root. It is an abortable
 mutation lifecycle with explicit `ignore`, `replace`, and `reject` concurrency
 policies. It exposes the last result/error through the standard emitter
 snapshot and a read-only `isRunning` view. It deliberately does not own batch
 progress, retries, notifications, or UI behavior. See
-[EXPERIMENTAL.md](EXPERIMENTAL.md) for the provisional contract.
+the API reference below for the command contract.
+
+## Integration with Fray and other consumers
+
+Glue's UI seam is intentionally just the readable/writable emitter protocol.
+A typical Fray path is:
+
+```text
+browser event
+    └──► Fray control writes an Emitter
+              └──► DerivedEmitter computes shared/domain state
+                        ├──► Fray renders a local view
+                        └──► LiveQuery refreshes through a handler
+                                      └──► Fray renders query snapshot state
+```
+
+Leaf controls should normally receive ordinary writable emitters, not
+`QueryArg` objects. The component or service that understands an aggregate
+interaction owns its derived value. The data-aware consumer owns the query
+bridge and watches the result it actually renders. This keeps UI components
+reusable for local state, static data, remote data, and tests.
+
+Fray's theme and color selection is not a Glue feature. An application may
+store selected theme/color identifiers in ordinary Glue emitters when it wants
+observable or persistent selection state, but Fray and the browser remain
+responsible for CSS assets, stylesheet links, and rendering.
+
+Nothing in this contract is Fray-specific: another UI framework, a CLI, a Node
+service, or a test can consume the same emitters and live queries.
 
 ## Local checks
 
@@ -120,7 +256,7 @@ Glue intentionally does not own a DOM renderer, component lifecycle,
 application-specific query encoding, persistent event history, CommonJS build,
 or framework adapter. Fray consumes Glue as a peer; browser UI belongs there.
 
-See the [workspace overview](../../README.md), [alpha API
+See the [workspace overview](../../README.md), [API
 surface](../../docs/API_SURFACE.md), [changelog](../../CHANGELOG.md),
 [contribution guide](../../CONTRIBUTING.md), and [security
 policy](../../SECURITY.md).

package/dist/commands/asyncCommand.d.ts

@@ -19,7 +19,7 @@ export interface AsyncCommandOptions<TArguments, TResult, TError = unknown> {
 export declare class AsyncCommandConcurrencyError extends Error {
     constructor();
 }
-/** Experimental abortable mutation state with an explicit concurrency policy. */
+/** Abortable mutation state with an explicit concurrency policy. */
 export declare class AsyncCommand<TArguments, TResult, TError = unknown> extends BaseEmitter<TResult | undefined, TError> {
     readonly execute: AsyncCommandExecutor<TArguments, TResult>;
     readonly concurrency: AsyncCommandConcurrency;

package/dist/commands/asyncCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"asyncCommand.d.ts","sourceRoot":"","sources":["../../src/commands/asyncCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,WAAW,EAAC,MAAM,6BAA6B,CAAA;AACvD,OAAO,EAAC,WAAW,EAAC,MAAM,4BAA4B,CAAA;AACtD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,4BAA4B,CAAA;AAG/D,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kCAAkC,CAAA;AAErE,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAA;AAErE,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;IAChC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;CAC9C;AAED,MAAM,MAAM,oBAAoB,CAAC,UAAU,EAAE,OAAO,IAAI,CACpD,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,mBAAmB,KAC3B,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;AAEnC,MAAM,WAAW,mBAAmB,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IACtE,OAAO,EAAE,oBAAoB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;IAClD,WAAW,CAAC,EAAE,uBAAuB,CAAA;IACrC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAA;IACrC,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,CAAA;CAClB;AAWD,qBAAa,4BAA6B,SAAQ,KAAK;;CAKtD;AAED,iFAAiF;AACjF,qBAAa,YAAY,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAC3D,SAAQ,WAAW,CAAC,OAAO,GAAG,SAAS,EAAE,MAAM,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;IAC3D,QAAQ,CAAC,WAAW,EAAE,uBAAuB,CAAA;IAC7C,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,eAAe,CAAmC;IAC1D,OAAO,CAAC,mBAAmB,CAAqB;IAChD,OAAO,CAAC,kBAAkB,CAAQ;IAClC,2EAA2E;IAC3E,cAAc,EAAE,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,GAAG,IAAI,CAAO;gBAE9C,OAAO,EAAE,mBAAmB,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC;IAgCrE,GAAG,CACC,UAAU,EAAE,UAAU,EACtB,YAAY,GAAE,WAAW,CAAC,OAAO,CAAC,GAAG,OAAuB,GAC7D,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAiE/B,KAAK,CAAC,YAAY,GAAE,WAAW,CAAC,OAAO,CAAC,GAAG,OAA2B,GAAG,OAAO;IAmBhF,KAAK,CAAC,YAAY,GAAE,WAAW,CAAC,OAAO,CAAC,GAAG,OAAyB,GAAG,IAAI;IAelE,OAAO,IAAI,IAAI;IAWxB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,eAAe;CAO1B"}
+{"version":3,"file":"asyncCommand.d.ts","sourceRoot":"","sources":["../../src/commands/asyncCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,WAAW,EAAC,MAAM,6BAA6B,CAAA;AACvD,OAAO,EAAC,WAAW,EAAC,MAAM,4BAA4B,CAAA;AACtD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,4BAA4B,CAAA;AAG/D,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kCAAkC,CAAA;AAErE,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAA;AAErE,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;IAChC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;CAC9C;AAED,MAAM,MAAM,oBAAoB,CAAC,UAAU,EAAE,OAAO,IAAI,CACpD,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,mBAAmB,KAC3B,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;AAEnC,MAAM,WAAW,mBAAmB,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IACtE,OAAO,EAAE,oBAAoB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;IAClD,WAAW,CAAC,EAAE,uBAAuB,CAAA;IACrC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAA;IACrC,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,CAAA;CAClB;AAWD,qBAAa,4BAA6B,SAAQ,KAAK;;CAKtD;AAED,oEAAoE;AACpE,qBAAa,YAAY,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAC3D,SAAQ,WAAW,CAAC,OAAO,GAAG,SAAS,EAAE,MAAM,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;IAC3D,QAAQ,CAAC,WAAW,EAAE,uBAAuB,CAAA;IAC7C,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,eAAe,CAAmC;IAC1D,OAAO,CAAC,mBAAmB,CAAqB;IAChD,OAAO,CAAC,kBAAkB,CAAQ;IAClC,2EAA2E;IAC3E,cAAc,EAAE,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,GAAG,IAAI,CAAO;gBAE9C,OAAO,EAAE,mBAAmB,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC;IAgCrE,GAAG,CACC,UAAU,EAAE,UAAU,EACtB,YAAY,GAAE,WAAW,CAAC,OAAO,CAAC,GAAG,OAAuB,GAC7D,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAiE/B,KAAK,CAAC,YAAY,GAAE,WAAW,CAAC,OAAO,CAAC,GAAG,OAA2B,GAAG,OAAO;IAmBhF,KAAK,CAAC,YAAY,GAAE,WAAW,CAAC,OAAO,CAAC,GAAG,OAAyB,GAAG,IAAI;IAelE,OAAO,IAAI,IAAI;IAWxB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,eAAe;CAO1B"}

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export type { BubbleGraph, EventListener } from './debugging/eventBus.js';
 export { BaseEmitter, DerivedEmitter } from './emitters/baseEmitter.js';
 export type { DerivedEmitterOptions, DerivedErrorEntry, DerivedErrors, EmitterNotification, EmitterOptions, EmitterValue, EmitterValues, MapOptions, ReadableEmitter, SnapshotUpdate, SubscribeOptions, } from './emitters/baseEmitter.js';
 export { Emitter } from './emitters/emitter.js';
+export { AsyncCommand, AsyncCommandConcurrencyError } from './commands/asyncCommand.js';
+export type { AsyncCommandConcurrency, AsyncCommandContext, AsyncCommandExecutor, AsyncCommandOptions, } from './commands/asyncCommand.js';
 export { LiveQuery } from './emitters/liveQuery.js';
 export type { LiveQueryOptions, QueryArgumentEmitters, QueryArgumentValues, } from './emitters/liveQuery.js';
 export { combineFetchStates, FetchState, FetchStateValues } from './enums/fetchState.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,WAAW,EAAC,MAAM,4BAA4B,CAAA;AACtD,YAAY,EAAC,YAAY,EAAC,MAAM,4BAA4B,CAAA;AAC5D,OAAO,EAAC,QAAQ,EAAC,MAAM,yBAAyB,CAAA;AAChD,YAAY,EAAC,WAAW,EAAE,aAAa,EAAC,MAAM,yBAAyB,CAAA;AAEvE,OAAO,EAAC,WAAW,EAAE,cAAc,EAAC,MAAM,2BAA2B,CAAA;AACrE,YAAY,EACR,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,UAAU,EACV,eAAe,EACf,cAAc,EACd,gBAAgB,GACnB,MAAM,2BAA2B,CAAA;AAClC,OAAO,EAAC,OAAO,EAAC,MAAM,uBAAuB,CAAA;AAC7C,OAAO,EAAC,SAAS,EAAC,MAAM,yBAAyB,CAAA;AACjD,YAAY,EACR,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,GACtB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAAC,kBAAkB,EAAE,UAAU,EAAE,gBAAgB,EAAC,MAAM,uBAAuB,CAAA;AACtF,YAAY,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAA;AAE1D,OAAO,EAAC,QAAQ,EAAC,MAAM,6BAA6B,CAAA;AACpD,OAAO,EAAC,YAAY,EAAC,MAAM,iCAAiC,CAAA;AAC5D,YAAY,EACR,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,GACd,MAAM,iCAAiC,CAAA;AACxC,OAAO,EAAC,gBAAgB,EAAC,MAAM,qCAAqC,CAAA;AACpE,YAAY,EACR,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,uBAAuB,EACvB,gBAAgB,EAChB,OAAO,GACV,MAAM,qCAAqC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,WAAW,EAAC,MAAM,4BAA4B,CAAA;AACtD,YAAY,EAAC,YAAY,EAAC,MAAM,4BAA4B,CAAA;AAC5D,OAAO,EAAC,QAAQ,EAAC,MAAM,yBAAyB,CAAA;AAChD,YAAY,EAAC,WAAW,EAAE,aAAa,EAAC,MAAM,yBAAyB,CAAA;AAEvE,OAAO,EAAC,WAAW,EAAE,cAAc,EAAC,MAAM,2BAA2B,CAAA;AACrE,YAAY,EACR,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,UAAU,EACV,eAAe,EACf,cAAc,EACd,gBAAgB,GACnB,MAAM,2BAA2B,CAAA;AAClC,OAAO,EAAC,OAAO,EAAC,MAAM,uBAAuB,CAAA;AAC7C,OAAO,EAAC,YAAY,EAAE,4BAA4B,EAAC,MAAM,4BAA4B,CAAA;AACrF,YAAY,EACR,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,GACtB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EAAC,SAAS,EAAC,MAAM,yBAAyB,CAAA;AACjD,YAAY,EACR,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,GACtB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAAC,kBAAkB,EAAE,UAAU,EAAE,gBAAgB,EAAC,MAAM,uBAAuB,CAAA;AACtF,YAAY,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAA;AAE1D,OAAO,EAAC,QAAQ,EAAC,MAAM,6BAA6B,CAAA;AACpD,OAAO,EAAC,YAAY,EAAC,MAAM,iCAAiC,CAAA;AAC5D,YAAY,EACR,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,GACd,MAAM,iCAAiC,CAAA;AACxC,OAAO,EAAC,gBAAgB,EAAC,MAAM,qCAAqC,CAAA;AACpE,YAAY,EACR,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,uBAAuB,EACvB,gBAAgB,EAChB,OAAO,GACV,MAAM,qCAAqC,CAAA"}