{{ message }}
Add Bun + SQLite example app and pre-launch friction fixes#4
Merged
Conversation
- Public method name now matches the Store contract method (store.getActiveJobByKey). Behavior unchanged: terminal jobs return null because the key may have been reused by a fresh schedule. The active-only filter is load-bearing for schedule idempotency, unschedule, debounce/throttle window semantics, and the assertKeyReusable invariant. - JSDoc on the renamed method documents the filter and points to getJob(id) for status-agnostic lookup. - JSDoc on the PollingScheduler constructor surfaces option defaults (interval 1000ms, stalledCheckInterval 30000ms, maxConcurrent 10) so new PollingScheduler() is self-documenting on hover. - Pre-1.0 breaking; CHANGELOG entry under [Unreleased].
- dk.stop({ closeStore: true }) closes the store after the scheduler
drains, hiding the scheduler.stop() → store.close() order inside
the library where the invariant lives. The canonical shutdown for
a long-running app that owns its store is now one call instead of
two.
- Default closeStore: false preserves the post-stop-cleanup contract
(cancel/unschedule remain available after dk.stop returns) and the
shared-store / shared-pool case.
- dk.stop() docstring now states it is idempotent — repeated or
concurrent calls await the same in-flight shutdown promise.
- SQLiteStore.close() is now idempotent (was throwing on second
call). MemoryStore and PostgresStore were already idempotent.
- examples/bun-sqlite-server/ — minimal HTTP server demonstrating
dk.schedule, getActiveJobByKey, and unschedule against a
SQLiteStore + PollingScheduler. ~80 lines of server.ts with
inline DTO projection and one-call shutdown via
dk.stop({ closeStore: true }).
- README covers run, curl examples, env vars, and persistence
across restarts. `bun run setup` builds the parent's dist/ and
installs deps so a fresh clone runs cleanly with no extra steps.
- docs/deploy.md: canonical SIGTERM snippet updated to use
closeStore: true and idempotent shutdown; pointer to the example
added at the end of the Bun-server section.
cgenuity
added a commit
that referenced
this pull request
May 3, 2026
- Add Vocabulary preamble; renumber the remaining 7 invariants (former #3 Identity model becomes the preamble; #4–#8 shift down) - Remove the handler-idempotency invariant — it was end-user authoring guidance, not a property the library maintains, and is already covered by invariant #3 (atomic claim) and the README's Crash recovery paragraph - Move schedule()/debounce()/throttle()/cancel() behavior spec to docs/api.md under a new Behavior section, with a back-pointer for the correctness model - Replace the schema DDL with a one-line link to the migration files; keep the required-indexes paragraph (which is invariant material) - Consolidate "Race conditions and recovery" from six implementation walkthroughs to four invariant-led subsections - Drop the contract-test prescription from #2's "Active-slot acquisition" paragraph — test guidance, not a runtime contract - Standardize "Posthook" capitalization (was "PostHook" in 4 spots) - Update the one cross-reference (`invariant #4` → `invariant #3`) in both the doc and test/race-conditions.test.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
examples/bun-sqlite-server/— a minimal single-file Bun server demonstratingdk.schedule,dk.getActiveJobByKey, anddk.unscheduleagainstSQLiteStore+PollingScheduler. ~80 lines, inline DTO projection, one-call shutdown viadk.stop({ closeStore: true }). Run withbun run setup && bun run server.tsfrom a fresh clone.dk.getJobByKeyrenamed todk.getActiveJobByKeyfor parity with theStorecontract method. Behavior unchanged — terminal jobs still return null because the key may have been reused. New JSDoc clarifies the active-only filter and points togetJob(id)for status-agnostic lookup.StopOptions.closeStore?: boolean(defaultfalse) —dk.stop({ closeStore: true })closes the store after the scheduler drains, hiding the lifecycle order inside the library. Default staysfalseto preserve the post-stop-cleanup contract (cancel/unscheduleafter stop) and the shared-pool case.SQLiteStore.close()is now idempotent. JSDoc added todk.stop()(states it is idempotent) andPollingSchedulerconstructor (summarizes default options).docs/deploy.mdcanonical SIGTERM snippet updated to usecloseStore: trueand the new idempotent shutdown; pointer to the example added at the end of the Bun-server section.Test plan
npm run typecheck— cleannpm run test— 469 passednpm run test:postgres— 117 passed (Docker postgres up at `localhost:5444`)npm run test:packaging— 8 passednpm run test:bun— 199 passed