DEV Community: Lucas

kokuin — Deterministic Hashing for JSON Values in TypeScript

Lucas — Mon, 27 Jul 2026 16:02:53 +0000

Ever needed a cache key from a complex API response, an idempotency key from a request body, or a way to detect identical payloads across services? If you reach for JSON.stringify plus a hash function, you'll discover edge cases you didn't account for: key order breaks your cache, circular objects crash your process, and BigInt throws before you even start.

Kokuin solves this with a single function: pass in any JSON-compatible value, get a deterministic SHA-256 hash back. No config, no options, no surprises.

The problem

JSON.stringify(value) + SHA-256(...) is the naive approach to hashing JSON values for cache keys, deduplication, or idempotency — but it breaks on key order, throws on circular references, and silently mis-handles types like undefined and BigInt. Most hashing libraries either operate on strings/blobs or require pulling in a heavy dependency tree.

What if you want a single function that takes any JSON-compatible value and returns a deterministic, cross-runtime hash — without worrying about key ordering, circular objects, or which crypto API is available?

Enter kokuin.

What is kokuin?

Kokuin is a zero-dependency TypeScript library (~200 LOC) that hashes JSON-compatible values deterministically. The entire API is a single function: hash(value).

import { hash } from 'kokuin'

hash({ a: 1, b: 2 })
hash({ b: 2, a: 1 })
// → same hash, key order doesn't matter

hash([1, 2, 3])
hash([3, 2, 1])
// → different hash — array order matters

Why not JSON.stringify + crypto?

Problem	`JSON.stringify` + crypto	kokuin
Key ordering	`{b:2, a:1}` ≠ `{a:1, b:2}`	Normalized — same hash
Circular references	Throws	Gracefully resolved
`undefined`	`JSON.stringify({a: undefined})` → `'{}'`	Preserved as a value
`BigInt`	Throws	Supported
`-0 === 0`	`JSON.stringify(-0)` → `'-0'`	Normalized to `0`
Cross-runtime	Depends on `crypto.subtle` vs `createHash`	Same pure JS SHA-256 everywhere

How it works

Under the hood, kokuin builds a canonical binary representation of the value:

Serialize the value to a canonical byte buffer — type tags (1 byte), numbers (Float64), strings (UTF-8 with length prefix), sorted keys for objects
Hash the buffer with a hand-written SHA-256 (pure JS, zero dependencies, works on Node, Bun, Deno, and browsers)

// The type tags keep values distinct
hash(1)     !== hash('1')    // number ≠ string
hash(1n)    !== hash(1)      // BigInt ≠ number
hash(null)  !== hash(undefined)
hash(false) !== hash(0)

Circular references

The one place kokuin deliberately goes beyond JSON:

const a: any = {}
a.self = a

hash(a) // does not throw — resolves the cycle

toJSON() support

Any object with a toJSON() method is hashed via its return value — the same contract JSON.stringify follows:

class Money {
  constructor(private cents: number) {}
  toJSON() { return { cents: this.cents } }
}

hash(new Money(500)) === hash({ cents: 500 }) // true

A guard prevents built-in types (like Date) that have toJSON on their prototype from sneaking through:

hash(new Date()) // Error: Cannot hash Date values

What it doesn't do

Kokuin intentionally rejects types where "identity" in JavaScript is unreliable:

hash(new Map())     // Error
hash(new Set())     // Error
hash(new Date())    // Error
hash(/abc/)         // Error
hash(new Error())   // Error
hash(() => {})      // Error
hash(Symbol())      // Error

These aren't oversights. A class name survives minification only by luck; instanceof can fail across realms (iframes, workers, multiple copies of the package). Instead of silently producing a shaky hash, kokuin asks you to convert explicitly:

hash(Object.fromEntries(myMap))          // Map → object
hash([...mySet].sort())                  // Set → sorted array
hash(myDate.toISOString())               // Date → string
hash({ message: err.message })           // Error → plain object

Why pure JS SHA-256?

Zero dependencies means zero node_modules overhead, zero polyfill concerns, and zero runtime-specific branches. The SHA-256 implementation fits in ~100 lines of plain bitwise operations. The same hash on Node, Bun, Deno, and every modern browser.

Use cases

Cache keys — hash complex query parameters deterministically, regardless of how the object is constructed
Deduplication — detect identical payloads across requests
Idempotency — generate idempotency keys from request bodies
Structural identity — compare deeply nested data structures by their hash

The name

"Kokuin" (刻印) means "engraving" or "stamp" in Japanese — a permanent, deterministic mark.

Try it

npm install kokuin

pnpm add kokuin

yarn add kokuin

GitHub: https://github.com/smokeeaasd/kokuin
npm: https://npmjs.com/package/kokuin

houhou — Resilience Policies for TypeScript Async Functions

Lucas — Thu, 23 Jul 2026 21:05:01 +0000

The problem

Most resilience libraries in the TypeScript ecosystem are tied to HTTP clients (axios-retry, p-retry, Polly.js) or require wrapping your function in a class with a .execute() ceremony. What if you just want to wrap any async function — a database query, an internal service call, a file operation — with retry logic, a timeout, and a circuit breaker, without pulling in heavy dependencies?

Enter houhou.

What is houhou?

Houhou is a zero-dependency TypeScript library (~500 LOC) that wraps any async function with composable resilience policies. The wrapped function keeps the exact same signature — you call it like the original.

import { task } from 'houhou'

const charge = task(chargeCard)
  .retry(3)
  .timeout(10_000)
  .fallback(() => ({ status: 'pending' }))

await charge(account, amount)

Policies at a glance

Retry

Re-execute on failure with fixed or exponential backoff:

task(fetchUser).retry(3) // shorthand

task(fetchUser).retry({
  attempts: 5,
  backoff: 'exponential',
  jitter: true,
  delay: 500
})

Timeout

Reject if the function doesn't complete in time:

task(fetchUser).timeout(5000)

Fallback

Run an alternative function on failure:

task(fetchUser).fallback(() => loadFromCache(id))

Circuit Breaker

Prevent repeated calls to an unhealthy service:

task(queryDb).circuitBreaker({
  failureThreshold: 5,
  successThreshold: 2,
  resetTimeout: 30_000
})

Delay

Wait before execution:

task(syncData).delay(1000)

Policy ordering matters

Policies are nested: the last method called wraps the previous ones. Execution order is reverse of declaration order.

task(fn).retry(3).timeout(1000)
// → timeout wraps retry
// → function runs → retry on failure (up to 3 times) → 1s total timeout
// → if the timeout fires, there are no more retries

task(fn).timeout(1000).retry(3)
// → retry wraps timeout
// → function runs → 1s timeout → if timeout fires, retry catches it
// → the whole cycle repeats up to 3 times

Type safety — policy lock

Each method is lockable. TypeScript prevents configuring the same policy twice at compile time, and a runtime Set guard enforces it at runtime:

const t = task(fn).retry(3)

// @ts-expect-error — 'retry' is already locked
t.retry(2) // throws at runtime too

Cancellation with AbortSignal

Houhou uses AbortController to cancel operations when a timeout fires or an external signal is provided. The AbortSignal is passed as the last argument to your function:

const fn = (url: string, signal?: AbortSignal) => fetch(url, { signal })

task(fn).timeout(5000)('https://api.example.com')
// → timeout fires → controller.abort() → fetch is cancelled

You can also pass your own external signal:

const controller = new AbortController()
const promise = task(fn).timeout(5000).retry(3)('url', controller.signal)

controller.abort() // cancels everything

Composition example

Policies chain fluently in any order:

const resilient = task(callApi)
  .retry({ attempts: 3, backoff: 'exponential' })
  .timeout(5000)
  .fallback(loadFromCache)
  .circuitBreaker({ failureThreshold: 5, successThreshold: 2, resetTimeout: 30_000 })
  .delay(100)

The name

"houhou" means "method" or "way of doing" in Japanese — fitting for a library about how you execute your functions.

Try it

npm install houhou
# or
pnpm add houhou
yarn add houhou

GitHub: https://github.com/smokeeaasd/houhou
npm: https://npmjs.com/package/houhou