structured-fw 0.8.1 → 0.8.3

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
@@ -106,12 +111,12 @@ new Application(config);
 ### Methods
 - `init(): Promise<void>` - initializes application, you only need to run this if you set `autoInit = false` in config, otherwise this will be ran when you create the Application instance
 - `on(evt: ApplicationEvents, callback: RequestCallback|((payload?: any) => void))` - allows you to add event listeners for specific `ApplicationEvenets`:
-    - `serverStarted` - executed once the built-in http server is started and running. Callback receives no arguments
+    - `serverStarted` - executed once the built-in http server is started and running. Callback receives Server (exported from node:http) instance as the first argument
     - `beforeRequestHandler` - runs before any request handler (route) is executed. Callback receives `RequestContext` as the first argument. Useful for example to set `RequestContext.data: RequestContextData` (user defined data, to make it available to routes and components)
     - `afterRequestHandler` - runs after any request handler (route) is executed. Callback receives `RequestContext` as the first argument
     - `afterRoutes` - runs after all routes are loaded from `StructuredConfig.routes.path`. Callback receives no arguments
-    - `beforeComponentLoad` - runs before components are loaded from `StructuredConfig.components.path`. Callback receives no arguments
-    - `afterComponentLoad` - runs after all components are loaded from `StructuredConfig.components.path`. Callback receives no arguments
+    - `beforeComponentsLoad` - runs before components are loaded from `StructuredConfig.components.path`. Callback receives no arguments
+    - `afterComponentsLoaded` - runs after all components are loaded from `StructuredConfig.components.path`. Callback receives instance of Components as the first argument
     - `documentCreated` - runs whenever an instance of a [Document](#document) is created. Callback receives the Document instance as the first argument. You will often use this, for example if you want to include a CSS file to all pages `Document.head.addCSS(...)`
     - `beforeAssetAccess` - runs when assets are being accessed, before response is sent. Callback receives `RequestContext` as the first argument
     - `afterAssetAccess` - runs when assets are being accessed, after response is sent. Callback receives `RequestContext` as the first argument
@@ -319,7 +324,7 @@ In some edge cases you may need more control of when a route is executed, in whi
 >}>('POST', '/users/create', asyc (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
 > });
 > ```
@@ -605,6 +610,117 @@ Methods:
 - `arrayRef<T>(refName: string): Array<T>` - get an array of HTMLElement or ClientComponent that have attribute `array:ref="[refName]"`
 - `add(appendTo: HTMLElement, componentName: string, data?: LooseObject)` - add `componentName` component to `appendTo` element, optionally passing `data` to the component when it's being rendered
 
+## Good to know
+- [Uing CSS frameworks](#css-frameworks)
+- [Using JS runtimes other than Node.js](#runtimes)
+- [Why not JSR](#jsr)
+
+### CSS frameworks
+We rarely write all CSS from scratch, usually we use a CSS framework to speed us up. Structured allows you to work with any CSS frameworks such as Tailwind, PostCSS or Bootstrap.
+
+Your Tailwind configuration may look something like:
+```
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: ["./app/views/**/*.html", "./app/views/**/*.hbs"],
+  ...
+}
+```
+
+Above we just defined where all our HTML resides, which is within /app/views. That is all there is to it. From there, you can generate the CSS, for example:\
+`npx tailwindcss -i ./assets/css/src/style.css -o ./assets/css/dist.css`
+
+**Including the output CSS**\
+To include the output CSS in all pages, you can add the following to `index.ts`:
+```
+const app = new Application(config);
+
+app.on('documentCreated', (doc) => {
+    doc.head.addCSS('/assets/css/dist.css');
+});
+```
+
+### Runtimes
+Structured is tested with Node.js and Deno. Other runtimes would likely work as well.
+
+To use Structured with Deno, you can:
+```
+cd /path/to/project
+deno init
+deno add npm:structured-fw
+```
+
+With Deno, we can't use the cli to create the boilerplate, so you will need to create it yourself.
+```
+mkdir app
+mkdir app/views
+mkdir app/routes
+```
+
+Create `Config.ts`:
+```
+import { StructuredConfig } from "structured-fw/Types";
+
+export const config: StructuredConfig = {
+    // Application.importEnv will load all env variables starting with [envPrefix]_
+    envPrefix: 'STRUCTURED',
+
+    // whether to call Application.init when an instance of Application is created
+    autoInit: true,
+
+    url: {
+        removeTrailingSlash: true,
+
+        // if you want to enable individual component rendering set this to URI (string)
+        // to disable component rendering set it to false
+        // setting this to false disallows the use of ClientComponent.redraw and ClientComponent.add
+        componentRender: '/componentRender',
+
+        // function that receives the requested URL and returns boolean, if true, treat as static asset
+        // if there is a registered request handler that matches this same URL, it takes precedence over this
+        isAsset: function(uri: string) {
+            return uri.indexOf('/assets/') === 0;
+        }
+    },
+    routes: {
+        path: '/app/routes'
+    },
+    components : {
+        // relative to index.ts
+        path: '/app/views',
+
+        componentNameAttribute: 'structured-component'
+    },
+    session: {
+        cookieName: 'session',
+        keyLength: 24,
+        durationSeconds: 60 * 60,
+        garbageCollectIntervalSeconds: 60
+    },
+    http: {
+        port: 9191,
+        host: '0.0.0.0',
+        // used by Document.push, can be preload or preconnect
+        linkHeaderRel : 'preload'
+    },
+    runtime: 'Deno'
+}
+```
+
+Import `Config.ts` in `main.ts` and create the Application instance:
+```
+import { Application } from 'structured-fw/Application';
+import { config } from './Config.ts';
+
+new Application(config);
+```
+
+Run application using `deno main.ts`
+
+### JSR
+It would make a lot of sense to have Structured hosted on JSR (JavaScript Registry) given Structured is a TypeScript framework, and JSR is a TypeScript-first registry, however, the issue is that Deno imposes [limitations with dynamic imports](https://docs.deno.com/deploy/api/dynamic-import/) with JSR-imported dependencies, which are required for the framework (to dynamically import your routes and components).\
+This does not stop the framework from working with Deno, but for the time being, we have to stick with good old npm.
+
 ## Why Structured
 Framework was developed by someone who has been a web developer for almost 20 years (me), and did not like the path web development has taken.
 \

package/build/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' | 'componentCreated' | 'documentCreated' | 'beforeAssetAccess' | 'afterAssetAccess' | 'pageNotFound';
 export type SessionEntry = {
     sessionId: string;
     lastRequest: number;

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

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

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

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

package/build/system/server/Application.js

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

package/build/system/server/Component.js

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

package/index.ts

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

package/jsr.json

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

package/package.json

@@ -14,7 +14,7 @@
   "license": "MIT",
   "type": "module",
   "main": "build/index",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "scripts": {
     "develop": "tsc --watch",
     "startDev": "cd build && nodemon --watch '../app/**/*' --watch '../build/**/*' -e js,html,css index.js",

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'|'componentCreated'|'documentCreated'|'beforeAssetAccess'|'afterAssetAccess'|'pageNotFound';
 
 export type SessionEntry = {
     sessionId : string,

package/system/client/ClientComponent.ts

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

package/system/global.d.ts

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

package/system/server/Application.ts

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

package/system/server/Component.ts

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