Skip to content

Commit

Permalink
fix(Rx): remove kitchenSink and DOM, let Rx exports all
Browse files Browse the repository at this point in the history
closes ReactiveX#1650

BREAKING CHANGE: `Rx.kitchenSink` and `Rx.DOM` are not removed, `Rx`
exports everything.
  • Loading branch information
kwonoj committed Apr 30, 2016
1 parent 56a12ba commit 11d69c3
Show file tree
Hide file tree
Showing 80 changed files with 130 additions and 173 deletions.
2 changes: 1 addition & 1 deletion .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ Thank you very much for your pull request!
If your PR is the addition of a new operator, please make sure all these boxes are ticked with an x:
- [ ] Add the operator to either Core or KitchenSink
- [ ] Add the operator to Rx
- [ ] It must have a `-spec.ts` tests file covering the canonical corner cases, with marble diagram tests
- [ ] If possible, write a `asDiagram` test case too, for PNG diagram generation purposes
- [ ] The spec file should have a type definition test at the end of the spec to verify type definition for various use cases
Expand Down
40 changes: 20 additions & 20 deletions doc/operator-creation.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Operator Creation

There are many ways to create an operator for RxJS. In this version of RxJS, performance was the primary consideration, as such, operator creation
in a way that adheres to the existing structures in this library may not be straight forward. This is an attempt to document how to
There are many ways to create an operator for RxJS. In this version of RxJS, performance was the primary consideration, as such, operator creation
in a way that adheres to the existing structures in this library may not be straight forward. This is an attempt to document how to
create an operator either for yourself, or for this library.

For how to develop a custom operator for *this* library, [see below](#advanced).
Expand All @@ -11,20 +11,20 @@ For how to develop a custom operator for *this* library, [see below](#advanced).

### Guidelines

In the most common case, users might like to create an operator to be used only by their app. These can be developed in
In the most common case, users might like to create an operator to be used only by their app. These can be developed in
any way the developer sees fit, but here are some guidelines:

1. __Operators should always return an Observable__. You're performing operations on unknown sets of things to create new sets.
It only makes sense to return a new set. If you create a method that returns something other than an Observable, it's not an operator,
and that's fine.
2. __Be sure to manage subscriptions__ created inside of the Observable your operator returns. Your operator is going to have to
subscribe to the source (or `this`) inside of the returned Observable, be sure that it's returned as part of unsubscribe handler or
subscribe to the source (or `this`) inside of the returned Observable, be sure that it's returned as part of unsubscribe handler or
subscription.
3. __Be sure to handle exceptions from passed functions__. If you're implementing an operator that takes a function as an argument,
3. __Be sure to handle exceptions from passed functions__. If you're implementing an operator that takes a function as an argument,
when you call it, you'll want to wrap it in a `try/catch` and send the error down the `error()` path on the observable.
4. __Be sure to teardown scarce resources__ in your unsubscribe handler of your returned Observable. If you're setting up event handlers
or a web socket, or something like that, the unsubscribe handler is a great place to remove that event handler or close that socket.



<!-- share-code-between-examples -->
Expand All @@ -36,7 +36,7 @@ function mySimpleOperator(someCallback) {
return Observable.create(subscriber => {
// because we're in an arrow function `this` is from the outer scope.
var source = this;

// save our inner subscription
var subscription = source.subscribe(value => {
// important: catch errors from user-provided callbacks
Expand All @@ -45,12 +45,12 @@ function mySimpleOperator(someCallback) {
} catch(err) {
subscriber.error(err);
}
},
},
// be sure to handle errors and completions as appropriate and
// send them along
err => subscriber.error(err),
() => subscriber.complete());

// to return now
return subscription;
});
Expand All @@ -77,10 +77,10 @@ class MyObservable extends Observable {
observable.operator = operator;
return observable;
}

// put it here .. or ..
customOperator() {
/* do things and return an Observable */
/* do things and return an Observable */
}
}

Expand All @@ -101,11 +101,11 @@ someObservable.mySimpleOperator(x => x + '!');

## <a id="advanced"></a>Creating An Operator For Inclusion In *This* Library

__To create an operator for inclusion in this library, it's probably best to work from prior art__. Something
__To create an operator for inclusion in this library, it's probably best to work from prior art__. Something
like the `filter` operator would be a good start. It's not expected that you'll be able to read
this section and suddenly be an expert operator contributor.

**If you find yourself confused, DO NOT worry. Follow prior examples in the repo, submit a PR, and we'll work with you.**
**If you find yourself confused, DO NOT worry. Follow prior examples in the repo, submit a PR, and we'll work with you.**

Hopefully the information provided here will give context to decisions made while developing operators in this library.
There are a few things to know and (try to) understand while developing operators:
Expand All @@ -114,15 +114,15 @@ There are a few things to know and (try to) understand while developing operator
"build their own observable" by pulling in operator methods an adding them to observable in their own module.
It also means operators can be brought in ad-hock and used directly, either with the ES7 function bind operator
in Babel (`::`) or by using it with `.call()`.
2. Every operator has an `Operator` class. The `Operator` class is really a `Subscriber` "factory". It's
what gets passed into the `lift` method to make the "magic" happen. It's sole job is to create the operation's
2. Every operator has an `Operator` class. The `Operator` class is really a `Subscriber` "factory". It's
what gets passed into the `lift` method to make the "magic" happen. It's sole job is to create the operation's
`Subscriber` instance on subscription.
3. Every operator has a `Subscriber` class. This class does *all* of the logic for the operation. It's job is to
handle values being nexted in (generally by overriding `_next()`) and forward it along to the `destination`,
3. Every operator has a `Subscriber` class. This class does *all* of the logic for the operation. It's job is to
handle values being nexted in (generally by overriding `_next()`) and forward it along to the `destination`,
which is the next observer in the chain.
- It's important to note that the `destination` Observer set on any `Subscriber` serves as more than just
the destinations for the events passing through, If the `destination` is a `Subscriber` it also is used to set up
a shared underlying `Subscription`, which, in fact, is also a `Subscriber`, and is the first `Subscriber` in the
a shared underlying `Subscription`, which, in fact, is also a `Subscriber`, and is the first `Subscriber` in the
chain.
- Subscribers all have `add` and `remove` methods that are used for adding and removing inner subscriptions to
the shared underlying subscription.
Expand All @@ -133,7 +133,7 @@ There are a few things to know and (try to) understand while developing operator

Please complete these steps for each new operator added to RxJS as a pull request:

- Add the operator to either Core or KitchenSink
- Add the operator to Rx
- It must have a `-spec.ts` tests file covering the canonical corner cases, with marble diagram tests
- If possible, write a `asDiagram` test case too, for PNG diagram generation purposes
- The spec file should have a type definition test at the end of the spec to verify type definition for various use cases
Expand All @@ -152,7 +152,7 @@ for their `unsubscribe` calls. Meaning if you call `unsubscribe` on them, it mig
not to set the `destination` of inner subscriptions. An example of this might be the switch operators, that have a single underlying
inner subscription that needs to unsubscribe independent of the main subscription.

If you find yourself creating inner subscriptions, it might also be worth checking to see if the observable being passed `_isScalar`,
If you find yourself creating inner subscriptions, it might also be worth checking to see if the observable being passed `_isScalar`,
because if it is, you can pull the `value` out of it directly and improve the performance of your operator when it's operating over
scalar observables. For reference a scalar observable is any observable that has a single static value underneath it. `Observable.of('foo')` will
return a `ScalarObservable`, likewise, resolved `PromiseObservable`s will act as scalars.
5 changes: 0 additions & 5 deletions doc/scripts/setup-rx-script.js

This file was deleted.

5 changes: 2 additions & 3 deletions esdoc.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,10 @@
"title": "RxJS",
"styles": ["./doc/styles/main.css"],
"scripts": [
"./dist/global/Rx.KitchenSink.umd.js",
"./dist/global/Rx.umd.js",
"./doc/asset/devtools-welcome.js",
"./doc/scripts/custom-manual-styles.js",
"./doc/decision-tree-widget/dist/decision-tree-widget.min.js",
"./doc/scripts/setup-rx-script.js"
"./doc/decision-tree-widget/dist/decision-tree-widget.min.js"
],
"index": "./doc/index.md",
"plugins": [
Expand Down
2 changes: 1 addition & 1 deletion index.js
Original file line number Diff line number Diff line change
@@ -1 +1 @@
module.exports = require('./dist/cjs/Rx.KitchenSink');
module.exports = require('./dist/cjs/Rx');
16 changes: 7 additions & 9 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,7 @@
"build_cjs": "Build CJS package with clean up existing build, copy source into dist",
"build_es6": "Build ES6 package with clean up existing build, copy source into dist",
"build_closure_core": "Minify Global core build using closure compiler",
"build_closure_kitchensink": "Minify Global kitchenSink build using closure compiler",
"build_global": "Build Global package, then minify core & kitchensink build",
"build_global": "Build Global package, then minify build",
"build_perf": "Build CJS & Global build, run macro performance test",
"build_test": "Build CJS package & test spec, execute mocha test runner",
"build_cover": "Run lint to current code, build CJS & test spec, execute test coverage",
Expand Down Expand Up @@ -55,8 +54,7 @@
"build_es6": "npm-run-all clean_dist_es6 copy_src_es6 compile_dist_es6",
"build_es6_for_docs": "npm-run-all clean_dist_es6 copy_src_es6 compile_dist_es6_for_docs",
"build_closure_core": "java -jar ./node_modules/google-closure-compiler/compiler.jar --js ./dist/global/Rx.umd.js --language_in ECMASCRIPT5 --create_source_map ./dist/global/Rx.umd.min.js.map --js_output_file ./dist/global/Rx.umd.min.js",
"build_closure_kitchensink": "java -jar ./node_modules/google-closure-compiler/compiler.jar --js ./dist/global/Rx.KitchenSink.umd.js --language_in ECMASCRIPT5 --create_source_map ./dist/global/Rx.KitchenSink.umd.min.js.map --js_output_file ./dist/global/Rx.KitchenSink.umd.min.js",
"build_global": "rm -rf ./dist/global && mkdirp ./dist/global && node tools/make-umd-bundle.js && node tools/make-system-bundle.js && npm-run-all build_closure_core build_closure_kitchensink",
"build_global": "rm -rf ./dist/global && mkdirp ./dist/global && node tools/make-umd-bundle.js && node tools/make-system-bundle.js && npm-run-all build_closure_core",
"build_perf": "webdriver-manager update && npm-run-all build_cjs build_global perf",
"build_test": "rm -rf ./dist/ && npm-run-all lint build_cjs clean_spec build_spec test_mocha",
"build_cover": "rm -rf ./dist/ && npm-run-all lint build_cjs build_spec cover",
Expand All @@ -72,12 +70,12 @@
"copy_src_cjs": "mkdirp ./dist/cjs/src && cp -r ./src/* ./dist/cjs/src",
"copy_src_es6": "mkdirp ./dist/es6/src && cp -r ./src/* ./dist/es6/src",
"commit": "git-cz",
"compile_dist_amd": "tsc typings/main/ambient/es6-shim/index.d.ts ./dist/amd/src/Rx.ts ./dist/amd/src/Rx.KitchenSink.ts ./dist/amd/src/Rx.DOM.ts ./dist/amd/src/add/observable/of.ts -m amd --sourceMap --outDir ./dist/amd --target ES5 --diagnostics --pretty --noImplicitAny --suppressImplicitAnyIndexErrors --moduleResolution node",
"compile_dist_cjs": "tsc typings/main/ambient/es6-shim/index.d.ts ./dist/cjs/src/Rx.ts ./dist/cjs/src/Rx.KitchenSink.ts ./dist/cjs/src/Rx.DOM.ts ./dist/cjs/src/add/observable/of.ts -m commonjs --sourceMap --outDir ./dist/cjs --target ES5 -d --diagnostics --pretty --noImplicitAny --suppressImplicitAnyIndexErrors --moduleResolution node",
"compile_dist_es6": "tsc ./dist/es6/src/Rx.ts ./dist/es6/src/Rx.KitchenSink.ts ./dist/es6/src/Rx.DOM.ts ./dist/es6/src/add/observable/of.ts -m es2015 --sourceMap --outDir ./dist/es6 --target ES6 -d --diagnostics --pretty --noImplicitAny --suppressImplicitAnyIndexErrors --moduleResolution node",
"compile_dist_es6_for_docs": "tsc ./dist/es6/src/Rx.ts ./dist/es6/src/Rx.KitchenSink.ts ./dist/es6/src/Rx.DOM.ts ./dist/es6/src/add/observable/of.ts ./dist/es6/src/MiscJSDoc.ts -m es2015 --sourceMap --outDir ./dist/es6 --target ES6 -d --diagnostics --pretty --noImplicitAny --suppressImplicitAnyIndexErrors --moduleResolution node",
"compile_dist_amd": "tsc typings/main/ambient/es6-shim/index.d.ts ./dist/amd/src/Rx.ts ./dist/amd/src/add/observable/of.ts -m amd --sourceMap --outDir ./dist/amd --target ES5 --diagnostics --pretty --noImplicitAny --suppressImplicitAnyIndexErrors --moduleResolution node",
"compile_dist_cjs": "tsc typings/main/ambient/es6-shim/index.d.ts ./dist/cjs/src/Rx.ts ./dist/cjs/src/add/observable/of.ts -m commonjs --sourceMap --outDir ./dist/cjs --target ES5 -d --diagnostics --pretty --noImplicitAny --suppressImplicitAnyIndexErrors --moduleResolution node",
"compile_dist_es6": "tsc ./dist/es6/src/Rx.ts ./dist/es6/src/add/observable/of.ts -m es2015 --sourceMap --outDir ./dist/es6 --target ES6 -d --diagnostics --pretty --noImplicitAny --suppressImplicitAnyIndexErrors --moduleResolution node",
"compile_dist_es6_for_docs": "tsc ./dist/es6/src/Rx.ts ./dist/es6/src/add/observable/of.ts ./dist/es6/src/MiscJSDoc.ts -m es2015 --sourceMap --outDir ./dist/es6 --target ES6 -d --diagnostics --pretty --noImplicitAny --suppressImplicitAnyIndexErrors --moduleResolution node",
"cover": "npm-run-all cover_test cover_remapping",
"cover_test": "rm -rf dist/cjs && tsc typings/main/ambient/es6-shim/index.d.ts src/Rx.ts src/Rx.KitchenSink.ts src/Rx.DOM.ts src/add/observable/of.ts -m commonjs --outDir dist/cjs --sourceMap --target ES5 -d && istanbul cover -x \"spec-js/**/*\" -x \"mocha-setup-node.js\" ./node_modules/mocha/bin/_mocha -- --opts spec/support/default.opts spec-js",
"cover_test": "rm -rf dist/cjs && tsc typings/main/ambient/es6-shim/index.d.ts src/Rx.ts src/add/observable/of.ts -m commonjs --outDir dist/cjs --sourceMap --target ES5 -d && istanbul cover -x \"spec-js/**/*\" -x \"mocha-setup-node.js\" ./node_modules/mocha/bin/_mocha -- --opts spec/support/default.opts spec-js",
"cover_remapping": "remap-istanbul -i coverage/coverage.json -o coverage/coverage-remapped.json && remap-istanbul -i coverage/coverage.json -o coverage/coverage-remapped.lcov -t lcovonly && remap-istanbul -i coverage/coverage.json -o coverage/coverage-remapped -t html",
"decision_tree_widget": "cd doc/decision-tree-widget && npm run build && cd ../..",
"generate_packages": "node .make-packages.js",
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
var RxOld = require('rx');
var RxNew = require('../../../../dist/cjs/Rx.KitchenSink');
var RxNew = require('../../../../dist/cjs/Rx');

module.exports = function (suite) {
var source = Array.from({ length: 25 }, function (_, i) { return { value: i % 3 }; });
Expand Down
2 changes: 1 addition & 1 deletion perf/micro/immediate-scheduler/operators/distinct.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
var RxOld = require('rx');
var RxNew = require('../../../../dist/cjs/Rx.KitchenSink');
var RxNew = require('../../../../dist/cjs/Rx');

module.exports = function (suite) {
var source = Array.from({ length: 25 }, function (_, i) { return i % 3; });
Expand Down
2 changes: 1 addition & 1 deletion spec/helpers/test-helper.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
declare const global: any;
declare const Symbol: any;

import * as Rx from '../../dist/cjs/Rx.KitchenSink';
import * as Rx from '../../dist/cjs/Rx';
import {root} from '../../dist/cjs/util/root';

export function lowerCaseO<T>(...args): Rx.Observable<T> {
Expand Down
2 changes: 1 addition & 1 deletion spec/helpers/testScheduler-ui.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import * as escapeRe from 'escape-string-regexp';
import * as chai from 'chai';
import * as sinonChai from 'sinon-chai';

import * as Rx from '../../dist/cjs/Rx.KitchenSink';
import * as Rx from '../../dist/cjs/Rx';
import * as marble from './marble-testing';

//setup sinon-chai
Expand Down
2 changes: 1 addition & 1 deletion spec/helpers/tests2png/diagram-test-runner.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
var root = require('../../../dist/cjs/util/root').root;
var Rx = require('../../../dist/cjs/Rx.KitchenSink');
var Rx = require('../../../dist/cjs/Rx');
var painter = require('./painter');

function getInputStreams(rxTestScheduler) {
Expand Down
2 changes: 1 addition & 1 deletion spec/observables/IteratorObservable-spec.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import {expect} from 'chai';
import * as Rx from '../../dist/cjs/Rx.KitchenSink';
import * as Rx from '../../dist/cjs/Rx';
import {IteratorObservable} from '../../dist/cjs/observable/IteratorObservable';

declare const expectObservable;
Expand Down
2 changes: 1 addition & 1 deletion spec/observables/ScalarObservable-spec.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import {expect} from 'chai';
import * as Rx from '../../dist/cjs/Rx.KitchenSink';
import * as Rx from '../../dist/cjs/Rx';
import {ScalarObservable} from '../../dist/cjs/observable/ScalarObservable';

declare const rxTestScheduler: Rx.TestScheduler;
Expand Down
2 changes: 1 addition & 1 deletion spec/observables/SubscribeOnObservable-spec.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import {expect} from 'chai';
import * as sinon from 'sinon';
import * as Rx from '../../dist/cjs/Rx.KitchenSink';
import * as Rx from '../../dist/cjs/Rx';
import {SubscribeOnObservable} from '../../dist/cjs/observable/SubscribeOnObservable';

declare const {hot, expectObservable, expectSubscriptions};
Expand Down
2 changes: 1 addition & 1 deletion spec/observables/bindCallback-spec.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import {expect} from 'chai';
import * as sinon from 'sinon';
import * as Rx from '../../dist/cjs/Rx.KitchenSink';
import * as Rx from '../../dist/cjs/Rx';

declare const rxTestScheduler: Rx.TestScheduler;
const Observable = Rx.Observable;
Expand Down
2 changes: 1 addition & 1 deletion spec/observables/bindNodeCallback-spec.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import {expect} from 'chai';
import * as sinon from 'sinon';
import * as Rx from '../../dist/cjs/Rx.KitchenSink';
import * as Rx from '../../dist/cjs/Rx';

declare const rxTestScheduler: Rx.TestScheduler;
const Observable = Rx.Observable;
Expand Down
2 changes: 1 addition & 1 deletion spec/observables/combineLatest-spec.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import {expect} from 'chai';
import * as Rx from '../../dist/cjs/Rx.KitchenSink';
import * as Rx from '../../dist/cjs/Rx';
declare const {hot, cold, expectObservable, expectSubscriptions};

const Observable = Rx.Observable;
Expand Down
2 changes: 1 addition & 1 deletion spec/observables/concat-spec.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import {expect} from 'chai';
import * as Rx from '../../dist/cjs/Rx.KitchenSink';
import * as Rx from '../../dist/cjs/Rx';
declare const {hot, cold, expectObservable, expectSubscriptions};

const Observable = Rx.Observable;
Expand Down
2 changes: 1 addition & 1 deletion spec/observables/dom/ajax-spec.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import {expect} from 'chai';
import * as Rx from '../../../dist/cjs/Rx.DOM';
import * as Rx from '../../../dist/cjs/Rx';
import {root} from '../../../dist/cjs/util/root';
import {MockXMLHttpRequest} from '../../helpers/ajax-helper';

Expand Down
2 changes: 1 addition & 1 deletion spec/observables/dom/webSocket-spec.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import {expect} from 'chai';
import * as sinon from 'sinon';
import * as Rx from '../../../dist/cjs/Rx.DOM';
import * as Rx from '../../../dist/cjs/Rx';
import {MockWebSocket} from '../../helpers/ajax-helper';

declare const __root__: any;
Expand Down
2 changes: 1 addition & 1 deletion spec/observables/forkJoin-spec.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import {expect} from 'chai';
import * as Rx from '../../dist/cjs/Rx.KitchenSink';
import * as Rx from '../../dist/cjs/Rx';
declare const {hot, expectObservable, expectSubscriptions};
import {lowerCaseO} from '../helpers/test-helper';

Expand Down
2 changes: 1 addition & 1 deletion spec/observables/from-spec.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import {expect} from 'chai';
import * as Rx from '../../dist/cjs/Rx.KitchenSink';
import * as Rx from '../../dist/cjs/Rx';
import {$$iterator} from '../../dist/cjs/symbol/iterator';

declare const {asDiagram, expectObservable, Symbol, type};
Expand Down
2 changes: 1 addition & 1 deletion spec/observables/fromEvent-spec.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import {expect} from 'chai';
import * as Rx from '../../dist/cjs/Rx.KitchenSink';
import * as Rx from '../../dist/cjs/Rx';

declare const rxTestScheduler: Rx.TestScheduler;
declare const {hot, asDiagram, expectObservable, expectSubscriptions};
Expand Down
2 changes: 1 addition & 1 deletion spec/observables/fromEventPattern-spec.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import {expect} from 'chai';
import * as Rx from '../../dist/cjs/Rx.KitchenSink';
import * as Rx from '../../dist/cjs/Rx';

declare const rxTestScheduler: Rx.TestScheduler;
declare const {hot, asDiagram, expectObservable, expectSubscriptions};
Expand Down
Loading

0 comments on commit 11d69c3

Please sign in to comment.