{"id":21925270,"url":"https://github.com/fabienarcellier/qbind","last_synced_at":"2026-01-24T22:04:09.946Z","repository":{"id":58594771,"uuid":"532574663","full_name":"FabienArcellier/qbind","owner":"FabienArcellier","description":"powerful asynchronous query binding for vanillajs","archived":false,"fork":false,"pushed_at":"2023-01-14T13:49:00.000Z","size":190,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-26T08:17:38.250Z","etag":null,"topics":["ajax","javascript","querying","state-management"],"latest_commit_sha":null,"homepage":"","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/FabienArcellier.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-09-04T15:09:39.000Z","updated_at":"2023-04-21T19:53:44.000Z","dependencies_parsed_at":"2023-02-09T19:30:26.967Z","dependency_job_id":null,"html_url":"https://github.com/FabienArcellier/qbind","commit_stats":null,"previous_names":["fabienarcellier/cached-query"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/FabienArcellier/qbind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FabienArcellier%2Fqbind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FabienArcellier%2Fqbind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FabienArcellier%2Fqbind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FabienArcellier%2Fqbind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FabienArcellier","download_url":"https://codeload.github.com/FabienArcellier/qbind/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FabienArcellier%2Fqbind/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28737860,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T21:19:41.845Z","status":"ssl_error","status_checked_at":"2026-01-24T21:13:38.675Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["ajax","javascript","querying","state-management"],"created_at":"2024-11-28T21:17:50.186Z","updated_at":"2026-01-24T22:04:09.931Z","avatar_url":"https://github.com/FabienArcellier.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# qbind\n\n[![ci](https://github.com/FabienArcellier/qbind/actions/workflows/main.yml/badge.svg)](https://github.com/FabienArcellier/qbind/actions/workflows/main.yml) [![npm version](https://badge.fury.io/js/qbind.svg)](https://badge.fury.io/js/qbind)\n\npowerful asynchronous query binding for vanillajs.\n\n**This library is experimental**. Its API is likely to evolve between 2 versions. It covers one of my specific requirements.\nI am not sure to maintain this library yet.\n\nThis library is inspired from :\n\n* [React-query](https://tanstack.com/query/v4)\n* [Apollo Graphql](https://www.apollographql.com/)\n\n## Demo\n\n* [Vanilla.js](https://fabienarcellier.github.io/qbind/demo/vanilla/) / [[code](./demo/vanilla)]\n\n## Motivation\n\nI wanted to use a frontend library [Alpine.js](https://alpinejs.dev/), lighter than React or Vue.js, to make interactive interface.\nI need a asynchronous state management module as [react-query](https://github.com/TanStack/query) to :\n\n* declare query as independant code\n* deduplicate REST requests if several widgets load the same data source\n* update all widgets when the request is invalidated and run again\n* regularly pull a data source and update all the widgets that use it\n* mock REST requests easily to perform unit test\n* process only the last request during cascading invalidations\n\nAs I couldn't find a library that match this requirement for vanillajs, I decide to implement `qbind`\n\n## Installation\n\n### install in the browser\n\n```html\n\u003cscript src=\"https://unpkg.com/qbind/dist/qbind.min.js\"\u003e\u003c/script\u003e\n```\n\n### install with npm\n```\nnpm install --save qbind\n```\n\n## Code Example\n\nthe following examples can be played in the browser console when installing `qbind` in the browser.\n\n```javascript\npreparedQuery(\"users\", \"https://randomuser.me/api/?seed=foobar\u0026results=5\")\n\nfunction users() {\n    useQuery(\"users\", (data, loading, error, response) =\u003e {\n        if (loading == false) {\n            console.log(data.results)\n        }\n    })\n}\n\nfunction userByGender() {\n    useQuery(\"users\", (data, loading, error, response) =\u003e {\n        if (loading == false) {\n            results = {}\n            for (key in data.results) {\n                user = data.results[key]\n                gender = user.gender\n                if (!(gender in results)) {\n                    results[gender] = [] \n                }\n                results[gender].push(user)\n                \n            }\n            \n            // display the list in the dom element\n            console.log(results)\n        }\n    })\n}\n\nusers();\nuserByGender();\n\n// run the query once, and execute the callback of users and userByFender.\ninvalidateQuery(\"users\");\n```\n\n### Delayed query : Run the callback only after an invalidation has been performed\n\nIn some case, you have a query that is not ready. It requires an external argument that is not set yet.\n\n```javascript\nfunction users() {\n    subscribeQuery(\"users\", (data, loading, error, response) =\u003e {\n        if (loading == false) {\n            console.log(data.results)\n        }\n    });\n\n    users(); // nothing happens\n    invalidateQuery(\"users\");\n}\n```\n\n### Recurring query : Run an api request every 5 seconds and refresh dependent widgets\n\n```javascript\npreparedQuery(\"users\", \"https://randomuser.me/api/?seed=foobar\", {}, {interval: 5})\n\nfunction users() {\n    useQuery(\"users\", (data, loading, error, response) =\u003e {\n        if (loading == false) {\n            console.log(data.results)\n        }\n    })\n}\n\nfunction userByGender() {\n    useQuery(\"users\", (data, loading, error) =\u003e {\n        if (loading == false) {\n            results = {}\n            for (key in data.results) {\n                user = data.results[key]\n                gender = user.gender\n                if (!(gender in results)) {\n                    results[gender] = [] \n                }\n                results[gender].push(user)\n                \n            }\n            \n            // display the list in the dom element\n            console.log(results)\n        }\n    })\n}\n\nusers();\nuserByGender();\n```\n\n### Mock query : Test your javascript code without calling your API\n\n`qbind` allows you to mock an external call in your automatic tests with the `mockQuery` method and \nbypass the request to the server by returning a pre-programmed response.\n\n```javascript\npreparedQuery(\"users\", \"https://randomuser.me/api/?seed=foobar\u0026results=5\")\nmockQuery(\"users\", {results: []})\n\nfunction users() {\n    useQuery(\"users\", (data, loading, error, response) =\u003e {\n        if (loading == false) {\n            console.log(data.results)\n        }\n    })\n}\n\n/* use the mock instead of calling the api */\nusers();\n```\n\n### Forward parameter to fetch\n\nThe second argument of `preparedQuery` and `replaceQuery` contains the options for the fetch request.\n\n```javascript\npreparedQuery(\"users\", \"https://randomuser.me/api/?seed=foobar\u0026results=5\", {mode: 'cors'})\n\nfunction users() {\n    useQuery(\"users\", (data, loading, error, response) =\u003e {\n        if (loading == false) {\n            console.log(data.results)\n        }\n    })\n}\n\nusers();\n```\n\n### Trigger the callbacks for every invalidation\n\nBy default, `qbind` only returns the result of the last invalidation when several successive invalidations have been executed. \nThis behavior limits clipping by recovering incomplete data.\n\nIf you need to call the callbacks for all invalidations, use the `postponeInvalidation: false` option.\n\n```javascript\npreparedQuery(\"users\", \"https://randomuser.me/api/?seed=foobar\u0026results=5\", {}, {postponeInvalidation: false})\n\nfunction users() {\n    useQuery(\"users\", (data, loading, error, response) =\u003e {\n        if (loading == false) {\n            console.log(data.results)\n        }\n    })\n}\n\nusers();\n\n// run the query once, and execute the callback of users and userByFender.\ninvalidateQuery(\"users\");\n```\n\n### Change the behavior of an existing query\n\nThe `replaceQuery` method reconfigures an existing query. \nIt is possible to make an existing query recurrent, for example to run it every 60 seconds.\n\n```javascript\npreparedQuery('users', \"https://randomuser.me/api/?seed=foobar\u0026results=5\", {}, {});\nreplaceQuery('users', \"https://randomuser.me/api/?seed=foobar\u0026results=5\", {}, {interval: 60});\n\nfunction users() {\n    useQuery(\"users\", (data, loading, error, response) =\u003e {\n        if (loading == false) {\n            console.log(data.results)\n        }\n    })\n}\n\nusers();\n```\n\n### Query propagation : Remove a callback\n\n```javascript\npreparedQuery('users', \"https://randomuser.me/api/?seed=foobar\u0026results=5\", {}, {});\n\nuseQuery(\"users\", (data, loading, error, response, stopCallback) =\u003e {\n    if (loading == false) {\n        console.log(data.results)\n    }\n    \n    if (data !== null) {\n        map = //...\n    }\n    \n    if (map !== null) {\n        stopCallback.set()\n    }\n})\n\n\n/**\n * once the invocation of the stopCallback takes place, \n * the callback is no longer executed\n */\ninvalidateQuery(\"users\");\ninvalidateQuery(\"users\");\n\n```\n\n### Replace the default query engine, Fetch + json with Axios or Fetch + xml\n\nTo define a new engine, you must write a javascript function that takes a query object as a parameter.\nAn engine should always invoke the ``invokeSubscriptions`` function from the response it retrieves. \nThis will trigger the execution of the subscriptions of this query.\n\nThe `replaceQueryDefaultEngine` function replaces the query engine for all queries.\n\n```javascript\nexport function customAxiosEngine(query) {\n    axios.get(query.url)\n      .then(function (response) {\n          invokeSubscriptions(query, response.data, null, response);\n      })\n      .catch(function (error) {\n          invokeSubscriptions(query, null, error, null);\n      })\n}\n\nreplaceQueryDefaultEngine(customAxiosEngine)\n```\n\n``preparedQuery`` and ``replaceQuery`` accept also an ``engine`` option to specify \na specific query engine for a specific query.\n\n```javascript\npreparedQuery('users', \"https://randomuser.me/api/?seed=foobar\u0026results=5\", {}, {engine: customAxiosEngine});\n```\n\n``qbind`` implements 2 engines that you can use for inspiration ``fetchJsonEngine`` and ``mockEngine``.\n\n## The latest version\n\nYou can find the latest version to ...\n\n```bash\ngit clone https://github.com/FabienArcellier/qbind.git\n```\n\n### Tests\n\n```javascript\nnpm test\n```\n\n### Contributing\n\nIf you propose hotfixes or new features, I will integrate them as a best effort.\nAs the library is experimental I would prefer discuss them on discord. [You can join me on it](https://discord.gg/nMn9YPRGSY).\n\n## Contributors\n\n* Fabien Arcellier\n\n## License\n\nMIT License\n\nCopyright (c) 2022 Arcellier Fabien\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n## References\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabienarcellier%2Fqbind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabienarcellier%2Fqbind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabienarcellier%2Fqbind/lists"}