gtfs 4.18.3 → 4.18.5

package/dist/index.js

@@ -4064,7 +4064,8 @@ async function unzip(zipfilePath, exportPath) {
     await zip.close();
   } catch (error) {
     throw new Error(
-      `Failed to extract zip file: ${error instanceof Error ? error.message : "Unknown error"}`
+      `Failed to extract zip file: ${error instanceof Error ? error.message : "Unknown error"}`,
+      { cause: error }
     );
   }
 }
@@ -4078,6 +4079,104 @@ function untildify(pathWithTilde) {
   return homeDirectory ? pathWithTilde.replace(/^~(?=$|\/|\\)/, homeDirectory) : pathWithTilde;
 }
 
+// src/lib/errors.ts
+var GtfsErrorCategory = /* @__PURE__ */ ((GtfsErrorCategory2) => {
+  GtfsErrorCategory2["CONFIG"] = "config";
+  GtfsErrorCategory2["DOWNLOAD"] = "download";
+  GtfsErrorCategory2["ZIP"] = "zip";
+  GtfsErrorCategory2["VALIDATION"] = "validation";
+  GtfsErrorCategory2["DATABASE"] = "database";
+  GtfsErrorCategory2["PARSE"] = "parse";
+  GtfsErrorCategory2["QUERY"] = "query";
+  GtfsErrorCategory2["INTERNAL"] = "internal";
+  return GtfsErrorCategory2;
+})(GtfsErrorCategory || {});
+var GtfsErrorCode = /* @__PURE__ */ ((GtfsErrorCode2) => {
+  GtfsErrorCode2["GTFS_DOWNLOAD_HTTP"] = "GTFS_DOWNLOAD_HTTP";
+  GtfsErrorCode2["GTFS_DOWNLOAD_FAILED"] = "GTFS_DOWNLOAD_FAILED";
+  GtfsErrorCode2["GTFS_ZIP_INVALID"] = "GTFS_ZIP_INVALID";
+  GtfsErrorCode2["GTFS_REQUIRED_FIELD_MISSING"] = "GTFS_REQUIRED_FIELD_MISSING";
+  GtfsErrorCode2["GTFS_INVALID_DATE"] = "GTFS_INVALID_DATE";
+  GtfsErrorCode2["GTFS_CONFIG_INVALID"] = "GTFS_CONFIG_INVALID";
+  GtfsErrorCode2["DB_OPEN_FAILED"] = "DB_OPEN_FAILED";
+  GtfsErrorCode2["GTFS_DB_OPERATION_FAILED"] = "GTFS_DB_OPERATION_FAILED";
+  GtfsErrorCode2["GTFS_JSON_INVALID"] = "GTFS_JSON_INVALID";
+  GtfsErrorCode2["GTFS_UNSUPPORTED_FILE_TYPE"] = "GTFS_UNSUPPORTED_FILE_TYPE";
+  GtfsErrorCode2["GTFS_CSV_PARSE_FAILED"] = "GTFS_CSV_PARSE_FAILED";
+  GtfsErrorCode2["GTFS_QUERY_INVALID"] = "GTFS_QUERY_INVALID";
+  return GtfsErrorCode2;
+})(GtfsErrorCode || {});
+var GtfsWarningCode = /* @__PURE__ */ ((GtfsWarningCode2) => {
+  GtfsWarningCode2["GTFS_DUPLICATE_PRIMARY_KEY"] = "GTFS_DUPLICATE_PRIMARY_KEY";
+  return GtfsWarningCode2;
+})(GtfsWarningCode || {});
+var GtfsError = class extends Error {
+  code;
+  category;
+  isOperational;
+  statusCode;
+  details;
+  constructor(message, options) {
+    super(message, { cause: options.cause });
+    this.name = "GtfsError";
+    this.code = options.code;
+    this.category = options.category;
+    this.isOperational = options.isOperational ?? true;
+    this.statusCode = options.statusCode;
+    this.details = options.details;
+  }
+};
+function isGtfsError(error) {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const candidate = error;
+  return candidate.name === "GtfsError" && typeof candidate.message === "string" && typeof candidate.code === "string" && typeof candidate.category === "string" && typeof candidate.isOperational === "boolean";
+}
+function isGtfsValidationError(error) {
+  return isGtfsError(error) && error.category === "validation" /* VALIDATION */;
+}
+function toGtfsError(error, fallback) {
+  if (isGtfsError(error)) {
+    return error;
+  }
+  return new GtfsError(fallback.message, {
+    ...fallback,
+    cause: error
+  });
+}
+function createImportReport() {
+  return {
+    errors: [],
+    warnings: [],
+    errorCountsByCode: {},
+    warningCountsByCode: {}
+  };
+}
+function addImportError(report, error) {
+  report.errors.push(error);
+  report.errorCountsByCode[error.code] = (report.errorCountsByCode[error.code] ?? 0) + 1;
+}
+function addImportWarning(report, warning) {
+  report.warnings.push(warning);
+  report.warningCountsByCode[warning.code] = (report.warningCountsByCode[warning.code] ?? 0) + 1;
+}
+function formatGtfsError(error, options = { verbosity: "developer" }) {
+  if (!isGtfsError(error)) {
+    const message = error instanceof Error ? error.message : String(error);
+    return options.verbosity === "user" ? message : `UNKNOWN_ERROR: ${message}`;
+  }
+  if (options.verbosity === "user") {
+    return error.message;
+  }
+  return [
+    `${error.code}: ${error.message}`,
+    `category=${error.category}`,
+    error.statusCode !== void 0 ? `statusCode=${error.statusCode}` : null,
+    error.details ? `details=${JSON.stringify(error.details)}` : null
+  ].filter(Boolean).join(" | ");
+}
+
 // src/lib/db.ts
 var dbs = {};
 function setupDb(sqlitePath) {
@@ -4107,22 +4206,39 @@ function openDb(config = null) {
     return dbs[filename];
   }
   if (Object.keys(dbs).length > 1) {
-    throw new Error(
-      "Multiple databases open, please specify which one to use."
+    throw new GtfsError(
+      "Multiple databases open, please specify which one to use.",
+      {
+        code: "GTFS_DB_OPERATION_FAILED" /* GTFS_DB_OPERATION_FAILED */,
+        category: "database" /* DATABASE */,
+        details: { openDatabaseCount: Object.keys(dbs).length }
+      }
     );
   }
-  throw new Error("Unable to find database connection.");
+  throw new GtfsError("Unable to find database connection.", {
+    code: "GTFS_DB_OPERATION_FAILED" /* GTFS_DB_OPERATION_FAILED */,
+    category: "database" /* DATABASE */
+  });
 }
 function closeDb(db = null) {
   if (Object.keys(dbs).length === 0) {
-    throw new Error(
-      "No database connection. Call `openDb(config)` before using any methods."
+    throw new GtfsError(
+      "No database connection. Call `openDb(config)` before using any methods.",
+      {
+        code: "GTFS_DB_OPERATION_FAILED" /* GTFS_DB_OPERATION_FAILED */,
+        category: "database" /* DATABASE */
+      }
     );
   }
   if (!db) {
     if (Object.keys(dbs).length > 1) {
-      throw new Error(
-        "Multiple database connections. Pass the db you want to close as a parameter to `closeDb`."
+      throw new GtfsError(
+        "Multiple database connections. Pass the db you want to close as a parameter to `closeDb`.",
+        {
+          code: "GTFS_DB_OPERATION_FAILED" /* GTFS_DB_OPERATION_FAILED */,
+          category: "database" /* DATABASE */,
+          details: { openDatabaseCount: Object.keys(dbs).length }
+        }
       );
     }
     db = dbs[Object.keys(dbs)[0]];
@@ -4132,14 +4248,23 @@ function closeDb(db = null) {
 }
 function deleteDb(db = null) {
   if (Object.keys(dbs).length === 0) {
-    throw new Error(
-      "No database connection. Call `openDb(config)` before using any methods."
+    throw new GtfsError(
+      "No database connection. Call `openDb(config)` before using any methods.",
+      {
+        code: "GTFS_DB_OPERATION_FAILED" /* GTFS_DB_OPERATION_FAILED */,
+        category: "database" /* DATABASE */
+      }
     );
   }
   if (!db) {
     if (Object.keys(dbs).length > 1) {
-      throw new Error(
-        "Multiple database connections. Pass the db you want to delete as a parameter to `deleteDb`."
+      throw new GtfsError(
+        "Multiple database connections. Pass the db you want to delete as a parameter to `deleteDb`.",
+        {
+          code: "GTFS_DB_OPERATION_FAILED" /* GTFS_DB_OPERATION_FAILED */,
+          category: "database" /* DATABASE */,
+          details: { openDatabaseCount: Object.keys(dbs).length }
+        }
       );
     }
     db = dbs[Object.keys(dbs)[0]];
@@ -4278,12 +4403,21 @@ import sqlString from "sqlstring-sqlite";
 import Long from "long";
 function validateConfigForImport(config) {
   if (!config.agencies || config.agencies.length === 0) {
-    throw new Error("No `agencies` specified in config");
+    throw new GtfsError("No `agencies` specified in config", {
+      code: "GTFS_CONFIG_INVALID" /* GTFS_CONFIG_INVALID */,
+      category: "config" /* CONFIG */,
+      details: { field: "agencies" }
+    });
   }
   for (const [index, agency2] of config.agencies.entries()) {
     if (!agency2.path && !agency2.url) {
-      throw new Error(
-        `No Agency \`url\` or \`path\` specified in config for agency index ${index}.`
+      throw new GtfsError(
+        `No Agency \`url\` or \`path\` specified in config for agency index ${index}.`,
+        {
+          code: "GTFS_CONFIG_INVALID" /* GTFS_CONFIG_INVALID */,
+          category: "config" /* CONFIG */,
+          details: { agencyIndex: index }
+        }
       );
     }
   }
@@ -4354,7 +4488,11 @@ function formatWhereClauseBoundingBox(latitudeDegree, longitudeDegree, boundingB
   const lat = Number(latitudeDegree);
   const lon = Number(longitudeDegree);
   if (isNaN(lat) || isNaN(lon) || lat < -90 || lat > 90 || lon < -180 || lon > 180) {
-    throw new Error("Invalid latitude or longitude values");
+    throw new GtfsError("Invalid latitude or longitude values", {
+      code: "GTFS_QUERY_INVALID" /* GTFS_QUERY_INVALID */,
+      category: "query" /* QUERY */,
+      details: { latitudeDegree, longitudeDegree, boundingBoxSideMeters }
+    });
   }
   const latitudeRadian = degree2radian(lat);
   const radiusFromLatitude = Math.cos(latitudeRadian) * EARTH_RADIUS_METERS;
@@ -4410,14 +4548,22 @@ function getDayOfWeekFromDate(date) {
     "saturday"
   ];
   if (!Number.isInteger(date) || date.toString().length !== 8) {
-    throw new Error("Date must be in YYYYMMDD format");
+    throw new GtfsError("Date must be in YYYYMMDD format", {
+      code: "GTFS_INVALID_DATE" /* GTFS_INVALID_DATE */,
+      category: "validation" /* VALIDATION */,
+      details: { value: date }
+    });
   }
   const year = Math.floor(date / 1e4);
   const month = Math.floor(date % 1e4 / 100);
   const day = date % 100;
   const dateObj = new Date(year, month - 1, day);
   if (dateObj.toString() === "Invalid Date") {
-    throw new Error("Invalid date");
+    throw new GtfsError("Invalid date", {
+      code: "GTFS_INVALID_DATE" /* GTFS_INVALID_DATE */,
+      category: "validation" /* VALIDATION */,
+      details: { value: date }
+    });
   }
   return DAYS_OF_WEEK[dateObj.getDay()];
 }
@@ -4504,7 +4650,16 @@ async function fetchGtfsRealtimeData(type, task) {
         signal: task.downloadTimeout ? AbortSignal.timeout(task.downloadTimeout) : void 0
       });
       if (response.status !== 200) {
-        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        throw new GtfsError(`HTTP ${response.status}: ${response.statusText}`, {
+          code: "GTFS_DOWNLOAD_HTTP" /* GTFS_DOWNLOAD_HTTP */,
+          category: "download" /* DOWNLOAD */,
+          statusCode: response.status,
+          details: {
+            url: urlConfig.url,
+            status: response.status,
+            statusText: response.statusText
+          }
+        });
       }
       const buffer = await response.arrayBuffer();
       const message = GtfsRealtimeBindings.transit_realtime.FeedMessage.decode(
@@ -4521,17 +4676,27 @@ async function fetchGtfsRealtimeData(type, task) {
       });
       return feedMessage;
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
+      const gtfsError = toGtfsError(error, {
+        message: error instanceof Error ? error.message : String(error),
+        code: "GTFS_DOWNLOAD_FAILED" /* GTFS_DOWNLOAD_FAILED */,
+        category: "download" /* DOWNLOAD */,
+        details: { type, url: urlConfig.url }
+      });
       if (attempt === MAX_RETRIES) {
         if (task.ignoreErrors) {
           task.logError(
-            `Failed to fetch ${type} after ${MAX_RETRIES} attempts: ${errorMessage}`
+            `Failed to fetch ${type} after ${MAX_RETRIES} attempts: ${gtfsError.message}`
           );
+          if (task.report) {
+            addImportError(task.report, gtfsError);
+          }
           return null;
         }
-        throw error;
+        throw gtfsError;
       }
-      task.logWarning(`Attempt ${attempt} failed for ${type}: ${errorMessage}`);
+      task.logWarning(
+        `Attempt ${attempt} failed for ${type}: ${gtfsError.message}`
+      );
       await new Promise(
         (resolve) => setTimeout(resolve, RETRY_DELAY * attempt)
       );
@@ -4738,8 +4903,9 @@ async function updateGtfsRealtime(initialConfig) {
     );
     removeExpiredRealtimeData(config);
     await mapSeries(config.agencies, async (agency2) => {
+      let task;
       try {
-        const task = {
+        task = {
           realtimeAlerts: agency2.realtimeAlerts,
           realtimeTripUpdates: agency2.realtimeTripUpdates,
           realtimeVehiclePositions: agency2.realtimeVehiclePositions,
@@ -4755,11 +4921,19 @@ async function updateGtfsRealtime(initialConfig) {
         };
         await updateGtfsRealtimeData(task);
       } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
+        const gtfsError = toGtfsError(error, {
+          message: error instanceof Error ? error.message : String(error),
+          code: "GTFS_DB_OPERATION_FAILED" /* GTFS_DB_OPERATION_FAILED */,
+          category: "database" /* DATABASE */,
+          details: { sqlitePath: task?.sqlitePath ?? config.sqlitePath }
+        });
         if (config.ignoreErrors) {
-          logError(config)(errorMessage);
+          logError(config)(formatGtfsError(gtfsError));
+          if (task?.report) {
+            addImportError(task.report, gtfsError);
+          }
         } else {
-          throw error;
+          throw gtfsError;
         }
       }
     });
@@ -4773,42 +4947,88 @@ async function updateGtfsRealtime(initialConfig) {
     );
   } catch (error) {
     if (error.code === "SQLITE_CANTOPEN") {
-      logError(config)(
-        `Unable to open sqlite database "${config.sqlitePath}" defined as \`sqlitePath\` config.json. Ensure the parent directory exists or remove \`sqlitePath\` from config.json.`
+      const dbOpenError = new GtfsError(
+        `Unable to open sqlite database "${config.sqlitePath}" defined as \`sqlitePath\` config.json. Ensure the parent directory exists or remove \`sqlitePath\` from config.json.`,
+        {
+          code: "DB_OPEN_FAILED" /* DB_OPEN_FAILED */,
+          category: "database" /* DATABASE */,
+          details: {
+            sqlitePath: config.sqlitePath,
+            dbCode: error.code
+          },
+          cause: error
+        }
       );
+      logError(config)(dbOpenError.message);
+      throw dbOpenError;
     }
-    throw error;
+    throw toGtfsError(error, {
+      message: error instanceof Error ? error.message : String(error),
+      code: "GTFS_DB_OPERATION_FAILED" /* GTFS_DB_OPERATION_FAILED */,
+      category: "database" /* DATABASE */
+    });
   }
 }
 
 // src/lib/import-gtfs.ts
+function reportTaskError(task, error) {
+  if (task.report) {
+    addImportError(task.report, error);
+  }
+}
 var getTextFiles = async (folderPath) => {
   const files = await readdir(folderPath);
   return files.filter((filename) => filename.slice(-3) === "txt");
 };
 var downloadGtfsFiles = async (task) => {
   if (!task.url) {
-    throw new Error("No `url` specified in config");
+    throw new GtfsError("No `url` specified in config", {
+      code: "GTFS_CONFIG_INVALID" /* GTFS_CONFIG_INVALID */,
+      category: "config" /* CONFIG */
+    });
   }
   task.log(`Downloading GTFS from ${task.url}`);
   task.path = `${task.downloadDir}/gtfs.zip`;
-  const response = await fetch(task.url, {
-    method: "GET",
-    headers: task.headers || {},
-    signal: task.downloadTimeout ? AbortSignal.timeout(task.downloadTimeout) : void 0
-  });
-  if (response.status !== 200) {
-    throw new Error(
-      `Unable to download GTFS from ${task.url}. Got status ${response.status}.`
-    );
+  try {
+    const response = await fetch(task.url, {
+      method: "GET",
+      headers: task.headers || {},
+      signal: task.downloadTimeout ? AbortSignal.timeout(task.downloadTimeout) : void 0
+    });
+    if (response.status !== 200) {
+      throw new GtfsError(
+        `Unable to download GTFS from ${task.url}. Got status ${response.status}.`,
+        {
+          code: "GTFS_DOWNLOAD_HTTP" /* GTFS_DOWNLOAD_HTTP */,
+          category: "download" /* DOWNLOAD */,
+          statusCode: response.status,
+          details: {
+            url: task.url,
+            status: response.status,
+            statusText: response.statusText
+          }
+        }
+      );
+    }
+    const buffer = await response.arrayBuffer();
+    await writeFile(task.path, Buffer.from(buffer));
+    task.log("Download successful");
+  } catch (error) {
+    throw toGtfsError(error, {
+      message: `Unable to download GTFS from ${task.url}.`,
+      code: "GTFS_DOWNLOAD_FAILED" /* GTFS_DOWNLOAD_FAILED */,
+      category: "download" /* DOWNLOAD */,
+      details: { url: task.url }
+    });
   }
-  const buffer = await response.arrayBuffer();
-  await writeFile(task.path, Buffer.from(buffer));
-  task.log("Download successful");
 };
 var extractGtfsFiles = async (task) => {
   if (!task.path) {
-    throw new Error("No `path` specified in config");
+    throw new GtfsError("No `path` specified in config", {
+      code: "GTFS_CONFIG_INVALID" /* GTFS_CONFIG_INVALID */,
+      category: "config" /* CONFIG */,
+      details: { field: "path" }
+    });
   }
   const gtfsPath = untildify(task.path);
   task.log(`Importing static GTFS from ${task.path}\r`);
@@ -4820,19 +5040,34 @@ var extractGtfsFiles = async (task) => {
         const files = await readdir(task.downloadDir);
         const folders = files.filter((filename) => !["__MACOSX"].includes(filename)).map((filename) => path2.join(task.downloadDir, filename)).filter((source) => lstatSync(source).isDirectory());
         if (folders.length > 1) {
-          throw new Error(
-            `More than one subfolder found in zip file at \`${task.path}\`. Ensure that .txt files are in the top level of the zip file, or in a single subdirectory.`
+          throw new GtfsError(
+            `More than one subfolder found in zip file at \`${task.path}\`. Ensure that .txt files are in the top level of the zip file, or in a single subdirectory.`,
+            {
+              code: "GTFS_ZIP_INVALID" /* GTFS_ZIP_INVALID */,
+              category: "zip" /* ZIP */,
+              details: { path: task.path, folderCount: folders.length }
+            }
           );
         } else if (folders.length === 0) {
-          throw new Error(
-            `No .txt files found in \`${task.path}\`. Ensure that .txt files are in the top level of the zip file, or in a single subdirectory.`
+          throw new GtfsError(
+            `No .txt files found in \`${task.path}\`. Ensure that .txt files are in the top level of the zip file, or in a single subdirectory.`,
+            {
+              code: "GTFS_ZIP_INVALID" /* GTFS_ZIP_INVALID */,
+              category: "zip" /* ZIP */,
+              details: { path: task.path }
+            }
           );
         }
         const subfolderName = folders[0];
         const directoryTextFiles = await getTextFiles(subfolderName);
         if (directoryTextFiles.length === 0) {
-          throw new Error(
-            `No .txt files found in \`${task.path}\`. Ensure that .txt files are in the top level of the zip file, or in a single subdirectory.`
+          throw new GtfsError(
+            `No .txt files found in \`${task.path}\`. Ensure that .txt files are in the top level of the zip file, or in a single subdirectory.`,
+            {
+              code: "GTFS_ZIP_INVALID" /* GTFS_ZIP_INVALID */,
+              category: "zip" /* ZIP */,
+              details: { path: task.path, subfolderName }
+            }
           );
         }
         await Promise.all(
@@ -4845,15 +5080,27 @@ var extractGtfsFiles = async (task) => {
         );
       }
     } catch (error) {
-      task.logError(error);
-      throw new Error(`Unable to unzip file ${task.path}`);
+      const wrappedError = toGtfsError(error, {
+        message: `Unable to unzip file ${task.path}`,
+        code: "GTFS_ZIP_INVALID" /* GTFS_ZIP_INVALID */,
+        category: "zip" /* ZIP */,
+        details: { path: task.path }
+      });
+      task.logError(formatGtfsError(wrappedError));
+      throw wrappedError;
     }
   } else {
     try {
       await cp(gtfsPath, task.downloadDir, { recursive: true });
-    } catch {
-      throw new Error(
-        `Unable to load files from path \`${gtfsPath}\` defined in configuration. Verify that path exists and contains GTFS files.`
+    } catch (error) {
+      throw new GtfsError(
+        `Unable to load files from path \`${gtfsPath}\` defined in configuration. Verify that path exists and contains GTFS files.`,
+        {
+          code: "GTFS_DOWNLOAD_FAILED" /* GTFS_DOWNLOAD_FAILED */,
+          category: "download" /* DOWNLOAD */,
+          details: { path: gtfsPath },
+          cause: error
+        }
       );
     }
   }
@@ -4948,8 +5195,17 @@ var formatGtfsLine = (line, model, totalLineCount) => {
     if (value === "" || value === void 0 || value === null) {
       formattedLine[name] = null;
       if (required) {
-        throw new Error(
-          `Missing required value in ${filenameBase}.${filenameExtension} for ${name} on line ${lineNumber}.`
+        throw new GtfsError(
+          `Missing required value in ${filenameBase}.${filenameExtension} for ${name} on line ${lineNumber}.`,
+          {
+            code: "GTFS_REQUIRED_FIELD_MISSING" /* GTFS_REQUIRED_FIELD_MISSING */,
+            category: "validation" /* VALIDATION */,
+            details: {
+              file: `${filenameBase}.${filenameExtension}`,
+              line: lineNumber,
+              column: name
+            }
+          }
         );
       }
       continue;
@@ -4957,8 +5213,18 @@ var formatGtfsLine = (line, model, totalLineCount) => {
     if (type === "date") {
       value = value?.toString().replace(/-/g, "");
       if (value.length !== 8) {
-        throw new Error(
-          `Invalid date in ${filenameBase}.${filenameExtension} for ${name} on line ${lineNumber}.`
+        throw new GtfsError(
+          `Invalid date in ${filenameBase}.${filenameExtension} for ${name} on line ${lineNumber}.`,
+          {
+            code: "GTFS_INVALID_DATE" /* GTFS_INVALID_DATE */,
+            category: "validation" /* VALIDATION */,
+            details: {
+              file: `${filenameBase}.${filenameExtension}`,
+              line: lineNumber,
+              column: name,
+              value
+            }
+          }
         );
       }
     } else if (type === "time") {
@@ -5030,11 +5296,32 @@ var importGtfsFiles = async (db, task) => {
               task.logWarning(
                 `Duplicate values for primary key (${primaryColumns.map((column) => column.name).join(", ")}) found in ${filename}. Set the \`ignoreDuplicates\` option to true in config.json to ignore this error`
               );
+              if (task.report) {
+                addImportWarning(task.report, {
+                  code: "GTFS_DUPLICATE_PRIMARY_KEY" /* GTFS_DUPLICATE_PRIMARY_KEY */,
+                  message: `Duplicate values for primary key found in ${filename}.`,
+                  details: {
+                    file: filename,
+                    line: Number(rowNumber) + 1,
+                    columns: primaryColumns.map((column) => column.name)
+                  }
+                });
+              }
             }
             task.logWarning(
               `Check ${filename} for invalid data on line ${rowNumber + 1}.`
             );
-            throw error;
+            throw toGtfsError(error, {
+              message: error instanceof Error ? error.message : String(error),
+              code: "GTFS_DB_OPERATION_FAILED" /* GTFS_DB_OPERATION_FAILED */,
+              category: "database" /* DATABASE */,
+              details: {
+                file: filename,
+                line: Number(rowNumber) + 1,
+                sqlitePath: task.sqlitePath,
+                dbCode: error.code
+              }
+            });
           }
         }
       });
@@ -5063,12 +5350,20 @@ var importGtfsFiles = async (db, task) => {
               }
             }
           } catch (error) {
+            const gtfsError = toGtfsError(error, {
+              message: error instanceof Error ? error.message : String(error),
+              code: "GTFS_CSV_PARSE_FAILED" /* GTFS_CSV_PARSE_FAILED */,
+              category: "parse" /* PARSE */,
+              details: { file: filename }
+            });
             if (task.ignoreErrors) {
-              const errorMessage = error instanceof Error ? error.message : String(error);
-              task.logError(`Error processing ${filename}: ${errorMessage}`);
+              reportTaskError(task, gtfsError);
+              task.logError(
+                `Error processing ${filename}: ${gtfsError.message}`
+              );
               resolve();
             } else {
-              reject(error);
+              reject(gtfsError);
             }
           }
         });
@@ -5078,15 +5373,21 @@ var importGtfsFiles = async (db, task) => {
               try {
                 insertLines(lines);
               } catch (error) {
+                const gtfsError = toGtfsError(error, {
+                  message: error instanceof Error ? error.message : String(error),
+                  code: "GTFS_DB_OPERATION_FAILED" /* GTFS_DB_OPERATION_FAILED */,
+                  category: "database" /* DATABASE */,
+                  details: { file: filename, sqlitePath: task.sqlitePath }
+                });
                 if (task.ignoreErrors) {
-                  const errorMessage = error instanceof Error ? error.message : String(error);
                   task.logError(
-                    `Error inserting data for ${filename}: ${errorMessage}`
+                    `Error inserting data for ${filename}: ${gtfsError.message}`
                   );
+                  reportTaskError(task, gtfsError);
                   resolve();
                   return;
                 } else {
-                  reject(error);
+                  reject(gtfsError);
                   return;
                 }
               }
@@ -5097,22 +5398,38 @@ var importGtfsFiles = async (db, task) => {
             );
             resolve();
           } catch (error) {
+            const gtfsError = toGtfsError(error, {
+              message: error instanceof Error ? error.message : String(error),
+              code: "GTFS_DB_OPERATION_FAILED" /* GTFS_DB_OPERATION_FAILED */,
+              category: "database" /* DATABASE */,
+              details: { file: filename, sqlitePath: task.sqlitePath }
+            });
             if (task.ignoreErrors) {
-              const errorMessage = error instanceof Error ? error.message : String(error);
-              task.logError(`Error finalizing ${filename}: ${errorMessage}`);
+              task.logError(
+                `Error finalizing ${filename}: ${gtfsError.message}`
+              );
+              reportTaskError(task, gtfsError);
               resolve();
             } else {
-              reject(error);
+              reject(gtfsError);
             }
           }
         });
         parser.on("error", (error) => {
+          const gtfsError = toGtfsError(error, {
+            message: error instanceof Error ? error.message : String(error),
+            code: "GTFS_CSV_PARSE_FAILED" /* GTFS_CSV_PARSE_FAILED */,
+            category: "parse" /* PARSE */,
+            details: { file: filename }
+          });
           if (task.ignoreErrors) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            task.logError(`Parser error for ${filename}: ${errorMessage}`);
+            task.logError(
+              `Parser error for ${filename}: ${gtfsError.message}`
+            );
+            reportTaskError(task, gtfsError);
             resolve();
           } else {
-            reject(error);
+            reject(gtfsError);
           }
         });
         createReadStream(filepath).pipe(stripBomStream()).pipe(parser);
@@ -5121,10 +5438,24 @@ var importGtfsFiles = async (db, task) => {
           if (isValidJSON(data) === false) {
             if (task.ignoreErrors) {
               task.logError(`Invalid JSON in ${filename}`);
+              reportTaskError(
+                task,
+                new GtfsError(`Invalid JSON in ${filename}`, {
+                  code: "GTFS_JSON_INVALID" /* GTFS_JSON_INVALID */,
+                  category: "parse" /* PARSE */,
+                  details: { file: filename }
+                })
+              );
               resolve();
               return;
             } else {
-              reject(new Error(`Invalid JSON in ${filename}`));
+              reject(
+                new GtfsError(`Invalid JSON in ${filename}`, {
+                  code: "GTFS_JSON_INVALID" /* GTFS_JSON_INVALID */,
+                  category: "parse" /* PARSE */,
+                  details: { file: filename }
+                })
+              );
               return;
             }
           }
@@ -5142,23 +5473,37 @@ var importGtfsFiles = async (db, task) => {
             );
             resolve();
           } catch (error) {
+            const gtfsError = toGtfsError(error, {
+              message: error instanceof Error ? error.message : String(error),
+              code: "GTFS_DB_OPERATION_FAILED" /* GTFS_DB_OPERATION_FAILED */,
+              category: "database" /* DATABASE */,
+              details: { file: filename, sqlitePath: task.sqlitePath }
+            });
             if (task.ignoreErrors) {
-              const errorMessage = error instanceof Error ? error.message : String(error);
               task.logError(
-                `Error inserting data for ${filename}: ${errorMessage}`
+                `Error inserting data for ${filename}: ${gtfsError.message}`
               );
+              reportTaskError(task, gtfsError);
               resolve();
             } else {
-              reject(error);
+              reject(gtfsError);
             }
           }
         }).catch((error) => {
+          const gtfsError = toGtfsError(error, {
+            message: error instanceof Error ? error.message : String(error),
+            code: "GTFS_CSV_PARSE_FAILED" /* GTFS_CSV_PARSE_FAILED */,
+            category: "parse" /* PARSE */,
+            details: { file: filename }
+          });
           if (task.ignoreErrors) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            task.logError(`Error reading ${filename}: ${errorMessage}`);
+            task.logError(
+              `Error reading ${filename}: ${gtfsError.message}`
+            );
+            reportTaskError(task, gtfsError);
             resolve();
           } else {
-            reject(error);
+            reject(gtfsError);
           }
         });
       } else {
@@ -5169,7 +5514,17 @@ var importGtfsFiles = async (db, task) => {
           resolve();
         } else {
           reject(
-            new Error(`Unsupported file type: ${model.filenameExtension}`)
+            new GtfsError(
+              `Unsupported file type: ${model.filenameExtension}`,
+              {
+                code: "GTFS_UNSUPPORTED_FILE_TYPE" /* GTFS_UNSUPPORTED_FILE_TYPE */,
+                category: "parse" /* PARSE */,
+                details: {
+                  file: filename,
+                  extension: model.filenameExtension
+                }
+              }
+            )
           );
         }
       }
@@ -5181,6 +5536,7 @@ async function importGtfs(initialConfig) {
   const startTime = process.hrtime.bigint();
   const config = setDefaultConfig(initialConfig);
   validateConfigForImport(config);
+  const report = config.includeImportReport ? createImportReport() : void 0;
   try {
     const db = openDb(config);
     const agencyCount = config.agencies.length;
@@ -5208,7 +5564,8 @@ async function importGtfs(initialConfig) {
           currentTimestamp: Math.floor(Date.now() / 1e3),
           log: log(config),
           logWarning: logWarning(config),
-          logError: logError(config)
+          logError: logError(config),
+          report
         };
         if ("url" in agency2) {
           Object.assign(task, { url: agency2.url });
@@ -5223,11 +5580,18 @@ async function importGtfs(initialConfig) {
         await updateGtfsRealtimeData(task);
         await rm2(tempPath, { recursive: true });
       } catch (error) {
+        const wrappedError = toGtfsError(error, {
+          message: error instanceof Error ? error.message : String(error),
+          code: "GTFS_CSV_PARSE_FAILED" /* GTFS_CSV_PARSE_FAILED */,
+          category: "parse" /* PARSE */
+        });
         if (config.ignoreErrors) {
-          const errorMessage = error instanceof Error ? error.message : String(error);
-          logError(config)(errorMessage);
+          logError(config)(formatGtfsError(wrappedError));
+          if (report) {
+            addImportError(report, wrappedError);
+          }
         } else {
-          throw error;
+          throw wrappedError;
         }
       }
     });
@@ -5241,11 +5605,29 @@ async function importGtfs(initialConfig) {
     );
   } catch (error) {
     if (error.code === "SQLITE_CANTOPEN") {
-      logError(config)(
-        `Unable to open sqlite database "${config.sqlitePath}" defined as \`sqlitePath\` config.json. Ensure the parent directory exists or remove \`sqlitePath\` from config.json.`
+      const dbOpenError = new GtfsError(
+        `Unable to open sqlite database "${config.sqlitePath}" defined as \`sqlitePath\` config.json. Ensure the parent directory exists or remove \`sqlitePath\` from config.json.`,
+        {
+          code: "DB_OPEN_FAILED" /* DB_OPEN_FAILED */,
+          category: "database" /* DATABASE */,
+          details: {
+            sqlitePath: config.sqlitePath,
+            dbCode: error.code
+          },
+          cause: error
+        }
       );
+      logError(config)(dbOpenError.message);
+      throw dbOpenError;
     }
-    throw error;
+    throw toGtfsError(error, {
+      message: error instanceof Error ? error.message : String(error),
+      code: "GTFS_CSV_PARSE_FAILED" /* GTFS_CSV_PARSE_FAILED */,
+      category: "parse" /* PARSE */
+    });
+  }
+  if (report) {
+    return report;
   }
 }
 
@@ -5468,7 +5850,11 @@ function getCalendars(query = {}, fields = [], orderBy2 = [], options = {}) {
 function getServiceIdsByDate(date, options = {}) {
   const db = options.db ?? openDb();
   if (!date) {
-    throw new Error("`date` is a required query parameter");
+    throw new GtfsError("`date` is a required query parameter", {
+      code: "GTFS_QUERY_INVALID" /* GTFS_QUERY_INVALID */,
+      category: "query" /* QUERY */,
+      details: { field: "date" }
+    });
   }
   const dayOfWeek = getDayOfWeekFromDate(date);
   const results = db.prepare(
@@ -5937,7 +6323,11 @@ function getStoptimes(query = {}, fields = [], orderBy2 = [], options = {}) {
   );
   if (query.date) {
     if (typeof query.date !== "number") {
-      throw new Error("`date` must be a number in yyyymmdd format");
+      throw new GtfsError("`date` must be a number in yyyymmdd format", {
+        code: "GTFS_QUERY_INVALID" /* GTFS_QUERY_INVALID */,
+        category: "query" /* QUERY */,
+        details: { field: "date", value: query.date }
+      });
     }
     const serviceIds = getServiceIdsByDate(query.date, options);
     const tripSubquery = `SELECT DISTINCT trip_id FROM trips WHERE service_id IN (${serviceIds.map((id) => sqlString4.escape(id)).join(",")})`;
@@ -5945,7 +6335,11 @@ function getStoptimes(query = {}, fields = [], orderBy2 = [], options = {}) {
   }
   if (query.start_time) {
     if (typeof query.start_time !== "string") {
-      throw new Error("`start_time` must be a string in HH:mm:ss format");
+      throw new GtfsError("`start_time` must be a string in HH:mm:ss format", {
+        code: "GTFS_QUERY_INVALID" /* GTFS_QUERY_INVALID */,
+        category: "query" /* QUERY */,
+        details: { field: "start_time", value: query.start_time }
+      });
     }
     whereClauses.push(
       `arrival_timestamp >= ${calculateSecondsFromMidnight(query.start_time)}`
@@ -5953,7 +6347,11 @@ function getStoptimes(query = {}, fields = [], orderBy2 = [], options = {}) {
   }
   if (query.end_time) {
     if (typeof query.end_time !== "string") {
-      throw new Error("`end_time` must be a string in HH:mm:ss format");
+      throw new GtfsError("`end_time` must be a string in HH:mm:ss format", {
+        code: "GTFS_QUERY_INVALID" /* GTFS_QUERY_INVALID */,
+        category: "query" /* QUERY */,
+        details: { field: "end_time", value: query.end_time }
+      });
     }
     whereClauses.push(
       `departure_timestamp <= ${calculateSecondsFromMidnight(query.end_time)}`
@@ -6019,7 +6417,11 @@ function getTrips(query = {}, fields = [], orderBy2 = [], options = {}) {
   );
   if (query.date) {
     if (typeof query.date !== "number") {
-      throw new Error("`date` must be a number in yyyymmdd format");
+      throw new GtfsError("`date` must be a number in yyyymmdd format", {
+        code: "GTFS_QUERY_INVALID" /* GTFS_QUERY_INVALID */,
+        category: "query" /* QUERY */,
+        details: { field: "date", value: query.date }
+      });
     }
     const serviceIds = getServiceIdsByDate(query.date, options);
     whereClauses.push(
@@ -6299,10 +6701,15 @@ function getRunsPieces(query = {}, fields = [], orderBy2 = [], options = {}) {
   ).all();
 }
 export {
+  GtfsError,
+  GtfsErrorCategory,
+  GtfsErrorCode,
+  GtfsWarningCode,
   advancedQuery,
   closeDb,
   deleteDb,
   exportGtfs,
+  formatGtfsError,
   generateFolderName,
   getAgencies2 as getAgencies,
   getAreas,
@@ -6363,6 +6770,8 @@ export {
   getTripsDatedVehicleJourneys,
   getVehiclePositions,
   importGtfs,
+  isGtfsError,
+  isGtfsValidationError,
   openDb,
   prepDirectory,
   untildify,