{"id":20800332,"url":"https://github.com/maxtermax/lux-io","last_synced_at":"2026-04-21T17:31:33.214Z","repository":{"id":41663379,"uuid":"257476197","full_name":"Maxtermax/lux-io","owner":"Maxtermax","description":"Is a tiny javascript library for handle concurrent promise execution, limiting the maximum amount of promises execution at the same time","archived":false,"fork":false,"pushed_at":"2023-03-04T13:44:27.000Z","size":827,"stargazers_count":0,"open_issues_count":12,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-19T02:36:59.615Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Maxtermax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-21T04:06:12.000Z","updated_at":"2022-12-27T18:23:00.000Z","dependencies_parsed_at":"2023-02-05T06:30:27.130Z","dependency_job_id":null,"html_url":"https://github.com/Maxtermax/lux-io","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maxtermax%2Flux-io","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maxtermax%2Flux-io/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maxtermax%2Flux-io/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maxtermax%2Flux-io/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Maxtermax","download_url":"https://codeload.github.com/Maxtermax/lux-io/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243147274,"owners_count":20243744,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-17T18:13:20.422Z","updated_at":"2026-04-21T17:31:33.177Z","avatar_url":"https://github.com/Maxtermax.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lux-io\nLux io is a simple class that allow you to perform promises excecutions in queue, the excecution queue have a maximum number of concurrent promises that can be execute at the same time.\n\nThe applications in this library have no limits, only your imagination.\n\n# Installation\n```\nnpm i @maxtermax/lux-io --save\n```\n\n# Get started\nIn order to use lux-io you should import it first, then create a new instance of the class lx, now the instance have the main method of lux-io which is `push`, this method allow you to add n amount of operations, a operation is defined as and object that have all information to perform a promise execution\n\n```javascript\nimport { Lx } from '@maxtermax/lux-io'; //import lux-io\nconst MAX_CONCURRENT_PROMISES = 1;\nconst LxStream = new Lx(MAX_CONCURRENT_PROMISES);\n// as unique argument the contructor receive the maximum number of promises to executate at the same time.\nconst operation = {\n  id: 1,\n  onResult: ({result, fromCache}) =\u003e console.log({ result, fromCache }), // { result: 1, fromCache: false }\n  definition: () =\u003e Promise.resolve(1)\n};// define operation to perform\n\nLxStream.push(operation);\n```\nThe operation object must have this shape:\n\n| key        | value            | required  | default    | description                                                | \n|:----------:|:-----------------|:----------|:-----------|:-----------------------------------------------------------|\n| id         | Number or String | true      | undefined  | Unique identifier                                          |\n| cache      | Function         | true      | undefined  | Flag that allows you to save the promise result in cache   |\n| definition | Function         | true      | undefined  | A function that must return the  promise to execute        |\n| onResult   | Function         | true      | undefined  | A function that is called when the promise finish          |\n\nThe `onResult` is a callback that give you the result of the operation, with a object with this shape: \n\n| key        | value    | description                                                                                  |  \n|:----------:|:--------:|:---------------------------------------------------------------------------------------------|\n| fromCache  | Boolean  | Boolean value that tell you if the result of the operation come from cache or not            |\n| result     | Any      | Result of the promise execution could be any type depending on what value the promise return | \n| error      | Boolean  | Boolean value that tell you if the result of the operation was rejected of fulfilled         |\n\n\n# Use cases\n`lux-io` can be very handy in the cases like:\n- Reduce the server load by limiting the amount in requests sended by the client at the same time.\n- Use the cache for speed the time response of a program like an ajax call, or database request.\n\n# Examples\n## Push multiples operations\nIn this example you will notice that only 2 promises are executed at a time regardless of the time it takes to finish, this behavior occurs because the maximum number of promises to execute at the same time is 2, in this case lux-io will give you execution priority to the first 2 promises pushed, when one of those ends it will continue with the next one in the pending list.\n\n```javascript\nimport { Lx } from '@maxtermax/lux-io';// import lux-io as lx\nconst LxStream = new Lx(2);\n\nfunction promiseTimeout(cb, TIME) {\n  return new Promise((resolve, reject) =\u003e {\n    setTimeout(() =\u003e cb().then(resolve).catch(reject), TIME);\n  });\n};\n\nconst operationOne = {\n  id: 1,\n  cache: true,\n  onResult: ({result}) =\u003e console.log({result}),//resolve third\n  definition: () =\u003e promiseTimeout(() =\u003e Promise.resolve(1), 1000),\n};\n\nconst operationTwo = {\n  id: 2,\n  cache: true,\n  onResult: ({result}) =\u003e console.log({result}),//resolve first\n  definition: () =\u003e promiseTimeout(() =\u003e Promise.resolve(2), 500),\n};\n\nconst operationThree = {\n  id: 3,\n  cache: true,\n  onResult: ({result}) =\u003e console.log({result}),//resolve second\n  definition: () =\u003e promiseTimeout(() =\u003e Promise.resolve(3), 100),\n};\nLxStream.push(operationOne);\nLxStream.push(operationTwo);\nLxStream.push(operationThree);\n```\n\n## Using cache\n`lux-io` will try to cache the result of the promises executed in previous executions and if other operation with an id equals to a previus operation execuated is pushed into the stream `lux-io` will return the result from cache aslong the cache property is set to true.\n\nNote that this feature really depends of the time execution, this also depends of the maximum concurrent promises allowed settled in the creation of the instance, so for this reaseon the cache maybe not work if the first promise execution don't match in the time that other promise with the same id is pushed into the stream,  this escenation the cache could be empty.\n\nYou can also can deactivate the `cache` by set the property to `false` in that case all the cache thing will be ignored\n\n```javascript\nimport { Lx } from '@maxtermax/lux-io';\nconst LxStream = new Lx(1);\n\nconst operationOne = {\n  id: 1,\n  cache: true,\n  onResult: ({ fromCache }) =\u003e console.log({fromCache}),// { fromCache: false }\n  definition: () =\u003e Promise.resolve(1),\n}\n\nLxStream.push(operationOne);\n\nconst operationTwo = {\n  id: 1,\n  cache: true,\n  onResult: ({ fromCache }) =\u003e console.log({fromCache}),// { fromCache: true }\n  definition: () =\u003e Promise.resolve(1),\n};\nLxStream.push(operationTwo);\n```\n\n## Make a http call\nA great use case for `lux-io` is make http call's, with this aproach you can control the amount of call to you server, \nin this example are allowed only 2 call at the same time.\n\nNote that the todo with `id` 1 is repeated in the array of todos because of that in the second call of the todo with `id` id the response is immediate, because it come from the `cache`.\n\n```javascript\nimport { Lx } from '@maxtermax/lux-io';\nconst LxStream = new Lx(2); //Only 2 promises are allowed to be executed at the same time.\n\nasync function getTodo(id) {\n  return fetch(\n    `https://jsonplaceholder.typicode.com/todos/${id}`\n  ).then((response) =\u003e response.json());\n}\n\nconst todos = [1, 2, 3, 1, 4, 5];\nfunction fetchAllTodos(todos = []) {\n  todos.forEach((todo) =\u003e\n    LxStream.push({\n      id: todo,\n      cache: true,\n      onResult: ({ fromCache, result }) =\u003e console.log({ todo, fromCache, result }),\n      definition: () =\u003e getTodo(todo),\n    })\n  );\n}\n\nfetchAllTodos(todos);\n\n/*\n{ todo: 1, fromCache: false, result:{...} }\n{ todo: 2, fromCache: false, result:{...} }\n{ todo: 3, fromCache: false, result:{...} }\n{ todo: 1, fromCache: true, result:{...} }// this call came from cache\n{ todo: 4, fromCache: false, result:{...} }\n{ todo: 5, fromCache: false, result:{...} }\n*/\n```\nNote the request `1` only appears once, and the next request come from the internal cache of `lux-io` so this way avoid to repeat the same http call, for this example also notice that the requests come in pairs\n \n![Application network](https://i.imgur.com/bgU8neh.png \"Application network\")\n\n# Api\n\n## Push\nThis method allow you to push operations into the stream, this method must receive a operation object.\n\n```javascript\nconst LxStream = new Lx(1);\nconst operation = {\n  id: 1,\n  cache: true,\n  onResult: ({result}) =\u003e console.log({result}),\n  definition: () =\u003e Promise.resolve(1)\n};\nLxStream.push(operation);\n```\n## Pull\nThis method allow you to pull operations out the stream, in order the pull an operation this method must receive the\noperation id, note this method will only have effect on pending operations.\n\nThe pending operations will be in queue for later execution in this example the pending operation will be `operationTwo` because for this particular example the `MAX_CONCURRENT_PROMISES` is `1`.\n\n```javascript\nconst LxStream = new Lx(1);\nconst operationOne = {\n  id: 1,\n  cache: true,\n  onResult: () =\u003e console.log(\"just this callback will be called\"),\n  definition: () =\u003e promiseTimeout(() =\u003e Promise.resolve(\"TEST\"), 0),\n};\nconst operationTwo = {\n  id: 2,\n  cache: true,\n  onResult: () =\u003e console.log(\"this callback never will be called\"),\n  definition: () =\u003e promiseTimeout(() =\u003e Promise.resolve(\"TEST\"), 1000),\n};\nLxStream.push(operationOne);\nLxStream.push(operationTwo);\nLxStream.pull(2);\n```\n## removeFromCache \nThis method allow you to delete operations previously saved in cache, this method must receive the\noperation id.\n\nNote this method only will take effect if the operation was previously saved in cache\n```javascript\n const LxStream = new Lx(1);\n const id = 1;\n const operation = {\n   id,\n   cache: true,\n   onResult: ({ fromCache }) =\u003e console.log({ fromCache }),\n   definition: () =\u003e promiseTimeout(() =\u003e Promise.resolve(\"TEST\"), 0),\n };\n LxStream.push(operation);\n LxStream.push(operation);// this result will come from cache\n setTimeout(() =\u003e {\n   LxStream.removeFromCache(id);\n   LxStream.push(operation);// this result will not come from cache\n }, 1000)\n```\n\n## clearCache \nThis method allow you to all delete operations previously saved in cache.\n\nNote this method only will take effect if the operations was previously saved in cache.\n```javascript\n const LxStream = new Lx(1);\n const id = 1;\n const operation = {\n   id,\n   cache: true,\n   onResult: ({ fromCache }) =\u003e console.log({ fromCache }),\n   definition: () =\u003e promiseTimeout(() =\u003e Promise.resolve(\"TEST\"), 0),\n };\n LxStream.push(operation);\n LxStream.push(operation);// this result will come from cache\n setTimeout(() =\u003e {\n   LxStream.clearCache();// delete cache\n   LxStream.push(operation);// this result will not come from cache\n }, 1000)\n```\n\n# Inner workings\n\nWhen you try to push more promises than are allowed into the queue those  promises wait in a pending list of promises without execute, until at least one of the promises in the main queue get resolved or rejected,  when that happend one of the pending promises get push into the main queue.\n\nThe same process get execuate over and over againt until all the promises get exectuted.\n\nSo this is all for now, be in touch if you have some issue or want to contribute to this project\n\nFun fact lux means traffic light in latin.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxtermax%2Flux-io","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxtermax%2Flux-io","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxtermax%2Flux-io/lists"}