npm package: @huckleberry-inc/address-worldwide
Description: Address formatting library compatible with @shopify/address, using local YAML data
Author: Huckleberry Inc.
Latest version: 0.0.1

# @huckleberry-inc/address-worldwide

[Shopify/worldwide](https://github.com/Shopify/worldwide) のローカル YAML データを使用した `@shopify/address` の代替パッケージです。オフラインで動作します。

## インストール

```bash
npm install @huckleberry-inc/address-worldwide
```

## 使い方

### AddressFormatter クラス

```typescript
import AddressFormatter from '@huckleberry-inc/address-worldwide';

const formatter = new AddressFormatter('ja');

// 全国リストを取得（ローカライズ名でソート済み）
const countries = await formatter.getCountries();

// 特定の国を取得
const japan = await formatter.getCountry('JP');

// 住所をフォーマット
const formatted = await formatter.format({
  firstName: '太郎',
  lastName: '山田',
  address1: '永田町2-3-1',
  city: '千代田区',
  province: 'JP-13',
  zip: '100-0014',
  country: 'JP',
});
// => ['日本 〒100-0014', '東京都 千代田区', '永田町2-3-1', '山田 太郎様']

// フォーム用のフィールド順序を取得
const fields = await formatter.getOrderedFields('JP');

// ロケールを更新
formatter.updateLocale('en');

// キャッシュをリセット
AddressFormatter.resetCache();
```

### スタンドアロン関数

```typescript
import { formatAddress, buildOrderedFields } from '@huckleberry-inc/address-worldwide';
import type { Address, Country } from '@huckleberry-inc/address-worldwide';

const country: Country = await formatter.getCountry('US');
const address: Address = {
  firstName: 'John',
  lastName: 'Doe',
  address1: '123 Main St',
  city: 'San Francisco',
  province: 'CA',
  zip: '94102',
  country: 'US',
};

const formatted = formatAddress(address, country);
const fields = buildOrderedFields(country);
```

## API

### AddressFormatter

| メソッド | 戻り値 | 説明 |
|---------|--------|------|
| `new AddressFormatter(locale)` | `AddressFormatter` | 新しいインスタンスを作成 |
| `getCountries(options?)` | `Promise<Country[]>` | 全国リストを取得 |
| `getCountry(code, options?)` | `Promise<Country>` | 国コードから国を取得 |
| `format(address)` | `Promise<string[]>` | 住所を表示用にフォーマット |
| `getOrderedFields(code)` | `Promise<FieldName[][]>` | フォーム用のフィールド順序を取得 |
| `getZoneName(countryCode, zoneCode)` | `Promise<string \| undefined>` | ローカライズされた地域名を取得 |
| `updateLocale(locale)` | `void` | ロケールを更新 |
| `resetCache()` | `void` | キャッシュをリセット（静的メソッド） |

### スタンドアロン関数

| 関数 | 戻り値 | 説明 |
|-----|--------|------|
| `formatAddress(address, country)` | `string[]` | 住所を同期的にフォーマット |
| `buildOrderedFields(country)` | `FieldName[][]` | フィールド順序を同期的に取得 |

## 型定義

```typescript
interface Country {
  name: string;
  code: string;
  continent: string;
  phoneNumberPrefix: number;
  autocompletionField: FieldName;
  provinceKey: ZoneKey;
  labels: AddressLabels;
  optionalLabels: { address2: string };
  formatting: { edit: string; show: string };
  zones: Zone[];
}

interface Zone {
  name: string;
  code: string;
}

interface Address {
  firstName?: string;
  lastName?: string;
  company?: string;
  address1?: string;
  address2?: string;
  city?: string;
  province?: string;
  zip?: string;
  country: string;
  phone?: string;
}

enum FieldName {
  FirstName = 'firstName',
  LastName = 'lastName',
  Company = 'company',
  Address1 = 'address1',
  Address2 = 'address2',
  City = 'city',
  Country = 'country',
  Zone = 'province',
  PostalCode = 'zip',
  Phone = 'phone',
}
```

## サポートロケール

- `en`（英語）
- `ja`（日本語）

サポートされていないロケールは英語にフォールバックします。

## @shopify/address からの移行

```diff
- import AddressFormatter from '@shopify/address';
+ import AddressFormatter from '@huckleberry-inc/address-worldwide';

- import type { Country, Address } from '@shopify/address-consts';
+ import type { Country, Address } from '@huckleberry-inc/address-worldwide';
```

## このパッケージを作った理由

`@shopify/address` は Shopify の内部 GraphQL API（`atlas.shopifysvc.com`）に依存しており、API が利用できない場合に障害が発生します。このパッケージは [Shopify/worldwide](https://github.com/Shopify/worldwide) のローカルデータを使用し、以下を実現します：

- ネットワーク依存なし
- 高速なパフォーマンス
- オフラインサポート
- 同じ API 互換性

## 開発

```bash
# 依存関係をインストール
npm install

# ビルド（最新データ取得 + TypeScript コンパイル）
npm run build

# テスト実行
npm test

# 型チェック
npm run typecheck
```

## ライセンス

MIT