Always return an object

Author: matt-aitken

packages/trigger-sdk/src/v3/query.ts

@@ -12,7 +12,7 @@ export type QueryFormat = "json" | "csv";
 /**
  * Options for executing a TSQL query
  */
-export type QueryOptions<TFormat extends QueryFormat | undefined = QueryFormat | undefined> = {
+export type QueryOptions = {
   /**
    * The scope of the query - determines what data is accessible
    * - "environment": Current environment only (default)
@@ -48,74 +48,89 @@ export type QueryOptions<TFormat extends QueryFormat | undefined = QueryFormat |
    *
    * @default "json"
    */
-  format?: TFormat;
+  format?: QueryFormat;
 };
 
 /**
- * Result type that automatically narrows based on the format option
- * @template TFormat - The format type (json or csv)
- * @template TRow - The shape of each row in the result set
+ * Execute a TSQL query and export as CSV
  */
-export type QueryResult<
-  TFormat extends QueryFormat | undefined = undefined,
-  TRow extends Record<string, any> = Record<string, any>
-> = TFormat extends "csv"
-  ? QueryExecuteCSVResponseBody
-  : TFormat extends "json"
-  ? { rows: Array<TRow> }
-  : TFormat extends undefined
-  ? { rows: Array<TRow> }
-  : { rows: Array<TRow> } | QueryExecuteCSVResponseBody;
+function execute(
+  tsql: string,
+  options: QueryOptions & { format: "csv" },
+  requestOptions?: ApiRequestOptions
+): Promise<{ format: "csv"; results: string }>;
+
+/**
+ * Execute a TSQL query and return typed JSON rows
+ */
+function execute<TRow extends Record<string, any> = Record<string, any>>(
+  tsql: string,
+  options?: Omit<QueryOptions, "format"> | (QueryOptions & { format?: "json" }),
+  requestOptions?: ApiRequestOptions
+): Promise<{ format: "json"; results: Array<TRow> }>;
 
 /**
  * Execute a TSQL query against your Trigger.dev data
  *
- * @template TFormat - The format of the response (inferred from options)
+ * @template TRow - The shape of each row in the result set (provide for type safety)
  * @param {string} tsql - The TSQL query string to execute
- * @param {QueryOptions<TFormat>} [options] - Optional query configuration
+ * @param {QueryOptions} [options] - Optional query configuration
  * @param {ApiRequestOptions} [requestOptions] - Optional API request configuration
  * @returns A promise that resolves with the query results
  *
  * @example
  * ```typescript
  * // Basic query with defaults (environment scope, json format)
  * const result = await query.execute("SELECT * FROM runs LIMIT 10");
- * console.log(result.rows);
+ * console.log(result.format); // "json"
+ * console.log(result.results); // Array<Record<string, any>>
  *
- * // Query with custom period
- * const lastMonth = await query.execute(
- *   "SELECT COUNT(*) as count FROM runs",
- *   { period: "30d" }
+ * // Type-safe query with row type
+ * type RunRow = { id: string; status: string; duration: number };
+ * const typedResult = await query.execute<RunRow>(
+ *   "SELECT id, status, duration FROM runs LIMIT 10"
  * );
+ * typedResult.results.forEach(row => {
+ *   console.log(row.id, row.status); // Fully typed!
+ * });
  *
- * // Query with custom date range
- * const januaryRuns = await query.execute(
- *   "SELECT * FROM runs",
- *   {
- *     from: "2025-01-01T00:00:00Z",
- *     to: "2025-02-01T00:00:00Z"
- *   }
+ * // Inline type for aggregation query
+ * const stats = await query.execute<{ status: string; count: number }>(
+ *   "SELECT status, COUNT(*) as count FROM runs GROUP BY status"
  * );
+ * stats.results.forEach(row => {
+ *   console.log(row.status, row.count); // Fully type-safe
+ * });
  *
- * // Organization-wide query
- * const orgStats = await query.execute(
- *   "SELECT project, COUNT(*) as count FROM runs GROUP BY project",
- *   { scope: "organization", period: "7d" }
+ * // Query with custom period
+ * const lastMonth = await query.execute(
+ *   "SELECT COUNT(*) as count FROM runs",
+ *   { period: "30d" }
  * );
+ * console.log(lastMonth.results[0].count); // Type-safe access
  *
- * // Export as CSV
- * const csvData = await query.execute(
+ * // Export as CSV - automatically narrowed!
+ * const csvResult = await query.execute(
  *   "SELECT * FROM runs",
  *   { format: "csv", period: "7d" }
  * );
- * // csvData is a string containing CSV
+ * console.log(csvResult.format); // "csv"
+ * const lines = csvResult.results.split('\n'); // ✓ results is string
+ *
+ * // Discriminated union - can check format at runtime
+ * const dynamicResult = await query.execute("SELECT * FROM runs");
+ * if (dynamicResult.format === "json") {
+ *   dynamicResult.results.forEach(row => console.log(row)); // ✓ Typed as array
+ * } else {
+ *   console.log(dynamicResult.results.length); // ✓ Typed as string
+ * }
  * ```
  */
-function execute<TFormat extends QueryFormat | undefined = undefined>(
+function execute<TRow extends Record<string, any> = Record<string, any>>(
   tsql: string,
-  options?: QueryOptions<TFormat>,
+  options?: QueryOptions,
   requestOptions?: ApiRequestOptions
-): Promise<QueryResult<TFormat>> {
+): Promise<{ format: "json"; results: Array<TRow> } | { format: "csv"; results: string }> {
   const apiClient = apiClientManager.clientOrThrow();
 
   const $requestOptions = mergeRequestOptions(
@@ -131,7 +146,14 @@ function execute<TFormat extends QueryFormat | undefined = undefined>(
     requestOptions
   );
 
-  return apiClient.executeQuery(tsql, options, $requestOptions) as Promise<QueryResult<TFormat>>;
+  const format = options?.format ?? "json";
+
+  return apiClient.executeQuery(tsql, options, $requestOptions).then((response) => {
+    if (typeof response === "string") {
+      return { format: "csv" as const, results: response };
+    }
+    return { format: "json" as const, results: response.rows };
+  }) as Promise<{ format: "json"; results: Array<TRow> } | { format: "csv"; results: string }>;
 }
 
 export const query = {

references/hello-world/src/trigger/query.ts

@@ -1,5 +1,13 @@
 import { logger, query, task } from "@trigger.dev/sdk";
 
+// Type definition for a run row
+type RunRow = {
+  id: string;
+  status: string;
+  created_at: string;
+  duration: number;
+};
+
 // Simple query example - just the query string, all defaults
 export const simpleQueryTask = task({
   id: "simple-query",
@@ -9,31 +17,51 @@ export const simpleQueryTask = task({
     // Simplest usage - uses environment scope, json format, default period
     const result = await query.execute("SELECT * FROM runs LIMIT 10");
 
-    logger.info("Query results", {
-      rowCount: result.rows.length,
-      firstRow: result.rows[0],
+    logger.info("Query results (untyped)", {
+      format: result.format,
+      rowCount: result.results.length,
+      firstRow: result.results[0],
+    });
+
+    // Type-safe query with explicit row type
+    const typedResult = await query.execute<RunRow>(
+      "SELECT id, status, created_at, duration FROM runs LIMIT 10"
+    );
+
+    logger.info("Query results (typed)", {
+      format: typedResult.format,
+      rowCount: typedResult.results.length,
+      firstRow: typedResult.results[0],
     });
 
-    // Log all rows
-    result.rows.forEach((row, index) => {
-      logger.info(`Row ${index + 1}`, { row });
+    // Now we have full type safety on the rows!
+    typedResult.results.forEach((row, index) => {
+      logger.info(`Run ${index + 1}`, {
+        id: row.id, // TypeScript knows this is a string
+        status: row.status, // TypeScript knows this is a string
+        duration: row.duration, // TypeScript knows this is a number
+      });
     });
 
     return {
-      totalRows: result.rows.length,
-      rows: result.rows,
+      totalRows: typedResult.results.length,
+      rows: typedResult.results,
     };
   },
 });
 
-// JSON query with all options
+// JSON query with all options and inline type
 export const fullJsonQueryTask = task({
   id: "full-json-query",
   run: async () => {
     logger.info("Running full JSON query example with all options");
 
-    // All options specified
-    const result = await query.execute(
+    // All options specified with inline type for aggregation
+    const result = await query.execute<{
+      status: string;
+      count: number;
+      avg_duration: number;
+    }>(
       `SELECT
         status,
         COUNT(*) as count,
@@ -44,25 +72,26 @@ export const fullJsonQueryTask = task({
       {
         scope: "environment", // Query current environment only
         period: "30d", // Last 30 days of data
-        format: "json", // JSON format (default)
+        // format defaults to "json"
       }
     );
 
     logger.info("Query completed", {
-      rowCount: result.rows.length,
+      format: result.format,
+      rowCount: result.results.length,
     });
 
-    // Log the aggregated results
-    result.rows.forEach((row) => {
+    // Log the aggregated results - now fully type-safe!
+    result.results.forEach((row) => {
       logger.info("Status breakdown", {
-        status: row.status,
-        count: row.count,
-        averageDuration: row.avg_duration,
+        status: row.status, // string
+        count: row.count, // number
+        averageDuration: row.avg_duration, // number
       });
     });
 
     return {
-      summary: result.rows,
+      summary: result.results,
     };
   },
 });
@@ -73,8 +102,8 @@ export const csvQueryTask = task({
   run: async () => {
     logger.info("Running CSV query example");
 
-    // Query with CSV format - returns a string
-    const csvData = await query.execute(
+    // Query with CSV format - automatically typed as discriminated union!
+    const result = await query.execute(
       "SELECT id, status, created_at, duration FROM runs LIMIT 100",
       {
         scope: "project", // Query all environments in the project
@@ -83,13 +112,15 @@ export const csvQueryTask = task({
       }
     );
 
+    // result.format is "csv" and result.results is automatically typed as string!
     logger.info("CSV query completed", {
-      dataLength: csvData.length,
-      preview: csvData.substring(0, 200), // Show first 200 chars
+      format: result.format,
+      dataLength: result.results.length,
+      preview: result.results.substring(0, 200), // Show first 200 chars
     });
 
     // Count the number of rows (lines - 1 for header)
-    const lines = csvData.split("\n");
+    const lines = result.results.split("\n");
     const rowCount = lines.length - 1;
 
     logger.info("CSV stats", {
@@ -98,19 +129,29 @@ export const csvQueryTask = task({
     });
 
     return {
-      csv: csvData,
+      format: result.format,
+      csv: result.results,
       rowCount,
     };
   },
 });
 
-// Organization-wide query with date range
+// Organization-wide query with date range and type safety
 export const orgQueryTask = task({
   id: "org-query",
   run: async () => {
     logger.info("Running organization-wide query");
 
-    const result = await query.execute(
+    // Define the shape of our aggregated results
+    type ProjectStats = {
+      project: string;
+      environment: string;
+      total_runs: number;
+      successful_runs: number;
+      failed_runs: number;
+    };
+
+    const result = await query.execute<ProjectStats>(
       `SELECT
         project,
         environment,
@@ -124,25 +165,31 @@ export const orgQueryTask = task({
         scope: "organization", // Query across all projects
         from: "2025-02-01T00:00:00Z", // Custom date range
         to: "2025-02-11T23:59:59Z",
-        format: "json",
+        // format defaults to "json"
       }
     );
 
     logger.info("Organization query completed", {
-      projectCount: result.rows.length,
+      format: result.format,
+      projectCount: result.results.length,
     });
 
-    result.rows.forEach((row) => {
+    // Full type safety on aggregated results
+    result.results.forEach((row) => {
+      const successRate = (row.successful_runs / row.total_runs) * 100;
+
       logger.info("Project stats", {
         project: row.project,
         environment: row.environment,
         totalRuns: row.total_runs,
-        successRate: `${((row.successful_runs / row.total_runs) * 100).toFixed(2)}%`,
+        successfulRuns: row.successful_runs,
+        failedRuns: row.failed_runs,
+        successRate: `${successRate.toFixed(2)}%`,
       });
     });
 
     return {
-      projects: result.rows,
+      projects: result.results,
     };
   },
 });