nalloc 0.1.0 → 0.2.0

package/src/result.ts

@@ -4,6 +4,9 @@ import type { Ok, Err, Result, Option, Widen, WidenNever, MaybePromise } from '.
 export type { Ok, Err, Result };
 export { isOk, isErr };
 
+const identity = <T>(v: T): T => v;
+const wrapErr = (error: unknown): Err<never> => ERR(error) as Err<never>;
+
 /**
  * Executes a function and captures the result or error.
  * @param fn - Function to execute
@@ -14,8 +17,11 @@ 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>(fn: () => T): T extends Err<any> ? Err<unknown> : T extends Result<infer U, any> ? Result<U, unknown> : Result<T, unknown>;
+export function tryCatch<T, E>(
+  fn: () => T,
+  onError: (error: unknown) => E,
+): T extends Err<infer F> ? Err<F | E> : T extends Result<infer U, infer F> ? Result<U, F | 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>;
@@ -29,8 +35,55 @@ 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>(fn: () => T): T extends Err<any> ? Err<unknown> : T extends Result<infer U, any> ? Result<U, unknown> : Result<T, unknown>;
 export function of<T>(fn: () => T): Result<T, unknown> {
-  return tryCatch(fn);
+  try {
+    return fn() as Ok<T>;
+  } catch (error) {
+    return ERR(error);
+  }
+}
+
+/**
+ * Wraps a throwing function so it returns a Result instead.
+ * The wrapper is created once and reused, avoiding per-call closure allocation.
+ * @param fn - The function to wrap
+ * @param onError - Optional error transformer
+ * @returns A new function with the same signature that returns Result
+ * @example
+ * const safeParse = wrap(JSON.parse);
+ * safeParse('{"a":1}')  // Ok({a: 1})
+ * safeParse('invalid')  // Err(SyntaxError)
+ */
+export function wrap<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => Result<R, unknown>;
+export function wrap<A extends unknown[], R, E>(fn: (...args: A) => R, onError: (error: unknown) => E): (...args: A) => Result<R, E>;
+export function wrap<A extends unknown[], R, E = unknown>(fn: (...args: A) => R, onError?: (error: unknown) => E): (...args: A) => Result<R, E> {
+  return (...args: A) => {
+    try {
+      return fn(...args) as Ok<R>;
+    } catch (error) {
+      return ERR(onError ? onError(error) : (error as E));
+    }
+  };
+}
+
+/**
+ * Converts a Result-returning function into a throwing function.
+ * Inverse of wrap. Use at ecosystem boundaries where libraries expect exceptions
+ * (Express error handlers, Drizzle transactions, Passport.js, etc.).
+ * @param fn - A function that returns a Result
+ * @returns A new function that returns the Ok value or throws the Err error
+ * @example
+ * const findUser = (id: string): Result<User, NotFoundError> => { ... };
+ * const throwingFind = toThrowable(findUser);
+ * throwingFind('123') // returns User or throws NotFoundError
+ */
+export function toThrowable<A extends unknown[], R, E>(fn: (...args: A) => Result<R, E>): (...args: A) => R {
+  return (...args: A) => {
+    const result = fn(...args);
+    if (isErr(result)) throw result.error;
+    return result;
+  };
 }
 
 /**
@@ -42,8 +95,8 @@ export function of<T>(fn: () => T): Result<T, unknown> {
  * await fromPromise(fetch('/api'))              // Ok(Response) or Err(unknown)
  * await fromPromise(fetch('/api'), e => String(e)) // Ok(Response) or Err(string)
  */
-export async function fromPromise<T>(promise: Promise<T>): Promise<Result<T, unknown>>;
-export async function fromPromise<T, E>(promise: Promise<T>, onError: (error: unknown) => E): Promise<Result<T, E>>;
+export async function fromPromise<T>(promise: Promise<Exclude<T, Err<any>>>): Promise<Result<T, unknown>>;
+export async function fromPromise<T, E>(promise: Promise<Exclude<T, Err<any>>>, onError: (error: unknown) => E): Promise<Result<T, E>>;
 export async function fromPromise<T, E = unknown>(promise: Promise<T>, onError?: (error: unknown) => E): Promise<Result<T, E>> {
   try {
     return (await promise) as Ok<T>;
@@ -52,6 +105,43 @@ export async function fromPromise<T, E = unknown>(promise: Promise<T>, onError?:
   }
 }
 
+/** A validation issue from a Standard Schema validator. */
+export interface SchemaIssue {
+  readonly message: string;
+  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }>;
+}
+
+/** Minimal Standard Schema v1 interface (duck-typed, no external dependency). */
+export interface StandardSchema<O = unknown> {
+  readonly '~standard': {
+    readonly validate: (value: unknown) => StandardSchemaResult<O> | Promise<StandardSchemaResult<O>>;
+  };
+}
+
+type StandardSchemaResult<O> = { readonly value: O; readonly issues?: undefined } | { readonly issues: ReadonlyArray<SchemaIssue> };
+
+function schemaResultToResult<O>(sr: StandardSchemaResult<O>): Result<O, readonly SchemaIssue[]> {
+  return sr.issues ? ERR(sr.issues) : (sr.value as Ok<O>);
+}
+
+/**
+ * Validates a value against a Standard Schema and returns a Result.
+ * Works with any Standard Schema v1 compliant library (Zod, Valibot, ArkType, etc.).
+ * Returns synchronously if the schema validates synchronously.
+ * @param schema - A Standard Schema v1 compliant schema
+ * @param value - The value to validate
+ * @returns Ok(parsed) if valid, Err(issues) if invalid
+ * @example
+ * import { z } from 'zod';
+ * const result = fromSchema(z.string().email(), input);
+ * // Result<string, readonly SchemaIssue[]>
+ */
+export function fromSchema<O>(schema: StandardSchema<O>, value: unknown): Result<O, readonly SchemaIssue[]> | Promise<Result<O, readonly SchemaIssue[]>> {
+  const sr = schema['~standard'].validate(value);
+  if (isThenable(sr)) return sr.then(schemaResultToResult);
+  return schemaResultToResult(sr);
+}
+
 /**
  * Executes a function that may return sync or async, preserving sync execution when possible.
  * @param fn - Function that may return T or Promise<T>
@@ -497,7 +587,8 @@ export function partition<T, E>(results: Result<T, E>[]): [T[], E[]] {
   const oks: T[] = [];
   const errs: E[] = [];
 
-  for (const result of results) {
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
     if (isOk(result)) {
       oks.push(result);
     } else {
@@ -509,30 +600,32 @@ export function partition<T, E>(results: Result<T, E>[]): [T[], E[]] {
 }
 
 /**
- * Extracts all Ok values from an iterable of Results.
- * @param results - Iterable of Results
+ * Extracts all Ok values from an array of Results.
+ * @param results - Array 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[] {
+export function filterOk<T, E>(results: Result<T, E>[]): T[] {
   const oks: T[] = [];
-  for (const result of results) {
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
     if (isOk(result)) oks.push(result);
   }
   return oks;
 }
 
 /**
- * Extracts all Err values from an iterable of Results.
- * @param results - Iterable of Results
+ * Extracts all Err values from an array of Results.
+ * @param results - Array 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[] {
+export function filterErr<T, E>(results: Result<T, E>[]): E[] {
   const errs: E[] = [];
-  for (const result of results) {
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
     if (isErr(result)) errs.push(result.error);
   }
   return errs;
@@ -547,13 +640,12 @@ export function filterErr<T, E>(results: Iterable<Result<T, E>>): E[] {
  * collect([ok(1), err('e')])    // Err('e')
  */
 export function collect<T, E>(results: Result<T, E>[]): Result<T[], E> {
-  const len = results.length;
-  const values = new Array<T>(len);
+  const values: T[] = [];
 
-  for (let i = 0; i < len; i++) {
+  for (let i = 0; i < results.length; i++) {
     const result = results[i];
     if (isErr(result)) return result;
-    values[i] = result;
+    values.push(result);
   }
 
   return values as Ok<T[]>;
@@ -570,7 +662,8 @@ export function collect<T, E>(results: Result<T, E>[]): Result<T[], E> {
 export function collectAll<T, E>(results: Result<T, E>[]): Result<T[], E[]> {
   const oks: T[] = [];
   const errs: E[] = [];
-  for (const result of results) {
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
     if (isOk(result)) {
       oks.push(result);
     } else {
@@ -651,11 +744,6 @@ export function isErrAnd<T, E>(result: Result<T, E>, predicate: (error: E) => bo
   return isErr(result) && predicate(result.error);
 }
 
-export function settledToResult<T, E>(result: PromiseSettledResult<Result<T, E>>): Result<T, E> {
-  if (result.status === 'fulfilled') return result.value;
-  return ERR(result.reason);
-}
-
 /**
  * Partitions an async iterable of Results.
  * @param results - Iterable of Promise Results
@@ -666,7 +754,26 @@ export function settledToResult<T, E>(result: PromiseSettledResult<Result<T, E>>
  */
 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>[]];
+  const oks: Widen<T>[] = [];
+  const errs: WidenNever<E>[] = [];
+
+  for (let i = 0; i < settled.length; i++) {
+    const entry = settled[i];
+
+    if (entry.status === 'rejected') {
+      errs.push(entry.reason as WidenNever<E>);
+      continue;
+    }
+
+    const result = entry.value;
+    if (isOk(result)) {
+      oks.push(result as Widen<T>);
+    } else {
+      errs.push(result.error as WidenNever<E>);
+    }
+  }
+
+  return [oks, errs];
 }
 
 /**
@@ -681,7 +788,7 @@ export async function partitionAsync<T, E>(promises: Iterable<Promise<Result<T,
  */
 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);
+  const results = new Array<Result<T, E>>(len).fill(0 as never);
   let pendingIndices: number[] | undefined;
   let pendingPromises: Promise<T>[] | undefined;
 
@@ -712,36 +819,21 @@ export async function partitionMaybePromiseAsync<T, E>(
   errs: WidenNever<E>[],
   startIndex: number = 0,
 ): Promise<[Widen<T>[], WidenNever<E>[]]> {
-  const suffixLength = values.length - startIndex;
-  const pendingPromises: Promise<Result<T, E>>[] = [];
+  const remaining = values.length - startIndex;
+  const promises = new Array<Promise<Result<T, E>>>(remaining).fill(0 as never);
 
-  for (let i = 0; i < suffixLength; i++) {
+  for (let i = 0; i < remaining; i++) {
     const value = values[startIndex + i];
-    if (isThenable(value)) {
-      pendingPromises.push(
-        Promise.resolve(value).then(
-          (result) => result as Result<T, E>,
-          (error) => ERR(error as E),
-        ),
-      );
-    } else {
-      if (isOk(value)) {
-        oks.push(value as Widen<T>);
-      } else {
-        errs.push((value as Err<WidenNever<E>>).error);
-      }
-    }
+    promises[i] = isThenable(value) ? Promise.resolve(value).then(identity, wrapErr) : Promise.resolve(value);
   }
 
-  if (pendingPromises.length > 0) {
-    const resolved = await Promise.all(pendingPromises);
-    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);
-      }
+  const resolved = await Promise.all(promises);
+  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);
     }
   }
 
@@ -815,3 +907,51 @@ export async function safeTryAsync<T>(fn: () => Promise<T>): Promise<Result<T, u
     return ERR(e);
   }
 }
+
+function* unwrapYield<T, E>(result: Result<T, E>): Generator<Err<E>, T> {
+  if (isErr(result)) {
+    yield result;
+    return undefined as never;
+  }
+  return result;
+}
+
+type Unwrapper = <T, E>(result: Result<T, E>) => Generator<Err<E>, T>;
+
+/**
+ * Generator-based do-notation for Result. Provides a `$` function that unwraps
+ * Results inside a generator, short-circuiting on the first Err.
+ * Preserves error types (unlike safeTry which erases to unknown).
+ * @param fn - Generator function receiving `$` unwrapper
+ * @returns Ok(return value) or the first Err encountered
+ * @example
+ * const result = gen(function*($) {
+ *   const a = yield* $(parseNumber('10'));
+ *   const b = yield* $(parseNumber('5'));
+ *   return a + b;
+ * }); // Result<number, ParseError>
+ */
+export function gen<E, T>(fn: ($: Unwrapper) => Generator<Err<E>, T>): Result<T, E> {
+  const iter = fn(unwrapYield);
+  const step = iter.next();
+  if (!step.done) return step.value;
+  return step.value as Ok<T>;
+}
+
+/**
+ * Async generator-based do-notation for Result. Like gen, but for async operations.
+ * @param fn - Async generator function receiving `$` unwrapper
+ * @returns Promise of Ok(return value) or the first Err encountered
+ * @example
+ * const result = await genAsync(async function*($) {
+ *   const user = yield* $(await fetchUser(id));
+ *   const posts = yield* $(await fetchPosts(user.id));
+ *   return { user, posts };
+ * }); // Promise<Result<{user, posts}, FetchError>>
+ */
+export async function genAsync<E, T>(fn: ($: Unwrapper) => AsyncGenerator<Err<E>, T>): Promise<Result<T, E>> {
+  const iter = fn(unwrapYield);
+  const step = await iter.next();
+  if (!step.done) return step.value;
+  return step.value as Ok<T>;
+}

package/src/safe.ts

@@ -15,7 +15,55 @@ export type {
   InferErr,
   MaybePromise,
 } from './types.js';
-export { safeTry, safeTryAsync, unwrap } from './result.js';
+export { safeTry, safeTryAsync, unwrap, gen, genAsync } from './result.js';
 export * as Option from './option.js';
 export * as Result from './result.js';
 export * as Iter from './iter.js';
+
+/**
+ * Threads a value through a sequence of unary functions, left to right.
+ * @param value - The initial value
+ * @param fns - Functions to apply in order
+ * @returns The result of applying all functions
+ * @example
+ * pipe(
+ *   Result.tryCatch(() => JSON.parse(input)),
+ *   r => Result.flatMap(r, validate),
+ *   r => Result.map(r, transform),
+ * )
+ */
+export function pipe<A>(a: A): A;
+export function pipe<A, B>(a: A, ab: (a: A) => B): B;
+export function pipe<A, B, C>(a: A, ab: (a: A) => B, bc: (b: B) => C): C;
+export function pipe<A, B, C, D>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D): D;
+export function pipe<A, B, C, D, E>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E): E;
+export function pipe<A, B, C, D, E, F>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F): F;
+export function pipe<A, B, C, D, E, F, G>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G): G;
+export function pipe<A, B, C, D, E, F, G, H>(
+  a: A,
+  ab: (a: A) => B,
+  bc: (b: B) => C,
+  cd: (c: C) => D,
+  de: (d: D) => E,
+  ef: (e: E) => F,
+  fg: (f: F) => G,
+  gh: (g: G) => H,
+): H;
+export function pipe<A, B, C, D, E, F, G, H, I>(
+  a: A,
+  ab: (a: A) => B,
+  bc: (b: B) => C,
+  cd: (c: C) => D,
+  de: (d: D) => E,
+  ef: (e: E) => F,
+  fg: (f: F) => G,
+  gh: (g: G) => H,
+  hi: (h: H) => I,
+): I;
+export function pipe(a: unknown, ...fns: ((v: unknown) => unknown)[]): unknown {
+  let result = a;
+  for (let i = 0; i < fns.length; i++) {
+    result = fns[i](result);
+  }
+  return result;
+}