		# Changelog

		## v1.0.0
		### Added
		- Promise support. If you return a promise from a job, it's treated as an async job.
		- You can now send values back to the server. Any value returned (or resolved) is sent back in the job report.
		- The context is now passed as the first (and only) parameter.
		- New `.async` method to replace the `done` parameter.

		### Changed
		- Jobs emit a report when finished, instead of an error or nothing. This gives the report details space to grow in the future.
		- `this.data` renamed to `this.props` for clarity.
		- `panic.connection` is now `panic.socket`.

		### Removed
		- Job#timeout has been removed. Use `setTimeout(this.fail)` instead.
		- The `done` callback is no longer passed. Instead, use `var done = this.async()`, or return a promise.
		- The socket is no longer accessible as `this.socket`. Use `panic.connection` instead.
		- The `@scope` is no longer supported. It just caused too much confusion.

		## v0.3.0
		@@ -4,0 +22,0 @@ ### Added

package.json

		{
		"name": "panic-client",
		"version": "0.3.0",
		"version": "1.0.0",
		"description": "Test client for panic-server",
		"main": "src/index.js",
		"dependencies": {
		"phantomjs-polyfill": "0.0.2",
		"bluebird": "^3.4.6",
		"is-promise": "^2.1.0",
		"platform": "^1.3.1",
		@@ -12,3 +13,3 @@ "socket.io-client": "^1.4.5"
		"devDependencies": {
		"chai": "^3.5.0",
		"expect": "^1.20.2",
		"mocha": "^3.1.0",
		@@ -15,0 +16,0 @@ "webpack": "^1.12.14"

215

README.md

		Panic Client
		------------
		Lightweight client for panic-server
		Caters to the whims of panic-server.

		@@ -10,61 +10,200 @@ [![npm](https://img.shields.io/npm/dt/panic-client.svg?style=flat-square)](https://www.npmjs.com/package/panic-client)

		## Docs
		Since this library is just support for [panic-server](https://github.com/gundb/panic-server), you can find the majority of the documentation [over there](https://github.com/gundb/panic-server/blob/master/README.md).
		> These docs only cover the client API. An introduction to panic and the server API can be found [here](https://github.com/gundb/panic-server).

		## Installing
		Panic-client is hosted on [npm](https://www.npmjs.com/package/panic-client), and can be installed by running this in your terminal:
		## Server API
		Naturally, you wouldn't expect the server API to be in a repo named "panic-client".

		```bash
		npm install panic-client
		You'd be right.

		All the main API docs and cool, compelling reasons for using panic are in the [panic-server repo](https://github.com/gundb/panic-server).

		## Loading panic-client
		There are two ways! Because panic-client can be used (most) places JavaScript runs, there are a couple different ways you can load it.

		### From a browser
		When you start a panic server, it automatically handles routes hitting /panic.js. So from a browser, the simplest way is by including a script tag.

		```html
		<script src='http://localhost:8080/panic.js'></script>
		```

		> If you're not familiar with npm, you can learn more by [clicking here](https://docs.npmjs.com/getting-started/what-is-npm), or you can install it by following [these instructions](http://blog.npmjs.org/post/85484771375/how-to-install-npm).
		Now you'll find a global variable, `panic`, in your browser.

		## Usage
		Panic-client's API surface area is pretty small, since it's just a small wrapper around [socket.io](http://socket.io/). It consists of one method, `server`, and two properties, `connection` and `platform`.
		Afterwards, you'll call `panic.server()`, but we'll get to that in a second...

		There are two ways to include it in your code, depending on your environment...
		> If you're using Selenium, the easiest way to inject panic is with `executeScript`, or a library that wraps it.

		Node.js
		```javascript
		// simply import it.
		### From Node.js
		Ah, this one's easier.

		Panic-client is also on npm, so you can install it quickly like so:

		```sh
		$ npm install panic-client
		```

		> If you don't have npm, you can learn about it [here](https://docs.npmjs.com/getting-started/what-is-npm). It'll change your life.

		Now simply `require` it from a JS file.

		```js
		var panic = require('panic-client')
		```

		Browser
		### Connecting to panic-server
		Now that you've loaded panic, give it the URL to your panic server. Naturally, you'll need to start it first.

		> If you're using [panic-server](https://github.com/gundb/panic-server), the server automatically delivers the browser file at the at the port/hostname you configured. By default, it will be 'http://localhost:8080/panic.js'.
		```js
		// Or whatever port/ip it's running on.
		panic.server('http://localhost:8080')
		```

		If you're not using [panic-server](https://github.com/gundb/panic-server), it may be more complicated, depending on your file structure. If you're using [webpack](https://github.com/webpack/webpack), simply include it the same way as you would on Node.js. Otherwise, the browser build is located at root level, named `panic.js`. Simply point a script tag there, or copy it into your project root...
		Bam, you're connected.

		```html
		<script src="node_modules/{path to panic-client}/panic.js"></script>
		<script>
		panic; // now exposed as a global variable
		</script>
		## API
		Okay, first let's clarify what this documentation describes.

		When you call `panic.clients.run` from the panic-server code, that function is stringified and sent to the clients, running this code.

		So any methods or properties you access within that function, that's the client API.

		Cool. Now for the fun stuff.

		### Parameters
		You're just given one, and it's the same as the `this` context. Extra fancy if you're using an arrow function.

		```js
		clients.run(function (context) {
		this === context // yep
		})
		```

		Best practice is to load through panic-server.
		### Return values
		Any value you return from a job will be reported back to panic-server, with the exception of a `Promise`.

		```html
		<script src="http://localhost:8080/panic.js"></script>
		```js
		// Returning a primitive.
		client.run(function () {
		return 5
		}).then(function (result) {
		console.log(result) // 5
		})
		```

		### `.server(String)`
		This method attempts to connect to your panic-server host, and allows panic-server to run code on your machine in real-time. Just give it the url.
		Since you returned a promise, it automatically switches into async mode and won't report back until the promise resolves or rejects.

		```javascript
		// This is the default url.
		// When connecting from another computer,
		// exchange `localhost` with your ip address.
		panic.server('http://localhost:8080')
		```js
		// Returning a promise.
		client.run(function () {
		return fetch('/users.json')
		.then(function (res) {
		return res.json()
		})
		}).then(function (users) {
		users // whatever those users were...
		})
		```

		### `.connection`
		`panic.connection` is the websocket opened to panic-server. If you haven't called `panic.server()` yet, it'll be `null`.
		Though beware, if your promise rejects, the job will fail and reject on the server.

		### `.platform`
		The `panic.platform` object is created by [platform.js](https://github.com/bestiejs/platform.js/), and contains information about what environment the code is running on.
		```js
		client.run(function () {
		var error = new Error('KO!')
		return Promise.reject(error)
		}).catch(function (error) {
		error.message // KO!
		})
		```

		## Support
		If you have questions or ideas, please let us know on [our gitter channel](https://gitter.im/amark/gun) :grinning:
		Last thing, promise.

		If your return value can't be JSON.strungified, it'll just send back the type, like `[object Event]` as a best effort for debugging.

		### Methods
		#### `.async()`
		Maybe you're a menace and you hate promises. That's fine, `.async` returns a `done` callback.

		It won't report back to the server until you call it, throw an error, or explicitly fail the test.

		Also, you can use `this.done` instead, they both reference the same function. Matter of convenience.

		```js
		clients.run(function () {
		var done = this.async()
		setTimeout(done, 15000)
		}).then(function () {
		// 15 seconds later!
		})
		```

		#### `.done()`
		Reports the job back to the server immediately, sending it whatever value you pass. Unless of course `done` has already been called, 'cuz you've only got one shot kid.

		Basically, the job can only finish or fail once. Any additional calls are just ignored.

		#### `.fail()`
		Manually fails a job. If you pass something that isn't an error object, it'll be used as the message in an error that panic generates, then it's sent off to the server and jobs reject it's just messy.

		As with `.done`, calling `.done` or `.fail` after doesn't make any difference.

		#### `.set()`
		If you're running oodles of jobs, it's a matter of time until one job needs a variable another job created.

		Rather than doing `global` hackery, you can use `.set`, which saves a key-value pair into an object, where it's accessible to other jobs (in the same process).

		```js
		client.run(function () {
		var port = this.props.port
		this.set('port', port)
		}, { port: 8085 })
		```

		#### `.get()`
		Retrieve values created in `.set`.

		```js
		// From the port example.
		client.run(function () {
		var port = this.get('port')
		console.log(port) // 8085
		})
		```

		### Properties
		Here are some fancy things you have access to inside running jobs.

		#### `.props`
		You might have noticed you've only got one parameter. This raises an excellent question: will global warming really kill us all?

		Additionally, how do you get variables into the job? Well, if you've dug around in the server API, you know `.run` takes two parameters, the function to run, and any variables it depends on.

		Those variables are all accessible via `.props`.

		```js
		client.run(function () {
		var color = this.props.background
		color // orange
		}, {
		background: 'orange'
		})
		```

		#### `.platform`
		This property references the [platform.js](https://github.com/bestiejs/platform.js/) object. It's used internally with panic, and useful, so why not expose it? :tada:

		#### `.isAsync`
		A boolean, which refers to whether `.async()` has been called, and consequently, whether your job is asynchronous.

		## Getting support
		If you've got questions or need help, either swing by [our gitter channel](https://gitter.im/amark/gun/) and ask for @PsychoLlama, or post an issue.

		## Supporting us
		- Tell your friends how cool we are
		- Help us get to 5 million GitHub stars by adding yours
		- Report any bugs you find

		Any of those would be terrific.



		<!---->

src/index.js

		@@ -1,10 +0,36 @@
		/jslint node: true/
		'use strict';

		var panic = require('./panic');
		var io = require('socket.io-client');
		var platform = require('platform');
		var execute = require('./execute');
		var panic = exports;

		panic.platform = platform;
		panic.socket = null;

		/**
		* Handshakes with a panic server.
		* @param {String} url - The root-relative URL to a panic server.
		* @return {Socket} - A new socket.io instance.
		*/
		panic.server = function (url) {
		var socket = panic.socket = io.connect(url);

		/** Do whatever the server says. */
		socket.on('run', function (source, id, props) {
		execute(socket, {
		source: source,
		props: props,
		id: id
		});
		});

		/** Perform an initial handshake. */
		socket.emit('handshake', platform);

		return socket;
		};

		if (typeof window !== 'undefined') {
		window.panic = panic;
		}

		module.exports = panic;

src/parser.js

		@@ -1,2 +0,2 @@
		/eslint-disable/
		/* eslint-disable strict, no-eval*/

		@@ -11,16 +11,22 @@ /*

		The purpose of the parser is to take a stringified
		function, a scope, and return a function that has
		locally scoped variables according to the properties
		in the object (second param).
		This module takes a function string and magically
		(dangerously) turns it into a function using `eval`.
		The variables are named all shouty because eval can see
		local scope variables.
		*/

		// polyfill `arguments` for IE6
		module.exports = function () {
		var arguments = module.exports.arguments \|\| arguments;
		/**
		* Take a function string and evaluate it,
		* optionally injecting local variables.
		* @param {String} PANIC_SRC_STR - A function string to parse.
		* @return {Function} - The resulting function reference.
		*/
		module.exports = function (PANIC_SRC_STR) {

		/** IE6 doesn't like anon function expressions. */
		var PANIC_CB_FUNCTION;
		with (arguments[1] \|\| {}) {
		eval('PANIC_CB_FUNCTION = ' + arguments[0]);
		return PANIC_CB_FUNCTION;
		}

		eval('PANIC_CB_FUNCTION = ' + PANIC_SRC_STR);

		return PANIC_CB_FUNCTION;
		};

src/Job.js

src/panic.js

panic.js

Sorry, the diff of this file is too big to display

panic-client - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics

Worsened metrics

Dependency changes