🧱 Address blocks

Address blocks are reusable postal-code lookup operations exported through blocks from @nodeblocks/backend-sdk. They perform the driver lookup and return neverthrow results instead of throwing expected lookup failures.

Inventory

Export	Kind	Inputs	Result / behavior / errors
FindAddressServiceError	Error class	Message, optional data	Wraps unexpected driver failures.
AddressNotFoundError	Error class	Message, optional data	Represents a driver lookup that has no address.
Address	Type	None	{prefecture, city, postalCode, town?} or null.
FindAddressDriver	Type	Postal code	Contract for findAddress(postalCode).
findAddress	Async function	Driver, postal code, optional cache	Normalizes hyphens, uses cache, and returns an address result.

Details

FindAddressServiceError

Implementation

Extends BlockError and has no intrinsic HTTP status. findAddress returns this error when the driver rejects with a non-BlockError; findAddressRoute maps it to 500.

AddressNotFoundError

Implementation

Extends FindAddressServiceError and has no intrinsic HTTP status. A null driver result becomes this error in findAddress; findAddressRoute maps it to 404.

Address

Implementation

The public type is {prefecture, city, postalCode, town?} | null. Drivers may return null, but findAddress converts that result to err(AddressNotFoundError); its successful result therefore contains an address object.

Used by FindAddressDriver, findAddress, and the findAddressCache configuration accepted by the Address service.

FindAddressDriver

Implementation

Hosts provide findAddress(postalCode: string): Promise<Address>. The Japan Post driver satisfies this contract. The Address service injects a driver as findAddressDriver, and findAddress consumes it.

findAddress

Implementation

Signature: findAddress(findAddressDriver, postalCode, cache?): Promise<Result<Address, FindAddressServiceError>>, where cache is ReturnType<typeof createCache<string, Address>>.

It removes every hyphen before cache and driver access, but does not validate the resulting postal code; the injected driver determines input validity. A truthy cached value is returned directly. On a cache miss it calls the driver, writes the driver result to the cache, and converts a null result into err(AddressNotFoundError('No matching address found.')). A non-BlockError rejection becomes err(FindAddressServiceError('Failed to find address.', {cause})); an existing BlockError is preserved.

Because the cache-hit check is truthiness-based, a cached null does not produce a hit. Used by findAddressRoute, which maps AddressNotFoundError to 404 and FindAddressServiceError to 500.