Stage 1 Draft / February 8, 2024

Error Stacks

1 System

1.1 System.getStack ( error )

When the getStack method is called with argument error, the following steps are taken:

  1. If error does not have an [[ErrorData]] internal slot, throw a TypeError exception.
  2. Return ? GetStack(error).

1.2 System.getStackString ( error )

When the getStackString method is called with argument error, the following steps are taken:

  1. If error does not have an [[ErrorData]] internal slot, throw a TypeError exception.
  2. Return ? GetStackString(error).

2 GetStack ( error )

When the abstract operation GetStack is called with argument error, the following steps are performed:

  1. Assert: error has an [[ErrorData]] internal slot.
  2. Let frames be ! GetStackFrames(error).
  3. Let string be ? GetStackString(error).
  4. Let obj be OrdinaryObjectCreate(%ObjectPrototype%).
  5. Perform ! CreateDataProperty(obj, "frames", frames).
  6. Assert: The above CreateDataProperty operation returns true.
  7. Perform ! CreateDataProperty(obj, "string", string).
  8. Assert: The above CreateDataProperty operation returns true.
  9. Let status be ! SetIntegrityLevel(obj, frozen).
  10. Assert: status is true.
  11. Return obj.

3 GetStackString ( error )

When the abstract operation GetStackString is called with argument error, the following steps are performed:

  1. Assert: error has an [[ErrorData]] internal slot.
  2. Let errorString be ? Call(%Error.prototype.toString%, error).
  3. Let frames be ! GetStackFrames(error).
  4. Let frameString be a String consisting solely of the code unit 0x0020 (SPACE).
  5. For each Stack Frame frame in frames, do
    1. If frameString does not consist solely of the code unit 0x0020 (SPACE), then
      1. Set frameString to the string-concatenation of frameString, the code unit 0x000A (LINE FEED), and the code unit 0x0020 (SPACE).
    2. Set frameString to the string-concatenation of frameString and ! GetFrameString(frame).
  6. Return the string-concatenation of errorString, the code unit 0x000A (LINE FEED), and frameString.

4 GetFrameString ( frame )

When the abstract operation GetFrameString is called with argument frame, the following steps are performed:

  1. Assert: ! IsStackFrame(frame) is true.
  2. Let source be frame.[[Source]].
  3. If source is not a String, then
    1. Assert: ! IsStackFrame(source) is true.
    2. Set source to the string-concatenation of "eval" and ! GetFrameString(source).
  4. Assert: source is a String.
  5. Let spanString be ! GetStackFrameSpanString(frame.[[Span]]).
  6. Return the string-concatenation of the code unit 0x0020 (SPACE), "at", the code unit 0x0020 (SPACE), frame.[[Name]], the code unit 0x0020 (SPACE), and "(", source, spanString, and ")".

5 GetStackFrameSpanString ( span )

When the abstract operation GetStackFrameSpanString is called with argument span, the following steps are performed:

  1. Assert: ! IsStackFrameSpan(span) is true.
  2. Let spanString be ! GetStackFramePositionString(span.[[StartPosition]]).
  3. If span has an [[EndPosition]] internal slot, then
    1. Set spanString to the string-concatenation of spanString, "::", and ! GetStackFramePositionString(span.[[EndPosition]]).
  4. Return spanString.

6 GetStackFramePositionString ( position )

When the abstract operation GetStackFramePositionString is called with argument position, the following steps are performed:

  1. Assert: ! IsStackFramePosition(position) is true.
  2. Let positionString be ! ToString(position.[[Line]]).
  3. If position has a [[Column]] internal slot, then
    1. Set positionString to the string-concatenation of positionString, ":", and ! ToString(position.[[Column]]).
  4. Return positionString.

7 GetStackFrames ( error )

When the abstract operation GetStackFrames is called with argument error, the following steps are performed:

  1. Assert: error has an [[ErrorData]] internal slot.
  2. Let frames be a new empty List.
  3. For each Stack Frame frame in error.[[ErrorData]], do
    1. Append ! FromStackFrame(frame) to frames.
  4. Let array be CreateArrayFromList(frames).
  5. Let status be ! SetIntegrityLevel(array, frozen).
  6. Assert: status is true.
  7. Return array.

8 The Stack Frame Specification Type

8.1 IsStackFrame ( frame )

When the abstract operation IsStackFrame is called with Stack Frame frame, the following steps are performed:

  1. If Type(frame) is not Object, return false.
  2. If frame does not have a [[Name]] internal slot, return false.
  3. If frame does not have a [[Source]] internal slot, return false.
  4. If frame does not have a [[Span]] internal slot, return false.
  5. If frame.[[Name]] is not a String, return false.
  6. If frame.[[Source]] is not a String, and ! IsStackFrame(frame.[[Source]]) is not true, return false.
  7. If ! IsStackFrameSpan(frame.[[Span]]) is not true, return false.
  8. Return true.

8.2 IsStackFrameSpan ( span )

When the abstract operation IsStackFrameSpan is called with argument span, the following steps are performed:

  1. If Type(span) is not Object, return false.
  2. If span does not have a [[StartPosition]] internal slot, return false.
  3. If ! IsStackFramePosition(span.[[StartPosition]]) is not true, return false.
  4. If span has an [[EndPosition]] internal slot, then
    1. If ! IsStackFramePosition(span.[[EndPosition]]) is not true, return false.
  5. Return true.

8.3 IsStackFramePosition ( position )

When the abstract operation IsStackFramePosition is called with argument position, the following steps are performed:

  1. If Type(position) is not Object, return false.
  2. If position does not have a [[Line]] internal slot, return false.
  3. If position.[[Line]] is not a positive integer ≤ 253-1, return false.
  4. If position has a [[Column]] internal slot, then
    1. If position.[[Column]] is not 𝔽(0) or a positive integer ≤ 253-1, return false.
  5. Return true.

8.4 FromStackFrame ( frame )

When the abstract operation FromStackFrame is called with Stack Frame frame, the following steps are taken:

  1. Assert: ! IsStackFrame(frame) is true.
  2. Let obj be OrdinaryObjectCreate(%ObjectPrototype%).
  3. Assert: obj is an extensible ordinary object with no own properties.
  4. Perform ! CreateDataProperty(obj, "name", frame.[[Name]]).
  5. Let source be frame.[[Source]].
  6. If source is a String, then
    1. Perform ! CreateDataProperty(obj, "source", source).
  7. Else,
    1. Assert: ! IsStackFrame(source) is true.
    2. Perform ! CreateDataProperty(obj, "source", ! FromStackFrame(source)).
  8. Perform ! CreateDataProperty(obj, "span", ! FromStackFrameSpan(frame.[[Span]])).
  9. Assert: All of the above CreateDataProperty operations return true.
  10. Let status be ! SetIntegrityLevel(obj, frozen).
  11. Assert: status is true.
  12. Return obj.

8.5 FromStackFrameSpan ( span )

When the abstract operation FromStackFrameSpan is called with argument span, the following steps are taken:

  1. Assert: ! IsStackFrameSpan(span) is true.
  2. Let list be a new empty List.
  3. Append ! FromStackFramePosition(span.[[StartPosition]]) to list.
  4. If span has an [[EndPosition]] internal slot, append ! FromStackFramePosition(span.[[EndPosition]]) to list.
  5. Let array be CreateArrayFromList(list).
  6. Let status be ! SetIntegrityLevel(array, frozen).
  7. Assert: status is true.
  8. Return array.

8.6 FromStackFramePosition ( position )

When the abstract operation FromStackFramePosition is called with argument position, the following steps are taken:

  1. Assert: ! IsStackFramePosition(position) is true.
  2. Let list be a new empty List.
  3. Append position.[[Line]] to list.
  4. If position has a [[Column]] internal slot, append position.[[Column]] to list.
  5. Let array be CreateArrayFromList(list).
  6. Let status be ! SetIntegrityLevel(array, frozen).
  7. Assert: status is true.
  8. Return array.

A Placeholder to ensure correct annex lettering

B Additional Built-in Properties

When the ECMAScript host is a web browser the following additional properties of the standard built-in objects are defined.

B.1 Additional Properties of the Error.prototype Object

B.1.1 get Error.prototype.stack ( )

Error.prototype.stack is an accessor property whose get accessor function performs the following steps:

  1. Let E be the this value.
  2. If Type(E) is not Object, throw a TypeError exception.
  3. If E does not have an [[ErrorData]] internal slot, return undefined.
  4. Return ? GetStackString(error).

The value of the "name" property of this function is "get stack".

B.1.2 set Error.prototype.stack ( value )

Its set accessor function performs the following steps:

  1. Let E be the this value.
  2. If Type(E) is not Object, throw a TypeError exception.
  3. Let numberOfArgs be the number of arguments passed to this function call.
  4. If numberOfArgs is 0, throw a TypeError exception.
  5. Return ? CreateDataPropertyOrThrow(E, "stack", value).

The value of the "name" property of this function is "set stack".

C Copyright & Software License

Copyright Notice

© 2024 Jordan Harband, Mark Miller

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.