Skip to content

util: inspect ArrayBuffers TypedArray as well - #25006

Closed
BridgeAR wants to merge 2 commits into
nodejs:masterfrom
BridgeAR:inspect-array-buffer-closer
Closed

util: inspect ArrayBuffers TypedArray as well#25006
BridgeAR wants to merge 2 commits into
nodejs:masterfrom
BridgeAR:inspect-array-buffer-closer

Conversation

@BridgeAR

@BridgeARBridgeAR commented Dec 13, 2018•
edited
Loading

Copy link
Copy Markdown
Member

Inspecting an ArrayBuffer alone now also shows the Uint8Array to which the ArrayBuffer belongs to.

I visualized it as special property even though it's not a property. I have no strong opinion about that but it seemed like the best representation.

Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • tests and/or benchmarks are included
  • documentation is changed or added
  • commit message follows commit guidelines

@nodejs-github-bot

nodejs-github-bot commented Dec 13, 2018

Copy link
Copy Markdown
Collaborator

@BridgeAR build started: https://ci.nodejs.org/blue/organizations/jenkins/node-test-pull-request-lite-pipeline/detail/node-test-pull-request-lite-pipeline/1919/pipeline

@nodejs-github-botnodejs-github-bot added the util Issues and PRs related to the built-in util module. label Dec 13, 2018
@BridgeARBridgeAR added the semver-minor PRs that contain new features and should be released in the next minor version. label Dec 13, 2018
@targos

targos commented Dec 13, 2018

Copy link
Copy Markdown
Member

I find this very confusing. ArrayBuffers don't have an underlying Uint8Array, it's the opposite.

@BridgeAR

BridgeAR commented Dec 13, 2018

Copy link
Copy Markdown
MemberAuthor

@targos yes, I described it wrong. The point is, that inspecting two different ArrayBuffer directly can result in the same output while belonging to a very different TypedArray. This makes sure it's clear to the viewer.

I am also happy with a different representation but this was the best I could come up with.

@BridgeAR

BridgeAR commented Dec 13, 2018

Copy link
Copy Markdown
MemberAuthor

An alternative representations I thought about was:

ArrayBuffer { byteLength: n } [Uint8Array] [...]

addaleax
addaleax reviewed Dec 13, 2018
View reviewed changes
Comment threaddoc/api/util.md Outdated
@BridgeAR

BridgeAR commented Dec 13, 2018

Copy link
Copy Markdown
MemberAuthor

CI https://ci.nodejs.org/job/node-test-pull-request/19480/

@BridgeAR

BridgeAR commented Dec 14, 2018

Copy link
Copy Markdown
MemberAuthor

@nodejs/util PTAL

@targos

targos commented Dec 15, 2018•
edited
Loading

Copy link
Copy Markdown
Member

Since ArrayBuffers are the data holders for all typed arrays, I don't think it's a good idea to show the contents as Uint8Array. How about we do the same as with Node's Buffers and display it in hexadecimal form?
I'm also fine with the current state of things. It's easy enough to wrap the ArrayBuffer in any typed array to have the desired output.

@BridgeAR

BridgeAR commented Dec 16, 2018

Copy link
Copy Markdown
MemberAuthor

@targos I am fine with using a hexadecimal representation but I am not sure how to name the "property" (description) in that case. I could keep it as Uint8Array but it might be somewhat confusing that way?

About the current state: I think it's nice to see as much as possible right away but more important: it helps identifying different ArrayBuffers from each other right away. This also has impact on e.g. comparing two ArrayBuffers with assert as the error message could be is misleading until it's possible to distinguish them.

@BridgeAR

BridgeAR commented Dec 18, 2018

Copy link
Copy Markdown
MemberAuthor

@targos@addaleax what do you think of either of these representations (or any potential combination of some of these):

  1. 'ArrayBuffer { <Uint8BufferView 68 65 6c 6c 6f>, byteLength: 4 }'
  2. 'ArrayBuffer { <Uint8Array 68 65 6c 6c 6f>, byteLength: 4 }'
  3. 'ArrayBuffer { <ArrayBufferView (Uint8) 68 65 6c 6c 6f>, byteLength: 4 }'
  4. 'ArrayBuffer { [TypedArray]: <Uint8Array 68 65 6c 6c 6f>, byteLength: 4 }'
  5. 'ArrayBuffer { <ArrayBufferView 68 65 6c 6c 6f>, byteLength: 4 }'
  6. 'ArrayBuffer { [ArrayBufferView as base64]: 'aGVsbG8=', byteLength: 4 }'
  7. 'ArrayBuffer { <Base64 ArrayBufferView aGVsbG8>, byteLength: 4 }'

I personally think it's important to tell the user that it is represented as Uint8. In what way and with what other description is not really as important for me. Without that information it's hard to understand what the representation actually stands for.

@addaleax

addaleax commented Dec 18, 2018

Copy link
Copy Markdown
Member

@BridgeAR I think 2, 3, 4, 5, 6 are misleading because they imply an associated ArrayBufferView in one way or another that does not actually exist. I think 6 and 7 are not useful, because base64 does not provide much visual information about the contents, only a way to reconstruct it.

I’d prefer for visual clutter/“specialness” to be minimal, so maybe a pseudo-property like [Uint8Contents]: <68 65 6c 6c 6f> would work?

I personally think it's important to tell the user that it is represented as Uint8.

I’m not sure I agree – we don’t do this for Buffers either, hex characters grouped in 2s are pretty much the standard representation for uint8 sequences, so it’s not really ambiguous.

@BridgeAR

BridgeAR commented Dec 18, 2018

Copy link
Copy Markdown
MemberAuthor

@addaleax

hex characters grouped in 2s are pretty much the standard representation for uint8 sequences, so it’s not really ambiguous

Sounds fine to me.

I’d prefer for visual clutter/“specialness” to be minimal

Coming from your suggestion, here's a new set of possibilities. I personally prefer 1 and 2 while not having a strong preference for either. I think 3 and 5 lack a description of the "value" (looking at it alone), otherwise I would also go for a pseudo property.

  1. 'ArrayBuffer { <Content 68 65 6c 6c 6f>, byteLength: 4 }'
  2. 'ArrayBuffer { <Uint8Content 68 65 6c 6c 6f>, byteLength: 4 }'
  3. 'ArrayBuffer { [Content]: <68 65 6c 6c 6f>, byteLength: 4 }'
  4. 'ArrayBuffer { [Content]: <Uint8 68 65 6c 6c 6f>, byteLength: 4 }'
  5. 'ArrayBuffer { [Uint8Content]: <68 65 6c 6c 6f>, byteLength: 4 }'

@targos

targos commented Dec 18, 2018

Copy link
Copy Markdown
Member

Alternatives: Data, Contents

@targos

targos commented Dec 19, 2018

Copy link
Copy Markdown
Member

/cc @nodejs/util

@addaleax

addaleax commented Dec 19, 2018

Copy link
Copy Markdown
Member

@BridgeAR I think my personal preferences would be 5, 3, 2, 1, but let’s see what others think :)

Re: content vs contents, maybe it’s best to leave that to a native speaker?

@BridgeAR

BridgeAR commented Dec 19, 2018

Copy link
Copy Markdown
MemberAuthor

@addaleax the difference between content and contents is AFAIK subtle and depends on if we see the contained information as a whole (content) or if we consider it to be separate parts of information (contents). But by all means: I should not be the person to decide this :D (and I am also fine to use Data).

@Trott@vsemozhetbyt would you two be so kind and have a look at this? :)

Thinking about it: we could maybe use a team (e.g. nodejs/native-english-speaker) for pinging people with a very good English language knowledge (ideally both, British and American English. I for example struggle that)?

@targos do you have a preference for the last suggestions?

@Trott

Trott commented Dec 22, 2018•
edited
Loading

Copy link
Copy Markdown
Member

@Trott@vsemozhetbyt would you two be so kind and have a look at this? :)

In this particular case, I think contents is slightly more appropriate than content, but either will do. https://dictionary.cambridge.org/us/grammar/british-grammar/content-or-contents is a pretty good explanation of the subtlety. content is something that is uncountable, whereas contents is something that is enumerable. So in this case, contents is better, but no one will think it sounds strange if you use content instead.

vsemozhetbyt
vsemozhetbyt reviewed Dec 23, 2018
View reviewed changes
Comment threaddoc/api/util.md Outdated
@BridgeAR
BridgeARforce-pushed the inspect-array-buffer-closer branch from a5100e0 to f58d87cCompareDecember 24, 2018 00:04
@BridgeAR

BridgeAR commented Dec 24, 2018•
edited by Trott
Loading

Copy link
Copy Markdown
MemberAuthor

PTAL. I reworked the output as discussed.

CI https://ci.nodejs.org/job/node-test-pull-request/19772/ ✔️

@BridgeAR

BridgeAR commented Dec 27, 2018

Copy link
Copy Markdown
MemberAuthor

@nodejs/util @addaleax@targos PTAL

This needs some reviews.

@BridgeAR
util: inspect ArrayBuffers contents as well
48bde7a
Inspecting an ArrayBuffer now also shows their binary contents.
@BridgeAR
BridgeARforce-pushed the inspect-array-buffer-closer branch from f58d87c to 48bde7aCompareDecember 27, 2018 21:50
@BridgeAR

BridgeAR commented Dec 27, 2018

Copy link
Copy Markdown
MemberAuthor

Rebased due to conflicts. PTAL, this needs a review.

CI https://ci.nodejs.org/job/node-test-pull-request/19846/

@targos

targos commented Jan 1, 2019

Copy link
Copy Markdown
Member

CI: https://ci.nodejs.org/job/node-test-pull-request/19903/

@addaleax

addaleax commented Jan 7, 2019

Copy link
Copy Markdown
Member

Resume CI: https://ci.nodejs.org/job/node-test-pull-request/19976/

@addaleaxaddaleax added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Jan 7, 2019
@addaleax

addaleax commented Jan 9, 2019

Copy link
Copy Markdown
Member

Landed in aa07dd6

@addaleaxaddaleax closed this Jan 9, 2019
addaleax pushed a commit that referenced this pull request Jan 9, 2019
@BridgeAR@addaleax
util: inspect ArrayBuffers contents as well
aa07dd6
Inspecting an ArrayBuffer now also shows their binary contents.
PR-URL: #25006
Reviewed-By: Anna Henningsen <anna@addaleax.net>
@addaleax

addaleax commented Jan 9, 2019

Copy link
Copy Markdown
Member

@BridgeAR fyi, this would need a manual backport to v11.x-staging

@BridgeARBridgeAR mentioned this pull request Jan 9, 2019
Closed
4 tasks
BridgeAR added a commit to BridgeAR/node that referenced this pull request Jan 9, 2019
@BridgeAR
util: inspect ArrayBuffers contents as well
7472860
Inspecting an ArrayBuffer now also shows their binary contents.
PR-URL: nodejs#25006
Reviewed-By: Anna Henningsen <anna@addaleax.net>
BridgeAR added a commit that referenced this pull request Jan 10, 2019
@BridgeAR
util: inspect ArrayBuffers contents as well
dc4e5c5
Inspecting an ArrayBuffer now also shows their binary contents.
PR-URL: #25006
Reviewed-By: Anna Henningsen <anna@addaleax.net>
addaleax pushed a commit that referenced this pull request Jan 14, 2019
@BridgeAR@addaleax
util: inspect ArrayBuffers contents as well
901d3d0
Inspecting an ArrayBuffer now also shows their binary contents.
PR-URL: #25006
Reviewed-By: Anna Henningsen <anna@addaleax.net>
@BridgeARBridgeAR mentioned this pull request Jan 16, 2019
Merged
BridgeAR added a commit to BridgeAR/node that referenced this pull request Jan 17, 2019
@BridgeAR
2019-01-17, Version 11.7.0 (Current),@BridgeAR
6b7b827
Notable Changes
* compression / zlib:
* Added brotli support (Anna Henningsen and Zach Vacura)
nodejs#24938
* console:
* Added `inspectOptions` option (Ruben Bridgewater)
nodejs#24978
* crypto:
* Always accept private keys as public keys (Tobias Nießen)
nodejs#25217
* deps:
* Upgrade npm to v6.5.0 (Jordan Harband)
nodejs#25234
* fs:
* Use internalBinding('fs') internally instead of
process.binding('fs') (Masashi Hirano)
nodejs#22478
* http(s):
* Support overriding http\\s.globalAgent (Roy Sommer)
nodejs#25170
* util:
* Inspect ArrayBuffers contents closely (Ruben Bridgewater)
nodejs#25006
* worker:
* Expose workers by default and remove `--experimental-worker` flag
(Anna Henningsen) nodejs#25361
PR-URL: nodejs#25537
BridgeAR added a commit that referenced this pull request Jan 18, 2019
@BridgeAR
2019-01-17, Version 11.7.0 (Current),@BridgeAR
d3f8f90
Notable Changes
* compression / zlib:
* Added brotli support (Anna Henningsen and Zach Vacura)
#24938
* console:
* Added `inspectOptions` option (Ruben Bridgewater)
#24978
* crypto:
* Always accept private keys as public keys (Tobias Nießen)
#25217
* deps:
* Upgrade npm to v6.5.0 (Jordan Harband)
#25234
* fs:
* Use internalBinding('fs') internally instead of
process.binding('fs') (Masashi Hirano)
#22478
* http(s):
* Support overriding http\\s.globalAgent (Roy Sommer)
#25170
* util:
* Inspect ArrayBuffers contents closely (Ruben Bridgewater)
#25006
* worker:
* Expose workers by default and remove `--experimental-worker` flag
(Anna Henningsen) #25361
PR-URL: #25537
@MylesBorinsMylesBorins mentioned this pull request Jan 24, 2019
Merged
@BridgeAR
BridgeAR deleted the inspect-array-buffer-closer branch January 20, 2020 11:51
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@addaleaxaddaleaxaddaleax approved these changes
+1 more reviewer
@vsemozhetbytvsemozhetbytvsemozhetbyt left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

author readyPRs that have at least one approval, no pending requests for changes, and a CI started.semver-minorPRs that contain new features and should be released in the next minor version.utilIssues and PRs related to the built-in util module.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

7 participants

@BridgeAR@nodejs-github-bot@targos@addaleax@Trott@vsemozhetbyt@BethGriggs