✨ Signals finalization

src/signals-lib.js

@@ -1,4 +1,4 @@
-export const mark= Symbol.for("signal");
+export const mark= Symbol.for("Signal");
 
 export function isSignal(candidate){
 	try{ return Reflect.has(candidate, mark); }
@@ -12,10 +12,9 @@ export function S(value, actions){
 	const out= create();
 	watch(()=> out(value()));
 	return out;
+	//TODO is auto remove if used for args, if external listener needs also S.clear
 }
 S.action= function(signal, name, ...a){
-	if(!isSignal(signal))
-		throw new Error(`'${signal}' is not a signal!`);
 	const s= signal[mark], { actions }= s;
 	if(!actions || !Reflect.has(actions, name))
 		throw new Error(`'${signal}' has no action with name '${name}'!`);
@@ -23,16 +22,25 @@ S.action= function(signal, name, ...a){
 	if(s.skip) return Reflect.deleteProperty(s, "skip");
 	s.listeners.forEach(l=> l(s.value));
 };
-S.on= function on(signals, listener, options){
+S.on= function on(signals, listener, options= {}){
+	const { signal: as }= options;
+	if(as && as.aborted) return;
 	if(Array.isArray(signals)) return signals.forEach(s=> on(s, listener, options));
 	addSignalListener(signals, listener);
-	if(options && options.signal)
-		options.signal.addEventListener("abort", ()=> removeSignalListener(signals, listener));
+	if(as) as.addEventListener("abort", ()=> removeSignalListener(signals, listener));
 	//TODO cleanup when signal removed (also TODO)
 };
+S.symbols= {
+	signal: mark,
+	onclear: Symbol.for("Signal.onclear")
+};
 S.clear= function(...signals){
 	for(const signal of signals){
-		signal[mark].listeners.clear();
+		const s= signal[mark];
+		const { onclear }= S.symbols;
+		if(s.actions && s.actions[onclear])
+			s.actions[onclear].call(s);
+		s.listeners.clear();
 		Reflect.deleteProperty(signal, mark);
 	}
 };
@@ -48,13 +56,13 @@ export const signals_config= {
 		return attrS();
 	},
 	reactiveElement(signal, map){
-		const mark_start= document.createComment("<> #reactive");
-		const mark_end= document.createComment("</> #reactive");
+		const mark_start= document.createComment("<#reactive>");
+		const mark_end= document.createComment("</#reactive>");
 		const out= document.createDocumentFragment();
 		out.append(mark_start, mark_end);
-		const toEls= v=> {
+		const reRenderReactiveElement= v=> {
 			if(!mark_start.parentNode || !mark_end.parentNode)
-				return removeSignalListener(signal, toEls);
+				return removeSignalListener(signal, reRenderReactiveElement);
 			let els= map(v);
 			if(!Array.isArray(els))
 				els= [ els ];
@@ -63,8 +71,8 @@ export const signals_config= {
 				el_r.remove();
 			mark_start.after(...els);
 		};
-		addSignalListener(signal, toEls);
-		toEls(signal());
+		addSignalListener(signal, reRenderReactiveElement);
+		reRenderReactiveElement(signal());
 		return out;
 	}
 };

src/signals.d.ts

@@ -1,8 +1,34 @@
 export type Signal<V, A>= (set?: V)=> V & A;
 type Action<V>= (this: { value: V }, ...a: any[])=> typeof S._ | void;
+type SymbolOnclear= Symbol;
+type SymbolSignal= Symbol;
 type Actions<V>= Record<string, Action<V>>;
 interface S {
 	_: Symbol
+	/**
+	 * Simple example:
+	 * ```js
+	 * const hello= S("Hello Signal");
+	 * ```
+	 * …simple todo signal:
+	 * ```js
+	 * const todos= S([], {
+	 * 	add(v){ this.value.push(S(v)); },
+	 * 	remove(i){ this.value.splice(i, 1); },
+	 * 	[S.symbols.onclear](){ S.clear(...this.value); },
+	 * });
+	 * ```
+	 * …computed signal:
+	 * ```js
+	 * const name= S("Jan");
+	 * const surname= S("Andrle");
+	 * const fullname= S(()=> name()+" "+surname());
+	 * ```
+	 * @param value Initial signal value. Or function computing value from other signals.
+	 * @param actions Use to define actions on the signal. Such as add item to the array.
+	 *		There is also a reserved function `S.symbol.onclear` which is called when the signal is cleared
+	 *		by `S.clear`.
+	 * */
 	<V, A extends Actions<V>>(value: V, actions?: A): Signal<V, A>;
 	action<S extends Signal<any, Actions<any>>, A extends (S extends Signal<any, infer A> ? A : never), N extends keyof A>(
 		signal: S,
@@ -10,6 +36,10 @@ interface S {
 		...params: A[N] extends (...args: infer P)=> any ? P : never
 	): void;
 	clear(...signals: Signal<any, any>): void;
-	on<T>(signal: Signal<T, any>, onchange: (a: T)=> void, options?: AddEventListenerOptions): void
+	on<T>(signal: Signal<T, any>, onchange: (a: T)=> void, options?: AddEventListenerOptions): void;
+	symbols: {
+		signal: SymbolSignal;
+		onclear: SymbolOnclear;
+	}
 }
 export const S: S;