pure-effect 0.4.0 → 0.5.0

package/CLAUDE.md

@@ -0,0 +1,59 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+npm test                                          # run all tests
+npx mocha test/all.js --grep "pattern"            # run a single test by name
+```
+
+No build or lint step — the library ships as plain ES modules with no transpilation.
+
+## Architecture
+
+**pure-effect** is a zero-dependency effect system for JavaScript implementing the "Functional Core, Imperative Shell" pattern. Business logic returns plain data structures instead of executing side effects, enabling testing without mocks.
+
+### Core abstractions (all in `index.js`)
+
+| Export | Shape | Purpose |
+|--------|-------|---------|
+| `Success(value)` | `{ type: 'Success', value }` | Wraps a successful result |
+| `Failure(error, initialInput)` | `{ type: 'Failure', error, initialInput }` | Short-circuits the pipeline |
+| `Command(cmdFn, nextFn, meta)` | `{ type: 'Command', cmd, next, meta }` | Defers a side effect for the interpreter |
+| `effectPipe(...fns)` | — | Composes functions into a sequential pipeline via `chain` |
+| `runEffect(effect, context)` | async | Interpreter: traverses the effect tree, executes Commands |
+| `configureEffect(options)` | — | Injects telemetry hooks (`onStep`, `onRun`, `onBeforeCommand`) |
+
+### Data flow
+
+```
+effectPipe(f1, f2, f3)(input)
+  → returns tree of Success / Failure / Command values
+
+runEffect(tree, context)
+  → executes Commands async, passes results into next(), repeats
+  → resolves to final Success or Failure
+```
+
+The `chain` combinator (internal) drives composition: `Success` passes its value to the next function, `Failure` short-circuits, `Command` defers execution. `runEffect` loops through the tree with a `while` loop rather than recursion.
+
+`configureEffect` hooks:
+- `onStep` — fires on every Command execution; wraps the `cmd` call (use for per-command tracing)
+- `onRun` — fires once per `runEffect` call; wraps the whole workflow (use for top-level spans); receives `context.flowName` as the third argument
+- `onBeforeCommand` — intercepts each Command before execution; receives the Command and the `context` passed to `runEffect`
+
+### TypeScript
+
+Full generic type declarations are in `index.d.ts` and referenced via the `types` field in `package.json`. Type-level tests live in `test/types.test-d.ts` and run via `tsd` as part of `npm test`.
+
+### Observability
+
+`opentelemetry-example.js` shows how to wire OpenTelemetry spans into `configureEffect`'s hooks — it is reference code, not part of the library.
+
+### Tests
+
+`test/all.js` contains all runtime tests and uses a user-registration domain as the running example. Tests assert on the *returned data structures* (Commands, Failures) rather than on side effects, which is the core usage pattern to preserve.
+
+`test/types.test-d.ts` contains type-level tests using `tsd`, verifying that generic type parameters flow correctly through `effectPipe` and `runEffect`.

package/README.md

@@ -4,7 +4,7 @@
 
 It implements the "Functional Core, Imperative Shell" pattern, allowing you to decouple your business logic from external side effects like database calls or API requests. Instead of executing side effects immediately, your functions return Commands which are executed later by an interpreter.
 
-**Pure Effect** comes with JSDoc type annotations, so it can be used with TypeScript as well.
+**Pure Effect** ships with JSDoc type annotations for JavaScript users and a bundled `index.d.ts` declaration file with full generic types for TypeScript users.
 
 ## Installation
 

package/index.d.ts

@@ -0,0 +1,127 @@
+export type SuccessState<T> = {
+    type: 'Success';
+    value: T;
+    initialInput?: unknown;
+};
+
+export type FailureState<E = unknown> = {
+    type: 'Failure';
+    error: E;
+    initialInput?: unknown;
+};
+
+export type CommandState<R, T, E = unknown> = {
+    type: 'Command';
+    cmd: () => Promise<R> | R;
+    next: (result: R) => Effect<T, E>;
+    meta?: unknown;
+    initialInput?: unknown;
+};
+
+export type Effect<T, E = unknown> =
+    | SuccessState<T>
+    | FailureState<E>
+    | CommandState<any, T, E>;
+
+export declare function Success<T>(value: T): SuccessState<T>;
+
+export declare function Failure<E = unknown>(
+    error: E,
+    initialInput?: unknown
+): FailureState<E>;
+
+export declare function Command<R, T, E = unknown>(
+    cmd: () => Promise<R> | R,
+    next: (result: R) => Effect<T, E>,
+    meta?: unknown
+): CommandState<R, T, E>;
+
+export declare function effectPipe<A, B, E = unknown>(
+    f1: (a: A) => Effect<B, E>
+): (start: A) => Effect<B, E>;
+
+export declare function effectPipe<A, B, C, E = unknown>(
+    f1: (a: A) => Effect<B, E>,
+    f2: (b: B) => Effect<C, E>
+): (start: A) => Effect<C, E>;
+
+export declare function effectPipe<A, B, C, D, E = unknown>(
+    f1: (a: A) => Effect<B, E>,
+    f2: (b: B) => Effect<C, E>,
+    f3: (c: C) => Effect<D, E>
+): (start: A) => Effect<D, E>;
+
+export declare function effectPipe<A, B, C, D, F, E = unknown>(
+    f1: (a: A) => Effect<B, E>,
+    f2: (b: B) => Effect<C, E>,
+    f3: (c: C) => Effect<D, E>,
+    f4: (d: D) => Effect<F, E>
+): (start: A) => Effect<F, E>;
+
+export declare function effectPipe<A, B, C, D, F, G, E = unknown>(
+    f1: (a: A) => Effect<B, E>,
+    f2: (b: B) => Effect<C, E>,
+    f3: (c: C) => Effect<D, E>,
+    f4: (d: D) => Effect<F, E>,
+    f5: (f: F) => Effect<G, E>
+): (start: A) => Effect<G, E>;
+
+export declare function effectPipe<A, B, C, D, F, G, H, E = unknown>(
+    f1: (a: A) => Effect<B, E>,
+    f2: (b: B) => Effect<C, E>,
+    f3: (c: C) => Effect<D, E>,
+    f4: (d: D) => Effect<F, E>,
+    f5: (f: F) => Effect<G, E>,
+    f6: (g: G) => Effect<H, E>
+): (start: A) => Effect<H, E>;
+
+export declare function effectPipe<A, B, C, D, F, G, H, I, E = unknown>(
+    f1: (a: A) => Effect<B, E>,
+    f2: (b: B) => Effect<C, E>,
+    f3: (c: C) => Effect<D, E>,
+    f4: (d: D) => Effect<F, E>,
+    f5: (f: F) => Effect<G, E>,
+    f6: (g: G) => Effect<H, E>,
+    f7: (h: H) => Effect<I, E>
+): (start: A) => Effect<I, E>;
+
+export declare function effectPipe<A, B, C, D, F, G, H, I, J, E = unknown>(
+    f1: (a: A) => Effect<B, E>,
+    f2: (b: B) => Effect<C, E>,
+    f3: (c: C) => Effect<D, E>,
+    f4: (d: D) => Effect<F, E>,
+    f5: (f: F) => Effect<G, E>,
+    f6: (g: G) => Effect<H, E>,
+    f7: (h: H) => Effect<I, E>,
+    f8: (i: I) => Effect<J, E>
+): (start: A) => Effect<J, E>;
+
+export declare function runEffect<T, E = unknown>(
+    effect: Effect<T, E>,
+    context?: unknown
+): Promise<SuccessState<T> | FailureState<E>>;
+
+export type StepRunner = (
+    name: string,
+    type: string,
+    op: () => Promise<unknown>
+) => Promise<unknown>;
+
+export type RunWrapper = (
+    effect: Effect<unknown>,
+    op: () => Promise<SuccessState<unknown> | FailureState<unknown>>,
+    flowName?: string
+) => Promise<SuccessState<unknown> | FailureState<unknown>>;
+
+export type CommandInterceptor = (
+    command: CommandState<unknown, unknown>,
+    context?: any
+) => Promise<void>;
+
+export interface EffectConfiguration {
+    onStep?: StepRunner;
+    onRun?: RunWrapper;
+    onBeforeCommand?: CommandInterceptor;
+}
+
+export declare function configureEffect(options: EffectConfiguration): void;

package/package.json

@@ -1,11 +1,15 @@
 {
     "name": "pure-effect",
-    "version": "0.4.0",
-    "description": "A tiny, zero-dependency effect system for writing pure, testable JavaScript without mocks.",
+    "version": "0.5.0",
+    "description": "A tiny, zero-dependency effect system for writing pure, testable JavaScript/TypeScript without mocks.",
     "type": "module",
     "exports": "./index.js",
+    "types": "./index.d.ts",
     "scripts": {
-        "test": "mocha"
+        "test": "mocha && tsd"
+    },
+    "tsd": {
+        "directory": "test"
     },
     "author": "Aycan Gulez",
     "homepage": "https://github.com/aycangulez/pure-effect",
@@ -14,6 +18,7 @@
         "@opentelemetry/sdk-node": "^0.211.0",
         "@types/mocha": "^10.0.10",
         "@types/node": "^24.10.1",
-        "mocha": "^11.7.5"
+        "mocha": "^11.7.5",
+        "tsd": "^0.33.0"
     }
 }

package/test/types.test-d.ts

@@ -0,0 +1,53 @@
+import { expectType, expectError } from 'tsd';
+import { Success, Failure, Command, effectPipe, runEffect } from '../index.js';
+import type { SuccessState, FailureState, CommandState, Effect } from '../index.js';
+
+interface User { email: string; password: string; }
+interface SavedUser { id: number; email: string; }
+
+// --- Success ---
+
+const s = Success(42);
+expectType<SuccessState<number>>(s);
+expectError(Success()); // missing argument
+
+// --- Failure ---
+
+const f = Failure('oops');
+expectType<FailureState<string>>(f);
+
+// --- Command ---
+
+const cmd = Command(
+    async () => ({ id: 1, email: 'a@b.com' } as SavedUser),
+    (saved) => { expectType<SavedUser>(saved); return Success(saved); }
+);
+expectType<CommandState<SavedUser, SavedUser, unknown>>(cmd);
+
+// --- effectPipe type propagation ---
+
+const step1 = (input: User) => Success(input);
+const step2 = (user: User) => Command(async () => ({ id: 1, ...user } as SavedUser), (s) => Success(s));
+
+const flow = effectPipe(step1, step2);
+expectType<Effect<SavedUser>>(flow({ email: 'a@b.com', password: 'secret123' }));
+expectError(flow({ email: 'a@b.com' })); // missing password
+
+// --- runEffect return type ---
+
+const result = await runEffect(flow({ email: 'a@b.com', password: 'secret123' }));
+expectType<SuccessState<SavedUser> | FailureState<unknown>>(result);
+
+// --- discriminated union narrowing ---
+
+if (result.type === 'Success') {
+    expectType<SavedUser>(result.value);
+} else {
+    expectType<unknown>(result.error);
+}
+
+// --- Failure error type flows through runEffect ---
+
+const failFlow = effectPipe((input: User): Effect<User, string> => Failure<string>('bad'));
+const failResult = await runEffect(failFlow({ email: 'a@b.com', password: 'x' }));
+expectType<SuccessState<User> | FailureState<string>>(failResult);