SupportedFeatures

Supported C# Features Matrix

This document provides a comprehensive list of C# features, .NET APIs, and patterns supported by the eQuantic.UI compiler.

Legend

✅ Full Support: Transpiles to equivalent JavaScript behavior.

⚠️ Partial Support: Works with caveats or minor differences.

🚧 Planned: On the roadmap.

❌ Not Supported: fundamentally incompatible logic (e.g., blocking I/O, unsafe pointers).

---

🏗️ Core Language Features

Feature	Status	Notes
Classes & Structs	✅	Transpiled to ES6 Classes.
Interfaces	✅	Used for TypeScript type checking (erased at runtime).
Enums	✅	Transpiled to JS Objects (bidirectional mapping).
Generics	✅	Fully supported (erased at runtime).
Extension Methods	✅	Resolved via Semantic Model and transpiled to direct calls.
Async / Await	✅	Maps to async / await and Promise.
Lambda Expressions	✅	Maps to Arrow Functions () => {}.
Pattern Matching	✅	is patterns, Property Patterns, Recursive Patterns.
String Interpolation	✅	Maps to Template Literals `${var}`.
Null-Coalescing	✅	?? and ??= mapped to JS equivalents.
Object Initializers	✅	new Obj { Prop = 1 }.
Collection Initializers	✅	new List<int> { 1, 2 } maps to [1, 2].
Deconstruction	✅	var (a, b) = tuple maps to [a, b] = tuple.
Local Functions	✅	Transpiled to inner functions.
Records (with)	✅	Maps to object spread { ...src, prop: val }.
typeof	✅	Maps to type name string literal.
base calls	✅	Maps to super keyword.
cast & as	✅	Maps to JS passthrough/truncation.
sizeof	✅	Maps to C# primitive sizes.
Anonymous Methods	✅	delegate(...) { ... } maps to arrow functions.
stackalloc	✅	Maps to Typed Arrays (e.g., Int32Array).
yield return	✅	Maps to JS Generator Functions (function*).
lock	⚠️	Transpiled to a no-op block (JS is single-threaded).

---

🔄 LINQ Support

The compiler includes specialized strategies for nearly all LINQ methods.

Logic	Methods	Status
Filtering	Where, OfType	✅
Projection	Select, SelectMany, Cast	✅
Partitioning	Skip, Take, SkipWhile, TakeWhile	✅
Ordering	OrderBy, OrderByDescending, ThenBy, Reverse	✅
Aggregation	Count, Sum, Min, Max, Average, Aggregate	✅
Quantifiers	Any, All, Contains	✅
Sets	Distinct, DistinctBy, Union, Intersect, Except, Concat	✅
Elements	First, FirstOrDefault, Single, Last, ElementAt	✅
Utility	SequenceEqual, DefaultIfEmpty	✅
Conversion	ToList, ToArray, ToDictionary, ToHashSet	✅
Grouping/Join	GroupBy, Join, Zip	✅

---

📦 .NET Types (BCL)

We map common .NET types to their JavaScript equivalents.

Primitives

.NET Type	JavaScript Equivalent
string	String
int, double, float	Number
bool	Boolean
object	Object
dynamic	any

System.String

• ✅ Join, Format
• ✅ IsNullOrEmpty, IsNullOrWhiteSpace
• ✅ Split, Replace, Substring, Trim
• ✅ ToLower, ToUpper, StartsWith, EndsWith

System.DateTime & TimeSpan

• ✅ DateTime.Now, DateTime.UtcNow mapped to new Date().
• ✅ Year, Month, Day, Hour... properties.
• ✅ AddDays, AddHours... methods.
• ✅ ToString() (basic formatting).
• ✅ TimeSpan.FromMilliseconds... mapped to numeric milliseconds.

System.Collections.Generic

• ✅ List<T> → Javascript Array []
• ✅ Dictionary<TKey, TValue> → Javascript Object {} or Map (depending on usage).
• ✅ HashSet<T> → Javascript Set.
• ✅ Queue<T>, Stack<T> → Javascript Array methods (push/shift/pop).

System.Threading.Tasks

• ✅ Task, Task<T> → Promise.
• ✅ Task.Delay → setTimeout wrapper.
• ✅ Task.WhenAll, Task.WhenAny.
• ⚠️ Task.Run executes on the main thread (microtask), NOT a background thread.

Other Utilities

• ✅ Console.WriteLine → console.log.
• ✅ Math.* (Min, Max, Abs, Round, etc.) → Math.*.
• ✅ Guid (NewGuid, Empty, Parse) → crypto.randomUUID().
• ✅ Regex → JavaScript RegExp.

---

🌐 Ecosystem Packages

eQuantic.UI.Lucide / Heroicons / RadixIcons / TablerIcons / Phosphor / SimpleIcons / BootstrapIcons / Iconoir / ...

Purpose: Comprehensive Icon Sets. Contains:

• SVG resolution logic
• Specialized icon components
• IIconProvider implementation

Package	Purpose	Status
eQuantic.UI.Charts (Apex/ChartJS)	High-performance visualization.	✅
eQuantic.UI.Lottie	High-performance animations.	✅
eQuantic.UI.Image	Optimized (Lazy/Blur/Priority).	✅
eQuantic.UI.Tailwind	Standard styling integration.	✅

---

🧩 Framework Patterns

Pattern	Interface	Description	Status
Metadata Management	IHandleMetadata	SEO tags and head elements.	✅
Asset Management	IRequireAssets	Dynamic script/style injection.	✅
Server Actions	[ServerAction]	Secure RPC from Client to Server.	✅
Compound Components	N/A	Semantic sub-component patterns.	✅

---

⚠️ Limitations & Caveats

1. Blocking Code:

   • ❌ .Wait(), .Result on Tasks are NOT supported. You must use await. Blocking the main thread freezes the browser UI.

2. Reflection:

   • ❌ System.Reflection is largely unsupported.
   • ✅ typeof(T).Name and nameof(...) are supported constants.

3. File System:

   • ❌ System.IO (File, Directory) is not strictly forbidden but will fail at runtime in the browser.
   • Use Server Actions to handle file operations.

4. Numbers:

   • ✅ int/double/float map to JS numbers. Integer division truncates (Math.trunc) and Math.Round uses banker's rounding (MidpointRounding.ToEven) via the round compat helper.
   • ✅ decimal is now exact — compiled to the runtime Decimal compat type (BigInt mantissa + scale), so 0.1m + 0.2m == 0.3m is true. (Follow-up: decimal values arriving from server state should be hydrated as Decimal; literal/computed decimals are already exact.)
   • ✅ long/ulong are now exact — compiled to JS BigInt via the long compat helper. 9007199254740993L + 1L is 9007199254740994 (a plain JS number would round to …992). Literals become BigInt (5L → 5n); arithmetic/comparison operands are wrapped in long() (which coerces number/string → bigint) so mixed expressions never throw. On the wire, 64-bit ints cross as JSON strings (Server Actions + SSR state, via EqJson) so values beyond 2^53 survive the round trip. Other numeric type suffixes (1.5f, 100u) are stripped.

5. Thread Safety:

   • Since JS is single-threaded, lock statements are compiled away (ignored).
   • Thread.Sleep is not supported (use Task.Delay).

---

🧪 .NET BCL Coverage & Conformance

Transpilation fidelity is enforced by a conformance harness (tests/eQuantic.UI.Conformance.Tests): each case runs the same C# expression two ways — transpiled to JS (executed via the embedded Bun) and evaluated directly in .NET (Roslyn scripting) — and asserts identical results. 194+ cases are green.

Every construct resolves via one of three mechanisms (see docs/DOTNET-COVERAGE-PROGRAM.md):

1. Native strategy — idiomatic JS when the runtime has an equivalent.
2. .NET-compat runtime helper (the @equantic/runtime exports: format, parseEnum, round, Decimal/dec, long) — faithful .NET semantics where JS has none.
3. Fail-on-unsupported — a build error for genuinely impossible constructs (🚧 in progress).

Area	Status	Notes
Arithmetic / bitwise / comparison	✅	integer division truncates; %, shifts, `&
Math.*	✅	Truncate→trunc, Ceiling→ceil, Round banker's via round helper
decimal	✅	exact via Decimal (literals + + - * / == != < > <= >=)
Numeric constants	✅	int.MaxValue, double.Epsilon, … → literals
Parsing / Convert.*	✅	int/double.Parse, bool.Parse, Convert.ToInt32/ToDouble/ToString/ToBoolean/…
Strings	✅	Substring/IndexOf/Replace/Split/Pad/Trim(char)/Concat/Format/Join/IsNullOrEmpty/IsNullOrWhiteSpace
char.*	✅	ToUpper/ToLower/IsDigit/IsLetter/IsWhiteSpace/… (Unicode-aware)
LINQ	✅	Where/Select/SelectMany/Where-Select(indexed)/OrderBy/Distinct(By)/GroupBy/ToDictionary/Zip/Chunk/MinBy/MaxBy/Take(While)/Skip(While)/Aggregate/Sum/Min/Max/Average/Count/Any/All/First/Last/Concat/Reverse
Collections	✅	List, Dictionary, HashSet (incl. initializers and .Count)
enum	✅	member-name string (equality/switch/ternary)
long/ulong	✅	exact via BigInt (long helper); literals 5L→5n, wire as JSON string
DateTime/TimeSpan/Guid	⚠️/🚧	partial; full compat types planned