slang-ts 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,12 @@
 # slang-ts
 
-Functional programming library for TypeScript.
+[![npm version](https://img.shields.io/npm/v/slang-ts.svg)](https://www.npmjs.com/package/slang-ts)
+[![license](https://img.shields.io/npm/l/slang-ts.svg)][license]
 
-A collection of utilities and other cool programming stuff brought over from languages like Rust.
+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.
 
 ## Install
 
@@ -10,693 +14,276 @@ A collection of utilities and other cool programming stuff brought over from lan
 npm i slang-ts
 ```
 
-## Implemented Utilities
-
-- [x] Option (Some, None)
-- [x] isFalsy (Option truthiness check)
-- [x] Result (Ok, Err)
-- [x] Expect
-- [x] Unwrap (on Option)
-- [x] Else (on unwrap)
-- [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)
-
-## New in v0.0.10
-
-- **Ok messages**: `Ok(value, message?)` keeps an optional success message on the result, such as text to show the user. Results without one have no `message` property.
-
-## New in v0.0.9
-
-- **SafeTry**: unwraps nested Result, Option, and Atom values into one result; nested failures now become the outer `Err`, while plain object properties and array elements stay unchanged.
-- **Package types**: bundled declarations work with strict NodeNext consumers, so importing the package no longer exposes invalid declaration paths.
-- **Build tooling**: tsdown and TypeScript 7 build JavaScript and bundled types together.
-
-## New in v0.0.8
-
-- **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
-
-Import utilities individually or together:
-
-```ts
-// Individual imports
-import { option } from "slang-ts";
-import { Ok, Err } from "slang-ts";
-
-// Or import multiple at once
-import { option, Ok, Err, atom, match } from "slang-ts";
-
-// Or import under namespace (not so performant)
-import * as slang from "slang-ts";
-
-slang.println("Hello world!");
-```
-
-### 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.
-
-```ts
-import { option } from "slang-ts";
-
-const a = option("hi");      // Some("hi")
-const b = option(null);      // None
-const c = option(0);         // Some(0) - zero is truthy!
-const d = option("");        // None
-const e = option(false);     // Some(false) - false is truthy!
-
-if (a.isSome) {
-  println("Value:", a.value);
-}
+## Why I Made This?
 
-if (b.isNone) {
-  println("No value");
-}
-```
+Well I love functional programming so much and hate classes and inheritance with all my heart, sorry no offense intended, I prefer composition and functions over those but well that's not exactly why I made this despite part of the reasons, main reason was all functional programming (FP) libraries in typescript and javascript were really complicated, think effect ts and rameda, all seemed like needed one to be so nerdy, so was like I need something simple I can work with comfortably and can onboard a team to over an evenning, one by one, got each utility crafted out, to what you see today, here I aimed more for practicality than correctness, so yes some functions are not pure, a few rules broken, a few opinions, and all that makes this fun to use, try it!
 
-### Result
+## Quick start
 
-Represents operations that can succeed or fail. Returns `Ok<T>` on success or `Err<E>` on failure with typed error payload.
+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`:
 
 ```ts
-import { Ok, Err, type Result } from "slang-ts";
+import { Ok, Err, type Result, println } from "slang-ts";
 
-// Simple function returning Result
 function divide(a: number, b: number): Result<number, string> {
-  if (b === 0) return Err("Cannot divide by zero");
-  return Ok(a / b);
+  return b === 0 ? Err("Cannot divide by zero") : Ok(a / b);
 }
 
 const result = divide(10, 2);
 
 if (result.isOk) {
-  println("Success:", result.value); // 5
+  println("Result:", result.value); // 5
 } else {
   println("Error:", result.error);
 }
-
-// Async API example
-interface User {
-  id: string;
-  name: string;
-}
-
-async function fetchUser(id: string): Promise<Result<User, string>> {
-  try {
-    const response = await fetch(`/api/users/${id}`);
-    if (!response.ok) return Err("User not found");
-    const user = await response.json();
-    return Ok(user);
-  } catch (error) {
-    return Err("Network error");
-  }
-}
-
-const user = await fetchUser("123");
-if (user.isOk) {
-  println("User:", user.value.name);
-}
-
-// Optional success message as the second argument
-const saved = Ok({ id: "123" }, "Profile saved");
-if (saved.isOk) {
-  println(saved.message); // "Profile saved"
-}
 ```
 
-`andThen` and `safeTry` return new results, so a message stays with the value it described.
-
-### Expect
-
-Unwraps values or throws with custom message. Use when failure is unrecoverable.
-
-```ts
-const personAge = option(25).expect("a person must have age!");
-println("person age", personAge); // 25
-
-// This would throw!
-// const personAge2 = option("").expect("a person must have age!");
-```
+`println` is optional — it's a small development logger.
 
-### Unwrap/Else
+## Imports
 
-Chainable unwrapping with mandatory fallback. Must call `.else()` or throws.
+Import only what you use:
 
 ```ts
-const port = option(process.env.PORT).unwrap().else(3000);
-println("Using port:", port);
-
-// Function fallbacks
-const retries = option(null).unwrap().else(() => 5);
-println("Retries:", retries);
-
-// This throws! No .else() chained
-// const nothing = option(null).unwrap();
-```
-
-### 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`.
-
-```ts
-// Option - transforms Some, skips None
-option(5).andThen(x => x * 2);              // Some(10)
-option(null).andThen(x => x * 2);           // None (skipped)
-option(5).andThen(() => undefined);         // Some(5) - original
-
-// Result - transforms Ok, skips Err
-Ok(10).andThen(x => x + 5);                 // Ok(15)
-Err("fail").andThen(x => x + 5);            // Err("fail") (skipped)
-
-// Atom - transforms description (sync only)
-atom("hello").andThen(s => s.toUpperCase()); // Atom("HELLO")
-
-// Chained andThen - multiple transformations
-option(5)
-  .andThen(x => x + 1)
-  .andThen(x => x * 2)
-  .andThen(x => x.toString());              // Some("12")
-
-Ok(10)
-  .andThen(x => x * 2)
-  .andThen(x => x + 5)
-  .andThen(x => ({ value: x }));            // Ok({ value: 25 })
-
-atom("hello")
-  .andThen(s => s.toUpperCase())
-  .andThen(s => s + "!");                   // Atom("HELLO!")
-
-// Async support for Option and Result
-const data = await option(5).andThen(async x => await fetchData(x));
-
-// Error handling
-option(5).andThen(() => { throw "oops" });  // None (caught)
-Ok(5).andThen(() => { throw "oops" });      // Err("oops")
-atom("x").andThen(() => { throw "oops" });  // Panics!
-
-// Type transformation
-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
+import { option, Ok, Err, atom, match } from "slang-ts";
 ```
 
-Useful when values come from different functions with inconsistent return types and all you care about is whether the end result is usable.
-
-### SafeTry
+## Choose by problem
 
-Runs sync or async functions and captures failures as `Err<string>`. Always await it. Nested Result, Option, and Atom values resolve to one `Result`: `Ok` and `Some` unwrap until a plain value appears, `Err` stops with its error normalized through `String`, `None` becomes `Err("Option was None")`, and Atom becomes its description.
+| If you need… | Use |
+|---|---|
+| A value that may be missing | [Option][option] |
+| An operation that can fail | [Result][result] and [SafeTry][safe-try] |
+| Pattern matching over results | [Match][match] |
+| 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] |
+| 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] |
 
-```ts
-import { safeTry, Ok, Err, option, atom, println, type Result } from "slang-ts";
-
-// Inferred type is Promise<Result<number, string>>, not nested Results.
-const pending: Promise<Result<number, string>> = safeTry(() => Ok(Ok(42)));
-const nested = await pending; // Ok(42)
-if (nested.isOk) println(nested.value); // 42
+## What's inside
 
-const failed = await safeTry(() => Ok(Ok(Err("Not found")))); // Err("Not found")
-if (failed.isErr) println(failed.error); // "Not found"
+### Error handling and flow
 
-const mixed = await safeTry(() => Ok(option(Ok(atom("ready")))));
-// Ok("ready"); inferred success value is the literal "ready".
-if (mixed.isOk) println(mixed.value); // "ready"
+- [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]
 
-const missing = await safeTry(() => Ok(option(null))); // Err("Option was None")
-if (missing.isErr) println(missing.error);
+### Composition and conversion
 
-const caught = await safeTry(async () => {
-  throw new Error("Could not load profile");
-}); // Err("Could not load profile")
-if (caught.isErr) println(caught.error);
-```
+- [Atom][atom]
+- [To][to] (`.to()` converters)
+- [Zip][zip] (zip, zipWith, unzip)
 
-Only the returned wrapper chain unwraps. Plain object properties and array elements stay as supplied. Only the callback's return is awaited; a Promise inside `Ok` or `Some` stays a Promise.
+### Collections and data
 
-```ts
-import { safeTry, Ok, println } from "slang-ts";
+- [list][list]
+- [struct][struct]
+- [sets][sets]
+- [Ok.iterate][iterate]
+- [memoized][memoized]
 
-const payload = { result: Ok(42), items: [Ok(7)] };
-const plain = await safeTry(() => payload); // Ok(payload), same object
-if (plain.isOk) println(plain.value === payload); // true
+### Async and lifecycle
 
-const innerPromise = Promise.resolve(42);
-const wrapped = await safeTry(() => Ok(innerPromise));
-// Ok(innerPromise), success value stays Promise<number>.
-if (wrapped.isOk) println(wrapped.value === innerPromise); // true
-```
+- [SuperPromise][super-promise]
+- [SuperRunner][super-runner]
+- [taskGroup][task-group]
+- [Signal][signal]
+- [Channel][channel]
 
-`{ throw: true }` rethrows errors caught while running the callback or reading its returned wrappers. Returned `Err` values still return normally. A circular wrapper chain returns `Err("Cannot resolve a circular value")`, including with `{ throw: true }`.
+### Small utilities
 
-```ts
-import { safeTry, Ok, Err, println } from "slang-ts";
+- [Panic][panic]
+- [println][logging] (with `setEnvironment`)
+- [createStepper][stepper]
 
-const returned = await safeTry(() => Ok(Err("Not found")), { throw: true });
-if (returned.isErr) println(returned.error); // "Not found"
+Full reference: [docs index][docs-index]. Feature list: [CHANGELOG.md][changelog].
 
-await safeTry(() => {
-  throw new Error("Critical failure");
-}, { throw: true }).catch((error: Error) => println(error.message));
-// "Critical failure": the call rejects instead of returning Err.
-```
+## Real-world examples
 
-### Pipe
+### Load a value that can fail: SafeTry + Result
 
-Sequential function composition where each function receives a `Result` and returns a `Result`. Accepts plain values, Option, Result, or Atom as initial input.
+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`:
 
 ```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;
+import { Err, Ok, safeTry, type Result, println } from "slang-ts";
 
-// Basic usage
-const result = await pipe(5, add(3), multiply(2)).run();
-println("Result:", result.value); // 16
+type Role = "admin" | "member";
 
-// With Options as initial value
-const fromOption = await pipe(option(10), add(5)).run();
-println("From option:", fromOption.value); // 15
+function parseRole(value: string): Result<Role, string> {
+  return value === "admin" || value === "member"
+    ? Ok(value)
+    : Err("Unknown role");
+}
 
-// 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
+const role = await safeTry(() => {
+  const saved = localStorage.getItem("role");
+  if (saved === null) throw new Error("No role saved");
+  return parseRole(saved);
 });
-```
-
-### 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");
+if (role.isOk) {
+  println("Role:", role.value);
 } else {
-  println("not the same");          // This prints!
+  println("Could not load role:", role.error);
 }
 ```
 
-### Zip
-
-Combines multiple collections element-wise into tuples.
-
-```ts
-import { zip } from "slang-ts";
-
-// Zip arrays
-const arr1 = [1, 2, 3];
-const arr2 = [4, 5, 6];
-const arr3 = [7, 8, 9];
-println(zip([arr1, arr2, arr3]));
-// [[1,4,7],[2,5,8],[3,6,9]]
-
-// Zip with fillValue
-println(zip([arr1, [10, 20]], { fillValue: 0 }));
-// [[1,10],[2,20],[3,0]]
-
-// Zip Sets with includeValues=true
-const s1 = new Set([10, 20, 30]);
-const s2 = new Set([100, 200, 300]);
-println(zip([s1, s2], { includeValues: true }));
-// [[10,100],[20,200],[30,300]]
-
-// Zip objects with includeValues=true
-const o1 = { a: 1, b: 2, c: 3 };
-const o2 = { x: 100, y: 200, z: 300 };
-println(zip([o1, o2], { includeValues: true }));
-// [[1,100],[2,200],[3,300]]
-```
-
-### ZipWith
-
-Combines collections and applies transform function to each tuple.
-
-```ts
-import { zipWith } from "slang-ts";
-
-const arr1 = [1, 2, 3];
-const arr2 = [4, 5, 6];
-const arr3 = [7, 8, 9];
-
-println(zipWith([arr1, arr2, arr3], (t) => t.reduce((sum, x) => sum + x, 0)));
-// [12, 15, 18]
-```
-
-### Unzip
-
-Reverses zip operation, separating tuples back into arrays.
-
-```ts
-import { unzip } from "slang-ts";
-
-const arr1 = [1, 2, 3];
-const arr2 = [4, 5, 6];
-
-const zipped = zip([arr1, arr2]);
-println(unzip(zipped));
-// [[1, 2, 3], [4, 5, 6]]
-```
-
-### Panic
-
-Throws an error immediately. Use for unrecoverable failures.
+Without it, you'd have to catch the throw and still branch on the value:
 
 ```ts
-import { panic } from "slang-ts";
+type Role = "admin" | "member";
 
-function processUser(user: User | null) {
-  if (!user) panic("User cannot be null");
-  return user.name;
+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;
 }
 
-// Guard clause pattern
-const config = loadConfig();
-if (!config.apiKey) panic("API key required");
-```
-
-### println
-
-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.
-
-```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()) });
+try {
+  const role = loadRole();
+  console.log("Role:", role);
+} catch (error) {
+  console.log(
+    "Could not load role:",
+    error instanceof Error ? error.message : "Unknown error",
+  );
+}
 ```
 
-### Signal
-
-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 { createSignal } from "slang-ts";
-
-const ready = createSignal();
+Full detail: [SafeTry][safe-try] and [Result][result].
 
-ready.addEventListener("abort", () => println("ready!")); // fires when the trigger goes off
-ready.fire();                                             // flip it
-```
+### Call an API with a timeout and retries: SuperPromise
 
-The useful part: gate work on a signal, or publish events when a lifecycle completes.
+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.
 
 ```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 },
-});
-```
+import { superPromise, println } from "slang-ts";
 
-### SuperPromise
+const id = "123";
 
-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 }
+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 };
+  },
+  { timeout: 5000, retry: 2 },
 );
 
-if (result.isOk) {
-  println("User:", result.value);
+if (user.isOk) {
+  println("User:", user.value.name);
 } else {
-  println("Failed:", result.error);
+  println("Could not load user:", user.error);
 }
 ```
 
-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);
-  }
-});
-```
-
-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:
-
-```ts
-const config = superPromise(loadConfig);
-const user = superPromise(loadUser, { defer: config.done });
-
-const result = await user; // config runs first, then user
-```
-
-Cancel from outside, or keep retrying until you call it off:
-
-```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
-const manual = superPromise<number>();  // no executor; settle it yourself
-manual.resolve(100);                    // or manual.reject(error)
-
-await superPromise(loadUser).tap((user) => println(user.name)); // observe without changing
-```
+Full detail: [SuperPromise][super-promise].
 
-### SuperRunner
+### Page a list and shape records: list + struct
 
-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.
+`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.
 
 ```ts
-import { superRunner, superPromise as sp } from "slang-ts";
+import { list, struct, println } 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
-```
-
-Publish when a trigger goes off, a task finishing, anything at all:
+type User = {
+  id: string;
+  name: string;
+  avatar?: string;
+  email: string;
+};
+
+const users: User[] = await getUsers(); // your data source
+
+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 cards = paged.map((user) =>
+  struct(user).pick("id", "name", "avatar").else(user),
+);
 
-```ts
-channel.when({
-  signal: workflow.done,
-  topic: "workflow.completed",
-  data: { workflowId },
-});
+println(cards);
 ```
 
-## Code Samples
+`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.
 
-See [example.ts](https://github.com/Hussseinkizz/slang/blob/main/example.ts) for usage of currently implemented methods.
+Full detail: [list][list] and [struct][struct].
 
 ## Development
 
-Install project dependencies with Bun, then build:
+Install with Bun, then run the full check:
 
 ```bash
 bun install
-bun run build
+bun run export
 ```
 
-The build runs tests, checks types with TypeScript 7.0.2, then uses tsdown 0.23.1 to produce minified ESM at `dist/index.js` and bundled types at `dist/index.d.ts`. Package imports keep the same entry points. tsdown currently marks its TypeScript 7 integration as experimental; the project build passes with this setup.
-
-For building, tsdown requires Node.js `^22.18.0 || ^24.11.0 || >=26.0.0`. This is a build-tool requirement, not a new runtime requirement for Slang consumers.
+`export` runs the tests, checks types, and builds minified ESM with bundled declarations into
+`dist/`. `npm publish` runs it through `prepublishOnly`, so you never ship stale output. Tests live
+in [tests](https://github.com/Hussseinkizz/slang/tree/main/tests).
 
-Packaged output passes strict consumer checks with TypeScript 5.9.3 and 7.0.2 under both NodeNext and Bundler resolution, including declaration checking. See [migration context](context.md) for verification details.
+Building needs Node.js `^22.18.0 || ^24.11.0 || >=26.0.0`. That's for the build tool, not for
+projects using Slang.
 
 ## Contributing
 
-Contributions are welcome. I know there are a lot of cool things out there we can bring in.
+Got a utility from another language that belongs here? Open an issue or a pull request.
+Contributions are welcome.
+
+## Requirements
+
+- ESM only. You'll use `import`; `require` isn't supported.
+- Node.js 20+ or a modern browser.
+- TypeScript 5.9.x or 7.0.x if you want the bundled types. Plain JavaScript works too.
+- Zero runtime dependencies.
+
+## License
+
+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
+[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
+[atom]: https://github.com/Hussseinkizz/slang/blob/main/docs/atom.md
+[to]: https://github.com/Hussseinkizz/slang/blob/main/docs/to.md
+[zip]: https://github.com/Hussseinkizz/slang/blob/main/docs/zip.md
+[list]: https://github.com/Hussseinkizz/slang/blob/main/docs/list.md
+[struct]: https://github.com/Hussseinkizz/slang/blob/main/docs/struct.md
+[sets]: https://github.com/Hussseinkizz/slang/blob/main/docs/sets.md
+[iterate]: https://github.com/Hussseinkizz/slang/blob/main/docs/iterate.md
+[memoized]: https://github.com/Hussseinkizz/slang/blob/main/docs/memoized.md
+[super-promise]: https://github.com/Hussseinkizz/slang/blob/main/docs/super-promise.md
+[super-runner]: https://github.com/Hussseinkizz/slang/blob/main/docs/super-runner.md
+[task-group]: https://github.com/Hussseinkizz/slang/blob/main/docs/task-group.md
+[signal]: https://github.com/Hussseinkizz/slang/blob/main/docs/signal.md
+[channel]: https://github.com/Hussseinkizz/slang/blob/main/docs/channel.md
+[panic]: https://github.com/Hussseinkizz/slang/blob/main/docs/panic.md
+[logging]: https://github.com/Hussseinkizz/slang/blob/main/docs/logging.md
+[stepper]: https://github.com/Hussseinkizz/slang/blob/main/docs/stepper.md
+[docs-index]: https://github.com/Hussseinkizz/slang/blob/main/docs/README.md
+[changelog]: https://github.com/Hussseinkizz/slang/blob/main/CHANGELOG.md
+[license]: https://github.com/Hussseinkizz/slang/blob/main/LICENSE