TYTX for Dummies

Quick Start

Install

# Python
pip install genro-tytx              # Core
pip install genro-tytx[fast]        # With orjson (faster JSON)
pip install genro-tytx[msgpack]     # With MessagePack support
pip install genro-tytx[all]         # Everything

# JavaScript (from GitHub)
npm install genropy/genro-tytx

Encode & Decode (Python)

from decimal import Decimal
from datetime import date, datetime
from genro_tytx import to_tytx, from_tytx

# Encode a Python dict with typed values
order = {
    "product": "Widget",
    "price": Decimal("99.99"),
    "date": date(2025, 1, 15),
}

wire = to_tytx(order)
# '{"product": "Widget", "price": "99.99::N", "date": "2025-01-15::D"}::JS'

# Decode back — types are automatically restored
result = from_tytx(wire)
# {"product": "Widget", "price": Decimal("99.99"), "date": date(2025, 1, 15)}

Encode & Decode (JavaScript)

import { toTytx, fromTytx } from 'genro-tytx';
import { createDecimal, setDecimalLibrary } from 'genro-tytx/src/registry.js';

setDecimalLibrary('big.js');

const order = {
    product: "Widget",
    price: createDecimal("99.99"),
    date: new Date(Date.UTC(2025, 0, 15)),
};

const wire = toTytx(order);
// '{"product":"Widget","price":"99.99::N","date":"2025-01-15::D"}::JS'

const result = fromTytx(wire);
// { product: "Widget", price: Big("99.99"), date: Date(2025-01-15) }

HTTP Integration (Python ASGI)

from genro_tytx import asgi_data, to_tytx

async def handle_request(scope, receive, send):
    # Automatically decodes TYTX from query, headers, cookies, body
    data = await asgi_data(scope, receive)

    price = data["body"]["price"]   # Already a Decimal!
    total = price * 3

    response = to_tytx({"total": total})
    # Send response...

HTTP Integration (JavaScript)

import { fetchTytx } from 'genro-tytx';

const result = await fetchTytx('/api/order', {
    body: { price: createDecimal("99.99"), qty: 3 },
    transport: 'json',
});
// result.total is a Big (Decimal), ready to use

The Type System

TYTX adds a ::SUFFIX to values that JSON can't represent natively. The suffix tells the receiver how to reconstruct the original type.

Non-Native Types (always suffixed)

These types have no JSON equivalent. Without the suffix, the receiver has no way to know what they are.

JSON-Native Types (suffixed only in XML/QS)

These types exist natively in JSON. Suffixes are added only when the transport doesn't have native support (XML, query strings).

Structure Markers

DateTime Precision

JavaScript Date has millisecond precision. TYTX truncates Python microseconds to milliseconds during encoding to ensure perfect roundtrips.

# Python: microseconds truncated to milliseconds
to_tytx(datetime(2025, 1, 15, 10, 30, 45, 123456))
# "2025-01-15T10:30:45.123Z::DHZ"  (123456 μs → 123 ms)

# Naive datetimes are treated as UTC
to_tytx(datetime(2025, 1, 15, 10, 30))
# "2025-01-15T10:30:00.000Z::DHZ"

JSON Transport

JSON is the default transport. When your data contains typed values (Decimal, date, etc.), TYTX wraps them as strings with type suffixes and marks the whole structure with ::JS.

How encoding works

from decimal import Decimal
from datetime import date
from genro_tytx import to_tytx

# Dict with typed values → ::JS suffix
to_tytx({"price": Decimal("99.99"), "date": date(2025, 1, 15)})
# '{"price": "99.99::N", "date": "2025-01-15::D"}::JS'

# Dict with only native JSON types → no suffix
to_tytx({"name": "Widget", "count": 42})
# '{"name": "Widget", "count": 42}'

# Scalar typed value → quoted with suffix, no ::JS
to_tytx(Decimal("100.50"))
# '"100.50::N"'

# Plain scalar → quoted JSON
to_tytx("hello")
# '"hello"'

How decoding works

from genro_tytx import from_tytx

# TYTX structure → types restored
from_tytx('{"price": "99.99::N", "date": "2025-01-15::D"}::JS')
# {"price": Decimal("99.99"), "date": date(2025, 1, 15)}

# Scalar with suffix
from_tytx('"100.50::N"')
# Decimal("100.50")

# Plain JSON (no TYTX suffixes) → parsed as standard JSON
from_tytx('{"name": "Widget", "count": 42}')
# {"name": "Widget", "count": 42}

With explicit transport

When receiving data from HTTP (via asgi_data / wsgi_data), the transport is set to "json" based on the Content-Type. This tells from_tytx to expect JSON-encoded data.

# to_tytx with transport="json" wraps output in quotes
to_tytx({"price": Decimal("99.99")}, transport="json")
# '"{\\"price\\": \\"99.99::N\\"}::JS"'

# from_tytx with transport="json" strips the outer quotes
from_tytx('"{\\"price\\": \\"99.99::N\\"}::JS"', transport="json")
# {"price": Decimal("99.99")}

orjson acceleration

If orjson is installed, TYTX uses it automatically for faster JSON parsing. No code changes needed.

pip install genro-tytx[fast]   # installs orjson

XML Transport

When you need XML (SOAP, legacy integrations, config files), TYTX embeds type suffixes directly in text content and attribute values.

Data structure convention

XML elements map to Python dicts with a fixed structure:

{"tag_name": {"attrs": {...}, "value": ...}}

Encoding

from genro_tytx import to_tytx

data = {
    "order": {
        "attrs": {"id": 123, "created": date(2025, 1, 15)},
        "value": {
            "total": {"attrs": {}, "value": Decimal("299.97")}
        }
    }
}

to_tytx(data, transport="xml")

Produces:

<order id="123::L" created="2025-01-15::D">
  <total>299.97::N</total>
</order>

Decoding

xml_data = '<order id="123::L"><total>299.97::N</total></order>'

from_tytx(xml_data, transport="xml")
# {"order": {"attrs": {"id": 123}, "value": {"total": {"attrs": {}, "value": Decimal("299.97")}}}}

Configuration

MessagePack Transport

When you need compact binary encoding (WebSocket, IoT, high-throughput APIs), TYTX uses MessagePack native extension types — no string wrapping, zero overhead.

Install

# Python
pip install genro-tytx[msgpack]

# JavaScript
npm install @msgpack/msgpack

Usage

from genro_tytx import to_tytx, from_tytx

# Encode → bytes (compact binary with ext types)
data = {"price": Decimal("99.99"), "date": date(2025, 1, 15)}
packed = to_tytx(data, transport="msgpack")
# b'...'  binary payload: Decimal as ext 1, date as ext 2

# Decode → dict with real types
result = from_tytx(packed, transport="msgpack")
# {"price": Decimal("99.99"), "date": date(2025, 1, 15)}

Direct functions

from genro_tytx import to_msgpack, from_msgpack

packed = to_msgpack({"total": Decimal("500")})
result = from_msgpack(packed)
# {"total": Decimal("500")}

Query String Transport

When you need to pass typed data in URLs (query parameters, form data), TYTX encodes key-value pairs with type suffixes.

Object mode (key=value)

from genro_tytx import to_tytx, from_tytx
from genro_tytx import to_qs, from_qs

# Encode with qs=True
to_tytx({"price": Decimal("99.99"), "date": date(2025, 12, 14)}, qs=True)
# 'price=99.99::N&date=2025-12-14::D::QS'

# Or use direct functions
to_qs({"price": Decimal("99.99"), "active": True})
# 'price=99.99::N&active=true::B'

# Decode
from_qs('price=99.99::N&active=true::B')
# {"price": Decimal("99.99"), "active": True}

Array mode (no keys)

to_qs(["alpha", "beta", "gamma"])
# 'alpha&beta&gamma'

from_qs('alpha&beta&gamma')
# ["alpha", "beta", "gamma"]

HTTP Integration

TYTX provides ready-made utilities to decode typed data from HTTP requests — query parameters, headers, cookies, and body — in both ASGI and WSGI applications.

ASGI (async)

from genro_tytx import asgi_data

async def app(scope, receive, send):
    data = await asgi_data(scope, receive)

    data["query"]    # dict — decoded query parameters
    data["headers"]  # dict — decoded headers
    data["cookies"]  # dict — decoded cookies
    data["body"]     # any  — decoded body (based on Content-Type)

WSGI (sync)

from genro_tytx import wsgi_data

def app(environ, start_response):
    data = wsgi_data(environ)

    data["query"]    # same structure as ASGI
    data["headers"]
    data["cookies"]
    data["body"]

Auto-detection

Transport is detected automatically from Content-Type:

JavaScript: fetchTytx

import { fetchTytx } from 'genro-tytx';

// POST with automatic TYTX encoding
const result = await fetchTytx('/api/order', {
    body: { price: createDecimal("99.99"), qty: 3 },
    transport: 'json',     // default
});
// result is already decoded with real types

// GET (no body → auto GET)
const data = await fetchTytx('/api/products');

Configuration

How It All Fits Together

The encode/decode flow

Module architecture

JavaScript decimal libraries

JavaScript has no built-in Decimal. TYTX lets you choose your library:

import { setDecimalLibrary } from 'genro-tytx/src/registry.js';

setDecimalLibrary('decimal.js');  // Full-featured, larger bundle
setDecimalLibrary('big.js');      // Lightweight, recommended
setDecimalLibrary('number');     // Native Number fallback (loses precision)

Cheat Sheet

Python

JavaScript

Type suffixes