@veams/status-quo 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -9,6 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Added
 - `SignalStateHandler` (signals-backed state handler).
 - `BaseStateHandler` to share devtools and lifecycle APIs.
+- `bindSubscribable` helper for managing external subscriptions.
 - Playground/demo with GitHub Pages deployment.
 
 ### Changed

package/README.md

@@ -1,193 +1,312 @@
-# Status Quo (`@veams/status-quo`)
+# @veams/status-quo 
+[![npm version](https://img.shields.io/npm/v/@veams/status-quo)](https://www.npmjs.com/package/@veams/status-quo)
 
-The `Manager` to rule your state.
+<center>
+<img src="assets/statusquo-logo.png" width="200" alt="StatusQuo Logo" style="margin: 0 auto;">
+</center>
 
----
+The manager to rule your state.
 
-## Table of Content
+This page mirrors the demo content and adds a full API reference.
 
-1. [Getting Started](#getting-started)
-2. [Example](#example)
+## Table of Contents
 
----
+1. [Overview](#overview)
+2. [Philosophy](#philosophy)
+3. [Demo](#demo)
+4. [Quickstart](#quickstart)
+5. [Handlers](#handlers)
+6. [Hooks](#hooks)
+7. [Singletons](#singletons)
+8. [Composition](#composition)
+9. [Devtools](#devtools)
+10. [Cleanup](#cleanup)
+11. [API Reference](#api-reference)
+12. [Migration](#migration)
 
-## Getting Started
+## Overview
 
-1. Create your own state handler which handles all the streams and a state you expose next to the actions
-1. Use actions and state in your component
-1. When using React, initialize the state handler with a custom hook called `useStateFactory()` (or `useStateSingleton()` for Singleton states)
+StatusQuo is a small, framework-agnostic state layer that focuses on explicit lifecycle, clear action APIs, and a minimal subscription surface. It ships two handler implementations with the same public interface: RxJS-backed observables and signals-backed stores.
 
+## Philosophy
 
-These three steps are necessary to create a completely decoupled state management solution without the need of creating custom hooks with `useEffect()`.
-
-__Note__: 
-_Please keep in mind that dependencies for the hook needs to be flattened and cannot be used as an object due to how React works._
+- Swap the engine, keep the API. Your UI code stays the same when you switch from RxJS to Signals.
+- Separate view and state. Handlers own transitions and expose actions; views subscribe to snapshots.
+- Framework-agnostic core. Business logic lives outside the UI library; hooks provide the glue.
 
 ## Demo
 
 Live docs and demo:
 
-```
-https://veams.github.io/status-quo/
-```
+[https://veams.github.io/status-quo/](https://veams.github.io/status-quo/)
 
-## Handlers
+## Quickstart
 
-Status Quo ships two handler implementations with the same public interface:
+Install:
 
-- `ObservableStateHandler` (RxJS-backed)
-- `SignalStateHandler` (Signals-backed)
-
-## Example
+```bash
+npm install @veams/status-quo rxjs @preact/signals-core
+```
 
-Let's start with a simple state example. 
-You should start with the abstract class `ObservableStateHandler`:
+Create a store and use it in a component:
 
 ```ts
-import { useStateFactory, ObservableStateHandler } from '@veams/status-quo';
+import { ObservableStateHandler, useStateFactory } from '@veams/status-quo';
+
+type CounterState = { count: number };
 
-type CounterState = {
-  count: number;
-};
 type CounterActions = {
   increase: () => void;
   decrease: () => void;
 };
 
-class CounterStateHandler extends ObservableStateHandler<CounterState, CounterActions> {
-  constructor([startCount = 0]) {
-    super({ initialState: { count: startCount } });
+class CounterStore extends ObservableStateHandler<CounterState, CounterActions> {
+  constructor() {
+    super({ initialState: { count: 0 } });
   }
-  
-  getActions() {
+
+  getActions(): CounterActions {
     return {
-      increase() {
-        this.setState({
-          count: this.getState() + 1
-        })
-      },
-      decrease() {
-        const currentState = this.getState();
-
-        if (currentState.count > 0) {
-          this.setState({
-            count: currentState - 1
-          })
-        }
-      }
-    }
+      increase: () => this.setState({ count: this.getState().count + 1 }),
+      decrease: () => this.setState({ count: this.getState().count - 1 }),
+    };
   }
 }
 
-export function CounterStateFactory(...args) {
-  return new CounterStateHandler(...args);
-}
+const [state, actions] = useStateFactory(() => new CounterStore(), []);
 ```
 
-This can be used in our factory hook function:
-
-```tsx
-import { useStateFactory } from '@veams/status-quo';
-import { CounterStateFactory } from './counter.state.js';
-
-const Counter = () => {
-  const [state, actions] = useStateFactory(CounterStateFactory, [0]);
-  
-  return (
-    <div>
-      <h2>Counter: {state}</h2>
-      <button onClick={actions.increase}>Increase</button>
-      <button onClick={actions.decrease}>Decrease</button>
-    </div>
-  )
-}
-```
+## Handlers
+
+StatusQuo provides two handler implementations with the same public interface:
+
+- `ObservableStateHandler` (RxJS-backed)
+- `SignalStateHandler` (Signals-backed)
+
+Both are built on `BaseStateHandler`, which provides the shared lifecycle and devtools support.
 
-**What about singletons?**
+## Hooks
 
-Therefore, you can use a simple singleton class or use `makeStateSingleton()` and pass it later on to the singleton hook function:
+- `useStateFactory(factory, deps)`
+  - Creates a handler instance per component and subscribes to its snapshot.
+  - Suitable for per-component or per-instance state.
+- `useStateSingleton(singleton)`
+  - Uses a shared singleton handler across components.
+
+## Singletons
 
 ```ts
-import { makeStateSingleton } from '@veams/status-quo';
+import { makeStateSingleton, useStateSingleton } from '@veams/status-quo';
 
-import { CounterStateHandler } from './counter.state.js';
+const CounterSingleton = makeStateSingleton(() => new CounterStore());
 
-export const CounterStateManager = makeStateSingleton(() => new CounterStateHandler([0]))
+const [state, actions] = useStateSingleton(CounterSingleton);
 ```
 
-```tsx
-import { useStateSingleton } from '@veams/status-quo';
-import { CounterStateManager } from './counter.singleton.js';
-
-const GlobalCounterHandler = () => {
-  const [_, actions] = useStateSingleton(CounterStateManager);
-  
-  return (
-    <div>
-      <button onClick={actions.increase}>Increase</button>
-      <button onClick={actions.decrease}>Decrease</button>
-    </div>
-  )
+## Composition
+
+Use only the slice you need. RxJS makes multi-source composition powerful and declarative with operators like `combineLatest`, `switchMap`, or `debounceTime`. Signals can derive values with `computed` and wire them into a parent store via `bindSubscribable`.
+
+```ts
+import { combineLatest } from 'rxjs';
+
+// RxJS: combine handler streams (RxJS shines here)
+class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
+  private counter$ = CounterObservableStore.getInstance().getStateAsObservable();
+  private card$ = new CardObservableHandler();
+
+  constructor() {
+    super({ initialState: { counter: 0, cardTitle: '' }});
+
+    this.subscriptions.push(
+      combineLatest([
+        this.counter$,
+        this.card$,
+      ]).subscribe(([counterState, cardState]) => {
+        this.setState({
+          counter: counterState,
+          cardTitle: cardState.title,
+        }, 'sync-combined');
+      })
+    )
+  }
+
 }
 
-const GlobalCounterDisplay = () => {
-  const [state] = useStateSingleton(CounterStateManager);
-  
-  return (
-    <div>
-      <h2>Counter: {state}</h2>
-    </div>
-  )
+// Signals: combine derived values via computed + bindSubscribable
+import { computed } from '@preact/signals-core';
+
+class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
+  private counter = CounterSignalHandler.getInstance();
+  private card = new CardSignalHandler();
+  private combined$ = computed(() => ({
+    counter: this.counter.getSignal().value,
+    cardTitle: this.card.getSignal().value.title,
+  }));
+
+  constructor() {
+    super({ initialState: { counter: 0, cardTitle: '' }});
+
+    this.bindSubscribable(
+      { subscribe: this.combined.subscribe.bind(this.combined), getSnapshot: () => this.combined.value },
+      (nextState) => this.setState(nextState, 'sync-combined')
+    );
+  }
 }
 ```
 
-### What about debugging? 
+## Devtools
 
-You know redux-devtools? You like it? We covered you (at least a bit)!
-You can enable the devtools in an easy way: 
+Enable Redux Devtools integration with `options.devTools`:
 
 ```ts
-
-class CounterStateHandler extends ObservableStateHandler<CounterState, CounterActions> {
-  constructor([startCount = 0]) {
+class CounterStore extends ObservableStateHandler<CounterState, CounterActions> {
+  constructor() {
     super({
-      initialState: { count: startCount },
-      options: {
-        devTools: { enabled: true, namespace: 'Counter' },
-      },
+      initialState: { count: 0 },
+      options: { devTools: { enabled: true, namespace: 'Counter' } },
     });
   }
+}
+```
 
-  getActions() {
-    return {
-      increase() {
-        this.setState(
-          {
-            count: this.getState() + 1,
-          },
-          'increase'
-        );
-      },
-      decrease() {
-        const currentState = this.getState();
-
-        if (currentState.count > 0) {
-          this.setState(
-            {
-              count: currentState - 1,
-            },
-            'decrease'
-          );
-        }
-      },
-    };
-  }
+## Cleanup
+
+Handlers expose `subscribe`, `getSnapshot`, and `destroy` for custom integrations:
+
+```ts
+const unsubscribe = store.subscribe(() => {
+  console.log(store.getSnapshot());
+});
+
+unsubscribe();
+store.destroy();
+```
+
+## API Reference
+
+### `StateSubscriptionHandler<V, A>`
+
+Required interface implemented by all handlers.
+
+```ts
+interface StateSubscriptionHandler<V, A> {
+  subscribe: (listener: () => void) => () => void;
+  getSnapshot: () => V;
+  destroy: () => void;
+  getInitialState: () => V;
+  getActions: () => A;
 }
+```
+
+### `BaseStateHandler<S, A>`
+
+Shared base class for all handlers.
+
+Constructor:
+
+```ts
+protected constructor(initialState: S)
+```
+
+Public methods:
+
+- `getInitialState(): S`
+- `getState(): S`
+- `getSnapshot(): S`
+- `setState(next: Partial<S>, actionName = 'change'): void`
+- `subscribe(listener: () => void): () => void` (abstract)
+- `destroy(): void`
+- `getActions(): A` (abstract)
+
+Protected helpers:
+
+- `getStateValue(): S` (abstract)
+- `setStateValue(next: S): void` (abstract)
+- `initDevTools(options?: { enabled?: boolean; namespace: string }): void`
+- `bindSubscribable<T>(service: { subscribe: (listener: (value: T) => void) => () => void; getSnapshot?: () => T }, onChange: (value: T) => void): void`
+  - Registers the subscription on `this.subscriptions` and invokes `onChange` with the current snapshot when available.
+
+### `ObservableStateHandler<S, A>`
+
+RxJS-backed handler. Extends `BaseStateHandler`.
+
+Constructor:
 
-export function CounterStateFactory(...args) {
-  return new CounterStateHandler(...args);
+```ts
+protected constructor({
+  initialState,
+  options
+}: {
+  initialState: S;
+  options?: {
+    devTools?: { enabled?: boolean; namespace: string };
+  };
+})
+```
+
+Public methods:
+
+- `getStateAsObservable(options?: { useDistinctUntilChanged?: boolean }): Observable<S>`
+- `getStateItemAsObservable(key: keyof S): Observable<S[keyof S]>`
+- `getObservableItem(key: keyof S): Observable<S[keyof S]>`
+- `subscribe(listener: () => void): () => void`
+
+Notes:
+- The observable stream uses `distinctUntilChanged` by default (JSON compare).
+- `subscribe` does not fire for the initial value; it only fires on subsequent changes.
+
+### `SignalStateHandler<S, A>`
+
+Signals-backed handler. Extends `BaseStateHandler`.
+
+Constructor:
+
+```ts
+protected constructor({
+  initialState,
+  options
+}: {
+  initialState: S;
+  options?: {
+    devTools?: { enabled?: boolean; namespace: string };
+    useDistinctUntilChanged?: boolean;
+  };
+})
+```
+
+Public methods:
+
+- `getSignal(): Signal<S>`
+- `subscribe(listener: () => void): () => void`
+
+Notes:
+- `useDistinctUntilChanged` defaults to `true` (JSON compare).
+
+### `makeStateSingleton`
+
+```ts
+function makeStateSingleton<S, A>(
+  factory: () => StateSubscriptionHandler<S, A>
+): {
+  getInstance: () => StateSubscriptionHandler<S, A>;
 }
 ```
 
-We just added the `options.devTools` option and also updated the `setState()` function by passing a second argument into it which is the actions name.
-Now you can open up the the browser extension and you are able to take a look at your actions and state(s).
+### Hooks
+
+- `useStateFactory<V, A, P extends unknown[]>(factory: (...args: P) => StateSubscriptionHandler<V, A>, params?: P)`
+  - Returns `[state, actions]`.
+- `useStateSingleton<V, A>(singleton: StateSingleton<V, A>)`
+  - Returns `[state, actions]`.
+
+## Migration
+
+From pre-1.0 releases:
+
+1. Rename `StateHandler` -> `ObservableStateHandler`.
+2. Implement `subscribe()` and `getSnapshot()` on custom handlers.
+3. Replace `getObservable()` usage with `subscribe()` in custom integrations.
+4. Update devtools config:
+   - From: `super({ initialState, devTools: { ... } })`
+   - To: `super({ initialState, options: { devTools: { ... } } })`

package/dist/store/base-state-handler.d.ts

@@ -19,6 +19,10 @@ export declare abstract class BaseStateHandler<S, A> implements StateSubscriptio
     destroy(): void;
     protected abstract getStateValue(): S;
     protected abstract setStateValue(nextState: S): void;
+    protected bindSubscribable<T>(service: {
+        subscribe: (listener: (value: T) => void) => () => void;
+        getSnapshot?: () => T;
+    }, onChange: (value: T) => void): void;
     abstract subscribe(listener: () => void): () => void;
     abstract getActions(): A;
     private handleDevToolsEvents;

package/dist/store/base-state-handler.js

@@ -53,6 +53,12 @@ export class BaseStateHandler {
     destroy() {
         this.subscriptions.forEach((subscription) => subscription.unsubscribe());
     }
+    bindSubscribable(service, onChange) {
+        const unsubscribe = service.subscribe(onChange);
+        this.subscriptions = [...(this.subscriptions ?? []), { unsubscribe }];
+        if (service.getSnapshot)
+            onChange(service.getSnapshot());
+    }
     handleDevToolsEvents = (message) => {
         if (message.type !== 'DISPATCH') {
             return;

package/dist/store/base-state-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-state-handler.js","sourceRoot":"","sources":["../../src/store/base-state-handler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"base-state-handler.js","sourceRoot":"","sources":["../../src/store/base-state-handler.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veams/status-quo",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "The manager to rule states in frontend.",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/playground/src/App.tsx

@@ -16,6 +16,7 @@ import 'prismjs/components/prism-bash';
 import philosophySwap from './assets/philosophy-swap.svg';
 import philosophySeparation from './assets/philosophy-separation.svg';
 import philosophyAgnostic from './assets/philosophy-agnostic.svg';
+import statusQuoLogo from './assets/statusquo-logo.png';
 
 type CounterState = {
   count: number;
@@ -227,48 +228,49 @@ const CounterSingleton = makeStateSingleton(() => new CounterStore());
 
 const [state, actions] = useStateSingleton(CounterSingleton);`;
 
-  const composeSnippet = `// Observable: subscribe to a single field
-class UserStore extends ObservableStateHandler<UserState, UserActions> { /* ... */ }
-class CartStore extends ObservableStateHandler<CartState, CartActions> { /* ... */ }
+  const composeSnippet = `import { combineLatest } from "rxjs";
 
-class AppStore extends ObservableStateHandler<AppState, AppActions> {
-  private user = new UserStore();
-  private cart = new CartStore();
+// RxJS: combine handler streams (RxJS shines here)
+class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
+  private counter$ = CounterObservableStore.getInstance().getStateAsObservable();
+  private card$ = new CardObservableHandler();
 
   constructor() {
-    super({ initialState: { status: this.user.getState().status, cart: this.cart.getState() } });
-
-    this.subscriptions = [
-      { unsubscribe: this.user.getStateItemAsObservable('status').subscribe(() => this.sync()) },
-      { unsubscribe: this.cart.subscribe(() => this.syncCart()) }
-    ];
-  }
-
-  private sync() {
-    this.setState({ status: this.user.getState().status }, 'sync-status');
+    super({ initialState: { counter: 0, cardTitle: "" }});
+    
+    this.subscriptions.push(
+      combineLatest([
+        this.counter$,
+        this.card$,
+      ]).subscribe(([counterState, cardState]) => {
+        this.setState({
+          counter: counterState,
+          cardTitle: cardState.title,
+        }, "sync-combined");
+      })
+    )
   }
 
-  private syncCart() {
-    this.setState({ cart: this.cart.getState() }, 'sync-cart');
-  }
 }
 
-// Signal: derive a single field with computed()
-import { computed } from '@preact/signals-core';
-
-class UserSignalStore extends SignalStateHandler<UserState, UserActions> { /* ... */ }
+// Signals: combine derived values via computed + bindSubscribable
+import { computed } from "@preact/signals-core";
 
 class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
-  private user = new UserSignalStore();
-  private status = computed(() => this.user.getState().status);
+  private counter = CounterSignalHandler.getInstance().getSignal();
+  private card = new CardSignalHandler();
+  private combined = computed(() => ({
+    counter: this.counter.getSignal().value,
+    cardTitle: this.card.getSignal().value.title,
+  }));
 
   constructor() {
-    super({ initialState: { status: this.user.getState().status } });
-    this.subscriptions = [{ unsubscribe: this.user.subscribe(() => this.sync()) }];
-  }
+    super({ initialState: { counter: 0, cardTitle: "" }});
 
-  private sync() {
-    this.setState({ status: this.status.value }, 'sync-status');
+    this.bindSubscribable(
+      { subscribe: this.combined.subscribe.bind(this.combined), getSnapshot: () => this.combined.value },
+      (nextState) => this.setState(nextState, "sync-combined")
+    );
   }
 }`;
 
@@ -279,8 +281,7 @@ class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
   return (
     <div className="app">
       <div className="brand-bar">
-        <span className="brand-dot" />
-        <span>Status Quo Demo</span>
+        <img src={statusQuoLogo} alt="StatusQuo logo" className="brand-logo" />
       </div>
       <nav className="nav">
         <div className="nav-links">
@@ -300,7 +301,7 @@ class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
           <p className="eyebrow">Philosophy</p>
           <h1>State management that stays out of your way</h1>
           <p className="subtext">
-            Status Quo treats state handlers as small, composable objects with explicit
+            <span>StatusQuo</span> treats state handlers as small, composable objects with explicit
             lifecycle and a tiny interface. Components subscribe to snapshots, not
             framework‑specific store APIs. That makes it easy to swap the engine under the
             hood—RxJS for observable streams or Preact Signals for ultra‑light reactive state.
@@ -433,9 +434,10 @@ class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
           <p className="eyebrow">Compose</p>
           <h2>Combine multiple handlers</h2>
           <p>
-            Use only the slice you need. Observables can subscribe to a single key (or use
-            `combineLatest`), while Signals can derive values with `computed`. This keeps
-            parent stores lean and focused.
+            Use only the slice you need. RxJS makes multi-source composition powerful and
+            declarative with operators like `combineLatest`, `switchMap`, or `debounceTime`.
+            Signals can derive values with `computed` and wire them into a parent store via
+            `bindSubscribable`. This keeps parent stores lean and focused.
           </p>
         </div>
         <pre className="code-block">

package/playground/src/styles.css

@@ -54,12 +54,10 @@ body {
   width: 100%;
 }
 
-.brand-dot {
-  width: 12px;
-  height: 12px;
-  border-radius: 50%;
-  background: var(--accent);
-  box-shadow: 0 0 0 4px rgba(47, 107, 255, 0.2);
+.brand-logo {
+  width: 260px;
+  height: auto;
+  display: block;
 }
 
 .nav {
@@ -130,6 +128,12 @@ p {
   margin: 0;
   color: var(--muted);
   line-height: 1.6;
+
+  span {
+    font-family: monospace;
+    font-weight: 700;
+    font-size: .9rem;
+  }
 }
 
 .muted {

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

@@ -78,6 +78,15 @@ export abstract class BaseStateHandler<S, A> implements StateSubscriptionHandler
 
   protected abstract getStateValue(): S;
   protected abstract setStateValue(nextState: S): void;
+  protected bindSubscribable<T>(
+    service: { subscribe: (listener: (value: T) => void) => () => void; getSnapshot?: () => T },
+    onChange: (value: T) => void
+  ) {
+    const unsubscribe = service.subscribe(onChange);
+    this.subscriptions = [...(this.subscriptions ?? []), { unsubscribe }];
+
+    if (service.getSnapshot) onChange(service.getSnapshot());
+  }
 
   abstract subscribe(listener: () => void): () => void;
   abstract getActions(): A;