@schmock/core 1.3.0 → 1.4.0

package/dist/builder.d.ts

@@ -13,6 +13,7 @@ export declare class CallableMockInstance {
     private callableRef;
     private server;
     private serverInfo;
+    private listeners;
     constructor(globalConfig?: Schmock.GlobalConfig);
     defineRoute(route: Schmock.RouteKey, generator: Schmock.Generator, config: Schmock.RouteConfig): this;
     setCallableRef(ref: Schmock.CallableMockInstance): void;
@@ -21,6 +22,11 @@ export declare class CallableMockInstance {
     called(method?: Schmock.HttpMethod, path?: string): boolean;
     callCount(method?: Schmock.HttpMethod, path?: string): number;
     lastRequest(method?: Schmock.HttpMethod, path?: string): Schmock.RequestRecord | undefined;
+    getRoutes(): Schmock.RouteInfo[];
+    getState(): Record<string, unknown>;
+    on(event: string, listener: (data: unknown) => void): this;
+    off(event: string, listener: (data: unknown) => void): this;
+    private emit;
     reset(): void;
     resetHistory(): void;
     resetState(): void;

package/dist/builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AA4EA;;;;GAIG;AACH,qBAAa,oBAAoB;IAUnB,OAAO,CAAC,YAAY;IAThC,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,YAAY,CAA4C;IAChE,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,WAAW,CAA2C;IAC9D,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,UAAU,CAAiC;gBAE/B,YAAY,GAAE,OAAO,CAAC,YAAiB;IAa3D,WAAW,CACT,KAAK,EAAE,OAAO,CAAC,QAAQ,EACvB,SAAS,EAAE,OAAO,CAAC,SAAS,EAC5B,MAAM,EAAE,OAAO,CAAC,WAAW,GAC1B,IAAI;IAqFP,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,oBAAoB,GAAG,IAAI;IAIvD,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,GAAG,IAAI;IAoBlC,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE;IAS5E,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO;IAS3D,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM;IAS7D,WAAW,CACT,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAC3B,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,GAAG,SAAS;IAYpC,KAAK,IAAI,IAAI;IAcb,YAAY,IAAI,IAAI;IAKpB,UAAU,IAAI,IAAI;IAWlB,MAAM,CAAC,IAAI,SAAI,EAAE,QAAQ,SAAc,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC;IAmFrE,KAAK,IAAI,IAAI;IAUP,MAAM,CACV,MAAM,EAAE,OAAO,CAAC,UAAU,EAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,GAC/B,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;IAoL5B;;;;OAIG;YACW,UAAU;IAcxB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAwDrB;;;;;;;;;;OAUG;YACW,iBAAiB;IAqG/B;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS;IA0BjB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;CActB"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AA4EA;;;;GAIG;AACH,qBAAa,oBAAoB;IAWnB,OAAO,CAAC,YAAY;IAVhC,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,YAAY,CAA4C;IAChE,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,WAAW,CAA2C;IAC9D,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,UAAU,CAAiC;IACnD,OAAO,CAAC,SAAS,CAAmD;gBAEhD,YAAY,GAAE,OAAO,CAAC,YAAiB;IAa3D,WAAW,CACT,KAAK,EAAE,OAAO,CAAC,QAAQ,EACvB,SAAS,EAAE,OAAO,CAAC,SAAS,EAC5B,MAAM,EAAE,OAAO,CAAC,WAAW,GAC1B,IAAI;IAqFP,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,oBAAoB,GAAG,IAAI;IAIvD,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,GAAG,IAAI;IAoBlC,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE;IAS5E,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO;IAS3D,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM;IAS7D,WAAW,CACT,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAC3B,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,GAAG,SAAS;IAYpC,SAAS,IAAI,OAAO,CAAC,SAAS,EAAE;IAQhC,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAMnC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAU1D,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAK3D,OAAO,CAAC,IAAI;IAWZ,KAAK,IAAI,IAAI;IAeb,YAAY,IAAI,IAAI;IAKpB,UAAU,IAAI,IAAI;IAWlB,MAAM,CAAC,IAAI,SAAI,EAAE,QAAQ,SAAc,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC;IAmFrE,KAAK,IAAI,IAAI;IAUP,MAAM,CACV,MAAM,EAAE,OAAO,CAAC,UAAU,EAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,GAC/B,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;IAgN5B;;;;OAIG;YACW,UAAU;IAgBxB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAwDrB;;;;;;;;;;OAUG;YACW,iBAAiB;IAqG/B;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS;IA0BjB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;CActB"}

package/dist/builder.js

@@ -60,6 +60,7 @@ export class CallableMockInstance {
     callableRef;
     server;
     serverInfo;
+    listeners = new Map();
     constructor(globalConfig = {}) {
         this.globalConfig = globalConfig;
         this.logger = new DebugLogger(globalConfig.debug || false);
@@ -182,6 +183,39 @@ export class CallableMockInstance {
         }
         return this.requestHistory[this.requestHistory.length - 1];
     }
+    // ===== Introspection =====
+    getRoutes() {
+        return this.routes.map((r) => ({
+            method: r.method,
+            path: r.path,
+            hasParams: r.params.length > 0,
+        }));
+    }
+    getState() {
+        return this.globalConfig.state || {};
+    }
+    // ===== Lifecycle Events =====
+    on(event, listener) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(listener);
+        return this;
+    }
+    off(event, listener) {
+        this.listeners.get(event)?.delete(listener);
+        return this;
+    }
+    emit(event, data) {
+        const set = this.listeners.get(event);
+        if (set) {
+            for (const listener of set) {
+                listener(data);
+            }
+        }
+    }
     // ===== Reset / Lifecycle =====
     reset() {
         this.close();
@@ -189,6 +223,7 @@ export class CallableMockInstance {
         this.staticRoutes.clear();
         this.plugins = [];
         this.requestHistory = [];
+        this.listeners.clear();
         if (this.globalConfig.state) {
             for (const key of Object.keys(this.globalConfig.state)) {
                 delete this.globalConfig.state[key];
@@ -286,12 +321,18 @@ export class CallableMockInstance {
     }
     async handle(method, path, options) {
         const requestId = crypto.randomUUID();
+        const handleStart = performance.now();
         this.logger.log("request", `[${requestId}] ${method} ${path}`, {
             headers: options?.headers,
             query: options?.query,
             bodyType: options?.body ? typeof options.body : "none",
         });
         this.logger.time(`request-${requestId}`);
+        this.emit("request:start", {
+            method,
+            path,
+            headers: options?.headers || {},
+        });
         try {
             // Apply namespace if configured
             let requestPath = path;
@@ -324,18 +365,31 @@ export class CallableMockInstance {
             const matchedRoute = this.findRoute(method, requestPath);
             if (!matchedRoute) {
                 this.logger.log("route", `[${requestId}] No route found for ${method} ${requestPath}`);
+                this.emit("request:notfound", { method, path: requestPath });
                 const error = new RouteNotFoundError(method, path);
                 const response = {
                     status: 404,
                     body: { error: error.message, code: error.code },
                     headers: {},
                 };
+                this.emit("request:end", {
+                    method,
+                    path: requestPath,
+                    status: 404,
+                    duration: performance.now() - handleStart,
+                });
                 this.logger.timeEnd(`request-${requestId}`);
                 return response;
             }
             this.logger.log("route", `[${requestId}] Matched route: ${method} ${matchedRoute.path}`);
             // Extract parameters from the matched route
             const params = this.extractParams(matchedRoute, requestPath);
+            this.emit("request:match", {
+                method,
+                path: requestPath,
+                routePath: matchedRoute.path,
+                params,
+            });
             // Generate initial response from route handler
             const context = {
                 method,
@@ -377,8 +431,8 @@ export class CallableMockInstance {
             }
             // Parse and prepare response
             const response = this.parseResponse(result, matchedRoute.config);
-            // Apply global delay if configured
-            await this.applyDelay();
+            // Apply delay (route-level overrides global)
+            await this.applyDelay(matchedRoute.config.delay);
             // Record request in history
             this.requestHistory.push({
                 method,
@@ -390,6 +444,12 @@ export class CallableMockInstance {
                 timestamp: Date.now(),
                 response: { status: response.status, body: response.body },
             });
+            this.emit("request:end", {
+                method,
+                path: requestPath,
+                status: response.status,
+                duration: performance.now() - handleStart,
+            });
             // Log successful response
             this.logger.log("response", `[${requestId}] Sending response ${response.status}`, {
                 status: response.status,
@@ -410,7 +470,7 @@ export class CallableMockInstance {
                 },
                 headers: {},
             };
-            // Apply global delay if configured (even for error responses)
+            // Apply delay even for error responses
             await this.applyDelay();
             this.logger.log("error", `[${requestId}] Returning error response 500`);
             this.logger.timeEnd(`request-${requestId}`);
@@ -422,16 +482,16 @@ export class CallableMockInstance {
      * Supports both fixed delays and random delays within a range
      * @private
      */
-    async applyDelay() {
-        if (!this.globalConfig.delay) {
+    async applyDelay(routeDelay) {
+        const effectiveDelay = routeDelay ?? this.globalConfig.delay;
+        if (!effectiveDelay) {
             return;
         }
-        const delay = Array.isArray(this.globalConfig.delay)
-            ? Math.random() *
-                (this.globalConfig.delay[1] - this.globalConfig.delay[0]) +
-                this.globalConfig.delay[0]
-            : this.globalConfig.delay;
-        await new Promise((resolve) => setTimeout(resolve, delay));
+        const ms = Array.isArray(effectiveDelay)
+            ? Math.random() * (effectiveDelay[1] - effectiveDelay[0]) +
+                effectiveDelay[0]
+            : effectiveDelay;
+        await new Promise((resolve) => setTimeout(resolve, ms));
     }
     /**
      * Parse and normalize response result into Response object

package/dist/index.d.ts

@@ -24,5 +24,5 @@
 export declare function schmock(config?: Schmock.GlobalConfig): Schmock.CallableMockInstance;
 export { HTTP_METHODS, isHttpMethod, isStatusTuple, ROUTE_NOT_FOUND_CODE, toHttpMethod, } from "./constants.js";
 export { PluginError, ResourceLimitError, ResponseGenerationError, RouteDefinitionError, RouteNotFoundError, RouteParseError, SchemaGenerationError, SchemaValidationError, SchmockError, } from "./errors.js";
-export type { CallableMockInstance, Generator, GeneratorFunction, GlobalConfig, HttpMethod, Plugin, PluginContext, PluginResult, RequestContext, RequestOptions, RequestRecord, Response, ResponseBody, ResponseResult, RouteConfig, RouteKey, ServerInfo, StaticData, } from "./types.js";
+export type { CallableMockInstance, Generator, GeneratorFunction, GlobalConfig, HttpMethod, Plugin, PluginContext, PluginResult, RequestContext, RequestOptions, RequestRecord, Response, ResponseBody, ResponseResult, RouteConfig, RouteInfo, RouteKey, ServerInfo, StaticData, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CACrB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,GAC5B,OAAO,CAAC,oBAAoB,CAmC9B;AAGD,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,YAAY,GACb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,oBAAoB,EACpB,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,MAAM,EACN,aAAa,EACb,YAAY,EACZ,cAAc,EACd,cAAc,EACd,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,WAAW,EACX,QAAQ,EACR,UAAU,EACV,UAAU,GACX,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CACrB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,GAC5B,OAAO,CAAC,oBAAoB,CA6C9B;AAGD,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,YAAY,GACb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,oBAAoB,EACpB,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,MAAM,EACN,aAAa,EACb,YAAY,EACZ,cAAc,EACd,cAAc,EACd,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,WAAW,EACX,SAAS,EACT,QAAQ,EACR,UAAU,EACV,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -42,6 +42,16 @@ export function schmock(config) {
         reset: instance.reset.bind(instance),
         resetHistory: instance.resetHistory.bind(instance),
         resetState: instance.resetState.bind(instance),
+        on: ((event, listener) => {
+            instance.on(event, listener);
+            return callableInstance;
+        }),
+        off: ((event, listener) => {
+            instance.off(event, listener);
+            return callableInstance;
+        }),
+        getRoutes: instance.getRoutes.bind(instance),
+        getState: instance.getState.bind(instance),
         listen: instance.listen.bind(instance),
         close: instance.close.bind(instance),
     });

package/dist/types.d.ts

@@ -16,4 +16,5 @@ export type PluginResult = Schmock.PluginResult;
 export type StaticData = Schmock.StaticData;
 export type RequestRecord = Schmock.RequestRecord;
 export type ServerInfo = Schmock.ServerInfo;
+export type RouteInfo = Schmock.RouteInfo;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;AAC5C,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;AACxC,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;AACxC,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;AAC9C,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;AAC1C,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;AAC1D,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;AAChE,MAAM,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;AACpC,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;AAC5C,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;AAClD,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;AAC5C,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;AACxC,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;AACxC,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;AAC9C,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;AAC1C,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;AAC1D,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;AAChE,MAAM,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;AACpC,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;AAC5C,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;AAClD,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;AAC5C,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC"}

package/dist/types.js

@@ -1,2 +1,2 @@
-/// <reference path="../../../types/schmock.d.ts" />
+/// <reference path="../schmock.d.ts" />
 export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@schmock/core",
   "description": "Core functionality for Schmock",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/builder.ts

@@ -88,6 +88,7 @@ export class CallableMockInstance {
   private callableRef: Schmock.CallableMockInstance | undefined;
   private server: Server | undefined;
   private serverInfo: Schmock.ServerInfo | undefined;
+  private listeners = new Map<string, Set<(data: unknown) => void>>();
 
   constructor(private globalConfig: Schmock.GlobalConfig = {}) {
     this.logger = new DebugLogger(globalConfig.debug || false);
@@ -255,6 +256,46 @@ export class CallableMockInstance {
     return this.requestHistory[this.requestHistory.length - 1];
   }
 
+  // ===== Introspection =====
+
+  getRoutes(): Schmock.RouteInfo[] {
+    return this.routes.map((r) => ({
+      method: r.method,
+      path: r.path,
+      hasParams: r.params.length > 0,
+    }));
+  }
+
+  getState(): Record<string, unknown> {
+    return this.globalConfig.state || {};
+  }
+
+  // ===== Lifecycle Events =====
+
+  on(event: string, listener: (data: unknown) => void): this {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(listener);
+    return this;
+  }
+
+  off(event: string, listener: (data: unknown) => void): this {
+    this.listeners.get(event)?.delete(listener);
+    return this;
+  }
+
+  private emit(event: string, data: unknown): void {
+    const set = this.listeners.get(event);
+    if (set) {
+      for (const listener of set) {
+        listener(data);
+      }
+    }
+  }
+
   // ===== Reset / Lifecycle =====
 
   reset(): void {
@@ -263,6 +304,7 @@ export class CallableMockInstance {
     this.staticRoutes.clear();
     this.plugins = [];
     this.requestHistory = [];
+    this.listeners.clear();
     if (this.globalConfig.state) {
       for (const key of Object.keys(this.globalConfig.state)) {
         delete this.globalConfig.state[key];
@@ -386,6 +428,7 @@ export class CallableMockInstance {
     options?: Schmock.RequestOptions,
   ): Promise<Schmock.Response> {
     const requestId = crypto.randomUUID();
+    const handleStart = performance.now();
     this.logger.log("request", `[${requestId}] ${method} ${path}`, {
       headers: options?.headers,
       query: options?.query,
@@ -393,6 +436,12 @@ export class CallableMockInstance {
     });
     this.logger.time(`request-${requestId}`);
 
+    this.emit("request:start", {
+      method,
+      path,
+      headers: options?.headers || {},
+    });
+
     try {
       // Apply namespace if configured
       let requestPath = path;
@@ -440,12 +489,19 @@ export class CallableMockInstance {
           "route",
           `[${requestId}] No route found for ${method} ${requestPath}`,
         );
+        this.emit("request:notfound", { method, path: requestPath });
         const error = new RouteNotFoundError(method, path);
         const response = {
           status: 404,
           body: { error: error.message, code: error.code },
           headers: {},
         };
+        this.emit("request:end", {
+          method,
+          path: requestPath,
+          status: 404,
+          duration: performance.now() - handleStart,
+        });
         this.logger.timeEnd(`request-${requestId}`);
         return response;
       }
@@ -458,6 +514,13 @@ export class CallableMockInstance {
       // Extract parameters from the matched route
       const params = this.extractParams(matchedRoute, requestPath);
 
+      this.emit("request:match", {
+        method,
+        path: requestPath,
+        routePath: matchedRoute.path,
+        params,
+      });
+
       // Generate initial response from route handler
       const context: Schmock.RequestContext = {
         method,
@@ -510,8 +573,8 @@ export class CallableMockInstance {
       // Parse and prepare response
       const response = this.parseResponse(result, matchedRoute.config);
 
-      // Apply global delay if configured
-      await this.applyDelay();
+      // Apply delay (route-level overrides global)
+      await this.applyDelay(matchedRoute.config.delay);
 
       // Record request in history
       this.requestHistory.push({
@@ -525,6 +588,13 @@ export class CallableMockInstance {
         response: { status: response.status, body: response.body },
       });
 
+      this.emit("request:end", {
+        method,
+        path: requestPath,
+        status: response.status,
+        duration: performance.now() - handleStart,
+      });
+
       // Log successful response
       this.logger.log(
         "response",
@@ -555,7 +625,7 @@ export class CallableMockInstance {
         headers: {},
       };
 
-      // Apply global delay if configured (even for error responses)
+      // Apply delay even for error responses
       await this.applyDelay();
 
       this.logger.log("error", `[${requestId}] Returning error response 500`);
@@ -569,18 +639,20 @@ export class CallableMockInstance {
    * Supports both fixed delays and random delays within a range
    * @private
    */
-  private async applyDelay(): Promise<void> {
-    if (!this.globalConfig.delay) {
+  private async applyDelay(
+    routeDelay?: number | [number, number],
+  ): Promise<void> {
+    const effectiveDelay = routeDelay ?? this.globalConfig.delay;
+    if (!effectiveDelay) {
       return;
     }
 
-    const delay = Array.isArray(this.globalConfig.delay)
-      ? Math.random() *
-          (this.globalConfig.delay[1] - this.globalConfig.delay[0]) +
-        this.globalConfig.delay[0]
-      : this.globalConfig.delay;
+    const ms = Array.isArray(effectiveDelay)
+      ? Math.random() * (effectiveDelay[1] - effectiveDelay[0]) +
+        effectiveDelay[0]
+      : effectiveDelay;
 
-    await new Promise((resolve) => setTimeout(resolve, delay));
+    await new Promise((resolve) => setTimeout(resolve, ms));
   }
 
   /**

package/src/index.ts

@@ -52,6 +52,16 @@ export function schmock(
       reset: instance.reset.bind(instance),
       resetHistory: instance.resetHistory.bind(instance),
       resetState: instance.resetState.bind(instance),
+      on: ((event: string, listener: (data: unknown) => void) => {
+        instance.on(event, listener);
+        return callableInstance;
+      }) as Schmock.CallableMockInstance["on"],
+      off: ((event: string, listener: (data: unknown) => void) => {
+        instance.off(event, listener);
+        return callableInstance;
+      }) as Schmock.CallableMockInstance["off"],
+      getRoutes: instance.getRoutes.bind(instance),
+      getState: instance.getState.bind(instance),
       listen: instance.listen.bind(instance),
       close: instance.close.bind(instance),
     },
@@ -99,6 +109,7 @@ export type {
   ResponseBody,
   ResponseResult,
   RouteConfig,
+  RouteInfo,
   RouteKey,
   ServerInfo,
   StaticData,

package/src/steps/lifecycle-events.steps.ts

@@ -0,0 +1,142 @@
+import { describeFeature, loadFeature } from "@amiceli/vitest-cucumber";
+import { expect } from "vitest";
+import { schmock } from "../index";
+
+const feature = await loadFeature("../../features/lifecycle-events.feature");
+
+describeFeature(feature, ({ Scenario }) => {
+  let mock: Schmock.CallableMockInstance;
+  let events: Array<{ type: string; data: unknown }>;
+  let removedFired: boolean;
+
+  function collectEvent(type: string) {
+    return (data: unknown) => {
+      events.push({ type, data });
+    };
+  }
+
+  Scenario("Events fire at correct times", ({ Given, And, When, Then }) => {
+    Given('a mock with a route "GET /items"', () => {
+      mock = schmock({ state: {} });
+      mock("GET /items", [{ id: 1 }], {});
+    });
+
+    And("I register listeners for all events", () => {
+      events = [];
+      mock.on("request:start", collectEvent("request:start"));
+      mock.on("request:match", collectEvent("request:match"));
+      mock.on("request:notfound", collectEvent("request:notfound"));
+      mock.on("request:end", collectEvent("request:end"));
+    });
+
+    When('I request "GET /items"', async () => {
+      await mock.handle("GET", "/items");
+    });
+
+    Then('the "request:start" event fired', () => {
+      expect(events.some((e) => e.type === "request:start")).toBe(true);
+    });
+
+    And('the "request:match" event fired with routePath "/items"', () => {
+      const match = events.find((e) => e.type === "request:match");
+      expect(match).toBeDefined();
+      const data = match?.data as Record<string, unknown>;
+      expect(data.routePath).toBe("/items");
+    });
+
+    And('the "request:end" event fired with status 200', () => {
+      const end = events.find((e) => e.type === "request:end");
+      expect(end).toBeDefined();
+      const data = end?.data as Record<string, unknown>;
+      expect(data.status).toBe(200);
+    });
+  });
+
+  Scenario("Not found event fires for unmatched routes", ({ Given, And, When, Then }) => {
+    Given('a mock with a route "GET /items"', () => {
+      mock = schmock({ state: {} });
+      mock("GET /items", [{ id: 1 }], {});
+    });
+
+    And("I register listeners for all events", () => {
+      events = [];
+      mock.on("request:start", collectEvent("request:start"));
+      mock.on("request:match", collectEvent("request:match"));
+      mock.on("request:notfound", collectEvent("request:notfound"));
+      mock.on("request:end", collectEvent("request:end"));
+    });
+
+    When('I request "GET /missing"', async () => {
+      await mock.handle("GET", "/missing");
+    });
+
+    Then('the "request:start" event fired', () => {
+      expect(events.some((e) => e.type === "request:start")).toBe(true);
+    });
+
+    And('the "request:notfound" event fired', () => {
+      expect(events.some((e) => e.type === "request:notfound")).toBe(true);
+    });
+
+    And('the "request:end" event fired with status 404', () => {
+      const end = events.find((e) => e.type === "request:end");
+      expect(end).toBeDefined();
+      const data = end?.data as Record<string, unknown>;
+      expect(data.status).toBe(404);
+    });
+  });
+
+  Scenario("Off removes listener", ({ Given, And, When, Then }) => {
+    Given('a mock with a route "GET /items"', () => {
+      mock = schmock({ state: {} });
+      mock("GET /items", [{ id: 1 }], {});
+    });
+
+    And("I register and remove a listener", () => {
+      removedFired = false;
+      const listener = () => {
+        removedFired = true;
+      };
+      mock.on("request:start", listener);
+      mock.off("request:start", listener);
+    });
+
+    When('I request "GET /items"', async () => {
+      await mock.handle("GET", "/items");
+    });
+
+    Then("the removed listener did not fire", () => {
+      expect(removedFired).toBe(false);
+    });
+  });
+
+  Scenario("Reset clears all listeners", ({ Given, And, When, Then }) => {
+    Given('a mock with a route "GET /items"', () => {
+      mock = schmock({ state: {} });
+      mock("GET /items", [{ id: 1 }], {});
+    });
+
+    And("I register listeners for all events", () => {
+      events = [];
+      mock.on("request:start", collectEvent("request:start"));
+      mock.on("request:end", collectEvent("request:end"));
+    });
+
+    When("I reset the mock", () => {
+      mock.reset();
+      events = [];
+    });
+
+    And('I add a route "GET /items" again', () => {
+      mock("GET /items", [{ id: 1 }], {});
+    });
+
+    And('I request "GET /items" after reset', async () => {
+      await mock.handle("GET", "/items");
+    });
+
+    Then("no events were collected after reset", () => {
+      expect(events).toHaveLength(0);
+    });
+  });
+});

package/src/steps/response-delay.steps.ts

@@ -0,0 +1,85 @@
+import { describeFeature, loadFeature } from "@amiceli/vitest-cucumber";
+import { expect } from "vitest";
+import { schmock } from "../index";
+
+const feature = await loadFeature("../../features/response-delay.feature");
+
+describeFeature(feature, ({ Scenario }) => {
+  let mock: Schmock.CallableMockInstance;
+  let elapsed: number;
+  let elapsed2: number;
+
+  Scenario("Route delay overrides global delay", ({ Given, And, When, Then }) => {
+    Given("a mock with global delay of 200ms", () => {
+      mock = schmock({ delay: 200, state: {} });
+    });
+
+    And('a route "GET /fast" with delay of 10ms', () => {
+      mock("GET /fast", { ok: true }, { delay: 10 });
+    });
+
+    And('a route "GET /default" with no delay override', () => {
+      mock("GET /default", { ok: true }, {});
+    });
+
+    When('I request "GET /fast"', async () => {
+      const start = performance.now();
+      await mock.handle("GET", "/fast");
+      elapsed = performance.now() - start;
+    });
+
+    Then("the response took less than 100ms", () => {
+      expect(elapsed).toBeLessThan(100);
+    });
+
+    When('I request "GET /default" with timing', async () => {
+      const start = performance.now();
+      await mock.handle("GET", "/default");
+      elapsed2 = performance.now() - start;
+    });
+
+    Then("that response took at least 150ms", () => {
+      expect(elapsed2).toBeGreaterThanOrEqual(150);
+    });
+  });
+
+  Scenario("Route delay supports random range", ({ Given, And, When, Then }) => {
+    Given("a mock with no global delay", () => {
+      mock = schmock({ state: {} });
+    });
+
+    And('a route "GET /random" with delay range 10 to 30', () => {
+      mock("GET /random", { ok: true }, { delay: [10, 30] });
+    });
+
+    When('I request "GET /random"', async () => {
+      const start = performance.now();
+      await mock.handle("GET", "/random");
+      elapsed = performance.now() - start;
+    });
+
+    Then("the response took at least 10ms", () => {
+      expect(elapsed).toBeGreaterThanOrEqual(8); // small tolerance
+    });
+  });
+
+  Scenario("No route delay inherits global delay", ({ Given, And, When, Then }) => {
+    Given("a mock with global delay of 50ms", () => {
+      mock = schmock({ delay: 50, state: {} });
+    });
+
+    And('a route "GET /items" with no delay override', () => {
+      mock("GET /items", { ok: true }, {});
+    });
+
+    When('I request "GET /items" with timing', async () => {
+      const start = performance.now();
+      await mock.handle("GET", "/items");
+      elapsed = performance.now() - start;
+    });
+
+    Then("that response took at least 40ms", () => {
+      expect(elapsed).toBeGreaterThanOrEqual(40);
+    });
+  });
+});

package/src/types.ts

@@ -1,6 +1,6 @@
-/// <reference path="../../../types/schmock.d.ts" />
+/// <reference path="../schmock.d.ts" />
 
-// Re-export types for internal use
+// Re-export ambient types for consumers
 export type HttpMethod = Schmock.HttpMethod;
 export type RouteKey = Schmock.RouteKey;
 export type ResponseBody = Schmock.ResponseBody;
@@ -19,3 +19,4 @@ export type PluginResult = Schmock.PluginResult;
 export type StaticData = Schmock.StaticData;
 export type RequestRecord = Schmock.RequestRecord;
 export type ServerInfo = Schmock.ServerInfo;
+export type RouteInfo = Schmock.RouteInfo;

package/src/builder.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["builder.ts"],"names":[],"mappings":"AAAA,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;AAW7B,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EAEb,YAAY,EAGZ,MAAM,EACP,MAAM,SAAS,CAAC;AAajB;;;;GAIG;AACH,qBAAa,cAAc,CAAC,MAAM,GAAG,OAAO,CAAE,YAAW,OAAO,CAAC,MAAM,CAAC;IACtE,OAAO,CAAC,OAAO,CAEb;IAEF,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAK/C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAK/C,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAShC,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKpC,KAAK,IAAI,YAAY,CAAC,MAAM,CAAC;IAQ7B;;;OAGG;IACH,OAAO,CAAC,aAAa;CA0BtB"}

package/src/errors.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;aAGnB,IAAI,EAAE,MAAM;aACZ,OAAO,CAAC,EAAE,OAAO;gBAFjC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,OAAO,YAAA;CAMpC;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;gBACtC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAQzC;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,YAAY;gBACnC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAQ7C;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,YAAY;gBAC3C,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;CAQxC;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,YAAY;gBAC/B,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;CAQ7C;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAQ7C;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAQnE;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,OAAO;CAQ1D;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;gBACtC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAQ7D"}

package/src/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,IAAI,OAAO,CAEjC;AAGD,YAAY,EACV,OAAO,EACP,aAAa,EACb,UAAU,EACV,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,QAAQ,EACR,MAAM,GACP,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,WAAW,EACX,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,UAAU,CAAC"}

package/src/parser.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["parser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAuC3D"}

package/src/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;AAC5C,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;AACxC,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;AAClD,MAAM,MAAM,eAAe,CAAC,CAAC,GAAG,OAAO,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;AACtE,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;AACxE,MAAM,MAAM,eAAe,CAAC,CAAC,GAAG,OAAO,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;AACtE,MAAM,MAAM,MAAM,CAAC,CAAC,GAAG,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACpD,MAAM,MAAM,OAAO,CAAC,CAAC,GAAG,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AACtD,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC"}