angelxmoreno / angelxmoreno/bun-sqlite-orm

[Feature]: Add safeIntegers configuration for handling large integers

Open
#14 0 comments 0 reactions 0 assignees View on GitHub
enhancement feature medium-priority minor
Dominant language
TypeScript
Stars
1
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## Problem Statement
The ORM doesn't leverage bun:sqlite's `safeIntegers` option for handling large integers. JavaScript only supports 53-bit integers safely, but SQLite supports 64-bit integers, which can lead to precision loss.

## Proposed Solution
Add `safeIntegers` configuration option to DataSource that enables `bigint` return types for integers larger than `Number.MAX_SAFE_INTEGER`.

## Alternatives Considered
- Always using `bigint` for all integers
- Manual conversion by users
- Warning when precision loss occurs

## Example Usage
```typescript
// DataSource with safe integers enabled
const dataSource = new DataSource({
database: 'app.db',
entities: [User],
safeIntegers: true // Returns bigint for large integers
});

// Entity with large integer support
@Entity('analytics')
class AnalyticsEvent extends BaseEntity {
@PrimaryGeneratedColumn('increment')
id\!: number; // Will be bigint if > MAX_SAFE_INTEGER

@Column()
timestamp\!: bigint; // Large timestamp values

@Column()
userId\!: number; // Regular integers still work
}

// Usage with type safety
const event = await AnalyticsEvent.get(BigInt(Number.MAX_SAFE_INTEGER) + 100n);
console.log(typeof event.timestamp); // 'bigint'
```

## Impact
- Query API: ✓
- Performance: ✗
- Entity definitions: ✓
- Validation: ✗
- Migrations: ✗
- TypeScript types: ✓
- Documentation: ✓

## Additional Context

**Benefits of Safe Integers:**
- Prevents precision loss for large integers
- Type safety with `bigint`
- Validation of 64-bit integer bounds
- Better handling of timestamps and IDs

**Implementation Details:**
- Configure `Database` constructor with `{ safeIntegers: true }`
- Update entity metadata to handle `bigint` types
- Add TypeScript type definitions for mixed number/bigint scenarios
- Validation for bigint values exceeding 64-bit bounds

**Use Cases:**
- Large timestamp values (microseconds, nanoseconds)
- High-volume auto-increment IDs
- Financial calculations requiring precision
- Scientific applications with large integers

**Considerations:**
- Breaking change for existing code expecting `number`
- TypeScript type complexity with mixed integer types
- Performance impact of bigint operations
- Serialization/JSON handling of bigint values

**Priority:** Medium - Important for applications with large integers
**Estimated Impact:** Critical for high-volume applications

Contributor guide

Open the contributing guide

Research direction

Start by locating the DataSource configuration and the Database constructor setup referenced in the issue, then inspect how entity metadata and TypeScript integer types are currently handled. Define how safeIntegers affects number and bigint values, including 64-bit validation and serialization, and add coverage for the large-integer usage shown in the example.

Written by the indexing model from the issue text.

Assessment

Tech stack
bun, sqlite, typescript
Domain
database
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.