floppy-disk 3.7.1 → 3.7.2

package/esm/react/create-stream.d.mts

@@ -33,6 +33,50 @@ type StreamDataState<TData, TError> = {
     error: TError;
     errorUpdatedAt: number;
 };
+/**
+ * Represents the full state of a stream.
+ *
+ * @remarks
+ * A stream consists of two independent concerns:
+ *
+ * 1. **Connection state** — lifecycle of the underlying connection
+ * 2. **Data state** — lifecycle of emitted data
+ *
+ * These two are combined into a single state object.
+ *
+ * ---
+ *
+ * ## Connection lifecycle
+ *
+ * - `INITIAL` → no connection has been established
+ * - `CONNECTING` → connection is being established
+ * - `CONNECTED` → connection is active
+ * - `DISCONNECTED` → connection was previously established but is now closed
+ *
+ * Timestamps:
+ * - `connectingAt` → when connection attempt started
+ * - `connectedAt` → when connection was established
+ * - `disconnectedAt` → when connection was closed
+ *
+ * ---
+ *
+ * ## Data lifecycle
+ *
+ * - `INITIAL` → no data has been received
+ * - `SUCCESS` → data has been received successfully
+ * - `ERROR` → error occurred before any data
+ * - `SUCCESS_BUT_THEN_ERROR` → data exists, but a later error occurred
+ *
+ * ---
+ *
+ * ## Notes
+ *
+ * - Connection state and data state evolve independently.
+ * - A stream may be:
+ *   - connected but have no data yet
+ *   - disconnected but still retain previous data
+ * - Errors do not necessarily reset data.
+ */
 export type StreamState<TData, TError> = ({
     connectionState: "INITIAL";
     connectingAt: undefined;
@@ -60,25 +104,218 @@ type DisconnectTrigger = "last-unsubscribe" | "document-hidden" | "offline";
 type ReconnectTrigger = "first-subscribe" | "document-visible" | "online";
 type AdditionalStoreApi<TConnection> = {
     variableHash: string;
+    /**
+     * Connection controls for the stream.
+     *
+     * @remarks
+     * Provides imperative control over the underlying connection.
+     */
     connection: {
+        /**
+         * Returns the current connection instance.
+         *
+         * @returns The active connection or `undefined` if not connected
+         */
         get: () => Readonly<TConnection> | undefined;
+        /**
+         * Forces a reconnection.
+         *
+         * @remarks
+         * - Cancels any scheduled disconnect
+         * - Starts a new connection if not already connecting
+         */
         reconnect: () => void;
+        /**
+         * Immediately disconnects the current connection.
+         *
+         * @remarks
+         * - Ignores disconnect delay rules
+         * - Updates connection state to `DISCONNECTED`
+         */
         disconnect: () => void;
     };
+    /**
+     * Data controls for the stream.
+     */
     data: {
+        /**
+         * Resets the data state back to `INITIAL`.
+         *
+         * @remarks
+         * - Does not affect connection state
+         * - Useful for clearing stale or invalid data
+         */
         reset: () => void;
     };
+    /**
+     * Deletes the stream instance.
+     *
+     * @returns `true` if deleted, `false` otherwise
+     *
+     * @remarks
+     * - Cannot delete while there are active subscribers
+     * - Clears connection, state, and cached instance
+     */
     delete: () => boolean;
 };
+/**
+ * Configuration options for a stream.
+ *
+ * @remarks
+ * Controls connection lifecycle, reconnection behavior, and data retention.
+ */
 export type StreamOptions<TConnection, TData, TError = Error> = InitStoreOptions<StreamState<TData, TError>, AdditionalStoreApi<TConnection>> & {
+    /**
+     * Connection-related behavior.
+     */
     connection?: {
+        /**
+         * Determines when a connection should be disconnected.
+         *
+         * @param trigger - The reason for the disconnect attempt
+         * @param state - Current stream state
+         *
+         * @returns
+         * - `number` → delay (ms) before disconnecting
+         * - `false` → prevent disconnection
+         *
+         * @default Disconnect after 5 seconds for any triggers
+         *
+         * @remarks
+         * Triggers:
+         * - `"last-unsubscribe"` → no active subscribers
+         * - `"document-hidden"` → tab becomes hidden
+         * - `"offline"` → network goes offline
+         */
         disconnectOn?: (trigger: DisconnectTrigger, state: StreamState<TData, TError>) => false | number;
+        /**
+         * Determines whether a connection should reconnect.
+         *
+         * @param trigger - The reason for the reconnect attempt
+         * @param state - Current stream state
+         *
+         * @returns `true` to reconnect, otherwise `false`
+         *
+         * @default No reconnection if already connected
+         *
+         * @remarks
+         * Triggers:
+         * - `"first-subscribe"` → first subscriber appears
+         * - `"document-visible"` → tab becomes visible
+         * - `"online"` → network reconnects
+         */
         reconnectOn?: (trigger: ReconnectTrigger, state: StreamState<TData, TError>) => boolean;
     };
+    /**
+     * Data-related behavior.
+     */
     data?: {
+        /**
+         * Time (in milliseconds) before unused stream data is garbage collected.
+         *
+         * Starts counting after disconnection.
+         *
+         * @default 5 minutes
+         */
         gcTime?: number;
     };
 };
+/**
+ * Creates a stream factory for managing real-time connections.
+ *
+ * @param connect - Function to establish a connection
+ * @param disconnect - Function to close a connection
+ * @param options - Optional configuration for lifecycle and behavior
+ *
+ * @returns A function to retrieve or create a stream instance by variable
+ *
+ * @remarks
+ * This utility is designed for **long-lived, push-based async sources**, such as:
+ * - WebSocket
+ * - Server-Sent Events (SSE)
+ * - Firebase / realtime databases
+ *
+ * ---
+ *
+ * ## Key concepts
+ *
+ * ### 1. Connection lifecycle (managed automatically)
+ *
+ * - Connection is established when needed (e.g. first subscriber)
+ * - Connection may be disconnected based on triggers:
+ *   - no subscribers
+ *   - tab hidden
+ *   - offline
+ * - Reconnection is controlled via `reconnectOn`
+ *
+ * ---
+ *
+ * ### 2. Data flow (push-based)
+ *
+ * The `connect` function receives an `emit` API:
+ *
+ * - `emit.connected()` → mark connection as established
+ * - `emit.data(fn)` → update data using reducer
+ * - `emit.error(err)` → report error
+ *
+ * Data updates are **incremental** and controlled by the stream source.
+ *
+ * ---
+ *
+ * ### 3. Store-per-variable
+ *
+ * - Each unique `variable` creates a separate stream instance
+ * - Variables are deterministically hashed for stable identity
+ * - Each instance manages its own:
+ *   - connection
+ *   - state
+ *   - subscribers
+ *
+ * ---
+ *
+ * ### 4. React integration (Proxy-based)
+ *
+ * - The returned hook exposes the full state as a Proxy
+ * - Components automatically subscribe to accessed properties
+ * - No selector or memoization is required
+ *
+ * ---
+ *
+ * ## Execution model
+ *
+ * - Streams are **lazy**:
+ *   - No connection until there is a subscriber
+ * - Streams are **shared**:
+ *   - Multiple subscribers reuse the same connection
+ * - Streams are **stateful**:
+ *   - Data persists across reconnects (unless reset or GC)
+ *
+ * ---
+ *
+ * @example
+ * const chatStream = createStream(
+ *   (roomId, emit) => {
+ *     const ws = new WebSocket(`/chat/${roomId}`);
+ *
+ *     ws.onopen = () => emit.connected();
+ *     ws.onmessage = (e) => {
+ *       const msg = JSON.parse(e.data);
+ *       emit.data((prev) => [...(prev ?? []), msg]);
+ *     };
+ *     ws.onerror = (err) => emit.error(err);
+ *
+ *     return ws;
+ *   },
+ *   (ws) => ws.close()
+ * );
+ *
+ * function Chat({ roomId }) {
+ *   const useChat = chatStream(roomId);
+ *   const state = useChat();
+ *
+ *   return <div>{state.data?.length}</div>;
+ * }
+ */
 export declare const experimental_createStream: <TConnection, TData, TVariable extends StoreKey, TError = Error>(connect: (variable: TVariable, emit: {
     connected: () => void;
     data: (reducer: (data: TData | undefined) => TData) => void;
@@ -91,14 +328,58 @@ export declare const experimental_createStream: <TConnection, TData, TVariable e
     subscribe: (subscriber: import("../vanilla.d.mts").Subscriber<StreamState<TData, TError>>) => () => void;
     getSubscriberCount: () => number;
     variableHash: string;
+    /**
+     * Connection controls for the stream.
+     *
+     * @remarks
+     * Provides imperative control over the underlying connection.
+     */
     connection: {
+        /**
+         * Returns the current connection instance.
+         *
+         * @returns The active connection or `undefined` if not connected
+         */
         get: () => Readonly<TConnection> | undefined;
+        /**
+         * Forces a reconnection.
+         *
+         * @remarks
+         * - Cancels any scheduled disconnect
+         * - Starts a new connection if not already connecting
+         */
         reconnect: () => void;
+        /**
+         * Immediately disconnects the current connection.
+         *
+         * @remarks
+         * - Ignores disconnect delay rules
+         * - Updates connection state to `DISCONNECTED`
+         */
         disconnect: () => void;
     };
+    /**
+     * Data controls for the stream.
+     */
     data: {
+        /**
+         * Resets the data state back to `INITIAL`.
+         *
+         * @remarks
+         * - Does not affect connection state
+         * - Useful for clearing stale or invalid data
+         */
         reset: () => void;
     };
+    /**
+     * Deletes the stream instance.
+     *
+     * @returns `true` if deleted, `false` otherwise
+     *
+     * @remarks
+     * - Cannot delete while there are active subscribers
+     * - Clears connection, state, and cached instance
+     */
     delete: () => boolean;
 };
 export {};

package/esm/react.mjs

@@ -873,11 +873,14 @@ const experimental_createStream = (connect, disconnect, options = {}) => {
       store.connection = {};
       store.connection.get = () => connections.get(store);
       store.connection.reconnect = () => {
-        var _a;
         clearAllTimeouts(store);
         const { connectionState } = store.getState();
         if (connectionState === "CONNECTING") return;
-        (_a = disconnectFns.get(store)) == null ? void 0 : _a();
+        const prevDisconnect = disconnectFns.get(store);
+        if (prevDisconnect) {
+          prevDisconnect();
+          disconnectFns.delete(store);
+        }
         store.setState({
           connectionState: "CONNECTING",
           connectingAt: Date.now(),
@@ -894,10 +897,10 @@ const experimental_createStream = (connect, disconnect, options = {}) => {
           },
           data: (reducer) => {
             store.setState((prev) => {
-              var _a2;
+              var _a;
               return {
                 connectionState: "CONNECTED",
-                connectedAt: (_a2 = prev.connectedAt) != null ? _a2 : Date.now(),
+                connectedAt: (_a = prev.connectedAt) != null ? _a : Date.now(),
                 state: "SUCCESS",
                 isSuccess: true,
                 isError: false,
@@ -960,7 +963,10 @@ const experimental_createStream = (connect, disconnect, options = {}) => {
     clearAllTimeouts(store);
     const { connectionState } = store.getState();
     if (connectionState === "INITIAL" || connectionState === "DISCONNECTED") {
-      return store.connection.reconnect();
+      queueMicrotask(() => {
+        store.connection.reconnect();
+      });
+      return;
     }
     const shouldReconnect = reconnectOn(trigger, store.getState());
     if (shouldReconnect) store.connection.reconnect();

package/package.json

@@ -2,7 +2,7 @@
   "name": "floppy-disk",
   "description": "Lightweight unified state management for sync and async data.",
   "private": false,
-  "version": "3.7.1",
+  "version": "3.7.2",
   "keywords": [
     "utilities",
     "store",

package/react/create-stream.d.ts

@@ -33,6 +33,50 @@ type StreamDataState<TData, TError> = {
     error: TError;
     errorUpdatedAt: number;
 };
+/**
+ * Represents the full state of a stream.
+ *
+ * @remarks
+ * A stream consists of two independent concerns:
+ *
+ * 1. **Connection state** — lifecycle of the underlying connection
+ * 2. **Data state** — lifecycle of emitted data
+ *
+ * These two are combined into a single state object.
+ *
+ * ---
+ *
+ * ## Connection lifecycle
+ *
+ * - `INITIAL` → no connection has been established
+ * - `CONNECTING` → connection is being established
+ * - `CONNECTED` → connection is active
+ * - `DISCONNECTED` → connection was previously established but is now closed
+ *
+ * Timestamps:
+ * - `connectingAt` → when connection attempt started
+ * - `connectedAt` → when connection was established
+ * - `disconnectedAt` → when connection was closed
+ *
+ * ---
+ *
+ * ## Data lifecycle
+ *
+ * - `INITIAL` → no data has been received
+ * - `SUCCESS` → data has been received successfully
+ * - `ERROR` → error occurred before any data
+ * - `SUCCESS_BUT_THEN_ERROR` → data exists, but a later error occurred
+ *
+ * ---
+ *
+ * ## Notes
+ *
+ * - Connection state and data state evolve independently.
+ * - A stream may be:
+ *   - connected but have no data yet
+ *   - disconnected but still retain previous data
+ * - Errors do not necessarily reset data.
+ */
 export type StreamState<TData, TError> = ({
     connectionState: "INITIAL";
     connectingAt: undefined;
@@ -60,25 +104,218 @@ type DisconnectTrigger = "last-unsubscribe" | "document-hidden" | "offline";
 type ReconnectTrigger = "first-subscribe" | "document-visible" | "online";
 type AdditionalStoreApi<TConnection> = {
     variableHash: string;
+    /**
+     * Connection controls for the stream.
+     *
+     * @remarks
+     * Provides imperative control over the underlying connection.
+     */
     connection: {
+        /**
+         * Returns the current connection instance.
+         *
+         * @returns The active connection or `undefined` if not connected
+         */
         get: () => Readonly<TConnection> | undefined;
+        /**
+         * Forces a reconnection.
+         *
+         * @remarks
+         * - Cancels any scheduled disconnect
+         * - Starts a new connection if not already connecting
+         */
         reconnect: () => void;
+        /**
+         * Immediately disconnects the current connection.
+         *
+         * @remarks
+         * - Ignores disconnect delay rules
+         * - Updates connection state to `DISCONNECTED`
+         */
         disconnect: () => void;
     };
+    /**
+     * Data controls for the stream.
+     */
     data: {
+        /**
+         * Resets the data state back to `INITIAL`.
+         *
+         * @remarks
+         * - Does not affect connection state
+         * - Useful for clearing stale or invalid data
+         */
         reset: () => void;
     };
+    /**
+     * Deletes the stream instance.
+     *
+     * @returns `true` if deleted, `false` otherwise
+     *
+     * @remarks
+     * - Cannot delete while there are active subscribers
+     * - Clears connection, state, and cached instance
+     */
     delete: () => boolean;
 };
+/**
+ * Configuration options for a stream.
+ *
+ * @remarks
+ * Controls connection lifecycle, reconnection behavior, and data retention.
+ */
 export type StreamOptions<TConnection, TData, TError = Error> = InitStoreOptions<StreamState<TData, TError>, AdditionalStoreApi<TConnection>> & {
+    /**
+     * Connection-related behavior.
+     */
     connection?: {
+        /**
+         * Determines when a connection should be disconnected.
+         *
+         * @param trigger - The reason for the disconnect attempt
+         * @param state - Current stream state
+         *
+         * @returns
+         * - `number` → delay (ms) before disconnecting
+         * - `false` → prevent disconnection
+         *
+         * @default Disconnect after 5 seconds for any triggers
+         *
+         * @remarks
+         * Triggers:
+         * - `"last-unsubscribe"` → no active subscribers
+         * - `"document-hidden"` → tab becomes hidden
+         * - `"offline"` → network goes offline
+         */
         disconnectOn?: (trigger: DisconnectTrigger, state: StreamState<TData, TError>) => false | number;
+        /**
+         * Determines whether a connection should reconnect.
+         *
+         * @param trigger - The reason for the reconnect attempt
+         * @param state - Current stream state
+         *
+         * @returns `true` to reconnect, otherwise `false`
+         *
+         * @default No reconnection if already connected
+         *
+         * @remarks
+         * Triggers:
+         * - `"first-subscribe"` → first subscriber appears
+         * - `"document-visible"` → tab becomes visible
+         * - `"online"` → network reconnects
+         */
         reconnectOn?: (trigger: ReconnectTrigger, state: StreamState<TData, TError>) => boolean;
     };
+    /**
+     * Data-related behavior.
+     */
     data?: {
+        /**
+         * Time (in milliseconds) before unused stream data is garbage collected.
+         *
+         * Starts counting after disconnection.
+         *
+         * @default 5 minutes
+         */
         gcTime?: number;
     };
 };
+/**
+ * Creates a stream factory for managing real-time connections.
+ *
+ * @param connect - Function to establish a connection
+ * @param disconnect - Function to close a connection
+ * @param options - Optional configuration for lifecycle and behavior
+ *
+ * @returns A function to retrieve or create a stream instance by variable
+ *
+ * @remarks
+ * This utility is designed for **long-lived, push-based async sources**, such as:
+ * - WebSocket
+ * - Server-Sent Events (SSE)
+ * - Firebase / realtime databases
+ *
+ * ---
+ *
+ * ## Key concepts
+ *
+ * ### 1. Connection lifecycle (managed automatically)
+ *
+ * - Connection is established when needed (e.g. first subscriber)
+ * - Connection may be disconnected based on triggers:
+ *   - no subscribers
+ *   - tab hidden
+ *   - offline
+ * - Reconnection is controlled via `reconnectOn`
+ *
+ * ---
+ *
+ * ### 2. Data flow (push-based)
+ *
+ * The `connect` function receives an `emit` API:
+ *
+ * - `emit.connected()` → mark connection as established
+ * - `emit.data(fn)` → update data using reducer
+ * - `emit.error(err)` → report error
+ *
+ * Data updates are **incremental** and controlled by the stream source.
+ *
+ * ---
+ *
+ * ### 3. Store-per-variable
+ *
+ * - Each unique `variable` creates a separate stream instance
+ * - Variables are deterministically hashed for stable identity
+ * - Each instance manages its own:
+ *   - connection
+ *   - state
+ *   - subscribers
+ *
+ * ---
+ *
+ * ### 4. React integration (Proxy-based)
+ *
+ * - The returned hook exposes the full state as a Proxy
+ * - Components automatically subscribe to accessed properties
+ * - No selector or memoization is required
+ *
+ * ---
+ *
+ * ## Execution model
+ *
+ * - Streams are **lazy**:
+ *   - No connection until there is a subscriber
+ * - Streams are **shared**:
+ *   - Multiple subscribers reuse the same connection
+ * - Streams are **stateful**:
+ *   - Data persists across reconnects (unless reset or GC)
+ *
+ * ---
+ *
+ * @example
+ * const chatStream = createStream(
+ *   (roomId, emit) => {
+ *     const ws = new WebSocket(`/chat/${roomId}`);
+ *
+ *     ws.onopen = () => emit.connected();
+ *     ws.onmessage = (e) => {
+ *       const msg = JSON.parse(e.data);
+ *       emit.data((prev) => [...(prev ?? []), msg]);
+ *     };
+ *     ws.onerror = (err) => emit.error(err);
+ *
+ *     return ws;
+ *   },
+ *   (ws) => ws.close()
+ * );
+ *
+ * function Chat({ roomId }) {
+ *   const useChat = chatStream(roomId);
+ *   const state = useChat();
+ *
+ *   return <div>{state.data?.length}</div>;
+ * }
+ */
 export declare const experimental_createStream: <TConnection, TData, TVariable extends StoreKey, TError = Error>(connect: (variable: TVariable, emit: {
     connected: () => void;
     data: (reducer: (data: TData | undefined) => TData) => void;
@@ -91,14 +328,58 @@ export declare const experimental_createStream: <TConnection, TData, TVariable e
     subscribe: (subscriber: import("../vanilla.ts").Subscriber<StreamState<TData, TError>>) => () => void;
     getSubscriberCount: () => number;
     variableHash: string;
+    /**
+     * Connection controls for the stream.
+     *
+     * @remarks
+     * Provides imperative control over the underlying connection.
+     */
     connection: {
+        /**
+         * Returns the current connection instance.
+         *
+         * @returns The active connection or `undefined` if not connected
+         */
         get: () => Readonly<TConnection> | undefined;
+        /**
+         * Forces a reconnection.
+         *
+         * @remarks
+         * - Cancels any scheduled disconnect
+         * - Starts a new connection if not already connecting
+         */
         reconnect: () => void;
+        /**
+         * Immediately disconnects the current connection.
+         *
+         * @remarks
+         * - Ignores disconnect delay rules
+         * - Updates connection state to `DISCONNECTED`
+         */
         disconnect: () => void;
     };
+    /**
+     * Data controls for the stream.
+     */
     data: {
+        /**
+         * Resets the data state back to `INITIAL`.
+         *
+         * @remarks
+         * - Does not affect connection state
+         * - Useful for clearing stale or invalid data
+         */
         reset: () => void;
     };
+    /**
+     * Deletes the stream instance.
+     *
+     * @returns `true` if deleted, `false` otherwise
+     *
+     * @remarks
+     * - Cannot delete while there are active subscribers
+     * - Clears connection, state, and cached instance
+     */
     delete: () => boolean;
 };
 export {};

package/react.js

@@ -875,11 +875,14 @@ const experimental_createStream = (connect, disconnect, options = {}) => {
       store.connection = {};
       store.connection.get = () => connections.get(store);
       store.connection.reconnect = () => {
-        var _a;
         clearAllTimeouts(store);
         const { connectionState } = store.getState();
         if (connectionState === "CONNECTING") return;
-        (_a = disconnectFns.get(store)) == null ? void 0 : _a();
+        const prevDisconnect = disconnectFns.get(store);
+        if (prevDisconnect) {
+          prevDisconnect();
+          disconnectFns.delete(store);
+        }
         store.setState({
           connectionState: "CONNECTING",
           connectingAt: Date.now(),
@@ -896,10 +899,10 @@ const experimental_createStream = (connect, disconnect, options = {}) => {
           },
           data: (reducer) => {
             store.setState((prev) => {
-              var _a2;
+              var _a;
               return {
                 connectionState: "CONNECTED",
-                connectedAt: (_a2 = prev.connectedAt) != null ? _a2 : Date.now(),
+                connectedAt: (_a = prev.connectedAt) != null ? _a : Date.now(),
                 state: "SUCCESS",
                 isSuccess: true,
                 isError: false,
@@ -962,7 +965,10 @@ const experimental_createStream = (connect, disconnect, options = {}) => {
     clearAllTimeouts(store);
     const { connectionState } = store.getState();
     if (connectionState === "INITIAL" || connectionState === "DISCONNECTED") {
-      return store.connection.reconnect();
+      queueMicrotask(() => {
+        store.connection.reconnect();
+      });
+      return;
     }
     const shouldReconnect = reconnectOn(trigger, store.getState());
     if (shouldReconnect) store.connection.reconnect();