spacetime-cr

A comprehensive, zero-dependency Crystal SDK, BSATN & SATS-JSON codec, real-time WebSocket & HTTP client, reactive client-side table cache, code generator, and WASM module bindings for SpacetimeDB.

Built according to the Sol-Vin Two-Tier Engine Architecture, separating low-level binary/algebraic primitives (Spacetime::BSATN, Spacetime::SATS, Spacetime::Protocol) from expressive compile-time AST macros (Spacetime.table, Spacetime.type, Spacetime::Serializable, Spacetime::SQL).

---

Features

• Complete Spacetime Algebraic Type System (Spacetime::SATS):
  • Full AlgebraicType AST (Ref, Sum, Product, Array, String, Bool, I8..I256, U8..U256, F32, F64) and Typespace resolution.
  • Native 256-bit integers (Spacetime::U256, Spacetime::I256) and first-class special SATS types: Spacetime::Identity, Spacetime::ConnectionId, Spacetime::Timestamp, Spacetime::TimeDuration, Spacetime::UUID, Spacetime::ScheduleAt, and Spacetime::EnergyQuanta.
  • Dynamic AlgebraicValue, ProductValue, and SumValue with schema-guided BSATN encoding/decoding, SATS-JSON serialization, SATN human-readable formatting (to_satn), and structural type checking (type_check?).
• Zero-Allocation Binary Codec (Spacetime::BSATN):
  • Little-endian binary BSATN::Encoder and BSATN::Decoder with strict Bool (0 or 1) and UTF-8 validation.
  • Packed BsatnRowList and RowSizeHint (FixedSize and RowOffsets) for high-throughput table row streaming.
• Full WebSocket Wire Protocol (v1.bsatn.spacetimedb & v1.json.spacetimedb):
  • All 8 ClientMessage variants (CallReducer, Subscribe, OneOffQuery, SubscribeSingle, SubscribeMulti, Unsubscribe, UnsubscribeMulti, CallProcedure).
  • All 11 ServerMessage variants (InitialSubscription, TransactionUpdate, TransactionUpdateLight, IdentityToken, OneOffQueryResponse, SubscribeApplied, UnsubscribeApplied, SubscriptionError, SubscribeMultiApplied, UnsubscribeMultiApplied, ProcedureResult).
  • Transparent WebSocket frame and CompressableQueryUpdate Gzip compression (0x00 None, 0x02 Gzip).
• Reactive Client & Local Table Cache (Spacetime::Client & Spacetime::TableCache(T)):
  • Automatic primary-key deduplication and row-level reconciliation: when a transaction deletes an old row and inserts a new row with the same @[Spacetime::PrimaryKey], TableCache(T) automatically emits on_update(old_row, new_row) alongside on_insert(row) and on_delete(row).
  • Pluggable Spacetime::Transport (WebSocketTransport for live connections and MockTransport for deterministic unit testing).
• Complete HTTP REST API Client (Spacetime::HTTPClient):
  • Covers /v1/identity (create_identity, create_websocket_token, public_key, list_databases, verify_identity) and /v1/database (publish_database, get_database, delete_database, get_database_identity, get_database_names, add_database_name, schema, sql, call_reducer, logs).
• Compile-Time Two-Tier DSL & Schema Codegen (spacetime-cr generate):
  • Spacetime.table and Spacetime.type macros (and Spacetime::Serializable with @[Spacetime::PrimaryKey], @[Spacetime::Unique], @[Spacetime::AutoInc], @[Spacetime::Index]) generate BSATN codecs, SATS-JSON codecs, and RawTableDefV9 schemas at compile time.
  • Spacetime::Codegen::CrystalGenerator and spacetime-cr generate inspect a V9 schema JSON file or live database and generate typed Crystal structs, sum enums, and reducer methods.
• WASM Guest Module ABI & Transactional Datastore (Spacetime::Wasm):
  • spacetime_10.0 WASM host import bindings (LibSpacetimeWasm) plus an in-memory transactional Spacetime::Wasm::Datastore with atomic rollback for testing server module logic natively in crystal spec.

---

Installation

Add spacetime to your shard.yml:

dependencies:
  spacetime:
    github: sol-vin/spacetime-cr
    branch: main

Then run:

shards install

---

Quick Start

1. Define Tables & Types with the Declarative DSL

require "spacetime"

Spacetime.type Vector3 do
  field x : Float32
  field y : Float32
  field z : Float32
end

Spacetime.table Player, name: "players", public: true do
  primary_key identity : Spacetime::Identity
  unique username : String
  field position : Vector3
  field health : UInt32 = 100_u32
  field online : Bool = true
end

2. Connect, Subscribe & React to Live Table Updates

client = Spacetime.connect("http://localhost:3000", "mmo_world") do |opts|
  opts.use_bsatn
  opts.compression(Spacetime::Protocol::Compression::None)
end

players = client.register_table(Player)

players.on_insert do |player|
  puts "[SPAWN] #{player.username} at (#{player.position.x}, #{player.position.y}, #{player.position.z})"
end

players.on_update do |old_player, new_player|
  puts "[MOVE] #{new_player.username}: #{old_player.position} -> #{new_player.position}"
end

players.on_delete do |player|
  puts "[LEAVE] #{player.username}"
end

# Subscribe using the fluent SQL builder
query = Spacetime::SQL.select_from("players").where_eq("online", true)
client.subscribe_single(query)

# Invoke a server-side reducer with BSATN arguments
client.call_reducer("move_player") do |enc|
  enc.write_value(Vector3.new(x: 42.0_f32, y: 0.0_f32, z: 15.0_f32))
end

3. Query via HTTP REST API (/v1/database/:name/sql)

http = Spacetime.http("http://localhost:3000")
creds = http.create_identity

results = http.sql("mmo_world", Spacetime::SQL.select_from("players").where_eq("online", true))
online_players = results.first.decode_rows(Player)

4. Generate Crystal Bindings from a Module Schema (spacetime-cr)

# Generate bindings from a live SpacetimeDB instance:
bin/spacetime-cr generate --host http://localhost:3000 --database mmo_world --module MmoBindings -o src/mmo_bindings.cr

# Or from a local V9 schema JSON file:
bin/spacetime-cr generate --schema schema.json --module MmoBindings -o src/mmo_bindings.cr

# Run SDK & codec self-diagnostics:
bin/spacetime-cr doctor

---

License

MIT License — Copyright (c) 2026 Ian Rash (@sol-vin).