@quereus/store 0.4.14 → 0.5.1

package/README.md

@@ -27,6 +27,23 @@ This architecture enables:
 - **Custom storage backends** - Implement `KVStore` for IndexedDB, LevelDB, LMDB, or other "NoSQL" stores
 - **Dependency injection** - Use `KVStoreProvider` for store management
 
+## Storage Architecture
+
+The store module uses separate logical stores for different data types:
+
+**Store Naming Convention:**
+- `{schema}.{table}` - Data store (row data)
+- `{schema}.{table}_idx_{indexName}` - Index stores (one per secondary index)
+- `{prefix}.__stats__` - Unified stats store (row counts for all tables)
+- `__catalog__` - Catalog store (DDL metadata)
+
+**Key Formats:**
+- **Data keys**: Encoded primary key (no prefix)
+- **Index keys**: Encoded index columns + encoded PK
+- **Catalog keys**: `{schema}.{table}` as string
+
+This design eliminates redundant prefixes and groups related stores together by table name.
+
 ## Installation
 
 ```bash
@@ -83,14 +100,22 @@ class MyCustomStore implements KVStore {
   iterate(options?: IterateOptions) { /* ... */ }
   batch() { /* ... */ }
   async close() { /* ... */ }
+  async approximateCount(options?: IterateOptions) { /* ... */ }
 }
 
 class MyCustomProvider implements KVStoreProvider {
   async getStore(schemaName: string, tableName: string) {
     return new MyCustomStore(/* ... */);
   }
+  async getIndexStore(schemaName: string, tableName: string, indexName: string) {
+    return new MyCustomStore(/* ... */);
+  }
+  async getStatsStore(schemaName: string, tableName: string) {
+    return new MyCustomStore(/* ... */);
+  }
   async getCatalogStore() { /* ... */ }
   async closeStore(schemaName: string, tableName: string) { /* ... */ }
+  async closeIndexStore(schemaName: string, tableName: string, indexName: string) { /* ... */ }
   async closeAll() { /* ... */ }
 }
 
@@ -113,13 +138,30 @@ interface KVStore {
   iterate(options?: IterateOptions): AsyncIterable<KVEntry>;
   batch(): WriteBatch;
   close(): Promise<void>;
+  approximateCount(options?: IterateOptions): Promise<number>;
 }
 
 interface KVStoreProvider {
+  // Get data store for a table
   getStore(schemaName: string, tableName: string): Promise<KVStore>;
+  
+  // Get index store for a secondary index
+  getIndexStore(schemaName: string, tableName: string, indexName: string): Promise<KVStore>;
+  
+  // Get stats store for table statistics
+  getStatsStore(schemaName: string, tableName: string): Promise<KVStore>;
+  
+  // Get catalog store for DDL metadata
   getCatalogStore(): Promise<KVStore>;
+  
+  // Close specific stores
   closeStore(schemaName: string, tableName: string): Promise<void>;
+  closeIndexStore(schemaName: string, tableName: string, indexName: string): Promise<void>;
   closeAll(): Promise<void>;
+  
+  // Optional: Delete stores
+  deleteIndexStore?(schemaName: string, tableName: string, indexName: string): Promise<void>;
+  deleteTableStores?(schemaName: string, tableName: string): Promise<void>;
 }
 ```
 
@@ -162,10 +204,17 @@ interface KVStoreProvider {
 
 | Export | Description |
 |--------|-------------|
-| `buildDataKey` | Build key for row data |
+| `buildDataStoreName` | Build store name for table data |
+| `buildIndexStoreName` | Build store name for an index |
+| `buildStatsStoreName` | Build store name for table stats |
+| `buildDataKey` | Build key for row data (encoded PK) |
 | `buildIndexKey` | Build key for index entry |
-| `buildMetaKey` | Build key for metadata |
-| `buildTableScanBounds` | Build bounds for table scan |
+| `buildCatalogKey` | Build key for catalog metadata |
+| `buildFullScanBounds` | Build bounds for full table scan |
+| `buildIndexPrefixBounds` | Build bounds for index prefix scan |
+| `buildCatalogScanBounds` | Build bounds for catalog scan |
+| `CATALOG_STORE_NAME` | Reserved catalog store name constant |
+| `STORE_SUFFIX` | Store name suffixes (INDEX, STATS) |
 
 ## Related Packages
 
@@ -176,4 +225,3 @@ interface KVStoreProvider {
 ## License
 
 MIT
-

package/dist/src/common/index.d.ts

@@ -4,7 +4,7 @@
 export type { KVStore, KVEntry, WriteBatch, BatchOp, IterateOptions, KVStoreFactory, KVStoreOptions, KVStoreProvider, } from './kv-store.js';
 export { encodeValue, encodeCompositeKey, decodeValue, decodeCompositeKey, registerCollationEncoder, getCollationEncoder, type CollationEncoder, type EncodeOptions, } from './encoding.js';
 export { serializeRow, deserializeRow, serializeValue, deserializeValue, serializeStats, deserializeStats, type TableStats, } from './serialization.js';
-export { KEY_PREFIX, buildDataKey, buildIndexKey, buildMetaKey, buildTablePrefix, buildTableScanBounds, buildIndexScanBounds, buildMetaScanBounds, } from './key-builder.js';
+export { STORE_SUFFIX, CATALOG_STORE_NAME, STATS_STORE_NAME, buildDataStoreName, buildIndexStoreName, buildStatsStoreName, buildStatsKey, buildDataKey, buildIndexKey, buildCatalogKey, buildFullScanBounds, buildIndexPrefixBounds, buildCatalogScanBounds, KEY_PREFIX, buildTablePrefix, buildTableScanBounds, buildIndexScanBounds, buildMetaKey, buildMetaScanBounds, } from './key-builder.js';
 export { StoreEventEmitter, type SchemaChangeEvent, type DataChangeEvent, type SchemaChangeListener, type DataChangeListener, } from './events.js';
 export { generateTableDDL, generateIndexDDL, } from './ddl-generator.js';
 export { TransactionCoordinator, type TransactionCallbacks, } from './transaction.js';

package/dist/src/common/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,YAAY,EACV,OAAO,EACP,OAAO,EACP,UAAU,EACV,OAAO,EACP,cAAc,EACd,cAAc,EACd,cAAc,EACd,eAAe,GAChB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,kBAAkB,EAClB,wBAAwB,EACxB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,KAAK,UAAU,GAChB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,UAAU,EACV,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,sBAAsB,EACtB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EACL,UAAU,EACV,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,EAAE,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,YAAY,EACV,OAAO,EACP,OAAO,EACP,UAAU,EACV,OAAO,EACP,cAAc,EACd,cAAc,EACd,cAAc,EACd,eAAe,GAChB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,kBAAkB,EAClB,wBAAwB,EACxB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,KAAK,UAAU,GAChB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACN,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EAEtB,UAAU,EACV,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,EACZ,mBAAmB,GACnB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,sBAAsB,EACtB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EACL,UAAU,EACV,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,EAAE,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/src/common/index.js

@@ -5,8 +5,10 @@
 export { encodeValue, encodeCompositeKey, decodeValue, decodeCompositeKey, registerCollationEncoder, getCollationEncoder, } from './encoding.js';
 // Row serialization
 export { serializeRow, deserializeRow, serializeValue, deserializeValue, serializeStats, deserializeStats, } from './serialization.js';
-// Key building
-export { KEY_PREFIX, buildDataKey, buildIndexKey, buildMetaKey, buildTablePrefix, buildTableScanBounds, buildIndexScanBounds, buildMetaScanBounds, } from './key-builder.js';
+// Key building - new API
+export { STORE_SUFFIX, CATALOG_STORE_NAME, STATS_STORE_NAME, buildDataStoreName, buildIndexStoreName, buildStatsStoreName, buildStatsKey, buildDataKey, buildIndexKey, buildCatalogKey, buildFullScanBounds, buildIndexPrefixBounds, buildCatalogScanBounds, 
+// Legacy exports (deprecated)
+KEY_PREFIX, buildTablePrefix, buildTableScanBounds, buildIndexScanBounds, buildMetaKey, buildMetaScanBounds, } from './key-builder.js';
 // Events
 export { StoreEventEmitter, } from './events.js';
 // DDL generation

package/dist/src/common/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/common/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAcH,eAAe;AACf,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,kBAAkB,EAClB,wBAAwB,EACxB,mBAAmB,GAGpB,MAAM,eAAe,CAAC;AAEvB,oBAAoB;AACpB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,gBAAgB,GAEjB,MAAM,oBAAoB,CAAC;AAE5B,eAAe;AACf,OAAO,EACL,UAAU,EACV,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAE1B,SAAS;AACT,OAAO,EACL,iBAAiB,GAKlB,MAAM,aAAa,CAAC;AAErB,iBAAiB;AACjB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,sBAAsB;AACtB,OAAO,EACL,sBAAsB,GAEvB,MAAM,kBAAkB,CAAC;AAE1B,qBAAqB;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,qCAAqC;AACrC,OAAO,EACL,UAAU,GAGX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,uBAAuB;AACvB,OAAO,EAAE,WAAW,EAA0B,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/common/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAcH,eAAe;AACf,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,kBAAkB,EAClB,wBAAwB,EACxB,mBAAmB,GAGpB,MAAM,eAAe,CAAC;AAEvB,oBAAoB;AACpB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,gBAAgB,GAEjB,MAAM,oBAAoB,CAAC;AAE5B,yBAAyB;AACzB,OAAO,EACN,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB;AACtB,8BAA8B;AAC9B,UAAU,EACV,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,EACZ,mBAAmB,GACnB,MAAM,kBAAkB,CAAC;AAE1B,SAAS;AACT,OAAO,EACL,iBAAiB,GAKlB,MAAM,aAAa,CAAC;AAErB,iBAAiB;AACjB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,sBAAsB;AACtB,OAAO,EACL,sBAAsB,GAEvB,MAAM,kBAAkB,CAAC;AAE1B,qBAAqB;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,qCAAqC;AACrC,OAAO,EACL,UAAU,GAGX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,uBAAuB;AACvB,OAAO,EAAE,WAAW,EAA0B,MAAM,mBAAmB,CAAC"}

package/dist/src/common/key-builder.d.ts

@@ -1,57 +1,113 @@
 /**
  * Key builder utilities for constructing storage keys.
  *
- * Key prefixes:
- *   d: - Data rows
- *   i: - Secondary indexes
- *   m: - Metadata (DDL, stats)
+ * Storage naming convention:
+ *   {schema}.{table}              - Data store (row data)
+ *   {schema}.{table}_idx_{name}   - Index store (secondary indexes)
+ *   {schema}.{table}_stats        - Stats store (row count, etc.)
+ *   __catalog__                   - Catalog store (DDL metadata)
+ *
+ * Within each store, keys are minimal:
+ *   - Data store: just the encoded primary key
+ *   - Index store: encoded index columns + encoded primary key
+ *   - Stats store: single empty key (stats is the only value)
+ *   - Catalog store: {schema}.{table} as the key
  */
 import type { SqlValue } from '@quereus/quereus';
 import { type EncodeOptions } from './encoding.js';
-/** Key prefix bytes. */
-export declare const KEY_PREFIX: {
-    readonly DATA: Uint8Array<ArrayBuffer>;
-    readonly INDEX: Uint8Array<ArrayBuffer>;
-    readonly META: Uint8Array<ArrayBuffer>;
+/**
+ * Store name suffixes for different data types.
+ */
+export declare const STORE_SUFFIX: {
+    readonly INDEX: "_idx_";
+    readonly STATS: "_stats";
 };
+/** Reserved catalog store name. */
+export declare const CATALOG_STORE_NAME = "__catalog__";
+/** Reserved stats store name. */
+export declare const STATS_STORE_NAME = "__stats__";
 /**
- * Build a data row key.
- * Format: d:{schema}.{table}:{encoded_pk}
+ * Build the store name for a table's data.
+ * Format: {schema}.{table}
  */
-export declare function buildDataKey(schemaName: string, tableName: string, pkValues: SqlValue[], options?: EncodeOptions): Uint8Array;
+export declare function buildDataStoreName(schemaName: string, tableName: string): string;
 /**
- * Build a secondary index key.
- * Format: i:{schema}.{table}.{indexName}:{encoded_index_cols}:{encoded_pk}
+ * Build the store name for a secondary index.
+ * Format: {schema}.{table}_idx_{indexName}
  */
-export declare function buildIndexKey(schemaName: string, tableName: string, indexName: string, indexValues: SqlValue[], pkValues: SqlValue[], options?: EncodeOptions): Uint8Array;
+export declare function buildIndexStoreName(schemaName: string, tableName: string, indexName: string): string;
 /**
- * Build a metadata key.
- * Format: m:{type}:{schema}.{name}
+ * Build the store name for table statistics.
+ * @deprecated Stats are now stored in the unified __stats__ store. Use buildStatsKey instead.
+ * Format: {schema}.{table}_stats
+ */
+export declare function buildStatsStoreName(schemaName: string, tableName: string): string;
+/**
+ * Build a stats key for use in the unified __stats__ store.
+ * Format: {schema}.{table}
+ */
+export declare function buildStatsKey(schemaName: string, tableName: string): Uint8Array;
+/**
+ * Build a data row key (just the encoded primary key).
+ */
+export declare function buildDataKey(pkValues: SqlValue[], options?: EncodeOptions): Uint8Array;
+/**
+ * Build a secondary index key.
+ * Format: {encoded_index_cols}{encoded_pk}
+ *
+ * The index columns come first for range scans, followed by PK for uniqueness.
  */
-export declare function buildMetaKey(metaType: 'ddl' | 'stats' | 'index', schemaName: string, objectName: string, subName?: string): Uint8Array;
+export declare function buildIndexKey(indexValues: SqlValue[], pkValues: SqlValue[], options?: EncodeOptions): Uint8Array;
 /**
- * Build a table prefix for range scans.
- * Format: {prefix}:{schema}.{table}
+ * Build a catalog key for DDL storage.
+ * Format: {schema}.{table}
  */
-export declare function buildTablePrefix(prefix: 'd' | 'i' | 'm', schemaName: string, tableName: string): Uint8Array;
+export declare function buildCatalogKey(schemaName: string, tableName: string): Uint8Array;
 /**
- * Build range bounds for scanning all rows of a table.
+ * Build range bounds for scanning all rows in a data store.
+ * Since keys are just encoded PKs, we scan the entire store.
  */
-export declare function buildTableScanBounds(schemaName: string, tableName: string): {
+export declare function buildFullScanBounds(): {
     gte: Uint8Array;
     lt: Uint8Array;
 };
 /**
- * Build range bounds for scanning an index.
+ * Build range bounds for scanning an index with a prefix.
  */
-export declare function buildIndexScanBounds(schemaName: string, tableName: string, indexName: string, prefixValues?: SqlValue[], options?: EncodeOptions): {
+export declare function buildIndexPrefixBounds(prefixValues: SqlValue[], options?: EncodeOptions): {
     gte: Uint8Array;
     lt: Uint8Array;
 };
 /**
- * Build range bounds for scanning all metadata of a type.
+ * Build range bounds for scanning catalog entries.
+ * Optionally filter by schema prefix.
  */
-export declare function buildMetaScanBounds(metaType: 'ddl' | 'stats' | 'index', schemaName?: string): {
+export declare function buildCatalogScanBounds(schemaName?: string): {
+    gte: Uint8Array;
+    lt: Uint8Array;
+};
+/** @deprecated Use buildDataStoreName instead */
+export declare const KEY_PREFIX: {
+    readonly DATA: Uint8Array<ArrayBuffer>;
+    readonly INDEX: Uint8Array<ArrayBuffer>;
+    readonly META: Uint8Array<ArrayBuffer>;
+};
+/** @deprecated Use buildDataKey instead */
+export declare function buildTablePrefix(_prefix: 'd' | 'i' | 'm', schemaName: string, tableName: string): Uint8Array;
+/** @deprecated Use buildFullScanBounds instead */
+export declare function buildTableScanBounds(_schemaName: string, _tableName: string): {
+    gte: Uint8Array;
+    lt: Uint8Array;
+};
+/** @deprecated Use buildIndexPrefixBounds instead */
+export declare function buildIndexScanBounds(_schemaName: string, _tableName: string, _indexName: string, prefixValues?: SqlValue[], options?: EncodeOptions): {
+    gte: Uint8Array;
+    lt: Uint8Array;
+};
+/** @deprecated Use buildCatalogKey instead */
+export declare function buildMetaKey(_metaType: 'ddl' | 'stats' | 'index', schemaName: string, objectName: string, _subName?: string): Uint8Array;
+/** @deprecated Use buildCatalogScanBounds instead */
+export declare function buildMetaScanBounds(_metaType: 'ddl' | 'stats' | 'index', schemaName?: string): {
     gte: Uint8Array;
     lt: Uint8Array;
 };

package/dist/src/common/key-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"key-builder.d.ts","sourceRoot":"","sources":["../../../src/common/key-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAIvE,wBAAwB;AACxB,eAAO,MAAM,UAAU;;;;CAIb,CAAC;AAKX;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,EAAE,EACpB,OAAO,CAAC,EAAE,aAAa,GACtB,UAAU,CAKZ;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,QAAQ,EAAE,EACvB,QAAQ,EAAE,QAAQ,EAAE,EACpB,OAAO,CAAC,EAAE,aAAa,GACtB,UAAU,CAMZ;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,KAAK,GAAG,OAAO,GAAG,OAAO,EACnC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,GACf,UAAU,CAMZ;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,EACvB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,UAAU,CAEZ;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB;IAAE,GAAG,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,UAAU,CAAA;CAAE,CAMrC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,QAAQ,EAAE,EACzB,OAAO,CAAC,EAAE,aAAa,GACtB;IAAE,GAAG,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,UAAU,CAAA;CAAE,CAiBrC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,KAAK,GAAG,OAAO,GAAG,OAAO,EACnC,UAAU,CAAC,EAAE,MAAM,GAClB;IAAE,GAAG,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,UAAU,CAAA;CAAE,CASrC"}
+{"version":3,"file":"key-builder.d.ts","sourceRoot":"","sources":["../../../src/common/key-builder.ts"],"names":[],"mappings":"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"}

package/dist/src/common/key-builder.js

@@ -1,98 +1,122 @@
 /**
  * Key builder utilities for constructing storage keys.
  *
- * Key prefixes:
- *   d: - Data rows
- *   i: - Secondary indexes
- *   m: - Metadata (DDL, stats)
+ * Storage naming convention:
+ *   {schema}.{table}              - Data store (row data)
+ *   {schema}.{table}_idx_{name}   - Index store (secondary indexes)
+ *   {schema}.{table}_stats        - Stats store (row count, etc.)
+ *   __catalog__                   - Catalog store (DDL metadata)
+ *
+ * Within each store, keys are minimal:
+ *   - Data store: just the encoded primary key
+ *   - Index store: encoded index columns + encoded primary key
+ *   - Stats store: single empty key (stats is the only value)
+ *   - Catalog store: {schema}.{table} as the key
  */
 import { encodeCompositeKey } from './encoding.js';
 const encoder = new TextEncoder();
-/** Key prefix bytes. */
-export const KEY_PREFIX = {
-    DATA: encoder.encode('d:'),
-    INDEX: encoder.encode('i:'),
-    META: encoder.encode('m:'),
+/**
+ * Store name suffixes for different data types.
+ */
+export const STORE_SUFFIX = {
+    INDEX: '_idx_',
+    STATS: '_stats',
 };
-/** Separator between key components. */
-const SEPARATOR = encoder.encode(':');
+/** Reserved catalog store name. */
+export const CATALOG_STORE_NAME = '__catalog__';
+/** Reserved stats store name. */
+export const STATS_STORE_NAME = '__stats__';
 /**
- * Build a data row key.
- * Format: d:{schema}.{table}:{encoded_pk}
+ * Build the store name for a table's data.
+ * Format: {schema}.{table}
  */
-export function buildDataKey(schemaName, tableName, pkValues, options) {
-    const tablePrefix = buildTablePrefix('d', schemaName, tableName);
-    const pkEncoded = encodeCompositeKey(pkValues, options);
-    return concatBytes(tablePrefix, SEPARATOR, pkEncoded);
+export function buildDataStoreName(schemaName, tableName) {
+    return `${schemaName}.${tableName}`.toLowerCase();
 }
 /**
- * Build a secondary index key.
- * Format: i:{schema}.{table}.{indexName}:{encoded_index_cols}:{encoded_pk}
+ * Build the store name for a secondary index.
+ * Format: {schema}.{table}_idx_{indexName}
  */
-export function buildIndexKey(schemaName, tableName, indexName, indexValues, pkValues, options) {
-    const prefix = encoder.encode(`i:${schemaName}.${tableName}.${indexName}:`);
-    const indexEncoded = encodeCompositeKey(indexValues, options);
-    const pkEncoded = encodeCompositeKey(pkValues, options);
-    return concatBytes(prefix, indexEncoded, SEPARATOR, pkEncoded);
+export function buildIndexStoreName(schemaName, tableName, indexName) {
+    return `${schemaName}.${tableName}_idx_${indexName}`.toLowerCase();
 }
 /**
- * Build a metadata key.
- * Format: m:{type}:{schema}.{name}
+ * Build the store name for table statistics.
+ * @deprecated Stats are now stored in the unified __stats__ store. Use buildStatsKey instead.
+ * Format: {schema}.{table}_stats
  */
-export function buildMetaKey(metaType, schemaName, objectName, subName) {
-    let key = `m:${metaType}:${schemaName}.${objectName}`;
-    if (subName) {
-        key += `#${subName}`;
-    }
-    return encoder.encode(key);
+export function buildStatsStoreName(schemaName, tableName) {
+    return `${schemaName}.${tableName}_stats`.toLowerCase();
+}
+/**
+ * Build a stats key for use in the unified __stats__ store.
+ * Format: {schema}.{table}
+ */
+export function buildStatsKey(schemaName, tableName) {
+    return encoder.encode(`${schemaName}.${tableName}`.toLowerCase());
 }
 /**
- * Build a table prefix for range scans.
- * Format: {prefix}:{schema}.{table}
+ * Build a data row key (just the encoded primary key).
  */
-export function buildTablePrefix(prefix, schemaName, tableName) {
-    return encoder.encode(`${prefix}:${schemaName}.${tableName}`);
+export function buildDataKey(pkValues, options) {
+    return encodeCompositeKey(pkValues, options);
 }
 /**
- * Build range bounds for scanning all rows of a table.
+ * Build a secondary index key.
+ * Format: {encoded_index_cols}{encoded_pk}
+ *
+ * The index columns come first for range scans, followed by PK for uniqueness.
  */
-export function buildTableScanBounds(schemaName, tableName) {
-    const prefix = `d:${schemaName}.${tableName}:`;
+export function buildIndexKey(indexValues, pkValues, options) {
+    const indexEncoded = encodeCompositeKey(indexValues, options);
+    const pkEncoded = encodeCompositeKey(pkValues, options);
+    return concatBytes(indexEncoded, pkEncoded);
+}
+/**
+ * Build a catalog key for DDL storage.
+ * Format: {schema}.{table}
+ */
+export function buildCatalogKey(schemaName, tableName) {
+    return encoder.encode(`${schemaName}.${tableName}`.toLowerCase());
+}
+/**
+ * Build range bounds for scanning all rows in a data store.
+ * Since keys are just encoded PKs, we scan the entire store.
+ */
+export function buildFullScanBounds() {
     return {
-        gte: encoder.encode(prefix),
-        lt: incrementLastByte(encoder.encode(prefix)),
+        gte: new Uint8Array(0),
+        lt: new Uint8Array([0xff]), // All valid encoded keys are < 0xff
     };
 }
 /**
- * Build range bounds for scanning an index.
+ * Build range bounds for scanning an index with a prefix.
  */
-export function buildIndexScanBounds(schemaName, tableName, indexName, prefixValues, options) {
-    const prefix = `i:${schemaName}.${tableName}.${indexName}:`;
-    const prefixBytes = encoder.encode(prefix);
-    if (prefixValues && prefixValues.length > 0) {
-        const valueBytes = encodeCompositeKey(prefixValues, options);
-        const gte = concatBytes(prefixBytes, valueBytes);
-        return {
-            gte,
-            lt: incrementLastByte(gte),
-        };
+export function buildIndexPrefixBounds(prefixValues, options) {
+    if (prefixValues.length === 0) {
+        return buildFullScanBounds();
     }
+    const prefixEncoded = encodeCompositeKey(prefixValues, options);
     return {
-        gte: prefixBytes,
-        lt: incrementLastByte(prefixBytes),
+        gte: prefixEncoded,
+        lt: incrementLastByte(prefixEncoded),
     };
 }
 /**
- * Build range bounds for scanning all metadata of a type.
+ * Build range bounds for scanning catalog entries.
+ * Optionally filter by schema prefix.
  */
-export function buildMetaScanBounds(metaType, schemaName) {
-    let prefix = `m:${metaType}:`;
+export function buildCatalogScanBounds(schemaName) {
     if (schemaName) {
-        prefix += `${schemaName}.`;
+        const prefix = `${schemaName}.`.toLowerCase();
+        return {
+            gte: encoder.encode(prefix),
+            lt: incrementLastByte(encoder.encode(prefix)),
+        };
     }
     return {
-        gte: encoder.encode(prefix),
-        lt: incrementLastByte(encoder.encode(prefix)),
+        gte: new Uint8Array(0),
+        lt: new Uint8Array([0xff]),
     };
 }
 /**
@@ -127,4 +151,34 @@ function concatBytes(...arrays) {
     }
     return result;
 }
+// ============================================================================
+// Legacy exports for backwards compatibility during migration
+// These will be removed after all consumers are updated.
+// ============================================================================
+/** @deprecated Use buildDataStoreName instead */
+export const KEY_PREFIX = {
+    DATA: encoder.encode('d:'),
+    INDEX: encoder.encode('i:'),
+    META: encoder.encode('m:'),
+};
+/** @deprecated Use buildDataKey instead */
+export function buildTablePrefix(_prefix, schemaName, tableName) {
+    return encoder.encode(`${schemaName}.${tableName}`.toLowerCase());
+}
+/** @deprecated Use buildFullScanBounds instead */
+export function buildTableScanBounds(_schemaName, _tableName) {
+    return buildFullScanBounds();
+}
+/** @deprecated Use buildIndexPrefixBounds instead */
+export function buildIndexScanBounds(_schemaName, _tableName, _indexName, prefixValues, options) {
+    return buildIndexPrefixBounds(prefixValues || [], options);
+}
+/** @deprecated Use buildCatalogKey instead */
+export function buildMetaKey(_metaType, schemaName, objectName, _subName) {
+    return buildCatalogKey(schemaName, objectName);
+}
+/** @deprecated Use buildCatalogScanBounds instead */
+export function buildMetaScanBounds(_metaType, schemaName) {
+    return buildCatalogScanBounds(schemaName);
+}
 //# sourceMappingURL=key-builder.js.map

package/dist/src/common/key-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"key-builder.js","sourceRoot":"","sources":["../../../src/common/key-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"key-builder.js","sourceRoot":"","sources":["../../../src/common/key-builder.ts"],"names":[],"mappings":"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"}

package/dist/src/common/kv-store.d.ts

@@ -112,39 +112,78 @@ export interface KVStoreOptions {
  * This abstraction allows different storage backends (LevelDB, IndexedDB,
  * React Native AsyncStorage, etc.) to be used with the StoreModule.
  *
+ * Storage naming convention:
+ *   {schema}.{table}              - Data store (row data)
+ *   {schema}.{table}_idx_{name}   - Index store (secondary indexes)
+ *   {prefix}.__stats__            - Unified stats store (row counts for all tables)
+ *   __catalog__                   - Catalog store (DDL metadata)
+ *
  * Implementations should manage store lifecycle and caching.
  */
 export interface KVStoreProvider {
     /**
-     * Get or create a KVStore for a table.
+     * Get or create a KVStore for a table's row data.
+     * Store name: {schema}.{table}
      * @param schemaName - The schema name (e.g., 'main')
      * @param tableName - The table name
      * @param options - Additional options passed from CREATE TABLE
      * @returns The KVStore instance
      */
     getStore(schemaName: string, tableName: string, options?: Record<string, unknown>): Promise<KVStore>;
+    /**
+     * Get or create a KVStore for a secondary index.
+     * Store name: {schema}.{table}_idx_{indexName}
+     * @param schemaName - The schema name
+     * @param tableName - The table name
+     * @param indexName - The index name
+     * @returns The KVStore instance for the index
+     */
+    getIndexStore(schemaName: string, tableName: string, indexName: string): Promise<KVStore>;
+    /**
+     * Get or create the unified KVStore for table statistics.
+     * All table statistics are stored in a single __stats__ store, keyed by {schema}.{table}.
+     * Note: schemaName and tableName parameters are ignored (kept for API compatibility).
+     * @param schemaName - Unused (kept for API compatibility)
+     * @param tableName - Unused (kept for API compatibility)
+     * @returns The unified __stats__ KVStore instance
+     */
+    getStatsStore(schemaName: string, tableName: string): Promise<KVStore>;
     /**
      * Get or create a KVStore for catalog/DDL metadata.
-     * Some providers may use the same store as data, others may use a separate store.
+     * Store name: __catalog__
      * @returns The KVStore instance for catalog data
      */
     getCatalogStore(): Promise<KVStore>;
     /**
-     * Close a specific store.
+     * Close a specific table's data store.
      * @param schemaName - The schema name
      * @param tableName - The table name
      */
     closeStore(schemaName: string, tableName: string): Promise<void>;
+    /**
+     * Close a specific index store.
+     * @param schemaName - The schema name
+     * @param tableName - The table name
+     * @param indexName - The index name
+     */
+    closeIndexStore(schemaName: string, tableName: string, indexName: string): Promise<void>;
     /**
      * Close all stores managed by this provider.
      */
     closeAll(): Promise<void>;
     /**
-     * Optional: Called when a store is first accessed to perform any setup.
-     * @param store - The store that was just opened
+     * Delete an index store entirely (when dropping an index).
+     * @param schemaName - The schema name
+     * @param tableName - The table name
+     * @param indexName - The index name
+     */
+    deleteIndexStore?(schemaName: string, tableName: string, indexName: string): Promise<void>;
+    /**
+     * Delete all stores for a table (data, indexes, stats).
+     * Called when dropping a table.
      * @param schemaName - The schema name
      * @param tableName - The table name
      */
-    onStoreOpened?(store: KVStore, schemaName: string, tableName: string): void;
+    deleteTableStores?(schemaName: string, tableName: string): Promise<void>;
 }
 //# sourceMappingURL=kv-store.d.ts.map