Repository navigation
feat: add graph-source-contract package - #25
Conversation
The GraphSource port as an @orpc/contract router keyed by version, so one definition runs in process, over a message port or over HTTP. A sync page is a slice of the model: bound activities whose source-qualified id doubles as the element id, participants, transitions, relations, overlay status and gaps, with record schemas taken from the schema package's modelSchema. sync.page and sync.stream share a cursor: each page carries next, the stream yields pages on demand with next as the event id, and a sync resumes from an explicit after or the transport's lastEventId. Failures that end a call are typed UNAUTHORIZED, TOO_MANY_REQUESTS and BAD_REQUEST errors with data; what a source can partly read arrives as gaps. Adapters implement a pager; createGraphSourceRouter builds the port on it. The package ships an in-memory fake, assembleSync, and a conformance kit on a separate entry point that runs through the oRPC client, exercised here over the fake in process and across a MessageChannel.
… connections Adapters walk cursor-linked connections of their own source, such as nested GraphQL connections, with the same on-demand iteration the router streams pages with.
inProcessClient and messagePortClient move from the package's test support into the conformance entry point, so an adapter runs the kit over the same transports as the fake.
…rkspace The workspace moved to vitest 5.0.3 and released the schema package as 1.0.2 while this package was in review, so its dev dependency, its optional conformance peer and its sibling pin follow.
bf859d2 to
569bb4c
Compare
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
@codex security review |
🛡️ Codex Security ReviewSecurity review completed. No security issues were found in this pull request. Reviewed commit: Only the user who started this review can view the report in Codex. ℹ️ About Codex security reviews in GitHubThis is an experimental Codex feature. Security reviews are triggered when:
Once complete, Codex will leave suggestions, or a comment if no findings are found. |
|
@codex security review |
|
🎉 This PR is included in version 1.0.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
🛡️ Codex Security ReviewSecurity review completed. No security issues were found in this pull request. Reviewed commit: Only the user who started this review can view the report in Codex. ℹ️ About Codex security reviews in GitHubThis is an experimental Codex feature. Security reviews are triggered when:
Once complete, Codex will leave suggestions, or a comment if no findings are found. |
Phase 2 of the process-graph plan, first half:
@exadev/process-graph-source-contract, theGraphSourceport.The port is an
@orpc/contractrouter keyed by version (v1.describe,v1.sync.page,v1.sync.stream), so the same definition is called in process, across aMessagePortor over HTTP. A sync page is a slice of the model: bound activities (the source-qualified id such asgithub:org/repo#12is the element id, andsourcemust equal it), participants, transitions, relations (child-of,assigned-to,part-of, for links the model has no field for), overlay status and gaps. Its record schemas come frommodelSchemain the schema package, not restated.Paging and streaming share one cursor. Each page carries
next; the stream yields pages only as the consumer pulls and sets each event id tonext, so a sync resumes from an explicitafteror from the transport'slastEventId, withafterwinning. Failures that end a call are typedUNAUTHORIZED,TOO_MANY_REQUESTS(withresetAt) andBAD_REQUEST(invalid-cursororinvalid-scope) errors carrying data; anything a source can partly read arrives as gaps in the page.Adapters implement a one-page-at-a-time
GraphSourcePagerandcreateGraphSourceRouterbuilds the port on it, so streaming, resumption and error mapping are shared. The package also has an in-memory fake,assembleSync(merges pages into one model, later pages winning) andpaginate.The conformance kit is on its own entry point (
./conformance, Vitest as an optional peer) and talks only to the oRPC client. It runs here against the fake both in process and across aMessageChannel. The v2 beta resume behaviour I was asked to spike is pinned byresume.unit.test.tsover both transports: a stream closed after its first page resumes with exactly the remaining pages byafterand bylastEventId, asserted on activity ids, cursors and the cross-repository transition. I read the behaviour from the installed@orpc/*2.0.0-beta.41 source rather than the v1 docs: event meta survives the contract's output validation (wrapAsyncIteratorPreservingEventMeta), and handlers receivelastEventIdin their options.The GitHub issues adapter follows as a stacked PR. The npm name needs reserving before this merges:
npm-reserve @exadev/process-graph-source-contract --trust ExaDev/process-graph --workflow ci.yml.