@veams/status-quo 0.1.0 → 1.1.0

package/.github/workflows/pages.yml

@@ -0,0 +1,46 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Build docs
+        run: npm run docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

package/.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Build dist
+        run: npm run build
+      - name: Package dist
+        run: |
+          zip -r "dist-${{ github.ref_name }}.zip" dist
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist-${{ github.ref_name }}.zip
+          generate_release_notes: true

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [1.0.0] - 2026-02-17
+
+### 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
+- `StateHandler` renamed to `ObservableStateHandler`.
+- `StateSubscriptionHandler` now uses `subscribe/getSnapshot` (no `getObservable`).
+- Devtools options moved under `options.devTools`.
+
+### Migration
+- Update imports:
+  - From: `StateHandler`
+  - To: `ObservableStateHandler`
+- Implement `subscribe()` and `getSnapshot()` on custom handlers.
+- Replace `getObservable()` usage with `subscribe()` in custom integrations.
+- Update devtools config:
+  - From: `super({ initialState, devTools: { ... } })`
+  - To: `super({ initialState, options: { devTools: { ... } } })`
+
+[1.0.0]: https://github.com/Veams/status-quo/releases/tag/v1.0.0

package/README.md

@@ -1,176 +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()`.
+- 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.
 
-__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._
+## Demo
 
-## Example
+Live docs and demo:
 
-Let's start with a simple state example. 
-You should start with the abstract class `StateHandler`:
+[https://veams.github.io/status-quo/](https://veams.github.io/status-quo/)
+
+## Quickstart
+
+Install:
+
+```bash
+npm install @veams/status-quo rxjs @preact/signals-core
+```
+
+Create a store and use it in a component:
 
 ```ts
-import { useStateFactory, StateHandler } 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 StateHandler<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 StateHandler<CounterState, CounterActions> {
-  constructor([startCount = 0]) {
+class CounterStore extends ObservableStateHandler<CounterState, CounterActions> {
+  constructor() {
     super({
-      initialState: { count: startCount },
-      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:
+
+```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`
 
-export function CounterStateFactory(...args) {
-  return new CounterStateHandler(...args);
+```ts
+function makeStateSingleton<S, A>(
+  factory: () => StateSubscriptionHandler<S, A>
+): {
+  getInstance: () => StateSubscriptionHandler<S, A>;
 }
 ```
 
-We just added the `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/hooks/state-subscription.d.ts

@@ -1,3 +1,2 @@
 import type { StateSubscriptionHandler } from '../types/types.js';
-import type { SetStateAction } from 'react';
-export declare function useStateSubscription<V, A>(stateSubscriptionHandler: StateSubscriptionHandler<V, A>): SetStateAction<V>;
+export declare function useStateSubscription<V, A>(stateSubscriptionHandler: StateSubscriptionHandler<V, A>): V;

package/dist/hooks/state-subscription.js

@@ -1,15 +1,14 @@
-import { useEffect, useState } from 'react';
+import { useCallback, useSyncExternalStore } from 'react';
 export function useStateSubscription(stateSubscriptionHandler) {
-    const [state, setSubscriptionState] = useState(stateSubscriptionHandler.getInitialState());
-    useEffect(() => {
-        const state$ = stateSubscriptionHandler.getObservable().subscribe((data) => {
-            setSubscriptionState(data);
-        });
+    const subscribe = useCallback((listener) => {
+        const unsubscribe = stateSubscriptionHandler.subscribe(listener);
         return () => {
-            state$.unsubscribe();
-            return stateSubscriptionHandler.destroy();
+            unsubscribe();
+            stateSubscriptionHandler.destroy();
         };
     }, [stateSubscriptionHandler]);
-    return state;
+    const getSnapshot = useCallback(() => stateSubscriptionHandler.getSnapshot(), [stateSubscriptionHandler]);
+    const getServerSnapshot = useCallback(() => stateSubscriptionHandler.getInitialState(), [stateSubscriptionHandler]);
+    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }
 //# sourceMappingURL=state-subscription.js.map

package/dist/hooks/state-subscription.js.map

@@ -1 +1 @@
-{"version":3,"file":"state-subscription.js","sourceRoot":"","sources":["../../src/hooks/state-subscription.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAK5C,MAAM,UAAU,oBAAoB,CAClC,wBAAwD;IAExD,MAAM,CAAC,KAAK,EAAE,oBAAoB,CAAC,GAAG,QAAQ,CAC5C,wBAAwB,CAAC,eAAe,EAAE,CAC3C,CAAC;IAEF,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,MAAM,GAAG,wBAAwB,CAAC,aAAa,EAAE,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;YACzE,oBAAoB,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC;QAEH,OAAO,GAAG,EAAE;YACV,MAAM,CAAC,WAAW,EAAE,CAAC;YACrB,OAAO,wBAAwB,CAAC,OAAO,EAAE,CAAC;QAC5C,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,wBAAwB,CAAC,CAAC,CAAC;IAE/B,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"state-subscription.js","sourceRoot":"","sources":["../../src/hooks/state-subscription.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAK1D,MAAM,UAAU,oBAAoB,CAClC,wBAAwD;IAExD,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,QAAkB,EAAE,EAAE;QACrB,MAAM,WAAW,GAAG,wBAAwB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAEjE,OAAO,GAAG,EAAE;YACV,WAAW,EAAE,CAAC;YACd,wBAAwB,CAAC,OAAO,EAAE,CAAC;QACrC,CAAC,CAAC;IACJ,CAAC,EACD,CAAC,wBAAwB,CAAC,CAC3B,CAAC;IAEF,MAAM,WAAW,GAAG,WAAW,CAC7B,GAAG,EAAE,CAAC,wBAAwB,CAAC,WAAW,EAAE,EAC5C,CAAC,wBAAwB,CAAC,CAC3B,CAAC;IAEF,MAAM,iBAAiB,GAAG,WAAW,CACnC,GAAG,EAAE,CAAC,wBAAwB,CAAC,eAAe,EAAE,EAChD,CAAC,wBAAwB,CAAC,CAC3B,CAAC;IAEF,OAAO,oBAAoB,CAAC,SAAS,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAC;AACzE,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { useStateFactory, useStateSingleton } from './hooks/index.js';
-import { makeStateSingleton, StateHandler } from './store/index.js';
+import { BaseStateHandler, makeStateSingleton, ObservableStateHandler, SignalStateHandler } from './store/index.js';
 import type { StateSingleton } from './store/index.js';
 import type { StateSubscriptionHandler } from './types/types.js';
-export { makeStateSingleton, StateHandler, useStateFactory, useStateSingleton };
+export { BaseStateHandler, makeStateSingleton, ObservableStateHandler, SignalStateHandler, useStateFactory, useStateSingleton, };
 export type { StateSingleton, StateSubscriptionHandler };

package/dist/index.js

@@ -1,4 +1,4 @@
 import { useStateFactory, useStateSingleton } from './hooks/index.js';
-import { makeStateSingleton, StateHandler } from './store/index.js';
-export { makeStateSingleton, StateHandler, useStateFactory, useStateSingleton };
+import { BaseStateHandler, makeStateSingleton, ObservableStateHandler, SignalStateHandler, } from './store/index.js';
+export { BaseStateHandler, makeStateSingleton, ObservableStateHandler, SignalStateHandler, useStateFactory, useStateSingleton, };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAKpE,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,GAClB,CAAC"}