> 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/packages/packages.md).

# Overview

OSL keeps the core language small and ships capabilities as a **standard library of packages**. You pull in what you need with `import`:

```javascript
import "osl/fs"

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

Each package exposes a single global value named after the package (`fs`, `crypto`, `serve`, …) whose methods you call. The `osl/` prefix is optional for standard-library packages - `import "fs"` and `import "osl/fs"` are equivalent.

## How imports work

| Form                                  | Meaning                                                                                    |
| ------------------------------------- | ------------------------------------------------------------------------------------------ |
| `import "osl/fs"` / `import "fs"`     | A standard-library package (listed below).                                                 |
| `import "./helpers.osl"`              | Another OSL file in your project (path relative to the current file).                      |
| `import "utils"` / `import "./utils"` | A **directory** — imports every `.osl` file inside it (path relative to the current file). |
| `import "go/net/http"`                | A raw Go package, for advanced interop.                                                    |

Directory imports pull in all the `.osl` files in the named folder, so you can split a module across several files and import the folder once. The `osl/` prefix is reserved for standard-library packages: to import a local directory literally named `osl`, write `import "./osl"` — a bare `import "osl"` always looks for a standard-library package.

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

## Modules — `import(...)` as a value

The statement `import "./x.osl"` merges another file's functions into the current scope. The **expression** form `import("./x.osl")` instead returns that file as a **module object** whose fields are its public functions:

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

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

Top-level names that start with `_` are **private**: they are not exposed on the module object, but the module's own functions can still call them.

```javascript
// 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, but `math._double` is not — it exists only for the module's internal use. `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*:

```javascript
import "osl/db"

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

On each package page these are listed under **"Returned object"** headings.

## The standard library at a glance

### Web & networking

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

### Data & serialization

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

### Databases & storage

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

### Filesystem & system

| Package                                | Description                                           |
| -------------------------------------- | ----------------------------------------------------- |
| [fs](/packages/system/fs.md)           | Files, directories and path utilities.                |
| [sys](/packages/system/sys.md)         | System info, environment, and running shell commands. |
| [process](/packages/system/process.md) | Spawn, manage and signal processes.                   |
| [zip](/packages/system/zip.md)         | ZIP / TAR / GZIP compression.                         |

### Crypto & security

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

### Text, math & time

| Package                                | Description                                           |
| -------------------------------------- | ----------------------------------------------------- |
| [regex](/packages/mathtime/regex.md)   | Regular expressions plus validators and text helpers. |
| [semver](/packages/mathtime/semver.md) | Semantic-version parsing and comparison.              |
| [math](/packages/mathtime/math.md)     | Maths, statistics and number theory.                  |
| [random](/packages/mathtime/random.md) | Seedable pseudo-random numbers.                       |
| [date](/packages/mathtime/date.md)     | Dates, durations and time zones.                      |
| [cron](/packages/mathtime/cron.md)     | Cron-style job scheduling.                            |

### Terminal & logging

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

### Media & documents

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

### Graphics & windowing

| Package                                  | Description                                                 |
| ---------------------------------------- | ----------------------------------------------------------- |
| [window](/graphics-osl-window/window.md) | Open a window and draw to it (the originOS graphics model). |

### Scripting & concurrency

| Package                                   | Description                      |
| ----------------------------------------- | -------------------------------- |
| [lua](/packages/concurrency/lua.md)       | Embed and run Lua scripts.       |
| [thread](/packages/concurrency/thread.md) | Background threads.              |
| [sync](/packages/concurrency/sync.md)     | Named locks for synchronisation. |

### Utilities & data structures

| Package                                 | Description                      |
| --------------------------------------- | -------------------------------- |
| [map](/packages/utilities/map.md)       | An ordered key-value map type.   |
| [set](/packages/utilities/set.md)       | A set type.                      |
| [option](/packages/utilities/option.md) | Optional values (`some`/`none`). |
| [result](/packages/utilities/result.md) | Success/error result values.     |
| [ptr](/packages/utilities/ptr.md)       | Low-level pointer operations.    |

### More

| Package                              | Description                        |
| ------------------------------------ | ---------------------------------- |
| [email](/packages/more/email.md)     | Compose and send email (SMTP).     |
| [torrent](/packages/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
```