Refactor/access to lambda event (#157)

* feat: implement LambdaHandler.LambdaHandlerArgs accessor

* docs: add changeset

* fix: improve lambda types

* docs: update changeset doc

Author: floydspace

.changeset/tasty-rice-trade.md

@@ -0,0 +1,26 @@
+---
+"@effect-aws/lambda": patch
+---
+
+Implement `LambdaHandler.event()` and `LambdaHandler.context()` to access raw lambda event and context
+
+Just yield them within api handler:
+
+```ts
+//...
+import { type APIGatewayProxyEvent, LambdaHandler } from "@effect-aws/lambda"
+//...
+const HelloLive = HttpApiBuilder.group(MyApi, "hello", (handlers) =>
+  handlers.handle("hello", () =>
+    Effect.gen(function* () {
+      const event = yield* LambdaHandler.event<APIGatewayProxyEvent>()
+      const context = yield* LambdaHandler.context()
+
+      yield* Effect.logInfo("Lambda event", { event, context })
+
+      return yield* Effect.succeed("Hello, World!")
+    })
+  )
+)
+//...
+```

packages/lambda/README.md

@@ -20,9 +20,8 @@ npm install --save @effect-aws/lambda
 Without dependencies:
 
 ```typescript
-import type { SNSEvent } from "aws-lambda"
 import { Effect } from "effect"
-import { EffectHandler, makeLambda } from "@effect-aws/lambda"
+import { EffectHandler, makeLambda, SNSEvent } from "@effect-aws/lambda"
 
 // Define your effect handler
 const myEffectHandler: EffectHandler<SNSEvent, never> = (event, context) => {
@@ -37,9 +36,8 @@ export const handler = makeLambda(myEffectHandler)
 With dependencies:
 
 ```typescript
-import { EffectHandler, makeLambda } from "@effect-aws/lambda"
+import { EffectHandler, makeLambda, SNSEvent } from "@effect-aws/lambda"
 import * as Logger from "@effect-aws/powertools-logger"
-import type { SNSEvent } from "aws-lambda"
 import { Context, Effect, Layer } from "effect"
 
 interface FooService {

packages/lambda/src/Compatibility.ts

@@ -9,22 +9,20 @@ import * as LambdaRuntime from "./LambdaRuntime.js";
  * The global layer is used to provide a runtime which will gracefully handle lambda termination during down-scaling.
  *
  * @example
- * import { makeLambda } from "@effect-aws/lambda";
- * import { Context } from "aws-lambda";
+ * import { makeLambda, LambdaContext } from "@effect-aws/lambda";
  * import { Effect } from "effect";
  *
- * const effectHandler = (event: unknown, context: Context) => {
+ * const effectHandler = (event: unknown, context: LambdaContext) => {
  *  return Effect.logInfo("Hello, world!");
  * };
  *
  * export const handler = makeLambda(effectHandler);
  *
  * @example
- * import { makeLambda } from "@effect-aws/lambda";
- * import { Context } from "aws-lambda";
+ * import { makeLambda, LambdaContext } from "@effect-aws/lambda";
  * import { Effect, Logger } from "effect";
  *
- * const effectHandler = (event: unknown, context: Context) => {
+ * const effectHandler = (event: unknown, context: LambdaContext) => {
  *  return Effect.logInfo("Hello, world!");
  * };
  *
@@ -46,15 +44,14 @@ export const makeLambda = LambdaHandler.make;
  * All finalizers will be executed on process termination or interruption.
  *
  * @example
- * import { fromLayer } from "@effect-aws/lambda";
- * import { Context } from "aws-lambda";
+ * import { fromLayer, LambdaContext } from "@effect-aws/lambda";
  * import { Effect, Logger } from "effect";
  *
  * const LambdaLayer = Logger.replace(Logger.defaultLogger, Logger.logfmtLogger);
  *
  * const lambdaRuntime = fromLayer(LambdaLayer);
  *
- * export const handler = async (event: unknown, context: Context) => {
+ * export const handler = async (event: unknown, context: LambdaContext) => {
  *  return Effect.logInfo("Hello, world!").pipe(lambdaRuntime.runPromise);
  * };
  *

packages/lambda/src/LambdaHandler.ts

@@ -1,37 +1,107 @@
 /**
  * @since 1.4.0
  */
-import type { HttpApi, HttpRouter, HttpServerError } from "@effect/platform";
+import type { HttpApi, HttpRouter } from "@effect/platform";
 import { HttpApiBuilder, HttpApp } from "@effect/platform";
 import type { Cause } from "effect";
 import { Context, Effect, Function, Layer } from "effect";
 import { getEventSource } from "./internal/index.js";
-import type { EventSource, LambdaEvent, LambdaResult } from "./internal/types.js";
+import * as internal from "./internal/lambdaHandler.js";
+import type { EventSource } from "./internal/types.js";
 import { encodeBase64, isContentEncodingBinary, isContentTypeBinary } from "./internal/utils.js";
 import * as LambdaRuntime from "./LambdaRuntime.js";
-import type { EffectHandler, EffectHandlerWithLayer, Handler } from "./Types.js";
+import type {
+  ALBEvent,
+  ALBResult,
+  APIGatewayProxyEvent,
+  APIGatewayProxyEventV2,
+  APIGatewayProxyResult,
+  APIGatewayProxyResultV2,
+  CloudFrontRequestEvent,
+  DynamoDBStreamEvent,
+  EffectHandler,
+  EffectHandlerWithLayer,
+  EventBridgeEvent,
+  Handler,
+  KinesisStreamEvent,
+  LambdaContext,
+  S3Event,
+  SelfManagedKafkaEvent,
+  SNSEvent,
+  SQSEvent,
+} from "./Types.js";
+
+/**
+ * @since 1.4.0
+ */
+export declare namespace LambdaHandler {
+  /**
+   * @since 1.4.0
+   * @category model
+   */
+  export type Event =
+    | ALBEvent
+    | APIGatewayProxyEvent
+    | APIGatewayProxyEventV2
+    | EventBridgeEvent<string, unknown>
+    | DynamoDBStreamEvent
+    | KinesisStreamEvent
+    | S3Event
+    | SelfManagedKafkaEvent
+    | SNSEvent
+    | SQSEvent
+    | CloudFrontRequestEvent;
+
+  /**
+   * @since 1.4.0
+   * @category model
+   */
+  export type Result =
+    | ALBResult
+    | APIGatewayProxyResult
+    | APIGatewayProxyResultV2
+    | void;
+}
+
+/**
+ * @since 1.4.0
+ * @category context
+ */
+export const event = <T extends LambdaHandler.Event>(): Effect.Effect<T> =>
+  Effect.map(
+    Effect.context<never>(),
+    (context) => Context.unsafeGet(context, internal.lambdaEventTag),
+  ) as Effect.Effect<T>;
+
+/**
+ * @since 1.4.0
+ * @category context
+ */
+export const context = (): Effect.Effect<LambdaContext> =>
+  Effect.map(
+    Effect.context<never>(),
+    (context) => Context.unsafeGet(context, internal.lambdaContextTag),
+  );
 
 /**
  * Makes a lambda handler from the given EffectHandler and optional global layer.
  * The global layer is used to provide a runtime which will gracefully handle lambda termination during down-scaling.
  *
  * @example
- * import { LambdaHandler } from "@effect-aws/lambda"
- * import { Context } from "aws-lambda";
+ * import { LambdaHandler, LambdaContext } from "@effect-aws/lambda"
  * import { Effect } from "effect";
  *
- * const effectHandler = (event: unknown, context: Context) => {
+ * const effectHandler = (event: unknown, context: LambdaContext) => {
  *  return Effect.logInfo("Hello, world!");
  * };
  *
  * export const handler = LambdaHandler.make(effectHandler);
  *
  * @example
- * import { LambdaHandler } from "@effect-aws/lambda"
- * import { Context } from "aws-lambda";
+ * import { LambdaHandler, LambdaContext } from "@effect-aws/lambda"
  * import { Effect, Logger } from "effect";
  *
- * const effectHandler = (event: unknown, context: Context) => {
+ * const effectHandler = (event: unknown, context: LambdaContext) => {
  *  return Effect.logInfo("Hello, world!");
  * };
  *
@@ -107,11 +177,18 @@ const WebHandler = Context.GenericTag<WebHandler>("@effect-aws/lambda/WebHandler
 export const makeWebHandler = (options?: Pick<HttpApiOptions, "middleware">): Effect.Effect<
   WebHandler,
   never,
-  HttpApiBuilder.Router | HttpApi.Api | HttpRouter.HttpRouter.DefaultServices | HttpApiBuilder.Middleware
+  | HttpApiBuilder.Router
+  | HttpApi.Api
+  | HttpRouter.HttpRouter.DefaultServices
+  | HttpApiBuilder.Middleware
+  | LambdaHandler.Event
+  | LambdaContext
 > =>
   Effect.gen(function*() {
     const app = yield* HttpApiBuilder.httpApp;
-    const rt = yield* Effect.runtime<HttpRouter.HttpRouter.DefaultServices>();
+    const rt = yield* Effect.runtime<
+      HttpRouter.HttpRouter.DefaultServices | LambdaHandler.Event | LambdaContext
+    >();
     return HttpApp.toWebHandlerRuntime(rt)(
       options?.middleware ? options.middleware(app as any) as any : app,
     );
@@ -123,14 +200,15 @@ export const makeWebHandler = (options?: Pick<HttpApiOptions, "middleware">): Ef
  * @since 1.4.0
  * @category constructors
  */
-export const httpApiHandler: EffectHandler<
-  LambdaEvent,
-  WebHandler,
-  HttpServerError.ResponseError | Cause.UnknownException,
-  LambdaResult
-> = (event) =>
+export const httpApiHandler = (options?: Pick<HttpApiOptions, "middleware">): EffectHandler<
+  LambdaHandler.Event,
+  HttpApi.Api | HttpApiBuilder.Router | HttpRouter.HttpRouter.DefaultServices | HttpApiBuilder.Middleware,
+  Cause.UnknownException,
+  LambdaHandler.Result
+> =>
+(event, context) =>
   Effect.gen(function*() {
-    const eventSource = getEventSource(event) as EventSource<LambdaEvent, LambdaResult>;
+    const eventSource = getEventSource(event) as EventSource<LambdaHandler.Event, LambdaHandler.Result>;
     const requestValues = eventSource.getRequest(event);
 
     const req = new Request(
@@ -142,7 +220,11 @@ export const httpApiHandler: EffectHandler<
       },
     );
 
-    const res = yield* WebHandler.pipe(Effect.andThen((handler) => handler(req)));
+    const res = yield* makeWebHandler(options).pipe(
+      Effect.provideService(internal.lambdaEventTag, event),
+      Effect.provideService(internal.lambdaContextTag, context),
+      Effect.andThen((handler) => handler(req)),
+    );
 
     const contentType = res.headers.get("content-type");
     let isBase64Encoded = contentType && isContentTypeBinary(contentType) ? true : false;
@@ -213,9 +295,7 @@ export const httpApiHandler: EffectHandler<
 export const fromHttpApi = <LA, LE>(
   layer: Layer.Layer<LA | HttpApi.Api | HttpRouter.HttpRouter.DefaultServices, LE>,
   options?: HttpApiOptions,
-): Handler<LambdaEvent, LambdaResult> => {
-  const httpApiLayer = Layer.effect(WebHandler, makeWebHandler(options)).pipe(
-    Layer.provide(Layer.mergeAll(layer, HttpApiBuilder.Router.Live, HttpApiBuilder.Middleware.layer)),
-  );
-  return make({ handler: httpApiHandler, layer: httpApiLayer, memoMap: options?.memoMap });
+): Handler<LambdaHandler.Event, LambdaHandler.Result> => {
+  const httpApiLayer = Layer.mergeAll(layer, HttpApiBuilder.Router.Live, HttpApiBuilder.Middleware.layer);
+  return make({ handler: httpApiHandler(options), layer: httpApiLayer, memoMap: options?.memoMap });
 };

packages/lambda/src/LambdaRuntime.ts

@@ -9,15 +9,14 @@ import { Console, Effect, ManagedRuntime } from "effect";
  * All finalizers will be executed on process termination or interruption.
  *
  * @example
- * import { LambdaRuntime } from "@effect-aws/lambda";
- * import { Context } from "aws-lambda";
+ * import { LambdaRuntime, LambdaContext } from "@effect-aws/lambda";
  * import { Effect, Logger } from "effect";
  *
  * const LambdaLayer = Logger.replace(Logger.defaultLogger, Logger.logfmtLogger);
  *
  * const lambdaRuntime = LambdaRuntime.fromLayer(LambdaLayer);
  *
- * export const handler = async (event: unknown, context: Context) => {
+ * export const handler = async (event: unknown, context: LambdaContext) => {
  *  return Effect.logInfo("Hello, world!").pipe(lambdaRuntime.runPromise);
  * };
  *

packages/lambda/src/Types.ts

@@ -1,7 +1,23 @@
 /**
  * @since 1.0.0
  */
-import type { Context } from "aws-lambda";
+import type {
+  ALBEvent,
+  ALBResult,
+  APIGatewayProxyEvent,
+  APIGatewayProxyEventV2,
+  APIGatewayProxyResult,
+  APIGatewayProxyResultV2,
+  CloudFrontRequestEvent,
+  Context,
+  DynamoDBStreamEvent,
+  EventBridgeEvent,
+  KinesisStreamEvent,
+  S3Event,
+  SelfManagedKafkaEvent,
+  SNSEvent,
+  SQSEvent,
+} from "aws-lambda";
 import { type Layer } from "effect";
 import type * as Effect from "effect/Effect";
 
@@ -41,3 +57,66 @@ export type EffectHandlerWithLayer<T, R, E1 = never, E2 = never, A = void> = {
   readonly layer: Layer.Layer<R, E2>;
   readonly memoMap?: Layer.MemoMap;
 };
+
+export {
+  /**
+   * @since 1.4.0
+   */
+  ALBEvent,
+  /**
+   * @since 1.4.0
+   */
+  ALBResult,
+  /**
+   * @since 1.4.0
+   */
+  APIGatewayProxyEvent,
+  /**
+   * @since 1.4.0
+   */
+  APIGatewayProxyEventV2,
+  /**
+   * @since 1.4.0
+   */
+  APIGatewayProxyResult,
+  /**
+   * @since 1.4.0
+   */
+  APIGatewayProxyResultV2,
+  /**
+   * @since 1.4.0
+   */
+  CloudFrontRequestEvent,
+  /**
+   * @since 1.4.0
+   */
+  Context as LambdaContext,
+  /**
+   * @since 1.4.0
+   */
+  DynamoDBStreamEvent,
+  /**
+   * @since 1.4.0
+   */
+  EventBridgeEvent,
+  /**
+   * @since 1.4.0
+   */
+  KinesisStreamEvent,
+  /**
+   * @since 1.4.0
+   */
+  S3Event,
+  /**
+   * @since 1.4.0
+   */
+  SelfManagedKafkaEvent,
+  /**
+   * @since 1.4.0
+   */
+  SNSEvent,
+  /**
+   * @since 1.4.0
+   */
+  SQSEvent,
+};

packages/lambda/src/internal/aws/alb.ts

@@ -1,6 +1,6 @@
 import url from "node:url";
 
-import type { ALBEvent, ALBResult } from "aws-lambda";
+import type { ALBEvent, ALBResult } from "../../Types.js";
 import type { EventSource } from "../types.js";
 import { getMultiValueHeaders, getRequestValuesFromEvent } from "../utils.js";