DEV Community: JKC

Stop Writing while (true) reader.read() Loops. Streams Are Iterable Now

JKC — Mon, 02 Nov 2026 05:33:25 +0000

TL;DR: ReadableStream is async iterable, so for await (const chunk of stream) replaces the reader loop. With Safari 27 it is Baseline Newly available since September 2026, and it already works in Node.js.

The loop everyone copies from Stack Overflow

You want the text of a streamed response. Not all at once, but chunk by chunk, as it arrives. So you write the ritual:

const reader = stream.getReader();
const decoder = new TextDecoder();
let text = "";
try {
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    text += decoder.decode(value, { stream: true });
  }
  text += decoder.decode();
} finally {
  reader.releaseLock();
}

Thirteen lines, a while (true), a destructured done flag, and a finally you will forget one day. It works. It also looks like code that was written under protest.

What it is

A ReadableStream now implements the async iterable protocol. That means for await...of can read it directly, one chunk per turn of the loop:

const stream = new ReadableStream({
  start(controller) {
    for (const word of ["streams", "are", "iterable"]) controller.enqueue(word);
    controller.close();
  },
});

for await (const chunk of stream) {
  console.log(chunk);
}
// streams
// are
// iterable

No reader, no done, no releaseLock(). While the loop runs, the stream is locked, and the lock is released when the loop exits.

There is also stream.values(), which returns the same iterator and takes one option, preventCancel. More on why you might want it in the gotchas.

The realistic one: read NDJSON as it arrives

Logs, AI responses, and export endpoints love newline-delimited JSON. Here is a small helper that turns any byte stream into lines, built on the new loop:

async function* lines(stream) {
  let buffer = "";
  for await (const text of stream.pipeThrough(new TextDecoderStream())) {
    buffer += text;
    const parts = buffer.split("\n");
    buffer = parts.pop();
    yield* parts;
  }
  if (buffer) yield buffer;
}

const body = new Response(
  '{"level":"info","msg":"boot"}\n{"level":"error","msg":"disk full"}\n{"level":"info","msg":"retry"}'
).body;

let errors = 0;
for await (const line of lines(body)) {
  const entry = JSON.parse(line);
  if (entry.level === "error") errors++;
  console.log(entry.level.padEnd(5), entry.msg);
}
console.log("errors:", errors);

Output:

info  boot
error disk full
info  retry
errors: 1

In a browser, swap the Response for (await fetch("/logs")).body and nothing else changes. The helper is an async generator, so callers get the same for await shape all the way up.

TextDecoderStream is doing quiet but important work here. It keeps multi-byte characters intact when a chunk boundary lands in the middle of one, which the next section shows the hard way.

Can I use it?

Where	Status
Baseline	Newly available since September 2026
Chrome and Edge	124
Firefox	110
Safari (macOS and iOS)	27
Node.js	Works in v24.11.0, where every example in this post ran
Spec	WHATWG Streams

Safari was the last one in, and its 27.0 release notes list for await...of on ReadableStream as new. If you still support older Safari, keep the reader loop as a fallback, or feature-check Symbol.asyncIterator in ReadableStream.prototype.

Gotchas

Leaving the loop early cancels the stream. A break, return, or throw inside the loop cancels the stream by default, so it is done for good. After breaking at chunk 3 of an endless stream, the lock was released, but a fresh reader got { value: undefined, done: true } straight away. That is usually what you want for a fetch body you no longer need: cancelling tells the source you are done with it.
Use values({ preventCancel: true }) to stop and come back later. With that option, the same break left the stream alive, and a new reader got { value: 4, done: false }. Use it when you read a header from a stream and hand the rest to someone else.
The stream reads ahead of your loop. The cancel() callback in that test logged cancelled at 4, not 3. With the default queue size, the stream had already pulled one more chunk than the loop consumed. If pulling a chunk has side effects, such as charging an API call, count on one extra.
A locked stream cannot be iterated. Calling getReader() first and then looping threw TypeError: Invalid state: ReadableStream is locked in Node. Browsers word the message differently, but it is a TypeError everywhere, per MDN. One consumer at a time; use stream.tee() if you really need two.
Do not decode each chunk on its own. "café" is 5 bytes in UTF-8, because é takes two. Splitting it after byte 4 and calling new TextDecoder().decode(chunk) per chunk gave "caf��". Piping through TextDecoderStream first gave "café". Bytes and characters only look like the same thing in ASCII.

Wrap-up

The reader loop was never hard, just noisy, and noise is where the missing releaseLock() hides. Next time you reach for getReader(), try for await first and see how much of the ritual disappears.

Sources

This article was written with the help of AI and checked against the sources above.

Stop Writing a Comparer Class for One Property. .NET 11 Takes a Lambda

JKC — Sun, 01 Nov 2026 05:57:45 +0000

TL;DR: .NET 11 adds EqualityComparer<T>.Create(keySelector, keyComparer). Comparing objects by one property in a HashSet, Dictionary, or LINQ set operator is now a lambda, not a class. .NET 11 is at Release Candidate 2 right now: go-live licensed, but not final yet.

The class nobody wants to write again

You have a list of products. Two of them have the same SKU, and you want them treated as the same thing. So you open a new file and write this:

sealed class ProductBySkuComparer : IEqualityComparer<Product>
{
    public bool Equals(Product? x, Product? y)
    {
        if (ReferenceEquals(x, y)) return true;
        if (x is null || y is null) return false;
        return string.Equals(x.Sku, y.Sku, StringComparison.OrdinalIgnoreCase);
    }

    public int GetHashCode(Product obj) =>
        StringComparer.OrdinalIgnoreCase.GetHashCode(obj.Sku);
}

Twelve lines to say "compare by Sku". And there are two places to get it wrong: forget the case-insensitive hash, and Equals says yes while the HashSet never looks in the right bucket. It compiles fine and fails quietly, which is the worst kind of bug.

.NET 8 helped a little with EqualityComparer<T>.Create(equals, getHashCode). You still had to write both halves and keep them in sync.

Meet the key selector overload

.NET 11 adds a second Create that takes the key instead of the logic:

public static EqualityComparer<T> Create<TKey>(
    Func<T?, TKey?> keySelector,
    IEqualityComparer<TKey>? keyComparer = default);

You say which property matters. Equality and hashing both come from that one key, so they cannot drift apart.

The minimal example

var bySku = EqualityComparer<Product>.Create(p => p?.Sku);

var set = new HashSet<Product>(bySku)
{
    new("A-1", "Mug"),
    new("B-2", "Hat"),
    new("A-1", "Mug v2"),
};

Console.WriteLine(set.Count); // 2
foreach (var p in set) Console.WriteLine($"{p.Sku} {p.Name}");
// A-1 Mug
// B-2 Hat

record Product(string Sku, string Name);

The first A-1 wins, and Mug v2 is turned away at the door.

Need the key compared a specific way? Pass a comparer for the key itself:

var bySkuIgnoreCase = EqualityComparer<Product>.Create(
    p => p?.Sku, StringComparer.OrdinalIgnoreCase);

Console.WriteLine(bySkuIgnoreCase.Equals(
    new("A-1", "Mug"), new("a-1", "Mug v2"))); // True

That one line replaces the whole class at the top of this post.

A realistic example: two customer lists, one person

Your CRM and your shop both have customers. Same humans, different IDs, and nobody agrees on how to capitalize an email address.

Customer[] crm =
[
    new(1, "Ana@Example.com", "Ana"),
    new(2, "bo@example.com", "Bo"),
];
Customer[] shop =
[
    new(77, "ana@example.com", "Ana P."),
    new(78, "cy@example.com", "Cy"),
];

var byEmail = EqualityComparer<Customer>.Create(
    c => c?.Email, StringComparer.OrdinalIgnoreCase);

// Everyone, once
var everyone = new HashSet<Customer>(crm, byEmail);
everyone.UnionWith(shop);
Console.WriteLine(everyone.Count); // 3

// Who is new in the shop
var newInShop = shop.Except(crm, byEmail).Select(c => c.Email);
Console.WriteLine(string.Join(", ", newInShop)); // cy@example.com

// Orders per person, keyed by the customer object
var orders = new Dictionary<Customer, int>(byEmail);
foreach (var c in crm.Concat(shop))
    orders[c] = orders.GetValueOrDefault(c) + 1;

foreach (var (c, n) in orders) Console.WriteLine($"{c.Email}: {n}");
// Ana@Example.com: 2
// bo@example.com: 1
// cy@example.com: 1

record Customer(int Id, string Email, string Name);

One comparer, three different APIs, and Ana is counted once. The dictionary keeps the first key it saw (Ana@Example.com) and just bumps the value.

Can I use it?

The key selector overload is new in .NET 11. On the .NET 10 SDK, the same line does not compile:

error CS1593: Delegate 'Func<P?, P?, bool>' does not take 1 arguments

That is the compiler finding only the .NET 8 overload and telling you it wanted two arguments.

Everything in this post was run as a file-based app on the .NET 11 RC 1 SDK. RC 2 is the current release candidate, and it carries a go-live license.

Gotchas

1. The key selector gets null. The parameter is Func<T?, TKey?>, and the comparer really does call it with null. Write p => p.Sku and you get warning CS8602, then a NullReferenceException the first time null is compared. Write p => p?.Sku and it behaves: Equals(null, null) is true, Equals(null, someone) is false, and GetHashCode(null) returns 0.

2. The old overload still bites. Create((a, b) => ...) with no hash delegate compiles fine. Put it in a HashSet and the first Add throws NotSupportedException, because there is no hash code to ask for. The key selector overload does not have this trap.

3. The key must not change. Hash sets put an item in a bucket based on its key at insert time.

var tickets = new HashSet<Ticket>(EqualityComparer<Ticket>.Create(t => t?.Code));
var t1 = new Ticket { Code = "X1" };
tickets.Add(t1);
t1.Code = "X2";
Console.WriteLine(tickets.Contains(t1)); // False

class Ticket { public string Code { get; set; } = ""; }

Same object, same set, and the set swears it has never seen it. Use keys that never change, like IDs or init properties.

4. You might not need a comparer at all. For a one-off LINQ query, DistinctBy, ExceptBy, and UnionBy already take a key selector. The new Create is for when the comparer has to live somewhere: a HashSet, a Dictionary, or a field you pass around.

Wrap-up

If your codebase has a folder full of XxxByIdComparer classes, most of them are now one line each. Grab the .NET 11 RC SDK and delete one this week.

Sources

This article was written with the help of AI and checked against the sources above.

Stop Spreading Iterables Into Arrays to Join Them. Iterator.concat() Is Here

JKC — Sat, 31 Oct 2026 11:02:36 +0000

TL;DR: Iterator.concat(a, b, c) walks any iterables one after another and returns a lazy iterator. No temporary array, no hand-written generator, and it has been Baseline Newly available since March 2026.

The array you build just to throw away

You have an array, a Set, and a generator. You want to loop over all of them in order. So you write the line everyone writes:

for (const item of [...pinned, ...recentSet, ...loadMore()]) {
  render(item);
}

It works. It also copies every item into a brand new array, runs the generator to the very end, and then hands the array to the garbage collector a moment later. If you only needed the first few items, you paid for all of them.

The careful version is a generator with yield*:

function* concat(...iterables) {
  for (const iterable of iterables) {
    yield* iterable;
  }
}

Correct, lazy, and copy-pasted into a utils folder near you.

What it is

Iterator.concat() is that generator, built into the language. It takes any number of iterables and returns an iterator that yields from each one in turn:

const array = [1, 2, 3];
const set = new Set([4, 5]);
function* gen() {
  yield 6;
  yield 7;
}

console.log([...Iterator.concat(array, set, gen())]);
// [1, 2, 3, 4, 5, 6, 7]

The result is a real iterator, so the iterator helpers work on it directly:

const evensTimesTen = Iterator.concat([1, 2, 3], new Set([4, 5, 6]))
  .filter((n) => n % 2 === 0)
  .map((n) => n * 10)
  .toArray();

console.log(evensTimesTen); // [20, 40, 60]

Maps are iterables of [key, value] pairs, which makes "defaults, then overrides" a one-liner:

const defaults = new Map([["theme", "light"], ["lang", "en"]]);
const user = new Map([["theme", "dark"]]);

const settings = new Map(Iterator.concat(defaults, user));
console.log(Object.fromEntries(settings)); // { theme: "dark", lang: "en" }

Later keys win, because that is how the Map constructor already behaves.

The realistic one: take only what you need

Here is where laziness pays. Two sources of 1000 rows each, and a UI that shows the first three:

let pulled = 0;

function* page(start) {
  for (let i = start; i < start + 1000; i++) {
    pulled++;
    yield i;
  }
}

const spread = [...page(0), ...page(1000)].slice(0, 3);
console.log(spread, pulled); // [0, 1, 2] 2000

pulled = 0;

const lazy = Iterator.concat(page(0), page(1000)).take(3).toArray();
console.log(lazy, pulled); // [0, 1, 2] 3

Same answer. The spread version produced 2000 rows to keep 3. The concat version produced 3. Replace "row" with "parsed log line" or "decoded image" and that gap stops being academic.

It is also lazy about opening each source. Logging every [Symbol.iterator]() call on two iterables gave this order:

created
open a
next 1
next 2
open b
next 3

Nothing is opened when you call concat, and b is not touched until a runs out. That also means infinite sources are fine, as long as you stop early:

function* naturals() {
  let i = 1;
  while (true) yield i++;
}

console.log(Iterator.concat(["start"], naturals()).take(5).toArray());
// ["start", 1, 2, 3, 4]

Can I use it?

Where	Status
Baseline	Newly available since March 2026
Chrome and Edge	146
Firefox	147
Safari (macOS and iOS)	26.4
Node.js 24	Not yet: `typeof Iterator.concat` is `"undefined"` in v24.11.0
Spec	TC39 Iterator Sequencing proposal, Stage 4

Everything in this post ran in Chrome 156. If you need it in Node today, keep the five-line generator from above as a fallback.

Gotchas

Strings are rejected, even though they are iterable. Iterator.concat([1], "ab") throws TypeError: Iterator.concat called on non-object right away, at the call, not later during iteration. null throws the same error. Wrap a string first: Iterator.from("bc") or [..."bc"] both worked.
Bare iterators need Iterator.from(). An object with only a next() method is not iterable, and passing one threw TypeError: #<Object> is not iterable. Built-in iterators like [1, 2, 3].values() are fine, because they are iterable too.
The result is single use. Spreading the same concat result twice gave [1, 2, 3] the first time and [] the second. It is an iterator, not an array, so call Iterator.concat again if you need a second pass.
Breaking early closes what it opened. With two generators that log in finally, a for...of that broke on the first item of the second one logged closed a when a ran out and closed b on the break. Your cleanup code runs, which is exactly what you want.

Wrap-up

Iterator.concat() is the yield* helper you kept rewriting, now with iterator helpers attached. Next time you type [...a, ...b] only to loop over it once, try Iterator.concat(a, b) instead.

Sources

This article was written with the help of AI and checked against the sources above.

Your Type Has No Indexer. C# 15 Lets You Add One.

JKC — Fri, 30 Oct 2026 01:38:32 +0000

TL;DR: C# 15 lets you declare an indexer inside an extension block, so thing[i] works on types you don't own. Add a Count and a Slice, and you get ^1, ranges, and list patterns too.

C# 15 ships with .NET 11, which is still in release candidate. Everything below ran on the .NET 11 RC 1 SDK with no LangVersion setting.

The helper everyone writes

You have a type you can't change. Maybe it is a wrapper from a library, maybe it is an interface like IReadOnlyDictionary<TKey, TValue>. You want square brackets. You get a method instead:

int last = readings.GetAt(readings.Values.Length - 1);
int stock = inventory.GetValueOrDefault("kiwi", 0);
int cell = grid.Get(row: 1, column: 2);

Each one works. Each one is also a tiny dialect your team has to learn per type. C# 14 gave us extension properties, but indexers were left out. C# 15 fills that gap.

What it is

Inside an extension block you can now declare this[...], just like on a class. Indexers are always instance members, so the block needs a named receiver:

public static class SequenceIndexer
{
    extension(IEnumerable<int> sequence)
    {
        public int this[int index] => sequence.ElementAt(index);
    }
}

And the call site looks like the indexer was always there:

IEnumerable<int> numbers = Enumerable.Range(1, 10);
Console.WriteLine(numbers[2]); // 3

That is the whole feature. Get and set accessors, multiple parameters, expression bodies, and ref returns all work like they do on normal indexers.

A lookup with a fallback

Here is one you can use today. A second parameter turns any read-only dictionary into a lookup with a default:

public static class DictionaryIndexers
{
    extension<TKey, TValue>(IReadOnlyDictionary<TKey, TValue> map)
    {
        public TValue this[TKey key, TValue fallback]
            => map.TryGetValue(key, out var value) ? value : fallback;
    }
}

var stock = new Dictionary<string, int> { ["apple"] = 12, ["pear"] = 0 };
Console.WriteLine(stock["apple", 0]); // 12
Console.WriteLine(stock["kiwi", 0]);  // 0

No out var, no KeyNotFoundException. Dictionary<string, int> picks it up because it implements IReadOnlyDictionary.

The realistic one: a type you don't own

Say a library hands you this, and you can't edit it:

public sealed class Readings(int[] values)
{
    public int[] Values { get; } = values;
}

Give it a Count, an integer indexer, and a Slice, all as extensions:

public static class ReadingExtensions
{
    extension(Readings readings)
    {
        public int Count => readings.Values.Length;

        public int this[int index] => readings.Values[index];

        public Readings Slice(int start, int length)
            => new(readings.Values.AsSpan(start, length).ToArray());
    }
}

Now the compiler treats it like a real collection:

var temps = new Readings([18, 21, 24, 19]);

Console.WriteLine(temps[0]);                // 18
Console.WriteLine(temps[^1]);               // 19
Console.WriteLine(temps[1..3].Values[0]);   // 21
Console.WriteLine(temps is [18, .., 19]);   // True

Index from the end, ranges, and list patterns all came for free. You wrote three members, and the compiler wired up the rest. That is the same pattern the language already uses for "countable" types, now open to extensions.

Setters work too, with as many parameters as you need:

public sealed class Grid(int width, int height)
{
    public int Width { get; } = width;
    public int[] Cells { get; } = new int[width * height];
}

public static class GridIndexer
{
    extension(Grid grid)
    {
        public int this[int row, int column]
        {
            get => grid.Cells[row * grid.Width + column];
            set => grid.Cells[row * grid.Width + column] = value;
        }
    }
}

var grid = new Grid(3, 2);
grid[1, 2] = 7;
Console.WriteLine(grid[1, 2]);                   // 7
Console.WriteLine(string.Join(", ", grid.Cells)); // 0, 0, 0, 0, 0, 7

No more doing row-major math at every call site. It happens in one place, which is the only place it should be wrong.

Can I use it?

What	Status
Language version	C# 15
SDK	.NET 11 SDK (RC at the time of writing)
`LangVersion` needed	No, C# 15 is the default for `net11.0`
.NET 10 / C# 14	No: error CS8652, "extension indexers" is in Preview
GA	Microsoft says C# 15 ships with .NET 11 in November

Gotchas

Real indexers always win, silently. The compiler tries the type's own indexer first, then extensions. In a test, an extension this[int] on List<int> that returns -1 changed nothing: list[1] still returned 20, and the build gave no warning. So you can't use an extension to "fix" an indexer a type already has.
Arrays and strings are off limits. Extension indexers are never used for array or string element access. An extension this[string] on int[] compiled fine, but a["x"] failed with CS0029, because the compiler only looked at the built-in array indexer.
Brackets can hide a loop. The ElementAt indexer on IEnumerable<int> looks like O(1) and isn't. Reading seq[0] through seq[9] from a lazy iterator pulled 55 items to return 10. If the receiver is not already a list, think twice before giving it brackets.
No expression trees. Expression<Func<Box, int>> f = b => b[0]; fails with CS9296: an expression tree may not contain an extension property or indexer access. That matters if you hoped to use one inside an EF Core query.

Wrap-up

Extension indexers are small, but they finish the story C# 14 started: methods, properties, operators, and now brackets. Pick the one GetAt helper in your codebase that annoys you most and give it a this[...] on the .NET 11 RC.

Sources

This article was written with the help of AI and checked against the sources above.

Stop Spreading Bytes Into btoa(). Uint8Array Speaks Base64 Now

JKC — Thu, 29 Oct 2026 01:07:32 +0000

TL;DR: bytes.toBase64() and Uint8Array.fromBase64(str) turn bytes into base64 and back, and toHex() / fromHex() do the same for hex. They handle URL-safe base64, padding, and whitespace, and they are Baseline 2025 Newly available.

The one-liner that is secretly three bugs

You have bytes. You need base64. So you reach for the line every Stack Overflow answer hands you:

const base64 = btoa(String.fromCharCode(...bytes));

It works in the demo. Then it meets real data.

Feed btoa() a string with an emoji and Chrome throws InvalidCharacterError, because btoa() only understands Latin1. Feed the spread a 1 MB Uint8Array and Chrome 156 throws RangeError: Maximum call stack size exceeded, because every byte became a function argument. And when the token is URL-safe base64, you get the bonus round of .replace(/-/g, "+").replace(/_/g, "/") plus padding math.

Hex is no better:

const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");

Fine. It also looks like a sentence written by a compiler.

What it is

The TC39 "Uint8Array to/from Base64" proposal reached Stage 4 in July 2025, and TC39 lists ECMAScript 2026 as its expected publication year. It adds four methods you will use and two you will be glad exist:

bytes.toBase64(options) returns a base64 string.
Uint8Array.fromBase64(string, options) returns a new Uint8Array.
bytes.toHex() returns a lowercase hex string.
Uint8Array.fromHex(string) returns a new Uint8Array.
bytes.setFromBase64(string) and bytes.setFromHex(string) decode into an array you already have.

The options are small:

alphabet: "base64" (default, uses + and /) or "base64url" (uses - and _).
omitPadding (encode only): drop the trailing =.
lastChunkHandling (decode only): "loose" (default), "strict", or "stop-before-partial".

A minimal example

Text to base64 and back, emoji included:

const bytes = new TextEncoder().encode("héllo 👋");

const encoded = bytes.toBase64();
console.log(encoded); // "aMOpbGxvIPCfkYs="

const decoded = new TextDecoder().decode(Uint8Array.fromBase64(encoded));
console.log(decoded); // "héllo 👋"

The same 1 MB array that blew the stack above encodes to a 1,333,336 character string without complaint.

URL-safe output and padding are just options:

const b = new Uint8Array([251, 255, 191]);
console.log(b.toBase64());                         // "+/+/"
console.log(b.toBase64({ alphabet: "base64url" })); // "-_-_"

const two = new Uint8Array([1, 2]);
console.log(two.toBase64());                       // "AQI="
console.log(two.toBase64({ omitPadding: true }));  // "AQI"

And hex, in both directions:

console.log(new Uint8Array([202, 254]).toHex()); // "cafe"
console.log(Uint8Array.fromHex("CAFE"));         // Uint8Array [202, 254]

Uppercase input is accepted, and output is always lowercase.

A realistic example: hashes and tokens

Hashing a string with Web Crypto used to end in that padStart line. Now it ends in one call:

async function sha256Hex(text) {
  const data = new TextEncoder().encode(text);
  const digest = await crypto.subtle.digest("SHA-256", data);
  return new Uint8Array(digest).toHex();
}

console.log(await sha256Hex("hello"));
// "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

Reading the payload of a JWT, which is unpadded base64url, is just as short:

function decodeJwtPayload(token) {
  const part = token.split(".")[1];
  const bytes = Uint8Array.fromBase64(part, { alphabet: "base64url" });
  return JSON.parse(new TextDecoder().decode(bytes));
}

// payload part: "eyJzdWIiOiI0MiIsIm5hbWUiOiJBbmEifQ"
// result: { sub: "42", name: "Ana" }

No character swapping, no padding math. Decoding is not verifying, so do not trust that payload until the signature checks out.

Every output in this post is from a run in Chrome 156.

Can I use it?

From MDN's compatibility data:

Runtime	Version
Chrome / Edge	140
Firefox	133
Safari	18.2
Node.js	25.0.0

MDN marks the methods Baseline 2025, Newly available since September 2025. Current browsers are fine; older ones need a fallback, because the methods are simply missing there.

Gotchas

Node 24 does not have it. On Node 24.11 (V8 13.6), typeof Uint8Array.fromBase64 is "undefined". If the same code runs on the server, check the Node version before deleting the helper.
It lives on Uint8Array only. ArrayBuffer.prototype.toBase64 and Uint16Array.prototype.toBase64 are both undefined. crypto.subtle.digest() returns an ArrayBuffer, so calling digest.toHex() throws TypeError: digest.toHex is not a function. Wrap it in new Uint8Array(...) first.
Forgetting alphabet: "base64url" works until it does not. The JWT payload above decodes fine with the default alphabet, because it happens to contain no - or _. The first token that does throws SyntaxError, which is exactly the kind of bug that waits for production. Always pass the alphabet you actually have.
The default decoder is forgiving. fromBase64("SGVs\nbG8=") and fromBase64("SGVsbG8") both return the bytes for "Hello": whitespace is ignored and missing padding is fine. If you are validating input rather than reading it, pass lastChunkHandling: "strict", and the unpadded version throws SyntaxError.
setFromBase64() only writes whole chunks. Decoding "Hello world" (11 bytes) into an 8 byte array returned { read: 8, written: 6 } and left the last two bytes as 0. It stops at the last full 3 byte group that fits, so check read before assuming the whole string went in.
Odd hex is an error, not a guess. Uint8Array.fromHex("abc") throws SyntaxError: Input string must contain hex characters in even length. Good. Silently padding would have been worse.

Wrap-up

btoa(String.fromCharCode(...bytes)) was always a string API wearing a bytes costume. Search your codebase for fromCharCode(... and padStart(2, "0"), and let Uint8Array do the job it was clearly meant for.

Sources

MDN: Uint8Array.prototype.toBase64()
MDN: Uint8Array.fromBase64()
MDN: Uint8Array.prototype.toHex()
MDN: Uint8Array.prototype.setFromBase64()
MDN browser-compat-data: Uint8Array
TC39: Uint8Array to/from Base64 proposal
TC39: Finished proposals

This article was written with the help of AI and checked against the sources above.

Stop Trimming \r Off Every Regex Match. .NET 11 Has AnyNewLine

JKC — Wed, 28 Oct 2026 05:55:56 +0000

TL;DR: In .NET 11, RegexOptions.AnyNewLine makes ^, $, \Z, and . treat \r\n, \r, and the Unicode line breaks as newlines, not just \n. No more \r?$, and no more values that end in an invisible carriage return. .NET 11 is at Release Candidate 2 right now: go-live licensed, but not final yet.

The character nobody can see

You write a regex that grabs a line. It passes every test, because the test strings were typed in C# with \n. Then a real file arrives from Windows, and every value you capture ends with \r.

using System.Text.RegularExpressions;

var bug = Regex.Match("foo\r\nbar", @".+$", RegexOptions.Multiline);
Console.WriteLine(bug.Value.Length); // 4

Three letters, length 4. The fourth one is \r, and it only shows up later, when "foo" == value is mysteriously false.

The reason is old and simple. .NET's regex engine has always treated only \n as a newline. In Multiline mode, $ matches before \n, and . happily matches \r because, as far as the engine knows, it is just another character.

So everybody learned the ritual: [^\r\n]*\r?$. It looks like someone sneezed on the keyboard, and as you will see below, it is not even correct.

Meet AnyNewLine

.NET 11 adds one flag:

var fixedMatch = Regex.Match("foo\r\nbar", @".+$",
    RegexOptions.Multiline | RegexOptions.AnyNewLine);
Console.WriteLine(fixedMatch.Value.Length); // 3

With it, ^, $, \Z, and . recognize all of these as line breaks: \r\n, \r, \n, \u0085 (NEL),   (line separator), and   (paragraph separator). Microsoft's docs say this follows Unicode TR18 RL1.6.

The important detail is that \r\n counts as one newline. In "a\r\nb", $ matched at positions 1 and 4: before the \r and at the end, never between \r and \n. ^ matched at 0 and 3, so the second line starts at b, not at a stray \n.

A realistic one: a config file from three operating systems

Here is a tiny key=value parser. The input mixes Windows, Unix, and classic Mac line endings, because somebody's editor had opinions.

using System.Text.RegularExpressions;

string config = "host=db.local\r\nport=5432\nuser=app\rtimeout=30\r\n";

foreach (Match m in Config.Line().Matches(config))
    Console.WriteLine($"{m.Groups["key"].Value} = [{m.Groups["value"].Value}]");

static partial class Config
{
    [GeneratedRegex(@"^(?<key>\w+)=(?<value>.*)$",
        RegexOptions.Multiline | RegexOptions.AnyNewLine)]
    public static partial Regex Line();
}

host = [db.local]
port = [5432]
user = [app]
timeout = [30]

Four keys, clean values. The source generator accepts the new flag, and so does RegexOptions.Compiled, which returned the same four values.

Now the same pattern without AnyNewLine. It found only three keys: host came back as db.local\r, and user swallowed the next line whole, as app\rtimeout=30\r. timeout vanished, because to the old engine a lone \r is not a line break at all.

And the ritual? ^(?<key>\w+)=(?<value>[^\r\n]*)\r?$ found 2 of the 4 keys. It fixes \r\n and quietly gives up on a bare \r.

Can I use it?

RegexOptions.AnyNewLine is new in .NET 11, with the value 2048. The .NET 11 Preview 3 release notes introduced it, and the RegexOptions docs list it as available in .NET 11 and later.
It works with new Regex(...), the static Regex methods, RegexOptions.Compiled, and [GeneratedRegex].
.NET 11 RC2 shipped on October 13, 2026 with a go-live support license. It is still a release candidate, and general availability is expected in November.
On the .NET 10 SDK, the code fails to build with CS0117: 'RegexOptions' does not contain a definition for 'AnyNewLine'.

I ran every snippet here as a file-based app with dotnet run file.cs on SDK 11.0.100-rc.1, on Windows.

Gotchas

1. NonBacktracking and ECMAScript say no. RegexOptions.AnyNewLine | RegexOptions.NonBacktracking threw ArgumentOutOfRangeException at construction, and so did the combination with ECMAScript. If you picked NonBacktracking for its linear-time guarantee, you keep \r? for now.

2. There is no inline letter. Multiline has (?m) and Singleline has (?s), but the docs list no inline option for AnyNewLine. You have to pass the flag in code, so a pattern stored in a config file cannot turn it on by itself.

3. Character classes are not newline-aware. The flag changes ^, $, \Z, and ., and nothing else. [^\n]+ against "foo\r\nbar" still matched 4 characters, \r included, with AnyNewLine on. If you want "anything but a line break", use . and let the flag do its job.

4. \A and \z do not move. They still mean the absolute start and end of the string. With AnyNewLine, done\Z matched "done\r\n", while done\z did not. That is by design, and it is the escape hatch when you really do mean "end of input".

5. Singleline still wins. With Singleline | AnyNewLine, a.+ against "a\r\nb" matched the whole string, newline included. Singleline means "the dot matches everything", and the new flag does not argue with it.

6. The docs disagree about \v and \f. The RegexOptions API reference says AnyNewLine also recognizes vertical tab and form feed. The options article lists only the six sequences above. In the RC1 run, . did not match \v or \f, and ^\w$ found 2 lines in "a\vb", so the API reference matches what the runtime did. If your input can contain form feeds, test it rather than trusting either page.

Wrap-up

\r has been hiding at the end of captured strings for as long as .NET has had regex. Now one flag tells the engine what a line actually is, on every OS at once. Go search your codebase for \r?$ and see how many of them can retire in .NET 11.

Sources

This article was written with the help of AI and checked against the sources above.

Stop Writing if (!map.has(key)). Map Has getOrInsert()

JKC — Tue, 27 Oct 2026 10:01:10 +0000

TL;DR: map.getOrInsert(key, []) returns the value for key, and adds [] first if the key is missing. getOrInsertComputed() does the same with a callback, so the default is only built when it is needed. Both landed on Map and WeakMap, and they are Baseline 2026 Newly available.

The three lines everyone has typed

You have a Map and you want to group things into it. So you write the ritual:

if (!groups.has(key)) {
  groups.set(key, []);
}
groups.get(key).push(item);

Three lookups to add one item. Or the shorter version that sneaks in a falsy bug the day someone stores 0:

const list = groups.get(key) || groups.set(key, []).get(key);

It works. It also looks like a riddle.

Every codebase has a getOrCreate helper for this, usually in a file called utils.js, next to three other helpers nobody remembers writing.

What it is

The TC39 "Upsert" proposal reached Stage 4 at the January 2026 meeting, and it adds two methods to both Map and WeakMap:

getOrInsert(key, defaultValue) returns the existing value for key. If the key is missing, it stores defaultValue and returns that.
getOrInsertComputed(key, callback) does the same, but calls callback(key) only when the key is missing, and stores what it returns.

That is the whole API. No options object, no flags.

A minimal example

Counting words, the classic:

const counts = new Map();

for (const word of ["css", "js", "css", "html", "css"]) {
  counts.set(word, counts.getOrInsert(word, 0) + 1);
}

console.log([...counts]);
// [["css", 3], ["js", 1], ["html", 1]]

And the grouping ritual from above becomes one line:

const orders = [
  { id: 1, customer: "ana" },
  { id: 2, customer: "ben" },
  { id: 3, customer: "ana" },
];

const byCustomer = new Map();
for (const order of orders) {
  byCustomer.getOrInsert(order.customer, []).push(order.id);
}

console.log([...byCustomer]);
// [["ana", [1, 3]], ["ben", [2]]]

Both outputs are from a run in Chrome 155.

When the default is expensive

getOrInsert() is a normal function call, so its arguments are evaluated before it runs. If the default is costly, you pay for it even when the key already exists:

let built = 0;
const make = () => {
  built++;
  return 42;
};

const cache = new Map([["a", 1]]);

cache.getOrInsert("a", make());
console.log(built); // 1, built for nothing

built = 0;
cache.getOrInsertComputed("a", make);
console.log(built); // 0, key exists, callback skipped

cache.getOrInsertComputed("b", make);
console.log(built); // 1, key missing, callback ran once

Rule of thumb: a literal like 0 or [] goes to getOrInsert(). Anything that does real work goes to getOrInsertComputed().

The callback also receives the key, which keeps lazy caches short:

const upper = new Map();
console.log(upper.getOrInsertComputed("hello", (key) => key.toUpperCase()));
// "HELLO"

A realistic example: per-element state in a WeakMap

The same methods exist on WeakMap, which is where they get quietly useful. Say you want to track state for DOM elements without leaking memory when they are removed:

const state = new WeakMap();

function stateFor(element) {
  return state.getOrInsertComputed(element, () => ({ clicks: 0 }));
}

document.addEventListener("click", (event) => {
  const button = event.target.closest("button");
  if (!button) return;

  const s = stateFor(button);
  s.clicks++;
  button.dataset.clicks = s.clicks;
});

The first click creates the state object, every later click reuses it, and when the button leaves the DOM the entry can be garbage collected. In a Chrome test page, clicking button A three times and a <span> inside button B once left data-clicks="3" and data-clicks="1", with the callback running exactly twice.

Can I use it?

From MDN's compatibility data:

Runtime	Version
Chrome / Edge	145
Firefox	144
Safari	26.2
Node.js	26.0.0

MDN marks it Baseline 2026, Newly available since February 2026. That means current browsers are fine, but anything older needs a fallback or a polyfill, since the methods simply do not exist there.

Gotchas

Node 24 does not have it. On Node 24.11 (V8 13.6), typeof Map.prototype.getOrInsert is "undefined". If your code also runs on the server, check your Node version before you delete that helper.
An existing undefined counts as existing. new Map([["x", undefined]]).getOrInsert("x", 5) returns undefined and leaves it there. The check is "does the key exist", not "is the value truthy", which is exactly what the || trick gets wrong.
The callback's return value wins. If the callback itself calls map.set(key, ...), the method still stores what the callback returns. In a run, the map ended up holding "returned", not the value set inside the callback, with a size of 1. Better still, do not mutate the map from inside the callback.
WeakMap keys still must be objects. new WeakMap().getOrInsert("str", 1) throws TypeError: Invalid value used as weak map key. The new methods do not relax the old rules.
The error message blames the wrong thing. Pass a non-function to getOrInsertComputed() and Chrome 155 throws TypeError: Map.prototype.getOrInsertComputed is not a function. The method exists. It is your second argument that is not a function.

Wrap-up

The has, set, get dance was always three lookups wearing a trench coat. Find your getOrCreate helper, swap it for getOrInsert() or getOrInsertComputed(), and delete one more file from utils/.

Sources

MDN: Map.prototype.getOrInsert()
MDN: Map.prototype.getOrInsertComputed()
MDN: WeakMap.prototype.getOrInsertComputed()
MDN browser-compat-data: Map
TC39: Upsert proposal
TC39: Finished proposals
ECMAScript spec: Map.prototype.getOrInsert

This article was written with the help of AI and checked against the sources above.

Stop Blocking on the Database Inside IsValid. .NET 11 Validates Async

JKC — Sun, 25 Oct 2026 06:45:37 +0000

TL;DR: .NET 11 lets DataAnnotations rules await things. Derive from AsyncValidationAttribute, or implement IAsyncValidatableObject, and call Validator.TryValidateObjectAsync. .NET 11 is a release candidate right now: go-live licensed, but not final yet.

The line nobody wants to touch

"Is this email already taken?" is a validation rule. It is also a database query. DataAnnotations has always been synchronous, so the rule ends up looking like this:

sealed class UniqueEmailAttribute : ValidationAttribute
{
    protected override ValidationResult? IsValid(object? value, ValidationContext validationContext)
    {
        // The database call is async. The validator is not. So...
        bool taken = UserStore.IsTakenAsync((string)value!).GetAwaiter().GetResult();
        return taken ? new ValidationResult("That email is already taken.") : ValidationResult.Success;
    }
}

It works. It ran fine on .NET 10 and correctly said the email was taken. It also parks a thread-pool thread for the whole query, which is fine right up until a lot of people sign up at once. So most teams move the check out of the model, into the controller, and now the rules live in two places.

Meet AsyncValidationAttribute

.NET 11 adds three things to System.ComponentModel.DataAnnotations:

AsyncValidationAttribute, a base class with IsValidAsync.
IAsyncValidatableObject, whose ValidateAsync returns an IAsyncEnumerable<ValidationResult>.
Validator.TryValidateObjectAsync, ValidateObjectAsync, ValidatePropertyAsync, and ValidateValueAsync.

Here is the same rule, without the hostage situation:

[AttributeUsage(AttributeTargets.Property)]
sealed class UniqueAttribute(string field) : AsyncValidationAttribute
{
    protected override ValidationResult? IsValid(object? value, ValidationContext validationContext) =>
        throw new InvalidOperationException("[Unique] needs the async validator APIs.");

    protected override async Task<ValidationResult?> IsValidAsync(
        object? value, ValidationContext validationContext, CancellationToken cancellationToken)
    {
        if (value is not string s) return ValidationResult.Success;
        var store = (UserStore)validationContext.GetService(typeof(UserStore))!;
        bool taken = await store.IsTakenAsync(field, s, cancellationToken);
        return taken
            ? new ValidationResult($"That {field} is already taken.", [validationContext.MemberName!])
            : ValidationResult.Success;
    }
}

The synchronous IsValid is still abstract, so you have to decide what it does. Throwing is what the ASP.NET Core docs recommend for a rule that only works async, and gotcha 2 shows why.

Use it like any other attribute:

class SignUp
{
    [Required, EmailAddress, Unique("email")]
    public string? Email { get; set; }

    [Required, Unique("handle")]
    public string? Handle { get; set; }
}

var form = new SignUp { Email = "taken@example.com", Handle = "neo" };
var results = new List<ValidationResult>();
var ctx = new ValidationContext(form, services, null);

bool ok = await Validator.TryValidateObjectAsync(form, ctx, results, validateAllProperties: true);

valid=False
  Email: That email is already taken.

services is any IServiceProvider; in ASP.NET Core it is the request's container. In my test, the fake email lookup waited 200 ms and the handle lookup waited 600 ms. The whole validation took 608 ms, because the two properties were checked at the same time.

A realistic one: the booking form

Rules that span fields go on the object. Check-out after check-in is a plain comparison; "is the room free" needs the database:

using System.Runtime.CompilerServices; // for [EnumeratorCancellation]

class Booking : IAsyncValidatableObject
{
    [Required] public string? Room { get; set; }
    public DateOnly From { get; set; }
    public DateOnly To { get; set; }

    public IEnumerable<ValidationResult> Validate(ValidationContext validationContext) =>
        throw new InvalidOperationException("Booking validates asynchronously. Use Validator.TryValidateObjectAsync.");

    public async IAsyncEnumerable<ValidationResult> ValidateAsync(
        ValidationContext validationContext,
        [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        if (To <= From)
            yield return new ValidationResult("Check-out must be after check-in.", [nameof(To)]);

        await Task.Delay(50, cancellationToken); // the availability query
        if (Room == "Blue")
            yield return new ValidationResult("Blue is fully booked for those dates.", [nameof(Room)]);
    }
}

With Room = "Blue" and the dates backwards, TryValidateObjectAsync returned both errors:

Check-out must be after check-in. | Blue is fully booked for those dates.

The synchronous Validate was called zero times. On the async path, the validator calls only ValidateAsync, so the plain date check has to live in there too.

Can I use it?

Where	What you get
`System.ComponentModel.DataAnnotations`	`AsyncValidationAttribute`, `IAsyncValidatableObject`, async `Validator` methods
Minimal APIs (`AddValidation()`)	Runs async rules before the endpoint
Blazor `DataAnnotationsValidator`	Awaits async rules on `EditForm` submit
`Microsoft.Extensions.Options`	Async options validation, and `IAsyncStartupValidator`

The base library APIs arrived in .NET 11 Preview 6, per the ASP.NET Core release notes.
.NET 11 RC2 shipped on October 13, 2026 with a go-live support license. It is still a release candidate.
On the .NET 10 SDK, the attribute fails with CS0246: The type or namespace name 'AsyncValidationAttribute' could not be found.

I ran every snippet here as a file-based app with dotnet run file.cs on SDK 11.0.100-rc.1, on Windows.

Gotchas

1. validateAllProperties still defaults to "not really". TryValidateObjectAsync(form, ctx, results) without the flag checks only [Required] and type-level rules. For the taken email above, it answered valid=True with zero errors. Same rule as the sync API, and just as easy to forget.

2. The sync API does not skip your async rule. Validator.TryValidateObject on the same form called the sync IsValid, which threw InvalidOperationException: [Unique] needs the async validator APIs. That is the point of throwing: a silent Success would let the taken email through.

3. Pass null for the results to fail fast. With a results list, a form where both checks fail took 605 to 608 ms and collected two errors. With null, it stopped at the first failure in 200 to 214 ms, and the 600 ms handle lookup saw its token cancelled. So honor the CancellationToken, or the shortcut waits for you anyway.

4. Stages still run in order. Property rules first, then type-level attributes, then the object. With Room empty, the result was only The Room field is required., and ValidateAsync never ran. Your users will meet the date error on their second try.

5. File-based apps complain about trimming. File-based apps default to PublishAot=true, and every ValidationContext constructor and Validator call raised IL2026. I added #:property PublishAot=false to the test file. In a trimmed app, take the warning seriously: it says the context uses reflection to find your type's display names.

Wrap-up

The async check finally lives next to [Required], where everybody looks for it. Go find the .GetAwaiter().GetResult() in your validators and give it the day off.

Sources

This article was written with the help of AI and checked against the sources above.

Stop Nesting try/finally for Cleanup. JavaScript Has using

JKC — Sat, 24 Oct 2026 03:19:19 +0000

TL;DR: using file = ... calls file[Symbol.dispose]() the moment the block ends, whether it returned or threw. It ships in Chrome 134+, Edge 134+, Firefox 141+, Node 24+, Deno and Bun, but Safari has it only in Technology Preview, so it is not Baseline yet.

The pyramid nobody wants to touch

Every codebase has a function shaped like this:

const file = await open(path, "w");
try {
  const timer = setInterval(report, 1000);
  try {
    await writeEverything(file);
  } finally {
    clearInterval(timer);
  }
} finally {
  await file.close();
}

Two resources, two finally blocks, four levels of indentation. Add a third resource and the function starts drifting off the right side of the screen. Forget one finally and you leak a file handle that only shows up in production at 3 a.m.

The cleanup is always the same: undo things in the reverse order you did them. That is exactly the kind of bookkeeping a language should do for you.

What it is

Explicit resource management adds two declarations and a few helpers:

Piece	What it does
`using x = value`	Calls `x[Symbol.dispose]()` when the scope exits
`await using x = value`	Awaits `x[Symbol.asyncDispose]()` when the scope exits
`DisposableStack`	Collects cleanups by hand with `use()`, `defer()`, `adopt()` and `move()`
`AsyncDisposableStack`	The same, for async cleanups
`SuppressedError`	Carries a cleanup error together with the error it interrupted

It is a TC39 Stage 4 proposal, listed in TC39's finished proposals with an expected publication year of 2027.

A minimal example

Any object with a [Symbol.dispose]() method can be using-ed:

function resource(name) {
  console.log(`open ${name}`);
  return { [Symbol.dispose]() { console.log(`close ${name}`); } };
}

{
  using db = resource("db");
  using cache = resource("cache");
  console.log("working");
}
console.log("after the block");

Output from Node 24.11:

open db
open cache
working
close cache
close db
after the block

Last in, first out. The cache is closed before the database it might depend on, and you did not write a single finally.

A realistic example: writing a file with a progress timer

Node's FileHandle already has [Symbol.asyncDispose], so await using works on it out of the box. A timer is not disposable, but DisposableStack.defer() turns any cleanup function into one.

import { open, readFile } from "node:fs/promises";

let lastFile; // only here so we can peek after the function returns

async function exportCsv(path, rows) {
  await using file = await open(path, "w");
  lastFile = file;

  using stack = new DisposableStack();
  const timer = setInterval(() => console.log("still writing..."), 1000);
  stack.defer(() => {
    clearInterval(timer);
    console.log("timer cleared");
  });

  for (const row of rows) {
    if (!Array.isArray(row)) throw new Error(`bad row: ${row}`);
    await file.write(row.join(",") + "\n");
  }
  return rows.length;
}

console.log("wrote", await exportCsv("ok.csv", [["id", "name"], [1, "Ada"]]), "rows");
console.log("fd after success:", lastFile.fd);
console.log(JSON.stringify(await readFile("ok.csv", "utf8")));

try {
  await exportCsv("bad.csv", [["id"], "oops"]);
} catch (e) {
  console.log("caught:", e.message);
}
console.log("fd after failure:", lastFile.fd);

Output from Node 24.11:

timer cleared
wrote 2 rows
fd after success: -1
"id,name\n1,Ada\n"
timer cleared
caught: bad row: oops
fd after failure: -1

An fd of -1 means the handle is closed. Happy path or thrown error, the timer is cleared and the file is closed, in that order. The pyramid from the top of this post is now flat.

Can I use it?

On the server, yes: Node has it from 24.0, Deno from 2.2.10 and Bun from 1.3.0, according to MDN's compatibility data.

In the browser, mostly. Chrome and Edge shipped it in 134, and Firefox in 141. Safari lists it only as "preview", which means Safari Technology Preview, and MDN marks the feature as Limited availability. If you ship to Safari users, keep the try/finally version or let your build tool transpile using for now.

Gotchas

Not at the top level of a classic script. MDN says using is not allowed at the top level of a script, and Node's vm.Script throws SyntaxError: Unexpected identifier 'a' for using a = null;. Modules, functions and blocks are fine. A CommonJS file works too, because Node wraps it in a function.
The value must be disposable, or nothing. using x = { name: "no dispose" } throws TypeError: Symbol(Symbol.dispose) is not a function. null and undefined are allowed and simply skipped, which is handy for optional resources.
Cleanup errors do not swallow the real error. If the block throws and a disposer throws too, you get a SuppressedError. Its error is the cleanup failure and its suppressed is the original one, so check both before blaming the wrong line.
Closures can outlive the resource. This returns a function that reads an already closed resource:

function getReader() {
  using r = { open: true, [Symbol.dispose]() { this.open = false; } };
  return () => r.open;
}
console.log("still open?", getReader()()); // still open? false

using ties the lifetime to the block, not to whoever holds a reference.

Constructors want move(). When an object opens two resources and the second one fails, the first should be closed. Build them on a stack and call move() only after everything succeeded:

class Connection {
  #stack;
  constructor() {
    using stack = new DisposableStack();
    this.db = stack.use(openDb());
    this.cache = stack.use(openCache()); // if this throws, db is closed
    this.#stack = stack.move();          // success: we own them now
  }
  [Symbol.dispose]() { this.#stack.dispose(); }
}

In Node 24.11, a failing openCache() printed open db, close db, then the error. On success, nothing closes until the caller's own using conn = new Connection() goes out of scope.

Wrap-up

Cleanup code was always the part we copy, paste and forget. Find your deepest try/finally pyramid, give its resources a [Symbol.dispose], and let the block end do the work.

Sources

MDN: using
MDN: DisposableStack
MDN: Firefox 141 release notes for developers
MDN browser-compat-data: DisposableStack
Web Platform Status: Explicit resource management
TC39: Finished proposals
TC39: Explicit Resource Management proposal

This article was written with the help of AI and checked against the sources above.

Stop Hand-Rolling Full Outer Joins in LINQ. .NET 11 Has FullJoin

JKC — Fri, 23 Oct 2026 01:10:59 +0000

TL;DR: In .NET 11, a.FullJoin(b, x => x.Key, y => y.Key) returns every matched pair plus the unmatched rows from both sides, as (Outer, Inner) tuples. Join, LeftJoin, RightJoin, and GroupJoin also get overloads with no result selector. .NET 11 is at Release Candidate 2 right now: go-live licensed, but not final yet.

The join you Google every time

You have two lists that should agree and never do. What the system thinks is in stock, and what the stocktake actually counted. You want three answers: what matches, what only the left side has, and what only the right side has.

SQL calls that a full outer join. LINQ never had one, so everybody pastes the same answer:

var left =
    from s in system
    join c in counted on s.Sku equals c.Sku into matches
    from c in matches.DefaultIfEmpty()
    select (Record: s, Count: c);

var rightOnly =
    from c in counted
    where !system.Any(s => s.Sku == c.Sku)
    select (Record: (StockRecord?)null, Count: c);

var full = left.Concat(rightOnly);

It works. It is also two queries, a DefaultIfEmpty nobody can explain on the first read, and an Any inside a where, which scans the whole left list once for every row on the right. And the key comparison lives in two places, so the day someone changes one of them, the halves quietly disagree.

Meet FullJoin

.NET 10 already added LeftJoin and RightJoin. .NET 11 closes the set with FullJoin, and it returns tuples, so you do not even need a result selector:

var products = new List<(int Id, string Name, string? Category)>
{
    (1, "Laptop", "Electronics"),
    (2, "Mouse", "Electronics"),
    (3, "Orphan", null),
};
var categories = new List<(string Name, string Description)>
{
    ("Electronics", "Electronic devices"),
    ("Furniture", "Office furniture"),
};

foreach (var pair in products.FullJoin(categories, p => p.Category, c => c.Name))
    Console.WriteLine($"{pair.Outer.Name ?? "(none)"} | {pair.Inner.Description ?? "(none)"}");

Laptop | Electronic devices
Mouse | Electronic devices
Orphan | (none)
(none) | Office furniture

The tuple elements are named Outer and Inner, and the side with no match is default. For reference types, that means null, which is exactly what you want to pattern match on. Here the elements are themselves tuples, so a missing side is an empty tuple whose Name is null; gotcha 1 explains why that deserves a second look.

The same release gives the old operators a selector-free overload, too. products.Join(categories, p => p.Category, c => c.Name) now yields (Outer, Inner) pairs, so (p, c) => new { p, c } can finally retire.

A realistic one: the stocktake

Here is the reconciliation from the start, done properly. The counted SKUs were typed by a human, so one of them is lowercase.

List<StockRecord> system =
[
    new("SKU-100", "USB-C cable", 40),
    new("SKU-200", "Desk lamp", 12),
    new("SKU-300", "Monitor arm", 5),
];

List<ShelfCount> counted =
[
    new("sku-100", 38),
    new("SKU-300", 5),
    new("SKU-999", 3),
];

var report = system.FullJoin(
    counted,
    s => s.Sku,
    c => c.Sku,
    StringComparer.OrdinalIgnoreCase);

foreach (var (record, count) in report)
{
    Console.WriteLine((record, count) switch
    {
        (null, { } c) => $"{c.Sku}: on the shelf, not in the system ({c.Quantity})",
        ({ } r, null) => $"{r.Sku}: in the system, not on the shelf ({r.Quantity} missing)",
        ({ } r, { } c) when r.Quantity != c.Quantity => $"{r.Sku}: off by {c.Quantity - r.Quantity}",
        ({ } r, _) => $"{r.Sku}: OK",
        (null, null) => "nothing on either side, which FullJoin never yields",
    });
}

record StockRecord(string Sku, string Name, int Quantity);
record ShelfCount(string Sku, int Quantity);

SKU-100: off by -2
SKU-200: in the system, not on the shelf (12 missing)
SKU-300: OK
SKU-999: on the shelf, not in the system (3)

One call, one comparer, and a switch that reads like the spec. The comparer is a plain optional parameter, which the query-syntax join ... equals never let you pass at all. It built with zero warnings, nullable checks included.

Can I use it?

FullJoin and the tuple-returning overloads are new in .NET 11. The .NET 11 Preview 5 announcement listed "LINQ adds full outer joins", and the release notes cover both additions.
They exist on Enumerable, Queryable, and AsyncEnumerable. Existing on Queryable does not mean every provider translates them, though: see gotcha 6 for EF Core.
.NET 11 RC2 shipped on October 13, 2026 with a go-live support license. It is still a release candidate.
On the .NET 10 SDK, the call fails with CS1061: 'int[]' does not contain a definition for 'FullJoin'.

I ran every snippet here as a file-based app with dotnet run file.cs on SDK 11.0.100-rc.1, on Windows. The classic two-query version ran on the .NET 10 SDK, with the SKUs in matching case, and paired up the same four rows.

Gotchas

1. Value types hide the missing side. default for an int is 0, not "nothing". A full join of the int arrays [0, 5] and [0, 7] on the values themselves printed (0,0), (5,0), (0,7), and you cannot tell the real match from the two misses. With int?[] the same data printed (0,0), (5,null), (null,7). If your elements are structs or tuples, make them nullable or check a field that is never empty.

2. Null keys never match. Joining ["a", null] with [null, "b"] gave four rows, and the two null keys came out as separate unmatched rows instead of a pair. That is the same rule Join has always had, so this is consistency, not a bug.

3. Duplicate keys multiply. [1, 1, 2] joined with [1, 1, 3] produced four (1,1) rows, then (2,0) and (0,3). Two times two is still four, even in a full join.

4. Unmatched right rows come last. Joining ["x", "a", "y"] with ["b", "a", "c"] gave (x,-), (a,a), (y,-), (-,b), (-,c). Left rows keep their order, and the right-only rows are appended at the end in their own order. If your report needs a different order, sort it.

5. GroupJoin's new overload is not a tuple. The selector-free GroupJoin returns IGrouping<TOuter, TInner>, so the outer element is g.Key. Grouping the products from the first example under their categories gave Electronics: 2 [Laptop, Mouse] and Furniture: 0 [].

6. EF Core wants a result selector, and no comparer. Added after a reader asked about EF Core in the comments. EF Core 11 translates FullJoin to a real FULL JOIN on relational providers, but only the overload with a result selector. On EF Core 11 RC1, with SQL Server LocalDB and SQLite, this worked:

var rows = db.SystemRecords.FullJoin(
    db.ShelfCounts,
    s => s.Sku,
    c => c.Sku,
    (s, c) => new { S = s.Sku, C = c.Sku });

SELECT [s].[Sku] AS [S], [s0].[Sku] AS [C]
FROM [SystemRecords] AS [s]
FULL JOIN [ShelfCounts] AS [s0] ON [s].[Sku] = [s0].[Sku]

The selector-free tuple overload from the top of this post threw "could not be translated" on every provider I tried, SQL Server included. Passing StringComparer.OrdinalIgnoreCase threw as well; in SQL, the column collation does that job. That cuts both ways: with sku-100 against SKU-100, SQL Server's default case-insensitive collation matched them, while SQLite returned two unmatched rows. The InMemory provider rejected both shapes, so a query that passes against SQL Server can still throw in an InMemory test. Cosmos rejected them too, checked with ToQueryString() only, since no emulator was running.

Wrap-up

The full outer join was the last SQL join that LINQ made you build by hand. Now it is one call that tells you what matches, what is missing, and what showed up uninvited. Go find that DefaultIfEmpty().Concat(...) in your codebase and see whether it survives .NET 11.

Sources

This article was written with the help of AI and checked against the sources above.

Stop Hardcoding Sunday as Day One. Intl.Locale Has getWeekInfo()

JKC — Thu, 22 Oct 2026 02:37:22 +0000

TL;DR: new Intl.Locale("en-GB").getWeekInfo() tells you the week starts on Monday and the weekend is Saturday and Sunday. With Firefox 153, the whole Intl.Locale info family is Baseline Newly available, so you can delete that hand-rolled "first day of week" table.

The line nobody wants to touch

Every date picker has it somewhere.

const FIRST_DAY = 0; // Sunday. Probably. Ask product.

Then a user in London opens the calendar and the week starts on the wrong day. Someone adds if (locale === "en-GB") ..., then a lookup table, then a ticket about Israel, where the weekend is Friday and Saturday. The table grows. Nobody is sure where the data came from.

The browser already ships that data. It has been sitting in the Unicode CLDR tables that power Intl.DateTimeFormat all along. Now there is a standard way to ask for it.

What it is

Intl.Locale has seven get methods that answer "how does this locale do things?":

Method	What you get back
`getWeekInfo()`	`{ firstDay, weekend }`
`getHourCycles()`	Hour cycles such as `["h12"]` or `["h23"]`
`getTextInfo()`	`{ direction: "ltr" }` or `{ direction: "rtl" }`
`getTimeZones()`	IANA time zones for the locale's region
`getCalendars()`	Calendars in use, most preferred first
`getCollations()`	Sort orders in use
`getNumberingSystems()`	Digit systems in use

They came from the TC39 Intl Locale Info proposal, which is now Stage 4 and part of ECMA-402.

A minimal example

for (const tag of ["en-US", "en-GB", "he-IL", "ar-AF", "fa-IR"]) {
  console.log(tag, new Intl.Locale(tag).getWeekInfo());
}

Run in Node 24.11:

en-US { firstDay: 7, weekend: [ 6, 7 ] }
en-GB { firstDay: 1, weekend: [ 6, 7 ] }
he-IL { firstDay: 7, weekend: [ 5, 6 ] }
ar-AF { firstDay: 6, weekend: [ 4, 5 ] }
fa-IR { firstDay: 6, weekend: [ 5 ] }

Days are numbered 1 for Monday through 7 for Sunday. Notice fa-IR: a one-day weekend. Your two-element array assumption just left the chat.

The siblings work the same way:

new Intl.Locale("en-US").getHourCycles(); // ["h12"]
new Intl.Locale("en-GB").getHourCycles(); // ["h23"]
new Intl.Locale("ar").getTextInfo();      // { direction: "rtl" }
new Intl.Locale("th-TH").getCalendars();  // ["buddhist", "gregory"]

A realistic example: a calendar header

Here is a week header that starts on the right day and marks the weekend, with no lookup table. The day labels are in English so the output stays readable here; drop the second argument to get them in the user's language.

// firstDay and weekend use 1 = Monday ... 7 = Sunday.
// Date#getDay() uses 0 = Sunday ... 6 = Saturday.
const isoDay = (date) => date.getDay() || 7;

function weekHeader(tag, labels = tag) {
  const locale = new Intl.Locale(tag);
  const { firstDay, weekend } = locale.getWeekInfo();
  const fmt = new Intl.DateTimeFormat(labels, { weekday: "short", timeZone: "UTC" });

  // 2024-01-01 was a Monday, so day n (1-7) is January n.
  return Array.from({ length: 7 }, (_, i) => {
    const day = ((firstDay - 1 + i) % 7) + 1;
    const label = fmt.format(new Date(Date.UTC(2024, 0, day)));
    return weekend.includes(day) ? `[${label}]` : label;
  }).join(" ");
}

function isWeekend(date, tag) {
  return new Intl.Locale(tag).getWeekInfo().weekend.includes(isoDay(date));
}

for (const tag of ["en-US", "en-GB", "he-IL", "fa-IR"]) {
  console.log(tag.padEnd(6), weekHeader(tag, "en"));
}

const friday = new Date(2026, 9, 23); // October 23, 2026
console.log(friday.toDateString(), "en-US:", isWeekend(friday, "en-US"), "he-IL:", isWeekend(friday, "he-IL"));

Output from Node 24.11:

en-US  [Sun] Mon Tue Wed Thu Fri [Sat]
en-GB  Mon Tue Wed Thu Fri [Sat] [Sun]
he-IL  Sun Mon Tue Wed Thu [Fri] [Sat]
fa-IR  Sat Sun Mon Tue Wed Thu [Fri]
Fri Oct 23 2026 en-US: false he-IL: true

Same Friday, two answers. Both correct.

The same idea fixes time pickers: getHourCycles()[0] tells you whether to show an AM/PM toggle (h12) or a 0 to 23 clock (h23), and getTextInfo().direction tells you which way to lay out the arrows.

Can I use it?

Yes. The feature is Baseline Newly available since July 21, 2026, when Firefox 153 shipped all seven methods. Chrome and Edge have had the method form since 130, and Safari since 17. Node has it from 24.0.

Older Chrome (99 to 129) and Safari 15.4 to 16 exposed the same data as getters named weekInfo, hourCycles and so on. If you need those users, feature-detect:

const weekInfo = (locale) => locale.getWeekInfo?.() ?? locale.weekInfo;

Gotchas

Days are ISO, not getDay(). firstDay uses 1 for Monday and 7 for Sunday, while Date#getDay() uses 0 for Sunday. Convert with date.getDay() || 7, or enjoy a calendar that is off by one only on Sundays.
minimalDays is gone. MDN's getWeekInfo() page still shows a minimalDays property, but it was dropped from the proposal. MDN's own compat data says Chrome removed it in 136, and Node 24.11 does not return it. Do not build week numbering on it.
The weekend is not always two days, or a Saturday. fa-IR returns [5], and ar-AF returns [4, 5]. Use weekend.includes(day), never day >= 6.
getTimeZones() needs a region. new Intl.Locale("en-AU").getTimeZones() returned 12 zones in Node, but new Intl.Locale("en").getTimeZones() returned undefined. Handle the missing case.
Unicode extensions win. In Node, new Intl.Locale("en-US-u-fw-mon").getWeekInfo().firstDay is 1, and en-US-u-hc-h23 gives ["h23"]. That is handy for a "week starts on" user setting, but it means the result is not always the region default.
Each call returns a new object. locale.getWeekInfo() === locale.getWeekInfo() is false. That is exactly why the spec moved from getters to methods, so cache the result if you call it in a render loop.

Wrap-up

The week-start table in your codebase was always a guess about data the browser already had. Find your FIRST_DAY constant, swap it for getWeekInfo(), and let CLDR take the tickets.

Sources

MDN: Intl.Locale.prototype.getWeekInfo()
MDN: Intl.Locale.prototype.getHourCycles()
MDN: Firefox 153 release notes for developers
web.dev: July 2026 Baseline monthly digest
web-features: intl-locale-info status
MDN browser-compat-data: Intl.Locale
TC39: Intl Locale Info proposal

This article was written with the help of AI and checked against the sources above.

Your Process.Start Code Can Deadlock. .NET 11 Has RunAndCaptureText

JKC — Wed, 21 Oct 2026 01:35:52 +0000

TL;DR: In .NET 11, Process.RunAndCaptureText("git", ["status", "--porcelain"]) starts the process, reads stdout and stderr at the same time, waits for exit, and hands you both strings plus the exit code. .NET 11 is at Release Candidate 2 right now: go-live licensed, but not final yet.

The ten lines everyone copies

You want to run git, or ffmpeg, or some CLI your team wrote in 2019. You want its output and its exit code. So you write the ten lines everyone writes:

var psi = new ProcessStartInfo("some-tool", "build")
{
    RedirectStandardOutput = true,
    RedirectStandardError = true,
};
using var p = Process.Start(psi)!;
string output = p.StandardOutput.ReadToEnd();
string errors = p.StandardError.ReadToEnd();
p.WaitForExit();

It works on your machine. Then one day the tool prints a lot of warnings, and your app just stops. No exception, no log line, no CPU.

Here is why. Redirected output goes through pipes with small buffers. Your code reads stdout to the end before it touches stderr. The child fills the stderr pipe and waits for someone to drain it. You are waiting for stdout to finish, the child is waiting for you, and nobody is coming.

I reproduced it with a child that writes 1 MB to stderr and a short line to stdout. The StandardOutput.ReadToEnd() call had still not returned after 5 seconds, so the demo killed the child. Swapping the two reads does not help either: then a chatty stdout blocks it instead.

The real fix used to be OutputDataReceived, ErrorDataReceived, BeginOutputReadLine, and a StringBuilder per stream. Nobody remembers that code. Everybody pastes it.

Meet RunAndCaptureText

.NET 11 adds a set of one-shot helpers to Process. The one you want most of the time:

using System.Diagnostics;

ProcessTextOutput result = Process.RunAndCaptureText("git", ["--version"]);

Console.WriteLine(result.StandardOutput.TrimEnd()); // git version 2.51.2.windows.1
Console.WriteLine(result.ExitStatus.ExitCode);      // 0

ProcessTextOutput carries StandardOutput, StandardError, ExitStatus, and ProcessId. The arguments are a list, so nothing needs quoting. I passed ["echo", "my file.txt", "say \"hi\"", ""] to a child that echoes each argument after echo in brackets, and it printed [my file.txt], [say "hi"], and an empty [].

The same 1 MB stderr child that hung the classic code finished in one call:

stdout='built OK', stderr chars=1000000, exit=3, canceled=False

According to the .NET team's write-up, the sync version drains both pipes at once by multiplexing on one thread, and the async version uses async I/O, so neither burns a thread per stream.

A realistic one: a tiny git wrapper

Most apps that shell out want the same thing: give me stdout, and throw with stderr if it failed.

using System.Diagnostics;

string repo = args[0];

string[] changed = Git(repo, "status", "--porcelain")
    .Split('\n', StringSplitOptions.RemoveEmptyEntries);
Console.WriteLine($"{changed.Length} changed file(s):");
foreach (var line in changed) Console.WriteLine($"  {line}");

try
{
    Git(repo, "checkout", "no-such-branch");
}
catch (InvalidOperationException ex)
{
    Console.WriteLine(ex.Message);
}

static string Git(string repo, params string[] args)
{
    ProcessTextOutput result = Process.RunAndCaptureText(
        "git", ["-C", repo, .. args], timeout: TimeSpan.FromSeconds(30));

    if (result.ExitStatus.ExitCode != 0)
        throw new InvalidOperationException(
            $"git {string.Join(' ', args)} failed ({result.ExitStatus.ExitCode}): {result.StandardError.Trim()}");

    return result.StandardOutput;
}

Run against a fresh repo with two untracked files:

2 changed file(s):
  ?? "my file.txt"
  ?? notes.md
git checkout no-such-branch failed (1): error: pathspec 'no-such-branch' did not match any file(s) known to git

The whole process story is one call and one if. The timeout is built in, too, which is more than most hand-rolled versions ever got.

The rest of the family

Process.Run(fileName, args, silent, timeout) runs a process and returns only a ProcessExitStatus. With silent: true, its stdin, stdout, and stderr go to the null device.
Process.RunAndCaptureTextAsync(...) is the async twin, and takes a CancellationToken.
process.ReadAllText() and ReadAllBytes() drain both streams of a process you started yourself.
process.ReadAllLines() and ReadAllLinesAsync() yield ProcessOutputLine values with Content and a StandardError flag, so you know which stream each line came from:

var psi = new ProcessStartInfo("git", ["--version"])
{
    RedirectStandardOutput = true,
    RedirectStandardError = true,
};
using var g = Process.Start(psi)!;

foreach (ProcessOutputLine line in g.ReadAllLines())
    Console.WriteLine($"{(line.StandardError ? "err" : "out")}: {line.Content}");

g.WaitForExit();
// out: git version 2.51.2.windows.1

Can I use it?

These APIs are new in .NET 11 and live in System.Diagnostics. The .NET team's post says they arrived in Preview 4.
.NET 11 RC2 shipped with a go-live support license, so production use is allowed. It is still a release candidate, and the API docs still carry the prerelease warning.
On the .NET 10 SDK, the git wrapper fails with CS0117: 'Process' does not contain a definition for 'RunAndCaptureText'.
The docs mark them unsupported on iOS and tvOS.

I ran every snippet here as a file-based app with dotnet run file.cs on SDK 11.0.100-rc.1, on Windows.

Gotchas

1. A timeout while reading throws. RunAndCaptureText with a 2-second timeout, on a child that sleeps for 10, threw TimeoutException after 2.0 seconds. The docs say it kills the process first, and in my run no child was left behind. You only get a result with ExitStatus.Canceled == true when the streams already closed but the process still did not exit in time.

2. Process.Run reports a timeout instead. Process.Run on the same sleeping child, with silent: true and a 1-second timeout, returned Canceled=True and ExitCode=-1. Same idea, different shape, so check Canceled before you trust the exit code.

3. Async cancellation throws, too. RunAndCaptureTextAsync with a token cancelled after 2 seconds threw OperationCanceledException after 2.0 seconds. Catch it where you catch your other cancellations.

4. A ProcessStartInfo must redirect both streams. The ProcessStartInfo overload of RunAndCaptureText throws InvalidOperationException unless RedirectStandardOutput and RedirectStandardError are both true, and UseShellExecute is false. Process.Run wants the opposite: no redirection at all.

5. ReadAllText ends at end-of-stream, not at exit. A child can close its output and keep running. If you use ReadAllText or ReadAllLines on your own Process, still call WaitForExit() before you read the exit code.

6. A non-zero exit code is not an exception. git status outside a repository came back from Process.Run with exit code 128 and no exception. The helpers report what happened; deciding it was a failure is still your job, which is fair, since grep exits with 1 just for finding nothing.

Wrap-up

Shelling out used to mean ten lines of boilerplate and one deadlock waiting for a noisy day. Now it is one call with a timeout. Go find that ProcessHelper.cs everybody copied from Stack Overflow and see how much of it survives .NET 11.

Sources

This article was written with the help of AI and checked against the sources above.