2c:null 2d:["$","title",null,{"children":"How I Shipped BigInt64Array and BigUint64Array Polyfills in 4 Days | Michaël Guitton | Observable"}] 32:T4c3,Our interaction focused on solving several complex implementation milestones: 1. **Proxy-Based Indexing**: We implemented a `Proxy` to allow for standard array-like indexing (e.g., `new BigInt64Array(1)[0]`), which is notoriously difficult to simulate in custom JavaScript classes. - **64-bit Bitwise Simulation**: Since we were targeting environments without native 64-bit support, we manually managed the high and low 32-bit words using `DataView`. Google Gemini helped refine the logic for `BigInt.asIntN` and `BigInt.asUintN` behavior to ensure correct signed/unsigned overflows. - **Performance Optimization**: We moved beyond simple loops, implementing bulk byte-level copying via `Uint8Array` views for methods like `set` and `slice`, significantly boosting performance for large data sets. - **Internal State Management**: We used `Symbols` for private members to ensure internal properties (like the underlying `DataView`) remained hidden from iteration and external tampering. - **Inheritance & Prototypes**: We tackled the challenge of ensuring `BigUint64Array` correctly inherited from the base polyfill while overriding the internal bit-handling logic, all while maintaining correct instanceof checks.33:T914,BigUint64ArrayPolyfill = (function* () { /** * Polyfill for BigUint64Array extending the BigInt64ArrayPolyfill logic. */ const BigUint64ArrayPolyfill = class extends BigInt64ArrayPolyfill { static name = "BigUint64Array"; /** * Overrides static from method */ static from( source, mapFn, thisArg, { C = this || BigUint64ArrayPolyfill } = {} ) { return super.from(source, mapFn, thisArg, { C }); } /** * Returns the specific string tag for BigUint64Array. */ get [Symbol.toStringTag]() { return BigUint64ArrayPolyfill.name; } }; Object.defineProperties(BigUint64ArrayPolyfill.prototype, { [_getBigInt64]: { /** * Internal method to retrieve an unsigned 64-bit integer from the buffer. * @private */ value: IS_LITTLE_ENDIAN ? function (byteOffset) { const view = this[_view]; const high = view.getUint32(byteOffset + 4, true); const low = view.getUint32(byteOffset, true); return (BigInt(high) << 32n) | (BigInt(low) & 0xffffffffn); } : function (byteOffset) { const view = this[_view]; const high = view.getUint32(byteOffset, false); const low = view.getUint32(byteOffset + 4, false); return (BigInt(high) << 32n) | (BigInt(low) & 0xffffffffn); } }, [_setBigInt64]: { /** * Internal method to store an unsigned 64-bit integer into the buffer. * @private */ value: IS_LITTLE_ENDIAN ? function (byteOffset, value) { const uintValue = BigInt.asUintN(64, BigInt(value)); const view = this[_view]; view.setUint32(byteOffset, Number(uintValue & 0xffffffffn), true); view.setUint32(byteOffset + 4, Number(uintValue >> 32n), true); } : function (byteOffset, value) { const uintValue = BigInt.asUintN(64, BigInt(value)); const view = this[_view]; view.setUint32( byteOffset + 4, Number(uintValue & 0xffffffffn), false ); view.setUint32(byteOffset, Number(uintValue >> 32n), false); } } }); yield BigUint64ArrayPolyfill; })()34:T5068,BigInt64ArrayPolyfill = (function* () { const __BPE__ = 64 / 8; const __IMMUTABLE__ = new Set([ _buffer, "buffer", _byteOffset, "byteOffset", _byteLength, "byteLength", _len, "length", _view ]); const traps = { get(target, prop, receiver) { if (typeof prop === "string") { const index = Number(prop); if (Number.isInteger(index) && prop === String(index)) { if (index < 0 || index >= target[_len]) return void 0; return target[_getBigInt64](index * __BPE__); } } const value = Reflect.get(target, prop, receiver); return typeof value === "function" ? value.bind(receiver) : value; }, set(target, prop, value, receiver) { if (__IMMUTABLE__.has(prop)) { throw new TypeError("Attempted to assign to immutable property"); } if (typeof prop === "string") { const index = Number(prop); if (Number.isInteger(index) && prop === String(index)) { if (index < 0 || index >= target[_len]) return false; try { target[_setBigInt64](index * __BPE__, BigInt(value)); } catch (e) { target[_setBigInt64](index * __BPE__, /* force 0 on failure */ 0n); } return true; } } return Reflect.set(target, prop, value, receiver); }, defineProperty(target, prop, descriptor) { if (__IMMUTABLE__.has(prop)) { return true; // Don't comply } return Reflect.defineProperty(target, prop, descriptor); }, deleteProperty(target, prop) { if (__IMMUTABLE__.has(prop)) { return true; // Don't comply } return delete target[prop]; }, has(target, prop) { if (typeof prop === "string") { const index = Number(prop); if (Number.isInteger(index) && prop === String(index)) { return index >= 0 && index < target[_len]; } } return Reflect.has(target, prop); }, ownKeys: "symbols" === internals ? (target) => { const keys = Array.from({ length: target[_len] }, (_, i) => String(i) ); return keys.concat( Reflect.ownKeys(target).filter((k) => !keys.includes(k)) ); } : (target) => Array.from({ length: target[_len] }, (_, i) => String(i)), getOwnPropertyDescriptor(target, prop) { // 1. Handle Numeric Indices if (typeof prop === "string") { const index = Number(prop); if (Number.isInteger(index) && prop === String(index)) { if (index >= 0 && index < target[_len]) { return { // Retrieve value via target or receiver logic value: target[_getBigInt64](index * __BPE__), writable: true, enumerable: true, configurable: true }; } } } // 2. Handle standard properties (buffer, byteOffset, byteLength, etc.) // This also handles the 'length' getter if requested, though it // will correctly return undefined as an "own" property. return Reflect.getOwnPropertyDescriptor(target, prop); } }; /** * Polyfill for BigInt64Array using DataView and Proxy. */ const BigInt64ArrayPolyfill = class { static name = "BigInt64Array"; // --- Static Methods --- /** * Creates a new BigInt64Array from an array-like or iterable object. * @param {ArrayLike|Iterable} source * @param {Function} [mapFn] * @param {any} [thisArg] * @returns {BigInt64ArrayPolyfill} */ static from( source, mapFn, thisArg, { C = this || BigInt64ArrayPolyfill } = {} ) { if (null == source) { throw new TypeError( `${this.name}.from requires an array-like object - not ${source}` ); } const items = Array.from(source, mapFn, thisArg); const result = new C(items.length); try { result.length && result.set(items); } catch (e) {} return result; } /** * Creates a new BigInt64Array with a variable number of arguments. * @param {...any} items * @returns {BigInt64ArrayPolyfill} */ static of(...items) { return this.from(items); } /** * Returns the constructor used to create derived objects. */ static get [Symbol.species]() { return this; } /** * @param {number|ArrayBuffer|ArrayLike} arg * @param {number} [byteOffset=0] * @param {number} [length] */ constructor(arg = 0, byteOffset = 0, length) { let buffer; let len; if (byteOffset % __BPE__ !== 0) { throw new RangeError("Byte offset should be a multiple of " + __BPE__); } // 1. Data Setup if (arg instanceof ArrayBuffer) { buffer = arg; // Calculate length based on remaining bytes in buffer if not provided len = length !== void 0 ? length : Math.floor((buffer.byteLength - byteOffset) / __BPE__); } else if ( arg && -1 === ["function", "string"].indexOf(typeof arg) && (typeof arg.length === "number" || typeof arg[Symbol.iterator] === "function") ) { len = arg.length || (!!arg.has && arg.size) || (arg = [...arg]).length; buffer = new ArrayBuffer(len * __BPE__); } else { try { len = (arg = Number(arg)) | 0; buffer = new ArrayBuffer(len * __BPE__); } catch ({ constructor: ErrorKind, message }) { throw new ErrorKind(message); } } // 2. Symbol-based Private State this[_buffer] = buffer; this[_byteOffset] = byteOffset; this[_byteLength] = len * __BPE__; this[_len] = len; this[_view] = new DataView(buffer, byteOffset, len * __BPE__); // 3. Create the Proxy const proxy = new Proxy(this, traps); // 4. Populate initial values using optimized set() if arg is array-like/iterable if (arg !== buffer && arg !== len) { proxy.set(arg); } return proxy; } // --- Prototype Methods --- get buffer() { return this[_buffer]; } get byteOffset() { return this[_byteOffset]; } get byteLength() { return this[_byteLength]; } /** * Returns the number of elements in the array. */ get length() { return this[_len]; } /** * Returns the specific string tag for BigInt64Array. */ get [Symbol.toStringTag]() { return BigInt64ArrayPolyfill.name; } /** * Takes an integer value and returns the item at that index. * @param {number} index * @returns {bigint|undefined} */ at(index) { let k = Number(index); k = k >= 0 ? k : this[_len] + k; if (k < 0 || k >= this[_len]) return void 0; return this[k]; } /** * Copies a sequence of array elements within the array. */ copyWithin(target, start = 0, end = this[_len]) { const byteTarget = (target < 0 ? Math.max(this[_len] + target, 0) : Math.min(target, this[_len])) * __BPE__; const byteStart = (start < 0 ? Math.max(this[_len] + start, 0) : Math.min(start, this[_len])) * __BPE__; const byteEnd = (end < 0 ? Math.max(this[_len] + end, 0) : Math.min(end, this[_len])) * __BPE__; new Uint8Array( this[_buffer], this[_byteOffset], this[_byteLength] ).copyWithin(byteTarget, byteStart, byteEnd); return this; } /** * Fills all the elements of an array from a start index to an end index with a static value. * @param {bigint} value * @param {number} [start=0] * @param {number} [end] */ fill(value, start = 0, end = this[_len]) { const len = this[_len]; let k = start < 0 ? Math.max(len + start, 0) : Math.min(start, len); const final = end < 0 ? Math.max(len + end, 0) : Math.min(end, len); while (k < final) { this[k] = value; k++; } return this; } /** * Calls a defined callback function for each element of an array. */ forEach(callback, thisArg) { for (let i = 0; i < this[_len]; i++) { callback.call(thisArg, this[i], i, this); } } /** * Calls a defined callback function on each element and returns a new array with the results. */ map(callback, thisArg) { const C = this.constructor[Symbol.species] || this.constructor; const result = new C(this[_len]); for (let i = 0; i < this[_len]; i++) { result[i] = callback.call(thisArg, this[i], i, this); } return result; } /** * Reverses the elements in an array in place. */ reverse() { const len = this[_len]; const middle = Math.floor(len / 2); const lastIndex = len - 1; for (let i = 0; i < middle; i++) { const temp = this[i]; const targetIndex = lastIndex - i; this[i] = this[targetIndex]; this[targetIndex] = temp; } return this; } /** * Stores multiple values in the typed array, reading input values from a specified array. */ set(source, offset = 0) { const targetLen = this[_len]; const count = source.length || 0; if ((offset = +offset) < 0) { throw new RangeError("Offset should not be negative"); } COPY: switch (true) { case source.buffer instanceof ArrayBuffer && source.BYTES_PER_ELEMENT === __BPE__: // Bulk copy if source is a TypedArray/Polyfill if (offset + count > targetLen) { break COPY; } if (0 === count) { return; } const byteOffsetTarget = this[_byteOffset] + offset * __BPE__; const byteLengthToCopy = count * __BPE__; const targetView = new Uint8Array( this[_buffer], byteOffsetTarget, byteLengthToCopy ); const sourceView = new Uint8Array( source.buffer, source.byteOffset || 0, byteLengthToCopy ); targetView.set(sourceView); return; case typeof source[Symbol.iterator] === "function" && !(source instanceof Array): // Perform manual iteration to avoid [...source] memory bloat let i = 0; for (const val of source) { if (offset + i >= targetLen) { break COPY; } this[offset + i] = val; i++; } return; default: // Standard Array or Array-like if (offset + count > targetLen) { break COPY; } for (let i = 0; i < count; i++) { this[offset + i] = source[i]; } return; } throw new RangeError( "Range consisting of offset and length are out of bounds" ); } /** * Returns a copy of a section of an array. */ slice(begin = 0, end = this[_len]) { const len = this[_len]; const start = begin < 0 ? Math.max(len + begin, 0) : Math.min(begin, len); const stop = end < 0 ? Math.max(len + end, 0) : Math.min(end, len); const newLen = Math.max(stop - start, 0); const C = this.constructor[Symbol.species] || BigInt64ArrayPolyfill; const result = new C(newLen); if (newLen > 0) { const byteStart = this[_byteOffset] + start * __BPE__; // Fast byte-level copy from our buffer to the new instance's buffer const sourceView = new Uint8Array( this[_buffer], byteStart, newLen * __BPE__ ); const targetView = new Uint8Array(result.buffer, 0, newLen * __BPE__); targetView.set(sourceView); } return result; } // --- Accumulation Methods --- /** * Executes a user-supplied "reducer" callback function on each element. */ reduce(callback, initialValue) { const len = this[_len]; if (len === 0 && arguments.length < 2) { throw new TypeError("Reduce of empty array with no initial value"); } let k = 0; let accumulator; if (arguments.length >= 2) { accumulator = initialValue; } else { accumulator = this[k++]; } for (; k < len; k++) { accumulator = callback(accumulator, this[k], k, this); } return accumulator; } /** * Same as reduce, but iterates from right-to-left. */ reduceRight(callback, initialValue) { const len = this[_len]; if (len === 0 && arguments.length < 2) { throw new TypeError("Reduce of empty array with no initial value"); } let k = len - 1; let accumulator; if (arguments.length >= 2) { accumulator = initialValue; } else { accumulator = this[k--]; } for (; k >= 0; k--) { accumulator = callback(accumulator, this[k], k, this); } return accumulator; } // --- Transformation Methods --- /** * Sorts the elements of the typed array numerically in place and returns the typed array. */ sort(compareFn) { const tempArray = Array.from(this); if (compareFn !== void 0) { if (typeof compareFn !== "function") { throw new TypeError( "The comparator argument must be either a function or undefined" ); } tempArray.sort(compareFn); } else { tempArray.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)); } this.set(tempArray); return this; } /** * Returns a new BigInt64Array on the same ArrayBuffer store. */ subarray(begin = 0, end = this[_len]) { const start = begin < 0 ? Math.max(this[_len] + begin, 0) : Math.min(begin, this[_len]); const stop = end < 0 ? Math.max(this[_len] + end, 0) : Math.min(end, this[_len]); const C = this.constructor[Symbol.species] || BigInt64ArrayPolyfill; return new C( this[_buffer], this[_byteOffset] + start * __BPE__, Math.max(stop - start, 0) ); } /** * Returns a new BigInt64Array with the elements in reversed order. * Unlike reverse(), it does not mutate the original array. */ toReversed() { return this.slice().reverse(); } /** * Returns a new BigInt64Array with the elements sorted. * Unlike sort(), it does not mutate the original array. */ toSorted(compareFn) { return this.slice().sort(compareFn); } /** * Returns a new array with the element at the given index replaced with the given value. */ with(index, value) { const result = this.slice(); let k = Number(index); k = k >= 0 ? k : this[_len] + k; if (k < 0 || k >= this[_len]) throw new RangeError("Invalid index"); result[k] = value; return result; } // --- Search and Comparison Methods --- /** * Returns the value of the first element that satisfies the provided testing function. */ find(predicate, thisArg) { for (let i = 0; i < this[_len]; i++) { const value = this[i]; if (predicate.call(thisArg, value, i, this)) { return value; } } return void 0; } /** * Returns the value of the last element that satisfies the provided testing function. * @param {Function} predicate * @param {any} [thisArg] * @returns {bigint|undefined} */ findLast(predicate, thisArg) { for (let i = this[_len] - 1; i >= 0; i--) { const value = this[i]; if (predicate.call(thisArg, value, i, this)) { return value; } } return void 0; } /** * Returns the index of the first element that satisfies the provided testing function. */ findIndex(predicate, thisArg) { for (let i = 0; i < this[_len]; i++) { if (predicate.call(thisArg, this[i], i, this)) { return i; } } return -1; } /** * Returns the index of the first occurrence of a value in the array. */ indexOf(searchElement, fromIndex = 0) { let k = Number(fromIndex); k = k >= 0 ? k : Math.max(this[_len] + k, 0); for (let i = k; i < this[_len]; i++) { if (this[i] === searchElement) { return i; } } return -1; } /** * Returns the index of the last occurrence of a value in the array. */ lastIndexOf(searchElement, fromIndex = this[_len] - 1) { let k = Number(fromIndex); k = k >= 0 ? Math.min(k, this[_len] - 1) : this[_len] + k; for (let i = k; i >= 0; i--) { if (this[i] === searchElement) { return i; } } return -1; } /** * Determines whether an array includes a certain element. */ includes(searchElement, fromIndex = 0) { return this.indexOf(searchElement, fromIndex) !== -1; } /** * Returns true if every element in the array satisfies the testing function. */ every(callback, thisArg) { for (let i = 0; i < this[_len]; i++) { if (!callback.call(thisArg, this[i], i, this)) { return false; } } return true; } /** * Returns true if at least one element in the array satisfies the testing function. */ some(callback, thisArg) { for (let i = 0; i < this[_len]; i++) { if (callback.call(thisArg, this[i], i, this)) { return true; } } return false; } /** * Creates a new array with all elements that pass the test implemented by the provided function. */ filter(callback, thisArg) { const temp = []; for (let i = 0; i < this[_len]; i++) { if (callback.call(thisArg, this[i], i, this)) { temp.push(this[i]); } } const C = this.constructor[Symbol.species] || BigInt64ArrayPolyfill; const result = new C(temp.length); result.set(temp); return result; } // --- Iteration Methods --- *entries() { for (let i = 0; i < this[_len]; i++) { yield [i, this[i]]; } } *keys() { for (let i = 0; i < this[_len]; i++) { yield i; } } *values() { for (let i = 0; i < this[_len]; i++) { yield this[i]; } } [Symbol.iterator]() { return this.values(); } toString() { return Array.from(this).join(","); } }; Object.defineProperty(BigInt64ArrayPolyfill, "BYTES_PER_ELEMENT", { value: __BPE__ }); Object.defineProperties(BigInt64ArrayPolyfill.prototype, { BYTES_PER_ELEMENT: { value: __BPE__ }, [_getBigInt64]: { /** * Internal method to retrieve a 64-bit integer from the buffer. * @private */ value: IS_LITTLE_ENDIAN ? function (byteOffset) { const view = this[_view]; const high = view.getInt32(byteOffset + 4, true); const low = view.getUint32(byteOffset, true); return (BigInt(high) << 32n) | (BigInt(low) & 0xffffffffn); } : function (byteOffset) { const view = this[_view]; const high = view.getInt32(byteOffset, false); const low = view.getUint32(byteOffset + 4, false); return (BigInt(high) << 32n) | (BigInt(low) & 0xffffffffn); } }, [_setBigInt64]: { /** * Internal method to store a 64-bit integer into the buffer. * @private */ value: IS_LITTLE_ENDIAN ? function (byteOffset, value) { const val = BigInt.asIntN(64, value); const view = this[_view]; view.setUint32(byteOffset, Number(val & 0xffffffffn), true); view.setInt32(byteOffset + 4, Number(val >> 32n), true); } : function (byteOffset, value) { const val = BigInt.asIntN(64, value); const view = this[_view]; view.setUint32(byteOffset + 4, Number(val & 0xffffffffn), false); view.setInt32(byteOffset, Number(val >> 32n), false); } } }); yield BigInt64ArrayPolyfill; })()35:[] 30:{"id":"ed799605f4d9b42b","slug":"how-i-shipped-bigint64array-and-biguint64array-polyfills-in-4-days","title":"How I Shipped BigInt64Array and BigUint64Array Polyfills in 4 Days","thumbnail":"98a7d040b6d5c5d39bfb8f23879cf8b2c6fb43dd0ce027a7052141f27c053792","access_level":"public","create_time":"$D2026-03-12T22:30:23.349Z","update_time":"$D2026-08-28T08:30:16.057Z","view_time":null,"first_public_time":"$D2026-03-13T05:18:11.264Z","fork":true,"stars":1,"starred":false,"owner":{"type":"team","id":"4c1622bb5c37477f","login":"galopin","name":"Michaël Guitton","avatar_url":"https://avatars-next.observableusercontent.com/10e2fe999ac95c8686156fd07e96a686520149a4eef18a95f97795b7a7be1e29","tier":"starter_2024"},"version":87,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"950eb34948878085","login":"galopin","name":"Michaël Guitton","avatar_url":"https://avatars-next.observableusercontent.com/b59822ff41962e9448473fadd4a11819ac725b074ad3868aabf532bade0ac00d","tier":null}],"members":[{"type":"individual","id":"950eb34948878085","login":"galopin","name":"Michaël Guitton","avatar_url":"https://avatars-next.observableusercontent.com/b59822ff41962e9448473fadd4a11819ac725b074ad3868aabf532bade0ac00d","tier":null,"role":"editor"},{"type":"team","id":"4c1622bb5c37477f","login":"galopin","name":"Michaël Guitton","avatar_url":"https://avatars-next.observableusercontent.com/10e2fe999ac95c8686156fd07e96a686520149a4eef18a95f97795b7a7be1e29","tier":"starter_2024","role":"viewer"}],"comments":[],"custom_thumbnail":false,"trashed":false,"subscribed":null,"forks":1,"collection":{"id":"e01c3182ec20df24","slug":"tinkering","title":"Tinkering","owner":{"id":"4c1622bb5c37477f","login":"galopin","name":"Michaël Guitton"}},"type":"notebook","body":{"title":"How I Shipped BigInt64Array and BigUint64Array Polyfills in 4 Days","cells":[{"id":0,"value":"$${[\n md`# How I Shipped \\`BigInt64Array\\` and \\`BigUint64Array\\` Polyfills in 4 Days`,\n md`## Prompting, Patching, and Polishing: Wrestling With an LLM Sidekick`\n]\n .map(($_) =>\n Object.assign($_, {\n style: \"text-wrap: balance;\"\n })\n )\n .concat([html`