@genrojs/tytx

中文文档
0.16.4发布于 2026/10/25Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 4284

Typed data interchange between Python and JavaScript over JSON, XML and MessagePack: Decimal, dates and custom types arrive with their type.

原始使用文档
文档目录16 节
  1. The Pain You Know
  2. The TYTX Solution
  3. 30-Second Demo
  4. Untyped JSON codec
  5. Streams of records (JSON Lines)
  6. Custom types
  7. Installation
  8. Real-World Example: Order Processing
  9. 1. The Data
  10. 2. ❌ WITHOUT TYTX: 20 Manual Conversions
  11. 3. ✅ WITH TYTX: Zero Conversions
  12. Bonus: Switch to MessagePack in One Line
  13. Supported Types
  14. When to Use TYTX
  15. Documentation
  16. License

TYTX Logo

PyPI JSR Python 3.10+ License Status
Tests Coverage Documentation

genro-tytx

A lightweight multi-transport typed data interchange system.

TYTX eliminates manual type conversions between Python and JavaScript, and makes switching to MessagePack for better performance as simple as changing a parameter.

You send a Decimal from Python, JavaScript receives a string. You convert it back. Every. Single. Time. TYTX fixes this—types flow automatically between Python and JavaScript, over JSON, XML, or MessagePack.

The Pain You Know

# Your Python API
return {"price": Decimal("99.99"), "due_date": date(2025, 1, 15)}
// Your JavaScript client
const data = await response.json();
// data.price is "99.99" (string) - need to convert
// data.due_date is "2025-01-15" (string) - need to convert

const price = new Decimal(data.price);      // Manual conversion
const dueDate = new Date(data.due_date);    // Manual conversion

This leads to:

  • Conversion code scattered everywhere
  • Bugs when someone forgets to convert
  • Financial calculations with floating-point errors
  • Different date formats causing off-by-one-day bugs

The TYTX Solution

# Server - just return native types
return {"price": Decimal("99.99"), "due_date": date(2025, 1, 15)}
// Client - types arrive ready to use
const data = await fetchTytx('/api/order');
data.price      // → Decimal (not string)
data.due_date   // → Date (not string)

Zero conversion code. Types just work.

30-Second Demo

Python:

pip install genro-tytx
from decimal import Decimal
from datetime import date
from genro_tytx import to_tytx, from_tytx

# Encode
data = {"price": Decimal("99.99"), "date": date(2025, 1, 15)}
encoded = to_tytx(data)
# '{"price":"99.99::N","date":"2025-01-15::D"}::JS'

# Decode
decoded = from_tytx(encoded)
# {"price": Decimal("99.99"), "date": date(2025, 1, 15)}

JavaScript:

npm install @genrojs/tytx   # npm
bunx jsr add @genro/tytx    # JSR
import { fetchTytx } from '@genro/tytx';
import Big from 'big.js';

const result = await fetchTytx('/api/invoice', {
    body: { price: new Big('99.99'), date: new Date() }
});
// result.total → Big (ready to use)

Untyped JSON codec

Besides the typed to_tytx / from_tytx API, TYTX exposes a plain JSON codec for the untyped path — no type suffixes, just fast JSON (orjson when available, stdlib otherwise):

from genro_tytx import json_dumps, json_loads

json_dumps({"a": 1})        # -> b'{"a":1}'   (UTF-8 bytes)
json_loads('{"a": 1}')      # accepts str or bytes -> {"a": 1}

json_dumps returns UTF-8 bytes (ready for ASGI/WebSocket send), json_loads accepts str or bytes. Use these when you want plain JSON; use to_tytx / from_tytx when you want typed values to flow.

Streams of records (JSON Lines)

to_tytx_iter / from_tytx_iter (JavaScript toTytxIter / fromTytxIter) take an iterable of objects and give back an iterator, one record at a time, so a selection is never held in memory as a whole. Encoding turns typed values into "value::CODE" strings with no ::JS marker: each record is plain JSON, one JSONL line. Decoding turns those strings back into typed values and leaves everything else unchanged. A sync source gives an iterator, an async source an async iterator. Splitting the stream into lines belongs to the JSONL reader or writer.

from genro_tytx import to_tytx_iter, from_tytx_iter

for record in to_tytx_iter(rows):                  # rows: dicts with Decimal, date, ...
    out.write(json.dumps(record) + "\n")           # {"price": "12.50::N", "day": "2026-10-22::D"}

for record in from_tytx_iter(json.loads(line) for line in open("orders.jsonl")):
    ...                                            # record["price"] is a Decimal

async for record in from_tytx_iter(async_records): # async source -> async iterator
    ...

Over HTTP the stream is sent as Content-Type: application/jsonl with X-TYTX-Transport: jsonl; getTransport returns 'jsonl' for it. A response that ends early looks like a complete one: reporting errors after the headers, or the expected number of records, is up to the application.

Custom types

register_type lets an external package teach TYTX a new type — a serialize hook (object → string) and a deserialize hook (string → object) under a custom suffix. The package registers at its own import time, so TYTX gains no dependency on it:

from genro_tytx import register_type, to_tytx, from_tytx

class Point:
    def __init__(self, x, y): self.x, self.y = x, y

register_type(Point, "PT", lambda p: f"{p.x},{p.y}",
              lambda s: Point(*map(int, s.split(","))))

to_tytx([1, Point(5, 6), "k"])   # '[1,"5,6::PT","k"]::JS'
from_tytx('5,6::PT')             # Point(5, 6)

The custom type flows like any built-in scalar, including nested inside dicts and lists. The exact type is matched first; an unregistered subclass of a registered type travels under that type's code, written by its own serializer (genro-builders' SourceBag travels as genro-bag's X). Built-in types keep the exact-type rule. A class cannot be registered under a code another class owns. A code is one or more uppercase ASCII letters, any length; registration refuses anything else. Re-registering the same class replaces its hooks; reusing a suffix owned by a different type raises an error. An unknown code on the receiving side is not an error: the string comes back untouched. The same semantics apply to the JavaScript client (registerType / registerClass). The rules and the codes reserved by consumers are in spec/TYTX-SPEC.md §2.5.

When the type owns its serialization, register_class reads the hooks from the class itself — usable as a decorator. It needs __tytx_suffix__, an instance to_tytx() and a from_tytx classmethod (from_tytx must be a classmethod: decoding starts from the suffix and rebuilds the instance from scratch):

from genro_tytx import register_class

@register_class
class Point:
    __tytx_suffix__ = "PT"
    def __init__(self, x, y): self.x, self.y = x, y
    def to_tytx(self): return f"{self.x},{self.y}"
    @classmethod
    def from_tytx(cls, s): return cls(*map(int, s.split(",")))

The concrete class of a subclass is the type's own business. TYTX keeps one subtype dictionary per code and never reads it: set_subtype_dict(suffix, dict) replaces it, get_subtype_dict(suffix) returns it ({} if none was set). JavaScript: setSubtypeDict / getSubtypeDict. The type's to_tytx/from_tytx use it; whoever adds a subclass calls register_subtype(suffix, cls, name=None) (JavaScript registerSubtype), which adds the class under its own name, or under name, and raises if the name already belongs to another class. genro-bag maps symbolic names to Bag classes this way.

Installation

# Python
pip install genro-tytx

# JavaScript/TypeScript, from npm
npm install @genrojs/tytx

# JavaScript/TypeScript, from JSR
bunx jsr add @genro/tytx
# With npm: npx jsr add @genro/tytx

JavaScript includes Decimal, Big, MessagePack and XML dependencies. No separate codec installation is needed. Python extras remain unchanged.

Real-World Example: Order Processing

A typical business scenario: process an order with 8 typed fields, return 6 typed results.

1. The Data

JavaScript Client has order data with proper types:

import Big from 'big.js';

const orderData = {
    unit_price: new Big('149.99'),      // Decimal
    quantity: 3,
    discount: new Big('10.00'),         // Decimal
    order_date: new Date(2025, 0, 15),  // Date
    delivery_date: new Date(2025, 0, 20),
    express: true,
    customer_id: 12345,
    notes: 'Handle with care'
};

// Expects response: { subtotal, tax, shipping, total, ship_date, arrival_date }

Python Server has business logic expecting proper types:

async def process_order(unit_price, quantity, discount, order_date,
                        delivery_date, express, customer_id, notes):
    """Business logic - expects Decimal and date types."""
    subtotal = unit_price * quantity
    tax = subtotal * Decimal('0.22')
    shipping = Decimal('15.00') if express else Decimal('5.00')
    total = subtotal - discount + tax + shipping
    ship_date = order_date + timedelta(days=1 if express else 3)
    return {
        'subtotal': subtotal, 'tax': tax, 'shipping': shipping,
        'total': total, 'ship_date': ship_date, 'arrival_date': delivery_date
    }

2. ❌ WITHOUT TYTX: 20 Manual Conversions

JavaScript - must convert to/from strings:

// Send: convert types → strings
const response = await fetch('/api/process_order', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        unit_price: orderData.unit_price.toString(),           // Decimal → string
        discount: orderData.discount.toString(),               // Decimal → string
        order_date: orderData.order_date.toISOString().slice(0, 10),  // Date → string
        delivery_date: orderData.delivery_date.toISOString().slice(0, 10),
        quantity: orderData.quantity, express: orderData.express,
        customer_id: orderData.customer_id, notes: orderData.notes
    })
});

// Receive: convert strings → types
const json = await response.json();
const result = {
    subtotal: new Big(json.subtotal),     tax: new Big(json.tax),
    shipping: new Big(json.shipping),     total: new Big(json.total),
    ship_date: new Date(json.ship_date),  arrival_date: new Date(json.arrival_date)
};

Python - must convert to/from strings:

@app.post("/api/process_order")
async def handle_order(request: Request):
    json_data = await request.json()

    # Receive: convert strings → types
    unit_price = Decimal(json_data['unit_price'])
    discount = Decimal(json_data['discount'])
    order_date = date.fromisoformat(json_data['order_date'])
    delivery_date = date.fromisoformat(json_data['delivery_date'])

    result = await process_order(unit_price, json_data['quantity'], discount,
        order_date, delivery_date, json_data['express'],
        json_data['customer_id'], json_data['notes'])

    # Send: convert types → strings
    return JSONResponse({
        'subtotal': str(result['subtotal']), 'tax': str(result['tax']),
        'shipping': str(result['shipping']), 'total': str(result['total']),
        'ship_date': result['ship_date'].isoformat(),
        'arrival_date': result['arrival_date'].isoformat()
    })

Total: 20 manual conversions (4 JS→string + 4 string→Python + 6 Python→string + 6 string→JS).


3. ✅ WITH TYTX: Zero Conversions

import { fetchTytx } from '@genro/tytx';

const result = await fetchTytx('/api/process_order', { body: orderData });
console.log(result.total.toFixed(2));  // Big, ready to use

Total: 0 conversions. Types flow naturally.

Bonus: Switch to MessagePack in One Line

Need binary format for better performance? Just add transport: 'msgpack':

// JSON (default)
const result = await fetchTytx('/api/process_order', { body: orderData });

// MessagePack - same API, binary format
const result = await fetchTytx('/api/process_order', { body: orderData, transport: 'msgpack' });

Supported Types

PythonJavaScriptWire Format
DecimalDecimal (big.js)"99.99::N"
dateDate (midnight UTC)"2025-01-15::D"
datetimeDate"2025-01-15T10:30:00.000Z::DHZ"
timeDate (epoch date)"10:30:00.000::H"
bytesUint8Array"AAEC::RAW" (base64; native bin on MessagePack)

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

When to Use TYTX

Good fit:

  • Web apps with forms containing dates/decimals
  • Financial applications requiring decimal precision
  • APIs that send/receive typed data frequently
  • Excel-like grids with mixed types

Not needed:

  • APIs that only use strings and integers
  • Simple CRUD with no special types
  • Already using GraphQL/Protobuf with full type support

Documentation

I want to...Go to...
Try it in 5 minutesQuick Start
Use it over HTTPHTTP Integration
Understand the wire formatHow It Works
See API referenceAPI Reference
Compare with alternativesAlternatives

License

Apache License 2.0 - Copyright 2025 Softwell S.r.l.

版本与发布记录

@genrojs/tytx 共发布 4 个版本,首次发布于 2026/10/01;过去 12 个月发布了 4 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.16.4latest2026/10/2522 天前
0.16.32026/10/1927 天前
0.16.22026/10/041 个月前
0.16.12026/10/011 个月前

关于 @genrojs/tytx 的常见问题

@genrojs/tytx 是什么?

Typed data interchange between Python and JavaScript over JSON, XML and MessagePack: Decimal, dates and custom types arrive with their type.

如何安装 @genrojs/tytx?

在项目目录运行 npm install @genrojs/tytx,或使用 pnpm add / yarn add / bun add。

@genrojs/tytx 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@genrojs/tytx 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@genrojs/tytx 可以商用吗?

@genrojs/tytx 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@genrojs/tytx 的下载量有多少?

根据 npm 官方下载统计,@genrojs/tytx 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,284 次,日均约 143 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@genrojs/tytx 还在维护吗?

最新版本 0.16.4 发布于 2026/10/25(22 天前);至今共发布 4 个版本,其中过去 12 个月发布了 4 个;首次发布于 2026/10/01。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。