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:
parent
71d8ff3080
commit
99682077a1
2 changed files with 10 additions and 8 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
Loading…
Reference in a new issue