Observable implementation bugfix + docs

Author: hediet

src/vs/base/common/observableImpl/autorun.ts

@@ -23,6 +23,41 @@ export function autorunHandleChanges<TChangeSummary>(
 	return new AutorunObserver(debugName, fn, options.createEmptyChangeSummary, options.handleChange);
 }
 
+// TODO@hediet rename to autorunWithStore
+export function autorunWithStore2(
+	debugName: string,
+	fn: (reader: IReader, store: DisposableStore) => void,
+): IDisposable {
+	return autorunWithStore(fn, debugName);
+}
+
+export function autorunWithStoreHandleChanges<TChangeSummary>(
+	debugName: string,
+	options: {
+		createEmptyChangeSummary?: () => TChangeSummary;
+		handleChange: (context: IChangeContext, changeSummary: TChangeSummary) => boolean;
+	},
+	fn: (reader: IReader, changeSummary: TChangeSummary, store: DisposableStore) => void
+): IDisposable {
+	const store = new DisposableStore();
+	const disposable = autorunHandleChanges(
+		debugName,
+		{
+			createEmptyChangeSummary: options.createEmptyChangeSummary,
+			handleChange: options.handleChange,
+		},
+		(reader, changeSummary) => {
+			store.clear();
+			fn(reader, changeSummary, store);
+		}
+	);
+	return toDisposable(() => {
+		disposable.dispose();
+		store.dispose();
+	});
+}
+
+// TODO@hediet deprecate, rename to autorunWithStoreEx
 export function autorunWithStore(
 	fn: (reader: IReader, store: DisposableStore) => void,
 	debugName: string

src/vs/base/common/observableImpl/base.ts

@@ -7,6 +7,11 @@ import { IDisposable } from 'vs/base/common/lifecycle';
 import type { derived } from 'vs/base/common/observableImpl/derived';
 import { getLogger } from 'vs/base/common/observableImpl/logging';
 
+/**
+ * Represents an observable value.
+ * @template T The type of the value.
+ * @template TChange The type of delta information (usually `void` and only used in advanced scenarios).
+ */
 export interface IObservable<T, TChange = unknown> {
 	/**
 	 * Returns the current value.
@@ -248,6 +253,10 @@ export function getFunctionName(fn: Function): string | undefined {
 export interface ISettableObservable<T, TChange = void> extends IObservable<T, TChange>, ISettable<T, TChange> {
 }
 
+/**
+ * Creates an observable value.
+ * Observers get informed when the value changes.
+ */
 export function observableValue<T, TChange = void>(name: string, initialValue: T): ISettableObservable<T, TChange> {
 	return new ObservableValue(name, initialValue);
 }

src/vs/base/common/observableImpl/utils.ts

@@ -198,6 +198,9 @@ class FromEventObservableSignal extends BaseObservable<void> {
 	}
 }
 
+/**
+ * Creates a signal that can be triggered to invalidate observers.
+ */
 export function observableSignal<TDelta = void>(
 	debugName: string
 ): IObservableSignal<TDelta> {
@@ -287,6 +290,10 @@ export function wasEventTriggeredRecently(event: Event<any>, timeoutMs: number,
 export function keepAlive(observable: IObservable<any>, forceRecompute?: boolean): IDisposable {
 	const o = new KeepAliveObserver(forceRecompute ?? false);
 	observable.addObserver(o);
+	if (forceRecompute) {
+		observable.reportChanges();
+	}
+
 	return toDisposable(() => {
 		observable.removeObserver(o);
 	});