v0.3.0: Unique indexes, by-key helpers, JS array migration, and benchmark suite

[emremy]

Overview

This release introduces unique indexes, stable key-based helpers, JS array migration utilities, and a comprehensive JS Array vs ColQL benchmark suite.

The goal of v0.3.0 is to make ColQL more practical for real-world backend usage while strengthening correctness guarantees and improving performance transparency.

---

Highlights

🔐 Unique Indexes (Data Integrity + Fast Lookup)

ColQL now supports unique indexes:

users.createUniqueIndex("id");
users.createUniqueIndex("email");

Guarantees:

• Duplicate inserts are rejected
• insertMany is all-or-nothing on duplicates
• Updates cannot violate uniqueness
• Deleted keys can be reused
• Unique indexes never return stale row positions

Supported:

• numeric columns
• dictionary columns

Not supported:

• boolean columns

---

🔑 By-Key Helpers

Stable-key operations are now first-class:

users.findBy("id", 123);
users.updateBy("email", "a@b.com", { active: false });
users.deleteBy("id", 123);

• Require a unique index
• Do not rely on unstable rowIndex
• Provide predictable single-row semantics

---

🔄 JS Array Migration Helpers

Easier transition from JS arrays:

const users = fromRows(schema, rows);

users.firstWhere({ id: 1 });
users.countWhere({ active: true });
users.exists({ country: "TR" });

• Thin wrappers over the query engine
• Fully typed
• Preserve lazy execution behavior

---

📊 JS Array vs ColQL Benchmark Suite

New benchmark comparing:

• JS object arrays
• ColQL scan
• equality index
• sorted index
• unique index

Across:

• 1k / 100k / 1M rows
• memory usage
• filtering
• projection + limit
• lookup
• range queries
• mutations

Key observations:

• ~6–7x lower memory usage vs JS arrays at 1M rows
• sub-millisecond indexed lookups
• projection + limit significantly faster
• JS arrays remain faster for simple full scans
• filter(fn) is a full-scan escape hatch and can be expensive

Benchmarks are local reference results, not universal guarantees.

---

⚡ Performance Improvements

• Optimized structured scan hot path
• Reduced 1M-row scan latency from ~40ms → ~20ms
• Bulk compaction for deleteMany
• Avoid unnecessary unique index rebuilds
• Clearer benchmark measurement (setup excluded from timing)

---

🧪 Expanded Test Coverage

• Real-world scenario tests:
  • user directory (id/email uniqueness)
  • product catalog (SKU uniqueness + range queries)
  • session/token registry
  • feature flags
• Mixed operation sequences (insert → update → delete → rebuild → serialize)
• Edge cases for unique indexes
• Parity checks against JS array oracle

---

Design Notes

• Equality and sorted indexes remain performance-only
• Unique indexes add data integrity guarantees
• Row indexes are not stable identifiers
• Unique indexes are not serialized and must be recreated after restore
• Broad mutations may be slower than raw JS arrays due to safety guarantees

---

When to Use ColQL

ColQL is most useful when:

• Data is already in-process
• Memory efficiency matters
• Indexed lookups or range queries are needed
• You want structured queries without a database roundtrip

JS arrays may still be preferable for:

• Small datasets
• Simple scans
• Minimal logic

---

Breaking Changes

None.

---

Notes

This release focuses on correctness, clarity, and real-world usability rather than adding heavy features or external integrations.