@boo-labs/server 1.0.1 → 1.0.2

package/source/shared/validations/PathnamePattern/index.mjs

@@ -14,11 +14,24 @@
 import Validation from '#shared/outcome/Validation';
 import PathnamePatternError from '#shared/errors/PathnamePatternError';
 
+// ━━ 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 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
  * Maximum number of characters allowed in a pathname pattern.
  *
- * @private
  * @type {number}
  */
 const MAX_PATTERN_LENGTH = 512;
@@ -29,7 +42,6 @@ const MAX_PATTERN_LENGTH = 512;
  * Parameter names must begin with a letter or underscore and may contain
  * letters, digits, and underscores.
  *
- * @private
  * @type {string}
  */
 const PARAM_NAME = String.raw`[A-Za-z_][A-Za-z0-9_]*`;
@@ -38,7 +50,6 @@ const PARAM_NAME = String.raw`[A-Za-z_][A-Za-z0-9_]*`;
  * Regular expression source for a literal character allowed inside a pathname
  * segment.
  *
- * @private
  * @type {string}
  */
 const LITERAL_CHAR = String.raw`[A-Za-z0-9._~!$&'()+,;=@-]`;
@@ -49,7 +60,6 @@ const LITERAL_CHAR = String.raw`[A-Za-z0-9._~!$&'()+,;=@-]`;
  *
  * Supported forms are `:name` and `{name}`.
  *
- * @private
  * @type {string}
  */
 const PARAM_SEGMENT = String.raw`(?::${PARAM_NAME}|\{${PARAM_NAME}\})`;
@@ -111,7 +121,8 @@ const PARAMETER_PATTERN_REGEXP = /:([A-Za-z_][A-Za-z0-9_]*)|\{([A-Za-z_][A-Za-z0
  *
  * @private
  * @param {string} pathnamePattern - Pathname pattern to validate.
- * @returns {Validation} Validation result.
+ * @returns {SuccessValidation|FailureValidation<PathnamePatternError>} Validation result.
+ *
  * @example
  * ```js
  * const validation = validateUniqueParamNames('/users/:id/posts/{postId}');
@@ -119,6 +130,7 @@ const PARAMETER_PATTERN_REGEXP = /:([A-Za-z_][A-Za-z0-9_]*)|\{([A-Za-z_][A-Za-z0
  * console.log(validation.ok);
  * // => true
  * ```
+ *
  * @example
  * ```js
  * const validation = validateUniqueParamNames('/users/:id/posts/{id}');
@@ -134,15 +146,12 @@ function validateUniqueParamNames(pathnamePattern) {
     const name = match[1] ?? match[2];
 
     if (names.has(name)) {
-      return Validation.failure({
-        error: PathnamePatternError,
-        code: 'DUPLICATE_PARAMETER_NAME',
-        custom: true,
-        options: {
+      return Validation.failure(
+        new PathnamePatternError('DUPLICATE_PARAMETER_NAME', {
           values: { name },
           details: { pathnamePattern },
-        },
-      });
+        }),
+      );
     }
 
     names.add(name);
@@ -165,7 +174,8 @@ function validateUniqueParamNames(pathnamePattern) {
  * 5. Parameter names must be unique.
  *
  * @param {unknown} pathnamePattern - Pathname pattern to validate.
- * @returns {Validation} Validation result.
+ * @returns {SuccessValidation|FailureValidation<PathnamePatternError>} Validation result.
+ *
  * @example
  * ```js
  * const validation = validatePathnamePattern('/users/:id');
@@ -184,45 +194,32 @@ function validateUniqueParamNames(pathnamePattern) {
  */
 export function validatePathnamePattern(pathnamePattern) {
   if (typeof pathnamePattern !== 'string') {
-    return Validation.failure({
-      error: PathnamePatternError,
-      code: 'INVALID_PATTERN_TYPE',
-      custom: true,
-      options: {
+    return Validation.failure(
+      new PathnamePatternError('INVALID_PATTERN_TYPE', {
         values: { expected: 'string', received: typeof pathnamePattern },
-      },
-    });
+      }),
+    );
   }
 
   if (pathnamePattern.length === 0) {
-    return Validation.failure({
-      error: PathnamePatternError,
-      code: 'EMPTY_PATTERN',
-      custom: true,
-    });
+    return Validation.failure(new PathnamePatternError('EMPTY_PATTERN'));
   }
 
   if (pathnamePattern.length > MAX_PATTERN_LENGTH) {
-    return Validation.failure({
-      error: PathnamePatternError,
-      code: 'PATTERN_TOO_LONG',
-      custom: true,
-      options: {
+    return Validation.failure(
+      new PathnamePatternError('PATTERN_TOO_LONG', {
         values: { maxLength: MAX_PATTERN_LENGTH, actualLength: pathnamePattern.length },
-      },
-    });
+      }),
+    );
   }
 
   if (!PATHNAME_PATTERN_REGEXP.test(pathnamePattern)) {
-    return Validation.failure({
-      error: PathnamePatternError,
-      code: 'INVALID_PATHNAME_PATTERN',
-      custom: true,
-      options: {
+    return Validation.failure(
+      new PathnamePatternError('INVALID_PATHNAME_PATTERN', {
         values: { pathnamePattern },
         details: { constraint: 'Must be * or start with / and contain valid segments' },
-      },
-    });
+      }),
+    );
   }
 
   return validateUniqueParamNames(pathnamePattern);
@@ -237,6 +234,7 @@ export function validatePathnamePattern(pathnamePattern) {
  * @throws {PathnamePatternError} If the pathname pattern exceeds the maximum length.
  * @throws {PathnamePatternError} If the pathname pattern syntax is invalid.
  * @throws {PathnamePatternError} If the pathname pattern has duplicate parameter names.
+ *
  * @example
  * ```js
  * assertPathnamePattern('/users/:id');
@@ -250,6 +248,7 @@ export function validatePathnamePattern(pathnamePattern) {
  */
 export function assertPathnamePattern(pathnamePattern) {
   const validation = validatePathnamePattern(pathnamePattern);
+
   if (!validation.ok) {
     throw validation.error;
   }

package/source/shared/validations/Server/NotFoundHandler/index.mjs

@@ -13,6 +13,20 @@
 import Validation from '#shared/outcome/Validation';
 import ServerError from '#shared/errors/ServerError';
 
+// ━━ 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
+ */
+
 // ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
  * Validates a not-found handler.
@@ -21,7 +35,8 @@ import ServerError from '#shared/errors/ServerError';
  * `exchange`.
  *
  * @param {unknown} handler - Handler function to validate.
- * @returns {Validation} Validation result.
+ * @returns {SuccessValidation|FailureValidation<ServerError>} Validation result.
+ *
  * @example
  * ```js
  * const validation = validateNotFoundHandler((exchange) => {
@@ -42,31 +57,25 @@ import ServerError from '#shared/errors/ServerError';
  */
 export function validateNotFoundHandler(handler) {
   if (typeof handler !== 'function') {
-    return Validation.failure({
-      error: ServerError,
-      code: 'INVALID_NOT_FOUND_HANDLER_TYPE',
-      custom: true,
-      options: {
+    return Validation.failure(
+      new ServerError('INVALID_NOT_FOUND_HANDLER_TYPE', {
         values: {
           expected: 'function',
           received: typeof handler,
         },
-      },
-    });
+      }),
+    );
   }
 
   if (handler.length !== 1) {
-    return Validation.failure({
-      error: ServerError,
-      code: 'INVALID_NOT_FOUND_HANDLER_ARITY',
-      custom: true,
-      options: {
+    return Validation.failure(
+      new ServerError('INVALID_NOT_FOUND_HANDLER_ARITY', {
         values: {
           expected: 1,
           received: handler.length,
         },
-      },
-    });
+      }),
+    );
   }
 
   return Validation.success();
@@ -78,6 +87,7 @@ export function validateNotFoundHandler(handler) {
  * @param {unknown} handler - Handler function to validate.
  * @throws {ServerError} If the handler is not a function.
  * @throws {ServerError} If the handler does not declare exactly one parameter.
+ *
  * @example
  * ```js
  * assertNotFoundHandler((exchange) => {

package/source/shared/validations/Server/Router/index.mjs

@@ -13,12 +13,27 @@ import { ROUTER_BRAND } from '#shared/constants/symbols/brands';
 import Validation from '#shared/outcome/Validation';
 import ServerError from '#shared/errors/ServerError';
 
-// ━━ FUNCTIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// ━━ 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
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
  * Validates that a value implements the Router contract.
  *
  * @param {unknown} value - Value to validate.
- * @returns {Validation} Validation result.
+ * @returns {SuccessValidation|FailureValidation<ServerError>} Validation result.
+ *
  * @example
  * ```js
  * const validation = validateRouter(router);
@@ -29,21 +44,15 @@ import ServerError from '#shared/errors/ServerError';
  */
 export function validateRouter(value) {
   if (value === null || typeof value !== 'object') {
-    return Validation.failure({
-      error: ServerError,
-      message: `Expected a Router instance, received: ${value === null ? 'null' : typeof value}.`,
-      code: 'INVALID_ROUTER_TYPE',
-      custom: true,
-    });
+    return Validation.failure(
+      new ServerError('INVALID_ROUTER_TYPE', {
+        values: { received: value === null ? 'null' : typeof value },
+      }),
+    );
   }
 
   if (Reflect.get(value, ROUTER_BRAND) !== true) {
-    return Validation.failure({
-      error: ServerError,
-      message: 'Expected a Router instance.',
-      code: 'INVALID_ROUTER_INSTANCE',
-      custom: true,
-    });
+    return Validation.failure(new ServerError('INVALID_ROUTER_INSTANCE'));
   }
 
   return Validation.success();
@@ -54,6 +63,7 @@ export function validateRouter(value) {
  *
  * @param {unknown} value - Value to assert.
  * @throws {ServerError} If the value does not implement the Router contract.
+ *
  * @example
  * ```js
  * assertRouter(router);

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

@@ -13,12 +13,27 @@ import { SERVER_CONFIGURATION_BRAND } from '#shared/constants/symbols/brands';
 import Validation from '#shared/outcome/Validation';
 import ServerError from '#shared/errors/ServerError';
 
-// ━━ FUNCTIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// ━━ 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
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
  * Validates that a value implements the ServerConfiguration contract.
  *
  * @param {unknown} value - Value to validate.
- * @returns {Validation} Validation result.
+ * @returns {SuccessValidation|FailureValidation<ServerError>} Validation result.
+ *
  * @example
  * ```js
  * const validation = validateServerConfiguration(configuration);
@@ -29,21 +44,15 @@ import ServerError from '#shared/errors/ServerError';
  */
 export function validateServerConfiguration(value) {
   if (value === null || typeof value !== 'object') {
-    return Validation.failure({
-      error: ServerError,
-      message: `Expected a ServerConfiguration instance, received: ${value === null ? 'null' : typeof value}.`,
-      code: 'INVALID_SERVER_CONFIGURATION_TYPE',
-      custom: true,
-    });
+    return Validation.failure(
+      new ServerError('INVALID_SERVER_CONFIGURATION_TYPE', {
+        values: { received: value === null ? 'null' : typeof value },
+      }),
+    );
   }
 
   if (Reflect.get(value, SERVER_CONFIGURATION_BRAND) !== true) {
-    return Validation.failure({
-      error: ServerError,
-      message: 'Expected a ServerConfiguration instance.',
-      code: 'INVALID_SERVER_CONFIGURATION_INSTANCE',
-      custom: true,
-    });
+    return Validation.failure(new ServerError('INVALID_SERVER_CONFIGURATION_INSTANCE'));
   }
 
   return Validation.success();
@@ -54,6 +63,7 @@ export function validateServerConfiguration(value) {
  *
  * @param {unknown} value - Value to assert.
  * @throws {ServerError} If the value does not implement the ServerConfiguration contract.
+ *
  * @example
  * ```js
  * assertServerConfiguration(configuration);

package/source/shared/validations/Server/SystemErrorHandler/index.mjs

@@ -13,6 +13,20 @@
 import Validation from '#shared/outcome/Validation';
 import ServerError from '#shared/errors/ServerError';
 
+// ━━ 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
+ */
+
 // ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
  * Validates a system error handler.
@@ -21,7 +35,8 @@ import ServerError from '#shared/errors/ServerError';
  * parameters: `error` and `exchange`.
  *
  * @param {unknown} handler - Handler function to validate.
- * @returns {Validation} Validation result.
+ * @returns {SuccessValidation|FailureValidation<ServerError>} Validation result.
+ *
  * @example
  * ```js
  * const validation = validateSystemErrorHandler((error, exchange) => {
@@ -42,31 +57,25 @@ import ServerError from '#shared/errors/ServerError';
  */
 export function validateSystemErrorHandler(handler) {
   if (typeof handler !== 'function') {
-    return Validation.failure({
-      error: ServerError,
-      code: 'INVALID_SYSTEM_ERROR_HANDLER_TYPE',
-      custom: true,
-      options: {
+    return Validation.failure(
+      new ServerError('INVALID_SYSTEM_ERROR_HANDLER_TYPE', {
         values: {
           expected: 'function',
           received: typeof handler,
         },
-      },
-    });
+      }),
+    );
   }
 
   if (handler.length !== 2) {
-    return Validation.failure({
-      error: ServerError,
-      code: 'INVALID_SYSTEM_ERROR_HANDLER_ARITY',
-      custom: true,
-      options: {
+    return Validation.failure(
+      new ServerError('INVALID_SYSTEM_ERROR_HANDLER_ARITY', {
         values: {
           expected: 2,
           received: handler.length,
         },
-      },
-    });
+      }),
+    );
   }
 
   return Validation.success();
@@ -78,6 +87,7 @@ export function validateSystemErrorHandler(handler) {
  * @param {unknown} handler - Handler function to validate.
  * @throws {ServerError} If the handler is not a function.
  * @throws {ServerError} If the handler does not declare exactly two parameters.
+ *
  * @example
  * ```js
  * assertSystemErrorHandler((error, exchange) => {