@lafken/main 0.7.0 → 0.8.0

package/README.md

@@ -1,58 +1,219 @@
 # @lafken/main
 
-This is the core entry point of an Lafken application. Internally, it initializes the @cdktn/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.
+Core entry point for a Lafken serverless application. `@lafken/main` initializes the AWS provider, orchestrates resolvers and modules, and synthesizes the resulting Terraform configuration through CDKTN. It provides `createApp` to bootstrap the application and `createModule` to organize resources into logical groups.
 
 ## Installation
 
-
 ```bash
-npm  install  @lafken/main
+npm install @lafken/main
 ```
 
+## Getting Started
 
-## Features
+Create an application with resolvers and modules, then let Lafken generate all the infrastructure:
 
+```typescript
+import { createApp, createModule } from '@lafken/main';
+import { ApiResolver } from '@lafken/api/resolver';
+import { QueueResolver } from '@lafken/queue/resolver';
 
-### createApp
+// 1. Define modules that group related resources
+const userModule = createModule({
+  name: 'users',
+  resources: [UserApi, UserQueue],
+});
+
+const billingModule = createModule({
+  name: 'billing',
+  resources: [InvoiceSchedule],
+});
 
+// 2. Create the application
+await createApp({
+  name: 'my-app',
+  modules: [userModule, billingModule],
+  resolvers: [
+    new ApiResolver({ restApi: { name: 'my-api' } }),
+    new QueueResolver(),
+  ],
+});
+```
+
+## Features
 
-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.
+### createApp
 
-Creating an application is straightforward.
+`createApp` is the main entry point. It initializes the AWS stack, runs all resolver lifecycle hooks (`beforeCreate` → `create` → `afterCreate`), and synthesizes the Terraform output:
 
-```ts
-createApp({
-  name: 'awesome',
-  modules: [],
-  resolvers: [],
+```typescript
+await createApp({
+  name: 'my-app',
+  modules: [userModule, billingModule],
+  resolvers: [new ApiResolver(), new QueueResolver()],
   globalConfig: {
+    lambda: {
+      memory: 512,
+      timeout: 30,
+      runtime: 22,
+      services: ['dynamodb', 's3', 'sqs'],
+    },
     tags: {
-      'global-tag': 'awesome-tag',
+      environment: 'production',
+      team: 'platform',
     },
   },
-  extend() {
-    // extend your application
+  awsProviderConfig: {
+    region: 'us-east-1',
+    profile: 'my-aws-profile',
+  },
+  s3Backend: {
+    bucket: 'my-terraform-state',
+    key: 'app/terraform.tfstate',
+    region: 'us-east-1',
+  },
+  extend: async (scope) => {
+    // Add custom CDKTN constructs after all resolvers finish
   },
 });
 ```
 
-Just give your application a name, import your resolvers—such as `ApiResolver` or `BucketResolver`—add your modules, and you’re ready to go.
+#### Application Options
+
+| Option              | Type                | Required | Description                                               |
+| ------------------- | ------------------- | -------- | --------------------------------------------------------- |
+| `name`              | `string`            | Yes      | Application name, used as the stack identifier             |
+| `modules`           | `StackModule[]`     | Yes      | Modules created with `createModule`                        |
+| `resolvers`         | `ResolverType[]`    | Yes      | Resolvers that process decorated resources                 |
+| `globalConfig`      | `GlobalConfig`      | No       | Shared Lambda and tag settings for all resources           |
+| `awsProviderConfig` | `AwsProviderConfig` | No       | AWS provider settings (region, profile, etc.)              |
+| `s3Backend`         | `S3BackendConfig`   | No       | Remote S3 backend for Terraform state                      |
+| `extend`            | `(scope) => void`   | No       | Callback invoked after all resolvers finish                |
 
 ### 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.
+`createModule` groups related resources into a logical unit with its own scope, IAM role, and configuration. Each resource inside the module is processed by the matching resolver based on its decorator type:
 
-```ts
-createModule({
-  name: 'awesome-module',
-  resources: [/** API, QUEUE, SCHEDULE */],
+```typescript
+const orderModule = createModule({
+  name: 'orders',
+  resources: [OrderApi, OrderQueue, OrderSchedule],
   globalConfig: {
     lambda: {
-      services: ['cloudwatch', 's3', 'sqs', 'dynamodb'],
+      memory: 256,
+      timeout: 15,
+      services: ['dynamodb', 'sqs'],
+    },
+    tags: {
+      domain: 'orders',
     },
   },
 });
 ```
 
-This allows you to group related functionality, organize your infrastructure, and apply shared settings across multiple resources.
+#### Module Options
+
+| Option         | Type              | Required | Description                                           |
+| -------------- | ----------------- | -------- | ----------------------------------------------------- |
+| `name`         | `string`          | Yes      | Module name, used as scope and tag identifier          |
+| `resources`    | `ClassResource[]` | Yes      | Decorated classes to be processed by resolvers         |
+| `globalConfig` | `GlobalConfig`    | No       | Lambda and tag settings scoped to this module          |
+
+### Global Configuration
+
+Global configuration applies default settings to all Lambda functions and resources. Values cascade from application to module to individual resource, with more specific settings taking precedence:
+
+```
+App globalConfig → Module globalConfig → Resource-level config
+```
+
+#### Lambda Configuration
+
+| Option        | Type             | Description                                               |
+| ------------- | ---------------- | --------------------------------------------------------- |
+| `memory`      | `number`         | Memory allocation in MB                                   |
+| `timeout`     | `number`         | Execution timeout in seconds                              |
+| `runtime`     | `20 \| 22 \| 24` | Node.js runtime version                                   |
+| `services`    | `Services[]`     | AWS services the Lambda can access (creates IAM role)     |
+| `enableTrace` | `boolean`        | Enable AWS X-Ray tracing                                  |
+| `env`         | `EnvironmentValue` | Environment variables for Lambda functions              |
+
+#### Available Services
+
+Services define which AWS resources the Lambda IAM role can access:
+
+| Service         | Description                      |
+| --------------- | -------------------------------- |
+| `dynamodb`      | Amazon DynamoDB                  |
+| `s3`            | Amazon S3                        |
+| `lambda`        | AWS Lambda                       |
+| `cloudwatch`    | Amazon CloudWatch Logs           |
+| `sqs`           | Amazon SQS                       |
+| `state_machine` | AWS Step Functions               |
+| `kms`           | AWS KMS                          |
+| `ssm`           | AWS Systems Manager Parameter Store |
+| `event`         | Amazon EventBridge               |
+
+For fine-grained control, specify individual permissions:
+
+```typescript
+services: [
+  'cloudwatch',
+  { type: 'dynamodb', permissions: ['Query', 'GetItem'] },
+  { type: 's3', permissions: ['GetObject'], resources: ['arn:aws:s3:::my-bucket/*'] },
+  { type: 'custom', serviceName: 'ses', permissions: ['SendEmail'] },
+]
+```
+
+#### Tags
+
+Tags are applied automatically to all taggable resources. Module-level tags merge with app-level tags, and resource-specific tags take highest precedence:
+
+```typescript
+// App-level tags
+globalConfig: {
+  tags: {
+    environment: 'production',
+    project: 'my-app',
+  },
+}
+
+// Module-level tags (merged with app tags)
+globalConfig: {
+  tags: {
+    domain: 'orders',
+  },
+}
+```
+
+Lafken also adds automatic tags: `lafken:app` with the app name and `lafken:module` with the module name.
+
+### S3 Backend
+
+Store Terraform state remotely in an S3 bucket for team collaboration and state locking:
+
+```typescript
+await createApp({
+  name: 'my-app',
+  s3Backend: {
+    bucket: 'terraform-state-bucket',
+    key: 'apps/my-app/terraform.tfstate',
+    region: 'us-east-1',
+    dynamodbTable: 'terraform-locks',
+  },
+});
+```
+
+### Extending the Application
+
+The `extend` callback runs after all resolvers have finished processing. Use it to add custom infrastructure that is not covered by the standard resolvers:
+
+```typescript
+await createApp({
+  name: 'my-app',
+  modules: [userModule],
+  resolvers: [new ApiResolver()],
+  extend: async (scope) => {
+    // Add any CDKTN construct directly to the stack
+  },
+});
+```

package/lib/app/app.d.ts

@@ -10,6 +10,31 @@ export declare class AppStack extends TerraformStack {
     private createRole;
     private addAspectProperties;
 }
+/**
+ * Creates and synthesizes a Lafken serverless application.
+ *
+ * Initializes the CDKTN application, sets up the AWS stack with the
+ * provided modules and resolvers, executes the full resolver lifecycle
+ * (beforeCreate → create → afterCreate), and synthesizes the resulting
+ * Terraform configuration.
+ *
+ * @param props - The application configuration including name, modules,
+ * resolvers, global settings, and optional extensions.
+ * @returns The CDKTN `App` instance and the `AppStack` created for the application.
+ *
+ * @example
+ * await createApp({
+ *   name: 'my-app',
+ *   modules: [
+ *     //... ,
+ *   ],
+ *   resolvers: [new ApiResolver({ restApi: { name: 'my-api' } })],
+ *   globalConfig: {
+ *     lambda: { runtime: 22, memory: 512 },
+ *     tags: { environment: 'production' },
+ *   },
+ * });
+ */
 export declare const createApp: (props: CreateAppProps) => Promise<{
     app: App;
     appStack: AppStack;

package/lib/app/app.js

@@ -26,6 +26,9 @@ class AppStack extends cdktn_1.TerraformStack {
             contextCreator: props.name,
         });
         new provider_1.AwsProvider(this, 'AWS', props.awsProviderConfig);
+        if (props.s3Backend) {
+            new cdktn_1.S3Backend(this, props.s3Backend);
+        }
         this.createRole();
     }
     async init() {
@@ -83,6 +86,31 @@ class AppStack extends cdktn_1.TerraformStack {
     }
 }
 exports.AppStack = AppStack;
+/**
+ * Creates and synthesizes a Lafken serverless application.
+ *
+ * Initializes the CDKTN application, sets up the AWS stack with the
+ * provided modules and resolvers, executes the full resolver lifecycle
+ * (beforeCreate → create → afterCreate), and synthesizes the resulting
+ * Terraform configuration.
+ *
+ * @param props - The application configuration including name, modules,
+ * resolvers, global settings, and optional extensions.
+ * @returns The CDKTN `App` instance and the `AppStack` created for the application.
+ *
+ * @example
+ * await createApp({
+ *   name: 'my-app',
+ *   modules: [
+ *     //... ,
+ *   ],
+ *   resolvers: [new ApiResolver({ restApi: { name: 'my-api' } })],
+ *   globalConfig: {
+ *     lambda: { runtime: 22, memory: 512 },
+ *     tags: { environment: 'production' },
+ *   },
+ * });
+ */
 const createApp = async (props) => {
     const app = new cdktn_1.App({
         skipValidation: true,

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

@@ -1,9 +1,32 @@
 import type { AwsProviderConfig } from '@cdktn/provider-aws/lib/provider';
 import type { LambdaGlobalConfig, ResolverType } from '@lafken/resolver';
+import type { S3BackendConfig } from 'cdktn';
 import type { StackModule } from '../module';
 import type { ModuleResolverType } from '../module/module.types';
 import type { AppStack } from './app';
+/**
+ * Global configuration for the application.
+ *
+ * Defines shared settings that apply across all resources and Lambda
+ * functions in the application. Individual resources can override
+ * these values with their own specific configuration.
+ */
 export interface GlobalConfig {
+    /**
+     * Global Lambda configuration.
+     *
+     * Specifies default properties for all Lambda functions in the
+     * application, such as memory, timeout, runtime, and services.
+     * These values can be overridden at the module or resource level.
+     *
+     * @example
+     * lambda: {
+     *   memory: 512,
+     *   timeout: 30,
+     *   runtime: 22,
+     *   services: ['s3', 'dynamodb'],
+     * }
+     */
     lambda?: LambdaGlobalConfig;
     /**
      * Global resource tags.
@@ -29,6 +52,18 @@ export interface CreateAppProps {
      * Application modules.
      *
      * Defines the set of modules to be created within the application.
+     * Each module groups related resources and handlers into a logical
+     * unit with shared configuration. Modules are created using
+     * `createModule()` and receive the application stack scope along
+     * with the registered resolvers.
+     *
+     * @example
+     * modules: [
+     *   createModule({
+     *     name: 'users',
+     *     resources: [UserApi, UserQueue],
+     *   }),
+     * ]
      */
     modules: ((scope: AppStack, resources: Record<string, ModuleResolverType>) => Promise<StackModule>)[];
     /**
@@ -52,11 +87,49 @@ export interface CreateAppProps {
      */
     globalConfig?: GlobalConfig;
     /**
+     * AWS provider configuration.
      *
+     * Specifies the configuration for the AWS provider used by the
+     * application stack. This includes settings such as the AWS region,
+     * profile, and other provider-level options required for
+     * deploying resources.
+     *
+     * @example
+     * awsProviderConfig: {
+     *   region: 'us-east-1',
+     *   profile: 'my-aws-profile',
+     * }
      */
     awsProviderConfig?: AwsProviderConfig;
     /**
+     * S3 backend configuration for Terraform state.
      *
+     * Configures an S3 bucket as the remote backend for storing the
+     * Terraform state file. This enables team collaboration, state
+     * locking, and centralized state management.
+     *
+     * @example
+     * s3Backend: {
+     *   bucket: 'my-terraform-state',
+     *   key: 'app/terraform.tfstate',
+     *   region: 'us-east-1',
+     * }
+     */
+    s3Backend?: S3BackendConfig;
+    /**
+     * Extension callback.
+     *
+     * An optional async callback that is invoked after all modules and
+     * resolvers have been fully processed. Use this to add custom
+     * infrastructure or perform additional configuration on the
+     * application stack that is not covered by the standard resolvers.
+     *
+     * @param scope - The application stack instance.
+     *
+     * @example
+     * extend: async (scope) => {
+     *   new S3Bucket(scope, 'custom-bucket', { bucket: 'my-bucket' });
+     * }
      */
     extend?: (scope: AppStack) => Promise<void>;
 }

package/lib/module/module.d.ts

@@ -8,4 +8,28 @@ export declare class StackModule extends Construct {
     private createRole;
     private addAspectProperties;
 }
+/**
+ * Creates a module factory for the Lafken application.
+ *
+ * Returns a function that, when invoked by `createApp`, instantiates a
+ * `StackModule` and processes all its declared resources through the
+ * registered resolvers. Each module groups related resources into a
+ * logical unit with its own scope, IAM role, tags, and optional
+ * Lambda configuration.
+ *
+ * @param props - The module configuration including name, resources, and
+ * optional global settings scoped to this module.
+ * @returns A factory function consumed by `createApp` to build the module
+ * within the application stack.
+ *
+ * @example
+ * createModule({
+ *   name: 'users',
+ *   resources: [UserApi, UserQueue],
+ *   globalConfig: {
+ *     lambda: { memory: 256, services: ['dynamodb'] },
+ *     tags: { team: 'backend' },
+ *   },
+ * })
+ */
 export declare const createModule: (props: CreateModuleProps) => (scope: ModuleConstruct, resolvers: Record<string, ModuleResolverType>) => Promise<StackModule>;

package/lib/module/module.js

@@ -54,6 +54,30 @@ class StackModule extends constructs_1.Construct {
     }
 }
 exports.StackModule = StackModule;
+/**
+ * Creates a module factory for the Lafken application.
+ *
+ * Returns a function that, when invoked by `createApp`, instantiates a
+ * `StackModule` and processes all its declared resources through the
+ * registered resolvers. Each module groups related resources into a
+ * logical unit with its own scope, IAM role, tags, and optional
+ * Lambda configuration.
+ *
+ * @param props - The module configuration including name, resources, and
+ * optional global settings scoped to this module.
+ * @returns A factory function consumed by `createApp` to build the module
+ * within the application stack.
+ *
+ * @example
+ * createModule({
+ *   name: 'users',
+ *   resources: [UserApi, UserQueue],
+ *   globalConfig: {
+ *     lambda: { memory: 256, services: ['dynamodb'] },
+ *     tags: { team: 'backend' },
+ *   },
+ * })
+ */
 const createModule = (props) => async (scope, resolvers) => {
     const module = new StackModule(scope, props.name, {
         ...props,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lafken/main",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": false,
   "description": "Lafken core engine - orchestrate AWS serverless infrastructure using decorators with automatic CDKTN code generation",
   "keywords": [
@@ -31,17 +31,15 @@
   "dependencies": {
     "pretty-error": "^4.0.0",
     "reflect-metadata": "^0.2.2",
-    "@lafken/resolver": "0.7.0"
+    "@lafken/resolver": "0.8.0"
   },
   "devDependencies": {
     "@cdktn/provider-aws": "^23.0.0",
-    "@types/jest": "^30.0.0",
     "cdktn": "^0.22.0",
+    "cdktn-vitest": "^1.0.0",
     "constructs": "^10.4.5",
-    "jest": "^30.2.0",
-    "ts-jest": "^29.4.6",
-    "ts-node": "^10.9.2",
-    "@lafken/common": "0.7.0"
+    "vitest": "^4.0.18",
+    "@lafken/common": "0.8.0"
   },
   "peerDependencies": {
     "@cdktn/provider-aws": "^23.0.0",
@@ -57,9 +55,9 @@
   },
   "scripts": {
     "build": "pnpm clean && tsc -p ./tsconfig.build.json",
+    "check-types": "tsc --noEmit -p ./tsconfig.build.json",
     "clean": "rm -rf ./lib",
     "dev": "tsc -w",
-    "test": "jest",
-    "test:coverage": "jest --coverage"
+    "test": "vitest"
   }
 }