grainjs 1.0.2 → 1.1.0

package/dist/cjs/lib/dispose.d.ts

@@ -1,75 +1,3 @@
-/**
- * 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:
- *
- *    https://phab.getgrist.com/w/disposal/
- *
- * 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 { ... }
- *
- * To create Foo:
- *    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
- *       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, ...);
- *
- * For objects that are not instances of Disposable but have a .dispose() methods, use:
- *    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
- *
- * To mark this object to be wiped out on disposal (i.e. set all properties to null):
- *    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()
- *
- * 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
- *
- * 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 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
- *
- * 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
- *
- * 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';
 /**
  * Anything with a .dispose() method is a disposable object, and implements the IDisposable interface.
  */
@@ -77,7 +5,7 @@ export interface IDisposable {
     dispose(): void;
 }
 /**
- * Anything with .autoDispose() can be the owner of a disposable object. This is a type-specific
+ * Anything with `.autoDispose()` can be the owner of a disposable object. This is a type-specific
  * class that can only own a disposable object of type T.
  */
 export interface IDisposableOwnerT<T extends IDisposable> {
@@ -97,33 +25,107 @@ export interface IDisposableCtor<Derived, CtorArgs extends any[]> {
     create<T extends new (...args: any[]) => any>(this: T, owner: IDisposableOwnerT<InstanceType<T>> | null, ...args: ConstructorParameters<T>): InstanceType<T>;
 }
 /**
- * Base class for disposable objects that can own other objects. See the module documentation.
+ * Base class for disposable objects that can own other objects.
+ *
+ * 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
+ * responsibility for other pieces that require cleanup.
+ *
+ * To define a disposable class:
+ * ```ts
+ * class Foo extends Disposable { ... }
+ * ```
+ *
+ * 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
+ *       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:
+ * ```ts
+ * this.bar = Bar.create(this, ...);
+ * ```
+ *
+ * For objects that are not instances of Disposable but have a .dispose() methods, use:
+ * ```ts
+ * this.bar = this.autoDispose(createSomethingDisposable());
+ * ```
+ *
+ * To call a function on disposal (e.g. to add custom disposal logic):
+ * ```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):
+ * ```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()`.
+ *
+ * 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.
+ *
+ * Using a parametrized (generic) class as a Disposable is tricky. E.g.
+ * ```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:
+ * ```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 declare abstract class Disposable implements IDisposable, IDisposableOwner {
     /**
      * 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<T extends new (...args: any[]) => any>(this: T, owner: IDisposableOwnerT<InstanceType<T>> | null, ...args: ConstructorParameters<T>): InstanceType<T>;
     private _disposalList;
     constructor();
-    /** Take ownership of obj, and dispose it when this.dispose() is called. */
+    /** Take ownership of `obj`, and dispose it when `this.dispose()` is called. */
     autoDispose<T extends IDisposable>(obj: T): T;
-    /** Call the given callback when this.dispose() is called. */
-    onDispose<T>(callback: (this: T) => void, context?: T): DisposeListener;
+    /** Call the given callback when `this.dispose()` is called. */
+    onDispose<T>(callback: (this: T) => void, context?: T): IDisposable;
     /**
      * Wipe out this object when it is disposed, i.e. set all its properties to null. It is
      * 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.
      *
@@ -136,7 +138,7 @@ export declare abstract class Disposable implements IDisposable, IDisposableOwne
      */
     isDisposed(): boolean;
     /**
-     * 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(): void;
@@ -148,14 +150,28 @@ export declare abstract class Disposable implements IDisposable, IDisposableOwne
 }
 /**
  * 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 declare class Holder<T extends IDisposable> implements IDisposable, IDisposableOwner {
+    /** `Holder.create(owner)` creates a new `Holder`. */
     static create<T extends IDisposable>(owner: IDisposableOwnerT<Holder<T>> | null): Holder<T>;
+    /** @internal */
     protected _owned: T | null;
     private _disposalListener;
     /** Take ownership of a new object, disposing the previously held one. */
@@ -175,9 +191,18 @@ export declare class Holder<T extends IDisposable> implements IDisposable, IDisp
     private _onOutsideDispose;
 }
 /**
- * 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 declare class MultiHolder extends Disposable {
 }
@@ -185,15 +210,3 @@ export declare class MultiHolder extends Disposable {
  * Sets owner of obj (i.e. calls owner.autoDispose(obj)) unless owner is null. Returns obj.
  */
 export declare function setDisposeOwner<T extends IDisposable>(owner: IDisposableOwnerT<T> | null, obj: T): T;
-/**
- * Internal class that keeps track of one item of the DisposalList. It mimicks emit.Listener, but
- * reports and swallows erros when it calls the callbacks in the list.
- */
-declare class DisposeListener extends LLink implements IDisposable {
-    private callback;
-    private context?;
-    static callAll(begin: LLink, end: LLink, owner: Disposable): void;
-    constructor(callback: () => void, context?: any);
-    dispose(): void;
-}
-export {};

package/dist/cjs/lib/dispose.js

@@ -1,105 +1,97 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setDisposeOwner = exports.MultiHolder = exports.Holder = exports.Disposable = void 0;
+const emit_1 = require("./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!
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.setDisposeOwner = exports.MultiHolder = exports.Holder = exports.Disposable = void 0;
-const emit_1 = require("./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!
+ * ```
  */
 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;
@@ -127,12 +119,20 @@ 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);
     }
@@ -141,10 +141,13 @@ 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.
      *
@@ -161,7 +164,7 @@ 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() {
@@ -191,17 +194,31 @@ class Disposable {
 exports.Disposable = 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
+ * ```
+ * :::
  */
 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());
     }
@@ -251,9 +268,18 @@ class Holder {
 }
 exports.Holder = 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
+ * ```
+ * :::
  */
 class MultiHolder extends Disposable {
 }
@@ -303,11 +329,6 @@ class DisposalList extends emit_1.LLink {
  * reports and swallows erros when it calls the callbacks in the list.
  */
 class DisposeListener extends emit_1.LLink {
-    constructor(callback, context) {
-        super();
-        this.callback = callback;
-        this.context = context;
-    }
     static callAll(begin, end, owner) {
         while (begin !== end) {
             const lis = begin;
@@ -321,6 +342,11 @@ class DisposeListener extends emit_1.LLink {
             begin = lis._next;
         }
     }
+    constructor(callback, context) {
+        super();
+        this.callback = callback;
+        this.context = context;
+    }
     dispose() {
         if (this.isDisposed()) {
             return;

package/dist/cjs/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":";;;AAAA,iCAA6B;AAwB7B,kGAAkG;AAClG,iGAAiG;AACjG,MAAM,UAAU,GAAqB;IACnC,WAAW,CAAC,GAAgB,IAAqB,CAAC;CACnD,CAAC;AAEF,+FAA+F;AAC/F,4DAA4D;AAC5D,IAAI,uBAAuB,GAAG,UAAU,CAAC;AAWzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,MAAsB,UAAU;IAC9B;;;;;;;OAOG;IACI,MAAM,CAAC,MAAM,CACT,KAA8C,EAAE,GAAG,IAA8B;QAE1F,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;QACjD,MAAM,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI;YACF,0DAA0D;YAC1D,uBAAuB,GAAG,MAAM,CAAC;YACjC,OAAO,eAAe,CAAC,KAAK,EAAE,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;SAClD;QAAC,OAAO,CAAC,EAAE;YACV,IAAI;gBACF,yDAAyD;gBACzD,MAAM,CAAC,KAAK,EAAE,CAAC;aAChB;YAAC,OAAO,EAAE,EAAE;gBACX,sCAAsC;gBACtC,OAAO,CAAC,KAAK,CAAC,2CAA2C,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;aAC3E;YACD,MAAM,CAAC,CAAC;SACT;gBAAS;YACR,6EAA6E;YAC7E,uEAAuE;YACvE,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,uBAAuB,GAAG,gBAAgB,CAAC;SAC5C;IACH,CAAC;IAID;QAFQ,kBAAa,GAAiB,IAAI,YAAY,EAAE,CAAC;QAGvD,8FAA8F;QAC9F,uBAAuB,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC1C,4FAA4F;QAC5F,uFAAuF;QACvF,uBAAuB,GAAG,UAAU,CAAC;IACvC,CAAC;IAED,+EAA+E;IACxE,WAAW,CAAwB,GAAM;QAC9C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACjC,OAAO,GAAG,CAAC;IACb,CAAC;IAED,+DAA+D;IACxD,SAAS,CAAI,QAA2B,EAAE,OAAW;QAC1D,OAAO,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACI,aAAa;QAClB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;IAC5C,CAAC;IAED;;OAEG;IACI,UAAU;QACf,OAAO,IAAI,CAAC,aAAa,KAAK,IAAI,CAAC;IACrC,CAAC;IAED;;;OAGG;IACI,OAAO;QACZ,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAC;QACxC,IAAI,CAAC,YAAY,EAAE;YACf,sCAAsC;YACxC,OAAO,CAAC,KAAK,CAAC,8CAA8C,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;SAChF;aAAM;YACL,IAAI,CAAC,aAAa,GAAG,IAAK,CAAC;YAC3B,YAAY,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;SACnC;IACH,CAAC;IAED;;;OAGG;IACK,cAAc;QACpB,6FAA6F;QAC7F,6FAA6F;QAC7F,yFAAyF;QACzF,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YAChC,IAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;SACzB;IACH,CAAC;CACF;AAhHD,gCAgHC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAa,MAAM;IAAnB;QAME,gBAAgB;QACN,WAAM,GAAW,IAAI,CAAC;QACxB,sBAAiB,GAA0B,SAAS,CAAC;IAoD/D,CAAC;IA3DC,qDAAqD;IAC9C,MAAM,CAAC,MAAM,CAAwB,KAAwC;QAClF,OAAO,eAAe,CAAC,KAAK,EAAE,IAAI,MAAM,EAAK,CAAC,CAAC;IACjD,CAAC;IAMD,yEAAyE;IAClE,WAAW,CAAC,GAAM;QACvB,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC;QAClB,IAAI,GAAG,YAAY,UAAU,EAAE;YAC7B,IAAI,CAAC,iBAAiB,GAAG,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC;SACtE;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,0EAA0E;IACnE,OAAO;QACZ,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,uDAAuD;IAChD,KAAK;QACV,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,KAAK,EAAE;YACT,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,KAAK,CAAC,OAAO,EAAE,CAAC;SACjB;IACH,CAAC;IAED,+DAA+D;IACxD,GAAG,KAAa,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAE5C,2CAA2C;IACpC,OAAO,KAAc,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAElD,uEAAuE;IAChE,OAAO,KAAW,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAExC,sDAAsD;IAC9C,SAAS;QACf,MAAM,gBAAgB,GAAG,IAAI,CAAC,iBAAiB,CAAC;QAChD,IAAI,gBAAgB,EAAE;YACpB,IAAI,CAAC,iBAAiB,GAAG,SAAS,CAAC;YACnC,gBAAgB,CAAC,OAAO,EAAE,CAAC;SAC5B;IACH,CAAC;IAEO,iBAAiB;QACvB,IAAI,CAAC,iBAAiB,GAAG,SAAS,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;CACF;AA5DD,wBA4DC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAa,WAAY,SAAQ,UAAU;CAAG;AAA9C,kCAA8C;AAE9C;;GAEG;AACH,SAAgB,eAAe,CAAwB,KAAgC,EAAE,GAAM;IAC7F,IAAI,KAAK,EAAE;QAAE,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;KAAE;IACtC,OAAO,GAAG,CAAC;AACb,CAAC;AAHD,0CAGC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,GAAQ;IACzB,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC;AAC5F,CAAC;AAED;;;GAGG;AACH,MAAM,YAAa,SAAQ,YAAK;IAC9B,gBAAgB,KAAK,EAAE,CAAC,CAAC,CAAC;IAEnB,WAAW,CAAI,QAA2B,EAAE,UAAc;QAC/D,MAAM,GAAG,GAAG,IAAI,eAAe,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACtD,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAM,EAAE,GAAG,CAAC,CAAC;QACrC,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;OAGG;IACI,cAAc,CAAC,KAAiB;QACrC,IAAI;YACF,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,KAAM,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;SACnD;gBAAS;YACR,IAAI,CAAC,YAAY,EAAE,CAAC;SACrB;IACH,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,eAAgB,SAAQ,YAAK;IAC1B,MAAM,CAAC,OAAO,CAAC,KAAY,EAAE,GAAU,EAAE,KAAiB;QAC/D,OAAO,KAAK,KAAK,GAAG,EAAE;YACpB,MAAM,GAAG,GAAG,KAAwB,CAAC;YACrC,IAAI;gBACF,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;aAChC;YAAC,OAAO,CAAC,EAAE;gBACV,sCAAsC;gBACtC,OAAO,CAAC,KAAK,CAAC,4CAA4C,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aACnG;YACD,KAAK,GAAG,GAAG,CAAC,KAAM,CAAC;SACpB;IACH,CAAC;IAED,YAAoB,QAAoB,EAAU,OAAa;QAAI,KAAK,EAAE,CAAC;QAAvD,aAAQ,GAAR,QAAQ,CAAY;QAAU,YAAO,GAAP,OAAO,CAAM;IAAa,CAAC;IAEtE,OAAO;QACZ,IAAI,IAAI,CAAC,UAAU,EAAE,EAAE;YAAE,OAAO;SAAE;QAClC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;CACF"}

package/dist/cjs/lib/dom.d.ts

@@ -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.
- */
 export * from './domImpl';
 export * from './domComponent';
 export * from './domComputed';
@@ -31,6 +13,44 @@ import * as _domImpl from './domImpl';
 import * as _domMethods from './domMethods';
 import * as domevent from './domevent';
 import { IDomArgs, TagElem, TagName } 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).
+ */
 export declare function dom<Tag extends TagName>(tagString: Tag, ...args: IDomArgs<TagElem<Tag>>): TagElem<Tag>;
 export declare namespace dom {
     const svg: typeof _domImpl.svg;