structured-fw 0.8.3 → 0.8.5

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)
@@ -38,6 +41,17 @@ npm install @types/node
 ### Create boilerplate
 `npx structured init`
 
+### Create a test route
+Create a file `/app/routes/Test.ts`:
+```
+import { Application } from 'structured-fw/Application';
+export default function(app: Application) {
+    app.request.on('GET', '/test', async()=> {
+        return 'Hello, World!';
+    });
+}
+```
+
 ### Compile
 `tsc`\
 This will create a directory `build` (or whatever you have in tsconfig.json as compilerOptions.outputDir)
@@ -54,6 +68,8 @@ cd build
 pm2 start index.js --name="[appName]"
 ```
 
+If you followed the above steps, you should be able to access `http://localhost:9191/test` in your browser and see the output `Hello, World!`.
+
 # Key concepts
 
 ## Application
@@ -110,7 +126,7 @@ 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`:
+- `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
@@ -173,7 +189,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,7 +337,7 @@ 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(app, 'User', ctx);
@@ -330,7 +346,7 @@ In some edge cases you may need more control of when a route is executed, in whi
 > ```
 
 ## 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 +360,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 +395,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,10 +423,15 @@ 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';
+import { ComponentScaffold } from 'structured-fw/Types';
 export default class HelloWorld implements ComponentScaffold {
     async getData(): Promise<{
         luckyNumber: number
@@ -423,10 +462,18 @@ 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';
+import { InitializerFunction } from 'structured-fw/Types';
 export const init: InitializerFunction = async function() {
     const generateNew = this.ref<HTMLButtonElement>('newNumber');
 
@@ -475,7 +522,7 @@ Parent says your lucky number is {{number}}.
 That's it. Since `AnotherComponent` has no server side code, all data passed to it is exported to HTML, hence the `number` you passed from `HelloWorld` will be readily available for use. If AnotherComponent had a server side part, the process is a bit different, it will receive it as part of the `data`, but can choose whether to make it available to the HTML, or just make use of it and return other stuff. Let's see how that works.
 Create `/app/views/AnotherComponent/AnotherComponent.ts`:
 ```
-import { ComponentScaffold } from 'system/Types.js';
+import { ComponentScaffold } from 'structured-fw/Types';
 export default class AnotherComponent implements ComponentScaffold {
     async getData(data: { number: number }): Promise<{
         parentSuggests: number,
@@ -499,22 +546,16 @@ 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';
+import { InitializerFunction } from 'structured-fw/Types';
 export const init: InitializerFunction = async function() {
     const betterNumber = this.getData<number>('betterNumber');
 
@@ -524,7 +565,7 @@ export const init: InitializerFunction = async function() {
 
 And let's update `AnotherComponent.ts` to export `betterNumber`:
 ```
-import { ComponentScaffold } from 'system/Types.js';
+import { ComponentScaffold } from 'structured-fw/Types';
 export default class AnotherComponent implements ComponentScaffold {
     exportFields = ['betterNumber'];
     async getData(data: { number: number }): Promise<{
@@ -546,7 +587,7 @@ This concept is wrong to start with, if we want a component to be independent, i
 
 Let's say we wanted to access the `parent` Component from `AnotherComponent`:
 ```
-import { InitializerFunction } from 'system/Types.js';
+import { InitializerFunction } from 'structured-fw/Types';
 export const init: InitializerFunction = async function() {
     const betterNumber = this.getData<number>('betterNumber');
 
@@ -555,9 +596,9 @@ 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';
+import { InitializerFunction } from 'structured-fw/Types';
 export const init: InitializerFunction = async function() {
     const betterNumber = this.getData<number>('betterNumber');
 
@@ -567,7 +608,7 @@ export const init: InitializerFunction = async function() {
 
 We emitted an `event` with `eventName` = "`truth`" and a `payload`, which in this case is a string, but can be of any type. If the parent cares about it (or for that matter, not necessarily the parent, but anyone in the component tree), they can subscribe to that event. Let's subscribe to the event from `HelloWorld` (`HelloWorld.client.ts`):
 ```
-import { InitializerFunction } from 'system/Types.js';
+import { InitializerFunction } from 'structured-fw/Types';
 export const init: InitializerFunction = async function() {
 
     const child = this.find('AnotherComponent'); // ClientComponent | null
@@ -585,7 +626,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 +646,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 +817,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/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/{system/client/EventEmitter.ts → build/system/EventEmitter.js}

@@ -1,38 +1,31 @@
-import { EventEmitterCallback } from "../Types.js";
-
 export class EventEmitter {
-    protected listeners: Record<string, Array<EventEmitterCallback>> = {}
-
-    // add event listener
-    public on(eventName: string, callback: EventEmitterCallback): void {
-        if (! Array.isArray(this.listeners[eventName])) {
+    constructor() {
+        this.listeners = {};
+    }
+    on(eventName, callback) {
+        if (!Array.isArray(this.listeners[eventName])) {
             this.listeners[eventName] = [];
         }
-
         this.listeners[eventName].push(callback);
     }
-
-    // emit event with given payload
-    public emit(eventName: string, payload?: any): void {
+    emit(eventName, payload) {
         if (Array.isArray(this.listeners[eventName])) {
             this.listeners[eventName].forEach((callback) => {
                 callback(payload);
             });
         }
     }
-
-    // remove event listener
-    public unbind(eventName: string, callback: EventEmitterCallback): void {
+    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 {
-                    // callback not found, all removed
+                }
+                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' | 'beforeComponentsLoad' | 'afterComponentsLoaded' | 'componentCreated' | '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

@@ -1,5 +1,5 @@
 import { Server } from 'node:http';
-import { ApplicationEvents, LooseObject, RequestContext, StructuredConfig } from '../Types';
+import { ApplicationEvents, LooseObject, RequestContext, StructuredConfig } from '../Types.js';
 import { Document } from './Document.js';
 import { Components } from './Components.js';
 import { Session } from './Session.js';
@@ -8,6 +8,7 @@ import { Handlebars } from './Handlebars.js';
 import { Cookies } from './Cookies.js';
 export declare class Application {
     readonly config: StructuredConfig;
+    private initialized;
     server: null | Server;
     listening: boolean;
     private readonly eventEmitter;
@@ -25,6 +26,7 @@ export declare class Application {
     importEnv<T extends LooseObject>(smartPrimitives?: boolean): T;
     exportContextFields(...fields: Array<keyof RequestContextData>): void;
     contentType(extension: string): string | false;
+    registerPlugin(callback: (app: Application) => void): void;
     private respondWithComponent;
     memoryUsage(): NodeJS.MemoryUsage;
     printMemoryUsage(): void;

package/build/system/server/Application.js

@@ -12,6 +12,7 @@ import { Handlebars } from './Handlebars.js';
 import { Cookies } from './Cookies.js';
 export class Application {
     constructor(config) {
+        this.initialized = false;
         this.server = null;
         this.listening = false;
         this.eventEmitter = new EventEmitter();
@@ -28,6 +29,9 @@ export class Application {
         }
     }
     async init() {
+        if (this.initialized) {
+            return;
+        }
         this.eventEmitter.setMaxListeners(10);
         try {
             await this.handlebars.loadHelpers('../Helpers.js');
@@ -63,6 +67,7 @@ export class Application {
             return '';
         }, this, true);
         await this.start();
+        this.initialized = true;
     }
     start() {
         return new Promise((resolve, reject) => {
@@ -136,6 +141,12 @@ export class Application {
     contentType(extension) {
         return mime.contentType(extension);
     }
+    registerPlugin(callback) {
+        if (this.initialized) {
+            console.warn('Plugin registered after app is initialized, some plugin features may not work.');
+        }
+        callback(this);
+    }
     async respondWithComponent(ctx, componentName, attributes, unwrap = true) {
         const component = this.components.getByName(componentName);
         if (component) {

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,8 +1,10 @@
 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 = {};
@@ -44,7 +46,7 @@ export class Component {
             this.entry = null;
         }
         if (!isDocument) {
-            this.document.application.emit('componentCreated', this);
+            this.document.emit('componentCreated', this);
         }
     }
     async init(html, data) {
@@ -184,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());
@@ -218,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;
@@ -226,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' ||
@@ -235,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/Components.d.ts

@@ -1,4 +1,4 @@
-import { ComponentEntry, StructuredConfig } from '../Types';
+import { ComponentEntry, StructuredConfig } from '../Types.js';
 import { Application } from './Application.js';
 export declare class Components {
     config: StructuredConfig;

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/build/system/server/DocumentHead.d.ts

@@ -1,4 +1,4 @@
-import { DocumentResource } from '../Types';
+import { DocumentResource } from '../Types.js';
 export declare class DocumentHead {
     title: string;
     js: Array<DocumentResource>;

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

@@ -1,4 +1,4 @@
-import { FormValidationEntry, PostedDataDecoded, ValidationResult, ValidationRuleWithArguments, ValidatorErrorDecorator, ValidatorFunction } from '../Types';
+import { FormValidationEntry, PostedDataDecoded, ValidationResult, ValidationRuleWithArguments, ValidatorErrorDecorator, ValidatorFunction } from '../Types.js';
 export declare class FormValidation {
     fieldRules: Array<FormValidationEntry>;
     singleError: boolean;