functype 0.8.67 → 0.8.69

package/README.md

@@ -25,8 +25,9 @@ Functype is a lightweight functional programming library for TypeScript, drawing
 - **Task**: Handle synchronous and asynchronous operations with error handling
 - **Tuple**: Type-safe fixed-length arrays
 - **Typeable**: Runtime type identification with compile-time safety
-- **Branded Types**: Nominal typing in TypeScript's structural type system 
+- **Branded Types**: Nominal typing in TypeScript's structural type system
 - **FPromise**: Enhanced Promise functionality with built-in error handling
+- **Error Formatting**: Utilities for improved error visualization and logging
 
 ## Installation
 
@@ -215,7 +216,9 @@ const Email = (email: string): Email => {
 }
 
 // Type safety in action
-function getUserByEmail(email: Email): User { /* ... */ }
+function getUserByEmail(email: Email): User {
+  /* ... */
+}
 
 // These calls are type-safe
 const userId = UserId("U123456")
@@ -238,21 +241,21 @@ import { Option, Either, Try, List } from "functype"
 const opt = Option(5)
 const optResult = opt.fold(
   () => "None",
-  (value) => `Some(${value})`
+  (value) => `Some(${value})`,
 ) // "Some(5)"
 
 // Either fold
 const either = Right<string, number>(42)
 const eitherResult = either.fold(
   (left) => `Left(${left})`,
-  (right) => `Right(${right})`
+  (right) => `Right(${right})`,
 ) // "Right(42)"
 
 // Try fold
 const tryValue = Try(() => 10)
 const tryResult = tryValue.fold(
   (error) => `Error: ${error.message}`,
-  (value) => `Success: ${value}`
+  (value) => `Success: ${value}`,
 ) // "Success: 10"
 
 // List fold
@@ -260,6 +263,85 @@ const list = List([1, 2, 3])
 const listResult = list.foldLeft(0)((acc, num) => acc + num) // 6
 ```
 
+## Foldable
+
+New in v0.8.67, Functype includes a proper `Foldable` type class that data structures can implement:
+
+```typescript
+import { FoldableUtils, Option, List, Try } from "functype"
+
+// All data structures implement the Foldable interface
+const option = Option(5)
+const list = List([1, 2, 3, 4, 5])
+const tryVal = Try(() => 10)
+
+// Use fold to pattern-match on data structures
+option.fold(
+  () => console.log("Empty option"),
+  (value) => console.log(`Option value: ${value}`),
+)
+
+// Use foldLeft for left-associative operations
+const sum = list.foldLeft(0)((acc, value) => acc + value) // 15
+
+// Use foldRight for right-associative operations
+const product = list.foldRight(1)((value, acc) => value * acc) // 120
+
+// Use FoldableUtils to work with any Foldable
+const isEmpty = FoldableUtils.isEmpty(option) // false
+const size = FoldableUtils.size(list) // 5
+const convertedToList = FoldableUtils.toList(option) // List([5])
+const convertedToEither = FoldableUtils.toEither(tryVal, "Error") // Right(10)
+```
+
+## Matchable
+
+New in v0.8.68, Functype now includes a `Matchable` type class for enhanced pattern matching:
+
+```typescript
+import { Option, Either, Try, List, MatchableUtils } from "functype"
+
+// Pattern matching on Option
+const opt = Option(42)
+const optResult = opt.match({
+  Some: (value) => `Found: ${value}`,
+  None: () => "Not found",
+}) // "Found: 42"
+
+// Pattern matching on Either
+const either = Either.fromNullable(null, "Missing value")
+const eitherResult = either.match({
+  Left: (error) => `Error: ${error}`,
+  Right: (value) => `Value: ${value}`,
+}) // "Error: Missing value"
+
+// Pattern matching on Try
+const tryVal = Try(() => JSON.parse('{"name":"John"}'))
+const tryResult = tryVal.match({
+  Success: (data) => `Name: ${data.name}`,
+  Failure: (error) => `Parse error: ${error.message}`,
+}) // "Name: John"
+
+// Pattern matching on List
+const list = List([1, 2, 3])
+const listResult = list.match({
+  NonEmpty: (values) => `Values: ${values.join(", ")}`,
+  Empty: () => "No values",
+}) // "Values: 1, 2, 3"
+
+// Using MatchableUtils for advanced pattern matching
+const isPositive = MatchableUtils.when(
+  (n: number) => n > 0,
+  (n) => `Positive: ${n}`,
+)
+
+const defaultCase = MatchableUtils.default((n: number) => `Default: ${n}`)
+
+// Using pattern guards in custom matching logic
+const num = 42
+const result = isPositive(num) ?? defaultCase(num) // "Positive: 42"
+```
+
 ## Type Safety
 
 Functype leverages TypeScript's advanced type system to provide compile-time safety for functional patterns, ensuring that your code is both robust and maintainable.
@@ -272,6 +354,51 @@ const mappedValue = option.map((x) => x.toString())
 // Inferred as string
 ```
 
+## Error Formatting
+
+Functype provides utilities for improved error visualization and logging:
+
+```typescript
+import { formatError, createErrorSerializer } from "functype/error"
+
+// Create a nested task error
+const innerTask = Task({ name: "DbQuery" }).Sync(() => {
+  throw new Error("Database connection failed")
+})
+
+const outerTask = Task({ name: "UserFetch" }).Sync(() => {
+  return innerTask.value
+})
+
+// Format the error for console display
+console.error(
+  formatError(outerTask.value as Error, {
+    includeTasks: true,
+    includeStackTrace: true,
+    colors: true,
+  }),
+)
+
+// Create a serializer for structured logging libraries like Pino
+const errorSerializer = createErrorSerializer()
+
+// Use with Pino
+const logger = pino({
+  serializers: { err: errorSerializer },
+})
+
+// Log the error with full context
+logger.error(
+  {
+    err: outerTask.value,
+    requestId: "req-123",
+  },
+  "Failed to fetch user data",
+)
+```
+
+For more details, see the [Error Formatting Guide](docs/error-formatting.md).
+
 ## Roadmap / TODO
 
 ### Missing Functionality
@@ -281,6 +408,9 @@ const mappedValue = option.map((x) => x.toString())
 - [ ] Add Reader/State/IO monads for more functional patterns
 - [ ] Implement lens/optics for immutable updates
 - [ ] Expand concurrent execution utilities beyond FPromise.all
+- [x] Add a proper Foldable type class interface
+- [x] Implement Matchable type class for pattern matching
+- [ ] Implement Applicative and other functional type classes
 
 ### Performance Optimizations
 
@@ -346,4 +476,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.