Repository navigation
Documentation
simpleS is under active development, the API may change from version to version, it is highly recommended to read the documentation of the current version as there may me be some radical changes
var simples = require('simples');simples(port)
port: number
simpleS needs only the port number and it sets up a HTTP server on this port.
var server = new simples(80);or
var server = simples(80); // simpler.start(port[, callback])
port: number
callback: function(0)
Start listening for requests on the provided port. If the server is already started, then simpleS will restart the server and will listen on the new provided port. Can have an optional callback.
server.start(80, function () {
// Application logic
});.stop([callback])
callback: function(0)
Stop the server. Can have an optional callback.
server.stop(function () {
// Application logic
});.host(name)
name: string
simpleS can serve multiple domains on the same server and port, using .host() method it's simple to specify which host should use which routes. By default simpleS has the main host which will route all existent routes of the simpleS instance, this is vital for one host on server or when it is needed a general behavior for incoming requests. Routing methods explained below are applicable on simpleS instance, for the main host, and on this method to define different hosts. Example:
server.host('example.com');.accept([arguments])
arguments: list of strings
simpleS provide a very simple way to accept cross-origin requests. It will automatically check the origin of the request and if it is in the list then it will response positively. By default the server will accept requests only from the host and local file system origins. To accept requests from any origin use '*', if this parameter is used as the first parameter then all next origins are rejected. 'null' is used for local file system origin. This method is applicable on the current or the main host (see Virtual Hosting). These limitations will work for HTTP GET and POST request and even for WebSocket requests. Example:
server.accept('null', 'localhost', 'example.com');.engine(engine)
engine: object
simpleS provide a simple way to use template engine for response rendering, for this it is necessary to define the needed template engine, if it has the method .render() then it will be used, else the engine itself will be used to render the response. Example:
var noopEngine = {
render: function (string) {
console.log(string);
return string;
}
};
server.engine(noopEngine);All the methods described below are applicable on the current or the main host (see Virtual Hosting).
.get(route, callback)
route: string
callback: function(2)
Listen for get requests and uses the callback function with request and response as parameters. Warning: route is case sensitive.
server.get('/', function (request, response) {
// Application logic
});.post(route, callback)
route: string
callback: function(2)
Listen for post requests and uses the callback function with request and response as parameters. Warning: route is case sensitive.
server.post('/', function (request, response) {
// Application logic
});.all(route, callback)
route: string
callback: function(2)
Listen for both GET and POST requests and uses the callback function with request and response as parameters,this is useful for defining general behavior for both types of requests. Warning: route is case sensitive.
server.all('/', function (request, response) {
// Application logic
});.serve(path)
path: string
path is the local path to a folder that contains static files (for example: css and js files), this folder will serve as the root folder for the server. simpleS will return response status 304 (Not Modified) if the files have not been changed since last visit of the client. Only one folder should be used to server static files, if more .serve() methods will be called only the last will be used to serve static files. The folder with static files can contain other folders, their content will be also served. The provided path must be relative to the current working directory. Warning: the names of static files are case sensitive.
server.serve('root');.error(code, callback)
code: number
callback: function(2)
Use the callback function with request and response as parameters for errors that can have place. Only one callback function can be used for a specific error code, if more .error() methods will be called for the same error code only the last will be used for routing. Possible values for error codes are: 404 (Not Found), 405 (Method Not Allowed) and 500 (Internal Server Error).
server.error(404, function (request, response) {
// Application logic
});The first parameter provided in callbacks for routing requests is an object that contains data about the current request. Example:
{
body: '',
cookies: {
user: 'me',
pass: 'password'
},
files: {},
headers: {
host: 'localhost',
'user-agent': 'myBrowser',
accept: 'text/html',
'accept-language': 'ro;q=0.8,en;q=0.6',
'accept-encoding': 'gzip, deflate',
cookie: 'user=me; pass=password'
},
langs: [
'ro',
'en'
],
method: 'GET',
query: {},
session: {},
url: {
search: '',
query: {},
pathname: '/',
path: '/',
href: '/'
}
}The content of the body of the request, for GET requests it is empty, for POST request it will contain plain data, parsed data is contained in request.query.
An object that contains the cookies provided by the client.
An object that contains files send using POST method with multipart/form-data content type.
An object that contains the HTTP headers of the request.
An array of strings that represents languages accepted by the client in the order of their relevance.
The HTTP method of the request.
The object that contains queries from both GET and POST methods.
A container used to keep important data on the server-side, the clients have access to this data using the _session cookie.
The url of the request split in components like href, path, pathname, query as object and query as string (search).
The second parameter provided in callbacks for routing requests is a writable stream that defines the data sent to the client. It has the next methods:
name: string
value: string
attributes: object
Sets the cookies sent to the client, providing a name, a value and an object to configure the expiration time, to limit the domain and the path and to specify if the cookie is http only. Can be used multiple times, but before .write() method. Example:
response.cookie('user', 'me', {
expires: new Date(new Date().valueOf() + 3600000), // or maxAge: 3600000, Set the expiration time of the cookie
path: '/path/', // Path of the cookie, should be defined only if it is diferent from the root, the first slash may be omitted, simpleS will add it
domain: 'localhost', // Domain of the cookie, should be defined only if it is different from the current host
httpOnly: false, // Set if the cookie can not be changed from client-side
});language: string
Sets the language of the response. Should be used before the .write() method. Should be used only once. Example:
response.lang('ro');path: string
Redirects the client to the provided path. Should not be used with the other methods except .cookie(). Example:
response.redirect('/index');type: string
override: boolean
Sets the type of the content of the response. Default is 'html'. By default uses one of 100 content types defined in mime.json, which can be edited to add mode content types. Should be used only once and before the .write() method. If the content type header is not set correctly or the exact value of the type is known it is possible to override using the second parameter with true value and setting the first parameter as a valid content type. The second parameter is optional. Example:
response.type('html');data: buffer or string
Writes data to the response stream. Should be ended with .end() method. Example:
response.write('Hello');data: buffer, string or empty
If data is provided it calls the .write() method and ends the response. Example:
response.end('World');data: any value except undefined
Writes preformatted data to the response stream and ends the response, usually very useful for sending file content or JSON format. Arrays, booleans, numbers and objects are stringified. Should not be used with .write() or .end() methods, but .write() method can be used before. Should be used only once. Example:
response.send(['Hello', 'World']);arguments: arguments for the template engine
Renders the response using the template engine, arguments will be those necessary for the template engine. Should not be used with .write() or .end() methods, but .write() method can be used before. Should be used only once. Example:
response.render('HelloWorld');The WebSocket host is linked to the current or the main HTTP host (see Virtual Hosting).
.ws(path, config, callback)
path: string
config: object
callback: function(1)
Create WebSocket host and listen for WebSocket connections. For security reasons only requests from the current host or local file system origins are accepted, to accept requests from another locations the .accept() method from the simpleS instance should be used. Also, for additional security or logic separation, protocols should be provided in the config parameter, by default no protocols are required, the length of the message can be limited too, default is 1MiB, the value is defined in bytes. The callback function comes with the connection as parameter.
server.ws('/', {
length: 1024,
protocols: ['', 'echo']
}, function (connection) {
// Application logic
});The object that represents the current WebSocket connection. The WebSocket connection is an event emitter and has some attributes from request interface to handle needed data from the handshake request. It has the next attributes and methods:
See Request Interface .cookies
See Request Interface .headers
See Request Interface .langs
The array of protocols of the WebSocket connection.
See Request Interface .query
See Request Interface .session
See Request Interface .url
data: any value except undefined
Sends a message to the client. If data is a buffer then the sent message will be of binary type, else - text type, arrays, booleans, numbers and objects are stringified.
data: string or buffer
filter: function(3)
Sends a message to all connected clients. Clients can be filtered by providing the second parameter, equivalent to Array.filter(). Example:
connection.broadcast('HelloWorld', function (element, index, array) {
return element.protocols.indexOf('chat') >= 0; // Will send the message to clients that use "chat" as a subprotocol
});The WebSocket connection has the next events:
Emitted when the server receives a message from the client.
Emitted when the connection is closed.
To have access to the simpleS client-side API it is necessary to add <script src="/simples/client.js"></script> in the HTML code, this JavaScript file will provide a simple API for AJAX requests and WebSocket connections, which are described below.
simples.ajax(url, method, params)
url: string
method: string
params: object
simples.ajax() will return an object which will create an XMLHttpRequest to the provided url and using the provided method and parameters. This object has 3 methods to attach listeners for error, progress and success events, which are named with the respective events. Example:
simples.ajax('/', 'post', {
user: 'me',
password: 'ok'
}).error(function (response) {
// Application logic
}).progress(function (response) {
// Application logic
}).success(function (response) {
// Application logic
});simples.ws(host, protocols, raw)
host: string
protocols: array
raw: boolean
simples.ws() will return an object which will create an WebSocket connection to the provided host and protocols. If raw parameter is set to true then this connection will use a low level communication with the server, else the connection will use a event based communication with the server, which is more intuitive, by default raw is set to true. This object is an event emitter (has the folowing methods: .emit(), .addListener(), .on(), .once(), .removeAllListeners(), .removeListener()). To receive a message in raw mode .on('message' function () {/*...*/}) should be used, for advanced mode .on(EVENT, function () {/*...*/}) is used. To send data to the server the .send() method is used, in raw mode it should have only one parameter, the data, in advanced mode it should have two parameters, the event and the data. .emit() method is used to trigger the events locally, but not on the server, this is useful for triggering instantly the event on the client or for debugging. To close the WebSocket connection .close() method is used. Example:
simples.ws('/', ['echo'], true).on('message', function (message) {
this.send('Hello World');
});