Skip to content

docs(job): clarify JSON-serialization caveat for job.data (#2539)#4137

Open
maruthang wants to merge 1 commit into
taskforcesh:masterfrom
maruthang:fix/issue-2539-job-data-jsdoc-clarification
Open

docs(job): clarify JSON-serialization caveat for job.data (#2539)#4137
maruthang wants to merge 1 commit into
taskforcesh:masterfrom
maruthang:fix/issue-2539-job-data-jsdoc-clarification

Conversation

@maruthang

Copy link
Copy Markdown
Contributor

Port Impact Checklist

  • Python – does this change need to be ported or documented in the Python library?
  • Elixir – does this change need to be ported or documented in the Elixir library?
  • PHP – does this change need to be ported or documented in the PHP library?

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 that job.data is 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.data field — note that data is JSON-serialized when persisted, so only JSON-safe values survive a round trip; class instances lose their prototype/methods.
  • Job.createdata param JSDoc states the same caveat.
  • Queue.adddata param JSDoc states the same caveat.
  • Queue.addBulk — JSDoc states that each job's data is serialized in the same way.

Plus a new section in docs/gitbook/guide/jobs/job-data.md:

  • "Data is serialized as JSON" — explains the round trip explicitly and shows the recommended workaround pattern: producer sends a plain object, processor re-instantiates the class. Mentions toJSON() as an alternative when a custom serialized shape is desired.

No code changes, no test changes.

Additional Notes (Optional)

  • Documentation-only PR. No runtime behavior changes.
  • Verified runtime behavior in src/classes/job.ts (asJSON() / fromJSON() use plain JSON.stringify / JSON.parse with no toJSON revival hook on the parse side) so the docs match what the code actually does.
  • The python/elixir/php ports likely have the same caveat in their respective docs and may warrant follow-up PRs in those directories. Out of scope for this Node-focused PR.

…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 manast left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove dashes so that the text does not look so obviously written by an LLM.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants