Api Patterns

Detailed code examples for idiomatic KJ API usage patterns in workerd.

Unwrapping `kj::Maybe`

Always use KJ_IF_SOME. Never dereference directly.

cpp

// Correct:
KJ_IF_SOME(value, maybeValue) {
  use(value);  // value is a reference to the contained T
}

// Correct:
auto& value = KJ_ASSERT_NONNULL(maybeValue);  // asserts if maybeValue is none, otherwise gives T&
auto& value = KJ_REQUIRE_NONNULL(maybeValue);  // same but for preconditions
auto& value = JSG_REQUIRE_NONNULL(maybeValue, ErrorType, "message");  // same but with JavaScript exception type/message

// Wrong
auto& value = *maybeValue;      // doesn't exist
auto& value = maybeValue.value(); // not how KJ works

Maybe use maybe.map(fn) and maybe.orDefault(val) are useful for simple transforms/fallbacks.

When moving a value out of a kj::Maybe, use kj::mv() and remember to set the kj::Maybe to kj::none to avoid dangling references:

cpp

KJ_IF_SOME(value, maybeValue) {
  auto movedValue = kj::mv(value);  // move out of the Maybe
  maybeValue = kj::none;            // set Maybe to none to avoid dangling reference
  use(movedValue);
}

Unwrapping `kj::OneOf`

Always use KJ_SWITCH_ONEOF / KJ_CASE_ONEOF:

cpp

KJ_SWITCH_ONEOF(variant) {
  KJ_CASE_ONEOF(s, kj::String) { handleString(s); }
  KJ_CASE_ONEOF(i, int) { handleInt(i); }
}

Building Strings

Always use kj::str(), never std::to_string or + concatenation:

cpp

kj::String msg = kj::str("count: ", count, ", name: ", name);

Use kj::hex(n) for hex output. Extend with KJ_STRINGIFY(MyType) or a .toString() method. Use "literal"_kj suffix for kj::StringPtr literals (can be constexpr).

Scope-Exit Cleanup

Use KJ_DEFER or kj::defer():

cpp

KJ_DEFER(close(fd));                          // block scope
auto cleanup = kj::defer([&]() { close(fd); }); // movable, for non-block lifetimes

Also: KJ_ON_SCOPE_SUCCESS(...) and KJ_ON_SCOPE_FAILURE(...) for conditional cleanup.

Syscall Error Checking

Use KJ_SYSCALL, never manual errno checks:

cpp

int n;
KJ_SYSCALL(n = read(fd, buf, size));          // throws on error, retries EINTR
KJ_SYSCALL_HANDLE_ERRORS(fd = open(path, O_RDONLY)) {
  case ENOENT: return nullptr;                // handle specific errors
  default: KJ_FAIL_SYSCALL("open()", error);
}

Downcasting

Use kj::downcast<T> (debug-checked), not static_cast or dynamic_cast:

cpp

auto& derived = kj::downcast<DerivedType>(baseRef);  // asserts in debug builds

Use kj::dynamicDowncastIfAvailable<T> only for optimizations (returns null without RTTI).

Iteration Helpers

cpp

for (auto i: kj::zeroTo(n)) { ... }        // 0..n-1
for (auto i: kj::range(a, b)) { ... }      // a..b-1
for (auto i: kj::indices(array)) { ... }    // 0..array.size()-1

Unwrapping kj::Maybe

Unwrapping kj::OneOf