timescaledb-ts

Power your TimescaleDB applications with TypeScript

Welcome to the Timescale Typescript library. This library is a collection of packages that help you work with TimescaleDB in a Typescript environment.

If you are looking to setup this project locally, you can follow the instructions in the CONTRIBUTING.md file.

Packages

• @timescaledb/typeorm - Official TimescaleDB integration for TypeORM.
• @timescaledb/core - Migration and query helpers
• @timescaledb/schemas - TimescaleDB object schemas
• @timescaledb/utils - utilities and helpers

Examples

• Node Sequelize Example - Using TimescaleDB with Node.js and Sequelize
• Node TypeORM Example - Using TimescaleDB with Node.js and TypeORM

Guides

• Getting Started - A guide to getting started with TimescaleDB and this library.
• Working with Energy Data - A guide to working with energy data in TimescaleDB.
• Working with Candlesticks - A guide to working with candlestick data in TimescaleDB.

Feature Compatibility

Feature	Core	TypeORM	Sequelize
Core Functions
Create Hypertable	✅	✅ Auto	✅ Manual (via Core)
Add Compression	✅	✅ Auto	✅ Manual (via Core)
Add Compression Policy	✅	✅ Auto	✅ Manual (via Core)
Add Retention Policy	❌	❌	❌
Continuous Aggregates	✅	✅ Auto	✅ Manual (via Core)
Hyperfunctions
Time Bucket	✅	✅	✅ Manual (via Core)
Candlestick Aggregates	✅	✅	✅ Manual (via Core)
Stats Aggregates	❌	❌	❌
Percentile Approximation	❌	❌	❌
Info Views
Chunks	❌	❌	❌
User Defined Actions	❌	❌	❌
Compression Settings	✅	✅	✅ Manual (via Core)
Continuous Aggregates	✅	✅	✅ Manual (via Core)
Hierarchical continuous aggregates	✅	✅	✅ Manual (via Core)

Legend:

• ✅ Supported
• ❌ Not Supported at this time
• Auto = Automatic integration with ORM
• Manual = Manual integration using Core package

Getting Started

• TypeORM: README

To get started with TypeORM simply install the package:

npm install typeorm @timescaledb/typeorm

Then you can use the @Hypertable decorator to define your hypertables:

import { Entity, PrimaryColumn } from 'typeorm';
+ import { Hypertable, TimeColumn } from '@timescaledb/typeorm';

+ @Hypertable({ ... })
@Entity('page_loads')
export class PageLoad {
  @PrimaryColumn({ type: 'varchar' })
  user_agent!: string;

+  @TimeColumn()
  time!: Date;
}

Then you can query a Hypertable using the attached methods:

import { AppDataSource } from './data-source';
import { PageLoad } from './models/PageLoad';

const repository = AppDataSource.getRepository(PageLoad);
const stats = await repository.getTimeBucket({
  timeRange: {
    start: new Date('2025-01-01'),
    end: new Date('2025-01-02'),
  },
  where: {
    user_agent: 'Chrome',
  },
  bucket: {
    interval: '1 hour',
    metrics: [{ type: 'distinct_count', column: 'user_agent', alias: 'unique_users' }],
  },
});

console.log(stats);
// [
//   { time: '2021-01-01T00:00:00.000Z', unique_users: 5 },
//   { time: '2021-01-01T01:00:00.000Z', unique_users: 10 },
//   { time: '2021-01-01T02:00:00.000Z', unique_users: 15 },
//   ...
// ]

License

The library is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Timescale project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.