diff --git a/dist/MeteorObservable.d.ts b/dist/MeteorObservable.d.ts index 6f9eca4b..d9ee1d2d 100644 --- a/dist/MeteorObservable.d.ts +++ b/dist/MeteorObservable.d.ts @@ -1,6 +1,108 @@ import { Observable } from 'rxjs'; +/** + * A class with static methods, which wraps Meteor's API and returns + * RxJS Observable as return value for all Meteor's API. + * The method's signature is the same as Metoer's, except you don't + * need to provide callbacks, and you need to "subscribe" instead. + * The functionality that wrapped in this implementation is Meteor.call, + * Meteor.autorun and Meteor.subscribe. + * + */ export declare class MeteorObservable { + /** + * Method has the same notation as Meteor.call, only without the callbacks: + * MeteorObservable.call(name, [...args]) + * + * @param {String} name - Name of the method in the Meteor server + * @param {any} args - Parameters that will be forwarded to the method. + * after the func call to initiate change detection. + * @returns {Observable} - RxJS Observable, which completes when the server return a response. + * @example Example using Angular2 Component + * class MyComponent { + * constructor() { + * + * } + * + * doAction(payload) { + * MeteorObservable.call("myData", payload).subscribe((response) => { + * // Handle success and response from server! + * }, (err) => { + * // Handle error + * }); + * } + * } + */ static call(name: string, ...args: any[]): Observable; + /** + * Method has the same notation as Meteor.subscribe, only without the callbacks: + * subscribe(name, [...args]) + * + * You can use this method from any Angular2 element - such as Component, Pipe or + * Service. + * + * @param {String} name - Name of the publication in the Meteor server + * @param {any} args - Parameters that will be forwarded to the publication. + * after the func call to initiate change detection. + * @returns {Observable} - RxJS Observable, which completes when the subscription is ready. + * @example Example using Angular2 Service + * class MyService { + * private meteorSubscription: Observable; + * + * constructor() { + * + * } + * + * subscribeToData() { + * this.meteorSubscription = MeteorObservable.subscribe("myData").subscribe(() => { + * // Subscription is ready! + * }); + * } + * + * unsubscribeToData() { + * this.meteorSubscription.unsubscribe(); + * } + * } + * + * @example Example using Angular2 Component + * class MyComponent implements OnInit, OnDestroy { + * private meteorSubscription: Observable; + * + * constructor() { + * + * } + * + * ngOnInit() { + * this.meteorSubscription = MeteorObservable.subscribe("myData").subscribe(() => { + * // Subscription is ready! + * }); + * } + * + * ngOnDestroy() { + * this.meteorSubscription.unsubscribe(); + * } + * } + * + * @see {@link http://docs.meteor.com/api/pubsub.html|Publications in Meteor documentation} + */ static subscribe(name: string, ...args: any[]): Observable; + /** + * Method has the same notation as Meteor.autorun, only without the callback: + * MeteorObservable.autorun() + * + * @returns {Observable} - RxJS Observable, which trigger the subscription callback + * each time that Meteor Tracker detects a change. + * @example Example using Angular2 Component + * class MyComponent { + * constructor() { + * + * } + * + * doAction(payload) { + * MeteorObservable.autorun().subscribe(() => { + * // Handle Tracker autorun change + * }); + * } + * } + */ static autorun(): Observable; } diff --git a/dist/MeteorObservable.js b/dist/MeteorObservable.js index b14a1ff9..f251b88a 100644 --- a/dist/MeteorObservable.js +++ b/dist/MeteorObservable.js @@ -4,9 +4,41 @@ import { isMeteorCallbacks, forkZone, removeObserver } from './utils'; function throwInvalidCallback(method) { throw new Error("Invalid " + method + " arguments:\n your last param can't be a callback function, \n please remove it and use \".subscribe\" of the Observable!"); } +/** + * A class with static methods, which wraps Meteor's API and returns + * RxJS Observable as return value for all Meteor's API. + * The method's signature is the same as Metoer's, except you don't + * need to provide callbacks, and you need to "subscribe" instead. + * The functionality that wrapped in this implementation is Meteor.call, + * Meteor.autorun and Meteor.subscribe. + * + */ export var MeteorObservable = (function () { function MeteorObservable() { } + /** + * Method has the same notation as Meteor.call, only without the callbacks: + * MeteorObservable.call(name, [...args]) + * + * @param {String} name - Name of the method in the Meteor server + * @param {any} args - Parameters that will be forwarded to the method. + * after the func call to initiate change detection. + * @returns {Observable} - RxJS Observable, which completes when the server return a response. + * @example Example using Angular2 Component + * class MyComponent { + * constructor() { + * + * } + * + * doAction(payload) { + * MeteorObservable.call("myData", payload).subscribe((response) => { + * // Handle success and response from server! + * }, (err) => { + * // Handle error + * }); + * } + * } + */ MeteorObservable.call = function (name) { var args = []; for (var _i = 1; _i < arguments.length; _i++) { @@ -29,6 +61,57 @@ export var MeteorObservable = (function () { ]))); }); }; + /** + * Method has the same notation as Meteor.subscribe, only without the callbacks: + * subscribe(name, [...args]) + * + * You can use this method from any Angular2 element - such as Component, Pipe or + * Service. + * + * @param {String} name - Name of the publication in the Meteor server + * @param {any} args - Parameters that will be forwarded to the publication. + * after the func call to initiate change detection. + * @returns {Observable} - RxJS Observable, which completes when the subscription is ready. + * @example Example using Angular2 Service + * class MyService { + * private meteorSubscription: Observable; + * + * constructor() { + * + * } + * + * subscribeToData() { + * this.meteorSubscription = MeteorObservable.subscribe("myData").subscribe(() => { + * // Subscription is ready! + * }); + * } + * + * unsubscribeToData() { + * this.meteorSubscription.unsubscribe(); + * } + * } + * + * @example Example using Angular2 Component + * class MyComponent implements OnInit, OnDestroy { + * private meteorSubscription: Observable; + * + * constructor() { + * + * } + * + * ngOnInit() { + * this.meteorSubscription = MeteorObservable.subscribe("myData").subscribe(() => { + * // Subscription is ready! + * }); + * } + * + * ngOnDestroy() { + * this.meteorSubscription.unsubscribe(); + * } + * } + * + * @see {@link http://docs.meteor.com/api/pubsub.html|Publications in Meteor documentation} + */ MeteorObservable.subscribe = function (name) { var args = []; for (var _i = 1; _i < arguments.length; _i++) { @@ -67,6 +150,25 @@ export var MeteorObservable = (function () { }; }); }; + /** + * Method has the same notation as Meteor.autorun, only without the callback: + * MeteorObservable.autorun() + * + * @returns {Observable} - RxJS Observable, which trigger the subscription callback + * each time that Meteor Tracker detects a change. + * @example Example using Angular2 Component + * class MyComponent { + * constructor() { + * + * } + * + * doAction(payload) { + * MeteorObservable.autorun().subscribe(() => { + * // Handle Tracker autorun change + * }); + * } + * } + */ MeteorObservable.autorun = function () { var zone = forkZone(); var observers = []; diff --git a/dist/ObservableCollection.d.ts b/dist/ObservableCollection.d.ts index 1d3f0133..eeae053f 100644 --- a/dist/ObservableCollection.d.ts +++ b/dist/ObservableCollection.d.ts @@ -18,24 +18,136 @@ export declare module MongoObservable { fetch?: string[]; transform?: Function; } - function fromExisting(collection: Mongo.Collection): Collection; + /** + * Creates a new MongoObservable.Collection from an existing of predefined Mongo.Collection. + * Use this feature to wrap existing collections such as Meteor.users. + * @param {Mongo.Collection} collection - The collection. + * @returns {MongoObservable.Collection} - Wrapped collection. + * @static + */ + function fromExisting(collection: Mongo.Collection): MongoObservable.Collection; + /** + * A class represents a MongoDB collection in the client side, wrapped with RxJS + * Observables, so you can use it with your Angular 2 easier. + * The wrapper has the same API as Mongo.Collection, only the "find" method returns + * an ObservableCursor instead of regular Mongo.Cursor. + * + * T is a generic type - should be used with the type of the objects inside the collection. + */ class Collection { private _collection; + /** + * Creates a new Mongo.Collection instance wrapped with Observable features. + * @param {String | Mongo.Collection} nameOrExisting - The name of the collection. If null, creates an + * unmanaged (unsynchronized) local collection. If provided an instance of existing collection, will + * create a wrapper for the existing Mongo.Collection. + * @param {ConstructorOptions} options - Creation options. + * @constructor + */ constructor(nameOrExisting: string | Mongo.Collection, options?: ConstructorOptions); + /** + * Returns the Mongo.Collection object that wrapped with the MongoObservable.Collection. + * @returns {Mongo.Collection} The Collection instance + */ readonly collection: Mongo.Collection; + /** + * Allow users to write directly to this collection from client code, subject to limitations you define. + * + * @returns {Boolean} + */ allow(options: AllowDenyOptionsObject): boolean; + /** + * Override allow rules. + * + * @returns {Boolean} + */ deny(options: AllowDenyOptionsObject): boolean; + /** + * Returns the Collection object corresponding to this collection from the npm + * mongodb driver module which is wrapped by Mongo.Collection. + * + * @returns {Mongo.Collection} The Collection instance + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-rawCollection|rawCollection on Meteor documentation} + */ rawCollection(): any; + /** + * Returns the Db object corresponding to this collection's database connection from the + * npm mongodb driver module which is wrapped by Mongo.Collection. + * + * @returns {Mongo.Db} The Db instance + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-rawDatabase|rawDatabase on Meteor documentation} + */ rawDatabase(): any; + /** + * Insert a document in the collection. + * + * @param {T} doc - The document to insert. May not yet have an _id + * attribute, in which case Meteor will generate one for you. + * @returns {Observable} Observable which completes with the inserted ObjectId + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-insert|insert on Meteor documentation} + */ insert(doc: T): Observable; + /** + * Remove documents from the collection. + * + * @param {Collection~MongoQuerySelector} selector - Specifies which documents to modify + * @returns {Observable} Observable which completes with the number of affected rows + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-remove|remove on Meteor documentation} + */ remove(selector: Selector | ObjectID | string): Observable; + /** + * Modify one or more documents in the collection. + * + * @param {Collection~MongoQuerySelector} selector - Specifies which documents to modify + * @param {Modifier} modifier - Specifies how to modify the documents + * @param {MongoUpdateOptions} options - Update options + * first argument and, if no error, the number of affected documents as the second + * @returns {Observable} Observable which completes with the number of affected rows + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-update|update on Meteor documentation} + */ update(selector: Selector | ObjectID | string, modifier: Modifier, options?: { multi?: boolean; upsert?: boolean; }): Observable; + /** + * Finds the first document that matches the selector, as ordered by sort and skip options. + * + * @param {Collection~MongoQuerySelector} selector - Specifies which documents to modify + * @param {Modifier} modifier - Specifies how to modify the documents + * @param {MongoUpsertOptions} options - Upsert options + * first argument and, if no error, the number of affected documents as the second. + * @returns {Observable<{numberAffected, insertedId}>} Observable which completes with an + * Object that contain the keys numberAffected and insertedId. + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-upsert|upsert on Meteor documentation} + */ upsert(selector: Selector | ObjectID | string, modifier: Modifier, options?: { multi?: boolean; }): Observable; + /** + * Method has the same notation as Mongo.Collection.find, only returns Observable. + * + * @param {Collection~MongoQuerySelector} selector - A query describing the documents to find + * @param {Collection~MongoQueryOptions} options - Query options, such as sort, limit, etc. + * @returns {ObservableCursor} RxJS Observable wrapped with Meteor features. + * @example Using Angular2 Component + * const MyCollection = MongoObservable.Collection("myCollection"); + * + * class MyComponent { + * private myData: ObservableCursor; + * + * constructor() { + * this.myData = MyCollection.find({}, {limit: 10}); + * } + * } + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-find|find on Meteor documentation} + */ find(selector?: Selector | ObjectID | string, options?: { sort?: SortSpecifier; skip?: number; @@ -44,6 +156,15 @@ export declare module MongoObservable { reactive?: boolean; transform?: Function; }): ObservableCursor; + /** + * Finds the first document that matches the selector, as ordered by sort and skip options. + * + * @param {Collection~MongoQuerySelector} selector - A query describing the documents to find + * @param {Collection~MongoQueryOptions} options - Query options, such as sort, limit, etc. + * @returns {any} The first object, or `undefined` in case of non-existing object. + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-findOne|findOne on Meteor documentation} + */ findOne(selector?: Selector | ObjectID | string, options?: { sort?: SortSpecifier; skip?: number; diff --git a/dist/ObservableCollection.js b/dist/ObservableCollection.js index 08d45f55..c8a91e1c 100644 --- a/dist/ObservableCollection.js +++ b/dist/ObservableCollection.js @@ -4,11 +4,34 @@ import { removeObserver } from './utils'; export var MongoObservable; (function (MongoObservable) { 'use strict'; + /** + * Creates a new MongoObservable.Collection from an existing of predefined Mongo.Collection. + * Use this feature to wrap existing collections such as Meteor.users. + * @param {Mongo.Collection} collection - The collection. + * @returns {MongoObservable.Collection} - Wrapped collection. + * @static + */ function fromExisting(collection) { return new MongoObservable.Collection(collection); } MongoObservable.fromExisting = fromExisting; + /** + * A class represents a MongoDB collection in the client side, wrapped with RxJS + * Observables, so you can use it with your Angular 2 easier. + * The wrapper has the same API as Mongo.Collection, only the "find" method returns + * an ObservableCursor instead of regular Mongo.Cursor. + * + * T is a generic type - should be used with the type of the objects inside the collection. + */ var Collection = (function () { + /** + * Creates a new Mongo.Collection instance wrapped with Observable features. + * @param {String | Mongo.Collection} nameOrExisting - The name of the collection. If null, creates an + * unmanaged (unsynchronized) local collection. If provided an instance of existing collection, will + * create a wrapper for the existing Mongo.Collection. + * @param {ConstructorOptions} options - Creation options. + * @constructor + */ function Collection(nameOrExisting, options) { if (nameOrExisting instanceof Mongo.Collection) { this._collection = nameOrExisting; @@ -18,24 +41,63 @@ export var MongoObservable; } } Object.defineProperty(Collection.prototype, "collection", { + /** + * Returns the Mongo.Collection object that wrapped with the MongoObservable.Collection. + * @returns {Mongo.Collection} The Collection instance + */ get: function () { return this._collection; }, enumerable: true, configurable: true }); + /** + * Allow users to write directly to this collection from client code, subject to limitations you define. + * + * @returns {Boolean} + */ Collection.prototype.allow = function (options) { return this._collection.allow(options); }; + /** + * Override allow rules. + * + * @returns {Boolean} + */ Collection.prototype.deny = function (options) { return this._collection.deny(options); }; + /** + * Returns the Collection object corresponding to this collection from the npm + * mongodb driver module which is wrapped by Mongo.Collection. + * + * @returns {Mongo.Collection} The Collection instance + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-rawCollection|rawCollection on Meteor documentation} + */ Collection.prototype.rawCollection = function () { return this._collection.rawCollection(); }; + /** + * Returns the Db object corresponding to this collection's database connection from the + * npm mongodb driver module which is wrapped by Mongo.Collection. + * + * @returns {Mongo.Db} The Db instance + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-rawDatabase|rawDatabase on Meteor documentation} + */ Collection.prototype.rawDatabase = function () { return this._collection.rawDatabase(); }; + /** + * Insert a document in the collection. + * + * @param {T} doc - The document to insert. May not yet have an _id + * attribute, in which case Meteor will generate one for you. + * @returns {Observable} Observable which completes with the inserted ObjectId + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-insert|insert on Meteor documentation} + */ Collection.prototype.insert = function (doc) { var observers = []; var obs = this._createObservable(observers); @@ -48,6 +110,14 @@ export var MongoObservable; }); return obs; }; + /** + * Remove documents from the collection. + * + * @param {Collection~MongoQuerySelector} selector - Specifies which documents to modify + * @returns {Observable} Observable which completes with the number of affected rows + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-remove|remove on Meteor documentation} + */ Collection.prototype.remove = function (selector) { var observers = []; var obs = this._createObservable(observers); @@ -60,6 +130,17 @@ export var MongoObservable; }); return obs; }; + /** + * Modify one or more documents in the collection. + * + * @param {Collection~MongoQuerySelector} selector - Specifies which documents to modify + * @param {Modifier} modifier - Specifies how to modify the documents + * @param {MongoUpdateOptions} options - Update options + * first argument and, if no error, the number of affected documents as the second + * @returns {Observable} Observable which completes with the number of affected rows + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-update|update on Meteor documentation} + */ Collection.prototype.update = function (selector, modifier, options) { var observers = []; var obs = this._createObservable(observers); @@ -72,6 +153,18 @@ export var MongoObservable; }); return obs; }; + /** + * Finds the first document that matches the selector, as ordered by sort and skip options. + * + * @param {Collection~MongoQuerySelector} selector - Specifies which documents to modify + * @param {Modifier} modifier - Specifies how to modify the documents + * @param {MongoUpsertOptions} options - Upsert options + * first argument and, if no error, the number of affected documents as the second. + * @returns {Observable<{numberAffected, insertedId}>} Observable which completes with an + * Object that contain the keys numberAffected and insertedId. + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-upsert|upsert on Meteor documentation} + */ Collection.prototype.upsert = function (selector, modifier, options) { var observers = []; var obs = this._createObservable(observers); @@ -84,10 +177,38 @@ export var MongoObservable; }); return obs; }; + /** + * Method has the same notation as Mongo.Collection.find, only returns Observable. + * + * @param {Collection~MongoQuerySelector} selector - A query describing the documents to find + * @param {Collection~MongoQueryOptions} options - Query options, such as sort, limit, etc. + * @returns {ObservableCursor} RxJS Observable wrapped with Meteor features. + * @example Using Angular2 Component + * const MyCollection = MongoObservable.Collection("myCollection"); + * + * class MyComponent { + * private myData: ObservableCursor; + * + * constructor() { + * this.myData = MyCollection.find({}, {limit: 10}); + * } + * } + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-find|find on Meteor documentation} + */ Collection.prototype.find = function (selector, options) { var cursor = this._collection.find.apply(this._collection, arguments); return ObservableCursor.create(cursor); }; + /** + * Finds the first document that matches the selector, as ordered by sort and skip options. + * + * @param {Collection~MongoQuerySelector} selector - A query describing the documents to find + * @param {Collection~MongoQueryOptions} options - Query options, such as sort, limit, etc. + * @returns {any} The first object, or `undefined` in case of non-existing object. + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-findOne|findOne on Meteor documentation} + */ Collection.prototype.findOne = function (selector, options) { return this._collection.findOne.apply(this._collection, arguments); }; @@ -103,3 +224,28 @@ export var MongoObservable; }()); MongoObservable.Collection = Collection; })(MongoObservable || (MongoObservable = {})); +/** + * An options object for MongoDB queries. + * @typedef {Object} Collection~MongoQueryOptions + * @property {Object} sort - Sort order (default: natural order) + * @property {Number} skip - Number of results to skip at the beginning + * @property {Object} fields - Dictionary of fields to return or exclude. + * @property {Boolean} reactive - (Client only) Default true; pass false to disable reactivity + * @property {Function} transform - Overrides transform on the Collection for this cursor. Pass null to disable transformation. + */ +/** + * A MongoDB query selector representation. + * @typedef {(Mongo.Selector|Mongo.ObjectID|string)} Collection~MongoQuerySelector + */ +/** + * A MongoDB query options for upsert action + * @typedef {Object} Collection~MongoUpsertOptions + * @property {Boolean} multi - True to modify all matching documents; + * false to only modify one of the matching documents (the default). + */ +/** + * A MongoDB query options for update action + * @typedef {Object} Collection~MongoUpdateOptions + * @property {Boolean} multi - True to modify all matching documents; + * @property {Boolean} upsert - True to use upsert logic. + */ diff --git a/dist/ObservableCursor.d.ts b/dist/ObservableCursor.d.ts index 88a53237..c91d96f1 100644 --- a/dist/ObservableCursor.d.ts +++ b/dist/ObservableCursor.d.ts @@ -1,4 +1,8 @@ import { Observable } from 'rxjs'; +/** + * A class represents a Monog.Cursor wrapped with RxJS features. + * @extends Observable + */ export declare class ObservableCursor extends Observable { private _zone; private _data; @@ -6,14 +10,61 @@ export declare class ObservableCursor extends Observable { private _hCursor; private _observers; private _countObserver; + /** + * Static method which creates an ObservableCursor from Mongo.Cursor. + * Use this to create an ObservableCursor object from an existing Mongo.Cursor. + * Prefer to create an Cursors from the ObservableCollection instance instead. + * + * @param {Mongo.Cursor} cursor - The Mongo.Cursor to wrap. + * @returns {ObservableCursor} Wrapped Cursor. + */ static create(cursor: Mongo.Cursor): ObservableCursor; + /** + * @constructor + * @extends Observable + * @param {Mongo.Cursor} cursor - The Mongo.Cursor to wrap. + */ constructor(cursor: Mongo.Cursor); + /** + * Returns the actual Mongo.Cursor that wrapped by current ObservableCursor instance. + * @return {Mongo.Cursor} The actual MongoDB Cursor. + */ readonly cursor: Mongo.Cursor; + /** + * A wrapper for Mongo.Cursor.count() method - returns an Observable of number, which + * triggers each time there is a change in the collection, and exposes the number of + * objects in the collection. + * @returns {Observable} Observable which trigger the callback when the + * count of the object changes. + */ collectionCount(): Observable; + /** + * Stops the observation on the cursor. + */ stop(): void; + /** + * Clears the Observable definition. + * Use this method only when the Observable is still cold, and there are no active subscriptions yet. + */ dispose(): void; + /** + * Return all matching documents as an Array. + * + * @return {Array} The array with the matching documents. + */ fetch(): Array; + /** + * Watch a query. Receive callbacks as the result set changes. + * @param {Mongo.ObserveCallbacks} callbacks - The callbacks object. + * @return {Meteor.LiveQueryHandle} The array with the matching documents. + */ observe(callbacks: Mongo.ObserveCallbacks): Meteor.LiveQueryHandle; + /** + * Watch a query. Receive callbacks as the result set changes. + * Only the differences between the old and new documents are passed to the callbacks. + * @param {Mongo.ObserveChangesCallbacks} callbacks - The callbacks object. + * @return {Meteor.LiveQueryHandle} The array with the matching documents. + */ observeChanges(callbacks: Mongo.ObserveChangesCallbacks): Meteor.LiveQueryHandle; _runComplete(): void; _runNext(data: Array): void; diff --git a/dist/ObservableCursor.js b/dist/ObservableCursor.js index 253480d8..42c300e9 100644 --- a/dist/ObservableCursor.js +++ b/dist/ObservableCursor.js @@ -1,8 +1,17 @@ 'use strict'; import { Observable, Subject } from 'rxjs'; import { gZone, forkZone, removeObserver } from './utils'; +/** + * A class represents a Monog.Cursor wrapped with RxJS features. + * @extends Observable + */ export var ObservableCursor = (function (_super) { __extends(ObservableCursor, _super); + /** + * @constructor + * @extends Observable + * @param {Mongo.Cursor} cursor - The Mongo.Cursor to wrap. + */ function ObservableCursor(cursor) { var _this = this; _super.call(this, function (observer) { @@ -21,19 +30,41 @@ export var ObservableCursor = (function (_super) { this._cursor = cursor; this._zone = forkZone(); } + /** + * Static method which creates an ObservableCursor from Mongo.Cursor. + * Use this to create an ObservableCursor object from an existing Mongo.Cursor. + * Prefer to create an Cursors from the ObservableCollection instance instead. + * + * @param {Mongo.Cursor} cursor - The Mongo.Cursor to wrap. + * @returns {ObservableCursor} Wrapped Cursor. + */ ObservableCursor.create = function (cursor) { return new ObservableCursor(cursor); }; Object.defineProperty(ObservableCursor.prototype, "cursor", { + /** + * Returns the actual Mongo.Cursor that wrapped by current ObservableCursor instance. + * @return {Mongo.Cursor} The actual MongoDB Cursor. + */ get: function () { return this._cursor; }, enumerable: true, configurable: true }); + /** + * A wrapper for Mongo.Cursor.count() method - returns an Observable of number, which + * triggers each time there is a change in the collection, and exposes the number of + * objects in the collection. + * @returns {Observable} Observable which trigger the callback when the + * count of the object changes. + */ ObservableCursor.prototype.collectionCount = function () { return this._countObserver.asObservable(); }; + /** + * Stops the observation on the cursor. + */ ObservableCursor.prototype.stop = function () { var _this = this; this._zone.run(function () { @@ -45,16 +76,36 @@ export var ObservableCursor = (function (_super) { this._data = []; this._hCursor = null; }; + /** + * Clears the Observable definition. + * Use this method only when the Observable is still cold, and there are no active subscriptions yet. + */ ObservableCursor.prototype.dispose = function () { this._observers = null; this._cursor = null; }; + /** + * Return all matching documents as an Array. + * + * @return {Array} The array with the matching documents. + */ ObservableCursor.prototype.fetch = function () { return this._cursor.fetch(); }; + /** + * Watch a query. Receive callbacks as the result set changes. + * @param {Mongo.ObserveCallbacks} callbacks - The callbacks object. + * @return {Meteor.LiveQueryHandle} The array with the matching documents. + */ ObservableCursor.prototype.observe = function (callbacks) { return this._cursor.observe(callbacks); }; + /** + * Watch a query. Receive callbacks as the result set changes. + * Only the differences between the old and new documents are passed to the callbacks. + * @param {Mongo.ObserveChangesCallbacks} callbacks - The callbacks object. + * @return {Meteor.LiveQueryHandle} The array with the matching documents. + */ ObservableCursor.prototype.observeChanges = function (callbacks) { return this._cursor.observeChanges(callbacks); }; diff --git a/dist/bundles/index.umd.js b/dist/bundles/index.umd.js index dd611fc5..e8d0d121 100644 --- a/dist/bundles/index.umd.js +++ b/dist/bundles/index.umd.js @@ -56,8 +56,17 @@ function removeObserver(observers, observer, onEmpty) { } var gZone = g.Zone ? g.Zone.current : fakeZone; +/** + * A class represents a Monog.Cursor wrapped with RxJS features. + * @extends Observable + */ var ObservableCursor = (function (_super) { __extends(ObservableCursor, _super); + /** + * @constructor + * @extends Observable + * @param {Mongo.Cursor} cursor - The Mongo.Cursor to wrap. + */ function ObservableCursor(cursor) { var _this = this; _super.call(this, function (observer) { @@ -76,19 +85,41 @@ var ObservableCursor = (function (_super) { this._cursor = cursor; this._zone = forkZone(); } + /** + * Static method which creates an ObservableCursor from Mongo.Cursor. + * Use this to create an ObservableCursor object from an existing Mongo.Cursor. + * Prefer to create an Cursors from the ObservableCollection instance instead. + * + * @param {Mongo.Cursor} cursor - The Mongo.Cursor to wrap. + * @returns {ObservableCursor} Wrapped Cursor. + */ ObservableCursor.create = function (cursor) { return new ObservableCursor(cursor); }; Object.defineProperty(ObservableCursor.prototype, "cursor", { + /** + * Returns the actual Mongo.Cursor that wrapped by current ObservableCursor instance. + * @return {Mongo.Cursor} The actual MongoDB Cursor. + */ get: function () { return this._cursor; }, enumerable: true, configurable: true }); + /** + * A wrapper for Mongo.Cursor.count() method - returns an Observable of number, which + * triggers each time there is a change in the collection, and exposes the number of + * objects in the collection. + * @returns {Observable} Observable which trigger the callback when the + * count of the object changes. + */ ObservableCursor.prototype.collectionCount = function () { return this._countObserver.asObservable(); }; + /** + * Stops the observation on the cursor. + */ ObservableCursor.prototype.stop = function () { var _this = this; this._zone.run(function () { @@ -100,16 +131,36 @@ var ObservableCursor = (function (_super) { this._data = []; this._hCursor = null; }; + /** + * Clears the Observable definition. + * Use this method only when the Observable is still cold, and there are no active subscriptions yet. + */ ObservableCursor.prototype.dispose = function () { this._observers = null; this._cursor = null; }; + /** + * Return all matching documents as an Array. + * + * @return {Array} The array with the matching documents. + */ ObservableCursor.prototype.fetch = function () { return this._cursor.fetch(); }; + /** + * Watch a query. Receive callbacks as the result set changes. + * @param {Mongo.ObserveCallbacks} callbacks - The callbacks object. + * @return {Meteor.LiveQueryHandle} The array with the matching documents. + */ ObservableCursor.prototype.observe = function (callbacks) { return this._cursor.observe(callbacks); }; + /** + * Watch a query. Receive callbacks as the result set changes. + * Only the differences between the old and new documents are passed to the callbacks. + * @param {Mongo.ObserveChangesCallbacks} callbacks - The callbacks object. + * @return {Meteor.LiveQueryHandle} The array with the matching documents. + */ ObservableCursor.prototype.observeChanges = function (callbacks) { return this._cursor.observeChanges(callbacks); }; @@ -166,11 +217,34 @@ var ObservableCursor = (function (_super) { (function (MongoObservable) { 'use strict'; + /** + * Creates a new MongoObservable.Collection from an existing of predefined Mongo.Collection. + * Use this feature to wrap existing collections such as Meteor.users. + * @param {Mongo.Collection} collection - The collection. + * @returns {MongoObservable.Collection} - Wrapped collection. + * @static + */ function fromExisting(collection) { return new MongoObservable.Collection(collection); } MongoObservable.fromExisting = fromExisting; + /** + * A class represents a MongoDB collection in the client side, wrapped with RxJS + * Observables, so you can use it with your Angular 2 easier. + * The wrapper has the same API as Mongo.Collection, only the "find" method returns + * an ObservableCursor instead of regular Mongo.Cursor. + * + * T is a generic type - should be used with the type of the objects inside the collection. + */ var Collection = (function () { + /** + * Creates a new Mongo.Collection instance wrapped with Observable features. + * @param {String | Mongo.Collection} nameOrExisting - The name of the collection. If null, creates an + * unmanaged (unsynchronized) local collection. If provided an instance of existing collection, will + * create a wrapper for the existing Mongo.Collection. + * @param {ConstructorOptions} options - Creation options. + * @constructor + */ function Collection(nameOrExisting, options) { if (nameOrExisting instanceof Mongo.Collection) { this._collection = nameOrExisting; @@ -180,24 +254,63 @@ var ObservableCursor = (function (_super) { } } Object.defineProperty(Collection.prototype, "collection", { + /** + * Returns the Mongo.Collection object that wrapped with the MongoObservable.Collection. + * @returns {Mongo.Collection} The Collection instance + */ get: function () { return this._collection; }, enumerable: true, configurable: true }); + /** + * Allow users to write directly to this collection from client code, subject to limitations you define. + * + * @returns {Boolean} + */ Collection.prototype.allow = function (options) { return this._collection.allow(options); }; + /** + * Override allow rules. + * + * @returns {Boolean} + */ Collection.prototype.deny = function (options) { return this._collection.deny(options); }; + /** + * Returns the Collection object corresponding to this collection from the npm + * mongodb driver module which is wrapped by Mongo.Collection. + * + * @returns {Mongo.Collection} The Collection instance + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-rawCollection|rawCollection on Meteor documentation} + */ Collection.prototype.rawCollection = function () { return this._collection.rawCollection(); }; + /** + * Returns the Db object corresponding to this collection's database connection from the + * npm mongodb driver module which is wrapped by Mongo.Collection. + * + * @returns {Mongo.Db} The Db instance + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-rawDatabase|rawDatabase on Meteor documentation} + */ Collection.prototype.rawDatabase = function () { return this._collection.rawDatabase(); }; + /** + * Insert a document in the collection. + * + * @param {T} doc - The document to insert. May not yet have an _id + * attribute, in which case Meteor will generate one for you. + * @returns {Observable} Observable which completes with the inserted ObjectId + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-insert|insert on Meteor documentation} + */ Collection.prototype.insert = function (doc) { var observers = []; var obs = this._createObservable(observers); @@ -210,6 +323,14 @@ var ObservableCursor = (function (_super) { }); return obs; }; + /** + * Remove documents from the collection. + * + * @param {Collection~MongoQuerySelector} selector - Specifies which documents to modify + * @returns {Observable} Observable which completes with the number of affected rows + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-remove|remove on Meteor documentation} + */ Collection.prototype.remove = function (selector) { var observers = []; var obs = this._createObservable(observers); @@ -222,6 +343,17 @@ var ObservableCursor = (function (_super) { }); return obs; }; + /** + * Modify one or more documents in the collection. + * + * @param {Collection~MongoQuerySelector} selector - Specifies which documents to modify + * @param {Modifier} modifier - Specifies how to modify the documents + * @param {MongoUpdateOptions} options - Update options + * first argument and, if no error, the number of affected documents as the second + * @returns {Observable} Observable which completes with the number of affected rows + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-update|update on Meteor documentation} + */ Collection.prototype.update = function (selector, modifier, options) { var observers = []; var obs = this._createObservable(observers); @@ -234,6 +366,18 @@ var ObservableCursor = (function (_super) { }); return obs; }; + /** + * Finds the first document that matches the selector, as ordered by sort and skip options. + * + * @param {Collection~MongoQuerySelector} selector - Specifies which documents to modify + * @param {Modifier} modifier - Specifies how to modify the documents + * @param {MongoUpsertOptions} options - Upsert options + * first argument and, if no error, the number of affected documents as the second. + * @returns {Observable<{numberAffected, insertedId}>} Observable which completes with an + * Object that contain the keys numberAffected and insertedId. + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-upsert|upsert on Meteor documentation} + */ Collection.prototype.upsert = function (selector, modifier, options) { var observers = []; var obs = this._createObservable(observers); @@ -246,10 +390,38 @@ var ObservableCursor = (function (_super) { }); return obs; }; + /** + * Method has the same notation as Mongo.Collection.find, only returns Observable. + * + * @param {Collection~MongoQuerySelector} selector - A query describing the documents to find + * @param {Collection~MongoQueryOptions} options - Query options, such as sort, limit, etc. + * @returns {ObservableCursor} RxJS Observable wrapped with Meteor features. + * @example Using Angular2 Component + * const MyCollection = MongoObservable.Collection("myCollection"); + * + * class MyComponent { + * private myData: ObservableCursor; + * + * constructor() { + * this.myData = MyCollection.find({}, {limit: 10}); + * } + * } + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-find|find on Meteor documentation} + */ Collection.prototype.find = function (selector, options) { var cursor = this._collection.find.apply(this._collection, arguments); return ObservableCursor.create(cursor); }; + /** + * Finds the first document that matches the selector, as ordered by sort and skip options. + * + * @param {Collection~MongoQuerySelector} selector - A query describing the documents to find + * @param {Collection~MongoQueryOptions} options - Query options, such as sort, limit, etc. + * @returns {any} The first object, or `undefined` in case of non-existing object. + * + * @see {@link https://docs.meteor.com/api/collections.html#Mongo-Collection-findOne|findOne on Meteor documentation} + */ Collection.prototype.findOne = function (selector, options) { return this._collection.findOne.apply(this._collection, arguments); }; @@ -265,13 +437,70 @@ var ObservableCursor = (function (_super) { }()); MongoObservable.Collection = Collection; })(exports.MongoObservable || (exports.MongoObservable = {})); +/** + * An options object for MongoDB queries. + * @typedef {Object} Collection~MongoQueryOptions + * @property {Object} sort - Sort order (default: natural order) + * @property {Number} skip - Number of results to skip at the beginning + * @property {Object} fields - Dictionary of fields to return or exclude. + * @property {Boolean} reactive - (Client only) Default true; pass false to disable reactivity + * @property {Function} transform - Overrides transform on the Collection for this cursor. Pass null to disable transformation. + */ +/** + * A MongoDB query selector representation. + * @typedef {(Mongo.Selector|Mongo.ObjectID|string)} Collection~MongoQuerySelector + */ +/** + * A MongoDB query options for upsert action + * @typedef {Object} Collection~MongoUpsertOptions + * @property {Boolean} multi - True to modify all matching documents; + * false to only modify one of the matching documents (the default). + */ +/** + * A MongoDB query options for update action + * @typedef {Object} Collection~MongoUpdateOptions + * @property {Boolean} multi - True to modify all matching documents; + * @property {Boolean} upsert - True to use upsert logic. + */ function throwInvalidCallback(method) { throw new Error("Invalid " + method + " arguments:\n your last param can't be a callback function, \n please remove it and use \".subscribe\" of the Observable!"); } +/** + * A class with static methods, which wraps Meteor's API and returns + * RxJS Observable as return value for all Meteor's API. + * The method's signature is the same as Metoer's, except you don't + * need to provide callbacks, and you need to "subscribe" instead. + * The functionality that wrapped in this implementation is Meteor.call, + * Meteor.autorun and Meteor.subscribe. + * + */ var MeteorObservable = (function () { function MeteorObservable() { } + /** + * Method has the same notation as Meteor.call, only without the callbacks: + * MeteorObservable.call(name, [...args]) + * + * @param {String} name - Name of the method in the Meteor server + * @param {any} args - Parameters that will be forwarded to the method. + * after the func call to initiate change detection. + * @returns {Observable} - RxJS Observable, which completes when the server return a response. + * @example Example using Angular2 Component + * class MyComponent { + * constructor() { + * + * } + * + * doAction(payload) { + * MeteorObservable.call("myData", payload).subscribe((response) => { + * // Handle success and response from server! + * }, (err) => { + * // Handle error + * }); + * } + * } + */ MeteorObservable.call = function (name) { var args = []; for (var _i = 1; _i < arguments.length; _i++) { @@ -294,6 +523,57 @@ var MeteorObservable = (function () { ]))); }); }; + /** + * Method has the same notation as Meteor.subscribe, only without the callbacks: + * subscribe(name, [...args]) + * + * You can use this method from any Angular2 element - such as Component, Pipe or + * Service. + * + * @param {String} name - Name of the publication in the Meteor server + * @param {any} args - Parameters that will be forwarded to the publication. + * after the func call to initiate change detection. + * @returns {Observable} - RxJS Observable, which completes when the subscription is ready. + * @example Example using Angular2 Service + * class MyService { + * private meteorSubscription: Observable; + * + * constructor() { + * + * } + * + * subscribeToData() { + * this.meteorSubscription = MeteorObservable.subscribe("myData").subscribe(() => { + * // Subscription is ready! + * }); + * } + * + * unsubscribeToData() { + * this.meteorSubscription.unsubscribe(); + * } + * } + * + * @example Example using Angular2 Component + * class MyComponent implements OnInit, OnDestroy { + * private meteorSubscription: Observable; + * + * constructor() { + * + * } + * + * ngOnInit() { + * this.meteorSubscription = MeteorObservable.subscribe("myData").subscribe(() => { + * // Subscription is ready! + * }); + * } + * + * ngOnDestroy() { + * this.meteorSubscription.unsubscribe(); + * } + * } + * + * @see {@link http://docs.meteor.com/api/pubsub.html|Publications in Meteor documentation} + */ MeteorObservable.subscribe = function (name) { var args = []; for (var _i = 1; _i < arguments.length; _i++) { @@ -332,6 +612,25 @@ var MeteorObservable = (function () { }; }); }; + /** + * Method has the same notation as Meteor.autorun, only without the callback: + * MeteorObservable.autorun() + * + * @returns {Observable} - RxJS Observable, which trigger the subscription callback + * each time that Meteor Tracker detects a change. + * @example Example using Angular2 Component + * class MyComponent { + * constructor() { + * + * } + * + * doAction(payload) { + * MeteorObservable.autorun().subscribe(() => { + * // Handle Tracker autorun change + * }); + * } + * } + */ MeteorObservable.autorun = function () { var zone = forkZone(); var observers = []; diff --git a/docs/MeteorObserbable.md b/docs/MeteorObserbable.md new file mode 100644 index 00000000..7ff6a3f2 --- /dev/null +++ b/docs/MeteorObserbable.md @@ -0,0 +1,122 @@ + + +## MeteorComponent +A class to extend in Angular 2 components. +Contains wrappers over main Meteor methods, +that does some maintenance work behind the scene. +For example, it destroys subscription handles +when the component is being destroyed itself. + +**Kind**: global class + +* [MeteorComponent](#MeteorComponent) + * _instance_ + * [.autorun(func, autoBind)](#MeteorComponent+autorun) ⇒ Tracker.Computation + * [.subscribe(name, ...args, autoBind)](#MeteorComponent+subscribe) ⇒ Meteor.SubscriptionHandle + * [.call(name, ...args, autoBind)](#MeteorComponent+call) ⇒ void + * _inner_ + * [~autorunCallback](#MeteorComponent..autorunCallback) : function + + + +### meteorComponent.autorun(func, autoBind) ⇒ Tracker.Computation +Method has the same notation as Meteor.autorun +except the last parameter. + +**Kind**: instance method of [MeteorComponent](#MeteorComponent) +**Returns**: Tracker.Computation - - Object representing the Meteor computation +**See** + +- [Tracker.Computation in Meteor documentation](https://docs.meteor.com/api/tracker.html#tracker_computation) +- [autorun in Meteor documentation](https://docs.meteor.com/api/tracker.html#Tracker-autorun) + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| func | [autorunCallback](#MeteorComponent..autorunCallback) | | Callback to be executed when current computation is invalidated. The Tracker.Computation object will be passed as argument to this callback. | +| autoBind | Boolean | true | Determine whether Angular2 Zone will run after the func call to initiate change detection. | + +**Example** +```js +class MyComponent extends MeteorComponent { + private myData: Mongo.Cursor; + private dataId: any; + + constructor() { + super(); + + this.autorun(() => { + this.myData = MyCollection.find({ _id: dataId}); + }, true); + } +} +``` + + +### meteorComponent.subscribe(name, ...args, autoBind) ⇒ Meteor.SubscriptionHandle +Method has the same notation as Meteor.subscribe: + subscribe(name, [args1, args2], [callbacks], [autoBind]) + except the last autoBind param (see autorun above). + +**Kind**: instance method of [MeteorComponent](#MeteorComponent) +**Returns**: Meteor.SubscriptionHandle - - The handle of the subscription created by Meteor. +**See**: [Publication/Subscription in Meteor documentation](http://docs.meteor.com/api/pubsub.html) + +| Param | Type | Description | +| --- | --- | --- | +| name | String | Name of the publication in the Meteor server | +| ...args | any | Parameters that will be forwarded to the publication. | +| autoBind | Boolean | Determine whether Angular 2 zone will run after the func call to initiate change detection. | + +**Example** +```js +class MyComponent extends MeteorComponent { + constructor() { + super(); + + this.subscribe("myData", 10); + } + } + + +``` + + +### meteorComponent.call(name, ...args, autoBind) ⇒ void +Method has the same notation as Meteor.call: + call(name, [args1, args2], [callbacks], [autoBind]) + except the last autoBind param (see autorun above). + +**Kind**: instance method of [MeteorComponent](#MeteorComponent) + +| Param | Type | Description | +| --- | --- | --- | +| name | String | Name of the publication in the Meteor server | +| ...args | any | Parameters that will be forwarded to the method. | +| autoBind | Boolean | autoBind Determine whether Angular 2 zone will run after the func call to initiate change detection. | + +**Example** +```js +class MyComponent extends MeteorComponent { + constructor() { + super(); + + this.call("serverMethod", (err, result) => { + // Handle response... + }); + } + } + + +``` + + +### MeteorComponent~autorunCallback : function +This callback called when autorun triggered by Meteor. + +**Kind**: inner typedef of [MeteorComponent](#MeteorComponent) + +| Param | Type | +| --- | --- | +| computation | Tracker.Computation | + diff --git a/docs/ObservableCollection.md b/docs/ObservableCollection.md new file mode 100644 index 00000000..7ff6a3f2 --- /dev/null +++ b/docs/ObservableCollection.md @@ -0,0 +1,122 @@ + + +## MeteorComponent +A class to extend in Angular 2 components. +Contains wrappers over main Meteor methods, +that does some maintenance work behind the scene. +For example, it destroys subscription handles +when the component is being destroyed itself. + +**Kind**: global class + +* [MeteorComponent](#MeteorComponent) + * _instance_ + * [.autorun(func, autoBind)](#MeteorComponent+autorun) ⇒ Tracker.Computation + * [.subscribe(name, ...args, autoBind)](#MeteorComponent+subscribe) ⇒ Meteor.SubscriptionHandle + * [.call(name, ...args, autoBind)](#MeteorComponent+call) ⇒ void + * _inner_ + * [~autorunCallback](#MeteorComponent..autorunCallback) : function + + + +### meteorComponent.autorun(func, autoBind) ⇒ Tracker.Computation +Method has the same notation as Meteor.autorun +except the last parameter. + +**Kind**: instance method of [MeteorComponent](#MeteorComponent) +**Returns**: Tracker.Computation - - Object representing the Meteor computation +**See** + +- [Tracker.Computation in Meteor documentation](https://docs.meteor.com/api/tracker.html#tracker_computation) +- [autorun in Meteor documentation](https://docs.meteor.com/api/tracker.html#Tracker-autorun) + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| func | [autorunCallback](#MeteorComponent..autorunCallback) | | Callback to be executed when current computation is invalidated. The Tracker.Computation object will be passed as argument to this callback. | +| autoBind | Boolean | true | Determine whether Angular2 Zone will run after the func call to initiate change detection. | + +**Example** +```js +class MyComponent extends MeteorComponent { + private myData: Mongo.Cursor; + private dataId: any; + + constructor() { + super(); + + this.autorun(() => { + this.myData = MyCollection.find({ _id: dataId}); + }, true); + } +} +``` + + +### meteorComponent.subscribe(name, ...args, autoBind) ⇒ Meteor.SubscriptionHandle +Method has the same notation as Meteor.subscribe: + subscribe(name, [args1, args2], [callbacks], [autoBind]) + except the last autoBind param (see autorun above). + +**Kind**: instance method of [MeteorComponent](#MeteorComponent) +**Returns**: Meteor.SubscriptionHandle - - The handle of the subscription created by Meteor. +**See**: [Publication/Subscription in Meteor documentation](http://docs.meteor.com/api/pubsub.html) + +| Param | Type | Description | +| --- | --- | --- | +| name | String | Name of the publication in the Meteor server | +| ...args | any | Parameters that will be forwarded to the publication. | +| autoBind | Boolean | Determine whether Angular 2 zone will run after the func call to initiate change detection. | + +**Example** +```js +class MyComponent extends MeteorComponent { + constructor() { + super(); + + this.subscribe("myData", 10); + } + } + + +``` + + +### meteorComponent.call(name, ...args, autoBind) ⇒ void +Method has the same notation as Meteor.call: + call(name, [args1, args2], [callbacks], [autoBind]) + except the last autoBind param (see autorun above). + +**Kind**: instance method of [MeteorComponent](#MeteorComponent) + +| Param | Type | Description | +| --- | --- | --- | +| name | String | Name of the publication in the Meteor server | +| ...args | any | Parameters that will be forwarded to the method. | +| autoBind | Boolean | autoBind Determine whether Angular 2 zone will run after the func call to initiate change detection. | + +**Example** +```js +class MyComponent extends MeteorComponent { + constructor() { + super(); + + this.call("serverMethod", (err, result) => { + // Handle response... + }); + } + } + + +``` + + +### MeteorComponent~autorunCallback : function +This callback called when autorun triggered by Meteor. + +**Kind**: inner typedef of [MeteorComponent](#MeteorComponent) + +| Param | Type | +| --- | --- | +| computation | Tracker.Computation | + diff --git a/docs/ObservableCursor.md b/docs/ObservableCursor.md new file mode 100644 index 00000000..7ff6a3f2 --- /dev/null +++ b/docs/ObservableCursor.md @@ -0,0 +1,122 @@ + + +## MeteorComponent +A class to extend in Angular 2 components. +Contains wrappers over main Meteor methods, +that does some maintenance work behind the scene. +For example, it destroys subscription handles +when the component is being destroyed itself. + +**Kind**: global class + +* [MeteorComponent](#MeteorComponent) + * _instance_ + * [.autorun(func, autoBind)](#MeteorComponent+autorun) ⇒ Tracker.Computation + * [.subscribe(name, ...args, autoBind)](#MeteorComponent+subscribe) ⇒ Meteor.SubscriptionHandle + * [.call(name, ...args, autoBind)](#MeteorComponent+call) ⇒ void + * _inner_ + * [~autorunCallback](#MeteorComponent..autorunCallback) : function + + + +### meteorComponent.autorun(func, autoBind) ⇒ Tracker.Computation +Method has the same notation as Meteor.autorun +except the last parameter. + +**Kind**: instance method of [MeteorComponent](#MeteorComponent) +**Returns**: Tracker.Computation - - Object representing the Meteor computation +**See** + +- [Tracker.Computation in Meteor documentation](https://docs.meteor.com/api/tracker.html#tracker_computation) +- [autorun in Meteor documentation](https://docs.meteor.com/api/tracker.html#Tracker-autorun) + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| func | [autorunCallback](#MeteorComponent..autorunCallback) | | Callback to be executed when current computation is invalidated. The Tracker.Computation object will be passed as argument to this callback. | +| autoBind | Boolean | true | Determine whether Angular2 Zone will run after the func call to initiate change detection. | + +**Example** +```js +class MyComponent extends MeteorComponent { + private myData: Mongo.Cursor; + private dataId: any; + + constructor() { + super(); + + this.autorun(() => { + this.myData = MyCollection.find({ _id: dataId}); + }, true); + } +} +``` + + +### meteorComponent.subscribe(name, ...args, autoBind) ⇒ Meteor.SubscriptionHandle +Method has the same notation as Meteor.subscribe: + subscribe(name, [args1, args2], [callbacks], [autoBind]) + except the last autoBind param (see autorun above). + +**Kind**: instance method of [MeteorComponent](#MeteorComponent) +**Returns**: Meteor.SubscriptionHandle - - The handle of the subscription created by Meteor. +**See**: [Publication/Subscription in Meteor documentation](http://docs.meteor.com/api/pubsub.html) + +| Param | Type | Description | +| --- | --- | --- | +| name | String | Name of the publication in the Meteor server | +| ...args | any | Parameters that will be forwarded to the publication. | +| autoBind | Boolean | Determine whether Angular 2 zone will run after the func call to initiate change detection. | + +**Example** +```js +class MyComponent extends MeteorComponent { + constructor() { + super(); + + this.subscribe("myData", 10); + } + } + + +``` + + +### meteorComponent.call(name, ...args, autoBind) ⇒ void +Method has the same notation as Meteor.call: + call(name, [args1, args2], [callbacks], [autoBind]) + except the last autoBind param (see autorun above). + +**Kind**: instance method of [MeteorComponent](#MeteorComponent) + +| Param | Type | Description | +| --- | --- | --- | +| name | String | Name of the publication in the Meteor server | +| ...args | any | Parameters that will be forwarded to the method. | +| autoBind | Boolean | autoBind Determine whether Angular 2 zone will run after the func call to initiate change detection. | + +**Example** +```js +class MyComponent extends MeteorComponent { + constructor() { + super(); + + this.call("serverMethod", (err, result) => { + // Handle response... + }); + } + } + + +``` + + +### MeteorComponent~autorunCallback : function +This callback called when autorun triggered by Meteor. + +**Kind**: inner typedef of [MeteorComponent](#MeteorComponent) + +| Param | Type | +| --- | --- | +| computation | Tracker.Computation | + diff --git a/generate-docs.sh b/generate-docs.sh new file mode 100755 index 00000000..0225a068 --- /dev/null +++ b/generate-docs.sh @@ -0,0 +1,3 @@ +$(npm bin)/jsdoc2md -l js --source "$(cat ./src/MeteorObservable.ts)" > ./docs/MeteorObserbable.md +$(npm bin)/jsdoc2md -l js --source "$(cat ./src/ObservableCollection.ts)" > ./docs/ObservableCollection.md +$(npm bin)/jsdoc2md -l js --source "$(cat ./src/ObservableCursor.ts)" > ./docs/ObservableCursor.md \ No newline at end of file diff --git a/package.json b/package.json index a2a819a8..99223293 100644 --- a/package.json +++ b/package.json @@ -14,9 +14,10 @@ "browser": "dist/bundles/index.umd.js", "typings": "dist/index.d.ts", "scripts": { + "docs": "./generate-docs.sh", "typings": "typings i", "prebuild": "npm run typings && npm run lint", - "build": "npm run build-only && npm run bundle", + "build": "npm run build-only && npm run bundle && npm run docs", "prepublish": "npm run build", "build-only": "tsc || echo not ok", "pretest": "cd tests && npm install", @@ -44,6 +45,7 @@ "conventional-changelog-cli": "^1.2.0", "es6-shim": "^0.35.0", "ghooks": "^1.2.1", + "jsdoc-to-markdown": "^2.0.1", "rollup": "^0.36.1", "rxjs": "^5.0.0-beta.12", "tslint": "^3.6.0", diff --git a/tslint.json b/tslint.json index 9a439c15..3da82f97 100644 --- a/tslint.json +++ b/tslint.json @@ -8,7 +8,7 @@ "indent": [true, "spaces"], "label-position": true, "label-undefined": true, - "max-line-length": [true, 100], + "max-line-length": [true, 150], "member-access": false, "member-ordering": [true, "public-before-private",