ts-prorm-orm 1.1.0 → 1.2.0

package/dist/dialects/timescaledb/index.d.ts

@@ -0,0 +1,286 @@
+/**
+ * TimescaleDB dialect implementation for the TypeScript ORM
+ *
+ * TimescaleDB is not a separate database engine — it is a PostgreSQL extension
+ * (`CREATE EXTENSION timescaledb`) that layers time-series capabilities on top
+ * of a stock PostgreSQL server. Because of that, this dialect extends
+ * `PostgresDialect` and reuses the exact same `pg` driver, wire protocol, and
+ * default port (5432). Everything PostgreSQL can do, TimescaleDB can do; this
+ * subclass only adds thin SQL builders for TimescaleDB-specific features.
+ *
+ * TimescaleDB-specific helpers (pure, synchronous SQL builders — they return
+ * the SQL string so callers can run it through the inherited `query()`):
+ *
+ *  - `createExtensionSQL()`        → `CREATE EXTENSION IF NOT EXISTS timescaledb`
+ *  - `createHypertable()`          → `SELECT create_hypertable(...)`
+ *  - `addCompressionPolicy()`      → `SELECT add_compression_policy(...)`
+ *  - `addRetentionPolicy()`        → `SELECT add_retention_policy(...)`
+ *  - `createContinuousAggregate()` → `CREATE MATERIALIZED VIEW ... WITH (timescaledb.continuous) AS ...`
+ *  - `enableCompression()`         → `ALTER TABLE ... SET (timescaledb.compress, ...)`
+ *
+ * @see https://docs.timescale.com/
+ */
+import { PostgresDialect, PostgresDialectOptions } from '../postgres/index';
+/**
+ * Options for {@link TimescaleDBDialect.createHypertable}.
+ * @see https://docs.timescale.com/api/latest/hypertable/create_hypertable/
+ */
+export interface CreateHypertableOptions {
+    /**
+     * Chunk time interval. A string is treated as a PostgreSQL interval literal
+     * (e.g. `'7 days'`, `'1 hour'`) and emitted as
+     * `chunk_time_interval => INTERVAL '...'`. A number is treated as a raw
+     * integer interval (for hypertables partitioned on an integer/bigint time
+     * column rather than a timestamp) and emitted as
+     * `chunk_time_interval => <number>` with no `INTERVAL` keyword.
+     * @default '7 days'
+     */
+    chunkTimeInterval?: string | number;
+    /** Emit `if_not_exists => TRUE` so re-running is idempotent. */
+    ifNotExists?: boolean;
+    /**
+     * Emit `migrate_data => TRUE` to convert a table that already contains rows
+     * into a hypertable (moving existing data into chunks).
+     */
+    migrateData?: boolean;
+}
+/**
+ * Options for {@link TimescaleDBDialect.enableCompression}.
+ * @see https://docs.timescale.com/api/latest/compression/alter_table_compression/
+ */
+export interface EnableCompressionOptions {
+    /**
+     * Column(s) used to segment compressed data
+     * (`timescaledb.compress_segmentby`). Accepts a single column name or a list.
+     */
+    segmentBy?: string | string[];
+    /**
+     * Column(s) used to order data within a compressed chunk
+     * (`timescaledb.compress_orderby`), e.g. `'time DESC'`.
+     */
+    orderBy?: string | string[];
+}
+/**
+ * Options for {@link TimescaleDBDialect.addDimension} — add a secondary
+ * (space) partitioning dimension to an existing hypertable.
+ * @see https://docs.timescale.com/api/latest/hypertable/add_dimension/
+ */
+export interface AddDimensionOptions {
+    /**
+     * Number of hash partitions for a space dimension
+     * (`number_partitions => n`). Mutually exclusive with
+     * {@link chunkTimeInterval}.
+     */
+    numberPartitions?: number;
+    /**
+     * Interval for an additional time/range dimension
+     * (`chunk_time_interval => ...`). A string becomes an `INTERVAL '...'`
+     * literal; a number is emitted raw (integer time columns).
+     */
+    chunkTimeInterval?: string | number;
+    /** Emit `if_not_exists => TRUE` so re-running is idempotent. */
+    ifNotExists?: boolean;
+}
+/**
+ * Options for {@link TimescaleDBDialect.addContinuousAggregatePolicy} — the
+ * automatic refresh policy for a continuous aggregate.
+ * @see https://docs.timescale.com/api/latest/continuous-aggregates/add_continuous_aggregate_policy/
+ */
+export interface ContinuousAggregatePolicyOptions {
+    /**
+     * How far back the refresh window starts (`start_offset`). A string is an
+     * `INTERVAL '...'` literal, a number is a raw integer offset, and `null`
+     * emits `NULL` (refresh from the beginning of time).
+     */
+    startOffset: string | number | null;
+    /**
+     * How close to "now" the refresh window ends (`end_offset`). Same encoding
+     * rules as {@link startOffset}.
+     */
+    endOffset: string | number | null;
+    /** How often the policy runs (`schedule_interval`), e.g. `'1 hour'`. */
+    scheduleInterval: string | number;
+}
+/**
+ * TimescaleDB dialect — a PostgreSQL dialect (reusing the `pg` driver on the
+ * standard port 5432) extended with time-series helpers backed by the
+ * `timescaledb` extension.
+ */
+export declare class TimescaleDBDialect extends PostgresDialect {
+    readonly name: "postgres";
+    constructor(config?: PostgresDialectOptions);
+    /**
+     * Build the SQL that enables the TimescaleDB extension on the current
+     * database. Overrides the base `createExtension()` idea with a dedicated,
+     * synchronous SQL builder specifically for `timescaledb`.
+     *
+     * @param extensionName - Extension to enable. Defaults to `'timescaledb'`.
+     * @returns `CREATE EXTENSION IF NOT EXISTS timescaledb`
+     */
+    createExtensionSQL(extensionName?: string): string;
+    /**
+     * Format a TimescaleDB interval argument. Time-based hypertables use a
+     * PostgreSQL interval literal (`INTERVAL '7 days'`); integer-based
+     * hypertables use a bare integer (e.g. `86400000`). A number is emitted
+     * as a raw integer with no `INTERVAL` keyword; a string is wrapped in a
+     * safely-escaped `INTERVAL '...'` literal.
+     */
+    private formatInterval;
+    /**
+     * Build a `SELECT create_hypertable(...)` statement that converts a regular
+     * table into a TimescaleDB hypertable partitioned on a time column.
+     *
+     * @param table - Table to convert.
+     * @param timeColumn - The time/timestamp column to partition on.
+     * @param opts - Chunk interval and other options.
+     * @returns e.g. `SELECT create_hypertable('conditions', 'time', chunk_time_interval => INTERVAL '7 days')`
+     */
+    createHypertable(table: string, timeColumn: string, opts?: CreateHypertableOptions): string;
+    /**
+     * Build a `SELECT add_compression_policy(...)` statement that schedules
+     * automatic compression of chunks older than the given interval. The table
+     * must have compression enabled first (see {@link enableCompression}).
+     *
+     * @param table - Hypertable to add the policy to.
+     * @param olderThan - Age threshold. A string is a PostgreSQL interval literal
+     *   (e.g. `'30 days'`); a number is a raw integer threshold for hypertables
+     *   partitioned on an integer time column.
+     * @returns e.g. `SELECT add_compression_policy('conditions', INTERVAL '30 days')`
+     */
+    addCompressionPolicy(table: string, olderThan: string | number): string;
+    /**
+     * Build a `SELECT add_retention_policy(...)` statement that schedules
+     * automatic dropping of chunks older than the given interval.
+     *
+     * @param table - Hypertable to add the policy to.
+     * @param olderThan - Age threshold. A string is a PostgreSQL interval literal
+     *   (e.g. `'90 days'`); a number is a raw integer threshold for hypertables
+     *   partitioned on an integer time column.
+     * @returns e.g. `SELECT add_retention_policy('conditions', INTERVAL '90 days')`
+     */
+    addRetentionPolicy(table: string, olderThan: string | number): string;
+    /**
+     * Build a `CREATE MATERIALIZED VIEW ... WITH (timescaledb.continuous) AS ...`
+     * statement for a continuous aggregate — a TimescaleDB materialized view that
+     * is incrementally and automatically refreshed as new data arrives.
+     *
+     * @param viewName - Name of the continuous aggregate view to create.
+     * @param query - The `SELECT` query (typically using `time_bucket(...)`) that defines the aggregate.
+     * @returns e.g. `CREATE MATERIALIZED VIEW "daily_avg" WITH (timescaledb.continuous) AS SELECT ...`
+     */
+    createContinuousAggregate(viewName: string, query: string): string;
+    /**
+     * Build an `ALTER TABLE ... SET (timescaledb.compress, ...)` statement that
+     * enables native compression on a hypertable and optionally configures the
+     * segment-by / order-by columns.
+     *
+     * @param table - Hypertable to enable compression on.
+     * @param opts - Segment-by and order-by column configuration.
+     * @returns e.g. `ALTER TABLE "conditions" SET (timescaledb.compress, timescaledb.compress_segmentby = 'device_id')`
+     */
+    enableCompression(table: string, opts?: EnableCompressionOptions): string;
+    /**
+     * Format an interval-or-null argument for a policy function. `null` becomes
+     * the SQL literal `NULL`; otherwise delegates to {@link formatInterval}.
+     */
+    private formatIntervalOrNull;
+    /**
+     * Build a `SELECT add_dimension(...)` statement adding a secondary
+     * partitioning dimension (space or additional time) to a hypertable — used
+     * for multi-dimensional partitioning (e.g. partition by time AND device id).
+     *
+     * @returns e.g. `SELECT add_dimension('conditions', 'device_id', number_partitions => 4)`
+     */
+    addDimension(table: string, column: string, opts?: AddDimensionOptions): string;
+    /**
+     * Build a `SELECT drop_chunks(...)` statement that drops chunks older than
+     * (and, optionally, newer than) the given thresholds — the efficient way to
+     * expire time-series data by dropping whole chunks rather than deleting rows.
+     *
+     * @param table - Hypertable to drop chunks from.
+     * @param olderThan - Drop chunks older than this (interval literal or raw integer).
+     * @param newerThan - Optional lower bound (`newer_than =>`).
+     * @returns e.g. `SELECT drop_chunks('conditions', older_than => INTERVAL '3 months')`
+     */
+    dropChunks(table: string, olderThan: string | number, newerThan?: string | number): string;
+    /**
+     * Build a `SELECT show_chunks(...)` statement listing a hypertable's chunks,
+     * optionally filtered by age.
+     *
+     * @returns e.g. `SELECT show_chunks('conditions', older_than => INTERVAL '3 months')`
+     */
+    showChunks(table: string, olderThan?: string | number): string;
+    /**
+     * Build a `SELECT compress_chunk(...)` statement compressing a single chunk.
+     * @param chunk - Fully-qualified chunk name (e.g. `_timescaledb_internal._hyper_1_1_chunk`).
+     */
+    compressChunk(chunk: string, ifNotCompressed?: boolean): string;
+    /**
+     * Build a `SELECT decompress_chunk(...)` statement decompressing a chunk.
+     */
+    decompressChunk(chunk: string, ifCompressed?: boolean): string;
+    /**
+     * Build a `SELECT reorder_chunk(...)` statement that physically reorders a
+     * chunk by the given index to improve locality of range scans.
+     */
+    reorderChunk(chunk: string, indexName: string): string;
+    /**
+     * Build a `SELECT remove_compression_policy(...)` statement.
+     */
+    removeCompressionPolicy(table: string, ifExists?: boolean): string;
+    /**
+     * Build a `SELECT remove_retention_policy(...)` statement.
+     */
+    removeRetentionPolicy(table: string, ifExists?: boolean): string;
+    /**
+     * Build a `SELECT add_continuous_aggregate_policy(...)` statement that
+     * schedules automatic incremental refresh of a continuous aggregate.
+     *
+     * @returns e.g. `SELECT add_continuous_aggregate_policy('daily_avg',
+     *   start_offset => INTERVAL '1 month', end_offset => INTERVAL '1 hour',
+     *   schedule_interval => INTERVAL '1 hour')`
+     */
+    addContinuousAggregatePolicy(viewName: string, opts: ContinuousAggregatePolicyOptions): string;
+    /**
+     * Build a `SELECT remove_continuous_aggregate_policy(...)` statement.
+     */
+    removeContinuousAggregatePolicy(viewName: string, ifExists?: boolean): string;
+    /**
+     * Build a `CALL refresh_continuous_aggregate(...)` statement that manually
+     * refreshes a continuous aggregate over the `[start, end)` window. Pass
+     * `null` for an unbounded side (`NULL` = beginning/end of time).
+     *
+     * @returns e.g. `CALL refresh_continuous_aggregate('daily_avg', '2023-01-01', '2023-02-01')`
+     */
+    refreshContinuousAggregate(viewName: string, windowStart: string | null, windowEnd: string | null): string;
+    /**
+     * Build a `DROP MATERIALIZED VIEW ...` statement for a continuous aggregate
+     * (continuous aggregates are dropped as materialized views).
+     */
+    dropContinuousAggregate(viewName: string, opts?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): string;
+    /**
+     * Build a TimescaleDB `time_bucket(...)` expression for bucketing a timestamp
+     * column into fixed-width intervals — the core building block of a continuous
+     * aggregate's `SELECT`. Returns just the expression so callers can embed it
+     * in a larger query.
+     *
+     * @param interval - Bucket width. A string becomes `INTERVAL '...'`; a number
+     *   is emitted raw (integer time columns).
+     * @param column - The timestamp column to bucket.
+     * @returns e.g. `time_bucket(INTERVAL '1 hour', "ts")`
+     */
+    timeBucket(interval: string | number, column: string): string;
+}
+/**
+ * Options for constructing a {@link TimescaleDBDialect}. Identical to
+ * PostgreSQL's options since TimescaleDB reuses the `pg` driver.
+ */
+export type TimescaleDBDialectOptions = PostgresDialectOptions;
+/**
+ * Create a new TimescaleDB dialect instance.
+ */
+export declare function createTimescaleDBDialect(options?: TimescaleDBDialectOptions): TimescaleDBDialect;
+export default TimescaleDBDialect;

package/dist/dialects/timescaledb/index.js

@@ -153,6 +153,185 @@ class TimescaleDBDialect extends index_1.PostgresDialect {
         }
         return `ALTER TABLE ${this.quoteTable(table)} SET (${settings.join(', ')})`;
     }
+    /**
+     * Format an interval-or-null argument for a policy function. `null` becomes
+     * the SQL literal `NULL`; otherwise delegates to {@link formatInterval}.
+     */
+    formatIntervalOrNull(value) {
+        if (value === null) {
+            return 'NULL';
+        }
+        return this.formatInterval(value);
+    }
+    /**
+     * Build a `SELECT add_dimension(...)` statement adding a secondary
+     * partitioning dimension (space or additional time) to a hypertable — used
+     * for multi-dimensional partitioning (e.g. partition by time AND device id).
+     *
+     * @returns e.g. `SELECT add_dimension('conditions', 'device_id', number_partitions => 4)`
+     */
+    addDimension(table, column, opts) {
+        const args = [this.escape(table), this.escape(column)];
+        if (opts?.numberPartitions !== undefined) {
+            args.push(`number_partitions => ${opts.numberPartitions}`);
+        }
+        if (opts?.chunkTimeInterval !== undefined) {
+            args.push(`chunk_time_interval => ${this.formatInterval(opts.chunkTimeInterval)}`);
+        }
+        if (opts?.ifNotExists) {
+            args.push('if_not_exists => TRUE');
+        }
+        return `SELECT add_dimension(${args.join(', ')})`;
+    }
+    /**
+     * Build a `SELECT drop_chunks(...)` statement that drops chunks older than
+     * (and, optionally, newer than) the given thresholds — the efficient way to
+     * expire time-series data by dropping whole chunks rather than deleting rows.
+     *
+     * @param table - Hypertable to drop chunks from.
+     * @param olderThan - Drop chunks older than this (interval literal or raw integer).
+     * @param newerThan - Optional lower bound (`newer_than =>`).
+     * @returns e.g. `SELECT drop_chunks('conditions', older_than => INTERVAL '3 months')`
+     */
+    dropChunks(table, olderThan, newerThan) {
+        const args = [
+            this.escape(table),
+            `older_than => ${this.formatInterval(olderThan)}`,
+        ];
+        if (newerThan !== undefined) {
+            args.push(`newer_than => ${this.formatInterval(newerThan)}`);
+        }
+        return `SELECT drop_chunks(${args.join(', ')})`;
+    }
+    /**
+     * Build a `SELECT show_chunks(...)` statement listing a hypertable's chunks,
+     * optionally filtered by age.
+     *
+     * @returns e.g. `SELECT show_chunks('conditions', older_than => INTERVAL '3 months')`
+     */
+    showChunks(table, olderThan) {
+        const args = [this.escape(table)];
+        if (olderThan !== undefined) {
+            args.push(`older_than => ${this.formatInterval(olderThan)}`);
+        }
+        return `SELECT show_chunks(${args.join(', ')})`;
+    }
+    /**
+     * Build a `SELECT compress_chunk(...)` statement compressing a single chunk.
+     * @param chunk - Fully-qualified chunk name (e.g. `_timescaledb_internal._hyper_1_1_chunk`).
+     */
+    compressChunk(chunk, ifNotCompressed = true) {
+        const args = [this.escape(chunk)];
+        if (ifNotCompressed) {
+            args.push('if_not_compressed => TRUE');
+        }
+        return `SELECT compress_chunk(${args.join(', ')})`;
+    }
+    /**
+     * Build a `SELECT decompress_chunk(...)` statement decompressing a chunk.
+     */
+    decompressChunk(chunk, ifCompressed = true) {
+        const args = [this.escape(chunk)];
+        if (ifCompressed) {
+            args.push('if_compressed => TRUE');
+        }
+        return `SELECT decompress_chunk(${args.join(', ')})`;
+    }
+    /**
+     * Build a `SELECT reorder_chunk(...)` statement that physically reorders a
+     * chunk by the given index to improve locality of range scans.
+     */
+    reorderChunk(chunk, indexName) {
+        return `SELECT reorder_chunk(${this.escape(chunk)}, ${this.escape(indexName)})`;
+    }
+    /**
+     * Build a `SELECT remove_compression_policy(...)` statement.
+     */
+    removeCompressionPolicy(table, ifExists = false) {
+        const args = [this.escape(table)];
+        if (ifExists) {
+            args.push('if_exists => TRUE');
+        }
+        return `SELECT remove_compression_policy(${args.join(', ')})`;
+    }
+    /**
+     * Build a `SELECT remove_retention_policy(...)` statement.
+     */
+    removeRetentionPolicy(table, ifExists = false) {
+        const args = [this.escape(table)];
+        if (ifExists) {
+            args.push('if_exists => TRUE');
+        }
+        return `SELECT remove_retention_policy(${args.join(', ')})`;
+    }
+    /**
+     * Build a `SELECT add_continuous_aggregate_policy(...)` statement that
+     * schedules automatic incremental refresh of a continuous aggregate.
+     *
+     * @returns e.g. `SELECT add_continuous_aggregate_policy('daily_avg',
+     *   start_offset => INTERVAL '1 month', end_offset => INTERVAL '1 hour',
+     *   schedule_interval => INTERVAL '1 hour')`
+     */
+    addContinuousAggregatePolicy(viewName, opts) {
+        const args = [
+            this.escape(viewName),
+            `start_offset => ${this.formatIntervalOrNull(opts.startOffset)}`,
+            `end_offset => ${this.formatIntervalOrNull(opts.endOffset)}`,
+            `schedule_interval => ${this.formatInterval(opts.scheduleInterval)}`,
+        ];
+        return `SELECT add_continuous_aggregate_policy(${args.join(', ')})`;
+    }
+    /**
+     * Build a `SELECT remove_continuous_aggregate_policy(...)` statement.
+     */
+    removeContinuousAggregatePolicy(viewName, ifExists = false) {
+        const args = [this.escape(viewName)];
+        if (ifExists) {
+            args.push('if_exists => TRUE');
+        }
+        return `SELECT remove_continuous_aggregate_policy(${args.join(', ')})`;
+    }
+    /**
+     * Build a `CALL refresh_continuous_aggregate(...)` statement that manually
+     * refreshes a continuous aggregate over the `[start, end)` window. Pass
+     * `null` for an unbounded side (`NULL` = beginning/end of time).
+     *
+     * @returns e.g. `CALL refresh_continuous_aggregate('daily_avg', '2023-01-01', '2023-02-01')`
+     */
+    refreshContinuousAggregate(viewName, windowStart, windowEnd) {
+        const start = windowStart === null ? 'NULL' : this.escape(windowStart);
+        const end = windowEnd === null ? 'NULL' : this.escape(windowEnd);
+        return `CALL refresh_continuous_aggregate(${this.escape(viewName)}, ${start}, ${end})`;
+    }
+    /**
+     * Build a `DROP MATERIALIZED VIEW ...` statement for a continuous aggregate
+     * (continuous aggregates are dropped as materialized views).
+     */
+    dropContinuousAggregate(viewName, opts) {
+        let sql = 'DROP MATERIALIZED VIEW';
+        if (opts?.ifExists) {
+            sql += ' IF EXISTS';
+        }
+        sql += ` ${this.escapeId(viewName)}`;
+        if (opts?.cascade) {
+            sql += ' CASCADE';
+        }
+        return sql;
+    }
+    /**
+     * Build a TimescaleDB `time_bucket(...)` expression for bucketing a timestamp
+     * column into fixed-width intervals — the core building block of a continuous
+     * aggregate's `SELECT`. Returns just the expression so callers can embed it
+     * in a larger query.
+     *
+     * @param interval - Bucket width. A string becomes `INTERVAL '...'`; a number
+     *   is emitted raw (integer time columns).
+     * @param column - The timestamp column to bucket.
+     * @returns e.g. `time_bucket(INTERVAL '1 hour', "ts")`
+     */
+    timeBucket(interval, column) {
+        return `time_bucket(${this.formatInterval(interval)}, ${this.escapeId(column)})`;
+    }
 }
 exports.TimescaleDBDialect = TimescaleDBDialect;
 /**