alien-middleware 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Alec Larson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+import { AdapterRequestContext, HattipHandler } from '@hattip/core';
+
+type RequestPlugin = {
+    /**
+     * Define properties on the request context.
+     */
+    define?: object;
+    /**
+     * Add type-safe environment variables.
+     */
+    env?: object;
+};
+type Inputs<T extends MiddlewareChain> = T['$']['input'];
+type Platform<T extends MiddlewareChain> = T['$']['platform'];
+type InputProperties<T extends MiddlewareChain> = Inputs<T>['properties'];
+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;
+    env: TEnv;
+};
+interface HattipContext<TPlatform, TEnv extends object> extends AdapterRequestContext<TPlatform> {
+    env<K extends keyof TEnv>(key: K): 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, {}>;
+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>;
+type RequestHandler<TInputs extends MiddlewareTypes, TCurrent extends MiddlewareTypes, TPlatform> = HattipHandler<TPlatform> & MiddlewareChain<TInputs, TCurrent, TPlatform>;
+/**
+ * Either a request middleware or a response middleware.
+ *
+ * If your middleware declares the `response` parameter, it's treated as a
+ * 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 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 ApplyMiddleware<TChain extends MiddlewareChain, TMiddleware> = TMiddleware extends MiddlewareChain ? RequestHandler<Inputs<TChain>, Current<TChain>, Platform<TChain>> : TMiddleware extends () => Awaitable<infer TPlugin extends RequestPlugin> ? RequestHandler<Inputs<TChain>, {
+    properties: Merge<Properties<TChain>, TPlugin['define']>;
+    env: Merge<Env<TChain>, TPlugin['env']>;
+}, Platform<TChain>> : RequestHandler<Inputs<TChain>, Current<TChain>, Platform<TChain>>;
+type ApplyFirstMiddleware<T extends Middleware> = ApplyMiddleware<MiddlewareChain<{
+    properties: {};
+    env: {};
+}, {
+    properties: {};
+    env: {};
+}, unknown>, T>;
+
+declare const kRequestChain: unique symbol;
+declare const kResponseChain: unique symbol;
+declare class MiddlewareChain<
+/** Values expected by the start of the chain. */
+TInputs extends MiddlewareTypes = any, 
+/** Values provided by the end of the chain. */
+TCurrent extends MiddlewareTypes = any, 
+/** Values from the host platform. */
+TPlatform = any> {
+    /** This property won't exist at runtime. It contains type information for inference purposes. */
+    $: {
+        input: TInputs;
+        current: TCurrent;
+        platform: TPlatform;
+    };
+    /** The number of parameters when called as a function. */
+    readonly length: 1;
+    protected [kRequestChain]: RequestMiddleware[];
+    protected [kResponseChain]: ResponseMiddleware[];
+    /**
+     * Attach a middleware. If the `response` paramter is declared, it will be
+     * treated as a response middleware. Otherwise, it will be treated as a
+     * request middleware.
+     *
+     * @returns a new `MiddlewareChain` instance
+     */
+    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<{
+    env: TEnv;
+    properties: TProperties;
+}, {
+    env: TEnv;
+    properties: TProperties;
+}, TPlatform>;
+declare function chain<const T extends Middleware = Middleware>(middleware: T): ApplyFirstMiddleware<T>;
+
+export { MiddlewareChain, chain };

package/dist/index.js

@@ -0,0 +1,106 @@
+// node_modules/.pnpm/radashi@12.5.0-beta.6d5c035/node_modules/radashi/dist/radashi.js
+var asyncIteratorSymbol = (
+  /* c8 ignore next */
+  Symbol.asyncIterator || Symbol.for("Symbol.asyncIterator")
+);
+function isFunction(value) {
+  return typeof value === "function";
+}
+function isPromise(value) {
+  return !!value && isFunction(value.then);
+}
+
+// src/index.ts
+var kRequestChain = Symbol("requestChain");
+var kResponseChain = Symbol("responseChain");
+var kIgnoreNotFound = Symbol("ignoreNotFound");
+var kMiddlewareCache = Symbol("middlewareCache");
+var MiddlewareChain = class _MiddlewareChain {
+  [kRequestChain] = [];
+  [kResponseChain] = [];
+  /**
+   * Attach a middleware. If the `response` paramter is declared, it will be
+   * treated as a response middleware. Otherwise, it will be treated as a
+   * request middleware.
+   *
+   * @returns a new `MiddlewareChain` instance
+   */
+  use(middleware) {
+    let requestChain = this[kRequestChain];
+    let responseChain = this[kResponseChain];
+    if (middleware.length < 2) {
+      requestChain = [...requestChain, middleware];
+    } else {
+      responseChain = [...responseChain, middleware];
+    }
+    async function handler(parentContext) {
+      const context = Object.create(parentContext);
+      context[kIgnoreNotFound] = true;
+      const cache = context[kMiddlewareCache] ||= /* @__PURE__ */ new Set();
+      let response;
+      let env;
+      for (const middleware2 of requestChain) {
+        if (cache.has(middleware2)) {
+          continue;
+        }
+        cache.add(middleware2);
+        let result = middleware2(context);
+        if (isPromise(result)) {
+          result = await result;
+        }
+        if (result) {
+          if (result instanceof Response) {
+            response = result;
+            break;
+          }
+          if (result.define) {
+            Object.assign(context, result.define);
+          }
+          if (result.env) {
+            env ||= createExtendedEnv(context);
+            Object.assign(env, result.env);
+          }
+        }
+      }
+      if (!response) {
+        if (parentContext[kIgnoreNotFound]) {
+          return;
+        }
+        return new Response("Not Found", { status: 404 });
+      }
+      for (const middleware2 of responseChain) {
+        if (cache.has(middleware2)) {
+          continue;
+        }
+        cache.add(middleware2);
+        let result = middleware2(context, response);
+        if (isPromise(result)) {
+          result = await result;
+        }
+        if (result && result instanceof Response) {
+          response = result;
+          continue;
+        }
+      }
+      return response;
+    }
+    Object.setPrototypeOf(handler, _MiddlewareChain.prototype);
+    handler[kRequestChain] = requestChain;
+    handler[kResponseChain] = responseChain;
+    return handler;
+  }
+};
+function createExtendedEnv(context) {
+  const env = /* @__PURE__ */ Object.create(null);
+  const superEnv = context.env;
+  context.env = (key) => env[key] ?? superEnv(key);
+  return env;
+}
+function chain(middleware) {
+  const handler = new MiddlewareChain();
+  return middleware ? handler.use(middleware) : handler;
+}
+export {
+  MiddlewareChain,
+  chain
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "alien-middleware",
+  "type": "module",
+  "version": "0.1.0",
+  "exports": {
+    "types": "./dist/index.d.ts",
+    "default": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "author": "Alec Larson",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alloc/alien-middleware.git"
+  },
+  "prettier": "@alloc/prettier-config",
+  "peerDependencies": {
+    "@hattip/core": "*"
+  },
+  "devDependencies": {
+    "@alloc/prettier-config": "^1.0.0",
+    "@hattip/core": "^0.0.49",
+    "@types/node": "^22.15.3",
+    "prettier": "^3.5.3",
+    "radashi": "12.5.0-beta.6d5c035",
+    "rimraf": "^6.0.1",
+    "tsc-lint": "^0.1.9",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2"
+  },
+  "scripts": {
+    "dev": "rimraf dist && tsup --sourcemap --watch",
+    "build": "rimraf dist && tsup",
+    "format": "prettier --write .",
+    "lint": "tsc-lint",
+    "test": "vitest"
+  }
+}

package/readme.md

@@ -0,0 +1,203 @@
+# alien-middleware
+
+Reusable middleware chains with top-notch TypeScript support. Built upon [Hattip](https://github.com/hattipjs/hattip) to avoid vendor lock-in using Web Standard APIs.
+
+## Philosophy
+
+By default, middlewares in `alien-middleware` are **synchronous** or **promise-based**. There is no `next()` function to call. If a middleware returns a `Response`, the chain is terminated. If a middleware wants to extend the request context, it returns an object implementing the `RequestPlugin` interface.
+
+Middlewares are either **request-oriented** (the default) or **response-oriented**. Response-oriented middlewares run _after_ a `Response` has been generated. They're allowed to return a new `Response`, but cannot return a `RequestPlugin` object.
+
+## Quick Start
+
+First, add the package to your project:
+
+```bash
+pnpm add alien-middleware
+```
+
+### Creating a Chain
+
+Import the `chain` function and initialize a middleware chain. You can optionally provide an initial middleware directly to `chain`.
+
+```typescript
+import { chain } from 'alien-middleware'
+
+// Create an empty chain
+const app = chain()
+
+// Or create a chain with an initial middleware
+const appWithInitial = chain(ctx => {
+  console.log('Initial middleware running for:', ctx.request.url)
+})
+```
+
+### Adding Middleware with `.use()`
+
+Use the `.use()` method to add middleware functions to the chain. Each call to `.use()` returns a _new_, immutable chain instance.
+
+```typescript
+import type { RequestContext } from 'alien-middleware'
+
+const firstMiddleware = (ctx: RequestContext) => {
+  console.log('First middleware')
+  // Doesn't return anything, so the chain continues
+}
+
+const secondMiddleware = (ctx: RequestContext) => {
+  console.log('Second middleware')
+  return new Response('Hello from middleware!', { status: 200 })
+  // Returns a Response, terminating the request-phase chain
+}
+
+// Add middleware sequentially
+const finalApp = app.use(firstMiddleware).use(secondMiddleware)
+```
+
+> [!NOTE]
+> Middleware chains are immutable. Each call to `.use()` returns a new chain instance.
+
+### Executing the Chain
+
+To run the middleware chain, call the chain instance itself with a context object. This object typically comes from an adapter like Hattip's [Node adapter](https://www.npmjs.com/package/@hattip/adapter-node).
+
+```typescript
+// Simplified context for demonstration (requires necessary imports like 'noop' if run directly)
+const context: AdapterRequestContext = {
+  request: new Request('http://localhost/test'),
+  ip: '127.0.0.1',
+  platform: {},
+  waitUntil: (promise: Promise<any>) => {},
+  passThrough: () => {},
+  env: (key: string) => undefined, // Basic env function
+}
+
+// Execute the chain
+const response = await finalApp(context) // Assuming finalApp from previous example
+
+console.log(await response.text()) // Output: Hello from middleware!
+console.log(response.status) // Output: 200
+```
+
+> [!NOTE]
+> If no middleware in the chain returns a `Response`, a `404 Not Found` response
+> is automatically returned, except for nested chains.
+
+### Request Middleware
+
+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')) {
+      return new Response('Forbidden', { status: 403 })
+    }
+    // Otherwise, continue the chain
+  }
+  ```
+
+- **Extending Context:** Return an object with a `define` property to add properties to the context for _downstream_ middleware.
+
+  ```typescript
+  const addUser = (ctx: RequestContext) => {
+    // In a real app, you might look up a user based on a token
+    const user = { id: 1, name: 'Alice' }
+
+    return { define: { user } }
+  }
+
+  const greetUser = (
+    ctx: RequestContext<{ user: { id: number; name: string } }>
+  ) => {
+    // The `user` property is now available thanks to `addUser`
+    return new Response(`Hello, ${ctx.user.name}!`)
+  }
+
+  const userApp = app.use(addUser).use(greetUser)
+  ```
+
+  > [!NOTE]
+  > If you're wondering why you need to return a `{ define: { … } }` object
+  > (rather than using simple assignment), it's because TypeScript is unable to
+  > infer the type of the context object downstream if you don't do this.
+  >
+  > Another thing to note is you don't typically define middlewares outside the
+  > `.use(…)` call expression, since that requires you to unnecessarily declare
+  > the type of the context object. It's better to define them inline.
+
+- **Extending Environment:** Return an object with an `env` property to add environment variables accessible via `ctx.env()`.
+
+  ```typescript
+  const addApiKey = (ctx: RequestContext) => {
+    return { env: { API_KEY: 'secret123' } }
+  }
+
+  const useApiKey = (ctx: RequestContext<{}, { API_KEY: string }>) => {
+    const key = ctx.env('API_KEY')
+    console.log('API Key:', key) // Output: API Key: secret123
+  }
+
+  const envApp = app.use(addApiKey).use(useApiKey)
+  ```
+
+### Response Middleware
+
+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 addHeader = (ctx: RequestContext, response: Response) => {
+  response.headers.set('X-Powered-By', 'alien-middleware')
+}
+
+const mainHandler = (ctx: RequestContext) => {
+  return new Response('Main content')
+}
+
+// `addHeader` runs after `mainHandler` generates a response
+const headerApp = app.use(mainHandler).use(addHeader)
+
+// Assuming `context` is defined as in the "Executing the Chain" example
+const responseWithHeader = await headerApp(context)
+console.log(responseWithHeader.headers.get('X-Powered-By')) // Output: alien-middleware
+```
+
+> [!NOTE]
+> Response middleware cannot extend the context using `{ define }` or `{ env }`.
+> They can only inspect the `Response` or replace it by returning a new
+> `Response`.
+
+### 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.
+
+```typescript
+const innerChain = chain((ctx: 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)
+})
+
+const outerMiddleware = (ctx: RequestContext) => {
+  // ctx.innerData is not accessible here
+  console.log('Outer middleware after inner chain')
+  if (!('innerData' in ctx)) {
+    console.log('innerData is correctly scoped.')
+  }
+  return new Response('Finished')
+}
+
+const nestedApp = app.use(innerChain).use(outerMiddleware)
+
+// Assuming `context` is defined as in the "Executing the Chain" example
+await nestedApp(context)
+// Output:
+// Inner chain start
+// Accessing inner data: secret
+// Outer middleware after inner chain
+// innerData is correctly scoped.
+```
+
+If a nested chain does not return a `Response`, execution continues with the next middleware in the outer chain.