alien-middleware 0.5.0 → 0.6.0

package/dist/{index-DQDr9Gkb.d.ts → index-CuxbHrbf.d.ts}

@@ -1,16 +1,22 @@
 import { AdapterRequestContext, HattipHandler } from '@hattip/core';
 import { Any } from 'radashi';
 
-type RequestPlugin = {
+type RequestEnvPlugin = {
     /**
-     * Define properties on the request context.
-     */
-    define?: object;
-    /**
-     * Add type-safe environment variables.
+     * Add type-safe environment variables. These are accessed with the `env()`
+     * method on the request context.
      */
     env?: object;
 };
+/**
+ * The object returned by a request middleware that is merged into the request
+ * context. The same context property cannot be defined by two different
+ * plugins, or an error will be thrown at runtime.
+ *
+ * May contain special properties:
+ * - `env`: Add type-safe environment variables.
+ */
+type RequestPlugin = Record<string, unknown> & RequestEnvPlugin;
 type Inputs<T extends MiddlewareChain> = T['$']['input'];
 type Platform<T extends MiddlewareChain> = T['$']['platform'];
 type InputProperties<T extends MiddlewareChain> = Inputs<T>['properties'];
@@ -35,7 +41,14 @@ interface HattipContext<TPlatform, TEnv extends object> extends AdapterRequestCo
  * 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>;
+/**
+ * An extensible Hattip context object.
+ *
+ * NOTE: When using this type on the right side of an `extends` clause, you
+ * should prefer `RequestContext<any>` over `RequestContext` (no type
+ * parameters), as the default type is stricter.
+ */
+type RequestContext<TProperties extends object = never, TEnv extends object = any, TPlatform = any> = HattipContext<TPlatform, TEnv> & Intersectable<TProperties>;
 /**
  * Extract a `RequestContext` type from a `MiddlewareChain` type.
  *
@@ -62,7 +75,7 @@ type Merge<TSource extends object, TOverrides extends object | undefined> = {} &
     [K in keyof TSource | keyof TOverrides]: K extends keyof TOverrides ? TOverrides[K] : K extends keyof TSource ? TSource[K] : never;
 } : TSource);
 type ApplyRequestPlugin<TParent extends MiddlewareChain, TPlugin extends RequestPlugin> = {
-    properties: Merge<Properties<TParent>, TPlugin['define']>;
+    properties: Merge<Properties<TParent>, Omit<TPlugin, keyof RequestEnvPlugin>>;
     env: Merge<Env<TParent>, TPlugin['env']>;
 };
 /**
@@ -71,13 +84,14 @@ type ApplyRequestPlugin<TParent extends MiddlewareChain, TPlugin extends Request
  * parent chain.
  */
 type ApplyMiddleware<TParent extends MiddlewareChain, TMiddleware> = TMiddleware extends MiddlewareChain ? RequestHandler<Inputs<TParent>, Current<TParent>, Platform<TParent>> : TMiddleware extends () => Awaitable<infer TPlugin extends RequestPlugin> ? RequestHandler<Inputs<TParent>, ApplyRequestPlugin<TParent, TPlugin>, Platform<TParent>> : RequestHandler<Inputs<TParent>, Current<TParent>, Platform<TParent>>;
-type ApplyFirstMiddleware<T extends Middleware> = T extends MiddlewareChain ? T : ApplyMiddleware<MiddlewareChain<{
+type EmptyMiddlewareChain = MiddlewareChain<{
     properties: {};
     env: {};
 }, {
     properties: {};
     env: {};
-}, unknown>, T>;
+}, unknown>;
+type ApplyFirstMiddleware<T extends Middleware> = T extends MiddlewareChain ? T : ApplyMiddleware<EmptyMiddlewareChain, T>;
 type MergeMiddleware<TFirst extends MiddlewareChain, TSecond extends Middleware<Properties<TFirst>, Env<TFirst>, Platform<TFirst>>> = RequestHandler<Inputs<TFirst>, TSecond extends MiddlewareChain ? {
     properties: Merge<Properties<TFirst>, Properties<TSecond>>;
     env: Merge<Env<TFirst>, Env<TSecond>>;
@@ -135,4 +149,4 @@ declare function chain<TProperties extends object = {}, TEnv extends object = {}
 }, TPlatform>;
 declare function chain<const T extends Middleware = Middleware>(middleware: T): ApplyFirstMiddleware<T>;
 
-export { type ApplyMiddleware as A, type ExtractMiddleware as E, MiddlewareChain as M, type RouteHandler as R, type MiddlewareContext as a, type RouteMethod as b, chain as c, type MergeMiddleware as d, type Middleware as e, type RequestContext as f, type RequestHandler as g, type RequestMiddleware as h, type RequestPlugin as i, type ResponseMiddleware as j };
+export { type ApplyMiddleware as A, type EmptyMiddlewareChain as E, MiddlewareChain as M, type RouteHandler as R, type MiddlewareContext as a, type RouteMethod as b, type RouterContext as c, chain as d, type ExtractMiddleware as e, type MergeMiddleware as f, type Middleware as g, type RequestContext as h, type RequestHandler as i, type RequestMiddleware as j, type RequestPlugin as k, type ResponseMiddleware as l };

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { A as ApplyMiddleware, E as ExtractMiddleware, d as MergeMiddleware, e as Middleware, M as MiddlewareChain, a as MiddlewareContext, f as RequestContext, g as RequestHandler, h as RequestMiddleware, i as RequestPlugin, j as ResponseMiddleware, c as chain } from './index-DQDr9Gkb.js';
+export { A as ApplyMiddleware, e as ExtractMiddleware, f as MergeMiddleware, g as Middleware, M as MiddlewareChain, a as MiddlewareContext, h as RequestContext, i as RequestHandler, j as RequestMiddleware, k as RequestPlugin, l as ResponseMiddleware, d as chain } from './index-CuxbHrbf.js';
 import '@hattip/core';
 import 'radashi';

package/dist/index.js

@@ -73,18 +73,16 @@ function createHandler(requestChain, responseChain) {
           response = result;
           break;
         }
-        if (result.define) {
-          for (const key in result.define) {
-            Object.defineProperty(context, key, {
-              ...Object.getOwnPropertyDescriptor(result.define, key),
-              configurable: false
-            });
+        for (const key in result) {
+          const descriptor = Object.getOwnPropertyDescriptor(result, key);
+          if (key === "env") {
+            env ||= createExtendedEnv(context);
+            Object.defineProperty(env, key, descriptor);
+          } else {
+            descriptor.configurable = false;
+            Object.defineProperty(context, key, descriptor);
           }
         }
-        if (result.env) {
-          env ||= createExtendedEnv(context);
-          Object.assign(env, result.env);
-        }
       }
     }
     if (!response) {

package/dist/router.d.ts

@@ -1,11 +1,12 @@
 import { InferParams } from 'pathic';
-import { M as MiddlewareChain, a as MiddlewareContext, R as RouteHandler, b as RouteMethod } from './index-DQDr9Gkb.js';
+import { M as MiddlewareChain, E as EmptyMiddlewareChain, a as MiddlewareContext, R as RouteHandler, b as RouteMethod } from './index-CuxbHrbf.js';
+export { c as RouterContext } from './index-CuxbHrbf.js';
 import '@hattip/core';
 import 'radashi';
 
 type OneOrMany<T> = T | readonly T[];
 type Router<T extends MiddlewareChain = any> = ReturnType<typeof routes<T>>;
-declare function routes<T extends MiddlewareChain>(middlewares?: T): {
+declare function routes<T extends MiddlewareChain = EmptyMiddlewareChain>(middlewares?: T): {
     (context: MiddlewareContext<T>): void | Response | Promise<void | Response> | undefined;
     use: {
         <TPath extends string>(path: TPath, handler: RouteHandler<T, InferParams<TPath>>): /*elided*/ any;
@@ -13,4 +14,4 @@ declare function routes<T extends MiddlewareChain>(middlewares?: T): {
     };
 };
 
-export { type Router, routes };
+export { RouteHandler, type Router, routes };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "alien-middleware",
   "type": "module",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",

package/readme.md

@@ -97,6 +97,8 @@ Request middleware runs sequentially before a `Response` is generated.
 - **Terminating the Chain:** Return a `Response` object to stop processing subsequent request middleware.
 
   ```typescript
+  import type { RequestContext } from 'alien-middleware'
+
   const earlyResponder = (context: RequestContext) => {
     if (context.request.url.endsWith('/forbidden')) {
       return new Response('Forbidden', { status: 403 })
@@ -105,19 +107,21 @@ 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.
+- **Extending Context:** Return an object (known as a "request plugin") to add its properties to the context for _downstream_ middleware. Getter syntax is supported.
 
   ```typescript
+  import type { RequestContext } from 'alien-middleware'
+
+  type User = { id: number; name: string }
+
   const addUser = (context: RequestContext) => {
     // In a real app, you might look up a user based on a token
-    const user = { id: 1, name: 'Alice' }
+    const user: User = { id: 1, name: 'Alice' }
 
-    return { define: { user } }
+    return { user }
   }
 
-  const greetUser = (
-    context: RequestContext<{ user: { id: number; name: string } }>
-  ) => {
+  const greetUser = (context: RequestContext<{ user: User }>) => {
     // The `user` property is now available thanks to `addUser`
     return new Response(`Hello, ${context.user.name}!`)
   }
@@ -125,14 +129,16 @@ Request middleware runs sequentially before a `Response` is generated.
   const app = chain().use(addUser).use(greetUser)
   ```
 
-- **Extending Environment:** Return an object with an `env` property to add environment variables accessible via `context.env()`.
+- **Extending Environment:** Request plugins may have an `env` property to add environment variables accessible via `context.env()`.
 
   ```typescript
+  import type { RequestContext } from 'alien-middleware'
+
   const addApiKey = (context: RequestContext) => {
     return { env: { API_KEY: 'secret123' } }
   }
 
-  const useApiKey = (context: RequestContext<{}, { API_KEY: string }>) => {
+  const useApiKey = (context: RequestContext<never, { API_KEY: string }>) => {
     const key = context.env('API_KEY')
     console.log('API Key:', key) // Output: API Key: secret123
   }
@@ -141,7 +147,7 @@ Request middleware runs sequentially before a `Response` is generated.
   ```
 
 > [!NOTE]
-> If you're wondering why you need to return a `{ define: { … } }` object
+> If you're wondering why you need to return an object to define properties
 > (rather than simply assigning to the context object), it's because TypeScript
 > is unable to infer the type of the context object downstream if you don't do
 > it like this.
@@ -182,7 +188,7 @@ another chain, since the outer chain will still have a chance to return a
 
 ### Nesting Chains
 
-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.
+You can compose middleware by nesting chains using `.use()`. _Request plugins_ within a nested chain are scoped to that chain and do not affect middleware outside of it.
 
 ```typescript
 const innerChain = chain((context: RequestContext) => {