structured-fw 0.8.21 → 0.8.42

package/README.md

@@ -5,6 +5,9 @@ Framework allows the developer to develop self-contained components which are re
 
 It works with Node.js and Deno runtimes. Other runtimes are not tested.
 
+> [!NOTE]
+> While Structured framework is in development for a couple of years and is production tested, the npm package is introduced recently and there were still issues that came up with it in the past few versions. Since version 0.8.3 all should be functional. Please update to latest version and check for updates regularly until the npm package is as stable as the framework itself. Feel free to open issues on the github page if you have any issues with the npm package or the framework. _Structured followed versioning x.y.z where z was a single digit 0-9, but since there were a couple of versions that introduced no changes to the framework and were just npm package tweaks, I decided to make an exception to the rule and allow myself to use 2 digits for such updates._
+
 - [Why Structured](#why-structured)
 - [Audience](#audience)
 - [Getting started](#getting-started)
@@ -110,13 +113,13 @@ 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
+- `on(evt: ApplicationEvents, callback: RequestCallback|((payload?: any) => void))` - allows you to add event listeners for specific `ApplicationEvents`:
+    - `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
@@ -173,7 +176,7 @@ 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 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 instance `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.
 
@@ -321,16 +324,16 @@ In some edge cases you may need more control of when a route is executed, in whi
 >   email: string,
 >   password: string,
 >   age: number
->}>('POST', '/users/create', asyc (ctx) => {
+>}>('POST', '/users/create', async (ctx) => {
 >    ctx.body.email // string
 >    ctx.body.age // number
->    const doc = new Document(ctx, 'User', app);
+>    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.
+Document does not differ much from a component, in fact, it extends Component. It has a more user-friendly 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.
 
 Creating a document:
 `const doc = new Document(app, 'HelloWorld page', ctx);`
@@ -344,13 +347,25 @@ app.request.on('GET', '/home', async (ctx) => {
 });
 ```
 
+> [!TIP]
+> Since version 0.8.4 Document extends EventEmitter, and "componentCreated" event is emitted whenever a component instance is created within the Document.\
+> This makes the following possible:
+> ```
+> app.on('documentCreated', (doc) => {
+>   doc.on('componentCreated', (component) => {
+>       // do something with the document or the component
+>   })    
+> })
+> ```
+
 ## Component
-A component is comprised of 1-3 files. It always must include one HTML file, while server side and client side files are optional.
-* HTML file preobably requires no explanation
+A component is comprised of [1-3 files](#component-parts). It always must include one HTML file, while server side and client side files are optional.
+* HTML file probably requires no explanation
 * server side file, code that runs on the server and makes data available to HTML and client side code
 * client side file, code that runs on the client (in the browser)
 
-You should never need to instantiate a Component on your own. You will always load a Component representing your page into a document (using `Document.loadComponent(componentName: string)`), which will know what to do from there.
+> [!TIP]
+> You should never need to instantiate a Component on your own. You will always load a Component representing your page into a document (using `Document.loadComponent(componentName: string)`), which will know what to do from there.
 
 Example component files:
 - `/app/views/`
@@ -367,9 +382,15 @@ It is recommended, but not necessary, that you contain each component in it's ow
 \
 **Component rules:**
 - **Component names must be unique**
-- Components HTML file can have a `.hbs` extension (which allows for better Handlebars sytax highlighting)
+- Components HTML file can have a `.hbs` extension (which allows for better Handlebars syntax highlighting)
 - Components can reside at any depth in the file structure
 
+### Component parts
+- [Component HTML](#component-html) (_ComponentName.html_)
+- [Component server-side code](#component-server-side-code) (_ComponentName.ts_)
+- [Component client-side code](#component-client-side-code) (_ComponentName.client.ts_)
+
+### Component HTML
 Let's create a HelloWorld Component `/app/views/HelloWorld/HelloWorld.html`:\
 `Hello, World!`
 
@@ -389,7 +410,12 @@ export default function(app: Application) {
 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.
+> [!TIP]
+> It is recommended to use .hbs (Handlebars) extension as you will get better syntax highlighting in most IDEs. Other than syntax highlighting there is no difference between using html or hbs extension.
+
+That was the simplest possible example, let's make it more interesting by adding some server-side code.
+
+### Component server-side code
 Create a new file `/app/views/HelloWorld/HelloWorld.ts` (server side component code):
 ```
 import { ComponentScaffold } from 'system/Types.js';
@@ -423,7 +449,15 @@ Your lucky number is [a number from 0-100]
 This demonstrates the use of a *server side component code* to make data available to HTML.
 We just generated a random number, but the data could be anything and will more often come from a database, session, or be provided by the parent component.
 
+> [!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 make it even more interesting by adding some client side code to it.
+
+### Component client-side code
 Create `/app/views/HelloWorld/HelloWorld.client.ts`:
 ```
 import { InitializerFunction } from 'system/Types.js';
@@ -499,19 +533,13 @@ What we did is, we accepted the number provided by parent component, and returne
     betterNumber: number
 }
 ```
-which is now avaialble in `AnotherComponent` HTML, we assigned the received number to `parentSuggests`, while `betterNumber` is `parentSuggests + 5`, we now have these 2 available and ready to use in our HTML template.
+which is now available in `AnotherComponent` HTML, we assigned the received number to `parentSuggests`, while `betterNumber` is `parentSuggests + 5`, we now have these 2 available and ready to use in our HTML template.
 
 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';
@@ -555,7 +583,7 @@ export const init: InitializerFunction = async function() {
 ```
 Here we accessed the `parent` and obtained it's `name`.
 
-*"But we did not send any data to the parent here"* - correct, we did not, and we won't, instead we can inform them we have some data available, or that an event they might be interested in has ocurred, and if they care, so be it:
+*"But we did not send any data to the parent here"* - correct, we did not, and we won't, instead we can inform them we have some data available, or that an event they might be interested in has occurred, and if they care, so be it:
 ```
 import { InitializerFunction } from 'system/Types.js';
 export const init: InitializerFunction = async function() {
@@ -585,7 +613,7 @@ export const init: InitializerFunction = async function() {
 }
 ```
 
-That's it. If there is `AnotherComponent` found within `HelloWorld` (which there is in our case) we are subscribing to "truth" event and capturing the payload. Payload is optional, sometimes we just want to inform anyone interested that a certain event has ocurred, without the need to pass any extra data with it. We used `this.find(componentName: string)`, this will recursively find the first instance of a component with `componentName`, optionally you can make it non-recursive by passing `false` as the second argument to `find` method in which case it will look for a direct child with given name.
+That's it. If there is `AnotherComponent` found within `HelloWorld` (which there is in our case) we are subscribing to "truth" event and capturing the payload. Payload is optional, sometimes we just want to inform anyone interested that a certain event has occurred, without the need to pass any extra data with it. We used `this.find(componentName: string)`, this will recursively find the first instance of a component with `componentName`, optionally you can make it non-recursive by passing `false` as the second argument to `find` method in which case it will look for a direct child with given name.
 
 We have only scratched the surface of what client-side code of a component is capable of. Which brings us to `this`. In client-side code of a component, `this` is the instance of a `ClientComponent`.
 
@@ -605,15 +633,70 @@ Methods:
 - `store.set(key: string, value: any)` - set data in client side data store
 - `find(componentName: string, recursive: boolean = true): ClientComponent | null` - find a child component
 - `findParent(componentName: string): ClientComponent | null` - find the first parent with given name
-- `query(componentName: string, recursive: boolean = true): Array<ClientComponent>` - return all components with given name found within this component, if `recurive = false`, only direct children are considered
+- `query(componentName: string, recursive: boolean = true): Array<ClientComponent>` - return all components with given name found within this component, if `recursive = false`, only direct children are considered
 - `ref<T>(refName: string): T` - get a HTMLElement or ClientComponent that has attribute `ref="[refName]"`
 - `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
+- `add(appendTo: HTMLElement, componentName: string, data?: LooseObject): Promise<ClientComponent | null>` - add `componentName` component to `appendTo` element, optionally passing `data` to the component when it's being rendered. Returns a promise that resolves with added ClientComponent or null if something went wrong
+- `redraw(data?: LooseObject): Promise<void>` - redraw the component, optionally provide data which will be available server side
+
+### Conditionals
+You can make any DOM node within your components conditionally shown/hidden using `data-if` attribute.\
+For example:
+```
+<div data-if="showDiv"></div>
+```
+Above div will only be shown if store.showDiv = true
+
+You can also use `!` to invert the value, `!showDiv` in which case div would be shown if showDiv is false.
+
+You can also use comparison:
+```
+<div data-if="val === 1"></div>
+<div data-if="val == 1"></div>
+<div data-if="val !== 1"></div>
+<div data-if="val != 1"></div>
+<div data-if="val > 1"></div>
+<div data-if="val < 1"></div>
+<div data-if="val <= 1"></div>
+<div data-if="val >= 1"></div>
+```
+
+The right hand side of the comparison does not have to be boolean or number. It can be a string or any primitive value, but the numeric comparisons don't make sense in such case.
+
+You can also define callbacks and use them as the condition, in you ComponentName.client.ts:
+```
+import { InitializerFunction } from 'structured-fw/Types';
+export const init: InitializerFunction = async function() {
+    this.conditionalCallback('showDiv', () => {
+        // return a boolean here
+    });
+}
+```
+
+then in ComponentName.html:
+```
+<div data-if="showDiv()"></div>
+```
+
+**Basic animation/transitions**\
+If you use conditionals on any DOM node, you may also enable basic animations/transitions using following attributes:
+- Enable transition:
+    - `data-transition-show-slide="durationMilliseconds"` - when DOM node is shown, slide it in
+    - `data-transition-hide-slide="durationMilliseconds"` - when DOM node is hidden, slide it out
+    - `data-transition-show-fade="durationMilliseconds"` - fade DOM node in
+    - `data-transition-hide-fade="durationMilliseconds"` - fade DOM node out
+- Modify transition (slide only)
+    - `data-transform-origin-show="CSS transform origin"` - from where does the component slide in for example `0% 50%` to slide it in from mid-left
+    - `data-transform-origin-hide="CSS transform origin"` - where does the component slide out to for example `100% 100%` to slide it out to bottom-right
+    - `data-transition-axis-show="X | Y"` - slide animation axis
+    - `data-transition-axis-hide="X | Y"` - slide animation axis
 
 ## Good to know
-- [Uing CSS frameworks](#css-frameworks)
+- [Using CSS frameworks](#css-frameworks)
 - [Using JS runtimes other than Node.js](#runtimes)
 - [Why not JSR](#jsr)
+- [Best practices](#best-practices)
+- [Having an issue?](#issues-and-feedback)
 
 ### 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.
@@ -721,6 +804,46 @@ Run application using `deno main.ts`
 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.
 
+### Best practices
+
+**Entry point:**\
+I suggest the following setup for your entry point:
+1) Set `autoInit = false` in your `/Config.ts`
+2) If you are using ENV variables, define a type `EnvConf` in `/app/Types.ts`
+3) In `/index.ts`, only create the Application instance and import ENV using `importEnv`, exporting both, as follows:
+    ```
+    import { EnvConf } from './app/Types.js';
+    import { Application } from 'structured-fw/Application';
+    import { config } from './Config.js';
+
+    export const app = new Application(config);
+    export const env = app.importEnv<EnvConf>();
+    ```
+4) Create `/main.ts` and import `app` and `env` from `/index.ts`, add `main.ts` to tsconfig.json include array, add any event listeners, and load helpers from within `/main.ts`. This makes sure you can use env in any imported modules in main.ts without having to use dynamic imports. You can later import `env` and `app` from `index.ts` wherever you want to use them.
+
+\
+**Component directories**\
+You should always place your components in a directory named same as your component. While this is not required, it will keep things organized. You might think your component will only have a HTML part, but at some point you may decide you want to add client/server code to it, so it's better to start out with a directory.\
+Feel free to group your components in directories and subdirectories. Structured loads all components recursively when Application is initialized, and allows you to load any existing component from any component/Document. You can even move your components to other directory later without having to worry about updating the imports.
+
+**Type definitions**\
+I suggest keeping your general type definitions in /app/Types.ts, but for more specific types you should probably create /app/types/[entity].types.ts to keep things clean easy to maintain.\
+For example:\
+`export type BooleanInt = 0 | 1;` - this is fine 
+in /app/Types.ts\
+`export type User = {email: string, password: string}` - you should probably create /app/types/users.types.ts for this one
+
+**Models**\
+If you ran `npx structured init`, it has created /app/models for you. Structured does not use this directory, but I suggest keeping your models interfacing the DB/APIs there. While Structured framework is not an MVC in a traditional sense, it's a good idea to keep your models in one place, as you will want to import the same model from many routes and components.
+
+> [!IMPORTANT]
+> while it's true that with Structured, components take care of their own data, it does not mean that they need to contain the code to fetch said data, instead you are encouraged to keep data logic in your models, and use those models in components/routes.
+
+You can create additional code separation, for example, it would make sense to have /app/lib for code that interfaces an API, or have /app/Util.ts where you export utility functions. Structured boilerplate does not include these as not all applications will need them.
+
+### Issues and feedback
+If you have any issues with the framework or the npm package, please don't hesitate to open an issue on [github](https://github.com/julijan/structured). Feedback is also welcome!
+
 ## 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/index.js

@@ -1,3 +1,8 @@
 import { Application } from "structured-fw/Application";
 import { config } from './Config.js';
-new Application(config);
+const app = new Application(config);
+app.on('documentCreated', (document) => {
+    document.on('componentCreated', (component) => {
+        document.head.add(`<script>console.log('${component.name}')</script>`);
+    });
+});

package/build/system/EventEmitter.d.ts

@@ -0,0 +1,7 @@
+import { EventEmitterCallback } from "./Types.js";
+export declare class EventEmitter<T extends Record<string, any> = Record<string, any>> {
+    protected listeners: Partial<Record<keyof T, Array<EventEmitterCallback<any>>>>;
+    on<K extends keyof T>(eventName: K, callback: EventEmitterCallback<T[K]>): void;
+    emit(eventName: keyof T, payload?: any): void;
+    unbind(eventName: keyof T, callback: EventEmitterCallback<any>): void;
+}

package/build/system/EventEmitter.js

@@ -0,0 +1,31 @@
+export class EventEmitter {
+    constructor() {
+        this.listeners = {};
+    }
+    on(eventName, callback) {
+        if (!Array.isArray(this.listeners[eventName])) {
+            this.listeners[eventName] = [];
+        }
+        this.listeners[eventName].push(callback);
+    }
+    emit(eventName, payload) {
+        if (Array.isArray(this.listeners[eventName])) {
+            this.listeners[eventName].forEach((callback) => {
+                callback(payload);
+            });
+        }
+    }
+    unbind(eventName, callback) {
+        if (Array.isArray(this.listeners[eventName])) {
+            while (true) {
+                const index = this.listeners[eventName].indexOf(callback);
+                if (index > -1) {
+                    this.listeners[eventName].splice(index, 1);
+                }
+                else {
+                    break;
+                }
+            }
+        }
+    }
+}

package/build/system/Types.d.ts

@@ -127,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' | 'documentCreated' | 'beforeAssetAccess' | 'afterAssetAccess' | 'pageNotFound';
 export type SessionEntry = {
     sessionId: string;
     lastRequest: number;
@@ -166,4 +166,4 @@ export type ClientComponentTransition = {
 };
 export type ClientComponentTransitionEvent = 'show' | 'hide';
 export type ClientComponentTransitions = Record<ClientComponentTransitionEvent, ClientComponentTransition>;
-export type EventEmitterCallback = (payload: any) => void;
+export type EventEmitterCallback<T> = (payload: T) => void;

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

@@ -2,7 +2,7 @@ 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';
+import { EventEmitter } from '../EventEmitter.js';
 export declare class ClientComponent extends EventEmitter {
     readonly name: string;
     children: Array<ClientComponent>;

package/build/system/client/ClientComponent.js

@@ -2,7 +2,7 @@ import { attributeValueFromString, attributeValueToString, mergeDeep, objectEach
 import { DataStoreView } from './DataStoreView.js';
 import { Net } from './Net.js';
 import { NetRequest } from './NetRequest.js';
-import { EventEmitter } from './EventEmitter.js';
+import { EventEmitter } from '../EventEmitter.js';
 export class ClientComponent extends EventEmitter {
     constructor(parent, name, domNode, store, runInitializer = true) {
         super();

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.d.ts

@@ -1,7 +1,10 @@
 import { Document } from './Document.js';
 import { ComponentEntry, LooseObject } from '../Types.js';
 import { DOMNode } from './dom/DOMNode.js';
-export declare class Component {
+import { EventEmitter } from '../EventEmitter.js';
+export declare class Component<Events extends Record<string, any> = {
+    'componentCreated': Component;
+}> extends EventEmitter<Events> {
     id: string;
     name: string;
     document: Document;
@@ -20,8 +23,8 @@ export declare class Component {
     private initChildren;
     protected importedParentData(parentData: LooseObject): LooseObject;
     protected initAttributesData(domNode?: DOMNode): void;
-    private attributePreffix;
+    private attributePrefix;
     private attributeDataType;
-    private attributeUnpreffixed;
+    private attributeUnprefixed;
     protected fillData(data: LooseObject): void;
 }

package/build/system/server/Component.js

@@ -1,13 +1,16 @@
 import { Document } from './Document.js';
 import { attributeValueFromString, attributeValueToString, objectEach, toCamelCase } from '../Util.js';
 import { DOMFragment } from './dom/DOMFragment.js';
-export class Component {
+import { EventEmitter } from '../EventEmitter.js';
+export class Component extends EventEmitter {
     constructor(name, node, parent, autoInit = true) {
+        super();
         this.children = [];
         this.path = [];
         this.attributesRaw = {};
         this.attributes = {};
         this.data = {};
+        const isDocument = this instanceof Document;
         this.name = name;
         if (name === 'root') {
             this.dom = new DOMFragment();
@@ -21,7 +24,7 @@ export class Component {
             }
             this.isRoot = false;
         }
-        if (this instanceof Document) {
+        if (isDocument) {
             this.document = this;
         }
         else {
@@ -42,6 +45,9 @@ export class Component {
         else {
             this.entry = null;
         }
+        if (!isDocument) {
+            this.document.emit('componentCreated', this);
+        }
     }
     async init(html, data) {
         this.initAttributesData();
@@ -180,7 +186,7 @@ export class Component {
         }
         for (let i = 0; i < domNode.attributes.length; i++) {
             const attrNameRaw = domNode.attributes[i].name;
-            const attrNameUnprefixed = this.attributeUnpreffixed(attrNameRaw);
+            const attrNameUnprefixed = this.attributeUnprefixed(attrNameRaw);
             if (attrNameUnprefixed.indexOf('data-') === 0) {
                 const attrDataType = this.attributeDataType(attrNameRaw);
                 const dataDecoded = attributeValueFromString(domNode.attributes[i].value.toString());
@@ -214,7 +220,7 @@ export class Component {
             this.attributesRaw[attrNameRaw] = domNode.attributes[i].value;
         }
     }
-    attributePreffix(attrName) {
+    attributePrefix(attrName) {
         const index = attrName.indexOf(':');
         if (index < 0) {
             return null;
@@ -222,7 +228,7 @@ export class Component {
         return attrName.substring(0, index);
     }
     attributeDataType(attrName) {
-        const prefix = this.attributePreffix(attrName);
+        const prefix = this.attributePrefix(attrName);
         if (prefix === 'string' ||
             prefix === 'number' ||
             prefix === 'object' ||
@@ -231,7 +237,7 @@ export class Component {
         }
         return 'any';
     }
-    attributeUnpreffixed(attrName) {
+    attributeUnprefixed(attrName) {
         const index = attrName.indexOf(':');
         if (index < 0) {
             return attrName;

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

@@ -3,7 +3,9 @@ import { Initializers, LooseObject, RequestContext } from '../../system/Types.js
 import { Application } from './Application.js';
 import { DocumentHead } from './DocumentHead.js';
 import { Component } from './Component.js';
-export declare class Document extends Component {
+export declare class Document extends Component<{
+    'componentCreated': Component;
+}> {
     head: DocumentHead;
     language: string;
     application: Application;

package/index.ts

@@ -1,4 +1,21 @@
 import { Application } from "structured-fw/Application";
 import { config } from './Config.js';
 
-new Application(config);
+const app = 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);
+// })
+
+app.on('documentCreated', (document) => {
+    document.on('componentCreated', (component) => {
+        document.head.add(`<script>console.log('${component.name}')</script>`);
+    });
+})

package/package.json

@@ -14,12 +14,13 @@
   "license": "MIT",
   "type": "module",
   "main": "build/index",
-  "version": "0.8.21",
+  "version": "0.8.42",
   "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"
+    "prepublish": "tsc",
+    "postinstall": "rm tsconfig.json"
   },
   "bin": {
     "structured": "./build/system/bin/structured.js"

package/system/{client/EventEmitter.ts → EventEmitter.ts}

@@ -1,10 +1,10 @@
-import { EventEmitterCallback } from "../Types.js";
+import { EventEmitterCallback } from "./Types.js";
 
-export class EventEmitter {
-    protected listeners: Record<string, Array<EventEmitterCallback>> = {}
+export class EventEmitter<T extends Record<string, any> = Record<string, any>> {
+    protected listeners: Partial<Record<keyof T, Array<EventEmitterCallback<any>>>> = {}
 
     // add event listener
-    public on(eventName: string, callback: EventEmitterCallback): void {
+    public on<K extends keyof T>(eventName: K, callback: EventEmitterCallback<T[K]>): void {
         if (! Array.isArray(this.listeners[eventName])) {
             this.listeners[eventName] = [];
         }
@@ -13,7 +13,7 @@ export class EventEmitter {
     }
 
     // emit event with given payload
-    public emit(eventName: string, payload?: any): void {
+    public emit(eventName: keyof T, payload?: any): void {
         if (Array.isArray(this.listeners[eventName])) {
             this.listeners[eventName].forEach((callback) => {
                 callback(payload);
@@ -22,7 +22,7 @@ export class EventEmitter {
     }
 
     // remove event listener
-    public unbind(eventName: string, callback: EventEmitterCallback): void {
+    public unbind(eventName: keyof T, callback: EventEmitterCallback<any>): void {
         if (Array.isArray(this.listeners[eventName])) {
             while (true) {
                 const index = this.listeners[eventName].indexOf(callback);

package/system/Types.ts

@@ -177,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'|'documentCreated'|'beforeAssetAccess'|'afterAssetAccess'|'pageNotFound';
 
 export type SessionEntry = {
     sessionId : string,
@@ -229,4 +229,4 @@ export type ClientComponentTransition = {
 export type ClientComponentTransitionEvent = 'show' | 'hide';
 export type ClientComponentTransitions = Record<ClientComponentTransitionEvent, ClientComponentTransition>;
 
-export type EventEmitterCallback = (payload: any) => void
+export type EventEmitterCallback<T> = (payload: T) => void

package/system/client/ClientComponent.ts

@@ -4,7 +4,7 @@ import { DataStoreView } from './DataStoreView.js';
 import { DataStore } from './DataStore.js';
 import { Net } from './Net.js';
 import { NetRequest } from './NetRequest.js';
-import { EventEmitter } from './EventEmitter.js';
+import { EventEmitter } from '../EventEmitter.js';
 
 export class ClientComponent extends EventEmitter {
     readonly name: string;

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 {
@@ -144,7 +146,7 @@ export class Application {
         });
     }
 
-    // load envirnment variables
+    // load environment variables
     // if this.config.envPrefix is a string, load all ENV variables starting with [envPrefix]_
     // the method is generic, so user can define the expected return type
     public importEnv<T extends LooseObject>(smartPrimitives: boolean = true): T {

package/system/server/Component.ts

@@ -3,8 +3,9 @@ import { attributeValueFromString, attributeValueToString, objectEach, toCamelCa
 import { ComponentEntry, LooseObject } from '../Types.js';
 import { DOMFragment } from './dom/DOMFragment.js';
 import { DOMNode } from './dom/DOMNode.js';
+import { EventEmitter } from '../EventEmitter.js';
 
-export class Component {
+export class Component<Events extends Record<string, any> = {'componentCreated' : Component}> extends EventEmitter<Events> {
     id: string;
     name: string;
     document: Document;
@@ -29,6 +30,8 @@ export class Component {
     isRoot: boolean;
 
     constructor(name: string, node?: DOMNode, parent?: Document|Component, autoInit: boolean = true) {
+        super();
+        const isDocument = this instanceof Document;
         this.name = name;
 
         if (name === 'root') {
@@ -43,7 +46,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,16 +74,20 @@ export class Component {
         } else {
             this.entry = null;
         }
+
+        if (! isDocument) {
+            this.document.emit('componentCreated', this);
+        }
     }
     
     // load component's data and fill it
     // load any nested components recursively
     public async init(html: string, data?: LooseObject): Promise<void> {
 
-        // extract data-atributes and encode non-encoded attributes
+        // extract data-attributes and encode non-encoded attributes
         this.initAttributesData();
 
-        // create component container replacng the original tag name with a div
+        // create component container replacing the original tag name with a div
         // (or whatever is set as renderTagName on ComponentEntry)
         this.dom.tagName = this.entry?.renderTagName || 'div';
 
@@ -88,7 +95,7 @@ export class Component {
         this.dom.innerHTML = html;
 
 
-        // re-apply attributes the orignal tag had
+        // re-apply attributes the original tag had
         // no need to encode values at this point
         // any non-encoded attributes got encoded earlier by initAttributesData
         this.setAttributes(this.attributesRaw, '', false);
@@ -110,7 +117,7 @@ export class Component {
             this.id = this.attributes.componentId;
         }
 
-        // export RequestContext.data fields specified in Application.exporteRequestContextData
+        // export RequestContext.data fields specified in Application.exportedRequestContextData
         const exportedContextData = this.document.application.exportedRequestContextData.reduce((prev, field) => {
             if (! this.document.ctx) {return prev;}
             if (field in this.document.ctx.data) {
@@ -295,7 +302,7 @@ export class Component {
 
             // attributes can have a data prefix eg. number:data-num="3"
             // return unprefixed attribute name
-            const attrNameUnprefixed = this.attributeUnpreffixed(attrNameRaw);
+            const attrNameUnprefixed = this.attributeUnprefixed(attrNameRaw);
 
             if (attrNameUnprefixed.indexOf('data-') === 0) {
                 // only attributes starting with data- are stored to this.attributes
@@ -353,7 +360,7 @@ export class Component {
 
     // component attributes can have a data type prefix [prefix]:data-[name]="[val]"
     // returns the prefix
-    private attributePreffix(attrName: string): string|null {
+    private attributePrefix(attrName: string): string|null {
         const index = attrName.indexOf(':');
         if (index < 0) {
             return null;
@@ -364,7 +371,7 @@ export class Component {
     // returns the user defined data type of given attribute
     // for example number:data-total returns 'number'
     private attributeDataType(attrName: string): 'string'|'number'|'object'|'boolean'|'any' {
-        const prefix = this.attributePreffix(attrName);
+        const prefix = this.attributePrefix(attrName);
 
         if (
             prefix === 'string' ||
@@ -375,13 +382,13 @@ export class Component {
             return prefix;
         }
 
-        // unrecognized attribute preffix
+        // unrecognized attribute prefix
         return 'any';
     }
 
     // removes the data-type prefix from given attribute name
     // for example number:data-total returns data-total
-    private attributeUnpreffixed(attrName: string): string {
+    private attributeUnprefixed(attrName: string): string {
         const index = attrName.indexOf(':');
         if (index < 0) {
             return attrName;

package/system/server/Document.ts

@@ -9,7 +9,7 @@ import { attributeValueToString, randomString } from '../Util.js';
 import path from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 
-export class Document extends Component {
+export class Document extends Component<{'componentCreated': Component}> {
 
     head: DocumentHead;
     language = 'en';

package/tsconfig.json

@@ -10,7 +10,7 @@
         "module": "ES2020",
         "target": "ES2021",
         "alwaysStrict": true,
-        "allowSyntheticDefaultImports": true, // albe to do import { default as varname } from 'module'
+        "allowSyntheticDefaultImports": true, // able to do import { default as varname } from 'module'
         "declaration": true,
         "isolatedDeclarations": true,
         "noImplicitReturns": true,