Drop 'Definition' from step defn names and refactor impl classes

This makes the handler implementations entirely internal (no longer
expected to be provided through the manual or chained APIs, neither
types nor classes actually exposed directly) so that the external API is
simpler for manual rule building (just use requestSteps.XStep), the
internal state is better contained, and the rule creation flow loses a
branch - it now always converts a definition to a rule.

This is a breaking change, but combined with previous changes to rename
the export may mean that cumulatively existing code actually still works
just fine. If you have any references to Definitions, you should simply
drop those.

Author: pimterry

src/main.ts

@@ -26,18 +26,16 @@ export type {
 
 // Export rule data builders & type definitions:
 import * as matchers from './rules/matchers';
-import type { RequestStep, RequestStepOptions } from './rules/requests/request-steps';
 import * as requestStepDefinitions from './rules/requests/request-step-definitions';
-import type { WebSocketStep } from './rules/websockets/websocket-steps';
 import * as webSocketStepDefinitions from './rules/websockets/websocket-step-definitions';
 import * as completionCheckers from './rules/completion-checkers';
 
+export type RequestStep = requestStepDefinitions.RequestStepDefinition;
+export type WebSocketStep = webSocketStepDefinitions.WebSocketStepDefinition;
+
 export {
     matchers,
-    RequestStep,
-    RequestStepOptions,
     requestStepDefinitions as requestSteps,
-    WebSocketStep,
     webSocketStepDefinitions as webSocketSteps,
     completionCheckers
 };

src/rules/passthrough-handling.ts

@@ -20,7 +20,7 @@ import {
     CallbackRequestResult,
     CallbackResponseMessageResult
 } from './requests/request-step-definitions';
-import { AbortError } from './requests/request-steps';
+import { AbortError } from './requests/request-step-impls';
 import {
     CADefinition,
     PassThroughLookupOptions

src/rules/requests/request-rule-builder.ts

@@ -6,20 +6,20 @@ import { Headers, CompletedRequest, Method, MockedEndpoint, Trailers } from "../
 import type { RequestRuleData } from "./request-rule";
 
 import {
-    FixedResponseStepDefinition,
-    PassThroughStepDefinition,
-    CallbackStepDefinition,
+    RequestStepDefinition,
+    FixedResponseStep,
+    PassThroughStep,
+    CallbackStep,
     CallbackResponseResult,
-    StreamStepDefinition,
-    CloseConnectionStepDefinition,
-    TimeoutStepDefinition,
+    StreamStep,
+    CloseConnectionStep,
+    TimeoutStep,
     PassThroughStepOptions,
-    FileStepDefinition,
-    JsonRpcResponseStepDefinition,
-    ResetConnectionStepDefinition,
+    FileStep,
+    JsonRpcResponseStep,
+    ResetConnectionStep,
     CallbackResponseMessageResult,
-    RequestStepDefinition,
-    DelayStepDefinition
+    DelayStep
 } from "./request-step-definitions";
 import { byteLength } from "../../util/util";
 import { BaseRuleBuilder } from "../base-rule-builder";
@@ -94,7 +94,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
      * Add a delay (in milliseconds) before the next step in the rule
      */
     waitFor(ms: number): this {
-        this.steps.push(new DelayStepDefinition(ms));
+        this.steps.push(new DelayStep(ms));
         return this;
     }
 
@@ -151,7 +151,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
             trailers = headersOrTrailers as Trailers | undefined;
         }
 
-        this.steps.push(new FixedResponseStepDefinition(
+        this.steps.push(new FixedResponseStep(
             status,
             statusMessage,
             data,
@@ -196,7 +196,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
             // connection after the response is sent, which can confuse clients.
         }, headers);
 
-        this.steps.push(new FixedResponseStepDefinition(status, undefined, jsonData, headers));
+        this.steps.push(new FixedResponseStep(status, undefined, jsonData, headers));
 
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
@@ -232,7 +232,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
     thenCallback(callback:
         (request: CompletedRequest) => MaybePromise<CallbackResponseResult>
     ): Promise<MockedEndpoint> {
-        this.steps.push(new CallbackStepDefinition(callback));
+        this.steps.push(new CallbackStep(callback));
 
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
@@ -263,7 +263,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
      * @category Responses
      */
     thenStream(status: number, stream: Readable, headers?: Headers): Promise<MockedEndpoint> {
-        this.steps.push(new StreamStepDefinition(status, stream, headers));
+        this.steps.push(new StreamStep(status, stream, headers));
 
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
@@ -314,7 +314,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
             headers = pathOrHeaders as Headers | undefined;
         }
 
-        this.steps.push(new FileStepDefinition(status, statusMessage, path, headers));
+        this.steps.push(new FileStep(status, statusMessage, path, headers));
 
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
@@ -344,7 +344,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
      * @category Responses
      */
     thenPassThrough(options?: PassThroughStepOptions): Promise<MockedEndpoint> {
-        this.steps.push(new PassThroughStepDefinition(options));
+        this.steps.push(new PassThroughStep(options));
 
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
@@ -384,7 +384,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
             forwarding?: Omit<PassThroughStepOptions['forwarding'], 'targetHost'>
         } = {}
     ): Promise<MockedEndpoint> {
-        this.steps.push(new PassThroughStepDefinition({
+        this.steps.push(new PassThroughStep({
             ...options,
             forwarding: {
                 ...options.forwarding,
@@ -415,7 +415,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
      * @category Responses
      */
     thenCloseConnection(): Promise<MockedEndpoint> {
-        this.steps.push(new CloseConnectionStepDefinition());
+        this.steps.push(new CloseConnectionStep());
 
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
@@ -444,7 +444,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
      * @category Responses
      */
     thenResetConnection(): Promise<MockedEndpoint> {
-        this.steps.push(new ResetConnectionStepDefinition());
+        this.steps.push(new ResetConnectionStep());
 
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
@@ -469,7 +469,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
      * @category Responses
      */
     thenTimeout(): Promise<MockedEndpoint> {
-        this.steps.push(new TimeoutStepDefinition());
+        this.steps.push(new TimeoutStep());
 
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
@@ -487,7 +487,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
      * @category Responses
      */
     thenSendJsonRpcResult(result: any) {
-        this.steps.push(new JsonRpcResponseStepDefinition({ result }));
+        this.steps.push(new JsonRpcResponseStep({ result }));
 
         const rule = {
             ...this.buildBaseRuleData(),
@@ -505,7 +505,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
      * @category Responses
      */
     thenSendJsonRpcError(error: any) {
-        this.steps.push(new JsonRpcResponseStepDefinition({ error }));
+        this.steps.push(new JsonRpcResponseStep({ error }));
 
         const rule = {
             ...this.buildBaseRuleData(),

src/rules/requests/request-rule.ts

@@ -7,7 +7,7 @@ import { MaybePromise } from '@httptoolkit/util';
 
 import * as matchers from "../matchers";
 import { type RequestStepDefinition } from "./request-step-definitions";
-import { StepLookup, RequestStep } from "./request-steps";
+import { StepLookup, RequestStepImpl } from "./request-step-impls";
 import * as completionCheckers from "../completion-checkers";
 import { validateMockRuleData } from '../rule-serialization';
 
@@ -29,13 +29,13 @@ export interface RequestRuleData {
     id?: string;
     priority?: number; // Higher is higher, by default 0 is fallback, 1 is normal, must be positive
     matchers: matchers.RequestMatcher[];
-    steps: Array<RequestStep | RequestStepDefinition>;
+    steps: Array<RequestStepDefinition>;
     completionChecker?: completionCheckers.RuleCompletionChecker;
 }
 
 export class RequestRule implements RequestRule {
     private matchers: matchers.RequestMatcher[];
-    private steps: Array<RequestStep>;
+    private steps: Array<RequestStepImpl>;
     private completionChecker?: completionCheckers.RuleCompletionChecker;
 
     public id: string;
@@ -52,12 +52,10 @@ export class RequestRule implements RequestRule {
         this.completionChecker = data.completionChecker;
 
         this.steps = data.steps.map((stepDefinition, i) => {
-            const step = 'handle' in stepDefinition
-                ? stepDefinition
-                : Object.assign(
-                    Object.create(StepLookup[stepDefinition.type].prototype),
-                    stepDefinition
-                ) as RequestStep;
+            const step = Object.assign(
+                Object.create(StepLookup[stepDefinition.type].prototype),
+                stepDefinition
+            ) as RequestStepImpl;
 
             if (StepLookup[step.type].isFinal && i !== data.steps.length - 1) {
                 throw new Error(

src/rules/requests/request-step-definitions.ts

@@ -44,16 +44,23 @@ import {
 /*
 This file defines request step *definitions*, which includes everything necessary to define
 and serialize their behaviour, but doesn't include the actual handling logic (which
-lives in ./request-steps instead). This is intended to allow tree-shaking in browser usage
-or remote clients to import only the necessary code, with no need to include all the real
-request-processing and handling code that is only used at HTTP-runtime, so isn't relevant when
-defining rules.
+lives in the Impl classes in ./request-steps instead). This is intended to allow tree-shaking
+in browser usage or remote clients, importing only the necessary code, with no need to include
+all the real request-processing and handling code that is only used at HTTP-runtime, so isn't
+relevant when defining rules.
 
-Every RequestStep extends its definition, simply adding a handle() method, which handles
+Every RequestStepImpl extends its definition, simply adding a handle() method, which handles
 requests according to the configuration, and adding a deserialize static method that takes
 the serialized output from the serialize() methods defined here and creates a working step.
 */
 
+/**
+ * The definition of a request rule step, which can be passed to Mockttp to define
+ * a rule.
+ *
+ * Implementation of the step is not included in the definition classes, but
+ * instead exists in an *Impl class defined separately and used internally.
+ */
 export interface RequestStepDefinition extends Explainable, Serializable {
     type: keyof typeof StepDefinitionLookup;
 }
@@ -251,7 +258,7 @@ function validateCustomHeaders(
     }
 }
 
-export class FixedResponseStepDefinition extends Serializable implements RequestStepDefinition {
+export class FixedResponseStep extends Serializable implements RequestStepDefinition {
 
     readonly type = 'simple';
     static readonly isFinal = true;
@@ -301,7 +308,7 @@ export interface CallbackRequestMessage {
     args: [Replace<CompletedRequest, { body: SerializedBody }>];
 }
 
-export class CallbackStepDefinition extends Serializable implements RequestStepDefinition {
+export class CallbackStep extends Serializable implements RequestStepDefinition {
 
     readonly type = 'callback';
     static readonly isFinal = true;
@@ -359,7 +366,7 @@ type StreamStepEventMessage =
     { type: 'arraybuffer', value: string } |
     { type: 'nil' };
 
-export class StreamStepDefinition extends Serializable implements RequestStepDefinition {
+export class StreamStep extends Serializable implements RequestStepDefinition {
 
     readonly type = 'stream';
     static readonly isFinal = true;
@@ -421,7 +428,7 @@ export class StreamStepDefinition extends Serializable implements RequestStepDef
     }
 }
 
-export class FileStepDefinition extends Serializable implements RequestStepDefinition {
+export class FileStep extends Serializable implements RequestStepDefinition {
 
     readonly type = 'file';
     static readonly isFinal = true;
@@ -722,7 +729,7 @@ export interface BeforePassthroughResponseRequest {
  */
 export const SERIALIZED_OMIT = "__mockttp__transform__omit__";
 
-export class PassThroughStepDefinition extends Serializable implements RequestStepDefinition {
+export class PassThroughStep extends Serializable implements RequestStepDefinition {
 
     readonly type = 'passthrough';
     static readonly isFinal = true;
@@ -988,7 +995,7 @@ export class PassThroughStepDefinition extends Serializable implements RequestSt
     }
 }
 
-export class CloseConnectionStepDefinition extends Serializable implements RequestStepDefinition {
+export class CloseConnectionStep extends Serializable implements RequestStepDefinition {
     readonly type = 'close-connection';
     static readonly isFinal = true;
 
@@ -997,7 +1004,7 @@ export class CloseConnectionStepDefinition extends Serializable implements Reque
     }
 }
 
-export class ResetConnectionStepDefinition extends Serializable implements RequestStepDefinition {
+export class ResetConnectionStep extends Serializable implements RequestStepDefinition {
     readonly type = 'reset-connection';
     static readonly isFinal = true;
 
@@ -1006,7 +1013,7 @@ export class ResetConnectionStepDefinition extends Serializable implements Reque
     }
 }
 
-export class TimeoutStepDefinition extends Serializable implements RequestStepDefinition {
+export class TimeoutStep extends Serializable implements RequestStepDefinition {
     readonly type = 'timeout';
     static readonly isFinal = true;
 
@@ -1015,7 +1022,7 @@ export class TimeoutStepDefinition extends Serializable implements RequestStepDe
     }
 }
 
-export class JsonRpcResponseStepDefinition extends Serializable implements RequestStepDefinition {
+export class JsonRpcResponseStep extends Serializable implements RequestStepDefinition {
     readonly type = 'json-rpc-response';
     static readonly isFinal = true;
 
@@ -1040,7 +1047,7 @@ export class JsonRpcResponseStepDefinition extends Serializable implements Reque
     }
 }
 
-export class DelayStepDefinition extends Serializable implements RequestStepDefinition {
+export class DelayStep extends Serializable implements RequestStepDefinition {
 
     readonly type = 'delay';
     static readonly isFinal = false;
@@ -1058,14 +1065,14 @@ export class DelayStepDefinition extends Serializable implements RequestStepDefi
 }
 
 export const StepDefinitionLookup = {
-    'simple': FixedResponseStepDefinition,
-    'callback': CallbackStepDefinition,
-    'stream': StreamStepDefinition,
-    'file': FileStepDefinition,
-    'passthrough': PassThroughStepDefinition,
-    'close-connection': CloseConnectionStepDefinition,
-    'reset-connection': ResetConnectionStepDefinition,
-    'timeout': TimeoutStepDefinition,
-    'json-rpc-response': JsonRpcResponseStepDefinition,
-    'delay': DelayStepDefinition
+    'simple': FixedResponseStep,
+    'callback': CallbackStep,
+    'stream': StreamStep,
+    'file': FileStep,
+    'passthrough': PassThroughStep,
+    'close-connection': CloseConnectionStep,
+    'reset-connection': ResetConnectionStep,
+    'timeout': TimeoutStep,
+    'json-rpc-response': JsonRpcResponseStep,
+    'delay': DelayStep
 }