pure-effect 0.1.1 → 0.2.0

package/README.md

@@ -4,6 +4,8 @@
 
 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.
+
 ## Installation
 
 ```bash
@@ -28,13 +30,13 @@ const validateRegistration = (input) => {
 const findUser = (email) => {
     const cmdFindUser = () => db.findUser(email); // The work to do later
     const next = (user) => Success(user); // Wrap result in Success
-    return Command(cmd, next);
+    return Command(cmdFindUser, next);
 };
 
 const saveUser = (input) => {
     const cmdSaveUser = () => db.saveUser(input);
     const next = (saved) => Success(saved);
-    return Command(cmd, next);
+    return Command(cmdSaveUser, next);
 };
 
 const ensureEmailAvailable = (user) => {
@@ -52,8 +54,6 @@ const registerUserFlow = (input) =>
 
 // The Imperative Shell
 async function registerUser() {
-    const input = { email: 'new@test.com', password: 'password123' };
-
     // logic is just a data structure until we pass it to runEffect
     const logic = registerUserFlow(input);
 

package/index.js

@@ -1,7 +1,50 @@
+// @ts-check
+
+/** @typedef {{ type: 'Success', value: any }} SuccessState */
+/** @typedef {{ type: 'Failure', error: any }} FailureState */
+/**
+ * @typedef {{
+ *   type: 'Command',
+ *   cmd: () => Promise<any>|any,
+ *   next: (result: any) => Effect
+ * }} CommandState
+ */
+
+/**
+ * The Union type for all possible states
+ * @typedef {SuccessState | FailureState | CommandState} Effect
+ */
+
+/**
+ * Represents a successful computation
+ * @param {any} value - The result value
+ * @returns {SuccessState}
+ */
 const Success = (value) => ({ type: 'Success', value });
+
+/**
+ * Represents a failed computation. Stops the pipeline execution
+ * @param {any} error - The error reason (string, Error object, etc).
+ * @returns {FailureState}
+ */
 const Failure = (error) => ({ type: 'Failure', error });
+
+/**
+ * Represents a side effect to be executed later
+ * @param {() => Promise<any>|any} cmd - The side-effect function to execute
+ * @param {(result: any) => Effect} next - A function that receives the result of `cmd` and returns the next Effect
+ * @returns {CommandState}
+ */
 const Command = (cmd, next) => ({ type: 'Command', cmd, next });
 
+/**
+ * Connects an Effect to the next function in the pipeline.
+ * Handles the branching logic for Success, Failure, and Command.
+ *
+ * @param {Effect} effect - The current Effect object
+ * @param {(value: any) => Effect} fn - The next function to run if the current effect is a Success
+ * @returns {Effect} The composed Effect
+ */
 const chain = (effect, fn) => {
     switch (effect.type) {
         case 'Success':
@@ -9,15 +52,29 @@ const chain = (effect, fn) => {
         case 'Failure':
             return effect;
         case 'Command':
-            const next = (result) => chain(effect.next(result), fn);
+            const next = (/** @type {Effect} */ result) => chain(effect.next(result), fn);
             return Command(effect.cmd, next);
     }
 };
 
+/**
+ * Composes a list of functions into a single Effect pipeline.
+ * Each function receives the output of the previous one.
+ *
+ * @param {...(input: any) => Effect} fns - Functions that return Success, Failure, or Command.
+ * @returns {(start: any) => Effect} A function that accepts an initial input and returns the final Effect tree.
+ */
 const effectPipe = (...fns) => {
     return (start) => fns.reduce(chain, Success(start));
 };
 
+/**
+ * The Interpreter
+ * Iterates through the Effect tree, executing Commands and handling async flow.
+ *
+ * @param {Effect} effect - The Effect tree returned by a pipeline
+ * @returns {Promise<SuccessState | FailureState>}
+ */
 async function runEffect(effect) {
     while (effect.type === 'Command') {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pure-effect",
-    "version": "0.1.1",
+    "version": "0.2.0",
     "description": "A tiny, zero-dependency effect system for writing pure, testable JavaScript without mocks.",
     "type": "module",
     "exports": "./index.js",
@@ -11,6 +11,8 @@
     "homepage": "https://github.com/aycangulez/pure-effect",
     "license": "MIT",
     "devDependencies": {
+        "@types/mocha": "^10.0.10",
+        "@types/node": "^24.10.1",
         "mocha": "^11.7.5"
     }
 }

package/test/all.js

@@ -1,19 +1,23 @@
+// @ts-check
+
 import { strict as assert } from 'assert';
 import { Success, Failure, Command, effectPipe, runEffect } from '../index.js';
 
+/** @typedef {{id?: number, email: string, password: string}} User */
+
 const db = {
     users: new Map(),
-    async findUserByEmail(email) {
+    async findUserByEmail(/** @type string */ email) {
         return this.users.get(email) || null;
     },
-    async saveUser(user) {
-        const u = { id: Date.now(), ...user };
+    async saveUser(/** @type {User} */ user) {
+        const u = { ...user, id: Date.now() };
         this.users.set(user.email, u);
         return u;
     },
 };
 
-function validateRegistration(input) {
+function validateRegistration(/** @type {User} */ input) {
     const { email, password } = input;
     if (!email?.includes('@')) {
         return Failure('Invalid email format.');
@@ -24,26 +28,26 @@ function validateRegistration(input) {
     return Success(input);
 }
 
-function findUserByEmail(email) {
+function findUserByEmail(/** @type string */ email) {
     const cmdFindUser = () => db.findUserByEmail(email);
-    const next = (foundUser) => Success(foundUser);
+    const next = (/** @type {User} */ foundUser) => Success(foundUser);
     return Command(cmdFindUser, next);
 }
 
-function ensureEmailIsAvailable(foundUser) {
+function ensureEmailIsAvailable(/** @type {User} */ foundUser) {
     return foundUser ? Failure('Email already in use.') : Success(true);
 }
 
-function saveUser(input) {
+function saveUser(/** @type {User} */ input) {
     const { email, password } = input;
     const hashedPassword = `hashed_${password}`;
     const userToSave = { email, password: hashedPassword };
     const cmdSaveUser = () => db.saveUser(userToSave);
-    const next = (savedUser) => Success(savedUser);
+    const next = (/** @type {User} */ savedUser) => Success(savedUser);
     return Command(cmdSaveUser, next);
 }
 
-const registerUserFlow = (input) =>
+const registerUserFlow = (/** @type {User} */ input) =>
     effectPipe(
         validateRegistration,
         () => findUserByEmail(input.email),
@@ -51,7 +55,7 @@ const registerUserFlow = (input) =>
         () => saveUser(input)
     )(input);
 
-async function registerUser(input) {
+async function registerUser(/** @type {User} */ input) {
     return await runEffect(registerUserFlow(input));
 }