@dvsa/appdev-api-common 0.8.0 → 0.8.1

package/http/decorators.d.ts

@@ -1,7 +1,42 @@
 import type { Logger } from "@aws-lambda-powertools/logger";
-export declare function LogDurationWithAccessor<T extends {
+/**
+ * Decorator to log the duration of a method execution by passing in an accessor function to retrieve the logger.
+ * @param getLogger - A function that takes the class instance and returns the logger instance.
+ * @param {string} label - Optional label for the log message.
+ *
+ * Note: If you are already using a logger as a class property, you can use the `Timed` decorator instead.
+ *
+ * @constructor
+ *
+ * Example usage:
+ * class MyClass {
+ *  @TimedWithAccessor(() => Container.get(LOGGER))
+ * 	async findAll() {} // The log name here will be [findAll]
+ * }
+ */
+export declare function TimedWithAccessor<T extends {
     logger: Logger;
 }>(getLogger: (self: T) => Logger, label?: string): (_target: unknown, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Decorator to log the duration of a method execution.
+ * @param {string} label - Optional label for the log message.
+ *
+ * Note: This decorator can be used on any class method that has a `logger` property.
+ * This method will throw an error if the `logger` property is not found on the class instance.
+ * If you are not using logger as a class property, you can use `LogDurationWithAccessor` instead.
+ * @constructor
+ *
+ * Example usage:
+ * class MyClass {
+ * 	private readonly logger = Container.get(Logger);
+ *
+ * 	@Timed()
+ * 	myMethod() {} // The log name here will be [myMethod]
+ *
+ * 	@Timed('MyClass.myMethod')
+ * 	myMethodWithOptName() {} // The log name here will be [MyClass.myMethod]
+ * }
+ */
 export declare function Timed<T extends {
     logger: Logger;
 }>(label?: string): (_target: unknown, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/http/decorators.js

@@ -1,9 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogDurationWithAccessor = LogDurationWithAccessor;
+exports.TimedWithAccessor = TimedWithAccessor;
 exports.Timed = Timed;
 const node_perf_hooks_1 = require("node:perf_hooks");
-function LogDurationWithAccessor(getLogger, label) {
+/**
+ * Decorator to log the duration of a method execution by passing in an accessor function to retrieve the logger.
+ * @param getLogger - A function that takes the class instance and returns the logger instance.
+ * @param {string} label - Optional label for the log message.
+ *
+ * Note: If you are already using a logger as a class property, you can use the `Timed` decorator instead.
+ *
+ * @constructor
+ *
+ * Example usage:
+ * class MyClass {
+ *  @TimedWithAccessor(() => Container.get(LOGGER))
+ * 	async findAll() {} // The log name here will be [findAll]
+ * }
+ */
+function TimedWithAccessor(getLogger, label) {
     return (_target, propertyKey, descriptor) => {
         const originalMethod = descriptor.value;
         // biome-ignore lint/suspicious/noExplicitAny: "any" is correct for this context
@@ -41,8 +56,28 @@ function LogDurationWithAccessor(getLogger, label) {
         return descriptor;
     };
 }
+/**
+ * Decorator to log the duration of a method execution.
+ * @param {string} label - Optional label for the log message.
+ *
+ * Note: This decorator can be used on any class method that has a `logger` property.
+ * This method will throw an error if the `logger` property is not found on the class instance.
+ * If you are not using logger as a class property, you can use `LogDurationWithAccessor` instead.
+ * @constructor
+ *
+ * Example usage:
+ * class MyClass {
+ * 	private readonly logger = Container.get(Logger);
+ *
+ * 	@Timed()
+ * 	myMethod() {} // The log name here will be [myMethod]
+ *
+ * 	@Timed('MyClass.myMethod')
+ * 	myMethodWithOptName() {} // The log name here will be [MyClass.myMethod]
+ * }
+ */
 function Timed(label) {
-    return LogDurationWithAccessor((cls) => {
+    return TimedWithAccessor((cls) => {
         if (!cls.logger) {
             throw new Error(`[${label}] Logger not found on decorated class.`);
         }

package/http/index.d.ts

@@ -3,8 +3,34 @@ export declare class HTTPError extends Error {
     constructor(message: string, response: Response);
 }
 export declare class HTTP {
+    /**
+     * Performs an HTTP GET request.
+     * Note: This method will throw an HTTPError if the response is not ok (status code 200-299) to emulate Axios behaviour.
+     * @param url
+     * @param options
+     */
     static get(url: string, options?: RequestInit): Promise<Response>;
+    /**
+     * Performs an HTTP POST request.
+     * Note: This method will throw an HTTPError if the response is not ok (status code 200-299) to emulate Axios behaviour.
+     * @param url
+     * @param body
+     * @param options
+     */
     static post<T>(url: string, body: T, options?: RequestInit): Promise<Response>;
+    /**
+     * Performs an HTTP PUT request.
+     * Note: This method will throw an HTTPError if the response is not ok (status code 200-299) to emulate Axios behaviour.
+     * @param url
+     * @param body
+     * @param options
+     */
     static put<T>(url: string, body: T, options?: RequestInit): Promise<Response>;
+    /**
+     * Performs an HTTP DELETE request.
+     * Note: This method will throw an HTTPError if the response is not ok (status code 200-299) to emulate Axios behaviour.
+     * @param url
+     * @param options
+     */
     static delete(url: string, options?: RequestInit): Promise<Response>;
 }

package/http/index.js

@@ -13,6 +13,12 @@ class HTTPError extends Error {
 exports.HTTPError = HTTPError;
 // biome-ignore lint/complexity/noStaticOnlyClass: makes sense for an HTTP utility to encompass all methods
 class HTTP {
+    /**
+     * Performs an HTTP GET request.
+     * Note: This method will throw an HTTPError if the response is not ok (status code 200-299) to emulate Axios behaviour.
+     * @param url
+     * @param options
+     */
     static async get(url, options) {
         const response = await fetch(url, { method: "GET", ...options });
         if (!response.ok) {
@@ -20,6 +26,13 @@ class HTTP {
         }
         return response;
     }
+    /**
+     * Performs an HTTP POST request.
+     * Note: This method will throw an HTTPError if the response is not ok (status code 200-299) to emulate Axios behaviour.
+     * @param url
+     * @param body
+     * @param options
+     */
     static async post(url, body, options) {
         const response = await fetch(url, {
             method: "POST",
@@ -32,6 +45,13 @@ class HTTP {
         }
         return response;
     }
+    /**
+     * Performs an HTTP PUT request.
+     * Note: This method will throw an HTTPError if the response is not ok (status code 200-299) to emulate Axios behaviour.
+     * @param url
+     * @param body
+     * @param options
+     */
     static async put(url, body, options) {
         const response = await fetch(url, {
             method: "PUT",
@@ -44,6 +64,12 @@ class HTTP {
         }
         return response;
     }
+    /**
+     * Performs an HTTP DELETE request.
+     * Note: This method will throw an HTTPError if the response is not ok (status code 200-299) to emulate Axios behaviour.
+     * @param url
+     * @param options
+     */
     static async delete(url, options) {
         const response = await fetch(url, { method: "DELETE", ...options });
         if (!response.ok) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dvsa/appdev-api-common",
-	"version": "0.8.0",
+	"version": "0.8.1",
 	"keywords": ["dvsa", "nodejs", "typescript"],
 	"author": "DVSA",
 	"description": "Utils library for common API functionality",