hot.dev/hot-std / ::hot::lang

Functions

call core

fn (f: Fn, args: Vec): Any
fn (f: Fn, args: Vec, on-err: OnErr): Any
fn (f: Fn): Any

Call function f with args (default empty vec). Supports both single-argument and no-argument forms.

By default, a normal domain Err returned by the callee is forced. Pass OnErr.Preserve to return the Err as the call result instead. fail(), cancel(), and hard runtime errors still halt unless explicitly contained.

Example

// Call a function by reference
add-fn ::hot::math/add
call(add-fn, [1, 2])  // 3

// Call with no arguments
call(::hot::math/rand)  // 0.7234...

// Preserve a recoverable domain Err as a value
result call(maybe-fetch, [id], OnErr.Preserve)
if-err(result, (e) { fallback(e) })

functions-in-namespace core

fn (namespace: Namespace): Vec

Return all functions defined in namespace.

Example

fns functions-in-namespace(Namespace("::hot::math"))
// [add, sub, mul, div, ...]

namespaces core

fn (): Vec

Return all loaded namespaces.

Example

all-ns namespaces()
// [::hot::coll, ::hot::str, ::myapp::users, ...]

resolve core

fn (function-str: Str): Fn

Resolve a fully-qualified function name string to a Fn value.

Example

add-fn resolve("::hot::math/add")
call(add-fn, [1, 2])  // 3

try core

fn (f: Fn, args: Vec): Result
fn (f: Fn): Result

Call function f with args, catching exceptional halts (fail(), cancel()) and hard runtime errors as a normal Result.

• On success: Result.Ok(value)
• On failure: Result.Err(payload)

Most Hot code should not need try. Use normal Result values for expected domain errors, and usually let fail() / cancel() stop the run or task. Reach for try only at an explicit fault-isolation boundary, such as fan-out work where one item must be recorded without stopping the rest.

Its result composes with the normal Result helpers (is-ok, is-err, if-ok, if-err, match) and follows Hot's usual auto-unwrapping rules: bind the result or pass it to a lazy helper when you want to inspect it.

attempt try(() { run-digest-for-session(s) })
if-err(attempt, (failure) { record-error("digest", failure) })

try-call core

fn (f: Fn, args: Vec): Map
fn (f: Fn): Map

Call function f with args, catching all errors — including runtime panics — and returning a plain Map (not a Result, so the return value won't be auto-unwrapped).

• On success: {ok: true, value: <result>}
• On failure: {ok: false, error: "error message"}

Deprecated: prefer try(...), which returns a normal Result and composes with is-ok, is-err, if-ok, if-err, and match.

Use this legacy helper only when you need the old non-Result map shape:

1. Fault isolation across independent units of work — scheduled fan-out where one item's failure must not kill the loop, e.g. for-each(sessions, (s) { try(...) }).
2. Dynamic dispatch where you don't trust the function reference (built from resolve(...) or pulled from config).
3. Defensive boundaries for built-ins that don't yet have Result-returning siblings.

Prefer Result for known-error APIs. If a stdlib function can fail in a structured way, it should return Result<T, E> and callers should branch on is-err. Reach for try only when no Result form is available, or when you genuinely need to catch arbitrary runtime errors (depth-limit overflow, type mismatches, etc.) that Result doesn't model.

Common Result-returning siblings to use instead:

• ::hot::http/try-request(...) — for outbound HTTP calls.
• ::hot::base64/is-valid(s) followed by ::hot::base64/decode(s) — for guarding malformed input.

Example (fault isolation across sessions)

for-each(sessions, (s) {
    result try(() { run-digest-for-session(s) })
    cond {
        is-err(result) => { record-error("digest", `${s.id}: ${Str(result)}`) }
    }
})

call-event-handler event

fn (event: Map): Any

Event handler: call a function specified in event data.

The once: true flag ensures this handler runs only once per event, even when multiple projects are deployed in the same environment.

ns alias

Alias of ::hot::lang/

Language introspection and function invocation utilities.

schedule-cancel-event-handler event

fn (event: Map): Bool

Event handler: cancel a scheduled call (one-time or recurring).

The once: true flag ensures this handler runs only once per event, even when multiple projects are deployed in the same environment.

Example

// Cancel by schedule-id
send("hot:schedule:cancel", {schedule-id: "01234567-..."})

// Cancel by function name (cancels all schedules for this function)
send("hot:schedule:cancel", {fn: "::myapp::jobs/heavy-process"})

Returns true if schedule was found and cancelled.

schedule-event-handler event

fn (event: Map): Any

Event handler: execute scheduled function from event data.

The once: true flag ensures this handler runs only once per event, even when multiple projects are deployed in the same environment.

schedule-new-event-handler event

fn (event: Map): Str

Event handler: create a new schedule (one-time or recurring).

The once: true flag ensures this handler runs only once per event, even when multiple projects are deployed in the same environment.

Supported schedule formats

• ISO datetime: "2024-01-15T10:30:00Z"
• Duration: "10 minutes", "2h", "1 day 3 hours"
• Natural: "in 10 minutes", "2 hours from now"
• Cron: "0 30 9 * * MON", "@daily"
• English: "every day at 9am", "every Monday at 2 PM"

Example

// Schedule for specific time
send("hot:schedule:new", {
    fn: "::myapp::orders/process",
    args: [{order_id: "123"}],
    schedule: "2024-01-15T10:30:00Z"
})

// Schedule for 10 minutes from now
send("hot:schedule:new", {
    fn: "::myapp::reminders/send",
    args: [{user_id: user.id}],
    schedule: "in 10 minutes"
})

// Create a recurring schedule dynamically
send("hot:schedule:new", {
    fn: "::myapp::reports/daily",
    args: [],
    schedule: "every day at 9am"
})

Returns the schedule_id which can be used to cancel.