FAQ

Common questions about using TYTX.

Getting Started

Do I need to understand the wire format to use TYTX?

No. The middleware handles encoding/decoding automatically. Your application code works with native types (Decimal, date, datetime, time) on both ends. See How It Works if you’re curious about the internals.

Which decimal library should I use in JavaScript?

We recommend big.js for most use cases - it’s lightweight and sufficient for financial calculations. Use decimal.js if you need advanced features like trigonometric functions.

Without a decimal library, TYTX falls back to native Number, which can cause precision loss for large or precise values.

npm install big.js  # Recommended
# or
npm install decimal.js

Does TYTX work with my framework?

TYTX provides HTTP utilities for:

ASGI (FastAPI, Starlette, Quart) - use asgi_data()
WSGI (Flask, Django, Bottle) - use wsgi_data()

Example:

from genro_tytx import asgi_data, to_tytx

# In your request handler (FastAPI/Starlette)
data = await asgi_data(request.scope, request.receive)
response = to_tytx(result)

Types and Conversion

How does TYTX handle timezones?

All datetime values are converted to UTC during encoding. The wire format always uses ISO 8601 with Z suffix:

# Input: aware datetime
datetime(2025, 1, 15, 10, 30, tzinfo=timezone.utc)
# Wire: "2025-01-15T10:30:00.000Z::DHZ"
# Output: datetime with UTC timezone

# Input: naive datetime (treated as UTC)
datetime(2025, 1, 15, 10, 30)
# Wire: "2025-01-15T10:30:00.000Z::DHZ"
# Output: datetime with UTC timezone

Why does `time` become a `Date` in JavaScript?

JavaScript doesn’t have a native time-only type. TYTX represents time values as Date objects with the epoch date (1970-01-01):

// time(10, 30) in Python becomes
new Date('1970-01-01T10:30:00.000Z')

// To display just the time:
const timeStr = date.toISOString().slice(11, 19);  // "10:30:00"

What happens to microseconds?

Microseconds are truncated to milliseconds for JavaScript compatibility. JavaScript’s Date only supports millisecond precision:

time(10, 30, 45, 123456)  # 123456 microseconds
# Wire: "10:30:45.123::H"  # 123 milliseconds

Can I send native JSON types through TYTX?

Yes. Native JSON types (string, number, boolean, null) pass through unchanged:

{
    "price": Decimal("99.99"),  # Encoded as "99.99::N"
    "name": "Widget",           # Unchanged
    "quantity": 5,              # Unchanged
    "in_stock": True,           # Unchanged
}

HTTP Integration

Do I need to set Content-Type headers manually?

When using fetchTytx on the client, headers are set automatically. For manual requests:

headers = {"Content-Type": "application/vnd.tytx+json"}

Can I use TYTX with regular `fetch()`?

Yes, but you need to encode/decode manually:

import { toTytx, fromTytx } from 'genro-tytx';
import Big from 'big.js';

const response = await fetch('/api/data', {
    method: 'POST',
    headers: { 'Content-Type': 'application/vnd.tytx+json' },
    body: toTytx({ price: new Big('100.50') }),
});

const data = fromTytx(await response.text());

fetchTytx does this automatically.

How do I pass typed values in query strings?

Query strings with TYTX suffixes are automatically decoded on the server:

# URL: /api/search?start_date=2025-01-01::D&min_price=10.00::N

@app.get("/api/search")
async def search(request: Request):
    data = await asgi_data(request.scope, request.receive)
    start_date = data["query"]["start_date"]  # date object
    min_price = data["query"]["min_price"]    # Decimal object

Troubleshooting

My Decimal values are becoming floats

Make sure you have a decimal library installed in JavaScript:

npm install big.js

Without a decimal library, TYTX falls back to Number.

Dates are off by one day

This usually happens with date-only values when local timezone conversion is applied. TYTX uses UTC for all date/time values. When creating dates in JavaScript:

// Wrong - may shift due to timezone
new Date('2025-01-15')

// Correct - explicit UTC
new Date(Date.UTC(2025, 0, 15))

The request data isn’t being decoded

Check that:

The Content-Type header is set correctly (application/json or application/vnd.tytx+json)
The request body is valid JSON
You’re using asgi_data() or wsgi_data() to decode the request

I’m getting “unknown type code” warnings

Unknown suffixes are passed through as strings. This can happen when:

Using a newer TYTX version with new type codes
Data contains :: in regular strings (escape if needed)

Performance

Is TYTX slower than plain JSON?

The overhead is minimal - just string suffix parsing. For high-performance scenarios, install orjson:

pip install genro-tytx[fast]

Should I use MessagePack for better performance?

MessagePack is more compact than JSON but requires an additional library. Use it when:

Bandwidth is a concern
You’re sending large amounts of data
Both client and server support it

To enable MessagePack support:

Python:

pip install genro-tytx[msgpack]

from genro_tytx import to_msgpack, from_msgpack

# Encode
binary_data = to_msgpack({"price": Decimal("100.50")})

# Decode
data = from_msgpack(binary_data)

JavaScript / TypeScript:

npm install @msgpack/msgpack

import { toMsgpack, fromMsgpack } from 'genro-tytx';
import Big from 'big.js';

// Encode
const binary = toMsgpack({ price: new Big('100.50') });

// Decode
const data = fromMsgpack(binary);

For most web applications, JSON is fine.