chrome-remote-interface - npm Package Compare versions

Comparing version 0.5.0 to 0.6.0

lib/chrome.js

@@ -56,6 +56,8 @@ var protocol = require('./protocol.json');
     self.ws.send(JSON.stringify(message));
-    // register command response callback
-    if (typeof callback === 'function') {
-        self.callbacks[id] = callback;
+    // register a command response callback or use a dummy callback to ensure
+    // that the 'ready' event is correctly fired
+    if (typeof callback === 'undefined') {
+        callback = function () {};
     }
+    self.callbacks[id] = callback;
 };
@@ -182,2 +184,6 @@
                 delete self.callbacks[message.id];
+                // notify when there are no more pending commands
+                if (Object.keys(self.callbacks).length === 0) {
+                    self.emit('ready');
+                }
             }
@@ -184,0 +190,0 @@ }

package.json

@@ -10,3 +10,3 @@ {
     "homepage": "https://github.com/cyrus-and/chrome-remote-interface",
-    "version": "0.5.0",
+    "version": "0.6.0",
     "repository": {
@@ -13,0 +13,0 @@ "type": "git",

README.md

 chrome-remote-interface
 =======================
 
-[Remote Debugging Protocol][1] interface that helps to instrument Chrome by
+[Remote Debugging Protocol][rdb] interface that helps to instrument Chrome by
 providing a simple abstraction of the two main objects exposed by the protocol
 in a Node.js fashion: commands and notifications.
 
+`chrome-remote-interface` is listed among
+[third-party Chrome debugging protocol clients][clients-cri].
+
 Installation
@@ -17,3 +20,3 @@ ------------
 Chrome needs to be started with the `--remote-debugging-port=<port>` option to
-enable the [Remote Debugging Protocol][1], for example:
+enable the [Remote Debugging Protocol][rdb], for example:
 
@@ -31,9 +34,11 @@ google-chrome --remote-debugging-port=9222
     with (chrome) {
-        on('Network.requestWillBeSent', function (message) {
-            console.log(message.request.url);
+        Network.requestWillBeSent(function (params) {
+            console.log(params.request.url);
         });
-        on('Page.loadEventFired', close);
+        Page.loadEventFired(close);
         Network.enable();
         Page.enable();
-        Page.navigate({'url': 'https://github.com'});
+        once('ready', function () {
+            Page.navigate({'url': 'https://github.com'});
+        });
     }
@@ -51,4 +56,4 @@ }).on('error', function () {
 supports command execution and event binding, see the documentation for
-`chrome.Domain.method([params], [callback])` and
-`chrome.Domain.event(callback)`. Here's a sample session:
+`chrome.<domain>.<method>([params], [callback])` and
+`chrome.<domain>.<event>(callback)`. Here's a sample session:
 
@@ -62,3 +67,3 @@ ```javascript
 Using the provided `help` field it's possible to obtain information on the
-events and methods available through the [Remote Debugging Protocol][1]. For
+events and methods available through the [Remote Debugging Protocol][rdb]. For
 example to learn how to call `Page.navigate` type:
@@ -76,3 +81,3 @@
 
-The field `type` determines whether this member is a command or an event.
+The `type` field determines whether this member is a `command` or an `event`.
 
@@ -95,11 +100,11 @@ For what concerns the types instead (they usually start with an upper case
 Connects to a remote instance of Chrome using the [Remote Debugging
-Protocol][1].
+Protocol][rdb].
 
 `options` is an object with the following optional properties:
 
-- `host`: [Remote Debugging Protocol][1] host. Defaults to `localhost`;
-- `port`: [Remote Debugging Protocol][1] port. Defaults to `9222`;
+- `host`: [Remote Debugging Protocol][rdb] host. Defaults to `localhost`;
+- `port`: [Remote Debugging Protocol][rdb] port. Defaults to `9222`;
 - `chooseTab`: callback used to determine which remote tab attach to. Takes the
   array returned by `http://host:port/json` containing the tab list and must
-  return the numeric index of a tab. Defaults to a function that returns the
+  return the numeric index of a tab. Defaults to a function which returns the
   active one (`function (tabs) { return 0; }`).
@@ -114,3 +119,5 @@
 
-    function (chrome) {}
+```javascript
+function (chrome) {}
+```
 
@@ -123,3 +130,5 @@ Emitted when the connection to Chrome is established.
 
-    function (err) {}
+```javascript
+function (err) {}
+```
 
@@ -137,4 +146,4 @@ Emitted if `http://host:port/json` can't be reached or if it's not possible to
 
-- `host`: [Remote Debugging Protocol][1] host. Defaults to `localhost`;
-- `port`: [Remote Debugging Protocol][1] port. Defaults to `9222`.
+- `host`: [Remote Debugging Protocol][rdb] host. Defaults to `localhost`;
+- `port`: [Remote Debugging Protocol][rdb] port. Defaults to `9222`.
 
@@ -162,3 +171,5 @@ `callback` is executed when the list is correctly received, it gets the
 
-    function (message) {}
+```javascript
+function (message) {}
+```
 
@@ -169,21 +180,61 @@ Emitted when Chrome sends a notification through the WebSocket.
 
-- `method`: a string describing the message.
+- `method`: a string describing the notification (e.g.,
+  `'Network.requestWillBeSent'`).
 - `params`: an object containing the payload.
 
-Refer to the [Remote Debugging Protocol specifications][1] for more information.
+Refer to the [Remote Debugging Protocol specifications][rdb] for more information.
 
-#### Event: method
+For example:
 
-    function (params) {}
+```javascript
+on('event', function (message) {
+    if (message.method === 'Network.requestWillBeSent') {
+        console.log(message.params);
+    }
+});
+```
 
-Emitted when Chrome sends a notification classified as `method` through the
-WebSocket.
+#### Event: '`<method>`'
 
+```javascript
+function (params) {}
+```
+
+Emitted when Chrome sends a notification for `<method>` through the WebSocket.
+
 `params` is an object containing the payload.
 
-This is just a utility event that allows to easily filter out specific
-notifications (see the documentation of `event`), for example:
+This is just a utility event which allows to easily listen for specific
+notifications (see the above event), for example:
 
-    chrome.on('Network.requestWillBeSent', console.log);
+```javascript
+chrome.on('Network.requestWillBeSent', console.log);
+```
 
+#### Event: 'ready'
+
+```javascript
+function () {}
+```
+
+Emitted every time that there are no more pending commands waiting for a
+response from Chrome. Note that the interaction with Chrome is asynchronous so
+the only way to serialize a sequence of commands is to use the callback provided
+by the `chrome.send` method. This event acts as a barrier and it is useful to
+avoid the callback hell in certain simple situations.
+
+For example to load a URL only after having enabled the notifications of both
+`Network` and `Page` domains:
+
+```javascript
+Network.enable();
+Page.enable();
+once('ready', function() {
+    Page.navigate({'url': 'https://github.com'});
+});
+```
+
+In this particular case, not enforcing this kind of serialization may cause that
+Chrome doesn't properly deliver the desired notifications the client.
+
 #### chrome.send(method, [params], [callback])
@@ -193,3 +244,3 @@
 
-`method` is a string describing the message.
+`method` is a string describing the command.
 
@@ -207,23 +258,37 @@ `params` is an object containing the payload.
 Note that the field `id` mentioned in the [Remote Debugging Protocol
-specifications][1] is managed internally and it's not exposed to the user.
+specifications][rdb] is managed internally and it's not exposed to the user.
 
-#### chrome.Domain.method([params], [callback])
+For example:
 
+```javascript
+chrome.send('Page.navigate', {'url': 'https://github.com'}, console.log);
+```
+
+#### chrome.`<domain>`.`<method>`([params], [callback])
+
 Just a shorthand for:
 
-    chrome.send('Domain.method', params, callback);
+```javascript
+chrome.send('<domain>.<method>', params, callback);
+```
 
 For example:
 
-    chrome.Page.navigate({'url': 'https://github.com'});
+```javascript
+chrome.Page.navigate({'url': 'https://github.com'}, console.log);
+```
 
-#### chrome.Domain.event(callback)
+#### chrome.`<domain>`.`<event>`(callback)
 
 Just a shorthand for:
 
-    chrome.on('Domain.event', callback);
+```javascript
+chrome.on('<domain>.<event>', callback);
+```
 
 For example:
 
-    chrome.Network.requestWillBeSent(console.log);
+```javascript
+chrome.Network.requestWillBeSent(console.log);
+```
 
@@ -242,4 +307,7 @@ #### chrome.close()
 
-- [Chrome Developer Tools: Remote Debugging Protocol v1.1][1]
+- [Chrome Developer Tools: Remote Debugging Protocol v1.1][rdb]
+- [Showcase Chrome Debugging Protocol Clients][clients]
 
-[1]: https://developer.chrome.com/devtools/docs/protocol/1.1/index
+[rdb]: https://developer.chrome.com/devtools/docs/protocol/1.1/index
+[clients-cri]: https://developer.chrome.com/devtools/docs/debugging-clients#chrome-remote-interface
+[clients]: https://developer.chrome.com/devtools/docs/debugging-clients

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

311946

increased by14.09%

Lines of code

5313

increased by12.61%

Number of lines in readme file

300

increased by29.31%

No dependency changes