An interactive educational tool built with Vue.js and Vite that simulates the internal mechanics of the Go (Golang) map data structure.

This project aims to demystify the "black box" of Go maps by visualising the memory layout, bucket allocation, hashing strategies, and collision resolution in real time.

In Go, maps are efficient and easy to use, but their internal implementation is a sophisticated engineering feat. This application simulates the Go Runtime logic to demonstrate:

• The hmap Header: How metadata like count and B (log buckets) manage the structure.
• Bucket Architecture: Visualising fixed-size buckets that hold eight key/value pairs.
• Smart Hashing: How the hash is split into High-Order Bits (Tophash) and Low-Order Bits (Bucket Index).
• Memory Optimization: How keys and values are packed separately (keys[8], values[8]) to eliminate padding.
• Overflow Chaining: How the map handles collisions by linking to overflow buckets.

• Interactive Insertion: Add random or specific keys to see how they are hashed and placed.
• Visual Hashing: Watch the binary split of the hash between LOB (Bucket selection) and HOB (Tophash).
• Memory X-Ray: Click on any bucket to inspect its internal memory layout (Tophash arrays vs Key arrays).
• Overflow Simulation: Force keys into specific buckets to visualise linked-list chaining.
• Growth Trigger: Simulate "Evacuation" by forcing the map to resize when the load factor exceeds 6.5.

• Framework: Vue 3 (Composition API)
• Build Tool: Vite
• Styling: CSS3 (Grid/Flexbox)

You can follow these steps to get a local copy up and running.

• Node.js (v16.0 or higher)
• npm or yarn

1. Clone the repository

   git@github.com:gocanto/go-maps.git
   cd go-maps

2. Install dependencies

   npm install

3. Start the development server

   npm run dev

4. Open your browser Navigate to the Local URL provided in the terminal (usually http://localhost:5173).

Unlike generic hash maps, Go uses buckets. Each bucket is a fixed-size memory block holding exactly eight key/value pairs.

Inside a bucket, data is packed as [8 Tophashes] + [8 Keys] + [8 Values]. This structure eliminates padding bytes between keys and values, optimising CPU cache locality.

Go uses Chaining. If a bucket fills up (8 items), it allocates a new "overflow bucket" and links to it, creating a linked list of blocks rather than individual nodes.

The map grows when the average Load Factor exceeds 6.5. It allocates a double-sized array and incrementally "evacuates" data from old buckets to new ones to prevent latency spikes.

Please feel free to fork this repository and submit a pull request to enhance it with functionality or bug fixes.

Please see License File for more information.

There are many ways you can support my open source work. There is no correct answer, so the choice is yours.

Nevertheless, I propose the following.

• ⬆️ Follow me on Twitter.
• ⭐ Star the repository.
• 🤝 Open a pull request to fix/improve the codebase.
• ✍️ Open a pull request to improve the documentation.
• ☕ Buy me a coffee?

Thank you for reading this far. 😊