@trafficgroup/knex-rel 0.1.8 → 0.1.10

package/migrations/20251020225758_migration.ts

@@ -13,49 +13,28 @@ import type { Knex } from "knex";
 export async function up(knex: Knex): Promise<void> {
   // Step 1: Create video_batch table with proper id/uuid pattern
   await knex.schema.createTable("video_batch", (table) => {
-    table
-      .increments("id")
-      .primary()
+    table.increments("id").primary()
       .comment("Primary key for internal foreign key relationships");
 
-    table
-      .uuid("uuid")
-      .notNullable()
-      .unique()
-      .defaultTo(knex.raw("uuid_generate_v4()"))
+    table.uuid("uuid").notNullable().unique().defaultTo(knex.raw('uuid_generate_v4()'))
       .comment("UUID for external API communication");
 
-    table
-      .integer("folderId")
-      .unsigned()
-      .notNullable()
-      .references("id")
-      .inTable("folders")
-      .onDelete("CASCADE")
+    table.integer("folderId").unsigned().notNullable()
+      .references("id").inTable("folders").onDelete("CASCADE")
       .comment("Foreign key to folders table");
 
-    table
-      .enu("status", ["PENDING", "IN_PROGRESS", "COMPLETED", "FAILED"])
+    table.enu("status", ["PENDING", "IN_PROGRESS", "COMPLETED", "FAILED"])
       .notNullable()
       .defaultTo("PENDING")
       .comment("Status of the batch upload");
 
-    table
-      .integer("totalVideos")
-      .notNullable()
-      .defaultTo(0)
+    table.integer("totalVideos").notNullable().defaultTo(0)
       .comment("Total number of videos in batch");
 
-    table
-      .integer("completedVideos")
-      .notNullable()
-      .defaultTo(0)
+    table.integer("completedVideos").notNullable().defaultTo(0)
       .comment("Number of successfully created videos");
 
-    table
-      .integer("failedVideos")
-      .notNullable()
-      .defaultTo(0)
+    table.integer("failedVideos").notNullable().defaultTo(0)
       .comment("Number of failed videos");
 
     table.timestamps(true, true);
@@ -63,32 +42,17 @@ export async function up(knex: Knex): Promise<void> {
 
   // Step 2: Add recording time, trimming, and batch columns to video table
   await knex.schema.alterTable("video", (table) => {
-    table
-      .timestamp("recordingStartedAt", { useTz: true })
-      .nullable()
+    table.timestamp("recordingStartedAt", { useTz: true }).nullable()
       .comment("Recording start time in UTC - null for backward compatibility");
 
-    table
-      .boolean("trimEnabled")
-      .notNullable()
-      .defaultTo(false)
+    table.boolean("trimEnabled").notNullable().defaultTo(false)
       .comment("Whether video trimming is enabled");
 
-    table
-      .jsonb("trimPeriods")
-      .nullable()
-      .comment(
-        "Array of trim periods with startTime and endTime in ISO 8601 format",
-      );
-
-    table
-      .integer("batchId")
-      .unsigned()
-      .nullable()
-      .references("id")
-      .inTable("video_batch")
-      .withKeyName("fk_video_batch")
-      .onDelete("SET NULL")
+    table.jsonb("trimPeriods").nullable()
+      .comment("Array of trim periods with startTime and endTime in ISO 8601 format");
+
+    table.integer("batchId").unsigned().nullable()
+      .references("id").inTable("video_batch").withKeyName("fk_video_batch").onDelete("SET NULL")
       .comment("Foreign key to video_batch table (numerical ID, NOT UUID)");
   });
 

package/migrations/20251112120000_migration.ts

@@ -0,0 +1,81 @@
+import { Knex } from "knex";
+
+/**
+ * Migration: Rename cameras table to locations
+ *
+ * Purpose: Rename existing 'cameras' table to 'locations' to represent physical study sites.
+ * This is the first step in separating locations (physical sites) from cameras (devices at those sites).
+ */
+export async function up(knex: Knex): Promise<void> {
+  // 1. Rename the cameras table to locations
+  await knex.schema.renameTable("cameras", "locations");
+
+  // 2. Rename the uuid unique constraint to match new table name (frees up name for new cameras table)
+  await knex.raw(`
+    ALTER TABLE locations
+    RENAME CONSTRAINT cameras_uuid_unique TO locations_uuid_unique
+  `);
+
+  // 3. Rename the foreign key column in study table
+  await knex.schema.alterTable("study", (table) => {
+    table.renameColumn("cameraId", "locationId");
+  });
+
+  // 4. Drop the old foreign key constraint
+  await knex.raw(`
+    ALTER TABLE study
+    DROP CONSTRAINT IF EXISTS study_cameraid_foreign
+  `);
+
+  // 5. Add new foreign key constraint with updated name
+  await knex.schema.alterTable("study", (table) => {
+    table.foreign("locationId").references("id").inTable("locations").onDelete("SET NULL");
+  });
+
+  // 6. Drop old index if it exists
+  await knex.raw(`
+    DROP INDEX IF EXISTS study_cameraid_index
+  `);
+
+  // 7. Create new index with updated name
+  await knex.schema.alterTable("study", (table) => {
+    table.index(["locationId"], "study_locationid_index");
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  // 1. Drop the new foreign key constraint
+  await knex.raw(`
+    ALTER TABLE study
+    DROP CONSTRAINT IF EXISTS study_locationid_foreign
+  `);
+
+  // 2. Drop new index
+  await knex.raw(`
+    DROP INDEX IF EXISTS study_locationid_index
+  `);
+
+  // 3. Rename column back
+  await knex.schema.alterTable("study", (table) => {
+    table.renameColumn("locationId", "cameraId");
+  });
+
+  // 4. Restore original foreign key constraint
+  await knex.schema.alterTable("study", (table) => {
+    table.foreign("cameraId").references("id").inTable("locations").onDelete("SET NULL");
+  });
+
+  // 5. Restore original index
+  await knex.schema.alterTable("study", (table) => {
+    table.index(["cameraId"], "study_cameraid_index");
+  });
+
+  // 6. Rename constraint back to original name
+  await knex.raw(`
+    ALTER TABLE locations
+    RENAME CONSTRAINT locations_uuid_unique TO cameras_uuid_unique
+  `);
+
+  // 7. Rename the table back to cameras
+  await knex.schema.renameTable("locations", "cameras");
+}

package/migrations/20251112120100_migration.ts

@@ -0,0 +1,21 @@
+import { Knex } from "knex";
+
+/**
+ * Migration: Add isMultiCamera field to study table
+ *
+ * Purpose: Add boolean flag to indicate whether a study uses multiple cameras.
+ * Defaults to false for backward compatibility with existing single-camera studies.
+ */
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("study", (table) => {
+    table.boolean("isMultiCamera").notNullable().defaultTo(false);
+    table.index(["isMultiCamera"], "study_ismulticamera_index");
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("study", (table) => {
+    table.dropIndex(["isMultiCamera"], "study_ismulticamera_index");
+    table.dropColumn("isMultiCamera");
+  });
+}

package/migrations/20251112120200_migration.ts

@@ -0,0 +1,38 @@
+import { Knex } from "knex";
+
+/**
+ * Migration: Create cameras table
+ *
+ * Purpose: Create new 'cameras' table to represent camera devices at locations.
+ * This allows multiple cameras to be associated with a single location.
+ */
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable("cameras", (table) => {
+    table.increments("id").primary();
+    table.uuid("uuid").defaultTo(knex.raw("uuid_generate_v4()")).unique().notNullable();
+    table.integer("locationId").unsigned().notNullable()
+      .references("id").inTable("locations").onDelete("CASCADE");
+    table.string("name", 100).notNullable();
+    table.text("description").nullable();
+    table.enu("status", ["ACTIVE", "INACTIVE", "MAINTENANCE"], {
+      useNative: true,
+      enumName: "camera_status_enum"
+    }).defaultTo("ACTIVE").notNullable();
+    table.jsonb("metadata").defaultTo("{}").notNullable();
+    table.timestamps(true, true);
+
+    // Unique constraint: camera names must be unique within a location
+    table.unique(["locationId", "name"], "cameras_locationid_name_unique");
+
+    // Index for faster lookups
+    table.index(["locationId"], "cameras_locationid_index");
+    table.index(["status"], "cameras_status_index");
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.dropTableIfExists("cameras");
+
+  // Drop the enum type
+  await knex.raw("DROP TYPE IF EXISTS camera_status_enum");
+}

package/migrations/20251112120300_migration.ts

@@ -0,0 +1,22 @@
+import { Knex } from "knex";
+
+/**
+ * Migration: Add cameraId column to video table
+ *
+ * Purpose: Link videos to specific cameras in multi-camera studies.
+ * Nullable to maintain backward compatibility with existing videos.
+ */
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("video", (table) => {
+    table.integer("cameraId").unsigned().nullable()
+      .references("id").inTable("cameras").onDelete("SET NULL");
+    table.index(["cameraId"], "video_cameraid_index");
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("video", (table) => {
+    table.dropIndex(["cameraId"], "video_cameraid_index");
+    table.dropColumn("cameraId");
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trafficgroup/knex-rel",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Knex Module",
   "main": "dist/index.js",
   "scripts": {

package/src/constants/video.constants.ts

@@ -0,0 +1,19 @@
+/**
+ * Video sorting constants
+ * Shared between DAO and API controller to ensure validation consistency
+ */
+
+export const VALID_VIDEO_SORT_FIELDS = ['created_at', 'name', 'status'] as const;
+export type VideoSortField = typeof VALID_VIDEO_SORT_FIELDS[number];
+
+export const VALID_SORT_ORDERS = ['ASC', 'DESC'] as const;
+export type SortOrder = typeof VALID_SORT_ORDERS[number];
+
+/**
+ * Maps API sort field names to database column names with table aliases
+ */
+export const VIDEO_SORT_COLUMN_MAP: Record<VideoSortField, string> = {
+    'created_at': 'v.created_at',
+    'name': 'v.name',
+    'status': 'v.status'
+};

package/src/d.types.ts

@@ -1,22 +1,18 @@
 export interface IDataPaginator<T> {
-  success: boolean;
-  data: T[];
-  page: number;
-  limit: number;
-  count: number;
-  totalCount: number;
-  totalPages: number;
+    success: boolean;
+    data: T[];
+    page: number;
+    limit: number;
+    count: number;
+    totalCount: number;
+    totalPages: number;
 }
 
 export interface IBaseDAO<T> {
-  create(item: T): Promise<T>;
-  getById(id: number): Promise<T | null>;
-  getByUuid(uuid: string): Promise<T | null>;
-  getAll(
-    page: number,
-    limit: number,
-    entityId?: any | null,
-  ): Promise<IDataPaginator<T>>;
-  update(id: number, item: T): Promise<T | null>;
-  delete(id: number): Promise<boolean>;
-}
+    create(item: T): Promise<T>;
+    getById(id: number): Promise<T | null>;
+    getByUuid(uuid: string): Promise<T | null>;
+    getAll(page: number, limit: number, entityId?: any | null): Promise<IDataPaginator<T>>;
+    update(id: number, item: T): Promise<T | null>;
+    delete(id: number): Promise<boolean>;
+}

package/src/dao/VideoMinuteResultDAO.ts

@@ -69,13 +69,15 @@ interface IGroupedResponse {
 }
 
 interface IStudyTimeGroupResult {
-  absoluteTime: string; // ISO 8601 start of bucket
+  absoluteTime: string;      // ISO 8601 start of bucket
   groupIndex: number;
-  label: string; // Formatted label
+  startMinute: number;        // Start minute number (0-based from video start)
+  endMinute: number;          // End minute number (0-based from video start)
+  label: string;              // Formatted label
   results: ITMCResult | IATRResult;
   minuteCount: number;
   videoCount: number;
-  contributingVideos: string[]; // Video UUIDs
+  contributingVideos: string[];  // Video UUIDs
 }
 
 interface IGroupedStudyResponse {
@@ -85,7 +87,7 @@ interface IGroupedStudyResponse {
   study: {
     uuid: string;
     name: string;
-    type: "TMC" | "ATR";
+    type: 'TMC' | 'ATR';
     status: string;
   };
   videoCount: number;
@@ -421,41 +423,37 @@ export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
     // Use Knex query builder for safe parameter binding
     const groupingQuery = this.knex(this.tableName)
       .select(
-        this.knex.raw("FLOOR(minute_number / ?) as group_index", [
-          groupingMinutes,
-        ]),
-        this.knex.raw("MIN(minute_number) as start_minute"),
-        this.knex.raw("MAX(minute_number) as end_minute"),
-        this.knex.raw("COUNT(*) as minute_count"),
-        this.knex.raw(
-          "array_agg(results ORDER BY minute_number) as all_results",
-        ),
+        this.knex.raw('FLOOR(minute_number / ?) as group_index', [groupingMinutes]),
+        this.knex.raw('MIN(minute_number) as start_minute'),
+        this.knex.raw('MAX(minute_number) as end_minute'),
+        this.knex.raw('COUNT(*) as minute_count'),
+        this.knex.raw('array_agg(results ORDER BY minute_number) as all_results')
       )
-      .where("video_id", video.id);
+      .where('video_id', video.id);
 
     if (startMinute !== undefined) {
-      groupingQuery.where("minute_number", ">=", startMinute);
+      groupingQuery.where('minute_number', '>=', startMinute);
     }
 
     if (endMinute !== undefined) {
-      groupingQuery.where("minute_number", "<=", endMinute);
+      groupingQuery.where('minute_number', '<=', endMinute);
     }
 
     const rows = await groupingQuery
-      .groupBy("group_index")
-      .orderBy("group_index");
+      .groupBy('group_index')
+      .orderBy('group_index');
 
     // Aggregate the results in TypeScript based on video type
     const aggregatedGroups: IGroupedResult[] = rows.map((row: any) => {
-      if (!row || typeof row !== "object") {
-        throw new Error("Invalid row data received from database query");
+      if (!row || typeof row !== 'object') {
+        throw new Error('Invalid row data received from database query');
       }
 
       const allResults = Array.isArray(row.all_results) ? row.all_results : [];
-
+      
       // Determine video type based on multiple factors
-      let studyType = video.videoType || "ATR"; // Default fallback to ATR
-
+      let studyType = video.videoType || 'ATR'; // Default fallback to ATR
+      
       // Check if minute data has study_type field (ATR usually does)
       if (allResults.length > 0 && allResults[0].study_type) {
         studyType = allResults[0].study_type;
@@ -467,24 +465,20 @@ export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
           const vehicleKeys = Object.keys(sampleResult.vehicles);
           if (vehicleKeys.length > 0) {
             const firstVehicleType = sampleResult.vehicles[vehicleKeys[0]];
-            if (firstVehicleType && typeof firstVehicleType === "object") {
+            if (firstVehicleType && typeof firstVehicleType === 'object') {
               const directions = Object.keys(firstVehicleType);
-              if (
-                directions.includes("NORTH") ||
-                directions.includes("SOUTH") ||
-                directions.includes("EAST") ||
-                directions.includes("WEST")
-              ) {
-                studyType = "TMC";
+              if (directions.includes('NORTH') || directions.includes('SOUTH') || 
+                  directions.includes('EAST') || directions.includes('WEST')) {
+                studyType = 'TMC';
               }
             }
           }
         }
       }
-
+      
       // Aggregate based on determined video type
       let aggregatedResult;
-      if (studyType === "TMC") {
+      if (studyType === 'TMC') {
         aggregatedResult = this.aggregateTMCResults(allResults);
       } else {
         aggregatedResult = this.aggregateATRResults(allResults);
@@ -575,8 +569,8 @@ export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
         "v.uuid as videoUuid",
         "v.recordingStartedAt",
         this.knex.raw(
-          '"v"."recordingStartedAt" + (vmr.minute_number || \' minutes\')::INTERVAL as "absoluteTime"',
-        ),
+          '"v"."recordingStartedAt" + (vmr.minute_number || \' minutes\')::INTERVAL as "absoluteTime"'
+        )
       )
       .whereIn("v.id", videoIds)
       .orderBy("absoluteTime", "asc");
@@ -614,7 +608,7 @@ export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
     for (const minute of minuteResults) {
       const absoluteTime = new Date(minute.absoluteTime);
       const minutesSinceEarliest = Math.floor(
-        (absoluteTime.getTime() - earliestTime.getTime()) / (1000 * 60),
+        (absoluteTime.getTime() - earliestTime.getTime()) / (1000 * 60)
       );
       const bucketIndex = Math.floor(minutesSinceEarliest / groupingMinutes);
 
@@ -622,7 +616,7 @@ export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
         // Calculate bucket start time
         const bucketStartMinutes = bucketIndex * groupingMinutes;
         const bucketStartTime = new Date(
-          earliestTime.getTime() + bucketStartMinutes * 60 * 1000,
+          earliestTime.getTime() + bucketStartMinutes * 60 * 1000
         );
 
         buckets.set(bucketIndex, {
@@ -639,14 +633,12 @@ export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
     }
 
     // Step 5: Aggregate using existing methods based on study type
-    const aggregatedGroups: IStudyTimeGroupResult[] = Array.from(
-      buckets.values(),
-    )
+    const aggregatedGroups: IStudyTimeGroupResult[] = Array.from(buckets.values())
       .sort((a, b) => a.groupIndex - b.groupIndex)
       .map((bucket) => {
         let aggregatedResult: ITMCResult | IATRResult;
 
-        if (study.type === "TMC") {
+        if (study.type === 'TMC') {
           aggregatedResult = this.aggregateTMCResults(bucket.results);
         } else {
           aggregatedResult = this.aggregateATRResults(bucket.results);
@@ -655,10 +647,9 @@ export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
         return {
           absoluteTime: bucket.absoluteTime.toISOString(),
           groupIndex: bucket.groupIndex,
-          label: this.formatStudyTimeLabel(
-            bucket.absoluteTime,
-            groupingMinutes,
-          ),
+          startMinute: bucket.groupIndex * groupingMinutes,
+          endMinute: (bucket.groupIndex + 1) * groupingMinutes - 1,
+          label: this.formatStudyTimeLabel(bucket.absoluteTime, groupingMinutes),
           results: aggregatedResult,
           minuteCount: bucket.results.length,
           videoCount: bucket.videoUuids.size,
@@ -721,27 +712,25 @@ export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
       vehicles: {},
       counts: {
         total_vehicles: 0,
-        entry_vehicles: 0,
+        entry_vehicles: 0
       },
       total: 0,
       totalcount: 0,
       detected_classes: {},
-      study_type: "TMC",
+      study_type: "TMC"
     };
 
     for (const minute of minutes) {
       const results = minute; // minute is already the results object from array_agg
 
       // Aggregate vehicle movements by class and direction
-      if (results.vehicles && typeof results.vehicles === "object") {
-        for (const [vehicleClass, directions] of Object.entries(
-          results.vehicles,
-        )) {
+      if (results.vehicles && typeof results.vehicles === 'object') {
+        for (const [vehicleClass, directions] of Object.entries(results.vehicles)) {
           // Skip the 'total' pseudo vehicle class - validate it's actually aggregate data
-          if (vehicleClass === "total" && typeof directions === "number") {
+          if (vehicleClass === 'total' && typeof directions === 'number') {
             continue; // This is aggregate total data, not a vehicle class
           }
-
+          
           if (!aggregated.vehicles[vehicleClass]) {
             aggregated.vehicles[vehicleClass] = {};
           }
@@ -764,12 +753,11 @@ export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
               for (const [turnType, count] of Object.entries(turns)) {
                 const turnCount = (count as number) || 0;
                 aggregated.vehicles[vehicleClass][direction][turnType] =
-                  (aggregated.vehicles[vehicleClass][direction][turnType] ||
-                    0) + turnCount;
-
+                  (aggregated.vehicles[vehicleClass][direction][turnType] || 0) + turnCount;
+                
                 // Add to detected_classes count for this vehicle type
                 aggregated.detected_classes[vehicleClass] += turnCount;
-
+                
                 // Add to total counts
                 aggregated.total += turnCount;
                 aggregated.totalcount += turnCount;
@@ -777,12 +765,10 @@ export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
             }
           }
         }
-
+        
         // Also process the 'total' entry for validation but don't count it as a vehicle class
         if (results.vehicles.total) {
-          for (const [direction, turns] of Object.entries(
-            results.vehicles.total as any,
-          )) {
+          for (const [direction, turns] of Object.entries(results.vehicles.total as any)) {
             if (typeof turns === "object" && turns !== null) {
               for (const [turnType, count] of Object.entries(turns)) {
                 const turnCount = (count as number) || 0;
@@ -795,8 +781,7 @@ export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
     }
 
     // Set entry_vehicles same as total_vehicles for TMC
-    aggregated.counts.entry_vehicles =
-      aggregated.counts.total_vehicles || aggregated.total;
+    aggregated.counts.entry_vehicles = aggregated.counts.total_vehicles || aggregated.total;
 
     return aggregated;
   }
@@ -820,7 +805,7 @@ export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
       if (results.vehicles) {
         for (const [vehicleClass, lanes] of Object.entries(results.vehicles)) {
           // Skip 'total' pseudo-class if present
-          if (vehicleClass === "total") {
+          if (vehicleClass === 'total') {
             continue;
           }
 
@@ -829,8 +814,7 @@ export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
           }
 
           for (const [laneId, count] of Object.entries(lanes as any)) {
-            const numericCount =
-              typeof count === "number" ? count : parseInt(String(count)) || 0;
+            const numericCount = typeof count === 'number' ? count : (parseInt(String(count)) || 0);
             aggregated.vehicles[vehicleClass][laneId] =
               (aggregated.vehicles[vehicleClass][laneId] || 0) + numericCount;
           }
@@ -935,16 +919,14 @@ export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
   /**
    * Format time label for study-level results (time only, no dates)
    * Used when results are already grouped by date in the UI
+   * Uses UTC time for consistency with absoluteTime field
    */
-  private formatStudyTimeLabel(
-    startTime: Date,
-    durationMinutes: number,
-  ): string {
+  private formatStudyTimeLabel(startTime: Date, durationMinutes: number): string {
     const endTime = new Date(startTime.getTime() + durationMinutes * 60 * 1000);
 
     const formatTime = (date: Date): string => {
-      const hours = date.getHours().toString().padStart(2, "0");
-      const minutes = date.getMinutes().toString().padStart(2, "0");
+      const hours = date.getUTCHours().toString().padStart(2, "0");
+      const minutes = date.getUTCMinutes().toString().padStart(2, "0");
       return `${hours}:${minutes}`;
     };