slang-ts 0.2.2 → 0.2.3

package/skill/SKILL.md

@@ -1,10 +1,19 @@
 # slang-ts agent skill
 
-This skill tells AI agents how to work with slang-ts: its APIs, patterns, and conventions so agents can write correct TypeScript against it.
+Use this skill to write correct TypeScript with slang-ts: its APIs, the patterns it expects, and
+the conventions to follow.
 
 ## What slang-ts is
 
-slang-ts is a zero-dependency functional programming library for TypeScript. It brings Rust- and Erlang-style utilities: `Option`, `Result`, `SafeTry`, pattern matching (`match`/`matchAll`), async control (`SuperPromise`, `SuperRunner`, `taskGroup`, `Signal`, `Channel`), and data helpers (`list`, `struct`, `sets`, `Ok.iterate`, `memoized`, `zip`, `pipe`, `atom`, `to`).
+slang-ts is a zero-dependency functional programming library for TypeScript, with utilities
+brought over from Rust and Erlang:
+
+- Failures as values: `Result` (`Ok`, `Err`), `Option`, `safeTry`, `combineResults`, `combineErrors`, `match`, `matchAll`, `Options`, `pipe`, `panic`
+- Data helpers: `list`, `struct`, `sets`, `Ok(value).iterate()`, `memoized`, `zip`, `zipWith`, `unzip`
+- Conversion: `atom`, `.to()` on every wrapper
+- Async work: `superPromise`, `superRunner`, `taskGroup`, `createSignal`, `createChannel`
+- Step history: `createStepper`
+- Output: `println`, `setEnvironment`
 
 Import only what you use:
 
@@ -16,60 +25,210 @@ import { option, Ok, Err, match, superPromise, list } from "slang-ts";
 
 ### Option
 
-`option<T>(value): Option<T>` — wraps a value that may or may not be there.
+`option<T>(value): Option<T>` wraps a value which may be missing.
 
-`0` and `false` count as present; `null`, `undefined`, `""`, `NaN`, and `Infinity` are `None`.
+`0` and `false` count as present. `null`, `undefined`, `""`, `NaN`, `Infinity` and `-Infinity`
+become `None`.
 
 ```ts
-const port = option(process.env.PORT).unwrap().else(3000);
+import { option, println } from "slang-ts";
+
+const savedPort = new URLSearchParams("port=8080").get("port");
+
+const port = option(savedPort).unwrap().else("3000");
+
+println("Port:", port); // "8080"
 ```
 
-Never read `.value` on `None`. Check `.isSome` / `.isNone` first, or use `.unwrap().else(fallback)`.
+- Check `.isSome` / `.isNone` before reading `.value`, or use `.unwrap().else(fallback)`.
+- `.unwrap()` must be finished with `.else(...)`. `.else` throws if the fallback is a value
+  `option()` treats as missing; `0` and `false` are valid fallbacks.
+- `.expect(message?)` returns the value or throws on `None`.
 
 ### Result
 
 `Result<T, E>` is `Ok<T>` or `Err<E>`.
 
 ```ts
-Ok<T>(value, message?);     // success, optional message
-Err<E>(error, raw?);        // failure, optional diagnostic cause
+// Signature
+Ok<T>(value, message?);   // success, with an optional message for the user
+Err(error, raw?);         // failure: a human-readable error, plus an optional cause for logs
+```
+
+`Err(error, raw?)` keeps the original cause on the non-enumerable `.raw` for logs; `.error`
+stays human-readable.
+
+```ts
+import { Ok, Err, type Result, println } from "slang-ts";
+
+function splitBill(total: number, people: number): Result<number, string> {
+  if (people === 0) {
+    return Err("Add at least one person to split the bill");
+  }
+
+  return Ok(total / people);
+}
+
+const share = splitBill(120, 4);
+
+if (share.isOk) {
+  println("Each person pays:", share.value); // 30
+} else {
+  println("Could not split the bill:", share.error);
+}
+```
+
+- Branch with `if (result.isOk) { ... } else { ... }`.
+- Get the value with `.unwrap().else(fallback)`, or `.expect(message?)` when a failure should
+  throw.
+- `.andThen(fn)` transforms an `Ok` and skips an `Err`. A plain return becomes `Ok`, a
+  returned `Result` passes through, `undefined` keeps the original, and a throw or rejection
+  becomes `Err(message)`.
+- `.mapErr(fn)` rewrites an `Err`'s message (`fn` receives the message, returns a string) and
+  keeps the original `.raw`. Use it at a route or page edge to turn a technical message into
+  a human one. Sync only. On `Ok` it returns the same `Ok`.
+- `.orFn(fn)` recovers from an `Err`: `fn(error, raw)` follows the same rules as `andThen`
+  (plain value becomes `Ok`, a `Result` passes through, `undefined` keeps the original `Err`,
+  a throw or rejection becomes `Err(message)`). On `Ok` it returns the same `Ok`. It is not
+  `unwrap().else()`, which leaves the `Result` and returns a plain value.
+- With a sync callback, `andThen` and `orFn` return a `Result`; read it without `await`. With
+  an async callback, or one typed as either a value or a promise, or `unknown`, they return
+  `Result | Promise<Result>`: `await` it. The skipped side never calls the callback and
+  returns the same instance synchronously, so the async case stays a union.
+- A `Result` never nests inside another `Result`: `Ok(Ok(x))` and `Ok(Err(x))` do not compile.
+
+### safeTry
+
+`safeTry(fn, options?)` runs a sync or async function and turns every failure (a throw, a
+returned `Err`, a returned `None`) into one `Err`. Sync in, sync out:
+
+- A function returning a plain value gets its `Result` directly; read it without `await`.
+- A function returning a promise (or any thenable) gets `Promise<Result>`. `await` it.
+- A function typed as either a value or a promise, or `unknown`, gets the union. `await` it.
+- A sync result is a plain `Result`: `await` on it works, `.then()` does not exist.
+- `{ throw: true }`: a sync throw throws from the call; an async throw rejects the promise.
+
+```ts
+import { safeTry, println } from "slang-ts";
+
+type Settings = {
+  theme: string;
+};
+
+const settings = safeTry(() => {
+  return JSON.parse('{"theme":"dark"}') as Settings;
+});
+
+if (settings.isOk) {
+  println("Theme:", settings.value.theme); // "dark"
+} else {
+  println("Could not read the settings:", settings.error);
+}
 ```
 
-`Err(error, raw?)` keeps the original cause on the non-enumerable `.raw` for logs; `.error` stays human-readable.
+### combineResults / combineErrors
 
-Branch with `if (result.isOk) { ... } else { ... }`. Finish chains with `.unwrap().else(fallback)` or `.unwrap().panic(message?)`.
+`combineResults(results)` returns `Ok([...values])` typed as a tuple when every result is `Ok`,
+or the first `Err` as the same instance (`.raw` kept). An empty array gives `Ok([])`.
+`combineErrors(results)` returns every error message in input order, `[]` when all are `Ok`.
 
 ```ts
-function divide(a: number, b: number): Result<number, string> {
-  return b === 0 ? Err("Cannot divide by zero") : Ok(a / b);
+import { Ok, Err, combineResults, combineErrors, type Result, println } from "slang-ts";
+
+function validateEmail(input: string): Result<string, string> {
+  if (!input.includes("@")) {
+    return Err("Enter a valid email address");
+  }
+
+  return Ok(input.toLowerCase());
+}
+
+function validateAge(input: string): Result<number, string> {
+  const age = Number(input);
+
+  if (!Number.isInteger(age) || age < 13) {
+    return Err("You must be at least 13 to sign up");
+  }
+
+  return Ok(age);
+}
+
+const fields: [Result<string, string>, Result<number, string>] = [
+  validateEmail("ada@example.com"),
+  validateAge("29"),
+];
+
+const problems = combineErrors(fields);
+
+if (problems.length > 0) {
+  println("Fix these fields:", problems);
+} else {
+  const values = combineResults(fields);
+
+  if (values.isOk) {
+    const [email, age] = values.value; // typed [string, number]
+
+    println(email, age); // "ada@example.com" 29
+  }
 }
 ```
 
-`Result` never nests inside another `Result` — `Ok(Ok(x))` and `Ok(Err(x))` won't compile.
+- Arrays of results only, and sync. `await` promises first; run async tasks with
+  `superRunner`; chain dependent steps with `pipe`.
+- Pass an array literal or a tuple-typed value to keep the tuple type.
 
 ### match / matchAll
 
-`match(value, patterns)` — exhaustive pattern matching for `Option` and `Result`. TypeScript requires both cases.
+`match(value, patterns)` handles every case of an `Option` or `Result`. TypeScript requires both
+cases. Each handler receives the wrapper itself.
 
 ```ts
-match(result, { Ok: (v) => ..., Err: (e) => ... });
+import { Ok, match, println } from "slang-ts";
+
+const saved = Ok({ id: "u_1", name: "Ada" });
+
+const greeting = match(saved, {
+  Ok: (user) => `Welcome back, ${user.value.name}`,
+  Err: (failed) => `Could not load your profile: ${failed.error}`,
+});
+
+println(greeting); // "Welcome back, Ada"
 ```
 
-`matchAll(value, patterns)` — matching for strings, numbers, booleans, symbols, and `Atom`s. Always needs a `_` fallback.
+`matchAll(value, patterns)` matches strings, numbers, booleans and `Atom`s. It always needs a
+`_` fallback.
 
 ```ts
-const message = matchAll(failed.category, {
+import { list, matchAll, println } from "slang-ts";
+
+const failed = list(["a", "b", "c"]).take(5);
+
+const message = matchAll(String(failed.category), {
   OUT_OF_BOUNDS: () => "That page is out of range.",
-  _: (category) => `Unexpected failure: ${category}`,
+  _: () => "Something went wrong.",
 });
+
+println(message); // "That page is out of range."
 ```
 
 ## Collection chains (list, struct, sets, Ok.iterate)
 
-These return a `Fallible<T>`, not a plain `Result`. Finish with `.else(fallback)` or `.panic(message?)`. On failure, `.category` holds a string like `"OUT_OF_BOUNDS"` or `"INVALID_INPUT"`.
+These return a `Fallible<T>`, not a `Result`. Finish with `.else(fallback)` or
+`.panic(message?)`. On failure, `.category` holds a string such as `"OUT_OF_BOUNDS"` or
+`"INVALID_INPUT"`.
+
+- `list`, `struct` and `sets` run each method at once and return a new chain. `Ok.iterate` is
+  lazy: steps run only when `toArray`, `reduce` or `count` is called.
+- Nothing throws mid-chain. The first failure is kept and later steps are skipped.
+- Inputs are never changed; each step returns new arrays, objects or sets.
+- `list`, `struct` and `sets` accept a raw value or a successful `Ok` holding one; an `Err`
+  fails with `INVALID_INPUT`.
 
 ```ts
+import { list, println } from "slang-ts";
+
 const failed = list([1, 2, 3]).range(1, 99).take(1);
+
 if (failed.category === "OUT_OF_BOUNDS") {
   println(failed.else([])); // []
 } else {
@@ -77,114 +236,241 @@ if (failed.category === "OUT_OF_BOUNDS") {
 }
 ```
 
-- `get` already takes a fallback: `get(key, fallback)`. Do not pair `get(x, fallback)` with `.else(fallback)` — that's redundant.
+- `get` takes a fallback: `get(key, fallback)`. Finish it with `.panic()`, or use
+  `get(key).else(fallback)`. Never pair `get(key, fallback)` with `.else(fallback)`.
 - `.panic()` throws; once you panic, no custom message is read afterward.
 
 ### list
 
-`list<T>(input): ListChain<T>` — strict indexed arrays with explicit bounds. Out-of-range fails instead of clamping.
+`list<T>(input): ListChain<T>` reads and slices an array with strict bounds. Every index,
+count and bound must be an integer inside the array; negative indices count from the end. An
+out-of-range request fails with `OUT_OF_BOUNDS` instead of returning fewer items.
 
 ```ts
-const page = list(users).range(start, end).else([]);
+import { list, println } from "slang-ts";
+
+const users = ["Ada", "Grace", "Linus"];
+
+const page = list(users).range(0, 2).else([]);
+
+println(page); // ["Ada","Grace"]
 ```
 
 Methods: `get`, `take`, `skip`, `range`, `chunk`, `count`, `prune`.
 
 ### struct
 
-`struct<T>(input): StructChain<T>` — safe record access and shaping.
+`struct<T>(input): StructChain<T>` reads paths through a record and shapes it. `get` reads own
+properties only: an absent key fails, a key holding `undefined` succeeds. `merge` deep merges
+plain objects; arrays and other values in the patch replace the old value.
 
-Methods: `get`, `pick`, `omit`, `merge`, `countBy`, `keyBy`, `prune`.
+Methods: `get`, `pick`, `omit`, `merge`, `count`, `countBy`, `keyBy`, `prune`.
 
 ```ts
-const port = struct(config).get(["server", "port"], 3000);
+import { struct, println } from "slang-ts";
+
+const config = {
+  server: { host: "localhost" },
+};
+
+const port = struct(config).get(["server", "port"], 3000).panic();
+
+println("Port:", port); // 3000
 ```
 
-- `prune` drops Slang-falsy values (`null`, `undefined`, `""`, `NaN`, `Infinity`, `-Infinity`) but keeps `0` and `false`. Its predicate receives `(value, key)` and returns `true` to keep a value. It needs a plain object.
-- Wrong shape for the operation fails with `INVALID_INPUT`. A missing `get` path fails with `OUT_OF_BOUNDS`. Once a chain fails, later steps don't run, and the category survives so you can check `.category`.
+- `prune` drops Slang-falsy values (`null`, `undefined`, `""`, `NaN`, `Infinity`, `-Infinity`)
+  and keeps `0` and `false`. Its predicate receives `(value, key)` and returns `true` to keep a
+  value. It needs a plain object.
+- The wrong shape for an operation fails with `INVALID_INPUT`. A missing `get` path fails with
+  `OUT_OF_BOUNDS`. Once a chain fails, later steps are skipped and the category stays on
+  `.category`.
 
 ### sets
 
-`sets<T>(input): SetsChain<T>` — membership and set operations.
+`sets<T>(input): SetsChain<T>` handles membership and set operations.
 
-Methods: `has`, `unique`, `union`, `intersection`, `difference`. Objects compare by identity; primitives by value.
+Methods: `has`, `unique`, `union`, `intersection`, `difference`, `count`. An array, string or
+iterable gives its values, a `Map` its keys, a plain object its own keys. Objects compare by
+identity; primitives by value. The other side of an operation accepts the same inputs.
 
 ### Ok.iterate
 
-`Ok<T>(value).iterate(): IterateChain<T>` — lazy pipelines over a successful `Ok`.
+`Ok<T>(value).iterate(): IterateChain<T>` builds a lazy pipeline over the iterable in a
+successful `Ok`. Values pass through every step one at a time, so `take(n)` stops reading the
+source early. A throw in a callback or the source becomes a failure with `INVALID_INPUT`. A
+single-use source, such as a generator, can be finished once.
 
 Methods: `map`, `filter`, `flatMap`, `take`, `drop`, `chunk`, `reduce`, `count`, `toArray`.
 
 ```ts
+import { Ok, println } from "slang-ts";
+
+type User = {
+  name: string;
+  active: boolean;
+};
+
+const users: User[] = [
+  { name: "Ada", active: true },
+  { name: "Grace", active: false },
+];
+
 const names = Ok(users)
   .iterate()
-  .filter((u) => u.active)
-  .map((u) => u.name)
+  .filter((user) => user.active)
+  .map((user) => user.name)
   .toArray()
   .else([]);
+
+println(names); // ["Ada"]
 ```
 
 ## Async
 
 ### SuperPromise
 
-`superPromise<T>(fn, options?): SuperPromise<T>` — one async operation with start, retry, timeout, and cancel controls. Your function gets an `AbortSignal`. Tasks end as `Ok` or `Err`.
+`superPromise<T>(fn, options?): SuperPromise<T>` is a native promise plus start, retry, timeout
+and cancel controls. Your function receives an `AbortSignal`. Awaiting it gives `Ok` or `Err`;
+it never rejects.
 
 Options: `defer`, `delay`, `timeout`, `retry`, `retryUntil`, `group`.
 
 ```ts
+import { superPromise, println } from "slang-ts";
+
+type User = {
+  id: string;
+  name: string;
+};
+
 const user = await superPromise(
-  async (signal) => {
-    const response = await fetch(`/api/users/${id}`, { signal });
-    return response.json();
+  async (signal: AbortSignal): Promise<User> => {
+    const response = await fetch("https://example.com/api/users/u_1", { signal });
+
+    if (!response.ok) {
+      throw new Error("Could not load the user");
+    }
+
+    return (await response.json()) as User;
   },
-  { timeout: 5000, retry: 2 },
+  { timeout: 5000, retry: 2 }, // 5 seconds per attempt, up to 2 retries
 );
+
+if (user.isOk) {
+  println("User:", user.value.name);
+} else {
+  println("Could not load the user:", user.error);
+}
 ```
 
 ### SuperRunner
 
-`superRunner(config): SuperRunner<Value>` — manages several already-created `SuperPromise`s: sequence, parallel, or race. `start()` runs once.
+`superRunner(config): SuperRunner<Value>` runs several already-created `SuperPromise`s in
+sequence, in parallel (`all`), or as a race (`race`, with a `count`). `start()` runs once; later
+calls return the same result.
 
 ```ts
-const all = superRunner({ type: "all", runners: { a, b } });
-const result = await all.start();
+import { superPromise, superRunner, println } from "slang-ts";
+
+const profile = superPromise(async (): Promise<string> => {
+  return "Ada";
+});
+
+const orders = superPromise(async (): Promise<number> => {
+  return 3;
+});
+
+const dashboard = superRunner({ type: "all", runners: { profile, orders } });
+
+const loaded = await dashboard.start();
+
+if (loaded.isOk) {
+  println(loaded.value); // {"profile":"Ada","orders":3}
+}
 ```
 
 ### taskGroup
 
-`taskGroup(name, options?): TaskGroup` — shared concurrency limit and start spacing across tasks and runners. Retries wait for a new slot.
+`taskGroup(name, options?): TaskGroup` shares a concurrency limit and start spacing across tasks
+and runners. A retry waits for a new slot.
 
 ```ts
-const api = taskGroup("user-api", { concurrency: 3, throttle: 200 });
-const task = superPromise(fetchUsers, { group: api });
+import { taskGroup, superPromise, println } from "slang-ts";
+
+const api = taskGroup("user-api", { concurrency: 3, throttle: 200 }); // starts at least 200 ms apart
+
+const task = superPromise(async (): Promise<string> => {
+  return "Ada";
+}, { group: api });
+
+const user = await task;
+
+println(user.isOk); // true
 ```
 
 ### Signal / Channel
 
-`createSignal(): Signal` — a trigger that fires once (`fire()`), AbortSignal-compatible.
+`createSignal(): Signal` is a trigger which fires once (`fire()`). It works anywhere an
+`AbortSignal` does.
 
-`createChannel(): Channel` — in-process publish/subscribe. `subscribe(topic, handler)` returns an unsubscribe function.
+`createChannel(): Channel` is in-process publish/subscribe. `subscribe({ topic }, handler)`
+returns an unsubscribe function, `send({ topic, data })` runs every subscriber of the topic, and
+`when({ signal, topic, data })` sends once the signal fires.
+
+```ts
+import { createChannel, createSignal, println } from "slang-ts";
+
+const events = createChannel();
+
+const unsubscribe = events.subscribe({ topic: "order.placed" }, (event) => {
+  println("Order placed:", event.data); // Order placed: {"orderId":"o_42"}
+});
+
+events.send({ topic: "order.placed", data: { orderId: "o_42" } });
+
+const shutdown = createSignal();
+
+events.when({ signal: shutdown, topic: "order.placed", data: { orderId: "o_43" } });
+
+shutdown.fire(); // Order placed: {"orderId":"o_43"}
+
+unsubscribe();
+```
 
 ## Other utilities
 
-- `atom<T>(name): Atom<T>` — unique symbol with a readable description; matches in `matchAll` by description.
-- `to(target)` — convert between `Option`, `Atom`, `Result` (e.g. `option("ready").to("atom")`).
-- `pipe(value, ...fns)` — run `Result`-returning steps in order, stopping at the first failure.
-- `zip` / `zipWith` / `unzip` — combine parallel collections.
-- `memoized(fn)` — cache a function by argument identity.
-- `panic(message)` — throw immediately for unrecoverable states.
-- `println` — dev logging, silent in production unless `setEnvironment` routes it.
+- `atom<T>(name): Atom<T>`: a unique symbol with a readable description; `matchAll` matches it
+  by description.
+- `.to(target)`: converts between `Option`, `Atom` and `Result`, such as
+  `option("ready").to("atom")`. `_to(value, target)` is the same conversion as a function.
+- `Options(values, fallback?)`: the first usable value from a mix of raw values, `Option`s and
+  `Result`s, as `Ok`, or the fallback (`Err("No value!")` by default).
+- `pipe(initial, ...fns).run(options?)`: runs `Result` steps in order and stops at the first
+  `Err`. Each function receives the previous `Result`; `run` returns a promise.
+- `zip(inputs, options?)` / `zipWith` / `unzip`: rows of items at the same position across arrays.
+  Stops at the shortest input unless `fillValue` is set. Returns plain arrays, not a `Result`,
+  and throws on a non-array input unless `includeValues: true`.
+- `memoized(fn)`: stores results per argument list (primitives by value, objects by identity).
+  An async result is stored as its promise, so concurrent callers share one call; a rejected
+  promise is removed. A throw stores nothing. No size limit or expiry; `.clear()` empties it.
+- `createStepper(config?)`: a history of named steps with `next`, `prev`, `current` and `size`.
+- `panic(message)`: throws at once, for states the program cannot recover from.
+- `println`: development output, silent in production unless `setEnvironment({ printFn })`
+  routes it. Plain objects, arrays, sets and maps print as JSON.
+- `isFalsy(value)`: `true` for the values `option()` treats as `None`.
 
 ## Conventions agents should follow
 
-- Named params in an object for multi-arg functions, not positional.
+- Named params in an object for multi-argument functions, not positional.
 - No classes: use functions and plain objects.
 - Error categories are strings (`.category`), not numeric codes. Never call them "error codes."
-- `get` accepts a fallback; don't chain `.else()` after a `get` that already has one.
-- `.panic()` throws: only for unrecoverable states. Use `Result` / `.else()` for expected failures.
+- `get` accepts a fallback; finish it with `.panic()`, not a second `.else()` fallback.
+- `.panic()` throws: only for unrecoverable states. Use `Result` / `.else()` for expected
+  failures.
+- Write `if` / `else` with braces; avoid ternaries and `&&` for control flow in examples.
 - Zero runtime dependencies; ESM only.
 
 ## Package contents
 
-The published package ships `dist/` (JS + bundled declarations), `CHANGELOG.md`, and `skill/SKILL.md` (this file, for agents working with slang-ts).
+The published package ships `dist/` (JavaScript and bundled declarations), `CHANGELOG.md`, and
+`skill/SKILL.md` (this file, for agents working with slang-ts).