{"id":48109928,"url":"https://github.com/zhyt1985/udbx4ts","last_synced_at":"2026-04-04T16:02:44.285Z","repository":{"id":348077119,"uuid":"1192240452","full_name":"zhyt1985/udbx4ts","owner":"zhyt1985","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-30T17:02:05.000Z","size":127,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T19:05:05.037Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhyt1985.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-26T02:53:19.000Z","updated_at":"2026-03-30T17:02:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zhyt1985/udbx4ts","commit_stats":null,"previous_names":["zhyt1985/udbx4ts"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/zhyt1985/udbx4ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhyt1985%2Fudbx4ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhyt1985%2Fudbx4ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhyt1985%2Fudbx4ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhyt1985%2Fudbx4ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhyt1985","download_url":"https://codeload.github.com/zhyt1985/udbx4ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhyt1985%2Fudbx4ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31405224,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-04-04T16:02:17.097Z","updated_at":"2026-04-04T16:02:44.237Z","avatar_url":"https://github.com/zhyt1985.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# udbx4ts\n\nTypeScript UDBX runtime — 在 Web 浏览器和 Electron 中读写 UDBX 空间数据库。\n\n## 概述\n\nUDBX 是基于 SQLite 的空间数据库格式，兼容 SpatiaLite 的 GAIA 二进制几何编码。`udbx4ts` 提供纯 TypeScript 实现，支持：\n\n- **浏览器**：基于 sql.js (WASM) + OPFS，在 Web Worker 中运行\n- **Electron**：基于 better-sqlite3，在主进程中直接访问\n- **零外部依赖**（核心层），最小化打包体积\n\n## 功能\n\n| 功能 | 浏览器 | Electron |\n|------|--------|----------|\n| 打开/创建 UDBX 文件 | OPFS / 内存 | 本地文件 |\n| 数据集 CRUD | Point / Line / Region / Tabular | Point / Line / Region / Tabular |\n| 流式读取 (AsyncIterable) | 分页代理 | 原生流式 |\n| 批量写入 (prepared statement) | 支持 | 支持 |\n| 几何编解码 (GAIA) | Point / MultiLineString / MultiPolygon | Point / MultiLineString / MultiPolygon |\n\n## 安装\n\n```bash\nnpm install udbx4ts\n```\n\n### 浏览器\n\n```typescript\nimport { createBrowserUdbx } from \"udbx4ts/web\";\n```\n\n浏览器运行时需要 sql.js WASM，通过 `peerDependency` 声明。\n\n### Electron\n\n```typescript\nimport { createElectronUdbx } from \"udbx4ts/electron\";\n```\n\nElectron 运行时需要 `better-sqlite3`，通过 `peerDependency` 声明。\n\n```bash\nnpm install better-sqlite3\n```\n\n## 快速开始\n\n### 浏览器\n\n1. 创建 Web Worker 并安装运行时：\n\n```typescript\n// worker.ts\nimport { installSqliteWasmWorkerRuntime } from \"udbx4ts/web\";\n\ninstallSqliteWasmWorkerRuntime(self, {\n  openTarget: {\n    opfsPath: \"udbx/workspace.udbx\",\n    memoryName: \"udbx-fallback\"\n  }\n});\n```\n\n2. 在主线程中使用：\n\n```typescript\n// main.ts\nimport { createBrowserUdbx } from \"udbx4ts/web\";\n\nconst worker = new Worker(new URL(\"./worker.ts\", import.meta.url), { type: \"module\" });\nconst ds = await createBrowserUdbx(worker, { kind: \"memory\" });\n\n// 创建点数据集\nconst points = await ds.createPointDataset(\"cities\", 4326, [\n  { name: \"NAME\", fieldType: \"string\", nullable: true }\n]);\n\n// 插入要素\nawait points.insert({\n  id: 1,\n  geometry: { type: \"Point\", coordinates: [116.4, 39.9], srid: 4326 },\n  attributes: { NAME: \"Beijing\" }\n});\n\n// 查询\nconst features = await points.list();\nfor (const f of features) {\n  console.log(f.id, f.geometry.coordinates, f.attributes);\n}\n```\n\n### Electron\n\n```typescript\n// main process\nimport { createElectronUdbx } from \"udbx4ts/electron\";\n\n// 打开已有文件\nconst ds = await createElectronUdbx({ path: \"/path/to/file.udbx\" });\n\n// 或创建新文件\nconst ds = await createElectronUdbx({ path: \"/path/to/new.udbx\" }); // 自动创建\n\n// 使用 API\nconst datasets = await ds.listDatasets();\nconst regions = await ds.createRegionDataset(\"parcels\", 4326, [\n  { name: \"AREA\", fieldType: \"double\", nullable: true }\n]);\n```\n\n## API 概览\n\n### UdbxDataSource\n\n数据源入口，管理数据集的创建、打开和列举。\n\n```typescript\ninterface UdbxDataSource {\n  listDatasets(): Promise\u003creadonly DatasetInfo[]\u003e;\n  getDataset(name: string): Promise\u003cUdbxDataset\u003e;\n  createPointDataset(name: string, srid: number, fields?: FieldInfo[]): Promise\u003cPointDataset\u003e;\n  createLineDataset(name: string, srid: number, fields?: FieldInfo[]): Promise\u003cLineDataset\u003e;\n  createRegionDataset(name: string, srid: number, fields?: FieldInfo[]): Promise\u003cRegionDataset\u003e;\n  createTabularDataset(name: string, fields?: FieldInfo[]): Promise\u003cTabularDataset\u003e;\n  close(): Promise\u003cvoid\u003e;\n}\n```\n\n### 数据集类型\n\n| 类型 | 几何 | Feature 类型 |\n|------|------|-------------|\n| `PointDataset` | Point (GAIA type 1) | `Feature\u003cPointGeometry\u003e` |\n| `LineDataset` | MultiLineString (GAIA type 5) | `Feature\u003cMultiLineStringGeometry\u003e` |\n| `RegionDataset` | MultiPolygon (GAIA type 6) | `Feature\u003cMultiPolygonGeometry\u003e` |\n| `TabularDataset` | 无几何 | `TabularRecord` |\n\n### 数据集操作\n\n所有数据集支持：\n\n- `getById(id)` — 按 ID 查询单条记录\n- `list(options?)` — 列出记录（支持 limit/offset/filter）\n- `iterate(options?)` — 异步迭代器，流式读取\n- `insert(feature)` — 插入单条记录\n- `insertMany(features)` — 批量插入（使用 prepared statement 优化）\n- `getFields()` — 获取字段元信息\n\n`TabularDataset` 额外支持：\n\n- `update(id, attributes)` — 更新属性\n- `delete(id)` — 删除记录\n\n### 几何类型\n\n```typescript\ninterface PointGeometry {\n  type: \"Point\";\n  coordinates: [number, number] | [number, number, number];\n}\n\ninterface MultiLineStringGeometry {\n  type: \"MultiLineString\";\n  coordinates: [number, number][][] | [number, number, number][][];\n}\n\ninterface MultiPolygonGeometry {\n  type: \"MultiPolygon\";\n  coordinates: [number, number][][][] | [number, number, number][][][];\n}\n```\n\n### 字段类型\n\n```typescript\ntype FieldType = \"boolean\" | \"int16\" | \"int32\" | \"int64\" | \"float\" | \"double\" | \"date\" | \"binary\" | \"string\";\n\ninterface FieldInfo {\n  name: string;\n  fieldType: FieldType;\n  nullable: boolean;\n  defaultValue?: unknown;\n}\n```\n\n## 示例\n\n- [`examples/browser/`](./examples/browser/) — 浏览器示例（Vite + Web Worker）\n- [`examples/electron/`](./examples/electron/) — Electron 示例（主进程 + IPC）\n\n## 开发\n\n```bash\n# 安装依赖\npnpm install\n\n# 运行测试（99 tests）\npnpm test\n\n# 类型检查\npnpm typecheck\n\n# 构建\npnpm build\n\n# 浏览器示例\npnpm dev:browser\n\n# Electron 示例\ncd examples/electron \u0026\u0026 npm start\n```\n\n## 架构\n\n```\nsrc/\n├── core/                    # 核心层（运行时无关）\n│   ├── dataset/             # 数据集实现（Point/Line/Region/Tabular）\n│   ├── datasource/          # UdbxDataSource 入口\n│   ├── geometry/gaia/       # GAIA 二进制编解码\n│   ├── schema/              # UDBX 元数据表（SmRegister/SmFieldInfo）\n│   ├── sql/                 # SqlDriver 接口 + SQL helpers\n│   └── types/               # 类型定义\n├── shared-runtime/          # 共享 RPC 协议\n├── runtime-browser/         # 浏览器运行时（sql.js + OPFS + Worker）\n└── runtime-electron/        # Electron 运行时（better-sqlite3）\n```\n\n## License\n\nPrivate\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhyt1985%2Fudbx4ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhyt1985%2Fudbx4ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhyt1985%2Fudbx4ts/lists"}