{"id":13487438,"url":"https://github.com/eggjs/schedule","last_synced_at":"2026-03-09T19:47:25.443Z","repository":{"id":57143203,"uuid":"63405746","full_name":"eggjs/schedule","owner":"eggjs","description":"Schedule plugin for egg","archived":false,"fork":false,"pushed_at":"2024-12-19T15:34:44.000Z","size":180,"stargazers_count":88,"open_issues_count":2,"forks_count":19,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-12-19T16:32:54.742Z","etag":null,"topics":["cron","egg","egg-plugin","egg-schedule","schedule-task"],"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/eggjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.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":"2016-07-15T08:36:28.000Z","updated_at":"2024-12-19T15:30:33.000Z","dependencies_parsed_at":"2024-12-19T16:43:10.586Z","dependency_job_id":null,"html_url":"https://github.com/eggjs/schedule","commit_stats":{"total_commits":90,"total_committers":20,"mean_commits":4.5,"dds":0.6666666666666667,"last_synced_commit":"78db046e2bbcb305002d3e9412ec02f2c3ebb089"},"previous_names":["eggjs/schedule"],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eggjs%2Fschedule","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eggjs%2Fschedule/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eggjs%2Fschedule/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eggjs%2Fschedule/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eggjs","download_url":"https://codeload.github.com/eggjs/schedule/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245750479,"owners_count":20666183,"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":["cron","egg","egg-plugin","egg-schedule","schedule-task"],"created_at":"2024-07-31T18:00:59.343Z","updated_at":"2026-03-09T19:47:20.408Z","avatar_url":"https://github.com/eggjs.png","language":"TypeScript","readme":"# @eggjs/schedule\n\n[![NPM version][npm-image]][npm-url]\n[![Node.js CI](https://github.com/eggjs/schedule/actions/workflows/nodejs.yml/badge.svg)](https://github.com/eggjs/schedule/actions/workflows/nodejs.yml)\n[![Test coverage][codecov-image]][codecov-url]\n[![Known Vulnerabilities][snyk-image]][snyk-url]\n[![npm download][download-image]][download-url]\n[![Node.js Version](https://img.shields.io/node/v/@eggjs/schedule.svg?style=flat)](https://nodejs.org/en/download/)\n\n[npm-image]: https://img.shields.io/npm/v/@eggjs/schedule.svg?style=flat-square\n[npm-url]: https://npmjs.org/package/@eggjs/schedule\n[codecov-image]: https://codecov.io/github/eggjs/schedule/coverage.svg?branch=master\n[codecov-url]: https://codecov.io/github/eggjs/schedule?branch=master\n[snyk-image]: https://snyk.io/test/npm/@eggjs/schedule/badge.svg?style=flat-square\n[snyk-url]: https://snyk.io/test/npm/@eggjs/schedule\n[download-image]: https://img.shields.io/npm/dm/@eggjs/schedule.svg?style=flat-square\n[download-url]: https://npmjs.org/package/@eggjs/schedule\n\nA schedule plugin for egg, has been built-in plugin for egg enabled by default.\n\nIt's fully extendable for a developer and provides a simple built-in TimerStrategy.\n\n## Usage\n\nJust add your job file to `{baseDir}/app/schedule`.\n\n```ts\n// {baseDir}/app/schedule/cleandb.ts\nimport { Subscription } from 'egg';\n\nexport default class CleanDB extends Subscription {\n  /**\n   * @property {Object} schedule\n   *  - {String} type - schedule type, `worker` or `all` or your custom types.\n   *  - {String} [cron] - cron expression, see [below](#cron-style-scheduling)\n   *  - {Object} [cronOptions] - cron options, see [cron-parser#options](https://github.com/harrisiirak/cron-parser#options)\n   *  - {String | Number} [interval] - interval expression in millisecond or express explicitly like '1h'. see [below](#interval-style-scheduling)\n   *  - {Boolean} [immediate] - To run a scheduler at startup\n   *  - {Boolean} [disable] - whether to disable a scheduler, usually use in dynamic schedule\n   *  - {Array} [env] - only enable scheduler when match env list\n   */\n  static get schedule() {\n    return {\n      type: 'worker',\n      cron: '0 0 3 * * *',\n      // interval: '1h',\n      // immediate: true,\n    };\n  }\n\n  async subscribe() {\n    await this.ctx.service.db.cleandb();\n  }\n}\n```\n\nYou can also use function simply like:\n\n```ts\nimport { EggContext } from 'egg';\n\nexport const schedule = {\n  type: 'worker',\n  cron: '0 0 3 * * *',\n  // interval: '1h',\n  // immediate: true,\n}\n\nexport async function task(ctx: EggContext) {\n  await ctx.service.db.cleandb();\n}\n```\n\n## Overview\n\n`@eggjs/schedule` supports both cron-based scheduling and interval-based scheduling.\n\nSchedule decision is being made by `agent` process. `agent` triggers a task and sends a message to `worker` process. Then, one or all `worker` process(es) execute the task based on schedule type.\n\nTo setup a schedule task, simply create a job file in `{app_root}/app/schedule`. A file contains one job and exports `schedule` and `task` properties.\n\nThe rule of thumbs is one job per file.\n\n## Task\n\nTask is a class which will be instantiated with every schedule, and a `subscribe` method will be invoked.\n\nYou can get anonymous context with `this.ctx`.\n\n- ctx.method: `SCHEDULE`\n- ctx.path: `/__schedule?path=${schedulePath}\u0026${schedule}`.\n\nTo create a task, `subscribe` can be a generator function or async function. For example:\n\n```ts\n// A simple logger example\nimport { Subscription } from 'egg';\n\nexport default class LoggerExample extends Subscription {\n  async subscribe() {\n    this.ctx.logger.info('Info about your task');\n  }\n}\n```\n\n```ts\n// A real world example: wipe out your database.\n// Use it with caution. :)\nimport { Subscription } from 'egg';\n\nexport default class CleanDB extends Subscription {\n  async subscribe() {\n    await this.ctx.service.db.cleandb();\n  }\n}\n```\n\n## Scheduling\n\n`schedule` is an object that contains one required property, `type`, and optional properties, `{ cron, cronOptions, interval, immediate, disable, env }`.\n\n### Cron-style Scheduling\n\nUse [cron-parser](https://github.com/harrisiirak/cron-parser).\n\n\u003e Note: `cron-parser` support `second` as optional that is not supported by linux crontab.\n\u003e\n\u003e `@hourly / @daily / @weekly / @monthly / @yearly` is also supported.\n\n```bash\n*    *    *    *    *    *\n┬    ┬    ┬    ┬    ┬    ┬\n│    │    │    │    │    |\n│    │    │    │    │    └ day of week (0 - 7) (0 or 7 is Sun)\n│    │    │    │    └───── month (1 - 12)\n│    │    │    └────────── day of month (1 - 31)\n│    │    └─────────────── hour (0 - 23)\n│    └──────────────────── minute (0 - 59)\n└───────────────────────── second (0 - 59, optional)\n```\n\nExample:\n\n```ts\n// To execute task every 3 hours\nexport const schedule = {\n  type: 'worker',\n  cron: '0 0 */3 * * *',\n  cronOptions: {\n    // tz: 'Europe/Athens',\n  },\n};\n```\n\n### Interval-style Scheduling\n\nTo use `setInterval`, and support [ms](https://www.npmjs.com/package/ms) conversion style\n\nExample:\n\n```ts\n// To execute task every 3 hours\nexport const schedule = {\n  type: 'worker',\n  interval: '3h',\n};\n```\n\n**Notice: Egg built-in TimerStrategy will schedule each execution at a fix rate, regardless of its execution time. So you have to make sure that your actual execution time of your `task/subscribe` must be smaller than your delay time.**\n\n### Schedule Type\n\n**Build-in support is:**\n\n- `worker`: will be executed in one random worker when a schedule runs.\n- `all`: will be executed in all workers when a schedule runs.\n\n**Custom schedule:**\n\nTo create a custom schedule, simply extend `agent.ScheduleStrategy` and register it by `agent.schedule.use(type, clz)`.\nYou can schedule the task to be executed by one random worker or all workers with\nthe built-in method `this.sendOne(...args)` or `this.sendAll(...args)` which support params,\nit will pass to `subscribe(...args)` or `task(ctx, ...args)`.\n\n```ts\n// {baseDir}/agent.ts\nimport { Agent } from 'egg';\n\nexport default (agent: Agent) =\u003e {\n  class CustomStrategy extends agent.ScheduleStrategy {\n    start() {\n      // such as mq / redis subscribe\n      agent.notify.subscribe('remote_task', data =\u003e {\n        this.sendOne(data);\n      });\n    }\n  }\n\n  agent.schedule.use('custom', CustomStrategy);\n}\n```\n\nThen you could use it to defined your job:\n\n```ts\n// {baseDir}/app/schedule/other.ts\nimport { Subscription } from 'egg';\n\nexport default class ClusterTask extends Subscription {\n  static get schedule() {\n    return {\n      type: 'custom',\n    };\n  }\n\n  async subscribe(data) {\n    console.log('got custom data:', data);\n    await this.ctx.service.someTask.run();\n  }\n}\n```\n\n## Dynamic schedule\n\n```ts\n// {baseDir}/app/schedule/sync.ts\nimport { Application } from 'egg';\n\nexport default (app: Application) =\u003e {\n  class SyncTask extends app.Subscription {\n    static get schedule() {\n      return {\n        interval: 10000,\n        type: 'worker',\n        // only start task when hostname match\n        disable: require('os').hostname() !== app.config.sync.hostname,\n        // only start task at prod mode\n        env: [ 'prod' ],\n      };\n    }\n\n    async subscribe() {\n      await this.ctx.sync();\n    }\n  }\n\n  return SyncTask;\n}\n```\n\n## Configuration\n\n### Logging\n\nSee `${appInfo.root}/logs/{app_name}/egg-schedule.log` which provided by [config.customLogger.scheduleLogger](https://github.com/eggjs/schedule/blob/master/src/config/config.default.ts).\n\n```ts\n// config/config.default.ts\nimport { EggAppConfig } from 'egg';\n\nexport default {\n  customLogger: {\n    scheduleLogger: {\n      // consoleLevel: 'NONE',\n      // file: path.join(appInfo.root, 'logs', appInfo.name, 'egg-schedule.log'),\n    },\n  },\n} as Partial\u003cEggAppConfig\u003e;\n```\n\n### Customize directory\n\nIf you want to add additional schedule directories, you can use this config.\n\n```ts\n// config/config.default.ts\nimport { EggAppConfig } from 'egg';\n\nexport default {\n  schedule: {\n    directory: [\n      'path/to/otherSchedule',\n    ],\n  },\n} as Partial\u003cEggAppConfig\u003e;\n```\n\n## Testing\n\n`app.runSchedule(scheduleName)` is provided by `@eggjs/schedule` plugin only for test purpose.\n\nExample:\n\n```ts\nit('test a schedule task', async () =\u003e {\n  // get app instance\n  await app.runSchedule('clean_cache');\n});\n```\n\n## Questions \u0026 Suggestions\n\nPlease open an issue [here](https://github.com/eggjs/egg/issues).\n\n## License\n\n[MIT](LICENSE)\n\n## Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=eggjs/schedule)](https://github.com/eggjs/schedule/graphs/contributors)\n\nMade with [contributors-img](https://contrib.rocks).\n","funding_links":[],"categories":["仓库"],"sub_categories":["[内置插件](https://eggjs.org/zh-cn/basics/plugin.html#%E6%8F%92%E4%BB%B6%E5%88%97%E8%A1%A8)"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feggjs%2Fschedule","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feggjs%2Fschedule","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feggjs%2Fschedule/lists"}