https://github.com/floydspace/aws-lambda-effect-runtime
Experimental Effect-TS custom runtime for AWS Lambda
https://github.com/floydspace/aws-lambda-effect-runtime
aws aws-lambda aws-lambda-layer effect-ts extensions lambda-layer runtime
Last synced: 9 months ago
JSON representation
Experimental Effect-TS custom runtime for AWS Lambda
- Host: GitHub
- URL: https://github.com/floydspace/aws-lambda-effect-runtime
- Owner: floydspace
- Created: 2025-02-22T22:23:09.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-03-03T20:40:12.000Z (10 months ago)
- Last Synced: 2025-03-12T01:27:00.587Z (10 months ago)
- Topics: aws, aws-lambda, aws-lambda-layer, effect-ts, extensions, lambda-layer, runtime
- Language: TypeScript
- Homepage:
- Size: 52.7 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# aws-lambda-effect-runtime
A custom runtime layer that runs "Effectful" lambda functions.
The idea is to have an option to implement lambda functions returning `Effect` type from [effect](https://github.com/Effect-TS/effect) library.
## Setup
First, you will need to deploy the layer to your AWS account. Clone this repository and run the `build-layer` script to prepare the layer for distribution. Then run the `publish-layer` script to publish the layer to your AWS account.
```sh
git clone https://github.com/floydspace/aws-lambda-effect-runtime.git
cd aws-lambda-effect-runtime
pnpm install
pnpm publish-layer
```
## Usage
Once you publish the layer to your AWS account, you can create a Lambda function that uses the layer.
### Step 1: Create a Lambda handler function that returns an `Effect` type
Example of an effectful lambda handler implementing the `EffectHandler` type from [`@effect-aws/lambda`](https://github.com/floydspace/effect-aws/tree/main/packages/lambda):
```typescript
import type { SNSEvent } from "aws-lambda"
import { Effect } from "effect"
import type { EffectHandler } from "@effect-aws/lambda"
// Define your effect handler
export const handler: EffectHandler = (event, context) => {
// Your effect logic here
return Effect.logInfo("Hello, World!")
}
```
or with global layer:
```typescript
import type { SNSEvent } from "aws-lambda"
import { Effect, Logger } from "effect"
import type { EffectHandlerWithLayer } from "@effect-aws/lambda"
// Define your effect handler with global layer
export const handler: EffectHandlerWithLayer = {
handler: (event, context) => {
// Your effect logic here
return Effect.logInfo("Hello, World!")
},
layer: Logger.pretty,
};
```
The global layer will be constructed on lambda cold-start and finalized on shutdown. (How cool is that, huh!)
### Step 2: Build the handler
You can transpile your handler function to JavaScript or bundle it. Here's how you can do it using `esbuild`:
1. Run `esbuild src/handler.ts --bundle --platform=node --target=node22 --external:@effect/platform --external:effect --outfile=dist/handler.js`
2. Zip the `/dist` folder
_Note_: Make sure you exclude `effect` and `@effect/platform` from the bundle. Those dependencies are provided by the layer.
### Step 3: Create the Lambda function on AWS
Once you've written your Lambda function, you need to configure a new Lambda function to the layer. The following steps apply to configuring in the console, CloudFormation, CDK, Terraform, or any other configuration management option for AWS:
1. Create the Lambda function
2. Set the Runtime to custom with Amazon Linux 2023
3. Set the handler to `.` (e.g. `src/handler.effectHandler`)
4. Set the architecture to whichever architecture you configured when you built/deployed the Lambda Layer
5. Attach the Lambda Layer to your new function
6. Upload the zip file from step 2. You can do this in the console directly, upload to S3 and set that as the location for the handler file in Lambda, or use something like CDK to manage this for you.