DEV Community: Doogal Simpson

How to Safely Handle Currencies in Code with ISO 4217

Doogal Simpson — Tue, 13 Oct 2026 07:13:48 +0000

Storing money as integers prevents floating-point precision loss, but hardcoding a 100x multiplier assumes every currency works like USD or EUR. Under ISO 4217, currencies vary from zero decimal places (JPY) to three (KWD). To avoid catastrophic overcharging or rounding loss, treat currency decimal scale as dynamic metadata tied to the ISO code.

Every software engineer learns the golden rule of financial software early on: never store monetary values as floating-point numbers. Floating-point arithmetic introduces IEEE 754 precision errors that turn fractions of a cent into accounting discrepancies.

So, we switch to integers, store values in the currency's smallest minor unit, and move on. But there is a hidden trap hiding inside that naive solution.

Why Does the "Multiply by 100" Strategy Fail Globally?

Hardcoding a 100 multiplier assumes every global currency uses two decimal places, which is incorrect. ISO 4217 defines over 30 zero-decimal currencies and several three-decimal currencies. Applying a fixed multiplier leads to severe overcharging or truncation errors depending on the target currency.

Imagine you run an e-commerce platform expanding into Japan. A customer buys a coffee for 500 Japanese Yen (JPY). If your payment service naively executes amount * 100 before passing the integer to an API like Stripe, it sends 50000.

Because payment gateways respect ISO 4217 standards, they interpret zero-decimal currencies as whole units. Your script just charged the customer 50,000 yen for a 500-yen coffee.

The bug bites in reverse for three-decimal currencies like the Kuwaiti Dinar (KWD), where 1 Dinar divides into 1,000 fils. Assuming two decimal places makes it impossible to represent the third digit, silently chopping off fils as a rounding error on every transaction.

How Does ISO 4217 Define Currency Minor Units?

The ISO 4217 standard assigns an explicit minor unit exponent (scale) to every official currency code. This exponent represents the number of decimal places required to convert a major currency unit into its smallest sub-unit.

Money isn't uniform. You cannot treat currency as a pure numeric value; it is a composite structure of a value and its ISO 4217 metadata.

Here is how common ISO 4217 currencies break down by decimal exponent:

Currency Code	Currency Name	Decimal Exponent	Minor Unit Name	Example (1 Major Unit in Minor Units)
USD	US Dollar	2	Cent	100 cents
JPY	Japanese Yen	0	N/A	1 Yen
KWD	Kuwaiti Dinar	3	Fils	1,000 fils
BHD	Bahraini Dinar	3	Fils	1,000 fils
CLF	Unidad de Fomento	4	Unidades	10,000 unidades

Notice that while two decimal places is common, it is far from universal. Over 30 currencies have zero decimal places, seven have three, and some non-standard currencies do not even use base 10.

How Do You Safely Handle Currency Conversion in Code?

Rather than multiplying by a hardcoded number, look up the currency exponent dynamically from a verified ISO 4217 registry. Use exponent-based scaling (10^scale) or specialized currency handling libraries to convert major units into minor units.

Here is how you can look up the exponent and compute the minor unit dynamically:

const ISO_CURRENCY_EXPONENTS: Record<string, number> = {
  USD: 2, EUR: 2, GBP: 2, JPY: 0, KWD: 3, BHD: 3
};

function toMinorUnits(amount: number, currencyCode: string): number {
  const exponent = ISO_CURRENCY_EXPONENTS[currencyCode.toUpperCase()];
  if (exponent === undefined) {
    throw new Error(`Unsupported currency code: ${currencyCode}`);
  }
  return Math.round(amount * Math.pow(10, exponent));
}

By looking up the exponent dynamically, toMinorUnits(500, 'JPY') correctly returns 500, while toMinorUnits(1.5, 'KWD') returns 1500.

Frequently Asked Questions

Which ISO 4217 currencies have zero decimal places?

Over 30 currencies do not use minor units, including the Japanese Yen (JPY), South Korean Won (KRW), Chilean Peso (CLP), and Vietnamese Dong (VND). When interacting with payment processors, these values must be passed as unscaled integers.

How do payment APIs like Stripe handle zero-decimal currencies?

Stripe expects monetary values in the smallest currency unit but respects ISO 4217 exponent definitions. For USD, sending 1000 means $10.00. For JPY, sending 1000 means 1,000 Yen.

Should I store money as integers or decimals in a database?

Store monetary amounts as integers representing the minor unit alongside the three-letter ISO 4217 currency code. Alternatively, store major units in arbitrary-precision decimal columns (e.g., DECIMAL(18, 4)) to accommodate high-scale precision safely.

How to Prevent Retry Storms in Microservices

Doogal Simpson — Sun, 11 Oct 2026 14:26:56 +0000

Quick Answer: A retry storm occurs when deeply nested microservices independently retry failed downstream requests, causing exponential traffic amplification. If five services in a chain each retry three times upon failure, a single user click generates 243 requests against an already struggling database. Exponential backoff delays the traffic, but solving the issue requires retry budgets and circuit breakers.

Microservices give us isolation, scalability, and independent deployment cycles. However, they also introduce subtle feedback loops that can convert a minor transient glitch into a full-scale infrastructure outage.

If you have ever watched a database collapse under traffic during a mild network blip, you have likely witnessed a retry storm in action. Let's look at how standard resiliency defaults can inadvertently multiply traffic and destroy your systems.

What is a retry storm in microservice architecture?

An exponential retry storm is a cascading failure scenario where multiple upstream services independently retry failed downstream requests. Instead of recovering from a transient error, the accumulated retries exponentially amplify traffic against a failing dependency or database.

Imagine a standard architecture where a user click flows through five sequential hops: an API Gateway, three microservices, and a final service querying a primary database. If the database experiences a momentary connection drop, the service directly above it times out and executes three retries.

Because that service times out, the service upstream from it also times out and executes its own three retries. Each of those retries triggers three new attempts downstream. By the time this failure cascades up and back down a five-service stack, your request count scales as powers of three.

Call Stack Hop	Retry Math	Cumulative Requests to Dependency
Hop 1 (Service 4 to DB)	3^1	3
Hop 2 (Service 3 to Service 4)	3^2	9
Hop 3 (Service 2 to Service 3)	3^3	27
Hop 4 (Service 1 to Service 2)	3^4	81
Hop 5 (Gateway to Service 1)	3^5	243

What started as a single HTTP request from a client becomes 243 aggressive hits pounding an already failing database.

Why doesn't exponential backoff with jitter prevent retry storms?

Exponential backoff and jitter change when retries happen to avoid synchronized traffic spikes, but they do not reduce the total volume of requests. In a multi-hop architecture, the total math remains unchanged, meaning your dying database still receives the same amplified payload of retries.

Adding backoff and random jitter is excellent practice for avoiding the "thundering herd" problem on single-service calls. It spreads request attempts over a wider time window. However, when you have five layers of microservices all maintaining their own independent backoff clocks, you are merely staggering the delivery of those 243 requests. You have changed the schedule of the avalanche, but you haven't reduced the snow.

How do you prevent exponential request multiplication in microservices?

To stop retry multiplication, you must enforce request-level limits and fail fast rather than allowing every service in a call stack to retry blindly. The two primary patterns for mitigation are retry budgets and circuit breakers.

Here is how to stop the amplification loop:

Retry Budgets: Limit the percentage of total traffic dedicated to retries across a service instance. For example, if you set a retry budget of 10%, a service will refuse to retry if retries account for more than 10% of its total incoming calls. Once the budget is exhausted, downstream failures return immediately to the caller.
Circuit Breakers: Monitor error rates over a rolling time window. If a downstream dependency fails beyond a set threshold (e.g., 50% error rate over 10 seconds), the circuit breaker opens and immediately trips subsequent requests without attempting network calls or retries.
Single-Layer Retries: Restrict retries to a specific layer in the call stack—typically the edge or the immediate caller of the database—rather than enabling retries inside every client SDK down the chain.

Frequently Asked Questions

What is a retry budget in microservices?

A retry budget is a safety mechanism that caps retries to a maximum percentage (typically 10%) of total service traffic. If a service experiences widespread downstream failures, the budget depletes rapidly, preventing the service from launching an excessive number of retries.

Should microservices retry on all HTTP 5xx errors?

No. Microservices should only retry on idempotent requests and specific transient errors, such as 503 Service Unavailable or 504 Gateway Timeout. Retrying non-idempotent operations or persistent errors like 500 Internal Server Error often causes duplicate side effects and worsens system load.

How does a circuit breaker differ from a retry mechanism?

A retry mechanism attempts to re-send failed requests in hopes that a transient issue has resolved. A circuit breaker actively prevents calls from being executed once a downstream service crosses a failure threshold, failing fast to allow the system time to recover.

Preventing Timing Attacks with Constant-Time Comparisons

Doogal Simpson — Sat, 10 Oct 2026 09:53:53 +0000

TL;DR: Using standard comparison operators like == to validate API keys or cryptographic signatures leaks secrets byte-by-byte. Because standard operators return early upon encountering a mismatch, attackers can measure tiny response-time differences to brute-force your keys. Replacing them with constant-time comparison functions completely neutralizes this vulnerability.

Imagine trying to crack a physical safe. Usually, you must guess the entire combination at once. But what if the dial gave a faint, satisfying "click" the moment you got just the first digit right? Suddenly, your search space collapses. Instead of guessing a million combinations, you only need to try ten digits to find the first one, ten for the second, and so on.

In software, standard string comparison operators do exactly this: they "click" when you get a character right, leaking your secrets one byte at a time.

How does a timing attack exploit standard string comparisons?

Standard comparison operators evaluate strings from left to right and terminate immediately upon finding the first mismatched byte. This early-return behavior allows an attacker to guess a secret byte-by-byte by measuring microsecond differences in API response times.

When you compare a 32-character API key using a standard comparison like if (apiKey == inputKey), the CPU does not analyze all 32 characters simultaneously. It evaluates them sequentially. If the very first character of the user's input is wrong, the engine is optimized to return false instantly.

However, if the first character is correct, the engine moves on to check the second character. This additional step takes a tiny fraction of a nanosecond. If an attacker repeatedly sends requests to your endpoint, they can use statistical analysis to filter out network noise and identify which characters caused the server to respond just a fraction of a nanosecond slower. By keeping the slowest-responding character and moving to the next position, they can brute-force a highly secure signature or token in a fraction of the time. This exact vulnerability famously compromised Google's Keyczar cryptography library in 2009.

How does constant-time comparison solve this vulnerability?

Constant-time comparison functions evaluate every single character in both strings regardless of where a mismatch occurs, ensuring the execution time is identical for every input. This uniformity denies attackers the timing variance they need to deduce the correct characters.

To prevent this timing leak, we must strip away the performance optimization of early-return. We need to force the CPU to walk through every single byte of both strings, comparing them all, and only returning a boolean result at the very end of the loop.

Why does Node's timingSafeEqual require a hashing pre-step?

In Node.js, crypto.timingSafeEqual() throws a critical RangeError if the compared buffers are of unequal length, which can crash your application. Hashing both inputs with SHA-256 before comparing them guarantees equal-length buffers and masks the true length of the secret key.

If you simply compare the string lengths before using timingSafeEqual, you leak the exact length of your secret key to attackers via the execution time of that length check. By hashing both the secret and the user input with SHA-256 first, you transform both values into identical-length 32-byte buffers. This bypasses the buffer-length constraint safely without crashing or leaking details.

import crypto from 'crypto';

const isSecure = (secretKey, userInput) => {
  // Hash both to fixed-length buffers to avoid RangeErrors and length-leakage
  const hashA = crypto.createHash('sha256').update(secretKey).digest();
  const hashB = crypto.createHash('sha256').update(userInput).digest();

  return crypto.timingSafeEqual(hashA, hashB);
};

What are the best practices for implementing constant-time checks?

To implement these checks securely, you should leverage native cryptographic libraries and normalize your input lengths using hashing. This prevents compiler optimizations or unexpected runtime crashes when comparing user-supplied data against your secrets.

Most modern backend runtimes provide safe utility functions out of the box. When verifying webhooks, API tokens, or cryptographic signatures, reference the table below to select the appropriate comparison method for your stack:

Language / Runtime	Standard Vulnerable Comparison	Constant-Time Secure Function
Node.js	`a === b`	`crypto.timingSafeEqual(bufA, bufB)`
Python	`a == b`	`hmac.compare_digest(a, b)`
Go	`a == b`	`subtle.ConstantTimeCompare(a, b)`
PHP	`a === b`	`hash_equals(a, b)`

Can timing attacks be executed reliably over the public internet?

Yes, though it requires more statistical sampling. While public internet routing introduces substantial latency variance (jitter), attackers can easily bypass this noise by sending thousands of requests and analyzing the statistical distribution of response times to extract the timing signal.

Does using HTTPS or encryption protect against timing attacks?

No, HTTPS only encrypts the payload in transit to prevent eavesdropping. It does not alter the processing execution path on your application server, meaning an attacker can still measure the exact interval between when a request is fully sent and when the first byte of the response is received.

Should I use constant-time comparison for all string checks?

No, you only need constant-time comparisons for security-sensitive strings such as API keys, password reset tokens, signatures, and session IDs. Using it for standard routing, usernames, or public string matches adds unnecessary performance overhead without providing any security benefits.

Fixing Node.js Localhost ECONNREFUSED Connection Errors

Doogal Simpson — Sat, 10 Oct 2026 09:35:09 +0000

Quick Answer: Node 17 broke local connections by switching from hardcoded IPv4 (127.0.0.1) lookups to the operating system’s default order, which prioritizes IPv6 (::1). If your server listened only on IPv4, connections failed immediately. Node 20 resolved this by implementing the "Happy Eyeballs" algorithm, which automatically falls back to IPv4 if IPv6 fails.

I’ve run into a frustrating issue more than once: upgrading a Node version only to find that a local service suddenly throws ECONNREFUSED on a port that is clearly open. The server is running, the configuration looks right, but the connection fails. This headache started with Node 17, which changed how Node.js resolves localhost. Here is why this broke and how Node 20 resolves the issue.

Why did Node 17 cause connection refused errors on localhost?

Node 17 stopped hardcoding IPv4 (127.0.0.1) as the default fallback for localhost and began respecting the operating system’s default lookup order, which prioritizes IPv6 (::1). If a local server only listens on IPv4, the client-side Node process attempts to connect via IPv6, gets refused immediately, and fails the connection.

When I look at how operating systems resolve names, a machine typically has two loopback addresses: the IPv4 address 127.0.0.1 and the IPv6 address ::1. Modern operating systems prioritize the IPv6 address. In Node 16, the runtime quietly reordered these DNS results to put IPv4 first. Node 17 removed this reordering to align with standard OS behavior.

If a backend service (like a database or an API) binds strictly to the IPv4 address, Node 17's client attempts to connect to ::1 first. When that connection is refused, Node 17 simply stops and throws an error instead of trying the next address in the list.

How does Node 20's Happy Eyeballs algorithm fix localhost?

Node 20 resolves this by implementing the Happy Eyeballs algorithm (RFC 8305), which manages dual-stack connections by racing IPv6 and IPv4. If the preferred IPv6 connection fails immediately or takes longer than 250 milliseconds, Node automatically falls back to IPv4.

The Happy Eyeballs algorithm makes dual-stack connections seamless. Instead of waiting indefinitely or failing immediately, the client initiates a fast fallback. Think of it like trying to enter a house with two doors. I might knock on the IPv6 door first. If that door is locked, or if there is no response within 250 milliseconds, I do not give up; I immediately try the IPv4 door. Node 20 does exactly this, allowing local development to work regardless of which IP format the server binds to.

Node.js Version	Default Resolution Order	Behavior on IPv6 Connection Failure	Result for IPv4-only Local Servers
Node 16 and below	Hardcoded IPv4 (`127.0.0.1`) first	N/A (rarely hit IPv6 first)	Works seamlessly
Node 17 to 19	OS Default (usually IPv6 `::1` first)	Fails immediately with `ECONNREFUSED`	Broken local connections
Node 20 and above	OS Default (IPv6 first via Happy Eyeballs)	Falls back to IPv4 after 250ms (or on refusal)	Works seamlessly

How can you resolve localhost connection issues without upgrading?

If upgrading to Node 20 is not an option, you can resolve the issue by binding your local servers to the wildcard address 0.0.0.0 or by using the explicit IP address 127.0.0.1 in your client connection strings instead of the localhost hostname.

When I configure a local server to listen on 127.0.0.1, it only accepts IPv4 traffic. If I cannot upgrade Node, I change the server's binding configuration to 0.0.0.0 or :: (which binds to all interfaces). Alternatively, changing the client connection string from http://localhost:3000 to http://127.0.0.1:3000 bypasses DNS resolution entirely, preventing the OS from offering the IPv6 address.

FAQ

Why does macOS prioritize IPv6 over IPv4 for localhost?

Modern operating systems prioritize IPv6 by default to encourage the global transition away from the exhausted IPv4 address space, as defined in internet engineering standards like RFC 6724.

What is the difference between 127.0.0.1 and 0.0.0.0?

127.0.0.1 is a loopback address representing only the local machine, whereas 0.0.0.0 is a wildcard address that tells a server to listen on all available network interfaces, including local loopbacks and external IPs.

Does the Happy Eyeballs fallback add latency to my local API requests?

No noticeable latency is added; if the IPv6 connection is immediately refused, the fallback to IPv4 happens instantly. The 250ms delay only acts as a timeout if the IPv6 address is reachable but completely non-responsive.

How to Build a Java LRU Cache in 5 Lines

Doogal Simpson — Thu, 08 Oct 2026 11:37:41 +0000

To build a simple Least Recently Used (LRU) cache in Java, extend the standard LinkedHashMap with accessOrder set to true and override the removeEldestEntry method. While this standard library approach is incredibly elegant and fits in five lines of code, I should warn you that it is not thread-safe by default.

Whenever I'm talking shop with other engineers, the classic "build an LRU cache" interview question always seems to come up. Most devs immediately start sketching out a custom doubly linked list and a hash map, sweating over manual pointer updates. But if you're writing Java, we've had a production-ready, elegant solution sitting right under our noses in the standard library since 2002.

It's called LinkedHashMap, and I'm going to show you how to turn it into a fully functional LRU cache with almost zero boilerplate.

How does LinkedHashMap work as an LRU cache?

LinkedHashMap maintains a doubly linked list running through all of its entries to track element ordering. By initializing it with the accessOrder constructor argument set to true, the map automatically moves any accessed element to the end of the list. This ensures that the least recently used item always remains at the very front of the list.

I like to think of a standard hash map as a messy drawer where you toss items. It is highly efficient for retrieving things, but it has no sense of order. LinkedHashMap threads a string through all those items to keep track of them.

When you set accessOrder to true, the map changes its behavior. Instead of keeping items in insertion order, it reshuffles them every time you call get() or put(). Reading an item unhooks it from its current position and moves it to the end. Because it uses a doubly linked list, this pointer swap runs in O(1) constant time, meaning it takes the same amount of time whether your cache has three items or three million.

How do you implement a 5-line LRU cache in Java?

To implement the cache, extend LinkedHashMap and override the protected removeEldestEntry method to return true when the map exceeds your capacity limit. This hook runs after every put operation, instructing the map to automatically evict the oldest entry.

Personally, I love this solution because of how clean it is. We can inherit all the heavy lifting from the standard library. Here is how I implement it in just five lines of actual logic:

import java.util.LinkedHashMap;
import java.util.Map;

public class LruCache<K, V> extends LinkedHashMap<K, V> {
    private final int maxCapacity;

    public LruCache(int maxCapacity) {
        super(maxCapacity, 0.75f, true);
        this.maxCapacity = maxCapacity;
    }

    @Override
    protected boolean removeEldestEntry(Map.Entry<K, V> eldest) {
        return size() > maxCapacity;
    } 
}

Let’s trace how this works with a capacity of three. Imagine you insert keys A, B, and C. Your cache is now full. If you read key A, the pointer swaps move A to the end of the list, leaving B at the front as the oldest, least recently used entry. When you insert a new key, D, the overridden removeEldestEntry method checks if the size exceeds three, returns true, and discards B instantly.

Is the LinkedHashMap LRU cache thread-safe?

No, the default LinkedHashMap implementation is not thread-safe. If multiple threads access and modify the cache concurrently, you must wrap it in a synchronized wrapper or use a dedicated concurrent cache.

I should warn you, though: this elegant little class is not thread-safe out of the box. If you have multiple threads modifying the cache at the same time, you'll run into race conditions.

If I need to use this approach in a multi-threaded environment, I wrap it using Collections.synchronizedMap:

Map<String, String> cache = Collections.synchronizedMap(new LruCache<>(100));

However, synchronization introduces locks, which can slow down high-throughput applications. If your service handles heavy concurrent traffic, I recommend comparing your options before deciding on an implementation strategy:

Cache Strategy	Thread-Safety	Performance Under Load	Best Use Case
LinkedHashMap (Standard)	No	Extremely Fast (Single Thread)	Lightweight, single-threaded memory management
Synchronized LinkedHashMap	Yes (Lock-based)	Medium (Lock Contention)	Simple multi-threaded apps with low write volume
Caffeine / Guava Cache	Yes (Lock-free)	Industry-leading	High-throughput, concurrent production services

FAQ

Can you use LinkedHashMap as an LRU cache without extending it?

Yes, but you lose the automatic eviction. Without overriding removeEldestEntry, you would have to manually check the map's size and delete the oldest item using an iterator after every insertion, which defeats the purpose of this clean implementation.

What is the time complexity of LinkedHashMap LRU operations?

Both read and write operations run in O(1) constant time. The pointer updates in the underlying doubly linked list require only a few reference swaps, which do not scale with the size of the cache.

Why does the LinkedHashMap constructor require a float value?

The float value (typically 0.75f) is the load factor. It determines when the underlying hash table resizes itself to prevent collision chains, ensuring lookup times remain predictable and fast.

That is all there is to it. Next time someone challenges you to write an LRU cache, you can show them how to get it done in five lines of clean, standard Java. Have you ever used this trick in production, or do you always reach for Caffeine? Let me know!

Cheers,

Doogal

How to Preserve Key Insertion Order in JavaScript

Doogal Simpson — Wed, 07 Oct 2026 17:41:23 +0000

TL;DR: JavaScript objects do not guarantee insertion order when using integer keys. The ES6 specification forces integer-like keys (array indices) to the front of the object, sorted numerically. To maintain exact insertion order across all key types, you should use a JavaScript Map or restructure your data payload as an array.

We have all been there. You write some JavaScript code, build an object, populate it with some keys, and expect them to come back in the exact order you put them in. For the most part, they do.

But then integers enter the picture, and your carefully ordered data gets completely scrambled.

In JavaScript, integer keys are the ultimate line-cutters. They do not care when they were added; they jump straight to the front of the queue, sort themselves in ascending order, and leave your string keys trailing behind. Let's look at why this happens and how it can break your applications.

Why do JavaScript object keys change order?

JavaScript object keys change order because the ECMAScript specification mandates that keys behaving as integer indices must be sorted numerically and placed at the beginning of the key iteration order. Other string and symbol keys are then appended in the order they were created.

This behavior is defined by the OrdinaryOwnPropertyKeys internal algorithm introduced in ES6. When you call methods like Object.keys(), Object.entries(), or use a for...in loop, the engine groups and orders keys into three distinct phases:

Integer Properties: Keys that can be parsed as a 32-bit unsigned integer (plain whole numbers from 0 up to 4,294,967,294). These are sorted in ascending numerical order and placed first.
String Properties: Standard string keys (including floats, negative numbers, and alphabetic strings). These are preserved in chronological insertion order and placed second.
Symbol Properties: Symbol keys are grouped last, also preserving insertion order.

Here is a quick demonstration of this sorting behavior in action:

const obj = {};
obj['b'] = 'first string';
obj['2'] = 'second integer';
obj['1'] = 'first integer';
obj['-1'] = 'negative integer';

console.log(Object.keys(obj));
// Output: ['1', '2', 'b', '-1']

Notice how '1' and '2' immediately jumped to the front and sorted themselves, while 'b' and '-1' (which is not a valid array index) stayed in their original insertion order.

How does this behavior affect API data fetching?

When a server sends a JSON payload where the top-level keys are database IDs (like 300, then 100, then 200), parsing this payload in JavaScript automatically reorders the keys numerically (100, 200, 300). This destroys any intentional ordering, such as ranking or chronological sorting, applied by your backend.

Imagine you are building a dashboard that displays a leaderboard. The backend does the heavy lifting of sorting the users and sends back a JSON response keyed by user ID:

{
  "301": { "name": "Alice", "score": 95 },
  "102": { "name": "Bob", "score": 88 },
  "205": { "name": "Charlie", "score": 74 }
}

The moment you run JSON.parse() on this response in your frontend code, JavaScript reconstructs it as a standard object. Because the keys are integer-like, the engine instantly resort-sorts them to 102, 205, 301. Your carefully calculated leaderboard sequence is completely broken before you even render a single component.

How can you preserve insertion order in JavaScript?

To guarantee that your data keeps its exact sequence, you should either return an array of objects from your API or use a JavaScript Map on the frontend. Unlike plain objects, the Map object preserves the insertion order of all keys, regardless of their type.

Depending on where you are in the stack, you have a few ways to tackle this issue:

Data Structure	Preserves Integer Key Order?	Best Use Case
Plain Object (`{}`)	No (forced to front & sorted)	General key-value lookups where order is irrelevant
ES6 `Map`	Yes (strict insertion order)	Frontend state where key-value pairs require strict ordering
Array of Objects (`[]`)	Yes (strict array index order)	API payloads and lists transferred over the network

If you have control over the backend, the most resilient fix is to stop keying your collections by ID at the root level. Send an array instead:

[
  { "id": 301, "name": "Alice" },
  { "id": 102, "name": "Bob" }
]

If you must handle sorted keys purely on the client side, read the data into an ES6 Map instead of a plain object. Maps are guaranteed to respect insertion order for all keys—whether they are integers, strings, or symbols.

FAQ

Are float keys or negative numbers sorted numerically in JavaScript objects?

No. Floating-point numbers (such as 1.5) and negative integers (such as -5) are not valid 32-bit unsigned integers, meaning they cannot function as array indices. JavaScript treats them as standard string keys, so they will preserve their chronological insertion order.

Does JSON.parse() preserve key order?

No, JSON.parse() does not preserve key order if your keys are integers. Because it produces a standard JavaScript object, the JS engine applies the same ES6 spec rules, forcing all integer-like keys to the front in numeric order.

When should I choose a Map over a standard Object?

You should choose a Map when key insertion order is critical to your application logic, when you need keys that are not strings (like objects or functions), or when you are frequently adding and removing entries, as Map is highly optimized for frequent writes.

How iPhone's Secure Enclave Stops Brute-Force Attacks

Doogal Simpson — Tue, 06 Oct 2026 11:28:11 +0000

TL;DR: Your iPhone protects your 6-digit passcode by combining hardware-bound cryptography with forced validation delays. The Secure Enclave enforces a deliberate 80-millisecond verification lag alongside exponential lockouts. This transforms a theoretical 22-hour brute-force window into an impossible task, restricting physical attempts to just 10 before lockout.

Every time you type a wrong passcode into an iPhone, there's a tiny, deliberate lag before the UI shakes to tell you it failed. It isn't a slow CPU, a rendering hitch, or poor software optimization. It is a calculated cryptographic speed bump.

Apple intentionally stretches passcode verification to take about 80 milliseconds. When scaled up, this minor delay completely destroys standard automated brute-force attacks.

Why does Apple introduce an intentional delay to passcode validation?

Apple artificially delays passcode verification to make automated, high-speed guessing computationally expensive. By anchoring this delay inside specialized hardware, iOS ensures that attackers cannot bypass the wait time using external processing power or custom rigs.

If an attacker gains access to a hashed database on a traditional server, they can throw massive GPU clusters at it, testing billions of combinations per second. A standard six-digit passcode has exactly one million possible combinations. Without an artificial delay, a modern system would crack that search space instantly.

By forcing an 80-millisecond delay on every single guess, the timeline shifts dramatically. The math is simple:

1,000,000 combinations * 80 milliseconds = 80,000 seconds (or roughly 22 hours)

If an attacker could guess continuously and sequentially, it would take nearly a full day just to brute-force a basic six-digit PIN. But this math only holds true because the hardware prevents parallel attempts.

How does the Secure Enclave prevent offline brute-force attacks?

The Secure Enclave prevents offline attacks by fusing your passcode with a unique, hardware-bound cryptographic key that never leaves the silicon chip. Because this private key is inaccessible to the main operating system, attackers cannot copy the device's storage to run guesses on high-speed external GPU clusters.

In typical software security, you can duplicate an encrypted payload and attack it offline. On an iPhone, you can't. As a software engineer, I know that software-based rate limiting is always vulnerable to memory tampering if an attacker gets root access. Apple solves this by removing software from the equation entirely and handling verification in a dedicated coprocessor isolated from the main application processor.

The verification must happen directly on the device's silicon. An attacker cannot desolder the storage chip, plug it into a custom rig, and run parallelized decryption routines. Because the key never leaves the Secure Enclave, attackers are forced to play by the chip's rules, submitting guesses one at a time at the hardware's pace.

What happens to the math when you introduce lockout delays?

Lockout delays reduce the number of practical attempts from a million down to just 10 before total lockout or device wiping occurs. Instead of letting an attacker spend 22 hours guessing, the Secure Enclave enforces an exponential backoff that turns the timeline from hours into days.

The 80-millisecond delay is just the first line of defense. The real killer for brute-force attacks is the exponential backoff. After a few bad guesses, the Secure Enclave forces increasingly long wait times before it will accept another attempt.

Attempt Number	Delay Enforced	Cumulative Wait Time
1 to 5	None (80ms per guess)	< 1 second
6	1 Minute	1 Minute
7	5 Minutes	6 Minutes
8	15 Minutes	21 Minutes
9	1 Hour	1 Hour, 21 Minutes
10	3 Hours (or permanent lockout/wipe)	Over 4 Hours (or device erased)
11	Connect to Computer / Permanent Lockout	Permanent

If the user has the "Erase Data" setting enabled, the Secure Enclave doesn't just stop accepting guesses after the 10th attempt—it physically destroys the cryptographic keys required to decrypt the flash storage, rendering the data permanent gibberish.

Why do forensic tools target the lockout system instead of the encryption?

Forensic tools focus on exploiting operating system vulnerabilities to bypass the lockout state-tracking mechanism rather than cracking the underlying cryptography. Because breaking the Secure Enclave’s hardware-bound encryption is mathematically unfeasible, attackers must try to prevent the chip from recording failed attempts.

Decades of cryptographic research mean the AES implementation itself is virtually bulletproof. The weakest link is state management. If a forensic tool can find an exploit that intercepts the communication between the main OS and the Secure Enclave, it might prevent the hardware from writing the failed attempt count to its storage. If you can keep resetting the failure counter to zero, you can bypass the lockout timers and run guesses sequentially.

FAQ

Can you extract the passcode key from the Secure Enclave?

No. The key is a unique hardware identifier burned directly into the silicon during manufacturing. It is unreadable by any software, including the main iOS operating system.

Does a 4-digit passcode offer enough security?

While a 4-digit passcode only has 10,000 combinations, the 10-attempt lockout limit makes it highly secure against physical brute-forcing. However, it remains vulnerable to simple shoulder-surfing.

How does "Erase Data" protect the device?

Once the 10th failed attempt is registered, the Secure Enclave permanently discards the key used to decrypt the device's storage. Without this key, the raw data on the flash chip becomes mathematically impossible to recover.

Prevent Thundering Herd: Retry Jitter in Microservices

Doogal Simpson — Mon, 05 Oct 2026 16:11:02 +0000

When services fail, standard exponential backoff causes retries to sync up, creating a "thundering herd" that repeatedly crashes your servers. Adding "jitter"—a small dose of randomness to your wait times—spreads the retry load over time, allowing struggling systems to recover and slashing total call volume by more than half.

Whenever I audit a distributed system that keeps falling over after a minor blip, the first thing I look at is the retry logic. It is almost always a client coordination problem.

Imagine a crowded coffee shop where the barista suddenly announces, "Our espresso machine is clogged, please try again in exactly five minutes!" What happens? Five minutes later, fifty angry, caffeine-deprived people stampede the counter at the exact same millisecond. This is exactly what happens to your microservices when a downstream dependency blips. If we don't design our retry logic carefully, our attempts to be resilient will actually act as a self-inflicted Distributed Denial of Service (DDoS) attack.

What is the thundering herd problem in distributed systems?

The thundering herd problem occurs when multiple client applications coordinate their retry schedules, hitting a struggling server with massive, synchronized spikes of traffic at the exact same moment. Instead of giving a failing database or API time to recover, these synchronized retries repeatedly knock the system back down just as it tries to boot back up.

When I model system failures, I like to visualize this scenario: Imagine you have 1,000 serverless functions trying to write to a database. If the database locks up temporarily, all 1,000 write requests fail.

If your client code implements a standard exponential backoff (waiting 1 second, then 2 seconds, then 4 seconds), those 1,000 clients don't disappear. They simply pause, look at their synchronized internal clocks, and then hammer that fragile database again in unison. You aren’t backing off; you are just scheduling your stampedes.

How does adding jitter to retries fix system overload?

Adding jitter introduces random delays to your retry wait times, which breaks up the synchronization of client requests and distributes the load smoothly over time. Instead of hitting a database with 1,000 requests in a single millisecond, jitter spreads those requests across a wider, randomized window so the server can process them sequentially.

I always point developers to a classic AWS architecture paper where engineers simulated this exact scenario: 100 clients fighting over a single database row. By adding just a tiny bit of jitter, they cut the total number of calls in more than half.

Retry Strategy	Request Distribution Profile	Impact on Struggling Server
Standard Backoff	Massive, synchronized spikes at fixed intervals (e.g., exactly at 1s, 2s, 4s)	High chance of permanent failure; server never recovers
Backoff with Jitter	Evenly spread, randomized distribution across a time window (e.g., 0 to 4s)	Smooth traffic flow; server recovers quickly and processes requests

By spreading 1,000 retries over a four-second window, you turn a devastating spike of 1,000 concurrent requests into a manageable stream of roughly 250 requests per second.

How do you implement retry jitter in code?

To implement retry jitter, calculate your maximum exponential backoff limit for the current attempt, and then multiply that limit by a random decimal between 0 and 1. This ensures that the client sleeps for a random duration up to the maximum backoff limit, decoupling its retry timing from every other client.

When I write retry helpers, I use this lightweight JavaScript implementation of "Full Jitter" backoff:

function getJitterBackoff(attempt, baseDelayMs = 1000) { 
  const maxBackoff = baseDelayMs * Math.pow(2, attempt);
  // Multiply by random float between 0 and 1
  return Math.random() * maxBackoff; 
}

By adding that simple Math.random() multiplier, you instantly protect your downstream infrastructure from synchronized retry storms.

Frequently Asked Questions

What is the difference between Full Jitter and Equal Jitter?

Full Jitter selects a random sleep time anywhere between 0 and the maximum exponential backoff limit. Equal Jitter keeps a portion of the backoff constant and randomizes the remaining portion, meaning the client will always wait at least a minimum baseline duration before retrying.

Does adding jitter increase overall API latency for users?

While individual retries may occasionally wait slightly longer or shorter, jitter significantly decreases overall user latency during system outages. Because jitter prevents servers from being overwhelmed, the downstream service recovers much faster, allowing the total retry cycle to succeed sooner.

Should I use jitter for all API retry attempts?

Yes. I recommend making jitter a standard practice for any remote network call, especially in distributed microservice architectures or high-throughput serverless applications where client synchronization is common.

How Java HashMap Prevents Hash Collision DoS Attacks

Doogal Simpson — Mon, 05 Oct 2026 15:55:44 +0000

Java's HashMap mitigates Hash Collision Denial of Service (DoS) attacks by automatically converting congested linked list buckets into Red-Black trees once a bucket exceeds 8 entries and the total map capacity reaches 64. This transition reduces lookup complexity from O(N) to O(log N), preventing attackers from exhausting CPU resources.

Imagine sending a tiny 2MB payload to a web server and completely freezing a CPU core for nearly three-quarters of an hour. In 2011, security researchers demonstrated exactly this vulnerability. It wasn't a complex buffer overflow or a zero-day exploit; it was a fundamental math trick exploiting how hash maps handle collisions. I always find it fascinating how security concerns reshape standard library internals. Let's look at how Java quietly re-engineered its foundational data structure to stop this attack in its tracks.

How do hash collision DoS attacks exploit Java's HashMap?

A hash collision attack occurs when an attacker deliberately crafts inputs that generate the identical hash code, forcing them into the same storage bucket. Instead of distributing items evenly, the map collapses into a single, massive linked list, forcing the CPU to perform slow, sequential searches for every lookup.

Java’s String.hashCode() function is deterministic and openly documented. This predictability is a double-edged sword. If you know how the hash is calculated, you can generate thousands of unique strings that resolve to the exact same hash value.

For example, the strings "Aa" and "BB" generate the exact same hash code. If you run a quick test, you can see this in action:

public class CollisionTest {
    public static void main(String[] args) {
        // Both strings produce the hash code: 2112
        System.out.println("Aa".hashCode()); 
        System.out.println("BB".hashCode());
    }
}

Imagine your application is building a system that processes incoming web forms. If a malicious client sends a POST request containing thousands of form fields named with these colliding keys, the Java server stores them in a single HashMap. Normally, map lookups are O(1)—instantaneous. But when thousands of keys crowd into one bucket, that bucket becomes a long linked list. Finding a key suddenly requires traversing the entire list (O(N) complexity). For 1,000 colliding keys, this results in up to half a million comparison operations, keeping the CPU core pinned at 100% capacity.

What is Java's treeify threshold and how does it solve this?

Starting in Java 8, when a bucket's linked list grows beyond 8 elements and the overall map has at least 64 buckets, the JVM automatically converts that bucket into a self-balancing Red-Black tree. This dynamically lowers search time from O(N) down to O(log N), neutralizing the performance penalty of hash collisions.

Instead of walking a massive linked list line by line, the JVM reorganizes the bucket into a Red-Black tree. Let's look at how the performance characteristics scale when an attacker tries to flood a bucket with 1,000 colliding keys:

Bucket Structure	Algorithm Complexity	Comparisons for 1,000 Keys
Linked List (Pre-Java 8)	O(N)	Up to 1,000 comparisons
Red-Black Tree (Java 8+)	O(log N)	Roughly 10 comparisons

By shifting to a tree, searching through 1,000 colliding keys drops from a grueling thousand steps to a mere ten. The CPU barely breaks a sweat, and the DoS attack is rendered completely ineffective.

Why is the treeification threshold set to exactly 8?

The threshold of 8 is chosen because the probability of any single bucket naturally reaching 8 elements under normal circumstances is incredibly low—roughly 6 in 100 million. Setting the threshold here ensures that the performance overhead of maintaining complex Red-Black trees is only incurred when a structural anomaly or a malicious attack occurs.

In a healthy application using a well-distributed hash function, the distribution of keys across buckets follows a Poisson distribution. Under normal operations, the chance of a bucket naturally accumulating 8 elements is virtually zero.

Trees are memory-heavy and complex to rebalance during insertions. We don't want them active unless absolutely necessary. By choosing 8, Java keeps the map highly optimized for standard workloads while keeping a robust shield ready for worst-case scenarios.

Frequently Asked Questions

Can you disable or change the HashMap treeify threshold?

No, the TREEIFY_THRESHOLD constant is hardcoded as static final int TREEIFY_THRESHOLD = 8; inside java.util.HashMap. It cannot be configured via JVM flags or system properties, ensuring consistent security behavior across all standard Java runtimes.

Does treeification happen in ConcurrentHashMap as well?

Yes, ConcurrentHashMap uses the exact same treeification strategy. When a bin in a ConcurrentHashMap exceeds 8 entries, it converts into a tree structure (using TreeNode objects) to prevent thread congestion and complexity-based denial of service.

What happens if elements are removed from a treeified bucket?

If elements are removed (via remove() or map resizing) and the bucket size falls to 6 or fewer elements, the map automatically converts the Red-Black tree back into a standard linked list. This process is called "untreeifying" and helps save memory when the collision threat is gone.

How Structural Sharing Makes Immutability Fast

Doogal Simpson — Sat, 03 Oct 2026 09:09:50 +0000

If you need to update a single element in an immutable list containing one million items, you do not have to copy all one million elements. Instead, functional ecosystems like Scala, Clojure, and Immutable.js use a 32-way tree structure (a bitmapped vector trie). Through structural sharing, they only copy a tiny path of four nodes, preserving memory and ensuring near-instant updates.

I often chat with developers who are highly skeptical of immutability purely because of performance concerns. On paper, it sounds terrible: if I change one item in an immutable list of a million elements, I should have to copy all one million elements to keep the original state intact. I completely understand why engineers look at that overhead and worry about the sheer garbage collection pressure and CPU cycles it would waste.

But in practice, it works incredibly fast. I want to take you under the hood of how functional languages and libraries pull this off without blowing up your memory budget.

How do immutable lists update without copying everything?

I find it easiest to understand this by looking at how immutable lists replace flat arrays with trees. Instead of copying a flat array, these data structures copy only the specific nodes along the direct path to the modified element, leaving the rest of the tree completely shared.

To explain this, I like to use the analogy of a nested directory of files. Imagine you have a nested directory of folders on your computer. If you want to modify a single text file inside a deeply nested folder, you do not copy the entire hard drive. You only create a new path of folders leading to your new, modified text file. The rest of your file system remains completely untouched.

In an immutable vector, every node in the tree holds up to 32 elements. Because the tree is so wide, it is incredibly shallow. When you update a single item, the system only duplicates the small 32-element arrays along the direct path to that item. It then links the new root node to these new copies, while the rest of the pointers point directly back to the original unmodified branches of the old tree.

What is structural sharing in functional programming?

I define structural sharing as an optimization technique where multiple versions of a data structure share references to identical, unmodified nodes. This allows us to create new versions of our data with virtually zero memory overhead because we only allocate memory for the changes.

Here is a quick look at how a flat array copy compares to a 32-way bitmapped trie copy during updates:

Feature	Flat Array (Naive Copy)	Bitmapped Trie (Structural Sharing)
Time Complexity (Lookup)	O(1)	O(log base 32 of N) (effectively O(1))
Time Complexity (Update)	O(N)	O(log base 32 of N) (effectively O(1))
Memory Overhead (Update)	Copies all N elements	Copies at most 4-6 small nodes
Garbage Collection Pressure	Very high for large N	Extremely low

How does the math behind a 32-way trie work?

I like to break down the math of a 32-branching factor to show how incredibly flat these trees actually remain. Because each node can branch 32 times, a tree with a depth of just four levels can hold over a million items, meaning I never have to traverse more than four hops to read or update an element.

I find it helpful to map out the exponentiation of a branching factor of 32 to show how this scales:

Level 1: 32 elements
Level 2: 32 * 32 = 1,024 elements
Level 3: 1,024 * 32 = 32,768 elements
Level 4: 32,768 * 32 = 1,048,576 elements
Level 5: 1,048,576 * 32 = 33,554,432 elements

If you have a list of one million items, any single element is at most four hops away from the root of the tree. To update that element, the system only copies four nodes of 32 elements each. You copy 128 references instead of one million.

This makes the time complexity log base 32 of N. For all practical purposes in software engineering, this is effectively constant time, O(1). Even if you scale up to a billion items, the tree only reaches six levels deep.

Here is how simple this looks in practice when using a library like Immutable.js:

import { List } from 'immutable';

// Creating a list of one million elements
const originalList = List(Array.from({ length: 1000000 }, (_, i) => i));

// This set operation only copies 4 tiny nodes under the hood
const updatedList = originalList.set(500000, 999999);

console.log(originalList.get(500000)); // Outputs: 500000
console.log(updatedList.get(500000));  // Outputs: 999999

Both originalList and updatedList coexist perfectly, and they share 99.9% of their memory footprint.

FAQ

Why is the branching factor specifically 32?

The branching factor of 32 is chosen because it aligns beautifully with modern CPU cache lines. Walking a node with 32 pointers minimizes CPU cache misses, making memory access incredibly fast while keeping the tree shallow enough to limit lookups to a handful of hops.

Is structural sharing thread-safe?

Yes. Because the nodes are strictly read-only, multiple threads can read the shared parts of the tree simultaneously without any locks or risk of race conditions. If a thread needs to write, it simply creates its own path of new nodes without affecting the other threads.

Do arrays and trees behave differently for sequential reads?

Yes. Because a vector is a tree under the hood, sequential iteration is slightly slower than traversing a flat, contiguous memory array. However, engines optimize this by processing nodes in chunks of 32, minimizing the performance penalty during standard loops.

SHA-256 vs Bcrypt: Why Speed Kills Password Security

Doogal Simpson — Fri, 02 Oct 2026 14:54:25 +0000

Quick Answer: Standard cryptographic hashes like SHA-256 are built for speed, making them dangerous for password storage. Bcrypt defeats offline brute-force attacks by introducing a configurable cost factor that exponentially increases computational work, turning a one-minute crack time into seven years while keeping legitimate logins fast.

A top-tier graphics card can crack 22 billion SHA-256 hashes every second. Let that number sink in. If an attacker dumps your database, SHA-256 isn't a security barrier—it's a highway. For verifying massive files or checking data integrity, that speed is exactly what you want. But when you're storing user credentials, high throughput is fatal.

Why can't we use SHA-256 for password hashing?

SHA-256 is built for raw throughput, allowing systems to verify large datasets almost instantly. While highly efficient, this speed is a massive liability for passwords because it allows offline attackers to run parallel dictionary attacks at a rate of billions of guesses per second.

When a breach occurs, attackers don't hammer your production API; they take the hashed database offline. Armed with consumer GPUs, they hash massive dictionaries of common passwords and compare them to your stolen hashes. Because SHA-256 has no built-in delay, it offers zero resistance to this massive parallel processing power.

How does bcrypt stop offline brute-force attacks?

Bcrypt stops brute-force attacks by introducing a configurable cost factor that forces the hashing engine to perform a massive loop of calculations. This intentional bottleneck drops a GPU's guessing speed from billions to thousands of attempts per second, neutralizing dictionary attacks.

Instead of optimizing for speed, bcrypt was engineered to be slow. For a single legitimate user logging in, a fraction of a second delay is completely imperceptible. But for an attacker trying to guess millions of combinations, that same delay compounds exponentially, turning a fast crack into an impossible timeline. An offline attack that would crack a password in one minute on SHA-256 takes about seven years on bcrypt.

How do SHA-256 and bcrypt compare in a brute-force scenario?

SHA-256 allows standard graphics cards to process billions of operations per second, making short work of weak passwords. Bcrypt limits that same hardware to a few thousand guesses per second, drastically increasing the time required to break a single hash.

Metric / Feature	SHA-256	bcrypt
Primary Purpose	Fast data integrity verification	Secure password storage
Execution Speed	Ultra-fast (designed for high throughput)	Intentionally slow (designed for latency)
GPU Guesses / Sec	~22 billion	~6,000
Work Scaling	Fixed complexity	Configurable exponential cost
Crack Time (Offline)	~1 minute	~7 years

What is a configurable cost factor and how does it scale?

A configurable cost factor is a setting in bcrypt that determines the number of hashing rounds, which doubles with every single increment. This exponential relationship allows you to increase the work required to compute a hash without changing your underlying codebase.

The math behind bcrypt is beautifully simple yet incredibly robust. The cost factor represents the exponent in a base-2 calculation. If you set your work factor to 10, the algorithm performs 2^10, or 1,024, iterations of its key derivation function.

If you bump that cost factor up to 11, the workload doubles to 2,048 iterations. Turn it up 10 notches to 20, and you are scaling the work by a factor of over a thousand (reaching 1,048,576 iterations). As hardware inevitably gets faster and cheaper over the years, you don't need to migrate to a new algorithm; you simply increment this cost factor to keep your security posture exactly where it needs to be.

FAQ

Is bcrypt better than Argon2?

Argon2 is newer and generally considered superior because it is memory-hard, meaning it resists GPU/ASIC parallelization better than bcrypt. However, bcrypt remains highly secure, incredibly reliable, and widely supported across almost every programming language.

What is a good bcrypt work factor to use today?

A work factor of 10 to 12 is the current sweet spot for most production environments, taking roughly 100ms to 250ms to compute. You should benchmark your specific servers to ensure it doesn't cause high CPU spikes during peak login hours.

Why doesn't the slow speed of bcrypt affect the user experience?

To a human, a 100-millisecond delay during a login request is completely imperceptible. However, to an automated script trying to brute-force a leaked database, that 100ms penalty applies to every single guess, making automated attacks completely impractical.

Python Integer Caching: Why 256 is 256 but 257 is Not

Doogal Simpson — Fri, 02 Oct 2026 14:36:28 +0000

Why does 256 is 256 evaluate to True, but 257 is 257 return False? Python pre-allocates small integer objects (traditionally -5 to 256) inside a global array to save memory. Because this optimization is version-dependent, using the is operator for numeric comparisons introduces subtle, breaking bugs.

Run a = 256; b = 256; a is b in your Python REPL, and it returns True. Run x = 257; y = 257; x is y on separate lines, and it returns False. This behavior isn't a glitch—it is a direct consequence of how CPython optimizes memory allocation for low-value integers.

Understanding the mechanics of this behavior requires looking beneath Python's high-level syntax and into CPython's memory management.

How does CPython optimize small integers under the hood?

CPython pre-allocates a static array of integer objects for values between -5 and 256 (inclusive) during interpreter initialization. When you assign one of these values, CPython returns a pointer to the pre-existing object rather than allocating new memory on the heap.

In CPython, integers are not lightweight, 8-byte primitive types like they are in C or C++. Instead, they are defined as PyLongObject structures. Every PyLongObject contains metadata inherited from the base PyObject structure, including:

ob_refcnt: An 8-byte reference counter used for garbage collection.
ob_type: An 8-byte pointer to the type object (&PyLong_Type).
ob_size: An 8-byte signed integer indicating the size of the digit array.

On a 64-bit system, this structural overhead means even the integer 0 consumes 24 to 28 bytes of memory. Constantly allocating and deallocating these structures for basic loop counters or arithmetic operations would cause massive heap fragmentation and CPU overhead.

To mitigate this, CPython's source code (specifically in Objects/longobject.c) defines an array named small_ints. During startup, CPython initializes this array with PyLongObject instances for every number from -5 up to 256.

Why does the "is" operator fail on larger numbers?

The is operator evaluates object identity by comparing memory addresses directly, whereas == evaluates value equality by invoking the object's comparison method. For integers outside the cached range, CPython allocates distinct heap memory addresses, causing is to return False even if the values are identical.

When you assign a number outside the small_ints range (such as 257) across separate lines in the interactive REPL, the CPython runtime cannot reuse a cached instance. It calls PyLong_FromLong(), which invokes _PyObject_New to allocate a completely new PyLongObject on the heap.

As a result, the variables point to two entirely different addresses in virtual memory. The is operator checks if the raw pointer values are equal. Because these pointers point to distinct heap allocations, the identity check fails, even though the underlying numeric values match.

How does Python 3.15 change integer caching behavior?

Starting in Python 3.15, CPython is raising the small integer caching threshold from 256 up to 1024. This means that expressions like 1000 is 1000 will evaluate to True in Python 3.15, whereas they evaluated to False in all prior versions.

This upcoming adjustment highlights why relying on the is operator for value comparison is a dangerous anti-pattern. The boundaries of the small_ints array are internal implementation details, not part of the Python language specification.

If you write code that accidentally relies on this cache, your application might pass its tests locally on a newer Python interpreter but fail silently when deployed to a production environment running an older version of CPython.

Python Version	`256 is 256`	`257 is 257`	`1024 is 1024`	Safe Comparison Operator
Python 3.12 and older	`True`	`False`	`False`	`==`
Python 3.15+	`True`	`True`	`True`	`==`

FAQ

Why does CPython's cache start exactly at -5?

CPython starts the cache at -5 because low-value negative numbers are frequently used as index offsets (such as accessing lists from the end with -1) and error-state sentinel values in C-API integrations.

Does CPython optimize string objects using a similar mechanism?

Yes, CPython uses a process called "string interning" for short, ASCII-only strings that look like Python identifiers. This is handled via the sys.intern() function and internal dictionary keys, allowing the interpreter to perform fast pointer comparisons instead of expensive character-by-character string comparisons.

Why do two large identical numbers sometimes return True for "is" inside a script?

When Python compiles a single script file or module, the compiler processes entire code blocks at once. During this compilation phase, CPython performs constant folding and merges identical literals within the same code object's constant pool (co_consts), causing them to share the same memory allocation.