{"id":28066820,"url":"https://github.com/needim/recurrentry","last_synced_at":"2025-07-01T05:37:12.055Z","repository":{"id":282396559,"uuid":"927861787","full_name":"needim/recurrentry","owner":"needim","description":"An opinionated library for handling recurring payments.","archived":false,"fork":false,"pushed_at":"2025-05-05T19:02:09.000Z","size":209,"stargazers_count":23,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-07T16:14:55.453Z","etag":null,"topics":["recurrence","recurrence-rules"],"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/needim.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":"2025-02-05T17:03:08.000Z","updated_at":"2025-05-05T19:02:13.000Z","dependencies_parsed_at":"2025-03-14T12:25:44.690Z","dependency_job_id":"590c638a-7122-4125-8502-dfec9f9ea3ad","html_url":"https://github.com/needim/recurrentry","commit_stats":null,"previous_names":["needim/recurrentry"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needim%2Frecurrentry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needim%2Frecurrentry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needim%2Frecurrentry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needim%2Frecurrentry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/needim","download_url":"https://codeload.github.com/needim/recurrentry/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253770422,"owners_count":21961769,"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":["recurrence","recurrence-rules"],"created_at":"2025-05-12T15:54:50.689Z","updated_at":"2025-05-12T15:54:51.129Z","avatar_url":"https://github.com/needim.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🌀 recurrentry\n\n![TypeScript Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/needim/ccae711fb07ccaed86d73f03c1922557/raw/badge.json)\n\n\u003e [!CAUTION]\n\u003e This is a work in progress and the API is not stable yet. Don't use it in production.\n\nA highly opinionated TypeScript library for handling recurring payments with precision and flexibility.\n\nI built this library to help me manage my personal finances and automate recurring payments for my income \u0026 expense trackking app [gider.im](https://gider.im?utm_source=recurrentry\u0026utm_medium=github\u0026utm_campaign=library).\n\n## 🚀 Key Features\n\n### Payment Scheduling\n\n- ✨ Single and recurring payments (single, weekly, monthly, yearly)\n- 🔄 Support for payment modifications (edit, delete)\n- 💼 Business day adjustments (weekends/holidays)\n- ⏰ Grace period support for payment due dates\n- 📆 Day-level precision using Temporal API\n- 🛡️ Type-safe configuration with TypeScript\n\n### Advanced Payment Rules\n\n- 🔢 Flexible payment intervals (every X weeks/months/years)\n- 📅 Ordinal day specifications:\n  - `first-monday`, `last-friday`, `first-weekday`, `last-weekend`\n  - Supports all combinations of:\n    - Position: first, second, third, fourth, fifth, last, nextToLast\n    - Type: day, weekday, weekend, or specific day (monday-sunday)\n- 📅 Weekly payment features:\n  - Specify days of the week (1-7, where 1 is Monday)\n  - Skip weeks with the \"every\" parameter (e.g., bi-weekly payments)\n  - Set specific payment days within each week\n\n### Modifications for Recurring Payments\n\n- ✏️ Edit amount, date for recurring payments\n- 🗑️ Delete single or future occurrences\n- 📝 Apply changes to future payments\n- Single payments are not modified, they are as is (you need to modify them manually)\n\n## 🗓️ Date Handling\n\nThe library operates with day-level precision using the Temporal API:\n\n- Uses `Temporal.PlainDate` for all date operations\n- Helper function `createDate()` provided for easy date creation\n\n## 📦 Installation\n\n```bash\npnpm install recurrentry\n# or\nbun install recurrentry\n# or\nnpm install recurrentry\n# or\nyarn add recurrentry\n```\n\n## 🎯 Quick Example\n\n```typescript\nconst data = [\n  {\n    id: 1,\n    name: \"Single Payment\",\n    amount: \"100.00\",\n    type: \"income\",\n    date: createDate(\"2024-01-01\"),\n    config: {\n      period: PERIOD.NONE,\n      start: createDate(\"2024-01-01\"),\n      interval: 1,\n    } satisfies SinglePayment,\n  },\n  {\n    id: 3,\n    name: \"Weekly Income\",\n    amount: \"255.00\",\n    type: \"income\",\n    date: createDate(\"2024-01-01\"),\n    config: {\n      period: PERIOD.WEEK,\n      start: createDate(\"2024-01-01\"),\n      interval: 5,\n      options: {\n        every: 1,\n        workdaysOnly: \"next\",\n      },\n    } satisfies WeeklyPayment,\n  },\n  {\n    id: 4,\n    name: \"Credit Card\",\n    amount: \"1000.00\",\n    type: \"expense\",\n    date: createDate(\"2024-01-01\"),\n    config: {\n      period: PERIOD.MONTH,\n      start: createDate(\"2024-01-01\"),\n      interval: 5,\n      options: {\n        every: 1,\n        workdaysOnly: \"next\",\n        gracePeriod: 10,\n      },\n    } satisfies MonthlyPayment,\n  },\n];\n\n// Let's generate the payments\nconst result = generator({\n  data,\n  modifications: [\n    {\n      itemId: 3,\n      index: 2,\n      payload: {\n        amount: \"411.00\",\n      },\n      restPayload: {\n        amount: \"300.00\",\n      },\n    },\n    {\n      itemId: 3,\n      index: 4,\n      payload: {\n        amount: \"555.12\",\n      },\n    },\n    {\n      itemId: 4,\n      index: 3,\n      payload: {\n        date: createDate(\"2024-03-15\"),\n        amount: \"6087.22\",\n      },\n    },\n  ],\n  weekendDays: [6, 7], // Saturday and Sunday\n  holidays: [createDate(\"2024-01-01\")], // New Year's Day\n});\n```\n\n## 🟰 Example Generator Result\n\n| #   | index | name           |  amount | period  | occurrence date | payment date |\n| --- | ----- | -------------- | ------: | :-----: | --------------- | ------------ |\n| 1   |       | Single Payment |  100.00 | `none`  | 2024-01-01      | 2024-01-01   |\n|     |       |                |         |         |                 |              |\n| 3   | 1     | Weekly Income  |  255.00 | `week`  | 2024-01-01      | 2024-01-02   |\n| 3   | 2     | Weekly Income  |  411.00 | `week`  | 2024-01-08      | 2024-01-08   |\n| 3   | 3     | Weekly Income  |  300.00 | `week`  | 2024-01-15      | 2024-01-15   |\n| 3   | 4     | Weekly Income  |  555.12 | `week`  | 2024-01-22      | 2024-01-22   |\n| 3   | 5     | Weekly Income  |  300.00 | `week`  | 2024-01-29      | 2024-01-29   |\n|     |       |                |         |         |                 |              |\n| 4   | 1     | Credit Card    | 1000.00 | `month` | 2024-01-01      | 2024-01-11   |\n| 4   | 2     | Credit Card    | 1000.00 | `month` | 2024-02-01      | 2024-02-12   |\n| 4   | 3     | Credit Card    | 6087.22 | `month` | 2024-03-15      | 2024-03-15   |\n| 4   | 4     | Credit Card    | 1000.00 | `month` | 2024-04-01      | 2024-04-11   |\n| 4   | 5     | Credit Card    | 1000.00 | `month` | 2024-05-01      | 2024-05-13   |\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a new branch for your changes\n3. Make your changes and write tests if applicable\n4. Submit a pull request\n\n## 📄 License\n\nLicensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneedim%2Frecurrentry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneedim%2Frecurrentry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneedim%2Frecurrentry/lists"}