serial-task 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kasukabe tsumugi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,355 @@
+# Serial Task
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> Put a list of functions in and get a composed task function. Similar to functional programming's compose (function composition), but with more fine-grained and precise control, and the generated task incurs almost no runtime overhead. ✨
+
+**Note**: For async functions, use `createSerialTaskAsync` instead of `createSerialTask`. Both functions have the same API, but `createSerialTaskAsync` properly handles async/await and Promise-based functions.
+
+For more awesome packages, check out [my homepage💛](https://baendlorel.github.io/?repoType=npm)
+
+## 📦 Installation
+
+```bash
+npm install serial-task
+```
+
+```bash
+pnpm add serial-task
+```
+
+## 🎯 Quick Start
+
+> Note: For async functions(tasks/resultWrapper/conditions), use `createSerialTaskAsync` instead.
+
+```typescript
+import { createSerialTask } from 'serial-task';
+
+// Create a serial task with multiple functions
+const mathTask = createSerialTask({
+  tasks: [
+    (x: number) => x + 1, // Step 1: add 1
+    (x: number) => x * 2, // Step 2: multiply by 2
+    (x: number) => x - 1, // Step 3: subtract 1
+  ],
+});
+
+const result = mathTask(5);
+console.log(result.value); // 11 -> ((5 + 1) * 2) - 1 = 11
+console.log(result.results); // [6, 12, 11]
+```
+
+## 🔄 Execution Flow
+
+The following diagram shows how functions are called in each iteration of the loop:
+
+<div style="text-align: center">
+  <img src="https://raw.githubusercontent.com/baendlorel/serial-task/main/assets/flow.svg" alt="Execution Flow" width="360" />
+</div>
+
+## 📖 API Reference
+
+### createSerialTask(options) / createSerialTaskAsync(options)
+
+Creates a sync/async serial task function.
+
+#### Parameters
+
+- **options**: `SerialTaskOptions<F>`
+  - **name?**: `string` - Name of the generated task function (default: `'kskbTask'`)
+  - **tasks**: `F[]` - Array of functions to be executed in order
+  - **breakCondition?**: `function` - Function that determines when to break the loop (default: `() => false`)
+  - **skipCondition?**: `function` - Function that determines when to skip a task (default: `() => false`)
+  - **resultWrapper?**: `function` - Function that transforms input between tasks, default(means the first task gets original args, subsequent tasks get the last return value):
+  ```ts
+  (_task: Fn, index: number, _tasks: Fn[], args: unknown[], lastReturn: unknown) =>
+    index === 0 ? args : [lastReturn];
+  ```
+
+#### Returns
+
+A function that executes the tasks in order and returns a `TaskReturn<R>` object:
+
+```typescript
+interface TaskReturn<R> {
+  value: R; // Result of the last executed task
+  results: R[]; // All results (skipped tasks are undefined)
+  trivial: boolean; // True if tasks array was empty
+  breakAt: number; // Index where loop broke (-1 if not broken)
+  skipped: number[]; // Indices of skipped tasks
+}
+```
+
+## 🎨 Usage Scenarios
+
+### Scenario 1: Function Composition Pipeline
+
+Perfect for data transformation pipelines where you need to apply multiple transformations in sequence:
+
+```typescript
+import { createSerialTask } from 'serial-task';
+
+// Data processing pipeline
+interface UserData {
+  name: string;
+  email: string;
+  age: number;
+}
+
+const processUser = createSerialTask({
+  name: 'userProcessor',
+  tasks: [
+    // Step 1: Validate input
+    (user: UserData) => {
+      if (!user.email.includes('@')) {
+        throw new Error('Invalid email');
+      }
+      return user;
+    },
+
+    // Step 2: Normalize data
+    (user: UserData) => ({
+      ...user,
+      name: user.name.trim().toLowerCase(),
+      email: user.email.toLowerCase(),
+    }),
+
+    // Step 3: Add computed fields
+    (user: UserData) => ({
+      ...user,
+      isAdult: user.age >= 18,
+      displayName: user.name.charAt(0).toUpperCase() + user.name.slice(1),
+    }),
+
+    // Step 4: Generate summary
+    (user: any) => ({
+      ...user,
+      summary: `${user.displayName} (${user.email}) - ${user.isAdult ? 'Adult' : 'Minor'}`,
+    }),
+  ],
+});
+
+const result = processUser({
+  name: '  John Doe  ',
+  email: 'JOHN@EXAMPLE.COM',
+  age: 25,
+});
+
+console.log(result.value);
+// Output: {
+//   name: 'john doe',
+//   email: 'john@example.com',
+//   age: 25,
+//   isAdult: true,
+//   displayName: 'John doe',
+//   summary: 'John doe (john@example.com) - Adult'
+// }
+```
+
+### Scenario 2: Event Handler Chain with Conditional Logic
+
+Great for building middleware-like handler chains with skip and break logic:
+
+```typescript
+import { createSerialTask } from 'serial-task';
+
+interface Request {
+  path: string;
+  method: string;
+  headers: Record<string, string>;
+  body?: any;
+  metadata?: Record<string, any>;
+}
+
+// HTTP request handler chain
+const requestHandler = createSerialTask({
+  name: 'httpHandler',
+  tasks: [
+    // Handler 1: Authentication
+    (req: Request) => {
+      console.log('🔐 Authenticating request...');
+      return {
+        ...req,
+        metadata: { ...req.metadata, authenticated: true, userId: 'user123' },
+      };
+    },
+
+    // Handler 2: Rate limiting
+    (req: Request) => {
+      console.log('⏱️ Checking rate limits...');
+      return {
+        ...req,
+        metadata: { ...req.metadata, rateLimited: false },
+      };
+    },
+
+    // Handler 3: Input validation
+    (req: Request) => {
+      console.log('✅ Validating input...');
+      if (req.method === 'POST' && !req.body) {
+        throw new Error('Body required for POST requests');
+      }
+      return {
+        ...req,
+        metadata: { ...req.metadata, validated: true },
+      };
+    },
+
+    // Handler 4: Business logic
+    (req: Request) => {
+      console.log('🔄 Processing business logic...');
+      return {
+        ...req,
+        metadata: { ...req.metadata, processed: true, result: 'success' },
+      };
+    },
+
+    // Handler 5: Response formatting
+    (req: Request) => {
+      console.log('📤 Formatting response...');
+      return {
+        ...req,
+        metadata: { ...req.metadata, formatted: true },
+      };
+    },
+  ],
+
+  // Skip rate limiting for admin users
+  skipCondition: (task, index, tasks, args, lastReturn) => {
+    if (index === 1) {
+      // rate limiting handler
+      const req = lastReturn as Request;
+      return req.metadata?.userId === 'admin';
+    }
+    return false;
+  },
+
+  // Break early if user is not authenticated
+  breakCondition: (task, index, tasks, args, lastReturn) => {
+    if (index > 0) {
+      // after authentication
+      const req = lastReturn as Request;
+      return !req.metadata?.authenticated;
+    }
+    return false;
+  },
+
+  // Pass the result to the next handler
+  resultWrapper: (task, index, tasks, args, lastReturn) => {
+    if (index === 0) {
+      return args; // First handler gets original args
+    }
+    return [...args, lastReturn]; // Subsequent handlers get the result from previous
+  },
+});
+
+// Example usage
+const request: Request = {
+  path: '/api/users',
+  method: 'GET',
+  headers: { Authorization: 'Bearer token123' },
+  metadata: {},
+};
+
+const result = requestHandler(request);
+
+console.log('Final result:', result.value);
+console.log('Skipped handlers:', result.skipped); // e.g., [1] if rate limiting was skipped
+console.log('Broke at:', result.breakAt); // -1 if completed successfully
+
+// Example output:
+// 🔐 Authenticating request...
+// ⏱️ Checking rate limits...
+// ✅ Validating input...
+// 🔄 Processing business logic...
+// 📤 Formatting response...
+// Final result: { ... processed request with all metadata ... }
+// Skipped handlers: []
+// Broke at: -1
+```
+
+## 🔧 Advanced Features
+
+### Conditional Execution
+
+Control the flow of your task execution with powerful conditions:
+
+```typescript
+const conditionalTask = createSerialTask({
+  tasks: [taskA, taskB, taskC, taskD],
+
+  // Skip tasks based on conditions
+  skipCondition: (task, index, tasks, args, lastReturn) => {
+    // Skip taskB if input is negative
+    if (index === 1 && args[0] < 0) return true;
+    return false;
+  },
+
+  // Break early if result exceeds threshold
+  breakCondition: (task, index, tasks, args, lastReturn) => {
+    return lastReturn > 100;
+  },
+});
+```
+
+### Dynamic Task Arrays
+
+Modify the task array during execution:
+
+```typescript
+const dynamicTask = createSerialTask({
+  tasks: [initialTask],
+  resultWrapper: (task, index, taskArray, args, lastReturn) => {
+    // Add more tasks dynamically
+    if (index === 0 && someCondition) {
+      taskArray.push(additionalTask);
+    }
+    return index === 0 ? args : [lastReturn];
+  },
+});
+```
+
+## 🔄 Async Support
+
+For async functions, use `createSerialTaskAsync`:
+
+```typescript
+import { createSerialTaskAsync } from 'serial-task';
+
+const asyncTask = createSerialTaskAsync({
+  tasks: [
+    async (data) => await fetchUserData(data),
+    async (user) => await validateUser(user),
+    async (user) => await saveUser(user),
+  ],
+});
+
+const result = await asyncTask(inputData);
+```
+
+## 🎪 Error Handling
+
+Tasks can throw errors, which will propagate up and stop execution:
+
+```typescript
+const taskWithErrors = createSerialTask({
+  tasks: [
+    (x) => x + 1,
+    (x) => {
+      if (x > 10) throw new Error('Value too large!');
+      return x * 2;
+    },
+    (x) => x - 1,
+  ],
+});
+
+try {
+  const result = taskWithErrors(15);
+} catch (error) {
+  console.error('Task failed:', error.message);
+}
+```
+
+## 📄 License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,184 @@
+/**
+ * ## Usage
+ * Use this when you have async functions in tasks, conditions or result wrapper
+ *
+ * Creates an async serial task function that executes a series of functions in order
+ * - all given functions(`options.tasks`) will be called in order
+ * - generated task function will have the same length as the first task function
+ * - you can appoint generated task function's name by `options.name`
+ * - **Strongly Recommended**: all task functions have same input type and output type
+ *   - returned function.length will be the same as the first task function's length
+ * @param opts Options for creating a serial task, details in `SerialTaskOptions`
+ * @returns a funtcion that executes the tasks in order, returns `TaskReturn<OriginalReturn>`
+ *
+ * ## About
+ * @package SerialTask
+ * @author Kasukabe Tsumugi <futami16237@gmail.com>
+ * @version 1.0.0 (Last Update: 2025.08.22 17:05:02.346)
+ * @license MIT
+ * @link https://github.com/baendlorel/serial-task
+ * @description Put a list of functions in and get a composed task function. Similar to functional programming's compose (function composition), but with more fine-grained and precise control, and the generated task incurs almost no runtime overhead. Supports both synchronous and asynchronous functions.
+ * @copyright Copyright (c) 2025 Kasukabe Tsumugi. All rights reserved.
+ */
+declare function createSerialTaskAsync<F extends Fn>(opts: SerialTaskOptions<F>): TaskifyAsync<F>;
+
+/**
+ * ## Usage
+ * **DO NOT Use** this when you have **async functions** in tasks, conditions or result wrapper
+ *
+ * Creates a serial task function that executes a series of functions in order.
+ * - all given functions(`options.tasks`) will be called in order
+ *   - the returned value will be `options.resultWrapper`ed then passed to the next task
+ * - generated task function will have the same length as the first task function
+ * - you can appoint generated task function's name by `options.name`
+ * - **Strongly Recommended**: all task functions have same input type and output type
+ *   - returned function.length will be the same as the first task function's length
+ * @param opts Options for creating a serial task, details in `SerialTaskOptions`
+ * @returns a funtcion that executes the tasks in order, returns `TaskReturn<OriginalReturn>`
+ *
+ * ## About
+ * @package SerialTask
+ * @author Kasukabe Tsumugi <futami16237@gmail.com>
+ * @version 1.0.0 (Last Update: 2025.08.22 17:05:02.346)
+ * @license MIT
+ * @link https://github.com/baendlorel/serial-task
+ * @description Put a list of functions in and get a composed task function. Similar to functional programming's compose (function composition), but with more fine-grained and precise control, and the generated task incurs almost no runtime overhead. Supports both synchronous and asynchronous functions.
+ * @copyright Copyright (c) 2025 Kasukabe Tsumugi. All rights reserved.
+ */
+declare function createSerialTask<F extends Fn>(opts: SerialTaskOptions<F>): Taskify<F>;
+
+export { createSerialTask, createSerialTaskAsync };
+
+// # from: src/global.d.ts
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type Fn = (...args: any[]) => any;
+
+interface TaskReturn<R = any> {
+  /**
+   * The result of the last task function
+   */
+  value: R;
+
+  /**
+   * All results of the tasks
+   * - same order as `tasks`
+   * - skipped tasks will be empty slot in this array
+   *   - which means `index in results` is `false`
+   */
+  results: R[];
+
+  /**
+   * Means `options.tasks.length` is `0`
+   */
+  trivial: boolean;
+
+  /**
+   * If the task breaks, this will record the index of the task that caused the break.
+   * - `-1` means not broken
+   * - otherwise, the index of the task that caused the break
+   */
+  breakAt: number;
+
+  /**
+   * Index of the skipped tasks
+   */
+  skipped: number[];
+}
+
+type TaskifyAsync<F extends Fn> = (...args: Parameters<F>) => Promise<TaskReturn<ReturnType<F>>>;
+type Taskify<F extends Fn> = (...args: Parameters<F>) => TaskReturn<ReturnType<F>>;
+
+interface SerialTaskOptions<F extends Fn> {
+  /**
+   * Name of the generated task function
+   * - default is `'kskbTask'`
+   */
+  name?: string;
+
+  /**
+   * Functions to be executed in order. The one that iterates internally.
+   * - if you use `createSerialTaskAsync`, these functions will be called with `await`
+   * - **Strongly Recommended**: all task functions must have same input type and output type
+   * - creator will directly use this array, so you can modify it dynamically
+   * - will be executed from `0` to `length - 1`
+   */
+  tasks: F[] | Fn[];
+
+  /**
+   * Returns an array of arguments that will be passed to the next task
+   * - **MUST return an array of arguments!**
+   * - if you use `createSerialTaskAsync`, this function will be called with `await`
+   * - when calling the first task(no result before), the `lastReturn` will be set to `undefined`
+   * @default
+   *  (_task: Fn, index: number, _tasks: Fn[], args: unknown[], lastReturn: unknown) => index === 0 ? args : [lastReturn]
+   * @param task current task function
+   * @param index index of current task
+   * @param tasks is `options.tasks`, since `for tasks.length` loop is used here, you can add new tasks dynamically
+   * @param args input value of the whole serial task
+   * @param lastReturn returned value of the last task function
+   * @returns **must return an array of arguments!**
+   * @example
+   * ```typescript
+   * // Internal implementation
+   * // first loop, index = 0
+   * // The calling order of each function is as follows:
+   * const inputValue = [...arguments]; // arguments of the created task function
+   * let returnValue = null
+   * for(...){
+   *   const currentInput = resultWrapper(index, ...inputValue, returnValue);
+   *   const toBreak = breakCondition(index, ...currentInput);
+   *   if (toBreak) break;
+   *   const toSkip = skipCondition(index, ...currentInput);
+   *   if (toSkip) continue;
+   *   returnValue = tasks[index](...currentInput);
+   * }
+   * ```
+   */
+  resultWrapper?: (
+    task: F,
+    index: number,
+    tasks: F[],
+    args: Parameters<F>,
+    lastReturn: ReturnType<F>
+  ) => unknown[];
+
+  /**
+   * Break the loop and return the last result immediately when this function returns `true`
+   * - if you use `createSerialTaskAsync`, this function will be called with `await`
+   * - when calling the first task(no result before), the `lastReturn` will be `undefined`
+   * - default is `() => false`
+   * @param task current task function
+   * @param index index of current task
+   * @param tasks is `options.tasks`, since `for tasks.length` loop is used here, you can add new tasks dynamically
+   * @param args input value of the whole serial task
+   * @param lastReturn returned value of the last task function
+   */
+  breakCondition?: (
+    task: F,
+    index: number,
+    tasks: F[],
+    args: Parameters<F>,
+    lastReturn: ReturnType<F>
+  ) => boolean;
+
+  /**
+   * Give `true` to skip this task item
+   * - if you use `createSerialTaskAsync`, this function will be called with `await`
+   * - when calling the first task(no result before), the `lastReturn` will be `undefined`
+   * - default is `() => false`
+   * @param task current task function
+   * @param index index of current task
+   * @param tasks is `options.tasks`, since `for tasks.length` loop is used here, you can add new tasks dynamically
+   * @param args input value of the whole serial task
+   * @param lastReturn returned value of the last task function
+   */
+  skipCondition?: (
+    task: F,
+    index: number,
+    tasks: F[],
+    args: Parameters<F>,
+    lastReturn: ReturnType<F>
+  ) => boolean;
+}
+
+type StrictSerialTaskOptions<F extends Fn> = Required<SerialTaskOptions<F>>;

package/dist/index.mjs

@@ -0,0 +1 @@
+const t=Reflect.defineProperty,e=Array.isArray,n=Promise.resolve.bind(Promise),r=Promise.reject.bind(Promise),o=t=>("object"==typeof t&&null!==t||"function"==typeof t)&&("then"in t&&"function"==typeof t.then),i=()=>!1,a=i,s=(t,e,n,r,o)=>0===e?r:[o];function u(t){if("object"!=typeof t||null===t)throw new TypeError("SerialTask: 'options' must be an object");const{name:n="kskbTask",tasks:r,breakCondition:o=i,skipCondition:u=a,resultWrapper:l=s}=t;if("string"!=typeof n)throw new TypeError("SerialTask: 'name' must be a string or omitted");if(!e(r)||r.some(t=>"function"!=typeof t))throw new TypeError("SerialTask: 'tasks' must be a function array");if("function"!=typeof o)throw new TypeError("SerialTask: 'breakCondition' must be a function or omitted");if("function"!=typeof u)throw new TypeError("SerialTask: 'skipCondition' must be a function or omitted");if("function"!=typeof l)throw new TypeError("SerialTask: 'resultWrapper' must be a function or omitted");return{name:n,tasks:r,breakCondition:o,skipCondition:u,resultWrapper:l}}function l(t,e,...i){try{const r=t.apply(e,i);return o(r)?r:n(r)}catch(t){return r(t)}}function c(t,e,i){try{const r=t.apply(e,i);return o(r)?r:n(r)}catch(t){return r(t)}}function f(e){const{name:n,tasks:r,breakCondition:o,skipCondition:i,resultWrapper:a}=u(e);if(0===r.length){const e=()=>({value:void 0,results:[],trivial:!0,breakAt:-1,skipped:[]});return t(e,"name",{value:n,configurable:!0}),e}const s=async function(...t){let e;const n=new Array(r.length);let s=-1;const u=[];for(let f=0;f<r.length;f++){const p=r[f],k=await l(a,null,p,f,r,t,e);if(await l(o,null,p,f,r,t,e)){s=f;break}await l(i,null,p,f,r,t,e)?u.push(f):(e=await c(p,null,k),n[f]=e)}return{value:e,results:n,trivial:!1,breakAt:s,skipped:u}};return t(s,"name",{value:n,configurable:!0}),t(s,"length",{value:r[0].length,configurable:!0}),s}function p(e){const{name:n,tasks:r,breakCondition:o,skipCondition:i,resultWrapper:a}=u(e);if(0===r.length){const e=()=>({value:void 0,results:[],trivial:!0,breakAt:-1,skipped:[]});return t(e,"name",{value:n,configurable:!0}),e}const s=function(...t){let e;const n=new Array(r.length);let s=-1;const u=[];for(let l=0;l<r.length;l++){const c=r[l],f=a(c,l,r,t,e);if(o(c,l,r,t,e)){s=l;break}i(c,l,r,t,e)?u.push(l):(e=c.apply(null,f),n[l]=e)}return{value:e,results:n,trivial:!1,breakAt:s,skipped:u}};return t(s,"name",{value:n,configurable:!0}),t(s,"length",{value:r[0].length,configurable:!0}),s}export{p as createSerialTask,f as createSerialTaskAsync};

package/package.json

@@ -0,0 +1,60 @@
+{
+	"name": "serial-task",
+	"version": "1.0.0",
+	"author": {
+		"name": "Kasukabe Tsumugi",
+		"email": "futami16237@gmail.com"
+	},
+	"purpose": "npm",
+	"description": "Put a list of functions in and get a composed task function. Similar to functional programming's compose (function composition), but with more fine-grained and precise control, and the generated task incurs almost no runtime overhead. Supports both synchronous and asynchronous functions.",
+	"description_zh": "将一组函数放入并获取一个组合任务函数。类似于函数式编程的函数组合，但具有更细粒度和精确的控制，生成的任务几乎没有运行时判定的额外开销。支持同步和异步函数。",
+	"type": "module",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		"types": "./dist/index.d.ts",
+		"import": "./dist/index.mjs",
+		"default": "./dist/index.mjs"
+	},
+	"files": [
+		"dist"
+	],
+	"homepage": "https://github.com/baendlorel/serial-task#readme",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/baendlorel/serial-task"
+	},
+	"keywords": [
+		"typescript",
+		"javascript"
+	],
+	"scripts": {
+		"test": "clear & vitest",
+		"lint": "oxlint .",
+		"cover": "clear & vitest --coverage",
+		"build": "node ./scripts/rollup.mjs"
+	},
+	"license": "MIT",
+	"devDependencies": {
+		"@babel/plugin-proposal-decorators": "^7.28.0",
+		"@babel/preset-env": "^7.28.3",
+		"@rollup/plugin-alias": "^5.1.1",
+		"@rollup/plugin-babel": "^6.0.4",
+		"@rollup/plugin-commonjs": "^28.0.6",
+		"@rollup/plugin-node-resolve": "^16.0.1",
+		"@rollup/plugin-replace": "^6.0.2",
+		"@rollup/plugin-terser": "^0.4.4",
+		"@rollup/plugin-typescript": "^12.1.4",
+		"@types/node": "^24.3.0",
+		"@vitest/coverage-v8": "^3.2.4",
+		"oxlint": "^1.12.0",
+		"prettier": "^3.6.2",
+		"rimraf": "^6.0.1",
+		"rollup": "^4.47.1",
+		"rollup-plugin-dts": "^6.2.3",
+		"rollup-plugin-dts-merger": "^1.2.3",
+		"tslib": "^2.8.1",
+		"typescript": "^5.9.2",
+		"vitest": "^3.2.4"
+	}
+}