signalium 2.1.3 → 2.1.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # signalium
 
+## 2.1.4
+
+### Patch Changes
+
+- 2cf6766: Add forwardRelay utility
+
 ## 2.1.3
 
 ### Patch Changes

package/dist/cjs/index.d.ts

@@ -4,5 +4,5 @@ export { signal, notifier } from './internals/signal.js';
 export { ReactivePromise } from './internals/async.js';
 export { callback } from './internals/callback.js';
 export { context, getContext, withContexts, setGlobalContexts, clearGlobalContexts, setScopeOwner, } from './internals/contexts.js';
-export { watchOnce } from './utils.js';
+export { watchOnce, forwardRelay } from './utils.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,4BAA4B,EACjC,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,KAAK,sBAAsB,EAC3B,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,OAAO,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,cAAc,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEzG,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD,OAAO,EACL,OAAO,EACP,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,GACd,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,4BAA4B,EACjC,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,KAAK,sBAAsB,EAC3B,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,OAAO,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,cAAc,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEzG,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD,OAAO,EACL,OAAO,EACP,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,GACd,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.watchOnce = exports.setScopeOwner = exports.clearGlobalContexts = exports.setGlobalContexts = exports.withContexts = exports.getContext = exports.context = exports.callback = exports.ReactivePromise = exports.notifier = exports.signal = exports.watcher = exports.relay = exports.task = exports.reactiveSignal = exports.reactiveMethod = exports.reactive = void 0;
+exports.forwardRelay = exports.watchOnce = exports.setScopeOwner = exports.clearGlobalContexts = exports.setGlobalContexts = exports.withContexts = exports.getContext = exports.context = exports.callback = exports.ReactivePromise = exports.notifier = exports.signal = exports.watcher = exports.relay = exports.task = exports.reactiveSignal = exports.reactiveMethod = exports.reactive = void 0;
 var core_api_js_1 = require("./internals/core-api.js");
 Object.defineProperty(exports, "reactive", { enumerable: true, get: function () { return core_api_js_1.reactive; } });
 Object.defineProperty(exports, "reactiveMethod", { enumerable: true, get: function () { return core_api_js_1.reactiveMethod; } });
@@ -24,4 +24,5 @@ Object.defineProperty(exports, "clearGlobalContexts", { enumerable: true, get: f
 Object.defineProperty(exports, "setScopeOwner", { enumerable: true, get: function () { return contexts_js_1.setScopeOwner; } });
 var utils_js_1 = require("./utils.js");
 Object.defineProperty(exports, "watchOnce", { enumerable: true, get: function () { return utils_js_1.watchOnce; } });
+Object.defineProperty(exports, "forwardRelay", { enumerable: true, get: function () { return utils_js_1.forwardRelay; } });
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAoBA,uDAAyG;AAAhG,uGAAA,QAAQ,OAAA;AAAE,6GAAA,cAAc,OAAA;AAAE,6GAAA,cAAc,OAAA;AAAE,mGAAA,IAAI,OAAA;AAAE,oGAAA,KAAK,OAAA;AAAE,sGAAA,OAAO,OAAA;AAEvE,mDAAyD;AAAhD,mGAAA,MAAM,OAAA;AAAE,qGAAA,QAAQ,OAAA;AAEzB,iDAAuD;AAA9C,2GAAA,eAAe,OAAA;AAExB,uDAAmD;AAA1C,uGAAA,QAAQ,OAAA;AAEjB,uDAOiC;AAN/B,sGAAA,OAAO,OAAA;AACP,yGAAA,UAAU,OAAA;AACV,2GAAA,YAAY,OAAA;AACZ,gHAAA,iBAAiB,OAAA;AACjB,kHAAA,mBAAmB,OAAA;AACnB,4GAAA,aAAa,OAAA;AAGf,uCAAuC;AAA9B,qGAAA,SAAS,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAoBA,uDAAyG;AAAhG,uGAAA,QAAQ,OAAA;AAAE,6GAAA,cAAc,OAAA;AAAE,6GAAA,cAAc,OAAA;AAAE,mGAAA,IAAI,OAAA;AAAE,oGAAA,KAAK,OAAA;AAAE,sGAAA,OAAO,OAAA;AAEvE,mDAAyD;AAAhD,mGAAA,MAAM,OAAA;AAAE,qGAAA,QAAQ,OAAA;AAEzB,iDAAuD;AAA9C,2GAAA,eAAe,OAAA;AAExB,uDAAmD;AAA1C,uGAAA,QAAQ,OAAA;AAEjB,uDAOiC;AAN/B,sGAAA,OAAO,OAAA;AACP,yGAAA,UAAU,OAAA;AACV,2GAAA,YAAY,OAAA;AACZ,gHAAA,iBAAiB,OAAA;AACjB,kHAAA,mBAAmB,OAAA;AACnB,4GAAA,aAAa,OAAA;AAGf,uCAAqD;AAA5C,qGAAA,SAAS,OAAA;AAAE,wGAAA,YAAY,OAAA"}

package/dist/cjs/utils.d.ts

@@ -1,4 +1,5 @@
 export { hashValue, registerCustomHash } from './internals/utils/hash.js';
+import { RelayState, DiscriminatedReactivePromise } from './types.js';
 /**
  * Watches a function once in a reactive context, activating any relays,
  * then automatically tears down the watcher when complete.
@@ -23,4 +24,35 @@ export { hashValue, registerCustomHash } from './internals/utils/hash.js';
  */
 export declare function watchOnce<T>(fn: () => T): T;
 export { setReactivePromise } from './internals/async.js';
+/**
+ * Forwards state from a source relay to the target relay's state.
+ * This enables composition patterns where relays can add side effects
+ * while transparently forwarding state from another relay.
+ *
+ * The forwarding is automatically tracked through the signal graph.
+ * When the source relay updates, the target relay will re-run its
+ * activation function, and forwardRelay will forward the new state.
+ * No cleanup is needed - dependencies are managed automatically.
+ *
+ * @param state - The target relay's state object
+ * @param sourceRelay - The source relay to forward state from
+ *
+ * @example
+ * ```ts
+ * const sourceRelay = relay(state => {
+ *   // ... source relay logic
+ * });
+ *
+ * const forwardedRelay = relay(state => {
+ *   // Add additional side effect
+ *   const cleanup = setupSomeEffect();
+ *
+ *   // Forward state from source relay (automatically tracked and cleaned up)
+ *   forwardRelay(state, sourceRelay);
+ *
+ *   return cleanup; // Only return cleanup for the additional effect
+ * });
+ * ```
+ */
+export declare function forwardRelay<T>(state: RelayState<T>, sourceRelay: DiscriminatedReactivePromise<T>): void;
 //# sourceMappingURL=utils.d.ts.map

package/dist/cjs/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAW1E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAwB3C;AAED,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAQ1E,OAAO,EAAiB,UAAU,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAwB3C;AAED,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,4BAA4B,CAAC,CAAC,CAAC,GAAG,IAAI,CA8BxG"}

package/dist/cjs/utils.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setReactivePromise = exports.registerCustomHash = exports.hashValue = void 0;
 exports.watchOnce = watchOnce;
+exports.forwardRelay = forwardRelay;
 var hash_js_1 = require("./internals/utils/hash.js");
 Object.defineProperty(exports, "hashValue", { enumerable: true, get: function () { return hash_js_1.hashValue; } });
 Object.defineProperty(exports, "registerCustomHash", { enumerable: true, get: function () { return hash_js_1.registerCustomHash; } });
@@ -57,4 +58,66 @@ function watchOnce(fn) {
 }
 var async_js_2 = require("./internals/async.js");
 Object.defineProperty(exports, "setReactivePromise", { enumerable: true, get: function () { return async_js_2.setReactivePromise; } });
+/**
+ * Forwards state from a source relay to the target relay's state.
+ * This enables composition patterns where relays can add side effects
+ * while transparently forwarding state from another relay.
+ *
+ * The forwarding is automatically tracked through the signal graph.
+ * When the source relay updates, the target relay will re-run its
+ * activation function, and forwardRelay will forward the new state.
+ * No cleanup is needed - dependencies are managed automatically.
+ *
+ * @param state - The target relay's state object
+ * @param sourceRelay - The source relay to forward state from
+ *
+ * @example
+ * ```ts
+ * const sourceRelay = relay(state => {
+ *   // ... source relay logic
+ * });
+ *
+ * const forwardedRelay = relay(state => {
+ *   // Add additional side effect
+ *   const cleanup = setupSomeEffect();
+ *
+ *   // Forward state from source relay (automatically tracked and cleaned up)
+ *   forwardRelay(state, sourceRelay);
+ *
+ *   return cleanup; // Only return cleanup for the additional effect
+ * });
+ * ```
+ */
+function forwardRelay(state, sourceRelay) {
+    // Verify that sourceRelay is actually a ReactivePromiseImpl
+    if (!(0, async_js_1.isReactivePromise)(sourceRelay)) {
+        throw new Error('forwardRelay: sourceRelay must be a ReactivePromise');
+    }
+    // Read from source relay to establish dependency and forward state
+    // When sourceRelay updates, this relay's activation function will be called again,
+    // and forwardRelay will be called again, forwarding the new state
+    if (sourceRelay.isPending) {
+        // For pending state, try to forward the promise if available
+        // Accessing isPending establishes the dependency
+        const source = sourceRelay;
+        const promise = source['_promise'];
+        if (promise) {
+            state.setPromise(promise);
+        }
+    }
+    else if (sourceRelay.isRejected) {
+        // Accessing error establishes dependency and forwards it
+        const error = sourceRelay.error;
+        if (error !== undefined) {
+            state.setError(error);
+        }
+    }
+    else if (sourceRelay.isResolved && sourceRelay.isReady) {
+        // Accessing value establishes dependency and forwards it
+        const value = sourceRelay.value;
+        if (value !== undefined) {
+            state.value = value;
+        }
+    }
+}
 //# sourceMappingURL=utils.js.map

package/dist/cjs/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":";;;AAiCA,8BAwBC;AAzDD,qDAA0E;AAAjE,oGAAA,SAAS,OAAA;AAAE,6GAAA,kBAAkB,OAAA;AAEtC,yDAAkD;AAClD,mDAAkE;AAClE,+CAA+C;AAC/C,mDAA0E;AAG1E,mEAA4D;AAG5D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,SAAS,CAAI,EAAW;IACtC,0BAA0B;IAC1B,MAAM,MAAM,GAAG,IAAA,qBAAO,EAAC,EAAE,CAAiC,CAAC;IAE3D,IAAI,CAAC;QACH,0CAA0C;QAC1C,IAAA,sBAAW,EAAC,MAAM,CAAC,CAAC;QAEpB,yCAAyC;QACzC,IAAI,MAAM,GAAG,IAAA,kBAAS,EAAC,MAAM,CAAC,CAAC;QAE/B,IAAI,IAAA,4BAAiB,EAAC,MAAgB,CAAC,IAAI,IAAA,yBAAS,EAAC,MAAgB,CAAC,EAAE,CAAC;YACvE,MAAM,GAAI,MAAqB,CAAC,OAAO,CAAC,GAAG,EAAE;gBAC3C,IAAA,wBAAa,EAAC,MAAM,CAAC,CAAC;YACxB,CAAC,CAAqB,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,IAAA,wBAAa,EAAC,MAAM,CAAC,CAAC;QACxB,CAAC;QAED,OAAO,MAAW,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAA,wBAAa,EAAC,MAAM,CAAC,CAAC;QACtB,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,iDAA0D;AAAjD,8GAAA,kBAAkB,OAAA"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":";;;AAgCA,8BAwBC;AAkCD,oCA8BC;AAxHD,qDAA0E;AAAjE,oGAAA,SAAS,OAAA;AAAE,6GAAA,kBAAkB,OAAA;AAEtC,yDAA4D;AAC5D,mDAAkE;AAClE,+CAA+C;AAC/C,mDAA8E;AAE9E,mEAA4D;AAG5D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,SAAS,CAAI,EAAW;IACtC,0BAA0B;IAC1B,MAAM,MAAM,GAAG,IAAA,qBAAO,EAAC,EAAE,CAAiC,CAAC;IAE3D,IAAI,CAAC;QACH,0CAA0C;QAC1C,IAAA,sBAAW,EAAC,MAAM,CAAC,CAAC;QAEpB,yCAAyC;QACzC,IAAI,MAAM,GAAG,IAAA,kBAAS,EAAC,MAAM,CAAC,CAAC;QAE/B,IAAI,IAAA,4BAAiB,EAAC,MAAgB,CAAC,IAAI,IAAA,yBAAS,EAAC,MAAgB,CAAC,EAAE,CAAC;YACvE,MAAM,GAAI,MAAqB,CAAC,OAAO,CAAC,GAAG,EAAE;gBAC3C,IAAA,wBAAa,EAAC,MAAM,CAAC,CAAC;YACxB,CAAC,CAAqB,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,IAAA,wBAAa,EAAC,MAAM,CAAC,CAAC;QACxB,CAAC;QAED,OAAO,MAAW,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAA,wBAAa,EAAC,MAAM,CAAC,CAAC;QACtB,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,iDAA0D;AAAjD,8GAAA,kBAAkB,OAAA;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,SAAgB,YAAY,CAAI,KAAoB,EAAE,WAA4C;IAChG,4DAA4D;IAC5D,IAAI,CAAC,IAAA,4BAAiB,EAAC,WAAW,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IAED,mEAAmE;IACnE,mFAAmF;IACnF,kEAAkE;IAClE,IAAI,WAAW,CAAC,SAAS,EAAE,CAAC;QAC1B,6DAA6D;QAC7D,iDAAiD;QACjD,MAAM,MAAM,GAAG,WAAqC,CAAC;QACrD,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAA2B,CAAC;QAC7D,IAAI,OAAO,EAAE,CAAC;YACZ,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;SAAM,IAAI,WAAW,CAAC,UAAU,EAAE,CAAC;QAClC,yDAAyD;QACzD,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;SAAM,IAAI,WAAW,CAAC,UAAU,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC;QACzD,yDAAyD;QACzD,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/esm/index.d.ts

@@ -4,5 +4,5 @@ export { signal, notifier } from './internals/signal.js';
 export { ReactivePromise } from './internals/async.js';
 export { callback } from './internals/callback.js';
 export { context, getContext, withContexts, setGlobalContexts, clearGlobalContexts, setScopeOwner, } from './internals/contexts.js';
-export { watchOnce } from './utils.js';
+export { watchOnce, forwardRelay } from './utils.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,4BAA4B,EACjC,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,KAAK,sBAAsB,EAC3B,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,OAAO,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,cAAc,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEzG,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD,OAAO,EACL,OAAO,EACP,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,GACd,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,4BAA4B,EACjC,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,KAAK,sBAAsB,EAC3B,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,OAAO,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,cAAc,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEzG,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD,OAAO,EACL,OAAO,EACP,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,GACd,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/esm/index.js

@@ -3,5 +3,5 @@ export { signal, notifier } from './internals/signal.js';
 export { ReactivePromise } from './internals/async.js';
 export { callback } from './internals/callback.js';
 export { context, getContext, withContexts, setGlobalContexts, clearGlobalContexts, setScopeOwner, } from './internals/contexts.js';
-export { watchOnce } from './utils.js';
+export { watchOnce, forwardRelay } from './utils.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,cAAc,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEzG,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD,OAAO,EACL,OAAO,EACP,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,GACd,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,cAAc,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEzG,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD,OAAO,EACL,OAAO,EACP,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,GACd,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/esm/utils.d.ts

@@ -1,4 +1,5 @@
 export { hashValue, registerCustomHash } from './internals/utils/hash.js';
+import { RelayState, DiscriminatedReactivePromise } from './types.js';
 /**
  * Watches a function once in a reactive context, activating any relays,
  * then automatically tears down the watcher when complete.
@@ -23,4 +24,35 @@ export { hashValue, registerCustomHash } from './internals/utils/hash.js';
  */
 export declare function watchOnce<T>(fn: () => T): T;
 export { setReactivePromise } from './internals/async.js';
+/**
+ * Forwards state from a source relay to the target relay's state.
+ * This enables composition patterns where relays can add side effects
+ * while transparently forwarding state from another relay.
+ *
+ * The forwarding is automatically tracked through the signal graph.
+ * When the source relay updates, the target relay will re-run its
+ * activation function, and forwardRelay will forward the new state.
+ * No cleanup is needed - dependencies are managed automatically.
+ *
+ * @param state - The target relay's state object
+ * @param sourceRelay - The source relay to forward state from
+ *
+ * @example
+ * ```ts
+ * const sourceRelay = relay(state => {
+ *   // ... source relay logic
+ * });
+ *
+ * const forwardedRelay = relay(state => {
+ *   // Add additional side effect
+ *   const cleanup = setupSomeEffect();
+ *
+ *   // Forward state from source relay (automatically tracked and cleaned up)
+ *   forwardRelay(state, sourceRelay);
+ *
+ *   return cleanup; // Only return cleanup for the additional effect
+ * });
+ * ```
+ */
+export declare function forwardRelay<T>(state: RelayState<T>, sourceRelay: DiscriminatedReactivePromise<T>): void;
 //# sourceMappingURL=utils.d.ts.map

package/dist/esm/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAW1E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAwB3C;AAED,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAQ1E,OAAO,EAAiB,UAAU,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAwB3C;AAED,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,4BAA4B,CAAC,CAAC,CAAC,GAAG,IAAI,CA8BxG"}

package/dist/esm/utils.js

@@ -50,4 +50,66 @@ export function watchOnce(fn) {
     }
 }
 export { setReactivePromise } from './internals/async.js';
+/**
+ * Forwards state from a source relay to the target relay's state.
+ * This enables composition patterns where relays can add side effects
+ * while transparently forwarding state from another relay.
+ *
+ * The forwarding is automatically tracked through the signal graph.
+ * When the source relay updates, the target relay will re-run its
+ * activation function, and forwardRelay will forward the new state.
+ * No cleanup is needed - dependencies are managed automatically.
+ *
+ * @param state - The target relay's state object
+ * @param sourceRelay - The source relay to forward state from
+ *
+ * @example
+ * ```ts
+ * const sourceRelay = relay(state => {
+ *   // ... source relay logic
+ * });
+ *
+ * const forwardedRelay = relay(state => {
+ *   // Add additional side effect
+ *   const cleanup = setupSomeEffect();
+ *
+ *   // Forward state from source relay (automatically tracked and cleaned up)
+ *   forwardRelay(state, sourceRelay);
+ *
+ *   return cleanup; // Only return cleanup for the additional effect
+ * });
+ * ```
+ */
+export function forwardRelay(state, sourceRelay) {
+    // Verify that sourceRelay is actually a ReactivePromiseImpl
+    if (!isReactivePromise(sourceRelay)) {
+        throw new Error('forwardRelay: sourceRelay must be a ReactivePromise');
+    }
+    // Read from source relay to establish dependency and forward state
+    // When sourceRelay updates, this relay's activation function will be called again,
+    // and forwardRelay will be called again, forwarding the new state
+    if (sourceRelay.isPending) {
+        // For pending state, try to forward the promise if available
+        // Accessing isPending establishes the dependency
+        const source = sourceRelay;
+        const promise = source['_promise'];
+        if (promise) {
+            state.setPromise(promise);
+        }
+    }
+    else if (sourceRelay.isRejected) {
+        // Accessing error establishes dependency and forwards it
+        const error = sourceRelay.error;
+        if (error !== undefined) {
+            state.setError(error);
+        }
+    }
+    else if (sourceRelay.isResolved && sourceRelay.isReady) {
+        // Accessing value establishes dependency and forwards it
+        const value = sourceRelay.value;
+        if (value !== undefined) {
+            state.value = value;
+        }
+    }
+}
 //# sourceMappingURL=utils.js.map

package/dist/esm/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE1E,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAmB,MAAM,sBAAsB,CAAC;AAG1E,OAAO,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAG5D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,SAAS,CAAI,EAAW;IACtC,0BAA0B;IAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,EAAE,CAAiC,CAAC;IAE3D,IAAI,CAAC;QACH,0CAA0C;QAC1C,WAAW,CAAC,MAAM,CAAC,CAAC;QAEpB,yCAAyC;QACzC,IAAI,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;QAE/B,IAAI,iBAAiB,CAAC,MAAgB,CAAC,IAAI,SAAS,CAAC,MAAgB,CAAC,EAAE,CAAC;YACvE,MAAM,GAAI,MAAqB,CAAC,OAAO,CAAC,GAAG,EAAE;gBAC3C,aAAa,CAAC,MAAM,CAAC,CAAC;YACxB,CAAC,CAAqB,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,aAAa,CAAC,MAAM,CAAC,CAAC;QACxB,CAAC;QAED,OAAO,MAAW,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,aAAa,CAAC,MAAM,CAAC,CAAC;QACtB,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE1E,OAAO,EAAE,OAAO,EAAY,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAuB,MAAM,sBAAsB,CAAC;AAE9E,OAAO,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAG5D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,SAAS,CAAI,EAAW;IACtC,0BAA0B;IAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,EAAE,CAAiC,CAAC;IAE3D,IAAI,CAAC;QACH,0CAA0C;QAC1C,WAAW,CAAC,MAAM,CAAC,CAAC;QAEpB,yCAAyC;QACzC,IAAI,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;QAE/B,IAAI,iBAAiB,CAAC,MAAgB,CAAC,IAAI,SAAS,CAAC,MAAgB,CAAC,EAAE,CAAC;YACvE,MAAM,GAAI,MAAqB,CAAC,OAAO,CAAC,GAAG,EAAE;gBAC3C,aAAa,CAAC,MAAM,CAAC,CAAC;YACxB,CAAC,CAAqB,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,aAAa,CAAC,MAAM,CAAC,CAAC;QACxB,CAAC;QAED,OAAO,MAAW,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,aAAa,CAAC,MAAM,CAAC,CAAC;QACtB,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,YAAY,CAAI,KAAoB,EAAE,WAA4C;IAChG,4DAA4D;IAC5D,IAAI,CAAC,iBAAiB,CAAC,WAAW,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IAED,mEAAmE;IACnE,mFAAmF;IACnF,kEAAkE;IAClE,IAAI,WAAW,CAAC,SAAS,EAAE,CAAC;QAC1B,6DAA6D;QAC7D,iDAAiD;QACjD,MAAM,MAAM,GAAG,WAAqC,CAAC;QACrD,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAA2B,CAAC;QAC7D,IAAI,OAAO,EAAE,CAAC;YACZ,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;SAAM,IAAI,WAAW,CAAC,UAAU,EAAE,CAAC;QAClC,yDAAyD;QACzD,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;SAAM,IAAI,WAAW,CAAC,UAAU,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC;QACzD,yDAAyD;QACzD,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalium",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "type": "module",
   "repository": {
     "type": "git",