Initial commit

node_modules/server/api.js

@@ -0,0 +1,127 @@
+// API Specification
+// This document is to define server's stable API
+// - Main function
+// - options
+// - middleware
+// - context
+// - router
+// - reply
+// - utils
+
+
+
+// Main function
+const server = require('server');
+
+// Definition: an ASYNC function that accepts options and/or middleware
+server(opts, mid1, mid2, ...).then(...);
+
+// Properties (defined below)
+server.router;
+server.reply;
+server.utils;
+
+
+
+// Options
+const ops = {
+
+  // Simple options
+  port,
+  engine,
+  public,
+  secret,
+  log,
+
+  // TODO: MISSING MANY HERE; THIS PART IS NOT YET STABLE
+
+  // Plugins options
+  core,
+  parser,
+};
+
+
+
+// Middleware
+// Definition: (a)sync function, accepts the Context and returns a reply
+const mid1 = ctx => { ... };
+const mid2 = async ctx => { ... };
+
+// Return types
+// String => HTML or PLAIN response
+const mid = ctx => 'Hello world';
+// Array/Object => JSON response
+const mid = ctx => ['I', 'am', 'json'];
+const mid = ctx => ({ hello: 'world' });  // To return an object the extra () is needed
+// Reply instance
+const mid = ctx => server.reply.send('hello world');
+
+
+
+// Context
+// Definition: all of the currently known data. Varies depending on location
+// NOTE: there are more properties, but they are not considered stable
+ctx.options,  // the specified or inherited options
+ctx.log,      // a method to log things in several levels
+ctx.reply,    // same as above
+ctx.utils,    // utilities
+ctx.server,   // the currently running server instance
+
+// For middleware/routers
+ctx.data,     // the parsed body if it's a POST request
+ctx.params,   // NOTE: NOT YET, rely on ctx.req.params so far
+ctx.query,    // NOTE: NOT YET, rely on ctx.req.query so far
+// ...
+
+// Non-stable (will change at some point in the future)
+ctx.req,      // express request; considering removing/changing it in 1.1
+ctx.res,      // express response; not useful anymore, use server.reply instead
+
+
+
+// Router
+const router = server.router;
+const router = require('server/router');
+
+// Definition: handle the different methods and paths requested
+router.get('/', mid1);
+router.post('/users', mid2);
+router.put('/users/:id', mid3);
+
+// Methods (REST methods not explained):
+router.get;
+router.post;
+router.put;
+router.del;
+router.socket;  // Handle websocket calls
+router.error;   // Handle errors further up in the chain
+
+
+
+// Reply
+const reply = server.reply;
+const reply = require('server/reply');
+
+// Definition: handle the response from your code
+// Note: it MUST be returned from the middleware or it won't be executed
+reply.cookie;
+reply.download;
+reply.end;
+reply.file;
+reply.header;
+reply.json;
+reply.jsonp;
+reply.redirect;
+reply.render;
+reply.send;
+reply.status;
+reply.type;
+
+
+
+// Utils
+const utils = server.utils;
+const utils = require('server/utils');  // NOT YET AVAILABLE
+
+// Definition: some extra utilities to make development easier
+utils.modern;  // Make express middleware work with server.js