litedbmodel 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (21) hide show
  1. package/README.md +1 -1
  2. package/dist/DBModel.d.ts +5 -2
  3. package/dist/DBModel.d.ts.map +1 -1
  4. package/dist/DBModel.js +55 -22
  5. package/dist/DBModel.js.map +1 -1
  6. package/dist/LazyRelation.d.ts.map +1 -1
  7. package/dist/LazyRelation.js +9 -3
  8. package/dist/LazyRelation.js.map +1 -1
  9. package/dist/decorators.d.ts.map +1 -1
  10. package/dist/decorators.js +6 -8
  11. package/dist/decorators.js.map +1 -1
  12. package/dist/drivers/PostgresHelper.d.ts.map +1 -1
  13. package/dist/drivers/PostgresHelper.js +4 -0
  14. package/dist/drivers/PostgresHelper.js.map +1 -1
  15. package/dist/drivers/postgres.d.ts.map +1 -1
  16. package/dist/drivers/postgres.js +57 -10
  17. package/dist/drivers/postgres.js.map +1 -1
  18. package/docs/BENCHMARK.md +52 -52
  19. package/docs/COMPARISON.md +5 -5
  20. package/docs/benchmark-chart.svg +163 -163
  21. package/package.json +1 -1
package/docs/BENCHMARK.md CHANGED
@@ -27,52 +27,52 @@ Reference: [Kysely performance comparison article](https://izanami.dev/post/1e3f
27
27
  <!--@embedoc:benchmark_table-->
28
28
  | Operation | litedbmodel | Kysely | Drizzle | TypeORM | Prisma |
29
29
  | --- | --- | --- | --- | --- | --- |
30
- | Find all (limit 100) | 0.65ms | **0.61ms** 🏆 | **0.61ms** 🏆 | 0.69ms | 1.28ms |
31
- | Filter, paginate & sort | **0.55ms** 🏆 | 0.57ms | 0.61ms | 0.64ms | 0.95ms |
32
- | Nested find all (include posts) | 3.57ms | 4.59ms | **3.32ms** 🏆 | 7.63ms | 12.37ms |
33
- | Find first | 0.35ms | **0.31ms** 🏆 | 0.32ms | 0.33ms | 0.59ms |
34
- | Nested find first (include posts) | 0.57ms | 0.53ms | 0.58ms | **0.46ms** 🏆 | 0.98ms |
35
- | Find unique (by email) | 0.29ms | **0.27ms** 🏆 | 0.29ms | 0.32ms | 0.54ms |
36
- | Nested find unique (include posts) | 0.56ms | **0.50ms** 🏆 | 0.57ms | 0.94ms | 0.88ms |
37
- | Create | **0.62ms** 🏆 | 0.67ms | 0.69ms | 0.74ms | 0.97ms |
38
- | Nested create (with post) | 0.91ms | **0.89ms** 🏆 | 0.95ms | 1.15ms | 1.64ms |
39
- | Update | **0.65ms** 🏆 | 0.66ms | **0.65ms** 🏆 | **0.65ms** 🏆 | 1.11ms |
40
- | Nested update (update user + post) | **0.86ms** 🏆 | 0.87ms | 0.92ms | 0.95ms | 2.12ms |
41
- | Upsert | 0.65ms | **0.63ms** 🏆 | 0.67ms | 0.75ms | 1.77ms |
42
- | Nested upsert (user + post) | **0.87ms** 🏆 | 0.90ms | 0.95ms | 0.98ms | 1.92ms |
43
- | Delete | **0.85ms** 🏆 | 0.88ms | 0.91ms | 0.96ms | 1.44ms |
44
- | Create Many (10 records) | 0.68ms | **0.67ms** 🏆 | 0.85ms | 0.91ms | 1.17ms |
45
- | Upsert Many (10 records) | 0.81ms | **0.80ms** 🏆 | 0.98ms | 1.02ms | 11.34ms |
46
- | Update Many (10 different values) | **0.75ms** 🏆 | 2.71ms | 2.79ms | 3.05ms | 5.24ms |
47
- | Nested relations (100→1000→10000) | 26.84ms | 23.74ms | **22.31ms** 🏆 | 75.25ms | 83.91ms |
48
- | Nested relations (composite key, 5 tenants) | 23.38ms | N/A | **15.75ms** 🏆 | 37.72ms | 214.51ms |
30
+ | Find all (limit 100) | 0.70ms | 0.65ms | **0.64ms** 🏆 | 0.72ms | 1.35ms |
31
+ | Filter, paginate & sort | **0.58ms** 🏆 | 0.64ms | 0.59ms | 0.66ms | 1.10ms |
32
+ | Nested find all (include posts) | **3.64ms** 🏆 | 4.60ms | 4.66ms | 8.34ms | 12.06ms |
33
+ | Find first | 0.37ms | **0.32ms** 🏆 | 0.36ms | 0.40ms | 0.59ms |
34
+ | Nested find first (include posts) | 0.65ms | 0.61ms | 0.71ms | **0.52ms** 🏆 | 1.06ms |
35
+ | Find unique (by email) | **0.29ms** 🏆 | 0.31ms | 0.30ms | 0.32ms | 0.53ms |
36
+ | Nested find unique (include posts) | **0.57ms** 🏆 | 0.58ms | 0.59ms | 1.05ms | 0.94ms |
37
+ | Create | 0.69ms | **0.68ms** 🏆 | 0.76ms | 0.79ms | 1.01ms |
38
+ | Nested create (with post) | **0.90ms** 🏆 | 0.96ms | 1.03ms | 1.22ms | 1.81ms |
39
+ | Update | 0.63ms | **0.61ms** 🏆 | 0.66ms | 0.67ms | 1.12ms |
40
+ | Nested update (update user + post) | 0.94ms | 1.00ms | **0.92ms** 🏆 | 1.02ms | 2.28ms |
41
+ | Upsert | 0.71ms | 0.74ms | **0.66ms** 🏆 | 0.75ms | 2.07ms |
42
+ | Nested upsert (user + post) | **1.00ms** 🏆 | **1.00ms** 🏆 | **1.00ms** 🏆 | 1.14ms | 2.27ms |
43
+ | Delete | **0.97ms** 🏆 | 1.00ms | 0.98ms | 1.10ms | 1.72ms |
44
+ | Create Many (10 records) | 0.77ms | **0.72ms** 🏆 | 0.89ms | 1.00ms | 1.20ms |
45
+ | Upsert Many (10 records) | **0.88ms** 🏆 | 0.90ms | 1.03ms | 1.06ms | 11.89ms |
46
+ | Update Many (10 different values) | **0.70ms** 🏆 | 2.83ms | 2.75ms | 3.02ms | 5.31ms |
47
+ | Nested relations (100→1000→10000) | 25.82ms | 24.65ms | **24.25ms** 🏆 | 80.56ms | 84.10ms |
48
+ | Nested relations (composite key, 5 tenants) | 22.41ms | N/A | **16.26ms** 🏆 | 39.25ms | 219.00ms |
49
49
  <!--@embedoc:end-->
50
50
 
51
51
  *All write operations wrapped in transactions for fair comparison across all ORMs.*
52
52
 
53
53
  ### Analysis
54
54
 
55
- 1. **litedbmodel** - **Fastest in write operations** 🏆
56
- - **#1 in Filter/paginate, Create, Update (tie), Nested update, Nested upsert, Delete, Update Many**
57
- - Update Many with different values: **3.6x - 7.0x faster** than other ORMs
55
+ 1. **litedbmodel** - **Fastest in read/write operations** 🏆
56
+ - **#1 in Filter/paginate, Nested find all, Find unique, Nested find unique, Nested create, Nested upsert (tie), Delete, Upsert Many, Update Many**
57
+ - Update Many with different values: **3.9x - 7.6x faster** than other ORMs
58
58
  - Excellent balance of read and write performance
59
59
 
60
60
  2. **Kysely** - **Strong simple query performance**
61
- - **#1 in Find all (tie), Find first, Find unique, Nested find unique, Nested create, Upsert, Create Many, Upsert Many**
61
+ - **#1 in Find first, Create, Update, Create Many**
62
62
  - Minimal abstraction overhead
63
63
  - **Limitation:** Cannot batch load composite FK
64
64
 
65
65
  3. **Drizzle** - **Fastest in nested relations** 🏆
66
- - **#1 in Find all (tie), Nested find all, Update (tie), Nested relations single key (22ms), Nested composite key (16ms)** using LATERAL JOIN
66
+ - **#1 in Find all, Nested update, Upsert, Nested upsert (tie), Nested relations single key (24ms), Nested composite key (16ms)** using LATERAL JOIN
67
67
  - Query API with relations provides excellent performance
68
68
 
69
69
  4. **TypeORM** - Variable performance
70
- - **#1 in Update (tie), Nested find first** (JOIN-based approach)
71
- - Decent composite key support (38ms)
70
+ - **#1 in Nested find first** (JOIN-based approach)
71
+ - Decent composite key support (39ms)
72
72
 
73
73
  5. **Prisma** - Convenience over speed
74
74
  - **Slowest in most operations** (1.5x - 14x slower)
75
- - Composite key nested: 215ms (**14x slower** than Drizzle)
75
+ - Composite key nested: 219ms (**13x slower** than Drizzle)
76
76
  - Trade-off: Rich DX features (Prisma Studio, migrations, etc.)
77
77
 
78
78
  ---
@@ -89,33 +89,33 @@ Reference: [Kysely performance comparison article](https://izanami.dev/post/1e3f
89
89
 
90
90
  | ORM | Median | Ratio | Queries | Notes |
91
91
  |-----|--------|-------|---------|-------|
92
- | **Drizzle** 🏆 | **22.31ms** | **1.00x** | 1 | **LATERAL JOIN** |
93
- | Kysely | 23.74ms | 1.06x | 3 | Separate queries |
94
- | litedbmodel | 26.84ms | 1.20x | 3 | Separate queries + sync cache |
95
- | TypeORM | 75.25ms | 3.37x | 2 | JOIN-based |
96
- | Prisma | 83.91ms | 3.76x | 3 | Parameter explosion |
92
+ | **Drizzle** 🏆 | **24.25ms** | **1.00x** | 1 | **LATERAL JOIN** |
93
+ | Kysely | 24.65ms | 1.02x | 3 | Separate queries |
94
+ | litedbmodel | 25.82ms | 1.06x | 3 | Separate queries + sync cache |
95
+ | TypeORM | 80.56ms | 3.32x | 2 | JOIN-based |
96
+ | Prisma | 84.10ms | 3.47x | 3 | Parameter explosion |
97
97
 
98
98
  ### Composite Key Relations (5 tenants × 100 users)
99
99
 
100
100
  | ORM | Median | Ratio | Queries | Notes |
101
101
  |-----|--------|-------|---------|-------|
102
- | **Drizzle** 🏆 | **15.75ms** | **1.00x** | 1 | **LATERAL JOIN with composite** |
103
- | litedbmodel | 23.38ms | 1.48x | 3 | unnest + JOIN |
104
- | TypeORM | 37.72ms | 2.39x | 2 | Multiple OR conditions |
105
- | Prisma | 214.51ms | 13.62x | 3 | Parameter explosion (2000+ params) |
102
+ | **Drizzle** 🏆 | **16.26ms** | **1.00x** | 1 | **LATERAL JOIN with composite** |
103
+ | litedbmodel | 22.41ms | 1.38x | 3 | unnest + JOIN |
104
+ | TypeORM | 39.25ms | 2.41x | 2 | Multiple OR conditions |
105
+ | Prisma | 219.00ms | 13.47x | 3 | Parameter explosion (2000+ params) |
106
106
  | Kysely | N/A | - | - | Cannot batch composite FK |
107
107
 
108
108
  ### Deep Nested Analysis
109
109
 
110
110
  **Single Key:**
111
- - Drizzle fastest with LATERAL JOIN (22ms)
112
- - Kysely close (24ms) with 3 separate queries
113
- - litedbmodel (27ms, 1.20x) with 3 separate queries
111
+ - Drizzle fastest with LATERAL JOIN (24ms)
112
+ - Kysely close (25ms) with 3 separate queries
113
+ - litedbmodel (26ms, 1.06x) with 3 separate queries
114
114
 
115
115
  **Composite Key (multi-tenant):**
116
116
  - **Drizzle fastest (16ms)** with LATERAL JOIN query API
117
- - litedbmodel 1.48x (23ms) with `unnest + JOIN` approach
118
- - Prisma 14x slower with 2000+ parameters
117
+ - litedbmodel 1.38x (22ms) with `unnest + JOIN` approach
118
+ - Prisma 13x slower with 2000+ parameters
119
119
  - **Kysely cannot batch load composite FK** (would require manual tuple matching)
120
120
 
121
121
  > **Drizzle advantage:** LATERAL JOIN provides fastest nested relation loading for both single and composite keys when using the query API with relations.
@@ -538,11 +538,11 @@ WHERE (tenant_id, user_id) IN (($1,$2),($3,$4),...,($1999,$2000))
538
538
 
539
539
  | Scenario | Best Fit | Notes |
540
540
  |----------|----------|-------|
541
- | Write operations (transactions) | **litedbmodel** | Fastest in Create, Upsert, Delete, etc. |
542
- | Bulk Update (diff values) | **litedbmodel** | **3.8x - 7.3x faster** than others (single query) |
543
- | Nested find all | **litedbmodel** | Fastest at 3.59ms |
544
- | Nested single key (speed) | Drizzle | 1 query via LATERAL JOIN (22ms) |
545
- | Nested composite key (speed) | **litedbmodel** | **23ms** (7x faster than Drizzle, 9x faster than Prisma) |
541
+ | Write operations (transactions) | **litedbmodel** | Fastest in Nested create, Delete, Upsert Many, etc. |
542
+ | Bulk Update (diff values) | **litedbmodel** | **3.9x - 7.6x faster** than others (single query) |
543
+ | Nested find all | **litedbmodel** | Fastest at 3.64ms |
544
+ | Nested single key (speed) | Drizzle | 1 query via LATERAL JOIN (24ms) |
545
+ | Nested composite key (speed) | Drizzle | 16ms via LATERAL JOIN |
546
546
  | Nested relation SQL quality | **litedbmodel** | Readable + debuggable; stable query patterns (PG) |
547
547
  | Log Analysis / Monitoring | **litedbmodel** | Consistent query patterns |
548
548
  | SQL Fingerprint Stability (PG) | **litedbmodel** | Most predictable in prepared-statement setups |
@@ -550,14 +550,14 @@ WHERE (tenant_id, user_id) IN (($1,$2),($3,$4),...,($1999,$2000))
550
550
  | Data Integrity | **litedbmodel** | Explicit transactions required for writes |
551
551
 
552
552
  **litedbmodel excels at:**
553
- - **Write operations** (Create, Nested create, Upsert, Delete - all fastest when using transactions)
554
- - **Bulk update with different values** (3.8x - 7.3x faster)
555
- - **Nested find all** (fastest at 3.40ms)
553
+ - **Read operations** (Find unique, Nested find unique, Nested find all - all fastest)
554
+ - **Write operations** (Nested create, Delete, Upsert Many, Update Many - fastest)
555
+ - **Bulk update with different values** (3.9x - 7.6x faster)
556
556
  - **Consistent performance** across all operations
557
557
  - **Data integrity** via required transactions
558
558
 
559
- **vs Prisma:** litedbmodel is **1.6x - 14.4x faster** across operations
560
- **vs Query Builders:** litedbmodel is **fastest for write operations** when all ORMs use transactions
559
+ **vs Prisma:** litedbmodel is **1.5x - 13.5x faster** across operations
560
+ **vs Query Builders:** litedbmodel matches or beats Kysely/Drizzle in most operations
561
561
 
562
562
  > **litedbmodel provides best-in-class performance with safety guarantees:**
563
563
  > - Type-safe column symbols (IDE refactoring)
@@ -569,6 +569,6 @@ WHERE (tenant_id, user_id) IN (($1,$2),($3,$4),...,($1999,$2000))
569
569
 
570
570
  ---
571
571
 
572
- *Last updated: January 2026*
572
+ *Last updated: March 2026*
573
573
  *Benchmark methodology: Based on [Prisma orm-benchmarks](https://github.com/prisma/orm-benchmarks)*
574
574
 
package/docs/COMPARISON.md CHANGED
@@ -1077,13 +1077,13 @@ For detailed benchmark results comparing litedbmodel with Prisma, Kysely, Drizzl
1077
1077
 
1078
1078
  | Operation Type | litedbmodel Performance |
1079
1079
  |----------------|------------------------|
1080
- | Standard CRUD | **Fastest in 7/14 operations** (Find all, Filter/sort, Create, Upsert, Delete) |
1081
- | Nested relations | Competitive (within 10% of fastest) |
1082
- | Deep nested (10K) | 2.9x faster than Prisma |
1080
+ | Standard CRUD | **Fastest in 9/19 operations** (Filter/sort, Nested find all, Find unique, Nested find unique, Nested create, Delete, Upsert Many, Update Many, etc.) |
1081
+ | Nested relations | Competitive (within 6% of fastest) |
1082
+ | Deep nested (10K) | 3.3x faster than Prisma |
1083
1083
  | SQL quality | ⭐⭐⭐⭐⭐ (readable, fixed params on PG) |
1084
1084
 
1085
- **vs Prisma:** litedbmodel is **1.6x - 5.9x faster** across all operations
1086
- **vs Query Builders:** litedbmodel is competitive (within 10%), with better DX
1085
+ **vs Prisma:** litedbmodel is **1.5x - 13.5x faster** across all operations
1086
+ **vs Query Builders:** litedbmodel matches or beats Kysely/Drizzle in most operations
1087
1087
 
1088
1088
  ---
1089
1089