nmea-web-serial 1.1.1 → 1.1.3

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';
@@ -28,61 +27,29 @@ import { Values } from 'xstate';
 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.
- *
- * @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.
- */
-export declare function createNavigationNmeaConfig(options?: {
-    allowedSentenceIds?: readonly string[];
-    externalVariation?: number;
-}): NmeaMachineConfig<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.
+ * This is a pre-configured machine that computes navigation data (position, time, speed, heading, depth)
+ * from NMEA packets. It uses the navigation adapter which automatically handles priority-based fallback
+ * between different sentence types.
  *
  * @example
  * ```typescript
- * const machine = createNavigationNmeaMachine({
- *   externalVariation: 5.5,
- * });
+ * const machine = createNavigationNmeaMachine();
+ * const actor = createActor(machine);
+ * actor.start();
+ * actor.send({ type: 'CONNECT' });
  * ```
+ *
+ * @returns An XState state machine configured for navigation data computation.
+ *
+ * @remarks
+ * The returned machine is an XState state machine. Use it with XState's `createActor` to create
+ * an actor instance, or use the {@link NavigationNmeaClient} class for a simpler API that doesn't
+ * require direct XState knowledge.
  */
-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,18 +575,11 @@ 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.
  *
- * @template TData - The type of computed/translated data stored in context.
- * @template TPackets - The type of stored packets (typically a record of sentence ID to packet).
- * @param config - Configuration for the machine including adapter function and initial values.
- * @returns An XState machine configured with the provided adapter and types.
+ * Creates an XState state machine that manages serial port connections, parses NMEA sentences,
+ * and transforms them into your application's data format using the provided adapter function.
  *
  * @example
  * ```typescript
@@ -629,9 +589,23 @@ export declare function createNmeaChecksumFooter(sentenceWithoutChecksum: string
  *   initialData: { time: null, position: null },
  *   initialPackets: {},
  * });
+ *
+ * const actor = createActor(machine);
+ * actor.start();
+ * actor.send({ type: 'CONNECT' });
  * ```
+ *
+ * @template TData - The type of computed/translated data stored in context.
+ * @template TPackets - The type of stored packets (typically a record of sentence ID to packet).
+ * @param config - Configuration for the machine including adapter function and initial values.
+ * @returns An XState state machine that can be used with `createActor` from XState.
+ *
+ * @remarks
+ * The returned machine is an XState state machine. Use it with XState's `createActor` to create
+ * an actor instance, or use the {@link NmeaClient} class for a simpler API that doesn't require
+ * direct XState knowledge.
  */
-export declare function createNmeaMachine<TData, TPackets extends Record<string, unknown>>(config: NmeaMachineConfig<TData, TPackets>): StateMachine<NmeaContext<TData, TPackets>, {
+export declare function createNmeaMachine<TData, TPackets extends Record<string, PacketStub | undefined>>(config: NmeaMachineConfig<TData, TPackets>): StateMachine<NmeaContext<TData, TPackets>, {
 type: "CONNECT";
 } | {
 type: "DISCONNECT";
@@ -1159,74 +1133,26 @@ readonly CONNECT: "connecting";
 
 declare type CustomPackets = DBSPacket | DBKPacket | DPTPacket;
 
-export declare interface DBKPacket extends PacketStub<typeof sentenceId_3> {
+declare interface DBKPacket extends PacketStub<typeof sentenceId_3> {
     depthFeet: number;
     depthMeters: number;
     depthFathoms: number;
 }
 
-export declare interface DBSPacket extends PacketStub<typeof sentenceId_2> {
+declare interface DBSPacket extends PacketStub<typeof sentenceId_2> {
     depthFeet: number;
     depthMeters: number;
     depthFathoms: number;
 }
 
-export declare interface DPTPacket extends PacketStub<typeof sentenceId> {
+declare interface DPTPacket extends PacketStub<typeof sentenceId> {
     depthMeters: number;
     offsetMeters: number;
     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 +1178,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,12 +1187,112 @@ export declare interface NavigationData {
     } | null;
 }
 
+/**
+ * Simple client for navigation NMEA data.
+ * Creates a machine and manages connection state automatically.
+ *
+ * @example
+ * ```typescript
+ * const client = new NavigationNmeaClient({
+ *   enableLogging: true,
+ *   onData: (navigation) => {
+ *     console.log('Position:', navigation.position);
+ *   },
+ * });
+ *
+ * client.connect();
+ * ```
+ */
+export declare class NavigationNmeaClient extends NmeaClient<NavigationData, StoredPackets> {
+    /**
+     * Creates a new navigation NMEA client.
+     *
+     * @param options - Optional configuration and callbacks.
+     */
+    constructor(options?: NmeaClientOptions<NavigationData>);
+}
+
+/**
+ * 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, PacketStub | undefined>> {
+    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.
  * @template TPackets - The type of stored packets.
  */
-export declare interface NmeaContext<TData, TPackets extends Record<string, unknown>> {
+declare interface NmeaContext<TData, TPackets extends Record<string, PacketStub | undefined>> {
     /** The active Web Serial port connection, or null if disconnected. */
     port: SerialPort | null;
     /** Current error message, or null if no error. */
@@ -1284,7 +1310,7 @@ export declare interface NmeaContext<TData, TPackets extends Record<string, unkn
 /**
  * Events that the NMEA state machine can handle.
  */
-export declare type NmeaEvent = {
+declare type NmeaEvent = {
     type: 'CONNECT';
 } | {
     type: 'DISCONNECT';
@@ -1314,14 +1340,14 @@ export declare type NmeaEvent = {
  * @template TData - The type of computed/translated data.
  * @template TPackets - The type of stored packets.
  */
-export declare type NmeaMachineActor<TData, TPackets extends Record<string, unknown>> = ActorRefFrom<ReturnType<typeof createNmeaMachine<TData, TPackets>>>;
+export declare type NmeaMachineActor<TData, TPackets extends Record<string, PacketStub | undefined>> = ActorRefFrom<ReturnType<typeof createNmeaMachine<TData, TPackets>>>;
 
 /**
  * Configuration for creating an NMEA machine.
  * @template TData - The type of computed/translated data stored in context.
  * @template TPackets - The type of stored packets (typically a record of sentence ID to packet).
  */
-export declare interface NmeaMachineConfig<TData, TPackets extends Record<string, unknown>> {
+export declare interface NmeaMachineConfig<TData, TPackets extends Record<string, PacketStub | undefined>> {
     /** Function that transforms stored packets into the computed data type. */
     adapter: (packets: TPackets) => TData;
     /** Optional list of sentence IDs to filter and store. If not provided, all parsed sentences are stored. */
@@ -1332,54 +1358,8 @@ 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 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";
@@ -1391,14 +1371,13 @@ declare const sentenceId_3: "DBK";
 /**
  * Types for stored packets by sentence type.
  */
-export declare interface StoredPackets extends Record<string, unknown> {
+export declare interface StoredPackets extends Record<string, PacketStub | undefined> {
     GGA?: GGAPacket;
     RMC?: RMCPacket;
     GLL?: GLLPacket;
     VTG?: VTGPacket;
     HDT?: HDTPacket;
     HDG?: HDGPacket;
-    HDM?: HDMPacket;
     DPT?: DPTPacket;
     DBT?: DBTPacket;
     DBS?: DBSPacket;
@@ -1406,16 +1385,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 { }