functype 0.8.67 → 0.8.69

package/dist/option/index.mjs

@@ -1,2 +1,2 @@
-export{e as None,g as Option,f as OptionConstructor,d as Some}from'../chunk-NTL4HYMA.mjs';import'../chunk-PXFJPCM7.mjs';import'../chunk-TQJDL6YW.mjs';//# sourceMappingURL=index.mjs.map
+export{c as None,e as Option,d as OptionConstructor,b as Some}from'../chunk-5DWCHDSA.mjs';import'../chunk-7PQA3W7W.mjs';import'../chunk-TQJDL6YW.mjs';//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/set/index.d.ts

@@ -1,3 +1,2 @@
-export { S as Set } from '../option/index.js';
-import '../Tuple-DfdXAbL_.js';
-import '../branded/index.js';
+export { m as Set } from '../Either-BfXNbTHo.js';
+import '../Valuable-CtuVEKTZ.js';

package/dist/set/index.mjs

@@ -1,2 +1,2 @@
-export{h as Set}from'../chunk-NTL4HYMA.mjs';import'../chunk-PXFJPCM7.mjs';import'../chunk-TQJDL6YW.mjs';//# sourceMappingURL=index.mjs.map
+export{f as Set}from'../chunk-5DWCHDSA.mjs';import'../chunk-7PQA3W7W.mjs';import'../chunk-TQJDL6YW.mjs';//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/try/index.d.ts

@@ -1,3 +1,59 @@
-export { h as Try } from '../option/index.js';
-import '../Tuple-DfdXAbL_.js';
-import '../branded/index.js';
+import { E as Either, S as Serializable, P as Pipe, F as Foldable, M as Matchable } from '../Either-BfXNbTHo.js';
+import { a as Type, T as Typeable, V as Valuable } from '../Valuable-CtuVEKTZ.js';
+
+/**
+ * Possible types of Try instances
+ */
+type TypeNames = "Success" | "Failure";
+type Try<T> = {
+    readonly _tag: TypeNames;
+    readonly error: Error | undefined;
+    isSuccess: () => boolean;
+    isFailure: () => boolean;
+    get: () => T;
+    getOrElse: (defaultValue: T) => T;
+    orElse: (alternative: Try<T>) => Try<T>;
+    orThrow: (error: Error) => T;
+    toEither: () => Either<Error, T>;
+    map: <U>(f: (value: T) => U) => Try<U>;
+    flatMap: <U>(f: (value: T) => Try<U>) => Try<U>;
+    /**
+     * Pattern matches over the Try, applying onFailure if Failure and onSuccess if Success
+     * @param onFailure - Function to apply if the Try is Failure
+     * @param onSuccess - Function to apply if the Try is Success
+     * @returns The result of applying the appropriate function
+     */
+    fold: <U extends Type>(onFailure: (error: Error) => U, onSuccess: (value: T) => U) => U;
+    toString: () => string;
+    /**
+     * Pattern matches over the Try, applying a handler function based on the variant
+     * @param patterns - Object with handler functions for Success and Failure variants
+     * @returns The result of applying the matching handler function
+     */
+    match<R>(patterns: {
+        Success: (value: T) => R;
+        Failure: (error: Error) => R;
+    }): R;
+} & Typeable<TypeNames> & Valuable<TypeNames, T | Error> & Serializable<T> & Pipe<T> & Foldable<T> & Matchable<T | Error, "Success" | "Failure">;
+declare const Try: (<T>(f: () => T) => Try<T>) & {
+    /**
+     * Creates a Try from JSON string
+     * @param json - The JSON string
+     * @returns Try instance
+     */
+    fromJSON: <T>(json: string) => Try<T>;
+    /**
+     * Creates a Try from YAML string
+     * @param yaml - The YAML string
+     * @returns Try instance
+     */
+    fromYAML: <T>(yaml: string) => Try<T>;
+    /**
+     * Creates a Try from binary string
+     * @param binary - The binary string
+     * @returns Try instance
+     */
+    fromBinary: <T>(binary: string) => Try<T>;
+};
+
+export { Try, type TypeNames };

package/dist/try/index.mjs

@@ -1,2 +1,2 @@
-export{x as Try}from'../chunk-NTL4HYMA.mjs';import'../chunk-PXFJPCM7.mjs';import'../chunk-TQJDL6YW.mjs';//# sourceMappingURL=index.mjs.map
+export{G as Try}from'../chunk-5DWCHDSA.mjs';import'../chunk-7PQA3W7W.mjs';import'../chunk-TQJDL6YW.mjs';//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/tuple/index.d.ts

@@ -1 +1,12 @@
-export { b as Tuple } from '../Tuple-DfdXAbL_.js';
+import { a as Type, c as ArrayFunctor, T as Typeable, V as Valuable } from '../Valuable-CtuVEKTZ.js';
+
+type Tuple<T extends Type[]> = {
+    get<K extends number>(index: K): T[K];
+    map<U extends Type[]>(f: (value: T) => U): Tuple<U>;
+    flatMap<U extends Type[]>(f: (value: T) => Tuple<U>): Tuple<U>;
+    toArray(): T;
+    [Symbol.iterator](): Iterator<T[number]>;
+} & ArrayFunctor<T> & Typeable<"Tuple"> & Valuable<"Tuple", T>;
+declare const Tuple: <T extends Type[]>(values: T) => Tuple<T>;
+
+export { Tuple };

package/dist/tuple/index.mjs

@@ -1,2 +1,2 @@
-export{c as Tuple}from'../chunk-PXFJPCM7.mjs';//# sourceMappingURL=index.mjs.map
+export{d as Tuple}from'../chunk-7PQA3W7W.mjs';//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functype",
-  "version": "0.8.67",
+  "version": "0.8.69",
   "type": "module",
   "description": "A smallish functional library for TypeScript",
   "author": "jordan.burke@gmail.com",
@@ -12,29 +12,30 @@
   "homepage": "https://github.com/jordanburke/functype#readme",
   "url": "https://github.com/jordanburke/functype",
   "devDependencies": {
-    "@eslint/compat": "^1.2.8",
+    "@eslint/compat": "^1.2.9",
     "@eslint/eslintrc": "^3.3.1",
-    "@eslint/js": "^9.25.1",
-    "@types/node": "^22.15.3",
-    "@typescript-eslint/eslint-plugin": "^8.31.1",
-    "@typescript-eslint/parser": "^8.31.1",
-    "@vitest/coverage-v8": "^3.1.2",
-    "@vitest/ui": "^3.1.2",
+    "@eslint/js": "^9.28.0",
+    "@types/node": "^22.15.30",
+    "@typescript-eslint/eslint-plugin": "^8.33.1",
+    "@typescript-eslint/parser": "^8.33.1",
+    "@vitest/coverage-v8": "^3.2.2",
+    "@vitest/ui": "^3.2.2",
     "cross-env": "^7.0.3",
-    "eslint": "^9.25.1",
-    "eslint-config-prettier": "^10.1.2",
+    "eslint": "^9.28.0",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-plugin-functional": "^9.0.2",
     "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-prettier": "^5.2.6",
+    "eslint-plugin-prettier": "^5.4.1",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "fast-check": "^4.1.1",
-    "globals": "^16.0.0",
+    "globals": "^16.2.0",
     "prettier": "^3.5.3",
     "rimraf": "^6.0.1",
     "ts-node": "^10.9.2",
-    "tsup": "^8.4.0",
-    "typedoc": "^0.28.3",
+    "tsup": "^8.5.0",
+    "typedoc": "^0.28.5",
     "typescript": "5.8.3",
-    "vitest": "^3.1.2"
+    "vitest": "^3.2.2"
   },
   "types": "./dist/index.d.ts",
   "module": "./dist/index.mjs",
@@ -129,7 +130,7 @@
     "test:ui": "vitest --ui",
     "docs": "typedoc",
     "docs:watch": "typedoc --watch",
-    "postdocs": "node -e \"console.log('Documentation generated in ./docs')\"",
+    "postdocs": "node -e \"console.log('Documentation generated in ./typedocs')\"",
     "analyze:size": "pnpm build:prod && node ./scripts/analyze-bundle-size.js"
   }
 }

package/readme/BUNDLE_OPTIMIZATION.md

@@ -0,0 +1,74 @@
+# Bundle Size Optimization Guide
+
+## Overview
+
+Functype is designed with tree-shaking in mind, allowing you to optimize your application's bundle size by only including the specific modules you need.
+
+## Import Strategies
+
+### Strategy 1: Selective Module Imports (Recommended)
+
+Import only the specific modules you need to reduce bundle size significantly.
+
+```typescript
+import { Option } from "functype/option"
+import { Either } from "functype/either"
+
+// Usage
+const option = Option.some(42)
+const either = Either.right("value")
+```
+
+### Strategy 2: Direct Constructor Imports (Smallest Bundle)
+
+For the most aggressive tree-shaking, import only the specific constructors and functions you need.
+
+```typescript
+import { some, none } from "functype/option"
+import { right } from "functype/either"
+
+// Usage
+const option = some(42)
+const none_value = none()
+const either = right("value")
+```
+
+## Bundle Size Comparison
+
+| Import Strategy | Approximate Bundle Size  | Best For                   |
+| --------------- | ------------------------ | -------------------------- |
+| Selective       | 200-500 bytes per module | Most applications          |
+| Direct          | <200 bytes per feature   | Size-critical applications |
+
+## Common Module Sizes
+
+| Module   | Approximate Size (minified) | Gzipped Size |
+| -------- | --------------------------- | ------------ |
+| Option   | ~200 bytes                  | ~140 bytes   |
+| Either   | ~290 bytes                  | ~190 bytes   |
+| List     | ~170 bytes                  | ~125 bytes   |
+| Try      | ~170 bytes                  | ~125 bytes   |
+| Tuple    | ~120 bytes                  | ~100 bytes   |
+| FPromise | ~200 bytes                  | ~140 bytes   |
+
+## Additional Tips
+
+1. **Import Analysis**: Use tools like [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) or [rollup-plugin-visualizer](https://github.com/btd/rollup-plugin-visualizer) to analyze your bundle and identify opportunities for optimization.
+
+2. **Dynamic Imports**: Consider using dynamic imports for rarely used functionality:
+
+   ```typescript
+   // Only load when needed
+   const useRareFeature = async () => {
+     const { someLargeUtility } = await import("functype/some-large-module")
+     return someLargeUtility()
+   }
+   ```
+
+3. **Development vs Production**: During development, you might prefer the convenience of importing everything. In production builds, switch to selective imports.
+
+4. **Peer Dependencies**: Functype has minimal dependencies, and the only external dependency (`safe-stable-stringify`) is quite small.
+
+## Need Help?
+
+If you need assistance with optimizing your bundle size further, please open an issue on our GitHub repository.

package/readme/FPromise-Assessment.md

@@ -0,0 +1,43 @@
+# FPromise Implementation Assessment
+
+## Overview
+
+This document provides an assessment of whether the FPromise implementation is ready to replace the old main branch version, with particular focus on potential impacts to implementing libraries outside this one.
+
+## Strengths of the FPromise Implementation
+
+1. **Comprehensive Error Handling**: FPromise provides rich error handling capabilities including `mapError`, `tapError`, `recover`, `recoverWith`, `recoverWithF`, `filterError`, and `logError`.
+
+2. **Either Integration**: FPromise has built-in conversion to/from Either with `toEither()` and `fromEither()`, which aligns well with the functional programming approach used in the Task implementation.
+
+3. **Promise Compatibility**: FPromise implements the PromiseLike interface, ensuring compatibility with async/await and standard Promise chains.
+
+4. **Extensive Test Coverage**: The test suite is comprehensive, covering basic functionality, error handling, recovery mechanisms, and real-world scenarios.
+
+5. **Retry Mechanisms**: The implementation includes multiple retry strategies (basic retry, retry with backoff, and retry with options).
+
+## Potential Compatibility Issues
+
+1. **Import Path Differences**: The Task.ts file imports from `"'core/throwable/Throwable"'` and `"'either/Either"'` with unusual quotes, while the actual imports should use `@/` prefix. This might cause issues if external libraries rely on these specific import paths.
+
+2. **Type Compatibility**: The Task implementation uses `Either<Throwable, T>` for error handling, while FPromise uses a more generic approach. Libraries expecting specific Either structures might need adjustments.
+
+3. **API Surface Changes**: External libraries that directly interact with the Promise implementation might need to adapt to the new methods and patterns provided by FPromise.
+
+## Recommendation
+
+The FPromise implementation is technically sound and provides significant improvements, but to avoid breaking implementing libraries outside this one:
+
+1. **Gradual Migration**: Consider a phased approach where both implementations coexist temporarily.
+
+2. **Version Bumping**: This change warrants a major version bump to signal potential breaking changes.
+
+3. **Documentation**: Provide clear migration guides for dependent libraries.
+
+4. **Import Path Fixes**: Ensure import paths are consistent and follow the project's conventions.
+
+5. **Compatibility Layer**: Consider providing a thin compatibility layer for libraries that can't immediately migrate to the new API.
+
+## Conclusion
+
+The FPromise implementation appears ready to replace the old main branch version from a technical perspective, but careful migration planning is necessary to minimize disruption to implementing libraries.

package/readme/HKT.md

@@ -0,0 +1,110 @@
+# Higher-Kinded Types (HKT)
+
+Higher-kinded types allow for writing generic code that works across different container types like `Option`, `List`, `Either`, and `Try`. This is a powerful abstraction that lets you create algorithms that work with any type that supports certain operations, without having to rewrite them for each specific type.
+
+## Introduction
+
+In functional programming, many operations like `map`, `flatMap`, or `sequence` follow similar patterns across different data structures. The HKT module provides a unified way to work with these operations for any supporting container type.
+
+## Key Concepts
+
+1. **Kind**: A type-level function representing a higher-kinded type relationship
+2. **Container Types**: Data structures that contain values (Option, List, Either, etc.)
+3. **Type Constructor**: A function that takes a type and returns a new type
+
+## Basic Operations
+
+### Map
+
+Apply a function to a value inside a container:
+
+```typescript
+import { Option, HKT } from "functype"
+
+const option = Option(42)
+const doubled = HKT.map(option, (x) => x * 2) // Option(84)
+```
+
+### FlatMap
+
+Apply a function that returns a container to a value inside a container, then flatten the result:
+
+```typescript
+const option = Option(42)
+const result = HKT.flatMap(option, (x) => Option(x * 2)) // Option(84)
+```
+
+### Flatten
+
+Flatten a nested container:
+
+```typescript
+const nestedOption = Option(Option(42))
+const flattened = HKT.flatten(nestedOption) // Option(42)
+```
+
+## Advanced Operations
+
+### Sequence
+
+Transform a container of containers into a container of container (e.g., `Option<List<A>>` to `List<Option<A>>`):
+
+```typescript
+const optionOfList = Option(List([1, 2, 3]))
+const listOfOptions = HKT.sequence(optionOfList)
+// List([Option(1), Option(2), Option(3)])
+```
+
+### Traverse
+
+Transform each element in a container using a function that returns another container type, then sequence the results:
+
+```typescript
+const list = List([1, 2, 3])
+const result = HKT.traverse(list, (x) => Option(x * 2))
+// Option(List([2, 4, 6]))
+```
+
+### Applicative (ap)
+
+Apply a function inside a container to a value inside another container:
+
+```typescript
+const optionFn = Option((x: number) => x * 2)
+const optionValue = Option(21)
+const result = HKT.ap(optionFn, optionValue) // Option(42)
+```
+
+## Supported Container Types
+
+The HKT module currently supports the following container types:
+
+- `Option<A>`
+- `List<A>`
+- `Either<E, A>`
+- `Try<A>`
+
+## Creating Generic Algorithms
+
+The power of HKT is in creating algorithms that work with any container type:
+
+```typescript
+// A function that works with any container implementing map
+function increment<F extends (a: number) => any>(container: Kind<F, number>): Kind<F, number> {
+  return HKT.map(container, (x) => x + 1)
+}
+
+// Works with any container
+increment(Option(41)) // Option(42)
+increment(List([1, 2, 3])) // List([2, 3, 4])
+increment(Right<string, number>(41)) // Right(42)
+```
+
+## Implementing Your Own Container Types
+
+To make your custom container types work with HKT, you need to:
+
+1. Implement the appropriate methods (`map`, `flatMap`, etc.)
+2. Add type checking in the HKT functions
+
+This allows seamless integration with the rest of the functional programming ecosystem.

package/readme/ROADMAP.md

@@ -0,0 +1,113 @@
+# Functype Roadmap (2025-2026)
+
+This roadmap outlines the planned development path for the Functype library, focusing on expanding functionality, improving performance, ensuring API consistency, and enhancing TypeScript integration.
+
+## Q2 2025: Core Functional Data Types
+
+### Lazy Evaluation
+
+- [ ] Implement `LazyList` / `Stream` for efficient processing of potentially infinite sequences
+- [ ] Add common operations: `map`, `filter`, `take`, `drop`, etc.
+- [ ] Implement memoization for evaluated values
+
+### Validation Type
+
+- [ ] Create `Validation` data type for applicative validation
+- [ ] Support collecting multiple errors (unlike Either which short-circuits)
+- [ ] Add utilities for combining validation results
+
+### Performance Foundation
+
+- [ ] Add memoization utilities for expensive function calls
+- [ ] Implement a basic benchmarking suite for measuring performance
+- [ ] Standardize performance metrics across data structures
+
+## Q3 2025: Advanced Functional Patterns & Optimizations
+
+### Type Classes
+
+- [x] Implement `Foldable` typeclass with fold, foldLeft, and foldRight methods
+- [x] Implement `Matchable` typeclass for pattern matching
+- [ ] Implement proper `Functor` and `Monad` typeclasses
+- [ ] Add `Applicative` typeclass
+- [ ] Support `Traversable` with comprehensive HKT
+
+### Monad Implementations
+
+- [ ] Implement `Reader` monad for dependency injection
+- [ ] Add `State` monad for managing state transformations
+- [ ] Create `IO` monad for pure handling of side effects
+- [ ] Add comprehensive documentation and examples
+
+### Performance Improvements
+
+- [ ] Implement structural sharing for immutable collections
+- [ ] Optimize recursive operations for large data structures
+- [ ] Add performance comparison against other FP libraries
+
+### Lenses & Optics
+
+- [ ] Implement lens abstraction for immutable updates
+- [ ] Add prism implementation for optional data
+- [ ] Create utilities for composing lenses and prisms
+
+## Q4 2025: TypeScript Enhancements & API Consistency
+
+### TypeScript Integration
+
+- [x] Add support for higher-kinded types
+- [ ] Remove `any` from HKT
+- [x] Implement branded/nominal types for stronger type safety
+- [ ] Add type-level utilities using newer TypeScript features
+- [ ] Leverage const type parameters and tuple manipulation
+
+### API Normalization
+
+- [ ] Review and standardize API across all modules
+- [ ] Ensure consistent implementation of the Scala-inspired pattern
+- [ ] Standardize import patterns (@imports throughout)
+- [ ] Create migration guides for API changes
+
+## Q1 2026: Testing, Documentation & Community Support
+
+### Testing Expansion
+
+- [ ] Add test coverage metrics and set coverage goals
+- [ ] Expand property-based testing across all modules
+- [ ] Create interoperability tests with popular libraries
+- [ ] Add more specialized test cases for error handling
+
+### Documentation & Examples
+
+- [ ] Add comprehensive documentation for all modules
+- [ ] Create step-by-step migration guides from imperative to functional
+- [ ] Add real-world examples showcasing practical applications
+- [ ] Create tutorial sections for beginners
+
+### Community Engagement
+
+- [ ] Create contribution guidelines and templates
+- [ ] Set up automated issue/PR handling
+- [ ] Establish regular release schedule
+- [ ] Add community forum/discussion platform
+
+## Ongoing Priorities
+
+### Compatibility
+
+- [ ] Ensure compatibility with Node.js LTS versions
+- [ ] Maintain browser compatibility
+- [ ] Support for Deno and other runtimes
+- [ ] Test with various bundlers (webpack, esbuild, etc.)
+
+### Bundle Size
+
+- [x] Optimize tree-shaking
+- [x] Provide guidance on importing only needed modules
+- [x] Add bundle size monitoring to CI/CD
+
+### Community Feedback
+
+- [ ] Regular review of GitHub issues and feature requests
+- [ ] Prioritization based on community needs
+- [ ] Transparent development process