structured-fw 0.8.1 → 0.8.4

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
@@ -105,13 +110,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
@@ -168,7 +173,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.
 
@@ -316,16 +321,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);`
@@ -341,7 +346,7 @@ app.request.on('GET', '/home', async (ctx) => {
 
 ## 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
+* 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)
 
@@ -362,7 +367,7 @@ 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
 
 Let's create a HelloWorld Component `/app/views/HelloWorld/HelloWorld.html`:\
@@ -494,7 +499,7 @@ 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).
 
@@ -550,7 +555,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() {
@@ -580,7 +585,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`.
 
@@ -600,11 +605,160 @@ 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
 
+## Good to know
+- [Using CSS frameworks](#css-frameworks)
+- [Using JS runtimes other than Node.js](#runtimes)
+- [Why not JSR](#jsr)
+- [Best practices](#best-practices)
+
+### 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.
+
+### 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.
+
 ## 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

@@ -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;
-    }
-}
+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/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,12 +14,13 @@
   "license": "MIT",
   "type": "module",
   "main": "build/index",
-  "version": "0.8.1",
+  "version": "0.8.4",
   "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 && mv tsconfig.json _ts.json",
+    "postpublish": "mv _ts.json 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

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

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 {
@@ -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,