@veams/status-quo 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,57 @@ 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.3.0] - 2026-02-25
+
+### Added
+- `setupStatusQuo(config)` runtime setup for global distinct update behavior.
+
+### Changed
+- Handler distinct comparison now supports global defaults (`setupStatusQuo`) with per-handler override precedence.
+
+## [1.2.0] - 2026-02-25
+
+### Added
+- New composable hook APIs:
+  - `useStateHandler(factory, params?)`
+  - `useStateActions(handler)`
+  - `useStateSubscription(source, selector?, isEqual?)`
+- Selector + equality support across shortcut hooks:
+  - `useStateFactory(factory, selector?, isEqual?, params?)`
+  - `useStateSingleton(singleton, selector?, isEqual?)`
+- `StateSingletonOptions` with `destroyOnNoConsumers?: boolean` (default: `true`).
+- Ref-counted singleton lifecycle handling so shared singleton instances are only destroyed when the last consumer unmounts.
+- New hook test coverage for:
+  - composed API usage (`useStateHandler + useStateActions + useStateSubscription`)
+  - selector subscriptions with and without custom equality
+  - singleton subscription behavior and `destroyOnNoConsumers: false`
+  - full-snapshot subscription behavior.
+
+### Changed
+- `useStateFactory` now composes `useStateHandler` + `useStateSubscription` internally.
+- `useStateSubscription` now:
+  - accepts either `StateSubscriptionHandler` or `StateSingleton`
+  - returns `[selectedState, actions]`
+  - supports selector/equality without requiring separate selector-specific hook APIs.
+- `useStateSingleton` is now a shortcut over `useStateSubscription(singleton, selector?, isEqual?)`.
+- `makeStateSingleton` now accepts options and manages instance destruction through explicit lifecycle controls.
+- Public exports extended:
+  - Added `useStateHandler`, `useStateActions`, `useStateSubscription`
+  - Added exported `StateSingletonOptions` type.
+- Observable handler naming aligned with signal convention:
+  - Added `getObservable(key)` as the canonical API.
+
+### Deprecated
+- `ObservableStateHandler#getObservableItem(key)` is now deprecated in favor of `getObservable(key)`.
+
+### Documentation
+- README rewritten with a dedicated API guide that documents base composition, shortcut composition, singleton lifecycle options, and usage examples.
+- Playground documentation significantly expanded:
+  - dedicated API section grouped by base composition, shortcut composition, and helper functions
+  - clearer singleton lifecycle explanation and examples
+  - improved card hierarchy and spacing for readability
+  - responsive/toggleable navigation for better mobile usage.
+
 ## [1.0.0] - 2026-02-17
 
 ### Added
@@ -27,4 +78,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   - From: `super({ initialState, devTools: { ... } })`
   - To: `super({ initialState, options: { devTools: { ... } } })`
 
+[1.3.0]: https://github.com/Veams/status-quo/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/Veams/status-quo/compare/v1.0.0...v1.2.0
 [1.0.0]: https://github.com/Veams/status-quo/releases/tag/v1.0.0

package/README.md

@@ -1,10 +1,10 @@
-# @veams/status-quo 
-[![npm version](https://img.shields.io/npm/v/@veams/status-quo)](https://www.npmjs.com/package/@veams/status-quo)
-
 <center>
 <img src="assets/statusquo-logo.png" width="200" alt="StatusQuo Logo" style="margin: 0 auto;">
 </center>
 
+# @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.
 
 This page mirrors the demo content and adds a full API reference.
@@ -19,10 +19,11 @@ This page mirrors the demo content and adds a full API reference.
 6. [Hooks](#hooks)
 7. [Singletons](#singletons)
 8. [Composition](#composition)
-9. [Devtools](#devtools)
-10. [Cleanup](#cleanup)
-11. [API Reference](#api-reference)
-12. [Migration](#migration)
+9. [API Guide](#api-guide)
+10. [Devtools](#devtools)
+11. [Cleanup](#cleanup)
+12. [API Reference](#api-reference)
+13. [Migration](#migration)
 
 ## Overview
 
@@ -76,6 +77,19 @@ class CounterStore extends ObservableStateHandler<CounterState, CounterActions>
 const [state, actions] = useStateFactory(() => new CounterStore(), []);
 ```
 
+Optional global setup (e.g. with a custom deep-equality comparator):
+
+```ts
+import equal from 'fast-deep-equal';
+import { setupStatusQuo } from '@veams/status-quo';
+
+setupStatusQuo({
+  distinct: {
+    comparator: equal,
+  },
+});
+```
+
 ## Handlers
 
 StatusQuo provides two handler implementations with the same public interface:
@@ -87,22 +101,54 @@ Both are built on `BaseStateHandler`, which provides the shared lifecycle and de
 
 ## Hooks
 
-- `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.
+Use `useStateHandler + useStateActions + useStateSubscription` as the base composition.
+`useStateFactory` and `useStateSingleton` are shortcut APIs over that composition.
+For full signatures and practical examples, see [API Guide](#api-guide).
+
+- `useStateHandler(factory, params)`
+  - Creates and memoizes one handler instance per component.
+- `useStateActions(handler)`
+  - Returns actions without subscribing to state.
+- `useStateSubscription(handlerOrSingleton, selector?, isEqual?)`
+  - Subscribes to full state or a selected slice and returns `[state, actions]`.
+- `useStateFactory(factory, selector?, isEqual?, params?)`
+  - Shortcut for `useStateHandler + useStateSubscription`.
+- `useStateSingleton(singleton, selector?, isEqual?)`
+  - Shortcut for `useStateSubscription(singleton, selector?, isEqual?)`.
+
+Recommended composition:
+
+```ts
+const handler = useStateHandler(createUserStore, []);
+const actions = useStateActions(handler);
+const [name] = useStateSubscription(handler, (state) => state.user.name);
+
+const [singletonName] = useStateSubscription(UserSingleton, (state) => state.user.name);
+```
 
 ## Singletons
 
+Use singletons for shared state across multiple components.
+
 ```ts
 import { makeStateSingleton, useStateSingleton } from '@veams/status-quo';
 
+// Default behavior: singleton is destroyed when the last consumer unmounts.
 const CounterSingleton = makeStateSingleton(() => new CounterStore());
 
 const [state, actions] = useStateSingleton(CounterSingleton);
 ```
 
+Keep a singleton instance alive across unmounts:
+
+```ts
+const PersistentCounterSingleton = makeStateSingleton(() => new CounterStore(), {
+  destroyOnNoConsumers: false,
+});
+```
+
+Use this for app-level stores that should survive route/component unmounts. Keep the default for stores that should release resources when unused.
+
 ## 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`.
@@ -155,6 +201,154 @@ class AppSignalStore extends SignalStateHandler<AppState, AppActions> {
 }
 ```
 
+## API Guide
+
+This section documents the primary public API with behavior notes and usage examples.
+
+### `setupStatusQuo(config?)`
+
+Sets global runtime defaults for distinct update behavior.
+Per-handler options still override the global setup.
+
+```ts
+type StatusQuoConfig = {
+  distinct?: {
+    enabled?: boolean; // default: true
+    comparator?: (previous: unknown, next: unknown) => boolean; // default: JSON compare
+  };
+};
+```
+
+```ts
+import equal from 'fast-deep-equal';
+import { setupStatusQuo } from '@veams/status-quo';
+
+setupStatusQuo({
+  distinct: {
+    comparator: equal,
+  },
+});
+```
+
+### `useStateHandler(factory, params?)`
+
+Creates one handler instance per component mount and returns it.
+
+- `factory`: function returning a `StateSubscriptionHandler`
+- `params`: optional factory params tuple
+- lifecycle note: params are applied when the handler instance is created for that mount
+
+```ts
+const handler = useStateHandler(createUserStore, []);
+```
+
+### `useStateActions(handler)`
+
+Returns actions from a handler without subscribing to state changes.
+Use this in action-only components to avoid rerenders from state updates.
+
+```ts
+const handler = useStateHandler(createUserStore, []);
+const actions = useStateActions(handler);
+```
+
+### `useStateSubscription(source, selector?, isEqual?)`
+
+Subscribes to either a handler instance or a singleton and returns `[selectedState, actions]`.
+
+- `source`: `StateSubscriptionHandler` or `StateSingleton`
+- `selector`: optional projection function; defaults to identity
+- `isEqual`: optional equality function; defaults to `Object.is`
+
+Full snapshot subscription:
+
+```ts
+const handler = useStateHandler(createUserStore, []);
+const [state, actions] = useStateSubscription(handler);
+```
+
+Selector subscription:
+
+```ts
+const [name, actions] = useStateSubscription(
+  handler,
+  (state) => state.user.name
+);
+```
+
+Selector with custom equality:
+
+```ts
+const [profile] = useStateSubscription(
+  handler,
+  (state) => state.user.profile,
+  (current, next) => current.id === next.id && current.role === next.role
+);
+```
+
+Singleton source:
+
+```ts
+const [session, actions] = useStateSubscription(SessionSingleton);
+```
+
+Lifecycle note for singleton sources:
+- Consumers are ref-counted.
+- The singleton instance is only destroyed when the last consumer unmounts and `destroyOnNoConsumers !== false`.
+
+### `useStateFactory(factory, selector?, isEqual?, params?)`
+
+Shortcut API for `useStateHandler + useStateSubscription`.
+
+- `useStateFactory(factory, params)`
+- `useStateFactory(factory, selector, params)`
+- `useStateFactory(factory, selector, isEqual, params)`
+
+```ts
+const [state, actions] = useStateFactory(createUserStore, []);
+const [name] = useStateFactory(createUserStore, (state) => state.user.name, []);
+const [profile] = useStateFactory(
+  createUserStore,
+  (state) => state.user.profile,
+  (current, next) => current.id === next.id,
+  []
+);
+```
+
+### `makeStateSingleton(factory, options?)`
+
+Creates a shared singleton provider for a handler instance.
+
+```ts
+const UserSingleton = makeStateSingleton(() => new UserStore());
+```
+
+Options:
+
+```ts
+type StateSingletonOptions = {
+  destroyOnNoConsumers?: boolean; // default: true
+};
+```
+
+- `true` (default): destroy instance after last consumer unmounts
+- `false`: keep instance alive across periods with zero consumers
+
+```ts
+const PersistentUserSingleton = makeStateSingleton(() => new UserStore(), {
+  destroyOnNoConsumers: false,
+});
+```
+
+### `useStateSingleton(singleton, selector?, isEqual?)`
+
+Shortcut API for `useStateSubscription(singleton, selector?, isEqual?)`.
+
+```ts
+const [state, actions] = useStateSingleton(UserSingleton);
+const [name] = useStateSingleton(UserSingleton, (state) => state.user.name);
+```
+
 ## Devtools
 
 Enable Redux Devtools integration with `options.devTools`:
@@ -241,6 +435,11 @@ protected constructor({
   initialState: S;
   options?: {
     devTools?: { enabled?: boolean; namespace: string };
+    distinct?: {
+      enabled?: boolean;
+      comparator?: (previous: S, next: S) => boolean;
+    };
+    useDistinctUntilChanged?: boolean; // optional override
   };
 })
 ```
@@ -249,11 +448,12 @@ Public methods:
 
 - `getStateAsObservable(options?: { useDistinctUntilChanged?: boolean }): Observable<S>`
 - `getStateItemAsObservable(key: keyof S): Observable<S[keyof S]>`
-- `getObservableItem(key: keyof S): Observable<S[keyof S]>`
+- `getObservable(key: keyof S): Observable<S[keyof S]>`
 - `subscribe(listener: () => void): () => void`
 
 Notes:
-- The observable stream uses `distinctUntilChanged` by default (JSON compare).
+- The observable stream uses `distinctUntilChanged` by default.
+- Distinct behavior can be configured globally via `setupStatusQuo` or per handler via `options.distinct`.
 - `subscribe` does not fire for the initial value; it only fires on subsequent changes.
 
 ### `SignalStateHandler<S, A>`
@@ -270,6 +470,10 @@ protected constructor({
   initialState: S;
   options?: {
     devTools?: { enabled?: boolean; namespace: string };
+    distinct?: {
+      enabled?: boolean;
+      comparator?: (previous: S, next: S) => boolean;
+    };
     useDistinctUntilChanged?: boolean;
   };
 })
@@ -281,23 +485,53 @@ Public methods:
 - `subscribe(listener: () => void): () => void`
 
 Notes:
-- `useDistinctUntilChanged` defaults to `true` (JSON compare).
+- Distinct behavior defaults to enabled.
+- Configure it globally via `setupStatusQuo` or per handler via `options.distinct`.
+- `useDistinctUntilChanged` remains available as a shorthand enable/disable override.
+
+### `setupStatusQuo`
+
+```ts
+type StatusQuoConfig = {
+  distinct?: {
+    enabled?: boolean;
+    comparator?: (previous: unknown, next: unknown) => boolean;
+  };
+};
+
+function setupStatusQuo(config?: StatusQuoConfig): void
+```
 
 ### `makeStateSingleton`
 
 ```ts
+type StateSingletonOptions = {
+  destroyOnNoConsumers?: boolean; // default: true
+};
+
 function makeStateSingleton<S, A>(
-  factory: () => StateSubscriptionHandler<S, A>
+  factory: () => StateSubscriptionHandler<S, A>,
+  options?: StateSingletonOptions
 ): {
   getInstance: () => StateSubscriptionHandler<S, A>;
 }
 ```
 
+Lifecycle behavior:
+- `destroyOnNoConsumers: true` (default): destroy and recreate singleton instances with mount lifecycle.
+- `destroyOnNoConsumers: false`: keep the same singleton instance alive when no component is subscribed.
+
 ### Hooks
 
-- `useStateFactory<V, A, P extends unknown[]>(factory: (...args: P) => StateSubscriptionHandler<V, A>, params?: P)`
+- `useStateHandler<V, A, P extends unknown[]>(factory: (...args: P) => StateSubscriptionHandler<V, A>, params?: P)`
+  - Returns `StateSubscriptionHandler<V, A>`.
+- `useStateActions<V, A>(handler: StateSubscriptionHandler<V, A>)`
+  - Returns `A`.
+- `useStateSubscription<V, A, Sel = V>(source: StateSubscriptionHandler<V, A> | StateSingleton<V, A>, selector?: (state: V) => Sel, isEqual?: (current: Sel, next: Sel) => boolean)`
+  - Returns `[state, actions]`.
+- `useStateFactory<V, A, P extends unknown[], Sel = V>(factory: (...args: P) => StateSubscriptionHandler<V, A>, selector?: (state: V) => Sel, isEqual?: (current: Sel, next: Sel) => boolean, params?: P)`
   - Returns `[state, actions]`.
-- `useStateSingleton<V, A>(singleton: StateSingleton<V, A>)`
+- `useStateSingleton<V, A, Sel = V>(singleton: StateSingleton<V, A>, selector?: (state: V) => Sel, isEqual?: (current: Sel, next: Sel) => boolean)`
   - Returns `[state, actions]`.
 
 ## Migration

package/dist/config/status-quo-config.d.ts

@@ -0,0 +1,21 @@
+export type DistinctComparator<T = unknown> = (previous: T, next: T) => boolean;
+export type DistinctOptions<T = unknown> = {
+    enabled?: boolean;
+    comparator?: DistinctComparator<T>;
+};
+export type StatusQuoConfig<T = unknown> = {
+    distinct?: DistinctOptions<T>;
+};
+type ResolvedDistinctOptions<T = unknown> = {
+    enabled: boolean;
+    comparator: DistinctComparator<T>;
+};
+type ResolvedStatusQuoConfig = {
+    distinct: ResolvedDistinctOptions;
+};
+export declare function setupStatusQuo<T = unknown>(config?: StatusQuoConfig<T>): void;
+export declare function resolveDistinctOptions<T>(options?: DistinctOptions<T>, useDistinctUntilChanged?: boolean): ResolvedDistinctOptions<T>;
+export declare function getStatusQuoConfig(): ResolvedStatusQuoConfig;
+/** @internal testing helper */
+export declare function resetStatusQuoForTests(): void;
+export {};

package/dist/config/status-quo-config.js

@@ -0,0 +1,48 @@
+function distinctAsJson(previous, next) {
+    if (Object.is(previous, next)) {
+        return true;
+    }
+    try {
+        return JSON.stringify(previous) === JSON.stringify(next);
+    }
+    catch {
+        return false;
+    }
+}
+function createDefaultStatusQuoConfig() {
+    return {
+        distinct: {
+            enabled: true,
+            comparator: distinctAsJson,
+        },
+    };
+}
+let statusQuoConfig = createDefaultStatusQuoConfig();
+export function setupStatusQuo(config = {}) {
+    statusQuoConfig = {
+        distinct: {
+            enabled: config.distinct?.enabled ?? true,
+            comparator: (config.distinct?.comparator ?? distinctAsJson),
+        },
+    };
+}
+export function resolveDistinctOptions(options, useDistinctUntilChanged) {
+    return {
+        enabled: options?.enabled ?? useDistinctUntilChanged ?? statusQuoConfig.distinct.enabled,
+        comparator: (options?.comparator ??
+            statusQuoConfig.distinct.comparator),
+    };
+}
+export function getStatusQuoConfig() {
+    return {
+        distinct: {
+            enabled: statusQuoConfig.distinct.enabled,
+            comparator: statusQuoConfig.distinct.comparator,
+        },
+    };
+}
+/** @internal testing helper */
+export function resetStatusQuoForTests() {
+    statusQuoConfig = createDefaultStatusQuoConfig();
+}
+//# sourceMappingURL=status-quo-config.js.map

package/dist/config/status-quo-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-quo-config.js","sourceRoot":"","sources":["../../src/config/status-quo-config.ts"],"names":[],"mappings":"AAoBA,SAAS,cAAc,CAAC,QAAiB,EAAE,IAAa;IACtD,IAAI,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,SAAS,4BAA4B;IACnC,OAAO;QACL,QAAQ,EAAE;YACR,OAAO,EAAE,IAAI;YACb,UAAU,EAAE,cAAc;SAC3B;KACF,CAAC;AACJ,CAAC;AAED,IAAI,eAAe,GAAG,4BAA4B,EAAE,CAAC;AAErD,MAAM,UAAU,cAAc,CAAc,SAA6B,EAAE;IACzE,eAAe,GAAG;QAChB,QAAQ,EAAE;YACR,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,IAAI,IAAI;YACzC,UAAU,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,IAAI,cAAc,CAAuB;SAClF;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,OAA4B,EAC5B,uBAAiC;IAEjC,OAAO;QACL,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,uBAAuB,IAAI,eAAe,CAAC,QAAQ,CAAC,OAAO;QACxF,UAAU,EAAE,CAAC,OAAO,EAAE,UAAU;YAC9B,eAAe,CAAC,QAAQ,CAAC,UAAU,CAA0B;KAChE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,QAAQ,EAAE;YACR,OAAO,EAAE,eAAe,CAAC,QAAQ,CAAC,OAAO;YACzC,UAAU,EAAE,eAAe,CAAC,QAAQ,CAAC,UAAU;SAChD;KACyB,CAAC;AAC/B,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,sBAAsB;IACpC,eAAe,GAAG,4BAA4B,EAAE,CAAC;AACnD,CAAC"}

package/dist/hooks/__tests__/state-selector.spec.d.ts

@@ -0,0 +1,4 @@
+declare global {
+    var IS_REACT_ACT_ENVIRONMENT: boolean;
+}
+export {};