@signaltree/core 9.2.2 → 9.5.0

package/README.md

@@ -305,7 +305,7 @@ console.log(tree.$.message()); // 'Hello World'
 //   tree.$.message.set('Updated!');
 //   tree.$.count.update((n) => n + 1);
 // See: https://github.com/JBorgia/signaltree/blob/main/packages/callable-syntax/README.md
-tree.$.count(5);          // requires @signaltree/callable-syntax transform
+tree.$.count(5); // requires @signaltree/callable-syntax transform
 tree.$.message('Updated!'); // requires @signaltree/callable-syntax transform
 
 // Use in an Angular component
@@ -343,6 +343,10 @@ const tree = signalTree({
 });
 
 // Access nested signals with full type safety
+// Requires @signaltree/callable-syntax. Without the transform, use:
+// tree.$.user.name.set('Jane Doe');
+// tree.$.user.preferences.theme.set('light');
+// tree.$.ui.loading.set(true);
 tree.$.user.name('Jane Doe');
 tree.$.user.preferences.theme('light');
 tree.$.ui.loading(true);
@@ -500,6 +504,8 @@ const tree = signalTree<AppState>({
 });
 
 // Complex updates with type safety
+// Requires @signaltree/callable-syntax. Without the transform, use
+// tree.set((state) => ({ ... })) or leaf .set() / .update() calls instead.
 tree((state) => ({
   auth: {
     ...state.auth,
@@ -671,16 +677,15 @@ All enhancers are exported directly from `@signaltree/core`:
 ```typescript
 import { signalTree, effects } from '@signaltree/core';
 
-const tree = signalTree({ count: 0, user: { name: 'Alice' } })
-  .with(effects());
+const tree = signalTree({ count: 0, user: { name: 'Alice' } }).with(effects());
 
 // Subscribe with automatic cleanup on destroy
-const unsub = tree.subscribe(state => {
+const unsub = tree.subscribe((state) => {
   console.log('State changed:', state.count);
 });
 
 // Effect with cleanup callback
-const cleanup = tree.effect(state => {
+const cleanup = tree.effect((state) => {
   console.log('Count:', state.count);
   return () => console.log('Previous effect cleaned up');
 });
@@ -708,7 +713,7 @@ import { signalTree, batching, devTools } from '@signaltree/core';
 
 // Apply enhancers by chaining — each .with() takes a single enhancer
 const tree = signalTree({ count: 0 })
-  .with(batching())  // Performance optimization
+  .with(batching()) // Performance optimization
   .with(devTools()); // Development tools
 ```
 
@@ -721,8 +726,7 @@ import { signalTree, batching } from '@signaltree/core';
 const tree = signalTree({
   products: entityMap<Product>(),
   ui: { loading: false },
-})
-  .with(batching()); // Batch updates for optimal rendering
+}).with(batching()); // Batch updates for optimal rendering
 
 // Entity CRUD operations
 tree.$.products.addOne(newProduct);
@@ -741,11 +745,14 @@ const tree = signalTree({
   user: null as User | null,
   preferences: { theme: 'light' },
 })
-  .with(serialization({  // Auto-save to localStorage
-    autoSave: true,
-    storage: 'localStorage',
-  }))
-  .with(timeTravel());   // Undo/redo support
+  .with(
+    serialization({
+      // Auto-save to localStorage
+      autoSave: true,
+      storage: 'localStorage',
+    })
+  )
+  .with(timeTravel()); // Undo/redo support
 
 // For async operations, use manual async or async helpers
 async function fetchUser(id: string) {
@@ -776,8 +783,8 @@ Enhancers can declare metadata for automatic dependency resolution:
 ```typescript
 // Chain enhancers — each .with() takes a single enhancer
 const tree = signalTree(state)
-  .with(batching())   // Requires: core, provides: batching
-  .with(devTools());  // Requires: core, provides: debugging
+  .with(batching()) // Requires: core, provides: batching
+  .with(devTools()); // Requires: core, provides: debugging
 ```
 
 #### Core Stubs
@@ -1159,6 +1166,8 @@ LoadingState.Error; // 'error'
 
 Auto-syncs state to localStorage with versioning and migration support.
 
+> ⚠️ **Read first:** [Persistence and Security](../../docs/guides/persistence-and-security.md) covers the threat model and what `stored()` is — and isn't — appropriate for. Short version: fine for UI prefs, never for tokens, secrets, or PII.
+
 ```typescript
 import { signalTree, stored, createStorageKeys, clearStoragePrefix } from '@signaltree/core';
 
@@ -1653,18 +1662,24 @@ const tree = signalTree({
     data: { users: [], posts: [] },
   },
 })
-  .with(batching())                       // Performance
-  .with(serialization({                   // State persistence
-    autoSave: true,
-    storage: 'localStorage',
-  }))
+  .with(batching()) // Performance
+  .with(
+    serialization({
+      // State persistence
+      autoSave: true,
+      storage: 'localStorage',
+    })
+  )
   .with(timeTravel({ maxHistorySize: 50 })) // Undo/redo
-  .with(devTools({                        // Debug tools (dev only)
-    name: 'MyApp',
-    enableTimeTravel: true,
-    includePaths: ['app.*', 'ui.*'],
-    formatPath: (path) => path.replace(/\.(\d+)/g, '[$1]'),
-  }));
+  .with(
+    devTools({
+      // Debug tools (dev only)
+      name: 'MyApp',
+      enableTimeTravel: true,
+      includePaths: ['app.*', 'ui.*'],
+      formatPath: (path) => path.replace(/\.(\d+)/g, '[$1]'),
+    })
+  );
 
 // Rich feature set available
 async function fetchUser(id: string) {
@@ -2159,7 +2174,7 @@ Consider separate packages when you need:
 
 ### Case Study
 
-Measured from a production Angular mobile application migrating from NgRx Signal Store to SignalTree. Results reflect one team's experience; your mileage will vary depending on app complexity and existing architecture.
+Snapshot from one production Angular mobile app's NgRx Signal Store → SignalTree migration. Original migration measured ~11,700 → ~2,800 lines of state code (~76%) and ~50KB → ~27KB gzipped state bundle (~46%). Both codebases have continued to evolve; re-measuring today the same scope yields a 60–70% reduction depending on definition (apps-only vs apps+libs, narrow vs broad import filter). The directional finding is reproducible — the exact percentages are not. **YMMV** — your migration's reduction depends on app complexity, prior architecture, and how heavily the original code leaned on custom `withX` helpers. The single biggest driver of the savings is cross-cutting concerns (devtools, error banners, telemetry, refresh handling) moving from per-store composition to tree-level enhancers.
 
 | Metric | NgRx | SignalTree | Change |
 | --- | --- | --- | --- |

package/dist/Action.js

@@ -0,0 +1,15 @@
+import { __extends } from 'tslib';
+import { Subscription } from './Subscription.js';
+
+var Action = (function (_super) {
+    __extends(Action, _super);
+    function Action(scheduler, work) {
+        return _super.call(this) || this;
+    }
+    Action.prototype.schedule = function (state, delay) {
+        return this;
+    };
+    return Action;
+}(Subscription));
+
+export { Action };

package/dist/AsyncAction.js

@@ -0,0 +1,91 @@
+import { __extends } from 'tslib';
+import { Action } from './Action.js';
+import { intervalProvider } from './intervalProvider.js';
+import { arrRemove } from './arrRemove.js';
+
+var AsyncAction = (function (_super) {
+    __extends(AsyncAction, _super);
+    function AsyncAction(scheduler, work) {
+        var _this = _super.call(this, scheduler, work) || this;
+        _this.scheduler = scheduler;
+        _this.work = work;
+        _this.pending = false;
+        return _this;
+    }
+    AsyncAction.prototype.schedule = function (state, delay) {
+        var _a;
+        if (delay === void 0) { delay = 0; }
+        if (this.closed) {
+            return this;
+        }
+        this.state = state;
+        var id = this.id;
+        var scheduler = this.scheduler;
+        if (id != null) {
+            this.id = this.recycleAsyncId(scheduler, id, delay);
+        }
+        this.pending = true;
+        this.delay = delay;
+        this.id = (_a = this.id) !== null && _a !== void 0 ? _a : this.requestAsyncId(scheduler, this.id, delay);
+        return this;
+    };
+    AsyncAction.prototype.requestAsyncId = function (scheduler, _id, delay) {
+        if (delay === void 0) { delay = 0; }
+        return intervalProvider.setInterval(scheduler.flush.bind(scheduler, this), delay);
+    };
+    AsyncAction.prototype.recycleAsyncId = function (_scheduler, id, delay) {
+        if (delay === void 0) { delay = 0; }
+        if (delay != null && this.delay === delay && this.pending === false) {
+            return id;
+        }
+        if (id != null) {
+            intervalProvider.clearInterval(id);
+        }
+        return undefined;
+    };
+    AsyncAction.prototype.execute = function (state, delay) {
+        if (this.closed) {
+            return new Error('executing a cancelled action');
+        }
+        this.pending = false;
+        var error = this._execute(state, delay);
+        if (error) {
+            return error;
+        }
+        else if (this.pending === false && this.id != null) {
+            this.id = this.recycleAsyncId(this.scheduler, this.id, null);
+        }
+    };
+    AsyncAction.prototype._execute = function (state, _delay) {
+        var errored = false;
+        var errorValue;
+        try {
+            this.work(state);
+        }
+        catch (e) {
+            errored = true;
+            errorValue = e ? e : new Error('Scheduled action threw falsy error');
+        }
+        if (errored) {
+            this.unsubscribe();
+            return errorValue;
+        }
+    };
+    AsyncAction.prototype.unsubscribe = function () {
+        if (!this.closed) {
+            var _a = this, id = _a.id, scheduler = _a.scheduler;
+            var actions = scheduler.actions;
+            this.work = this.state = this.scheduler = null;
+            this.pending = false;
+            arrRemove(actions, this);
+            if (id != null) {
+                this.id = this.recycleAsyncId(scheduler, id, null);
+            }
+            this.delay = null;
+            _super.prototype.unsubscribe.call(this);
+        }
+    };
+    return AsyncAction;
+}(Action));
+
+export { AsyncAction };

package/dist/AsyncScheduler.js

@@ -0,0 +1,37 @@
+import { __extends } from 'tslib';
+import { Scheduler } from './Scheduler.js';
+
+var AsyncScheduler = (function (_super) {
+    __extends(AsyncScheduler, _super);
+    function AsyncScheduler(SchedulerAction, now) {
+        if (now === void 0) { now = Scheduler.now; }
+        var _this = _super.call(this, SchedulerAction, now) || this;
+        _this.actions = [];
+        _this._active = false;
+        return _this;
+    }
+    AsyncScheduler.prototype.flush = function (action) {
+        var actions = this.actions;
+        if (this._active) {
+            actions.push(action);
+            return;
+        }
+        var error;
+        this._active = true;
+        do {
+            if ((error = action.execute(action.state, action.delay))) {
+                break;
+            }
+        } while ((action = actions.shift()));
+        this._active = false;
+        if (error) {
+            while ((action = actions.shift())) {
+                action.unsubscribe();
+            }
+            throw error;
+        }
+    };
+    return AsyncScheduler;
+}(Scheduler));
+
+export { AsyncScheduler };

package/dist/ObjectUnsubscribedError.js

@@ -0,0 +1,11 @@
+import { createErrorClass } from './createErrorClass.js';
+
+var ObjectUnsubscribedError = createErrorClass(function (_super) {
+    return function ObjectUnsubscribedErrorImpl() {
+        _super(this);
+        this.name = 'ObjectUnsubscribedError';
+        this.message = 'object unsubscribed';
+    };
+});
+
+export { ObjectUnsubscribedError };

package/dist/Observable.js

@@ -0,0 +1,103 @@
+import { SafeSubscriber, Subscriber } from './Subscriber.js';
+import { isSubscription } from './Subscription.js';
+import { observable } from './observable2.js';
+import { pipeFromArray } from './pipe.js';
+import { config } from './config.js';
+import { isFunction } from './isFunction.js';
+import { errorContext } from './errorContext.js';
+
+var Observable = (function () {
+    function Observable(subscribe) {
+        if (subscribe) {
+            this._subscribe = subscribe;
+        }
+    }
+    Observable.prototype.lift = function (operator) {
+        var observable = new Observable();
+        observable.source = this;
+        observable.operator = operator;
+        return observable;
+    };
+    Observable.prototype.subscribe = function (observerOrNext, error, complete) {
+        var _this = this;
+        var subscriber = isSubscriber(observerOrNext) ? observerOrNext : new SafeSubscriber(observerOrNext, error, complete);
+        errorContext(function () {
+            var _a = _this, operator = _a.operator, source = _a.source;
+            subscriber.add(operator
+                ?
+                    operator.call(subscriber, source)
+                : source
+                    ?
+                        _this._subscribe(subscriber)
+                    :
+                        _this._trySubscribe(subscriber));
+        });
+        return subscriber;
+    };
+    Observable.prototype._trySubscribe = function (sink) {
+        try {
+            return this._subscribe(sink);
+        }
+        catch (err) {
+            sink.error(err);
+        }
+    };
+    Observable.prototype.forEach = function (next, promiseCtor) {
+        var _this = this;
+        promiseCtor = getPromiseCtor(promiseCtor);
+        return new promiseCtor(function (resolve, reject) {
+            var subscriber = new SafeSubscriber({
+                next: function (value) {
+                    try {
+                        next(value);
+                    }
+                    catch (err) {
+                        reject(err);
+                        subscriber.unsubscribe();
+                    }
+                },
+                error: reject,
+                complete: resolve,
+            });
+            _this.subscribe(subscriber);
+        });
+    };
+    Observable.prototype._subscribe = function (subscriber) {
+        var _a;
+        return (_a = this.source) === null || _a === void 0 ? void 0 : _a.subscribe(subscriber);
+    };
+    Observable.prototype[observable] = function () {
+        return this;
+    };
+    Observable.prototype.pipe = function () {
+        var operations = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            operations[_i] = arguments[_i];
+        }
+        return pipeFromArray(operations)(this);
+    };
+    Observable.prototype.toPromise = function (promiseCtor) {
+        var _this = this;
+        promiseCtor = getPromiseCtor(promiseCtor);
+        return new promiseCtor(function (resolve, reject) {
+            var value;
+            _this.subscribe(function (x) { return (value = x); }, function (err) { return reject(err); }, function () { return resolve(value); });
+        });
+    };
+    Observable.create = function (subscribe) {
+        return new Observable(subscribe);
+    };
+    return Observable;
+}());
+function getPromiseCtor(promiseCtor) {
+    var _a;
+    return (_a = promiseCtor !== null && promiseCtor !== void 0 ? promiseCtor : config.Promise) !== null && _a !== void 0 ? _a : Promise;
+}
+function isObserver(value) {
+    return value && isFunction(value.next) && isFunction(value.error) && isFunction(value.complete);
+}
+function isSubscriber(value) {
+    return (value && value instanceof Subscriber) || (isObserver(value) && isSubscription(value));
+}
+
+export { Observable };

package/dist/OperatorSubscriber.js

@@ -0,0 +1,62 @@
+import { __extends } from 'tslib';
+import { Subscriber } from './Subscriber.js';
+
+function createOperatorSubscriber(destination, onNext, onComplete, onError, onFinalize) {
+    return new OperatorSubscriber(destination, onNext, onComplete, onError, onFinalize);
+}
+var OperatorSubscriber = (function (_super) {
+    __extends(OperatorSubscriber, _super);
+    function OperatorSubscriber(destination, onNext, onComplete, onError, onFinalize, shouldUnsubscribe) {
+        var _this = _super.call(this, destination) || this;
+        _this.onFinalize = onFinalize;
+        _this.shouldUnsubscribe = shouldUnsubscribe;
+        _this._next = onNext
+            ? function (value) {
+                try {
+                    onNext(value);
+                }
+                catch (err) {
+                    destination.error(err);
+                }
+            }
+            : _super.prototype._next;
+        _this._error = onError
+            ? function (err) {
+                try {
+                    onError(err);
+                }
+                catch (err) {
+                    destination.error(err);
+                }
+                finally {
+                    this.unsubscribe();
+                }
+            }
+            : _super.prototype._error;
+        _this._complete = onComplete
+            ? function () {
+                try {
+                    onComplete();
+                }
+                catch (err) {
+                    destination.error(err);
+                }
+                finally {
+                    this.unsubscribe();
+                }
+            }
+            : _super.prototype._complete;
+        return _this;
+    }
+    OperatorSubscriber.prototype.unsubscribe = function () {
+        var _a;
+        if (!this.shouldUnsubscribe || this.shouldUnsubscribe()) {
+            var closed_1 = this.closed;
+            _super.prototype.unsubscribe.call(this);
+            !closed_1 && ((_a = this.onFinalize) === null || _a === void 0 ? void 0 : _a.call(this));
+        }
+    };
+    return OperatorSubscriber;
+}(Subscriber));
+
+export { OperatorSubscriber, createOperatorSubscriber };

package/dist/Scheduler.js

@@ -0,0 +1,17 @@
+import { dateTimestampProvider } from './dateTimestampProvider.js';
+
+var Scheduler = (function () {
+    function Scheduler(schedulerActionCtor, now) {
+        if (now === void 0) { now = Scheduler.now; }
+        this.schedulerActionCtor = schedulerActionCtor;
+        this.now = now;
+    }
+    Scheduler.prototype.schedule = function (work, delay, state) {
+        if (delay === void 0) { delay = 0; }
+        return new this.schedulerActionCtor(this, work).schedule(state, delay);
+    };
+    Scheduler.now = dateTimestampProvider.now;
+    return Scheduler;
+}());
+
+export { Scheduler };

package/dist/Subject.js

@@ -0,0 +1,162 @@
+import { __extends, __values } from 'tslib';
+import { Observable } from './Observable.js';
+import { EMPTY_SUBSCRIPTION, Subscription } from './Subscription.js';
+import { ObjectUnsubscribedError } from './ObjectUnsubscribedError.js';
+import { arrRemove } from './arrRemove.js';
+import { errorContext } from './errorContext.js';
+
+var Subject = (function (_super) {
+    __extends(Subject, _super);
+    function Subject() {
+        var _this = _super.call(this) || this;
+        _this.closed = false;
+        _this.currentObservers = null;
+        _this.observers = [];
+        _this.isStopped = false;
+        _this.hasError = false;
+        _this.thrownError = null;
+        return _this;
+    }
+    Subject.prototype.lift = function (operator) {
+        var subject = new AnonymousSubject(this, this);
+        subject.operator = operator;
+        return subject;
+    };
+    Subject.prototype._throwIfClosed = function () {
+        if (this.closed) {
+            throw new ObjectUnsubscribedError();
+        }
+    };
+    Subject.prototype.next = function (value) {
+        var _this = this;
+        errorContext(function () {
+            var e_1, _a;
+            _this._throwIfClosed();
+            if (!_this.isStopped) {
+                if (!_this.currentObservers) {
+                    _this.currentObservers = Array.from(_this.observers);
+                }
+                try {
+                    for (var _b = __values(_this.currentObservers), _c = _b.next(); !_c.done; _c = _b.next()) {
+                        var observer = _c.value;
+                        observer.next(value);
+                    }
+                }
+                catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                finally {
+                    try {
+                        if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+                    }
+                    finally { if (e_1) throw e_1.error; }
+                }
+            }
+        });
+    };
+    Subject.prototype.error = function (err) {
+        var _this = this;
+        errorContext(function () {
+            _this._throwIfClosed();
+            if (!_this.isStopped) {
+                _this.hasError = _this.isStopped = true;
+                _this.thrownError = err;
+                var observers = _this.observers;
+                while (observers.length) {
+                    observers.shift().error(err);
+                }
+            }
+        });
+    };
+    Subject.prototype.complete = function () {
+        var _this = this;
+        errorContext(function () {
+            _this._throwIfClosed();
+            if (!_this.isStopped) {
+                _this.isStopped = true;
+                var observers = _this.observers;
+                while (observers.length) {
+                    observers.shift().complete();
+                }
+            }
+        });
+    };
+    Subject.prototype.unsubscribe = function () {
+        this.isStopped = this.closed = true;
+        this.observers = this.currentObservers = null;
+    };
+    Object.defineProperty(Subject.prototype, "observed", {
+        get: function () {
+            var _a;
+            return ((_a = this.observers) === null || _a === void 0 ? void 0 : _a.length) > 0;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Subject.prototype._trySubscribe = function (subscriber) {
+        this._throwIfClosed();
+        return _super.prototype._trySubscribe.call(this, subscriber);
+    };
+    Subject.prototype._subscribe = function (subscriber) {
+        this._throwIfClosed();
+        this._checkFinalizedStatuses(subscriber);
+        return this._innerSubscribe(subscriber);
+    };
+    Subject.prototype._innerSubscribe = function (subscriber) {
+        var _this = this;
+        var _a = this, hasError = _a.hasError, isStopped = _a.isStopped, observers = _a.observers;
+        if (hasError || isStopped) {
+            return EMPTY_SUBSCRIPTION;
+        }
+        this.currentObservers = null;
+        observers.push(subscriber);
+        return new Subscription(function () {
+            _this.currentObservers = null;
+            arrRemove(observers, subscriber);
+        });
+    };
+    Subject.prototype._checkFinalizedStatuses = function (subscriber) {
+        var _a = this, hasError = _a.hasError, thrownError = _a.thrownError, isStopped = _a.isStopped;
+        if (hasError) {
+            subscriber.error(thrownError);
+        }
+        else if (isStopped) {
+            subscriber.complete();
+        }
+    };
+    Subject.prototype.asObservable = function () {
+        var observable = new Observable();
+        observable.source = this;
+        return observable;
+    };
+    Subject.create = function (destination, source) {
+        return new AnonymousSubject(destination, source);
+    };
+    return Subject;
+}(Observable));
+var AnonymousSubject = (function (_super) {
+    __extends(AnonymousSubject, _super);
+    function AnonymousSubject(destination, source) {
+        var _this = _super.call(this) || this;
+        _this.destination = destination;
+        _this.source = source;
+        return _this;
+    }
+    AnonymousSubject.prototype.next = function (value) {
+        var _a, _b;
+        (_b = (_a = this.destination) === null || _a === void 0 ? void 0 : _a.next) === null || _b === void 0 ? void 0 : _b.call(_a, value);
+    };
+    AnonymousSubject.prototype.error = function (err) {
+        var _a, _b;
+        (_b = (_a = this.destination) === null || _a === void 0 ? void 0 : _a.error) === null || _b === void 0 ? void 0 : _b.call(_a, err);
+    };
+    AnonymousSubject.prototype.complete = function () {
+        var _a, _b;
+        (_b = (_a = this.destination) === null || _a === void 0 ? void 0 : _a.complete) === null || _b === void 0 ? void 0 : _b.call(_a);
+    };
+    AnonymousSubject.prototype._subscribe = function (subscriber) {
+        var _a, _b;
+        return (_b = (_a = this.source) === null || _a === void 0 ? void 0 : _a.subscribe(subscriber)) !== null && _b !== void 0 ? _b : EMPTY_SUBSCRIPTION;
+    };
+    return AnonymousSubject;
+}(Subject));
+
+export { AnonymousSubject, Subject };