@luckystack/sync 0.1.9 → 0.2.1

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 import { StreamPayload, statusContent, BaseSessionLayout, SyncTypeMap } from '@luckystack/core/client';
 import { Dispatch, SetStateAction, RefObject } from 'react';
+import { Socket } from 'socket.io-client';
 
 type SyncRequestStreamEvent<T extends StreamPayload = StreamPayload> = T;
 type SyncRouteStreamEvent<T extends StreamPayload = StreamPayload> = T;
@@ -114,6 +115,7 @@ declare const useSyncEventTrigger: () => {
     triggerSyncEvent: (name: string, clientOutput?: unknown, serverOutput?: unknown) => void;
     triggerSyncStreamEvent: (name: string, stream: SyncRouteStreamEvent) => void;
 };
+declare const attachSyncReceiver: (socketInstance: Socket) => void;
 type SocketStatusSetter = Dispatch<SetStateAction<{
     self: statusContent;
     [userId: string]: statusContent;
@@ -123,4 +125,4 @@ declare const initSyncRequest: ({ setSocketStatus, sessionRef }: {
     sessionRef: RefObject<BaseSessionLayout | null> | null;
 }) => Promise<void>;
 
-export { type SyncRequestStreamEvent, type SyncRouteStreamEvent, initSyncRequest, syncRequest, useSyncEventTrigger, useSyncEvents };
+export { type SyncRequestStreamEvent, type SyncRouteStreamEvent, attachSyncReceiver, initSyncRequest, syncRequest, useSyncEventTrigger, useSyncEvents };

package/dist/client.js

@@ -41,7 +41,8 @@ var getStreamCallbacksForRoute = (route) => {
 var triggerSyncCallbacks = (name, clientOutput, serverOutput) => {
   const callbacks = syncEvents[name] ?? [];
   if (callbacks.length === 0) {
-    if (shouldLogDev()) {
+    const streamCallbacks = syncStreamEvents[name] ?? [];
+    if (streamCallbacks.length === 0 && shouldLogDev()) {
       getLogger().warn(`Sync event ${name} has no registered callback on this page`);
     }
     return;
@@ -81,6 +82,82 @@ var normalizeSyncError = ({
     httpStatus: normalized.httpStatus
   };
 };
+var prepareSyncRequest = async ({
+  name,
+  version,
+  receiver,
+  payloadData
+}) => {
+  if (!name || typeof name !== "string") {
+    if (shouldLogDev()) {
+      getLogger().error("Invalid name for syncRequest");
+    }
+    if (shouldNotifyDev()) {
+      notify.error({ key: "sync.invalidName" });
+    }
+    return { ok: false, error: normalizeSyncError({
+      response: { status: "error", errorCode: "sync.invalidName" },
+      fallbackErrorCode: "sync.invalidName"
+    }) };
+  }
+  const parsedRoute = parseServiceRouteName(name);
+  if (parsedRoute.status === "error") {
+    if (shouldLogDev()) {
+      getLogger().error(`[syncRequest] Invalid service route name '${name}'`, void 0, { reason: parsedRoute.reason });
+    }
+    if (shouldNotifyDev()) {
+      notify.error({ key: "routing.invalidServiceRouteName" });
+    }
+    return { ok: false, error: normalizeSyncError({
+      response: {
+        status: "error",
+        errorCode: "routing.invalidServiceRouteName",
+        errorParams: [{ key: "name", value: name }]
+      },
+      fallbackErrorCode: "routing.invalidServiceRouteName"
+    }) };
+  }
+  const sanitizedName = parsedRoute.normalizedRouteName;
+  const data = payloadData && typeof payloadData === "object" ? payloadData : {};
+  if (!version || typeof version !== "string") {
+    if (shouldLogDev()) {
+      getLogger().error("Invalid version for syncRequest");
+    }
+    if (shouldNotifyDev()) {
+      notify.error({ key: "sync.invalidVersion" });
+    }
+    return { ok: false, error: normalizeSyncError({
+      response: { status: "error", errorCode: "sync.invalidVersion" },
+      fallbackErrorCode: "sync.invalidVersion"
+    }) };
+  }
+  const normalizedReceiver = typeof receiver === "string" ? receiver.trim() : "";
+  if (!normalizedReceiver) {
+    if (shouldLogDev()) {
+      getLogger().error("You need to provide a receiver for syncRequest, this can be either 'all' to trigger all sockets which we do not recommend or it can be any value such as a code e.g 'Ag2cg4'. this works together with the joinRoom and leaveRoom function");
+    }
+    if (shouldNotifyDev()) {
+      notify.error({ key: "sync.missingReceiver" });
+    }
+    return { ok: false, error: normalizeSyncError({
+      response: { status: "error", errorCode: "sync.missingReceiver" },
+      fallbackErrorCode: "sync.missingReceiver"
+    }) };
+  }
+  if (!await waitForSocket()) {
+    return { ok: false, error: normalizeSyncError({
+      response: { status: "error", errorCode: "sync.ioUnavailable" },
+      fallbackErrorCode: "sync.ioUnavailable"
+    }) };
+  }
+  if (!socket) {
+    return { ok: false, error: normalizeSyncError({
+      response: { status: "error", errorCode: "sync.ioUnavailable" },
+      fallbackErrorCode: "sync.ioUnavailable"
+    }) };
+  }
+  return { ok: true, sanitizedName, version, data, normalizedReceiver };
+};
 var syncRequestInternal = (params) => {
   const runtimeParams = params;
   const { name, version, receiver, ignoreSelf, onStream, offlineDropPolicy, signal: externalSignal } = runtimeParams;
@@ -94,85 +171,26 @@ var syncRequestInternal = (params) => {
         }));
         return;
       }
-      if (!name || typeof name !== "string") {
-        if (shouldLogDev()) {
-          getLogger().error("Invalid name for syncRequest");
-        }
-        if (shouldNotifyDev()) {
-          notify.error({ key: "sync.invalidName" });
-        }
-        resolve(normalizeSyncError({
-          response: { status: "error", errorCode: "sync.invalidName" },
-          fallbackErrorCode: "sync.invalidName"
-        }));
-        return;
-      }
-      const parsedRoute = parseServiceRouteName(name);
-      if (parsedRoute.status === "error") {
-        if (shouldLogDev()) {
-          getLogger().error(`[syncRequest] Invalid service route name '${name}'`, void 0, { reason: parsedRoute.reason });
-        }
-        if (shouldNotifyDev()) {
-          notify.error({ key: "routing.invalidServiceRouteName" });
-        }
-        resolve(normalizeSyncError({
-          response: {
-            status: "error",
-            errorCode: "routing.invalidServiceRouteName",
-            errorParams: [{ key: "name", value: name }]
-          },
-          fallbackErrorCode: "routing.invalidServiceRouteName"
-        }));
-        return;
-      }
-      const sanitizedName = parsedRoute.normalizedRouteName;
-      const data = payloadData && typeof payloadData === "object" ? payloadData : {};
-      if (!version || typeof version !== "string") {
-        if (shouldLogDev()) {
-          getLogger().error("Invalid version for syncRequest");
-        }
-        if (shouldNotifyDev()) {
-          notify.error({ key: "sync.invalidVersion" });
-        }
-        resolve(normalizeSyncError({
-          response: { status: "error", errorCode: "sync.invalidVersion" },
-          fallbackErrorCode: "sync.invalidVersion"
-        }));
-        return;
-      }
-      const normalizedReceiver = typeof receiver === "string" ? receiver.trim() : "";
-      if (!normalizedReceiver) {
-        if (shouldLogDev()) {
-          getLogger().error("You need to provide a receiver for syncRequest, this can be either 'all' to trigger all sockets which we do not recommend or it can be any value such as a code e.g 'Ag2cg4'. this works together with the joinRoom and leaveRoom function");
-        }
-        if (shouldNotifyDev()) {
-          notify.error({ key: "sync.missingReceiver" });
-        }
-        resolve(normalizeSyncError({
-          response: { status: "error", errorCode: "sync.missingReceiver" },
-          fallbackErrorCode: "sync.missingReceiver"
-        }));
-        return;
-      }
-      if (!await waitForSocket()) {
-        resolve(normalizeSyncError({
-          response: { status: "error", errorCode: "sync.ioUnavailable" },
-          fallbackErrorCode: "sync.ioUnavailable"
-        }));
+      const prepared = await prepareSyncRequest({ name, version, receiver, payloadData });
+      if (!prepared.ok) {
+        resolve(prepared.error);
         return;
       }
-      if (!socket) {
+      const { sanitizedName, version: resolvedVersion, data, normalizedReceiver } = prepared;
+      const activeSocket = socket;
+      if (!activeSocket) {
         resolve(normalizeSyncError({
           response: { status: "error", errorCode: "sync.ioUnavailable" },
           fallbackErrorCode: "sync.ioUnavailable"
         }));
         return;
       }
-      const fullName = `sync/${sanitizedName}/${version}`;
+      const fullName = `sync/${sanitizedName}/${resolvedVersion}`;
       let queueId = null;
       const runRequest = (socketInstance) => {
         if (!canSendNow(socketInstance)) {
           queueId ??= createQueueId();
+          let suppressOnDrop = true;
           const enqueued = enqueueSyncRequest({
             id: queueId,
             key: fullName,
@@ -180,8 +198,23 @@ var syncRequestInternal = (params) => {
               runRequest(s);
             },
             createdAt: Date.now(),
-            dropPolicy: offlineDropPolicy
+            dropPolicy: offlineDropPolicy,
+            //? SYNC-09 — settle the awaiting caller when this QUEUED request is
+            //? later EVICTED (drop-oldest by a future enqueue / age expiry)
+            //? instead of ever running. Without it the promise would hang
+            //? forever, since `run` is the only thing that could otherwise
+            //? resolve it. The default `offlineQueue.dropPolicy` is
+            //? `'drop-oldest'`, so async eviction is the NORMAL overflow path
+            //? for high-churn syncs (cursor moves), not an edge case.
+            onDrop: (reason) => {
+              if (suppressOnDrop) return;
+              resolve(normalizeSyncError({
+                response: { status: "error", errorCode: "offline.dropped", errorParams: [{ key: "reason", value: reason }] },
+                fallbackErrorCode: "offline.dropped"
+              }));
+            }
           });
+          suppressOnDrop = false;
           if (!enqueued) {
             resolve(normalizeSyncError({
               response: { status: "error", errorCode: "offline.queueFull" },
@@ -192,30 +225,46 @@ var syncRequestInternal = (params) => {
         }
         const tempIndex = incrementResponseIndex();
         let cleanupProgressListener = null;
+        let responseTimeout = null;
+        const clearResponseTimeout = () => {
+          if (responseTimeout) {
+            clearTimeout(responseTimeout);
+            responseTimeout = null;
+          }
+        };
         if (shouldLogDev()) {
           getLogger().debug(`Client Sync Request(${String(tempIndex)})`, { syncName: sanitizedName, data, receiver: normalizedReceiver, ignoreSelf });
         }
-        if (typeof onStream === "function") {
-          const progressEventName = buildSyncProgressEventName(tempIndex);
-          const progressListener = (streamPayload) => {
-            if (shouldLogStream()) {
-              getLogger().debug(`Server Sync Stream(${String(tempIndex)})`, { syncName: sanitizedName, streamPayload });
-            }
-            onStream(streamPayload);
-          };
-          socketInstance.on(progressEventName, progressListener);
-          cleanupProgressListener = () => {
-            socketInstance.off(progressEventName, progressListener);
-          };
-        }
-        const syncCb = `${sanitizedName}/${version}`;
+        let serverCancelId = null;
+        const progressEventName = buildSyncProgressEventName(tempIndex);
+        const progressListener = (streamPayload) => {
+          if (typeof streamPayload.__cancelId === "string") {
+            serverCancelId = streamPayload.__cancelId;
+            return;
+          }
+          if (typeof onStream !== "function") return;
+          if (shouldLogStream()) {
+            getLogger().debug(`Server Sync Stream(${String(tempIndex)})`, { syncName: sanitizedName, streamPayload });
+          }
+          onStream(streamPayload);
+        };
+        socketInstance.on(progressEventName, progressListener);
+        cleanupProgressListener = () => {
+          socketInstance.off(progressEventName, progressListener);
+        };
+        const syncCb = `${sanitizedName}/${resolvedVersion}`;
         socketInstance.emit(socketEventNames.sync, { name: fullName, data, cb: syncCb, receiver: normalizedReceiver, responseIndex: tempIndex, ignoreSelf });
+        const responseEventName = buildSyncResponseEventName(tempIndex);
+        let cleanupResponseListener = null;
         let cleanupExternalAbort = null;
         if (externalSignal) {
           const externalAbortHandler = () => {
-            socketInstance.emit(socketEventNames.syncCancel, { cb: syncCb });
+            clearResponseTimeout();
+            socketInstance.emit(socketEventNames.syncCancel, { cb: serverCancelId ?? syncCb });
             cleanupProgressListener?.();
             cleanupProgressListener = null;
+            cleanupResponseListener?.();
+            cleanupResponseListener = null;
             cleanupExternalAbort?.();
             cleanupExternalAbort = null;
             resolve(normalizeSyncError({
@@ -228,8 +277,30 @@ var syncRequestInternal = (params) => {
             externalSignal.removeEventListener("abort", externalAbortHandler);
           };
         }
-        socketInstance.once(buildSyncResponseEventName(tempIndex), (responseData) => {
+        const effectiveTimeoutMs = getProjectConfig().sync.requestTimeoutMs;
+        if (typeof effectiveTimeoutMs === "number" && effectiveTimeoutMs > 0) {
+          responseTimeout = setTimeout(() => {
+            responseTimeout = null;
+            cleanupProgressListener?.();
+            cleanupProgressListener = null;
+            cleanupResponseListener?.();
+            cleanupResponseListener = null;
+            cleanupExternalAbort?.();
+            cleanupExternalAbort = null;
+            if (shouldLogDev()) {
+              getLogger().error(`Sync ${sanitizedName} timed out`, void 0, { responseIndex: tempIndex });
+            }
+            resolve(normalizeSyncError({
+              response: { status: "error", errorCode: "sync.requestTimeout", httpStatus: 504 },
+              fallbackErrorCode: "sync.requestTimeout"
+            }));
+          }, effectiveTimeoutMs);
+        }
+        const responseListener = (responseData) => {
+          clearResponseTimeout();
           cleanupProgressListener?.();
+          cleanupProgressListener = null;
+          cleanupResponseListener = null;
           cleanupExternalAbort?.();
           cleanupExternalAbort = null;
           if (responseData.status === "error") {
@@ -265,9 +336,13 @@ var syncRequestInternal = (params) => {
             message: typeof responseData.message === "string" && responseData.message.trim().length > 0 ? responseData.message : `sync ${sanitizedName} success`,
             result
           });
-        });
+        };
+        socketInstance.once(responseEventName, responseListener);
+        cleanupResponseListener = () => {
+          socketInstance.off(responseEventName, responseListener);
+        };
       };
-      runRequest(socket);
+      runRequest(activeSocket);
     })();
   });
 };
@@ -442,6 +517,78 @@ var useSyncEventTrigger = () => {
   }, []);
   return { triggerSyncEvent, triggerSyncStreamEvent };
 };
+var normalizeSyncRouteKey = (value) => {
+  const sanitized = value.replaceAll(/^\/+|\/+$/g, "");
+  if (sanitized.length === 0) return "";
+  if (sanitized.startsWith("sync/")) return sanitized;
+  return `sync/${sanitized}`;
+};
+var getSyncRouteKeys = ({ fullName, cb }) => {
+  const keys = /* @__PURE__ */ new Set();
+  if (typeof fullName === "string") {
+    const normalized = normalizeSyncRouteKey(fullName);
+    if (normalized) keys.add(normalized);
+  }
+  if (typeof cb === "string") {
+    const normalized = normalizeSyncRouteKey(cb);
+    if (normalized) keys.add(normalized);
+  }
+  return [...keys];
+};
+var attachedSyncSockets = /* @__PURE__ */ new WeakSet();
+var attachSyncReceiver = (socketInstance) => {
+  if (attachedSyncSockets.has(socketInstance)) return;
+  attachedSyncSockets.add(socketInstance);
+  socketInstance.on(socketEventNames.sync, (payload) => {
+    const { cb, clientOutput, serverOutput, message, status, fullName, errorCode, errorParams } = payload;
+    if (shouldLogDev()) {
+      getLogger().debug("Server Sync Response", { payload });
+    }
+    const routeKeys = getSyncRouteKeys({ fullName, cb });
+    if (status === "stream") {
+      if (routeKeys.length === 0) return;
+      const streamPayload = { ...payload };
+      delete streamPayload.status;
+      delete streamPayload.fullName;
+      delete streamPayload.cb;
+      delete streamPayload.errorCode;
+      delete streamPayload.errorParams;
+      delete streamPayload.httpStatus;
+      delete streamPayload.message;
+      if (shouldLogStream()) {
+        getLogger().debug("Server Sync Stream", { routeKeys, streamPayload });
+      }
+      for (const routeKey of routeKeys) {
+        triggerSyncStreamCallbacks(routeKey, streamPayload);
+      }
+      return;
+    }
+    if (status === "error") {
+      if (errorCode === "sync.ignore" || message === "sync.ignore") return;
+      if (shouldNotifyDev()) {
+        if (errorCode) {
+          notify.error({ key: errorCode, params: errorParams });
+        } else if (message) {
+          notify.error({ key: message });
+        }
+      }
+      return;
+    }
+    if (routeKeys.length === 0) {
+      const errorMessage = `Sync response is missing fullName for cb '${cb ?? "unknown"}'.`;
+      if (shouldLogDev()) {
+        getLogger().error(errorMessage);
+      }
+      if (shouldNotifyDev()) {
+        notify.error({ key: "sync.invalidRequestFormat" });
+      }
+      return;
+    }
+    for (const routeKey of routeKeys) {
+      triggerSyncCallbacks(routeKey, clientOutput, serverOutput);
+    }
+  });
+};
 var buildConnectHandler = ({ setSocketStatus }) => () => {
   if (shouldLogSocketStatus()) getLogger().info("Connected to server");
   setSocketStatus((prev) => ({ ...prev, self: { ...prev.self, status: "CONNECTED" } }));
@@ -529,6 +676,7 @@ var initSyncRequest = async ({
   socket.on(socketEventNames.connectError, connectError);
 };
 export {
+  attachSyncReceiver,
   initSyncRequest,
   syncRequest,
   useSyncEventTrigger,