@lafken/common 0.12.29 → 0.13.0

package/lib/decorators/index.d.ts

@@ -2,3 +2,4 @@ export * from './field';
 export * from './lambda';
 export * from './payload';
 export * from './resource';
+export * from './streaming';

package/lib/decorators/index.js

@@ -18,3 +18,4 @@ __exportStar(require("./field"), exports);
 __exportStar(require("./lambda"), exports);
 __exportStar(require("./payload"), exports);
 __exportStar(require("./resource"), exports);
+__exportStar(require("./streaming"), exports);

package/lib/decorators/lambda/lambda.d.ts

@@ -5,3 +5,4 @@ export declare const reflectArgumentMethod: (target: Function, methodName: strin
 export declare const createLambdaDecorator: <T, M>({ getLambdaMetadata, descriptorValue, validateEvent, argumentParser, }: CreateLambdaDecoratorProps<T, M>) => (props?: T) => (target: any, methodName: string, descriptor: PropertyDescriptor) => any;
 export declare const createEventDecorator: ({ enableInLambdaInvocation, prefix }: CreateEventDecoratorProps) => (eventField: AllowedTypes) => (target: any, methodName: string, _number: number) => void;
 export declare const Context: () => (target: any, methodName: string, _number: number) => void;
+export declare const ResponseStreaming: () => (target: any, methodName: string, _number: number) => void;

package/lib/decorators/lambda/lambda.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Context = exports.createEventDecorator = exports.createLambdaDecorator = exports.reflectArgumentMethod = void 0;
+exports.ResponseStreaming = exports.Context = exports.createEventDecorator = exports.createLambdaDecorator = exports.reflectArgumentMethod = void 0;
 require("reflect-metadata");
 const utils_1 = require("../../utils");
 const field_1 = require("../field");
@@ -8,6 +8,7 @@ const lambda_types_1 = require("./lambda.types");
 const argumentsByType = {
     [lambda_types_1.LambdaArgumentTypes.event]: ({ event }) => event,
     [lambda_types_1.LambdaArgumentTypes.context]: ({ context }) => context,
+    [lambda_types_1.LambdaArgumentTypes.responseStream]: ({ responseStream }) => responseStream,
 };
 const reflectArgumentMethod = (target, methodName, type) => {
     const properties = Reflect.getMetadata(lambda_types_1.LambdaReflectKeys.arguments, target) || {};
@@ -29,11 +30,22 @@ const createLambdaDecorator = ({ getLambdaMetadata, descriptorValue, validateEve
         ...argumentsByType,
         ...argumentParser,
     };
-    descriptor.value = async function (event, context) {
+    descriptor.value = async function (...args) {
+        const [event, responseStreamOrContext, lambdaContext] = args;
         if (!(0, utils_1.isBuildEnvironment)() && event && validateEvent) {
             validateEvent(target, methodName, event);
         }
-        const methodArguments = (lambdaArguments?.[methodName] || []).map((argumentType) => mapArgumentMethod[argumentType]({ event, context, methodName, target }));
+        const responseStream = typeof responseStreamOrContext?.write === 'function'
+            ? responseStreamOrContext
+            : undefined;
+        const context = responseStream === undefined ? responseStreamOrContext : lambdaContext;
+        const methodArguments = (lambdaArguments?.[methodName] || []).map((argumentType) => mapArgumentMethod[argumentType]({
+            event,
+            context,
+            methodName,
+            target,
+            responseStream,
+        }));
         const response = await originalValue.apply(this, methodArguments);
         return response;
     };
@@ -62,3 +74,7 @@ const Context = () => (target, methodName, _number) => {
     (0, exports.reflectArgumentMethod)(target, methodName, lambda_types_1.LambdaArgumentTypes.context);
 };
 exports.Context = Context;
+const ResponseStreaming = () => (target, methodName, _number) => {
+    (0, exports.reflectArgumentMethod)(target, methodName, lambda_types_1.LambdaArgumentTypes.responseStream);
+};
+exports.ResponseStreaming = ResponseStreaming;

package/lib/decorators/lambda/lambda.types.d.ts

@@ -303,7 +303,8 @@ export declare enum LambdaReflectKeys {
 }
 export declare enum LambdaArgumentTypes {
     event = "event",
-    context = "context"
+    context = "context",
+    responseStream = "responseStream"
 }
 export type CallbackParam = (error: boolean | null, response?: any) => void;
 export type LambdaArguments = Record<string, LambdaArgumentTypes[]>;
@@ -312,6 +313,7 @@ export type LambdaArgumentsType = Record<LambdaArgumentTypes, ({ event, context,
     context: any;
     methodName: string;
     target: any;
+    responseStream?: any;
 }) => any>;
 export interface CreateLambdaDecoratorProps<T, M> {
     getLambdaMetadata: (params: T, methodName: string) => M;

package/lib/decorators/lambda/lambda.types.js

@@ -12,4 +12,5 @@ var LambdaArgumentTypes;
 (function (LambdaArgumentTypes) {
     LambdaArgumentTypes["event"] = "event";
     LambdaArgumentTypes["context"] = "context";
+    LambdaArgumentTypes["responseStream"] = "responseStream";
 })(LambdaArgumentTypes || (exports.LambdaArgumentTypes = LambdaArgumentTypes = {}));

package/lib/decorators/streaming/index.d.ts

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

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

package/lib/decorators/streaming/streaming.d.ts

@@ -0,0 +1,34 @@
+import 'reflect-metadata';
+/**
+ * Method decorator factory that marks a Lambda handler as a response-streaming
+ * handler.
+ *
+ * It only records, per method name, that the handler is a streaming one under
+ * `StreamingReflectKeys.streaming` on the class prototype (during synth). The
+ * actual `awslambda.streamifyResponse` wrapping is applied later by the build
+ * step, when the handler is exported as the Lambda entry point, so the
+ * streaming marker ends up on the final exported function (a decorator wrap
+ * would be dropped by `Function.prototype.bind` when the handler is bound to
+ * its instance at export time).
+ *
+ * The decorated method's runtime signature is `(event, responseStream, context)`
+ * instead of the usual `(event, context)`. When combined with a method decorator
+ * built from `createLambdaDecorator` (e.g. `Get`/`Handler`), that decorator's
+ * generated wrapper tells both signatures apart by checking whether the second
+ * argument exposes a `write` function: if it does it is treated as the response
+ * stream and forwarded to any parameter decorated with `ResponseStreaming()`,
+ * and `context` is read from the third argument; otherwise the second argument
+ * is the `context`. The check is structural rather than `instanceof Stream`
+ * because the runtime hands over its own stream implementation, which does not
+ * necessarily inherit from the `stream` module of this bundle.
+ *
+ * @example
+ * @Streaming()
+ * @Handler()
+ * myHandler(@ResponseStreaming() responseStream: Writable, @Context() context: any) {
+ *   responseStream.write('chunk');
+ *   responseStream.end();
+ * }
+ */
+export declare const createStreamingDecorator: () => () => (target: any, methodName: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+export declare const Streaming: () => (target: any, methodName: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/lib/decorators/streaming/streaming.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Streaming = exports.createStreamingDecorator = void 0;
+require("reflect-metadata");
+const utils_1 = require("../../utils");
+const streaming_types_1 = require("./streaming.types");
+/**
+ * Method decorator factory that marks a Lambda handler as a response-streaming
+ * handler.
+ *
+ * It only records, per method name, that the handler is a streaming one under
+ * `StreamingReflectKeys.streaming` on the class prototype (during synth). The
+ * actual `awslambda.streamifyResponse` wrapping is applied later by the build
+ * step, when the handler is exported as the Lambda entry point, so the
+ * streaming marker ends up on the final exported function (a decorator wrap
+ * would be dropped by `Function.prototype.bind` when the handler is bound to
+ * its instance at export time).
+ *
+ * The decorated method's runtime signature is `(event, responseStream, context)`
+ * instead of the usual `(event, context)`. When combined with a method decorator
+ * built from `createLambdaDecorator` (e.g. `Get`/`Handler`), that decorator's
+ * generated wrapper tells both signatures apart by checking whether the second
+ * argument exposes a `write` function: if it does it is treated as the response
+ * stream and forwarded to any parameter decorated with `ResponseStreaming()`,
+ * and `context` is read from the third argument; otherwise the second argument
+ * is the `context`. The check is structural rather than `instanceof Stream`
+ * because the runtime hands over its own stream implementation, which does not
+ * necessarily inherit from the `stream` module of this bundle.
+ *
+ * @example
+ * @Streaming()
+ * @Handler()
+ * myHandler(@ResponseStreaming() responseStream: Writable, @Context() context: any) {
+ *   responseStream.write('chunk');
+ *   responseStream.end();
+ * }
+ */
+const createStreamingDecorator = () => () => (target, methodName, descriptor) => {
+    if ((0, utils_1.isBuildEnvironment)()) {
+        const streamingMethods = Reflect.getMetadata(streaming_types_1.StreamingReflectKeys.streaming, target) || {};
+        Reflect.defineMetadata(streaming_types_1.StreamingReflectKeys.streaming, { ...streamingMethods, [methodName]: true }, target);
+    }
+    return descriptor;
+};
+exports.createStreamingDecorator = createStreamingDecorator;
+exports.Streaming = (0, exports.createStreamingDecorator)();

package/lib/decorators/streaming/streaming.types.d.ts

@@ -0,0 +1,4 @@
+export declare enum StreamingReflectKeys {
+    streaming = "streaming:handlers"
+}
+export type StreamingMethods = Record<string, boolean>;

package/lib/decorators/streaming/streaming.types.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamingReflectKeys = void 0;
+var StreamingReflectKeys;
+(function (StreamingReflectKeys) {
+    StreamingReflectKeys["streaming"] = "streaming:handlers";
+})(StreamingReflectKeys || (exports.StreamingReflectKeys = StreamingReflectKeys = {}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lafken/common",
-  "version": "0.12.29",
+  "version": "0.13.0",
   "private": false,
   "description": "Lafken utilities - TypeScript decorator factories and metadata reflection for infrastructure-as-code decorators",
   "keywords": [
@@ -28,16 +28,17 @@
     "lib"
   ],
   "dependencies": {
-    "reflect-metadata": "0.2.2"
+    "@types/aws-lambda": "^8.10.162",
+    "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
-    "@swc/core": "^1.15.40",
+    "@swc/core": "^1.15.43",
     "@swc/helpers": "^0.5.23",
-    "@vitest/runner": "^4.1.8",
+    "@vitest/runner": "^4.1.10",
     "cdktn-vitest": "^1.0.0",
-    "typescript": "6.0.3",
+    "typescript": "7.0.2",
     "unplugin-swc": "^1.5.9",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.10"
   },
   "engines": {
     "node": ">=20.19"