@stdb-zod-gen/runtime

Runtime helpers for @stdb-zod-gen/cli — custom Zod types that coerce frontend primitives to SpacetimeDB SDK types.

Installation

pnpm add @stdb-zod-gen/runtime

Usage

This package is automatically imported by generated schemas. You can also use it manually:

import { z } from 'zod';
import { zodSpacetime } from '@stdb-zod-gen/runtime';

const UserSchema = z.object({
  identity: zodSpacetime.identity(),
  createdAt: zodSpacetime.timestamp(),
  sessionDuration: zodSpacetime.timeDuration(),
});

// Accepts frontend primitives
const user = UserSchema.parse({
  identity: '0x' + '0'.repeat(64),  // hex string → Identity
  createdAt: new Date(),             // Date → Timestamp
  sessionDuration: 5000,             // number (ms) → TimeDuration
});

API

zodSpacetime.identity()

Accepts: Identity, hex string, bigint Returns: Identity

const schema = zodSpacetime.identity();

schema.parse(new Identity(123n));           // ✅ Identity
schema.parse('0x' + '0'.repeat(64));        // ✅ hex string → Identity
schema.parse(123456789n);                   // ✅ bigint → Identity
schema.parse('invalid');                     // ❌ throws

zodSpacetime.timestamp()

Accepts: Timestamp, Date, ISO string, Unix ms Returns: Timestamp

const schema = zodSpacetime.timestamp();

schema.parse(new Timestamp(...));           // ✅ Timestamp
schema.parse(new Date());                   // ✅ Date → Timestamp
schema.parse('2025-10-18T12:00:00Z');       // ✅ ISO string → Timestamp
schema.parse(1729252800000);                // ✅ Unix ms → Timestamp
schema.parse('invalid');                     // ❌ throws

zodSpacetime.timeDuration()

Accepts: TimeDuration, number (milliseconds) Returns: TimeDuration

const schema = zodSpacetime.timeDuration();

schema.parse(new TimeDuration(...));        // ✅ TimeDuration
schema.parse(5000);                         // ✅ 5000ms → TimeDuration
schema.parse(-1);                            // ❌ throws (must be non-negative)

zodSpacetime.connectionId()

Accepts: ConnectionId, string Returns: ConnectionId

const schema = zodSpacetime.connectionId();

schema.parse(new ConnectionId(...));        // ✅ ConnectionId
schema.parse('12345');                      // ✅ string → ConnectionId

Error Messages

Clear, actionable error messages:

zodSpacetime.identity().parse('invalid');
// ZodError: Invalid Identity: Must be a 64-character hex string (with optional 0x prefix)

zodSpacetime.timestamp().parse('not-a-date');
// ZodError: Invalid Timestamp: Invalid time value

Why This Package?

SpacetimeDB uses custom classes (Identity, Timestamp, etc.) but frontend forms/APIs typically use primitives (string, Date). This package bridges the gap:

Without coercion (manual conversion):

const identity = Identity.fromString(formData.identity);
const timestamp = Timestamp.fromDate(new Date(formData.createdAt));

With coercion (automatic):

const data = UserSchema.parse(formData);
// data.identity is Identity
// data.createdAt is Timestamp

TypeScript Support

Fully typed with TypeScript 5.7+. All types are inferred correctly:

const schema = z.object({
  identity: zodSpacetime.identity(),
});

type Inferred = z.infer<typeof schema>;
// { identity: Identity }

Requirements

• SpacetimeDB SDK ≥ 1.6.0
• Zod ≥ 4.0.0

License

MIT