nmea-web-serial 1.1.1 → 1.1.2

package/dist/nmea-web-serial.d.ts

@@ -12,7 +12,6 @@ import { EventObject } from 'xstate';
 import { GGAPacket } from 'nmea-simple';
 import { GLLPacket } from 'nmea-simple';
 import { HDGPacket } from 'nmea-simple';
-import { HDMPacket } from 'nmea-simple';
 import { HDTPacket } from 'nmea-simple';
 import { MachineSnapshot } from 'xstate';
 import { MetaObject } from 'xstate';
@@ -29,60 +28,38 @@ import { VTGPacket } from 'nmea-simple';
 import { ZDAPacket } from 'nmea-simple';
 
 /**
- * Append the correct trailing "*xx" footer for an NMEA string and return the result.
- */
-export declare function appendChecksumFooter(sentenceWithoutChecksum: string): string;
-
-/**
- * Computes navigation data from stored packets using a fallback strategy.
- * Each navigation property (time, position, speed, heading, depth) is computed
- * with priority-based fallback to the best available data source.
- */
-export declare function computeNavigationData(packets: StoredPackets, externalVariation?: number): NavigationData;
-
-/**
- * Generate a checksum for an NMEA sentence without the trailing "*xx".
- */
-export declare function computeNmeaChecksum(sentenceWithoutChecksum: string): number;
-
-/**
- * Creates a navigation adapter function with the specified magnetic variation.
- * The adapter is a closure that captures the variation value.
+ * Simple client for navigation NMEA data.
+ * Creates a machine and manages connection state automatically.
  *
- * @param externalVariation - Optional magnetic variation for heading calculations.
- * @returns An adapter function that transforms packets into navigation data.
- */
-export declare function createNavigationAdapter(externalVariation?: number): (packets: StoredPackets) => NavigationData;
-
-/**
- * Configuration for creating a navigation-focused NMEA machine.
- * This is a convenience configuration that uses the navigation adapter.
+ * @param options - Configuration options.
+ * @returns A client instance for managing the NMEA connection.
+ *
+ * @example
+ * ```typescript
+ * const client = createNavigationNmeaClient({
+ *   enableLogging: true,
+ *   onData: (navigation) => {
+ *     console.log('Position:', navigation.position);
+ *   },
+ * });
+ *
+ * client.connect();
+ * ```
  */
-export declare function createNavigationNmeaConfig(options?: {
-    allowedSentenceIds?: readonly string[];
-    externalVariation?: number;
-}): NmeaMachineConfig<NavigationData, StoredPackets>;
+export declare function createNavigationNmeaClient(options?: NmeaClientOptions<NavigationData>): NmeaClient<NavigationData, StoredPackets>;
 
 /**
  * Convenience function to create a navigation-focused NMEA machine.
  * This is a pre-configured machine that computes navigation data from NMEA packets.
  *
- * @param options - Optional configuration for the navigation machine.
- * @param options.allowedSentenceIds - Optional array of allowed sentence IDs.
- * @param options.externalVariation - Optional magnetic variation for heading calculations.
  * @returns An NMEA machine configured for navigation data computation.
  *
  * @example
  * ```typescript
- * const machine = createNavigationNmeaMachine({
- *   externalVariation: 5.5,
- * });
+ * const machine = createNavigationNmeaMachine();
  * ```
  */
-export declare function createNavigationNmeaMachine(options?: {
-    allowedSentenceIds?: readonly string[];
-    externalVariation?: number;
-}): StateMachine<NmeaContext<NavigationData, StoredPackets>, {
+export declare function createNavigationNmeaMachine(): StateMachine<NmeaContext<NavigationData, StoredPackets>, {
 type: "CONNECT";
 } | {
 type: "DISCONNECT";
@@ -608,11 +585,6 @@ readonly CONNECT: "connecting";
 };
 }>;
 
-/**
- * Generate the correct trailing "*xx" footer for an NMEA sentence.
- */
-export declare function createNmeaChecksumFooter(sentenceWithoutChecksum: string): string;
-
 /**
  * Factory function to create an NMEA state machine with a generic adapter pattern.
  *
@@ -1177,56 +1149,8 @@ export declare interface DPTPacket extends PacketStub<typeof sentenceId> {
     maximumRangeScale: number;
 }
 
-export declare function encodeAltitude(alt: number): string;
-
-export declare function encodeAltitudeNoUnits(alt: number): string;
-
-export declare function encodeDate(date?: Date): string;
-
-export declare function encodeDegrees(degrees?: number): string;
-
-export declare function encodeFixed(value: number | undefined, decimalPlaces: number): string;
-
-export declare function encodeGeoidalSeperation(geoidalSep: number): string;
-
-export declare function encodeGeoidalSeperationNoUnits(geoidalSep: number): string;
-
-/**
- * Encodes the latitude in the standard NMEA format "ddmm.mmmmmm".
- *
- * @param latitude Latitude in decimal degrees.
- */
-export declare function encodeLatitude(latitude?: number): string;
-
-/**
- * Encodes the longitude in the standard NMEA format "dddmm.mmmmmm".
- *
- * @param longitude Longitude in decimal degrees.
- */
-export declare function encodeLongitude(longitude?: number): string;
-
-export declare function encodeTime(date?: Date): string;
-
-export declare function encodeValue(value?: unknown): string;
-
 declare type ExtendedNmeaPacket = Packet | CustomPackets;
 
-/**
- * Initial navigation data state.
- */
-export declare const initialNavigationData: NavigationData;
-
-/**
- * Initial stored packets state.
- */
-export declare const initialNavigationPackets: StoredPackets;
-
-/**
- * Default sentence IDs used for navigation data computation.
- * Includes standard NMEA sentences and custom depth sentences.
- */
-export declare const NAVIGATION_SENTENCE_IDS: readonly ["GGA", "RMC", "GLL", "VTG", "HDT", "HDG", "HDM", "DPT", "DBT", "DBS", "DBK", "ZDA"];
-
 /**
  * Types for navigation data.
  */
@@ -1252,7 +1176,7 @@ export declare interface NavigationData {
     } | null;
     heading: {
         degreesTrue: number;
-        source: 'HDT' | 'HDG' | 'HDM' | 'COG' | null;
+        source: 'HDT' | 'HDG' | 'COG' | null;
         isDerived: boolean;
     } | null;
     depth: {
@@ -1261,6 +1185,81 @@ export declare interface NavigationData {
     } | null;
 }
 
+/**
+ * Simple client for managing NMEA connections.
+ * Abstracts away XState details while still exposing the machine for advanced use.
+ */
+export declare class NmeaClient<TData, TPackets extends Record<string, unknown>> {
+    private actor;
+    private subscription;
+    private options?;
+    /**
+     * Creates a new NMEA client.
+     *
+     * @param machine - The NMEA machine instance (created with createNmeaMachine).
+     * @param options - Optional configuration and callbacks.
+     */
+    constructor(machine: ReturnType<typeof createNmeaMachine<TData, TPackets>>, options?: NmeaClientOptions<TData>);
+    private setupSubscriptions;
+    /**
+     * Gets the current data.
+     */
+    get data(): TData;
+    /**
+     * Gets whether the connection is currently active.
+     */
+    get isConnected(): boolean;
+    /**
+     * Gets whether the connection is in progress.
+     */
+    get isConnecting(): boolean;
+    /**
+     * Gets the current error message, if any.
+     */
+    get error(): string | null;
+    /**
+     * Connects to the serial port.
+     */
+    connect(): void;
+    /**
+     * Disconnects from the serial port.
+     */
+    disconnect(): void;
+    /**
+     * Sets logging enabled/disabled.
+     */
+    setLogging(enabled: boolean): void;
+    /**
+     * Sets the baud rate (requires reconnection to take effect).
+     */
+    setBaudRate(baudRate: number): void;
+    /**
+     * Gets the underlying XState actor (for advanced users).
+     * Allows access to full XState functionality.
+     */
+    get machine(): NmeaMachineActor<TData, TPackets>;
+    /**
+     * Disposes of the client and cleans up resources.
+     */
+    dispose(): void;
+}
+
+/**
+ * Configuration for the NMEA client.
+ */
+export declare interface NmeaClientOptions<TData = unknown> {
+    /** Whether to enable logging of parsed packets. */
+    enableLogging?: boolean;
+    /** Baud rate for serial communication. Default is 4800. */
+    baudRate?: number;
+    /** Callback function called when data is updated. */
+    onData?: (data: TData) => void;
+    /** Callback function called when connection state changes. */
+    onStateChange?: (isConnected: boolean) => void;
+    /** Callback function called when an error occurs. */
+    onError?: (error: string) => void;
+}
+
 /**
  * Generic context for the NMEA state machine.
  * @template TData - The type of computed/translated data.
@@ -1332,54 +1331,10 @@ export declare interface NmeaMachineConfig<TData, TPackets extends Record<string
     initialPackets: TPackets;
 }
 
-export declare function padLeft(value: string | number, length: number, paddingCharacter: string): string;
-
-/**
- * Parses coordinate given as "dddmm.mm", "ddmm.mm", "dmm.mm" or "mm.mm"
- */
-export declare function parseDmCoordinate(coordinate: string): number;
-
-/**
- * Parse the given string to a float, returning 0 for an empty string.
- */
-export declare function parseFloatSafe(str: string): number;
-
-/**
- * Parse the given string to a integer, returning 0 for an empty string.
- */
-export declare function parseIntSafe(i: string): number;
-
-/**
- * Parses latitude given as "ddmm.mm", "dmm.mm" or "mm.mm" (assuming zero
- * degrees) along with a given hemisphere of "N" or "S" into decimal degrees,
- * where north is positive and south is negative.
- */
-export declare function parseLatitude(lat: string, hemi: string): number;
-
-/**
- * Parses latitude given as "dddmm.mm", "ddmm.mm", "dmm.mm" or "mm.mm" (assuming
- * zero degrees) along with a given hemisphere of "E" or "W" into decimal
- * degrees, where east is positive and west is negative.
- */
-export declare function parseLongitude(lon: string, hemi: string): number;
+export { Packet }
 
 export declare function parseNmeaSentence(sentence: string): ExtendedNmeaPacket;
 
-/**
- * Parse the given string to a float if possible, returning 0 for an undefined
- * value and a string the the given string cannot be parsed.
- */
-export declare function parseNumberOrString(str?: string): number | string;
-
-/**
- * Parses a UTC time and optionally a date and returns a Date
- * object.
- * @param {string} time Time the format "hhmmss" or "hhmmss.ss"
- * @param {string=} date Optional date in format the ddmmyyyy or ddmmyy
- * @returns {Date}
- */
-export declare function parseTime(time: string, date?: string, rmcCompatible?: boolean): Date;
-
 export declare function parseUnsafeNmeaSentence(sentence: string): ExtendedNmeaPacket | UnknownPacket;
 
 declare const sentenceId: "DPT";
@@ -1398,7 +1353,6 @@ export declare interface StoredPackets extends Record<string, unknown> {
     VTG?: VTGPacket;
     HDT?: HDTPacket;
     HDG?: HDGPacket;
-    HDM?: HDMPacket;
     DPT?: DPTPacket;
     DBT?: DBTPacket;
     DBS?: DBSPacket;
@@ -1406,16 +1360,6 @@ export declare interface StoredPackets extends Record<string, unknown> {
     ZDA?: ZDAPacket;
 }
 
-/**
- * Utility functions for NMEA encoding, decoding, and validation.
- */
-export declare function toHexString(v: number): string;
-
 export declare type UnsafeAndCustomPackets = CustomPackets | UnknownPacket;
 
-/**
- * Checks that the given NMEA sentence has a valid checksum.
- */
-export declare function validNmeaChecksum(nmeaSentence: string): boolean;
-
 export { }