JavaScript Typed Arrays, ArrayBuffers, DataView & Atomics

// Regular array — each element is a full JavaScript value object
// Every number is stored as a 64-bit float with type metadata
// Elements can be non-contiguous in memory
const nums = [1, 2, 3, 4, 5];

// Operations on regular arrays:
// - Each read/write involves type checking and boxing/unboxing
// - No guarantee of contiguous memory (hard for CPU cache)
// - Can't pass directly to WebGL, WebAssembly, AudioContext, etc.

┌─────────────────────────────────────────────┐
│            ArrayBuffer (raw bytes)          │
│  [ 00 ] [ 00 ] [ 00 ] [ 00 ] [ 00 ] [ 00 ] │  ← 6 bytes of raw memory
└────────────────────┬────────────────────────┘
                     │  interpreted by
          ┌──────────┼──────────────┐
          ▼          ▼              ▼
   Int8Array    Uint16Array    Float32Array
   (6 values)   (3 values)     (1.5 values!)

const arr = new Int32Array(4);    // 4 elements × 4 bytes = 16 bytes of memory
console.log(arr);                 // Output: Int32Array(4) [0, 0, 0, 0]
console.log(arr.length);          // Output: 4
console.log(arr.byteLength);      // Output: 16  (4 elements × 4 bytes each)

const fromArray = new Uint8Array([10, 20, 30, 255]);
console.log(fromArray);           // Output: Uint8Array(4) [10, 20, 30, 255]

const fromSet = new Float32Array(new Set([1.1, 2.2, 3.3]));
console.log(fromSet);             // Output: Float32Array(3) [1.1, 2.2, 3.3]

const buffer = new ArrayBuffer(8);   // 8 bytes of raw memory

// Two different views into the SAME 8 bytes:
const int32View  = new Int32Array(buffer);    // 2 elements (8 ÷ 4 bytes each)
const uint8View  = new Uint8Array(buffer);    // 8 elements (8 ÷ 1 byte each)

int32View[0] = 256;    // Write 256 as a 32-bit integer

// The bytes changed — and both views see the change:
console.log(int32View[0]);   // Output: 256
console.log(uint8View[0]);   // Output: 0    ← first byte of 256 in little-endian
console.log(uint8View[1]);   // Output: 1    ← second byte of 256 (0x00 0x01 0x00 0x00)

const scores = new Uint8Array(5);

scores[0] = 95;
scores[1] = 88;
scores[2] = 72;
scores[3] = 100;
scores[4] = 61;

console.log(scores[2]);    // Output: 72
console.log(scores);       // Output: Uint8Array(5) [95, 88, 72, 100, 61]

// Iterate like a regular array:
for (const score of scores) {
  process.stdout.write(score + " ");
}
// Output: 95 88 72 100 61

const u8 = new Uint8Array(1);   // Range: 0 to 255

u8[0] = 255;
console.log(u8[0]);   // Output: 255

u8[0] = 256;          // 256 mod 256 = 0 (wraps to 0)
console.log(u8[0]);   // Output: 0

u8[0] = 257;          // 257 mod 256 = 1
console.log(u8[0]);   // Output: 1

u8[0] = -1;           // -1 mod 256 = 255
console.log(u8[0]);   // Output: 255

const i8 = new Int8Array(1);   // Range: -128 to 127

i8[0] = 127;
console.log(i8[0]);   // Output: 127

i8[0] = 128;          // Wraps to -128
console.log(i8[0]);   // Output: -128

i8[0] = 129;          // Wraps to -127
console.log(i8[0]);   // Output: -127

const clamped = new Uint8ClampedArray(3);

clamped[0] = 300;    // Clamped to 255 (max)
clamped[1] = -50;    // Clamped to 0 (min)
clamped[2] = 128;    // In range — stays 128

console.log(clamped);   // Output: Uint8ClampedArray(3) [255, 0, 128]

const arr = new Float32Array(10);

console.log(arr.length);         // Output: 10  — number of elements
console.log(arr.byteLength);     // Output: 40  — total bytes (10 × 4 bytes per float32)
console.log(arr.byteOffset);     // Output: 0   — starting byte offset within the buffer
console.log(arr.BYTES_PER_ELEMENT); // Output: 4  — bytes per element (Float32 = 4)
console.log(arr.buffer);         // Output: ArrayBuffer { byteLength: 40 }
console.log(arr.buffer === arr.buffer); // Output: true — reference to underlying buffer

const dest = new Uint8Array(8);

dest.set([10, 20, 30, 40]);         // Copy to positions 0–3
console.log(dest);
// Output: Uint8Array(8) [10, 20, 30, 40, 0, 0, 0, 0]

dest.set([50, 60], 4);              // Copy to positions 4–5 (offset = 4)
console.log(dest);
// Output: Uint8Array(8) [10, 20, 30, 40, 50, 60, 0, 0]

// Efficient bulk copy from another typed array:
const src  = new Uint8Array([1, 2, 3]);
const dest2 = new Uint8Array(6);
dest2.set(src, 3);
console.log(dest2);
// Output: Uint8Array(6) [0, 0, 0, 1, 2, 3]

const full = new Uint8Array([10, 20, 30, 40, 50, 60, 70, 80]);

const slice = full.subarray(2, 5);   // Elements at index 2, 3, 4
console.log(slice);   // Output: Uint8Array(3) [30, 40, 50]

// Modifying the subarray modifies the original:
slice[0] = 99;
console.log(full);
// Output: Uint8Array(8) [10, 20, 99, 40, 50, 60, 70, 80]  ← position 2 changed!

const arr = new Uint8Array([1, 2, 3, 4, 5]);

const sub   = arr.subarray(1, 4);  // View — same buffer, no copy
const copy  = arr.slice(1, 4);     // Copy — new buffer

sub[0] = 99;
copy[0] = 77;

console.log(arr[1]);   // Output: 99  ← subarray mutation visible
console.log(arr[1]);   // Output: 99  ← copy mutation NOT visible

const arr = new Uint8Array([1, 2, 3, 4, 5, 6]);

// copyWithin(target, start, end?)
// Copy elements at [1,3) to position 3:
arr.copyWithin(3, 1, 3);
console.log(arr);   // Output: Uint8Array(6) [1, 2, 3, 2, 3, 6]
//                                                      ↑   ↑
//                                             positions 3,4 got values from positions 1,2

const arr = new Int32Array(5);
arr.fill(7);                     // Fill all with 7
console.log(arr);   // Output: Int32Array(5) [7, 7, 7, 7, 7]

arr.fill(0, 2, 4);               // Fill positions 2–3 with 0
console.log(arr);   // Output: Int32Array(5) [7, 7, 0, 0, 7]

const pixels = new Uint8Array([100, 150, 200, 250]);

// map — transform each element (returns same typed array type):
const brightened = pixels.map(p => Math.min(255, p + 50));
console.log(brightened);   // Output: Uint8Array(4) [150, 200, 250, 255]

// filter — select elements (returns same typed array type):
const bright = pixels.filter(p => p > 150);
console.log(bright);   // Output: Uint8Array(2) [200, 250]

// reduce — aggregate:
const total = pixels.reduce((sum, p) => sum + p, 0);
console.log(total);    // Output: 700

// find / findIndex:
const first  = pixels.find(p => p > 180);
const firstI = pixels.findIndex(p => p > 180);
console.log(first, firstI);   // Output: 200  2

// every / some:
console.log(pixels.every(p => p > 0));    // Output: true
console.log(pixels.some(p => p > 240));   // Output: true

// forEach:
pixels.forEach((val, idx) => console.log(`[${idx}]: ${val}`));

// TypedArray.from() — like Array.from, with an optional map function:
const doubled = Int16Array.from([1, 2, 3, 4, 5], x => x * 2);
console.log(doubled);   // Output: Int16Array(5) [2, 4, 6, 8, 10]

// TypedArray.of() — create from arguments:
const vals = Float32Array.of(1.1, 2.2, 3.3);
console.log(vals);   // Output: Float32Array(3) [1.1, 2.2, 3.3]

const nums = new Int16Array([40, -10, 5, 100, -3]);
nums.sort();
console.log(nums);   // Output: Int16Array(5) [-10, -3, 5, 40, 100]

// Custom comparator:
const desc = new Int16Array([40, -10, 5, 100, -3]);
desc.sort((a, b) => b - a);
console.log(desc);   // Output: Int16Array(5) [100, 40, 5, -3, -10]

const arr = new Float32Array([1.5, 2.7, 3.14]);

// To regular array:
const regular = Array.from(arr);
console.log(regular);   // Output: [1.5, 2.700000047683716, 3.140000104904175]
// Note: Float32 has limited precision — values are approximate

// To string:
console.log(arr.join(" | "));   // Output: 1.5 | 2.700000047683716 | 3.1400001049...
console.log(arr.toString());    // Output: 1.5,2.700000047683716,3.1400001049...

console.log(Int8Array.BYTES_PER_ELEMENT);      // Output: 1
console.log(Float32Array.BYTES_PER_ELEMENT);   // Output: 4
console.log(Float64Array.BYTES_PER_ELEMENT);   // Output: 8

console.log(Int8Array.name);    // Output: Int8Array

const buffer = new ArrayBuffer(16);   // Allocate 16 bytes of memory

console.log(buffer.byteLength);       // Output: 16
console.log(buffer instanceof ArrayBuffer);  // Output: true

const buffer = new ArrayBuffer(4);
console.log(buffer[0]);   // Output: undefined  ← can't read directly!

// You must create a view:
const view = new Uint8Array(buffer);
view[0] = 42;
console.log(view[0]);     // Output: 42

const buffer = new ArrayBuffer(4);   // 4 bytes

const u8   = new Uint8Array(buffer);    // 4 elements (1 byte each)
const u16  = new Uint16Array(buffer);   // 2 elements (2 bytes each)
const u32  = new Uint32Array(buffer);   // 1 element  (4 bytes each)

// Write a single 32-bit value:
u32[0] = 0x01020304;

// Observe how it's stored in bytes (little-endian on most systems):
console.log(u8[0].toString(16));  // Output: 4  (least significant byte first)
console.log(u8[1].toString(16));  // Output: 3
console.log(u8[2].toString(16));  // Output: 2
console.log(u8[3].toString(16));  // Output: 1  (most significant byte last)

// The 16-bit view sees two 16-bit numbers:
console.log(u16[0].toString(16)); // Output: 304
console.log(u16[1].toString(16)); // Output: 102

Value: 0x01020304 (decimal: 16909060)

Big-endian (network byte order):
Byte 0: 01   Byte 1: 02   Byte 2: 03   Byte 3: 04
(most significant first)

Little-endian (most CPUs: x86, ARM):
Byte 0: 04   Byte 1: 03   Byte 2: 02   Byte 3: 01
(least significant first)

const buffer = new ArrayBuffer(16);

// First Int32 view — covers bytes 0–3:
const view1 = new Int32Array(buffer, 0, 1);

// Second Int32 view — covers bytes 4–7:
const view2 = new Int32Array(buffer, 4, 1);

// Third Int32 view — covers bytes 8–15:
const view3 = new Int32Array(buffer, 8, 2);

view1[0] = 100;
view2[0] = 200;
view3[0] = 300;
view3[1] = 400;

// Read all through a full view:
const all = new Int32Array(buffer);
console.log(all);   // Output: Int32Array(4) [100, 200, 300, 400]

const original = new ArrayBuffer(8);
const view = new Uint8Array(original);
view.set([1, 2, 3, 4, 5, 6, 7, 8]);

// Copy bytes 2–5:
const copy = original.slice(2, 6);
const copyView = new Uint8Array(copy);
console.log(copyView);   // Output: Uint8Array(4) [3, 4, 5, 6]

// Modifying the copy does NOT affect the original:
copyView[0] = 99;
console.log(view[2]);    // Output: 3  ← original unchanged

// Main thread:
const buffer = new ArrayBuffer(1024 * 1024);  // 1MB
const view   = new Uint8Array(buffer);
view.fill(42);

// Transfer to Worker (zero-copy — buffer becomes unusable in main thread):
worker.postMessage({ data: buffer }, [buffer]);   // buffer in transfer list

// After transfer, buffer is detached:
console.log(buffer.byteLength);   // Output: 0  ← detached!
// console.log(view[0]);          // ❌ TypeError: buffer is detached

// Main thread:
const shared = new SharedArrayBuffer(4);   // 4 bytes, shared
const view   = new Int32Array(shared);
view[0] = 0;   // Initial value: 0

// Send to Worker (shared — NOT transferred, original still accessible):
worker.postMessage({ buffer: shared });

// Both threads can now read/write view[0] simultaneously
// (Use Atomics for safe concurrent access — see Chapter 6!)

const buffer = new ArrayBuffer(16);
const view   = new DataView(buffer);

// Optional offset and length:
const subView = new DataView(buffer, 4, 8);   // Start at byte 4, 8 bytes long

const buffer = new ArrayBuffer(16);
const view   = new DataView(buffer);

view.setUint8(0, 0xFF);               // Write byte 0xFF at byte offset 0
view.setInt16(1, -1000, true);        // Write int16 at offset 1 (little-endian)
view.setInt16(3, -1000, false);       // Write int16 at offset 3 (big-endian)
view.setFloat32(5, 3.14, true);       // Write float32 at offset 5 (little-endian)
view.setUint32(9, 0xDEADBEEF, true);  // Write uint32 at offset 9 (little-endian)

const buffer = new ArrayBuffer(16);
const view   = new DataView(buffer);

// Write some values:
view.setUint8(0, 255);
view.setInt32(1, -1, false);          // Big-endian
view.setFloat64(5, Math.PI, true);    // Little-endian

// Read them back:
console.log(view.getUint8(0));         // Output: 255
console.log(view.getInt32(1, false));  // Output: -1  (big-endian)
console.log(view.getFloat64(5, true)); // Output: 3.141592653589793  (little-endian)

const buffer = new ArrayBuffer(8);

// ❌ Typed array at odd offset:
const ta = new Int32Array(buffer, 1);   // RangeError: offset must be multiple of 4

// ✅ DataView at any offset:
const dv = new DataView(buffer);
dv.setInt32(1, 42);   // Perfectly fine — byte offset 1
console.log(dv.getInt32(1));   // Output: 42

// Simulate a binary file header:
// Bytes 0–1:  Magic number (0x4A53 = "JS" in ASCII)
// Bytes 2–5:  File version (uint32, big-endian)
// Bytes 6–9:  Data length in bytes (uint32, little-endian)
// Bytes 10–13: Scale factor (float32, little-endian)
// Byte  14:   Flags (uint8 bitmask)

const buffer = new ArrayBuffer(15);
const dv     = new DataView(buffer);

// Write (simulate file creation):
dv.setUint16(0,  0x4A53, false);       // Big-endian magic
dv.setUint32(2,  2,      false);       // Version 2, big-endian
dv.setUint32(6,  1024,   true);        // 1024 bytes of data, little-endian
dv.setFloat32(10, 1.5,   true);        // Scale 1.5x, little-endian
dv.setUint8(14, 0b00000101);           // Flags: bit 0 and bit 2 set

// Read (simulate file parsing):
const magic    = dv.getUint16(0, false);
const version  = dv.getUint32(2, false);
const dataLen  = dv.getUint32(6, true);
const scale    = dv.getFloat32(10, true);
const flags    = dv.getUint8(14);

console.log("Magic:",   magic.toString(16).toUpperCase()); // Output: 4A53
console.log("Version:", version);          // Output: 2
console.log("Data len:",dataLen);           // Output: 1024
console.log("Scale:",   scale);            // Output: 1.5
console.log("Flags:",   flags.toString(2).padStart(8, "0")); // Output: 00000101
console.log("Flag 0 set?", !!(flags & 0b00000001));  // Output: true
console.log("Flag 1 set?", !!(flags & 0b00000010));  // Output: false
console.log("Flag 2 set?", !!(flags & 0b00000100));  // Output: true

const buffer = new ArrayBuffer(32);
const view   = new DataView(buffer, 8, 16);   // Start at byte 8, 16 bytes long

console.log(view.buffer);       // Output: ArrayBuffer { byteLength: 32 }  ← the full buffer
console.log(view.byteOffset);   // Output: 8    ← starting byte
console.log(view.byteLength);   // Output: 16   ← length of this view

// Single thread — no atomics needed:
const arr = new Int32Array(new ArrayBuffer(4));
arr[0]++;   // Safe — no other thread can see this

// Multi-thread — atomics required:
const shared = new SharedArrayBuffer(4);
const sarr   = new Int32Array(shared);
// ❌ sarr[0]++ — NOT safe if multiple workers do this simultaneously
// ✅ Atomics.add(sarr, 0, 1)  — safe

const shared = new SharedArrayBuffer(4);
const sarr   = new Int32Array(shared);
sarr[0] = 10;

const before = Atomics.add(sarr, 0, 5);   // Atomically: sarr[0] += 5
console.log(before);     // Output: 10   ← value BEFORE the add
console.log(sarr[0]);    // Output: 15   ← value AFTER

const before2 = Atomics.sub(sarr, 0, 3);  // Atomically: sarr[0] -= 3
console.log(before2);    // Output: 15
console.log(sarr[0]);    // Output: 12

const shared = new SharedArrayBuffer(4);
const sarr   = new Int32Array(shared);

Atomics.store(sarr, 0, 42);        // Write 42 atomically
const value = Atomics.load(sarr, 0); // Read atomically
console.log(value);   // Output: 42

const shared = new SharedArrayBuffer(4);
const sarr   = new Int32Array(shared);
sarr[0] = 100;

const old = Atomics.exchange(sarr, 0, 999);
console.log(old);      // Output: 100  ← previous value
console.log(sarr[0]);  // Output: 999  ← new value

Atomics.compareExchange(typedArray, index, expectedValue, replacementValue)
// Returns the ACTUAL value before the operation
// If actual === expected → replaces with replacement → returns expected
// If actual !== expected → does nothing → returns actual

const shared = new SharedArrayBuffer(4);
const sarr   = new Int32Array(shared);
sarr[0] = 5;

// Try to change 5 → 10 (should succeed):
const result1 = Atomics.compareExchange(sarr, 0, 5, 10);
console.log(result1);   // Output: 5   ← old value (5 === expected, so swap happened)
console.log(sarr[0]);   // Output: 10  ← updated!

// Try to change 5 → 20 (should fail — current value is 10, not 5):
const result2 = Atomics.compareExchange(sarr, 0, 5, 20);
console.log(result2);   // Output: 10  ← actual value (10 !== 5, so no swap)
console.log(sarr[0]);   // Output: 10  ← unchanged

// Lock convention: 0 = unlocked, 1 = locked

function lock(sarr, index) {
  // Spin until we successfully change 0 → 1 (acquire the lock):
  while (Atomics.compareExchange(sarr, index, 0, 1) !== 0) {
    Atomics.wait(sarr, index, 1);   // Sleep while locked (see 6.7)
  }
}

function unlock(sarr, index) {
  Atomics.store(sarr, index, 0);     // Release the lock
  Atomics.notify(sarr, index, 1);    // Wake one waiting thread
}

const shared = new SharedArrayBuffer(4);
const sarr   = new Uint32Array(shared);
sarr[0] = 0b00001111;

// AND — keep only bits that are set in both:
console.log(Atomics.and(sarr, 0, 0b00110011));
console.log(sarr[0].toString(2));   // Output: 11  (0b00001111 & 0b00110011)

sarr[0] = 0b00001111;
// OR — set all bits that are set in either:
console.log(Atomics.or(sarr, 0, 0b00110011));
console.log(sarr[0].toString(2));   // Output: 111111  (0b00001111 | 0b00110011)

sarr[0] = 0b00001111;
// XOR — flip bits that differ:
console.log(Atomics.xor(sarr, 0, 0b00110011));
console.log(sarr[0].toString(2));   // Output: 111100  (0b00001111 ^ 0b00110011)

// Worker thread code:
const shared = new SharedArrayBuffer(4);
const sarr   = new Int32Array(shared);

// Worker sleeps until sarr[0] is no longer 0:
const result = Atomics.wait(sarr, 0, 0);
// (Thread sleeps here until notify() is called)
console.log("Woken up! Result:", result);   // Output: Woken up! Result: ok

// Main thread wakes up waiting workers:
Atomics.store(sarr, 0, 1);           // Change the value first
Atomics.notify(sarr, 0, 1);          // Wake 1 waiting thread

console.log(Atomics.isLockFree(1));   // Output: true  — hardware atomic for 1-byte values
console.log(Atomics.isLockFree(2));   // Output: true
console.log(Atomics.isLockFree(4));   // Output: true  — most important (Int32Array)
console.log(Atomics.isLockFree(8));   // Output: true on 64-bit systems, false on 32-bit

// --- Sensor packet format (32 bytes) ---
// Byte 0:     Sensor ID       (Uint8)
// Byte 1:     Packet type     (Uint8: 0=status, 1=reading, 2=alert)
// Bytes 2–3:  Sequence number (Uint16, big-endian)
// Bytes 4–7:  Timestamp       (Uint32, little-endian, Unix ms mod 2³²)
// Bytes 8–11: Reading value   (Float32, little-endian)
// Bytes 12–15: Battery level  (Float32, little-endian, 0.0–1.0)
// Bytes 16–19: Temperature    (Float32, little-endian, Celsius)
// Bytes 20–23: Latitude       (Float32, little-endian)
// Bytes 24–27: Longitude      (Float32, little-endian)
// Bytes 28–29: Status flags   (Uint16, little-endian bitmask)
// Bytes 30–31: CRC checksum   (Uint16, big-endian)

const PACKET_SIZE = 32;

const PacketType = Object.freeze({ STATUS: 0, READING: 1, ALERT: 2 });
const StatusFlag = Object.freeze({
  ONLINE:      0b0000000000000001,
  LOW_BATTERY: 0b0000000000000010,
  OVERHEATING: 0b0000000000000100,
  DATA_ERROR:  0b0000000000001000,
});

function encodeSensorPacket(sensor) {
  const buffer = new ArrayBuffer(PACKET_SIZE);
  const dv     = new DataView(buffer);

  dv.setUint8(0,   sensor.id);
  dv.setUint8(1,   sensor.type);
  dv.setUint16(2,  sensor.sequence, false);    // Big-endian sequence
  dv.setUint32(4,  sensor.timestamp, true);    // Little-endian timestamp
  dv.setFloat32(8, sensor.reading,   true);
  dv.setFloat32(12, sensor.battery,  true);
  dv.setFloat32(16, sensor.temperature, true);
  dv.setFloat32(20, sensor.latitude,    true);
  dv.setFloat32(24, sensor.longitude,   true);
  dv.setUint16(28, sensor.flags,     true);

  // Simple checksum: XOR all bytes 0–29:
  let crc = 0;
  const bytes = new Uint8Array(buffer, 0, 30);
  for (const byte of bytes) crc ^= byte;
  dv.setUint16(30, crc, false);   // Big-endian CRC

  return buffer;
}

function decodeSensorPacket(buffer) {
  const dv = new DataView(buffer);

  // Verify CRC:
  let crc = 0;
  const bytes = new Uint8Array(buffer, 0, 30);
  for (const byte of bytes) crc ^= byte;
  const storedCRC = dv.getUint16(30, false);
  if (crc !== storedCRC) throw new Error("CRC mismatch — packet corrupted");

  const flags = dv.getUint16(28, true);

  return {
    id:          dv.getUint8(0),
    type:        dv.getUint8(1),
    sequence:    dv.getUint16(2, false),
    timestamp:   dv.getUint32(4, true),
    reading:     dv.getFloat32(8, true),
    battery:     dv.getFloat32(12, true),
    temperature: dv.getFloat32(16, true),
    latitude:    dv.getFloat32(20, true),
    longitude:   dv.getFloat32(24, true),
    flags,
    isOnline:    !!(flags & StatusFlag.ONLINE),
    lowBattery:  !!(flags & StatusFlag.LOW_BATTERY),
    overheating: !!(flags & StatusFlag.OVERHEATING),
  };
}

// Test:
const packet = encodeSensorPacket({
  id: 7, type: PacketType.READING, sequence: 1024,
  timestamp: Date.now() & 0xFFFFFFFF,
  reading: 23.45, battery: 0.72, temperature: 31.2,
  latitude: 6.5244, longitude: 3.3792,
  flags: StatusFlag.ONLINE
});

const decoded = decodeSensorPacket(packet);
console.log(`Sensor ${decoded.id}: ${decoded.reading.toFixed(2)} @ ${decoded.battery.toFixed(0) * 100}% battery`);
// Output: Sensor 7: 23.45 @ 72% battery

// A circular ring buffer for sensor packets using a single large ArrayBuffer:
class SensorRingBuffer {
  #buffer;
  #view;
  #capacity;
  #writeHead;
  #count;

  constructor(capacity) {
    this.#capacity  = capacity;
    this.#buffer    = new ArrayBuffer(capacity * PACKET_SIZE);
    this.#view      = new Uint8Array(this.#buffer);
    this.#writeHead = 0;
    this.#count     = 0;
  }

  push(packetBuffer) {
    const src    = new Uint8Array(packetBuffer);
    const offset = this.#writeHead * PACKET_SIZE;

    // Use set() for fast bulk copy:
    this.#view.set(src, offset);

    this.#writeHead = (this.#writeHead + 1) % this.#capacity;
    if (this.#count < this.#capacity) this.#count++;
  }

  get(index) {
    if (index >= this.#count) throw new RangeError("Index out of bounds");
    const offset = index * PACKET_SIZE;

    // Return a subarray view — zero copy:
    return this.#buffer.slice(offset, offset + PACKET_SIZE);
  }

  // Get all packets as an array of decoded objects:
  decodeAll() {
    const results = [];
    for (let i = 0; i < this.#count; i++) {
      try {
        results.push(decodeSensorPacket(this.get(i)));
      } catch (e) {
        results.push({ error: e.message, index: i });
      }
    }
    return results;
  }

  get size()     { return this.#count; }
  get isFull()   { return this.#count === this.#capacity; }
  get byteUsed() { return this.#count * PACKET_SIZE; }
}

// Test the ring buffer:
const ringBuffer = new SensorRingBuffer(100);

// Simulate receiving 5 sensor packets:
for (let i = 0; i < 5; i++) {
  const pkt = encodeSensorPacket({
    id: i + 1, type: PacketType.READING, sequence: i,
    timestamp: (Date.now() + i * 1000) & 0xFFFFFFFF,
    reading: 20 + Math.random() * 10,
    battery: 0.5 + Math.random() * 0.5,
    temperature: 25 + Math.random() * 15,
    latitude: 6.5 + Math.random() * 0.1,
    longitude: 3.3 + Math.random() * 0.1,
    flags: StatusFlag.ONLINE
  });
  ringBuffer.push(pkt);
}

console.log(`Buffer size: ${ringBuffer.size} packets (${ringBuffer.byteUsed} bytes)`);
// Output: Buffer size: 5 packets (160 bytes)

// Simulate a 32×32 grayscale sensor snapshot as RGBA data:
class SensorImage {
  #pixels;
  #width;
  #height;

  constructor(width, height) {
    this.#width  = width;
    this.#height = height;
    this.#pixels = new Uint8ClampedArray(width * height * 4);
  }

  static fromGrayscaleData(grayData, width, height) {
    const img = new SensorImage(width, height);
    for (let i = 0; i < grayData.length; i++) {
      const px = i * 4;
      img.#pixels[px]     = grayData[i];   // R
      img.#pixels[px + 1] = grayData[i];   // G
      img.#pixels[px + 2] = grayData[i];   // B
      img.#pixels[px + 3] = 255;           // A (fully opaque)
    }
    return img;
  }

  // Apply threshold: pixels above threshold → white, below → black:
  threshold(level) {
    const result = new SensorImage(this.#width, this.#height);
    for (let i = 0; i < this.#pixels.length; i += 4) {
      const gray  = this.#pixels[i];
      const value = gray >= level ? 255 : 0;
      result.#pixels.set([value, value, value, 255], i);
    }
    return result;
  }

  // Brighten by delta (clamping handled automatically by Uint8ClampedArray):
  brighten(delta) {
    const result = new SensorImage(this.#width, this.#height);
    for (let i = 0; i < this.#pixels.length; i += 4) {
      result.#pixels[i]     = this.#pixels[i]     + delta;
      result.#pixels[i + 1] = this.#pixels[i + 1] + delta;
      result.#pixels[i + 2] = this.#pixels[i + 2] + delta;
      result.#pixels[i + 3] = this.#pixels[i + 3];   // Preserve alpha
    }
    return result;
  }

  // Histogram: count pixels in each 0–255 intensity bucket:
  histogram() {
    const hist = new Uint32Array(256);
    for (let i = 0; i < this.#pixels.length; i += 4) {
      hist[this.#pixels[i]]++;   // Count red channel (R=G=B for grayscale)
    }
    return hist;
  }

  // Compute mean intensity:
  meanIntensity() {
    const hist  = this.histogram();
    let total   = 0;
    let pixels  = 0;
    for (let i = 0; i < 256; i++) {
      total  += i * hist[i];
      pixels += hist[i];
    }
    return total / pixels;
  }

  get data()   { return this.#pixels; }
  get width()  { return this.#width; }
  get height() { return this.#height; }
}

// Simulate a sensor snapshot:
const grayValues = new Uint8Array(32 * 32);
for (let i = 0; i < grayValues.length; i++) {
  grayValues[i] = Math.floor(50 + 150 * Math.abs(Math.sin(i * 0.1)));
}

const img = SensorImage.fromGrayscaleData(grayValues, 32, 32);
const brightened = img.brighten(50);
const thresholded = img.threshold(128);

console.log("Original mean:", img.meanIntensity().toFixed(1));
console.log("Brightened mean:", brightened.meanIntensity().toFixed(1));

// Shared statistics counters between main thread and workers.
// Layout (all Int32):
// Index 0: Total packets received
// Index 1: Total packets processed
// Index 2: Total errors
// Index 3: Lock flag (0=unlocked, 1=locked)

const STAT_RECEIVED   = 0;
const STAT_PROCESSED  = 1;
const STAT_ERRORS     = 2;
const LOCK_INDEX      = 3;

class SharedStats {
  #sarr;

  constructor(sharedBuffer) {
    this.#sarr = new Int32Array(sharedBuffer);
  }

  incrementReceived()  { return Atomics.add(this.#sarr, STAT_RECEIVED, 1); }
  incrementProcessed() { return Atomics.add(this.#sarr, STAT_PROCESSED, 1); }
  incrementErrors()    { return Atomics.add(this.#sarr, STAT_ERRORS, 1); }

  getReceived()   { return Atomics.load(this.#sarr, STAT_RECEIVED); }
  getProcessed()  { return Atomics.load(this.#sarr, STAT_PROCESSED); }
  getErrors()     { return Atomics.load(this.#sarr, STAT_ERRORS); }

  getReport() {
    return {
      received:  this.getReceived(),
      processed: this.getProcessed(),
      errors:    this.getErrors(),
      pending:   this.getReceived() - this.getProcessed() - this.getErrors()
    };
  }

  reset() {
    Atomics.store(this.#sarr, STAT_RECEIVED,  0);
    Atomics.store(this.#sarr, STAT_PROCESSED, 0);
    Atomics.store(this.#sarr, STAT_ERRORS,    0);
  }
}

// Simulate processing 20 packets with some errors:
const statsBuffer = new SharedArrayBuffer(4 * 4);   // 4 Int32 values
const stats       = new SharedStats(statsBuffer);

for (let i = 0; i < 20; i++) {
  stats.incrementReceived();

  // Simulate 10% error rate:
  if (Math.random() < 0.1) {
    stats.incrementErrors();
  } else {
    stats.incrementProcessed();
  }
}

const report = stats.getReport();
console.log("\n=== Processing Report ===");
console.log(`Received:  ${report.received}`);
console.log(`Processed: ${report.processed}`);
console.log(`Errors:    ${report.errors}`);
console.log(`Pending:   ${report.pending}`);

class SensorPipeline {
  #ringBuffer;
  #stats;
  #imageStore;

  constructor(bufferCapacity = 100) {
    this.#ringBuffer = new SensorRingBuffer(bufferCapacity);
    const statsBuffer = new SharedArrayBuffer(4 * 4);
    this.#stats      = new SharedStats(statsBuffer);
    this.#imageStore = new Map();
  }

  // Accept a raw ArrayBuffer (from WebSocket):
  receivePacket(rawBuffer) {
    this.#stats.incrementReceived();
    try {
      const packet = decodeSensorPacket(rawBuffer);
      this.#ringBuffer.push(rawBuffer);
      this.#stats.incrementProcessed();
      return packet;
    } catch (e) {
      this.#stats.incrementErrors();
      console.warn("Packet decode failed:", e.message);
      return null;
    }
  }

  // Process all buffered packets and generate a status report:
  generateReport() {
    const packets = this.#ringBuffer.decodeAll();
    const valid   = packets.filter(p => !p.error);
    const stats   = this.#stats.getReport();

    // Aggregate by sensor ID:
    const bySensor = new Map();
    for (const packet of valid) {
      if (!bySensor.has(packet.id)) {
        bySensor.set(packet.id, { id: packet.id, count: 0, readings: [] });
      }
      const sensor = bySensor.get(packet.id);
      sensor.count++;
      sensor.readings.push(packet.reading);
    }

    // Compute averages using Float32Array for efficiency:
    const summary = [];
    for (const [id, sensor] of bySensor) {
      const fa  = new Float32Array(sensor.readings);
      const avg = fa.reduce((s, v) => s + v, 0) / fa.length;
      const max = fa.reduce((m, v) => Math.max(m, v), -Infinity);
      const min = fa.reduce((m, v) => Math.min(m, v),  Infinity);
      summary.push({ id, count: sensor.count, avg, max, min });
    }

    return {
      pipeline: stats,
      sensors: summary.sort((a, b) => a.id - b.id),
      bufferUsage: `${this.#ringBuffer.size} / ${this.#ringBuffer.isFull ? "FULL" : "OK"}`
    };
  }
}

// Run the full pipeline:
const pipeline = new SensorPipeline(100);

// Simulate 15 incoming packets from 3 sensors:
for (let seq = 0; seq < 15; seq++) {
  const sensorId = (seq % 3) + 1;
  const buf = encodeSensorPacket({
    id: sensorId, type: PacketType.READING, sequence: seq,
    timestamp: (Date.now() + seq * 100) & 0xFFFFFFFF,
    reading: 20 + sensorId * 5 + Math.sin(seq) * 2,
    battery: 0.8 - seq * 0.01, temperature: 28 + sensorId,
    latitude: 6.5244 + sensorId * 0.01, longitude: 3.3792,
    flags: StatusFlag.ONLINE
  });
  pipeline.receivePacket(buf);
}

const report = pipeline.generateReport();
console.log("\n========= PIPELINE REPORT =========");
console.log("Buffer:", report.bufferUsage);
console.log("Stats:", report.pipeline);
console.log("\nSensor Summaries:");
for (const s of report.sensors) {
  console.log(`  Sensor ${s.id}: ${s.count} readings | avg=${s.avg.toFixed(2)} min=${s.min.toFixed(2)} max=${s.max.toFixed(2)}`);
}

const buffer = new ArrayBuffer(12);
const dv     = new DataView(buffer);
dv.setUint32(4, 0xDEADBEEF, true);  // Write something first
console.log(dv.getUint32(4, true).toString(16));  // Read as little-endian Uint32