@luckystack/sync 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+import { syncMessage } from '@luckystack/core';
+import { Socket } from 'socket.io';
+
+declare function handleSyncRequest({ msg, socket, token }: {
+    msg: syncMessage;
+    socket: Socket;
+    token: string | null;
+}): Promise<boolean | undefined>;
+
+interface HttpSyncRequestParams {
+    name: string;
+    cb?: string;
+    data: Record<string, unknown>;
+    receiver: string;
+    ignoreSelf?: boolean;
+    token: string | null;
+    requesterIp?: string;
+    xLanguageHeader?: string | string[];
+    acceptLanguageHeader?: string | string[];
+    stream?: (payload: HttpSyncStreamEvent) => void;
+    /**
+     * Optional AbortSignal. The HTTP server (`@luckystack/server`) wires this
+     * to `req.on('close', ...)` so a closed SSE connection aborts in-flight
+     * stream emits. Sync handlers receive it as `abortSignal` in params.
+     */
+    abortSignal?: AbortSignal;
+}
+interface HttpSyncResponse {
+    status: 'success' | 'error';
+    message: string;
+    errorCode?: string;
+    errorParams?: {
+        key: string;
+        value: string | number | boolean;
+    }[];
+    httpStatus?: number;
+}
+type SyncStreamPayload = Record<string, unknown>;
+type HttpSyncStreamEvent = SyncStreamPayload;
+declare function handleHttpSyncRequest({ name, cb, data, receiver, ignoreSelf, token, requesterIp, xLanguageHeader, acceptLanguageHeader, stream, abortSignal, }: HttpSyncRequestParams): Promise<HttpSyncResponse>;
+
+interface CreateStreamThrottleOptions {
+    /**
+     * Flush buffered text once it crosses this many characters. Default: 32.
+     * Lower = more updates, more network traffic.
+     * Higher = fewer updates, choppier UI.
+     */
+    flushAtChars?: number;
+    /**
+     * Flush buffered text after this many milliseconds even if the char
+     * threshold hasn't been hit. Default: 50ms — fast enough that the user
+     * perceives "live typing", slow enough that 50–100 tokens batch into a
+     * single message on a fast LLM stream.
+     *
+     * Set to `false` to disable the timer (only flush at char threshold or
+     * on explicit `flush()`).
+     */
+    flushEveryMs?: number | false;
+    /**
+     * Field name on the emitted payload that carries the buffered text.
+     * Default: `'chunk'`. Override if your stream payload uses a different
+     * key (e.g. `'text'`, `'delta'`).
+     */
+    field?: string;
+}
+interface StreamThrottle {
+    /** Append text to the buffer. May trigger a flush. */
+    push: (text: string, emit: (payload: Record<string, unknown>) => void) => void;
+    /** Force-flush whatever is in the buffer right now. Call after the source loop ends. */
+    flush: (emit: (payload: Record<string, unknown>) => void) => void;
+    /** Drop the buffered text without emitting. Useful on abort. */
+    reset: () => void;
+}
+/**
+ * Build a chunk throttle for streaming use cases. Designed for LLM token
+ * streams where the provider yields very small pieces (3–10 chars) and you
+ * don't want to send a separate socket message for each one.
+ *
+ * @example
+ *   const throttle = createStreamThrottle({ flushEveryMs: 50, flushAtChars: 32 });
+ *   for await (const chunk of openaiStream) {
+ *     throttle.push(chunk.text, broadcastStream);
+ *   }
+ *   throttle.flush(broadcastStream);
+ */
+declare const createStreamThrottle: (options?: CreateStreamThrottleOptions) => StreamThrottle;
+
+export { type CreateStreamThrottleOptions, type HttpSyncStreamEvent, type StreamThrottle, createStreamThrottle, handleHttpSyncRequest, handleSyncRequest };