From 1296b17ba8fc46a5751c6ab0117c1be34cddd2cd Mon Sep 17 00:00:00 2001
From: Joseph Ajayi <adekoyeajayi@gmail.com>
Date: Wed, 21 Jan 2026 12:23:52 +0000
Subject: [PATCH 1/2] docs: enhance FP extensions documentation

- Add comprehensive documentation for NullableExtensions and ObjectExtensions
- Include practical examples for match() and let() methods
- Explain use cases and benefits of functional programming patterns
- Improve developer experience for core API utilities
---
 .../dart_node_core/lib/src/extensions.dart    | 64 ++++++++++++++++++-
 1 file changed, 61 insertions(+), 3 deletions(-)

diff --git a/packages/dart_node_core/lib/src/extensions.dart b/packages/dart_node_core/lib/src/extensions.dart
index ba4ecc9..2596e12 100644
--- a/packages/dart_node_core/lib/src/extensions.dart
+++ b/packages/dart_node_core/lib/src/extensions.dart
@@ -1,6 +1,42 @@
-/// Extension methods FP style transformations
+/// Functional programming extensions for nullable and non-null types.
+///
+/// Provides pattern matching and transformation utilities inspired by 
+/// functional programming languages like Kotlin and Rust.
+library;
+
+/// Extension methods for nullable values enabling pattern matching and 
+/// functional transformations.
+///
+/// Example:
+/// ```dart
+/// String? getName() => 'World';
+/// 
+/// final greeting = getName().match(
+///   some: (name) => 'Hello, $name!',
+///   none: () => 'Hello, stranger!',
+/// );
+/// ```
 extension NullableExtensions<T extends Object> on T? {
   /// Pattern match on nullable value with cases for non-null and null.
+  ///
+  /// This provides a safe way to handle nullable values by requiring
+  /// explicit handling of both the present (`some`) and absent (`none`) cases.
+  ///
+  /// **Parameters:**
+  /// - `some`: Function called when this value is non-null
+  /// - `none`: Function called when this value is null
+  ///
+  /// **Returns:** The result of calling either `some` or `none`
+  ///
+  /// Example:
+  /// ```dart
+  /// int? maybeNumber = 42;
+  /// 
+  /// final result = maybeNumber.match(
+  ///   some: (n) => 'Number: $n',
+  ///   none: () => 'No number',
+  /// ); // Returns: "Number: 42"
+  /// ```
   R match<R>({required R Function(T) some, required R Function() none}) =>
       switch (this) {
         final T value => some(value),
@@ -8,8 +44,30 @@ extension NullableExtensions<T extends Object> on T? {
       };
 }
 
-/// Extension methods FP style transformations
+/// Extension methods for non-null values enabling functional transformations.
+///
+/// Provides utilities for applying transformations to values in a functional style.
 extension ObjectExtensions<T extends Object> on T {
-  /// Apply function [op] to this value if non-null and return the result.
+  /// Apply function [op] to this value and return the result.
+  ///
+  /// This is useful for chaining operations and avoiding temporary variables.
+  /// Also known as the "let" operation in Kotlin or "tap" in other languages.
+  ///
+  /// **Parameters:**
+  /// - `op`: Function that transforms this value into a result of type `R`
+  ///
+  /// **Returns:** The result of calling `op` with this value
+  ///
+  /// Example:
+  /// ```dart
+  /// final length = 'hello world'
+  ///     .let((s) => s.split(' '))
+  ///     .let((words) => words.length); // Returns: 2
+  /// 
+  /// // Instead of:
+  /// final text = 'hello world';
+  /// final words = text.split(' ');
+  /// final length = words.length;
+  /// ```
   R let<R>(R Function(T) op) => op(this);
 }

From a9d4a0ca24bb88fcb1c618845fae2393ec3473ad Mon Sep 17 00:00:00 2001
From: Joseph Ajayi <adekoyeajayi@gmail.com>
Date: Wed, 21 Jan 2026 12:36:22 +0000
Subject: [PATCH 2/2] docs: fix formatting issues in extensions documentation

---
 packages/dart_node_core/lib/src/extensions.dart | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/dart_node_core/lib/src/extensions.dart b/packages/dart_node_core/lib/src/extensions.dart
index 2596e12..3803451 100644
--- a/packages/dart_node_core/lib/src/extensions.dart
+++ b/packages/dart_node_core/lib/src/extensions.dart
@@ -1,16 +1,16 @@
 /// Functional programming extensions for nullable and non-null types.
 ///
-/// Provides pattern matching and transformation utilities inspired by 
+/// Provides pattern matching and transformation utilities inspired by
 /// functional programming languages like Kotlin and Rust.
 library;
 
-/// Extension methods for nullable values enabling pattern matching and 
+/// Extension methods for nullable values enabling pattern matching and
 /// functional transformations.
 ///
 /// Example:
 /// ```dart
 /// String? getName() => 'World';
-/// 
+///
 /// final greeting = getName().match(
 ///   some: (name) => 'Hello, $name!',
 ///   none: () => 'Hello, stranger!',
@@ -31,7 +31,7 @@ extension NullableExtensions<T extends Object> on T? {
   /// Example:
   /// ```dart
   /// int? maybeNumber = 42;
-  /// 
+  ///
   /// final result = maybeNumber.match(
   ///   some: (n) => 'Number: $n',
   ///   none: () => 'No number',
@@ -63,7 +63,7 @@ extension ObjectExtensions<T extends Object> on T {
   /// final length = 'hello world'
   ///     .let((s) => s.split(' '))
   ///     .let((words) => words.length); // Returns: 2
-  /// 
+  ///
   /// // Instead of:
   /// final text = 'hello world';
   /// final words = text.split(' ');