@ultimat3/realtime 1.0.0

package/src/hooks.ts

@@ -0,0 +1,230 @@
+// The four calls a component makes: one live query, one connection view, one mutator call, one
+// queue view. Nothing here is a reactive runtime — realtime never imports solid-js, so every
+// accessor is a closure over the `SignalFactory` the registered `LiveClient` was built with, and
+// every hook resolves that client through one ambient seam rather than a context per surface.
+
+import type { LiveClient, LiveHandle, LiveQueryRef, MutatorRef } from './client';
+import { LiveClientMissingError } from './errors';
+import type { JsonValue, Row } from './json';
+import type { LocalTx } from './local-store';
+import type { ConflictStrategy } from './rebase';
+
+/** What `setLiveClient` holds. The version signal is the queue's only reactive handle — see below. */
+interface Registered {
+  readonly client: LiveClient;
+  /** Read to subscribe, bumped to invalidate: `OfflineQueue` stores plain arrays, not signals. */
+  readonly version: () => number;
+  readonly bump: () => void;
+}
+
+let registered: Registered | null = null;
+
+/** Register once, in the app entry, before the first render. One app, one socket, one client. */
+export function setLiveClient(client: LiveClient): void {
+  const [version, setVersion] = client.signal<number>(0);
+  const bump = (): void => {
+    setVersion(version() + 1);
+  };
+  registered = { client, version, bump };
+  // Closes the gap a direct call can't: a reconnect drains automatically inside `connect()`, and
+  // an ack/fail frame arrives asynchronously inside `#onFrame` — neither is awaited by any hook, so
+  // this is the only path that reaches them. The direct `bump()` calls below stay too: they fire at
+  // the earliest possible moment for the call that made them, and a redundant bump is harmless.
+  client.onQueueChange(bump);
+}
+
+/** For tests: drop the registration so cases stay independent. */
+export function clearLiveClient(): void {
+  registered = null;
+}
+
+export function hasLiveClient(): boolean {
+  return registered !== null;
+}
+
+function live(hook: string): Registered {
+  if (registered === null) throw new LiveClientMissingError({ hook });
+  return registered;
+}
+
+// ---- useLive ------------------------------------------------------------------------------------
+
+/** The query's input, or a thunk returning it. The thunk is read once — see `useLive`. */
+export type LiveInput = JsonValue | (() => JsonValue);
+
+/**
+ * A callable result set: `feed()` are the rows, `feed.state()` / `feed.cursor()` /
+ * `feed.unsubscribe()` are the rest of the `LiveHandle` hanging off it.
+ */
+export type LiveRows<R extends Row = Row> = (() => readonly R[]) & Omit<LiveHandle<R>, 'rows'>;
+
+/**
+ * Subscribe to a live query. `query` is anything carrying a `name`, which a `@ultimat3/query`
+ * `Query` satisfies structurally — realtime is tier 3, so it names the shape rather than importing
+ * the package sideways.
+ *
+ * A thunk `input` is read **once**, at subscribe time: tier 3 has no reactive runtime of its own,
+ * so nothing re-runs it when its dependencies change. Changing input means a new subscription.
+ * The caller owns `unsubscribe` — nothing here disposes on unmount, because nothing here knows
+ * what a mount is.
+ */
+export function useLive<R extends Row = Row>(query: LiveQueryRef, input: LiveInput): LiveRows<R> {
+  const handle = live('useLive').client.useLive<R>(
+    query,
+    typeof input === 'function' ? input() : input,
+  );
+  return Object.assign((): readonly R[] => handle.rows(), {
+    state: handle.state,
+    cursor: handle.cursor,
+    unsubscribe: handle.unsubscribe,
+  });
+}
+
+// ---- useConnection ------------------------------------------------------------------------------
+
+export interface Connection {
+  readonly offline: boolean;
+  readonly online: boolean;
+  /** Epoch ms of the next reconnect attempt; `null` while the socket is up. */
+  readonly reconnectAt: number | null;
+  /** The buildId the server announced, or `null` while this build is current. */
+  readonly updateAvailable: string | null;
+}
+
+/**
+ * The socket, as four booleans and two values. Every member is a **getter**, so a read inside a
+ * tracking scope reaches the underlying signal; a snapshot object would freeze the answer at the
+ * moment the component rendered and never say "offline" again.
+ */
+export function useConnection(): Connection {
+  const client = live('useConnection').client;
+  return {
+    get offline() {
+      return !client.connected;
+    },
+    get online() {
+      return client.connected;
+    },
+    get reconnectAt() {
+      return client.reconnectAt();
+    },
+    get updateAvailable() {
+      return client.appUpdateAvailable();
+    },
+  };
+}
+
+// ---- useMutation --------------------------------------------------------------------------------
+
+/**
+ * Both spellings of a conflict strategy: realtime's `custom()` (`{ kind: 'custom' }`, merging rows)
+ * and `@ultimat3/action`'s (`{ strategy: 'custom' }`, merging parsed outputs).
+ */
+export type ConflictLike = ConflictStrategy | { readonly strategy: 'custom' };
+
+/**
+ * What a hook needs from a mutator: the name it queues under, and the optimistic twin. A
+ * `@ultimat3/action` `Mutator` satisfies it structurally.
+ *
+ * `local` is declared with **method syntax** on purpose. TypeScript relates method parameters
+ * bivariantly, so a `Mutator` whose `local` takes its own parsed input and its own `tx` assigns
+ * here with no cast at the call site; written as a function-typed property, `strictFunctionTypes`
+ * would reject exactly that mutator. The parameters are `unknown` because this layer never reads
+ * them — it binds them and hands the closure to the client.
+ */
+export interface MutatorLike {
+  readonly name: string;
+  local?(tx: unknown, input: unknown): void;
+  readonly entity?: string;
+  readonly conflict?: ConflictLike;
+}
+
+/** A callable mutator with its own queue depth attached. */
+export type Mutate = ((input: JsonValue) => Promise<void>) & {
+  /** Queued mutations of this mutator. Always `0` at tier 2, where nothing is queued. */
+  readonly pending: number;
+};
+
+/**
+ * Call a mutator: optimistic twin, rebase entry, durable queue, drain — all of it inside
+ * `LiveClient.mutate`. `pending` is a getter, so it stays reactive for as long as the component
+ * reads it; it refreshes on every call routed through this hook and on `useMutationQueue().drain`.
+ */
+export function useMutation(mutator: MutatorLike): Mutate {
+  const state = live('useMutation');
+  const ref = mutatorRef(mutator);
+  const call = async (input: JsonValue): Promise<void> => {
+    await state.client.mutate(ref, input);
+    state.bump();
+  };
+  Object.defineProperty(call, 'pending', {
+    get: (): number => {
+      state.version();
+      const queue = state.client.queue;
+      return queue === undefined
+        ? 0
+        : queue.pending().filter((mutation) => mutation.name === mutator.name).length;
+    },
+  });
+  // `defineProperty` cannot widen a function type, so the assembled shape is asserted once, here.
+  return call as Mutate;
+}
+
+// ---- useMutationQueue ---------------------------------------------------------------------------
+
+export interface MutationQueue {
+  /** Queued and not yet acknowledged, across every mutator. */
+  readonly pending: number;
+  /** Terminally failed — a policy denial or a validation error, kept for the UI, never retried. */
+  readonly failed: number;
+  drain(): Promise<void>;
+}
+
+/** The whole durable queue, as two counts and the one command that empties it. */
+export function useMutationQueue(): MutationQueue {
+  const state = live('useMutationQueue');
+  return {
+    get pending() {
+      state.version();
+      return state.client.queue?.pending().length ?? 0;
+    },
+    get failed() {
+      state.version();
+      const all = state.client.queue?.all() ?? [];
+      return all.filter((mutation) => mutation.status === 'failed').length;
+    },
+    drain: async () => {
+      await state.client.drain();
+      state.bump();
+    },
+  };
+}
+
+/** The hook's mutator, as the client's. Only the twin needs binding; the rest is carried through. */
+function mutatorRef(mutator: MutatorLike): MutatorRef {
+  const conflict = replayable(mutator.conflict);
+  return {
+    name: mutator.name,
+    // Called back through the mutator rather than through a hoisted reference: `local` may be
+    // written as a method, and an unbound method loses the receiver its body could read.
+    ...(mutator.local === undefined
+      ? {}
+      : {
+          local: (tx: LocalTx, input: JsonValue) => {
+            mutator.local?.(tx, input);
+          },
+        }),
+    ...(mutator.entity === undefined ? {} : { entity: mutator.entity }),
+    ...(conflict === undefined ? {} : { conflict }),
+  };
+}
+
+/**
+ * `@ultimat3/action`'s `custom(merge)` merges parsed *outputs*; realtime's merges *rows*. Only the
+ * second is a `CustomMerge` `reconcile` can replay, so the other spelling is dropped rather than
+ * handed to a rebase that would call it with the wrong argument — the log then takes its default.
+ */
+function replayable(conflict: ConflictLike | undefined): ConflictStrategy | undefined {
+  if (conflict === undefined || typeof conflict === 'string') return conflict;
+  return 'kind' in conflict ? conflict : undefined;
+}

package/src/index.ts

@@ -0,0 +1,328 @@
+// Public API. Explicit, tier by tier: channels, live queries, local-first sync, plus the wire and
+// the server/client halves that carry all three.
+
+export { type ChangeBufferOptions, RingChangeBuffer } from './change-buffer';
+// ---- tier 2: live queries ----------------------------------------------------------------------
+export {
+  type ChangeEvent,
+  type ChangeFeed,
+  type ChangeFeedStartOptions,
+  type ChangeOp,
+  formatLsn,
+  InMemoryChangeFeed,
+  type InMemoryChangeFeedOptions,
+  PgLogicalReplicationFeed,
+  type PgLogicalReplicationOptions,
+  parseLsn,
+} from './changefeed';
+export {
+  type ChangeFeedSelection,
+  DEFAULT_REPLICATION_PUBLICATION,
+  DEFAULT_REPLICATION_SLOT,
+  REPLICATION_ENV_KEYS,
+  type ReplicationEnvironment,
+  replicatorLockKey,
+  type SelectChangeFeedOptions,
+  selectChangeFeed,
+} from './changefeed-env';
+
+// ---- tier 1: channels + presence ---------------------------------------------------------------
+export {
+  ChannelHub,
+  type ChannelHubOptions,
+  channelFrame,
+  type Topic,
+  type TopicGuard,
+  type TopicGuardArgs,
+  type TopicGuardResult,
+  topic,
+} from './channel';
+// ---- server + client halves -------------------------------------------------------------------
+export {
+  applyPatches,
+  type ClientSocket,
+  LiveClient,
+  type LiveClientOptions,
+  type LiveHandle,
+  type LiveQueryRef,
+  type LiveState,
+  type MutatorRef,
+  type SignalFactory,
+} from './client';
+// ---- reconnect ----------------------------------------------------------------------------------
+export {
+  advance,
+  CURSOR_ID_LIMIT,
+  DIGEST_UNVERIFIED,
+  defaultReconnectBudget,
+  digestOf,
+  type LiveCursor,
+  makeCursor,
+  type ReconnectBudget,
+  type ResumeDecision,
+  type ResumeDeps,
+  type ResumeReason,
+  type ResumeResult,
+  type ResumeSource,
+  resumeFrom,
+  shouldResnapshot,
+  verifyDigest,
+} from './cursor';
+// ---- errors ----------------------------------------------------------------------------------
+export {
+  CursorStaleError,
+  LiveClientMissingError,
+  LiveRowUnidentifiedError,
+  NotImplementedError,
+  ProtocolVersionError,
+  REALTIME_ERROR_CODES,
+  REALTIME_ERROR_TITLES,
+  RealtimeError,
+  type RealtimeErrorCode,
+  RebaseConflictError,
+  ReplicationFailedError,
+  ReplicationProtocolError,
+  ReplicatorSlotHeldError,
+  SubscriptionLimitError,
+  TopicForbiddenError,
+  TransportProtocolError,
+  TransportUnavailableError,
+} from './errors';
+export {
+  InProcessTransport,
+  type InProcessTransportOptions,
+  subjectMatches,
+  type Transport,
+  type TransportHandler,
+  type TransportSet,
+  type TransportSetEntry,
+  type TransportSubscription,
+} from './fanout';
+// ---- the client hooks --------------------------------------------------------------------------
+export {
+  type ConflictLike,
+  type Connection,
+  clearLiveClient,
+  hasLiveClient,
+  type LiveInput,
+  type LiveRows,
+  type Mutate,
+  type MutationQueue,
+  type MutatorLike,
+  setLiveClient,
+  useConnection,
+  useLive,
+  useMutation,
+  useMutationQueue,
+} from './hooks';
+// ---- shared value domain ---------------------------------------------------------------------
+export {
+  canonicalJson,
+  changedColumns,
+  fnv1a,
+  isJsonObject,
+  isRow,
+  type JsonObject,
+  type JsonValue,
+  type Row,
+  type RowOp,
+  type RowPatch,
+} from './json';
+export { type LiveDefinitionOptions, liveQueryDefinition } from './live-definition';
+export {
+  type LiveQueryDefinition,
+  LiveQueryRegistry,
+  type LiveQueryRegistryOptions,
+  type LiveSubscription,
+  qidOf,
+  type RowDenied,
+  type SnapshotResult,
+} from './live-query';
+// ---- tier 3: local-first ------------------------------------------------------------------------
+export {
+  createOpfsLocalStore,
+  type LocalStore,
+  type LocalTable,
+  type LocalTx,
+  MemoryLocalStore,
+  type OpfsLocalStoreOptions,
+  type TableMap,
+} from './local-store';
+export {
+  applyToWindow,
+  type BridgeResult,
+  bridgeChange,
+  canAffect,
+  type IncrementalMatcher,
+  matcherFor,
+  NO_CHANGE,
+  normalizePatch,
+  patchFromChange,
+  type SubscriptionShape,
+  toBridgeResult,
+} from './matcher-bridge';
+export type { NatsConnectOptions } from './nats-commands';
+// ---- the production bus -------------------------------------------------------------------------
+export {
+  NatsConnection,
+  type NatsConnectionOptions,
+  type NatsMessageHandler,
+  type NatsSubscription,
+} from './nats-connection';
+export { type FakeNatsOptions, FakeNatsServer, fakeNatsStream } from './nats-fake';
+export {
+  assertBucket,
+  assertServerVersion,
+  ensureKvBucket,
+  type JsError,
+  type KvRecord,
+  kvGet,
+  kvLast,
+  kvSubject,
+  kvWrite,
+} from './nats-jetstream';
+export { decodeToken, encodeToken, NatsKvSet, type NatsKvSetOptions } from './nats-kv';
+export {
+  type NatsHeaders,
+  type NatsMessage,
+  type NatsOperation,
+  NatsProtocolParser,
+  type NatsServerInfo,
+} from './nats-protocol';
+export {
+  bunNatsStream,
+  type NatsStream,
+  type NatsTarget,
+  natsStreamOver,
+  parseNatsUrl,
+} from './nats-socket';
+export { NatsTransport, type NatsTransportOptions } from './nats-transport';
+export {
+  type DrainReport,
+  MemoryQueueStore,
+  type MutationSender,
+  type MutationStatus,
+  mutateFrame,
+  OfflineQueue,
+  type QueuedMutation,
+  type QueueState,
+  type QueueStore,
+} from './offline-queue';
+export { PgAdvisoryLock, type PgAdvisoryLockOptions } from './pg-advisory-lock';
+// ---- the postgres replication path ------------------------------------------------------------
+export { camel, entityRow } from './pg-entity-row';
+export {
+  changeLsn,
+  commitPositionOf,
+  type ReplicationStreamStats,
+} from './pg-replication';
+export { bunPgStream, type PgTarget, parsePgUrl, type SslMode } from './pg-socket';
+export type { PgStream } from './pg-wire';
+export {
+  type PgColumn,
+  PgOutputDecoder,
+  type PgOutputMessage,
+  type PgRelation,
+} from './pgoutput';
+export { authorizeWithPolicy, type GateOptions, visibleWithPolicy } from './policy-gate';
+export {
+  PRESENCE_KEY_PREFIX,
+  type PresenceInput,
+  type PresenceOptions,
+  PresenceRegistry,
+  presenceFrame,
+} from './presence';
+export {
+  type ConflictStrategy,
+  type CustomMerge,
+  custom,
+  type MergeArgs,
+  type RebaseEntry,
+  RebaseLog,
+  type ReconcileOptions,
+  type ReconcileResult,
+  rebaseFrame,
+  reconcile,
+  type ServerAck,
+  strategyName,
+} from './rebase';
+export {
+  type AdvisoryLock,
+  CHANGE_SUBJECT_PREFIX,
+  changeSubject,
+  createReplicator,
+  InMemoryAdvisoryLock,
+  normalize,
+  parseChange,
+  type Replicator,
+  type ReplicatorOptions,
+  type ReplicatorStats,
+} from './replicator';
+export {
+  actorIdOf,
+  CLOSE,
+  SocketRegistry,
+  type SocketRegistryOptions,
+  SyncSocket,
+  type SyncSocketOptions,
+  type WsLike,
+} from './socket';
+export {
+  createSyncNode,
+  type ListenOptions,
+  listenSyncNode,
+  type MutationHandler,
+  type SyncListener,
+  type SyncNode,
+  type SyncNodeOptions,
+  type SyncWs,
+  type UpgradeTarget,
+  type WsData,
+} from './sync-node';
+// ---- the wire -------------------------------------------------------------------------------------
+export {
+  type AckFrame,
+  type ConflictStrategyName,
+  decode,
+  encode,
+  FRAME_KINDS,
+  type Frame,
+  type FrameKind,
+  type HelloFrame,
+  type MutateFrame,
+  type PatchFrame,
+  PROTOCOL_VERSION,
+  type PresenceFrame,
+  type PresenceMember,
+  type RebaseFrame,
+  type ReconnectFrame,
+  type SnapshotFrame,
+  type SubscribeFrame,
+  type SubscribeTarget,
+  toWireError,
+  type UpdateAvailableFrame,
+  type WireError,
+} from './sync-protocol';
+export {
+  AcceptBudget,
+  type AcceptBudgetOptions,
+  type BackoffPolicy,
+  backoffDelay,
+  type DrainPlanEntry,
+  type DrainPlanOptions,
+  defaultBackoff,
+  drainPlan,
+  type JitterMode,
+  type ReconnectReason,
+  type Rng,
+  reconnectFrame,
+} from './thundering-herd';
+export {
+  DEFAULT_PRESENCE_BUCKET,
+  DEFAULT_PRESENCE_TTL_MS,
+  type SelectTransportOptions,
+  selectTransport,
+  TRANSPORT_ENV_KEYS,
+  type TransportEnvironment,
+  type TransportSelection,
+} from './transport-env';

package/src/json.ts

@@ -0,0 +1,76 @@
+// The JSON value domain shared by the wire, the matcher, and the local store.
+// Kept dependency-free so every other module in this package can import it without a cycle.
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type JsonObject = { [key: string]: JsonValue };
+
+/** Every row that crosses the wire or lands in the local store is identified by `id`. */
+export type Row = JsonObject & { id: string };
+
+export type RowOp = 'insert' | 'update' | 'delete';
+
+/**
+ * The minimal delta for one row in one subscription's result set.
+ * `index` is present only for ordered result sets, so a client can splice instead of re-sort.
+ */
+export interface RowPatch {
+  readonly op: RowOp;
+  readonly id: string;
+  /** `null` for deletes. For updates this is the changed columns only, never the whole row. */
+  readonly row: JsonObject | null;
+  readonly lsn: string;
+  readonly index?: number;
+}
+
+export function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function isRow(value: unknown): value is Row {
+  return isJsonObject(value) && typeof value['id'] === 'string';
+}
+
+/** Shallow diff used to keep update patches minimal — the pipeline never ships unchanged columns. */
+export function changedColumns(before: JsonObject | null, after: JsonObject): JsonObject {
+  if (before === null) return after;
+  const out: JsonObject = {};
+  for (const key of Object.keys(after)) {
+    const next = after[key];
+    if (next === undefined) continue;
+    if (!sameJson(before[key], next)) out[key] = next;
+  }
+  return out;
+}
+
+/** Key-sorted JSON so a query id derived from input is stable across property order. */
+export function canonicalJson(value: JsonValue): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  const parts = keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key] ?? null)}`);
+  return `{${parts.join(',')}}`;
+}
+
+/** FNV-1a, 32-bit, hex. Not cryptographic — it identifies and detects drift, it does not protect. */
+export function fnv1a(text: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i += 1) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, '0');
+}
+
+function sameJson(a: JsonValue | undefined, b: JsonValue | undefined): boolean {
+  if (a === b) return true;
+  if (a === undefined || b === undefined || a === null || b === null) return false;
+  if (typeof a !== 'object' || typeof b !== 'object') return false;
+  return JSON.stringify(a) === JSON.stringify(b);
+}