alien-middleware 0.7.0 → 0.8.0

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

@@ -24,9 +24,9 @@ type InputEnv<T extends MiddlewareChain> = Inputs<T>['env'];
 type Current<T extends MiddlewareChain> = T['$']['current'];
 type Properties<T extends MiddlewareChain> = Current<T>['properties'];
 type Env<T extends MiddlewareChain> = Current<T>['env'];
-type MiddlewareTypes<TProperties extends object = any, TEnv extends object = any> = {
-    properties: TProperties;
+type MiddlewareTypes<TEnv extends object = any, TProperties extends object = any> = {
     env: TEnv;
+    properties: TProperties;
 };
 interface HattipContext<TPlatform, TEnv extends object> extends AdapterRequestContext<TPlatform> {
     /**
@@ -48,13 +48,13 @@ type Intersectable<T extends object> = [T] extends [never] ? {} : [T] extends [A
  * 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>;
+type RequestContext<TEnv extends object = any, TProperties extends object = never, TPlatform = any> = HattipContext<TPlatform, TEnv> & Intersectable<TProperties>;
 /**
  * Extract a `RequestContext` type from a `MiddlewareChain` type.
  *
  * 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 MiddlewareContext<T extends MiddlewareChain> = [T] extends [never] ? RequestContext<{}, never, unknown> : RequestContext<Env<T>, Properties<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>;
@@ -67,34 +67,22 @@ type RequestHandler<TInputs extends MiddlewareTypes = any, TCurrent extends Midd
  * response middleware. This means it will run *after* a `Response` is generated
  * by a request middleware.
  */
-type Middleware<TProperties extends object = any, TEnv extends object = any, TPlatform = any> = (context: RequestContext<TProperties, TEnv, TPlatform>, response: Response) => Awaitable<Response | RequestPlugin | void>;
+type Middleware<TEnv extends object = any, TProperties extends object = any, TPlatform = any> = (context: RequestContext<TEnv, TProperties, TPlatform>, response: Response) => Awaitable<Response | RequestPlugin | void>;
 /**
  * Extract a `Middleware` type from a `MiddlewareChain` type.
  */
-type ExtractMiddleware<T extends MiddlewareChain> = Middleware<Properties<T>, Env<T>, Platform<T>>;
+type ExtractMiddleware<T extends MiddlewareChain> = Middleware<Env<T>, Properties<T>, Platform<T>>;
 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> = {} & {
-    properties: Merge<Properties<TParent>, Omit<TPlugin, keyof RequestEnvPlugin>>;
-    env: Merge<Env<TParent>, TPlugin['env']>;
-};
+type ApplyRequestPlugin<TParent extends MiddlewareChain, TPlugin extends RequestPlugin> = {} & MiddlewareTypes<Merge<Env<TParent>, TPlugin['env']>, Merge<Properties<TParent>, Omit<TPlugin, keyof RequestEnvPlugin>>>;
 /**
  * This applies a middleware to a chain. If the type `TMiddleware` is itself a
  * chain, it's treated as a nested chain, which won't leak its plugins into the
  * parent chain.
  */
-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: {};
-}, {
-    properties: {};
-    env: {};
-}, unknown>;
+type ApplyMiddleware<TFirst extends MiddlewareChain, TSecond extends Middleware<Env<TFirst>, Properties<TFirst>, Platform<TFirst>>> = RequestHandler<Inputs<TFirst>, TSecond extends MiddlewareChain ? MiddlewareTypes<Merge<Env<TFirst>, Env<TSecond>>, Merge<Properties<TFirst>, Properties<TSecond>>> : TSecond extends () => Awaitable<infer TResult> ? TResult extends RequestPlugin ? ApplyRequestPlugin<TFirst, TResult> : Current<TFirst> : Current<TFirst>, Platform<TFirst>>;
+type EmptyMiddlewareChain = MiddlewareChain<MiddlewareTypes<{}, {}>, MiddlewareTypes<{}, {}>, unknown>;
 type ApplyFirstMiddleware<T extends Middleware> = T extends MiddlewareChain ? T : ApplyMiddleware<EmptyMiddlewareChain, T>;
 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> & {
@@ -139,13 +127,7 @@ TPlatform = any> {
      */
     isolate(): ((ctx: IsolatedContext<this>) => Promise<Response | void>) | typeof noop;
 }
-declare function chain<TProperties extends object = {}, TEnv extends object = {}, TPlatform = unknown>(): MiddlewareChain<{
-    env: TEnv;
-    properties: TProperties;
-}, {
-    env: TEnv;
-    properties: TProperties;
-}, TPlatform>;
+declare function chain<TEnv extends object = {}, TProperties extends object = {}, TPlatform = unknown>(): MiddlewareChain<MiddlewareTypes<TEnv, TProperties>, MiddlewareTypes<TEnv, TProperties>, 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 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 @@
 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';
+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-BP2sjKus.js';
 import '@hattip/core';

package/dist/router.d.ts

@@ -1,6 +1,6 @@
 import { InferParams } from 'pathic';
-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 { M as MiddlewareChain, E as EmptyMiddlewareChain, a as MiddlewareContext, R as RouteHandler, b as RouteMethod } from './index-BP2sjKus.js';
+export { c as RouterContext } from './index-BP2sjKus.js';
 import 'radashi';
 import '@hattip/core';
 

package/package.json

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

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