@idpass/data-collect-core / AreaService
Class: AreaService
Defined in: services/AreaService.ts:76
Service for managing hierarchical geographic areas (HDX admin boundary aligned).
Provides CRUD operations for areas, hierarchical traversal (ancestors/descendants), bulk import from HDX admin boundary format, and entity-to-area assignment.
Constructors
Constructor
new AreaService(
connectionString):AreaService
Defined in: services/AreaService.ts:80
Parameters
connectionString
string
Returns
AreaService
Methods
initialize()
initialize():
Promise<void>
Defined in: services/AreaService.ts:88
Initializes the areas table in the database.
Returns
Promise<void>
createArea()
createArea(
input):Promise<AreaRecord>
Defined in: services/AreaService.ts:117
Creates a single area record.
Parameters
input
The area data to create.
Returns
Promise<AreaRecord>
The created area record.
getArea()
getArea(
id):Promise<AreaRecord|null>
Defined in: services/AreaService.ts:154
Retrieves an area by its ID.
Parameters
id
string
The area ID to look up.
Returns
Promise<AreaRecord | null>
The area record, or null if not found.
getAreaByPcode()
getAreaByPcode(
pcode):Promise<AreaRecord|null>
Defined in: services/AreaService.ts:170
Retrieves an area by its p-code.
Parameters
pcode
string
The p-code to look up.
Returns
Promise<AreaRecord | null>
The area record, or null if not found.
getChildren()
getChildren(
parentId):Promise<AreaRecord[]>
Defined in: services/AreaService.ts:186
Retrieves the direct children of an area.
Parameters
parentId
string
The parent area ID.
Returns
Promise<AreaRecord[]>
Array of child area records.
getAncestors()
getAncestors(
areaId):Promise<AreaRecord[]>
Defined in: services/AreaService.ts:202
Retrieves the ancestor chain from a given area up to the root. Returns ancestors in order from the immediate parent to the root.
Parameters
areaId
string
The starting area ID.
Returns
Promise<AreaRecord[]>
Array of ancestor area records (parent first, root last).
getDescendants()
getDescendants(
areaId):Promise<AreaRecord[]>
Defined in: services/AreaService.ts:227
Retrieves all descendants of an area (recursive, all levels below). Uses a recursive CTE for efficient traversal.
Parameters
areaId
string
The parent area ID.
Returns
Promise<AreaRecord[]>
Array of all descendant area records.
importFromHDX()
importFromHDX(
data):Promise<AreaRecord[]>
Defined in: services/AreaService.ts:269
Bulk imports areas from HDX admin boundary format.
Records are sorted by level before insertion to ensure parent areas exist before their children. Parent references are resolved by pcode.
Parameters
data
Array of HDX area import records.
Returns
Promise<AreaRecord[]>
Array of created area records.
assignEntityToArea()
assignEntityToArea(
entityGuid,areaId,tenantId?):Promise<void>
Defined in: services/AreaService.ts:314
Assigns an entity to an area by updating the entity's modified data with an area_id field.
Parameters
entityGuid
string
The GUID of the entity to assign.
areaId
string
The ID of the area to assign the entity to.
tenantId?
string = "default"
The tenant ID for multi-tenant isolation.
Returns
Promise<void>
getRootAreas()
getRootAreas():
Promise<AreaRecord[]>
Defined in: services/AreaService.ts:336
Retrieves all root areas (areas with no parent).
Returns
Promise<AreaRecord[]>
Array of root area records.
deleteArea()
deleteArea(
id):Promise<void>
Defined in: services/AreaService.ts:350
Deletes an area and all its descendants.
Parameters
id
string
The area ID to delete.
Returns
Promise<void>
clearStore()
clearStore():
Promise<void>
Defined in: services/AreaService.ts:372
Clears all areas from the table.
Returns
Promise<void>
closeConnection()
closeConnection():
Promise<void>
Defined in: services/AreaService.ts:379
Closes the database connection pool.
Returns
Promise<void>