{"id":31664024,"url":"https://github.com/bbopen/tywrap","last_synced_at":"2026-04-09T11:01:16.752Z","repository":{"id":309477622,"uuid":"1036408708","full_name":"bbopen/tywrap","owner":"bbopen","description":"TypeScript wrapper for Python libraries with full type safety and multi-runtime support (Node.js, Deno, Bun, Browser/Pyodide)","archived":false,"fork":false,"pushed_at":"2025-08-30T18:17:29.000Z","size":134,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-30T19:23:56.328Z","etag":null,"topics":["browser","bun","code-generation","deno","nodejs","pyodide","python","type-safety","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/bbopen/tywrap","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbopen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-12T03:24:53.000Z","updated_at":"2025-08-12T04:10:39.000Z","dependencies_parsed_at":"2025-08-12T06:21:16.536Z","dependency_job_id":"e0ae4783-1048-497a-88de-371d31ad1c10","html_url":"https://github.com/bbopen/tywrap","commit_stats":null,"previous_names":["bbopen/tywrap"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bbopen/tywrap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbopen%2Ftywrap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbopen%2Ftywrap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbopen%2Ftywrap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbopen%2Ftywrap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbopen","download_url":"https://codeload.github.com/bbopen/tywrap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbopen%2Ftywrap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278846332,"owners_count":26056090,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser","bun","code-generation","deno","nodejs","pyodide","python","type-safety","typescript"],"created_at":"2025-10-07T20:53:20.999Z","updated_at":"2026-04-09T11:01:16.744Z","avatar_url":"https://github.com/bbopen.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tywrap\n\n[![npm version](https://img.shields.io/npm/v/tywrap.svg)](https://www.npmjs.com/package/tywrap)\n[![PyPI version](https://img.shields.io/pypi/v/tywrap-ir.svg)](https://pypi.org/project/tywrap-ir/)\n[![CI](https://github.com/bbopen/tywrap/actions/workflows/ci.yml/badge.svg)](https://github.com/bbopen/tywrap/actions/workflows/ci.yml)\n[![Coverage](https://codecov.io/gh/bbopen/tywrap/branch/main/graph/badge.svg)](https://codecov.io/gh/bbopen/tywrap)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![npm downloads](https://img.shields.io/npm/dm/tywrap.svg)](https://www.npmjs.com/package/tywrap)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n[![Docs](https://img.shields.io/badge/docs-bbopen.github.io%2Ftywrap-blue)](https://bbopen.github.io/tywrap)\n\nTypeScript wrapper for Python libraries with full type safety.\n\n\u003e **⚠️ Experimental** — APIs may change before v1.0.0. See the\n\u003e [releases page](https://github.com/bbopen/tywrap/releases) for breaking\n\u003e changes.\n\n## Features\n\n- **Full Type Safety** - TypeScript definitions generated from Python source\n  analysis\n- **Multi-Runtime** - Node.js (subprocess) and browsers (Pyodide)\n- **Rich Data Types** - numpy, pandas, scipy, torch, sklearn, and stdlib types\n- **Efficient Serialization** - Apache Arrow binary format with JSON fallback\n\n## Why tywrap?\n\n| Feature                         | tywrap    | pythonia  | node-calls-python | pymport   |\n| ------------------------------- | --------- | --------- | ----------------- | --------- |\n| Auto-generated TypeScript types | ✅        | ❌        | ❌                | ❌        |\n| Browser / WASM (Pyodide)        | ✅        | ❌        | ❌                | ❌        |\n| numpy / pandas type mappings    | ✅        | ❌        | ❌                | ❌        |\n| Node.js + Bun + Deno            | All three | Node only | Node only         | Node only |\n| Apache Arrow binary transport   | ✅        | ❌        | ❌                | ❌        |\n\n## Requirements\n\n- Node.js 20+ (or Bun 1.1+ / Deno 1.46+)\n- Python 3.10+ with `tywrap-ir`:\n\n  ```bash\n  pip install tywrap-ir\n  ```\n\n## Quick Start\n\n```bash\nnpm install tywrap\npip install tywrap-ir  # Python component for code generation\nnpx tywrap init        # Create config (and package.json scripts if present)\nnpx tywrap generate    # Generate wrappers\n```\n\nFor CI (or to verify a dependency upgrade didn’t change the generated surface):\n\n```bash\nnpx tywrap generate --check\n```\n\n```typescript\nimport { NodeBridge } from 'tywrap/node';\nimport { setRuntimeBridge } from 'tywrap/runtime';\nimport * as math from './generated/math.generated.js';\n\nconst bridge = new NodeBridge({ pythonPath: 'python3' });\nsetRuntimeBridge(bridge);\n\nconst result = await math.sqrt(16); // 4\n```\n\n\u003e If tywrap saves you time, a ⭐ on [GitHub](https://github.com/bbopen/tywrap)\n\u003e helps others find it.\n\n## Runtime Bridges\n\n### Node.js\n\n```typescript\nimport { NodeBridge } from 'tywrap/node';\nconst bridge = new NodeBridge({\n  pythonPath: 'python3',\n  virtualEnv: './venv',\n  timeoutMs: 30000,\n});\n```\n\nNodeBridge is the default, correctness-first bridge. OptimizedNodeBridge is a\nperformance-focused prototype (process pooling + optional caching) and is not a\ndrop-in replacement yet. See `ROADMAP.md` for the unification plan.\n\nBoth bridges share a common JSONL core for protocol validation and timeouts.\n\nBy default, NodeBridge inherits only PATH/PYTHON*/TYWRAP\\_* from `process.env`\nto keep the subprocess environment minimal. Set `inheritProcessEnv: true` if you\nneed the full environment.\n\nYou can cap payload sizes with `TYWRAP_CODEC_MAX_BYTES` (responses) and\n`TYWRAP_REQUEST_MAX_BYTES` (requests) to keep JSONL traffic bounded.\n\n### Browser (Pyodide)\n\n```typescript\nimport { PyodideBridge } from 'tywrap/pyodide';\nconst bridge = new PyodideBridge({\n  indexURL: 'https://cdn.jsdelivr.net/pyodide/v0.28.0/full/',\n});\nawait bridge.init();\n```\n\n### Deno / Bun\n\n```typescript\nimport { NodeBridge } from 'npm:tywrap'; // Deno\nimport { NodeBridge } from 'tywrap'; // Bun\n```\n\n## Configuration\n\n```typescript\n// tywrap.config.ts\nimport { defineConfig } from 'tywrap';\n\nexport default defineConfig({\n  pythonModules: {\n    pandas: {\n      runtime: 'node',\n      typeHints: 'strict',\n      classes: ['DataFrame'],\n      functions: ['read_csv'],\n    },\n    numpy: {\n      runtime: 'node',\n      typeHints: 'strict',\n      alias: 'np',\n    },\n  },\n  output: { dir: './src/generated' },\n});\n```\n\nSee [Configuration Guide](https://bbopen.github.io/tywrap/guide/configuration)\nfor all options.\n\n## Supported Data Types\n\n| Python                                | TypeScript               | Notes            |\n| ------------------------------------- | ------------------------ | ---------------- |\n| `numpy.ndarray`                       | `Uint8Array` / `array`   | Arrow or JSON    |\n| `pandas.DataFrame`                    | Arrow Table / `object[]` | Arrow or JSON    |\n| `scipy.sparse.*`                      | `SparseMatrix`           | CSR, CSC, COO    |\n| `torch.Tensor`                        | `TorchTensor`            | CPU only         |\n| `sklearn estimator`                   | `SklearnEstimator`       | Params only      |\n| `datetime`, `Decimal`, `UUID`, `Path` | `string`                 | Standard formats |\n\nFor Arrow encoding with numpy/pandas:\n\n```typescript\nimport { registerArrowDecoder } from 'tywrap';\nimport { tableFromIPC } from 'apache-arrow';\nregisterArrowDecoder(bytes =\u003e tableFromIPC(bytes));\n```\n\n## Documentation\n\n- [Getting Started](https://bbopen.github.io/tywrap/guide/getting-started)\n- [Configuration](https://bbopen.github.io/tywrap/guide/configuration)\n- [API Reference](https://bbopen.github.io/tywrap/reference/api/)\n- [Troubleshooting](https://bbopen.github.io/tywrap/troubleshooting/)\n\n## Contributing\n\n```bash\nnpm install\nnpm test\n```\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT © [tywrap contributors](LICENSE)\n\n## Links\n\n- [GitHub](https://github.com/bbopen/tywrap)\n- [npm](https://www.npmjs.com/package/tywrap)\n- [PyPI](https://pypi.org/project/tywrap-ir/)\n- [Issues](https://github.com/bbopen/tywrap/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbopen%2Ftywrap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbopen%2Ftywrap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbopen%2Ftywrap/lists"}