feat: Add release build configuration details to documentation and improve assertion handling

Author: gedaiu

README.md

@@ -141,6 +141,53 @@ The `Evaluation.result` provides access to:
 
 This is particularly useful when writing tests for custom assertion operations or when you need to verify that assertions produce the correct error messages.
 
+## Release Build Configuration
+
+By default, fluent-asserts behaves like D's built-in `assert`: assertions are enabled in debug builds and disabled (become no-ops) in release builds. This allows you to use fluent-asserts as a replacement for `assert` in your production code without any runtime overhead in release builds.
+
+**Default behavior:**
+- Debug build: assertions enabled
+- Release build (`dub build -b release` or `-release` flag): assertions disabled (no-op)
+
+**Force enable in release builds:**
+
+dub.sdl:
+```sdl
+versions "FluentAssertsDebug"
+```
+
+dub.json:
+```json
+{
+    "versions": ["FluentAssertsDebug"]
+}
+```
+
+**Force disable in all builds:**
+
+dub.sdl:
+```sdl
+versions "D_Disable_FluentAsserts"
+```
+
+dub.json:
+```json
+{
+    "versions": ["D_Disable_FluentAsserts"]
+}
+```
+
+**Check at compile-time:**
+```D
+import fluent.asserts;
+
+static if (fluentAssertsEnabled) {
+    // assertions are active
+} else {
+    // assertions are disabled (release build)
+}
+```
+
 ## Custom Assert Handler
 
 During unittest builds, the library automatically installs a custom handler for D's built-in `assert` statements. This provides fluent-asserts style error messages even when using standard `assert`:

docs/src/content/docs/guide/configuration.mdx

@@ -130,6 +130,75 @@ not ok - [1, 2, 3] should contain 5. 5 is missing from [1, 2, 3].
   ...
 ```
 
+## Release Build Configuration
+
+By default, fluent-asserts behaves like D's built-in `assert`: assertions are enabled in debug builds and disabled (become no-ops) in release builds. This allows you to use fluent-asserts as a replacement for `assert` in your production code without any runtime overhead in release builds.
+
+### Default Behavior
+
+| Build Type | Assertions |
+|------------|------------|
+| Debug (default) | Enabled |
+| Release (`-release` or `dub build -b release`) | Disabled (no-op) |
+
+### Version Flags
+
+You can override the default behavior using version flags.
+
+**Force enable in release builds:**
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+<Tabs>
+  <TabItem label="dub.sdl">
+```sdl
+versions "FluentAssertsDebug"
+```
+  </TabItem>
+  <TabItem label="dub.json">
+```json
+{
+    "versions": ["FluentAssertsDebug"]
+}
+```
+  </TabItem>
+</Tabs>
+
+**Force disable in all builds:**
+
+<Tabs>
+  <TabItem label="dub.sdl">
+```sdl
+versions "D_Disable_FluentAsserts"
+```
+  </TabItem>
+  <TabItem label="dub.json">
+```json
+{
+    "versions": ["D_Disable_FluentAsserts"]
+}
+```
+  </TabItem>
+</Tabs>
+
+### Compile-Time Check
+
+You can check at compile-time whether assertions are enabled:
+
+```d
+import fluent.asserts;
+
+static if (fluentAssertsEnabled) {
+    // assertions are active
+    writeln("Running with assertions enabled");
+} else {
+    // assertions are disabled (release build)
+    writeln("Assertions disabled for performance");
+}
+```
+
+This is useful for conditionally including assertion-related code or logging.
+
 ## Next Steps
 
 - Learn about [Core Concepts](/guide/core-concepts/)

docs/src/content/docs/guide/installation.mdx

@@ -3,25 +3,28 @@ title: Installation
 description: How to install fluent-asserts in your D project
 ---
 
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
 ## Using DUB (Recommended)
 
 The easiest way to use fluent-asserts is through [DUB](https://code.dlang.org/), the D package manager.
 
-### Add to dub.json
-
+<Tabs>
+  <TabItem label="dub.sdl">
+```sdl
+dependency "fluent-asserts" version="~>1.0.1"
+```
+  </TabItem>
+  <TabItem label="dub.json">
 ```json
 {
     "dependencies": {
         "fluent-asserts": "~>1.0.1"
     }
 }
 ```
-
-### Or add to dub.sdl
-
-```sdl
-dependency "fluent-asserts" version="~>1.0.1"
-```
+  </TabItem>
+</Tabs>
 
 Then run:
 
@@ -75,6 +78,12 @@ dub test
 dub test --compiler=ldc2
 ```
 
+## Release Builds
+
+By default, fluent-asserts assertions are disabled in release builds (similar to D's built-in `assert`). This means you can use fluent-asserts in production code without runtime overhead in release builds.
+
+See [Configuration](/guide/configuration/#release-build-configuration) for details on how to control this behavior.
+
 ## Integration with Test Frameworks
 
 fluent-asserts integrates seamlessly with D test frameworks.
@@ -85,6 +94,14 @@ fluent-asserts integrates seamlessly with D test frameworks.
 
 Add trial to your project:
 
+<Tabs>
+  <TabItem label="dub.sdl">
+```sdl
+dependency "fluent-asserts" version="~>1.0.1"
+dependency "trial" version="~>0.8.0-beta.7"
+```
+  </TabItem>
+  <TabItem label="dub.json">
 ```json
 {
     "dependencies": {
@@ -93,6 +110,8 @@ Add trial to your project:
     }
 }
 ```
+  </TabItem>
+</Tabs>
 
 Run your tests with:
 

docs/src/content/docs/guide/introduction.mdx

@@ -101,6 +101,18 @@ The `Evaluation.result` provides access to:
 - `missing` - array of missing elements (for collection comparisons)
 - `extra` - array of extra elements (for collection comparisons)
 
+## Release Builds
+
+Like D's built-in `assert`, fluent-asserts assertions are disabled in release builds. This means you can use them in production code without runtime overhead:
+
+```d
+// In debug builds: assertion is checked
+// In release builds: this is a no-op
+expect(value).to.be.greaterThan(0);
+```
+
+See [Configuration](/guide/configuration/#release-build-configuration) for how to control this behavior.
+
 ## Custom Assert Handler
 
 During unittest builds, the library automatically installs a custom handler for D's built-in `assert` statements. This provides fluent-asserts style error messages even when using standard `assert`:

source/fluent/asserts.d

@@ -1,6 +1,7 @@
 module fluent.asserts;
 
 public import fluentasserts.core.base;
+public import fluentasserts.core.config : fluentAssertsEnabled;
 
 version(Have_fluent_asserts_vibe) {
   public import fluentasserts.vibe.json;

source/fluentasserts/core/config.d

@@ -11,6 +11,39 @@ enum OutputFormat {
   tap
 }
 
+/// Compile-time check for whether assertions are enabled.
+///
+/// By default, assertions are enabled in debug builds and disabled in release builds.
+/// This allows using fluent-asserts as a replacement for D's built-in assert
+/// while maintaining the same release-build behavior.
+///
+/// Build configurations:
+/// - Debug build (default): assertions enabled
+/// - Release build (`-release` or `dub build -b release`): assertions disabled (no-op)
+/// - Force disable: add version `D_Disable_FluentAsserts` to disable even in debug
+/// - Force enable in release: add version `FluentAssertsDebug` to enable in release builds
+///
+/// Example dub.sdl configuration to force enable in release:
+/// ---
+/// versions "FluentAssertsDebug"
+/// ---
+///
+/// Example dub.sdl configuration to always disable:
+/// ---
+/// versions "D_Disable_FluentAsserts"
+/// ---
+version (D_Disable_FluentAsserts) {
+  enum fluentAssertsEnabled = false;
+} else version (release) {
+  version (FluentAssertsDebug) {
+    enum fluentAssertsEnabled = true;
+  } else {
+    enum fluentAssertsEnabled = false;
+  }
+} else {
+  enum fluentAssertsEnabled = true;
+}
+
 /// Singleton configuration struct for fluent-asserts.
 /// Provides centralized access to all configurable settings.
 struct FluentAssertsConfig {

source/fluentasserts/core/expect.d

@@ -29,7 +29,7 @@ import fluentasserts.operations.comparison.approximately : approximatelyOp = app
 import fluentasserts.operations.exception.throwable : throwAnyExceptionOp = throwAnyException, throwExceptionOp = throwException, throwAnyExceptionWithMessageOp = throwAnyExceptionWithMessage, throwExceptionWithMessageOp = throwExceptionWithMessage, throwSomethingOp = throwSomething, throwSomethingWithMessageOp = throwSomethingWithMessage;
 import fluentasserts.operations.memory.gcMemory : allocateGCMemoryOp = allocateGCMemory;
 import fluentasserts.operations.memory.nonGcMemory : allocateNonGCMemoryOp = allocateNonGCMemory;
-import fluentasserts.core.config : config = FluentAssertsConfig;
+import fluentasserts.core.config : config = FluentAssertsConfig, fluentAssertsEnabled;
 
 import std.datetime : Duration, SysTime;
 
@@ -67,6 +67,13 @@ string truncateForMessage(const(char)[] value) @trusted nothrow {
   private {
     Evaluation _evaluation;
     int refCount;
+    bool _initialized;
+  }
+
+  /// Returns true if this Expect was properly initialized.
+  /// Used to skip processing for no-op assertions in release builds.
+  bool isInitialized() const @nogc nothrow {
+    return _initialized;
   }
 
   /// Returns a reference to the underlying evaluation.
@@ -79,6 +86,7 @@ string truncateForMessage(const(char)[] value) @trusted nothrow {
   /// Initializes the evaluation state and sets up the initial message.
   /// Source parsing is deferred until assertion failure for performance.
   this(ValueEvaluation value) @trusted {
+    _initialized = true;
     _evaluation.id = Lifecycle.instance.beginEvaluation(value);
     _evaluation.currentValue = value;
     _evaluation.source = SourceResult.create(value.fileName[].idup, value.line);
@@ -105,12 +113,18 @@ string truncateForMessage(const(char)[] value) @trusted nothrow {
   /// Increments the source's refCount so only the last copy triggers finalization.
   this(ref return scope Expect another) @trusted nothrow {
     this._evaluation = another._evaluation;
+    this._initialized = another._initialized;
     this.refCount = 0;  // New copy starts with 0
     another.refCount++;  // Prevent source from finalizing
   }
 
   /// Destructor. Finalizes the evaluation when reference count reaches zero.
+  /// Does nothing if the Expect was never initialized (e.g., in release builds).
   ~this() {
+    if (!_initialized) {
+      return;
+    }
+
     refCount--;
 
     if(refCount < 0) {
@@ -536,31 +550,36 @@ string truncateForMessage(const(char)[] value) @trusted nothrow {
 
 /// Creates an Expect from a callable delegate.
 /// Executes the delegate and captures any thrown exception.
+/// In release builds (unless FluentAssertsDebug is set), this is a no-op.
 Expect expect(void delegate() callable, const string file = __FILE__, const size_t line = __LINE__, string prependText = null) @trusted {
-  ValueEvaluation value;
-  value.typeNames.put("callable");
-
-  try {
-    if(callable !is null) {
-      callable();
-    } else {
-      value.typeNames.clear();
-      value.typeNames.put("null");
+  static if (!fluentAssertsEnabled) {
+    return Expect.init;
+  } else {
+    ValueEvaluation value;
+    value.typeNames.put("callable");
+
+    try {
+      if(callable !is null) {
+        callable();
+      } else {
+        value.typeNames.clear();
+        value.typeNames.put("null");
+      }
+    } catch(Exception e) {
+      value.throwable = e;
+      value.meta["Exception"] = "yes";
+    } catch(Throwable t) {
+      value.throwable = t;
+      value.meta["Throwable"] = "yes";
     }
-  } catch(Exception e) {
-    value.throwable = e;
-    value.meta["Exception"] = "yes";
-  } catch(Throwable t) {
-    value.throwable = t;
-    value.meta["Throwable"] = "yes";
-  }
 
-  value.fileName = toHeapString(file);
-  value.line = line;
-  value.prependText = toHeapString(prependText);
+    value.fileName = toHeapString(file);
+    value.line = line;
+    value.prependText = toHeapString(prependText);
 
-  auto result = Expect(value);
-  return result;
+    auto result = Expect(value);
+    return result;
+  }
 }
 
 /// Creates an Expect struct from a lazy value.
@@ -570,7 +589,12 @@ Expect expect(void delegate() callable, const string file = __FILE__, const size
 ///   line = Source line (auto-filled)
 ///   prependText = Optional text to prepend to the value display
 /// Returns: An Expect struct for fluent assertions
+/// In release builds (unless FluentAssertsDebug is set), this is a no-op.
 Expect expect(T)(lazy T testedValue, const string file = __FILE__, const size_t line = __LINE__, string prependText = null) @trusted {
-  auto result = Expect(testedValue.evaluate(file, line, prependText).evaluation);
-  return result;
+  static if (!fluentAssertsEnabled) {
+    return Expect.init;
+  } else {
+    auto result = Expect(testedValue.evaluate(file, line, prependText).evaluation);
+    return result;
+  }
 }