Hosts Utilities - Beta

Table of Contents

• What is it?
• Why did I make this library?
• Why is it in beta?
• Install
• Use
• API
  • assignHostnames
  • hostsPath
  • parse
  • removeHostnames
  • write
• Schemas
  • Parse Options
  • Remove Hostnames Options
  • Assign Hostnames Options
  • Write Options
  • Format Options
  • Parsed Line

What is it?

A few node utilities for working with your hosts file, inspired by Hostile

[!note] If you're looking for a CLI frontend, raise an issue and I'll write one.

Why did I make this library?

I wanted to programatically work with my hosts file while maintaining formatting. Hostile doesn't seem to be maintained anymore and lacks features I was looking for.

Why is it in beta?

Because I haven't worked much with hosts files and can't be confident in the code until it's used in the real world.

The hosts file seems simple, but in my experience, real-world implementations of anything are quirky.

Install

npm install hosts-utilities

Use

Assume a hosts file /etc/hosts

1.2.3.4 hostname1

We can add hostname2 using assignHostnames

import * as hosts from 'hosts-utilities'

await hosts.assignHostnames('1.2.3.4', ['hostname2'])

// updates /etc/hosts to
// 1.2.3.4 hostname1 hostname2

API

[!note] Both named and sub-path exports are available. Paths are kebab-cased. Example:

import { hostsPath } from 'hosts-utilities'
// or
import hostsPath from 'hosts-utilities/hosts-path'

assignHostnames

What is it?

• A function to add or update host entries

Why use it?

• To add hostnames to an existing entry, or add a new entry

Signature

• async (ip: string, hostnames: string[], options: AssignOptions = {}) => undefined
  • ip and hostnames must match /^[^#\s]+$/

Examples

Assume a file /etc/hosts with

1.2.3.4 hostname1 hostname2

await assignHostnames('1.2.3.4', ['hostname1', 'hostname3'])
// updates /etc/hosts to
// 1.2.3.4 hostname1 hostname2 hostname3

await assignHostnames('5.6.7.8', ['hostname4'])
// adds the line
// 5.6.7.8 hostname4

hostsPath

A string

• On windows: C:\Windows\System32\drivers\etc\hosts
• On not windows: /etc/hosts

parse

What is it?

• A function which parses the hosts file

Why use it?

• This let's you perform your own logic on the hosts file. For example, you could parse it, modify the parsed lines, then call write(updatedParsedLines)

Signature

• async (options: ParseOptions = {}) => ParsedLine[]

Examples

• here's an example of a parsed file

const parsedLines1 = await parse()
const parsedLines2 = await parse({ filePath: '/path/to/custom/hosts' })

removeHostnames

What is it?

• A function removing the hostnames from a hosts file

Why use it?

• Self explanatory

Signature

• async (hostnames: string[], options: RemoveOptions = {}) => undefined
  • hostnames must match /^[^#\s]+$/

Examples

Let's assume a file /etc/hosts with

1.2.3.4 hostname1
5.6.7.8 hostname2 hostname3

await removeHostnames(['hostname1', 'hostname2'])
// updates /etc/hosts to
// 5.6.7.8 hostname3

write

What is it?

• A function to write parsedLines to the host file

Why use it?

• Like parse, this lets you perform your own logic on the hosts file. For example, you could parse it, modify the parsedLines, then write them.

Signature

• async (parsedLines: ParsedLine[], options: WriteOptions = {}) => undefined

Examples

• here are some examples of writing your own parsedLines

const parsedLines = await parse()
const updatedLines = doSomethingTo(parsedLines)
await write(updatedLines)

Schemas

Parse Options

{
  // default: hostsPath
  // validation: minimum of one character
  filePath?: string
}

Remove Hostnames Options

Includes FormatOptions

FormatOptions & {
  // default: hostsPath
  // validation: minimum of one character
  filePath?: string

  // default: undefined (removes hostnames for all ips)
  // validation: matches /^[^#\s]+$/
  withIp?: string
}

[!warning] The option withIp is provided because Hostile supports it, meaning I assume someone found it helpful. Keep in mind hosts shouldn't be mapped to more than one IP address, so withIp should be unnecessary.

Assign Hostnames Options

Includes FormatOptions

FormatOptions & {
  // default: hostsPath
  // validation: minimum of one character
  filePath?: string
}

Write Options

Includes FormatOptions

FormatOptions & {
  // default: hostsPath
  // validation: minimum of one character
  filePath?: string
}

Format Options

[!note] Due to complexity, these options may not behave as you expect.

• See details here
• and examples here

At a glance

{
  preserveFormatting?: boolean = true
  separatorParts?: string = '\t'
  separatorHostname?: string = ' '
}

Parsed Line

[!note] Due to complexity, this structure may not work how you expect.

• See details here
• and examples here

At a glance

{
  original: string
  data: {
    ip: string
    hostnamesWithSpace: string[]
    comment: string
    space: {
      beforeIp: string
      afterIp: string
      beforeComment: string
    }
  }
}