improve error message to enhance readability

  fixed: #36

Author: mohayonao

src/AudioBuffer.js

@@ -56,10 +56,11 @@ export default class AudioBuffer {
   @methods.contract({
     precondition(channel) {
       if (this._.data.length <= channel) {
-        throw new TypeError(`channel index (${channel}) exceeds number of channels (${this._.data.length})`);
+        throw new TypeError(`The {{channel}} index (${channel}) exceeds number of channels (${this._.data.length}).`);
       }
     }
   })
+  @methods.returns(validators.isInstanceOf(Float32Array))
   getChannelData(channel) {
     return this._.data[channel];
   }
@@ -69,11 +70,11 @@ export default class AudioBuffer {
   @methods.param("[ startInChannel ]", validators.isPositiveInteger)
   @methods.contract({
     precondition(destination, channelNumber, startInChannel = 0) {
-      if (channelNumber < 0 || this._.data.length <= channelNumber) {
-        throw new TypeError(`The channelNumber provided (${channelNumber}) is outside the range [0, ${this._.data.length})`);
+      if (this._.data.length <= channelNumber) {
+        throw new TypeError(`The {{channelNumber}} provided (${channelNumber}) is outside the range [0, ${this._.data.length}).`);
       }
-      if (startInChannel < 0 || this._.length <= startInChannel) {
-        throw new TypeError(`The startInChannel provided (${startInChannel}) is outside the range [0, ${this._.length}).`);
+      if (this._.length <= startInChannel) {
+        throw new TypeError(`The {{startInChannel}} provided (${startInChannel}) is outside the range [0, ${this._.length}).`);
       }
       if (configuration.getState("AudioBuffer#copyFromChannel") !== "enabled") {
         throw new TypeError("not enabled");
@@ -91,11 +92,11 @@ export default class AudioBuffer {
   @methods.param("[ startInChannel ]", validators.isPositiveInteger)
   @methods.contract({
     precondition(source, channelNumber, startInChannel = 0) {
-      if (channelNumber < 0 || this._.data.length <= channelNumber) {
-        throw new TypeError(`The channelNumber provided (${channelNumber}) is outside the range [0, ${this._.data.length})`);
+      if (this._.data.length <= channelNumber) {
+        throw new TypeError(`The {{channelNumber}} provided (${channelNumber}) is outside the range [0, ${this._.data.length}).`);
       }
-      if (startInChannel < 0 || this._.length <= startInChannel) {
-        throw new TypeError(`The startInChannel provided (${startInChannel}) is outside the range [0, ${this._.length}).`);
+      if (this._.length <= startInChannel) {
+        throw new TypeError(`The {{startInChannel}} provided (${startInChannel}) is outside the range [0, ${this._.length}).`);
       }
       if (configuration.getState("AudioBuffer#copyToChannel") !== "enabled") {
         throw new TypeError("not enabled");

src/AudioBufferSourceNode.js

@@ -52,7 +52,7 @@ export default class AudioBufferSourceNode extends AudioNode {
   @methods.contract({
     precondition() {
       if (this._.startTime !== Infinity) {
-        throw new TypeError("cannot start more than once");
+        throw new TypeError("Cannot start more than once.");
       }
     }
   })
@@ -66,10 +66,10 @@ export default class AudioBufferSourceNode extends AudioNode {
   @methods.contract({
     precondition() {
       if (this._.startTime === Infinity) {
-        throw new TypeError("cannot call stop without calling start first");
+        throw new TypeError("Cannot call stop without calling start first.");
       }
       if (this._.stopTime !== Infinity) {
-        throw new TypeError("cannot stop more than once");
+        throw new TypeError("Cannot stop more than once.");
       }
     }
   })

src/AudioContext.js

@@ -2,6 +2,8 @@ import Configuration from "./utils/Configuration";
 import Immigration from "./utils/Immigration";
 import Event from "./dom/Event";
 import EventTarget from "./dom/EventTarget";
+import HTMLMediaElement from "./dom/HTMLMediaElement";
+import MediaStream from "./dom/MediaStream";
 import AudioBuffer from "./AudioBuffer";
 import AnalyserNode from "./AnalyserNode";
 import AudioBufferSourceNode from "./AudioBufferSourceNode";
@@ -98,6 +100,7 @@ export default class AudioContext extends EventTarget {
   @props.on("statechange")
   onstatechange() {}
 
+  @methods.returns(validators.isInstanceOf(Promise))
   suspend() {
     return this.__transitionToState("suspend", () => {
       if (this._.state === "running") {
@@ -107,6 +110,7 @@ export default class AudioContext extends EventTarget {
     });
   }
 
+  @methods.returns(validators.isInstanceOf(Promise))
   resume() {
     return this.__transitionToState("resume", () => {
       if (this._.state === "suspended") {
@@ -116,6 +120,7 @@ export default class AudioContext extends EventTarget {
     });
   }
 
+  @methods.returns(validators.isInstanceOf(Promise))
   close() {
     return this.__transitionToState("close", () => {
       if (this._.state !== "closed") {
@@ -129,6 +134,7 @@ export default class AudioContext extends EventTarget {
   @methods.param("numberOfChannels", validators.isPositiveInteger)
   @methods.param("length", validators.isPositiveInteger)
   @methods.param("sampleRate", validators.isPositiveInteger)
+  @methods.returns(validators.isInstanceOf(AudioBuffer))
   createBuffer(numberOfChannels, length, sampleRate) {
     return immigration.apply(admission =>
       new AudioBuffer(admission, this, numberOfChannels, length, sampleRate)
@@ -165,24 +171,30 @@ export default class AudioContext extends EventTarget {
     }
   }
 
+  @methods.returns(validators.isInstanceOf(AudioBufferSourceNode))
   createBufferSource() {
     return immigration.apply(admission =>
       new AudioBufferSourceNode(admission, this)
     );
   }
 
+  @methods.param("mediaElement", validators.isInstanceOf(HTMLMediaElement))
+  @methods.returns(validators.isInstanceOf(MediaElementAudioSourceNode))
   createMediaElementSource(mediaElement) {
     return immigration.apply(admission =>
       new MediaElementAudioSourceNode(admission, this, mediaElement)
     );
   }
 
+  @methods.param("mediaStream", validators.isInstanceOf(MediaStream))
+  @methods.returns(validators.isInstanceOf(MediaStreamAudioSourceNode))
   createMediaStreamSource(mediaStream) {
     return immigration.apply(admission =>
       new MediaStreamAudioSourceNode(admission, this, mediaStream)
     );
   }
 
+  @methods.returns(validators.isInstanceOf(MediaStreamAudioDestinationNode))
   createMediaStreamDestination() {
     return immigration.apply(admission =>
       new MediaStreamAudioDestinationNode(admission, this)
@@ -199,43 +211,50 @@ export default class AudioContext extends EventTarget {
   @methods.param("bufferSize", validators.isPositiveInteger)
   @methods.param("[ numberOfInputChannels ]", validators.isPositiveInteger)
   @methods.param("[ numberOfOutputChannels ]", validators.isPositiveInteger)
+  @methods.returns(validators.isInstanceOf(ScriptProcessorNode))
   createScriptProcessor(bufferSize, numberOfInputChannels = 2, numberOfOutputChannels = 2) {
     return immigration.apply(admission =>
       new ScriptProcessorNode(admission, this, bufferSize, numberOfInputChannels, numberOfOutputChannels)
     );
   }
 
+  @methods.returns(validators.isInstanceOf(AnalyserNode))
   createAnalyser() {
     return immigration.apply(admission =>
       new AnalyserNode(admission, this)
     );
   }
 
+  @methods.returns(validators.isInstanceOf(GainNode))
   createGain() {
     return immigration.apply(admission =>
       new GainNode(admission, this)
     );
   }
 
   @methods.param("[ maxDelayTime ]", validators.isPositiveNumber)
+  @methods.returns(validators.isInstanceOf(DelayNode))
   createDelay(maxDelayTime = 1) {
     return immigration.apply(admission =>
       new DelayNode(admission, this, maxDelayTime)
     );
   }
 
+  @methods.returns(validators.isInstanceOf(BiquadFilterNode))
   createBiquadFilter() {
     return immigration.apply(admission =>
       new BiquadFilterNode(admission, this)
     );
   }
 
+  @methods.returns(validators.isInstanceOf(WaveShaperNode))
   createWaveShaper() {
     return immigration.apply(admission =>
       new WaveShaperNode(admission, this)
     );
   }
 
+  @methods.returns(validators.isInstanceOf(PannerNode))
   createPanner() {
     return immigration.apply(admission =>
       new PannerNode(admission, this)
@@ -249,38 +268,44 @@ export default class AudioContext extends EventTarget {
       }
     }
   })
+  @methods.returns(validators.isInstanceOf(StereoPannerNode))
   createStereoPanner() {
     return immigration.apply(admission =>
       new StereoPannerNode(admission, this)
     );
   }
 
+  @methods.returns(validators.isInstanceOf(ConvolverNode))
   createConvolver() {
     return immigration.apply(admission =>
       new ConvolverNode(admission, this)
     );
   }
 
   @methods.param("[ numberOfOutputs ]", validators.isPositiveInteger)
+  @methods.returns(validators.isInstanceOf(ChannelSplitterNode))
   createChannelSplitter(numberOfOutputs = 6) {
     return immigration.apply(admission =>
       new ChannelSplitterNode(admission, this, numberOfOutputs)
     );
   }
 
   @methods.param("[ numberOfInputs ]", validators.isPositiveInteger)
+  @methods.returns(validators.isInstanceOf(ChannelMergerNode))
   createChannelMerger(numberOfInputs = 6) {
     return immigration.apply(admission =>
       new ChannelMergerNode(admission, this, numberOfInputs)
     );
   }
 
+  @methods.returns(validators.isInstanceOf(DynamicsCompressorNode))
   createDynamicsCompressor() {
     return immigration.apply(admission =>
       new DynamicsCompressorNode(admission, this)
     );
   }
 
+  @methods.returns(validators.isInstanceOf(OscillatorNode))
   createOscillator() {
     return immigration.apply(admission =>
       new OscillatorNode(admission, this)
@@ -289,6 +314,7 @@ export default class AudioContext extends EventTarget {
 
   @methods.param("real", validators.isInstanceOf(Float32Array))
   @methods.param("imag", validators.isInstanceOf(Float32Array))
+  @methods.returns(validators.isInstanceOf(PeriodicWave))
   createPeriodicWave(real, imag) {
     return immigration.apply(admission =>
       new PeriodicWave(admission, this, real, imag)
@@ -305,7 +331,7 @@ export default class AudioContext extends EventTarget {
   __transitionToState(methodName, callback) {
     return new Promise((resolve) => {
       if (this._.state === "close") {
-        throw new TypeError(`Cannot ${methodName} a context that is being closed or has already been closed`);
+        throw new TypeError(`Cannot ${methodName} a context that is being closed or has already been closed.`);
       }
       callback();
       resolve();

src/AudioNode.js

@@ -76,13 +76,13 @@ export default class AudioNode extends EventTarget {
   @methods.contract({
     precondition(destination, output = 0, input = 0) {
       if (this.$context !== destination.$context) {
-        throw new TypeError(`cannot connect to a destination belonging to a different audio context`);
+        throw new TypeError("Cannot connect to a destination belonging to a different AudioContext.");
       }
       if (this.numberOfOutputs <= output) {
-        throw new TypeError(`output index (${output}) exceeds number of outputs (${this.numberOfOutputs})`);
+        throw new TypeError(`The {{output}} index (${output}) exceeds number of outputs (${this.numberOfOutputs}).`);
       }
       if ((destination.numberOfInputs || 1) <= input) {
-        throw new TypeError(`input index (${input}) exceeds number of inputs (${destination.numberOfInputs})`);
+        throw new TypeError(`The {{input}} index (${input}) exceeds number of inputs (${destination.numberOfInputs}).`);
       }
     }
   })
@@ -122,7 +122,7 @@ export default class AudioNode extends EventTarget {
   @methods.contract({
     precondition(output) {
       if (this.numberOfOutputs <= output) {
-        throw new TypeError(`output index (${output}) exceeds number of outputs (${this.numberOfOutputs})`);
+        throw new TypeError(`The {{output}} index (${output}) exceeds number of outputs (${this.numberOfOutputs}).`);
       }
     }
   })
@@ -134,7 +134,7 @@ export default class AudioNode extends EventTarget {
   @methods.contract({
     precondition(destination) {
       if (!this._.outputs.some(junction => junction.isConnected(destination))) {
-        throw new TypeError("the given destination is not connected");
+        throw new TypeError("The given {{destination}} is not connected.");
       }
     }
   })
@@ -149,10 +149,10 @@ export default class AudioNode extends EventTarget {
   @methods.contract({
     precondition(destination, output) {
       if (!this._.outputs.some(junction => junction.isConnected(destination))) {
-        throw new TypeError("the given destination is not connected");
+        throw new TypeError("The given {{destination}} is not connected.");
       }
-      if (output < 0 || this.numberOfOutputs <= output) {
-        throw new TypeError(`output provided (${output}) is outside the range [0, ${this.numberOfOutputs})`);
+      if (this.numberOfOutputs <= output) {
+        throw new TypeError(`The {{output}} provided (${output}) is outside the range [0, ${this.numberOfOutputs}).`);
       }
     }
   })
@@ -166,13 +166,13 @@ export default class AudioNode extends EventTarget {
   @methods.contract({
     precondition(destination, output, input) {
       if (!this._.outputs.some(junction => junction.isConnected(destination))) {
-        throw new TypeError("the given destination is not connected");
+        throw new TypeError("The given {{destination}} is not connected.");
       }
       if (output < 0 || this.numberOfOutputs <= output) {
-        throw new TypeError(`output provided (${output}) is outside the range [0, ${this.numberOfOutputs})`);
+        throw new TypeError(`The {{output}} provided (${output}) is outside the range [0, ${this.numberOfOutputs}).`);
       }
       if (input < 0 || destination.numberOfInputs <= input) {
-        throw new TypeError(`input provided (${input}) is outside the range [0, ${this.numberOfInputs})`);
+        throw new TypeError(`The {{input}} provided (${input}) is outside the range [0, ${this.numberOfInputs}).`);
       }
     }
   })

src/OfflineAudioContext.js

@@ -47,7 +47,7 @@ export default class OfflineAudioContext extends AudioContext {
   @methods.contract({
     precondition() {
       if (this._.rendering) {
-        throw new TypeError("cannot call startRendering more than once");
+        throw new TypeError("Cannot call startRendering more than once.");
       }
     }
   })
@@ -77,7 +77,7 @@ export default class OfflineAudioContext extends AudioContext {
   })
   __transitionToState(methodName) {
     return new Promise(() => {
-      throw new TypeError(`Cannot ${methodName} on an OfflineAudioContext`);
+      throw new TypeError(`Cannot ${methodName} on an OfflineAudioContext.`);
     });
   }
 

src/OscillatorNode.js

@@ -41,7 +41,7 @@ export default class OscillatorNode extends AudioNode {
   @methods.contract({
     precondition() {
       if (this._.startTime !== Infinity) {
-        throw new Error(`cannot start more than once`);
+        throw new Error("Cannot start more than once.");
       }
     }
   })
@@ -53,10 +53,10 @@ export default class OscillatorNode extends AudioNode {
   @methods.contract({
     precondition() {
       if (this._.startTime === Infinity) {
-        throw new Error(`cannot call stop without calling start first`);
+        throw new Error("Cannot call stop without calling start first.");
       }
       if (this._.stopTime !== Infinity) {
-        throw new Error(`cannot stop more than once`);
+        throw new Error("Cannot stop more than once.");
       }
     }
   })

src/PeriodicWave.js

@@ -20,13 +20,13 @@ export default class PeriodicWave {
   @methods.contract({
     precondition(real, imag) {
       if (4096 < real.length) {
-        throw new TypeError(`length of "real" array (${real.length}) exceeds allow maximum of 4096`);
+        throw new TypeError(`The length of "{{real}}" array (${real.length}) exceeds allow maximum of 4096.`);
       }
       if (4096 < imag.length) {
-        throw new TypeError(`length of "imag" array (${imag.length}) exceeds allow maximum of 4096`);
+        throw new TypeError(`The length of "{{imag}}" array (${imag.length}) exceeds allow maximum of 4096.`);
       }
       if (real.length !== imag.length) {
-        throw new TypeError(`length of real array (${real.length}) and length of imaginary array (${imag.length}) must match`);
+        throw new TypeError(`The length of "{{real}}" array (${real.length}) and length of "imag" array (${imag.length}) must match.`);
       }
     }
   })

src/ScriptProcessorNode.js

@@ -30,7 +30,7 @@ export default class ScriptProcessorNode extends AudioNode {
   @methods.contract({
     precondition(bufferSize) {
       if ([ 256, 512, 1024, 2048, 4096, 8192, 16384 ].indexOf(bufferSize) === -1) {
-        throw new TypeError(`bufferSize should be an enum [ 256, 512, 1024, 2048, 4096, 8192, 16384 ], but got ${bufferSize}`);
+        throw new TypeError(`The {{bufferSize}} should be one of [ 256, 512, 1024, 2048, 4096, 8192, 16384 ], but got ${bufferSize}.`);
       }
     }
   })