xh123637 · Nov 5, 2026 · coderabbitai · Nov 5, 2026 · coderabbitai · Nov 5, 2026
diff --git a/packages/core/data/observable-array/index.ts b/packages/core/data/observable-array/index.ts
@@ -433,7 +433,7 @@ export interface ObservableArray<T> {
 	 * `this` context when the callback is called. Falsy values will be not be
 	 * bound.
 	 */
-	on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
+	on(eventName: string, callback: (data: EventData) => void, thisArg?: any): this;
 
-	on(event: 'change', callback: (args: ChangedData<T>) => void, thisArg?: any): void;
+	on(event: 'change', callback: (args: ChangedData<T>) => void, thisArg?: any): this;
 }
diff --git a/packages/core/data/observable/index.spec.ts b/packages/core/data/observable/index.spec.ts
@@ -145,6 +145,44 @@ describe('Observable', () => {
 		});
 	});
 
+	describe('returning this for chaining', () => {
+		it('on returns the observable', () => {
+			const observable = new Observable();
+			expect(observable.on('test', () => {})).toBe(observable);
+		});
+
+		it('once returns the observable', () => {
+			const observable = new Observable();
+			expect(observable.once('test', () => {})).toBe(observable);
+		});
+
+		it('off returns the observable', () => {
+			const observable = new Observable();
+			const handler = () => {};
+			observable.on('test', handler);
+			expect(observable.off('test', handler)).toBe(observable);
+		});
+
+		it('addEventListener and removeEventListener return the observable', () => {
+			const observable = new Observable();
+			const handler = () => {};
+			expect(observable.addEventListener('test', handler)).toBe(observable);
+			expect(observable.removeEventListener('test', handler)).toBe(observable);
+		});
+
+		it('chains on, once and off and still notifies the remaining listeners', () => {
+			const observable = new Observable();
+			const calls: string[] = [];
+			const first = () => calls.push('first');
+			const second = () => calls.push('second');
+			const third = () => calls.push('third');
+			observable.on('test', first).on('test', second).once('test', third).off('test', first);
+			observable.notify({ eventName: 'test', object: observable });
+			observable.notify({ eventName: 'test', object: observable });
+			expect(calls).toEqual(['second', 'third', 'second']);
+		});
+	});
+
 	describe('hasListeners', () => {
 		it('reflects listener registration and removal', () => {
 			const observable = new Observable();

diff --git a/packages/core/data/observable/index.ts b/packages/core/data/observable/index.ts
@@ -186,8 +186,10 @@ export class Observable {
 	 * `this` context when the callback is called. Falsy values will be not be
 	 * bound.
 	 */
-	public on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void {
+	public on(eventName: string, callback: (data: EventData) => void, thisArg?: any): this {
 		this.addEventListener(eventName, callback, thisArg);
+
+		return this;
 	}
 
 	/**
@@ -201,8 +203,10 @@ export class Observable {
 	 * `this` context when the callback is called. Falsy values will be not be
 	 * bound.
 	 */
-	public once(eventName: string, callback: (data: EventData) => void, thisArg?: any): void {
+	public once(eventName: string, callback: (data: EventData) => void, thisArg?: any): this {
 		this.addEventListener(eventName, callback, thisArg, true);
+
+		return this;
 	}
 
 	/**
@@ -214,8 +218,10 @@ export class Observable {
 	 * @param thisArg An optional parameter which, when set, will be used to
 	 * refine search of the correct event listener to be removed.
 	 */
-	public off(eventName: string, callback?: (data: EventData) => void, thisArg?: any): void {
+	public off(eventName: string, callback?: (data: EventData) => void, thisArg?: any): this {
 		this.removeEventListener(eventName, callback, thisArg);
+
+		return this;
 	}
 
 	/**
@@ -225,7 +231,7 @@ export class Observable {
 	 * @param thisArg An optional parameter which when set will be used as "this" in callback method call.
 	 * @param once An optional parameter which when set will cause the event listener to fire once.
 	 */
-	public addEventListener(eventName: string, callback: (data: EventData) => void, thisArg?: any, once?: boolean): void {
+	public addEventListener(eventName: string, callback: (data: EventData) => void, thisArg?: any, once?: boolean): this {
 		once = once || undefined;
 		thisArg = thisArg || undefined;
 
@@ -240,14 +246,16 @@ export class Observable {
 		const list = this._getEventList(eventName, true);
 		if (Observable._indexOfListener(list, callback, thisArg) !== -1) {
 			// Already added.
-			return;
+			return this;
 		}
 
 		list.push({
 			callback,
 			thisArg,
 			once,
 		});
+
+		return this;
 	}
 
 	/**
@@ -256,7 +264,7 @@ export class Observable {
 	 * @param callback An optional parameter pointing to a specific listener. If not defined, all listeners for the event names will be removed.
 	 * @param thisArg An optional parameter which when set will be used to refine search of the correct callback which will be removed as event listener.
 	 */
-	public removeEventListener(eventName: string, callback?: (data: EventData) => void, thisArg?: any): void {
+	public removeEventListener(eventName: string, callback?: (data: EventData) => void, thisArg?: any): this {
 		thisArg = thisArg || undefined;
 
 		if (typeof eventName !== 'string') {
@@ -269,7 +277,7 @@ export class Observable {
 
 		const entries = this._observers[eventName];
 		if (!entries) {
-			return;
+			return this;
 		}
 
 		Observable.innerRemoveEventListener(entries, callback, thisArg);
@@ -278,6 +286,8 @@ export class Observable {
 			// Clear all entries of this type
 			delete this._observers[eventName];
 		}
+
+		return this;
 	}
 
 	/**

diff --git a/packages/core/data/virtual-array/index.ts b/packages/core/data/virtual-array/index.ts
@@ -192,13 +192,13 @@ export interface VirtualArray<T> {
 	 * `this` context when the callback is called. Falsy values will be not be
 	 * bound.
 	 */
-	on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
+	on(eventName: string, callback: (data: EventData) => void, thisArg?: any): this;
 	/**
 	 * Raised when still not loaded items are requested.
 	 */
-	on(event: 'itemsLoading', callback: (args: ItemsLoading) => void, thisArg?: any): void;
+	on(event: 'itemsLoading', callback: (args: ItemsLoading) => void, thisArg?: any): this;
 	/**
 	 * Raised when a change occurs.
 	 */
-	on(event: 'change', callback: (args: ChangedData<T>) => void, thisArg?: any): void;
+	on(event: 'change', callback: (args: ChangedData<T>) => void, thisArg?: any): this;
 }
diff --git a/packages/core/media-query-list/index.ts b/packages/core/media-query-list/index.ts
@@ -109,7 +109,7 @@ class MediaQueryListImpl extends Observable implements MediaQueryList {
 	}
 
 	// @ts-ignore
-	public addEventListener(eventName: string, callback: (data: EventData) => void, thisArg?: any, once?: boolean): void {
+	public addEventListener(eventName: string, callback: (data: EventData) => void, thisArg?: any, once?: boolean): this {
 		this._throwInvocationError?.();
 
 		const hasChangeListeners = this.hasListeners(MediaQueryListImpl.changeEvent);
@@ -124,10 +124,12 @@ class MediaQueryListImpl extends Observable implements MediaQueryList {
 				toggleApplicationEventListeners(true, onDeviceChange);
 			}
 		}
+
+		return this;
 	}
 
 	// @ts-ignore
-	public removeEventListener(eventName: string, callback?: (data: EventData) => void, thisArg?: any): void {
+	public removeEventListener(eventName: string, callback?: (data: EventData) => void, thisArg?: any): this {
 		this._throwInvocationError?.();
 
 		// Call super method first since it throws in the case of bad parameters
@@ -147,6 +149,8 @@ class MediaQueryListImpl extends Observable implements MediaQueryList {
 				}
 			}
 		}
+
+		return this;
 	}
 
 	addListener(callback: (this: MediaQueryList, ev: MediaQueryListEvent) => any): void {