> For the complete documentation index, see [llms.txt](https://osl.mistium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://osl.mistium.com/standard-library/packages.md).

# Package index

OSL ships its standard library as importable packages:

```osl
import "std:fs"

log fs.readFile("notes.txt")
```

An import adds a package value with the same name. For example, `std:fs` adds `fs`. Use the `std:` prefix in new code. The older `osl/` spelling still works, but the compiler reports a migration warning.

## How imports work

| Form                                   | Meaning                                             |
| -------------------------------------- | --------------------------------------------------- |
| `import "std:fs"`                      | A standard-library package listed below             |
| `import "./helpers.osl"`               | A local OSL file, relative to the importing file    |
| `import "utils"` or `import "./utils"` | Every `.osl` file directly inside a local directory |
| `import "git.rotur.dev/me/tools"`      | A Git dependency installed by Opal                  |
| `import "go:net/http"`                 | A Go package                                        |

Directory imports sort files by name and do not recurse. Import or re-export child directories yourself.

Missing third-party Go dependencies are fetched automatically when you compile.

## Module objects

The statement form merges another file's declarations into the current scope. Its top-level statements run once, where OSL first imports the file. The expression form returns its public API as an object instead:

```osl
object math = import("./math.osl")

log math.add(2, 3)
log math.square(4)
```

Without an export statement, a file exposes all of its declarations. Adding an export statement turns on an explicit public API for that file:

```osl
export {add, subtract as difference}
export {Vector} from "./geometry/vector.osl"
export * as geometry from "./geometry"
```

Consumers can import the full API, selected names, or a namespace:

```osl
import * from "./math.osl"
import {add, subtract as difference} from "./math.osl"
import * as math from "./math.osl"
```

Files in the same directory can share private declarations. Consumers in another directory see only exported declarations. Missing, duplicate, and conflicting exports are compile errors.

```osl
// math.osl
def _double(number n) number (
  return n * 2
)

def square(number n) number (
  return n * n
)

def quadruple(number n) number (
  return _double(_double(n))
)
```

Here `math.square` and `math.quadruple` are callable from outside. `import(...)` works with local `.osl` files whose path is a string literal.

## Returned objects

Some packages give you an **object** to keep working with. For example, `db.open()` returns a database handle, and you call further methods on *that*:

```osl
import "std:db"

*db.DB handle = db.open("app.db")
handle.exec("CREATE TABLE users (id INTEGER, name TEXT)")
array rows = handle.query("SELECT * FROM users")
```

Each package page lists handle methods in a separate section.

## The standard library at a glance

### Web & networking

| Package                                             | Description                                                  |
| --------------------------------------------------- | ------------------------------------------------------------ |
| [serve](/standard-library/web/serve.md)             | HTTP server / web framework (routing, middleware, contexts). |
| [ws](/standard-library/web/ws.md)                   | WebSocket client and server.                                 |
| [originchats](/standard-library/web/originchats.md) | Bot framework for OriginChats servers.                       |
| [requests](/standard-library/web/requests.md)       | HTTP client methods including `get`, `post`, and `put`.      |
| [net](/standard-library/web/net.md)                 | Low-level TCP/UDP sockets and DNS lookups.                   |
| [url](/standard-library/web/url.md)                 | URL parsing, building and query-string handling.             |
| [ftp](/standard-library/web/ftp.md)                 | FTP file transfers.                                          |
| [ssh](/standard-library/web/ssh.md)                 | SSH connections, remote commands and SCP.                    |
| [s3](/standard-library/web/s3.md)                   | S3-compatible object storage client.                         |
| [webpush](/standard-library/web/webpush.md)         | Web Push notifications (VAPID).                              |

### Data & serialization

| Package                                        | Description                                        |
| ---------------------------------------------- | -------------------------------------------------- |
| [json](/standard-library/data/json.md)         | JSON parsing and encoding.                         |
| [yaml](/standard-library/data/yaml.md)         | YAML parsing and encoding.                         |
| [schema](/standard-library/data/schema.md)     | Composable validation and normalization schemas.   |
| [csv](/standard-library/data/csv.md)           | CSV parsing plus a small dataframe-style toolkit.  |
| [xml](/standard-library/data/xml.md)           | XML parsing and querying.                          |
| [template](/standard-library/data/template.md) | Lightweight `{{ }}` templating with HTML escaping. |
| [md](/standard-library/data/md.md)             | Markdown to HTML (CommonMark + GFM via goldmark).  |
| [mime](/standard-library/data/mime.md)         | MIME-type lookup and parsing.                      |
| [diff](/standard-library/data/diff.md)         | Text/line/word diffing.                            |

### Databases & storage

| Package                                     | Description                                           |
| ------------------------------------------- | ----------------------------------------------------- |
| [db](/standard-library/storage/db.md)       | Embedded SQLite - SQL plus a document/collection API. |
| [save](/standard-library/storage/save.md)   | Simple persistent key-value storage.                  |
| [cache](/standard-library/storage/cache.md) | In-memory LRU cache with TTLs.                        |
| [env](/standard-library/storage/env.md)     | Environment variables and `.env` files.               |

### Filesystem & system

| Package                                        | Description                                                          |
| ---------------------------------------------- | -------------------------------------------------------------------- |
| [fs](/standard-library/system/fs.md)           | Files, directories and path utilities.                               |
| [mem](/standard-library/system/mem.md)         | Runtime memory counters, heap snapshots, and live pprof diagnostics. |
| [sys](/standard-library/system/sys.md)         | System info, environment, and running shell commands.                |
| [process](/standard-library/system/process.md) | Spawn, manage and signal processes.                                  |
| [zip](/standard-library/system/zip.md)         | ZIP / TAR / GZIP compression.                                        |

### Crypto & security

| Package                                      | Description                                                    |
| -------------------------------------------- | -------------------------------------------------------------- |
| [crypto](/standard-library/crypto/crypto.md) | Hashing, HMAC, AES, password hashing, file encryption, random. |
| [jwt](/standard-library/crypto/jwt.md)       | JSON Web Token signing and verification.                       |

### Text, math & time

| Package                                        | Description                                                      |
| ---------------------------------------------- | ---------------------------------------------------------------- |
| [emoji](/standard-library/mathtime/emoji.md)   | Emoji detection, extraction, replacement, flags, and skin tones. |
| [regex](/standard-library/mathtime/regex.md)   | Regular expressions plus validators and text helpers.            |
| [semver](/standard-library/mathtime/semver.md) | Semantic-version parsing and comparison.                         |
| [math](/standard-library/mathtime/math.md)     | Maths, statistics and number theory.                             |
| [random](/standard-library/mathtime/random.md) | Seedable pseudo-random numbers.                                  |
| [date](/standard-library/mathtime/date.md)     | Dates, durations and time zones.                                 |
| [cron](/standard-library/mathtime/cron.md)     | Cron-style job scheduling.                                       |
| [retry](/standard-library/utilities/retry.md)  | Bounded retries with exponential backoff and jitter.             |

### Terminal & logging

| Package                                        | Description                                                  |
| ---------------------------------------------- | ------------------------------------------------------------ |
| [tui](/standard-library/terminal/tui.md)       | Terminal UI: colours, boxes, tables, prompts, menus, charts. |
| [log](/standard-library/terminal/log.md)       | Levelled, colourful logging.                                 |
| [notify](/standard-library/terminal/notify.md) | Desktop notifications.                                       |

### Media & documents

| Package                                     | Description                                             |
| ------------------------------------------- | ------------------------------------------------------- |
| [img](/standard-library/media/img.md)       | Load, transform and save images.                        |
| [qr](/standard-library/media/qr.md)         | QR codes and barcodes.                                  |
| [pdf](/standard-library/media/pdf.md)       | Generate PDF documents.                                 |
| [canvas](/standard-library/media/canvas.md) | In-memory pixel canvas.                                 |
| [colors](/standard-library/media/colors.md) | Build colour values (used by image-producing packages). |
| [sound](/standard-library/media/sound.md)   | Audio playback.                                         |

### Graphics & windowing

| Package                                                                | Description                                                                    |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| [shader](/standard-library/graphics-and-windowing/shader.md)           | GLSL and OSL-style shader transpilation and rendering to images and windows.   |
| [raylib](/standard-library/graphics-and-windowing/raylib.md)           | Native windowing, input, 2D drawing, collision helpers, shaders, and textures. |
| [window](/standard-library/graphics-and-windowing/window.md)           | Open a window and draw to it (the originOS graphics model).                    |
| [win-buttons](/standard-library/graphics-and-windowing/win-buttons.md) | Install native window controls.                                                |

### Scripting & concurrency

| Package                                             | Description                                                         |
| --------------------------------------------------- | ------------------------------------------------------------------- |
| [testing](/standard-library/concurrency/testing.md) | Assertions and the `osl test` workflow.                             |
| [js](/standard-library/concurrency/js.md)           | Run sandboxed JavaScript with hard resource limits.                 |
| [lua](/standard-library/concurrency/lua.md)         | Embed and run Lua scripts.                                          |
| [thread](/standard-library/concurrency/thread.md)   | Background threads, parallel workers, racing, and message channels. |
| [sync](/standard-library/concurrency/sync.md)       | Named locks, scoped locking, one-time execution, and wait groups.   |

### Utilities & data structures

| Package                                         | Description                                               |
| ----------------------------------------------- | --------------------------------------------------------- |
| [box2d](/standard-library/utilities/box2d.md)   | Box2D-compatible rigid-body worlds, bodies, and fixtures. |
| [map](/standard-library/utilities/map.md)       | An ordered key-value map type.                            |
| [set](/standard-library/utilities/set.md)       | A set type.                                               |
| [option](/standard-library/utilities/option.md) | Optional values (`some`/`none`).                          |
| [result](/standard-library/utilities/result.md) | Success/error result values.                              |
| [ptr](/standard-library/utilities/ptr.md)       | Low-level pointer operations.                             |

### More

| Package                                      | Description                        |
| -------------------------------------------- | ---------------------------------- |
| [email](/standard-library/more/email.md)     | Compose and send email (SMTP).     |
| [torrent](/standard-library/more/torrent.md) | Create and parse `.torrent` files. |

To read a package's source directly from the CLI:

```bash
osl package fs       # print the fs package source
osl package          # list every available package
```