grainjs 1.0.2 → 1.1.0

package/dist/esm/lib/computed.js

@@ -1,48 +1,57 @@
+import { setDisposeOwner } from './dispose';
+import { Observable } from './observable';
+import { Subscription } from './subscribe';
+function _noWrite() {
+    throw new Error("Can't write to non-writable computed");
+}
 /**
- * computed.js implements a computed observable, whose value depends on other observables and gets
+ * `Computed` implements a computed observable, whose value depends on other observables and gets
  * recalculated automatically when they change.
  *
- * E.g. if we have some existing observables (which may themselves be instances of `computed`),
+ * E.g. if we have some existing observables (which may themselves be instances of `Computed`),
  * we can create a computed that subscribes to them explicitly:
- *  let obs1 = observable(5), obs2 = observable(12);
- *  let computed1 = computed(obs1, obs2, (use, v1, v2) => v1 + v2);
+ * ```ts
+ * const obs1 = Observable.create(null, 5), obs2 = Observable.create(null, 12);
+ * const computed1 = Computed.create(null, obs1, obs2, (use, v1, v2) => v1 + v2);
+ * ```
  *
  * or implicitly by using `use(obs)` function:
- *  let computed2 = computed(use => use(obs1) + use(obs2));
+ * ```ts
+ * const computed2 = Computed.create(null, use => use(obs1) + use(obs2));
+ * ```
  *
- * In either case, computed1.get() and computed2.get() will have the value 17. If obs1 or obs2 is
- * changed, computed1 and computed2 will get recomputed automatically.
+ * In either case, `computed1.get()` and `computed2.get()` will have the value 17. If `obs1` or
+ * `obs2` is changed, `computed1` and `computed2` will get recomputed automatically.
  *
  * Creating a computed allows any number of dependencies to be specified explicitly, and their
- * values will be passed to the read() callback. These may be combined with automatic dependencies
- * detected using use(). Note that constructor dependencies have less overhead.
- *
- *  let val = computed(...deps, ((use, ...depValues) => READ_CALLBACK));
+ * values will be passed to the `read()` callback. These may be combined with automatic dependencies
+ * detected using `use()`. Note that constructor dependencies have less overhead.
+ * ```ts
+ * const val = Computed.create(null, ...deps, ((use, ...depValues) => READ_CALLBACK));
+ * ```
  *
  * You may specify a `write` callback by calling `onWrite(WRITE_CALLBACK)`, which will be called
- * whenever set() is called on the computed by its user. If a `write` bacllback is not specified,
+ * whenever `set()` is called on the computed by its user. If a `write` bacllback is not specified,
  * calling `set` on a computed observable will throw an exception.
  *
- * Note that pureComputed.js offers a variation of computed() with the same interface, but which
+ * Note that `PureComputed` offers a variation of `Computed` with the same interface, but which
  * stays unsubscribed from dependencies while it itself has no subscribers.
  *
  * A computed may be used with a disposable value using `use.owner` as the value's owner. E.g.
- *    let val = computed((use) => Foo.create(use.owner, use(a), use(b)));
+ * ```ts
+ * const val = Computed.create(null, ((use) => Foo.create(use.owner, use(a), use(b)));
+ * ```
  *
- * When the computed() is re-evaluated, and when it itself is disposed, it disposes the previously
- * owned value. Note that only the pattern above works, i.e. use.owner may only be used to take
+ * When the `Computed` is re-evaluated, and when it itself is disposed, it disposes the previously
+ * owned value. Note that only the pattern above works, i.e. `use.owner` may only be used to take
  * ownership of the same disposable that the callback returns.
  */
-import { setDisposeOwner } from './dispose';
-import { Observable } from './observable';
-import { Subscription } from './subscribe';
-function _noWrite() {
-    throw new Error("Can't write to non-writable computed");
-}
 export class Computed extends Observable {
-    /**
-     * Internal constructor for a Computed observable. You should use computed() function instead.
-     */
+    static create(owner, ...args) {
+        const readCb = args.pop();
+        return setDisposeOwner(owner, new Computed(readCb, args));
+    }
+    // Internal constructor for a Computed observable. You should use computed() function instead.
     constructor(callback, dependencies) {
         // At initialization we force an undefined value even though it's not of type T: it gets set
         // to a proper value during the creation of new Subscription, which calls this._read.
@@ -51,22 +60,9 @@ export class Computed extends Observable {
         this._write = _noWrite;
         this._sub = new Subscription(this._read.bind(this), dependencies, this);
     }
-    /**
-     * Creates a new Computed, owned by the given owner.
-     * @param owner: Object to own this Computed, or null to handle disposal manually.
-     * @param ...observables: Zero or more observables on which this computes depends. The callback
-     *        will get called when any of these changes.
-     * @param callback: Read callback that will be called with (use, ...values),
-     *    i.e. the `use` function and values for all of the ...observables. The callback is called
-     *    immediately and whenever any dependency changes.
-     * @returns {Computed} The newly created computed observable.
-     */
-    static create(owner, ...args) {
-        const readCb = args.pop();
-        return setDisposeOwner(owner, new Computed(readCb, args));
-    }
     /**
      * Used by subscriptions to keep track of dependencies.
+     * @internal
      */
     _getDepItem() {
         return this._sub._getDepItem();
@@ -74,7 +70,7 @@ export class Computed extends Observable {
     /**
      * "Sets" the value of the 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.
      */
     set(value) { this._write(value); }
     /**
@@ -96,16 +92,6 @@ export class Computed extends Observable {
         super.set(this._callback(use, ...args));
     }
 }
-/**
- * Creates a new Computed.
- * @param {Observable} ...observables: The initial params, of which there may be zero or more, are
- *    observables on which this computed depends. When any of them change, the read() callback
- *    will be called with the values of these observables as arguments.
- * @param {Function} readCallback: Read callback that will be called with (use, ...values),
- *    i.e. the `use` function and values for all of the ...observables. The callback is called
- *    immediately and whenever any dependency changes.
- * @returns {Computed} The newly created computed observable.
- */
 export function computed(...args) {
     const readCb = args.pop();
     return new Computed(readCb, args);

package/dist/esm/lib/computed.js.map

@@ -1 +1 @@
-{"version":3,"file":"computed.js","sourceRoot":"","sources":["../../../lib/computed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,EAAoB,eAAe,EAAC,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAwB,UAAU,EAAC,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAgB,YAAY,EAAsB,MAAM,aAAa,CAAC;AAE7E,SAAS,QAAQ;IACf,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;AAC1D,CAAC;AAID,MAAM,OAAO,QAAY,SAAQ,UAAa;IAuC5C;;OAEG;IACH,YAAY,QAA2C,EAAE,YAA6B;QACpF,4FAA4F;QAC5F,qFAAqF;QACrF,KAAK,CAAC,SAAgB,CAAC,CAAC;QACxB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;IAC1E,CAAC;IA7BD;;;;;;;;;OASG;IACI,MAAM,CAAC,MAAM,CAAI,KAA0C,EAAE,GAAG,IAAW;QAChF,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC1B,OAAO,eAAe,CAAC,KAAK,EAAE,IAAI,QAAQ,CAAI,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;IAC/D,CAAC;IAkBD;;OAEG;IACI,WAAW;QAChB,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACI,GAAG,CAAC,KAAQ,IAAU,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAElD;;;OAGG;IACI,OAAO,CAAC,SAA6B;QAC1C,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACI,OAAO;QACZ,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACpB,KAAK,CAAC,OAAO,EAAE,CAAC;IAClB,CAAC;IAEO,KAAK,CAAC,GAAQ,EAAE,GAAG,IAAW;QACpC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,GAAY,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;IACnD,CAAC;CACF;AA6BD;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAG,IAAW;IACrC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC1B,OAAO,IAAI,QAAQ,CAAM,MAAM,EAAE,IAAI,CAAC,CAAC;AACzC,CAAC;AAED,kDAAkD;AAClD,2FAA2F;AAC3F,4FAA4F;AAC5F,+EAA+E;AAC/E,EAAE;AACF,yDAAyD;AACzD,wFAAwF;AACxF,oEAAoE;AACpE,qEAAqE;AACrE,uFAAuF;AACvF,kGAAkG;AAClG,oCAAoC"}
+{"version":3,"file":"computed.js","sourceRoot":"","sources":["../../../lib/computed.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,eAAe,EAAC,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAwB,UAAU,EAAC,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAgB,YAAY,EAAsB,MAAM,aAAa,CAAC;AAE7E,SAAS,QAAQ;IACf,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;AAC1D,CAAC;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,OAAO,QAAY,SAAQ,UAAa;IA6BrC,MAAM,CAAC,MAAM,CAAI,KAA0C,EAAE,GAAG,IAAW;QAChF,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC1B,OAAO,eAAe,CAAC,KAAK,EAAE,IAAI,QAAQ,CAAI,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;IAC/D,CAAC;IAMD,8FAA8F;IAC9F,YAAY,QAA2C,EAAE,YAA6B;QACpF,4FAA4F;QAC5F,qFAAqF;QACrF,KAAK,CAAC,SAAgB,CAAC,CAAC;QACxB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;IAC1E,CAAC;IAED;;;OAGG;IACI,WAAW;QAChB,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACI,GAAG,CAAC,KAAQ,IAAU,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAElD;;;OAGG;IACI,OAAO,CAAC,SAA6B;QAC1C,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACI,OAAO;QACZ,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACpB,KAAK,CAAC,OAAO,EAAE,CAAC;IAClB,CAAC;IAEO,KAAK,CAAC,GAAQ,EAAE,GAAG,IAAW;QACpC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,GAAY,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;IACnD,CAAC;CACF;AAkCD,MAAM,UAAU,QAAQ,CAAC,GAAG,IAAW;IACrC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC1B,OAAO,IAAI,QAAQ,CAAM,MAAM,EAAE,IAAI,CAAC,CAAC;AACzC,CAAC;AAED,kDAAkD;AAClD,2FAA2F;AAC3F,4FAA4F;AAC5F,+EAA+E;AAC/E,EAAE;AACF,yDAAyD;AACzD,wFAAwF;AACxF,oEAAoE;AACpE,qEAAqE;AACrE,uFAAuF;AACvF,kGAAkG;AAClG,oCAAoC"}

package/dist/esm/lib/dispose.js

@@ -1,102 +1,94 @@
+import { LLink } from './emit';
+// Internal "owner" of disposable objects which doesn't actually dispose or keep track of them. It
+// is the effective owner when creating a Disposable with `new Foo()` rather than `Foo.create()`.
+const _noopOwner = {
+    autoDispose(obj) { },
+};
+// Newly-created Disposable instances will have this as their owner. This is not a constant, it
+// is used by create() for the safe creation of Disposables.
+let _defaultDisposableOwner = _noopOwner;
 /**
- * dispose.js provides tools to objects that needs to dispose resources, such as destroy DOM, and
- * unsubscribe from events. The motivation with examples is presented here:
+ * Base class for disposable objects that can own other objects.
  *
- *    https://phab.getgrist.com/w/disposal/
+ * For background and motivation, see [Disposables](/dispose).
  *
- * Disposable is a class for components that need cleanup (e.g. maintain DOM, listen to events,
- * subscribe to anything). It provides a .dispose() method that should be called to destroy the
- * component, and .onDispose()/.autoDispose() methods that the component should use to take
+ * `Disposable` is a class for components that need cleanup (e.g. maintain DOM, listen to events,
+ * subscribe to anything). It provides a `.dispose()` method that should be called to destroy the
+ * component, and `.onDispose()` / `.autoDispose()` methods that the component should use to take
  * responsibility for other pieces that require cleanup.
  *
  * To define a disposable class:
- *    class Foo extends Disposable { ... }
+ * ```ts
+ * class Foo extends Disposable { ... }
+ * ```
  *
- * To create Foo:
- *    const foo = Foo.create(owner, ...args);
+ * To create `Foo`:
+ * ```ts
+ * const foo = Foo.create(owner, ...args);
+ * ```
  * This is better than `new Foo` for two reasons:
- *    1. If Foo's constructor throws an exception, any disposals registered in that constructor
+ *    1. If `Foo`'s constructor throws an exception, any disposals registered in that constructor
  *       before the exception are honored.
  *    2. It ensures you specify the owner of the new instance (but you can use null to skip it).
  *
- * In Foo's constructor (or rarely methods), take ownership of other Disposable objects:
- *    this.bar = Bar.create(this, ...);
+ * In `Foo`'s constructor (or rarely methods), take ownership of other Disposable objects:
+ * ```ts
+ * this.bar = Bar.create(this, ...);
+ * ```
  *
  * For objects that are not instances of Disposable but have a .dispose() methods, use:
- *    this.bar = this.autoDispose(createSomethingDisposable());
+ * ```ts
+ * this.bar = this.autoDispose(createSomethingDisposable());
+ * ```
  *
  * To call a function on disposal (e.g. to add custom disposal logic):
- *    this.onDispose(() => this.myUnsubscribeAllMethod());
- *    this.onDispose(this.myUnsubscribeAllMethod, this);    // slightly more efficient
+ * ```ts
+ * this.onDispose(() => this.myUnsubscribeAllMethod());
+ * this.onDispose(this.myUnsubscribeAllMethod, this);
+ * ```
  *
  * To mark this object to be wiped out on disposal (i.e. set all properties to null):
- *    this.wipeOnDispose();
+ * ```ts
+ * this.wipeOnDispose();
+ * ```
  * See the documentation of that method for more info.
  *
- * To dispose Foo directly:
- *    foo.dispose();
- * To determine if an object has already been disposed:
- *    foo.isDisposed()
+ * To dispose Foo directly: `foo.dispose()`.
  *
- * If you need to replace an owned object, or release, or dispose it early, use a Holder:
- *    this._holder = Holder.create(this);
- *    Bar.create(this._holder, 1);      // creates new Bar(1)
- *    Bar.create(this._holder, 2);      // creates new Bar(2) and disposes previous object
- *    this._holder.clear();             // disposes contained object
- *    this._holder.release();           // releases contained object
+ * To determine if an object has already been disposed: `foo.isDisposed()`.
  *
- * If you need a container for multiple objects and dispose them all together, use a MultiHolder:
- *    this._mholder = MultiHolder.create(null);
- *    Bar.create(this._mholder, 1);     // create new Bar(1)
- *    Bar.create(this._mholder, 2);     // create new Bar(2)
- *    this._mholder.dispose();          // disposes both objects
+ * If you need to replace an owned object, or release, or dispose it early, use a
+ * [`Holder`](#Holder) or [`MultiHolder`](#MultiHolder).
  *
- * If creating your own class with a dispose() method, do NOT throw exceptions from dispose().
- * These cannot be handled properly in all cases. Read here about the same issue in C++:
- *    http://bin-login.name/ftp/pub/docs/programming_languages/cpp/cffective_cpp/MAGAZINE/SU_FRAME.HTM#destruct
+ * If creating your own class with a `dispose()` method, do NOT throw exceptions from `dispose()`.
+ * These cannot be handled properly in all cases.
  *
  * Using a parametrized (generic) class as a Disposable is tricky. E.g.
- *    class Bar<T> extends Disposable { ... }
- *    // Bar<T>.create(...)   <-- doesn't work
- *    // Bar.create<T>(...)   <-- doesn't work
- *    // Bar.create(...)      <-- works, but with {} for Bar's type parameters
+ * ```ts
+ * class Bar<T> extends Disposable { ... }
+ * // Bar<T>.create(...)   <-- doesn't work
+ * // Bar.create<T>(...)   <-- doesn't work
+ * // Bar.create(...)      <-- works, but with {} for Bar's type parameters
+ * ```
  *
  * The solution is to expose the constructor type using a helper method:
- *    class Bar<T> extends Disposable {
- *      // Note the tuple below which must match the constructor parameters of Bar<U>.
- *      public static ctor<U>(): IDisposableCtor<Bar<U>, [U, boolean]> { return this; }
- *      constructor(a: T, b: boolean) { ... }
- *    }
- *    Bar.ctor<T>().create(...)   // <-- works, creates Bar<T>, and does type-checking!
- */
-import { LLink } from './emit';
-// Internal "owner" of disposable objects which doesn't actually dispose or keep track of them. It
-// is the effective owner when creating a Disposable with `new Foo()` rather than `Foo.create()`.
-const _noopOwner = {
-    autoDispose(obj) { },
-};
-// Newly-created Disposable instances will have this as their owner. This is not a constant, it
-// is used by create() for the safe creation of Disposables.
-let _defaultDisposableOwner = _noopOwner;
-/**
- * Base class for disposable objects that can own other objects. See the module documentation.
+ * ```ts
+ * class Bar<T> extends Disposable {
+ *   // Note the tuple below which must match the constructor parameters of Bar<U>.
+ *   public static ctor<U>(): IDisposableCtor<Bar<U>, [U, boolean]> { return this; }
+ *   constructor(a: T, b: boolean) { ... }
+ * }
+ * Bar.ctor<T>().create(...)   // <-- works, creates Bar<T>, and does type-checking!
+ * ```
  */
 export class Disposable {
-    constructor() {
-        this._disposalList = new DisposalList();
-        // This registers with a temp Holder when using create(), and is a no-op when using `new Foo`.
-        _defaultDisposableOwner.autoDispose(this);
-        // Be sure to reset to no-op, so that a (non-recommended) direct call like 'new Bar()', from
-        // inside Foo's constructor doesn't use the same Holder that's temporarily holding Foo.
-        _defaultDisposableOwner = _noopOwner;
-    }
     /**
      * Create Disposable instances using `Class.create(owner, ...)` rather than `new Class(...)`.
      *
      * This reminds you to provide an owner, and ensures that if the constructor throws an
-     * exception, dispose() gets called to clean up the partially-constructed object.
+     * exception, `dispose()` gets called to clean up the partially-constructed object.
      *
-     * Owner may be null if intend to ensure disposal some other way.
+     * Owner may be `null` if you intend to ensure disposal some other way.
      */
     static create(owner, ...args) {
         const origDefaultOwner = _defaultDisposableOwner;
@@ -124,12 +116,20 @@ export class Disposable {
             _defaultDisposableOwner = origDefaultOwner;
         }
     }
-    /** Take ownership of obj, and dispose it when this.dispose() is called. */
+    constructor() {
+        this._disposalList = new DisposalList();
+        // This registers with a temp Holder when using create(), and is a no-op when using `new Foo`.
+        _defaultDisposableOwner.autoDispose(this);
+        // Be sure to reset to no-op, so that a (non-recommended) direct call like 'new Bar()', from
+        // inside Foo's constructor doesn't use the same Holder that's temporarily holding Foo.
+        _defaultDisposableOwner = _noopOwner;
+    }
+    /** Take ownership of `obj`, and dispose it when `this.dispose()` is called. */
     autoDispose(obj) {
         this.onDispose(obj.dispose, obj);
         return obj;
     }
-    /** Call the given callback when this.dispose() is called. */
+    /** Call the given callback when `this.dispose()` is called. */
     onDispose(callback, context) {
         return this._disposalList.addListener(callback, context);
     }
@@ -138,10 +138,13 @@ export class Disposable {
      * recommended to call this early in the constructor.
      *
      * This makes disposal more costly, but has certain benefits:
+     *
      * - If anything still refers to the object and uses it, we'll get an early error, rather than
      *   silently keep going, potentially doing useless work (or worse) and wasting resources.
+     *
      * - If anything still refers to the object (even without using it), the fields of the object
      *   can still be garbage-collected.
+     *
      * - If there are circular references involving this object, they get broken, making the job
      *   easier for the garbage collector.
      *
@@ -158,7 +161,7 @@ export class Disposable {
         return this._disposalList === null;
     }
     /**
-     * Clean up `this` by disposing all owned objects, and calling onDispose() callbacks, in reverse
+     * Clean up `this` by disposing all owned objects, and calling `onDispose()` callbacks, in reverse
      * order to that in which they were added.
      */
     dispose() {
@@ -187,17 +190,31 @@ export class Disposable {
 }
 /**
  * Holder keeps a single disposable object. If given responsibility for another object using
- * holder.autoDispose() or Foo.create(holder, ...), it automatically disposes the currently held
+ * `holder.autoDispose()` or `Foo.create(holder, ...)`, it automatically disposes the currently held
  * object. It also disposes it when the holder itself is disposed.
  *
- * If the object is an instance of Disposable, the holder will also notice when the object gets
+ * If the object is an instance of `Disposable`, the holder will also notice when the object gets
  * disposed from outside of it, in which case the holder will become empty again.
+ *
+ * If you need a container for multiple objects and dispose them all together, use a `MultiHolder`:
+ *
+ * :::info Example
+ * ```ts
+ * this._holder = Holder.create(this);
+ * Bar.create(this._holder, 1);      // creates new Bar(1), assuming it's a Disposable
+ * Bar.create(this._holder, 2);      // creates new Bar(2) and disposes previous object
+ * this._holder.clear();             // disposes contained object
+ * this._holder.release();           // releases contained object
+ * ```
+ * :::
  */
 export class Holder {
     constructor() {
+        /** @internal */
         this._owned = null;
         this._disposalListener = undefined;
     }
+    /** `Holder.create(owner)` creates a new `Holder`. */
     static create(owner) {
         return setDisposeOwner(owner, new Holder());
     }
@@ -246,9 +263,18 @@ export class Holder {
     }
 }
 /**
- * MultiHolder keeps multiple disposable object. It disposes all held object when the holder
- * itself is disposed. It's actually nothing more than the Disposable base class itself, just
+ * `MultiHolder` keeps multiple disposable objects. It disposes all held object when the holder
+ * itself is disposed. It's actually nothing more than the `Disposable` base class itself, just
  * exposed with a clearer name that describes its purpose.
+ *
+ * :::info Example
+ * ```ts
+ * this._mholder = MultiHolder.create(null);
+ * Bar.create(this._mholder, 1);     // create new Bar(1)
+ * Bar.create(this._mholder, 2);     // create new Bar(2)
+ * this._mholder.dispose();          // disposes both objects
+ * ```
+ * :::
  */
 export class MultiHolder extends Disposable {
 }
@@ -296,11 +322,6 @@ class DisposalList extends LLink {
  * reports and swallows erros when it calls the callbacks in the list.
  */
 class DisposeListener extends LLink {
-    constructor(callback, context) {
-        super();
-        this.callback = callback;
-        this.context = context;
-    }
     static callAll(begin, end, owner) {
         while (begin !== end) {
             const lis = begin;
@@ -314,6 +335,11 @@ class DisposeListener extends LLink {
             begin = lis._next;
         }
     }
+    constructor(callback, context) {
+        super();
+        this.callback = callback;
+        this.context = context;
+    }
     dispose() {
         if (this.isDisposed()) {
             return;

package/dist/esm/lib/dispose.js.map

@@ -1 +1 @@
-{"version":3,"file":"dispose.js","sourceRoot":"","sources":["../../../lib/dispose.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dispose.js","sourceRoot":"","sources":["../../../lib/dispose.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/dom.js

@@ -1,21 +1,3 @@
-/**
- * dom.js provides a way to build a DOM tree easily.
- *
- * E.g.
- *  import {dom} from 'grainjs';
- *  dom('a#link.c1.c2', {'href': url}, 'Hello ', dom('span', 'world'));
- *    creates Node <a id="link" class="c1 c2" href={{url}}Hello <span>world</span></a>.
- *
- *  dom.frag(dom('span', 'Hello'), ['blah', dom('div', 'world')])
- *    creates document fragment with <span>Hello</span>blah<div>world</div>.
- *
- * DOM can also be created and modified inline during creation:
- *  dom('a#id.c1',
- *      dom.cls('c2'), dom.attr('href', url),
- *      dom.text('Hello '), dom('span', dom.text('world')))
- *    creates Node <a id="link" class="c1 c2" href={{url}}Hello <span>world</span></a>,
- *    identical to the first example above.
- */
 // We keep various dom-related functions organized in private modules, but they are exposed here.
 export * from './domImpl';
 export * from './domComponent';
@@ -32,6 +14,44 @@ import * as _domImpl from './domImpl';
 import * as _domMethods from './domMethods';
 import * as domevent from './domevent';
 import { dom as _dom } from './domImpl';
+/**
+ * `dom()` provides a way to build a DOM tree easily.
+ *
+ * The first argument is a string consisting of a lowercase tag name (e.g. `"div"`), with optional
+ * `"#foo"` suffix to add the ID `'foo'`, and zero or more `".bar"` suffixes to add a CSS class
+ * `'bar'`.
+ *
+ * The rest of the arguments are optional and may be any number, of these types:
+ *
+ * @param Nodes - become children of the created element
+ * @param strings - become text node children
+ * @param objects - Literal objects to set string attributes on the element.
+ *    E.g. `{title: "foo"}`.
+ * @param null - The values `null` and `undefined` values are ignored completely.
+ * @param Arrays - flattened with each item processed recursively
+ * @param functions - called with the element being built as the argument, for a chance to modify
+ *    the element as it's being created. Return values are processed recursively.
+ * @param functions - "dom methods" are a expressions such as `dom.attr('href', url)` or
+ *    `dom.hide(obs)`, which are special cases of the "functions" category.
+ *
+ * @example
+ * ```ts
+ * import {dom} from 'grainjs';
+ * dom('a', {href: url, className: 'myclass'}, 'Hello ', dom('strong', 'world'));
+ * ```
+ * creates HTML element `<a href={{url}} class="myclass">Hello <strong>world</strong></a>`.
+ *
+ * @example
+ * Here's an example equivalent to the one above, using dom methods `dom.cls`, `dom.attr`,
+ * `dom.text`. In reality, these methods are useful with observable values rather than constant
+ * strings.
+ * ```ts
+ *  dom('a', dom.attr('href', url), dom.cls('myclass'),
+ *      dom.text('Hello '), dom('strong', dom.text('world')));
+ * ```
+ *
+ * @see [DOM & Observables](/basics).
+ */
 // We just want to re-export _domImpl.dom, but to allow adding methods to it in a typesafe way,
 // TypeScript wants us to declare a real function in the same file.
 export function dom(tagString, ...args) {

package/dist/esm/lib/dom.js.map

@@ -1 +1 @@
-{"version":3,"file":"dom.js","sourceRoot":"","sources":["../../../lib/dom.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dom.js","sourceRoot":"","sources":["../../../lib/dom.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAE3B,OAAO,KAAK,aAAa,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,YAAY,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,WAAW,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,WAAW,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,QAAQ,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,WAAW,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AAEvC,OAAO,EAAC,GAAG,IAAI,IAAI,EAA6B,MAAM,WAAW,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,+FAA+F;AAC/F,mEAAmE;AACnE,MAAM,UAAU,GAAG,CAAsB,SAAc,EAAE,GAAG,IAA4B;IACtF,OAAO,IAAI,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,CAAC;AAClC,CAAC;AAED,mEAAmE;AACnE,WAAiB,GAAG;IACL,OAAG,GAAe,QAAQ,CAAC,GAAG,CAAC;IAC/B,QAAI,GAAc,QAAQ,CAAC,IAAI,CAAC;IAChC,UAAM,GAAY,QAAQ,CAAC,MAAM,CAAC;IAClC,QAAI,GAAc,QAAQ,CAAC,IAAI,CAAC;IAChC,WAAO,GAAW,QAAQ,CAAC,OAAO,CAAC;IAEnC,cAAU,GAAQ,WAAW,CAAC,UAAU,CAAC;IACzC,iBAAa,GAAK,WAAW,CAAC,aAAa,CAAC;IAC5C,aAAS,GAAS,WAAW,CAAC,SAAS,CAAC;IACxC,mBAAe,GAAG,WAAW,CAAC,eAAe,CAAC;IAC9C,eAAW,GAAO,WAAW,CAAC,WAAW,CAAC;IAE1C,aAAS,GAAS,WAAW,CAAC,SAAS,CAAC;IACxC,SAAK,GAAa,WAAW,CAAC,KAAK,CAAC;IACpC,YAAQ,GAAU,WAAW,CAAC,QAAQ,CAAC;IACvC,QAAI,GAAc,WAAW,CAAC,IAAI,CAAC;IACnC,gBAAY,GAAM,WAAW,CAAC,YAAY,CAAC;IAC3C,YAAQ,GAAU,WAAW,CAAC,QAAQ,CAAC;IACvC,YAAQ,GAAU,WAAW,CAAC,QAAQ,CAAC;IACvC,QAAI,GAAc,WAAW,CAAC,IAAI,CAAC;IACnC,aAAS,GAAS,WAAW,CAAC,SAAS,CAAC;IACxC,SAAK,GAAa,WAAW,CAAC,KAAK,CAAC;IACpC,YAAQ,GAAU,WAAW,CAAC,QAAQ,CAAC;IACvC,QAAI,GAAc,WAAW,CAAC,IAAI,CAAC;IACnC,YAAQ,GAAU,WAAW,CAAC,QAAQ,CAAC;IACvC,QAAI,GAAc,WAAW,CAAC,IAAI,CAAC;IACnC,YAAQ,GAAU,WAAW,CAAC,QAAQ,CAAC;IACvC,QAAI,GAAc,WAAW,CAAC,IAAI,CAAC;IACnC,WAAO,GAAW,WAAW,CAAC,OAAO,CAAC;IACtC,OAAG,GAAe,WAAW,CAAC,GAAG,CAAC;IAClC,aAAS,GAAS,WAAW,CAAC,SAAS,CAAC;IACxC,YAAQ,GAAU,WAAW,CAAC,QAAQ,CAAC;IACvC,QAAI,GAAc,WAAW,CAAC,IAAI,CAAC;IACnC,WAAO,GAAW,WAAW,CAAC,OAAO,CAAC;IACtC,kBAAc,GAAI,YAAY,CAAC,cAAc,CAAC;IAC9C,eAAW,GAAO,YAAY,CAAC,WAAW,CAAC;IAC3C,oBAAgB,GAAG,YAAY,CAAC,gBAAgB,CAAC;IACjD,SAAK,GAAa,YAAY,CAAC,KAAK,CAAC;IACrC,cAAU,GAAQ,YAAY,CAAC,UAAU,CAAC;IAE1C,WAAO,GAAW,WAAW,CAAC,OAAO,CAAC;IAEtC,UAAM,GAAY,aAAa,CAAC,MAAM,CAAC;IAEvC,UAAM,GAAY,QAAQ,CAAC,MAAM,CAAC;IAClC,MAAE,GAAgB,QAAQ,CAAC,EAAE,CAAC;IAC9B,eAAW,GAAO,QAAQ,CAAC,WAAW,CAAC;IACvC,WAAO,GAAW,QAAQ,CAAC,OAAO,CAAC;IACnC,aAAS,GAAS,QAAQ,CAAC,SAAS,CAAC;IACrC,cAAU,GAAQ,QAAQ,CAAC,UAAU,CAAC;IACtC,aAAS,GAAS,QAAQ,CAAC,SAAS,CAAC;AACpD,CAAC,EApDgB,GAAG,KAAH,GAAG,QAoDnB"}

package/dist/esm/lib/domComponent.js

@@ -1,4 +1,69 @@
 import { domComputedOwned } from './domComputed';
+/**
+ * UI components that can be inserted into `dom()`.
+ *
+ * Components are created and inserted using `dom.create()`:
+ * ```ts
+ * dom('div',
+ *   dom.create(MyWidget, ...myArgs),        // Calls MyWidget.create(owner, ...myArgs)
+ *   dom.create(createMyWidget, ...myArgs),  // Calls createMyWidget(owner, ...myArgs)
+ * )
+ * ```
+ *
+ * The first argument may be a function, which is called directly, or a class with a `.create()`
+ * static method, in which case that's what gets called.
+ *
+ * In both cases, the call gets a first argument of `owner` followed by the rest of the arguments
+ * to `dom.create()`. The `owner` is a `MultiHolder` that will own this component. This works
+ * naturally with any class that derives from Disposable, since it then has a suitable static
+ * `create()` method.
+ *
+ * Function-based components may use owner to easily handle disposal. For example:
+ * ```ts
+ * dom.create(createMyWidget)
+ * function createMyWidget(owner) {
+ *   const foo = Foo.create(owner);
+ *   return dom('div', foo.getTitle());
+ * }
+ * ```
+ *
+ * The `owner` argument is the main benefit of `dom.create()`. Logically, the owner is the DOM where
+ * the component is attached. When the parent DOM element is disposed, so is the component.
+ *
+ * :::info Explanation
+ *
+ * To understand why the syntax is such, consider a potential alternative such as:
+ * ```ts
+ * dom('div', _insert_(new Comp1()), _insert_(new Comp2(...args)))
+ * ```
+ *
+ * In both cases, the constructor for Comp1 runs before the constructor for Comp2. What happens
+ * when Comp2's constructor throws an exception? In the second case, nothing yet owns the
+ * created Comp1 component, and it will never get cleaned up. With `dom.create()`, the DOM
+ * gets ownership of Comp1 early enough and will dispose it.
+ *
+ * :::
+ *
+ * A function component may return DOM directly. A class component returns the class instance,
+ * which must have a `.buildDom()` method which will be called right after the constructor to get
+ * the DOM. Note that buildDom is only called once.
+ *
+ * A function component may also return an object with `.buildDom()`. So these are equivalent:
+ * ```ts
+ * dom.create(MyWidget)
+ * dom.create((owner) => MyWidget.create(owner))
+ * ```
+ *
+ * Note that ownership should be handled using the `owner` argument. Don't do this:
+ * ```ts
+ * // NON-EXAMPLE: Nothing will dispose the created object:
+ * // dom.create(() => new MyWidget());
+ * ```
+ *
+ * The returned DOM may includes Nodes, strings, and `domComputed()` values, as well as arrays of
+ * any of these. In other words, any `DomArg` goes except `DomMethods`. All the DOM returned will be
+ * disposed when the containing element is disposed, followed by the `owner` itself.
+ */
 export function create(fn, ...args) {
     return domComputedOwned(null, (owner) => {
         const value = ('create' in fn) ?

package/dist/esm/lib/domComponent.js.map

@@ -1 +1 @@
-{"version":3,"file":"domComponent.js","sourceRoot":"","sources":["../../../lib/domComponent.ts"],"names":[],"mappings":"AAyDA,OAAO,EAAC,gBAAgB,EAAc,MAAM,eAAe,CAAC;AAuB5D,MAAM,UAAU,MAAM,CAAgC,EAAM,EAAE,GAAG,IAAwB;IACvF,OAAO,gBAAgB,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE;QACtC,MAAM,KAAK,GAAuB,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC;YACjD,EAA6B,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;YACtD,EAA4B,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC;QAChD,OAAO,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC;YAClE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"domComponent.js","sourceRoot":"","sources":["../../../lib/domComponent.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,gBAAgB,EAAc,MAAM,eAAe,CAAC;AAuB5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,MAAM,UAAU,MAAM,CAAgC,EAAM,EAAE,GAAG,IAAwB;IACvF,OAAO,gBAAgB,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE;QACtC,MAAM,KAAK,GAAuB,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC;YACjD,EAA6B,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;YACtD,EAA4B,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC;QAChD,OAAO,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC;YAClE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC"}