alien-middleware 0.6.1 → 0.7.1

package/dist/{chunk-DEWCXAOT.js → chunk-HZDENULC.js}

@@ -1,3 +1,11 @@
+// node_modules/.pnpm/radashi@12.5.0-beta.6d5c035/node_modules/radashi/dist/radashi.js
+function noop() {
+}
+var isArray = /* @__PURE__ */ (() => Array.isArray)();
+function isFunction(value) {
+  return typeof value === "function";
+}
+
 // src/url.ts
 var urlDescriptor = {
   configurable: true,
@@ -14,5 +22,8 @@ function defineParsedURL(context) {
 }
 
 export {
+  noop,
+  isArray,
+  isFunction,
   defineParsedURL
 };

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

@@ -1,5 +1,5 @@
+import { Any, noop } from 'radashi';
 import { AdapterRequestContext, HattipHandler } from '@hattip/core';
-import { Any } from 'radashi';
 
 type RequestEnvPlugin = {
     /**
@@ -55,6 +55,7 @@ type RequestContext<TProperties extends object = never, TEnv extends object = an
  * When type `T` is `never`, a default context is returned.
  */
 type MiddlewareContext<T extends MiddlewareChain> = [T] extends [never] ? RequestContext<{}, {}, unknown> : RequestContext<Properties<T>, Env<T>, Platform<T>>;
+type IsolatedContext<T extends MiddlewareChain> = RequestContext<InputProperties<T>, InputEnv<T>, Platform<T>>;
 type Awaitable<T> = T | Promise<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>;
@@ -74,7 +75,7 @@ type ExtractMiddleware<T extends MiddlewareChain> = Middleware<Properties<T>, En
 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);
-type ApplyRequestPlugin<TParent extends MiddlewareChain, TPlugin extends RequestPlugin> = {
+type ApplyRequestPlugin<TParent extends MiddlewareChain, TPlugin extends RequestPlugin> = {} & {
     properties: Merge<Properties<TParent>, Omit<TPlugin, keyof RequestEnvPlugin>>;
     env: Merge<Env<TParent>, TPlugin['env']>;
 };
@@ -83,7 +84,10 @@ type ApplyRequestPlugin<TParent extends MiddlewareChain, TPlugin extends Request
  * chain, it's treated as a nested chain, which won't leak its plugins into the
  * 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 ApplyMiddleware<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>>;
+} : TSecond extends () => Awaitable<infer TResult> ? TResult extends RequestPlugin ? ApplyRequestPlugin<TFirst, TResult> : Current<TFirst> : Current<TFirst>, Platform<TFirst>>;
 type EmptyMiddlewareChain = MiddlewareChain<{
     properties: {};
     env: {};
@@ -92,10 +96,6 @@ type EmptyMiddlewareChain = MiddlewareChain<{
     env: {};
 }, 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>>;
-} : TSecond extends () => Awaitable<infer TPlugin extends RequestPlugin> ? ApplyRequestPlugin<TFirst, TPlugin> : Current<TFirst>, Platform<TFirst>>;
 type RouteMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD';
 type RouterContext<T extends MiddlewareChain = any, TPathParams extends object = any, TMethod extends RouteMethod = RouteMethod> = MiddlewareContext<T> & {
     params: TPathParams;
@@ -127,18 +127,17 @@ TPlatform = any> {
      * treated as a response middleware. Otherwise, it will be treated as a
      * request middleware.
      *
+     * If a middleware chain is given, its middlewares will be executed after any
+     * existing middlewares in this chain.
+     *
      * @returns a new `MiddlewareChain` instance
      */
     use<const TMiddleware extends ExtractMiddleware<this>>(middleware: TMiddleware): ApplyMiddleware<this, TMiddleware>;
     /**
-     * Merge two middleware chains. The middlewares from the second chain will be
-     * executed after the middlewares from the first chain.
-     *
-     * For ease of use, this method may be given a middleware function, which
-     * short-circuits to the `use` method. You should prefer using the `use`
-     * method directly, if possible.
+     * Create a middleware function that encapsulates this middleware chain, so
+     * any modifications it makes to the request context are not leaked.
      */
-    merge<TMiddleware extends ExtractMiddleware<this>>(chain: TMiddleware): MergeMiddleware<this, TMiddleware>;
+    isolate(): ((ctx: IsolatedContext<this>) => Promise<Response | void>) | typeof noop;
 }
 declare function chain<TProperties extends object = {}, TEnv extends object = {}, TPlatform = unknown>(): MiddlewareChain<{
     env: TEnv;
@@ -149,4 +148,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 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 };
+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 Middleware as f, type RequestContext as g, type RequestHandler as h, type RequestMiddleware as i, type RequestPlugin as j, type ResponseMiddleware as k };

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-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';
+export { A as ApplyMiddleware, e as ExtractMiddleware, f as Middleware, M as MiddlewareChain, a as MiddlewareContext, g as RequestContext, h as RequestHandler, i as RequestMiddleware, j as RequestPlugin, k as ResponseMiddleware, d as chain } from './index-DEMeaByn.js';
+import '@hattip/core';

package/dist/index.js

@@ -1,6 +1,8 @@
 import {
-  defineParsedURL
-} from "./chunk-DEWCXAOT.js";
+  defineParsedURL,
+  isFunction,
+  noop
+} from "./chunk-HZDENULC.js";
 
 // src/index.ts
 var kRequestChain = Symbol("requestChain");
@@ -15,9 +17,18 @@ var MiddlewareChain = class _MiddlewareChain {
    * treated as a response middleware. Otherwise, it will be treated as a
    * request middleware.
    *
+   * If a middleware chain is given, its middlewares will be executed after any
+   * existing middlewares in this chain.
+   *
    * @returns a new `MiddlewareChain` instance
    */
   use(middleware) {
+    if (middleware instanceof _MiddlewareChain) {
+      return createHandler(
+        [...this[kRequestChain], ...middleware[kRequestChain]],
+        [...this[kResponseChain], ...middleware[kResponseChain]]
+      );
+    }
     let requestChain = this[kRequestChain];
     let responseChain = this[kResponseChain];
     if (middleware.length < 2) {
@@ -28,21 +39,11 @@ var MiddlewareChain = class _MiddlewareChain {
     return createHandler(requestChain, responseChain);
   }
   /**
-   * Merge two middleware chains. The middlewares from the second chain will be
-   * executed after the middlewares from the first chain.
-   *
-   * For ease of use, this method may be given a middleware function, which
-   * short-circuits to the `use` method. You should prefer using the `use`
-   * method directly, if possible.
+   * Create a middleware function that encapsulates this middleware chain, so
+   * any modifications it makes to the request context are not leaked.
    */
-  merge(chain2) {
-    if (chain2 instanceof _MiddlewareChain) {
-      return createHandler(
-        [...this[kRequestChain], ...chain2[kRequestChain]],
-        [...this[kResponseChain], ...chain2[kResponseChain]]
-      );
-    }
-    return this.use(chain2);
+  isolate() {
+    return isFunction(this) ? (ctx) => this(ctx) : noop;
   }
 };
 function createHandler(requestChain, responseChain) {
@@ -50,6 +51,11 @@ function createHandler(requestChain, responseChain) {
     const context = Object.create(parentContext);
     context[kIgnoreNotFound] = true;
     defineParsedURL(context);
+    const { passThrough } = context;
+    let shouldPassThrough = false;
+    context.passThrough = () => {
+      shouldPassThrough = true;
+    };
     const cache = context[kMiddlewareCache] ||= /* @__PURE__ */ new Set();
     let response;
     let env;
@@ -62,6 +68,9 @@ function createHandler(requestChain, responseChain) {
       if (result instanceof Promise) {
         result = await result;
       }
+      if (shouldPassThrough) {
+        break;
+      }
       if (result) {
         if (result instanceof Response) {
           response = result;
@@ -87,6 +96,12 @@ function createHandler(requestChain, responseChain) {
         return;
       }
       response = new Response("Not Found", { status: 404 });
+      if (shouldPassThrough) {
+        passThrough();
+        return response;
+      }
+    } else if (response.type !== "default") {
+      response = new Response(response.body, response);
     }
     for (const middleware of responseChain) {
       if (cache.has(middleware)) {
@@ -119,8 +134,8 @@ function chain(middleware) {
   if (middleware instanceof MiddlewareChain) {
     return middleware;
   }
-  const handler = new MiddlewareChain();
-  return middleware ? handler.use(middleware) : handler;
+  const empty = new MiddlewareChain();
+  return middleware ? empty.use(middleware) : empty;
 }
 export {
   MiddlewareChain,

package/dist/router.d.ts

@@ -1,8 +1,8 @@
 import { InferParams } from 'pathic';
-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 { M as MiddlewareChain, E as EmptyMiddlewareChain, a as MiddlewareContext, R as RouteHandler, b as RouteMethod } from './index-DEMeaByn.js';
+export { c as RouterContext } from './index-DEMeaByn.js';
 import 'radashi';
+import '@hattip/core';
 
 type OneOrMany<T> = T | readonly T[];
 type Router<T extends MiddlewareChain = any> = ReturnType<typeof routes<T>>;

package/dist/router.js

@@ -1,17 +1,11 @@
 import {
-  defineParsedURL
-} from "./chunk-DEWCXAOT.js";
+  defineParsedURL,
+  isArray,
+  isFunction
+} from "./chunk-HZDENULC.js";
 
 // src/router.ts
 import { compilePaths } from "pathic";
-
-// node_modules/.pnpm/radashi@12.5.0-beta.6d5c035/node_modules/radashi/dist/radashi.js
-var isArray = /* @__PURE__ */ (() => Array.isArray)();
-function isFunction(value) {
-  return typeof value === "function";
-}
-
-// src/router.ts
 function routes(middlewares) {
   const paths = [];
   const filters = [];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "alien-middleware",
   "type": "module",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -36,7 +36,7 @@
     "tsc-lint": "^0.1.9",
     "tsup": "^8.4.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.1.2"
+    "vitest": "^3.1.3"
   },
   "dependencies": {
     "pathic": "^0.1.6"

package/readme.md

@@ -186,45 +186,71 @@ request middlewares, **except** when the middleware chain is nested inside
 another chain, since the outer chain will still have a chance to return a
 `Response`.
 
-### Nesting Chains
+### Merging a Middleware Chain
 
-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.
+By passing a middleware chain to `.use()`, you can merge it with the existing chain. Its middlewares will be executed _after_ any existing middlewares in this chain and _before_ any new middlewares you add later.
 
 ```typescript
 const innerChain = chain((context: RequestContext) => {
-  console.log('Inner chain start')
-  return { define: { innerData: 'secret' } } // Only available inside innerChain
-}).use((context: RequestContext<{ innerData: string }>) => {
-  console.log('Accessing inner data:', context.innerData)
+  return { helloFromInner: true }
 })
 
-const outerMiddleware = (context: RequestContext) => {
-  // context.innerData is not accessible here
-  console.log('Outer middleware after inner chain')
-  if (!('innerData' in context)) {
-    console.log('innerData is correctly scoped.')
-  }
-  return new Response('Finished')
-}
-
-const finalApp = chain().use(innerChain).use(outerMiddleware)
-// Output when executing the finalApp chain:
-//   Inner chain start
-//   Accessing inner data: secret
-//   Outer middleware after inner chain
-//   innerData is correctly scoped.
+const app = chain()
+  .use(innerChain)
+  .use(context => {
+    context.helloFromInner // Output: true
+  })
 ```
 
-If a nested chain does not return a `Response`, execution continues with the next middleware in the outer chain.
+### Isolating a Middleware Chain
 
-### Merging Chains
+When adding a middleware chain to another, you may use the `isolate()` method to isolate the nested chain from the outer chain.
 
-You can merge two middleware chains using the `merge` method. This is useful if you want to combine middleware from multiple files or modules.
+```typescript
+const isolatedChain = chain().isolate()
+```
+
+This prevents the nested chain from affecting middleware in the outer chain (e.g. through _request plugins_).
 
 ```typescript
-const mergedApp = chain().use(middleware1).merge(chain().use(middleware2))
-// …is equivalent to…
-const mergedApp = chain().use(middleware1).use(middleware2)
+const innerChain = chain()
+  .use(() => ({
+    foo: true,
+  }))
+  .use(context => {
+    context.foo // Output: true
+  })
+
+const outerChain = chain()
+  .use(innerChain.isolate())
+  .use(context => {
+    context.foo // Output: undefined
+  })
+```
+
+If an isolated chain does not return a `Response`, execution continues with the next middleware in the outer chain.
+
+### Escaping a Middleware Chain
+
+To stop processing a request (e.g. skip any remaining middlewares), use the `context.passThrough()` method. The Hattip adapter is responsible for deciding the appropriate action based on the request.
+
+In the context of an isolated chain, `context.passThrough()` will skip remaining middlewares in the isolated chain, but the outer chain will continue execution with the next middleware.
+
+```ts
+const app = chain()
+  .use(context => {
+    if (!context.request.headers.has('Authorization')) {
+      // It's best practice to return immediately after
+      // calling passThrough()
+      return context.passThrough()
+    }
+    return new Response('Authorized', { status: 200 })
+  })
+  .use(context => {
+    // This will never run, since the previous middleware
+    // either returns a Response or calls passThrough()
+    throw new Error('This request middleware will never run')
+  })
 ```
 
 ### Safe Environment Variables
@@ -338,7 +364,7 @@ import { routes } from 'alien-middleware/router'
 // Define a middleware that adds a user to the context
 const addUserMiddleware = (context: RequestContext): RequestPlugin => {
   const user = { id: 123, name: 'Alice' }
-  return { define: { user } }
+  return { user }
 }
 
 // Create a chain with the middleware