grainjs 0.1.0 → 1.0.2

package/index.ts

@@ -1,10 +1,14 @@
-export {Computed, computed} from './lib/computed';
+export * from './lib/binding';
+export * from './lib/computed';
 export * from './lib/dispose';
 export * from './lib/dom';
 export * from './lib/emit';
 export * from './lib/kowrap';
 export * from './lib/obsArray';
 export * from './lib/observable';
+export * from './lib/pureComputed';
 export * from './lib/styled';
-export {ISubscribable, Subscription, subscribe} from './lib/subscribe';
+export * from './lib/subscribe';
 export * from './lib/util';
+export * from './lib/widgets/input';
+export * from './lib/widgets/select';

package/lib/_computed_queue.ts

@@ -24,7 +24,7 @@ import {PriorityQueue} from './PriorityQueue';
  */
 export class DepItem {
   public static isPrioritySmaller(a: DepItem, b: DepItem): boolean {
-    return a._priority < b._priority;
+    return a._priority < b._priority || (a._priority === b._priority && a._creation < b._creation);
   }
 
   private _priority: number = 0;
@@ -32,6 +32,9 @@ export class DepItem {
   private _callback: () => void;
   private _context?: object;
 
+  // Order of creation, used for ordering items at same priority.
+  private _creation: number = ++_nextCreationNum;
+
   /**
    * Callback should call depItem.useDep(dep) for each DepInput it depends on.
    */
@@ -73,6 +76,9 @@ export class DepItem {
 // The main compute queue.
 const queue = new PriorityQueue<DepItem>(DepItem.isPrioritySmaller);
 
+// Counter for creation order, used to create a stable ordering of DepItems at same priority.
+let _nextCreationNum = 0;
+
 // Array to keep track of items recomputed during this call to compute(). It could be a local
 // variable in compute(), but is made global to minimize allocations.
 const _seen: any[] = [];

package/lib/binding.ts

@@ -5,18 +5,14 @@
 
 import {computed} from './computed';
 import {IDisposable} from './dispose';
-import {Observable} from './observable';
-import {UseCB} from './subscribe';
+import {autoDisposeElem} from './domDispose';
+import {IKnockoutReadObservable, InferKoType} from './kowrap';
+import {BaseObservable} from './observable';
+import {subscribe, UseCBOwner} from './subscribe';
 
-export type BindableValue<T> = Observable<T> | ComputedCallback<T> | T | IKnockoutObservable<T>;
+export type BindableValue<T> = BaseObservable<T> | ComputedCallback<T> | T | IKnockoutReadObservable<T>;
 
-export type ComputedCallback<T> = (use: UseCB, ...args: any[]) => T;
-
-export interface IKnockoutObservable<T> {
-  (): T;
-  peek(): T;
-  subscribe(callback: (newValue: T) => void, target?: any, event?: "change"): IDisposable;
-}
+export type ComputedCallback<T> = (use: UseCBOwner, ...args: any[]) => T;
 
 /**
  * Subscribes a callback to valueObs, which may be one a plain value, an observable, a knockout
@@ -29,20 +25,20 @@ export interface IKnockoutObservable<T> {
  *
  * Returns an object which should be disposed to remove the created subscriptions, or null.
  */
-export function subscribe<T>(valueObs: BindableValue<T>,
-                             callback: (newVal: T, oldVal?: T) => void): IDisposable|null {
+// The overload below is annoying, but needed for correct type inference; see test/types/kowrap.ts.
+export function subscribeBindable<KObs extends IKnockoutReadObservable<any>>(
+    valueObs: KObs, callback: (val: InferKoType<KObs>) => void): IDisposable|null;
+export function subscribeBindable<T>(
+    valueObs: BindableValue<T>, callback: (val: T) => void): IDisposable|null;
+export function subscribeBindable<T>(
+    valueObs: BindableValue<T>, callback: (val: T) => void): IDisposable|null {
   // A plain function (to make a computed from), or a knockout observable.
   if (typeof valueObs === 'function') {
     // Knockout observable.
-    const koValue = valueObs as IKnockoutObservable<T>;
+    const koValue = valueObs as IKnockoutReadObservable<T>;
     if (typeof koValue.peek === 'function') {
-      let savedValue = koValue.peek();
-      const sub = koValue.subscribe((val: T) => {
-        const old = savedValue;
-        savedValue = val;
-        callback(val, old);
-      });
-      callback(savedValue, undefined);
+      const sub = koValue.subscribe((val) => callback(val));
+      callback(koValue.peek());
       return sub;
     }
 
@@ -50,19 +46,28 @@ export function subscribe<T>(valueObs: BindableValue<T>,
     //    let sub = subscribe(use => callback(valueObs(use)));
     // The difference is that when valueObs() evaluates to unchanged value, callback would be
     // called in the version above, but not in the version below.
-    const comp = computed(valueObs);
-    comp.addListener(callback);
-    callback(comp.get(), undefined);
+    const comp = computed(valueObs as ComputedCallback<T>);
+    comp.addListener((val) => callback(val));
+    callback(comp.get());
     return comp;      // Disposing this will dispose its one listener.
   }
 
   // An observable.
-  if (valueObs instanceof Observable) {
-    const sub = valueObs.addListener(callback);
-    callback(valueObs.get(), undefined);
-    return sub;
+  if (valueObs instanceof BaseObservable) {
+    // Use subscribe() rather than addListener(), so that bundling of changes (implicit and with
+    // bundleChanges()) is respected. This matters when callback also uses observables.
+    return subscribe(valueObs, (use, val) => callback(val));
   }
 
-  callback(valueObs, undefined);
+  callback(valueObs);
   return null;
 }
+
+/**
+ * Subscribes a callback to valueObs (which may be a value, observable, or function) using
+ * subscribe(), and disposes the subscription with the passed-in element.
+ */
+export function subscribeElem<T>(elem: Node, valueObs: BindableValue<T>,
+                                 callback: (newVal: T, oldVal?: T) => void): void {
+  autoDisposeElem(elem, subscribeBindable(valueObs, callback));
+}

package/lib/browserGlobals.ts

@@ -27,6 +27,8 @@ export interface IBrowserGlobals {
   window: typeof window;
 }
 
+export interface IBrowserGlobalsLax extends IBrowserGlobals {window: any};
+
 function _updateGlobals(dest: IBrowserGlobals, source: IBrowserGlobals): void {
   dest.DocumentFragment  = source.DocumentFragment;
   dest.Element           = source.Element;
@@ -48,7 +50,7 @@ const _globalsStack: IBrowserGlobals[] = [initial];
 /**
  * Replace globals with those from the given object. Use popGlobals() to restore previous values.
  */
-export function pushGlobals(globals: IBrowserGlobals): void {
+export function pushGlobals(globals: IBrowserGlobalsLax): void {
   _globalsStack.push(globals);
   _updateGlobals(G, globals);
 }

package/lib/computed.ts

@@ -35,21 +35,51 @@
  */
 
 import {DepItem} from './_computed_queue';
-import {IDisposableOwner} from './dispose';
+import {IDisposableOwnerT, setDisposeOwner} from './dispose';
 import {BaseObservable as Obs, Observable} from './observable';
-import {ISubscribable, Subscription} from './subscribe';
+import {ISubscribable, Subscription, UseCBOwner as UseCB} from './subscribe';
 
 function _noWrite(): never {
   throw new Error("Can't write to non-writable computed");
 }
 
-// The generic type for the use() function that callbacks get.
-export interface UseCB {    // tslint:disable-line:interface-name
-  <U>(obs: Obs<U>): U;
-  owner: IDisposableOwner;
-}
+type Owner<T> = IDisposableOwnerT<Computed<T>>|null;
 
 export class Computed<T> extends Observable<T> {
+  // Still need repetitive declarations to support varargs that are not the final argument.
+  public static create<T>(
+    owner: Owner<T>, cb: (use: UseCB) => T): Computed<T>;
+  public static create<T, A>(
+    owner: Owner<T>, a: Obs<A>,
+    cb: (use: UseCB, a: A) => T): Computed<T>;
+  public static create<T, A, B>(
+    owner: Owner<T>, a: Obs<A>, b: Obs<B>,
+    cb: (use: UseCB, a: A, b: B) => T): Computed<T>;
+  public static create<T, A, B, C>(
+    owner: Owner<T>, a: Obs<A>, b: Obs<B>, c: Obs<C>,
+    cb: (use: UseCB, a: A, b: B, c: C) => T): Computed<T>;
+  public static create<T, A, B, C, D>(
+    owner: Owner<T>, a: Obs<A>, b: Obs<B>, c: Obs<C>, d: Obs<D>,
+    cb: (use: UseCB, a: A, b: B, c: C, d: D) => T): Computed<T>;
+  public static create<T, A, B, C, D, E>(
+    owner: Owner<T>, a: Obs<A>, b: Obs<B>, c: Obs<C>, d: Obs<D>, e: Obs<E>,
+    cb: (use: UseCB, a: A, b: B, c: C, d: D, e: E) => T): Computed<T>;
+
+  /**
+   * 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.
+   */
+  public static create<T>(owner: IDisposableOwnerT<Computed<T>>|null, ...args: any[]): Computed<T> {
+    const readCb = args.pop();
+    return setDisposeOwner(owner, new Computed<T>(readCb, args));
+  }
+
   private _callback: (use: UseCB, ...args: any[]) => T;
   private _write: (value: T) => void;
   private _sub: Subscription;

package/lib/dispose.ts

@@ -45,9 +45,29 @@
  *    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';
@@ -84,6 +104,15 @@ const _noopOwner: IDisposableOwner = {
 // is used by create() for the safe creation of Disposables.
 let _defaultDisposableOwner = _noopOwner;
 
+/**
+ * The static portion of class Disposable.
+ */
+export interface IDisposableCtor<Derived, CtorArgs extends any[]> {
+  new(...args: CtorArgs): Derived;
+  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.
  */
@@ -95,27 +124,9 @@ export abstract class Disposable implements IDisposable, IDisposableOwner {
    * exception, dispose() gets called to clean up the partially-constructed object.
    *
    * Owner may be null if intend to ensure disposal some other way.
-   *
-   * TODO: create() needs more unittests, including to ensure that TypeScript types are done
-   * correctly.
    */
-  // The complex-looking overloads are to ensure that it can do type-checking for constuctors of
-  // different arity. E.g. if Foo's constructor takes (number, string), we want Foo.create to
-  // require (owner, number, string) as arguments.
-  public static create<T extends IDisposable>(
-    this: new () => T, owner: IDisposableOwnerT<T>|null): T;
-  public static create<T extends IDisposable, A>(
-    this: new (a: A) => T, owner: IDisposableOwnerT<T>|null, a: A): T;
-  public static create<T extends IDisposable, A, B>(
-    this: new (a: A, b: B) => T, owner: IDisposableOwnerT<T>|null, a: A, b: B): T;
-  public static create<T extends IDisposable, A, B, C>(
-    this: new (a: A, b: B, c: C) => T, owner: IDisposableOwnerT<T>|null, a: A, b: B, c: C): T;
-  public static create<T extends IDisposable, A, B, C, D>(
-    this: new (a: A, b: B, c: C, d: D) => T, owner: IDisposableOwnerT<T>|null, a: A, b: B, c: C, d: D): T;
-  public static create<T extends IDisposable, A, B, C, D, E>(
-    this: new (a: A, b: B, c: C, d: D, e: E) => T, owner: IDisposableOwnerT<T>|null, a: A, b: B, c: C, d: D, e: E): T;
-  public static create<T extends IDisposable>(
-    this: new (...args: any[]) => T, owner: IDisposableOwnerT<T>|null, ...args: any[]): T {
+  public static create<T extends new (...args: any[]) => any>(
+    this: T, owner: IDisposableOwnerT<InstanceType<T>>|null, ...args: ConstructorParameters<T>): InstanceType<T> {
 
     const origDefaultOwner = _defaultDisposableOwner;
     const holder = new Holder();
@@ -145,6 +156,9 @@ export abstract class Disposable implements IDisposable, IDisposableOwner {
   constructor() {
     // 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. */
@@ -154,8 +168,8 @@ export abstract class Disposable implements IDisposable, IDisposableOwner {
   }
 
   /** Call the given callback when this.dispose() is called. */
-  public onDispose<T>(callback: (this: T) => void, context?: T): void {
-    this._disposalList.addListener(callback, context);
+  public onDispose<T>(callback: (this: T) => void, context?: T): DisposeListener {
+    return this._disposalList.addListener(callback, context);
   }
 
   /**
@@ -190,8 +204,13 @@ export abstract class Disposable implements IDisposable, IDisposableOwner {
    */
   public dispose(): void {
     const disposalList = this._disposalList;
-    this._disposalList = null!;
-    disposalList.callAndDispose(this);
+    if (!disposalList) {
+        // tslint:disable-next-line:no-console
+      console.error("Error disposing %s which is already disposed", _describe(this));
+    } else {
+      this._disposalList = null!;
+      disposalList.callAndDispose(this);
+    }
   }
 
   /**
@@ -215,28 +234,28 @@ export abstract class Disposable implements IDisposable, IDisposableOwner {
  *
  * 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.
- *
- * TODO Holder needs unittests.
  */
 export class Holder<T extends IDisposable> implements IDisposable, IDisposableOwner {
-  public static create<T extends IDisposable>(owner: IDisposableOwner|null): Holder<T> {
+  public static create<T extends IDisposable>(owner: IDisposableOwnerT<Holder<T>>|null): Holder<T> {
     return setDisposeOwner(owner, new Holder<T>());
   }
 
   protected _owned: T|null = null;
+  private _disposalListener: DisposeListener|undefined = undefined;
 
   /** Take ownership of a new object, disposing the previously held one. */
   public autoDispose(obj: T): T {
-    if (this._owned) { this._owned.dispose(); }
+    this.clear();
     this._owned = obj;
     if (obj instanceof Disposable) {
-      obj.onDispose(this.release, this);
+      this._disposalListener = obj.onDispose(this._onOutsideDispose, this);
     }
     return obj;
   }
 
   /** Releases the held object without disposing it, emptying the holder. */
   public release(): IDisposable|null {
+    this._unlisten();
     const ret = this._owned;
     this._owned = null;
     return ret;
@@ -244,9 +263,11 @@ export class Holder<T extends IDisposable> implements IDisposable, IDisposableOw
 
   /** Disposes the held object and empties the holder. */
   public clear(): void {
-    if (this._owned) {
-      this._owned.dispose();
+    this._unlisten();
+    const owned = this._owned;
+    if (owned) {
       this._owned = null;
+      owned.dispose();
     }
   }
 
@@ -258,8 +279,29 @@ export class Holder<T extends IDisposable> implements IDisposable, IDisposableOw
 
   /** When the holder is disposed, it disposes the held object if any. */
   public dispose(): void { this.clear(); }
+
+  /** Stop listening for the disposal of this._owned. */
+  private _unlisten() {
+    const disposalListener = this._disposalListener;
+    if (disposalListener) {
+      this._disposalListener = undefined;
+      disposalListener.dispose();
+    }
+  }
+
+  private _onOutsideDispose() {
+    this._disposalListener = undefined;
+    this._owned = null;
+  }
 }
 
+/**
+ * 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
+ * exposed with a clearer name that describes its purpose.
+ */
+export class MultiHolder extends Disposable {}
+
 /**
  * Sets owner of obj (i.e. calls owner.autoDispose(obj)) unless owner is null. Returns obj.
  */
@@ -282,9 +324,10 @@ function _describe(obj: any) {
 class DisposalList extends LLink {
   constructor() { super(); }
 
-  public addListener<T>(callback: (this: T) => void, optContext?: T): void {
+  public addListener<T>(callback: (this: T) => void, optContext?: T): DisposeListener {
     const lis = new DisposeListener(callback, optContext);
     this._insertBefore(this._next!, lis);
+    return lis;
   }
 
   /**
@@ -304,7 +347,7 @@ class DisposalList extends LLink {
  * 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.
  */
-class DisposeListener extends LLink {
+class DisposeListener extends LLink implements IDisposable {
   public static callAll(begin: LLink, end: LLink, owner: Disposable): void {
     while (begin !== end) {
       const lis = begin as DisposeListener;
@@ -319,4 +362,9 @@ class DisposeListener extends LLink {
   }
 
   constructor(private callback: () => void, private context?: any) { super(); }
+
+  public dispose(): void {
+    if (this.isDisposed()) { return; }
+    this._removeNode(this);
+  }
 }

package/lib/dom.ts

@@ -18,24 +18,29 @@
  */
 
 // We keep various dom-related functions organized in private modules, but they are exposed here.
-export {DomMethod, DomElementMethod, DomArg, DomElementArg, svg, update, frag, find, findAll} from './_domImpl';
-export * from './_domComponent';
-export * from './_domDispose';
-export * from './_domForEach';
-export * from './_domMethods';
+export * from './domImpl';
+export * from './domComponent';
+export * from './domComputed';
+export * from './domDispose';
+export * from './domForEach';
+export * from './domMethods';
 export * from './domevent';
 
-import * as _domComponent from './_domComponent';
-import * as _domDispose from './_domDispose';
-import * as _domForEach from './_domForEach';
-import * as _domImpl from './_domImpl';
-import * as _domMethods from './_domMethods';
+import * as _domComponent from './domComponent';
+import * as _domComputed from './domComputed';
+import * as _domDispose from './domDispose';
+import * as _domForEach from './domForEach';
+import * as _domImpl from './domImpl';
+import * as _domMethods from './domMethods';
+
 import * as domevent from './domevent';
 
+import {dom as _dom, IDomArgs, TagElem, TagName} from './domImpl';
+
 // 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: string, ...args: _domImpl.DomElementArg[]): HTMLElement {
-  return _domImpl.dom(tagString, ...args);
+export function dom<Tag extends TagName>(tagString: Tag, ...args: IDomArgs<TagElem<Tag>>): TagElem<Tag> {
+  return _dom(tagString, ...args);
 }
 
 // Additionally export all methods as properties of dom() function.
@@ -74,20 +79,21 @@ export namespace dom {      // tslint:disable-line:no-namespace
   export const dataElem        = _domMethods.dataElem;
   export const data            = _domMethods.data;
   export const getData         = _domMethods.getData;
-  export const replaceContent  = _domMethods.replaceContent;
-  export const domComputed     = _domMethods.domComputed;
-  export const maybe           = _domMethods.maybe;
+  export const replaceContent  = _domComputed.replaceContent;
+  export const domComputed     = _domComputed.domComputed;
+  export const domComputedOwned = _domComputed.domComputedOwned;
+  export const maybe           = _domComputed.maybe;
+  export const maybeOwned      = _domComputed.maybeOwned;
 
   export const forEach         = _domForEach.forEach;
 
-  export const Component       = _domComponent.Component;
   export const create          = _domComponent.create;
-  export const createInit      = _domComponent.createInit;
 
   export const onElem          = domevent.onElem;
   export const on              = domevent.on;
   export const onMatchElem     = domevent.onMatchElem;
   export const onMatch         = domevent.onMatch;
-  export const onKeyPressElem  = domevent.onKeyPressElem;
+  export const onKeyElem       = domevent.onKeyElem;
   export const onKeyPress      = domevent.onKeyPress;
+  export const onKeyDown       = domevent.onKeyDown;
 }

package/lib/domComponent.ts

@@ -0,0 +1,89 @@
+/**
+ * UI components that can be inserted into dom().
+ *
+ * Components are created and inserted using dom.create():
+ *
+ *    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:
+ *
+ *    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.
+ *
+ *    [Explanation] To understand why the syntax is such, consider a potential alternative such as:
+ *
+ *       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:
+ *
+ *    dom.create(MyWidget)
+ *    dom.create((owner) => MyWidget.create(owner))
+ *
+ * Note that ownership should be handled using the `owner` argument. Don't do this:
+ *
+ *    // 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.
+ */
+import {MultiHolder} from './dispose';
+import {domComputedOwned, DomContents} from './domComputed';
+
+export interface IDomComponent {
+  buildDom(): DomContents;
+}
+
+export type DomComponentReturn = DomContents | IDomComponent;
+
+export type IDomCreateFunc<Args extends any[]> = (owner: MultiHolder, ...args: Args) => DomComponentReturn;
+
+// It's not that we must have a constructor matching create(), but specifying type of new allows
+// type checking of classes that derive from Disposable, whereas matching only create() does not
+// (presumably because of the too much magic that Disposable does for the type of create()).
+export interface IDomCreateClass<Args extends any[]> {
+  create: IDomCreateFunc<Args>;
+  new (...args: Args): DomComponentReturn;
+}
+export type IDomCreator<Args extends any[]> = IDomCreateFunc<Args> | IDomCreateClass<Args>;
+
+type DomCreatorArgs<T> =
+  T extends (owner: MultiHolder, ...args: infer P) => any ? P :
+  (T extends new (...args: infer P) => any ? P : never);
+
+export function create<Fn extends IDomCreator<any[]>>(fn: Fn, ...args: DomCreatorArgs<Fn>): DomContents {
+  return domComputedOwned(null, (owner) => {
+    const value: DomComponentReturn = ('create' in fn) ?
+      (fn as IDomCreateClass<any[]>).create(owner, ...args) :
+      (fn as IDomCreateFunc<any[]>)(owner, ...args);
+    return (value && typeof value === 'object' && 'buildDom' in value) ?
+      value.buildDom() : value;
+  });
+}