refactor: rename plugins option to middleware on withSupabase

The array holds middleware entries (per-request behavior from
defineMiddleware) — the word 'plugins' is reserved for the package-level
concept whose client namespace goes in createClient({ plugins }). One
word per concept: server-side composition is 'middleware', client-side
namespaces are 'plugins', a Plugin is the package that ships both.

PluginsCtx -> MiddlewareCtx; overload trick unchanged
(middleware?: never on overload 1).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: mandarini

src/with-supabase.test.ts

@@ -159,8 +159,8 @@ describe('withSupabase', () => {
     })
   })
 
-  describe('plugins', () => {
-    it('composes plugins after the Supabase context is established', async () => {
+  describe('middleware', () => {
+    it('composes middleware after the Supabase context is established', async () => {
       const withFlag = defineMiddleware<
         'flag',
         void,
@@ -172,7 +172,7 @@ describe('withSupabase', () => {
       })
 
       const handler = withSupabase(
-        { auth: 'none', env: baseEnv, plugins: [withFlag()] },
+        { auth: 'none', env: baseEnv, middleware: [withFlag()] },
         async (_req, ctx) =>
           Response.json({ authMode: ctx.authMode, flag: ctx.flag }),
       )
@@ -183,7 +183,7 @@ describe('withSupabase', () => {
       expect(body.flag).toBe(true)
     })
 
-    it('plugin receives the Supabase context at runtime', async () => {
+    it('middleware receives the Supabase context at runtime', async () => {
       let capturedHasSupabase = false
 
       const withCapture = defineMiddleware<
@@ -200,15 +200,15 @@ describe('withSupabase', () => {
       })
 
       const handler = withSupabase(
-        { auth: 'none', env: baseEnv, plugins: [withCapture()] },
+        { auth: 'none', env: baseEnv, middleware: [withCapture()] },
         async () => Response.json({ ok: true }),
       )
 
       await handler(new Request('http://localhost'))
       expect(capturedHasSupabase).toBe(true)
     })
 
-    it('plugin can short-circuit before the handler', async () => {
+    it('middleware can short-circuit before the handler', async () => {
       const withBlock = defineMiddleware<
         'blocked',
         void,
@@ -222,7 +222,7 @@ describe('withSupabase', () => {
       const innerHandler = vi.fn(async () => Response.json({ ok: true }))
 
       const handler = withSupabase(
-        { auth: 'none', env: baseEnv, plugins: [withBlock()] },
+        { auth: 'none', env: baseEnv, middleware: [withBlock()] },
         innerHandler,
       )
 
@@ -231,7 +231,7 @@ describe('withSupabase', () => {
       expect(innerHandler).not.toHaveBeenCalled()
     })
 
-    it('plugins run in array order (first = outermost, runs first on request)', async () => {
+    it('middleware run in array order (first = outermost, runs first on request)', async () => {
       const order: string[] = []
 
       const withA = defineMiddleware<'a', void, Record<never, never>, true>({
@@ -250,7 +250,7 @@ describe('withSupabase', () => {
       })
 
       const handler = withSupabase(
-        { auth: 'none', env: baseEnv, plugins: [withA(), withB()] },
+        { auth: 'none', env: baseEnv, middleware: [withA(), withB()] },
         async (_req, ctx) => Response.json({ a: ctx.a, b: ctx.b }),
       )
 
@@ -259,7 +259,7 @@ describe('withSupabase', () => {
       expect(await res.json()).toEqual({ a: true, b: true })
     })
 
-    it('CORS headers still apply when plugins are present', async () => {
+    it('CORS headers still apply when middleware are present', async () => {
       const withNoop = defineMiddleware<
         'noop',
         void,
@@ -271,7 +271,7 @@ describe('withSupabase', () => {
       })
 
       const handler = withSupabase(
-        { auth: 'none', env: baseEnv, plugins: [withNoop()] },
+        { auth: 'none', env: baseEnv, middleware: [withNoop()] },
         async () => Response.json({ ok: true }),
       )
 

src/with-supabase.ts

@@ -8,17 +8,17 @@ type AnyEntry = Entry<string, object, unknown>
 type AnyHandler = (req: Request, ctx: any) => Promise<Response>
 
 /**
- * Accumulate the ctx contributions of a plugin tuple — same logic as
+ * Accumulate the ctx contributions of a middleware tuple — same logic as
  * `pipeline`'s internal `Accumulate`, seeded from `object` (no `BaseContext`
  * or `_runtime` in the visible ctx type; see implementation note below).
  */
-type PluginsCtx<Plugins extends readonly AnyEntry[]> =
-  Plugins extends readonly [
+type MiddlewareCtx<Entries extends readonly AnyEntry[]> =
+  Entries extends readonly [
     Entry<infer Key extends string, object, infer Contribution>,
     ...infer Rest,
   ]
     ? Rest extends readonly AnyEntry[]
-      ? { [P in Key]: Contribution } & PluginsCtx<Rest>
+      ? { [P in Key]: Contribution } & MiddlewareCtx<Rest>
       : { [P in Key]: Contribution }
     : object
 
@@ -39,7 +39,7 @@ type PluginsCtx<Plugins extends readonly AnyEntry[]> =
  * ```ts
  * import { withSupabase } from '@supabase/server'
  *
- * // Without plugins — existing API, unchanged.
+ * // Without middleware — existing API, unchanged.
  * export default {
  *   fetch: withSupabase({ auth: 'user' }, async (req, ctx) => {
  *     const { data } = await ctx.supabase.rpc('get_my_profile')
@@ -49,15 +49,17 @@ type PluginsCtx<Plugins extends readonly AnyEntry[]> =
  * ```
  */
 export function withSupabase<Database = unknown>(
-  config: WithSupabaseConfig & { plugins?: never },
+  config: WithSupabaseConfig & { middleware?: never },
   handler: (req: Request, ctx: SupabaseContext<Database>) => Promise<Response>,
 ): (req: Request) => Promise<Response>
 
 /**
- * Variant that accepts a `plugins` array — each `withFoo(config)` call returns
- * an `Entry` from `@supabase/web-middleware`. Plugins run **after** the Supabase
- * context is established; they receive `ctx.supabase`, `ctx.userClaims`, etc.
- * already present and contribute their own typed keys on top.
+ * Variant that accepts a `middleware` array — each `withFoo(config)` call
+ * returns an `Entry` from `@supabase/web-middleware`. Middleware run **after**
+ * the Supabase context is established; they receive `ctx.supabase`,
+ * `ctx.userClaims`, etc. already present and contribute their own typed keys
+ * on top. (This is the server leg of a Plugin: the package's middleware goes
+ * here; its client namespace goes in `createClient`'s `plugins` array.)
  *
  * @example
  * ```ts
@@ -67,7 +69,7 @@ export function withSupabase<Database = unknown>(
  *
  * export default {
  *   fetch: withSupabase(
- *     { auth: 'user', plugins: [withRateLimit({ rpm: 100 }), withGuestbook()] },
+ *     { auth: 'user', middleware: [withRateLimit({ rpm: 100 }), withGuestbook()] },
  *     async (req, ctx) => {
  *       ctx.supabase      // from @supabase/server
  *       ctx.rateLimit     // from withRateLimit
@@ -78,27 +80,27 @@ export function withSupabase<Database = unknown>(
  * }
  * ```
  *
- * **Type note.** `PluginsCtx<Plugins>` accumulates the key contributions of the
- * plugins array. Plugins that declare `In` prerequisites on Supabase-provided
- * keys (`supabase`, `userClaims`, …) satisfy those at runtime (the Supabase
- * context is merged before plugins run) but not at the type level — a full
- * implementation would widen the prerequisite-validation seed to include
- * `SupabaseContext`. Ordering and collision checks within the plugins array work
- * normally via `web-middleware`'s runtime chain.
+ * **Type note.** `MiddlewareCtx<Entries>` accumulates the key contributions of
+ * the middleware array. Middleware that declare `In` prerequisites on
+ * Supabase-provided keys (`supabase`, `userClaims`, …) satisfy those at runtime
+ * (the Supabase context is merged before the middleware run) but not at the
+ * type level — a full implementation would widen the prerequisite-validation
+ * seed to include `SupabaseContext`. Ordering and collision checks within the
+ * middleware array work normally via `web-middleware`'s runtime chain.
  */
 export function withSupabase<
   Database = unknown,
-  const Plugins extends readonly AnyEntry[] = readonly AnyEntry[],
+  const Entries extends readonly AnyEntry[] = readonly AnyEntry[],
 >(
-  config: WithSupabaseConfig & { plugins: Plugins },
+  config: WithSupabaseConfig & { middleware: Entries },
   handler: (
     req: Request,
-    ctx: SupabaseContext<Database> & PluginsCtx<Plugins>,
+    ctx: SupabaseContext<Database> & MiddlewareCtx<Entries>,
   ) => Promise<Response>,
 ): (req: Request) => Promise<Response>
 
 export function withSupabase<Database = unknown>(
-  config: WithSupabaseConfig & { plugins?: readonly AnyEntry[] },
+  config: WithSupabaseConfig & { middleware?: readonly AnyEntry[] },
   handler: AnyHandler,
 ): (req: Request) => Promise<Response> {
   return async (req: Request) => {
@@ -126,11 +128,12 @@ export function withSupabase<Database = unknown>(
     }
 
     let response: Response
-    if (config.plugins?.length) {
-      // Compose plugins around the handler — same fold as pipeline's reduceRight,
-      // but without calling pipeline() so we supply the seeded ctx ourselves.
+    if (config.middleware?.length) {
+      // Compose the middleware around the handler — same fold as pipeline's
+      // reduceRight, but without calling pipeline() so we supply the seeded
+      // ctx ourselves.
       const composed = (
-        config.plugins as readonly AnyEntry[]
+        config.middleware as readonly AnyEntry[]
       ).reduceRight<AnyHandler>((h, entry) => entry(h), handler)
       // Seed _runtime so web-middleware entries recognise this as an upstream
       // context (isContext() checks for _runtime.getEnv). Falls through to