recurrentry v0.3.1

A highly opinionated TypeScript library for handling recurring payments with precision and flexibility.

I built this library to help me manage my personal finances and automate recurring payments for my income & expense trackking app gider.im.

🚀 Key Features

Payment Scheduling

• ✨ Single and recurring payments (single, weekly, monthly, yearly)
• 🔄 Support for payment modifications (edit, delete)
• 💼 Business day adjustments (skip weekends/holidays)
• ⏰ Grace period support for payment due dates
• 📆 Day-level precision using Temporal API
• 🛡️ Type-safe configuration with TypeScript

Advanced Payment Rules

• 🔢 Flexible payment intervals (every X weeks/months/years)
• 📅 Ordinal day specifications:
  • first-monday, last-friday, first-weekday, last-weekend
  • Supports all combinations of:
    • Position: first, second, third, fourth, fifth, last, nextToLast
    • Type: day, weekday, weekend, or specific day (monday-sunday)
• 📅 Weekly payment features:
  • Specify days of the week (1-7, where 1 is Monday)
  • Skip weeks with the "every" parameter (e.g., bi-weekly payments)
  • Set specific payment days within each week

Modifications

• ✏️ Edit amount, date, or recurrence rules
• 🗑️ Delete single or future occurrences
• 📝 Apply changes to future payments

🗓️ Date Handling

The library operates with day-level precision using the Temporal API:

• Uses Temporal.PlainDate for all date operations
• Helper function createDate() provided for easy date creation
• It's a peer dependency

📦 Installation

pnpm install recurrentry
# or
bun install recurrentry
# or
npm install recurrentry
# or
yarn add recurrentry

🎯 Quick Example

const data = [
  {
    id: 1,
    name: "Single Payment",
    amount: "100.00",
    type: "income",
    date: createDate("2024-01-01"),
    config: {
      period: PERIOD.NONE,
      start: createDate("2024-01-01"),
      interval: 1,
    } satisfies SinglePayment,
  },
  {
    id: 3,
    name: "Weekly Income",
    amount: "255.00",
    type: "income",
    date: createDate("2024-01-01"),
    config: {
      period: PERIOD.WEEK,
      start: createDate("2024-01-01"),
      interval: 5,
      options: {
        every: 1,
        workdaysOnly: true,
      },
    } satisfies WeeklyPayment,
  },
  {
    id: 4,
    name: "Credit Card",
    amount: "1000.00",
    type: "expense",
    date: createDate("2024-01-01"),
    config: {
      period: PERIOD.MONTH,
      start: createDate("2024-01-01"),
      interval: 5,
      options: {
        every: 1,
        workdaysOnly: true,
        gracePeriod: 10,
      },
    } satisfies MonthlyPayment,
  },
];

// Let's generate the payments
const result = generator({
  data,
  modifications: [
    {
      itemId: 3,
      index: 2,
      payload: {
        amount: "411.00",
      },
      restPayload: {
        amount: "300.00",
      },
    },
    {
      itemId: 3,
      index: 4,
      payload: {
        amount: "555.12",
      },
    },
    {
      itemId: 4,
      index: 3,
      payload: {
        date: createDate("2024-01-15"),
        amount: "6087.22",
      },
    },
  ],
  weekendDays: [6, 7], // Saturday and Sunday
  holidays: [createDate("2024-01-01")], // New Year's Day
});

🟰 Example Generator Result

🤝 Contributing

1. Fork the repository
2. Create a new branch for your changes
3. Make your changes and write tests if applicable
4. Submit a pull request

📄 License

Licensed under the MIT License.