Node

A NodeJS program is defined like a browser-based Gren program, except that there is more flexibility regarding how it is initialized.

You can initialize any number of subsystems, like FileSystem or Terminal, before initializing your own program with the results of those initializations.

As part of initializing a subsystem, you usually also get access to a value that permits you to contact said subsystem. Be careful what code you give these permissions to.

Program

type alias Program model msg = Program {} (Model model) (Msg model msg)

The definition of a Gren program that runs on NodeJS.
type alias ProgramConfiguration model msg =
{ init : Environment -> Task { model : model, command : Cmd msg }
, update : msg -> model -> { model : model, command : Cmd msg }
, subscriptions : model -> Sub msg
}

The required functions that define a program.
defineProgram : ProgramConfiguration model msg -> Program model msg

Define a program with access to long-lived state and the ability to respond to messages and listen to subscriptions. If you want to define a simple and short-lived program, chances are you're looking for defineSimpleProgram instead.
startProgram :
{ model : model
, command : Cmd cmd
}
-> Task { model : model, command : Cmd cmd
}

This lets the runtime know that you're done initializing other subsystems, and that your program is ready to start.

Simple Program

type alias SimpleProgram a = Program {} a

A program that executes a single task and then exits.
defineSimpleProgram : (Environment -> Task (Cmd a)) -> SimpleProgram a

Define a simple program that doesn't require long-lived state or the ability to respond to messages or subscriptions. Ideal for simple and short-lived programs.
endSimpleProgram : Task Never x -> Task (Cmd a)

When defining a program with defineSimpleProgram, use this function to define the final command to execute.

Environment information

type alias Environment =
{ platform : Platform
, cpuArchitecture : CpuArchitecture
, applicationPath : Path
, args : Array String
, stdout : Writable Bytes
, stderr : Writable Bytes
, stdin : Readable Bytes
}

Contains information about the environment your application was initiated in.

  • platform and cpuArchitecture tells you something about the operating system and machine your application is running on.
  • applicationPath is the path to the currently executing program.
  • args is an Array of the arguments passed to your application.
  • stdout, stderr and stdin are streams you can use to communicate with the outside world. Take a closer look at the Stream module for more information.
getEnvironmentVariables : Task x (Dict String String)

Get a Dict of environment variables.
type Platform
= Win32
| Darwin
| Linux
| FreeBSD
| OpenBSD
| SunOS
| Aix
| UnknownPlatform String

The platform, or operating system, that your application is running on.
getPlatform : Task x Platform

Retrieve the platform of the computer running the application.
type CpuArchitecture
= Arm
| Arm64
| IA32
| Mips
| Mipsel
| PPC
| PPC64
| S390
| S390x
| X64
| UnknownArchitecture String

The CPU architecture your application is running on.
getCpuArchitecture : Task x CpuArchitecture

Retrieve the CPU architecture of the computer running the application.

Exit

exit : Task x {}

Terminate the program immediatly. It will not wait for tasks like http calls or file system writes to complete.

This function is equivalent to:

exitWithCode 0
exitWithCode : Int -> Task x {}

Terminate the program immediatly. It will not wait for tasks like http calls or file system writes, so only use this if you've reached a state where it makes no sense to continue.

The exit code can be read by other processes on your system. Any value other than 0 is considered an error, but there are no other formal requirements for what makes an exit code. If all you want is to signalize that your application exited due to an error, -1 is a good option.
setExitCode : Int -> Task x {}

Set the error code that the program will return once it finishes.

Note: This will not terminate your program, so things like http calls or writes to the filesystem will be allowed to complete. However, the program will only exit once there are no ongoing tasks.