@veams/status-quo 1.7.0 → 1.8.0

package/src/store/__tests__/native-state-handler.spec.ts

@@ -0,0 +1,291 @@
+import { resetStatusQuoForTests, setupStatusQuo } from '../../config/status-quo-config.js';
+import { NativeStateHandler } from '../native-state-handler.js';
+import { makeStateSingleton } from '../state-singleton.js';
+
+import type { DistinctOptions } from '../../config/status-quo-config.js';
+
+type TestState = { test: string; test2: string };
+type TestActions = { testAction: () => void };
+type TestNativeHandlerOptions = {
+  withDevTools?: boolean;
+  distinct?: DistinctOptions<TestState>;
+  useDistinctUntilChanged?: boolean;
+};
+
+class TestNativeStateHandler extends NativeStateHandler<TestState, TestActions> {
+  constructor({ withDevTools, distinct, useDistinctUntilChanged }: TestNativeHandlerOptions = {}) {
+    super({
+      initialState: {
+        test: 'testValue',
+        test2: 'testValue2',
+      },
+      options: {
+        ...(withDevTools && {
+          devTools: {
+            enabled: true,
+            namespace: 'TestNativeStateHandler',
+          },
+        }),
+        ...(distinct && {
+          distinct,
+        }),
+        ...(typeof useDistinctUntilChanged === 'boolean' && {
+          useDistinctUntilChanged,
+        }),
+      },
+    });
+  }
+
+  getActions(): TestActions {
+    return {
+      testAction: () => {
+        this.setState({ test: 'newValue' });
+      },
+    };
+  }
+}
+
+type CounterState = { count: number };
+type CounterActions = { increase: () => void };
+type CounterBucketSelection = { bucket: number };
+type CounterBucketState = { bucket: number };
+
+class CounterNativeStateHandler extends NativeStateHandler<CounterState, CounterActions> {
+  constructor(initialCount = 0) {
+    super({
+      initialState: {
+        count: initialCount,
+      },
+    });
+  }
+
+  getActions(): CounterActions {
+    return {
+      increase: () => {
+        this.setState({ count: this.getState().count + 1 }, 'increase');
+      },
+    };
+  }
+}
+
+class CounterNativeBridgeStateHandler extends NativeStateHandler<
+  CounterState,
+  { noop: () => void }
+> {
+  constructor(
+    counterSingleton: ReturnType<typeof makeStateSingleton<CounterState, CounterActions>>,
+    onCounterSync: (counterState: CounterState) => void
+  ) {
+    super({
+      initialState: {
+        count: 0,
+      },
+    });
+
+    const counterStateHandler = counterSingleton.getInstance();
+
+    this.bindSubscribable<CounterState, CounterState>(
+      counterStateHandler,
+      (nextCounterState) => {
+        onCounterSync(nextCounterState);
+        this.setState({ count: nextCounterState.count }, 'sync-counter');
+      },
+      (counterState) => counterState
+    );
+  }
+
+  getActions(): { noop: () => void } {
+    return {
+      noop: () => undefined,
+    };
+  }
+}
+
+class CounterNativeBucketBridgeStateHandler extends NativeStateHandler<
+  CounterBucketState,
+  { noop: () => void }
+> {
+  constructor(
+    counterSingleton: ReturnType<typeof makeStateSingleton<CounterState, CounterActions>>,
+    onCounterSync: (selection: CounterBucketSelection) => void
+  ) {
+    super({
+      initialState: {
+        bucket: -1,
+      },
+    });
+
+    const counterStateHandler = counterSingleton.getInstance();
+
+    this.bindSubscribable<CounterState, CounterBucketSelection>(
+      counterStateHandler,
+      (nextSelection) => {
+        onCounterSync(nextSelection);
+        this.setState({ bucket: nextSelection.bucket }, 'sync-counter-bucket');
+      },
+      (counterState) => ({
+        bucket: Math.floor(counterState.count / 2),
+      }),
+      (current, next) => current.bucket === next.bucket
+    );
+  }
+
+  getActions(): { noop: () => void } {
+    return {
+      noop: () => undefined,
+    };
+  }
+}
+
+describe('Native State Handler', () => {
+  let stateHandler: TestNativeStateHandler;
+
+  beforeEach(() => {
+    resetStatusQuoForTests();
+    stateHandler = new TestNativeStateHandler();
+  });
+
+  afterEach(() => {
+    resetStatusQuoForTests();
+  });
+
+  it('should provide initial state', () => {
+    expect(stateHandler.getInitialState()).toStrictEqual({
+      test: 'testValue',
+      test2: 'testValue2',
+    });
+  });
+
+  it('should provide current state', () => {
+    expect(stateHandler.getState()).toStrictEqual({
+      test: 'testValue',
+      test2: 'testValue2',
+    });
+  });
+
+  it('should support state changing via setter and merge state object on first level', () => {
+    const expected = {
+      test: 'change',
+      test2: 'testValue2',
+    };
+
+    stateHandler.setState(expected);
+
+    expect(stateHandler.getState()).toStrictEqual(expected);
+  });
+
+  it('should support additional subscriptions handling', () => {
+    const spy = jest.fn();
+    const subscription = { unsubscribe: spy };
+
+    stateHandler.subscriptions = [subscription];
+
+    stateHandler.destroy();
+
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it('should call subscriber when state has changed and also on initial subscribe', () => {
+    const spy = jest.fn();
+    const unsubscribe = stateHandler.subscribe(spy);
+
+    stateHandler.setState({
+      test: 'test',
+    });
+    stateHandler.setState({
+      test: 'test2',
+    });
+    stateHandler.setState({
+      test: 'test2',
+    });
+    stateHandler.setState({
+      test: 'test2',
+    });
+
+    unsubscribe();
+
+    expect(spy).toHaveBeenCalledTimes(3); // initial + change + change
+  });
+
+  it('should respect global distinct setup when disabled', () => {
+    setupStatusQuo({
+      distinct: {
+        enabled: false,
+      },
+    });
+
+    const handler = new TestNativeStateHandler();
+    const spy = jest.fn();
+    const unsubscribe = handler.subscribe(spy);
+
+    handler.setState({ test: 'same' });
+    handler.setState({ test: 'same' });
+
+    unsubscribe();
+
+    expect(spy).toHaveBeenCalledTimes(3); // initial + change + change
+  });
+
+  it('should respect global custom distinct comparator from setupStatusQuo', () => {
+    setupStatusQuo({
+      distinct: {
+        comparator: (previous: TestState, next: TestState) => {
+          return previous.test === next.test;
+        },
+      },
+    });
+
+    const handler = new TestNativeStateHandler();
+    const spy = jest.fn();
+    const unsubscribe = handler.subscribe(spy);
+
+    handler.setState({ test2: 'newValue2' }); // test remains same -> skipped
+    handler.setState({ test: 'newValue' }); // test changed -> notified
+
+    unsubscribe();
+
+    expect(spy).toHaveBeenCalledTimes(2); // initial + one change
+  });
+
+  it('should notify another state handler for each singleton counter update', () => {
+    const counterSingleton = makeStateSingleton(() => new CounterNativeStateHandler(0), {
+      destroyOnNoConsumers: false,
+    });
+    const syncSpy = jest.fn();
+    const bridgeStateHandler = new CounterNativeBridgeStateHandler(counterSingleton, syncSpy);
+    const counterStateHandler = counterSingleton.getInstance();
+
+    counterStateHandler.getActions().increase();
+    counterStateHandler.getActions().increase();
+
+    expect(syncSpy).toHaveBeenCalledTimes(3);
+    expect(syncSpy).toHaveBeenNthCalledWith(1, { count: 0 });
+    expect(syncSpy).toHaveBeenNthCalledWith(2, { count: 1 });
+    expect(syncSpy).toHaveBeenNthCalledWith(3, { count: 2 });
+    expect(bridgeStateHandler.getState()).toStrictEqual({ count: 2 });
+
+    bridgeStateHandler.destroy();
+  });
+
+  it('should support selector + equality filtering for bindSubscribable', () => {
+    const counterSingleton = makeStateSingleton(() => new CounterNativeStateHandler(0), {
+      destroyOnNoConsumers: false,
+    });
+    const syncSpy = jest.fn();
+    const bridgeStateHandler = new CounterNativeBucketBridgeStateHandler(counterSingleton, syncSpy);
+    const counterStateHandler = counterSingleton.getInstance();
+
+    counterStateHandler.getActions().increase(); // count 1 -> bucket 0 (no change)
+    counterStateHandler.getActions().increase(); // count 2 -> bucket 1
+    counterStateHandler.getActions().increase(); // count 3 -> bucket 1 (no change)
+    counterStateHandler.getActions().increase(); // count 4 -> bucket 2
+
+    expect(syncSpy).toHaveBeenCalledTimes(3);
+    expect(syncSpy).toHaveBeenNthCalledWith(1, { bucket: 0 });
+    expect(syncSpy).toHaveBeenNthCalledWith(2, { bucket: 1 });
+    expect(syncSpy).toHaveBeenNthCalledWith(3, { bucket: 2 });
+    expect(bridgeStateHandler.getState()).toStrictEqual({ bucket: 2 });
+
+    bridgeStateHandler.destroy();
+  });
+});

package/src/store/__tests__/observable-state-handler.spec.ts

@@ -5,6 +5,14 @@ import { ObservableStateHandler } from '../observable-state-handler.js';
 
 import type { DevToolsOptions, DistinctOptions } from '../../config/status-quo-config.js';
 
+declare global {
+  interface Window {
+    __REDUX_DEVTOOLS_EXTENSION__?: {
+      connect: (options: any) => any;
+    };
+  }
+}
+
 type TestState = { test: string; test2: string };
 type TestActions = { testAction: () => void };
 type TestObservableHandlerOptions = {

package/src/store/base-state-handler.ts

@@ -1,50 +1,81 @@
+/**
+ * Import internal configuration and utility functions.
+ */
 import { resolveDevToolsOptions } from '../config/status-quo-config.js';
 import { createSelectorCache, selectWithCache } from '../utils/selector-cache.js';
 import { withDevTools } from './dev-tools.js';
 
+/**
+ * Import necessary types for state management and Redux DevTools integration.
+ */
 import type { StateSubscriptionHandler } from '../types/types.js';
 import type { EqualityFn, Selector } from '../utils/selector-cache.js';
 import type { DevTools, MessagePayload } from './dev-tools.js';
 import type { DevToolsOptions } from '../config/status-quo-config.js';
 
+/**
+ * Interface for objects that can be subscribed to.
+ */
 type Subscribable<T> = {
+  // Method to subscribe to changes.
   subscribe: (listener: (value: T) => void) => () => void;
+  // Optional method to get the current snapshot of the state.
   getSnapshot?: () => T;
 };
 
+/**
+ * Configuration for Redux DevTools features enabled in this handler.
+ */
 const devToolsFeatures = {
-  pause: true,
-  lock: true,
-  persist: false,
-  export: true,
-  import: 'custom',
-  jump: true,
-  skip: true,
-  reorder: true,
-  dispatch: false,
-  test: false,
-};
-
+  pause: true, // Allow pausing the recording of actions.
+  lock: true, // Allow locking the state.
+  persist: false, // Do not persist state across reloads by default.
+  export: true, // Allow exporting the state/actions.
+  import: 'custom', // Use custom import logic.
+  jump: true, // Allow jumping to specific states.
+  skip: true, // Allow skipping specific actions.
+  reorder: true, // Allow reordering actions.
+  dispatch: false, // Do not allow dispatching actions from DevTools.
+  test: false, // Do not generate tests.
+} as const;
+
+/**
+ * Abstract base class for all state handlers in the system.
+ * Implements core logic for initialization, DevTools integration, and subscriptions.
+ */
 export abstract class BaseStateHandler<S, A> implements StateSubscriptionHandler<S, A> {
+  // Stores the initial state passed during construction.
   protected readonly initialState: S;
+  // Holds the Redux DevTools instance if enabled.
   protected devTools: DevTools | null = null;
 
+  // Keeps track of active subscriptions to allow for cleanup.
   subscriptions: Array<{ unsubscribe: () => void }> = [];
 
+  /**
+   * Initializes the handler with the given initial state.
+   */
   protected constructor(initialState: S) {
     this.initialState = initialState;
   }
 
+  /**
+   * Sets up Redux DevTools integration based on the provided options.
+   */
   protected initDevTools(devToolsOptions?: DevToolsOptions) {
+    // Resolve the final DevTools configuration.
     const resolvedOptions = resolveDevToolsOptions(devToolsOptions);
 
+    // If DevTools is disabled, stop here.
     if (!resolvedOptions.enabled) {
       this.devTools = null;
       return;
     }
 
+    // Determine the namespace for the DevTools instance.
     const namespace = devToolsOptions?.namespace ?? this.getDevToolsNamespace();
 
+    // Connect to the Redux DevTools extension.
     this.devTools = withDevTools(this.initialState, {
       name: namespace,
       instanceId: namespace.toLowerCase().replaceAll(' ', '-'),
@@ -52,38 +83,67 @@ export abstract class BaseStateHandler<S, A> implements StateSubscriptionHandler
       features: devToolsFeatures,
     });
 
+    // Subscribe to events coming from the DevTools extension (e.g., time travel).
     this.devTools?.subscribe(this.handleDevToolsEvents);
   }
 
+  /**
+   * Returns the initial state of the handler.
+   */
   getInitialState() {
     return this.initialState;
   }
 
+  /**
+   * Returns the current state.
+   */
   getState() {
     return this.getStateValue();
   }
 
+  /**
+   * Alias for getState, often used by React's useSyncExternalStore.
+   */
   getSnapshot() {
     return this.getState();
   }
 
+  /**
+   * Updates the state by merging the partial new state into the current one.
+   * Also sends the update to DevTools if enabled.
+   */
   setState(newState: Partial<S>, actionName = 'change') {
+    // Merge current state with the new partial state.
     const nextState = { ...this.getState(), ...newState };
+    // Update the underlying state value (implemented by subclasses).
     this.setStateValue(nextState);
+    // Notify DevTools of the state change.
     this.devTools?.send(actionName, nextState);
   }
 
+  /**
+   * Cleans up all active subscriptions when the handler is destroyed.
+   */
   destroy(): void {
+    // Execute the unsubscribe function for each tracked subscription.
     this.subscriptions.forEach((subscription) => subscription.unsubscribe());
   }
 
+  // Abstract methods to be implemented by concrete handlers for specific state engines (RxJS, Signals, etc.).
   protected abstract getStateValue(): S;
   protected abstract setStateValue(nextState: S): void;
 
+  /**
+   * Returns a default namespace for DevTools based on the class name.
+   */
   protected getDevToolsNamespace() {
     return this.constructor.name || 'Store';
   }
 
+  /**
+   * Binds an external subscribable source to this handler's state.
+   * Useful for bridging different state systems.
+   */
   protected bindSubscribable<T, Sel>(
     service: Subscribable<T>,
     onChange: (value: Sel) => void,
@@ -97,12 +157,17 @@ export abstract class BaseStateHandler<S, A> implements StateSubscriptionHandler
     selector?: Selector<T, Sel>,
     isEqual: EqualityFn<Sel> = Object.is
   ) {
+    // Default to identity selector if none is provided.
     const selectorFn = (selector ?? ((value: T) => value as unknown as Sel));
+    // Create a cache for selector results to avoid unnecessary updates.
     const selectorCache = createSelectorCache<Sel>();
+    // Flag to track if we received an initial value synchronously during subscription.
     let receivedSyncValue = false;
 
+    // Internal function to handle value changes from the external source.
     const notifySelectedValue = (value: T) => {
       receivedSyncValue = true;
+      // Extract the selected value and check if it has actually changed.
       const { value: nextSelection, hasChanged } = selectWithCache(
         selectorCache,
         value,
@@ -110,6 +175,7 @@ export abstract class BaseStateHandler<S, A> implements StateSubscriptionHandler
         isEqual
       );
 
+      // Only trigger the callback if the selected value changed.
       if (!hasChanged) {
         return;
       }
@@ -117,32 +183,43 @@ export abstract class BaseStateHandler<S, A> implements StateSubscriptionHandler
       onChange(nextSelection);
     };
 
+    // Subscribe to the external source.
     const unsubscribe = service.subscribe(notifySelectedValue);
+    // Track the subscription for later cleanup.
     this.subscriptions = [...(this.subscriptions ?? []), { unsubscribe }];
 
+    // If the source has a getSnapshot method and we haven't received a value yet, pull it manually.
     if (service.getSnapshot && !receivedSyncValue) notifySelectedValue(service.getSnapshot());
   }
 
+  // Abstract methods that must be defined by all concrete state handlers.
   abstract subscribe(listener: () => void): () => void;
   abstract subscribe(listener: (value: S) => void): () => void;
   abstract getActions(): A;
 
+  /**
+   * Handles messages dispatched from the Redux DevTools extension.
+   */
   private handleDevToolsEvents = (message: MessagePayload) => {
+    // We only care about DISPATCH type messages (e.g., reset, jump).
     if (message.type !== 'DISPATCH') {
       return;
     }
 
     switch (message.payload.type) {
+      // Revert state to the initial state.
       case 'RESET':
         this.setStateValue(this.getInitialState());
         this.devTools?.init(this.getInitialState());
         break;
 
+      // Commit the current state in DevTools.
       case 'COMMIT':
         this.setStateValue(this.getState());
         this.devTools?.init(this.getState());
         break;
 
+      // Handle time travel actions.
       case 'JUMP_TO_STATE':
       case 'JUMP_TO_ACTION':
         this.setStateValue(JSON.parse(message.state) as S);

package/src/store/dev-tools.ts

@@ -1,44 +1,89 @@
-declare global {
-  interface Window {
-    __REDUX_DEVTOOLS_EXTENSION__?: {
-      connect: (opts: Record<string, unknown>) => DevTools;
-    };
-  }
-}
+/**
+ * Redux DevTools extension types and constants.
+ */
 
-export type MessagePayload = {
+/**
+ * Interface for messages dispatched from the Redux DevTools extension.
+ */
+export interface MessagePayload {
+  // Type of the message (e.g., 'DISPATCH').
   type: string;
+  // Details about the message, including action type and state.
   payload: {
+    // Specific type of the dispatch action (e.g., 'RESET', 'JUMP_TO_STATE').
     type: string;
-    actionId: number;
+    // Index of the state in the history.
+    stateIndex?: number;
+    // Unique ID for the action.
+    id?: string;
   };
+  // Current state of the store in the DevTools as a JSON string.
   state: string;
-  id: string;
-  source: '@devtools-extension';
-};
+}
 
-export type DevTools = {
-  init: (state: unknown) => void;
+/**
+ * Interface for the Redux DevTools instance returned by the extension.
+ */
+export interface DevTools {
+  // Method to send a new state update to the DevTools extension.
   send: (action: string, state: unknown) => void;
-  subscribe: (cb: (message: MessagePayload) => void) => void;
-};
+  // Method to subscribe to changes coming from the DevTools extension.
+  subscribe: (listener: (message: MessagePayload) => void) => () => void;
+  // Method to initialize the state in the DevTools extension.
+  init: (state: unknown) => void;
+}
 
-export function withDevTools<S>(initialState: S, options = {}): DevTools | null {
-  if (typeof window === 'undefined') {
-    return null;
-  }
+/**
+ * Interface for Redux DevTools connection options.
+ */
+export interface DevToolsConnectionOptions {
+  // Name to be displayed for the store in the DevTools window.
+  name?: string;
+  // Unique ID for the DevTools instance.
+  instanceId?: string;
+  // Action creators that will be available in the DevTools UI.
+  actionCreators?: unknown;
+  // Configuration for specific DevTools features to enable or disable.
+  features?: {
+    pause?: boolean;
+    lock?: boolean;
+    persist?: boolean;
+    export?: boolean | 'custom';
+    import?: boolean | 'custom';
+    jump?: boolean;
+    skip?: boolean;
+    reorder?: boolean;
+    dispatch?: boolean;
+    test?: boolean;
+  };
+}
+
+/**
+ * Connects the state handler to the Redux DevTools browser extension.
+ * Returns a DevTools object to communicate with the extension.
+ */
+export function withDevTools(initialState: unknown, options: DevToolsConnectionOptions): DevTools | null {
+  // Check if the Redux DevTools extension is available in the browser.
+  const extension = (globalThis as any)?.__REDUX_DEVTOOLS_EXTENSION__;
 
-   
-  if (!window.__REDUX_DEVTOOLS_EXTENSION__) {
-    console.error('Status Quo :: Devtools Extension is not installed!');
+  // If the extension is not found, we cannot connect.
+  if (!extension) {
     return null;
   }
 
-   
-  const devTools = window.__REDUX_DEVTOOLS_EXTENSION__.connect(options);
+  // Connect to the extension and get an instance.
+  const devTools = extension.connect(options);
 
+  // Initialize the DevTools instance with the initial state.
   devTools.init(initialState);
 
-   
-  return devTools;
+  // Return an interface to interact with the extension.
+  return {
+    // Send a new action and state to the DevTools.
+    send: (action: string, state: unknown) => devTools.send(action, state),
+    // Subscribe to events coming from the DevTools.
+    subscribe: (listener: (message: MessagePayload) => void) => devTools.subscribe(listener),
+    // Re-initialize the state in the extension.
+    init: (state: unknown) => devTools.init(state),
+  };
 }

package/src/store/index.ts

@@ -1,5 +1,21 @@
+/**
+ * Export core state handler classes and factory functions.
+ */
+
+// Export the abstract base class for all state handlers.
 export { BaseStateHandler } from './base-state-handler.js';
+// Export the lightweight state handler using plain JavaScript.
+export { NativeStateHandler } from './native-state-handler.js';
+// Export the state handler powered by RxJS BehaviorSubjects.
 export { ObservableStateHandler } from './observable-state-handler.js';
+// Export the state handler powered by Preact Signals.
 export { SignalStateHandler } from './signal-state-handler.js';
+
+/**
+ * Export singleton related types and factory function.
+ */
+
+// Export the StateSingleton and StateSingletonOptions interfaces for external typing.
 export type { StateSingleton, StateSingletonOptions } from './state-singleton.js';
+// Export the factory function to create singleton state handler instances.
 export { makeStateSingleton } from './state-singleton.js';