structured-fw 0.8.43 → 0.8.71

package/README.md

@@ -5,9 +5,6 @@ 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)
@@ -41,6 +38,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)
@@ -57,6 +65,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
@@ -418,7 +428,7 @@ That was the simplest possible example, let's make it more interesting by adding
 ### 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
@@ -460,7 +470,7 @@ 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');
 
@@ -509,7 +519,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,
@@ -542,7 +552,7 @@ What about client side? **By default, data returned by server side code is not a
 
 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');
 
@@ -552,7 +562,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<{
@@ -574,7 +584,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');
 
@@ -585,7 +595,7 @@ 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 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');
 
@@ -595,7 +605,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
@@ -678,6 +688,69 @@ then in ComponentName.html:
 <div data-if="showDiv()"></div>
 ```
 
+### Layout
+Prior to version 0.8.7:
+
+1) `/app/views/layout.html`
+    ```
+    ...
+    {{{layoutComponent component data attributes}}}
+    ...
+    ```
+2) `/app/routes/Test.ts`
+    ```
+    import Document from 'structured-fw/Document';
+
+    app.request.on('GET', '/test', async (ctx) => {
+        const doc = new Document(app, 'Title', ctx);
+        await doc.loadComponent('layout', {
+            component: 'ComponentName',
+            data: {
+                something: 123
+            }
+        });
+        return doc;
+    });
+    ```
+
+Version 0.8.7 introduced the `Layout` class, which allows accomplishing the above in a nicer way:
+1) `/app/views/layout.html`
+    ```
+    ...
+    <template></template>
+    ...
+    ```
+2) `/index.ts` (`app` is an instance of `Application`)
+    ```
+    export const layout = new Layout(app, 'layout');
+    ```
+3) `/app/routes/Test.ts`
+    ```
+    import { layout } from '../../index.js';
+
+    app.request.on('GET', '/test', async (ctx) => {
+        return await layout.document(ctx, 'Test', 'Conditionals', {
+            something: 123
+        });
+    });
+
+    ```
+
+While with the new approach there is an extra step where we create the instance(s) of `Layout`, it makes the route/template code cleaner (you will create your layout instance(s) only once, while you will likely use it in many routes, so adding an extra step is worth it).
+
+```
+Layout.document(
+    ctx: RequestContext,
+    title: string,
+    componentName: string,
+    data?: LooseObject
+): Promise<Document>
+```
+`Layout.document` the only method of Layout you will use, it creates an instance of Document, loads template component (provided as second argument to Layout constructor) into it and loads `componentName` component in place of `<template></template>` found within your template.
+
+> [!TIP]
+> You will often want to use a few different layouts in your web application. You can achieve that by creating and exporting multiple instances of Layout and use the appropriate one where you need it.
+
 **Basic animation/transitions**\
 If you use conditionals on any DOM node, you may also enable basic animations/transitions using following attributes:
 - Enable transition:

package/build/system/bin/structured.js

@@ -61,9 +61,9 @@ function createTsconfig() {
                 "strictNullChecks": true,
                 "strictPropertyInitialization": true,
                 "strictBindCallApply": true,
-                "moduleResolution": "bundler",
+                "moduleResolution": "node16",
                 "outDir": "./build",
-                "module": "ES2020",
+                "module": "Node16",
                 "target": "ES2021",
                 "allowSyntheticDefaultImports": true,
                 "preserveSymlinks": true,

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

@@ -4,6 +4,7 @@ export declare class Net {
     request(method: RequestMethod, url: string, headers?: IncomingHttpHeaders, body?: any, responseType?: XMLHttpRequestResponseType): Promise<string>;
     get(url: string, headers?: IncomingHttpHeaders): Promise<string>;
     delete(url: string, headers?: IncomingHttpHeaders): Promise<string>;
+    private serializeData;
     post(url: string, data: any, headers?: IncomingHttpHeaders): Promise<string>;
     put(url: string, data: any, headers?: IncomingHttpHeaders): Promise<string>;
     getJSON<T>(url: string, headers?: IncomingHttpHeaders): Promise<T>;

package/build/system/client/Net.js

@@ -10,18 +10,19 @@ export class Net {
     async delete(url, headers = {}) {
         return this.request('DELETE', url, headers);
     }
-    async post(url, data, headers = {}) {
+    serializeData(data, headers) {
         if (typeof data === 'object' && !headers['content-type'] && !(data instanceof FormData)) {
             headers['content-type'] = 'application/json';
-            data = JSON.stringify(data);
+            return JSON.stringify(data);
         }
+        return data;
+    }
+    async post(url, data, headers = {}) {
+        data = this.serializeData(data, headers);
         return await this.request('POST', url, headers, data);
     }
     async put(url, data, headers = {}) {
-        if (typeof data === 'object' && !headers['content-type']) {
-            headers['content-type'] = 'application/json';
-            data = JSON.stringify(data);
-        }
+        data = this.serializeData(data, headers);
         return this.request('PUT', url, headers, data);
     }
     async getJSON(url, headers) {

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;
+    initialized: boolean;
     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<Opt extends Readonly<LooseObject>>(callback: (app: Application, options: Opt) => void | Promise<void>, opts: NoInfer<Opt>): Promise<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);
     }
+    async registerPlugin(callback, opts) {
+        if (this.initialized) {
+            console.warn('Plugin registered after app is initialized, some plugin features may not work.');
+        }
+        await callback.apply(this, [this, opts]);
+    }
     async respondWithComponent(ctx, componentName, attributes, unwrap = true) {
         const component = this.components.getByName(componentName);
         if (component) {

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/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;

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

@@ -0,0 +1,10 @@
+import { LooseObject, RequestContext } from "../Types.js";
+import { Application } from "./Application.js";
+import { Document } from "./Document.js";
+export declare class Layout {
+    layoutComponent: string;
+    app: Application;
+    constructor(app: Application, layoutComponent: string);
+    private layoutComponentExists;
+    document(ctx: RequestContext, title: string, componentName: string, data?: LooseObject): Promise<Document>;
+}

package/build/system/server/Layout.js

@@ -0,0 +1,30 @@
+import { Component } from "./Component.js";
+import { Document } from "./Document.js";
+export class Layout {
+    constructor(app, layoutComponent) {
+        this.app = app;
+        this.layoutComponent = layoutComponent;
+        if (this.app.initialized) {
+            this.layoutComponentExists();
+        }
+        else {
+            this.app.on('afterComponentsLoaded', () => { this.layoutComponentExists(); });
+        }
+    }
+    layoutComponentExists() {
+        if (this.app.components.getByName(this.layoutComponent) === null) {
+            throw new Error(`Layout component "${this.layoutComponent}" not found`);
+        }
+    }
+    async document(ctx, title, componentName, data) {
+        const doc = new Document(this.app, title, ctx);
+        await doc.loadComponent(this.layoutComponent, data);
+        const layoutComponent = doc.dom.queryByTagName('template');
+        if (layoutComponent.length === 0) {
+            throw new Error(`<template></template> not found in the layout component ${this.layoutComponent}`);
+        }
+        const component = new Component(componentName, layoutComponent[0], doc, false);
+        await component.init(`<${componentName}></${componentName}>`, data);
+        return doc;
+    }
+}

package/index.ts

@@ -1,8 +1,15 @@
 import { Application } from "structured-fw/Application";
 import { config } from './Config.js';
+import { Layout } from "./system/server/Layout.js";
 
 const app = new Application(config);
 
+app.registerPlugin(async (app) => {
+    
+}, {
+    poop: 123
+});
+
 // app.on('afterComponentsLoaded', (components) => {
 //     components.componentNames.forEach((componentName) => {
 //         console.log(componentName)
@@ -18,4 +25,6 @@ app.on('documentCreated', (document) => {
     document.on('componentCreated', (component) => {
         document.head.add(`<script>console.log('${component.name}')</script>`);
     });
-})
+});
+
+export const layout: Layout = new Layout(app, 'layout');

package/package.json

@@ -14,7 +14,7 @@
   "license": "MIT",
   "type": "module",
   "main": "build/index",
-  "version": "0.8.43",
+  "version": "0.8.71",
   "scripts": {
     "develop": "tsc --watch",
     "startDev": "cd build && nodemon --watch '../app/**/*' --watch '../build/**/*' -e js,html,css index.js",
@@ -48,6 +48,8 @@
     "./Util": "./build/system/Util.js",
     "./Application": "./build/system/server/Application.js",
     "./Document": "./build/system/server/Document.js",
+    "./Component": "./build/system/server/Component.js",
+    "./Layout": "./build/system/server/Layout.js",
     "./FormValidation": "./build/system/server/FormValidation.js",
     "./ClientComponent": "./build/system/client/ClientComponent.js"
   }