functype 0.9.3 → 0.9.4

package/dist/either/index.mjs

@@ -1,2 +1,2 @@
-export{q as Either,j as Left,i as Right,o as TypeCheckLeft,n as TypeCheckRight,l as isLeft,k as isRight,m as tryCatch,p as tryCatchAsync}from'../chunk-4WBZOSQH.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-ECL55NTP.mjs';//# sourceMappingURL=index.mjs.map
+export{q as Either,j as Left,i as Right,o as TypeCheckLeft,n as TypeCheckRight,l as isLeft,k as isRight,m as tryCatch,p as tryCatchAsync}from'../chunk-Q45K2ZSV.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-ECL55NTP.mjs';//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/fpromise/index.mjs

@@ -1,2 +1,2 @@
-export{K as FPromise,J as FPromiseCompanion}from'../chunk-4WBZOSQH.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-ECL55NTP.mjs';//# sourceMappingURL=index.mjs.map
+export{K as FPromise,J as FPromiseCompanion}from'../chunk-Q45K2ZSV.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-ECL55NTP.mjs';//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/index.d.ts

@@ -11,16 +11,19 @@ export { TypeNames } from './try/index.js';
 export { Map, SafeTraversable } from './map/index.js';
 export { Tuple } from './tuple/index.js';
 
-interface ValidatedBrand<K extends string, T> {
+interface ValidatedBrandCompanion<K extends string, T> {
     readonly brand: K;
     readonly validate: (value: T) => boolean;
-    readonly of: (value: T) => Option<Brand<K, T>>;
-    readonly from: (value: T) => Either<string, Brand<K, T>>;
-    readonly unsafeOf: (value: T) => Brand<K, T>;
-    readonly is: (value: unknown) => value is Brand<K, T>;
+    readonly of: (value: T) => Option<ValidatedBrand<K, T>>;
+    readonly from: (value: T) => Either<string, ValidatedBrand<K, T>>;
+    readonly unsafeOf: (value: T) => ValidatedBrand<K, T>;
+    readonly is: (value: unknown) => value is ValidatedBrand<K, T>;
     readonly unwrap: (branded: Brand<K, T>) => T;
-    readonly refine: <K2 extends string>(brand: K2, validate: (value: Brand<K, T>) => boolean) => ValidatedBrand<K2, Brand<K, T>>;
+    readonly refine: <K2 extends string>(brand: K2, validate: (value: Brand<K, T>) => boolean) => ValidatedBrandCompanion<K2, Brand<K, T>>;
 }
+type ValidatedBrand<K extends string, T> = Brand<K, T> & {
+    readonly __validated: true;
+};
 /**
  * Create a validated brand with runtime validation
  * @example
@@ -40,7 +43,7 @@ interface ValidatedBrand<K extends string, T> {
  *   // value is Brand<"Email", string>
  * }
  */
-declare function ValidatedBrand<K extends string, T>(brand: K, validate: (value: T) => boolean): ValidatedBrand<K, T>;
+declare function ValidatedBrand<K extends string, T>(brand: K, validate: (value: T) => boolean): ValidatedBrandCompanion<K, T>;
 /**
  * Positive number brand (> 0)
  * @example
@@ -48,17 +51,17 @@ declare function ValidatedBrand<K extends string, T>(brand: K, validate: (value:
  * const invalid = PositiveNumber.of(-5) // None
  * const checked = PositiveNumber.from(0) // Left("Invalid PositiveNumber: validation failed")
  */
-declare const PositiveNumber: ValidatedBrand<"PositiveNumber", number>;
-declare const NonNegativeNumber: ValidatedBrand<"NonNegativeNumber", number>;
-declare const IntegerNumber: ValidatedBrand<"IntegerNumber", number>;
-declare const PositiveInteger: ValidatedBrand<"PositiveInteger", Brand<"PositiveNumber", number>>;
+declare const PositiveNumber: ValidatedBrandCompanion<"PositiveNumber", number>;
+declare const NonNegativeNumber: ValidatedBrandCompanion<"NonNegativeNumber", number>;
+declare const IntegerNumber: ValidatedBrandCompanion<"IntegerNumber", number>;
+declare const PositiveInteger: ValidatedBrandCompanion<"PositiveInteger", Brand<"PositiveNumber", number>>;
 /**
  * Non-empty string brand
  * @example
  * const name = NonEmptyString.of("John") // Some(Brand<"NonEmptyString", string>)
  * const empty = NonEmptyString.of("") // None
  */
-declare const NonEmptyString: ValidatedBrand<"NonEmptyString", string>;
+declare const NonEmptyString: ValidatedBrandCompanion<"NonEmptyString", string>;
 /**
  * Email address brand with basic validation
  * @example
@@ -73,10 +76,10 @@ declare const NonEmptyString: ValidatedBrand<"NonEmptyString", string>;
  *     .getOrElse("Invalid email address")
  * }
  */
-declare const EmailAddress: ValidatedBrand<"EmailAddress", string>;
-declare const UrlString: ValidatedBrand<"UrlString", string>;
-declare const UUID: ValidatedBrand<"UUID", string>;
-declare const ISO8601Date: ValidatedBrand<"ISO8601Date", string>;
+declare const EmailAddress: ValidatedBrandCompanion<"EmailAddress", string>;
+declare const UrlString: ValidatedBrandCompanion<"UrlString", string>;
+declare const UUID: ValidatedBrandCompanion<"UUID", string>;
+declare const ISO8601Date: ValidatedBrandCompanion<"ISO8601Date", string>;
 /**
  * Create a number brand with min/max bounds
  * @example
@@ -89,7 +92,7 @@ declare const ISO8601Date: ValidatedBrand<"ISO8601Date", string>;
  * const httpPort = Port.unsafeOf(80) // Brand<"Port", number>
  * // Port.unsafeOf(70000) // throws Error
  */
-declare function BoundedNumber(brand: string, min: number, max: number): ValidatedBrand<string, number>;
+declare function BoundedNumber(brand: string, min: number, max: number): ValidatedBrandCompanion<string, number>;
 /**
  * Create a string brand with length constraints
  * @example
@@ -98,7 +101,7 @@ declare function BoundedNumber(brand: string, min: number, max: number): Validat
  * const tooShort = Username.of("jo") // None
  * const tooLong = Username.of("verylongusernamethatexceedslimit") // None
  */
-declare function BoundedString(brand: string, minLength: number, maxLength: number): ValidatedBrand<string, string>;
+declare function BoundedString(brand: string, minLength: number, maxLength: number): ValidatedBrandCompanion<string, string>;
 /**
  * Create a string brand that matches a regex pattern
  * @example
@@ -112,7 +115,7 @@ declare function BoundedString(brand: string, minLength: number, maxLength: numb
  *   .map(p => formatPhoneNumber(p))
  *   .getOrElse("Invalid phone number")
  */
-declare function PatternString(brand: string, pattern: RegExp): ValidatedBrand<string, string>;
+declare function PatternString(brand: string, pattern: RegExp): ValidatedBrandCompanion<string, string>;
 
 /**
  * Creates a function-object hybrid similar to Scala's companion objects.
@@ -1734,4 +1737,4 @@ declare const Stack: (<A extends Type>(values?: A[]) => Stack<A>) & {
     fromBinary: <A>(binary: string) => Stack<A>;
 };
 
-export { type Async, Base, BoundedNumber, BoundedString, Brand, type CancellationToken, type CancellationTokenSource, Companion, Cond, ESMap, type ESMapType, Either, type EitherKind, EmailAddress, type ErrorChainElement, type ErrorCode, type ErrorFormatterOptions, type ErrorMessage, type ErrorStatus, type ErrorWithTaskInfo, Extractable, FPromise, type FieldValidation, Foldable, FoldableUtils, type FormValidation, FunctypeBase, HKT, ISO8601Date, Identity, IntegerNumber, type Kind, Lazy, LazyList, Lazy as LazyType, List, type ListKind, Match, Matchable, NAME, NonEmptyString, NonNegativeNumber, Option, type OptionKind, ParseError, PatternString, Pipe, PositiveInteger, PositiveNumber, Ref, Ref as RefType, Serializable, Stack, type Sync, type TaggedThrowable, Task, type TaskErrorInfo, TaskException, type TaskInfo, type TaskParams, TaskResult, Throwable, type ThrowableType, Traversable, Try, type TryKind, Type, Typeable, TypedError, type TypedErrorContext, UUID, type UniversalContainer, UrlString, ValidatedBrand, Validation, type ValidationRule, type Validator, Valuable, type ValuableParams, createCancellationTokenSource, createErrorSerializer, formatError, formatStackTrace, isTaggedThrowable, safeStringify };
+export { type Async, Base, BoundedNumber, BoundedString, Brand, type CancellationToken, type CancellationTokenSource, Companion, Cond, ESMap, type ESMapType, Either, type EitherKind, EmailAddress, type ErrorChainElement, type ErrorCode, type ErrorFormatterOptions, type ErrorMessage, type ErrorStatus, type ErrorWithTaskInfo, Extractable, FPromise, type FieldValidation, Foldable, FoldableUtils, type FormValidation, FunctypeBase, HKT, ISO8601Date, Identity, IntegerNumber, type Kind, Lazy, LazyList, Lazy as LazyType, List, type ListKind, Match, Matchable, NAME, NonEmptyString, NonNegativeNumber, Option, type OptionKind, ParseError, PatternString, Pipe, PositiveInteger, PositiveNumber, Ref, Ref as RefType, Serializable, Stack, type Sync, type TaggedThrowable, Task, type TaskErrorInfo, TaskException, type TaskInfo, type TaskParams, TaskResult, Throwable, type ThrowableType, Traversable, Try, type TryKind, Type, Typeable, TypedError, type TypedErrorContext, UUID, type UniversalContainer, UrlString, ValidatedBrand, type ValidatedBrandCompanion, Validation, type ValidationRule, type Validator, Valuable, type ValuableParams, createCancellationTokenSource, createErrorSerializer, formatError, formatStackTrace, isTaggedThrowable, safeStringify };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-export{G as Base,B as BoundedNumber,C as BoundedString,E as Cond,ca as ESMap,q as Either,x as EmailAddress,K as FPromise,J as FPromiseCompanion,Z as FoldableUtils,$ as HKT,A as ISO8601Date,aa as Identity,u as IntegerNumber,ba as Lazy,W as LazyList,j as Left,h as List,da as Map,F as Match,ea as MatchableUtils,H as NAME,w as NonEmptyString,t as NonNegativeNumber,b as None,d as Option,c as OptionConstructor,U as ParseError,D as PatternString,v as PositiveInteger,s as PositiveNumber,fa as Ref,i as Right,e as Set,a as Some,ha as Stack,P as Task,M as TaskException,N as TaskResult,I as Throwable,_ as Try,o as TypeCheckLeft,n as TypeCheckRight,f as Typeable,V as TypedError,z as UUID,y as UrlString,r as ValidatedBrand,X as Validation,ga as Valuable,O as createCancellationTokenSource,T as createErrorSerializer,S as formatError,R as formatStackTrace,Y as isExtractable,l as isLeft,k as isRight,L as isTaggedThrowable,g as isTypeable,Q as safeStringify,m as tryCatch,p as tryCatchAsync}from'./chunk-4WBZOSQH.mjs';export{a as Companion,b as Tuple}from'./chunk-BQJB6CCW.mjs';export{a as Brand,g as BrandedBoolean,f as BrandedNumber,e as BrandedString,d as createBrander,c as hasBrand,b as unbrand}from'./chunk-ECL55NTP.mjs';//# sourceMappingURL=index.mjs.map
+export{G as Base,B as BoundedNumber,C as BoundedString,E as Cond,ca as ESMap,q as Either,x as EmailAddress,K as FPromise,J as FPromiseCompanion,Z as FoldableUtils,$ as HKT,A as ISO8601Date,aa as Identity,u as IntegerNumber,ba as Lazy,W as LazyList,j as Left,h as List,da as Map,F as Match,ea as MatchableUtils,H as NAME,w as NonEmptyString,t as NonNegativeNumber,b as None,d as Option,c as OptionConstructor,U as ParseError,D as PatternString,v as PositiveInteger,s as PositiveNumber,fa as Ref,i as Right,e as Set,a as Some,ha as Stack,P as Task,M as TaskException,N as TaskResult,I as Throwable,_ as Try,o as TypeCheckLeft,n as TypeCheckRight,f as Typeable,V as TypedError,z as UUID,y as UrlString,r as ValidatedBrand,X as Validation,ga as Valuable,O as createCancellationTokenSource,T as createErrorSerializer,S as formatError,R as formatStackTrace,Y as isExtractable,l as isLeft,k as isRight,L as isTaggedThrowable,g as isTypeable,Q as safeStringify,m as tryCatch,p as tryCatchAsync}from'./chunk-Q45K2ZSV.mjs';export{a as Companion,b as Tuple}from'./chunk-BQJB6CCW.mjs';export{a as Brand,g as BrandedBoolean,f as BrandedNumber,e as BrandedString,d as createBrander,c as hasBrand,b as unbrand}from'./chunk-ECL55NTP.mjs';//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/list/index.mjs

@@ -1,2 +1,2 @@
-export{h as List}from'../chunk-4WBZOSQH.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-ECL55NTP.mjs';//# sourceMappingURL=index.mjs.map
+export{h as List}from'../chunk-Q45K2ZSV.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-ECL55NTP.mjs';//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/map/index.mjs

@@ -1,2 +1,2 @@
-export{da as Map}from'../chunk-4WBZOSQH.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-ECL55NTP.mjs';//# sourceMappingURL=index.mjs.map
+export{da as Map}from'../chunk-Q45K2ZSV.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-ECL55NTP.mjs';//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/option/index.mjs

@@ -1,2 +1,2 @@
-export{b as None,d as Option,c as OptionConstructor,a as Some}from'../chunk-4WBZOSQH.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-ECL55NTP.mjs';//# sourceMappingURL=index.mjs.map
+export{b as None,d as Option,c as OptionConstructor,a as Some}from'../chunk-Q45K2ZSV.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-ECL55NTP.mjs';//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/set/index.mjs

@@ -1,2 +1,2 @@
-export{e as Set}from'../chunk-4WBZOSQH.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-ECL55NTP.mjs';//# sourceMappingURL=index.mjs.map
+export{e as Set}from'../chunk-Q45K2ZSV.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-ECL55NTP.mjs';//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/try/index.mjs

@@ -1,2 +1,2 @@
-export{_ as Try}from'../chunk-4WBZOSQH.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-ECL55NTP.mjs';//# sourceMappingURL=index.mjs.map
+export{_ as Try}from'../chunk-Q45K2ZSV.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-ECL55NTP.mjs';//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functype",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "type": "module",
   "description": "A smallish functional library for TypeScript",
   "author": "jordan.burke@gmail.com",

package/readme/BRAND_MIGRATION_GUIDE.md

@@ -0,0 +1,230 @@
+# Brand Type Migration Guide
+
+This guide helps you migrate from the old object-based Brand implementation to the new phantom type implementation.
+
+## What Changed?
+
+### Old Implementation (Object Wrappers)
+
+- Branded values were **objects** with methods
+- Required `.unbrand()` or `.unwrap()` to access the primitive value
+- `typeof brandedString === "object"`
+- Object overhead and indexed properties
+
+### New Implementation (Phantom Types)
+
+- Branded values **ARE** the primitive values
+- No unwrapping needed - use directly
+- `typeof brandedString === "string"`
+- Zero runtime overhead
+
+## Migration Steps
+
+### 1. Remove `.unbrand()` and `.unwrap()` calls
+
+**Before:**
+
+```typescript
+const userId = Brand("UserId", "user-123")
+const id = userId.unbrand() // Had to unwrap
+console.log(`User: ${userId.unbrand()}`)
+```
+
+**After:**
+
+```typescript
+const userId = Brand("UserId", "user-123")
+const id = userId // It IS the string!
+console.log(`User: ${userId}`)
+```
+
+### 2. Remove `.toString()` for custom formatting
+
+**Before:**
+
+```typescript
+const userId = Brand("UserId", "user-123")
+console.log(userId.toString()) // "UserId(user-123)"
+```
+
+**After:**
+
+```typescript
+const userId = Brand("UserId", "user-123")
+console.log(userId.toString()) // "user-123" - standard string method
+console.log(userId) // "user-123"
+```
+
+### 3. Update ValidatedBrand usage
+
+**Before:**
+
+```typescript
+const email = EmailAddress.of("user@example.com")
+if (!email.isEmpty) {
+  const branded = email.get()
+  sendEmail(branded.unbrand()) // Had to unwrap
+}
+```
+
+**After:**
+
+```typescript
+const email = EmailAddress.of("user@example.com")
+if (!email.isEmpty) {
+  const branded = email.get()
+  sendEmail(branded) // It IS a string!
+}
+```
+
+### 4. Update refine validators
+
+**Before:**
+
+```typescript
+const SmallPositive = PositiveNumber.refine("SmallPositive", (n) => {
+  return n.unbrand() < 100 // Had to unwrap
+})
+```
+
+**After:**
+
+```typescript
+const SmallPositive = PositiveNumber.refine("SmallPositive", (n) => {
+  return n < 100 // n IS a number!
+})
+```
+
+### 5. Remove type assertions for external APIs
+
+**Before:**
+
+```typescript
+const config = {
+  userId: userId.unbrand(),
+  port: port.unbrand(),
+}
+await api.request(config)
+```
+
+**After:**
+
+```typescript
+const config = {
+  userId, // Already a string!
+  port, // Already a number!
+}
+await api.request(config)
+```
+
+## Common Patterns
+
+### Working with Option/Either
+
+When extracting branded values from Option or Either, you may need to adjust default values:
+
+**Before:**
+
+```typescript
+const email = EmailAddress.of(input)
+const value = email.map((e) => e.unbrand()).getOrElse("")
+```
+
+**After (Option 1 - Keep branded type):**
+
+```typescript
+const email = EmailAddress.of(input)
+const value = email.getOrElse("" as Brand<"EmailAddress", string>)
+```
+
+**After (Option 2 - Use fold for clean extraction):**
+
+```typescript
+const email = EmailAddress.of(input)
+const value = email.fold(
+  () => "", // Default value
+  (e) => e, // e IS already a string!
+)
+```
+
+### Type-safe functions
+
+Function signatures don't change, but implementation is cleaner:
+
+**Before:**
+
+```typescript
+function processUser(userId: Brand<"UserId", string>) {
+  const id = userId.unbrand()
+  return db.query(`SELECT * FROM users WHERE id = '${id}'`)
+}
+```
+
+**After:**
+
+```typescript
+function processUser(userId: Brand<"UserId", string>) {
+  return db.query(`SELECT * FROM users WHERE id = '${userId}'`)
+}
+```
+
+## Benefits After Migration
+
+1. **Better Performance**: No object allocation overhead
+2. **Cleaner Code**: No more `.unbrand()` calls everywhere
+3. **Natural JavaScript**: String interpolation, JSON serialization work directly
+4. **Smaller Bundles**: Less code to ship
+5. **Better Debugging**: Values show as primitives in debugger
+
+## Compatibility
+
+### If you need the old behavior
+
+The `unbrand` utility function still exists for compatibility:
+
+```typescript
+import { unbrand } from "@/branded"
+
+const userId = Brand("UserId", "user-123")
+const plain = unbrand(userId) // Works but unnecessary
+```
+
+ValidatedBrand also provides an `unwrap` method:
+
+```typescript
+const email = EmailAddress.unsafeOf("user@example.com")
+const plain = EmailAddress.unwrap(email) // Works but unnecessary
+```
+
+## Quick Reference
+
+| Old Code                             | New Code                    |
+| ------------------------------------ | --------------------------- |
+| `value.unbrand()`                    | `value`                     |
+| `value.unwrap()`                     | `value`                     |
+| `value.toString()`                   | `value` or `String(value)`  |
+| `typeof value === "object"`          | `typeof value === "string"` |
+| `${value.unbrand()}`                 | `${value}`                  |
+| `JSON.stringify({id: id.unbrand()})` | `JSON.stringify({id})`      |
+
+## Testing
+
+Update your tests to expect primitives:
+
+**Before:**
+
+```typescript
+expect(typeof userId).toBe("object")
+expect(userId.unbrand()).toBe("user-123")
+```
+
+**After:**
+
+```typescript
+expect(typeof userId).toBe("string")
+expect(userId).toBe("user-123")
+```
+
+## Summary
+
+The migration is mostly about **removing code**. Branded values now work exactly like their underlying primitive types, making the code cleaner and more performant. The type safety remains unchanged - you still get full compile-time protection against mixing different branded types.