ubx-parser 0.1.4 → 0.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 A native Node.js addon for parsing [u-blox UBX binary protocol](https://www.u-blox.com/) messages (GNSS/GPS). Built with [node-addon-api](https://github.com/nodejs/node-addon-api) (N-API) and wraps the [CommsChampion](https://github.com/commschamp) ecosystem for protocol definitions.
 
-Supports 315+ UBX message types with sub-millisecond parsing and auto-generated TypeScript definitions.
+Supports 315+ UBX message types with sub-millisecond parsing and auto-generated TypeScript definitions. Includes two complementary classes: `UbxParser` for streaming and `UbxLog` for file-based navigation.
 
 ## Installation
 
@@ -47,6 +47,45 @@ for (const msg of messages) {
 }
 ```
 
+### File-based log reader
+
+```js
+const { UbxLog } = require('ubx-parser');
+
+const log = await UbxLog.open('recording.ubx');
+
+console.log(`Total messages: ${log.count()}`);
+console.log(`NAV-PVT count: ${log.count('NAV-PVT')}`);
+console.log(`Message types: ${log.messageTypes().join(', ')}`);
+
+// Navigate forward
+const msg = log.next('NAV-PVT');
+console.log(msg);
+
+// Get the 5th NAV-PVT message (0-based)
+const fifth = log.get('NAV-PVT', 4);
+
+// Seek to beginning and iterate
+log.seek(0);
+let m;
+while ((m = log.next()) !== null) {
+  console.log(m.name);
+}
+
+log.close();
+```
+
+`UbxLog` builds a SQLite index on first open (saved as a companion `.idx` file). Subsequent opens reuse the index for instant access. Messages are deep-parsed on demand.
+
+## When to use which class
+
+| | `UbxParser` | `UbxLog` |
+|---|---|---|
+| **Use case** | Streaming / real-time data | Post-processing log files |
+| **Input** | Byte chunks (feed incrementally) | File path |
+| **Navigation** | Forward only (event-driven) | Random access, cursor-based |
+| **Memory** | Buffers only partial frames | SQLite index + on-demand parsing |
+
 ## API
 
 ### `new UbxParser()`
@@ -70,6 +109,38 @@ Static method. Parses a complete buffer and returns all decoded messages.
 
 Static method. Returns field metadata for all supported UBX message types. Used internally by the type generation script.
 
+### `UbxLog.open(filePath: string): Promise<UbxLog>`
+
+Static async factory. Opens a `.ubx` file, builds or reuses a companion `.idx` index, and resolves with a ready `UbxLog` instance.
+
+### `log.count(name?: string): number`
+
+Returns total message count, or count of a specific message type.
+
+### `log.messageTypes(): string[]`
+
+Returns an array of distinct message type names found in the file.
+
+### `log.next(name?: string): UbxMessage | null`
+
+Advances the cursor and returns the next message (optionally filtered by type). Returns `null` at end.
+
+### `log.prev(name?: string): UbxMessage | null`
+
+Moves the cursor backward and returns the previous message. Returns `null` at beginning.
+
+### `log.seek(pos: number): void`
+
+Positions the cursor. `seek(0)` resets to the beginning. `seek(-1)` moves to the end (for backward iteration with `prev()`).
+
+### `log.get(name: string, ordinal: number): UbxMessage | null`
+
+Returns the Nth message (0-based) of a given type, without affecting the cursor.
+
+### `log.close(): void`
+
+Closes the file handle.
+
 ## TypeScript
 
 Full TypeScript definitions are included with typed interfaces for all 315+ message types and type-narrowing event listeners.

package/lib/index.js

@@ -34,4 +34,48 @@ class UbxParser extends EventEmitter {
   }
 }
 
-module.exports = { UbxParser };
+const NativeUbxLog = ubx.UbxLog;
+
+class UbxLog {
+  /** @type {import('../types').NativeUbxLog} */
+  _native;
+
+  constructor(native) {
+    this._native = native;
+  }
+
+  static async open(filePath) {
+    const native = await NativeUbxLog.open(filePath);
+    return new UbxLog(native);
+  }
+
+  count(name) {
+    return name !== undefined ? this._native.count(name) : this._native.count();
+  }
+
+  messageTypes() {
+    return this._native.messageTypes();
+  }
+
+  next(name) {
+    return name !== undefined ? this._native.next(name) : this._native.next();
+  }
+
+  prev(name) {
+    return name !== undefined ? this._native.prev(name) : this._native.prev();
+  }
+
+  seek(pos) {
+    this._native.seek(pos);
+  }
+
+  get(name, ordinal) {
+    return this._native.get(name, ordinal);
+  }
+
+  close() {
+    this._native.close();
+  }
+}
+
+module.exports = { UbxParser, UbxLog };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ubx-parser",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "Native Node.js addon for parsing u-blox UBX binary protocol (GNSS/GPS) messages",
   "main": "lib/index.js",
   "types": "types.d.ts",

package/types.d.ts

@@ -3879,3 +3879,14 @@ export declare class UbxParser {
   static parse(data: Uint8Array): UbxMessage[];
   static schema(): object[];
 }
+
+export declare class UbxLog {
+  static open(filePath: string): Promise<UbxLog>;
+  count(name?: string): number;
+  messageTypes(): string[];
+  next(name?: string): UbxMessage | null;
+  prev(name?: string): UbxMessage | null;
+  seek(pos: number): void;
+  get(name: string, ordinal: number): UbxMessage | null;
+  close(): void;
+}