# function

> A function is a top-level unit of work, written like a C# method — a return type, a name, typed parameters, a body. It runs transactionally. Called on its own it commits when it finishes; called from a page with a row as an argument it joins the page's unit of work, and its writes are stored when the page commits.

<!-- id: function-declaration · area: function · stability: stable · html: https://osysharp.com/reference/function/declaration/ -->

## Summary        {#summary}
A function is the unit of work: a return type, a name, typed parameters and a body, written exactly like a C# method
but declared at the top level of a file. It is where you create rows, query them and decide things.

It runs **transactionally**: a function that fails half-way leaves nothing behind. Whether its writes are stored
when it returns depends on **who called it**, and that is the one thing to know:

- Called **on its own** — from a test, a workflow, an endpoint or schedule, a function running on the server, or from a page
  with only plain values (`string`, `int`, …) as arguments — it runs in a unit of work of its own, and the rows it
  writes are committed together when it returns.
- Called **from a page with a row as an argument** (`void Strip(Route r)` from an `action`), it joins the **page's**
  unit of work: its writes show on screen at once and are stored only when that page commits. If nothing on the page
  calls `UnitOfWork.Commit()`, they are discarded when the page goes away — with no error, and with every test that
  only looks at the screen passing. End such a function (or the action) with `UnitOfWork.Commit();`. `osy validate`
  and `osy test` print this case as `DATA_NEVER_SAVED`, naming the write.

The examples on this page are called on their own, so they need no commit. A body inside a `component` always works
in the page's unit of work — see [creating & saving data](https://osysharp.com/reference/ui/data-mutation/) and [UnitOfWork](https://osysharp.com/reference/function/unit-of-work/). Pages are getting an explicit
unit-of-work mode; until then, the rule above is how it works.

## Signature      {#signature}
```osy syntax
<ReturnType> <Name>(<Type> <param>, …) {
  <statements>
}

```

## Description    {#description}

### How do I declare a function?   {#declaring}
`void` when it returns nothing, a type when it returns something. Parameters are typed and camelCase; the function
name is PascalCase:

```osy title="a function that writes, and one that reads" test app=function-declaration
entity Order {
  [Required] string Code;
  decimal Total;
}

void PlaceOrder(string code, decimal total) {
  var o = new Order { Code = code, Total = total };
}

decimal OrderTotal(string code) {
  var o = Order.Single(x => x.Code == code);
  return o.Total;
}
```

### It commits as one unit   {#transactional}
Everything a function writes lands together, or not at all. That is what lets you write the obvious thing:

```osy title="two rows, one outcome" test app=function-declaration
entity AuditLine {
  [Required] string Message;
}

void PlaceAndLog(string code, decimal total) {
  var o = new Order { Code = code, Total = total };
  var a = new AuditLine { Message = "placed " + code };
  // both rows commit together — there is no state where the order exists and the log line does not
}
```

If the function faults — a constraint violation, an invariant, a division by zero — **neither row is written.** You
do not have to unwind anything by hand.

### Does a function that calls out need `async`?   {#no-async}
No. A function that reaches outside the database — an HTTP call, an LLM completion — is written **exactly like any
other function**: no `async`, no `Task<T>`, and no colour to keep track of. (`async` is for running two calls side by
side — [async / await and Task](https://osysharp.com/reference/function/async-await/).)

```osy title="a function that calls out — no async anywhere" test app=function-declaration-async
app Shop {
  model "model/**/*.osy";
  use Osysharp.Http;
}

string Fetch(string url) {
  var r = Http.Get(url);           // just a call — the engine suspends and resumes around it
  return r.IsSuccess ? r.Body : "";
}
```

Those outward calls are **effects**, and the platform handles them: when a function hits one, the engine suspends it,
performs the effect, and resumes the function where it left off — even if that means surviving a process restart in
between. You do not have to mark the function, and neither does its caller.

This is why C#'s `async` is absent rather than merely optional. `async` exists to colour a function so its *callers*
know to await it, and that colour spreads until it has infected everything it touches. Here the durability is the
engine's job, not the signature's, so there is nothing to spread.

`await` appears in exactly one place in the language — `Workflow.Run()` — where you are genuinely waiting for another
long-running thing to finish, and want to say so. If you are coming from C#, [async / await and Task](https://osysharp.com/reference/function/async-await/) is the page to
read: it is the first habit to unlearn.

### Where may a function be declared?   {#where}
**At the top level of a file — that is what a `function` is.** It is not nested in anything, and there is no
namespace, module or class you have to put it inside first. A file may hold as many as you like, beside its entities
and components. Not inside an entity, though: an entity body holds data, and behaviour sits beside it.

Two things that LOOK like the same question are not, and the difference is what each one commits:

| you write it… | what it is | where it runs | what saves it |
|---|---|---|---|
| at the top level of a file | a **function** | inferred from its body — see [Crossing the network](https://osysharp.com/reference/function/execution-side/) | itself, on return |
| inside a `component` | a **method** of that component | with the component | the page's `UnitOfWork.Commit()` |
| inside a `class` | a **method** of that class | wherever it is called from | its caller |

All three are written identically — a return type, a name, a typed parameter list, a body — so the enclosing
declaration is the only thing that decides which you have. There is no `function` keyword to write and no `method`
keyword either; see [Writing a component — what differs from C#](https://osysharp.com/reference/ui/csharp-differences/) for why.

```osy title="all three, in one file" test app=function-declaration-where
int Doubled(int n) { return n * 2; }                            // a function

class Rates { public decimal WithVat(decimal net) { return net * 1.25m; } }   // a class method

[Route("/counter")] [AllowAnonymous] [Render(CSR)]
component Counter() {
  int n = 1;
  int Quadrupled(int x) { return x * 4; }                       // a component method
  action Bump() { n = Quadrupled(n); }
  render { Text("n=" + n); }
}
```

And the top-level form beside the data it works on:

```osy title="behaviour lives beside the data, not inside it" test app=function-declaration
entity Product {
  [Required] string Name;
  decimal Price;
}

decimal PriceWithVat(Product p, decimal rate) {
  return Math.Round(p.Price * (1 + rate), 2);
}
```

If you want behaviour *attached* to a type — a method with a receiver — that is a [class method](https://osysharp.com/reference/class/methods/).

## See also       {#see-also}
- [var](https://osysharp.com/reference/function/var/) — locals inside the body
- [if / else](https://osysharp.com/reference/function/if/) · [foreach](https://osysharp.com/reference/function/foreach/) · [while](https://osysharp.com/reference/function/while-loop/) — control flow
- [class methods](https://osysharp.com/reference/class/methods/) — behaviour attached to a type
- [async / await and Task](https://osysharp.com/reference/function/async-await/) — `async`, `await` and `Task`: running calls side by side
- [Running tests](https://osysharp.com/reference/testing/running-tests/) — how you run one