DEV Community: nyaomaru

The relevant type originally looked roughly like this

refinement: Predicate.Refinement<E, EB>;

and the fix changed it to

refinement: Predicate.Refinement<NoInfer<E>, EB>;

The important idea is that the refinement's input type should not be allowed to redefine the error type already established by the Effect.

The PR also adds type tests for cases like

const result = Effect.catchIf(
  mixedEffect,
  (e: unknown): e is AiError => e instanceof AiError,
  () => Effect.succeed("ok"),
);

Without the fix, the refinement input could participate in inference and widen the error channel.

With NoInfer, the original error type remains the source of truth.

The same pattern was fixed for Channel and Stream too.

There was also a Bluesky post about the issue

Not like the lib itself caught it, but when I created a reusable operator: export const isNotFoundError = and( isObject, refineDefinedKey('reason', equalsKey('_tag', 'NotFound')), ) I noticed my streams having unknown in the error channel github.com/Effect-TS/ef...
— Evangeline Rome 🌵🦎🌱🐢🐍🐸 🥦 (@evadeva.bsky.social) 2026-10-15T16:38:16.787Z

I really liked this bug because it came from an interaction I would probably never have discovered by testing is-kit alone.

is-kit did not "break Effect". And Effect was not doing something absurd either.

It was a subtle TypeScript inference interaction between a generic API and a refinement whose input was intentionally broad.

That is exactly the kind of edge case that appears when libraries start meeting each other in real code.

👍 This Is the Kind of Feedback I Wanted

When is-kit reached 50 stars, I wrote

"Someone found this idea useful."

That was already enough to make me happy.

100 stars still does not mean the library is huge.

A star is still not a benchmark.
It is still not proof of correctness.
And it definitely does not mean every TypeScript project should install is-kit.

But something has changed.

People are not only starring the repository anymore.

They are

Using the library
Asking questions
Finding edge cases
Reporting bugs
Comparing it with other validation approaches
Using its guards with other TypeScript libraries
Making me reconsider APIs I thought were already finished

That is much more valuable than the number itself. 💖

💬 The Project Is Also Becoming Easier to Explain

Another thing changed between 50 and 100 stars.

I became much clearer about what is-kit is not.

It is not trying to replace every schema library.
It is not trying to turn every runtime value into a schema-first workflow.
And it is not trying to hide normal TypeScript control flow.

The core question is still very small

"Can this unknown value safely enter this branch?"

Sometimes a schema library is the right answer.

For example, if I need:

Rich validation errors
Transformations
Form validation
A contract shared across systems

I may want Zod, Valibot, ArkType, or something else.

But sometimes I already have normal TypeScript code and I only need a reusable narrowing function.

That is where I want is-kit to be useful.

if (isUser(value)) {
  value.id;
}

if (isHttpClientError(error)) {
  // Handle HTTP client errors
}

items.filter(isString);

result.catch(isHttpClientError);

const isMaybeNumber = nullish(isNumber);

Small runtime decisions.
Normal functions.
Normal TypeScript.

🐱 What 100 Stars Means to Me

100 stars is still small compared with the largest TypeScript OSS projects.

No problem.

What matters to me is that the project is becoming more real in ways that have nothing to do with the star counter.

Since the 50-star milestone:

New APIs were added
Existing APIs became stricter
Runtime edge cases were fixed
Package compatibility testing improved
I started using is-kit naturally in other OSS
External usage produced feedback I could not generate alone
An unknown-based refinement even helped expose an inference edge case in Effect

That last part is probably my favorite.

Because the goal was never to build a library that only looks nice in its own README!!!

The goal is to make reusable runtime narrowing work naturally inside real TypeScript code.

And now I am starting to see that happen outside my own repository too.

Thank you to everyone who starred the project, tried it, reported something, asked a question, opened an issue, or simply read the code. 🙏

There is still a lot I want to improve.

But 100 feels pretty nice. 😸⭐

If small composable type guards fit your TypeScript style, give it a try!

nyaomaru / is-kit

Build small guards. Compose them. A lightweight, zero-dependency toolkit for building reusable TypeScript type guards that compose, refine, and preserve natural narrowing. Runtime-safe 🛡️, composable 🧩, and ergonomic ✨.

is-kit

Build small guards. Compose them.

is-kit is a lightweight, zero-dependency toolkit for building reusable TypeScript type guards.

is-kit is not just a collection of isX helpers. Its main focus is composing small runtime checks into reusable guards while preserving useful TypeScript narrowing.

It helps you write small isFoo functions, compose them into richer runtime checks, refine properties on values you already know about, and keep TypeScript narrowing natural inside regular control flow. Use it at runtime boundaries when needed, without requiring a schema-first workflow.

Runtime-safe 🛡️, composable 🧩, and ergonomic ✨ without asking you to adopt a heavy schema workflow.

Build and reuse typed guards
Compose guards with and, or, not, oneOf
Use refineKey to narrow a child property while preserving its parent type
Validate object shapes and collections when that is useful
Parse or assert unknown values without a large schema framework

Best…

Thank you for reading! 🤲

How Do You Validate `unknown` in TypeScript Without a Schema Library? 🛡️

nyaomaru — Wed, 14 Oct 2026 15:35:25 +0000

Hoi hoi! 👋

I'm @nyaomaru, a frontend engineer who is obsessed with gamba. 😸🦐

Recently, I was thinking about a very common TypeScript problem.

Suppose some value comes from:

an API response
JSON.parse
local storage
a message payload
third-party code

What type should it have before we actually verify it?

Probably this

declare const input: unknown;

That part is easy.

The interesting question is what comes next.

How do we safely turn that unknown into something useful?

And do we really need a full schema library every time?

Let's look at it! 👀

Validate unknown in TypeScript Without a Schema Library | is-kit

Validate unknown TypeScript values with small composable type guards and safeParse, without adopting a schema-first validation workflow.

is-kit.dev

🧱 `unknown` Is Doing Its Job

Suppose we have

declare const input: unknown;

input.name;
// Error

TypeScript refuses to let us access name.

At first this can feel annoying.

But TypeScript is actually telling us something important

We have a value.

We do not know what it is yet.

That is exactly what an untrusted boundary value should mean.

An HTTP response does not become a User just because our application expects a User.

Neither does parsed JSON.

So I like to think of unknown like this

unknown is not missing type information.

It is an honest description of a value we have not verified yet.

The problem is not unknown.

The problem is how we establish trust.

😈 The Easy Escape: `as User`

There is a very short way out.

type User = {
  id: string;
  name: string;
};

declare const input: unknown;

const user = input as User;

user.name.toUpperCase();

TypeScript is happy.

Nice! 🎉

Except, nothing was actually checked.

This still works

const input = {
  id: "user-1",
  name: 123,
} as unknown;

const user = input as User;

user.name.toUpperCase();
// 💥 Runtime error

as User changes what the compiler believes.

It does not inspect the runtime value.
It does not add missing properties.
It does not turn 123 into a string.

So if runtime trust matters, a type assertion is not validation.

We need an actual runtime check.

🛡️ A Type Guard Connects Runtime and TypeScript

Let's start small.

With is-kit, we can build a guard like this

import { isString, oneOfValues, struct } from "is-kit";

const isUser = struct({
  id: isString,
  name: isString,
  role: oneOfValues("admin", "member"),
});

Now we can pass unknown directly to it

declare const input: unknown;

if (isUser(input)) {
  input.name.toUpperCase();

  // input:
  // Readonly<{
  //   id: string;
  //   name: string;
  //   role: "admin" | "member";
  // }>
}

This is the part I like.

The same check does two jobs

runtime
→ does this value actually match?

TypeScript
→ what is this value after the check succeeds?

There is no separate schema definition and no type assertion.

We just compose small runtime predicates.

🧩 The Shape Can Grow Naturally

Real payloads are usually a little more complicated.

Maybe a user has:

an optional profile
a nullable bio
a list of tags

We can keep composing guards

import {
  arrayOf,
  isString,
  nullable,
  oneOfValues,
  optionalKey,
  struct,
} from "is-kit";

const isProfile = struct({
  displayName: isString,
  bio: optionalKey(nullable(isString)),
});

const isUser = struct({
  id: isString,
  role: oneOfValues("admin", "member"),
  profile: optionalKey(isProfile),
  tags: arrayOf(isString),
});

Then

isUser({
  id: "user-1",
  role: "member",
  tags: ["typescript", "guards"],
});
// true

But

isUser({
  id: "user-1",
  role: "owner",
  tags: ["typescript"],
});
// false

Each piece is still just a guard.

That means we can test it independently, reuse it somewhere else, or compose it into something larger.

There is also an important difference here

optionalKey(...)

means

the property may be absent

while

nullable(...)

means

the value may be null

Those are different runtime contracts, so I prefer keeping them separate.

📦 What Does `safeParse` Add?

A direct guard is often enough.

if (isUser(input)) {
  renderUser(input);
}

But sometimes I want the validation result itself to move through the program.

For example

const result = safeParse(isUser, input);

if (!result.valid) {
  return { status: 400 as const };
}

return {
  status: 200 as const,
  user: result.value,
};

safeParse gives us a small tagged result

{
  valid: (true, value);
}

{
  valid: false;
}

So TypeScript can narrow it with a normal branch.

The important part is what safeParse does not do.

It does not:

clone the value
coerce the value
generate a new object
transform invalid data into valid data

On success, it returns the same value after the guard has accepted it.

So I think of the difference like this

guard
→ boolean + narrowing

safeParse
→ tagged result + validated value

Same runtime rule.

Different control-flow shape.

🧃 What About JSON?

This is one of the most common boundaries.

const value = JSON.parse(body);

The awkward part is that JSON.parse returns any.

So now the unsafe value can spread through the program before we validate it.

Instead, we can keep the boundary small

import { safeJsonParse } from "is-kit";

declare const body: string;

const result = safeJsonParse(body, isUser);

if (!result.valid) {
  return { status: 400 as const };
}

renderUser(result.value);

Conceptually, the flow is

JSON text
   ↓
decode
   ↓
unknown
   ↓
guard
   ↓
validated value

Invalid JSON and guard failures both produce

{
  valid: false;
}

And again, nothing is coerced just to make the value pass.

I like this because the unsafe part stays right at the decode boundary.

🚪 Should Extra Keys Be Allowed?

There is another small design choice that appears at object boundaries.

Suppose we expect

{
  username: string;
  password: string;
}

Should this also be accepted?

{
  username: "Neko",
  password: "secret",
  admin: true,
}

With struct, extra keys are allowed by default.

That is often useful for API responses because a server may add a new field without breaking an older client.

But sometimes we really want a closed object shape.

Then we can use

const isCredentials = struct(
  {
    username: isString,
    password: isString,
  },
  { exact: true },
);

Now

isCredentials({
  username: "Neko",
  password: "secret",
});
// true

while

isCredentials({
  username: "Neko",
  password: "secret",
  admin: true,
});
// false

The important part is not that one mode is always better.

It is that the boundary should express the contract we actually want.

🤔 So Do We Still Need Schema Libraries?

Yes.

Sometimes absolutely.

A type guard toolkit and a schema library overlap a little, but they are not trying to solve exactly the same problem.

For example, a schema library is probably the better choice when we need:

structured validation errors with field paths
multiple validation issues at once
coercion
default values
transformations
schema-generated types or external artifacts
deep integration with a form or API framework

Those are larger validation workflows.

is-kit asks a narrower question

Does this value satisfy this runtime predicate?

If yes, what can TypeScript safely narrow it to?

That narrower model is sometimes exactly what I want.

For example

Approach	Good fit
Inline `typeof` checks	One small local condition
Type guards	Reusable boolean validation and narrowing
Schema library	Rich validation, transformation, and schema workflows

So I don't think the question is

Type guards or schema libraries—which one wins?

The more useful question is

What is the smallest validation model that solves this boundary?

🎯 The Important Part

I started with a simple value

declare const input: unknown;

The tempting shortcut was

const user = input as User;

But that only changes TypeScript's belief.

It does not establish runtime trust.

A runtime guard gives us a much more useful flow

unknown
   ↓
runtime check
   ↓
narrowed value

And when we want a result-oriented API

unknown
   ↓
guard
   ↓
safeParse
   ↓
{ valid: true, value }
or
{ valid: false }

No hidden conversion.

No assertion pretending the check already happened.

Just small runtime rules that TypeScript can understand too. 😸

If you want to see the full guide, including JSON boundaries, exact objects, and custom domain refinements:

Validate unknown in TypeScript Without a Schema Library | is-kit

Validate unknown TypeScript values with small composable type guards and safeParse, without adopting a schema-first validation workflow.

is-kit.dev

And if you want to explore is-kit itself:

nyaomaru / is-kit

Build small guards. Compose them. A lightweight, zero-dependency toolkit for building reusable TypeScript type guards that compose, refine, and preserve natural narrowing. Runtime-safe 🛡️, composable 🧩, and ergonomic ✨.

is-kit

Build small guards. Compose them.

is-kit is a lightweight, zero-dependency toolkit for building reusable TypeScript type guards.

is-kit is not just a collection of isX helpers. Its main focus is composing small runtime checks into reusable guards while preserving useful TypeScript narrowing.

Runtime-safe 🛡️, composable 🧩, and ergonomic ✨ without asking you to adopt a heavy schema workflow.

Build and reuse typed guards
Compose guards with and, or, not, oneOf
Use refineKey to narrow a child property while preserving its parent type
Validate object shapes and collections when that is useful
Parse or assert unknown values without a large schema framework

Best…

If it looks useful, a ⭐ on GitHub is always very welcome!

Thanks for reading! 🙌

How Do We Extract the “Why” from a PR into a CHANGELOG with Jev? 🤔

nyaomaru — Sat, 10 Oct 2026 15:49:58 +0000

Hoi hoi! 👋

I'm @nyaomaru, a frontend engineer currently building an AI-assisted CHANGELOG generator and experimenting with Jev. 😸

Recently, I have been thinking about one problem.

How can we extract this

## Why

The previous implementation could leave stale release data after an update.

from a pull request and put it into a CHANGELOG?

### Fixed

- Fix cache invalidation

  Why: The previous implementation could leave stale release data after an update.

Getting the WHAT is relatively easy.
Getting the WHY is much harder.
And I didn't want AI to simply invent a nice-looking reason.

Let's look at how changelog-bot currently approaches this! 👀

nyaomaru / changelog-bot

Automatic create changelog with AI. 🤖 It provides CLI and github actions. 🚀 https://www.npmjs.com/package/@nyaomaru/changelog-bot

Releases should feel exciting, not tedious.

@nyaomaru/changelog-bot 🤖 turns your Git history and release notes into a polished changelog entry (and optional PR) in a single run. Drop it into CI, run it locally, or hand it to your release captain—either way, you ship with a crisp changelog and zero copy-paste fatigue.

Why changelog-bot?

Automated storytelling: Combines commit history, PR titles, and release notes to produce human-ready changelog sections.
LLM superpowers (optional): Connect OpenAI or Anthropic for tone-aware summaries or skip API keys entirely and rely on a robust heuristic fallback.
PR-ready output: Can open a pull request with updated changelog, compare links, and release notes already wired up.
Safe defaults: Detects duplicate versions, keeps compare links current, and won’t fail a release if AI is down.
CI-native: Works as a GitHub Action, reusable workflow, or plain CLI—no fragile scripting required.

Important

This project is currently in its early stages…

https://github.com/nyaomaru/changelog-bot/blob/main/v1-design.md

📝 WHAT Is Easy. WHY Is Hard.

Suppose a PR contains.

## Description

Extract shared runtime configuration into ProviderBase.

Update OpenAI, Anthropic, and Gemini adapters to use the shared implementation.

This reduces duplicated setup logic and makes adding new providers easier.

The first two sentences mainly describe WHAT and HOW.

But this one is different

This reduces duplicated setup logic and makes adding new providers easier.

That is much closer to WHY.

We could simply give the whole PR to an LLM and ask

Why was this change made?

But then the model may summarize, paraphrase, or infer a reason that was never explicitly written.

For a CHANGELOG, I wanted something stricter.

Maybe WHY extraction is not a generation problem.

Maybe it is a selection problem.

✂️ First, Find Possible WHY Candidates

Before calling a model, changelog-bot preprocesses the PR description.

It looks for signals such as

const STRONG_CANONICAL_SECTION_NAMES = new Set([
  "why",
  "reason",
  "because",
  "motivation",
  "context",
  "background",
  "problem",
  "rationale",
]);

const RATIONALE_MARKER_RE =
  /\b(why|because|so that|in order to|reason|rationale|motivation|to avoid|to prevent|context|problem)\b|,\s*so\b/i;

It also removes template noise such as checkboxes, placeholders, and irrelevant fields.

Then it builds small candidate snippets

const candidates = buildWhyCandidateSnippets(
  extracted.sections,
  body,
  options.maxCharsPerPr,
  !extracted.hasTargetSection,
);

So instead of sending a large PR body, we might get

[
  "Extract shared runtime configuration into ProviderBase.",
  "This reduces duplicated setup logic and makes adding new providers easier.",
];

Now the problem is much smaller.

Which candidate is actually the WHY?

🧠 Asking Jev Two Questions

This is where I started experimenting with Jev.

I don't ask Jev to write a WHY sentence.

Instead, each candidate is evaluated with two questions.

First

question: "Does the target candidate explicitly state why this changelog change was made?";

Basically

Is this actually a reason?

But that alone is not enough.

Imagine

We changed the cache invalidation logic.

The README was updated because the previous explanation was confusing.

The second sentence definitely contains a reason.

But it explains the README change, not the cache invalidation change.

So we also ask

question: "Does the target candidate state a reason that applies to the identified changelog change?";

Now each candidate has two signals

{
  probability: explicitWhyProbability,
  relevanceProbability: changeRelevanceProbability,
}

So the real question becomes

Is this a reason?

AND

Is it the reason for this change?

🎯 Selecting the Candidate

changelog-bot compares the candidate probabilities

const bestCandidate = candidateProbabilities.reduce((best, candidate) =>
  combinedWhyCandidateProbability(candidate) >
  combinedWhyCandidateProbability(best)
    ? candidate
    : best,
);

Then both minimum thresholds must pass

const accepted =
  selectedCandidate !== undefined &&
  bestCandidate.probability >= JEV_MIN_EXPLICIT_WHY_PROBABILITY &&
  bestCandidate.relevanceProbability >= JEV_MIN_CHANGE_RELEVANCE_PROBABILITY;

If the candidate does not pass

if (!accepted) continue;

No WHY is added.

And I think that is important.

Sometimes the correct answer is

There is no reliable WHY in this PR.

That is better than inventing one.

🔒 Keep the Original PR Text

This is probably my favourite part.

When a candidate is accepted

items.push({
  prNumber: item.prNumber,
  why: selectedCandidate,
  confidence: mappedConfidence,
});

Notice

why: selectedCandidate;

The final WHY is the original PR text.

Not newly generated prose.

So the pipeline becomes

PR description
      ↓
candidate extraction
      ↓
Jev evaluates candidates
      ↓
select candidate
      ↓
original source text
      ↓
CHANGELOG

Jev decides.

The PR author still provides the sentence. 😸

🧱 Where Does WHY Fit in the v1 Pipeline?

While working on WHY extraction, I have also been redesigning the changelog-bot pipeline for v1.

The main idea is deterministic-first.

A complete CHANGELOG should exist even when AI is disabled or fails.

So AI should enrich the result, not own the result.

The target v1 pipeline looks roughly like this

source changes
      ↓
ReleaseChange[]
      ↓
deterministic classification
      ↓
complete ReleaseDraft
      ↓
optional editorial enrichment
      +
optional WHY enrichment
      ↓
ReleaseResult
      ↓
deterministic renderer
      ↓
CHANGELOG

WHY extraction is therefore an independent optional enrichment stage.

Conceptually

ReleaseDraft / ReleaseChange[]
      ↓
find eligible WHY targets
      ↓
collect PR rationale candidates
      ↓
LLM or Jev
      ↓
trust / confidence validation
      ↓
attach structured WHY notes
      ↓
ReleaseResult

One important change here is that the WHY engine does not need to control the final Markdown.

Today, some of the pipeline still works by finding targets from generated Markdown and inserting WHY text afterward.

For v1, I want to remove that boundary.

Instead

{
  prNumber,
  why: selectedCandidate,
  confidence,
}

becomes structured release data first.

Then one deterministic renderer decides how it appears

- Fix cache invalidation
  - Why: The previous implementation could leave stale release data after an update.

So the responsibility becomes clearer

WHY engine
→ find the evidence

Renderer
→ format the evidence

This is also part of a larger rule I am using for the v1 migration

Deterministic code owns the CHANGELOG structure. AI only enriches it.

Phases 1–4 of this migration are already implemented, and the structured rendering and enrichment boundary is part of the next phase.

You can see the full v1 design here 👇

🧪 But What Threshold Should We Use?

Of course, once we have probabilities, another question appears.

0.50?
0.60?
0.80?

I didn't want to pick one only because it felt reasonable.

So I created an evaluation harness with an initial 14-case corpus.

For example

{
  candidates: [
    "Separate changelog execution into input-resolution and output-finalization phases.",
    "This simplifies the main orchestration flow and runs independent GitHub lookups concurrently.",
  ],
  expectedSelectedCandidateIndex: 1,
}

We also need negative examples

{
  candidates: [
    "Extract shared provider runtime configuration into ProviderBase.",
    "Refactor OpenAI, Anthropic, and Gemini adapters to inherit it.",
  ],
  expectedSelectedCandidateIndex: null,
}

There is plenty of implementation information.

But no strong explicit WHY.

So null is the correct result.

🤝 Then John Joined the Project

While I was working on this experiment, @johnnylemonny joined the project as a contributor. 🎉

johnnylemonny (John) · GitHub

Full‑stack developer creating fast, modern, and refined applications. I focus on simplicity, performance, and real value for users. Open to opportunities. - johnnylemonny

github.com

John proposed expanding the small benchmark into roughly 50 cases covering

Explicit Rationale
Implementation-Only
Template & Noise
Multilingual PRs

I liked the idea, but I wanted one rule to stay clear

Ground truth should be independent of the current Jev threshold.

So the benchmark first defines whether a candidate is actually valid.

Then we evaluate different thresholds afterward.

John implemented the expanded corpus in PR #212. 🙌

The benchmark grew from 14 cases to 50, including tricky negative cases.

He also added finer threshold sweeps

[0.4, 0.45, 0.5, 0.55, 0.6, 0.65, 0.7, 0.75, 0.8, 0.85, 0.9];

Now we can compare precision, recall, and F1 instead of saying

0.8 feels safe! 👍

Let's measure it instead. 😸

🧩 The Current Pipeline

Today, WHY extraction roughly looks like this

Pull Request
     ↓
Normalize PR body
     ↓
Extract WHY candidates
     ↓
Remove noise
     ↓
Local trust check
     ↓
Jev:
  explicit rationale?
  relevant to this change?
     ↓
Apply threshold
     ↓
Candidate or none
     ↓
Original PR text
     ↓
CHANGELOG

There are quite a few steps for one small Why: line. 😂

But that is what made this problem interesting.

🎯 What I Learned

When I started this feature, I thought the main question was

How can AI write a good reason?

Now I think the more interesting question is

How can we find evidence that the reason already exists?

So my current approach is simple

Use deterministic code to find evidence.

Use Jev to evaluate the evidence.

Keep the original evidence as the output.

And thanks to John's contributions, we now have a much better way to test whether that approach actually works.

Open source is fun when someone looks at your experiment and says:

What if we test this properly?

and then builds it with you. 🙌

changelog-bot is still evolving, and Jev support is still experimental.

I'm curious to see where this approach goes next!

https://github.com/nyaomaru/changelog-bot

Thanks for reading!

See you in the next article! 👋😸

Migrating a Real TypeScript OSS Library from tsup to tsdown 🔧

nyaomaru — Wed, 07 Oct 2026 15:59:28 +0000

The config migration was small. Preserving the package contract was the interesting part.

Hoi hoi! 👋

I'm @nyaomaru, a frontend engineer who enjoyed looking for fungus this season. 😸🍄

Recently, I migrated its build setup from tsup to tsdown.

At first, I expected this to be a very small task.

Just remove tsup.
Just install tsdown.
Just change the config.
Run the build.
Done! 🎉

And honestly...

The config migration was small.

But there was one interesting problem.

The first tsdown build succeeded while silently changing files that were already part of the package's public contract.

So this article isn't really an introduction to tsdown.

Instead, I want to show what happened when I migrated a real published TypeScript library from tsup to tsdown, what actually changed, and how I verified that consumers would still receive the same package.

Let's take a look! 👀

🤔 Why Migrate a Package That Already Builds Correctly?

is-kit is a zero-dependency TypeScript library for runtime type guards.

Its build setup was already pretty boring.

And boring build systems are good. 😸

The package had:

one entry point
ESM and CJS outputs
bundled declaration files
explicit package.json exports
a declaration banner
a packed-package smoke test

Before the migration, it used

Environment	Value
Package	`is-kit@1.14.2`
Bundler	`tsup@8.5.1`
Entry	`src/index.ts`
Output	`ESM + CJS + bundled declarations`
Target	`esnext`

I wasn't trying to solve a broken build.

The motivation was mostly maintenance.

tsdown is built around Rolldown, has an active ecosystem, and is explicitly designed as a migration path for projects currently using tsup.

So the question wasn't

Can tsdown build this library?

It was

Can I move the build setup to tsdown without changing what existing consumers receive?

That's a much more useful question for a published package.

📦 The Package Contract I Needed to Preserve

For an application, changing an output filename may not matter much.

For a library, it can be a breaking change.

is-kit already exposes files through explicit package exports.

The important paths were effectively

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.js"
    }
  }
}

So I wanted the migration to preserve

dist/index.mjs
dist/index.js
dist/index.d.ts

along with the existing ESM/CJS runtime behavior, declaration compatibility, export set, and declaration banner.

In other words

The source code was not the contract here. The packed npm package was.

That distinction became important very quickly.

🛠️ The Migration Looked Almost Trivial

I replaced tsup with tsdown and replaced

tsup.config.ts

with

tsdown.config.mts

I intentionally used .mts.

The package itself is not "type": "module", and using an ESM-specific config extension avoids having Node reinterpret the config file and emit related warnings.

Most of the important options mapped almost directly.

import { defineConfig } from "tsdown";

export default defineConfig({
  entry: ["src/index.ts"],
  format: ["esm", "cjs"],
  dts: true,
  clean: true,
  outDir: "dist",
  target: "esnext",
  banner: {
    dts: dtsBanner,
  },
});

The declaration banner also stayed dts-only with banner: { dts: dtsBanner }.

So far, everything looked easy.

Then I ran the build.

It passed.

And the package contract was wrong. 🙀

💥 The First Build Succeeded and Changed My Filenames

This was the interesting part.

Before the migration, the important generated files looked like this:

Build	Main generated files
`tsup`	`index.mjs`, `index.js`, `index.d.ts`
default `tsdown` migration	`index.mjs`, `index.cjs`, `index.d.mts`, `index.d.cts`

The tsdown build completed successfully with exit code 0.

But my existing package.json still expected

require → ./dist/index.js
types   → ./dist/index.d.ts

Those files no longer matched the generated output.

If I had stopped at

pnpm build

and published the package.

CJS consumers and TypeScript resolution could have been broken.

This was the most important lesson from the migration

Build success ≠ package contract preserved.

A bundler only knows whether it successfully produced its output.

It doesn't automatically mean that output still matches every promise your already-published package makes.

🔧 Fixing the Public Contract with `outExtensions`

The tsdown migration guide explicitly calls out the rename from outExtension to outExtensions.

For is-kit, I used it to preserve the existing filenames

outExtensions: ({ format }) => ({
  dts: format === 'cjs' ? '.d.ts' : '.d.mts',
  js: format === 'cjs' ? '.js' : '.mjs',
}),

Now the relevant output became

dist/index.mjs
dist/index.js
dist/index.d.mts
dist/index.d.ts

and the existing exports continued to resolve correctly.

I don't really consider the original output behavior a tsdown bug.

tsdown chooses extensions based on the package type and output format to avoid ambiguous module interpretation.

That's reasonable.

But for an existing package, reasonable new defaults are still changes.

If consumers already depend on your filenames, those filenames are part of your compatibility surface.

🧪 Verifying the Published Package with a Smoke Test

This is where an existing packed-package smoke test in is-kit helped a lot.

I already had a pnpm test:package command that builds the package, runs npm pack, installs the generated tarball into a temporary project, and verifies it from a real consumer's perspective.

Instead of testing this

src/index.ts

it tests this

is-kit-1.14.2.tgz
        ↓
temporary consumer
        ↓
npm install

A library can work perfectly inside its own repository while still publishing a broken package, so this smoke test exercises the artifact that users would actually install.

After the migration, I expanded the test to verify more of the package contract 👇

Contract	Result
`exports["."].import` → `./dist/index.mjs`	✅ pass
`exports["."].require` → `./dist/index.js`	✅ pass
`exports["."].types` → `./dist/index.d.ts`	✅ pass
Runtime dependencies	✅ 0
ESM exports	✅ same 83 exports
CJS exports	✅ same 83 exports
Declaration banner	✅ preserved
ESM runtime import	✅ pass
CJS runtime require	✅ pass
Packed TypeScript consumer	✅ pass

I also installed the packed package into temporary consumer projects using TypeScript v5.7 through v7.0.

All of them successfully resolved and consumed the generated declarations.

This isn't testing whether each TypeScript version can generate declarations through tsdown. It's testing the artifact my users actually install.

So if a future build change accidentally alters an extension, export path, declaration file, or runtime behavior, the smoke test should catch it before publishing.

For a library migration like this, that is much more meaningful than simply asserting "build exited successfully".

📏 The Output Actually Got Bigger

I was also curious about artifact size.

This produced a result I didn't expect.

Metric	`tsup`	`tsdown`	Difference
JS + dts total	116,503 B	144,007 B	+23.6%
ESM JavaScript	15,787 B	29,410 B	+86.3%
CJS JavaScript	19,318 B	31,155 B	+61.3%
dts, one format	40,699 B	41,721 B	+2.5%
`npm pack` tarball	37,226 B	42,366 B	+13.8%

In this configuration, the tsdown output retained more comments and region markers than the previous tsup output.

So the raw JavaScript became noticeably larger.

Compression reduced the difference in the actual npm tarball, but didn't remove it.

For is-kit, this isn't particularly concerning.

It is a small zero-dependency utility library, and we're talking about a few kilobytes in the final tarball.

But it was still a useful reminder

A faster or newer bundler does not automatically mean a smaller artifact.

If package size is a strict constraint for your library, I would compare the generated files and decide on your minification strategy before migrating.

⏱️ What About Build Performance?

I also measured wall-clock build time.

The old tsup build

1.50 s

The new tsdown build across three runs

1.22 s
1.17 s
1.18 s

Looking only at those numbers, it would be very tempting to say

tsdown made the build faster! 🚀

But I don't think this benchmark supports that conclusion.

I only have one measured tsup run in this comparison.

Also, this is a tiny single-entry library where declaration generation represents a large part of the build.

The bundlers' own timing output was roughly

tsup
JavaScript: ~22 ms
dts:        ~707 ms

tsdown
complete:   ~717–755 ms

The wall-clock result was better, but with only one tsup sample and declaration generation dominating this tiny library, I don't think this is enough evidence to claim a meaningful performance improvement.

But no, I'm not migrating because I saved around 300 ms.

🐱 Was the Migration Actually Small?

For is-kit, yes.

There were no source-code changes.

The migration was basically limited to

dependency
config
task documentation
package smoke assertions

The important options were almost one-to-one.

But I think it's important to explain why it stayed small.

is-kit has

one entry
zero runtime dependencies
no bundler plugins
no CSS pipeline
no complicated code splitting

and, most importantly, it already had a way to test the packed package as a consumer.

The migration becomes more interesting if your package relies on custom plugins, unusual entries, CSS processing, exact source maps, generated exports, strict byte-size limits, or older Node build environments.

There is also a build-environment requirement worth checking.

For the version tested here

tsdown 0.23.0
Rolldown 1.2.8

the relevant Node engine requirement is

^22.18.0 || ^24.11.0 || >=26.0.0

My CI uses

Node 22.22.0

so that was fine.

But if contributors still build your library with Node v20 or an older Node v22 version, this is something you need to solve before migrating.

That doesn't necessarily mean your library consumers must use Node v22.

It's a build-tool requirement.

Still, contributor and CI environments are part of the migration cost too. 😿

🎯 So, Was Moving from tsup to tsdown Worth It?

For is-kit, I think yes.

But not because of performance.

The migration preserved the package contract across ESM, CJS, declarations, exports, and the packed-package consumer tests.

The configuration change was small and reviewable.

My existing Node environment satisfies the new build requirement.

And the build setup is now aligned with the actively evolving Rolldown ecosystem.

The cost was also real

artifact size increased
Node build requirements increased
output extensions needed explicit configuration

So I wouldn't describe this as

Everyone using tsup should migrate immediately because tsdown is faster!

That's not what this experiment showed.

For me, the better conclusion is

If your project already meets the Node requirements and you want to move your build setup toward the Rolldown ecosystem, migrating a small library from tsup to tsdown can be a very reasonable change.

But verify the package you publish.

Not only the source.
Not only the config.
And definitely not only the green build message. 😸

Because the most interesting bug in this migration happened when the build said everything was fine.

If you'd like to see the package from this article in a real project, is-kit is open source.

It's a lightweight, zero-dependency TypeScript type guard library focused on runtime validation and safe narrowing.

If it looks useful for your project, I'd be happy if you gave it a try and a ⭐ on GitHub is always appreciated.

nyaomaru / is-kit

Build small guards. Compose them. A lightweight, zero-dependency toolkit for building reusable TypeScript type guards that compose, refine, and preserve natural narrowing. Runtime-safe 🛡️, composable 🧩, and ergonomic ✨.

is-kit

Build small guards. Compose them.

is-kit is a lightweight, zero-dependency toolkit for building reusable TypeScript type guards.

is-kit is not just a collection of isX helpers. Its main focus is composing small runtime checks into reusable guards while preserving useful TypeScript narrowing.

Runtime-safe 🛡️, composable 🧩, and ergonomic ✨ without asking you to adopt a heavy schema workflow.

Build and reuse typed guards
Compose guards with and, or, not, oneOf
Use refineKey to narrow a child property while preserving its parent type
Validate object shapes and collections when that is useful
Parse or assert unknown values without a large schema framework

Best…

Issues and PRs are welcome too. 😸

TypeScript Compiler API: Preserving Child Node Narrowing in Reusable Type Guards 🔧

nyaomaru — Wed, 30 Sep 2026 14:34:27 +0000

Hoi hoi! 👋

I'm @nyaomaru, a frontend engineer exploring new possibilities with Jev 😸 (I'm also curious about "Decisions API" from OpenAI)

Recently, I was looking into the TypeScript Compiler API and asking a pretty specific question

Can reusable type guards preserve not only the AST node type, but also a narrowed child property?

At first, I thought this might be a Compiler API-specific problem.

Then I reproduced the same pattern with plain TypeScript objects.

That changed the way I looked at it.

The interesting problem wasn't really the AST.

It was property refinement.

Let's look at it! 👀

🌲 A Very Common Compiler API Pattern

Suppose we have a broad ts.Node.

import * as ts from "typescript";

declare const node: ts.Node;

We want to know two things:

Is this a CallExpression?
Is its expression an Identifier?

Inline, this is easy.

if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
  // node: ts.CallExpression
  // node.expression: ts.Identifier
  node.expression.text;
}

TypeScript understands the control flow perfectly.

Nothing special is needed.

And honestly, if this check appears only once, I would probably leave it exactly like this.

🤔 What If We Want to Reuse That Shape?

Now suppose the same AST shape appears in several places:

a visitor
filter
find
another transformation
another lint rule

Then giving the check a name starts to make sense.

Since TypeScript v5.5, simple functions can often infer a type predicate automatically.

But this compound parent-plus-child check is different.

const isCallWithIdentifierExpression = (node: ts.Node) =>
  ts.isCallExpression(node) && ts.isIdentifier(node.expression);
// inferred:
// (node: ts.Node) => boolean

So if we want the extracted predicate to preserve both facts, we have to describe the refined type explicitly.

const isCallWithIdentifierExpression = (
  node: ts.Node,
): node is ts.CallExpression & {
  expression: ts.Identifier;
} => ts.isCallExpression(node) && ts.isIdentifier(node.expression);

This works. Then we can reuse it

declare const nodes: readonly ts.Node[];

const calls = nodes.filter(isCallWithIdentifierExpression);
// calls:
// Array<
//   ts.CallExpression & {
//     expression: ts.Identifier;
//   }
// >

So what's the problem?

There isn't really a runtime problem.

The annoying part is that we had to manually describe this 👇

ts.CallExpression & {
  expression: ts.Identifier;
}

But we already performed those exact runtime checks.

It would be nice if we could compose the checks and let the type follow them. 😸

🧩 Refining the Parent and Child Together

This is where I ended up using refineKey.

With is-kit

import * as ts from "typescript";
import { and, refineKey } from "is-kit";

const isCallWithIdentifierExpression = and(
  ts.isCallExpression,
  refineKey("expression", ts.isIdentifier),
);

That's it.

Now

declare const node: ts.Node;

if (isCallWithIdentifierExpression(node)) {
  // node:
  // ts.CallExpression & {
  //   expression: ts.Identifier;
  // }
  node.expression.text;
}

The interesting part is the relationship between the two checks.

ts.isCallExpression;

narrows the parent.

Then

refineKey("expression", ts.isIdentifier);

within the composed narrowing chain, checks one property on the parent already narrowed by ts.isCallExpression and preserves the checked child type.

So the idea is

Check the child once at runtime, then carry that same fact back to the parent type.

😸 This Turned Out Not to Be an AST Problem

This was the part that surprised me during the research.

I originally thought I was investigating a TypeScript Compiler API gap.

But the same shape appears with ordinary objects too.

Conceptually, the pattern is just

Parent
  ↓
check property
  ↓
Parent & {
  property: RefinedChild
}

The Compiler API is simply a really good stress test for it because AST code contains this pattern everywhere.

For example

CallExpression
  → expression
  → Identifier

VariableDeclaration
  → initializer?
  → CallExpression

CallExpression
  → arguments[0]
  → StringLiteral

So I don't think of refineKey as a Compiler API helper.

The Compiler API is just an advanced example of a more generic composition problem.

🔗 Compiler API Guards Already Compose Well

Another thing I wanted to avoid was wrapping TypeScript's existing predicates unnecessarily.

The Compiler API already provides excellent guards

ts.isStringLiteral;
ts.isIdentifier;
ts.isCallExpression;
ts.isClassDeclaration;

We should reuse them.

For example

import * as ts from "typescript";
import { or } from "is-kit";

const isStringLike = or(ts.isStringLiteral,　ts.isNoSubstitutionTemplateLiteral);

declare const nodes: readonly ts.Node[];

const strings = nodes.filter(isStringLike);
// strings:
// (
//   | ts.StringLiteral
//   | ts.NoSubstitutionTemplateLiteral
// )[]

There is no reason for is-kit to create its own

isTsStringLiteral();
isTsIdentifier();
isTsCallExpression();

That would just duplicate the Compiler API.

The useful part is composition.

♻️ Reuse the Same Guard in `find` and Visitors

This becomes more useful when a refined shape appears in several contexts.

For example

import * as ts from "typescript";
import { and, refineKey } from "is-kit";

const isIdentifierNamedJsxAttribute = and(
  ts.isJsxAttribute,
  refineKey("name", ts.isIdentifier),
);

We can use it with find:

declare const attributes: readonly ts.JsxAttributeLike[];

const attribute = attributes.find(isIdentifierNamedJsxAttribute);
// attribute:
// (
//   ts.JsxAttribute & {
//     name: ts.Identifier;
//   }
// ) | undefined

The same guard works in a visitor

function visit(node: ts.Node): void {
  if (isIdentifierNamedJsxAttribute(node)) {
    // node:
    // ts.JsxAttribute & {
    //   name: ts.Identifier;
    // }
    node.name.text;
  }
  ts.forEachChild(node, visit);
}

That's the point where extracting the guard starts earning its keep.

The runtime rule and the TypeScript narrowing travel together.

🫥 Optional Children Are a Different Contract

AST nodes contain lots of optional properties.

For example, a VariableDeclaration may or may not have an initializer.

declaration.initializer;

So this is slightly different from refining a required property.

We don't just want

Refine initializer.

We want

Require initializer to exist, then refine it.

For that case, is-kit has refineDefinedKey.

import * as ts from "typescript";
import { refineDefinedKey } from "is-kit";

const hasCallInitializer = refineDefinedKey("initializer", ts.isCallExpression);

Now

declare const declaration: ts.VariableDeclaration;

if (hasCallInitializer(declaration)) {
  // declaration.initializer: ts.CallExpression
  declaration.initializer.expression;
}

Inside the branch, initializer is both:

present
a ts.CallExpression

A missing initializer returns false.

An explicitly undefined initializer also returns false.

I like keeping this separate from refineKey because absence is runtime behavior, not just a TypeScript annotation.

📦 Arrays Have the Same Problem

AST arrays introduce another small issue.

Suppose we want a call whose first argument is a string literal.

This

node.arguments[0];

looks simple, but at runtime the array can be empty.

So we want to prove two things:

index 0 exists
the value is a StringLiteral

We can compose that too

import * as ts from "typescript";
import { and, refineIndex, refineKey } from "is-kit";

const isCallWithStringFirstArgument = and(
  ts.isCallExpression,
  refineKey("arguments", refineIndex(0, ts.isStringLiteral)),
);

Then

declare const node: ts.Node;

if (isCallWithStringFirstArgument(node)) {
  // node: ts.CallExpression
  // node.arguments[0]: ts.StringLiteral
  node.arguments[0].text;
}

Now index 0 is known to exist and to be a ts.StringLiteral.

Again, this isn't really an AST-specific idea.

It's just

Refine one checked location and preserve that fact.

🪆 Nested Checks Can Stay Composable

These refinements can also be nested.

Suppose we want a function-like declaration whose:

body exists
body is a block
first statement exists
first statement is a return statement

We can build the pieces separately.

import * as ts from "typescript";
import { and, refineDefinedKey, refineIndex, refineKey } from "is-kit";

const isBlockStartingWithReturn = and(
  ts.isBlock,
  refineKey("statements", refineIndex(0, ts.isReturnStatement)),
);

const hasBodyStartingWithReturn = refineDefinedKey(
  "body",
  isBlockStartingWithReturn,
);

Then

declare const functionLike: ts.FunctionLikeDeclaration;

if (hasBodyStartingWithReturn(functionLike)) {
  // functionLike.body: ts.Block
  // functionLike.body.statements[0]: ts.ReturnStatement
  functionLike.body.statements[0].expression;
}

Each step proves one thing.

There is no path string like

body.statements[0]

and no special AST DSL.

It's just small guards composed together.

🔒 Why Only One Concrete Key or Index?

There is an important limitation here.

A successful lookup proves one concrete location.

If we check

refineKey("expression", ...)

we proved something about

parent.expression;

We did not prove that every property from some wider key domain passed the same test.

That's why the refinement helpers intentionally work with one concrete key or index.

Broad key unions and similar multi-location claims would make the resulting type much easier to overstate.

I would rather make the API slightly less magical than let one runtime lookup claim more than it actually checked.

🧪 What About TypeScript 7?

This research became especially interesting because TypeScript v7 changed the Compiler API landscape.

The examples in this section were verified against TypeScript v7.0.2.

As of TypeScript v7.0.2, AST types and predicates are exposed through

typescript/unstable/ast

So the same composition style can be used there

import * as ast from "typescript/unstable/ast";
import { and, refineKey } from "is-kit";

const isCallWithIdentifierExpression = and(
  ast.isCallExpression,
  refineKey("expression", ast.isIdentifier),
);

One thing I specifically investigated was whether TypeScript v7 made these isX checks unnecessary through kind narrowing.

For a genuine discriminated union, TypeScript can absolutely narrow from a literal discriminant.

But the broad AST Node currently exposed by the TypeScript v7 AST surface is not that kind of closed discriminated union.

So with a broad AST node, the isX predicates still matter.

For example

import * as ast from "typescript/unstable/ast";

declare const node: ast.Node;

if (node.kind === ast.SyntaxKind.CallExpression) {
  // broad ast.Node does not automatically
  // expose CallExpression properties here
}

This distinction matters.

A custom AST type modeled as a discriminated union can behave differently.

That doesn't mean TypeScript v7's broad Node currently behaves the same way.

Why Not Make `Node` a Closed Union?

After I posted about this, Jake Bailey gave a wonderfully concise answer:

because it's slow 😞

because it's slow 😞
— Jake Bailey (@jakebailey.dev) 2026-09-30T01:49:50.060Z

That makes the trade-off much easier to understand.

If Node were one closed discriminated union containing every AST node type, kind could potentially give us stronger narrowing and exhaustive checks.

For example, with a closed union, we can use the familiar never pattern

switch (node.kind) {
  // handle every known kind...

  default: {
    const exhaustive: never = node;
  }
}

When a new variant is added, that never check can fail at compile time and tell us that our handling is no longer exhaustive.

But that stronger type-level model is not free.

The cost is type-checking performance, a very large closed union gives the checker more work to do.

So the broad shape of ast.Node is not simply a missing narrowing feature.

There is a real trade-off here

stronger compile-time exhaustiveness vs. type-checking performance

And that also helps explain why explicit predicates like ast.isCallExpression() still have an important role.

There is one more TypeScript 7-specific detail worth keeping in mind.

The unstable part of

typescript/unstable/ast

is also important.

I wouldn't build documentation promises around a still-evolving API surface.

The composition pattern is generic.

The exact TypeScript v7 integration can evolve with TypeScript itself.

✋ You Probably Don't Need This for Every AST Check

This is also important.

If I have one local condition

if (ts.isReturnStatement(node) && node.expression) {
  // node: ts.ReturnStatement
  // node.expression: ts.Expression
  visit(node.expression);
}

I would leave it inline.

Really.

Turning it into

const isReturnWithExpression = ...

just because we can doesn't automatically make the code better.

I think the useful split is

Situation	Prefer
One local branch	Native `ts.isX` checks
Repeated AST shape	Named reusable guard
Project already uses `is-kit`	`refineKey`, `refineDefinedKey`, `refineIndex`

The goal isn't

Replace every ts.isX condition with is-kit.

The goal is

When a runtime fact becomes reusable vocabulary, keep the narrowing reusable too.

🚫 What This Does Not Try to Do

is-kit doesn't try to become a Compiler API framework.

It does not:

wrap individual Compiler API functions
validate complete AST node shapes
control AST traversal
detect AST cycles
add a TypeScript runtime dependency
require TypeScript as a peer dependency
replace clear one-off inline checks

The Compiler API is simply a demanding real-world example of generic property refinement.

That's the boundary I want to keep.

🎯 The Important Part

I started this research thinking

Maybe the TypeScript Compiler API needs some special handling.

What I found was more general.

The recurring problem was

narrow parent
    ↓
check child
    ↓
preserve both facts
    ↓
reuse the predicate

That's useful for AST nodes, but it isn't really about AST nodes.

So my current mental model is:

use native type guards for the actual runtime knowledge
keep one-off conditions inline
compose a named guard when the same checked shape becomes reusable
preserve child refinement on the parent instead of rewriting intersection types by hand

For the Compiler API, that can look like

const isCallWithIdentifierExpression = and(
  ts.isCallExpression,
  refineKey("expression", ts.isIdentifier),
);

Small runtime checks.
Small reusable pieces.
And TypeScript keeps the facts we actually checked. 😸

I also wrote a more detailed guide with examples for required children, optional children, array indices, nested AST shapes, and TypeScript 7

Advanced Property Refinement with the TypeScript Compiler API

Advanced Property Refinement with the TypeScript Compiler API | is-kit

Use TypeScript Compiler API guards as an advanced example of reusable property refinement across broad AST node types.

is-kit.dev

And if you want to explore is-kit itself

nyaomaru / is-kit

Build small guards. Compose them. Lightweight, zero-dependency TypeScript type guards for runtime validation and natural narrowing. Runtime-safe 🛡️, composable 🧩, and ergonomic ✨.

is-kit

Build small guards. Compose them.

is-kit is a lightweight, zero-dependency toolkit for building reusable TypeScript type guards.

It helps you write small isFoo functions, compose them into richer runtime checks, and keep TypeScript narrowing natural inside regular control flow.

Runtime-safe 🛡️, composable 🧩, and ergonomic ✨ without asking you to adopt a heavy schema workflow.

Build and reuse typed guards
Compose guards with and, or, not, oneOf
Validate object shapes and collections
Parse or assert unknown values without a large schema framework

Best for app-internal narrowing, filtering, and reusable guards.

🤔 Why use `is-kit`?

Tired of rewriting the same isFoo checks again and again?

is-kit is a good fit when you want to:

write reusable isX functions instead of one-off inline checks
keep runtime validation lightweight and dependency-free
narrow values directly in if, filter…

If it looks useful, a ⭐ on GitHub is always very welcome!

Thanks for reading! 🙌

Your Type Guard Can Silently Drift from Your TypeScript Type 🔧

nyaomaru — Wed, 23 Sep 2026 14:23:57 +0000

Hoi hoi! 👋

I'm @nyaomaru, a frontend engineer just back from a short vacation on Texel, a small island in the Netherlands. 😸🏝️

Today, let's talk about a type guard that looks completely safe.

const isUser = (value: unknown): value is User => {
  // runtime checks...
};

Looks good, right?

TypeScript knows that when isUser(value) returns true, the value is a User.

But there's a small problem

TypeScript trusts that promise.

It doesn't prove that your runtime checks actually validate every field in User.

And that's where type guards can slowly drift away from the types they claim to protect.

Let's take a look! 👀

🕳️ A Type Guard Can Become Outdated Without an Error

Imagine we start with this type

type User = {
  id: string;
  name: string;
};

And a hand-written type guard

const isUser = (value: unknown): value is User => {
  if (typeof value !== "object" || value === null) {
    return false;
  }

  const candidate = value as Record<string, unknown>;

  return typeof candidate.id === "string" && typeof candidate.name === "string";
};

So far, everything matches.

Later, we update User

type User = {
  id: string;
  name: string;
  role: "admin" | "member";
};

But we forget to update the guard.

const isUser = (value: unknown): value is User => {
  if (typeof value !== "object" || value === null) {
    return false;
  }

  const candidate = value as Record<string, unknown>;

  return typeof candidate.id === "string" && typeof candidate.name === "string";
};

There is no role check.

But this still compiles. 😿

🧠 Why Doesn't TypeScript Catch This?

Because this

(value: unknown): value is User

is a user-defined type predicate.

You are telling TypeScript

Trust me. If this function returns true, the value is a User.

TypeScript can check whether the declared predicate type itself makes sense.

But it cannot generally prove that arbitrary runtime logic actually validates every part of that type.

So this is possible

const isUser = (_value: unknown): _value is User => true;

Terrible guard.

Perfectly valid TypeScript. 😹

The return type is a contract written by us, not a proof generated from the function body.

🔄 This Becomes a Maintenance Problem

The annoying part isn't writing the guard once.

It's keeping these two things synchronized over time

TypeScript type
      ↕
Runtime validation

Types change.

Properties get

added
removed
renamed
made optional
changed to another type

And every time that happens, we need to remember that some runtime guard somewhere may also need an update.

If we forget, the compiler may not tell us.

That's the kind of bug I really don't want to rely on memory to prevent.

✅ What If the Type Could Be the Contract?

This is one of the reasons I added typedStruct to is-kit.

Suppose the application type already exists:

type User = {
  id: string;
  name: string;
  age?: number;
};

We can build the guard against that existing type

import { isNumber, isString, optionalKey, typedStruct } from "is-kit";

const isUser = typedStruct<User>()({
  id: isString,
  name: isString,
  age: optionalKey(isNumber),
});

Now the field map has a type-level relationship with User.

At runtime, it still performs ordinary object validation.

But at compile time, TypeScript can check whether the guards we declared match the object type they're supposed to follow.

💥 Now Drift Becomes Visible

Let's add a field again

type User = {
  id: string;
  name: string;
  role: "admin" | "member";
  age?: number;
};

But forget to update the guard

typedStruct<User>()({
  id: isString,
  name: isString,
  age: optionalKey(isNumber),

  // TypeScript error:
  // role is missing
});

Nice.

The runtime bug became a compile-time problem.

The same thing happens if the guard uses an incompatible field type

import {
  isNumber,
  isString,
  oneOfValues,
  optionalKey,
  typedStruct,
} from "is-kit";

typedStruct<User>()({
  id: isString,

  name: isNumber,
  // TypeScript error:
  // User["name"] is string

  role: oneOfValues("admin", "member"),
  age: optionalKey(isNumber),
});

This is the part I care about most.

typedStruct doesn't eliminate maintenance.

It makes forgotten maintenance visible.

🧩 Optional and Nullable Are Different

Another place where object guards can get confusing is optional properties.

Consider:

type User = {
  id: string;
  nickname?: string | null;
};

There are two separate ideas here

nickname may be absent

and

nickname may exist with the value null

Those are different runtime contracts.

With typedStruct

import { isString, nullable, optionalKey, typedStruct } from "is-kit";

const isUser = typedStruct<User>()({
  id: isString,
  nickname: optionalKey(nullable(isString)),
});

Now

isUser({ id: "user-1" });
// true

isUser({
  id: "user-1",
  nickname: null,
});
// true

isUser({
  id: "user-1",
  nickname: "Neko",
});
// true

isUser({
  id: "user-1",
  nickname: 42,
});
// false

I like keeping these two decisions explicit:

optionalKey(...) → the property may be absent
nullable(...) → the value may be null

They look similar at first, but they describe different things.

🌳 Nested Types Don't Need to Be Duplicated Either

Now imagine a larger type:

type Account = {
  readonly id: string;

  readonly profile: {
    readonly displayName: string;
    readonly bio: string | null;
  } | null;

  readonly tags: readonly string[];
};

We could manually copy the profile shape into another type.

But that creates another thing that can drift.

Instead, we can reference the type we already have

import { arrayOf, isString, nullable, typedStruct } from "is-kit";

const isProfile = typedStruct<NonNullable<Account["profile"]>>()({
  displayName: isString,
  bio: nullable(isString),
});

const isAccount = typedStruct<Account>()({
  id: isString,
  profile: nullable(isProfile),
  tags: arrayOf(isString),
});

This is the model I like:

Reuse the existing type at compile time. Compose small guards at runtime.

The application type remains the source we want the guard to follow.

🔒 What About Extra Runtime Properties?

There is another distinction worth making.

These are two different questions:

Does my guard definition match the TypeScript type?
Should a runtime object be allowed to contain additional properties?

By default, an object can still have additional keys.

If you want the runtime object shape to be closed as well, you can enable exact mode:

import { isString, typedStruct } from "is-kit";

type User = {
  id: string;
  name: string;
};

const isExactUser = typedStruct<User>()(
  {
    id: isString,
    name: isString,
  },
  {
    exact: true,
  },
);

Then:

isExactUser({
  id: "user-1",
  name: "Ada",
});
// true

isExactUser({
  id: "user-1",
  name: "Ada",
  debug: true,
});
// false

Whether extra properties should be rejected is a runtime policy decision.

It shouldn't be confused with keeping the guard definition synchronized with the TypeScript type.

⚖️ Which Should Be the Source of Truth?

I don't think there is one correct validation style for every project.

The important question is

What already owns the shape of this data?

Manual predicate

const isSomething = (value: unknown): value is Something => {
  // custom logic
};

Great when the validation is unusual or not primarily structural.

Guard-first

const isUser = struct({
  id: isString,
  name: isString,
});

Useful when the guard itself should define the resulting type.

Type-first

const isUser = typedStruct<User>()({
  id: isString,
  name: isString,
});

Useful when User already exists and the runtime guard needs to stay aligned with it.

Schema-first

A schema library or code generation may be the better source of truth when you need things like:

structured validation errors
coercion
transforms
defaults
generated artifacts

These solve different problems.

I don't think every boolean validation check needs to become a schema. 😸

🚫 What `typedStruct` Does Not Do

There are some important boundaries.

typedStruct does not generate runtime validation from a TypeScript type.

Types are erased at runtime, so you still need to declare the guards you want to execute.

It also doesn't:

prove that every custom predicate is honest
coerce values
return rich structured validation errors
replace schema-first workflows
validate numeric or symbol properties as part of its string-keyed object contract

It's intentionally smaller than that.

The goal is simply to create a typed bridge between

the object type you already have

and

the runtime guards you choose to run

🎯 The Important Part

The main point isn't really typedStruct.

It's this

A type predicate is a promise, not a proof.

This

(value): value is User

doesn't mean TypeScript inspected your implementation and proved that every User field was validated.

We made that promise.

So when a TypeScript type is the source of truth, I think it's useful to make the runtime guard structurally depend on that type instead of relying on us to remember every future change.

That's what I wanted typedStruct to help with. 😸

If your guard defines the type, use a guard-first approach.

If an existing TypeScript type should define the contract, connect the guard to that type.

And if you need rich parsing, transforms, coercion, or detailed errors, that's where a schema starts to earn its weight.

I wrote a more complete guide about this on the is-kit documentation site:

Keep Type Guards in Sync with TypeScript Types | is-kit

Keep hand-written runtime guards aligned with existing string-keyed TypeScript object types using typedStruct and field-level checks.

is-kit.dev

If you like small reusable TypeScript type guards, is-kit is open source too!

nyaomaru / is-kit

Build small guards. Compose them. Lightweight, zero-dependency TypeScript type guards for runtime validation and natural narrowing. Runtime-safe 🛡️, composable 🧩, and ergonomic ✨.

is-kit

Build small guards. Compose them.

is-kit is a lightweight, zero-dependency toolkit for building reusable TypeScript type guards.

It helps you write small isFoo functions, compose them into richer runtime checks, and keep TypeScript narrowing natural inside regular control flow.

Runtime-safe 🛡️, composable 🧩, and ergonomic ✨ without asking you to adopt a heavy schema workflow.

Build and reuse typed guards
Compose guards with and, or, not, oneOf
Validate object shapes and collections
Parse or assert unknown values without a large schema framework

Best for app-internal narrowing, filtering, and reusable guards.

🤔 Why use `is-kit`?

Tired of rewriting the same isFoo checks again and again?

is-kit is a good fit when you want to:

write reusable isX functions instead of one-off inline checks
keep runtime validation lightweight and dependency-free
narrow values directly in if, filter…

Thanks for reading! 🙌

Why filter(Boolean) Is Not a Nullish Filter in TypeScript 🔧

nyaomaru — Wed, 16 Sep 2026 14:24:28 +0000

Hoi hoi! 👋

I'm @nyaomaru, a frontend engineer building small TypeScript OSS with shoyu ramen. 😸🍜

Today, let's look at a very small line of JavaScript.

values.filter(Boolean);

You've probably seen it before.

It's short.
It's convenient.
And sometimes, it's exactly what you want.

But if your intention is

Remove only null and undefined

then filter(Boolean) is doing more than you asked.

Let's see why! 👀

🕳️ The Small Trap in `filter(Boolean)`

Imagine we have this array.

const values = ["ready", "", 0, false, null, undefined];

Suppose we try to remove the missing values like this.

const result = values.filter(Boolean);

At runtime, what remains?

["ready"];

Wait.

We only wanted to remove

null;
undefined;

But we also lost

"";
0;
false;

Why?

Because Boolean converts its argument to a boolean and keeps only values
whose result is true.

It isn't checking whether a value is nullish.

🤔 Falsy and Nullish Are Different

JavaScript considers all of these values falsy

false;
0;
("");
null;
undefined;
NaN;

But these two requirements are different

Remove every falsy value

and

Remove null and undefined

In real applications, 0, false, and '' can all be completely valid data.

For example

type Settings = {
  retryCount: number;
  notificationsEnabled: boolean;
  nickname: string;
};

These can all be valid

retryCount = 0;
notificationsEnabled = false;
nickname = "";

Falsy does not mean missing.

🧠 There Is a TypeScript Difference Too

filter(Boolean) removes falsy values at runtime, but Boolean is not a type guard.

TypeScript therefore does not generally know that null and undefined are gone.

const values: Array<string | number | boolean | null | undefined> = [
  "ready",
  "",
  0,
  false,
  null,
  undefined,
];

const result = values.filter(Boolean);

// result: Array<string | number | boolean | null | undefined>

So filter(Boolean) can be right when truthiness is the runtime rule, but it doesn't express a nullish-removal rule to either JavaScript readers or the TypeScript type system. 🙀

✅ Say What You Actually Mean

If the rule is

Keep everything except null and undefined

we can write exactly that

const values: Array<string | null | undefined> = [
  "Ada",
  null,
  "Linus",
  undefined,
];

const names = values.filter(
  (value): value is string => value !== null && value !== undefined,
);

Now

// names: string[]

This is perfectly good TypeScript.

You don't need a library for a one-off check.

⚠️ A browser edge case: avoid `value != null`

You may also see this shorter version

values.filter((value): value is string => value != null);

For ordinary values, it looks equivalent to checking both null and
undefined. In browsers, though, document.all is a historical compatibility exception.

document.all == null; // true
document.all != null; // false

document.all === null; // false
document.all === undefined; // false

document.all is an object, not null or undefined, but loose equality　treats it as nullish. So if the contract is only “remove null and　undefined”, use strict comparisons.

(value): value is string => value !== null && value !== undefined;

You will rarely encounter this in application code, but the edge case is why a precise nullish guard should not be implemented with != null.

See MDN's equality operator reference for the compatibility rule behind this behavior.

🔁 What If You Keep Writing It?

The interesting part starts when the same meaning appears repeatedly.

(value): value is string => value !== null && value !== undefined;

Maybe in

API adapters
selectors
UI helpers
mapped data
utility functions

At that point, the useful abstraction isn't really the syntax.

It's the meaning

This value is not nullish.

That's where I like using a named type guard.

With is-kit

import { isNotNil } from "is-kit";

const names = values.filter(isNotNil);

The result still narrows naturally

// names: string[]

And unlike Boolean, valid falsy values stay intact.

const values: Array<string | number | boolean | null | undefined> = [
  "ready",
  "",
  0,
  false,
  null,
  undefined,
];

const result = values.filter(isNotNil);

// ['ready', '', 0, false]
// result: Array<string | number | boolean>

🧩 A Practical Example

Nullable values often appear after map.

type User = {
  id: string;
  nickname?: string | null;
};

const users: User[] = [
  { id: "1", nickname: "nyaomaru" },
  { id: "2", nickname: null },
  { id: "3" },
];

We want only the existing nicknames.

const nicknames = users.map((user) => user.nickname).filter(isNotNil);

// string[]

This is the kind of place where a reusable guard feels natural to me.

The array transformation stays ordinary JavaScript, while TypeScript knows
that the nullish values are gone.

⚖️ Which One Should You Use?

I think the choice is pretty simple.

Use

filter(Boolean);

when you genuinely want

Keep only truthy values.

Use an inline predicate when the nullish check appears once:

values.filter(
  (value): value is string => value !== null && value !== undefined,
);

And use a reusable guard such as

values.filter(isNotNil);

when that same meaning appears repeatedly.

There is no need to turn every condition into an abstraction.

🔍 Can ESLint Catch This?

I recently released eslint-plugin-is-kit, a type-aware ESLint plugin for TypeScript predicates.

One of its rules looks specifically for ambiguous filter(Boolean) calls.

declare const values: Array<string | null>;

values.filter(Boolean);

Because the element type contains both null and a non-nullish falsy value (""), the plugin can warn that Boolean may remove more than just the missing value.

But it does not simply ban filter(Boolean).

declare const values: number[];

values.filter(Boolean);

There is no null or undefined in the element type, so there is no evidence that nullish removal was intended.

The rule is deliberately conservative.

The initial v0.1.0 release includes four type-aware rules for:

ambiguous filter(Boolean) calls
redundant is-kit predicates
repeated inline nullish filters that could use isNotNil
inline predicates that can be expressed with reusable type guards

For example

values.filter((value) => typeof value === "string");

can be expressed as

values.filter(isString);

when doing so preserves the runtime behavior and useful TypeScript narrowing.

If this kind of check would be useful in your codebase:

It's still an early release, so false positives and ideas for useful rules are very welcome. 😸

🎯 The Important Part

The main point isn't really isNotNil.

It's this

Falsy values and missing values are not the same thing.

filter(Boolean) is not bad code.

It just expresses a different requirement.

So before writing

values.filter(Boolean);

ask

Do I want to remove falsy values, or only nullish values?

That tiny distinction can prevent valid data like 0, false, and '' from disappearing unexpectedly. 😸

I also wrote a more complete guide about nullish filtering on the is-kit
documentation site, including isNil, isNotNil, and the different
approaches.

If you like small reusable TypeScript type guards, is-kit is open source too! And don't forget to put a star! ⭐

nyaomaru / is-kit

Build small guards. Compose them. Lightweight, zero-dependency TypeScript type guards for runtime validation and natural narrowing. Runtime-safe 🛡️, composable 🧩, and ergonomic ✨.

is-kit

Build small guards. Compose them.

is-kit is a lightweight, zero-dependency toolkit for building reusable TypeScript type guards.

It helps you write small isFoo functions, compose them into richer runtime checks, and keep TypeScript narrowing natural inside regular control flow.

Runtime-safe 🛡️, composable 🧩, and ergonomic ✨ without asking you to adopt a heavy schema workflow.

Build and reuse typed guards
Compose guards with and, or, not, oneOf
Validate object shapes and collections
Parse or assert unknown values without a large schema framework

Best for app-internal narrowing, filtering, and reusable guards.

🤔 Why use `is-kit`?

Tired of rewriting the same isFoo checks again and again?

is-kit is a good fit when you want to:

write reusable isX functions instead of one-off inline checks
keep runtime validation lightweight and dependency-free
narrow values directly in if, filter…

Thanks for reading! 🙌

Learn Trapping Rain Water, Top K Frequent and Selection Sort with Step-by-Step Visualization in DSA View View 👀👀

nyaomaru — Wed, 09 Sep 2026 12:48:25 +0000

Hoi hoi!

I’m @nyaomaru, a frontend engineer who has been obsessed with ramen lately. 😸🍜

Have you used DSA View View already? 👀👀

Features a timeline to step backward mid-loop

nyaomaru

Jul 15

I Built a Tool to Visualize DSA. Let’s Learn Together! (DSA View View 👀👀)

#showdev #typescript #dsa #react

7 min read

DSA View View allows you to understand DSA by visualizing how your implementation actually runs.

In the previous articles, we looked at problems like:

Two Sum
Binary Search
Bubble Sort
Valid Parentheses
Reverse Linked List
Maximum Depth of Binary Tree
Number of Islands
Invert Binary Tree
Course Schedule

Visualizing execution logic changes mental models

nyaomaru

Aug 19

Is Learning DSA Boring? Let's Use DSA View View 👀👀 (Two Sum, Binary Search, and Bubble Sort)

#dsa #typescript #opensource #learning

7 min read

Curated progression from stacks to recursion

nyaomaru

Aug 26

Learn Valid Parentheses, Reverse Linked List, and Tree Max Depth with Step-by-Step Visualization in DSA View View 👀👀

#typescript #algorithms #opensource #dsa

9 min read

Readers praise the recursive swap explanation

nyaomaru

Sep 2

Learn Number of Islands, Invert Binary Tree, and Course Schedule with Step-by-Step Visualization in DSA View View 👀👀

#typescript #dsa #opensource #webdev

12 min read

This time, let's try three more problems:

Trapping Rain Water
Top K Frequent Elements
Selection Sort

These three problems introduce some very useful ways of thinking

Shrink a problem from both sides
Count first, then organize by frequency
Repeatedly select the next value

Once again, the implementations are not necessarily huge.

But there are several changing values that we need to keep in our heads.

So instead of only reading the final code,

Let's view what actually happens. 👀👀

🌧️ Trapping Rain Water

Let's start with Trapping Rain Water.

Suppose we have these heights

[0, 1, 0, 2, 1, 0, 1, 3]

If we draw them as walls, it looks roughly like this.

              █
      █       █
  █   █ █   █ █
-----------------
0 1 0 2 1 0 1 3

Rain falls from above.

Some water escapes.

But some water becomes trapped between taller walls.

For example

      █~~~~~~~█
  █~~~█~~~~~~~█
-----------------

So the question is

How much water can be trapped?

At first, I found this problem quite confusing. 😿

Because the amount of water above one position depends on walls somewhere else.

So what information do we actually need?

How Much Water Fits Above One Position?

Imagine this position

left wall     right wall
    █             █
    █      x      █
    █      █      █

The water level cannot be higher than the shorter side.

So the maximum possible water level is

Math.min(leftMax, rightMax);

Then we subtract the current height.

Conceptually:

water = min(leftMax, rightMax) - currentHeight

That's the basic idea.

But do we really need to calculate both sides again for every position?

No.

We can use two pointers.

Two Pointers

Here is the implementation.

function trap(height: number[]): number {
  let left = 0;
  let right = height.length - 1;

  let leftMax = 0;
  let rightMax = 0;

  let water = 0;

  while (left <= right) {
    if (height[left] <= height[right]) {
      if (height[left] >= leftMax) {
        leftMax = height[left];
      } else {
        water += leftMax - height[left];
      }

      left++;
    } else {
      if (height[right] >= rightMax) {
        rightMax = height[right];
      } else {
        water += rightMax - height[right];
      }

      right--;
    }
  }

  return water;
}

There are several important values.

left
right
leftMax
rightMax
water

This is exactly the kind of code where I understand every variable individually,

but then lose track of all of them together. 😹

Let's follow a smaller example.

[2, 0, 1, 3]

Start From Both Ends

At first

left = 0
right = 3

[2, 0, 1, 3]
 ↑        ↑
left    right

The heights are:

height[left]  = 2
height[right] = 3

Since

2 <= 3

we process the left side.

There is a wall with height 2.

leftMax = 2

Then move left.

[2, 0, 1, 3]
    ↑     ↑
   left right

Now We Can Trap Water

The current height is

But we already know there is a wall of height 2 on the left.

And the right side is currently at least as high as that.

So this position can hold

leftMax - height[left]
= 2

Therefore

water = 2

Move again.

[2, 0, 1, 3]
       ↑  ↑
      left right

Now

height[left] = 1
leftMax = 2

2 - 1 = 1

One more unit of water.

water = 3

Eventually we reach the final wall.

Done! 🎉

Why Can We Process the Shorter Side?

This part is the important idea.

Suppose

height[left] <= height[right]

Then we already know there is a wall on the right that is at least as tall as the current left wall.

So for the current left position, the limiting factor is the best wall we have seen from the left.

That's why we can safely calculate

leftMax - height[left];

without knowing every future wall.

The same logic works from the other side.

height[right] < height[left]

we process the right side using rightMax.

So the algorithm keeps shrinking the unknown area

L → → →     ← ← ← R

until everything has been processed.

Complexity

Each pointer only moves across the array once.

Time:  O(n)
Space: O(1)

👀 Let's View View It

This problem is a perfect example of why I like visualization.

The code contains

left
right
leftMax
rightMax
water

And they all change at different times.

When I only read

water += leftMax - height[left];

I might ask:

Why are we using leftMax here?
What is rightMax right now?
Why did we move left instead of right?
How much water have we already counted?
Which part of the array is still unprocessed?

😿

Step by step, we can actually watch the search area shrink.

L         R
↓         ↓
[2, 0, 1, 3]

    L     R
    ↓     ↓
[2, 0, 1, 3]

       L  R
       ↓  ↓
[2, 0, 1, 3]

And at the same time

leftMax
rightMax
water

keep changing.

The algorithm is really asking

Which side can I safely solve right now?

Then it solves that side and moves inward. 🌧️😸

🔢 Top K Frequent Elements

Next, let's find the Top K Frequent Elements.

Suppose we have

[1, 1, 1, 2, 2, 3]

and

k = 2

How often does each number appear?

1 → 3 times
2 → 2 times
3 → 1 time

So the two most frequent values are

[1, 2]

Simple enough.

But how should we implement it?

First, Count Everything

The first thing we need is frequency.

We can use a Map.

const frequency = new Map<number, number>();

Then count each value.

for (const num of nums) {
  frequency.set(num, (frequency.get(num) ?? 0) + 1);
}

For

[1, 1, 1, 2, 2, 3]

we get

frequency = {
  1 → 3
  2 → 2
  3 → 1
}

Nice.

But we still need the top K.

Of course, we could sort everything by frequency.

But there is another interesting approach.

Use Frequency as an Index

The maximum possible frequency is

nums.length

So we can create buckets.

const buckets: number[][] = Array.from({ length: nums.length + 1 }, () => []);

The index represents frequency.

For example

bucket[1] = values appearing 1 time
bucket[2] = values appearing 2 times
bucket[3] = values appearing 3 times

For our example:

frequency = {
  1 → 3
  2 → 2
  3 → 1
}

the buckets become

index 0 → []
index 1 → [3]
index 2 → [2]
index 3 → [1]

That's pretty interesting. 👀👀

Instead of asking

What is the frequency of this number?

we reverse the relationship

Which numbers have this frequency?

Implementation

Here is the full implementation:

function topKFrequent(nums: number[], k: number): number[] {
  const frequency = new Map<number, number>();

  for (const num of nums) {
    frequency.set(num, (frequency.get(num) ?? 0) + 1);
  }

  const buckets: number[][] = Array.from({ length: nums.length + 1 }, () => []);

  for (const [num, count] of frequency) {
    buckets[count].push(num);
  }

  const result: number[] = [];

  for (let count = buckets.length - 1; count >= 0; count--) {
    for (const num of buckets[count]) {
      result.push(num);

      if (result.length === k) {
        return result;
      }
    }
  }

  return result;
}

Let's follow it.

Step 1: Build the Frequency Map

Start

frequency = {}

Read the first 1. And another one and another...

1 → 1
1 → 2
1 → 3

Then 2. And another one.

1 → 3
2 → 1
2 → 2

Finally 3.

1 → 3
2 → 2
3 → 1

Done.

Step 2: Put Values Into Buckets

Now

buckets[count].push(num);

For

1 → 3

we do

buckets[3].push(1)

For

2 → 2

we do

buckets[2].push(2)

And

3 → 1

becomes

buckets[1].push(3)

0: []
1: [3]
2: [2]
3: [1]

Step 3: Read From Highest Frequency

We want the most frequent values.

So don't start at 0. Start from the end.

3 → [1]
2 → [2]
1 → [3]

Take 1.

result = [1]

We still need one more. Move down.

Take 2.

result = [1, 2]

Now

result.length === k

So return.

Done! 🎉

Why Is This Interesting?

I like this solution because the second structure changes our perspective.

The Map says

value → frequency

The buckets say

frequency → values

Same information. But different direction.

And suddenly finding the most frequent values becomes easy.

We just walk backward through the buckets.

Complexity

We count every number once.

We distribute every unique number into a bucket.

Then we walk through the buckets.

Time:  O(n)
Space: O(n)

👀 Let's View View It

There are two transformations happening here.

First

nums
 ↓
frequency Map

Then

frequency Map
 ↓
buckets

Then

buckets
 ↓
result

Reading the final implementation, it can be easy to miss why we're building two different data structures.

With the runtime visible, we can follow the data changing shape.

[1, 1, 1, 2, 2, 3]
        ↓ count
1 → 3
2 → 2
3 → 1
        ↓ bucket
1: [3]
2: [2]
3: [1]
        ↓ highest first
[1, 2]

That's the part I like.

We don't magically find the top K.

We reorganize the information until the answer becomes easy to read. 🔢😸

👉 Selection Sort

Finally, let's sort something again!

We already looked at Bubble Sort in a previous article.

This time, let's try Selection Sort.

Suppose we have

[5, 3, 4, 1, 2]

We want

[1, 2, 3, 4, 5]

Selection Sort follows a very simple idea

Find the smallest remaining value and move it to the front.

Then repeat.

First Pass

Start

[5, 3, 4, 1, 2]
 ↑
 i

Assume the first value is currently the smallest.

minIndex = 0

Then scan everything to the right.

5 vs 3

3 is smaller.

So:

minIndex = 1

Then:

3 vs 4

No change.

Then

3 vs 1

1 is smaller.

minIndex = 3

Finally

1 vs 2

Still 1.

So the smallest value is at index 3.

Swap

[5, 3, 4, 1, 2]
 ↑        ↑
 i       min

↓

[1, 3, 4, 5, 2]

Now the first position is finished.

[1 | 3, 4, 5, 2]
 ↑
sorted

Repeat

Next, start from index 1.

[1 | 3, 4, 5, 2]
     ↑
     i

Find the smallest value in

[3, 4, 5, 2]

That's 2.

Swap.

[1, 2 | 4, 5, 3]

Again.

Find the smallest remaining value.

Eventually

[1, 2, 3, 4, 5]

Sorted! 🎉

Implementation

function selectionSort(nums: number[]): number[] {
  for (let i = 0; i < nums.length - 1; i++) {
    let minIndex = i;

    for (let j = i + 1; j < nums.length; j++) {
      if (nums[j] < nums[minIndex]) {
        minIndex = j;
      }
    }

    if (minIndex !== i) {
      [nums[i], nums[minIndex]] = [nums[minIndex], nums[i]];
    }
  }

  return nums;
}

There are two important indexes.

i
minIndex

And also

which searches through the unsorted area.

Why Is It Called Selection Sort?

Because each pass selects the smallest remaining value.

Find smallest
  ↓
Select it
  ↓
Move it to the front
  ↓
Repeat

That's basically the whole algorithm.

Complexity

For every position, we search through the remaining values.

Time: O(n²)

We sort the array in place.

Space: O(1)

Selection Sort is not something I would normally choose for sorting a huge production dataset. 😹

But as a learning algorithm, it is wonderfully visual.

👀 Let's View View It

The implementation contains nested loops.

for (let i = 0; i < nums.length - 1; i++) {
  let minIndex = i;

  for (let j = i + 1; j < nums.length; j++) {

Reading it, I might lose track of:

Which area is already sorted?
Where is i?
Where is j?
What does minIndex currently point to?
When exactly does the swap happen?

When we visualize it, the basic pattern becomes obvious.

[5, 3, 4, 1, 2]
          ↑
       smallest

[1 | 3, 4, 5, 2]
              ↑
           smallest

[1, 2 | 4, 5, 3]

The algorithm is continuously growing a finished area from left to right.

That's Selection Sort.

Pick the smallest remaining value.

Put it next. And repeat. 🍥😸

🧠 What Did We Actually Learn?

Again, these three problems look completely different.

But each one introduces a useful way of thinking.

Trapping Rain Water

Use information from both sides to decide which part can already be solved safely.

Which side do I know enough about right now?

Top K Frequent Elements

Sometimes counting the data is only the first step.

Reorganize it into a structure where the answer becomes easy to retrieve.

Can I reorganize this information around what I actually need?

Selection Sort

Build the answer one permanent position at a time.

What value belongs in this position next?

So this time we saw

Two pointers
Frequency buckets
Selection

Three different mental models again.

And just like the previous problems, the difficult part is often not the syntax.

It's the changing state.

Which pointer moved?
What is the maximum now?
What is inside the Map?
Which bucket changed?
Where is minIndex?
Which part is already finished?

That's a lot to keep in our heads.

So instead, I want to view it. 👀👀

🎯 Conclusion

In this article, we looked at:

Trapping Rain Water with two pointers
Top K Frequent Elements with frequency buckets
Selection Sort

And more importantly, we followed how their state changes while they run.

For Trapping Rain Water, we watched two pointers move inward while leftMax, rightMax, and water changed.

left →       ← right

For Top K Frequent Elements, we watched the same data change representation.

array
  ↓
frequency Map
  ↓
buckets
  ↓
result

For Selection Sort, we watched the sorted area grow one position at a time.

This is exactly the kind of thing I built DSA View View for.

You can write or load a TypeScript implementation, run it with your own inputs, and move backward and forward through the runtime.

If you are learning DSA too, try viewing one of these problems step by step.

And if there is a DSA problem you want me to cover next, please let me know in the comments!

I still have many algorithms to learn myself. 😸

Let's train our DSA muscles together! 💪

If you like DSA View View, please give it a star ⭐

nyaomaru / dsa-view-view

DSA View View allows you to understand DSA to see the data flow. 👀👀 Of course, it's free.

DSA View View

DSA View View turns TypeScript algorithm functions into step-by-step visual stories. 👀👀

Write code, run it with structured inputs, and see the arrays, matrices trees, lists, stacks, pointers, and return values move as the function executes.

It is built for those moments when reading the code is not enough and you want to view why the answer changes.

Why Try It?

🧠 Step through real TypeScript
Paste or edit a function, validate it, then run the exact code in the browser.
🧩 Views that match the data
Arrays become bars, matrices become grids, trees become node graphs, linked lists become chains, and two-pointer area problems get their own visual view.
🌳 DSA-friendly inputs out of the box
TreeNode, ListNode, MinHeap, MaxHeap, PriorityQueue, nested arrays matrices, strings, numbers, and class-style inputs are supported without ceremony.
🔎 39 built-in examples
Search by name, browse…

See you in the next article!

Learn Number of Islands, Invert Binary Tree, and Course Schedule with Step-by-Step Visualization in DSA View View 👀👀

nyaomaru — Wed, 02 Sep 2026 14:54:12 +0000

Hoi hoi!

I’m @nyaomaru, a frontend engineer who is surprised by how cold it is in the Netherlands even though it’s still summer. 😸

Have you used DSA View View already? 👀👀

Features a timeline to step backward mid-loop

nyaomaru

Jul 15

I Built a Tool to Visualize DSA. Let’s Learn Together! (DSA View View 👀👀)

#showdev #typescript #dsa #react

7 min read

DSA View View allows you to understand DSA by visualizing how your implementation actually runs.

In the previous articles, we looked at problems like:

Two Sum
Binary Search
Bubble Sort
Valid Parentheses
Reverse Linked List
Maximum Depth of Binary Tree

Visualizing execution logic changes mental models

nyaomaru

Aug 19

Is Learning DSA Boring? Let's Use DSA View View 👀👀 (Two Sum, Binary Search, and Bubble Sort)

#dsa #typescript #opensource #learning

7 min read

Curated progression from stacks to recursion

nyaomaru

Aug 26

Learn Valid Parentheses, Reverse Linked List, and Tree Max Depth with Step-by-Step Visualization in DSA View View 👀👀

#typescript #algorithms #opensource #dsa

9 min read

This time, let's try three more classic problems:

Number of Islands
Invert Binary Tree
Course Schedule

These three problems introduce some very useful ways of thinking:

Explore connected things
Transform a tree with recursion
Resolve dependencies in the right order

The implementations are not huge.

But the runtime can become surprisingly difficult to hold in our heads.

So let's view what actually happens. 👀

Let's learn together! 😸

🏝️ Number of Islands

Let's start with Number of Islands.

Suppose we have this grid:

1 means land. 🏝️

0 means water. 🌊

Land connected vertically or horizontally belongs to the same island.

So how many islands are there?

Let's look at the first group.

1 1
1

These cells are connected.

So they form one island.

On the right side

    1
  1 1

Those cells are also connected.

So the answer is 2.

Nice! 🏝️🏝️

But how do we make the code understand that several 1s belong to the same island?

Find One Land, Then Explore All Connected Land

The basic idea is

When we find a new 1, count one island and visit all land connected to it.

Let's use this implementation.

function numIslands(grid: string[][]): number {
  let islands = 0;

  const visit = (row: number, col: number): void => {
    if (row < 0 || col < 0) return;
    if (row >= grid.length || col >= grid[row].length) return;
    if (grid[row][col] !== "1") return;

    grid[row][col] = "0";
    visit(row + 1, col);
    visit(row - 1, col);
    visit(row, col + 1);
    visit(row, col - 1);
  };

  for (let row = 0; row < grid.length; row++) {
    for (let col = 0; col < grid[row].length; col++) {
      if (grid[row][col] === "1") {
        islands++;
        visit(row, col);
      }
    }
  }

  return islands;
}

There are two important parts.

First, we scan the grid

for (let row = 0; row < grid.length; row++) {
  for (let col = 0; col < grid[row].length; col++) {

Then, when we find land

if (grid[row][col] === "1") {
  islands++;
  visit(row, col);
}

We count a new island.

But then visit() does something important.

It removes all land connected to that island from future consideration.

Why Do We Change `1` to `0`?

Inside visit() we have

grid[row][col] = "0";

At first, changing land into water looks a little strange. 😿

But here, 0 really means

We already visited this land.

Let's follow a tiny example.

1 1
1 0

We start at the top-left. And we found land! So

islands = 1

Then

visit(0, 0);

Inside visit(), we mark it as visited.

0 1
1 0

Then we visit the four directions

down
up
right
left

Going down finds another 1.

0 1
1 0
↑

So we visit it too.

0 1
0 0

Going right from the original cell also finds land.

Visit it.

0 0
0 0

Now the whole connected island has disappeared from our search.

When the outer loops continue, there is no 1 left in that island to count again.

That's the key idea.

Count once, then mark the whole connected area as visited.

Why Four Recursive Calls?

We use

visit(row + 1, col);
visit(row - 1, col);
visit(row, col + 1);
visit(row, col - 1);

That means

        up
         ↑
left ← current → right
         ↓
        down

Each visited cell asks

Is there more land next to me?

And every newly discovered land cell asks the same question again.

This continues until we reach:

water
outside the grid
land we already visited

Those cases stop the recursion.

The Base Cases

These lines protect us

if (row < 0 || col < 0) return;
if (row >= grid.length || col >= grid[row].length) return;
if (grid[row][col] !== "1") return;

So,

If we walk outside the grid, stop.
If we reach water, stop.
If we reach a cell we already changed to 0, stop.

Otherwise, continue exploring.

Let's Follow Two Islands

Consider

1 1 0
0 0 1
0 1 1

The scan begins at the top-left.

Found land.

islands = 1

visit() removes everything connected to it.

0 0 0
0 0 1
0 1 1

The loops continue.

Eventually we reach

Another 1.

islands = 2

And visit() explores that entire connected area.

0 0 0
0 0 0
0 0 0

Done!

2 islands

🎉

Complexity

Every cell is processed at most a small number of times.

If the grid has m rows and n columns

Time:  O(m × n)

In the worst case, the recursive call stack may grow with the number of land cells.

Space: O(m × n)

👀 Let's View View It

This is one of those algorithms where the final code is pretty small.

But while reading it, there are a lot of things moving at once

row
col
grid
islands
recursive calls

And then suddenly we see

grid[row][col] = "0";

Why did that cell disappear?
Which recursive call are we inside?
Which cells belong to the current island?
Where will the outer loop continue after recursion finishes?

That is a lot to simulate mentally. 😿

When we view it step by step, the idea becomes much more visual.

Find land
  ↓
islands++
  ↓
visit connected land
  ↓
mark it visited
  ↓
expand up / down / left / right
  ↓
return to scanning
  ↓
find next island

Instead of thinking about recursion first, I like to think about it like this

Find one island, paint the whole island away, then keep searching.

🏝️😸

🌳 Invert Binary Tree

Next, let's invert a binary tree.

Suppose we have

We want to change

Every left child becomes the right child.

Every right child becomes the left child.

Simple, right?

Well, the final implementation is also surprisingly small.

function invertTree(root: TreeNode | null): TreeNode | null {
  if (root === null) return null;

  const left = invertTree(root.left);
  const right = invertTree(root.right);

  root.left = right;
  root.right = left;

  return root;
}

That's almost suspiciously short. 👀

Go Down First

Let's use a smaller tree.

    1
   / \
  2   3

We start at node 1.

But we don't swap immediately.

First,

const left = invertTree(root.left);

So we go to node 2.

Node 2 also tries to invert its left child.

But there is no child.

if (root === null) return null;

returns null.

The same thing happens on the right side of node 2.

Now node 2 has

left = null
right = null

root.left = right;
root.right = left;

does not visibly change anything.

Node 2 returns.

Then node 1 explores its right subtree.

Node 3 also has no children, so it returns after the same process.

Only then do we come back to node 1.

Now

left = 2
right = 3

And we do

root.left = right;
root.right = left;

    1
   / \
  2   3

becomes 👇

    1
   / \
  3   2

Done! 🎉

The Important Part: The Swap Happens on the Way Back

This is what makes the recursive solution interesting.

The function first goes down.

1
↓
2
↓
null

Then it comes back.

Later it explores the other side.

1
↓
3
↓
null

And after both children have returned, the current node swaps them.

So the flow is more like

Go left
  ↓
Invert left subtree
  ↓
Go right
  ↓
Invert right subtree
  ↓
Swap the returned subtrees
  ↓
Return current node

The tree transformation is built while recursion unwinds.

A Slightly Bigger Example

Let's look at

We start at 4.

invertTree(4)

Then

invertTree(2)

Then

invertTree(1)

Node 1 returns.

Then node 3 returns.

Now node 2 has

left = 1
right = 3

Swap them.

    2
   / \
  3   1

Then recursion returns to 4.

The right subtree rooted at 7 is also processed.

Finally node 4 receives

left = inverted subtree rooted at 2
right = inverted subtree rooted at 7

and swaps them.

The final tree becomes

The interesting thing is that each node only needs to know about its own two children.

It doesn't need to understand the whole tree.

Complexity

We visit every node once.

Time: O(n)

The recursive call stack depends on the height of the tree.

Space: O(h)

For a balanced tree

O(log n)

In the worst case

O(n)

👀 Let's View View It

This is exactly where recursion can become difficult to mentally simulate.

The code says

const left = invertTree(root.left);
const right = invertTree(root.right);

Then

root.left = right;
root.right = left;

But my brain immediately starts asking:

Which root are we talking about now?
Did node 2 already swap?
Are we still going down?
Or are we coming back up?
What does left contain at this moment?

😿

When we step through the runtime, we can separate two different movements.

The final code is short.

But the actual runtime has a rhythm 🎵

Go down
↓
Return
↓
Swap
↓
Return
↓
Swap

Once I can see that rhythm, the recursive solution feels much less magical. 🌳😸

🎓 Course Schedule

Finally, let's look at Course Schedule.

This one is a little more difficult.

Suppose we have three courses

0
1
2

And the prerequisites are

[1, 0]
[2, 1]

That means

To take course 1, finish course 0 first.
To take course 2, finish course 1 first.

So the dependency looks like

0 → 1 → 2

Can we finish all courses?

Yes.

We can take them in this order 0 → 1 → 2.

Easy.

But what if the dependencies look like this?

0 → 1
↑   ↓
└── 2

Now

0 needs 2
1 needs 0
2 needs 1

Everyone is waiting for someone else.

We can never start.

That is a cycle.

And if there is a cycle, we cannot finish all courses.

Build the Graph

Here is the implementation:

function canFinish(numCourses: number, prerequisites: number[][]): boolean {
  const graph: number[][] = Array.from({ length: numCourses }, () => []);
  const indegree: number[] = Array(numCourses).fill(0);

  for (const [course, prerequisite] of prerequisites) {
    graph[prerequisite].push(course);
    indegree[course]++;
  }

  const queue: number[] = [];
  for (let course = 0; course < numCourses; course++) {
    if (indegree[course] === 0) queue.push(course);
  }

  let completed = 0;
  for (let head = 0; head < queue.length; head++) {
    const course = queue[head];
    completed++;

    for (const next of graph[course]) {
      indegree[next]--;
      if (indegree[next] === 0) queue.push(next);
    }
  }

  return completed === numCourses;
}

There are a few moving parts here.

graph
indegree
queue
completed

This is exactly the kind of algorithm where every individual line makes sense.

but the whole thing can still feel confusing. 😿

Let's break it down.

What Is `graph`?

For

0 → 1 → 2

we want to know

After I finish this course, which courses become closer to being available?

graph[0] = [1]
graph[1] = [2]
graph[2] = []

That means

Finish 0
↓
course 1 is affected

Finish 1
↓
course 2 is affected

We build that here

graph[prerequisite].push(course);

What Is `indegree`?

indegree tells us how many prerequisites a course is still waiting for.

For

0 → 1 → 2

we have

course 0: 0 prerequisites
course 1: 1 prerequisite
course 2: 1 prerequisite

indegree = [0, 1, 1]

Course 0 is special. Because it does not need anything before it.

So we can start there immediately.

Start With Courses That Need Nothing

We build the queue

for (let course = 0; course < numCourses; course++) {
  if (indegree[course] === 0) queue.push(course);
}

For our example

indegree = [0, 1, 1]

Only course 0 has zero prerequisites.

queue = [0]

This means

Course 0 is currently available.

Finish Course 0

Take

course = 0

Then

completed++;

completed = 1

Now look at courses depending on 0.

graph[0] = [1]

Course 1 was waiting for one prerequisite.

But course 0 is now complete.

indegree[1]--;

Then

indegree[1] = 0

Now course 1 needs nothing.

So we add it to the queue.

queue = [0, 1]

Finish Course 1

course = 1

Now

completed = 2

Course 2 depends on 1.

indegree[2]: 1 → 0

Add it to the queue.

queue = [0, 1, 2]

Finish Course 2

Finally

course = 2

completed = 3

And

numCourses = 3

Therefore

completed === numCourses; // true

We can finish everything! 🎉

Why Does This Detect a Cycle?

Now let's try

0 → 1
↑   ↓
└── 2

Every course has one prerequisite.

indegree = [1, 1, 1]

We try to build the initial queue.

if (indegree[course] === 0)

But there is no course with indegree 0.

So, nothing can start.

Therefore

completed = 0

And,

0 === 3 // false

We cannot finish the courses.

Another Example

Suppose

0 → 2
1 → 2
2 → 3

Course 2 needs both 0 and 1.

indegree = [0, 0, 2, 1]

The initial queue is

queue = [0, 1]

Finish 0.

indegree[2]: 2 → 1

Course 2 is still waiting.

So don't add it yet.

Finish 1.

indegree[2]: 1 → 0

Now course 2 is ready.

queue = [0, 1, 2]

Finish 2.

indegree[3]: 1 → 0

Now

queue = [0, 1, 2, 3]

Everything can be completed.

This is the key idea

When all prerequisites for a course are resolved, that course becomes available.

Why Use `head` Instead of `shift()`?

The queue is processed like this

for (let head = 0; head < queue.length; head++) {
  const course = queue[head]

Instead of repeatedly doing

queue.shift();

we keep an index pointing to the next item to process.

So the queue can grow while we iterate through it.

For example

queue = [0]

process 0
↓
queue = [0, 1]

process 1
↓
queue = [0, 1, 2]

head simply moves forward.

0 → 1 → 2
↑
head

Then

0 → 1 → 2
    ↑
   head

Then

0 → 1 → 2
        ↑
       head

Complexity

V = number of courses
E = number of prerequisite relationships

We build the graph once and process every course and edge.

Time: O(V + E)
Space: O(V + E)

👀 Let's View View It

This is probably the most interesting visualization of the three.

Because there are several things changing together.

graph
indegree
queue
head
completed

If I only read

indegree[next]--;
if (indegree[next] === 0) queue.push(next);

I understand the syntax.

But I may still ask:

Why did this course become available now?
Which prerequisite was removed?
Why is this course still not in the queue?
What does completed tell us?
Where exactly does the cycle get stuck?

When we view the runtime, we can watch the dependencies disappear.

0 → 1 → 2

indegree = [0, 1, 1]
queue = [0]

       ↓ finish 0

indegree = [0, 0, 1]
queue = [0, 1]

       ↓ finish 1

indegree = [0, 0, 0]
queue = [0, 1, 2]

       ↓ finish 2

completed = 3

The code stops feeling like mysterious bookkeeping.

We're really doing one simple thing:

Keep taking courses that are ready, and make their dependent courses closer to being ready.

If eventually every course becomes ready

completed === numCourses

there is no blocking cycle.

If some courses never become ready

completed < numCourses

something is stuck in a cycle. 🎓😸

🧠 What Did We Actually Learn?

These three problems look very different.

But each one teaches a useful way of thinking.

Number of Islands

When you find one part of a connected group, explore the entire group before continuing.

What else is connected to this?

Invert Binary Tree

Let recursive calls solve the smaller subtrees first, then transform the current node using their results.

Can my children finish their work before I change this node?

Course Schedule

Process things that have no unresolved dependencies, then use them to unlock more work.

What can I safely process right now?

The implementations are not very long.

But each one introduces a different mental model.

DFS on a grid
Recursive tree transformation
Topological sorting

And once again, the syntax is not really the hardest part.

The difficult part is keeping track of the changing state.

Where are we?
What changed?
What is waiting?
What has already been visited?
Which recursive call are we inside?

Sometimes I can read every line and still lose the thread somewhere in the middle. 😿

That's exactly when I want to view it. 👀👀

🎯 Conclusion

In this article, we looked at:

Number of Islands with recursive grid traversal
Invert Binary Tree with recursion
Course Schedule with topological sorting

And more importantly, we followed what changed while each algorithm was running.

For Number of Islands, we watched connected land disappear as it became visited.

1 → 0

For Invert Binary Tree, we watched recursive calls go down and the tree change while they returned.

go down
↓
come back
↓
swap

For Course Schedule, we watched prerequisites disappear and new courses enter the queue.

indegree--
↓
0 prerequisites
↓
queue.push()

This is exactly the kind of thing I built DSA View View for.

You can write or load a TypeScript implementation, run it with your own inputs, and move backward and forward through the runtime.

If you are learning DSA too, try viewing one of these problems step by step.

Especially when the implementation looks short, but your brain still says

Wait... what just changed? 😿

Seeing the runtime may make the idea much easier to follow.

And if there is a DSA problem you want me to cover next, please let me know in the comments!

I still have many algorithms to learn myself. 😸

Let's train our DSA muscles together! 💪

If you like DSA View View, please give it a star ⭐

nyaomaru / dsa-view-view

DSA View View allows you to understand DSA to see the data flow. 👀👀 Of course, it's free.

DSA View View

DSA View View turns TypeScript algorithm functions into step-by-step visual stories. 👀👀

Write code, run it with structured inputs, and see the arrays, matrices trees, lists, stacks, pointers, and return values move as the function executes.

It is built for those moments when reading the code is not enough and you want to view why the answer changes.

Why Try It?

🧠 Step through real TypeScript
Paste or edit a function, validate it, then run the exact code in the browser.
🧩 Views that match the data
Arrays become bars, matrices become grids, trees become node graphs, linked lists become chains, and two-pointer area problems get their own visual view.
🌳 DSA-friendly inputs out of the box
TreeNode, ListNode, MinHeap, MaxHeap, PriorityQueue, nested arrays matrices, strings, numbers, and class-style inputs are supported without ceremony.
🔎 39 built-in examples
Search by name, browse…

See you in the next article!

Learn Valid Parentheses, Reverse Linked List, and Tree Max Depth with Step-by-Step Visualization in DSA View View 👀👀

nyaomaru — Wed, 26 Aug 2026 14:18:19 +0000

Hoi hoi!

I’m @nyaomaru, a frontend engineer who struggles to make game sounds. 😿

Have you used DSA View View already? 👀👀

Features a timeline to step backward mid-loop

nyaomaru

Jul 15

I Built a Tool to Visualize DSA. Let’s Learn Together! (DSA View View 👀👀)

#showdev #typescript #dsa #react

7 min read

DSA View View allows you to understand DSA by visualizing how your implementation actually runs.

In the previous article, we looked at:

Two Sum
Binary Search
Bubble Sort

Visualizing execution logic changes mental models

nyaomaru

Aug 19

Is Learning DSA Boring? Let's Use DSA View View 👀👀 (Two Sum, Binary Search, and Bubble Sort)

#dsa #typescript #opensource #learning

7 min read

This time, let's try three more classic problems:

Valid Parentheses
Reverse Linked List
Maximum Depth of Binary Tree

These problems introduce three very different ideas:

Stack
Pointer manipulation
Recursion

And all three can become confusing when we only stare at the final code.

So let's view what actually happens. 👀

I'm still learning DSA too, so let's learn together! 😸

🥞 Valid Parentheses

Let's start with Valid Parentheses.

Suppose we have this string:

()[]{}

Every opening bracket has a matching closing bracket.

So this is valid. ✅

But this

([)]

is not valid. ❌

Why?

Because the brackets close in the wrong order.

(
  [
)
  ]

The [ should be closed before the (.

So how can we keep track of that order?

Use a Stack

A stack follows a simple rule:

The last thing we put in is the first thing we take out.

This is called LIFO (Last In / First Out)

Imagine stacking plates.

    🍽️  ← remove first
    🍽️
    🍽️

The last plate we put on top is the first one we can take.

Parentheses work in the same way.

If we see:

(
[
{

then the brackets must close in reverse order

}
]
)

So a stack is a very natural fit.

Here is the implementation:

function isValid(s: string): boolean {
  const stack: string[] = [];

  const pairs: Record<string, string> = {
    ")": "(",
    "]": "[",
    "}": "{",
  };

  for (const char of s) {
    if (char === "(" || char === "[" || char === "{") {
      stack.push(char);
      continue;
    }

    if (stack.length === 0) return false;

    const target = stack.pop();
    if (target !== pairs[char]) {
      return false;
    }
  }

  return stack.length === 0;
}

The important part is what happens to stack.

Let's use

([])

At first

stack = []

We see

It's an opening bracket.

Push it.

stack = ["("]

Next,

Push again.

stack = ["(", "["]

Then,

This is a closing bracket.

What should it close?

And what is currently on top of the stack?

Perfect. ✅

So we remove it.

stack = ["("]

Finally,

It should close

The top of the stack is also

Pop!

stack = []

We reached the end with an empty stack.

Valid! 🎉

What About an Invalid Example?

Consider

([)]

We start the same way.

(
↓
stack = ["("]

[
↓
stack = ["(", "["]

Then we find

A ) needs

But the top of our stack is

They don't match.

expected: (
actual:   [

So we immediately know the string is invalid.

Complexity

We walk through the string once.

Time:  O(n)
Space: O(n)

In the worst case, the stack may contain all opening brackets.

👀 Let's View View It

This is where the stack becomes much easier to understand.

When we only read.

stack.push(char);

And

stack.pop();

It can be easy to lose track of what is actually inside the stack.

Especially with something like.

({[]})

What is on top right now?

Which opening bracket are we trying to close?

Instead of remembering everything in our head, we can follow the stack changing step by step.

Conceptually, we can see:

(
↓
[(]

{
↓
[(, {]

[
↓
[(, {, []

]
↓
[(, {]

}
↓
[(]

)
↓
[]

That's the whole idea.

Remember the opening brackets, and always match the most recent one first.

Stack suddenly feels much less mysterious. 🥞😸

🔗 Reverse Linked List

Next, let's reverse a linked list.

Suppose we have

1 → 2 → 3 → 4 → 5

We want

5 → 4 → 3 → 2 → 1

At first glance, this sounds simple.

Just reverse it!

But linked lists are a little different from arrays.

With an array, the values live in positions like

0  1  2  3  4
↓  ↓  ↓  ↓  ↓
1  2  3  4  5

A linked list instead consists of nodes pointing to the next node.

1 → 2 → 3 → 4 → 5 → null

Each arrow matters. To reverse the list, we need to reverse those arrows.

1 ← 2 ← 3 ← 4 ← 5

And this is where things can get confusing.

Because if we change an arrow too early...

we may lose the rest of the list. 😿

Three Important Variables

A common iterative solution uses three variables

prev
current
next

Here is the implementation:

function reverseList(head: ListNode | null): ListNode | null {
  let prev: ListNode | null = null;
  let current = head;

  while (current !== null) {
    const next = current.next;

    current.next = prev;

    prev = current;
    current = next;
  }

  return prev;
}

It's short.

But there is a lot happening inside these few lines.

Let's follow it carefully.

We start with

1 → 2 → 3 → null

And

prev = null
current = 1

Step 1: Save the Next Node

First

const next = current.next;

next = 2

Why do we need this?

Because we're about to change

1 → 2

If we change that arrow without remembering 2, we lose access to the rest of the list.

So first

Save where we need to go next.

Step 2: Reverse the Arrow

Now

current.next = prev;

Originally

1 → 2

But prev is

null

So now

1 → null

The first arrow has been reversed.

Step 3: Move `prev`

prev = current;

prev = 1

Step 4: Move `current`

Finally

current = next;

We saved 2 earlier.

So now

current = 2

Our state looks like this

null ← 1    2 → 3 → null
       ↑    ↑
      prev current

Then we do exactly the same thing again.

Save:

next = 3

Reverse

2 → 1

Move

prev = 2
current = 3

Now

null ← 1 ← 2    3 → null
           ↑    ↑
          prev  current

One more time

next = null

Reverse

3 → 2

Move

prev = 3
current = null

And now

null ← 1 ← 2 ← 3
               ↑
              prev

The loop stops because

current === null

And prev is the new head.

return prev;

Done! 🎉

Complexity

We visit each node once.

Time:  O(n)
Space: O(1)

We don't create another linked list.

We only move a few pointers.

👀 Let's View View It

This is exactly the kind of code that I find difficult to understand by reading alone.

These four lines:

const next = current.next;
current.next = prev;
prev = current;
current = next;

look simple.

But when I first see code like this, my brain starts asking.

Wait.

- Where is current now?
- Did we lose next?
- Which arrow changed?
- What exactly does prev point to?

😿

When we visualize each step, we can actually follow the pointers moving.

prev      current
 ↓           ↓
null         1 → 2 → 3

      ↓↓↓

null ← 1     2 → 3
       ↑     ↑
      prev current

      ↓↓↓

null ← 1 ← 2     3
           ↑     ↑
          prev current

      ↓↓↓

null ← 1 ← 2 ← 3
               ↑
              prev

The algorithm becomes much simpler when we stop thinking of it as four mysterious assignments.

It's really just

Save next
  ↓
Reverse arrow
  ↓
Move prev
  ↓
Move current
  ↓
Repeat

Nice! 🔗😸

🌳 Maximum Depth of Binary Tree

Finally, let's look at a tree.

Consider this binary tree.

What is its maximum depth?

The longest path from the root to a leaf contains three nodes:

So the answer is.

How can we calculate that?

Think About a Smaller Tree

Suppose we are standing at one node.

We don't really need to understand the entire tree at once.

We only need to ask.

How deep is the left subtree?

How deep is the right subtree?

Then choose the larger one.

And add 1 for the current node.

That's exactly what this implementation does.

function maxDepth(root: TreeNode | null): number {
  if (root === null) {
    return 0;
  }

  const leftDepth = maxDepth(root.left);
  const rightDepth = maxDepth(root.right);

  return Math.max(leftDepth, rightDepth) + 1;
}

The important idea is

Math.max(leftDepth, rightDepth) + 1;

But recursion can feel strange.

When we call

maxDepth(root.left);

where does the current function go?

And how do all those calls eventually become one number?

Let's follow a small example.

We start at

But before 1 can know its depth, it asks its left child

maxDepth(2)

Node 2 asks

maxDepth(4)

Node 4 has no children.

So both sides eventually reach

null

And

maxDepth(null);

returns

Therefore node 4 can calculate

max(0, 0) + 1
= 1

Now we return to node 2.

Its left side has depth

Its right side is null

max(1, 0) + 1
= 2

Now return to node 1.

Eventually its right subtree also returns

So node 1 gets

leftDepth = 2
rightDepth = 1

And calculates

max(2, 1) + 1
= 3

Answer

🎉

The Interesting Part: Going Down and Coming Back Up

This is what makes recursion interesting.

First, the function calls go down the tree.

1
↓
2
↓
4
↓
null

But the answers are built while returning back up.

null → 0
4    → 1
2    → 2
1    → 3

So recursion isn't only

Keep calling the same function.

There are really two directions.

Go down
  ↓
Reach the base case
  ↓
Return values back up

The base case here is

if (root === null) {
  return 0;
}

Without it, the recursion would have no place to stop.

Complexity

Every node is visited once.

Time: O(n)

The recursive call stack depends on the height of the tree.

Space: O(h)

where h is the height of the tree.

For a balanced tree, that is roughly

O(log n)

In the worst case, if the tree looks like a linked list

the depth can become

O(n)

👀 Let's View View It

Recursion is probably my favorite example for visualization.

Because the final implementation is tiny

const leftDepth = maxDepth(root.left);
const rightDepth = maxDepth(root.right);

return Math.max(leftDepth, rightDepth) + 1;

But a lot is hidden inside those function calls.

When reading the code, it can feel like

maxDepth()
inside maxDepth()
inside maxDepth()
inside maxDepth()
...

Where are we now? 😿

When we step through the execution, we can follow both parts

Going down

1
↓
2
↓
4
↓
null

and then

Coming back

null → 0
↓
4 → 1
↓
2 → 2
↓
1 → 3

That makes the recursive idea much easier to see.

Ask the smaller subproblems for their answers, then use those answers to build the current answer.

🌳😸

🧠 What Did We Actually Learn?

These three problems look completely different.

But each one introduces a very useful way of thinking.

Valid Parentheses

Use a stack when the most recent item needs to be handled first.

What was the last thing I opened?

Reverse Linked List

When changing references, save what you still need before breaking the old connection.

Where do I need to go next before I change this pointer?

Maximum Depth of Binary Tree

Break a problem into smaller versions of the same problem.

Can I get the answers from my children and build my answer from them?

This is one reason I like learning these problems together.

The implementations are not very large.

But each one introduces a completely different mental model

Stack
Pointer
Recursion

And those mental models are much harder to learn than the syntax itself.

Sometimes the code tells us what happens.

But I also want to see how it happens.

I want to view it. 👀👀

🎯 Conclusion

In this article, we looked at:

Valid Parentheses with a stack
Reverse Linked List with pointer manipulation
Maximum Depth of Binary Tree with recursion

And more importantly, we followed the state while each algorithm was running.

We watched change the stack.

stack.push() / stack.pop()

We watched move through a linked list.

prev
current
next

And we watched recursive calls travel down a tree and return their answers back up.

This is exactly the kind of thing I built DSA View View for.

You can write or load a TypeScript implementation, run it with your own inputs, and move backward and forward through the runtime.

If you are learning DSA too, try viewing one of these problems step by step.

Especially if a solution feels like

I understand every line individually... but somehow I still don't understand the whole thing. 😿

Seeing the runtime may connect those pieces together.

And if there is a DSA problem you want me to cover next, please let me know in the comments!

I still have many algorithms to learn myself. 😸

Let's train our DSA muscles together! 💪

If you like DSA View View, please give it a star ⭐

nyaomaru / dsa-view-view

DSA View View allows you to understand DSA to see the data flow. 👀👀 Of course, it's free.

DSA View View

DSA View View turns TypeScript algorithm functions into step-by-step visual stories. 👀👀

Write code, run it with structured inputs, and see the arrays, matrices trees, lists, stacks, pointers, and return values move as the function executes.

It is built for those moments when reading the code is not enough and you want to view why the answer changes.

Why Try It?

🧠 Step through real TypeScript
Paste or edit a function, validate it, then run the exact code in the browser.
🧩 Views that match the data
Arrays become bars, matrices become grids, trees become node graphs, linked lists become chains, and two-pointer area problems get their own visual view.
🌳 DSA-friendly inputs out of the box
TreeNode, ListNode, MinHeap, MaxHeap, PriorityQueue, nested arrays matrices, strings, numbers, and class-style inputs are supported without ceremony.
🔎 39 built-in examples
Search by name, browse…

See you in the next article!

Is Learning DSA Boring? Let's Use DSA View View 👀👀 (Two Sum, Binary Search, and Bubble Sort)

nyaomaru — Wed, 19 Aug 2026 14:43:44 +0000

Hoi hoi!

I’m @nyaomaru, a frontend engineer who dislikes crowded places, so I'm planning to take a quiet vacation in September. 🏝️

Have you used DSA View View already? 👀👀

Features a timeline to step backward mid-loop

nyaomaru

Jul 15

I Built a Tool to Visualize DSA. Let’s Learn Together! (DSA View View 👀👀)

#showdev #typescript #dsa #react

7 min read

DSA View View allows you to understand DSA by visualizing how your implementation actually runs.

But just introducing the tool is not enough.

Can it actually help us understand DSA?

In this article, we'll walk through three classic problems:

Two Sum
Binary Search
Bubble Sort

We'll first understand the algorithm, and then see what is actually happening with DSA View View.

Let's learn together! 😸

🗺️ Two Sum

Let's start with a very famous problem.

Given an array of numbers and a target value, find the indices of two numbers whose sum equals the target.

For example,

nums = [2, 7, 11, 15];
target = 9;

The answer is

[0, 1];

Because

2 + 7 = 9

Simple!

So, how should we find them? 🤔

Brute Force

The easiest approach is probably checking every possible pair.

function twoSum(nums: number[], target: number): number[] {
  for (let i = 0; i < nums.length; i++) {
    for (let j = i + 1; j < nums.length; j++) {
      if (nums[i] + nums[j] === target) {
        return [i, j];
      }
    }
  }

  return [];
}

This works.

But if the array becomes large, we may need to compare a lot of pairs, right?

The time complexity is O(n²)

Can we avoid checking the same values again and again?

Yes.

Let's use a Map.

function twoSum(nums: number[], target: number): number[] {
  const seen = new Map<number, number>();

  for (let i = 0; i < nums.length; i++) {
    const current = nums[i];
    const need = target - current;

    if (seen.has(need)) {
      return [seen.get(need)!, i];
    }

    seen.set(current, i);
  }

  return [];
}

The important part is this 👇

const need = target - current;

Instead of asking

Which two numbers should I combine?

we ask

What number do I need to complete the target?

Let's follow the example.

At first

current = 2
target = 9

need = 9 - 2
     = 7

Have we already seen 7?

No.

So we remember 2.

seen = {
  2 → 0
}

current = 7
target = 9

need = 9 - 7
     = 2

Have we already seen 2?

Yes! 👀👀

seen = {
  2 → 0
}

return [0, 1];

Done!

Because we only need to walk through the array once, the time complexity becomes.

Time:  O(n)
Space: O(n)

👀 Let's View View It

The implementation is quite small.

But when I was first learning this pattern, this part still felt a little magical.

if (seen.has(need))

Where did need come from?
What is inside seen at this moment?
Why does checking the previous values solve the problem?

This is exactly where visualization helps.

With DSA View View, we can move through the runtime one step at a time and inspect how the values change.

2
↓
Need 7
↓
Remember 2
↓
7
↓
Need 2
↓
Found 2!
🎉

Now the Map is not just some mysterious trick.

We can actually follow the idea.

Remember what we have already seen, and check whether the value we need is there.

Nice! 😸

🔍 Binary Search

Next is Binary Search.

Suppose we have this sorted array

[1, 3, 5, 7, 9, 11, 13]

And we want to find

Of course, we could start from 1 and check every number.

1 → 3 → 5 → 7 → 9 → 11

That works.

But Binary Search does something smarter.

Instead of checking from the beginning, it checks the middle.

[1, 3, 5, 7, 9, 11, 13]
          ↑
         mid

Our middle value is 7.

We are looking for 11.

11 > 7

Because the array is sorted, we already know something very useful.

Everything on the left side of 7 is also smaller than 11.

So, we don't need that half anymore. 👋

[1, 3, 5, 7, 9, 11, 13]
             └───────┘
               search

Now we check the middle of the remaining range.

[9, 11, 13]
     ↑
    mid

And

11 === 11

Found it! 🎉

Here is the implementation.

function binarySearch(nums: number[], target: number): number {
  let left = 0;
  let right = nums.length - 1;

  while (left <= right) {
    const mid = Math.floor((left + right) / 2);

    if (nums[mid] === target) {
      return mid;
    }

    if (nums[mid] < target) {
      left = mid + 1;
    } else {
      right = mid - 1;
    }
  }

  return -1;
}

There are three important variables.

left
right
mid

They represent the current search range.

For our example, they start like this

left = 0
right = 6
mid = 3

[1, 3, 5, 7, 9, 11, 13]
 ↑        ↑          ↑
left     mid       right

Because

nums[mid] < target;

we move left.

left = mid + 1;

Now

[1, 3, 5, 7, 9, 11, 13]
             ↑   ↑   ↑
           left mid right

And 11 is found.

Why Is Binary Search Fast?

This is the interesting part.

Each step removes about half of the remaining candidates.

If there are 1,000 values, we don't necessarily need 1,000 checks.

It becomes roughly

1000
↓
500
↓
250
↓
125
↓
...

That's why Binary Search has

Time:  O(log n)
Space: O(1)

But there is one very important condition.

The data must be sorted.

Without sorted data, we cannot safely throw away half of the search range.

👀 Let's View View It

Binary Search is one of the algorithms that made me want a visualization tool in the first place.

The code itself is short

left = mid + 1;

right = mid - 1;

Easy.

But when learning it, I sometimes found myself thinking:

Wait... which part are we searching now? 😿

When we visualize left, mid, and right, the idea becomes much easier to follow.

We are not randomly changing three numbers.

We are continuously shrinking the search area.

███████████████

       ↓

        ███████

       ↓

          ███

       ↓

           █

That's Binary Search!

Cut the unnecessary half.

Then cut it again. And again. And again.

Until we find the answer. ✂️😸

🫧 Bubble Sort

Finally, let's sort something!

Consider this array.

[5, 1, 4, 2, 8];

We want.

[1, 2, 4, 5, 8];

Bubble Sort repeatedly compares two neighboring values.

If they are in the wrong order, it swaps them.

Let's look at the beginning.

[5, 1, 4, 2, 8]
 ↑  ↑

Compare

5 > 1

So swap them.

[1, 5, 4, 2, 8]

[1, 5, 4, 2, 8]
    ↑  ↑

Again

5 > 4

Swap!

[1, 4, 5, 2, 8]

And continue.

[1, 4, 5, 2, 8]
       ↑  ↑

5 > 2

Swap!

[1, 4, 2, 5, 8]

Eventually, larger values move toward the end of the array.

They kind of...

bubble up. 🫧

That's why it is called Bubble Sort.

Here is a simple implementation:

function bubbleSort(nums: number[]): number[] {
  for (let i = 0; i < nums.length - 1; i++) {
    for (let j = 0; j < nums.length - i - 1; j++) {
      if (nums[j] > nums[j + 1]) {
        [nums[j], nums[j + 1]] = [nums[j + 1], nums[j]];
      }
    }
  }

  return nums;
}

We repeatedly compare

nums[j];

And

nums[j + 1];

and swap them when necessary.

After one full pass, the largest remaining value reaches its correct position near the end.

So on the next pass, we don't need to check that position again.

That's why the inner loop contains.

nums.length - i - 1;

Complexity

Bubble Sort isn't very fast for large arrays.

Its time complexity is

Time:  O(n²)
Space: O(1)

So I probably won't suddenly replace production sorting with Bubble Sort tomorrow. 😸

But as a learning example, I really like it.

Why?

Because you can see the algorithm working.

👀 Let's View View It

This is probably the most visually satisfying one of the three.

Instead of only reading

[nums[j], nums[j + 1]] = [nums[j + 1], nums[j]];

we can follow the values moving through the array.

[5, 1, 4, 2, 8]

 ↓ swap

[1, 5, 4, 2, 8]

    ↓ swap

[1, 4, 5, 2, 8]

       ↓ swap

[1, 4, 2, 5, 8]

Then another pass begins.

The code contains nested loops, indexes, comparisons, and swaps.

But visually, the basic rule is extremely simple:

Compare neighbors. If the left one is bigger, swap them.

Repeat. Repeat. Repeat.

Sorted! 🎉

🧠 What Did We Actually Learn?

These three problems look quite different.

But each one introduces a useful way of thinking.

Two Sum

Remember information from previous steps.

Have I already seen what I need?

Binary Search

Use what we already know to remove impossible candidates.

Can I safely discard half of the search space?

Bubble Sort

Break a larger problem into many small comparisons.

Are these two values in the correct order?

This is one of the things I find interesting about learning DSA.

At first, the implementation can look like a collection of indexes, loops, conditions, and mysterious variables.

But behind the code, there is usually a much simpler idea.

And sometimes I don't fully understand that idea just by staring at the code.

I want to view it. 👀👀

🎯 Conclusion

In this article, we looked at three classic algorithms:

Two Sum with a Map
Binary Search
Bubble Sort

And more importantly, we looked at how the data changes while they run.

I think this is where visualization can be especially useful.

Reading the final implementation tells us what the code is.
Stepping through it helps us understand why it works.

That's exactly why I built DSA View View.

You can write or load a TypeScript implementation, run it with your own inputs, and move backward and forward through the runtime.

If you are learning DSA too, try taking a problem you already solved and viewing it step by step.

You may notice something you didn't notice when only reading the code. 👀

And if there is a DSA problem you want me to cover next, please let me know in the comments!

I still have many algorithms to learn myself. 😸

Let's train our DSA muscles together! 💪

If you like DSA View View, please give it a star ⭐

nyaomaru / dsa-view-view

DSA View View allows you to understand DSA to see the data flow. 👀👀 Of course, it's free.

DSA View View

DSA View View turns TypeScript algorithm functions into step-by-step visual stories. 👀👀

Write code, run it with structured inputs, and see the arrays, matrices trees, lists, stacks, pointers, and return values move as the function executes.

It is built for those moments when reading the code is not enough and you want to view why the answer changes.

Why Try It?

🧠 Step through real TypeScript
Paste or edit a function, validate it, then run the exact code in the browser.
🧩 Views that match the data
Arrays become bars, matrices become grids, trees become node graphs, linked lists become chains, and two-pointer area problems get their own visual view.
🌳 DSA-friendly inputs out of the box
TreeNode, ListNode, MinHeap, MaxHeap, PriorityQueue, nested arrays matrices, strings, numbers, and class-style inputs are supported without ceremony.
🔎 39 built-in examples
Search by name, browse…

And my DSA View View has launched at TinyLaunch! 🚀 Please take a loot 👇

tinylaunch.com

See you in the next article!

is-kit Reached 50 Stars ⭐ Here’s How We Use It in Production

nyaomaru — Wed, 12 Aug 2026 13:16:48 +0000

Hoi hoi!

I'm @nyaomaru, a frontend engineer who is trying to lose weight. 🐖🙀

I maintain a type guard library, is-kit.

I spend an unreasonable amount of time asking

“But what if this value is actually unknown???”

Recently, is-kit crossed 50 GitHub stars 🎉🎉🎉

A star is not a benchmark. And 50 stars do not suddenly make a library production-ready.

But each one still means

“Someone found this idea useful.”

That makes me very happy!! Each star gives me more motivation to keep improving the library!!!!

There is also something more concrete I want to share

is-kit is now used in a production TypeScript application serving more than 100,000 users. 🚀

This article explains:

What problem we had
How we introduced is-kit
What actually changed
Where it is used today
What its practical advantages are

Let's dive in!

📋 The Problem Was Not “Validation”

The application already had many small checks like 👇

typeof value === "string";
typeof value === "number";
value === null || value === undefined;

It also had user-defined type guards for:

HTTP client errors
Status codes
Literal unions
Arrays
Plain objects
Values coming from JSON or API responses

Each check was reasonable by itself.

The problem appeared when they started repeating.

For example, several error guards had almost the same structure.

type HttpClientError<T = unknown> = Error & {
  isHttpClientError: true;
  response?: {
    status: number;
    data: T;
  };
};

function isUnauthorizedError(error: unknown): error is HttpClientError {
  return (
    !!error &&
    (error as HttpClientError).isHttpClientError === true &&
    (error as HttpClientError).response?.status === 401
  );
}

function isValidationError(error: unknown): error is HttpClientError {
  return (
    !!error &&
    (error as HttpClientError).isHttpClientError === true &&
    (error as HttpClientError).response?.status === 422
  );
}

This works.

But it has three practical problems:

The same base check is repeated
Assertion casts appear inside every guard
Adding another status means adding another copy

The code was not broken.

It was simply asking for a reusable abstraction. 🔧

🏃‍♂️ The Production Pattern

We replaced the repeated checks with small composable guards.

Here is a business-neutral version of the production pattern.

import { define, equalsKey, or } from "is-kit";

type HttpClientError<T = unknown> = Error & {
  isHttpClientError: true;
  code?: string;
  response?: {
    status: number;
    data: T;
  };
};

const isHttpClientError = define<HttpClientError>((value) =>
  equalsKey("isHttpClientError", true)(value),
);

const isHttpErrorWithStatus = (status: number) =>
  define<HttpClientError>(
    (value) => isHttpClientError(value) && value.response?.status === status,
  );

export const isUnauthorizedError = isHttpErrorWithStatus(401);

export const isValidationError = isHttpErrorWithStatus(422);

const hasTimeoutCode = define<HttpClientError>(
  (value) => isHttpClientError(value) && value.code === "TIMEOUT",
);

const hasTimeoutMessage = define<HttpClientError>(
  (value) => isHttpClientError(value) && value.message.includes("timed out"),
);

export const isTimeoutError = or(hasTimeoutCode, hasTimeoutMessage);

There are a few important details here.

`define`

define<T> turns a runtime boolean check into a reusable predicate.

const isHttpErrorWithStatus = (status: number) =>
  define<HttpClientError>(...);

The responsibility is still ours. The runtime check must actually prove T.

is-kit cannot make an incorrect predicate correct.

But it gives custom guards one consistent shape.

`equalsKey`

The base error is not plain JSON.

It is an error instance with a marker property.

So a plain-object schema is not the right abstraction here.

equalsKey("isHttpClientError", true) expresses exactly what we need,

“This value owns this key, and its value is exactly true.”

`or`

A timeout can be detected in more than one way.

Instead of creating another large conditional, we compose two reusable guards.

const isTimeoutError = or(hasTimeoutCode, hasTimeoutMessage);

That is the core idea of is-kit,

Build small guards, then compose them.

✨ What Actually Changed

The first adoption refactor was not just 👇

pnpm add is-kit

It changed the structure of the guard layer.

Observable result	Change
Error guards	7 separate modules became 1 shared module
Adoption diff	335 lines added, 584 removed
Net diff	249 fewer lines
Direct imports today	`is-kit` is isolated to 7 app helper modules
App reach today	Those helpers are consumed by 39 non-test source files

The diff includes rewritten tests and helper adapters, so 249 fewer lines is not a claim that a library magically deletes code.

It is the measured result of that specific consolidation.

The more important change is the shape.

is-kit primitives
       ↓
app guard helpers
       ↓
features, routes, services, and UI

The production application does not import is-kit from every component.

Instead, most call sites use application-owned helpers.

🤔 Why Keep an Application Boundary?

For primitives, the application wraps or re-exports the library guards 👇

import {
  isNumber as isFiniteNumberGuard,
  isNumberPrimitive,
  isString as isStringGuard,
} from "is-kit";

export const isString = isStringGuard;
export const isNumber = isNumberPrimitive;
export const isFiniteNumber = isFiniteNumberGuard;

This looks like a small detail, but it is an important design choice.

JavaScript has more than one useful meaning for “number”.

typeof NaN === "number";
typeof Infinity === "number";

In the application:

isNumber follows primitive typeof semantics
isFiniteNumber rejects NaN and Infinity

The application owns those names. is-kit provides the reusable implementation.

This boundary also means:

Call sites do not depend on library naming decisions
Semantics stay consistent across the app
A future migration has one clear place to start

This is how I prefer to introduce small libraries into large applications.

Adopt them behind a local vocabulary.

😎 Other Real Usage Patterns

The HTTP error guards are the largest example, but not the only one.

Arrays

import { arrayOf, isNumberPrimitive } from "is-kit";

export const isNumberArray = arrayOf(isNumberPrimitive);

This replaces

const isNumberArray = (value: unknown): value is number[] =>
  Array.isArray(value) &&
  value.every((item): item is number => typeof item === "number");

Literal unions

import { oneOfValues } from "is-kit";

const VIEW_MODES = ["compact", "comfortable"] as const;

const isViewMode = oneOfValues(VIEW_MODES);

declare const input: unknown;

if (isViewMode(input)) {
  // "compact" | "comfortable"
  input;
}

Nullish values

import { isNull, isUndefined, or } from "is-kit";

export const isNullish = or(isNull, isUndefined);

Because this is a function, it can be reused directly.

const definedItems = items.filter((item) => !isNullish(item));

The current application uses the same idea for:

Error branching
JSON and API-derived values
Filtering nullable collections
Literal-value checks
UI values that may be strings or other renderable values

This is what production usage looks like in practice.

not one giant schema,
but many small decisions at normal control-flow points.

🚀 The Practical Advantages

After using it in the application, the advantages became clearer.

1. Incremental adoption

We did not need to redesign the data layer.

A check like

typeof value === "string";

can become

isString(value);

And later, if reuse becomes useful.

values.filter(isString);

2. Less assertion casting

The old error guards repeatedly used

error as HttpClientError;

The composed version narrows once, then accesses the narrowed value normally

isHttpClientError(value) && value.response?.status === status;

3. Shared runtime semantics

Questions like these now have explicit answers:

Does “number” include NaN?
Does this object check accept class instances?
Is this field optional, nullable, or both?
Are two values compared with === or Object.is semantics?

The benefit is not shorter syntax alone.

It is fewer slightly-different answers across the codebase.

4. Normal TypeScript control flow

The result is still a function.

if (isValidationError(error)) {
  error.response?.data;
}

No parse result is required.

No schema object has to travel through the application.

That makes the guards easy to use in:

if
filter
event handlers
error boundaries
utility functions

5. Small dependency surface

is-kit has no runtime dependencies.

That does not mean it has zero bundle cost.

It means introducing it does not bring a tree of transitive runtime packages with it.

👮 It Became a Team Rule

One sign of real adoption is that the library moved beyond individual preference.

The production repository now has a contributor rule:

When combining is-kit guards,
prefer or, and, andAll, nullish, and related combinators
instead of rebuilding the same composition with native operators.

For example,

const isTextOrNumber = or(isString, isNumberPrimitive);

instead of,

const isTextOrNumber = (value: unknown) =>
  isString(value) || isNumberPrimitive(value);

Both can return the same boolean.

But the first version is a named, reusable guard that can be passed around and composed again.

This rule is also used by coding agents working in the repository.

That matters because a tool is not truly adopted if every contributor, human or AI, invents a different style.

✖️ What We Cannot Claim

I want to be careful here.

We did not run a controlled study showing that is-kit:

Improved runtime performance
Reduced production incidents
Made every validation task easier

So I will not claim those things.

The effects we can actually see are:

Repeated guards were consolidated
Assertion heavy checks became composable predicates
Primitive semantics became centralized
Application code gained reusable narrowing functions
The pattern became part of the repository guidelines

This is primarily a maintainability and type-safety improvement. 🏋️‍♂️

👀 Why Not Use a Schema Library?

For these call sites, we did not need:

Rich validation error trees
Data transformations
A schema-first model

We needed

“Can this unknown value safely enter this branch?”

That is exactly where a type guard fits.

For forms, API contracts, or detailed validation errors, a schema library such as Zod may still be the better tool.

They solve different problems.

🎯 What 50 Stars Means to Me

50 stars is small compared with the largest TypeScript libraries.

But OSS does not become meaningful only after thousands of stars.

For me, this milestone means:

People outside the project understand the idea
The API is useful beyond a toy example
The library is solving a real maintenance problem
There is still a lot to improve

And the production application gives the milestone some weight.

is-kit is not only being starred.

It is currently helping real application code answer:

“What is this value, and can TypeScript trust it?”

Thank you to everyone who starred, tested, reported an issue, or simply looked at the repository.

If small composable type guards fit your TypeScript style, give it a try 👇

nyaomaru / is-kit

Build small guards. Compose them. Lightweight, zero-dependency TypeScript type guards for runtime validation and natural narrowing. Runtime-safe 🛡️, composable 🧩, and ergonomic ✨.

is-kit

Build small guards. Compose them.

is-kit is a lightweight, zero-dependency toolkit for building reusable TypeScript type guards.

It helps you write small isFoo functions, compose them into richer runtime checks, and keep TypeScript narrowing natural inside regular control flow.

Runtime-safe 🛡️, composable 🧩, and ergonomic ✨ without asking you to adopt a heavy schema workflow.

Build and reuse typed guards
Compose guards with and, or, not, oneOf
Validate object shapes and collections
Parse or assert unknown values without a large schema framework

Best for app-internal narrowing, filtering, and reusable guards.

🤔 Why use `is-kit`?

Tired of rewriting the same isFoo checks again and again?

is-kit is a good fit when you want to:

write reusable isX functions instead of one-off inline checks
keep runtime validation lightweight and dependency-free
narrow values directly in if, filter…