Home Reference Source Repository 
import WriteAheadLog from 'wal/src/write-ahead-log.js'
public class | source

WriteAheadLog

An encapsulation of write-ahead logging behavior.

Write-ahead logging (WAL) is a building block used to improve automicity and durability in distributed systems. WAL improves these properties by providing persistent, sequenced storage for Log Entries as well as a record of which Log Entries have been committed. Write-ahead logging enables systems to recover from failures, whether those failures are in software, storage, or the network.

This implementation provides a basic semantic on which reliable systems can be built.

Constructor Summary

Public Constructor
public

constructor(file: *, index: *)

Member Summary

Public Members
public get
public get
public get
public get
public get
public get

Method Summary

Public Methods
public

close(): *

public

commit(index: number): Promise

Commits the specified, uncommitted LSN/index.
public

Determines if the specified LSN/index has been committed.
public

read(index: number): Promise

Reads the log entry at the specified LSN/index.
public

readRange(first: number, count: number): Readable

Reads a range of log entries beginning at the specified first LSN/index.
public

recover(handler: *): *

public

Truncates the log from the specified, uncommitted LSN/index.
public

write(data: Buffer): Promise

Writes a log entry.

Public Constructors

public constructor(file: *, index: *) source

Params:

NameTypeAttributeDescription
file *
index *

Public Members

public get commitHead: number source

public get index: string source

public get name: string source

public get next: number source

public get size: number source

public get writable: boolean source

Public Methods

public close(): * source

Return:

*

public commit(index: number): Promise source

Commits the specified, uncommitted LSN/index.

wal.commit(lsn)
  .then(lsn => {
     console.log(lsn + ' successfully committed');
  })
  .catch(err => {
     console.log(`Unexpected error during commit of ${lsn}: ${''+err.stack}.`);
  })

Params:

NameTypeAttributeDescription
index number

The LSN/index to commit.

Return:

Promise

A promise that upon success is resolved with the specified, committed LSN/index.

public isCommitted(index: number): Promise source

Determines if the specified LSN/index has been committed.

wal.isCommitted(lsn)
  .then(committed => {
     if (committed) console.log(lsn + ' is committed');
  });

Params:

NameTypeAttributeDescription
index number

The LSN/index to check.

Return:

Promise

A promise that upon success is resolved with boolean indicating whether the LSN/index has been committed.

public read(index: number): Promise source

Reads the log entry at the specified LSN/index.

wal.read(lsn)
  .then(data => {
    console.log(`Log Entry ${lsn} has ${data.length} bytes of data.`);
  })
  .catch(err => {
     console.log(`Unexpected error: ${''+err.stack}.`);
  })

Params:

NameTypeAttributeDescription
index number

Specifies the LSN/index of the log entry to read.

Return:

Promise

A promise that upon success is resolved with a buffer containing the log entry

Throw:

AssertionError

Thrown when the LSN/index is out of range.

public readRange(first: number, count: number): Readable source

Reads a range of log entries beginning at the specified first LSN/index. If count is not specified all subsequent log entries are returned.

wal.readRange(first)
  .then(stream => new Promise((resolve, reject) => {
      let acc = [];
      stream.on('data', data => {
         acc.push(data);
       })
       .on('end', () => resolve(acc))
       .on('error', reject);
     }))
  .then(entries => {
    console.log(`There are ${entries.length} log entries after LSN ${first}.`);
  })
  .catch(err => {
     console.log(`Unexpected error: ${''+err.stack}.`);
  })

Params:

NameTypeAttributeDescription
first number

Specifies the index of the first log entry to read.
count number

Specifies the number of log entries to read.

Return:

Readable

A readable stream where the log entries are streamed to the caller.

public recover(handler: *): * source

Params:

NameTypeAttributeDescription
handler *

Return:

*

public truncate(from: number): Promise source

Truncates the log from the specified, uncommitted LSN/index.

Since the .next property is usually ahead of the .commitHead, when this call succeeds it resets the write head to the newly truncated LSN/index position. Be aware that the very next .write() will re-use this most-recent truncated LSN/index.

wal.truncate(first)
  .then(size => {
    console.log(`There are ${bytes} committed to the log.`);
  })
  .catch(err => {
     console.log(`Unexpected error: ${''+err.stack}.`);
  })

Params:

NameTypeAttributeDescription
from number

Specifies the LSN/index where the log entries should be truncated.

Return:

Promise

A promise that upon success is resolved with the new write head.

public write(data: Buffer): Promise source

Writes a log entry.

The entire contents of the specified data buffer is written as the log entry, the actual binary data is treated as opaque in the log. Since the log is not involved in the interpretation of the data, concerns such as encryption and data security is entirely the caller's responsibility.

wal.write(data)
  .then(lsn => {
     console.log(`Data written as Log Entry ${lsn}.`);
  })
  .catch(err => {
     console.log(`Unexpected error: ${''+err.stack}.`);
  })

Params:

NameTypeAttributeDescription
data Buffer

The log entry as an opaque data buffer.

Return:

Promise

A promise that upon success is resolved with the new entry's LSN/index.

Throw:

AssertionError

thrown when data is unspecified or not a Buffer.