nalloc 0.0.1 → 0.0.2

package/README.md

@@ -44,7 +44,7 @@ npm install nalloc
 ## Quick start
 
 ```ts
-import { Option, Result, ok, err, none } from 'nalloc';
+import { Option, Result, ok, err, none, safeTry, unwrap } from 'nalloc';
 
 // Option: the value IS the Option
 const port = Option.fromNullable(process.env.PORT);
@@ -57,6 +57,13 @@ const data = Result.match(
   cfg => cfg,
   error => ({ fallback: true })
 );
+
+// safeTry: Rust-like ? operator
+const result = safeTry(() => {
+  const a = unwrap(parseNumber('10'));
+  const b = unwrap(parseNumber('5'));
+  return a + b;
+}); // Ok(15) or Err(...)
 ```
 
 ## How it works
@@ -105,7 +112,7 @@ Option.map(42, x => x * 2);               // value IS the Option
 The API mirrors Rust's `Option` and `Result`:
 
 ```ts
-import { Option, Result, ok, err, none } from 'nalloc';
+import { Option, Result, ok, err, none, safeTry, unwrap } from 'nalloc';
 
 // Rust: Some(42).map(|x| x * 2)
 Option.map(42, x => x * 2);
@@ -115,6 +122,12 @@ Result.andThen(ok(42), x => x > 0 ? ok(x) : err('negative'));
 
 // Rust: result.unwrap_or(0)
 Result.unwrapOr(result, 0);
+
+// Rust: let value = try!(get_value())  /  let value = get_value()?
+const value = safeTry(() => {
+  const a = unwrap(getValue());
+  return a + 1;
+});
 ```
 
 ## Option
@@ -158,7 +171,7 @@ const maybeUser = await Option.fromPromise(fetchUserById(id));
 A `Result<T, E>` is either `Ok<T>` (the value itself) or `Err<E>` (a wrapper).
 
 ```ts
-import { Result, ok, err } from 'nalloc';
+import { Result, ok, err, safeTry, safeTryAsync, unwrap } from 'nalloc';
 
 // Wrap throwing functions
 const parsed = Result.tryCatch(
@@ -166,11 +179,18 @@ const parsed = Result.tryCatch(
   e => 'invalid json'
 );
 
-// Async operations
-const data = await Result.fromPromise(fetch('/api'));
-const processed = await Result.tryAsync(async () => {
-  const res = await fetch('/api');
-  return res.json();
+// safeTry: Rust-like ? operator for imperative error handling
+const result = safeTry(() => {
+  const config = unwrap(parseConfig(raw));
+  const db = unwrap(connectDb(config.url));
+  return db.query('SELECT 1');
+});
+
+// Async safeTry
+const data = await safeTryAsync(async () => {
+  const res = unwrap(await fetchUser(id));
+  const posts = unwrap(await fetchPosts(res.id));
+  return { user: res, posts };
 });
 
 // Transform
@@ -195,6 +215,34 @@ const first = Result.any([err('a'), ok(42), err('b')]);  // Ok(42)
 const [oks, errs] = Result.partition(results);
 ```
 
+## Iter
+
+Iterator utilities for working with fallible iteration and Result streams.
+
+```ts
+import { Iter } from 'nalloc';
+
+// Safe iteration: wraps throws as Err, values as Ok
+for (const result of Iter.safeIter(riskyIterator)) {
+  if (isOk(result)) handleValue(result);
+  else handleError(result.error);
+}
+
+// mapWhile: yields mapped values while fn returns Some
+const taken = [...Iter.mapWhile([1, 2, 3, 4, 5], n =>
+  n < 4 ? n * 10 : null
+)]; // [10, 20, 30]
+
+// tryCollect: collect Results into Result<T[], E>
+const collected = Iter.tryCollect(results); // Ok([1, 2, 3]) or first Err
+
+// tryFold: fold with early exit on Err
+const sum = Iter.tryFold([1, 2, 3], 0, (acc, n) => ok(acc + n));
+
+// tryForEach: iterate with early exit on Err
+Iter.tryForEach(items, item => processItem(item));
+```
+
 ## API Reference
 
 ### Option
@@ -205,62 +253,100 @@ const [oks, errs] = Result.partition(results);
 | `fromPromise(promise)` | Promise to Option (rejection = None) |
 | `map(opt, fn)` | Transform Some value |
 | `flatMap(opt, fn)` | Chain Option-returning functions |
+| `andThen(opt, fn)` | Alias for flatMap |
+| `tap(opt, fn)` | Side effect on Some, return original |
 | `filter(opt, predicate)` | Keep Some if predicate passes |
 | `match(opt, onSome, onNone)` | Pattern match |
 | `unwrap(opt)` | Extract or throw |
 | `unwrapOr(opt, default)` | Extract or default |
 | `unwrapOrElse(opt, fn)` | Extract or compute default |
+| `unwrapOrReturn(opt, fn)` | Extract or return computed value |
+| `expect(opt, msg)` | Extract or throw with message |
 | `assertSome(opt, msg?)` | Assert and narrow to Some |
 | `isSome(opt)` / `isNone(opt)` | Type guards |
+| `isSomeAnd(opt, pred)` | Some and predicate passes |
+| `isNoneOr(opt, pred)` | None or predicate passes |
+| `or(opt, other)` | Return first Some |
+| `orElse(opt, fn)` | Return Some or compute fallback |
+| `and(opt, other)` | Return second if first is Some |
+| `xor(opt, other)` | Some if exactly one is Some |
+| `zip(opt, other)` | Combine two Options into tuple |
+| `unzip(opt)` | Split tuple Option into two |
+| `flatten(opt)` | Flatten nested Option |
+| `contains(opt, value)` | Check if Some contains value |
+| `mapOr(opt, default, fn)` | Map or return default |
+| `mapOrElse(opt, defaultFn, fn)` | Map or compute default |
+| `toArray(opt)` | Some to [value], None to [] |
+| `toNullable(opt)` | Some to value, None to null |
+| `toUndefined(opt)` | Some to value, None to undefined |
+| `okOr(opt, error)` | Option to Result |
+| `okOrElse(opt, fn)` | Option to Result with computed error |
+| `ofOk(result)` | Ok to Some, Err to None |
+| `ofErr(result)` | Err to Some, Ok to None |
 | `filterMap(items, fn)` | Map and filter in one pass |
+| `findMap(items, fn)` | Find first Some from mapping |
 
 ### Result
 
 | Function | Description |
 |----------|-------------|
 | `tryCatch(fn, onError?)` | Wrap throwing function |
-| `tryAsync(fn, onError?)` | Wrap async function |
-| `fromPromise(promise)` | Promise to Result |
+| `tryCatchMaybePromise(fn, onError?)` | Wrap sync-or-async, preserving sync |
+| `of(fn)` | Alias for tryCatch (no error mapper) |
+| `safeTry(fn)` | Imperative error handling with unwrap |
+| `safeTryAsync(fn)` | Async version of safeTry |
+| `unwrap(result)` | Extract Ok or throw error value |
+| `unwrapErr(result)` | Extract Err or throw |
+| `unwrapOr(result, default)` | Extract Ok or default |
+| `unwrapOrElse(result, fn)` | Extract Ok or compute from error |
+| `unwrapOrReturn(result, fn)` | Extract Ok or return computed value |
+| `expect(result, msg)` | Extract Ok or throw with message |
+| `expectErr(result, msg)` | Extract Err or throw with message |
 | `map(result, fn)` | Transform Ok value |
 | `mapErr(result, fn)` | Transform Err value |
+| `bimap(result, okFn, errFn)` | Transform both Ok and Err |
 | `flatMap(result, fn)` | Chain Result-returning functions |
+| `andThen(result, fn)` | Alias for flatMap |
+| `tap(result, fn)` | Side effect on Ok, return original |
+| `tapErr(result, fn)` | Side effect on Err, return original |
 | `match(result, onOk, onErr)` | Pattern match |
-| `unwrap(result)` | Extract Ok or throw |
-| `unwrapOr(result, default)` | Extract Ok or default |
 | `assertOk(result, msg?)` | Assert and narrow to Ok |
+| `assertErr(result, msg?)` | Assert and narrow to Err |
 | `isOk(result)` / `isErr(result)` | Type guards |
+| `isOkAnd(result, pred)` | Ok and predicate passes |
+| `isErrAnd(result, pred)` | Err and predicate passes |
+| `isSomeErr(result)` | Err with non-null error |
+| `and(result, other)` | Return second if first is Ok |
+| `or(result, other)` | Return first Ok |
+| `orElse(result, fn)` | Ok or compute fallback from error |
+| `zip(a, b)` | Combine two Ok into tuple |
+| `zipWith(a, b, fn)` | Combine two Ok with function |
+| `flatten(result)` | Flatten nested Result |
+| `transpose(result)` | Result<Option> to Option<Result> |
+| `toOption(result)` | Ok to Some, Err to None |
+| `toErrorOption(result)` | Err to Some, Ok to None |
+| `mapOr(result, default, fn)` | Map Ok or return default |
+| `mapOrElse(result, defaultFn, fn)` | Map Ok or compute default |
 | `all(results)` | Collect all Ok or first Err |
 | `any(results)` | First Ok or all Errs |
+| `collect(results)` | Collect Ok values or first Err |
+| `collectAll(results)` | All Ok or all Errs |
 | `partition(results)` | Split into [oks, errs] |
 | `partitionAsync(promises)` | Async partition |
+| `filterOk(results)` | Extract all Ok values |
+| `filterErr(results)` | Extract all Err values |
+| `settleMaybePromise(values)` | Settle sync/async values to Results |
+| `partitionMaybePromise(values)` | Partition sync/async Results |
 
-## Testing
-
-```ts
-import { expectOk, expectErr, expectSome, expectNone, extendExpect } from 'nalloc/testing';
-import { expect } from 'vitest';
-
-extendExpect(expect);
-
-expect(result).toBeOk();
-expect(result).toBeErr();
-expect(option).toBeSome();
-expect(option).toBeNone();
-
-const value = expectOk(result);  // returns value or throws
-```
+### Iter
 
-## Devtools
-
-```ts
-import { formatResult, formatOption, inspectResult, inspectOption } from 'nalloc/devtools';
-
-formatResult(ok(42));    // "Ok(42)"
-formatOption(null);      // "None"
-
-inspectResult(ok(42));   // { status: 'ok', value: 42 }
-inspectOption(42);       // { kind: 'some', value: 42 }
-```
+| Function | Description |
+|----------|-------------|
+| `safeIter(source)` | Wrap iterable: values as Ok, throws as Err |
+| `mapWhile(source, fn)` | Yield mapped values while fn returns Some |
+| `tryCollect(source)` | Collect Results into Result<T[], E> |
+| `tryFold(source, init, fn)` | Fold with early exit on Err |
+| `tryForEach(source, fn)` | Iterate with early exit on Err |
 
 ## Comparison
 

package/build/index.cjs

@@ -2,75 +2,19 @@
 Object.defineProperty(exports, "__esModule", {
     value: true
 });
-function _export(target, all) {
-    for(var name in all)Object.defineProperty(target, name, {
-        enumerable: true,
-        get: Object.getOwnPropertyDescriptor(all, name).get
-    });
-}
-_export(exports, {
-    get Option () {
-        return _optioncjs;
-    },
-    get Result () {
-        return _resultcjs;
-    },
-    get err () {
-        return _typescjs.err;
-    },
-    get none () {
-        return _typescjs.none;
-    },
-    get ok () {
-        return _typescjs.ok;
-    },
-    get some () {
-        return _typescjs.some;
-    }
-});
-const _typescjs = require("./types.cjs");
-const _optioncjs = /*#__PURE__*/ _interop_require_wildcard(require("./option.cjs"));
-const _resultcjs = /*#__PURE__*/ _interop_require_wildcard(require("./result.cjs"));
-function _getRequireWildcardCache(nodeInterop) {
-    if (typeof WeakMap !== "function") return null;
-    var cacheBabelInterop = new WeakMap();
-    var cacheNodeInterop = new WeakMap();
-    return (_getRequireWildcardCache = function(nodeInterop) {
-        return nodeInterop ? cacheNodeInterop : cacheBabelInterop;
-    })(nodeInterop);
-}
-function _interop_require_wildcard(obj, nodeInterop) {
-    if (!nodeInterop && obj && obj.__esModule) {
-        return obj;
-    }
-    if (obj === null || typeof obj !== "object" && typeof obj !== "function") {
-        return {
-            default: obj
-        };
-    }
-    var cache = _getRequireWildcardCache(nodeInterop);
-    if (cache && cache.has(obj)) {
-        return cache.get(obj);
-    }
-    var newObj = {
-        __proto__: null
-    };
-    var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;
-    for(var key in obj){
-        if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {
-            var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;
-            if (desc && (desc.get || desc.set)) {
-                Object.defineProperty(newObj, key, desc);
-            } else {
-                newObj[key] = obj[key];
-            }
+_export_star(require("./safe.cjs"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
         }
-    }
-    newObj.default = obj;
-    if (cache) {
-        cache.set(obj, newObj);
-    }
-    return newObj;
+    });
+    return from;
 }
 
 //# sourceMappingURL=index.cjs.map

package/build/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export { some, none, ok, err } from './types.js';\nexport type {\n  Some,\n  None,\n  Ok,\n  Err,\n  Option as OptionType,\n  OptionValue,\n  IsOption,\n  InferSome,\n  Result as ResultType,\n  ResultValue,\n  ResultErrorType,\n  IsResult,\n  InferErr,\n} from './types.js';\nexport * as Option from './option.js';\nexport * as Result from './result.js';\n"],"names":["Option","Result","err","none","ok","some"],"mappings":";;;;;;;;;;;QAgBYA;;;QACAC;;;QAjBaC;eAAAA,aAAG;;QAAbC;eAAAA,cAAI;;QAAEC;eAAAA,YAAE;;QAAdC;eAAAA,cAAI;;;0BAAuB;mEAgBZ;mEACA"}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './safe.js';\n"],"names":[],"mappings":";;;;qBAAc"}

package/build/index.d.ts

@@ -1,4 +1 @@
-export { some, none, ok, err } from './types.js';
-export type { Some, None, Ok, Err, Option as OptionType, OptionValue, IsOption, InferSome, Result as ResultType, ResultValue, ResultErrorType, IsResult, InferErr, } from './types.js';
-export * as Option from './option.js';
-export * as Result from './result.js';
+export * from './safe.js';

package/build/index.js

@@ -1,5 +1,3 @@
-export { some, none, ok, err } from "./types.js";
-export * as Option from "./option.js";
-export * as Result from "./result.js";
+export * from "./safe.js";
 
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export { some, none, ok, err } from './types.js';\nexport type {\n  Some,\n  None,\n  Ok,\n  Err,\n  Option as OptionType,\n  OptionValue,\n  IsOption,\n  InferSome,\n  Result as ResultType,\n  ResultValue,\n  ResultErrorType,\n  IsResult,\n  InferErr,\n} from './types.js';\nexport * as Option from './option.js';\nexport * as Result from './result.js';\n"],"names":["some","none","ok","err","Option","Result"],"mappings":"AAAA,SAASA,IAAI,EAAEC,IAAI,EAAEC,EAAE,EAAEC,GAAG,QAAQ,aAAa;AAgBjD,OAAO,KAAKC,MAAM,MAAM,cAAc;AACtC,OAAO,KAAKC,MAAM,MAAM,cAAc"}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './safe.js';\n"],"names":[],"mappings":"AAAA,cAAc,YAAY"}

package/build/iter.cjs

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get mapWhile () {
+        return mapWhile;
+    },
+    get safeIter () {
+        return safeIter;
+    },
+    get tryCollect () {
+        return tryCollect;
+    },
+    get tryFold () {
+        return tryFold;
+    },
+    get tryForEach () {
+        return tryForEach;
+    }
+});
+const _typescjs = require("./types.cjs");
+function* mapWhile(source, fn) {
+    for (const item of source){
+        const mapped = fn(item);
+        if (!(0, _typescjs.isSome)(mapped)) return;
+        yield mapped;
+    }
+}
+function safeIter(source) {
+    const iter = source[Symbol.iterator]();
+    let done = false;
+    return {
+        [Symbol.iterator] () {
+            return this;
+        },
+        next () {
+            if (done) return {
+                value: undefined,
+                done: true
+            };
+            try {
+                const next = iter.next();
+                if (next.done) {
+                    done = true;
+                    return next;
+                }
+                return {
+                    value: next.value,
+                    done: false
+                };
+            } catch (e) {
+                done = true;
+                return {
+                    value: (0, _typescjs.err)(e),
+                    done: false
+                };
+            }
+        },
+        return () {
+            if (!done) {
+                done = true;
+                try {
+                    iter.return?.();
+                } catch  {}
+            }
+            return {
+                value: undefined,
+                done: true
+            };
+        }
+    };
+}
+function tryCollect(source) {
+    const collected = [];
+    for (const result of source){
+        if ((0, _typescjs.isErr)(result)) return result;
+        collected.push(result);
+    }
+    return collected;
+}
+function tryFold(source, init, fn) {
+    let acc = init;
+    for (const item of source){
+        const result = fn(acc, item);
+        if ((0, _typescjs.isErr)(result)) return result;
+        acc = result;
+    }
+    return acc;
+}
+function tryForEach(source, fn) {
+    for (const item of source){
+        const result = fn(item);
+        if ((0, _typescjs.isErr)(result)) return result;
+    }
+    return undefined;
+}
+
+//# sourceMappingURL=iter.cjs.map

package/build/iter.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/iter.ts"],"sourcesContent":["import { isSome, isErr, err as ERR } from './types.js';\nimport type { Option, Result, Ok } from './types.js';\n\n/**\n * Yields mapped values while the mapping function returns Some, stops at the first None.\n * @param source - The iterable to map over\n * @param fn - Mapping function returning Some(value) to continue or None to stop\n * @returns Generator of mapped values\n * @example\n * [...mapWhile([1, 2, 3, 4], n => n < 3 ? some(n * 10) : none)] // [10, 20]\n */\nexport function* mapWhile<T, U>(source: Iterable<T>, fn: (value: T) => Option<U>): Generator<U> {\n  for (const item of source) {\n    const mapped = fn(item);\n    if (!isSome(mapped)) return;\n    yield mapped as U;\n  }\n}\n\n/**\n * Wraps an iterable so that each yielded value becomes Ok and any throw becomes a single Err.\n * Stops after the first error - the source's internal state is unknown after an exception.\n *\n * Uses a manual iterator instead of a generator to avoid coroutine suspend/resume overhead.\n *\n * Follows the for-of IteratorClose spec:\n * - iter.return() is never called on natural exhaustion or after a caught error\n * - iter.return() is only called on early consumer exit (break/return)\n * - Cleanup errors from iter.return() are suppressed\n *\n * @param source - The iterable to wrap\n * @returns Iterable iterator of Result values\n * @example\n * [...safeIter([1, 2, 3])]       // [Ok(1), Ok(2), Ok(3)]\n * [...safeIter(throwingIter())]   // [Ok(1), Err(error)]\n */\nexport function safeIter<T>(source: Iterable<T>): IterableIterator<Result<T, unknown>> {\n  const iter = source[Symbol.iterator]();\n  let done = false;\n  return {\n    [Symbol.iterator]() {\n      return this;\n    },\n    next(): IteratorResult<Result<T, unknown>> {\n      if (done) return { value: undefined, done: true };\n      try {\n        const next = iter.next();\n        if (next.done) {\n          done = true;\n          return next;\n        }\n        return { value: next.value as Ok<T>, done: false };\n      } catch (e) {\n        done = true;\n        return { value: ERR(e), done: false };\n      }\n    },\n    return(): IteratorResult<Result<T, unknown>> {\n      if (!done) {\n        done = true;\n        try {\n          iter.return?.();\n        } catch {\n          // suppressed\n        }\n      }\n      return { value: undefined, done: true };\n    },\n  };\n}\n\n// -- Result-oriented terminal operations --\n\n/**\n * Collects an iterable of Results into a single Result containing an array.\n * Short-circuits on the first Err.\n * @param source - Iterable of Result values\n * @returns Ok(values[]) if all Ok, or the first Err encountered\n * @example\n * tryCollect([ok(1), ok(2), ok(3)])   // Ok([1, 2, 3])\n * tryCollect([ok(1), err('x')])       // Err('x')\n */\nexport function tryCollect<T, E>(source: Iterable<Result<T, E>>): Result<T[], E> {\n  const collected: T[] = [];\n  for (const result of source) {\n    if (isErr(result)) return result;\n    collected.push(result as T);\n  }\n  return collected as Ok<T[]>;\n}\n\n/**\n * Folds an iterable with a fallible accumulator function.\n * Short-circuits on the first Err returned by fn.\n * @param source - The iterable to fold over\n * @param init - Initial accumulator value\n * @param fn - Folding function returning Ok(newAcc) or Err\n * @returns Ok(finalAcc) if all steps succeed, or the first Err\n * @example\n * tryFold([1, 2, 3], 0, (acc, n) => ok(acc + n))   // Ok(6)\n * tryFold([1, 2, 3], 0, (acc, n) => n === 2 ? err('stop') : ok(acc + n))  // Err('stop')\n */\nexport function tryFold<T, Acc, E>(source: Iterable<T>, init: Acc, fn: (acc: Acc, item: T) => Result<Acc, E>): Result<Acc, E> {\n  let acc = init;\n  for (const item of source) {\n    const result = fn(acc, item);\n    if (isErr(result)) return result;\n    acc = result as Acc;\n  }\n  return acc as Ok<Acc>;\n}\n\n/**\n * Iterates over a source, calling a fallible function for each item.\n * Short-circuits on the first Err returned by fn.\n * @param source - The iterable to iterate over\n * @param fn - Function to call for each item, returning Ok(void) or Err\n * @returns Ok(void) if all calls succeed, or the first Err\n * @example\n * tryForEach([1, 2, 3], n => ok(console.log(n)))  // Ok(void), logs 1, 2, 3\n * tryForEach([1, 2, 3], n => n === 2 ? err('stop') : ok(undefined))  // Err('stop')\n */\nexport function tryForEach<T, E>(source: Iterable<T>, fn: (item: T) => Result<void, E>): Result<void, E> {\n  for (const item of source) {\n    const result = fn(item);\n    if (isErr(result)) return result;\n  }\n  return undefined as Ok<void>;\n}\n"],"names":["mapWhile","safeIter","tryCollect","tryFold","tryForEach","source","fn","item","mapped","isSome","iter","Symbol","iterator","done","next","value","undefined","e","ERR","return","collected","result","isErr","push","init","acc"],"mappings":";;;;;;;;;;;QAWiBA;eAAAA;;QAyBDC;eAAAA;;QA8CAC;eAAAA;;QAoBAC;eAAAA;;QAoBAC;eAAAA;;;0BA1H0B;AAWnC,UAAUJ,SAAeK,MAAmB,EAAEC,EAA2B;IAC9E,KAAK,MAAMC,QAAQF,OAAQ;QACzB,MAAMG,SAASF,GAAGC;QAClB,IAAI,CAACE,IAAAA,gBAAM,EAACD,SAAS;QACrB,MAAMA;IACR;AACF;AAmBO,SAASP,SAAYI,MAAmB;IAC7C,MAAMK,OAAOL,MAAM,CAACM,OAAOC,QAAQ,CAAC;IACpC,IAAIC,OAAO;IACX,OAAO;QACL,CAACF,OAAOC,QAAQ,CAAC;YACf,OAAO,IAAI;QACb;QACAE;YACE,IAAID,MAAM,OAAO;gBAAEE,OAAOC;gBAAWH,MAAM;YAAK;YAChD,IAAI;gBACF,MAAMC,OAAOJ,KAAKI,IAAI;gBACtB,IAAIA,KAAKD,IAAI,EAAE;oBACbA,OAAO;oBACP,OAAOC;gBACT;gBACA,OAAO;oBAAEC,OAAOD,KAAKC,KAAK;oBAAWF,MAAM;gBAAM;YACnD,EAAE,OAAOI,GAAG;gBACVJ,OAAO;gBACP,OAAO;oBAAEE,OAAOG,IAAAA,aAAG,EAACD;oBAAIJ,MAAM;gBAAM;YACtC;QACF;QACAM;YACE,IAAI,CAACN,MAAM;gBACTA,OAAO;gBACP,IAAI;oBACFH,KAAKS,MAAM;gBACb,EAAE,OAAM,CAER;YACF;YACA,OAAO;gBAAEJ,OAAOC;gBAAWH,MAAM;YAAK;QACxC;IACF;AACF;AAaO,SAASX,WAAiBG,MAA8B;IAC7D,MAAMe,YAAiB,EAAE;IACzB,KAAK,MAAMC,UAAUhB,OAAQ;QAC3B,IAAIiB,IAAAA,eAAK,EAACD,SAAS,OAAOA;QAC1BD,UAAUG,IAAI,CAACF;IACjB;IACA,OAAOD;AACT;AAaO,SAASjB,QAAmBE,MAAmB,EAAEmB,IAAS,EAAElB,EAAyC;IAC1G,IAAImB,MAAMD;IACV,KAAK,MAAMjB,QAAQF,OAAQ;QACzB,MAAMgB,SAASf,GAAGmB,KAAKlB;QACvB,IAAIe,IAAAA,eAAK,EAACD,SAAS,OAAOA;QAC1BI,MAAMJ;IACR;IACA,OAAOI;AACT;AAYO,SAASrB,WAAiBC,MAAmB,EAAEC,EAAgC;IACpF,KAAK,MAAMC,QAAQF,OAAQ;QACzB,MAAMgB,SAASf,GAAGC;QAClB,IAAIe,IAAAA,eAAK,EAACD,SAAS,OAAOA;IAC5B;IACA,OAAOL;AACT"}

package/build/iter.d.ts

@@ -0,0 +1,61 @@
+import type { Option, Result } from './types.js';
+/**
+ * Yields mapped values while the mapping function returns Some, stops at the first None.
+ * @param source - The iterable to map over
+ * @param fn - Mapping function returning Some(value) to continue or None to stop
+ * @returns Generator of mapped values
+ * @example
+ * [...mapWhile([1, 2, 3, 4], n => n < 3 ? some(n * 10) : none)] // [10, 20]
+ */
+export declare function mapWhile<T, U>(source: Iterable<T>, fn: (value: T) => Option<U>): Generator<U>;
+/**
+ * Wraps an iterable so that each yielded value becomes Ok and any throw becomes a single Err.
+ * Stops after the first error - the source's internal state is unknown after an exception.
+ *
+ * Uses a manual iterator instead of a generator to avoid coroutine suspend/resume overhead.
+ *
+ * Follows the for-of IteratorClose spec:
+ * - iter.return() is never called on natural exhaustion or after a caught error
+ * - iter.return() is only called on early consumer exit (break/return)
+ * - Cleanup errors from iter.return() are suppressed
+ *
+ * @param source - The iterable to wrap
+ * @returns Iterable iterator of Result values
+ * @example
+ * [...safeIter([1, 2, 3])]       // [Ok(1), Ok(2), Ok(3)]
+ * [...safeIter(throwingIter())]   // [Ok(1), Err(error)]
+ */
+export declare function safeIter<T>(source: Iterable<T>): IterableIterator<Result<T, unknown>>;
+/**
+ * Collects an iterable of Results into a single Result containing an array.
+ * Short-circuits on the first Err.
+ * @param source - Iterable of Result values
+ * @returns Ok(values[]) if all Ok, or the first Err encountered
+ * @example
+ * tryCollect([ok(1), ok(2), ok(3)])   // Ok([1, 2, 3])
+ * tryCollect([ok(1), err('x')])       // Err('x')
+ */
+export declare function tryCollect<T, E>(source: Iterable<Result<T, E>>): Result<T[], E>;
+/**
+ * Folds an iterable with a fallible accumulator function.
+ * Short-circuits on the first Err returned by fn.
+ * @param source - The iterable to fold over
+ * @param init - Initial accumulator value
+ * @param fn - Folding function returning Ok(newAcc) or Err
+ * @returns Ok(finalAcc) if all steps succeed, or the first Err
+ * @example
+ * tryFold([1, 2, 3], 0, (acc, n) => ok(acc + n))   // Ok(6)
+ * tryFold([1, 2, 3], 0, (acc, n) => n === 2 ? err('stop') : ok(acc + n))  // Err('stop')
+ */
+export declare function tryFold<T, Acc, E>(source: Iterable<T>, init: Acc, fn: (acc: Acc, item: T) => Result<Acc, E>): Result<Acc, E>;
+/**
+ * Iterates over a source, calling a fallible function for each item.
+ * Short-circuits on the first Err returned by fn.
+ * @param source - The iterable to iterate over
+ * @param fn - Function to call for each item, returning Ok(void) or Err
+ * @returns Ok(void) if all calls succeed, or the first Err
+ * @example
+ * tryForEach([1, 2, 3], n => ok(console.log(n)))  // Ok(void), logs 1, 2, 3
+ * tryForEach([1, 2, 3], n => n === 2 ? err('stop') : ok(undefined))  // Err('stop')
+ */
+export declare function tryForEach<T, E>(source: Iterable<T>, fn: (item: T) => Result<void, E>): Result<void, E>;

package/build/iter.js

@@ -0,0 +1,78 @@
+import { isSome, isErr, err as ERR } from "./types.js";
+export function* mapWhile(source, fn) {
+    for (const item of source){
+        const mapped = fn(item);
+        if (!isSome(mapped)) return;
+        yield mapped;
+    }
+}
+export function safeIter(source) {
+    const iter = source[Symbol.iterator]();
+    let done = false;
+    return {
+        [Symbol.iterator] () {
+            return this;
+        },
+        next () {
+            if (done) return {
+                value: undefined,
+                done: true
+            };
+            try {
+                const next = iter.next();
+                if (next.done) {
+                    done = true;
+                    return next;
+                }
+                return {
+                    value: next.value,
+                    done: false
+                };
+            } catch (e) {
+                done = true;
+                return {
+                    value: ERR(e),
+                    done: false
+                };
+            }
+        },
+        return () {
+            if (!done) {
+                done = true;
+                try {
+                    iter.return?.();
+                } catch  {}
+            }
+            return {
+                value: undefined,
+                done: true
+            };
+        }
+    };
+}
+export function tryCollect(source) {
+    const collected = [];
+    for (const result of source){
+        if (isErr(result)) return result;
+        collected.push(result);
+    }
+    return collected;
+}
+export function tryFold(source, init, fn) {
+    let acc = init;
+    for (const item of source){
+        const result = fn(acc, item);
+        if (isErr(result)) return result;
+        acc = result;
+    }
+    return acc;
+}
+export function tryForEach(source, fn) {
+    for (const item of source){
+        const result = fn(item);
+        if (isErr(result)) return result;
+    }
+    return undefined;
+}
+
+//# sourceMappingURL=iter.js.map

package/build/iter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/iter.ts"],"sourcesContent":["import { isSome, isErr, err as ERR } from './types.js';\nimport type { Option, Result, Ok } from './types.js';\n\n/**\n * Yields mapped values while the mapping function returns Some, stops at the first None.\n * @param source - The iterable to map over\n * @param fn - Mapping function returning Some(value) to continue or None to stop\n * @returns Generator of mapped values\n * @example\n * [...mapWhile([1, 2, 3, 4], n => n < 3 ? some(n * 10) : none)] // [10, 20]\n */\nexport function* mapWhile<T, U>(source: Iterable<T>, fn: (value: T) => Option<U>): Generator<U> {\n  for (const item of source) {\n    const mapped = fn(item);\n    if (!isSome(mapped)) return;\n    yield mapped as U;\n  }\n}\n\n/**\n * Wraps an iterable so that each yielded value becomes Ok and any throw becomes a single Err.\n * Stops after the first error - the source's internal state is unknown after an exception.\n *\n * Uses a manual iterator instead of a generator to avoid coroutine suspend/resume overhead.\n *\n * Follows the for-of IteratorClose spec:\n * - iter.return() is never called on natural exhaustion or after a caught error\n * - iter.return() is only called on early consumer exit (break/return)\n * - Cleanup errors from iter.return() are suppressed\n *\n * @param source - The iterable to wrap\n * @returns Iterable iterator of Result values\n * @example\n * [...safeIter([1, 2, 3])]       // [Ok(1), Ok(2), Ok(3)]\n * [...safeIter(throwingIter())]   // [Ok(1), Err(error)]\n */\nexport function safeIter<T>(source: Iterable<T>): IterableIterator<Result<T, unknown>> {\n  const iter = source[Symbol.iterator]();\n  let done = false;\n  return {\n    [Symbol.iterator]() {\n      return this;\n    },\n    next(): IteratorResult<Result<T, unknown>> {\n      if (done) return { value: undefined, done: true };\n      try {\n        const next = iter.next();\n        if (next.done) {\n          done = true;\n          return next;\n        }\n        return { value: next.value as Ok<T>, done: false };\n      } catch (e) {\n        done = true;\n        return { value: ERR(e), done: false };\n      }\n    },\n    return(): IteratorResult<Result<T, unknown>> {\n      if (!done) {\n        done = true;\n        try {\n          iter.return?.();\n        } catch {\n          // suppressed\n        }\n      }\n      return { value: undefined, done: true };\n    },\n  };\n}\n\n// -- Result-oriented terminal operations --\n\n/**\n * Collects an iterable of Results into a single Result containing an array.\n * Short-circuits on the first Err.\n * @param source - Iterable of Result values\n * @returns Ok(values[]) if all Ok, or the first Err encountered\n * @example\n * tryCollect([ok(1), ok(2), ok(3)])   // Ok([1, 2, 3])\n * tryCollect([ok(1), err('x')])       // Err('x')\n */\nexport function tryCollect<T, E>(source: Iterable<Result<T, E>>): Result<T[], E> {\n  const collected: T[] = [];\n  for (const result of source) {\n    if (isErr(result)) return result;\n    collected.push(result as T);\n  }\n  return collected as Ok<T[]>;\n}\n\n/**\n * Folds an iterable with a fallible accumulator function.\n * Short-circuits on the first Err returned by fn.\n * @param source - The iterable to fold over\n * @param init - Initial accumulator value\n * @param fn - Folding function returning Ok(newAcc) or Err\n * @returns Ok(finalAcc) if all steps succeed, or the first Err\n * @example\n * tryFold([1, 2, 3], 0, (acc, n) => ok(acc + n))   // Ok(6)\n * tryFold([1, 2, 3], 0, (acc, n) => n === 2 ? err('stop') : ok(acc + n))  // Err('stop')\n */\nexport function tryFold<T, Acc, E>(source: Iterable<T>, init: Acc, fn: (acc: Acc, item: T) => Result<Acc, E>): Result<Acc, E> {\n  let acc = init;\n  for (const item of source) {\n    const result = fn(acc, item);\n    if (isErr(result)) return result;\n    acc = result as Acc;\n  }\n  return acc as Ok<Acc>;\n}\n\n/**\n * Iterates over a source, calling a fallible function for each item.\n * Short-circuits on the first Err returned by fn.\n * @param source - The iterable to iterate over\n * @param fn - Function to call for each item, returning Ok(void) or Err\n * @returns Ok(void) if all calls succeed, or the first Err\n * @example\n * tryForEach([1, 2, 3], n => ok(console.log(n)))  // Ok(void), logs 1, 2, 3\n * tryForEach([1, 2, 3], n => n === 2 ? err('stop') : ok(undefined))  // Err('stop')\n */\nexport function tryForEach<T, E>(source: Iterable<T>, fn: (item: T) => Result<void, E>): Result<void, E> {\n  for (const item of source) {\n    const result = fn(item);\n    if (isErr(result)) return result;\n  }\n  return undefined as Ok<void>;\n}\n"],"names":["isSome","isErr","err","ERR","mapWhile","source","fn","item","mapped","safeIter","iter","Symbol","iterator","done","next","value","undefined","e","return","tryCollect","collected","result","push","tryFold","init","acc","tryForEach"],"mappings":"AAAA,SAASA,MAAM,EAAEC,KAAK,EAAEC,OAAOC,GAAG,QAAQ,aAAa;AAWvD,OAAO,UAAUC,SAAeC,MAAmB,EAAEC,EAA2B;IAC9E,KAAK,MAAMC,QAAQF,OAAQ;QACzB,MAAMG,SAASF,GAAGC;QAClB,IAAI,CAACP,OAAOQ,SAAS;QACrB,MAAMA;IACR;AACF;AAmBA,OAAO,SAASC,SAAYJ,MAAmB;IAC7C,MAAMK,OAAOL,MAAM,CAACM,OAAOC,QAAQ,CAAC;IACpC,IAAIC,OAAO;IACX,OAAO;QACL,CAACF,OAAOC,QAAQ,CAAC;YACf,OAAO,IAAI;QACb;QACAE;YACE,IAAID,MAAM,OAAO;gBAAEE,OAAOC;gBAAWH,MAAM;YAAK;YAChD,IAAI;gBACF,MAAMC,OAAOJ,KAAKI,IAAI;gBACtB,IAAIA,KAAKD,IAAI,EAAE;oBACbA,OAAO;oBACP,OAAOC;gBACT;gBACA,OAAO;oBAAEC,OAAOD,KAAKC,KAAK;oBAAWF,MAAM;gBAAM;YACnD,EAAE,OAAOI,GAAG;gBACVJ,OAAO;gBACP,OAAO;oBAAEE,OAAOZ,IAAIc;oBAAIJ,MAAM;gBAAM;YACtC;QACF;QACAK;YACE,IAAI,CAACL,MAAM;gBACTA,OAAO;gBACP,IAAI;oBACFH,KAAKQ,MAAM;gBACb,EAAE,OAAM,CAER;YACF;YACA,OAAO;gBAAEH,OAAOC;gBAAWH,MAAM;YAAK;QACxC;IACF;AACF;AAaA,OAAO,SAASM,WAAiBd,MAA8B;IAC7D,MAAMe,YAAiB,EAAE;IACzB,KAAK,MAAMC,UAAUhB,OAAQ;QAC3B,IAAIJ,MAAMoB,SAAS,OAAOA;QAC1BD,UAAUE,IAAI,CAACD;IACjB;IACA,OAAOD;AACT;AAaA,OAAO,SAASG,QAAmBlB,MAAmB,EAAEmB,IAAS,EAAElB,EAAyC;IAC1G,IAAImB,MAAMD;IACV,KAAK,MAAMjB,QAAQF,OAAQ;QACzB,MAAMgB,SAASf,GAAGmB,KAAKlB;QACvB,IAAIN,MAAMoB,SAAS,OAAOA;QAC1BI,MAAMJ;IACR;IACA,OAAOI;AACT;AAYA,OAAO,SAASC,WAAiBrB,MAAmB,EAAEC,EAAgC;IACpF,KAAK,MAAMC,QAAQF,OAAQ;QACzB,MAAMgB,SAASf,GAAGC;QAClB,IAAIN,MAAMoB,SAAS,OAAOA;IAC5B;IACA,OAAOL;AACT"}