Return values

Actions can return values using the same syntax as any Go function.

GOX automatically converts the returned value to a JavaScript-compatible type before delivering it to the client.

It is not necessary to manually serialize the data or use additional APIs to send information to the browser.

Return of values

An Action returns a single value.

func GetName() gox.Action {
    return "George"
}

const [name, err] = await Actions.GetName()

console.log(name)

The first element contains the value returned by the Action and the second contains any error produced during its execution.

Supported types

The Actions can return any of the following types.

GOX automatically determines the most appropriate representation for each type. In most cases no manual conversion is necessary.

Objects

The structures, maps, slices and arrays are automatically converted to their equivalent in JavaScript.

type User struct {
    Name string
    Age  int
}

func GetUser() gox.Action {
    return User{
        Name: "George",
        Age: 30,
    }
}

const [user, err] = await Actions.GetUser()

console.log(user.Name)
console.log(user.Age)

The exported fields of the structure are part of the object sent to the client.

HTML

Actions can return HTML content using gox.HTML.

func Card() gox.Action {
    return gox.HTML(`<article>
        <h2>George</h2>
        <p>Administrator</p>
    </article>`)
}

The client receives a HTMLElement when the content contains a single elemental root. If it contains several roots, it receives a DocumentFragment.

const [html, err] = await Actions.Card()

document.body.append(html)

gox.HTML identifies reliable HTML within the transport. It does not represent a handler or replace gox.Component.

To know your statement and methods, see the reference to HTML.

Files

Actions can return a file using gox.File.

func Download() gox.Action {
    file, err := gox.NewFile(gox.FileConfig{
        Path: "documents/report.pdf",
    })

    if err != nil {
        return err
    }

    return file
}

The client receives a native instance of File.

const [file, err] = await Actions.Download()

console.log(file.name)
console.log(file.type)
console.log(file.size)

The content can be used with any browser API.

const text = await file.text()
const buffer = await file.arrayBuffer()
const url = URL.createObjectURL(file)

It is also possible to return several files.

func DownloadAll() gox.Action {
    return []gox.File{
        report,
        invoice,
    }
}

const [files, err] = await Actions.DownloadAll()

for (const file of files) {
    console.log(file.name)
}

To know how to create files and all the capabilities of gox.File, consult the documentation of the File.

Streams

Actions can also return any value compatible with io.Reader.

func StreamLog() gox.Action {
    file, err := os.Open("server.log")

    if err != nil {
        return err
    }

    return file
}

The client receives a ReadableStream.

const [stream, err] = await Actions.StreamLog()

const reader = stream.getReader()

Streams are suitable when the content is to be consumed progressively.

When you need to deliver a full file to the browser it is preferable to use gox.File.

Large integers

GOX automatically converts the Go integers to the most suitable JavaScript type.

When the value can be safely represented using numberThe client gets a number.

func Value() gox.Action {
    return int64(42)
}

const [value, err] = await Actions.Value()

typeof value
// number

When the value exceeds the safe range of number, GOX automatically returns a bigint.

func Value() gox.Action {
    return int64(9007199254740993)
}

const [value, err] = await Actions.Value()

typeof value
// bigint

No manual conversions are necessary to preserve the accuracy of the large integers.

Nil values

When an Action returns nil, the client receives null.

func FindUser() gox.Action {
    return nil
}

const [user, err] = await Actions.FindUser()

if (user === null) {
    console.log("User not found")
}

Non-compatible types

The values returned by an Action should be able to be represented in JavaScript.

Exclusive types of Go's running environment, such as functions or channels, cannot be returned directly.

func Invalid() gox.Action {
    return make(chan string)
}

When a type is not compatible, GOX reports the problem during the compilation.

Integration with Go

The Actions use conventional Go values and types.

They do not require special structures to indicate how a result should be sent to the client.

GOX automatically analyses the return type and selects the most appropriate JavaScript representation.

This allows to reuse structures, custom types and existing models without creating specific versions for communication with the browser.

Best practices

• Returns the type that best represents the result of the operation.
• It uses structures to group related data.
• Returns gox.HTML when the result is HTML content.
• Use gox.File to send full files to the browser.
• Use io.Reader to transmit content progressively.
• Allows GOX to automatically determine when to use number or bigint.
• Avoid manually converting the data before returning them.
• See the documentation of the SDK to know the contracts of gox.HTML and gox.File.
• Do not expose internal structures that should not reach the client.

To learn more about ActionsSee your documentation. To learn more about ParametersSee your documentation. To learn more about FormsSee your documentation. To learn more about Errors, check your documentation.

See also

• Actions
• Parameters
• Forms
• HTML
• File
• Errors