🧱 Location blocks

Location blocks は、@nodeblocks/backend-sdk からエクスポートされる再利用可能な階層および MongoDB 操作の blocks です。呼び出し元は Result 値を消費し、ルートは Location ブロックのエラーを HTTP 応答に変換します。

インベントリ

エクスポート	種類	入力	結果 / 動作 / エラー
LocationBlockError	エラークラス	メッセージ、オプションのデータ	基本 BlockError；それ自体に HTTP ステータスはない。
LocationNotFoundBlockError	エラークラス	メッセージ、オプションのデータ	未発見ロケーション結果；ルートは 404 にマッピングする。
LocationUnexpectedDBError	エラークラス	メッセージ、オプションのデータ	DB/ミューテーション結果；ルートは 500 にマッピングする。
LocationConflictError	エラークラス	メッセージ、オプションのデータ	子孫競合；ルートは 409 にマッピングする。
buildAncestorsFromParent	ヘルパー	ancestors, parent ID	ok(string[]) を返す。
buildLocationToCreate	ヘルパー	body, オプションの ancestors	ok(location data) を返す。
buildDescendantsFilter	ヘルパー	location ID	ok({ ancestors: { $in } }) を返す。
assertNoDescendantLocations	ガード	child locations	ok(true) または競合エラー。
getLocationById	DB 読み取り	collection, ID	プロジェクションされた location または not-found/DB エラー。
createLocation	DB 作成	collection, location	作成された ID または DB エラー。
updateLocation	DB 更新	collection, update, ID	true または not-found/DB エラー。
deleteLocation	DB 削除	collection, ID	true または DB エラー。
findLocations	DB 検索	collection, filter	プロジェクションされた配列または DB エラー。
normalizeLocation	ノーマライザー	location ドキュメント	ok(public location) を返す。

詳細

LocationBlockError

実装

BlockError を拡張し、そのコンストラクタは (message, data?) を受け取るが HTTP ステータスフィールドを持たない。Location ソースはコンストラクタを宣言しないため、サブクラスはその契約を継承する。Location ルートでの orThrow は HTTP マッピングを実行するが、この基本クラスは現在の Location ブロックでは構築されない。

LocationNotFoundBlockError

実装

getLocationById および updateLocation によって LocationNotFoundBlockError('Location not found') として作成される。createLocationRoute、getLocationRoute、updateLocationRoute はこれを 404 にマッピングする；deleteLocationRoute は 404 マッピングをリストするが、その現在のブロックチェーンはこのクラスを生成しない。

LocationUnexpectedDBError

実装

失敗した読み取り、挿入、更新、削除、またはクエリによって作成される。各データベースブロックに文書化された正確なメッセージを含む。createLocationRoute、getLocationRoute、updateLocationRoute、deleteLocationRoute、findLocationsRoute はこれを 500 にマッピングする。

LocationConflictError

実装

assertNoDescendantLocations によってのみ 'Dependent child locations still exist' メッセージで作成される；deleteLocationRoute はこれを 409 にマッピングする。

buildAncestorsFromParent

実装

(ancestorsOfParent: string[], parentId: string) は Promise<Result<string[], never>> を返す：すべての値を文字列正規化し、親 ID を追加した祖先リストのコピー。失敗することはできない。createLocationRoute は真の body parentId が提供された場合にのみこれを呼び出す。

buildLocationToCreate

実装

(location: Record<string, unknown>, ancestors: string[] = []) は Promise<Result<Record<string, unknown>, never>> を返す。body を保持し、ancestors を上書きし、真の parentId を文字列正規化し、欠落または偽の親に対して parentId: null を書き込む。createLocationRoute は永続化前にこれを使用する。

buildDescendantsFilter

実装

(locationId: string) は Promise<Result<Record<string, unknown>, never>> を返す：{ ancestors: { $in: [String(locationId)] } } を含む。deleteLocationRoute はこれを findLocations に渡してすべての子孫を見つける。

assertNoDescendantLocations

実装

(childLocations: Record<string, unknown>[]) は Promise<Result<boolean, LocationBlockError>> を返す：空の配列の場合は ok(true)、それ以外の場合は err(new LocationConflictError('Dependent child locations still exist'))。deleteLocationRoute によって使用される。

getLocationById

実装

(locationsCollection: Collection, locationId: string) は Promise<Result<Record<string, unknown>, LocationBlockError>> を返す。findOne({ id: String(locationId) }, { projection: { _id: 0 } }) をクエリするため、_id は省略されるが階層フィールドは残る。LocationNotFoundBlockError('Location not found') または LocationUnexpectedDBError('Failed to get location by id') を返す。createLocationRoute、getLocationRoute、updateLocationRoute によって使用される。

createLocation

実装

(locationsCollection: Collection, location: Record<string, unknown>) は Promise<Result<string, LocationBlockError>> を返す。createBaseEntity を適用し、id、createdAt、updatedAt を追加し、結果を挿入して ok(baseEntity.id) を返す。insertedId が欠落しているか例外が発生した場合、LocationUnexpectedDBError('Failed to create location') を返す。createLocationRoute によって使用される。

updateLocation

実装

(locationsCollection: Collection, location: Record<string, unknown>, locationId: string) は Promise<Result<boolean, LocationBlockError>> を返す。updateOne({ id: String(locationId) }, { $set: updateBaseEntity(location) }) を実行し、updatedAt を追加する；一致しない場合は not-found、変更がないか例外が発生した場合は LocationUnexpectedDBError('Failed to update location') を返す。updateLocationRoute によって使用される。

deleteLocation

実装

(locationsCollection: Collection, locationId: string) は Promise<Result<boolean, LocationBlockError>> を返す。deleteOne({ id: String(locationId) }) を実行する；削除ゼロは LocationUnexpectedDBError('Location could not be deleted')、例外は LocationUnexpectedDBError('Failed to delete location') を返す。deleteLocationRoute によって使用される。

findLocations

実装

(locationsCollection: Collection, filter: Record<string, unknown>) は Promise<Result<Record<string, unknown>[], LocationBlockError>> を返す。find(filter, { projection: { _id: 0 } }).toArray() を実行する；失敗は LocationUnexpectedDBError('Failed to find locations') を返す。deleteLocationRoute および findLocationsRoute によって使用される。

normalizeLocation

実装

(location: Record<string, unknown> & { _id: string; parentId: string; ancestors: string[] }) は Result<Record<string, unknown>, never> を返す。_id、parentId、ancestors を削除し、ok({ ...rest, parent: parentId }) を返す。現在の Location ルートはこれをcomposeしていない；カスタム呼び出し元は必要な場合にのみ使用する。