@trafficgroup/knex-rel 0.1.7 → 0.1.9

package/dist/interfaces/video/video.interfaces.d.ts

@@ -1,9 +1,14 @@
 import type { IFolder } from "../folder/folder.interfaces";
+export interface ITrimPeriod {
+    startTime: string;
+    endTime: string;
+}
 export interface IVideo {
     id: number;
     uuid: string;
     folderId: number;
     annotationSourceId?: number;
+    cameraId?: number;
     name: string;
     videoLocation: string;
     videoOutputLocation: string | null;
@@ -20,6 +25,10 @@ export interface IVideo {
     hlsPlaylist: string | null;
     videoSizeMB: number | null;
     streamingMetadata: Record<string, any> | null;
+    recordingStartedAt?: Date;
+    trimEnabled?: boolean;
+    trimPeriods?: ITrimPeriod[] | null;
+    batchId?: number | null;
     created_at: string;
     updated_at: string;
     folder?: IFolder;

package/migrations/20251020225758_migration.ts

@@ -0,0 +1,135 @@
+import type { Knex } from "knex";
+
+/**
+ * Migration: Add Recording Time, Video Trimming, and Batch Upload Features
+ *
+ * This migration implements three major features:
+ * 1. Recording Start Time - REQUIRED field for all videos (TIMESTAMPTZ in UTC)
+ * 2. Video Trimming - Optional datetime-based trimming with frame-skipping
+ * 3. Batch Upload - Up to 50 videos in all-or-nothing transaction
+ *
+ * FK Pattern: video_batch table uses id (INTEGER) for FKs, uuid (UUID) for external API
+ */
+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()
+      .comment("Primary key for internal foreign key relationships");
+
+    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")
+      .comment("Foreign key to folders table");
+
+    table
+      .enu("status", ["PENDING", "IN_PROGRESS", "COMPLETED", "FAILED"])
+      .notNullable()
+      .defaultTo("PENDING")
+      .comment("Status of the batch upload");
+
+    table
+      .integer("totalVideos")
+      .notNullable()
+      .defaultTo(0)
+      .comment("Total number of videos in batch");
+
+    table
+      .integer("completedVideos")
+      .notNullable()
+      .defaultTo(0)
+      .comment("Number of successfully created videos");
+
+    table
+      .integer("failedVideos")
+      .notNullable()
+      .defaultTo(0)
+      .comment("Number of failed videos");
+
+    table.timestamps(true, true);
+  });
+
+  // Step 2: Add recording time, trimming, and batch columns to video table
+  await knex.schema.alterTable("video", (table) => {
+    table
+      .timestamp("recordingStartedAt", { useTz: true })
+      .nullable()
+      .comment("Recording start time in UTC - null for backward compatibility");
+
+    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")
+      .comment("Foreign key to video_batch table (numerical ID, NOT UUID)");
+  });
+
+  // Step 3: Create indices for performance optimization
+
+  // Index for chronological queries by folder and recording time
+  await knex.raw(`
+    CREATE INDEX idx_videos_folder_recording
+    ON video("folderId", "recordingStartedAt")
+    WHERE "recordingStartedAt" IS NOT NULL
+  `);
+
+  // Index for batch operations
+  await knex.raw(`
+    CREATE INDEX idx_videos_batch
+    ON video("batchId")
+    WHERE "batchId" IS NOT NULL
+  `);
+
+  // Index for trimming filter
+  await knex.raw(`
+    CREATE INDEX idx_videos_trimming
+    ON video("trimEnabled")
+    WHERE "trimEnabled" = true
+  `);
+}
+
+export async function down(knex: Knex): Promise<void> {
+  // Drop indices first
+  await knex.raw(`DROP INDEX IF EXISTS idx_videos_folder_recording`);
+  await knex.raw(`DROP INDEX IF EXISTS idx_videos_batch`);
+  await knex.raw(`DROP INDEX IF EXISTS idx_videos_trimming`);
+
+  // Drop columns from video table
+  await knex.schema.alterTable("video", (table) => {
+    table.dropColumn("recordingStartedAt");
+    table.dropColumn("trimEnabled");
+    table.dropColumn("trimPeriods");
+    table.dropColumn("batchId");
+  });
+
+  // Drop video_batch table
+  await knex.schema.dropTableIfExists("video_batch");
+}

package/migrations/20251112120000_migration.ts

@@ -0,0 +1,89 @@
+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,50 @@
+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,27 @@
+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.7",
+  "version": "0.1.9",
   "description": "Knex Module",
   "main": "dist/index.js",
   "scripts": {

package/src/dao/VideoMinuteResultDAO.ts

@@ -68,6 +68,35 @@ interface IGroupedResponse {
   };
 }
 
+interface IStudyTimeGroupResult {
+  absoluteTime: string; // ISO 8601 start of bucket
+  groupIndex: number;
+  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
+}
+
+interface IGroupedStudyResponse {
+  success: boolean;
+  data: IStudyTimeGroupResult[];
+  groupingMinutes: number;
+  study: {
+    uuid: string;
+    name: string;
+    type: "TMC" | "ATR";
+    status: string;
+  };
+  videoCount: number;
+  dateRange: {
+    earliest: string;
+    latest: string;
+  };
+}
+
 export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
   private knex = KnexManager.getConnection();
   private tableName = "video_minute_results";
@@ -486,6 +515,184 @@ export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
     };
   }
 
+  /**
+   * Get grouped minute results by study UUID with time block aggregation across all videos
+   * @param studyUuid - The UUID of the study
+   * @param groupingMinutes - Number of minutes to group together (default: 15)
+   */
+  async getGroupedMinuteResultsByStudyUuid(
+    studyUuid: string,
+    groupingMinutes: number = 15,
+  ): Promise<IGroupedStudyResponse> {
+    // Step 1: Fetch study and validate
+    const study = await this.knex("study").where("uuid", studyUuid).first();
+
+    if (!study) {
+      throw new Error(`Study with UUID ${studyUuid} not found`);
+    }
+
+    // Step 2: Fetch all COMPLETED videos in the study with recordingStartedAt
+    const videos = await this.knex("video as v")
+      .innerJoin("folders as f", "v.folderId", "f.id")
+      .select("v.id", "v.uuid", "v.name", "v.recordingStartedAt", "v.videoType")
+      .where("f.studyId", study.id)
+      .where("v.status", "COMPLETED")
+      .whereNotNull("v.recordingStartedAt")
+      .orderBy("v.recordingStartedAt", "asc");
+
+    // If no completed videos with recordingStartedAt, return empty result
+    if (videos.length === 0) {
+      return {
+        success: true,
+        data: [],
+        groupingMinutes,
+        study: {
+          uuid: study.uuid,
+          name: study.name,
+          type: study.type,
+          status: study.status,
+        },
+        videoCount: 0,
+        dateRange: {
+          earliest: "",
+          latest: "",
+        },
+      };
+    }
+
+    // Get video IDs for minute results query
+    const videoIds = videos.map((v) => v.id);
+
+    // Calculate date range
+    const earliestVideo = videos[0];
+    const latestVideo = videos[videos.length - 1];
+    const earliestTime = new Date(earliestVideo.recordingStartedAt);
+
+    // Step 3: Fetch and normalize all minute results with absolute times
+    const minuteResults = await this.knex("video_minute_results as vmr")
+      .innerJoin("video as v", "vmr.video_id", "v.id")
+      .select(
+        "vmr.minute_number",
+        "vmr.results",
+        "v.uuid as videoUuid",
+        "v.recordingStartedAt",
+        this.knex.raw(
+          '"v"."recordingStartedAt" + (vmr.minute_number || \' minutes\')::INTERVAL as "absoluteTime"',
+        ),
+      )
+      .whereIn("v.id", videoIds)
+      .orderBy("absoluteTime", "asc");
+
+    // If no minute results found, return empty result
+    if (minuteResults.length === 0) {
+      return {
+        success: true,
+        data: [],
+        groupingMinutes,
+        study: {
+          uuid: study.uuid,
+          name: study.name,
+          type: study.type,
+          status: study.status,
+        },
+        videoCount: videos.length,
+        dateRange: {
+          earliest: earliestVideo.recordingStartedAt.toISOString(),
+          latest: latestVideo.recordingStartedAt.toISOString(),
+        },
+      };
+    }
+
+    // Step 4: Group by time buckets in TypeScript
+    interface IBucket {
+      groupIndex: number;
+      absoluteTime: Date;
+      results: any[];
+      videoUuids: Set<string>;
+    }
+
+    const buckets = new Map<number, IBucket>();
+
+    for (const minute of minuteResults) {
+      const absoluteTime = new Date(minute.absoluteTime);
+      const minutesSinceEarliest = Math.floor(
+        (absoluteTime.getTime() - earliestTime.getTime()) / (1000 * 60),
+      );
+      const bucketIndex = Math.floor(minutesSinceEarliest / groupingMinutes);
+
+      if (!buckets.has(bucketIndex)) {
+        // Calculate bucket start time
+        const bucketStartMinutes = bucketIndex * groupingMinutes;
+        const bucketStartTime = new Date(
+          earliestTime.getTime() + bucketStartMinutes * 60 * 1000,
+        );
+
+        buckets.set(bucketIndex, {
+          groupIndex: bucketIndex,
+          absoluteTime: bucketStartTime,
+          results: [],
+          videoUuids: new Set<string>(),
+        });
+      }
+
+      const bucket = buckets.get(bucketIndex)!;
+      bucket.results.push(minute.results);
+      bucket.videoUuids.add(minute.videoUuid);
+    }
+
+    // Step 5: Aggregate using existing methods based on study type
+    const aggregatedGroups: IStudyTimeGroupResult[] = Array.from(
+      buckets.values(),
+    )
+      .sort((a, b) => a.groupIndex - b.groupIndex)
+      .map((bucket) => {
+        let aggregatedResult: ITMCResult | IATRResult;
+
+        if (study.type === "TMC") {
+          aggregatedResult = this.aggregateTMCResults(bucket.results);
+        } else {
+          aggregatedResult = this.aggregateATRResults(bucket.results);
+        }
+
+        return {
+          absoluteTime: bucket.absoluteTime.toISOString(),
+          groupIndex: bucket.groupIndex,
+          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,
+          contributingVideos: Array.from(bucket.videoUuids),
+        };
+      });
+
+    // Calculate latest time from last minute result
+    const lastMinute = minuteResults[minuteResults.length - 1];
+    const latestTime = new Date(lastMinute.absoluteTime);
+
+    // Step 6: Format response
+    return {
+      success: true,
+      data: aggregatedGroups,
+      groupingMinutes,
+      study: {
+        uuid: study.uuid,
+        name: study.name,
+        type: study.type,
+        status: study.status,
+      },
+      videoCount: videos.length,
+      dateRange: {
+        earliest: earliestTime.toISOString(),
+        latest: latestTime.toISOString(),
+      },
+    };
+  }
+
   /**
    * Aggregate minute results based on video type (TMC or ATR)
    */
@@ -728,6 +935,36 @@ export class VideoMinuteResultDAO implements IBaseDAO<IVideoMinuteResult> {
 
     return `${formatMinute(startMinute)}:00 - ${formatMinute(endMinute)}:59`;
   }
+
+  /**
+   * 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 {
+    const endTime = new Date(startTime.getTime() + durationMinutes * 60 * 1000);
+
+    const formatTime = (date: Date): string => {
+      const hours = date.getUTCHours().toString().padStart(2, "0");
+      const minutes = date.getUTCMinutes().toString().padStart(2, "0");
+      return `${hours}:${minutes}`;
+    };
+
+    return `${formatTime(startTime)} - ${formatTime(endTime)}`;
+  }
 }
 
+// Export interfaces for external use
+export type {
+  IStudyTimeGroupResult,
+  IGroupedStudyResponse,
+  IGroupedResponse,
+  IGroupedResult,
+  ITMCResult,
+  IATRResult,
+};
+
 export default VideoMinuteResultDAO;