structured-fw 0.7.2

package/build/system/server/Session.js

@@ -0,0 +1,114 @@
+import { randomString } from '../Util.js';
+export class Session {
+    constructor(app) {
+        this.enabled = false;
+        this.sessions = {};
+        this.application = app;
+        this.application.on('beforeRequestHandler', async (ctx) => {
+            if (this.enabled) {
+                const sessionCookie = ctx.cookies[this.application.config.session.cookieName];
+                const invalidSessionId = sessionCookie && !this.sessions[sessionCookie];
+                if (!sessionCookie || invalidSessionId) {
+                    this.sessionInit(ctx);
+                }
+                else {
+                    ctx.sessionId = sessionCookie;
+                    if (ctx.sessionId) {
+                        this.application.cookies.set(ctx.response, this.application.config.session.cookieName, ctx.sessionId, this.application.config.session.durationSeconds);
+                        this.sessions[ctx.sessionId].lastRequest = new Date().getTime();
+                    }
+                }
+            }
+        });
+        this.garbageCollect();
+    }
+    start() {
+        this.enabled = true;
+    }
+    stop() {
+        this.enabled = false;
+    }
+    sessionInit(ctx) {
+        ctx.sessionId = this.generateId();
+        this.application.cookies.set(ctx.response, this.application.config.session.cookieName, ctx.sessionId, this.application.config.session.durationSeconds);
+        const sessionEntry = {
+            sessionId: ctx.sessionId,
+            lastRequest: new Date().getTime(),
+            data: {}
+        };
+        this.sessions[ctx.sessionId] = sessionEntry;
+    }
+    generateId() {
+        return randomString(this.application.config.session.keyLength);
+    }
+    garbageCollect() {
+        const time = new Date().getTime();
+        const sessDurationMilliseconds = this.application.config.session.garbageCollectAfterSeconds * 1000;
+        for (const sessionId in this.sessions) {
+            const sess = this.sessions[sessionId];
+            if (time - sess.lastRequest > sessDurationMilliseconds) {
+                delete this.sessions[sessionId];
+            }
+        }
+        setTimeout(() => {
+            this.garbageCollect();
+        }, this.application.config.session.garbageCollectIntervalSeconds * 1000);
+    }
+    setValue(sessionId, key, value) {
+        if (sessionId === undefined) {
+            return;
+        }
+        if (this.sessions[sessionId]) {
+            const session = this.sessions[sessionId];
+            session.data[key] = value;
+        }
+    }
+    getValue(sessionId, key) {
+        if (sessionId === undefined) {
+            return null;
+        }
+        if (this.sessions[sessionId]) {
+            const session = this.sessions[sessionId];
+            return typeof session.data[key] !== 'undefined' ? session.data[key] : null;
+        }
+        return null;
+    }
+    getClear(sessionId, key) {
+        const val = this.getValue(sessionId, key);
+        this.removeValue(sessionId, key);
+        return val;
+    }
+    removeValue(sessionId, key) {
+        if (sessionId === undefined) {
+            return;
+        }
+        if (this.sessions[sessionId] && this.sessions[sessionId].data[key]) {
+            delete this.sessions[sessionId].data[key];
+        }
+    }
+    clear(sessionId) {
+        if (sessionId === undefined) {
+            return;
+        }
+        if (this.sessions[sessionId]) {
+            this.sessions[sessionId].data = {};
+        }
+    }
+    extract(sessionId, keys) {
+        if (sessionId === undefined) {
+            return {};
+        }
+        const data = {};
+        keys.forEach((key) => {
+            if (typeof key === 'string') {
+                data[key] = this.getValue(sessionId, key);
+            }
+            else {
+                const keyInSession = Object.keys(key)[0];
+                const keyReturned = key[keyInSession];
+                data[keyReturned] = this.getValue(sessionId, keyInSession);
+            }
+        });
+        return data;
+    }
+}

package/build/system/server/dom/DOMFragment.d.ts

@@ -0,0 +1,4 @@
+import { DOMNode } from "./DOMNode.js";
+export declare class DOMFragment extends DOMNode {
+    constructor();
+}

package/build/system/server/dom/DOMFragment.js

@@ -0,0 +1,6 @@
+import { DOMNode } from "./DOMNode.js";
+export class DOMFragment extends DOMNode {
+    constructor() {
+        super('body');
+    }
+}

package/build/system/server/dom/DOMNode.d.ts

@@ -0,0 +1,31 @@
+type DOMNodeAttribute = {
+    name: string;
+    value: string | true;
+};
+type JSONNode = {
+    name: string;
+    children: Array<JSONNode>;
+    attributes: Record<string, DOMNodeAttribute>;
+    strings: Array<string>;
+};
+export declare const selfClosingTags: ReadonlyArray<string>;
+export declare class DOMNode {
+    tagName: string;
+    parentNode: DOMNode | null;
+    children: Array<DOMNode | string>;
+    attributes: Array<DOMNodeAttribute>;
+    attributeMap: Record<string, DOMNodeAttribute>;
+    style: Partial<CSSStyleDeclaration>;
+    selfClosing: boolean;
+    constructor(tagName: string);
+    appendChild(node: DOMNode | string): void;
+    setAttribute(attributeName: string, attributeValue: string | true): void;
+    hasAttribute(attributeName: string): boolean;
+    queryByTagName(...tagNames: Array<string>): Array<DOMNode>;
+    queryByHasAttribute(...attributeNames: Array<string>): Array<DOMNode>;
+    get innerHTML(): string;
+    set innerHTML(html: string);
+    get outerHTML(): string;
+    toObject(): JSONNode;
+}
+export {};

package/build/system/server/dom/DOMNode.js

@@ -0,0 +1,110 @@
+import { HTMLParser } from "./HTMLParser.js";
+export const selfClosingTags = ['br', 'hr', 'input', 'img', 'link', 'meta', 'source', 'embed', 'path', 'area'];
+export class DOMNode {
+    constructor(tagName) {
+        this.parentNode = null;
+        this.children = [];
+        this.attributes = [];
+        this.attributeMap = {};
+        this.style = {};
+        this.tagName = tagName;
+        this.selfClosing = selfClosingTags.includes(tagName);
+    }
+    appendChild(node) {
+        if (typeof node !== 'string') {
+            node.parentNode = this;
+        }
+        this.children.push(node);
+    }
+    setAttribute(attributeName, attributeValue) {
+        const attributeExisting = this.attributeMap[attributeName];
+        if (!attributeExisting) {
+            const attribute = {
+                name: attributeName,
+                value: attributeValue
+            };
+            this.attributeMap[attributeName] = attribute;
+            this.attributes.push(attribute);
+        }
+        else {
+            attributeExisting.value = attributeValue;
+        }
+    }
+    hasAttribute(attributeName) {
+        return attributeName in this.attributeMap;
+    }
+    queryByTagName(...tagNames) {
+        let nodes = [];
+        for (let i = 0; i < this.children.length; i++) {
+            const child = this.children[i];
+            if (typeof child === 'string') {
+                continue;
+            }
+            if (tagNames.includes(child.tagName)) {
+                nodes.push(child);
+            }
+            nodes = nodes.concat(child.queryByTagName(...tagNames));
+        }
+        return nodes;
+    }
+    queryByHasAttribute(...attributeNames) {
+        let nodes = [];
+        for (let i = 0; i < this.children.length; i++) {
+            const child = this.children[i];
+            if (typeof child === 'string') {
+                continue;
+            }
+            if (attributeNames.some((attributeName) => {
+                return child.hasAttribute(attributeName);
+            })) {
+                nodes.push(child);
+            }
+            nodes = nodes.concat(child.queryByHasAttribute(...attributeNames));
+        }
+        return nodes;
+    }
+    get innerHTML() {
+        return this.children.reduce((html, child) => {
+            if (typeof child === 'string') {
+                return html += child;
+            }
+            else {
+                return html += child.outerHTML;
+            }
+        }, '');
+    }
+    set innerHTML(html) {
+        const fragment = new HTMLParser(html).dom();
+        this.children = fragment.children;
+    }
+    get outerHTML() {
+        const attributes = this.attributes.reduce((attributes, attribute) => {
+            attributes += ` ${attribute.name}${attribute.value === true ? '' : `="${attribute.value}"`}`;
+            return attributes;
+        }, '');
+        const style = Object.keys(this.style).reduce((style, styleName) => {
+            const styleValue = this.style[styleName];
+            if (styleValue?.toString().trim().length === 0) {
+                return style;
+            }
+            ;
+            style += ` ${styleName}: ${styleValue};`;
+            return style;
+        }, '');
+        return `<${this.tagName}${attributes}${style.trim().length > 0 ? ` style="${style}"` : ''}>${this.selfClosing ? '' : `${this.innerHTML}</${this.tagName}>`}`;
+    }
+    toObject() {
+        return {
+            name: this.tagName,
+            children: this.children.filter((child) => {
+                return typeof child !== 'string';
+            }).map((child) => {
+                return child.toObject();
+            }),
+            attributes: this.attributeMap,
+            strings: this.children.filter((child) => {
+                return typeof child === 'string';
+            })
+        };
+    }
+}

package/build/system/server/dom/HTMLParser.d.ts

@@ -0,0 +1,21 @@
+import { DOMFragment } from "./DOMFragment.js";
+export declare class HTMLParser {
+    private readonly html;
+    private offset;
+    private context;
+    private state;
+    private tokenCurrent;
+    private fragment;
+    private attributeOpenQuote;
+    private attributeNameCurrent;
+    private attributeContext;
+    constructor(html: string);
+    private char;
+    private lastChar;
+    parse(): boolean;
+    private line;
+    private isLetter;
+    private isNumber;
+    dom(): DOMFragment;
+    private error;
+}

package/build/system/server/dom/HTMLParser.js

@@ -0,0 +1,204 @@
+import { DOMFragment } from "./DOMFragment.js";
+import { DOMNode } from "./DOMNode.js";
+export class HTMLParser {
+    constructor(html) {
+        this.offset = 0;
+        this.state = 'idle';
+        this.tokenCurrent = '';
+        this.fragment = new DOMFragment();
+        this.attributeOpenQuote = '"';
+        this.attributeNameCurrent = '';
+        this.attributeContext = null;
+        this.html = html;
+        this.context = this.fragment;
+        while (this.parse()) {
+            this.offset++;
+        }
+    }
+    char() {
+        return this.html.charAt(this.offset);
+    }
+    lastChar() {
+        return this.offset === this.html.length - 1;
+    }
+    parse() {
+        if (this.offset >= this.html.length) {
+            return false;
+        }
+        const char = this.char();
+        const charCode = char.charCodeAt(0);
+        if (this.state === 'idle') {
+            if (char === ' ') {
+                return true;
+            }
+            if (char === '<') {
+                this.state = 'tagStart';
+                this.tokenCurrent = '';
+                return true;
+            }
+            this.state = 'text';
+            this.tokenCurrent = char;
+        }
+        else if (this.state === 'tagStart') {
+            if (char === '/') {
+                this.state = 'tagClose';
+                return true;
+            }
+            if (this.isLetter(charCode)) {
+                this.state = 'tagOpen';
+                this.tokenCurrent = char;
+                return true;
+            }
+        }
+        else if (this.state === 'tagOpen') {
+            if (char === '\n') {
+                return true;
+            }
+            if (char === '/') {
+                if (this.tokenCurrent.length === 0) {
+                    throw this.error(`Unexpected tag closing sequence "</", expected opening tag`);
+                }
+                return true;
+            }
+            if (char === '>') {
+                if (this.tokenCurrent.length === 0) {
+                    throw this.error(`Found an empty HTML tag <>`);
+                }
+                const node = new DOMNode(this.tokenCurrent);
+                this.context.appendChild(node);
+                this.state = 'idle';
+                this.tokenCurrent = '';
+                if (!node.selfClosing) {
+                    this.context = node;
+                }
+                this.attributeContext = node;
+                return true;
+            }
+            if (char === ' ') {
+                if (this.tokenCurrent.length === 0) {
+                    return true;
+                }
+                this.state = 'attributeName';
+                const node = new DOMNode(this.tokenCurrent);
+                this.context.appendChild(node);
+                this.tokenCurrent = '';
+                if (!node.selfClosing) {
+                    this.context = node;
+                }
+                this.attributeContext = node;
+                return true;
+            }
+            if (char !== '_' && !this.isLetter(charCode) && (this.tokenCurrent.length > 0 && !this.isNumber(charCode))) {
+                throw this.error(`Expected a-Z after HTML opening tag`);
+            }
+            this.tokenCurrent += char;
+            return true;
+        }
+        else if (this.state === 'tagClose') {
+            if (char === '/') {
+                return true;
+            }
+            if (char === '>') {
+                if (this.tokenCurrent !== this.context.tagName) {
+                    throw this.error(`Found closing tag ${this.tokenCurrent}, expected ${this.context.tagName}`);
+                }
+                this.context = this.context.parentNode || this.fragment;
+                this.state = 'idle';
+            }
+            this.tokenCurrent += char;
+        }
+        else if (this.state === 'text') {
+            if (char === '<') {
+                this.state = 'tagStart';
+                this.context.appendChild(this.tokenCurrent);
+                this.tokenCurrent = '';
+                return true;
+            }
+            this.tokenCurrent += char;
+            if (this.lastChar() && this.tokenCurrent.length > 0) {
+                this.context.appendChild(this.tokenCurrent);
+            }
+        }
+        else if (this.state === 'attributeName') {
+            const boundsChar = char === ' ' || char === '\n' || char === '\t';
+            if (boundsChar || char === '=' || char === '>') {
+                if (char === '=') {
+                    this.state = 'attributeValueStart';
+                }
+                else if (char === '>') {
+                    this.state = 'idle';
+                }
+                if (this.tokenCurrent.length > 0) {
+                    if (this.attributeContext !== null && this.tokenCurrent.trim().length > 0) {
+                        this.attributeContext.setAttribute(this.tokenCurrent, true);
+                    }
+                    this.attributeNameCurrent = this.tokenCurrent;
+                    this.tokenCurrent = '';
+                    return true;
+                }
+            }
+            if (!boundsChar) {
+                this.tokenCurrent += char;
+            }
+        }
+        else if (this.state === 'attributeValueStart') {
+            if (char === '"' || char === "'") {
+                this.state = 'attributeValue';
+                this.attributeOpenQuote = char;
+                return true;
+            }
+        }
+        else if (this.state === 'attributeValue') {
+            if (char === this.attributeOpenQuote) {
+                if (this.attributeContext) {
+                    this.attributeContext.setAttribute(this.attributeNameCurrent, this.tokenCurrent);
+                }
+                this.tokenCurrent = '';
+                this.attributeNameCurrent = '';
+                this.state = 'attributeEnd';
+                return true;
+            }
+            this.tokenCurrent += char;
+        }
+        else if (this.state === 'attributeEnd') {
+            if (char === '>') {
+                this.state = 'idle';
+                return true;
+            }
+            if (char === ' ' || char === '\n') {
+                this.state = 'attributeName';
+                return true;
+            }
+            else if (char === '/') {
+                return true;
+            }
+            else {
+                throw this.error(`Unexpected character ${char} after attribute value`);
+            }
+        }
+        return true;
+    }
+    line() {
+        return this.html.substring(0, this.offset).split('\n').length;
+    }
+    isLetter(charCode) {
+        const isLowerCase = charCode > 96 && charCode < 123;
+        if (isLowerCase) {
+            return true;
+        }
+        const isUpperCase = charCode > 64 && charCode < 91;
+        if (isUpperCase) {
+            return true;
+        }
+        return false;
+    }
+    isNumber(charCode) {
+        return charCode > 47 && charCode < 58;
+    }
+    dom() {
+        return this.fragment;
+    }
+    error(message) {
+        return new Error(`HTMLParser: ${message}\nLine ${this.line()}\nHTML:\n${this.html}\n`);
+    }
+}

package/index.ts

@@ -0,0 +1,4 @@
+import { Application } from "@structured/Application.js";
+import { config } from './Config.js';
+
+new Application(config);

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "structured-fw",
+  "displayName": "Structured framework",
+  "description": "Production-tested Node.js framework for creating performant server-side rendered web apps and APIs, with a sane amount of client side abstraction.",
+  "author": {
+    "name": "Julijan Andjelic",
+    "email": "julijan.andjelic@gmail.com"
+  },
+  "type": "module",
+  "main": "build/index",
+  "version": "0.7.2",
+  "scripts": {
+    "develop": "tsc --watch",
+    "startDev": "cd build && nodemon --watch '../app/**/*' --watch '../build/**/*' -e js,html,css index.js",
+    "start": "cd build && node index.js",
+    "postinstall": "tsc"
+  },
+  "bin": {
+    "structured": "./bin/structured"
+  },
+  "devDependencies": {
+    "@types/mime-types": "^2.1.4",
+    "@types/node": "^22.9.3",
+    "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "handlebars": "^4.7.8",
+    "mime-types": "^3.0.0",
+    "ts-md5": "^1.3.1"
+  }
+}

package/system/Helpers.ts

@@ -0,0 +1,97 @@
+import { HelperDelegate } from "handlebars";
+import { attributeValueToString, objectEach } from "./Util.js";
+
+const helpers: Record<string, HelperDelegate> = {
+
+    // {{{htmlTag tagName}}} outputs <tagName></tagName>
+    htmlTag : function(...args) {
+        // output a tag with given name
+        return `<${args[0]}></${args[0]}>`;
+    },
+
+    // {{{layoutComponent componentName data}}} outputs <tagName data-use="data.key0,data.key1..."></tagName>
+    layoutComponent: function(...args) {
+        // output a tag with given name
+        if (args.length < 2 || args.length > 4) {
+            console.warn('layoutComponent expects 1 - 3 arguments (componentName, data?, attributes?) got ' + (args.length - 1));
+        }
+
+        const argsUsed = args.slice(0, args.length - 1);
+
+        const componentName = argsUsed[0];
+        const data = argsUsed[1];
+        const attributes = argsUsed[2];
+        const dataAttributes: Array<string> = [];
+        let attributesString = '';
+
+        if (attributes) {
+            // got attributes
+            if (attributes) {
+                const attrNames = Object.keys(attributes);
+                attributesString = attrNames.map((attrName) => {
+                    const val = attributes[attrName];
+                    if (typeof val === 'string' || typeof val === 'number') {
+                        return `${attrName}="${val}"`
+                    }
+                    if (val === true) {
+                        return attrName;
+                    }
+                    return null;
+                }).filter((val) => val !== null).join(' ');
+            }
+        }
+
+        if (data) {
+            objectEach(data, (key, val) => {
+                dataAttributes.push(`data-${key as string}="${attributeValueToString(key as string, val)}"`);
+            });
+        }
+        
+        return `<${componentName} ${dataAttributes.length > 0 ? dataAttributes.join(' ') : ''} ${attributesString}></${componentName}>`;
+    },
+
+    // JSON.stringify the given object
+    json: function(...args) {
+        if (args.length > 1) {
+            if (typeof args[0] === 'object' && args[0] !== null) {
+                return JSON.stringify(args[0]);
+            }
+            return '';
+        }
+        return '';
+    },
+
+    // used as <div {{{attr [attrName] [attrValue]}}}></div>
+    // returns data-[attrName]="attributeValueToString([attrValue])"
+    // valu can be of any type and will be preserved since it is encoded using attributeValueToString
+    attr: function(key: string, val: any) {
+        return `data-${key}="${attributeValueToString(key, val)}"`;
+    },
+
+    // converts newline characters to <br>
+    nl2br: function(...args) {
+        if (args.length === 1 && 'fn' in args[0]) {
+            // block
+            return (args[0].fn(this) || '').replaceAll('\n', '<br>');
+        }
+        if (args.length === 2) {
+            if (typeof args[0] !== 'string') {return '';}
+            return args[0].replaceAll('\n', '<br>');
+        }
+        return '';
+    },
+
+    // preserve indentation in given string by replacing space with &nbsp;
+    indent: function(...args) {
+        if (args.length === 1 && 'fn' in args[0]) {
+            // block
+            return args[0].fn(this).replaceAll(' ', '&nbsp;').replaceAll('\t', '&nbsp;'.repeat(4));
+        }
+        if (args.length === 2) {
+            return args[0].replaceAll(' ', '&nbsp;').replaceAll('\t', '&nbsp;'.repeat(4));
+        }
+        return '';
+    }
+}
+
+export default helpers;

package/system/Symbols.ts

@@ -0,0 +1,6 @@
+// all framework related data will be stored under this session key
+export const symbolSession: unique symbol = Symbol('session');
+
+export const symbolAny: unique symbol = Symbol('*');
+
+export const symbolArrays: unique symbol = Symbol.for('arrays');