slang-ts 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,13 +1,22 @@
 # Changelog
 
-Everything notable in `slang-ts`, grouped by area. No release diary — just what's here.
+Everything notable in `slang-ts`, grouped by area. No release diary: just what's here.
 
 ## Results and flow
 
-- `Ok(value, message?)` keeps an optional success message on the result, like text you want to show
-  the user. Results without one have no `message` property.
+- `Ok(value, message?)` keeps an optional success message on the result. Results without one have no `message` property.
 - `SafeTry` unwraps Option and Atom values into one result. A Result never nests inside another
   Result, and plain object properties and array elements stay unchanged.
+- `safeTry` is sync in, sync out: a function returning a plain value gets its `Result`
+  directly, and a function returning a promise gets a promise of it. With `{ throw: true }`, a
+  sync throw is thrown from the call and an async one rejects.
+- `Result.mapErr(fn)` rewrites an `Err` message and keeps its `.raw` cause; `Result.orFn(fn)`
+  recovers from an `Err` with the same return rules as `andThen`. Both return the same `Ok`
+  untouched.
+- `andThen` and `orFn` on a `Result` return a plain `Result` for a sync callback; an async
+  callback gives `Result | Promise<Result>` to `await`.
+- `combineResults` turns an array of `Result`s into one `Ok` of all values, typed as a tuple,
+  or the first `Err` with its `.raw` kept. `combineErrors` lists every error message in order.
 
 ## Collections and data
 
@@ -33,7 +42,8 @@ Everything notable in `slang-ts`, grouped by area. No release diary — just wha
 
 - `createStepper`: bounded step history with named steps, undo, and explicit `prev` handling.
 - `println` respects the environment: `setEnvironment("production")` turns it into a no-op, and
-  `{ printFn }` routes output through an existing logger.
+  `{ printFn }` routes output through an existing logger. Plain objects, arrays, Sets and Maps
+  print as JSON, circular references included; errors and dates keep their text form.
 
 ## Typing and packaging
 
@@ -49,5 +59,7 @@ Everything notable in `slang-ts`, grouped by area. No release diary — just wha
 
 ## Documentation
 
-- A shorter README tour, per-utility reference pages, and plain-TypeScript contrasts for the
-  utilities that replace real boilerplate.
+- A shorter README tour and per-utility reference pages. Each page explains how the utility
+  behaves (when it runs, what it returns, how it fails) and every example compiles and runs
+  as written.
+- An agent guide at `skill/SKILL.md`, shipped with the package.

package/README.md

@@ -6,7 +6,7 @@
 An opinionated functional programming library for TypeScript.
 
 A collection of utilities and mechanisms brought over from languages like Rust and Erlang. Each
-utility is deliberately chosen and built from scratch with zero dependencies.
+utility is deliberately selected and built from scratch with zero dependencies.
 
 ## Install
 
@@ -20,26 +20,30 @@ Well I love functional programming so much and hate classes and inheritance with
 
 ## Quick start
 
-So let's say you have a function that can fail. Instead of throwing and hoping someone up the chain
-catches it, you return a `Result`:
+So let's say your function can fail. Instead of throwing, you return a `Result`: `Ok` with the
+value or `Err` with a message, and the caller checks `isOk` before reading either:
 
 ```ts
 import { Ok, Err, type Result, println } from "slang-ts";
 
-function divide(a: number, b: number): Result<number, string> {
-  return b === 0 ? Err("Cannot divide by zero") : Ok(a / b);
+function splitBill(total: number, people: number): Result<number, string> {
+  if (people === 0) {
+    return Err("Add at least one person to split the bill");
+  }
+
+  return Ok(total / people);
 }
 
-const result = divide(10, 2);
+const share = splitBill(120, 4);
 
-if (result.isOk) {
-  println("Result:", result.value); // 5
+if (share.isOk) {
+  println("Each person pays:", share.value); // 30
 } else {
-  println("Error:", result.error);
+  println("Could not split the bill:", share.error);
 }
 ```
 
-`println` is optional — it's a small development logger.
+`println` is optional: it's a small development logger, silent in production.
 
 ## Imports
 
@@ -49,145 +53,145 @@ Import only what you use:
 import { option, Ok, Err, atom, match } from "slang-ts";
 ```
 
-## Choose by problem
+## Choose by what you want to solve
 
 | If you need… | Use |
 |---|---|
-| A value that may be missing | [Option][option] |
-| An operation that can fail | [Result][result] and [SafeTry][safe-try] |
+| A value which may be missing | [Option][option] |
+| An operation which can fail | [Result][result] and [SafeTry][safe-try] |
+| Several results checked together | [combineResults and combineErrors][combine] |
 | Pattern matching over results | [Match][match] |
+| Steps which stop at the first failure | [Pipe][pipe] |
 | Timeout, retry, or cancellation | [SuperPromise][super-promise] |
 | Ordered, parallel, or race tasks | [SuperRunner][super-runner] |
 | A shared concurrency limit | [taskGroup][task-group] |
 | Strict array bounds or paging | [list][list] |
-| Safe nested record access | [struct][struct] |
-| Set membership and algebra | [sets][sets] |
+| Nested record reads with defaults | [struct][struct] |
+| Set membership and set operations | [sets][sets] |
 | Lazy pipelines over an `Ok` | [Ok.iterate][iterate] |
 | Cached function calls | [memoized][memoized] |
 | Step history or undo | [createStepper][stepper] |
-| Publish/subscribe between parts of an app | [Channel][channel] |
-| A lifecycle trigger that fires once | [Signal][signal] |
+| Events between parts of an app | [Channel][channel] |
+| A lifecycle trigger which fires once | [Signal][signal] |
 
 ## What's inside
 
 ### Error handling and flow
 
-- [Option][option] (Some/None, `isFalsy`, expect, unwrap/else, andThen)
-- [Result][result] (Ok/Err, expect, unwrap/else, andThen, raw cause)
-- [SafeTry][safe-try]
-- [Match][match] (match, matchAll)
-- [Options][options]
-- [Pipe][pipe]
+- [Result][result] (`Ok`, `Err`, expect, unwrap with else, andThen, mapErr, orFn, raw cause)
+- [SafeTry][safe-try] (`safeTry`)
+- [combineResults and combineErrors][combine] (`combineResults`, `combineErrors`)
+- [Option][option] (`option`, Some, None, `isFalsy`, expect, unwrap with else, andThen)
+- [Match][match] (`match`, `matchAll`)
+- [Options][options] (`Options`)
+- [Pipe][pipe] (`pipe`)
+- [Panic][panic] (`panic`)
 
 ### Composition and conversion
 
-- [Atom][atom]
-- [To][to] (`.to()` converters)
-- [Zip][zip] (zip, zipWith, unzip)
+- [Atom][atom] (`atom`)
+- [To][to] (`.to()` on every wrapper, and `_to`)
+- [Zip][zip] (`zip`, `zipWith`, `unzip`)
 
 ### Collections and data
 
-- [list][list]
-- [struct][struct]
-- [sets][sets]
-- [Ok.iterate][iterate]
-- [memoized][memoized]
+- [list][list] (`list`)
+- [struct][struct] (`struct`)
+- [sets][sets] (`sets`)
+- [Ok.iterate][iterate] (`Ok(value).iterate()`)
+- [memoized][memoized] (`memoized`)
 
 ### Async and lifecycle
 
-- [SuperPromise][super-promise]
-- [SuperRunner][super-runner]
-- [taskGroup][task-group]
-- [Signal][signal]
-- [Channel][channel]
+- [SuperPromise][super-promise] (`superPromise`)
+- [SuperRunner][super-runner] (`superRunner`: sequence, all, race)
+- [taskGroup][task-group] (`taskGroup`)
+- [Signal][signal] (`createSignal`)
+- [Channel][channel] (`createChannel`: send, subscribe, when)
+- [createStepper][stepper] (`createStepper`)
 
 ### Small utilities
 
-- [Panic][panic]
-- [println][logging] (with `setEnvironment`)
-- [createStepper][stepper]
+- [println][logging] (`println`, `setEnvironment`)
 
-Full reference: [docs index][docs-index]. Feature list: [CHANGELOG.md][changelog]. Agent guide: [skill/SKILL.md](skill/SKILL.md).
+Full reference: [docs index][docs-index]. Feature list: [CHANGELOG.md][changelog]. Agent guide: [skill/SKILL.md][skill].
 
 ## Real-world examples
 
-### Load a value that can fail: SafeTry + Result
+### Load a value which can fail: SafeTry + Result
 
-The edge of your app probably mixes failures: a lookup that throws, a parser that rejects a value,
-an optional result. `safeTry` brings all of that into one `Result`:
+Loading saved settings can fail two ways: the saved text is not valid JSON, or the role inside
+is one you do not support. `safeTry` turns both into one `Result`:
 
 ```ts
-import { Err, Ok, safeTry, type Result, println } from "slang-ts";
+import { Ok, Err, safeTry, type Result, println } from "slang-ts";
 
 type Role = "admin" | "member";
 
+type SavedSettings = {
+  role: string;
+};
+
 function parseRole(value: string): Result<Role, string> {
-  return value === "admin" || value === "member"
-    ? Ok(value)
-    : Err("Unknown role");
+  if (value === "admin" || value === "member") {
+    return Ok(value);
+  }
+
+  return Err("Unknown role");
 }
 
-const role = await safeTry(() => {
-  const saved = localStorage.getItem("role");
-  if (saved === null) throw new Error("No role saved");
-  return parseRole(saved);
+const savedText = '{"role":"admin"}';
+
+const role = safeTry(() => {
+  const settings = JSON.parse(savedText) as SavedSettings;
+
+  return parseRole(settings.role);
 });
 
 if (role.isOk) {
-  println("Role:", role.value);
+  println("Role:", role.value); // "admin"
 } else {
-  println("Could not load role:", role.error);
+  println("Could not load the role:", role.error);
 }
 ```
 
-Without it, you'd have to catch the throw and still branch on the value:
-
-```ts
-type Role = "admin" | "member";
-
-function loadRole(): Role {
-  const saved = localStorage.getItem("role");
-  if (saved === null) throw new Error("No role saved");
-  if (saved !== "admin" && saved !== "member") throw new Error("Unknown role");
-  return saved;
-}
-
-try {
-  const role = loadRole();
-  console.log("Role:", role);
-} catch (error) {
-  console.log(
-    "Could not load role:",
-    error instanceof Error ? error.message : "Unknown error",
-  );
-}
-```
+A throw from `JSON.parse` and an `Err` from `parseRole` both come back as `Err`, so you check
+the result once. `safeTry` itself never throws. Your function is sync here, so the `Result`
+comes back directly; an async function gives you a promise of it to `await`.
 
 Full detail: [SafeTry][safe-try] and [Result][result].
 
 ### Call an API with a timeout and retries: SuperPromise
 
-Your function gets an `AbortSignal`. `timeout` aborts an attempt, `retry` runs it again after an
-ordinary failure, and you get back `Ok` or `Err` — so no `try`/`catch` around the await.
+Your function receives an `AbortSignal` to pass along to `fetch`. `timeout` stops an attempt
+once it takes too long, `retry` runs it again after a failure, and the call resolves to `Ok` or
+`Err`. It never rejects:
 
 ```ts
 import { superPromise, println } from "slang-ts";
 
-const id = "123";
+type User = {
+  id: string;
+  name: string;
+};
 
 const user = await superPromise(
-  async (signal) => {
-    const response = await fetch(`/api/users/${id}`, { signal });
-    if (!response.ok) throw new Error("User not found");
-    return (await response.json()) as { name: string };
+  async (signal: AbortSignal): Promise<User> => {
+    const response = await fetch("https://example.com/api/users/u_1", { signal });
+
+    if (!response.ok) {
+      throw new Error("Could not load the user");
+    }
+
+    return (await response.json()) as User;
   },
-  { timeout: 5000, retry: 2 },
+  { timeout: 5000, retry: 2 }, // 5 seconds per attempt, up to 2 retries
 );
 
 if (user.isOk) {
-  println("User:", user.value.name);
+  println("User:", user.value.name); // "Ada"
 } else {
-  println("Could not load user:", user.error);
+  println("Could not load the user:", user.error);
 }
 ```
 
@@ -195,8 +199,8 @@ Full detail: [SuperPromise][super-promise].
 
 ### Page a list and shape records: list + struct
 
-`list` keeps bounds strict: a bad range fails instead of quietly giving you less data. `struct`
-reads and shapes records without spreading fields you didn't choose.
+`list` keeps bounds strict: a range outside the array fails instead of returning fewer items. `struct`
+reads and shapes records, keeping only the fields you choose.
 
 ```ts
 import { list, struct, println } from "slang-ts";
@@ -208,25 +212,28 @@ type User = {
   email: string;
 };
 
-const users: User[] = await getUsers(); // your data source
+const users: User[] = [
+  { id: "u_1", name: "Ada", avatar: "/avatars/ada.png", email: "ada@example.com" },
+  { id: "u_2", name: "Grace", email: "grace@example.com" },
+  { id: "u_3", name: "Linus", email: "linus@example.com" },
+];
+
+const page = 1;
+const size = 2;
 
-const page = 2;
-const size = 20;
 const total = list(users).count().else(0);
 const start = Math.min(page * size, total);
-const paged = list(users)
-  .range(start, Math.min(start + size, total))
-  .else([]);
+const end = Math.min(start + size, total);
 
-const cards = paged.map((user) =>
-  struct(user).pick("id", "name", "avatar").else(user),
-);
+const paged = list(users).range(start, end).else([]);
+
+const cards = paged.map((user) => struct(user).pick("id", "name", "avatar").else(user));
 
-println(cards);
+println(cards); // [{"id":"u_3","name":"Linus"}]
 ```
 
-`list` won't clamp a range for you, so the example clamps the window and lets the last page be
-short. `struct` then keeps only the fields the card needs.
+`list` never shortens a range, so the example clamps the window and lets the last page
+be short. `struct` then keeps only the fields the card needs.
 
 Full detail: [list][list] and [struct][struct].
 
@@ -248,7 +255,7 @@ projects using Slang.
 
 ## Contributing
 
-Got a utility from another language that belongs here? Open an issue or a pull request.
+Got a utility from another language which belongs here? Open an issue or a pull request.
 Contributions are welcome.
 
 ## Requirements
@@ -265,6 +272,7 @@ MIT License. See [LICENSE][license].
 [option]: https://github.com/Hussseinkizz/slang/blob/main/docs/option.md
 [result]: https://github.com/Hussseinkizz/slang/blob/main/docs/result.md
 [safe-try]: https://github.com/Hussseinkizz/slang/blob/main/docs/safe-try.md
+[combine]: https://github.com/Hussseinkizz/slang/blob/main/docs/combine.md
 [match]: https://github.com/Hussseinkizz/slang/blob/main/docs/match.md
 [options]: https://github.com/Hussseinkizz/slang/blob/main/docs/match.md#options
 [pipe]: https://github.com/Hussseinkizz/slang/blob/main/docs/pipe.md

package/dist/index.d.ts

@@ -116,8 +116,52 @@ interface ResultMethods<T> {
    * Ok(5).andThen(x => undefined);         // Ok(5) - original
    * await Ok(5).andThen(async x => x);     // Ok(5)
    */
+  andThen<R extends PromiseLike<unknown>>(fn: (value: T) => R, ..._asyncOnly: AsyncCallbackGuard<R>): Result<SettledValue<Awaited<R>>, string> | Promise<Result<SettledValue<Awaited<R>>, string>>;
+  /**
+   * Sync callback overload: the result is a plain Result, so it can be read without `await`.
+   * The async overload above stays a union because a skipped `Err` returns itself
+   * synchronously; the callback never runs, so nothing can tell it was async.
+   */
+  andThen<R>(fn: (value: T) => R, ..._syncOnly: SyncCallbackGuard<R>): Result<SettledValue<R>, string>;
+  /**
+   * Fallback for a callback that may or may not return a promise, such as
+   * `flag ? value : Promise.resolve(value)`, or whose return is `unknown`. Typed as the
+   * union so the promise case is not hidden.
+   */
   andThen<U>(fn: (value: T) => U | Result<U, string> | Promise<U | Result<U, string>>): Result<U, string> | Promise<Result<U, string>>;
+  /**
+   * Rewrites the error message if `Err`, returns the same `Ok` if `Ok`.
+   * Exists so a technical message can be made human at a boundary while `.raw` keeps the
+   * cause for logs. Sync only: rewriting a message never needs to wait.
+   * - If fn throws, returns `Err(message)` with the original `.raw`.
+   * @example
+   * Err("ECONNRESET", cause).mapErr(() => "Could not reach the server"); // .raw is still cause
+   * Ok(5).mapErr(() => "never runs");                                     // same Ok
+   */
+  mapErr(fn: (error: string) => string): Result<T, string>;
+  /**
+   * Recovers from `Err`, returns the same `Ok` if `Ok`. The error-side mirror of `andThen`,
+   * named `orFn` so it is not confused with `unwrap().else()`.
+   * - `raw` is passed so recovery can inspect the cause, such as retrying only on a network failure.
+   * - A plain value becomes `Ok(value)`; a returned Result is passed through.
+   * - If fn returns `undefined`, returns the original `Err`.
+   * - If fn throws or rejects, returns `Err(message)`.
+   * @example
+   * Err("missing").orFn(() => 0);                  // Ok(0)
+   * Err("missing").orFn((e) => Err(`${e}!`));      // Err("missing!")
+   * await Err("offline").orFn(async () => cached); // Ok(cached)
+   */
+  orFn<R extends PromiseLike<unknown>>(fn: (error: string, raw: unknown) => R, ..._asyncOnly: AsyncCallbackGuard<R>): Result<T | SettledValue<Awaited<R>>, string> | Promise<Result<T | SettledValue<Awaited<R>>, string>>;
+  /** Sync callback overload: the result is a plain Result, so it can be read without `await`. */
+  orFn<R>(fn: (error: string, raw: unknown) => R, ..._syncOnly: SyncCallbackGuard<R>): Result<T | SettledValue<R>, string>;
+  /**
+   * Fallback for a callback that may or may not return a promise, or whose return is
+   * `unknown`. Typed as the union so the promise case is not hidden.
+   */
+  orFn<U>(fn: (error: string, raw: unknown) => U | Result<U, string> | Promise<U | Result<U, string>>): Result<T | U, string> | Promise<Result<T | U, string>>;
 }
+/** The value a callback's return settles to: a returned Result passes its value through. */
+type SettledValue<R> = R extends ResultMethods<infer Value> ? Value : R;
 /**
  * Creates a new, successful result.
  * @param value Value of the result. A Result is rejected; a Result never nests inside another Result.
@@ -236,15 +280,31 @@ interface OptionMethods<T> {
   };
   /**
    * Transforms the inner value if `Some`, returns `None` if `None`.
+   * - A sync callback returns a plain Option, readable without `await`.
+   * - An async callback returns `Option | Promise<Option>`: a `None` skips the callback and
+   *   returns itself synchronously, so `await` the result.
+   * - The returned value is wrapped with `option()`, not flattened: returning an Option gives
+   *   `Some(thatOption)`, and a falsy value gives `None`.
    * - If fn returns `undefined`, returns original Option (no new allocation).
-   * - If fn throws, returns `None`.
-   * - Supports async functions, returning `Promise<Option<U>>`.
+   * - If fn throws or rejects, returns `None`.
    * @example
    * option(5).andThen(x => x * 2);           // Some(10)
    * option(null).andThen(x => x * 2);        // None
    * option(5).andThen(x => undefined);       // Some(5) - original
    * await option(5).andThen(async x => x);   // Some(5)
    */
+  andThen<R extends PromiseLike<unknown>>(fn: (value: T) => R, ..._asyncOnly: AsyncCallbackGuard<R>): Option<Awaited<R>> | Promise<Option<Awaited<R>>>;
+  /**
+   * Sync callback overload: the result is a plain Option, so it can be read without `await`.
+   * The async overload above stays a union because a `None` returns itself synchronously;
+   * the callback never runs, so nothing can tell it was async.
+   */
+  andThen<R>(fn: (value: T) => R, ..._syncOnly: SyncCallbackGuard<R>): Option<R>;
+  /**
+   * Fallback for a callback that may or may not return a promise, such as
+   * `flag ? value : Promise.resolve(value)`, or whose return is `unknown`. Typed as the
+   * union so the promise case is not hidden.
+   */
   andThen<U>(fn: (value: T) => U | Promise<U>): Option<U> | Promise<Option<U>>;
 }
 /**
@@ -281,6 +341,20 @@ export declare function option<T>(value: T | NonTruthy): Option<T> & OptionMetho
  * Used internally for deferred error handling in unwrap chains.
  */
 export declare const scheduleMicrotask: (fn: () => void) => void;
+/** Evaluated value result type */
+/**
+ * Rest-parameter guard for a sync-callback overload: matches only callbacks whose return
+ * type is known to hold no promise. `unknown`, `any` and promise unions fall through to the
+ * union overload, because at runtime they may return either shape. `Rest` lets a caller add
+ * its own guard once the callback is known to be sync.
+ */
+type SyncCallbackGuard<T, Rest extends readonly string[] = []> = unknown extends T ? [never] : [Extract<T, PromiseLike<unknown>>] extends [never] ? Rest : [never];
+/**
+ * Rest-parameter guard for a promise-callback overload: matches only real promise returns.
+ * A callback that only throws returns `never`, which is assignable to a promise type but
+ * runs synchronously, so it is sent to the sync overload.
+ */
+type AsyncCallbackGuard<R, Rest extends readonly string[] = []> = [R] extends [never] ? [never] : Rest;
 //#endregion
 //#region src/println.d.ts
 type EnvironmentMode = "development" | "production" | "dev" | "prod";
@@ -293,12 +367,12 @@ type EnvironmentOptions = {
  * Safe to call any number of times, in any order; the last call wins.
  * Accepts a mode (full words or short forms: "development"/"dev", "production"/"prod")
  * or options `{ printFn }` to route println through an existing logger instead of
- * the console — useful in production, where logs go somewhere real.
+ * the console: useful in production, where logs go somewhere real.
  * Pass `{ printFn: null }` to switch back to the console.
  */
 export declare const setEnvironment: (next: EnvironmentMode | EnvironmentOptions) => void;
 /**
- * Prints a line to the console — args joined with spaces, newline appended.
+ * Prints a line to the console: args joined with spaces, newline appended.
  * When a custom printFn is set, the line goes to it instead, in every mode.
  * Otherwise production mode is silent, so dev chatter never leaks to prod logs.
  */
@@ -317,6 +391,28 @@ export declare const println: (...args: unknown[]) => void;
  */
 export declare function panic(message: string): never;
 //#endregion
+//#region src/combine.d.ts
+/** Maps a tuple or array of Results to the tuple or array of their success values. */
+type CombinedValues<R extends readonly Result<unknown, string>[]> = { -readonly [K in keyof R]: R[K] extends ResultMethods<infer Value> ? Value : never; };
+/**
+ * Combines results you already have into one Result of all their values.
+ * Stops at the first failure and returns that same `Err` instance, so its `.raw` cause is
+ * kept. Sync by design: dependent steps belong in `pipe`, async tasks in `superRunner`.
+ * @example
+ * combineResults([Ok(1), Ok("a")]); // Ok([1, "a"]), typed Result<[number, string], string>
+ * combineResults([Ok(1), Err("bad")]); // the Err("bad") instance
+ * combineResults([]); // Ok([])
+ */
+export declare function combineResults<R extends readonly Result<unknown, string>[]>(results: readonly [...R]): Result<CombinedValues<R>, string>;
+/**
+ * Collects every error message, in input order, so a form can show all problems at once
+ * instead of only the first. Returns `[]` when every result is `Ok`.
+ * @example
+ * combineErrors([Err("Enter a valid email"), Ok("Ada"), Err("Name is required")]);
+ * // ["Enter a valid email", "Name is required"]
+ */
+export declare function combineErrors(results: readonly Result<unknown, string>[]): string[];
+//#endregion
 //#region src/options.d.ts
 /**
  * Resolves the usable inner type of a value.
@@ -339,8 +435,8 @@ type OptionsValue<T> = T extends {
  * Returns the first usable value from a list as an `Ok`, or the fallback
  * `Err` if none is usable.
  *
- * Normalizes mixed values — raw values, `Option`s, and `Result`s
- * from different sources — when all you care about is whether any of them
+ * Normalizes mixed values: raw values, `Option`s, and `Result`s
+ * from different sources: when all you care about is whether any of them
  * is usable. A value is usable when its unwrapped inner value is truthy;
  * `None`, `Err`, null, undefined, `""`, NaN, and Infinity are skipped.
  * Note that `0` and `false` count as usable, just as they do in `option()`.
@@ -375,7 +471,7 @@ export declare function _to<E = string>(value: Atom<any>, target: "result"): Res
 //#endregion
 //#region src/match.d.ts
 /**
- * Pattern matching for `Result` and `Option` — exhaustiveness enforced.
+ * Pattern matching for `Result` and `Option`: exhaustiveness enforced.
  *
  * Returns the value returned by the selected handler. If all handlers return
  * `Result` or `Option`, TypeScript will infer that automatically.
@@ -496,29 +592,34 @@ type SafeTryOptions = {
 };
 /**
  * Captures failures and resolves nested Slang wrappers into one Result.
- * - Awaits the callback, then iteratively unwraps Result, Option, and Atom values.
+ * - A sync callback gets its Result back directly; a promise-returning callback
+ *   gets a Promise of the Result. `await` works on both, so callers need not know.
+ * - Iteratively unwraps Result, Option, and Atom values.
  * - Returns the first Err or None as Err; cycles also return Err.
  * - Leaves object properties, array elements, and wrapped Promise values intact.
- * - `{ throw: true }` re-throws thrown errors; returned failures remain Err.
+ * - `{ throw: true }` re-throws thrown errors (synchronously for a sync callback,
+ *   as a rejection for an async one); returned failures remain Err.
  * - `{ collectValues: true }` records every unwrapped layer and failure on
  *   `result.raw` as `{ errors, values }`.
  * - A caught throw reaches the caller as `Err(message)`, with the thrown value on `.raw`.
  *
  * @param fn - Function to execute (sync or async)
  * @param options - `{ throw?: boolean; collectValues?: boolean }`
- * @returns Promise of one Result containing the final success value or error text
+ * @returns One Result for a sync callback, a Promise of one Result for an async one
  *
  * @example
- * const result = await safeTry(() => Ok(option("Hello")));
+ * const result = safeTry(() => Ok(option("Hello")));
  * if (result.isOk) println(result.value); // "Hello"
  *
  * @example
- * const result = await safeTry(() => {
+ * const result = await safeTry(async () => {
  *   throw new Error("Oops!");
  * });
  * if (result.isErr) println(result.error);
  */
-export declare function safeTry<T>(fn: () => T | Promise<T>, options?: SafeTryOptions, ..._noNestedResult: NestedValueGuard<Awaited<T>>): Promise<Result<SafeTryValue<Awaited<T>>, string>>;
+export declare function safeTry<R extends PromiseLike<unknown>>(fn: () => R, options?: SafeTryOptions, ..._noNestedResult: AsyncCallbackGuard<R, NestedValueGuard<Awaited<R>>>): Promise<Result<SafeTryValue<Awaited<R>>, string>>;
+export declare function safeTry<T>(fn: () => T, options?: SafeTryOptions, ..._noNestedResult: SyncCallbackGuard<T, NestedValueGuard<T>>): Result<SafeTryValue<T>, string>;
+export declare function safeTry<T>(fn: () => T | PromiseLike<T>, options?: SafeTryOptions, ..._noNestedResult: NestedValueGuard<T>): Result<SafeTryValue<T>, string> | Promise<Result<SafeTryValue<T>, string>>;
 //#endregion
 //#region src/list.d.ts
 /** Accepted list input: a raw array, or a narrowed successful `Ok` holding one. */
@@ -773,7 +874,7 @@ export declare function pipe<T, E = string>(initial: T, ...fns: PipeFn[]): Pipel
 type Executor<T> = (signal: AbortSignal) => T | Promise<T> | Result<T, string> | Promise<Result<T, string>>;
 /** Stop signal for `retryUntil`. */
 type RetryUntilOptions = {
-  /** When this fires, retrying ends — mid-attempt firings cancel the in-flight attempt. */
+  /** When this fires, retrying ends: mid-attempt firings cancel the in-flight attempt. */
   signal: AbortSignal;
   /** Wait between attempts. No wait applies before the first attempt. */
   delay?: number;
@@ -786,7 +887,7 @@ type SuperPromiseOptions = {
   delay?: number;
   /** Abort the operation after this many milliseconds. Timeouts are never retried. */
   timeout?: number;
-  /** `n` retries after the first attempt — `n + 1` attempts total. Aborts and timeouts are never retried. */
+  /** `n` retries after the first attempt: `n + 1` attempts total. Aborts and timeouts are never retried. */
   retry?: number;
   /** Keep retrying until the stop signal fires. Overrides `retry` and `delay`. */
   retryUntil?: RetryUntilOptions;
@@ -807,13 +908,13 @@ type SuperPromise<T> = {
   tap(fn: (value: T) => unknown | Promise<unknown>): SuperPromise<T>;
   /** Promise-compatible. The callback receives the settled `Result`; the task never rejects. */
   then<TR1 = Result<T, string>, TR2 = never>(onfulfilled?: ((value: Result<T, string>) => TR1 | PromiseLike<TR1>) | null, onrejected?: ((reason: unknown) => TR2 | PromiseLike<TR2>) | null): Promise<TR1 | TR2>;
-  /** Promise-compatible. Effectively dead — failures are captured into `Err`, never rejections. */
+  /** Promise-compatible. Effectively dead: failures are captured into `Err`, never rejections. */
   catch<TR = never>(onrejected?: ((reason: unknown) => TR | PromiseLike<TR>) | null): Promise<Result<T, string> | TR>;
   /** Promise-compatible. Native behavior. */
   finally(onfinally?: (() => void) | null): Promise<Result<T, string>>;
 };
 /**
- * Creates a SuperPromise — one async operation plus start, retry, timeout, and cancel controls.
+ * Creates a SuperPromise: one async operation plus start, retry, timeout, and cancel controls.
  *
  * Lazy start: your function runs on first use (`await`/`.then()`, or a runner's `start()`),
  * not at creation. Defer chains start recursively, so awaiting a deferred task runs its
@@ -891,7 +992,7 @@ type Channel = {
   }): void;
 };
 /**
- * Creates a Channel — completely independent of SuperPromise/SuperRunner.
+ * Creates a Channel: completely independent of SuperPromise/SuperRunner.
  *
  * @example
  * const channel = createChannel();
@@ -907,7 +1008,7 @@ export declare function createChannel(): Channel;
 //#endregion
 //#region src/signal.d.ts
 /**
- * A lifecycle Signal — a trigger that fires once and stays fired.
+ * A lifecycle Signal: a trigger that fires once and stays fired.
  *
  * ... structurally an `AbortSignal` plus a `fire()` method,
  * so it can be passed anywhere a native `AbortSignal` is expected
@@ -933,9 +1034,9 @@ type Signal = AbortSignal & {
  * signal.aborted; // true
  * ```
  *
- * Listeners are NOT replayed after firing — consumers must check
+ * Listeners are NOT replayed after firing: consumers must check
  * `signal.aborted` synchronously to detect an already-fired signal.
  */
 export declare function createSignal(): Signal;
 //#endregion
-export type { Atom, AtomMethods, Channel, ChannelEvent, ChannelSubscriber, EnvironmentMode, EnvironmentOptions, Err as ErrType, Executor, Fallible, IterateChain, ListChain, ListGet, ListInput, Memoized, NextOptions, NonTruthy, None, Ok as OkType, Option, OptionMethods, OptionsValue, PipeEachContext, PipeFn, PipeRunOptions, Pipeline, PrevRecover, PrevResolution, PrintFn, Result, ResultMethods, RetryUntilOptions, SetsChain, SetsInput, Signal, SlangErrorCategory, Some, Step, StepFactory, StepFn, Stepper, StepperConfig, StructChain, StructGet, SuperPromise, SuperPromiseOptions, SuperRunner, TaskGroup, TaskGroupOptions };
+export type { Atom, AtomMethods, Channel, ChannelEvent, ChannelSubscriber, CombinedValues, EnvironmentMode, EnvironmentOptions, Err as ErrType, Executor, Fallible, IterateChain, ListChain, ListGet, ListInput, Memoized, NextOptions, NonTruthy, None, Ok as OkType, Option, OptionMethods, OptionsValue, PipeEachContext, PipeFn, PipeRunOptions, Pipeline, PrevRecover, PrevResolution, PrintFn, Result, ResultMethods, RetryUntilOptions, SetsChain, SetsInput, Signal, SlangErrorCategory, Some, Step, StepFactory, StepFn, Stepper, StepperConfig, StructChain, StructGet, SuperPromise, SuperPromiseOptions, SuperRunner, TaskGroup, TaskGroupOptions };