bsuir-iis-api 0.7.0 → 0.9.1

package/CHANGELOG.md

@@ -1,12 +1,52 @@
 # Changelog
 
-All notable changes to this project are documented in this file.
+## [0.9.1] - 2026-05-10
 
-The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-This changelog is maintained manually and updated in release commits.
+### Fixed
+
+- `http.ts`: cache eviction now performs true LRU — entries are sorted by `accessedAt` timestamp before eviction instead of relying on Map insertion order (which produced FIFO behaviour, not LRU).
+- `http.ts`: `setCache` now removes the key before re-inserting on a cache refresh, ensuring Map insertion order stays consistent with actual last-write time.
+- `http.ts`: `canUseCaching` and `canUseDedup` now check `config.signal?.aborted` in addition to per-request `options.signal`; previously a globally aborted client signal did not suppress cache reads, which could return stale data after cancellation.
+
+### Documentation
+
+- `types.ts`: all `BsuirClientOptions` fields now have full JSDoc — description, `@defaultValue`, `@example`, and side-effect notes where applicable.
+- `types.ts`: `validateResponses` JSDoc explicitly recommends `process.env.NODE_ENV !== "production"` as a sensible default pattern and clarifies the performance trade-off.
+- `types.ts`: `signal` JSDoc clarifies that an aborted global signal suppresses both cache reads and in-flight deduplication.
+
+## [0.9.0] - 2026-05-10
+
+### Added
+
+- Public exports for schedule utilities: `normalizeSchedule` and `filterLessons`.
+- Public re-export of `ScheduleFilterOptions` type from `src/index.ts`.
+- Global cancellation support via `createBsuirClient({ signal })`.
+- `src/modules/index.ts` barrel for module factory imports.
+- In-memory GET cache via `createBsuirClient({ cache: { ttlMs, maxEntries } })`.
+- In-flight GET request deduplication via `dedupeInFlight`.
+- Opt-in runtime response-shape validation via `validateResponses` and `BsuirResponseValidationError`.
+- Request lifecycle hooks via `createBsuirClient({ hooks })`: `onRequest`, `onRetry`, `onResponse`, `onError`.
+- API Extractor configuration (`api-extractor.json`) and npm scripts for local/update and CI checks.
+- `POST` method support in `requestJson` via `options.method` and `options.body`.
+
+### Fixed
+
+- `schedule.getGroup/getEmployee` return typing now follows client-level `defaultRaw` when `raw` is omitted.
+- `normalizeSchedule` no longer duplicates day-item flattening work and avoids repeated `auditories` normalization per lesson.
+- Strict date parsing in `parseDdMmYyyy` now rejects non-existent calendar dates (for example `31.02.2026`).
+- `BsuirNetworkError` now relies on standard `Error.cause` instead of duplicate `causeError` field.
+- Client option validation now rejects invalid timeout/retry configuration values early.
+- `week.ts`: passing an empty string now throws a clear `BsuirValidationError` ("is an empty string") instead of a misleading "must be a positive integer" message.
+- `filterLessons`: `weekNumber: 0` is now rejected with `assertPositiveInt` instead of silently passing.
+- `http.ts`: cache eviction now uses pseudo-LRU (oldest-inserted Map key, O(1)) instead of an O(n) scan; `inFlightPromise` is typed as `Promise<T>` to eliminate unsafe `as Promise<unknown>` cast.
+- `http.ts`: restored file integrity after shell heredoc substitution corrupted ES module imports; fixed `@typescript-eslint/no-unsafe-call` error on `inFlight` read by shifting the `as T` cast to the Promise type before `await`.
+
+### Changed
 
-## [Unreleased]
+- JSDoc for `defaultRaw` client option now clarifies that a per-call `raw` option takes priority and includes an `@example` for both cases.
+- Dev tooling: bumped TypeScript to 6.0.3, ESLint to ^10.2.1, Vitest and `@vitest/coverage-v8` to ^4.1.4, `@types/node` to ^25.6.0, `@typescript-eslint/*` and `typescript-eslint` to ^8.58.2, `@changesets/cli` to ^2.31.0, `@microsoft/api-extractor` to ^7.58.5, Prettier to ^3.8.3, `globals` to ^17.5.0; regenerated `package-lock.json`.
+- CI now validates API report compatibility via `npm run api:report:check` (Node 24 job in matrix).
+- `vitest.config.ts`: added coverage thresholds (`lines: 80`, `functions: 80`) to enforce minimum test coverage on CI.
 
 ## [0.7.0] - 2026-04-19
 

package/README.md

@@ -38,11 +38,24 @@ const client = createBsuirClient({
   retryDelayMs: 300,
   retryMaxDelayMs: 3000,
   retryJitter: true,
+  cache: { ttlMs: 60_000, maxEntries: 200 },
+  dedupeInFlight: true,
+  validateResponses: false,
+  hooks: {
+    onRetry: ({ endpoint, delayMs, reason }) => {
+      console.log("retry", endpoint, delayMs, reason);
+    }
+  },
   defaultRaw: false
 });
 ```
 
 - `fetch` can be passed for custom runtime/testing.
+- `signal` in `createBsuirClient({ signal })` acts as a global cancellation signal for all requests made by that client.
+- `cache` stores successful GET responses in-memory for the configured TTL.
+- `dedupeInFlight` reuses the same in-flight GET request for concurrent callers (when no per-request signal is passed).
+- `validateResponses` enables runtime payload-shape checks for key endpoints.
+- `hooks` provides lifecycle callbacks (`onRequest`, `onRetry`, `onResponse`, `onError`) for observability.
 - `AbortSignal` is supported by all read methods.
 
 ## API
@@ -84,7 +97,8 @@ When IIS responds with HTTP `404` or `400` (no list, missing resource, or endpoi
 SDK throws typed errors:
 
 - `BsuirApiError` for HTTP errors (contains `status`, `endpoint`, `body`). **Exception:** `client.announcements.byEmployee` / `byDepartment` resolve to `[]` on IIS HTTP `404` or `400` instead of throwing (see Announcements above).
-- `BsuirNetworkError` for transport errors (contains `endpoint`, `causeError`, and standard `cause`)
+- `BsuirNetworkError` for transport errors (contains `endpoint` and standard `cause`)
+- `BsuirResponseValidationError` for invalid payload shapes when `validateResponses: true`
 - `BsuirTimeoutError` for timeouts (contains `endpoint`, `timeoutMs`)
 - `BsuirValidationError` for invalid input parameters
 - `BsuirConfigurationError` when the runtime has no `fetch` and none was passed to `createBsuirClient({ fetch })`
@@ -151,6 +165,7 @@ npm run lint
 npm run lint:fix
 npm run check
 npm run build
+npm run api:report
 ```
 
 `npm run build` uses [tsup](https://tsup.egoist.dev/) with [`experimentalDts`](https://tsup.egoist.dev/) so `.d.ts` output is produced via `@microsoft/api-extractor` rather than the legacy Rollup declaration path (which is awkward with TypeScript 6’s `baseUrl` deprecation). TypeScript’s handbook notes that [`paths` can be used without `baseUrl`](https://www.typescriptlang.org/docs/handbook/modules/reference.html) when you need path mapping.