structured-fw 0.8.0 → 0.8.3

package/Config.ts

@@ -34,8 +34,7 @@ export const config: StructuredConfig = {
         cookieName: 'session',
         keyLength: 24,
         durationSeconds: 60 * 60,
-        garbageCollectIntervalSeconds: 60,
-        garbageCollectAfterSeconds: 500
+        garbageCollectIntervalSeconds: 60
     },
     http: {
         port: 9191,

package/README.md

@@ -8,15 +8,20 @@ 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](#key-concepts)
+- [Good to know](#good-to-know)
+
 
 ### Key concepts:
 * [Application](#application)
 * [Route](#route)
 * [Document](#document)
-* [ClientComponent](#component) (component)
+* [Component](#component)
 
 ## Getting started
 
+_Following getting started instructions are relevant for Node.js runtime, if you are using Deno skip to [runtimes](#runtimes) section._
+
 ### Initialize a Node.js project
 ```
 cd /path/to/project
@@ -98,7 +103,7 @@ new Application(config);
 
 ### Properties
 - `cookies` - Instance of Cookies, allows you to set a cookie
-- `session` - Instance of Session, utilities to manage sessions and data
+- [`session`](#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
@@ -106,12 +111,12 @@ new Application(config);
 ### 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
+    - `serverStarted` - executed once the built-in http server is started and running. Callback receives Server (exported from node:http) instance as the first argument
     - `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
+    - `beforeComponentsLoad` - runs before components are loaded from `StructuredConfig.components.path`. Callback receives no arguments
+    - `afterComponentsLoaded` - runs after all components are loaded from `StructuredConfig.components.path`. Callback receives instance of Components as the first argument
     - `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
@@ -167,6 +172,39 @@ app.exportContextFields('user');
 
 ```
 
+### Session
+Session allows you to store temporary data for the users of your web application. You don't need to create an instance of Session, you will always use the instace `Application.session`.
+
+Session data is tied to a visitor via sessionId, which is always available on `RequestContext`, which means you can interact with session data from routes and server side code of your components.
+
+**Configuration**\
+`StructuredConfig`.`session`:
+```
+{
+    // cookie name for the session cookie
+    readonly cookieName: string,
+
+    // cookie stores the session key (a random string), keyLength determines it's length (longer key = more secure)
+    readonly keyLength: number,
+
+    // sessions expire after durationSeconds of no activity
+    readonly durationSeconds: number,
+
+    // session garbage collector runs every garbageCollectIntervalSeconds
+    // removing expired sessions from the memory
+    readonly garbageCollectIntervalSeconds: number
+}
+```
+
+**Methods**
+- `setValue(sessionId: string, key: string, value: any): void` - set a session value for given sessionId
+- `getValue<T>(sessionId: string, key: string): T | null` - return a value for given `key` from session, if `key` is not set, returns `null`. It is a generic method so you can specify the expected return type
+- `removeValue(sessionId: string, key: string): void` - remove value for given `key`
+- `getClear<T>(sessionId: string, key: string): T | null` - return and clear value for given `key`
+- `clear(sessionId: string): void` - clear all data for given `sessionId`
+- `extract(sessionId: string, keys: Array<string|{ [keyInSession: string] : string }>): LooseObject` - extract given keys from session and return them as an object. Key in `keys` can be a string in which case the key will remain the same in returned object or it can be an object { keyInSession : keyInReturnedData } in which case key in returned data will be keyInReturnedData
+
+
 ## 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.
 
@@ -199,7 +237,7 @@ Route file name has no effect on how the route (request handler) behaves, the on
 ### RequestContext
 All request handlers receive a `RequestContext` as the first argument.
 ```
-type RequestContext = {
+type RequestContext<Body extends LooseObject | undefined = LooseObject> = {
     request: IncomingMessage,
     response: ServerResponse,
     args: URIArguments,
@@ -208,7 +246,7 @@ type RequestContext = {
     cookies: Record<string, string>,
 
     // POSTed data, parsed to object
-    body?: PostedDataDecoded,
+    body?: LooseObject,
 
     bodyRaw?: Buffer,
 
@@ -276,6 +314,21 @@ 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.
 
+> [!TIP]
+> Since version 0.8.1 `Request`.`on` is a generic, accepting 0-2 generic arguments. First argument defines the request handler return type (response type) and defaults to any, second argument allows you to specify the expected (parsed) request body type, defaults to LooseObject.
+> ```
+> app.request.on<Document, {
+>   email: string,
+>   password: string,
+>   age: number
+>}>('POST', '/users/create', asyc (ctx) => {
+>    ctx.body.email // string
+>    ctx.body.age // number
+>    const doc = new Document(app, 'User', ctx);
+>    return doc; // error if we return anything but Document
+> });
+> ```
+
 ## 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.
 
@@ -337,7 +390,7 @@ You can now run the app and if you open /hello/world in the browser you will see
 `Hello, World!` - which came from your HelloWorld component.
 
 That was the simplest possible example, let's make it more interesting.
-Create a new file `/app/views/HelloWorld/HelloWorld.ts`:
+Create a new file `/app/views/HelloWorld/HelloWorld.ts` (server side component code):
 ```
 import { ComponentScaffold } from 'system/Types.js';
 export default class HelloWorld implements ComponentScaffold {
@@ -450,6 +503,15 @@ which is now avaialble in `AnotherComponent` HTML, we assigned the received numb
 
 What about client side? **By default, data returned by server side code is not available in client side code** for obvious reasons, let's assume your server side code returns sensitive data such as user's password, you would not like that exposed on the client side, hence exporting data needs to be explicitly requested in the server side code. There are two ways to achieve this, setting `exportData = true` (exports all data), or `exportFields: Array<string> = [...keysToExport]` (export only given fields).
 
+> [!NOTE]
+> Whenever a component with server-side code is rendered, `getData` is automatically called and anything it returns is available in HTML. You can export all returned data to client-side code by setting `exportData = true` or you can export some of the fields by setting `exportFields = ["field1", "field2", ...]` as a direct property of the class. To access the exported data from client-side use `ClientComponent`.`getData(key: string)` which will be `this.getData(key:string)` within client side code.
+
+> [!IMPORTANT]
+> Server side `getData` will receive the following arguments:
+> - `data: LooseObject` any data passed in (either by attributes, ClientComponent.add or ClientComponent.redraw)
+> - `ctx: RequestContext` - current `RequestContext`, you will often use this to access for example ctx.data (`RequestContextData`) or ctx.sessionId to interact with session
+> - `app: Application` - your Application instance. You can use it to, for example, access the session in combination with ctx.sessionId
+
 Let's create a client side code for `AnotherComponent` and export the `betterNumber` to it, create `/app/views/AnotherComponent/AnotherComponent.client.ts`:
 ```
 import { InitializerFunction } from 'system/Types.js';
@@ -548,6 +610,117 @@ Methods:
 - `arrayRef<T>(refName: string): Array<T>` - get an array of HTMLElement or ClientComponent that have attribute `array:ref="[refName]"`
 - `add(appendTo: HTMLElement, componentName: string, data?: LooseObject)` - add `componentName` component to `appendTo` element, optionally passing `data` to the component when it's being rendered
 
+## Good to know
+- [Uing CSS frameworks](#css-frameworks)
+- [Using JS runtimes other than Node.js](#runtimes)
+- [Why not JSR](#jsr)
+
+### CSS frameworks
+We rarely write all CSS from scratch, usually we use a CSS framework to speed us up. Structured allows you to work with any CSS frameworks such as Tailwind, PostCSS or Bootstrap.
+
+Your Tailwind configuration may look something like:
+```
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: ["./app/views/**/*.html", "./app/views/**/*.hbs"],
+  ...
+}
+```
+
+Above we just defined where all our HTML resides, which is within /app/views. That is all there is to it. From there, you can generate the CSS, for example:\
+`npx tailwindcss -i ./assets/css/src/style.css -o ./assets/css/dist.css`
+
+**Including the output CSS**\
+To include the output CSS in all pages, you can add the following to `index.ts`:
+```
+const app = new Application(config);
+
+app.on('documentCreated', (doc) => {
+    doc.head.addCSS('/assets/css/dist.css');
+});
+```
+
+### Runtimes
+Structured is tested with Node.js and Deno. Other runtimes would likely work as well.
+
+To use Structured with Deno, you can:
+```
+cd /path/to/project
+deno init
+deno add npm:structured-fw
+```
+
+With Deno, we can't use the cli to create the boilerplate, so you will need to create it yourself.
+```
+mkdir app
+mkdir app/views
+mkdir app/routes
+```
+
+Create `Config.ts`:
+```
+import { StructuredConfig } from "structured-fw/Types";
+
+export const config: StructuredConfig = {
+    // Application.importEnv will load all env variables starting with [envPrefix]_
+    envPrefix: 'STRUCTURED',
+
+    // whether to call Application.init when an instance of Application is created
+    autoInit: true,
+
+    url: {
+        removeTrailingSlash: true,
+
+        // if you want to enable individual component rendering set this to URI (string)
+        // to disable component rendering set it to false
+        // setting this to false disallows the use of ClientComponent.redraw and ClientComponent.add
+        componentRender: '/componentRender',
+
+        // function that receives the requested URL and returns boolean, if true, treat as static asset
+        // if there is a registered request handler that matches this same URL, it takes precedence over this
+        isAsset: function(uri: string) {
+            return uri.indexOf('/assets/') === 0;
+        }
+    },
+    routes: {
+        path: '/app/routes'
+    },
+    components : {
+        // relative to index.ts
+        path: '/app/views',
+
+        componentNameAttribute: 'structured-component'
+    },
+    session: {
+        cookieName: 'session',
+        keyLength: 24,
+        durationSeconds: 60 * 60,
+        garbageCollectIntervalSeconds: 60
+    },
+    http: {
+        port: 9191,
+        host: '0.0.0.0',
+        // used by Document.push, can be preload or preconnect
+        linkHeaderRel : 'preload'
+    },
+    runtime: 'Deno'
+}
+```
+
+Import `Config.ts` in `main.ts` and create the Application instance:
+```
+import { Application } from 'structured-fw/Application';
+import { config } from './Config.ts';
+
+new Application(config);
+```
+
+Run application using `deno main.ts`
+
+### JSR
+It would make a lot of sense to have Structured hosted on JSR (JavaScript Registry) given Structured is a TypeScript framework, and JSR is a TypeScript-first registry, however, the issue is that Deno imposes [limitations with dynamic imports](https://docs.deno.com/deploy/api/dynamic-import/) with JSR-imported dependencies, which are required for the framework (to dynamically import your routes and components).\
+This does not stop the framework from working with Deno, but for the time being, we have to stick with good old npm.
+
 ## Why Structured
 Framework was developed by someone who has been a web developer for almost 20 years (me), and did not like the path web development has taken.
 \

package/build/Config.js

@@ -19,8 +19,7 @@ export const config = {
         cookieName: 'session',
         keyLength: 24,
         durationSeconds: 60 * 60,
-        garbageCollectIntervalSeconds: 60,
-        garbageCollectAfterSeconds: 500
+        garbageCollectIntervalSeconds: 60
     },
     http: {
         port: 9191,

package/build/app/routes/Test.js

@@ -4,7 +4,7 @@ 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);
+        return doc;
     });
     app.request.on('POST', '/test/form', async (ctx) => {
         console.log(JSON.stringify(ctx.body, undefined, 4));

package/build/system/Types.d.ts

@@ -24,7 +24,6 @@ export type StructuredConfig = {
         readonly keyLength: number;
         readonly durationSeconds: number;
         readonly garbageCollectIntervalSeconds: number;
-        readonly garbageCollectAfterSeconds: number;
     };
     http: {
         host?: string;
@@ -38,21 +37,21 @@ export type StructuredClientConfig = {
     componentNameAttribute: string;
 };
 export type RequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-export type RequestCallback = (ctx: RequestContext) => Promise<any>;
+export type RequestCallback<R extends any, Body extends LooseObject | undefined> = (ctx: RequestContext<Body>) => Promise<R>;
 export type RequestHandler = {
     match: Array<URISegmentPattern> | RegExp;
     methods: Array<RequestMethod>;
-    callback: RequestCallback;
+    callback: RequestCallback<any, LooseObject | undefined>;
     scope: any;
     staticAsset: boolean;
 };
-export type RequestContext = {
+export type RequestContext<Body extends LooseObject | undefined = LooseObject> = {
     request: IncomingMessage;
     response: ServerResponse;
     args: URIArguments;
     handler: null | RequestHandler;
     cookies: Record<string, string>;
-    body?: PostedDataDecoded;
+    body: Body;
     bodyRaw?: Buffer;
     files?: Record<string, RequestBodyRecordValue>;
     data: RequestContextData;
@@ -128,7 +127,7 @@ export interface ComponentScaffold {
     [key: string]: any;
 }
 export type LooseObject = Record<string, any>;
-export type ApplicationEvents = 'serverStarted' | 'beforeRequestHandler' | 'afterRequestHandler' | 'beforeRoutes' | 'afterRoutes' | 'beforeComponentLoad' | 'afterComponentLoad' | 'documentCreated' | 'beforeAssetAccess' | 'afterAssetAccess' | 'pageNotFound';
+export type ApplicationEvents = 'serverStarted' | 'beforeRequestHandler' | 'afterRequestHandler' | 'beforeRoutes' | 'afterRoutes' | 'beforeComponentsLoad' | 'afterComponentsLoaded' | 'componentCreated' | 'documentCreated' | 'beforeAssetAccess' | 'afterAssetAccess' | 'pageNotFound';
 export type SessionEntry = {
     sessionId: string;
     lastRequest: number;

package/build/system/client/ClientComponent.d.ts

@@ -1,14 +1,8 @@
-import { InitializerFunction, LooseObject, StructuredClientConfig } from '../Types.js';
+import { LooseObject } from '../Types.js';
 import { DataStoreView } from './DataStoreView.js';
 import { DataStore } from './DataStore.js';
 import { Net } from './Net.js';
 import { EventEmitter } from './EventEmitter.js';
-declare global {
-    interface Window {
-        initializers: Record<string, InitializerFunction | string>;
-        structuredClientConfig: StructuredClientConfig;
-    }
-}
 export declare class ClientComponent extends EventEmitter {
     readonly name: string;
     children: Array<ClientComponent>;

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

@@ -20,7 +20,7 @@ export declare class Application {
     constructor(config: StructuredConfig);
     init(): Promise<void>;
     private start;
-    on<E extends ApplicationEvents>(evt: E, callback: (payload: E extends 'beforeRequestHandler' | 'afterRequestHandler' | 'beforeAssetAccess' | 'afterAssetAccess' | 'pageNotFound' ? RequestContext : E extends 'documentCreated' ? Document : undefined) => void): void;
+    on<E extends ApplicationEvents>(evt: E, callback: (payload: E extends 'beforeRequestHandler' | 'afterRequestHandler' | 'beforeAssetAccess' | 'afterAssetAccess' | 'pageNotFound' ? RequestContext : E extends 'documentCreated' ? Document : E extends 'afterComponentsLoaded' ? Components : E extends 'serverStarted' ? Server : undefined) => void): void;
     emit(eventName: ApplicationEvents, payload?: any): Promise<Array<any>>;
     importEnv<T extends LooseObject>(smartPrimitives?: boolean): T;
     exportContextFields(...fields: Array<keyof RequestContextData>): void;

package/build/system/server/Application.js

@@ -35,12 +35,12 @@ export class Application {
         catch (e) {
             console.error(e.message);
         }
-        await this.emit('beforeComponentLoad');
+        await this.emit('beforeComponentsLoad');
         this.components.loadComponents();
-        await this.emit('afterComponentLoad');
+        await this.emit('afterComponentsLoaded', this.components);
         await this.emit('beforeRoutes');
         await this.request.loadHandlers();
-        await this.emit('afterRoutes');
+        await this.emit('afterRoutes', this.request);
         if (this.config.url.componentRender !== false) {
             this.request.on('POST', `${this.config.url.componentRender}`, async (ctx) => {
                 const input = ctx.body;
@@ -49,16 +49,18 @@ export class Application {
         }
         this.request.on('GET', /^\/assets\/client-js/, async ({ request, response }) => {
             const uri = request.url?.substring(18);
-            const filePath = path.resolve('./system/', uri);
+            if (uri.includes('..')) {
+                return '';
+            }
+            const filePath = path.resolve(import.meta.dirname, '..', uri);
             if (existsSync(filePath)) {
                 response.setHeader('Content-Type', 'application/javascript');
-                response.write(readFileSync(filePath));
-                response.end();
+                return readFileSync(filePath);
             }
             else {
                 response.statusCode = 404;
             }
-            return;
+            return '';
         }, this, true);
         await this.start();
     }
@@ -69,7 +71,7 @@ export class Application {
             });
             this.server.listen(this.config.http.port, this.config.http.host || '127.0.0.1', async () => {
                 const address = (this.config.http.host !== undefined ? this.config.http.host : '') + ':' + this.config.http.port;
-                await this.emit('serverStarted');
+                await this.emit('serverStarted', this.server);
                 console.log(`Server started on ${address}`);
                 resolve();
             });

package/build/system/server/Component.js

@@ -8,6 +8,7 @@ export class Component {
         this.attributesRaw = {};
         this.attributes = {};
         this.data = {};
+        const isDocument = this instanceof Document;
         this.name = name;
         if (name === 'root') {
             this.dom = new DOMFragment();
@@ -21,7 +22,7 @@ export class Component {
             }
             this.isRoot = false;
         }
-        if (this instanceof Document) {
+        if (isDocument) {
             this.document = this;
         }
         else {
@@ -42,6 +43,9 @@ export class Component {
         else {
             this.entry = null;
         }
+        if (!isDocument) {
+            this.document.application.emit('componentCreated', this);
+        }
     }
     async init(html, data) {
         this.initAttributesData();

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

@@ -1,12 +1,12 @@
 import { IncomingMessage, ServerResponse } from "node:http";
-import { PostedDataDecoded, RequestBodyFile, RequestCallback, RequestMethod } from "../Types.js";
+import { LooseObject, PostedDataDecoded, RequestBodyFile, RequestCallback, RequestMethod } from "../Types.js";
 import { Application } from "./Application.js";
 export declare class Request {
     private app;
     constructor(app: Application);
-    pageNotFoundCallback: RequestCallback;
+    pageNotFoundCallback: RequestCallback<void, PostedDataDecoded | undefined>;
     private readonly handlers;
-    on(methods: RequestMethod | Array<RequestMethod>, pattern: string | RegExp | Array<string | RegExp>, callback: RequestCallback, scope?: any, isStaticAsset?: boolean): void;
+    on<R extends any, Body extends LooseObject | undefined = LooseObject>(methods: RequestMethod | Array<RequestMethod>, pattern: string | RegExp | Array<string | RegExp>, callback: RequestCallback<R, Body>, scope?: any, isStaticAsset?: boolean): void;
     private getHandler;
     handle(request: IncomingMessage, response: ServerResponse): Promise<void>;
     private extractURIArguments;

package/build/system/server/Request.js

@@ -102,6 +102,7 @@ export class Request {
             handler,
             args: {},
             data: {},
+            body: undefined,
             getArgs,
             cookies: this.app.cookies.parse(request),
             isAjax: request.headers['x-requested-with'] == 'xmlhttprequest',

package/build/system/server/Session.js

@@ -43,7 +43,7 @@ export class Session {
     }
     garbageCollect() {
         const time = new Date().getTime();
-        const sessDurationMilliseconds = this.application.config.session.garbageCollectAfterSeconds * 1000;
+        const sessDurationMilliseconds = this.application.config.session.durationSeconds * 1000;
         for (const sessionId in this.sessions) {
             const sess = this.sessions[sessionId];
             if (time - sess.lastRequest > sessDurationMilliseconds) {

package/index.ts

@@ -1,4 +1,15 @@
 import { Application } from "structured-fw/Application";
 import { config } from './Config.js';
 
-new Application(config);
+new Application(config);
+
+// app.on('afterComponentsLoaded', (components) => {
+//     components.componentNames.forEach((componentName) => {
+//         console.log(componentName)
+//         console.log(components.getByName(componentName));
+//     });
+// })
+
+// app.on('componentCreated', (component) => {
+//     console.log(component.document.id);
+// })

package/jsr.json

@@ -0,0 +1,35 @@
+{
+    "name": "@structured/structured-fw",
+    "version": "0.8.21",
+    "license": "MIT",
+    "exports" : {
+        "./Types": "./system/Types.ts",
+        "./Symbols": "./system/Symbols.ts",
+        "./Util": "./system/Util.ts",
+        "./Application": "./system/server/Application.ts",
+        "./Document": "./system/server/Document.ts",
+        "./FormValidation": "./system/server/FormValidation.ts",
+        "./ClientComponent": "./system/client/ClientComponent.ts"
+    },
+    "dependencies": {
+        "handlebars": "^4.7.8",
+        "mime-types": "^3.0.0",
+        "ts-md5": "^1.3.1",
+        "@types/node": "^22.9.3",
+        "@types/mime-types": "^2.1.4"
+    },
+    "exclude": [
+        "build",
+        "assets",
+        "node_modules",
+        "tsconfig.json",
+        "package.json",
+        "package.lock.json",
+        "tailwind.config.cjs",
+        ".vscode",
+        "app/Types.ts",
+        "app/views/*",
+        "app/routes/*",
+        "app/models/*"
+    ]
+}

package/package.json

@@ -14,13 +14,12 @@
   "license": "MIT",
   "type": "module",
   "main": "build/index",
-  "version": "0.8.0",
+  "version": "0.8.3",
   "scripts": {
     "develop": "tsc --watch",
     "startDev": "cd build && nodemon --watch '../app/**/*' --watch '../build/**/*' -e js,html,css index.js",
     "start": "cd build && node index.js",
-    "prepublish": "tsc",
-    "postinstall": "echo \"Run npx structured init\" to create application boilerplate"
+    "prepublish": "tsc"
   },
   "bin": {
     "structured": "./build/system/bin/structured.js"

package/system/Types.ts

@@ -24,8 +24,7 @@ export type StructuredConfig = {
         readonly cookieName: string,
         readonly keyLength: number,
         readonly durationSeconds: number,
-        readonly garbageCollectIntervalSeconds: number,
-        readonly garbageCollectAfterSeconds: number
+        readonly garbageCollectIntervalSeconds: number
     },
     http: {
         host?: string,
@@ -42,19 +41,19 @@ export type StructuredClientConfig = {
 
 export type RequestMethod = 'GET'|'POST'|'PUT'|'PATCH'|'DELETE';
 
-export type RequestCallback = (ctx: RequestContext) => Promise<any>
+export type RequestCallback<R extends any, Body extends LooseObject | undefined> = (ctx: RequestContext<Body>) => Promise<R>
 
 export type RequestHandler = {
     match: Array<URISegmentPattern>|RegExp,
     methods: Array<RequestMethod>,
-    callback: RequestCallback,
+    callback: RequestCallback<any, LooseObject | undefined>,
     scope: any,
         
     // if true, no (before/after)RequestHandler event is emitted, body and GET args not parsed
     staticAsset: boolean
 }
 
-export type RequestContext = {
+export type RequestContext<Body extends LooseObject | undefined = LooseObject> = {
     request: IncomingMessage,
     response: ServerResponse,
     args: URIArguments,
@@ -63,7 +62,7 @@ export type RequestContext = {
     cookies: Record<string, string>,
 
     // POSTed data, parsed to object
-    body?: PostedDataDecoded,
+    body: Body,
 
     bodyRaw?: Buffer,
 
@@ -178,7 +177,7 @@ export interface ComponentScaffold  {
 
 export type LooseObject = Record<string, any>
 
-export type ApplicationEvents = 'serverStarted'|'beforeRequestHandler'|'afterRequestHandler'|'beforeRoutes'|'afterRoutes'|'beforeComponentLoad'|'afterComponentLoad'|'documentCreated'|'beforeAssetAccess'|'afterAssetAccess'|'pageNotFound';
+export type ApplicationEvents = 'serverStarted'|'beforeRequestHandler'|'afterRequestHandler'|'beforeRoutes'|'afterRoutes'|'beforeComponentsLoad'|'afterComponentsLoaded'|'componentCreated'|'documentCreated'|'beforeAssetAccess'|'afterAssetAccess'|'pageNotFound';
 
 export type SessionEntry = {
     sessionId : string,

package/system/client/ClientComponent.ts

@@ -1,4 +1,4 @@
-import { ClientComponentTransition, ClientComponentTransitions, InitializerFunction, LooseObject, StoreChangeCallback, StructuredClientConfig } from '../Types.js';
+import { ClientComponentTransition, ClientComponentTransitions, InitializerFunction, LooseObject, StoreChangeCallback } from '../Types.js';
 import { attributeValueFromString, attributeValueToString, mergeDeep, objectEach, queryStringDecodedSetValue, toCamelCase } from '../Util.js';
 import { DataStoreView } from './DataStoreView.js';
 import { DataStore } from './DataStore.js';
@@ -6,16 +6,6 @@ import { Net } from './Net.js';
 import { NetRequest } from './NetRequest.js';
 import { EventEmitter } from './EventEmitter.js';
 
-// window.initializers will always be present
-// each Document has a list of initializers used in components within it
-// and they will be output as initializers = { componentName : initializer }
-declare global {
-    interface Window {
-        initializers: Record<string, InitializerFunction | string>;
-        structuredClientConfig: StructuredClientConfig;
-    }
-}
-
 export class ClientComponent extends EventEmitter {
     readonly name: string;
     children: Array<ClientComponent> = [];

package/system/global.d.ts

@@ -0,0 +1,12 @@
+import { InitializerFunction, StructuredClientConfig } from "./Types.js";
+
+export {}
+// window.initializers will always be present
+// each Document has a list of initializers used in components within it
+// and they will be output as initializers = { componentName : initializer }
+declare global {
+    interface Window {
+        initializers: Record<string, InitializerFunction | string>;
+        structuredClientConfig: StructuredClientConfig;
+    }
+}

package/system/server/Application.ts

@@ -59,14 +59,14 @@ export class Application {
             console.error(e.message);
         }
 
-        await this.emit('beforeComponentLoad');
+        await this.emit('beforeComponentsLoad');
         this.components.loadComponents();
-        await this.emit('afterComponentLoad');
+        await this.emit('afterComponentsLoaded', this.components);
 
 
         await this.emit('beforeRoutes');
         await this.request.loadHandlers();
-        await this.emit('afterRoutes');
+        await this.emit('afterRoutes', this.request);
 
         if (this.config.url.componentRender !== false) {
             // special request handler, executed when ClientComponent.redraw is called
@@ -84,15 +84,15 @@ export class Application {
         // special request handler, serve the client side JS
         this.request.on('GET', /^\/assets\/client-js/, async ({ request, response }) => {
             const uri = request.url?.substring(18) as string;
-            const filePath = path.resolve('./system/', uri);
+            if (uri.includes('..')) {return '';} // disallow having ".." in the URL
+            const filePath = path.resolve(import.meta.dirname, '..', uri);
             if (existsSync(filePath)) {
                 response.setHeader('Content-Type', 'application/javascript');
-                response.write(readFileSync(filePath));
-                response.end();
+                return readFileSync(filePath);
             } else {
                 response.statusCode = 404;
             }
-            return;
+            return '';
         }, this, true);
 
         await this.start();
@@ -106,7 +106,7 @@ export class Application {
             });
             this.server.listen(this.config.http.port, this.config.http.host || '127.0.0.1', async () => {
                 const address = (this.config.http.host !== undefined ? this.config.http.host : '') + ':' + this.config.http.port;
-                await this.emit('serverStarted');
+                await this.emit('serverStarted', this.server);
                 console.log(`Server started on ${address}`);
                 resolve();
             });
@@ -120,6 +120,8 @@ export class Application {
             payload:
                 E extends 'beforeRequestHandler' | 'afterRequestHandler' | 'beforeAssetAccess' | 'afterAssetAccess' | 'pageNotFound' ? RequestContext :
                 E extends 'documentCreated' ? Document :
+                E extends 'afterComponentsLoaded' ? Components :
+                E extends 'serverStarted' ? Server :
                 undefined
         ) => void
     ): void {

package/system/server/Component.ts

@@ -29,6 +29,7 @@ export class Component {
     isRoot: boolean;
 
     constructor(name: string, node?: DOMNode, parent?: Document|Component, autoInit: boolean = true) {
+        const isDocument = this instanceof Document;
         this.name = name;
 
         if (name === 'root') {
@@ -43,7 +44,7 @@ export class Component {
             this.isRoot = false;
         }
 
-        if (this instanceof Document) {
+        if (isDocument) {
             // this will only happen if an instance of Document, as it extends component
             this.document = this;
         } else {
@@ -71,6 +72,10 @@ export class Component {
         } else {
             this.entry = null;
         }
+
+        if (! isDocument) {
+            this.document.application.emit('componentCreated', this);
+        }
     }
     
     // load component's data and fill it

package/system/server/Request.ts

@@ -1,5 +1,5 @@
 import { IncomingMessage, ServerResponse } from "node:http";
-import { PostedDataDecoded, RequestBodyFile, RequestCallback, RequestContext, RequestHandler, RequestMethod, URIArguments, URISegmentPattern } from "../Types.js";
+import { LooseObject, PostedDataDecoded, RequestBodyFile, RequestCallback, RequestContext, RequestHandler, RequestMethod, URIArguments, URISegmentPattern } from "../Types.js";
 import { mergeDeep, queryStringDecode, queryStringDecodedSetValue } from "../Util.js";
 import { Application } from "./Application.js";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
@@ -15,7 +15,7 @@ export class Request {
         this.app = app;
     }
 
-    pageNotFoundCallback: RequestCallback =  async ({ response }) => {
+    pageNotFoundCallback: RequestCallback<void, PostedDataDecoded | undefined> =  async ({ response }) => {
         response.statusCode = 404;
         response.write('Page not found');
         response.end();
@@ -30,10 +30,10 @@ export class Request {
     // callback.this will be the scope if scope is provided, otherwise scope is the Application instance
     // if pattern is given as array, one request handler will be created for each element of the array
     // if isStaticAsset = true, (before/after)RequestHandler event not emitted, body and GET args not parsed
-    public on(
+    public on<R extends any, Body extends LooseObject | undefined = LooseObject>(
         methods: RequestMethod|Array<RequestMethod>,
         pattern: string|RegExp|Array<string|RegExp>,
-        callback: RequestCallback,
+        callback: RequestCallback<R, Body>,
         scope?: any,
         isStaticAsset: boolean = false
     ): void {
@@ -163,7 +163,7 @@ export class Request {
         // get the best matching request handler
         const handler = this.getHandler(uri, requestMethod);
         
-        const context: RequestContext = {
+        const context: RequestContext<LooseObject | undefined> = {
             request,
             response,
             handler,
@@ -173,6 +173,7 @@ export class Request {
             // potentially falsely declared as RequestContextData
             // user will fill this out, usually on beforeRequestHandler
             data: {} as RequestContextData,
+            body: undefined,
             getArgs,
             cookies: this.app.cookies.parse(request),
             isAjax : request.headers['x-requested-with'] == 'xmlhttprequest',
@@ -347,7 +348,7 @@ export class Request {
     // parse raw request body
     // if there is a parser for received Content-Type
     // then ctx.body is populated with data: URIArgs
-    private async parseBody(ctx: Omit<RequestContext, 'data'>): Promise<void> {
+    private async parseBody(ctx: RequestContext<LooseObject | undefined>): Promise<void> {
         if (ctx.request.headers['content-type']) {
 
             ctx.bodyRaw = await this.dataRaw(ctx.request);

package/system/server/Session.ts

@@ -73,7 +73,7 @@ export class Session {
     // remove expired session entries
     private garbageCollect(): void {
         const time = new Date().getTime();
-        const sessDurationMilliseconds = this.application.config.session.garbageCollectAfterSeconds * 1000;
+        const sessDurationMilliseconds = this.application.config.session.durationSeconds * 1000;
 
         for (const sessionId in this.sessions) {
             const sess = this.sessions[sessionId];