{"id":27085504,"url":"https://github.com/yahya-aghdam/guardflux","last_synced_at":"2026-02-15T20:01:15.608Z","repository":{"id":258264762,"uuid":"874406148","full_name":"yahya-aghdam/guardflux","owner":"yahya-aghdam","description":"A light callable lib to keep your API alive","archived":false,"fork":false,"pushed_at":"2025-10-24T08:14:50.000Z","size":95,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-24T10:08:36.986Z","etag":null,"topics":["api","body","ddos","joi-validation","mikroorm","query","ratelimit","redis","security-tools"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/yahya-aghdam.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-17T19:11:46.000Z","updated_at":"2025-10-24T08:44:55.000Z","dependencies_parsed_at":"2025-09-14T16:23:21.859Z","dependency_job_id":"b57404a4-c9ef-481e-a078-deb9869063c0","html_url":"https://github.com/yahya-aghdam/guardflux","commit_stats":null,"previous_names":["yahya-aghdam/guardflux"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/yahya-aghdam/guardflux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahya-aghdam%2Fguardflux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahya-aghdam%2Fguardflux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahya-aghdam%2Fguardflux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahya-aghdam%2Fguardflux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yahya-aghdam","download_url":"https://codeload.github.com/yahya-aghdam/guardflux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahya-aghdam%2Fguardflux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29487774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T19:29:10.908Z","status":"ssl_error","status_checked_at":"2026-02-15T19:29:10.419Z","response_time":118,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":["api","body","ddos","joi-validation","mikroorm","query","ratelimit","redis","security-tools"],"created_at":"2025-04-06T04:37:42.844Z","updated_at":"2026-02-15T20:01:15.589Z","avatar_url":"https://github.com/yahya-aghdam.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Guardflux\n\n![License](https://img.shields.io/badge/License-MIT-blue)\n![Version](https://img.shields.io/badge/Version-3.0.0-orange)\n\nA light callable lib to keep your Node.Js API alive\n\n- [Guardflux](#guardflux)\n  - [Installation](#installation)\n  - [Functions and usage](#functions-and-usage)\n    - [schema](#schema)\n    - [checkObject()](#checkobject)\n    - [rateLimit()](#ratelimit)\n  - [License](#license)\n\n## Installation\n\n```bash\nnpm i guardflux\n```\n\n## Functions and usage\n\n### schema\n\nThis is expansion of [Joi](https://github.com/hapijs/joi) lib that we use it to verify API input. It can be `query` or `body` of a request. Here is the example of usage:\n\n```ts\nconst ipSchema = schema.object({\n    api_key: schema.string().min(10).max(10).required(),\n})\n```\n\n### checkObject()\n\nThen you can verify the input with `checkObject()` function and it returns result with two elements `isValid: boolean` and `log: any`. `isValid` returns `true` if given object and schema match and `log` returns `Joi` log if an error happen. Also this function has an element called `devMode` that prints all logs in `console` to get what is happening in function and default set to `true`. Here is the full example:\n\n```ts\nimport { checkObject, schema } from 'guardflux'\nimport { CheckResult } from 'guardflux/dist/lib/types'\n\n...\n// This is the api-key or user ip or id that you can pass to function\nconst user_given_api_key: string = \"x2a45B78C0\"\n\nconst ipSchema = schema.object({\n    api_key: schema.string().min(10).max(10).required(),\n})\n\nconst check: CheckResult = await checkObject({ api_key: user_given_api_key }, ipSchema)\n```\n\nYou can use `check.isValid` to response the user that given data in request is valid or not.\n\n### rateLimit()\n\nThis is a very useful function that make rate limit for every route based on user api-key/id/ip that you pass. We use [MikroOrm](https://github.com/mikro-orm/mikro-orm) because it is light and can handle several DBs. Because of needing to save data in DB we have to config the DB options first:\n\n```ts\nconst dbConfig: DbConfig = {\n    dbName: \"guardflux\", // Default name id \"guardflux\" but you can pass any name you want\n    dbType: \"mongodb\", // Choose which DB you want to work with it. Supported DBs are 1-MySQL 2-MongoDB 3-PostgreSQL\n    dbURI: MONGO_URI, // Pass URI of your DB\n    dbDebug: true // Make MikroOrm debug mode on\n}\n```\n\nIf your DB has username and password, you can add it to you URI string. These are default DBs URI string that don't have username and password.\n\n| Type       |        default connection url        |\n| :--------- | :----------------------------------: |\n| mongo      |      mongodb://127.0.0.1:27017       |\n| mysql      |     mysql://root@127.0.0.1:3306      |\n| postgresql | postgresql://postgres@127.0.0.1:5432 |\n| redis      | redis://127.0.0.1:6379               |\n\nRedis support\n\nYou can now use Redis as the backing store for rate limiting. Redis uses a simple fixed-window counter with TTL. To enable Redis, set dbType to \"redis\" and pass your redis URI in dbURI. Optionally set redisPrefix in DbConfig to namespace keys.\n\nExample dbConfig for Redis:\n\n```ts README.md\nconst dbConfig: DbConfig = {\n    dbType: 'redis',\n    dbURI: 'redis://:password@127.0.0.1:6379', // or 'redis://127.0.0.1:6379' if no password\n    dbDebug: false,\n    redisPrefix: 'guardflux' // optional key prefix\n}\n```\n\nBehavior notes:\n\n- Key format: {prefix}:{userId}:{route}\n- Uses INCR and EXPIRE to implement a fixed window counter (cycleTime seconds).\n- If Redis is unavailable the function currently logs the error and allows the request; change as needed.\n\nAfter we config the DB, we have to add `options` for `rateLimit` function:\n\n```ts\nconst rlOptions: RateLimitOptions = {\n    route: \"/api/test_route\", // API route to specify ratelimit based on route\n    cycleTime: 60, // Rate limit cycle based on seconds\n    maxRequests: 5 // Max requests that a user can make in cycleTime\n}\n```\n\nNow we pass all consts to function. This function works based on two keys: 1- User API-key/ip/id 2- Route path. At least you can turn `devMode` to see in console what is happen. Like `checkObject` function, this method has `devMode` too that is enabled by default.This option will prints all data of `MikroOrm` and what is happen in function. This function returns like `checkObject` and you can use it to response the user if you want. All example is here:\n\n```ts\nimport { checkObject, schema } from 'guardflux'\nimport { CheckResult } from 'guardflux/dist/lib/types'\n\n...\n// This is the api-key or user ip or id that you can pass to function\nconst user_given_api_key: string = \"x2a45B78C0\"\n\nconst rlOptions: RateLimitOptions = {\n    route: \"/api/test_route\", // API route to specify ratelimit based on route\n    cycleTime: 60, // Rate limit cycle based on seconds\n    maxRequests: 5 // Max requests that a user can make in cycleTime\n}\n\nconst dbConfig: DbConfig = {\n    dbName: \"guardflux\", // Default name id \"guardflux\" but you can pass any name you want\n    dbType: \"mongodb\", // Choose which DB you want to work with it. Supported DBs are 1-MySQL 2-MongoDB 3-PostgreSQL 4-Redis\n    dbURI: MONGO_URI, // Pass URI of your DB\n    dbDebug: true // Make MikroOrm debug mode on\n}\n\nconst rl: CheckResult = await rateLimit(user_given_api_key, rlOptions, dbConfig)\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyahya-aghdam%2Fguardflux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyahya-aghdam%2Fguardflux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyahya-aghdam%2Fguardflux/lists"}