@arkyn/server 2.0.1-beta.8 → 2.0.1

package/src/http/successResponses/noContent.ts

@@ -1,32 +1,41 @@
+/**
+ * Represents a successful HTTP response with a status code of 204 (No Content).
+ * This class is used to standardize the structure of a "No Content" response,
+ * including headers, status, and status text.
+ */
+
 class NoContent {
   headers: ResponseInit["headers"];
   status: number;
   statusText: string;
 
+  /**
+   * Creates an instance of the `NoContent` class.
+   *
+   * @param init - Optional initialization object for customizing headers, status, and status text.
+   */
+
   constructor(init?: ResponseInit) {
     this.headers = init?.headers || {};
     this.status = init?.status || 204;
     this.statusText = init?.statusText ?? "No content";
   }
 
-  toResponse() {
-    const responseInit: ResponseInit = {
-      headers: this.headers,
-      status: this.status,
-      statusText: this.statusText,
-    };
+  /**
+   * Converts the `NoContent` instance into a `Response` object.
+   * This method ensures the response has the appropriate headers, status, and status text.
+   *
+   * @returns A `Response` object with no body and response metadata.
+   */
 
-    return new Response(null, responseInit);
-  }
-
-  toJson() {
+  toResponse(): Response {
     const responseInit: ResponseInit = {
       headers: this.headers,
       status: this.status,
       statusText: this.statusText,
     };
 
-    return Response.json(null, responseInit);
+    return new Response(null, responseInit);
   }
 }
 

package/src/http/successResponses/success.ts

@@ -1,9 +1,24 @@
+/**
+ * Represents a successful HTTP response with a status code of 200 (OK).
+ * This class is used to standardize the structure of a "Success" response,
+ * including the response body, headers, status, and status text.
+ *
+ * @template T - The type of the response body.
+ */
+
 class Success<T> {
   body: T;
   headers: ResponseInit["headers"];
   status: number;
   statusText: string;
 
+  /**
+   * Creates an instance of the `Success` class.
+   *
+   * @param body - The response body to be included in the HTTP response.
+   * @param init - Optional initialization object for customizing headers, status, and status text.
+   */
+
   constructor(body: T, init?: ResponseInit) {
     this.body = body;
     this.headers = init?.headers || {};
@@ -11,7 +26,14 @@ class Success<T> {
     this.statusText = init?.statusText ?? "OK";
   }
 
-  toResponse() {
+  /**
+   * Converts the `Success` instance into a `Response` object with a JSON body.
+   * This method ensures the response has the appropriate headers, status, and status text.
+   *
+   * @returns A `Response` object with the serialized JSON body and response metadata.
+   */
+
+  toResponse(): Response {
     const responseInit: ResponseInit = {
       headers: { "Content-Type": "application/json", ...this.headers },
       status: this.status,
@@ -21,7 +43,14 @@ class Success<T> {
     return new Response(JSON.stringify(this.body), responseInit);
   }
 
-  toJson() {
+  /**
+   * Converts the `Success` instance into a `Response` object using the `Response.json` method.
+   * This method is an alternative to `toResponse` for generating JSON responses.
+   *
+   * @returns A `Response` object with the JSON body and response metadata.
+   */
+
+  toJson(): Response {
     const responseInit: ResponseInit = {
       headers: this.headers,
       status: this.status,

package/src/http/successResponses/updated.ts

@@ -1,9 +1,24 @@
+/**
+ * Represents a successful HTTP response with a status code of 200 (OK) or other custom status codes.
+ * This class is used to standardize the structure of an "Updated" response,
+ * including the response body, headers, status, and status text.
+ *
+ * @template T - The type of the response body.
+ */
+
 class Updated<T> {
   body: T;
   headers: ResponseInit["headers"];
   status: number;
   statusText: string;
 
+  /**
+   * Creates an instance of the `Updated` class.
+   *
+   * @param body - The response body to be included in the HTTP response.
+   * @param init - Optional initialization object for customizing headers, status, and status text.
+   */
+
   constructor(body: T, init?: ResponseInit) {
     this.body = body;
     this.headers = init?.headers || {};
@@ -11,7 +26,14 @@ class Updated<T> {
     this.statusText = init?.statusText || "Resource updated successfully";
   }
 
-  toResponse() {
+  /**
+   * Converts the `Updated` instance into a `Response` object with a JSON body.
+   * This method ensures the response has the appropriate headers, status, and status text.
+   *
+   * @returns A `Response` object with the serialized JSON body and response metadata.
+   */
+
+  toResponse(): Response {
     const responseInit: ResponseInit = {
       headers: { "Content-Type": "application/json", ...this.headers },
       status: this.status,
@@ -21,7 +43,14 @@ class Updated<T> {
     return new Response(JSON.stringify(this.body), responseInit);
   }
 
-  toJson() {
+  /**
+   * Converts the `Updated` instance into a `Response` object using the `Response.json` method.
+   * This method is an alternative to `toResponse` for generating JSON responses.
+   *
+   * @returns A `Response` object with the JSON body and response metadata.
+   */
+
+  toJson(): Response {
     const responseInit: ResponseInit = {
       headers: this.headers,
       status: this.status,

package/src/index.ts

@@ -1,3 +1,8 @@
+// config
+export { ApiInstance } from "./config/apiInstance";
+export { InboxFlowInstance } from "./config/inboxFlowInstance";
+
+// http bad responses
 export { BadGateway } from "./http/badResponses/badGateway";
 export { BadRequest } from "./http/badResponses/badRequest";
 export { Conflict } from "./http/badResponses/conflict";
@@ -8,17 +13,20 @@ export { ServerError } from "./http/badResponses/serverError";
 export { Unauthorized } from "./http/badResponses/unauthorized";
 export { UnprocessableEntity } from "./http/badResponses/unprocessableEntity";
 
+// http success responses
 export { Created } from "./http/successResponses/created";
 export { Found } from "./http/successResponses/found";
 export { NoContent } from "./http/successResponses/noContent";
 export { Success } from "./http/successResponses/success";
 export { Updated } from "./http/successResponses/updated";
 
+// services
+export { decodeErrorMessageFromRequest } from "./services/decodeErrorMessageFromRequest";
 export { decodeRequestBody } from "./services/decodeRequestBody";
 export { errorHandler } from "./services/errorHandler";
 export { formParse } from "./services/formParse";
 export { getCaller } from "./services/getCaller";
 export { getScopedParams } from "./services/getScopedParams";
 export { httpDebug } from "./services/httpDebug";
-export { sendFileToS3 } from "./services/sendFileToS3";
 export { SchemaValidator } from "./services/schemaValidator";
+export { sendFileToS3 } from "./services/sendFileToS3";

package/src/services/__test__/decodeRequestBody.spec.ts

@@ -0,0 +1,51 @@
+import { decodeRequestBody } from "../decodeRequestBody";
+import { BadRequest } from "../../http/badResponses/badRequest";
+import { describe, expect, it } from "vitest";
+
+describe("decodeRequestBody", () => {
+  it("should decode the request body as JSON", async () => {
+    const mockRequest = {
+      arrayBuffer: async () =>
+        new TextEncoder().encode(JSON.stringify({ key: "value" })).buffer,
+    };
+
+    const result = await decodeRequestBody(mockRequest as any);
+    expect(result).toEqual({ key: "value" });
+  });
+
+  it("should decode the request body as URL-encoded form data", async () => {
+    const mockRequest = {
+      arrayBuffer: async () =>
+        new TextEncoder().encode("key=value&anotherKey=anotherValue").buffer,
+    };
+
+    const result = await decodeRequestBody(mockRequest as any);
+    expect(result).toEqual({ key: "value", anotherKey: "anotherValue" });
+  });
+
+  it("should throw BadRequest if the text is neither valid JSON nor URL-encoded", async () => {
+    const mockRequest = {
+      arrayBuffer: async () => new TextEncoder().encode("{invalidJson").buffer,
+    };
+
+    await expect(decodeRequestBody(mockRequest as any)).rejects.toThrow();
+  });
+
+  it("should throw BadRequest if the text is not a valid format for URLSearchParams", async () => {
+    const mockRequest = {
+      arrayBuffer: async () => new TextEncoder().encode("invalidFormat").buffer,
+    };
+
+    await expect(decodeRequestBody(mockRequest as any)).rejects.toThrow();
+  });
+
+  it("should throw BadRequest if an error occurs while reading the body", async () => {
+    const mockRequest = {
+      arrayBuffer: async () => {
+        throw new Error("Error reading the body");
+      },
+    };
+
+    await expect(decodeRequestBody(mockRequest as any)).rejects.toThrow();
+  });
+});

package/src/services/__test__/errorHandler.spec.ts

@@ -0,0 +1,133 @@
+import { errorHandler } from "../errorHandler";
+import { Found } from "../../http/successResponses/found";
+import { Created } from "../../http/successResponses/created";
+import { Updated } from "../../http/successResponses/updated";
+import { Success } from "../../http/successResponses/success";
+import { NoContent } from "../../http/successResponses/noContent";
+
+import { BadGateway } from "../../http/badResponses/badGateway";
+import { BadRequest } from "../../http/badResponses/badRequest";
+import { Conflict } from "../../http/badResponses/conflict";
+import { Forbidden } from "../../http/badResponses/forbidden";
+import { NotFound } from "../../http/badResponses/notFound";
+import { NotImplemented } from "../../http/badResponses/notImplemented";
+import { ServerError } from "../../http/badResponses/serverError";
+import { Unauthorized } from "../../http/badResponses/unauthorized";
+import { UnprocessableEntity } from "../../http/badResponses/unprocessableEntity";
+import { describe, expect, it } from "vitest";
+
+describe("errorHandler", () => {
+  describe("Success Responses", () => {
+    it("should handle Found response", () => {
+      const found = new Found("Resource found");
+      const response = errorHandler(found);
+      expect(response.status).toBe(found.toResponse().status);
+      expect(response.statusText).toBe(found.toResponse().statusText);
+    });
+
+    it("should handle Created response", () => {
+      const created = new Created("Resource created");
+      const response = errorHandler(created);
+      expect(response.status).toBe(created.toResponse().status);
+      expect(response.statusText).toBe(created.toResponse().statusText);
+    });
+
+    it("should handle Updated response", () => {
+      const updated = new Updated("Resource updated");
+      const response = errorHandler(updated);
+      expect(response.status).toBe(updated.toResponse().status);
+      expect(response.statusText).toBe(updated.toResponse().statusText);
+    });
+
+    it("should handle Success response", () => {
+      const success = new Success("Operation successful");
+      const response = errorHandler(success);
+      expect(response.status).toBe(success.toResponse().status);
+      expect(response.statusText).toBe(success.toResponse().statusText);
+    });
+
+    it("should handle NoContent response", () => {
+      const noContent = new NoContent();
+      const response = errorHandler(noContent);
+      expect(response.status).toBe(noContent.toResponse().status);
+      expect(response.statusText).toBe(noContent.toResponse().statusText);
+    });
+  });
+
+  describe("Error Responses", () => {
+    it("should handle BadGateway error", () => {
+      const badGateway = new BadGateway("Bad gateway error");
+      const response = errorHandler(badGateway);
+      expect(response.status).toBe(badGateway.toResponse().status);
+      expect(response.statusText).toBe(badGateway.toResponse().statusText);
+    });
+
+    it("should handle BadRequest error", () => {
+      const badRequest = new BadRequest("Bad request error");
+      const response = errorHandler(badRequest);
+      expect(response.status).toBe(badRequest.toResponse().status);
+      expect(response.statusText).toBe(badRequest.toResponse().statusText);
+    });
+
+    it("should handle Conflict error", () => {
+      const conflict = new Conflict("Conflict error");
+      const response = errorHandler(conflict);
+      expect(response.status).toBe(conflict.toResponse().status);
+      expect(response.statusText).toBe(conflict.toResponse().statusText);
+    });
+
+    it("should handle Forbidden error", () => {
+      const forbidden = new Forbidden("Forbidden error");
+      const response = errorHandler(forbidden);
+      expect(response.status).toBe(forbidden.toResponse().status);
+      expect(response.statusText).toBe(forbidden.toResponse().statusText);
+    });
+
+    it("should handle NotFound error", () => {
+      const notFound = new NotFound("Not found error");
+      const response = errorHandler(notFound);
+      expect(response.status).toBe(notFound.toResponse().status);
+      expect(response.statusText).toBe(notFound.toResponse().statusText);
+    });
+
+    it("should handle NotImplemented error", () => {
+      const notImplemented = new NotImplemented("Not implemented error");
+      const response = errorHandler(notImplemented);
+      expect(response.status).toBe(notImplemented.toResponse().status);
+      expect(response.statusText).toBe(notImplemented.toResponse().statusText);
+    });
+
+    it("should handle ServerError error", () => {
+      const serverError = new ServerError("Server error");
+      const response = errorHandler(serverError);
+      expect(response.status).toBe(serverError.toResponse().status);
+      expect(response.statusText).toBe(serverError.toResponse().statusText);
+    });
+
+    it("should handle Unauthorized error", () => {
+      const unauthorized = new Unauthorized("Unauthorized error");
+      const response = errorHandler(unauthorized);
+      expect(response.status).toBe(unauthorized.toResponse().status);
+      expect(response.statusText).toBe(unauthorized.toResponse().statusText);
+    });
+
+    it("should handle UnprocessableEntity error", () => {
+      const unprocessableEntity = new UnprocessableEntity({});
+      const response = errorHandler(unprocessableEntity);
+      expect(response.status).toBe(unprocessableEntity.toResponse().status);
+      expect(response.statusText).toBe(
+        unprocessableEntity.toResponse().statusText
+      );
+    });
+  });
+
+  describe("Unknown Error", () => {
+    it("should return undefined for unknown error types", () => {
+      const unknownError = new Error("Unknown error");
+      const serverError = new ServerError("Server error");
+      const response = errorHandler(unknownError);
+      expect(response.status).toBe(serverError.toResponse().status);
+      expect(response.statusText).toBe(serverError.toResponse().statusText);
+    });
+  });
+});

package/src/services/__test__/formParse.spec.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { formParse } from "../formParse";
+
+describe("formParse", () => {
+  it("should return success and parsed data when validation passes", () => {
+    const schema = z.object({
+      name: z.string().min(1, "Name is required"),
+      age: z.number().min(18, "Must be at least 18"),
+    });
+
+    const formData = { name: "John", age: 25 };
+
+    const result = formParse([formData, schema]);
+
+    expect(result.success).toBe(true);
+    expect(result).toHaveProperty("data");
+    if (result.success) expect(result.data).toEqual(formData);
+  });
+
+  it("should return field errors when validation fails", () => {
+    const schema = z.object({
+      name: z.string().min(1, "Name is required"),
+      age: z.number().min(18, "Must be at least 18"),
+    });
+
+    const formData = { name: "", age: 17 };
+
+    const result = formParse([formData, schema]);
+
+    expect(result.success).toBe(false);
+    expect(result).toHaveProperty("fieldErrors");
+
+    if (!result.success) {
+      expect(result.fieldErrors).toEqual({
+        name: "Name is required",
+        age: "Must be at least 18",
+      });
+      expect(result.fields).toEqual(formData);
+    }
+  });
+
+  it("should handle missing fields gracefully", () => {
+    const schema = z.object({
+      name: z
+        .string({ required_error: "Name is required" })
+        .min(1, "Name is required"),
+      age: z.number().min(18, "Must be at least 18"),
+    });
+
+    const formData = { age: 20 }; // Missing "name"
+
+    const result = formParse([formData, schema]);
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.fieldErrors).toEqual({ name: "Name is required" });
+      expect(result.fields).toEqual(formData);
+    }
+  });
+
+  it("should return success for an empty schema", () => {
+    const schema = z.object({});
+    const formData = {};
+
+    const result = formParse([formData, schema]);
+
+    expect(result.success).toBe(true);
+    expect(result).toHaveProperty("data");
+    if (result.success) expect(result.data).toEqual(formData);
+  });
+
+  it("should handle nested schemas correctly", () => {
+    const schema = z.object({
+      user: z.object({
+        name: z.string().min(1, "Name is required"),
+        age: z.number().min(18, "Must be at least 18"),
+      }),
+    });
+
+    const formData = {
+      user: { name: "", age: 16 },
+    };
+
+    const result = formParse([formData, schema]);
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.fieldErrors).toEqual({
+        "user.name": "Name is required",
+        "user.age": "Must be at least 18",
+      });
+      expect(result.fields).toEqual(formData);
+    }
+  });
+});

package/src/services/__test__/getCaller.spec.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import { getCaller } from "../getCaller";
+
+describe("getCaller", () => {
+  it("should return the correct caller function name and file path", () => {
+    function testFunction() {
+      return getCaller();
+    }
+
+    const result = testFunction();
+
+    expect(result.functionName).toBe("testFunction");
+    expect(result.callerInfo).toContain("getCaller.spec.ts");
+  });
+
+  it("should handle calls from anonymous functions", () => {
+    const result = (() => getCaller())();
+
+    expect(result.functionName).toBe("Unknown function");
+    expect(result.callerInfo).toContain("getCaller.spec.ts");
+  });
+
+  it("should return the correct name for nested functions", () => {
+    function outerFunction() {
+      function innerFunction() {
+        return getCaller();
+      }
+      return innerFunction();
+    }
+
+    const result = outerFunction();
+
+    expect(result.functionName).toBe("innerFunction");
+    expect(result.callerInfo).toContain("getCaller.spec.ts");
+  });
+
+  it("should return method name when called from object method", () => {
+    const obj = {
+      method() {
+        return getCaller();
+      },
+    };
+
+    const result = obj.method();
+
+    expect(result.functionName).toMatch(/method|Object.method/);
+    expect(result.callerInfo).toContain("getCaller.spec.ts");
+  });
+
+  it("should return method name when called from class method", () => {
+    class TestClass {
+      call() {
+        return getCaller();
+      }
+    }
+
+    const instance = new TestClass();
+    const result = instance.call();
+
+    expect(result.functionName).toMatch(/call|TestClass.call/);
+    expect(result.callerInfo).toContain("getCaller.spec.ts");
+  });
+
+  it("should return the correct caller for indirect calls", () => {
+    function intermediary(fn: () => any) {
+      return fn();
+    }
+
+    function actualCaller() {
+      return getCaller();
+    }
+
+    const result = intermediary(actualCaller);
+
+    expect(result.functionName).toBe("actualCaller");
+    expect(result.callerInfo).toContain("getCaller.spec.ts");
+  });
+});

package/src/services/__test__/getScopedParams.spec.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { getScopedParams } from "../getScopedParams";
+
+describe("getScopedParams", () => {
+  it("should return all query parameters when no scope is provided", () => {
+    const request = {
+      url: "https://example.com?key1=value1&key2=value2",
+    } as Request;
+
+    const params = getScopedParams(request);
+
+    expect(params.get("key1")).toBe("value1");
+    expect(params.get("key2")).toBe("value2");
+    expect(params.toString()).toBe("key1=value1&key2=value2");
+  });
+
+  it("should return only scoped query parameters when a scope is provided", () => {
+    const request = {
+      url: "https://example.com?scope:key1=value1&scope:key2=value2&key3=value3",
+    } as Request;
+
+    const params = getScopedParams(request, "scope");
+
+    expect(params.get("key1")).toBe("value1");
+    expect(params.get("key2")).toBe("value2");
+    expect(params.get("key3")).toBeNull();
+    expect(params.toString()).toBe("key1=value1&key2=value2");
+  });
+
+  it("should return an empty URLSearchParams object if no parameters match the scope", () => {
+    const request = {
+      url: "https://example.com?key1=value1&key2=value2",
+    } as Request;
+
+    const params = getScopedParams(request, "scope");
+
+    expect(params.toString()).toBe("");
+  });
+
+  it("should handle URLs with no query parameters", () => {
+    const request = { url: "https://example.com" } as Request;
+    const params = getScopedParams(request);
+
+    expect(params.toString()).toBe("");
+  });
+
+  it("should handle URLs with query parameters but no matching scope", () => {
+    const request = {
+      url: "https://example.com?other:key1=value1&other:key2=value2",
+    } as Request;
+
+    const params = getScopedParams(request, "scope");
+
+    expect(params.toString()).toBe("");
+  });
+
+  it("should handle special characters in query parameter keys and values", () => {
+    const request = {
+      url: "https://example.com?scope:key+1=value+1&scope:key+2=value+2",
+    } as Request;
+
+    const params = getScopedParams(request, "scope");
+
+    expect(params.get("key 1")).toBe("value 1");
+    expect(params.get("key 2")).toBe("value 2");
+    expect(params.toString()).toBe("key+1=value+1&key+2=value+2");
+  });
+});