Merge pull request #2795 from sanderhahn/master

Add docstrings to store

src/store.ts

@@ -1,32 +1,64 @@
 import { run_all, noop, safe_not_equal, is_function } from './internal/utils';
 
+/** Callback to inform of a value updates. */
 type Subscriber<T> = (value: T) => void;
 
+/** Unsubscribes from value updates. */
 type Unsubscriber = () => void;
 
+/** Callback to update a value. */
 type Updater<T> = (value: T) => T;
 
+/** Cleanup logic callback. */
 type Invalidater<T> = (value?: T) => void;
 
+/** Start and stop notification callbacks. */
 type StartStopNotifier<T> = (set: Subscriber<T>) => Unsubscriber | void;
 
+/** Readable interface for subscribing. */
 export interface Readable<T> {
+	/**
+	 * Subscribe on value changes.
+	 * @param run subscription callback
+	 * @param invalidate cleanup callback
+	 */
 	subscribe(run: Subscriber<T>, invalidate?: Invalidater<T>): Unsubscriber;
 }
 
+/** Writable interface for both updating and subscribing. */
 export interface Writable<T> extends Readable<T> {
+	/**
+	 * Set value and inform subscribers.
+	 * @param value to set
+	 */
 	set(value: T): void;
+
+	/**
+	 * Update value using callback and inform subscribers.
+	 * @param updater callback
+	 */
 	update(updater: Updater<T>): void;
 }
 
+/** Pair of subscriber and invalidator. */
 type SubscribeInvalidateTuple<T> = [Subscriber<T>, Invalidater<T>];
 
+/**
+ * Creates a `Readable` store that allows reading by subscription.
+ * @param value initial value
+ * @param start start and stop notifications for subscriptions
+ */
 export function readable<T>(value: T, start: StartStopNotifier<T>): Readable<T> {
 	return {
 		subscribe: writable(value, start).subscribe,
 	};
 }
 
+/**
+ * Create a `Writable` store that allows both updating and reading by subscription.
+ * @param value initial value
+ * @param start start and stop notifications for subscriptions
+ */
 export function writable<T>(value: T, start: StartStopNotifier<T> = noop): Writable<T> {
 	let stop: Unsubscriber;
 	const subscribers: Array<SubscribeInvalidateTuple<T>> = [];
@@ -68,11 +100,20 @@ export function writable<T>(value: T, start: StartStopNotifier<T> = noop): Writa
 	return { set, update, subscribe };
 }
 
+/** One or more `Readable`s. */
 type Stores = Readable<any> | [Readable<any>, ...Array<Readable<any>>];
 
+/** One or more values from `Readable` stores. */
 type StoresValues<T> = T extends Readable<infer U> ? U :
 	{ [K in keyof T]: T[K] extends Readable<infer U> ? U : never };
 
+/**
+ * Derived value store by synchronizing one or more readable stores and
+ * applying an aggregation function over its input values.
+ * @param stores input stores
+ * @param fn function callback that aggregates the values
+ * @param initial_value when used asynchronously
+ */
 export function derived<T, S extends Stores>(
 	stores: S,
 	fn: (values: StoresValues<S>, set?: Subscriber<T>) => T | Unsubscriber | void,
@@ -129,6 +170,10 @@ export function derived<T, S extends Stores>(
 	});
 }
 
+/**
+ * Get the current value from a store by subscribing and immediately unsubscribing.
+ * @param store readable
+ */
 export function get<T>(store: Readable<T>): T {
 	let value: T | undefined;
 	store.subscribe((_: T) => value = _)();