grainjs 1.0.2 → 1.1.0

package/README.md

@@ -1,86 +1,38 @@
-# GrainJS
+# GrainJS: a light typescript web framework
 
 [![npm version](https://badge.fury.io/js/grainjs.svg)](https://badge.fury.io/js/grainjs)
-[![Build Status](https://travis-ci.org/gristlabs/grainjs.svg?branch=master)](https://travis-ci.org/gristlabs/grainjs)
+[![Build status](https://github.com/gristlabs/grainjs/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/gristlabs/grainjs/actions/workflows/build-and-test.yml)
+[![codecov](https://codecov.io/gh/gristlabs/grainjs/branch/main/graph/badge.svg?token=1OIMMBLI6N)](https://codecov.io/gh/gristlabs/grainjs)
 
-GrainJS is a Javascript (and TypeScript) library for building highly performant dynamic
-applications.
+GrainJS is a JavaScript / TypeScript library for building dynamic web applications.
 
-GrainJS provides convenient pure-JS interfaces for building DOM. It has observables inspired by
-[Knockout](http://knockoutjs.com/documentation/introduction.html) to create declarative data
-models and tie them to UI. It includes light-weight event dispatching, DOM event subscriptions,
-disposable components, and in-code CSS styling.
+- It's in part inspired by [React](https://reactjs.org/), but based on observables (like
+[Knockout](http://knockoutjs.com/documentation/introduction.html)) instead of virtual dom.
+- It is lightweight, has no dependencies, and takes only ~30KB minified.
+- It needs no special tooling. It's nothing more than a library.
+- It supports convenient DOM-building in JS, event dispatching, DOM event subscriptions,
+  disposable components, and in-code CSS styling.
+- It's fully typed for use with TypeScript.
+- It's proven its worth by powering [Grist](https://github.com/gristlabs/grist-core#grist)'s rich
+  frontend app.
 
-GrainJS is in part inspired by [React](https://reactjs.org/), but based on observables instead of
-virtual dom, and with a convenient way to build DOM without JSX. It is lighter weight, and has
-less magic happening under the covers.
+## Documentation
 
-The focus is on performance and conciseness. The library has no dependencies and is only 31K.
-minified.
+For docs, visit [https://gristlabs.github.io/grainjs/](https://gristlabs.github.io/grainjs/).
 
 ## Installation
 
+```sh
+npm install grainjs
 ```
-npm install --save grainjs
-```
-
-## Basic Example
-
-```typescript
-const name = observable("");
-
-dom.update(document.body,
-  dom('input', {type: 'text', placeholder: 'Enter your name'},
-    dom.on('input', (ev, elem) => name.set(elem.value)),
-  ),
-  dom('div', 'Hello, ',
-    dom.text((use) => use(name).toUpperCase() || 'Stranger'),
-    '!',
-  ),
-);
-```
-
-# Documentation
-
-At a basic level, GrainJS allows you to describe DOM structure in one place, using Javascript (or
-TypeScript), and to keep the dynamic aspects of it separated into variables called "observables".
-These observables serve as the model of the UI; other code can update them to cause UI to update,
-without knowing the details of the DOM construction.
-
-In addition, the library provides approaches to create and dispose resources (important for
-long-lived single-page applications), and an assortment of other related tools.
 
-- [DOM & Observables](docs/basics.md)
-  - [DOM Construction](docs/basics.md#dom-construction)
-  - [Observables](docs/basics.md#observables)
-    - [Computed Observables](docs/basics.md#computed-observables)
-  - [DOM Bindings](docs/basics.md#dom-bindings)
-    - [Conditional DOM](docs/basics.md#conditional-dom)
-    - [Repeating DOM](docs/basics.md#repeating-dom)
-    - [DOM Events](docs/basics.md#dom-events)
-  - [Styling DOM](docs/basics.md#styling-dom)
+Or see [Getting started with GrainJS](https://gristlabs.github.io/grainjs/getting-started.html).
 
-- [Disposables](docs/dispose.md)
-  - [Class Disposable](docs/dispose.md#class-disposable)
-  - [Taking Ownership](docs/dispose.md#taking-ownership)
-  - [Holders](docs/dispose.md#holders)
-  - [Further Notes](docs/dispose.md#further-notes)
+## Examples
 
-- [More on Observables](docs/more-observables.md)
-  - [Subscribe](docs/more-observables.md#subscribe)
-  - [Disposable Values](docs/more-observables.md#disposable-values)
-  - [ObsArray](docs/more-observables.md#obsarray)
-  - [PureComputed](docs/more-observables.md#purecomputed)
-  - [Order of Evaluation](docs/more-observables.md#order-of-evaluation)
+See basic examples in [Quick tour](https://gristlabs.github.io/grainjs/#quick-tour) or complete examples
+at [Examples](https://gristlabs.github.io/grainjs/examples.html).
 
-- [Miscellaneous](docs/misc.md)
-  - [Event Emitters](docs/misc.md#event-emitters)
-  - [Disposing DOM](docs/misc.md#disposing-dom)
-  - [DOM Components](docs/misc.md#dom-components)
-    - [Functional Components](docs/misc.md#functional-components)
-  - [Knockout Integration](docs/misc.md#knockout-integration)
+## License
 
-- [Reference](docs/reference.md)
-  - [DOM Reference](docs/reference.md#dom-reference)
-  - [Disposables Reference](docs/reference.md#disposables-reference)
-  - [Observables Reference](docs/reference.md#observables-reference)
+GrainJS is licensed under [Apache-2.0 license](https://github.com/gristlabs/grainjs/blob/main/LICENSE).

package/dist/cjs/index.js

@@ -1,7 +1,11 @@
 "use strict";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
 }) : (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,gDAA8B;AAC9B,iDAA+B;AAC/B,gDAA8B;AAC9B,4CAA0B;AAC1B,6CAA2B;AAC3B,+CAA6B;AAC7B,iDAA+B;AAC/B,mDAAiC;AACjC,qDAAmC;AACnC,+CAA6B;AAC7B,kDAAgC;AAChC,6CAA2B;AAC3B,sDAAoC;AACpC,uDAAqC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA8B;AAC9B,iDAA+B;AAC/B,gDAA8B;AAC9B,4CAA0B;AAC1B,6CAA2B;AAC3B,+CAA6B;AAC7B,iDAA+B;AAC/B,mDAAiC;AACjC,qDAAmC;AACnC,+CAA6B;AAC7B,kDAAgC;AAChC,6CAA2B;AAC3B,sDAAoC;AACpC,uDAAqC"}

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

@@ -6,7 +6,7 @@
  * It is constructed with a function that returns which of two items is "prior"; the pop() method
  * returns the most-prior element.
  */
-export declare type IsPriorFunc<T> = (a: T, b: T) => boolean;
+export type IsPriorFunc<T> = (a: T, b: T) => boolean;
 export declare class PriorityQueue<T> {
     private _isPrior;
     private _items;

package/dist/cjs/lib/_computed_queue.js

@@ -24,6 +24,9 @@ const PriorityQueue_1 = require("./PriorityQueue");
  * for subscriptions and computed observables.
  */
 class DepItem {
+    static isPrioritySmaller(a, b) {
+        return a._priority < b._priority || (a._priority === b._priority && a._creation < b._creation);
+    }
     /**
      * Callback should call depItem.useDep(dep) for each DepInput it depends on.
      */
@@ -35,9 +38,6 @@ class DepItem {
         this._callback = callback;
         this._context = optContext;
     }
-    static isPrioritySmaller(a, b) {
-        return a._priority < b._priority || (a._priority === b._priority && a._creation < b._creation);
-    }
     /**
      * Mark depItem as a dependency of this DepItem. The argument may be null to indicate a leaf (an
      * item such as a plain observable, which does not itself depend on anything else).

package/dist/cjs/lib/_computed_queue.js.map

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

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

@@ -6,8 +6,15 @@ import { IDisposable } from './dispose';
 import { IKnockoutReadObservable, InferKoType } from './kowrap';
 import { BaseObservable } from './observable';
 import { UseCBOwner } from './subscribe';
-export declare type BindableValue<T> = BaseObservable<T> | ComputedCallback<T> | T | IKnockoutReadObservable<T>;
-export declare type ComputedCallback<T> = (use: UseCBOwner, ...args: any[]) => T;
+/**
+ * Any of the value types that DOM methods know how to subscribe to: a plain value (like a
+ * string); an Observable (including a Computed); a knockout observable; a function.
+ *
+ * If a function, it's used to create a `Computed`, and will be called with a context function
+ * `use`, allowing it to depend on other observable values (see documentation for `Computed`).
+ */
+export type BindableValue<T> = BaseObservable<T> | ComputedCallback<T> | T | IKnockoutReadObservable<T>;
+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
  * observable, or a function. If a function, it's used to create a computed() and will be called
@@ -22,7 +29,7 @@ export declare type ComputedCallback<T> = (use: UseCBOwner, ...args: any[]) => T
 export declare function subscribeBindable<KObs extends IKnockoutReadObservable<any>>(valueObs: KObs, callback: (val: InferKoType<KObs>) => void): IDisposable | null;
 export declare function subscribeBindable<T>(valueObs: BindableValue<T>, callback: (val: T) => void): IDisposable | 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.
+ * Subscribes a callback to `valueObs` (which may be a value, observable, or function) using
+ * `subscribeBindable()`, and ties the disposal of this subscription to the passed-in element.
  */
 export declare function subscribeElem<T>(elem: Node, valueObs: BindableValue<T>, callback: (newVal: T, oldVal?: T) => void): void;

package/dist/cjs/lib/binding.js

@@ -23,7 +23,7 @@ function subscribeBindable(valueObs, callback) {
         //    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_1.computed(valueObs);
+        const comp = (0, computed_1.computed)(valueObs);
         comp.addListener((val) => callback(val));
         callback(comp.get());
         return comp; // Disposing this will dispose its one listener.
@@ -32,18 +32,18 @@ function subscribeBindable(valueObs, callback) {
     if (valueObs instanceof observable_1.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_1.subscribe(valueObs, (use, val) => callback(val));
+        return (0, subscribe_1.subscribe)(valueObs, (use, val) => callback(val));
     }
     callback(valueObs);
     return null;
 }
 exports.subscribeBindable = subscribeBindable;
 /**
- * Subscribes a callback to valueObs (which may be a value, observable, or function) using
- * subscribe(), and disposes the subscription with the passed-in element.
+ * Subscribes a callback to `valueObs` (which may be a value, observable, or function) using
+ * `subscribeBindable()`, and ties the disposal of this subscription to the passed-in element.
  */
 function subscribeElem(elem, valueObs, callback) {
-    domDispose_1.autoDisposeElem(elem, subscribeBindable(valueObs, callback));
+    (0, domDispose_1.autoDisposeElem)(elem, subscribeBindable(valueObs, callback));
 }
 exports.subscribeElem = subscribeElem;
 //# sourceMappingURL=binding.js.map

package/dist/cjs/lib/binding.js.map

@@ -1 +1 @@
-{"version":3,"file":"binding.js","sourceRoot":"","sources":["../../../lib/binding.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,yCAAoC;AAEpC,6CAA6C;AAE7C,6CAA4C;AAC5C,2CAAkD;AAsBlD,SAAgB,iBAAiB,CAC7B,QAA0B,EAAE,QAA0B;IACxD,wEAAwE;IACxE,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE;QAClC,uBAAuB;QACvB,MAAM,OAAO,GAAG,QAAsC,CAAC;QACvD,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE;YACtC,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;YACtD,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;YACzB,OAAO,GAAG,CAAC;SACZ;QAED,6EAA6E;QAC7E,0DAA0D;QAC1D,yFAAyF;QACzF,6DAA6D;QAC7D,MAAM,IAAI,GAAG,mBAAQ,CAAC,QAA+B,CAAC,CAAC;QACvD,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;QACzC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC,CAAM,gDAAgD;KACnE;IAED,iBAAiB;IACjB,IAAI,QAAQ,YAAY,2BAAc,EAAE;QACtC,4FAA4F;QAC5F,mFAAmF;QACnF,OAAO,qBAAS,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;KACzD;IAED,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACnB,OAAO,IAAI,CAAC;AACd,CAAC;AA/BD,8CA+BC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAI,IAAU,EAAE,QAA0B,EACtC,QAAyC;IACxE,4BAAe,CAAC,IAAI,EAAE,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC/D,CAAC;AAHD,sCAGC"}
+{"version":3,"file":"binding.js","sourceRoot":"","sources":["../../../lib/binding.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,yCAAoC;AAEpC,6CAA6C;AAE7C,6CAA4C;AAC5C,2CAAkD;AA6BlD,SAAgB,iBAAiB,CAC7B,QAA0B,EAAE,QAA0B;IACxD,wEAAwE;IACxE,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE;QAClC,uBAAuB;QACvB,MAAM,OAAO,GAAG,QAAsC,CAAC;QACvD,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE;YACtC,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;YACtD,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;YACzB,OAAO,GAAG,CAAC;SACZ;QAED,6EAA6E;QAC7E,0DAA0D;QAC1D,yFAAyF;QACzF,6DAA6D;QAC7D,MAAM,IAAI,GAAG,IAAA,mBAAQ,EAAC,QAA+B,CAAC,CAAC;QACvD,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;QACzC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC,CAAM,gDAAgD;KACnE;IAED,iBAAiB;IACjB,IAAI,QAAQ,YAAY,2BAAc,EAAE;QACtC,4FAA4F;QAC5F,mFAAmF;QACnF,OAAO,IAAA,qBAAS,EAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;KACzD;IAED,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACnB,OAAO,IAAI,CAAC;AACd,CAAC;AA/BD,8CA+BC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAI,IAAU,EAAE,QAA0B,EACtC,QAAyC;IACxE,IAAA,4BAAe,EAAC,IAAI,EAAE,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC/D,CAAC;AAHD,sCAGC"}

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

@@ -1,44 +1,62 @@
+import { DepItem } from './_computed_queue';
+import { IDisposableOwnerT } from './dispose';
+import { BaseObservable as Obs, Observable } from './observable';
+import { ISubscribable, UseCBOwner as UseCB } from './subscribe';
+/** @internal */
+type Owner<T> = IDisposableOwnerT<Computed<T>> | null;
 /**
- * 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 { DepItem } from './_computed_queue';
-import { IDisposableOwnerT } from './dispose';
-import { BaseObservable as Obs, Observable } from './observable';
-import { ISubscribable, UseCBOwner as UseCB } from './subscribe';
-declare type Owner<T> = IDisposableOwnerT<Computed<T>> | null;
 export declare class Computed<T> extends Observable<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 The newly created `Computed` observable.
+     */
     static create<T>(owner: Owner<T>, cb: (use: UseCB) => T): Computed<T>;
     static create<T, A>(owner: Owner<T>, a: Obs<A>, cb: (use: UseCB, a: A) => T): Computed<T>;
     static create<T, A, B>(owner: Owner<T>, a: Obs<A>, b: Obs<B>, cb: (use: UseCB, a: A, b: B) => T): Computed<T>;
@@ -48,18 +66,16 @@ export declare class Computed<T> extends Observable<T> {
     private _callback;
     private _write;
     private _sub;
-    /**
-     * Internal constructor for a Computed observable. You should use computed() function instead.
-     */
     constructor(callback: (use: UseCB, ...args: any[]) => T, dependencies: ISubscribable[]);
     /**
      * Used by subscriptions to keep track of dependencies.
+     * @internal
      */
     _getDepItem(): DepItem;
     /**
      * "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: T): void;
     /**
@@ -74,9 +90,14 @@ export declare class Computed<T> extends Observable<T> {
     private _read;
 }
 /**
- * This is the type-checking interface for computed(), which allows TypeScript to do helpful
- * type-checking when using it. We can only support a fixed number of argumnets (explicit
- * dependencies), but 5 should almost always be enough.
+ * Creates a new Computed.
+ * @param 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 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 The newly created `Computed` observable.
  */
 export declare function computed<T>(cb: (use: UseCB) => T): Computed<T>;
 export declare function computed<T, A>(a: Obs<A>, cb: (use: UseCB, a: A) => T): Computed<T>;

package/dist/cjs/lib/computed.js

@@ -1,51 +1,60 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computed = exports.Computed = void 0;
+const dispose_1 = require("./dispose");
+const observable_1 = require("./observable");
+const subscribe_1 = require("./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.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.computed = exports.Computed = void 0;
-const dispose_1 = require("./dispose");
-const observable_1 = require("./observable");
-const subscribe_1 = require("./subscribe");
-function _noWrite() {
-    throw new Error("Can't write to non-writable computed");
-}
 class Computed extends observable_1.Observable {
-    /**
-     * Internal constructor for a Computed observable. You should use computed() function instead.
-     */
+    static create(owner, ...args) {
+        const readCb = args.pop();
+        return (0, dispose_1.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.
@@ -54,22 +63,9 @@ class Computed extends observable_1.Observable {
         this._write = _noWrite;
         this._sub = new subscribe_1.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 dispose_1.setDisposeOwner(owner, new Computed(readCb, args));
-    }
     /**
      * Used by subscriptions to keep track of dependencies.
+     * @internal
      */
     _getDepItem() {
         return this._sub._getDepItem();
@@ -77,7 +73,7 @@ class Computed extends observable_1.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); }
     /**
@@ -100,16 +96,6 @@ class Computed extends observable_1.Observable {
     }
 }
 exports.Computed = Computed;
-/**
- * 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.
- */
 function computed(...args) {
     const readCb = args.pop();
     return new Computed(readCb, args);

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

@@ -1 +1 @@
-{"version":3,"file":"computed.js","sourceRoot":"","sources":["../../../lib/computed.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;;;AAGH,uCAA6D;AAC7D,6CAA+D;AAC/D,2CAA6E;AAE7E,SAAS,QAAQ;IACf,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;AAC1D,CAAC;AAID,MAAa,QAAY,SAAQ,uBAAa;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,wBAAY,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,yBAAe,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;AArFD,4BAqFC;AA6BD;;;;;;;;;GASG;AACH,SAAgB,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;AAHD,4BAGC;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,uCAA6D;AAC7D,6CAA+D;AAC/D,2CAA6E;AAE7E,SAAS,QAAQ;IACf,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;AAC1D,CAAC;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAa,QAAY,SAAQ,uBAAa;IA6BrC,MAAM,CAAC,MAAM,CAAI,KAA0C,EAAE,GAAG,IAAW;QAChF,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC1B,OAAO,IAAA,yBAAe,EAAC,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,wBAAY,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;AAnFD,4BAmFC;AAkCD,SAAgB,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;AAHD,4BAGC;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"}