@tmlmobilidade/go-utils-sql 20260911.111.29

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './registry.generated.js';
+export * from './sql-path.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './registry.generated.js';
+export * from './sql-path.js';

package/dist/registry.generated.d.ts

@@ -0,0 +1,12 @@
+/**
+ * This file is auto-generated by the generate-sql-registry.sh script.
+ * Do not edit this file manually. Run `npm run repo:sql` to regenerate.
+ *
+ * Source: every .sql file under modules/<module>/sql
+ */
+export declare const SQL_FILES: {
+    readonly hub: readonly ["eta/bootstrap/create-tables.sql", "eta/bootstrap/mv-predict-node-etas.sql", "eta/bootstrap/mv-predict-trip-stop-etas.sql", "eta/bootstrap/mv-sync-curr-vehicle-events.sql", "eta/cleanup/1-delete-out-of-window-curr-rides.sql", "eta/cleanup/2-delete-out-of-window-curr-vehicle-events.sql", "eta/cleanup/3-delete-orphan-curr-waypoints.sql", "eta/cleanup/4-delete-out-of-window-hist-rides.sql", "eta/cleanup/5-delete-orphan-hist-vehicle-events.sql", "eta/cleanup/6-delete-orphan-hist-node-travel-times.sql", "eta/cleanup/7-delete-out-of-window-hist-node-travel-times-aggregation.sql", "eta/loader/aggregate-hist-node-travel-times.sql", "eta/loader/build-hist-node-travel-times.sql", "eta/loader/load-current-waypoints.sql", "eta/loader/load-historical-vehicle-events.sql", "eta/loader/load-rides.sql", "eta/loader/snap-waypoints.sql", "publish-realtime/select-eta-by-stop-gtfs.sql", "publish-realtime/select-eta-by-stop.sql", "publish-realtime/select-eta-by-trip-gtfs.sql", "publish-realtime/select-eta-by-trip.sql", "publish-realtime/select-eta-gtfs.sql", "publish-realtime/select-eta.sql", "publish-realtime/select-vehicle-positions.sql"];
+    readonly operation: readonly ["alerts/list-lines.sql", "alerts/list-rides.sql", "alerts/list-stops.sql", "compose-alert/fetch-lines-reference-context.sql", "compose-alert/fetch-rides-reference-context.sql", "compose-alert/fetch-stops-reference-context.sql", "rides/get-ride.sql", "rides/list-rides.sql"];
+    readonly performance: readonly ["demand/by-agency-by-operational-date.sql"];
+    readonly tracker: readonly ["pt-tml-fertagus-rawdb-stream/find-trip-id.sql", "pt-tml-ml-api-fetch/find-hashed-shape.sql", "pt-tml-ml-api-fetch/find-hashed-trip.sql", "pt-tml-ml-api-fetch/find-rides-for-train.sql"];
+};

package/dist/registry.generated.js

@@ -0,0 +1,54 @@
+/**
+ * This file is auto-generated by the generate-sql-registry.sh script.
+ * Do not edit this file manually. Run `npm run repo:sql` to regenerate.
+ *
+ * Source: every .sql file under modules/<module>/sql
+ */
+/* * */
+export const SQL_FILES = {
+    hub: [
+        'eta/bootstrap/create-tables.sql',
+        'eta/bootstrap/mv-predict-node-etas.sql',
+        'eta/bootstrap/mv-predict-trip-stop-etas.sql',
+        'eta/bootstrap/mv-sync-curr-vehicle-events.sql',
+        'eta/cleanup/1-delete-out-of-window-curr-rides.sql',
+        'eta/cleanup/2-delete-out-of-window-curr-vehicle-events.sql',
+        'eta/cleanup/3-delete-orphan-curr-waypoints.sql',
+        'eta/cleanup/4-delete-out-of-window-hist-rides.sql',
+        'eta/cleanup/5-delete-orphan-hist-vehicle-events.sql',
+        'eta/cleanup/6-delete-orphan-hist-node-travel-times.sql',
+        'eta/cleanup/7-delete-out-of-window-hist-node-travel-times-aggregation.sql',
+        'eta/loader/aggregate-hist-node-travel-times.sql',
+        'eta/loader/build-hist-node-travel-times.sql',
+        'eta/loader/load-current-waypoints.sql',
+        'eta/loader/load-historical-vehicle-events.sql',
+        'eta/loader/load-rides.sql',
+        'eta/loader/snap-waypoints.sql',
+        'publish-realtime/select-eta-by-stop-gtfs.sql',
+        'publish-realtime/select-eta-by-stop.sql',
+        'publish-realtime/select-eta-by-trip-gtfs.sql',
+        'publish-realtime/select-eta-by-trip.sql',
+        'publish-realtime/select-eta-gtfs.sql',
+        'publish-realtime/select-eta.sql',
+        'publish-realtime/select-vehicle-positions.sql',
+    ],
+    operation: [
+        'alerts/list-lines.sql',
+        'alerts/list-rides.sql',
+        'alerts/list-stops.sql',
+        'compose-alert/fetch-lines-reference-context.sql',
+        'compose-alert/fetch-rides-reference-context.sql',
+        'compose-alert/fetch-stops-reference-context.sql',
+        'rides/get-ride.sql',
+        'rides/list-rides.sql',
+    ],
+    performance: [
+        'demand/by-agency-by-operational-date.sql',
+    ],
+    tracker: [
+        'pt-tml-fertagus-rawdb-stream/find-trip-id.sql',
+        'pt-tml-ml-api-fetch/find-hashed-shape.sql',
+        'pt-tml-ml-api-fetch/find-hashed-trip.sql',
+        'pt-tml-ml-api-fetch/find-rides-for-train.sql',
+    ],
+};

package/dist/sql-path.d.ts

@@ -0,0 +1,23 @@
+import { SQL_FILES } from './registry.generated.js';
+/**
+ * A module that ships SQL files under `modules/<module>/sql`.
+ */
+export type SqlModule = keyof typeof SQL_FILES;
+/**
+ * A SQL file shipped by a given module, relative to `modules/<module>/sql`.
+ */
+export type SqlFile<T extends SqlModule> = (typeof SQL_FILES)[T][number] & string;
+/**
+ * Returns the absolute path to a `.sql` file shipped by a module.
+ *
+ * Both arguments are checked against the generated registry, so a renamed or
+ * deleted SQL file fails at build time instead of at runtime.
+ *
+ * @param module The module that owns the SQL file.
+ * @param file The file path, relative to `modules/<module>/sql`.
+ * @returns The absolute path to the file.
+ *
+ * @example
+ * await labDb.queryFromFile(sqlPath('hub', 'eta/loader/load-rides.sql'));
+ */
+export declare function sqlPath<T extends SqlModule>(module: T, file: SqlFile<T>): string;

package/dist/sql-path.js

@@ -0,0 +1,83 @@
+/* * */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/* * */
+/**
+ * Overrides the directory that contains the `modules/` tree. Only meant for
+ * tests and for deployments that do not follow the standard layout.
+ */
+const SQL_ROOT_ENV_VAR = 'GO_SQL_ROOT';
+/**
+ * SQL files are plain assets, not workspace packages, so they cannot be found
+ * through Node module resolution. Instead this file walks up from its own
+ * location looking for a directory that holds `modules/<module>/sql`. The
+ * target of the search is also its own validation, so no marker file is needed.
+ *
+ * - Dev / monorepo: this file lives in `packages-new/utils/sql/{src,dist}`, and
+ *   the walk stops at the repository root.
+ * - Docker runner (`nodejs.dockerfile`): this file lives in
+ *   `/app/packages-new/utils/sql/dist`, and the walk stops at `/app`, where the
+ *   Dockerfile copies `modules/<module>/sql`.
+ */
+const selfDir = path.dirname(fileURLToPath(import.meta.url));
+/** Resolved SQL roots, keyed by module name. */
+const resolvedRoots = new Map();
+/**
+ * Builds the list of directories to test, nearest first: the environment
+ * override, then every ancestor of this file, then the working directory.
+ */
+function candidateBaseDirs() {
+    const baseDirs = [];
+    const override = process.env[SQL_ROOT_ENV_VAR];
+    if (override) {
+        baseDirs.push(path.resolve(override));
+    }
+    let currentDir = selfDir;
+    while (true) {
+        baseDirs.push(currentDir);
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir)
+            break;
+        currentDir = parentDir;
+    }
+    baseDirs.push(path.resolve(process.cwd()));
+    return baseDirs;
+}
+/**
+ * Finds and caches the absolute path to `modules/<module>/sql`.
+ * @throws When no candidate directory holds the module's SQL folder.
+ */
+function resolveModuleSqlRoot(module) {
+    const cachedRoot = resolvedRoots.get(module);
+    if (cachedRoot)
+        return cachedRoot;
+    const searchedPaths = [];
+    for (const baseDir of candidateBaseDirs()) {
+        const candidateRoot = path.join(baseDir, 'modules', module, 'sql');
+        searchedPaths.push(candidateRoot);
+        if (existsSync(candidateRoot)) {
+            resolvedRoots.set(module, candidateRoot);
+            return candidateRoot;
+        }
+    }
+    throw new Error(`Could not locate "modules/${module}/sql". Searched:\n  ${searchedPaths.join('\n  ')}\n`
+        + `Set ${SQL_ROOT_ENV_VAR} to the directory that contains the "modules" tree if it lives elsewhere.`);
+}
+/* * */
+/**
+ * Returns the absolute path to a `.sql` file shipped by a module.
+ *
+ * Both arguments are checked against the generated registry, so a renamed or
+ * deleted SQL file fails at build time instead of at runtime.
+ *
+ * @param module The module that owns the SQL file.
+ * @param file The file path, relative to `modules/<module>/sql`.
+ * @returns The absolute path to the file.
+ *
+ * @example
+ * await labDb.queryFromFile(sqlPath('hub', 'eta/loader/load-rides.sql'));
+ */
+export function sqlPath(module, file) {
+    return path.join(resolveModuleSqlRoot(module), file);
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@tmlmobilidade/go-utils-sql",
+	"version": "20260911.111.29",
+	"author": {
+		"email": "iso@tmlmobilidade.pt",
+		"name": "TML-ISO"
+	},
+	"license": "AGPL-3.0-or-later",
+	"homepage": "https://go.tmlmobilidade.pt",
+	"bugs": {
+		"url": "https://github.com/tmlmobilidade/go/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tmlmobilidade/go.git"
+	},
+	"keywords": [
+		"public transit",
+		"tml",
+		"transportes metropolitanos de lisboa",
+		"go"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsc && resolve-tspaths",
+		"lint": "eslint ./src/ && tsc --noEmit",
+		"lint:fix": "eslint ./src/ --fix",
+		"watch": "tsc-watch --onSuccess 'resolve-tspaths'"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/go-utils-tsconfig": "*",
+		"@types/node": "26.4.0",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.1",
+		"typescript": "6.0.3"
+	}
+}