Skip to main content

API Reference

Classes

ChildProcess

Handle to a running child process.

Initializers

bring util;

new util.ChildProcess(program: str, args: MutArray<str>, opts?: SpawnOptions);
NameTypeDescription
program
strNo description.
args
MutArray<str>No description.
opts
SpawnOptions
No description.

programRequired
  • Type: str

argsRequired
  • Type: MutArray<str>

optsOptional

Methods

NameDescription
kill
Kill the process.
wait
Wait for the process to finish and return its output.

kill
kill(signal?: num): void

Kill the process.

signalOptional
  • Type: num

the signal to send to the process (defaults to SIGTERM).


wait
wait(): Output

Wait for the process to finish and return its output.

Calling this method multiple times will return the same output.

Properties

NameTypeDescription
pid
numThe child's OS-assigned process ID.

pidOptional
pid: num;
  • Type: num

The child's OS-assigned process ID.


Util

Utility functions.

Static Functions

NameDescription
base64Decode
Converts a string from base64 to UTF-8.
base64Encode
Converts a string from UTF-8 to base64.
env
Returns the value of an environment variable.
exec
Execute a program with the given arguments, wait for it to finish, and return its outputs.
nanoid
Generates a unique ID using the nanoid library.
os
Returns a string identifying the operating system platform.
setEnv
Sets the given name and value as an environment variable.
sha256
Computes the SHA256 hash of the given data.
shell
Executes a command in the shell and returns its standard output.
sleep
Suspends execution for a given duration.
spawn
Execute a program with the given arguments, and return a ChildProcess object that can be used to interact with the process while it is running.
tryEnv
Returns the value of an environment variable.
ulid
Generates universally unique lexicographically sortable identifier.
uuidv4
Generates a version 4 UUID.
waitUntil
Run a predicate repeatedly, waiting until it returns true or until the timeout elapses.

base64Decode
bring util;

util.base64Decode(stringToDecode: str, url?: bool);

Converts a string from base64 to UTF-8.

stringToDecodeRequired
  • Type: str

base64 string to decode.


urlOptional
  • Type: bool

If true, the source is expected to be a URL-safe base64 string.


base64Encode
bring util;

util.base64Encode(stringToEncode: str, url?: bool);

Converts a string from UTF-8 to base64.

stringToEncodeRequired
  • Type: str

The name of the UTF-8 string to encode.


urlOptional
  • Type: bool

If true, a URL-safe base64 string is returned.


env
bring util;

util.env(name: str);

Returns the value of an environment variable.

Throws if not found or empty.

nameRequired
  • Type: str

The name of the environment variable.


exec
bring util;

util.exec(program: str, args: MutArray<str>, opts?: ExecOptions);

Execute a program with the given arguments, wait for it to finish, and return its outputs.

programRequired
  • Type: str

The program to execute.


argsRequired
  • Type: MutArray<str>

An array of arguments to pass to the program.


optsOptional

ExecOptions, such as the working directory and environment variables.


nanoid
bring util;

util.nanoid(options?: NanoidOptions);

Generates a unique ID using the nanoid library.

https://github.com/ai/nanoid

optionsOptional

Optional options object for generating the ID.


os
bring util;

util.os();

Returns a string identifying the operating system platform.

Example

"linux", "darwin", "win32"
setEnv
bring util;

util.setEnv(name: str, value: str);

Sets the given name and value as an environment variable.

nameRequired
  • Type: str

The name of the environment variable.


valueRequired
  • Type: str

The value of the environment variable.


sha256
bring util;

util.sha256(data: str);

Computes the SHA256 hash of the given data.

dataRequired
  • Type: str

The string to be hashed.


shell
bring util;

util.shell(command: str, opts?: ShellOptions);

Executes a command in the shell and returns its standard output.

commandRequired
  • Type: str

The command string to execute in the shell.


optsOptional

ShellOptions, such as the working directory and environment variables.


sleep
bring util;

util.sleep(delay: duration);

Suspends execution for a given duration.

delayRequired

The time to suspend execution.


spawn
bring util;

util.spawn(program: str, args: MutArray<str>, opts?: SpawnOptions);

Execute a program with the given arguments, and return a ChildProcess object that can be used to interact with the process while it is running.

programRequired
  • Type: str

The program to execute.


argsRequired
  • Type: MutArray<str>

An array of arguments to pass to the program.


optsOptional

Spawn options including working directory, environment variables, and stdio configurations.


tryEnv
bring util;

util.tryEnv(name: str);

Returns the value of an environment variable.

Returns nil if not found or empty.

nameRequired
  • Type: str

The name of the environment variable.


ulid
bring util;

util.ulid(options?: UlidOptions);

Generates universally unique lexicographically sortable identifier.

https://github.com/ulid/javascript

optionsOptional

Optional options object for generating the ID.


uuidv4
bring util;

util.uuidv4();

Generates a version 4 UUID.

waitUntil
bring util;

util.waitUntil(predicate: IPredicateHandler, props?: WaitUntilProps);

Run a predicate repeatedly, waiting until it returns true or until the timeout elapses.

If the timeout elapses, the function throws an error.

Alternatively, you can pass throws: false to suppress the error, and instead return a boolean indicating whether the predicate returned true within the timeout.

predicateRequired

The function that will be evaluated.


propsOptional

Timeout and interval values, default to one 1m timeout and 0.1sec interval.


Structs

CommandOptions

Base command options.

Initializer

bring util;

let CommandOptions = util.CommandOptions{ ... };

Properties

NameTypeDescription
cwd
strPath to a directory to run the command in.
env
MutMap<str>Environment variables.
inheritEnv
boolWhether to inherit environment variables from the host's environment.

cwdOptional
cwd: str;
  • Type: str
  • Default: the default working directory of the host

Path to a directory to run the command in.


envOptional
env: MutMap<str>;
  • Type: MutMap<str>
  • Default: no environment variables

Environment variables.


inheritEnvOptional
inheritEnv: bool;
  • Type: bool
  • Default: false

Whether to inherit environment variables from the host's environment.


ExecOptions

Additional options for util.exec().

Initializer

bring util;

let ExecOptions = util.ExecOptions{ ... };

Properties

NameTypeDescription
cwd
strPath to a directory to run the command in.
env
MutMap<str>Environment variables.
inheritEnv
boolWhether to inherit environment variables from the host's environment.

cwdOptional
cwd: str;
  • Type: str
  • Default: the default working directory of the host

Path to a directory to run the command in.


envOptional
env: MutMap<str>;
  • Type: MutMap<str>
  • Default: no environment variables

Environment variables.


inheritEnvOptional
inheritEnv: bool;
  • Type: bool
  • Default: false

Whether to inherit environment variables from the host's environment.


NanoidOptions

Options to generating a unique ID.

Initializer

bring util;

let NanoidOptions = util.NanoidOptions{ ... };

Properties

NameTypeDescription
alphabet
strCharacters that make up the alphabet to generate the ID, limited to 256 characters or fewer.
size
numSize of ID.

alphabetOptional
alphabet: str;
  • Type: str

Characters that make up the alphabet to generate the ID, limited to 256 characters or fewer.


sizeOptional
size: num;
  • Type: num
  • Default: 21

Size of ID.


Output

Output of a finished process.

Initializer

bring util;

let Output = util.Output{ ... };

Properties

NameTypeDescription
status
numA process's exit status.
stderr
strThe standard error of a finished process.
stdout
strThe standard output of a finished process.

statusRequired
status: num;
  • Type: num

A process's exit status.


stderrRequired
stderr: str;
  • Type: str

The standard error of a finished process.


stdoutRequired
stdout: str;
  • Type: str

The standard output of a finished process.


ShellOptions

Additional options for util.shell().

Initializer

bring util;

let ShellOptions = util.ShellOptions{ ... };

Properties

NameTypeDescription
cwd
strPath to a directory to run the command in.
env
MutMap<str>Environment variables.
inheritEnv
boolWhether to inherit environment variables from the host's environment.
throw
boolWhether to throw an error on command execution failure.

cwdOptional
cwd: str;
  • Type: str
  • Default: the default working directory of the host

Path to a directory to run the command in.


envOptional
env: MutMap<str>;
  • Type: MutMap<str>
  • Default: no environment variables

Environment variables.


inheritEnvOptional
inheritEnv: bool;
  • Type: bool
  • Default: false

Whether to inherit environment variables from the host's environment.


throwOptional
throw: bool;
  • Type: bool
  • Default: true

Whether to throw an error on command execution failure.


SpawnOptions

Additional options for util.spawn().

Initializer

bring util;

let SpawnOptions = util.SpawnOptions{ ... };

Properties

NameTypeDescription
cwd
strPath to a directory to run the command in.
env
MutMap<str>Environment variables.
inheritEnv
boolWhether to inherit environment variables from the host's environment.
stderr
Stdio
Configuration for the process's standard error stream.
stdin
Stdio
Configuration for the process's standard input stream.
stdout
Stdio
Configuration for the process's standard output stream.

cwdOptional
cwd: str;
  • Type: str
  • Default: the default working directory of the host

Path to a directory to run the command in.


envOptional
env: MutMap<str>;
  • Type: MutMap<str>
  • Default: no environment variables

Environment variables.


inheritEnvOptional
inheritEnv: bool;
  • Type: bool
  • Default: false

Whether to inherit environment variables from the host's environment.


stderrOptional
stderr: Stdio;
  • Type: Stdio
  • Default: Stdio.INHERIT

Configuration for the process's standard error stream.


stdinOptional
stdin: Stdio;
  • Type: Stdio
  • Default: Stdio.INHERIT

Configuration for the process's standard input stream.


stdoutOptional
stdout: Stdio;
  • Type: Stdio
  • Default: Stdio.INHERIT

Configuration for the process's standard output stream.


UlidOptions

Options to generate universally unique lexicographically sortable identifiers.

Initializer

bring util;

let UlidOptions = util.UlidOptions{ ... };

Properties

NameTypeDescription
seed
numYou can also input a seed time which will consistently give you the same string for the time component.

seedOptional
seed: num;
  • Type: num
  • Default: Date.now()

You can also input a seed time which will consistently give you the same string for the time component.

This is useful for migrating to ulid.


WaitUntilProps

Properties for util.waitUntil.

Initializer

bring util;

let WaitUntilProps = util.WaitUntilProps{ ... };

Properties

NameTypeDescription
interval
duration
Interval between predicate retries.
throws
boolWhether to throw an error if the timeout elapses.
timeout
duration
The timeout for keep trying predicate.

intervalOptional
interval: duration;

Interval between predicate retries.


throwsOptional
throws: bool;
  • Type: bool
  • Default: true

Whether to throw an error if the timeout elapses.


timeoutOptional
timeout: duration;

The timeout for keep trying predicate.


Protocols

IPredicateHandler

Inflight client: @winglang/sdk.util.IPredicateHandlerClient

A predicate with an inflight "handle" method that can be passed to util.busyWait.

IPredicateHandlerClient

Inflight client for IPredicateHandler.

Methods

NameDescription
handle
The Predicate function that is called.

handle
inflight handle(): bool

The Predicate function that is called.

Enums

Stdio

Describes what to do with a standard I/O stream for a child process.

Members

NameDescription
INHERIT
The child inherits from the corresponding parent descriptor.
PIPED
A new pipe should be arranged to connect the parent and child processes.
NULL
This stream will be ignored.

INHERIT

The child inherits from the corresponding parent descriptor.


PIPED

A new pipe should be arranged to connect the parent and child processes.


NULL

This stream will be ignored.

This is the equivalent of attaching the stream to /dev/null.