@alwatr/signal 9.26.0 → 9.29.0

package/src/operators/filter.ts

@@ -1,7 +1,4 @@
-import {createComputedSignal} from '../creators/computed.js';
 import {createStateSignal} from '../creators/state.js';
-
-import type {ComputedSignal} from '../core/computed-signal.js';
 import type {IReadonlySignal} from '../type.js';
 
 /**
@@ -24,40 +21,45 @@ import type {IReadonlySignal} from '../type.js';
  * @returns A new computed signal that emits filtered values.
  *
  * @example
+ * ```typescript
  * const numberSignal = createStateSignal({ name: 'number', initialValue: 0 });
  *
  * const evenNumberSignal = createFilteredSignal(
- * numberSignal,
- * (num) => num % 2 === 0,
+ *   numberSignal,
+ *   (num) => num % 2 === 0,
  * );
  *
  * createEffect({
- * deps: [evenNumberSignal],
- * run: () => {
- * // This effect only runs for even numbers.
- * // The value can be `undefined` on the first run if initialValue is not even.
- * if (evenNumberSignal.get() !== undefined) {
- * console.log(`Even number detected: ${evenNumberSignal.get()}`);
- * }
- * },
- * runImmediately: true,
+ *   deps: [evenNumberSignal],
+ *   run: () => {
+ *     // This effect only runs for even numbers.
+ *     // The value can be `undefined` on the first run if initialValue is not even.
+ *     if (evenNumberSignal.get() !== undefined) {
+ *       console.log(`Even number detected: ${evenNumberSignal.get()}`);
+ *     }
+ *   },
+ *   runImmediately: true,
  * });
  * // Logs: "Even number detected: 0"
  *
  * numberSignal.set(1); // Effect does not run
  * numberSignal.set(2); // Logs: "Even number detected: 2"
+ * ```
  */
 export function createFilteredSignal<T>(
   sourceSignal: IReadonlySignal<T>,
   predicate: (value: T) => boolean,
-  name = `${sourceSignal.name}-filtered`,
-): ComputedSignal<T | undefined> {
+  name = `${sourceSignal.name}_filtered`,
+): IReadonlySignal<T | undefined> {
   const sourceValue = sourceSignal.get();
   const initialValue = predicate(sourceValue) ? sourceValue : undefined;
 
   const internalSignal = createStateSignal({
-    name: `${name}-internal`,
+    name,
     initialValue,
+    onDestroy() {
+      subscription.unsubscribe();
+    },
   });
 
   const subscription = sourceSignal.subscribe((newValue) => {
@@ -66,13 +68,5 @@ export function createFilteredSignal<T>(
     }
   });
 
-  return createComputedSignal({
-    name: name,
-    deps: [internalSignal],
-    get: () => internalSignal.get(),
-    onDestroy: () => {
-      subscription.unsubscribe();
-      internalSignal.destroy();
-    },
-  });
+  return internalSignal;
 }

package/src/type.ts

@@ -1,4 +1,3 @@
-import type {Awaitable} from '@alwatr/type-helper';
 import type {DebouncerConfig} from '@alwatr/debounce';
 import type {LocalStorageProviderConfig} from '@alwatr/local-storage';
 import type {SessionStorageProviderConfig} from '@alwatr/session-storage';
@@ -11,7 +10,7 @@ import type {SessionStorageProviderConfig} from '@alwatr/session-storage';
  *
  * @template T The type of the value that the signal holds or dispatches.
  */
-export type ListenerCallback<T> = (value: T) => Awaitable<void>;
+export type ListenerCallback<T> = (value: T) => void;
 
 /**
  * Options for fine-tuning the behavior of a subscription to a signal.
@@ -225,6 +224,23 @@ export interface ComputedSignalConfig<T> extends SignalConfig {
   get: () => T;
 }
 
+/**
+ * Configuration for creating a `DerivedSignal`.
+ * @template S The type of the source signal state.
+ * @template T The type of the projected derived state.
+ */
+export interface DerivedSignalConfig<S, T> extends SignalConfig {
+  /**
+   * The single upstream readonly source signal.
+   */
+  readonly source: IReadonlySignal<S>;
+
+  /**
+   * Projection mapping function transforming source S to derived T.
+   */
+  readonly projector: (value: S) => T;
+}
+
 /**
  * Configuration for creating an `EffectSignal`.
  */
@@ -258,7 +274,7 @@ export interface EffectSignalConfig {
    *   run: () => console.log(`The counter is now: ${counter.get()}`),
    * });
    */
-  run: () => Awaitable<void>;
+  run: () => void;
 
   /**
    * If `true`, the effect's `run` function will be executed once immediately upon initialization.
@@ -406,3 +422,55 @@ export interface SessionStateSignalConfig<T> extends StateSignalConfig<T>, Sessi
    */
   saveDebounceDelay?: number;
 }
+
+/**
+ * Determines whether the payload argument for a given channel message is
+ * required or optional, based solely on the declared type in `TMap`.
+ *
+ * - `void | undefined` → payload is optional (second arg may be omitted).
+ * - anything else      → payload is **required** (omitting it is a compile error).
+ *
+ * This is used to build the rest-parameter tuple for `dispatch()` so that
+ * TypeScript enforces the correct call signature at every dispatch site.
+ *
+ * @template TMap A record mapping message names to their payload types.
+ * @template K    The specific message name key.
+ *
+ * @example
+ * ```ts
+ * // ActionRecord: { 'logout': void; 'add-to-cart': {productId: number} }
+ * type A = DispatchArgs<ActionRecord, 'logout'>;       // [name: 'logout', payload?: void]
+ * type B = DispatchArgs<ActionRecord, 'add-to-cart'>;  // [name: 'add-to-cart', payload: {productId: number}]
+ * ```
+ */
+export type DispatchArgs<TMap extends object, K extends keyof TMap> =
+  TMap[K] extends void | undefined ? [name: K, payload?: TMap[K]] : [name: K, payload: TMap[K]];
+
+/**
+ * A single message dispatched through a `ChannelSignal`.
+ *
+ * `name` identifies the message type (e.g. `'open-drawer'`, `'add-to-cart'`).
+ * `payload` carries the associated data, whose type is determined by the generic `TMap` based on the `name`.
+ *
+ * @template TMap A record mapping message names to their payload types.
+ * @template K    The specific message name key (inferred, not set manually).
+ */
+export type ChannelMessage<TMap extends object, K extends keyof TMap = keyof TMap> = {name: K; payload: TMap[K]};
+
+/**
+ * A typed handler for a specific named message on a `ChannelSignal`.
+ * Receives only the `payload` — the name is already known at subscription time.
+ *
+ * The payload type mirrors `DispatchArgs`: it is `TMap[K] | undefined` only
+ * when the declared type is `void | undefined`; otherwise it is exactly `TMap[K]`
+ * (non-optional) so handlers do not need unnecessary null-guards.
+ *
+ * @template TMap A record mapping message names to their payload types.
+ * @template K    The specific message name key.
+ */
+export type ChannelHandler<TMap extends object, K extends keyof TMap = keyof TMap> = (payload: TMap[K]) => void;
+
+/**
+ * Configuration for creating a `ChannelSignal`.
+ */
+export interface ChannelSignalConfig extends SignalConfig {}

package/dist/operators/map.d.ts

@@ -1,36 +0,0 @@
-import type { ComputedSignal } from '../core/computed-signal.js';
-import type { IReadonlySignal } from '../type.js';
-/**
- * Creates a new read-only computed signal that transforms the value of a source
- * signal using a projection function.
- *
- * This operator is analogous to `Array.prototype.map`. It applies a function to
- * each value emitted by the source signal and emits the result.
- *
- * @template T The type of the source signal's value.
- * @template R The type of the projected value.
- *
- * @param sourceSignal The original signal to transform.
- * @param projectFunction A function to apply to each value from the source signal.
- * @param [name] An optional, unique identifier for the new signal for debugging. default: `${sourceSignal.name}-mapped`
- *
- * @returns A new, read-only computed signal with the transformed values.
- *
- * @example
- * const userSignal = createStateSignal({
- *   name: 'user',
- *   initialValue: { name: 'John', age: 30 },
- * });
- *
- * const userNameSignal = createMappedSignal(
- *   userSignal,
- *   (user) => user.name,
- * );
- *
- * console.log(userNameSignal.get()); // Outputs: "John"
- * // in next macro-task ...
- * userSignal.set({ name: 'Jane', age: 32 });
- * console.log(userNameSignal.get()); // Outputs: "Jane"
- */
-export declare function createMappedSignal<T, R>(sourceSignal: IReadonlySignal<T>, projectFunction: (value: T) => R, name?: string): ComputedSignal<R>;
-//# sourceMappingURL=map.d.ts.map

package/dist/operators/map.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../src/operators/map.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,YAAY,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EACrC,YAAY,EAAE,eAAe,CAAC,CAAC,CAAC,EAChC,eAAe,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EAChC,IAAI,SAAgC,GACnC,cAAc,CAAC,CAAC,CAAC,CAMnB"}

package/src/operators/map.ts

@@ -1,48 +0,0 @@
-import {createComputedSignal} from '../creators/computed.js';
-
-import type {ComputedSignal} from '../core/computed-signal.js';
-import type {IReadonlySignal} from '../type.js';
-
-/**
- * Creates a new read-only computed signal that transforms the value of a source
- * signal using a projection function.
- *
- * This operator is analogous to `Array.prototype.map`. It applies a function to
- * each value emitted by the source signal and emits the result.
- *
- * @template T The type of the source signal's value.
- * @template R The type of the projected value.
- *
- * @param sourceSignal The original signal to transform.
- * @param projectFunction A function to apply to each value from the source signal.
- * @param [name] An optional, unique identifier for the new signal for debugging. default: `${sourceSignal.name}-mapped`
- *
- * @returns A new, read-only computed signal with the transformed values.
- *
- * @example
- * const userSignal = createStateSignal({
- *   name: 'user',
- *   initialValue: { name: 'John', age: 30 },
- * });
- *
- * const userNameSignal = createMappedSignal(
- *   userSignal,
- *   (user) => user.name,
- * );
- *
- * console.log(userNameSignal.get()); // Outputs: "John"
- * // in next macro-task ...
- * userSignal.set({ name: 'Jane', age: 32 });
- * console.log(userNameSignal.get()); // Outputs: "Jane"
- */
-export function createMappedSignal<T, R>(
-  sourceSignal: IReadonlySignal<T>,
-  projectFunction: (value: T) => R,
-  name = `${sourceSignal.name}-mapped`,
-): ComputedSignal<R> {
-  return createComputedSignal({
-    name: name,
-    deps: [sourceSignal],
-    get: () => projectFunction(sourceSignal.get()),
-  });
-}