udbx4ts 0.3.0

package/README.md

@@ -0,0 +1,250 @@
+# udbx4ts
+
+TypeScript UDBX runtime — 在 Web 浏览器和 Electron 中读写 UDBX 空间数据库。
+
+## 概述
+
+UDBX 是基于 SQLite 的空间数据库格式，兼容 SpatiaLite 的 GAIA 二进制几何编码。`udbx4ts` 提供纯 TypeScript 实现，支持：
+
+- **浏览器**：基于 sql.js (WASM) + OPFS，在 Web Worker 中运行
+- **Electron**：基于 better-sqlite3，在主进程中直接访问
+- **零外部依赖**（核心层），最小化打包体积
+
+## 功能
+
+| 功能 | 浏览器 | Electron |
+|------|--------|----------|
+| 打开/创建 UDBX 文件 | OPFS / 内存 | 本地文件 |
+| 数据集 CRUD | Point / Line / Region / Tabular / PointZ / LineZ / RegionZ / Cad | Point / Line / Region / Tabular / PointZ / LineZ / RegionZ / Cad |
+| 流式读取 (AsyncIterable) | 分页代理 | 原生流式 |
+| 批量写入 (prepared statement) | 支持 | 支持 |
+| 几何编解码 (GAIA) | Point / MultiLineString / MultiPolygon | Point / MultiLineString / MultiPolygon |
+
+## 安装
+
+```bash
+npm install udbx4ts
+```
+
+### 浏览器
+
+```typescript
+import { createBrowserUdbx } from "udbx4ts/web";
+```
+
+浏览器运行时需要 sql.js WASM，通过 `peerDependency` 声明。
+
+### Electron
+
+```typescript
+import { createElectronUdbx } from "udbx4ts/electron";
+```
+
+Electron 运行时需要 `better-sqlite3`，通过 `peerDependency` 声明。
+
+```bash
+npm install better-sqlite3
+```
+
+## 快速开始
+
+### 浏览器
+
+1. 创建 Web Worker 并安装运行时：
+
+```typescript
+// worker.ts
+import { installSqliteWasmWorkerRuntime } from "udbx4ts/web";
+
+installSqliteWasmWorkerRuntime(self, {
+  openTarget: {
+    opfsPath: "udbx/workspace.udbx",
+    memoryName: "udbx-fallback"
+  }
+});
+```
+
+2. 在主线程中使用：
+
+```typescript
+// main.ts
+import { createBrowserUdbx } from "udbx4ts/web";
+
+const worker = new Worker(new URL("./worker.ts", import.meta.url), { type: "module" });
+const ds = await createBrowserUdbx(worker, { kind: "memory" });
+
+// 创建点数据集
+const points = await ds.createPointDataset("cities", 4326, [
+  { name: "NAME", fieldType: "string", nullable: true }
+]);
+
+// 插入要素
+await points.insert({
+  id: 1,
+  geometry: { type: "Point", coordinates: [116.4, 39.9], srid: 4326 },
+  attributes: { NAME: "Beijing" }
+});
+
+// 查询
+const features = await points.list();
+for (const f of features) {
+  console.log(f.id, f.geometry.coordinates, f.attributes);
+}
+```
+
+### Electron
+
+```typescript
+// main process
+import { createElectronUdbx } from "udbx4ts/electron";
+
+// 打开已有文件
+const ds = await createElectronUdbx({ path: "/path/to/file.udbx" });
+
+// 或创建新文件
+const ds = await createElectronUdbx({ path: "/path/to/new.udbx" }); // 自动创建
+
+// 使用 API
+const datasets = await ds.listDatasets();
+const regions = await ds.createRegionDataset("parcels", 4326, [
+  { name: "AREA", fieldType: "double", nullable: true }
+]);
+```
+
+## API 概览
+
+### UdbxDataSource
+
+数据源入口，管理数据集的创建、打开和列举。
+
+```typescript
+interface UdbxDataSource {
+  listDatasets(): Promise<readonly DatasetInfo[]>;
+  getDataset(name: string): Promise<UdbxDataset>;
+  createPointDataset(name: string, srid: number, fields?: FieldInfo[]): Promise<PointDataset>;
+  createLineDataset(name: string, srid: number, fields?: FieldInfo[]): Promise<LineDataset>;
+  createRegionDataset(name: string, srid: number, fields?: FieldInfo[]): Promise<RegionDataset>;
+  createPointZDataset(name: string, srid: number, fields?: FieldInfo[]): Promise<PointZDataset>;
+  createLineZDataset(name: string, srid: number, fields?: FieldInfo[]): Promise<LineZDataset>;
+  createRegionZDataset(name: string, srid: number, fields?: FieldInfo[]): Promise<RegionZDataset>;
+  createCadDataset(name: string, srid: number, fields?: FieldInfo[]): Promise<CadDataset>;
+  createTabularDataset(name: string, fields?: FieldInfo[]): Promise<TabularDataset>;
+  close(): Promise<void>;
+}
+```
+
+### 数据集类型
+
+| 类型 | 几何 | Feature 类型 |
+|------|------|-------------|
+| `PointDataset` | Point (GAIA type 1) | `Feature<PointGeometry>` |
+| `LineDataset` | MultiLineString (GAIA type 5) | `Feature<MultiLineStringGeometry>` |
+| `RegionDataset` | MultiPolygon (GAIA type 6) | `Feature<MultiPolygonGeometry>` |
+| `PointZDataset` | Point Z (GAIA type 1 + Z) | `Feature<PointGeometry>` |
+| `LineZDataset` | MultiLineString Z (GAIA type 5 + Z) | `Feature<MultiLineStringGeometry>` |
+| `RegionZDataset` | MultiPolygon Z (GAIA type 6 + Z) | `Feature<MultiPolygonGeometry>` |
+| `CadDataset` | CAD Geometry | `Feature<CadGeometry>` |
+| `TabularDataset` | 无几何 | `TabularRecord` |
+
+### 数据集操作
+
+所有数据集支持：
+
+- `getById(id)` — 按 ID 查询单条记录
+- `list(options?)` — 列出记录（支持 limit/offset/filter）
+- `iterate(options?)` — 异步迭代器，流式读取
+- `insert(feature)` — 插入单条记录
+- `insertMany(features)` — 批量插入（使用 prepared statement 优化）
+- `getFields()` — 获取字段元信息
+- `count()` — 获取记录总数
+- `update(id, changes)` — 更新记录（所有数据集类型均支持）
+- `delete(id)` — 删除记录（所有数据集类型均支持）
+
+### 几何类型
+
+```typescript
+interface PointGeometry {
+  type: "Point";
+  coordinates: [number, number] | [number, number, number];
+}
+
+interface MultiLineStringGeometry {
+  type: "MultiLineString";
+  coordinates: [number, number][][] | [number, number, number][][];
+}
+
+interface MultiPolygonGeometry {
+  type: "MultiPolygon";
+  coordinates: [number, number][][][] | [number, number, number][][][];
+}
+```
+
+### 字段类型
+
+```typescript
+type FieldType = "boolean" | "byte" | "int16" | "int32" | "int64" | "single" | "double" | "date" | "time" | "datetime" | "binary" | "text" | "ntext" | "geometry";
+
+interface FieldInfo {
+  name: string;
+  fieldType: FieldType;
+  nullable: boolean;
+  defaultValue?: unknown;
+}
+```
+
+## 示例
+
+- [`examples/browser/`](./examples/browser/) — 浏览器示例（Vite + Web Worker）
+- [`examples/electron/`](./examples/electron/) — Electron 示例（主进程 + IPC）
+
+## 开发
+
+```bash
+# 安装依赖
+pnpm install
+
+# 运行测试（99 tests）
+pnpm test
+
+# 类型检查
+pnpm typecheck
+
+# 构建
+pnpm build
+
+# 浏览器示例
+pnpm dev:browser
+
+# Electron 示例
+cd examples/electron && npm start
+```
+
+## 架构
+
+```
+src/
+├── core/                    # 核心层（运行时无关）
+│   ├── dataset/             # 数据集实现（Point/Line/Region/Tabular）
+│   ├── datasource/          # UdbxDataSource 入口
+│   ├── geometry/gaia/       # GAIA 二进制编解码
+│   ├── schema/              # UDBX 元数据表（SmRegister/SmFieldInfo）
+│   ├── sql/                 # SqlDriver 接口 + SQL helpers
+│   └── types/               # 类型定义
+├── shared-runtime/          # 共享 RPC 协议
+├── runtime-browser/         # 浏览器运行时（sql.js + OPFS + Worker）
+└── runtime-electron/        # Electron 运行时（better-sqlite3）
+```
+
+## License
+
+Private
+
+## udbx4spec 规范合规
+
+本项目严格遵循 `udbx4spec/` 中定义的跨语言规范。关键约束：
+
+- **API 命名**：所有公开 API 必须与 `udbx4spec/docs/01-naming-conventions.md` 对齐
+- **数据模型**：几何模型必须符合 `udbx4spec/docs/02-geometry-model.md`
+- **数据集类型**：`DatasetKind` 枚举值必须与 `udbx4spec/docs/03-dataset-taxonomy.md` 同步
+- **字段类型**：`FieldType` 枚举值必须与 `udbx4spec/docs/04-field-taxonomy.md` 同步（14 种）
+- **变更流程**：任何 API 变更、新增数据集类型或字段类型，必须先在 udbx4spec 中定义，然后在各语言实现中同步

package/dist/UdbxDataSource-dOqTLN6v.d.cts

@@ -0,0 +1,387 @@
+type DatasetKind = "point" | "line" | "region" | "tabular" | "pointZ" | "lineZ" | "regionZ" | "text" | "cad";
+
+interface DatasetInfo {
+    readonly id: number;
+    readonly name: string;
+    readonly kind: DatasetKind;
+    readonly tableName: string;
+    readonly srid: number | null;
+    readonly objectCount: number;
+    readonly geometryType: number | null;
+}
+
+interface GeometryBase {
+    readonly srid?: number;
+    readonly bbox?: readonly [number, number, number, number];
+    readonly hasZ?: boolean;
+    readonly geoType?: number;
+}
+interface PointGeometry extends GeometryBase {
+    readonly type: "Point";
+    readonly coordinates: [number, number] | [number, number, number];
+}
+interface MultiLineStringGeometry extends GeometryBase {
+    readonly type: "MultiLineString";
+    readonly coordinates: ReadonlyArray<ReadonlyArray<readonly [number, number]>> | ReadonlyArray<ReadonlyArray<readonly [number, number, number]>>;
+}
+interface MultiPolygonGeometry extends GeometryBase {
+    readonly type: "MultiPolygon";
+    readonly coordinates: ReadonlyArray<ReadonlyArray<ReadonlyArray<readonly [number, number]>>> | ReadonlyArray<ReadonlyArray<ReadonlyArray<readonly [number, number, number]>>>;
+}
+interface CadGeometry extends GeometryBase {
+    readonly type: "Cad";
+    readonly coordinates: readonly number[];
+}
+interface TextGeometry extends GeometryBase {
+    readonly type: "Text";
+    readonly text: string;
+    readonly x: number;
+    readonly y: number;
+    readonly rotation?: number;
+}
+type Geometry = PointGeometry | MultiLineStringGeometry | MultiPolygonGeometry | CadGeometry | TextGeometry;
+
+interface Feature<TGeometry extends Geometry = Geometry, TAttributes extends Record<string, unknown> = Record<string, unknown>> {
+    readonly id: number;
+    readonly geometry: TGeometry;
+    readonly attributes: TAttributes;
+}
+
+type FieldType = "boolean" | "byte" | "int16" | "int32" | "int64" | "single" | "double" | "date" | "binary" | "geometry" | "char" | "ntext" | "text" | "time";
+
+interface FieldInfo {
+    readonly name: string;
+    readonly fieldType: FieldType;
+    readonly alias?: string;
+    readonly required?: boolean;
+    readonly nullable?: boolean;
+    readonly defaultValue?: unknown;
+}
+
+interface QueryOptions {
+    readonly ids?: readonly number[];
+    readonly limit?: number;
+    readonly offset?: number;
+}
+
+interface TabularRecord<TAttributes extends Record<string, unknown> = Record<string, unknown>> {
+    readonly id: number;
+    readonly attributes: TAttributes;
+}
+
+type SqlValue = null | string | number | bigint | Uint8Array | ArrayBuffer;
+type SqlOpenTarget = {
+    readonly kind: "file";
+    readonly path: string;
+} | {
+    readonly kind: "buffer";
+    readonly data: Uint8Array;
+} | {
+    readonly kind: "opfs";
+    readonly path: string;
+} | {
+    readonly kind: "memory";
+    readonly name?: string;
+};
+interface SqlStatement {
+    bind(params?: readonly SqlValue[]): Promise<void>;
+    step(): Promise<boolean>;
+    getRow<T = Record<string, unknown>>(): Promise<T>;
+    reset(): Promise<void>;
+    finalize(): Promise<void>;
+}
+interface SqlDriver {
+    open(target: SqlOpenTarget): Promise<void>;
+    close(): Promise<void>;
+    exec(sql: string): Promise<void>;
+    prepare(sql: string): Promise<SqlStatement>;
+    transaction<T>(operation: () => Promise<T>): Promise<T>;
+}
+
+declare class SmFieldInfoRepository {
+    private readonly driver;
+    constructor(driver: SqlDriver);
+    findByDatasetId(datasetId: number): Promise<readonly FieldInfo[]>;
+    insertAll(datasetId: number, fields: readonly FieldInfo[]): Promise<void>;
+}
+
+interface Dataset {
+    readonly info: DatasetInfo;
+    getFields(): Promise<readonly FieldInfo[]>;
+}
+interface ReadableDataset<TFeature extends Feature = Feature> extends Dataset {
+    getById(id: number): Promise<TFeature | null>;
+    list(options?: QueryOptions): Promise<readonly TFeature[]>;
+    iterate(options?: QueryOptions): AsyncIterable<TFeature>;
+    count(): Promise<number>;
+}
+interface WritableDataset<TFeature extends Feature = Feature> extends ReadableDataset<TFeature> {
+    insert(feature: TFeature): Promise<void>;
+    insertMany(features: Iterable<TFeature> | AsyncIterable<TFeature>): Promise<void>;
+    update(id: number, changes: {
+        geometry?: TFeature["geometry"];
+        attributes?: Partial<TFeature["attributes"]>;
+    }): Promise<void>;
+    delete(id: number): Promise<void>;
+}
+
+declare abstract class BaseDataset implements Dataset {
+    protected readonly driver: SqlDriver;
+    readonly info: DatasetInfo;
+    protected readonly fieldInfoRepository: SmFieldInfoRepository;
+    constructor(driver: SqlDriver, info: DatasetInfo);
+    getFields(): Promise<readonly FieldInfo[]>;
+}
+
+type CadFeature<TAttributes extends Record<string, unknown> = Record<string, unknown>> = {
+    readonly id: number;
+    readonly geometry: CadGeometry;
+    readonly attributes: TAttributes;
+};
+declare class CadDataset<TAttributes extends Record<string, unknown> = Record<string, unknown>> extends BaseDataset implements WritableDataset<CadFeature<TAttributes>> {
+    getById(): Promise<CadFeature<TAttributes> | null>;
+    list(): Promise<readonly CadFeature<TAttributes>[]>;
+    iterate(): AsyncIterable<CadFeature<TAttributes>>;
+    count(): Promise<number>;
+    insert(): Promise<void>;
+    insertMany(): Promise<void>;
+    update(): Promise<void>;
+    delete(): Promise<void>;
+}
+
+declare class SmRegisterRepository {
+    private readonly driver;
+    constructor(driver: SqlDriver);
+    findAll(): Promise<readonly DatasetInfo[]>;
+    findByName(name: string): Promise<DatasetInfo | null>;
+    nextDatasetId(): Promise<number>;
+    insert(params: {
+        readonly name: string;
+        readonly kind: DatasetKind;
+        readonly srid: number;
+        readonly idColumnName: string;
+        readonly geometryColumnName: string | null;
+    }): Promise<number>;
+    incrementObjectCount(datasetId: number, geometrySize?: number): Promise<void>;
+    incrementObjectCountBatch(datasetId: number, count: number, maxGeometrySize: number): Promise<void>;
+    decrementObjectCount(datasetId: number): Promise<void>;
+}
+
+type LineFeature<TAttributes extends Record<string, unknown> = Record<string, unknown>> = Feature<MultiLineStringGeometry, TAttributes>;
+declare class LineDataset<TAttributes extends Record<string, unknown> = Record<string, unknown>> extends BaseDataset implements WritableDataset<LineFeature<TAttributes>> {
+    private readonly registerRepository;
+    constructor(driver: SqlDriver, info: DatasetInfo);
+    getById(id: number): Promise<LineFeature<TAttributes> | null>;
+    list(options?: QueryOptions): Promise<readonly LineFeature<TAttributes>[]>;
+    iterate(options?: QueryOptions): AsyncIterable<LineFeature<TAttributes>>;
+    insert(feature: LineFeature<TAttributes>): Promise<void>;
+    insertMany(features: Iterable<LineFeature<TAttributes>> | AsyncIterable<LineFeature<TAttributes>>): Promise<void>;
+    count(): Promise<number>;
+    update(id: number, changes: {
+        geometry?: MultiLineStringGeometry;
+        attributes?: Partial<TAttributes>;
+    }): Promise<void>;
+    delete(id: number): Promise<void>;
+    static create(driver: SqlDriver, registerRepository: SmRegisterRepository, params: {
+        readonly name: string;
+        readonly srid: number;
+        readonly fields?: readonly FieldInfo[];
+    }): Promise<LineDataset>;
+}
+
+type LineZFeature<TAttributes extends Record<string, unknown> = Record<string, unknown>> = Feature<MultiLineStringGeometry, TAttributes>;
+declare class LineZDataset<TAttributes extends Record<string, unknown> = Record<string, unknown>> extends BaseDataset implements WritableDataset<LineZFeature<TAttributes>> {
+    private readonly registerRepository;
+    constructor(driver: SqlDriver, info: DatasetInfo);
+    getById(id: number): Promise<LineZFeature<TAttributes> | null>;
+    list(options?: QueryOptions): Promise<readonly LineZFeature<TAttributes>[]>;
+    iterate(options?: QueryOptions): AsyncIterable<LineZFeature<TAttributes>>;
+    count(): Promise<number>;
+    insert(feature: LineZFeature<TAttributes>): Promise<void>;
+    insertMany(features: Iterable<LineZFeature<TAttributes>> | AsyncIterable<LineZFeature<TAttributes>>): Promise<void>;
+    update(id: number, changes: {
+        geometry?: MultiLineStringGeometry;
+        attributes?: Partial<TAttributes>;
+    }): Promise<void>;
+    delete(id: number): Promise<void>;
+    static create(driver: SqlDriver, registerRepository: SmRegisterRepository, params: {
+        readonly name: string;
+        readonly srid: number;
+        readonly fields?: readonly FieldInfo[];
+    }): Promise<LineZDataset>;
+}
+
+type PointFeature<TAttributes extends Record<string, unknown> = Record<string, unknown>> = Feature<PointGeometry, TAttributes>;
+declare class PointDataset<TAttributes extends Record<string, unknown> = Record<string, unknown>> extends BaseDataset implements WritableDataset<PointFeature<TAttributes>> {
+    private readonly registerRepository;
+    constructor(driver: SqlDriver, info: DatasetInfo);
+    getById(id: number): Promise<PointFeature<TAttributes> | null>;
+    list(options?: QueryOptions): Promise<readonly PointFeature<TAttributes>[]>;
+    iterate(options?: QueryOptions): AsyncIterable<PointFeature<TAttributes>>;
+    insert(feature: PointFeature<TAttributes>): Promise<void>;
+    insertMany(features: Iterable<PointFeature<TAttributes>> | AsyncIterable<PointFeature<TAttributes>>): Promise<void>;
+    count(): Promise<number>;
+    update(id: number, changes: {
+        geometry?: PointGeometry;
+        attributes?: Partial<TAttributes>;
+    }): Promise<void>;
+    delete(id: number): Promise<void>;
+    static create(driver: SqlDriver, registerRepository: SmRegisterRepository, params: {
+        readonly name: string;
+        readonly srid: number;
+        readonly fields?: readonly FieldInfo[];
+    }): Promise<PointDataset>;
+}
+
+type PointZFeature<TAttributes extends Record<string, unknown> = Record<string, unknown>> = Feature<PointGeometry, TAttributes>;
+declare class PointZDataset<TAttributes extends Record<string, unknown> = Record<string, unknown>> extends BaseDataset implements WritableDataset<PointZFeature<TAttributes>> {
+    private readonly registerRepository;
+    constructor(driver: SqlDriver, info: DatasetInfo);
+    getById(id: number): Promise<PointZFeature<TAttributes> | null>;
+    list(options?: QueryOptions): Promise<readonly PointZFeature<TAttributes>[]>;
+    iterate(options?: QueryOptions): AsyncIterable<PointZFeature<TAttributes>>;
+    count(): Promise<number>;
+    insert(feature: PointZFeature<TAttributes>): Promise<void>;
+    insertMany(features: Iterable<PointZFeature<TAttributes>> | AsyncIterable<PointZFeature<TAttributes>>): Promise<void>;
+    update(id: number, changes: {
+        geometry?: PointGeometry;
+        attributes?: Partial<TAttributes>;
+    }): Promise<void>;
+    delete(id: number): Promise<void>;
+    static create(driver: SqlDriver, registerRepository: SmRegisterRepository, params: {
+        readonly name: string;
+        readonly srid: number;
+        readonly fields?: readonly FieldInfo[];
+    }): Promise<PointZDataset>;
+}
+
+type RegionFeature<TAttributes extends Record<string, unknown> = Record<string, unknown>> = Feature<MultiPolygonGeometry, TAttributes>;
+declare class RegionDataset<TAttributes extends Record<string, unknown> = Record<string, unknown>> extends BaseDataset implements WritableDataset<RegionFeature<TAttributes>> {
+    private readonly registerRepository;
+    constructor(driver: SqlDriver, info: DatasetInfo);
+    getById(id: number): Promise<RegionFeature<TAttributes> | null>;
+    list(options?: QueryOptions): Promise<readonly RegionFeature<TAttributes>[]>;
+    iterate(options?: QueryOptions): AsyncIterable<RegionFeature<TAttributes>>;
+    insert(feature: RegionFeature<TAttributes>): Promise<void>;
+    insertMany(features: Iterable<RegionFeature<TAttributes>> | AsyncIterable<RegionFeature<TAttributes>>): Promise<void>;
+    count(): Promise<number>;
+    update(id: number, changes: {
+        geometry?: MultiPolygonGeometry;
+        attributes?: Partial<TAttributes>;
+    }): Promise<void>;
+    delete(id: number): Promise<void>;
+    static create(driver: SqlDriver, registerRepository: SmRegisterRepository, params: {
+        readonly name: string;
+        readonly srid: number;
+        readonly fields?: readonly FieldInfo[];
+    }): Promise<RegionDataset>;
+}
+
+type RegionZFeature<TAttributes extends Record<string, unknown> = Record<string, unknown>> = Feature<MultiPolygonGeometry, TAttributes>;
+declare class RegionZDataset<TAttributes extends Record<string, unknown> = Record<string, unknown>> extends BaseDataset implements WritableDataset<RegionZFeature<TAttributes>> {
+    private readonly registerRepository;
+    constructor(driver: SqlDriver, info: DatasetInfo);
+    getById(id: number): Promise<RegionZFeature<TAttributes> | null>;
+    list(options?: QueryOptions): Promise<readonly RegionZFeature<TAttributes>[]>;
+    iterate(options?: QueryOptions): AsyncIterable<RegionZFeature<TAttributes>>;
+    count(): Promise<number>;
+    insert(feature: RegionZFeature<TAttributes>): Promise<void>;
+    insertMany(features: Iterable<RegionZFeature<TAttributes>> | AsyncIterable<RegionZFeature<TAttributes>>): Promise<void>;
+    update(id: number, changes: {
+        geometry?: MultiPolygonGeometry;
+        attributes?: Partial<TAttributes>;
+    }): Promise<void>;
+    delete(id: number): Promise<void>;
+    static create(driver: SqlDriver, registerRepository: SmRegisterRepository, params: {
+        readonly name: string;
+        readonly srid: number;
+        readonly fields?: readonly FieldInfo[];
+    }): Promise<RegionZDataset>;
+}
+
+interface TabularDatasetReadable {
+    readonly info: DatasetInfo;
+    getFields(): Promise<readonly FieldInfo[]>;
+    getById(id: number): Promise<TabularRecord | null>;
+    list(options?: QueryOptions): Promise<readonly TabularRecord[]>;
+    iterate(options?: QueryOptions): AsyncIterable<TabularRecord>;
+    count(): Promise<number>;
+}
+interface TabularDatasetWritable extends TabularDatasetReadable {
+    insert(record: TabularRecord): Promise<void>;
+    insertMany(records: Iterable<TabularRecord> | AsyncIterable<TabularRecord>): Promise<void>;
+    update(id: number, attributes: Record<string, unknown>): Promise<void>;
+    delete(id: number): Promise<void>;
+}
+declare class TabularDataset<TAttributes extends Record<string, unknown> = Record<string, unknown>> extends BaseDataset implements TabularDatasetWritable {
+    private readonly registerRepository;
+    constructor(driver: SqlDriver, info: DatasetInfo);
+    getById(id: number): Promise<TabularRecord<TAttributes> | null>;
+    list(options?: QueryOptions): Promise<readonly TabularRecord<TAttributes>[]>;
+    iterate(options?: QueryOptions): AsyncIterable<TabularRecord<TAttributes>>;
+    count(): Promise<number>;
+    insert(record: TabularRecord<TAttributes>): Promise<void>;
+    insertMany(records: Iterable<TabularRecord<TAttributes>> | AsyncIterable<TabularRecord<TAttributes>>): Promise<void>;
+    update(id: number, attributes: Record<string, unknown>): Promise<void>;
+    delete(id: number): Promise<void>;
+    static create(driver: SqlDriver, registerRepository: SmRegisterRepository, params: {
+        readonly name: string;
+        readonly fields?: readonly FieldInfo[];
+    }): Promise<TabularDataset>;
+}
+
+type TextFeature<TAttributes extends Record<string, unknown> = Record<string, unknown>> = {
+    readonly id: number;
+    readonly geometry: TextGeometry;
+    readonly attributes: TAttributes;
+};
+/**
+ * 文本数据集实现（DatasetKind="text"）。
+ *
+ * <p>对应白皮书 §3.1.5（文本数据集）。
+ *
+ * <p><b>TODO:</b> GeoText 二进制编解码器待实现。
+ */
+declare class TextDataset<TAttributes extends Record<string, unknown> = Record<string, unknown>> extends BaseDataset implements WritableDataset<TextFeature<TAttributes>> {
+    getById(): Promise<TextFeature<TAttributes> | null>;
+    list(_options?: QueryOptions): Promise<readonly TextFeature<TAttributes>[]>;
+    iterate(_options?: QueryOptions): AsyncIterable<TextFeature<TAttributes>>;
+    count(): Promise<number>;
+    insert(): Promise<void>;
+    insertMany(): Promise<void>;
+    update(): Promise<void>;
+    delete(): Promise<void>;
+}
+
+type UdbxRuntime = "browser" | "electron" | "unknown";
+type UdbxDataset = PointDataset | PointZDataset | LineDataset | LineZDataset | RegionDataset | RegionZDataset | TabularDataset | TextDataset | CadDataset;
+declare class UdbxDataSource {
+    private readonly driver;
+    readonly runtime: UdbxRuntime;
+    private readonly registerRepository;
+    constructor(driver: SqlDriver, runtime?: UdbxRuntime);
+    static open(params: {
+        readonly driver: SqlDriver;
+        readonly target: SqlOpenTarget;
+        readonly runtime?: UdbxRuntime;
+    }): Promise<UdbxDataSource>;
+    static create(params: {
+        readonly driver: SqlDriver;
+        readonly target: SqlOpenTarget;
+        readonly runtime?: UdbxRuntime;
+    }): Promise<UdbxDataSource>;
+    listDatasets(): Promise<readonly DatasetInfo[]>;
+    getDataset(name: string): Promise<UdbxDataset | null>;
+    createPointDataset(name: string, srid: number, fields?: readonly FieldInfo[]): Promise<PointDataset>;
+    createLineDataset(name: string, srid: number, fields?: readonly FieldInfo[]): Promise<LineDataset>;
+    createRegionDataset(name: string, srid: number, fields?: readonly FieldInfo[]): Promise<RegionDataset>;
+    createPointZDataset(name: string, srid: number, fields?: readonly FieldInfo[]): Promise<PointZDataset>;
+    createLineZDataset(name: string, srid: number, fields?: readonly FieldInfo[]): Promise<LineZDataset>;
+    createRegionZDataset(name: string, srid: number, fields?: readonly FieldInfo[]): Promise<RegionZDataset>;
+    createTabularDataset(name: string, fields?: readonly FieldInfo[]): Promise<TabularDataset>;
+    createTextDataset(name: string, srid: number, fields?: readonly FieldInfo[]): Promise<TextDataset>;
+    createCadDataset(name: string, fields?: readonly FieldInfo[]): Promise<CadDataset>;
+    close(): Promise<void>;
+}
+
+export { type TabularRecord as A, BaseDataset as B, CadDataset as C, type DatasetKind as D, TextDataset as E, type FieldType as F, type Geometry as G, type TextFeature as H, type TextGeometry as I, type UdbxDataset as J, type UdbxRuntime as K, LineDataset as L, type MultiLineStringGeometry as M, type PointGeometry as P, type QueryOptions as Q, type ReadableDataset as R, type SqlDriver as S, TabularDataset as T, UdbxDataSource as U, type WritableDataset as W, type MultiPolygonGeometry as a, type CadFeature as b, type CadGeometry as c, type Dataset as d, type DatasetInfo as e, type Feature as f, type FieldInfo as g, type GeometryBase as h, type LineFeature as i, LineZDataset as j, type LineZFeature as k, PointDataset as l, type PointFeature as m, PointZDataset as n, type PointZFeature as o, RegionDataset as p, type RegionFeature as q, RegionZDataset as r, type RegionZFeature as s, SmFieldInfoRepository as t, SmRegisterRepository as u, type SqlOpenTarget as v, type SqlStatement as w, type SqlValue as x, type TabularDatasetReadable as y, type TabularDatasetWritable as z };