@congruent-stack/congruent-api 0.9.0-rc.0 → 0.10.0

package/dist/index.cjs

@@ -19,6 +19,11 @@ class HttpMethodEndpoint {
     }
     return this._cachedGenericPath;
   }
+  createPath(pathParams) {
+    return `/${this.pathSegments.map(
+      (segment) => segment.startsWith(":") ? pathParams[segment.slice(1)] ?? "?" : segment
+    ).join("/")}`;
+  }
   _method = null;
   get method() {
     return this._method;
@@ -112,6 +117,7 @@ var HttpStatusCode = /* @__PURE__ */ ((HttpStatusCode2) => {
   HttpStatusCode2[HttpStatusCode2["Forbidden_403"] = 403] = "Forbidden_403";
   HttpStatusCode2[HttpStatusCode2["NotFound_404"] = 404] = "NotFound_404";
   HttpStatusCode2[HttpStatusCode2["Conflict_409"] = 409] = "Conflict_409";
+  HttpStatusCode2[HttpStatusCode2["UnprocessableEntity_422"] = 422] = "UnprocessableEntity_422";
   HttpStatusCode2[HttpStatusCode2["InternalServerError_500"] = 500] = "InternalServerError_500";
   HttpStatusCode2[HttpStatusCode2["NotImplemented_501"] = 501] = "NotImplemented_501";
   HttpStatusCode2[HttpStatusCode2["BadGateway_502"] = 502] = "BadGateway_502";
@@ -140,6 +146,9 @@ class MethodEndpointHandlerRegistryEntry {
     this._methodEndpoint = methodEndpoint;
     this._dicontainer = dicontainer;
   }
+  get genericPath() {
+    return this._methodEndpoint.genericPath;
+  }
   _handler = null;
   get handler() {
     return this._handler;
@@ -149,6 +158,7 @@ class MethodEndpointHandlerRegistryEntry {
     if (this._onHandlerRegisteredCallback) {
       this._onHandlerRegisteredCallback(this);
     }
+    return this;
   }
   _onHandlerRegisteredCallback = null;
   _onHandlerRegistered(callback) {
@@ -166,7 +176,55 @@ class MethodEndpointHandlerRegistryEntry {
     this._injection = injection;
     return this;
   }
+  _decoratorFactories = [];
+  get decoratorFactories() {
+    return this._decoratorFactories;
+  }
+  /**
+   * 
+   * @param decoratorFactory must be a function that takes exactly the DI scope type and returns an instance of a class that implements IEndpointHandlerDecorator
+   * @returns this
+   * 
+   * Initially, the method was defined as:
+   * ```ts
+   * decorate<
+   *   TDecoratorSchemas extends IDecoratorHandlerSchemas, 
+   *   TDecorator extends IEndpointHandlerDecorator<TDecoratorSchemas>
+   * > (
+   *   decoratorFactory: IEndpointHandlerDecoratorFactory<TDecoratorSchemas, TDIContainer, TDecorator>
+   * ): this {
+   *   this._decoratorFactories.push(decoratorFactory);
+   *   return this;
+   * }
+   * ```
+   * 
+   * and the type IEndpointHandlerDecoratorFactory was defined as:
+   * ```ts
+   * type IEndpointHandlerDecoratorFactory<
+   *   TDecoratorSchemas extends IDecoratorHandlerSchemas, 
+   *   TDIContainer extends DIContainer, 
+   *   TDecorator extends IEndpointHandlerDecorator<TDecoratorSchemas>
+   * > = (diScope: ReturnType<TDIContainer['createScope']>) => TDecorator;
+   * ```
+   * 
+   * However, TypeScript was incorrectly inferring the types when using the 'decorate' method. 
+   * The end developer would have had to explicitly provide the generic types, which is not ideal.
+   * 
+   * With the current definition, TypeScript can infer the types from the decoratorFactory parameter, 
+   * making it easier to use.
+   */
+  decorate(decoratorFactory, decoratingArgs) {
+    this._decoratorFactories.push((scope) => decoratorFactory(scope, decoratingArgs));
+    return this;
+  }
+  decorateWith(decoratorStaticMethodFactory, decoratingArgs) {
+    this._decoratorFactories.push((scope) => decoratorStaticMethodFactory.create(scope, decoratingArgs));
+    return this;
+  }
   async trigger(diScope, requestObject) {
+    return this.triggerNoStaticTypeCheck(diScope, requestObject, { originalRequest: requestObject });
+  }
+  async exec(injected, requestObject) {
     if (!this._handler) {
       throw new Error("Handler not set for this endpoint");
     }
@@ -186,9 +244,7 @@ class MethodEndpointHandlerRegistryEntry {
       badRequestResponse = body;
       return badRequestResponse;
     }
-    const path = `/${this._methodEndpoint.pathSegments.map(
-      (segment) => segment.startsWith(":") ? requestObject.pathParams[segment.slice(1)] ?? "?" : segment
-    ).join("/")}`;
+    const path = this._methodEndpoint.createPath(requestObject.pathParams);
     return await this._handler({
       method: this._methodEndpoint.method,
       path,
@@ -197,9 +253,41 @@ class MethodEndpointHandlerRegistryEntry {
       headers,
       pathParams: requestObject.pathParams,
       query,
-      body,
-      injected: this._injection(diScope)
-    });
+      body
+    }, injected);
+  }
+  async triggerNoStaticTypeCheck(diScope, requestObject, context) {
+    if (!this._handler) {
+      throw new Error("Handler not set for this endpoint");
+    }
+    let badRequestResponse = null;
+    const headers = parseRequestDefinitionField(this._methodEndpoint.definition, "headers", requestObject);
+    if (isHttpResponseObject(headers)) {
+      badRequestResponse = headers;
+      return badRequestResponse;
+    }
+    const query = parseRequestDefinitionField(this._methodEndpoint.definition, "query", requestObject);
+    if (isHttpResponseObject(query)) {
+      badRequestResponse = query;
+      return badRequestResponse;
+    }
+    const body = parseRequestDefinitionField(this._methodEndpoint.definition, "body", requestObject);
+    if (isHttpResponseObject(body)) {
+      badRequestResponse = body;
+      return badRequestResponse;
+    }
+    const path = this._methodEndpoint.createPath(requestObject.pathParams);
+    Object.assign(context, this._injection(diScope));
+    return await this._handler({
+      method: this._methodEndpoint.method,
+      path,
+      genericPath: this._methodEndpoint.genericPath,
+      pathSegments: this._methodEndpoint.pathSegments,
+      headers,
+      pathParams: requestObject.pathParams,
+      query,
+      body
+    }, context);
   }
 }
 function parseRequestDefinitionField(definition, key, requestObject) {
@@ -255,7 +343,26 @@ class MiddlewareHandlersRegistryEntryInternal {
   get genericPath() {
     return this._middlewareGenericPath;
   }
-  _splitMiddlewarePath() {
+  _middlewarePathSegments;
+  get pathSegments() {
+    return this._middlewarePathSegments;
+  }
+  _middlewareMethod;
+  get method() {
+    return this._middlewareMethod;
+  }
+  _middlewareSchemas;
+  get middlewareSchemas() {
+    return this._middlewareSchemas;
+  }
+  _handler;
+  constructor(diContainer, middlewarePath, middlewareSchemas, decoratorFactories, injection, handler) {
+    this._dicontainer = diContainer;
+    this._middlewareGenericPath = middlewarePath;
+    this._middlewareSchemas = middlewareSchemas;
+    this._decoratorFactories.push(...decoratorFactories);
+    this._injection = injection;
+    this._handler = handler;
     const splitResult = this._middlewareGenericPath.split(" ");
     let method = "";
     let pathSegments = [];
@@ -266,58 +373,57 @@ class MiddlewareHandlersRegistryEntryInternal {
       }
       pathSegments = splitResult[1].split("/").map((segment) => segment.trim()).filter((segment) => segment !== "");
     }
-    return {
-      method,
-      pathSegments
-    };
+    this._middlewareMethod = method;
+    this._middlewarePathSegments = pathSegments;
   }
-  _inputSchemas;
-  _handler;
-  constructor(diContainer, middlewarePath, inputSchemas, injection, handler) {
-    this._dicontainer = diContainer;
-    this._middlewareGenericPath = middlewarePath;
-    this._inputSchemas = inputSchemas;
-    this._injection = injection;
-    this._handler = handler;
+  _decoratorFactories = [];
+  get decoratorFactories() {
+    return this._decoratorFactories;
   }
   _injection = (_dicontainer) => ({});
-  async trigger(diScope, requestObject, next) {
+  async trigger(diScope, requestObject, context) {
+    return this.triggerNoStaticTypeCheck(diScope, requestObject, context);
+  }
+  async triggerNoStaticTypeCheck(diScope, requestObject, context) {
     let badRequestResponse = null;
-    const headers = middlewareParseRequestDefinitionField(this._inputSchemas, "headers", requestObject);
+    const headers = middlewareParseRequestDefinitionField(this._middlewareSchemas, "headers", requestObject);
     if (isHttpResponseObject(headers)) {
       badRequestResponse = headers;
       return badRequestResponse;
     }
-    const query = middlewareParseRequestDefinitionField(this._inputSchemas, "query", requestObject);
+    const query = middlewareParseRequestDefinitionField(this._middlewareSchemas, "query", requestObject);
     if (isHttpResponseObject(query)) {
       badRequestResponse = query;
       return badRequestResponse;
     }
-    const body = middlewareParseRequestDefinitionField(this._inputSchemas, "body", requestObject);
+    const body = middlewareParseRequestDefinitionField(this._middlewareSchemas, "body", requestObject);
     if (isHttpResponseObject(body)) {
       badRequestResponse = body;
       return badRequestResponse;
     }
-    const { method, pathSegments } = this._splitMiddlewarePath();
-    const path = `/${pathSegments.map(
-      (segment) => segment.startsWith(":") ? requestObject.pathParams[segment.slice(1)] ?? "?" : segment
-    ).join("/")}`;
+    const path = this.createPath(requestObject.pathParams);
+    Object.assign(context, this._injection(diScope));
     return await this._handler(
       {
-        method,
-        // TODO: might be empty, as middleware can be registered with path only, without method, possible fix: take it from express.request.method
+        method: this.method,
+        // TODO: might be empty, as middleware can be registered with path only, without method
         path,
         genericPath: this.genericPath,
-        pathSegments,
+        pathSegments: this.pathSegments,
         headers,
         pathParams: requestObject.pathParams,
         query,
-        body,
-        injected: this._injection(diScope)
+        body
       },
-      next
+      context
     );
   }
+  createPath(pathParams) {
+    const path = `/${this.pathSegments.map(
+      (segment) => segment.startsWith(":") ? pathParams[segment.slice(1)] ?? "?" : segment
+    ).join("/")}`;
+    return path;
+  }
 }
 class MiddlewareHandlersRegistryEntry {
   _registry;
@@ -334,16 +440,62 @@ class MiddlewareHandlersRegistryEntry {
     this._injection = injection;
     return this;
   }
-  register(inputSchemas, handler) {
+  register(middlewareSchemas, handler) {
     const internalEntry = new MiddlewareHandlersRegistryEntryInternal(
       this._registry.dicontainer,
       this._path,
-      inputSchemas,
+      middlewareSchemas,
+      this._decoratorFactories,
       this._injection,
       handler
     );
     this._registry.register(internalEntry);
   }
+  _decoratorFactories = [];
+  get decoratorFactories() {
+    return this._decoratorFactories;
+  }
+  /**
+   * 
+   * @param decoratorFactory must be a function that takes exactly the DI scope type and returns an instance of a class that implements IEndpointHandlerDecorator
+   * @returns this
+   * 
+   * Initially, the method was defined as:
+   * ```ts
+   * decorate<
+   *   TDecoratorSchemas extends IDecoratorHandlerSchemas, 
+   *   TDecorator extends IEndpointHandlerDecorator<TDecoratorSchemas>
+   * > (
+   *   decoratorFactory: IEndpointHandlerDecoratorFactory<TDecoratorSchemas, TDIContainer, TDecorator>
+   * ): this {
+   *   this._decoratorFactories.push(decoratorFactory);
+   *   return this;
+   * }
+   * ```
+   * 
+   * and the type IEndpointHandlerDecoratorFactory was defined as:
+   * ```ts
+   * type IEndpointHandlerDecoratorFactory<
+   *   TDecoratorSchemas extends IDecoratorHandlerSchemas, 
+   *   TDIContainer extends DIContainer, 
+   *   TDecorator extends IEndpointHandlerDecorator<TDecoratorSchemas>
+   * > = (diScope: ReturnType<TDIContainer['createScope']>) => TDecorator;
+   * ```
+   * 
+   * However, TypeScript was incorrectly inferring the types when using the 'decorate' method. 
+   * The end developer would have had to explicitly provide the generic types, which is not ideal.
+   * 
+   * With the current definition, TypeScript can infer the types from the decoratorFactory parameter, 
+   * making it easier to use.
+   */
+  decorate(decoratorFactory) {
+    this._decoratorFactories.push(decoratorFactory);
+    return this;
+  }
+  decorateWith(decoratorStaticMethodFactory) {
+    this._decoratorFactories.push(decoratorStaticMethodFactory.create);
+    return this;
+  }
 }
 class MiddlewareHandlersRegistry {
   dicontainer;
@@ -366,12 +518,12 @@ class MiddlewareHandlersRegistry {
     this._onHandlerRegisteredCallback = callback;
   }
 }
-function middlewareParseRequestDefinitionField(inputSchemas, key, requestObject) {
-  if (inputSchemas[key]) {
+function middlewareParseRequestDefinitionField(middlewareSchemas, key, requestObject) {
+  if (middlewareSchemas[key]) {
     if (!(key in requestObject) || requestObject[key] === null || requestObject[key] === void 0) {
-      const result2 = inputSchemas[key].safeParse(requestObject[key]);
+      const result2 = middlewareSchemas[key].safeParse(requestObject[key]);
       if (!result2.success) {
-        switch (inputSchemas[key].type) {
+        switch (middlewareSchemas[key].type) {
           case "optional":
             if (requestObject[key] === null) {
               return void 0;
@@ -390,7 +542,7 @@ function middlewareParseRequestDefinitionField(inputSchemas, key, requestObject)
       }
       return result2.data;
     }
-    const result = inputSchemas[key].safeParse(requestObject[key]);
+    const result = middlewareSchemas[key].safeParse(requestObject[key]);
     if (!result.success) {
       return {
         code: HttpStatusCode.BadRequest_400,
@@ -521,6 +673,41 @@ function registerEntryHandler(endpointEntry, handler) {
   endpointEntry.register(handler);
 }
 
+async function execHandlerChain(diScope, allHandlerEntries, input) {
+  const queue = [...allHandlerEntries];
+  let response = void 0;
+  const next = async () => {
+    if (response) {
+      return;
+    }
+    const current = queue.shift();
+    if (!current) {
+      return;
+    }
+    if (!input.genericPath.startsWith(current.genericPath)) {
+      await next();
+      return;
+    }
+    const currResponse = await current.triggerNoStaticTypeCheck(
+      diScope,
+      input,
+      {
+        next
+      }
+    );
+    if (response) {
+      return;
+    }
+    if (currResponse) {
+      response = currResponse;
+      return;
+    }
+    await next();
+  };
+  await next();
+  return response;
+}
+
 function partialPathString(_apiReg, path) {
   return path;
 }
@@ -714,66 +901,175 @@ class DIContainerTestClone extends DIContainerBase {
   }
 }
 
-function execMiddleware(diScope, list, input) {
-  const queue = [...list];
-  const next = async () => {
-    const current = queue.shift();
-    if (!current) {
-      return;
+async function triggerEndpointDecoratorNoStaticTypeCheck(endpoint, decorator, requestObject, context) {
+  let badRequestResponse = null;
+  const headers = decoratorParseRequestDefinitionField(endpoint.definition, "headers", requestObject);
+  if (isHttpResponseObject(headers)) {
+    badRequestResponse = headers;
+    return badRequestResponse;
+  }
+  const query = decoratorParseRequestDefinitionField(endpoint.definition, "query", requestObject);
+  if (isHttpResponseObject(query)) {
+    badRequestResponse = query;
+    return badRequestResponse;
+  }
+  const body = decoratorParseRequestDefinitionField(endpoint.definition, "body", requestObject);
+  if (isHttpResponseObject(body)) {
+    badRequestResponse = body;
+    return badRequestResponse;
+  }
+  const path = endpoint.createPath(requestObject.pathParams);
+  return decorator.handle({
+    ...requestObject,
+    method: endpoint.method,
+    genericPath: endpoint.genericPath,
+    path,
+    pathSegments: endpoint.pathSegments
+  }, context);
+}
+async function triggerMiddlewareDecoratorNoStaticTypeCheck(middlewareEntry, decorator, requestObject, context) {
+  let badRequestResponse = null;
+  const headers = decoratorParseRequestDefinitionField(middlewareEntry.middlewareSchemas, "headers", requestObject);
+  if (isHttpResponseObject(headers)) {
+    badRequestResponse = headers;
+    return badRequestResponse;
+  }
+  const query = decoratorParseRequestDefinitionField(middlewareEntry.middlewareSchemas, "query", requestObject);
+  if (isHttpResponseObject(query)) {
+    badRequestResponse = query;
+    return badRequestResponse;
+  }
+  const body = decoratorParseRequestDefinitionField(middlewareEntry.middlewareSchemas, "body", requestObject);
+  if (isHttpResponseObject(body)) {
+    badRequestResponse = body;
+    return badRequestResponse;
+  }
+  const path = middlewareEntry.createPath(requestObject.pathParams);
+  return decorator.handle({
+    ...requestObject,
+    method: middlewareEntry.method,
+    // TODO: might be empty, as middleware can be registered with path only, without method
+    genericPath: middlewareEntry.genericPath,
+    path,
+    pathSegments: middlewareEntry.pathSegments
+  }, context);
+}
+function decoratorParseRequestDefinitionField(decoratorSchemas, key, requestObject) {
+  if (decoratorSchemas[key]) {
+    if (!(key in requestObject) || requestObject[key] === null || requestObject[key] === void 0) {
+      const result2 = decoratorSchemas[key].safeParse(requestObject[key]);
+      if (!result2.success) {
+        switch (decoratorSchemas[key].type) {
+          case "optional":
+            if (requestObject[key] === null) {
+              return void 0;
+            }
+            break;
+          case "nullable":
+            if (requestObject[key] === void 0) {
+              return null;
+            }
+            break;
+        }
+        return {
+          code: HttpStatusCode.BadRequest_400,
+          body: `'${key}' is required for this endpoint` + (key === "body" ? ", { 'Content-Type': 'application/json' } header might be missing" : "")
+        };
+      }
+      return result2.data;
     }
-    const result = await current.trigger(
-      diScope,
-      {
-        headers: input.headers,
-        pathParams: input.pathParams,
-        body: input.body,
-        query: input.query
-      },
-      next
-    );
-    if (result) {
-      return result;
+    const result = decoratorSchemas[key].safeParse(requestObject[key]);
+    if (!result.success) {
+      return {
+        code: HttpStatusCode.BadRequest_400,
+        body: result.error.issues
+      };
     }
-    return next();
-  };
-  return next();
+    return result.data;
+  }
+  return null;
 }
 
-function createInProcApiClient(contract, testContainer, registry) {
-  const testApiReg = createRegistry(testContainer, contract, {
-    handlerRegisteredCallback: (_entry) => {
-    },
-    middlewareHandlerRegisteredCallback: (_entry) => {
+function createInProcApiClient(contract, testContainer, registry, options) {
+  const mwHandlers = [];
+  const mwReg = registry._middlewareRegistry;
+  const mwNdx = 0;
+  for (const mwEntry of mwReg.list) {
+    if (!options?.filterMiddleware) {
+      addMiddlewareDecorators(mwHandlers, mwEntry);
+      mwHandlers.push(mwEntry);
+      continue;
     }
-  });
-  registry._middlewareRegistry.list.forEach((mwEntry) => {
-    testApiReg._middlewareRegistry.register(mwEntry);
-  });
-  const mwReg = testApiReg._middlewareRegistry;
-  flatListAllRegistryEntries(registry).forEach((entry) => {
-    if (!entry.handler) {
-      return;
+    const isIncluded = options.filterMiddleware(mwEntry.genericPath, mwNdx);
+    if (!isIncluded) {
+      continue;
     }
-    const rt = route(testApiReg, `${entry.methodEndpoint.method} ${entry.methodEndpoint.genericPath}`);
-    rt.inject(entry.injection).register(entry.handler);
-  });
+    addMiddlewareDecorators(mwHandlers, mwEntry);
+    mwHandlers.push(mwEntry);
+  }
   const client = createClient(contract, async (input) => {
+    if (options?.enhanceRequest) {
+      input = options.enhanceRequest(input);
+    }
     const diScope = testContainer.createScope();
-    const haltExecResponse = await execMiddleware(diScope, mwReg.list, input);
-    if (haltExecResponse) {
-      return haltExecResponse;
-    }
-    const rt = route(testApiReg, `${input.method} ${input.genericPath}`);
-    const result = await rt.trigger(diScope, {
-      headers: input.headers,
-      pathParams: input.pathParams,
-      body: input.body,
-      query: input.query
+    const allHandlerEntries = [...mwHandlers];
+    const endpointHandlerEntry = route(registry, `${input.method} ${input.genericPath}`);
+    if (!endpointHandlerEntry.handler) {
+      throw new Error(`No handler registered for ${input.method} ${input.genericPath}`);
+    }
+    endpointHandlerEntry.decoratorFactories.forEach((decoratorFactory) => {
+      allHandlerEntries.push({
+        genericPath: endpointHandlerEntry.genericPath,
+        triggerNoStaticTypeCheck: async (diScope2, requestObject, context) => {
+          const decorator = decoratorFactory(diScope2);
+          return await triggerEndpointDecoratorNoStaticTypeCheck(
+            endpointHandlerEntry.methodEndpoint,
+            decorator,
+            requestObject,
+            context
+          );
+        }
+      });
     });
-    return result;
+    if (options?.mockEndpointResponse) {
+      const mockResponse = options.mockEndpointResponse(input.genericPath, input.method, diScope);
+      if (mockResponse) {
+        allHandlerEntries.push({
+          genericPath: endpointHandlerEntry.genericPath,
+          triggerNoStaticTypeCheck: async (_diScope, _requestObject, _next) => {
+            return mockResponse;
+          }
+        });
+      } else {
+        allHandlerEntries.push(endpointHandlerEntry);
+      }
+    } else {
+      allHandlerEntries.push(endpointHandlerEntry);
+    }
+    const response = await execHandlerChain(diScope, allHandlerEntries, input);
+    if (!response) {
+      throw new Error(`No response from ${input.method} ${input.genericPath}`);
+    }
+    return response;
   });
   return client;
 }
+function addMiddlewareDecorators(mwHandlers, mwEntry) {
+  mwEntry.decoratorFactories.forEach((decoratorFactory) => {
+    mwHandlers.push({
+      genericPath: mwEntry.genericPath,
+      triggerNoStaticTypeCheck: async (diScope, requestObject, context) => {
+        const decorator = decoratorFactory(diScope);
+        return await triggerMiddlewareDecoratorNoStaticTypeCheck(
+          mwEntry,
+          decorator,
+          requestObject,
+          context
+        );
+      }
+    });
+  });
+}
 
 exports.ApiClient = ApiClient;
 exports.ApiContract = ApiContract;
@@ -793,6 +1089,7 @@ exports.createClient = createClient;
 exports.createInProcApiClient = createInProcApiClient;
 exports.createRegistry = createRegistry;
 exports.endpoint = endpoint;
+exports.execHandlerChain = execHandlerChain;
 exports.flatListAllRegistryEntries = flatListAllRegistryEntries;
 exports.isHttpResponseObject = isHttpResponseObject;
 exports.isHttpStatusCode = isHttpStatusCode;
@@ -802,3 +1099,5 @@ exports.partialPathString = partialPathString;
 exports.register = register;
 exports.response = response;
 exports.route = route;
+exports.triggerEndpointDecoratorNoStaticTypeCheck = triggerEndpointDecoratorNoStaticTypeCheck;
+exports.triggerMiddlewareDecoratorNoStaticTypeCheck = triggerMiddlewareDecoratorNoStaticTypeCheck;