@flancer32/teq-web 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.8.0] - 2026-03-17 - Flat runtime configuration and server startup alignment
+
+### Changed
+- Flattened runtime startup configuration to top-level fields `port`, `type`, and `tls` (without nested `server` branch).
+- Aligned server startup and runtime components with the updated flat runtime configuration contract.
+- Updated and verified the `ai/` consumer interface documentation to reflect current runtime usage patterns.
+- Updated package version metadata to `0.8.0`.
+
 ## [0.7.0] - 2026-03-16 - Runtime composition and agent interface alignment
 
 ### Changed

package/ai/abstractions.md

@@ -16,7 +16,7 @@ Main methods:
 
 `Fl32_Web_Back_Server$` is the built-in transport adapter around Node.js `http` and `http2`. On `start(cfg)` it locks the pipeline, creates the server instance, binds request events to the Pipeline Engine, and starts listening.
 
-Default transport settings come from `Fl32_Web_Back_Config_Runtime$` under the `server` branch. TLS values for `server.tls` are provided by the dedicated runtime configuration component `Fl32_Web_Back_Config_Runtime_Tls$`. Supported transport modes come from `Fl32_Web_Back_Enum_Server_Type$`:
+Default transport settings come from flat fields of `Fl32_Web_Back_Config_Runtime$` (`port`, `type`, `tls`). TLS values for `tls` are provided by the dedicated runtime configuration component `Fl32_Web_Back_Config_Runtime_Tls$`. Supported transport modes come from `Fl32_Web_Back_Enum_Server_Type$`:
 
 - `http`
 - `http2`

package/ai/examples/minimal-server.md

@@ -74,6 +74,6 @@ Consumer notes:
 - The composition root configures namespace roots once and resolves one application entry service.
 - Application modules do not construct collaborators directly and do not call `new` for DI-managed handlers or infrastructure services.
 - `server.start()` locks handler registration for the runtime lifetime of that server instance.
-- Built-in server defaults may also be supplied through `Fl32_Web_Back_Config_Runtime__Factory$` as `{server: {port, type, tls}}`, where `tls` is owned by the runtime component `Fl32_Web_Back_Config_Runtime_Tls$`.
+- Built-in server defaults may also be supplied through `Fl32_Web_Back_Config_Runtime__Factory$` as `{port, type, tls}`, where `tls` is owned by the runtime component `Fl32_Web_Back_Config_Runtime_Tls$`.
 - If your application already has its own transport layer, inject `Fl32_Web_Back_PipelineEngine$` and call `pipeline.onEventRequest(req, res)` from that adapter instead of using `Fl32_Web_Back_Server$`.
 - A correct PROCESS handler ends the response and then marks the context completed.

package/ai/overview.md

@@ -6,7 +6,7 @@ This package is not a general-purpose web framework. It does not define routing,
 
 The package assumes `@teqfw/di` and exposes its runtime surface through DI-managed modules under the `Fl32_Web_` namespace rooted at the published `src/` tree. In normal usage, application modules receive these dependencies through constructor injection and orchestrate them from DI-managed services rather than creating containers or wiring collaborators manually inside feature code.
 
-Runtime startup configuration is exposed through `Fl32_Web_Back_Config_Runtime$`. Its built-in transport branch is `config.server`, which contains `port`, `type`, and a `tls` branch backed by `Fl32_Web_Back_Config_Runtime_Tls$`.
+Runtime startup configuration is exposed through `Fl32_Web_Back_Config_Runtime$` with flat transport fields `config.port`, `config.type`, and `config.tls`. The `tls` field is backed by `Fl32_Web_Back_Config_Runtime_Tls$`.
 
 Use this package when external code needs one of these roles:
 

package/ai/rules.md

@@ -38,7 +38,7 @@
 
 - The package is designed for `@teqfw/di`.
 - Consumer code should resolve package modules through the `Fl32_Web_` namespace mapped to the package `src/` path.
-- Startup configuration for the built-in server should be supplied through `Fl32_Web_Back_Config_Runtime__Factory$` using the hierarchical configuration shape `{server: {...}}`.
-- TLS startup configuration belongs to the dedicated runtime component `Fl32_Web_Back_Config_Runtime_Tls$`, even though consumers read it through `config.server.tls`.
+- Startup configuration for the built-in server should be supplied through `Fl32_Web_Back_Config_Runtime__Factory$` using flat runtime fields (`{port, type, tls}`).
+- TLS startup configuration belongs to the dedicated runtime component `Fl32_Web_Back_Config_Runtime_Tls$`, even though consumers read it through `config.tls`.
 - Configure runtime values during startup only; once the runtime configuration is frozen for use, consumers must treat `Fl32_Web_Back_Config_Runtime$` and `Fl32_Web_Back_Config_Runtime_Tls$` as immutable read-only state.
 - Treat helper internals under deep implementation paths as non-essential unless the task specifically requires them. Preferred consumer entry points are the Pipeline Engine, Server, handler API, DTO factories, enums, and built-in handlers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flancer32/teq-web",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Server-side web request coordination infrastructure for TeqFW modular monolith applications.",
   "type": "module",
   "license": "Apache-2.0",

package/src/Back/Config/Runtime/Tls.mjs

@@ -57,7 +57,6 @@ export class Factory {
     constructor({cast}) {
         /**
          * @param {Fl32_Web_Back_Config_Runtime_Tls_Params} [params]
-         * @returns {Fl32_Web_Back_Config_Runtime_Tls}
          */
         this.configure = function (params = {}) {
             if (frozen) throw new Error('Runtime configuration is frozen.');
@@ -70,7 +69,6 @@ export class Factory {
             if (cfg.key === undefined && params.key !== undefined) {
                 cfg.key = cast.string(params.key);
             }
-            return proxy;
         };
 
         /**

package/src/Back/Config/Runtime.mjs

@@ -10,14 +10,6 @@ export const __deps__ = Object.freeze({
  * Backend runtime configuration.
  */
 export class Data {
-    /** @type {Fl32_Web_Back_Config_Runtime_Server|undefined} */
-    server;
-}
-
-/**
- * Built-in server runtime configuration subtree.
- */
-export class Server {
     /** @type {number|undefined} */
     port;
     /** @type {string|undefined} */
@@ -68,44 +60,38 @@ export class Factory {
      */
     constructor({ cast, SERVER_TYPE, tlsFactory }) {
         /**
-         * @param {Fl32_Web_Back_Config_Runtime_Params} [params]
-         * @returns {Fl32_Web_Back_Config_Runtime}
+         * @param {Fl32_Web_Back_Config_Runtime} [params]
          */
         this.configure = function (params = {}) {
             if (frozen) throw new Error('Runtime configuration is frozen.');
-            if (cfg.server === undefined) cfg.server = new Server();
-            if (cfg.server.port === undefined && params.server?.port !== undefined) {
-                cfg.server.port = cast.int(params.server.port);
+            if (cfg.port === undefined && params.port !== undefined) {
+                cfg.port = cast.int(params.port);
             }
-            if (cfg.server.type === undefined && params.server?.type !== undefined) {
-                cfg.server.type = cast.enum(params.server.type, SERVER_TYPE, { lower: true });
+            if (cfg.type === undefined && params.type !== undefined) {
+                cfg.type = cast.enum(params.type, SERVER_TYPE, { lower: true });
             }
-            if (params.server?.tls !== undefined) {
-                tlsFactory.configure(params.server.tls);
+            if (params.tls !== undefined) {
+                tlsFactory.configure(params.tls);
             }
-            return proxy;
         };
 
         /**
-         * @returns {Fl32_Web_Back_Config_Runtime}
+         * @returns {void}
          */
         this.freeze = function () {
-            if (frozen) return proxy;
-            if (cfg.server === undefined) cfg.server = new Server();
-            if (cfg.server.port === undefined) cfg.server.port = 3000;
-            if (cfg.server.type === undefined) cfg.server.type = SERVER_TYPE.HTTP;
+            if (frozen) return;
+            if (cfg.port === undefined) cfg.port = 3000;
+            if (cfg.type === undefined) cfg.type = SERVER_TYPE.HTTP;
             const tls = tlsFactory.freeze();
-            if (cfg.server.tls === undefined) cfg.server.tls = tls;
-            if (cfg.server.type === SERVER_TYPE.HTTPS && cfg.server.tls === undefined) {
+            if (cfg.tls === undefined) cfg.tls = tls;
+            if (cfg.type === SERVER_TYPE.HTTPS && cfg.tls === undefined) {
                 throw new Error('TLS configuration is required for HTTPS server type');
             }
-            if (cfg.server.type === SERVER_TYPE.HTTPS && (!cfg.server.tls.key || !cfg.server.tls.cert)) {
+            if (cfg.type === SERVER_TYPE.HTTPS && (!cfg.tls.key || !cfg.tls.cert)) {
                 throw new Error('TLS configuration is required for HTTPS server type');
             }
-            Object.freeze(cfg.server);
             Object.freeze(cfg);
             frozen = true;
-            return proxy;
         };
     }
 }

package/src/Back/Server.mjs

@@ -49,15 +49,15 @@ export default class Fl32_Web_Back_Server {
 
         /**
          * Starts the server with optional configuration.
-         * @param {Fl32_Web_Back_Config_Runtime_Server} [cfg]
+         * @param {Fl32_Web_Back_Config_Runtime} [cfg]
          * @returns {Promise<void>}
          */
         this.start = async function (cfg) {
             pipelineEngine.lockHandlers();
             // create server
-            const port = cfg?.port ?? config.server.port;
-            const type = cfg?.type ?? config.server.type;
-            const tls = cfg?.tls ?? config.server.tls;
+            const port = cfg?.port ?? config.port;
+            const type = cfg?.type ?? config.type;
+            const tls = cfg?.tls ?? config.tls;
 
             if (type === SERVER_TYPE.HTTP2) {
                 _instance = createServerH2();

package/types.d.ts

@@ -2,10 +2,8 @@ declare global {
   type Fl32_Web_Back_Api_Handler = import("./src/Back/Api/Handler.mjs").default;
   type Fl32_Web_Back_Config_Runtime = import("./src/Back/Config/Runtime.mjs").Data;
   type Fl32_Web_Back_Config_Runtime$Factory = import("./src/Back/Config/Runtime.mjs").Factory;
-  type Fl32_Web_Back_Config_Runtime_Server = import("./src/Back/Config/Runtime.mjs").Server;
   type Fl32_Web_Back_Config_Runtime_Tls = import("./src/Back/Config/Runtime/Tls.mjs").Data;
   type Fl32_Web_Back_Config_Runtime_Tls$Factory = import("./src/Back/Config/Runtime/Tls.mjs").Factory;
-  type Fl32_Web_Back_Config_Runtime_Params = {server?: {port?: unknown, type?: unknown, tls?: unknown}};
   type Fl32_Web_Back_Config_Runtime_Tls_Params = {ca?: unknown, cert?: unknown, key?: unknown};
   type Fl32_Web_Back_Dto_Info = import("./src/Back/Dto/Info.mjs").default;
   type Fl32_Web_Back_Dto_Info$Factory = import("./src/Back/Dto/Info.mjs").Factory;