LogoPear Docs
ReferencesBareModules

bare-pipe

Native I/O pipes for JavaScript

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)

Source

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

ParameterTypeDefaultDescription
pathstring | 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

Source

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

Parameters

ParameterTypeDefaultDescription
targetT—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

Source

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

ParameterTypeDefaultDescription
pathstring—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

Source

Whether the pipe is currently connecting.

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

Source

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

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

pending: boolean

Source

Whether the pipe has not yet connected.

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
  }
}
Source

Object containing internal state constants and handle type constants.

Pipe.createConnection

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

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

Parameters

ParameterTypeDefaultDescription
pathstring—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

Source

Create a new pipe server. The server extends EventEmitter.

Parameters

ParameterTypeDefaultDescription
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]

Source

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

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

Source

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

Pipe.ref(): this

Source

Ref the pipe, preventing the process from exiting.

Pipe.unref(): this

Source

Unref the pipe, allowing the process to exit.

write

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

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

ParameterTypeDefaultDescription
chunkBuffer | string—The data to write.
encodingBufferEncoding—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)

Source

Overloads:

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

Parameters

ParameterTypeDefaultDescription
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

Source

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

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

Source

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

Parameters

ParameterTypeDefaultDescription
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
Source

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

Parameters

ParameterTypeDefaultDescription
pathstring—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.

listening: boolean

Source

Whether the server is listening.

PipeServer.ref(): this

Source

Ref the pipe, preventing the process from exiting.

PipeServer.unref(): this

Source

Unref the pipe, allowing the process to exit.

Types

CreateConnectionOptions

interface CreateConnectionOptions extends PipeOptions, PipeConnectOptions {}
Source

IPCAcceptable

interface IPCAcceptable {
  readonly [ipcHandle]: unknown
  [ipcAccept]?(): void
}
Source

PipeEvents

interface PipeEvents extends DuplexEvents {
  connect: []
  handle: [type: number]
}
Source

PipeOptions

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

PipeConnectOptions

interface PipeConnectOptions {
  path?: string
}
Source

PipeServerEvents

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

PipeServerOptions

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

PipeServerListenOptions

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

Classes

PipeError

Source 
class PipeError {
  code: string
}

bare-pipe/constants

Constants and variables

constants

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
  }
}
Source

bare-pipe/errors

Classes

errors.PipeError

Source

See also

bare-atomics

Previous Page

bare-semver

Next Page

On this page

Usage
API
Pipe
new Pipe(path: string | number, opts?: PipeOptions)
accept<T extends IPCAcceptable>(target: T): T
connect(path: string, opts?: PipeConnectOptions, onconnect?: () => void): this
connecting: boolean
open(fd: number, opts?: { fd?: number }, onconnect?: () => void): this
pending: boolean
Pipe.constants
Pipe.createConnection
Pipe.createServer(opts?: PipeServerOptions, onconnection?: () => void): PipeServer
Pipe.pipe(): [read: number, write: number]
readyState: 'open' | 'readOnly' | 'writeOnly' | 'opening'
Pipe.ref(): this
Pipe.unref(): this
write
PipeServer
new PipeServer(opts?: PipeServerOptions, onconnection?: () => void)
address(): string | null
close(onclose?: (err?: Error) => void): this
listen
listening: boolean
PipeServer.ref(): this
PipeServer.unref(): this
Types
CreateConnectionOptions
IPCAcceptable
PipeEvents
PipeOptions
PipeConnectOptions
PipeServerEvents
PipeServerOptions
PipeServerListenOptions
Classes
PipeError
bare-pipe/constants
Constants and variables
constants
bare-pipe/errors
Classes
errors.PipeError
See also