OS environment utilities: platform detection, safe path operations, and OS-standard directory resolution (XDG/macOS/Windows) with temp_dir support

env

dirs

xdg

platform

path

config

cache

temp

moon add trkbt10/osenv@0.1.0

Download zip

Author

trkbt10

Version

0.1.0

License

Apache-2.0

Repository

github.com/trkbt10/osenv.mbt

Last updated

4 months ago

Downloads

524

Dependencies

moonbitlang/x0.4.41

README

#trkbt10/osenv

OS environment utilities for MoonBit: platform detection, safe path operations, and OS-standard directory resolution.

Cross-platform: Linux, macOS, Windows (native + JS targets)
Security-first: null byte rejection, path traversal prevention, app name validation
node:path aligned: basename, dirname, extname, join, normalize and more
XDG compliant: respects XDG Base Directory on Linux, Library paths on macOS, APPDATA on Windows

#Overview

osenv is organized into four sub-packages, each with a single responsibility:

platform/   OS detection         (no dependencies)
    |
  path/     Path operations      (depends on platform)
    |
validate/   Security validation  (depends on path)
    |
  dirs/     Directory resolution (depends on platform, path, validate)

#Design Principles

Runtime separator: all output uses the runtime OS separator. Both / and \ are recognized as input separators for security.
Error on invalid input: join() and *_dir_for() raise PathError on null bytes, absolute path injection, or invalid app names.
Pure string operations: no symlink resolution, no filesystem access. Safe to use in any target (wasm included for path operations).

#Getting Started

Add the dependency:

moon add trkbt10/osenv

Import the packages you need in your moon.pkg:

import {
  "trkbt10/osenv/dirs" @dirs,
  "trkbt10/osenv/path" @path,
  "trkbt10/osenv/platform" @platform,
}

Basic example:

fn main {
  let p = @platform.platform() // MacOS, Linux, Windows, or Unknown
  println("Running on: \{p}")

  let config = @dirs.config_dir_for("myapp") // raises PathError on bad input
  match config {
    Some(dir) => println("Config: \{dir}")
    None => println("Config dir not available")
  }

  let tmp = @dirs.temp_dir() // always returns a value
  println("Temp: \{tmp}")
}

Run with native target for full platform detection:

moon run --target native cmd/main

#API Reference

#trkbt10/osenv/platform

Function	Signature	Description
platform()	() -> Platform	Returns current OS: Linux, MacOS, Windows, or Unknown
is_windows()	() -> Bool	Shorthand for Windows check

Platform supports Eq and Show.

#trkbt10/osenv/path

Path operations modeled after node:path. Both / and \ are recognized as separators on all platforms. Output always uses the runtime separator.

Function	Signature	Description
sep()	() -> String	Runtime path separator (/ or \\)
join(segments)	(Array[String]) -> String raise PathError	Join segments; rejects null bytes and absolute path hijacking
normalize(path)	(String) -> String	Collapse . and .., deduplicate separators
basename(path)	(String) -> String	Last path component
dirname(path)	(String) -> String	Parent directory
extname(path)	(String) -> String	File extension including dot
is_absolute(path)	(String) -> Bool	/ or C:\ style
is_relative(path)	(String) -> Bool	Inverse of is_absolute
to_relative(path, base)	(String, String) -> String	Strip base prefix (normalizes both first)
to_absolute(path, base)	(String, String) -> String	Prepend base to relative path
strip_trailing_sep(s)	(String) -> String	Remove trailing / or \
contains_null_byte(s)	(String) -> Bool	Detect null bytes

#trkbt10/osenv/validate

Security validation utilities.

Function	Signature	Description
validate_app_name(name)	(String) -> String raise PathError	Rejects empty, null bytes, /, \, ., .., control chars
is_within(child, base)	(String, String) -> Bool	Check path containment after normalization

#trkbt10/osenv/dirs

OS-standard directory resolution. Returns String? (None when HOME is unavailable).

Function	Returns	Linux	macOS	Windows
home_dir()	String?	$HOME	$HOME	%USERPROFILE%
config_dir()	String?	$XDG_CONFIG_HOME or ~/.config	~/Library/Application Support	%APPDATA%
data_dir()	String?	$XDG_DATA_HOME or ~/.local/share	~/Library/Application Support	%LOCALAPPDATA%
cache_dir()	String?	$XDG_CACHE_HOME or ~/.cache	~/Library/Caches	%LOCALAPPDATA%
temp_dir()	String	$TMPDIR or /tmp	$TMPDIR or /tmp	%TEMP% or %TMP%
runtime_dir()	String?	$XDG_RUNTIME_DIR	None	None
state_dir()	String?	$XDG_STATE_HOME or ~/.local/state	None	None

App-scoped variants (config_dir_for, data_dir_for, cache_dir_for, temp_dir_for, state_dir_for) append the app name after validation. They raise PathError on invalid app names.