# @tmlmobilidade/go-utils-import-gtfs 中文文档

规范地址：https://npmcn.com/package/%40tmlmobilidade/go-utils-import-gtfs/

版本：20261102\.1501\.57
npm 元数据更新时间：2026-11-02T15:21:42.707Z
中文译文更新时间：2026-11-02T17:02:51.201Z
软件包许可：AGPL-3\.0-or-later

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40tmlmobilidade/go-utils-import-gtfs
原文对照：https://npmcn.com/package/%40tmlmobilidade/go-utils-import-gtfs/?lang=original
项目主页：https://go.tmlmobilidade.pt/
源码仓库：https://github.com/tmlmobilidade/go

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：8.9 MB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2026-10-28T12:05:58.672Z
- 最新版本发布：2026-11-02T15:21:42.348Z
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

Go GTFS导入器的TypeScript包装器。将本地或远程ZIP导入SQLite并返回 `_db`， `calendar_dates`， `routes`， `shapes`， `stop_times`， `stops`, `trips`，无需GTFS验证。

## 安装

```sh
npm install @tmlmobilidade/go-utils-import-gtfs
```

也可以使用：`pnpm add @tmlmobilidade/go-utils-import-gtfs`、`yarn add @tmlmobilidade/go-utils-import-gtfs`、`bun add @tmlmobilidade/go-utils-import-gtfs`

## README

# 进口GTFS

Go GTFS导入器的TypeScript包装器。将本地或远程ZIP导入到 SQLite和返回 `_db`， `calendar_dates`， `routes`， `shapes`， `stop_times`， `stops`, `trips`，无需GTFS验证。

```ts
import { importGtfsToDatabase } from '@tmlmobilidade/go-utils-import-gtfs';

const gtfs = await importGtfsToDatabase({
    source: { path: './gtfs.zip' },
    sqlite_config: { memory: true },
});

try {
    console.log(gtfs.stops?.all());
    console.log(gtfs.trips?.get('trip_id', '001'));
} finally {
    gtfs._db.cleanup();
}
```

使用 `source: { url: 'https://example.com/gtfs.zip' }` 对于下载。可选 `sqlite_config` 接受 `instanceName`， `instancePath`, `memory`。活数据库 实例不能在进程之间传递。集 `sqlite_config: { memory: true }` 接收内存中的数据库； `instancePath` 被忽略并且没有数据库文件 被创建。Go通过stdout传输二进制SQLite图像，这是TypeScript 在内存中打开。这些进程之间不能共享内存地址。 传输将数据库副本暂时保存在内存中。使用相对路径 来电者的工作目录。

包装器将JSON直接传递给CLI，而不需要shell。导入错误拒绝 承诺与CLI的标准错误。遥测数据被转发给父节点 当它到达时，在文件和内存模式下。 `ENVIRONMENT=dev` 选择可读 日志;其他值生成OpenTelemetry JSON。

`_db` 是一个 `SQLiteDatabase`。每个表句柄都是一个 `SQLiteTableInstance` 与 `all`， `get`， `has`， `stream`，以及其他SQLite客户机方法。列是 从SQLite读取；空字段是 `null` 其他值仍然是字符串。 `calendar_dates` 是一个 `Record<string, OperationalDateInt[]>` 以服务ID为键， 包含不同数字日期的 `exception_type: '1'`。它是空的 不存在日历日期行。使用非空过滤器，这些都被解析为活动的 扩展周日历并应用例外情况后的服务日期。没有 那个过滤器，只显式添加自 `calendar_dates.txt` 包括; 周日历不扩展。原始日历行始终可用 `_db.databaseInstance`。缺失或空的源文件产生 `undefined` 表格 处理;仅头文件生成空表。 其他导入的GTFS表仍然可以通过 `_db.databaseInstance`.

传递一个完整的表束类型来保留每个表的行类型：

```ts
const gtfs = await importGtfsToDatabase<GtfsHubV1SQLTables>(config);
```

泛型描述返回的包，但不验证或转换行 值。丢失的表仍然返回 `undefined`，所以自定义包必须反映 由源存档保证的表。

可选 `time_range` 接受与遗留进口者相同的日期：

```ts
time_range: {
    date_range: {
        start: OperationalDateIntSchema.parse(20261001),
        end: OperationalDateIntSchema.parse(20261031),
    },
    discrete_dates: [OperationalDateIntSchema.parse(20261027)],
},
```

进口 `OperationalDateIntSchema` 从 `@tmlmobilidade/go-types-shared`. 范围包括两个端点。当两个过滤器都提供时，日期必须 两相匹配。一个省略的过滤器， `{}`，或一个空的 `discrete_dates` 数组进口 所有的日期。无效的配置日期或反转的范围拒绝导入。 非空过滤器展开 `calendar.txt` 工作日,适用 `calendar_dates.txt` 添加/删除，并保留具有选定活动日期的旅行。它只保留 参考停车时间、路线、形状和站点（包括母站）。 解析后的 `calendar_dates` 行有 `exception_type: '1'`； 导入的 `calendar` 桌子空了。保留自定义异常字段；生成每周 日期 `null` 定制字段。其他GTFS表和现有数据库行是 保留。省略或空过滤器保留原始导入行为。

调用者拥有数据库连接和任何输出文件。呼叫 `_db.cleanup()` 关闭 并释放其内存或删除其文件（包括自定义输出路径），或调用 `_db.databaseInstance.close()` 关闭连接并保留文件。

从存储库根目录，使用：

```sh
npx turbo run build --filter=@tmlmobilidade/go-utils-import-gtfs
npm run test --workspace=@tmlmobilidade/go-utils-import-gtfs
```

构建中包含Go命令行 `dist/bin/import-gtfs`； Go和C编译器是 在构建时需要。运行时不需要Go语言。生成的包必须 运行在与构建机器相同的操作系统和体系结构上。Go的工作空间是 命名 `@tmlmobilidade/go-golang-import-gtfs`.

## 常见问题

### @tmlmobilidade/go-utils-import-gtfs 是什么？

Go GTFS导入器的TypeScript包装器。将本地或远程ZIP导入SQLite并返回 \_db， calendar\_dates， routes， shapes， stop\_times， stops, trips，无需GTFS验证。

### 如何安装 @tmlmobilidade/go-utils-import-gtfs？

在项目目录运行 npm install @tmlmobilidade/go-utils-import-gtfs，或使用 pnpm add / yarn add / bun add。

### @tmlmobilidade/go-utils-import-gtfs 支持 TypeScript 吗？

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

### @tmlmobilidade/go-utils-import-gtfs 支持 ESM 还是 CommonJS？

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

### @tmlmobilidade/go-utils-import-gtfs 可以商用吗？

@tmlmobilidade/go-utils-import-gtfs 使用 AGPL-3\.0-or-later 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @tmlmobilidade/go-utils-import-gtfs 还在维护吗？

最新版本 20261102\.1501\.57 发布于 2026/11/02（今天）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/10/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。