@boo-labs/server 1.0.0 → 1.0.2

package/source/shared/validations/ServerConfiguration/ListenOptions/index.mjs

@@ -13,6 +13,20 @@
 import Validation from '#shared/outcome/Validation';
 import ServerConfigurationError from '#shared/errors/ServerConfigurationError';
 
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * A successful {@link Validation} instance.
+ *
+ * @typedef {import('#shared/outcome/Validation').SuccessValidation} SuccessValidation
+ */
+
+/**
+ * A failed {@link Validation} instance.
+ *
+ * @template {Error} E
+ * @typedef {import('#shared/outcome/Validation').FailureValidation<E>} FailureValidation
+ */
+
 // ━━ CONSTANTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
  * Minimum valid TCP port.
@@ -42,6 +56,7 @@ function isPlainObject(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
  * Validates listen options.
  *
@@ -54,7 +69,8 @@ function isPlainObject(value) {
  * 5. `backlog`, if present, must be a number.
  *
  * @param {unknown} options - Listen options to validate.
- * @returns {Validation} Validation result.
+ * @returns {SuccessValidation|FailureValidation<ServerConfigurationError>} Validation result.
+ *
  * @example
  * ```js
  * const validation = validateListenOptions({ port: 3000 });
@@ -77,33 +93,31 @@ export function validateListenOptions(options) {
   }
 
   if (!isPlainObject(options)) {
-    return Validation.failure({
-      error: ServerConfigurationError,
-      code: 'INVALID_LISTEN_OPTIONS',
-      custom: true,
-      options: { values: { received: typeof options } },
-    });
+    return Validation.failure(
+      new ServerConfigurationError('INVALID_LISTEN_OPTIONS', {
+        values: { received: typeof options },
+      }),
+    );
   }
 
   if ('port' in options) {
     const { port } = options;
 
     if (typeof port !== 'number') {
-      return Validation.failure({
-        error: ServerConfigurationError,
-        code: 'INVALID_PORT_TYPE',
-        custom: true,
-        options: { values: { received: typeof port } },
-      });
+      return Validation.failure(
+        new ServerConfigurationError('INVALID_PORT_TYPE', {
+          values: { received: typeof port },
+        }),
+      );
     }
 
     if (!Number.isInteger(port) || port < MIN_PORT || port > MAX_PORT) {
-      return Validation.failure({
-        error: ServerConfigurationError,
-        code: 'INVALID_PORT_RANGE',
-        custom: true,
-        options: { details: { port } },
-      });
+      return Validation.failure(
+        new ServerConfigurationError('INVALID_PORT_RANGE', {
+          values: { port },
+          details: { port },
+        }),
+      );
     }
   }
 
@@ -111,21 +125,19 @@ export function validateListenOptions(options) {
     const { host } = options;
 
     if (typeof host !== 'string') {
-      return Validation.failure({
-        error: ServerConfigurationError,
-        code: 'INVALID_HOST_TYPE',
-        custom: true,
-        options: { values: { received: typeof host } },
-      });
+      return Validation.failure(
+        new ServerConfigurationError('INVALID_HOST_TYPE', {
+          values: { received: typeof host },
+        }),
+      );
     }
 
     if (host.length === 0) {
-      return Validation.failure({
-        error: ServerConfigurationError,
-        code: 'INVALID_HOST_VALUE',
-        custom: true,
-        options: { details: { host } },
-      });
+      return Validation.failure(
+        new ServerConfigurationError('INVALID_HOST_VALUE', {
+          details: { host },
+        }),
+      );
     }
   }
 
@@ -133,21 +145,20 @@ export function validateListenOptions(options) {
     const { backlog } = options;
 
     if (typeof backlog !== 'number') {
-      return Validation.failure({
-        error: ServerConfigurationError,
-        code: 'INVALID_BACKLOG_TYPE',
-        custom: true,
-        options: { values: { received: typeof backlog } },
-      });
+      return Validation.failure(
+        new ServerConfigurationError('INVALID_BACKLOG_TYPE', {
+          values: { received: typeof backlog },
+        }),
+      );
     }
 
     if (!Number.isInteger(backlog) || backlog <= 0) {
-      return Validation.failure({
-        error: ServerConfigurationError,
-        code: 'INVALID_BACKLOG_RANGE',
-        custom: true,
-        options: { details: { backlog } },
-      });
+      return Validation.failure(
+        new ServerConfigurationError('INVALID_BACKLOG_RANGE', {
+          values: { backlog },
+          details: { backlog },
+        }),
+      );
     }
   }
 
@@ -164,6 +175,7 @@ export function validateListenOptions(options) {
  * @throws {ServerConfigurationError} If `host` is not a string.
  * @throws {ServerConfigurationError} If `host` is an empty string.
  * @throws {ServerConfigurationError} If `backlog` is not a number.
+ *
  * @example
  * ```js
  * assertListenOptions({ port: 3000, host: '127.0.0.1' });

package/source/shared/validations/ServerConfiguration/RateLimitOptions/index.mjs

@@ -14,6 +14,20 @@
 import Validation from '#shared/outcome/Validation';
 import ServerConfigurationError from '#shared/errors/ServerConfigurationError';
 
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * A successful {@link Validation} instance.
+ *
+ * @typedef {import('#shared/outcome/Validation').SuccessValidation} SuccessValidation
+ */
+
+/**
+ * A failed {@link Validation} instance.
+ *
+ * @template {Error} E
+ * @typedef {import('#shared/outcome/Validation').FailureValidation<E>} FailureValidation
+ */
+
 // ━━ CONSTANTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
  * Minimum valid HTTP status code for a rate-limit rejection.
@@ -43,6 +57,7 @@ function isPlainObject(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
  * Validates rate limit options.
  *
@@ -61,7 +76,8 @@ function isPlainObject(value) {
  * 11. `legacyHeaders`, if present, must be a boolean.
  *
  * @param {unknown} options - Rate limit options to validate.
- * @returns {Validation} Validation result.
+ * @returns {SuccessValidation|FailureValidation<ServerConfigurationError>} Validation result.
+ *
  * @example
  * ```js
  * const validation = validateRateLimitOptions({ windowMs: 60_000, max: 100 });
@@ -84,33 +100,31 @@ export function validateRateLimitOptions(options) {
   }
 
   if (!isPlainObject(options)) {
-    return Validation.failure({
-      error: ServerConfigurationError,
-      code: 'INVALID_RATE_LIMIT_OPTIONS',
-      custom: true,
-      options: { values: { received: typeof options } },
-    });
+    return Validation.failure(
+      new ServerConfigurationError('INVALID_RATE_LIMIT_OPTIONS', {
+        values: { received: typeof options },
+      }),
+    );
   }
 
   if ('windowMs' in options) {
     const { windowMs } = options;
 
     if (typeof windowMs !== 'number') {
-      return Validation.failure({
-        error: ServerConfigurationError,
-        code: 'INVALID_RATE_LIMIT_WINDOW_MS_TYPE',
-        custom: true,
-        options: { values: { received: typeof windowMs } },
-      });
+      return Validation.failure(
+        new ServerConfigurationError('INVALID_RATE_LIMIT_WINDOW_MS_TYPE', {
+          values: { received: typeof windowMs },
+        }),
+      );
     }
 
     if (!Number.isInteger(windowMs) || windowMs <= 0) {
-      return Validation.failure({
-        error: ServerConfigurationError,
-        code: 'INVALID_RATE_LIMIT_WINDOW_MS_RANGE',
-        custom: true,
-        options: { details: { windowMs } },
-      });
+      return Validation.failure(
+        new ServerConfigurationError('INVALID_RATE_LIMIT_WINDOW_MS_RANGE', {
+          values: { windowMs },
+          details: { windowMs },
+        }),
+      );
     }
   }
 
@@ -118,21 +132,20 @@ export function validateRateLimitOptions(options) {
     const { max } = options;
 
     if (typeof max !== 'number') {
-      return Validation.failure({
-        error: ServerConfigurationError,
-        code: 'INVALID_RATE_LIMIT_MAX_TYPE',
-        custom: true,
-        options: { values: { received: typeof max } },
-      });
+      return Validation.failure(
+        new ServerConfigurationError('INVALID_RATE_LIMIT_MAX_TYPE', {
+          values: { received: typeof max },
+        }),
+      );
     }
 
     if (!Number.isInteger(max) || max <= 0) {
-      return Validation.failure({
-        error: ServerConfigurationError,
-        code: 'INVALID_RATE_LIMIT_MAX_RANGE',
-        custom: true,
-        options: { details: { max } },
-      });
+      return Validation.failure(
+        new ServerConfigurationError('INVALID_RATE_LIMIT_MAX_RANGE', {
+          values: { max },
+          details: { max },
+        }),
+      );
     }
   }
 
@@ -140,12 +153,11 @@ export function validateRateLimitOptions(options) {
     const { statusCode } = options;
 
     if (typeof statusCode !== 'number') {
-      return Validation.failure({
-        error: ServerConfigurationError,
-        code: 'INVALID_RATE_LIMIT_STATUS_CODE_TYPE',
-        custom: true,
-        options: { values: { received: typeof statusCode } },
-      });
+      return Validation.failure(
+        new ServerConfigurationError('INVALID_RATE_LIMIT_STATUS_CODE_TYPE', {
+          values: { received: typeof statusCode },
+        }),
+      );
     }
 
     if (
@@ -153,12 +165,12 @@ export function validateRateLimitOptions(options) {
       statusCode < MIN_STATUS_CODE ||
       statusCode > MAX_STATUS_CODE
     ) {
-      return Validation.failure({
-        error: ServerConfigurationError,
-        code: 'INVALID_RATE_LIMIT_STATUS_CODE_RANGE',
-        custom: true,
-        options: { details: { statusCode } },
-      });
+      return Validation.failure(
+        new ServerConfigurationError('INVALID_RATE_LIMIT_STATUS_CODE_RANGE', {
+          values: { statusCode },
+          details: { statusCode },
+        }),
+      );
     }
   }
 
@@ -166,12 +178,11 @@ export function validateRateLimitOptions(options) {
     const { message } = options;
 
     if (!isPlainObject(message)) {
-      return Validation.failure({
-        error: ServerConfigurationError,
-        code: 'INVALID_RATE_LIMIT_MESSAGE_TYPE',
-        custom: true,
-        options: { values: { received: typeof message } },
-      });
+      return Validation.failure(
+        new ServerConfigurationError('INVALID_RATE_LIMIT_MESSAGE_TYPE', {
+          values: { received: typeof message },
+        }),
+      );
     }
   }
 
@@ -179,12 +190,11 @@ export function validateRateLimitOptions(options) {
     const { standardHeaders } = options;
 
     if (typeof standardHeaders !== 'boolean') {
-      return Validation.failure({
-        error: ServerConfigurationError,
-        code: 'INVALID_RATE_LIMIT_STANDARD_HEADERS_TYPE',
-        custom: true,
-        options: { values: { received: typeof standardHeaders } },
-      });
+      return Validation.failure(
+        new ServerConfigurationError('INVALID_RATE_LIMIT_STANDARD_HEADERS_TYPE', {
+          values: { received: typeof standardHeaders },
+        }),
+      );
     }
   }
 
@@ -192,12 +202,11 @@ export function validateRateLimitOptions(options) {
     const { legacyHeaders } = options;
 
     if (typeof legacyHeaders !== 'boolean') {
-      return Validation.failure({
-        error: ServerConfigurationError,
-        code: 'INVALID_RATE_LIMIT_LEGACY_HEADERS_TYPE',
-        custom: true,
-        options: { values: { received: typeof legacyHeaders } },
-      });
+      return Validation.failure(
+        new ServerConfigurationError('INVALID_RATE_LIMIT_LEGACY_HEADERS_TYPE', {
+          values: { received: typeof legacyHeaders },
+        }),
+      );
     }
   }
 
@@ -215,6 +224,7 @@ export function validateRateLimitOptions(options) {
  * @throws {ServerConfigurationError} If `message` is not a plain object.
  * @throws {ServerConfigurationError} If `standardHeaders` is not a boolean.
  * @throws {ServerConfigurationError} If `legacyHeaders` is not a boolean.
+ *
  * @example
  * ```js
  * assertRateLimitOptions({ windowMs: 60_000, max: 100 });

package/source/shared/validations/ServerConfiguration/RequestOptions/index.mjs

@@ -13,6 +13,20 @@
 import Validation from '#shared/outcome/Validation';
 import ServerConfigurationError from '#shared/errors/ServerConfigurationError';
 
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * A successful {@link Validation} instance.
+ *
+ * @typedef {import('#shared/outcome/Validation').SuccessValidation} SuccessValidation
+ */
+
+/**
+ * A failed {@link Validation} instance.
+ *
+ * @template {Error} E
+ * @typedef {import('#shared/outcome/Validation').FailureValidation<E>} FailureValidation
+ */
+
 // ━━ FUNCTIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
  * Determines whether a value is a non-null plain object.
@@ -25,6 +39,7 @@ function isPlainObject(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
  * Validates request options.
  *
@@ -36,7 +51,7 @@ function isPlainObject(value) {
  * 4. `trustProxy`, if defined, must be a boolean or a non-negative integer.
  *
  * @param {unknown} options - Request options to validate.
- * @returns {Validation} Validation result.
+ * @returns {SuccessValidation|FailureValidation<ServerConfigurationError>} Validation result.
  */
 export function validateRequestOptions(options) {
   if (options === undefined) {
@@ -44,12 +59,11 @@ export function validateRequestOptions(options) {
   }
 
   if (!isPlainObject(options)) {
-    return Validation.failure({
-      error: ServerConfigurationError,
-      code: 'INVALID_REQUEST_OPTIONS',
-      custom: true,
-      options: { values: { received: typeof options } },
-    });
+    return Validation.failure(
+      new ServerConfigurationError('INVALID_REQUEST_OPTIONS', {
+        values: { received: typeof options },
+      }),
+    );
   }
 
   if ('bodyLimit' in options) {
@@ -57,21 +71,20 @@ export function validateRequestOptions(options) {
 
     if (bodyLimit !== undefined) {
       if (typeof bodyLimit !== 'number') {
-        return Validation.failure({
-          error: ServerConfigurationError,
-          code: 'INVALID_BODY_LIMIT_TYPE',
-          custom: true,
-          options: { values: { received: typeof bodyLimit } },
-        });
+        return Validation.failure(
+          new ServerConfigurationError('INVALID_BODY_LIMIT_TYPE', {
+            values: { received: typeof bodyLimit },
+          }),
+        );
       }
 
       if (!Number.isSafeInteger(bodyLimit) || bodyLimit <= 0) {
-        return Validation.failure({
-          error: ServerConfigurationError,
-          code: 'INVALID_BODY_LIMIT_RANGE',
-          custom: true,
-          options: { details: { bodyLimit } },
-        });
+        return Validation.failure(
+          new ServerConfigurationError('INVALID_BODY_LIMIT_RANGE', {
+            values: { bodyLimit },
+            details: { bodyLimit },
+          }),
+        );
       }
     }
   }
@@ -84,21 +97,20 @@ export function validateRequestOptions(options) {
       const isNumber = typeof trustProxy === 'number';
 
       if (!isBoolean && !isNumber) {
-        return Validation.failure({
-          error: ServerConfigurationError,
-          code: 'INVALID_TRUST_PROXY_TYPE',
-          custom: true,
-          options: { values: { received: typeof trustProxy } },
-        });
+        return Validation.failure(
+          new ServerConfigurationError('INVALID_TRUST_PROXY_TYPE', {
+            values: { received: typeof trustProxy },
+          }),
+        );
       }
 
       if (isNumber && (!Number.isInteger(trustProxy) || trustProxy < 0)) {
-        return Validation.failure({
-          error: ServerConfigurationError,
-          code: 'INVALID_TRUST_PROXY_RANGE',
-          custom: true,
-          options: { details: { trustProxy } },
-        });
+        return Validation.failure(
+          new ServerConfigurationError('INVALID_TRUST_PROXY_RANGE', {
+            values: { trustProxy },
+            details: { trustProxy },
+          }),
+        );
       }
     }
   }
@@ -115,6 +127,7 @@ export function validateRequestOptions(options) {
  * @throws {ServerConfigurationError} If `bodyLimit` is defined and is not a positive safe integer.
  * @throws {ServerConfigurationError} If `trustProxy` is defined and is not a boolean or number.
  * @throws {ServerConfigurationError} If numeric `trustProxy` is defined and is negative or not an integer.
+ *
  * @example
  * ```js
  * assertRequestOptions({

package/source/shared/validations/ServerConfiguration/ResponseOptions/index.mjs

@@ -13,6 +13,20 @@
 import Validation from '#shared/outcome/Validation';
 import ServerConfigurationError from '#shared/errors/ServerConfigurationError';
 
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * A successful {@link Validation} instance.
+ *
+ * @typedef {import('#shared/outcome/Validation').SuccessValidation} SuccessValidation
+ */
+
+/**
+ * A failed {@link Validation} instance.
+ *
+ * @template {Error} E
+ * @typedef {import('#shared/outcome/Validation').FailureValidation<E>} FailureValidation
+ */
+
 // ━━ FUNCTIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
  * Determines whether a value is a non-null plain object.
@@ -25,6 +39,7 @@ function isPlainObject(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
  * Validates response options.
  *
@@ -36,7 +51,8 @@ function isPlainObject(value) {
  * 4. `defaultCharset`, if defined, must be a non-empty string.
  *
  * @param {unknown} options - Response options to validate.
- * @returns {Validation} Validation result.
+ * @returns {SuccessValidation|FailureValidation<ServerConfigurationError>} Validation result.
+ *
  * @example
  * ```js
  * const validation = validateResponseOptions({ etag: true });
@@ -51,12 +67,11 @@ export function validateResponseOptions(options) {
   }
 
   if (!isPlainObject(options)) {
-    return Validation.failure({
-      error: ServerConfigurationError,
-      code: 'INVALID_RESPONSE_OPTIONS',
-      custom: true,
-      options: { values: { received: typeof options } },
-    });
+    return Validation.failure(
+      new ServerConfigurationError('INVALID_RESPONSE_OPTIONS', {
+        values: { received: typeof options },
+      }),
+    );
   }
 
   if ('etag' in options) {
@@ -64,12 +79,11 @@ export function validateResponseOptions(options) {
 
     if (etag !== undefined) {
       if (typeof etag !== 'boolean') {
-        return Validation.failure({
-          error: ServerConfigurationError,
-          code: 'INVALID_ETAG_TYPE',
-          custom: true,
-          options: { values: { received: typeof etag } },
-        });
+        return Validation.failure(
+          new ServerConfigurationError('INVALID_ETAG_TYPE', {
+            values: { received: typeof etag },
+          }),
+        );
       }
     }
   }
@@ -79,21 +93,19 @@ export function validateResponseOptions(options) {
 
     if (defaultCharset !== undefined) {
       if (typeof defaultCharset !== 'string') {
-        return Validation.failure({
-          error: ServerConfigurationError,
-          code: 'INVALID_DEFAULT_CHARSET_TYPE',
-          custom: true,
-          options: { values: { received: typeof defaultCharset } },
-        });
+        return Validation.failure(
+          new ServerConfigurationError('INVALID_DEFAULT_CHARSET_TYPE', {
+            values: { received: typeof defaultCharset },
+          }),
+        );
       }
 
       if (defaultCharset.trim().length === 0) {
-        return Validation.failure({
-          error: ServerConfigurationError,
-          code: 'INVALID_DEFAULT_CHARSET_VALUE',
-          custom: true,
-          options: { details: { defaultCharset } },
-        });
+        return Validation.failure(
+          new ServerConfigurationError('INVALID_DEFAULT_CHARSET_VALUE', {
+            details: { defaultCharset },
+          }),
+        );
       }
     }
   }
@@ -109,6 +121,7 @@ export function validateResponseOptions(options) {
  * @throws {ServerConfigurationError} If `etag` is defined and is not a boolean.
  * @throws {ServerConfigurationError} If `defaultCharset` is defined and is not a string.
  * @throws {ServerConfigurationError} If `defaultCharset` is defined and is an empty string.
+ *
  * @example
  * ```js
  * assertResponseOptions({ etag: true, defaultCharset: 'utf-8' });
@@ -116,6 +129,7 @@ export function validateResponseOptions(options) {
  */
 export function assertResponseOptions(options) {
   const validation = validateResponseOptions(options);
+
   if (!validation.ok) {
     throw validation.error;
   }