KSLCore/ksl.app.settings/UserSettingsStore

UserSettingsStore

class UserSettingsStore(settingsDir: Path = defaultSettingsDir(), userHome: Path = Path(System.getProperty("user.home")), defaultWorkspaceProvider: (Path) -> Path = ::resolveDefaultWorkspace)(source)

Per-user persistence for ~/.ksl/settings.toml.

Loads eagerly at construction so the first observer of settings sees real state immediately. Mutation methods write the file synchronously; failures (read-only ~/.ksl/, locked file, etc.) are logged and absorbed — the in-memory flow always reflects the user's latest action even when persistence is unavailable.

Constructor injection of settingsDir lets tests redirect the settings location to a temporary directory. Production code uses the no-arg UserSettingsStore() which resolves to ~/.ksl/.

Thread-safety: the underlying MutableStateFlow is safe for concurrent updates from any thread; mutation methods are @Synchronized so the file write and the flow update happen atomically.

Parameters

settingsDir

directory containing settings.toml; defaults to ~/.ksl/.

userHome

the user's home directory, used to resolve the default workspace path and as the last-resort fallback for stale-path recovery. Defaults to the JVM's user.home system property.

defaultWorkspaceProvider

resolves the "out-of-the-box" workspace location when the user has not yet set one via setCurrentDirectory (and when a previously-saved path has gone stale). Defaults to resolveDefaultWorkspace, which prefers <userHome>/Documents/KSLWork and falls back to <userHome>/KSLWork on systems without a Documents folder. Tests can inject a temp-dir-based provider to stay isolated.

Constructors

UserSettingsStore

constructor(settingsDir: Path = defaultSettingsDir(), userHome: Path = Path(System.getProperty("user.home")), defaultWorkspaceProvider: (Path) -> Path = ::resolveDefaultWorkspace)

Types

Companion

object Companion

Properties

settings

val settings: StateFlow<UserSettings>

Observable settings state. Read-only; mutate via the public methods.

Functions

activeWorkspace

@Synchronized

fun activeWorkspace(): Path

Resolves the active workspace path. Returns the saved currentDirectory when it exists on disk; otherwise resolves the default workspace via defaultWorkspaceProvider and materializes the directory if it does not yet exist (so downstream consumers like file choosers always see a valid starting point). Stale saved paths are evicted on first read.

addRecentConfiguration

@Synchronized

fun addRecentConfiguration(path: Path)

Promote path to the front of the recent-configurations list (dedup, cap at RECENT_LIMIT). Mirrors addRecentDirectory but targets the configurations submenu rather than the workspace submenu. Called after a successful Save or Open of a TOML configuration file, so reopening a recent document is one click regardless of which workspace folder the user is currently in.

addRecentDirectory

@Synchronized

fun addRecentDirectory(path: Path)

Adds path to the recent-directories list without changing the current directory. Used when the user saves a file to a directory other than the workspace — scenario §2 step 4 specifies the saved file's parent directory becomes the new workspace, but consumers may also want to record a directory as recently used without promoting it.

setCurrentDirectory

@Synchronized

fun setCurrentDirectory(path: Path)

Sets the active workspace to path and bumps it to the front of the recent-directories list (dedup, cap at RECENT_LIMIT).