prefeature: requires justification when throwing actionable errors (#282)

- before, all actionable errors that were thrown anyway were given the same boilerplate message
- now, it's more obvious that bypassing error handling warrants explicit justification

Author: bjacobgordon

src/library/Attempt/Outcome.ts

@@ -122,7 +122,7 @@ const failureDueTo = <
   isSuccess       : false,
   isFailure       : true,
   optionallyUnwrap: () => null,
-  forciblyUnwrap  : () => givenCause.throwAnyway(),
+  forciblyUnwrap  : () => givenCause.throwAnyway('Unexpected forceful unwrap of a failure'),
   causeOfFailure  : givenCause,
 });
 

src/library/Attempt/error/ActionableError.ts

@@ -12,13 +12,12 @@ abstract class ActionableError<SomeBrand extends string>
   implements Branded<SomeBrand> {
   public readonly brand!: SomeBrand;
 
-  public throwAnyway(): never {
-    return NonActionableError.throw(
-      'Implementation not specified for actionable error',
-      {
-        cause: this,
-      },
-    );
+  public throwAnyway(
+    givenJustification: string,
+  ): never {
+    return NonActionableError.throw(givenJustification, {
+      cause: this,
+    });
   }
 }
 

src/library/Attempt/error/modifier/SafelyPropagated.ts

@@ -16,11 +16,9 @@ export const assertSafelyPropagated = <
 >(
   givenError: SomePotentiallyActionableError,
 ): SafelyPropagated<SomePotentiallyActionableError> => {
-  // Propagated beyond confines of type system
-  // i.e. with raw `throw` instead of `.throwAnyway()` method
   if (
     givenError instanceof ActionableError
-  ) return givenError.throwAnyway();
+  ) return givenError.throwAnyway('Unexpected raw `throw` of some `ActionableError`. If this was intentional, use `.throwAnyway(...)` on the instance instead.');
 
   return givenError as SafelyPropagated<SomePotentiallyActionableError>;
 };

src/library/Base64/CharacterSequence/index.ts

@@ -7,7 +7,7 @@ const CharacterSequence_pattern = new RegExp(`^[${Base64_Alphabet.pattern.source
 const assertConformanceOf = (givenCharacterSequence: string): string => {
   if (
     !CharacterSequence_pattern.test(givenCharacterSequence)
-  ) return new Base64_CharacterSequence_ConformanceError().throwAnyway();
+  ) return new Base64_CharacterSequence_ConformanceError().throwAnyway('To be converted to `Attempt` failure');
 
   return givenCharacterSequence;
 };

src/library/Byte/Sequence/index.ts

@@ -16,7 +16,7 @@ const Byte_Sequence_assertEncodable = (
 
   if (
     givenSequence.length % byteCofactor !== 0
-  ) return new Byte_Sequence_EncodingCompatibilityError(givenBitWidth).throwAnyway();
+  ) return new Byte_Sequence_EncodingCompatibilityError(givenBitWidth).throwAnyway('To be converted to `Attempt` failure');
 
   return givenSequence;
 };

src/library/customTypes/NonTrivialString/index.ts

@@ -18,7 +18,7 @@ class NonTrivialString
 
     if (
       isEmpty(trimmedSubject)
-    ) return new NonTrivialString_ParsingError(givenSubject).throwAnyway();
+    ) return new NonTrivialString_ParsingError(givenSubject).throwAnyway('To be converted to `Attempt` failure');
 
     return new NonTrivialString(givenSubject);
   }

src/library/customTypes/URLComponent/URLOrigin.ts

@@ -29,7 +29,7 @@ class URLOrigin
     ) return new URLOrigin_ParsingError({
       expectation: derived.origin,
       reality    : givenSubject,
-    }).throwAnyway();
+    }).throwAnyway('To be converted to `Attempt` failure');
 
     return new URLOrigin(derived.origin);
   }

src/library/customTypes/URLComponent/URLPath.ts

@@ -29,7 +29,7 @@ class URLPath
     ) return new URLPath_ParsingError({
       expectation: exampleURL.pathname,
       reality    : givenSubject,
-    }).throwAnyway();
+    }).throwAnyway('To be converted to `Attempt` failure');
 
     return new URLPath(exampleURL.pathname);
   }

src/library/customTypes/UniformResourceIdentifier/Data/Image/index.ts

@@ -52,13 +52,13 @@ class ImageURI extends DataURI {
 
     if (
       proposedURI.mediaType.fileType !== ImageURI.mediaType
-    ) return new ImageURI_ParsingError(`Expected media type starting with ${ImageURI.mediaType}`).throwAnyway();
+    ) return new ImageURI_ParsingError(`Expected media type starting with ${ImageURI.mediaType}`).throwAnyway('To be converted to `Attempt` failure');
 
     const format = allImageURIFormats.find($0 => $0 === proposedURI.mediaType.fileSubtype);
 
     if (
       format === undefined
-    ) return new ImageURI_ParsingError(`Expected format to be one of ${allImageURIFormats.toString()}`).throwAnyway();
+    ) return new ImageURI_ParsingError(`Expected format to be one of ${allImageURIFormats.toString()}`).throwAnyway('To be converted to `Attempt` failure');
 
     return new ImageURI(
       format,

src/library/customTypes/UniformResourceIdentifier/Data/MediaType/index.ts

@@ -103,13 +103,13 @@ class MediaType implements StaticStringParser<typeof MediaType> {
 
     if (
       !isEmpty(componentsFollowingUnexpectedFileTypeSuffix)
-    ) return new MediaType_ParsingError(`Found component sets after extraneous file type suffix(es): ${componentsFollowingUnexpectedFileTypeSuffix.toString()}`).throwAnyway();
+    ) return new MediaType_ParsingError(`Found component sets after extraneous file type suffix(es): ${componentsFollowingUnexpectedFileTypeSuffix.toString()}`).throwAnyway('To be converted to `Attempt` failure');
 
     const fileType = allFileTypes.find($0 => $0 === rawFileType);
 
     if (
       fileType === undefined
-    ) return new MediaType_ParsingError(`Expected file type as one of ${allFileTypes.toString()}`).throwAnyway();
+    ) return new MediaType_ParsingError(`Expected file type as one of ${allFileTypes.toString()}`).throwAnyway('To be converted to `Attempt` failure');
 
     const [
       remainderBeforeParameters,
@@ -125,15 +125,15 @@ class MediaType implements StaticStringParser<typeof MediaType> {
 
       if (
         !isEmpty(extraneousComponentsInEachParameter)
-      ) return new MediaType_ParsingError(`Found extraneous components in parameter at index ${indexOfEachParameter.toString()}: ${extraneousComponentsInEachParameter.toString()}`).throwAnyway();
+      ) return new MediaType_ParsingError(`Found extraneous components in parameter at index ${indexOfEachParameter.toString()}: ${extraneousComponentsInEachParameter.toString()}`).throwAnyway('To be converted to `Attempt` failure');
 
       if (
         keyOfEachParameter === undefined
-      ) return new MediaType_ParsingError(`Expected key for parameter at index ${indexOfEachParameter.toString()}`).throwAnyway();
+      ) return new MediaType_ParsingError(`Expected key for parameter at index ${indexOfEachParameter.toString()}`).throwAnyway('To be converted to `Attempt` failure');
 
       if (
         valueOfEachParameter === undefined
-      ) return new MediaType_ParsingError(`Expected value for parameter at index ${indexOfEachParameter.toString()}`).throwAnyway();
+      ) return new MediaType_ParsingError(`Expected value for parameter at index ${indexOfEachParameter.toString()}`).throwAnyway('To be converted to `Attempt` failure');
 
       return [
         keyOfEachParameter,
@@ -149,7 +149,7 @@ class MediaType implements StaticStringParser<typeof MediaType> {
 
     if (
       !isEmpty(extraComponentsWithStructureTypePrefix)
-    ) return new MediaType_ParsingError(`Unexpected component sets after extraneous structure type prefix(es): ${extraComponentsWithStructureTypePrefix.toString()}`).throwAnyway();
+    ) return new MediaType_ParsingError(`Unexpected component sets after extraneous structure type prefix(es): ${extraComponentsWithStructureTypePrefix.toString()}`).throwAnyway('To be converted to `Attempt` failure');
 
     const structureType = (() => {
       if (rawStructureType === undefined) return null;
@@ -158,22 +158,22 @@ class MediaType implements StaticStringParser<typeof MediaType> {
 
       if (
         potentialStructureType === undefined
-      ) return new MediaType_ParsingError(`Expected structure type as one of ${allStructuredSyntaxNameSuffix.toString()}`).throwAnyway();
+      ) return new MediaType_ParsingError(`Expected structure type as one of ${allStructuredSyntaxNameSuffix.toString()}`).throwAnyway('To be converted to `Attempt` failure');
 
       return potentialStructureType;
     })();
 
     if (
       serializedTreeBranchesEndingInFileSubtype === undefined
-    ) return new MediaType_ParsingError('Expected file subtype').throwAnyway();
+    ) return new MediaType_ParsingError('Expected file subtype').throwAnyway('To be converted to `Attempt` failure');
 
     const treeBranchesEndingInFileSubtype = serializedTreeBranchesEndingInFileSubtype.split(MediaType.treeBranchSuffix);
     const reversedTreeBranchesBeginningWithFileSubtype = treeBranchesEndingInFileSubtype.reverse();
     const fileSubtype = reversedTreeBranchesBeginningWithFileSubtype.shift();
 
     if (
       fileSubtype === undefined
-    ) return new MediaType_ParsingError('Expected file subtype').throwAnyway();
+    ) return new MediaType_ParsingError('Expected file subtype').throwAnyway('To be converted to `Attempt` failure');
 
     const tree = reversedTreeBranchesBeginningWithFileSubtype.reverse();