@honua/app-platform 0.0.20-alpha.0

package/realtime/honua-server.d.ts

@@ -0,0 +1,123 @@
+/**
+ * First-party realtime preset for honua-server's
+ * `/api/v1/streaming/features` Server-Sent Events endpoint.
+ *
+ * The default SSE transport encoder emits `sourceId=` / `layerId=` query
+ * params and assumes events already use the SDK's `RealtimeFeatureEvent`
+ * vocabulary. honua-server instead expects `serviceId=` / `layers=` query
+ * params and emits its own feature-change envelopes. This module packages the
+ * two hooks (`encodeRequest` + `decodeEvent`) the transport already exposes so
+ * consumers do not have to re-implement the same adapter for every app.
+ *
+ * @example Use the preset options with the SSE transport.
+ * ```ts
+ * import {
+ *   createRealtimeServerSentEventsTransport,
+ *   honuaServerRealtimePreset,
+ * } from "@honua/sdk-js/realtime";
+ *
+ * const transport = createRealtimeServerSentEventsTransport({
+ *   url: "https://honua.example/api/v1/streaming/features",
+ *   ...honuaServerRealtimePreset(),
+ * });
+ * ```
+ *
+ * @example Or use the convenience factory.
+ * ```ts
+ * import { createHonuaServerRealtimeSubscription } from "@honua/sdk-js/realtime";
+ *
+ * const transport = createHonuaServerRealtimeSubscription({
+ *   baseUrl: "https://honua.example",
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { FeatureId } from "../contract/types.js";
+import type { RealtimeServerSentEventsTransportOptions } from "./sse.js";
+import type { RealtimeFeatureEvent, RealtimeFeatureTransport, RealtimeSubscriptionRequest } from "./types.js";
+/** Default streaming-features path served by honua-server. */
+export declare const HONUA_SERVER_STREAMING_FEATURES_PATH = "/api/v1/streaming/features";
+/**
+ * Encode a `RealtimeSubscriptionRequest` into honua-server's
+ * `/api/v1/streaming/features` query contract: `serviceId=` (not `sourceId=`)
+ * and `layers=` (not `layerId=`). The remaining filter/resume params match the
+ * default encoder so cursors, watermarks, and where-clauses keep working.
+ */
+export declare function encodeHonuaServerRealtimeRequest(url: URL, request: RealtimeSubscriptionRequest): URL;
+/**
+ * Shape of a single change carried by a honua-server feature-change envelope.
+ * honua-server reports the change kind via `op` (`insert` / `update` / `delete`)
+ * alongside the affected feature or feature id.
+ */
+export interface HonuaServerFeatureChange<TFeature = unknown> {
+    readonly op: "insert" | "update" | "delete" | "snapshot";
+    readonly featureId?: FeatureId;
+    readonly feature?: TFeature;
+    readonly version?: number;
+    readonly updatedAt?: string;
+}
+/**
+ * Shape of the envelope honua-server writes to the
+ * `/api/v1/streaming/features` SSE stream. Each envelope carries the service /
+ * layer scope, ordering metadata, and one or more feature changes.
+ */
+export interface HonuaServerFeatureChangeEnvelope<TFeature = unknown> {
+    readonly serviceId?: string;
+    readonly layerId?: string | number;
+    readonly eventId?: string;
+    readonly sequence?: number;
+    readonly cursor?: string;
+    readonly watermark?: string;
+    readonly timestamp?: string;
+    readonly deltaToken?: string;
+    /** `change` (or `feature-change`) is the default envelope kind. */
+    readonly kind?: string;
+    readonly changes?: ReadonlyArray<HonuaServerFeatureChange<TFeature>>;
+    /** Single-change envelopes inline the change instead of a `changes` array. */
+    readonly op?: HonuaServerFeatureChange<TFeature>["op"];
+    readonly featureId?: FeatureId;
+    readonly feature?: TFeature;
+    readonly version?: number;
+    readonly updatedAt?: string;
+    /** Pass-through status / heartbeat / error envelopes. */
+    readonly type?: string;
+}
+/**
+ * Decode a honua-server `/api/v1/streaming/features` envelope into the SDK's
+ * `RealtimeFeatureEvent`. Feature-change envelopes become `delta` events
+ * (batching upserts and deletes); status, heartbeat, and error envelopes that
+ * already speak the SDK vocabulary pass through unchanged.
+ */
+export declare function decodeHonuaServerRealtimeEvent<TFeature = unknown>(payload: unknown): RealtimeFeatureEvent<TFeature>;
+/**
+ * Reusable hook bundle for honua-server's streaming-features endpoint. Spread
+ * this into {@link createRealtimeServerSentEventsTransport} options to opt into
+ * honua-server's query-param contract and feature-change decoding.
+ */
+export declare function honuaServerRealtimePreset<TFeature = unknown>(): Pick<RealtimeServerSentEventsTransportOptions<TFeature>, "encodeRequest" | "decodeEvent">;
+export interface CreateHonuaServerRealtimeSubscriptionOptions<TFeature = unknown> extends Omit<RealtimeServerSentEventsTransportOptions<TFeature>, "url" | "encodeRequest" | "decodeEvent"> {
+    /**
+     * honua-server origin, e.g. `https://honua.example`. The
+     * `/api/v1/streaming/features` path is appended automatically. Mutually
+     * exclusive with {@link CreateHonuaServerRealtimeSubscriptionOptions.url}.
+     */
+    readonly baseUrl?: string;
+    /**
+     * Full streaming-features URL. Use this when the endpoint lives at a
+     * non-default path. Overrides {@link CreateHonuaServerRealtimeSubscriptionOptions.baseUrl}.
+     */
+    readonly url?: string;
+    /**
+     * Override the honua-server feature-change decoder while keeping the
+     * `serviceId=` / `layers=` query encoding.
+     */
+    readonly decodeEvent?: RealtimeServerSentEventsTransportOptions<TFeature>["decodeEvent"];
+}
+/**
+ * Convenience factory that builds a {@link RealtimeFeatureTransport} wired to
+ * honua-server's `/api/v1/streaming/features` endpoint with the
+ * {@link honuaServerRealtimePreset} hooks applied.
+ */
+export declare function createHonuaServerRealtimeSubscription<TFeature = unknown>(options: CreateHonuaServerRealtimeSubscriptionOptions<TFeature>): RealtimeFeatureTransport<TFeature>;
+//# sourceMappingURL=honua-server.d.ts.map

package/realtime/honua-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"honua-server.d.ts","sourceRoot":"","sources":["../../../src/realtime/honua-server.ts"],"names":[],"mappings":"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"}

package/realtime/honua-server.js

@@ -0,0 +1,188 @@
+/**
+ * First-party realtime preset for honua-server's
+ * `/api/v1/streaming/features` Server-Sent Events endpoint.
+ *
+ * The default SSE transport encoder emits `sourceId=` / `layerId=` query
+ * params and assumes events already use the SDK's `RealtimeFeatureEvent`
+ * vocabulary. honua-server instead expects `serviceId=` / `layers=` query
+ * params and emits its own feature-change envelopes. This module packages the
+ * two hooks (`encodeRequest` + `decodeEvent`) the transport already exposes so
+ * consumers do not have to re-implement the same adapter for every app.
+ *
+ * @example Use the preset options with the SSE transport.
+ * ```ts
+ * import {
+ *   createRealtimeServerSentEventsTransport,
+ *   honuaServerRealtimePreset,
+ * } from "@honua/sdk-js/realtime";
+ *
+ * const transport = createRealtimeServerSentEventsTransport({
+ *   url: "https://honua.example/api/v1/streaming/features",
+ *   ...honuaServerRealtimePreset(),
+ * });
+ * ```
+ *
+ * @example Or use the convenience factory.
+ * ```ts
+ * import { createHonuaServerRealtimeSubscription } from "@honua/sdk-js/realtime";
+ *
+ * const transport = createHonuaServerRealtimeSubscription({
+ *   baseUrl: "https://honua.example",
+ * });
+ * ```
+ *
+ * @module
+ */
+import { trimTrailingSlashes } from "../core/path-utils.js";
+import { createRealtimeServerSentEventsTransport } from "./sse.js";
+/** Default streaming-features path served by honua-server. */
+export const HONUA_SERVER_STREAMING_FEATURES_PATH = "/api/v1/streaming/features";
+/**
+ * Encode a `RealtimeSubscriptionRequest` into honua-server's
+ * `/api/v1/streaming/features` query contract: `serviceId=` (not `sourceId=`)
+ * and `layers=` (not `layerId=`). The remaining filter/resume params match the
+ * default encoder so cursors, watermarks, and where-clauses keep working.
+ */
+export function encodeHonuaServerRealtimeRequest(url, request) {
+    url.searchParams.set("serviceId", String(request.sourceId));
+    if (request.layerId !== undefined)
+        url.searchParams.set("layers", String(request.layerId));
+    if (request.requestId)
+        url.searchParams.set("requestId", request.requestId);
+    if (request.mode)
+        url.searchParams.set("mode", request.mode);
+    if (request.where)
+        url.searchParams.set("where", request.where);
+    if (request.fields?.length)
+        url.searchParams.set("fields", request.fields.join(","));
+    if (request.cursor ?? request.resumeFrom?.cursor) {
+        url.searchParams.set("cursor", request.cursor ?? request.resumeFrom?.cursor ?? "");
+    }
+    if (request.watermark ?? request.resumeFrom?.watermark) {
+        url.searchParams.set("watermark", request.watermark ?? request.resumeFrom?.watermark ?? "");
+    }
+    if (request.timestamp ?? request.resumeFrom?.timestamp) {
+        url.searchParams.set("timestamp", request.timestamp ?? request.resumeFrom?.timestamp ?? "");
+    }
+    if (request.deltaToken ?? request.resumeFrom?.deltaToken) {
+        url.searchParams.set("deltaToken", request.deltaToken ?? request.resumeFrom?.deltaToken ?? "");
+    }
+    if (request.resumeFrom?.sequence !== undefined) {
+        url.searchParams.set("sequence", String(request.resumeFrom.sequence));
+    }
+    if (request.spatialFilter !== undefined)
+        url.searchParams.set("spatialFilter", JSON.stringify(request.spatialFilter));
+    if (request.metadata !== undefined)
+        url.searchParams.set("metadata", JSON.stringify(request.metadata));
+    return url;
+}
+/**
+ * Decode a honua-server `/api/v1/streaming/features` envelope into the SDK's
+ * `RealtimeFeatureEvent`. Feature-change envelopes become `delta` events
+ * (batching upserts and deletes); status, heartbeat, and error envelopes that
+ * already speak the SDK vocabulary pass through unchanged.
+ */
+export function decodeHonuaServerRealtimeEvent(payload) {
+    if (!isRecord(payload))
+        throw new Error("honua-server streaming payload must be a JSON object.");
+    const envelope = payload;
+    // Status / heartbeat / error envelopes already use the SDK vocabulary.
+    if (typeof envelope.type === "string" && envelope.type !== "change" && envelope.type !== "feature-change") {
+        return payload;
+    }
+    const changes = collectChanges(envelope);
+    if (changes.length === 0) {
+        throw new Error("honua-server feature-change envelope is missing changes.");
+    }
+    const base = {
+        eventId: envelope.eventId,
+        sequence: envelope.sequence,
+        cursor: envelope.cursor,
+        watermark: envelope.watermark,
+        timestamp: envelope.timestamp,
+        deltaToken: envelope.deltaToken,
+    };
+    const upserts = [];
+    const deletes = [];
+    for (const change of changes) {
+        if (change.featureId === undefined) {
+            throw new Error("honua-server feature change is missing featureId.");
+        }
+        if (change.op === "delete") {
+            deletes.push({ id: change.featureId, version: change.version, updatedAt: change.updatedAt });
+            continue;
+        }
+        if (change.feature === undefined) {
+            throw new Error(`honua-server ${change.op} change is missing feature payload.`);
+        }
+        upserts.push({
+            id: change.featureId,
+            sourceId: envelope.serviceId,
+            feature: change.feature,
+            version: change.version,
+            updatedAt: change.updatedAt,
+        });
+    }
+    return {
+        type: "delta",
+        ...base,
+        ...(upserts.length ? { upserts } : {}),
+        ...(deletes.length ? { deletes: deletes.map((entry) => ({ ...entry, sourceId: envelope.serviceId })) } : {}),
+    };
+}
+/**
+ * Reusable hook bundle for honua-server's streaming-features endpoint. Spread
+ * this into {@link createRealtimeServerSentEventsTransport} options to opt into
+ * honua-server's query-param contract and feature-change decoding.
+ */
+export function honuaServerRealtimePreset() {
+    return {
+        encodeRequest: (url, request) => {
+            encodeHonuaServerRealtimeRequest(url, request);
+        },
+        decodeEvent: (decodeHonuaServerRealtimeEvent),
+    };
+}
+/**
+ * Convenience factory that builds a {@link RealtimeFeatureTransport} wired to
+ * honua-server's `/api/v1/streaming/features` endpoint with the
+ * {@link honuaServerRealtimePreset} hooks applied.
+ */
+export function createHonuaServerRealtimeSubscription(options) {
+    const { baseUrl, url, decodeEvent, ...rest } = options;
+    const resolvedUrl = url ?? resolveStreamingUrl(baseUrl);
+    const preset = honuaServerRealtimePreset();
+    return createRealtimeServerSentEventsTransport({
+        ...rest,
+        url: resolvedUrl,
+        encodeRequest: preset.encodeRequest,
+        decodeEvent: decodeEvent ?? preset.decodeEvent,
+    });
+}
+function resolveStreamingUrl(baseUrl) {
+    if (!baseUrl) {
+        throw new Error("createHonuaServerRealtimeSubscription requires either `url` or `baseUrl`.");
+    }
+    // Linear trim (no anchored `\/+$` regex) to avoid polynomial backtracking on
+    // adversarial input — mirrors the rest of the SDK's path handling.
+    return `${trimTrailingSlashes(baseUrl)}${HONUA_SERVER_STREAMING_FEATURES_PATH}`;
+}
+function collectChanges(envelope) {
+    if (Array.isArray(envelope.changes))
+        return envelope.changes;
+    if (envelope.op !== undefined) {
+        return [
+            {
+                op: envelope.op,
+                featureId: envelope.featureId,
+                feature: envelope.feature,
+                version: envelope.version,
+                updatedAt: envelope.updatedAt,
+            },
+        ];
+    }
+    return [];
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/realtime/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@honua/sdk-js/realtime` — realtime transport adapters (Server-Sent Events today,
+ * WebSocket/WebTransport adapters land alongside future server endpoints).
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver contract
+ *   — the surface may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+export { createRealtimeServerSentEventsTransport, decodeRealtimeServerSentEvent, encodeDefaultRealtimeRequest, } from "./sse.js";
+export type { RealtimeServerSentEventSource, RealtimeServerSentEventSourceFactory, RealtimeServerSentEventsTransportOptions, } from "./sse.js";
+export { createHonuaServerRealtimeSubscription, decodeHonuaServerRealtimeEvent, encodeHonuaServerRealtimeRequest, honuaServerRealtimePreset, HONUA_SERVER_STREAMING_FEATURES_PATH, } from "./honua-server.js";
+export type { CreateHonuaServerRealtimeSubscriptionOptions, HonuaServerFeatureChange, HonuaServerFeatureChangeEnvelope, } from "./honua-server.js";
+export { emptyRealtimeFeatureState, reconcileRealtimeStaleness, reduceRealtimeFeatureState, realtimeFeatureKey, realtimeResumeCheckpoint, realtimeSubscriptionKey, } from "./reducer.js";
+export { createRealtimeFeatureStore } from "./store.js";
+export type { RealtimeFeatureStore } from "./store.js";
+export { filterRealtimeSelection, reconcileRealtimeSelection } from "./exploration.js";
+export { selectRealtimeDetail, selectRealtimeFeatureRecordMap, selectRealtimeFeatureRecords, selectRealtimeFeatureTombstones, selectRealtimeFeatures, } from "./projections.js";
+export type { RealtimeDetailSelectorOptions, RealtimeDetailState, RealtimeFeatureRecordSelectorOptions, RealtimeFeatureReference, } from "./projections.js";
+export type { RealtimeConnectionStatus, RealtimeDeleteEvent, RealtimeDeletePatch, RealtimeDeltaEvent, RealtimeErrorEvent, RealtimeFeatureEvent, RealtimeFeatureEventBase, RealtimeFeatureObserver, RealtimeFeaturePatch, RealtimeFeatureRecord, RealtimeFeatureState, RealtimeFeatureTombstone, RealtimeFeatureTransport, RealtimeHeartbeatEvent, RealtimeReducerOptions, RealtimeResumeCheckpoint, RealtimeResumeMode, RealtimeSnapshotEvent, RealtimeStateListener, RealtimeStatusEvent, RealtimeStalenessOptions, RealtimeSubscriptionIdentity, RealtimeSubscriptionHandle, RealtimeSubscriptionMode, RealtimeSubscriptionRequest, RealtimeTransportCapabilities, RealtimeTransportKind, RealtimeUpsertEvent, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/realtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/realtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,uCAAuC,EACvC,6BAA6B,EAC7B,4BAA4B,GAC7B,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,6BAA6B,EAC7B,oCAAoC,EACpC,wCAAwC,GACzC,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,qCAAqC,EACrC,8BAA8B,EAC9B,gCAAgC,EAChC,yBAAyB,EACzB,oCAAoC,GACrC,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,4CAA4C,EAC5C,wBAAwB,EACxB,gCAAgC,GACjC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,yBAAyB,EACzB,0BAA0B,EAC1B,0BAA0B,EAC1B,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AACxD,YAAY,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AACvF,OAAO,EACL,oBAAoB,EACpB,8BAA8B,EAC9B,4BAA4B,EAC5B,+BAA+B,EAC/B,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,6BAA6B,EAC7B,mBAAmB,EACnB,oCAAoC,EACpC,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,wBAAwB,EACxB,4BAA4B,EAC5B,0BAA0B,EAC1B,wBAAwB,EACxB,2BAA2B,EAC3B,6BAA6B,EAC7B,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/realtime/index.js

@@ -0,0 +1,14 @@
+/**
+ * `@honua/sdk-js/realtime` — realtime transport adapters (Server-Sent Events today,
+ * WebSocket/WebTransport adapters land alongside future server endpoints).
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver contract
+ *   — the surface may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+export { createRealtimeServerSentEventsTransport, decodeRealtimeServerSentEvent, encodeDefaultRealtimeRequest, } from "./sse.js";
+export { createHonuaServerRealtimeSubscription, decodeHonuaServerRealtimeEvent, encodeHonuaServerRealtimeRequest, honuaServerRealtimePreset, HONUA_SERVER_STREAMING_FEATURES_PATH, } from "./honua-server.js";
+export { emptyRealtimeFeatureState, reconcileRealtimeStaleness, reduceRealtimeFeatureState, realtimeFeatureKey, realtimeResumeCheckpoint, realtimeSubscriptionKey, } from "./reducer.js";
+export { createRealtimeFeatureStore } from "./store.js";
+export { filterRealtimeSelection, reconcileRealtimeSelection } from "./exploration.js";
+export { selectRealtimeDetail, selectRealtimeFeatureRecordMap, selectRealtimeFeatureRecords, selectRealtimeFeatureTombstones, selectRealtimeFeatures, } from "./projections.js";

package/realtime/projections.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Projection helpers for map, table, and detail views that consume realtime
+ * feature state.
+ *
+ * @module
+ */
+import type { FeatureId, SourceId } from "../contract/types.js";
+import type { RealtimeFeatureRecord, RealtimeFeatureState, RealtimeFeatureTombstone } from "./types.js";
+export interface RealtimeFeatureRecordSelectorOptions<TFeature = unknown> {
+    readonly sourceId?: SourceId;
+    readonly sort?: (left: RealtimeFeatureRecord<TFeature>, right: RealtimeFeatureRecord<TFeature>) => number;
+}
+export interface RealtimeFeatureReference {
+    readonly id: FeatureId;
+    readonly sourceId?: SourceId;
+}
+export interface RealtimeDetailSelectorOptions {
+    readonly sourceId?: SourceId;
+}
+export interface RealtimeDetailState<TFeature = unknown> {
+    readonly status: "present" | "deleted" | "missing";
+    readonly record?: RealtimeFeatureRecord<TFeature>;
+    readonly tombstone?: RealtimeFeatureTombstone;
+}
+export declare function selectRealtimeFeatureRecords<TFeature>(state: RealtimeFeatureState<TFeature>, options?: RealtimeFeatureRecordSelectorOptions<TFeature>): RealtimeFeatureRecord<TFeature>[];
+export declare function selectRealtimeFeatures<TFeature>(state: RealtimeFeatureState<TFeature>, options?: RealtimeFeatureRecordSelectorOptions<TFeature>): TFeature[];
+export declare function selectRealtimeFeatureRecordMap<TFeature>(state: RealtimeFeatureState<TFeature>, options?: RealtimeFeatureRecordSelectorOptions<TFeature>): Readonly<Record<string, RealtimeFeatureRecord<TFeature>>>;
+export declare function selectRealtimeFeatureTombstones(state: RealtimeFeatureState<unknown>, options?: RealtimeDetailSelectorOptions): RealtimeFeatureTombstone[];
+export declare function selectRealtimeDetail<TFeature>(state: RealtimeFeatureState<TFeature>, target: FeatureId | RealtimeFeatureReference, options?: RealtimeDetailSelectorOptions): RealtimeDetailState<TFeature>;
+//# sourceMappingURL=projections.d.ts.map

package/realtime/projections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projections.d.ts","sourceRoot":"","sources":["../../../src/realtime/projections.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAExG,MAAM,WAAW,oCAAoC,CAAC,QAAQ,GAAG,OAAO;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,qBAAqB,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAC;CAC3G;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CAC9B;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB,CAAC,QAAQ,GAAG,OAAO;IACrD,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,wBAAwB,CAAC;CAC/C;AAED,wBAAgB,4BAA4B,CAAC,QAAQ,EACnD,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EACrC,OAAO,GAAE,oCAAoC,CAAC,QAAQ,CAAM,GAC3D,qBAAqB,CAAC,QAAQ,CAAC,EAAE,CAGnC;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAC7C,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EACrC,OAAO,GAAE,oCAAoC,CAAC,QAAQ,CAAM,GAC3D,QAAQ,EAAE,CAEZ;AAED,wBAAgB,8BAA8B,CAAC,QAAQ,EACrD,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EACrC,OAAO,GAAE,oCAAoC,CAAC,QAAQ,CAAM,GAC3D,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAM3D;AAED,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,oBAAoB,CAAC,OAAO,CAAC,EACpC,OAAO,GAAE,6BAAkC,GAC1C,wBAAwB,EAAE,CAE5B;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAC3C,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EACrC,MAAM,EAAE,SAAS,GAAG,wBAAwB,EAC5C,OAAO,GAAE,6BAAkC,GAC1C,mBAAmB,CAAC,QAAQ,CAAC,CAiB/B"}

package/realtime/projections.js

@@ -0,0 +1,51 @@
+/**
+ * Projection helpers for map, table, and detail views that consume realtime
+ * feature state.
+ *
+ * @module
+ */
+import { realtimeFeatureKey } from "./reducer.js";
+export function selectRealtimeFeatureRecords(state, options = {}) {
+    const records = Object.values(state.records).filter((record) => matchesSource(record, options.sourceId));
+    return options.sort ? [...records].sort(options.sort) : records;
+}
+export function selectRealtimeFeatures(state, options = {}) {
+    return selectRealtimeFeatureRecords(state, options).map((record) => record.feature);
+}
+export function selectRealtimeFeatureRecordMap(state, options = {}) {
+    const records = {};
+    for (const record of selectRealtimeFeatureRecords(state, options)) {
+        records[record.key] = record;
+    }
+    return records;
+}
+export function selectRealtimeFeatureTombstones(state, options = {}) {
+    return Object.values(state.tombstones).filter((tombstone) => matchesSource(tombstone, options.sourceId));
+}
+export function selectRealtimeDetail(state, target, options = {}) {
+    const key = realtimeReferenceKey(target, options.sourceId);
+    const record = state.records[key];
+    if (record) {
+        return {
+            status: "present",
+            record,
+        };
+    }
+    const tombstone = state.tombstones[key];
+    if (tombstone) {
+        return {
+            status: "deleted",
+            tombstone,
+        };
+    }
+    return { status: "missing" };
+}
+function matchesSource(record, sourceId) {
+    return sourceId === undefined || record.sourceId === sourceId;
+}
+function realtimeReferenceKey(target, sourceId) {
+    if (typeof target === "object" && target !== null) {
+        return realtimeFeatureKey(target.sourceId ?? sourceId, target.id);
+    }
+    return realtimeFeatureKey(sourceId, target);
+}

package/realtime/reducer.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Pure reducer helpers for realtime feature state.
+ *
+ * @module
+ */
+import type { FeatureId, SourceId } from "../contract/types.js";
+import type { RealtimeFeatureEvent, RealtimeFeatureState, RealtimeReducerOptions, RealtimeResumeCheckpoint, RealtimeStalenessOptions, RealtimeSubscriptionIdentity } from "./types.js";
+export declare function emptyRealtimeFeatureState<TFeature = unknown>(): RealtimeFeatureState<TFeature>;
+export declare function realtimeFeatureKey(sourceId: SourceId | undefined, id: FeatureId): string;
+export declare function realtimeSubscriptionKey(request: RealtimeSubscriptionIdentity): string;
+export declare function realtimeResumeCheckpoint<TFeature>(state: RealtimeFeatureState<TFeature>): RealtimeResumeCheckpoint | undefined;
+export declare function reduceRealtimeFeatureState<TFeature>(state: RealtimeFeatureState<TFeature>, event: RealtimeFeatureEvent<TFeature>, options?: RealtimeReducerOptions): RealtimeFeatureState<TFeature>;
+export declare function reconcileRealtimeStaleness<TFeature>(state: RealtimeFeatureState<TFeature>, options: RealtimeStalenessOptions): RealtimeFeatureState<TFeature>;
+//# sourceMappingURL=reducer.d.ts.map

package/realtime/reducer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reducer.d.ts","sourceRoot":"","sources":["../../../src/realtime/reducer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAEV,oBAAoB,EAGpB,oBAAoB,EAEpB,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,4BAA4B,EAC7B,MAAM,YAAY,CAAC;AAKpB,wBAAgB,yBAAyB,CAAC,QAAQ,GAAG,OAAO,KAAK,oBAAoB,CAAC,QAAQ,CAAC,CAQ9F;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAAE,EAAE,EAAE,SAAS,GAAG,MAAM,CAExF;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CASrF;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAC/C,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GACpC,wBAAwB,GAAG,SAAS,CAGtC;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EACjD,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EACrC,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EACrC,OAAO,GAAE,sBAA2B,GACnC,oBAAoB,CAAC,QAAQ,CAAC,CAuEhC;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EACjD,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EACrC,OAAO,EAAE,wBAAwB,GAChC,oBAAoB,CAAC,QAAQ,CAAC,CAUhC"}