cultcache-ts docs: README and DocumentPayload list the routes that read a payload without the owner

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-10-11 22:03:20 +02:00
commit 99682077a1
2 changed files with 10 additions and 8 deletions

View file

@ -41,11 +41,12 @@ MessagePack decoder accepts it.
What the type guarantees is that a payload cannot be read or assigned directly: a decoder call, an
assignment to `Uint8Array` and `new Uint8Array(payload)` fail to compile. It does not stop what the
runtime value allows. Because the value is a `Uint8Array`, a check such as `payload instanceof
Uint8Array` narrows it back to bytes, and a cast does the same; a read made that way sees the raw
bytes, which for a codec or formatter document are not the document. Read through
`decodeDocumentPayload`, and when you need the bytes themselves (hashing, signing, a store write)
take them with `documentPayloadBytes`.
runtime value allows, because the value is a `Uint8Array`. These routes read it without the owner:
`instanceof Uint8Array` or `ArrayBuffer.isView` narrowing, `Object.values`, `Object.assign` onto a
`Uint8Array`, a JSON round trip, `Reflect.get`, and a cast. A read made that way sees the raw bytes,
which for a codec or formatter document are not the document. No lint or guard closes them. Read
through `decodeDocumentPayload`, and when you need the bytes themselves (hashing, signing, a store
write) take them with `documentPayloadBytes`, the sanctioned escape.
- `decodeDocumentPayload(definition, payload)` reads a payload through the definition's formatter,
codec or plain map and then its schema. The definition is required.

View file

@ -86,9 +86,10 @@ export function defineDocumentType<TSchema extends CultCacheSchema>(
* The key is a plain string, not a unique symbol, so two installed copies of this package stay compatible.
*
* What the type guarantees: a payload cannot be read or assigned directly (a decoder call, `const b: Uint8Array = p`,
* `new Uint8Array(p)` fail to compile). What it does not: the runtime value is a `Uint8Array`, so runtime narrowing
* (`p instanceof Uint8Array`) or a cast gets the raw bytes back, and a codec or formatter document read that way is not
* the document. The escape for bytes is `documentPayloadBytes`; the reader is `decodeDocumentPayload`.
* `new Uint8Array(p)` fail to compile). What it does not: the runtime value is a `Uint8Array`, so these routes read it
* without the owner: `instanceof Uint8Array` or `ArrayBuffer.isView` narrowing, `Object.values`, `Object.assign` onto a
* `Uint8Array`, a JSON round trip, `Reflect.get`, and a cast. A codec or formatter document read that way is raw bytes,
* not the document. The sanctioned escape for bytes is `documentPayloadBytes`; the reader is `decodeDocumentPayload`.
*/
export interface DocumentPayload {
readonly "cultcache.documentPayload": true;