@aetherionfw/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristian Londoño
+
+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/dist/adapter/interfaces.d.ts

@@ -0,0 +1,6 @@
+export interface CanActivate {
+    canActivate(event: any, context: any): boolean | Promise<boolean>;
+}
+export interface Middleware {
+    use(event: any, context: any, next: () => Promise<any>): Promise<any>;
+}

package/dist/adapter/interfaces.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/adapter/lambda-adapter.d.ts

@@ -0,0 +1,2 @@
+import { Type } from '../di/Injector';
+export declare function createLambdaHandler(ControllerClass: Type): (event: any, context: any) => Promise<any>;

package/dist/adapter/lambda-adapter.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLambdaHandler = createLambdaHandler;
+const Injector_1 = require("../di/Injector");
+function createLambdaHandler(ControllerClass) {
+    // Resolve the controller via DI
+    const controllerInstance = Injector_1.Injector.getInstance().resolve(ControllerClass);
+    return async (event, context) => {
+        // 1. Determine event type
+        const isHttpEvent = !!event.httpMethod || !!(event.requestContext && event.requestContext.http);
+        // 2. Identify target method from ENV (Injected by builder for 1:1 Lambda per Handle)
+        const targetMethodName = process.env.AETHERION_TARGET_METHOD;
+        if (!targetMethodName || typeof controllerInstance[targetMethodName] !== 'function') {
+            if (isHttpEvent) {
+                return { statusCode: 404, body: 'Not Found: Target method missing or invalid' };
+            }
+            throw new Error(`No suitable handler found for target method: ${targetMethodName}`);
+        }
+        // 3. Middlewares
+        const classMiddlewares = Reflect.getMetadata('middlewares', ControllerClass) || [];
+        const methodMiddlewares = Reflect.getMetadata('middlewares', ControllerClass.prototype, targetMethodName) || [];
+        const allMiddlewares = [...classMiddlewares, ...methodMiddlewares];
+        let middlewareIndex = 0;
+        const executeMiddleware = async () => {
+            if (middlewareIndex < allMiddlewares.length) {
+                const MiddlewareClass = allMiddlewares[middlewareIndex++];
+                const middlewareInstance = Injector_1.Injector.getInstance().resolve(MiddlewareClass);
+                return middlewareInstance.use(event, context, executeMiddleware);
+            }
+            else {
+                // Finally execute the controller method
+                return controllerInstance[targetMethodName](event, context);
+            }
+        };
+        try {
+            const result = await executeMiddleware();
+            if (isHttpEvent) {
+                // Auto-format HTTP response if the controller just returned an object
+                if (result && result.statusCode) {
+                    return result;
+                }
+                return {
+                    statusCode: 200,
+                    body: JSON.stringify(result),
+                    headers: { 'Content-Type': 'application/json' }
+                };
+            }
+            return result; // SQS resolves normally
+        }
+        catch (error) {
+            if (isHttpEvent) {
+                return { statusCode: 500, body: JSON.stringify({ error: error.message }) };
+            }
+            throw error;
+        }
+    };
+}

package/dist/decorators/controller.decorator.d.ts

@@ -0,0 +1,2 @@
+import { ControllerMetadata } from '../registry/MetadataRegistry';
+export declare function LambdaController(metadata: ControllerMetadata): ClassDecorator;

package/dist/decorators/controller.decorator.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LambdaController = LambdaController;
+const MetadataRegistry_1 = require("../registry/MetadataRegistry");
+function LambdaController(metadata) {
+    return (target) => {
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerController(target, metadata);
+    };
+}

package/dist/decorators/handler.decorator.d.ts

@@ -0,0 +1,8 @@
+import { RouteMetadata } from '../registry/MetadataRegistry';
+export declare function Route(metadata: Omit<RouteMetadata, 'methodName'>): MethodDecorator;
+export declare function Handle(options?: {
+    timeout?: number;
+    memorySize?: number;
+}): MethodDecorator;
+export declare function IamPermissions(permissions: Record<string, any>): ClassDecorator & MethodDecorator;
+export declare function SqsTrigger(queueName: string, options?: any): MethodDecorator;

package/dist/decorators/handler.decorator.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Route = Route;
+exports.Handle = Handle;
+exports.IamPermissions = IamPermissions;
+exports.SqsTrigger = SqsTrigger;
+const MetadataRegistry_1 = require("../registry/MetadataRegistry");
+function Route(metadata) {
+    return (target, propertyKey, descriptor) => {
+        const fullMetadata = { ...metadata, methodName: String(propertyKey) };
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerRoute(target.constructor, fullMetadata);
+        Reflect.defineMetadata('route', fullMetadata, target, propertyKey);
+    };
+}
+function Handle(options) {
+    return (target, propertyKey, descriptor) => {
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerHandle(target.constructor, {
+            methodName: String(propertyKey),
+            timeout: options?.timeout,
+            memorySize: options?.memorySize,
+        });
+        Reflect.defineMetadata('handle', options || true, target, propertyKey);
+    };
+}
+function IamPermissions(permissions) {
+    return (target, propertyKey, descriptor) => {
+        // If propertyKey is undefined, it's a class decorator so target is the constructor.
+        // If propertyKey is defined, it's a method decorator so target is the prototype.
+        const actualTarget = propertyKey ? target.constructor : target;
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerIamPermissions(actualTarget, {
+            methodName: propertyKey ? String(propertyKey) : undefined,
+            permissions
+        });
+    };
+}
+function SqsTrigger(queueName, options) {
+    return (target, propertyKey, descriptor) => {
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerSqsTrigger(target.constructor, {
+            queueName,
+            methodName: String(propertyKey),
+            options
+        });
+    };
+}

package/dist/decorators/infra.decorator.d.ts

@@ -0,0 +1,48 @@
+export declare function Infra(): ClassDecorator;
+export declare function S3Bucket(props: {
+    name: string;
+    versioned?: boolean;
+    private?: boolean;
+}): PropertyDecorator;
+export declare function DynamoTable(props: {
+    name: string;
+    partitionKey: any;
+}): PropertyDecorator;
+export declare function SqsQueue(props: {
+    name: string;
+    visibilityTimeout?: number;
+    deadLetterQueue?: string;
+}): PropertyDecorator;
+export declare function KmsKey(props: {
+    alias?: string;
+    description?: string;
+}): PropertyDecorator;
+export declare function SsmParameter(props: {
+    name: string;
+    value: string;
+    type?: string;
+}): PropertyDecorator;
+export declare function EventBridgeRule(props: {
+    name: string;
+    scheduleExpression?: string;
+}): PropertyDecorator;
+export declare function CloudFrontDistribution(props: {
+    originDomain: string;
+}): PropertyDecorator;
+export declare function CognitoUserPool(props: {
+    name: string;
+}): PropertyDecorator;
+export declare function Vpc(props: {
+    name: string;
+    cidr: string;
+    natGateways?: number;
+}): PropertyDecorator;
+export declare function IamRole(props: {
+    name: string;
+    assumedBy: string;
+}): PropertyDecorator;
+export declare function RdsInstance(props: {
+    engine: string;
+    size: string;
+    dbName: string;
+}): PropertyDecorator;

package/dist/decorators/infra.decorator.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Infra = Infra;
+exports.S3Bucket = S3Bucket;
+exports.DynamoTable = DynamoTable;
+exports.SqsQueue = SqsQueue;
+exports.KmsKey = KmsKey;
+exports.SsmParameter = SsmParameter;
+exports.EventBridgeRule = EventBridgeRule;
+exports.CloudFrontDistribution = CloudFrontDistribution;
+exports.CognitoUserPool = CognitoUserPool;
+exports.Vpc = Vpc;
+exports.IamRole = IamRole;
+exports.RdsInstance = RdsInstance;
+const MetadataRegistry_1 = require("../registry/MetadataRegistry");
+function Infra() {
+    return (target) => {
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerInfraClass(target);
+    };
+}
+// Example of a specific infra resource decorator
+function S3Bucket(props) {
+    return (target, propertyKey) => {
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerInfraResource(target.constructor, {
+            type: 'S3Bucket',
+            name: String(propertyKey),
+            props
+        });
+    };
+}
+function DynamoTable(props) {
+    return (target, propertyKey) => {
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerInfraResource(target.constructor, {
+            type: 'DynamoTable',
+            name: String(propertyKey),
+            props
+        });
+    };
+}
+function SqsQueue(props) {
+    return (target, propertyKey) => {
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerInfraResource(target.constructor, {
+            type: 'SqsQueue',
+            name: String(propertyKey),
+            props
+        });
+    };
+}
+function KmsKey(props) {
+    return (target, propertyKey) => {
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerInfraResource(target.constructor, {
+            type: 'KmsKey',
+            name: String(propertyKey),
+            props
+        });
+    };
+}
+function SsmParameter(props) {
+    return (target, propertyKey) => {
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerInfraResource(target.constructor, {
+            type: 'SsmParameter',
+            name: String(propertyKey),
+            props
+        });
+    };
+}
+function EventBridgeRule(props) {
+    return (target, propertyKey) => {
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerInfraResource(target.constructor, {
+            type: 'EventBridgeRule',
+            name: String(propertyKey),
+            props
+        });
+    };
+}
+function CloudFrontDistribution(props) {
+    return (target, propertyKey) => {
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerInfraResource(target.constructor, {
+            type: 'CloudFrontDistribution',
+            name: String(propertyKey),
+            props
+        });
+    };
+}
+function CognitoUserPool(props) {
+    return (target, propertyKey) => {
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerInfraResource(target.constructor, {
+            type: 'CognitoUserPool',
+            name: String(propertyKey),
+            props
+        });
+    };
+}
+function Vpc(props) {
+    return (target, propertyKey) => {
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerInfraResource(target.constructor, {
+            type: 'Vpc',
+            name: String(propertyKey),
+            props
+        });
+    };
+}
+function IamRole(props) {
+    return (target, propertyKey) => {
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerInfraResource(target.constructor, {
+            type: 'IamRole',
+            name: String(propertyKey),
+            props
+        });
+    };
+}
+function RdsInstance(props) {
+    return (target, propertyKey) => {
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerInfraResource(target.constructor, {
+            type: 'RdsInstance',
+            name: String(propertyKey),
+            props
+        });
+    };
+}

package/dist/decorators/injectable.decorator.d.ts

@@ -0,0 +1 @@
+export declare function Injectable(): ClassDecorator;

package/dist/decorators/injectable.decorator.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Injectable = Injectable;
+function Injectable() {
+    return (target) => {
+        // Keep it simple for now, can be extended for scoping (Singleton, Transient)
+    };
+}

package/dist/decorators/module.decorator.d.ts

@@ -0,0 +1,2 @@
+import { ModuleMetadata } from '../registry/MetadataRegistry';
+export declare function Module(metadata: ModuleMetadata): ClassDecorator;

package/dist/decorators/module.decorator.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Module = Module;
+const MetadataRegistry_1 = require("../registry/MetadataRegistry");
+function Module(metadata) {
+    return (target) => {
+        MetadataRegistry_1.MetadataRegistry.getInstance().registerModule(target, metadata);
+    };
+}

package/dist/decorators/use-middlewares.decorator.d.ts

@@ -0,0 +1,3 @@
+import { Type } from '../di/Injector';
+import { Middleware } from '../adapter/interfaces';
+export declare function UseMiddlewares(middlewares: Type<Middleware>[]): ClassDecorator & MethodDecorator;

package/dist/decorators/use-middlewares.decorator.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UseMiddlewares = UseMiddlewares;
+// We could extend MetadataRegistry to support storing middlewares per controller/method.
+// For now, we'll attach it directly as reflect metadata.
+function UseMiddlewares(middlewares) {
+    return (target, propertyKey) => {
+        if (propertyKey) {
+            Reflect.defineMetadata('middlewares', middlewares, target, propertyKey);
+        }
+        else {
+            Reflect.defineMetadata('middlewares', middlewares, target);
+        }
+    };
+}

package/dist/di/Injector.d.ts

@@ -0,0 +1,10 @@
+import 'reflect-metadata';
+export type Type<T = any> = new (...args: any[]) => T;
+export declare class Injector {
+    private static instance;
+    private container;
+    private constructor();
+    static getInstance(): Injector;
+    resolve<T>(target: Type<T>): T;
+    provide<T>(target: Type<T>, instance: T): void;
+}

package/dist/di/Injector.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Injector = void 0;
+require("reflect-metadata");
+class Injector {
+    static instance;
+    container = new Map();
+    constructor() { }
+    static getInstance() {
+        if (!Injector.instance) {
+            Injector.instance = new Injector();
+        }
+        return Injector.instance;
+    }
+    resolve(target) {
+        // If instance already exists, return it (Singleton pattern)
+        if (this.container.has(target)) {
+            return this.container.get(target);
+        }
+        // Get constructor parameters
+        const tokens = Reflect.getMetadata('design:paramtypes', target) || [];
+        // Resolve dependencies recursively
+        const injections = tokens.map((token) => this.resolve(token));
+        // Instantiate class with dependencies
+        const instance = new target(...injections);
+        // Store in container
+        this.container.set(target, instance);
+        return instance;
+    }
+    provide(target, instance) {
+        this.container.set(target, instance);
+    }
+}
+exports.Injector = Injector;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './registry/MetadataRegistry';
+export * from './decorators/module.decorator';
+export * from './decorators/controller.decorator';
+export * from './decorators/handler.decorator';
+export * from './decorators/infra.decorator';
+export * from './decorators/injectable.decorator';
+export * from './decorators/use-middlewares.decorator';
+export * from './di/Injector';
+export * from './adapter/interfaces';
+export * from './adapter/lambda-adapter';

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./registry/MetadataRegistry"), exports);
+__exportStar(require("./decorators/module.decorator"), exports);
+__exportStar(require("./decorators/controller.decorator"), exports);
+__exportStar(require("./decorators/handler.decorator"), exports);
+__exportStar(require("./decorators/infra.decorator"), exports);
+__exportStar(require("./decorators/injectable.decorator"), exports);
+__exportStar(require("./decorators/use-middlewares.decorator"), exports);
+__exportStar(require("./di/Injector"), exports);
+__exportStar(require("./adapter/interfaces"), exports);
+__exportStar(require("./adapter/lambda-adapter"), exports);

package/dist/registry/MetadataRegistry.d.ts

@@ -0,0 +1,69 @@
+import 'reflect-metadata';
+export interface ModuleMetadata {
+    name: string;
+    imports?: any[];
+    providers?: any[];
+    controllers?: any[];
+    infra?: any[];
+}
+export interface ControllerMetadata {
+    lambdaName: string;
+    runtime?: string;
+    memorySize?: number;
+    timeout?: number;
+    layers?: string[];
+}
+export interface RouteMetadata {
+    method: string;
+    path: string;
+    authorizer?: string;
+    methodName: string;
+}
+export interface HandleMetadata {
+    methodName: string;
+    timeout?: number;
+    memorySize?: number;
+}
+export interface IamPermissionMetadata {
+    methodName?: string;
+    permissions: Record<string, any>;
+}
+export interface SqsTriggerMetadata {
+    queueName: string;
+    methodName: string;
+    options?: any;
+}
+export interface InfraMetadata {
+    type: string;
+    name: string;
+    props: any;
+}
+export declare class MetadataRegistry {
+    private static instance;
+    private modules;
+    private controllers;
+    private handles;
+    private iamPermissions;
+    private routes;
+    private sqsTriggers;
+    private infraClasses;
+    private infraResources;
+    private constructor();
+    static getInstance(): MetadataRegistry;
+    registerModule(target: any, metadata: ModuleMetadata): void;
+    getModules(): [any, ModuleMetadata][];
+    registerController(target: any, metadata: ControllerMetadata): void;
+    getControllers(): [any, ControllerMetadata][];
+    registerHandle(target: any, metadata: HandleMetadata): void;
+    getHandles(target: any): HandleMetadata[];
+    registerIamPermissions(target: any, metadata: IamPermissionMetadata): void;
+    getIamPermissions(target: any): IamPermissionMetadata[];
+    registerRoute(target: any, metadata: RouteMetadata): void;
+    getRoutes(target: any): RouteMetadata[];
+    registerSqsTrigger(target: any, metadata: SqsTriggerMetadata): void;
+    getSqsTriggers(target: any): SqsTriggerMetadata[];
+    registerInfraClass(target: any): void;
+    getInfraClasses(): any[];
+    registerInfraResource(target: any, metadata: InfraMetadata): void;
+    getInfraResources(target: any): InfraMetadata[];
+}

package/dist/registry/MetadataRegistry.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetadataRegistry = void 0;
+require("reflect-metadata");
+class MetadataRegistry {
+    static instance;
+    modules = new Map();
+    controllers = new Map();
+    handles = new Map();
+    iamPermissions = new Map();
+    routes = new Map();
+    sqsTriggers = new Map(); // target -> triggers
+    infraClasses = new Map();
+    infraResources = new Map(); // target -> resources
+    constructor() { }
+    static getInstance() {
+        if (!MetadataRegistry.instance) {
+            MetadataRegistry.instance = new MetadataRegistry();
+        }
+        return MetadataRegistry.instance;
+    }
+    registerModule(target, metadata) {
+        this.modules.set(target, metadata);
+    }
+    getModules() {
+        return Array.from(this.modules.entries());
+    }
+    registerController(target, metadata) {
+        this.controllers.set(target, metadata);
+    }
+    getControllers() {
+        return Array.from(this.controllers.entries());
+    }
+    registerHandle(target, metadata) {
+        if (!this.handles.has(target)) {
+            this.handles.set(target, []);
+        }
+        this.handles.get(target).push(metadata);
+    }
+    getHandles(target) {
+        return this.handles.get(target) || [];
+    }
+    registerIamPermissions(target, metadata) {
+        if (!this.iamPermissions.has(target)) {
+            this.iamPermissions.set(target, []);
+        }
+        this.iamPermissions.get(target).push(metadata);
+    }
+    getIamPermissions(target) {
+        return this.iamPermissions.get(target) || [];
+    }
+    registerRoute(target, metadata) {
+        if (!this.routes.has(target)) {
+            this.routes.set(target, []);
+        }
+        this.routes.get(target).push(metadata);
+    }
+    getRoutes(target) {
+        return this.routes.get(target) || [];
+    }
+    registerSqsTrigger(target, metadata) {
+        if (!this.sqsTriggers.has(target)) {
+            this.sqsTriggers.set(target, []);
+        }
+        this.sqsTriggers.get(target).push(metadata);
+    }
+    getSqsTriggers(target) {
+        return this.sqsTriggers.get(target) || [];
+    }
+    registerInfraClass(target) {
+        this.infraClasses.set(target, true);
+    }
+    getInfraClasses() {
+        return Array.from(this.infraClasses.keys());
+    }
+    registerInfraResource(target, metadata) {
+        if (!this.infraResources.has(target)) {
+            this.infraResources.set(target, []);
+        }
+        this.infraResources.get(target).push(metadata);
+    }
+    getInfraResources(target) {
+        return this.infraResources.get(target) || [];
+    }
+}
+exports.MetadataRegistry = MetadataRegistry;

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@aetherionfw/core",
+  "version": "1.0.0",
+  "description": "Core decorators and runtime for Aetherion Framework",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "reflect-metadata": "^0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^5.5.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md"
+  ],
+  "author": "CrisD3v",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  }
+}