bare-pipe

stable

bare-pipe — Native I/O pipes for JavaScript. It is a native addon and requires Bare >=1.16.0.

npm i bare-pipe

Usage

const Pipe = require('bare-pipe')

const stdout = new Pipe(1)

stdout.write('Hello world!\n')

API

Pipe

`new Pipe(path: string | number, opts?: PipeOptions)`

Create a new pipe. If path is a number, it is treated as a file descriptor to open. If it is a string, it is treated as a path to connect to.

Overloads:

new Pipe(path: string | number, opts?: PipeOptions)
new Pipe(opts?: PipeOptions)

Parameters

Parameter	Type	Default	Description
`path`	`string` \| `number`	—	A file descriptor to open (number), or a path to connect to (string).
`opts?`	`PipeOptions`	—	Options; `readBufferSize` defaults to `65536`, `allowHalfOpen` and `eagerOpen` to `true`, and `ipc` to `false` (set `ipc: true` to enable handle passing over the pipe).

`accept<T extends IPCAcceptable>(target: T): T`

Accept a pending handle into target. target must implement the IPCAcceptable protocol. Call this synchronously from the 'handle' event listener.

Parameters

Parameter	Type	Default	Description
`target`	`T`	—	The object to accept the pending handle into; must implement the `IPCAcceptable` protocol. Call synchronously from the `'handle'` event listener.

Returns T — target, for chaining the accepted handle into an expression.

Throws

INVALID_IPC_TARGET — target does not implement the IPC handle protocol.

`connect(path: string, opts?: PipeConnectOptions, onconnect?: () => void): this`

Connect the pipe to path. onconnect is called when the connection is established.

Overloads:

connect(path: string, opts?: PipeConnectOptions, onconnect?: () => void): this
connect(path: string, onconnect: () => void): this
connect(opts: PipeConnectOptions, onconnect?: () => void): this

Parameters

Parameter	Type	Default	Description
`path`	`string`	—	The path to connect to.
`opts?`	`PipeConnectOptions`	—	Options; `path` may be given here instead of as the first argument.
`onconnect?`	`() => void`	—	Called when the connection is established.

Throws

PIPE_ALREADY_CONNECTED — the pipe is already connecting or connected.

`connecting: boolean`

Whether the pipe is currently connecting.

`open(fd: number, opts?: { fd?: number }, onconnect?: () => void): this`

Open the pipe on the given file descriptor.

Overloads:

open(fd: number, opts?: { fd?: number }, onconnect?: () => void): this
open(fd: number, onconnect: () => void): this
open(opts: { fd: number }, onconnect?: () => void): this

Parameters

Parameter	Type	Default	Description
`fd`	`number`	—	The file descriptor to open the pipe on.
`opts?`	`{ fd?: number }`	—	—
`onconnect?`	`() => void`	—	Called once when the pipe emits `'connect'`.

`Pipe.constants`

Pipe.constants: {
  state: {
    CONNECTING: number
    CONNECTED: number
    BINDING: number
    BOUND: number
    READING: number
    CLOSING: number
    READABLE: number
    WRITABLE: number
    UNREFED: number
  }
  handle: {
    NAMED_PIPE: number
    TCP: number
    UDP: number
  }
}

Object containing internal state constants and handle type constants.

`Pipe.createConnection`

Pipe.createConnection(path: string, opts?: CreateConnectionOptions, onconnect?: () => void): Pipe

Create a new pipe and connect it to path. Shorthand for new Pipe(options).connect(path, options, onconnect).

Parameters

Parameter	Type	Default	Description
`path`	`string`	—	The path to connect to.
`opts?`	`CreateConnectionOptions`	—	Options passed to both the `Pipe` constructor and `connect()`.
`onconnect?`	`() => void`	—	Called when the connection is established.

`Pipe.createServer(opts?: PipeServerOptions, onconnection?: () => void): PipeServer`

Create a new pipe server. The server extends EventEmitter.

Parameters

Parameter	Type	Default	Description
`opts?`	`PipeServerOptions`	—	Options applied to each incoming pipe; `readBufferSize` defaults to `65536`, `allowHalfOpen` to `true`, `pauseOnConnect` to `false`, and `ipc` to `false`.
`onconnection?`	`() => void`	—	Called on each `'connection'` event.

`Pipe.pipe(): [read: number, write: number]`

Returns [read: number, write: number] — A [read, write] pair of file descriptors connected to each other.

`readyState: 'open' | 'readOnly' | 'writeOnly' | 'opening'`

The current state of the pipe. One of 'open', 'readOnly', 'writeOnly', or 'opening'.

`Pipe.ref(): this`

Ref the pipe, preventing the process from exiting.

`Pipe.unref(): this`

Unref the pipe, allowing the process to exit.

`write`

write(chunk: Buffer | string, encoding: BufferEncoding, handle?: IPCAcceptable, cb?: (err: Error | null) => void): boolean

Write chunk to the pipe. If handle is given and the pipe was created with ipc: true, the handle is transferred to the receiver alongside the chunk. handle must implement the IPCAcceptable protocol.

Parameters

Parameter	Type	Default	Description
`chunk`	`Buffer` \| `string`	—	The data to write.
`encoding`	`BufferEncoding`	—	The encoding of `chunk` when it is a string.
`handle?`	`IPCAcceptable`	—	A handle to transfer to the receiver alongside the chunk; requires the pipe to have been created with `ipc: true` and `handle` to implement the `IPCAcceptable` protocol.
`cb?`	`(err: Error \| null) => void`	—	Called when the chunk has been processed.

PipeServer

`new PipeServer(opts?: PipeServerOptions, onconnection?: () => void)`

Overloads:

new PipeServer(opts?: PipeServerOptions, onconnection?: () => void)
new PipeServer(onconnection: () => void)

Parameters

Parameter	Type	Default	Description
`opts?`	`PipeServerOptions`	—	Options applied to each incoming pipe; `readBufferSize` defaults to `65536`, `allowHalfOpen` to `true`, `pauseOnConnect` to `false`, and `ipc` to `false`.
`onconnection?`	`() => void`	—	Called on each `'connection'` event.

`address(): string | null`

Returns string | null — The bound path, or null if the server is not listening.

`close(onclose?: (err?: Error) => void): this`

Close the server. No new connections will be accepted. The server emits close after all existing connections have ended.

Parameters

Parameter	Type	Default	Description
`onclose?`	`(err?: Error) => void`	—	Called once when the server emits `'close'`, after all existing connections have ended.

`listen`

listen(path: string, backlog?: number, opts?: PipeServerListenOptions, onlistening?: () => void): this

Start listening for connections on path. backlog defaults to 511.

Parameters

Parameter	Type	Default	Description
`path`	`string`	—	The path to listen on.
`backlog?`	`number`	—	The maximum length of the queue of pending connections (default `511`).
`opts?`	`PipeServerListenOptions`	—	`path` and `backlog` may be given here instead of as positional arguments.
`onlistening?`	`() => void`	—	Called once when the server emits `'listening'`.

Throws

SERVER_ALREADY_LISTENING — the server is already listening.
SERVER_IS_CLOSED — the server has been closed.

interface CreateConnectionOptions {
  allowHalfOpen?: boolean
  eagerOpen?: boolean
  ipc?: boolean
  readBufferSize?: number
  path?: string
}

`IPCAcceptable`

interface IPCAcceptable {
}

`PipeEvents`

interface PipeEvents {
  connect: []
  handle: [type: number]
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}

`PipeOptions`

interface PipeOptions {
  allowHalfOpen?: boolean
  eagerOpen?: boolean
  ipc?: boolean
  readBufferSize?: number
}

`PipeConnectOptions`

interface PipeConnectOptions {
  path?: string
}

`PipeServerEvents`

interface PipeServerEvents {
  close: []
  connection: [pipe: Pipe]
  error: [err: Error]
  listening: []
}

`PipeServerOptions`

interface PipeServerOptions {
  allowHalfOpen?: boolean
  ipc?: boolean
  pauseOnConnect?: boolean
  readBufferSize?: number
}

`PipeServerListenOptions`

interface PipeServerListenOptions {
  path?: string
  backlog?: number
}

Classes

`PipeError`

class PipeError {
  code: string
}

constants: {
  state: {
    CONNECTING: number
    CONNECTED: number
    BINDING: number
    BOUND: number
    READING: number
    CLOSING: number
    READABLE: number
    WRITABLE: number
    UNREFED: number
  }
  handle: {
    NAMED_PIPE: number
    TCP: number
    UDP: number
  }
}

bare-pipe

On this page