lambda-pipe 0.1.0

package/docs/dev-server.md

@@ -0,0 +1,278 @@
+# Dev Server (lambda-pipe)
+
+Local development server that simulates AWS Lambda execution using a Fastify-based runtime.
+
+It converts HTTP requests into Lambda-like events and executes routes with full middleware + plugin lifecycle.
+
+---
+
+# Features
+
+- File-based routing (`src/routes`)
+- Lambda-like request context
+- Fastify-based dev runtime
+- Cookie support
+- JSON-safe response serialization
+- Dynamic route loading
+- Optional hot reload (tsx / nodemon)
+
+---
+
+# Installation
+
+```bash
+npm install fastify @fastify/cookie
+```
+
+---
+
+# Quick Start
+
+```ts
+import { createDevApp } from 'lambda-pipe/cli'
+
+await createDevApp({
+  port: 3000,
+  routesDir: 'src/routes',
+})
+```
+
+```bash
+npm run dev
+```
+
+---
+
+# Project Structure
+
+```bash
+src/
+  routes/
+    health.ts
+    user.ts
+```
+
+---
+
+# Health Route
+
+```ts
+import { defineRoute, ok } from 'lambda-pipe'
+
+export default defineRoute({
+  method: 'GET',
+  path: '/health',
+
+  handler: async () => {
+    return ok({
+      status: 'ok',
+      uptime: process.uptime(),
+    })
+  },
+})
+```
+
+---
+
+# Full User Route Example
+
+```ts
+import {
+  defineRoute,
+  ok,
+  HttpError,
+  ValidationError,
+} from 'lambda-pipe'
+
+import type { Middleware, Plugin, Validator } from 'lambda-pipe'
+
+type User = {
+  id: string
+  teamId: string
+}
+
+type PluginContext = {
+  log: {
+    info: (...args: any[]) => void
+    error: (...args: any[]) => void
+  }
+
+  auth: {
+    can: (scope: string) => boolean
+  }
+
+  db: {
+    findUserById: (id: string) => Promise<any>
+  }
+}
+
+const paramsValidator: Validator<{ id: string }> = async (input) => {
+  const params = input as any
+  if (!params.id) throw new ValidationError('missing id')
+  return { id: params.id }
+}
+
+const queryValidator: Validator<{ expand?: string }> = async (input) => {
+  const query = input as any
+  if (query.expand && typeof query.expand !== 'string') {
+    throw new ValidationError('expand must be string')
+  }
+  return { expand: query.expand }
+}
+
+const loggerPlugin: Plugin = {
+  name: 'logger',
+  extend: () => ({
+    log: {
+      info: console.log,
+      error: console.error,
+    },
+  }),
+}
+
+const authPlugin: Plugin = {
+  name: 'auth',
+  extend: () => ({
+    auth: {
+      can: (scope: string) => scope === 'read:user',
+    },
+  }),
+}
+
+const dbPlugin: Plugin = {
+  name: 'db',
+  extend: () => ({
+    db: {
+      findUserById: async (id: string) => ({
+        id,
+        username: 'john_doe',
+        createdAt: new Date().toISOString(),
+      }),
+    },
+  }),
+}
+
+const requestMiddleware: Middleware<any, User, PluginContext> = {
+  onRequest: async (context, next) => {
+    context.state.startedAt = Date.now()
+
+    context.log.info('request start', {
+      requestId: context.req.requestId,
+      ip: context.req.ip,
+    })
+
+    if (!context.req.user) {
+      throw new HttpError(401, 'Unauthorized')
+    }
+
+    if (!context.auth.can('read:user')) {
+      throw new HttpError(403, 'Forbidden')
+    }
+
+    await next()
+  },
+
+  onResponse: async (context) => {
+    const ms = Date.now() - context.state.startedAt
+    context.log.info('response done', { duration: ms })
+  },
+
+  onError: async (err, context) => {
+    context.log.error('request failed', {
+      err,
+      requestId: context.req.requestId,
+    })
+  },
+}
+
+export default defineRoute<
+  {
+    params: { id: string }
+    query: { expand?: string }
+  },
+  User,
+  PluginContext
+>({
+  method: 'GET',
+  path: '/user/:id',
+
+  plugins: [loggerPlugin, authPlugin, dbPlugin],
+  middleware: [requestMiddleware],
+
+  validate: {
+    params: paramsValidator,
+    query: queryValidator,
+  },
+
+  authenticate: async (token) => {
+    if (token !== 'valid-token') return null
+
+    return {
+      user: {
+        id: 'u1',
+        teamId: 'team-1',
+      },
+      scope: ['read:user'],
+      metadata: {
+        role: 'admin',
+      },
+    }
+  },
+
+  handler: async (context) => {
+    const { id } = context.params
+    const { expand } = context.query
+
+    const cacheKey = `user:${id}`
+    const cached = context.exec.cache.get(cacheKey)
+
+    if (cached) {
+      return ok({
+        source: 'cache',
+        data: cached,
+      })
+    }
+
+    const user = await context.db.findUserById(id)
+
+    const result = {
+      id: user.id,
+      username: user.username,
+      teamId: context.req.user?.teamId,
+      expand,
+      createdAt: user.createdAt,
+    }
+
+    context.exec.cache.set(cacheKey, result, 10000)
+
+    return ok({
+      source: 'database',
+      data: result,
+    })
+  },
+})
+```
+
+---
+
+# Execution Flow
+
+```
+HTTP Request
+  ↓
+Fastify server
+  ↓
+Route loader
+  ↓
+Lambda-like context
+  ↓
+Middleware + Auth
+  ↓
+Validation
+  ↓
+Plugins injection
+  ↓
+Handler
+  ↓
+Response
+```

package/docs/websocket.md

@@ -0,0 +1,118 @@
+# WebSocket (lambda-pipe)
+
+lambda-pipe supports AWS API Gateway WebSocket APIs with a simple handler abstraction.
+
+It handles:
+- $connect
+- $disconnect
+- custom route messages
+
+---
+
+# Installation
+
+```bash
+npm install @aws-sdk/client-apigatewaymanagementapi
+```
+
+---
+
+# Basic Usage
+
+```ts
+import { wsHandler } from 'lambda-pipe/websocket'
+
+export const handler = wsHandler({
+  connect: async () => {
+    console.log('client connected')
+  },
+
+  message: async (ctx) => {
+    return {
+      statusCode: 200,
+      body: JSON.stringify({ ok: true }),
+    }
+  },
+
+  disconnect: async () => {
+    console.log('client disconnected')
+  },
+})
+```
+
+---
+
+# Context
+
+```
+{
+  event: APIGatewayProxyWebsocketEventV2
+}
+```
+
+---
+
+# Important fields
+
+```
+const connectionId =
+  context.event.requestContext.connectionId
+
+const routeKey =
+  context.event.requestContext.routeKey
+```
+
+| Field | Description |
+|------|-------------|
+| connectionId | unique connection |
+| routeKey | $connect / message / disconnect |
+
+---
+
+# Chat Example
+
+```ts
+export const handler = wsHandler({
+  connect: async (ctx) => {
+    console.log('connected')
+  },
+
+  message: async (ctx) => {
+    const body = JSON.parse(ctx.event.body || '{}')
+
+    return {
+      statusCode: 200,
+      body: JSON.stringify({
+        received: true,
+      }),
+    }
+  },
+
+  disconnect: async () => {
+    console.log('disconnected')
+  },
+})
+```
+
+---
+
+# Metal model
+
+```bash
+API Gateway WebSocket
+   ↓
+lambda-pipe wsHandler
+   ↓
+routeKey dispatcher
+   ↓
+handler
+   ↓
+response
+```
+
+---
+
+# Notes
+
+- Works only with AWS API Gateway WebSocket
+- Stateless execution model

package/package.json

@@ -0,0 +1,135 @@
+{
+  "name": "lambda-pipe",
+  "version": "0.1.0",
+  "description": "Type-safe plugin & middleware runtime for AWS Lambda and serverless APIs.",
+  "license": "MIT",
+  "author": "Delpi.Kye",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./build/cjs/index.cjs",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": "./build/esm/index.js",
+      "require": "./build/cjs/index.cjs"
+    },
+    "./jobs": {
+      "types": "./build/jobs/index.d.ts",
+      "import": "./build/esm/jobs/index.js",
+      "require": "./build/cjs/jobs/index.js"
+    },
+    "./logger": {
+      "types": "./build/logger/index.d.ts",
+      "import": "./build/esm/logger/index.js",
+      "require": "./build/cjs/logger/index.js"
+    },
+    "./runtime": {
+      "types": "./build/runtime/index.d.ts",
+      "import": "./build/esm/runtime/index.js",
+      "require": "./build/cjs/runtime/index.js"
+    },
+    "./websocket": {
+      "types": "./build/websocket/index.d.ts",
+      "import": "./build/esm/websocket/index.js",
+      "require": "./build/cjs/websocket/index.js"
+    },
+    "./cli": {
+      "types": "./build/cli/dev.d.ts",
+      "import": "./build/esm/cli/index.js",
+      "require": "./build/cjs/cli/index.js"
+    }
+  },
+  "files": [
+    "build",
+    "docs"
+  ],
+  "scripts": {
+    "clean": "rimraf build",
+    "dev": "nodemon --watch src --ext ts --exec tsx src/cli/dev.ts",
+    "build": "rollup -c",
+    "cb": "npm run clean && npm run build",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "lint:fix": "eslint \"src/**/*.{ts,tsx}\" --fix",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run clean && npm run lint && npm run typecheck && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/delpikye-v/lambda-pipe.git"
+  },
+  "homepage": "https://github.com/delpikye-v/lambda-pipe#readme",
+  "bugs": {
+    "url": "https://github.com/delpikye-v/lambda-pipe/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/delpikye-v"
+  },
+  "keywords": [
+    "lambda",
+    "aws-lambda",
+    "serverless",
+    "middleware",
+    "plugin-system",
+    "typescript",
+    "runtime",
+    "execution-engine",
+    "request-context",
+    "validation",
+    "fastify",
+    "lambda-adapter",
+    "api-runtime",
+    "backend",
+    "nodejs",
+    "http",
+    "router",
+    "framework-agnostic",
+    "typed-context",
+    "serverless-framework"
+  ],
+  "peerDependencies": {
+    "fastify": ">=5"
+  },
+
+  "peerDependenciesMeta": {
+    "fastify": {
+      "optional": true
+    }
+  },
+
+  "dependencies": {
+    "@aws-sdk/client-apigatewaymanagementapi": "^3.1045.0",
+    "aws-lambda": "^1.0.7"
+  },
+  "devDependencies": {
+    "@fastify/cookie": "^11.0.2",
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@types/aws-lambda": "^8.10.161",
+    "@types/node": "^25.5.0",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-simple-import-sort": "^13.0.0",
+    "eslint-plugin-unused-imports": "^4.4.1",
+    "fastify": "^5.8.5",
+    "nodemon": "^3.1.14",
+    "prettier": "^3.8.1",
+    "rimraf": "^5.0.5",
+    "rollup": "^4.12.0",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "rollup-plugin-typescript2": "^0.37.0",
+    "tslib": "^2.8.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}