@kedem/okdb 1.1.3 → 1.2.0

package/docs/http-api.md

@@ -449,6 +449,7 @@ DELETE /api/:env/type/:type             → drop a type
 
 POST /api/:env/type/:type/indexes       → register an index
 DELETE /api/:env/type/:type/index/:idx  → drop an index
+GET  /api/:env/type/:type/index/:idx/count?start=<json>&end=<json>  → count index entries in range
 ```
 
 ---

package/docs/indexes.md

@@ -100,6 +100,28 @@ The trailing `null` sentinel in the LMDB key format ensures that a prefix scan o
 
 ---
 
+## Counting without loading records
+
+`countByIndex` counts matching index entries without touching the data store:
+
+```javascript
+await okdb.registerIndex('orders', ['status']);
+
+const pending = okdb.countByIndex('orders', ['status'], {
+    start: ['pending'],
+    end: ['pending', OKDBEnv.HIGH_SENTINEL],
+});
+
+// Compound index
+await okdb.registerIndex('orders', ['status', 'createdAt']);
+const open = okdb.countByIndex('orders', ['status', 'createdAt'], {
+    start: ['open'],
+    end: ['open', OKDBEnv.HIGH_SENTINEL],
+});
+```
+
+---
+
 ## Dot-notation for nested fields
 
 Field paths can use dots to reach nested properties:

package/docs/querying.md

@@ -161,6 +161,35 @@ for (const { key, value } of okdb.byIndex('articles', ['author', 'publishedAt'],
 | `offset`            | number  | Skip this many entries                            |
 | `includeViolations` | boolean | For unique indexes: include all violating entries |
 
+`getIndex` returns primary keys from the index sub-database (not full records) as a **lazy iterable**. Spread to an array if you need `.length`: `[...env.getIndex(...)]`.
+
+---
+
+## Counting index entries
+
+`countByIndex` counts entries in an index range without loading any record data. It reads only the index sub-database — O(matching index entries), no record loads.
+
+Pass `{start, end}` directly, same as `byIndex`. Use `OKDBEnv.HIGH_SENTINEL` as the end bound for prefix scans:
+
+```javascript
+// Count orders with status === 'pending'
+const n = okdb.countByIndex('orders', ['status'], {
+    start: ['pending'],
+    end: ['pending', OKDBEnv.HIGH_SENTINEL],
+});
+
+// Compound index — count by first field prefix
+const open = okdb.countByIndex('orders', ['status', 'createdAt'], {
+    start: ['open'],
+    end: ['open', OKDBEnv.HIGH_SENTINEL],
+});
+```
+
+**`countByIndex` vs `getCount`:**
+
+- `getCount(type)` — O(1), total count, no filtering.
+- `countByIndex(type, index, {start, end})` — O(matching index entries), filtered count, no record loads.
+
 ---
 
 ## Geo query