synstate 3.4.0 → 4.1.0

package/README.md

@@ -24,7 +24,7 @@
 - 🎯 **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 -->~5.5 kB min+gzip<!-- /bundle-size:synstate --> with two external runtime dependencies ([ts-data-forge](https://www.npmjs.com/package/ts-data-forge) and [ts-std-forge](https://www.npmjs.com/package/ts-std-forge), and the first depends on the second)
+- 🚀 **Lightweight**: <!-- bundle-size:synstate -->~6.1 kB min+gzip<!-- /bundle-size:synstate --> with two external runtime dependencies ([ts-data-forge](https://www.npmjs.com/package/ts-data-forge) and [ts-std-forge](https://www.npmjs.com/package/ts-std-forge), and the first depends on the second)
 - 🌐 **Framework Agnostic**: Works with React, Vue, Svelte, or vanilla JavaScript
 - 🔄 **Reactive Updates**: Automatic propagation of state changes to all subscribers
 - 📡 **Event System**: Built-in `createValueEmitter`, `createEventEmitter` for event-driven architecture
@@ -282,7 +282,7 @@ assert.deepStrictEqual(stateHistory, [0, 1, 3, 0]);
 
 ### Skipping Updates Equal to the Current State (`equals`)
 
-`createState`, `createReducer` and `createBooleanState` take an `equals` option. When it says the next state is the same as the current one, the update is not passed on: no subscriber, and nothing derived from the state, is told of it, and the current state is kept. Decide this where the state is held rather than downstream with `skipIfNoChange`, because an update passed on reaches whatever reads the state directly before any operator can thin it out.
+`createState`, `createReducer` and `createBooleanState` take an `equals` option, `Object.is` by default. When it says the next state is the same as the current one, the update is not passed on: no subscriber, and nothing derived from the state, is told of it, and the current state is kept. Decide this where the state is held rather than downstream with `skipIfNoChange`, because an update passed on reaches whatever reads the state directly before any operator can thin it out.
 
 ```tsx
 const [filters, setFilters] = createState(
@@ -312,13 +312,13 @@ setFilters({ label: 'bug', page: 2 });
 assert.deepStrictEqual(queryHistory, ['label:bug page:1', 'label:bug page:2']);
 ```
 
-The same option is the third argument of `createReducer`:
+The same option is the third argument of `createReducer`. Pass `equals: () => false` to pass on every update, equal or not:
 
 ```tsx
 const [count, dispatch] = createReducer(
     (s, action: Readonly<{ type: 'add'; amount: number }>) => s + action.amount,
     0,
-    { equals: Object.is },
+    { equals: () => false },
 );
 
 const countHistory: number[] = [];
@@ -327,15 +327,13 @@ count.subscribe((value: number) => {
     countHistory.push(value);
 });
 
-dispatch({ type: 'add', amount: 0 }); // 0 again: nothing is passed on
+dispatch({ type: 'add', amount: 0 }); // 0 again, passed on all the same
 
 dispatch({ type: 'add', amount: 2 });
 
-assert.deepStrictEqual(countHistory, [0, 2]);
+assert.deepStrictEqual(countHistory, [0, 0, 2]);
 ```
 
-When `equals` is omitted, every update is passed on, equal or not. The next major version will make `Object.is` the default; pass `equals: () => false` to keep passing on every update.
-
 ### Global Counter State (React)
 
 ```tsx
@@ -709,6 +707,13 @@ For complex scenarios, SynState provides observable-based APIs:
 - `merge(observables)`: Merge multiple streams
 - `zip(observables)`: Pair values by index
 
+#### Scopes (for library authors)
+
+- `createScope(parent?)`: Create a scope; observables created synchronously inside `scope.run(body)` belong to it and are disposed by `scope.dispose()`
+- `getCurrentScope()`: The scope whose `run` is executing, if any
+- `onScopeDispose(cleanup)`: Call `cleanup` when the current scope is disposed
+- `untracked(body)`: Call `body` with no current scope
+
 #### Utilities
 
 - `isChildObservable(obs)`: Check if observable is a child observable

package/dist/core/authoring.d.mts

@@ -0,0 +1,7 @@
+/**
+ * What custom creators and operators are written with: the factories every
+ * built-in observable is made by (#2117). The rest of `core/base` stays
+ * internal.
+ */
+export { createAsyncChildObservable, createInitializedSyncChildObservable, createRootObservable, createSyncChildObservable, type AsyncChildObservableHooks, type AsyncChildObservableTools, type ChildObservableConfig, type InitializedChildObservableConfig, type RootObservableConfig, type RootObservableTools, type SyncChildObservableHooks, type SyncChildObservableTools, } from './class/index.mjs';
+//# sourceMappingURL=authoring.d.mts.map

package/dist/core/authoring.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring.d.mts","sourceRoot":"","sources":["../../src/core/authoring.mts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,0BAA0B,EAC1B,oCAAoC,EACpC,oBAAoB,EACpB,yBAAyB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,gCAAgC,EACrC,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC"}

package/dist/core/authoring.mjs

@@ -0,0 +1,7 @@
+
+
+
+
+
+export { createAsyncChildObservable, createInitializedSyncChildObservable, createRootObservable, createSyncChildObservable, } from './class/index.mjs';
+//# sourceMappingURL=authoring.mjs.map

package/dist/core/authoring.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring.mjs","sourceRoot":"","sources":["../../src/core/authoring.mts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,0BAA0B,EAC1B,oCAAoC,EACpC,oBAAoB,EACpB,yBAAyB,GAS1B,MAAM,mBAAmB,CAAC"}

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

@@ -0,0 +1,93 @@
+import { type Optional, type Some } from 'ts-data-forge';
+import type { AsyncChildObservable, DropInitialValueOperator, InitializedObservable, InitializedSyncChildObservable, KeepInitialValueOperator, NonEmptyUnknownList, Observable, SyncChildObservable, WithInitialValueOperator, Wrap } from '../types/index.mjs';
+import { ManagerObservableClass } from './manager-observable-class.mjs';
+import { ObservableBaseClass } from './observable-base-class.mjs';
+import { type ManagerNode } from './observable-node.mjs';
+type ChildObservableConfig<A, P extends NonEmptyUnknownList> = Readonly<{
+    parents: Wrap<P>;
+    /**
+     * Defaults to one more than the deepest parent. An update reaches
+     * observables in ascending depth, so an observable `tryUpdate` reads with
+     * `getSnapshot` without being its child (`withCurrentValueFrom`'s second
+     * source) has to be shallower than this one too, or this one reads its value
+     * from before the update: pass `1 + Math.max(...)` over both then.
+     */
+    depth?: number;
+    initialValue: Optional<A>;
+}>;
+/**
+ * An observable derived from `parents` that emits, if at all, in the same
+ * update as they do (`map`, `filter`, `combine`, …).
+ *
+ * A subclass overrides `tryUpdate`, and, when it holds something to
+ * release, `teardown`; its constructor ends with `this.attach()`, once
+ * everything `tryUpdate` and `teardown` read is in place.
+ */
+export declare class SyncChildObservableClass<A, const P extends NonEmptyUnknownList> extends ObservableBaseClass<A, 'sync child', number> implements SyncChildObservable<A, P> {
+    #private;
+    readonly parents: Wrap<P>;
+    readonly managers: readonly ManagerNode[];
+    constructor({ parents, depth, initialValue, }: ChildObservableConfig<A, P>);
+    /**
+     * Joins the current scope and registers this observable to its parents
+     * and the managers it is reached from. Completed parents never update
+     * again, so a child created under them is complete from the start
+     * (#2248), as is one its constructor completed; registering it would only
+     * leave a reference in each parent.
+     */
+    protected attach(): void;
+    protected detach(): void;
+    tryComplete(): void;
+    /**
+     * Whether this observable can emit nothing more although some parent is
+     * still live, asked whenever a parent completes. `true` completes it then,
+     * as all parents completing does (`zip` once a completed source's queue is
+     * empty).
+     */
+    canEmitNoMore(): boolean;
+    /**
+     * Completes this observable once the update now propagating has reached
+     * every descendant, so that they see the value just passed on first.
+     */
+    protected completeAfterPropagation(): void;
+}
+/**
+ * An observable derived from `parents` that may emit later, in an update of
+ * its own, through `startUpdate` (`debounce`, `switchMap`). It may also emit
+ * synchronously with `setNext`, as a sync child does. A subclass may also
+ * override `flush`, to pass on at completion what it still holds.
+ */
+export declare class AsyncChildObservableClass<A, const P extends NonEmptyUnknownList> extends ManagerObservableClass<A, 'async child', number> implements AsyncChildObservable<A, P> {
+    #private;
+    readonly parents: Wrap<P>;
+    constructor({ parents, depth, initialValue, }: ChildObservableConfig<A, P>);
+    /** See `SyncChildObservableClass.attach`. */
+    protected attach(): void;
+    protected detach(): void;
+    tryComplete(): void;
+    /** See `SyncChildObservableClass.canEmitNoMore`. */
+    canEmitNoMore(): boolean;
+    /** See `SyncChildObservableClass.completeAfterPropagation`. */
+    protected completeAfterPropagation(): void;
+}
+/**
+ * A sync child that always holds a value: a subclass passes a `Some` as its
+ * `initialValue`. It differs from its base only in the types of
+ * `getSnapshot` and `pipe`.
+ */
+export declare class InitializedSyncChildObservableClass<A, const P extends NonEmptyUnknownList> extends SyncChildObservableClass<A, P> implements InitializedSyncChildObservable<A, P> {
+    getSnapshot(): Some<A>;
+    pipe<B>(operator: KeepInitialValueOperator<A, B> | WithInitialValueOperator<A, B>): InitializedObservable<B>;
+    pipe<B>(operator: DropInitialValueOperator<A, B>): Observable<B>;
+}
+/**
+ * Whether {@link registerChild} checks for a circular dependency: everywhere
+ * but in a process whose `NODE_ENV` is `production`. A child's parents exist
+ * before it and cannot be changed afterwards, so only code that rewrites an
+ * observable's readonly `parents` can make a cycle, while the walk over every
+ * ancestor is paid on every creation. Where there is no `process` (a browser
+ * bundle) the check is off.
+ */
+export declare const checksCircularDependency: boolean;
+export {};
+//# sourceMappingURL=child-observable-class.d.mts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,248 @@
+
+
+
+
+import { Arr, hasKey, isRecord } from 'ts-data-forge';
+import { panic } from 'ts-std-forge';
+import { maxDepth } from '../utils/index.mjs';
+import { ManagerObservableClass } from './manager-observable-class.mjs';
+import { ObservableBaseClass } from './observable-base-class.mjs';
+import { toNode, } from './observable-node.mjs';
+import { runAfterPropagation } from './propagation-state.mjs';
+
+
+
+
+
+
+
+
+export class SyncChildObservableClass extends ObservableBaseClass {
+    #mut_isAttached;
+    parents;
+    managers;
+    constructor({ parents, depth = 1 + maxDepth(parents), initialValue, }) {
+        super({
+            kind: 'sync child',
+            depth,
+            initialValue,
+        });
+        this.parents = parents;
+        this.managers = managersOf(parents);
+        this.#mut_isAttached = false;
+    }
+
+
+
+
+
+
+
+    attach() {
+        this.adoptIntoCurrentScope();
+        if (this.isCompleted || this.parents.every((p) => p.isCompleted)) {
+            this.complete();
+        }
+        else {
+            registerChild(this, this.managers);
+            this.#mut_isAttached = true;
+        }
+    }
+    detach() {
+        if (!this.#mut_isAttached) {
+            return;
+        }
+        this.#mut_isAttached = false;
+        unregisterChild(this, this.managers);
+    }
+    tryComplete() {
+        if (shouldComplete(this)) {
+            this.complete();
+        }
+    }
+
+
+
+
+
+
+
+    canEmitNoMore() {
+        return false;
+    }
+
+
+
+
+    completeAfterPropagation() {
+        runAfterPropagation(() => {
+            this.complete();
+        });
+    }
+}
+
+
+
+
+
+
+export class AsyncChildObservableClass extends ManagerObservableClass {
+    #mut_isAttached;
+    parents;
+    constructor({ parents, depth = 1 + maxDepth(parents), initialValue, }) {
+        super({
+            kind: 'async child',
+            depth,
+            initialValue,
+        });
+        this.parents = parents;
+        this.#mut_isAttached = false;
+    }
+
+    attach() {
+        this.adoptIntoCurrentScope();
+        if (this.isCompleted || this.parents.every((p) => p.isCompleted)) {
+            this.complete();
+        }
+        else {
+            registerChild(this, managersOf(this.parents));
+            this.#mut_isAttached = true;
+        }
+    }
+    detach() {
+        if (!this.#mut_isAttached) {
+            return;
+        }
+        this.#mut_isAttached = false;
+        unregisterChild(this, managersOf(this.parents));
+    }
+    tryComplete() {
+        if (shouldComplete(this)) {
+            this.complete();
+        }
+    }
+
+
+    canEmitNoMore() {
+        return false;
+    }
+
+    completeAfterPropagation() {
+        runAfterPropagation(() => {
+            this.complete();
+        });
+    }
+}
+
+
+
+
+
+export class InitializedSyncChildObservableClass extends SyncChildObservableClass {
+    getSnapshot() {
+
+
+        return super.getSnapshot();
+    }
+    pipe(operator) {
+        return operator(this);
+    }
+}
+
+
+
+
+
+const shouldComplete = (child) => !child.isCompleted &&
+    (child.parents.every((p) => p.isCompleted) || child.canEmitNoMore());
+
+const registerChild = (child, managers) => {
+    if (checksCircularDependency) {
+        detectCircularDependency(child);
+    }
+    for (const p of child.parents) {
+        toNode(p).addChild(child);
+    }
+    for (const m of managers) {
+        m.addDescendant(child);
+    }
+};
+
+
+
+
+
+
+const unregisterChild = (child, managers) => {
+    for (const p of child.parents) {
+        toNode(p).deleteChild(child);
+    }
+    for (const m of managers) {
+        m.deleteDescendant(child);
+    }
+};
+
+
+
+
+const managersOf = (parents) => Arr.isFixedLengthArray(1, parents)
+    ? toNode(parents[0]).managers
+    : Array.from(new Set(parents.flatMap((p) => toNode(p).managers)));
+const isDevelopmentProcess = () => {
+    const proc = Reflect.get(globalThis, 'process');
+    return (isRecord(proc) &&
+        hasKey(proc, 'env') &&
+        isRecord(proc.env) &&
+        (!hasKey(proc.env, 'NODE_ENV') || proc.env.NODE_ENV !== 'production'));
+};
+
+
+
+
+
+
+
+
+export const checksCircularDependency = isDevelopmentProcess();
+
+
+
+
+
+
+const detectCircularDependency = (child) => {
+    const mut_visited = new Set();
+    const mut_inPath = new Set([
+
+        child,
+    ]);
+    for (const parent of child.parents) {
+        if (hasCircularDependencyFrom(parent, mut_visited, mut_inPath)) {
+
+
+
+
+            panic('Circular dependency detected in observable graph: a child observable cannot be its own ancestor.');
+        }
+    }
+};
+const hasCircularDependencyFrom = (node, mut_visited, mut_inPath) => {
+    if (mut_inPath.has(node)) {
+        return true;
+    }
+    if (mut_visited.has(node)) {
+        return false;
+    }
+    mut_visited.add(node);
+    mut_inPath.add(node);
+    if (node.kind !== 'root') {
+        for (const parent of node.parents) {
+            if (hasCircularDependencyFrom(parent, mut_visited, mut_inPath)) {
+                return true;
+            }
+        }
+    }
+    mut_inPath.delete(node);
+    return false;
+};
+//# sourceMappingURL=child-observable-class.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"child-observable-class.mjs","sourceRoot":"","sources":["../../../src/core/class/child-observable-class.mts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,159 @@
+import { type Optional, type Some } from 'ts-data-forge';
+import type { AsyncChildObservable, InitializedSyncChildObservable, NonEmptyUnknownList, SyncChildObservable, UpdateToken, Wrap } from '../types/index.mjs';
+/**
+ * The tools a sync-child factory (`map`, `filter`, `zip`, …) receives: what
+ * only the observable being created may do to itself.
+ */
+export type SyncChildObservableTools<A> = Readonly<{
+    /** Emits `nextValue` under `updateToken` and notifies subscribers. */
+    setNext: (nextValue: A, updateToken: UpdateToken) => void;
+    getSnapshot: () => Optional<A>;
+    /** Completes this observable (leaf teardown included). */
+    complete: () => void;
+    /**
+     * Completes this observable once the update now propagating has reached
+     * every descendant, so that they see the value just passed on first.
+     */
+    completeAfterPropagation: () => void;
+    /**
+     * Registers a teardown (clear timers, unsubscribe inner observables, …) to
+     * run when this observable completes or is disposed, in the order
+     * registered. Called from `init`, it lets the teardown close over what
+     * `init` creates. Registered once the observable has completed, the
+     * teardown runs at once.
+     */
+    onComplete: (teardown: () => void) => void;
+}>;
+/**
+ * The tools an async-child factory (`debounce`, `switchMap`, …) receives.
+ * Async children additionally start their own update propagation.
+ */
+export type AsyncChildObservableTools<A> = Readonly<{
+    /** Emits `nextValue` and propagates the update to all descendants. */
+    startUpdate: (nextValue: A) => void;
+}> & SyncChildObservableTools<A>;
+/**
+ * What a sync child's `init` may return instead of `tryUpdate` alone: the
+ * hooks the factory calls, which read the state `init` creates.
+ */
+export type SyncChildObservableHooks = Readonly<{
+    /** Called with the token of every update that reaches this observable. */
+    tryUpdate: (updateToken: UpdateToken) => void;
+    /**
+     * Whether this observable can emit nothing more although some parent is
+     * still live, asked whenever a parent completes. `true` completes it then,
+     * as all parents completing does (`zip` once a completed source's queue is
+     * empty).
+     */
+    canEmitNoMore?: () => boolean;
+}>;
+/**
+ * What an async child's `init` may return instead of `tryUpdate` alone. An
+ * async child can also hold a value it has not passed on yet (`debounce`'s
+ * pending value), which completing should not lose.
+ */
+export type AsyncChildObservableHooks = SyncChildObservableHooks & Readonly<{
+    /**
+     * Run at the beginning of `complete()`, before the teardowns, and never
+     * by `dispose()`: passes on what this observable still holds through
+     * `startUpdate`, so that its subscribers see it before they see the
+     * completion. A disposed observable has no one left to tell.
+     */
+    flush?: () => void;
+}>;
+type ChildObservableConfigBase<P extends NonEmptyUnknownList> = Readonly<{
+    parents: Wrap<P>;
+    /**
+     * Defaults to one more than the deepest parent. An update reaches
+     * observables in ascending depth, so an observable `tryUpdate` reads with
+     * `getSnapshot` without being its child (`withCurrentValueFrom`'s second
+     * source) has to be shallower than this one too, or this one reads its value
+     * from before the update: pass `1 + Math.max(...)` over both then.
+     */
+    depth?: number;
+}>;
+export type ChildObservableConfig<A, P extends NonEmptyUnknownList> = ChildObservableConfigBase<P> & Readonly<{
+    initialValue: Optional<A>;
+}>;
+export type InitializedChildObservableConfig<A, P extends NonEmptyUnknownList> = ChildObservableConfigBase<P> & Readonly<{
+    initialValue: Some<A>;
+}>;
+/**
+ * Creates a sync-child observable: one derived from `parents` that emits, if
+ * at all, in the same update as they do. `map`, `filter`, `combine` and the
+ * other synchronous operators are built with it.
+ *
+ * `init` runs during construction and receives the tools. It returns
+ * `tryUpdate`, which is called with the token of every update that reaches
+ * this observable — a parent that did not emit in that update has a different
+ * `updateToken`; to emit, call `setNext` with the token received — or an
+ * object holding `tryUpdate` and the other hooks
+ * ({@link SyncChildObservableHooks}). State the hooks share can live inside
+ * `init`, next to the teardown it registers with the `onComplete` tool.
+ * `init` may complete the observable; it is then never registered to its
+ * parents.
+ *
+ * @example
+ *
+ * ```ts
+ * // A custom operator, written as `map((x) => x * 2)` is.
+ * const double = (src: Observable<number>): Observable<number> =>
+ *   createSyncChildObservable(
+ *     { parents: [src], initialValue: Optional.none },
+ *     ({ setNext }) =>
+ *       (updateToken) => {
+ *         const sn = src.getSnapshot();
+ *
+ *         if (src.updateToken !== updateToken || Optional.isNone(sn)) {
+ *           return; // `src` did not emit in this update
+ *         }
+ *
+ *         setNext(sn.value * 2, updateToken);
+ *       },
+ *   );
+ *
+ * const num$ = source<number>();
+ *
+ * const pair$ = combine([num$, double(num$)]);
+ *
+ * const valueHistory: FixedLengthTuple<2, number>[] = [];
+ *
+ * pair$.subscribe((pair) => {
+ *   valueHistory.push(pair);
+ * });
+ *
+ * num$.next(1);
+ *
+ * num$.next(2);
+ *
+ * // `double` joins the same update as `num$`, so `combine` sees no [2, 2].
+ * assert.deepStrictEqual(valueHistory, [
+ *   [1, 2],
+ *   [2, 4],
+ * ]);
+ * ```
+ */
+export declare const createSyncChildObservable: <A, P extends NonEmptyUnknownList>(config: ChildObservableConfig<A, P>, init: (tools: SyncChildObservableTools<A>) => ((updateToken: UpdateToken) => void) | SyncChildObservableHooks) => SyncChildObservable<A, P>;
+/**
+ * Creates a sync-child observable that always holds a value.
+ *
+ * Runtime-wise this is exactly `createSyncChildObservable`; only the types of
+ * `getSnapshot` and `pipe` are narrowed.
+ */
+export declare const createInitializedSyncChildObservable: <A, P extends NonEmptyUnknownList>(config: InitializedChildObservableConfig<A, P>, init: (tools: SyncChildObservableTools<A>) => ((updateToken: UpdateToken) => void) | SyncChildObservableHooks) => InitializedSyncChildObservable<A, P>;
+/**
+ * Creates an async-child observable: one derived from `parents` that may emit
+ * later, in an update of its own, through `startUpdate` (`debounce`,
+ * `switchMap`). It may also emit synchronously with `setNext`, as a sync child
+ * does. See {@link createSyncChildObservable} for the `init` contract; an
+ * async child's `init` may also return a `flush` hook
+ * ({@link AsyncChildObservableHooks}).
+ */
+export declare const createAsyncChildObservable: <A, P extends NonEmptyUnknownList>(config: ChildObservableConfig<A, P>, init: (tools: AsyncChildObservableTools<A>) => ((updateToken: UpdateToken) => void) | AsyncChildObservableHooks) => AsyncChildObservable<A, P>;
+/**
+ * An `init` for a child that never receives a parent update; reaching its
+ * `tryUpdate` is the invariant breaking (Sumi D-48).
+ */
+export declare const createTryUpdateNotImplemented: () => ((updateToken: UpdateToken) => void);
+export {};
+//# sourceMappingURL=create-child-observable.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-child-observable.d.mts","sourceRoot":"","sources":["../../../src/core/class/create-child-observable.mts"],"names":[],"mappings":"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"}