{"id":13779527,"url":"https://github.com/koajs/koa-redis","last_synced_at":"2025-05-14T20:04:40.276Z","repository":{"id":12804113,"uuid":"15478900","full_name":"koajs/koa-redis","owner":"koajs","description":"Redis storage for Koa session middleware/cache with Sentinel and Cluster support","archived":false,"fork":false,"pushed_at":"2024-06-02T14:09:09.000Z","size":1386,"stargazers_count":352,"open_issues_count":14,"forks_count":40,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-10-29T15:32:21.512Z","etag":null,"topics":["cache","cluster","koa","node","redis","sentinel","session","storage"],"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/koajs.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","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}},"created_at":"2013-12-27T17:50:49.000Z","updated_at":"2024-07-18T22:48:14.000Z","dependencies_parsed_at":"2024-11-06T09:23:47.772Z","dependency_job_id":"6314b9b3-4a66-43fa-95f6-2ce7d42c2fff","html_url":"https://github.com/koajs/koa-redis","commit_stats":{"total_commits":112,"total_committers":17,"mean_commits":6.588235294117647,"dds":0.6607142857142857,"last_synced_commit":"f3f10a500ec1e99fb77ef9a613d08e4aa9e564a3"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fkoa-redis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fkoa-redis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fkoa-redis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fkoa-redis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/koajs","download_url":"https://codeload.github.com/koajs/koa-redis/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247166156,"owners_count":20894652,"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":["cache","cluster","koa","node","redis","sentinel","session","storage"],"created_at":"2024-08-03T18:01:06.160Z","updated_at":"2025-04-08T14:10:11.189Z","avatar_url":"https://github.com/koajs.png","language":"JavaScript","funding_links":[],"categories":["Middleware","仓库","JavaScript"],"sub_categories":["中间件"],"readme":"# koa-redis\n\n[![build status][travis-image]][travis-url]\n[![Coveralls][coveralls-image]][coveralls-url]\n[![David deps][david-image]][david-url]\n[![David devDeps][david-dev-image]][david-dev-url]\n[![license][license-image]][license-url]\n[![code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg?style=flat-square)](https://github.com/sindresorhus/xo)\n[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)\n[![made with lass](https://img.shields.io/badge/made_with-lass-95CC28.svg?style=flat-square)](https://lass.js.org)\n\n\u003e Redis storage for Koa session middleware/cache with Sentinel and Cluster support\n\n[![NPM](https://nodei.co/npm/koa-redis.svg?downloads=true)](https://nodei.co/npm/koa-redis/)\n\n**v4.0.0+ now uses `ioredis` and has support for Sentinel and Cluster!**\n\n\n## Table of Contents\n\n* [Install](#install)\n* [Usage](#usage)\n  * [Basic](#basic)\n  * [Sentinel](#sentinel)\n  * [Cluster](#cluster)\n* [Options](#options)\n* [Events](#events)\n* [API](#api)\n  * [module(options)](#moduleoptions)\n  * [session.get(sid)](#sessiongetsid)\n  * [session.set(sid, sess, ttl)](#sessionsetsid-sess-ttl)\n  * [session.destroy(sid)](#sessiondestroysid)\n  * [session.quit()](#sessionquit)\n  * [session.end()](#sessionend)\n  * [session.status](#sessionstatus)\n  * [session.connected](#sessionconnected)\n  * [session.client](#sessionclient)\n* [Benchmark](#benchmark)\n* [Testing](#testing)\n* [License](#license)\n* [Contributors](#contributors)\n\n\n## Install\n\n[npm][]:\n\n```sh\nnpm install koa-redis\n```\n\n[yarn][]:\n\n```sh\nyarn add koa-redis\n```\n\n\n## Usage\n\n`koa-redis` works with [koa-generic-session](https://github.com/koajs/generic-session) (a generic session middleware for koa).\n\nFor more examples, please see the [examples folder of `koa-generic-session`](https://github.com/koajs/generic-session/tree/master/example).\n\n### Basic\n\n```js\nconst session = require('koa-generic-session');\nconst redisStore = require('koa-redis');\nconst koa = require('koa');\n\nconst app = koa();\napp.keys = ['keys', 'keykeys'];\napp.use(session({\n  store: redisStore({\n    // Options specified here\n  })\n}));\n\napp.use(function *() {\n  switch (this.path) {\n  case '/get':\n    get.call(this);\n    break;\n  case '/remove':\n    remove.call(this);\n    break;\n  case '/regenerate':\n    yield regenerate.call(this);\n    break;\n  }\n});\n\nfunction get() {\n  const session = this.session;\n  session.count = session.count || 0;\n  session.count++;\n  this.body = session.count;\n}\n\nfunction remove() {\n  this.session = null;\n  this.body = 0;\n}\n\nfunction *regenerate() {\n  get.call(this);\n  yield this.regenerateSession();\n  get.call(this);\n}\n\napp.listen(8080);\n```\n\n### Sentinel\n\n```js\nconst session = require('koa-generic-session');\nconst redisStore = require('koa-redis');\nconst koa = require('koa');\n\nconst app = koa();\napp.keys = ['keys', 'keykeys'];\napp.use(session({\n  store: redisStore({\n    // Options specified here\n    // \u003chttps://github.com/luin/ioredis#sentinel\u003e\n    sentinels: [\n      { host: 'localhost', port: 26379 },\n      { host: 'localhost', port: 26380 }\n      // ...\n    ],\n    name: 'mymaster'\n  })\n}));\n\n// ...\n```\n\n### Cluster\n\n```js\nconst session = require('koa-generic-session');\nconst redisStore = require('koa-redis');\nconst koa = require('koa');\n\nconst app = koa();\napp.keys = ['keys', 'keykeys'];\napp.use(session({\n  store: redisStore({\n    // Options specified here\n    // \u003chttps://github.com/luin/ioredis#cluster\u003e\n    isRedisCluster: true,\n    nodes: [\n      {\n        port: 6380,\n        host: '127.0.0.1'\n      },\n      {\n        port: 6381,\n        host: '127.0.0.1'\n      }\n      // ...\n    ],\n    // \u003chttps://github.com/luin/ioredis/blob/master/API.md#new-clusterstartupnodes-options\u003e\n    clusterOptions: {\n      // ...\n      redisOptions: {\n        // ...\n      }\n    }\n  })\n}));\n\n// ...\n```\n\n\n## Options\n\n* _all [`ioredis`](https://github.com/luin/ioredis/blob/master/API.md#new-redisport-host-options) options_ - Useful things include `url`, `host`, `port`, and `path` to the server. Defaults to `127.0.0.1:6379`\n* `db` (number) - will run `client.select(db)` after connection\n* `client` (object) - supply your own client, all other options are ignored unless `duplicate` is also supplied\n* `duplicate` (boolean) - When true, it will run `client.duplicate()` on the supplied `client` and use all other options supplied. This is useful if you want to select a different DB for sessions but also want to base from the same client object.\n* `serialize` - Used to serialize the data that is saved into the store.\n* `unserialize` - Used to unserialize the data that is fetched from the store.\n* `isRedisCluster` (boolean) - Used for creating a Redis cluster instance per [`ioredis`][cluster] Cluster options, if set to `true`, then a new Redis cluster will be instantiated with `new Redis.Cluster(options.nodes, options.clusterOptions)` (see [Cluster docs][cluster] for more info).\n* `nodes` (array) - Conditionally used for creating a Redis cluster instance when `isRedisCluster` option is `true`, this is the first argument passed to `new Redis.Cluster` and contains a list of all the nodes of the cluster ou want to connect to (see [Cluster docs][cluster] for more info).\n* `clusterOptions` (object) - Conditionally used for created a Redi cluster instance when `isRedisCluster` option is `true`, this is the second argument passed to `new Redis.Cluster` and contains options, such as `redisOptions` (see [Cluster docs][cluster] for more info).\n* **DEPRECATED:** old options - `auth_pass` and `pass` have been replaced with `password`, and `socket` has been replaced with `path`, however all of these options are backwards compatible.\n\n\n## Events\n\nSee the [`ioredis` docs](https://github.com/luin/ioredis#connection-events) for more info.\n\n**Note that as of v4.0.0 the `disconnect` and `warning` events are removed as `ioredis` does not support them.   The `disconnect` event is deprecated, although it is still emitted when `end` events are emitted.**\n\n\n## API\n\nThese are some the functions that `koa-generic-session` uses that you can use manually. You will need to initialize differently than the example above:\n\n```js\nconst session = require('koa-generic-session');\nconst redisStore = require('koa-redis')({\n  // Options specified here\n});\nconst app = require('koa')();\n\napp.keys = ['keys', 'keykeys'];\napp.use(session({\n  store: redisStore\n}));\n```\n\n### module([options](#options))\n\nInitialize the Redis connection with the optionally provided options (see above). _The variable `session` below references this_.\n\n### session.get(sid)\n\nGenerator that gets a session by ID. Returns parsed JSON is exists, `null` if it does not exist, and nothing upon error.\n\n### session.set(sid, sess, ttl)\n\nGenerator that sets a JSON session by ID with an optional time-to-live (ttl) in milliseconds. Yields `ioredis`'s `client.set()` or `client.setex()`.\n\n### session.destroy(sid)\n\nGenerator that destroys a session (removes it from Redis) by ID. Tields `ioredis`'s `client.del()`.\n\n### session.quit()\n\nGenerator that stops a Redis session after everything in the queue has completed. Yields `ioredis`'s `client.quit()`.\n\n### session.end()\n\nAlias to `session.quit()`. It is not safe to use the real end function, as it cuts off the queue.\n\n### session.status\n\nString giving the connection status updated using `client.status`.\n\n### session.connected\n\nBoolean giving the connection status updated using `client.status` after any of the events above is fired.\n\n### session.client\n\nDirect access to the `ioredis` client object.\n\n\n## Benchmark\n\n| Server                  | Transaction rate      | Response time |\n| ----------------------- | --------------------- | ------------- |\n| connect without session | **6763.56 trans/sec** | **0.01 secs** |\n| koa without session     | **5684.75 trans/sec** | **0.01 secs** |\n| connect with session    | **2759.70 trans/sec** | **0.02 secs** |\n| koa with session        | **2355.38 trans/sec** | **0.02 secs** |\n\nDetailed benchmark report [here](https://github.com/koajs/koa-redis/tree/master/benchmark)\n\n\n## Testing\n\n1. Start a Redis server on `localhost:6379`. You can use [`redis-windows`](https://github.com/ServiceStack/redis-windows) if you are on Windows or just want a quick VM-based server.\n2. Clone the repository and run `npm i` in it (Windows should work fine).\n3. If you want to see debug output, turn on the prompt's `DEBUG` flag.\n4. Run `npm test` to run the tests and generate coverage. To run the tests without generating coverage, run `npm run-script test-only`.\n\n\n## License\n\n[MIT](LICENSE) © dead_horse\n\n\n## Contributors\n\n| Name           | Website                    |\n| -------------- | -------------------------- |\n| **dead_horse** |                            |\n| **Nick Baugh** | \u003chttp://niftylettuce.com/\u003e |\n\n\n## \n\n[travis-image]: https://img.shields.io/travis/koajs/koa-redis.svg?style=flat-square\n\n[travis-url]: https://travis-ci.org/koajs/koa-redis\n\n[coveralls-image]: https://img.shields.io/coveralls/koajs/koa-redis.svg?style=flat-square\n\n[coveralls-url]: https://coveralls.io/r/koajs/koa-redis?branch=master\n\n[david-image]: https://img.shields.io/david/koajs/koa-redis.svg?style=flat-square\u0026label=deps\n\n[david-url]: https://david-dm.org/koajs/koa-redis\n\n[david-dev-image]: https://img.shields.io/david/dev/koajs/koa-redis.svg?style=flat-square\u0026label=devDeps\n\n[david-dev-url]: https://david-dm.org/koajs/koa-redis#info=devDependencies\n\n[license-image]: https://img.shields.io/npm/l/koa-redis.svg?style=flat-square\n\n[license-url]: https://github.com/koajs/koa-redis/blob/master/LICENSE\n\n[cluster]: https://github.com/luin/ioredis/blob/master/API.md#new-clusterstartupnodes-options\n\n[npm]: https://www.npmjs.com/\n\n[yarn]: https://yarnpkg.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoajs%2Fkoa-redis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkoajs%2Fkoa-redis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoajs%2Fkoa-redis/lists"}