@lafken/standalone 0.12.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,177 @@
+# @lafken/standalone
+
+Define standalone AWS Lambda functions using TypeScript decorators. `@lafken/standalone` lets you declare independent Lambda handlers that can be invoked by other services, and automatically wires them up with optional IAM invoke roles and global references.
+
+## Installation
+
+```bash
+npm install @lafken/standalone
+```
+
+## Getting Started
+
+Define a standalone class with `@Standalone`, add `@Handler` methods, and register everything through `StandaloneResolver`:
+
+```typescript
+import { createApp, createModule } from '@lafken/main';
+import { StandaloneResolver } from '@lafken/standalone/resolver';
+import { Standalone, Handler } from '@lafken/standalone/main';
+
+// 1. Define standalone handlers
+@Standalone()
+export class OrderFunctions {
+  @Handler()
+  processOrder() {
+    console.log('Processing order...');
+  }
+}
+
+// 2. Register in a module
+const orderModule = createModule({
+  name: 'order',
+  resources: [OrderFunctions],
+});
+
+// 3. Add the resolver to the app
+createApp({
+  name: 'my-app',
+  resolvers: [new StandaloneResolver()],
+  modules: [orderModule],
+});
+```
+
+Each `@Handler` method becomes an independent Lambda function ready to be invoked by other services.
+
+## Features
+
+### Standalone Class
+
+Use the `@Standalone` decorator to group related Lambda handlers in a single class:
+
+```typescript
+import { Standalone, Handler } from '@lafken/standalone/main';
+
+@Standalone()
+export class NotificationFunctions {
+  @Handler()
+  sendEmail() { }
+
+  @Handler()
+  sendSms() { }
+}
+```
+
+### Custom Handler Name
+
+By default the method name is used as the Lambda handler identifier. Override it with the `name` option:
+
+```typescript
+@Handler({ name: 'process-payment' })
+handlePayment() { }
+```
+
+### Invoke Role
+
+Configure an IAM role that grants another principal permission to invoke the Lambda. When `invocator` is provided, a dedicated invoke role is created and attached to the function:
+
+```typescript
+@Handler({
+  invocator: {
+    principalRole: 'apigateway.amazonaws.com',
+    services: [
+      {
+        type: 'execute-api',
+        permissions: ['Invoke'],
+        resources: ['*'],
+      },
+    ],
+    roleRef: 'processOrderInvokeRole',
+  },
+})
+processOrder() { }
+```
+
+#### Invocator Options
+
+| Option               | Type             | Description                                                                 |
+| -------------------- | ---------------- | --------------------------------------------------------------------------- |
+| `principalRole`      | `string`         | AWS service or account ARN allowed to assume the role                       |
+| `principalPermission`| `string`         | Permission level for the principal                                          |
+| `services`           | `ServicesValues` | Additional IAM policy statements to include in the role                     |
+| `roleRef`            | `string`         | Name to register the created role as a global reference                     |
+
+### Global References
+
+Use `ref` to register the Lambda function as a named global reference so other resources can access its attributes (e.g. ARN, function name):
+
+```typescript
+@Handler({
+  ref: 'processOrderLambda',
+})
+processOrder() { }
+```
+
+### Lambda Configuration
+
+Pass any Lambda-specific settings through the `lambda` option:
+
+```typescript
+@Handler({
+  lambda: {
+    timeout: 30,
+    memorySize: 512,
+    environment: {
+      QUEUE_URL: 'https://sqs.us-east-1.amazonaws.com/...',
+    },
+  },
+})
+processOrder() { }
+```
+
+### Full Example
+
+```typescript
+import { createApp, createModule } from '@lafken/main';
+import { StandaloneResolver } from '@lafken/standalone/resolver';
+import { Standalone, Handler } from '@lafken/standalone/main';
+
+@Standalone()
+export class PaymentFunctions {
+  @Handler({
+    name: 'process-payment',
+    ref: 'processPaymentLambda',
+    invocator: {
+      principalRole: 'apigateway.amazonaws.com',
+      services: [
+        {
+          type: 'execute-api',
+          permissions: ['Invoke'],
+          resources: ['*'],
+        },
+      ],
+      roleRef: 'processPaymentInvokeRole',
+    },
+    lambda: {
+      timeout: 30,
+      memorySize: 256,
+    },
+  })
+  processPayment() { }
+
+  @Handler({
+    ref: 'refundPaymentLambda',
+  })
+  refundPayment() { }
+}
+
+const paymentModule = createModule({
+  name: 'payment',
+  resources: [PaymentFunctions],
+});
+
+createApp({
+  name: 'my-app',
+  resolvers: [new StandaloneResolver()],
+  modules: [paymentModule],
+});
+```

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './main';
+export * from './resolver';

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("./main"), exports);
+__exportStar(require("./resolver"), exports);

package/lib/main/index.d.ts

@@ -0,0 +1 @@
+export * from './standalone';

package/lib/main/index.js

@@ -0,0 +1,17 @@
+"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("./standalone"), exports);

package/lib/main/standalone/index.d.ts

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

package/lib/main/standalone/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("./standalone"), exports);
+__exportStar(require("./standalone.types"), exports);

package/lib/main/standalone/standalone.d.ts

@@ -0,0 +1,38 @@
+import { type HandlerProps } from './standalone.types';
+/**
+ * Class decorator that marks a class as a standalone Lambda resource module.
+ * The resolver uses the metadata stored by this decorator to discover and wire
+ * up all `@Handler`-decorated methods within the class.
+ *
+ * @example
+ * @Standalone()
+ * export class MyFunctions {
+ *   @Handler()
+ *   myHandler() {}
+ * }
+ */
+export declare const Standalone: (props?: import("@lafken/common").ResourceProps | undefined) => (constructor: Function) => void;
+/**
+ * Method decorator that registers a class method as a Lambda handler.
+ * The decorated method becomes the entry point of a Lambda function; its name
+ * (or the explicit `name` prop) is used as the logical function identifier.
+ *
+ * @example
+ * // Minimal — uses the method name as the handler name
+ * @Handler()
+ * myHandler() {}
+ *
+ * @example
+ * // Custom name + invoke role for API Gateway
+ * @Handler({
+ *   name: 'my-handler',
+ *   invocator: {
+ *     principal: 'apigateway.amazonaws.com',
+ *     services: (props) => [{ type: 'execute-api', permissions: ['Invoke'], resources: [props.arn] }],
+ *     roleRef: 'myHandlerInvokeRole',
+ *   },
+ *   ref: 'myHandler',
+ * })
+ * myHandler() {}
+ */
+export declare const Handler: (props?: HandlerProps | undefined) => (target: any, methodName: string, descriptor: PropertyDescriptor) => any;

package/lib/main/standalone/standalone.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Handler = exports.Standalone = void 0;
+const common_1 = require("@lafken/common");
+const standalone_types_1 = require("./standalone.types");
+/**
+ * Class decorator that marks a class as a standalone Lambda resource module.
+ * The resolver uses the metadata stored by this decorator to discover and wire
+ * up all `@Handler`-decorated methods within the class.
+ *
+ * @example
+ * @Standalone()
+ * export class MyFunctions {
+ *   @Handler()
+ *   myHandler() {}
+ * }
+ */
+exports.Standalone = (0, common_1.createResourceDecorator)({
+    type: standalone_types_1.RESOURCE_TYPE,
+});
+/**
+ * Method decorator that registers a class method as a Lambda handler.
+ * The decorated method becomes the entry point of a Lambda function; its name
+ * (or the explicit `name` prop) is used as the logical function identifier.
+ *
+ * @example
+ * // Minimal — uses the method name as the handler name
+ * @Handler()
+ * myHandler() {}
+ *
+ * @example
+ * // Custom name + invoke role for API Gateway
+ * @Handler({
+ *   name: 'my-handler',
+ *   invocator: {
+ *     principal: 'apigateway.amazonaws.com',
+ *     services: (props) => [{ type: 'execute-api', permissions: ['Invoke'], resources: [props.arn] }],
+ *     roleRef: 'myHandlerInvokeRole',
+ *   },
+ *   ref: 'myHandler',
+ * })
+ * myHandler() {}
+ */
+exports.Handler = (0, common_1.createLambdaDecorator)({
+    getLambdaMetadata: (props, methodName) => ({
+        ...props,
+        name: props.name || methodName,
+    }),
+});

package/lib/main/standalone/standalone.types.d.ts

@@ -0,0 +1,47 @@
+import type { LambdaMetadata, LambdaProps, ServicesValues } from '@lafken/common';
+export declare const RESOURCE_TYPE = "standalone";
+export interface HandlerProps {
+    /**
+     * The logical name used to identify this Lambda handler within the stack.
+     * Defaults to the function's file or export name if not provided.
+     *
+     * @example
+     * name: 'myHandler'
+     */
+    name?: string;
+    /**
+     * Configures an IAM role that grants another principal permission to invoke
+     * this Lambda function. When provided, a dedicated invoke role is created and
+     * attached to the function.
+     *
+     * - `principal` — the AWS service or account ARN allowed to assume the role
+     *   (e.g. `'apigateway.amazonaws.com'`).
+     * - `services` — additional IAM policy statements to include in the role.
+     * - `roleRef` — registers the created role as a named global reference so
+     *   other resources can look it up by name.
+     *
+     * @example
+     * invocator: {
+     *   principal: 'apigateway.amazonaws.com',
+     *   services: [{ type: 'lambda', permissions: ['InvokeFunction'], resources: ['*'] }],
+     *   roleRef: 'myHandlerInvokeRole',
+     * }
+     */
+    invocator?: {
+        principalRole?: string;
+        principalPermission?: string;
+        services?: ServicesValues;
+        roleRef?: string;
+    };
+    lambda?: LambdaProps;
+    /**
+     * Registers this Lambda function as a named global reference, allowing other
+     * resources to access its attributes (e.g. ARN, function name) by reference name.
+     *
+     * @example
+     * ref: 'myHandler'
+     */
+    ref?: string;
+}
+export interface HandlerMetadata extends Omit<HandlerProps, 'name'>, LambdaMetadata {
+}

package/lib/main/standalone/standalone.types.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESOURCE_TYPE = void 0;
+exports.RESOURCE_TYPE = 'standalone';

package/lib/resolver/handler/handler.d.ts

@@ -0,0 +1,16 @@
+import { type AppModule, LambdaHandler } from '@lafken/resolver';
+import type { HandlerProps } from './handler.types';
+declare const GlobalLambdaHandler: (new (...args: any[]) => {
+    register(namespaces: import("@lafken/common").RegisterNamespaces | (string & {}), id: string): void;
+    onResolve(callback: () => void): void;
+    readonly node: import("constructs").Node;
+    with(...mixins: import("constructs").IMixin[]): import("constructs").IConstruct;
+    toString(): string;
+}) & typeof LambdaHandler;
+export declare class Handler extends GlobalLambdaHandler {
+    protected scope: AppModule;
+    protected props: HandlerProps;
+    constructor(scope: AppModule, id: string, props: HandlerProps);
+    private createInvokeRole;
+}
+export {};

package/lib/resolver/handler/handler.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Handler = void 0;
+const resolver_1 = require("@lafken/resolver");
+const GlobalLambdaHandler = resolver_1.lafkenResource.make(resolver_1.LambdaHandler);
+class Handler extends GlobalLambdaHandler {
+    scope;
+    props;
+    constructor(scope, id, props) {
+        const { handlerMetadata, resourceMetadata } = props;
+        super(scope, id, {
+            filename: resourceMetadata.filename,
+            foldername: resourceMetadata.foldername,
+            name: handlerMetadata.name,
+            originalName: resourceMetadata.originalName,
+            lambda: handlerMetadata.lambda,
+            principal: handlerMetadata?.invocator?.principalPermission,
+        });
+        this.scope = scope;
+        this.props = props;
+        this.createInvokeRole(id);
+        if (props.handlerMetadata.ref) {
+            this.register('lambda', props.handlerMetadata.ref);
+        }
+    }
+    createInvokeRole(id) {
+        const { invocator = {} } = this.props.handlerMetadata;
+        const { principalPermission: _exclude, ...rolePermissions } = invocator;
+        if (Object.values(rolePermissions).length === 0) {
+            return;
+        }
+        const appContext = (0, resolver_1.getAppContext)(this);
+        const role = new resolver_1.Role(this, 'handler-role', {
+            name: `${appContext.contextCreator}-${id.toLocaleLowerCase()}-invoke-role`,
+            principal: rolePermissions.principalRole,
+            services: (props) => [
+                ...(Array.isArray(rolePermissions.services) ||
+                    rolePermissions.services === undefined
+                    ? rolePermissions.services || []
+                    : rolePermissions.services(props)),
+                {
+                    type: 'lambda',
+                    permissions: ['InvokeFunction'],
+                    resources: [this.arn],
+                },
+            ],
+        });
+        if (this.props.handlerMetadata.ref) {
+            role.register('lambda', this.props.handlerMetadata.ref);
+        }
+    }
+}
+exports.Handler = Handler;

package/lib/resolver/handler/handler.types.d.ts

@@ -0,0 +1,6 @@
+import type { ResourceMetadata } from '@lafken/common';
+import type { HandlerMetadata } from '../../main';
+export interface HandlerProps {
+    resourceMetadata: ResourceMetadata;
+    handlerMetadata: HandlerMetadata;
+}

package/lib/resolver/handler/handler.types.js

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

package/lib/resolver/index.d.ts

@@ -0,0 +1 @@
+export * from './resolver';

package/lib/resolver/index.js

@@ -0,0 +1,17 @@
+"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("./resolver"), exports);

package/lib/resolver/resolver.d.ts

@@ -0,0 +1,6 @@
+import { type ClassResource } from '@lafken/common';
+import { type AppModule, type ResolverType } from '@lafken/resolver';
+export declare class StandaloneResolver implements ResolverType {
+    type: string;
+    create(module: AppModule, resource: ClassResource): void;
+}

package/lib/resolver/resolver.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StandaloneResolver = void 0;
+const common_1 = require("@lafken/common");
+const resolver_1 = require("@lafken/resolver");
+const main_1 = require("../main");
+const handler_1 = require("./handler/handler");
+class StandaloneResolver {
+    type = main_1.RESOURCE_TYPE;
+    create(module, resource) {
+        const minify = (0, resolver_1.getContextValueByScope)(module, 'minify');
+        const metadata = (0, common_1.getResourceMetadata)(resource);
+        const handlers = (0, common_1.getResourceHandlerMetadata)(resource);
+        resolver_1.lambdaAssets.initializeMetadata({
+            foldername: metadata.foldername,
+            filename: metadata.filename,
+            minify: metadata.minify ?? minify,
+            className: metadata.originalName,
+            methods: handlers.map((handler) => handler.name),
+        });
+        for (const handler of handlers) {
+            new handler_1.Handler(module, `${handler.name}-${metadata.name}`, {
+                handlerMetadata: handler,
+                resourceMetadata: metadata,
+            });
+        }
+    }
+}
+exports.StandaloneResolver = StandaloneResolver;

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@lafken/standalone",
+  "version": "0.12.0",
+  "private": false,
+  "description": "Define Lambdas using TypeScript decorators - serverless event-driven infrastructure",
+  "keywords": [
+    "aws",
+    "lambda",
+    "serverless",
+    "typescript",
+    "decorators",
+    "lafken"
+  ],
+  "homepage": "https://github.com/Hero64/lafken#readme",
+  "bugs": "https://github.com/Hero64/lafken/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Hero64/lafken",
+    "directory": "packages/event"
+  },
+  "license": "MIT",
+  "author": "Aníbal Jorquera",
+  "exports": {
+    "./main": {
+      "import": "./lib/main/index.js",
+      "types": "./lib/main/index.d.ts",
+      "require": "./lib/main/index.js"
+    },
+    "./resolver": {
+      "import": "./lib/resolver/index.js",
+      "types": "./lib/resolver/index.d.ts",
+      "require": "./lib/resolver/index.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "main": [
+        "./lib/main/index.d.ts"
+      ],
+      "resolver": [
+        "./lib/resolver/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "dependencies": {
+    "reflect-metadata": "^0.2.2",
+    "@lafken/resolver": "0.12.0"
+  },
+  "devDependencies": {
+    "@cdktn/provider-aws": "^24.0.0",
+    "@swc/core": "^1.15.33",
+    "@swc/helpers": "^0.5.21",
+    "@vitest/runner": "^4.1.5",
+    "cdktn": "^0.23.0",
+    "cdktn-vitest": "^1.0.0",
+    "constructs": "^10.6.0",
+    "typescript": "6.0.3",
+    "unplugin-swc": "^1.5.9",
+    "vitest": "^4.1.5",
+    "@lafken/common": "0.12.0"
+  },
+  "peerDependencies": {
+    "@cdktn/provider-aws": ">=23.0.0",
+    "cdktn": ">=0.22.0",
+    "constructs": "^10.4.5",
+    "@lafken/common": "0.12.0"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "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": "vitest"
+  }
+}