From ef0e138448aa2dc3031ed475b7c2ecc400d2760e Mon Sep 17 00:00:00 2001 From: Julian Maurer Date: Mon, 29 Sep 2025 18:14:32 +0200 Subject: [PATCH 1/3] Improved documentation with usage examples --- EXAMPLES.md | 172 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 +- package.json | 2 +- src/helpers.ts | 5 +- typedoc.json | 3 + 5 files changed, 181 insertions(+), 5 deletions(-) create mode 100644 EXAMPLES.md create mode 100644 typedoc.json diff --git a/EXAMPLES.md b/EXAMPLES.md new file mode 100644 index 0000000..8b88465 --- /dev/null +++ b/EXAMPLES.md @@ -0,0 +1,172 @@ +# Usage Examples + +This section provides examples of typical usage scenarios. For detailed information on how to use the library, please refer to the complete [documentation](https://docs.epilot.io/docs/deadlines/deadlines-library/). + +## Calculating a single deadline + +Use the function `calculateDeadline` when you only need the earliest possible contract start date for a single case, without additional details. + +### Example + +```typescript +import { calculateDeadline, Commodity, UseCase } from '@epilot/switching-deadlines' + +const result = calculateDeadline( + { + commodity: Commodity.POWER, + useCase: UseCase.SWITCH, + requiresTermination: true + }, + '2025-10-01' // optional date to calculate from +) + +console.log(result) +``` + +### Expected Output + +``` +2025-10-07 +``` + +## Validating a date + +Use the function `validateDate` if you want to quickly check whether a specific switching date is valid for a given commodity and use case. + +### Example + +```typescript +import { validateDate, Commodity, UseCase } from '@epilot/switching-deadlines' + +const isValid = validateDate( + { + commodity: Commodity.POWER, + useCase: UseCase.SWITCH, + requiresTermination: true + }, + '2025-01-05', // proposed start date + '2025-10-01' // optional date to calculate from +) + +console.log(isValid) +``` + +### Expected Output + +``` +false +``` + +## Using the Deadline Calculator + +Use the `DeadlineCalculator` class when you need more detailed results (e.g., for APIs or batch calculations), including applied rules and working days. + +### Example + +```typescript +import { DeadlineCalculator, Commodity, UseCase } from '@epilot/switching-deadlines' + +const calculator = new DeadlineCalculator() + +const result = calculator.calculateEarliestStartDate( + { + commodity: Commodity.POWER, + useCase: UseCase.SWITCH, + requiresTermination: true + }, + '2025-10-01' +) + +console.log(result) +``` + +### Expected Output + +```json +{ + earliestStartDate: 2025-10-07T00:00:00.000Z, + earliestStartDateString: '2025-10-07', + workingDaysApplied: 2, + calendarDaysTotal: 6, + isRetrospective: false, + ruleApplied: { + id: 'power_switch_with_termination', + commodity: 'power', + useCase: 'switch', + requiresTermination: true, + requiredWorkingDays: 2, + allowsRetrospective: false, + description: 'Power contract switch with termination requires 2 working days lead time' + } +``` + +## Using a custom Calendar Provider + +Use a custom calendar provider if you want to include one-time or special holidays not yet reflected in the default calendar. + +### Example + +```typescript +import { DeadlineCalculator, CalendarProvider, HolidayType } from '@epilot/switching-deadlines' + +const customCalendar = new CalendarProvider({ + customCalendar: { + holidays: [ + { + date: '2026-03-10', + name: 'Einmaliger Sonderfeiertag', + type: HolidayType.SPECIAL_HOLIDAY, + description: 'Special holiday for demonstration purposes', + isOneTime: true + } + ] + }, + useSpecialHolidays: true +}) + +const calculator = new DeadlineCalculator({ + customCalendarProvider: customCalendar +}) +``` + +## Checking the library version + +Tp verify that your library installation contains the latest holiday updates and is up to date. + +### Example + +```typescript +import { getVersion } from '@epilot/switching-deadlines' + +const { version } = getVersion() + +console.log(`Library version: ${version}`) +``` + +### Expected Output + +``` +Library version: 2025.1.4 +``` + +Alternatively, you can use the `CalendarProvider` to check the version details. + +### Example + +```typescript +import { CalendarProvider } from '@epilot/switching-deadlines' + +const customCalendar = new CalendarProvider() + +console.log(customCalendar.getCalendarVersion()) +``` + +### Expected Output + +```json +{ + version: "2025.1.4", + year: 2025, + lastUpdated: "2025-09-29T13:20:52.863Z" +} +``` diff --git a/README.md b/README.md index 6366d47..e92bd4e 100644 --- a/README.md +++ b/README.md @@ -78,9 +78,11 @@ console.log( ) ``` +Check [EXAMPLES.md](EXAMPLES.md) for more usage examples. + ## 📖 Documentation -Comprehensive usage examples and background information are available in the 👉 [epilot dev center](https://docs.epilot.io/docs/deadlines/intro). +Comprehensive documentation and background information are available in the 👉 [epilot dev center](https://docs.epilot.io/docs/deadlines/intro). ## 📜 Disclaimer diff --git a/package.json b/package.json index ebb6d4d..08e1b5d 100644 --- a/package.json +++ b/package.json @@ -41,7 +41,7 @@ "clean": "rimraf dist coverage", "prepare": "pnpm run build", "prepublishOnly": "pnpm run build", - "gen-docs": "rm -rf docs && typedoc --plugin typedoc-plugin-markdown --out docs src && echo '{ \"label\": \"Switching Deadlines Library\", \"position\": 0 }' > docs/_category_.json" + "gen-docs": "rm -rf docs && typedoc --plugin typedoc-plugin-markdown --out docs src/index.ts && echo '{ \"label\": \"Switching Deadlines Library\", \"position\": 0 }' > docs/_category_.json" }, "keywords": [], "author": "epilot GmbH", diff --git a/src/helpers.ts b/src/helpers.ts index 2d80ba4..654d68c 100644 --- a/src/helpers.ts +++ b/src/helpers.ts @@ -40,14 +40,13 @@ export function calculateDeadline( * ```typescript * import { validateDate, Commodity, UseCase } from '@epilot/switching-deadlines'; * - * const result = validateDate('2025-10-05', { + * const isValid = validateDate('2025-10-05', { * commodity: Commodity.POWER, * useCase: UseCase.SWITCH, * requiresTermination: true * }); * - * console.log(result.isValid); // false - * console.log(result.earliestValidDate); // Date object for 2025-10-07 + * console.log(isValid); // false * ``` */ export function validateDate( diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 0000000..de6a1f5 --- /dev/null +++ b/typedoc.json @@ -0,0 +1,3 @@ +{ + "projectDocuments": ["./CHANGELOG.md", "./EXAMPLES.md"] +} From 6764c18ea2525d949c8b9824eea28bc98b53665e Mon Sep 17 00:00:00 2001 From: Julian Maurer Date: Mon, 29 Sep 2025 18:15:57 +0200 Subject: [PATCH 2/3] Add linting step to CI pipeline --- .github/workflows/build-and-test.js.yml | 31 +++++++++++++------------ 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/.github/workflows/build-and-test.js.yml b/.github/workflows/build-and-test.js.yml index 998fbdd..82fc382 100644 --- a/.github/workflows/build-and-test.js.yml +++ b/.github/workflows/build-and-test.js.yml @@ -5,13 +5,12 @@ name: Build and Test on: push: - branches: [ "main" ] + branches: ["main"] pull_request: - branches: [ "main" ] + branches: ["main"] jobs: build: - runs-on: ubuntu-latest strategy: @@ -20,15 +19,17 @@ jobs: # See supported Node.js release schedule at https://nodejs.org/en/about/releases/ steps: - - uses: actions/checkout@v4 - - name: Install pnpm - uses: pnpm/action-setup@v4 - - name: Use Node.js ${{ matrix.node-version }} - uses: actions/setup-node@v4 - with: - node-version: ${{ matrix.node-version }} - cache: "pnpm" - - name: Install dependencies - run: pnpm install - - name: Run tests - run: pnpm test + - uses: actions/checkout@v4 + - name: Install pnpm + uses: pnpm/action-setup@v4 + - name: Use Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: "pnpm" + - name: Install dependencies + run: pnpm install + - name: Run linting + run: pnpm lint + - name: Run tests + run: pnpm test From ccb62c1916572d2783e8abbeb6540dce7443ad34 Mon Sep 17 00:00:00 2001 From: Julian Maurer Date: Mon, 29 Sep 2025 18:56:00 +0200 Subject: [PATCH 3/3] Small improvements --- EXAMPLES.md | 6 +++--- README.md | 7 ++----- 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/EXAMPLES.md b/EXAMPLES.md index 8b88465..e9f0fad 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -1,6 +1,6 @@ -# Usage Examples +# 📖 Usage Examples -This section provides examples of typical usage scenarios. For detailed information on how to use the library, please refer to the complete [documentation](https://docs.epilot.io/docs/deadlines/deadlines-library/). +This section provides examples of typical usage scenarios. For detailed information on how to use the library, please refer to the complete [documentation](https://docs.epilot.io/docs/deadlines/deadlines-library/index/). ## Calculating a single deadline @@ -131,7 +131,7 @@ const calculator = new DeadlineCalculator({ ## Checking the library version -Tp verify that your library installation contains the latest holiday updates and is up to date. +To verify that your library installation contains the latest holiday updates and is up to date. ### Example diff --git a/README.md b/README.md index e92bd4e..fcd04e5 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A TypeScript library for handling German energy market compliance requirements, specifically supplier switching deadlines as defined by **GPKE** (power) and **GeLi Gas** (gas). -This library is regularly updated to reflect the latest calendar updates. You can find the changelog at [CHANGELOG.md](CHANGELOG.md). +This library is regularly updated to reflect the latest calendar updates. You can find the changelog at [here](CHANGELOG.md). ## ✨ Features @@ -77,10 +77,7 @@ console.log( `${`The earliest start date is ${relocationResult.earliestStartDate} for relocation and ${switchResult.earliestStartDate} for switching`}` ) ``` - -Check [EXAMPLES.md](EXAMPLES.md) for more usage examples. - -## 📖 Documentation +You can find more information in the 📖 [usage examples](EXAMPLES.md). Comprehensive documentation and background information are available in the 👉 [epilot dev center](https://docs.epilot.io/docs/deadlines/intro).