@idlesummer/tasker 0.1.0

package/LICENSE

@@ -0,0 +1,6 @@
+MIT License
+
+Copyright (c) 2026 idlesummer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation...

package/README.md

@@ -0,0 +1,220 @@
+# @idlesummer/tasker
+
+A simple, lightweight task pipeline runner with CLI spinners and formatters for Node.js build tools.
+
+> **⚠️ Learning Project Notice**
+> Hey! Just so you know, this is a learning project I built to understand task pipelines and build tools better. It works and I use it for my own stuff, but there might be bugs or rough edges. Feel free to use it, but maybe don't bet your production deploy on it just yet. Contributions and bug reports are super welcome though!
+
+## What's This?
+
+Basically, it's a simple way to run tasks in sequence with nice terminal spinners. I got tired of writing the same boilerplate for build scripts, so I made this. Think of it like a mini task runner - simpler than Gulp but more structured than a bash script.
+
+## Features
+
+- **Task Pipeline** - Run tasks one after another, each task gets the results from the previous ones
+- **CLI Spinners** - Those satisfying loading spinners powered by ora
+- **Formatters** - Helper functions to make bytes, durations, and file lists look nice
+- **TypeScript** - Full type safety so you don't shoot yourself in the foot
+
+## Installation
+
+```bash
+npm install @idlesummer/tasker
+```
+
+## Quick Start
+
+Here's the simplest example:
+
+```typescript
+import { pipe, type Context } from '@idlesummer/tasker'
+
+interface MyContext extends Context {
+  count?: number
+}
+
+const pipeline = pipe<MyContext>([
+  {
+    name: 'Initialize',
+    run: async () => ({ count: 0 }),
+  },
+  {
+    name: 'Process',
+    run: async (ctx) => ({ count: (ctx.count ?? 0) + 10 }),
+    onSuccess: (ctx) => `Processed (count: ${ctx.count})`,
+  },
+])
+
+const result = await pipeline.run({})
+console.log(`Done in ${result.duration}ms`)
+```
+
+That's it! You get:
+- Spinners while tasks run ✨
+- Type-safe context passing between tasks
+- Timing info automatically
+
+## Why Would I Use This?
+
+Good question! Use this if you:
+- Want to build a simple CLI tool or build script
+- Like seeing spinners while stuff happens
+- Need tasks to share data between each other
+- Want something lighter than Gulp but more structured than raw scripts
+
+Don't use this if you:
+- Need parallel task execution (tasks run sequentially here)
+- Want a mature, battle-tested solution (this is a learning project!)
+- Need a full-featured task runner (look at Gulp, Grunt, etc.)
+
+## Documentation
+
+I wrote pretty detailed docs with a casual tone (because formal docs are boring):
+
+- **[API Reference](./docs/API.md)** - All the functions and types explained
+- **[Examples](./docs/EXAMPLES.md)** - Real code you can copy-paste
+- **[Architecture](./docs/ARCHITECTURE.md)** - How it works under the hood
+- **[Contributing](./docs/CONTRIBUTING.md)** - Want to help? Start here
+- **[Troubleshooting](./docs/TROUBLESHOOTING.md)** - Common issues and fixes
+
+## Example Projects
+
+The `examples/` folder has working projects you can run:
+
+- **[basic-pipeline](./examples/basic-pipeline)** - Super simple example to get started
+- **[build-tool](./examples/build-tool)** - More realistic build tool with file operations
+- **[formatters](./examples/formatters)** - Shows off all the formatting utilities
+
+Each example is a standalone npm package. To run one:
+
+```bash
+# Clone and setup
+git clone https://github.com/idlesummer/tasker.git
+cd tasker
+npm install
+npm run build
+
+# Try an example
+cd examples/basic-pipeline
+npm install
+npm run build
+npm start
+```
+
+See the [examples README](./examples/README.md) for more info.
+
+## Quick API Overview
+
+### Pipeline
+
+Create a pipeline with tasks:
+
+```typescript
+const pipeline = pipe([
+  {
+    name: 'Task name',
+    run: async (ctx) => {
+      // Do stuff
+      return { key: 'value' }  // Updates context
+    },
+    onSuccess: (ctx, duration) => 'Custom success message',
+    onError: (error) => 'Custom error message'
+  }
+])
+
+const result = await pipeline.run({})
+// result.context has your final context
+// result.duration is total time in ms
+```
+
+### Formatters
+
+Make numbers pretty:
+
+```typescript
+import { bytes, duration, fileList } from '@idlesummer/tasker'
+
+console.log(bytes(1234567))        // "1.23 MB"
+console.log(duration(12345))       // "12.3s"
+console.log(fileList('./dist'))    // Formatted file list with sizes
+```
+
+Check [API.md](./docs/API.md) for the full reference.
+
+## A More Real Example
+
+Here's what a build script might look like:
+
+```typescript
+import { pipe, fileList, duration } from '@idlesummer/tasker'
+import { exec } from 'child_process'
+import { promisify } from 'util'
+
+const execAsync = promisify(exec)
+
+const build = pipe([
+  {
+    name: 'Clean dist folder',
+    run: async () => {
+      await execAsync('rm -rf dist')
+    }
+  },
+  {
+    name: 'Compile TypeScript',
+    run: async () => {
+      await execAsync('tsc')
+    },
+    onSuccess: () => 'TypeScript compiled successfully'
+  },
+  {
+    name: 'Show output',
+    run: async () => {
+      console.log('\nBuild output:')
+      console.log(fileList('./dist'))
+    }
+  }
+])
+
+console.log('🏗️  Building...\n')
+const result = await build.run({})
+console.log(`\n✅ Done in ${duration(result.duration)}`)
+```
+
+You get nice spinners for each step, and a clean output at the end.
+
+## Known Issues / Limitations
+
+Since this is a learning project:
+- Tasks run sequentially only (no parallel execution yet)
+- No built-in retry logic
+- Error handling is basic (task fails = pipeline stops)
+- Haven't tested with huge codebases
+
+These might get fixed eventually, or they might not. PRs welcome if you want to add features!
+
+## Contributing
+
+Found a bug? Want to add a feature? Awesome!
+
+1. Check [CONTRIBUTING.md](./docs/CONTRIBUTING.md) for guidelines
+2. Open an issue or PR
+3. Be nice (we're all learning here)
+
+Even if you're new to open source, feel free to contribute. I'm learning too!
+
+## License
+
+MIT - do whatever you want with this.
+
+## Questions?
+
+- Check the [docs](./docs/)
+- Look at the [examples](./examples/)
+- Open an issue
+- Read the [troubleshooting guide](./docs/TROUBLESHOOTING.md)
+
+---
+
+Made with ☕ and procrastination by [@idlesummer](https://github.com/idlesummer)
+
+If this helps you, cool! If you find bugs, let me know. If you want to improve it, send a PR. Let's learn together!

package/dist/index.cjs

@@ -0,0 +1,123 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let fs = require("fs");
+let path = require("path");
+let fdir = require("fdir");
+let picocolors = require("picocolors");
+picocolors = __toESM(picocolors);
+let picomatch = require("picomatch");
+picomatch = __toESM(picomatch);
+let pretty_bytes = require("pretty-bytes");
+pretty_bytes = __toESM(pretty_bytes);
+let pretty_ms = require("pretty-ms");
+pretty_ms = __toESM(pretty_ms);
+let ora = require("ora");
+ora = __toESM(ora);
+
+//#region src/format.ts
+/**
+* Formats byte sizes into human-readable strings
+* @param size - The size in bytes
+* @returns Formatted string (e.g., "1.23 kB", "4.56 MB")
+*/
+const bytes = pretty_bytes.default;
+/**
+* Formats milliseconds into human-readable durations
+* @param ms - The duration in milliseconds
+* @returns Formatted string (e.g., "42ms", "1.2s", "2m 3.5s")
+*/
+const duration = pretty_ms.default;
+/**
+* Display a formatted list of files in a directory with their sizes
+* @param baseDir - The base directory to search
+* @param pattern - Glob pattern to match files
+* @param width - Row width for file paths
+* @returns Formatted file list with sizes and total
+*/
+function fileList(baseDir, pattern = "**/*", width = 45) {
+	const matcher = (0, picomatch.default)(pattern, { windows: true });
+	const files = new fdir.fdir().withRelativePaths().filter((path$1) => matcher(path$1)).crawl(baseDir).sync();
+	const stats = files.map((path$1) => {
+		const fullPath = (0, path.join)(baseDir, path$1);
+		return {
+			path: path$1.replace(/\\/g, "/"),
+			size: (0, fs.statSync)(fullPath).size
+		};
+	});
+	const total = stats.reduce((sum, stat) => sum + stat.size, 0);
+	const lines = stats.map(({ path: path$1, size }) => {
+		return `  ${picocolors.default.cyan(path$1.padEnd(width))}  ${picocolors.default.dim(bytes(size))}`;
+	});
+	const footerLabel = `${files.length} files, total:`.padEnd(width);
+	const footer = `  ${picocolors.default.dim(footerLabel)}  ${picocolors.default.dim(bytes(total))}`;
+	return [...lines, footer].join("\n");
+}
+
+//#endregion
+//#region src/pipeline.ts
+/**
+* Creates a task pipeline that runs tasks sequentially with spinners
+* @template TContext - The context type for the pipeline
+*/
+function pipe(tasks) {
+	return { run: async (initialContext) => {
+		const startTime = Date.now();
+		let context = initialContext;
+		for (const task of tasks) {
+			const taskStart = Date.now();
+			const spinner = (0, ora.default)(task.name).start();
+			try {
+				const updates = await task.run(context) ?? {};
+				const duration$2 = Date.now() - taskStart;
+				const message = task.onSuccess?.(context, duration$2) ?? task.name;
+				spinner.succeed(message);
+				context = {
+					...context,
+					...updates
+				};
+			} catch (error) {
+				const err = error instanceof Error ? error : new Error(String(error));
+				const message = task.onError?.(err) ?? task.name;
+				spinner.fail(message);
+				throw new Error(`Task "${task.name}" failed: ${err.message}`, { cause: err });
+			}
+		}
+		const duration$1 = Date.now() - startTime;
+		return {
+			context,
+			duration: duration$1
+		};
+	} };
+}
+
+//#endregion
+exports.bytes = bytes;
+exports.duration = duration;
+exports.fileList = fileList;
+exports.pipe = pipe;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["prettyBytes","prettyMs","path","pc","duration"],"sources":["../src/format.ts","../src/pipeline.ts"],"sourcesContent":["import { statSync } from 'fs'\r\nimport { join } from 'path'\r\nimport { fdir } from 'fdir'\r\nimport pc from 'picocolors'\r\nimport pm from 'picomatch'\r\nimport prettyBytes from 'pretty-bytes'\r\nimport prettyMs from 'pretty-ms'\r\n\r\n/**\r\n * Formats byte sizes into human-readable strings\r\n * @param size - The size in bytes\r\n * @returns Formatted string (e.g., \"1.23 kB\", \"4.56 MB\")\r\n */\r\nexport const bytes = prettyBytes\r\n\r\n/**\r\n * Formats milliseconds into human-readable durations\r\n * @param ms - The duration in milliseconds\r\n * @returns Formatted string (e.g., \"42ms\", \"1.2s\", \"2m 3.5s\")\r\n */\r\nexport const duration = prettyMs\r\n\r\n/**\r\n * Display a formatted list of files in a directory with their sizes\r\n * @param baseDir - The base directory to search\r\n * @param pattern - Glob pattern to match files\r\n * @param width - Row width for file paths\r\n * @returns Formatted file list with sizes and total\r\n */\r\nexport function fileList(baseDir: string, pattern = '**/*', width = 45) {\r\n  // Find all files matching the pattern\r\n  // Use windows: true option to handle both / and \\ as path separators\r\n  const matcher = pm(pattern, { windows: true })\r\n  const files = new fdir()\r\n    .withRelativePaths()\r\n    .filter(path => matcher(path))\r\n    .crawl(baseDir)\r\n    .sync()\r\n\r\n  const stats = files.map(path => {\r\n    const fullPath = join(baseDir, path)\r\n    const displayPath = path.replace(/\\\\/g, '/')\r\n    return {\r\n      path: displayPath,\r\n      size: statSync(fullPath).size,\r\n    }\r\n  })\r\n\r\n  const total = stats.reduce((sum, stat) => sum + stat.size, 0)\r\n  const lines = stats.map(({ path, size }) => {\r\n    const paddedPath = pc.cyan(path.padEnd(width))\r\n    const formattedSize = pc.dim(bytes(size))\r\n    return `  ${paddedPath}  ${formattedSize}`\r\n  })\r\n\r\n  const footerLabel = `${files.length} files, total:`.padEnd(width)\r\n  const footer = `  ${pc.dim(footerLabel)}  ${pc.dim(bytes(total))}`\r\n  return [...lines, footer].join('\\n')\r\n}\r\n","import ora from 'ora'\r\n\r\n/** Base context type - extend this to add your own properties */\r\nexport type Context = Record<string, unknown>\r\n\r\n/**\r\n * A task that runs in a pipeline\r\n * @template TContext - The context type for this task\r\n * @property name - Task name shown in spinner\r\n * @property run - Task implementation - return updates to merge into context\r\n * @property onSuccess - Optional success message (default: task name)\r\n * @property onError - Optional error message (default: task name)\r\n */\r\nexport interface Task<TContext extends Context> {\r\n  name: string\r\n  run: (ctx: TContext) => Promise<Partial<TContext> | void>\r\n  onSuccess?: (ctx: TContext, duration: number) => string\r\n  onError?: (error: Error) => string\r\n}\r\n\r\n/**\r\n * Result after running a pipeline\r\n * @template TContext - The context type\r\n * @property context - Final context after all tasks\r\n * @property duration - Total duration in milliseconds\r\n */\r\nexport type PipeResult<TContext extends Context> = {\r\n  context: TContext\r\n  duration: number\r\n}\r\n\r\n/**\r\n * Creates a task pipeline that runs tasks sequentially with spinners\r\n * @template TContext - The context type for the pipeline\r\n */\r\nexport function pipe<TContext extends Context>(tasks: Task<TContext>[]) {\r\n  return {\r\n    run: async (initialContext: TContext) => {\r\n      const startTime = Date.now()\r\n      let context = initialContext\r\n\r\n      for (const task of tasks) {\r\n        const taskStart = Date.now()\r\n        const spinner = ora(task.name).start()\r\n\r\n        try {\r\n          const updates = await task.run(context) ?? {}\r\n          const duration = Date.now() - taskStart\r\n          const message = task.onSuccess?.(context, duration) ?? task.name\r\n          spinner.succeed(message)\r\n          context = { ...context, ...updates }\r\n        }\r\n        catch (error) {\r\n          const err = error instanceof Error ? error : new Error(String(error))\r\n          const message = task.onError?.(err) ?? task.name\r\n          spinner.fail(message)\r\n          throw new Error(`Task \"${task.name}\" failed: ${err.message}`, { cause: err })\r\n        }\r\n      }\r\n\r\n      const duration = Date.now() - startTime\r\n      return { context, duration } as PipeResult<TContext>\r\n    },\r\n  }\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAaA,MAAa,QAAQA;;;;;;AAOrB,MAAa,WAAWC;;;;;;;;AASxB,SAAgB,SAAS,SAAiB,UAAU,QAAQ,QAAQ,IAAI;CAGtE,MAAM,iCAAa,SAAS,EAAE,SAAS,MAAM,CAAC;CAC9C,MAAM,QAAQ,IAAI,WAAM,CACrB,mBAAmB,CACnB,QAAO,WAAQ,QAAQC,OAAK,CAAC,CAC7B,MAAM,QAAQ,CACd,MAAM;CAET,MAAM,QAAQ,MAAM,KAAI,WAAQ;EAC9B,MAAM,0BAAgB,SAASA,OAAK;AAEpC,SAAO;GACL,MAFkBA,OAAK,QAAQ,OAAO,IAAI;GAG1C,uBAAe,SAAS,CAAC;GAC1B;GACD;CAEF,MAAM,QAAQ,MAAM,QAAQ,KAAK,SAAS,MAAM,KAAK,MAAM,EAAE;CAC7D,MAAM,QAAQ,MAAM,KAAK,EAAE,cAAM,WAAW;AAG1C,SAAO,KAFYC,mBAAG,KAAKD,OAAK,OAAO,MAAM,CAAC,CAEvB,IADDC,mBAAG,IAAI,MAAM,KAAK,CAAC;GAEzC;CAEF,MAAM,cAAc,GAAG,MAAM,OAAO,gBAAgB,OAAO,MAAM;CACjE,MAAM,SAAS,KAAKA,mBAAG,IAAI,YAAY,CAAC,IAAIA,mBAAG,IAAI,MAAM,MAAM,CAAC;AAChE,QAAO,CAAC,GAAG,OAAO,OAAO,CAAC,KAAK,KAAK;;;;;;;;;ACtBtC,SAAgB,KAA+B,OAAyB;AACtE,QAAO,EACL,KAAK,OAAO,mBAA6B;EACvC,MAAM,YAAY,KAAK,KAAK;EAC5B,IAAI,UAAU;AAEd,OAAK,MAAM,QAAQ,OAAO;GACxB,MAAM,YAAY,KAAK,KAAK;GAC5B,MAAM,2BAAc,KAAK,KAAK,CAAC,OAAO;AAEtC,OAAI;IACF,MAAM,UAAU,MAAM,KAAK,IAAI,QAAQ,IAAI,EAAE;IAC7C,MAAMC,aAAW,KAAK,KAAK,GAAG;IAC9B,MAAM,UAAU,KAAK,YAAY,SAASA,WAAS,IAAI,KAAK;AAC5D,YAAQ,QAAQ,QAAQ;AACxB,cAAU;KAAE,GAAG;KAAS,GAAG;KAAS;YAE/B,OAAO;IACZ,MAAM,MAAM,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,MAAM,CAAC;IACrE,MAAM,UAAU,KAAK,UAAU,IAAI,IAAI,KAAK;AAC5C,YAAQ,KAAK,QAAQ;AACrB,UAAM,IAAI,MAAM,SAAS,KAAK,KAAK,YAAY,IAAI,WAAW,EAAE,OAAO,KAAK,CAAC;;;EAIjF,MAAMA,aAAW,KAAK,KAAK,GAAG;AAC9B,SAAO;GAAE;GAAS;GAAU;IAE/B"}

package/dist/index.d.cts

@@ -0,0 +1,62 @@
+import prettyBytes from "pretty-bytes";
+import prettyMs from "pretty-ms";
+
+//#region src/format.d.ts
+/**
+ * Formats byte sizes into human-readable strings
+ * @param size - The size in bytes
+ * @returns Formatted string (e.g., "1.23 kB", "4.56 MB")
+ */
+declare const bytes: typeof prettyBytes;
+/**
+ * Formats milliseconds into human-readable durations
+ * @param ms - The duration in milliseconds
+ * @returns Formatted string (e.g., "42ms", "1.2s", "2m 3.5s")
+ */
+declare const duration: typeof prettyMs;
+/**
+ * Display a formatted list of files in a directory with their sizes
+ * @param baseDir - The base directory to search
+ * @param pattern - Glob pattern to match files
+ * @param width - Row width for file paths
+ * @returns Formatted file list with sizes and total
+ */
+declare function fileList(baseDir: string, pattern?: string, width?: number): string;
+//#endregion
+//#region src/pipeline.d.ts
+/** Base context type - extend this to add your own properties */
+type Context = Record<string, unknown>;
+/**
+ * A task that runs in a pipeline
+ * @template TContext - The context type for this task
+ * @property name - Task name shown in spinner
+ * @property run - Task implementation - return updates to merge into context
+ * @property onSuccess - Optional success message (default: task name)
+ * @property onError - Optional error message (default: task name)
+ */
+interface Task<TContext extends Context> {
+  name: string;
+  run: (ctx: TContext) => Promise<Partial<TContext> | void>;
+  onSuccess?: (ctx: TContext, duration: number) => string;
+  onError?: (error: Error) => string;
+}
+/**
+ * Result after running a pipeline
+ * @template TContext - The context type
+ * @property context - Final context after all tasks
+ * @property duration - Total duration in milliseconds
+ */
+type PipeResult<TContext extends Context> = {
+  context: TContext;
+  duration: number;
+};
+/**
+ * Creates a task pipeline that runs tasks sequentially with spinners
+ * @template TContext - The context type for the pipeline
+ */
+declare function pipe<TContext extends Context>(tasks: Task<TContext>[]): {
+  run: (initialContext: TContext) => Promise<PipeResult<TContext>>;
+};
+//#endregion
+export { Context, PipeResult, Task, bytes, duration, fileList, pipe };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/format.ts","../src/pipeline.ts"],"mappings":";;;;;AAaA;AAOA;AASA;;cAhBa,KAAA,SAAK,WAAA;AAAA;AAOlB;AASA;;;AAhBkB,cAOL,QAAA,SAAQ,QAAA;AAAA;AASrB;;;;AC1BA;AAUA;ADOqB,iBASL,QAAA,CAAA,OAAA,UAAA,OAAA,WAAA,KAAA;;;;KC1BJ,OAAA,GAAU,MAAA;AAAA;AAUtB;;;;;;;AAVsB,UAUL,IAAA,kBAAsB,OAAA;EAAA,IAAA;EAAA,GAAA,GAAA,GAAA,EAE1B,QAAA,KAAa,OAAA,CAAQ,OAAA,CAAQ,QAAA;EAAA,SAAA,IAAA,GAAA,EACtB,QAAA,EAAA,QAAA;EAAA,OAAA,IAAA,KAAA,EACA,KAAA;AAAA;AAAA;;AASpB;AASA;;;AAlBoB,KASR,UAAA,kBAA4B,OAAA;EAAA,OAAA,EAC7B,QAAA;EAAA,QAAA;AAAA;AAAA;AAQX;;;AARW,iBAQK,IAAA,kBAAsB,OAAA,CAAA,CAAA,KAAA,EAAgB,IAAA,CAAK,QAAA;EAAA,GAAA,GAAA,cAAA,EAE3B,QAAA,KAAQ,OAAA,CAAA,UAAA,CAAA,QAAA;AAAA"}

package/dist/index.d.mts

@@ -0,0 +1,62 @@
+import prettyBytes from "pretty-bytes";
+import prettyMs from "pretty-ms";
+
+//#region src/format.d.ts
+/**
+ * Formats byte sizes into human-readable strings
+ * @param size - The size in bytes
+ * @returns Formatted string (e.g., "1.23 kB", "4.56 MB")
+ */
+declare const bytes: typeof prettyBytes;
+/**
+ * Formats milliseconds into human-readable durations
+ * @param ms - The duration in milliseconds
+ * @returns Formatted string (e.g., "42ms", "1.2s", "2m 3.5s")
+ */
+declare const duration: typeof prettyMs;
+/**
+ * Display a formatted list of files in a directory with their sizes
+ * @param baseDir - The base directory to search
+ * @param pattern - Glob pattern to match files
+ * @param width - Row width for file paths
+ * @returns Formatted file list with sizes and total
+ */
+declare function fileList(baseDir: string, pattern?: string, width?: number): string;
+//#endregion
+//#region src/pipeline.d.ts
+/** Base context type - extend this to add your own properties */
+type Context = Record<string, unknown>;
+/**
+ * A task that runs in a pipeline
+ * @template TContext - The context type for this task
+ * @property name - Task name shown in spinner
+ * @property run - Task implementation - return updates to merge into context
+ * @property onSuccess - Optional success message (default: task name)
+ * @property onError - Optional error message (default: task name)
+ */
+interface Task<TContext extends Context> {
+  name: string;
+  run: (ctx: TContext) => Promise<Partial<TContext> | void>;
+  onSuccess?: (ctx: TContext, duration: number) => string;
+  onError?: (error: Error) => string;
+}
+/**
+ * Result after running a pipeline
+ * @template TContext - The context type
+ * @property context - Final context after all tasks
+ * @property duration - Total duration in milliseconds
+ */
+type PipeResult<TContext extends Context> = {
+  context: TContext;
+  duration: number;
+};
+/**
+ * Creates a task pipeline that runs tasks sequentially with spinners
+ * @template TContext - The context type for the pipeline
+ */
+declare function pipe<TContext extends Context>(tasks: Task<TContext>[]): {
+  run: (initialContext: TContext) => Promise<PipeResult<TContext>>;
+};
+//#endregion
+export { Context, PipeResult, Task, bytes, duration, fileList, pipe };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/format.ts","../src/pipeline.ts"],"mappings":";;;;;AAaA;AAOA;AASA;;cAhBa,KAAA,SAAK,WAAA;AAAA;AAOlB;AASA;;;AAhBkB,cAOL,QAAA,SAAQ,QAAA;AAAA;AASrB;;;;AC1BA;AAUA;ADOqB,iBASL,QAAA,CAAA,OAAA,UAAA,OAAA,WAAA,KAAA;;;;KC1BJ,OAAA,GAAU,MAAA;AAAA;AAUtB;;;;;;;AAVsB,UAUL,IAAA,kBAAsB,OAAA;EAAA,IAAA;EAAA,GAAA,GAAA,GAAA,EAE1B,QAAA,KAAa,OAAA,CAAQ,OAAA,CAAQ,QAAA;EAAA,SAAA,IAAA,GAAA,EACtB,QAAA,EAAA,QAAA;EAAA,OAAA,IAAA,KAAA,EACA,KAAA;AAAA;AAAA;;AASpB;AASA;;;AAlBoB,KASR,UAAA,kBAA4B,OAAA;EAAA,OAAA,EAC7B,QAAA;EAAA,QAAA;AAAA;AAAA;AAQX;;;AARW,iBAQK,IAAA,kBAAsB,OAAA,CAAA,CAAA,KAAA,EAAgB,IAAA,CAAK,QAAA;EAAA,GAAA,GAAA,cAAA,EAE3B,QAAA,KAAQ,OAAA,CAAA,UAAA,CAAA,QAAA;AAAA"}

package/dist/index.mjs

@@ -0,0 +1,88 @@
+import { statSync } from "fs";
+import { join } from "path";
+import { fdir } from "fdir";
+import pc from "picocolors";
+import pm from "picomatch";
+import prettyBytes from "pretty-bytes";
+import prettyMs from "pretty-ms";
+import ora from "ora";
+
+//#region src/format.ts
+/**
+* Formats byte sizes into human-readable strings
+* @param size - The size in bytes
+* @returns Formatted string (e.g., "1.23 kB", "4.56 MB")
+*/
+const bytes = prettyBytes;
+/**
+* Formats milliseconds into human-readable durations
+* @param ms - The duration in milliseconds
+* @returns Formatted string (e.g., "42ms", "1.2s", "2m 3.5s")
+*/
+const duration = prettyMs;
+/**
+* Display a formatted list of files in a directory with their sizes
+* @param baseDir - The base directory to search
+* @param pattern - Glob pattern to match files
+* @param width - Row width for file paths
+* @returns Formatted file list with sizes and total
+*/
+function fileList(baseDir, pattern = "**/*", width = 45) {
+	const matcher = pm(pattern, { windows: true });
+	const files = new fdir().withRelativePaths().filter((path) => matcher(path)).crawl(baseDir).sync();
+	const stats = files.map((path) => {
+		const fullPath = join(baseDir, path);
+		return {
+			path: path.replace(/\\/g, "/"),
+			size: statSync(fullPath).size
+		};
+	});
+	const total = stats.reduce((sum, stat) => sum + stat.size, 0);
+	const lines = stats.map(({ path, size }) => {
+		return `  ${pc.cyan(path.padEnd(width))}  ${pc.dim(bytes(size))}`;
+	});
+	const footerLabel = `${files.length} files, total:`.padEnd(width);
+	const footer = `  ${pc.dim(footerLabel)}  ${pc.dim(bytes(total))}`;
+	return [...lines, footer].join("\n");
+}
+
+//#endregion
+//#region src/pipeline.ts
+/**
+* Creates a task pipeline that runs tasks sequentially with spinners
+* @template TContext - The context type for the pipeline
+*/
+function pipe(tasks) {
+	return { run: async (initialContext) => {
+		const startTime = Date.now();
+		let context = initialContext;
+		for (const task of tasks) {
+			const taskStart = Date.now();
+			const spinner = ora(task.name).start();
+			try {
+				const updates = await task.run(context) ?? {};
+				const duration$2 = Date.now() - taskStart;
+				const message = task.onSuccess?.(context, duration$2) ?? task.name;
+				spinner.succeed(message);
+				context = {
+					...context,
+					...updates
+				};
+			} catch (error) {
+				const err = error instanceof Error ? error : new Error(String(error));
+				const message = task.onError?.(err) ?? task.name;
+				spinner.fail(message);
+				throw new Error(`Task "${task.name}" failed: ${err.message}`, { cause: err });
+			}
+		}
+		const duration$1 = Date.now() - startTime;
+		return {
+			context,
+			duration: duration$1
+		};
+	} };
+}
+
+//#endregion
+export { bytes, duration, fileList, pipe };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["duration"],"sources":["../src/format.ts","../src/pipeline.ts"],"sourcesContent":["import { statSync } from 'fs'\r\nimport { join } from 'path'\r\nimport { fdir } from 'fdir'\r\nimport pc from 'picocolors'\r\nimport pm from 'picomatch'\r\nimport prettyBytes from 'pretty-bytes'\r\nimport prettyMs from 'pretty-ms'\r\n\r\n/**\r\n * Formats byte sizes into human-readable strings\r\n * @param size - The size in bytes\r\n * @returns Formatted string (e.g., \"1.23 kB\", \"4.56 MB\")\r\n */\r\nexport const bytes = prettyBytes\r\n\r\n/**\r\n * Formats milliseconds into human-readable durations\r\n * @param ms - The duration in milliseconds\r\n * @returns Formatted string (e.g., \"42ms\", \"1.2s\", \"2m 3.5s\")\r\n */\r\nexport const duration = prettyMs\r\n\r\n/**\r\n * Display a formatted list of files in a directory with their sizes\r\n * @param baseDir - The base directory to search\r\n * @param pattern - Glob pattern to match files\r\n * @param width - Row width for file paths\r\n * @returns Formatted file list with sizes and total\r\n */\r\nexport function fileList(baseDir: string, pattern = '**/*', width = 45) {\r\n  // Find all files matching the pattern\r\n  // Use windows: true option to handle both / and \\ as path separators\r\n  const matcher = pm(pattern, { windows: true })\r\n  const files = new fdir()\r\n    .withRelativePaths()\r\n    .filter(path => matcher(path))\r\n    .crawl(baseDir)\r\n    .sync()\r\n\r\n  const stats = files.map(path => {\r\n    const fullPath = join(baseDir, path)\r\n    const displayPath = path.replace(/\\\\/g, '/')\r\n    return {\r\n      path: displayPath,\r\n      size: statSync(fullPath).size,\r\n    }\r\n  })\r\n\r\n  const total = stats.reduce((sum, stat) => sum + stat.size, 0)\r\n  const lines = stats.map(({ path, size }) => {\r\n    const paddedPath = pc.cyan(path.padEnd(width))\r\n    const formattedSize = pc.dim(bytes(size))\r\n    return `  ${paddedPath}  ${formattedSize}`\r\n  })\r\n\r\n  const footerLabel = `${files.length} files, total:`.padEnd(width)\r\n  const footer = `  ${pc.dim(footerLabel)}  ${pc.dim(bytes(total))}`\r\n  return [...lines, footer].join('\\n')\r\n}\r\n","import ora from 'ora'\r\n\r\n/** Base context type - extend this to add your own properties */\r\nexport type Context = Record<string, unknown>\r\n\r\n/**\r\n * A task that runs in a pipeline\r\n * @template TContext - The context type for this task\r\n * @property name - Task name shown in spinner\r\n * @property run - Task implementation - return updates to merge into context\r\n * @property onSuccess - Optional success message (default: task name)\r\n * @property onError - Optional error message (default: task name)\r\n */\r\nexport interface Task<TContext extends Context> {\r\n  name: string\r\n  run: (ctx: TContext) => Promise<Partial<TContext> | void>\r\n  onSuccess?: (ctx: TContext, duration: number) => string\r\n  onError?: (error: Error) => string\r\n}\r\n\r\n/**\r\n * Result after running a pipeline\r\n * @template TContext - The context type\r\n * @property context - Final context after all tasks\r\n * @property duration - Total duration in milliseconds\r\n */\r\nexport type PipeResult<TContext extends Context> = {\r\n  context: TContext\r\n  duration: number\r\n}\r\n\r\n/**\r\n * Creates a task pipeline that runs tasks sequentially with spinners\r\n * @template TContext - The context type for the pipeline\r\n */\r\nexport function pipe<TContext extends Context>(tasks: Task<TContext>[]) {\r\n  return {\r\n    run: async (initialContext: TContext) => {\r\n      const startTime = Date.now()\r\n      let context = initialContext\r\n\r\n      for (const task of tasks) {\r\n        const taskStart = Date.now()\r\n        const spinner = ora(task.name).start()\r\n\r\n        try {\r\n          const updates = await task.run(context) ?? {}\r\n          const duration = Date.now() - taskStart\r\n          const message = task.onSuccess?.(context, duration) ?? task.name\r\n          spinner.succeed(message)\r\n          context = { ...context, ...updates }\r\n        }\r\n        catch (error) {\r\n          const err = error instanceof Error ? error : new Error(String(error))\r\n          const message = task.onError?.(err) ?? task.name\r\n          spinner.fail(message)\r\n          throw new Error(`Task \"${task.name}\" failed: ${err.message}`, { cause: err })\r\n        }\r\n      }\r\n\r\n      const duration = Date.now() - startTime\r\n      return { context, duration } as PipeResult<TContext>\r\n    },\r\n  }\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;AAaA,MAAa,QAAQ;;;;;;AAOrB,MAAa,WAAW;;;;;;;;AASxB,SAAgB,SAAS,SAAiB,UAAU,QAAQ,QAAQ,IAAI;CAGtE,MAAM,UAAU,GAAG,SAAS,EAAE,SAAS,MAAM,CAAC;CAC9C,MAAM,QAAQ,IAAI,MAAM,CACrB,mBAAmB,CACnB,QAAO,SAAQ,QAAQ,KAAK,CAAC,CAC7B,MAAM,QAAQ,CACd,MAAM;CAET,MAAM,QAAQ,MAAM,KAAI,SAAQ;EAC9B,MAAM,WAAW,KAAK,SAAS,KAAK;AAEpC,SAAO;GACL,MAFkB,KAAK,QAAQ,OAAO,IAAI;GAG1C,MAAM,SAAS,SAAS,CAAC;GAC1B;GACD;CAEF,MAAM,QAAQ,MAAM,QAAQ,KAAK,SAAS,MAAM,KAAK,MAAM,EAAE;CAC7D,MAAM,QAAQ,MAAM,KAAK,EAAE,MAAM,WAAW;AAG1C,SAAO,KAFY,GAAG,KAAK,KAAK,OAAO,MAAM,CAAC,CAEvB,IADD,GAAG,IAAI,MAAM,KAAK,CAAC;GAEzC;CAEF,MAAM,cAAc,GAAG,MAAM,OAAO,gBAAgB,OAAO,MAAM;CACjE,MAAM,SAAS,KAAK,GAAG,IAAI,YAAY,CAAC,IAAI,GAAG,IAAI,MAAM,MAAM,CAAC;AAChE,QAAO,CAAC,GAAG,OAAO,OAAO,CAAC,KAAK,KAAK;;;;;;;;;ACtBtC,SAAgB,KAA+B,OAAyB;AACtE,QAAO,EACL,KAAK,OAAO,mBAA6B;EACvC,MAAM,YAAY,KAAK,KAAK;EAC5B,IAAI,UAAU;AAEd,OAAK,MAAM,QAAQ,OAAO;GACxB,MAAM,YAAY,KAAK,KAAK;GAC5B,MAAM,UAAU,IAAI,KAAK,KAAK,CAAC,OAAO;AAEtC,OAAI;IACF,MAAM,UAAU,MAAM,KAAK,IAAI,QAAQ,IAAI,EAAE;IAC7C,MAAMA,aAAW,KAAK,KAAK,GAAG;IAC9B,MAAM,UAAU,KAAK,YAAY,SAASA,WAAS,IAAI,KAAK;AAC5D,YAAQ,QAAQ,QAAQ;AACxB,cAAU;KAAE,GAAG;KAAS,GAAG;KAAS;YAE/B,OAAO;IACZ,MAAM,MAAM,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,MAAM,CAAC;IACrE,MAAM,UAAU,KAAK,UAAU,IAAI,IAAI,KAAK;AAC5C,YAAQ,KAAK,QAAQ;AACrB,UAAM,IAAI,MAAM,SAAS,KAAK,KAAK,YAAY,IAAI,WAAW,EAAE,OAAO,KAAK,CAAC;;;EAIjF,MAAMA,aAAW,KAAK,KAAK,GAAG;AAC9B,SAAO;GAAE;GAAS;GAAU;IAE/B"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@idlesummer/tasker",
+  "version": "0.1.0",
+  "description": "A simple task pipeline runner with CLI spinners and formatters",
+  "keywords": [
+    "task",
+    "pipeline",
+    "build",
+    "runner",
+    "spinner",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/idlesummer/tasker.git"
+  },
+  "license": "MIT",
+  "author": "idlesummer <09louisthebob@gmail.com> (https://github.com/idlesummer)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "workspaces": [
+    "examples/*"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:ui": "vitest --ui",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "fdir": "^6.4.2",
+    "ora": "^8.1.1",
+    "picocolors": "^1.1.1",
+    "picomatch": "^4.0.2",
+    "pretty-bytes": "^6.1.1",
+    "pretty-ms": "^9.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^22.10.5",
+    "@types/picomatch": "^3.0.1",
+    "@vitest/ui": "^4.0.17",
+    "eslint": "^9.39.2",
+    "globals": "^17.0.0",
+    "tsdown": "^0.20.0-beta.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.53.0",
+    "vitest": "^4.0.17"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}