@vyriy/handler 0.2.0 → 0.3.0

package/AGENTS.md

@@ -0,0 +1,65 @@
+# Vyriy Package Agent Guide
+
+This package belongs to the Vyriy toolkit. Keep changes calm, explicit, reusable, and easy to reason about.
+
+## Architecture
+
+- Prefer simple modules over clever frameworks or hidden conventions.
+- Keep package boundaries explicit and avoid project-specific coupling.
+- Extract only proven reusable behavior.
+- Keep public APIs small, typed, documented, and stable.
+- Prefer SSR-friendly and SSG-friendly code paths.
+- Keep integrations replaceable and avoid hard coupling to a CMS or runtime host.
+- Prefer AWS serverless-compatible assumptions when infrastructure concerns appear.
+
+## File Shape
+
+- Prefer one exported runtime method, component, or helper per production file when it stays readable.
+- Prefer one matching test file per production file, for example `feature.ts` and `feature.test.ts`.
+- Use focused folders when behavior naturally splits into several related files.
+- Keep `index.ts` as a public re-export surface only. Do not place implementation logic in it.
+- Use `.js` relative import and export specifiers in TypeScript source where package style requires it.
+- Add `types.ts` when public shared types are part of the package contract.
+- Keep constants near the code that owns them unless they are shared or clarify repeated behavior.
+
+## Public Surface
+
+- Every new public export should be re-exported from `index.ts`.
+- Add or update `index.test.ts` when the public export surface changes.
+- Add JSDoc for public exports when behavior, parameters, return values, or usage expectations need explanation.
+- Do not hand-maintain source package `exports` maps unless the package has a real custom publishing need.
+
+## Tests
+
+- Tests use Jest and `@jest/globals`.
+- Cover public behavior and meaningful edge cases.
+- Prefer behavior-focused tests over private implementation lock-in.
+- When mocking modules, install mocks before loading the module under test.
+- Use focused validation when changing package behavior:
+
+```bash
+yarn jest packages/<package> --runInBand --coverage=false
+```
+
+## Documentation
+
+- Keep `README.md` concise and usage-oriented.
+- Start package READMEs with `# @vyriy/<package>`.
+- Document real public exports, supported options, and examples that actually work.
+- Keep `doc.mdx` as the Storybook/docs wrapper for the README when the package participates in docs.
+- For component packages, include Storybook coverage for supported states and common usage.
+
+## Components
+
+- Prefer lightweight React 19+ components with TypeScript.
+- Keep components SSR-friendly and avoid browser globals during render.
+- Prefer composable props and Bootstrap-compatible ergonomics where practical.
+- Put each public component in its own file with a matching test.
+- Add Storybook stories when a component has visual states, variants, or interaction states.
+
+## Change Discipline
+
+- Keep changes scoped to the requested behavior.
+- Avoid unrelated refactors and metadata churn.
+- Sync implementation, tests, README, `doc.mdx`, and public re-exports together.
+- Prefer the option that is simpler to explain, easier to evolve, and calmer to maintain.

package/README.md

@@ -22,6 +22,14 @@ With Yarn:
 yarn add @vyriy/handler
 ```
 
+For TypeScript Lambda projects, install AWS Lambda types as a development dependency:
+
+```bash
+yarn add @types/aws-lambda
+```
+
+The `awslambda` response streaming helper is a global provided by the AWS Lambda Node.js runtime. It is not imported from `aws-lambda`; `@types/aws-lambda` only lets TypeScript type-check that global.
+
 ## Usage
 
 Use a prebuilt API Gateway handler chain:
@@ -37,6 +45,65 @@ export const handler = api(async (event) => ({
 }));
 ```
 
+For Lambda response streaming, keep the reusable handler separate from the runtime entrypoints:
+
+```ts
+// handler.ts
+import { api, streamify } from '@vyriy/handler';
+
+export const handler = streamify(
+  api(async (event, responseStream, context) => {
+    responseStream.setContentType?.('text/plain');
+    responseStream.write(`Request path: ${event.path}\n`);
+    responseStream.write(`Request id: ${context.awsRequestId}\n`);
+    responseStream.write('Part 1 of the response...');
+    responseStream.write('Part 2 of the response...');
+    responseStream.end();
+  }),
+);
+```
+
+Use the same handler locally, in Docker, or in a Fargate-style HTTP runtime:
+
+```ts
+// server.ts
+import { server } from '@vyriy/server';
+
+import { handler } from './handler.js';
+
+server(handler);
+```
+
+Use the same handler in AWS Lambda response streaming:
+
+```ts
+// lambda.ts
+import { handler } from './handler.js';
+
+export const main = awslambda.streamifyResponse(handler);
+```
+
+That `handler.ts` shape is already streamified. For a standard non-streaming Lambda, export an `api(...)` handler directly without `streamify(...)` and without `responseStream`.
+
+You can also inline the same shape in one file when a separate local entrypoint is not needed:
+
+```ts
+import { api, streamify } from '@vyriy/handler';
+
+export const main = awslambda.streamifyResponse(
+  streamify(
+    api(async (event, responseStream, context) => {
+      responseStream.setContentType?.('text/plain');
+      responseStream.write(`Request path: ${event.path}\n`);
+      responseStream.write(`Request id: ${context.awsRequestId}\n`);
+      responseStream.write('Part 1 of the response...');
+      responseStream.write('Part 2 of the response...');
+      responseStream.end();
+    }),
+  ),
+);
+```
+
 Use a prebuilt queue or event handler chain:
 
 ```ts
@@ -129,7 +196,11 @@ export const handler = compose(
 ## Prebuilt Chains
 
 - `api`
-  API Gateway chain with error handling, logging, timeout handling, context setup, smoke checks, healthcheck handling, default headers, and CORS preflight handling.
+  API Gateway chain with error handling, logging, timeout handling, context setup, smoke checks, healthcheck handling, default headers, CORS preflight handling, and structural support for streaming/static-file response results.
+- `streamifyApiResponse`
+  Adapts an `api(...)` handler that returns a streaming result to the three-argument handler shape expected by `awslambda.streamifyResponse`.
+- `streamify`
+  Alias for `streamifyApiResponse` intended for direct Lambda response streaming handlers.
 
 - `schedule`
   EventBridge schedule chain with logging, timeout handling, context setup, smoke checks, and rethrown errors.

package/api.d.ts

@@ -1,2 +1,7 @@
-import type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
-export declare const api: import("./types.js").Decorator<APIGatewayProxyEvent, APIGatewayProxyResult>;
+import type { ApiEvent, ApiResult, Context, Handler, ResponseStream } from './types.js';
+type ApiDecorator = {
+    (handler: Handler<ApiEvent, ApiResult | void, [context: Context]>): Handler<ApiEvent, ApiResult | void, [context: Context]>;
+    (handler: Handler<ApiEvent, ApiResult | void, [responseStream: ResponseStream, context: Context]>): Handler<ApiEvent, ApiResult | void, [responseStream: ResponseStream, context: Context]>;
+};
+export declare const api: ApiDecorator;
+export {};

package/factory.d.ts

@@ -1,2 +1,4 @@
-import type { Factory } from './types.js';
+import type { Context } from 'aws-lambda';
+import type { Factory, HandlerArgs, HandlerParams } from './types.js';
+export declare const getContext: <Event, Args extends HandlerArgs>(args: HandlerParams<Event, Args>) => Context;
 export declare const factory: Factory;

package/factory.js

@@ -1,2 +1,3 @@
-const createFactory = (wrapper) => (options) => (handler) => async (event, context) => wrapper(handler, [event, context], options);
+const createFactory = (wrapper) => (options) => (handler) => async (event, ...args) => wrapper(handler, [event, ...args], options);
+export const getContext = (args) => args.at(-1);
 export const factory = createFactory;

package/index.d.ts

@@ -4,6 +4,7 @@ export * from './factory.js';
 export * from './schedule.js';
 export * from './sns.js';
 export * from './sqs.js';
+export * from './streamify.js';
 export * from './wrapper/context.js';
 export * from './wrapper/cors.js';
 export * from './wrapper/chaos.js';

package/index.js

@@ -4,6 +4,7 @@ export * from './factory.js';
 export * from './schedule.js';
 export * from './sns.js';
 export * from './sqs.js';
+export * from './streamify.js';
 export * from './wrapper/context.js';
 export * from './wrapper/cors.js';
 export * from './wrapper/chaos.js';

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@vyriy/handler",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Composable AWS Lambda handler chains and wrappers for Vyriy projects",
   "type": "module",
   "main": "./index.js",
   "dependencies": {
     "@types/aws-lambda": "^8.10.161",
-    "@vyriy/chaos": "0.2.0",
-    "@vyriy/config": "0.2.0",
-    "@vyriy/logger": "0.2.0",
-    "@vyriy/smoke": "0.2.0",
-    "@vyriy/timeout": "0.2.0"
+    "@vyriy/chaos": "0.3.0",
+    "@vyriy/config": "0.3.0",
+    "@vyriy/logger": "0.3.0",
+    "@vyriy/smoke": "0.3.0",
+    "@vyriy/timeout": "0.3.0"
   },
+  "agents": "./AGENTS.md",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -95,6 +96,16 @@
       "import": "./sqs.js",
       "default": "./sqs.js"
     },
+    "./streamify": {
+      "types": "./streamify.d.ts",
+      "import": "./streamify.js",
+      "default": "./streamify.js"
+    },
+    "./streamify.js": {
+      "types": "./streamify.d.ts",
+      "import": "./streamify.js",
+      "default": "./streamify.js"
+    },
     "./wrapper/chaos": {
       "types": "./wrapper/chaos.d.ts",
       "import": "./wrapper/chaos.js",

package/schedule.d.ts

@@ -1,2 +1,2 @@
 import type { ScheduledEvent } from 'aws-lambda';
-export declare const schedule: import("./types.js").Decorator<ScheduledEvent<any>, void>;
+export declare const schedule: import("./types.js").Decorator<ScheduledEvent<any>, void, [context: import("aws-lambda").Context]>;

package/sns.d.ts

@@ -1,2 +1,2 @@
 import type { SNSEvent } from 'aws-lambda';
-export declare const sns: import("./types.js").Decorator<SNSEvent, void>;
+export declare const sns: import("./types.js").Decorator<SNSEvent, void, [context: import("aws-lambda").Context]>;

package/sqs.d.ts

@@ -1,2 +1,2 @@
 import type { SQSEvent } from 'aws-lambda';
-export declare const sqs: import("./types.js").Decorator<SQSEvent, void>;
+export declare const sqs: import("./types.js").Decorator<SQSEvent, void, [context: import("aws-lambda").Context]>;

package/streamify.d.ts

@@ -0,0 +1,9 @@
+import type { Context } from 'aws-lambda';
+import type { ApiEvent, ApiResult, Handler, ResponseStream } from './types.js';
+type LambdaResponseStream = ResponseStream & {
+    setContentType?: (contentType: string) => void;
+};
+export type StreamifiedApiHandler = (event: ApiEvent, responseStream: LambdaResponseStream, context: Context) => Promise<void>;
+export declare const streamifyApiResponse: (handler: Handler<ApiEvent, ApiResult | void, [context: Context]>) => StreamifiedApiHandler;
+export declare const streamify: (handler: Handler<ApiEvent, ApiResult | void, [responseStream: ResponseStream, context: Context]>) => StreamifiedApiHandler;
+export {};

package/streamify.js

@@ -0,0 +1,33 @@
+const getLambdaResponseStream = (responseStream, result) => {
+    const response = globalThis.awslambda?.HttpResponseStream?.from?.(responseStream, {
+        headers: result.headers,
+        statusCode: result.statusCode ?? 200,
+    });
+    return response ?? responseStream;
+};
+const isStreamResult = (result) => 'stream' in result && typeof result.stream === 'function';
+const writeResult = async (responseStream, result) => {
+    if (!result) {
+        if (!responseStream.writableEnded) {
+            responseStream.end();
+        }
+        return;
+    }
+    const stream = getLambdaResponseStream(responseStream, result);
+    if (isStreamResult(result)) {
+        await result.stream(stream);
+        return;
+    }
+    if ('body' in result && result.body !== undefined) {
+        stream.write(result.body);
+    }
+    stream.end();
+};
+export const streamifyApiResponse = (handler) => async (event, responseStream, context) => {
+    const result = await handler(event, context);
+    await writeResult(responseStream, result);
+};
+export const streamify = (handler) => async (event, responseStream, context) => {
+    const result = await handler(event, responseStream, context);
+    await writeResult(responseStream, result);
+};

package/types.d.ts

@@ -1,12 +1,34 @@
-import type { Context } from 'aws-lambda';
+import type { APIGatewayProxyEvent, APIGatewayProxyResult, Context } from 'aws-lambda';
 export type { Context } from 'aws-lambda';
+export type ResponseStream = {
+    end: {
+        (): unknown;
+        (chunk: string | Buffer | Uint8Array): unknown;
+    };
+    setContentType?: (contentType: string) => unknown;
+    writableEnded?: boolean;
+    write(chunk: string | Buffer | Uint8Array): unknown;
+};
+export type StreamWriter = (responseStream: ResponseStream) => Promise<void> | void;
+export type StreamResult = Omit<Partial<APIGatewayProxyResult>, 'body'> & {
+    stream: StreamWriter;
+    body?: never;
+};
+export type StaticFileResult = Omit<Partial<APIGatewayProxyResult>, 'body'> & {
+    filePath: string;
+    body?: never;
+};
+export type ApiResult = APIGatewayProxyResult | StaticFileResult | StreamResult;
+export type ApiEvent = APIGatewayProxyEvent;
+export type HandlerArgs = [...args: unknown[], context: Context];
+export type HandlerParams<Event, Args extends HandlerArgs = [context: Context]> = [event: Event, ...args: Args];
 export type Response<Result> = Promise<Result>;
-export type Handler<Event, Result> = (event: Event, context: Context) => Response<Result>;
-export type Decorator<Event, Result> = (handler: Handler<Event, Result>) => Handler<Event, Result>;
-export type Compose = <Event, Result>(...decorators: Array<Decorator<Event, Result>>) => Decorator<Event, Result>;
-export type Wrapper<Options> = <Event, Result>(handler: Handler<Event, Result>, args: [event: Event, context: Context], options?: Options) => Response<Result>;
-export type TypedWrapper<Event, Result, Options> = (handler: Handler<Event, Result>, args: [event: Event, context: Context], options?: Options) => Response<Result>;
+export type Handler<Event, Result, Args extends HandlerArgs = [context: Context]> = (event: Event, ...args: Args) => Response<Result>;
+export type Decorator<Event, Result, Args extends HandlerArgs = [context: Context]> = (handler: Handler<Event, Result, Args>) => Handler<Event, Result, Args>;
+export type Compose = <Event, Result, Args extends HandlerArgs = [context: Context]>(...decorators: Array<Decorator<Event, Result, Args>>) => Decorator<Event, Result, Args>;
+export type Wrapper<Options> = <Event, Result, Args extends HandlerArgs = [context: Context]>(handler: Handler<Event, Result, Args>, args: HandlerParams<Event, Args>, options?: Options) => Response<Result>;
+export type TypedWrapper<Event, Result, Options, Args extends HandlerArgs = [context: Context]> = (handler: Handler<Event, Result, Args>, args: HandlerParams<Event, Args>, options?: Options) => Response<Result>;
 export type Factory = {
-    <Options = undefined>(wrapper: Wrapper<Options>): <Event, Result>(options?: Options) => Decorator<Event, Result>;
-    <Options, Event, Result>(wrapper: TypedWrapper<Event, Result, Options>): (options?: Options) => Decorator<Event, Result>;
+    <Options = undefined>(wrapper: Wrapper<Options>): <Event, Result, Args extends HandlerArgs = [context: Context]>(options?: Options) => Decorator<Event, Result, Args>;
+    <Options, Event, Result, Args extends HandlerArgs = [context: Context]>(wrapper: TypedWrapper<Event, Result, Options, Args>): (options?: Options) => Decorator<Event, Result, Args>;
 };

package/wrapper/chaos.d.ts

@@ -1,2 +1,2 @@
 import { type ChaosOptions } from '@vyriy/chaos';
-export declare const withChaos: <Event, Result>(options?: ChaosOptions | undefined) => import("../types.js").Decorator<Event, Result>;
+export declare const withChaos: <Event, Result, Args extends import("../types.js").HandlerArgs = [context: import("aws-lambda").Context]>(options?: ChaosOptions | undefined) => import("../types.js").Decorator<Event, Result, Args>;

package/wrapper/context.d.ts

@@ -1 +1 @@
-export declare const withContext: <Event, Result>(options?: undefined) => import("../types.js").Decorator<Event, Result>;
+export declare const withContext: <Event, Result, Args extends import("../types.js").HandlerArgs = [context: import("aws-lambda").Context]>(options?: undefined) => import("../types.js").Decorator<Event, Result, Args>;

package/wrapper/context.js

@@ -1,6 +1,6 @@
-import { factory } from '../factory.js';
+import { factory, getContext } from '../factory.js';
 export const withContext = factory(async (handler, args) => {
-    const [, ctx] = args;
+    const ctx = getContext(args);
     ctx.callbackWaitsForEmptyEventLoop = false;
     return handler(...args);
 });

package/wrapper/cors.d.ts

@@ -1,2 +1,2 @@
-import type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
-export declare const withCors: (options?: undefined) => import("../types.js").Decorator<APIGatewayProxyEvent, APIGatewayProxyResult>;
+import type { ApiResult, HandlerArgs } from '../types.js';
+export declare const withCors: (options?: undefined) => import("../types.js").Decorator<import("aws-lambda").APIGatewayProxyEvent, void | ApiResult, HandlerArgs>;

package/wrapper/error.d.ts

@@ -2,4 +2,4 @@ export type ErrorOptions = {
     errorHandler?: (err: unknown) => Promise<void>;
     throwError?: boolean;
 };
-export declare const withError: <Event, Result>(options?: ErrorOptions | undefined) => import("../types.js").Decorator<Event, Result>;
+export declare const withError: <Event, Result, Args extends import("../types.js").HandlerArgs = [context: import("aws-lambda").Context]>(options?: ErrorOptions | undefined) => import("../types.js").Decorator<Event, Result, Args>;

package/wrapper/headers.d.ts

@@ -1,2 +1,2 @@
-import type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
-export declare const withHeaders: (options?: Record<string, string> | undefined) => import("../types.js").Decorator<APIGatewayProxyEvent, APIGatewayProxyResult>;
+import type { ApiResult, HandlerArgs } from '../types.js';
+export declare const withHeaders: (options?: Record<string, string> | undefined) => import("../types.js").Decorator<import("aws-lambda").APIGatewayProxyEvent, void | ApiResult, HandlerArgs>;

package/wrapper/headers.js

@@ -1,6 +1,9 @@
 import { factory } from '../factory.js';
 export const withHeaders = factory(async (handler, args, options = {}) => {
     const result = await handler(...args);
+    if (!result) {
+        return result;
+    }
     result.headers = {
         ...options,
         ...result.headers,

package/wrapper/healthcheck.d.ts

@@ -1,5 +1,5 @@
-import type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
+import type { ApiResult, HandlerArgs } from '../types.js';
 export declare const withHealthcheck: (options?: {
     path?: string;
     action?: () => Promise<void>;
-} | undefined) => import("../types.js").Decorator<APIGatewayProxyEvent, APIGatewayProxyResult>;
+} | undefined) => import("../types.js").Decorator<import("aws-lambda").APIGatewayProxyEvent, void | ApiResult, HandlerArgs>;

package/wrapper/logger.d.ts

@@ -1,4 +1,4 @@
 export type LoggerOptions = {
     logger?: typeof console;
 };
-export declare const withLogger: <Event, Result>(options?: LoggerOptions | undefined) => import("../types.js").Decorator<Event, Result>;
+export declare const withLogger: <Event, Result, Args extends import("../types.js").HandlerArgs = [context: import("aws-lambda").Context]>(options?: LoggerOptions | undefined) => import("../types.js").Decorator<Event, Result, Args>;

package/wrapper/logger.js

@@ -1,8 +1,9 @@
 import { createLogger } from '@vyriy/logger';
-import { factory } from '../factory.js';
+import { factory, getContext } from '../factory.js';
 export const withLogger = factory(async (handler, args, options = {}) => {
     const { logger = createLogger() } = options;
-    const [event, context] = args;
+    const [event] = args;
+    const context = getContext(args);
     logger.info('Event:', event);
     logger.info('Context:', context);
     try {

package/wrapper/smoke.d.ts

@@ -1,2 +1,2 @@
-import type { Decorator } from '../types.js';
-export declare const withSmoke: <Event, Result>() => Decorator<Event, Result>;
+import type { Context, Decorator, HandlerArgs } from '../types.js';
+export declare const withSmoke: <Event, Result, Args extends HandlerArgs = [context: Context]>() => Decorator<Event, Result, Args>;

package/wrapper/timeout.d.ts

@@ -1 +1 @@
-export declare const withTimeout: <Event, Result>(options?: undefined) => import("../types.js").Decorator<Event, Result>;
+export declare const withTimeout: <Event, Result, Args extends import("../types.js").HandlerArgs = [context: import("aws-lambda").Context]>(options?: undefined) => import("../types.js").Decorator<Event, Result, Args>;

package/wrapper/timeout.js

@@ -1,6 +1,6 @@
 import { timeout as error } from '@vyriy/timeout';
-import { factory } from '../factory.js';
+import { factory, getContext } from '../factory.js';
 export const withTimeout = factory(async (handler, args) => Promise.race([
-    error(args[1].getRemainingTimeInMillis() - 1000),
+    error(getContext(args).getRemainingTimeInMillis() - 1000),
     handler(...args),
 ]));