API Reference

Classes

ChildProcess

Handle to a running child process.

Initializers

bring util;

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

Name	Type	Description
`program`	`str`	No description.
`args`	`MutArray<str>`	No description.
`opts`	`SpawnOptions`	No description.

`program`^Required

Type: str

`args`^Required

Type: MutArray<str>

`opts`^Optional

Type: SpawnOptions

Methods

Name	Description
`kill`	Kill the process.
`wait`	Wait for the process to finish and return its output.

`kill`

kill(signal?: num): void

Kill the process.

`signal`^Optional

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

Name	Type	Description
`pid`	`num`	The child's OS-assigned process ID.

`pid`^Optional

pid: num;

Type: num

The child's OS-assigned process ID.

Util

Utility functions.

Static Functions

Name	Description
`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.

`stringToDecode`^Required

Type: str

base64 string to decode.

`url`^Optional

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.

`stringToEncode`^Required

Type: str

The name of the UTF-8 string to encode.

`url`^Optional

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.

`name`^Required

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.

`program`^Required

Type: str

The program to execute.

`args`^Required

Type: MutArray<str>

An array of arguments to pass to the program.

`opts`^Optional

Type: ExecOptions

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

`options`^Optional

Type: NanoidOptions

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.

`name`^Required

Type: str

The name of the environment variable.

`value`^Required

Type: str

The value of the environment variable.

`sha256`

bring util;

util.sha256(data: str);

Computes the SHA256 hash of the given data.

`data`^Required

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.

`command`^Required

Type: str

The command string to execute in the shell.

`opts`^Optional

Type: ShellOptions

ShellOptions, such as the working directory and environment variables.

`sleep`

bring util;

util.sleep(delay: duration);

Suspends execution for a given duration.

`delay`^Required

Type: duration

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.

`program`^Required

Type: str

The program to execute.

`args`^Required

Type: MutArray<str>

An array of arguments to pass to the program.

`opts`^Optional

Type: SpawnOptions

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.

`name`^Required

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

`options`^Optional

Type: UlidOptions

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.

`predicate`^Required

Type: IPredicateHandler

The function that will be evaluated.

`props`^Optional

Type: WaitUntilProps

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

Name	Type	Description
`cwd`	`str`	Path to a directory to run the command in.
`env`	`MutMap<str>`	Environment variables.
`inheritEnv`	`bool`	Whether to inherit environment variables from the host's environment.

`cwd`^Optional

cwd: str;

Type: str
Default: the default working directory of the host

Path to a directory to run the command in.

`env`^Optional

env: MutMap<str>;

Type: MutMap<str>
Default: no environment variables

Environment variables.

`inheritEnv`^Optional

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

Name	Type	Description
`cwd`	`str`	Path to a directory to run the command in.
`env`	`MutMap<str>`	Environment variables.
`inheritEnv`	`bool`	Whether to inherit environment variables from the host's environment.

`cwd`^Optional

cwd: str;

Type: str
Default: the default working directory of the host

Path to a directory to run the command in.

`env`^Optional

env: MutMap<str>;

Type: MutMap<str>
Default: no environment variables

Environment variables.

`inheritEnv`^Optional

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

Name	Type	Description
`alphabet`	`str`	Characters that make up the alphabet to generate the ID, limited to 256 characters or fewer.
`size`	`num`	Size of ID.

`alphabet`^Optional

alphabet: str;

Type: str

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

`size`^Optional

size: num;

Type: num
Default: 21

Size of ID.

Output

Output of a finished process.

Initializer

bring util;

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

Properties

Name	Type	Description
`status`	`num`	A process's exit status.
`stderr`	`str`	The standard error of a finished process.
`stdout`	`str`	The standard output of a finished process.

`status`^Required

status: num;

Type: num

A process's exit status.

`stderr`^Required

stderr: str;

Type: str

The standard error of a finished process.

`stdout`^Required

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

Name	Type	Description
`cwd`	`str`	Path to a directory to run the command in.
`env`	`MutMap<str>`	Environment variables.
`inheritEnv`	`bool`	Whether to inherit environment variables from the host's environment.
`throw`	`bool`	Whether to throw an error on command execution failure.

`cwd`^Optional

cwd: str;

Type: str
Default: the default working directory of the host

Path to a directory to run the command in.

`env`^Optional

env: MutMap<str>;

Type: MutMap<str>
Default: no environment variables

Environment variables.

`inheritEnv`^Optional

inheritEnv: bool;

Type: bool
Default: false

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

`throw`^Optional

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

Name	Type	Description
`cwd`	`str`	Path to a directory to run the command in.
`env`	`MutMap<str>`	Environment variables.
`inheritEnv`	`bool`	Whether 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.

`cwd`^Optional

cwd: str;

Type: str
Default: the default working directory of the host

Path to a directory to run the command in.

`env`^Optional

env: MutMap<str>;

Type: MutMap<str>
Default: no environment variables

Environment variables.

`inheritEnv`^Optional

inheritEnv: bool;

Type: bool
Default: false

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

`stderr`^Optional

stderr: Stdio;

Type: Stdio
Default: Stdio.INHERIT

Configuration for the process's standard error stream.

`stdin`^Optional

stdin: Stdio;

Type: Stdio
Default: Stdio.INHERIT

Configuration for the process's standard input stream.

`stdout`^Optional

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

Name	Type	Description
`seed`	`num`	You can also input a seed time which will consistently give you the same string for the time component.

`seed`^Optional

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

Name	Type	Description
`interval`	`duration`	Interval between predicate retries.
`throws`	`bool`	Whether to throw an error if the timeout elapses.
`timeout`	`duration`	The timeout for keep trying predicate.

`interval`^Optional

interval: duration;

Type: duration
Default: 0.1s

Interval between predicate retries.

`throws`^Optional

throws: bool;

Type: bool
Default: true

Whether to throw an error if the timeout elapses.

`timeout`^Optional

timeout: duration;

Type: duration
Default: 1m

The timeout for keep trying predicate.

Protocols

IPredicateHandler

Extends: IInflight
Implemented By: IPredicateHandler

Inflight client: @winglang/sdk.util.IPredicateHandlerClient

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

IPredicateHandlerClient

Implemented By: IPredicateHandlerClient

Inflight client for IPredicateHandler.

Methods

Name	Description
`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

Name	Description
`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.

API Reference

Classes ​

ChildProcess ​

Initializers ​

programRequired ​

argsRequired ​

optsOptional ​

Methods ​

kill ​

signalOptional ​

wait ​

Properties ​

pidOptional ​

Util ​

Static Functions ​

base64Decode ​

stringToDecodeRequired ​

urlOptional ​

base64Encode ​

stringToEncodeRequired ​

urlOptional ​

env ​

nameRequired ​

exec ​

programRequired ​

argsRequired ​

optsOptional ​

nanoid ​

optionsOptional ​

os ​

setEnv ​

nameRequired ​

valueRequired ​

sha256 ​

dataRequired ​

shell ​

commandRequired ​

optsOptional ​

sleep ​

delayRequired ​

spawn ​

programRequired ​

argsRequired ​

optsOptional ​

tryEnv ​

nameRequired ​

ulid ​

optionsOptional ​

uuidv4 ​

waitUntil ​

predicateRequired ​

propsOptional ​

Structs ​

CommandOptions ​

Initializer ​

Properties ​

cwdOptional ​

envOptional ​

inheritEnvOptional ​

ExecOptions ​

Initializer ​

Properties ​

cwdOptional ​

envOptional ​

inheritEnvOptional ​

NanoidOptions ​

Initializer ​

Properties ​

alphabetOptional ​

sizeOptional ​

Output ​

Initializer ​

Properties ​

statusRequired ​

stderrRequired ​

stdoutRequired ​

ShellOptions ​

Initializer ​

Properties ​

cwdOptional ​

Classes

ChildProcess

Initializers

`program`^Required

`args`^Required

`opts`^Optional

Methods

`kill`

`signal`^Optional

`wait`

Properties

`pid`^Optional

Util

Static Functions

`base64Decode`

`stringToDecode`^Required

`url`^Optional

`base64Encode`

`stringToEncode`^Required

`url`^Optional

`env`

`name`^Required

`exec`

`program`^Required

`args`^Required

`opts`^Optional

`nanoid`

`options`^Optional

`os`

`setEnv`

`name`^Required

`value`^Required

`sha256`

`data`^Required

`shell`

`command`^Required

`opts`^Optional

`sleep`

`delay`^Required

`spawn`

`program`^Required

`args`^Required

`opts`^Optional

`tryEnv`

`name`^Required

`ulid`

`options`^Optional

`uuidv4`

`waitUntil`

`predicate`^Required

`props`^Optional

Structs

CommandOptions

Initializer

Properties

`cwd`^Optional

`env`^Optional

`inheritEnv`^Optional

ExecOptions

Initializer

Properties

`cwd`^Optional

`env`^Optional

`inheritEnv`^Optional

NanoidOptions

Initializer

Properties

`alphabet`^Optional

`size`^Optional

Output

Initializer

Properties

`status`^Required

`stderr`^Required

`stdout`^Required

ShellOptions

Initializer

Properties

`cwd`^Optional

`env`^Optional