with-ease-progress 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# with-ease-progress
+
+Smooth progress tracking for async tasks in JavaScript/TypeScript.
+
+## Installation
+
+```bash
+npm install with-ease-progress
+# or
+yarn add with-ease-progress
+```
+
+## Usage
+
+### Direct
+
+```typescript
+import { withProgress } from "with-ease-progress";
+
+// Simulate an async task
+await withProgress(
+  async (update) => {
+    for (let i = 0; i <= 100; i += 10) {
+      await new Promise(r => setTimeout(r, 100));
+      update({ loaded: i, total: 100 });
+    }
+  },
+  {
+    minDuration: 2000,
+    onProgress: (p) => console.log("Progress:", p + "%"),
+  }
+);
+
+// Output:
+//   Progress: 10%
+//   Progress: 25%
+//   Progress: 40%
+//   ...
+```
+
+- `update` is a function that accepts an object `{ loaded: number, total: number }`
+- `onProgress` is called with the smooth progress percentage
+- `minDuration` ensures the progress bar moves smoothly even if the task finishes quickly
+
+### Curryable (functional-friendly)
+
+```typescript
+const uploadWithProgress = withProgress({
+  minDuration: 1500,
+  onProgress: p => console.log(p),
+});
+
+await uploadWithProgress(update => uploadFile(update));
+```
+
+### Features
+
+- Works with any async task
+- Smooth progress updates, prevents jumps
+- Supports TypeScript and provides typings
+- Functional-friendly / curryable usage
+- ESM + CJS compatible
+
+### License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,14 @@
+type ProgressEventLike = {
+    loaded?: number;
+    total?: number;
+};
+type ProgressHandler = (e: ProgressEventLike) => void;
+type Task<T> = (update: ProgressHandler) => Promise<T>;
+interface ProgressOptions {
+    minDuration?: number;
+    onProgress?: (percent: number) => void;
+}
+declare function withProgress<T>(task: Task<T>, options?: ProgressOptions): Promise<T>;
+declare function withProgress(options: ProgressOptions): <T>(task: Task<T>) => Promise<T>;
+
+export { type ProgressEventLike, type ProgressHandler, type ProgressOptions, type Task, withProgress };

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+type ProgressEventLike = {
+    loaded?: number;
+    total?: number;
+};
+type ProgressHandler = (e: ProgressEventLike) => void;
+type Task<T> = (update: ProgressHandler) => Promise<T>;
+interface ProgressOptions {
+    minDuration?: number;
+    onProgress?: (percent: number) => void;
+}
+declare function withProgress<T>(task: Task<T>, options?: ProgressOptions): Promise<T>;
+declare function withProgress(options: ProgressOptions): <T>(task: Task<T>) => Promise<T>;
+
+export { type ProgressEventLike, type ProgressHandler, type ProgressOptions, type Task, withProgress };

package/dist/index.js

@@ -0,0 +1,91 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  withProgress: () => withProgress
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_MIN_DURATION = 2e3;
+function withProgress(arg1, arg2) {
+  if (typeof arg1 === "function") {
+    return runWithProgress(arg1, arg2);
+  }
+  return (task) => runWithProgress(task, arg1);
+}
+async function runWithProgress(task, options = {}) {
+  const {
+    minDuration = DEFAULT_MIN_DURATION,
+    onProgress
+  } = options;
+  const controller = onProgress ? createProgressController(minDuration, onProgress) : null;
+  const startTime = Date.now();
+  let result;
+  let error;
+  try {
+    result = await task((controller == null ? void 0 : controller.updateReal) ?? noop);
+  } catch (e) {
+    error = e;
+  }
+  const elapsed = Date.now() - startTime;
+  const remaining = minDuration - elapsed;
+  if (remaining > 0) {
+    await sleep(remaining);
+  }
+  controller == null ? void 0 : controller.stop();
+  if (error) throw error;
+  return result;
+}
+function createProgressController(minDuration, onProgress) {
+  const start = Date.now();
+  let lastPercent = 0;
+  const update = (realPercent = 0) => {
+    const elapsed = Date.now() - start;
+    const easedPercent = Math.min(
+      99,
+      Math.round(elapsed / minDuration * 100)
+    );
+    const percent = Math.max(easedPercent, realPercent);
+    if (percent > lastPercent && percent < 100) {
+      lastPercent = percent;
+      onProgress(percent);
+    }
+  };
+  const interval = setInterval(update, 50);
+  return {
+    updateReal(event) {
+      const real = event.total ? Math.round(event.loaded * 100 / event.total) : 0;
+      update(real);
+    },
+    stop() {
+      clearInterval(interval);
+      onProgress(100);
+    }
+  };
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function noop() {
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  withProgress
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export type ProgressEventLike = {\n  loaded?: number;\n  total?: number;\n};\n\nexport type ProgressHandler = (e: ProgressEventLike) => void;\n\nexport type Task<T> = (update: ProgressHandler) => Promise<T>;\n\nexport interface ProgressOptions {\n  minDuration?: number;\n  onProgress?: (percent: number) => void;\n}\n\nconst DEFAULT_MIN_DURATION = 2000;\n\nexport function withProgress<T>(\n  task: Task<T>,\n  options?: ProgressOptions,\n): Promise<T>;\n\nexport function withProgress(\n  options: ProgressOptions,\n): <T>(task: Task<T>) => Promise<T>;\n\nexport function withProgress<T>(\n  arg1: Task<T> | ProgressOptions,\n  arg2?: ProgressOptions,\n) {\n  if (typeof arg1 === \"function\") {\n    return runWithProgress(arg1, arg2);\n  }\n\n  return <T>(task: Task<T>) => runWithProgress(task, arg1);\n}\n\nasync function runWithProgress<T>(\n  task: Task<T>,\n  options: ProgressOptions = {},\n): Promise<T> {\n  const {\n    minDuration = DEFAULT_MIN_DURATION,\n    onProgress,\n  } = options;\n\n  const controller = onProgress\n    ? createProgressController(minDuration, onProgress)\n    : null;\n\n  const startTime = Date.now();\n  let result: T | undefined;\n  let error: unknown;\n\n  try {\n    result = await task(controller?.updateReal ?? noop);\n  } catch (e) {\n    error = e;\n  }\n\n  const elapsed = Date.now() - startTime;\n  const remaining = minDuration - elapsed;\n\n  if (remaining > 0) {\n    await sleep(remaining);\n  }\n\n  controller?.stop();\n\n  if (error) throw error;\n  return result as T;\n}\n\nfunction createProgressController(\n  minDuration: number,\n  onProgress: (p: number) => void,\n) {\n  const start = Date.now();\n  let lastPercent = 0;\n\n  const update = (realPercent = 0) => {\n    const elapsed = Date.now() - start;\n\n    const easedPercent = Math.min(\n      99,\n      Math.round((elapsed / minDuration) * 100),\n    );\n\n    const percent = Math.max(easedPercent, realPercent);\n\n    if (percent > lastPercent && percent < 100) {\n      lastPercent = percent;\n      onProgress(percent);\n    }\n  };\n\n  const interval = setInterval(update, 50);\n\n  return {\n    updateReal(event: ProgressEventLike) {\n      const real = event.total\n        ? Math.round((event.loaded! * 100) / event.total)\n        : 0;\n\n      update(real);\n    },\n\n    stop() {\n      clearInterval(interval);\n      onProgress(100);\n    },\n  };\n}\n\nfunction sleep(ms: number) {\n  return new Promise(resolve => setTimeout(resolve, ms));\n}\n\nfunction noop() { }\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAcA,IAAM,uBAAuB;AAWtB,SAAS,aACd,MACA,MACA;AACA,MAAI,OAAO,SAAS,YAAY;AAC9B,WAAO,gBAAgB,MAAM,IAAI;AAAA,EACnC;AAEA,SAAO,CAAI,SAAkB,gBAAgB,MAAM,IAAI;AACzD;AAEA,eAAe,gBACb,MACA,UAA2B,CAAC,GAChB;AACZ,QAAM;AAAA,IACJ,cAAc;AAAA,IACd;AAAA,EACF,IAAI;AAEJ,QAAM,aAAa,aACf,yBAAyB,aAAa,UAAU,IAChD;AAEJ,QAAM,YAAY,KAAK,IAAI;AAC3B,MAAI;AACJ,MAAI;AAEJ,MAAI;AACF,aAAS,MAAM,MAAK,yCAAY,eAAc,IAAI;AAAA,EACpD,SAAS,GAAG;AACV,YAAQ;AAAA,EACV;AAEA,QAAM,UAAU,KAAK,IAAI,IAAI;AAC7B,QAAM,YAAY,cAAc;AAEhC,MAAI,YAAY,GAAG;AACjB,UAAM,MAAM,SAAS;AAAA,EACvB;AAEA,2CAAY;AAEZ,MAAI,MAAO,OAAM;AACjB,SAAO;AACT;AAEA,SAAS,yBACP,aACA,YACA;AACA,QAAM,QAAQ,KAAK,IAAI;AACvB,MAAI,cAAc;AAElB,QAAM,SAAS,CAAC,cAAc,MAAM;AAClC,UAAM,UAAU,KAAK,IAAI,IAAI;AAE7B,UAAM,eAAe,KAAK;AAAA,MACxB;AAAA,MACA,KAAK,MAAO,UAAU,cAAe,GAAG;AAAA,IAC1C;AAEA,UAAM,UAAU,KAAK,IAAI,cAAc,WAAW;AAElD,QAAI,UAAU,eAAe,UAAU,KAAK;AAC1C,oBAAc;AACd,iBAAW,OAAO;AAAA,IACpB;AAAA,EACF;AAEA,QAAM,WAAW,YAAY,QAAQ,EAAE;AAEvC,SAAO;AAAA,IACL,WAAW,OAA0B;AACnC,YAAM,OAAO,MAAM,QACf,KAAK,MAAO,MAAM,SAAU,MAAO,MAAM,KAAK,IAC9C;AAEJ,aAAO,IAAI;AAAA,IACb;AAAA,IAEA,OAAO;AACL,oBAAc,QAAQ;AACtB,iBAAW,GAAG;AAAA,IAChB;AAAA,EACF;AACF;AAEA,SAAS,MAAM,IAAY;AACzB,SAAO,IAAI,QAAQ,aAAW,WAAW,SAAS,EAAE,CAAC;AACvD;AAEA,SAAS,OAAO;AAAE;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,67 @@
+// src/index.ts
+var DEFAULT_MIN_DURATION = 2e3;
+function withProgress(arg1, arg2) {
+  if (typeof arg1 === "function") {
+    return runWithProgress(arg1, arg2);
+  }
+  return (task) => runWithProgress(task, arg1);
+}
+async function runWithProgress(task, options = {}) {
+  const {
+    minDuration = DEFAULT_MIN_DURATION,
+    onProgress
+  } = options;
+  const controller = onProgress ? createProgressController(minDuration, onProgress) : null;
+  const startTime = Date.now();
+  let result;
+  let error;
+  try {
+    result = await task((controller == null ? void 0 : controller.updateReal) ?? noop);
+  } catch (e) {
+    error = e;
+  }
+  const elapsed = Date.now() - startTime;
+  const remaining = minDuration - elapsed;
+  if (remaining > 0) {
+    await sleep(remaining);
+  }
+  controller == null ? void 0 : controller.stop();
+  if (error) throw error;
+  return result;
+}
+function createProgressController(minDuration, onProgress) {
+  const start = Date.now();
+  let lastPercent = 0;
+  const update = (realPercent = 0) => {
+    const elapsed = Date.now() - start;
+    const easedPercent = Math.min(
+      99,
+      Math.round(elapsed / minDuration * 100)
+    );
+    const percent = Math.max(easedPercent, realPercent);
+    if (percent > lastPercent && percent < 100) {
+      lastPercent = percent;
+      onProgress(percent);
+    }
+  };
+  const interval = setInterval(update, 50);
+  return {
+    updateReal(event) {
+      const real = event.total ? Math.round(event.loaded * 100 / event.total) : 0;
+      update(real);
+    },
+    stop() {
+      clearInterval(interval);
+      onProgress(100);
+    }
+  };
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function noop() {
+}
+export {
+  withProgress
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export type ProgressEventLike = {\n  loaded?: number;\n  total?: number;\n};\n\nexport type ProgressHandler = (e: ProgressEventLike) => void;\n\nexport type Task<T> = (update: ProgressHandler) => Promise<T>;\n\nexport interface ProgressOptions {\n  minDuration?: number;\n  onProgress?: (percent: number) => void;\n}\n\nconst DEFAULT_MIN_DURATION = 2000;\n\nexport function withProgress<T>(\n  task: Task<T>,\n  options?: ProgressOptions,\n): Promise<T>;\n\nexport function withProgress(\n  options: ProgressOptions,\n): <T>(task: Task<T>) => Promise<T>;\n\nexport function withProgress<T>(\n  arg1: Task<T> | ProgressOptions,\n  arg2?: ProgressOptions,\n) {\n  if (typeof arg1 === \"function\") {\n    return runWithProgress(arg1, arg2);\n  }\n\n  return <T>(task: Task<T>) => runWithProgress(task, arg1);\n}\n\nasync function runWithProgress<T>(\n  task: Task<T>,\n  options: ProgressOptions = {},\n): Promise<T> {\n  const {\n    minDuration = DEFAULT_MIN_DURATION,\n    onProgress,\n  } = options;\n\n  const controller = onProgress\n    ? createProgressController(minDuration, onProgress)\n    : null;\n\n  const startTime = Date.now();\n  let result: T | undefined;\n  let error: unknown;\n\n  try {\n    result = await task(controller?.updateReal ?? noop);\n  } catch (e) {\n    error = e;\n  }\n\n  const elapsed = Date.now() - startTime;\n  const remaining = minDuration - elapsed;\n\n  if (remaining > 0) {\n    await sleep(remaining);\n  }\n\n  controller?.stop();\n\n  if (error) throw error;\n  return result as T;\n}\n\nfunction createProgressController(\n  minDuration: number,\n  onProgress: (p: number) => void,\n) {\n  const start = Date.now();\n  let lastPercent = 0;\n\n  const update = (realPercent = 0) => {\n    const elapsed = Date.now() - start;\n\n    const easedPercent = Math.min(\n      99,\n      Math.round((elapsed / minDuration) * 100),\n    );\n\n    const percent = Math.max(easedPercent, realPercent);\n\n    if (percent > lastPercent && percent < 100) {\n      lastPercent = percent;\n      onProgress(percent);\n    }\n  };\n\n  const interval = setInterval(update, 50);\n\n  return {\n    updateReal(event: ProgressEventLike) {\n      const real = event.total\n        ? Math.round((event.loaded! * 100) / event.total)\n        : 0;\n\n      update(real);\n    },\n\n    stop() {\n      clearInterval(interval);\n      onProgress(100);\n    },\n  };\n}\n\nfunction sleep(ms: number) {\n  return new Promise(resolve => setTimeout(resolve, ms));\n}\n\nfunction noop() { }\n"],"mappings":";AAcA,IAAM,uBAAuB;AAWtB,SAAS,aACd,MACA,MACA;AACA,MAAI,OAAO,SAAS,YAAY;AAC9B,WAAO,gBAAgB,MAAM,IAAI;AAAA,EACnC;AAEA,SAAO,CAAI,SAAkB,gBAAgB,MAAM,IAAI;AACzD;AAEA,eAAe,gBACb,MACA,UAA2B,CAAC,GAChB;AACZ,QAAM;AAAA,IACJ,cAAc;AAAA,IACd;AAAA,EACF,IAAI;AAEJ,QAAM,aAAa,aACf,yBAAyB,aAAa,UAAU,IAChD;AAEJ,QAAM,YAAY,KAAK,IAAI;AAC3B,MAAI;AACJ,MAAI;AAEJ,MAAI;AACF,aAAS,MAAM,MAAK,yCAAY,eAAc,IAAI;AAAA,EACpD,SAAS,GAAG;AACV,YAAQ;AAAA,EACV;AAEA,QAAM,UAAU,KAAK,IAAI,IAAI;AAC7B,QAAM,YAAY,cAAc;AAEhC,MAAI,YAAY,GAAG;AACjB,UAAM,MAAM,SAAS;AAAA,EACvB;AAEA,2CAAY;AAEZ,MAAI,MAAO,OAAM;AACjB,SAAO;AACT;AAEA,SAAS,yBACP,aACA,YACA;AACA,QAAM,QAAQ,KAAK,IAAI;AACvB,MAAI,cAAc;AAElB,QAAM,SAAS,CAAC,cAAc,MAAM;AAClC,UAAM,UAAU,KAAK,IAAI,IAAI;AAE7B,UAAM,eAAe,KAAK;AAAA,MACxB;AAAA,MACA,KAAK,MAAO,UAAU,cAAe,GAAG;AAAA,IAC1C;AAEA,UAAM,UAAU,KAAK,IAAI,cAAc,WAAW;AAElD,QAAI,UAAU,eAAe,UAAU,KAAK;AAC1C,oBAAc;AACd,iBAAW,OAAO;AAAA,IACpB;AAAA,EACF;AAEA,QAAM,WAAW,YAAY,QAAQ,EAAE;AAEvC,SAAO;AAAA,IACL,WAAW,OAA0B;AACnC,YAAM,OAAO,MAAM,QACf,KAAK,MAAO,MAAM,SAAU,MAAO,MAAM,KAAK,IAC9C;AAEJ,aAAO,IAAI;AAAA,IACb;AAAA,IAEA,OAAO;AACL,oBAAc,QAAQ;AACtB,iBAAW,GAAG;AAAA,IAChB;AAAA,EACF;AACF;AAEA,SAAS,MAAM,IAAY;AACzB,SAAO,IAAI,QAAQ,aAAW,WAAW,SAAS,EAAE,CAAC;AACvD;AAEA,SAAS,OAAO;AAAE;","names":[]}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "with-ease-progress",
+  "version": "0.1.0",
+  "description": "Smooth progress tracking for async tasks",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/matthieupinte/with-ease-progress.git"
+  },
+  "keywords": [
+    "progress",
+    "async",
+    "task",
+    "smooth",
+    "ease",
+    "typescript",
+    "javascript"
+  ],
+  "author": "Matthieu Pinte",
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}