{"_id":"@douglance/stdb-zod-bridge-runtime","name":"@douglance/stdb-zod-bridge-runtime","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@douglance/stdb-zod-bridge-runtime","version":"1.0.0","description":"Runtime helpers for SpacetimeDB Zod schema generator","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc --build","dev":"tsc --build --watch","clean":"rm -rf dist .tsbuildinfo","typecheck":"tsc --noEmit","lint":"biome check .","lint:fix":"biome check --write .","test":"vitest run --passWithNoTests","test:watch":"vitest","test:coverage":"vitest run --coverage"},"dependencies":{"zod":"^4.1.12"},"devDependencies":{"@biomejs/biome":"^1.9.4","@types/node":"^20.17.10","@vitest/coverage-v8":"^3.2.4","spacetimedb":"^1.6.0","typescript":"^5.7.0","vitest":"^3.2.4"},"peerDependencies":{"spacetimedb":">=1.6.0","zod":">=4.0.0"},"peerDependenciesMeta":{"spacetimedb":{"optional":false},"zod":{"optional":false}},"keywords":["spacetimedb","zod","validation","runtime","helpers"],"author":"","license":"MIT","_id":"@douglance/stdb-zod-bridge-runtime@1.0.0","gitHead":"d95209c60e55e862b01f3a505241d5059eacf573","_nodeVersion":"23.10.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-K9Qw71FWFkt/dP2e40wACrcRGN+W6TOgmy8gt1i4rb//VHS3egnox23kxUiXQidHW7af6Xc0FJJOFBdVaDLO4A==","shasum":"dc041ac65dd387558fd6dbc7e98bf194959804fa","tarball":"https://registry.npmjs.org/@douglance/stdb-zod-bridge-runtime/-/stdb-zod-bridge-runtime-1.0.0.tgz","fileCount":8,"unpackedSize":29079,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCVovjfvX/uxMWnuJNKZjK2PyQLg4mz0XLGpBJG7qlZ2AIgQmvC1kGGAqBe9LbHicLQh919RDV/wsjVIvGpg0Fh7dQ="}]},"_npmUser":{"name":"douglance","email":"douglance@gmail.com"},"directories":{},"maintainers":[{"name":"douglance","email":"douglance@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/stdb-zod-bridge-runtime_1.0.0_1761473537910_0.7730362762019123"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-26T10:12:17.852Z","1.0.0":"2025-10-26T10:12:18.124Z","modified":"2025-10-26T10:12:18.379Z"},"maintainers":[{"name":"douglance","email":"douglance@gmail.com"}],"description":"Runtime helpers for SpacetimeDB Zod schema generator","keywords":["spacetimedb","zod","validation","runtime","helpers"],"license":"MIT","readme":"# @spacetimedb/zod-bridge-runtime\n\nRuntime helpers for validating SpacetimeDB types with [Zod](https://zod.dev).\n\nThis 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](../zod-bridge) but can also be used standalone.\n\n## Installation\n\n```bash\nnpm install @spacetimedb/zod-bridge-runtime zod spacetimedb\n```\n\n## Usage\n\n### SpacetimeDB Types\n\n```typescript\nimport { zodSpacetime } from '@spacetimedb/zod-bridge-runtime';\nimport { z } from 'zod';\n\n// Identity: accepts Identity instance, hex string, or BigInt\nconst IdentitySchema = zodSpacetime.identity();\n\n// Valid inputs:\nIdentitySchema.parse(myIdentity); // Identity instance\nIdentitySchema.parse(\"0x1234...\"); // 64-char hex string\nIdentitySchema.parse(123456789n); // BigInt\n\n// Timestamp: accepts Timestamp instance, Date, ISO string, or Unix ms\nconst TimestampSchema = zodSpacetime.timestamp();\n\n// Valid inputs:\nTimestampSchema.parse(myTimestamp); // Timestamp instance\nTimestampSchema.parse(new Date()); // Date object\nTimestampSchema.parse(\"2024-01-15T10:30:00Z\"); // ISO string\nTimestampSchema.parse(1705318200000); // Unix milliseconds\n\n// TimeDuration: accepts TimeDuration instance or number (milliseconds)\nconst DurationSchema = zodSpacetime.timeDuration();\n\n// Valid inputs:\nDurationSchema.parse(myDuration); // TimeDuration instance\nDurationSchema.parse(5000); // 5 seconds in milliseconds\n\n// ConnectionId: accepts ConnectionId instance or string\nconst ConnectionIdSchema = zodSpacetime.connectionId();\n\n// Valid inputs:\nConnectionIdSchema.parse(myConnectionId); // ConnectionId instance\nConnectionIdSchema.parse(\"conn-123\"); // String\n\n// ScheduleAt: accepts ScheduleAt instance or BigInt (microseconds)\nconst ScheduleAtSchema = zodSpacetime.scheduleAt();\n\n// Valid inputs:\nScheduleAtSchema.parse(myScheduleAt); // ScheduleAt instance\nScheduleAtSchema.parse(16667n); // 16.667 microseconds (60 Hz tick)\n```\n\n### Numeric Types\n\nAll numeric types enforce proper range validation:\n\n```typescript\nimport { zodNumeric } from '@spacetimedb/zod-bridge-runtime';\n\n// Unsigned integers\nconst u8 = zodNumeric.u8(); // 0-255\nconst u16 = zodNumeric.u16(); // 0-65535\nconst u32 = zodNumeric.u32(); // 0-4294967295\nconst u64 = zodNumeric.u64(); // 0n-18446744073709551615n (BigInt)\nconst u128 = zodNumeric.u128(); // 0n+ (BigInt, no upper bound)\nconst u256 = zodNumeric.u256(); // 0n+ (BigInt, no upper bound)\n\n// Signed integers\nconst i8 = zodNumeric.i8(); // -128-127\nconst i16 = zodNumeric.i16(); // -32768-32767\nconst i32 = zodNumeric.i32(); // -2147483648-2147483647\nconst i64 = zodNumeric.i64(); // -9223372036854775808n-9223372036854775807n (BigInt)\nconst i128 = zodNumeric.i128(); // Any BigInt\nconst i256 = zodNumeric.i256(); // Any BigInt\n\n// Floating point\nconst f32 = zodNumeric.f32(); // Any number\nconst f64 = zodNumeric.f64(); // Any number\n```\n\n### Range Validation Examples\n\n```typescript\nimport { zodNumeric } from '@spacetimedb/zod-bridge-runtime';\nimport { z } from 'zod';\n\n// u8 validation\nconst u8Schema = zodNumeric.u8();\nu8Schema.parse(0); // ✓\nu8Schema.parse(255); // ✓\nu8Schema.parse(256); // ✗ Error: Number must be less than or equal to 255\n\n// u32 validation\nconst u32Schema = zodNumeric.u32();\nu32Schema.parse(0); // ✓\nu32Schema.parse(4294967295); // ✓\nu32Schema.parse(4294967296); // ✗ Error: Number must be less than or equal to 4294967295\nu32Schema.parse(-1); // ✗ Error: Number must be greater than or equal to 0\n\n// i32 validation\nconst i32Schema = zodNumeric.i32();\ni32Schema.parse(-2147483648); // ✓\ni32Schema.parse(2147483647); // ✓\ni32Schema.parse(2147483648); // ✗ Error: Number must be less than or equal to 2147483647\n```\n\n## API Reference\n\n### `zodSpacetime`\n\n#### `zodSpacetime.identity()`\n\nReturns a Zod schema that accepts:\n- `Identity` instance from SpacetimeDB\n- 64-character hex string (with or without `0x` prefix)\n- `BigInt`\n\nAll inputs are transformed to `Identity` instances.\n\n**Example:**\n```typescript\nconst schema = zodSpacetime.identity();\nconst id = schema.parse(\"0x\" + \"0\".repeat(64)); // Identity instance\n```\n\n#### `zodSpacetime.timestamp()`\n\nReturns a Zod schema that accepts:\n- `Timestamp` instance from SpacetimeDB\n- `Date` object\n- ISO 8601 datetime string\n- Unix timestamp in milliseconds (number)\n\nAll inputs are transformed to `Timestamp` instances.\n\n**Example:**\n```typescript\nconst schema = zodSpacetime.timestamp();\nconst ts = schema.parse(new Date()); // Timestamp instance\n```\n\n#### `zodSpacetime.timeDuration()`\n\nReturns a Zod schema that accepts:\n- `TimeDuration` instance from SpacetimeDB\n- Number (milliseconds)\n\nAll inputs are transformed to `TimeDuration` instances.\n\n**Example:**\n```typescript\nconst schema = zodSpacetime.timeDuration();\nconst duration = schema.parse(5000); // TimeDuration instance (5 seconds)\n```\n\n#### `zodSpacetime.connectionId()`\n\nReturns a Zod schema that accepts:\n- `ConnectionId` instance from SpacetimeDB\n- String representation\n\nAll inputs are transformed to `ConnectionId` instances.\n\n**Example:**\n```typescript\nconst schema = zodSpacetime.connectionId();\nconst connId = schema.parse(\"conn-123\"); // ConnectionId instance\n```\n\n#### `zodSpacetime.scheduleAt()`\n\nReturns a Zod schema that accepts:\n- `ScheduleAt` instance from SpacetimeDB\n- `BigInt` (microseconds)\n\nAll inputs are transformed to `ScheduleAt` instances.\n\n**Example:**\n```typescript\nconst schema = zodSpacetime.scheduleAt();\nconst schedule = schema.parse(16667n); // ScheduleAt instance\n```\n\n### `zodNumeric`\n\nAll numeric schemas return standard Zod number or BigInt schemas with range constraints:\n\n| Method | Return Type | Range |\n|--------|-------------|-------|\n| `u8()` | `z.ZodNumber` | 0-255 |\n| `u16()` | `z.ZodNumber` | 0-65535 |\n| `u32()` | `z.ZodNumber` | 0-4294967295 |\n| `u64()` | `z.ZodBigInt` | 0n-18446744073709551615n |\n| `u128()` | `z.ZodBigInt` | 0n+ |\n| `u256()` | `z.ZodBigInt` | 0n+ |\n| `i8()` | `z.ZodNumber` | -128-127 |\n| `i16()` | `z.ZodNumber` | -32768-32767 |\n| `i32()` | `z.ZodNumber` | -2147483648-2147483647 |\n| `i64()` | `z.ZodBigInt` | -9223372036854775808n-9223372036854775807n |\n| `i128()` | `z.ZodBigInt` | Any |\n| `i256()` | `z.ZodBigInt` | Any |\n| `f32()` | `z.ZodNumber` | Any |\n| `f64()` | `z.ZodNumber` | Any |\n\n## Error Handling\n\nAll schemas provide clear error messages on validation failure:\n\n```typescript\nimport { zodSpacetime, zodNumeric } from '@spacetimedb/zod-bridge-runtime';\nimport { z } from 'zod';\n\ntry {\n  zodNumeric.u8().parse(256);\n} catch (error) {\n  if (error instanceof z.ZodError) {\n    console.error(error.errors);\n    // [{\n    //   code: \"too_big\",\n    //   maximum: 255,\n    //   path: [],\n    //   message: \"Number must be less than or equal to 255\"\n    // }]\n  }\n}\n\ntry {\n  zodSpacetime.identity().parse(\"not-a-hex-string\");\n} catch (error) {\n  if (error instanceof z.ZodError) {\n    console.error(error.errors);\n    // [{\n    //   code: \"custom\",\n    //   path: [],\n    //   message: \"Invalid Identity: ...\"\n    // }]\n  }\n}\n```\n\n## TypeScript Types\n\nThe package exports TypeScript type declarations for all SpacetimeDB classes:\n\n```typescript\nimport type {\n  Identity,\n  Timestamp,\n  TimeDuration,\n  ConnectionId,\n  ScheduleAt,\n} from '@spacetimedb/zod-bridge-runtime';\n```\n\nThese match the actual classes from `spacetimedb` package.\n\n## Standalone Usage\n\nWhile this package is primarily used by `@spacetimedb/zod-bridge`, you can use it standalone:\n\n```typescript\nimport { zodSpacetime, zodNumeric } from '@spacetimedb/zod-bridge-runtime';\nimport { z } from 'zod';\n\nconst PlayerSchema = z.object({\n  id: zodSpacetime.identity(),\n  name: z.string().min(1).max(20),\n  score: zodNumeric.u32(),\n  lastSeen: zodSpacetime.timestamp(),\n});\n\ntype Player = z.infer<typeof PlayerSchema>;\n\nfunction validatePlayer(data: unknown): Player {\n  return PlayerSchema.parse(data);\n}\n```\n\n## License\n\nMIT\n\n## Related\n\n- [@spacetimedb/zod-bridge](../zod-bridge) - Auto-generate Zod schemas from SpacetimeDB modules\n- [spacetimedb](https://www.npmjs.com/package/spacetimedb) - SpacetimeDB TypeScript SDK\n- [zod](https://zod.dev) - TypeScript-first schema validation\n","readmeFilename":"README.md","_rev":"1-533f00d5d82f72351149cf4fb4bd61dd"}