docs: external storage TS - #4946
Merged
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
cconstable
marked this pull request as draft
July 22, 2026 17:46
Contributor
📖 Docs PR preview links
|
# Conflicts: # sidebars.js
…ling Rewrite the TypeScript External Storage page against the shipped API in @temporalio/*@1.21.1. Every code sample now typechecks against the published packages. API corrections: - Install @temporalio/external-storage-s3-aws-sdk alongside the driver; S3StorageDriver takes an S3StorageDriverClient, not an S3Client. - ExternalStorage is a class, not an object literal. - StorageDriverClaim is a class taking claimData positionally. - StorageDriver exposes readonly name and type properties rather than a name() method. Document type, which was missing. - context.target is a discriminated union keyed on kind, with the identifier in id. - The AWS SDK for JavaScript does not bundle a SigV4A signer, so MRAP requires installing and importing @aws-sdk/signature-v4a. The previous text described Go SDK behavior and would have left MRAP requests failing. Also adds a Google Cloud Storage section, maxPayloadSize, the required IAM permissions, and the duplicate driver name constraint. Structural: main restructured TypeScript data handling in #4928, so move the page under best-practices/data-handling, fix two links to the removed converters-and-encryption page, and drop the slug to match its siblings. Add the page to the sidebar, the data-handling index table, and the five Go/Python references in the External Storage encyclopedia page.
…ions Replace the ":::info Release, stability, and dependency info" admonition with the ReleaseNoteHeader component on all four External Storage pages (Go, Python, TypeScript, and the encyclopedia). The component renders the "Currently in: Public Preview" pill and links to the release stages page, so the sentence naming the release stage is dropped from the body. The remaining copy carries the API stability caveat and the Slack channel link. Register externalStorage in FEATURE_RELEASE_TYPES so both the component and scripts/mdx-to-md.mjs resolve the label from one place.
The GCS section read as an abbreviated version of the S3 one. Merge both into a single "Store and retrieve large payloads" flow with backend tabs on the two things that actually differ, the install command and the driver construction. The ExternalStorage and Data Converter step is shared, so it is now written once instead of being summarized for GCS. Keep the full backend names in the H2 for search, and pin a short "#store-and-retrieve-large-payloads" anchor so the heading can grow to a third driver without breaking inbound links. Repoint the two encyclopedia deep links at that anchor. Also drop the prerequisites paragraph explaining how the S3 driver packages are split. Prerequisites should say what to install, not describe package internals.
Wraps the seven substantial code blocks in SNIPSTART/SNIPEND markers pointing at the snippets added in temporalio/features#855, matching how the Python and Go pages source their samples. Short blocks stay inline, the same ones the Python and Go pages keep inline: the npm install commands, the SigV4A signer import, and the MRAP bucket example. The markers are inert until features#855 merges. Snipsync skips ids it cannot resolve, verified by a local run that left this page byte identical, so the two PRs can land in either order.
lennessyy
marked this pull request as ready for review
July 27, 2026 22:33
lennessyy
approved these changes
Jul 27, 2026
…s repo The custom-driver example now comes from the external-storage sample in samples-typescript, which runs the driver end to end and tests it, instead of a hand-written copy in the features repo. The sample's FileSystemStorageDriver is a better example than the one it replaces: it content-addresses payloads so retries don't accumulate duplicate blobs, writes atomically, verifies the hash on read, rejects claims that resolve outside the storage root, and stores payloads concurrently while honoring the SDK's abort signal. Also corrects the driver `type` example. The built-in GCS driver reports "gcp.gcsdriver", which the page never mentioned. The S3 and GCS snippets still come from the features repo; the sample has no S3 or GCS code.
All three SDKs offload a payload when its serialized size is greater than or equal to the threshold, not strictly greater: - TypeScript: external-storage-runner.ts, `if (size < payloadSizeThreshold) continue` - Python: _extstore.py, `if payload.ByteSize() < self.payload_size_threshold` - Go: internal_extstore.go, `if proto.Size(p) < v.params.payloadSizeThreshold` The pages said "larger than 256 KiB", and the TypeScript page said payloads "at or below the threshold stay inline", which is backwards at the boundary. The Python SDK's own S3 driver README already documented this correctly. Also notes that the size compared is the serialized Payload including its metadata, not the raw application data. Separately, the encyclopedia told all readers to set the threshold to zero to externalize every payload. That is right for Python and TypeScript but wrong for Go, where zero selects the 256 KiB default and 1 is the value that offloads everything. The Go SDK page already had this right.
The whole FileSystemStorageDriver class was too long to read inline. Show just store and retrieve, which is what the surrounding prose walks through, and link the sample for the per-payload work in the private helpers: content-addressed keys, the atomic write, the hash check on read, and the guard against claims that resolve outside the storage root. Markers narrowed in samples-typescript to match.
lennessyy
enabled auto-merge (squash)
July 29, 2026 22:14
lennessyy
disabled auto-merge
July 29, 2026 22:14
Bump snipsync to 1.13.0, which indents spliced blocks to match their SNIPSTART marker instead of writing at column 0. A fenced block at column 0 inside a numbered list closes the list item, which split the Go and Python procedures into two lists and broke the MDX build outright on the TypeScript page, where the marker sits inside a Tabs element. That is the whole change to the Go and Python pages: same content, now indented under their markers. Two Python markers were at six spaces while their SNIPEND and list content were at three, so normalize them. The TypeScript snippets were materialized by pinning the snipsync origins at temporalio/features#855 and temporalio/samples-typescript#503, then restoring the config. A run against main is a no-op, so the daily snipsync job will re-sync these byte for byte once both land. Until they do, the source files are not on main, so the generated code block titles and the links to the samples repo would 404. Strip them, along with the custom driver excerpt that came from the unmerged sample. The daily job restores the titles on its own after the sources land.
…xtstore/initial-ts-docs
lennessyy
enabled auto-merge (squash)
July 30, 2026 00:09
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
3 participants
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.
What does this PR do?
Adds the initial docs for External Storage for TypeScript.
Notes to reviewers
┆Attachments: EDU-6785 Initial ts docs for extstore.