address PR comments

Author: svozza

package-lock.json

@@ -125,8 +125,7 @@
     "url": "https://github.com/aws-powertools/powertools-lambda-typescript/issues"
   },
   "dependencies": {
-    "@aws-lambda-powertools/commons": "2.27.0",
-    "lambda-stream": "0.6.0"
+    "@aws-lambda-powertools/commons": "2.27.0"
   },
   "keywords": [
     "aws",

packages/event-handler/package.json

@@ -7,7 +7,6 @@ import {
   isDevMode,
 } from '@aws-lambda-powertools/commons/utils/env';
 import type { APIGatewayProxyResult, Context } from 'aws-lambda';
-import type { ResolveStreamOptions } from '../types/common.js';
 import type { HandlerResponse, ResolveOptions } from '../types/index.js';
 import type {
   ErrorConstructor,
@@ -17,6 +16,7 @@ import type {
   Middleware,
   Path,
   RequestContext,
+  ResolveStreamOptions,
   ResponseStream,
   RestRouteOptions,
   RestRouterOptions,

packages/event-handler/src/rest/Router.ts

@@ -1,4 +1,4 @@
-import { Readable } from 'node:stream';
+import { Readable, Writable } from 'node:stream';
 import { isRecord, isString } from '@aws-lambda-powertools/commons/typeutils';
 import type { APIGatewayProxyEvent } from 'aws-lambda';
 import type {
@@ -239,7 +239,13 @@ export const resolvePrefixedPath = (path: Path, prefix?: Path): Path => {
 
 export const HttpResponseStream =
   globalThis.awslambda?.HttpResponseStream ??
-  class HttpResponseStream {
+  class LocalHttpResponseStream extends Writable {
+    #contentType: string | undefined;
+
+    setContentType(contentType: string) {
+      this.#contentType = contentType;
+    }
+
     static from(
       underlyingStream: ResponseStream,
       prelude: Record<string, string>

packages/event-handler/src/rest/utils.ts

@@ -1,7 +1,3 @@
-import type { AppSyncEventsResolver } from '../appsync-events/AppSyncEventsResolver.js';
-import type { AppSyncGraphQLResolver } from '../appsync-graphql/AppSyncGraphQLResolver.js';
-import type { ResponseStream } from './rest.js';
-
 // biome-ignore lint/suspicious/noExplicitAny: We intentionally use `any` here to represent any type of data and keep the logger is as flexible as possible.
 type Anything = any;
 
@@ -43,9 +39,4 @@ type ResolveOptions = {
   scope?: unknown;
 };
 
-type ResolveStreamOptions = {
-  scope?: unknown;
-  responseStream: ResponseStream;
-};
-
-export type { Anything, ResolveOptions, ResolveStreamOptions };
+export type { Anything, ResolveOptions };

packages/event-handler/src/types/common.ts

@@ -8,9 +8,9 @@ import type {
   APIGatewayProxyResult,
   Context,
 } from 'aws-lambda';
-import type { ResponseStream as LambdaResponseStream } from 'lambda-stream';
 import type { HttpStatusCodes, HttpVerbs } from '../rest/constants.js';
 import type { Route } from '../rest/Route.js';
+import type { HttpResponseStream } from '../rest/utils.js';
 import type { ResolveOptions } from './common.js';
 
 type RequestContext = {
@@ -65,10 +65,6 @@ type ExtendedAPIGatewayProxyResult = Omit<APIGatewayProxyResult, 'body'> & {
   body: ExtendedAPIGatewayProxyResultBody;
 };
 
-type ResponseStream = LambdaResponseStream & {
-  _onBeforeFirstWrite?: (write: (data: Uint8Array | string) => void) => void;
-};
-
 type HandlerResponse = Response | JSONObject | ExtendedAPIGatewayProxyResult;
 
 type RouteHandler<TReturn = HandlerResponse> = (
@@ -126,6 +122,51 @@ type ValidationResult = {
   issues: string[];
 };
 
+type ResponseStream = InstanceType<typeof HttpResponseStream> & {
+  _onBeforeFirstWrite?: (write: (data: Uint8Array | string) => void) => void;
+};
+
+/**
+ * Object to pass to the {@link Router.resolveStream | `Router.resolveStream()`} method.
+ */
+type ResolveStreamOptions = {
+  /**
+   * Reference to `this` instance of the class that is calling the `resolveStream` method.
+   *
+   * This parameter should be used only when using {@link Router} route decorators like
+   * {@link Router.get | `Router.get()`}, {@link Router.post | `Router.post()`}, etc. as class method decorators, and
+   * it's used to bind the decorated methods to your class instance.
+   *
+   * @example
+   * ```ts
+   * import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
+   *
+   * const app = new Router();
+   *
+   * class Lambda {
+   *   public scope = 'scoped';
+   *
+   *   @app.get('/test')
+   *   public async getTest() {
+   *     return { message: `${this.scope}: success` };
+   *   }
+   *
+   *   public async handler(event: unknown, context: Context, responseStream: ResponseStream) {
+   *     return app.resolveStream(event, context, { scope: this, responseStream });
+   *   }
+   * }
+   * const lambda = new Lambda();
+   * const handler = lambda.handler.bind(lambda);
+   * ```
+   */
+  scope?: unknown;
+  /**
+   * The Lambda response stream used for streaming responses directly to the client.
+   * This stream is provided by the AWS Lambda runtime for response streaming.
+   */
+  responseStream: ResponseStream;
+};
+
 /**
  * Configuration options for CORS middleware
  */
@@ -190,8 +231,9 @@ export type {
   Path,
   RequestContext,
   RestRouterOptions,
-  ResponseStream,
   RouteHandler,
+  ResolveStreamOptions,
+  ResponseStream,
   RestRouteOptions,
   RestRouteHandlerOptions,
   RouteRegistryOptions,

packages/event-handler/src/types/rest.ts

@@ -191,9 +191,9 @@ describe('Class: Router - Middleware', () => {
         await next();
       });
 
-      app.use(({ next }) => {
+      // biome-ignore lint/suspicious/useAwait: This specifically tests a missing await call in an async function
+      app.use(async ({ next }) => {
         next();
-        return Promise.resolve();
       });
 
       // Act

packages/event-handler/tests/unit/rest/Router/middleware.test.ts

@@ -1,5 +1,5 @@
 import type { APIGatewayProxyEvent } from 'aws-lambda';
-import { ResponseStream } from 'lambda-stream';
+import { HttpResponseStream } from '../../../src/rest/utils.js';
 import type { HandlerResponse, Middleware } from '../../../src/types/rest.js';
 
 export const createTestEvent = (
@@ -92,19 +92,19 @@ export const createHeaderCheckMiddleware = (headers: {
 };
 
 // Mock ResponseStream that extends the actual ResponseStream class
-export class MockResponseStream extends ResponseStream {
+export class MockResponseStream extends HttpResponseStream {
   public chunks: Buffer[] = [];
   public _onBeforeFirstWrite?: (
     write: (data: Uint8Array | string) => void
   ) => void;
-  private firstWrite = true;
+  #firstWrite = true;
 
   _write(chunk: Buffer, _encoding: string, callback: () => void): void {
-    if (this.firstWrite && this._onBeforeFirstWrite) {
+    if (this.#firstWrite && this._onBeforeFirstWrite) {
       this._onBeforeFirstWrite((data: Uint8Array | string) => {
         this.chunks.push(Buffer.from(data));
       });
-      this.firstWrite = false;
+      this.#firstWrite = false;
     }
     this.chunks.push(chunk);
     callback();