prefeature: requires justification when throwing actionable errors

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();
 

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

@@ -75,7 +75,7 @@ class DataURI extends UniformResourceIdentifier {
 
     if (
       !proposedURI.scheme.isEqualTo(DataURI.scheme)
-    ) return new DataURI_ParsingError(`Expected scheme to be "${DataURI.scheme.toString()}"`).throwAnyway();
+    ) return new DataURI_ParsingError(`Expected scheme to be "${DataURI.scheme.toString()}"`).throwAnyway('To be converted to `Attempt` failure');
 
     const [
       mediaTypeAndEncoding,
@@ -85,11 +85,11 @@ class DataURI extends UniformResourceIdentifier {
 
     if (
       !isEmpty(extraComponentsWithDataPrefix)
-    ) return new DataURI_ParsingError(`Unexpected components with data prefix: ${extraComponentsWithDataPrefix.toString()}`).throwAnyway();
+    ) return new DataURI_ParsingError(`Unexpected components with data prefix: ${extraComponentsWithDataPrefix.toString()}`).throwAnyway('To be converted to `Attempt` failure');
 
     if (
       rawData === undefined
-    ) return new DataURI_ParsingError('Expected data portion to be defined').throwAnyway();
+    ) return new DataURI_ParsingError('Expected data portion to be defined').throwAnyway('To be converted to `Attempt` failure');
 
     const [
       rawMediaType,
@@ -99,17 +99,17 @@ class DataURI extends UniformResourceIdentifier {
 
     if (
       !isEmpty(extraComponentsWithEncodingPrefix)
-    ) return new DataURI_ParsingError(`Unexpected components with encoding prefix: ${extraComponentsWithEncodingPrefix.toString()}`).throwAnyway();
+    ) return new DataURI_ParsingError(`Unexpected components with encoding prefix: ${extraComponentsWithEncodingPrefix.toString()}`).throwAnyway('To be converted to `Attempt` failure');
 
     if (
       rawMediaType === undefined
-    ) return new DataURI_ParsingError('Expected `mediaType` portion to be defined').throwAnyway();
+    ) return new DataURI_ParsingError('Expected `mediaType` portion to be defined').throwAnyway('To be converted to `Attempt` failure');
 
     const coercedEncoding = allDataURIBinaryEncodings.find($0 => $0 === rawEncoding);
 
     if (
       coercedEncoding === undefined
-    ) return new DataURI_ParsingError(`Expected encoding portion to be defined as one of: ${allDataURIBinaryEncodings.toString()}`).throwAnyway();
+    ) return new DataURI_ParsingError(`Expected encoding portion to be defined as one of: ${allDataURIBinaryEncodings.toString()}`).throwAnyway('To be converted to `Attempt` failure');
 
     return new DataURI(
       MediaType.forciblyParsedFrom(rawMediaType),

src/library/customTypes/UniformResourceIdentifier/index.ts

@@ -116,11 +116,11 @@ class UniformResourceIdentifier implements StaticStringParser<typeof UniformReso
 
     if (
       !isEmpty(componentsFollowingUnexpectedSchemeSuffix)
-    ) return new URI_ParsingError(`Found components with extra scheme suffix: ${componentsFollowingUnexpectedSchemeSuffix.join()}`).throwAnyway();
+    ) return new URI_ParsingError(`Found components with extra scheme suffix: ${componentsFollowingUnexpectedSchemeSuffix.join()}`).throwAnyway('To be converted to `Attempt` failure');
 
     if (
       scheme === undefined
-    ) return new URI_ParsingError('Expected a scheme').throwAnyway();
+    ) return new URI_ParsingError('Expected a scheme').throwAnyway('To be converted to `Attempt` failure');
 
     const [
       componentsPrecedingFragment,
@@ -130,7 +130,7 @@ class UniformResourceIdentifier implements StaticStringParser<typeof UniformReso
 
     if (
       !isEmpty(unexpectedComponentsWithFragmentPrefix)
-    ) return new URI_ParsingError(`Found extra components with fragment prefix: ${unexpectedComponentsWithFragmentPrefix.join()}`).throwAnyway();
+    ) return new URI_ParsingError(`Found extra components with fragment prefix: ${unexpectedComponentsWithFragmentPrefix.join()}`).throwAnyway('To be converted to `Attempt` failure');
 
     const [
       componentsPrecedingQuery,
@@ -140,11 +140,11 @@ class UniformResourceIdentifier implements StaticStringParser<typeof UniformReso
 
     if (
       !isEmpty(unexpectedComponentsWithQueryPrefix)
-    ) return new URI_ParsingError(`Found extra components with query prefix: ${unexpectedComponentsWithQueryPrefix.join()}`).throwAnyway();
+    ) return new URI_ParsingError(`Found extra components with query prefix: ${unexpectedComponentsWithQueryPrefix.join()}`).throwAnyway('To be converted to `Attempt` failure');
 
     if (
       componentsPrecedingQuery === undefined
-    ) return new URI_ParsingError('Expected components preceding query').throwAnyway();
+    ) return new URI_ParsingError('Expected components preceding query').throwAnyway('To be converted to `Attempt` failure');
 
     const pathSegmentDelimiter = '/';
 
@@ -176,7 +176,7 @@ class UniformResourceIdentifier implements StaticStringParser<typeof UniformReso
 
       if (
         authority === undefined
-      ) return new URI_ParsingError('Expected to find authority between its prefix and the path segments').throwAnyway();
+      ) return new URI_ParsingError('Expected to find authority between its prefix and the path segments').throwAnyway('To be converted to `Attempt` failure');
 
       return {
         authority,