more docs

docs/docs/getting-started/docker.md

@@ -8,6 +8,8 @@ exa.js is intended to be used with or without docker in both development and pro
 
 ## compose file
 
+the only item in the docker compose file that may need to be changed is the port number. by default it uses the same port that is configured in `config/master.js` for the app.
+
 ```yaml title="docker-compose.yml"
 services:
     app:
@@ -41,3 +43,20 @@ services:
         profiles:
             - nostart
 ```
+
+## helper script
+
+for your convenience, a docker helper script is located in the root directory to help interact with an exa.js project running in docker more easily. the helper script has the following functions:
+
+- `./docker.sh dev` - starts app in foreground
+- `./docker.sh start` - starts app in background
+- `./docker.sh stop` - stops app
+- `./docker.sh shell` - opens shell to the container running the app
+- `./docker.sh console <name>` - runs a console command by name
+- `./docker.sh jmig <command>` - runs jmig in the app container
+  * requires the app to be running
+- `./docker.sh npm <args>` - runs npm in the root directory of the app
+
+:::tip[Tip]
+if your project was initialized to use `bun`, swap `npm` for `bun` anywhere it appears
+:::

docs/docs/getting-started/project-structure.md

@@ -27,7 +27,7 @@ contains express.js compatible middleware. middleware is configured for use in a
 contains [jmig](https://github.com/realtux/jmig) compatible database migrations files. these are used to apply and rollback changes to a database. please see the jmig readme for usage specifics.
 
 ### models
-contains sequelize.js compatible database model files. to use a different database orm, set `database.use = false` in `config/master.js` which will disable automatic initialization of the `models` folder. see docs for proper format.
+contains sequelize.js compatible database model files. to use a different database orm, set `database.use = false` in `config/master.js` which will disable automatic initialization of the `models` directory. see docs for proper format.
 
 ### public
 contains publicly available static files. in development, this is served with `express.static()` at base url `/public`. in production, this should be served with a normal web server.

docs/docs/modules/console.md

@@ -23,5 +23,30 @@ export default new class {
     }
 
 };
+```
+
+## running a console command
+
+all the following examples assume a script called `sample` is located at `console/sample.js`.
+
+### from root directory
+
+```bash
+npm run sample
+```
+
+### via a cronjob
+
+```bash
+npm --prefix /path/to/app run sample
+```
+
+### while using docker
+
+```bash
+# from root directory
+./docker.sh console sample
 
+# via cronjob
+/path/to/app/docker.sh console sample
 ```

docs/docs/modules/http.md

@@ -0,0 +1,116 @@
+---
+sidebar_position: 2
+---
+
+# http
+
+this module is used for exposing http routes for use in apis and other purposes.
+
+## concept
+
+files are organized within the `http` directory in any manner desired. a common pattern used is to have directories in the same structure that your urls will ultimately be, however, this is entirely up to you. exa.js on start will process all files recursively that are present in the `http` directory.
+
+## internal handling
+
+http server and routes and implemented using express.js, a well known and trusted http server. everything express.js supports is also supported in exa.js.
+
+## anatomy of an http file
+
+the following is the structure of an http file
+
+```js title="http/sample.js"
+import authorized from '#app/middleware/authorized.js';
+
+export default new class {
+
+    routes = {
+        'get /hello/world': 'world',
+    }
+
+    middleware = {
+        '*': [authorized]
+    }
+
+    async world(req, res) {
+        return res
+            .status(200)
+            .send({
+                message: 'hello world'
+            });
+    }
+
+};
+```
+
+### routes
+
+each route is a key composed of the http method and route path or pattern with a string value of the name of the method it should call. because this just wraps express.js internally, it supports everything express.js supports, including:
+
+basic routes
+```js
+routes = {
+    'get /hello/world': 'world',
+}
+```
+
+regex routes
+```js
+routes = {
+    'get /pets/(dog|cat)': 'pet',
+}
+```
+
+param routes
+```js
+routes = {
+    'get /blogs/:blog_id': 'get_blog',
+}
+```
+
+### middleware
+
+one or more pieces of middleware can be ran prior to the route method being called. this middleware is great for many purposes such as authentication, setting context variables, or performing pre-route logic.
+
+a middleware file looks like this:
+
+```js title="middleware/authorized.js"
+export default async (req, res, next) => {
+    // middleware logic
+    if (req.headers.authorization !== 'abc123') {
+        return res
+            .status(401)
+            .send();
+    }
+
+    return next();
+};
+```
+
+this middleware checks an api key to see if it's the right value. if it's not, a 401 unauthorized response is received, otherwise `next()` is called which either calls the next middleware in the chain or calls the route method.
+
+to use middleware, add key/value pairs to the `middleware` object. the key should be the method name and the value should be an array of middleware to run.
+
+```js
+// apply authorized middleware to all routes
+middleware = {
+    '*': [authorized],
+}
+
+// apply authorized middleware to one route
+middleware = {
+    hello: [authorized],
+}
+
+// apply authorized middleware to all routes except for hello
+middleware = {
+    '*': [authorized],
+    hello: []
+}
+
+// apply common and authorized middleware to all routes
+middleware = {
+    '*': [common, authorized],
+}
+```
+
+middleware precedence is top to bottom. this is why everything works in the third example. `hello` has a value of blank array.

docs/docs/modules/websockets.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 4
 ---
 
 # websockets
@@ -8,13 +8,13 @@ this module is used for exposing urls that upgrade to websocket connections.
 
 ## concept
 
-zero or more files are created in the `websocket` directory. each file is intended to be used for a single url that upgrades to websocket. the file can be named anything and has no effect on functionality. all files in the `websocket` folder will be loaded and processed when `exa.js` starts.
+zero or more files are created in the `websocket` directory. each file is intended to be used for a single url that upgrades to websocket. the file can be named anything and has no effect on functionality. all files in the `websocket` directory will be loaded and processed when `exa.js` starts.
 
 ## internal handling
 
 the websocket server implementation is handled using the well known and trusted `ws` module. this module largely just wraps `wss.on('connection', callback)`. connections are upgraded from regular http requests rather than running entirely separate servers on separate ports. this makes enabling websockets very easy.
 
-## file structure
+## anatomy of a websocket handler
 
 a websocket handler looks like this:
 

readme.md

@@ -51,7 +51,7 @@ initializing will create the exa.js template project structure in the current di
 *contains [jmig](https://github.com/realtux/jmig) compatible database migrations files. these are used to apply and rollback changes to a database. please see the jmig readme for usage specifics.*
 
 - **models**  
-*contains sequelize.js compatible database model files. to use a different database orm, set `database.use = false` in `config/master.js` which will disable automatic initialization of the `models` folder. see docs for proper format.*
+*contains sequelize.js compatible database model files. to use a different database orm, set `database.use = false` in `config/master.js` which will disable automatic initialization of the `models` directory. see docs for proper format.*
 
 - **public**  
 *contains publicly available static files. in development, this is served with `express.static()` at base url `/public`. in production, this should be served with a normal web server.*