{"record":{"id":"570e20009c6a361d","repo":"clockworklabs/SpacetimeDB","slug":"timestamp-is-outside-of-the-representable-range-fo","errorCode":null,"errorMessage":"Timestamp is outside of the representable range for ISO string formatting","messagePattern":"Timestamp is outside of the representable range for ISO string formatting","errorType":"exception","errorClass":"RangeError","httpStatus":null,"severity":"error","filePath":"crates/bindings-typescript/src/lib/timestamp.ts","lineNumber":133,"sourceCode":"  }\n\n  /**\n   * Get an ISO 8601 / RFC 3339 formatted string representation of this timestamp with microsecond precision.\n   *\n   * This method preserves the full microsecond precision of the timestamp,\n   * and throws `RangeError` if the `Timestamp` is outside the range representable in ISO format.\n   *\n   * @returns ISO 8601 formatted string with microsecond precision (e.g., '2025-02-17T10:30:45.123456Z')\n   */\n  toISOString(): string {\n    const micros = this.__timestamp_micros_since_unix_epoch__;\n    const millis = micros / Timestamp.MICROS_PER_MILLIS;\n\n    if (\n      millis > BigInt(Number.MAX_SAFE_INTEGER) ||\n      millis < BigInt(Number.MIN_SAFE_INTEGER)\n    ) {\n      throw new RangeError(\n        'Timestamp is outside of the representable range for ISO string formatting'\n      );\n    }\n\n    const date = new Date(Number(millis));\n    const isoBase = date.toISOString(); // Format: '2025-02-17T10:30:45.123Z'\n\n    // Extract the full 6 decimal places of microseconds\n    const microsRemainder = Math.abs(Number(micros % 1000000n));\n    const fractionalPart = String(microsRemainder).padStart(6, '0');\n\n    // Replace the 3-digit millisecond part with the full 6-digit microsecond part\n    return isoBase.replace(/\\.\\d{3}Z$/, `.${fractionalPart}Z`);\n  }\n\n  since(other: Timestamp): TimeDuration {\n    return new TimeDuration(\n      this.__timestamp_micros_since_unix_epoch__ -","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/524b4487d949b61a07d4f39c862d1290259dfd20/crates/bindings-typescript/src/lib/timestamp.ts#L115-L151","documentation":"Timestamp.toISOString() formats with full microsecond precision by reusing new Date(Number(millis)).toISOString() and replacing the millisecond digits with the microsecond remainder. The same safe-integer guard as toDate applies: millis beyond +/-Number.MAX_SAFE_INTEGER cannot round-trip through a Date without losing precision, so it throws RangeError.","triggerScenarios":"Calling .toISOString() on a Timestamp whose micros, divided by 1000n, fall outside +/-2^53-1 - typically unit-confused input (millis multiplied by 1e6 twice) or corrupted values.","commonSituations":"Formatting timestamps received from feeds with different epochs or units; BigInt arithmetic bugs; log/audit code that assumes every timestamp is 21st-century.","solutions":["Fix the precision at the source: microseconds since the Unix epoch","Range-check millis before formatting and fall back to raw micros in the display string","Keep comparisons on Timestamp values instead of round-tripping through Date/ISO strings"],"exampleFix":"// before\nconst s = ts.toISOString(); // extreme micros -> RangeError\n\n// after\nconst MAX_MS = BigInt(Number.MAX_SAFE_INTEGER);\nconst ms = ts.__timestamp_micros_since_unix_epoch__ / 1000n;\nconst s = ms >= -MAX_MS && ms <= MAX_MS\n  ? ts.toISOString()\n  : `${ts.__timestamp_micros_since_unix_epoch__}us`; // lossless fallback","handlingStrategy":"validation","validationCode":"const MAX_SAFE_MILLIS = BigInt(Number.MAX_SAFE_INTEGER);\nfunction timestampToIsoSafe(ts: Timestamp): string {\n  const millis = ts.__timestamp_micros_since_unix_epoch__ / 1000n;\n  if (millis > MAX_SAFE_MILLIS || millis < -MAX_SAFE_MILLIS) {\n    return `${ts.__timestamp_micros_since_unix_epoch__}us`;\n  }\n  return ts.toISOString();\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Fix units at the ingest boundary rather than guarding every formatter","Range-check before formatting when input sources are untrusted","Prefer microsecond accessors over ISO strings for machine-to-machine exchange"],"tags":["timestamp","iso8601","range-error","javascript","bigint"],"backgroundTag":"timestamp-out-of-range","analyzedSha":"524b4487d949b61a07d4f39c862d1290259dfd20","analyzedAt":"2026-08-16T23:58:54.611Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}