TypeScript library to read/watch the Player Journal of Frontier's game Elite: Dangerous.
Interfaces are provided for all events so you can work with them type-safe and get completion help in your favorite TypeScript IDE.
Old events/properties which have been renamed in newer game versions are automatically converted to the new names so an application build for current game version can most likely also read the older journal files.
Install the dependency:
$ npm install @kayahr/ed-journal
The following simple example shows how to use the Journal class to read all events from all journal files in chronological order and print the timestamp and event name and specially handle the Music event to print the music track.
import { Journal } from "@kayahr/ed-journal";
const journal = await Journal.open();
try {
for await (const event of journal) {
console.log(event.timestamp, event.event);
if (event.event === "Music") {
// TypeScript automatically infers the event to be "Music"
// so it knows its properties
console.log(event.MusicTrack);
}
});
} finally {
await journal.close();
}
With modern JavaScript it also possible to use the Journal with await using instead of try...finally so it is closed automatically when the end of the scope is reached:
import { Journal } from "@kayahr/ed-journal";
await using journal = await Journal.open();
for await (const event of journal) {
console.log(event.timestamp, event.event);
});
You can pass JournalOptions when opening a Journal with the following properties:
| Option | Description |
|---|---|
| directory | The journal directory to scan. Automatically determined if not specified (See Journal directory location section below) |
| position | The position within the journal to start reading it. Can be start (Default, start of journal), end (end of journal), a event name (starting at last occurrence of this event in the journal) or a JournalPosition object with properties file, offset and line to specify an exact manual position within the journal. |
| watch | Set to true to watch the journal directory for new events after reading the existing ones. When false (default) then only existing events are read and then reading ends. |
If you want your application to remember the journal position on shutdown and continue from this position when application is started again you can read the current JournalPosition (consisting of file, offset and line) from the journal object, persist it in some way and use it again when starting the application again. Example:
// Read previously persisted journal position
// (hardcoded in this example)
let position: JournalPosition = {
file: "Journal.2022-06-07T181623.01.log",
offset: 54133,
line: 95
};
const journal = await Journal.open({ watch: true, position });
try {
for await (const event of journal) {
// Do something with the events.
// At some point use `break` to stop watching
}
// Get current position from journal and persist it somewhere
position = journal.getPosition();
} finally {
await journal.close();
}
The game writes some additional JSON files containing only a single event which is overwritten regularly. The current event from these files can be read with the following methods on the journal instance:
These methods return a single event object or null if the corresponding JSON file is not accessible (not yet present for example).
Example:
const journal = await Journal.open();
try {
const status = await journal.readStatus();
console.log(status);
} finally {
await journal.close();
}
You can also watch these files for changes which works pretty much the same way as watching the normal journal events by using the following methods on the journal instance:
These methods return an async generator to iterate. The current event is always reported as first change when the file already exists.
Example:
const journal = await Journal.open();
try {
for await (const event of journal.watchStatus()) {
// Do something with the events
// At some point use `break` to stop watching
}
} finally {
await journal.close();
}
The generators automatically stop when journal is closed. So you might want to do the watching of various files in asynchronous background functions while your main application thread controls the journal. Example:
async function watchStatus(journal: Journal): Promise<void> {
for await (const event of journal.watchStatus()) {
console.log(status);
}
}
const journal = await Journal.open();
try {
// Returned promise is resolved when watching ends after journal
// is closed. But we don't need this promise, so voided here.
void watchStatus(journal);
// Run application here until it quits
...
} finally {
await journal.close();
}
Some IDs in the Journal (Like SystemAddress for example) are 64 bit integers. But the JavaScript number type can only handle integers up to 53 bit. So when a number exceeds this range then it is interpreted as a large floating point number which looses precision, which is very bad for IDs. To fix this problem ed-journal uses a special JSON reviver when parsing the journal logs to convert numbers, which are too large for JavaScript, into the BigInt type. So the value type of an ID-like property like SystemAddress for example can either be number or BigInt, depending on how many bits the number actually needs. The typescript typings use an ID type for these properties to express that.
BigInt values cannot be serialized. So when you need to serialize a journal event, which was read with ed-journal, back into a JSON string, then it is recommended to use the json-with-bigint library, which automatically handles this and writes the correct 64 bit numbers into the JSON string.
The location of the journal directory is automatically determined by looking at the following locations:
When the library does not find your journal directory then you can either use the directory option to specify it manually or define the $ED_JOURNAL_DIR environment variable.