lambda-pipe 0.1.0

package/README.md

@@ -0,0 +1,761 @@
+# ⚡ lambda-pipe
+
+[![NPM](https://img.shields.io/npm/v/lambda-pipe.svg)](https://www.npmjs.com/package/lambda-pipe) ![Downloads](https://img.shields.io/npm/dt/lambda-pipe.svg) ![Bundle Size](https://img.shields.io/bundlephobia/minzip/lambda-pipe)
+
+[LIVE EXAMPLE](https://codesandbox.io/p/devbox/2tyg7y)
+
+
+🚀 A type-safe plugin & middleware runtime for AWS Lambda APIs.
+
+> Build composable serverless backends with typed context, lifecycle hooks, validation, plugins, middleware, caching, runtime adapters, and background jobs.
+
+---
+
+# Basic Route
+
+```ts
+// src/routes
+import {
+  defineRoute,
+  ok,
+} from 'lambda-pipe'
+
+export default defineRoute({
+  method: 'GET',
+
+  path: '/health',
+
+  handler: async () => {
+    return ok({
+      status: 'ok',
+    })
+  },
+})
+
+```
+
+---
+
+# What is lambda-pipe?
+
+lambda-pipe is a lightweight execution runtime for serverless APIs.
+
+It provides:
+
+* typed request context
+* middleware lifecycle
+* plugin system
+* validation pipeline
+* authentication pipeline
+* execution metadata
+* cache layer
+* runtime adapters
+* background job handlers
+
+without forcing framework architecture.
+
+---
+
+# Why lambda-pipe?
+
+Most serverless projects become messy over time:
+
+* auth duplicated everywhere
+* validation inconsistent
+* middleware order unclear
+* request context untyped
+* plugins tightly coupled
+* runtime logic scattered
+
+lambda-pipe provides:
+
+* deterministic execution
+* composable plugins
+* centralized lifecycle
+* typed runtime context
+* adapter-friendly architecture
+
+---
+
+# Features
+
+* ⚡ Serverless-first runtime
+* 🔌 Plugin system
+* 🧩 Middleware pipeline
+* 🧠 Cold start lifecycle hooks
+* 🛡 Typed validation
+* 🔑 Authentication pipeline
+* 🍪 Cookie helpers
+* 🧱 Runtime adapters
+* 📝 Full TypeScript inference
+* 💾 In-memory execution cache
+* 🌐 Framework agnostic
+* 📦 SQS job runtime
+* 🚀 Fastify development server
+
+---
+
+# Metal model
+
+```text
+Runtime Adapter
+      ↓
+normalizeRequest()
+      ↓
+createRequestContext()
+      ↓
+Plugins
+      ↓
+Middleware Pipeline
+      ↓
+Handler
+      ↓
+serializeResponse()
+```
+
+---
+
+# Installation
+
+```bash
+npm install lambda-pipe
+```
+
+---
+
+# Route Definition
+
+```ts
+import {
+  defineRoute,
+  ok,
+} from 'lambda-pipe'
+
+export default defineRoute({
+  method: 'GET',
+
+  path: '/users/:id',
+
+  handler: async (context) => {
+    return ok({
+      id: context.params.id,
+    })
+  },
+})
+```
+
+---
+
+# Typed Context
+
+```ts
+import {
+  defineRoute,
+  ok,
+} from 'lambda-pipe'
+
+export default defineRoute<
+  {
+    query: {
+      expand?: string
+    }
+
+    params: {
+      id: string
+    }
+  }
+>({
+  method: 'GET',
+
+  path: '/users/:id',
+
+  handler: async (context) => {
+    context.query.expand
+
+    context.params.id
+
+    return ok()
+  },
+})
+```
+
+---
+
+# Validation
+
+```ts
+import {
+  defineRoute,
+  ok,
+  ValidationError,
+} from 'lambda-pipe'
+
+import type {
+  Validator,
+} from 'lambda-pipe'
+
+const paramsValidator: Validator<{
+  id: string
+}> = async (input) => {
+  const params = input as any
+
+  if (!params.id) {
+    throw new ValidationError('missing id')
+  }
+
+  return {
+    id: params.id,
+  }
+}
+
+export default defineRoute({
+  method: 'GET',
+
+  path: '/users/:id',
+
+  validate: {
+    params: paramsValidator,
+  },
+
+  handler: async (context) => {
+    return ok(context.params)
+  },
+})
+```
+
+---
+
+# Middleware
+
+```ts
+import type {
+  Middleware,
+} from 'lambda-pipe'
+
+const loggerMiddleware: Middleware = {
+  onRequest: async (context, next) => {
+    console.log(context.req.requestId)
+
+    await next()
+  },
+
+  onResponse: async () => {
+    console.log('response sent')
+  },
+
+  onError: async (error) => {
+    console.error(error)
+  },
+}
+```
+
+---
+
+# Middleware Lifecycle
+
+| Hook            | Description                        |
+| --------------- | ---------------------------------- |
+| `onInit`        | Runs once during cold start        |
+| `onRequest`     | Runs before handler                |
+| `onResponse`    | Runs before response serialization |
+| `afterResponse` | Runs after response serialization  |
+| `onError`       | Runs on request failure            |
+
+---
+
+# Plugins
+
+```ts
+import type {
+  Plugin,
+} from 'lambda-pipe'
+
+const authPlugin: Plugin<{
+  auth: {
+    can: (scope: string) => boolean
+  }
+}> = {
+  name: 'auth',
+
+  setup: async () => {
+    console.log('setup once')
+  },
+
+  onColdStart: async () => {
+    console.log('cold start')
+  },
+
+  extend: () => {
+    return {
+      auth: {
+        can: (scope) => {
+          return scope === 'read:user'
+        },
+      },
+    }
+  },
+}
+```
+
+---
+
+# Plugin Context Injection
+
+```ts
+import {
+  defineRoute,
+  ok,
+} from 'lambda-pipe'
+
+type User = {
+  id: string
+}
+
+type PluginContext = {
+  auth: {
+    can: (scope: string) => boolean
+  }
+}
+
+export default defineRoute<
+  {},
+  User,
+  PluginContext
+>({
+  plugins: [authPlugin],
+
+  handler: async (context) => {
+    context.auth.can('read:user')
+
+    return ok()
+  },
+})
+```
+
+---
+
+# Authentication
+
+```ts
+import {
+  defineRoute,
+  ok,
+} from 'lambda-pipe'
+
+export default defineRoute({
+  authenticate: async (token) => {
+    if (token !== 'valid-token') {
+      return null
+    }
+
+    return {
+      user: {
+        id: 'u1',
+      },
+
+      scope: ['read:user'],
+    }
+  },
+
+  handler: async (context) => {
+    return ok({
+      user: context.req.user,
+    })
+  },
+})
+```
+
+---
+
+# Request Context
+
+| Property                 | Description        |
+| ------------------------ | ------------------ |
+| `context.req.user`       | authenticated user |
+| `context.req.scope`      | auth scopes        |
+| `context.req.metadata`   | auth metadata      |
+| `context.req.requestId`  | request id         |
+| `context.req.ip`         | client ip          |
+| `context.req.userAgent`  | request user agent |
+| `context.req.cookies`    | parsed cookies     |
+| `context.req.receivedAt` | request timestamp  |
+
+---
+
+# Execution Context
+
+| Property                   | Description          |
+| -------------------------- | -------------------- |
+| `context.exec.isColdStart` | lambda cold start    |
+| `context.exec.containerId` | runtime container id |
+| `context.exec.cache`       | in-memory cache      |
+
+---
+
+# Cache Example
+
+```ts
+const cacheKey = `user:${context.params.id}`
+
+const user = await context.exec.cache.getOrSet(
+  cacheKey,
+  async () => {
+    return db.user.findUnique({
+      where: {
+        id: context.params.id,
+      },
+    })
+  },
+  10000,
+)
+
+return ok(user)
+```
+
+---
+
+# Response Helpers
+
+```ts
+import {
+  ok,
+  json,
+  badRequest,
+  unauthorized,
+  forbidden,
+} from 'lambda-pipe'
+```
+
+| Helper           | Status |
+| ---------------- | ------ |
+| `ok()`           | 200    |
+| `json()`         | custom |
+| `badRequest()`   | 400    |
+| `unauthorized()` | 401    |
+| `forbidden()`    | 403    |
+
+---
+
+# Context Response API
+
+```ts
+context.setHeader('x-request-id', '123')
+
+context.status(200)
+
+context.setCookie('session', 'abc', {
+  httpOnly: true,
+  secure: true,
+  path: '/',
+  maxAge: 3600,
+})
+```
+
+---
+
+# Error Handling
+
+```ts
+import {
+  HttpError,
+} from 'lambda-pipe'
+
+throw new HttpError(
+  403,
+  'Forbidden',
+)
+```
+
+---
+
+# Built-in Errors
+
+```ts
+import {
+  UnauthorizedError,
+  ForbiddenError,
+  ValidationError,
+  NotFoundError,
+} from 'lambda-pipe'
+```
+
+---
+
+# AWS Lambda Example
+
+```ts
+// src/functions/user.ts
+
+import {
+  lambdaHandler,
+} from 'lambda-pipe/runtime'
+
+import route from '../routes/user'
+
+export const handler =
+  lambdaHandler(route)
+```
+
+---
+
+# SQS Job Example
+
+```ts
+import {
+  defineJob,
+  sqsHandler,
+} from 'lambda-pipe/jobs'
+
+const userCreatedJob = defineJob({
+  name: 'user-created',
+
+  handler: async (payload: {
+    id: string
+  }) => {
+    console.log(payload.id)
+  },
+})
+
+export const handler =
+  sqsHandler(userCreatedJob)
+```
+
+---
+
+# Utilities
+
+```ts
+import {
+  normalizeHeaders,
+  parseCookies,
+  extractBearerToken,
+  safeJsonParse,
+} from 'lambda-pipe'
+```
+
+---
+
+# Route Example
+
+```ts
+import {
+  defineRoute,
+  ok,
+  HttpError,
+} from 'lambda-pipe'
+
+import type {
+  Middleware,
+  Plugin,
+} from 'lambda-pipe'
+
+type User = {
+  id: string
+}
+
+type PluginContext = {
+  auth: {
+    can: (
+      scope: string,
+    ) => boolean
+  }
+}
+
+/**
+ * plugin
+ */
+
+const authPlugin: Plugin<
+  PluginContext
+> = {
+  name: 'auth',
+
+  extend: () => ({
+    auth: {
+      can: (scope: string) =>
+        scope === 'read:user',
+    },
+  }),
+}
+
+/**
+ * middleware
+ */
+
+const authMiddleware: Middleware<
+  any,
+  User,
+  PluginContext
+> = {
+  onRequest: async (
+    context,
+    next,
+  ) => {
+    if (!context.req.user) {
+      throw new HttpError(
+        401,
+        'Unauthorized',
+      )
+    }
+
+    await next()
+  },
+}
+
+/**
+ * route
+ */
+
+export default defineRoute<
+  {
+    params: {
+      id: string
+    }
+  },
+  User,
+  PluginContext
+>({
+  method: 'GET',
+
+  path: '/users/:id',
+
+  plugins: [authPlugin],
+
+  middleware: [
+    authMiddleware,
+  ],
+
+  authenticate: async (token) => {
+    if (token !== 'valid-token') {
+      return null
+    }
+
+    return {
+      user: {
+        id: 'u1',
+      },
+
+      scope: ['read:user'],
+    }
+  },
+
+  handler: async (context) => {
+    return ok({
+      id: context.params.id,
+
+      canRead:
+        context.auth.can(
+          'read:user',
+        ),
+
+      requestId:
+        context.req.requestId,
+    })
+  },
+})
+```
+
+---
+
+# Development Runtime
+
+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.
+
+```ts
+import { createDevApp } from 'lambda-pipe/cli'
+
+await createDevApp({
+  port: 3000,
+  routesDir: 'src/routes',
+})
+
+```
+
+```bash
+npm run dev
+```
+
+See: [DOC](https://github.com/delpikye-v/lambda-pipe/blob/main/docs/dev-server.md
+)
+
+---
+
+# WebSocket Runtime
+
+`lambda-pipe` supports AWS API Gateway WebSocket APIs with a simple handler abstraction.
+
+It handles:
+
+- $connect
+- $disconnect
+- custom route messages
+
+```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')
+  },
+})
+```
+
+See: [DOC](https://github.com/delpikye-v/lambda-pipe/blob/main/docs/websocket.md)
+
+---
+
+# Philosophy
+
+```text
+You control:
+- plugins
+- middleware
+- runtime
+- architecture
+
+lambda-pipe controls:
+- execution
+- lifecycle
+- typing
+- orchestration
+```
+
+---
+
+# Design Principles
+
+* Explicit execution
+* Typed runtime
+* Composition over inheritance
+* Runtime agnostic
+* Serverless-first architecture
+
+---
+
+# When to Use
+
+* Serverless APIs
+* Lambda backends
+* Internal platforms
+* Runtime adapters
+* Typed middleware systems
+* Plugin-based architecture
+
+---
+
+# License
+
+MIT