npm - structured-fw - Versions diffs - 1.4.0 → 1.6.0 - Mend

structured-fw 1.4.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

package/README.md +64 -23
package/build/system/EventEmitter.js +4 -6
package/build/system/StructuredError.d.ts +8 -0
package/build/system/StructuredError.js +40 -0
package/build/system/bin/structured.js +1 -2
package/build/system/client/ClientApplication.js +3 -2
package/build/system/client/ClientComponent.js +21 -13
package/build/system/client/DataStore.js +2 -4
package/build/system/client/DataStoreView.js +3 -1
package/build/system/client/NetRequest.js +7 -2
package/build/system/server/Application.d.ts +3 -2
package/build/system/server/Application.js +19 -7
package/build/system/server/Component.js +15 -7
package/build/system/server/Components.js +3 -2
package/build/system/server/Document.d.ts +1 -1
package/build/system/server/Document.js +10 -7
package/build/system/server/DocumentHead.js +9 -8
package/build/system/server/FormValidation.js +121 -123
package/build/system/server/Handlebars.js +2 -4
package/build/system/server/Layout.d.ts +2 -2
package/build/system/server/Layout.js +4 -0
package/build/system/server/Request.d.ts +1 -11
package/build/system/server/Request.js +12 -269
package/build/system/server/RequestContext.d.ts +43 -0
package/build/system/server/RequestContext.js +322 -0
package/build/system/server/Session.js +3 -2
package/build/system/server/dom/DOMNode.js +11 -7
package/build/system/server/dom/HTMLParser.js +10 -8
package/build/system/types/application.types.d.ts +1 -1
package/build/system/types/component.types.d.ts +1 -1
package/build/system/types/request.types.d.ts +1 -19
package/package.json +2 -1

package/README.md CHANGED Viewed

@@ -29,6 +29,13 @@ npm init -y
 npm install @types/node
 ```
+## Set type to "module" in package.json
+```
+...
+  "type": "module",
+...
+```
 *If you have TypeScript installed globally then you can skip the following*\
 `npm install --save-dev typescript`
@@ -127,13 +134,14 @@ new Application(config);
     - `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
+    - `requestHandleError` - runs if there were errors while serving the request. Callback's result is sent as a response - a good use case is showing a "server error" page. Callback receives `RequestContext` as the first argument
     - `afterRoutes` - runs after all routes are loaded from `StructuredConfig.routes.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
-    - `pageNotFound` - runs when a request is received for which there is no registered request handler (route), and the requested URL is not an asset. Callback receives `RequestContext` as the first argument
+    - `pageNotFound` - runs when a request is received for which there is no registered request handler (route), and the requested URL is not an asset. Callback's result is sent as a response - a good use case is showing a 404 page. Callback receives `RequestContext` as the first argument
     - **Callback to any of the `ApplicationEvents` is expected to be an async function**
 - `importEnv<T extends LooseObject>(smartPrimitives: boolean = true): T` - import ENV variables that start with `StructuredConfig.envPrefix`_ (if envPrefix is omitted from config, all ENV variables are returned). It is a generic method so that you can specify the expected return type. If `smartPrimitives = true` importEnv will convert the ENV values to type it feels is appropriate:
     - numeric values -> `number`
@@ -258,44 +266,67 @@ Route file name has no effect on how the route (request handler) behaves, the on
 RequestContext is created for every received request. It contains all the data related to the request, as well as data you include in `RequestContextData`.
 All request handlers receive a `RequestContext` as the first argument. Your component server side part also receives `RequestContext` as the second argument.
 ```
-type RequestContext<Body extends LooseObject | undefined = LooseObject> = {
-    request: IncomingMessage,
-    response: ServerResponse,
-    args: URIArguments,
-    handler: null|RequestHandler,
+class RequestContext<Body extends LooseObject | undefined = LooseObject> = {
+    app: Application;
+    uri: string;
+    request: IncomingMessage;
+    response: ServerResponse;
-    cookies: Record<string, string>,
+    // captured URI arguments
+    // for example if the requested URI was /users/8 and the pattern was /users/(userId:num)
+    // args will be { userId: 8 }
+    args: URIArguments;
+    // request cookies parsed into an object
+    cookies: Record<string, string>;
     // POSTed data, parsed to object
-    body?: LooseObject,
+    body?: LooseObject;
-    bodyRaw?: Buffer,
+    bodyRaw?: Buffer;
     // files extracted from request body
-    files?: Record<string, RequestBodyRecordValue>,
+    files?: Record<string, RequestBodyRecordValue>;
     // user defined data
-    data: RequestContextData,
+    data: RequestContextData;
-    // if session is started and user has visited any page
-    sessionId?: string,
+    // defined if session is started and user has visited any page
+    sessionId?: string;
-    // true if x-requested-with header is received and it equals 'xmlhttprequest'
-    isAjax: boolean,
+    // true if x-requested-with header value is 'xmlhttprequest'
+    isAjax: () => boolean;
     // time when request was received (unix timestamp in milliseconds)
-    timeStart: number,
+    timeStart: number;
+    // URL GET arguments, for example if the URI isss /users?id=8
+    // getArgs would be { id: '8' }
+    getArgs: PostedDataDecoded;
+    // create a Document and load given component
+    createDocument: (title: string, component: string, data?: LooseObject) => Promise<Document>;
-    // URL GET arguments
-    getArgs: PostedDataDecoded,
+    // create a Document using provided layout
+    layoutDocument: layoutDocument(
+        layout: Layout,
+        title: string,
+        component: string,
+        data?: LooseObject,
+        attributes?: Record<string, string>
+    ) => Promise<Document>;
     // send given data as a response
-    respondWith: (data: any) => Promise<void>,
+    respondWith: (data: any) => Promise<void>;
-    // redirect to given url, with given statusCode
-    redirect: (to: string, statusCode?: number) => void,
+    // redirect to given URI, with given statusCode (default 302)
+    redirect: (to: string, statusCode?: number) => void;
-    // show a 404 page
+    // show a blank page and send a 404 status code
+    // to show a custom page, text, json, etc... register an event handler for pageNotFound event
+    // for example:
+    // app.on('pageNotFound', (ctx) => { return await ctx.createDocument('Page not found', 'NotFound'); })
     show404: () => Promise<void>
 }
 ```
@@ -371,6 +402,15 @@ app.request.on('GET', '/home', async (ctx) => {
 });
 ```
+Above code could be simplified using RequestContext.createDocument method as:
+```
+app.request.on('GET', '/home', async (ctx) => {
+    return await ctx.createDocument('Home', 'Home');
+});
+```
+Much shorter, but slightly confusing due to bad example (both arguments being 'Home'). First argument is the document title, second argument is the name of the component you want to load.
 > [!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:
@@ -445,7 +485,8 @@ That was the simplest possible example, let's make it more interesting by adding
 Create a new file `/app/views/HelloWorld/HelloWorld.ts` (server side component code):
 ```
 import { Application } from 'structured-fw/Application';
-import { ComponentScaffold, RequestContext } from 'structured-fw/Types';
+import { ComponentScaffold } from 'structured-fw/Types';
+import { RequestContext } from 'structured-fw/RequestContext';
 type ComponentInput = {
     name: string,

package/build/system/EventEmitter.js CHANGED Viewed

@@ -1,10 +1,8 @@
 export class EventEmitter {
-    constructor() {
-        this.listeners = {};
-        this.destroyed = false;
-        this.ready = false;
-        this.eventQueue = [];
-    }
+    listeners = {};
+    destroyed = false;
+    ready = false;
+    eventQueue = [];
     on(eventName, callback) {
         if (this.destroyed) {
             return;

package/build/system/StructuredError.d.ts ADDED Viewed

@@ -0,0 +1,8 @@
+export declare class StructuredError extends Error {
+    causedBy: StructuredError | null;
+    stack: string | undefined;
+    constructor(message: string | Error, cause: StructuredError | Error | null);
+    toString(depth?: number): string;
+    log(depth?: number): void;
+    private formatLines;
+}

package/build/system/StructuredError.js ADDED Viewed

@@ -0,0 +1,40 @@
+export class StructuredError extends Error {
+    causedBy;
+    stack;
+    constructor(message, cause) {
+        super(typeof message === 'string' ? message : message.message);
+        if (message instanceof Error) {
+            this.stack = message.stack;
+        }
+        if (cause === null) {
+            this.causedBy = null;
+        }
+        else {
+            this.causedBy = cause instanceof StructuredError ? cause : new StructuredError(cause, null);
+        }
+    }
+    toString(depth = 0) {
+        const errorParts = [this.message];
+        if (this.stack) {
+            errorParts.push('Stack trace:');
+            errorParts.push(this.stack);
+        }
+        if (this.causedBy !== null) {
+            errorParts.push('Originated from:');
+            errorParts.push(this.causedBy.toString(depth + 1));
+        }
+        return this.formatLines(errorParts.join('\n'), depth);
+    }
+    log(depth = 0) {
+        console.error(this.formatLines(this.toString(), depth));
+    }
+    formatLines(text, depth) {
+        const linesFormatted = [];
+        const lines = text.split('\n');
+        const prepend = '  '.repeat(depth);
+        lines.forEach((line) => {
+            linesFormatted.push(prepend + line);
+        });
+        return linesFormatted.join('\n');
+    }
+}

package/build/system/bin/structured.js CHANGED Viewed

@@ -64,11 +64,10 @@ function createTsconfig() {
                 "moduleResolution": "node16",
                 "outDir": "./build",
                 "module": "Node16",
-                "target": "ES2021",
+                "target": "es2022",
                 "allowSyntheticDefaultImports": true,
                 "preserveSymlinks": true,
                 "removeComments": true,
-                "baseUrl": ".",
                 "rootDir": ".",
                 paths
             },

package/build/system/client/ClientApplication.js CHANGED Viewed

@@ -1,9 +1,10 @@
 import { DataStore } from './DataStore.js';
 import { ClientComponent } from './ClientComponent.js';
 export class ClientApplication {
+    root;
+    store = new DataStore();
+    initializers = {};
     constructor() {
-        this.store = new DataStore();
-        this.initializers = {};
         this.loadInitializers();
         this.root = new ClientComponent(null, 'root', document.body, this);
     }

package/build/system/client/ClientComponent.js CHANGED Viewed

@@ -4,21 +4,29 @@ import { Net } from './Net.js';
 import { NetRequest } from './NetRequest.js';
 import { EventEmitter } from '../EventEmitter.js';
 export class ClientComponent extends EventEmitter {
+    name;
+    children = [];
+    parent;
+    domNode;
+    isRoot;
+    root;
+    store;
+    app;
+    net = new Net();
+    initializerExecuted = false;
+    fn;
+    destroyed = false;
+    redrawRequest = null;
+    bound = [];
+    conditionals = [];
+    conditionalCallbacks = {};
+    conditionalClassNames = [];
+    refs = {};
+    refsArray = {};
+    isReady = false;
+    data = {};
     constructor(parent, name, domNode, app) {
         super();
-        this.children = [];
-        this.net = new Net();
-        this.initializerExecuted = false;
-        this.destroyed = false;
-        this.redrawRequest = null;
-        this.bound = [];
-        this.conditionals = [];
-        this.conditionalCallbacks = {};
-        this.conditionalClassNames = [];
-        this.refs = {};
-        this.refsArray = {};
-        this.isReady = false;
-        this.data = {};
         this.name = name;
         this.domNode = domNode;
         if (parent === null) {

package/build/system/client/DataStore.js CHANGED Viewed

@@ -1,9 +1,7 @@
 import { equalDeep } from '../Util.js';
 export class DataStore {
-    constructor() {
-        this.data = {};
-        this.changeListeners = {};
-    }
+    data = {};
+    changeListeners = {};
     set(component, key, val, force = false, triggerListeners = true) {
         const componentId = component.getData('componentId');
         const oldValue = this.get(componentId, key);

package/build/system/client/DataStoreView.js CHANGED Viewed

@@ -1,6 +1,8 @@
 export class DataStoreView {
+    store;
+    component;
+    destroyed = false;
     constructor(store, component) {
-        this.destroyed = false;
         this.store = store;
         this.component = component;
     }

package/build/system/client/NetRequest.js CHANGED Viewed

@@ -1,7 +1,12 @@
 export class NetRequest {
+    xhr = new XMLHttpRequest();
+    method;
+    url;
+    headers;
+    responseType;
+    body;
+    requestSent = false;
     constructor(method, url, headers = {}, responseType = 'text', body) {
-        this.xhr = new XMLHttpRequest();
-        this.requestSent = false;
         this.method = method;
         this.url = url;
         this.headers = headers;

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

@@ -2,13 +2,13 @@ import { Server } from 'node:http';
 import { ApplicationEvents } from '../types/application.types.js';
 import { StructuredConfig } from '../types/structured.types.js';
 import { LooseObject } from '../types/general.types.js';
-import { RequestContext } from "../types/request.types.js";
 import { Document } from './Document.js';
 import { Components } from './Components.js';
 import { Session } from './Session.js';
 import { Request } from './Request.js';
 import { Handlebars } from './Handlebars.js';
 import { Cookies } from './Cookies.js';
+import { RequestContext } from './RequestContext.js';
 export declare class Application {
     readonly config: StructuredConfig;
     initialized: boolean;
@@ -25,13 +25,14 @@ 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 : E extends 'afterComponentsLoaded' ? Components : E extends 'serverStarted' ? Server : undefined) => void): void;
+    on<E extends ApplicationEvents>(evt: E, callback: (payload: E extends 'beforeRequestHandler' | 'afterRequestHandler' | 'beforeAssetAccess' | 'afterAssetAccess' | 'pageNotFound' | 'requestHandleError' ? RequestContext<RequestContextData> : 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;
     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;
+    directory(uri?: string): string;
     memoryUsage(): NodeJS.MemoryUsage;
     printMemoryUsage(): void;
 }

package/build/system/server/Application.js CHANGED Viewed

@@ -11,14 +11,19 @@ import { Request } from './Request.js';
 import { Handlebars } from './Handlebars.js';
 import { Cookies } from './Cookies.js';
 export class Application {
+    config;
+    initialized = false;
+    server = null;
+    listening = false;
+    eventEmitter = new EventEmitter();
+    cookies;
+    session;
+    request;
+    components;
+    handlebars = new Handlebars();
+    exportedRequestContextData = [];
+    data = {};
     constructor(config) {
-        this.initialized = false;
-        this.server = null;
-        this.listening = false;
-        this.eventEmitter = new EventEmitter();
-        this.handlebars = new Handlebars();
-        this.exportedRequestContextData = [];
-        this.data = {};
         this.config = config;
         this.cookies = new Cookies();
         this.session = new Session(this);
@@ -167,6 +172,13 @@ export class Application {
         }
         return false;
     }
+    directory(uri) {
+        const dir = path.resolve('../');
+        if (typeof uri === 'string') {
+            return path.resolve(dir, uri.startsWith('/') ? uri.substring(1) : uri);
+        }
+        return dir;
+    }
     memoryUsage() {
         return process.memoryUsage();
     }

package/build/system/server/Component.js CHANGED Viewed

@@ -2,14 +2,22 @@ import { Document } from './Document.js';
 import { attributeValueFromString, attributeValueToString, objectEach, toCamelCase } from '../Util.js';
 import { DOMFragment } from './dom/DOMFragment.js';
 import { EventEmitter } from '../EventEmitter.js';
+import { StructuredError } from '../StructuredError.js';
 export class Component extends EventEmitter {
+    id;
+    name;
+    document;
+    parent;
+    children = [];
+    path = [];
+    attributesRaw = {};
+    attributes = {};
+    dom;
+    data = {};
+    entry;
+    isRoot;
     constructor(name, node, parent, autoInit = true) {
         super();
-        this.children = [];
-        this.path = [];
-        this.attributesRaw = {};
-        this.attributes = {};
-        this.data = {};
         const isDocument = this instanceof Document;
         this.name = name;
         this.emitterReady();
@@ -96,7 +104,7 @@ export class Component extends EventEmitter {
                 await this.entry.serverPart.getData(Object.assign(importedParentData, this.attributes, data || {}), this.document.ctx, this.document.application, this) : {}) || {};
         }
         catch (e) {
-            throw new Error(`Error executing getData in component ${this.name}: ${e.message}`);
+            throw new StructuredError(`Error executing getData in component ${this.name}`, e);
         }
         if (data === undefined) {
             if (this.entry && this.entry.hasServerPart) {
@@ -271,7 +279,7 @@ export class Component extends EventEmitter {
             this.dom.innerHTML = this.document.application.handlebars.compile(html, data);
         }
         catch (e) {
-            throw new Error(`Error compiling Handlebars template in component ${this.name}, error: ${e.message}`);
+            throw new StructuredError(`Error compiling Handlebars template in component ${this.name}`, e);
         }
     }
 }

package/build/system/server/Components.js CHANGED Viewed

@@ -2,9 +2,10 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import * as path from 'node:path';
 import { stripBOM } from '../Util.js';
 export class Components {
+    config;
+    components = {};
+    componentNames = [];
     constructor(app) {
-        this.components = {};
-        this.componentNames = [];
         this.config = app.config;
     }
     loadComponents(relativeToPath) {

package/build/system/server/Document.d.ts CHANGED Viewed

@@ -1,10 +1,10 @@
 import { ServerResponse } from 'node:http';
 import { LooseObject } from '../types/general.types.js';
 import { Initializers } from '../types/component.types.js';
-import { RequestContext } from "../types/request.types.js";
 import { Application } from './Application.js';
 import { DocumentHead } from './DocumentHead.js';
 import { Component } from './Component.js';
+import { RequestContext } from './RequestContext.js';
 export declare class Document extends Component<{
     'componentCreated': Component;
     'beforeRender': void;

package/build/system/server/Document.js CHANGED Viewed

@@ -5,15 +5,18 @@ import path from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 export class Document extends Component {
+    head;
+    language = 'en';
+    application;
+    htmlTagAttributes = {};
+    bodyTagAttributes = {};
+    initializers = {};
+    initializersInitialized = false;
+    componentIds = [];
+    ctx;
+    appendHTML = '';
     constructor(app, title, ctx) {
         super('root');
-        this.language = 'en';
-        this.htmlTagAttributes = {};
-        this.bodyTagAttributes = {};
-        this.initializers = {};
-        this.initializersInitialized = false;
-        this.componentIds = [];
-        this.appendHTML = '';
         this.application = app;
         this.ctx = ctx;
         this.document = this;

package/build/system/server/DocumentHead.js CHANGED Viewed

@@ -1,13 +1,14 @@
 export class DocumentHead {
+    title;
+    js = [];
+    css = [];
+    custom = [];
+    charset = 'UTF-8';
+    favicon = {
+        image: null,
+        type: 'image/png'
+    };
     constructor(title) {
-        this.js = [];
-        this.css = [];
-        this.custom = [];
-        this.charset = 'UTF-8';
-        this.favicon = {
-            image: null,
-            type: 'image/png'
-        };
         this.title = title;
     }
     setTitle(title) {