Repository navigation
Conversation
🦋 Changeset detectedLatest commit: d702eda The changes in this PR will be included in the next version bump. This PR includes changesets to release 7 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
This was referenced Nov 18, 2026
xyos
force-pushed
the
docs/readme-data-blocks
branch
2 times, most recently
from
November 19, 2026 06:11
3d37e66 to
d0bfa41
Compare
…ter the options The conditional-writes section pointed to `transaction()` on `Database` (`@aws-blocks/bb-data`) or `DistributedDatabase` (`@aws-blocks/bb-distributed-data`); neither package exists, so it now names `transaction()` on `Database`. The same section now says that KVStore has no atomic increment and gives two ways to keep a concurrent counter: a `get()`/conditional `put()` loop that creates the item with `ifNotExists: true` and retries on `KVStoreErrors.ConditionalCheckFailed`, or one item per event aggregated with `query()`. The errors table moves to directly after the options, with the causes of `ValidationFailedException` and `InvalidQueryException` as lists, and the options table has a `Default` column. `scan` has its own section, and "Best practices" and "Scaling and cost (AWS)" keep only the items that are not stated earlier in the README. The README keeps 17 `typescript` blocks and 4 compile-error lines; `scripts/generate-readme-test.mjs` requires at least 15 and 4.
…db in one section The errors table listed short names such as `QueryFailed`; it now lists each `DatabaseErrors` constant with the `error.name` a caller sees (`QueryFailedException`), and the four errors that are not for `catch` are a second table. `npm run db` was documented in two sections; it is now one `## Command line` section with a column for the kind of block each command applies to, and it says that a command with `--block` refuses `--name`. The options of `transaction()` and of the block and cluster are tables with a `Default` column. "Migrations" has one subsection per target (`dsql` cluster, `aurora` cluster, existing database), and the `dsql-lint` check is scoped to files for a `dsql` cluster. The steps to move or rename a block are their own section, and `## Local mode` is renamed `## Local development` and is the last section.
… one errors table The errors table said `FileBucketErrors.FileNotFound` was "surfaced by presigned-URL 404s etc." and `FileTooLarge` meant "file exceeds size limits"; no FileBucket method throws either, and an upload over `maxUploadBytes` throws `ValidationFailed`. `ValidationFailed` is now the first row of the table, as a name with no `FileBucketErrors` constant that is matched with `isBlocksError(e, 'ValidationFailed')`. Two bullets gave opposite advice on handles and raw presigned URLs; the method table now says when to return each. The README gains a quick start, the `FileBucket.fromKmsKey(keyArn)` method row, tables for `FileContent`, `FileInfo`, `FileDownloadClient` and `FileUploadClient`, a `Default` column in the options table and a `## Scaling and cost (AWS)` section that says an upload is one `PutObject` request. The "Best Practices" list and the Batch Delete example are removed; the reason to encode an OIDC `userId` moves to "Access control and per-user isolation".
…lue is set The options table said `value` was not required; it is required unless `secret: true`. The README said a missing parameter throws `ParameterNotFound` in both the AWS and mock runtimes; a missing parameter throws on AWS, and an empty `secret: true` value throws on AWS and locally. `AppSetting.fromExisting` was not documented; it now has a method row and a section that says the app's role gets read access only and that `put()` on such a setting is denied on AWS although it succeeds locally. A new section on `secret: true` says the first deploy stores a random value, how to set the real value with `put()` or in the console, and that `get()` parses the stored text as JSON. Errors are one table, and the options table has a `Default` column and absorbs the "Validation Rules" list.
…scope of put() `SecretErrors.NotSupported` was mentioned only for browser code; the errors table now also lists the deployed case of a `Secret` with no registered secret ARN. The rotation note now says that `put()` clears the cache of the calling instance only, and that other running instances read the new value once their cache entry expires (`cacheTtlSeconds`). Errors are one `## Errors` table, and the options table has a `Default` column instead of `Required`. "Managing secret values" opens with the scenario table, and "Scaling & cost (AWS)" is split into `## What it provisions (AWS)` and `## Scaling and cost (AWS)`. A quick start replaces the "Manually-configured credential" example.
xyos
force-pushed
the
docs/readme-data-blocks
branch
from
November 19, 2026 14:24
d0bfa41 to
1933843
Compare
This branch has not been deployed
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.
Problem
The READMEs of the five data blocks (
KVStore,Database,FileBucket,AppSetting,Secret) had statements that the source contradicts, and left out parts of the public API:bb-kv-storesent a reader who needs a transaction to@aws-blocks/bb-dataand@aws-blocks/bb-distributed-data, which do not exist, and did not say that there is no atomic increment.bb-file-bucketlistedFileBucketErrors.FileTooLargeas "File exceeds size limits", but no method throws it: an upload overmaxUploadBytesthrowsValidationFailed.bb-databaselisted errors by short name (QueryFailed), whileerror.nameisQueryFailedException, and documentednpm run dbin two sections.bb-app-settingdid not documentAppSetting.fromExisting, or how asecret: truesetting gets its real value.Facts were also hard to find: 56 prose lines across the five files were longer than 400 characters (27 in
bb-database), and errors were spread over prose, tables and comments intry/catchexamples.Issue #, if available:
Changes
packages/bb-kv-store/README.mdtransaction()onDatabase", without the two package names (packages/bb-database/src/runtime/index.ts:144).get()/conditionalput()loop, or one item per event). Derived fromsrc/types.ts:161-200,src/errors.ts:33,src/item.ts:704-712,763-768andsrc/index.mock.ts:255-261.## Errorsmoves to after### Options, with the causes ofValidationFailedExceptionandInvalidQueryExceptionas lists. The options table has aDefaultcolumn.scanhas its own heading.try/catchexample (its imports move to "Rewrite a store of strings as objects"), and "Best practices" and "Scaling and cost (AWS)" bullets that repeated the body.typescriptblocks (18 before) and 4 compile-error lines;scripts/generate-readme-test.mjs:40-41requires at least 15 and 4.packages/bb-database/README.mdConstant,error.name,Thrown when,Retried automatically(src/errors.ts:18-30), and moves to after the options. The four errors not meant forcatchare a second table.## Command linereplaces "The command line" and "Types and status from the command line": one row per command, with a column for the kind of block. "Every command" now says that a command with--blockrefuses--name(src/cli.ts:197-200).transaction()options (src/types.ts:238-265,src/constants.ts:52) andDefaultcolumns for the options (src/types.ts:109-179).## Moving or renaming a block,## Scaling and cost (AWS), one "Migrations" subsection per target. "What is rejected" scopes thedsql-lintcheck to adsqlcluster (src/migrations/plan.ts:111-122).## Local modeis renamed## Local development.try/catchexample (its two import lines stay), a second Kysely snippet. The file grows by 95 lines because long paragraphs became lists and tables.packages/bb-file-bucket/README.mdFileNotFound(src/errors.ts:32is its only definition;src/index.aws.ts:135mapsNoSuchKeytonull;src/file-server.ts:136-139answers 404NoSuchKey),FileTooLarge(src/upload-constraints.ts:320-321throwsValidationFailed), andValidationFailedas a name with no constant (src/errors.ts:31-36,src/validation-error.ts:10).src/middleware.ts:29-56).## Quick start; theFileBucket.fromKmsKey(keyArn)row (src/index.aws.ts:353); tables forFileContent,FileInfoand the two handle clients (src/types.ts:400-418,:483-498); aDefaultcolumn;## Scaling and cost (AWS)(onePutObjectrequest per upload,src/index.aws.ts:106,:322).DESIGN.md).packages/bb-app-setting/README.mdvalueis required unlesssecret: true(src/validation.ts:97-103);ParameterNotFoundper runtime (src/index.aws.ts:129,:137,:149;src/index.mock.ts:150-159); asecret: truevalue is not size-checked (src/validation.ts:121-122).fromExistingmethod row and section (src/index.cdk.ts:63-82,:121-164), and "Secret values (secret: true)" (src/index.cdk.ts:234-235,src/index.aws.ts:140-146,:173).packages/bb-secret/README.mdNotSupportedalso covers a deployedSecretwith no secret ARN (src/index.aws.ts:233-242);put()clears the calling instance's cache only (src/index.aws.ts:153,:402).Defaultcolumn; a quick start replaces the "Manually-configured credential" example; "Scaling & cost (AWS)" is split in two sections.packages/bb-kv-store/README.mdpackages/bb-database/README.mdpackages/bb-file-bucket/README.mdpackages/bb-app-setting/README.mdpackages/bb-secret/README.mdLook hardest at:
bb-kv-store"Conditional writes" section, including "give such a counter no expiry".bb-file-bucketrows forFileNotFound,FileTooLargeandValidationFailed, and theerror.namecolumn inbb-database.bb-app-settingtext onfromExistingand on how asecret: truevalue is set.bb-database## Command linesection, which merges two sections.Not changed on purpose:
bb-kv-storeREADME: JSDoc on exported symbols and a test link to that heading.@aws-blocks/bb-*) andnpm installlines.bb-kv-storeexamples key per-user data byuserSub;bb-databaseexamples byuserId, becauseasUser()sets thesubclaim fromuser.userId(packages/bb-database/src/runtime/scoped.ts:171-177).Open questions:
asUser()use,userSuboruserId?@aws-blocks/blocks, and should thebb-databaseREADME lose itsnpm installblock and be titled# Database?FileBucketErrors.FileNotFoundandFileTooLargehave no throw site: remove the constants or keep them documented as unused? ShouldValidationFailedget aFileBucketErrorsconstant?PutObjectrequest. The README gives no size figure because none is in the source, whilePRODUCTION.mdsays "5 TB per object". Should either state the single-request limit?put()on anAppSetting.fromExistingsetting is on the type and denied by IAM on AWS; the error name SSM returns is not verified. Shouldput()be removed from that type or throw a named error?NoSuchKeyfor a missing file is S3 behaviour, confirmed here only for the local file server.Related pull requests: this carries what still applies from the closed #794 for the key/value block, now
KVStore: there is no atomic increment, with the two ways to keep a concurrent counter. Open pull requests that touch the same files; whichever merges second rebases:packages/bb-kv-store/README.md: feat(bb-kv-store): add KVStore.increment() for atomic counters #1618, feat(bb-kv-store): add appendToList for atomic appends to a list field #1619. feat(bb-kv-store): add KVStore.increment() for atomic counters #1618 addsKVStore.increment(); if it merges first, the "no atomic increment" paragraph must change.packages/bb-database/README.md: feat(bb-database): production deploy guard for cluster bindings #1109packages/bb-file-bucket/README.md: feat(bb-file-bucket): run a handler when an object is created (onObjectCreated) #1299, fix(file-bucket): avoid reusing deleted local version IDs #1302, fix: keep__proto__response keys in Realtime and FileBucket client middleware #1313packages/bb-app-setting/README.md: fix(bb-app-setting): browser stub throws actionable server-only error #310, docs(bb-app-setting): correct mock storage path #576, feat(core, blocks, hosting, create-blocks-app, admin-ui, bb-database)!: rename the hidden .blocks folder to .cdk-blocks and consolidate local data under it #1607packages/bb-secret/README.md: fix(bb-secret): preserve schema-backed strings in the local mock #844Part of a set of README revisions: #1635 (core), #1636 (hosting and pipeline), #1637 (bb-agent and bb-knowledge-base), #1638 (bb-auth and auth-common), #1640 (compute, jobs, realtime, email and observability), #1641 (the guide, the scaffolder and its templates), #1642 (the native SDKs), #1643 (contributor docs). Each merges on its own.
Validation
Run on this branch alone at
d0bfa419d, onmain8940cfd2f, with Node 22. All pass:npm run buildpackages/blocks(readme-links,docs-pointers,doc-snippets,imports-reference)packages/blockssandbox-dir-coverage(no tracked file names the old directory.blocks-sandbox)packages/corereadme-policies(the IAM policy JSON)packages/bb-authreadme-recipes,first-admin,multi-block-snippets,users-cli,gate-diagnosticspackages/auth-commonui.react-typespackages/bb-kv-storereadme.generated(every README snippet compiled) andlegacy/runtimepackages/create-blocks-appnpm testnpm run sync-docs:checknpm run check:importschangeset-guard.ts validate-structurechangeset-guard.ts verify-coveragechangeset-guard.ts verify-umbrellachangeset-guard.ts block-major#anchorin the changed files, and every link into them from another Markdown file, resolves (checked with a script)Run once on all the README branches of this set combined, as they were on an earlier
maincommit (e1e484465), and not run again after the rebases:packages/coreunit suite,packages/blocksunit suite,packages/bb-kv-storeunit suite,packages/bb-authunit suite,packages/auth-commonunit suite,npm run lint,npm run lint:depsandnpm run check:api. All passed.Not run locally: the full
npm testacross all workspaces,npm run test:e2e:localand the sandbox e2e suites. CI runs them.No test was added: the tests listed above already read these READMEs, and the remaining statements are checked against the source by review.
Checklist
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.