@webtypen/webframez-core 0.3.39 → 0.3.40

package/README.md

@@ -297,6 +297,57 @@ Example: `GET /api/backoffice/current-user`.
 
 The scope middleware runs before the function. Its return value is passed to the function as `apiRequest.context`. Calling `abort(message, status)` stops execution and returns an error response with that status.
 
+### Group ApiScopes
+
+Use `ApiScopesGroup` to share middleware across multiple scopes:
+
+```ts
+import { ApiScope, ApiScopesGroup, Request, Response } from "@webtypen/webframez-core";
+
+class BackofficeApiScope extends ApiScope {
+  key = "backoffice";
+  apiBasePath = "/api/backoffice";
+  functions = [CurrentUserFunction];
+
+  async middleware(_req: Request, _res: Response, _abort: (message?: any, status?: number) => never) {
+    return {
+      scope: "backoffice"
+    };
+  }
+
+  async groupMiddleware(_req: Request, _res: Response, _abort: (message?: any, status?: number) => never) {
+    return {
+      reachedThroughGroup: true
+    };
+  }
+}
+
+class BackofficeApiScopesGroup extends ApiScopesGroup {
+  key = "backoffice-group";
+  apiScopes = [BackofficeApiScope];
+
+  async middleware(req: Request, _res: Response, abort: (message?: any, status?: number) => never) {
+    if (!req.headers.authorization) {
+      return abort("Unauthorized", 401);
+    }
+
+    return {
+      user: { id: "..." }
+    };
+  }
+}
+```
+
+When a scope is reached through a group, middleware runs in this order:
+
+```text
+ApiScopesGroup.middleware()
+ApiScope.middleware()
+ApiScope.groupMiddleware()
+```
+
+The context objects are merged in that order, so later scope-specific values can override group values. `groupMiddleware()` only runs when the scope was registered through an `ApiScopesGroup`.
+
 ### Register ApiScopes
 
 Register scopes on the web kernel:
@@ -305,7 +356,7 @@ Register scopes on the web kernel:
 import { BaseKernelWeb } from "@webtypen/webframez-core";
 
 class Kernel extends BaseKernelWeb {
-  static apiScopes = [BackofficeApiScope];
+  static apiScopes = [BackofficeApiScope, BackofficeApiScopesGroup];
 }
 ```
 
@@ -315,7 +366,7 @@ Modules can register scopes as instance properties:
 import { ModuleProvider } from "@webtypen/webframez-core";
 
 class BackofficeModuleProvider extends ModuleProvider {
-  apiScopes = [BackofficeApiScope];
+  apiScopes = [BackofficeApiScope, BackofficeApiScopesGroup];
 }
 ```
 

package/dist/Api/ApiFunctionUtils.d.ts

@@ -4,7 +4,12 @@ import { Request } from "../Router/Request";
 import { Response } from "../Router/Response";
 import { ApiFunction } from "./ApiFunction";
 import { ApiScope } from "./ApiScope";
-import { ApiFunctionClass, ApiFunctionParamDefinition, ApiFunctionParamsDefinition, ApiScopeClass } from "./ApiTypes";
+import { ApiScopesGroup } from "./ApiScopesGroup";
+import { ApiFunctionClass, ApiFunctionParamDefinition, ApiFunctionParamsDefinition, ApiScopeClass, ApiScopeRegistrationClass, ApiScopesGroupClass } from "./ApiTypes";
+export type ApiScopeRegistrationEntry = {
+    scopeClass: ApiScopeClass;
+    groupClass?: ApiScopesGroupClass;
+};
 export declare class ApiFunctionRuntimeError extends Error {
     statusCode: number;
     constructor(message: string, statusCode?: number);
@@ -15,9 +20,22 @@ export declare function getApiErrorMessage(error: any): any;
 export declare function isPlainApiObject(value: any): boolean;
 export declare function normalizeApiFunctionProvider(provider: any): ApiFunctionClass[];
 export declare function getApiFunctionClasses(scope: ApiScope): ApiFunctionClass[];
+export declare function normalizeApiScopesGroupProvider(provider: any): ApiScopeClass[];
+export declare function isApiScopesGroupInstance(value: any): value is ApiScopesGroup;
+export declare function instantiateApiScopesGroup(GroupClass: ApiScopesGroupClass): ApiScopesGroup;
+export declare function collectApiScopeRegistrations(registrations: ApiScopeRegistrationClass[]): ApiScopeRegistrationEntry[];
 export declare function runApiScopeMiddleware(scope: ApiScope, req: Request, res: Response): Promise<{
     [key: string]: any;
 }>;
+export declare function runApiScopesGroupMiddleware(group: ApiScopesGroup, req: Request, res: Response): Promise<{
+    [key: string]: any;
+}>;
+export declare function runApiScopeGroupMiddleware(scope: ApiScope, req: Request, res: Response): Promise<{
+    [key: string]: any;
+}>;
+export declare function runApiScopeRegistrationMiddleware(registration: ApiScopeRegistrationEntry, req: Request, res: Response): Promise<{
+    [x: string]: any;
+}>;
 export declare function validateApiFunctionParams(definitions: ApiFunctionParamsDefinition, source: {
     [key: string]: any;
 }): {

package/dist/Api/ApiFunctionUtils.js

@@ -9,9 +9,10 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.instantiateApiFunction = exports.instantiateApiScope = exports.assertUniqueApiFunctionKeys = exports.createApiFrameworkRequest = exports.toApiFunctionPayload = exports.toApiFunctionHttpResult = exports.apiFunctionParamToJsonSchema = exports.apiFunctionParamsToJsonSchema = exports.coerceApiFunctionParam = exports.validateApiFunctionParams = exports.runApiScopeMiddleware = exports.getApiFunctionClasses = exports.normalizeApiFunctionProvider = exports.isPlainApiObject = exports.getApiErrorMessage = exports.joinApiPath = exports.normalizeApiPath = exports.ApiFunctionRuntimeError = void 0;
+exports.instantiateApiFunction = exports.instantiateApiScope = exports.assertUniqueApiFunctionKeys = exports.createApiFrameworkRequest = exports.toApiFunctionPayload = exports.toApiFunctionHttpResult = exports.apiFunctionParamToJsonSchema = exports.apiFunctionParamsToJsonSchema = exports.coerceApiFunctionParam = exports.validateApiFunctionParams = exports.runApiScopeRegistrationMiddleware = exports.runApiScopeGroupMiddleware = exports.runApiScopesGroupMiddleware = exports.runApiScopeMiddleware = exports.collectApiScopeRegistrations = exports.instantiateApiScopesGroup = exports.isApiScopesGroupInstance = exports.normalizeApiScopesGroupProvider = exports.getApiFunctionClasses = exports.normalizeApiFunctionProvider = exports.isPlainApiObject = exports.getApiErrorMessage = exports.joinApiPath = exports.normalizeApiPath = exports.ApiFunctionRuntimeError = void 0;
 const Request_1 = require("../Router/Request");
 const ApiFunction_1 = require("./ApiFunction");
+const ApiScopesGroup_1 = require("./ApiScopesGroup");
 class ApiFunctionRuntimeError extends Error {
     constructor(message, statusCode = 500) {
         super(message);
@@ -68,16 +69,92 @@ function getApiFunctionClasses(scope) {
     return functions;
 }
 exports.getApiFunctionClasses = getApiFunctionClasses;
+function createApiScopeMiddlewareAbort() {
+    const abort = (message, status = 403) => {
+        throw new ApiFunctionRuntimeError(getApiErrorMessage(message || "Request aborted"), status);
+    };
+    return abort;
+}
+function normalizeApiScopesGroupProvider(provider) {
+    if (typeof provider === "function") {
+        const resolved = provider();
+        if (resolved && typeof resolved.then === "function") {
+            throw new Error("Async ApiScopesGroup.apiScopes providers are not supported during web boot");
+        }
+        return Array.isArray(resolved) ? resolved : [];
+    }
+    return Array.isArray(provider) ? provider : [];
+}
+exports.normalizeApiScopesGroupProvider = normalizeApiScopesGroupProvider;
+function isApiScopesGroupInstance(value) {
+    return value instanceof ApiScopesGroup_1.ApiScopesGroup;
+}
+exports.isApiScopesGroupInstance = isApiScopesGroupInstance;
+function instantiateApiScopesGroup(GroupClass) {
+    return new GroupClass();
+}
+exports.instantiateApiScopesGroup = instantiateApiScopesGroup;
+function collectApiScopeRegistrations(registrations) {
+    const entries = [];
+    for (const RegistrationClass of registrations || []) {
+        if (typeof RegistrationClass !== "function") {
+            continue;
+        }
+        const registration = new RegistrationClass();
+        if (isApiScopesGroupInstance(registration)) {
+            for (const ScopeClass of normalizeApiScopesGroupProvider(registration.apiScopes)) {
+                if (typeof ScopeClass === "function") {
+                    entries.push({
+                        scopeClass: ScopeClass,
+                        groupClass: RegistrationClass,
+                    });
+                }
+            }
+            continue;
+        }
+        entries.push({
+            scopeClass: RegistrationClass,
+        });
+    }
+    return entries;
+}
+exports.collectApiScopeRegistrations = collectApiScopeRegistrations;
 function runApiScopeMiddleware(scope, req, res) {
     return __awaiter(this, void 0, void 0, function* () {
-        const abort = (message, status = 403) => {
-            throw new ApiFunctionRuntimeError(getApiErrorMessage(message || "Request aborted"), status);
-        };
+        const abort = createApiScopeMiddlewareAbort();
         const result = yield scope.middleware(req, res, abort);
         return isPlainApiObject(result) ? result : {};
     });
 }
 exports.runApiScopeMiddleware = runApiScopeMiddleware;
+function runApiScopesGroupMiddleware(group, req, res) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const abort = createApiScopeMiddlewareAbort();
+        const result = yield group.middleware(req, res, abort);
+        return isPlainApiObject(result) ? result : {};
+    });
+}
+exports.runApiScopesGroupMiddleware = runApiScopesGroupMiddleware;
+function runApiScopeGroupMiddleware(scope, req, res) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const abort = createApiScopeMiddlewareAbort();
+        const result = yield scope.groupMiddleware(req, res, abort);
+        return isPlainApiObject(result) ? result : {};
+    });
+}
+exports.runApiScopeGroupMiddleware = runApiScopeGroupMiddleware;
+function runApiScopeRegistrationMiddleware(registration, req, res) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const groupContext = registration.groupClass
+            ? yield runApiScopesGroupMiddleware(instantiateApiScopesGroup(registration.groupClass), req, res)
+            : {};
+        const scope = instantiateApiScope(registration.scopeClass);
+        const scopeContext = yield runApiScopeMiddleware(scope, req, res);
+        const groupScopeContext = registration.groupClass ? yield runApiScopeGroupMiddleware(scope, req, res) : {};
+        return Object.assign(Object.assign(Object.assign({}, groupContext), scopeContext), groupScopeContext);
+    });
+}
+exports.runApiScopeRegistrationMiddleware = runApiScopeRegistrationMiddleware;
 function validateApiFunctionParams(definitions, source) {
     const params = {};
     const input = isPlainApiObject(source) ? source : {};

package/dist/Api/ApiScope.d.ts

@@ -9,4 +9,7 @@ export declare class ApiScope {
     middleware(_req: Request, _res: Response, _abort: ApiScopeMiddlewareAbort): Promise<{
         [key: string]: any;
     }>;
+    groupMiddleware(_req: Request, _res: Response, _abort: ApiScopeMiddlewareAbort): Promise<{
+        [key: string]: any;
+    }>;
 }

package/dist/Api/ApiScope.js

@@ -22,5 +22,10 @@ class ApiScope {
             return {};
         });
     }
+    groupMiddleware(_req, _res, _abort) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return {};
+        });
+    }
 }
 exports.ApiScope = ApiScope;

package/dist/Api/ApiScopeRegistry.d.ts

@@ -1,4 +1,4 @@
-import { ApiScopeClass } from "./ApiTypes";
+import { ApiScopeRegistrationEntry } from "./ApiFunctionUtils";
 type ApiScopeRuntimeContext = {
     kernel?: any;
     modulesLoader?: any;
@@ -6,7 +6,7 @@ type ApiScopeRuntimeContext = {
 declare class ApiScopeRegistryFacade {
     private context;
     configure(context?: ApiScopeRuntimeContext): this;
-    collect(context?: ApiScopeRuntimeContext): ApiScopeClass[];
+    collect(context?: ApiScopeRuntimeContext): ApiScopeRegistrationEntry[];
     register(context?: ApiScopeRuntimeContext): this;
     private registerHttpRoutes;
     private registerRouteMethod;

package/dist/Api/ApiScopeRegistry.js

@@ -46,19 +46,19 @@ class ApiScopeRegistryFacade {
                     : [];
             scopes.push(...moduleScopes);
         }
-        return scopes.filter((scopeClass) => typeof scopeClass === "function");
+        return (0, ApiFunctionUtils_1.collectApiScopeRegistrations)(scopes);
     }
     register(context) {
         this.configure(context);
         const scopes = this.collect(context);
         this.assertUniqueApiPaths(scopes);
-        for (const ScopeClass of scopes) {
-            this.registerHttpRoutes(ScopeClass);
+        for (const registration of scopes) {
+            this.registerHttpRoutes(registration);
         }
         return this;
     }
-    registerHttpRoutes(ScopeClass) {
-        const scope = (0, ApiFunctionUtils_1.instantiateApiScope)(ScopeClass);
+    registerHttpRoutes(registration) {
+        const scope = (0, ApiFunctionUtils_1.instantiateApiScope)(registration.scopeClass);
         if (!scope.apiBasePath) {
             return;
         }
@@ -69,7 +69,7 @@ class ApiScopeRegistryFacade {
             }
             const path = (0, ApiFunctionUtils_1.joinApiPath)(scope.apiBasePath, func.key);
             const handler = (req, res) => __awaiter(this, void 0, void 0, function* () {
-                return yield this.handleHttpFunction(ScopeClass, FunctionClass, req, res);
+                return yield this.handleHttpFunction(registration, FunctionClass, req, res);
             });
             this.registerRouteMethod(func.requestMethod, path, handler);
         }
@@ -85,12 +85,11 @@ class ApiScopeRegistryFacade {
         }
         routeMethod.bind(Route_1.Route)(path, handler);
     }
-    handleHttpFunction(ScopeClass, FunctionClass, req, res) {
+    handleHttpFunction(registration, FunctionClass, req, res) {
         return __awaiter(this, void 0, void 0, function* () {
-            const scope = (0, ApiFunctionUtils_1.instantiateApiScope)(ScopeClass);
             const func = (0, ApiFunctionUtils_1.instantiateApiFunction)(FunctionClass);
             try {
-                const context = yield (0, ApiFunctionUtils_1.runApiScopeMiddleware)(scope, req, res);
+                const context = yield (0, ApiFunctionUtils_1.runApiScopeRegistrationMiddleware)(registration, req, res);
                 const paramsSource = (func.requestMethod || req.method).toUpperCase() === "GET" ? req.query : req.body;
                 const params = (0, ApiFunctionUtils_1.validateApiFunctionParams)(func.params || {}, paramsSource || {});
                 const result = yield func.handle({ context, params, request: req, response: res });
@@ -107,8 +106,8 @@ class ApiScopeRegistryFacade {
     }
     assertUniqueApiPaths(scopes) {
         const seen = {};
-        for (const ScopeClass of scopes) {
-            const scope = (0, ApiFunctionUtils_1.instantiateApiScope)(ScopeClass);
+        for (const registration of scopes) {
+            const scope = (0, ApiFunctionUtils_1.instantiateApiScope)(registration.scopeClass);
             if (!scope.apiBasePath) {
                 continue;
             }

package/dist/Api/ApiScopesGroup.d.ts

@@ -0,0 +1,10 @@
+import { Request } from "../Router/Request";
+import { Response } from "../Router/Response";
+import { ApiScopeClass, ApiScopeMiddlewareAbort } from "./ApiTypes";
+export declare class ApiScopesGroup {
+    key: string;
+    apiScopes: Array<ApiScopeClass> | (() => Array<ApiScopeClass>);
+    middleware(_req: Request, _res: Response, _abort: ApiScopeMiddlewareAbort): Promise<{
+        [key: string]: any;
+    }>;
+}

package/dist/Api/ApiScopesGroup.js

@@ -0,0 +1,24 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiScopesGroup = void 0;
+class ApiScopesGroup {
+    constructor() {
+        this.key = "unique_api_scopes_group_key";
+        this.apiScopes = [];
+    }
+    middleware(_req, _res, _abort) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return {};
+        });
+    }
+}
+exports.ApiScopesGroup = ApiScopesGroup;

package/dist/Api/ApiTypes.d.ts

@@ -22,6 +22,8 @@ export type ApiFunctionParamsDefinition = {
 };
 export type ApiFunctionClass = new (...args: any[]) => any;
 export type ApiScopeClass = new (...args: any[]) => any;
+export type ApiScopesGroupClass = new (...args: any[]) => any;
+export type ApiScopeRegistrationClass = ApiScopeClass | ApiScopesGroupClass;
 export type ApiScopeMiddlewareAbort = (message?: any, status?: number) => never;
 export type ApiFunctionRequest = {
     context: ApiScopeFunctionContext;

package/dist/BaseKernelWeb.d.ts

@@ -1,7 +1,7 @@
 import { Controller } from "./Controller/Controller";
 import { KernelAiRegistrations } from "./Ai/AiTypes";
 import { KernelMcpRegistrations } from "./Mcp/McpTypes";
-import { ApiScopeClass } from "./Api/ApiTypes";
+import { ApiScopeRegistrationClass } from "./Api/ApiTypes";
 export declare class BaseKernelWeb {
     static controller: {
         [key: string]: Controller;
@@ -9,7 +9,7 @@ export declare class BaseKernelWeb {
     static middleware: {
         [key: string]: any;
     };
-    static apiScopes: ApiScopeClass[];
+    static apiScopes: ApiScopeRegistrationClass[];
     static mcp?: KernelMcpRegistrations;
     static ai?: KernelAiRegistrations;
 }

package/dist/Modules/ModuleProvider.d.ts

@@ -1,5 +1,5 @@
 import { KernelAiRegistrations } from "../Ai/AiTypes";
-import { ApiScopeClass } from "../Api/ApiTypes";
+import { ApiScopeRegistrationClass } from "../Api/ApiTypes";
 import { KernelMcpRegistrations } from "../Mcp/McpTypes";
 export declare class ModuleProvider {
     static key: string;
@@ -9,7 +9,7 @@ export declare class ModuleProvider {
     middleware: {
         [key: string]: any;
     };
-    apiScopes: ApiScopeClass[];
+    apiScopes: ApiScopeRegistrationClass[];
     commands: any[];
     mcp?: KernelMcpRegistrations;
     ai?: KernelAiRegistrations;

package/dist/index.d.ts

@@ -43,6 +43,7 @@ export * from "./Hooks/WebframezHooks";
 export * from "./Api/ApiTypes";
 export * from "./Api/ApiFunction";
 export * from "./Api/ApiScope";
+export * from "./Api/ApiScopesGroup";
 export * from "./Api/ApiFunctionUtils";
 export * from "./Api/ApiScopeRegistry";
 export * from "./Ai/AiTypes";

package/dist/index.js

@@ -59,6 +59,7 @@ __exportStar(require("./Hooks/WebframezHooks"), exports);
 __exportStar(require("./Api/ApiTypes"), exports);
 __exportStar(require("./Api/ApiFunction"), exports);
 __exportStar(require("./Api/ApiScope"), exports);
+__exportStar(require("./Api/ApiScopesGroup"), exports);
 __exportStar(require("./Api/ApiFunctionUtils"), exports);
 __exportStar(require("./Api/ApiScopeRegistry"), exports);
 __exportStar(require("./Ai/AiTypes"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webtypen/webframez-core",
-    "version": "0.3.39",
+    "version": "0.3.40",
     "description": "The core package of the typescript based webframez (web-framework) by webtypen.de",
     "homepage": "https://webtypen.de/",
     "license": "MIT",