minotor 1.0.0

package/src/stops/proto/stops.ts

@@ -0,0 +1,445 @@
+// Code generated by protoc-gen-ts_proto. DO NOT EDIT.
+// versions:
+//   protoc-gen-ts_proto  v2.6.1
+//   protoc               v4.23.4
+// source: src/stops/proto/stops.proto
+
+/* eslint-disable */
+import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
+
+export const protobufPackage = "minotor.stops";
+
+export enum LocationType {
+  SIMPLE_STOP_OR_PLATFORM = 0,
+  STATION = 1,
+  ENTRANCE_EXIT = 2,
+  GENERIC_NODE = 3,
+  BOARDING_AREA = 4,
+  UNRECOGNIZED = -1,
+}
+
+export function locationTypeFromJSON(object: any): LocationType {
+  switch (object) {
+    case 0:
+    case "SIMPLE_STOP_OR_PLATFORM":
+      return LocationType.SIMPLE_STOP_OR_PLATFORM;
+    case 1:
+    case "STATION":
+      return LocationType.STATION;
+    case 2:
+    case "ENTRANCE_EXIT":
+      return LocationType.ENTRANCE_EXIT;
+    case 3:
+    case "GENERIC_NODE":
+      return LocationType.GENERIC_NODE;
+    case 4:
+    case "BOARDING_AREA":
+      return LocationType.BOARDING_AREA;
+    case -1:
+    case "UNRECOGNIZED":
+    default:
+      return LocationType.UNRECOGNIZED;
+  }
+}
+
+export function locationTypeToJSON(object: LocationType): string {
+  switch (object) {
+    case LocationType.SIMPLE_STOP_OR_PLATFORM:
+      return "SIMPLE_STOP_OR_PLATFORM";
+    case LocationType.STATION:
+      return "STATION";
+    case LocationType.ENTRANCE_EXIT:
+      return "ENTRANCE_EXIT";
+    case LocationType.GENERIC_NODE:
+      return "GENERIC_NODE";
+    case LocationType.BOARDING_AREA:
+      return "BOARDING_AREA";
+    case LocationType.UNRECOGNIZED:
+    default:
+      return "UNRECOGNIZED";
+  }
+}
+
+export interface Stop {
+  name: string;
+  lat?: number | undefined;
+  lon?: number | undefined;
+  children: string[];
+  parent?: string | undefined;
+  locationType: LocationType;
+  platform?: string | undefined;
+}
+
+export interface StopsMap {
+  version: string;
+  stops: { [key: string]: Stop };
+}
+
+export interface StopsMap_StopsEntry {
+  key: string;
+  value: Stop | undefined;
+}
+
+function createBaseStop(): Stop {
+  return {
+    name: "",
+    lat: undefined,
+    lon: undefined,
+    children: [],
+    parent: undefined,
+    locationType: 0,
+    platform: undefined,
+  };
+}
+
+export const Stop: MessageFns<Stop> = {
+  encode(message: Stop, writer: BinaryWriter = new BinaryWriter()): BinaryWriter {
+    if (message.name !== "") {
+      writer.uint32(10).string(message.name);
+    }
+    if (message.lat !== undefined) {
+      writer.uint32(17).double(message.lat);
+    }
+    if (message.lon !== undefined) {
+      writer.uint32(25).double(message.lon);
+    }
+    for (const v of message.children) {
+      writer.uint32(34).string(v!);
+    }
+    if (message.parent !== undefined) {
+      writer.uint32(42).string(message.parent);
+    }
+    if (message.locationType !== 0) {
+      writer.uint32(48).int32(message.locationType);
+    }
+    if (message.platform !== undefined) {
+      writer.uint32(58).string(message.platform);
+    }
+    return writer;
+  },
+
+  decode(input: BinaryReader | Uint8Array, length?: number): Stop {
+    const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
+    let end = length === undefined ? reader.len : reader.pos + length;
+    const message = createBaseStop();
+    while (reader.pos < end) {
+      const tag = reader.uint32();
+      switch (tag >>> 3) {
+        case 1: {
+          if (tag !== 10) {
+            break;
+          }
+
+          message.name = reader.string();
+          continue;
+        }
+        case 2: {
+          if (tag !== 17) {
+            break;
+          }
+
+          message.lat = reader.double();
+          continue;
+        }
+        case 3: {
+          if (tag !== 25) {
+            break;
+          }
+
+          message.lon = reader.double();
+          continue;
+        }
+        case 4: {
+          if (tag !== 34) {
+            break;
+          }
+
+          message.children.push(reader.string());
+          continue;
+        }
+        case 5: {
+          if (tag !== 42) {
+            break;
+          }
+
+          message.parent = reader.string();
+          continue;
+        }
+        case 6: {
+          if (tag !== 48) {
+            break;
+          }
+
+          message.locationType = reader.int32() as any;
+          continue;
+        }
+        case 7: {
+          if (tag !== 58) {
+            break;
+          }
+
+          message.platform = reader.string();
+          continue;
+        }
+      }
+      if ((tag & 7) === 4 || tag === 0) {
+        break;
+      }
+      reader.skip(tag & 7);
+    }
+    return message;
+  },
+
+  fromJSON(object: any): Stop {
+    return {
+      name: isSet(object.name) ? globalThis.String(object.name) : "",
+      lat: isSet(object.lat) ? globalThis.Number(object.lat) : undefined,
+      lon: isSet(object.lon) ? globalThis.Number(object.lon) : undefined,
+      children: globalThis.Array.isArray(object?.children) ? object.children.map((e: any) => globalThis.String(e)) : [],
+      parent: isSet(object.parent) ? globalThis.String(object.parent) : undefined,
+      locationType: isSet(object.locationType) ? locationTypeFromJSON(object.locationType) : 0,
+      platform: isSet(object.platform) ? globalThis.String(object.platform) : undefined,
+    };
+  },
+
+  toJSON(message: Stop): unknown {
+    const obj: any = {};
+    if (message.name !== "") {
+      obj.name = message.name;
+    }
+    if (message.lat !== undefined) {
+      obj.lat = message.lat;
+    }
+    if (message.lon !== undefined) {
+      obj.lon = message.lon;
+    }
+    if (message.children?.length) {
+      obj.children = message.children;
+    }
+    if (message.parent !== undefined) {
+      obj.parent = message.parent;
+    }
+    if (message.locationType !== 0) {
+      obj.locationType = locationTypeToJSON(message.locationType);
+    }
+    if (message.platform !== undefined) {
+      obj.platform = message.platform;
+    }
+    return obj;
+  },
+
+  create<I extends Exact<DeepPartial<Stop>, I>>(base?: I): Stop {
+    return Stop.fromPartial(base ?? ({} as any));
+  },
+  fromPartial<I extends Exact<DeepPartial<Stop>, I>>(object: I): Stop {
+    const message = createBaseStop();
+    message.name = object.name ?? "";
+    message.lat = object.lat ?? undefined;
+    message.lon = object.lon ?? undefined;
+    message.children = object.children?.map((e) => e) || [];
+    message.parent = object.parent ?? undefined;
+    message.locationType = object.locationType ?? 0;
+    message.platform = object.platform ?? undefined;
+    return message;
+  },
+};
+
+function createBaseStopsMap(): StopsMap {
+  return { version: "", stops: {} };
+}
+
+export const StopsMap: MessageFns<StopsMap> = {
+  encode(message: StopsMap, writer: BinaryWriter = new BinaryWriter()): BinaryWriter {
+    if (message.version !== "") {
+      writer.uint32(10).string(message.version);
+    }
+    Object.entries(message.stops).forEach(([key, value]) => {
+      StopsMap_StopsEntry.encode({ key: key as any, value }, writer.uint32(18).fork()).join();
+    });
+    return writer;
+  },
+
+  decode(input: BinaryReader | Uint8Array, length?: number): StopsMap {
+    const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
+    let end = length === undefined ? reader.len : reader.pos + length;
+    const message = createBaseStopsMap();
+    while (reader.pos < end) {
+      const tag = reader.uint32();
+      switch (tag >>> 3) {
+        case 1: {
+          if (tag !== 10) {
+            break;
+          }
+
+          message.version = reader.string();
+          continue;
+        }
+        case 2: {
+          if (tag !== 18) {
+            break;
+          }
+
+          const entry2 = StopsMap_StopsEntry.decode(reader, reader.uint32());
+          if (entry2.value !== undefined) {
+            message.stops[entry2.key] = entry2.value;
+          }
+          continue;
+        }
+      }
+      if ((tag & 7) === 4 || tag === 0) {
+        break;
+      }
+      reader.skip(tag & 7);
+    }
+    return message;
+  },
+
+  fromJSON(object: any): StopsMap {
+    return {
+      version: isSet(object.version) ? globalThis.String(object.version) : "",
+      stops: isObject(object.stops)
+        ? Object.entries(object.stops).reduce<{ [key: string]: Stop }>((acc, [key, value]) => {
+          acc[key] = Stop.fromJSON(value);
+          return acc;
+        }, {})
+        : {},
+    };
+  },
+
+  toJSON(message: StopsMap): unknown {
+    const obj: any = {};
+    if (message.version !== "") {
+      obj.version = message.version;
+    }
+    if (message.stops) {
+      const entries = Object.entries(message.stops);
+      if (entries.length > 0) {
+        obj.stops = {};
+        entries.forEach(([k, v]) => {
+          obj.stops[k] = Stop.toJSON(v);
+        });
+      }
+    }
+    return obj;
+  },
+
+  create<I extends Exact<DeepPartial<StopsMap>, I>>(base?: I): StopsMap {
+    return StopsMap.fromPartial(base ?? ({} as any));
+  },
+  fromPartial<I extends Exact<DeepPartial<StopsMap>, I>>(object: I): StopsMap {
+    const message = createBaseStopsMap();
+    message.version = object.version ?? "";
+    message.stops = Object.entries(object.stops ?? {}).reduce<{ [key: string]: Stop }>((acc, [key, value]) => {
+      if (value !== undefined) {
+        acc[key] = Stop.fromPartial(value);
+      }
+      return acc;
+    }, {});
+    return message;
+  },
+};
+
+function createBaseStopsMap_StopsEntry(): StopsMap_StopsEntry {
+  return { key: "", value: undefined };
+}
+
+export const StopsMap_StopsEntry: MessageFns<StopsMap_StopsEntry> = {
+  encode(message: StopsMap_StopsEntry, writer: BinaryWriter = new BinaryWriter()): BinaryWriter {
+    if (message.key !== "") {
+      writer.uint32(10).string(message.key);
+    }
+    if (message.value !== undefined) {
+      Stop.encode(message.value, writer.uint32(18).fork()).join();
+    }
+    return writer;
+  },
+
+  decode(input: BinaryReader | Uint8Array, length?: number): StopsMap_StopsEntry {
+    const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
+    let end = length === undefined ? reader.len : reader.pos + length;
+    const message = createBaseStopsMap_StopsEntry();
+    while (reader.pos < end) {
+      const tag = reader.uint32();
+      switch (tag >>> 3) {
+        case 1: {
+          if (tag !== 10) {
+            break;
+          }
+
+          message.key = reader.string();
+          continue;
+        }
+        case 2: {
+          if (tag !== 18) {
+            break;
+          }
+
+          message.value = Stop.decode(reader, reader.uint32());
+          continue;
+        }
+      }
+      if ((tag & 7) === 4 || tag === 0) {
+        break;
+      }
+      reader.skip(tag & 7);
+    }
+    return message;
+  },
+
+  fromJSON(object: any): StopsMap_StopsEntry {
+    return {
+      key: isSet(object.key) ? globalThis.String(object.key) : "",
+      value: isSet(object.value) ? Stop.fromJSON(object.value) : undefined,
+    };
+  },
+
+  toJSON(message: StopsMap_StopsEntry): unknown {
+    const obj: any = {};
+    if (message.key !== "") {
+      obj.key = message.key;
+    }
+    if (message.value !== undefined) {
+      obj.value = Stop.toJSON(message.value);
+    }
+    return obj;
+  },
+
+  create<I extends Exact<DeepPartial<StopsMap_StopsEntry>, I>>(base?: I): StopsMap_StopsEntry {
+    return StopsMap_StopsEntry.fromPartial(base ?? ({} as any));
+  },
+  fromPartial<I extends Exact<DeepPartial<StopsMap_StopsEntry>, I>>(object: I): StopsMap_StopsEntry {
+    const message = createBaseStopsMap_StopsEntry();
+    message.key = object.key ?? "";
+    message.value = (object.value !== undefined && object.value !== null) ? Stop.fromPartial(object.value) : undefined;
+    return message;
+  },
+};
+
+type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+
+export type DeepPartial<T> = T extends Builtin ? T
+  : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>>
+  : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>>
+  : T extends {} ? { [K in keyof T]?: DeepPartial<T[K]> }
+  : Partial<T>;
+
+type KeysOfUnion<T> = T extends T ? keyof T : never;
+export type Exact<P, I extends P> = P extends Builtin ? P
+  : P & { [K in keyof P]: Exact<P[K], I[K]> } & { [K in Exclude<keyof I, KeysOfUnion<P>>]: never };
+
+function isObject(value: any): boolean {
+  return typeof value === "object" && value !== null;
+}
+
+function isSet(value: any): boolean {
+  return value !== null && value !== undefined;
+}
+
+export interface MessageFns<T> {
+  encode(message: T, writer?: BinaryWriter): BinaryWriter;
+  decode(input: BinaryReader | Uint8Array, length?: number): T;
+  fromJSON(object: any): T;
+  toJSON(message: T): unknown;
+  create<I extends Exact<DeepPartial<T>, I>>(base?: I): T;
+  fromPartial<I extends Exact<DeepPartial<T>, I>>(object: I): T;
+}

package/src/stops/stops.ts

@@ -0,0 +1,24 @@
+export type StopId = string;
+export type Platform = string;
+export type Latitude = number;
+export type Longitude = number;
+
+export type LocationType =
+  | 'SIMPLE_STOP_OR_PLATFORM'
+  | 'STATION'
+  | 'ENTRANCE_EXIT'
+  | 'GENERIC_NODE'
+  | 'BOARDING_AREA';
+
+export type Stop = {
+  id: StopId;
+  name: string;
+  lat?: Latitude;
+  lon?: Longitude;
+  children: StopId[];
+  parent?: StopId;
+  locationType: LocationType;
+  platform?: Platform;
+};
+
+export type StopsMap = Map<StopId, Stop>;

package/src/stops/stopsIndex.ts

@@ -0,0 +1,151 @@
+import { BinaryReader, BinaryWriter } from '@bufbuild/protobuf/wire';
+import { around } from 'geokdbush';
+import KDTree from 'kdbush';
+import { addAll, createIndex, search, SearchResult } from 'slimsearch';
+
+import { generateAccentVariants } from './i18n.js';
+import { deserializeStopsMap, serializeStopsMap } from './io.js';
+import { StopsMap as ProtoStopsMap } from './proto/stops.js';
+import { Stop, StopId, StopsMap } from './stops.js';
+
+type StopPoint = { id: StopId; lat: number; lon: number };
+
+/**
+ * The StopMap class provides functionality to search for public transport stops
+ * by name or geographic location. It leverages text search and geospatial indexing
+ * to efficiently find stops based on user queries.
+ */
+export class StopsIndex {
+  private readonly stopsMap: StopsMap;
+  private readonly textIndex;
+  private readonly geoIndex: KDTree;
+  private readonly stopPoints: StopPoint[];
+
+  constructor(stopsMap: StopsMap) {
+    this.stopsMap = stopsMap;
+    this.textIndex = createIndex({
+      fields: ['name'],
+      storeFields: ['id'],
+      searchOptions: { prefix: true, fuzzy: 0.2 },
+      processTerm: generateAccentVariants,
+    });
+    const stopsSet = new Map<string, { id: StopId; name: string }>();
+    for (const [id, stop] of stopsMap.entries()) {
+      const effectiveStopId = stop.parent ?? id;
+      if (!stopsSet.has(effectiveStopId)) {
+        stopsSet.set(effectiveStopId, {
+          id: effectiveStopId,
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          name: stop.parent ? this.stopsMap.get(stop.parent)!.name : stop.name,
+        });
+      }
+    }
+    const stopsArray = Array.from(stopsSet.values());
+    addAll(this.textIndex, stopsArray);
+
+    this.stopPoints = Array.from(this.stopsMap.entries())
+      .filter(([, stop]) => {
+        if (stop.lat && stop.lon) return true;
+        return false;
+      })
+      .map(([id, stop]) => ({
+        id: id,
+        lat: stop.lat as number,
+        lon: stop.lon as number,
+      }));
+    this.geoIndex = new KDTree(this.stopPoints.length);
+    for (const { lat, lon } of this.stopPoints) {
+      this.geoIndex.add(lon, lat);
+    }
+    this.geoIndex.finish();
+  }
+
+  /**
+   * Deserializes a binary representation of the stops.
+   *
+   * @param {Uint8Array} data - The binary data to deserialize.
+   * @returns {StopsMap} - The deserialized StopFinder.
+   */
+  static fromData(data: Uint8Array): StopsIndex {
+    const reader = new BinaryReader(data);
+    const protoStopsMap = ProtoStopsMap.decode(reader);
+
+    return new StopsIndex(deserializeStopsMap(protoStopsMap));
+  }
+
+  /**
+   * Serializes the stops into a binary protobuf.
+   *
+   * @returns {Uint8Array} - The serialized binary data.
+   */
+  serialize(): Uint8Array {
+    const protoStopsMap: ProtoStopsMap = serializeStopsMap(this.stopsMap);
+
+    const writer = new BinaryWriter();
+    ProtoStopsMap.encode(protoStopsMap, writer);
+    return writer.finish();
+  }
+
+  /**
+   * Finds stops by their name using a text search.
+   *
+   * @param query - The name or partial name of the stop to search for.
+   * @param maxResults - The maximum number of results to return (default is 5).
+   * @returns An array of Stop objects that match the search query.
+   */
+  findStopsByName(query: string, maxResults = 5): Stop[] {
+    const results = search(this.textIndex, query).map(
+      (result: SearchResult) => this.stopsMap.get(result.id as string) as Stop,
+    );
+    return results.slice(0, maxResults);
+  }
+
+  /**
+   * Finds stops by their geographic location using latitude and longitude.
+   *
+   * @param lat - The latitude of the location to search near.
+   * @param lon - The longitude of the location to search near.
+   * @param maxResults - The maximum number of results to return (default is 10).
+   * @param radius - The search radius in kilometers (default is 0.5).
+   * @returns An array of Stop objects that are closest to the specified location.
+   */
+  findStopsByLocation(
+    lat: number,
+    lon: number,
+    maxResults = 5,
+    radius = 0.5,
+  ): Stop[] {
+    const nearestStops = around(
+      this.geoIndex,
+      lon,
+      lat,
+      maxResults,
+      radius,
+    ).map((id) => {
+      const stopPoint = this.stopPoints[id as number] as StopPoint;
+      return this.stopsMap.get(stopPoint.id) as Stop;
+    });
+    return nearestStops;
+  }
+
+  /**
+   * Finds a stop by its ID.
+   *
+   * @param id - The ID of the stop to search for.
+   * @returns The Stop object that matches the specified ID, or undefined if not found.
+   */
+  findStopById(id: StopId): Stop | undefined {
+    return this.stopsMap.get(id);
+  }
+
+  equivalentStops(id: StopId): StopId[] {
+    const stop = this.stopsMap.get(id);
+    if (!stop) {
+      return [];
+    }
+    const equivalentStops = stop.parent
+      ? (this.stopsMap.get(stop.parent)?.children ?? [])
+      : stop.children;
+    return Array.from(new Set([id, ...equivalentStops]));
+  }
+}