[P1] Document BigInt

[chrisdavidmills]

Cross-filed from https://bugzilla.mozilla.org/show_bug.cgi?id=1476965.

See also https://trello.com/c/toqiqtQ1/17-bigint-fx-67 for the content roadmap Trello card detailing the bugs that need to be ddc'ed one this is done.

Florian's recommendations:

I think we should document this sooner rather than later. I'm adding my brain dump on what I think needs to be done. There might be more work involved here, but this is a start.

BigInt is a new primitive type and this needs to be added to a few places (with notes on type conversation)

• Update: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_Types#Data_types
• Update: https://developer.mozilla.org/en-US/docs/Glossary/Primitive
• Update: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures
• Update: https://developer.mozilla.org/en-US/docs/Glossary/Falsy
• Update: https://developer.mozilla.org/en-US/docs/Glossary/Truthy

BigInt should be mentioned/referenced from relevant Number docs

• Update: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number
• Update: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER
• Update: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_SAFE_INTEGER
• Update: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger

BigInt comes with a new numeric literal (n)

• Update: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#Numeric_literals

BigInt and typeof

• Update: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof

BigInt API:

• New page: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt
• New page: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/asUintN (static method)
• New page: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/asIntN (static method)
• New page: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/prototype
• New page: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/toLocaleString
• New page: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/toString
• New page: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/valueOf

BigInt TypedArray API:

• Update: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays
• Update: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
• New page: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt64Array
• New page: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigUint64Array
• Update: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView
• Update: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/prototype
• New page: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getBigInt64
• New page: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getBigUint64
• New page: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setBigInt64
• New page: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setBigUint64

BigInt and interaction with other parts of JS (add examples)

• Update: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
• Mention that BigInt doesn't at all work with the Math object https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math
• Update: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseFloat
• Update: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt

All new reference pages need compat data and interactive examples, see

• https://github.com/mdn/browser-compat-data/
• https://github.com/mdn/interactive-examples

[chrisdavidmills]

See also #887

[chrisdavidmills]

@sarahgp wrote https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt

This needs reviewing. @Elchi3 can you give her some feedback and help her with future work here? Provided she still wants to contribute further, of coursde ;-)

[sarahghp]

Yes, I am still interested in contributing and I am open to feedback. I've also been emailing with @iulia-codes about contributing.

My next plan is to take on the Updates starting from the top, but if other people want to hop in (I have limited time), I am totally glad for that, too.

[Elchi3]

Hey, thanks for re-filing this on GitHub! I've updated the description to use checklists.

I've glanced over the two pages that were created so far and they look excellent!
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/prototype

I'm happy to review more and let me know if there are questions with the items on the to-do list above.

[iulia-codes]

Hi all, so I've updated the main https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray but I am missing permissions to create new page. Can the page placeholders already be created ? https://developer.mozilla.org/en-US/docs/new?slug=BigInt64Array&parent=5612 and https://developer.mozilla.org/en-US/docs/new?slug=BigUint64Array&parent=5612

I will work on these next.

[chrisdavidmills]

@iulia-codes I am happy to give you page creation permissions. What's you MDN username?

I am also happy to create the placeholders for you, but it looks like when you use the jsxref macro call to create a reference to a new page, it is creating them under /JavaScript/Reference, whereas it should be creating them under /JavaScript/Reference/Global_Objects, e.g.

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float64Array

So ideally we should create them as children of Global_Objects, e.g. by going to https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects and using the "New sub-article" option in the gear menu.

[chrisdavidmills]

New pages created:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt64Array
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigUint64Array

[iulia-codes]

Hi @chrisdavidmills, my username is iulia on MDN

Good thing to know about the hierarchy of the pages & thanks for creating the two new pages :)

[chrisdavidmills]

Hi @chrisdavidmills, my username is iulia on MDN

OK, cool. I've given you page creation permissions.

Good thing to know about the hierarchy of the pages

Yeah, I had to do a bit of digging here. I asked around, and it looks like the jsxref macro has a couple of bugs in terms of where new pages a created, if you use it to create links to new/non-existent pages.

thanks for creating the two new pages :)

You are welcome. Let me know if you need any more help.

[chrisdavidmills]

@iulia-codes Hi there! I just wanted to do a quick check in about the two pages I created for you to fill in. Do you think you'll have time to do them soon? If not, don't worry about it — we can just delete them again until you are ready.

[iulia-codes]

Hey @chrisdavidmills, I noticed the pages are gone, but that's okay, as I've continued updating on the already existing pages. I have planned to update the two new pages that you created by the end of May.

• Updated: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_Types#Data_types

• Updated: https://developer.mozilla.org/en-US/docs/Glossary/Primitive

• Updated: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures

• Created:https://developer.mozilla.org/en-US/docs/Glossary/BigInt

[iulia-codes]

Also, what is missing in the Falsy page? https://developer.mozilla.org/en-US/docs/Glossary/Falsy

• Updated: https://developer.mozilla.org/en-US/docs/Glossary/Truthy

[littledan]

Great work on all of those, @iulia-codes. The new content you wrote looks very good to me. Would it make sense to also add context to https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_Types#Literals ?

[chrisdavidmills]

Hey @chrisdavidmills, I noticed the pages are gone, but that's okay, as I've continued updating on the already existing pages. I have planned to update the two new pages that you created by the end of May.

Hi @iulia-codes; thanks for all the work on this! If you are ready to start working on those two new pages, I can always reinstate them again. Would you like me to do so?

[iulia-codes]

Hi @chrisdavidmills yes, I can finish it this weekend and then maybe have it up for review.

[iulia-codes]

Definitely @littledan will add a reference there as well.

[chrisdavidmills]

@iulia-codes ok, cool!

I have reinstated the following pages, so you can now edit them and fill them in:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt64Array
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigUint64Array

As always, let me know if you need any help. I'll check my mail a couple of times over the weekend, just in case.

[lpd-au]

Just a heads up, at the moment the BigInt page itself says:

The following operators may be used with BigInts (or object-wrapped BigInts): +, *, -, **, %.

Without making any mention of bitwise operators, which do appear to be supported.

[Elchi3]

BigInt typed array API

I worked on the BigInt typed array API part of this as it seems like I wouldn't collide with anyone. Here's things to look at and to maybe review, if you're interested.

The BigInt typed array additions are now listed on relevant pages:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference#Indexed_collections
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects#Indexed_collections
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray#Syntax
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray#TypedArray_objects
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays#Typed_array_views
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView#Methods
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Indexed_collections#Typed_array_views
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Indexed_collections_Arrays_and_typed_Arrays

New reference pages have been created:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt64Array
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigUint64Array
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getBigInt64
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getBigUint64
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setBigInt64
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setBigUint64

To make the sidebar menu as useful as for the other typed arrays some hacks are needed:

• Add BigInt typed array types kumascript#1174

Browser compat data updates are in this PR (assumes same compat as general BigInt availability)

• Add BigInt TypedArray API browser-compat-data#4248

Interactive sample updates for bigint typed arrays:

• Add support for BigInts in js console bob#254
• Add samples for BigInt typed array API interactive-examples#1367
• More to come here, but I already attempted to fix our interactive JS console to deal with the bigint types. (tl;dr toString doesn't preserve the "n", but I believe we should display it, as browser consoles display it, too).

Questions:

• A contributor updated following reference page and added some code. This can now use getBigUint64, right?
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView#64-bit_Integer_Values

[Elchi3]

BigInt as a new type/primitive/literal

The next bunch of docs that is ready for review is about BigInt as a new type/primitive/literal. I've reviewed and completed what @iulia-codes did and the pages listed below belong to this topic. Review welcome.

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#BigInt_type
• https://developer.mozilla.org/en-US/docs/Glossary/BigInt
• https://developer.mozilla.org/en-US/docs/Glossary/Primitive
• https://developer.mozilla.org/en-US/docs/Glossary/Falsy
  https://developer.mozilla.org/en-US/docs/Glossary/Truthy
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_Types#Data_structures_and_types
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Numeric_literals
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#Numeric_literals

[Elchi3]

Main BigInt API

More stuff to review! Here are the pages for the main BigInt API.

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference#Numbers_and_dates
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects#Numbers_and_dates
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/asIntN
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/asUintN
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/prototype
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/toLocaleString
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/toString
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/valueOf

Compat data:

• Expand BigInt data to cover full API browser-compat-data#4255
• Add locales/options to BigInt#toLocaleString browser-compat-data#4313

Interactive examples:

• Add examples for BigInt API interactive-examples#1380

[Elchi3]

Related pages

Not much about BigInt on these pages, but it is worth having BigInt mentioned somehow at least as these APIs interact with the BigInt type, are related, or (surprisingly) don't work with it.

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_SAFE_INTEGER
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math
  • I haven't mentioned on every Math method that it doesn't work with BigInt. Should I do that?
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseFloat
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt

Review appreciated.

[Elchi3]

@chrisdavidmills Could you review the docs that I've listed in the last four comments here?

[chrisdavidmills]

@Elchi3 Sure. Might take me a few days to dig myself out of this current hole, but I should get to them by the end of the week ;-)

[chrisdavidmills]

@Elchi3 OK, so I've reviewed all the stuff on #1002 (comment)

The pages all look great and make sense. I just did a bit of light copy editing really.

You had a question here:

A contributor updated following reference page and added some code. This can now use getBigUint64, right?
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView#64-bit_Integer_Values

I'm not an expert, but yeah, looks like it.

[Elchi3]

Thanks Chris! It looks like another contributor added a BigInt version of that code in the meantime already. I've just looked that over and removed "works only in Chrome" which isn't true anymore :)

[chrisdavidmills]

OK, I've also now reviewed everything at #1002 (comment)

Again, all reads really well. Just a few minor bits of copy editing to do.

Thanks Chris! It looks like another contributor added a BigInt version of that code in the meantime already. I've just looked that over and removed "works only in Chrome" which isn't true anymore :)

OK, great!

[lpd-au]

Just a heads up, at the moment the BigInt page itself says:

The following operators may be used with BigInts (or object-wrapped BigInts): +, *, -, **, %.

Without making any mention of bitwise operators, which do appear to be supported.

Bump

[Elchi3]

I've added "Bitwise operators are supported as well, except >>> (zero-fill right shift) as all BigInts are signed. Also unsupported is the unary + in order to not break asm.js."

[chrisdavidmills]

I've now reviewed everything at #1002 (comment). All looks fine, just made a few really minor copy edits.

[chrisdavidmills]

OK, everything at #1002 (comment) now reviewed too! Only a few copy edits.

I haven't mentioned on every Math method that it doesn't work with BigInt. Should I do that?

Is it just all Math methods? In which case, you already basically say that, so I think we're OK.

[Elchi3]

Yeah, it is all of them. Thank you a lot for all your reviews! 👍

[Elchi3]

I'm going to close this. Thanks everyone who helped on this! If there is follow-up work on BigInt, please file a new issue and cc me.