@absolutejs/sync 1.15.0 → 1.16.0

package/dist/client/syncStore.d.ts

@@ -1,5 +1,6 @@
 import type { RowKey } from '../engine/types';
 import type { MutationStorage } from './syncCollection';
+import { type FrameSerializer } from '../serializer';
 export type SyncStoreStatus = 'connecting' | 'ready' | 'closed';
 export type SyncStoreState<Row> = {
     /** Visible rows: confirmed server state with pending optimistic edits applied. */
@@ -49,6 +50,11 @@ export type SyncStoreOptions<Row, M extends MutationMap> = {
     /** Persist the pending-mutation queue across reloads (offline). */
     storage?: MutationStorage;
     onError?: (error: unknown) => void;
+    /**
+     * Wire-format serializer (1.16.0). Defaults to `jsonSerializer`. MUST
+     * match the server's `syncSocket` serializer.
+     */
+    serializer?: FrameSerializer;
 };
 export type SyncStore<Row, M extends MutationMap> = {
     get: () => SyncStoreState<Row>;

package/dist/engine/connection.d.ts

@@ -1,5 +1,6 @@
 import type { PresenceHub, PresenceMember } from './presence';
 import type { SyncEngine } from './syncEngine';
+import type { FrameSerializer } from '../serializer';
 /**
  * Wire protocol for the sync-engine WebSocket. One connection multiplexes many
  * collection subscriptions, each tagged with a client-chosen `id`.
@@ -80,16 +81,58 @@ export type SyncConnectionOptions = {
     engine: SyncEngine;
     /** Resolved auth context for this connection; passed to every subscribe. */
     ctx: unknown;
-    /** Send a frame to the client (the transport serializes it). */
-    send: (frame: ServerFrame) => void;
+    /**
+     * Send a frame to the client (the transport serializes it). May return
+     * a number — by convention `-1` signals transport-layer backpressure (the
+     * value Bun's `ws.send()` returns when the WS buffer is full). The
+     * connection tracks consecutive `-1` returns and surfaces them via
+     * `connection.stats().slowSendsRecent`. Legacy `void`-returning sends
+     * keep working unchanged.
+     *
+     * NOTE: 1.16.0 — `send` receives the typed `ServerFrame`. The connection
+     * does NOT pre-serialize; the WS adapter (`syncSocket`) wraps `send` to
+     * call `serializer.encodeServer(frame)` before `ws.send(...)`. This keeps
+     * the connection layer transport-agnostic.
+     */
+    send: (frame: ServerFrame) => void | number;
     /** Optional presence hub; enables the `presence-*` frames (see createPresenceHub). */
     presence?: PresenceHub;
+    /**
+     * Wire-format serializer (1.16.0). Defaults to `jsonSerializer` —
+     * the historical JSON-over-WS behavior. Both ends of the connection
+     * MUST use the same serializer; pair this option with the matching
+     * client-side `serializer` to opt into binary frames.
+     */
+    serializer?: FrameSerializer;
+};
+/**
+ * Connection-level operational counters surfaced via {@link SyncConnection.stats}.
+ * Pair with the WS adapter's own backpressure signal for end-to-end slow-client
+ * detection.
+ */
+export type SyncConnectionStats = {
+    /** Active subscriptions on this connection. */
+    subscriptionCount: number;
+    /** Active presence-room memberships on this connection. */
+    presenceRoomCount: number;
+    /** Frames successfully sent (non-backpressure return) since the connection opened. */
+    framesSent: number;
+    /** Consecutive `-1` (backpressure) returns from `send` since the last successful send. */
+    slowSendsRecent: number;
 };
 export type SyncConnection = {
     /** Handle one client frame (a parsed object or a raw JSON string). */
     handle: (raw: unknown) => Promise<void>;
     /** Tear down every subscription on this connection (call on socket close). */
     close: () => void;
+    /**
+     * Point-in-time connection counters — subscription count, frames sent, and
+     * how many consecutive `send` calls came back with the transport's backpressure
+     * signal. Cheap; safe to call from a metering loop.
+     *
+     * Added in 1.14.0.
+     */
+    stats: () => SyncConnectionStats;
 };
 /**
  * The per-connection protocol handler — transport-agnostic glue between a single
@@ -100,4 +143,4 @@ export type SyncConnection = {
  * Pure (no WebSocket import) so it can be unit-tested with a fake `send`; the
  * Elysia `syncSocket` plugin is the thin adapter that feeds it socket events.
  */
-export declare const createSyncConnection: ({ engine, ctx, send, presence }: SyncConnectionOptions) => SyncConnection;
+export declare const createSyncConnection: ({ engine, ctx, send: rawSend, presence, serializer }: SyncConnectionOptions) => SyncConnection;

package/dist/engine/index.js

@@ -1356,6 +1356,32 @@ class UnauthorizedError extends Error {
   }
 }
 
+class AbortError extends Error {
+  constructor(reason) {
+    super(reason ?? "Aborted");
+    this.name = "AbortError";
+  }
+}
+var checkAborted = (signal) => {
+  if (signal?.aborted) {
+    throw new AbortError(signal.reason instanceof Error ? signal.reason.message : typeof signal.reason === "string" ? signal.reason : "Aborted");
+  }
+};
+var linkAbortToUnsubscribe = (signal, unsubscribe) => {
+  if (signal === undefined)
+    return;
+  if (signal.aborted) {
+    unsubscribe();
+    return;
+  }
+  const handler = () => {
+    try {
+      unsubscribe();
+    } catch {}
+  };
+  signal.addEventListener("abort", handler, { once: true });
+};
+
 class SchemaError extends Error {
   constructor(table, fieldName) {
     super(`Schema violation on "${table}": invalid field "${fieldName}"`);
@@ -2218,29 +2244,35 @@ var createSyncEngine = (options = {}) => {
     registerSearch: (collection) => {
       registry.set(collection.name, collection);
     },
-    subscribe: async ({ collection, params, ctx, onDiff, since }) => {
+    subscribe: async ({ collection, params, ctx, onDiff, since, signal }) => {
+      checkAborted(signal);
       const registered = registry.get(collection);
       if (registered === undefined) {
         throw new Error(`Unknown collection "${collection}"`);
       }
       const typedOnDiff = onDiff;
       const subscribeSet = subsFor(collection);
+      const wrapReturn = (sub) => {
+        checkAborted(signal);
+        linkAbortToUnsubscribe(signal, sub.unsubscribe);
+        return sub;
+      };
       const registeredKind = registered.kind;
       if (registeredKind === "join") {
         const joined = await subscribeJoin(collection, registered, params, ctx, typedOnDiff, subscribeSet);
-        return joined;
+        return wrapReturn(joined);
       }
       if (registeredKind === "graph") {
         const graphed = await subscribeGraph(collection, registered, params, ctx, typedOnDiff, subscribeSet);
-        return graphed;
+        return wrapReturn(graphed);
       }
       if (registeredKind === "reactive") {
         const reactived = await subscribeReactive(collection, registered, params, ctx, typedOnDiff, subscribeSet);
-        return reactived;
+        return wrapReturn(reactived);
       }
       if (registeredKind === "search") {
         const searched = await subscribeSearch(collection, registered, params, ctx, typedOnDiff, subscribeSet);
-        return searched;
+        return wrapReturn(searched);
       }
       const definition = registered;
       if (definition.authorize !== undefined) {
@@ -2282,31 +2314,35 @@ var createSyncEngine = (options = {}) => {
         subscribeSet.delete(subscription);
       };
       if (resuming) {
-        return {
+        return wrapReturn({
           initial: [],
           catchup: buildCatchup(since, tables, key, boundMatch),
           version: atVersion,
           unsubscribe
-        };
+        });
       }
-      return {
+      return wrapReturn({
         initial: view.rows(),
         version: atVersion,
         unsubscribe
-      };
+      });
     },
-    hydrate: async (collection, params, ctx) => {
+    hydrate: async (collection, params, ctx, options2) => {
+      const signal = options2?.signal;
+      checkAborted(signal);
       const definition = registry.get(collection);
       if (definition === undefined) {
         throw new Error(`Unknown collection "${collection}"`);
       }
       if (definition.authorize !== undefined) {
         const allowed = await definition.authorize(params, ctx);
+        checkAborted(signal);
         if (!allowed) {
           throw new UnauthorizedError(`hydrate collection "${collection}"`);
         }
       }
       const raw = [...await definition.hydrate(params, ctx)];
+      checkAborted(signal);
       const tables = definition.tables ?? [collection];
       const scopedTable = tables.length === 1 ? tables[0] : undefined;
       const rows = scopedTable !== undefined ? raw.map((row) => migrateRow(scopedTable, row)) : raw;
@@ -2953,15 +2989,43 @@ var mutateRoute = (engine, mutation, resolveContext = emptyContext) => {
     return result;
   };
 };
+// src/serializer.ts
+var jsonSerializer = {
+  decode: (raw) => {
+    if (typeof raw === "string") {
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return null;
+      }
+    }
+    if (raw instanceof Uint8Array) {
+      try {
+        return JSON.parse(new TextDecoder().decode(raw));
+      } catch {
+        return null;
+      }
+    }
+    if (raw instanceof ArrayBuffer) {
+      try {
+        return JSON.parse(new TextDecoder().decode(new Uint8Array(raw)));
+      } catch {
+        return null;
+      }
+    }
+    return raw;
+  },
+  encodeClient: (frame) => JSON.stringify(frame),
+  encodeServer: (frame) => JSON.stringify(frame)
+};
+
 // src/engine/connection.ts
-var parseFrame = (raw) => {
+var parseFrame = (raw, serializer) => {
   let value = raw;
-  if (typeof value === "string") {
-    try {
-      value = JSON.parse(value);
-    } catch {
+  if (typeof value === "string" || value instanceof Uint8Array || value instanceof ArrayBuffer) {
+    value = serializer.decode(raw);
+    if (value === null)
       return;
-    }
   }
   if (typeof value !== "object" || value === null) {
     return;
@@ -3006,11 +3070,23 @@ var parseFrame = (raw) => {
 var createSyncConnection = ({
   engine,
   ctx,
-  send,
-  presence
+  send: rawSend,
+  presence,
+  serializer = jsonSerializer
 }) => {
   const subscriptions = new Map;
   const presenceRooms = new Map;
+  let framesSent = 0;
+  let slowSendsRecent = 0;
+  const send = (frame) => {
+    const ret = rawSend(frame);
+    if (ret === -1) {
+      slowSendsRecent += 1;
+    } else {
+      framesSent += 1;
+      slowSendsRecent = 0;
+    }
+  };
   let pending = [];
   let pendingVersion;
   let flushScheduled = false;
@@ -3055,7 +3131,7 @@ var createSyncConnection = ({
     scheduleFlush();
   };
   const handle = async (raw) => {
-    const frame = parseFrame(raw);
+    const frame = parseFrame(raw, serializer);
     if (frame === undefined) {
       send({ type: "error", message: "Malformed sync frame" });
       return;
@@ -3172,7 +3248,13 @@ var createSyncConnection = ({
     }
     presenceRooms.clear();
   };
-  return { handle, close };
+  const stats = () => ({
+    framesSent,
+    presenceRoomCount: presenceRooms.size,
+    slowSendsRecent,
+    subscriptionCount: subscriptions.size
+  });
+  return { close, handle, stats };
 };
 export {
   syncCdc,
@@ -3222,5 +3304,5 @@ export {
   CdcConsumerSlowError
 };
 
-//# debugId=61A7A6BDD6B4D12064756E2164756E21
+//# debugId=2B8B686DC5E953C364756E2164756E21
 //# sourceMappingURL=index.js.map