> For the complete documentation index, see [llms.txt](https://docs.sacruda.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sacruda.nl/developers/sacruda-apis/built-in-utilities.md).

# Built-in utilities

Sacruda comes with several utility functions built-in that may come in handy for you when you're developing your app. These functions range from array chunking to path manipulation and concatenation.&#x20;

### Global utilities

```typescript
const Sleep: (ms?: number) => Promise<unknown>;
```

{% hint style="info" %}
This function is asynchronous; it should be awaited.
{% endhint %}

Waits for `ms` milliseconds. That's it.

***

```typescript
export const Debug: (m: any) => void;
```

Creates a message box with `m` as the message.

### The `util` object

All of these functions are properties of the `util` global object.

```typescript
util.htmlspecialchars(text: string): string;
```

Makes the input HTML-safe to prevent XSS attacks.

***

```typescript
util.Plural: (s: string, x: number) => string;
```

Appends an `s` to the input if the `x` argument is 0 or above 1.

***

```typescript
util.sliceIntoChunks(arr: any[], chunkSize: number): any[][];
```

Converts an array of items into equally sized chunks.

***

```typescript
util.decimalToHex: (value: number, maxLength?: number) => string;
```

Returns a hex string representation of the input, optionally specifying a length to make the resulting string. The output will be padded with zeroes as per the `maxLength` parameter.

***

```typescript
util.sha256(message: string): Promise<string>;
```

{% hint style="info" %}
This function is asynchronous; it should be awaited.
{% endhint %}

Generates an SHA256 hash for the input.

***

```typescript
util.CountInstances(input: string, search: string): number;
```

Counts how many times `search` is found in `input`.

***

```typescript
util.join(...args: string[]): string;
```

A web-based `path.join` implementation for joining path parts together, with support for the Sacruda Filesystem kernel module.

***

```typescript
util.getItemNameFromPath(path: string): string;
```

Returns the file or folder name from a path. For example: `U:/Documents/test.txt` becomes `test.txt`.

***

```typescript
util.getParentDirectory(p: string): string;
```

Parses the parent directory of a path. For example: `U:/Applications/Minesweeper` becomes `U:/Applications`.

***

```typescript
util.getDriveLetter(path: string, allowUuid?: boolean): string | undefined;
```

Returns the drive letter of a path. It will only allow drive UUIDs if specified. Returns `undefined` if the drive letter cannot be parsed.

***

```typescript
util.formatBytes(bytes: number): string;
```

Converts the input bytes to a human-readable format. Supports up to the YB size unit (excessive, I know)

***

```typescript
util.DownloadFile(file: ArrayBuffer, filename: string, mimetype?: string): void;
```

Takes an ArrayBuffer, filename and optional mimetype, and queries the browser to download that file to the user's computer.

***

{% hint style="warning" %}
The following functions are of dubious reliability and should not be used regularly.
{% endhint %}

```typescript
util.onFileChange(path: string, callback: () => void): void;
```

Watches the SystemDispatch kernel module for file changes broadcasted by the Filesystem kernel module.

***

```typescript
util.onFolderChange(path: string, callback: () => void): void;
```

Watches the SystemDispatch kernel module for folder changes broadcasted by the Filesystem kernel module.
