Basic Usage

These examples show how to use the NJ address geocoding domain in a minimal setup.

Basic Usage Examples

These examples show how to use the NJ address geocoding domain in a minimal setup.

Prerequisites

bun install

Examples

1. Simple Geocoding (simple-geocoding.ts)

Minimal example showing how to geocode a single address using the NJ API.

bun run examples/basic-usage/simple-geocoding.ts

What it demonstrates:

• Creating domain entities (AddressInput)
• Setting up adapters (HTTP client, geocoding service)
• Using a use case to perform business logic
• Error handling with custom domain errors

2. With Caching (with-caching.ts)

Shows how to add caching to reduce API calls and improve performance.

bun run examples/basic-usage/with-caching.ts

What it demonstrates:

• Adding cache adapter
• Cache-first strategy in use case
• Performance benefits (cache hit vs cache miss)
• Cache statistics monitoring

3. Batch Geocoding (batch-geocoding.ts)

Demonstrates processing multiple addresses efficiently.

bun run examples/basic-usage/batch-geocoding.ts

What it demonstrates:

• Bulk address processing
• Error handling for individual failures
• Progress tracking
• Performance optimization

Key Concepts

Factory Functions

All services use factory functions:

const httpClient = createFetchClient({ timeout: 5000 });
const geocodingService = createNjGeocodingClient(httpClient, logger);
const cache = createInMemoryCache();
const lookupAddress = createLookupAddressUseCase(geocodingService, cache);

Dependency Injection

Services receive their dependencies as parameters:

// Dependencies are explicit
const lookupAddress = createLookupAddressUseCase(
  geocodingService, // Can be real or fake
  cache, // Can be swapped for Redis, etc.
);

Port/Adapter Pattern

Domain defines interfaces (ports), adapters implement them:

// Domain port (interface)
interface GeocodingServicePort {
  geocodeAddress(address: AddressInput): Promise<GeocodingResult>;
}

// Adapter implementation
const njApiClient: GeocodingServicePort = createNjGeocodingClient(httpClient);

Next Steps

• See examples/custom-adapter/ for creating your own adapters
• See examples/extracting-domain/ for using the domain in other applications
• Read docs/ARCHITECTURE.md for detailed pattern explanations