@tmlmobilidade/utils 20250628.1124.5 → 20250628.1632.4

package/dist/src/dates/utils.d.ts

@@ -1,4 +1,4 @@
-import { OperationalDate } from '@tmlmobilidade/types';
+import { type OperationalDate, type UnixTimestamp } from '@tmlmobilidade/types';
 /**
  * Returns an array of individual dates from a given range of operational dates.
  * @param start The start date of the range, in OperationalDate format.
@@ -6,3 +6,12 @@ import { OperationalDate } from '@tmlmobilidade/types';
  * @returns An array of OperationalDate objects representing each date in the range.
  */
 export declare function getOperationalDatesFromRange(start: OperationalDate, end: OperationalDate): OperationalDate[];
+/**
+ * Sorts an array of objects by a Unix timestamp key in ascending or descending order.
+ * The key must be of type UnixTimestamp, which is a number representing the timestamp in milliseconds.
+ * @param data The array of objects to be sorted.
+ * @param key The key of the objects to sort by, which must be a UnixTimestamp.
+ * @param direction The direction to sort the data, either 'asc' for ascending or 'desc' for descending. Defaults to 'asc'.
+ * @returns A new array of objects sorted by the specified Unix timestamp key.
+ */
+export declare function sortByUnixTimestamp<T, K extends keyof T>(data: T[], key: K extends keyof T ? (T[K] extends UnixTimestamp ? K : never) : never, direction?: 'asc' | 'desc'): T[];

package/dist/src/dates/utils.js

@@ -29,3 +29,25 @@ export function getOperationalDatesFromRange(start, end) {
     }
     return dates;
 }
+/**
+ * Sorts an array of objects by a Unix timestamp key in ascending or descending order.
+ * The key must be of type UnixTimestamp, which is a number representing the timestamp in milliseconds.
+ * @param data The array of objects to be sorted.
+ * @param key The key of the objects to sort by, which must be a UnixTimestamp.
+ * @param direction The direction to sort the data, either 'asc' for ascending or 'desc' for descending. Defaults to 'asc'.
+ * @returns A new array of objects sorted by the specified Unix timestamp key.
+ */
+export function sortByUnixTimestamp(data, key, direction = 'asc') {
+    //
+    if (direction === 'desc') {
+        return [...data].sort((a, b) => {
+            return b[key] - a[key];
+        });
+    }
+    //
+    // If direction is 'asc'
+    return [...data].sort((a, b) => {
+        return a[key] - b[key];
+    });
+    //
+}

package/dist/src/geo/chunk-line.d.ts

@@ -0,0 +1,10 @@
+import { type LineString } from 'geojson';
+/**
+ * This function takes a GeoJSON LineString and splits it into equal chunks of a given precision
+ * using a custom implementation. This is useful to ensure greater precision when calculating the nearest
+ * point on a path, as some paths may have very long "straight" segments with only two points.
+ * @param line The LineString to be split into chunks.
+ * @param segmentLength The length of each segment in meters.
+ * @returns A GeoJSON LineString with the split chunks.
+ */
+export declare function chunkLineByDistance(line: LineString, segmentLength: number): LineString;

package/dist/src/geo/chunk-line.js

@@ -0,0 +1,67 @@
+/* * */
+import { toLineStringFromPositions } from './conversions.js';
+import { getDistanceBetweenPositions, interpolatePositions } from './measurements.js';
+/**
+ * This function takes a GeoJSON LineString and splits it into equal chunks of a given precision
+ * using a custom implementation. This is useful to ensure greater precision when calculating the nearest
+ * point on a path, as some paths may have very long "straight" segments with only two points.
+ * @param line The LineString to be split into chunks.
+ * @param segmentLength The length of each segment in meters.
+ * @returns A GeoJSON LineString with the split chunks.
+ */
+export function chunkLineByDistance(line, segmentLength) {
+    // Exit early if the line is empty
+    if (line.coordinates.length < 2)
+        return line;
+    // Setup variables to hold the coordinates of the chunked line
+    const chunkedLineCoordinates = [];
+    // Add the first point to the chunked line
+    chunkedLineCoordinates.push(line.coordinates[0]);
+    // Loop through the coordinates of the line
+    for (let i = 0; i < line.coordinates.length - 1; i++) {
+        // Extract the coordinates of the current and the next point
+        const [lngA, latA] = line.coordinates[i];
+        const [lngB, latB] = line.coordinates[i + 1];
+        // Calculate the length of the current segment
+        const currentSegmentLength = getDistanceBetweenPositions(line.coordinates[i], line.coordinates[i + 1]);
+        // If the current segment length is greater than the desired segment length
+        if (currentSegmentLength > segmentLength) {
+            // Calculate the number of segments needed to fill the current segment
+            const segmentsNeeded = Math.floor(currentSegmentLength / segmentLength);
+            // Calculate the length of each chunked segment
+            const chunkedSegmentLength = currentSegmentLength / segmentsNeeded;
+            // Calculate the remaining distance to be filled
+            let remainingDist = segmentLength;
+            // Loop through the segments needed
+            for (let j = 0; j < segmentsNeeded; j++) {
+                // Calculate the ratio of the segment
+                const ratio = remainingDist / chunkedSegmentLength;
+                // Interpolate the coordinates of the segment
+                const interpolated = interpolatePositions([lngA, latA], [lngB, latB], ratio);
+                // Add the interpolated coordinates to the chunked line
+                chunkedLineCoordinates.push(interpolated);
+                // Update the remaining distance to be filled
+                remainingDist -= chunkedSegmentLength;
+            }
+            // Add the last point of the segment to the chunked line
+            const lastPoint = line.coordinates[i + 1];
+            if (chunkedLineCoordinates[chunkedLineCoordinates.length - 1][0] !== lastPoint[0] || chunkedLineCoordinates[chunkedLineCoordinates.length - 1][1] !== lastPoint[1]) {
+                chunkedLineCoordinates.push(lastPoint);
+            }
+        }
+        else {
+            // If the current segment length is less than or equal to the desired segment length
+            // Add the current point to the chunked line
+            if (chunkedLineCoordinates[chunkedLineCoordinates.length - 1][0] !== line.coordinates[i][0] || chunkedLineCoordinates[chunkedLineCoordinates.length - 1][1] !== line.coordinates[i][1]) {
+                chunkedLineCoordinates.push(line.coordinates[i]);
+            }
+        }
+    }
+    // Add the last point of the line to the chunked line
+    const lastPoint = line.coordinates[line.coordinates.length - 1];
+    if (chunkedLineCoordinates[chunkedLineCoordinates.length - 1][0] !== lastPoint[0] || chunkedLineCoordinates[chunkedLineCoordinates.length - 1][1] !== lastPoint[1]) {
+        chunkedLineCoordinates.push(lastPoint);
+    }
+    // Return the chunked line as a GeoJSON LineString
+    return toLineStringFromPositions(chunkedLineCoordinates);
+}

package/dist/src/geo/constants.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Earth's radius in meters.
+ */
+export declare const EARTH_RADIUS = 6371000;
+/**
+ * Approximate number of meters per degree of latitude.
+ */
+export declare const METERS_PER_DEGREE = 111320;

package/dist/src/geo/constants.js

@@ -0,0 +1,8 @@
+/**
+ * Earth's radius in meters.
+ */
+export const EARTH_RADIUS = 6_371_000;
+/**
+ * Approximate number of meters per degree of latitude.
+ */
+export const METERS_PER_DEGREE = 111_320;

package/dist/src/geo/conversions.d.ts

@@ -0,0 +1,36 @@
+import { type HashedShape } from '@tmlmobilidade/types';
+import { type Feature, type GeoJsonProperties, type LineString, type Point, type Polygon, type Position } from 'geojson';
+/**
+ * Converts a list of GTFS shape points into a GeoJSON LineString.
+ * @param hashedShape The hashed shape containing GTFS shape points.
+ * @returns GeoJSON LineString feature
+ */
+export declare function toLineStringFromHashedShape(hashedShape: HashedShape): LineString;
+/**
+ * Creates a new LineString from the given set of coordinates.
+ * @param positions An array of coordinate positions for the LineString. Defaults to an empty array.
+ * @returns A GeoJSON LineString with the specified coordinates.
+ */
+export declare function toLineStringFromPositions(positions?: Position[]): LineString;
+/**
+ * Creates a new Point from the given coordinates.
+ * @param position A coordinate position for the Point. Defaults to an empty array.
+ * @returns A GeoJSON Point with the specified coordinates.
+ */
+export declare function toPointFromPositions(position?: Position): Point;
+/**
+ * Creates a new Feature from the given object and properties.
+ * @param object The object to convert to a Feature. Can be a LineString, Point, or Polygon.
+ * @param properties Optional properties to attach to the Feature. Defaults to an empty object.
+ * @returns A GeoJSON Feature with the specified object and properties.
+ */
+export declare function toFeatureFromObject<T extends LineString | Point | Polygon>(object: T, properties?: GeoJsonProperties): Feature<T>;
+/**
+ * Converts a value in kilometers or meters to meters based on a ballpark value.
+ * If the ballpark value is greater than 800 meters, it assumes the value is in meters.
+ * Otherwise, it assumes the value is in kilometers and converts it to meters.
+ * @param value The value to be converted, which can be a number or a string that can be converted to a number.
+ * @param ballpark The ballpark value to determine the unit of the value, which can also be a number or a string that can be converted to a number.
+ * @returns The converted value in meters.
+ */
+export declare function toMetersFromKilometersOrMeters(value: number | string, ballpark: number | string): number;

package/dist/src/geo/conversions.js

@@ -0,0 +1,79 @@
+/* * */
+/**
+ * Converts a list of GTFS shape points into a GeoJSON LineString.
+ * @param hashedShape The hashed shape containing GTFS shape points.
+ * @returns GeoJSON LineString feature
+ */
+export function toLineStringFromHashedShape(hashedShape) {
+    // Exit if no points are provided
+    if (!hashedShape.points?.length)
+        return toLineStringFromPositions([]);
+    // Sort points by shape_pt_sequence
+    const sortedPoints = [...hashedShape.points].sort((a, b) => a.shape_pt_sequence - b.shape_pt_sequence);
+    // Create a LineString feature
+    const coordinates = sortedPoints.map(p => [Number(p.shape_pt_lon), Number(p.shape_pt_lat)]);
+    // Return the LineString feature
+    return toLineStringFromPositions(coordinates);
+}
+/**
+ * Creates a new LineString from the given set of coordinates.
+ * @param positions An array of coordinate positions for the LineString. Defaults to an empty array.
+ * @returns A GeoJSON LineString with the specified coordinates.
+ */
+export function toLineStringFromPositions(positions = []) {
+    return {
+        coordinates: positions,
+        type: 'LineString',
+    };
+}
+/**
+ * Creates a new Point from the given coordinates.
+ * @param position A coordinate position for the Point. Defaults to an empty array.
+ * @returns A GeoJSON Point with the specified coordinates.
+ */
+export function toPointFromPositions(position = []) {
+    return {
+        coordinates: position,
+        type: 'Point',
+    };
+}
+/**
+ * Creates a new Feature from the given object and properties.
+ * @param object The object to convert to a Feature. Can be a LineString, Point, or Polygon.
+ * @param properties Optional properties to attach to the Feature. Defaults to an empty object.
+ * @returns A GeoJSON Feature with the specified object and properties.
+ */
+export function toFeatureFromObject(object, properties) {
+    return {
+        geometry: object,
+        properties: properties || {},
+        type: 'Feature',
+    };
+}
+/**
+ * Converts a value in kilometers or meters to meters based on a ballpark value.
+ * If the ballpark value is greater than 800 meters, it assumes the value is in meters.
+ * Otherwise, it assumes the value is in kilometers and converts it to meters.
+ * @param value The value to be converted, which can be a number or a string that can be converted to a number.
+ * @param ballpark The ballpark value to determine the unit of the value, which can also be a number or a string that can be converted to a number.
+ * @returns The converted value in meters.
+ */
+export function toMetersFromKilometersOrMeters(value, ballpark) {
+    //
+    const BALLPARK_THRESHOLD = 800; // meters
+    const valueAsNumber = Number(value);
+    const ballparkAsNumber = Number(ballpark);
+    if (Number.isNaN(valueAsNumber))
+        throw new Error('Value must be a number or a string that can be converted to a number.');
+    if (Number.isNaN(ballparkAsNumber))
+        throw new Error('Ballpark must be a number or a string that can be converted to a number.');
+    // If the ballpark is bigger than 800, then the value is in meters
+    // Otherwise, the value is in kilometers. This is because it is unlikely
+    // that a trip will be smaller than 800 meters, and longer than 800 kilometers.
+    if (ballparkAsNumber > BALLPARK_THRESHOLD) {
+        return valueAsNumber;
+    }
+    return valueAsNumber * 1000;
+    //
+}
+;

package/dist/src/geo/cut-line-at-length.d.ts

@@ -0,0 +1,9 @@
+import { type LineString } from 'geojson';
+/**
+ * Cuts a LineString at a specified length.
+ * If the line is shorter than the specified length, it returns the entire line.
+ * @param line The LineString to cut.
+ * @param length The length at which to cut the line, in meters, from the start of the line.
+ * @returns A new LineString that is cut at the specified length.
+ */
+export declare function cutLineStringAtLength(line: LineString, length: number): LineString;

package/dist/src/geo/cut-line-at-length.js

@@ -0,0 +1,53 @@
+/* * */
+import { toLineStringFromPositions } from './conversions.js';
+import { getDistanceBetweenPositions, interpolatePositions } from './measurements.js';
+/**
+ * Cuts a LineString at a specified length.
+ * If the line is shorter than the specified length, it returns the entire line.
+ * @param line The LineString to cut.
+ * @param length The length at which to cut the line, in meters, from the start of the line.
+ * @returns A new LineString that is cut at the specified length.
+ */
+export function cutLineStringAtLength(line, length) {
+    // Return the line if it is empty
+    if (line.coordinates.length < 2)
+        return line;
+    // Return an empty line if the length is less than or equal to 0
+    if (length <= 0)
+        return toLineStringFromPositions();
+    // Hold the cumulative distance between points
+    // and the coordinates of the new line
+    let cumulativeLength = 0;
+    const newLinePositions = [];
+    // Loop through the coordinates of the line
+    for (let i = 0; i < line.coordinates.length - 1; i++) {
+        // Get the coordinates of the current and the next point
+        const coordA = line.coordinates[i];
+        const coordB = line.coordinates[i + 1];
+        // Calculate the distance between the two points
+        const segmentLength = getDistanceBetweenPositions(coordA, coordB);
+        // If the current segment length plus the cumulative length
+        // extends the desired length of the resulting string
+        // then the line should be cut at the interpolation point
+        if (cumulativeLength + segmentLength >= length) {
+            const remainingLength = length - cumulativeLength;
+            const relativePositionOnSegment = remainingLength / segmentLength;
+            const interpolated = interpolatePositions(coordA, coordB, relativePositionOnSegment);
+            newLinePositions.push(coordA, interpolated);
+            return toLineStringFromPositions(newLinePositions);
+        }
+        // Add the length of the current segment to the
+        // cumulative length of the line up until this point
+        cumulativeLength += segmentLength;
+        // If the cumulative length is already greater than the desired length
+        // then the line should be cut at this point. Break the loop now.
+        if (cumulativeLength > length)
+            break;
+        // If the cumulative length is not yet up to the desired length
+        // then the current point should be added to the new line
+        newLinePositions.push(coordA);
+    }
+    // If the entire line is shorter than the target length
+    newLinePositions.push(line.coordinates[line.coordinates.length - 1]);
+    return toLineStringFromPositions(newLinePositions);
+}

package/dist/src/geo/index.d.ts

@@ -1 +1,5 @@
-export * from './convert-to-meters.js';
+export * from './chunk-line.js';
+export * from './constants.js';
+export * from './conversions.js';
+export * from './cut-line-at-length.js';
+export * from './measurements.js';

package/dist/src/geo/index.js

@@ -1 +1,5 @@
-export * from './convert-to-meters.js';
+export * from './chunk-line.js';
+export * from './constants.js';
+export * from './conversions.js';
+export * from './cut-line-at-length.js';
+export * from './measurements.js';

package/dist/src/geo/measurements.d.ts

@@ -0,0 +1,42 @@
+import { type Point, type Position } from 'geojson';
+/**
+ * Calculates the distance between two points, in meters.
+ * This is a wrapper function around the `getDistanceBetweenPositions` function.
+ * @param pointA The first point.
+ * @param pointB The second point.
+ * @returns The distance between the two points, in meters.
+ */
+export declare function getDistanceBetweenPoints(pointA: Point, pointB: Point): number;
+/**
+ * Calculates the distance between two coordinate positions, in meters.
+ * This function uses the Haversine formula to calculate the distance
+ * between two points on the Earth's surface, given their latitude and longitude.
+ * The formula accounts for the curvature of the Earth.
+ * It is important to note that this function assumes the Earth is a perfect sphere,
+ * which is not entirely accurate, but it provides a good approximation for small distances.
+ * @param positionA The first position.
+ * @param positionB The second position.
+ * @returns The distance between the two points, in meters.
+ */
+export declare function getDistanceBetweenPositions(positionA: Position, positionB: Position): number;
+/**
+ * Interpolates between two points at a given ratio (0..1).
+ * This is a wrapper function around the `interpolatePosition` function.
+ * @param pointA The first point.
+ * @param pointB The second point.
+ * @param ratio The ratio at which to interpolate (0 = pointA, 1 = pointB).
+ * @returns The interpolated point.
+ */
+export declare function interpolatePoints(pointA: Point, pointB: Point, ratio: number): Point;
+/**
+ * Linearly interpolates between two positions at a given ratio (0..1).
+ * This function is useful for calculating intermediate points
+ * along a line segment defined by two positions.
+ * @param positionA The first position.
+ * @param positionB The second position.
+ * @param ratio The ratio at which to interpolate (0 = positionA, 1 = positionB).
+ *              A ratio of 0.5 would give the midpoint between the two positions.
+ *              A ratio of 0.25 would give a point closer to positionA.
+ * @returns The interpolated position.
+ */
+export declare function interpolatePositions(positionA: Position, positionB: Position, ratio: number): Position;

package/dist/src/geo/measurements.js

@@ -0,0 +1,71 @@
+/* * */
+import { METERS_PER_DEGREE } from './constants.js';
+import { toPointFromPositions } from './conversions.js';
+/**
+ * Calculates the distance between two points, in meters.
+ * This is a wrapper function around the `getDistanceBetweenPositions` function.
+ * @param pointA The first point.
+ * @param pointB The second point.
+ * @returns The distance between the two points, in meters.
+ */
+export function getDistanceBetweenPoints(pointA, pointB) {
+    return getDistanceBetweenPositions(pointA.coordinates, pointB.coordinates);
+}
+/**
+ * Calculates the distance between two coordinate positions, in meters.
+ * This function uses the Haversine formula to calculate the distance
+ * between two points on the Earth's surface, given their latitude and longitude.
+ * The formula accounts for the curvature of the Earth.
+ * It is important to note that this function assumes the Earth is a perfect sphere,
+ * which is not entirely accurate, but it provides a good approximation for small distances.
+ * @param positionA The first position.
+ * @param positionB The second position.
+ * @returns The distance between the two points, in meters.
+ */
+export function getDistanceBetweenPositions(positionA, positionB) {
+    // Extract coordinates from the points
+    const [lngA, latA] = positionA;
+    const [lngB, latB] = positionB;
+    // Calculate the average latitude
+    const averageLatitude = (latA + latB) / 2;
+    // Calculate the differences in longitude and latitude
+    const dx = (lngB - lngA) * METERS_PER_DEGREE * Math.cos((averageLatitude * Math.PI) / 180);
+    const dy = (latB - latA) * METERS_PER_DEGREE;
+    // Calculate the distance using the Pythagorean theorem
+    return Math.sqrt(dx * dx + dy * dy);
+}
+/**
+ * Interpolates between two points at a given ratio (0..1).
+ * This is a wrapper function around the `interpolatePosition` function.
+ * @param pointA The first point.
+ * @param pointB The second point.
+ * @param ratio The ratio at which to interpolate (0 = pointA, 1 = pointB).
+ * @returns The interpolated point.
+ */
+export function interpolatePoints(pointA, pointB, ratio) {
+    const result = interpolatePositions(pointA.coordinates, pointB.coordinates, ratio);
+    return toPointFromPositions(result);
+}
+/**
+ * Linearly interpolates between two positions at a given ratio (0..1).
+ * This function is useful for calculating intermediate points
+ * along a line segment defined by two positions.
+ * @param positionA The first position.
+ * @param positionB The second position.
+ * @param ratio The ratio at which to interpolate (0 = positionA, 1 = positionB).
+ *              A ratio of 0.5 would give the midpoint between the two positions.
+ *              A ratio of 0.25 would give a point closer to positionA.
+ * @returns The interpolated position.
+ */
+export function interpolatePositions(positionA, positionB, ratio) {
+    // Extract coordinates from the points
+    const lng = positionA[0] + (positionB[0] - positionA[0]) * ratio;
+    const lat = positionA[1] + (positionB[1] - positionA[1]) * ratio;
+    // Preserve elevation if present
+    if (positionA.length > 2 && positionB.length > 2) {
+        const alt = positionA[2] + (positionB[2] - positionA[2]) * ratio;
+        return [lng, lat, alt];
+    }
+    // Return the interpolated position
+    return [lng, lat];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tmlmobilidade/utils",
-	"version": "20250628.1124.5",
+	"version": "20250628.1632.4",
 	"author": "João de Vasconcelos & Jusi Monteiro",
 	"license": "AGPL-3.0-or-later",
 	"homepage": "https://github.com/tmlmobilidade/services#readme",

package/dist/src/geo/convert-to-meters.d.ts

@@ -1,11 +0,0 @@
-/**
- * This function checks if a value is small enough to be considered a meter value,
- * as it should be used exclusevely for trip distance values.
- * If the value is greater than 1, it is considered to be in meters.
- * Converts a value to meters if it is in kilometers, otherwise returns meters.
- * @param value - The value to be checked
- * @param context - The context in which the value is being used
- * @param ballpark - A ballpark value to be used as a reference. It is recommended to use the total distance of the object.
- * @returns The value in meters
- */
-export declare function convertMetersOrKilometersToMeters(value: number | string, ballpark: number | string): number;

package/dist/src/geo/convert-to-meters.js

@@ -1,30 +0,0 @@
-/* * */
-const BALLPARK_THRESHOLD = 800; // meters
-/**
- * This function checks if a value is small enough to be considered a meter value,
- * as it should be used exclusevely for trip distance values.
- * If the value is greater than 1, it is considered to be in meters.
- * Converts a value to meters if it is in kilometers, otherwise returns meters.
- * @param value - The value to be checked
- * @param context - The context in which the value is being used
- * @param ballpark - A ballpark value to be used as a reference. It is recommended to use the total distance of the object.
- * @returns The value in meters
- */
-export function convertMetersOrKilometersToMeters(value, ballpark) {
-    //
-    const valueAsNumber = Number(value);
-    const ballparkAsNumber = Number(ballpark);
-    if (Number.isNaN(valueAsNumber))
-        throw new Error('Value must be a number or a string that can be converted to a number.');
-    if (Number.isNaN(ballparkAsNumber))
-        throw new Error('Ballpark must be a number or a string that can be converted to a number.');
-    // If the ballpark is bigger than 800, then the value is in meters
-    // Otherwise, the value is in kilometers. This is because it is unlikely
-    // that a trip will be smaller than 800 meters, and longer than 800 kilometers.
-    if (ballparkAsNumber > BALLPARK_THRESHOLD) {
-        return valueAsNumber;
-    }
-    return valueAsNumber * 1000;
-    //
-}
-;