GPS.js is a typed NMEA 0183 parser for GPS and GNSS receivers. It parses individual sentences, consumes arbitrarily split streams, emits sentence-specific events, and maintains a normalized receiver state.
The library handles supplied NMEA text only. Opening serial devices, sockets, and other transports remains an application concern.
import GPS from 'gps';const gps = new GPS();gps.on('GGA', fix => { console.log(fix.lat, fix.lon, fix.alt);});gps.update( '$GPGGA,224900.000,4832.3762,N,00903.5393,E,1,04,7.8,498.6,M,48.0,M,,0000*5E');
CommonJS is supported as well:
const GPS = require('gps');const gps = new GPS();
The package includes TypeScript declarations. Event names narrow callback payloads automatically:
import GPS from 'gps';const gps = new GPS();gps.on('RMC', record => { record.speed; // number | null, in km/h record.navStatus; // safe | caution | unsafe | not valid | null});
Parsing Sentences
Use GPS.Parse() when accumulated receiver state and events are unnecessary:
GPS.Parse() returns false for unsupported or structurally rejected input. A recognized sentence with a bad checksum is returned with valid: false.
gps.update() emits recognized checksum-invalid records so applications can inspect reception errors, but does not merge them into gps.state or multipart TXT buffers. Both rejected and checksum-invalid input increment state.errors.
Streaming Input
updatePartial() buffers incomplete chunks and accepts CRLF or LF delimiters:
const gps = new GPS();gps.on('data', record => console.log(record));gps.updatePartial('$GPGGA,224900.000,4832.3762,N,');gps.updatePartial('00903.5393,E,1,04,7.8,498.6,M,48.0,M,,0000*5E\r\n');
Events
Subscribe to data for every parsed sentence or use a sentence identifier such as GGA, RMC, or GSV:
on() and off() return the receiver instance for chaining.
Receiver State
gps.state is updated in place as valid sentences arrive. It includes counters and the latest available navigation values:
gps.on('data', record => { if (record.valid) { console.log(gps.state.lat, gps.state.lon, gps.state.speed); }});
Depending on the received sentences, state may contain time, lat, lon, alt, speed, track, heading, fix, dilution values, active satellite IDs, and visible satellite records. Snapshot values when historical states are needed.
Supported Sentences
Sentence
Data
GGA
Fix position, quality, altitude, and dilution
GSA
Fix mode, active satellites, dilution, and GNSS system
RMC
Position, speed, track, date, mode, and navigation status
VTG
True/magnetic track and speed
GSV
Satellites in view, signal strength, and GNSS system
GLL
Geographic position and status
ZDA
UTC date/time and local offset
GST
Position error statistics
HDT
Heading relative to true north
GRS
Range residuals
GPS, GLONASS, Galileo, BeiDou, QZSS, and NavIC identifiers are normalized where the sentence provides enough information.
Every parsed record includes:
type: the sentence identifier
raw: the original sentence
valid: whether the checksum matches
Blank optional numeric fields are represented as null rather than NaN.
Geospatial Helpers
Coordinates use decimal degrees. Distances are returned in kilometers and headings use compass degrees, with north at 0 and east at 90.
Distance() uses the haversine formula on a spherical Earth model. It is suitable for navigation estimates, not survey-grade ellipsoidal geodesy.
Browser Usage
The browser IIFE exposes a global GPS constructor and also supports AMD loaders:
<script src="https://unpkg.com/gps/dist/gps.min.js"></script><script> const gps = new GPS();</script>
The browser ESM build is available through the gps/browser package export:
import GPS from 'gps/browser';
Published artifacts are:
dist/gps.js: CommonJS
dist/gps.mjs: ES module
dist/gps.min.js: minified browser IIFE with AMD support
dist/gps.min.mjs: minified browser ES module
Development
npm installnpm test
npm test runs strict TypeScript checking, builds every distribution, validates CommonJS and ESM type consumers, and executes the runtime and distribution suites.