Skip to content

docs(kv-store, database, file-bucket, app-setting, secret): correct errors tables; add counters, fromExisting - #1639

Draft
xyos wants to merge 6 commits into
aws:mainfrom
xyos:docs/readme-data-blocks
Draft

xyos wants to merge 6 commits into
aws:mainfrom
xyos:docs/readme-data-blocks

Conversation

@xyos

@xyos xyos commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

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-store sent a reader who needs a transaction to @aws-blocks/bb-data and @aws-blocks/bb-distributed-data, which do not exist, and did not say that there is no atomic increment.
  • bb-file-bucket listed FileBucketErrors.FileTooLarge as "File exceeds size limits", but no method throws it: an upload over maxUploadBytes throws ValidationFailed.
  • bb-database listed errors by short name (QueryFailed), while error.name is QueryFailedException, and documented npm run db in two sections.
  • bb-app-setting did not document AppSetting.fromExisting, or how a secret: true setting 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 in try/catch examples.

Issue #, if available:

Changes

packages/bb-kv-store/README.md

  • Corrected: "use transaction() on Database", without the two package names (packages/bb-database/src/runtime/index.ts:144).
  • New in "Conditional writes": there is no atomic increment, and two ways to keep a concurrent counter (a get()/conditional put() loop, or one item per event). Derived from src/types.ts:161-200, src/errors.ts:33, src/item.ts:704-712,763-768 and src/index.mock.ts:255-261.
  • ## Errors moves to after ### Options, with the causes of ValidationFailedException and InvalidQueryException as lists. The options table has a Default column. scan has its own heading.
  • Removed: the try/catch example (its imports move to "Rewrite a store of strings as objects"), and "Best practices" and "Scaling and cost (AWS)" bullets that repeated the body.
  • The README keeps 17 typescript blocks (18 before) and 4 compile-error lines; scripts/generate-readme-test.mjs:40-41 requires at least 15 and 4.

packages/bb-database/README.md

  • Corrected: the errors table has the columns Constant, error.name, Thrown when, Retried automatically (src/errors.ts:18-30), and moves to after the options. The four errors not meant for catch are a second table.
  • ## Command line replaces "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 --block refuses --name (src/cli.ts:197-200).
  • New tables: the transaction() options (src/types.ts:238-265, src/constants.ts:52) and Default columns for the options (src/types.ts:109-179).
  • New sections from existing text: ## Moving or renaming a block, ## Scaling and cost (AWS), one "Migrations" subsection per target. "What is rejected" scopes the dsql-lint check to a dsql cluster (src/migrations/plan.ts:111-122). ## Local mode is renamed ## Local development.
  • Removed: design rationale, the try/catch example (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.md

  • Corrected: FileNotFound (src/errors.ts:32 is its only definition; src/index.aws.ts:135 maps NoSuchKey to null; src/file-server.ts:136-139 answers 404 NoSuchKey), FileTooLarge (src/upload-constraints.ts:320-321 throws ValidationFailed), and ValidationFailed as a name with no constant (src/errors.ts:31-36, src/validation-error.ts:10).
  • Corrected: two bullets gave opposite advice on handles and raw URLs; the method table has one rule (src/middleware.ts:29-56).
  • Added: ## Quick start; the FileBucket.fromKmsKey(keyArn) row (src/index.aws.ts:353); tables for FileContent, FileInfo and the two handle clients (src/types.ts:400-418, :483-498); a Default column; ## Scaling and cost (AWS) (one PutObject request per upload, src/index.aws.ts:106, :322).
  • Removed: "Best Practices", the Batch Delete example, and the mock's on-disk layout (in DESIGN.md).

packages/bb-app-setting/README.md

  • Corrected: value is required unless secret: true (src/validation.ts:97-103); ParameterNotFound per runtime (src/index.aws.ts:129, :137, :149; src/index.mock.ts:150-159); a secret: true value is not size-checked (src/validation.ts:121-122).
  • Added: the fromExisting method 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).
  • Errors are one table; the options table absorbs the "Validation Rules" list.

packages/bb-secret/README.md

  • Corrected: NotSupported also covers a deployed Secret with no secret ARN (src/index.aws.ts:233-242); put() clears the calling instance's cache only (src/index.aws.ts:153, :402).
  • One errors table; a Default column; a quick start replaces the "Manually-configured credential" example; "Scaling & cost (AWS)" is split in two sections.
File Lines Words Prose lines over 400 characters
packages/bb-kv-store/README.md 596 → 589 5770 → 5426 5 → 3
packages/bb-database/README.md 540 → 635 7913 → 7601 27 → 10
packages/bb-file-bucket/README.md 442 → 422 4996 → 4346 13 → 5
packages/bb-app-setting/README.md 175 → 159 1159 → 1170 1 → 0
packages/bb-secret/README.md 309 → 289 3378 → 2636 10 → 0

Look hardest at:

  • The new counter sentences in the bb-kv-store "Conditional writes" section, including "give such a counter no expiry".
  • The errors tables: the bb-file-bucket rows for FileNotFound, FileTooLarge and ValidationFailed, and the error.name column in bb-database.
  • The new bb-app-setting text on fromExisting and on how a secret: true value is set.
  • The bb-database ## Command line section, which merges two sections.

Not changed on purpose:

  • "Upgrade from release 0.4.0 or earlier" stays in the bb-kv-store README: JSDoc on exported symbols and a test link to that heading.
  • Examples keep their import specifiers (@aws-blocks/bb-*) and npm install lines.
  • bb-kv-store examples key per-user data by userSub; bb-database examples by userId, because asUser() sets the sub claim from user.userId (packages/bb-database/src/runtime/scoped.ts:171-177).

Open questions:

  • Which field should storage examples and asUser() use, userSub or userId?
  • Should README examples import from @aws-blocks/blocks, and should the bb-database README lose its npm install block and be titled # Database?
  • FileBucketErrors.FileNotFound and FileTooLarge have no throw site: remove the constants or keep them documented as unused? Should ValidationFailed get a FileBucketErrors constant?
  • A FileBucket upload is one PutObject request. The README gives no size figure because none is in the source, while PRODUCTION.md says "5 TB per object". Should either state the single-request limit?
  • put() on an AppSetting.fromExisting setting is on the type and denied by IAM on AWS; the error name SSM returns is not verified. Should put() be removed from that type or throw a named error?
  • That a presigned download URL on AWS answers 404 NoSuchKey for 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:

Part 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, on main 8940cfd2f, with Node 22. All pass:

  • npm run build
  • the shipped-docs tests in packages/blocks (readme-links, docs-pointers, doc-snippets, imports-reference)
  • packages/blocks sandbox-dir-coverage (no tracked file names the old directory .blocks-sandbox)
  • packages/core readme-policies (the IAM policy JSON)
  • packages/bb-auth readme-recipes, first-admin, multi-block-snippets, users-cli, gate-diagnostics
  • packages/auth-common ui.react-types
  • packages/bb-kv-store readme.generated (every README snippet compiled) and legacy/runtime
  • packages/create-blocks-app npm test
  • npm run sync-docs:check
  • npm run check:imports
  • changeset-guard.ts validate-structure
  • changeset-guard.ts verify-coverage
  • changeset-guard.ts verify-umbrella
  • changeset-guard.ts block-major
  • every relative link and #anchor in 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 main commit (e1e484465), and not run again after the rebases: packages/core unit suite, packages/blocks unit suite, packages/bb-kv-store unit suite, packages/bb-auth unit suite, packages/auth-common unit suite, npm run lint, npm run lint:deps and npm run check:api. All passed.

Not run locally: the full npm test across all workspaces, npm run test:e2e:local and 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

  • PR description included
  • Tests are changed or added
  • Relevant documentation is changed or added (and PR referenced)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@changeset-bot

changeset-bot Bot commented Nov 18, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: d702eda

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages
Name Type
@aws-blocks/bb-kv-store Patch
@aws-blocks/bb-database Patch
@aws-blocks/bb-file-bucket Patch
@aws-blocks/bb-app-setting Patch
@aws-blocks/bb-secret Patch
@aws-blocks/blocks Patch
@aws-blocks/create-blocks-app Patch

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

xyos added 6 commits November 19, 2026 14:23
…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
xyos force-pushed the docs/readme-data-blocks branch from d0bfa41 to 1933843 Compare November 19, 2026 14:24

This branch has not been deployed

No deployments
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.

1 participant