api-overview.md

This is a very rough and verbose overview of an API that is simplistic and can be kept consistent across the entire code base. I visited many API possibilities that could have been used, and this API came out as the best combination of everything available.

First we'll start with examples from the file system API. This is a partial set of all features that already exist, also included are some new APIs.

File System

new File(path)

Create a new file system object that can be operated on.

Object Functions

File.lsof()

Return an array of all file resources that are open.

File.rx()

Return number of bytes read from all files since start of the applications.

File.tx()

Return number of bytes written to all files since start of the application.

Prototype Methods

File#stat(callback)

Retrieve statistics about the file resource.

File#open(flags[, mode], callback)

Open the file resource

File#close(callback)

Close the file resource.

File#read(position, length, callback)

Read data starting at byte position for byte length.

File#write(buffer, offset, length[, position], callback)

Write buffer to file resource.

File#rx()

Return the number of bytes have been read from the file.

File#tx()

Return he number of bytes written to the file.

FS Example

var myFile = new File('/path/to/my/file');

myFile.open('r+', function fileOpen(er) {
  if (er)
    throw er;
  this.read(0, 16, fileRead);
});

function fileRead(er, data) {
  if (er)
    throw er;
  console.log('Bytes read: ' + this.rx());
  this.write(data, 0, data.length, fileWrite);
}

function fileWrite(er) {
  if (er)
    throw er;
  console.log('Bytes written: ' + this.tx());
  this.close(fileClose);
}

function fileClose(er) {
  if (er)
    throw er;
}

TCP

new TCP()

Create new TCP resource.

Object Functions

TCP.rx()

Return number of bytes read from all TCP connections.

TCP.tx()

Return number of bytes written to all TCP connections.

Prototype Methods

TCP#listen(port[, hostname][, backlog], callback)

Bind to a port and listen for incoming connections.

TCP#connect(port[, host][, callback])

Connect to port.

TCP#onerror(callback)

Call callback if there's an error on the server.

TCP#onconnection(callback)

When a connection is received byte the server call callback.

TCP#onclose(callback)

When the server has been closed.

Connections

Prototype Methods

Connection#rx()

Connection#tx()

Connection#flush()

Flush the written data to the client. Data being written is automatically queued during the synchronous write portion of the script, then written out once when done. flush() will automatically write data out to the client immediately.

Connection#ondata(callback)

Connection#onerror(callback)

Connection#onclose(callback)

TCP Example

var server = new TCP();

server.onerror(onServerError);
server.onconnection(function onConnection(c) {
  c.onerror(onConnectionError);
  c.ondata(onData);
});

function onData() {
  var data;
  // The connection stream is automatically chunked mode.
  while (data = this.read()) {
    this.write(data);
  }
  this.end(onConnectionEnd);
}

function onConnectionEnd() {
  console.log('Number of bytes read by connection: ' + this.rx());
  console.log('Number of bytex written by connection: ' + this.tx());
  this.server.close(onServerClose);
}

function onServerClose() {
  console.log('Number of bytes read by server: ' + this.rx());
  console.log('Number of bytes written by server: ' + this.tx());
  console.log('Server has been closed');
}