synstate 0.1.2 → 1.0.1

package/README.md

@@ -1,7 +1,7 @@
 # SynState
 
 <p align="center">
-  <img src="./assets/synstate-icon.png" alt="SynState Logo" width="400" />
+  <img src="./assets/synstate-logo.png" alt="SynState Logo" width="400" />
 </p>
 
 <p align="center">
@@ -9,26 +9,30 @@
 [![npm version](https://img.shields.io/npm/v/synstate.svg)](https://www.npmjs.com/package/synstate)
 [![npm downloads](https://img.shields.io/npm/dm/synstate.svg)](https://www.npmjs.com/package/synstate)
 [![License](https://img.shields.io/npm/l/synstate.svg)](./LICENSE)
-[![codecov](https://codecov.io/gh/noshiro-pf/synstate/graph/badge.svg?token=xrJgTVxMpr)](https://codecov.io/gh/noshiro-pf/synstate)
+[![codecov](https://codecov.io/gh/noshiro-pf/synstate/graph/badge.svg)](https://codecov.io/gh/noshiro-pf/synstate)
 
 </p>
 
 **SynState** is a lightweight, high-performance, type-safe state management library for TypeScript/JavaScript applications. Perfect for building reactive global state and event-driven systems in React, Vue, and other frameworks.
 
+"SynState" is named after "Synchronized + State." It represents a sound synchronized state through a **glitch-free**[^1] Observable implementation.
+
+[^1]: See ["How SynState solved the glitch?"](./documents/how-synstate-solved-the-glitch.md).
+
 ## Features
 
-- 🎯 **Simple State Management**: Easy-to-use `createState` and `createReducer` for global state
-- 📡 **Event System**: Built-in `createValueEmitter`, `createEventEmitter` for event-driven architecture
-- 🔄 **Reactive Updates**: Automatic propagation of state changes to all subscribers
-- 🎨 **Type-Safe**: Full TypeScript support with precise type inference
-- 🚀 **Lightweight**: Minimal bundle size with only one external runtime dependency ([ts-data-forge](https://www.npmjs.com/package/ts-data-forge))
+- 🎯 **Simple State Management**: Easy-to-use `createState` and `createReducer` similar to React useState/useReducer for global state
 - ⚡ **High Performance**: Optimized for fast state updates and minimal re-renders
+- 🎨 **Type-Safe**: Full TypeScript support with precise type inference
+- 🚀 **Lightweight**: <!-- bundle-size:synstate -->~4.5 kB min+gzip<!-- /bundle-size:synstate --> with only one external runtime dependency ([ts-data-forge](https://www.npmjs.com/package/ts-data-forge))
 - 🌐 **Framework Agnostic**: Works with React, Vue, Svelte, or vanilla JavaScript
-- 🔧 **Observable-based**: Built on Observable pattern similar to RxJS, but with a completely independent implementation from scratch — not a wrapper. Offers optional advanced features like operators (`map`, `filter`, `scan`, `debounceTime`) and combinators (`merge`, `combine`)
+- 🔄 **Reactive Updates**: Automatic propagation of state changes to all subscribers
+- 📡 **Event System**: Built-in `createValueEmitter`, `createEventEmitter` for event-driven architecture
+- 🔧 **Observable-based**: Built on Observable pattern similar to RxJS, but with a completely independent implementation from scratch — not a wrapper. Offers optional advanced features like operators (`map`, `filter`, `scan`, `debounce`) and combinators (`merge`, `combine`)
 
 ## Documentation
 
-- API reference: TBD <!-- <https://noshiro-pf.github.io/synstate/> -->
+- <https://noshiro-pf.github.io/synstate/>
 
 ## Installation
 
@@ -52,63 +56,46 @@ pnpm add synstate
 
 ```tsx
 // Create a reactive state
-const [state, setState, { updateState, resetState, getSnapshot }] =
-    createState(0);
+const [state, setState] = createState(0);
+// type of state: InitializedObservable<number>
+// type of setState: (v: number) => number
 
-const mut_history: number[] = [];
+const stateHistory: number[] = [];
 
-// Subscribe to changes (in React components, Vue watchers, etc.)
+// Subscribe to changes
 state.subscribe((count) => {
-    mut_history.push(count);
+    stateHistory.push(count);
 });
 
-assert.deepStrictEqual(mut_history, [0]);
+assert.deepStrictEqual(stateHistory, [0]);
 
 // Update state
 setState(1);
 
-assert.deepStrictEqual(mut_history, [0, 1]);
-
-updateState((prev) => prev + 2);
-
-assert.deepStrictEqual(mut_history, [0, 1, 3]);
-
-assert.isTrue(getSnapshot() === 3);
-
-resetState();
-
-assert.isTrue(getSnapshot() === 0);
+assert.deepStrictEqual(stateHistory, [0, 1]);
 ```
 
 ### With React
 
+```bash
+npm add synstate-react-hooks
+```
+
 ```tsx
-import * as React from 'react';
-import { createState } from 'synstate';
+import type * as React from 'react';
+import { createState } from 'synstate-react-hooks';
 
-// Global state (outside component)
-const [userState, setUserState, { getSnapshot }] = createState({
+const [useUserState, setUserState] = createState({
     name: '',
     email: '',
 });
 
 const UserProfile = (): React.JSX.Element => {
-    const [user, setUser] = React.useState(getSnapshot());
-
-    React.useEffect(() => {
-        const subscription = userState.subscribe(setUser);
-
-        return () => {
-            subscription.unsubscribe();
-        };
-    }, []);
+    const user = useUserState();
 
     return (
         <div>
-            <p>
-                {'Name: '}
-                {user.name}
-            </p>
+            <p>{`Name: ${user.name}`}</p>
             <button
                 onClick={() => {
                     setUserState({
@@ -124,7 +111,7 @@ const UserProfile = (): React.JSX.Element => {
 };
 ```
 
-If you're using React v18 or later:
+This is equivalent to the following code without synstate-react-hook:
 
 ```tsx
 import * as React from 'react';
@@ -147,10 +134,7 @@ const UserProfile = (): React.JSX.Element => {
 
     return (
         <div>
-            <p>
-                {'Name: '}
-                {user.name}
-            </p>
+            <p>{`Name: ${user.name}`}</p>
             <button
                 onClick={() => {
                     setUserState({
@@ -166,30 +150,34 @@ const UserProfile = (): React.JSX.Element => {
 };
 ```
 
-You can write the equivalent code more concisely using synstate-react-hooks:
+See also the [synstate-react-hooks README](../synstate-react-hooks/README.md).
 
-```bash
-npm add synstate-react-hooks
-```
+If you're using React v17 or earlier:
 
 ```tsx
-import type * as React from 'react';
-import { createState } from 'synstate-react-hooks';
+import * as React from 'react';
+import { createState } from 'synstate';
 
-const [useUserState, setUserState] = createState({
+// Global state (outside component)
+const [userState, setUserState, { getSnapshot }] = createState({
     name: '',
     email: '',
 });
 
 const UserProfile = (): React.JSX.Element => {
-    const user = useUserState();
+    const [user, setUser] = React.useState(getSnapshot());
+
+    React.useEffect(() => {
+        const subscription = userState.subscribe(setUser);
+
+        return () => {
+            subscription.unsubscribe();
+        };
+    }, []);
 
     return (
         <div>
-            <p>
-                {'Name: '}
-                {user.name}
-            </p>
+            <p>{`Name: ${user.name}`}</p>
             <button
                 onClick={() => {
                     setUserState({
@@ -205,59 +193,92 @@ const UserProfile = (): React.JSX.Element => {
 };
 ```
 
-See also the [synstate-react-hooks README](../synstate-react-hooks/README.md).
+## Why SynState?
 
-## Core Concepts
+### Simple to Start, Powerful When You Need It
 
-### State Management
+SynState is a state management library for web frontends. For most use cases, `createState`, `createReducer`, and simple combinators like `combine` and `map` are all you need — clean, minimal APIs that feel as intuitive as React's `useState` / `useReducer`, but for global state.
 
-SynState provides simple, intuitive APIs for managing application state:
+When your requirements grow more complex, SynState scales with you. Built on its own Observable implementation, it provides operators like `debounce`, `throttle`, `switchMap`, and `mergeMap` for sophisticated asynchronous state management — without requiring an additional library like RxJS. You can describe everything from a simple counter to a debounced search pipeline with auto-cancellation in a single, unified API.
 
-- **`createState`**: Create state with getter/setter
-- **`createReducer`**: Create state by reducer and initial value
-- **`createBooleanState`**: Specialized state for boolean values
+### Why Observable-Based?
 
-### Event System
+A state management library that scales from simple global state to complex asynchronous workflows needs **reactive value propagation** at its core — when one piece of state changes, all derived values must update automatically and consistently. The Observable pattern is a natural fit for this: it models state as streams of values that can be composed, transformed, and combined declaratively.
 
-Built-in event emitter for event-driven patterns:
+RxJS is the most well-known Observable library, and it excels at modeling asynchronous event processing. However, RxJS has a fundamental issue known as **glitch**[^1] — a phenomenon where derived values can temporarily enter inconsistent intermediate states during synchronous propagation. For a state management library, where consistency of derived state is critical, this is unacceptable. SynState was built from scratch with a glitch-free Observable implementation to solve this problem.
 
-- **`createValueEmitter`**: Create type-safe event emitters
-- **`createEventEmitter`**: Create event emitters without payload
+For a detailed explanation, see ["How SynState solved the glitch?"](./documents/how-synstate-solved-the-glitch.md).
 
-### Observable (Optional Advanced Feature)
+### Key Differences from RxJS
 
-For advanced use cases, you can use observables to build complex reactive data flows. However, most applications will only need `createState`, `createReducer`, and `createValueEmitter`.
+- **Glitch free**: While RxJS Observables suffer from a troublesome phenomenon called glitch [^1], SynState Observables are glitch-free.
+- **InitializedObservable**: Provides `InitializedObservable` which always holds an initial value, making it ideal for representing state
+- **Focus on State Management**: Designed specifically for state management, not just asynchronous event processing. SynState provides utility functions `createState`, `createReducer`, and `createBooleanState`. However, this doesn't mean it's inadequate for asynchronous event processing — it can handle asynchronous operations as elegantly as RxJS.
 
-## API Reference
+### Use Cases
 
-For complex scenarios, SynState provides observable-based APIs:
+**Use SynState when you need:**
 
-### Creation Functions
+- ✅ A small piece of global state shared across components (e.g., dark mode toggle, user session)
+- ✅ Complex asynchronous state management with operators like `debounce`, `throttle`, `switchMap`
+- ✅ Redux-like state with reducers (`createReducer`)
+- ✅ A project where the scale of state management is uncertain — SynState's unified API covers everything from a single shared counter to a full debounced search pipeline, so you never have to switch libraries as requirements grow
+- ✅ Type-safe event emitters (`createEventEmitter`)
 
-- `source<T>()`: Create a new observable source
-- `of(value)`: Create observable from a single value
-- `fromArray(array)`: Create observable from array
-- `fromPromise(promise)`: Create observable from promise
-- `interval(ms)`: Emit values at intervals
-- `timer(delay)`: Emit after delay
+**Consider other solutions when:**
 
-### Operators
+- You only need a React component (local) state (use React hooks `useState`, `useReducer`)
 
-- `filter(predicate)`: Filter values
-- `map(fn)`: Transform values
-- `scan(reducer, seed)`: Accumulate values
-- `debounceTime(ms)`: Debounce emissions
-- `throttleTime(ms)`: Throttle emissions
-- `skipIfNoChange()`: Skip duplicate values
-- `takeUntil(notifier)`: Complete on notifier emission
+## Examples
 
-### Combination
+### Simple State with Additional APIs
 
-- `combine(observables)`: Combine latest values from multiple sources
-- `merge(observables)`: Merge multiple streams
-- `zip(observables)`: Pair values by index
+```tsx
+// Create a reactive state
+const [
+    state,
+    setState,
+    { updateState, resetState, getSnapshot, initialState },
+] = createState(0);
+// type of state: InitializedObservable<number>
+// type of setState: (v: number) => number
+// type of updateState: (updater: (prev: number) => number) => number
+// type of resetState: () => void
+// type of getSnapshot: () => number
+// type of initialState: number
+
+const stateHistory: number[] = [];
+
+// Subscribe to changes
+state.subscribe((count) => {
+    stateHistory.push(count);
+});
 
-## Examples
+assert.deepStrictEqual(stateHistory, [0]);
+
+assert.strictEqual(getSnapshot(), 0);
+
+// Update state
+setState(1);
+
+assert.strictEqual(getSnapshot(), 1);
+
+assert.deepStrictEqual(stateHistory, [0, 1]);
+
+updateState((prev) => prev + 2);
+
+assert.strictEqual(getSnapshot(), 3);
+
+assert.deepStrictEqual(stateHistory, [0, 1, 3]);
+
+resetState();
+
+assert.strictEqual(getSnapshot(), 0);
+
+assert.strictEqual(initialState, 0);
+
+assert.deepStrictEqual(stateHistory, [0, 1, 3, 0]);
+```
 
 ### Global Counter State (React)
 
@@ -266,8 +287,11 @@ import type * as React from 'react';
 import { createState } from 'synstate-react-hooks';
 
 // Create global state
-export const [useCounterState, , { updateState, resetState, getSnapshot }] =
-    createState(0);
+export const [useCounterState, , { updateState, resetState }] = createState(0);
+
+const increment = (): void => {
+    updateState((n) => n + 1);
+};
 
 // Component 1
 const Counter = (): React.JSX.Element => {
@@ -275,30 +299,15 @@ const Counter = (): React.JSX.Element => {
 
     return (
         <div>
-            <p>
-                {'Count: '}
-                {count}
-            </p>
-            <button
-                onClick={() => {
-                    updateState((n: number) => n + 1);
-                }}
-            >
-                {'Increment'}
-            </button>
+            <p>{`Count: ${count}`}</p>
+            <button onClick={increment}>{'Increment'}</button>
         </div>
     );
 };
 
-// Component 2 (synced automatically)
+// Component 2
 const ResetButton = (): React.JSX.Element => (
-    <button
-        onClick={() => {
-            resetState();
-        }}
-    >
-        {'Reset'}
-    </button>
+    <button onClick={resetState}>{'Reset'}</button>
 );
 ```
 
@@ -320,7 +329,7 @@ type Action = Readonly<
     | { type: 'remove'; id: number }
 >;
 
-const initialTodos: readonly Todo[] = [];
+const initialTodos: readonly Todo[] = [] as const;
 
 const reducer = (todos: readonly Todo[], action: Action): readonly Todo[] => {
     switch (action.type) {
@@ -475,17 +484,15 @@ const ItemList = (): React.JSX.Element => {
 };
 ```
 
-// Events
-
 ### Advanced: Search with Debounce
 
 ```tsx
 import type * as React from 'react';
 import {
     createState,
-    debounceTime,
+    debounce,
     filter,
-    fromPromise,
+    fromAbortablePromise,
     type InitializedObservable,
     map,
     switchMap,
@@ -500,12 +507,12 @@ const [searchState, setSearchState] = createState('');
 const searchResults$: InitializedObservable<
     readonly Readonly<{ id: string; name: string }>[]
 > = searchState
-    .pipe(debounceTime(300))
+    .pipe(debounce(300))
     .pipe(filter((query) => query.length > 2))
     .pipe(
         switchMap((query) =>
-            fromPromise(
-                fetch(`/api/search?q=${query}`).then(
+            fromAbortablePromise((signal) =>
+                fetch(`/api/search?q=${query}`, { signal }).then(
                     (r) =>
                         r.json() as Promise<
                             readonly Readonly<{ id: string; name: string }>[]
@@ -542,10 +549,12 @@ const SearchBox = (): React.JSX.Element => {
 ### Advanced: Event Emitter with Throttle
 
 ```tsx
-import { createEventEmitter, throttleTime } from 'synstate';
+import { createEventEmitter, throttle } from 'synstate';
 
 // Create event emitter
 const [refreshClicked, onRefreshClick] = createEventEmitter();
+// refreshClicked: Observable<void>
+// onRefreshClick: () => void
 
 // Subscribe to events
 refreshClicked.subscribe(() => {
@@ -553,7 +562,7 @@ refreshClicked.subscribe(() => {
 });
 
 // Throttle refresh clicks to prevent rapid successive executions
-const throttledRefresh = refreshClicked.pipe(throttleTime(2000));
+const throttledRefresh = refreshClicked.pipe(throttle(2000));
 
 throttledRefresh.subscribe(() => {
     console.log('Executing refresh...');
@@ -572,38 +581,82 @@ const DataTable = (): React.JSX.Element => (
 );
 ```
 
-## Why SynState?
+## API Reference
+
+### State Management
+
+SynState provides simple, intuitive APIs for managing application state:
 
-### Simple State Management, Not Complex Reactive Programming
+- **`createState`**: Create state with InitializedObservable and setter
+- **`createReducer`**: Create state by reducer and initial value
+- **`createBooleanState`**: Specialized state for boolean values
 
-SynState is a state management library for web frontends, similar to Redux, Jotai, Zustand, and MobX. It provides APIs for creating and managing global state across your application.
+### Event System
 
-Under the hood, SynState is built on Observable patterns similar to those provided by RxJS. However, unlike RxJS, which can make code harder to read with many operators and complex streams, SynState focuses on **simple, readable state management and event handling**. Most applications only need `createState`, `createReducer`, and simple operators/combinators like `combine` and `map` — clean, straightforward APIs that developers understand immediately.
+Built-in event emitter for event-driven patterns:
 
-**Advanced reactive features are optional** and only used when you actually need them (like debouncing search input). The library doesn't force you into a reactive programming mindset.
+- **`createValueEmitter`**: Create type-safe event emitters
+- **`createEventEmitter`**: Create event emitters without payload
 
-### Key Differences from RxJS
+### Observable APIs
 
-- **Focus on State Management**: Designed specifically for state management, not just asynchronous event processing
-- **InitializedObservable**: Provides `InitializedObservable` which always holds an initial value, making it ideal for representing state
-- **Simpler API**: Most use cases are covered by `createState`, `createReducer`, and `createEventEmitter`
-- **Better Readability**: No need for complex operator chains in everyday code
-- **Optional Complexity**: Advanced features available to manipulate Observables when needed
+For complex scenarios, SynState provides observable-based APIs:
 
-### Use Cases
+#### Creation Functions
 
-**Use SynState when you need:**
+- `source<T>()`: Create a new observable source (Almost equivalent to RxJS `subject`)
+- `fromPromise(promise)`: Create observable from promise
+- `fromSubscribable()`: Create observable from any subscribable object
+- `counter(ms)`: Emit values at intervals (Almost equivalent to RxJS `interval`)
+- `timer(delay)`: Emit after delay
 
-- ✅ Global state management across components
-- ✅ Event-driven communication between components
-- ✅ Type-safe event emitters
-- ✅ Redux-like state with reducers
-- ✅ Simple reactive patterns (debounce, throttle, etc.)
+#### Operators
+
+- `map` variants
+    - `map(fn)`: Transform values
+    - `mapTo(value)`: Map all values to a constant
+    - `getKey(key)`: Extract property value from objects (alias: `pluck`)
+    - `attachIndex()`: Attach index to each value (alias: `withIndex`)
+    - Result/Optional
+        - `mapOptional(fn)`: Map over Optional values
+        - `mapResultOk(fn)`: Map over Result ok values
+        - `mapResultErr(fn)`: Map over Result error values
+        - `unwrapOptional()`: Unwrap Optional values to undefined
+        - `unwrapResultOk()`: Unwrap Result ok values to undefined
+        - `unwrapResultErr()`: Unwrap Result error values to undefined
+    - `mergeMap(fn)`: Map to observables and merge all (runs in parallel) (alias: `flatMap`)
+    - `switchMap(fn)`: Map to observables and switch to latest (cancels previous)
+- Filtering
+    - `filter(predicate)`: Filter values
+    - `skipIfNoChange()`: Skip duplicate values (alias: `distinctUntilChanged`)
+    - `skip(n)`: Skip first n emissions
+    - `take(n)`: Take first n emissions then complete
+    - `skipWhile(predicate)`: Skip values while predicate is true
+    - `takeWhile(predicate)`: Emit values while predicate is true, then complete
+    - `skipUntil(notifier)`: Skip values until notifier emits
+    - `takeUntil(notifier)`: Complete on notifier emission
+- Time series processing
+    - `audit(ms)`: Emit the last value after specified time window (Almost equivalent to RxJS `auditTime`)
+    - `debounce(ms)`: Debounce emissions (Almost equivalent to RxJS `debounceTime`)
+    - `throttle(ms)`: Throttle emissions (Almost equivalent to RxJS `throttleTime`)
+- Others
+    - `pairwise()`: Emit previous and current values as pairs
+    - `scan(reducer, seed)`: Accumulate values
+    - `withBuffered(observable)`: Buffer values from observable and emit with parent (alias: `withBufferedFrom`)
+    - `withCurrentValueFrom(observable)`: Sample current value from another observable (alias: `withLatestFrom`)
+    - `withInitialValue(value)`: Provide an initial value for uninitialized observable
+
+#### Combination
+
+- `combine(observables)`: Combine latest values from multiple sources (alias: `combineLatest`)
+- `merge(observables)`: Merge multiple streams
+- `zip(observables)`: Pair values by index
 
-**Consider other solutions when:**
+#### Utilities
 
-- ❌ You need state in a React component (use React hooks `useState`, `useReducer`)
-- ❌ Your app is simple enough for React Context alone
+- `isChildObservable(obs)`: Check if observable is a child observable
+- `isManagerObservable(obs)`: Check if observable is a manager observable
+- `isRootObservable(obs)`: Check if observable is a root observable
 
 ## Type Safety
 

package/dist/core/class/child-observable-class.d.mts

@@ -1,3 +1,5 @@
+import { type Some } from 'ts-data-forge';
+import { type MutableSet } from 'ts-type-forge';
 import { type AsyncChildObservable, type ChildObservable, type InitializedObservable, type InitializedSyncChildObservable, type KeepInitialValueOperator, type NonEmptyUnknownList, type Observable, type ObservableId, type Operator, type SyncChildObservable, type WithInitialValueOperator, type Wrap } from '../types/index.mjs';
 import { ObservableBaseClass } from './observable-base-class.mjs';
 export declare class AsyncChildObservableClass<A, const P extends NonEmptyUnknownList> extends ObservableBaseClass<A, 'async child', number> implements AsyncChildObservable<A, P> {

package/dist/core/class/child-observable-class.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"child-observable-class.d.mts","sourceRoot":"","sources":["../../../src/core/class/child-observable-class.mts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,8BAA8B,EACnC,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,IAAI,EACV,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAwDlE,qBAAa,yBAAyB,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,SAAS,mBAAmB,CAC3E,SAAQ,mBAAmB,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,CACpD,YAAW,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC;;IAErC,QAAQ,CAAC,OAAO,sDAAC;IAEjB,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;gBAElD,EACV,OAAO,EACP,KAA6B,EAC7B,YAAY,GACb,EAAE,QAAQ,CAAC;QACV,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,UAAU,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;KAClE,CAAC;IAiBF,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,IAAI;IAajD,WAAW,CAAC,SAAS,EAAE,CAAC,GAAG,IAAI;IAUtB,QAAQ,IAAI,IAAI;IAShB,WAAW,IAAI,IAAI;CAU7B;AAED,qBAAa,wBAAwB,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,SAAS,mBAAmB,CAC1E,SAAQ,mBAAmB,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CACnD,YAAW,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC;IAEpC,QAAQ,CAAC,OAAO,sDAAC;gBAEL,EACV,OAAO,EACP,KAA6B,EAC7B,YAAY,GACb,EAAE,QAAQ,CAAC;QACV,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;KACjE,CAAC;IAYO,QAAQ,IAAI,IAAI;IAQhB,WAAW,IAAI,IAAI;CAU7B;AAED,qBAAa,mCAAmC,CAC9C,CAAC,EACD,KAAK,CAAC,CAAC,SAAS,mBAAmB,CAEnC,SAAQ,wBAAwB,CAAC,CAAC,EAAE,CAAC,CACrC,YAAW,8BAA8B,CAAC,CAAC,EAAE,CAAC,CAAC;gBAEnC,EACV,OAAO,EACP,KAA6B,EAC7B,YAAY,GACb,EAAE,QAAQ,CAAC;QACV,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,UAAU,CAAC,8BAA8B,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;KAC5E,CAAC;IAIO,WAAW,IAAI,IAAI,CAAC,CAAC,CAAC;IAKtB,IAAI,CAAC,CAAC,EACb,QAAQ,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,GACxE,qBAAqB,CAAC,CAAC,CAAC;IAElB,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;CAO1D"}
+{"version":3,"file":"child-observable-class.d.mts","sourceRoot":"","sources":["../../../src/core/class/child-observable-class.mts"],"names":[],"mappings":"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"}

package/dist/core/class/child-observable-class.mjs

@@ -1,11 +1,44 @@
 import { Arr } from 'ts-data-forge';
-import { isManagerObservable } from '../types/observable.mjs';
-import { issueUpdaterSymbol } from '../utils/id-maker.mjs';
+import { isManagerObservable, isChildObservable } from '../types/observable.mjs';
+import { issueUpdateToken } from '../utils/id-maker.mjs';
 import { maxDepth } from '../utils/max-depth.mjs';
 import { binarySearch } from '../utils/utils.mjs';
 import { ObservableBaseClass } from './observable-base-class.mjs';
 
+/**
+ * Detects circular dependencies by walking the full ancestor chain of the
+ * given parents and checking whether `child` already appears among them.
+ *
+ * @throws {Error} if a circular dependency is detected
+ */
+const hasCircularDependencyFrom = (node, mut_visited, mut_inPath) => {
+    if (mut_inPath.has(node.id))
+        return true;
+    if (mut_visited.has(node.id))
+        return false;
+    mut_visited.add(node.id);
+    mut_inPath.add(node.id);
+    if (isChildObservable(node)) {
+        for (const parent of node.parents) {
+            if (hasCircularDependencyFrom(parent, mut_visited, mut_inPath)) {
+                return true;
+            }
+        }
+    }
+    mut_inPath.delete(node.id);
+    return false;
+};
+const detectCircularDependency = (child, parents) => {
+    const mut_visited = new Set();
+    const mut_inPath = new Set([child.id]);
+    for (const parent of parents) {
+        if (hasCircularDependencyFrom(parent, mut_visited, mut_inPath)) {
+            throw new Error('Circular dependency detected in observable graph: a child observable cannot be its own ancestor.');
+        }
+    }
+};
 const registerChild = (child, parents) => {
+    detectCircularDependency(child, parents);
     for (const p of parents) {
         p.addChild(child);
     }
@@ -41,7 +74,7 @@ const tryComplete = ({ hasSubscriber, hasActiveChild, parents, complete, }) => {
 };
 class AsyncChildObservableClass extends ObservableBaseClass {
     parents;
-    #mut_procedure;
+    #mut_propagationOrder;
     descendantsIdSet;
     constructor({ parents, depth = 1 + maxDepth(parents), initialValue, }) {
         super({
@@ -50,7 +83,7 @@ class AsyncChildObservableClass extends ObservableBaseClass {
             initialValue,
         });
         this.parents = parents;
-        this.#mut_procedure = [];
+        this.#mut_propagationOrder = [];
         this.descendantsIdSet = new Set();
         registerChild(this, parents);
     }
@@ -59,14 +92,14 @@ class AsyncChildObservableClass extends ObservableBaseClass {
         if (this.descendantsIdSet.has(child.id))
             return;
         this.descendantsIdSet.add(child.id);
-        const insertPos = binarySearch(this.#mut_procedure.map((a) => a.depth), child.depth);
-        this.#mut_procedure = Arr.toInserted(this.#mut_procedure, insertPos, child);
+        const insertPos = binarySearch(this.#mut_propagationOrder.map((a) => a.depth), child.depth);
+        this.#mut_propagationOrder = Arr.toInserted(this.#mut_propagationOrder, insertPos, child);
     }
     startUpdate(nextValue) {
-        const updaterSymbol = issueUpdaterSymbol();
-        this.setNext(nextValue, updaterSymbol);
-        for (const p of this.#mut_procedure) {
-            p.tryUpdate(updaterSymbol);
+        const updateToken = issueUpdateToken();
+        this.setNext(nextValue, updateToken);
+        for (const p of this.#mut_propagationOrder) {
+            p.tryUpdate(updateToken);
         }
     }
     complete() {
@@ -124,9 +157,7 @@ class InitializedSyncChildObservableClass extends SyncChildObservableClass {
         return super.getCurrentValue();
     }
     pipe(operator) {
-        return operator(
-        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-        this);
+        return operator(this);
     }
 }