@lafken/main 0.6.0

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aníbal Emilio Jorquera Cornejo
+
+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,58 @@
+# @lafken/main
+
+This is the core entry point of an Lafken application. Internally, it initializes the @cdktf/provider-aws, allowing you to register resolvers, modules, and global configuration. It orchestrates the creation of all the infrastructure required for a fully serverless application.
+
+## Installation
+
+
+```bash
+npm  install  @lafken/main
+```
+
+
+## Features
+
+
+### createApp
+
+
+This is the main entry point of the application. It allows you to register the resolvers required for processing your infrastructure, as well as define global configuration.
+
+Creating an application is straightforward.
+
+```ts
+createApp({
+  name: 'awesome',
+  modules: [],
+  resolvers: [],
+  globalConfig: {
+    tags: {
+      'global-tag': 'awesome-tag',
+    },
+  },
+  extend() {
+    // extend your application
+  },
+});
+```
+
+Just give your application a name, import your resolvers—such as `ApiResolver` or `BucketResolver`—add your modules, and you’re ready to go.
+
+### createModule
+
+Each module contains one or more resources. With a module, you can import your classes and define the resources that will be processed by a resolver.  
+Additionally, you can apply global configuration to all resources managed by the module.
+
+```ts
+createModule({
+  name: 'awesome-module',
+  resources: [/** API, QUEUE, SCHEDULE */],
+  globalConfig: {
+    lambda: {
+      services: ['cloudwatch', 's3', 'sqs', 'dynamodb'],
+    },
+  },
+});
+```
+
+This allows you to group related functionality, organize your infrastructure, and apply shared settings across multiple resources.

package/lib/app/app.d.ts

@@ -0,0 +1,16 @@
+import { App, TerraformStack } from 'cdktf';
+import type { CreateAppProps } from './app.types';
+export declare class AppStack extends TerraformStack {
+    id: string;
+    private props;
+    constructor(scope: App, id: string, props: CreateAppProps);
+    init(): Promise<void>;
+    private triggerHook;
+    private resolveModuleResources;
+    private createRole;
+    private addAspectProperties;
+}
+export declare const createApp: (props: CreateAppProps) => Promise<{
+    app: App;
+    appStack: AppStack;
+}>;

package/lib/app/app.js

@@ -0,0 +1,98 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApp = exports.AppStack = void 0;
+const provider_1 = require("@cdktf/provider-aws/lib/provider");
+const common_1 = require("@lafken/common");
+const resolver_1 = require("@lafken/resolver");
+const cdktf_1 = require("cdktf");
+const pretty_error_1 = __importDefault(require("pretty-error"));
+const aspect_1 = require("../aspect/aspect");
+const context_1 = require("../context/context");
+(0, common_1.enableBuildEnvVariable)();
+new pretty_error_1.default().start();
+class AppStack extends cdktf_1.TerraformStack {
+    id;
+    props;
+    constructor(scope, id, props) {
+        super(scope, id);
+        this.id = id;
+        this.props = props;
+        new context_1.AppContext(this, {
+            contextName: resolver_1.ContextName.app,
+            globalConfig: props.globalConfig?.lambda,
+            contextCreator: props.name,
+        });
+        new provider_1.AwsProvider(this, 'AWS', props.awsProviderConfig);
+        this.createRole();
+    }
+    async init() {
+        const { resolvers, extend } = this.props;
+        await this.triggerHook(resolvers, 'beforeCreate');
+        await this.resolveModuleResources();
+        await this.triggerHook(resolvers, 'afterCreate');
+        this.addAspectProperties();
+        await resolver_1.lafkenResource.callDependentCallbacks();
+        await resolver_1.lambdaAssets.createAssets();
+        if (extend) {
+            await extend(this);
+        }
+    }
+    async triggerHook(resolvers, trigger) {
+        for (const resolver of resolvers) {
+            if (resolver[trigger] !== undefined) {
+                await resolver[trigger](this);
+            }
+        }
+    }
+    async resolveModuleResources() {
+        const { modules, resolvers } = this.props;
+        const resolversByType = resolvers.reduce((acc, resolver) => {
+            acc[resolver.type] = resolver;
+            return acc;
+        }, {});
+        await Promise.all(modules.map((module) => module(this, resolversByType)));
+    }
+    createRole() {
+        const roleName = `${this.props.name}-global-role`;
+        const lambdaRole = new resolver_1.Role(this, roleName, {
+            name: roleName,
+            services: this.props.globalConfig?.lambda?.services || [
+                'dynamodb',
+                's3',
+                'lambda',
+                'cloudwatch',
+                'sqs',
+                'state_machine',
+                'kms',
+                'ssm',
+                'event',
+            ],
+        });
+        lambdaRole.isGlobal('app', roleName);
+    }
+    addAspectProperties() {
+        cdktf_1.Aspects.of(this).add(new aspect_1.AppAspect({
+            tags: {
+                ...(this.props.globalConfig?.tags || {}),
+                'lafken:app': this.id,
+            },
+        }));
+    }
+}
+exports.AppStack = AppStack;
+const createApp = async (props) => {
+    const app = new cdktf_1.App({
+        skipValidation: true,
+    });
+    const appStack = new AppStack(app, props.name, props);
+    await appStack.init();
+    app.synth();
+    return {
+        app,
+        appStack,
+    };
+};
+exports.createApp = createApp;

package/lib/app/app.types.d.ts

@@ -0,0 +1,62 @@
+import type { AwsProviderConfig } from '@cdktf/provider-aws/lib/provider';
+import type { LambdaGlobalConfig, ResolverType } from '@lafken/resolver';
+import type { StackModule } from '../module';
+import type { ModuleResolverType } from '../module/module.types';
+import type { AppStack } from './app';
+export interface GlobalConfig {
+    lambda?: LambdaGlobalConfig;
+    /**
+     * Global resource tags.
+     *
+     * Specifies a set of tags that will be applied to all resources
+     * unless a resource explicitly defines its own tags. In that case,
+     * the resource-specific tags will override the global values.
+     */
+    tags?: Record<string, string>;
+}
+export interface CreateAppProps {
+    /**
+     * Application name.
+     *
+     * Specifies the name of the application, which is used within
+     * the AWS stack as an identifier for resources.
+     *
+     * @example
+     * name: "my-awesome-app"
+     */
+    name: string;
+    /**
+     * Application modules.
+     *
+     * Defines the set of modules to be created within the application.
+     */
+    modules: ((scope: AppStack, resources: Record<string, ModuleResolverType>) => Promise<StackModule>)[];
+    /**
+     * Resource resolvers.
+     *
+     * Defines the list of resolvers responsible for creating and configuring
+     * resources loaded by the stacks. Each resolver can receive detailed
+     * configuration options depending on the type of resource it manages.
+     *
+     * For example, an `ApiResolver` can include REST API settings,
+     * deployment options, and authorization configurations.
+     */
+    resolvers: ResolverType[];
+    /**
+     * Global configuration for the application.
+     *
+     * Provides settings that are applied across all resources, stacks,
+     * and Lambda functions unless overridden at a lower level.
+     * This includes global Lambda properties, environment configuration,
+     * and resource tags.
+     */
+    globalConfig?: GlobalConfig;
+    /**
+     *
+     */
+    awsProviderConfig?: AwsProviderConfig;
+    /**
+     *
+     */
+    extend?: (scope: AppStack) => Promise<void>;
+}

package/lib/app/app.types.js

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

package/lib/app/index.d.ts

@@ -0,0 +1,2 @@
+export * from './app';
+export * from './app.types';

package/lib/app/index.js

@@ -0,0 +1,18 @@
+"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("./app"), exports);
+__exportStar(require("./app.types"), exports);

package/lib/aspect/aspect.d.ts

@@ -0,0 +1,12 @@
+import type { IAspect } from 'cdktf';
+import type { IConstruct } from 'constructs';
+interface AppAspectProps {
+    tags: Record<string, string>;
+}
+export declare class AppAspect implements IAspect {
+    private props;
+    constructor(props: AppAspectProps);
+    visit(node: IConstruct): void;
+    private isTaggableResource;
+}
+export {};

package/lib/aspect/aspect.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppAspect = void 0;
+class AppAspect {
+    props;
+    constructor(props) {
+        this.props = props;
+    }
+    visit(node) {
+        if (this.isTaggableResource(node)) {
+            const currentTags = node.tagsInput || {};
+            node.tags = { ...this.props.tags, ...currentTags };
+        }
+    }
+    isTaggableResource(resource) {
+        return 'tags' in resource && 'tagsInput' in resource;
+    }
+}
+exports.AppAspect = AppAspect;

package/lib/context/context.d.ts

@@ -0,0 +1,5 @@
+import type { Construct } from 'constructs';
+import type { ContextProps } from './context.types';
+export declare class AppContext {
+    constructor(scope: Construct, props: ContextProps);
+}

package/lib/context/context.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppContext = void 0;
+class AppContext {
+    constructor(scope, props) {
+        const { contextName, globalConfig = {} } = props;
+        const { services: _services, ...contextData } = globalConfig || {};
+        scope.node.setContext(contextName, {
+            ...contextData,
+            contextCreator: props.contextCreator,
+        });
+    }
+}
+exports.AppContext = AppContext;

package/lib/context/context.types.d.ts

@@ -0,0 +1,6 @@
+import type { LambdaGlobalConfig } from '@lafken/resolver';
+export interface ContextProps {
+    globalConfig?: LambdaGlobalConfig;
+    contextCreator: string;
+    contextName: string;
+}

package/lib/context/context.types.js

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

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './app';
+export * from './module';

package/lib/index.js

@@ -0,0 +1,18 @@
+"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("./app"), exports);
+__exportStar(require("./module"), exports);

package/lib/module/index.d.ts

@@ -0,0 +1,2 @@
+export * from './module';
+export * from './module.types';

package/lib/module/index.js

@@ -0,0 +1,18 @@
+"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("./module"), exports);
+__exportStar(require("./module.types"), exports);

package/lib/module/module.d.ts

@@ -0,0 +1,11 @@
+import { Construct } from 'constructs';
+import type { CreateModuleProps, ModuleConstruct, ModuleProps, ModuleResolverType } from './module.types';
+export declare class StackModule extends Construct {
+    id: string;
+    private props;
+    constructor(scope: Construct, id: string, props: ModuleProps);
+    generateResources(): Promise<void>;
+    private createRole;
+    private addAspectProperties;
+}
+export declare const createModule: (props: CreateModuleProps) => (scope: ModuleConstruct, resolvers: Record<string, ModuleResolverType>) => Promise<StackModule>;

package/lib/module/module.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createModule = exports.StackModule = void 0;
+const common_1 = require("@lafken/common");
+const resolver_1 = require("@lafken/resolver");
+const cdktf_1 = require("cdktf");
+const constructs_1 = require("constructs");
+const aspect_1 = require("../aspect/aspect");
+const context_1 = require("../context/context");
+class StackModule extends constructs_1.Construct {
+    id;
+    props;
+    constructor(scope, id, props) {
+        super(scope, id);
+        this.id = id;
+        this.props = props;
+        new context_1.AppContext(this, {
+            contextName: resolver_1.ContextName.module,
+            globalConfig: props.globalConfig?.lambda,
+            contextCreator: props.name,
+        });
+        this.createRole();
+    }
+    async generateResources() {
+        const { resources } = this.props;
+        for (const resource of resources) {
+            const metadata = (0, common_1.getResourceMetadata)(resource);
+            const resolver = this.props.resolvers[metadata.type];
+            if (!resolver) {
+                throw new Error(`There is no resolver for the resource ${metadata.type}`);
+            }
+            await resolver.create(this, resource);
+        }
+        this.addAspectProperties();
+    }
+    createRole() {
+        if (!this.props.globalConfig?.lambda?.services?.length) {
+            return;
+        }
+        const roleName = `${this.props.name}-module-role`;
+        const lambdaRole = new resolver_1.Role(this, roleName, {
+            name: roleName,
+            services: this.props.globalConfig?.lambda?.services || [],
+        });
+        lambdaRole.isGlobal('module', roleName);
+    }
+    addAspectProperties() {
+        cdktf_1.Aspects.of(this).add(new aspect_1.AppAspect({
+            tags: {
+                ...(this.props.globalConfig?.tags || {}),
+                'lafken:module': this.props.name,
+            },
+        }));
+    }
+}
+exports.StackModule = StackModule;
+const createModule = (props) => async (scope, resolvers) => {
+    const module = new StackModule(scope, props.name, {
+        ...props,
+        resolvers,
+    });
+    await module.generateResources();
+    return module;
+};
+exports.createModule = createModule;

package/lib/module/module.types.d.ts

@@ -0,0 +1,42 @@
+import type { ClassResource, ResourceMetadata } from '@lafken/common';
+import type { ResolverType } from '@lafken/resolver';
+import type { Construct } from 'constructs';
+import type { GlobalConfig } from '../app/app.types';
+import type { StackModule } from './module';
+export interface CreateModuleProps {
+    /**
+     * Module name.
+     *
+     * Specifies the name of the module, which will be used as an identifier
+     * for all resources created within this stack.
+     */
+    name: string;
+    /**
+     * Module resources.
+     *
+     * Defines the list of resources to be created within this stack.
+     * Each item represents a resource such as Api, Queue, StateMachine, etc.
+     */
+    resources: ClassResource[];
+    /**
+     * Module-level global configuration.
+     *
+     * Provides settings that are applied to all resources and Lambda functions
+     * within this specific module. This configuration behaves similarly to
+     * the application-wide `GlobalConfig`, but excludes environment settings (`env`),
+     * which are managed at the application level.
+     */
+    globalConfig?: Omit<GlobalConfig, 'env'>;
+}
+export interface ModuleProps extends CreateModuleProps {
+    resolvers: Record<string, ResolverType>;
+}
+export interface ModuleResource {
+    module: StackModule;
+    metadata: ResourceMetadata;
+    Resource: ClassResource;
+}
+export interface ModuleResolverType extends ResolverType {
+}
+export interface ModuleConstruct extends Construct {
+}

package/lib/module/module.types.js

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

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@lafken/main",
+  "version": "0.6.0",
+  "private": false,
+  "license": "MIT",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "dependencies": {
+    "@cdktf/provider-aws": "21.22.0",
+    "cdktf": "0.21.0",
+    "constructs": "10.4.4",
+    "pretty-error": "4.0.0",
+    "reflect-metadata": "0.2.2",
+    "@lafken/common": "0.6.0",
+    "@lafken/resolver": "0.6.0"
+  },
+  "devDependencies": {
+    "@types/jest": "30.0.0",
+    "jest": "30.2.0",
+    "ts-jest": "29.4.6",
+    "ts-node": "10.9.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm clean && tsc -p ./tsconfig.build.json",
+    "clean": "rm -rf ./lib",
+    "dev": "tsc -w",
+    "test": "jest",
+    "test:coverage": "jest --coverage"
+  }
+}