feat(result): add AsyncResult for point-free async chaining

- Introduce `AsyncResult<Ok, Fail>` wrapper around `Promise<Result<...>>`
- Provide chainable `map`, `mapAsync`, `flatMap`, `flatMapAsync`, `chain`,
  `match`, `matchAsync`, `toPromise`, and `all`
- Export `AsyncResult` via `src/result/public_api.ts`
- Add comprehensive tests with 100% coverage

Addresses the pain called out in #171 about point-free async ergonomics.

Author: CharlieHelps

src/result/async-result.spec.ts

@@ -0,0 +1,140 @@
+import { ok, fail } from './result.factory'
+import { AsyncResult } from './async-result'
+
+describe(AsyncResult.name, () => {
+  it('should allow point-free async chaining with map/mapAsync/flatMap/flatMapAsync', async () => {
+    const res = AsyncResult.ok<number, string>(2)
+      .map(n => n + 1) // 3
+      .mapAsync(async n => n * 2) // 6
+      .flatMap(x => ok<string, string>(String(x))) // Ok('6')
+      .flatMapAsync(async s => ok<string, string>(s + '!')) // Ok('6!')
+
+    const final = await res.toPromise()
+    expect(final.isOk()).toBe(true)
+    expect(final.unwrap()).toBe('6!')
+  })
+
+  it('should propagate failures across async boundaries', async () => {
+    const res = AsyncResult.ok<number, string>(1)
+      .mapAsync(async () => {
+        throw 'bad'
+      })
+      .map(n => n + 1)
+      .flatMap(() => ok<number, string>(999))
+
+    const final = await res.toPromise()
+    expect(final.isFail()).toBe(true)
+    expect(final.unwrapFail()).toBe('bad')
+  })
+
+  it('fromPromise should wrap resolve/reject into Result and support chaining', async () => {
+    const okAr = AsyncResult.fromPromise<number, string>(Promise.resolve(5)).map(n => n * 2)
+    const okFinal = await okAr.toPromise()
+    expect(okFinal.isOk()).toBe(true)
+    expect(okFinal.unwrap()).toBe(10)
+
+    const failAr = AsyncResult.fromPromise<number, string>(Promise.reject('nope')).map(n => n * 2)
+    const failFinal = await failAr.toPromise()
+    expect(failFinal.isFail()).toBe(true)
+    expect(failFinal.unwrapFail()).toBe('nope')
+  })
+
+  it('flatMapAsync should flatten Promise<Result<...>>', async () => {
+    const ar = AsyncResult.ok<number, string>(1).flatMapAsync(async (n) => {
+      return n > 0 ? ok<number, string>(n + 1) : fail<number, string>('neg')
+    })
+
+    const final = await ar.toPromise()
+    expect(final.isOk()).toBe(true)
+    expect(final.unwrap()).toBe(2)
+  })
+
+  it('chain should accept a function returning AsyncResult and keep it point-free', async () => {
+    const incAsync = (n: number): AsyncResult<number, string> => AsyncResult.ok<number, string>(n + 1)
+
+    const ar = AsyncResult.ok<number, string>(3)
+      .chain(incAsync)
+      .chain(incAsync)
+
+    const final = await ar.toPromise()
+    expect(final.isOk()).toBe(true)
+    expect(final.unwrap()).toBe(5)
+  })
+
+  it('all should collect Ok values and fail on the first failure', async () => {
+    const a = AsyncResult.ok<number, string>(1)
+    const b = AsyncResult.fromPromise<number, string>(Promise.resolve(2))
+    const c = AsyncResult.ok<number, string>(3)
+
+    const allOk = await AsyncResult.all([a, b, c]).toPromise()
+    expect(allOk.isOk()).toBe(true)
+    expect(allOk.unwrap()).toEqual([1, 2, 3])
+
+    const bad = AsyncResult.fail<number, string>('oops')
+    const allFail = await AsyncResult.all([a, bad, c]).toPromise()
+    expect(allFail.isFail()).toBe(true)
+    expect(allFail.unwrapFail()).toBe('oops')
+  })
+
+  it('fromResult and fromResultPromise should wrap existing Results', async () => {
+    const syncOk = AsyncResult.fromResult(ok<number, string>(1))
+    const okFinal = await syncOk.toPromise()
+    expect(okFinal.isOk()).toBe(true)
+    expect(okFinal.unwrap()).toBe(1)
+
+    const syncFail = AsyncResult.fromResult(fail<number, string>('e'))
+    const failFinal = await syncFail.toPromise()
+    expect(failFinal.isFail()).toBe(true)
+    expect(failFinal.unwrapFail()).toBe('e')
+
+    const p = Promise.resolve(ok<number, string>(7))
+    const fromPromiseResult = await AsyncResult.fromResultPromise(p).toPromise()
+    expect(fromPromiseResult.isOk()).toBe(true)
+    expect(fromPromiseResult.unwrap()).toBe(7)
+
+    const viaFromResult = await AsyncResult.fromResult(Promise.resolve(ok<number, string>(42))).toPromise()
+    expect(viaFromResult.isOk()).toBe(true)
+    expect(viaFromResult.unwrap()).toBe(42)
+  })
+
+  it('mapFail should transform the error', async () => {
+    const ar = AsyncResult.fail<number, Error>(new Error('x')).mapFail(e => e.message)
+    const final = await ar.toPromise()
+    expect(final.isFail()).toBe(true)
+    expect(final.unwrapFail()).toBe('x')
+  })
+
+  it('flatMapAsync should catch thrown/rejected errors and convert to Fail', async () => {
+    const ar = AsyncResult.ok<number, string>(1).flatMapAsync(async () => {
+      throw 'oops'
+    })
+    const final = await ar.toPromise()
+    expect(final.isFail()).toBe(true)
+    expect(final.unwrapFail()).toBe('oops')
+  })
+
+  it('flatMapAsync and chain should short-circuit when initial AsyncResult is Fail', async () => {
+    const fm = await AsyncResult.fail<number, string>('bad')
+      .flatMapAsync(async n => ok<number, string>(n + 1))
+      .toPromise()
+    expect(fm.isFail()).toBe(true)
+    expect(fm.unwrapFail()).toBe('bad')
+
+    const chained = await AsyncResult.fail<number, string>('bad')
+      .chain(n => AsyncResult.ok<number, string>(n + 1))
+      .toPromise()
+    expect(chained.isFail()).toBe(true)
+    expect(chained.unwrapFail()).toBe('bad')
+  })
+
+  it('match and matchAsync should resolve with the proper branch', async () => {
+    const m1 = await AsyncResult.ok<number, string>(2).match({ ok: n => n * 2, fail: _ => -1 })
+    expect(m1).toBe(4)
+
+    const m2 = await AsyncResult.ok<number, string>(3).matchAsync({ ok: async n => n * 3, fail: async _ => -1 })
+    expect(m2).toBe(9)
+
+    const m3 = await AsyncResult.fail<number, string>('x').matchAsync({ ok: async _ => 0, fail: async e => e.length })
+    expect(m3).toBe(1)
+  })
+})

src/result/async-result.ts

@@ -0,0 +1,101 @@
+import type { IResult } from './result.interface'
+import { Result } from './result'
+
+/**
+* AsyncResult is a thin wrapper around Promise<Result<Ok, Fail>> that preserves
+* the point-free, chainable API developers expect from Result while crossing
+* async boundaries. Methods return AsyncResult so you can keep chaining without
+* mixing in `.then` calls until the very end (use `toPromise()` to unwrap).
+*/
+export class AsyncResult<TOk, TFail> {
+  private readonly promise: Promise<IResult<TOk, TFail>>
+
+  private constructor(promise: Promise<IResult<TOk, TFail>>) {
+    this.promise = promise
+  }
+
+  // Constructors / factories
+  static ok<TOk, TFail = never>(value: TOk): AsyncResult<TOk, TFail> {
+    return new AsyncResult<TOk, TFail>(Promise.resolve(Result.ok<TOk, TFail>(value)))
+  }
+
+  static fail<TOk = never, TFail = unknown>(error: TFail): AsyncResult<TOk, TFail> {
+    return new AsyncResult<TOk, TFail>(Promise.resolve(Result.fail<TOk, TFail>(error)))
+  }
+
+  static fromResult<TOk, TFail>(result: IResult<TOk, TFail> | Promise<IResult<TOk, TFail>>): AsyncResult<TOk, TFail> {
+    const p = result instanceof Promise ? result : Promise.resolve(result)
+    return new AsyncResult<TOk, TFail>(p)
+  }
+
+  static fromResultPromise<TOk, TFail>(promise: Promise<IResult<TOk, TFail>>): AsyncResult<TOk, TFail> {
+    return new AsyncResult<TOk, TFail>(promise)
+  }
+
+  static fromPromise<TOk, TFail = unknown>(promise: Promise<TOk>): AsyncResult<TOk, TFail> {
+    return new AsyncResult<TOk, TFail>(Result.fromPromise<TOk, TFail>(promise))
+  }
+
+  static all<T, E>(items: ReadonlyArray<AsyncResult<T, E>>): AsyncResult<ReadonlyArray<T>, E> {
+    const p = Promise.all(items.map(i => i.promise)).then(results => Result.sequence(results))
+    return new AsyncResult<ReadonlyArray<T>, E>(p)
+  }
+
+  // Core instance methods
+  map<M>(fn: (val: TOk) => M): AsyncResult<M, TFail> {
+    const p = this.promise.then(r => r.map(fn))
+    return new AsyncResult<M, TFail>(p)
+  }
+
+  mapFail<M>(fn: (err: TFail) => M): AsyncResult<TOk, M> {
+    const p = this.promise.then(r => r.mapFail(fn))
+    return new AsyncResult<TOk, M>(p)
+  }
+
+  flatMap<M>(fn: (val: TOk) => IResult<M, TFail>): AsyncResult<M, TFail> {
+    const p = this.promise.then(r => r.flatMap(fn))
+    return new AsyncResult<M, TFail>(p)
+  }
+
+  mapAsync<M>(fn: (val: TOk) => Promise<M>): AsyncResult<M, TFail> {
+    const p = this.promise.then(r => r.flatMapPromise(fn))
+    return new AsyncResult<M, TFail>(p)
+  }
+
+  flatMapAsync<M>(fn: (val: TOk) => Promise<IResult<M, TFail>>): AsyncResult<M, TFail> {
+    const p = this.promise.then(async r => {
+      if (r.isOk()) {
+        try {
+          const next = await fn(r.unwrap())
+          return next
+        } catch (e) {
+          return Result.fail<M, TFail>(e as TFail)
+        }
+      }
+      return Result.fail<M, TFail>(r.unwrapFail())
+    })
+    return new AsyncResult<M, TFail>(p)
+  }
+
+  chain<M>(fn: (val: TOk) => AsyncResult<M, TFail>): AsyncResult<M, TFail> {
+    const p = this.promise.then(r => {
+      if (r.isOk()) {
+        return fn(r.unwrap()).promise
+      }
+      return Promise.resolve(Result.fail<M, TFail>(r.unwrapFail()))
+    })
+    return new AsyncResult<M, TFail>(p)
+  }
+
+  match<M>(pattern: { ok: (val: TOk) => M; fail: (err: TFail) => M }): Promise<M> {
+    return this.promise.then(r => r.match(pattern))
+  }
+
+  matchAsync<M>(pattern: { ok: (val: TOk) => Promise<M>; fail: (err: TFail) => Promise<M> }): Promise<M> {
+    return this.promise.then(r => (r.isOk() ? pattern.ok(r.unwrap()) : pattern.fail(r.unwrapFail())))
+  }
+
+  toPromise(): Promise<IResult<TOk, TFail>> {
+    return this.promise
+  }
+}

src/result/public_api.ts

@@ -1,6 +1,7 @@
 export * from './result'
 export * from './result.factory'
 export * from './result.interface'
+export * from './async-result'
 export * from './transformers/result-to-promise'
 export * from './transformers/try-catch-to-result'
 export * from './transformers/unwrap-result'