{"id":19778324,"url":"https://github.com/npkgz/async-magic","last_synced_at":"2026-04-15T07:36:08.387Z","repository":{"id":51858715,"uuid":"92400696","full_name":"npkgz/async-magic","owner":"npkgz","description":"Promises FTW! A pure promised based, async toolbox for Node.js \u003e=7.6","archived":false,"fork":false,"pushed_at":"2021-05-24T12:08:58.000Z","size":131,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-26T00:49:32.044Z","etag":null,"topics":["async","async-await","control-flow","es2017","javascript","library","nodejs","promise","promisify","toolbox"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/async-magic","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/npkgz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-25T12:21:15.000Z","updated_at":"2024-09-01T07:28:03.000Z","dependencies_parsed_at":"2022-09-14T09:01:20.310Z","dependency_job_id":null,"html_url":"https://github.com/npkgz/async-magic","commit_stats":null,"previous_names":["andidittrich/node.async-magic"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/npkgz/async-magic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npkgz%2Fasync-magic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npkgz%2Fasync-magic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npkgz%2Fasync-magic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npkgz%2Fasync-magic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/npkgz","download_url":"https://codeload.github.com/npkgz/async-magic/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npkgz%2Fasync-magic/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31831847,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T07:17:56.427Z","status":"ssl_error","status_checked_at":"2026-04-15T07:17:30.007Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","async-await","control-flow","es2017","javascript","library","nodejs","promise","promisify","toolbox"],"created_at":"2024-11-12T05:28:55.118Z","updated_at":"2026-04-15T07:36:08.358Z","avatar_url":"https://github.com/npkgz.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/AndiDittrich/Node.async-magic.svg?branch=master)](https://travis-ci.org/AndiDittrich/Node.async-magic)\n\nasync-magic\n=========================\n\nPromises FTW! A pure promised based, straight forward async library for Node.js **\u003e=7.6**.\n\n```\nyarn add async-magic --save\n```\n\nFeatures\n------------------------------\n\n* Convert callback based functions into promised based once (with named functions)\n* Advanced promised based control flows (parallel, series)\n* Run a set of promised functions in parallel with given number of maximum parallel tasks\n* Queue promised based function including arguments\n* Standalone, no external dependencies required\n* Designed to run with the pure power of native `Promise`, `await` and `async function`\n* No backward compatibility layer\n\nAPI\n------------------------------\n\n * [promisify](#promisify) - Promisify a callback-based function\n * [promisifyAll](#promisifyall) - Promisify a set of callback-based functions\n * [parallel](#parallel) - Executes multiple `PromiseResolver` in parallel with given task limit\n * [series](#series) - Executes multiple `PromiseResolver` in series\n * [PromiseResolver](#promiseresolver) - Utility function to cache a promised function including arguments for resolving. Required for advanced, promised based, control flows\n * [wait](#wait) - [Promise.all](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all) alias\n * [sleep](#sleep) - Intercept the current function execution\n * [Mutex](#mutex) - asynchronous Mutex lock pattern\n\n\npromisify\n------------------------------\n\n**Description:** Promisify a callback-based function\n\n**Requirements:**\n\n * Last function argument has to be the callback (Nodejs Standard)\n * The first argument of the callback has to be a possible error (Nodejs Standard)\n\n**Syntax:** `fn:function = promisify(fn:function, [functionName:String])`\n\n**Arguments:**\n\n * fn:function - the callback based function which should be converted into a promise based\n * functionName:String(optinal) - an optional name which is used as native js function name\n\n**Example:**\n\n```js\nconst _asyncMagic = require('async-magic');\nconst _fs = require('fs');\n\n// create promisified fs-stat. set \"stat\" as native function name\nconst fsStat = _asyncMagic.promisify(_fs, 'stat');\n\n// use promisified version\n(async function(){\n    const fstats = await _fsStat(__filename);\n    console.log('Size:', fstats.size);\n})();\n```\n\npromisifyAll\n------------------------------\n\n**Description:** Promisify a set of callback-based functions\n\n**Syntax:** `promisifiedFunctionSet:Object = promisifyAll(functionSet:Object, functionNames:StringArray)`\n\n**Arguments:**\n\n * functionSet:Object - a set of functions identified by the objects keys\n * functionNames:StringArray - a list of the object keys which should be promisified (names are also taken as native function names!)\n\n**Example:**\n\nPromisify some fs functions. Just as showcase, take a look at [fs-magic](https://www.npmjs.com/package/fs-magic) - it is based on async-magic.\n\n```js\nconst _asyncMagic = require('async-magic');\nconst _fs = require('fs');\n\n// list of fs methods to promisify\nconst fsApi = [\n    'access',\n    'appendFile',\n    'chmod'\n];\n\n// create promisified fs version\nconst _fsPromised = _asyncMagic.promisifyAll(_fs, fsApi);\n\n// use promisified version\n(async function(){\n    const fstats = await _fsPromised.stat(__filename);\n    console.log('Size:', fstats.size);\n})();\n```\n\nparallel\n------------------------------\n\n**Description:** Executes multiple `PromiseResolver` in parallel with given task limit\n\n**Syntax:** `results:array = parallel(resolvers:array, [limit:int=1000])`\n\n```js\nconst _asyncMagic = require('async-magic');\nconst _fsMagic = require('fs-magic');\nconst PromiseResolver = _asyncMagic.PromiseResolver;\n\n(async function(){\n    // task list\n    const tasks = [];\n    \n    // stat a large list of files \n    tasks.push(PromiseResolver(_fsMagic.stat, 'file1.txt'));\n    tasks.push(PromiseResolver(_fsMagic.stat, 'file2.txt'));\n    ...\n    tasks.push(PromiseResolver(_fsMagic.stat, 'fileN.txt'));\n    \n    // resolves the promise with predefined arguments\n    // limit the number of parallel executed promises to 100 (IO handle limitation)\n    const stats = await _asyncMagic.parallel(tasks, 100);\n})();\n```\n\nseries\n------------------------------\n\n**Description:** Executes multiple `PromiseResolver` in series\n\n**Syntax:** `results:array = series(resolvers:array, [failOnError:boolean=true])`\n\nIn case `failOnError` is not set, the resultset will contain the error object thrown during execution. Otherwise the executor will abort directly if an error has been thrown.\n\n```js\nconst _asyncMagic = require('async-magic');\nconst _fsMagic = require('fs-magic');\nconst PromiseResolver = _asyncMagic.PromiseResolver;\n\n(async function(){\n    // task list\n    const tasks = [];\n    \n    // stat a large list of files \n    tasks.push(PromiseResolver(_fsMagic.stat, 'file1.txt'));\n    tasks.push(PromiseResolver(_fsMagic.stat, 'file2.txt'));\n    ...\n    tasks.push(PromiseResolver(_fsMagic.stat, 'fileN.txt'));\n    \n    // resolves the promise with predefined arguments)\n    const stats = await _asyncMagic.series(tasks);\n})();\n```\n\nPromiseResolver\n------------------------------\n\n**Description:** Utility function to cache a promised function including arguments for resolving. Required for advanced, promised based, control flows\n\n**Syntax:** `p:PromiseResolver = PromiseResolver(fn:function, [...args:any])`\n\n```js\nconst _asyncMagic = require('async-magic');\nconst _fsMagic = require('fs-magic');\nconst PromiseResolver = _asyncMagic.PromiseResolver;\n\n(async function(){\n    // caches the function with given arguments\n    const task = PromiseResolver(_fsMagic.stat, 'file1.txt');\n    \n    // resolves the promise with predefined arguments\n    const stat = await task.resolve();\n})();\n```\n\nwait\n------------------------------\n\n**Description:** A [Promise.all](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all) alias - waits until each promise has been completed or a single error occurs\n\n**Syntax:** `p:Promise = wait(promises:Array)`\n\n```js\nconst _asyncMagic = require('async-magic');\nconst _fsMagic = require('fs-magic');\n\n// stat multiple files at once\n(async function(){\n    const stats = await _asyncMagic.wait([\n        _fsMagic.stat('file1.txt'),\n        _fsMagic.stat('file2.txt'),\n        _fsMagic.stat('file3.txt')\n    ]);\n})();\n```\n\nsleep\n------------------------------\n\n**Description:** Intercept the current function exection for a given time asynchronous (does not stop the global event loop!)\n\n**Syntax:** `p:Promise = sleep(time:int)`\n\n```js\nconst _asyncMagic = require('async-magic');\n\n(async function(){\n    console('Hello..');\n\n    // stop function execution for 1s (asynchronous!)\n    await _asyncMagic.sleep(1000);\n\n    console.log('World');\n})();\n```\n\nMutex\n------------------------------\n\n**Description:** Mutex lock pattern for asynchronous operations\n\n**Syntax:** `p:Mutex = new Mutex()`\n\n```js\nconst _asyncMagic = require('async-magic');\n\n(async function IOtask(){\n   // create Mutex\n    const mutex = new _asyncMagic.Mutex();\n\n    // acquire lock\n    await mutex.acquire();\n\n    // do something exclusively\n    await directIoOperation();\n\n    // unlock\n    mutex.release();\n})();\n```\n\n\nFAQ\n------------------------------\n\n**What is the difference between named and anonymous functions ? (promisify)**\n\nNamed functions contains its function-name as immutable `.name` attribute. This is especially useful during debugging, because the stacktrace will display the plain-text function name instead of \"anonymous\"\n\n```js\nconst _asyncMagic = require('../async-magic');\nconst _fs = require('fs');\n\n// create a unnamed (standard) version and a named one\nconst promisedStat = _asyncMagic.promisify(_fs.stat);\nconst namedPromisedStat = _asyncMagic.promisify(_fs.stat, 'stat');\n\n// show function names (immutable .name attribute is set)\nconsole.log(promisedStat.name); //=\u003e anonymous\nconsole.log(namedPromisedStat.name); //=\u003e stat\n```\n\nAny Questions ? Report a Bug ? Enhancements ?\n---------------------------------------------\nPlease open a new issue on [GitHub](https://github.com/AndiDittrich/Node.async-magic/issues)\n\nLicense\n-------\nasync-magic is OpenSource and licensed under the Terms of [The MIT License](LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpkgz%2Fasync-magic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnpkgz%2Fasync-magic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpkgz%2Fasync-magic/lists"}