Module: Jpzip

Defined in:
lib/jpzip.rb,
lib/jpzip/http.rb,
lib/jpzip/cache.rb,
lib/jpzip/types.rb,
lib/jpzip/client.rb,
lib/jpzip/version.rb

Overview

Jpzip is the Ruby SDK for the jpzip postal-code dataset (jpzip.nadai.dev). The SDK fetches normalized JSON from the CDN, keeps a per-prefix in-memory LRU, and optionally backs that with a user-supplied persistent cache.

Defined Under Namespace

Modules: Http Classes: Cache, Client, Endpoints, InvalidPrefixError, MemoryLRU, Meta, Town, ZipcodeEntry

Constant Summary collapse

ZIP_REGEX = 
/\A\d{7}\z/.freeze
PREFIX_REGEX = 
/\A\d{1,3}\z/.freeze
VERSION = 
"0.1.1"
SPEC_VERSION =

SpecVersion is the jpzip protocol version this SDK targets.

"1.0"
DEFAULT_BASE_URL =

DefaultBaseURL is the production CDN origin.

"https://jpzip.nadai.dev"

Class Method Summary collapse

Class Method Details

.configure(**opts) ⇒ Object

Override the singleton with a configured Client. Useful when the app wants to share an L2 cache through the module-level helpers.



50
51
52
 
# File 'lib/jpzip.rb', line 50

def configure(**opts)
  @default_client = Client.new(**opts)
end

.lookup(zipcode) ⇒ Object

Convenience shortcuts delegating to a process-wide default Client. The singleton uses L1 only — for L2 caches construct your own Client.



23
24
25
 
# File 'lib/jpzip.rb', line 23

def lookup(zipcode)
  default_client.lookup(zipcode)
end

.lookup_all ⇒ Object 



31
32
33
 
# File 'lib/jpzip.rb', line 31

def lookup_all
  default_client.lookup_all
end

.lookup_group(prefix) ⇒ Object 



27
28
29
 
# File 'lib/jpzip.rb', line 27

def lookup_group(prefix)
  default_client.lookup_group(prefix)
end

.meta ⇒ Object 



39
40
41
 
# File 'lib/jpzip.rb', line 39

def meta
  default_client.meta
end

.preload(scope) ⇒ Object 



35
36
37
 
# File 'lib/jpzip.rb', line 35

def preload(scope)
  default_client.preload(scope)
end

.reset_default_client! ⇒ Object

Replace the singleton — mainly for tests.



44
45
46
 
# File 'lib/jpzip.rb', line 44

def reset_default_client!
  @default_client = nil
end

.valid_zipcode?(str) ⇒ Boolean

Returns true iff str is a syntactically valid 7-digit zipcode (no network call).

Returns:

  • (Boolean) 


17
18
19
 
# File 'lib/jpzip.rb', line 17

def valid_zipcode?(str)
  ZIP_REGEX.match?(str.to_s)
end