@dotdo/postgres 0.1.0

package/src/iceberg/time-travel.test.ts

@@ -0,0 +1,1218 @@
+/**
+ * Time Travel Query Tests
+ * Task: postgres-3kc - Time travel query API (query as-of timestamp)
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import {
+  parseTimestamp,
+  parseTimeTravelSQL,
+  buildTimeTravelSQL,
+  formatTimestamp,
+  IcebergTimeTravelReader,
+  createTimeTravelReader,
+  TimestampOutOfRangeError,
+  NoSnapshotFoundError,
+  InvalidTimestampError,
+  type ParsedTimestamp,
+  type TimeTravelQueryOptions,
+  type RowOperation,
+  type VersionSystemColumns,
+  type RowVersion,
+  type VersionsBetweenResult,
+} from './time-travel'
+import type { IcebergTableMetadata, IcebergSnapshot } from './types'
+
+// ============================================================================
+// Timestamp Parsing Tests
+// ============================================================================
+
+describe('Timestamp Parsing', () => {
+  describe('parseTimestamp', () => {
+    it('should parse epoch milliseconds (number)', () => {
+      const result = parseTimestamp(1704067200000)
+
+      expect(result.timestampMs).toBe(1704067200000)
+      expect(result.isRelative).toBe(false)
+    })
+
+    it('should parse Date object', () => {
+      const date = new Date('2024-01-01T00:00:00Z')
+      const result = parseTimestamp(date)
+
+      expect(result.timestampMs).toBe(date.getTime())
+      expect(result.isRelative).toBe(false)
+    })
+
+    it('should parse ISO date string', () => {
+      const result = parseTimestamp('2024-01-01T00:00:00Z')
+
+      expect(result.timestampMs).toBe(1704067200000)
+      expect(result.isRelative).toBe(false)
+    })
+
+    it('should parse numeric string', () => {
+      const result = parseTimestamp('1704067200000')
+
+      expect(result.timestampMs).toBe(1704067200000)
+      expect(result.isRelative).toBe(false)
+    })
+
+    describe('relative timestamps', () => {
+      const referenceTime = 1704153600000 // 2024-01-02T00:00:00Z
+
+      it('should parse "X seconds ago"', () => {
+        const result = parseTimestamp('30 seconds ago', referenceTime)
+
+        expect(result.timestampMs).toBe(referenceTime - 30 * 1000)
+        expect(result.isRelative).toBe(true)
+      })
+
+      it('should parse "X minutes ago"', () => {
+        const result = parseTimestamp('5 minutes ago', referenceTime)
+
+        expect(result.timestampMs).toBe(referenceTime - 5 * 60 * 1000)
+        expect(result.isRelative).toBe(true)
+      })
+
+      it('should parse "X hours ago"', () => {
+        const result = parseTimestamp('2 hours ago', referenceTime)
+
+        expect(result.timestampMs).toBe(referenceTime - 2 * 60 * 60 * 1000)
+        expect(result.isRelative).toBe(true)
+      })
+
+      it('should parse "X days ago"', () => {
+        const result = parseTimestamp('1 day ago', referenceTime)
+
+        expect(result.timestampMs).toBe(referenceTime - 24 * 60 * 60 * 1000)
+        expect(result.isRelative).toBe(true)
+      })
+
+      it('should parse "X weeks ago"', () => {
+        const result = parseTimestamp('2 weeks ago', referenceTime)
+
+        expect(result.timestampMs).toBe(referenceTime - 2 * 7 * 24 * 60 * 60 * 1000)
+        expect(result.isRelative).toBe(true)
+      })
+
+      it('should parse short forms (h, m, s, d, w)', () => {
+        expect(parseTimestamp('1h ago', referenceTime).timestampMs).toBe(
+          referenceTime - 60 * 60 * 1000
+        )
+        expect(parseTimestamp('30m ago', referenceTime).timestampMs).toBe(
+          referenceTime - 30 * 60 * 1000
+        )
+        expect(parseTimestamp('10s ago', referenceTime).timestampMs).toBe(
+          referenceTime - 10 * 1000
+        )
+        expect(parseTimestamp('3d ago', referenceTime).timestampMs).toBe(
+          referenceTime - 3 * 24 * 60 * 60 * 1000
+        )
+        expect(parseTimestamp('1w ago', referenceTime).timestampMs).toBe(
+          referenceTime - 7 * 24 * 60 * 60 * 1000
+        )
+      })
+
+      it('should be case insensitive', () => {
+        const result1 = parseTimestamp('1 HOUR AGO', referenceTime)
+        const result2 = parseTimestamp('1 Hour Ago', referenceTime)
+
+        expect(result1.timestampMs).toBe(result2.timestampMs)
+      })
+
+      it('should parse "X years ago"', () => {
+        const result = parseTimestamp('1 year ago', referenceTime)
+
+        expect(result.timestampMs).toBe(referenceTime - 365 * 24 * 60 * 60 * 1000)
+        expect(result.isRelative).toBe(true)
+      })
+
+      it('should parse short form year (1y ago)', () => {
+        const result = parseTimestamp('1y ago', referenceTime)
+
+        expect(result.timestampMs).toBe(referenceTime - 365 * 24 * 60 * 60 * 1000)
+        expect(result.isRelative).toBe(true)
+      })
+    })
+
+    describe('NOW() and CURRENT_TIMESTAMP', () => {
+      const referenceTime = 1704153600000 // 2024-01-02T00:00:00Z
+
+      it('should parse NOW()', () => {
+        const result = parseTimestamp('NOW()', referenceTime)
+
+        expect(result.timestampMs).toBe(referenceTime)
+        expect(result.isRelative).toBe(true)
+      })
+
+      it('should parse now() (lowercase)', () => {
+        const result = parseTimestamp('now()', referenceTime)
+
+        expect(result.timestampMs).toBe(referenceTime)
+        expect(result.isRelative).toBe(true)
+      })
+
+      it('should parse CURRENT_TIMESTAMP', () => {
+        const result = parseTimestamp('CURRENT_TIMESTAMP', referenceTime)
+
+        expect(result.timestampMs).toBe(referenceTime)
+        expect(result.isRelative).toBe(true)
+      })
+
+      it('should parse current_timestamp (lowercase)', () => {
+        const result = parseTimestamp('current_timestamp', referenceTime)
+
+        expect(result.timestampMs).toBe(referenceTime)
+        expect(result.isRelative).toBe(true)
+      })
+    })
+
+    describe('SQL INTERVAL expressions', () => {
+      const referenceTime = 1704153600000 // 2024-01-02T00:00:00Z
+
+      it("should parse NOW() - INTERVAL '1 hour'", () => {
+        const result = parseTimestamp("NOW() - INTERVAL '1 hour'", referenceTime)
+
+        expect(result.timestampMs).toBe(referenceTime - 60 * 60 * 1000)
+        expect(result.isRelative).toBe(true)
+      })
+
+      it("should parse CURRENT_TIMESTAMP - INTERVAL '30 minutes'", () => {
+        const result = parseTimestamp("CURRENT_TIMESTAMP - INTERVAL '30 minutes'", referenceTime)
+
+        expect(result.timestampMs).toBe(referenceTime - 30 * 60 * 1000)
+        expect(result.isRelative).toBe(true)
+      })
+
+      it("should parse now() - interval '2 days'", () => {
+        const result = parseTimestamp("now() - interval '2 days'", referenceTime)
+
+        expect(result.timestampMs).toBe(referenceTime - 2 * 24 * 60 * 60 * 1000)
+        expect(result.isRelative).toBe(true)
+      })
+
+      it("should parse INTERVAL '1 hour' (standalone)", () => {
+        const result = parseTimestamp("INTERVAL '1 hour'", referenceTime)
+
+        expect(result.timestampMs).toBe(referenceTime - 60 * 60 * 1000)
+        expect(result.isRelative).toBe(true)
+      })
+
+      it("should parse interval '1 week' (standalone)", () => {
+        const result = parseTimestamp("interval '1 week'", referenceTime)
+
+        expect(result.timestampMs).toBe(referenceTime - 7 * 24 * 60 * 60 * 1000)
+        expect(result.isRelative).toBe(true)
+      })
+
+      it("should parse interval with various units", () => {
+        expect(parseTimestamp("INTERVAL '100 ms'", referenceTime).timestampMs).toBe(
+          referenceTime - 100
+        )
+        expect(parseTimestamp("INTERVAL '45 seconds'", referenceTime).timestampMs).toBe(
+          referenceTime - 45 * 1000
+        )
+        expect(parseTimestamp("INTERVAL '15 min'", referenceTime).timestampMs).toBe(
+          referenceTime - 15 * 60 * 1000
+        )
+        expect(parseTimestamp("INTERVAL '3 months'", referenceTime).timestampMs).toBe(
+          referenceTime - 3 * 30 * 24 * 60 * 60 * 1000
+        )
+        expect(parseTimestamp("INTERVAL '1 year'", referenceTime).timestampMs).toBe(
+          referenceTime - 365 * 24 * 60 * 60 * 1000
+        )
+      })
+    })
+
+    it('should throw InvalidTimestampError for invalid input', () => {
+      expect(() => parseTimestamp('invalid')).toThrow(InvalidTimestampError)
+      expect(() => parseTimestamp('yesterday')).toThrow(InvalidTimestampError)
+      expect(() => parseTimestamp('')).toThrow(InvalidTimestampError)
+    })
+  })
+
+  describe('formatTimestamp', () => {
+    it('should format timestamp as ISO string', () => {
+      const result = formatTimestamp(1704067200000)
+
+      expect(result).toBe('2024-01-01T00:00:00.000Z')
+    })
+  })
+})
+
+// ============================================================================
+// SQL AS OF Parser Tests
+// ============================================================================
+
+describe('SQL AS OF Parser', () => {
+  describe('parseTimeTravelSQL', () => {
+    it('should parse SQL with AS OF TIMESTAMP clause', () => {
+      const sql = "SELECT * FROM users AS OF TIMESTAMP '2024-01-01T00:00:00Z' WHERE id = 1"
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.timestamp?.timestampMs).toBe(1704067200000)
+      expect(result.cleanSql).toBe('SELECT * FROM users WHERE id = 1')
+    })
+
+    it('should parse SQL with AS OF SYSTEM TIME clause', () => {
+      const sql = "SELECT * FROM users AS OF SYSTEM TIME '2024-01-01T00:00:00Z'"
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.timestamp?.timestampMs).toBe(1704067200000)
+    })
+
+    it('should parse SQL with FOR SYSTEM_TIME AS OF clause', () => {
+      const sql = "SELECT * FROM users FOR SYSTEM_TIME AS OF '2024-01-01'"
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.timestamp).toBeDefined()
+    })
+
+    it('should handle SQL without AS OF clause', () => {
+      const sql = 'SELECT * FROM users WHERE id = 1'
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(false)
+      expect(result.timestamp).toBeUndefined()
+      expect(result.cleanSql).toBe(sql)
+    })
+
+    it('should extract table name', () => {
+      const sql = "SELECT * FROM events AS OF TIMESTAMP '2024-01-01'"
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.tableName).toBe('events')
+    })
+
+    it('should handle double-quoted timestamps', () => {
+      const sql = 'SELECT * FROM users AS OF TIMESTAMP "2024-01-01T00:00:00Z"'
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.timestamp?.timestampMs).toBe(1704067200000)
+    })
+
+    it('should parse AS OF TIMESTAMP with relative timestamp', () => {
+      const sql = "SELECT * FROM users AS OF TIMESTAMP '1 hour ago'"
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.timestamp?.isRelative).toBe(true)
+      expect(result.cleanSql).toBe('SELECT * FROM users')
+    })
+
+    it("should parse AS OF TIMESTAMP NOW() - INTERVAL '1 hour'", () => {
+      const sql = "SELECT * FROM users AS OF TIMESTAMP NOW() - INTERVAL '1 hour' WHERE id = 1"
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.timestamp?.isRelative).toBe(true)
+      expect(result.cleanSql).toBe('SELECT * FROM users WHERE id = 1')
+      expect(result.tableName).toBe('users')
+    })
+
+    it("should parse AS OF TIMESTAMP CURRENT_TIMESTAMP - INTERVAL '30 minutes'", () => {
+      const sql = "SELECT * FROM orders AS OF TIMESTAMP CURRENT_TIMESTAMP - INTERVAL '30 minutes'"
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.timestamp?.isRelative).toBe(true)
+      expect(result.cleanSql).toBe('SELECT * FROM orders')
+      expect(result.tableName).toBe('orders')
+    })
+
+    it('should parse AS OF TIMESTAMP NOW()', () => {
+      const sql = 'SELECT * FROM events AS OF TIMESTAMP NOW()'
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.timestamp?.isRelative).toBe(true)
+      expect(result.cleanSql).toBe('SELECT * FROM events')
+    })
+
+    it('should parse AS OF TIMESTAMP CURRENT_TIMESTAMP', () => {
+      const sql = 'SELECT * FROM logs AS OF TIMESTAMP CURRENT_TIMESTAMP'
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.timestamp?.isRelative).toBe(true)
+      expect(result.cleanSql).toBe('SELECT * FROM logs')
+    })
+
+    it('should preserve complex WHERE clauses', () => {
+      const sql = "SELECT id, name FROM users AS OF TIMESTAMP '2024-01-01' WHERE age > 21 AND status = 'active' ORDER BY name"
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.cleanSql).toBe("SELECT id, name FROM users WHERE age > 21 AND status = 'active' ORDER BY name")
+    })
+
+    it('should handle quoted table names', () => {
+      const sql = 'SELECT * FROM "my_table" AS OF TIMESTAMP \'2024-01-01\''
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      // Note: table name extraction may not work for quoted tables
+    })
+  })
+
+  describe('buildTimeTravelSQL', () => {
+    it('should add AS OF clause to SQL', () => {
+      const sql = 'SELECT * FROM users WHERE id = 1'
+      const result = buildTimeTravelSQL(sql, '2024-01-01T00:00:00Z')
+
+      expect(result).toContain("AS OF TIMESTAMP '2024-01-01T00:00:00.000Z'")
+      expect(result).toContain('FROM users')
+    })
+
+    it('should insert after specific table name', () => {
+      const sql = 'SELECT * FROM users WHERE id = 1'
+      const result = buildTimeTravelSQL(sql, '2024-01-01T00:00:00Z', 'users')
+
+      expect(result).toBe(
+        "SELECT * FROM users AS OF TIMESTAMP '2024-01-01T00:00:00.000Z' WHERE id = 1"
+      )
+    })
+  })
+})
+
+// ============================================================================
+// Time Travel Reader Tests
+// ============================================================================
+
+describe('IcebergTimeTravelReader', () => {
+  // Mock R2 bucket
+  const mockBucket = {
+    get: vi.fn(),
+    put: vi.fn(),
+    head: vi.fn(),
+    list: vi.fn(),
+    delete: vi.fn(),
+  } as unknown as R2Bucket
+
+  let reader: IcebergTimeTravelReader
+
+  // Sample metadata with snapshots
+  const createMetadata = (
+    snapshots: Array<{ id: number; timestampMs: number }>
+  ): IcebergTableMetadata => ({
+    'format-version': 2,
+    'table-uuid': 'test-uuid',
+    location: 'iceberg/test',
+    'last-sequence-number': snapshots.length,
+    'last-updated-ms': Date.now(),
+    'last-column-id': 10,
+    'current-schema-id': 0,
+    schemas: [{ type: 'struct', 'schema-id': 0, fields: [] }],
+    'default-spec-id': 0,
+    'partition-specs': [{ 'spec-id': 0, fields: [] }],
+    'last-partition-id': 0,
+    'default-sort-order-id': 0,
+    'sort-orders': [{ 'order-id': 0, fields: [] }],
+    'current-snapshot-id': snapshots.length > 0 ? snapshots[snapshots.length - 1]!.id : undefined,
+    snapshots: snapshots.map((s, i) => ({
+      'snapshot-id': s.id,
+      'sequence-number': i + 1,
+      'timestamp-ms': s.timestampMs,
+      'manifest-list': `iceberg/test/metadata/snap-${s.id}.avro`,
+      summary: { operation: 'append' as const },
+    })),
+  })
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    reader = createTimeTravelReader({ bucket: mockBucket })
+  })
+
+  describe('findSnapshotAtTimestamp', () => {
+    it('should find exact matching snapshot', async () => {
+      const metadata = createMetadata([
+        { id: 1, timestampMs: 1704067200000 },
+        { id: 2, timestampMs: 1704153600000 },
+        { id: 3, timestampMs: 1704240000000 },
+      ])
+
+      const result = await reader.findSnapshotAtTimestamp(
+        metadata,
+        1704153600000
+      )
+
+      expect(result.snapshot['snapshot-id']).toBe(2)
+      expect(result.exactMatch).toBe(true)
+      expect(result.timeDifferenceMs).toBe(0)
+    })
+
+    it('should find nearest earlier snapshot', async () => {
+      const metadata = createMetadata([
+        { id: 1, timestampMs: 1704067200000 },
+        { id: 2, timestampMs: 1704153600000 },
+        { id: 3, timestampMs: 1704240000000 },
+      ])
+
+      // Query time between snapshot 2 and 3
+      const queryTime = 1704200000000
+      const result = await reader.findSnapshotAtTimestamp(metadata, queryTime)
+
+      expect(result.snapshot['snapshot-id']).toBe(2)
+      expect(result.exactMatch).toBe(false)
+      expect(result.timeDifferenceMs).toBe(queryTime - 1704153600000)
+    })
+
+    it('should throw NoSnapshotFoundError when no snapshots exist', async () => {
+      const metadata = createMetadata([])
+
+      await expect(
+        reader.findSnapshotAtTimestamp(metadata, Date.now())
+      ).rejects.toThrow(NoSnapshotFoundError)
+    })
+
+    it('should throw TimestampOutOfRangeError for future timestamps', async () => {
+      const metadata = createMetadata([
+        { id: 1, timestampMs: 1704067200000 },
+      ])
+
+      const futureTime = Date.now() + 1000000
+
+      await expect(
+        reader.findSnapshotAtTimestamp(metadata, futureTime)
+      ).rejects.toThrow(TimestampOutOfRangeError)
+    })
+  })
+
+  describe('findSnapshotsInRange', () => {
+    it('should find all snapshots in time range', async () => {
+      const metadata = createMetadata([
+        { id: 1, timestampMs: 1704067200000 },
+        { id: 2, timestampMs: 1704153600000 },
+        { id: 3, timestampMs: 1704240000000 },
+        { id: 4, timestampMs: 1704326400000 },
+      ])
+
+      const snapshots = await reader.findSnapshotsInRange(
+        metadata,
+        1704100000000,
+        1704250000000
+      )
+
+      expect(snapshots).toHaveLength(2)
+      expect(snapshots.map((s) => s['snapshot-id'])).toEqual([2, 3])
+    })
+  })
+
+  describe('getDataFilesForSnapshot', () => {
+    it('should load data files from manifest list', async () => {
+      const metadata = createMetadata([
+        { id: 1, timestampMs: 1704067200000 },
+      ])
+
+      const mockManifestList = {
+        text: vi.fn().mockResolvedValue(
+          JSON.stringify({
+            manifests: [
+              {
+                'manifest-path': 'iceberg/test/metadata/manifest-1.avro',
+                'manifest-length': 1000,
+                'partition-spec-id': 0,
+                content: 0,
+                'sequence-number': 1,
+                'min-sequence-number': 1,
+                'added-snapshot-id': 1,
+                'added-files-count': 1,
+                'existing-files-count': 0,
+                'deleted-files-count': 0,
+                'added-rows-count': 100,
+                'existing-rows-count': 0,
+                'deleted-rows-count': 0,
+              },
+            ],
+          })
+        ),
+      }
+
+      const mockManifest = {
+        text: vi.fn().mockResolvedValue(
+          JSON.stringify({
+            entries: [
+              {
+                status: 1, // ADDED
+                'data-file': {
+                  content: 'data',
+                  'file-path': 'iceberg/test/data/file1.parquet',
+                  'file-format': 'parquet',
+                  partition: {},
+                  'record-count': 100,
+                  'file-size-in-bytes': 5000,
+                },
+              },
+            ],
+          })
+        ),
+      }
+
+      ;(mockBucket.get as ReturnType<typeof vi.fn>)
+        .mockResolvedValueOnce(mockManifestList)
+        .mockResolvedValueOnce(mockManifest)
+
+      const snapshot = metadata.snapshots![0]!
+      const result = await reader.getDataFilesForSnapshot(metadata, snapshot)
+
+      expect(result.dataFiles).toHaveLength(1)
+      expect(result.dataFiles[0]!['file-path']).toBe('iceberg/test/data/file1.parquet')
+      expect(result.metadata.totalRecords).toBe(100)
+    })
+  })
+
+  describe('resolveDataFiles', () => {
+    it('should resolve data files for point-in-time query', async () => {
+      const metadata = createMetadata([
+        { id: 1, timestampMs: 1704067200000 },
+      ])
+
+      const mockManifestList = {
+        text: vi.fn().mockResolvedValue(JSON.stringify({ manifests: [] })),
+      }
+
+      ;(mockBucket.get as ReturnType<typeof vi.fn>).mockResolvedValue(
+        mockManifestList
+      )
+
+      const options: TimeTravelQueryOptions = {
+        asOf: 1704067200000,
+      }
+
+      const result = await reader.resolveDataFiles(metadata, options)
+
+      expect(result.metadata.mode).toBe('point-in-time')
+      expect(result.metadata.snapshotId).toBe(1)
+    })
+
+    it('should use latest mode when no timestamp provided', async () => {
+      const metadata = createMetadata([
+        { id: 1, timestampMs: 1704067200000 },
+      ])
+
+      const mockManifestList = {
+        text: vi.fn().mockResolvedValue(JSON.stringify({ manifests: [] })),
+      }
+
+      ;(mockBucket.get as ReturnType<typeof vi.fn>).mockResolvedValue(
+        mockManifestList
+      )
+
+      const result = await reader.resolveDataFiles(metadata, {})
+
+      expect(result.metadata.mode).toBe('latest')
+    })
+  })
+
+  describe('getAvailableTimeRange', () => {
+    it('should return oldest and newest timestamps', () => {
+      const metadata = createMetadata([
+        { id: 1, timestampMs: 1704067200000 },
+        { id: 2, timestampMs: 1704153600000 },
+        { id: 3, timestampMs: 1704240000000 },
+      ])
+
+      const range = reader.getAvailableTimeRange(metadata)
+
+      expect(range.oldest).toBe(1704067200000)
+      expect(range.newest).toBe(1704240000000)
+    })
+
+    it('should return null for empty snapshots', () => {
+      const metadata = createMetadata([])
+
+      const range = reader.getAvailableTimeRange(metadata)
+
+      expect(range.oldest).toBeNull()
+      expect(range.newest).toBeNull()
+    })
+  })
+
+  describe('listSnapshots', () => {
+    it('should list snapshots sorted by timestamp descending', () => {
+      const metadata = createMetadata([
+        { id: 1, timestampMs: 1704067200000 },
+        { id: 2, timestampMs: 1704153600000 },
+        { id: 3, timestampMs: 1704240000000 },
+      ])
+
+      const snapshots = reader.listSnapshots(metadata)
+
+      expect(snapshots).toHaveLength(3)
+      expect(snapshots[0]!.snapshotId).toBe(3)
+      expect(snapshots[2]!.snapshotId).toBe(1)
+    })
+  })
+
+  describe('caching', () => {
+    it('should cache manifest list data', async () => {
+      const metadata = createMetadata([
+        { id: 1, timestampMs: 1704067200000 },
+      ])
+
+      const mockManifestList = {
+        text: vi.fn().mockResolvedValue(JSON.stringify({ manifests: [] })),
+      }
+
+      ;(mockBucket.get as ReturnType<typeof vi.fn>).mockResolvedValue(
+        mockManifestList
+      )
+
+      const snapshot = metadata.snapshots![0]!
+
+      // First call
+      await reader.getDataFilesForSnapshot(metadata, snapshot)
+      // Second call - should use cache
+      await reader.getDataFilesForSnapshot(metadata, snapshot)
+
+      // Should only call bucket.get once for manifest list
+      expect(mockBucket.get).toHaveBeenCalledTimes(1)
+
+      const stats = reader.getCacheStats()
+      expect(stats.size).toBe(1)
+    })
+
+    it('should clear cache', async () => {
+      const metadata = createMetadata([
+        { id: 1, timestampMs: 1704067200000 },
+      ])
+
+      const mockManifestList = {
+        text: vi.fn().mockResolvedValue(JSON.stringify({ manifests: [] })),
+      }
+
+      ;(mockBucket.get as ReturnType<typeof vi.fn>).mockResolvedValue(
+        mockManifestList
+      )
+
+      const snapshot = metadata.snapshots![0]!
+      await reader.getDataFilesForSnapshot(metadata, snapshot)
+
+      reader.clearCache()
+
+      const stats = reader.getCacheStats()
+      expect(stats.size).toBe(0)
+    })
+  })
+})
+
+// ============================================================================
+// Integration-like Tests
+// ============================================================================
+
+describe('Time Travel Integration', () => {
+  it('should support complete time travel query workflow', async () => {
+    // This tests the full flow from SQL parsing to snapshot resolution
+
+    // 1. Parse SQL with AS OF clause
+    const sql = "SELECT * FROM events AS OF TIMESTAMP '2024-01-01T12:00:00Z' WHERE type = 'click'"
+    const parsed = parseTimeTravelSQL(sql)
+
+    expect(parsed.hasTimeTravelClause).toBe(true)
+    expect(parsed.cleanSql).toBe("SELECT * FROM events WHERE type = 'click'")
+    expect(parsed.tableName).toBe('events')
+
+    // 2. Parse the timestamp
+    const timestamp = parsed.timestamp!
+    expect(timestamp.timestampMs).toBe(1704110400000) // 2024-01-01T12:00:00Z
+
+    // 3. Format for display
+    const formatted = formatTimestamp(timestamp.timestampMs)
+    expect(formatted).toBe('2024-01-01T12:00:00.000Z')
+  })
+
+  it('should support relative timestamp workflow', async () => {
+    const referenceTime = 1704153600000 // 2024-01-02T00:00:00Z
+
+    // User requests "1 hour ago"
+    const timestamp = parseTimestamp('1 hour ago', referenceTime)
+
+    expect(timestamp.isRelative).toBe(true)
+    expect(timestamp.timestampMs).toBe(1704150000000) // 1 hour before reference
+
+    // Build SQL with resolved timestamp
+    const sql = 'SELECT * FROM users'
+    const timeTravelSql = buildTimeTravelSQL(sql, timestamp.timestampMs)
+
+    expect(timeTravelSql).toContain("AS OF TIMESTAMP '2024-01-01T23:00:00.000Z'")
+  })
+})
+
+// ============================================================================
+// VERSIONS BETWEEN Tests
+// ============================================================================
+
+describe('VERSIONS BETWEEN Query Support', () => {
+  describe('parseTimeTravelSQL - VERSIONS BETWEEN', () => {
+    it('should parse basic VERSIONS BETWEEN syntax', () => {
+      const sql = "SELECT * FROM users VERSIONS BETWEEN '2024-01-01' AND '2024-01-15'"
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.mode).toBe('versions-between')
+      expect(result.startTimestamp?.timestampMs).toBe(1704067200000) // 2024-01-01
+      expect(result.endTimestamp?.timestampMs).toBe(1705276800000) // 2024-01-15
+      expect(result.cleanSql).toBe('SELECT * FROM users')
+      expect(result.tableName).toBe('users')
+    })
+
+    it('should parse VERSIONS BETWEEN with TIMESTAMP keyword', () => {
+      const sql = "SELECT * FROM orders VERSIONS BETWEEN TIMESTAMP '2024-01-01' AND TIMESTAMP '2024-01-15'"
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.mode).toBe('versions-between')
+      expect(result.startTimestamp?.timestampMs).toBe(1704067200000)
+      expect(result.endTimestamp?.timestampMs).toBe(1705276800000)
+      expect(result.cleanSql).toBe('SELECT * FROM orders')
+    })
+
+    it('should parse VERSIONS BETWEEN with CURRENT_TIMESTAMP', () => {
+      const sql = "SELECT * FROM orders VERSIONS BETWEEN TIMESTAMP '2024-01-01' AND CURRENT_TIMESTAMP"
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.mode).toBe('versions-between')
+      expect(result.startTimestamp?.timestampMs).toBe(1704067200000)
+      expect(result.endTimestamp?.isRelative).toBe(true)
+      expect(result.cleanSql).toBe('SELECT * FROM orders')
+    })
+
+    it('should parse VERSIONS BETWEEN with NOW()', () => {
+      const sql = "SELECT * FROM events VERSIONS BETWEEN '2024-01-01' AND NOW()"
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.mode).toBe('versions-between')
+      expect(result.startTimestamp?.timestampMs).toBe(1704067200000)
+      expect(result.endTimestamp?.isRelative).toBe(true)
+      expect(result.tableName).toBe('events')
+    })
+
+    it('should preserve WHERE clause in VERSIONS BETWEEN', () => {
+      const sql = "SELECT * FROM users VERSIONS BETWEEN '2024-01-01' AND '2024-01-15' WHERE customer_id = 123"
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.mode).toBe('versions-between')
+      expect(result.cleanSql).toBe('SELECT * FROM users WHERE customer_id = 123')
+    })
+
+    it('should handle full ISO timestamps in VERSIONS BETWEEN', () => {
+      const sql = "SELECT * FROM events VERSIONS BETWEEN TIMESTAMP '2024-01-01T00:00:00Z' AND TIMESTAMP '2024-01-15T23:59:59Z'"
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.mode).toBe('versions-between')
+      expect(result.startTimestamp?.timestampMs).toBe(1704067200000)
+      expect(result.endTimestamp?.timestampMs).toBe(1705363199000)
+    })
+
+    it('should handle complex SELECT with VERSIONS BETWEEN', () => {
+      const sql = "SELECT user_id, name, _operation, _valid_from, _valid_to FROM users VERSIONS BETWEEN '2024-01-01' AND '2024-01-15' WHERE active = true ORDER BY _valid_from"
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.mode).toBe('versions-between')
+      expect(result.cleanSql).toContain('SELECT user_id, name, _operation, _valid_from, _valid_to FROM users')
+      expect(result.cleanSql).toContain('WHERE active = true ORDER BY _valid_from')
+    })
+
+    it('should not match partial VERSIONS BETWEEN syntax', () => {
+      const sql = 'SELECT * FROM users WHERE version BETWEEN 1 AND 10'
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(false)
+      expect(result.mode).toBeUndefined()
+    })
+
+    it('should prioritize VERSIONS BETWEEN over AS OF', () => {
+      const sql = "SELECT * FROM users VERSIONS BETWEEN '2024-01-01' AND '2024-01-15' AS OF TIMESTAMP '2024-01-10'"
+      const result = parseTimeTravelSQL(sql)
+
+      expect(result.hasTimeTravelClause).toBe(true)
+      expect(result.mode).toBe('versions-between')
+      expect(result.startTimestamp).toBeDefined()
+      expect(result.endTimestamp).toBeDefined()
+    })
+  })
+
+  describe('IcebergTimeTravelReader - VERSIONS BETWEEN', () => {
+    const mockBucket = {
+      get: vi.fn(),
+      put: vi.fn(),
+      head: vi.fn(),
+      list: vi.fn(),
+      delete: vi.fn(),
+    } as unknown as R2Bucket
+
+    let reader: IcebergTimeTravelReader
+
+    const createMetadata = (
+      snapshots: Array<{ id: number; timestampMs: number }>
+    ): IcebergTableMetadata => ({
+      'format-version': 2,
+      'table-uuid': 'test-uuid',
+      location: 'iceberg/test',
+      'last-sequence-number': snapshots.length,
+      'last-updated-ms': Date.now(),
+      'last-column-id': 10,
+      'current-schema-id': 0,
+      schemas: [{ type: 'struct', 'schema-id': 0, fields: [] }],
+      'default-spec-id': 0,
+      'partition-specs': [{ 'spec-id': 0, fields: [] }],
+      'last-partition-id': 0,
+      'default-sort-order-id': 0,
+      'sort-orders': [{ 'order-id': 0, fields: [] }],
+      'current-snapshot-id': snapshots.length > 0 ? snapshots[snapshots.length - 1]!.id : undefined,
+      snapshots: snapshots.map((s, i) => ({
+        'snapshot-id': s.id,
+        'sequence-number': i + 1,
+        'timestamp-ms': s.timestampMs,
+        'manifest-list': `iceberg/test/metadata/snap-${s.id}.avro`,
+        summary: { operation: 'append' as const },
+      })),
+    })
+
+    beforeEach(() => {
+      vi.clearAllMocks()
+      reader = createTimeTravelReader({ bucket: mockBucket })
+    })
+
+    it('should resolve data files for VERSIONS BETWEEN query', async () => {
+      const metadata = createMetadata([
+        { id: 1, timestampMs: 1704067200000 }, // 2024-01-01
+        { id: 2, timestampMs: 1704326400000 }, // 2024-01-04
+        { id: 3, timestampMs: 1704585600000 }, // 2024-01-07
+        { id: 4, timestampMs: 1704844800000 }, // 2024-01-10
+      ])
+
+      const mockManifestListJson = JSON.stringify({
+        manifests: [
+          {
+            'manifest-path': 'iceberg/test/metadata/manifest-1.avro',
+            'manifest-length': 1000,
+            'partition-spec-id': 0,
+            content: 0,
+            'sequence-number': 1,
+            'min-sequence-number': 1,
+            'added-snapshot-id': 1,
+            'added-files-count': 1,
+            'existing-files-count': 0,
+            'deleted-files-count': 0,
+            'added-rows-count': 50,
+            'existing-rows-count': 0,
+            'deleted-rows-count': 0,
+          },
+        ],
+      })
+
+      const mockManifestJson = JSON.stringify({
+        entries: [
+          {
+            status: 1, // ADDED
+            'data-file': {
+              content: 'data',
+              'file-path': 'iceberg/test/data/file1.parquet',
+              'file-format': 'parquet',
+              partition: {},
+              'record-count': 50,
+              'file-size-in-bytes': 5000,
+            },
+          },
+        ],
+      })
+
+      // Mock calls for 3 snapshots (2, 3, 4) - manifest list + manifest for each
+      ;(mockBucket.get as ReturnType<typeof vi.fn>)
+        .mockResolvedValueOnce({ text: vi.fn().mockResolvedValue(mockManifestListJson) })
+        .mockResolvedValueOnce({ text: vi.fn().mockResolvedValue(mockManifestJson) })
+        .mockResolvedValueOnce({ text: vi.fn().mockResolvedValue(mockManifestListJson) })
+        .mockResolvedValueOnce({ text: vi.fn().mockResolvedValue(mockManifestJson) })
+        .mockResolvedValueOnce({ text: vi.fn().mockResolvedValue(mockManifestListJson) })
+        .mockResolvedValueOnce({ text: vi.fn().mockResolvedValue(mockManifestJson) })
+
+      const options: TimeTravelQueryOptions = {
+        fromTimestamp: 1704326400000, // 2024-01-04
+        toTimestamp: 1704844800000,   // 2024-01-10
+        mode: 'versions-between',
+      }
+
+      const result = await reader.resolveDataFiles(metadata, options)
+
+      expect(result.metadata.mode).toBe('versions-between')
+      expect(result.metadata.snapshotCount).toBe(3) // snapshots 2, 3, and 4
+      expect(result.metadata.startTimestampMs).toBe(1704326400000)
+      expect(result.metadata.endTimestampMs).toBe(1704844800000)
+      expect(result.dataFiles.length).toBeGreaterThan(0)
+    })
+
+    it('should collect all unique data files across snapshots', async () => {
+      // Create a fresh reader with caching disabled for this test
+      const freshReader = createTimeTravelReader({
+        bucket: mockBucket,
+        enableManifestCache: false,
+      })
+
+      const metadata = createMetadata([
+        { id: 5, timestampMs: 1705067200000 }, // Different IDs to avoid cache conflicts
+        { id: 6, timestampMs: 1705153600000 },
+      ])
+
+      const mockManifestListJson1 = JSON.stringify({
+        manifests: [
+          {
+            'manifest-path': 'iceberg/test/metadata/manifest-5.avro',
+            'manifest-length': 1000,
+            'partition-spec-id': 0,
+            content: 0,
+            'sequence-number': 1,
+            'min-sequence-number': 1,
+            'added-snapshot-id': 5,
+            'added-files-count': 1,
+            'existing-files-count': 0,
+            'deleted-files-count': 0,
+            'added-rows-count': 100,
+            'existing-rows-count': 0,
+            'deleted-rows-count': 0,
+          },
+        ],
+      })
+
+      const mockManifestJson1 = JSON.stringify({
+        entries: [
+          {
+            status: 1,
+            'data-file': {
+              content: 'data',
+              'file-path': 'iceberg/test/data/file-a.parquet',
+              'file-format': 'parquet',
+              partition: {},
+              'record-count': 100,
+              'file-size-in-bytes': 10000,
+            },
+          },
+        ],
+      })
+
+      const mockManifestListJson2 = JSON.stringify({
+        manifests: [
+          {
+            'manifest-path': 'iceberg/test/metadata/manifest-6.avro',
+            'manifest-length': 1000,
+            'partition-spec-id': 0,
+            content: 0,
+            'sequence-number': 2,
+            'min-sequence-number': 2,
+            'added-snapshot-id': 6,
+            'added-files-count': 1,
+            'existing-files-count': 0,
+            'deleted-files-count': 0,
+            'added-rows-count': 50,
+            'existing-rows-count': 0,
+            'deleted-rows-count': 0,
+          },
+        ],
+      })
+
+      const mockManifestJson2 = JSON.stringify({
+        entries: [
+          {
+            status: 1,
+            'data-file': {
+              content: 'data',
+              'file-path': 'iceberg/test/data/file-b.parquet',
+              'file-format': 'parquet',
+              partition: {},
+              'record-count': 50,
+              'file-size-in-bytes': 5000,
+            },
+          },
+        ],
+      })
+
+      // Mock multiple calls - manifest list for each snapshot, then manifest for each
+      ;(mockBucket.get as ReturnType<typeof vi.fn>)
+        .mockResolvedValueOnce({ text: vi.fn().mockResolvedValue(mockManifestListJson1) })
+        .mockResolvedValueOnce({ text: vi.fn().mockResolvedValue(mockManifestJson1) })
+        .mockResolvedValueOnce({ text: vi.fn().mockResolvedValue(mockManifestListJson2) })
+        .mockResolvedValueOnce({ text: vi.fn().mockResolvedValue(mockManifestJson2) })
+
+      const options: TimeTravelQueryOptions = {
+        fromTimestamp: 1705067200000,
+        toTimestamp: 1705153600000,
+        mode: 'versions-between',
+      }
+
+      const result = await freshReader.resolveDataFiles(metadata, options)
+
+      // Should have files from both snapshots
+      expect(result.dataFiles.length).toBe(2)
+      expect(result.metadata.snapshotCount).toBe(2)
+      const filePaths = result.dataFiles.map(f => f['file-path'])
+      // In VERSIONS BETWEEN, we collect data files from all snapshots
+      // The deduplication happens based on file path, so we should have 2 unique files
+      expect(filePaths.length).toBe(2)
+    })
+
+    it('should throw error for VERSIONS BETWEEN without timestamps', async () => {
+      const metadata = createMetadata([
+        { id: 1, timestampMs: 1704067200000 },
+      ])
+
+      const options: TimeTravelQueryOptions = {
+        mode: 'versions-between',
+      }
+
+      await expect(
+        reader.resolveDataFiles(metadata, options)
+      ).rejects.toThrow('fromTimestamp and toTimestamp are required for versions-between queries')
+    })
+
+    it('should throw NoSnapshotFoundError when no snapshots in range', async () => {
+      const metadata = createMetadata([
+        { id: 1, timestampMs: 1704067200000 }, // 2024-01-01
+      ])
+
+      const options: TimeTravelQueryOptions = {
+        fromTimestamp: 1705276800000, // 2024-01-15 (after all snapshots)
+        toTimestamp: 1705363200000,   // 2024-01-16
+        mode: 'versions-between',
+      }
+
+      await expect(
+        reader.resolveDataFiles(metadata, options)
+      ).rejects.toThrow(NoSnapshotFoundError)
+    })
+  })
+
+  describe('Integration - VERSIONS BETWEEN Workflow', () => {
+    it('should support complete VERSIONS BETWEEN query workflow', () => {
+      // 1. Parse SQL with VERSIONS BETWEEN clause
+      const sql = "SELECT user_id, name, _operation, _valid_from FROM users VERSIONS BETWEEN TIMESTAMP '2024-01-01' AND TIMESTAMP '2024-01-15' WHERE department = 'engineering'"
+      const parsed = parseTimeTravelSQL(sql)
+
+      expect(parsed.hasTimeTravelClause).toBe(true)
+      expect(parsed.mode).toBe('versions-between')
+      expect(parsed.cleanSql).toBe("SELECT user_id, name, _operation, _valid_from FROM users WHERE department = 'engineering'")
+      expect(parsed.tableName).toBe('users')
+
+      // 2. Parse the timestamps
+      const startTimestamp = parsed.startTimestamp!
+      const endTimestamp = parsed.endTimestamp!
+
+      expect(startTimestamp.timestampMs).toBe(1704067200000) // 2024-01-01
+      expect(endTimestamp.timestampMs).toBe(1705276800000)   // 2024-01-15
+
+      // 3. Format for display
+      const formattedStart = formatTimestamp(startTimestamp.timestampMs)
+      const formattedEnd = formatTimestamp(endTimestamp.timestampMs)
+
+      expect(formattedStart).toBe('2024-01-01T00:00:00.000Z')
+      expect(formattedEnd).toBe('2024-01-15T00:00:00.000Z')
+    })
+
+    it('should support VERSIONS BETWEEN with NOW()', () => {
+      const referenceTime = 1704153600000 // 2024-01-02
+
+      const sql = "SELECT * FROM orders VERSIONS BETWEEN '2024-01-01' AND NOW()"
+      const parsed = parseTimeTravelSQL(sql)
+
+      expect(parsed.hasTimeTravelClause).toBe(true)
+      expect(parsed.mode).toBe('versions-between')
+      expect(parsed.startTimestamp?.timestampMs).toBe(1704067200000)
+
+      // endTimestamp should be NOW(), which is relative
+      const endTimestamp = parseTimestamp(parsed.endTimestamp!.original, referenceTime)
+      expect(endTimestamp.isRelative).toBe(true)
+      expect(endTimestamp.timestampMs).toBe(referenceTime)
+    })
+  })
+
+  describe('System Columns Types', () => {
+    it('should support RowVersion type structure', () => {
+      const version: RowVersion<{ user_id: number; name: string }> = {
+        data: {
+          user_id: 123,
+          name: 'John Doe',
+        },
+        system: {
+          _operation: 'INSERT',
+          _valid_from: 1704067200000,
+          _valid_to: null,
+          _transaction_id: 1001,
+          _snapshot_id: 1,
+        },
+      }
+
+      expect(version.data.user_id).toBe(123)
+      expect(version.system._operation).toBe('INSERT')
+      expect(version.system._valid_from).toBe(1704067200000)
+      expect(version.system._valid_to).toBeNull()
+    })
+
+    it('should support all operation types', () => {
+      const operations: RowOperation[] = ['INSERT', 'UPDATE', 'DELETE']
+
+      operations.forEach(op => {
+        const systemColumns: VersionSystemColumns = {
+          _operation: op,
+          _valid_from: Date.now(),
+          _valid_to: null,
+          _transaction_id: 1,
+          _snapshot_id: 1,
+        }
+        expect(systemColumns._operation).toBe(op)
+      })
+    })
+
+    it('should support VersionsBetweenResult type structure', () => {
+      const result: VersionsBetweenResult<{ id: number; value: string }> = {
+        versions: [
+          {
+            data: { id: 1, value: 'v1' },
+            system: {
+              _operation: 'INSERT',
+              _valid_from: 1704067200000,
+              _valid_to: 1704153600000,
+              _transaction_id: 100,
+              _snapshot_id: 1,
+            },
+          },
+          {
+            data: { id: 1, value: 'v2' },
+            system: {
+              _operation: 'UPDATE',
+              _valid_from: 1704153600000,
+              _valid_to: null,
+              _transaction_id: 101,
+              _snapshot_id: 2,
+            },
+          },
+        ],
+        metadata: {
+          snapshotId: 2,
+          snapshotTimestampMs: 1704153600000,
+          requestedTimestampMs: 1704067200000,
+          mode: 'versions-between',
+          dataFilesScanned: 2,
+          totalRecords: 2,
+          snapshotCount: 2,
+          startTimestampMs: 1704067200000,
+          endTimestampMs: 1704153600000,
+        },
+        hasMore: false,
+      }
+
+      expect(result.versions.length).toBe(2)
+      expect(result.versions[0]!.system._operation).toBe('INSERT')
+      expect(result.versions[1]!.system._operation).toBe('UPDATE')
+      expect(result.hasMore).toBe(false)
+    })
+  })
+})