Value Representations

effect-spacetimedb works with three related value shapes:

• Authored Type values are what handlers and typed clients use.
• Schema encoded values are the wire side of Effect schema codecs, especially for typed HTTP request and response bodies.
• Host JS values are the shapes accepted by SpaceTimeDB’s JavaScript host for reducer arguments, table rows, lookup keys, and handler returns.

The host representation is close to authored values but not identical to schema encoded values. The library normalizes host values before schema decoding so handlers can work with authored Type values.

See Value Types for the canonical helper catalog. This page focuses on transport and encoding semantics.

Compatibility Rules

• Absent optional struct fields and absent Stdb.option fields are omitted from host structs.
• Result host input accepts { ok } and { err } envelopes, then normalizes them to schema tagged result shapes.
• Sum host input uses authored tagged values: { tag } for unit variants and { tag, value } for payload variants.
• Primitive, literal, custom, and no-descriptor leaves delegate to their schema encoder.

HTTP JSON has its own representation profile. It rewrites exact option envelopes, canonicalizes declared field names for SATS JSON, and normalizes responses back to declared field names where needed.

Numeric And Binary Profiles

• u8/u16/u32 and i8/i16/i32 are authored as number and checked at their constructor-owned integer bounds.
• u64/u128/u256 and i64/i128/i256 are authored as bigint, checked at their fixed-width bounds, and remain bigint in DB and WebSocket shapes.
• Stdb.bigint() is authored as bigint but lowers to a SATS string so large arbitrary integers can move through JSON safely.
• Stdb.f32() and Stdb.f64() use number. DB and generated WebSocket shapes preserve native NaN/Infinity; HTTP JSON rejects non-finite values because JSON has no representation for them.
• Stdb.bytes() is a Uint8Array byte array.

Native Host Values

Stdb.timestamp(), Stdb.timeDuration(), Stdb.uuid(), Stdb.identity(), and Stdb.connectionId() use the native SpacetimeDB classes in authored server and generated-client values. Their HTTP JSON shape is the schema-encoded representation produced by Stdb.httpCodec(...).

Transport Codecs

Use Stdb.dbCodec(T) for host/DB values, Stdb.httpCodec(T) for HTTP JSON, and Stdb.wsCodec(T) for generated WebSocket client values. The WebSocket codec accepts the generated client’s PascalCase enum tags for sums and string literals, while DB and HTTP profiles keep authored tags where SATS permits them.