Merge pull request #229 from mandarineorg/docs-220

Docs 2.2.0

docs/web/mandarine/endpoints.json

@@ -303,8 +303,20 @@
       "url": "entry-point",
       "document": "mandarine-mvc/entry-point.md"
     },
+    {
+      "url": "entry-point-builders",
+      "document": "mandarine-mvc/entry-point-builder.md"
+    },
     {
       "url": "built-in-response-time-header",
       "document": "mandarine-mvc/built-in-response-time-header.md"
+    },
+    {
+      "url": "exposed-injectables",
+      "document": "mandarine-core/exposed-injectables.md"
+    },
+    {
+      "url": "exposed-injectable-logger",
+      "document": "mandarine-core/exposed-injectable-logger.md"
     }
 ]

docs/web/mandarine/main-concepts/environmental-variables.md

@@ -10,3 +10,21 @@ With Mandarine's environmental variables you can alter certain behaviors at Deno
 
 - `MANDARINE_PROPERTY_FILE`
     - Location of `properties.json` file. Useful when `mandarine.json` is not present or when not wanting to use `mandarine.json` to indicate the location of this file.
+
+- `MANDARINE_SERVER_HOST`: string
+    - Specifies the host ip where Mandarine MVC should run.
+
+- `MANDARINE_SERVER_PORT`: number
+    - Specifies the port where Mandarine MVC should run.
+
+- `MANDARINE_SERVER_RESPONSE_TIME_HEADER`: boolean
+    - Specifies whether the `X-Response-Time` header should be enabled by default or not.
+
+- `MANDARINE_SERVER_SESSION_MIDDLEWARE`: boolean
+    - Specifies whether the session middleware should be enabled by default or not.
+
+- `MANDARINE_STATIC_CONTENT_FOLDER`: string
+    - Specifies the path of the folder where static content will be served if any.
+
+- `MANDARINE_AUTH_EXPIRATION_MS`: number
+    - Amount of time an authentication session should take in order to expire (in milliseconds)

docs/web/mandarine/main-concepts/mandarine-properties.md

@@ -13,7 +13,8 @@ Mandarine.TS contains a property structure that allows the developer to modify s
                 host?: string,
                 port: number,
                 responseType?: MandarineMVC.MediaTypes,
-                responseTimeHeader?: boolean
+                responseTimeHeader?: boolean,
+                enableSessions?: boolean
             } & any,
             resources: {
                 staticRegExpPattern?: string,
@@ -50,13 +51,14 @@ Mandarine.TS contains a property structure that allows the developer to modify s
 ## Default values
 
 ```typescript
-
 {
     mandarine: {
         server: {
             host: "0.0.0.0",
             port: 8080,
-            responseType: Mandarine.MandarineMVC.MediaTypes.TEXT_HTML
+            responseType: Mandarine.MandarineMVC.MediaTypes.TEXT_HTML,
+            responseTimeHeader: false
+            enableSessions: true
         },
         resources: {
             staticFolder: "./src/main/resources/static",

docs/web/mandarine/mandarine-core/exposed-injectable-logger.md

@@ -0,0 +1,15 @@
+# Logger as Injectable
+With Mandarine exposing its internal logger as an injectable, you may write content on the console keeping the format Mandarine has.
+
+---------
+
+## Usage
+
+```typescript
+import { Log } from "https://deno.land/x/mandarinets@v2.2.0/mod.ts"; 
+
+@Service()
+export class MyService {
+    constructor(logger: Log) {}
+}
+```

docs/web/mandarine/mandarine-core/exposed-injectables.md

@@ -0,0 +1,6 @@
+# Exposed Injectables
+
+-----------
+
+
+Mandarine has a list of injectables (components that can be used through [Dependency Injection](https://www.mandarinets.org/docs/master/mandarine/dependency-injection)) that you may use in your application.

docs/web/mandarine/mandarine-mvc/entry-point-builder.md

@@ -0,0 +1,50 @@
+# Application Builder
+Mandarine allows you to create an entry point with its application builder. The application builder has many advantages, one of it being having cleaner code in your entry point file.
+
+-------------------
+
+## Usage
+
+**Case #1**    
+By using `automaticBuildAndRun`, Mandarine will handle running and configuring your application automatically, including the different imports of the different components you have created. These components **must be** available for exports & imports.
+
+> Note: Mandarine will create a folder called `.mandarine_target` where the auto-generated entry point will be located.
+
+```typescript
+import { AppBuilder } from "https://deno.land/x/mandarinets@v2.2.0/appBuilder.ts";
+
+new AppBuilder().automaticBuildAndRun({
+    tsconfigPath: "./tsconfig.json",
+    flags: ["--allow-all", "--unstable"],
+    reload: false
+});
+```
+
+-------------
+
+**Case #2**   
+By using `buildMVC`, you must supply the components that Mandarine will be working with (this includes your controllers, services, middleware, and any other Mandarine-powered component you have created).
+
+```typescript
+import { AppBuilder } from "https://deno.land/x/mandarinets@v2.2.0/appBuilder.ts";
+import { MyController, MyService } from "imports.ts";
+
+new AppBuilder().setHost("127.0.0.1").setPort(1099).buildMVC([MyController, MyService]).run();
+
+```
+
+------------
+
+## Builder Methods
+
+| Method | Description |
+| ------ | ----------- | 
+| `setHost` | Sets the host IP where Mandarine MVC will run |
+| `setPort` | Sets the port where Mandarine MVC will run |
+| `enableResponseTimeHeader` | Enables `X-Response-Time` <br> Optionally, you could supply a boolean value to enable/disable |
+| `enableSessions` | Enables [the session middleware](https://www.mandarinets.org/docs/master/mandarine/session-middleware) <br> Optionally, you could supply a boolean value to enable/disable |
+| `setStaticContentFolder` | Sets the directory path for serving static content |
+| `setAuthExpirationTime` | Sets the amount of time an authentication session should take in order to be expired |
+| `buildCore` | Takes an array of classes (Mandarine-powered components) to be built in the core & builds the core |
+| `buildMVC` | Takes an array of classes (Mandarine-powered components), builds the core & the MVC engine |
+| `automaticBuildAndRun` | Automatically detects Mandarine-powered components, generates an entry-point file & runs the application |

docs/web/mandarine/mandarine-mvc/session-middleware.md

@@ -26,3 +26,23 @@ Sessions are unique per requester, it is a way to tell your web server who is re
 
 ## Accessing The Session Object
 As described above, the session object is part of the request object when a request is made to an endpoint. The session object is accessible via the use of [HTTP Parameter Decorators](/docs/mandarine/http-handlers), by using the decorator `@Session()` . Please, refer to the link in order to understand this concept.
+
+
+------------
+
+## Disabling Session Middleware
+Some scenearios may require the session middleware to be disabled, these scenarios may go from wanting a better performance when measuring or internal cases which are up to the developer. For this you may:
+
+- Set `mandarine.server.enableSessions` to false in your properties file. For more information about custom properties [click here](https://www.mandarinets.org/docs/master/mandarine/custom-properties)
+
+```json
+{
+    "mandarine": {
+        "server": {
+            "enableSessions": false
+        }
+    }
+}
+```
+
+- Set an environmental variable (`MANDARINE_SERVER_SESSION_MIDDLEWARE`) when running Deno with `false` as its value.

docs/web/mandarine/mandarine-security/session-container.md

@@ -57,24 +57,24 @@ export interface SessionCookie {
 For the session container, this is the most important interface. The implementations with this interface will handle the logic behind saving, modifying, and deleting a session.
 ```typescript
 export interface SessionStore {
-    options: {
-        expirationIntervalHandler: any;
-        expirationInterval: number;
-        autoclearExpiredSessions: boolean;
-        expiration: number; 
-    };
-    launch(): void;
-    get(sessionID: string, callback: (error, result: Mandarine.Security.Sessions.MandarineSession) => void, config?: { touch: boolean }): void;
-    getAll(callback: (error, result: Array<Mandarine.Security.Sessions.MandarineSession>) => void): void;
-    set(sessionID: string, session: Mandarine.Security.Sessions.MandarineSession, callback: (error, result) => void): void;
-    destroy(sessionID: string, callback: (error, result: any) => void): void;
-    touch(sessionId: string, callback: (error, result: any) => void): void;
-    exist?(sessionID: string): boolean;
+        options: {
+            expirationInterval: any,
+            autoclearExpiredSessions: boolean
+        }
 
-    clearExpiredSessions(): void;
-    startExpiringSessions(): void;
-    stopExpiringSessions(): void;
-    stopIntervals(): void;
+        launch(): void;
+        get(sessionID: string, config?: { touch: boolean }): Mandarine.Security.Sessions.MandarineSession | undefined,
+        getAll(): Array<Mandarine.Security.Sessions.MandarineSession>,
+        set(sessionID: string, session: Mandarine.Security.Sessions.MandarineSession, config?: { override: boolean }): Mandarine.Security.Sessions.MandarineSession;
+        destroy(sessionID: string): void;
+        touch(sessionID: string): Mandarine.Security.Sessions.MandarineSession | undefined;
+        exists(sessionID: string): boolean;
+        clearExpiredSessions(): void;
+        startExpiringSessions(): void;
+        stopIntervals(): void;
+        getExpirationInterval(): void;
+        setExpirationInterval(intervalHandler: any): void;
+        getDefaultExpiration(): number;
 }
 ```
 - `launch`
@@ -91,17 +91,22 @@ export interface SessionStore {
     - Removes a session from the session container
 - `touch`
     - Re-calculates the expiration time
-- `exist`
+- `exists`
     - Verifies whether a session is in the session container
 - `clearExpiredSessions`
     - Function to be called by the _"expired sessions interval"_.
     - This function holds the logic behind removing expired sessions.
 - `startExpiringSession`
     - Creates and adds a `setInterval` to `options.expirationIntervalHandler`, this interval should have `clearExpiredSessions` as its callback.
-- `stopExpiringSessions`
-    - Clears the interval for expired sessions
 - `stopIntervals`
     - This function should hold the logic behind clearing any interval available in the session store implementation
+- `getExpirationInterval`
+    - Get the variable where `setInterval` was assigned.
+- `setExpirationInterval`
+    - Sets a new `setInterval` to internal variable
+- `getDefaultExpiration`
+    - Gets the expiration time of the session (in milliseconds)
+    - Default: `(1000 * 60 * 60 * 24)` (1 day)
 
 &nbsp;
 

docs/web/mandarine/menu-items.json

@@ -137,6 +137,16 @@
               "url": "native-components-list"
             }
           ]
+        },
+        {
+          "title": "Exposed Injectables",
+          "url": "exposed-injectables",
+          "children": [
+            {
+              "url": "exposed-injectable-logger",
+              "title": "Logger"
+            }
+          ]
         }
       ]
     },
@@ -151,6 +161,10 @@
           "title": "Entry Point",
           "url": "entry-point"
         },
+        {
+          "title": "Entry Point Builder",
+          "url": "entry-point-builders"
+        },
         {
           "title": "Resource Handlers",
           "url": "resource-handlers",

main-core/mandarineAppBuilder.ts

@@ -30,13 +30,13 @@ export class AppBuilder {
         return this;
     }
 
-    public enableResponseTimeHeader(): AppBuilder {
-        Deno.env.set(MandarineEnvironmentalConstants.MANDARINE_SERVER_RESPONSE_TIME_HEADER, "true");
+    public enableResponseTimeHeader(value: boolean = true): AppBuilder {
+        Deno.env.set(MandarineEnvironmentalConstants.MANDARINE_SERVER_RESPONSE_TIME_HEADER, value.toString());
         return this;
     }
 
-    public enableSessions(): AppBuilder {
-        Deno.env.set(MandarineEnvironmentalConstants.MANDARINE_SERVER_SESSION_MIDDLEWARE, "true");
+    public enableSessions(value: boolean = true): AppBuilder {
+        Deno.env.set(MandarineEnvironmentalConstants.MANDARINE_SERVER_SESSION_MIDDLEWARE, value.toString());
         return this;
     }
 
@@ -73,7 +73,7 @@ export class AppBuilder {
             const decorators = readDecoratorsExportedClass(decoder.decode(Deno.readFileSync(path)));
             if(decorators !== null) {
                 const insertionDecorators = decorators.map(decorator =>  { decorator.filePath = path; return decorator; });
-                entries.set(path, decorators.map(decorator =>  { decorator.filePath = path; return decorator; }));
+                entries.set(path, insertionDecorators);
             }
         }