@zhin.js/middleware 1.0.11 → 1.0.13

package/lib/definition.d.ts

@@ -1,27 +1,50 @@
-import type { CapabilityContext } from '@zhin.js/feature-kit';
+/**
+ * Middleware authoring API consumed from `zhin.js/middleware`.
+ * @module zhin.js/middleware
+ */
+import type { AdapterClient, CapabilityContext, RegisteredAdapterName } from '@zhin.js/feature-kit';
 declare const middlewareBrand: "zhin.middleware/1";
 export type MiddlewarePhase = 'before-dispatch' | 'after-dispatch';
 export type MiddlewareTarget = 'inbound' | 'outbound';
 export type MiddlewareNext = () => Promise<void>;
-export interface MiddlewareContext<TInput = unknown, TConfig = unknown> extends CapabilityContext<TConfig> {
+export interface MiddlewareContext<TInput = unknown, TConfig = unknown, TAdapter extends string | undefined = undefined> extends CapabilityContext<TConfig> {
     readonly input: TInput;
+    /** Lazily resolved native Client. Without `adapter`, its static type is `unknown`. */
+    readonly $client: AdapterClient<TAdapter>;
 }
-export interface MiddlewareDefinition<TInput = unknown, TConfig = unknown> {
+export interface MiddlewareDefinition<TInput = unknown, TConfig = unknown, TAdapter extends string | undefined = string | undefined> {
+    /** @internal Runtime feature brand. */
     readonly $feature: typeof middlewareBrand;
     readonly phase: MiddlewarePhase;
     readonly target: MiddlewareTarget;
     readonly order: number;
-    handle(context: MiddlewareContext<TInput, TConfig>, next: MiddlewareNext): void | Promise<void>;
+    readonly adapter?: TAdapter;
+    handle(context: MiddlewareContext<TInput, TConfig, TAdapter>, next: MiddlewareNext): void | Promise<void>;
 }
 declare module '@zhin.js/plugin-runtime' {
-    interface PluginSetupContext<TConfig> {
-        addMiddleware<TInput = unknown>(localName: string, definition: MiddlewareDefinition<TInput, TConfig>): void;
+    interface PluginSetupContext<TConfig = unknown> {
+        addMiddleware<TInput = unknown>(localName: string, definition: MiddlewareDefinition<TInput, TConfig, string | undefined>): void;
     }
 }
-export declare function defineMiddleware<TInput = unknown, TConfig = unknown>(definition: Omit<MiddlewareDefinition<TInput, TConfig>, '$feature' | 'phase' | 'target' | 'order'> & {
+/**
+ * Define ordered inbound or outbound middleware.
+ * Call `next()` to continue the chain; omit it to stop dispatch deliberately.
+ *
+ * @public
+ */
+type MiddlewareAuthoringDefinition<TInput, TConfig> = (Omit<MiddlewareDefinition<TInput, TConfig, undefined>, '$feature' | 'phase' | 'target' | 'order'> & {
     readonly phase?: MiddlewarePhase;
     readonly target?: MiddlewareTarget;
     readonly order?: number;
-}): Readonly<MiddlewareDefinition<TInput, TConfig>>;
+}) | {
+    [TAdapter in RegisteredAdapterName]: Omit<MiddlewareDefinition<TInput, TConfig, TAdapter>, '$feature' | 'phase' | 'target' | 'order'> & {
+        readonly adapter: TAdapter;
+        readonly phase?: MiddlewarePhase;
+        readonly target?: MiddlewareTarget;
+        readonly order?: number;
+    };
+}[RegisteredAdapterName];
+export declare function defineMiddleware<TInput = unknown, TConfig = unknown>(definition: MiddlewareAuthoringDefinition<TInput, TConfig>): Readonly<MiddlewareDefinition<TInput, TConfig, string | undefined>>;
+/** @internal Runtime validation for convention-discovered modules. */
 export declare function parseMiddlewareDefinition(value: unknown): MiddlewareDefinition;
 export {};

package/lib/definition.js

@@ -3,6 +3,11 @@ export function defineMiddleware(definition) {
     if (typeof definition.handle !== 'function') {
         throw new TypeError('Middleware handle must be a function');
     }
+    const adapter = definition.adapter;
+    if (adapter !== undefined
+        && (typeof adapter !== 'string' || adapter.trim() === '')) {
+        throw new TypeError('Middleware adapter must be a non-empty string');
+    }
     const phase = definition.phase ?? 'before-dispatch';
     if (phase !== 'before-dispatch' && phase !== 'after-dispatch') {
         throw new TypeError(`Invalid Middleware phase: ${String(phase)}`);
@@ -16,6 +21,7 @@ export function defineMiddleware(definition) {
         throw new TypeError('Middleware order must be a safe integer');
     return Object.freeze({ ...definition, $feature: middlewareBrand, phase, target, order });
 }
+/** @internal Runtime validation for convention-discovered modules. */
 export function parseMiddlewareDefinition(value) {
     if (!value || typeof value !== 'object')
         throw invalidMiddleware();
@@ -24,10 +30,14 @@ export function parseMiddlewareDefinition(value) {
         || typeof definition.handle !== 'function'
         || (definition.phase !== 'before-dispatch' && definition.phase !== 'after-dispatch')
         || (definition.target !== 'inbound' && definition.target !== 'outbound')
-        || !Number.isSafeInteger(definition.order))
+        || !Number.isSafeInteger(definition.order)
+        || !validAdapterName(definition.adapter))
         throw invalidMiddleware();
     return definition;
 }
 function invalidMiddleware() {
     return new TypeError('Middleware module must default-export defineMiddleware(...)');
 }
+function validAdapterName(adapter) {
+    return adapter === undefined || (typeof adapter === 'string' && adapter.trim() !== '');
+}

package/lib/index.d.ts

@@ -1,4 +1,11 @@
+/**
+ * Ordered inbound and outbound middleware authoring contracts.
+ * @module @zhin.js/middleware
+ */
+/** @public Middleware authoring contract and `defineMiddleware`. */
 export * from './definition.js';
+/** @internal Runtime middleware projection. */
 export * from './middleware-index.js';
+/** @internal Feature provider installed by the Runtime composition root. */
 export * from './provider.js';
 export { default } from './provider.js';

package/lib/index.js

@@ -1,4 +1,11 @@
+/**
+ * Ordered inbound and outbound middleware authoring contracts.
+ * @module @zhin.js/middleware
+ */
+/** @public Middleware authoring contract and `defineMiddleware`. */
 export * from './definition.js';
+/** @internal Runtime middleware projection. */
 export * from './middleware-index.js';
+/** @internal Feature provider installed by the Runtime composition root. */
 export * from './provider.js';
 export { default } from './provider.js';

package/lib/middleware-index.d.ts

@@ -7,6 +7,7 @@ export interface MiddlewareDescriptor {
     readonly phase: MiddlewarePhase;
     readonly target: MiddlewareTarget;
     readonly order: number;
+    readonly adapter?: string;
 }
 export declare class MiddlewareIndex {
     #private;

package/lib/middleware-index.js

@@ -1,4 +1,4 @@
-import { createCapabilityContext } from '@zhin.js/feature-kit';
+import { createCapabilityContext, operationClientAdapter, readOperationClient, } from '@zhin.js/feature-kit';
 export class MiddlewareIndex {
     snapshot;
     $projection = 'zhin.middleware-index/1';
@@ -13,6 +13,7 @@ export class MiddlewareIndex {
             phase: slot.definition.phase,
             target: slot.definition.target,
             order: slot.definition.order,
+            ...(slot.definition.adapter ? { adapter: slot.definition.adapter } : {}),
             slot,
         })).sort((left, right) => compareMiddleware(left, right, topology)));
     }
@@ -20,7 +21,8 @@ export class MiddlewareIndex {
         return this.#records.map(({ slot: _slot, ...descriptor }) => descriptor);
     }
     async run(input, terminal = async () => undefined, target = 'inbound') {
-        const records = this.#records.filter((record) => record.target === target);
+        const clientAdapter = operationClientAdapter(input);
+        const records = this.#records.filter((record) => record.target === target && (!record.adapter || record.adapter === clientAdapter));
         let cursor = -1;
         const dispatch = async (index) => {
             if (index <= cursor)
@@ -29,10 +31,15 @@ export class MiddlewareIndex {
             const record = records[index];
             if (!record)
                 return terminal();
-            const context = Object.freeze({
+            const context = {
                 ...createCapabilityContext(this.snapshot, record.owner),
                 input,
+            };
+            Object.defineProperty(context, '$client', {
+                enumerable: true,
+                get: () => readOperationClient(input, record.adapter),
             });
+            Object.freeze(context);
             await record.slot.definition.handle(context, () => dispatch(index + 1));
         };
         await dispatch(0);

package/lib/provider.d.ts

@@ -1,5 +1,5 @@
 import { MiddlewareIndex } from './middleware-index.js';
 export declare const middlewareFeatureId: import("@zhin.js/plugin-runtime").FeatureId;
-declare const middlewareFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<import("./definition.js").MiddlewareDefinition<unknown, unknown>, MiddlewareIndex>>;
+declare const middlewareFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<import("./definition.js").MiddlewareDefinition<unknown, unknown, string | undefined>, MiddlewareIndex>>;
 export { middlewareFeature };
 export default middlewareFeature;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/middleware",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "Convention-based Middleware Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,8 +17,8 @@
     "src"
   ],
   "dependencies": {
-    "@zhin.js/feature-kit": "1.0.11",
-    "@zhin.js/plugin-runtime": "1.1.6"
+    "@zhin.js/feature-kit": "1.0.13",
+    "@zhin.js/plugin-runtime": "1.1.8"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/definition.ts

@@ -1,4 +1,12 @@
-import type { CapabilityContext } from '@zhin.js/feature-kit';
+/**
+ * Middleware authoring API consumed from `zhin.js/middleware`.
+ * @module zhin.js/middleware
+ */
+import type {
+  AdapterClient,
+  CapabilityContext,
+  RegisteredAdapterName,
+} from '@zhin.js/feature-kit';
 
 const middlewareBrand = 'zhin.middleware/1' as const;
 
@@ -6,41 +14,81 @@ export type MiddlewarePhase = 'before-dispatch' | 'after-dispatch';
 export type MiddlewareTarget = 'inbound' | 'outbound';
 export type MiddlewareNext = () => Promise<void>;
 
-export interface MiddlewareContext<TInput = unknown, TConfig = unknown>
+export interface MiddlewareContext<
+  TInput = unknown,
+  TConfig = unknown,
+  TAdapter extends string | undefined = undefined,
+>
   extends CapabilityContext<TConfig> {
   readonly input: TInput;
+  /** Lazily resolved native Client. Without `adapter`, its static type is `unknown`. */
+  readonly $client: AdapterClient<TAdapter>;
 }
 
-export interface MiddlewareDefinition<TInput = unknown, TConfig = unknown> {
+export interface MiddlewareDefinition<
+  TInput = unknown,
+  TConfig = unknown,
+  TAdapter extends string | undefined = string | undefined,
+> {
+  /** @internal Runtime feature brand. */
   readonly $feature: typeof middlewareBrand;
   readonly phase: MiddlewarePhase;
   readonly target: MiddlewareTarget;
   readonly order: number;
-  handle(context: MiddlewareContext<TInput, TConfig>, next: MiddlewareNext): void | Promise<void>;
+  readonly adapter?: TAdapter;
+  handle(
+    context: MiddlewareContext<TInput, TConfig, TAdapter>,
+    next: MiddlewareNext,
+  ): void | Promise<void>;
 }
 
 declare module '@zhin.js/plugin-runtime' {
-  interface PluginSetupContext<TConfig> {
+  interface PluginSetupContext<TConfig = unknown> {
     addMiddleware<TInput = unknown>(
       localName: string,
-      definition: MiddlewareDefinition<TInput, TConfig>,
+      definition: MiddlewareDefinition<TInput, TConfig, string | undefined>,
     ): void;
   }
 }
 
+/**
+ * Define ordered inbound or outbound middleware.
+ * Call `next()` to continue the chain; omit it to stop dispatch deliberately.
+ *
+ * @public
+ */
+type MiddlewareAuthoringDefinition<TInput, TConfig> =
+  | (Omit<
+      MiddlewareDefinition<TInput, TConfig, undefined>,
+      '$feature' | 'phase' | 'target' | 'order'
+    > & {
+      readonly phase?: MiddlewarePhase;
+      readonly target?: MiddlewareTarget;
+      readonly order?: number;
+    })
+  | {
+      [TAdapter in RegisteredAdapterName]: Omit<
+        MiddlewareDefinition<TInput, TConfig, TAdapter>,
+        '$feature' | 'phase' | 'target' | 'order'
+      > & {
+        readonly adapter: TAdapter;
+        readonly phase?: MiddlewarePhase;
+        readonly target?: MiddlewareTarget;
+        readonly order?: number;
+      }
+    }[RegisteredAdapterName];
+
 export function defineMiddleware<TInput = unknown, TConfig = unknown>(
-  definition: Omit<
-    MiddlewareDefinition<TInput, TConfig>,
-    '$feature' | 'phase' | 'target' | 'order'
-  > & {
-    readonly phase?: MiddlewarePhase;
-    readonly target?: MiddlewareTarget;
-    readonly order?: number;
-  },
-): Readonly<MiddlewareDefinition<TInput, TConfig>> {
+  definition: MiddlewareAuthoringDefinition<TInput, TConfig>,
+): Readonly<MiddlewareDefinition<TInput, TConfig, string | undefined>> {
   if (typeof definition.handle !== 'function') {
     throw new TypeError('Middleware handle must be a function');
   }
+  const adapter = (definition as { readonly adapter?: unknown }).adapter;
+  if (adapter !== undefined
+    && (typeof adapter !== 'string' || adapter.trim() === '')) {
+    throw new TypeError('Middleware adapter must be a non-empty string');
+  }
   const phase = definition.phase ?? 'before-dispatch';
   if (phase !== 'before-dispatch' && phase !== 'after-dispatch') {
     throw new TypeError(`Invalid Middleware phase: ${String(phase)}`);
@@ -51,9 +99,12 @@ export function defineMiddleware<TInput = unknown, TConfig = unknown>(
   }
   const order = definition.order ?? 0;
   if (!Number.isSafeInteger(order)) throw new TypeError('Middleware order must be a safe integer');
-  return Object.freeze({ ...definition, $feature: middlewareBrand, phase, target, order });
+  return Object.freeze({ ...definition, $feature: middlewareBrand, phase, target, order }) as Readonly<
+    MiddlewareDefinition<TInput, TConfig, string | undefined>
+  >;
 }
 
+/** @internal Runtime validation for convention-discovered modules. */
 export function parseMiddlewareDefinition(value: unknown): MiddlewareDefinition {
   if (!value || typeof value !== 'object') throw invalidMiddleware();
   const definition = value as Partial<MiddlewareDefinition>;
@@ -63,6 +114,7 @@ export function parseMiddlewareDefinition(value: unknown): MiddlewareDefinition
     || (definition.phase !== 'before-dispatch' && definition.phase !== 'after-dispatch')
     || (definition.target !== 'inbound' && definition.target !== 'outbound')
     || !Number.isSafeInteger(definition.order)
+    || !validAdapterName((definition as { readonly adapter?: unknown }).adapter)
   ) throw invalidMiddleware();
   return definition as MiddlewareDefinition;
 }
@@ -70,3 +122,7 @@ export function parseMiddlewareDefinition(value: unknown): MiddlewareDefinition
 function invalidMiddleware(): TypeError {
   return new TypeError('Middleware module must default-export defineMiddleware(...)');
 }
+
+function validAdapterName(adapter: unknown): boolean {
+  return adapter === undefined || (typeof adapter === 'string' && adapter.trim() !== '');
+}

package/src/index.ts

@@ -1,4 +1,11 @@
+/**
+ * Ordered inbound and outbound middleware authoring contracts.
+ * @module @zhin.js/middleware
+ */
+/** @public Middleware authoring contract and `defineMiddleware`. */
 export * from './definition.js';
+/** @internal Runtime middleware projection. */
 export * from './middleware-index.js';
+/** @internal Feature provider installed by the Runtime composition root. */
 export * from './provider.js';
 export { default } from './provider.js';

package/src/middleware-index.ts

@@ -1,5 +1,9 @@
 import type { CapabilitySlot, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
-import { createCapabilityContext } from '@zhin.js/feature-kit';
+import {
+  createCapabilityContext,
+  operationClientAdapter,
+  readOperationClient,
+} from '@zhin.js/feature-kit';
 import type {
   MiddlewareContext,
   MiddlewareDefinition,
@@ -15,6 +19,7 @@ export interface MiddlewareDescriptor {
   readonly phase: MiddlewarePhase;
   readonly target: MiddlewareTarget;
   readonly order: number;
+  readonly adapter?: string;
 }
 
 interface MiddlewareRecord extends MiddlewareDescriptor {
@@ -37,6 +42,7 @@ export class MiddlewareIndex {
       phase: slot.definition.phase,
       target: slot.definition.target,
       order: slot.definition.order,
+      ...(slot.definition.adapter ? { adapter: slot.definition.adapter } : {}),
       slot,
     })).sort((left, right) => compareMiddleware(left, right, topology)));
   }
@@ -50,17 +56,24 @@ export class MiddlewareIndex {
     terminal: MiddlewareNext = async () => undefined,
     target: MiddlewareTarget = 'inbound',
   ): Promise<void> {
-    const records = this.#records.filter((record) => record.target === target);
+    const clientAdapter = operationClientAdapter(input);
+    const records = this.#records.filter((record) =>
+      record.target === target && (!record.adapter || record.adapter === clientAdapter));
     let cursor = -1;
     const dispatch = async (index: number): Promise<void> => {
       if (index <= cursor) throw new Error('Middleware next() called more than once');
       cursor = index;
       const record = records[index];
       if (!record) return terminal();
-      const context: MiddlewareContext<TInput> = Object.freeze({
+      const context = {
         ...createCapabilityContext(this.snapshot, record.owner),
         input,
+      } as MiddlewareContext<TInput>;
+      Object.defineProperty(context, '$client', {
+        enumerable: true,
+        get: () => readOperationClient(input, record.adapter),
       });
+      Object.freeze(context);
       await record.slot.definition.handle(context, () => dispatch(index + 1));
     };
     await dispatch(0);