@iadev93/zuno 0.0.3 → 0.0.5

package/dist/sync/sse-client.js

@@ -0,0 +1,162 @@
+import { createTransport } from "./transport";
+import { applyIncomingEvent } from "./apply-incoming-event";
+/**
+ * Starts a Server-Sent Events (SSE) connection to synchronize state from a server.
+ * It can synchronize either a Zuno universe (collection of stores) or a single Zuno store.
+ *
+ * @param options - Configuration options for the SSE connection, including the URL,
+ *                  and either a Zuno universe or a specific Zuno store to update.
+ */
+export const startSSE = (options) => {
+    if (!options?.url)
+        throw new Error("startSSE: 'url' is required");
+    if (!options.universe && !options.store)
+        throw new Error("startSSE: provide either 'universe' or 'store'");
+    const clientId = options.clientId ?? (crypto?.randomUUID?.() ?? String(Math.random()));
+    // const eventSource = new EventSource(options.url);
+    const lastEventId = options.getLastEventId?.() ?? 0;
+    const url = lastEventId > 0
+        ? `${options.url}?lastEventId=${encodeURIComponent(String(lastEventId))}`
+        : options.url;
+    const eventSource = new EventSource(url);
+    const transport = createTransport(options.syncUrl);
+    /**
+     * Applies an incoming state event to the target Zuno universe or store.
+     * If a universe is provided, it updates the specific store identified by `storeKey`.
+     * If a single store is provided, it updates that store directly.
+     * @param eventState - The state event received from the SSE connection, containing `storeKey` and `state`.
+     */
+    const applyEventToTarget = (eventState) => {
+        if (options.universe) {
+            const store = options.universe.getStore(eventState.storeKey, () => eventState.state);
+            store.set(eventState.state);
+        }
+        else if (options.store) {
+            options.store.set(eventState.state);
+        }
+    };
+    /**
+     * Tracks the version of each store to handle conflicts.
+     */
+    const versions = options.versions;
+    /**
+     * Applies an incoming snapshot to the target Zuno universe or store.
+     * If a universe is provided, it updates all stores in the snapshot.
+     * If a single store is provided, it updates that store directly.
+     * @param snapshot - The snapshot received from the SSE connection, containing a map of store keys to states.
+     */
+    const applySnapshotToTarget = (snapshot) => {
+        if (options.universe) {
+            const snap = (snapshot ?? {});
+            for (const [storeKey, rec] of Object.entries(snap)) {
+                versions.set(storeKey, rec?.version ?? 0);
+                const store = options.universe.getStore(storeKey, () => rec.state);
+                store.set(rec.state);
+            }
+            options.getSnapshot?.(options.universe);
+        }
+        else if (options.store) {
+            options.store.set(snapshot);
+            options.getSnapshot?.(options.store);
+        }
+    };
+    /**
+     * Handles incoming snapshot events from the SSE connection.
+     * Parses the snapshot data and applies it to the target Zuno universe or store.
+     * @param event - The MessageEvent containing the snapshot data.
+     */
+    const onSnapshot = (event) => {
+        try {
+            const snapshotState = JSON.parse(event.data);
+            applySnapshotToTarget(snapshotState);
+        }
+        catch {
+            console.error("Zuno SSE: failed to parse snapshot payload");
+        }
+    };
+    /**
+     * Handles incoming state events from the SSE connection.
+     * Parses the state data and applies it to the target Zuno universe or store.
+     * @param event - The MessageEvent containing the state data.
+     */
+    const onState = (event) => {
+        try {
+            const eventState = JSON.parse(event.data);
+            /**
+             * Apply incoming event to universe or store
+             */
+            if (options.universe) {
+                applyIncomingEvent(options.universe, eventState, {
+                    clientId,
+                    versions,
+                });
+            }
+            /**
+             * Apply incoming event to store
+             */
+            else if (options.store) {
+                // Minimal support for single-store subscriptions.
+                if (typeof eventState.version === "number") {
+                    const currentVersion = versions.get(eventState.storeKey) ?? 0;
+                    if (eventState.version <= currentVersion)
+                        return;
+                    versions.set(eventState.storeKey, eventState.version);
+                }
+                options.store.set(eventState.state);
+            }
+        }
+        catch {
+            console.error("Zuno SSE: failed to parse state payload");
+        }
+    };
+    eventSource.addEventListener("snapshot", onSnapshot);
+    eventSource.addEventListener("state", onState);
+    eventSource.onopen = () => {
+        options.onOpen?.();
+    };
+    eventSource.onerror = () => {
+        options.onClose?.();
+    };
+    /**
+     * Unsubscribes from the SSE connection and removes the event listeners.
+     */
+    const unsubscribe = () => {
+        eventSource.removeEventListener("snapshot", onSnapshot);
+        eventSource.removeEventListener("state", onState);
+        eventSource.close();
+    };
+    /**
+     * Dispatches a state event to the server.
+     * If optimistic = true, also applies the event locally immediately.
+     * @param event - The state event to dispatch.
+     */
+    const dispatch = async (event) => {
+        const baseVersion = versions.get(event.storeKey) ?? 0;
+        /** Payload to send to server with event metadata, version and origin */
+        const payload = {
+            ...event,
+            origin: clientId
+        };
+        /**
+         * Optimistic logic applied locally
+         */
+        if (options.optimistic) {
+            applyEventToTarget(payload);
+            versions.set(event.storeKey, baseVersion + 1);
+        }
+        /**
+         * AUTHORITATIVE: send to server
+         */
+        const result = await transport.publish(payload);
+        /**
+         * If server rejects, reconcile (optional but good)
+         */
+        if (!result.ok && result.status === 409 && result.json?.current && options.universe) {
+            const { state, version } = result.json.current;
+            versions.set(event.storeKey, version);
+            options.universe.getStore(event.storeKey, () => state).set(state);
+        }
+        return result;
+    };
+    return { unsubscribe, dispatch };
+};

package/dist/sync/sync-types.d.ts

@@ -0,0 +1,164 @@
+import type { Store, Universe } from "../core/types";
+/**
+ * Represents a state event received from a Zuno SSE stream.
+ */
+export interface ZunoStateEvent {
+    /** The kind of the event. */
+    kind?: "state";
+    /** The key of the store that emitted the state change. */
+    storeKey: string;
+    /** The new state value. */
+    state: unknown;
+    /** The version of the store before the state change to resolve conflicts and ordering. */
+    baseVersion?: number;
+    /** The authoritative version after server applies. */
+    version?: number;
+    /** The origin of the state change. */
+    origin?: string;
+    /** The timestamp of the state change. */
+    ts?: number;
+    /** The global monotonic id of the event. */
+    eventId?: number;
+    /** The transport layer that published the event. */
+    via?: "http" | "sse" | "bc";
+}
+export type ZunoSSEOptionsDefault = {
+    /**
+     * The URL of the SSE endpoint.
+     * */
+    url: string;
+    /**
+     * The URL of the Sync endpoint.
+    */
+    syncUrl: string;
+    /**
+     * Get the snapshot of the universe or store.
+     */
+    getSnapshot?: (data: Universe | Store<unknown>) => void;
+    /**
+     * Whether to enable optimistic updates.
+     * If true, the client will update its state optimistically before receiving the server's response.
+     */
+    optimistic?: boolean;
+    /**
+     * The client id for the Broadcast Channel.
+     */
+    clientId?: string;
+    /**
+     * The name of the Broadcast Channel.
+     */
+    channelName?: string;
+    /**
+     * The versions of the stores.
+     */
+    versions: Map<string, number>;
+    /**
+     * Callback when SSE connection is opened.
+     */
+    onOpen?: () => void;
+    /**
+     * Callback when SSE connection is closed.
+     */
+    onClose?: () => void;
+    /**
+     * The last event ID received from the server.
+     */
+    getLastEventId?: () => number;
+    /**
+     * Callback when an event is received from the server.
+     */
+    onEvent?: (event: ZunoStateEvent) => void;
+};
+/**
+ * Options for configuring a Zuno Server-Sent Events (SSE) connection.
+ * It can be configured either with a `Universe` or a specific `Store`.
+ */
+export type ZunoSSEOptions = ZunoSSEOptionsDefault & ({
+    /** The universe to subscribe to. */
+    universe: Universe;
+    store?: never;
+} | {
+    /** The specific store to subscribe to. */
+    store: Store<any>;
+    universe?: never;
+});
+/**
+ * Defines the interface for a Zuno transport layer, responsible for
+ * publishing and subscribing to state events.
+ */
+export interface ZunoTransport {
+    /**
+     * Publishes a state event to the transport.
+     * @param event The state event to publish.
+     */
+    publish(event: ZunoStateEvent): {
+        ok: boolean;
+        status: number;
+        json: unknown;
+    } | Promise<{
+        ok: boolean;
+        status: number;
+        json: any;
+    }>;
+    /**
+     * Subscribes to state events from the transport.
+     * @param handler The function to call when a new state event is received.
+     */
+    subscribe(handler: (event: ZunoStateEvent) => void): () => void;
+}
+/**
+ * A record of a store's state and version.
+ * @property {unknown} state - The state of the store.
+ * @property {number} version - The version of the store.
+ */
+export type ZunoSnapshotRecord = {
+    /**
+     * The state of the store.
+     */
+    state: unknown;
+    /**
+     * The version of the store.
+     */
+    version: number;
+};
+/**
+ * A snapshot of the universe or store.
+ * @property {Record<string, ZunoSnapshotRecord>} state - The state of the store.
+ */
+export type ZunoSnapshotState = Record<string, ZunoSnapshotRecord>;
+/**
+ * A message sent over the broadcast channel.
+ * @property {"zuno:hello" | "zuno:snapshot" | "zuno:event"} type - The type of the message.
+ * @property {string} origin - The origin of the message.
+ * @property {string} target - The target of the message.
+ * @property {ZunoSnapshotState} snapshot - The snapshot of the universe or store.
+ * @property {ZunoStateEvent} event - The state event.
+ */
+export type BCMsg = {
+    type: "zuno:hello";
+    origin: string;
+} | {
+    type: "zuno:snapshot";
+    origin: string;
+    target: string;
+    snapshot: ZunoSnapshotState;
+} | {
+    type: "zuno:event";
+    origin: string;
+    event: ZunoStateEvent;
+};
+/**
+ * Options for starting a broadcast channel.
+ * @property {string} channelName - The name of the broadcast channel.
+ * @property {string} clientId - The client id for the broadcast channel.
+ * @property {(event: ZunoStateEvent) => void} onEvent - The function to call when a new state event is received.
+ * @property {() => ZunoSnapshotState} getSnapshot - The function to get the snapshot of the universe or store.
+ */
+export type ZunoBCOptions = {
+    channelName: string;
+    clientId: string;
+    onEvent: (event: ZunoStateEvent) => void;
+    getSnapshot?: () => ZunoSnapshotState;
+    onSnapshot?: (snapshot: ZunoSnapshotState) => void;
+};
+//# sourceMappingURL=sync-types.d.ts.map

package/dist/sync/sync-types.d.ts.map

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

package/dist/sync/sync-types.js

@@ -0,0 +1 @@
+export {};

package/dist/sync/transport.d.ts

@@ -0,0 +1,10 @@
+import type { ZunoTransport } from "./sync-types";
+/**
+ * Creates a transport for publishing Zuno state events.
+ *
+ * @param url The URL where events will be published.
+ * @param headers Additional headers to include in the HTTP request.
+ * @returns A ZunoTransport object with a publish method.
+ */
+export declare const createTransport: (url: string, headers?: HeadersInit) => ZunoTransport;
+//# sourceMappingURL=transport.d.ts.map

package/dist/sync/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/sync/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,aAAa,EAAE,MAAM,cAAc,CAAC;AAKlE;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,EAAE,UAAU,WAAW,KAAG,aAsBpE,CAAC"}

package/dist/sync/transport.js

@@ -0,0 +1,26 @@
+/**
+ * Creates a transport for publishing Zuno state events.
+ *
+ * @param url The URL where events will be published.
+ * @param headers Additional headers to include in the HTTP request.
+ * @returns A ZunoTransport object with a publish method.
+ */
+export const createTransport = (url, headers) => {
+    /** A set of subscribers to state events. */
+    const subs = new Set();
+    return {
+        async publish(event) {
+            const res = await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", ...headers },
+                body: JSON.stringify(event),
+            });
+            const json = await res.json().catch(() => null);
+            return { ok: res.ok, status: res.status, json };
+        },
+        subscribe(cb) {
+            subs.add(cb);
+            return () => subs.delete(cb);
+        },
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iadev93/zuno",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "author": "Ibrahim Aftab",
   "license": "MIT",
   "type": "module",