fsharp.fio - npm Package Compare versions

Comparing version 0.0.38-alpha to 0.0.39-alpha

FSharp.FIO.nuspec

@@ -5,3 +5,3 @@ <?xml version="1.0" encoding="utf-8"?>
     <id>FSharp.FIO</id>
-    <version>0.0.38-alpha</version>
+    <version>0.0.39-alpha</version>
     <title>FSharp.FIO</title>
@@ -18,6 +18,6 @@ <authors>Daniel Larsen</authors>
     <tags>fsharp effects async concurrent functional zio fibers</tags>
-    <repository type="git" url="https://github.com/fs-fio/FIO" commit="1134afc225bf7ca3a29b5017bc667731a95a10fd" />
+    <repository type="git" url="https://github.com/fs-fio/FIO" commit="4fcc3e947086bb6d3abb6521032889f405812814" />
     <dependencies>
       <group targetFramework="net10.0">
-        <dependency id="FSharp.Core" version="10.0.101" exclude="Build,Analyzers" />
+        <dependency id="FSharp.Core" version="10.0.102" exclude="Build,Analyzers" />
       </group>
@@ -24,0 +24,0 @@ </dependencies>

README.md

@@ -59,2 +59,11 @@ <a id="readme-top"></a>
     <li>
+      <a href="#library-modules">Library Modules</a>
+      <ul>
+        <li><a href="#console">Console</a></li>
+        <li><a href="#clock">Clock</a></li>
+        <li><a href="#environment">Environment</a></li>
+        <li><a href="#random">Random</a></li>
+      </ul>
+    </li>
+    <li>
       <a href="#extension-packages">Extension Packages</a>
@@ -138,3 +147,3 @@ <ul>
 - **App framework** - FIOApp base classes for simplified application entry points
-- **Console I/O** - Functional console operations
+- **Library modules** - Console, Clock, Environment, and Random operations
 
@@ -477,2 +486,36 @@ #### Optional Extension Packages
 
+##### FIOApp Customization
+
+FIOApp supports extensive customization through overridable properties:
+
+```fsharp
+type MyApp() =
+    inherit SimpleFIOApp()
+
+    // Application metadata
+    override _.name = "My Application"
+    override _.version = "1.0.0"
+    override _.description = "A sample FIO application"
+
+    // Show startup banner
+    override _.showBanner = true
+
+    // Cleanup on shutdown (Ctrl+C or completion)
+    override _.shutdownHook() = fio {
+        do! Console.PrintLine "Cleaning up resources..."
+    }
+
+    // Custom runtime configuration
+    override _.runtime =
+        new ConcurrentRuntime { EWC = 8; EWS = 500; BWC = 2 }
+
+    override _.effect = fio { ... }
+```
+
+**Available customizations:**
+- **Metadata**: `name`, `version`, `description`, `showBanner`, `banner`
+- **Lifecycle**: `shutdownHook()`, `shutdownHookTimeout`, `onStart()`, `onSuccess()`, `onError()`
+- **Runtime**: `runtime`, `configureThreadPool()`
+- **Exit codes**: `exitCodeSuccess`, `exitCodeError`, `exitCodeFatalError`
+
 For more examples, see [**FSharp.FIO.Examples.App**](https://github.com/fs-fio/FIO/tree/main/examples/FSharp.FIO.Examples.App).
@@ -503,2 +546,123 @@
 
+## Library Modules
+
+The core package includes four library modules for common effectful operations. All modules use qualified access (e.g., `Console.PrintLine`).
+
+### Console
+
+Provides functional console I/O operations including input/output, colors, cursor control, and more.
+
+```fsharp
+open FSharp.FIO.Console
+
+let effect = fio {
+    do! Console.PrintLine "Enter your name:"
+    let! name = Console.ReadLine
+    do! Console.PrintLine $"Hello, {name}!"
+
+    // Read password with masked input
+    do! Console.Print "Password: "
+    let! password = Console.ReadPassword
+
+    // Colored output (automatically restores original color)
+    do! Console.WithForegroundColor(ConsoleColor.Green,
+        Console.PrintLine "Success!")
+}
+```
+
+**Key functions:**
+- I/O: `Print`, `PrintLine`, `ReadLine`, `ReadKey`, `ReadPassword`
+- Stderr: `PrintError`, `PrintErrorLine`, `WriteError`, `WriteErrorLine`
+- Colors: `SetForegroundColor`, `SetBackgroundColor`, `WithForegroundColor`, `WithColors`
+- Cursor: `SetCursorPosition`, `GetCursorPosition`, `Clear`
+- Properties: `GetTitle`, `SetTitle`, `GetWindowWidth`, `GetWindowHeight`
+
+### Clock
+
+Provides time and date operations including timestamps and performance measurement.
+
+```fsharp
+open FSharp.FIO.Clock
+
+let effect = fio {
+    let! now = Clock.Now()
+    let! utcNow = Clock.UtcNow()
+
+    // Unix timestamps
+    let! timestamp = Clock.Timestamp()        // seconds
+    let! timestampMs = Clock.TimestampMillis() // milliseconds
+
+    // Measure execution time
+    let! (result, elapsed) = Clock.Timed(someExpensiveOperation)
+    do! Console.PrintLine $"Completed in {elapsed.TotalMilliseconds}ms"
+}
+```
+
+**Key functions:**
+- Time queries: `Now()`, `UtcNow()`, `Today()`, `NowOffset()`, `UtcNowOffset()`
+- Timestamps: `Timestamp()`, `TimestampMillis()`, `ToTimestamp`, `FromTimestamp`
+- Measurement: `Timed(effect)`, `GetTimestamp()`, `GetElapsedTime(start, end)`
+
+### Environment
+
+Provides environment variable access and system information.
+
+```fsharp
+open FSharp.FIO.Environment
+
+let effect = fio {
+    // Environment variables with defaults
+    let! port = Environment.GetOrDefault("PORT", "8080")
+    let! debug = Environment.GetBoolOrDefault("DEBUG", false)
+    let! timeout = Environment.GetIntOrDefault("TIMEOUT", 30)
+
+    // System information
+    let! user = Environment.UserName()
+    let! machine = Environment.MachineName()
+    let! cwd = Environment.CurrentDirectory()
+
+    // Check if variable is set
+    let! hasToken = Environment.IsSet "API_TOKEN"
+}
+```
+
+**Key functions:**
+- Env vars: `GetOption`, `Get`, `GetOrDefault`, `GetAll`, `IsSet`
+- Typed access: `GetInt`, `GetIntOrDefault`, `GetBool`, `GetBoolOrDefault`
+- System info: `MachineName()`, `UserName()`, `CurrentDirectory()`, `GetTempPath()`
+- Constants: `ProcessorCount`, `Is64BitProcess`, `Is64BitOperatingSystem`, `NewLine`
+
+### Random
+
+Provides random number generation with thread-safe operations.
+
+```fsharp
+open FSharp.FIO.Random
+
+let effect = fio {
+    // Integers
+    let! roll = Random.NextIntRange(1, 7)  // Dice roll [1, 6]
+    let! bigRoll = Random.NextInt64Range(1L, 1000000L)
+
+    // Floating point
+    let! probability = Random.NextDouble()  // [0.0, 1.0)
+    let! temperature = Random.NextDoubleRange(-10.0, 40.0)
+
+    // Utilities
+    let! coinFlip = Random.NextBool()
+    let! guid = Random.NextGuid()
+    let! bytes = Random.NextBytes(32)
+
+    // Collections
+    let! shuffled = Random.Shuffle [1; 2; 3; 4; 5]
+    let! picked = Random.Choice ["red"; "green"; "blue"]
+}
+```
+
+**Key functions:**
+- Integers: `NextInt()`, `NextIntBounded(max)`, `NextIntRange(min, max)`, `NextInt64...`
+- Floats: `NextDouble()`, `NextDoubleBounded(max)`, `NextDoubleRange(min, max)`
+- Utilities: `NextBool()`, `NextGuid()`, `NextBytes(count)`
+- Collections: `Shuffle(list)`, `Choice(list)`, `ChoiceOrFail(list, onEmpty)`
+
 ## Extension Packages
@@ -755,3 +919,3 @@
 [nuget-shield]: https://img.shields.io/nuget/v/FSharp.FIO.svg?style=for-the-badge
-[nuget-url]: https://www.nuget.org/packages/FSharp.FIO/0.0.38-alpha
+[nuget-url]: https://www.nuget.org/packages/FSharp.FIO/0.0.39-alpha
 [FSharp]: https://img.shields.io/badge/F%23-378BBA?style=for-the-badge&logo=.NET&logoColor=white
@@ -758,0 +922,0 @@ [FSharp-url]: https://fsharp.org/

No alert changes

No metric changes