infra-data-kit

infra-data-kit is a small npm package for processing infrastructure data. It includes:

• A catalog of common infrastructure and traffic data domains.
• A normalization layer that converts raw records into one consistent shape.
• Parsers for GeoJSON and CSV.
• Adapters for Shapefile, GeoPackage, and OSM records once they are decoded into JavaScript objects.
• Validation helpers and GeoJSON export helpers.

What data is common in infrastructure and traffic systems?

These are the data categories you usually need to handle:

Roads

Common fields:

• road_id
• name
• route_number
• functional_class
• surface_type
• lane_count
• speed_limit
• direction
• bridge_clearance
• weight_limit
• geometry

Traffic

Common fields:

• observation_id
• timestamp
• sensor_id
• road_id
• segment_id
• traffic_volume
• average_speed
• travel_time
• occupancy
• incident_type
• delay_seconds
• geometry

Transit

Common fields:

• agency_id
• route_id
• trip_id
• stop_id
• vehicle_id
• arrival_time
• departure_time
• headway_seconds
• passenger_load
• geometry

Utilities and assets

Common fields:

• asset_id
• asset_type
• owner
• material
• install_date
• condition_score
• inspection_date
• status
• diameter
• capacity
• geometry

Bridges and structures

Common fields:

• bridge_id
• name
• year_built
• owner
• material
• span_count
• deck_area
• load_rating
• inspection_date
• condition_score
• geometry

What file formats are used for roads and related data?

The most common formats are:

Geospatial formats

• GeoJSON: Common for web apps, APIs, road centerlines, and traffic overlays.
• Shapefile: Very common in city/state GIS exports, but older and split across multiple files.
• GeoPackage (.gpkg): Common for modern GIS exchange and offline/mobile workflows.
• OSM XML/PBF: Common when roads come from OpenStreetMap.

Tabular and analytics formats

• CSV: Common for traffic counts, sensor feeds, and road attribute tables.
• JSON: Common for APIs and custom interchange.
• Parquet: Common for large timeseries and analytics pipelines.

Transit-specific formats

• GTFS: Scheduled routes, trips, stops, and stop times.
• GTFS Realtime: Live vehicle positions, trip updates, and service alerts.

Install

npm install @wacrot/infra-data-kit

Usage

import {
  createFeatureCollection,
  listDomains,
  listFormats,
  normalizeCollection,
  parseCsv,
  parseGeoJSON,
  validateCollection
} from "@wacrot/infra-data-kit";

console.log(listDomains());
console.log(listFormats());

const geojsonRecords = parseGeoJSON({
  type: "FeatureCollection",
  features: [
    {
      type: "Feature",
      id: "road-1",
      properties: { name: "Main St", speed_limit: 35 },
      geometry: {
        type: "LineString",
        coordinates: [
          [-118.25, 34.05],
          [-118.24, 34.05]
        ]
      }
    }
  ]
}, {
  domain: "roads"
});

const trafficRecords = parseCsv(
  "id,latitude,longitude,traffic_volume,timestamp\nsensor-1,34.05,-118.25,220,2026-04-30T12:00:00Z",
  { domain: "traffic" }
);

const rows = [{ id: "road-1" }, { id: "road-2" }];
const genericRecords = normalizeCollection(rows, { domain: "roads" });

console.log(geojsonRecords);
console.log(trafficRecords);
console.log(validateCollection(trafficRecords, { requireGeometry: true }));
console.log(createFeatureCollection(genericRecords));

Normalized output shape

{
  id: "string | null",
  domain: "roads | traffic | transit | utilities | bridges",
  sourceFormat: "geojson | shapefile | csv | ...",
  geometryType: "Point | LineString | Polygon | null",
  geometry: "GeoJSON geometry | null",
  properties: { /* original attributes */ },
  timestamp: "ISO string | null"
}

Format support

Included directly

• parseGeoJSON(input, options): Accepts GeoJSON strings or objects.
• parseCsv(input, options): Accepts CSV text with header-based field mapping.
• parseByFormat(input, formatId, options): Dispatches by format name.

Included as adapters

These formats are common, but they are usually decoded by specialist GIS libraries before normalization:

• normalizeShapefileFeatures(features, options): Accepts GeoJSON-like features from a shapefile reader.
• normalizeGeoPackageFeatures(features, options): Accepts GeoJSON-like features from a GeoPackage reader.
• normalizeOsmElements(elements, options): Accepts decoded OpenStreetMap elements.

This package stays lightweight by not bundling heavy binary GIS parsers by default.

Validation

import { validateNormalizedRecord } from "@wacrot/infra-data-kit";

const result = validateNormalizedRecord(record, {
  requireGeometry: true,
  allowedDomains: ["roads", "traffic"]
});

console.log(result.valid, result.errors);