mirror of
https://github.com/zhigang1992/deployd.git
synced 2026-05-20 16:14:58 +08:00
90 lines
3.7 KiB
Markdown
90 lines
3.7 KiB
Markdown
# Script
|
|
|
|
A `Script` provides a mechanism to run JavaScript source in a sandbox. A `Script` is executed with a `Context` and a `domain` object using [the node vm module](http://nodejs.org/api/vm.html). Each `Script` runs independently. They do not share any scope (including global scope), nor do they share state with other scripts.
|
|
|
|
## Async Mode
|
|
|
|
Scripts can be run in an **async mode**. This mode is triggered when a `Script` is `run(ctx, domain, fn)` with a callback (`fn`). When run in this mode a `Script` will try scrub all functions in the domain for operations that require a callback. If a callback is required, the function is re-written to count the callbacks completion and notify the script. When all pending callbacks are complete the script is considered finished.
|
|
|
|
## Async Errors
|
|
|
|
If a script is run with a callback (in **async mode**), any error will emit an internal `error` event. This will stop the execution of the script and pass the error to the script's callback.
|
|
|
|
## Class: Script
|
|
|
|
var Script = require('deployd/lib/script');
|
|
var script = new Script('hello()', 'hello.js');
|
|
|
|
A `Script`'s source is compiled when its constructor is called. It can be `run()` many times with independent `Context`s and `domain`s.
|
|
|
|
## script.run(ctx, domain, [fn])
|
|
|
|
* ctx {Context}
|
|
|
|
A `Context` with a `session`, `query`, `req` and `res`.
|
|
|
|
* domain {Object}
|
|
|
|
An `Object` containing functions to be injected into the `Script`s sandbox. This will override any existing functions or objects in the `Script`s sandbox / global scope.
|
|
|
|
This example `domain` provides a log function to a script.
|
|
|
|
var script = new Script('log("hello world")');
|
|
var context = {};
|
|
var domain = {};
|
|
var msg;
|
|
|
|
domain.log = function(str) {
|
|
console.log(msg = str);
|
|
}
|
|
|
|
script.run(ctx, domain, function(err) {
|
|
console.log(msg); // 'hello world'
|
|
});
|
|
|
|
* fn(err) *optional*
|
|
|
|
If a callback is provided the script will be run in **async mode**. The callback will receive any error even if the error occurs asynchronously. Otherwise it will be called without any arguments when the script is finished executing (see: async mode).
|
|
|
|
var s = new Script('setTimeout(function() { throw "test err" }, 22)');
|
|
|
|
// give the script access to setTimeout
|
|
var domain = {setTimeout: setTimeout};
|
|
|
|
s.run({}, domain, function (e) {
|
|
console.log(e); // test err
|
|
});
|
|
|
|
## Script.load(path, fn)
|
|
|
|
* path {String}
|
|
|
|
* fn(err, script)
|
|
|
|
Load a new `script` at the given file `path`. Callback with an error if one occured or a new `Script` loaded from the contents of the file.
|
|
|
|
## Default Domain
|
|
|
|
Scripts are executed with a default sandbox and set of domain functions. These are functions that every `Script` needs. The following are available to every `Script`. These can be overridden by passing a value such as `{cancel: ...}` in a `domain`.
|
|
|
|
### cancel(msg, status)
|
|
|
|
Throws an error that immediately stops the execution of a context and calls the callback passed to `script.run()` passing the error as the first argument.
|
|
|
|
`cancel()` does not have an effect if the current `Context.isRoot` or `Context.internal` is true.
|
|
|
|
### emit([collection], [query], event, data)
|
|
|
|
Stability: will change in 0.7
|
|
|
|
Emits an `event` to all sessions. Can be passed an optional `UserCollection` and `query` to emit the event to only the users in the collection that match the query.
|
|
|
|
### Sandbox
|
|
|
|
The default sandbox or global object in a `Script` comes with several other properties:
|
|
|
|
- `me` - the current user if one exists on the `Context`
|
|
- `this` - an empty object if not overridden by the `domain`
|
|
- `query` - the current `Context`'s query
|
|
- `console` - support for `console.log()` and other `console` methods
|