mini-effect 0.0.0

package/README.md

@@ -0,0 +1,190 @@
+# 🎯 mini-effect
+
+> _Because sometimes you want Effect, but like... mini._
+
+A delightfully tiny Effect system for TypeScript that packs a punch! ✨
+
+## 🤔 What's This?
+
+Ever looked at [Effect-TS](https://effect.website/) and thought "wow, that's amazing but also... a lot"? Same.
+
+**mini-effect** gives you the good stuff:
+
+- 🦥 **Lazy evaluation** - Nothing runs until you say so
+- 🔗 **Pipes** - Compose like a functional programming wizard
+- 🎭 **Generators** - Write async code that doesn't look like callback spaghetti
+- 🎣 **Error handling** - Catch 'em all (or just some of 'em)
+- ⚡ **Concurrency** - `all`, `race`, `any`, `allSettled` - the gang's all here
+- 🛑 **AbortSignal support** - Cancel everything! EVERYTHING!
+
+All in a package so small it practically fits in a tweet. 🐦
+
+## 📦 Installation
+
+```bash
+npm install mini-effect
+# or
+pnpm add mini-effect
+# or
+yarn add mini-effect
+```
+
+## 🚀 Quick Start
+
+```typescript
+import { fn, run, succeed, fail, gen, pipe } from "mini-effect";
+import { all } from "mini-effect/concurrency";
+
+// Create an effect (it's lazy - nothing happens yet!)
+const fetchTodo = fn(async (signal) => {
+  const res = await fetch("https://jsonplaceholder.typicode.com/todos/1", {
+    signal,
+  });
+  return res.json();
+});
+
+// Run it! 🏃‍♂️
+const todo = await run(fetchTodo);
+```
+
+## 🎮 The Fun Parts
+
+### Generators (a.k.a. "async/await but cooler")
+
+```typescript
+const program = gen(function* (signal) {
+  const a = yield* fn(() => Promise.resolve(1));
+  const b = yield* fn(() => Promise.resolve(2));
+  const c = yield* succeed(3);
+
+  return a + b + c; // 6!
+});
+
+await run(program); // 6
+```
+
+### Pipes (a.k.a. "look ma, no nesting!")
+
+```typescript
+const result = await run(
+  pipe(
+    succeed(5),
+    (n: number) => succeed(n * 2), // 10
+    (n: number) => succeed(n + 1), // 11
+    (n: number) => succeed(`Result: ${n}`), // "Result: 11"
+  ),
+);
+```
+
+### Error Handling (a.k.a. "try/catch grew up")
+
+```typescript
+import { catchClass, catchSome } from "mini-effect";
+
+class NotFoundError extends Error {
+  constructor(public id: number) {
+    super(`Not found: ${id}`);
+  }
+}
+
+const safeProgram = pipe(
+  fn(() => {
+    throw new NotFoundError(42);
+  }),
+  catchClass(NotFoundError, (err) => succeed(`Handled: ${err.id}`)),
+);
+
+await run(safeProgram); // "Handled: 42"
+```
+
+### Concurrency (a.k.a. "Promise.all's cooler cousin")
+
+```typescript
+import { all, race, any, allSettled } from "mini-effect/concurrency";
+
+// Run 'em all at once!
+const results = await run(
+  all([
+    fn(() => fetch("/api/users")),
+    fn(() => fetch("/api/posts")),
+    fn(() => fetch("/api/comments")),
+  ]),
+);
+
+// First one wins! 🏆
+const fastest = await run(
+  race([fn(() => fetchFromServer1()), fn(() => fetchFromServer2())]),
+);
+
+// First SUCCESS wins (failures don't count)
+const firstSuccess = await run(any([fn(() => tryThis()), fn(() => tryThat())]));
+
+// Get all results, even the failures 🤷
+const allResults = await run(
+  allSettled([succeed(1), fail(new Error("oops")), succeed(3)]),
+);
+```
+
+### Cancellation (a.k.a. "STOP THE PRESSES!")
+
+```typescript
+const controller = new AbortController();
+
+const longRunning = fn(async (signal) => {
+  // Check if we should bail
+  if (signal.aborted) {
+    throw new DOMException("Aborted!", "AbortError");
+  }
+
+  // Or pass it to fetch
+  const res = await fetch("/api/slow", { signal });
+  return res.json();
+});
+
+// Start it
+const promise = run(longRunning, controller.signal);
+
+// Actually, never mind! 🙅
+controller.abort();
+```
+
+## 🗺️ API at a Glance
+
+| Function                     | What it does                        |
+| ---------------------------- | ----------------------------------- |
+| `fn(thunk)`                  | Create an effect from a function    |
+| `succeed(value)`             | Create a successful effect          |
+| `fail(error)`                | Create a failed effect              |
+| `gen(generator)`             | Create an effect from a generator   |
+| `pipe(effect, ...steps)`     | Compose effects left-to-right       |
+| `run(effect, signal?)`       | Execute an effect (returns Promise) |
+| `catchSome(handler)`         | Catch errors selectively            |
+| `catchClass(Class, handler)` | Catch errors by type                |
+
+### Concurrency
+
+| Function              | What it does                 |
+| --------------------- | ---------------------------- |
+| `all(effects)`        | Run all, fail if any fails   |
+| `allSettled(effects)` | Run all, collect all results |
+| `any(effects)`        | First success wins           |
+| `race(effects)`       | First to finish wins         |
+
+## 🧠 Why Effects?
+
+Effects are like promises, but:
+
+1. **Lazy** - They don't run until you explicitly `run()` them
+2. **Composable** - Pipe and combine them without execution
+3. **Typed errors** - Your errors are part of the type signature
+4. **Cancellable** - AbortSignal support baked right in
+
+Think of an Effect as a _description_ of a computation, not the computation itself. You're building a recipe, not cooking the meal. When you're ready to eat, call `run()`! 🍳
+
+## 📄 License
+
+MIT © [Jacob Ebey](https://github.com/jacob-ebey)
+
+---
+
+_Built with ☕ and a healthy disregard for bundle size anxiety._

package/dist/concurrency.d.mts

@@ -0,0 +1,9 @@
+import { Effect, inferError, inferReturn } from "./mini-effect.mjs";
+
+//#region src/concurrency.d.ts
+declare const all: <const E extends Effect<any, any>[]>(values: E) => Effect<{ [K in keyof E]: inferReturn<E[K]> }, inferError<E[number]>>;
+declare const allSettled: <const E extends Effect<any, any>[]>(values: E) => Effect<{ [K in keyof E]: PromiseSettledResult<inferReturn<E[K]>> }, inferError<E[number]>>;
+declare const any: <const E extends Effect<any, any>[]>(values: E) => Effect<inferReturn<E[number]>, inferError<E[number]>>;
+declare const race: <const E extends Effect<any, any>[]>(values: E) => Effect<inferReturn<E[number]>, inferError<E[number]>>;
+//#endregion
+export { all, allSettled, any, race };

package/dist/concurrency.mjs

@@ -0,0 +1,24 @@
+import { _run as run, fn } from "./mini-effect.mjs";
+
+//#region src/concurrency.ts
+const localController = (signal) => {
+	let controller = new AbortController();
+	signal.addEventListener("abort", () => controller.abort(signal.reason));
+	return controller;
+};
+const promiseMethod = (method, values) => fn(async (signal) => {
+	let controller = localController(signal);
+	let localSignal = controller.signal;
+	try {
+		return await Promise[method](values.map((effect) => run(effect, localSignal)));
+	} finally {
+		if (!controller.signal.aborted) controller.abort();
+	}
+});
+const all = (values) => promiseMethod("all", values);
+const allSettled = (values) => promiseMethod("allSettled", values);
+const any = (values) => promiseMethod("any", values);
+const race = (values) => promiseMethod("race", values);
+
+//#endregion
+export { all, allSettled, any, race };

package/dist/mini-effect.d.mts

@@ -0,0 +1,37 @@
+//#region src/mini-effect.d.ts
+declare const EXCLUDE: unique symbol;
+declare const run: <T, E$1>(effect: Effect<T, E$1>, signal?: AbortSignal) => Promise<T>;
+declare const fn: <R$1, C = never>(thunk: Thunk<R$1>) => Effect<R$1, C>;
+declare const fail: <C>(cause: C) => Effect<never, C>;
+declare const succeed: <R$1>(result: R$1) => Effect<R$1, never>;
+declare const catchSome: <R$1 = any, E$1 = any, EE = never>(thunk: (cause: unknown) => Effect<R$1, E$1> | undefined) => WrapEffect<R$1, E$1, EE>;
+declare const catchClass: <T extends {
+  new (...args: any[]): any;
+}, E$1 extends Effect<any, any>>(type: T, thunk: (cause: T) => E$1) => Pipeable<any, inferReturn<E$1>, inferError<E$1>, T>;
+declare const gen: <T extends Effect<any, any>, TReturn, TNext>(thunk: (signal: AbortSignal) => Generator<T, TReturn, TNext>) => Effect<TReturn, inferError<T>>;
+declare const pipe: <F extends Effect<any, any>, P$1 extends [Pipeable<any, any, any>, ...Pipeable<any, any, any>[]]>(first: F, ...pipeable: PipeReturn<[F, ...P$1]> extends never ? never : P$1) => PipeReturn<[F, ...P$1]>;
+type Thunk<out R$1> = (signal: AbortSignal) => R$1 | PromiseLike<R$1>;
+type PipeableThunk<in I = any, out T = any, out E$1 = any> = (next: I) => Effect<T, E$1> | WrapEffect<T, E$1, any>;
+type Pipeable<I = any, T = any, E$1 = any, EE = any> = PipeableThunk<I, T, E$1> | Effect<T, E$1> | WrapEffect<T, E$1, EE>;
+type Effect<out T, out C> = {
+  [RUN]?(signal: AbortSignal): PromiseLike<T> | T;
+  [WRAP]?(cause: unknown): Effect<T, C> | undefined;
+  [Symbol.iterator](): Generator<Effect<T, C>, T, any>;
+  pipe<P$1 extends [Pipeable<any, any, any>, ...Pipeable<any, any, any>[]]>(...pipeable: P$1): PipeReturn<[Effect<T, C>, ...P$1]>;
+};
+type WrapEffect<T, C, EE> = {
+  [WRAP]?(cause: unknown): Effect<T, C> | undefined;
+  [EXCLUDE]?: EE;
+};
+type inferInput<T> = T extends PipeableThunk<infer I, any, any> ? I : never;
+type inferReturn<T> = T extends Pipeable<any, infer R, any> ? R : T extends Effect<infer R, any> ? R : never;
+type inferError<T> = T extends Pipeable<any, any, infer E> ? E : T extends Effect<any, infer E> ? E : never;
+type mergePipeable<A extends Pipeable, B extends Pipeable> = A extends Pipeable<any, infer A2, infer A3> ? B extends Pipeable<any, infer B2, infer B3, infer B4> ? Pipeable<any, A2 | B2, Exclude<A3 | B3, B4>, never> : A : B;
+type asEffect<P$1> = P$1 extends Pipeable<any, infer R, infer E> ? Effect<R, E> : never;
+type PipeReturn<F extends Pipeable[]> = asEffect<mergePipeable<CheckPipe<F, F[0]>, Effect<never, inferError<F[number]>>>>;
+type CheckPipe<F extends Pipeable[], L extends Pipeable> = F extends [Pipeable, WrapEffect<any, any, any>, ...infer R] ? R extends Pipeable[] ? CheckPipe<[mergePipeable<L, mergePipeable<F[0], F[1]>>, ...R], mergePipeable<L, mergePipeable<F[0], F[1]>>> : never : F extends [Pipeable, Pipeable, ...infer P] ? ExtendsStrict<inferReturn<F[0]>, inferInput<F[1]>> extends true ? P extends Pipeable[] ? CheckPipe<[F[1], ...P], F[1]> : never : never : F extends [WrapEffect<any, any, any>] ? mergePipeable<F[0], L> : F extends [Pipeable<any, infer R, infer E>] ? Effect<R, E> : never;
+type IsNever<T> = [T] extends [never] ? true : false;
+type IsAny<T> = 0 extends 1 & NoInfer<T> ? true : false;
+type ExtendsStrict<Left, Right> = IsAny<Left | Right> extends true ? true : IsNever<Left> extends true ? IsNever<Right> : [Left] extends [Right] ? true : false;
+//#endregion
+export { Effect, IsAny, Pipeable, PipeableThunk, Thunk, WrapEffect, run as _run, run, catchClass, catchSome, fail, fn, gen, inferError, inferInput, inferReturn, pipe, succeed };

package/dist/mini-effect.mjs

@@ -0,0 +1,75 @@
+//#region src/mini-effect.ts
+const SYMBOL = Symbol;
+const RUN = SYMBOL();
+const WRAP = SYMBOL();
+const DEFAULT_SIGNAL = new AbortController().signal;
+const isFunction = (value) => typeof value === "function";
+const quickYieldResult = (iterator, signal, ret) => {
+	ret = iterator.next(ret);
+	return ret.done ? ret.value : run(ret.value, signal).then((r) => quickYieldResult(iterator, signal, r));
+};
+const run = (effect, signal) => new Promise((resolve) => resolve(effect[RUN](signal ?? DEFAULT_SIGNAL)));
+const fn = (thunk) => new EffectImpl(thunk);
+const fail = (cause) => fn(() => {
+	throw cause;
+});
+const succeed = (result) => fn(() => result);
+const catchSome = (thunk) => new EffectImpl(void 0, thunk);
+const catchClass = (type, thunk) => catchSome((cause) => cause instanceof type ? thunk(cause) : void 0);
+const gen = (thunk) => fn((signal) => quickYieldResult(thunk(signal), signal));
+const wrapEffect = (pipe$1, onErr) => new EffectImpl(pipe$1[RUN], (cause) => pipe$1[WRAP]?.(cause) ?? onErr(cause));
+const pipe = (first, ...pipeable) => {
+	let run$1 = [];
+	let wrap = [];
+	let pipe$1;
+	let effect;
+	let next;
+	let handlePipeError = (cause) => {
+		for (pipe$1 of wrap) {
+			effect = pipe$1(cause);
+			if (effect) return effect;
+		}
+	};
+	let handler, wrappedFirst = wrapEffect(first, handlePipeError);
+	for (pipe$1 of pipeable) {
+		handler = pipe$1[WRAP];
+		if (isFunction(handler)) wrap.push(handler);
+		if (isFunction(pipe$1) || isFunction(pipe$1[RUN])) run$1.push(pipe$1);
+	}
+	return gen(function* () {
+		next = yield* wrappedFirst;
+		for (pipe$1 of run$1) {
+			if (isFunction(pipe$1)) pipe$1 = pipe$1(next);
+			if (isFunction(pipe$1[RUN])) next = yield* wrapEffect(pipe$1, handlePipeError);
+		}
+		return next;
+	});
+};
+var EffectImpl = class {
+	[RUN];
+	[WRAP];
+	constructor(run$1, catchSome$1) {
+		this[RUN] = catchSome$1 && run$1 ? (signal) => {
+			let res;
+			let handleError = (cause) => {
+				const recovery = catchSome$1(cause);
+				if (recovery) return recovery[RUN]?.(signal);
+				throw cause;
+			};
+			try {
+				res = run$1(signal);
+				return isFunction(res?.then) ? res.then(void 0, handleError) : res;
+			} catch (cause) {
+				return handleError(cause);
+			}
+		} : run$1;
+		this[WRAP] = catchSome$1;
+	}
+	*[SYMBOL.iterator]() {
+		return yield this;
+	}
+	pipe = (...pipeable) => pipe(this, ...pipeable);
+};
+
+//#endregion
+export { run as _run, run, catchClass, catchSome, fail, fn, gen, pipe, succeed };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "mini-effect",
+  "type": "module",
+  "version": "0.0.0",
+  "description": "A mini-effect library for TypeScript.",
+  "author": "Jacob Ebey <jacob.ebey@live.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/jacob-ebey/mini-effect#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jacob-ebey/mini-effect.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jacob-ebey/mini-effect/issues"
+  },
+  "exports": {
+    "./concurrency": "./dist/concurrency.mjs",
+    "./mini-effect": "./dist/mini-effect.mjs",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "tsdown": "^0.18.4",
+    "typescript": "^5.9.3"
+  }
+}