slang-ts 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,11 +1,10 @@
 # Changelog
 
-Everything notable in `slang-ts`, grouped by area. No release diary — just what's here.
+Everything notable in `slang-ts`, grouped by area. No release diary: just what's here.
 
 ## Results and flow
 
-- `Ok(value, message?)` keeps an optional success message on the result, like text you want to show
-  the user. Results without one have no `message` property.
+- `Ok(value, message?)` keeps an optional success message on the result. Results without one have no `message` property.
 - `SafeTry` unwraps Option and Atom values into one result. A Result never nests inside another
   Result, and plain object properties and array elements stay unchanged.
 

package/README.md

@@ -39,7 +39,7 @@ if (result.isOk) {
 }
 ```
 
-`println` is optional — it's a small development logger.
+`println` is optional: it's a small development logger.
 
 ## Imports
 
@@ -168,7 +168,7 @@ Full detail: [SafeTry][safe-try] and [Result][result].
 ### Call an API with a timeout and retries: SuperPromise
 
 Your function gets an `AbortSignal`. `timeout` aborts an attempt, `retry` runs it again after an
-ordinary failure, and you get back `Ok` or `Err` — so no `try`/`catch` around the await.
+ordinary failure, and you get back `Ok` or `Err`: so no `try`/`catch` around the await.
 
 ```ts
 import { superPromise, println } from "slang-ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slang-ts",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Functional programming utilities for TypeScript: Option, Result, SafeTry, pattern matching, async control, and data helpers",
   "type": "module",
   "main": "dist/index.js",

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 # 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.
+This skill tells AI agents how to work with slang-ts: its APIs, patterns, and conventions so agents can write correct TypeScript against it.
 
 ## What slang-ts is
 
@@ -16,7 +16,9 @@ import { option, Ok, Err, match, superPromise, list } from "slang-ts";
 
 ### Option
 
-`option(value)` → `Some(value)` or `None`. `0` and `false` count as present; `null`, `undefined`, `""`, `NaN`, and `Infinity` are `None`.
+`option<T>(value): Option<T>` — wraps a value that may or may not be there.
+
+`0` and `false` count as present; `null`, `undefined`, `""`, `NaN`, and `Infinity` are `None`.
 
 ```ts
 const port = option(process.env.PORT).unwrap().else(3000);
@@ -26,7 +28,16 @@ Never read `.value` on `None`. Check `.isSome` / `.isNone` first, or use `.unwra
 
 ### Result
 
-`Ok(value, message?)` / `Err(error)`. Failures travel as values, not throws.
+`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
+```
+
+`Err(error, raw?)` keeps the original cause on the non-enumerable `.raw` for logs; `.error` stays human-readable.
+
+Branch with `if (result.isOk) { ... } else { ... }`. Finish chains with `.unwrap().else(fallback)` or `.unwrap().panic(message?)`.
 
 ```ts
 function divide(a: number, b: number): Result<number, string> {
@@ -34,15 +45,17 @@ function divide(a: number, b: number): Result<number, string> {
 }
 ```
 
-Branch with `if (result.isOk) { ... } else { ... }`. Finish chains with `.unwrap().else(fallback)` or `.unwrap().panic(message?)`.
-
-`Err(error, raw?)` keeps the original cause on the non-enumerable `.raw` for logs; `.error` stays human-readable.
+`Result` never nests inside another `Result` — `Ok(Ok(x))` and `Ok(Err(x))` won't compile.
 
 ### match / matchAll
 
-`match(result, { Ok: ..., Err: ... })` is exhaustive — TypeScript requires both cases.
+`match(value, patterns)` — exhaustive pattern matching for `Option` and `Result`. TypeScript requires both cases.
 
-`matchAll` is for strings, numbers, booleans, symbols, and `Atom`s. It always needs a `_` fallback since there's no finite set of cases.
+```ts
+match(result, { Ok: (v) => ..., Err: (e) => ... });
+```
+
+`matchAll(value, patterns)` — matching for strings, numbers, booleans, symbols, and `Atom`s. Always needs a `_` fallback.
 
 ```ts
 const message = matchAll(failed.category, {
@@ -65,31 +78,42 @@ 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.
-- `.panic()` throws; once you panic, no custom user message is read afterward.
+- `.panic()` throws; once you panic, no custom message is read afterward.
 
 ### list
 
-Strict indexed arrays with `get`, `take`, `skip`, `range`, `chunk`, `count`, `prune`. Bounds are strict — out-of-range fails instead of clamping.
+`list<T>(input): ListChain<T>` — strict indexed arrays with explicit bounds. Out-of-range fails instead of clamping.
 
 ```ts
 const page = list(users).range(start, end).else([]);
 ```
 
+Methods: `get`, `take`, `skip`, `range`, `chunk`, `count`, `prune`.
+
 ### struct
 
-Safe record access and shaping. `get`, `pick`, `omit`, `merge`, `countBy`, `keyBy`.
+`struct<T>(input): StructChain<T>` — safe record access and shaping.
+
+Methods: `get`, `pick`, `omit`, `merge`, `countBy`, `keyBy`, `prune`.
 
 ```ts
 const port = struct(config).get(["server", "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`.
+
 ### sets
 
-Membership and set algebra. `has`, `unique`, `union`, `intersection`, `difference`. Objects compare by identity; primitives by value.
+`sets<T>(input): SetsChain<T>` — membership and set operations.
+
+Methods: `has`, `unique`, `union`, `intersection`, `difference`. Objects compare by identity; primitives by value.
 
 ### Ok.iterate
 
-Lazy pipelines over a successful `Ok`. `map`, `filter`, `flatMap`, `take`, `drop`, `chunk`, then `reduce`, `count`, or `toArray`.
+`Ok<T>(value).iterate(): IterateChain<T>` — lazy pipelines over a successful `Ok`.
+
+Methods: `map`, `filter`, `flatMap`, `take`, `drop`, `chunk`, `reduce`, `count`, `toArray`.
 
 ```ts
 const names = Ok(users)
@@ -104,7 +128,9 @@ const names = Ok(users)
 
 ### SuperPromise
 
-One async operation with timeout, retry, cancellation, and `Ok`/`Err` settlement. Your function gets an `AbortSignal`.
+`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`.
+
+Options: `defer`, `delay`, `timeout`, `retry`, `retryUntil`, `group`.
 
 ```ts
 const user = await superPromise(
@@ -118,7 +144,7 @@ const user = await superPromise(
 
 ### SuperRunner
 
-Run `SuperPromise`s in sequence, parallel, or race. `start()` runs once.
+`superRunner(config): SuperRunner<Value>` — manages several already-created `SuperPromise`s: sequence, parallel, or race. `start()` runs once.
 
 ```ts
 const all = superRunner({ type: "all", runners: { a, b } });
@@ -127,7 +153,7 @@ const result = await all.start();
 
 ### taskGroup
 
-Shared concurrency limit and start spacing across tasks. Retries wait for a new slot.
+`taskGroup(name, options?): TaskGroup` — shared concurrency limit and start spacing across tasks and runners. Retries wait for a new slot.
 
 ```ts
 const api = taskGroup("user-api", { concurrency: 3, throttle: 200 });
@@ -136,27 +162,27 @@ const task = superPromise(fetchUsers, { group: api });
 
 ### Signal / Channel
 
-`createSignal()` — a trigger that fires once (`fire()`), AbortSignal-compatible.
+`createSignal(): Signal` — a trigger that fires once (`fire()`), AbortSignal-compatible.
 
-`createChannel()` — in-process publish/subscribe. `subscribe(topic, handler)` returns an unsubscribe function.
+`createChannel(): Channel` — in-process publish/subscribe. `subscribe(topic, handler)` returns an unsubscribe function.
 
 ## Other utilities
 
-- `atom("name")` — unique symbol with a readable description; matches in `matchAll` by description.
-- `to` — convert between `Option`, `Atom`, `Result` (e.g. `option("ready").to("atom")`).
-- `pipe` — run `Result`-returning steps in order, stopping at the first failure.
+- `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` — cache a function by argument identity.
+- `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.
 
 ## Conventions agents should follow
 
 - Named params in an object for multi-arg functions, not positional.
-- No classes — use functions and plain objects.
+- 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.
+- `.panic()` throws: only for unrecoverable states. Use `Result` / `.else()` for expected failures.
 - Zero runtime dependencies; ESM only.
 
 ## Package contents