@dotdo/postgres 0.1.0

package/dist/iceberg/time-travel.js

@@ -0,0 +1,689 @@
+/**
+ * Time Travel Query API
+ * Task: postgres-3kc - Time travel query API (query as-of timestamp)
+ *
+ * Enables querying data as of a specific timestamp using Iceberg snapshots.
+ * Supports:
+ * - Point-in-time queries (exact snapshot at timestamp)
+ * - Relative timestamps (e.g., '1 hour ago')
+ * - SQL AS OF syntax parsing
+ * - Query routing to appropriate storage
+ */
+/**
+ * Error thrown when timestamp is out of retention range
+ */
+export class TimestampOutOfRangeError extends Error {
+    requestedTimestamp;
+    oldestAvailable;
+    newestAvailable;
+    constructor(requestedTimestamp, oldestAvailable, newestAvailable) {
+        const requested = new Date(requestedTimestamp).toISOString();
+        const oldest = new Date(oldestAvailable).toISOString();
+        const newest = new Date(newestAvailable).toISOString();
+        super(`Requested timestamp ${requested} is out of range. ` +
+            `Available range: ${oldest} to ${newest}`);
+        this.requestedTimestamp = requestedTimestamp;
+        this.oldestAvailable = oldestAvailable;
+        this.newestAvailable = newestAvailable;
+        this.name = 'TimestampOutOfRangeError';
+    }
+}
+/**
+ * Error thrown when no snapshot is found
+ */
+export class NoSnapshotFoundError extends Error {
+    requestedTimestamp;
+    constructor(requestedTimestamp) {
+        super(`No snapshot found for timestamp ${new Date(requestedTimestamp).toISOString()}. ` +
+            `The table may not have any data yet.`);
+        this.requestedTimestamp = requestedTimestamp;
+        this.name = 'NoSnapshotFoundError';
+    }
+}
+/**
+ * Error thrown for invalid timestamp format
+ */
+export class InvalidTimestampError extends Error {
+    input;
+    constructor(input) {
+        super(`Invalid timestamp format: ${String(input)}`);
+        this.input = input;
+        this.name = 'InvalidTimestampError';
+    }
+}
+// ============================================================================
+// Timestamp Parsing
+// ============================================================================
+/**
+ * Relative time patterns and their millisecond multipliers
+ */
+const RELATIVE_TIME_PATTERNS = [
+    { pattern: /^(\d+)\s*(ms|milliseconds?)\s*ago$/i, multiplier: 1 },
+    { pattern: /^(\d+)\s*(s|sec|seconds?)\s*ago$/i, multiplier: 1000 },
+    { pattern: /^(\d+)\s*(m|min|minutes?)\s*ago$/i, multiplier: 60 * 1000 },
+    { pattern: /^(\d+)\s*(h|hr|hours?)\s*ago$/i, multiplier: 60 * 60 * 1000 },
+    { pattern: /^(\d+)\s*(d|days?)\s*ago$/i, multiplier: 24 * 60 * 60 * 1000 },
+    { pattern: /^(\d+)\s*(w|wk|weeks?)\s*ago$/i, multiplier: 7 * 24 * 60 * 60 * 1000 },
+    { pattern: /^(\d+)\s*(mo|months?)\s*ago$/i, multiplier: 30 * 24 * 60 * 60 * 1000 },
+    { pattern: /^(\d+)\s*(y|yr|years?)\s*ago$/i, multiplier: 365 * 24 * 60 * 60 * 1000 },
+];
+/**
+ * SQL INTERVAL patterns for PostgreSQL-style interval syntax
+ * Matches: INTERVAL '1 hour', INTERVAL '30 minutes', etc.
+ */
+const SQL_INTERVAL_PATTERNS = [
+    { pattern: /^interval\s*'(\d+)\s*(ms|milliseconds?)'$/i, multiplier: 1 },
+    { pattern: /^interval\s*'(\d+)\s*(s|sec|seconds?)'$/i, multiplier: 1000 },
+    { pattern: /^interval\s*'(\d+)\s*(m|min|minutes?)'$/i, multiplier: 60 * 1000 },
+    { pattern: /^interval\s*'(\d+)\s*(h|hr|hours?)'$/i, multiplier: 60 * 60 * 1000 },
+    { pattern: /^interval\s*'(\d+)\s*(d|days?)'$/i, multiplier: 24 * 60 * 60 * 1000 },
+    { pattern: /^interval\s*'(\d+)\s*(w|wk|weeks?)'$/i, multiplier: 7 * 24 * 60 * 60 * 1000 },
+    { pattern: /^interval\s*'(\d+)\s*(mo|months?)'$/i, multiplier: 30 * 24 * 60 * 60 * 1000 },
+    { pattern: /^interval\s*'(\d+)\s*(y|yr|years?)'$/i, multiplier: 365 * 24 * 60 * 60 * 1000 },
+];
+/**
+ * Parse a timestamp specification into milliseconds since epoch
+ */
+export function parseTimestamp(spec, referenceTime) {
+    const now = referenceTime ?? Date.now();
+    // Already a number (epoch ms)
+    if (typeof spec === 'number') {
+        return {
+            timestampMs: spec,
+            original: spec,
+            isRelative: false,
+        };
+    }
+    // Date object
+    if (spec instanceof Date) {
+        return {
+            timestampMs: spec.getTime(),
+            original: spec,
+            isRelative: false,
+        };
+    }
+    // String - try various formats
+    if (typeof spec === 'string') {
+        const trimmed = spec.trim();
+        // Check for NOW() or CURRENT_TIMESTAMP (case insensitive)
+        if (/^(now\(\)|current_timestamp)$/i.test(trimmed)) {
+            return {
+                timestampMs: now,
+                original: spec,
+                isRelative: true,
+            };
+        }
+        // Check for NOW() - INTERVAL or CURRENT_TIMESTAMP - INTERVAL patterns
+        const nowMinusIntervalMatch = trimmed.match(/^(now\(\)|current_timestamp)\s*-\s*interval\s*'(\d+)\s*(\w+)'$/i);
+        if (nowMinusIntervalMatch) {
+            const value = parseInt(nowMinusIntervalMatch[2], 10);
+            const unit = nowMinusIntervalMatch[3].toLowerCase();
+            const multiplier = getIntervalMultiplier(unit);
+            if (multiplier !== null) {
+                return {
+                    timestampMs: now - value * multiplier,
+                    original: spec,
+                    isRelative: true,
+                };
+            }
+        }
+        // Check for relative time expressions (e.g., "1 hour ago")
+        for (const { pattern, multiplier } of RELATIVE_TIME_PATTERNS) {
+            const match = trimmed.match(pattern);
+            if (match && match[1]) {
+                const value = parseInt(match[1], 10);
+                return {
+                    timestampMs: now - value * multiplier,
+                    original: spec,
+                    isRelative: true,
+                };
+            }
+        }
+        // Check for SQL INTERVAL syntax (standalone, treated as relative to now)
+        for (const { pattern, multiplier } of SQL_INTERVAL_PATTERNS) {
+            const match = trimmed.match(pattern);
+            if (match && match[1]) {
+                const value = parseInt(match[1], 10);
+                return {
+                    timestampMs: now - value * multiplier,
+                    original: spec,
+                    isRelative: true,
+                };
+            }
+        }
+        // Try ISO date parsing
+        const parsed = Date.parse(trimmed);
+        if (!isNaN(parsed)) {
+            return {
+                timestampMs: parsed,
+                original: spec,
+                isRelative: false,
+            };
+        }
+        // Try numeric string (epoch ms)
+        const numeric = parseInt(trimmed, 10);
+        if (!isNaN(numeric) && String(numeric) === trimmed) {
+            return {
+                timestampMs: numeric,
+                original: spec,
+                isRelative: false,
+            };
+        }
+    }
+    throw new InvalidTimestampError(spec);
+}
+/**
+ * Get the millisecond multiplier for an interval unit
+ */
+function getIntervalMultiplier(unit) {
+    const unitLower = unit.toLowerCase();
+    const unitMap = {
+        ms: 1,
+        millisecond: 1,
+        milliseconds: 1,
+        s: 1000,
+        sec: 1000,
+        second: 1000,
+        seconds: 1000,
+        m: 60 * 1000,
+        min: 60 * 1000,
+        minute: 60 * 1000,
+        minutes: 60 * 1000,
+        h: 60 * 60 * 1000,
+        hr: 60 * 60 * 1000,
+        hour: 60 * 60 * 1000,
+        hours: 60 * 60 * 1000,
+        d: 24 * 60 * 60 * 1000,
+        day: 24 * 60 * 60 * 1000,
+        days: 24 * 60 * 60 * 1000,
+        w: 7 * 24 * 60 * 60 * 1000,
+        wk: 7 * 24 * 60 * 60 * 1000,
+        week: 7 * 24 * 60 * 60 * 1000,
+        weeks: 7 * 24 * 60 * 60 * 1000,
+        mo: 30 * 24 * 60 * 60 * 1000,
+        month: 30 * 24 * 60 * 60 * 1000,
+        months: 30 * 24 * 60 * 60 * 1000,
+        y: 365 * 24 * 60 * 60 * 1000,
+        yr: 365 * 24 * 60 * 60 * 1000,
+        year: 365 * 24 * 60 * 60 * 1000,
+        years: 365 * 24 * 60 * 60 * 1000,
+    };
+    return unitMap[unitLower] ?? null;
+}
+/**
+ * Format a timestamp for display
+ */
+export function formatTimestamp(timestampMs) {
+    return new Date(timestampMs).toISOString();
+}
+// ============================================================================
+// SQL AS OF Parser
+// ============================================================================
+/**
+ * SQL AS OF clause pattern
+ * Matches: AS OF TIMESTAMP '2024-01-01' or AS OF TIMESTAMP '2024-01-01T00:00:00Z'
+ */
+const AS_OF_TIMESTAMP_PATTERN = /\bAS\s+OF\s+TIMESTAMP\s+['"]([^'"]+)['"]/i;
+/**
+ * SQL AS OF SYSTEM TIME pattern (alternative syntax)
+ */
+const AS_OF_SYSTEM_TIME_PATTERN = /\bAS\s+OF\s+SYSTEM\s+TIME\s+['"]([^'"]+)['"]/i;
+/**
+ * SQL FOR SYSTEM_TIME AS OF pattern
+ */
+const FOR_SYSTEM_TIME_AS_OF_PATTERN = /\bFOR\s+SYSTEM_TIME\s+AS\s+OF\s+['"]([^'"]+)['"]/i;
+/**
+ * SQL VERSIONS BETWEEN pattern
+ * Matches: VERSIONS BETWEEN TIMESTAMP '2024-01-01' AND '2024-01-15'
+ * Also matches: VERSIONS BETWEEN TIMESTAMP '2024-01-01' AND TIMESTAMP '2024-01-15'
+ * Also matches: VERSIONS BETWEEN '2024-01-01' AND '2024-01-15'
+ */
+const VERSIONS_BETWEEN_PATTERN = /\bVERSIONS\s+BETWEEN\s+(?:TIMESTAMP\s+)?['"]([^'"]+)['"]\s+AND\s+(?:TIMESTAMP\s+)?['"]([^'"]+)['"]/i;
+/**
+ * SQL VERSIONS BETWEEN with expression pattern
+ * Matches: VERSIONS BETWEEN TIMESTAMP '2024-01-01' AND CURRENT_TIMESTAMP
+ * Also matches: VERSIONS BETWEEN TIMESTAMP '2024-01-01' AND NOW()
+ */
+const VERSIONS_BETWEEN_EXPR_PATTERN = /\bVERSIONS\s+BETWEEN\s+(?:TIMESTAMP\s+)?['"]([^'"]+)['"]\s+AND\s+(?:TIMESTAMP\s+)?(now\(\)|current_timestamp)/i;
+/**
+ * SQL AS OF with expression pattern (NOW() - INTERVAL '1 hour')
+ * Matches: AS OF TIMESTAMP NOW() - INTERVAL '1 hour'
+ * Also matches: AS OF TIMESTAMP CURRENT_TIMESTAMP - INTERVAL '30 minutes'
+ */
+const AS_OF_TIMESTAMP_EXPR_PATTERN = /\bAS\s+OF\s+TIMESTAMP\s+((?:now\(\)|current_timestamp)\s*-\s*interval\s*'[^']+')/i;
+/**
+ * SQL AS OF with NOW() or CURRENT_TIMESTAMP (no subtraction)
+ * Matches: AS OF TIMESTAMP NOW() or AS OF TIMESTAMP CURRENT_TIMESTAMP
+ */
+const AS_OF_TIMESTAMP_NOW_PATTERN = /\bAS\s+OF\s+TIMESTAMP\s+(now\(\)|current_timestamp)/i;
+/**
+ * Parse SQL for AS OF TIMESTAMP clause
+ *
+ * Supports the following syntax variants:
+ * - AS OF TIMESTAMP '2024-01-01T00:00:00Z' (ISO timestamp)
+ * - AS OF TIMESTAMP '1 hour ago' (relative timestamp)
+ * - AS OF TIMESTAMP NOW() - INTERVAL '1 hour' (SQL expression)
+ * - AS OF TIMESTAMP CURRENT_TIMESTAMP - INTERVAL '30 minutes'
+ * - AS OF TIMESTAMP NOW()
+ * - AS OF SYSTEM TIME '2024-01-01' (alternative syntax)
+ * - FOR SYSTEM_TIME AS OF '2024-01-01' (SQL:2011 syntax)
+ * - VERSIONS BETWEEN TIMESTAMP '2024-01-01' AND '2024-01-15' (range query)
+ * - VERSIONS BETWEEN '2024-01-01' AND CURRENT_TIMESTAMP (range with expression)
+ */
+export function parseTimeTravelSQL(sql) {
+    // First check for VERSIONS BETWEEN patterns (highest precedence)
+    let versionsBetweenMatch = sql.match(VERSIONS_BETWEEN_EXPR_PATTERN);
+    if (versionsBetweenMatch && versionsBetweenMatch[1] && versionsBetweenMatch[2]) {
+        const startTimestamp = parseTimestamp(versionsBetweenMatch[1]);
+        const endTimestamp = parseTimestamp(versionsBetweenMatch[2]);
+        const cleanSql = sql.replace(VERSIONS_BETWEEN_EXPR_PATTERN, '').replace(/\s+/g, ' ').trim();
+        const tableMatch = cleanSql.match(/\bFROM\s+["']?(\w+)["']?/i);
+        const tableName = tableMatch?.[1];
+        const result = {
+            originalSql: sql,
+            cleanSql,
+            hasTimeTravelClause: true,
+            mode: 'versions-between',
+            startTimestamp,
+            endTimestamp,
+        };
+        if (tableName) {
+            result.tableName = tableName;
+        }
+        return result;
+    }
+    versionsBetweenMatch = sql.match(VERSIONS_BETWEEN_PATTERN);
+    if (versionsBetweenMatch && versionsBetweenMatch[1] && versionsBetweenMatch[2]) {
+        const startTimestamp = parseTimestamp(versionsBetweenMatch[1]);
+        const endTimestamp = parseTimestamp(versionsBetweenMatch[2]);
+        const cleanSql = sql.replace(VERSIONS_BETWEEN_PATTERN, '').replace(/\s+/g, ' ').trim();
+        const tableMatch = cleanSql.match(/\bFROM\s+["']?(\w+)["']?/i);
+        const tableName = tableMatch?.[1];
+        const result = {
+            originalSql: sql,
+            cleanSql,
+            hasTimeTravelClause: true,
+            mode: 'versions-between',
+            startTimestamp,
+            endTimestamp,
+        };
+        if (tableName) {
+            result.tableName = tableName;
+        }
+        return result;
+    }
+    const patterns = [
+        { pattern: AS_OF_TIMESTAMP_EXPR_PATTERN, name: 'expr' },
+        { pattern: AS_OF_TIMESTAMP_NOW_PATTERN, name: 'now' },
+        { pattern: AS_OF_TIMESTAMP_PATTERN, name: 'timestamp' },
+        { pattern: AS_OF_SYSTEM_TIME_PATTERN, name: 'system_time' },
+        { pattern: FOR_SYSTEM_TIME_AS_OF_PATTERN, name: 'for_system_time' },
+    ];
+    let match = null;
+    let matchedPattern = null;
+    for (const { pattern } of patterns) {
+        match = sql.match(pattern);
+        if (match) {
+            matchedPattern = pattern;
+            break;
+        }
+    }
+    if (!match || !match[1] || !matchedPattern) {
+        return {
+            originalSql: sql,
+            cleanSql: sql,
+            hasTimeTravelClause: false,
+        };
+    }
+    const timestampStr = match[1];
+    const timestamp = parseTimestamp(timestampStr);
+    const cleanSql = sql.replace(matchedPattern, '').replace(/\s+/g, ' ').trim();
+    // Try to extract table name from FROM clause
+    const tableMatch = cleanSql.match(/\bFROM\s+["']?(\w+)["']?/i);
+    const tableName = tableMatch?.[1];
+    const result = {
+        originalSql: sql,
+        cleanSql,
+        timestamp,
+        hasTimeTravelClause: true,
+        mode: 'point-in-time',
+    };
+    if (tableName) {
+        result.tableName = tableName;
+    }
+    return result;
+}
+/**
+ * Build SQL with AS OF clause
+ */
+export function buildTimeTravelSQL(baseSql, timestamp, tableName) {
+    const parsed = parseTimestamp(timestamp);
+    const isoTimestamp = formatTimestamp(parsed.timestampMs);
+    // If table name provided and SQL has FROM clause, insert AS OF after table name
+    if (tableName) {
+        const tablePattern = new RegExp(`(\\bFROM\\s+["']?${tableName}["']?)`, 'i');
+        if (tablePattern.test(baseSql)) {
+            return baseSql.replace(tablePattern, `$1 AS OF TIMESTAMP '${isoTimestamp}'`);
+        }
+    }
+    // Otherwise, try to insert after FROM table
+    const fromPattern = /(\bFROM\s+["']?\w+["']?)/i;
+    if (fromPattern.test(baseSql)) {
+        return baseSql.replace(fromPattern, `$1 AS OF TIMESTAMP '${isoTimestamp}'`);
+    }
+    // Fallback: append to end (may not be valid SQL but preserves intent)
+    return `${baseSql} AS OF TIMESTAMP '${isoTimestamp}'`;
+}
+/**
+ * Iceberg Time Travel Reader
+ *
+ * Reads Iceberg table data at a specific point in time using snapshots.
+ */
+export class IcebergTimeTravelReader {
+    bucket;
+    retentionWindowMs;
+    maxQueryAgeMs;
+    enableManifestCache;
+    manifestCacheTtlMs;
+    manifestCache = new Map();
+    constructor(config) {
+        this.bucket = config.bucket;
+        // Store retention window for future use in validation
+        this.retentionWindowMs = config.retentionWindowMs ?? 30 * 24 * 60 * 60 * 1000; // 30 days
+        this.maxQueryAgeMs = config.maxQueryAgeMs ?? 90 * 24 * 60 * 60 * 1000; // 90 days
+        this.enableManifestCache = config.enableManifestCache ?? true;
+        this.manifestCacheTtlMs = config.manifestCacheTtlMs ?? 5 * 60 * 1000; // 5 minutes
+    }
+    /**
+     * Get the retention window in milliseconds
+     */
+    getRetentionWindowMs() {
+        return this.retentionWindowMs;
+    }
+    /**
+     * Find the snapshot that was current at the given timestamp
+     */
+    async findSnapshotAtTimestamp(metadata, timestamp) {
+        const parsed = parseTimestamp(timestamp);
+        const targetMs = parsed.timestampMs;
+        const snapshots = metadata.snapshots ?? [];
+        if (snapshots.length === 0) {
+            throw new NoSnapshotFoundError(targetMs);
+        }
+        // Sort snapshots by timestamp descending
+        const sortedSnapshots = [...snapshots].sort((a, b) => b['timestamp-ms'] - a['timestamp-ms']);
+        // Find the oldest and newest snapshots for range checking
+        const oldestSnapshot = sortedSnapshots[sortedSnapshots.length - 1];
+        const newestSnapshot = sortedSnapshots[0];
+        // Check if timestamp is in valid range
+        const now = Date.now();
+        if (targetMs > now) {
+            throw new TimestampOutOfRangeError(targetMs, oldestSnapshot['timestamp-ms'], now);
+        }
+        if (targetMs < oldestSnapshot['timestamp-ms'] - this.maxQueryAgeMs) {
+            throw new TimestampOutOfRangeError(targetMs, oldestSnapshot['timestamp-ms'], newestSnapshot['timestamp-ms']);
+        }
+        // Find the snapshot that was current at the target timestamp
+        // This is the newest snapshot with timestamp <= target
+        let selectedSnapshot = null;
+        let timeDiff = Infinity;
+        for (const snapshot of sortedSnapshots) {
+            const snapshotTs = snapshot['timestamp-ms'];
+            if (snapshotTs <= targetMs) {
+                const diff = targetMs - snapshotTs;
+                if (diff < timeDiff) {
+                    selectedSnapshot = snapshot;
+                    timeDiff = diff;
+                }
+                break; // Since sorted descending, first match is best
+            }
+        }
+        // If no snapshot found at or before target, use oldest
+        if (!selectedSnapshot) {
+            selectedSnapshot = oldestSnapshot;
+            timeDiff = Math.abs(targetMs - oldestSnapshot['timestamp-ms']);
+        }
+        return {
+            snapshot: selectedSnapshot,
+            timestampMs: targetMs,
+            exactMatch: timeDiff === 0,
+            timeDifferenceMs: timeDiff,
+        };
+    }
+    /**
+     * Get the snapshot range for a time range query
+     */
+    async findSnapshotsInRange(metadata, fromTimestamp, toTimestamp) {
+        const from = parseTimestamp(fromTimestamp);
+        const to = parseTimestamp(toTimestamp);
+        const snapshots = metadata.snapshots ?? [];
+        return snapshots.filter((snapshot) => {
+            const ts = snapshot['timestamp-ms'];
+            return ts >= from.timestampMs && ts <= to.timestampMs;
+        });
+    }
+    /**
+     * Get data files for a snapshot
+     * @param _metadata - Table metadata (reserved for future schema validation)
+     * @param snapshot - The snapshot to read files from
+     */
+    async getDataFilesForSnapshot(_metadata, snapshot) {
+        const manifestListPath = snapshot['manifest-list'];
+        // Load manifest list
+        const manifestList = await this.loadManifestList(manifestListPath);
+        // Load all manifests and collect data files
+        const dataFiles = [];
+        for (const manifest of manifestList) {
+            const entries = await this.loadManifest(manifest['manifest-path']);
+            for (const entry of entries) {
+                // Only include EXISTING (0) and ADDED (1) entries
+                // DELETED (2) entries are excluded
+                if (entry.status === 0 || entry.status === 1) {
+                    dataFiles.push(entry['data-file']);
+                }
+            }
+        }
+        // Calculate total records
+        const totalRecords = dataFiles.reduce((sum, file) => sum + file['record-count'], 0);
+        return {
+            dataFiles,
+            metadata: {
+                snapshotId: snapshot['snapshot-id'],
+                snapshotTimestampMs: snapshot['timestamp-ms'],
+                requestedTimestampMs: snapshot['timestamp-ms'],
+                mode: 'point-in-time',
+                dataFilesScanned: dataFiles.length,
+                totalRecords,
+            },
+        };
+    }
+    /**
+     * Resolve data files for a time travel query
+     */
+    async resolveDataFiles(metadata, options) {
+        // Determine query mode
+        let mode = options.mode ?? 'latest';
+        if (options.asOf && !options.mode) {
+            mode = 'point-in-time';
+        }
+        else if (options.fromTimestamp && options.toTimestamp && !options.mode) {
+            mode = 'range';
+        }
+        switch (mode) {
+            case 'point-in-time': {
+                if (!options.asOf) {
+                    throw new Error('asOf timestamp is required for point-in-time queries');
+                }
+                const resolved = await this.findSnapshotAtTimestamp(metadata, options.asOf);
+                const result = await this.getDataFilesForSnapshot(metadata, resolved.snapshot);
+                result.metadata.requestedTimestampMs = resolved.timestampMs;
+                result.metadata.mode = mode;
+                return result;
+            }
+            case 'versions-between': {
+                if (!options.fromTimestamp || !options.toTimestamp) {
+                    throw new Error('fromTimestamp and toTimestamp are required for versions-between queries');
+                }
+                const fromParsed = parseTimestamp(options.fromTimestamp);
+                const toParsed = parseTimestamp(options.toTimestamp);
+                // Find all snapshots in the range
+                const snapshots = await this.findSnapshotsInRange(metadata, fromParsed.timestampMs, toParsed.timestampMs);
+                if (snapshots.length === 0) {
+                    throw new NoSnapshotFoundError(fromParsed.timestampMs);
+                }
+                // Collect all data files from all snapshots in the range
+                const allDataFiles = [];
+                let totalRecords = 0;
+                for (const snapshot of snapshots) {
+                    const { dataFiles } = await this.getDataFilesForSnapshot(metadata, snapshot);
+                    allDataFiles.push(...dataFiles);
+                    totalRecords += dataFiles.reduce((sum, file) => sum + file['record-count'], 0);
+                }
+                // Deduplicate data files by file path
+                const uniqueDataFiles = Array.from(new Map(allDataFiles.map(file => [file['file-path'], file])).values());
+                return {
+                    dataFiles: uniqueDataFiles,
+                    metadata: {
+                        snapshotId: snapshots[snapshots.length - 1]['snapshot-id'],
+                        snapshotTimestampMs: snapshots[snapshots.length - 1]['timestamp-ms'],
+                        requestedTimestampMs: fromParsed.timestampMs,
+                        mode: 'versions-between',
+                        dataFilesScanned: uniqueDataFiles.length,
+                        totalRecords,
+                        snapshotCount: snapshots.length,
+                        startTimestampMs: fromParsed.timestampMs,
+                        endTimestampMs: toParsed.timestampMs,
+                    },
+                };
+            }
+            case 'range': {
+                if (!options.fromTimestamp || !options.toTimestamp) {
+                    throw new Error('fromTimestamp and toTimestamp are required for range queries');
+                }
+                // For range queries, get the end snapshot's data files
+                // The data represents the state at the end of the range
+                const toResolved = await this.findSnapshotAtTimestamp(metadata, options.toTimestamp);
+                const result = await this.getDataFilesForSnapshot(metadata, toResolved.snapshot);
+                result.metadata.mode = mode;
+                return result;
+            }
+            case 'latest':
+            default: {
+                // Use current snapshot
+                const currentSnapshotId = metadata['current-snapshot-id'];
+                if (!currentSnapshotId) {
+                    throw new NoSnapshotFoundError(Date.now());
+                }
+                const snapshot = metadata.snapshots?.find((s) => s['snapshot-id'] === currentSnapshotId);
+                if (!snapshot) {
+                    throw new NoSnapshotFoundError(Date.now());
+                }
+                const result = await this.getDataFilesForSnapshot(metadata, snapshot);
+                result.metadata.mode = mode;
+                return result;
+            }
+        }
+    }
+    /**
+     * Get available time range for queries
+     */
+    getAvailableTimeRange(metadata) {
+        const snapshots = metadata.snapshots ?? [];
+        if (snapshots.length === 0) {
+            return { oldest: null, newest: null };
+        }
+        const timestamps = snapshots.map((s) => s['timestamp-ms']);
+        return {
+            oldest: Math.min(...timestamps),
+            newest: Math.max(...timestamps),
+        };
+    }
+    /**
+     * List all available snapshots with their timestamps
+     */
+    listSnapshots(metadata) {
+        const snapshots = metadata.snapshots ?? [];
+        return snapshots
+            .map((s) => ({
+            snapshotId: s['snapshot-id'],
+            timestampMs: s['timestamp-ms'],
+            timestamp: formatTimestamp(s['timestamp-ms']),
+        }))
+            .sort((a, b) => b.timestampMs - a.timestampMs);
+    }
+    /**
+     * Load manifest list from R2
+     */
+    async loadManifestList(path) {
+        // Check cache
+        if (this.enableManifestCache) {
+            const cached = this.manifestCache.get(path);
+            if (cached && cached.expiresAt > Date.now()) {
+                return cached.data;
+            }
+        }
+        const obj = await this.bucket.get(path);
+        if (!obj) {
+            throw new Error(`Manifest list not found: ${path}`);
+        }
+        const data = JSON.parse(await obj.text());
+        const manifests = data.manifests ?? [];
+        // Cache the result
+        if (this.enableManifestCache) {
+            this.manifestCache.set(path, {
+                data: manifests,
+                expiresAt: Date.now() + this.manifestCacheTtlMs,
+            });
+        }
+        return manifests;
+    }
+    /**
+     * Load manifest entries from R2
+     */
+    async loadManifest(path) {
+        const cacheKey = `manifest:${path}`;
+        // Check cache (reuse manifest cache for entries too)
+        if (this.enableManifestCache) {
+            const cached = this.manifestCache.get(cacheKey);
+            if (cached && cached.expiresAt > Date.now()) {
+                return cached.data;
+            }
+        }
+        const obj = await this.bucket.get(path);
+        if (!obj) {
+            throw new Error(`Manifest not found: ${path}`);
+        }
+        const data = JSON.parse(await obj.text());
+        const entries = data.entries ?? [];
+        // Cache the result
+        if (this.enableManifestCache) {
+            this.manifestCache.set(cacheKey, {
+                data: entries,
+                expiresAt: Date.now() + this.manifestCacheTtlMs,
+            });
+        }
+        return entries;
+    }
+    /**
+     * Clear the manifest cache
+     */
+    clearCache() {
+        this.manifestCache.clear();
+    }
+    /**
+     * Get cache statistics
+     */
+    getCacheStats() {
+        return {
+            size: this.manifestCache.size,
+            ttlMs: this.manifestCacheTtlMs,
+        };
+    }
+}
+/**
+ * Create a time travel reader
+ */
+export function createTimeTravelReader(config) {
+    return new IcebergTimeTravelReader(config);
+}
+//# sourceMappingURL=time-travel.js.map