@heojeongbo/calque-runtime

Types and codecs for code generated by calque.

npm install @heojeongbo/calque-runtime

This package deliberately does not import a database. It holds the parts of the contract that are true whatever the store is, so that a store adapter — like @heojeongbo/calque-dexie — is the only thing that knows about IndexedDB, and something else can know about something else.

If you are consuming generated code, install the adapter instead; it re-exports everything here, so generated files import one specifier.

API

Keys

type Key = string | number

The subset of IndexedDB's valid keys that calque uses. Not bigint, not a byte array, not a composite.

uuid

uuid.u8_str(v?: Uint8Array): string | undefined
uuid.str_u8(v?: string): Uint8Array | undefined

A uuid is sixteen raw bytes on the wire and canonical hyphenated text in a store — IndexedDB cannot index a byte array, and SQL drivers overwhelmingly write uuids as text, so both of calque's backends converge on the same representation.

u8_str returns undefined for anything that is not sixteen bytes. str_u8 strips non-hex characters, so the hyphenated and braced forms both work, and returns undefined unless exactly thirty-two hex digits remain.

urn:uuid: is mangled rather than refused. The prefix contributes a d, which survives the strip, so thirty-three characters remain and the wrong thirty-two are taken — every byte shifted by a nibble. The result is a plausible uuid rather than undefined. It is reproduced deliberately, because it is what the generator calque replaces does, and pinned by a test.

Service descriptors

type InputOf<Desc, Rpc>
type OutputOf<Desc, Rpc>
type RefOf<Desc, T = ...>
type QueryDescOf<Desc extends DescService>
type QueryDesc

QueryDescOf is the shape generated client.g.ts files export as queries: for each service, how to pick a message's primary reference, how to enumerate every reference it could be found by, and for each method how to extract the entity from that method's response.

A cache uses it to answer "what does this response contain, and what is it called" without knowing anything about the service in particular.

unsafe

unsafe.rm(obj: Record<string, unknown>, key: string): void
unsafe.set<T extends object, V>(obj: T | undefined, key: keyof T, value: V): void

Escape hatches the generated dehydration path needs — stripping $typeName and $unknown off a message before it is stored. They are named unsafe so that a reader can see where the type system stopped helping.

Peer dependencies

@bufbuild/protobuf ^2.10.0. Node 20 or later.

License

MIT