@braidlabs/data 0.1.1

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@braidlabs/data",
+  "version": "0.1.1",
+  "description": "Local-first client data layer: persistence-first, skew-tolerant across independently deployed readers.",
+  "keywords": [
+    "local-first",
+    "indexeddb",
+    "offline",
+    "outbox",
+    "micro-frontends",
+    "skew"
+  ],
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@braidlabs/skew": "^0.1.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/braidjs/braid.git",
+    "directory": "libs/data"
+  },
+  "homepage": "https://github.com/braidjs/braid#readme",
+  "bugs": {
+    "url": "https://github.com/braidjs/braid/issues"
+  },
+  "module": "./src/index.js"
+}

package/src/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @braidlabs/data — the local-first data layer.
+ *
+ * Persistence-first: IndexedDB is the source of truth and memory is a derived view. Every record is
+ * enveloped by `@braidlabs/skew` and projected to *this* reader's version on the way out, which is
+ * what lets independently deployed apps read the same store at different contract versions.
+ *
+ * Framework-neutral. Angular bindings live in `@braidlabs/angular-data`.
+ */
+export { createRecordStore } from './lib/record-store.js';
+export type { RecordStore, RecordStoreOptions, RecordDriver, StoredRecord, ProjectedRecord, } from './lib/record-store.js';
+export { memoryRecordDriver } from './lib/memory-driver.js';
+export { indexedDbRecordDriver } from './lib/indexeddb-driver.js';
+export type { IndexedDbDriverOptions } from './lib/indexeddb-driver.js';
+export { withLock, hasCrossContextLocks, outboxFlushLock } from './lib/locks.js';
+export type { LockResult, LockOptions } from './lib/locks.js';
+export { createDataClient } from './lib/query.js';
+export type { DataClient, DataClientOptions, Query, QueryDefinition, QueryState, QueryStatus, Conflict, ConflictPolicy, MutationDefinition, MutationOutcome, MutationRegistration, } from './lib/query.js';
+export { drainOutbox } from './lib/flush.js';
+export type { DrainOptions, FlushResult, MutationRunner } from './lib/flush.js';
+export { createInvalidator, sharedInvalidator, resetSharedInvalidators } from './lib/invalidation.js';
+export type { Invalidator, InvalidationOptions, BroadcastChannelLike } from './lib/invalidation.js';
+export { createOutbox, OutboxEntrySchema } from './lib/outbox.js';
+export type { Outbox, OutboxOptions, OutboxEntry, QueuedEntry, OptimisticOverlay } from './lib/outbox.js';
+export { createTenancy, partitionKey, TenancyRecordSchema } from './lib/tenancy.js';
+export type { Tenancy, TenancyOptions, Principal, AdoptOptions } from './lib/tenancy.js';
+export { copyPartition } from './lib/partitions.js';
+export type { CopyPartitionOptions, CopyPartitionResult, PartitionConflictPolicy, } from './lib/partitions.js';
+export { fromPull } from './lib/adapters.js';
+export type { PullAdapter, PushAdapter, PushConnection, PushRecord, PushSink, CommandAdapter, } from './lib/adapters.js';
+export { createEventBus } from './lib/events.js';
+export type { EventBus, EventBusOptions, Channel, ChannelOptions, SubscribeOptions, BusEvent, Delivery, } from './lib/events.js';
+export { createIntentRegistry, NoIntentHandlerError } from './lib/intents.js';
+export type { IntentRegistry, IntentRegistryOptions, IntentHandlerOptions, IntentCandidate, IntentResult, ResolvePolicy, RaiseOptions, } from './lib/intents.js';

package/src/index.js

@@ -0,0 +1,23 @@
+/**
+ * @braidlabs/data — the local-first data layer.
+ *
+ * Persistence-first: IndexedDB is the source of truth and memory is a derived view. Every record is
+ * enveloped by `@braidlabs/skew` and projected to *this* reader's version on the way out, which is
+ * what lets independently deployed apps read the same store at different contract versions.
+ *
+ * Framework-neutral. Angular bindings live in `@braidlabs/angular-data`.
+ */
+export { createRecordStore } from './lib/record-store.js';
+export { memoryRecordDriver } from './lib/memory-driver.js';
+export { indexedDbRecordDriver } from './lib/indexeddb-driver.js';
+export { withLock, hasCrossContextLocks, outboxFlushLock } from './lib/locks.js';
+export { createDataClient } from './lib/query.js';
+export { drainOutbox } from './lib/flush.js';
+export { createInvalidator, sharedInvalidator, resetSharedInvalidators } from './lib/invalidation.js';
+export { createOutbox, OutboxEntrySchema } from './lib/outbox.js';
+export { createTenancy, partitionKey, TenancyRecordSchema } from './lib/tenancy.js';
+export { copyPartition } from './lib/partitions.js';
+export { fromPull } from './lib/adapters.js';
+export { createEventBus } from './lib/events.js';
+export { createIntentRegistry, NoIntentHandlerError } from './lib/intents.js';
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/data/src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAS1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGlE,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAelD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG7C,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAGtG,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGlE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAGpF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAOpD,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAU7C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAWjD,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC"}

package/src/lib/adapters.d.ts

@@ -0,0 +1,74 @@
+import type { VersionedSchema } from '@braidlabs/skew';
+/**
+ * Protocol adapters: the layer never learns how to fetch.
+ *
+ * Three shapes cover the four protocols teams actually have. Each is a function type rather than a
+ * class or a registration, because the smallest thing that can be substituted is the thing most
+ * likely to be substituted — a REST endpoint replaced by a GraphQL query should not be a change to
+ * this package.
+ *
+ * | Shape     | Covers                                  |
+ * | --------- | --------------------------------------- |
+ * | `Pull`    | REST, RPC, GraphQL queries              |
+ * | `Push`    | GraphQL subscriptions, WebSockets, SSE  |
+ * | `Command` | REST writes, RPC calls, GraphQL mutations |
+ */
+/** Fetches one record. Cancellable, because a query that outlives its subscriber must stop. */
+export type PullAdapter = (key: string, signal: AbortSignal) => Promise<unknown>;
+/**
+ * Sends a write.
+ *
+ * Takes *input*, never a closure, and that constraint comes from the outbox rather than from taste:
+ * a queued command is replayed by a build that may not be the one that queued it.
+ */
+export type CommandAdapter<TInput = unknown> = (input: TInput) => Promise<unknown>;
+/**
+ * A record arriving from the server unbidden, and the key it belongs under.
+ *
+ * Push is the shape that bends the model — it is a third write source alongside optimistic and
+ * confirmed — so it is deliberately expressed as records handed to the layer rather than as a
+ * stream the layer subscribes to. Everything a push writes goes through the same enveloping path as
+ * every other write; otherwise a WebSocket update is the one record in the system with no version
+ * on it, which is exactly the record a fragment two majors behind will read.
+ */
+export interface PushRecord {
+    key: string;
+    value: unknown;
+    /** Tags to mark stale, for queries that hold lists rather than this key. */
+    tags?: string[];
+    /**
+     * Which tenant partition this record belongs to. Defaults to the client's current one.
+     *
+     * One socket often carries events for more than one tenant — an advisor subscribed to every client
+     * they cover, a desk subscribed to every fund. Filing all of it under whichever tenant happened to
+     * be on screen would put one client's position in another's cache, so a stream that knows better
+     * says so.
+     */
+    partition?: string;
+}
+/** What a push adapter writes into. Supplied by the client; never implemented by callers. */
+export interface PushSink {
+    /** Lands one record, enveloped and stamped, and refreshes readers of that key. */
+    receive(record: PushRecord): Promise<void>;
+    /** Reports a stream-level failure without tearing the subscription down. */
+    fail?(error: unknown): void;
+}
+/**
+ * Subscribes to a stream and writes what arrives into `sink`.
+ *
+ * Returns a disposer, or nothing when the `signal` is all the cleanup it needs.
+ */
+export type PushAdapter = (sink: PushSink, signal: AbortSignal) => void | (() => void) | Promise<void | (() => void)>;
+export interface PushConnection<T> {
+    schema: VersionedSchema<T>;
+    source: PushAdapter;
+    /** Applied to every record the stream produces, when the stream reports bare tags. */
+    tags?: (key: string) => string[];
+}
+/**
+ * Adapts a pull into a query's `fetch`.
+ *
+ * Trivial by design — the value is in the *shape* being named, so a team writing a second transport
+ * has something to conform to rather than a signature to reverse-engineer from a query definition.
+ */
+export declare function fromPull(key: string, adapter: PullAdapter): (signal: AbortSignal) => Promise<unknown>;

package/src/lib/adapters.js

@@ -0,0 +1,10 @@
+/**
+ * Adapts a pull into a query's `fetch`.
+ *
+ * Trivial by design — the value is in the *shape* being named, so a team writing a second transport
+ * has something to conform to rather than a signature to reverse-engineer from a query definition.
+ */
+export function fromPull(key, adapter) {
+    return (signal) => adapter(key, signal);
+}
+//# sourceMappingURL=adapters.js.map

package/src/lib/adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../../../../../libs/data/src/lib/adapters.ts"],"names":[],"mappings":"AA2EA;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,OAAoB;IACxD,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AAC1C,CAAC"}

package/src/lib/events.d.ts

@@ -0,0 +1,141 @@
+import type { VersionedSchema } from '@braidlabs/skew';
+import { type FlushResult } from './flush.js';
+import { type BroadcastChannelLike, type Invalidator } from './invalidation.js';
+import type { RecordDriver } from './record-store.js';
+import type { Conflict, ConflictPolicy } from './query.js';
+import { type IntentHandlerOptions, type IntentRegistry, type IntentResult, type RaiseOptions } from './intents.js';
+/**
+ * Eventing across independently deployed applications: channels, durable queues, and conflict.
+ *
+ * This lives in `@braidlabs/data` rather than in Braid because none of it is about composition — it is
+ * about a queue, a lock, and a versioned payload, which is what this package already is. A Module
+ * Federation deployment with no Braid at all should be able to use it, and Braid's context bus should
+ * be able to sit on top rather than beside it.
+ *
+ * **Almost nothing here is new.** Durability is the outbox, one record per entry. Draining is
+ * `drainOutbox`, with its ordering, its cross-context lock, and its give-up rule. Waking another
+ * realm is the invalidator. Surviving version skew is `versioned()`. The parts that are genuinely
+ * new are the two decisions below.
+ *
+ * **1. State is not an event.** FDC3 conflates them: `broadcast` sets a channel's current context
+ * *and* replays it to late joiners, so it means both "this happened" and "this is now true". That
+ * works for a selected row and fails for anything with a verb. Here `broadcast`/`state` is the
+ * former and `emit`/`addEventListener` is the latter.
+ *
+ * **2. Durable fan-out is one queue per consumer, not one queue with acknowledgements.** An
+ * at-least-once event is written once per registered consumer, into that consumer's own queue, and
+ * *deletion on success is the acknowledgement*. It costs N copies of the payload and buys three
+ * things: no new storage shape, no ack bookkeeping to keep consistent, and — the one that matters —
+ * a consumer whose handler keeps failing blocks only itself. A shared entry with an ack set gives
+ * every consumer the same head-of-line blocking.
+ */
+export type Delivery = 'at-most-once' | 'at-least-once';
+export interface BusEvent<T = unknown> {
+    /** Stable per emit, so an at-least-once consumer can dedupe if it must. */
+    eventId: string;
+    channel: string;
+    type: string;
+    payload: T;
+    /** ISO 8601. Used for the retention window. */
+    at: string;
+    /** Which application emitted it. */
+    source: string;
+}
+export interface EventBusOptions {
+    /**
+     * This application's identity, as the outbox's `owner` is. Durable delivery is addressed to it,
+     * and two applications sharing one name will replay each other's events.
+     */
+    consumer: string;
+    /** Tenant partition. Events are scoped like every other record. */
+    partition?: () => string;
+    /** Storage for durable channels. Without it, `at-least-once` is refused rather than downgraded. */
+    driver?: RecordDriver;
+    /**
+     * Every application that may consume a durable event on this origin.
+     *
+     * Fan-out writes one entry per name, so a queue cannot wait for an acknowledgement from a consumer
+     * it does not know exists. In a Braid deployment this comes from the manifests; anywhere else it is
+     * a list. A registered consumer that is not currently mounted is *waiting*, not gone.
+     */
+    consumers?: readonly string[];
+    /** Cross-context wake-up and page-scoped fan-out. Defaults to the shared one for the partition. */
+    invalidator?: Invalidator;
+    /** Origin-scope transport. Injectable for tests; defaults to a `BroadcastChannel`. */
+    broadcastChannel?: (name: string) => BroadcastChannelLike | undefined;
+    /** Attempts before a queued event is abandoned. */
+    maxAttempts?: number;
+    /** Never silent: retention drops and abandoned handlers are reported here. */
+    onEventError?: (message: string, detail?: unknown) => void;
+}
+export interface ChannelOptions {
+    /**
+     * `'page'` reaches every realm on this page; `'origin'` reaches every tab as well.
+     *
+     * Per channel rather than per bus, because the answer differs by channel on the same page: a
+     * selected row is page state, a sign-out is origin-wide. One global setting is how a UI selection
+     * ends up broadcast to five tabs.
+     */
+    scope?: 'page' | 'origin';
+    /** What to do when two publishers disagree about this channel's state. Defaults to `'raise'`. */
+    onConflict?: ConflictPolicy<unknown>;
+    /** How long a queued event stays deliverable. Defaults to one hour. */
+    ttlMs?: number;
+    /** Queue depth per consumer *on this channel*, after which the oldest is dropped loudly. Defaults to 500. */
+    maxDepth?: number;
+    /**
+     * Instances this channel per entity: a fund, a tenant, a portfolio, a conversation.
+     *
+     * `channel('selection', { entity: 'fund:f1' })` and `channel('selection', { entity: 'fund:f2' })`
+     * are two separate contexts that happen to share a shape. State does not cross between them,
+     * events are addressed to one of them, and an origin-scoped pair gets a transport each.
+     *
+     * **Deliberately not a `scope` value.** Reach and instance are different questions and a channel
+     * has to answer both: this fund's selection is page state, while this fund's orders want to reach
+     * every tab. Folding entity into `scope` would force one answer for both.
+     *
+     * Not a security boundary — that is what a partition is. Two entities in one partition are
+     * separated here for correctness and clarity, not for isolation; a different *tenant* belongs in a
+     * different partition, and then none of this applies because the storage differs too.
+     */
+    entity?: string;
+}
+export interface SubscribeOptions {
+    /** The contract version this subscriber speaks. Projected per subscriber, as the context bus does. */
+    as?: number;
+    signal?: AbortSignal;
+    consumer?: string;
+}
+export interface Channel<S = unknown> {
+    readonly name: string;
+    /** Sets this channel's current state. Last value wins; late subscribers receive it. */
+    broadcast(value: S): void;
+    /** The current state, projected to `as`. */
+    state(options?: {
+        as?: number;
+    }): S | undefined;
+    /** Subscribes to state. Called immediately with the current value when there is one. */
+    subscribe(listener: (value: S) => void, options?: SubscribeOptions): () => void;
+    /** Publishes an occurrence. Not replayed unless it is durable and unacknowledged. */
+    emit<T>(type: string, payload: T, options?: {
+        delivery?: Delivery;
+    }): Promise<void>;
+    /** Handles occurrences of one type. */
+    addEventListener<T>(type: string, handler: (event: BusEvent<T>) => void | Promise<void>, options?: SubscribeOptions): () => void;
+    /** The last state conflict raised on this channel, if any. */
+    conflict(): Conflict<unknown> | null;
+    acknowledgeConflict(): void;
+}
+export interface EventBus extends Pick<IntentRegistry, 'candidates'> {
+    channel<S = unknown>(name: string, options?: ChannelOptions): Channel<S>;
+    /** Registers a handler for an intent raised by any application on this page. */
+    addIntentListener<T>(intent: string, options: IntentHandlerOptions<T>): () => void;
+    /** Asks whoever can handle this to handle it. Resolution policy decides between candidates. */
+    raiseIntent<R = unknown>(intent: string, payload: unknown, options?: RaiseOptions): Promise<IntentResult<R>>;
+    /** Declares the contract a state key or event type carries, so delivery can project per reader. */
+    register<T>(type: string, schema: VersionedSchema<T>): void;
+    /** Drains this consumer's queue of durable events. Called on wake-up; call it after mounting. */
+    flush(): Promise<FlushResult>;
+    close(): void;
+}
+export declare function createEventBus(options: EventBusOptions): EventBus;