DEV Community: nyaomaru

Cat Mutilation Successful!! 🛸 Welcome New Members!! 🐈🎉

nyaomaru — Sun, 15 Nov 2026 10:01:42 +0000

Hoi hoi! 👋

Last week, we launched the Necoz organization here on DEV!

Necoz Follow

Necoz is a friendly open-source community building small, simple, and useful tools for developers. 🐈 Everyone is welcome, from first-time contributors to experienced engineers. Let's build something awesome together! 😸

And guess what?

28 cats have already joined us!!! 🙀🎉

YAYYYYY!!! 💚

A huge thank you to everyone who joined!

Apparently, DEV only allows up to 10 mentions per article, so I've listed everyone using profile links instead. 🙀💚

But now that we've captured all these cats,

Where are we going to take them? 👀

Hehehe... We're building something behind the scenes. Stay tuned! 🐈🛸

🏆 New Contributors, Good Cats 😺😺😺

This week, we've had some awesome contributors joining our projects!

GOOD CATS!!! 😻🎉

Since this is our first weekly report, we're also celebrating everyone who contributed before this week!

So far, 35 amazing cats have contributed 71 merged pull requests across our projects! 🐈🎉

🧩 is-kit

necoz-oss / 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…

View on GitHub

Aaqibhafeezkhan — Improved oneOf evaluation and short-circuit tests. (#385)
AmirAbaris — Strengthened refineKey type-level tests. (#372)
BoteroAlejandro11 — Improved mapOf short-circuit tests. (#416)
Doomguy-BFG9000 — Improved lazy predicate caching tests. (#392)
GyulianoDev — Improved array guard short-circuit tests. (#414)
Pratham2511 — Expanded sparse array and parsing edge-case coverage. (#393, #384)
crims0n — Improved predicateToRefine test coverage. (#386)
diyaryavuz — Expanded refinement and tupleOf edge-case tests. (#397, #377)
guhcostan — Improved safeParse documentation. (#370)
nuriadevs — Clarified isNumber documentation. (#371)
painbaba — Fixed literal narrowing behavior in oneOfValues. (#400)
psjdeveloper — Improved define predicate coverage. (#394)
saimskywalker — Fixed an edge case in isPlainObject. (#406)
srijavuppala — Strengthened assert runtime guard tests. (#417)
tridev-tej — Improved safeJsonParse error propagation tests. (#431)
tylrcc — Improved runtime guard tests and compatibility documentation. (#426, #425, #424, #423, #422)

🤖 changelog-bot

necoz-oss / 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.

The GitHub repository is necoz-oss/changelog-bot. The npm package name is still @nyaomaru/changelog-bot. In workflows, use necoz-oss/changelog-bot. GitHub Actions does not follow repository redirects for actions or reusable workflows, so keep uses: on the new owner. Web and git URLs for nyaomaru/changelog-bot still redirect.

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…

View on GitHub

19algorythms — Added a Jest coverage script. (#299)
Anantha-K — Fixed release version handling during changelog generation. (#251)
GyulianoDev — Improved CLI error messages. (#307)
KingEmma7 — Improved runtime validation using shared guards. (#265)
Mayank-jaiswal13 — Refactored PR lookup logic and improved test maintainability. (#327, #306)
MayurK-cmd — Expanded compare link generation tests. (#326)
Prashaxt — Added JSON schema support and improved GitHub API tests. (#288, #274)
Satorino01 — Expanded test coverage for repeated compare link updates. (#348)
WebWizard5243 — Reduced duplication in metadata diagnostics. (#325)
dbdefault — Simplified runtime validation using is-kit predicates, fixed PR linking inside fenced code blocks, and expanded title lookup and metadata fallback test coverage. (#352, #351, #349, #345, #342)
enidchen0125 — Improved repository configuration validation. (#339)
erSpell — Improved WHY extractor test coverage. (#276)
jay23606 — Improved changelog file error handling. (#272)
johnnylemonny — Contributed extensively to WHY extraction, evaluation, GitHub metadata handling, output delivery, Grok support, security, cross-platform compatibility, and much more! (View contributions)
mangomac — Expanded release Markdown test coverage. (#275)
noahkhomer18 — Fixed duplicate changelog bullet handling. (#324)
sorathiya903 — Added practical output destination examples. (#309)
tylrcc — Reduced code duplication across metadata, changelog utilities, and diagnostics. (#318, #317, #316)
xryanlee — Improved documentation on how to claim an issue. (#330)

🦀 type-tune

necoz-oss / type-tune

A Rust-powered CLI to find shared TypeScript types and move them safely. 🦀

type-tune

Give shared TypeScript types a better home. 😸

Scan. Review. Move. Validate.

type-tune is a Rust-powered CLI that finds shared TypeScript type aliases and interface declarations and helps move them without manually chasing imports.

It creates a reviewable plan, updates supported type imports and re-exports, and validates the rewrite with TypeScript. You decide what moves and where.

Guides for installation, the first scan, and the review workflow live in the official documentation. Releases are listed on GitHub Releases, and the package is type-tune on npm.

Why type-tune?

Types often start next to a component or utility, then end up shared across a project. Moving them later means tracking imports, local dependencies, and barrels by hand.

Discover shared types with deterministic candidate IDs.
Review plan.md and choose the destination before making changes.
Rewrite supported type-only imports, aliases, and simple barrels while keeping compatibility re-exports at the original…

View on GitHub

ViviBeri — Improved test coverage for aliased mixed imports through barrel re-exports. (#23)

Thank you so much for your contributions! 💚

Remember, no contribution is too small!

Code, tests, documentation, bug reports, ideas, or even a simple question. Everything is welcome!

🌐 Necoz Website

nyaomaru / necoz

Official Necoz B.V. website with custom scroll animations.

necoz

Necoz B.V. website built with Astro, React islands, and custom scroll / walker animation logic.

Scroll down and enjoy the animations!

You can check it on mobile too 😸

Project Structure

The project is organized like this:

/
├── public/                     # Static files served as-is
├── src/
│   ├── components/
│   │   ├── home/               # Homepage sections
│   │   └── ui/                 # Reusable UI primitives and shared shells
│   │       ├── block/
│   │       ├── button/
│   │       ├── layout/
│   │       ├── mail/
│   │       ├── nyaomaru/
│   │       ├── scene/
│   │       ├── scroll/
│   │       └── text/
│   ├── layouts/                # Shared page layout shells
│   ├── lib/                    # Non-visual shared logic
│   │   ├── nyaomaru/           # Walker controller, scene logic, scene models
│   │   ├── math.ts
│   │   └── site-links.ts
│   ├── pages/                  # Route entrypoints
│   │   ├── index.astro
│   │   └── privacy-policy.astro
│

…

View on GitHub

effessdev — Fixed text spacing and wrapping on desktop while preserving the mobile layout. (#23)

Even our little website is getting some love from our cats! 😻

🚀 From Discussion to Creation

One of our recent community discussions has already turned into a new open-source project called safe-paste! 🎉

necoz-oss / safe-paste

A lightweight, local-first browser extension for sensitive information before sharing. 😺🔎

safepaste

A lightweight, local-first browser extension for sensitive information before sharing. 😺🔎

View on GitHub

It's a little tool designed to help prevent accidentally pasting sensitive information.

We're still in the early stages of development, so if you're interested, feel free to jump in and help us build it together! 🐾

You're also more than welcome to start your own discussions, share ideas, suggest new projects, or just chat with other cats!

👉 https://github.com/orgs/necoz-oss/discussions

Who knows? Your little idea might become our next open-source project! 👀

Don't be shy! We're friendly cats. Probably. 😼

👑 Cat of the Necoz

And our very first Cat of the Necoz is

🥁 Drumroll, please...

🐈 @johnnylemonny

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 has made an incredible number of contributions to changelog-bot, helping us improve everything from new features to testing, reliability, and security.

Thank you for all your amazing work, John!

You are officially a SUPER CAT!!! 😻👑🎉

Who will be our next Cat of the Necoz? 👀

🎮 Necoz Quests

Looking for your next adventure?

We've prepared some quests for curious cats! 🐾

🧩 is-kit

A lightweight TypeScript runtime type validation library.

🐾 Available Quests

🚧 Current Major Quest — API Refinement

We're exploring ways to refine and simplify the public API to make is-kit more consistent, intuitive, and easier to use.

We're also improving our documentation and test coverage, so there are plenty of small quests for first-time contributors!

👉 Explore more quests

🤖 changelog-bot

An AI-powered tool that helps generate useful changelogs.

🐾 Available Quests

🚧 Current Major Quest — Road to v1.0

We're continuing our journey toward v1.0, including improvements to changelog generation, audience filtering, and WHY extraction.

Step by step, we're getting closer to our first major release. 🚀

👉 Explore more quests

🦀 type-tune

A Rust-powered CLI that helps organize shared TypeScript types.

🐾 Available Quests

🚧 Current Major Quest — Beyond TypeScript

We've been making progress on Vue support and validating type-tune against real-world Vue and Nuxt projects!

We're also exploring some exciting future features:

Love Rust or TypeScript? There are plenty of adventures waiting for you! 🦀

👉 Explore more quests

🐈 Before Starting Your Quest

Found something you'd like to work on?

Before you start working on an issue, please check whether another cat has already claimed it and leave a comment to let us know you'd like to work on it. 🙏

Something as simple as

I'd like to work on this issue!

If another cat is already working on it, please choose another quest or ask if you can help.

This helps us avoid duplicate work and makes sure everyone's time and effort count. 💚

🌱 First contribution? No problem!

Pick a quest, ask questions, or simply join the discussion. Every little step counts!

Not sure where to start? Just leave a comment, and we'll help you find your first quest!

There are plenty of adventures for cats of all experience levels! 🐾

📰 Necoz Articles

Our cats have been busy writing too! 😸

From technical deep dives and beginner-friendly tutorials to community discussions and mysterious UFO adventures, we've already seen some amazing articles!

Let's check them out! 🐾

🐈 John

A deep dive into why changelogs should explain the WHY behind changes, rather than simply repeating commit messages. 😺

CI rate limits and AI context solved

𝗝𝗼𝗵𝗻 for Necoz

Nov 3

Stop Generating Changelogs from Git Commits: How I Fixed the 'WHY' Problem in ChangelogBot

#devops #github #opensource #typescript

6 min read

🐈 nyaomaru

The announcement that started our little adventure here on DEV! 🎉🎉🎉

Open invite for contributors to join the new org

nyaomaru for Necoz

Nov 8

Necoz Has a New Home on DEV! 🐈🎉

#news #devto #community #organization

179

119

1 min read

🐈 Hanzla Baig

A wonderful reminder that even the smallest open-source contributions can make a meaningful difference.

This is exactly what Necoz is all about! 😸💚

Highlights the open-source community Necoz

Hanzla Baig for Necoz

Nov 8

Small Contributions Matter Too 🐈

#discuss #opensource #github #necoz

2 min read

🐈 Hanzla Baig

What if DEV had a dedicated space for developers to launch, share, and discover new projects? An interesting community discussion! 👍

Community weighs risks of spam versus discovery

Hanzla Baig for Necoz

Nov 10

What if DEV had a launch system, like Product Hunt but for developers?

#discuss #showdev #startup #opensource

1 min read

🐈 Sᴛᴀʀ⭐

A lovely reminder that building your very first project is still something special, even in the age of AI. 😸

Community praises the buggy first project

Sᴛᴀʀ⭐ for Necoz

Nov 11

AI can write code, but the magic of a first project is unmatched! 🗽

#html #programming #javascript #nicoz

1 min read

🐈 nyaomaru

Introducing type-tune, our new Rust-powered CLI for organizing shared TypeScript types! 🦀 (Actually, I'm allergic to crabs 🙀)

Addresses type clutter from AI-generated code

nyaomaru for Necoz

Nov 11

Meet type-tune! 🦀 Give Your TypeScript Types a Better Home! 😸

#showdev #rust #typescript #opensource

109

6 min read

🐈 Prasoon Jadon

A beginner-friendly guide to making your first open-source contribution, covering the workflow from getting started to submitting a pull request. 😸

Prasoon Jadon for Necoz

Nov 12

From User to Contributor: A Beginner's Guide to Open Source Workflow 🐱

#opensource #programming #beginners #tutorial

7 min read

🐈 Sᴛᴀʀ⭐

Becoming a DEV Trusted Member at just 10 years old!

Congratulations, Star! 😻🎉

Overcame discouragement from doubting classmates

Sᴛᴀʀ⭐ for Necoz

Nov 12

A 10 years old developer who has become a DEV.to Trusted Member! 😱

#discuss #trusted #beginners #devto

3 min read

🐈 John

An interesting technical deep dive into the hidden context costs of MCP servers and tool-heavy AI agents. 😼🤖

Schema bloat silently burns tokens

𝗝𝗼𝗵𝗻 for Necoz

Nov 12

Your MCP Servers Are Silently Draining Your Context Window: The Hidden Cost of Tool-Heavy AI Agents

#ai #typescript #opensource #productivity

7 min read

🐈 Shruti Shahi

A humorous and relatable story about the experience of opening LinkedIn as a developer. 😸

Relatable community replies to platform burnout

Shruti Shahi for Necoz

Nov 12

A Day in the Life of Someone Who Just Wanted to Open LinkedIn in Peace

#watercooler #career #socialmedia

5 min read

🐈 Sᴛᴀʀ⭐

Learning Python loops inside the Necoz UFO?!

Even our mysterious spaceship is becoming a programming classroom! 😹🛸

Story format makes Python fun

Sᴛᴀʀ⭐ for Necoz

Nov 13

🛸 Necoz: The UFO Kingdom Python Loops 🐱

#discuss #python #programming #beginners

6 min read

🐈 Hanzla Baig

A useful improvement to DEV itself! You can now respond to organization invitations directly from your notifications. 😽

Congratulations on getting your PR merged! 🎉

Hanzla Baig for Necoz

Nov 14

You Can Now Accept or Decline DEV Organization Invitations From Notifications Page! 🎉

#news #forem #discuss #devto

2 min read

Thank you to all our amazing writers! 😻💚

Want to publish your own article under Necoz?

Tutorials, technical deep dives, personal experiences, project announcements, or even stories about cats getting abducted by UFOs 🛸

Everything is welcome! 😹

Let's keep learning, sharing, and building together!

Necoz Follow

🔮 What's Next?

Starting now, I'll be sharing little Necoz updates and events every Sunday! 🐈

New members, contributors, quests, articles, and whatever strange things our cats have been doing!

And the week after next 👇

We're planning a little bring-your-own-something event! 👀🎉

What will everyone bring?

You'll find out soon!

Thanks for being part of Necoz! 💚

Happy coding! And stay a good cat! 🐈

Want to join our growing family of cats? 🐈

Feel free to leave a comment below!

There's always room for another cat in our little UFO. 🛸💚

Meet type-tune! 🦀 Give Your TypeScript Types a Better Home! 😸

nyaomaru — Wed, 11 Nov 2026 17:19:22 +0000

Hoi hoi! 👋

I'm @nyaomaru, a frontend engineer who is actually allergic to crabs! 🙀🦀

Today, I have another exciting announcement!

I've just released a new open-source tool called type-tune! 🦀🎉

necoz-oss / type-tune

A Rust-powered CLI to find shared TypeScript types and move them safely. 🦀

type-tune

Give shared TypeScript types a better home. 😸

Scan. Review. Move. Validate.

type-tune is a Rust-powered CLI that finds shared TypeScript type aliases and interface declarations and helps move them without manually chasing imports.

It creates a reviewable plan, updates supported type imports and re-exports, and validates the rewrite with TypeScript. You decide what moves and where.

Guides for installation, the first scan, and the review workflow live in the official documentation. Releases are listed on GitHub Releases, and the package is type-tune on npm.

Why type-tune?

Types often start next to a component or utility, then end up shared across a project. Moving them later means tracking imports, local dependencies, and barrels by hand.

Discover shared types with deterministic candidate IDs.
Review plan.md and choose the destination before making changes.
Rewrite supported type-only imports, aliases, and simple barrels while keeping compatibility re-exports at the original…

View on GitHub

type-tune-docs.vercel.app

It's a small CLI tool built with Rust 🦀 that helps you find shared TypeScript types and move them to a better place.

Scan. Review. Move. Validate.

Sounds simple, right?

Well, that's exactly the idea! 😸

🐈 What Is type-tune?

If you've worked on a large TypeScript project, you've probably used tools like Knip.

Knip is awesome! 🎉

It helps us find unused files, exports, and dependencies, making it easier to clean up our codebases.

But there's another problem I've been thinking about.

What about types that are still being used, but aren't organized very well?

TypeScript types are incredibly reusable.

A type declared in one component might eventually be needed by another component, an API module, or even an entire feature.

But in practice, we don't always pay much attention to maintaining our type declarations.

For example, imagine we have this

// src/features/order/OrderPage.tsx
export type OrderSummary = {
  id: string;
  total: number;
};

At first, OrderSummary might only be used by OrderPage.

But as the feature grows, other files start importing it.

And sometimes, developers end up declaring similar types again because they don't realize something reusable already exists.

Eventually, we might have:

Types scattered across components and utilities.
Similar type declarations repeated within the same feature.
Shared types living in files that don't really belong to them.
Imports that make refactoring unnecessarily complicated.

Everything still works!

But is it easy to maintain?

Hmm, not really. 😹

That's where type-tune comes in!

type-tune finds exported types and interfaces that are already shared across multiple files and helps relocate them to more appropriate locations.

It can also update supported imports and preserve compatibility re-exports, so we don't have to manually chase references around the project.

Unlike Knip, which focuses on unused code, type-tune focuses on organizing types that are actually being used.

They're complementary tools!

One helps us remove what we don't need. The other helps us organize what we still need. 😸

💡 Why Did I Build It?

This idea actually came from my own experience.

I was working on refactoring a production codebase with more than 300,000 lines of code.

And one thing kept bothering me.

We weren't making very good use of our existing types.

Even within the same feature, types that could have been shared were sometimes declared separately.

Some types had gradually become shared dependencies, but their locations still reflected where they were originally created.

As the codebase grew, maintaining those relationships became increasingly difficult.

And there was something else I noticed.

🤖 Types Are Even More Valuable in the AI Era

I've been working with AI-assisted development quite a lot recently.

And through that experience, I've come to appreciate TypeScript's type system even more.

Types aren't just there to catch mistakes.

They can also act as useful guardrails for AI coding agents. 🛤️

Well-defined types help communicate the structure of our applications, the relationships between data, and the contracts our code is expected to follow.

In my experience, making those contracts clear is an important part of building an effective AI development workflow.

But there's a catch!

If our types are duplicated, scattered, or poorly maintained, we're not making full use of that information.

So I started wondering

Why don't we have a tool that helps us maintain the structure of our types automatically?

I looked around, but couldn't find a tool that quite solved the problem I had in mind.

I decided to build one myself! 🦀🎉

YAY!!!

🚀 How to Use type-tune

Getting started is pretty simple!

📦 Installation

You can install type-tune from npm

npm install -D type-tune

Or with pnpm (My favorite 😸)

pnpm add -D type-tune

You can also try it without installing it into your project

npx type-tune scan --project tsconfig.json

The npm package requires Node.js v22 or later and runs a platform-specific native Rust binary.

And since type-tune is written in Rust, you can also build and install it directly from GitHub using Cargo! 📦

cargo install --git https://github.com/necoz-oss/type-tune --tag v1.0.0 type-tune

The Rust source requires Rust 1.99 or later.

🔍 Step 1. Find Shared Types

First, scan your TypeScript project

npx type-tune scan --project tsconfig.json

type-tune analyzes your project and finds candidates for relocation.

By default, it looks for exported types and interfaces referenced by at least two other files.

And don't worry!

Scanning doesn't modify your code. 😸

📋 Step 2. Create a Refactoring Plan

Next, generate a plan

npx type-tune plan \
  --project tsconfig.json \
  --out .type-tune/plan.json \
  --markdown .type-tune/plan.md

This creates a JSON plan and a Markdown file you can review.

You can inspect which types were found, where they're currently declared, and where they could be moved.

🐈 Step 3. Review the Changes

Here's an important part!

type-tune doesn't decide to move everything automatically.

Every candidate starts as ignore.

You can review the plan and choose which declarations should actually move.

npx type-tune review \
  --markdown .type-tune/plan.md

You can also edit the Markdown plan manually.

I wanted the tool to automate the tedious work while keeping architectural decisions in the developer's hands.

Automation is useful. But control matters too! 😸

🦀 Step 4. Apply the Changes

Once you've reviewed your plan, you can preview the refactoring

npx type-tune apply \
  --plan .type-tune/plan.json \
  --markdown .type-tune/plan.md \
  --dry-run

type-tune performs the supported rewrites, validates them with TypeScript, and restores the changed files after a normal dry-run.

When you're happy with the plan, run

npx type-tune apply \
  --plan .type-tune/plan.json \
  --markdown .type-tune/plan.md

That's it! 🎉

For supported transformations, type-tune handles moving declarations, updating type imports, and validating the result with the TypeScript compiler.

Of course, you should still review the Git diff and run your project's own checks.

✨ Want to Move Just One Type?

There's also a direct extraction command!

npx type-tune extract OrderSummary \
  --from src/features/order/OrderPage.tsx \
  --to src/features/order/types/order.ts \
  --project tsconfig.json \
  --dry-run

Pretty handy, right? 😸

🐈 Let's Build type-tune Together!

I released type-tune under Necoz because I want to build it together with other developers! 😸💚

Necoz · GitHub

A friendly open-source community building small, simple, and useful tools together. 😸 - Necoz

github.com

And this time, with Rust! 🦀

I believe open source becomes even more exciting when we share ideas, learn from each other, and build things together.

So, if you have any ideas, suggestions, or want to contribute, I'd love to hear from you!

Let's grow type-tune together! 🐈

🌱 Just the Beginning!

This is the first public release, v1!

type-tune currently focuses on exported TypeScript type aliases and interface declarations in .ts and .tsx files.

It doesn't automatically merge duplicate type definitions or handle every possible TypeScript refactoring yet.

But I think it's a useful first step toward making type maintenance easier.

And there's still plenty of room to improve!

We'd love to hear about the problems you've encountered while maintaining types in large TypeScript projects.

Maybe you've run into the same challenges!

Or maybe you've found a completely different approach.

Either way, I'd love to learn from your experience! 💚

💚 Check It Out!

type-tune is open source and available on GitHub!

necoz-oss / type-tune

A Rust-powered CLI to find shared TypeScript types and move them safely. 🦀

type-tune

Give shared TypeScript types a better home. 😸

Scan. Review. Move. Validate.

type-tune is a Rust-powered CLI that finds shared TypeScript type aliases and interface declarations and helps move them without manually chasing imports.

It creates a reviewable plan, updates supported type imports and re-exports, and validates the rewrite with TypeScript. You decide what moves and where.

Guides for installation, the first scan, and the review workflow live in the official documentation. Releases are listed on GitHub Releases, and the package is type-tune on npm.

Why type-tune?

Types often start next to a component or utility, then end up shared across a project. Moving them later means tracking imports, local dependencies, and barrels by hand.

Discover shared types with deterministic candidate IDs.
Review plan.md and choose the destination before making changes.
Rewrite supported type-only imports, aliases, and simple barrels while keeping compatibility re-exports at the original…

View on GitHub

If you find it interesting, please consider giving it a ⭐ on GitHub! 😸

And if you have any ideas, suggestions, or bugs to report, feel free to open an issue or contribute!

Every bit of feedback helps make these little projects better.

🦀 Coming Up Next

Oh, and one more thing!

You might be wondering

Why did I choose Rust instead of TypeScript to build a TypeScript refactoring tool? Is nyaomaru a TypeScript lover, isn't it? 🤔

That's actually an interesting story!

I'll talk about the reasons behind that decision, what I learned while building it, and my experience using Rust in my next article!

Stay tuned! 🦀

Thanks for reading, and happy coding! 😸🙌

💚 Join Our Necoz Community!

Oh, and one more thing! 😸

We also have a Necoz community on DEV! 🎉

Necoz Follow

Everyone is welcome, whether you're a developer, a writer, or just curious!

Wanna join? Leave a comment below and I'll send you an invitation! 💌

No pressure, no obligations. Just come hang out with us! 🐈

Small. Simple. Useful. Built Together! 💚

Necoz Has a New Home on DEV! 🐈🎉

nyaomaru — Sun, 08 Nov 2026 11:50:29 +0000

Hoi hoi! 👋

A little update from Necoz! 😸

We've created our own organization here on DEV!

Necoz Follow

YAY!!! 🎉

Necoz started with a few small open-source projects, and now we're slowly building a community around them.

This will be another place to share what we're building, what we're learning, and the little discoveries we make along the way.

And of course, we'd love to see more contributors sharing their own experiences too! 💚

Whether you're writing code, improving docs, fixing bugs, or just exploring, you're always welcome!

Small. Simple. Useful. Built Together! 🐈

🐈 Wanna Join Necoz?

We'd love to have you! 😸

John has already joined us here on DEV! Thanks, @johnnylemonny ! 🎉💚

If you're interested in joining Necoz here on DEV, just leave a comment below and I'll send you an invitation! 💌

Everyone is welcome! 🙌

You don't need to write articles or contribute anything. Just joining us is more than enough!

No pressure, no obligations. Let's grow this little community together, one cat at a time! 🐾

Necoz · GitHub

A friendly open-source community building small, simple, and useful tools together. 😸 - Necoz

github.com

Stay a Good Cat! 🐱

Meet Necoz! 😸 Small. Simple. Useful.

nyaomaru — Wed, 04 Nov 2026 16:17:07 +0000

Hoi hoi! 👋

I'm @nyaomaru, a frontend engineer who loves TypeScript and cats! 😸

Today, I have some exciting news!

I've created a new open-source organization called Necoz! 🐈🎉

Necoz · GitHub

A friendly open-source community building small, simple, and useful tools together. 😸 - Necoz

github.com

Why?

Well, my projects started as little tools I built for myself.

But over time, people started using them, reporting bugs, improving documentation, and contributing code.

YAY!!! 🎉

And I realized something.

Open source is much more fun when we build things together!

So, I decided to give these projects a new home. 🏠

🐈 Small. Simple. Useful.

This is the philosophy behind Necoz.

We don't need to build something gigantic to make a difference.

A tiny utility can solve a real problem.

A small PR can make a project better.

Even fixing one typo can help someone!

That's what I love about open source. 😸

🌱 Our Three Principles

🌍 Open to Everyone

First-time contributor?

Experienced engineer?

Just found a typo?

EVERYONE IS WELCOME!!! 🎉

You don't need to be an expert to contribute.

🛠️ Build Something Useful

Small tools. Simple solutions. Real problems.

A project doesn't need a thousand features to be valuable.

Sometimes one useful function is enough!

😸 Be a Good Cat

Be kind. Be curious. Respect others.

We can disagree about code, but we should always respect the people behind it.

And don't be afraid to make mistakes.

Even cats sometimes fall off tables! 😹

🚀 Our Projects

We're starting with two projects!

is-kit: A lightweight TypeScript toolkit for composing reusable type guards.

necoz-oss / 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…

View on GitHub

changelog-bot: A tool that helps generate useful changelogs from GitHub project history.

necoz-oss / 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.

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…

View on GitHub

Both started as personal projects.

Now, they're part of Necoz!

And hopefully, more little projects will join us someday. 😸

🎉 Welcome to Necoz, John!

And guess what?

@johnnylemonny has already joined Necoz! 🐈🎉

YAY!!! Our little cat family is growing! 😸

I'm really happy to have him on board!

Welcome, John! Let's build something awesome together! 🚀

❤️ Let's Build Together!

To everyone who has contributed to my projects so far...

THANK YOU!!! 🎉

Every Issue, PR, suggestion, and Star means a lot.

I don't know how big Necoz will become.

And that's okay!

What matters is building useful things, learning together, and making open source a welcoming place.

One small contribution at a time.

🐈 GitHub: https://github.com/necoz-oss
🌐 Website: https://necoz.co/

If something catches your interest, feel free to join us!

And if you like our projects, a ⭐ would make these little cats very happy! 😸

Stay a Good Cat! 😸

Thank you for reading! 🤲

Trick or Type Guard? Surviving `unknown` with is-kit 🎃

nyaomaru — Sat, 31 Oct 2026 15:16:52 +0000

Hoi hoi! 👋

I'm @nyaomaru, a frontend engineer who is scared of horror things 🙀

Happy Halloween! 🎃👻

Tonight, we're exploring a haunted TypeScript project.

There are zombies 🧟, ghosts 👻, mysterious pumpkins 🎃, and a terrifying vampire 🧛 waiting for us.

And they all have something to do with TypeScript types!

Our mission?

Survive the night without losing type safety! 😸

Let's go!

🧟 Chapter 1: The Unknown Living Dead

It's a dark and spooky night.

Suddenly, something crawls out of the grave! 🧟

const creature: unknown = JSON.parse('{"message":"BRAAAINS!"}');

Oh! An unknown creature!

Let's see what it wants.

console.log(creature.message);
// ❌ 'creature' is of type 'unknown'.

WHAT?! 🙀

TypeScript won't let us!

But why?

Well, because we don't actually know what creature is.

It might be a zombie.
It might be a ghost.
It might even be a cute little cat. 😸

unknown means we haven't verified the value yet.

Unlike any, TypeScript won't let us access arbitrary properties on an unknown value.

And that's actually a good thing!

Let's try something simpler.

import { isString } from "is-kit";

const voice: unknown = JSON.parse('"BRAAAINS!"');

if (isString(voice)) {
  console.log(voice.toUpperCase());
  // BRAAAINS!
}

YAY! 🎉

We survived our first encounter!

Of course, we could also use typeof voice === 'string' here.

For a single check, that's perfectly fine!

But what happens when our monsters become bigger and more complicated?

🎃 Chapter 2: The Big Pumpkin of Unknown

Look!

A GIGANTIC PUMPKIN! 🎃

And apparently, it's full of candy.

But nobody knows what's really inside.

const pumpkin: unknown = JSON.parse(`{
  "name": "Big Pumpkin",
  "candies": ["Chocolate", "Lollipop", "Cookie"],
  "spookyLevel": 99,
  "keeper": {
    "name": "cat",
    "friendly": true
  },
  "secret": "Meow!"
}`);

That's a pretty big object.

Can we just grab the candy?

console.log(pumpkin.candies);
// ❌ 'pumpkin' is of type 'unknown'.

Not again! 😿

We need to check what's inside before touching anything.

Fortunately, we have struct!

import {
  arrayOf,
  isBoolean,
  isNumber,
  isString,
  optionalKey,
  struct,
} from "is-kit";

const isPumpkin = struct({
  name: isString,
  candies: arrayOf(isString),
  spookyLevel: isNumber,
  keeper: struct({
    name: isString,
    friendly: isBoolean,
  }),
  secret: optionalKey(isString),
});

We composed several small guards into one big pumpkin guard.

isString checks strings.
isNumber checks finite numbers.
arrayOf(isString) checks an array of strings.
struct checks nested object shapes.
optionalKey allows a property to be missing.

Now, let's open the pumpkin!

import { safeParse } from "is-kit";

const result = safeParse(isPumpkin, pumpkin);

if (result.valid) {
  console.log(result.value.candies);
  // ['Chocolate', 'Lollipop', 'Cookie']

  console.log(result.value.keeper.name);
  // cat 😸
}

We found the candy!!! 🍬🎉

When validation succeeds, result.value has the type inferred from our guards.

And when validation fails?

const cursedPumpkin = {
  name: "Cursed Pumpkin",
  candies: "100 candies",
  spookyLevel: 99,
  keeper: {
    name: "cat",
    friendly: true,
  },
};

const result = safeParse(isPumpkin, cursedPumpkin);

console.log(result);
// { valid: false }

The candies were a string, not an array!

Our guard rejected the cursed pumpkin.

And here's the important part.

safeParse doesn't magically fix or convert invalid values.

It simply tells us whether the value passed our guard.

Also, struct allows extra properties by default. If you need to reject additional own enumerable string keys, you can use { exact: true }.

Nice and simple!

🍬 Chapter 3: Trick or Type Guard!

Ding dong! 🔔

TRICK OR TREAT!!! 😸

Someone hands us a mysterious gift.

function receiveGift(): unknown {
  return Math.random() > 0.5 ? "Chocolate" : { spiders: 100 };
}

const gift: unknown = receiveGift();

Wait.

Is it candy?
Or is it a box full of spiders?! 🕷️😱

We need a way to check!

And this time, we want to accept either a string or a number.

Let's combine our guards with or!

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

const isTreat = or(isString, isNumber);

function trickOrTreat(gift: unknown) {
  if (isTreat(gift)) {
    // gift: string | number
    return `🍬 Treat: ${gift}`;
  }

  return "👻 Trick!";
}

Now let's try it!

trickOrTreat("Chocolate");
// 🍬 Treat: Chocolate

trickOrTreat(100);
// 🍬 Treat: 100

trickOrTreat({ spiders: 100 });
// 👻 Trick!

YAY!!! 🍬

No spiders for us today!

This is one of my favorite things about is-kit.

We don't need to write one giant validator.

We can build small guards, combine them, and reuse them wherever we need.

Small guards. Simple composition. Useful TypeScript narrowing.

That's the idea!

But wait,
Something is coming.
Something TERRIFYING.

🧛 Final Boss: The Vampire Called `any`

Suddenly, the lights go out.

The door opens.

A mysterious figure appears in the darkness.

It's... COUNT ANY!!! 🧛💀

The most terrifying vampire in our TypeScript project! And he has a very dangerous power.

He can make TypeScript stop checking our operations!

const visitor: unknown = JSON.parse('{"name":666}');

A mysterious visitor has arrived.

Normally, TypeScript protects us from accessing properties before we verify them.

But Count Any has a trick.

THE CURSE OF as any! 🧛

const vampire = visitor as any;

// The vampire ignores type safety!
console.log(vampire.name.toUpperCase());

No TypeScript error!

Wait, What?! 🙀

Does that mean the code is safe?

At runtime

TypeError: vampire.name.toUpperCase is not a function

💀 GAME OVER 💀

Count Any didn't turn the number into a string.

He just convinced TypeScript to stop checking it!

That's what makes any dangerous.

It allows operations without requiring proof that they'll work.

But unknown behaves differently.

const visitor: unknown = JSON.parse('{"name":666}');

console.log(visitor.name.toUpperCase());
// ❌ TypeScript stops us!

TypeScript refuses to continue until we check the value.

So how do we defeat Count Any?

With a Type Guard, of course! 😸

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

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

if (isFriendlyGuest(visitor)) {
  console.log(visitor.name.toUpperCase());
} else {
  console.log("🧄 Not tonight, Count Any!");
}

And just like that

THE VAMPIRE HAS BEEN DEFEATED! 🧄🎉

Well, at least this particular cursed value has been rejected.

A Type Guard checks the actual runtime value, while a type assertion only changes what TypeScript believes about it.

One important detail, neither unknown nor any changes the value at runtime.

They are TypeScript types.

The difference is what the compiler allows us to do before verifying the value.

And that's why unknown is usually the safer choice for untrusted data.

😸 Epilogue: We Survived Halloween!

What a night!

We met the Unknown Living Dead, opened a gigantic pumpkin, collected some candy, and defeated Count Any!

So, what did we learn?

Monster	TypeScript lesson
🧟 Unknown Living Dead	`unknown` prevents unchecked operations
🎃 Big Pumpkin	`struct` validates object shapes
🍬 Trick or Treat	`or` combines reusable type guards
🧛 Count Any	`any` bypasses normal type checking

Of course, any isn't always evil.

Sometimes it's useful when dealing with legacy code or difficult integrations.

But when working with API responses, parsed JSON, and other untrusted values, keeping them as unknown until validation is usually a much safer approach.

And is-kit makes those checks easy to compose and reuse!

If you want to explore more, check out the official guide 👇

📖 How to Validate unknown in TypeScript Without a Schema Library

And remember

The real monster isn't unknown. It's unchecked any. 🧛

Happy Halloween!!! 🎃👻

If you enjoyed this little TypeScript adventure, check out is-kit!

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…

View on GitHub

And if you like the project, a ⭐ would make this little cat very happy! 😸

Thank you for reading! 🤲

I Compared 6 TypeScript Validation Libraries. Here's What Surprised Me 🤔

nyaomaru — Wed, 28 Oct 2026 15:37:53 +0000

Hoi hoi! 👋

I'm nyaomaru, a frontend engineer and OSS developer working mostly with TypeScript.

When we need runtime validation in TypeScript, the conversation often turns into this 👇

"Which library should I use?"

Or maybe, just write a type guard?

I maintain is-kit, so I think about this boundary quite a lot.

And recently I started wondering

Are we comparing libraries that are actually solving the same problem?

For example, if all I want is this

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

do I really need a schema system?

But if I want:

structured validation errors
transformations
parsing
schema metadata
framework integrations

then a small boolean guard is probably not enough either.

So instead of asking "Which validator is best?", I tried a different comparison.

I implemented the same User validation with:

a handwritten guard with a TypeScript predicate
is-kit
Runtypes
Valibot
Zod
ArkType
typia

Then I compiled, tested them against the same fixtures, measured standalone browser bundle size, and ran a small steady-state runtime benchmark.

The hardest part was not making seven validators compile.

It was making seven validators mean the same thing.

Even “a string with at most 100 characters” can describe different runtime contracts.

So, let's look at what each tool is actually buying us. 😺

🧪 The User we will validate

Here is the shared type.

type User = {
  id: string;
  name: string;
  age: number;
  role: "admin" | "user";
  tags: string[];
  profile: {
    bio: string;
    active: boolean;
  };
};

And the runtime rules are:

id must be a string
name must contain 1–100 UTF-16 code units
age must be an integer from 18 to 120
role must be exactly "admin" or "user"
tags must be an array of strings
profile.bio must be a string
profile.active must be a boolean
extra keys are rejected at the root and inside profile
values are not coerced

For this comparison, the main input domain is ordinary JSON-decoded data.

That matters because JavaScript can also give us strange things like inherited properties, sparse arrays, symbols, getters, and non-enumerable keys.

We'll come back to those later.

1. ✍️ Handwritten Guard — Sometimes a Guard Is Enough

Let's start with the boring option, a handwritten JavaScript guard with a TypeScript predicate.

No validation library.

const isRecord = (value: unknown): value is Record<string, unknown> =>
  typeof value === "object" && value !== null && !Array.isArray(value);

const hasExactKeys = (
  value: Record<string, unknown>,
  keys: readonly string[],
): boolean =>
  Object.keys(value).length === keys.length &&
  keys.every((key) => Object.hasOwn(value, key));

export const isUser = (value: unknown): value is User => {
  if (
    !isRecord(value) ||
    !hasExactKeys(value, ["id", "name", "age", "role", "tags", "profile"])
  ) {
    return false;
  }

  if (
    !isRecord(value.profile) ||
    !hasExactKeys(value.profile, ["bio", "active"])
  ) {
    return false;
  }

  return (
    typeof value.id === "string" &&
    typeof value.name === "string" &&
    value.name.length >= 1 &&
    value.name.length <= 100 &&
    typeof value.age === "number" &&
    Number.isInteger(value.age) &&
    value.age >= 18 &&
    value.age <= 120 &&
    (value.role === "admin" || value.role === "user") &&
    Array.isArray(value.tags) &&
    value.tags.every((tag) => typeof tag === "string") &&
    typeof value.profile.bio === "string" &&
    typeof value.profile.active === "boolean"
  );
};

And then

declare const input: unknown;

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

This is still very good.

For one local boundary, a handwritten type guard has a huge advantage

There is no extra model to learn.

It is just JavaScript runtime checks plus a TypeScript predicate.

But the cost starts to appear when your codebase grows this

isUser;
isProfile;
isRole;
isNonEmptyString;
isAdultAge;
isStringArray;
isApiResponse;
isConfig;
isFeatureFlag;

Now you are not writing "one guard" anymore.

You are maintaining your own tiny guard library.

And this is where the next option starts to make sense. 👍

2. 🔧 is-kit — When Small Guards Become Reusable Building Blocks

This is the problem I built is-kit around.

I didn't want a schema-first workflow for every narrowing problem.

I wanted small guards that stay small, but compose cleanly.

import {
  and,
  arrayOf,
  isBoolean,
  isNumber,
  isString,
  oneOfValues,
  predicateToRefine,
  safeParse,
  struct,
} from "is-kit";

export const isName = and(
  isString,
  predicateToRefine<string>(
    (value) => value.length >= 1 && value.length <= 100,
  ),
);

export const isAge = and(
  isNumber,
  predicateToRefine<number>(
    (value) => Number.isInteger(value) && value >= 18 && value <= 120,
  ),
);

export const isProfile = struct(
  {
    bio: isString,
    active: isBoolean,
  },
  { exact: true },
);

export const isUser = struct(
  {
    id: isString,
    name: isName,
    age: isAge,
    role: oneOfValues("admin", "user"),
    tags: arrayOf(isString),
    profile: isProfile,
  },
  { exact: true },
);

export const parseUser = (input: unknown) => safeParse(isUser, input);

The important part is that the pieces remain normal guards

const names = values.filter(isName);

if (isAge(value)) {
  // value is number
}

That is useful when your codebase already thinks in terms of predicates.

And this is also where I would draw the line.

safeParse() gives a small success/failure result around a guard.

It does not turn is-kit into:

a field-level issue system
a transformation pipeline
a schema metadata system
an OpenAPI ecosystem
a form integration layer

If those are the actual requirements, I would rather use a schema library than try to make a guard toolkit become one.

One type-level detail also showed up in the verification, struct() and arrayOf() infer readonly structures.

So the runtime shape matches our User, but readonly string[] is not assignable to mutable string[].

That difference is real, and the type tests make it explicit instead of hiding it with a cast. 🔧

3. 🏃 Runtypes — A Validator Object, Not Just a Predicate

Runtypes moves one level further.

Instead of just a boolean predicate, you get a runtime validator object with several ways to consume it.

import {
  Array as RtArray,
  Boolean as RtBoolean,
  Literal,
  Number as RtNumber,
  Object as RtObject,
  String as RtString,
  Union,
} from "runtypes";

const Name = RtString.withConstraint(
  (value) =>
    (value.length >= 1 && value.length <= 100) || "name length must be 1..100",
);

const Age = RtNumber.withConstraint(
  (value) =>
    (Number.isInteger(value) && value >= 18 && value <= 120) ||
    "age must be an integer in 18..120",
);

export const UserSchema = RtObject({
  id: RtString,
  name: Name,
  age: Age,
  role: Union(Literal("admin"), Literal("user")),
  tags: RtArray(RtString),
  profile: RtObject({
    bio: RtString,
    active: RtBoolean,
  }).exact(),
}).exact();

export const isUser = (input: unknown) => UserSchema.guard(input);

export const checkUser = (input: unknown) => UserSchema.check(input);

export const parseUser = (input: unknown) => UserSchema.parse(input);

export const inspectUser = (input: unknown) => UserSchema.inspect(input);

This feels different from a guard toolkit.

A predicate mainly answers

Is this value a User?

A Runtype can also answer that question, but the same object can:

narrow with guard
throw with check
parse with parse
expose structured failure data

Also, check() and parse() should not be treated as synonyms.

Runtypes supports parser behavior, and object handling can differ between validation and parsing contexts.

That is exactly the kind of runtime machinery you do not have in a plain predicate. 🏃

4. 🤖 Valibot — Schema Validation With a Modular API

Valibot is where the comparison starts looking more "schema-like".

import * as v from "valibot";

export const UserSchema = v.strictObject({
  id: v.string(),
  name: v.pipe(v.string(), v.minLength(1), v.maxLength(100)),
  age: v.pipe(v.number(), v.integer(), v.minValue(18), v.maxValue(120)),
  role: v.picklist(["admin", "user"]),
  tags: v.array(v.string()),
  profile: v.strictObject({
    bio: v.string(),
    active: v.boolean(),
  }),
});

export const isUser = (input: unknown) => v.is(UserSchema, input);

export const parseUser = (input: unknown) => v.safeParse(UserSchema, input);

This gives us:

schema validation
type inference
structured issues
parsing APIs
transformation pipelines

But the API is still function-based and modular.

That is a big part of Valibot's design.

Instead of every capability living as methods on large schema objects, you compose independent functions.

That makes tree shaking a first-class part of the normal API.

And unlike a pure schema-only mental model, Valibot also exposes v.is() as a type guard.

So schema validation and ordinary TypeScript narrowing are not mutually exclusive.

One caveat: v.is() is the guard path. It does not expose validation issues or apply transformations like parsing does. 🤖

5. 💎 Zod — When the Schema Is Part of a Bigger Ecosystem

Now Zod.

import * as z from "zod";

export const UserSchema = z.strictObject({
  id: z.string(),
  name: z
    .string()
    .refine(
      (value) => value.length >= 1 && value.length <= 100,
      "name must contain 1..100 UTF-16 code units",
    ),
  age: z.int().min(18).max(120),
  role: z.enum(["admin", "user"]),
  tags: z.array(z.string()),
  profile: z.strictObject({
    bio: z.string(),
    active: z.boolean(),
  }),
});

export type User = z.output<typeof UserSchema>;

export const parseUser = (input: unknown) => UserSchema.safeParse(input);

// This schema has no transforms, so its output type is safe for the input too.
export const isUser = (input: unknown): input is User => parseUser(input).success;

Zod does not expose a built-in is() method, but this adapter can narrow input because this schema has no transforms. With a transforming schema, safeParse().data is the safe typed value: the original input and output types may differ.

Zod is not interesting because it can validate a User.

All of these libraries can do that.

The real value is everything around the schema:

form integrations
API tooling
schema conversion
metadata
codecs
OpenAPI-related tooling
framework integrations

If your schema is already becoming part of application infrastructure, that ecosystem matters. 💎

There is one important detail in this sample though.

I did not use this

z.string().min(1).max(100);

Why?

Because our contract says

1–100 UTF-16 code units

Zod's built-in string length checks use Unicode code points, so this sample uses .refine() with JavaScript's string.length to preserve the stated UTF-16 contract. The shared emoji fixture demonstrates why below.

What about bundle size?

It is too easy to write

Valibot is small, Zod is large.

That is not a good 2026 comparison anymore.

Zod also has Zod Mini, which uses a more functional, tree-shakable API.

The bundle table later in this article measures regular Zod, not Zod Mini.

So it should not be read as Valibot versus the smallest possible Zod setup.

Zod can also compile optimized validation logic at runtime with z.compile() and new Function.

I did not enable it here.

That makes this distinction more useful than the broad label “generated validation”

runtime schema compilation
  vs
build-time generation from TypeScript types

That distinction becomes important when we get to typia.

6. 🚢 ArkType — What If the Runtime Schema Looked Like TypeScript?

ArkType has a very different authoring model.

import { type } from "arktype";

export const UserSchema = type({
  id: "string",
  name: "0 < string <= 100",
  age: "18 <= number.integer <= 120",
  role: "'admin' | 'user'",
  tags: "string[]",
  profile: {
    bio: "string",
    active: "boolean",
  },
}).onDeepUndeclaredKey("reject");

export const isUser = (input: unknown) => UserSchema.allows(input);

export const parseUser = (input: unknown) => UserSchema(input);

export const ArkErrors = type.errors;

I like this comparison

z.int().min(18).max(120);

"18 <= number.integer <= 120";

Neither is "better".

They are different ways to express the runtime contract.

If your team already thinks naturally in TypeScript-like expressions, ArkType is very readable.

allows() also works as a type guard.

And calling the schema directly gives you validated output or an error collection.

Another interesting part: ArkType can precompile optimized traversal logic at runtime when the environment allows new Function.

So ArkType is already doing specialization. 🚢

But it is still not the same architecture as typia.

ArkType starts from a runtime type representation.

typia starts from TypeScript types during the build.

7. 🚀 typia — Generate the Validator During the Build

typia is the outlier in this comparison.

import typia, { type tags } from "typia";

type Utf16Name = tags.TagBase<{
  kind: "utf16Name";
  target: "string";
  value: undefined;
  validate: "$input.length >= 1 && $input.length <= 100";
}>;

export interface User {
  id: string;
  name: string & Utf16Name;
  age: number & tags.Type<"uint32"> & tags.Minimum<18> & tags.Maximum<120>;
  role: "admin" | "user";
  tags: string[];
  profile: {
    bio: string;
    active: boolean;
  };
}

export const isUser = typia.createEquals<User>();

export const validateUser = typia.createValidateEquals<User>();

This is not a runtime schema object.

The source of truth is the TypeScript type plus typia's tags.

Then typia's build transform turns

typia.createEquals<User>();

into specialized validation code.

That means there is no general runtime schema interpreter walking a User schema object.

But there is a trade-off

You need build integration.

The current official setup uses TypeScript 7 and ttsc / typia's transform integration.

Stock tsc alone does not run the transform.

In my verification workspace, the first typia build also had to compile a Go source plugin and took several minutes.

That setup cost is not part of the runtime benchmark, but it is absolutely part of the adoption decision.

Also, typia's built-in MinLength / MaxLength did not match our UTF-16 contract.

So I used a custom tag for name.

Again, same-looking validation rule, different semantics. 🚀

😹 Wait, Even "String Length" Was Different?

This was the first test that made me stop.

"😀".repeat(51).length;
// 102

JavaScript's string.length counts UTF-16 code units.

So with our contract

maximum = 100 UTF-16 code units

this should fail.

And it did fail in:

handwritten guard
is-kit
Runtypes
Valibot
ArkType

But the original Zod and typia samples accepted it.

Why?

Because their built-in length constraints count Unicode code points instead.

For this string

51 emoji
= 51 code points
= 102 UTF-16 code units

Neither behavior is wrong.

They are just different contracts.

And neither one necessarily matches "what a human sees" either, because grapheme clusters make Unicode even more fun. 😹

So I changed the Zod sample to .refine() and typia to a custom tag.

That was probably the most useful lesson in the whole comparison 👇

Equivalent-looking schemas are not automatically equivalent runtime contracts.

So What Are We Actually Comparing?

At this point, these no longer look like seven interchangeable libraries.

They are different runtime models.

Approach	Source of truth	Natural success API	Structured failures	Transformation model	Compilation / build requirement
Handwritten guard	Type + handwritten check	Predicate	Manual	Manual	None
is-kit	Composed guards	Predicate / `safeParse`	Basic valid/invalid result	Guard-oriented	None
Runtypes	Runtype object	`guard` / `check` / `parse`	Yes	Parsers	None
Valibot	Schema functions	`is` / `safeParse`	Yes	Schema pipelines	None
Zod	Schema objects	`parse` / `safeParse`	Yes	Transforms / codecs	No build transform; optional runtime `z.compile()`
ArkType	Runtime type expressions	`allows` / invocation	Yes	Morphs	No build transform; runtime precompilation when available
typia	TypeScript types and tags	Generated predicates / validation results	With validation APIs	Build-generated functions	Build transform required

This is why I no longer like thinking about them as a simple upgrade ladder.

A schema library is not "a better type guard".
A generated validator is not "a better schema".

They solve overlapping problems at different layers.

✅ What Actually Passed?

The complete harness, lockfile, fixtures, probes, and generated result files live in typescript-validator-comparison. The article links to that immutable commit, rather than to a moving branch.

To reproduce the recorded snapshot:

git clone https://github.com/nyaomaru/typescript-validator-comparison.git
cd typescript-validator-comparison
git checkout --detach b26350d01fd18cb77d55a95e2f3b112657f0d305
corepack pnpm install --frozen-lockfile
corepack pnpm verify

pnpm verify runs lint, strict type checking, fixtures, bundle measurement, benchmarks, JavaScript-only probes, and report generation. The result tables below are that run's saved snapshot, reruns on another machine will naturally produce different timing numbers.

I pinned the versions and ran the same fixture matrix against all seven implementations.

Environment

Date:       2026-10-23
Node:       24.22.1
TypeScript: 7.0.2
pnpm:       11.22.0
ttsc:       0.31.3
tsbuild:    0.28.2

Packages

Package	Version
is-kit	1.15.3
runtypes	7.0.5
valibot	1.5.0
zod	4.6.5
arktype	2.2.8
typia	15.1.0

The shared matrix contains 35 JSON fixtures.

That includes:

valid users
age boundaries
name boundaries
emoji length cases
wrong primitive types
missing fields
invalid roles
invalid array elements
extra root keys
extra nested keys
non-object roots

All seven matched the expected result.

35 fixtures
× 7 validators
= 245 boolean checks

All 245 passed.

The harness also checks input mutation, richer APIs, strict TypeScript compilation, lint, builds, narrowing, and bundled output behavior.

So the implementations agree for the JSON-shaped contract in this article—not necessarily for every JavaScript value.

🧩 One More Surprise: "Exact" Is Not Always Exact

I also tested values outside the normal JSON-shaped input domain. The four probes in the table mean exactly this:

const sparseTags = { ...valid, tags: new Array(2) };
const inheritedFields = Object.create(valid);
const extraSymbol = { ...valid, [Symbol("extra")]: true };
const extraUndefined = { ...valid, extra: undefined };

The repository runs nine more probes, including non-enumerable properties and a throwing getter. Here is what happened for these four

Probe	Native	is-kit	Runtypes	Valibot	Zod	ArkType	typia
Sparse `tags` array	Accept	Reject	Accept	Reject	Reject	Reject	Accept
All fields inherited	Reject	Reject	Reject	Accept	Accept	Accept	Accept
Extra symbol property	Accept	Accept	Reject	Accept	Accept	Reject	Accept
Extra key with value `undefined`	Reject	Reject	Reject	Reject	Reject	Reject	Accept

All seven accepted the extra non-enumerable property I tested.

All seven threw when reading a getter that throws.

This does not mean one library is "correct" and the others are broken.

It means

"Exact object validation" needs a scope.

For example, my native guard uses

Object.keys(value);

That only sees enumerable string keys.

And this

value.tags.every(...)

skips sparse array holes.

That is perfectly reasonable for JSON data.

It is not a universal policy for every weird object JavaScript can create.

This is another reason I think validator comparisons should state the expected input domain.

📦 Bundle Size

Now the fun table. 😺

Each browser-targeted entry exports only validate.

All of them were bundled with the same esbuild settings:

browser platform
ESM
ES2022
minification
tree shaking
legal comments removed

Then I measured raw, gzip, and Brotli output.

Validator	Raw bytes	gzip bytes	Brotli bytes
handwritten guard	588	337	295
is-kit	3,421	1,530	1,423
runtypes	16,667	5,188	4,657
valibot	5,722	1,853	1,675
zod	89,888	26,212	23,331
arktype	155,549	47,603	41,956
typia	772	403	339

A few important caveats.

This is standalone cost

If your app already ships Zod, the marginal cost of one more schema is not 26 KB gzip.

This table measures isolated entry bundles.

This is regular Zod

Not Zod Mini.

So this table does not answer

Valibot vs Zod Mini?

Generated does not mean zero bytes

typia's final guard bundle was only 772 bytes raw in this test.

But it still shipped generated code and a uint32 helper.

"Generated validator" does not mean "free validator".

Still, the architectural difference is very visible here.

⚡ Runtime

I almost did not include runtime numbers because validator benchmarks get misleading very quickly.
But since the workspace already had the same contract and fixtures, I ran a small steady-state benchmark.

Three cases:

valid user
wrong id
wrong nested profile.active

Each library ran in a separate Node process.

Each case used:

20,000 warmup calls
9 measured samples
50,000 calls per sample

Schemas and validators were created outside the measured loop.

Results are median nanoseconds per call, with min–max in parentheses.

Validator	Valid	Wrong `id`	Wrong `profile.active`
handwritten guard	79.9 (77.3–114.1)	73.6 (72.1–84.9)	80.8 (79.0–96.3)
is-kit	232.0 (225.7–257.5)	34.5 (33.1–38.9)	210.3 (203.6–218.1)
runtypes	5804.0 (5425.5–6298.0)	9221.8 (8443.2–11063.2)	10101.2 (9287.6–10503.5)
valibot	951.2 (425.2–1782.7)	200.2 (96.1–422.3)	1112.1 (648.4–1538.1)
zod	612.6 (351.3–1203.5)	1491.6 (862.9–2824.6)	2208.5 (1592.4–4757.4)
arktype	291.5 (278.1–614.4)	9.6 (6.6–17.7)	12.0 (11.3–37.6)
typia	21.9 (20.5–46.1)	2.0 (1.9–6.4)	11.5 (10.8–17.2)

Please do not read this as:

typia is the fastest validator.

This is a microbenchmark.

The same small object shapes are validated repeatedly, so V8 can optimize very aggressively.

I would not interpret a 2.0 ns result as a portable "cost of validation" in a real application.

The success APIs are also different:

handwritten guard uses a predicate
is-kit uses a predicate
Runtypes uses .guard()
Valibot uses is()
Zod uses safeParse(...).success
ArkType uses allows()
typia uses a generated equals guard

Those operations do not all perform exactly the same work.

What the benchmark does show is that architecture and failure path matter.

For example:

the handwritten guard pays for exact-key checks before rejecting the wrong id
ArkType's invalid paths were much cheaper than its valid path
typia's generated guard had very low steady-state overhead here
Runtypes' richer validation machinery costs more in this particular hot loop

That is useful.

A universal speed ranking is not.

So... Which One Would I Use? 🤔

After doing all of this, my decision tree is actually pretty simple.

Just one local narrowing check?

Use a handwritten guard.

if (isUser(input)) {
  // input is User
}

No dependency is a feature when the problem is small.

Lots of reusable guards?

This is where I use is-kit. 🔧

values.filter(isName);

if (isAge(value)) {
  // ...
}

The problem is not "I need a schema".

The problem is "I keep rebuilding the same predicates and composition helpers".

Want a validator object?

Runtypes is interesting when you like having one runtime object that can: 🏃

guard
check
parse
inspect
assert

Want schema validation with a modular API?

Valibot. 🤖

Especially if client bundle size and tree shaking are important parts of the design.

Want schemas tied into a bigger ecosystem?

Zod. 💎

That is probably its strongest reason to exist in many applications.

And if bundle size is a concern, evaluate Zod Mini separately.

Want the schema syntax to feel like TypeScript?

ArkType. 🚢

"18 <= number.integer <= 120";

is a very different authoring experience from chained schema methods.

Want TypeScript types transformed into validators during the build?

typia.
But I would treat the build integration as part of the decision, not a footnote.

Final Thought

These tools overlap, but they live at different layers.

The hard part is not making seven validators compile. It is making seven validators mean the same thing.

So before comparing package size or benchmark screenshots, ask what the boundary needs to return and what runtime machinery is worth carrying.

Use the smallest model that still represents your boundary well.

Then, which one will you use?

Thank you for reading! 🤲

is-kit Reached 100 Stars ⭐🎉 Here’s What Changed Since 50

nyaomaru — Wed, 21 Oct 2026 15:08:25 +0000

Hoi hoi!

YAY! is-kit just reached 100 GitHub stars⭐ 🎉🎉🎉

When it reached 50 stars, I wrote about how we use it in a production TypeScript application serving more than 100,000 users. 👇

Real-world scale for type safety

nyaomaru

Aug 12

is-kit Reached 50 Stars ⭐ Here’s How We Use It in Production

#typescript #opensource #webdev #frontend

7 min read

I could write the same story again. But that would be boring. 😹

A lot has happened since then.

The library gained new APIs, some existing APIs became stricter, I started using it in more of my own OSS projects, and one real-world use case even exposed a type inference edge case in Effect.

So this time, instead of explaining the production adoption again, I want to look at:

What changed between 50 and 100 stars
Some of the most important APIs added since then
How I am actually using is-kit outside the original production application
A real bug report involving Effect.catchIf
What 100 stars means to me now

Let's dive in! 🔧

⭐ First, What Did 50 Stars Mean?

At 50 stars, the biggest thing I wanted to show was that is-kit was not only a toy project.

It was already being used in a real production application. 🚀

The application had repeated runtime checks like

typeof value === "string";
typeof value === "number";
value === null || value === undefined;

and several larger user-defined type guards for things like HTTP errors, literal unions, arrays, API values, and plain objects.

The interesting part was not that is-kit made those checks shorter.
The interesting part was that it gave them one reusable shape.

Small guards could be composed.

Application-owned helpers could sit between the library and feature code. And the result could still participate in normal TypeScript control flow.

That part has not changed.

But since 50 stars, the library itself has moved quite a bit. 👀

🔑 Property Refinement Became a First-Class Use Case

One thing I kept running into was this.

I already have a good type guard.
I just want to apply it to one property.

For example

declare const input: unknown;

Maybe I already know how to validate a string

import { isString } from "is-kit";

But now I want to express

"This object has a name property, and that property is a string."

That sounds simple, but there are actually a few different cases.

A required property is not the same as an optional property.
An array index is not the same as an object property.

And an optional property that becomes known to be defined should narrow differently from one that is still optional.

So is-kit added three property refinement helpers:

refineKey
refineDefinedKey
refineIndex

The idea is simple

Take a type guard you already trust and lift it onto a property or array element.

For example

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

const hasStringName = refineKey("name", isString);

Now the string guard is reusable at a deeper level instead of being rewritten inside another custom predicate.

This is a small API, but I like it because it follows the same design goal as the rest of is-kit.

Do not build one giant validator.

Build small checks that can be reused in normal TypeScript code.

🔍 Then `discriminatedUnion` Got Much More Serious

The biggest addition since the 50-star article is probably the exhaustive discriminated union API introduced in v1.15.0.

Consider a common TypeScript type

type Result = { ok: true; value: string } | { ok: false; error: string };

At runtime, validating this is not difficult.

You can check ok, then validate the corresponding fields.

But there is another question

Can TypeScript verify that the validator itself covers the whole union?

That is where discriminatedUnion comes in.

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

type Result = { ok: true; value: string } | { ok: false; error: string };

const resultUnion = discriminatedUnion<Result>();

export const isResult = resultUnion("ok", [true, false], {
  true: typedStruct<Extract<Result, { ok: true }>>()({
    ok: oneOfValues(true),
    value: isString,
  }),
  false: typedStruct<Extract<Result, { ok: false }>>()({
    ok: oneOfValues(false),
    error: isString,
  }),
});

The runtime behavior is useful.

But the more interesting part is the compile-time contract.

The builder checks things like:

Missing discriminant branches
Extra branches
Incompatible branch guards
Incomplete discriminant tuples

So if the union changes, the guard cannot silently stay incomplete.

That matters because one of the easiest ways for a hand-written type guard to become dangerous is drift.

The TypeScript type evolves.
The runtime guard does not.
And the compiler cannot normally tell you that the two are no longer aligned.

discriminatedUnion is one attempt to make that class of mistake harder.

💪 The Library Also Became Stricter

Not every improvement between 50 and 100 stars was a new feature.

A lot of work was about making existing behavior more precise.

For example, recent releases included fixes around:

recordOf literal-key narrowing
native Error brand checks
array guards with overridden iterators
exact struct validation
symbol-keyed struct schemas
cross-realm struct schemas

There was also more package-level testing.

is-kit now checks published-package behavior from both ESM and CommonJS TypeScript consumers, and also has Deno / JSR smoke coverage.

This part is less exciting to show in a code snippet.

But for a small library, I think it is important.

Making sure they behave correctly in weird JavaScript and TypeScript environments is where things become real.

🤖 I Started Using `is-kit` in Other OSS Too

Since reaching 50 stars, I've also started using is-kit more naturally in other OSS projects I maintain.

For example, in my changelog tooling of changelog-bot, I use define to keep small predicates reusable and composable instead of turning every runtime check into an isolated helper.

A simplified example looks like this 👇

import { define, oneOfValues } from "is-kit";

const CHANGELOG_SECTIONS = ["Added", "Changed", "Fixed", "Removed"] as const;

const isChangelogSection = define<(typeof CHANGELOG_SECTIONS)[number]>(
  oneOfValues(CHANGELOG_SECTIONS),
);

The exact code is not the important part.

What changed for me is that I no longer think

"I should use my library here."

I just reach for the guard I need.

A library starts becoming useful to its maintainer when it stops feeling like a demo of itself.

🚀 Then an `is-kit` Guard Ran Into an Effect Type Bug

This was one of the most interesting things that happened recently.

An is-kit user was using a type guard with Effect's catchIf.

Conceptually, the refinement looked like this 👇

(error: unknown): error is SomeError => ...

That is completely normal for is-kit.

In fact, unknown is exactly where the library is designed to start.

But with Effect.catchIf, that refinement could affect generic inference in an unexpected way.

The error channel could become widened to unknown.

The reported case resulted in this Effect PR 👏 And merged 🚀

fix(effect): Made catchIf NoInfer Refinement's first arg with generic Err param #9252

nikelborm posted on Oct 15, 2026

Type

[ ] Refactor
[ ] Feature
[x] Bug Fix
[ ] Optimization
[ ] Documentation Update

Description

When passing (arg: unknown) => arg is SomeError to some catchIfs, it turned the error channel into unknown. This PR makes only self's Error slot influence the types, regardless of the type taken by refinement.

Validation: the Channel, Effect, and Stream type-test files pass on TypeScript 5.9.3 and 6.0.3, and pnpm check passes. Temporarily reverting the implementation reproduces unknown error-channel widening in Channel data-last usage and in unrelated-refinement cases across all three APIs. The matching data-first refinement cases also pass without the fix. No tests were changed during maintainer validation.

Closes EFF-2233

View on GitHub

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.

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…

View on GitHub

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…

View on GitHub

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.

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…

View on GitHub

📝 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 👇

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

🧪 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…

View on GitHub

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

📚 Documentation Site · 🧭 Practical Guides

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…

View on GitHub

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

📚 Documentation Site · 🧭 Practical Guides

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…

View on GitHub

Thanks for reading! 🙌