@xaendar/core 0.5.7 → 0.6.0

package/dist/xaendar-core.es.d.ts

@@ -2,10 +2,11 @@ import { AccessorDecorator } from '@xaendar/types';
 import { Beautify } from '@xaendar/types';
 import { ClassDecorator as ClassDecorator_2 } from '@xaendar/types';
 import { Constructor } from '@xaendar/types';
+import { EffectOptions } from '@xaendar/signals';
 import { NoArgsVoidFunction } from '@xaendar/types';
+import { NoArgsVoidFunction as NoArgsVoidFunction_2 } from '@xaendar/types';
 import { RequireOne } from '@xaendar/types';
 import { SignalOptions } from '@xaendar/signals';
-import { SignalOptions as SignalOptions_2 } from '@xaendar/signals';
 import { VoidFunction as VoidFunction_2 } from '@xaendar/types';
 
 /**
@@ -62,6 +63,73 @@ export declare type BaseWebComponentConstructor = Constructor<BaseWebComponent,
     observedAttributes: string[];
 }>;
 
+/**
+ * A read-only reactive value derived from other signals.
+ *
+ * Wraps {@link Signal.Computed} and is also callable as a function to read the
+ * current computed value.
+ *
+ * @template Value - The type of the computed value. Defaults to `any`.
+ */
+export declare type Computed<Value = any> = Signal.Computed<Value> & {
+    /**
+     * Reads the current computed value, recomputing it if any dependency changed.
+     *
+     * @returns The current value of type `Value`.
+     */
+    (): Value;
+};
+
+/**
+ * Creates a read-only computed signal.
+ *
+ * Returns a callable getter that reads the current value, augmented with the
+ * underlying {@link Signal.State} API.
+ *
+ * @template Value - The type of the computed value. Defaults to `any`.
+ * @param value - The initial value.
+ * @param options - Configuration options for the signal.
+ * @returns A {@link Computed} instance.
+ */
+export declare function computed<Value = any>(value: Value, options?: SignalOptions<Value>): Computed<Value>;
+
+/**
+ * Runs a side-effectful function and automatically re-runs it whenever any
+ * Signal read during its execution changes.
+ *
+ * Internally, `effect` wraps the user callback inside a `Computed` node
+ * (for dependency tracking) and observes it with a `Watcher` (for push
+ * notifications). When any tracked dependency changes, the `Watcher`
+ * schedules a microtask that re-evaluates the `Computed`, which in turn
+ * re-runs the user callback and re-registers the new set of dependencies.
+ *
+ * The returned disposer function stops the effect: it unwatches the internal
+ * `Computed` from the `Watcher`, severing all dependency subscriptions so
+ * the callback is never called again and the graph nodes can be
+ * garbage-collected.
+ *
+ * @example
+ * ```ts
+ * const count = new State(0);
+ *
+ * const stop = effect(() => {
+ *   console.log('count is', count.get());
+ * });
+ * // logs: "count is 0"
+ *
+ * count.set(1); // logs: "count is 1"
+ * count.set(2); // logs: "count is 2"
+ *
+ * stop();       // no more logs
+ * count.set(3); // silent
+ * ```
+ *
+ * @param fn - The side-effectful function to run. Any Signal read inside it
+ *   is tracked as a dependency.
+ * @returns A disposer function that, when called, permanently stops the effect.
+ */
+export declare function effect(fn: NoArgsVoidFunction_2, options?: EffectOptions): NoArgsVoidFunction_2;
+
 declare function Event_2<Class extends BaseWebComponent, Data = void>(options?: EventOptions): AccessorDecorator<Class, Output<Data>>;
 export { Event_2 as Event }
 
@@ -75,32 +143,34 @@ export declare type EventOptions = Beautify<RequireOne<Omit<CustomEventInit, 'de
  * It extends the base `State` signal with additional functionality to handle incoming values, such as those from HTML attributes or external sources,
  * and allows for optional transformation of these values before they are stored in the signal.
  */
-export declare class InputSignal<ActualValue = unknown, IncomingValue = ActualValue> extends Signal.State<ActualValue> {
-    /**
-     * Optional transform function to convert incoming values to the actual type stored in the signal.
-     */
-    private _transform?;
+export declare function input<ActualValue = unknown, IncomingValue = ActualValue>(value?: ActualValue, options?: InputSignalOptions<ActualValue, IncomingValue>): InputSignal<ActualValue, IncomingValue>;
+
+/**
+ * A reactive value sourced from outside the component (e.g. an attribute).
+ *
+ * Wraps {@link Signal.State} without its `set` method (inputs are not set
+ * directly) and is callable as a function to read the current value. An
+ * optional {@link InputSignalOptions.transform} can convert the incoming value
+ * into the actual stored value.
+ *
+ * @template ActualValue - The internal type stored by the signal. Defaults to `unknown`.
+ * @template IncomingValue - The raw type received from outside. Defaults to `ActualValue`.
+ */
+export declare type InputSignal<ActualValue = unknown, IncomingValue = ActualValue> = Omit<Signal.State<ActualValue>, 'set'> & {
     /**
-     * Creates a new `InputSignal` instance.
+     * Reads the current value of the input signal.
      *
-     * @param initialValue - The initial value of the signal.
-     * @param options - Optional configuration:
-     *   - `equals` — custom equality function; defaults to `Object.is`.
-     *   - `watched` — called when the signal gains its first sink.
-     *   - `unwatched` — called when the signal loses its last sink.
-     *   - `transform` — function to transform incoming values before setting the signal's value.
+     * @returns The current value of type `ActualValue`.
      */
-    constructor(value?: ActualValue, options?: SignalOptions<ActualValue> & {
-        transform?: (value: IncomingValue) => ActualValue;
-    });
+    (): ActualValue;
     /**
-     * Set a new value to the signal, applying the transform function if provided.
-     * @param newValue - The new value to set.
-     * @throws If `frozen` is `true` — writes are forbidden while a protected
-     * callback is executing.
+     * Creates a new input signal.
+     *
+     * @param value - The initial incoming value.
+     * @param options - Optional configuration, including a `transform` function.
      */
-    set(newValue: IncomingValue, symbol: symbol): void;
-}
+    new (value: IncomingValue, options?: InputSignalOptions<ActualValue, IncomingValue>): InputSignal<ActualValue, IncomingValue>;
+};
 
 /**
  * Options used to configure an `InputSignal`.
@@ -112,7 +182,7 @@ export declare class InputSignal<ActualValue = unknown, IncomingValue = ActualVa
  * @template ActualValue - The internal type stored by the signal. Defaults to `unknown`.
  * @template IncomingValue - The raw type received from outside (e.g. from an attribute). Defaults to `ActualValue`.
  */
-export declare type InputSignalOptions<ActualValue = unknown, IncomingValue = ActualValue> = SignalOptions_2<ActualValue> & {
+export declare type InputSignalOptions<ActualValue = unknown, IncomingValue = ActualValue> = SignalOptions<ActualValue> & {
     /**
      * Optional function to transform the incoming value before it is stored.
      *
@@ -185,6 +255,44 @@ declare type PropertyDecoratorOptionsWithRequired<ActualValue = unknown, Incomin
     required: true;
 };
 
+/**
+ * Creates a writable reactive signal.
+ *
+ * Returns a callable getter that reads the current value, augmented with the
+ * underlying {@link Signal.State} API and an `update` method to derive the next
+ * value from the previous one.
+ *
+ * @template T - The type of the stored value. Defaults to `any`.
+ * @param value - The initial value of the signal.
+ * @param options - Configuration options for the signal.
+ * @returns A {@link SignalType} instance.
+ */
+export declare function signal<T = any>(value: T, options?: SignalOptions<T>): Signal_2<T>;
+
+/**
+ * A writable reactive value.
+ *
+ * Wraps {@link Signal.State} and is also callable as a function to set a new
+ * value directly.
+ *
+ * @template Value - The type of the stored value. Defaults to `any`.
+ */
+declare type Signal_2<Value = any> = Signal.State<Value> & {
+    /**
+     * Sets a new value for the signal.
+     *
+     * @param value - The new value to store.
+     */
+    (value: Value): void;
+    /**
+     * Updates the signal value based on its previous value.
+     *
+     * @param updater - Function receiving the previous value and returning the next one.
+     */
+    update(updater: (prev: Value) => Value): void;
+};
+export { Signal_2 as Signal }
+
 /**
  * Decorator to define a web component
  * @param selector Name or names of the custom element

package/dist/xaendar-core.es.js

@@ -33,6 +33,25 @@ function Event(options) {
 //#region ../packages/core/src/costants.ts
 var INTERNAL_OBSERVED_ATTRIBUTES = `observedAttributes`;
 //#endregion
+//#region ../packages/core/src/signals/input/input-instance.symbol.ts
+/**
+* This file defines a unique symbol used to identify instances of input signals within the framework.
+* The symbol serves as a marker to ensure that only valid input signal instances are recognized and processed.
+*
+* @internal
+*/
+var INPUT_SIGNAL_INSTANCE_SYMBOL = Symbol(`InputSignalInstance`);
+/**
+* Type guard function to check if a given instance is an InputSignal.
+* This function checks for the presence of the INPUT_SIGNAL_INSTANCE_SYMBOL on the instance, 
+* which is set to true for valid InputSignal instances.
+* @param instance - The object to check for being an InputSignal instance.
+* @returns A boolean indicating whether the instance is an InputSignal.
+*/
+function isInputSignal(instance) {
+	return instance?.[INPUT_SIGNAL_INSTANCE_SYMBOL];
+}
+//#endregion
 //#region ../packages/core/src/signals/input/input-set.symbol.ts
 /**
 * This symbol is used to call the set method of the InputSignal
@@ -55,45 +74,29 @@ function assertPrivateContext(symbol) {
 	if (symbol !== INPUT_SIGNAL_SET_SYMBOL) throw new Error("Invalid symbol for InputSignal set method");
 }
 //#endregion
-//#region ../packages/core/src/signals/input/input.model.ts
+//#region ../packages/core/src/signals/input/input.ts
 /**
 * An `InputSignal` is a specialized `Signal.State` designed for use as a property signal in web components. 
 * It extends the base `State` signal with additional functionality to handle incoming values, such as those from HTML attributes or external sources, 
 * and allows for optional transformation of these values before they are stored in the signal.
 */
-var InputSignal = class extends Signal.State {
-	/**
-	* Optional transform function to convert incoming values to the actual type stored in the signal.
-	*/
-	_transform;
-	/**
-	* Creates a new `InputSignal` instance.
-	*
-	* @param initialValue - The initial value of the signal.
-	* @param options - Optional configuration:
-	*   - `equals` — custom equality function; defaults to `Object.is`.
-	*   - `watched` — called when the signal gains its first sink.
-	*   - `unwatched` — called when the signal loses its last sink.
-	*   - `transform` — function to transform incoming values before setting the signal's value.
-	*/
-	constructor(value, options) {
-		const transform = options?.transform;
-		delete options?.transform;
-		super(value, options);
-		this._transform = transform;
-	}
-	/**
-	* Set a new value to the signal, applying the transform function if provided.
-	* @param newValue - The new value to set.
-	* @throws If `frozen` is `true` — writes are forbidden while a protected
-	* callback is executing.
-	*/
-	set(newValue, symbol) {
+function input(value, options) {
+	const transform = options?.transform;
+	delete options?.transform;
+	const signal = new Signal.State(value, options);
+	const originalSet = signal.set;
+	const getter = function() {
+		signal.get();
+	};
+	Object.assign(getter, signal);
+	Object.assign(signal, { set(newValue, symbol) {
 		assertPrivateContext(symbol);
-		const transformedValue = this._transform ? this._transform(newValue) : newValue;
-		super.set(transformedValue);
-	}
-};
+		const transformedValue = transform ? transform(newValue) : newValue;
+		originalSet.call(signal, transformedValue);
+	} });
+	getter[INPUT_SIGNAL_INSTANCE_SYMBOL] = true;
+	return getter;
+}
 //#endregion
 //#region ../packages/core/src/decorators/property.decorator.ts
 var propertyDecoratorOptionsWithRequiredBrand = Symbol("PropertyDecoratorOptionsWithRequiredBrand");
@@ -110,7 +113,7 @@ function createPropertyDecorator(value, options) {
 			actualValue = value;
 			actualOptions = options;
 		} else actualOptions = value;
-		const signal = new InputSignal(actualValue, {
+		const signal = input(actualValue, {
 			equals: actualOptions?.equals,
 			watched: actualOptions?.watched,
 			unwatched: actualOptions?.unwatched,
@@ -241,7 +244,7 @@ var BaseWebComponent = class extends HTMLElement {
 	attributeChangedCallback(name, _oldValue, newValue) {
 		const context = this;
 		if (!(name in context)) throw new Error(`Attribute ${name} is not associated to any property`);
-		if (!(context[name] instanceof InputSignal)) throw new Error(`Property ${name} is not an InputSignal`);
+		if (!isInputSignal(context[name])) throw new Error(`Property ${name} is not an InputSignal`);
 		context[name].set(newValue, INPUT_SIGNAL_SET_SYMBOL);
 	}
 	/**
@@ -269,4 +272,128 @@ var BaseWebComponent = class extends HTMLElement {
 	}
 };
 //#endregion
-export { BaseWebComponent, Event, InputSignal, Property, WebComponent };
+//#region ../packages/core/src/signals/computed/computed.ts
+/**
+* Creates a read-only computed signal.
+*
+* Returns a callable getter that reads the current value, augmented with the
+* underlying {@link Signal.State} API.
+*
+* @template Value - The type of the computed value. Defaults to `any`.
+* @param value - The initial value.
+* @param options - Configuration options for the signal.
+* @returns A {@link Computed} instance.
+*/
+function computed(value, options) {
+	const signal = new Signal.State(value, options);
+	const getter = function() {
+		signal.get();
+	};
+	Object.assign(getter, signal);
+	return getter;
+}
+//#endregion
+//#region ../packages/core/src/signals/effect/effect.ts
+/**
+* Runs a side-effectful function and automatically re-runs it whenever any
+* Signal read during its execution changes.
+*
+* Internally, `effect` wraps the user callback inside a `Computed` node
+* (for dependency tracking) and observes it with a `Watcher` (for push
+* notifications). When any tracked dependency changes, the `Watcher`
+* schedules a microtask that re-evaluates the `Computed`, which in turn
+* re-runs the user callback and re-registers the new set of dependencies.
+*
+* The returned disposer function stops the effect: it unwatches the internal
+* `Computed` from the `Watcher`, severing all dependency subscriptions so
+* the callback is never called again and the graph nodes can be
+* garbage-collected.
+*
+* @example
+* ```ts
+* const count = new State(0);
+*
+* const stop = effect(() => {
+*   console.log('count is', count.get());
+* });
+* // logs: "count is 0"
+*
+* count.set(1); // logs: "count is 1"
+* count.set(2); // logs: "count is 2"
+*
+* stop();       // no more logs
+* count.set(3); // silent
+* ```
+*
+* @param fn - The side-effectful function to run. Any Signal read inside it
+*   is tracked as a dependency.
+* @returns A disposer function that, when called, permanently stops the effect.
+*/
+function effect(fn, options) {
+	/**
+	* Wrap the user callback in a Computed so that automatic dependency
+	* tracking (via pushComputed / popComputed) works for free.
+	* The Computed always returns `undefined` — we only care about the
+	* side-effects and the tracked sources, not the value.
+	*/
+	const computed = new Signal.Computed(() => fn());
+	let needsEnqueue = true;
+	/**
+	* The Watcher is notified synchronously as soon as any tracked dependency
+	* changes. Its job is purely to schedule the re-execution; the actual
+	* re-evaluation happens asynchronously in a microtask so that multiple
+	* synchronous signal updates are batched into a single re-run.
+	*/
+	const watcher = new Signal.subtle.Watcher(() => {
+		if (needsEnqueue) {
+			needsEnqueue = false;
+			queueMicrotask(() => {
+				needsEnqueue = true;
+				options?.onBeforeRun?.();
+				watcher.getPending().forEach((computed) => computed.get());
+				options?.onAfterRun?.();
+				watcher.watch();
+			});
+		}
+	});
+	options?.onBeforeRun?.();
+	watcher.watch(computed);
+	computed.get();
+	options?.onAfterRun?.();
+	/**
+	* Disposer — call this to permanently stop the effect.
+	*
+	* Unwatching the Computed tears down the entire live dependency chain
+	* (Watcher → Computed → all sources), preventing any further
+	* notifications and allowing GC.
+	*/
+	return () => {
+		options?.onCleanup?.();
+		watcher.unwatch(computed);
+	};
+}
+//#endregion
+//#region ../packages/core/src/signals/signal/signal.ts
+/**
+* Creates a writable reactive signal.
+*
+* Returns a callable getter that reads the current value, augmented with the
+* underlying {@link Signal.State} API and an `update` method to derive the next
+* value from the previous one.
+*
+* @template T - The type of the stored value. Defaults to `any`.
+* @param value - The initial value of the signal.
+* @param options - Configuration options for the signal.
+* @returns A {@link SignalType} instance.
+*/
+function signal(value, options) {
+	const signal = new Signal.State(value, options);
+	const getter = function() {
+		signal.get();
+	};
+	Object.assign(getter, signal);
+	Object.assign(getter, { update: (updater) => signal.set(updater(signal.get())) });
+	return getter;
+}
+//#endregion
+export { BaseWebComponent, Event, Property, WebComponent, computed, effect, input, signal };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xaendar/core",
-  "version": "0.5.7",
+  "version": "0.6.0",
   "description": "A library containing core utils such as webcomponent base classes and theming support",
   "sideEffects": false,
   "type": "module",
@@ -16,7 +16,7 @@
     }
   },
   "dependencies": {
-    "@xaendar/signals": "0.5.7",
-    "@xaendar/types": "0.5.7"
+    "@xaendar/signals": "0.6.0",
+    "@xaendar/types": "0.6.0"
   }
 }