docs(job): clarify JSON-serialization caveat for job.data (#2539)#4137
Open
maruthang wants to merge 1 commit into
Open
docs(job): clarify JSON-serialization caveat for job.data (#2539)#4137maruthang wants to merge 1 commit into
maruthang wants to merge 1 commit into
Conversation
…h#2539) The reporter expected `job.data.someMethod()` to work after passing a class instance into the queue. The JSDoc and docs did not clearly warn against this. Job data is JSON-serialized through Redis (`JSON.stringify` on `Queue.add`, `JSON.parse` on the worker), so prototypes/methods are stripped. This is intentional and unchanged. Make the caveat explicit at the canonical surfaces: - `Job.data` field JSDoc - `Job.create`'s `data` param JSDoc - `Queue.add`'s `data` param JSDoc - `Queue.addBulk` JSDoc Also add a "Data is serialized as JSON" section to `docs/gitbook/guide/jobs/job-data.md` documenting the recommended workaround (re-instantiate the class in the processor, or implement `toJSON()`). No runtime behavior changes. Refs taskforcesh#2539
manast
reviewed
May 4, 2026
manast
left a comment
Contributor
There was a problem hiding this comment.
remove dashes so that the text does not look so obviously written by an LLM.
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
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.
Port Impact Checklist
Why
The reporter in #2539 expected
job.data.someMethod()to work after passing a class instance into the queue, but methods were missing. The current JSDoc and docs do not clearly warn thatjob.datais JSON-serialized through Redis on the way in and JSON-parsed on the way out, which strips prototypes/methods. The underlying behavior is correct and unchanged — this PR is a documentation-only clarification at the canonical user-facing surfaces.Refs #2539
How
JSDoc edits on the four entry points where users encounter
data:Job.datafield — note that data is JSON-serialized when persisted, so only JSON-safe values survive a round trip; class instances lose their prototype/methods.Job.create—dataparam JSDoc states the same caveat.Queue.add—dataparam JSDoc states the same caveat.Queue.addBulk— JSDoc states that each job'sdatais serialized in the same way.Plus a new section in
docs/gitbook/guide/jobs/job-data.md:toJSON()as an alternative when a custom serialized shape is desired.No code changes, no test changes.
Additional Notes (Optional)
src/classes/job.ts(asJSON()/fromJSON()use plainJSON.stringify/JSON.parsewith notoJSONrevival hook on the parse side) so the docs match what the code actually does.