npm package: @postrust/netherlands
Description: Never pay or wait for slow APIs to lookup a Dutch address anymore!
Latest version: 0.1.1

# @postrust/netherlands

⚡ **Ultra-fast Dutch address lookup** - Find street names and cities from postal codes and house numbers in **0.1ms**.

A blazingly fast WebAssembly-powered package that provides instant address lookups for all **9.8 million unique addresses** in the Netherlands, compressed into just **4.1MB**.

## 🚀 Features

- **Lightning Fast**: Lookup times as low as 0.1ms
- **Complete Coverage**: All 9.8 million Dutch addresses included
- **Tiny Footprint**: Entire dataset compressed to just 4.1MB
- **Zero Dependencies**: Self-contained WASM module
- **Browser & Node.js**: Works in both environments
- **Memory Efficient**: Uses FST (Finite State Transducer) data structures
- **Type Safe**: Full TypeScript support

## 📦 Installation

```bash
npm install @postrust/netherlands
```

**Note**: This package requires a bundler like Vite, Webpack, or Rollup to work properly.

## 🔧 Usage

### Basic Example

```javascript
import { AddressLookup } from "@postrust/netherlands";

// Initialize the lookup engine
const lookup = new AddressLookup();

// Find address details
const result = lookup.lookup("1012JS", 25);

console.log(result);
// Output:
// {
//   postcode: "1012JS",
//   straat: "Damrak",
//   huisnummer: 25,
//   woonplaats: "Amsterdam"
// }
```

### TypeScript

```typescript
import { AddressLookup } from "@postrust/netherlands";

interface LookupResult {
  postcode: string;
  straat: string;
  huisnummer: number;
  woonplaats: string;
}

const lookup = new AddressLookup();
const result: LookupResult | null = lookup.lookup("1012JS", 25);

if (result) {
  console.log(
    `Found: ${result.straat} ${result.huisnummer}, ${result.woonplaats}`,
  );
} else {
  console.log("Address not found");
}
```

### Node.js

```javascript
const { AddressLookup } = require("@postrust/netherlands");

const lookup = new AddressLookup();
const result = lookup.lookup("1012 JS", 25); // Spaces are automatically handled

if (result) {
  console.log(result);
}
```

## 📝 API Reference

### `AddressLookup`

#### Constructor

```typescript
new AddressLookup(): AddressLookup
```

Creates a new address lookup instance. The constructor automatically decompresses and initializes the address database.

#### Methods

##### `lookup(postcode: string, houseNumber: number): LookupResult | null`

Looks up an address by postal code and house number.

**Parameters:**

- `postcode` (string): Dutch postal code (e.g., "1012JS" or "1012 JS")
- `houseNumber` (number): House number

**Returns:**

- `LookupResult` object if found, `null` if not found

**LookupResult Interface:**

```typescript
interface LookupResult {
  postcode: string; // Normalized postal code (e.g., "1012JS")
  straat: string; // Street name (e.g., "Damrak")
  huisnummer: number; // House number (e.g., 25)
  woonplaats: string; // City/town name (e.g., "Amsterdam")
}
```

## 🎯 Examples

### Batch Lookups

```javascript
const lookup = new AddressLookup();

const addresses = [
  ["1012JS", 25],
  ["2511CS", 10],
  ["3511NV", 42],
];

const results = addresses
  .map(([postcode, number]) => lookup.lookup(postcode, number))
  .filter((result) => result !== null);

console.log(results);
```

### Address Validation

```javascript
function validateDutchAddress(postcode, houseNumber) {
  const lookup = new AddressLookup();
  const result = lookup.lookup(postcode, houseNumber);

  return {
    isValid: result !== null,
    details: result,
  };
}

const validation = validateDutchAddress("1012JS", 25);
console.log(validation.isValid); // true
```

### Form Integration

```javascript
// Example with form validation
document.getElementById("lookup-btn").addEventListener("click", () => {
  const postcode = document.getElementById("postcode").value;
  const houseNumber = parseInt(document.getElementById("house-number").value);

  const lookup = new AddressLookup();
  const result = lookup.lookup(postcode, houseNumber);

  if (result) {
    document.getElementById("street").value = result.straat;
    document.getElementById("city").value = result.woonplaats;
  } else {
    alert("Address not found");
  }
});
```

## ⚡ Performance

- **Lookup Speed**: 0.1ms - 1ms per lookup
- **Memory Usage**: ~40MB (runtime memory)
- **Bundle Size**: 4.1MB (compressed dataset)
- **Coverage**: 100% of Dutch addresses (9.8M addresses)

## 🏗️ Technical Details

This package uses advanced data compression and indexing techniques to achieve optimal performance. The WebAssembly module provides native-speed lookups while maintaining a compact bundle size.

## 🌍 Browser Support

- Chrome/Edge 57+
- Firefox 52+
- Safari 11+
- Node.js 12+

**Requirements**: Requires a modern bundler (Vite, Webpack, Rollup, etc.)

## 📄 License

MIT

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📞 Support

For questions or issues, please contact us at: **support@joyso.me**

---

**Made with ❤️ and ⚡ by Joysome**