@gj-kit/nest-notifications core concepts
A dispatcher with no presenter, or quiet hours with no time zone, is a compile error — not a DST bug in production.
Why this boundary exists
Section titled “Why this boundary exists”A hand-rolled notification outbox loses deliveries to non-atomic claims, writes duplicate inbox rows when two workers grab the same batch, and pushes to accounts that were deleted mid-relay. Then quiet hours turn out to be a fixed offset added to a Date, drifting an hour every DST transition, and a batch window that does not divide 24h moves the aggregation bucket every day.
Durability lives in the host store
Section titled “Durability lives in the host store”The package supplies ordering and relay rules, while the application implements the durable store, presenter, push gateway, and product policy.
Time policy needs a timezone
Section titled “Time policy needs a timezone”Quiet hours and batching are not fixed offsets. A timezone and valid daily window keep DST and aggregation behavior explainable.
What the package enforces
Section titled “What the package enforces”- Required options, enforced by tsc — createNotificationDispatcher without a presenter and createQuietHoursPolicy without a timeZone do not compile — no default copy, no default region.
- 30 contract cases for your database — notificationStoreContractCases() returns 30 runnable cases covering 29 numbered obligations: atomic claim, batch uniqueness, purge-versus-relay interleaving.
- A core Nest cannot leak into — Guards assert the strings @nestjs, rxjs and reflect-metadata appear nowhere in src/core, src/expo or src/testing, and nowhere in the dist/core., dist/expo. and dist/testing.* module graphs — with a control case requiring dist/index.js to contain @nestjs, so the guard is proven not to be checking an empty set.
- The latency hint returns void — NotificationPipelineWakeup.request() returns void — nothing to await, no result to inspect, no error to catch — so it cannot be mistaken for the owner of correctness. A test wires only that hint, advances the clock 12 hours, and finds the batched delivery still undelivered until dispatchDue() is called.
- DST resolution is a contract — A spring-forward gap releases at the first instant after it, an autumn fold at the earlier one, and batchWindowMs must divide 24h evenly or assembly throws ERR_NOTIFICATION_POLICY_INVALID.
What remains application-owned
Section titled “What remains application-owned”Keep credentials, endpoint ownership, and user-visible product wording in the application. Use the typed error and delivery outcomes instead of raw provider failures.
Continue with the two verified recipes.