nalloc 0.0.1 → 0.0.2

package/src/result.ts

@@ -1,5 +1,5 @@
-import { err as ERR, isOk, isErr, isSome, isNone, NONE, optionOf } from './types.js';
-import type { Ok, Err, Result, Option, Widen, WidenNever } from './types.js';
+import { err as ERR, isOk, isErr, isSome, isNone, NONE, optionOf, isThenable } from './types.js';
+import type { Ok, Err, Result, Option, Widen, WidenNever, MaybePromise } from './types.js';
 
 export type { Ok, Err, Result };
 export { isOk, isErr };
@@ -14,6 +14,8 @@ export { isOk, isErr };
  * tryCatch(() => JSON.parse('invalid'))     // Err(SyntaxError)
  * tryCatch(() => { throw 'oops' }, e => e)  // Err('oops')
  */
+export function tryCatch<T>(fn: () => T): Result<T, unknown>;
+export function tryCatch<T, E>(fn: () => T, onError: (error: unknown) => E): Result<T, E>;
 export function tryCatch<T, E = unknown>(fn: () => T, onError?: (error: unknown) => E): Result<T, E> {
   try {
     return fn() as Ok<T>;
@@ -27,52 +29,37 @@ export function tryCatch<T, E = unknown>(fn: () => T, onError?: (error: unknown)
  * @param fn - Function to execute
  * @returns Ok(result) if successful, Err(error) if thrown
  */
-export function of<T, E = unknown>(fn: () => T): Result<T, E> {
+export function of<T>(fn: () => T): Result<T, unknown> {
   return tryCatch(fn);
 }
 
 /**
- * Executes an async function and captures the result or error.
- * @param fn - Async function to execute
+ * Executes a function that may return sync or async, preserving sync execution when possible.
+ * @param fn - Function that may return T or Promise<T>
  * @param onError - Optional error transformer
- * @returns Promise of Ok(result) if successful, Err(error) if rejected
+ * @returns Result<T, E> if sync, Promise<Result<T, E>> if async
  * @example
- * await tryAsync(() => fetch('/api').then(r => r.json())) // Ok(data) or Err(error)
+ * tryCatchMaybePromise(() => 42)                    // Ok(42) - sync
+ * tryCatchMaybePromise(() => Promise.resolve(42))   // Promise<Ok(42)> - async
+ * tryCatchMaybePromise(() => { throw 'err' })       // Err('err') - sync
  */
-export async function tryAsync<T, E = unknown>(fn: () => Promise<T>, onError?: (error: unknown) => E): Promise<Result<T, E>> {
+export function tryCatchMaybePromise<T>(fn: () => MaybePromise<T>): Result<T, unknown> | Promise<Result<T, unknown>>;
+export function tryCatchMaybePromise<T, E>(fn: () => MaybePromise<T>, onError: (error: unknown) => E): Result<T, E> | Promise<Result<T, E>>;
+export function tryCatchMaybePromise<T, E = unknown>(fn: () => MaybePromise<T>, onError?: (error: unknown) => E): Result<T, E> | Promise<Result<T, E>> {
   try {
-    return (await fn()) as Ok<T>;
+    const result = fn();
+    if (isThenable(result)) {
+      return Promise.resolve(result).then(
+        (value) => value as Ok<T>,
+        (error) => ERR(onError ? onError(error) : (error as E)),
+      );
+    }
+    return result as Ok<T>;
   } catch (error) {
     return ERR(onError ? onError(error) : (error as E));
   }
 }
 
-/**
- * Alias for tryAsync. Executes an async function and captures the result or error.
- * @param fn - Async function to execute
- * @returns Promise of Ok(result) if successful, Err(error) if rejected
- */
-export function ofAsync<T, E = unknown>(fn: () => Promise<T>): Promise<Result<T, E>> {
-  return tryAsync(fn);
-}
-
-/**
- * Converts a Promise to a Result.
- * @param promise - The promise to convert
- * @param onRejected - Optional rejection handler
- * @returns Promise of Ok(value) if resolved, Err(error) if rejected
- * @example
- * await fromPromise(Promise.resolve(42))        // Ok(42)
- * await fromPromise(Promise.reject('error'))    // Err('error')
- */
-export async function fromPromise<T, E = unknown>(promise: Promise<T>, onRejected?: (reason: unknown) => E): Promise<Result<T, E>> {
-  try {
-    return (await promise) as Ok<T>;
-  } catch (error) {
-    return ERR(onRejected ? onRejected(error) : (error as E));
-  }
-}
-
 /**
  * Unwraps an Ok value or returns a computed value for Err.
  * @param result - The Result to unwrap
@@ -97,7 +84,7 @@ export function unwrapOrReturn<T, E, const R>(result: Result<T, E>, onErr: (erro
  */
 export function assertOk<T, E>(result: Result<T, E>, message?: string): asserts result is Ok<T> {
   if (isErr(result)) {
-    throw new Error(message ?? `Expected Ok result. Received error: ${String((result as Err<E>).error)}`);
+    throw new Error(message ?? `Expected Ok result. Received error: ${String(result.error)}`);
   }
 }
 
@@ -122,7 +109,7 @@ export function assertErr<T, E>(result: Result<T, E>, message?: string): asserts
  * @returns true if Err with Some error value
  */
 export function isSomeErr<T, E>(result: Result<T, E>): boolean {
-  return isErr(result) && isSome((result as Err<E>).error);
+  return isErr(result) && isSome(result.error);
 }
 
 /**
@@ -138,8 +125,8 @@ export function map<T, U, E>(result: Err<E>, fn: (value: T) => U): Err<E>;
 export function map<T, U>(result: Ok<T>, fn: (value: T) => U): Ok<U>;
 export function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
 export function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E> {
-  if (isErr(result)) return result as Err<E>;
-  return fn(result as Ok<T>) as Ok<U>;
+  if (isErr(result)) return result;
+  return fn(result) as Ok<U>;
 }
 
 /**
@@ -172,8 +159,8 @@ export function mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Resu
 export function flatMap<T, U, E>(result: Err<E>, fn: (value: T) => Result<U, E>): Err<E>;
 export function flatMap<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E>;
 export function flatMap<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E> {
-  if (isErr(result)) return result as Err<E>;
-  return fn(result as Ok<T>);
+  if (isErr(result)) return result;
+  return fn(result);
 }
 
 /**
@@ -185,7 +172,7 @@ export function flatMap<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<
 export function andThen<T, U, E>(result: Err<E>, fn: (value: T) => Result<U, E>): Err<E>;
 export function andThen<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E>;
 export function andThen<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E> {
-  return flatMap(result, fn);
+  return isErr(result) ? result : fn(result);
 }
 
 /**
@@ -219,7 +206,7 @@ export function tapErr<E>(result: Err<E>, fn: (error: E) => void): Err<E>;
 export function tapErr<T, E>(result: Result<T, E>, fn: (error: E) => void): Result<T, E>;
 export function tapErr<T, E>(result: Result<T, E>, fn: (error: E) => void): Result<T, E> {
   if (isErr(result)) {
-    fn((result as Err<E>).error);
+    fn(result.error);
   }
   return result;
 }
@@ -242,19 +229,22 @@ export function bimap<T, U, E, F>(result: Result<T, E>, okFn: (value: T) => U, e
 }
 
 /**
- * Extracts the Ok value, throws if Err.
+ * Extracts the Ok value, throws Err if not Ok.
+ * Use with safeTry for Rust-like ? operator ergonomics.
  * @param result - The Result to unwrap
  * @returns The contained Ok value
- * @throws Error if result is Err
+ * @throws The Err object itself
  * @example
  * unwrap(ok(42))        // 42
- * unwrap(err('failed')) // throws Error
+ * unwrap(err('failed')) // throws Err
+ * safeTry(() => {
+ *   const a = unwrap(getValue());
+ *   return a + 1;
+ * });
  */
 export function unwrap<T, E>(result: Result<T, E>): T {
-  if (isErr(result)) {
-    throw new Error(`Called unwrap on Err: ${String((result as Err<E>).error)}`);
-  }
-  return result as T;
+  if (isErr(result)) throw result.error;
+  return result;
 }
 
 /**
@@ -339,9 +329,9 @@ export function mapOrElse<T, E, U>(result: Result<T, E>, defaultFn: () => U, fn:
  */
 export function expect<T, E>(result: Result<T, E>, message: string): T {
   if (isErr(result)) {
-    throw new Error(`${message}: ${String((result as Err<E>).error)}`);
+    throw new Error(`${message}: ${String(result.error)}`);
   }
-  return result as Ok<T>;
+  return result;
 }
 
 /**
@@ -421,7 +411,7 @@ export function toOption<T, E>(result: Result<T, E>): Option<T> {
  * toErrorOption(ok(42))        // None
  */
 export function toErrorOption<T, E>(result: Result<T, E>): Option<E> {
-  return isErr(result) ? optionOf((result as Err<E>).error) : NONE;
+  return isErr(result) ? optionOf(result.error) : NONE;
 }
 
 /**
@@ -434,9 +424,9 @@ export function toErrorOption<T, E>(result: Result<T, E>): Option<E> {
  * zip(ok(1), err('e')) // Err('e')
  */
 export function zip<T, U, E>(left: Result<T, E>, right: Result<U, E>): Result<[T, U], E> {
-  if (isErr(left)) return left as Err<E>;
-  if (isErr(right)) return right as Err<E>;
-  return [left as Ok<T>, right as Ok<U>] as Ok<[T, U]>;
+  if (isErr(left)) return left;
+  if (isErr(right)) return right;
+  return [left, right] as Ok<[T, U]>;
 }
 
 /**
@@ -449,9 +439,9 @@ export function zip<T, U, E>(left: Result<T, E>, right: Result<U, E>): Result<[T
  * zipWith(ok(2), ok(3), (a, b) => a + b) // Ok(5)
  */
 export function zipWith<T, U, V, E>(left: Result<T, E>, right: Result<U, E>, fn: (left: T, right: U) => V): Result<V, E> {
-  if (isErr(left)) return left as Err<E>;
-  if (isErr(right)) return right as Err<E>;
-  return fn(left as Ok<T>, right as Ok<U>) as Ok<V>;
+  if (isErr(left)) return left;
+  if (isErr(right)) return right;
+  return fn(left, right) as Ok<V>;
 }
 
 /**
@@ -503,6 +493,36 @@ export function partition<T, E>(results: Result<T, E>[]): [T[], E[]] {
   return [oks, errs];
 }
 
+/**
+ * Extracts all Ok values from an iterable of Results.
+ * @param results - Iterable of Results
+ * @returns Array of Ok values
+ * @example
+ * filterOk([ok(1), err('a'), ok(2)]) // [1, 2]
+ */
+export function filterOk<T, E>(results: Iterable<Result<T, E>>): T[] {
+  const oks: T[] = [];
+  for (const result of results) {
+    if (isOk(result)) oks.push(result);
+  }
+  return oks;
+}
+
+/**
+ * Extracts all Err values from an iterable of Results.
+ * @param results - Iterable of Results
+ * @returns Array of error values
+ * @example
+ * filterErr([ok(1), err('a'), ok(2)]) // ['a']
+ */
+export function filterErr<T, E>(results: Iterable<Result<T, E>>): E[] {
+  const errs: E[] = [];
+  for (const result of results) {
+    if (isErr(result)) errs.push(result.error);
+  }
+  return errs;
+}
+
 /**
  * Collects an array of Results into a Result of an array. Fails on first Err.
  * @param results - Array of Results
@@ -515,10 +535,8 @@ export function collect<T, E>(results: Result<T, E>[]): Result<T[], E> {
   const values: T[] = [];
 
   for (const result of results) {
-    if (isErr(result)) {
-      return result as Err<E>;
-    }
-    values.push(result as Ok<T>);
+    if (isErr(result)) return result;
+    values.push(result);
   }
 
   return values as Ok<T[]>;
@@ -542,8 +560,8 @@ export function collectAll<T, E>(results: Result<T, E>[]): Result<T[], E[]> {
  * @param results - Array of Results
  * @returns Ok(values) if all Ok, first Err otherwise
  */
-export function all<T, E>(results: Result<T, E>[]): Result<Widen<T>[], WidenNever<E>> {
-  return collect(results) as Result<Widen<T>[], WidenNever<E>>;
+export function all<T, E>(results: Result<T, E>[]): Result<readonly Widen<T>[], WidenNever<E>> {
+  return collect(results) as Result<readonly Widen<T>[], WidenNever<E>>;
 }
 
 /**
@@ -555,12 +573,11 @@ export function all<T, E>(results: Result<T, E>[]): Result<Widen<T>[], WidenNeve
  * any([err('a'), err('b')])        // Err(['a', 'b'])
  */
 export function any<T, E>(results: Result<T, E>[]): Result<Widen<T>, WidenNever<E>[]> {
-  const len = results.length;
-  const errors = new Array<WidenNever<E>>(len);
-  for (let i = 0; i < len; i++) {
+  const errors: WidenNever<E>[] = [];
+  for (let i = 0; i < results.length; i++) {
     const result = results[i];
     if (isOk(result)) return result as Ok<Widen<T>>;
-    errors[i] = (result as Err<WidenNever<E>>).error;
+    errors.push((result as Err<WidenNever<E>>).error);
   }
   return ERR(errors);
 }
@@ -576,7 +593,7 @@ export function any<T, E>(results: Result<T, E>[]): Result<Widen<T>, WidenNever<
  */
 export function transpose<T, E>(result: Result<Option<T>, E>): Option<Result<T, E>> {
   if (isErr(result)) {
-    return ERR((result as Err<E>).error) as Option<Result<T, E>>;
+    return ERR(result.error) as Option<Result<T, E>>;
   }
   const opt = result as Option<T>;
   return isNone(opt) ? NONE : (opt as unknown as Ok<T> as Option<Result<T, E>>);
@@ -606,71 +623,157 @@ export function isOkAnd<T, E>(result: Result<T, E>, predicate: (value: T) => boo
  * isErrAnd(ok(42), e => true)                       // false
  */
 export function isErrAnd<T, E>(result: Result<T, E>, predicate: (error: E) => boolean): boolean {
-  return isErr(result) && predicate((result as Err<E>).error);
+  return isErr(result) && predicate(result.error);
 }
 
-/**
- * Maps an async function over an Ok value.
- * @param result - The Result to map
- * @param fn - Async transform function
- * @param onRejected - Optional rejection handler
- * @returns Promise of mapped Result
- * @example
- * await mapAsync(ok(2), async x => x * 2) // Ok(4)
- */
-export async function mapAsync<T, U, E = unknown>(
-  result: Result<T, E>,
-  fn: (value: T) => Promise<U>,
-  onRejected?: (error: unknown) => E,
-): Promise<Result<U, E>> {
-  if (isErr(result)) return result as Err<E>;
-  return fromPromise(fn(result as Ok<T>), onRejected);
+export function settledToResult<T, E>(result: PromiseSettledResult<Result<T, E>>): Result<T, E> {
+  if (result.status === 'fulfilled') return result.value;
+  return ERR(result.reason);
 }
 
 /**
- * Chains an async Result-returning function.
- * @param result - The Result to chain
- * @param fn - Async function returning a Result
- * @returns Promise of the chained Result
+ * Partitions an async iterable of Results.
+ * @param results - Iterable of Promise Results
+ * @returns Promise of [Ok values, Err values]
  * @example
- * await andThenAsync(ok(2), async x => ok(x * 2)) // Ok(4)
+ * await partitionAsync([Promise.resolve(ok(1)), Promise.resolve(err('a'))])
+ * // [[1], ['a']]
  */
-export async function andThenAsync<T, U, E>(result: Result<T, E>, fn: (value: T) => Promise<Result<U, E>>): Promise<Result<U, E>> {
-  if (isErr(result)) return result as Err<E>;
-  return fn(result as Ok<T>);
+export async function partitionAsync<T, E>(promises: Iterable<Promise<Result<T, E>>>): Promise<[Widen<T>[], WidenNever<E>[]]> {
+  const settled = await Promise.allSettled(promises);
+  return partition(settled.map(settledToResult)) as [Widen<T>[], WidenNever<E>[]];
 }
 
 /**
- * Pattern matches with async handlers.
- * @param result - The Result to match
- * @param onOk - Async handler for Ok
- * @param onErr - Async handler for Err
- * @returns Promise of the handler result
+ * Settles an array of MaybePromise values into Results.
+ * Returns synchronously if all inputs are sync, avoiding Promise overhead.
+ * @param values - Array of values that may or may not be Promises
+ * @returns Array of Results (sync) or Promise of Results (if any async)
+ * @example
+ * settleMaybePromise([1, 2, 3])                    // [Ok(1), Ok(2), Ok(3)] - sync
+ * settleMaybePromise([1, Promise.resolve(2)])     // Promise<[Ok(1), Ok(2)]>
+ * settleMaybePromise([Promise.reject('e')])       // Promise<[Err('e')]>
  */
-export async function matchAsync<T, E, U>(result: Result<T, E>, onOk: (value: T) => Promise<U>, onErr: (error: E) => Promise<U>): Promise<U> {
-  return isOk(result) ? onOk(result) : onErr(result.error);
+export function settleMaybePromise<T, E = unknown>(values: MaybePromise<T>[]): Result<T, E>[] | Promise<Result<T, E>[]> {
+  const len = values.length;
+  const results = new Array<Result<T, E>>(len);
+  let pendingIndices: number[] | undefined;
+  let pendingPromises: Promise<T>[] | undefined;
+
+  for (let i = 0; i < len; i++) {
+    const v = values[i];
+    if (isThenable(v)) {
+      (pendingIndices ??= []).push(i);
+      (pendingPromises ??= []).push(Promise.resolve(v));
+    } else {
+      results[i] = v as Ok<T>;
+    }
+  }
+
+  if (!pendingPromises) return results;
+
+  return Promise.allSettled(pendingPromises).then((settled) => {
+    for (let i = 0; i < settled.length; i++) {
+      const s = settled[i];
+      results[pendingIndices![i]] = s.status === 'fulfilled' ? (s.value as Ok<T>) : ERR(s.reason as E);
+    }
+    return results;
+  });
+}
+
+export async function partitionMaybePromiseAsync<T, E>(
+  values: MaybePromise<Result<T, E>>[],
+  oks: Widen<T>[],
+  errs: WidenNever<E>[],
+  startIndex: number = 0,
+): Promise<[Widen<T>[], WidenNever<E>[]]> {
+  const suffixLength = values.length - startIndex;
+  const pending = new Array<Promise<Result<T, E>>>(suffixLength);
+
+  for (let i = 0; i < suffixLength; i++) {
+    const value = values[startIndex + i];
+    pending[i] = Promise.resolve(value).then(
+      (result) => result as Result<T, E>,
+      (error) => ERR(error as E),
+    );
+  }
+
+  const resolved = await Promise.all(pending);
+  for (let i = 0; i < resolved.length; i++) {
+    const result = resolved[i];
+    if (isOk(result)) {
+      oks.push(result as Widen<T>);
+    } else {
+      errs.push((result as Err<WidenNever<E>>).error);
+    }
+  }
+  return [oks, errs] as [Widen<T>[], WidenNever<E>[]];
 }
 
 /**
- * Partitions an async iterable of Results.
- * @param results - Iterable of Promise Results
- * @returns Promise of [Ok values, Err values]
+ * Partitions MaybePromise Results into Ok and Err values.
+ * Returns synchronously if all inputs are sync, avoiding Promise overhead.
+ * @param values - Array of MaybePromise Results
+ * @returns [Ok values, Err values] (sync) or Promise of same (if any async)
  * @example
- * await partitionAsync([Promise.resolve(ok(1)), Promise.resolve(err('a'))])
- * // [[1], ['a']]
+ * partitionMaybePromise([ok(1), err('a')])                   // [[1], ['a']] - sync
+ * partitionMaybePromise([ok(1), Promise.resolve(err('a'))]) // Promise<[[1], ['a']]>
  */
-export async function partitionAsync<T, E>(results: Iterable<Promise<Result<T, E>>>): Promise<[Widen<T>[], WidenNever<E>[]]> {
+export function partitionMaybePromise<T, E>(values: MaybePromise<Result<T, E>>[]): [Widen<T>[], WidenNever<E>[]] | Promise<[Widen<T>[], WidenNever<E>[]]> {
+  const len = values.length;
   const oks: Widen<T>[] = [];
   const errs: WidenNever<E>[] = [];
 
-  for (const promise of results) {
-    const result = await promise;
-    if (isOk(result)) {
-      oks.push(result as Ok<Widen<T>>);
+  for (let i = 0; i < len; i++) {
+    const value = values[i];
+    if (isThenable(value)) {
+      return partitionMaybePromiseAsync(values, oks, errs, i);
+    }
+    if (isOk(value)) {
+      oks.push(value as Widen<T>);
     } else {
-      errs.push((result as Err<WidenNever<E>>).error);
+      errs.push((value as Err<WidenNever<E>>).error);
     }
   }
 
   return [oks, errs];
 }
+
+/**
+ * Executes a function, catching thrown Err values.
+ * Use with unwrap for Rust-like ? operator ergonomics.
+ * @param fn - Function that may throw Err via unwrap
+ * @returns Ok(return value) or the caught Err
+ * @example
+ * const result = safeTry(() => {
+ *   const a = unwrap(parseNumber('10'));
+ *   const b = unwrap(parseNumber('5'));
+ *   return a + b;
+ * }); // Ok(15) or Err(...)
+ */
+export function safeTry<T>(fn: () => T): Result<T, unknown> {
+  try {
+    return fn() as Ok<T>;
+  } catch (e) {
+    return ERR(e);
+  }
+}
+
+/**
+ * Async version of safeTry.
+ * @param fn - Async function that may throw Err via unwrap
+ * @returns Promise of Ok(return value) or the caught Err
+ * @example
+ * const result = await safeTryAsync(async () => {
+ *   const user = unwrap(await fetchUser(id));
+ *   const posts = unwrap(await fetchPosts(user.id));
+ *   return { user, posts };
+ * });
+ */
+export async function safeTryAsync<T>(fn: () => Promise<T>): Promise<Result<T, unknown>> {
+  try {
+    return (await fn()) as Ok<T>;
+  } catch (e) {
+    return ERR(e);
+  }
+}

package/src/safe.ts

@@ -1,5 +1,5 @@
-import { some as someUnsafe, ok as okUnsafe, err, none, isErr } from './types.js';
-import type {
+export { some, none, ok, err, isOk, isErr, isSome, isNone, isThenable, isSync } from './types.js';
+export type {
   Some,
   None,
   Ok,
@@ -13,46 +13,9 @@ import type {
   ResultErrorType,
   IsResult,
   InferErr,
-  ValueType,
+  MaybePromise,
 } from './types.js';
-
-export type { Some, None, Ok, Err, OptionType, OptionValue, IsOption, InferSome, ResultType, ResultValue, ResultErrorType, IsResult, InferErr };
-
-export { none, err };
+export { safeTry, safeTryAsync, unwrap } from './result.js';
 export * as Option from './option.js';
 export * as Result from './result.js';
-
-/**
- * Creates a Some value with runtime validation.
- * Throws if the value is null or undefined.
- * @param value - The value to wrap (must be non-nullable)
- * @returns The value typed as Some
- * @throws {TypeError} If value is null or undefined
- * @example
- * some(42)        // Some(42)
- * some(null)      // throws TypeError
- * some(undefined) // throws TypeError
- */
-export function some<T>(value: T): Some<ValueType<T>> {
-  if (value === null || value === undefined) {
-    throw new TypeError('some() requires a non-nullable value');
-  }
-  return someUnsafe(value as ValueType<T>);
-}
-
-/**
- * Creates an Ok value with runtime validation.
- * Throws if the value is an Err (prevents accidental double-wrapping).
- * @param value - The success value
- * @returns The value typed as Ok
- * @throws {TypeError} If value is an Err
- * @example
- * ok(42)           // Ok(42)
- * ok(err('fail'))  // throws TypeError
- */
-export function ok<T>(value: T): Ok<T> {
-  if (isErr(value)) {
-    throw new TypeError('ok() cannot wrap an Err value');
-  }
-  return okUnsafe(value);
-}
+export * as Iter from './iter.js';