[Bug]: v3.1.3にて、normalize関数のオプションjapaneseAddressesApiが機能しない

[ms-s-matsumoto]

What happened?

お世話になっております。
バージョン3.1.3において、normalize関数にoptions.japaneseAddressesApiでローカルの file:// パスを指定しても、設定が無視され、デフォルトのCDNが参照されてしまう問題について報告します。

環境

• ライブラリバージョン: normalize-japanese-addresses@3.1.3
• 実行環境: Node.js（v22.16.0）
• OS: Windows11

問題の詳細

ローカルの住所データを参照する目的で、以下のようなコードを実行しました。
この際、参照先のディレクトリ (C:\myAppPath\data\japanese-addresses) は、ローカルファイルが参照されているかを確かめるために空にしています。

import { normalize } from '@geolonia/normalize-japanese-addresses';

const address = '東京都新宿区西新宿2-8-1';
const localAddressesUrl = 'file://C:\\myAppPath\\data\\japanese-addresses\\ja';

// options にてローカルファイルのパスを指定
const normalizedResult = await normalize(address, {
    japaneseAddressesApi: localAddressesUrl,
});

console.log(normalizedResult);

期待される挙動

指定されたローカルパスからデータを読み込もうと試み、ファイルが存在しないためエラーが発生する。

実際の挙動

オプションが無視され、デフォルトのCDNへフォールバックします。結果として、正規化された住所オブジェクトが正常に返却されてしまいます。

調査

デバッガーで内部の動作を確認したところ、以下の点が判明しました。

1. node_modules\@geolonia\normalize-japanese-addresses\dist\main-node-esm.mjs 内の fetchOrReadFile 関数において、config$1.japaneseAddressesApi の値が、optionsで渡したパスではなく、デフォルトのCDN URL (https://japanese-addresses-v2.geoloniamaps.com/api/ja) になっていました。

// myAppPath\node_modules\@geolonia\normalize-japanese-addresses\dist\main-node-esm.mjs
const fetchOrReadFile = (input, options) => __awaiter(void 0, void 0, void 0, function* () {
    // ↓ ここの config$1.japaneseAddressesApi がデフォルト値のままになっている
    const fileURL = new URL(`${config$1.japaneseAddressesApi}${input}`);

2. 回避策の検証

同ファイル内の設定オブジェクトを直接書き換えることで、期待通りの動作になることを確認しました。

// 変更前
const currentConfig = {
  japaneseAddressesApi: defaultEndpoint,
  // ...
};

// 変更後（ローカルパスをハードコード）
const currentConfig = {
  japaneseAddressesApi: 'file://C:\\myAppPath\\data\\japanese-addresses\\ja',
  // ...
};

この変更後、

• ローカルディレクトリが空の場合 → 想定通りエラーが発生した
• ローカルディレクトリに住所データを配置した場合 → 想定通りローカルファイルを使って正規化に成功した

以上のことから、normalize関数に渡されたoptionsが、内部のデータ取得処理で参照される設定オブジェクトに正しく反映されていない不具合があるものと考えられます。

ご確認いただけますと幸いです。

Steps to reproduce

No response

Relevant log output

[sanak]

@ms-s-matsumoto 上記についてご報告頂き、ありがとうございます。
コメント頂いた冒頭のサンプルコードですが、以下のようにグローバルオプションとなる config をインポートし、 config.japaneseAddressesApi に対してローカルファイルパスを指定してお試し頂ければと思います。
(調査の2.回避策の検証でコメント頂いた内容を、クライアントコード上で指定する形になります。)

-import { normalize } from '@geolonia/normalize-japanese-addresses';
+import { normalize, config } from '@geolonia/normalize-japanese-addresses';
 
 const address = '東京都新宿区西新宿2-8-1';
 const localAddressesUrl = 'file://C:\\myAppPath\\data\\japanese-addresses\\ja';
 
-// options にてローカルファイルのパスを指定
-const normalizedResult = await normalize(address, {
-    japaneseAddressesApi: localAddressesUrl,
-});
+// config にてローカルファイルのパスを指定
+config.japaneseAddressesApi = localAddressesUrl;
+const normalizedResult = await normalize(address);
 
 console.log(normalizedResult);

[sanak]

上記ですが、README.mdのグローバルオプションの説明が少し分かりづらいようにも思いましたので、こちらはコード例を記載するなどして、改善を検討します。
https://github.com/geolonia/normalize-japanese-addresses/blob/master/README.md#%E3%82%B0%E3%83%AD%E3%83%BC%E3%83%90%E3%83%AB%E3%82%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3

グローバルオプション

以下のパラメーターを変更することでライブラリの動作全体に関わる設定が変更できます。

config.japaneseAddressesApi: string

住所データを配信する Web API のエンドポイントを指定します。デフォルトは https://japanese-addresses-v2.geoloniamaps.com/api/ja です。この API から配信されるデータのディレクトリ構成は Geolonia 住所データ を参考にしてください。

NodeJS環境のみ、このオプションに対して file:// 形式の URL を指定することで、ローカルファイルとして保存したファイルを参照することができます。

[ms-s-matsumoto]

type Normalizer = (input: string, option?: Option) => Promise<NormalizeResult>;

declare const version: string;
declare const config: Config;
declare const normalize: Normalizer;

export { type NormalizeResult, config, normalize, version };

このあたりを見てOptionとConfigとを勘違いしていたみたいです。
完全にコードの読み間違いでした…。
大変失礼いたしました。

提示いただきました方法で実行したところ、正しくローカルのファイルが参照されました。
ありがとうございます。