DEV Community: Henrique Sasaki Yuya

A type-safe GitHub Actions workflow library in TypeScript

Henrique Sasaki Yuya — Sat, 16 May 2026 10:10:01 +0000

tl;dr

I built ghawb, a TypeScript-first authoring library for GitHub Actions workflows and composite actions. It keeps GitHub Actions explicit, but moves workflow authoring into typed, validated, testable code. You still commit normal YAML; you just do not have to hand-author all of it.

Prologue

I like GitHub Actions.

I do not like finding out that I made a trivial mistake only after I pushed a branch, waited for CI to boot, and then watched a workflow fail because I wrote the wrong shape of permissions, mixed up a trigger filter, or typoed an output reference buried in YAML.

That feedback loop is too late.

So I built ghawb: a TypeScript library for authoring GitHub Actions workflows and composite actions with:

type-safe builders
validation at construction time
deterministic YAML rendering
source-first distribution through JSR

The idea is simple:

if a workflow is code, then at least some workflow mistakes should be regular programming errors

Instead of treating .github/workflows/*.yml as the source of truth, ghawb treats TypeScript as the source and renders committed YAML from it.

The problem I wanted to fix

GitHub Actions YAML has an awkward failure mode.

A lot of mistakes are not conceptually complicated, but they are still easy to make:

invalid combinations of trigger fields
blank or malformed IDs
step output references that point to nothing
reusable workflow jobs using fields GitHub does not allow there
matrix definitions that look plausible but are structurally wrong

None of these are interesting problems.

They are structural mistakes.

And structural mistakes are exactly the kind of thing a type system and a validation layer should help with.

What `ghawb` looks like

Here is a small CI workflow:

import { createJobId, createWorkflowId, defineWorkflow } from "@ghawb/sdk";
import { nodeCi } from "@ghawb/job-helpers";

const workflow = defineWorkflow({
  id: createWorkflowId("ci"),
  name: "CI",
})
  .onPush({ branches: ["main"] })
  .onPullRequest({ branches: ["main"] })
  .addJob(createJobId("test"), (job) => {
    job.runsOn("ubuntu-latest").apply(nodeCi({ nodeVersion: "24" }));
  })
  .build();

Then render it with the CLI:

bun x @ghawb/cli render --input workflows/ci.ts --output .github/workflows/ci.yml

The output is deterministic, so you can commit the generated YAML and review it normally.

The important part is not that YAML is generated.

The important part is that the authoring surface is now typed, validated, and testable.

The goal is not to hide GitHub Actions

I was not trying to pretend GitHub Actions is something other than GitHub Actions.

The goal is narrower:

keep the GitHub Actions model explicit
catch structural mistakes earlier
make large workflows easier to compose and review
preserve committed YAML as a normal repository artifact

That constraint matters.

I did not want a magical DSL that hides the underlying workflow model so aggressively that users stop knowing what GitHub Actions will actually do.

So ghawb stays close to the platform:

triggers are still triggers
jobs are still jobs
reusable workflows are still reusable workflows
rendered output is still plain GitHub Actions YAML

It is not a replacement for understanding GitHub Actions.

It is a better place to author GitHub Actions.

What kind of mistakes it catches

This is where the library becomes useful in day-to-day work.

ghawb validates things like:

identifier format for workflow IDs and job IDs
invalid trigger/filter combinations
duplicate or malformed step IDs
references to undeclared step outputs in job outputs
unsupported fields on reusable workflow jobs
invalid matrix declarations
invalid environment/config shapes

For example, if a job output references a step output that was never declared, that should not be something you discover only after pushing a branch.

If a reusable workflow job includes a field GitHub does not allow in that context, that should be rejected while the workflow is still being built.

If a matrix definition has the wrong shape, that should be treated as an authoring error, not a CI surprise.

So instead of:

CI failed 3 minutes later because the workflow shape was invalid

You get:

this workflow definition is invalid while you are still authoring it

That is a much better loop.

Why TypeScript

The value is not just type safety in the abstract.

The value is that workflow definitions become regular software artifacts.

That means you can:

factor repeated workflow logic into named helpers
test workflow construction
inject render-time config
use editor completion and refactoring
keep reusable CI paths small and explicit
review generated YAML without manually maintaining all of it

A growing YAML file is hard to refactor safely.

A TypeScript module can be composed, tested, and reviewed with the same tools you already use for application code.

How it differs from heavier CI abstractions

ghawb is intentionally not trying to be a new CI system.

It does not replace GitHub Actions with a different execution model.

It does not try to hide the workflow schema behind a completely separate abstraction.

It is closer to a typed authoring and rendering layer:

TypeScript is the source
GitHub Actions YAML is the committed artifact
GitHub Actions remains the runtime
the rendered output stays reviewable

That distinction is important.

Some tools give you a more powerful abstraction over builds or pipelines. That can be useful, but it also creates a larger conceptual boundary between the code you write and the workflow GitHub actually runs.

ghawb is deliberately smaller than that.

Its job is to make GitHub Actions authoring safer and more composable without making the resulting workflow feel mysterious.

Package boundaries

I wanted the core package to stay narrow.

The main package, @ghawb/sdk, is for:

workflow builders
expressions
rendering payloads
validation

More optional or opinionated parts live in separate packages:

@ghawb/job-helpers for higher-level helpers like Node CI setup
@ghawb/typed-actions for typed wrappers around common actions
@ghawb/composite-actions for authoring action.yml
@ghawb/cli for rendering source modules into YAML
@ghawb/reusable-workflow-import for bringing existing reusable workflow YAML into the typed world without pushing YAML parsing into the SDK core

That split was intentional.

Users can start with a small, explicit core and opt into the more opinionated layers only when they help.

Example: a reusable, typed CI path

This is the sort of thing I wanted to make boring:

import { createJobId, createWorkflowId, defineWorkflow } from "@ghawb/sdk";
import { nodeCi } from "@ghawb/job-helpers";

export default defineWorkflow({
  id: createWorkflowId("ci"),
  name: "CI",
})
  .onPush({ branches: ["main"] })
  .onPullRequest({ branches: ["main"] })
  .concurrency({
    group: "ci-${{ github.ref }}",
    cancelInProgress: true,
  })
  .addJob(createJobId("check"), (job) => {
    job
      .runsOn("ubuntu-latest")
      .permissions({ contents: "read" })
      .apply(nodeCi({ nodeVersion: "24" }));
  })
  .build();

This is not flashy.

That is the point.

CI should not be a place where I spend attention on preventable formatting and shape mistakes.

Why JSR-only distribution

This project ships through JSR only.

That decision comes from what the project actually is:

source-first TypeScript packages
Bun as the default development runtime
continued Deno support

The current compatibility policy is:

Bun 1.x
Deno 2.x

That is a deliberately smaller promise surface than “every JavaScript runtime forever.”

For this project, JSR fits better than carrying extra packaging complexity just to preserve compatibility expectations that were not helping the product.

Getting started

The repository is here:

GitHub: https://github.com/moriturus/ghawb.ts

Start with:

bunx jsr add @ghawb/sdk

If you want the CLI too:

bunx jsr add @ghawb/cli

Today, that install path does not create a local ghawb executable because JSR's npm compatibility tarballs currently drop package.json#bin.

The working invocation is:

bun x @ghawb/cli render --input workflows/ci.ts

And if you are on Deno:

deno add jsr:@ghawb/sdk

The project README includes the current package layout and examples for:

workflow authoring
CLI rendering
typed action wrappers
composite action authoring
reusable workflow import

Closing thought

If you have been treating GitHub Actions YAML as “just one of those things you have to suffer through,” I think there is real value in moving the authoring experience into typed code while still keeping the final YAML explicit and reviewable.

The goal is not to make GitHub Actions disappear.

The goal is to make preventable workflow mistakes show up earlier, closer to where they are created.

I Built a Type-Safe SI Unit Library in Swift — And the Compiler Catches Your Physics Mistakes

Henrique Sasaki Yuya — Tue, 24 Mar 2026 11:06:02 +0000

You've seen this bug before:

let speed = distance + time  // Compiles. Runs. Produces nonsense.

Or worse — the Mars Climate Orbiter kind, where pound-seconds and newton-seconds silently mix, and a $327 million spacecraft burns up in the atmosphere.

I built SystemeInternational to make that class of bug extinct in Swift — at compile time, with zero runtime cost.

What If the Type System Knew Physics?

SystemeInternational encodes physical dimensions, units, and even the distinction between absolute positions and intervals into Swift's type parameters. Every quantity is:

Quantity<Scalar, Unit, Space>

That's it. 8 bytes. The Unit and Space are phantom types — they exist only at compile time and vanish completely in the binary.

import UnitesSI

let distance = try Quantity<Double, Kilometer, Linear>(36)
let time     = try Quantity<Double, Second, Linear>(3_600)
let speed    = try distance / time  // ✅ Compiles — dimension is Length/Time

let nonsense = try distance + time  // ❌ Compile error — no overload

No runtime checks. No if unit == .meter. The compiler simply won't let you add meters to seconds.

Five Things That Make This Different

1. Hertz ≠ Becquerel (Even Though They're Both 1/s)

The SI system has unit pairs with identical dimensions but completely different physical meanings. Most unit libraries treat them as interchangeable. SystemeInternational doesn't:

import UnitesSI

let reciprocalRate = try Quantity<Double, CanonicalUnit<QuotientDimension<Dimensionless, TimeDimension>>, Linear>(50)
let frequency = reciprocalRate.interpreted(as: Hertz.self)
let activity = reciprocalRate.interpreted(as: Becquerel.self)

print(frequency.value)     // 50.0
print(activity.value)      // 50.0

Hertz and Becquerel are different public types even though they share the same exponent dimension. The same idea applies to angular frequency (rad/s) versus cyclic frequency (Hz), and to Gray/Sievert (absorbed dose vs. equivalent dose). The library respects BIPM's semantic distinctions.

2. You Can't Add Two Temperatures

Adding 20°C + 25°C is physically meaningless — you can't add two absolute positions. But subtracting them to get a temperature difference is perfectly valid.

SystemeInternational models this with affine space algebra:

import UnitesSI

let room    = try CelsiusTemperatureValue(20)       // Affine (absolute position)
let boiling = try CelsiusTemperatureValue(100)       // Affine
let rise    = try boiling - room                     // ✅ Linear (interval): 80°C

let shifted = try room + rise                        // ✅ Affine: 100°C
let oops    = try room + boiling                     // ❌ Compile error

Expression	Result	Meaning
Point − Point	Vector	Distance between positions
Point + Vector	Point	Shift a position
Point + Point	compile error	Adding positions is meaningless

And yes — it validates against absolute zero at runtime:

try CelsiusTemperatureValue(-274)  
// throws QuantityError.belowAbsoluteZero

3. Exact Integer Arithmetic

Need precise timing in embedded systems? Use integer scalars:

import UnitesSI

let duration = try Quantity<Int, Millisecond, Linear>(exactly: 2_000)
let seconds  = try duration.convertedIfExactly(to: Second.self)
print(seconds.exactValue)  // Optional(2)

let oneMeter = try Quantity<Int, Meter, Linear>(exactly: 1)
try oneMeter.convertedIfExactly(to: Kilometer.self)  // throws — 0.001 isn't an Int

No silent truncation. No floating-point drift. It throws when the math doesn't work out exactly.

4. Rational Scale Factors (Not Floating-Point)

Unit scales are stored as rational numbers with decimal exponents, preserving precision that Double arithmetic would destroy:

// 1° = π/180 radians, stored as:
UnitScale(numerator: 3_141_592_653_589_793, denominator: 180, decimalExponent: -15)

// 1 eV = 1.602176634 × 10⁻¹⁹ J (exact by 2019 SI redefinition), stored as:
UnitScale(numerator: 1_602_176_634, denominator: 1, decimalExponent: -28)

This means conversions like Degree → Radian or ElectronVolt → Joule carry the full precision of the defining constants.

5. Thin Abstractions the Optimizer Can See Through

Hot-path accessors and arithmetic are annotated with @inlinable, so the compiler can inline across module boundaries and apply full optimizations in Release builds:

Benchmark	Debug	Release	Speedup
`convert_kilometer_to_meter`	225 ns/op	3 ns/op	~75×
`semantic_lumen_operator`	291 ns/op	83 ns/op	~3.5×
`semantic_lux_operator`	435 ns/op	155 ns/op	~2.8×

Same-unit operations like linear_add_same_unit and multiply_canonical_area measured 0 ns/op in Release — the optimizer eliminated them entirely via dead code elimination, confirming that the phantom-type abstractions add no barriers to standard compiler optimizations. Real-world code that uses the results will still pay the cost of a bare Double operation, but nothing more.

The key takeaway: the type-safety layer is transparent to the optimizer. You get compile-time unit checking without runtime overhead beyond the underlying arithmetic.

The Module Architecture

SystemeInternational is split into focused, composable modules:

UnitesSI              ← Main facade (import this)
├── UnitesDeBaseDuSI  ← Core: Quantity, dimensions, 7 base units
├── PrefixesDuSI      ← All 20 SI prefixes (Quetta → Quecto)
└── UnitesDeriveesDuSI← Named derived units + temperature scales

UtiliseesNonSI        ← 16 BIPM-accepted non-SI units
UnitesSICompat        ← Foundation.Measurement bridge
UtiliseesNonSICompat  ← Non-SI Foundation bridge

For most use cases, import UnitesSI gives you everything. The modular design means you only link what you use.

Quick Tour

Prefixed Units — All 20 SI Prefixes

import UnitesSI

let distance = try Quantity<Double, Kilometer, Linear>(5.2)
let tiny     = try Quantity<Double, Microgram, Linear>(0.3)
let huge     = try Quantity<Double, Gigahertz, Linear>(2.4)

// Mass follows SI convention: Kilogram is base, but prefixes come from Gram
let mg = try Quantity<Double, Milligram, Linear>(500)
print(mg.converted(to: Kilogram.self).value)  // 0.0005

Derived Units with Semantic Operators

import UnitesSI

let intensity  = try Quantity<Double, Candela, Linear>(1_200)
let solidAngle = try Quantity<Double, Steradian, Linear>(1.5)
let luminous   = try intensity * solidAngle  // → Lumen

let area = try Quantity<Double, Meter, Linear>(3) * Quantity<Double, Meter, Linear>(2)  // → m²
let illuminance = try luminous / area  // → Lux

Foundation.Measurement Interop

import Foundation
import UnitesSICompat

// SystemeInternational → Foundation
let road = try Quantity<Double, Kilometer, Linear>(12.3).foundationMeasurement()
print(road.unit.symbol)  // "km"

// Foundation → SystemeInternational
let temp = try Measurement(value: 25, unit: UnitTemperature.celsius)
    .absoluteTemperature(as: DegreeCelsius.self)
print(temp.converted(to: Kelvin.self).value)  // 298.15

Non-SI Accepted Units

import UtiliseesNonSI

let water      = try Quantity<Double, Milliliter, Linear>(500)
let rightAngle = try Quantity<Double, Degree, Linear>(90)
let gain       = try Quantity<Double, Decibel, Linear>(20)

print(water.converted(to: Liter.self).value)       // 0.5
print(rightAngle.converted(to: Radian.self).value) // 1.5707963267948966

Why "Systeme International"?

The name comes from the French Système International d'Unités — the official name of the SI system, maintained by the Bureau International des Poids et Mesures (BIPM). The module names follow the same convention: Unités de base du SI, Préfixes du SI, Utilisées non-SI.

Requirements & Installation

Swift 6.2+
No dependencies — pure Swift, no external packages

// Package.swift
dependencies: [
    .package(url: "https://github.com/moriturus/SystemeInternational.git", from: "0.1.0"),
]

306 tests. 100% coverage target. Apache 2.0 licensed.

If you work with physical quantities in Swift — whether it's scientific computing, IoT sensor data, robotics, game physics, or just making sure your app doesn't confuse kilometers with miles — give SystemeInternational a look.

⭐ Star the repo on GitHub if you think the type system should catch your physics bugs.

moriturus / SystemeInternational

SI Units for Swift: Strongly typed, static type safe, (almost) zero-cost abstruction

SystemeInternational

A type-safe SI unit system for Swift — catch unit misuse at compile time, not at runtime.

Overview

SystemeInternational models physical quantities, units, and dimensions using Swift's strong type system. Units are marker types — you never instantiate Meter() directly; instead you write Quantity<Double, Meter, Linear> or refer to Meter.self.

Key characteristics:

Different physical meanings are different types — no raw Double or typealias ambiguity
Unit conversions are type-checked and use exact rational scale metadata
Named SI derived units with distinct semantics (Hertz vs Becquerel) are never implicitly convertible
Affine-space algebra distinguishes absolute positions (points) from intervals (vectors) at compile time
Temperature uses the same unified Quantity type with a Space parameter, not a separate type hierarchy
Foundation Measurement interoperability is available through dedicated compatibility modules

Requirements

Swift 6.2+

Installation

Add the package to your Package.swift:

dependencies: [
    .package(url: "https://github.com/moriturus/SystemeInternational.git

…

View on GitHub

P.S. To our friends still measuring things in feet, inches, pounds, ounces, fluid ounces (US), fluid ounces (UK), short tons, long tons, nautical miles, statute miles, furlongs, and—my personal favorite—slugs: the year is 2026. The rest of the world moved on. Even the UK went metric (mostly). Even NASA went metric (after that incident). This library does not, and will never, include Foot, Slug, or Hogshead. You know where to find Foundation.Measurement — it's right there, waiting, with all 14 of your competing gallon definitions. 🫡

Ktra: Your Little Cargo Registry

Henrique Sasaki Yuya — Thu, 22 Oct 2020 16:38:11 +0000

Today, I introduce an application to provide a private cargo registry, Ktra.

Ktra is a minimum implementation of an Alternate Registry that is introduced for non-public crates in Rust/Cargo 1.34.

This app is under heavy development so any contributions and/or feature requests are welcome!