diff --git a/src/api/client.ts b/src/api/client.ts index 5aef763..21adc51 100644 --- a/src/api/client.ts +++ b/src/api/client.ts @@ -44,6 +44,12 @@ export class DuneClient { /// Table Management Interface table: TableAPI; + /** + * Constructor for the DuneClient. + * + * @param {string} apiKey + * @returns Execution Results + */ constructor(apiKey: string) { this.exec = new ExecutionAPI(apiKey); this.query = new QueryAPI(apiKey); diff --git a/src/constants.ts b/src/constants.ts index e4fdb36..6b74eea 100644 --- a/src/constants.ts +++ b/src/constants.ts @@ -1,13 +1,21 @@ import { GetResultParams } from "./types/requestArgs"; -// Seconds between checking execution status +/* + * Seconds between checking execution status + */ export const POLL_FREQUENCY_SECONDS = 1; -// This is the expiry time on old query results. +/* + * This is the expiry time on old query results. + */ export const THREE_MONTHS_IN_HOURS = 2191; -// Headers used for pagination in CSV results +/* + * Headers used for pagination in CSV results + */ export const DUNE_CSV_NEXT_URI_HEADER = "x-dune-next-uri"; export const DUNE_CSV_NEXT_OFFSET_HEADER = "x-dune-next-offset"; -// Default maximum number of rows to retrieve per batch of results +/* + * Default maximum number of rows to retrieve per batch of results + */ export const MAX_NUM_ROWS_PER_BATCH = 32_000; export const DEFAULT_GET_PARAMS: GetResultParams = { diff --git a/src/types/error.ts b/src/types/error.ts index 98fcdb5..c01f1f6 100644 --- a/src/types/error.ts +++ b/src/types/error.ts @@ -1,4 +1,6 @@ -/// Basic Error structure meant to represent Dune API errors. +/* + * Basic Error structure meant to represent Dune API errors. + */ export class DuneError extends Error { constructor(msg: string) { super(msg); diff --git a/src/types/query.ts b/src/types/query.ts index dbfea3c..1c95712 100644 --- a/src/types/query.ts +++ b/src/types/query.ts @@ -2,33 +2,57 @@ import { QueryParameter } from "./queryParameter"; /** * Enriched structure representing all data constituting a DuneQuery. - * Modeling the CRUD operation response for `get_query` + * Modeling the CRUD operation response for 'get_query' * https://docs.dune.com/api-reference/queries/endpoint/read#example-return */ export interface DuneQuery { - /// Description of the query. + /** + * Description of the query. + */ description: string; - /// Indicates if the query is archived. - /// Note: This is as close as a user can get to deleting a query. + /** + * Indicates if the query is archived. + * Note: This is as close as a user can get to deleting a query. + */ is_archived: boolean; - /// Indicates if the query is private. + /** + * Indicates if the query is private. + */ is_private: boolean; - /// Indicates if the query is unsaved. + /** + * Indicates if the query is unsaved. + */ is_unsaved: boolean; - /// Name of the query. + /** + * Name of the query. + */ name: string; - /// Dune user who owns the query. + /** + * Dune user who owns the query. + */ owner: string; - /// Parameters with their names and default values. + /** + * Parameters with their names and default values. + */ parameters: QueryParameter[]; - /// The query engine used to execute the query. + /** + * The query engine used to execute the query. + */ query_engine: string; - /// Unique identifier of the query. + /** + * Unique identifier of the query. + */ query_id: number; - /// Raw SQL of the query. + /** + * Raw SQL of the query. + */ query_sql: string; - /// Tags associated with the query. + /** + * Tags associated with the query. + */ tags: string[]; - /// Version of the query. + /** + * Version of the query. + */ version: number; } diff --git a/src/types/queryParameter.ts b/src/types/queryParameter.ts index dc7fff4..21a8619 100644 --- a/src/types/queryParameter.ts +++ b/src/types/queryParameter.ts @@ -1,4 +1,6 @@ -/// All supported Dune Query Parameter types. +/* + * All supported Dune Query Parameter types. + */ export enum ParameterType { /// Note that text fields may also be used for varbinary data types. TEXT = "text", @@ -7,7 +9,9 @@ export enum ParameterType { ENUM = "enum", } -/// Class representing Dune Query Parameters with convience constructor methods for each type. +/* + * Class representing Dune Query Parameters with convience constructor methods for each type. + */ export class QueryParameter { type: ParameterType; value: string; diff --git a/src/types/requestArgs.ts b/src/types/requestArgs.ts index 765ef01..d7e925e 100644 --- a/src/types/requestArgs.ts +++ b/src/types/requestArgs.ts @@ -1,18 +1,25 @@ import assert from "assert"; import { QueryParameter } from "./queryParameter"; -/// Optional parameters for query exection. +/* + * Optional parameters for query exection. + */ export interface ExecutionParams { query_parameters?: QueryParameter[]; performance?: QueryEngine; } -/// Choice of execution engine when executing query via API [default = medium] +/* + * Choice of execution engine when executing query via API [default = medium] + */ export enum QueryEngine { Medium = "medium", Large = "large", } +/* + * Payload sent when uploading a CSV file to Dune. + */ export type UploadCSVArgs = { table_name: string; data: string; @@ -20,7 +27,9 @@ export type UploadCSVArgs = { is_private?: boolean; }; -/// Payload sent upon requests to Dune API. +/* + * Payload sent upon requests to Dune API. + */ export type RequestPayload = | GetResultParams | ExecuteQueryParams @@ -31,7 +40,9 @@ export type RequestPayload = | InsertTableArgs | Buffer; -/// Utility method used by router to parse request payloads. +/* + * Utility method used by router to parse request payloads. + */ export function payloadJSON(payload?: RequestPayload): string { return JSON.stringify(payloadRecords(payload)); } @@ -101,31 +112,43 @@ interface BaseParams { } export interface GetResultParams extends BaseParams { - /// Limit number of rows to return. - /// This together with 'offset' allows easy pagination through results in an incremental and efficient way. - /// This parameter is incompatible with sampling (`sample_count`). + /* + * Limit number of rows to return. + * This together with 'offset' allows easy pagination through results in an incremental and efficient way. + * This parameter is incompatible with sampling (`sample_count`). + */ limit?: number; - /// Offset row number to start (inclusive, first row means offset=0) returning results from. - /// This together with 'limit' allows easy pagination through results. - /// This parameter is incompatible with sampling (`sample_count`). + /* + * Offset row number to start (inclusive, first row means offset=0) returning results from. + * This together with 'limit' allows easy pagination through results. + * This parameter is incompatible with sampling (`sample_count`). + */ offset?: number; - /// Number of rows to return from the result by sampling the data. - /// This is useful when you want to get a uniform sample instead of the entire result. - /// If the result has less than the sample count, the entire result is returned. - /// Note that this will return a randomized sample, so not every call will return the same result. - /// This parameter is incompatible with `offset`, `limit`, and `filters` parameters. + /* + * Number of rows to return from the result by sampling the data. + * This is useful when you want to get a uniform sample instead of the entire result. + * If the result has less than the sample count, the entire result is returned. + * Note that this will return a randomized sample, so not every call will return the same result. + * This parameter is incompatible with `offset`, `limit`, and `filters` parameters. + */ sample_count?: number; - /// Expression to filter out rows from the results to return. - /// This expression is similar to a SQL WHERE clause. - /// More details about it in the [Filtering](https://docs.dune.com/api-reference/executions/filtering) section of the doc. - /// This parameter is incompatible with `sample_count`. + /* + * Expression to filter out rows from the results to return. + * This expression is similar to a SQL WHERE clause. + * More details about it in the [Filtering](https://docs.dune.com/api-reference/executions/filtering) section of the doc. + * This parameter is incompatible with `sample_count`. + */ filters?: string; - /// Expression to define the order in which the results should be returned. - /// This expression is similar to a SQL ORDER BY clause. - /// More details about it in the [Sorting](https://docs.dune.com/api-reference/executions/sorting) section of the doc. + /* + * Expression to define the order in which the results should be returned. + * This expression is similar to a SQL ORDER BY clause. + * More details about it in the [Sorting](https://docs.dune.com/api-reference/executions/sorting) section of the doc. + */ sort_by?: string[] | string; - /// Specified columns to be returned. If omitted, all columns are included. - /// Tip: use this to limit the result to specific columns, reducing datapoints cost of the call. + /* + * Specified columns to be returned. If omitted, all columns are included. + * Tip: use this to limit the result to specific columns, reducing datapoints cost of the call. + */ columns?: string[] | string; } @@ -180,29 +203,40 @@ export function validateAndBuildGetResultParams({ } export interface ExecuteQueryParams extends BaseParams { - /// The performance engine tier the execution will be run on. - /// Can be either medium or large. - /// Medium consumes 10 credits, and large consumes 20 credits, per run. - /// Default is medium. + /* The performance engine tier the execution will be run on. + * Can be either medium or large. + * Medium consumes 10 credits, and large consumes 20 credits, per run. + * Default is medium. + */ performance: QueryEngine; } export interface BaseCRUDParams extends BaseParams { - /// Description of the query. + /** + * Description of the query. + */ description?: string; - /// Name of the query. + /** + * Name of the query. + */ name?: string; - /// The SQL query text. + /** + * The SQL query text. + */ query_sql: string; } -/// Payload sent with query update requests. +/** + * Payload sent with query update requests. + */ export interface UpdateQueryParams extends BaseCRUDParams { /// Tags to be added (overrides existing tags). tags?: string[]; } -/// Payload sent with query creation requests. +/* + * Payload sent with query creation requests. + */ export interface CreateQueryParams extends BaseCRUDParams { /// Indicates if the query is private. is_private?: boolean; @@ -217,34 +251,52 @@ export enum ColumnType { } export interface SchemaRecord { - /// The column name. Can contain letters, numbers, and underscores, - /// but must begin with a letter or an underscore. + /* + * The column name. Can contain letters, numbers, and underscores, + * but must begin with a letter or an underscore. + */ name: string; - /// The column type. + /* + * The column type. + */ type: ColumnType; } export interface DeleteTableArgs { - /// The namespace of the table to delete (e.g. my_user). + /* + * The namespace of the table to delete (e.g. my_user). + */ namespace: string; - /// The name of the table to delete (e.g. interest_rates). + /* + * The name of the table to delete (e.g. interest_rates). + */ table_name: string; } export interface CreateTableArgs { - /// A description of the table. + /* + * A description of the table. + */ description?: string; - /// If true, the table will be private. - /// If private it is only visible to the team or user that your API key is associated with. + /* + * If true, the table will be private. + * If private it is only visible to the team or user that your API key is associated with. + */ is_private?: boolean; - /// The namespace of the table to create. - /// Must be the name of your associated API key, i.e. either `my_user` or `my_team`. + /* + * The namespace of the table to create. + * Must be the name of your associated API key, i.e. either `my_user` or `my_team`. + */ namespace: string; - /// An ordered list of columns that define the table schema. Cannot be empty. + /* + * An ordered list of columns that define the table schema. Cannot be empty. + */ schema: SchemaRecord[]; - /// The name of the table to create. - /// Must begin with a lowercase letter and contain only lowercase letters, - /// digits, and underscores. + /* + * The name of the table to create. + * Must begin with a lowercase letter and contain only lowercase letters, + * digits, and underscores. + */ table_name: string; } @@ -258,46 +310,72 @@ export enum ContentType { } export interface InsertTableArgs { - /// The namespace of the table to insert into (e.g. `my_user`). + /* + * The namespace of the table to insert into (e.g. `my_user`). + */ namespace: string; - /// The name of the table to insert into (e.g. `interest_rates`). + /* + * The name of the table to insert into (e.g. `interest_rates`). + */ table_name: string; - /// The body is of type file. + /* + * The body is of type file. + */ data: Buffer; content_type: ContentType; } export interface Options { - /// The page size when retriving results. + /* + * The page size when retriving results. + */ batchSize?: number; - /// How frequently should we check execution status + /* + * How frequently should we check execution status + */ pingFrequency?: number; - /// Determines result expiry date. + /* + * Determines result expiry date. + */ maxAgeHours?: number; } export interface RunQueryArgs extends GetResultParams, ExecutionParams { - /// ID of the query. + /* + * ID of the query. + */ queryId: number; opts?: Options; } export interface LatestResultArgs { - /// ID of the query. + /* + * ID of the query. + */ queryId: number; parameters?: QueryParameter[]; opts?: Options; } export interface RunSqlArgs extends ExecutionParams { - /// raw sql of query to run (Trino/DuneSQL syntax) + /* + * raw sql of query to run (Trino/DuneSQL syntax) + */ query_sql: string; - /// Name of created query. + /* + * Name of created query. + */ name?: string; - /// Whether the created query should be private or not (default = true). + /* + * Whether the created query should be private or not (default = true). + */ isPrivate?: boolean; - /// Whether the created query should be archived immediately after execution or not (default = true). + /* + * Whether the created query should be archived immediately after execution or not (default = true). + */ archiveAfter?: boolean; - /// Additional options execution options. + /* + * Additional options execution options. + */ opts?: Options; } diff --git a/src/types/response.ts b/src/types/response.ts index 06838e5..c3f1608 100644 --- a/src/types/response.ts +++ b/src/types/response.ts @@ -1,4 +1,6 @@ -/// Various possible states of a query exeuction. +/* + * Various possible states of a query exeuction. + */ export enum ExecutionState { COMPLETED = "QUERY_STATE_COMPLETED", EXECUTING = "QUERY_STATE_EXECUTING", @@ -35,13 +37,17 @@ export function concatResultCSV( }; } -/// Response resturned from query execution request. +/* + * Response resturned from query execution request. + */ export interface ExecutionResponse { execution_id: string; state: ExecutionState; } -/// Response resturned from query creation request. +/* + * Response resturned from query creation request. + */ export interface CreateQueryResponse { query_id: number; } @@ -50,91 +56,157 @@ export type SuccessResponse = { success: boolean; }; -/// Various query times related to an query status request. +/* + * Various query times related to an query status request. + */ export interface TimeData { submitted_at: Date; - /// Timestamp of when the query execution started. + /* + * Timestamp of when the query execution started. + */ execution_started_at?: Date; - /// Timestamp of when the query execution ended. + /* + * Timestamp of when the query execution ended. + */ execution_ended_at?: Date; - /// Timestamp of when the query result expires. + /* + * Timestamp of when the query result expires. + */ expires_at?: Date; - /// Timestamp of when the query execution was cancelled, if applicable. + /* + * Timestamp of when the query execution was cancelled, if applicable. + */ cancelled_at?: Date; } -/// Metadata contained within a quer `ExecutionResult` +/* + * Metadata contained within a quer `ExecutionResult` + */ export interface ResultMetadata { - /// Names of the columns contained in the query results. + /* + * Names of the columns contained in the query results. + */ column_names: string[]; - /// Total number of data points in result. - /// Used as part of the API credits computation. + /* + * Total number of data points in result. + * Used as part of the API credits computation. + */ datapoint_count: number; - /// Time in milliseconds that the query took to execute. + /* + * Time in milliseconds that the query took to execute. + */ execution_time_millis: number; - /// How long they query was pending (in the queue) before execution began. + /* + * How long they query was pending (in the queue) before execution began. + */ pending_time_millis: number; - // Number of bytes in the result set for the current page of results. + /* + * Number of bytes in the result set for the current page of results. + */ result_set_bytes: number; - // Number of rows in the result set for the current page of results. + /* + * Number of rows in the result set for the current page of results. + */ row_count: number; - // Total number of bytes in the result set. This doesn't include the json representation overhead. + /* + * Total number of bytes in the result set. This doesn't include the json representation overhead. + */ total_result_set_bytes: number; - // Total number of rows in the result set. + /* + * Total number of rows in the result set. + */ total_row_count: number; } -/// Status resonse fields contained in both Incomplete and Complete ExecutionStatus Responses. +/* + * Status resonse fields contained in both Incomplete and Complete ExecutionStatus Responses. + */ interface BaseStatusResponse extends TimeData { - // Unique identifier for the execution of the query. + /* + * Unique identifier for the execution of the query. + */ execution_id: string; - // Unique identifier of the query. + /* + * Unique identifier of the query. + */ query_id: number; queue_position?: number; } -/// Format of a `GetStatusResponse` when the query execution is anything but complete. +/* + * Format of a `GetStatusResponse` when the query execution is anything but complete. + */ interface IncompleteStatusResponse extends BaseStatusResponse { - // The state of the query execution. + /* + * The state of the query execution. + */ state: Exclude; } -/// Format of `GetStatusResponse` when a query execution has completed. +/* + * Format of `GetStatusResponse` when a query execution has completed. + */ interface CompleteStatusResponse extends BaseStatusResponse { - // The state of the query execution. + /* + * The state of the query execution. + */ state: ExecutionState.COMPLETED; - // Metadata about the execution of the query, including details like column names, - // row counts, and execution times. + /* + * Metadata about the execution of the query, including details like column names, + * row counts, and execution times. + */ result_metadata: ResultMetadata; } export type GetStatusResponse = IncompleteStatusResponse | CompleteStatusResponse; -/// Result of a Query Execution. +/* + * Result of a Query Execution. + */ export interface ExecutionResult { - // A list of rows. A row is dictionary of key-value pairs returned by the query, - // each pair corresponding to a column + /* + * A list of rows. A row is dictionary of key-value pairs returned by the query, + * each pair corresponding to a column + */ rows: Record[]; - // Metadata about the execution of the query, including details like column names, - // row counts, and execution times. + /* + * Metadata about the execution of the query, including details like column names, + * row counts, and execution times. + */ metadata: ResultMetadata; } -/// Response of reqeust for results of a query execution. +/* + * Response of reqeust for results of a query execution. + */ export interface ResultsResponse extends TimeData { - // Unique identifier for the execution of the query. + /* + * Unique identifier for the execution of the query. + */ execution_id: string; - // Unique identifier of the query. + /* + * Unique identifier of the query. + */ query_id: number; - // Whether the state of the query execution is terminal. This can be used for polling purposes. + /* + * Whether the state of the query execution is terminal. This can be used for polling purposes. + */ is_execution_finished: boolean; - // Offset that can be used to retrieve the next page of results. + /* + * Offset that can be used to retrieve the next page of results. + */ next_offset: number; - // URI that can be used to fetch the next page of results. + /* + * URI that can be used to fetch the next page of results. + */ next_uri: string; - // The state of the query execution. + /* + * The state of the query execution. + */ state: ExecutionState; - // only present when state is COMPLETE + /* + * only present when state is COMPLETE + */ result?: ExecutionResult; } @@ -190,18 +262,28 @@ function concatResultMetadata( } export interface DeleteTableResult { - /// The confirmation message of the deleted table + /* + * The confirmation message of the deleted table + */ message: string; } export interface CreateTableResult { - /// An example query to use on Dune querying your new table. + /* + * An example query to use on Dune querying your new table. + */ example_query: string; - /// The full name of the created table, as it should be referred to in a query. + /* + * The full name of the created table, as it should be referred to in a query. + */ full_name: string; - /// The namespace of the created table. + /* + * The namespace of the created table. + */ namespace: string; - /// The name of the created table. + /* + * The name of the created table. + */ table_name: string; }