@satoshibits/functional 1.0.2

package/dist/pipeline.mjs

@@ -0,0 +1,460 @@
+"use strict";
+/**
+ * @module pipeline
+ * @description A fluent, chainable API for function composition that maintains state.
+ * Unlike pure functional composition, Pipeline provides an object-oriented
+ * interface for building complex data transformations with method chaining.
+ * Combines the benefits of functional programming with familiar OOP patterns.
+ *
+ * @example
+ * ```typescript
+ * import { Pipeline } from './pipeline.mts';
+ *
+ * // basic transformations
+ * const result = Pipeline.of(5)
+ *   .map(x => x * 2)
+ *   .map(x => x + 1)
+ *   .value();
+ * // => 11
+ *
+ * // async transformations
+ * const userData = await Pipeline.of('user123')
+ *   .mapAsync(id => fetchUser(id))
+ *   .then(p => p.map(user => user.email))
+ *   .then(p => p.value());
+ *
+ * // error handling
+ * const validated = Pipeline.of(input)
+ *   .filter(x => x > 0, 'Must be positive')
+ *   .map(result => result.success ? result.data * 2 : result)
+ *   .value();
+ * ```
+ *
+ * @category Core
+ * @since 2025-07-03
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+/**
+ * Pipeline builder for fluent function composition.
+ * Provides a stateful, chainable interface for applying transformations
+ * to a value. Unlike pure functional composition, Pipeline maintains
+ * internal state and offers a familiar object-oriented API.
+ *
+ * @category Core
+ * @example
+ * // Basic transformation pipeline
+ * const result = Pipeline.of(5)
+ *   .map(x => x * 2)
+ *   .map(x => x + 1)
+ *   .map(x => `Result: ${x}`)
+ *   .value();
+ * // => "Result: 11"
+ *
+ * @example
+ * // Complex data transformation
+ * const userPipeline = Pipeline.of({ name: 'john doe', age: 30 })
+ *   .map(user => ({ ...user, name: user.name.toUpperCase() }))
+ *   .tap(user => console.log('Processing:', user.name))
+ *   .map(user => ({ ...user, ageGroup: user.age >= 18 ? 'adult' : 'minor' }))
+ *   .value();
+ * // => { name: 'JOHN DOE', age: 30, ageGroup: 'adult' }
+ *
+ * @example
+ * // Error handling with filter
+ * const processNumber = (n: number) => Pipeline.of(n)
+ *   .filter(x => x > 0, 'Number must be positive')
+ *   .map(result => {
+ *     if (!result.success) return result;
+ *     return { success: true as const, data: Math.sqrt(result.data) };
+ *   })
+ *   .value();
+ *
+ * processNumber(16);  // => { success: true, data: 4 }
+ * processNumber(-4);  // => { success: false, error: 'Number must be positive' }
+ */
+var Pipeline = /** @class */ (function () {
+    /**
+     * Creates a new Pipeline instance with the given value.
+     * Use Pipeline.of() for a more functional approach.
+     *
+     * @private
+     */
+    function Pipeline(_value) {
+        this._value = _value;
+    }
+    /**
+     * Apply a synchronous transformation.
+     * @description Transforms the current value using the provided function.
+     * Returns a new Pipeline containing the transformed value.
+     *
+     * @template U - The type of the transformed value
+     * @param {function(T): U} fn - Function to transform the value
+     * @returns {Pipeline<U>} A new Pipeline with the transformed value
+     *
+     * @category Transformation
+     * @example
+     * const doubled = Pipeline.of(5)
+     *   .map(x => x * 2)
+     *   .value();
+     * // => 10
+     *
+     * @example
+     * // Chaining transformations
+     * const result = Pipeline.of('hello')
+     *   .map(s => s.toUpperCase())
+     *   .map(s => s.split(''))
+     *   .map(arr => arr.reverse())
+     *   .map(arr => arr.join(''))
+     *   .value();
+     * // => 'OLLEH'
+     *
+     * @see mapAsync - Transform with async function
+     * @see flatMap - Transform and flatten
+     * @since 2025-07-03
+     */
+    Pipeline.prototype.map = function (fn) {
+        return new Pipeline(fn(this._value));
+    };
+    /**
+     * Apply an asynchronous transformation.
+     * @description Transforms the current value using an async function.
+     * Returns a Promise that resolves to a new Pipeline with the transformed value.
+     *
+     * @template U - The type of the transformed value
+     * @param {function(T): Promise<U>} fn - Async function to transform the value
+     * @returns {Promise<Pipeline<U>>} Promise resolving to a new Pipeline
+     *
+     * @category Async
+     * @example
+     * const userData = await Pipeline.of(123)
+     *   .mapAsync(async (id) => {
+     *     const response = await fetch(`/api/users/${id}`);
+     *     return response.json();
+     *   })
+     *   .then(p => p.value());
+     *
+     * @example
+     * // Chaining async operations
+     * const result = await Pipeline.of('user@example.com')
+     *   .mapAsync(email => fetchUserByEmail(email))
+     *   .then(p => p.mapAsync(user => fetchUserPosts(user.id)))
+     *   .then(p => p.map(posts => posts.length))
+     *   .then(p => p.value());
+     * // => number of posts
+     */
+    Pipeline.prototype.mapAsync = function (fn) {
+        return __awaiter(this, void 0, void 0, function () {
+            var result;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, fn(this._value)];
+                    case 1:
+                        result = _a.sent();
+                        return [2 /*return*/, new Pipeline(result)];
+                }
+            });
+        });
+    };
+    /**
+     * Apply a transformation that might fail.
+     * Handles functions that return Result types.
+     *
+     * @category Error Handling
+     * @example
+     * const safeDivide = (n: number, divisor: number) =>
+     *   divisor === 0
+     *     ? { success: false as const, error: 'Division by zero' }
+     *     : { success: true as const, data: n / divisor };
+     *
+     * const result = Pipeline.of(10)
+     *   .flatMap(n => safeDivide(n, 2))
+     *   .value();
+     * // => { success: true, data: 5 }
+     *
+     * @example
+     * // Chaining fallible operations
+     * const process = Pipeline.of('{"name": "John"}')
+     *   .flatMap(str => {
+     *     try {
+     *       return { success: true as const, data: JSON.parse(str) };
+     *     } catch {
+     *       return { success: false as const, error: 'Invalid JSON' };
+     *     }
+     *   })
+     *   .map(result => {
+     *     if (!result.success) return result;
+     *     return { success: true as const, data: result.data.name };
+     *   })
+     *   .value();
+     * // => { success: true, data: 'John' }
+     */
+    Pipeline.prototype.flatMap = function (fn) {
+        return new Pipeline(fn(this._value));
+    };
+    /**
+     * Filter the pipeline based on a predicate.
+     * Converts the value to a Result type based on the predicate.
+     *
+     * @category Filtering
+     * @example
+     * const result = Pipeline.of(5)
+     *   .filter(x => x > 0, 'Must be positive')
+     *   .value();
+     * // => { success: true, data: 5 }
+     *
+     * @example
+     * // Validation pipeline
+     * const validateUser = (user: any) => Pipeline.of(user)
+     *   .filter(u => u.name, 'Name is required')
+     *   .map(result => {
+     *     if (!result.success) return result;
+     *     return Pipeline.of(result.data)
+     *       .filter(u => u.age >= 18, 'Must be 18 or older')
+     *       .value();
+     *   })
+     *   .value();
+     *
+     * validateUser({ name: 'John', age: 20 }); // => { success: true, data: {...} }
+     * validateUser({ name: '', age: 20 });     // => { success: false, error: 'Name is required' }
+     */
+    Pipeline.prototype.filter = function (predicate, error) {
+        if (predicate(this._value)) {
+            return new Pipeline({ success: true, data: this._value });
+        }
+        return new Pipeline({ success: false, error: error });
+    };
+    /**
+     * Execute a side effect without changing the value.
+     * Useful for logging, debugging, or triggering external actions.
+     *
+     * @category Side Effects
+     * @example
+     * const result = Pipeline.of([1, 2, 3, 4, 5])
+     *   .tap(arr => console.log('Original:', arr))
+     *   .map(arr => arr.filter(x => x % 2 === 0))
+     *   .tap(arr => console.log('Filtered:', arr))
+     *   .map(arr => arr.reduce((a, b) => a + b, 0))
+     *   .tap(sum => console.log('Sum:', sum))
+     *   .value();
+     * // Logs: Original: [1,2,3,4,5], Filtered: [2,4], Sum: 6
+     * // Returns: 6
+     *
+     * @example
+     * // Analytics tracking
+     * const processOrder = Pipeline.of(order)
+     *   .tap(o => analytics.track('order_started', { orderId: o.id }))
+     *   .map(o => applyDiscount(o))
+     *   .tap(o => analytics.track('discount_applied', { amount: o.discount }))
+     *   .map(o => calculateTax(o))
+     *   .tap(o => analytics.track('order_completed', { total: o.total }))
+     *   .value();
+     */
+    Pipeline.prototype.tap = function (fn) {
+        fn(this._value);
+        return this;
+    };
+    /**
+     * Execute an async side effect without changing the value.
+     * Useful for async logging, API calls, or other async side effects.
+     *
+     * @category Async
+     * @example
+     * const saveUser = await Pipeline.of(userData)
+     *   .tapAsync(async (user) => {
+     *     await logToAnalytics('user_created', user);
+     *   })
+     *   .then(p => p.tapAsync(async (user) => {
+     *     await sendWelcomeEmail(user.email);
+     *   }))
+     *   .then(p => p.value());
+     *
+     * @example
+     * // Progress tracking
+     * const processLargeFile = await Pipeline.of(file)
+     *   .tapAsync(f => updateProgress(0))
+     *   .then(p => p.mapAsync(f => readFile(f)))
+     *   .then(p => p.tapAsync(_ => updateProgress(33)))
+     *   .then(p => p.mapAsync(content => parseContent(content)))
+     *   .then(p => p.tapAsync(_ => updateProgress(66)))
+     *   .then(p => p.mapAsync(data => saveToDatabase(data)))
+     *   .then(p => p.tapAsync(_ => updateProgress(100)))
+     *   .then(p => p.value());
+     */
+    Pipeline.prototype.tapAsync = function (fn) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, fn(this._value)];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/, this];
+                }
+            });
+        });
+    };
+    /**
+     * Get the final value from the pipeline.
+     * Extracts the transformed value, ending the pipeline chain.
+     *
+     * @category Extraction
+     * @example
+     * const result = Pipeline.of(10)
+     *   .map(x => x * 2)
+     *   .map(x => x + 5)
+     *   .value();
+     * // => 25
+     */
+    Pipeline.prototype.value = function () {
+        return this._value;
+    };
+    /**
+     * Create a new pipeline with the given value.
+     * Factory method for creating Pipeline instances.
+     *
+     * @category Creation
+     * @example
+     * const pipeline = Pipeline.of(42);
+     *
+     * @example
+     * // With complex initial values
+     * const userPipeline = Pipeline.of({
+     *   id: 123,
+     *   name: 'John Doe',
+     *   email: 'john@example.com'
+     * });
+     */
+    Pipeline.of = function (value) {
+        return new Pipeline(value);
+    };
+    /**
+     * Apply a function to the pipeline value and return the result.
+     * Useful for conditional transformations or extracting values.
+     *
+     * @category Advanced
+     * @example
+     * const discount = Pipeline.of(100)
+     *   .apply(price =>
+     *     price > 50
+     *       ? Pipeline.of(price * 0.9)  // 10% discount
+     *       : Pipeline.of(price)
+     *   )
+     *   .value();
+     * // => 90
+     *
+     * @example
+     * // Conditional branching
+     * const processUser = (user: User) => Pipeline.of(user)
+     *   .apply(u => {
+     *     if (u.type === 'premium') {
+     *       return Pipeline.of(u)
+     *         .map(u => ({ ...u, benefits: ['ad-free', 'priority-support'] }))
+     *         .map(u => ({ ...u, discount: 0.2 }));
+     *     } else {
+     *       return Pipeline.of(u)
+     *         .map(u => ({ ...u, benefits: [] }))
+     *         .map(u => ({ ...u, discount: 0 }));
+     *     }
+     *   })
+     *   .value();
+     */
+    Pipeline.prototype.apply = function (fn) {
+        return fn(this._value);
+    };
+    /**
+     * Combine two pipelines using a binary function.
+     * Useful for merging results from multiple pipelines.
+     *
+     * @category Advanced
+     * @example
+     * const pipeline1 = Pipeline.of(5);
+     * const pipeline2 = Pipeline.of(3);
+     *
+     * const sum = pipeline1
+     *   .combine(pipeline2, (a, b) => a + b)
+     *   .value();
+     * // => 8
+     *
+     * @example
+     * // Combining user data
+     * const userPipeline = Pipeline.of({ id: 1, name: 'John' });
+     * const preferencesPipeline = Pipeline.of({ theme: 'dark', lang: 'en' });
+     *
+     * const completeUser = userPipeline
+     *   .combine(preferencesPipeline, (user, prefs) => ({
+     *     ...user,
+     *     preferences: prefs
+     *   }))
+     *   .value();
+     * // => { id: 1, name: 'John', preferences: { theme: 'dark', lang: 'en' } }
+     */
+    Pipeline.prototype.combine = function (other, fn) {
+        return new Pipeline(fn(this._value, other._value));
+    };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    Pipeline.prototype.pipeAsync = function () {
+        var fns = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            fns[_i] = arguments[_i];
+        }
+        return __awaiter(this, void 0, void 0, function () {
+            var result, _a, fns_1, fn;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        result = this._value;
+                        _a = 0, fns_1 = fns;
+                        _b.label = 1;
+                    case 1:
+                        if (!(_a < fns_1.length)) return [3 /*break*/, 4];
+                        fn = fns_1[_a];
+                        return [4 /*yield*/, fn(result)];
+                    case 2:
+                        result = _b.sent();
+                        _b.label = 3;
+                    case 3:
+                        _a++;
+                        return [3 /*break*/, 1];
+                    case 4: return [2 /*return*/, result];
+                }
+            });
+        });
+    };
+    return Pipeline;
+}());
+export { Pipeline };
+//# sourceMappingURL=pipeline.mjs.map

package/dist/pipeline.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.mjs","sourceRoot":"","sources":["../src/pipeline.mts"],"names":[],"mappings":"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"}