@huckleberry-inc/address-worldwide

Shopify/worldwide のローカル YAML データを使用した @shopify/address の代替パッケージです。オフラインで動作します。

インストール

npm install @huckleberry-inc/address-worldwide

使い方

AddressFormatter クラス

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();

スタンドアロン関数

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[][] | フィールド順序を同期的に取得 |

型定義

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 からの移行

- 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 のローカルデータを使用し、以下を実現します：

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

開発

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

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

# テスト実行
npm test

# 型チェック
npm run typecheck

ライセンス

MIT