@tymber/common 0.0.1-alpha.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2025-present Damien ARRACHEQUESNE
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+<h1>Common module of the Tymber framework</h1>
+
+The internals of the framework.
+
+**Table of contents**
+
+<!-- TOC -->
+  * [Installation](#installation)
+  * [Usage](#usage)
+  * [License](#license)
+<!-- TOC -->
+
+## Installation
+
+```
+npm i @tymber/common
+```
+
+## Usage
+
+```ts
+import * as pg from "pg";
+import { PostgresDB } from "@tymber/postgres";
+import { App, toNodeHandler } from "@tymber/common";
+import { CoreModule } from "@tymber/core";
+import { createServer } from "node:http";
+
+const pgPool = new pg.Pool({
+  user: "postgres",
+  password: "changeit",
+});
+
+const db = new PostgresDB(pgPool);
+
+const app = await App.create(db, [
+  CoreModule
+]);
+
+const httpServer = createServer(toNodeHandler(app.fetch));
+
+httpServer.listen(8080);
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/App.d.ts

@@ -0,0 +1,17 @@
+import { type Module } from "./Module.js";
+import { Component } from "./Component.js";
+export declare class App {
+    private readonly assets;
+    private readonly viewRenderer;
+    private readonly router;
+    private readonly middlewares;
+    private constructor();
+    static create({ components, modules, }: {
+        components: Component[];
+        modules: Module[];
+    }): Promise<App>;
+    fetch(req: Request): Promise<Response>;
+    private renderHttp404Error;
+    private renderHttp500Error;
+    close(): Promise<void>;
+}

package/dist/App.js

@@ -0,0 +1,236 @@
+import { Router } from "./Router.js";
+import { ModuleDefinitions, } from "./Module.js";
+import { Middleware } from "./Middleware.js";
+import { parseCookieHeader } from "./contrib/cookie.js";
+import { HttpRedirectCode } from "./HttpContext.js";
+import { computeBaseUrl } from "./utils/computeBaseUrl.js";
+import { ViewRenderer } from "./ViewRenderer.js";
+import { computeContentType } from "./utils/computeContentType.js";
+import { loadModules } from "./utils/loadModules.js";
+import { BaseI18nService } from "./I18nService.js";
+import { BaseTemplateService } from "./TemplateService.js";
+import { runMigrations } from "./utils/runMigrations.js";
+import { createDebug } from "./utils/createDebug.js";
+import { DB } from "./DB.js";
+import { isProduction } from "./utils/isProduction.js";
+import { Component, ComponentFactory } from "./Component.js";
+import { PubSubService } from "./PubSubService.js";
+import { FS } from "./utils/fs.js";
+import { EnvironmentBasedConfigService } from "./ConfigService.js";
+import { snakeToCamelCase } from "./utils/snakeToCamelCase.js";
+const debug = createDebug("App");
+function createRouter(modules) {
+    const router = new Router();
+    for (const module of modules) {
+        for (const { method, path, handler } of module.endpoints) {
+            router.registerRoute(method, path, handler);
+        }
+        for (const { method, path, handler } of module.views) {
+            router.registerRoute(method, path, handler);
+        }
+        for (const { method, path, handler } of module.adminEndpoints) {
+            router.registerRoute(method, path, handler);
+        }
+        for (const { method, path, handler } of module.adminViews) {
+            router.registerRoute(method, path, handler);
+        }
+    }
+    return router;
+}
+function parseQueryParams(url) {
+    const query = Object.create(null);
+    url.searchParams.forEach((value, key) => {
+        query[snakeToCamelCase(key)] = value;
+    });
+    return query;
+}
+export class App {
+    assets;
+    viewRenderer;
+    router;
+    middlewares = [];
+    constructor(modules, assets, viewRenderer) {
+        this.assets = assets;
+        this.viewRenderer = viewRenderer;
+        this.router = createRouter(modules);
+        for (const module of modules) {
+            this.middlewares.push(...module.middlewares);
+        }
+        this.fetch = this.fetch.bind(this);
+    }
+    static async create({ components, modules, }) {
+        const db = components.find((c) => {
+            return c instanceof DB;
+        });
+        if (!db) {
+            throw new Error("no DB component found");
+        }
+        debug("starting app in %s mode", isProduction ? "production" : "development");
+        const componentFactory = new ComponentFactory();
+        let viewRenderer;
+        componentFactory.register(PubSubService);
+        componentFactory.register(EnvironmentBasedConfigService);
+        componentFactory.register(BaseI18nService);
+        componentFactory.register(BaseTemplateService);
+        componentFactory.register(ViewRenderer, (instance) => {
+            viewRenderer = instance;
+        });
+        debug("loading modules");
+        const moduleDefinitions = await loadModules(componentFactory, modules);
+        const allComponents = componentFactory.build(new ModuleDefinitions(moduleDefinitions), ...components);
+        debug("running migrations");
+        await runMigrations(db, moduleDefinitions);
+        debug("initializing all components");
+        await Promise.all(allComponents.map((component) => component.init()));
+        const assets = new Map();
+        for (const module of modules) {
+            if (!module.assetsDir) {
+                continue;
+            }
+            try {
+                for (const filename of await FS.readDirRecursively(FS.join(module.assetsDir, "static"))) {
+                    assets.set("/static/" + filename, FS.join(module.assetsDir, "static", filename));
+                }
+            }
+            catch (e) { }
+        }
+        const app = new App(moduleDefinitions, assets, viewRenderer);
+        app.close = () => {
+            debug("closing all components");
+            return Promise.all(components.map((component) => component.close())).then();
+        };
+        return app;
+    }
+    async fetch(req) {
+        const url = new URL(req.url, "http://localhost");
+        const locale = this.viewRenderer.computeLocale(req);
+        const ctx = {
+            startedAt: new Date(),
+            method: req.method,
+            path: url.pathname,
+            query: parseQueryParams(url),
+            headers: req.headers,
+            cookies: parseCookieHeader(req.headers.get("cookie") || ""),
+            abortSignal: req.signal,
+            locale,
+            responseHeaders: new Headers(),
+            render: async (view, data = {}) => {
+                try {
+                    return this.viewRenderer.render(ctx, view, data);
+                }
+                catch (e) {
+                    return this.renderHttp500Error(ctx, e);
+                }
+            },
+            redirect(path, code = HttpRedirectCode.HTTP_302_FOUND) {
+                const baseUrl = computeBaseUrl(ctx.headers);
+                // note: `Response.redirect()` does not allow to specify additional headers
+                return new Response(null, {
+                    status: code,
+                    headers: {
+                        Location: `${baseUrl}${path}`,
+                    },
+                });
+            },
+        };
+        if (ctx.path.startsWith("/static")) {
+            if (!this.assets.has(ctx.path)) {
+                return this.renderHttp404Error(ctx);
+            }
+            const contentType = computeContentType(ctx.path);
+            const absolutePath = this.assets.get(ctx.path);
+            debug("serving %s with content type %s", ctx.path, contentType);
+            return new Response(FS.createReadStream(absolutePath), {
+                headers: {
+                    "content-type": contentType,
+                    "cache-control": isProduction
+                        ? "public, max-age=31536000, immutable"
+                        : "no-cache",
+                },
+            });
+        }
+        // make a copy in case a middleware is removed
+        const middlewares = this.middlewares.slice();
+        for (const middleware of middlewares) {
+            try {
+                const httpRes = await middleware.handle(ctx);
+                if (httpRes) {
+                    ctx.responseHeaders.forEach((value, key) => {
+                        httpRes.headers.set(key, value);
+                    });
+                    return httpRes;
+                }
+            }
+            catch (e) {
+                return this.renderHttp500Error(ctx, e);
+            }
+        }
+        const route = this.router.findRoute(req.method, url.pathname);
+        if (!route) {
+            return this.renderHttp404Error(ctx);
+        }
+        ctx.pathParams = route.pathParams;
+        const contentType = req.headers.get("content-type");
+        if (contentType) {
+            if (contentType !== "application/json") {
+                // TODO support other content types
+                return Response.json({
+                    message: "unsupported media type",
+                }, {
+                    status: 415,
+                });
+            }
+            try {
+                ctx.payload = await req.json();
+            }
+            catch {
+                return Response.json({
+                    message: "invalid request body",
+                }, {
+                    status: 400,
+                });
+            }
+        }
+        try {
+            const httpRes = await route.handler.doHandle(ctx);
+            ctx.responseHeaders.forEach((value, key) => {
+                httpRes.headers.set(key, value);
+            });
+            return httpRes;
+        }
+        catch (e) {
+            return this.renderHttp500Error(ctx, e);
+        }
+    }
+    renderHttp404Error(ctx) {
+        const acceptHeader = ctx.headers.get("accept");
+        if (acceptHeader?.includes("text/html")) {
+            return this.viewRenderer.render(ctx, "404");
+        }
+        else {
+            return Response.json({
+                message: "resource not found",
+            }, {
+                status: 404,
+            });
+        }
+    }
+    renderHttp500Error(ctx, error) {
+        const acceptHeader = ctx.headers.get("accept");
+        if (acceptHeader?.includes("text/html")) {
+            return this.viewRenderer.render(ctx, "500", {
+                error,
+            });
+        }
+        else {
+            return Response.json({
+                message: "an unexpected error occurred",
+            }, {
+                status: 500,
+            });
+        }
+    }
+    close() {
+        return Promise.resolve();
+    }
+}

package/dist/Component.d.ts

@@ -0,0 +1,16 @@
+export declare const INJECT: unique symbol;
+export type Ctor<T> = new (...args: any[]) => T;
+type AbstractCtor<T> = abstract new (...args: any[]) => T;
+type Dependency = Ctor<Component> | AbstractCtor<Component>;
+export declare abstract class Component {
+    private __isComponent;
+    static [INJECT]: Dependency[];
+    init(): void | Promise<void>;
+    close(): void | Promise<void>;
+}
+export declare class ComponentFactory {
+    private readonly componentTree;
+    register<T extends Component>(ctor: Ctor<T>, onCreation?: (instance: T) => void): void;
+    build(...baseComponents: Component[]): Component[];
+}
+export {};

package/dist/Component.js

@@ -0,0 +1,116 @@
+import {} from "./Context.js";
+export const INJECT = Symbol("dependencies");
+export class Component {
+    __isComponent; // nominal typing
+    static [INJECT] = [];
+    init() { }
+    close() { }
+}
+function isSubclass(subclass, superclass) {
+    return superclass.prototype.isPrototypeOf(subclass.prototype);
+}
+function customConstructor(ctor, onCreation) {
+    return class extends ctor {
+        constructor(...args) {
+            super(...args);
+            onCreation(this);
+        }
+    };
+}
+export class ComponentFactory {
+    componentTree = [];
+    register(ctor, onCreation) {
+        if (onCreation) {
+            ctor = customConstructor(ctor, onCreation);
+        }
+        let level = 0;
+        // find place in the tree
+        for (const node of this.componentTree) {
+            for (const dependency of node.dependencies) {
+                if (ctor === dependency || isSubclass(ctor, dependency)) {
+                    level = Math.max(level, node.level + 1);
+                }
+            }
+        }
+        // move dependencies at the bottom
+        // @ts-expect-error
+        const dependencies = (ctor[INJECT] || []);
+        for (const node of this.componentTree) {
+            for (const dependency of dependencies) {
+                if (node.ctor === dependency || isSubclass(node.ctor, dependency)) {
+                    node.level = Math.max(node.level, level + 1);
+                }
+            }
+        }
+        this.componentTree.push({
+            ctor,
+            dependencies,
+            level,
+        });
+    }
+    build(...baseComponents) {
+        const components = [...baseComponents];
+        const proxyHandler = {
+            get(target, prop) {
+                const method = target[prop];
+                if (typeof method !== "function") {
+                    return method;
+                }
+                return function (...args) {
+                    const isTracingEnabled = args.length > 0 && args[0].tracing?.enabled;
+                    if (!isTracingEnabled) {
+                        return method.apply(target, args);
+                    }
+                    const ctx = args[0];
+                    const span = {
+                        component: target.constructor.name,
+                        method: prop,
+                        startedAt: Date.now(),
+                        duration: -1,
+                        isSuccess: false,
+                    };
+                    ctx.tracing?.spans.push(span);
+                    function completeSpan() {
+                        span.duration = Date.now() - span.startedAt;
+                    }
+                    try {
+                        const result = method.apply(target, args);
+                        if (isPromise(result)) {
+                            return result
+                                .then((output) => {
+                                span.isSuccess = true;
+                                return output;
+                            })
+                                .finally(() => completeSpan());
+                        }
+                        span.isSuccess = true;
+                        return result;
+                    }
+                    finally {
+                        completeSpan();
+                    }
+                };
+            },
+        };
+        this.componentTree.sort((a, b) => b.level - a.level);
+        // TODO do not instantiate components that are not used in the tree
+        for (const node of this.componentTree) {
+            const deps = node.dependencies.map((ctor) => {
+                const availableDeps = components.filter((component) => component instanceof ctor);
+                if (availableDeps.length === 0) {
+                    throw `unresolved dependency ${ctor.name} for ${node.ctor.name}`;
+                }
+                return availableDeps[availableDeps.length - 1];
+            });
+            const component = new node.ctor(...deps);
+            components.push(new Proxy(component, proxyHandler));
+        }
+        return components;
+    }
+}
+function isPromise(obj) {
+    return (!!obj &&
+        typeof obj === "object" &&
+        typeof obj.then === "function" &&
+        typeof obj.catch === "function");
+}

package/dist/ConfigService.d.ts

@@ -0,0 +1,31 @@
+import { Component } from "./Component.js";
+import { type Context } from "./Context.js";
+type ConfigType = "string" | "string[]" | "number" | "boolean";
+interface ConfigDefinition {
+    key: string;
+    type: ConfigType;
+    defaultValue?: any;
+    shouldObfuscate?: boolean;
+}
+interface ConfigDefinitionWithValue extends ConfigDefinition {
+    value: any;
+}
+type ConfigValues = Record<string, any>;
+interface ConfigHandler {
+    configDefinitions: ConfigDefinition[];
+    handler: (config: ConfigValues) => void | Promise<void>;
+    previousConfigHash: string;
+}
+export declare abstract class ConfigService extends Component {
+    protected handlers: ConfigHandler[];
+    subscribe(configDefinitions: ConfigDefinition[], handler: (config: ConfigValues) => void | Promise<void>): void;
+    init(): Promise<void>;
+    protected notifyConsumers(ctx: Context): Promise<void>;
+    getDefinitions(): ConfigDefinition[];
+    getCurrentConfig(ctx: Context): Promise<ConfigDefinitionWithValue[]>;
+    protected abstract getCurrentValues(ctx: Context): Promise<ConfigValues>;
+}
+export declare class EnvironmentBasedConfigService extends ConfigService {
+    getCurrentValues(): Promise<Record<string, any>>;
+}
+export {};

package/dist/ConfigService.js

@@ -0,0 +1,75 @@
+import { hash } from "node:crypto";
+import { Component } from "./Component.js";
+import { emptyContext } from "./Context.js";
+export class ConfigService extends Component {
+    handlers = [];
+    subscribe(configDefinitions, handler) {
+        this.handlers.push({
+            configDefinitions,
+            handler,
+            previousConfigHash: "",
+        });
+    }
+    init() {
+        return this.notifyConsumers(emptyContext());
+    }
+    async notifyConsumers(ctx) {
+        const values = await this.getCurrentValues(ctx);
+        for (const elem of this.handlers) {
+            const config = {};
+            for (const { key, defaultValue } of elem.configDefinitions) {
+                config[key] = values[key] || defaultValue;
+            }
+            const configHash = hash("sha256", JSON.stringify(config));
+            if (configHash !== elem.previousConfigHash) {
+                elem.previousConfigHash = configHash;
+                await elem.handler(config);
+            }
+        }
+    }
+    getDefinitions() {
+        return this.handlers.flatMap((elem) => elem.configDefinitions);
+    }
+    async getCurrentConfig(ctx) {
+        const values = await this.getCurrentValues(ctx);
+        const config = [];
+        for (const handler of this.handlers) {
+            for (const { key, type, defaultValue, shouldObfuscate, } of handler.configDefinitions) {
+                config.push({
+                    key,
+                    type,
+                    defaultValue,
+                    value: values[key] ?? defaultValue,
+                    shouldObfuscate,
+                });
+            }
+        }
+        return config;
+    }
+}
+function formatValue(type, value) {
+    switch (type) {
+        case "string":
+            return value;
+        case "string[]":
+            return value.split(",");
+        case "number":
+            return parseInt(value, 10);
+        case "boolean":
+            return value === "1";
+    }
+}
+export class EnvironmentBasedConfigService extends ConfigService {
+    getCurrentValues() {
+        const availableKeys = Object.keys(process.env);
+        const values = {};
+        for (const handler of this.handlers) {
+            for (const { key, type } of handler.configDefinitions) {
+                if (availableKeys.includes(key)) {
+                    values[key] = formatValue(type, process.env[key] ?? "");
+                }
+            }
+        }
+        return Promise.resolve(values);
+    }
+}

package/dist/Context.d.ts

@@ -0,0 +1,41 @@
+import { type Brand } from "./utils/types.js";
+export type InternalUserId = Brand<bigint, "InternalUserId">;
+export type UserId = Brand<string, "UserId">;
+export type InternalGroupId = Brand<bigint, "InternalGroupId">;
+export type GroupId = Brand<string, "GroupId">;
+export type Role = Brand<number, "Role">;
+export type AdminUserId = Brand<number, "AdminUserId">;
+export interface ConnectedUser {
+    internalId: InternalUserId;
+    id: UserId;
+    firstName: string;
+    lastName: string;
+    email: string;
+    groups: Array<{
+        internalId: InternalGroupId;
+        id: GroupId;
+        label: string;
+        role: Role;
+    }>;
+}
+export interface Admin {
+    id: AdminUserId;
+}
+export interface Span {
+    component: string;
+    method: string;
+    startedAt: number;
+    duration: number;
+    isSuccess: boolean;
+}
+export interface Context {
+    startedAt: Date;
+    tx?: any;
+    user?: ConnectedUser;
+    admin?: Admin;
+    tracing: {
+        enabled: boolean;
+        spans: Array<Span>;
+    };
+}
+export declare function emptyContext(): Context;

package/dist/Context.js

@@ -0,0 +1,10 @@
+import {} from "./utils/types.js";
+export function emptyContext() {
+    return {
+        startedAt: new Date(),
+        tracing: {
+            enabled: false,
+            spans: [],
+        },
+    };
+}

package/dist/DB.d.ts

@@ -0,0 +1,15 @@
+import { Component } from "./Component.js";
+import { type Context } from "./Context.js";
+import { Statement } from "./utils/sql.js";
+export declare abstract class DB extends Component {
+    abstract readonly name: string;
+    abstract query<T extends Record<string, any>>(ctx: Context, query: Statement): Promise<T[]>;
+    abstract run(ctx: Context, query: Statement): Promise<{
+        affectedRows: number;
+    }>;
+    abstract exec(ctx: Context, query: Statement): Promise<void>;
+    abstract startTransaction(ctx: Context, fn: () => Promise<void>): void | Promise<void>;
+    abstract createMigrationsTable(ctx: Context): Promise<void>;
+}
+export declare class DuplicateKeyError extends Error {
+}

package/dist/DB.js

@@ -0,0 +1,7 @@
+import { Component } from "./Component.js";
+import {} from "./Context.js";
+import { Statement } from "./utils/sql.js";
+export class DB extends Component {
+}
+export class DuplicateKeyError extends Error {
+}

package/dist/Endpoint.d.ts

@@ -0,0 +1,21 @@
+import { type HttpContext } from "./HttpContext.js";
+import { Handler } from "./Handler.js";
+declare abstract class BaseEndpoint extends Handler {
+    protected pathParamsSchema?: unknown;
+    protected querySchema?: unknown;
+    protected payloadSchema?: unknown;
+    private validatePathParams?;
+    private validateQuery?;
+    private validatePayload?;
+    doHandle(ctx: HttpContext): Response | Promise<Response>;
+    protected badRequest(message: string, details?: any): import("undici-types").Response;
+}
+export declare abstract class Endpoint extends BaseEndpoint {
+    private _endpointBrand;
+    doHandle(ctx: HttpContext): Response | Promise<Response>;
+}
+export declare abstract class AdminEndpoint extends BaseEndpoint {
+    private _adminEndpointBrand;
+    doHandle(ctx: HttpContext): Response | Promise<Response>;
+}
+export {};