@spacetimedb/zod-bridge-runtime

Runtime helpers for validating SpacetimeDB types with Zod.

This package provides Zod schemas for SpacetimeDB built-in types (Identity, Timestamp, etc.) and numeric types with proper range validation. It's used by @spacetimedb/zod-bridge but can also be used standalone.

Installation

npm install @spacetimedb/zod-bridge-runtime zod spacetimedb

Usage

SpacetimeDB Types

import { zodSpacetime } from '@spacetimedb/zod-bridge-runtime';
import { z } from 'zod';

// Identity: accepts Identity instance, hex string, or BigInt
const IdentitySchema = zodSpacetime.identity();

// Valid inputs:
IdentitySchema.parse(myIdentity); // Identity instance
IdentitySchema.parse("0x1234..."); // 64-char hex string
IdentitySchema.parse(123456789n); // BigInt

// Timestamp: accepts Timestamp instance, Date, ISO string, or Unix ms
const TimestampSchema = zodSpacetime.timestamp();

// Valid inputs:
TimestampSchema.parse(myTimestamp); // Timestamp instance
TimestampSchema.parse(new Date()); // Date object
TimestampSchema.parse("2024-01-15T10:30:00Z"); // ISO string
TimestampSchema.parse(1705318200000); // Unix milliseconds

// TimeDuration: accepts TimeDuration instance or number (milliseconds)
const DurationSchema = zodSpacetime.timeDuration();

// Valid inputs:
DurationSchema.parse(myDuration); // TimeDuration instance
DurationSchema.parse(5000); // 5 seconds in milliseconds

// ConnectionId: accepts ConnectionId instance or string
const ConnectionIdSchema = zodSpacetime.connectionId();

// Valid inputs:
ConnectionIdSchema.parse(myConnectionId); // ConnectionId instance
ConnectionIdSchema.parse("conn-123"); // String

// ScheduleAt: accepts ScheduleAt instance or BigInt (microseconds)
const ScheduleAtSchema = zodSpacetime.scheduleAt();

// Valid inputs:
ScheduleAtSchema.parse(myScheduleAt); // ScheduleAt instance
ScheduleAtSchema.parse(16667n); // 16.667 microseconds (60 Hz tick)

Numeric Types

All numeric types enforce proper range validation:

import { zodNumeric } from '@spacetimedb/zod-bridge-runtime';

// Unsigned integers
const u8 = zodNumeric.u8(); // 0-255
const u16 = zodNumeric.u16(); // 0-65535
const u32 = zodNumeric.u32(); // 0-4294967295
const u64 = zodNumeric.u64(); // 0n-18446744073709551615n (BigInt)
const u128 = zodNumeric.u128(); // 0n+ (BigInt, no upper bound)
const u256 = zodNumeric.u256(); // 0n+ (BigInt, no upper bound)

// Signed integers
const i8 = zodNumeric.i8(); // -128-127
const i16 = zodNumeric.i16(); // -32768-32767
const i32 = zodNumeric.i32(); // -2147483648-2147483647
const i64 = zodNumeric.i64(); // -9223372036854775808n-9223372036854775807n (BigInt)
const i128 = zodNumeric.i128(); // Any BigInt
const i256 = zodNumeric.i256(); // Any BigInt

// Floating point
const f32 = zodNumeric.f32(); // Any number
const f64 = zodNumeric.f64(); // Any number

Range Validation Examples

import { zodNumeric } from '@spacetimedb/zod-bridge-runtime';
import { z } from 'zod';

// u8 validation
const u8Schema = zodNumeric.u8();
u8Schema.parse(0); // ✓
u8Schema.parse(255); // ✓
u8Schema.parse(256); // ✗ Error: Number must be less than or equal to 255

// u32 validation
const u32Schema = zodNumeric.u32();
u32Schema.parse(0); // ✓
u32Schema.parse(4294967295); // ✓
u32Schema.parse(4294967296); // ✗ Error: Number must be less than or equal to 4294967295
u32Schema.parse(-1); // ✗ Error: Number must be greater than or equal to 0

// i32 validation
const i32Schema = zodNumeric.i32();
i32Schema.parse(-2147483648); // ✓
i32Schema.parse(2147483647); // ✓
i32Schema.parse(2147483648); // ✗ Error: Number must be less than or equal to 2147483647

API Reference

zodSpacetime

zodSpacetime.identity()

Returns a Zod schema that accepts:

• Identity instance from SpacetimeDB
• 64-character hex string (with or without 0x prefix)
• BigInt

All inputs are transformed to Identity instances.

Example:

const schema = zodSpacetime.identity();
const id = schema.parse("0x" + "0".repeat(64)); // Identity instance

zodSpacetime.timestamp()

Returns a Zod schema that accepts:

• Timestamp instance from SpacetimeDB
• Date object
• ISO 8601 datetime string
• Unix timestamp in milliseconds (number)

All inputs are transformed to Timestamp instances.

Example:

const schema = zodSpacetime.timestamp();
const ts = schema.parse(new Date()); // Timestamp instance

zodSpacetime.timeDuration()

Returns a Zod schema that accepts:

• TimeDuration instance from SpacetimeDB
• Number (milliseconds)

All inputs are transformed to TimeDuration instances.

Example:

const schema = zodSpacetime.timeDuration();
const duration = schema.parse(5000); // TimeDuration instance (5 seconds)

zodSpacetime.connectionId()

Returns a Zod schema that accepts:

• ConnectionId instance from SpacetimeDB
• String representation

All inputs are transformed to ConnectionId instances.

Example:

const schema = zodSpacetime.connectionId();
const connId = schema.parse("conn-123"); // ConnectionId instance

zodSpacetime.scheduleAt()

Returns a Zod schema that accepts:

• ScheduleAt instance from SpacetimeDB
• BigInt (microseconds)

All inputs are transformed to ScheduleAt instances.

Example:

const schema = zodSpacetime.scheduleAt();
const schedule = schema.parse(16667n); // ScheduleAt instance

zodNumeric

All numeric schemas return standard Zod number or BigInt schemas with range constraints:

| Method | Return Type | Range | |--------|-------------|-------| | u8() | z.ZodNumber | 0-255 | | u16() | z.ZodNumber | 0-65535 | | u32() | z.ZodNumber | 0-4294967295 | | u64() | z.ZodBigInt | 0n-18446744073709551615n | | u128() | z.ZodBigInt | 0n+ | | u256() | z.ZodBigInt | 0n+ | | i8() | z.ZodNumber | -128-127 | | i16() | z.ZodNumber | -32768-32767 | | i32() | z.ZodNumber | -2147483648-2147483647 | | i64() | z.ZodBigInt | -9223372036854775808n-9223372036854775807n | | i128() | z.ZodBigInt | Any | | i256() | z.ZodBigInt | Any | | f32() | z.ZodNumber | Any | | f64() | z.ZodNumber | Any |

Error Handling

All schemas provide clear error messages on validation failure:

import { zodSpacetime, zodNumeric } from '@spacetimedb/zod-bridge-runtime';
import { z } from 'zod';

try {
  zodNumeric.u8().parse(256);
} catch (error) {
  if (error instanceof z.ZodError) {
    console.error(error.errors);
    // [{
    //   code: "too_big",
    //   maximum: 255,
    //   path: [],
    //   message: "Number must be less than or equal to 255"
    // }]
  }
}

try {
  zodSpacetime.identity().parse("not-a-hex-string");
} catch (error) {
  if (error instanceof z.ZodError) {
    console.error(error.errors);
    // [{
    //   code: "custom",
    //   path: [],
    //   message: "Invalid Identity: ..."
    // }]
  }
}

TypeScript Types

The package exports TypeScript type declarations for all SpacetimeDB classes:

import type {
  Identity,
  Timestamp,
  TimeDuration,
  ConnectionId,
  ScheduleAt,
} from '@spacetimedb/zod-bridge-runtime';

These match the actual classes from spacetimedb package.

Standalone Usage

While this package is primarily used by @spacetimedb/zod-bridge, you can use it standalone:

import { zodSpacetime, zodNumeric } from '@spacetimedb/zod-bridge-runtime';
import { z } from 'zod';

const PlayerSchema = z.object({
  id: zodSpacetime.identity(),
  name: z.string().min(1).max(20),
  score: zodNumeric.u32(),
  lastSeen: zodSpacetime.timestamp(),
});

type Player = z.infer<typeof PlayerSchema>;

function validatePlayer(data: unknown): Player {
  return PlayerSchema.parse(data);
}

License

MIT

Related

• @spacetimedb/zod-bridge - Auto-generate Zod schemas from SpacetimeDB modules
• spacetimedb - SpacetimeDB TypeScript SDK
• zod - TypeScript-first schema validation