module

Spacetime::Docs::B_GUIDES::ClientCacheAndSubscriptions

Client Cache & Real-Time Subscriptions

Spacetime::Client automatically applies incoming InitialSubscription, TransactionUpdate, and TransactionUpdateLight server messages to registered Spacetime::TableCache(T) instances, firing row-level callbacks in real time.

Executive Summary & Key Topics

Topic Method / Anchor Description
Primary Keys vs. Full-Row Identity .topic_01_primary_key_coalescing How TableCache(T) coalesces delete+insert pairs into on_update callbacks.
Deterministic Unit Testing with LoopbackTransport .topic_02_loopback_testing Test client subscriptions, table caches, and reducer calls without a live server.

Related Guides & Source References

  • Spacetime::Client
  • Spacetime::TableCache
  • Spacetime::LoopbackTransport

Class methods

topic_01_primary_key_coalescing

Primary Keys vs Full-Row Identity: How TableCache(T) coalesces delete+insert pairs into on_update callbacks.

When a struct marks a property with @[Spacetime::Field(primary_key: true)], Spacetime::TableCache(T) indexes rows by their BSATN-encoded primary key. If a single transaction deletes and inserts a row with the same primary key, the cache automatically coalesces the pair into an on_update(old_row, new_row) event instead of separate delete and insert callbacks.

Source
topic_02_loopback_testing

Deterministic Unit Testing with LoopbackTransport: Test client subscriptions, table caches, and reducer calls without a live server.

Working Examples

require "spacetime"

transport = Spacetime::LoopbackTransport.new client = Spacetime::Client.new("ws://localhost:3000", "demo_db", transport: transport) client.connect

req_id = client.call_reducer("ping", "hello") puts "Sent #{transport.sent_messages.size} message(s), request_id=#{req_id}"

Source