structured-fw 0.7.5 → 0.7.7

package/Config.ts

@@ -1,4 +1,4 @@
-import { StructuredConfig } from 'structured-fw/system/Types.js';
+import { StructuredConfig } from 'structured-fw/Types';
 
 export const config: StructuredConfig = {
     // Application.importEnv will load all env variables starting with [envPrefix]_

package/README.md

@@ -7,32 +7,274 @@ It works with Node.js and Deno runtimes. Other runtimes are not tested.
 
 - [Why Structured](#why-structured)
 - [Audience](#audience)
-
+- [Getting started](#getting-started)
 
 ### Key concepts:
+* [Application](#application)
 * [Route](#route)
 * [Document](#document)
 * [ClientComponent](#component) (component)
 
+## Getting started
+
+### Initialize a Node.js project
+```
+cd /path/to/project
+npm init -y
+npm install @types/node
+```
+
+*If you have TypeScript installed globally then you can skip the following*\
+`npm install --save-dev typescript`
+
+### Install Structured
+`npm install structured-fw`
+
+### Create boilerplate
+`npx structured init`
+
+### Compile
+`tsc`\
+This will create a directory `build` (or whatever you have in tsconfig.json as compilerOptions.outputDir)
+
+### Run
+```
+cd build
+node index.js
+```
+
+Of course, you can use pm2 or other process managers to run it, with pm2:
+```
+cd build
+pm2 start index.js --name="[appName]"
+```
+
+# Key concepts
+
+## Application
+Application instance is the base of any Structured application. You will usually create an instance of Application in index.ts (or whatever you decide to be the entry point file name). Application starts a http server, creates instances of all classes that are required for the functioning of your application and allows handling of various events that will occur when your app is running.\
+Application constructor requires one argument of type `StructuredConfig`:
+```
+type StructuredConfig = {
+    readonly envPrefix?: string,
+    readonly autoInit: boolean,
+    url: {
+        removeTrailingSlash: boolean,
+        componentRender: false | string,
+        isAsset: (url: string) => boolean
+    },
+    routes: {
+        readonly path: string
+    },
+    components: {
+        readonly path: string,
+        readonly componentNameAttribute: string
+    },
+    session: {
+        readonly cookieName: string,
+        readonly keyLength: number,
+        readonly durationSeconds: number,
+        readonly garbageCollectIntervalSeconds: number,
+        readonly garbageCollectAfterSeconds: number
+    },
+    http: {
+        host?: string,
+        port: number,
+        linkHeaderRel: 'preload' | 'preconnect'
+    },
+    readonly runtime: 'Node.js' | 'Deno'
+}
+```
+
+If you created the boilerplate using `npx structured init` then a sample `Config.ts` has been created in the project root. You can read the comments there if you need clarification on what each config option affects.
+
+The most basic entry point may look something like this:
+```
+import { Application } from "structured-fw/Application";
+import { config } from "./Config.js";
+
+new Application(config);
+```
+
+### Properties
+- `cookies` - Instance of Cookies, allows you to set a cookie
+- `session` - Instance of Session, utilities to manage sessions and data
+- `request` - Instance of Request, you will use this to add routes, but usually not directly by accessing Application.request, more on that in [routes](#route) section
+- `handlebars` - Instance of Handlebars (wrapper around Handlebars templating engine)
+- `components` - Instance of Components, this is the components registry, you should never need to use this directly
+
+### Methods
+- `init(): Promise<void>` - initializes application, you only need to run this if you set `autoInit = false` in config, otherwise this will be ran when you create the Application instance
+- `on(evt: ApplicationEvents, callback: RequestCallback|((payload?: any) => void))` - allows you to add event listeners for specific `ApplicationEvenets`:
+    - `serverStarted` - executed once the built-in http server is started and running. Callback receives no arguments
+    - `beforeRequestHandler` - runs before any request handler (route) is executed. Callback receives `RequestContext` as the first argument. Useful for example to set `RequestContext.data: RequestContextData` (user defined data, to make it available to routes and components)
+    - `afterRequestHandler` - runs after any request handler (route) is executed. Callback receives `RequestContext` as the first argument
+    - `afterRoutes` - runs after all routes are loaded from `StructuredConfig.routes.path`. Callback receives no arguments
+    - `beforeComponentLoad` - runs before components are loaded from `StructuredConfig.components.path`. Callback receives no arguments
+    - `afterComponentLoad` - runs after all components are loaded from `StructuredConfig.components.path`. Callback receives no arguments
+    - `documentCreated` - runs whenever an instance of a [Document](#document) is created. Callback receives the Document instance as the first argument. You will often use this, for example if you want to include a CSS file to all pages `Document.head.addCSS(...)`
+    - `beforeAssetAccess` - runs when assets are being accessed, before response is sent. Callback receives `RequestContext` as the first argument
+    - `afterAssetAccess` - runs when assets are being accessed, after response is sent. Callback receives `RequestContext` as the first argument
+    - `pageNotFound` - runs when a request is received for which there is no registered request handler (route), and the requested URL is not an asset. Callback receives `RequestContext` as the first argument
+    - **Callback to any of the `ApplicationEvents` is expected to be an async function**
+- `importEnv<T extends LooseObject>(smartPrimitives: boolean = true): T` - import ENV variables that start with `StructuredConfig.envPrefix`_ (if envPrefix is omitted from config, all ENV variables are returned). It is a generic method so that you can specify the expected return type. If `smartPrimitives = true` importEnv will convert the ENV values to type it feels is appropriate:
+    - numeric values -> `number`
+    - "true"|"false" -> `boolean`
+    - "null" -> `null`
+    - "undefined" -> `undefined`
+- `exportContextFields(...fields: Array<keyof RequestContextData>): void` - allows you to export any fields from `RequestContextData` to all components (even if they don't have server side code)
+
+What your entry point may look like in a real-world application:
+```
+import { Application } from "structured-fw/Application";
+import { config } from './Config.js';
+import { userModel } from './app/models/User.js';
+
+const app = new Application(config);
+
+const env = app.importEnv<{ COOKIE_AUTOLOGIN: string }>();
+
+app.on('documentCreated', (doc: Document) => {
+    doc.head.setFavicon({
+        image: '/assets/img/favicon.png',
+        type: 'image/png'
+    });
+    doc.head.addCSS('/assets/css/dist.css', 0);
+});
+
+app.on('beforeRequestHandler', async (ctx: RequestContext) => {
+
+    // set ctx.data.user from session
+    ctx.data.user = app.session.getValue<User>(ctx.sessionId, 'user');
+
+    if (! ctx.data.user) {
+        // check if user has an autologinKey cookie set
+        const autologinCookie = ctx.cookies[env.COOKIE_AUTOLOGIN];
+        if (autologinCookie) {
+            const user = await userModel.getByAutologinKey(autologinCookie);
+            if (user) {
+                ctx.data.user = user;
+            }
+        }
+    }
+});
+
+// load handlebars helpers (which will become available in all components)
+app.handlebars.loadHelpers(path.resolve('./app/Helpers.js'));
+
+// make user available to all components
+app.exportContextFields('user');
+
+```
+
 ## Route
 Routes are the first thing that gets executed when your application receives a request. They are a mean for the developer to dictate what code gets executed depending on the URL. In addition to that, they allow capturing parts of the URL for use within the route.
-\
-\
+
+
+You can add routes from your entry point using `app.request.on(RequestMethod, URLPattern, requestHandler)`, but you will never want to do that unless your entire application has a very few routes, in which case it would be acceptable.
+
 **Simple route:**
 ```
 app.request.on('GET', '/hello/world', async () => {
     return 'Hello, world!';
 });
 ```
-\
-**Capture URL segment:**
+
+
+In a real life situation, you will likely have quite a few routes that you want to handle, and it usually makes sense to group them in multiple files, for example Auth.ts, Users.ts, Products.ts, etc...
+When Application instance is created and initialized, it will load all routes from `conf.routes.path`.
+
+All route files need to export a function that will receive the Application instance as the first argument:
+```
+import { Application } from "structured-fw/Application";
+
+export default function(app: Application) {
+    // all routes that belong to this file come here
+    app.request.on(...)
+}
+```
+
+Route file name has no effect on how the route (request handler) behaves, the only purpose of splitting your routes in separate files is making your code more maintainable.
+
+### RequestContext
+All request handlers receive a `RequestContext` as the first argument.
+```
+type RequestContext = {
+    request: IncomingMessage,
+    response: ServerResponse,
+    args: URIArguments,
+    handler: null|RequestHandler,
+
+    cookies: Record<string, string>,
+
+    // POSTed data, parsed to object
+    body?: PostedDataDecoded,
+
+    bodyRaw?: Buffer,
+
+    // files extracted from request body
+    files?: Record<string, RequestBodyRecordValue>,
+
+    // user defined data
+    data: RequestContextData,
+
+    // if session is started and user has visited any page
+    sessionId?: string,
+
+    // true if x-requested-with header is received and it equals 'xmlhttprequest'
+    isAjax: boolean,
+
+    // URL GET arguments
+    getArgs: PostedDataDecoded,
+
+    // send given data as a response
+    respondWith: (data: any) => void,
+
+    // redirect to given url, with given statusCode
+    redirect: (to: string, statusCode?: number) => void,
+
+    // show a 404 page
+    show404: () => Promise<void>
+}
+```
+
+**Capture URL segment:**\
+Any URL segments in parenthesis will become available in ctx.args. For example:
 ```
 app.request.on('GET', '/greet/(name)', async (ctx) => {
     return `Hello, ${ctx.args.name}!`;
 });
 ```
+You can capture any number of URL segments in this way.
+
+**Capture group modifiers:**\
+Capture group in URL pattern is (name) in above example. It makes data available within your route. Name will capture any string. Sometimes we know we expect a number in our URLs, in which case it is useful to use the modifier :num (which is the only modifier available), for example:
+```
+app.request.on('GET', '/greet/(userId:num)', async (ctx) => {
+    const userId = ctx.args.userId as number;
+    // fetch user from DB
+    const user = await userModel.get(userId);
+    return `Hello, ${user.name}!`;
+});
+```
+It is safe to cast `ctx.args.userId` as `number` in above example because the route would not get executed if the second segment of the URL is not a numeric value, and in case :num modifier is used, URL-provided value is parsed to a number and you don't need to parseInt manually.
 
 
+**Doing more with less code**\
+You can have the same route be executed for multiple different request methods or URLs. Both request method (first argument) and URL pattern (second argument) can be an array.
+```
+app.request.on(['GET', 'POST'], ['/greet/(name)', '/hello/(name)'], async (ctx) => {
+    return `Hello, ${ctx.args.name}!`;
+});
+```
+Above is equivalent of registering 4 request handlers one-by-one:\
+GET '/greet/(name)'\
+POST '/greet/(name)'\
+GET '/hello/(name)'\
+POST '/hello/(name)'
+
+**RegExp as URLPatter**\
+In some edge cases you may need more control of when a route is executed, in which case you can use a regular expression as URLPattern. If you use a RegExp, ctx.args will be `RegExpExecArray` so you can still capture data from the URL. This is very rarely needed because Structured router is versatile and covers almost all use cases.
 
 ## Document
 Document does not differ much from a component, in fact, it extends Component. It has a more user-firendly API than Component. Each Document represents a web page. It has a head and body. Structured intentionally does not differentiate between a page and a Component - page is just a component that loads many other components in a desired layout. DocumentHead (each document has one at Document.head) allows adding content to `<head>` section of the output HTML page.

package/bin/structured

@@ -78,7 +78,7 @@ function createTsconfig() {
                 "strictNullChecks": true,
                 "strictPropertyInitialization": true,
                 "strictBindCallApply": true,
-                "moduleResolution" : "Node",
+                "moduleResolution" : "bundler",
                 "outDir": "./build",
                 "module": "ES2020",
                 "target": "ES2021",

package/build/Config.d.ts

@@ -1,2 +1,2 @@
-import { StructuredConfig } from 'structured-fw/system/Types.js';
+import { StructuredConfig } from 'structured-fw/Types';
 export declare const config: StructuredConfig;

package/build/app/routess/Auth.js

@@ -0,0 +1 @@
+"use strict";

package/build/app/routess/Test.d.ts

@@ -0,0 +1,2 @@
+import { Application } from '../../system/server/Application.js';
+export default function (app: Application): void;

package/build/app/routess/Test.js

@@ -0,0 +1,101 @@
+import { Document } from '../../system/server/Document.js';
+import { Request } from '../../system/server/Request.js';
+export default function (app) {
+    app.request.on('GET', '/test/form', async (ctx) => {
+        const doc = new Document(app, 'Form test', ctx);
+        await doc.loadComponent('FormTestNested', { test: 3 });
+        ctx.respondWith(doc);
+    });
+    app.request.on('POST', '/test/form', async (ctx) => {
+        console.log(JSON.stringify(ctx.body, undefined, 4));
+        const userImage = ctx.files.user.image[0];
+        ctx.response.setHeader('Content-Type', userImage.type);
+        ctx.respondWith(userImage.data);
+    });
+    app.request.on('GET', '/test/client_import', async (ctx) => {
+        const doc = new Document(app, 'Test', ctx);
+        await doc.loadComponent('ClientImport', { xyz: 10, asd: 12 });
+        ctx.respondWith(doc);
+    });
+    app.request.on('GET', '/test/redraw', async (ctx) => {
+        const doc = new Document(app, 'Test', ctx);
+        await doc.loadComponent('RedrawAbort');
+        ctx.respondWith(doc);
+    });
+    app.request.on('GET', '/test/models', async (ctx) => {
+        const doc = new Document(app, 'Test', ctx);
+        await doc.loadComponent('ModelsTest');
+        ctx.respondWith(doc);
+    });
+    app.request.on('GET', '/getargs', async (ctx) => {
+        ctx.respondWith(ctx.getArgs);
+    });
+    app.request.on('GET', '/form/multipart', async (ctx) => {
+        const doc = new Document(app, 'Test multipart form', ctx);
+        await doc.loadComponent('MultipartForm');
+        ctx.respondWith(doc);
+    });
+    app.request.on('POST', '/form/multipart', async (ctx) => {
+        console.log(ctx.files);
+        ctx.respondWith(ctx.body);
+    });
+    app.request.on('GET', '/conditional', async (ctx) => {
+        const doc = new Document(app, 'Test multipart form', ctx);
+        await doc.loadComponent('Conditionals');
+        ctx.respondWith(doc);
+    });
+    app.request.on('GET', '/urldecode', async (ctx) => {
+        const noVal = 'noVal';
+        const noValNested = 'filters[beds][min]';
+        const simple = 'simple=2';
+        const simpleObj = 'person[name]=fname&person[last_name]=lname';
+        const simpleArray = 'colors[]=red&colors[]=blue';
+        const orderedArray = 'colorsOrdered[1]=red&colorsOrdered[0]=blue';
+        const indexedArray = 'months[0]=Jan&months[1]=Feb&months[2]=Mar';
+        const arrayOfObjects = 'users[0][name]=John&users[0][email]=johndoe@gmail.com&users[1][name]=Tim&users[1][email]=tim@gmail.com';
+        const objectWithArrayValues = 'user[name]=John&user[last_name]=Doe&user[sports][]=table tennis&user[sports][]=football';
+        const objectWithObjectValues = 'data[paper][props][size]=10x13&data[paper][props][type]=matte';
+        const nestedArraySimple = 'colorStack[0][]=red&colorStack[0][]=blue&colorStack[1][]=green';
+        const arrayOfObjectsWithArrayValues = 'usersArr[0][name]=John&usersArr[0][email]=johndoe@gmail.com&usersArr[0][sports][]=football&usersArr[0][sports][]=basketball&usersArr[1][name]=Too&usersArr[1][email]=tootoo@gmail.com&usersArr[1][sports][]=bocce&usersArr[1][sports][]=cricket&usersArr[1][sports][]=dancing';
+        const missingValue = 'missing=';
+        const missingArrayValue = 'missingArr[]=';
+        const objBlankValue = `objBlank[0][email]=`;
+        const spaces = `spaces=value%20with%20spaces`;
+        const special = `garbage=` + encodeURIComponent('value!@#&$%^*()');
+        const nonLatin = `key3=` + encodeURIComponent('привет');
+        const t = new Date().getTime();
+        const test = Request.queryStringDecode([noVal, noValNested, simple, simpleObj, simpleArray, orderedArray, indexedArray, arrayOfObjects, objectWithArrayValues, objectWithObjectValues, nestedArraySimple, arrayOfObjectsWithArrayValues, missingValue, nonLatin, spaces, special, objBlankValue, missingArrayValue, simple].join('&'));
+        const dur = new Date().getTime() - t;
+        console.log(dur);
+        ctx.respondWith(test);
+    });
+    app.request.on('GET', '/client_import', async (ctx) => {
+        const doc = new Document(app, 'Test multipart form', ctx);
+        await doc.loadComponent('ClientImport');
+        doc.head.add(`
+        <script type="importmap">
+        {
+            imports: {
+                'components/*' : '/build/app/views/components/*'
+            }
+        }
+        </script>
+        `);
+        ctx.respondWith(doc);
+    });
+    app.request.on('GET', '/serverclass', async (ctx) => {
+        const doc = new Document(app, 'Test multipart form', ctx);
+        await doc.loadComponent('ServerSideContext');
+        ctx.respondWith(doc);
+    });
+    app.request.on('GET', '/routes/new', async (ctx) => {
+        const doc = new Document(app, 'Test multipart form', ctx);
+        await doc.loadComponent('Conditionals');
+        return doc;
+    });
+    app.request.on('GET', '/passObj', async (ctx) => {
+        const doc = new Document(app, 'Test pass obj', ctx);
+        await doc.loadComponent('PassObject');
+        ctx.respondWith(doc);
+    });
+}

package/build/app/routess/Todo.js

@@ -0,0 +1 @@
+"use strict";

package/build/app/routess/Upload.js

@@ -0,0 +1 @@
+"use strict";

package/build/app/routess/Validation.d.ts

@@ -0,0 +1,2 @@
+import { Application } from "../../system/server/Application.js";
+export default function (app: Application): void;

package/build/app/routess/Validation.js

@@ -0,0 +1,34 @@
+import { FormValidation } from '../../system/server/FormValidation.js';
+import { Document } from "../../system/server/Document.js";
+export default function (app) {
+    let validator = new FormValidation();
+    validator.singleError = true;
+    validator.addRule('name', 'Name', ['required', ['minLength', 3]]);
+    validator.addRule('email', 'Email', ['validEmail']);
+    validator.addRule('number', 'Number', ['number', 'required']);
+    validator.addRule('numeric', 'Numeric', ['numeric', 'required']);
+    validator.addRule('float', 'Float', ['float', 'required']);
+    app.request.on('POST', '/validation', async (ctx) => {
+        if (ctx.body) {
+            let validationResult = await validator.validate(ctx.body);
+            if (validationResult.valid) {
+                ctx.response.write('Valid');
+            }
+            else {
+                app.session.setValue(ctx.sessionId, 'validationErrors', validationResult.errors);
+                app.session.setValue(ctx.sessionId, 'formValues', ctx.body);
+                app.request.redirect(ctx.response, '/validation');
+            }
+        }
+    });
+    app.request.on('GET', '/validation', async (ctx) => {
+        let doc = new Document(app, 'Form validation');
+        await doc.loadView('pages/validation', app.session.extract(ctx.sessionId, [
+            { validationErrors: 'errors' },
+            { formValues: 'values' }
+        ]));
+        ctx.response.write(doc.toString());
+        app.session.removeValue(ctx.sessionId, 'validationErrors');
+        app.session.removeValue(ctx.sessionId, 'formValues');
+    });
+}

package/build/index.js

@@ -1,3 +1,3 @@
-import { Application } from "structured-fw/system/server/Application.js";
+import { Application } from "structured-fw/Application";
 import { config } from './Config.js';
 new Application(config);

package/build/system/server/Application.d.ts

@@ -19,7 +19,7 @@ export declare class Application {
     readonly exportedRequestContextData: Array<keyof RequestContextData>;
     constructor(config: StructuredConfig);
     init(): Promise<void>;
-    start(): Promise<void>;
+    private start;
     on(evt: ApplicationEvents, callback: RequestCallback | ((payload?: any) => void)): void;
     emit(eventName: ApplicationEvents, payload?: any): Promise<Array<any>>;
     importEnv<T extends LooseObject>(smartPrimitives?: boolean): T;

package/build/system/server/Components.js

@@ -9,6 +9,9 @@ export class Components {
     loadComponents(relativeToPath) {
         if (relativeToPath === undefined) {
             relativeToPath = path.resolve((this.config.runtime === 'Node.js' ? '../' : './') + this.config.components.path);
+            if (!existsSync(relativeToPath)) {
+                throw new Error(`Components path not found, expected to find:\n${relativeToPath}`);
+            }
         }
         const components = readdirSync(relativeToPath);
         components.forEach(async (component) => {

package/build/system/server/Request.js

@@ -293,6 +293,9 @@ export class Request {
         else {
             routesPath = path.resolve((this.app.config.runtime === 'Node.js' ? '../build/' : './') + this.app.config.routes.path);
         }
+        if (!existsSync(routesPath)) {
+            throw new Error(`Routes path not found, expected to find:\n${routesPath}`);
+        }
         const files = readdirSync(routesPath);
         for (let i = 0; i < files.length; i++) {
             const file = files[i];

package/index.ts

@@ -1,4 +1,4 @@
-import { Application } from "structured-fw/system/server/Application.js";
+import { Application } from "structured-fw/Application";
 import { config } from './Config.js';
 
 new Application(config);

package/package.json

@@ -8,7 +8,7 @@
   },
   "type": "module",
   "main": "build/index",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "scripts": {
     "develop": "tsc --watch",
     "startDev": "cd build && nodemon --watch '../app/**/*' --watch '../build/**/*' -e js,html,css index.js",
@@ -30,6 +30,12 @@
     "ts-md5": "^1.3.1"
   },
   "exports" : {
-    "./Application": "./build/system/server/Application.js"
+    "./Types": "./build/system/Types.js",
+    "./Symbols": "./build/system/Symbols.js",
+    "./Util": "./build/system/Util.js",
+    "./Application": "./build/system/server/Application.js",
+    "./Document": "./build/system/server/Document.js",
+    "./FormValidation": "./build/system/server/FormValidation.js",
+    "./ClientComponent": "./build/system/client/ClientComponent.js"
   }
 }

package/system/server/Application.ts

@@ -100,7 +100,7 @@ export class Application {
     }
 
     // start the http server
-    public start(): Promise<void> {
+    private start(): Promise<void> {
         return new Promise((resolve, reject) => {
             this.server = createServer((req, res) => {
                 this.request.handle(req, res);

package/system/server/Components.ts

@@ -18,6 +18,9 @@ export class Components {
     public loadComponents(relativeToPath?: string): void {
         if (relativeToPath === undefined) {
             relativeToPath = path.resolve((this.config.runtime === 'Node.js' ? '../' : './') + this.config.components.path);
+            if (! existsSync(relativeToPath)) {
+                throw new Error(`Components path not found, expected to find:\n${relativeToPath}`);
+            }
         }
         const components = readdirSync(relativeToPath);
         

package/system/server/Request.ts

@@ -420,6 +420,11 @@ export class Request {
         } else {
             routesPath = path.resolve((this.app.config.runtime === 'Node.js' ? '../build/' : './') + this.app.config.routes.path);
         }
+
+        if (! existsSync(routesPath)) {
+            throw new Error(`Routes path not found, expected to find:\n${routesPath}`);
+        }
+
         const files = readdirSync(routesPath);
 
         for (let i = 0; i < files.length; i++) {

package/tsconfig.json

@@ -5,7 +5,7 @@
         "strictPropertyInitialization": true,
         "strictBindCallApply": true,
         "noUnusedLocals": true,
-        "moduleResolution" : "Node",
+        "moduleResolution" : "bundler",
         "outDir": "./build",
         "module": "ES2020",
         "target": "ES2021",