Forem: Angel Daniel Munoz Gonzalez

Exploring MonoGame with F#

Angel Daniel Munoz Gonzalez — Tue, 16 Dec 2025 14:00:00 +0000

Hey there!
It has been quite some time since the last blog entry.

Another December, another #FsAdvent entry in my F# decade long journey!
Thanks to Sergey Tihon for another consecutive year of organizing the very lovely F# Advent calendar

Rather than bore you with "How I burned out and recovered" stories, I thought it would be more interesting to share my recent journey into game development using F# and MonoGame.

Today I'll be talking about Kipo

AngelMunoz / Kipo

An RPG-like Game prototype written in F# and Monogame

Kipo

An ARPG engine prototype, built as a playground for exploring functional game development patterns in F# and MonoGame.

What is This?

Kipo is an isometric action-RPG engine written entirely in F#. It's a technical sandbox where serious engineering meets game development curiosity. If you've ever wondered what an RPG engine looks like built from the ground up with functional principles—here it is.

This isn't a finished game. It's a working prototype with real systems: combat, AI, skills, projectiles, visual effects, and more. The architecture is designed for performance and maintainability, but the scope is still evolving.

Technical Highlights

Data-Oriented Programming

State is strictly separated from logic. We prioritize using immutable data structures that flow through pure transformation functions, aiming for code that is easier to reason about, test, and parallelize.

Performance Engineering

The engine is built with a focus on minimizing GC pressure. We aim to keep critical paths…

View on GitHub

Kipo is the second prototype I've build with MonoGame and although Kps shares similarities, Kipo took off from where I became blocked with Kps.

In the ideal world these are some of the overall goals I had for this project:

F# : because I really love the language, and these days is hard for me to pick something else for my own projects.
MonoGame: Because for some reason it is basically the only option that doesn't fight me tooth and nail to use F#. Neither Unity nor Godot have F# support at all. Sure I could jump through hoops to use F# in these engines but I find that the friction is not worth it at least for me.
RPG in its core: If you ever played Trickster Online or even Ragnarok Online, you'll know the feeling I'm looking for. I wanted to apply some of these mechanics in a single-player RPG format.
Isometric View: It looks good, I didn't know what I was getting into.
Tiled2D Maps: I don't really have experience with games, but every time I've given it a micro shot, tiled2d has been there and I started to get somewhat familiar with it.
3D entities: The scenario and world can be 2D as I think for that kind of work it is easier to have images/sprites, but when it comes to characters, entities, objects and so on, I think 3D is interesting to explore, particularly inspired by Super Mario World Games where the platform looks 2D but the characters are 3D.
ECS-like architecture: Since I'm not an expert in game development, I wanted to explore some of the common patterns but after reading a little bit about ECS, I felt it brought a lot of things to the table that would make my life more complex than I needed it. Picking up some ideas from ECS and adapting core concepts from F# and adaptive data seemed like a good fit.
FSharp.Data.Adaptive: Adaptive data is one of my favorite approaches to state changes in applications, so I wanted to explore if I could skeak it into a game architecture.

With that in mind, I started this project roughly two months ago (counting KPS as well) and I wanted to share some of the journey, phases, and learnings I had along the way.

NOTE: I must say though that my previous experience writing video games has been close to zero, (a few demos of phaser.js, some monogame experiments no longer than 300 LOC, and at most one or two unity tutorials) so as I was implementing both Kipo and KPS I was learning quite a lot.

Foundations & Architecture (Early November)

The project began not with graphics, but with a focus on data + types architecture.
What I've leaned over the years with F# is that a solid set of models and types can simplify life a long way.

Re-architecture & Core Systems

While some of the architectural choices were born in Kps, some were entirely born in Kipo.
Most of it though, simply flowed from Kps to Kipo with the corresponding adjustments to the domain. This allowed me to not start strictly from zero and this time, I would focus a more on staying more true to Monogame where possible (GameComponent, DrawableGameComponent) than complete F# moules and functions.

The decision comes from being able to interop and leverage existing MonoGame Libraries in case I needed to, which ended up being useful when integrating Myra as a GUI library.

In any case back on the game itself, the main effort at the beginning was to port over the input, keybindings and action systems from KPS. These would allow me to start moving a player and invoking abilities for the early prototype phases.

Then simple motion in a top-down 2d world was more than enough to get started.

Kps had a monolithic GameState that managed every component of entities in a single record in a very monolithic way. In Kipo I decided to split the components into separate maps of components which allowed for more flexibility and granular updates although, that introduced a little bit of coginitive complexity as entity components are no longer grouped together.

// Kps code
type EntityComponents = {
  Identity: Classification.Profession
  BaseStats: Attributes.BaseAttributes
  Resources: Attributes.Resources
  Position: Position
  Movement: Movement
  AbilityCooldowns: HashMap<int<AbilityId>, TimeSpan>
  Effects: HashMap<int<EffectId>, ActiveEffect>
  Factions: Classification.Faction HashSet
  Abilities: int<AbilityId> HashSet
  PartyId: Guid<PartyId> voption
  Inventory: HashMap<Guid<InventoryItemInstanceId>, InventoryItem>
  EquippedItems: HashMap<Slot, Guid<InventoryItemInstanceId>>
}

Note: Kps Domain.fs shows the full picture of the Kps domain types.

// Kipo code
type World =
    abstract Time: Time aval
    // Components as adaptive maps
    abstract Positions: amap<Guid<EntityId>, Vector2>
    abstract Velocities: amap<Guid<EntityId>, Vector2>
    abstract Resources: amap<Guid<EntityId>, Entity.Resource>
    abstract Factions: amap<Guid<EntityId>, Entity.Faction HashSet>
    // ...
    abstract AIControllers: amap<Guid<EntityId>, AI.AIController>

This in turn allowed the newer systems to operate on the components they care about and when updates were made, only the relevant state would update, not an entire entity.

Reactive Data

One of the key technical choices was the integration of FSharp.Data.Adaptive.
This library allows for reactive programming patterns, where changes to data automatically propagate through the system. This also guaranteed a single source of truth along systems when these requested the most recent snapshot of the game state.

The built-in cache mechanisms also (hopefully as I didn't measure anything at this point though no performance issues have been noticed at all) helped to avoid unnecessary recomputations during the game loop.

For example:

type EffectProcessingSystem(game: Game, env: PomoEnvironment) =
  inherit GameSystem(game)

  let (Core core) = env.CoreServices

  // Adaptive computations were set in class private properties
  let timedEvents =
    core.World.ActiveEffects
    |> timedEffects
    |> calculateTimedEvents core.World

  let loopEvents =
    core.World.ActiveEffects
    |> loopEffects
    |> calculateLoopEvents core.World

  let permanentLoopEvents =
    core.World.ActiveEffects
    |> permanentLoopEffects
    |> calculatePermanentLoopEvents core.World

  let allEvents =
    let inline resolve _ a b = IndexList.append a b
    AMap.unionWith
      resolve
      timedEvents
      (AMap.unionWith resolve loopEvents permanentLoopEvents)
    // get only the values, as keys are not relevant here
    |> AMap.toASetValues

  let publishEvents(events: IndexList<LifecycleEvent> seq) =
    for evts in events do
      for evt in evts do
        match evt with
        | State stateEvent -> core.EventBus.Publish stateEvent
        | EffectTick(DamageIntent dmg) -> core.EventBus.Publish dmg
        | EffectTick(ResourceIntent res) -> core.EventBus.Publish res

  override _.Update _ =
    allEvents
    |> ASet.force // request the latest snapshot
    |> publishEvents

having the adaptive value "running" within the class and requesting the latest snapshot during the update loop allows the system to avoid dirty checking and flag-based management with ifs and other flow control mechanisms.

Most of these computations are pure functions that operate on the state and transform that data to produce something that can be used in this case by other systems via the event bus.

In this case, all of the effect-related events are calculated from the active effects map, which if no-one is applying or removing effects, this map remains unchanged and no recomputations are made even if we request the latest snapshot every frame.

Depending of what the systems do, some of them use adaptive values some of them just use pure functions that operate on the latest snapshot of the world and overall this is what most systems within the game look like.

Gameplay Depth (Mid-November)

With these core systems in place, I was able to start iterating on basic gameplay features. Each time a new feature was added. It fit neatly into the established architecture, more domain types, a new system and the game loop just kept running smoothly.

Then the focus shifted to implementing deep RPG mechanics. F# algebraic data types make it easier to reason about the relation between different concepts and how those can be intertwined, for my case it boiled down to have simple and small types that represent the domain concepts and then build systems that operate on these types.

Combat, Skills, and Inventory

Porting what I had already done in Kps, was a bit complex as some of the previous code assumed the existance of things that weren't there just yet however, the very core of combat and skills were ported with nearly no changes.

Non-Surprisingly F# is very good at math 😆, the complex part as usual was to decide how these calculations were going to be performed.

What are the attackers stats, what are the defender stats. How do defenses (and when) apply and so on.

Skills were a difficult piece in the sense that, there's a lot of moving parts and trying to be relatively generic while still being flexible enough to express different kinds of skills was a challenge in itself.

I've been playing Trickster Online at least a decade at this point (thanks private servers), and I never thought how complex skill definitions, effects placed from skills, targeting modes, nuances between single-hit, multi-hit, multi-target, directed-multi-target, area-of-effect, were... something I always took for granted as a player.

However, I think I was able to settle on a flexible enough skill definition format that allows me to express a wide variety of skills. For example, here's a fireball skill definition:

"2": {
    "Name": "Fireball",
    "Description": "Hurls a seeker fiery ball that explodes upon impact.",
    "Intent": "Offensive",
    "Cost": { "Type": "MP", "Amount": 20 },
    "Targeting": "TargetEntity",
    "Area": "Point",
    "Delivery": {
      "Type": "Projectile",
      "Speed": 100.0,
      "CollisionMode": "IgnoreTerrain"
    },
    "ElementFormula": {
      "Element": "Fire",
      "Formula": "(MA * 1.0) + (FireA * 1500)"
    }
}

Note: For more definitions and the difference between them you can check Skills.json

Effects were complicated as there's stacking, permanency, effects that get stronger/weaker based on stats, and so on.

[<Struct>]
type Targeting =
    | Self
    | TargetEntity
    | TargetPosition
    | TargetDirection

[<Struct>]
type SkillArea =
    | Point
    | Circle of radius: float32 * maxCircleCircleTargets: int
    | Cone of angle: float32 * length: float32 * maxConeTargets: int
    | Line of width: float32 * length: float32 * maxLineTargets: int

[<Struct>]
type EffectModifier =
  | StaticMod of StatModifier
  // e.g. The more MA, the more HP heals/damages as the result of the effect
  | DynamicMod of expression: Formula.MathExpr * target: Stat
  // e.g. Hellfire residual burn damage based on ability power and element
  | AbilityDamageMod of
    abilityDamageValue: Formula.MathExpr *
    element: Element voption
  | ResourceChange of resource: ResourceType * amount: Formula.MathExpr

[<Struct>]
type Effect = {
    Name: string
    Kind: EffectKind
    Duration: Duration // e.g., Instant, Timed, Loop, Permanent
    Modifiers: EffectModifier[]
}

Bonus: Flexible Formulas

One thing that I feel like I should mention is how we handle skill damage sources. In a typical RPG, you have damage formulas, stat calculations, and elemental modifiers and a bunch of other things... it can get messy fast.

I didn't want to hardcode logic like let damage = (attack * 2) - defense directly into the codebase. I wanted the flexibility to tweak game balance because I feel mods could be a thing somewhere in the far future.

So, as usual with F#, I started with a type and wrote a small parser to convert the strings into a type-safe tree at runtime.

type MathExpr =
    | Const of float
    | Var of VarId  // e.g. "AttackPower", "FireRes"
    | Add of MathExpr * MathExpr
    | Mul of MathExpr * MathExpr
    | Pow of MathExpr * MathExpr
    // ... and so on

This allows me to write strings like "(MA * 1.0) + (FireA * 1500)" directly in the skill data. The game parses this at runtime and evaluates it when a fireball hits an enemy entity (or a friendly one if it relates to healing).

AI Behaviors

One of the previous parts that I felt were almost good enough in Kps was the AI system.

Based on controllers that are attached to entities, the core of the AI controlled entities is based on perception, behavior and cues.

[<Struct>]
type CuePriority = {
  cueType: CueType
  minStrength: CueStrength
  priority: int
  response: ResponseType
}

type AIArchetype = {
  id: int<AiArchetypeId>
  name: string
  behaviorType: BehaviorType // e.g. Patrol, Aggressive
  perceptionConfig: PerceptionConfig
  cuePriorities: CuePriority[]
  decisionInterval: TimeSpan
}

Note: For more details on how the AI system works, check AI.fs

I think there's still a lot of room for improvement here, but the basic systems are in place to allow entities to perceive their surroundings, react to stimuli (cues), and make decisions based on their defined behavior types.

Event Bus

To decouple these growing systems, we refined the internal event system. This allowed gameplay events (like "UnitDamaged" or "SkillCast") to trigger independent reactions across the codebase without systems knowing about each other.

I have always been a big fan of event-driven code, firing an event and handling somewhere else I feel it is a good way to decouple systems even if that brings some complexity when trying to trace what is going on.

[<RequireQualifiedAccess>]
module SystemCommunications =
  [<Struct>]
  type EffectApplicationIntent = {
    SourceEntity: Guid<EntityId>
    TargetEntity: Guid<EntityId>
    Effect: Effect
  }

  [<Struct>]
  type ProjectileImpacted = {
    ProjectileId: Guid<EntityId>
    CasterId: Guid<EntityId>
    TargetId: Guid<EntityId>
    SkillId: int<SkillId>
  }

  // ... other strongly typed events

Maps and Tiled2D

Tiled2D maps are basically just XML files that describe layers of tiles, objects. Some data can be attached to the map itself or to objects via custom properties.

And since there's already an XML parser built into .NET parsing these maps is very straightforward.

The Map.fs file defines the F# types that mirror the structure of the Tiled XML files, allowing the game engine to load and work with map data programmatically.

Basic Definitions:
- Orientation, StaggerAxis, RenderOrder: F# enums corresponding to Tiled's map settings.
- TileDefinition, MapTile: Types to represent individual tiles and their instances on a map layer.
Map Components:
- MapLayer: An F# record representing a Tiled layer, containing its ID, name, dimensions, and a 2D array of optional MapTiles.
- MapObject: Represents a single object from an object group, encapsulating its ID, name, type (MapObjectType), position (X, Y), size (Width, Height), rotation, custom properties, and geometric Points (for polygons).
- MapObjectType: An F# discriminated union (Wall, Zone, Spawn, Teleport) to categorize map objects, facilitating type-safe pattern matching in game logic.
- PortalData: Specifically for Teleport objects, defining the target map and spawn point.
- ObjectGroup: A collection of MapObjects, matching the Tiled object groups.
- Tileset: An F# record holding the metadata and TileDefinitions for a tileset.
MapDefinition: This is the top-level type that holds all the parsed information from a .xml map file, including global properties, tilesets, layers, and object groups. This MapDefinition is then used by various game systems (rendering, physics, AI) to interact with the game world.

[<Struct>]
type MapObjectType =
    | Wall
    | Zone
    | Spawn
    | Teleport

[<Struct>]
type MapObject = {
    Id: int<ObjectId>
    Name: string
    Type: MapObjectType voption
    X: float32
    Y: float32
    // ...
    Points: IndexList<Vector2> voption // For polygons
}

You can find the full parsing code in MapLoader.fs

Optimization & Refinement (Late November)

At some point when some core systems were in place. Adding more entities, traversing the map suddenly brought some random freezes, which I attributed to garbage collection. From what others have said in their F# experiences, excessive garbage collection can be a common issue due to the immutable nature of F#.

And while avoiding GC and trying to be performant from the start was also one of the goals, somehow I missed the mark.

So I revisited some of the core systems to realize that there were some bad assumptions of using adaptive data for things that change very often like positions, spatial grids which are updated every update cycle, so the adaptive graph was being invalidated every frame as the "root" data was changing constantly. That got me thinking "If we're going to invalidate the tree every frame, there's no point in using adaptive data for these parts". I opted for a mixed approach where adaptive data is used for more stable data while more dynamic data while still backed up by adaptive data, snapshots are calculated on demand rather than leveraging full adaptivity and calculations being made in adaptive computations.

[<Struct>]
type MovementSnapshot = {
    Positions: HashMap<Guid<EntityId>, Vector2>
    SpatialGrid: HashMap<GridCell, IndexList<Guid<EntityId>>>
    Rotations: HashMap<Guid<EntityId>, float32>
}

// In Projections.fs
member _.ComputeMovementSnapshot(scenarioId) =
    // Forces the adaptive values once per frame to build the snapshot
    let velocities = world.Velocities |> AMap.force
    let positions = world.Positions |> AMap.force
    // ... calculates physics logic ...
    calculateMovementSnapshot time velocities positions ...

This resulted in smoother performance and the freezes were gone.

If you're using adaptive data for whatever reason, I would say that try to keep the adaptive roots/trunk as stable as possible when it comes to the frequency of input data and leave most of the high frequency changes to leaves in the adaptive tree.

Spatial Optimization

A major refactor involved the spatial domain, implementing SAT for precise collision detection. The good news is that even if I'm not skilled in geometry this math is an already solved problem. So after a couple prompts to assistants I had a working implementation.

There are some edge cases where collision boudaries are not being calculated properly, specially when boundaries overlap, this is something I still need to investigate and fix. I guess AI is not replacing us soon after all 😆. It however, helped me to not divert too much time and effort to learn something that works and unblocks me from more interesting/important work untill I have a chance or motivation to fix this.

The 3D Pivot (Early December - Present)

The most recent and significant shift has been the transition from 2D sprites to a full 3D visual style while keeping the same logic core.

I imported 3D models (using KayKit assets) and replaced the legacy 2D rendering logic. This also meant building a 3D animation system from scratch to handle model rigging, keyframes, and state-based animations like Idle, Walk, and Attack.

This is just another area where I have never worked before, but with a few prompts and trial and error I was able to get something basic working and it is sustainable enough to keep building upon!

I can see myself later on adding more complex animations like spell casting, taking damage, dying, and so on.

[<Struct>]
type RigNode = {
  ModelAsset: string
  Parent: string voption
  Offset: Vector3
  Pivot: Vector3 // Key for fixing rotation issues!
}

[<Struct>]
type Keyframe = {
  Time: TimeSpan
  Rotation: Quaternion
  Position: Vector3
}

[<Struct>]
type AnimationClip = {
  Name: string
  Duration: TimeSpan
  Tracks: Track[] // Array of keyframes per node
}

Data Driven

One of the important aspects of this game is how some key systems are data-driven.

For example, AI Archetypes, Skills, Maps, and Items among others, are defined in JSON files which may be moved to a database later on.

This while allowing me to iterate fast on mechanics or design, also hints at a possible modding system in the future as well as oportunities for more F# tools to be created in order to facilitate content creation.

Visual Polish: The Particle System (Mid-December)

With combat, skills and 3D rendering in place, one missing piece (among others) are particles! Things flying and arriving look good for a demo but they lack emotion, so the next sensible thing to add is particles which should give the visuals a little bit more of sense of being alive.

Modeling Emitter Behavior with DUs

The particle system needed to describe where particles spawn (shapes) and how they flow (emission modes). Rather than a flat configuration object with fields like isOutward: bool or shapeType: string, these became proper discriminated unions:

[<Struct>]
type EmitterShape =
    | Point
    | Sphere of radius: float32
    | Cone of angle: float32 * radius: float32
    | Line of width: float32 * length: float32

[<Struct>]
type EmissionMode =
    | Uniform   // Fill area evenly
    | Outward   // Flow away from origin
    | Inward    // Converge toward center
    | EdgeOnly  // Spawn at perimeter only

These two dimensions compose orthogonally: a Sphere + Outward creates an explosion, while Sphere + Inward creates an implosion. The pattern matching makes the logic clean:

let inline computeSpawnDistance (mode: EmissionMode) (length: float32) (rng: Random) =
    match mode with
    | Uniform  -> float32(Math.Sqrt(rng.NextDouble())) * length
    | Outward  -> float32(rng.NextDouble() * 0.85) * length
    | Inward   -> length * (0.85f + float32(rng.NextDouble() * 0.15))
    | EdgeOnly -> length * (0.95f + float32(rng.NextDouble() * 0.05))

Adding a new emission mode is straightforward: define the case, then the compiler points to every match expression that needs updating.

Cross-System Integration: Skills Shape Particles

One pattern that emerged was letting the combat system's SkillArea influence particle geometry. When a cone skill like Dragon's Breath fires, its particles should automatically fill that cone — not some hardcoded shape from the particle config.

The particle system checks for skill-driven overrides at spawn time:

| EmitterShape.Cone(configAngle, configRadius) ->
    let angle, length =
        match overrides.Area with
        | ValueSome(SkillArea.Cone(skillAngle, skillLength, _)) ->
            skillAngle, skillLength
        | ValueSome(SkillArea.AdaptiveCone(skillLength, _)) ->
            configAngle, skillLength
        | _ -> configAngle, configRadius * 10.0f
    spawnConeShape rng angle length effectiveMode

This keeps the systems decoupled — particles don't know about combat logic, they just receive typed data. Adding a new skill area type automatically prompts consideration of how particles should render it.

Note: The full particle configuration reference can be found in ParticleConfigReference.md

What's the actual F# role here?

F# is usually seen as a niche language, downplayed due it's functional nature and the fact that has to compete in a C# dominated space. Using it for Game development is even more niche, so why bother?

Refactoring confidence. Moving from a single, monolithic GameState to separate component maps (and later switching parts of the renderer to 3D) felt safe because the compiler would catch a lot of the mechanical mistakes. That meant I could iterate fast: change a type, let the compiler point out what else needed fixing, and keep moving.
Domain-first modeling. Instead of inventing a bunch of boilerplate classes, I encoded the game's rules and structures directly as types. Those types became a readable, enforceable design document — tooling (and the type system) did a lot of the heavy lifting.
Things like units-of-measure/UMX for IDs and strongly typed events reduced accidental bugs (mixing up identifiers or event payloads). They're not flashy, but they save time when you refactor or add new systems.

All of that combined let me mix high-level functional ideas (the MathExpr tree for flexible formulas) with low-level, performance-conscious code (structs, spans, inline function control, among others) without feeling like I was fighting the language.

If you look at the commit history for Kipo you'll see a theme: quick, targeted rewrites and a lot of small, confident changes. I rebuilt the rendering pipeline to support skeletal 3D animation in a day, and when GC hiccups showed up I refactored movement to use frame snapshots.

That kind of speed comes from a practical place: F# encourages expressive domain modelling and gives you enough type-safety to catch many mistakes early. The payoff is especially noticeable while prototyping — you can experiment, refactor, and change direction without the usual fear of breaking everything.

As I usually say, F# is a high level rust with an even easier time to get going. You get performance, safety, and expressiveness all in one package.

LLMs and what they've contributed.

If you've follow me before, you probably know that I've been using LLMs to help me with my Game Development Journey!

I know next to nothing from 3D graphics programming, Geometry, Animation, and many of the areas game development touches. so Things like Gemini, Qwen, Claude have been really useful to get me going where I wanted to go.

Whether you like AI or not, for me it is clear that these tools offer a value, I wouldn't let gemini or other assistants write the entire game for me that's for sure and I am very wary of code they write when I am familiar with the domain. I do inspect code in order to correct patterns that I don't like or that I think are not optimal. But when I am exploring new areas, these assistants help me get started, give me ideas, and unblock me when I get stuck.

LLMs produce slop? Yes. Humans produce slop? Also yes.

A challenge when working alone (especially when you don't know particular areas like geometry or 3D rendering) is detecting sloppy code. You can't really code review your own blind spots.

From my experience with this codebase, the AI-generated code wasn't so much wrong as it was redundant: repetitive patterns, duplicated logic, correct inputs and outputs but with bloated inner workings. Honestly, this reflects what us humans tend to do anyway.

There are still moments where I need to go back and do a full refactoring pass (specially before merging a PR) so I can ensure the code follows my general guidelines. Not super minuciously detailed, I'm human after all and my time is limited. It still requires deliberate effort to keep the codebase in shape and not let it become slop soup.

Combined with how expressive and robust F# is, moving fast and safe is possible even when exploring new areas, as long as the domain is well modelled F# code will flow naturally, things will break in expected ways and the compiler will help you get back on track. The most troublesome part is when there's subtle logical bugs or lack of domain knowledge, but that's where human intuition and experience come into play.
Even then AI assistants are good "rubber ducks" so rather than a "just code" tool, I also do a lot of back and forth to validate, refine and challenge my own understanding of the problem at hand.

Conclusion

In just over a couple months, Kipo has evolved from a basic F# architectural prototype into a functional 3D RPG with complex systems for AI, combat, and inventory. This journey proves that F# is not just viable for game development but can offer a powerful, type-safe, and expressive way to build complex interactive systems.

If you are interested in game development with F# and MonoGame, I highly encourage you to give it a try. The ecosystem might be smaller than C#'s, but the power of the language makes up for it.

If you want me to share more of F# + AI personal experiences and personal approaches let me know in the comments or ping me on my socials!

Local migrations for embedded SQLite in F#

Angel Daniel Munoz Gonzalez — Sat, 02 Mar 2024 05:01:58 +0000

Hello there, once again we're back with more F# goodies.

There's a very minimal chance that you might remember one of my F# OSS projects called Migrondi.

AngelMunoz / Migrondi

A Super simple SQL Migrations Tool for SQLite, PostgreSQL, MySQL and SQL Server

Currently Working on the next version to also add better support for the VSCode Extension!

Migrondi

Migrondi is a SQL Migrations tool designed to be simple and execute simple migrations. Write SQL and execute SQL against your database.

No need to install it, use it from VSCode! https://github.com/AngelMunoz/migrondi-vscode

Migrondi Runs on Linux-x64, Linux-arm64, Windows-x64, and MacOS-x64 (intel based)

Install

For Non .NET users

Grab the binary from the releases page or build from source and put it on your PATH, that way the command is available globally e.g.

# you can put this at the end of your ~/.bashrc
# $HOME/Apps/migrondi is a directory where you have downloaded your "Migrondi" binary
export MIGRONDI_HOME="$HOME/Apps/migrondi"
export PATH="$PATH:$MIGRONDI_HOME"

For .NET users

you can now install this as a global/local tool as well

dotnet tool install --global Migrondi

Usage

Init

…

View on GitHub

It is fair as I wrote it over four years ago, So I'll give you a quick reminder:

Migrondi is a SQL Migrations tool designed to be simple and execute simple migrations. Write SQL and execute SQL against your database.

I initially wrote it as a CLI tool, but in my last attempt I tried to expose the core parts as a library, mostly to support programmatic cases as well as to be able to change the backing storage from file system to something else.

For the most part supports some of the major databases like SQL Server, MySQL, PostgreSQL, and SQLite.

Having that said... Have you ever written a CLI tool, or any kind of user facing application which stores local data? If you have, you might have faced the problem of managing a local database instance, perhaps a NoSQL embedded alternative or something painful related to text file formats.

Personally, I used to use LiteDB which is a NoSQL version which in v4 paired very nicely with F# thanks to Zaid's lovely LiteDB.FSharp library. Sadly, when v5 showed up, a lot of the F# niceties were lost given how the API was changed and v5 was not very F# friendly. You can still use it of course but you fall back to more unsafe F# code which is not ideal.

So the next natural candidate is SQLite, which is a very popular choice for local databases and also a safe bet for F# developers as there's a bunch of F# libraries that support SQL very well. My issue in general with SQL databases is having to manage the schema and migrations prior to get hacking around with your app.

For applications that have a remote database that's fine, you can use a tool like Migrondi, Flyway, Liquibase, etc. to manage your migrations and you're good to go but, for local databases how do you manage your schema and migrations?.

I'm sure there are solutions out there that I'm not aware of, but it was a big driver for me to add library support to Migrondi, so I could use it to manage local databases as well.

So let's see how we can use Migrondi to manage a local SQLite database. in your project!

For this we'll be looking at an example I already wrote for you!

AngelMunoz / Siquelin

WIP

This repository is meant to be source material for a future set of blog entries for more F# goodies.

Usage

Description:
  A simple time tracking cli example

Usage:
  Siquelin [command] [options]

Options:
  --version       Show version information
  -?, -h, --help  Show help and usage information

Commands:
  log <day>                      Start a new work day
  item <start> <finish> <label>  Add a new shift item
  list-items <day>               List shift items for a day []

View on GitHub

Which for the intended purposes, I'd recommend you to set github at the tag 01-exploring-a-foreign-codebase or clone it and checkout to that tag as that will be the code this post will be talking about.

If you want to learn a little bit more on "How to explore a foreign codebase" I'd recommend you to check out this post: Exploring an F# foreign codebase which contains a few tips and tricks to get you started with unknown to you F# codebases.

In our particular case we're only interested in the Types.fs, Migrations.fs, Program.fs and the Commands.Hidden in Commands.fs module.

NOTE: dotnet add package Migrondi.Core --prerelease to add the new bits to your project in case you want to try this yourself.

Let's start with the Migrations.fs file, which contains a few helper functions with Migrondi.Core to manage our migrations.

namespace Siquelin.Migrations

module Runner =
  open Migrondi.Core
  open Microsoft.Extensions.Logging

  let internal getMigrondi rootDir config =

    let migrondi = Migrondi.MigrondiFactory(config, rootDir)
    migrondi.Initialize()
    migrondi

  let runMigrations (logger: ILogger, migrondi: IMigrondi) = ...

  let addNewMigration (logger: ILogger, migrondi: IMigrondi) (name: string) = ...

If you don't want to customize Migrondi in any way (meaning that you want to use Migrondi just like you would use the CLI tool), then you can use MigrondiFactory to create a new instance of Migrondi and then call Initialize to load the migrations from the root directory.

The MigrondiFactory function takes a MigrondiConfig item and a string which is the root directory where the migrations are located.

The run migrations function is not particularly complex, it simply calls MigrationsList() from an IMigrondi instance and then filters the pending migrations. If there are any pending migrations, it calls RunUp to apply them and logs the applied migrations.

let runMigrations (logger: ILogger, migrondi: IMigrondi) =
    let hasPending =
      migrondi.MigrationsList()
      |> Seq.choose(fun m ->
        match m with
        | Pending p -> Some p
        | _ -> None
      )
      |> Seq.length > 0

    let applied: seq<MigrationRecord> =
      if hasPending then migrondi.RunUp() else Seq.empty

    for migration in applied do
      logger.LogInformation("Applied migration {}", migration.name)

The addNewMigration function is also quite short, it mainly calls Migrondi to generate a new migration file.

let addNewMigration (logger: ILogger, migrondi: IMigrondi) (name: string) =
    let migration = migrondi.RunNew name
    logger.LogInformation("Generated migration {}", migration.name)

For our simple application, we don't need anything else, once we're able to access an IMigrondi instance we can run migrations and add new ones.

Now, let's take a look at the Types.fs file, which contains the types that we'll be using to interact with the database.

type WorkDay = {
  id: int
  date: DateOnly
}

type ShiftItem = {
  id: int
  workDayId: int
  start: TimeOnly
  finish: TimeOnly
}

Our CLI app focuses on being able to save "shift items" for a given "work day". and basically for any work day we can have multiple shift items.

Which should be listable when required.

NOTE: Keep in mind that this example is for a use case where the user is generating the data, but if you're generating the data yourself for configuration, or for pre/post processing, you can follow this approach as well!

Without diving into much detail, our app has a new-migration hidden command, it is callable from the CLI and is enabled only in DEBUG builds.

When we're developing our app we are able to call the following command to generate a new migration file to manage our SQLite database.

dotnet run -- new-migration initial-types

This will generate a new migration file in the migrations directory which may look like this ./migrations/initial-types_1708665113196.sql

Our file content is about creating the tables for our types.

-- MIGRONDI:NAME=initial-types_1708665113196.sql
-- MIGRONDI:TIMESTAMP=1708665113196
-- ---------- MIGRONDI:UP ----------

create table work_days(
    id integer primary key autoincrement,
    date text not null,
    unique(date)
);

create table shift_items(
    id integer primary key autoincrement,
    work_day_id integer not null,
    start_time text not null,
    end_time text not null,

    foreign key(work_day_id) references work_days(id)
      ON DELETE CASCADE
);

-- ---------- MIGRONDI:DOWN ----------

In this file we have two sections

MIGRONDI:UP which contains the SQL to create the tables.
MIGRONDI:DOWN which is empty, but it would contain the SQL to drop the tables.

The golden rule in Migrondi is to not remove anything from MIGRONDI:UP and above and not to remove the particular line where MIGRONDI:DOWN is located.

The first part is basically metadata for migrondi to know what to do with the file, the content between MIGRONDI:UP and MIGRONDI:DOWN is the SQL that Migrondi will execute when running the migration, and below MIGRONDI:DOWN is the SQL that Migrondi will execute when rolling back the migration.

Many folks don't like rolling back, so feel free to leave it empty, it is your choice.

In Program.fs theres a single line that is important for us to be able to use Migrondi.

[<EntryPoint>]
let main argv =

  let env = Env.getEnv()

  // run this at the start of the app regardless of the commands
  // this will ensure that the database is up to date
  Runner.runMigrations(env.logger, env.migrondi)

  ... more content ...

When the app starts, it will run the migrations, and then it will continue with the rest of the app.

And that's it! As long as we tell Migrondi where our migrations are and where is the database, we can use Migrondi to manage our local SQLite database.

Let's check the Env.fs file to see what are the particular values we're picking up from the environment.

let private loggerFactory = ...

let private getEnvLocations () =
  // The appData let binding, refers to where are we going to store our database
  // in the user's machine. We're using the LocalApplicationData folder to avoid
  // polluting the user's home directory.
  // ~/.local/share/siquelin in *nix systems
  // C:\Users\<USER>\AppData\Local\siquelin in Windows
  let appData =
    Path.Combine(
      Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
      "siquelin"
    )

  // The full path to our database file including it's name.
  let dbPath = Path.Combine(appData, "siquelin.db")

  // appDir is the directory where the app is located, we use this to locate the migrations
  // in dev time we will be invoking these migrations from the project directory
  // so we just pick the current directory
  // in release time we will have our migrations next to our assembly
  // so we want to use that instead of the current directory
  let appDir =
#if DEBUG
    // At dev time we want to be in the project directory
    // as they will be copied to the output directory when building for release
    // ~/projects/Siquelin
    Environment.CurrentDirectory
#else
    // where is our assembly located
    // migrations will be in the same directory (e.g. {AppContext.BaseDirectory}/migrations/*.sql)
    AppContext.BaseDirectory
#endif

  {
    appDirectory = appDir
    appDataDirectory = appData
    databasePath = dbPath
  }

let getEnv () : Types.Env.AppEnv =
  let logger = loggerFactory.Value.CreateLogger("Siquelin")

  // get the locations for the app as we saw in the previous function
  let locations = getEnvLocations()

  // create the database directory if it doesn't exist
  // to avoid exceptions when trying to create the database file
  Path.GetDirectoryName locations.databasePath
  |> Directory.CreateDirectory
  |> ignore

  let config = {
    // use the default configuration but override the connection string
    MigrondiConfig.Default with
        connection = $"Data Source={locations.databasePath};"
  }

  // Get an instance of migrondi, the migrondi instance will use the app directory
  // as the root directory for the migrations, and the connection string to connect to the database
  let migrondi = Runner.getMigrondi locations.appDirectory config

  let getConnection () : IDbConnection =
    new Microsoft.Data.Sqlite.SqliteConnection(config.connection)

  let workdays = Database.Workday.factory getConnection
  let shiftItems = Database.ShiftItem.factory getConnection

  {
    locations = locations
    logger = logger
    migrondi = migrondi
    workdays = workdays
    shiftItems = shiftItems
  }

From here on you can start running the other commands

dotnet run -- item 10:00 11:00
dotnet run -- item 11:30 12:30

And then list the items

dotnet run -- list-items
info: Siquelin[0]
      Listing shift items for: Saturday, February 24, 2024
info: Siquelin[0]
      Shift item: 10:00 - 11:00
info: Siquelin[0]
      Shift item: 11:30 - 12:30

Before deploying this to production, we need to be sure that our migrations will be available for the app to run, so we will a couple of lines in our Siquelin.fsproj file to include the migrations in the output directory.

<ItemGroup>
    <None Include="./migrations/*">
        <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </None>
</ItemGroup>

This will ensure that our migrations are copied to the output directory when we build the app, and live next to the assembly.

Yay! We have a local database, we're managing it with Migrondi!

However, the eagle eyed reader might have noticed that we can't identify the shift items, they are just a bunch of times, and our users might want to know which shift item is which.

The bad news is that we've already shipped this and our users are already logging their shift items... so we can't simply blow away the database and start from scratch the next time we run the app, once again Migrondi comes to the rescue!

We can add a new migration to add a new column in the existing tables, and then we can update the data to fill in the new column.

dotnet run -- new-migration add-name-column

This will create something like add-name-column_1708811304117.sql, then we can add the following migration.

-- MIGRONDI:NAME=add-name-column_1708811304117.sql
-- MIGRONDI:TIMESTAMP=1708811304117
-- ---------- MIGRONDI:UP ----------

-- We're adding new columns to the database to store the name of the item.
-- and attempt to backfill

alter table work_days add column item_name text;

UPDATE work_days SET item_name = CAST(id AS TEXT) where item_name is null;

alter table shift_items add column item_name text;

UPDATE shift_items SET item_name = CAST(id AS TEXT) where item_name is null;

-- ---------- MIGRONDI:DOWN ----------

After adding that migration, we can update our types

type WorkDay = {
  id: int
  date: DateOnly
  name: string option
}

type ShiftItem = {
  id: int
  workDayId: int
  name: string
  start: TimeOnly
  finish: TimeOnly
}

and the rest of the code updates.
The next time we run the app, the migrations will be applied and the new columns will be added to the database, and the data will be updated to fill in the new columns.

Let's move forward to the 02-siquelin-upsert-existing tag in the repository to see the updated implementation.

In regards to our migration management, nothing changed other than the migration we added, and the types we updated. the rest were application and business logic changes.

Running the new commands

dotnet run -- item 17:55 20:15 "watch netflix"
dotnet run -- item 17:00 17:30 "Bathroom"

And then listing the items

dotnet run -- list-items
info: Siquelin[0]
      Listing shift items for: Saturday, February 24, 2024
info: Siquelin[0]
      Shift item: 'watch netflix': 17:55 - 20:15
info: Siquelin[0]
      Shift item: 'Bathroom': 17:00 - 17:30

Even if our users typed the wrong command (as it is a breaking change for them because a new required argument as added to the command line interface), the migrations will be applied and the data will be updated to fill in the new columns.

This is done transparently to the users, and we can be sure that the database is up to date.

That's how we can use Migrondi to manage a local SQLite database in our F# application. There are of course alternative approaches to this and hopefully Migrondi is up to the task for your use case. If not, I welcome you to open an issue in the repository for your potential contribution or discussions related to what you're trying to do.

Feedback and user testing is always welcome, so if you have any thoughts or questions, feel free to reach out to me on twitter or open an issue in the repository.

Exploring a foreign F# codebase

Angel Daniel Munoz Gonzalez — Sat, 24 Feb 2024 16:26:36 +0000

Hello folks, here we are again with more F# content for you!

I have a few things in mind that I want to write about relative to some of my older projects, but I'm not settled in stone yet.

This blog post is going to be part of a series called "Dissecting an F# codebase" where I'll try to tell you how to approach new codebases, what to look for and how to get a handle on them. Today's topic is the first one and relatively simple: "This place is inmense, how do I even begin to explore it!?".

For that we'll be working with

AngelMunoz / Siquelin

WIP

This repository is meant to be source material for a future set of blog entries for more F# goodies.

Usage

Description:
  A simple time tracking cli example

Usage:
  Siquelin [command] [options]

Options:
  --version       Show version information
  -?, -h, --help  Show help and usage information

Commands:
  log <day>                      Start a new work day
  item <start> <finish> <label>  Add a new shift item
  list-items <day>               List shift items for a day []

View on GitHub

This is a small project I wrote a few days ago in order to produce a series of blog posts, some about Migrondi and some about this series.

In case the contents of the project have changed at the time you're reading this, please check the git tag: 01-exploring-a-foreign-codebase

Finding a cool F# project to explore

While you can follow these tips with the stated project above, please feel free to check it out with any project you already have in mind or new ones to see if this will work for you or not.

The first step when you have a project already in mind, is to simply visit their repository and check out what the README has in place

WIP

This repository is meant to be source material for a future set of blog entries for more F# goodies.

Oh great... that's quite useful, isn't it? 😅

Hmm maybe file structure?

.config
.vscode
migrations
.editorconfig
.gitignore
Commands.fs
Database.fs
Env.fs
Extensions.fs
Migrations.fs
Program.fs
README.md
Siquelin.fsproj
Types.fs

Yes... but no. GitHub doesn't help very much in this department as it doesn't have any notion of how the files are used. If you come from other languages you also know that Files can be deceiving as they don't tell much about the codebase.

Well, here's one of the cool things F# offers for you: The often controversial "Top-Down File Ordering" requirement. Many folks when they come to F# from other languages are quite annoyed by this and is seen as a limitation, which perhaps it is! But it also has a very cool side effect: It gives you a very clear idea of how the codebase is structured.

So rather than doing what we've tried so far, let us check the Siquelin.fsproj file.

NOTE: Keep in mind that larger projects may have multiple .fsproj files. In those cases, you need to determine which one is the main project and go from there.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <Compile Include="Extensions.fs" />
    <Compile Include="Types.fs" />
    <Compile Include="Migrations.fs" />
    <Compile Include="Database.fs" />
    <Compile Include="Env.fs" />
    <Compile Include="Commands.fs" />
    <Compile Include="Program.fs" />
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Donald" Version="10.0.2" />
    <PackageReference Include="FSharp.SystemCommandLine" Version="0.17.0-beta4" />
    <PackageReference Include="Migrondi.Core" Version="1.0.0-beta-010" />
  </ItemGroup>
  <ItemGroup>
    <None Include="./migrations/*">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </None>
  </ItemGroup>
</Project>

Oh! ok, ok cool, this is a bit more useful. From checking this file we can see that the project fills the following bullets:

It is a console project (otherwise it wouldn't have the output type node)
It targets dotnet 8
The entry point is Program.fs (top-down file ordering!)
It has 3 dependencies: Donald, FSharp.SystemCommandLine and Migrondi.Core
It is copying the migrations folder to the output directory

NOTE: You can try this with the Feliz codebase, which is larger and has multiple .fsproj files. But as you will find out, the project structure is laid out just like we've seen here.

We can now go back to the Top-Down file ordering requirement and quickly determine that Extensions.fs is the most accessible file in the project as it is at the top and any other file below it will have knowledge from this file. The last file is Program.fs which must have the entry point for the application given that we've already determined that we're working with a console application.

Any other file in-between them may tell the structure of the application. But keep in mind that just because a file is ordered above another it doesn't mean it is using it's sibling contents. Sometimes these files don't use each other and may be using the contents of the files above them instead.

Let's check our entry point first.

open FSharp.SystemCommandLine
open Siquelin
open Siquelin.Types
open Siquelin.Migrations

[<EntryPoint>]
let main argv =

  let env = Env.getEnv()

  // run this at the start of the app regardless of the commands
  // this will ensure that the database is up to date
  Runner.runMigrations(env.logger, env.migrondi)

  rootCommand argv {
    description "A simple time tracking cli example"

    // set the main handler to do nothing
    setHandler id

    // add a subcommand to list shifts

    addCommand(Commands.logDay env)
    addCommand(Commands.logItem env)
    addCommand(Commands.listItemsForDay env)

#if DEBUG
    // only allow this command in debug mode as it is meant for dev purposes
    addCommand(Commands.Hidden.newMigration env)
#endif
  }

Oh, looks like the author at least gave us some comments to work with and figure out what the thing is doing. It seems like it's a CLI application for time tracking. It also seems like it is running some sort of migrations even before the commands are parsed and executed which is a bit questionable but we don't know the reasons behind that

So from this file we've at least determined that it is a CLI application which has four commands and one is hidden.
We can pick the next file in the list or we can check the Commands module to feed our curiosity and coincidentally the Commands module lives in the Commands.fs file!

NOTE: For larger codebases with more history it is likely that the Program.fs file will have a lot of orchestration and logic as well. given that it is often where everything clashes and starts, for example the Fable Entrypoint is in Entry.fs and it contains a lot of code. The best you can do always is to start at the bottom of the file and work your way up. Remember: Everything at the bottom uses what has already been defined at the top so there are no circular dependencies or random functions/types at the bottom that can trip you off, everything comes from the top!

If the file you're going to check next is big, or contains a lot of modules, I'd recommend you to fold/collapse via your editor the modules and check them one by one.

If we apply the tip from above then the Commands.fs file would look like this:

namespace Siquelin

open System
open FSharp.SystemCommandLine

open Siquelin.Types

module Parsing = ...

module Handlers = ...

module Commands = ...

Which is very helpful, otherwise this file would blast us 200 lines of code to the face directly filling us with a lot of context we don't understand yet which may become quickly confusing!

Following from our previous experience, we knew there was a Commands.logDay function, so we can check the Commands module and see what it does.
Once again following the same tip, we can fold/collapse the module and check the logDay function.

module Commands =
  let logDay (env: Env.AppEnv) = ...

  let logItem (env: Env.AppEnv) = ...

  let listItemsForDay (env: Env.AppEnv) = ...

  module Hidden = ...

Oh, so it seems like the Commands module is just a collection of functions that are being used in the Program.fs file.

As a word of caution, these functions seem to be asking for an Env.AppEnv type, it can be easy to start looking into what this AppEnv is and quickly get derailed looking into more, and more, and more code! My personal recommendation is to first keep checking the function is doing and how it is using this so called AppEnv

let logDay (env: Env.AppEnv) =
    let argument =
        Input.Argument<string>(
        "day",
        "The day to log, in the format of 'yyyy-MM-dd'"
        )

    let cmd = command "log" {
        description "Start a new work day"

        inputs(argument)

        setHandler(
        (fun day ->
            match Parsing.dayParser day with
            | Ok day -> day
            | Error e -> failwith e
        )
        >> Handlers.logDay(env.logger, env.workdays)
        )
    }

    cmd

Looks like we're creating a command with a description and an argument, and then we're setting a handler that is using the Parsing.dayParser and Handlers.logDay functions.

From here, it looks like the first parsing function is going to be composed with the Handlers.logDay function thanks to the >> operator.
We don't know the shape of the Handlers.logDay function yet but now at least we know that the so called AppEnv is some sort of dependency container as it has a logger and a workdays property.

The following step would be to check the Handlers module and see what the logDay function is doing.

module Handlers =
    let logDay (logger: ILogger, workdays: WorkdayService) (day: DateOnly) = ...

    let logItem
        (logger: ILogger, workDays: WorkdayService, shiftItems: ShiftItemService)
        (start: TimeOnly, finish: TimeOnly, day: DateOnly option) = ...

    let listItemsForDay
        (logger: ILogger, shiftItems: ShiftItemService)
        (day: DateOnly option) = ...

Oh, similar to the Commands module, it seems like the Handlers module is just a collection of things and by the looks of it these are functions.

let logDay (logger: ILogger, workdays: WorkdayService) (day: DateOnly) =
    logger.LogInformation(
        "Logging a new work day: {day}",
        day.ToLongDateString()
    )

    workdays.create day

Cool! So it looks like the logDay function is just logging a message and then calling the create method on the workdays service.

Notice how we've been able to follow the code without doing any Ctrl/Cmd+F or Go to definition or a similar action. the code so far has been very linear and hasn't done any kind of weird indirections or anything like that.

Let's skip one of the tips above and check the WorkdayService and see what the create method is doing via go to definition.

It took us straight into the Types.fs file and we found this:

namespace Siquelin.Types

open System

type WorkDay = { id: int; date: DateOnly }

type ShiftItem = {
  id: int
  workDayId: int
  start: TimeOnly
  finish: TimeOnly
}

module Env =
  open Microsoft.Extensions.Logging
  open Migrondi.Core

  type SiquelinDataLocations = {
    appDirectory: string
    appDataDirectory: string
    databasePath: string
  }

  [<Struct>]
  type ShiftItemQueryError = | WorkDayNotFound

  type WorkdayService =
    abstract member create: DateOnly -> unit
    abstract member list: unit -> WorkDay list
    abstract member get: DateOnly -> WorkDay option
    abstract member exists: DateOnly -> bool

  type ShiftItemService =
    abstract member create:
      DateOnly * TimeOnly * TimeOnly -> Result<unit, ShiftItemQueryError>

    abstract member list:
      DateOnly -> Result<ShiftItem list, ShiftItemQueryError>

  type AppEnv = {
    locations: SiquelinDataLocations
    logger: ILogger
    migrondi: IMigrondi
    workdays: WorkdayService
    shiftItems: ShiftItemService
  }

Looks like a file defining some types and a module with even more types... Aha there it is!

type WorkdayService =
    abstract member create: DateOnly -> unit
    abstract member list: unit -> WorkDay list
    abstract member get: DateOnly -> WorkDay option
    abstract member exists: DateOnly -> bool

Oh great just an interface definition 🫠... where is this being created? Maybe if I click in See usages I can find it!
Well... yes, you may find it that way, but do you want to do that?

You just followed up to check up a type in a function parameter and you're now exposed to this other information which may be a distracting factor if you're trying to understand how it works, it might have been useful and give you other contexts which is fine the more seasoned F# developer you are. However, if you're still not comfortable enough with F# this might be introducing you to more noise and overload you making you think: "Hmm I better check out this later there's a ton of stuff there...".

We've felt for this trap so... how do we get out of here?
Let's go back to the Handlers module and check the logDay function again.

let logDay (logger: ILogger, workdays: WorkdayService) (day: DateOnly) = ...

We now know that our logDay function is asking for a WorkdayService and a ILogger and thanks to our "go to definition" click, we also know that the WorkdayService is being part of the AppEnv type.

But wait, we already knew that, didn't we? We knew that the AppEnv type was being used in the Program.fs to create the commands and within the Commands module we also found out that the AppEnv type had a workdays property.

Let's check the Program.fs file once again but let's check the Env module this time.


[<EntryPoint>]
let main argv =

  let env = Env.getEnv()

Oh, great looks like there's a function in the Env module that is creating the AppEnv type for us. Let's check it out.

module Siquelin.Env

open System
open System.IO

open Microsoft.Extensions.Logging

open Migrondi.Core

open Siquelin.Types.Env
open Siquelin.Migrations
open System.Data

let private loggerFactory = ...

let private getEnvLocations () = ...

let getEnv () : Types.Env.AppEnv = ...

Oh, this file is laid out differently than the others, while sure it has an Env module, it looks like the whole file is a single module instead. It also looks like it is creating the AppEnv type for us and it is using a loggerFactory and a getEnvLocations function to do so.

Let's expand the getEnv function and see what it is doing.

let getEnv () : Types.Env.AppEnv =
  let logger = loggerFactory.Value.CreateLogger("Siquelin")
  let locations = getEnvLocations()

  // create the database directory if it doesn't exist
  // to avoid exceptions when trying to create the database file
  Path.GetDirectoryName locations.databasePath
  |> Directory.CreateDirectory
  |> ignore

  let config = {
    MigrondiConfig.Default with
        connection = $"Data Source={locations.databasePath};"
  }

  let migrondi = Runner.getMigrondi locations.appDirectory config

  let getConnection () : IDbConnection =
    new Microsoft.Data.Sqlite.SqliteConnection(config.connection)

  let workdays = Database.Workday.factory getConnection
  let shiftItems = Database.ShiftItem.factory getConnection

  {
    locations = locations
    logger = logger
    migrondi = migrondi
    workdays = workdays
    shiftItems = shiftItems
  }

Welp, at least we now know where this workdays implementation is coming from. Looks like it is being created from a Database.Workday.factory function.

Sheesh... we're out of the trap! we're back to the normal flow where we can check things from the bottom to the top and not get derailed by other things.

But how would the non-trap version would have been?

For that we would have taken just the same steps but in reverse.

I'm in the logDay function who is supplying these parameters?
I'm in the Commands.logDay function this is supplying me with the env parameter, where is this being supplied?
I'm in the Program.fs file and I see that the env is being created in the Env module, let's check that out.

And then we would have been in the Env module and continue our bottom to top exploration with folded members/modules. This would have prevented us from getting cognitive overload from information we don't necessarily need at this moment. Keep in mind that while those are two approaches to the same problem (figuring out how does WorkdayService looks and it is implemented), I personally believe that one method is better for seasoned F# developers and the other is better for newcomers. Feel free to mix and match these techniques so far to your liking and see what works best for you.

What do we know so far?

We have a CLI application
It has 4 commands, one of them is hidden
It is running migrations before the commands are parsed and executed
The Commands module is using an AppEnv type
The cli commands are being created in the Commands module
The Commands module is using a Parsing and Handlers module
The Handlers module is using a WorkdayService and a ShiftItemService
The WorkdayService and ShiftItemService are being created in the Env module
The Env module is creating the AppEnv type
The AppEnv type is being used in as a dependency container which is created in the Program.fs file

I hope that at this point you're spotting the discovering pattern and can start using it to explore foreign F# code bases. Perhaps that will ease a bit of stress when you're trying to understand a new codebase and potentially contribute to it.

Find the desired .fsproj file
Check the dependencies
Check the top-down file ordering
Check the last file in the list
If the code is big, fold/collapse the contents and check them from the bottom to the top
Visit the next module/file above what you're currently checking and repeat the process.

This is my personal way of exploring a new codebase, and I hope it helps you as well.

Note: For applications, this is a good way to start, but for libraries it might slightly different. Libraries don't have "entry points" in the same way applications do, so while you might still want to check the .fsproj file and the top-down file ordering The files in there might be sibling files and not sharing code between them, or there might be a set of indirections that you need to follow to understand how the library works. But I still find the bottom to top approach to be useful in those cases.

We'll stop here for the moment as this is just one entry in the series. Next time we'll talk about partial application and how it is used for dependency injection in the Siquelin project which probably at this point you've already spotted it.

In case you have any questions or comments, feel free to reach out to me on Twitter, Threads, The Fediverse or GitHub.
I hope you've enjoyed this entry and I hope to see you in the next one!

Revisiting WASM for F#

Angel Daniel Munoz Gonzalez — Sat, 16 Dec 2023 14:36:04 +0000

Hey there folks! It has been a while!

As you may be aware with my content at this point I do a bunch of F# on my free time, on my not so free time I do web development.

I am a big fan of going with web components + plain (build-less) javascript whenever possible, so it is not surprising that I often favor things like the Fable Compiler, where I can target my F# code directly to javascript and be as close to the native JS experience as possible, both for interop concerns and for ecosystem integration.

And while JS is still the best course of action today to do front-end development, I think with the release of dotnet 8 we're bound to re-visit how is Blazor doing.

If you don't know what Blazor is the Tl;Dr would be that it is a framework for building dotnet apps for WASM and running dotnet code in the browser like F#, be sure to visit Microsoft docs for more information though!

Blazor itself!

Before we go down into the F# code, I'd like to offer some of the new and shiny things that may be relevant for you when you evaluate if Blazor is good for your or your organization.

It is no secret that the talented folks at Microsoft can produce and improve very well crafted software when executives don't get in their way and I think Blazor is one of those pieces. On each release since dotnet 6 things have improved from trimming, AoT, runtime size, and, performance among others, they have also introduced different ways to render wasm in your dotnet apps.

Pre-rendering - Server Only no interactivity
Server Interactivity - Server Only, interactivity via websockets
Client WASM - Client only loads the whole app + runtime in the browser
Auto Interactive - best of the 3 worlds, pre-renders, provides interaction while wasm loads, once wasm loads it stays there

I was going to write a slightly longer part on this topic but to be honest Dustin wrote a much better and comprehensive post about it, so you should check him out.

I agree with most of the conten on his post (specially when he says "I've never been the person who blindly champions every Microsoft technology without critical thought") except on two sides

Auto Interactive mode is more akin to meta-frameworks like Nextjs, Remix, Qwik, and not so with SPA frameworks like Angular, React or Vue

This means that only client wasm should be compared to the later, and the former should be compared to blazor as a whole not just one segment of it, from that lens blazor isn't really that far behind and can actually provide a really performant and close to today JS frameworks, though Dev experience is still behind as there is no reliable hot reload (specially for F# where there's no hot reliad at all).

"The parallels with Silverlight are hard to ignore"

I would also say that IF blazor worked on a browser plugin like silverlight did, today that's not the case it is built on the webassembly standard which and it is being adopted in the browsers which means once it gets on the web, it is unlikely to ever go out again. Even if Microsoft themselves leave Blazor today, it can still work, the burden of creating a fork and keeping blazor alive will certainly be big but someone will be able to do that, just like the open silver folks revived silverlight via wasm tech without any particular Microsoft involvement.

That being said, let's talk about the stuff we're here for.

The F# bits

Over the past month I went down to try two of the most prominent libraries that build on top of Blazor

Last time we saw them was at the frontend review I wrote a couple of years ago

Exploring The F# Frontend Landscape

Angel Daniel Munoz Gonzalez ・ May 24 '22

#fsharp #dotnet #webassembly #webdev

But it is also nothing too extreme.

Essentially both options remain virtually the same in the sense that those simple example I showed there still work.

If it is not too cynical I think that might already be a point for wasm as you you may know how easy is to JS codebases not work after a couple of years pass by 😆. Well yeah maybe to cynic but, it is indeed a strong point for wasm codebases and specially dotnet ones, if the code worked before it is almost guaranteed that it will be working in a few years without any modifications at all.

Note: The examples and use cases I'll show below require interactivity, either with WASM only mode or any other of the previously mentioned rendering modes in Blazor, so keep that in mind.

Bolero

Let's dive into Bolero. This framework doesn't shy away from it's functional flavored style it goes straight into the MVU paradigm and it is the most common way you'll see code around, our previous example was the following:


type Model = { value: int }

type Message = Increment | Decrement

let initModel = { value = 0 }

let update message model =
    match message with
    | Increment -> { model with value = model.value + 1 }
    | Decrement -> { model with value = model.value - 1 }

let view model dispatch =
    div {
        button { on.click (fun _ -> dispatch Decrement); "-" }
        string model.value
        button { on.click (fun _ -> dispatch Increment); "+" }
    }

type MyApp() =
    // TheProgramComponent class implements the bits
    // that interop with blazor to make elmish work
    inherit ProgramComponent<Model, Message>()

    override _.Program =
        // here we start our elmish loop and let it do it's thing
        Program.mkSimple (fun _ -> initModel) update view

The elmish loop as usual provides predictability and a traceable code flow, however one of the main criticisms of MVU is the fact that once the code starts growing larger the update function becomes massive and starts losing the appeal.

While there's arguments from both sides if that's a bad thing at all, Bolero offers a way to abstract certain parts of your code in Elmish components which can be used to further de-couple the main update events with inner events in certain parts of your screen.

Let's say for example that we want a modal-like component that can be

Entirely Dismissed
Cencelled
Accepted with value

type ModalError =
  | Cancelled
  | Dismissed

type ModalInfo = {
  header: string;
  message: string;
}

type MyModal() =
    inherit ElmishComponent<ModalInfo, Result<unit, ModalError>> =

    override this.View model dispatch =
      let { header = modalHeader; message = message; } = model
      dialog {
        // For simplicity we'll let the parent control the visibility of this modal
        // so we'll set it to true rather than a dynamic value.
        attr.``open`` true
        // You could certainly handle this locally within the component.
        header {
            h3 {
                modalHeader
            }
            button {
                on.click(fun _ -> dispatch (Error Dismissed))
                "❌"
            }
        }

        p { message }

        button {
          attr.autofocus true
          on.click (fun _ -> dispatch (Error Cancelled))
          "Cancel"
        }

        button {
          on.click (fun _ -> dispatch (Ok ()))
          "Ok"
        }
      }

With styling aside, the general structure of our modal would look like that.

Note: As a general rule (regardless Blazor or Bolero) when you design components you want to pass the information into the components via props/parameters and any modifications hoisted to the parent via events/callbacks this enables unidirectional flow that makes it less prone to have bugs in your code and also de-couples the component of knowing what to do with the information once it "has changed".

In your parent you would use it like this:

// assuming we've defined already our message and our model before.
let view model dispatch =
  let translations = getTranslations model.language
  article {

    // content off your view

    // somewhere dispatch a message to open the modal
    button {
      on.click(fun _ -> dispatch OpenModal)
      "Open Modal"
    }

    cond model.showModal <| function
    | true ->
      ecomp<MyModal, _, _>
        { header = translations["modalTitle"]; message = translations["modalMessage"] }
        (fun value ->
          match value with
          | Ok () -> dispatch CanContinue
          | Error _ -> dispatch ShowAlternativeFlow
        )
    | false -> empty()
  }

As you can see this is a fairly simple way to keep constant with the MVU pattern but also allowing for internal messages to not leak into the main elmish loop.

This is not new though and it is well documented in their website so you should check them out when you have a chance.

Note: If you're interested in more Bolero specific examples for frontend use cases, let me know I'd be happy to write about those of that can help folks out there.

And if you include a few updates for Elmish V4 like reusable subscriptions then the MVU pattern becomes easier to manage.

Bolero clearly goes for the more functional side of frontend development and it works nice. There are still a few extra features I haven't talked about like remoting, routing but bolero is a solid choice if you want to bring your existing skills to the frontend development without getting lost into quest to learn how to do modern web development in the JS world.

Fun.Blazor

This framework also supports MVU via its [Fun.Blazor.Elmish] package but let's take a look at what's in the box.

If you have keep up with the frontend development landscape in JS-land then you may know that today's sauce is using "hooks" or "signals".
Hooks are a react invention to react problems, and while they aren't really needed in many frameworks today (because they don't have react problems) they provide good developer experience to handle unidirectional flow and local state management and that made them quite popular even outside react.

On the signals front, folks have gone full circle in their quest for wheel re-invention and currently we landed back into observables as the primitive for reactive state.
Thankfully this time we're not entirely back at square 0 with signals, as one of the major proponents Ryan Carniato is a very skilled person and more importantly he remembers history, something the frontend folks tend to not do when they're iterating and stomping accedentally in concepts already tried in the past.

This iteration of signals is very much appreciated and for the developers it looks almost like if they were using hooks.

With that context, I'd like to show you [FSharp.Data.Adaptive] which is an abstraction for reactive data that works similarly to excel cells, and pretty much fits the shape of signals in the frontend

type MyCounter() =
  inherit FunBlazorComponent() =

    let state = cval 0

    override this.Render() =
      article {
        button { onclick(fun _ -> state.Publish(fun state -> state + 1)) }

        "Counter: "

        adaptiview() {
          let! counter = state
          $"{counter}"
        }

        button { onclick(fun _ -> state.Publish(fun state -> state - 1)) }
      }

In the example above our local state is handled by changeable values, which will drive any other computations and the Adaptive model will take care of caching and checking for value changes that affect how often our views render, in the case above only the adaptiview() node will be re-rendered any time the state changes, the rest of the contents remain static which contrasts with the MVU way to always re-render regardless of state changes.

If we go back to the modal example from above it would look somewhat like this:

type ModalError =
  | Cancelled
  | Dismissed

type ModalInfo = {
  header: string;
  message: string;
}


module Modals =
  let MyModal (modalInfo: ModalInfo, onAction: unit -> Result<unit, ModalError>) =
    let { header = modalHeader; message = message } = modalInfo
    dialog {
      // For simplicity we'll let the parent control the visibility of this modal
      // so we'll set it to true rather than a dynamic value.
      attr.``open`` true
      // You could certainly handle this locally within the component.
      header {
        h3 { modalHeader }
        button {
            onclick(fun _ -> onAction (Error Dismissed))
            "❌"
        }
      }

      p { message }

      button {
        attr.autofocus true
        onclick (fun _ -> onAction (Error Cancelled))
        "Cancel"
      }

      button {
        onclick (fun _ -> onAction (Ok ()))
        "Ok"
      }
    }

type MyApp() =
  inherit FunBlazorComponent()

  override this.Render() =
    article {
      // your view's content

      // trigger the dialog
      button {
        onclick (fun _ -> state.Publish (fun state -> { state with modalOpen = true }))
        "Open Modal"
      }

      adaptiview() {
        let! (state, setState)  = state.WithSetter()

        let { modalOpen = isOpen; modalInfo = modalInfo } = state

        if modalOpen then
          Modals.MyModal(
            modalInfo,
            (fun result ->
              match result with
              | Ok() ->
                setState({ state with modalOpen = false })
                continue()
              | Error _ ->
                setState({ state with modalOpen = false })
                showAlternativeFlows()
            )
          )
      }
    }

Now, it certainly makes it simpler to write and to reason about what is updating what, however it can introduce complexity when coordinating other parts/features of the view you're currently in, in our MVU example we just dispatched another message, and here we're calling other functions, which they may be callbacks or part of the view's current function.

NOTE: Similarly to the MVU message, if you are able to pas information as parameters/props and hoist state to the parent via events/callbacks then this will be simpler to reason about.

Interop with JS

While both Bolero and Fun.Blazor provide means for your F# code to shine without the pain that may come with JS tooling (specially if you don't work with that in a day to day basis) until WASM gets DOM or Browser API access you still have to fallback to JS when that's the case. This is when we step back from the F# framework side and lean on the Blazor layer.

For both Bolero an fun Blazor you should be able to use dependency injection by standard means.

First let's create a common interface and a simple factory for our service.


type ILocalStorage =
  abstract getItem: string -> Task<string option>
  abstract setItem: string * obj -> Task<unit>

module LocalStorage =
  let factory (services: IServiceProvider) =
    let js = services.GetService<IJSRuntime>()

    { new ILocalStorage  with
      override _.getItem key = task {
        let! content = js.InvokeAsync<string>("localStorage.getItem", key)
        return content |> Option.ofObj
      }

      override _.setItem (key, value) = task {
        do! js.InvokeVoidAsync("localStorage.setItem", [| box key; value |])
      }
    }

With that factory, we can then register that in our Startup.fs file or wherever we are currently registering our DI services

To get a reference in a bolero component, it is fairly straight forward:

type Services = {
  jsRuntime: IJSRuntime
  localStorage: ILocalStorage
}
module MyApp =

  let update (services: Services) model message =

    match message with
    // in cases you already have registered service you can pass that to the update function
    // similar to constructor injection, but in this case it is partial application
    | FromParameter ->
      state,
      Cmd.ofTask.perform services.localStorage.getItem model.key SetContentInModel

    // For one of shots, you can simply invoke JS interop effect directly in the elmish loop
    | UsingBoleroHelpers =
      state,
      Cmd.OfJS.perform services.jsRuntime "localStorage.getItem" [| box model.key |] SetContentInModel

type MyApp() =
    // TheProgramComponent class implements the bits
    // that interop with blazor to make elmish work
    inherit ProgramComponent<Model, Message>()

    [<Inject>] // with get, set is important as the DI takes place on public properties
    member val LocalStorage: ILocalStorage = Unchecked.defaultOf<_> with get, set

    override this.Program =

        let update state message =
          let dependencies = { localStorage = this.LocalStorage; jsRuntime = this.JsRuntime }
          // partially apply the function dependencies
          MyApp.update dependencies

        // here we start our elmish loop and let it do it's thing
        Program.mkSimple (fun _ -> initModel) update view

For Fun.Blazor the situation is very similar

type MyComponent() =
  inherit FunBlazorComponent() =

  let key = "some-key"
  let state = cval {| value = None |}

  [<Inject>] // with get, set is important as the DI takes place on public properties
  member val LocalStorage: ILocalStorage = Unchecked.defaultOf<_> with get, set

  override this.Render() =
    article {
      button {
        onclick(fun _ task {
          let! value = this.LocalStorage.getItem(key)
          state.Publish(fun state -> {| state with value = value|})
        })
        "Invoke Function"
      }
    }

Both Bolero and Fun.Blazor allow you to interop with javascript seamlessly, it however depends on you how you'd like to structure your programs and follow patterns, one way is simpler but can lead to more complex code eventually while the other is very straight forward but can be cumbersome once it gets up to certain height.

Continuing with the topic at hand interop happens at the blazor layer, the parameters you pass in the InvokeAsync function in IJSRuntime must be JSON serializable, this serialization is not customizable as far as I know (there's better info at the MS docs in case I get that wrong). so you have to be careful what you're sending, for F# most types will work but discriminated unions will not, as that support has not been added yet to System.Text.Json (which powers all of interop layer)

In the previous interop example, we used global functions, and while nothing stops you from also adding your own namespace in the global window e.g.

window.MyNamespace = {
  MySubSection: {
    doWork(a, b, c) {},
  },
};
// call it like window.MyNamespace.MySubSection.doWork(a, b, c);

It promotes global polution and also you leave lazy loading out of the window, a better approach is to work straight with Javascript modules so, how about importing your own authored JS files? let's think about a module like this.

// /js/my-script.js
import { dependency } from "./lib/dependencies/dependency.js";

export async function doWork(a, b, c) {
  const value = await dependency(a, b);
  return c + value;
}

We can use our factory function again to create a service for that =

type IMyService =
  inherit IAsyncDisposable
  abstract doWork: string * string * int -> Task<int>

module MyService =
  let factory (services: IServiceProvider) =
    let js = services.GetService<IJSRuntime>()
    // use a lazy value here to call the import only untill we really need it
    let jsModule = lazy(js.InvokeAsync<IJSObjectReference>("import", "/js/my-script.js"))

    { new IMyService  with
      override _.doWork(a, b, c) = task {
          // will fetch the script on the first call
          // if this gets called again it will use the result from the already settled value task
          let! jsModule = jsModule.Value

          let! result = jsModule.InvokeAsync<int>("doWork", [|box a; b; c |])
          return result
      }
      override member _.DisposeAsync() =
        task {
          let! jsModule = jsModule.value
          return jsModule.Dispose()
        }
        |> ValueTask
    }

And just like that, you have lazy loading for services, and simple JS interop for both Fun.Blazor and Bolero you can then inject this service as shown above.

Closing thoughts!

There's a bunch more to talk about (from each of the frameworks and blazor itself!) but I'd rather leave that for other post entries.
Having in mind that this section is purely my personal thoughts...

I'd say blazor (with either bolero/fun.blazor) has moved the needle favorable a little bit more.

When I wrote the original piece about the Frontend landscape I felt WASM was simply not worth it at the time except on very specific cases, today with the new Auto Interactive rendering mode blazor offers plus the advances in the F# counterparts I think we're getting into "Let's GOOOO" territory.

Assuming you can deploy aspnet servers freely, then if you were considering nuxt/next/remix or those kinds of metaframerowks, then Blazor might have become an option for you and depending on the talent pool you have around it might be worth it to have lesser context switches and enjoy the benefits of F# and full dotnet in the browser.

Assuming WASM only mode then... Things haven't changed that much but they have changed a bit enough. While I don't have numbers loading times and trimmed app size have improved quite a lot so WASM apps are closer to your standard "Enterprise Angular" application (if you've seen those you know what I mean), so loading times and bundle sizes might not be that relevant for you anymore. Except in cases where time to interaction means $$$, then stick to pre-render and server first approaches.

For places like intranet applications or enterprise'y large apps then I'd consider it even more today for sure you could write those in angular/react today but if you still end up working with 10 thousands of lines of code, I think Blazor can benefit better from F#, its language features. and dotnet ecosystem specially in that "Full Stack" scenario where your core library gets shared entirely, not just a subset that may or may not work in the browser but the real thing.

Oh no, I typed 'dotnet new web' with F#!

Angel Daniel Munoz Gonzalez — Thu, 20 Jul 2023 18:00:00 +0000

Oh Jesus... not this again... please don't tell me that you just typed:

dotnet new web -lang F# -o MyProject

What!?

A friend of yours was insisting that you use F# for your next project, and you just wanted to get it over with?

Let me guess... he didn't even tell you that there are better™ web frameworks for F# like Giraffe, Saturn, and Falco among others?

You just followed the instructions at the Microsoft's documentation?

No worries that happens more often than you think.

If that sounds like too dramatic for you, let me tell you I've seen it before online, I've heard it in person and even in my own head (when I went through the "F# would be better without M$" phase).

When we insist to our friends to try out F# sometimes we actually don't expect them to try F# (because of reasons) and we don't give a path or indication to how to get started with the "True F# experience™" other than "You should try F# it's an awesome language".

In the F# online communities there are people who will tell you to avoid Microsoft at all costs, others will tell you that there are F# tailored solutions by the community and others won't care at all, it's your code not theirs.

But if for some particular reason you stumbled into the microsoft docs and you followed the instructions to create a new web project with F# you may have typed that command above and you may be wondering what to do next.

By the way, you can find source code for this post in the following repository:

AngelMunoz / dotnet-new-web-fsharp

Oh no, I typed 'dotnet new web' with F#!

You were told to use F# but noone gave you a path to get started right?

Well I have a blog post entry just for that case! and this repository is the source code that goes hand by hand with that post.

Run

dotnet run

And start sending requests with postman/curl/whatever to

http://localhost:5000/

http://localhost:5000/uploads

http://localhost:5000/api/uploads/user-avatar

That should show things working on nicely

View on GitHub

dotnet new web...

When you run that command you'll get a directory structure like this:

MyProject
├── appsettings.Development.json
├── appsettings.json
├── Program.fs
├── MyProject.fsproj

This is what is known as a Minimal API in dotnet it is an aspnet feature that introduces a simpler way to get started without too much ceremony for C# projects that also happens to work with F#.

The Program.fs file is the entry point of your application and should look somewhat like the following

open System
open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.Hosting

[<EntryPoint>]
let main args =
    let builder = WebApplication.CreateBuilder(args)
    let app = builder.Build()

    app.MapGet("/", Func<string>(fun () -> "Hello World!")) |> ignore

    app.Run()

    0 // Exit code

It has the standard main function with a web application builder, an example to define a single route and start the application, it is basically a hello world web application.

Buf you will notice straight away there are some weird things around, like the Func<string>(fun () -> "Hello World!") part why not just pass a function directly there? also what's the |> ignore thing doing? why are we ignoring that though?

It turns out that in C# the compiler and tooling is built in a way that Func<T>, Action<T>, and friends can be written transparently (e.g. (string name) => Results.Ok(name)) there, F# functions (FSharpFunc<T>, fun (name: string) -> Results.Ok(name)) on the other hand while syntactically similar they are not a 1-1 replacement for those types in the dotnet runtime and there has to be a translation the F# idiom to the C# idiom.

In our sample above MapGet is part of a route builder meaning that it always returns an instance of RouteHandlerBuilder in C# there's no warning for discarded values so it doesn't show anything, in F# to avoid that warning we explicitly ignore the value.

Note: In the case of the |> ignore<'T> (you don't see the 'T because the compiler provides type inference) this is a feature that doesn't let you simply discard return > values from an expression, you have to explicitly ignore them or live with a warning. Take into account the following JavaScript code
function addProp(obj, propName, value) {
  // The previous dev who worked here
  // Mutated the object, it didn't creae a new one
  // Not even god remembers why, he left the company 2 years ago
  obj[propName] = value;
  return obj;
}
// create a person with a name
const person = { name: "Frank" };

// add the age property to the person use the same reference
addProp(person, "age", 30);

// someone else decided to apply object destructuring
const { name, age, job } = addProp(person, "job", "Developer");
Now that the original dev is not around, we're not sure what was the true intent of the function was it to mutate the object only? was it intended to create copies and use the resulting value? no idea but If you're a relatively seasoned JS dev, you know mutating an object within a function may lead to unexpected code paths yet > the editor/tooling won't complain about it, it is usually you or a co-worker that finds out because they got a jira ticket to fix something out.

For F# this means that it will produce a warning in the build logs as well as the editor that there's a function call that returns a value that is not being used (the first function call in the previous example) it won't complain about the second function call because you're actually using the function's return value and since most objects are immutable in F# that kind of code that mutates an instance and returns it probably wouldn't compile unless it is a classic dotnet object.

Ok, but is that actually bad?

You might be wondering if those annoyances might limit how your F# code behaves or what can be done with it and the reality is that no that's not really a big issue in my opinion it is not bad it is just annoying, as you have to type more characters and it introduces more noise to the code, you certainly notice that C# gets more love but that's not a big deal, you can still write your code and it will work just fine.

At this point you might start wondering if there's an easier with less friction path to work with F# and asp.net, the answer is: Sure! there are actually other options you can check out like:

Falco - A functional web framework for F# that sits on top of aspnet.
Giraffe - A functional web framework for F# that sits on top of aspnet.
Saturn - A functional web take on MVC built on top of giraffe

both Falco and Giraffe are very similar but they offer different tools to work with they are not a 1-1 equivalent at the userland code level they are both worth looking at for you to evaluate.

Saturn is built on top of the giraffe abstractions for routes and function composition with a few helpers that provide a MVC-like smooth yet functional abstraction, it is more opinionated but also worth looking at.

Before we surrender to the F# idiomatic gods, I find myself in the position to tell you that you can still use the minimal api features and build your web application and that you can actually make it simpler to integrate things like swagger and open api documentation which is currently something the F# tailored solutions may not be as simple to add.

// Let's add the required namespaces
open System
open System.Threading.Tasks

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Microsoft.Extensions.Hosting
open Microsoft.AspNetCore.Http

// Rather than using functions inlined in the MapGet call we can define them
// as private functions in a dedicated module
// we use RequireQualifiedAccess to force us to use the module name
// when calling the functions
[<RequireQualifiedAccess>]
module MinimalHandlers =
    // dummy type to be able to resolve the logger
    type UploadAvatar =
          interface
          end

    // F# functions are public by default so if we want some sort of encapsulation here
    // (which is not necessary) we have to add the "private" keyword after "let"
    let private indexHandler () = "Hello World!"

    // here's a sample of a handler for file uploads
    // which in reallity is what we care about when we write our endpoints
    // the boilerplate and other things can be left out in a more localized place
    // here we can focus specifically on the request and response
    let private uploadAvatar (context: HttpContext) (logger: ILogger<UploadAvatar>) =
        task {
            logger.LogInformation "uploadAvatar Got Called"

            let! form = context.Request.ReadFormAsync(context.RequestAborted)

            let userAvatar = form.Files.GetFile "user-avatar" |> Option.ofObj

            match userAvatar with
            | Some file ->
                if file.ContentType.StartsWith("image/", StringComparison.InvariantCultureIgnoreCase) then
                    // do what you want with the file
                    return Results.NoContent()
                else
                    // if is not an image then we don't want it, tell the client it is a bad request
                    return Results.BadRequest("The file must be an image")

                    // no file means no avatar, and we will tell the client it is a bad request
            | None -> return Results.BadRequest("The request must contain a file")
        }
    // Now this is our public function, it takes a web application from the aspnet's
    // builder and registers the routes we want
    let register (app: WebApplication) =
        app
            // remember that (fun () -> "Hello World!") thing?
            // well we can now just pass the function directly
            // which adds a little bit of indirection but it makes it easier to read
            .MapGet("/", Func<string>(indexHandler))
             // Before we "ignore" the endpoint builder, we can also enjoy aspnet's features
             // which are very useful if you want swagger/open api documentation built for you
            .Produces(StatusCodes.Status200OK, "text/plain")
        |> ignore

        app
            .MapPost("/uploads", Func<HttpContext, ILogger<UploadAvatar>, Task<IResult>>(uploadAvatar))
            .Accepts("multipart/form-data")
            .Produces(StatusCodes.Status204NoContent, "text/plain")
            .ProducesProblem(StatusCodes.Status400BadRequest, "text/plain")
        |> ignore

[<EntryPoint>]
let main args =
    let builder = WebApplication.CreateBuilder(args)

    let app = builder.Build()

    // Here's where we register our handlers
    MinimalHandlers.register app
    // if we have more modules we can repeat this pattern
    // and our app is suddenly less annoying than what it got started with
    // examples could be:
    //
    // AuthHandlers.register app
    //
    // ProductHandlers.register app
    app.Run()

    0 // Exit code

If we follow the pattern of keeping our endpoints in a module and registering them at the main function we can keep our code organized with minimal effort.

But... How do we scale?

One thing I've heard before if you come from languages like Javascript/Typescript where express apps or Python's Flask apps blow up to hell due to the "micro-framework" focus of using just functions and routes

Some believe that by using only function handlers you set up yourself for spaghetti code with an untelligible mess.

This in my opinion is more of an architectural level problem rather than one at the application/framework level, you can still use the same patterns you use in other languages to keep your code organized such as dependency injection. In asp.net DI is built into the framework so you can use it out of the box. In the example above we actually injected a logger into our handler and the only thing we had to do was to add the correct signature plus the type annotation in the route registration.

If we add more services to our application, we can rely in the function parameters rather than closures to access services that may live in a module.

That being said, if you're still not convinced, we can also add controller endpoints which might be more reminiscent to controllers in frameworks like ruby on rails, laravel, django, etc which are often associated to "bigger" applications.

To do that we'll have to make some changes to our single file

// First we need to add the namespace
// otherwise controllers are not found
namespace PlainWeb

open System
open System.Threading.Tasks

open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.DependencyInjection
open Microsoft.Extensions.Hosting
open Microsoft.Extensions.Logging
open Microsoft.AspNetCore.Mvc
open Microsoft.AspNetCore.Http

// We have to use the ApiController + Route attributes
// to enable aspnets conventions for controllers
[<ApiController>]
[<Route("[controller]")>]
// DI in this case is applied at the controller's constructor level
// but... at the same time we're using a closure-like access to the handler's dependencies c:
// which was not present in the minimal example.
type UploadsController(logger: ILogger<UploadsController>) =
    inherit ControllerBase()

    // This attribute is used to specify the route otherwise it is taken from the method name
    [<HttpPost("user-avatar")>]
      // these are similar to the minimal api builder methods, they are used to specify
      // the content type of the request and response
    [<Consumes("multipart/form-data")>]
    [<ProducesResponseType(StatusCodes.Status204NoContent)>]
    [<ProducesResponseType(StatusCodes.Status400BadRequest)>]
    member ctrl.UserAvatar(avatar: IFormFile) : Task<IActionResult> =
        task {
            logger.LogInformation("UserAvatar Got Called")

            // File instance is obtained by the name of the file in the form data
            // in this case our file was named "avatar" in the client request
            // we also need to use Option.ofObj to convert the potential null value to an option
            let avatar = avatar |> Option.ofObj

            match avatar with
            | None -> return ctrl.BadRequest("The request must contain a file")
            | Some avatar ->

                if avatar.ContentType.StartsWith("image/", StringComparison.InvariantCultureIgnoreCase) then
                    // do what you want with the file
                    return ctrl.NoContent()
                else
                    return ctrl.BadRequest("The file must be an image")
        }

// Guess what!?
// We don't need to get rid of our minimal handlers!
[<RequireQualifiedAccess>]
module MinimalHandlers = (* ... *)

// namespaces cannot contain values (let bindings)
// we have to use a module wrapper to contain our main function
module Program =

    [<EntryPoint>]
    let main args =
        let builder = WebApplication.CreateBuilder(args)
        // add the required services for the controllers to work
        builder.Services.AddControllers() |> ignore

        let app = builder.Build()

        // as an example, we can keep our minimal api handlers
        // plus the controller route handlers!
        MinimalHandlers.register app
        // ProductHandlers.register app
        // ProductHandlers.register app

        // Ensure that the controller routing middleware is added
        app.MapControllers() |> ignore

        app.Run()

        0 // Exit code

With this, we also have convention based controllers that build in years of battle tested asp.net framework patterns, and minimal apis which are somewhat a newer and more lightweight concept that internally builds on top of the same conventions for regular asp.net apps.

In my personal and biased opinion, controllers are a little bit more verbose and feel heavier than minimal apis, so I tend to favor the later but they are also more familiar to people coming from other languages

In the end it is a matter of preference and how comfortable are you with the code you're writing.

So... what's next?

Getting started with your project of course! you can start adding more routes, or switching to the F# frameworks we've already mentioned or... hear me out...

Just Keep using standard asp.net!

If you got to this point and felt comfortable using plain asp.net then there's nothing wrong with that, perhaps even better as you may be able to provide feedback to the asp.net team on how to improve the experience for F# developers.

Closing Thoughts

A last word of advice, while you're learning this new F# thing with web servers you'll find that there's a ton of C# tailored documentation for things like Controllers and minimal APIs while the F# content in this regard is scarce. The main reason this happens is that most of the F# comunity doesn't want to deal with the friction of using C# idioms in F# code so they build their own solutions. Thus you're likely going to find more information by switching to an F# tailored solution.

I'd suggest that before you fully commit to something, make a couple of toy projects to test the waters and follow your gut, which one felt better and go from there! eventually you'll end up with something that you like and that works for you with the added knowledge of asp.net under the hood.

This is also not a definitive guide and I hope that you don't get discouraged from trying F# if for some reason you stumble upon the Official documentation and you end up doing something that may or may not be what your friends/twitter/reddit/discord folks were telling you about.

It is likely that when you try these minimal api things out you start feeling the friction between plain aspnet and F# so you will likely reach for a more F# tailored solution.

You know where to find me!

@angelmunoz@misskey.cloud - Fediverse presence (like mastodon).
@angel_d_munoz@threads.net - We're getting started here :P .

F# File uploads with Saturn and Falco

Angel Daniel Munoz Gonzalez — Wed, 19 Jul 2023 00:59:03 +0000

Hello there folks!

It has been quite a while (once again hah!) while I've been busy working in a few of my own F# projects the truth is that I didn't have much to write about in F# after my last "Simple things in F#" series.

Today I don't have a new series to start with but rather a simple example which may or may not grow in another blog series. For the moment we'll talk about how to do File uploads to an F# backend powered by Falco and Saturn so let's get started!

The samples for this post can be found at this repository:

AngelMunoz / fsharp-file-uploads

File Upload Sample

This is a small sample that shows how to upload a file from an HTML Form to an F# backend.

The backends here are

Falco
Saturn

While they're mainly the same as they both are built on top of ASP.NET it is nice to have a focused sample that works as a reference in case you need it.

You can check the post for this content now https://dev.to/tunaxor/f-file-uploads-with-saturn-and-falco-2ffh :)

View on GitHub

So the situation is the following

You just found F# or saw a tweet/toot/thread related to F# and decided to give it a go, you've been told there are F# web frameworks like falco and saturn but you haven't seen a lot of samples out there, it would be nice if there's a focused sample you can take a look at.

Well let me tell you that I've been there as well! Well... in my case it was with php, then with node, then with C# and at some point F# as well hah! But I digress, Let's start with our client side where we'll be sending files to our back-end.

HTML Forms

At this point in time, HTML is present everywhere so this is where we will start, given the following HTML:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Send a File to the Server</title>
  </head>
  <body>
    <!-- Standard HTML Post -->
    <form id="standard">
      <fieldset>
        <legend>Standard Html Upload</legend>
        <!-- don't forget the name, it is quite important! -->
        <input type="file" name="my-uploaded-file" />
        <!-- trigger the submit event with this button/input -->
        <input type="submit" value="Upload" />
        <progress id="standard-progress" style="opacity: 0"></progress>
      </fieldset>
    </form>
    <!-- Once the server answers our request we'll set the responses below -->
    <section id="response-target"></section>
    <section id="error-target"></section>

    <!-- Let's also sprinkle vanilla JS here to make it a little bit dynamic -->
    <script>
      // Let us wait for the DOM to load, so we can find our HTML nodes
      document.addEventListener("DOMContentLoaded", () => {
        // let's gather the elements we'll be working with
        const form = document.querySelector("#standard");
        const target = document.querySelector("#response-target");
        const errorTarget = document.querySelector("#error-target");
        const progress = document.querySelector("#standard-progress");

        form.addEventListener("submit", (e) => {
          // avoid page reloads we'll send our request manually
          e.preventDefault();
          // these days building a form data is so simple
          // just pass the form reference to the constructor and
          // all inputs related to the form will be added automatically
          const formData = new FormData(form);
          progress.style.opacity = 1;
          // We'll use a standard fetch here for simplicity
          fetch("/uploads", {
            method: "POST",
            body: formData,
          })
            .then((response) =>
              // if the status code is not ok, then we'll send the text to the catch handler
              response.ok
                ? response.text()
                : // remember text is a promise, so we'll need to extract that there
                  response.text().then((content) => Promise.reject(content))
            )
            .then((response) => {
              // if all goes well then we'll swap our target's html
              // with the server's response
              console.log("Success");
              target.innerHTML = response;
            })
            .catch((error) => {
              // you can reject promises with anything not just Errors so we'll check
              if (error instanceof Error) {
                errorTarget.textContent = error.message;
                return;
              }
              // if it was not an error then it is likely we're here due to our
              // handler above
              errorTarget.innerHTML = error;
            })
            .finally(() => {
              // hide the progress in any case
              progress.style.opacity = 0;
            });
        });
      });
    </script>
  </body>
</html>

Our client side HTML is as simple as we can get it, just a form and a few lines of JavaScript to avoid a page reload. The form submission will hit the /uploads endpoint in our server, this index file will be server by our server as well so no need to point to the full address (also to leave CORS out of the situation for the moment).

Saturn Back-end

Fortunately our sample is so focused that it can be implemented in a file with around... 50-60 LoC

open System
open System.IO

open Microsoft.AspNetCore.Http

open Saturn
open Giraffe
open Giraffe.ViewEngine

// This is a templating function to produce HTML content that we'll use later on
let responseTemplate color content =
    // Giraffe.ViewEngine uses a tagElement  attribute list  tagElement list
    article
        [ _style $"color: %s{color}" ]
        [ header [] [
            // encodedText is a function that produces a string with encoded html,
            // this avoids sending raw html to the client from the server
            h3 [] [ encodedText "File Contents below:" ]
          ]
          pre [] [ encodedText content ]
        ]
// the index handler is quite simple, just send the html file which is located by
// the relative path to the current working directory of the server
let index next context = htmlFile "./index.html" next context

// This is our File Uploads Handler
let handler next (context: HttpContext) =
    task {
        // Saturn/Giraffe can also use aspnet's features directly
        let form = context.Request.Form
        // From the ASPNET's form abstraction we try to get a single file with the name
        // we provided, we also convert it to an option to handle potential null values
        let extractedFile = form.Files.GetFile "my-uploaded-file" |> Option.ofObj
        // if we wanted to extract multiple files we'd use something like form.Files.GetFiles "input's name attribute"

        match extractedFile with
        | Some file ->
            // if the file is present in the request, then we can do anything we want here
            // from validating size, extension, content type, etc., etc.

            // For our use case we'll create a disposable stream reader to get the text content of the file
            use reader = new StreamReader(file.OpenReadStream())
            // in our simple use case we'll just read the content into a single string
            let! content = reader.ReadToEndAsync()

            // we'll write the file to disk just as a sample
            // we could upload it to S3, Google Buckets, Azure Storage as well
            do! File.WriteAllTextAsync($"./{Guid.NewGuid()}.txt", content)

            // We received a file and we've "processed it" successfully
            let content = responseTemplate "green" content
            // send our HTML content to the client and that's it
            return! htmlView content next context
        | None ->
            // The file was not found in the request well return an error message
            let content = responseTemplate "tomato" "The file was not provided"
            // and also set our status code to 400 to signal it was a client error
            return! (setStatusCode 400 >> htmlView content) next context
    }

// lastly register our routes in the router
let appRouter =
    router {
        get "/" index
        get "/index.html" index
        post "/uploads" handler
    }

// create a server
let server = application { use_router appRouter }

// run it baby!
run server

That's it! Nothing too crazy I hope!

Let's put that into an F# project

# create the project
dotnet new console -lang F# -o saturn-sample
cd saturn-sample
# add the Saturn package
dotnet add package Saturn
# create the empty index file
touch index.html

Now copy and paste the contents of the previously provided client side HTML into the index.html file, then copy F# source code and replace the contents of the Program.fs file.
and start your app.

dotnet run

You should be able to visit http://localhost:5000/ and start testing the file upload.

Falco Back-End

Fortunately, the falco sample is not much different and also fits in a single file! we'll be using the same index.html that we shown above so we'll go straight to the F# source code for this.

open System
open System.IO
open System.Threading.Tasks

open Microsoft.AspNetCore.Http

open Falco
open Falco.Routing
open Falco.HostBuilder
open Falco.Markup

// Similarly to the saturn sample
// we'll provide a templating function
// this one uses Falco.Markup though rather than Giraffe.ViewEngine
let responseTemplate color content =

    Elem.article
        [ Attr.style $"color: %s{color}" ]
        [ Elem.header [] [ Elem.h3 [] [ Text.enc "File Contents below:" ] ]
          Elem.pre [] [ Text.enc content ] ]

// equally to the previous sample we'll read the index file and return an html response
let index (context: HttpContext) : Task =
    task {
        // the only difference here is that we are able to pass the request aborted cancellation token
        let! content = File.ReadAllTextAsync("./index.html", context.RequestAborted)
        return! Response.ofHtmlString content context
    }

let handler context : Task =
    task {
        // Falco can also use aspnet's features directly
        // but offers an F# API for ease of use
        let! form = Request.streamForm context

        let extractedFile =
            // extract the file safely from the
            // IFormFileCollection in the http context
            form.Files
            |> Option.bind (fun form ->
                // try to extract the uploaded file named after the "name" attribute in html
                // GetFile returns null if no file is present, so we safely convert it into an optional value
                form.GetFile "my-uploaded-file" |> Option.ofObj)

        match extractedFile with
        | Some file ->
            // if the file is present in the request, then we can do anything we want here
            // from validating size, extension, content type, etc., etc.

            // For our use case we'll create a disposable stream reader to get the text content of the file
            use reader = new StreamReader(file.OpenReadStream())
            // in our simple use case we'll just read the content into a single string
            let! content = reader.ReadToEndAsync()

            // we'll write the file to disk just as a sample
            // we could upload it to S3, Google Buckets, Azure Storage as well
            do! File.WriteAllTextAsync($"./{Guid.NewGuid()}.txt", content)

            // We received a file and we've "processed it" successfully
            let content = responseTemplate "green" content
            // send our HTML content to the client and that's it
            return! Response.ofHtml content context
        | None ->
            // The file was not found in the request return something
            let content = responseTemplate "tomato" "The file was not provided"

            return! context |> Response.withStatusCode 400 |> Response.ofHtml content
    }


// declare the host and the endpoints
webHost [||] {
    endpoints
        [
          // handle the index routes as well
          get "/" index
          get "/index.html" index
          // our file endpoint handler as well
          post "/uploads" handler ]
}

Again, let's put that into an F# project

# create the project
dotnet new console -lang F# -o falco-sample
cd falco-sample
# add the Falco package
dotnet add package Falco
# create the empty index file
touch index.html

Now copy and paste the contents of the previously provided client side HTML into the index.html file, then copy F# source code and replace the contents of the Program.fs file.
and start your app.

dotnet run

You should be able to visit http://localhost:5000/ and start testing the file upload.

Both backends in F# are virtually the same a few differences here and there might make it more appealing for some than others but the premise is the same, using F# should make it easy and safe regardless of your preferred style and we can see this in using the F# Optional type to avoid null reference exceptions which can bite hard in languages where null is the day to day bread.

Please note the usage of the use keyword in the samples, for disposable references (the ones that implement the IDisposable interface) F# can make the disposition automatically at the end of the scope when this keyword is used, otherwise you would need to manually call reference.Dispose() which can be easily forgotten so... avoid that and just let F# handle it for you!

I must mention that when you're dealing with file uploads you should avoid reading the contents into a string, this is for performance reasons mainly because rarely you actually need to inspect the contents of the file you usually pass it on to another file upload service like I mentioned in the sample, aws, gcloud, azure, you name it letting the code process a stream is better as you don't allocate the string in memory for un-needed reasons.

Bonus HTMX

You may have heard of this HTMX thing... that supposedly makes it easier to deal with client side HTML + any existing back-end.

Well, let me tell you that it works wonders with F# as well!

to use HTMX we'll change our HTML a little bit:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Send a File to the Server</title>
    <!-- Include HTMX in your website -->
    <script src="https://unpkg.com/htmx.org@1.9.3"></script>
  </head>
  <body>
    <!-- HTMX uses hx-* attributes to indicate the behavior of the element that will send 
        an http request, in this case
        we're telling htmx to post a form-data request to the /uploads endpoint
        and when the server sends a response replace the inner html of the response target
        with the server's response
     -->
    <form
      id="htmx-form"
      hx-encoding="multipart/form-data"
      hx-post="/uploads"
      hx-target="#response-target"
      hx-swap="innerHtml"
    >
      <fieldset>
        <legend>HTMX Upload</legend>
        <input type="file" name="my-uploaded-file" />
        <button>Upload</button>
        <progress id="htmx-progress" value="0" max="100"></progress>
      </fieldset>
    </form>

    <section id="response-target"></section>
    <section id="error-target"></section>

    <!-- Closely to vanilla JS, but with a smoother API to work with -->
    <script>
      // given the element (specified by the selector) listen to the progress event in the
      // backing hxr request
      // crafting an xhr request manually is quite lengthy so that's why we used fetch in the plain
      // html example, htmx thankfully hides that for us and lets us focus on the omportant bits
      htmx.on("#htmx-form", "htmx:xhr:progress", function (evt) {
        htmx
          .find("#htmx-progress")
          .setAttribute("value", (evt.detail.loaded / evt.detail.total) * 100);
      });
      // if the backend sends an error we'll replace the contents of the error target instead
      htmx.on("htmx:responseError", (error) => {
        evt.detail.target = htmx.find("#error-target");
      });
    </script>
  </body>
</html>

You can replace the contents of the index.html file with that and it should work just as great, with the difference that we need to write a little bit of JS ourselves and we also get file upload progress as well!

Closing thoughts

Hopefully this shows that F# is not an alien language and it is more similar than you think, no weird maths, no weird point free code. This is very close to what you would write in other languages like typescript given that they provide a framework similar to aspnet!

Does this help you at all?
Do you want more content like this?

Until the next time, you know where to find me!

@angelmunoz@misskey.cloud - Fediverse presence (like mastodon).

@angel_d_munoz@threads.net - We're getting started here :P .

@angel_d_munoz - We'll take the beatings until the ship sinks or if we get bored.

Mixing Google Cloud and F#

Angel Daniel Munoz Gonzalez — Fri, 16 Dec 2022 11:00:00 +0000

This post is part of the #FsAdvent Calendar Thanks to Sergey Tihon for once again, organizing such an amazing event that brings many F# folks talking about the whole experience of using F# in a wide variety of use cases

Hello there folks, it has been a while!

I'm sorry for the lack of content and the lack of consistency (with both perla and the short F# video series I've been working with) but that's what happens when you only write for fun!

Today's topic is Google Cloud Platform and F#...

Wait what? Is that even possible? I thought that F# is just for some niche scenarios and hobby apps... Well even if that was the case (it is not) it is a Microsoft language, so it should be an Azure only thing right?

Nope, it can run on Amazon Web Services as well!

I digress, while GCP might not be the first option to pop up in your head when it comes to cloud and serverless (specially when we talk about dotnet), today that is a reality.

There are several libraries in dotnet for google apis which cover most of the GCP usage, but we will focus in Google Cloud Functions for dotnet.

Disclaimer

This blog entry is directed to those folks who are slightly familiar with gcloud, the more experience you have with it the better, but it should be fairly straight forward to follow (keeping in mind that anything that relates to the cloud is always a not so simple topic).
Also, this is not a tutorial or a "how to" kind of article but it should give you some pointers to allow you get at least a function online and running.

Before we start

While this is not a tutorial let's try to make a couple of functions just to get our feet wet

We a few things

A Google Cloud Project

You can create a new one if you don't have it

Note: The project id will be very important as it will be used in the google cloud APIs and dotnet libraries.

The GCloud CLI - https://cloud.google.com/sdk/gcloud/
The dotnet templates for the functions framework - https://github.com/GoogleCloudPlatform/functions-framework-dotnet
- dotnet new -i Google.Cloud.Functions.Templates

Fun is for Functions

Let's go for the simplest one un-authenticated, http functions let's get started

PS C:\Users\scyth\repos> dotnet new gcf-http -o MyFunction
The template "Google Cloud Functions HttpFunction" was created successfully.

This will create a new function template:

Function.fs
MyFunction.fsproj

The Function.fs file looks like this

namespace MyFunction

open Google.Cloud.Functions.Framework
open Microsoft.AspNetCore.Http

type Function() =
    interface IHttpFunction with
        /// <summary>
        /// Logic for your function goes here.
        /// </summary>
        /// <param name="context">The HTTP context, containing the request and the response.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        member this.HandleAsync context =
            async {
                do! context.Response.WriteAsync "Hello, Functions Framework." |> Async.AwaitTask
            } |> Async.StartAsTask :> _

cloud functions run aspnet core under the hood, but since it is a controlled environment it was designed in a way that the only concern you should worry about is running your function so all of the usual boilerplate related to adding services, middleware or enabling features is hidden away from you which for most simple scenarios this is what you will need and in the case of F# where dependency injection is more related to simply use functions it might be enough.

let's talk about the handler, surely it looks quite... weird right? well yes, it is kind of weird because with an async {} CE requires that you convert tasks to async, and that's a whole complex topic which may even have encyclopedic material to discuss with, in the meantime we won't care too much about it and we can change our handler to the following form:

member this.HandleAsync context =
  task {
      do! context.Response.WriteAsync "Hello, Functions Framework."
  }

Note: This is not an endorsement to switch all of the existing code in any other codebase from async {} to task {} both CEs have their usages and for this purpose since we're going to interface with many task based libraries (like GCloud dotnet APIs or aspnet's task based functions) and it makes sense to stay on the task side of things, for the most part async {} will be enough for most cases and it is still the recommended default.

That being said, let's continue with the function, the context parameter is an HttpContext object which means you have access to the Request and Response to it, you can easily extract information like the request's path, query string, it's body and other useful stuff. let's change our function to accept some json content and return some json as well.

To avoid cluttering our function body too much we will add a Json module that will handle deserialization via System.Text.Json although, feel free to use whatever json deserialization strategy you may want to go with, like Thoth.Json.Net.

namespace MyFunction

open Google.Cloud.Functions.Framework
open Microsoft.AspNetCore.Http

module Json =
  open System.IO
  open System.Text.Json

  let tryDeserialize<'Type> (body: Stream) =
    task {
      try
        let! result = JsonSerializer.DeserializeAsync<'Type>(body)

        return Ok result
      with
      | ex -> return Error ex.Message
    }

type Function() =
  interface IHttpFunction with

    member this.HandleAsync context =
      task {
        let! content = Json.tryDeserialize<{| numbers: int array |}> (context.Request.Body)

        match content with
        | Ok value ->
          let total = Array.sum value.numbers
          printfn $"Sum of the numbers is {total}"
          return! context.Response.WriteAsJsonAsync({| total = total |})
        | Error err ->
          printfn $"There were no numbers :( {err}"
          context.Response.StatusCode <- 400
          return! context.Response.WriteAsJsonAsync({| total = 0 |})
      }

Great, we now have a deserialized body and depending on what happened we can decide whether we can continue or not or if we want to tell the consumer that they didn't do what it was expected, the sky's the limit here, let's try it!

PS C:\Users\scyth\repos\MyFunction> dotnet run
2022-11-26T06:11:45.606Z [Google.Cloud.Functions.Hosting.EntryPoint] [info] Serving function MyFunction.Function
2022-11-26T06:11:45.720Z [Microsoft.Hosting.Lifetime] [info] Now listening on: http://127.0.0.1:8080
2022-11-26T06:11:45.721Z [Microsoft.Hosting.Lifetime] [info] Application started. Press Ctrl+C to shut down.
2022-11-26T06:11:45.722Z [Microsoft.Hosting.Lifetime] [info] Hosting environment: Production
2022-11-26T06:11:45.722Z [Microsoft.Hosting.Lifetime] [info] Content root path: C:\Users\scyth\repos\MyFunction

The first few lines are what we would normally expect when we run an asp net app locally via dotnet run just logs and the URL where the server is listening, I will do a bad request and a good request via postman, but feel free to use your favorite tool for this

[info] Request starting HTTP/1.1 GET http://127.0.0.1:8080/ - -
Scopes: [{ RequestId: 0HMMFEKIDG1IQ:00000002, RequestPath: / }]
There were no numbers :( The input does not contain any JSON tokens. Expected the input to start with a valid JSON token, when isFinalBlock is true. Path: $ | LineNumber: 0 | BytePositionInLine: 0.
[info] Request finished HTTP/1.1 GET http://127.0.0.1:8080/ - - - 400 - application/json;+charset=utf-8 239.0244ms

In the case above I didn't send any json body in the request and it shows our logs as well as asp.net ones.

Scopes: [{ RequestId: 0HMMFEKIDG1IQ:00000002, RequestPath: / }]
[info] Request starting HTTP/1.1 GET http://127.0.0.1:8080/ application/json;+charset=utf-8 32
Scopes: [{ RequestId: 0HMMFEKIDG1IQ:00000003, RequestPath: / }]
Sum of the numbers is 45
[info] Request finished HTTP/1.1 GET http://127.0.0.1:8080/ application/json;+charset=utf-8 32 - 200 - application/json;+charset=utf-8 30.8089ms
Scopes: [{ RequestId: 0HMMFEKIDG1IQ:00000003, RequestPath: / }]

with a little bit of date cleaning you can see in the logs that logs are there which is nice but, hold on a minute... they don't look as nice as the rest of the logs, perhaps that could be a problem with google cloud monitoring tools

Well one of the good things of asp.net is that it has a ton of stuff out fo the box and it can be included via dependency injection, which in this case we can use our Function constructor to bring things like an ILogger<Function>, IConfiguration, and other services that come out of the box from aspnet
let's change our code a little bit

namespace MyFunction

open Google.Cloud.Functions.Framework
open Microsoft.AspNetCore.Http
open Microsoft.Extensions.Logging // This line got added

module Json = // ... omit for brevity ...

// Notice
type Function(logger: ILogger<Function>) =
  interface IHttpFunction with

    member this.HandleAsync context =
      task {
        let! content = Json.tryDeserialize<{| numbers: int array |}> (context.Request.Body)

        match content with
        | Ok value ->
          let total = Array.sum value.numbers
          // switch from printfn to logger
          logger.LogInformation $"Sum of the numbers is {total}"
          return! context.Response.WriteAsJsonAsync({| total = total |})
        | Error err ->
          // switch from printfn to logger
          logger.LogInformation $"There were no numbers :( {err}"
          context.Response.StatusCode <- 400
          return! context.Response.WriteAsJsonAsync({| total = 0 |})
      }

Now our log entries will look more like

2022-11-26T06:22:08.838Z [MyFunction.Function] [info] Sum of the numbers is 45

2022-11-26T06:24:18.960Z [MyFunction.Function] [info] There were no numbers :( The input does not contain any JSON tokens. Expected the input to start with a valid JSON token, when isFinalBlock is true. Path: $ | LineNumber: 0 | BytePositionInLine: 0.

This will be very helpful to diagnose things once you deploy your function to the cloud, as it is simple to run and debug locally but it is not so simple once things are living in the cloud, logs are very important thing to get right and help yourself with future issues where your code may not be behaving as you would expect

Note: There are further customizations you can do to the startup sequence if you want for example add services via the asp.net's dependency injection mechanisms, you can view how in this document.

Great! Now we have our local function that we run, and we know it works time to deploy!

Deployment

Deploying via the CLI is I believe relatively simple, it takes a single command albeit, with a bunch of arguments but nothing more than that.

gcloud functions deploy my-function-name-in-gcp-console \
  --region us-west1 \
  --runtime dotnet6 \
  --trigger-http \
  --allow-unauthenticated \
  --entry-point MyFunction.Function

Note: Please ensure that you have initialized the gcloud cli (gcloud init) and that you have selected the project you created earlier.

gcloud functions deploy my-function-name-in-gcp-console

The first argument is the name of your function, this name will be the one that will show in the google cloud functions console and used as an identifier for your function (each new deploy will increment a version of that function rather than deploy a new function to a different endpoint)

--region us-west1

Where is this function getting deployed in the cloud? In my case, us-west1 is the assigned region.

--runtime dotnet6

Select the runtime to run this function with, since dotnet6 is the most recent LTS release at the time of writing, it makes sense to select it.

--trigger-http

Let GCP know that you want this function to be invoked via HTTP (rather than an Event like those from storage, firestore, or pub/sub)

--allow-unauthenticated

In this case you are not using anything related to IAM access within the gcloud network so we'll keep it simple and allow anyone to hit our endpoint

--entry-point MyFunction.Function

This is the "full namespace path" to the class that implements the IHttpFunction interface it doesn't have to me named Function but for our purposes it can stay like that.

--gen2

This is not listed here but I will mention it anyways because the following screenshot is using gcloud functions gen2 so your screen might be different than mine, but gen2 functions are still in preview so take it with a grain of salt.

If all went well you should see a screen like this once you selected your function in the gcloud console

You can monitor logs and also see what the function answers from there.

Next Steps

Great! hopefully the process of creating a new google cloud function, developing one and finally deploying it, I think in a best case scenario you are likely doing the full process in around 30 minutes just because the gcloud cli takes a lot of time to install 🤣.

But things in real life are not always that simple when it comes to projects, so are there other things worth having in mind? Yes let's see

NuGet dependencies

Since GCloud functions run in a controlled environment, they use conventions for deployments and other stuff if you are using a package manager like paket you may need to fall back to NuGet because the deployment process can't be customized as far as I know, so keep that in mind.

Other than that you can use dotnet add package My.Dependency --version 1.10.0 normally and dependencies install just right.

Project References

Referencing other projects like a shared library that has core types, validations and other business rules sometimes is a must because this code could be used by different projects in an organization this can prove problematic when you need to deploy something because your project structure now contains more than one project. Example:

README.md
src/
  Lib/
    ...
    Types.fs
    Lib.fsproj
  ProjectA/
    ...
    ProjectA.fsproj
  FunctionProject/
    Function.fs
    FunctionProject.fsproj

The idea now would be to deploy from src rather than from src/FunctionProject but if you do that just like that your project won't work as it won't be able to find Lib/Lib.fsproj which is not great, you have to change your deployment command and add the following

gcloud functions deploy my-function-name \
... other arguments ...
--set-build-env-vars=GOOGLE_BUILDABLE=FunctionProject

--set-build-env-vars=GOOGLE_BUILDABLE=FunctionProject

If you set this env var GOOGLE_BUILDABLE and point it to the directory of the project you want to build (that has project references) if will ensure to grab the sources if the current directory and build that project in the cloud to ensure it has what it needs to build correctly (You can find more about it in this document).

.gcloudignore and .gitignore

Don't forget to include both of these files otherwise you will end up uploading the whole sources + build artifacts to gcloud which is dead space you don't want to pay for!
An example of .gcloudignore

# let gcloiud ignore this file 😅
.gcloudignore

# If you would like to upload your .git directory, .gitignore file or files
# from your .gitignore file, remove the corresponding line
# below:
.git
.gitignore

node_modules
# include gitignore contents at this point
#!include:.gitignore

# Ensure the production appsettings is there
!appsettings.Production.json
# ignore other appsetting files

appsettings.*.json
# ... the rest of your ignores for gcloud ...

the .gitignore file can be created using dotnet new gitignore and both files complement each other (they must be side by side).

Working with GCLoud APIs with Auth

Some APIs like firestore, require you to have a set of credentials available in the environment, for the SDK to make authenticated requests to the GCP API, we can simplify by generating the default project credentials

gcloud auth application-default login

This will generate a set of credentials based on the default project your gcloud CLI is currently running

Linux, macOS: $HOME/.config/gcloud/application_default_credentials.json
Windows: %APPDATA%\gcloud\application_default_credentials.json

NOTE: Please ensure that your default project is not a PRODUCTION one! otherwise you may end up developing with the wrong data.
More info about this in the documentation.

The good

I think the dotnet team in google cloud has nailed the experience for the most part, it is simple it follows what one would expect from dotnet-land libraries adding a whole set of functions that talk to each other via gcloud pub/sub + http functions can be a powerful combo for serverless, and the free tier is very generous.

F# is not the only supported language of course you can also write functions in C# and VB, and guess what? they all have the same examples in the dotnet cloud functions framework yes including F# and VB isn't that crazy!?
...Once again third-party companies show that you can support template for languages other than C# and that is a very welcome thing from me I love to see that you get to decide what do tool do you want to use.

The bad

The documentation is sometimes a little too vague, you have to jump from section to section in hopes to find what you're looking for and just to be able to find it but most likely with C# samples, if you're a VB or an F# dev, then you have to have that mental overhead of translating that code from C# to VB or F# which is not desirable by any means, however I found out that the most important bits of information were in the GitHub markdown files rather than in the gcloud documentation. Arguably, this is because dotnet is basically a recent addition and probably most of the work and efforts were directed into provide a smooth developer experience and filling the gaps here and there when it comes to the docs.

The ugly

This is not a problem of functions per-se more like a gcloud libraries problem, most of the libraries do have certain preference for C# based designs, that means that in cases like firestore you will have to create classes rather than records, that or if you're using just primitives, records with CLIMutable attribute... You can't win them all I guess regardless, I think that's something we can live with as F# class and other OOP features support is great as well, it simply isn't that common but is not the end of the world!

Demo project

I made a sample project that you can use as a reference and explore that goes a little further than the hello world project style (not too far though)

https://github.com/AngelMunoz/FsFediverseArchive

In this project you will be able to see a few things

A Shared library

that contains types, and Thoth.Json encoders/decoders to have a unified API for json serialization/deserialization

An Http Function

that works as a webhook for one of the social media websites I'm part of

An Event function

that gets triggered when a Pub/Sub topic is fired (from the webhook function)

An Http Function

that shows the public notes and replies I've made or received, these notes were saved in firestore in the event function

While it's not the most complex project you'll ever see

You can see the last function in action in this website: https://fediverse.tunaxor.me

Closing thoughts

Once again F# proves that it can be a powerful tool that is not necessarily tied to run specifically with other Microsoft products like Windows or Azure. If you are in a situation that for some reason you have to run serverless in google cloud, don't fret! F# is there to help you if you need it!

Also making the FsFediverseArchive project made me realize that cloud, serverless and projects of a similar theme are very complex in nature, when your things are local everything works just fine and dandy, but when things get to the cloud... That is not always the case there is confusion, missing logs, code behaving weird and no obvious root cause... But all in all, things can be done and there's certain level of testing and integration with emulators and such tooling that can help so the road may be dark, but there's almost always a light at the end that guides us.

So, what do you think? Please give it a shot and let me know if the process is as simple and as smooth as I felt it was when I did it for the first time, it would be nice to hear where are the gotchas and issues so we can help each other out there :)

You know where to find me!

@angelmunoz@misskey.cloud - Fediverse presence (like mastodon).
@angel_d_munoz - We'll take the beatings until the ship sinks or if we get bored.

Targeting Node, Bun and Deno With F#

Angel Daniel Munoz Gonzalez — Wed, 13 Jul 2022 17:14:12 +0000

Hello folks, here we are once again with more F#, this time we'll be talking about how can we use the fable compiler to target bun.sh and deno.land.

As you may (or not) know by now if you have read some of my older posts fable lets you compile your F# code into modern web standards JavaScript this has a lot of advantages for modern runtimes like bun/deno which accept ES modules by default that means you don't need to further process your compiled JS code if not required it should just work!

What is node, deno, and bun?

Over the past decade the JavaScript ecosystem grew exponentially and innovated in many areas that were missing for JavaScript, it allowed the language to modernize and to enable tooling for web applications as well as servers, people found out that sometimes it makes sense to be able to share the code that runs in the browser with the one that runs on the server, node, deno and bun precisely allow you to do that, they are JavaScript runtimes built on top of web browser engines like V8 (chromium) and WebKit (safari) although the server code is different from the client, there is always logic that can be shared between both parties be it validation, workflow execution and other cool stuff.

nodejs

Until today... it is still the most used runtime to deploy server or desktop JavaScript it builds itself on top of chromium's V8 engine to power JavaScript code in a runtime similar yet different to the browser.

When node was getting started the JavaScript landscape was vastly different but node provided some niceties over browser JavaScript at the time, most notably for me the notion of modules, the format called commonjs caught the attention of many people who wanted to prove how applications were built there were other module systems at the time, amd, umd, system, etc but no one had a definitive solution, browserify was then built, webpack came to the scene, and a lot of tooling after (including Typescript, Babel, ES2015, and other niceties) here we are today, the node ecosystem is a beast on its own and with the support to ESModules the ecosystem is finally in the transition to a more web standards code which can allow better source code sharing among the browser and node itself.

deno.land

As per the words taken from deno's landing page:

Deno is a simple, modern and secure runtime for JavaScript, TypeScript, and WebAssembly that uses V8 and is built in Rust.

Provides web platform functionality and adopts web platform standards.

Secure by default. No file, network, or environment access, unless explicitly enabled.

Supports TypeScript out of the box.

Ships only a single executable file.

Has built-in development tooling like a dependency inspector (deno info) and a code formatter (deno fmt).

Has a set of reviewed (audited) standard modules that are guaranteed to work with Deno: deno.land/std.

Deno (which is built by the same person who initially built node) is basically another take to node but with different philosophies in some areas, some of the most notable and already mentioned are typescript support out of the box, it also uses V8 and is built with rust. Unlike node, deno doesn't have package manager, rather than that deno leverages web standards where it can and in this case it uses URL imports in ESModules to import files and import maps to keep bare modules intact, this pairs nicely with CDNs like jspm, jsdelivr, skypack and deno's cdn as well.

Bun.sh

Bun is the new player in the game and oh boi... what a player it is!

Bun is a fast all-in-one JavaScript runtime
Bundle, transpile, install and run JavaScript & TypeScript projects — all in Bun.

Bun is a new JavaScript runtime with a native bundler, transpiler, task runner and npm client built-in.

Bun aims to be compatible with node where it can, as well as being web standards driven (like deno) but it also takes lessons from the JavaScript ecosystem and tries to provide performant and efficient tooling it's like if you combined rollup/esbuild/npm/pnpm/yarn all in one.

One important bit is that Bun implements the node resolution algorithm which helps a lot bringing the existing node ecosystem into bun basically almost out of the box, in fact one of its advertising features is that you can run Next.js projects within bun without a hassle.

Also unlike deno and node, Bun preferred to use WebKit instead of V8 which seems to be faster in bun's benchmarks and well it is a very interesting prospect when you can tell folks "Hey! do tou want to make your node faster? Just run it in bun!"

Will node usage decline?

Now the creation of bun, and deno doesn't mean that node is going to die anytime soon, the idea alone is laughable. While these projects aim to solve similar problems, It depends how each project's developer audience uses them, that will make these projects favor more, less or different use cases.

Think about it for the moment, just think how many frameworks are out there yet most of then co-exist naturally and help each other out to improve, thankfully creating a JS runtime isn't as easy as writing yet another framework 🤣.

For us Developers though it adds more choices on the table, and that's good competition drives innovation. Given how each runtime relies more on web standards these innovations may end up in the standards and benefit everyone at the same time.

It also opens the possibility that code you write may be as agnostic as possible and run without modifications in different runtimes.

Getting back to fsharp

Now what does this mean for the F# folks?

Depending on how you use F# it might not mean anything at all or it might mean leveraging the type safety and the power of F# to write safe code that will perform well in a multitude of runtimes be it lambda functions, web workers like cloudflare's, or simply leverage the excellent F# tooling to improve your codebase and take advantage of the well supported compilation JavaScript target.

We will use a simple console application for this case.

Note: keep in mind that you should install node, deno, or bun depending which one you want to target I'll show the three runtimes but all of them are optional!

dotnet new console -lang F# -o fs-sample && cd fs-sample
dotnet new tool-manifest
dotnet tool install fable

# Let's built the app right away just to test it

dotnet fable -o dist

These commands should create and build, and compile JavaScript from the F# console application
inside the dist/Program.js file you will find a similar output to this:

import {
  printf,
  toConsole,
} from "./fable_modules/fable-library.3.7.16/String.js";

toConsole(printf("Hello from F#"));

You can run this file in the standard means of your runtime

Node: node dist/Program.js

Bun: bun dist/Program.js

Deno: deno run dist/Program.js

Note: node requires a package.json file with the property "type": "module" to run without issues

To add that just run npm init -y and add said property

At this point I can tell you:

"That's it, that's all you need to target JavaScript runtimes with F#"

Hopefully this is a reminder that Fable just outputs JavaScript , you can use the plain JavaScript as is in the runtimes that support ES2015 (and a few newer features) without the need for extra tooling like bundlers, and transpilers or similar tooling and as I've said before on other posts "Wherever Web Standards JavaScript runs, F# code will run as well"

There's a cool feature from fable when you use an [<EntryPoint>] attribute, let's change the Program.fs code to the following

[<EntryPoint>]
let main argv =
    printf "%A" argv
    0

after running once again dotnet fable -o dist the compiled output looks like this

import {
  printf,
  toConsole,
} from "./fable_modules/fable-library.3.7.16/String.js";

(function (argv) {
  toConsole(printf("%A"))(argv);
  return 0;
})(typeof process === "object" ? process.argv.slice(2) : []);

You can run this file in the standard means of your runtime

Node: node dist/Program.js -- -a --b=c outputs: --,-a,--b=c

Bun: bun dist/Program.js -- -a --b=c outputs: -a,-b=c

Deno: deno run dist/Program.js -- -a --b=c outputs:

Deno doesn't output anything at all, and that's because Deno doesn't use process.argv like node and bun but rather Deno.args so that's one of the few differences you will find, also bun requires to escape the arguments via -- otherwise it tries to parse them as if they were bun's cli arguments.

This entry point function might be useful for you depending what are you targeting and if you are looking forward to use the program's cli arguments.

Packages

For Node and Bun the package story is the same, just run npm/pnpm/yarn/bun install and once packages are downloaded just run things with bun, although keep in mind that if you're calling a CLI tool that internally calls Node, it won't run in bun but node.

for Deno the story is slightly different, you can use an import map like this:

{
  "imports": {
    "urlpattern-polyfill": "https://cdn.skypack.dev/pin/urlpattern-polyfill@v5.0.3-5dMKTgPBkStj8a3hiMD2/mode=imports,min/optimized/urlpattern-polyfill.js",
    "http": "https://deno.land/std@0.147.0/http/server.ts"
  }
}

which in turn allows you to do this in deno

import "urlpattern-polyfill";
// or
import { serve } from "http";

while these are not "packages" like the node/bun ones, they behave in the same way, deno applies cache techniques to allow offline usage as well so you don't depend on internet to import your dependencies at runtime.

Does that import map thing feel familiar? well maybe I spoke about that a few months ago when I wrote about a project of mine (Perla) which uses import maps to allow you to write Single Page Applications without node installed!

Fable.Node Fable.Bun, Fable.Deno

What about specific APIs for node, deno and bun?

Well you're in luck if you want to target node because Fable.Node has been out for a while and since node is the most popular runtime in this list you'll even find bindings to projects like express via the Glutinum project which are high quality bindings with test suites to ensure things don't just break!

If you want the newer runtimes though... you'll have to wait for me to release the bindings for fable.bun and fable.deno that will allow you to target Bun and Deno's APIs

Now let's move to something more exciting than just a console

Enter the Bix Experiment

With Both Bun and Deno out I really wanted to see if I could make something to test them out both runtimes offer HTTP servers that work with Request and Response which were introduced with the Fetch API in the browsers a few years ago

I have always wanted to make a JavaScript framework just to be part of the meme and as well to contribute back what the internet has given me for free over the years, this is where Bix comes in

Bix is a micro-framework designed with F# in mind and that runs on both Deno and Bun!
In theory it also should even run in a service worker! (intercepting fetch requests) although I haven't tested that yet.
It offers a general purpose handler that coupled with a set of route definitions it can bring a Giraffe/Saturn like framework to life in JavaScript runtimes which is incredibly awesome! useful? maybe not 😅, but awesome for me indeed. Let's see some code:

open Bix
open Bix.Types
open Bix.Handlers
open Bix.Router

open Bix.Bun

let checkCredentials: HttpHandler =
    fun next ctx ->
        let req: Request = ctx.Request
        let bearer = req.headers.get "Authorization" |> Option.ofObj
        // dummy handler
        match bearer with
        | None -> (setStatusCode (401) >=> sendText "Not Authorized") next ctx
        | Some token -> next ctx

let routes =
    Router.Empty
    // helper functions to define routes
    |> Router.get ("/", fun next ctx -> sendText "Hello, World!" next ctx)
    |> Router.get ("/posts/:slug", fun next ctx ->
        promise { // promise based handlers are supported
            let slug = ctx.PathParams "slug"
            let! post = Database.find slug // database from somewhere
            let! html = Views.renderPost post // views from somewhere
            return! sendHtml html next ctx
        }
    )
    |> Router.get ("/json", fun next ctx ->
        let content = {| name = "Bix Server!"; Date = System.DateTime.Now |}
        sendJson content next ctx
    )
    // route composition a'la suave/giraffe is supported
    |> Router.get ("/protected", (checkCredentials >=> (fun next ctx -> sendText "I'm protected!" next ctx)))

let server =
    Server.Empty
    |> Server.withRouter routes
    |> Server.withDevelopment true
    |> Server.withPort 5000
    |> Server.run

let mode =
    if server.development then
        "Development"
    else
        "Production"

printfn $"{mode} Server started at {server.hostname}"

For Deno it isn't much different

// open the Bix.Deno module
open Bix.Deno

Server.Empty
// you can use the same routes without changes!
|> Server.withRouter routes
|> Server.withDevelopment true
|> Server.withPort 5000
// the run function returns a promise in deno due how the std HTTP server works
|> Server.run
|> Promise.start

Bix provides some basic http handlers like returning json responses, set status codes, send html, and even send html files.

The most amazing (at least for me) about this is that... 90% - 95% of micro-framework code is shared code between both runtimes, the only thing that really changes is the run and the internal Request handler function which need to be different because of how the servers are started in both runtimes and that they are different in some areas, so we need to abstract some of these details away in order to make the rest of the framework re-usable between platforms.

If there's a Request/Response http server for node, be sure that it can be supported as well

If this peeks your interest then visit the project

AngelMunoz / fable-bun

Fable bindings for Bun.sh

Bun.sh + Fable

This is a small repository that adds Fable bindings for Bun.sh, these are very minimal and only add a few convenience methods for Bun's request/response impl consumption, but the rest of the Bun API should be included eventually, feel free to contribute any bindings that are missing for you!

Where are the other samples?

They have been moved to their corresponding repositories, feel free to check them out

Fable.Deno

Please visit fable-deno

Fable.URLPattern

Please visit fable-urlpattern

Bix

Please visit Bix

View on GitHub

There are slightly more complete samples there (including server side rendered endpoint using Feliz.ViewEngine) and give it a go, I'll try to start releasing the first previews over the next days/week but Feedback is super important here.

Final Thoughts

Fable is a very powerful tool to make F# code, style and conciseness available almost everywhere via JavaScript (and soon other languages), I'm truly excited to see how bun, deno and node will grow together and improve to become really good assets in the software developer toolbelt.

Creating a framework was also fun, I can finally call myself a JavaScript developer now that I've built my own framework 😅 /s if you want to know more about how Bix internals work and how is everything abstracted to just work in both deno and bun, feel free to let me know in the comments below or on twitter!

I'd be glad to write another piece specifically for that purpose

Exploring The F# Frontend Landscape

Angel Daniel Munoz Gonzalez — Tue, 24 May 2022 01:04:17 +0000

Hello everyone it's been a while!
Today we will talk about what is the current frontend landscape of Frontend development for the F# ecosystem. Over the last few years Fable has become quite capable and more bindings have been released.

Disclaimer: The F# Ecosystem Is Stable you don't need to jump ship to the next thing or anything like that! Just because there are options doesn't mean you need to ditch out what you know and learn something new. Think of this as as restaurant menu: There are options but ultimately it is your choice which one you pick and you can even decide "I don't want to eat here" it's completely fine. No kittens will die and the world won't stop so if you see a lot of options I'd suggest you to not feel pressured to choose!

When it comes to the Frontend landscape for F# we have three main roads:

Fable
WebSharper
Web Assembly

These have different approaches to the frontend landscape but ultimately do the same thing Websites some of those options allow you to go for server side rendering and others allow you to go for single page applications.

Fable

In this Section:

High Profile:

Feliz

Fable.Lit

Sutil

Low Profile

Fable.Svelte

Feliz.Snabdom

Fable Next:

Feliz.Solid

Fable is an F# to JavaScript compiler (like Typescript compiles to JavaScript) it is near its fourth major release and has a very very strong ecosystem based around React.js although, in recent times other options have become available.

Why Fable and who benefits most from it?

Fable is meant for those developers that need to work with the JavaScript ecosystem or that want to benefit from it, it would be unwise to negate the number of good libraries and existing solutions that have been born in it.

Fable rather than negate that JavaScript exists, builds on top of it and gives you the most flexible option when it comes to frontend development in F#.
You keep using the safety of F# (most of the time) and when necessary you can fall back to JavaScript interoperation (via emit, imports or the dynamic operator) or even JavaScript itself to fill the missing gaps that could be there.

The bad thing is that the JavaScript ecosystem is so vast and has grown so much over the years it might be possible that if you want X library there won't be bindings for it. After all the F# developer numbers are way too low compared so we don't have the programmer power to be on equal grounds.

Writing bindings isn't complex but it can take quite some time from your development efforts if the libraries you're targeting are too big, this cost is only paid once though, when the bindings are complete is just a matter of maintaining the bindings up to date (which isn't too big of a chore).

That being said! Let's dive into Fable's options:

Feliz

This is by far the most popular library in the F# frontend ecosystem, This library took existing lessons from Fable React and improved its DSL (Domain Specific Language) to be more concise and less verbose than existing alternatives. It also took a different approach when it came to React applications, it steered slightly away from what was very popular at the time the Elmish architecture (also known as MVU) and provided an API that is as close as possible to React itself.

Feliz introduced hooks which helped to simplify state management in some cases, as well as reduce the verbosity MVU can get when applications grow, since it was compatible with previous fable-react bindings it wasn't a big of an effort to migrate to Feliz.

Your typical Feliz UI component looks like this

[<ReactComponent>]
let Counter() =
    let (count, setCount) = React.useState(0)
    Html.div [
        Html.button [
            prop.style [ style.marginRight 5 ]
            prop.onClick (fun _ -> setCount(count + 1))
            prop.text "Increment"
        ]

        Html.button [
            prop.style [ style.marginLeft 5 ]
            prop.onClick (fun _ -> setCount(count - 1))
            prop.text "Decrement"
        ]

        Html.h1 count
    ]

Its DSL is based on a list of properties for each kind of HTML tag, you can build reusable pieces of UI by just writing functions and other components given React's nature it is clear why Feliz is the most used, it simply fits with the F# mind, data and functions!

Feliz supports MVU via the Feliz.UseElmish package

type Msg =
    | Increment
    | Decrement

type State = { Count : int }

let init() = { Count = 0 }, Cmd.none

let update msg state =
    match msg with
    | Increment -> { state with Count = state.Count + 1 }, Cmd.none
    | Decrement -> { state with Count = state.Count - 1 }, Cmd.none

[<ReactComponent>]
let Counter() =
    let state, dispatch = React.useElmish(init, update, [| |])
    Html.div [
        Html.h1 state.Count
        Html.button [
            prop.text "Increment"
            prop.onClick (fun _ -> dispatch Increment)
        ]

        Html.button [
            prop.text "Decrement"
            prop.onClick (fun _ -> dispatch Decrement)
        ]
    ]

// somewhere else
ReactDOM.render(Counter(), document.getElementById "feliz-app")

If you're looking to dive into Frontend F# then Feliz is a solid choice you will learn what most of the F# FE devs use and it is arguably the best choice today within the Fable realm.

The downsides of Feliz are the downsides of using React, since Feliz is a 1-1 binding over React you get the same problems React devs have, weird rules for hooks, easy to mistakenly provoke re-renders, and effects are still not entirely figured out in the react ecosystem and you have to keep manually what things need to re-render your UI. React uses Virtual DOM which was a performant way to render UI's in the early 2010's it is not the case anymore where browsers have caught up in performance and it turns out that in performance critical situations the VDOM diffing from React is just overhead rather than an advantage. For your average website, this shouldn't be a concern though but it is worth mentioning it.

Fable.Lit

This is my personal favorite one when it comes to Fable options, Fable.Lit builds on top of lit.dev which is a web component library built on web standards. It brings performant straightforward and inter-framework compatible components to the F# FE landscape since Lit works with DOM elements themselves rather than abstractions you can manipulate component instances like if you were doing vanilla JavaScript except that you can use the F# safety for that.

In Fable.Lit rather than building an F# DSL (we tried) we use a string-based alternative which is closed to the HTML you know and love, this also helps a lot when you have to consume web components like those from shoelace.style, fast.design, adobe spectrum components, and more, this will be a very important and big point over the next few years now that web components have taken off finally with major companies like Microsoft, Salesforce, Github, Adobe and more are using them.

Here's two ways you can use Fable.Lit Components

[<HookComponent>]
let functionCounter(initial: int) =
    let value, setValue = Hook.useState initial
    html
        $"""
        <!-- @<event name> means attach a handler to this event -->
        <sl-button outline variant="neutral" @click={fun _ -> setValue value + 1}>Increment</sl-button>
        <sl-button outline variant="neutral" @click={fun _ -> setValue value - 1}>Decrement</sl-button>
        <sl-badge>Count: {value}</sl-badge>
        """

[<LitElement("my-custom-element")>]
let MyCustomElement() =
    let host, props =
        LitElement.init(fun config ->
            config.props = {| initial = Prop.Of(0, attribute = "initial") |}
            // defaults to true if not set
            config.useShadowDom <- false
        )
    let value, setValue = Hook.useState props.initial.Value

    html
        $"""
        <sl-button outline variant="neutral" @click={fun _ -> setValue value + 1}>Increment</sl-button>
        <sl-button outline variant="neutral" @click={fun _ -> setValue value - 1}>Decrement</sl-button>
        <sl-badge>Count: {value}</sl-badge>
        """

// using both somewhere
html
    $"""
    Function Component:
    {functionCounter 20}
    <br>
    <!-- .initial means bind to "initial" property -->
    <my-custom-element .initial={10}></my-custom-element>
    """

First of all if you are wondering "ugh strings", "that doesn't give any highlight", "the holes are not typed" I have a few words for that:

Interpolated strings aren't as flexible as JS tagged templates so in .NET we fallback to using just objects and we lose type safety
We actually have two extensions to give you the ability to highlight these F# strings
- Highlight HTML/SQL templates in F#
- Html for F# (Lit Template)
- For Rider and other editors no-one has tried to build a plugin as far as I know

Here's the thing (and the main reason I like it):

Did we have to write bindings for sl-button?
Would we need to write bindings for any other custom element/web component?

The answer for both is No, we still have write bindings for the JS parts of the libraries we might use but when it comes to custom elements and other standard HTML elements we don't need to do anything, that includes it's attributes/properties.

The tradeoff is precisely that we gain access to a vast array of libraries out there but we lose some type safety when you describe your UIs.

And before I forget it, Fable.Lit also supports the Elmish architecture

type Msg =
    | Increment
    | Decrement

type State = { Count : int }

let init() = { Count = 0 }, Cmd.none

let update msg state =
    match msg with
    | Increment -> { state with Count = state.Count + 1 }, Cmd.none
    | Decrement -> { state with Count = state.Count - 1 }, Cmd.none

[<HookComponent>]
let Counter() =
    let model, dispatch = Hook.useElmish(init, update)
    html $"""
        <h1>{model.Count}</h1>
        <button @click={fun _ -> dispatch Increment}>Increment</button>
        <button @click={fun _ -> dispatch Decrement}>Decrement</button>
    """

Lit itself is a pretty safe bet is a solid choice and built on web standards so it's very likely to have a really long life (it first came out around 2013-2014 as polymer if you ever head of that) and has adjusted and improved together with web browsers

Fable.Lit on the other hand is fairly new and the bindings may still have some areas where we can improve but the technology underneath is already production ready.

Sutil

When I first learned about Sutil I fell in love with it, it brought a lot of concepts from Svelte to the F# frontend landscape and while it's development has been slower than most it has some really interesting choices which can fit some minds better than the other alternatives.

Sutil is the first pure F# framework for the frontend that we have, it doesn't have bindings to any framework because it's just F#.

Sutil uses a Feliz variation of a DSL called Feliz.Engine so you get the F# type safety you know and love with reactive UI elements.
Sutil functions run only once and then everything is static unless you choose to be reactive via stores. This helps in regards performance and updates are only applied where things change.

In a similar fashion to Fable.Li, Sutil works with plain DOM elements which make it compatible with Web Components as well, it also provides features to write web components with it!

If you really like the programming model of svelte or rxjs (observables) then Sutil is something to look after, it also has built-in animations, chrome dev tools, and other nice features.

Here's how Sutil looks like

// functions can be separated from UI logic
// with some thought we can make these very reusable
// and even UI agnostic
let increment (counter: IStore<int>) =
    counter
    |> Store.modify (fun count -> count + 1)

let decrement (counter: IStore<int>) =
    counter
    |> Store.modify (fun count -> count - 1)

let view() =
    let counter = Store.make 0

    Html.div [
        // make this element reactive
        Bind.el(counter, fun count -> Html.p $"Counter: {count}")
        Html.div [
            // using stablished HTML elements
            Html.button [
                onClick (fun _ -> increment counter ) []
                text "Increment"
            ]
            // interoperation with custom elements
            Html.custom("sl-button", [
                Attr.custom("variation", "neutral")
                onClick (fun _ -> decrement counter) []
                text "Decrement"
            ])
        ]
    ]

As mentioned before whenever we mount/call view it will render once and when stores/observables emit a new value only the reactive parts will update this allows for fine grained updates

Sutil Also offers MVU support:

type Msg =
    | Increment
    | Decrement

type State = { Count : int }

let init() = { Count = 0 }, Cmd.none

let update msg state =
    match msg with
    | Increment -> { state with Count = state.Count + 1 }, Cmd.none
    | Decrement -> { state with Count = state.Count - 1 }, Cmd.none

let Counter() =
    let model, dispatch = () |> Store.makeElmishSimple init update ignore
    Html.div [
        disposeOnUnmount [ model ]
        Bind.fragment (model |> Store.map getCounter) <| fun n ->
            Html.h1 [ text $"Counter = {n}" ]

        Html.div [
            Html.button [
                onClick (fun _ -> dispatch Decrement) []
                text "-"
            ]

            Html.button [
                onClick (fun _ -> dispatch Increment) []
                text "+"
            ]
        ]]

Part of the disadvantages in Sutil is the slow updates although David recently mentioned that he will be working on it, more maintainers would be welcome.
Also it has been in beta for a while so it might not be so ready for prime time.
More testing from real users would be nice because at least on my relatively limited testing it feels just as solid as any of the previous choices.

Feliz.Engine

Once the high profile projects have been mentioned one project that is worth mentioning and one you can use if you plan to ever bring another framework to the F# space is Feliz.Engine

Feliz.Engine is a library that defines in a standard way F# DSLs for Elements, Attributes and Styles. It was born out of the Original Feliz DSL but modified slightly to fit a more general use case.

Sutil, Feliz.Solid and Feliz.Snabdom use Feliz.Engine under the hood you could also use it to bring others to the fold!

This project deserves a mention just for it's potential to bring more to the ecosystem (and to not confuse it with Feliz itself)

Fable.Svelte

These bindings were a way to make F# work with .svelte files. I don't have much to say about this other than it exists and you could take a look if you want but it's usage is fairly low.

For this one I don't think is a good choice for your next serious project, maybe for experiments here and there but given it's low usage there might be some bugs not found just yet in the way, Sutil would be a better choice if you like Svelte-like way of doing UIs

Svelte of course is rock solid as a choice and is one of the most popular JS frameworks out there, the problem lies on how mature are the bindings and how battle tested they are

Feliz.Snabdom

Using Feliz.Engine comes Feliz.Snabdom as well snabdom has a virtual dom implementation but deals with DOM elements rather than abstract over them (like react) this gives you more wiggle room to interoperate with third party components. it provides life cycle hooks, lazy loaded elements and other features.

I'm not fan of virtual dom myself so I haven't really tried this much more than just a few examples at the same time I'm not sure of the maturity of the bindings, although snabdom has been out for years and has been used by thousands of devs the concerns lie in how portable the code is + how mature the bindings could be.

Fable Next!

These new options are coming hot from the oven and paint a bright future for Fable integrations on the Frontend ecosystem!

Fable 4 (snake island) is going to bring JSX compilation, meaning that frameworks that use JSX as their DSL and building blocks will have an even easier time integrating, this support will come to Feliz.Engine as well this means a couple of things

Stable API for the F# side (Feliz.Engine)
Broad Target of UI frameworks by just configuring the packages you want to use (be it solidjs, vue jsx, inferno, preact etc)
Easier migration paths between F# <-> JS

Given how JSX is still a compilation step you can always fallback to manual JSX and continue from/to JSX if needed.

Feliz.Solid

This is an exciting one, [solid.js] has been going up in popularity these days because it is what react could have been

True and Predictable reactivity
No manual dependency tracking
Observable support
No Virtual DOM
Fast and Efficient
Small footprint Library

So if the react model is your thing and you want to avoid many of the react footguns then this is something to keep an eye for

Solid code looks like this:

[<JSX.Component>]
let Counter() =
    let count, setCount = Solid.createSignal(0)
    let doubled() = count() * 2
    let quadrupled() = doubled() * 2

    Html.fragment [
        Html.p $"{count()} * 2 = {doubled()}"
        Html.p $"{doubled()} * 2 = {quadrupled()}"
        Html.br []
        Html.button [
            Attr.className "button"
            Ev.onClick(fun _ -> count() + 1 |> setCount)
            Html.children [
                Html.text $"Click me!"
            ]
        ]
    ]

As you can see it is very similar to Sutil or Feliz.Snabdom and that's because it is using Feliz.Engine as well! while these don't interoperate between themselves easy because each library defines what the DSL actually emits: DOM Elements, Virtual DOM elements they do use the same DSL so learning one it basically teaches you the others as well!

The main disadvantage of this is that is of course new, it only works on Fable 4 (Alpha at the time of writing) and thus should not be considered for your next serious project. Once Fable 4 is released for real then it could be something to really consider and contribute to.

Fable + JSX

If you're thinking "my favorite framework is not in the list" do not worry, writing bindings for Fable has become easier over the years, specially when you take Feliz.Engine into account Fable 4 will bring JSX as well meaning that it could be even simpler to integrate to the JavaScript ecosystem.

Perhaps you like vue, but supporting vue files is too much, perhaps the framework you are using at work supports JSX this has the potential to bring a lot with minimal changes, like Alfonso said

It's like programming against an interface (JSX) instead of an implementation (the compiled JS)

Although he also said there are nuances and likely differences in how each framework and its tooling treats JSX so Feliz.Engine is close to universal but not that universal.

WebSharper

Web sharper has been out for quite some time and has an interesting F# first approach to the UI, WebSharper aims to fulfill the full-stack F# promise hiding away some of the JS details but has some pretty good capabilities when it needs to interoperate with javascript.

Rather than a set of multiple libraries and frameworks WebSharper is a one stop shop all style of framework

A simple Web Sharper Application looks like this:

[<Website>]
let Main =
    Application.SinglePage (fun ctx ->
        Content.Page(
            h1 [] [ text "Hello World!"]
        )
    )

This will tell WebSharper to generate some JavaScript and run it directly on the body of your application.

While WebSharper has a ViewModel strategy it also offers MVU support, for example a counter can look like this

[<JavaScript>]
module Counter =

    type Model = { Counter : int }

    type Message = Increment | Decrement

    let Update (msg: Message) (model: Model) =
        match msg with
        | Increment -> { model with Counter = model.Counter + 1 }
        | Decrement -> { model with Counter = model.Counter - 1 }

    let Render (dispatch: Dispatch<Message>) (model: View<Model>) =
        div [] [
            button [on.click (fun _ _ -> dispatch Decrement)] [text "-"]
            span [] [text (sprintf " %i " model.V.Counter)]
            button [on.click (fun _ _ -> dispatch Increment)] [text "+"]
        ]

    let Main =
        App.CreateSimple { Counter = 0 } Update Render
        |> App.Run
        |> Doc.RunById "main"

or if you prefer HTML

<!-- this is inside the HTML page you're serving -->
<body>
  <button ws-onclick="OnDecrement">-</button>
  <div>${Counter}</div>
  <button ws-onclick="OnIncrement">+</button>
  <script type="text/javascript" src="Content/Counter.min.js"></script>
  <!--[BODY]-->
</body>


[<JavaScript>]
module Client =
    // The templates are loaded from the DOM, so you just can edit index.html
    // and refresh your browser, no need to recompile unless you add or remove holes.
    type MySPA = Template<Snippet.IndexHtml, ClientLoad.FromDocument>

    type Model = int

    type Message =
        | Increment
        | Decrement

    let update msg model =
        match msg with
        | Message.Increment -> model + 1
        | Message.Decrement -> model - 1

    let view =
        let vmodel = Var.Create 0

        let handle msg =
            let model = update msg vmodel.Value

            vmodel.Value <- model

        MySPA()
            .OnIncrement(fun _ -> handle Message.Increment)
            .OnDecrement(fun _ -> handle Message.Decrement)
            .Counter(V(string vmodel.V))
            .Bind()

        fun model ->
            vmodel.Value <- model

    let Main =
        view init

There's a whole website with demos you can try!

WebSharper also offers a reactive model that can be used in exchange of the MVU architecture, the last example could also be simplified to the next example:

[<JavaScript>]
module Client =
    // The templates are loaded from the DOM, so you just can edit index.html
    // and refresh your browser, no need to recompile unless you add or remove holes.
    type MySPA = Template<Snippet.IndexHtml, ClientLoad.FromDocument>
    let counter = Var.Create 0
    let Main =
        MySPA()
            .OnIncrement(fun _ -> counter.Value <- counter.Value + 1)
            .OnDecrement(fun _ -> counter.Value <- counter.Value - 1)
            .Counter(V(string counter.V))
            .Bind()

This reactive style is similar to the new Vue's Composition API so regardless of your choices WebSharper has you covered.

That being said, on my twitter bubble WebSharper is not one of the most popular ones and I'm not entirely aware why my guess is that it tries to hide JavaScript as much as possible to try to stay in F# and that could create some sort of vendor lock in and friction in some cases, this doesn't mean it is a bad choice though if you don't want to build on top of the JavaScript ecosystem that much it looks like solid technology to pick up specially because it offers paid support so this can be a good fit for teams rather than individuals.

If you want to learn more about WebSharper let me know, so I can explore more and dedicate a couple of blog posts to it.

Web Assembly

In this Section:

Bolero

Fun.Blazor

Avalonia.FuncUI

Web Assembly is the newest player in the game and one that is being/will be a true game changer with it comes to web development, just as a taste of it's power you can now use photoshop natively in the browser now, what does that mean for you as a .NET developer?

It means that you can run F# code (or C# if that's your jam) natively on the browser, no intermediary JavaScript that you have to touch and you keep the safety of F#

Why Web Assembly and who benefits most from it?

Web assembly (WASM) is meant for users who want to run native code in the browser, this has a few implications, WebAssembly does not have so far access to DOM and neither a garbage collector, so for WASM apps to work with .NET you need to load a .NET runtime + your application's code. That means that any time your website is visited you have to wait a few seconds while your web app loads the runtime + your code.
Any time that any of these technologies have to they need to share information with the JS world and this can be costly, while you as an App developer don't have to do it manually you still need to be wary of the costs of serialization/deserialization that are made any time you share information with the JS world, be it in form of big UI trees, large amounts/rows of data and similar situations.

That being said, if you can afford these drawbacks then you will be able to enjoy F# safety in all of its glory, no more weird JavaScript emits, or trying to bind an interface to a JavaScript object and hopefully that holds true at runtime. It's just the real deal.

You can leverage the .NET ecosystem when it comes to libraries with all of their patterns and knowledge you already may have. This also means that since you are using .NET you can share logic and data 100% with the server, after all .NET6 libraries (unless they are using OS specific APIs) work on ASP.NET core for the server and WASM, this means no shared folders with tweaked paths and #if FABLE or similar directives it's just the assembly being shared as is.

While you don't need to interact with JavaScript at all, you can do so if you must there are ways to interoperate with functions declared in the global scope or even in JavaScript modules.

So you're not entirely isolated you can interact with the outside world if needed.

DISCLAIMER: Most of these alternatives rely on Blazor which is the product solution offered by Microsoft to tap into WebAssembly with C# as usual F# is not in the roadmap but the community always jumps in to save the day and offer F# devs the experiences they deserve.

Bolero

Bolero is the most stable and mature solution for F# web assembly, it is brought to you by the same devs behind web sharper, in a way it could be the next step in their path to make web applications with F#. Bolero offers most of the functionalities of web sharper but native this time, HTML Templates via a Type Provider, Client Routing with Discriminated unions, F# DSL, MVU.

Your typical Bolero view looks like this


type Model = { value: int }
let initModel = { value = 0 }

type Message = Increment | Decrement
let update message model =
    match message with
    | Increment -> { model with value = model.value + 1 }
    | Decrement -> { model with value = model.value - 1 }

let view model dispatch =
    div {
        button { on.click (fun _ -> dispatch Decrement); "-" }
        string model.value
        button { on.click (fun _ -> dispatch Increment); "+" }
    }

let program =
    Program.mkSimple (fun _ -> initModel) update view

type MyApp() =
    inherit ProgramComponent<Model, Message>()

    override this.Program = program

It is pretty similar to the other MVU samples we've seen so far bolero also offers interoperation with Blazor concepts like external components from third party libraries, remoting (RPC client-server style of communication) and of course Pure F#.

If you liked the approach that WebSharper gave you and you're looking for the next step then bolero will be just what you want you can translate concepts and knowledge from there. The sad part for me is that it doesn't have a reactive style when it comes to handling state MVU is great but on larger applications it just doesn't cut it for me, the nice thing of the bad is that you can create multiple elmish components in your application and use parameters so you don't have a single master Elmish update function and rather each component have it's own state.

Fun.Blazor

This is another abstraction built on top of Blazor, it is the new kid in town and has some very enticing models when it comes to handle state. Fun.Blazor recently put out its version 2.0.0 which adds a bunch of nice things all around, it allows you to create UI's with F# Computation Expressions (CE) in a similar fashion to bolero, it also has the ability to use string templates (much like Fable.Lit) and has some options for routing like a giraffe style router it offers seamless integration with blazor's dependency injection, very useful to interoperate with JavaScript and other Blazor services.

Your typical Fun.Blazor component looks like this:

adaptiview() {
    let count, setCount = cval 0 // changeable value

    h1 { $"Counter: {count}"}

    button {
        onclick (fun _ -> setCount count + 1)
        "Increment"
    }

    button {
        onclick (fun _ -> setCount count - 1)
        "Decrement"
    }
}

Fun.Blazor brings the power of FSharp.Data.Adaptive to allow incremental updates to the view, this package works like excel cells, where one cell may be the source of truth for others, the other cells can recompute values depending on the first cell this allows for performant updates in the UI because only the reactive parts change. This model is very close to Sutil's model as well In fact you can use stores in Fun.Blazor as well

let myComponent() =
    html.comp(fun (hook: IComponentHook) ->
        let counter = hook.UseStore 0
        let double =
            store.Observable
            |> Observable.map(fun n -> n * n)
            |> AVal.ofObservable counter.Current hook.AddDispose

        adaptiview() {
            let! countValue, setCount = counter.WithSetter()
            let! doubleValue = double

            h1 { $"Counter: {countValue}, Double: {doubleValue}"}

            button {
                onclick (fun _ -> setCount countValue + 1)
                "Increment"
            }

            button {
                onclick (fun _ -> setCount countValue - 1)
                "Decrement"
            }
        }
    )

Adaptive views are a concept that I'd love if other frameworks implemented because the reactive model really resonates with me that being said, I know you want to see elmish in action, so I'm pleased to tell you that yes, it supports MVU as well

type Model = { value: int }
let initModel = { value = 0 }

type Message = Increment | Decrement
let update message model =
    match message with
    | Increment -> { model with value = model.value + 1 }
    | Decrement -> { model with value = model.value - 1 }
// using elmish directly
html.elmish (init, update, fun state dispatch ->
    div {
        h1 { $"Count: {state.value}" }
        button {
            onclick (fun _ -> dispatch Increment)
            "Increment"
        }
        button {
            onclick (fun _ -> dispatch Decrement)
            "Decrement"
        }
    }
)

// using elmish with adaptive views
html.comp (fun (hook: IComponentHook) ->
    let state, dispatch = hook.UseElmish(init, update)
    div {
        adaptiview() {
            let! count = state
            h1 { $"Count: {count.value}" }
        }
        button {
            onclick (fun _ -> dispatch Increment)
            "Increment"
        }
        button {
            onclick (fun _ -> dispatch Decrement)
            "Decrement"
        }
    }
)

Fun.Blazor has a lot of potential it is still young it needs more real world usage to validate many of the efforts taken in v2.0.0, although young it feels like a solid option, but keep in mind that just like Sutil it has only one maintainer, so if you like this you should look into contributing to the framework because it feels like really good option.

Avalonia.FuncUI

This one might come as a surprise for many because Avalonia is a Desktop application framework! but as seen in this Avalonia.FuncUI WASM Template it is possible to bring the power of avalonia into the desktop via WASM, The main advantage of Avalonia.FuncUI is that you will be able to share code between browsers, android, ios, mac, linux, and windows.

Avalonia.FuncUI was also recently updated and added this reactive-like model in v0.5.0

Component(fun ctx ->
    let state = ctx.useState 0
    DockPanel.create [
        DockPanel.verticalAlignment VerticalAlignment.Center
        DockPanel.horizontalAlignment HorizontalAlignment.Center
        DockPanel.children [
            TextBlock.create [
                TextBlock.dock Dock.Top
                TextBlock.text (string state.Current)
            ]
            Button.create [
                Button.dock Dock.Bottom
                Button.onClick (fun _ -> state.Current - 1 |> state.Set)
                Button.content "-"
            ]
            Button.create [
                Button.dock Dock.Bottom
                Button.content "+"
                Button.onClick (fun _ -> state.Current + 1 |> state.Set)
            ]
        ]
    ]
)

The concepts of IWritable<'T> and IReadable<'T> work just like adaptive/changeable/stores/observables that we've seen before in sutil/fun.blazor so Avalonia.FuncUI could start becoming a competitor in the Web landscape specially if you already have some desktop app development experience, this is part of the power of WASM in practice in the case of Avalonia.FuncUI WASM you don't really need to know anything of web development to get started, just jump in!

That being said, Avalonia uses Skia to render in a canvas (likely using webgl) so you won't have any kind of DOM nodes to inspect and also as far as I'm aware (and I'd love to be corrected if necessary) you throw accesibility out of the window because of that so assistive technology won't work with this kind of web sites, it also worth noting that as far as I'm aware (at the time of writing) Web support in Avalonia is in beta state so there might be a couple few bugs lurking out there.

MAUI

The elephant in the room here would likely be MAUI because it also has blazor support but I'm going to be very dismissive here and I plead guilty about it because it is a Microsoft product, I'd prefer to Microsoft to step out of the way of its .NET ecosystem and I'd love to better cultivate alternatives like Uno/Avalonia, but whatever right?

Good Luck about F# support
Good Luck to have linux support

Both things can be done with Avalonia without any major issues, also all of the other alternatives discussed here can be developed on any of the three major operating systems heck even from your Raspberry Pi 4 that's not something I'd expect in MAUI soon.

Takeaways

That being said the F# Frontend Landscape is not that big it might feel confusing with all the tweets and news going all over the place but thankfully as most things F#: We are pretty much settled how we use things and even if there is variety most alternatives can live together in one way or another.

Here's the tl;dr:

Use Fable if:

You want to take advantage of the JavaScript Ecosystem
You want to have the possibility to migrate away from F# if necessary
You want the lowest amount of kb of resources to the browser.
You must interact with JavaScript on a heavy basis
You Like and want to use React or Lit or Vanilla (Sutil)

Don't use Fable if:

You really dislike JS
You want true type safety
You can afford go vanilla F# (i.e. not use most of the JS ecosystem)
You don't want to learn or deal with the JavaScript Tooling

Use WebSharper if:

You don't mind about going F# first JS second
You want type safe HTML via type providers
You want to blur the lines between client side F# and server side F#
You don't care too much of the toolchain and only care about final deployable assets

Don't use WebSharper if:

You need to literally make manual js files and adjustments to the compiling toolchain
You need a more JavaScript oriented application
You need to build on top of the existing node tooling
You care about an extra runtime for your application (around 8kb)

Use Web Assembly if:

You want to run native F# in the browser not a fake one
You want to leverage the .NET ecosystem
You want to enjoy .NET tooling to publish, distribute and build your F#
You want to share code between Desktop, Server, and Mobile (like Avalonia will allow you)

Don't use Web Assembly if:

You don't want to ship heavy websites (even if there's trimming support for some libs)
You need low TTI (time to interaction) and TFP (Time to Fist Painting)
You need a more mature ecosystem
You need heavy JS interop

Personal Opinion

No one asked for it, and no one should because my opinion shouldn't have any weight on your decision making.
That being said...

My personal top is:

Fable.Lit
Sutil - Fun.Blazor
Feliz.Solid?

The main reason is that Fable.Lit checks the boxes when it comes to web standards and I'm primarily a frontend developer and React is just not my thing mainly due to it's focus on hooks which in the case of React they might make sense but are too magical and very prone to errors and performance issues if badly used (I'm looking at you useFootGun, I mean useEffect)

Sutil comes in second because of it is extremely awesome to have a pure F# framework that also offers a reactive state management model it simply fits my mental model of doing websites.

Fun.Blazor comes swiftly on second place as well for the Tie because it takes the same concepts sutil uses for state management and takes it a step further

Feliz.Solid comes in third because it also offers a reactive model that is likely going to replace React in a lot of places and codebases in the future. It doesn't suffer of the same problems React has and its future looks Bright, its author was recently hired (at the time of writing) at Netlify so it can only go up from here while the Feliz integration matures.

Conclusion

So there you have it I hope this post sheds some light on what the current state of F# frontend is and what you should take into account if you want to choose one or the other alternatives we have.

Ultimately you should not be pressured to chose right. F# solutions even if they are not "mature" are pretty solid, after all that's the main reason we chose F# to either work with or have fun (sometimes both) you should avoid one of these alternatives if you truly have reasons not to pick it otherwise it's likely going to work your needs.

These frameworks are excellent work of members of the F# community even if they look young or are in beta these tools are extremely well done and are far more capable than what you would think when you hear those words give them a try give feedback to its authors and remember not everything is React or derivatives you have choices today :)

Until the next one, don't forget to leave your comments and questions if needed!

F# Bits: Http Requests

Angel Daniel Munoz Gonzalez — Mon, 11 Apr 2022 03:40:21 +0000

Hello everyone!

I have the pleasure to announce you the pilot of a new series I have in mind, this time it will be video based.

Feel free to also watch it on the YouTube channel I'll try to post on both sites but it's very likely that YouTube videos get posted first.

In case you want to learn more about the topic above, feel free to check this blog post

Making Http Requests in F#

Angel Daniel Munoz Gonzalez ・ Mar 15 '21

#fsharp #dotnet #samples #http

In any case feel free to drop some feedback and if you are interested in more short (or longer) videos like this.

Have an amazing week!

F# and WebAssembly

Angel Daniel Munoz Gonzalez — Fri, 28 Jan 2022 19:39:24 +0000

F# and WebAssembly

When I talk about F# and Web development I tend to speak about Fable which is an F# -> JS compiler (although, in Fable 4+ it will officially target more than just JS), in a sense you're basically replacing Typescript or Flow or any other JS compiler for F#.

Today we will talk about Bolero and Fun.Blazor which are some F# abstractions over Blazor, Microsoft's Frontend Framework, objectively speaking blazor is a direct competitor to Angular, Vue, React, Svelte, Aurelia and similar alternatives.

I know there is people out there waiting both patiently and desperately for the death of javascript while I don't think that day will ever come, I understand how being able a single language to fill many if not all parts of the stack is useful (we already do that with JS and thousands of people love it), so let's take a look!

Bolero

Getting started with Bolero is pretty simple

dotnet new -i Bolero.Templates
dotnet new bolero-app -o MyApp
cd MyApp && dotnet run -p src/MyApp.Server

Most of the features I will talk about here are well described in bolero's website so don't forget to check them out there as well

Hosting models

Bolero (just as blazor) can be used for both server side and client side apps, the templates by default provide both backend and frontend projects, this is because there's a feature that allows you to have Hot Reload for HTML templates but it only works when you run the frontend app with the server project.

Markup and DSLs

Bolero two main ways to write HTML, one is using HTML templates and the other is to use an HTML DSL, both things ultimately will produce

HTML Templates

Bolero uses a custom HTML Type Provider that allows you to write HTML templates in a type safe manner and provides some Hot Reload capabilities

type Hello = Template<"""<div id="hello">Hello, world!</div>""">
// or using a filepath
type Hello = Template<"templates/hello.html">

this gives you a type which has information about your HTML template, templates can have holes in them, which can be used to insert F# values.

Let's make a simple counter

<section class="${Classes}">
  <p>Count: <span>${Count}</span></p>
  <button onclick="${Increment}">Increment</button>
  <button onclick="${Decrement}">Decrement</button>
  <button onclick="${Reset}">Reset</button>
</section>

with that HTML as our template we can handle these holes inside our F# code

type Counter = Template<"templates/counter.html">

let getCounter initial =
    let mutable count = initial
    let getCounterCls count = if count > 10 "warning" else "normal"
    // let's fill each of the wholes we made on the template
    Counter()
        .Classes($"counter {getCounterCls count}")
        .Count(count)
        .Increment(fun _ -> count <- count + 1)
        .Decrement(fun _ -> count <- count - 1)
        .Reset(fun _ -> count <- initial)
        // once we're done call Elt() to get the instance of the template
        .Elt()

// use this somewhere else
let startsAt100 = getCounter 100
let startsAt0 = getCounter 0

the .Elt() at the end is to get the instance of the template.

You can also get nested templates, bind inputs, and radios for example by the way don't be scared by the mutable keyword right there is just to show a brief example in a normal situation you would likely be using Elmish

If plain HTML is not your cup of tea, let's move on to an F# DSL then

HTML DSL

The HTML DSL is a fairly standard one it is composed from a function that takes two lists as arguments, the first is for attributes and the second one is for children elements our counter example would look like this

let getCounter initial =
    let mutable count = initial
    let getCounterCls count = if count > 10 "warning" else "normal"

    section [ attr.``class`` $"counter {getCounterCls count}" ] [
        p [] [ text "Count: "; span [] [ text $"%i{count}" ] ]
        button [ on.click(fun _ -> count <- count + 1) ] [ text "Increment" ]
        button [ on.click(fun _ -> count <- count - 1) ] [ text "Decrement" ]
        button [ on.click(fun _ -> count <- initial) ] [ text "Reset" ]
    ]

// use this somewhere else
let startsAt100 = getCounter 100
let startsAt0 = getCounter 0

The main advantages of this approach is that you get the full power of the F# language. You can call functions, use ifs, pattern matches, get out of the box type safety and whatever you can do with F#.

The main disadvantages are that since this is F# code it must get compiled any time you make changes to it so... You will have to re-start your server any time you make changes to it this can be slow and discouraging for some people which is completely understandable.

Elmish

One of the popular architectures for F# enthusiasts is the ability to use the elmish architecture (also known as MVU) bolero offers elmish in the form of Components this is super convenient given how unscalable can elmish be on more complex aplications, rather than have a main elmish loop, you can have each of your website parts as a different elmish loop allowing you to de-couple some logic and even pages when not needed.

let's revisit our counter example

type State = { count: int }
type Msg =
    | Increment
    | Decrement
    | Reset

let init initial = { count = initial }

let update initial msg state =
    match msg with
    | Increment -> { state with count = state.count + 1}
    | decrement -> { state with count = state.count - 1}
    | Increment -> { state with count = initial }

This is the core part of our elmish model we will see how it works with both HTML and the DSL approaches

// the HTML template stays the same
let view state dispatch =
    let getCounterCls count = if count > 10 "warning" else "normal"
    // let's fill each of the wholes we made on the template
    Counter()
        .Classes($"counter {getCounterCls state.count}")
        .Count(count)
        .Increment(fun _ -> dispatch Increment)
        .Decrement(fun _ -> dispatch Decrement)
        .Reset(fun _ -> dispatch Reset)
        // once we're done call Elt() to get the instance of the template
        .Elt()

let view state dispatch =
    let getCounterCls count = if count > 10 "warning" else "normal"

    section [ attr.``class`` $"counter {getCounterCls count}" ] [
        p [] [ text "Count: "; span [] [ text $"%i{count}" ] ]
        button [ on.click(fun _ -> dispatch Increment) ] [ text "Increment" ]
        button [ on.click(fun _ -> dispatch Decrement) ] [ text "Decrement" ]
        button [ on.click(fun _ -> dispatch Reset) ] [ text "Reset" ]
    ]

Now, let's tie in all of that in our component

type MyCounter() =
    inherit ProgramComponent<State, Msg>()

    [<Parameter>]
    // Grab the value from outside of the component
    member val InitialValue: int option = None with get, set

    override this.Program =
        // ensure there's a default value for our elmish loop
        let initial = this.InitialValue |> Option.defaultValue 0

        // with partial application give it the initial value
        let update = update initial

        // Run the elmish program
        Program.mkSimple (fun _ -> init initial) update view

As you can see regardless if we chose HTML or the DSL the elmish component works the same. there are also other types of elmish components that you could use to fine-tune your component's performance these are called View Components but I'll leave those to you as homework 😜

To use this component we can call it in the following way

let startsAt0 = comp<MyCounter> [] []
let startsAt100 = comp<MyCounter> [ "InitialValue" => 100 ] []

We could use these in other view function somehwere or if I'm not mistaken even in a C#'s blazor file but don't quote me on that because I haven't tried it.

All in all this is more-less the gist of Bolero there are other features like routing, remoting, dependency injection interop, JS services that can be used but I think many of those require their own articles, if you're interested in those let me know!

Fun.Blazor

Fun Blazor is a library built on top of bolero it can interop with bolero nicely but it offers a few more options in the DSL and state management department.

Note that Fun.Blazor is still a young library but I find it promising and more ergonomic to use to the point I actually could favor it over other solutions.

To get started with Fun.Blazor you can either use this extremely minimal (PWA ready) template I made for this post

https://github.com/AngelMunoz/Fun.Blazor.Sample

or use the official templates

dotnet new --install Fun.Blazor.Templates::*
dotnet new fun-blazor-min-wasm -o MyApp
cd MyApp && dotnet run

I will continue here with the simplified template I made which differs a little bit from the official but the core concepts remain the same.

Fun.Blazor offers three alternative ways to write your HTML code, the first is by using a set of Computation Expressions (CE), the second is by using a Feliz style of DSL and the third one is to write HTML Templates as well

Let's revise our counter example again

let counter initial =
  adaptiview () {
    let! counter, setCounter = cval(initial).WithSetter()
    p () { childContent $"Count: {counter}" }

    button () {
      onclick (fun _ -> setCounter (counter + 1))
      childContent "Increment"
    }

    button () {
      onclick (fun _ -> setCounter (counter - 1))
      childContent "Decrement"
    }

    button () {
      onclick (fun _ -> setCounter (initial))
      childContent "Reset"
    }
  }

If you're familiar with JSX/Swift/Kotlin this might be the best way for you to work with your views it's also the most performant variation of Fun.Blazor's way to write HTML content, Fun.Blazor offers custom operations that help you model views in a slightly less verbose manner than the plain DSL offered by bolero, it's worth noting that bolero is working on a variation like this but it might take a while to land.

let counter initial =
  adaptiview () {
    let! counter, setCounter = cval(initial).WithSetter()
    html.p [
        attr.childContent$"Count: {counter}"
    ]

    html.button [
        evts.click (fun _ -> setCounter (counter + 1))
        attr.childContent $"Increment"
    ]

    html.button [
        evts.click (fun _ -> setCounter (counter - 1))
        attr.childContent $"Decrement"
    ]

    html.button [
        evts.click (fun _ -> setCounter (initial))
        attr.childContent $"Reset"
    ]
  }

if you've ever used Feliz or Avalonia.FuncUI then this DSL will make you feel at home, it's less verbose than the original DSL and gives you basically the same benefits, in the case of Fun.Blazor is slightly less performant but it is a viable alternative

let counter initial =
  adaptiview () {
    let! counter, setCounter = cval(initial).WithSetter()
    Template.html
      $"""
      <section>
        <p>Count: <span>{counter}</span></p>
        <button onclick="{fun _ -> setCounter (counter + 1)}">Increment</button>
        <button onclick="{fun _ -> setCounter (counter - 1)}">Decrement</button>
        <button onclick="{fun _ -> setCounter (initial)}">Reset</button>
      </section>
      """
  }

You might look at this and think:

Why on earth would I use this version? no syntax coloring, no nothing ewww!

If you're using VSCode you can use the Highlight HTML/SQL templates in F# extension and you will automatically get HTML intellisense, syntax coloring as well as F# support!
If you're using Visual Studio you can use Html for F#, it won't give you HTML intellisense but it at least offers the HTML syntax coloring which is greatly appreciated

Besides that, one strong point for that HTML templates is the ability to use Web Components/Custom Elements which are on the rise on usage, sadly these are not able to do Hot Reload like bolero's ones but they have their own benefits

State Management

While Fun.Blazor also allows you to use Elmish, it also offers a different way to handle view's states (which hopefully you spotted already) since Web Assembly uses F# code, it means it has access to a vast amount of libraries in the wild and take advantage of those as well, Fable is somewhat limited by javascript itself so any improvements you can get from the F# language is also limited to what Javascript can understand.

Adaptiviews

This is not the case though! Fun.Blazor takes advantage of the FSharp.Data.Adaptive library which works more-less like an excel spreadsheet's cells, each value is fixed unless it's being computed by another this allows performant updates on-demand, and with the help of adaptiview() {} it can leverage those same efficient updates to allow performant views in F#, in essence adaptiviews are hook-like abstractions.

adaptiview() {
    let! value, setValue = cval("my initial value").WithSetter()
    // do whatever else you want with the value and set value
}

Stores

If you like Sutil/Svelte like state management using stores then using Fun.Blazor components will be a great option for you

let counterComponent (initial: int) =
  html.inject (fun (hook: IComponentHook) ->
    let counter = hook.UseStore initial
    // this value will automatically update any time counter changes
    let adaptiveValue = hook.UseAVal counter

    adaptiview () {
      // we can use the value directly if we bind it on the
      // adaptiview CE
      let! computed = adaptiveValue
      // use the computed value
      p () { childContent $"Count: %i{computed}" }

      button () {
        // publish updates to the store
        onclick (fun _ -> counter.Publish(computed + 1))
        childContent "Increment"
      }

      button () {
        onclick (fun _ -> counter.Publish(computed - 1))
        childContent "Decrement"
      }

      button () {
        onclick (fun _ -> counter.Publish(initial))
        childContent "Reset"
      }
    })

This can be a powerful approach because you can have functions that take a store and push updates to it, the adaptive value will always be up to date and you can even produce multiple adaptive values from the same store! meaning that sub components or other views can also enjoy the benefits of sharing stores and generate their own adaptive values.

Components

We just saw a component with stores and adaptive values, but the benefits of Fun.Blazor components don't stop there, they let you access blazor's components lifecycle hooks seamlessly!

for example you can tap on the after first render and do async operations that can be integrated with observables thanks to FSharp.Control.Reactive

html.inject(fun (hook: IHookComponent, themeService: IThemeService) ->
    let theme = hook.UseStore Theme.Dark

    // Event
    hook.OnFirstAfterRender
    // async task
    |> Observable.map themeService.GetTheme
    |> Observable.switchTask
    // update the store
    |> Observable.subscribe theme.Publish
    // ensure disposal from the component's subscription
    |> hook.AddDispose

    nav() {
        // the rest of the view code
    }
)

The same can be done with other blazor lifecycle hooks.

Fun.Blazor offers ways to handle state outside elmish which I believe they are very powerful and can help you avoid some annoyances you can get when you use existing frameworks/approaches

Closing thoughts

So there it is! I gave some love to WebAssembly in F# as well I'm still on the fence of going full web assembly but it is certainly an alternative you can consider thanks to the fact that web assembly is part of the browser standards and not some propietary plugin thing (sorry Silverlight)

Bolero wasn't really appealing to me given the options for state handling (elmish only basically) and the DSL options but with Fun.Blazor and the state management options it provides I really feel like it's worth trying out, it is still a young library so make sure you try it, report bugs, give feedback and help it grow!

Progressively Adding Fable to JS Projects

Angel Daniel Munoz Gonzalez — Fri, 07 Jan 2022 05:20:32 +0000

You can find the sources for the code we'll use in this post in this repository's directory

Hello everyone!

Hopefully you have had an amazing end of the year and the holidays are finally finishing for many (mine are done for sure), what a better time to start something new or even better yet progressively enhancing something that already exists!

First of all What is Fable and what are the alternatives?

The Fable project is a F# -> <Lang> compiler where <Lang> is any of Javascript, Typescript and Python at the time of writing the last two are more experimental and the main support is for Javascript future iterations of Fable will cover these languages and even more like PHP, Rust, Dart.

One could say Fable is a direct competitor to projects like Typescript, Flow, Purescript, ReasonML and similar projects which aim to write in a typed language to produce safer code. While every of the mentioned projects has their own pros/cons I won't discuss that here since it's very likely you already chose Fable for the new code effort.

What does Fable do?

As mentioned above Fable is an F# -> <Lang> compiler but from here on we will talk about fable in the context of an F# -> Javascript compiler.

Fable is distributed via a .NET tool which can be installed both globally and locally via dotnet tool install -g fable (or remove the -g to do it locally) meaning that it requires that you have the .NET SDK installed on your machine.

Before continuing into the complete topic there are a few myths that I want to get out of the way for sure

Fable is a framework
Fable is react
Fable is for SPAs
Fable is for new projects
Fable requires Node.js

The truth and only truth is that Fable is an F# -> JS Compiler hence you can treat it like any other, just like you would treat typescript or purescript or reasonml or even babel. The reality would actually be

Fable is a tool to produce Javascript code.
Fable allows you to use React JS code as well as Svelte, Lit, and others.
Fable can be used for single JS scripts as well as full SPA projects there are no hard requirements.
Fable produces JS code, so wherever you can consume JS code Fable will work^* even slightly older projects.
Fable can be used in any context outside nodejs like any python, ruby, or php servers.

^* Fable emits modern javascript so your target needs to at least support the ES2015 ecmascript specification, in some cases (for older environments) further processing will be needed to re-transpile the JS code to ES3/ES5.

Having that said, let's dive into the topic at last.

New Javascript projects

If you are not very familiar to nodejs because you are either a backend dev from other ecosystem or a frontend developer who happens to use node because that's how the ecosystem is right now I'll give you a run down the very basics of a node project.

type on the terminal on a new directory the following command

npm init -y

it should print something like this

// Wrote to /path/to/directory/package.json:
{
  "name": "project1",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

That... in essence is a node project even if you haven't created a index.js as is indicated in the main field, of course you can add the file and adjust the newly created package.json like this

// src/index.js
console.log("Hello, World!");

{
  "name": "project1",
  "version": "1.0.0",
  "description": "",
  "main": "./src/index.js",
  "scripts": {
    "start": "node ./src/index.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Now you can run npm start or npm run start you should see the lovely Hello, World! message.

Yeah, yeah I know you didn't come here for the node part; New Fable projects are also very very simple, with the .NET SDK installed you just need to run

# you can delete the previous src directory just to make this work smoothly
dotnet new console -lang F# -o src
# The following commands are to install the fable .NET tool locally
dotnet new tool-manifest
dotnet tool install fable

While we can run fable from the terminal whenever we want we can leverage the fact that we're inside a node project and leverage the npm commands

{
  "name": "project1",
  "version": "1.0.0",
  "description": "",
  "main": "./src/Program.fs.js",
  "scripts": {
    "start-app": "node ./src/Program.fs.js",
    "start": "dotnet fable src --run npm run start-app"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "module" // NOTE: this is required to run the fable output
}

now you can enter npm start and you'll see Fable compiling then getting a Hello from F# even if it was not run in .NET but node.js

If you want to target node.js this is a basic setup you can try. There are other tools like pm2 or nodemon that can help you minimize the developer feedback loop that can re-run servers or node processes and allow the debugger to connect.

Existing Javascript projects

Let's create a new node project again and this time instead of creating a console app, we will create a class library

npm init -y
dotnet new classlib -o src -lang F#
# The following commands are to install the fable .NET tool locally
dotnet new tool-manifest
dotnet tool install fable

replace the contents of the package.json file with the following contents

{
  "name": "project2",
  "version": "1.0.0",
  "description": "",
  "main": "./src/index.js",
  "scripts": {
    "start-app": "node ./src/index.js",
    "start": "dotnet fable src --run npm run start-app"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "module"
}

The file structure looks like this

package.json
  | src
    index.js
    Library.fs
    src.fsproj

then add the following index.js

import { hello } from "./Library.fs.js";

hello("Javascript");

and run npm start you should see the lovely Hello Javascript

At this point we can assume that any existing project and file on those projects in this case represented by our index.js can introduce F# in the code base and the reasoning for this is that this is the exact mechanism you can use to introduce typescript in a code base. Although, typescript benefits Javascript code from the editor and other tooling around so it's arguably easier but I digress, the main point is that you can either incrementally add F# code to your javascript project and let them co-exist side by side or you can slowly migrate JS code to F# code, file by file, module by module, however you feel the pace is better for your team.

Now let's take this exercise a little bit further just to show that we can do it, we will create a new vitejs project

npm init vite@latest project3 --template lit
cd project3 && npm install && npm run dev

This should run a lit plain JS project let's add two simple F# files to src

<!-- App.fsproj -->
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>

  <ItemGroup>
    <Compile Include="Library.fs" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Fable.Lit" Version="1.4.1" />
  </ItemGroup>

</Project>

// Library.fs
open Lit
[<LitElement("my-counter")>]
let Counter() =
    // This call is obligatory to initialize the web component
    let _, props =
        LitElement.init(fun init ->
            init.props <- {| initial = Prop.Of(defaultValue = 0) |})
    let counter, setCounter = Hook.useState props.initial.Value
    html
        $"""
        <article>
            <p>{counter}</p>
            <button @click={fun _ -> setCounter(counter + 1)}>+</button>
            <button @click={fun _ -> setCounter(counter - 1)}>-</button>
        </article>
        """

inside src/my-element.js we will import the compiled fable file

// src/my-element.js
import { html, css, LitElement } from "lit"; // this should be already there
import "./Library.fs.js"; // this line
// ... the rest of the file

next we will modify the "dev" script in package.json for the following "dev": "dotnet fable src --watch --run vite serve".

Lastly we will add inside index.html the following content right inside the body element

<my-element>
  <p>This is child content</p>
  <!-- This content is from our Fable Code  -->
  <my-counter></my-counter>
</my-element>

now let's run npm run dev and visit localhost:3000 and we should see our counter inside the default

This particular technique is very powerful given that Fable.Lit produces web components meaning that you can render those in any existing framework so you can slowly migrate away from angular/react/vue using Fable.Lit components!

Typescript Projects

In the case of typescript projects you only need to add "allowJS": true to the tsconfig.json's compiler options

{
  "compilerOptions": {
    //... the rest of the config
    "allowJs": true
  }
  //... the rest of the config
}

Webpack and other bundlers/dev servers

In the last example we used vite which loads ES modules by default, other modern tools like webpack/snowpack/parcel should be exactly the same, just import those fable output files where you need them and the bundler should manage that since (and I emphasize) Fable output is modern standards javascript.

that will make typescript to also process your Fable output files

NOTE: If you have a strict config enabled you might face issues with implicit any errors, you can also add "checkJs": false so your Fable output doesn't get re-checked by typescript (after all it has already been checked by F#)

Good ol' monoliths

I have good news for you, you can use any of the approaches above to produce your javascript and include it in your JS modules or directly in the index.html there are are some caveats about Fable projects with JS dependencies. There are two approaches here you are managing your JS dependencies in any of the following ways

via NPM
via CDN/Local Dist file

If it's via NPM and you already have sorted out how to serve those then it's about just using Fable as usual and let it emit your JS files directly to the static files directory via fable's outDir flag: -o --outDir Redirect compilation output to a directory, something along the lines of dotnet fable fable-sources -o wwwroot and it should just work.

If you need to handle dependencies via CDN/Local Dist file then some dependencies won't work because they use node like imports import {} from 'lit/some/sub/directory.js browser imports need to start with / or ./ or even ../ so they can be valid ES module imports thankfully for this you can check out in a shameless plug one of the projects I'm working on: Perla which handles this precise case but I digress, the ideal situation would be you with npm and already figured out how to serve node dependencies to your compiled code.

Please remember that each F# file is equal to a single JS File when it's ran through fable so you can create scripts for specific pages, you don't need to import/export everything from a single entry point and you can use fable-browser to do DOM manipulation, so it is not necessary to add a whole SPA framework to enhance parts of your monolith.

Final Thoughts

A brief recap, we just saw how to add Fable

New node projects
Existing node projects
New/Existing Vite/Webpack/Typescript projects

the short summary would be this

Get the .NET SDK
Create a new F# project (either console or class library)
Install Fable as a local/global tool
Integrate the fable command as part of your workflow (in our case the npm scripts we modified above)
Run Fable and start enhancing with or migrating to F# your code base.

Also we got remembered that Fable outputs Javascript, not react, not a SPA, not anything else (in the context of this blog post) so your existing knowledge of how to use Javascript inside a SPA, Monolith, Node.js applies exactly the same.

I put a lot emphasis on that because I have seen people who believe Fable must be used in a certain way or that there's a religious way to use it. No it's a tool and has several uses feel free to pick your own way to use it.