# Utility Classes

> Share code between all your code in API Maker with utility classes - written in TypeScript, Python, PHP, C#, Go, Rust, Java or Kotlin, imported the way each language imports, in custom APIs, hooks, events, schedulers, migrations and test cases, with interfaces, versions and Git.

Source: https://docs.apimaker.dev/v4/docs/utility-class/utility-class.html

A utility class is code shared by all your code : helpers, validations, pricing rules, clients of external services, interfaces. Write it once on the **Utility Classes** page (`APIs & Logic → Utility Classes`), in TypeScript or in [any other language](https://docs.apimaker.dev/v4/docs/utility-class/utility-class.html#other-languages) API Maker runs, and use it in all the code of that language. In TypeScript you import it anywhere with `utils/<Name>`.

## Create one

Click **+**, give a path (a folder to group them) and a name. The name is unique, starts with a capital letter, and is what you import.

**TypeScript**

**The utility class Calculator**

```typescript
class Calculator {
    add(x: number, y: number) {
        return x + y;
    }
    multi(x: number, y: number) {
        return x * y;
    }
}
let temp = new Calculator();
export = temp;
```

**A custom API which uses it**

```typescript
import * as T from 'types';
import * as calc from 'utils/Calculator';

async function main(g: T.IAMGlobal) {
    return { sum: calc.add(3, 6), product: calc.multi(3, 6) };
}
module.exports = main;
```

**Python**

**The utility class Calculator**

```python
def add(x, y):
    return x + y


def multi(x, y):
    return x * y
```

**A custom API which uses it**

```python
import Calculator as calc


async def main(g):
    return {'sum': calc.add(3, 6), 'product': calc.multi(3, 6)}
```

**PHP**

**The utility class Calculator**

```php
<?php
class Calculator
{
    public static function add($x, $y)
    {
        return $x + $y;
    }

    public static function multi($x, $y)
    {
        return $x * $y;
    }
}
```

**A custom API which uses it**

```php
<?php
function main(AmG $g)
{
    return ['sum' => Calculator::add(3, 6), 'product' => Calculator::multi(3, 6)];
}
```

**C#**

**The utility class Calculator**

```csharp
public static class Calculator
{
    public static double Add(double x, double y) => x + y;

    public static double Multi(double x, double y) => x * y;
}
```

**A custom API which uses it**

```csharp
file static class Api
{
    public static async Task<object?> Main(G g)
    {
        return new { sum = Calculator.Add(3, 6), product = Calculator.Multi(3, 6) };
    }
}
```

**Go**

**The utility class Calculator, in the folder utils**

```go
package calculator

func Add(x, y float64) float64 {
	return x + y
}

func Multi(x, y float64) float64 {
	return x * y
}
```

**A custom API which uses it**

```go
package code

import (
	"apimaker/am"
	calc "apimaker/src/utility_classes/utils---Calculator"
)

func Main(g *am.G) (any, error) {
	return am.M{"sum": calc.Add(3, 6), "product": calc.Multi(3, 6)}, nil
}
```

**Rust**

**The utility class Calculator**

```rust
pub fn add(x: f64, y: f64) -> f64 {
    x + y
}

pub fn multi(x: f64, y: f64) -> f64 {
    x * y
}
```

**A custom API which uses it**

```rust
use am::{Errors, G, Value, json};

use crate::Calculator as calc;

pub fn main(g: &mut G) -> Result<Value, Errors> {
    Ok(json!({ "sum": calc::add(3.0, 6.0), "product": calc::multi(3.0, 6.0) }))
}
```

**Java**

**The utility class Calculator**

```java
public class Calculator {
    public static double add(double x, double y) {
        return x + y;
    }

    public static double multi(double x, double y) {
        return x * y;
    }
}
```

**A custom API which uses it**

```java
import am.G;
import java.util.Map;

class Api {
    static Object main(G g) {
        return Map.of("sum", Calculator.add(3, 6), "product", Calculator.multi(3, 6));
    }
}
```

**Kotlin**

**The utility class Calculator**

```kotlin
object Calculator {
    fun add(x: Double, y: Double) = x + y

    fun multi(x: Double, y: Double) = x * y
}
```

**A custom API which uses it**

```kotlin
import am.G

fun main(g: G): Any? {
    return mapOf("sum" to Calculator.add(3.0, 6.0), "product" to Calculator.multi(3.0, 6.0))
}
```

- In TypeScript the file exports an **instance** (`export = temp`), so the importer calls the methods directly. The other languages name what a class declares the way they import things : see [below](https://docs.apimaker.dev/v4/docs/utility-class/utility-class.html#other-languages).
- The class can hold state : a connection opened in a method stays for the life of the sandbox.

## Use one

- Works in custom APIs, pre and post hooks, event listeners, schedulers, migration scripts, process initializers, WebSocket connect code and test cases.
- Press Ctrl+Space after `utils/` in the editor to see every class.
- A method which needs API Maker takes `g` as a parameter : `Pricing.total(g, order)`.

## The classes of a language

The list of the page has a dropdown next to its search : **All languages**, then each language on each of its runtimes (TypeScript on Node.js, TypeScript on Bun, Python, C# on .NET…), with how many classes each one shows. A choice shows the classes the code of that language uses, in the tree and in the grid : the classes written in TypeScript or JavaScript for Node.js and for Bun alike, the classes written in Python for Python. A class added while the list shows a language starts in that language.

On the API testing page, **Show Utility Classes** next to the code opens the dialog of the classes with the ones the code of the editor uses : those of its language, on its runtime. Pick **All languages**, or another language, in the dialog to see the others. An API without code of its own opens it with every class.

## Interfaces

A utility class can export interfaces and types, for every piece of code to share (a class, a record, a struct in the other languages) :

**TypeScript**

**The utility class Inf**

```typescript
class Inf {
}
let temp = new Inf();
export = temp;
export interface IUserP {
    firstName: string;
    lastName: string;
    phone: number;
}
```

**A custom API which uses it**

```typescript
import * as T from 'types';
import * as inf from 'utils/Inf';

async function main(g: T.IAMGlobal) {
    const data: inf.IUserP = { firstName: 'John', lastName: 'Doe', phone: 123456789 };
    return data;
}
module.exports = main;
```

**Python**

**The utility class Inf**

```python
from dataclasses import dataclass


@dataclass
class UserP:
    firstName: str
    lastName: str
    phone: int
```

**A custom API which uses it**

```python
from dataclasses import asdict

from Inf import UserP


async def main(g):
    data = UserP(firstName='John', lastName='Doe', phone=123456789)
    return asdict(data)
```

**PHP**

**The utility class Inf**

```php
<?php
final class UserP
{
    public function __construct(
        public string $firstName,
        public string $lastName,
        public int $phone,
    ) {
    }
}
```

**A custom API which uses it**

```php
<?php
function main(AmG $g)
{
    return new UserP(firstName: 'John', lastName: 'Doe', phone: 123456789);
}
```

**C#**

**The utility class Inf**

```csharp
public record UserP(string firstName, string lastName, long phone);
```

**A custom API which uses it**

```csharp
file static class Api
{
    public static async Task<object?> Main(G g)
    {
        return new UserP("John", "Doe", 123456789);
    }
}
```

**Go**

**The utility class Inf, in the folder utils**

```go
package inf

type UserP struct {
	FirstName string `json:"firstName"`
	LastName  string `json:"lastName"`
	Phone     int    `json:"phone"`
}
```

**A custom API which uses it**

```go
package code

import (
	"apimaker/am"
	inf "apimaker/src/utility_classes/utils---Inf"
)

func Main(g *am.G) (any, error) {
	return inf.UserP{FirstName: "John", LastName: "Doe", Phone: 123456789}, nil
}
```

**Rust**

**The utility class Inf**

```rust
#[derive(serde::Serialize)]
#[serde(rename_all = "camelCase")]
pub struct UserP {
    pub first_name: String,
    pub last_name: String,
    pub phone: u64,
}
```

**A custom API which uses it**

```rust
use am::{Errors, G, Value};

use crate::Inf::UserP;

pub fn main(g: &mut G) -> Result<Value, Errors> {
    let data = UserP { first_name: "John".to_owned(), last_name: "Doe".to_owned(), phone: 123456789 };
    Ok(serde_json::to_value(data)?)
}
```

**Java**

**The utility class Inf**

```java
public class Inf {
    public record UserP(String firstName, String lastName, long phone) {
    }
}
```

**A custom API which uses it**

```java
import am.G;

class Api {
    static Object main(G g) {
        return new Inf.UserP("John", "Doe", 123456789);
    }
}
```

**Kotlin**

**The utility class Inf**

```kotlin
data class UserP(val firstName: String, val lastName: String, val phone: Long)
```

**A custom API which uses it**

```kotlin
import am.G

fun main(g: G): Any? {
    return UserP("John", "Doe", 123456789)
}
```

## In every language

Pick the language of the class in the title bar of its editor. A new class starts as a small example of the language, with a comment which says how the other code names it. Each language does it its own way, the same in a sandbox and in the Git repository :

| Language | The class `Tax` in the folder `utils/` | In the code |
|---|---|---|
| TypeScript | the module `utils/Tax` | `import * as Tax from 'utils/Tax'`, `Tax.add(100)` |
| Python | the module `Tax` | `from Tax import add` |
| PHP | what its file declares (no `namespace` of its own) | `Tax::add(100)`, `add_tax(100)`, `TAX_RATE` |
| C# | what its file declares, compiled with the code | `Tax.Add(100)` |
| Go | a package, imported by its folder | `import tax "apimaker/src/utility_classes/utils---Tax"` |
| Rust | the module `Tax` of the crate of the code | `use crate::Tax::add;` |
| Java | the class `Tax`, compiled with the other classes of Java | `Tax.add(100)` |
| Kotlin | what its file declares (it starts as an `object Tax`), compiled with the other classes of Kotlin | `Tax.add(100.0)` |

**TypeScript**

**The utility class Tax**

```typescript
export const RATE = 0.2;

export function add(amount: number): number {
    return Math.round(amount * (1 + RATE) * 100) / 100;
}
```

**A custom API**

```typescript
import * as T from 'types';
import * as Tax from 'utils/Tax';

async function main(g: T.IAMGlobal) {
    return { total: Tax.add(g.req.body.amount) };
}
module.exports = main;
```

**Python**

**The utility class Tax**

```python
RATE = 0.2


def add(amount):
    return round(amount * (1 + RATE), 2)
```

**A custom API**

```python
from Tax import add


async def main(g):
    return {"total": add(g.req.body.amount)}
```

**PHP**

**The utility class Tax**

```php
<?php
const TAX_RATE = 0.2;

class Tax
{
    public static function add($amount)
    {
        return round($amount * (1 + TAX_RATE), 2);
    }
}
```

**A custom API**

```php
<?php
function main($g)
{
    return ['total' => Tax::add($g->req->body->amount)];
}
```

**C#**

**The utility class Tax**

```csharp
public static class Tax
{
    public const double Rate = 0.2;

    public static double Add(double amount) => Math.Round(amount * (1 + Rate), 2);
}
```

**A custom API**

```csharp
file static class Api
{
    public static async Task<object?> Main(G g)
    {
        return new { total = Tax.Add(g.Req.Body.GetDouble("amount")) };
    }
}
```

**Go**

**The utility class Tax, in the folder utils**

```go
package tax

import "math"

var Rate = 0.2

func Add(amount float64) float64 {
	return math.Round(amount*(1+Rate)*100) / 100
}
```

**A custom API**

```go
package code

import (
	"apimaker/am"
	tax "apimaker/src/utility_classes/utils---Tax"
)

func Main(g *am.G) (any, error) {
	return am.M{"total": tax.Add(g.Req.Body().Float("amount"))}, nil
}
```

**Rust**

**The utility class Tax**

```rust
pub const RATE: f64 = 0.2;

pub fn add(amount: f64) -> f64 {
    (amount * (1.0 + RATE) * 100.0).round() / 100.0
}
```

**A custom API**

```rust
use am::{Errors, G, Value, json};

use crate::Tax;

pub fn main(g: &mut G) -> Result<Value, Errors> {
    Ok(json!({ "total": Tax::add(g.req.body()["amount"].as_f64().unwrap_or(0.0)) }))
}
```

**Java**

**The utility class Tax**

```java
public class Tax {
    public static final double RATE = 0.2;

    public static double add(double amount) {
        return Math.round(amount * (1 + RATE) * 100) / 100.0;
    }
}
```

**A custom API**

```java
import am.G;
import java.util.Map;

class Api {
    static Object main(G g) {
        return Map.of("total", Tax.add(g.req.getBody().getDouble("amount")));
    }
}
```

**Kotlin**

**The utility class Tax**

```kotlin
object Tax {
    const val RATE = 0.2

    fun add(amount: Double): Double = Math.round(amount * (1 + RATE) * 100) / 100.0
}
```

**A custom API**

```kotlin
import am.G

fun main(g: G): Any? = mapOf("total" to Tax.add(g.req.body.getDouble("amount")))
```

- A class is used by the code of its own language; code of another language reaches what it does through a custom API.
- A class which is saved is what the next request runs with : nothing restarts.
- The rules of names, what a class keeps between requests, and how the repository resolves the same imports are on [Languages and runtimes](https://docs.apimaker.dev/v4/docs/languages/index.html#utility-classes).
- Declarations for the editors (`utils/` and Ctrl+Space) and interfaces are for the classes written in TypeScript. The coverage of test runs counts the lines of the classes of every language.

## Versions

A utility class has versions and one active version. The code which imports it always gets the active one, at once, without a restart. Keep the old version until the new one has proven itself, and switch back in one click.

## Testing

A [test case](https://docs.apimaker.dev/v4/docs/test-cases/test-cases.html#testing-a-utility-class) imports the class the way custom APIs do and calls its methods, with mocks for the `g.sys` calls it makes and coverage of its lines.

## Good to know

- Utility classes are files in Git under `src/utility_classes/` and deploy with a pull.
- A utility class runs where its importer runs : in the sandbox, or on the native process for a native custom API.
- A new account comes with a sample utility class to read.