alien-middleware 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { AdapterRequestContext, HattipHandler } from '@hattip/core';
+import { Any } from 'radashi';
 
 type RequestPlugin = {
     /**
@@ -22,11 +23,19 @@ type MiddlewareTypes<TProperties extends object = any, TEnv extends object = any
     env: TEnv;
 };
 interface HattipContext<TPlatform, TEnv extends object> extends AdapterRequestContext<TPlatform> {
-    env<K extends keyof TEnv>(key: K): TEnv[K];
+    /**
+     * The `request.url` string parsed into a `URL` object. Parsing is performed
+     * on-demand and the result is cached.
+     */
+    url: URL;
+    env<K extends keyof TEnv>(key: Extract<K, string>): TEnv[K];
     env(key: never): string | undefined;
 }
-type CastNever<T, U> = [T] extends [never] ? U : T;
-type RequestContext<TProperties extends object = {}, TEnv extends object = {}, TPlatform = unknown> = HattipContext<TPlatform, TEnv> & CastNever<TProperties, {}>;
+/**
+ * Converts a type `T` to something that can be intersected with an object.
+ */
+type Intersectable<T extends object> = [T] extends [never] ? {} : [T] extends [Any] ? Record<PropertyKey, any> : T;
+type RequestContext<TProperties extends object = any, TEnv extends object = any, TPlatform = any> = HattipContext<TPlatform, TEnv> & Intersectable<TProperties>;
 type Awaitable<T> = T | PromiseLike<T>;
 type RequestMiddleware<T extends MiddlewareChain = MiddlewareChain> = (context: RequestContext<InputProperties<T>, InputEnv<T>, Platform<T>>) => Awaitable<Response | RequestPlugin | void>;
 type ResponseMiddleware<T extends MiddlewareChain = MiddlewareChain> = (context: RequestContext<InputProperties<T>, InputEnv<T>, Platform<T>>, response: Response) => Awaitable<Response | void>;
@@ -38,7 +47,7 @@ type RequestHandler<TInputs extends MiddlewareTypes, TCurrent extends Middleware
  * response middleware. This means it will run *after* a `Response` is generated
  * by a request middleware.
  */
-type Middleware<TProperties extends object = {}, TEnv extends object = {}, TPlatform = unknown> = (context: RequestContext<TProperties, TEnv, TPlatform>, response: Response) => Awaitable<Response | RequestPlugin | void>;
+type Middleware<TProperties extends object = any, TEnv extends object = any, TPlatform = unknown> = (context: RequestContext<TProperties, TEnv, TPlatform>, response: Response) => Awaitable<Response | RequestPlugin | void>;
 type Merge<TSource extends object, TOverrides extends object | undefined> = {} & (TOverrides extends object ? {
     [K in keyof TSource | keyof TOverrides]: K extends keyof TOverrides ? TOverrides[K] : K extends keyof TSource ? TSource[K] : never;
 } : TSource);
@@ -82,7 +91,7 @@ TPlatform = any> {
      */
     use<const TMiddleware extends Middleware<TCurrent['properties'], TCurrent['env'], TPlatform>>(middleware: TMiddleware): ApplyMiddleware<this, TMiddleware>;
 }
-declare function chain<TPlatform = unknown, TEnv extends object = {}, TProperties extends object = {}>(): MiddlewareChain<{
+declare function chain<TProperties extends object = {}, TEnv extends object = {}, TPlatform = unknown>(): MiddlewareChain<{
     env: TEnv;
     properties: TProperties;
 }, {
@@ -91,4 +100,4 @@ declare function chain<TPlatform = unknown, TEnv extends object = {}, TPropertie
 }, TPlatform>;
 declare function chain<const T extends Middleware = Middleware>(middleware: T): ApplyFirstMiddleware<T>;
 
-export { MiddlewareChain, chain };
+export { type Middleware, MiddlewareChain, type RequestContext, type RequestHandler, type RequestMiddleware, type RequestPlugin, type ResponseMiddleware, chain };

package/dist/index.js

@@ -15,6 +15,14 @@ var kRequestChain = Symbol("requestChain");
 var kResponseChain = Symbol("responseChain");
 var kIgnoreNotFound = Symbol("ignoreNotFound");
 var kMiddlewareCache = Symbol("middlewareCache");
+var urlDescriptor = {
+  configurable: true,
+  get() {
+    const url = new URL(this.request.url);
+    Object.defineProperty(this, "url", { value: url });
+    return url;
+  }
+};
 var MiddlewareChain = class _MiddlewareChain {
   [kRequestChain] = [];
   [kResponseChain] = [];
@@ -36,6 +44,9 @@ var MiddlewareChain = class _MiddlewareChain {
     async function handler(parentContext) {
       const context = Object.create(parentContext);
       context[kIgnoreNotFound] = true;
+      if (!("url" in context)) {
+        Object.defineProperty(context, "url", urlDescriptor);
+      }
       const cache = context[kMiddlewareCache] ||= /* @__PURE__ */ new Set();
       let response;
       let env;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "alien-middleware",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "exports": {
     "types": "./dist/index.d.ts",
     "default": "./dist/index.js"

package/readme.md

@@ -27,8 +27,8 @@ import { chain } from 'alien-middleware'
 const app = chain()
 
 // Or create a chain with an initial middleware
-const appWithInitial = chain(ctx => {
-  console.log('Initial middleware running for:', ctx.request.url)
+const appWithInitial = chain(context => {
+  console.log('Initial middleware running for:', context.request.url)
 })
 ```
 
@@ -39,12 +39,12 @@ Use the `.use()` method to add middleware functions to the chain. Each call to `
 ```typescript
 import type { RequestContext } from 'alien-middleware'
 
-const firstMiddleware = (ctx: RequestContext) => {
+const firstMiddleware = (context: RequestContext) => {
   console.log('First middleware')
   // Doesn't return anything, so the chain continues
 }
 
-const secondMiddleware = (ctx: RequestContext) => {
+const secondMiddleware = (context: RequestContext) => {
   console.log('Second middleware')
   return new Response('Hello from middleware!', { status: 200 })
   // Returns a Response, terminating the request-phase chain
@@ -89,8 +89,8 @@ Request middleware runs sequentially before a `Response` is generated.
 - **Terminating the Chain:** Return a `Response` object to stop processing subsequent request middleware.
 
   ```typescript
-  const earlyResponder = (ctx: RequestContext) => {
-    if (ctx.request.url.endsWith('/forbidden')) {
+  const earlyResponder = (context: RequestContext) => {
+    if (context.request.url.endsWith('/forbidden')) {
       return new Response('Forbidden', { status: 403 })
     }
     // Otherwise, continue the chain
@@ -100,7 +100,7 @@ Request middleware runs sequentially before a `Response` is generated.
 - **Extending Context:** Return an object with a `define` property to add properties to the context for _downstream_ middleware.
 
   ```typescript
-  const addUser = (ctx: RequestContext) => {
+  const addUser = (context: RequestContext) => {
     // In a real app, you might look up a user based on a token
     const user = { id: 1, name: 'Alice' }
 
@@ -108,24 +108,24 @@ Request middleware runs sequentially before a `Response` is generated.
   }
 
   const greetUser = (
-    ctx: RequestContext<{ user: { id: number; name: string } }>
+    context: RequestContext<{ user: { id: number; name: string } }>
   ) => {
     // The `user` property is now available thanks to `addUser`
-    return new Response(`Hello, ${ctx.user.name}!`)
+    return new Response(`Hello, ${context.user.name}!`)
   }
 
   const app = chain().use(addUser).use(greetUser)
   ```
 
-- **Extending Environment:** Return an object with an `env` property to add environment variables accessible via `ctx.env()`.
+- **Extending Environment:** Return an object with an `env` property to add environment variables accessible via `context.env()`.
 
   ```typescript
-  const addApiKey = (ctx: RequestContext) => {
+  const addApiKey = (context: RequestContext) => {
     return { env: { API_KEY: 'secret123' } }
   }
 
-  const useApiKey = (ctx: RequestContext<{}, { API_KEY: string }>) => {
-    const key = ctx.env('API_KEY')
+  const useApiKey = (context: RequestContext<{}, { API_KEY: string }>) => {
+    const key = context.env('API_KEY')
     console.log('API Key:', key) // Output: API Key: secret123
   }
 
@@ -147,11 +147,11 @@ Request middleware runs sequentially before a `Response` is generated.
 Response middleware runs _after_ a `Response` has been generated by a request middleware or the final handler. It receives both the context and the generated `Response`.
 
 ```typescript
-const poweredByMiddleware = (ctx: RequestContext, response: Response) => {
+const poweredByMiddleware = (context: RequestContext, response: Response) => {
   response.headers.set('X-Powered-By', 'alien-middleware')
 }
 
-const mainHandler = (ctx: RequestContext) => {
+const mainHandler = (context: RequestContext) => {
   return new Response('Main content')
 }
 
@@ -177,17 +177,17 @@ another chain, since the outer chain will still have a chance to return a
 You can compose middleware by nesting chains using `.use()`. Context modifications (`define`, `env`) within a nested chain are scoped to that chain and do not affect middleware outside of it.
 
 ```typescript
-const innerChain = chain((ctx: RequestContext) => {
+const innerChain = chain((context: RequestContext) => {
   console.log('Inner chain start')
   return { define: { innerData: 'secret' } } // Only available inside innerChain
-}).use((ctx: RequestContext<{ innerData: string }>) => {
-  console.log('Accessing inner data:', ctx.innerData)
+}).use((context: RequestContext<{ innerData: string }>) => {
+  console.log('Accessing inner data:', context.innerData)
 })
 
-const outerMiddleware = (ctx: RequestContext) => {
-  // ctx.innerData is not accessible here
+const outerMiddleware = (context: RequestContext) => {
+  // context.innerData is not accessible here
   console.log('Outer middleware after inner chain')
-  if (!('innerData' in ctx)) {
+  if (!('innerData' in context)) {
     console.log('innerData is correctly scoped.')
   }
   return new Response('Finished')
@@ -202,3 +202,36 @@ const finalApp = chain().use(innerChain).use(outerMiddleware)
 ```
 
 If a nested chain does not return a `Response`, execution continues with the next middleware in the outer chain.
+
+### Safe Environment Variables
+
+When writing a Hattip handler without this package, the `context.env()` method is inherently unsafe. Its return type is always `string | undefined`, which means you either need to write defensive checks or use type assertions. Neither is ideal.
+
+With alien-middleware, you **must** declare an environment variable's type in order to use it.
+
+```typescript
+import { chain } from 'alien-middleware'
+
+// A common pattern is to declare a dedicated type for the environment variables.
+type Env = {
+  API_KEY: string
+}
+
+const app = chain<any, Env>().use(context => {
+  const key = context.env('API_KEY')
+  //    ^? string
+})
+```
+
+When defining a middleware, you can declare env types that the middleware expects to use.
+
+```typescript
+import type { RequestContext } from 'alien-middleware'
+
+// Assuming `Env` is defined like in the previous example.
+const myMiddleware = (context: RequestContext<any, Env>) => {
+  const key = context.env('API_KEY')
+}
+```
+
+In both examples, we skip declaring any additional context properties (the first type parameter) because we're not using any. The second type parameter is for environment variables. The third is for the special `context.platform` property, whose value is provided by the host platform (e.g. Node.js, Deno, Bun, etc). On principle, a middleware should avoid using the `context.platform` property, since that could make it non-portable unless you write extra fallback logic for other hosts.