slang-ts 0.0.6 → 0.0.8

package/README.md

@@ -1,8 +1,8 @@
-# Slang
+# slang-ts
 
 Functional programming library for TypeScript.
 
-A collection of functional programming utilities and other cool programming stuff from other languages such as rust implemented in TypeScript.
+A collection of utilities and other cool programming stuff brought over from languages like Rust.
 
 ## Install
 
@@ -12,31 +12,43 @@ npm i slang-ts
 
 ## Implemented Utilities
 
+- [x] Option (Some, None)
+- [x] isFalsy (Option truthiness check)
 - [x] Result (Ok, Err)
-- [x] Maybe (Option)
-- [x] andThen
-- [x] Atom
 - [x] Expect
 - [x] Unwrap (on Option)
 - [x] Else (on unwrap)
-- [x] Panic
-- [x] Zip, Unzip, zipWith
-- [x] SafeTry
+- [x] andThen
 - [x] Match
 - [x] MatchAll
+- [x] Options (normalize mixed values)
+- [x] SafeTry
 - [x] Pipe
 - [x] To (converters, e.g. `userAtom.to('option')`)
+- [x] Atom
+- [x] Zip, Unzip, zipWith
+- [x] Panic
+- [x] println (environment-aware logging)
+- [x] setEnvironment (logging mode, custom logger)
+- [x] Signal (lifecycle trigger)
+- [x] SuperPromise (abort, reject, resolve, defer)
+- [x] SuperRunner (sequence, all, race)
+- [x] Channel (send, subscribe, when)
+- [x] scheduleMicrotask (internal scheduling helper)
 
-All utilities fully tested, See [tests](https://github.com/Hussseinkizz/slang/tree/main/tests)
+All utilities fully tested. See [tests](https://github.com/Hussseinkizz/slang/tree/main/tests)
 
-## Others (Planned)
+## New in v0.0.8
 
-- Pubsub store with state locks
-- Promises and async utilities
+- **Signal**: a simple on/off trigger that fires once and stays fired; use it to make something start only after something else finishes.
+- **println now respects the environment**: `setEnvironment("production")` (or `"prod"`) turns it into a no-op, so dev logging never reaches prod logs; short forms `dev`/`prod` accepted, and it appends a real newline. Pass `{ printFn }` to route println through an existing logger instead.
+- **SuperPromise**: native JavaScript promises plus wait, retry, time out, cancel, settling into `Ok`/`Err`; use it for any async operation that needs more than plain promise.
+- **SuperRunner**: `Promise.all` and `Promise.race` grown up: run several SuperPromises in order, in parallel, or take first to finish.
+- **Channel**: a simple event bus between parts of your app that don't need to know each other; use it to broadcast things like "user created" or "workflow completed" without wiring components together.
 
 ## How It Works
 
-You can import utilities individually or together:
+Import utilities individually or together:
 
 ```ts
 // Individual imports
@@ -52,18 +64,6 @@ import * as slang from "slang-ts";
 slang.println("Hello world!");
 ```
 
-### println
-
-Well there's nothing special to slang's println utility, its just who wants console.log, its not fun at all, so we instead println, clean and classic, but latter it can be made environment aware so it doesn't print in prod, but for now its just sugar for console.log.
-
-```ts
-import { println } from "slang-ts";
-
-const name = "kizz";
-println("name:", name);
-println("multiple", "args", "work", { too: true });
-```
-
 ### Option
 
 Wraps values that may or may not be present. Returns `Some<T>` for truthy values, `None` for null, undefined, empty strings, NaN, or Infinity. Note that `0` and `false` are truthy as these are usually intentional.
@@ -130,72 +130,6 @@ if (user.isOk) {
 }
 ```
 
-### Atom
-
-Creates unique, non-interned symbols with semantic descriptions. Each call produces a distinct identity. So ideally define them in one file and import from it everywhere else, great for env variables stuff.
-
-```ts
-import { atom } from "slang-ts";
-
-const userAtom = atom("kizz");
-const user2Atom = atom("kizz");
-
-println(userAtom === atom("kizz")); // false - non interned ✅
-println(userAtom.description);      // "kizz"
-
-if (userAtom === user2Atom) {
-  println("all the same");
-} else {
-  println("not the same");          // This prints!
-}
-```
-
-### Match
-
-Exhaustive pattern matching for `Option` and `Result` types. Forces you to handle all cases.
-
-```ts
-import { match } from "slang-ts";
-
-// Matching Results
-const result = divide(10, 0);
-match(result, {
-  Ok: (v) => println("Success:", v.value),
-  Err: (e) => println("Failed:", e.error),
-});
-
-// Matching Options
-const maybePort = option(process.env.PORT);
-match(maybePort, {
-  Some: (v) => println("Port:", v.value),
-  None: () => println("No port configured"),
-});
-```
-
-### MatchAll
-
-Pattern matching for primitives and atoms with required `_` fallback.
-
-```ts
-import { matchAll } from "slang-ts";
-
-// Match atoms
-const ready = atom("ready");
-matchAll(ready, {
-  ready: () => println("Ready!"),
-  failed: () => println("Failed!"),
-  _: () => println("Unknown"),
-});
-
-// Match booleans
-const isActive = true;
-matchAll(isActive, {
-  true: () => println("Active"),
-  false: () => println("Inactive"),
-  _: () => println("Unknown"),
-});
-```
-
 ### Expect
 
 Unwraps values or throws with custom message. Use when failure is unrecoverable.
@@ -224,21 +158,6 @@ println("Retries:", retries);
 // const nothing = option(null).unwrap();
 ```
 
-### To
-
-Converts between Slang types.
-
-```ts
-const statusAtom = atom("active").to("option");
-println("Option:", statusAtom);           // Some("active")
-
-const stateOption = option("ready").to("atom");
-println("Atom:", stateOption.description); // "ready"
-
-const errResult = option(null).to("result");
-println("Result:", errResult.type);        // "Err"
-```
-
 ### andThen
 
 Chainable transformation for `Option`, `Result`, and `Atom`. Transforms the inner value while preserving the wrapper type. Returns original instance if provided transformation function returns `undefined`.
@@ -283,6 +202,187 @@ atom("x").andThen(() => { throw "oops" });  // Panics!
 option(42).andThen(x => x.toString());      // Some("42")
 ```
 
+### Match
+
+Exhaustive pattern matching for `Option` and `Result` types. Forces you to handle all cases. Returns the value from the matched handler.
+
+```ts
+import { match } from "slang-ts";
+
+// Matching Results - returns handler result
+const result = divide(10, 0);
+const message = match(result, {
+  Ok: (v) => `Success: ${v.value}`,
+  Err: (e) => `Failed: ${e.error}`,
+});
+println(message); // "Failed: Cannot divide by zero"
+
+// Matching Options - returns handler result
+const maybePort = option(process.env.PORT);
+const port = match(maybePort, {
+  Some: (v) => parseInt(v.value),
+  None: () => 3000,
+});
+println("Using port:", port); // Uses parsed port or default 3000
+```
+
+### MatchAll
+
+Pattern matching for primitives and atoms with required `_` fallback. Returns the value from the matched handler.
+
+```ts
+import { matchAll } from "slang-ts";
+
+// Match atoms - returns handler result
+const ready = atom("ready");
+const status = matchAll(ready, {
+  ready: () => "System is ready",
+  failed: () => "System failed",
+  _: () => "Unknown state",
+});
+println(status); // "System is ready"
+
+// Match booleans - returns handler result
+const isActive = true;
+const label = matchAll(isActive, {
+  true: () => "Active",
+  false: () => "Inactive",
+  _: () => "Unknown",
+});
+println(label); // "Active"
+```
+
+### Options
+
+Normalizes heterogeneous values (raw values, `Option`s, and `Result`s) into a single `Result`. Returns the first usable value as `Ok`, or the provided `Err` fallback if none is usable. A value is usable when its unwrapped inner value is truthy; `None`, `Err`, null, undefined, empty strings, NaN, and Infinity are skipped (note `0` and `false` are usable, matching `option()` semantics).
+
+```ts
+import { Options, option, Ok, Err } from "slang-ts";
+
+// First usable value wins
+let a = null;
+let b = option(undefined);
+let c = Ok(true);
+let d = Err("nope!");
+
+const something = Options([a, b, c, d], Err("No value!"));
+// Ok(true) - c is usable
+
+// Nothing usable -> fallback
+let e = option(null);
+const nothing = Options([a, b, e, d], Err("No value!"));
+// Err("No value!")
+
+// Raw (non-wrapped) values work too, just like a single option():
+Options([null, undefined, "hello"]);          // Ok("hello") - raw truthy wins
+Options(["", 0, "zero is skipped, 0 used"]);  // Ok("...") - skips "" first
+Options([null, undefined, ""]);               // Err("No value!") - all raw falsy
+```
+
+Useful when values come from different functions with inconsistent return types and all you care about is whether the end result is usable.
+
+### SafeTry
+
+Wraps potentially throwing functions in try-catch, returning a `Result<T, string>`. Always needs to be awaited as its async.
+
+```ts
+import { safeTry } from "slang-ts";
+
+const result = await safeTry(() => {
+  if (denom === 0) throw new Error("Cannot divide by zero");
+  return num / denom;
+});
+
+if (result.isOk) {
+  println("Result:", result.value);
+} else {
+  println("Error:", result.error);
+}
+
+// Async functions work the same way
+const data = await safeTry(async () => {
+  const res = await fetch("/api/user");
+  return res.json();
+});
+
+if (data.isOk) {
+  println("User:", data.value);
+}
+
+// Re-throw critical errors instead of capturing
+await safeTry(() => {
+  throw new Error("Critical!");
+}, { throw: true });
+```
+
+### Pipe
+
+Sequential function composition where each function receives a `Result` and returns a `Result`. Accepts plain values, Option, Result, or Atom as initial input.
+
+```ts
+import { pipe, Ok, Err, option, type Result } from "slang-ts";
+
+// Create pipeline functions
+const add = (x: number) => (res: Result<number, string>) =>
+  res.isOk ? Ok(res.value + x) : res;
+
+const multiply = (x: number) => (res: Result<number, string>) =>
+  res.isOk ? Ok(res.value * x) : res;
+
+// Basic usage
+const result = await pipe(5, add(3), multiply(2)).run();
+println("Result:", result.value); // 16
+
+// With Options as initial value
+const fromOption = await pipe(option(10), add(5)).run();
+println("From option:", fromOption.value); // 15
+
+// With callbacks and error handling
+const result = await pipe(5, add(3), multiply(2)).run({
+  onEach: ({ currentFn, prevResult }) => {
+    println("Executed:", currentFn);
+  },
+  onSuccess: (value) => println("Done:", value),
+  onError: (err) => println("Failed:", err.message),
+  allowErrors: false, // stops pipeline on first Err
+});
+```
+
+### To
+
+Converts between Slang types.
+
+```ts
+const statusAtom = atom("active").to("option");
+println("Option:", statusAtom);           // Some("active")
+
+const stateOption = option("ready").to("atom");
+println("Atom:", stateOption.description); // "ready"
+
+const errResult = option(null).to("result");
+println("Result:", errResult.type);        // "Err"
+```
+
+### Atom
+
+Creates unique, non-interned symbols with semantic descriptions. Each call produces a distinct identity. Define them in one file and import from it everywhere else, handy for env-var style constants.
+
+```ts
+import { atom } from "slang-ts";
+
+const userAtom = atom("kizz");
+const user2Atom = atom("kizz");
+
+println(userAtom === atom("kizz")); // false - non interned
+println(userAtom.description);      // "kizz"
+
+if (userAtom === user2Atom) {
+  println("all the same");
+} else {
+  println("not the same");          // This prints!
+}
+```
+
 ### Zip
 
 Combines multiple collections element-wise into tuples.
@@ -344,91 +444,198 @@ println(unzip(zipped));
 // [[1, 2, 3], [4, 5, 6]]
 ```
 
-### Pipe
+### Panic
 
-Sequential function composition where each function receives a `Result` and returns a `Result`. Accepts plain values, Option, Result, or Atom as initial input.
+Throws an error immediately. Use for unrecoverable failures.
 
 ```ts
-import { pipe, Ok, Err, option, type Result } from "slang-ts";
+import { panic } from "slang-ts";
 
-// Create pipeline functions
-const add = (x: number) => (res: Result<number, string>) =>
-  res.isOk ? Ok(res.value + x) : res;
+function processUser(user: User | null) {
+  if (!user) panic("User cannot be null");
+  return user.name;
+}
 
-const multiply = (x: number) => (res: Result<number, string>) =>
-  res.isOk ? Ok(res.value * x) : res;
+// Guard clause pattern
+const config = loadConfig();
+if (!config.apiKey) panic("API key required");
+```
 
-// Basic usage
-const result = await pipe(5, add(3), multiply(2)).run();
-println("Result:", result.value); // 16
+### println
 
-// With Options as initial value
-const fromOption = await pipe(option(10), add(5)).run();
-println("From option:", fromOption.value); // 15
+console.log sugar that stays out of production. Prints a line (args joined, newline appended) and does nothing once `setEnvironment` puts the app in production mode. Dev chatter never leaks to prod logs. Already have an advanced logger? Hand it to `setEnvironment({ printFn })` and every println routes through it: your logging code stays exactly as it is, in every mode.
 
-// With callbacks and error handling
-const result = await pipe(5, add(3), multiply(2)).run({
-  onEach: ({ currentFn, prevResult }) => {
-    println("Executed:", currentFn);
-  },
-  onSuccess: (value) => println("Done:", value),
-  onError: (err) => println("Failed:", err.message),
-  allowErrors: false, // stops pipeline on first Err
-});
+```ts
+import { println, setEnvironment } from "slang-ts";
+
+setEnvironment("development"); // "dev" works too (default)
+println("name:", name);
+println("multiple", "args", "work", { too: true });
+
+setEnvironment("production"); // "prod" works too
+println("not printed in prod");
+
+// Route println through an existing logger instead, even in prod
+import { appLogger } from "./logger";
+setEnvironment({ printFn: (line) => appLogger.info(line.trimEnd()) });
 ```
 
-### SafeTry
+### Signal
 
-Wraps potentially throwing functions in try-catch, returning a `Result<T, string>`. Always needs to be awaited as its async.
+A trigger (we call them signals) is a switch that fires once and stays fired. Flip it when you're ready, and anything waiting on it reacts. They're interchangeable with the platform's `AbortSignal`, so a signal you create can be handed to anything that already accepts one.
 
 ```ts
-import { safeTry } from "slang-ts";
+import { createSignal } from "slang-ts";
 
-const result = await safeTry(() => {
-  if (denom === 0) throw new Error("Cannot divide by zero");
-  return num / denom;
+const ready = createSignal();
+
+ready.addEventListener("abort", () => println("ready!")); // fires when the trigger goes off
+ready.fire();                                             // flip it
+```
+
+The useful part: gate work on a signal, or publish events when a lifecycle completes.
+
+```ts
+const task = superPromise(loadUser, { defer: ready }); // starts only once ready fires
+
+channel.when({
+  signal: task.done,   // task finished, success or not
+  topic: "user.loaded",
+  data: { id: userId },
 });
+```
+
+### SuperPromise
+
+Native JavaScript promises plus execution controls: wait before starting, retry when it fails, time out when it hangs, cancel from outside, `done` trigger to wire into other things. Tasks settle into `Ok` or `Err`: just check outcome, no try/catch around awaits. Library exports no short alias: alias locally when the name gets heavy: `import { superPromise as sp }`.
+
+```ts
+import { superPromise } from "slang-ts";
+
+// A fetch that gives up after 5 seconds and tries up to 3 more times
+const result = await superPromise(
+  (signal) => fetch("/api/user", { signal }),
+  { timeout: 5000, retry: 3 }
+);
 
 if (result.isOk) {
-  println("Result:", result.value);
+  println("User:", result.value);
 } else {
-  println("Error:", result.error);
+  println("Failed:", result.error);
 }
+```
 
-// Async functions work the same way
-const data = await safeTry(async () => {
-  const res = await fetch("/api/user");
-  return res.json();
+No `await` handy? Chain with `.then`; the callback receives the same `Result`:
+
+```ts
+superPromise(loadUser, { timeout: 5000 }).then((result) => {
+  if (result.isOk) {
+    println("User:", result.value);
+  } else {
+    println("Failed:", result.error);
+  }
 });
+```
 
-if (data.isOk) {
-  println("User:", data.value);
-}
+Need it to wait for something else first? `defer` holds execution until a signal fires; chain operations so the next starts only when the previous is done:
 
-// Re-throw critical errors instead of capturing
-await safeTry(() => {
-  throw new Error("Critical!");
-}, { throw: true });
+```ts
+const config = superPromise(loadConfig);
+const user = superPromise(loadUser, { defer: config.done });
+
+const result = await user; // config runs first, then user
 ```
 
-### Panic
+Cancel from outside, or keep retrying until you call it off:
 
-Throws an error immediately. Use for unrecoverable failures.
+```ts
+task.abort();                                  // cancel; you get Err("Aborted")
+superPromise(fetchData, {
+  retryUntil: { signal: stopSignal, delay: 2000 }, // keep trying until stopSignal fires
+});
+```
+
+One gotcha worth knowing: a task doesn't start until you consume it (`await`, `.then()`, or a runner's `start()`), so you can wire up dependencies first and they'll run in the right order when awaited.
+
+Also handy:
 
 ```ts
-import { panic } from "slang-ts";
+const manual = superPromise<number>();  // no executor; settle it yourself
+manual.resolve(100);                    // or manual.reject(error)
 
-function processUser(user: User | null) {
-  if (!user) panic("User cannot be null");
-  return user.name;
-}
+await superPromise(loadUser).tap((user) => println(user.name)); // observe without changing
+```
 
-// Guard clause pattern
-const config = loadConfig();
-if (!config.apiKey) panic("API key required");
+### SuperRunner
+
+Same idea as `Promise.all`, `Promise.race`, and plain `await` chain, but for SuperPromises, with cancellation and clean `Result` outcomes. Use it when multiple operations are needed: run several in order, in parallel, or take first to finish. Call `start()` once and read result; calling again just hands back same result without re-running anything.
+
+```ts
+import { superRunner, superPromise as sp } from "slang-ts";
+
+// In order: steps that depend on each other; stops at the first failure
+const auth = superRunner({
+  type: "sequence",
+  runners: [sp(authenticate), sp(loadProfile), sp(loadDashboard)],
+});
+const ordered = await auth.start(); // [authResult, profileResult, dashboardResult]
+
+// In parallel: all kicked off at once; result keyed by name
+const parallel = superRunner({
+  type: "all",
+  runners: {
+    user: sp(getUser),
+    posts: sp(getPosts),
+    settings: sp(getSettings),
+  },
+});
+const combined = await parallel.start(); // { user, posts, settings }
+
+// First to finish: take whichever source responds first, cancel the rest
+const first = superRunner({
+  type: "race",
+  count: 1,
+  runners: {
+    primary: sp(fetchPrimary),
+    backup: sp(fetchBackup),
+    cache: sp(fetchCache),
+  },
+});
+const winner = await first.start(); // { cache: ... } or whichever won
+```
+
+Cancel everything with one call:
+
+```ts
+workflow.abort(); // cancels all active children
+```
+
+### Channel
+
+Channel lets parts of your app that don't know each other talk: one side publishes, another listens, no wiring between them.
+
+```ts
+import { createChannel } from "slang-ts";
+
+const channel = createChannel();
+
+const unsubscribe = channel.subscribe({ topic: "user.created" }, (event) => {
+  println("Created:", event.data);
+});
+
+channel.send({ topic: "user.created", data: user });
+unsubscribe(); // stop listening
 ```
 
-And more are to be implemented in coming versions...
+Publish when a trigger goes off, a task finishing, anything at all:
+
+```ts
+channel.when({
+  signal: workflow.done,
+  topic: "workflow.completed",
+  data: { workflowId },
+});
+```
 
 ## Code Samples
 
@@ -436,4 +643,4 @@ See [example.ts](https://github.com/Hussseinkizz/slang/blob/main/example.ts) for
 
 ## Contributing
 
-Contributions are welcome, I know there a lot of cool things out there we can bring in.
+Contributions are welcome. I know there are a lot of cool things out there we can bring in.

package/dist/index.js

@@ -1 +1,2 @@
-var q=(G)=>{let B=globalThis?.queueMicrotask;if(typeof B==="function")B(G);else Promise.resolve().then(G)},P=(G)=>G!=null&&typeof G==="object"&&("type"in G)&&(G.type==="Ok"||G.type==="Err"),M=(G)=>G!=null&&typeof G==="object"&&("isSome"in G)&&("isNone"in G),O=(G)=>G!=null&&typeof G==="object"&&typeof G.valueOf?.()==="symbol";function N(G){if(O(G))return{ok:!0,value:G.valueOf().description};if(P(G)){if(G.isOk)return{ok:!0,value:G.value};return{ok:!1,error:typeof G.error==="string"?G.error:String(G.error)}}if(M(G)){if(G.isSome)return{ok:!0,value:G.value};return{ok:!1,error:"Option was None"}}return{ok:!0,value:G}}var R=(...G)=>{globalThis?.console?.log?.(...G)};function Z(G){throw Error(G)}function L(G){let B=Object.freeze({type:"Ok",value:G,isOk:!0,isErr:!1}),Y={...B,expect:(D)=>B.value,unwrap:()=>{let D=!1;return q(()=>{}),{else(X){return D=!0,B.value}}},andThen:(D)=>{try{let X=D(B.value);if(X instanceof Promise)return X.then(($)=>{if($===void 0)return Y;return L($)}).catch(($)=>{let J=$ instanceof Error?$.message:String($);return I(J)});if(X===void 0)return Y;return L(X)}catch(X){let $=X instanceof Error?X.message:String(X);return I($)}}};return Y}function I(G){let Y={...Object.freeze({type:"Err",error:G,isOk:!1,isErr:!0}),expect:(D)=>{throw Error(D??G)},unwrap:()=>{let D=!1;return q(()=>{if(!D)throw Error(G)}),{else(X){if(D=!0,typeof X==="function")return X(G);return X}}},andThen:(D)=>{return Y}};return Y}var K=(G)=>{return G===null||G===void 0||G===""||Number.isNaN(G)||G===1/0||G===-1/0};function b(G){if(K(G))throw Error("Cannot wrap null, undefined, NaN, or empty string in Some");return Object.freeze({type:"Some",value:G,isSome:!0,isNone:!1})}var g=Object.freeze({type:"None",isSome:!1,isNone:!0}),S=null;function A(G){S=G}function W(G){let B=K(G)?g:b(G),$={...B,to:(J)=>{if(!S)throw Error("Converter not initialized");return S(B,J)},expect:(J)=>{if(B.isSome)return B.value;throw Error(J??"Expected Some, got None")},unwrap:()=>{let J=!1,C=B;return q(()=>{if(!J)throw Error("Expected else")}),{else(j){if(J=!0,C.isSome)return C.value;let H=typeof j==="function"?j(void 0):j;if(K(H))throw Error("Fallback must be truthy");return H}}},andThen:(J)=>{let C=B;if(C.isNone)return $;let j=C.value;try{let H=J(j);if(H instanceof Promise)return H.then((x)=>{if(x===void 0)return $;return W(x)}).catch(()=>W(null));if(H===void 0)return $;return W(H)}catch{return W(null)}}};return $}var T=null;function F(G){T=G}function U(G){let B=Symbol(G),Q=Object(B),Y=(X)=>{if(!T)throw Error("Converter not initialized");return T(B,X)},D=(X)=>{let $;try{$=X(G)}catch(J){let C=J instanceof Error?J.message:String(J);Z(`Atom.andThen: fn threw an error: ${C}`)}if($===void 0)return Q;if(typeof $!=="string")Z(`Atom.andThen: fn must return a string, got ${typeof $}`);return U($)};return Q.to=Y,Q.andThen=D,Q}var V=(G)=>G!=null&&typeof G==="object"&&("isSome"in G)&&("isNone"in G);function _(G,B){if(G&&(G.type==="Ok"||G.type==="Err"))throw Error("Cannot convert a Result to any other type");switch(B){case"option":{if(V(G))return G;if(typeof G==="symbol")return W(G.description);return W(G)}case"atom":{if(V(G)){if(G.isNone)throw Error("Cannot convert None to Atom");if(typeof G.value!=="string")throw Error("Only string values can be converted to Atom");return U(G.value)}if(typeof G==="symbol")return G;throw Error(`Cannot convert type ${typeof G} to Atom`)}case"result":{if(V(G))return G.isSome?L(G.value):I("Value is None");if(typeof G==="symbol")return L(G.description);return L(G)}default:throw Error(`Invalid target: ${B}`)}}A(_);F(_);function w(G,B){let Q=B[G.type];if(!Q)throw Error(`Non-exhaustive match — missing handler for '${G.type}'`);return Q(G)}var k=(G)=>{return typeof G==="string"||typeof G==="number"||typeof G==="boolean"||typeof G==="symbol"};function y(G,B){let Q=(J)=>typeof J?.valueOf==="function"?J.valueOf():J,Y=(J)=>typeof J==="symbol"?J.description:void 0,D=Q(G);if(!k(D))throw Error(`Unsupported match all value type: ${typeof D}`);let X=Y(D)??D,$=typeof X==="boolean"||typeof X==="number"?String(X):X;if($!=null&&$ in B)return B[$](G);return B._()}function h(G,B=!1){if(!B&&!Array.isArray(G))throw Error("Only arrays allowed when includeValues=false");if(Array.isArray(G))return G;if(G instanceof Set)return Array.from(G);return Object.values(G)}function z(G,B){let{fillValue:Q,includeValues:Y=!1}=B||{};if(G.length===0)return[];let D=G.map((j)=>h(j,Y)),X=Math.max(...D.map((j)=>j.length)),$=Math.min(...D.map((j)=>j.length)),J=Q===void 0?$:X,C=[];for(let j=0;j<J;j++)C.push(D.map((H)=>j<H.length?H[j]:Q));return C}function m(G,B,Q){return z(G,Q).map(B)}function f(G){if(G.length===0)return[];let B=G[0]?.length??0,Q=Array.from({length:B},()=>[]);for(let Y of G)Y.forEach((D,X)=>Q[X]?.push(D));return Q}async function c(G,B){let Q=B?.throw??!1;try{let Y=await G(),D=N(Y);if(D.ok)return L(D.value);return I(D.error)}catch(Y){let D=Y instanceof Error?Y.message:String(Y);if(Q)throw Y instanceof Error?Y:Error(D);return I(D)}}function E(G){return G.error??"Unknown error"}function d(G){let B=N(G);if(B.ok)return L(B.value);return I(B.error)}async function p(G,B){try{let Q=await G(B);if(!P(Q))return I("Pipeline function must return a Result");return Q}catch(Q){let Y=Q instanceof Error?Q.message:String(Q);return I(Y)}}function v(G,...B){return{async run(Q){let{onEach:Y,onSuccess:D,onError:X,allowErrors:$=!1}=Q??{},J=d(G);for(let C=0;C<B.length;C++){let j=B[C],H=B[C+1];if(J.isErr&&!$)return X?.(Error(E(J))),J;J=await p(j,J),Y?.({prevResult:J,currentFn:j.name||`fn${C+1}`,nextFn:H?H.name||`fn${C+2}`:void 0})}if(J.isOk)D?.(J.value);else X?.(Error(E(J)));return J}}}export{m as zipWith,z as zip,f as unzip,q as scheduleMicrotask,c as safeTry,R as println,v as pipe,Z as panic,W as option,y as matchAll,w as match,K as isFalsy,U as atom,_ as _to,L as Ok,I as Err};
+var R=(G)=>{let B=globalThis?.queueMicrotask;if(typeof B==="function")B(G);else Promise.resolve().then(G)},h=(G)=>G!=null&&typeof G==="object"&&("type"in G)&&(G.type==="Ok"||G.type==="Err"),O=Symbol("slang.activate"),r=(G)=>G!=null&&typeof G==="object"&&("isSome"in G)&&("isNone"in G),e=(G)=>G!=null&&typeof G==="object"&&typeof G.valueOf?.()==="symbol";function x(G){if(e(G))return{ok:!0,value:G.valueOf().description};if(h(G)){if(G.isOk)return{ok:!0,value:G.value};return{ok:!1,error:typeof G.error==="string"?G.error:String(G.error)}}if(r(G)){if(G.isSome)return{ok:!0,value:G.value};return{ok:!1,error:"Option was None"}}return{ok:!0,value:G}}var v="development",m=null,GG=(G)=>{if(typeof G==="object"&&G!==null){m=G.printFn??null;return}v=G==="production"||G==="prod"?"production":"development"},BG=(G)=>{if(typeof G==="string")return G;if(typeof G==="symbol")return String(G);if(typeof G==="function")return`[Function ${G.name}]`;try{return String(G)}catch{try{return JSON.stringify(G)??"null"}catch{return Object.prototype.toString.call(G)}}},g=(...G)=>{let B=G.map(BG).join(" ").concat(`
+`);if(m){m(B);return}if(v==="production")return;globalThis.console?.log?.(B)};function E(G){throw Error(G)}function L(G){let B=Object.freeze({type:"Ok",value:G,isOk:!0,isErr:!1}),D={...B,expect:(X)=>B.value,unwrap:()=>{let X=!1;return R(()=>{}),{else(Z){return X=!0,B.value}}},andThen:(X)=>{try{let Z=X(B.value);if(Z instanceof Promise)return Z.then((q)=>{if(q===void 0)return D;return L(q)}).catch((q)=>{let Y=q instanceof Error?q.message:String(q);return $(Y)});if(Z===void 0)return D;return L(Z)}catch(Z){let q=Z instanceof Error?Z.message:String(Z);return $(q)}}};return D}function $(G){let D={...Object.freeze({type:"Err",error:G,isOk:!1,isErr:!0}),expect:(X)=>{throw Error(X??G)},unwrap:()=>{let X=!1;return R(()=>{if(!X)throw Error(G)}),{else(Z){if(X=!0,typeof Z==="function")return Z(G);return Z}}},andThen:(X)=>{return D}};return D}var z=(G)=>{return G===null||G===void 0||G===""||Number.isNaN(G)||G===1/0||G===-1/0};function JG(G){if(z(G))throw Error("Cannot wrap null, undefined, NaN, or empty string in Some");return Object.freeze({type:"Some",value:G,isSome:!0,isNone:!1})}var QG=Object.freeze({type:"None",isSome:!1,isNone:!0}),f=null;function u(G){f=G}function T(G){let B=z(G)?QG:JG(G),q={...B,to:(Y)=>{if(!f)throw Error("Converter not initialized");return f(B,Y)},expect:(Y)=>{if(B.isSome)return B.value;throw Error(Y??"Expected Some, got None")},unwrap:()=>{let Y=!1,Q=B;return R(()=>{if(!Y)throw Error("Expected else")}),{else(K){if(Y=!0,Q.isSome)return Q.value;let I=typeof K==="function"?K(void 0):K;if(z(I))throw Error("Fallback must be truthy");return I}}},andThen:(Y)=>{let Q=B;if(Q.isNone)return q;let K=Q.value;try{let I=Y(K);if(I instanceof Promise)return I.then((M)=>{if(M===void 0)return q;return T(M)}).catch(()=>T(null));if(I===void 0)return q;return T(I)}catch{return T(null)}}};return q}var i=(G)=>{if(typeof G!=="object"||G===null)return G;let B=G;if(B.isSome===!0||B.isOk===!0)return B.value;return G},XG=(G)=>{if(typeof G==="object"&&G!==null){let B=G;if(B.isNone===!0||B.isErr===!0)return!0}return z(i(G))};function YG(G,B=$("No value!")){for(let J of G){if(XG(J))continue;return L(i(J))}return B}var d=null;function s(G){d=G}function b(G){let B=Symbol(G),J=Object(B),D=(Z)=>{if(!d)throw Error("Converter not initialized");return d(B,Z)},X=(Z)=>{let q;try{q=Z(G)}catch(Y){let Q=Y instanceof Error?Y.message:String(Y);E(`Atom.andThen: fn threw an error: ${Q}`)}if(q===void 0)return J;if(typeof q!=="string")E(`Atom.andThen: fn must return a string, got ${typeof q}`);return b(q)};return J.to=D,J.andThen=X,J}var c=(G)=>G!=null&&typeof G==="object"&&("isSome"in G)&&("isNone"in G);function p(G,B){if(G&&(G.type==="Ok"||G.type==="Err"))throw Error("Cannot convert a Result to any other type");switch(B){case"option":{if(c(G))return G;if(typeof G==="symbol")return T(G.description);return T(G)}case"atom":{if(c(G)){if(G.isNone)throw Error("Cannot convert None to Atom");if(typeof G.value!=="string")throw Error("Only string values can be converted to Atom");return b(G.value)}if(typeof G==="symbol")return G;throw Error(`Cannot convert type ${typeof G} to Atom`)}case"result":{if(c(G))return G.isSome?L(G.value):$("Value is None");if(typeof G==="symbol")return L(G.description);return L(G)}default:throw Error(`Invalid target: ${B}`)}}u(p);s(p);function $G(G,B){let J=B[G.type];if(!J)throw Error(`Non-exhaustive match — missing handler for '${G.type}'`);return J(G)}var ZG=(G)=>{return typeof G==="string"||typeof G==="number"||typeof G==="boolean"||typeof G==="symbol"};function qG(G,B){let J=(Y)=>typeof Y?.valueOf==="function"?Y.valueOf():Y,D=(Y)=>typeof Y==="symbol"?Y.description:void 0,X=J(G);if(!ZG(X))throw Error(`Unsupported match all value type: ${typeof X}`);let Z=D(X)??X,q=typeof Z==="boolean"||typeof Z==="number"?String(Z):Z;if(q!=null&&q in B)return B[q](G);return B._()}function DG(G,B=!1){if(!B&&!Array.isArray(G))throw Error("Only arrays allowed when includeValues=false");if(Array.isArray(G))return G;if(G instanceof Set)return Array.from(G);return Object.values(G)}function o(G,B){let{fillValue:J,includeValues:D=!1}=B||{};if(G.length===0)return[];let X=G.map((K)=>DG(K,D)),Z=Math.max(...X.map((K)=>K.length)),q=Math.min(...X.map((K)=>K.length)),Y=J===void 0?q:Z,Q=[];for(let K=0;K<Y;K++)Q.push(X.map((I)=>K<I.length?I[K]:J));return Q}function WG(G,B,J){return o(G,J).map(B)}function HG(G){if(G.length===0)return[];let B=G[0]?.length??0,J=Array.from({length:B},()=>[]);for(let D of G)D.forEach((X,Z)=>J[Z]?.push(X));return J}async function jG(G,B){let J=B?.throw??!1;try{let D=await G(),X=x(D);if(X.ok)return L(X.value);return $(X.error)}catch(D){let X=D instanceof Error?D.message:String(D);if(J)throw D instanceof Error?D:Error(X);return $(X)}}function n(G){return G.error??"Unknown error"}function KG(G){let B=x(G);if(B.ok)return L(B.value);return $(B.error)}async function LG(G,B){try{let J=await G(B);if(!h(J))return $("Pipeline function must return a Result");return J}catch(J){let D=J instanceof Error?J.message:String(J);return $(D)}}function IG(G,...B){return{async run(J){let{onEach:D,onSuccess:X,onError:Z,allowErrors:q=!1}=J??{},Y=KG(G);for(let Q=0;Q<B.length;Q++){let K=B[Q],I=B[Q+1];if(Y.isErr&&!q)return Z?.(Error(n(Y))),Y;Y=await LG(K,Y),D?.({prevResult:Y,currentFn:K.name||`fn${Q+1}`,nextFn:I?I.name||`fn${Q+2}`:void 0})}if(Y.isOk)X?.(Y.value);else Z?.(Error(n(Y)));return Y}}}function w(){let G=new AbortController;return Object.assign(G.signal,{fire:()=>G.abort()})}var l=(G)=>G instanceof Error?G.message:String(G),a=(G,B)=>{if(G.aborted)return B.abort(),()=>{};let J=()=>B.abort();return G.addEventListener("abort",J,{once:!0}),()=>G.removeEventListener("abort",J)};function t(G,B={}){let J=new AbortController,D=w(),X=()=>{},Z=new Promise((W)=>{X=W}),q=!1,Y=!1,Q=(W)=>{if(Y)return;Y=!0,X(W),D.fire()},K=async(W,H,j)=>{let U=!1,N,S=j!==void 0?a(j,H):()=>{},F=a(J.signal,H);if(B.timeout!==void 0)N=setTimeout(()=>{U=!0,H.abort()},B.timeout);let P=(V)=>{if(N!==void 0)clearTimeout(N);return S(),F(),V};try{let V=await W(H.signal),_=x(V);if(H.signal.aborted){if(J.signal.aborted)return P({kind:"aborted"});if(j?.aborted)return P({kind:"stopped"});return P(U?{kind:"timedOut"}:{kind:"aborted"})}if(!_.ok)return P({kind:"error",error:_.error});return P({kind:"value",value:_.value})}catch(V){if(J.signal.aborted)return P({kind:"aborted"});if(j?.aborted)return P({kind:"stopped"});if(H.signal.aborted)return P(U?{kind:"timedOut"}:{kind:"aborted"});return P({kind:"error",error:l(V)})}},I=(W)=>new Promise((H)=>{if(W.aborted){H();return}W[O]?.();let j=()=>{U(),H()},U=()=>{W.removeEventListener("abort",j),J.signal.removeEventListener("abort",j)};W.addEventListener("abort",j,{once:!0}),J.signal.addEventListener("abort",j,{once:!0})}),M=(W)=>new Promise((H)=>{if(J.signal.aborted){H();return}let j=()=>{clearTimeout(N),U(),H()},U=()=>J.signal.removeEventListener("abort",j),N=setTimeout(j,W);J.signal.addEventListener("abort",j,{once:!0})}),k=async()=>{let{defer:W,delay:H,retry:j,retryUntil:U}=B,N=G;if(N===void 0)return;if(J.signal.aborted)return Q($("Aborted"));if(W!==void 0){if(await I(W),J.signal.aborted)return Q($("Aborted"))}if(U!==void 0){let P=U.signal;for(;;){if(J.signal.aborted)return Q($("Aborted"));if(P.aborted)return Q($("Stopped"));let V=new AbortController,_=await K(N,V,P);switch(_.kind){case"value":return Q(L(_.value));case"aborted":return Q($("Aborted"));case"stopped":return Q($("Stopped"));case"timedOut":case"error":{if(J.signal.aborted)return Q($("Aborted"));if(P.aborted)return Q($("Stopped"));if(U.delay!==void 0)await M(U.delay)}}}}if(j!==void 0&&j>0){let P=j;for(;;){if(J.signal.aborted)return Q($("Aborted"));if(H!==void 0)await M(H);if(J.signal.aborted)return Q($("Aborted"));let V=new AbortController,_=await K(N,V,void 0);switch(_.kind){case"value":return Q(L(_.value));case"aborted":return Q($("Aborted"));case"timedOut":return Q($("Timed out"));case"stopped":return Q($("Stopped"));case"error":if(P>0){P-=1;continue}return Q($(_.error))}}}if(H!==void 0)await M(H);if(J.signal.aborted)return Q($("Aborted"));let S=new AbortController,F=await K(N,S,void 0);switch(F.kind){case"value":return Q(L(F.value));case"aborted":return Q($("Aborted"));case"timedOut":return Q($("Timed out"));case"stopped":return Q($("Stopped"));case"error":return Q($(F.error))}},A=()=>{if(q)return;if(q=!0,G===void 0)return;k()};D[O]=A;let C={done:D,abort:()=>{J.abort(),Q($("Aborted"))},resolve:(W)=>Q(L(W)),reject:(W)=>Q($(l(W))),tap:(W)=>t(async()=>{let H=await C;if(H.isOk)await W(H.value);return H}),then:(W,H)=>{return A(),Z.then(W,H)},catch:(W)=>{return A(),Z.catch(W)},finally:(W)=>{return A(),Z.finally(W)}};return C}function PG(G){let{type:B}=G;if(B==="race"&&G.count<1)throw Error("superRunner race count must be at least 1");let J=new AbortController,D=w(),X=()=>{},Z=new Promise((C)=>{X=C}),q=!1,Y=!1,Q=(C)=>{if(Y)return;Y=!0,X(C),D.fire()},K=B==="sequence"?G.runners:Object.values(G.runners),I=()=>{for(let C of K)C.abort()},M=async(C)=>{let W=[];for(let H of C){if(J.signal.aborted)return Q($("Aborted"));let j=await H;if(J.signal.aborted)return Q($("Aborted"));if(j.isErr)return Q($(j.error));W.push(j.value)}Q(L(W))},k=async(C)=>{let W=Object.entries(C),H={},j=0;for(let[U,N]of W)N.then((S)=>{if(j+=1,S.isOk)H[U]=S.value;else if(!J.signal.aborted&&!Y){I(),Q($(S.error));return}if(j===W.length)Q(L(H))});if(W.length===0)Q(L(H))},A=async(C,W)=>{let H=Object.entries(C),j={},U=0,N=0;for(let[S,F]of H)F.then((P)=>{if(N+=1,P.isOk){if(j[S]=P.value,U+=1,U>=W){I(),Q(L(j));return}}if(N===H.length)Q($(U===0?"All runners failed":"Not enough runners succeeded"))});if(H.length===0)Q($("All runners failed"))},y=()=>{if(!q)if(q=!0,B==="sequence")M(G.runners);else if(B==="all")k(G.runners);else A(G.runners,G.count);return Z};return D[O]=y,{done:D,start:y,abort:()=>{J.abort(),I(),Q($("Aborted"))}}}function UG(){let G=new Map,B=(X)=>{let Z=G.get(X.topic);if(Z===void 0)return;for(let q of Z)try{q(X)}catch(Y){g("channel subscriber threw:",Y)}};return{send:B,subscribe:(X,Z)=>{let q=G.get(X.topic);if(q===void 0)q=new Set,G.set(X.topic,q);return q.add(Z),()=>{let Y=G.get(X.topic);if(Y!==void 0)Y.delete(Z)}},when:(X)=>{if(X.signal.aborted){B({topic:X.topic,data:X.data});return}X.signal.addEventListener("abort",()=>B({topic:X.topic,data:X.data}),{once:!0})}}}export{WG as zipWith,o as zip,HG as unzip,PG as superRunner,t as superPromise,GG as setEnvironment,R as scheduleMicrotask,jG as safeTry,g as println,IG as pipe,E as panic,T as option,qG as matchAll,$G as match,z as isFalsy,w as createSignal,UG as createChannel,b as atom,p as _to,YG as Options,L as Ok,$ as Err};

package/dist/src/channel.d.ts

@@ -0,0 +1,39 @@
+/** Event published on a Channel. */
+export type ChannelEvent = {
+    topic: string;
+    data: unknown;
+};
+/** Subscriber handler receiving published events. */
+export type ChannelSubscriber = (event: ChannelEvent) => void;
+/** Event communication between independent parts of an application. */
+export type Channel = {
+    /** Immediately publishes an event to subscribers of its topic. */
+    send(event: ChannelEvent): void;
+    /**
+     * Subscribes to events of a specific topic.
+     * Returns an unsubscribe function; after calling it, no further events are received.
+     */
+    subscribe(filter: {
+        topic: string;
+    }, handler: ChannelSubscriber): () => void;
+    /** Publishes an event when a signal fires. Accepts any compatible lifecycle signal. */
+    when(config: {
+        signal: AbortSignal;
+        topic: string;
+        data: unknown;
+    }): void;
+};
+/**
+ * Creates a Channel — completely independent of SuperPromise/SuperRunner.
+ *
+ * @example
+ * const channel = createChannel();
+ *
+ * const unsubscribe = channel.subscribe({ topic: "user.created" }, event => {
+ *   println(event.data);
+ * });
+ *
+ * channel.send({ topic: "user.created", data: user });
+ * unsubscribe(); // stop receiving events
+ */
+export declare function createChannel(): Channel;

package/dist/src/index.d.ts

@@ -1,10 +1,13 @@
 export { scheduleMicrotask } from "./internals";
-export { println } from "./println";
+export { println, setEnvironment } from "./println";
+export type { EnvironmentMode, EnvironmentOptions, PrintFn } from "./println";
 export { panic } from "./panic";
 export { Ok, Err } from "./result";
 export type { Result, ResultMethods, Ok as OkType, Err as ErrType } from "./result";
 export { option, isFalsy } from "./option";
 export type { Option, OptionMethods, Some, None, NonTruthy } from "./option";
+export { Options } from "./options";
+export type { OptionsValue } from "./options";
 export { atom } from "./atom";
 export type { Atom, AtomMethods } from "./atom";
 import "./to";
@@ -14,3 +17,11 @@ export { zip, zipWith, unzip } from "./zip";
 export { safeTry } from "./safe-try";
 export { pipe } from "./pipe";
 export type { PipeFn, PipeEachContext, PipeRunOptions, Pipeline } from "./pipe";
+export { superPromise } from "./super-promise";
+export type { SuperPromise, SuperPromiseOptions, Executor, RetryUntilOptions } from "./super-promise";
+export { superRunner } from "./super-runner";
+export type { SuperRunner } from "./super-runner";
+export { createChannel } from "./channel";
+export type { Channel, ChannelEvent, ChannelSubscriber } from "./channel";
+export { createSignal } from "./signal";
+export type { Signal } from "./signal";

package/dist/src/internals.d.ts

@@ -7,6 +7,14 @@ import type { Option } from "./option";
 export declare const scheduleMicrotask: (fn: () => void) => void;
 /** Type guard for Result */
 export declare const isResult: (value: unknown) => value is Result<unknown, unknown>;
+/**
+ * Hidden activation hook carried by lifecycle signals (task.done, runner.done).
+ * Lets defer chains activate their source task when awaited.
+ */
+export declare const ACTIVATE_HOOK: unique symbol;
+export type Activatable = {
+    [ACTIVATE_HOOK]?: () => void;
+};
 /** Type guard for Option */
 export declare const isOption: (value: unknown) => value is Option<unknown>;
 /** Type guard for Atom (boxed symbol) */

package/dist/src/match.d.ts

@@ -23,11 +23,18 @@ type MatchKey = string | number | symbol;
 /**
  * Type-safe pattern object: must always have `_` fallback.
  */
-type MatchPatterns<V, R> = {
-    [K in MatchKey]?: (v: V) => R;
+type MatchPatterns<V> = {
+    [K in MatchKey]?: (v: V) => unknown;
 } & {
-    _: () => R;
+    _: () => unknown;
 };
+/**
+ * Extracts return types from all handlers in a patterns object as a union.
+ * Allows each arm to return a different type.
+ */
+type InferReturnTypes<P> = {
+    [K in keyof P]: P[K] extends (...args: any[]) => infer R ? R : never;
+}[keyof P];
 /**
  * Matches a value against literal or Atom cases by *semantic name*.
  * - Supports string, number, booleans and Atom (symbol) values.
@@ -47,5 +54,5 @@ type MatchPatterns<V, R> = {
  *   _: () => println("Unknown!"),
  * });
  */
-export declare function matchAll<T extends MatchKey | boolean, R>(value: T, patterns: MatchPatterns<T, R>): R;
+export declare function matchAll<T extends MatchKey | boolean, P extends MatchPatterns<T>>(value: T, patterns: P): InferReturnTypes<P>;
 export {};

package/dist/src/options.d.ts

@@ -0,0 +1,41 @@
+import { Err, type Result, type ResultMethods } from "./result";
+/**
+ * Resolves the usable inner type of a value.
+ * - `Some<U>` / `Ok<U>` contribute `U`.
+ * - `None`, `Err`, null, undefined, and empty string contribute nothing.
+ * - Raw values contribute themselves.
+ */
+export type OptionsValue<T> = T extends {
+    isErr: true;
+} | {
+    isNone: true;
+} | null | undefined | "" ? never : T extends {
+    isSome: true;
+    value: infer U;
+} | {
+    isOk: true;
+    value: infer U;
+} ? U : T;
+/**
+ * Returns the first usable value from a list as an `Ok`, or the fallback
+ * `Err` if none is usable.
+ *
+ * Normalizes heterogeneous 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` are usable, matching `option()` semantics.
+ *
+ * @param values - Values to inspect in order; first usable one wins.
+ * @param fallback - `Err` returned when no value is usable (default `Err("No value!")`).
+ * @returns `Ok` of the first usable inner value, or the fallback.
+ * @example
+ * const a = null;
+ * const b = option(undefined);
+ * const c = Ok(true);
+ * const d = Err("nope!");
+ * Options([a, b, c, d]); // Ok(true) - c is usable
+ *
+ * const nothing = Options([a, option(null), Err("nope!")]); // Err("No value!")
+ */
+export declare function Options<T extends readonly unknown[]>(values: T, fallback?: Err<string> & ResultMethods<never>): Result<OptionsValue<T[number]>, string>;

package/dist/src/println.d.ts

@@ -1,7 +1,20 @@
+export type EnvironmentMode = "development" | "production" | "dev" | "prod";
+export type PrintFn = (line: string) => void;
+export type EnvironmentOptions = {
+    printFn?: PrintFn | null;
+};
 /**
- * Logs the provided arguments to the console.
- * - Uses `globalThis.console.log` if available.
- * - Supports variadic arguments.
- * @param args - The arguments to log. Can be of any type.
+ * Sets the runtime environment for dev-only utilities.
+ * Idempotent — 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.
+ * 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.
+ * 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.
  */
 export declare const println: (...args: unknown[]) => void;

package/dist/src/signal.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A lifecycle Signal — a trigger that fires once and stays fired.
+ *
+ * Abort-compatible: structurally an `AbortSignal` plus a `fire()` method,
+ * so it can be passed anywhere a native `AbortSignal` is expected
+ * (and vice-versa). Wraps AbortController semantics.
+ *
+ * Consumed by `defer`, `retryUntil`, `channel.when`, and `task.done`.
+ */
+export type Signal = AbortSignal & {
+    /** Fires the signal once. Subsequent calls are no-ops. */
+    fire(): void;
+};
+/**
+ * Creates a lifecycle signal.
+ *
+ * ```ts
+ * const signal = createSignal();
+ *
+ * signal.addEventListener("abort", () => {
+ *   println("fired");
+ * });
+ *
+ * signal.fire(); // "fired"
+ * signal.aborted; // true
+ * ```
+ *
+ * Listeners are NOT replayed after firing — consumers must check
+ * `signal.aborted` synchronously to detect an already-fired signal.
+ */
+export declare function createSignal(): Signal;

package/dist/src/super-promise.d.ts

@@ -0,0 +1,60 @@
+import type { Result } from "./result";
+/** The operation itself. Receives the attempt's AbortSignal. */
+export type Executor<T> = (signal: AbortSignal) => T | Promise<T> | Result<T, string> | Promise<Result<T, string>>;
+/** Stop signal for `retryUntil`. */
+export type RetryUntilOptions = {
+    /** 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;
+};
+/** Execution policies, configured at construction time. */
+export type SuperPromiseOptions = {
+    /** Do not execute until this signal fires (accepts SuperPromise signals and AbortSignal). */
+    defer?: AbortSignal;
+    /** Wait before initial execution; normal retries also wait this long. */
+    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. */
+    retry?: number;
+    /** Keep retrying until the stop signal fires. Overrides `retry` and `delay`. */
+    retryUntil?: RetryUntilOptions;
+};
+/** A single async operation with lifecycle ergonomics. Promise-compatible. */
+export type SuperPromise<T> = {
+    /** Lifecycle signal: fires once when the task reaches a terminal state. */
+    done: AbortSignal;
+    /** Cancels the operation; settles with `Err("Aborted")` when not yet settled. */
+    abort(): void;
+    /** Manually settles an externally controlled task with a value. First settlement wins. */
+    resolve(value: T): void;
+    /** Manually settles an externally controlled task with a failure. First settlement wins. */
+    reject(error: unknown): void;
+    /** Observes a successful value without transforming it. Callback throws settle as `Err`. */
+    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. */
+    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 lifecycle/execution ergonomics.
+ *
+ * Lazy activation: the executor starts on first consumption (`await`/`.then()`,
+ * or a runner's `start()`), not at creation. Defer chains activate recursively,
+ * so awaiting a deferred task runs its dependency first.
+ *
+ * @example
+ * const task = superPromise(async signal => {
+ *   const response = await fetch(url, { signal });
+ *   return response.json();
+ * });
+ *
+ * const result = await task; // Result<T, string>
+ */
+export declare function superPromise<T>(fn: Executor<T>, options?: SuperPromiseOptions): SuperPromise<T>;
+/** Creates an externally controlled SuperPromise, settled via `resolve`/`reject`. */
+export declare function superPromise<T>(fn?: undefined, options?: SuperPromiseOptions): SuperPromise<T>;

package/dist/src/super-runner.d.ts

@@ -0,0 +1,42 @@
+import type { Result } from "./result";
+import type { SuperPromise } from "./super-promise";
+/** Sequence result: positional tuple of the runners' Ok values. */
+type TupleValues<R extends readonly SuperPromise<unknown>[]> = {
+    -readonly [K in keyof R]: R[K] extends SuperPromise<infer T> ? T : never;
+};
+/** all/race result: named object of the runners' Ok values. */
+type NamedValues<R extends Record<string, SuperPromise<unknown>>> = {
+    [K in keyof R]: R[K] extends SuperPromise<infer T> ? T : never;
+};
+/** race(count: 1) result: union of single-winner objects. */
+type RaceValues<C extends number, R extends Record<string, SuperPromise<unknown>>> = C extends 1 ? {
+    [K in keyof R]: {
+        [P in K]: R[K] extends SuperPromise<infer T> ? T : never;
+    };
+}[keyof R] : Partial<NamedValues<R>>;
+/** Orchestrates multiple already-created SuperPromises. */
+export type SuperRunner<Value> = {
+    /** Lifecycle signal: fires once when the runner reaches a terminal state. */
+    done: AbortSignal;
+    /** Starts execution. Idempotent: repeated calls return the same result without re-executing children. */
+    start(): Promise<Result<Value, string>>;
+    /** Cancels the runner and all active children; settles with `Err("Aborted")`. */
+    abort(): void;
+};
+/** Runs runners in order; stops at the first failure. */
+export declare function superRunner<const R extends readonly SuperPromise<unknown>[]>(config: {
+    type: "sequence";
+    runners: R;
+}): SuperRunner<TupleValues<R>>;
+/** Runs runners concurrently; fails fast on the first failure, aborting remaining children. */
+export declare function superRunner<const R extends Record<string, SuperPromise<unknown>>>(config: {
+    type: "all";
+    runners: R;
+}): SuperRunner<NamedValues<R>>;
+/** Runs runners concurrently; first `count` successful completions win, remaining children are aborted. */
+export declare function superRunner<const C extends number, const R extends Record<string, SuperPromise<unknown>>>(config: {
+    type: "race";
+    count: C;
+    runners: R;
+}): SuperRunner<RaceValues<C, R>>;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "slang-ts",
-  "version": "0.0.6",
-  "description": "Functional programming library for TypeScript",
+  "version": "0.0.8",
+  "description": "Functional programming library for TypeScript: Option, Result, pattern matching, and async primitives",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -12,13 +12,6 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:ui": "vitest --ui",
-    "typecheck": "tsc --noEmit",
-    "build": "bun run test && bun run typecheck && bun run bun-build.ts && tsc -p tsconfig.build.json"
-  },
   "homepage": "https://github.com/Hussseinkizz/slang#readme",
   "repository": {
     "type": "git",
@@ -31,14 +24,26 @@
     "functional",
     "typescript",
     "option",
+    "maybe",
     "result",
+    "safe-try",
     "pattern-matching",
+    "match",
     "monad",
-    "ts-pattern",
+    "pipe",
+    "zip",
+    "async",
+    "promise",
+    "superpromise",
+    "superrunner",
+    "cancellation",
+    "abort",
+    "signal",
+    "channel",
+    "event-bus",
     "defensive programming",
     "fp-ts",
     "ramda",
-    "rameda",
     "neverthrow",
     "lodash"
   ],
@@ -47,10 +52,17 @@
   "sideEffects": false,
   "devDependencies": {
     "@types/bun": "latest",
-    "@vitest/ui": "^4.0.15",
-    "vitest": "^4.0.15"
+    "@vitest/ui": "^4.1.10",
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "typescript": "^5"
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "typecheck": "tsc --noEmit",
+    "build": "bun run test && bun run typecheck && bun run bun-build.ts && tsc -p tsconfig.build.json"
   }
-}
+}