getContent() should return parsed objects, not raw Uint8Array
Opened by swampadmin · 10/20/2025
Problem Statement
Extension model methods use context.writeResource() to persist data as structured objects, but context.dataRepository.getContent() returns a raw Uint8Array of the file bytes. This creates an asymmetric API where writing is ergonomic but reading requires manual deserialization:
// Writing — accepts an object, handles serialization internally
await context.writeResource("pairing", "my-pairing", { accessoryId: "...", ... });
// Reading — returns Uint8Array, requires manual parsing
const raw = await context.dataRepository.getContent(context.modelType, context.modelId, "latest");
const data = JSON.parse(new TextDecoder().decode(raw));Every extension that reads its own data must repeat this JSON.parse(new TextDecoder().decode(...)) pattern, which is error-prone and undocumented.
Proposed Solution
getContent() (or a higher-level alternative like the proposed context.readResource() from #708) should return the parsed object, matching the type that was passed to writeResource(). This would make the read path symmetric with the write path.
Scope of changes:
- Data repository layer: add JSON deserialization to the return path, or introduce a typed wrapper
- MethodContext: if
readResource()is added per #708, it should return parsed objects by default - Extension model documentation: update examples to reflect the new API
Alternatives Considered
- Document the manual decode pattern — reduces confusion but doesn't fix the ergonomic gap
- Add a utility function in the extension SDK — helps but still requires extension authors to know about it
Closed
No activity in this phase yet.
Sign in to post a ripple.