grainjs 1.0.2 → 1.1.0

package/lib/kowrap.ts

@@ -65,10 +65,10 @@ export function fromKo<KObs extends IKnockoutObservable<any>>(koObs: KObs): Obse
 }
 
 /**
- * An Observable that wraps a Knockout observable, created via fromKo(). It keeps minimal overhead
+ * An Observable that wraps a Knockout observable, created via `fromKo()`. It keeps minimal overhead
  * when unused by only subscribing to the wrapped observable while it itself has subscriptions.
  *
- * This way, when unused, the only reference is from the wrapper to the wrapped object. KoWrapObs
+ * This way, when unused, the only reference is from the wrapper to the wrapped object. `KoWrapObs`
  * should not be disposed; its lifetime is tied to that of the wrapped object.
  */
 export class KoWrapObs<T> extends Observable<T> {
@@ -88,8 +88,11 @@ export class KoWrapObs<T> extends Observable<T> {
       }
     });
   }
+  /** @override */
   public get(): T { return this._koObs.peek(); }
+  /** @override */
   public set(value: T): void { bundleChanges(() => this._koObs(value)); }
+  /** @override */
   public dispose(): void { throw new Error("KoWrapObs should not be disposed"); }
 }
 

package/lib/obsArray.ts

@@ -1,36 +1,3 @@
-/**
- * ObsArray extends a plain Observable to allow for more efficient observation of array changes.
- *
- * As for any array-valued Observable, when the contents of the observed array changes, the
- * listeners get called with new and previous values which are the same array. For simple changes,
- * such as those made with .push() and .splice() methods, ObsArray allows for more efficient
- * handling of the change by calling listeners with splice info in the third argument.
- *
- * This module also provides computedArray(), which allows mapping each item of an ObsArray
- * through a function, passing through splice info for efficient handling of small changes. It
- * also allows mapping an observable or a computed whose value is an ObsArray.
- *
- * There is no need or benefit in using computedArray() if you have a computed() that returns a
- * plain array. It is specifically for the case when you want to preserve the efficiency of
- * ObsArray when you map its values.
- *
- * Both ObsArray and ComputedArray may be used with disposable elements as their owners. E.g.
- *
- *    const arr = obsArray<D>();
- *    arr.push(D.create(arr, "x"), D.create(arr, "y"));
- *    arr.pop();      // Element "y" gets disposed.
- *    arr.dispose();  // Element "x" gets disposed.
- *
- *    const values = obsArray<string>();
- *    const compArr = computedArray<D>(values, (val, i, compArr) => D.create(compArr, val));
- *    values.push("foo", "bar");      // D("foo") and D("bar") get created
- *    values.pop();                   // D("bar") gets disposed.
- *    compArr.dispose();              // D("foo") gets disposed.
- *
- * Note that only the pattern above works: obsArray (or compArray) may only be used to take
- * ownership of those disposables that are added to it as array elements.
- */
-
 import {IDisposable, IDisposableOwnerT, setDisposeOwner} from './dispose';
 import {Listener} from './emit';
 import {BaseObservable, Observable} from './observable';
@@ -48,7 +15,7 @@ export type MaybeObsArray<T> = BaseObservable<T[]> | T[];
  * completely.
  */
 export interface IObsArraySplice<T> {
-  start: number;
+  start: number;        /** asdf */
   numAdded: number;
   deleted: T[];
 }
@@ -56,24 +23,50 @@ export interface IObsArraySplice<T> {
 export type ISpliceListener<T, C>  = (this: C, val: T[], prev: T[], change?: IObsArraySplice<T>) => void;
 
 /**
- * ObsArray<T> is essentially an array-valued observable. The main difference is that it may be
+ * `ObsArray<T>` is essentially an array-valued observable. It extends a plain Observable to allow
+ * for more efficient observation of array changes. It also may be
  * used as an owner for disposable array elements.
+ *
+ * As for any array-valued `Observable`, when the contents of the observed array changes, the
+ * listeners get called with new and previous values which are the same array. For simple changes,
+ * such as those made with `.push()` and `.splice()` methods, `ObsArray` allows for more efficient
+ * handling of the change by calling listeners with splice info in the third argument.
+ *
+ * `ObsArray` may be used with disposable elements as their owner. E.g.
+ * ```ts
+ * const arr = obsArray<D>();
+ * arr.push(D.create(arr, "x"), D.create(arr, "y"));
+ * arr.pop();      // Element "y" gets disposed.
+ * arr.dispose();  // Element "x" gets disposed.
+ * ```
+ *
+ * Note that only the pattern above works: `obsArray` may only be used to take
+ * ownership of those disposables that are added to it as array elements.
  */
 export class ObsArray<T> extends BaseObservable<T[]> {
   private _ownedItems?: Set<T & IDisposable> = undefined;
 
+  /**
+   * Adds a callback to listen to changes in the observable. In case of `ObsArray`, the listener
+   * gets additional information.
+   */
   public addListener(callback: ISpliceListener<T, void>): Listener;
   public addListener<C>(callback: ISpliceListener<T, C>, context: C): Listener;
   public addListener(callback: ISpliceListener<T, any>, optContext?: any): Listener {
     return super.addListener(callback, optContext);
   }
 
+  /**
+   * Take ownership of an item added to this array. This should _only_ be used for array elements,
+   * not any unrelated items.
+   */
   public autoDispose(value: T & IDisposable): T & IDisposable {
     if (!this._ownedItems) { this._ownedItems = new Set<T & IDisposable>(); }
     this._ownedItems.add(value);
     return value;
   }
 
+  /** @override */
   public dispose(): void {
     if (this._ownedItems) {
       for (const item of this.get() as Array<T & IDisposable>) {
@@ -86,10 +79,12 @@ export class ObsArray<T> extends BaseObservable<T[]> {
     super.dispose();
   }
 
+  /** @internal */
   protected _setWithSplice(value: T[], splice: IObsArraySplice<T>): void {
     return this._setWithArg(value, splice);
   }
 
+  /** @internal */
   protected _disposeOwned(splice?: IObsArraySplice<T>): void {
     if (!this._ownedItems) { return; }
     if (splice) {
@@ -117,10 +112,11 @@ export class ObsArray<T> extends BaseObservable<T[]> {
 }
 
 /**
- * MutableObsArray<T> adds array-like mutation methods which emit events with splice info, to
- * allow more efficient processing of such changes. It is created with obsArray<T>().
+ * `MutableObsArray<T>` adds array-like mutation methods which emit events with splice info, to
+ * allow more efficient processing of such changes. It is created with `obsArray<T>()`.
  */
 export class MutableObsArray<T> extends ObsArray<T> {
+  /** Appends elements to the end and returns the new length (like `Array#push`). */
   public push(...args: T[]): number {
     const value = this.get();
     const start = value.length;
@@ -129,6 +125,7 @@ export class MutableObsArray<T> extends ObsArray<T> {
     return newLen;
   }
 
+  /** Removes and returns the last element (like `Array#pop`). */
   public pop(): T|undefined {
     const value = this.get();
     if (value.length === 0) { return undefined; }
@@ -137,6 +134,7 @@ export class MutableObsArray<T> extends ObsArray<T> {
     return ret;
   }
 
+  /** Prepends elements to the start and returns the new length (like `Array#unshift`). */
   public unshift(...args: T[]) {
     const value = this.get();
     const newLen = value.unshift(...args);
@@ -144,6 +142,7 @@ export class MutableObsArray<T> extends ObsArray<T> {
     return newLen;
   }
 
+  /** Removes and returns the first element (like `Array#shift`). */
   public shift(): T|undefined {
     const value = this.get();
     if (value.length === 0) { return undefined; }
@@ -152,6 +151,10 @@ export class MutableObsArray<T> extends ObsArray<T> {
     return ret;
   }
 
+  /**
+   * Removes and/or inserts elements at a given index and returns the removed elements (like
+   * `Array#splice`).
+   */
   public splice(start: number, deleteCount: number = Infinity, ...newValues: T[]) {
     const value = this.get();
     const len = value.length;
@@ -164,7 +167,7 @@ export class MutableObsArray<T> extends ObsArray<T> {
 
 /**
  * Creates a new MutableObsArray with an optional initial value, defaulting to the empty array.
- * It is essentially the same as observable<T[]>, but with array-like mutation methods.
+ * It is essentially the same as `observable<T[]>`, but with array-like mutation methods.
  */
 export function obsArray<T>(value: T[] = []): MutableObsArray<T> {
   return new MutableObsArray<T>(value);
@@ -178,7 +181,7 @@ function isObsArray(val: BaseObservable<any>): val is BaseObservable<any[]> {
 }
 
 /**
- * See computedArray() below for documentation.
+ * See [`computedArray()`](#computedArray) for documentation.
  */
 export class ComputedArray<T, U> extends ObsArray<U> {
   private _sub: Subscription;
@@ -196,6 +199,7 @@ export class ComputedArray<T, U> extends ObsArray<U> {
       subscribe(obsArr, (use, obsArrayValue) => { use(obsArrayValue); return this._syncMap(obsArrayValue); });
   }
 
+  /** @internal */
   public dispose() {
     this._unsync();
     this._sub.dispose();
@@ -254,25 +258,43 @@ export class ComputedArray<T, U> extends ObsArray<U> {
 }
 
 /**
- * Returns an ObsArray that maps all elements of the passed-in ObsArray through a mapper function.
- * Also accepts an observable (e.g. a computed) whose value is an ObsArray. Usage:
- *
- *    computedArray(obsArray, mapper)
- *
- * The result is entirely analogous to:
+ * Returns an `ObsArray` that maps all elements of the passed-in `ObsArray` through a mapper
+ * function. Also accepts an observable (e.g. a computed) whose value is an `ObsArray`.
+ * ```ts
+ * computedArray(obsArray, mapper)
+ * ```
  *
- *     computed((use) => use(obsArray).map(mapper))       // for ObsArray
- *     computed((use) => use(use(obsArray)).map(mapper))  // for Observable<ObsArray>
+ * The result is analogous to:
+ * ```ts
+ * computed((use) => use(obsArray).map(mapper))       // for ObsArray
+ * computed((use) => use(use(obsArray)).map(mapper))  // for Observable<ObsArray>
+ * ```
  *
- * The benefit of computedArray() is that a small change to the source array (e.g. one item
+ * The benefit of `computedArray()` is that a small change to the source array (e.g. one item
  * added or removed), causes a small change to the mapped array, rather than a full rebuild.
  *
- * This is useful with an ObsArray or with an observable whose value is an ObsArray, and also
- * when the computed array owns its disposable items.
+ * This is useful with an `ObsArray` or with an observable whose value is an `ObsArray`, and also
+ * when the computed array's items are disposable and it owns them.
  *
- * Note that the mapper function is called with (item, index, array) as for a standard
- * array.map(), but that the index is only accurate at the time of the call, and will stop
+ * There is no need or benefit to using `computedArray()` if you have a `computed()` that returns
+ * a plain array. It is specifically for the case when you want to preserve the efficiency of
+ * `ObsArray` when you map its values.
+ *
+ * Note that the mapper function is called with `(item, index, array)` as for a standard
+ * `array.map()`, but that the index is only accurate at the time of the call, and will stop
  * reflecting the true index if more items are inserted into the array later.
+ *
+ * As with `ObsArray`, a `ComputedArray` may be used with disposable elements as their owners. E.g.
+ * ```ts
+ * const values = obsArray<string>();
+ * const compArr = computedArray<D>(values, (val, i, compArr) => D.create(compArr, val));
+ * values.push("foo", "bar");      // D("foo") and D("bar") get created
+ * values.pop();                   // D("bar") gets disposed.
+ * compArr.dispose();              // D("foo") gets disposed.
+ * ```
+ *
+ * Note that only the pattern above works: obsArray (or compArray) may only be used to take
+ * ownership of those disposables that are added to it as array elements.
  */
 export function computedArray<T, U>(
   obsArr: BaseObservable<T[]> | Observable<BaseObservable<T[]>>,
@@ -296,6 +318,9 @@ export function makeLiveIndex<T>(owner: IDisposableOwnerT<LiveIndex>|null, obsAr
   return setDisposeOwner(owner, new LiveIndex(obsArr, initialIndex));
 }
 
+/**
+ * An Observable that represents an index into an `ObsArray`, clamped to be in the valid range.
+ */
 export class LiveIndex extends Observable<number|null> {
   private _listener: Listener;
   private _isLive: boolean = true;
@@ -306,18 +331,28 @@ export class LiveIndex extends Observable<number|null> {
     this._listener = _obsArray.addListener(this._onArrayChange, this);
   }
 
+  /**
+   * Set the index, clamping it to a valid value.
+   */
   public set(index: number|null) {
     // Clamp to [0, len) range of the observable array.
     const len = this._obsArray.get().length;
     super.set(len === 0 ? null : Math.max(0, Math.min(len - 1, index || 0)));
   }
 
-  // Note that this feature comes from a rather obscure need, and it would be better if something
-  // similar were possible without making it an explicit feature.
+  /**
+   * Turn "liveness" on or off. While set to false, the observable will not be adjusted as the
+   * array changes, except to keep it valid.
+   *
+   * @privateRemarks
+   * Note that this feature comes from a rather obscure need, and it would be better if something
+   * similar were possible without making it an explicit feature.
+   */
   public setLive(value: boolean): void {
     this._isLive = value;
   }
 
+  /** @override */
   public dispose() {
     this._listener.dispose();
     super.dispose();

package/lib/observable.ts

@@ -27,13 +27,14 @@ import {Emitter, Listener} from './emit';
 
 export {bundleChanges} from './_computed_queue';
 
+/**
+ * Base class for several variants of observable values.
+ */
 export class BaseObservable<T> {
   private _onChange: Emitter;
   private _value: T;
 
-  /**
-   * Internal constructor for an Observable. You should use observable() function instead.
-   */
+  // Internal constructor for an Observable. You should use observable() function instead.
   constructor(value: T) {
     this._onChange = new Emitter();
     this._value = value;
@@ -42,14 +43,14 @@ export class BaseObservable<T> {
   /**
    * Returns the value of the observable. It is fast and does not create a subscription.
    * (It is similar to knockout's peek()).
-   * @returns {Object} The current value of the observable.
+   * @returns The current value of the observable.
    */
   public get(): T { return this._value; }
 
   /**
    * Sets the value of the observable. If the value differs from the previously set one, then
    * listeners to this observable will get called with (newValue, oldValue) as arguments.
-   * @param {Object} value: The new value to set.
+   * @param value - The new value to set.
    */
   public set(value: T): void {
     if (value !== this._value) {
@@ -70,9 +71,9 @@ export class BaseObservable<T> {
 
   /**
    * Adds a callback to listen to changes in the observable.
-   * @param {Function} callback: Function, called on changes with (newValue, oldValue) arguments.
-   * @param {Object} optContext: Context for the function.
-   * @returns {Listener} Listener object. Its dispose() method removes the callback.
+   * @param callback - Function, called on changes with (newValue, oldValue) arguments.
+   * @param optContext - Context for the function.
+   * @returns Listener object. Its dispose() method removes the callback.
    */
   public addListener(callback: (val: T, prev: T) => void, optContext?: object): Listener {
     return this._onChange.addListener(callback, optContext);
@@ -88,7 +89,7 @@ export class BaseObservable<T> {
   /**
    * Sets a single callback to be called when a listener is added or removed. It overwrites any
    * previously-set such callback.
-   * @param {Function} changeCB(hasListeners): Function to call after a listener is added or
+   * @param changeCB - Function to call after a listener is added or
    *    removed. It's called with a boolean indicating whether this observable has any listeners.
    *    Pass in `null` to unset the callback. Note that it can be called multiple times in a row
    *    with hasListeners `true`.
@@ -100,6 +101,7 @@ export class BaseObservable<T> {
   /**
    * Used by subscriptions to keep track of dependencies. An observable that has dependnecies,
    * such as a computed observable, would override this method.
+   * @internal
    */
   public _getDepItem(): DepItem|null {
     return null;
@@ -121,11 +123,13 @@ export class BaseObservable<T> {
     return this._onChange.isDisposed();
   }
 
+  /** @internal */
   protected _disposeOwned(arg?: any) { /* noop */ }
 
   /**
    * Allow derived classes to emit change events with an additional third argument describing the
    * change. It always emits the event without checking for value equality.
+   * @internal
    */
   protected _setWithArg(value: T, arg: any) {
     const prev = this._value;
@@ -136,7 +140,11 @@ export class BaseObservable<T> {
   }
 }
 
+/**
+ * An Observable holds a value and allows subscribing to changes.
+ */
 export class Observable<T> extends BaseObservable<T> implements IDisposableOwnerT<T & IDisposable> {
+  /** @internal */
   // See module-level holder() function below for documentation.
   public static holder<T>(value: T & IDisposable): Observable<T> {
     const obs = new Observable<T>(value);
@@ -168,6 +176,7 @@ export class Observable<T> extends BaseObservable<T> implements IDisposableOwner
     return value;
   }
 
+  /** @internal */
   protected _disposeOwned() {
     if (this._owned) {
       this._owned.dispose();
@@ -178,8 +187,8 @@ export class Observable<T> extends BaseObservable<T> implements IDisposableOwner
 
 /**
  * Creates a new Observable with the initial value of optValue if given or undefined if omitted.
- * @param {Object} optValue: The initial value to set.
- * @returns {Observable} The newly created observable.
+ * @param optValue - The initial value to set.
+ * @returns The newly created observable.
  */
 export function observable<T>(value: T): Observable<T> {
   return new Observable<T>(value);
@@ -187,16 +196,18 @@ export function observable<T>(value: T): Observable<T> {
 
 /**
  * Creates a new Observable with an initial disposable value owned by this observable, e.g.
- *
+ * ```
  *    const obs = obsHolder<D>(D.create(null, ...args));
+ * ```
  *
- * This is needed because using simply observable<D>(value) would not cause the observable to take
+ * This is needed because using simply `observable<D>(value)` would not cause the observable to take
  * ownership of value (i.e. to dispose it later). This function is a less hacky equivalent to:
- *
+ * ```
  *    const obs = observable<D>(null as any);
  *    D.create(obs, ...args);
+ * ```
  *
- * To allow nulls, use observable<D|null>(null); then the obsHolder() constructor is not needed.
+ * To allow nulls, use `observable<D|null>(null)`; then the obsHolder() constructor is not needed.
  */
 export function obsHolder<T>(value: T & IDisposable): Observable<T> {
   return Observable.holder<T>(value);

package/lib/pureComputed.ts

@@ -1,15 +1,3 @@
-/**
- * pureComputed.js implements a variant of computed() suitable for use with a pure read function
- * (free of side-effects). A pureComputed is only subscribed to its dependencies when something is
- * subscribed to it. At other times, it is not subscribed to anything, and calls to `get()` will
- * recompute its value each time by calling its read() function.
- *
- * Its syntax and usage are otherwise exactly as for a computed.
- *
- * In addition to being cheaper when unused, a pureComputed() also avoids leaking memory when
- * unused (since it's not registered with dependencies), so it is not necessary to dispose it.
- */
-
 import {DepItem} from './_computed_queue';
 import {IKnockoutReadObservable} from './kowrap';
 import {BaseObservable, Observable} from './observable';
@@ -26,6 +14,17 @@ function _useFunc<T>(obs: BaseObservable<T>|IKnockoutReadObservable<T>): T {
 // Constant empty array, which we use to avoid allocating new read-only empty arrays.
 const emptyArray: ReadonlyArray<any> = [];
 
+/**
+ * `PureComputed` is a variant of `Computed` suitable for use with a pure read function
+ * (free of side-effects). A `PureComputed` is only subscribed to its dependencies when something is
+ * subscribed to it. At other times, it is not subscribed to anything, and calls to `get()` will
+ * recompute its value each time by calling its `read()` function.
+ *
+ * Its syntax and usage are otherwise exactly as for a `Computed`.
+ *
+ * In addition to being cheaper when unused, a `PureComputed` also avoids leaking memory when
+ * unused (since it's not registered with dependencies), so it is not necessary to dispose it.
+ */
 export class PureComputed<T> extends Observable<T> {
   private _callback: (use: UseCB, ...args: any[]) => T;
   private _write: (value: T) => void;
@@ -33,9 +32,7 @@ export class PureComputed<T> extends Observable<T> {
   private readonly _dependencies: ReadonlyArray<ISubscribableObs>;
   private _inCall: boolean;
 
-  /**
-   * Internal constructor for a PureComputed. You should use pureComputed() function instead.
-   */
+  // Internal constructor for a PureComputed. You should use pureComputed() function instead.
   constructor(callback: (use: UseCB, ...args: any[]) => T, dependencies: ReadonlyArray<ISubscribable>) {
     // At initialization we force an undefined value even though it's not of type T: it's not
     // actually used as get() is overridden.
@@ -48,11 +45,13 @@ export class PureComputed<T> extends Observable<T> {
     this.setListenerChangeCB(this._onListenerChange, this);
   }
 
+  /** @internal */
   public _getDepItem(): DepItem {
     this._activate();
     return this._sub!._getDepItem();
   }
 
+  /** @override */
   public get(): T {
     if (!this._sub && !this._inCall) {
       // _inCall member prevents infinite recursion.
@@ -74,7 +73,7 @@ export class PureComputed<T> extends Observable<T> {
   /**
    * "Sets" the value of the pure computed by calling the write() callback if one was provided in
    * the constructor. Throws an error if there was no such callback (not a "writable" computed).
-   * @param {Object} value: The value to pass to the write() callback.
+   * @param value - The value to pass to the write() callback.
    */
   public set(value: T): void { this._write(value); }
 
@@ -121,9 +120,7 @@ export class PureComputed<T> extends Observable<T> {
 }
 
 /**
- * This is the type-checking interface for pureComputed(), which allows TypeScript to do helpful
- * type-checking when using it. We can only support a fixed number of argumnets (explicit
- * dependencies), but 5 should almost always be enough.
+ * Creates and returns a new PureComputed. The interface is identical to that of a Computed.
  */
 export function pureComputed<T>(cb: (use: UseCB) => T): PureComputed<T>;
 
@@ -147,9 +144,6 @@ export function pureComputed<A, B, C, D, E, T>(
     a: Observable<A>, b: Observable<B>, c: Observable<C>, d: Observable<D>, e: Observable<E>,
     cb: (use: UseCB, a: A, b: B, c: C, d: D, e: E) => T): PureComputed<T>;
 
-/**
- * Creates and returns a new PureComputed. The interface is identical to that of a Computed.
- */
 export function pureComputed(...args: any[]): PureComputed<any> {
   const readCb = args.pop();
   // The cast helps ensure that Observable is compatible with ISubscribable abstraction that we use.