@earth-app/collegedb 1.1.3 → 1.2.0

package/README.md

@@ -19,6 +19,7 @@ A TypeScript library for **true horizontal scaling** of SQLite-style databases p
 - [Provider Adapters](#provider-adapters)
 - [NuxtHub + Drizzle Recipes](#nuxthub--drizzle-recipes)
 - [Sandbox Benchmarks (Docker Compose)](#sandbox-benchmarks-docker-compose)
+- [In-Memory Providers for Testing & Development](#in-memory-providers-for-testing--development)
 - [Basic Usage](#basic-usage)
 - [Multi-Key Shard Mappings](#multi-key-shard-mappings)
 - [Drop-in Replacement for Existing Databases](#drop-in-replacement-for-existing-databases)
@@ -71,6 +72,7 @@ This allows you to:
 - Automatic query routing (primary key to shard mapping)
 - Provider adapters for Redis/Valkey/NuxtHub KV plus PostgreSQL/MySQL/SQLite SQL
 - Drizzle interop through existing SQL providers (`createPostgreSQLProvider`, `createMySQLProvider`, `createSQLiteProvider`)
+- Auto-allocated generated-id inserts via `insert()` and direct-shard inserts via `insertShard()` for AUTOINCREMENT / RETURNING workflows
 - Hyperdrive helpers for PostgreSQL and MySQL
 - Multiple allocation strategies: round-robin, random, hash, location-aware, and mixed read/write strategies
 - Durable Object shard coordination and shard statistics
@@ -193,18 +195,19 @@ CollegeDB includes a benchmark runner that executes each SQL+KV combination acro
 
 ### Scenario Catalog
 
-| Scenario Key      | Scenario                         | What Happens                                                                                        | Workload Per Run                                                       |
-| ----------------- | -------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| basic_crud        | Basic CRUD round-trip            | Insert, read, update, and delete a user via routed queries.                                         | 20 iterations; 4 routed SQL ops per iteration                          |
-| advanced_usage    | Advanced lookup workflow         | Writes user+post, adds lookup aliases, then validates join and alias-based lookup.                  | 15 iterations; ~5 routed SQL ops + KV lookup-key updates per iteration |
-| migration_mapping | Migration-style mapping creation | Inserts legacy records on a fixed shard, then builds shard mappings in batch and validates routing. | 10 iterations; 20 legacy records mapped per iteration                  |
-| bulk_crud         | Bulk CRUD pressure               | Performs bulk inserts, half updates, and full delete sweep, then validates shard-wide totals.       | 7 iterations; 160 inserts + 80 updates + 160 deletes per iteration     |
-| indexing          | Indexed query scan               | Creates an index on posts(user_id) and repeatedly queries the indexed path.                         | 15 iterations after warmup dataset build                               |
-| metadata_fetch    | Metadata inspection              | Reads table metadata/introspection rows from one shard.                                             | 14 iterations; 1 metadata query per iteration                          |
-| pragma_or_info    | PRAGMA / server info             | Runs provider-specific PRAGMA/info query to sample low-level metadata latency.                      | 14 iterations; 1 pragma/info query per iteration                       |
-| counting          | Cross-shard counting             | Counts users across all shards to measure fanout aggregation overhead.                              | 14 iterations; all-shard count aggregation per iteration               |
-| shard_fanout      | Shard fanout query               | Runs query fanout to all shards and aggregates shard-level responses.                               | 14 iterations; 1 all-shards query per iteration                        |
-| reassignment      | Shard reassignment flow          | Creates a record, reassigns it to another shard, and verifies routed reads still succeed.           | 10 iterations; insert + reassignment + verification per iteration      |
+| Scenario Key      | Scenario                         | What Happens                                                                                                                    | Workload Per Run                                                       |
+| ----------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| basic_crud        | Basic CRUD round-trip            | Insert, read, update, and delete a user via routed queries.                                                                     | 20 iterations; 4 routed SQL ops per iteration                          |
+| advanced_usage    | Advanced lookup workflow         | Writes user+post, adds lookup aliases, then validates join and alias-based lookup.                                              | 15 iterations; ~5 routed SQL ops + KV lookup-key updates per iteration |
+| migration_mapping | Migration-style mapping creation | Inserts legacy records on a fixed shard, then builds shard mappings in batch and validates routing.                             | 10 iterations; 20 legacy records mapped per iteration                  |
+| bulk_crud         | Bulk CRUD pressure               | Performs bulk inserts, half updates, and full delete sweep, then validates shard-wide totals.                                   | 7 iterations; 160 inserts + 80 updates + 160 deletes per iteration     |
+| auto_increment    | Auto-generated primary keys      | Inserts rows with generated ids on an automatically selected shard, captures the generated key, then validates routed readback. | 6 iterations; insert + generated-id readback per iteration             |
+| indexing          | Indexed query scan               | Creates an index on posts(user_id) and repeatedly queries the indexed path.                                                     | 15 iterations after warmup dataset build                               |
+| metadata_fetch    | Metadata inspection              | Reads table metadata/introspection rows from one shard.                                                                         | 14 iterations; 1 metadata query per iteration                          |
+| pragma_or_info    | PRAGMA / server info             | Runs provider-specific PRAGMA/info query to sample low-level metadata latency.                                                  | 14 iterations; 1 pragma/info query per iteration                       |
+| counting          | Cross-shard counting             | Counts users across all shards to measure fanout aggregation overhead.                                                          | 14 iterations; all-shard count aggregation per iteration               |
+| shard_fanout      | Shard fanout query               | Runs query fanout to all shards and aggregates shard-level responses.                                                           | 14 iterations; 1 all-shards query per iteration                        |
+| reassignment      | Shard reassignment flow          | Creates a record, reassigns it to another shard, and verifies routed reads still succeed.                                       | 10 iterations; insert + reassignment + verification per iteration      |
 
 ### Report Matrices
 
@@ -439,6 +442,7 @@ Benchmark coverage includes:
 - advanced lookup/routing workflows
 - migration-style mapping creation
 - bulk CRUD
+- auto-generated primary key inserts and readback
 - indexing queries
 - metadata fetch
 - pragma/info queries (provider-specific)
@@ -453,6 +457,264 @@ How to read benchmark rows:
 - `N/A` means the scenario was intentionally skipped in that environment.
 - Use the detailed section for full `avg`, `p50`, `p95`, `min`, `max`, and sample count (`n`).
 
+## In-Memory Providers for Testing & Development
+
+CollegeDB includes lightweight, zero-dependency in-memory mock implementations of the `KVStorage` and `SQLDatabase` interfaces. These are ideal for:
+
+- **Unit testing** without external dependencies
+- **Integration testing** with multiple shard combinations
+- **Local development** and rapid iteration
+- **Sandboxed playtesting** of routing logic
+
+The in-memory providers work in Cloudflare Workers, Node.js, and Deno environments.
+
+### Quick Start with In-Memory Providers
+
+```typescript
+import { createInMemoryKVProvider, createInMemorySQLProvider, initialize, run, first } from '@earth-app/collegedb';
+
+// Create fresh in-memory providers for each test
+const config = {
+	kv: createInMemoryKVProvider(),
+	shards: {
+		'shard-1': createInMemorySQLProvider(),
+		'shard-2': createInMemorySQLProvider(),
+		'shard-3': createInMemorySQLProvider()
+	},
+	strategy: 'hash'
+};
+
+initialize(config);
+
+// Use as normal - all operations happen in-memory
+await run('user-1', 'INSERT INTO users (id, name, email) VALUES (?, ?, ?)', ['user-1', 'Alice', 'alice@example.com']);
+
+const user = await first<{ id: string; name: string }>('user-1', 'SELECT id, name FROM users WHERE id = ?', ['user-1']);
+console.log(user); // { id: 'user-1', name: 'Alice' }
+```
+
+### Unit Testing Example
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createInMemoryKVProvider, createInMemorySQLProvider, initialize, resetConfig, run, first } from '@earth-app/collegedb';
+
+describe('User Shard Routing', () => {
+	beforeEach(() => {
+		// Fresh providers for each test
+		initialize({
+			kv: createInMemoryKVProvider(),
+			shards: {
+				'shard-1': createInMemorySQLProvider(),
+				'shard-2': createInMemorySQLProvider(),
+				'shard-3': createInMemorySQLProvider()
+			},
+			strategy: 'hash'
+		});
+	});
+
+	afterEach(() => {
+		resetConfig();
+	});
+
+	it('should insert and retrieve a user', async () => {
+		await run('user-1', 'INSERT INTO users (id, name, email) VALUES (?, ?, ?)', ['user-1', 'Alice', 'alice@example.com']);
+
+		const user = await first<{ name: string }>('user-1', 'SELECT name FROM users WHERE id = ?', ['user-1']);
+
+		expect(user?.name).toBe('Alice');
+	});
+
+	it('should distribute users across shards', async () => {
+		// Insert multiple users
+		for (let i = 0; i < 9; i++) {
+			await run(`user-${i}`, 'INSERT INTO users (id, name) VALUES (?, ?)', [`user-${i}`, `User ${i}`]);
+		}
+
+		// Verify each can be retrieved
+		for (let i = 0; i < 9; i++) {
+			const user = await first(`user-${i}`, 'SELECT id FROM users WHERE id = ?', [`user-${i}`]);
+			expect(user).toBeDefined();
+		}
+	});
+
+	it('should handle updates correctly', async () => {
+		await run('user-1', 'INSERT INTO users (id, name) VALUES (?, ?)', ['user-1', 'Alice']);
+
+		await run('user-1', 'UPDATE users SET name = ? WHERE id = ?', ['Alice Updated', 'user-1']);
+
+		const user = await first<{ name: string }>('user-1', 'SELECT name FROM users WHERE id = ?', ['user-1']);
+
+		expect(user?.name).toBe('Alice Updated');
+	});
+});
+```
+
+### Integration Testing with Multiple Providers
+
+Test different combinations without Docker or external services:
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+	createInMemoryKVProvider,
+	createInMemorySQLProvider,
+	initialize,
+	resetConfig,
+	run,
+	first,
+	KVShardMapper
+} from '@earth-app/collegedb';
+
+describe('Multi-Provider Integration', () => {
+	it('should work with different KV/SQL combinations', async () => {
+		const combinations = [{ kvName: 'memory', sqlName: 'memory' }];
+
+		for (const combo of combinations) {
+			resetConfig();
+
+			initialize({
+				kv: createInMemoryKVProvider(),
+				shards: {
+					'shard-1': createInMemorySQLProvider(),
+					'shard-2': createInMemorySQLProvider()
+				},
+				strategy: 'hash'
+			});
+
+			// Test basic operations
+			await run('key-1', 'INSERT INTO data (id, value) VALUES (?, ?)', ['key-1', 'test-value']);
+
+			const row = await first('key-1', 'SELECT value FROM data WHERE id = ?', ['key-1']);
+
+			expect(row?.value).toBe('test-value');
+		}
+	});
+
+	it('should support lookup key mapping', async () => {
+		initialize({
+			kv: createInMemoryKVProvider(),
+			shards: { 'shard-1': createInMemorySQLProvider() },
+			strategy: 'hash'
+		});
+
+		const mapper = new KVShardMapper(createInMemoryKVProvider());
+
+		// Add lookup keys
+		await mapper.addLookupKeys('user-123', ['email:alice@example.com', 'username:alice']);
+
+		// Retrieve via lookup key
+		const mapping = await mapper.getShardMapping('email:alice@example.com');
+		expect(mapping?.shard).toBeDefined();
+	});
+});
+```
+
+### Performance Testing with In-Memory Providers
+
+Run quick performance tests locally without external dependencies:
+
+```typescript
+import { createInMemoryKVProvider, createInMemorySQLProvider, initialize, run } from '@earth-app/collegedb';
+
+async function benchmarkInserts(iterations: number): Promise<number> {
+	initialize({
+		kv: createInMemoryKVProvider(),
+		shards: {
+			'shard-1': createInMemorySQLProvider(),
+			'shard-2': createInMemorySQLProvider(),
+			'shard-3': createInMemorySQLProvider()
+		},
+		strategy: 'hash'
+	});
+
+	const startTime = performance.now();
+
+	for (let i = 0; i < iterations; i++) {
+		const id = `perf-user-${i}`;
+		await run(id, 'INSERT INTO users (id, name) VALUES (?, ?)', [id, `User ${i}`]);
+	}
+
+	return performance.now() - startTime;
+}
+
+const duration = await benchmarkInserts(1000);
+console.log(`1000 inserts: ${duration.toFixed(2)}ms (${((1000 / duration) * 1000).toFixed(0)} ops/sec)`);
+```
+
+### Running the Memory Provider Sandbox
+
+CollegeDB includes a ready-made sandbox example demonstrating multiple scenarios:
+
+```bash
+bun run test:memory
+```
+
+This runs comprehensive benchmarks including:
+
+- Basic CRUD operations
+- Multi-shard data distribution
+- KV storage operations
+- Round-robin strategy testing
+- JOIN query performance
+
+### Supported Operations
+
+Both in-memory providers support the complete CollegeDB API:
+
+**SQLDatabase features:**
+
+- CREATE TABLE / DROP TABLE
+- INSERT / UPDATE / DELETE
+- SELECT with WHERE clauses
+- COUNT(\*) queries
+- JOIN queries
+- PRAGMA queries (basic support)
+
+**KVStorage features:**
+
+- `get()` / `put()` / `delete()`
+- `list()` with prefix filtering and cursor-based pagination
+- TTL/expiration support
+
+### Limitations
+
+The in-memory providers are intentionally simple to avoid dependencies:
+
+- **SQL Parser**: Basic pattern matching instead of full SQL parsing; works well for standard CollegeDB patterns but may not handle complex SQL edge cases
+- **Joins**: Supported at application level; cross-shard joins work via multiple routed queries
+- **Transactions**: Not supported; operations are atomic per-statement
+- **Indexes**: Created but not actually used for query optimization
+- **Schema**: Inferred from CREATE TABLE statements; dynamic column detection based on binding order
+
+For production use, migrate to appropriate providers (D1, Redis, PostgreSQL, etc.). For testing/development, these limitations are intentional to keep the implementation lightweight and zero-dependency.
+
+### Migrating from In-Memory to Production Providers
+
+When ready to migrate from testing to production:
+
+```typescript
+// Before (testing)
+import { createInMemoryKVProvider, createInMemorySQLProvider } from '@earth-app/collegedb';
+
+const config = {
+	kv: createInMemoryKVProvider(),
+	shards: { 'shard-1': createInMemorySQLProvider() }
+};
+
+// After (production)
+import { createRedisKVProvider, createPostgreSQLProvider } from '@earth-app/collegedb';
+
+const config = {
+	kv: createRedisKVProvider(redisClient),
+	shards: { 'shard-1': createPostgreSQLProvider(pgPool) }
+};
+
+// Rest of configuration stays the same!
+```
+
+The API remains identical - only the provider initialization changes.
+
 ## Basic Usage
 
 ```typescript
@@ -572,6 +834,67 @@ This approach provides:
 - **Optimal read performance**: Queries use `hash` strategy for consistent, high-performance routing
 - **Flexibility**: Each operation type can use the most appropriate routing strategy
 
+### Auto-Generated Primary Keys
+
+When your table assigns the primary key during insert, use `insert()` for the automatic shard-allocation path or `insertShard()` when you already know the target shard. Both helpers capture the generated id from provider metadata or `RETURNING` rows, then store the generated-id mapping so the normal routed `first()` / `all()` helpers can read the row back.
+
+```typescript
+import { first, insert, insertShard } from '@earth-app/collegedb';
+
+// SQLite / D1
+await createSchema(
+	env['db-east'],
+	`
+	CREATE TABLE IF NOT EXISTS auto_users (
+		id INTEGER PRIMARY KEY AUTOINCREMENT,
+		name TEXT NOT NULL,
+		email TEXT UNIQUE,
+		created_at INTEGER
+	)
+`
+);
+
+const created = await insert('INSERT INTO auto_users (name, email, created_at) VALUES (?, ?, ?)', ['Ada', 'ada@example.com', Date.now()]);
+
+const row = await first(String(created.generatedId), 'SELECT * FROM auto_users WHERE id = ?', [created.generatedId]);
+```
+
+```typescript
+// Direct shard insert when you want to pin the write to a specific shard
+const directCreated = await insertShard('db-east', 'INSERT INTO auto_users (name, email, created_at) VALUES (?, ?, ?)', [
+	'Ada',
+	'ada@example.com',
+	Date.now()
+]);
+
+console.log(directCreated.generatedId);
+```
+
+```typescript
+// PostgreSQL / MySQL 8.0.19+ RETURNING path
+await createSchema(
+	env['db-east'],
+	`
+	CREATE TABLE IF NOT EXISTS auto_users (
+		id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+		name VARCHAR(255) NOT NULL,
+		email VARCHAR(255) UNIQUE,
+		created_at BIGINT
+	)
+`
+);
+
+const created = await insert('INSERT INTO auto_users (name, email, created_at) VALUES (?, ?, ?) RETURNING id', [
+	'Ada',
+	'ada@example.com',
+	Date.now()
+]);
+
+const row = await first(String(created.generatedId), 'SELECT * FROM auto_users WHERE id = ?', [created.generatedId]);
+```
+
+If your SQL dialect uses `RETURNING`, include it in the insert statement. The helper will use the returned row instead of provider metadata when present.
+
 ## Multi-Key Shard Mappings
 
 CollegeDB supports **multiple lookup keys** for the same record, allowing you to query by username, email, ID, or any unique identifier. Keys are automatically hashed with SHA-256 for security and privacy.
@@ -1022,42 +1345,44 @@ await first('user-123', 'SELECT * FROM users WHERE email = ?', [email]);
 
 ## API Reference
 
-| Function                                          | Description                                                    | Parameters                                                         |
-| ------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------ |
-| `collegedb(config, callback)`                     | Initialize CollegeDB, then run a callback                      | `CollegeDBConfig, () => T`                                         |
-| `initialize(config)`                              | Initialize CollegeDB with configuration                        | `CollegeDBConfig`                                                  |
-| `createSchema(db, schema)`                        | Create schema on a shard database                              | `SQLDatabase, string`                                              |
-| `prepare(key, sql)`                               | Prepare a SQL statement for execution                          | `string, string`                                                   |
-| `run(key, sql, bindings)`                         | Execute a SQL query with primary key routing                   | `string, string, any[]`                                            |
-| `first(key, sql, bindings)`                       | Execute a SQL query and return first result                    | `string, string, any[]`                                            |
-| `all(key, sql, bindings)`                         | Execute a SQL query and return all results                     | `string, string, any[]`                                            |
-| `index(key, table, columns, options)`             | Create an index on routed shard                                | `string, string, string or index-column array, CreateIndexOptions` |
-| `indexShard(shard, table, columns, options)`      | Create an index on one shard                                   | `string, string, string or index-column array, CreateIndexOptions` |
-| `indexAllShards(table, columns, options)`         | Create an index on all shards                                  | `string, string or index-column array, CreateIndexOptions`         |
-| `firstByLookupKey(key, sql, bindings, batchSize)` | Resolve secondary-key mapping, fallback to fanout              | `string, string, any[], number`                                    |
-| `allByLookupKey(key, sql, bindings, batchSize)`   | Resolve secondary-key mapping, fallback to fanout              | `string, string, any[], number`                                    |
-| `runShard(shard, sql, bindings)`                  | Execute a query directly on a specific shard                   | `string, string, any[]`                                            |
-| `allShard(shard, sql, bindings)`                  | Execute a query on specific shard, return all results          | `string, string, any[]`                                            |
-| `firstShard(shard, sql, bindings)`                | Execute a query on specific shard, return first result         | `string, string, any[]`                                            |
-| `explain(key, sql, bindings, options)`            | Inspect query plan on routed shard                             | `string, string, any[], ExplainOptions`                            |
-| `explainShard(shard, sql, bindings, options)`     | Inspect query plan on one shard                                | `string, string, any[], ExplainOptions`                            |
-| `explainAllShards(sql, bindings, options)`        | Inspect query plan on all shards                               | `string, any[], ExplainOptions`                                    |
-| `count(key, table)`                               | Count rows on routed shard                                     | `string, string`                                                   |
-| `countShard(shard, table)`                        | Count rows on a specific shard                                 | `string, string`                                                   |
-| `countAllShards(table, batchSize)`                | Count rows per shard and global total                          | `string, number`                                                   |
-| `runAllShards(sql, bindings, batchSize)`          | Execute query on all shards                                    | `string, any[], number`                                            |
-| `allAllShards(sql, bindings, batchSize)`          | Execute query on all shards (SQL pagination applies per shard) | `string, any[], number`                                            |
-| `firstAllShards(sql, bindings, batchSize)`        | Execute query on all shards, return first row per shard        | `string, any[], number`                                            |
-| `allAllShardsGlobal(sql, bindings, options)`      | Execute query on all shards, then globally merge/sort/paginate | `string, any[], GlobalAllShardsOptions`                            |
-| `firstAllShardsGlobal(sql, bindings, options)`    | Return first row after global merge/sort/paginate              | `string, any[], GlobalAllShardsOptions`                            |
-| `reassignShard(key, newShard)`                    | Move primary key to different shard                            | `string, string`                                                   |
-| `listKnownShards()`                               | Get list of available shards                                   | `void`                                                             |
-| `getShardStats()`                                 | Get statistics for all shards                                  | `void`                                                             |
-| `getDatabaseSizeForKey(key)`                      | Get size of key-routed shard in bytes                          | `string`                                                           |
-| `getDatabaseSizeForShard(shard)`                  | Get size of a specific shard in bytes                          | `string`                                                           |
-| `getDatabaseSizesAllShards(batchSize)`            | Get per-shard size data                                        | `number`                                                           |
-| `getTotalDatabaseSize(batchSize)`                 | Get total size across all shards                               | `number`                                                           |
-| `flush()`                                         | Clear all shard mappings (development only)                    | `void`                                                             |
+| Function                                          | Description                                                            | Parameters                                                         |
+| ------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `collegedb(config, callback)`                     | Initialize CollegeDB, then run a callback                              | `CollegeDBConfig, () => T`                                         |
+| `initialize(config)`                              | Initialize CollegeDB with configuration                                | `CollegeDBConfig`                                                  |
+| `createSchema(db, schema)`                        | Create schema on a shard database                                      | `SQLDatabase, string`                                              |
+| `prepare(key, sql)`                               | Prepare a SQL statement for execution                                  | `string, string`                                                   |
+| `run(key, sql, bindings)`                         | Execute a SQL query with primary key routing                           | `string, string, any[]`                                            |
+| `insert(sql, bindings)`                           | Insert on an automatically selected shard and capture the generated id | `string, any[]`                                                    |
+| `insertShard(shard, sql, bindings)`               | Insert directly on a specific shard and capture the generated id       | `string, string, any[]`                                            |
+| `first(key, sql, bindings)`                       | Execute a SQL query and return first result                            | `string, string, any[]`                                            |
+| `all(key, sql, bindings)`                         | Execute a SQL query and return all results                             | `string, string, any[]`                                            |
+| `index(key, table, columns, options)`             | Create an index on routed shard                                        | `string, string, string or index-column array, CreateIndexOptions` |
+| `indexShard(shard, table, columns, options)`      | Create an index on one shard                                           | `string, string, string or index-column array, CreateIndexOptions` |
+| `indexAllShards(table, columns, options)`         | Create an index on all shards                                          | `string, string or index-column array, CreateIndexOptions`         |
+| `firstByLookupKey(key, sql, bindings, batchSize)` | Resolve secondary-key mapping, fallback to fanout                      | `string, string, any[], number`                                    |
+| `allByLookupKey(key, sql, bindings, batchSize)`   | Resolve secondary-key mapping, fallback to fanout                      | `string, string, any[], number`                                    |
+| `runShard(shard, sql, bindings)`                  | Execute a query directly on a specific shard                           | `string, string, any[]`                                            |
+| `allShard(shard, sql, bindings)`                  | Execute a query on specific shard, return all results                  | `string, string, any[]`                                            |
+| `firstShard(shard, sql, bindings)`                | Execute a query on specific shard, return first result                 | `string, string, any[]`                                            |
+| `explain(key, sql, bindings, options)`            | Inspect query plan on routed shard                                     | `string, string, any[], ExplainOptions`                            |
+| `explainShard(shard, sql, bindings, options)`     | Inspect query plan on one shard                                        | `string, string, any[], ExplainOptions`                            |
+| `explainAllShards(sql, bindings, options)`        | Inspect query plan on all shards                                       | `string, any[], ExplainOptions`                                    |
+| `count(key, table)`                               | Count rows on routed shard                                             | `string, string`                                                   |
+| `countShard(shard, table)`                        | Count rows on a specific shard                                         | `string, string`                                                   |
+| `countAllShards(table, batchSize)`                | Count rows per shard and global total                                  | `string, number`                                                   |
+| `runAllShards(sql, bindings, batchSize)`          | Execute query on all shards                                            | `string, any[], number`                                            |
+| `allAllShards(sql, bindings, batchSize)`          | Execute query on all shards (SQL pagination applies per shard)         | `string, any[], number`                                            |
+| `firstAllShards(sql, bindings, batchSize)`        | Execute query on all shards, return first row per shard                | `string, any[], number`                                            |
+| `allAllShardsGlobal(sql, bindings, options)`      | Execute query on all shards, then globally merge/sort/paginate         | `string, any[], GlobalAllShardsOptions`                            |
+| `firstAllShardsGlobal(sql, bindings, options)`    | Return first row after global merge/sort/paginate                      | `string, any[], GlobalAllShardsOptions`                            |
+| `reassignShard(key, newShard)`                    | Move primary key to different shard                                    | `string, string`                                                   |
+| `listKnownShards()`                               | Get list of available shards                                           | `void`                                                             |
+| `getShardStats()`                                 | Get statistics for all shards                                          | `void`                                                             |
+| `getDatabaseSizeForKey(key)`                      | Get size of key-routed shard in bytes                                  | `string`                                                           |
+| `getDatabaseSizeForShard(shard)`                  | Get size of a specific shard in bytes                                  | `string`                                                           |
+| `getDatabaseSizesAllShards(batchSize)`            | Get per-shard size data                                                | `number`                                                           |
+| `getTotalDatabaseSize(batchSize)`                 | Get total size across all shards                                       | `number`                                                           |
+| `flush()`                                         | Clear all shard mappings (development only)                            | `void`                                                             |
 
 ### Provider Adapter Functions
 

package/dist/index.d.ts

@@ -8,12 +8,13 @@
  * @author Gregory Mitchell
  * @license MIT
  */
-export { all, allAllShards, allAllShardsGlobal, allByLookupKey, allShard, collegedb, count, countAllShards, countShard, createSchema, explain, explainAllShards, explainShard, first, firstAllShards, firstAllShardsGlobal, firstByLookupKey, firstShard, flush, getClosestRegionFromIP, getDatabaseSizeForKey, getDatabaseSizeForShard, getDatabaseSizesAllShards, getShardStats, getTotalDatabaseSize, index, indexAllShards, indexShard, initialize, initializeAsync, listKnownShards, prepare, reassignShard, resetConfig, run, runAllShards, runShard } from './router';
-export type { CreateIndexOptions, ExplainOptions, GlobalAllShardsOptions, IndexColumnDefinition, ShardSizeResult, ShardTableCount } from './router';
+export { all, allAllShards, allAllShardsGlobal, allByLookupKey, allShard, collegedb, count, countAllShards, countShard, createSchema, explain, explainAllShards, explainShard, first, firstAllShards, firstAllShardsGlobal, firstByLookupKey, firstShard, flush, getClosestRegionFromIP, getDatabaseSizeForKey, getDatabaseSizeForShard, getDatabaseSizesAllShards, getShardStats, getTotalDatabaseSize, index, indexAllShards, indexShard, initialize, initializeAsync, insert, insertShard, listKnownShards, prepare, reassignShard, resetConfig, run, runAllShards, runShard } from './router';
+export type { CreateIndexOptions, ExplainOptions, GlobalAllShardsOptions, IndexColumnDefinition, InsertResult, ShardSizeResult, ShardTableCount } from './router';
 export { ShardCoordinator } from './durable';
 export { CollegeDBError } from './errors';
 export { KVShardMapper } from './kvmap';
 export { createDrizzleSQLProvider, createHyperdriveMySQLProvider, createHyperdrivePostgresProvider, createMySQLProvider, createNuxtHubKVProvider, createPostgreSQLProvider, createRedisKVProvider, createSQLiteProvider, createValkeyKVProvider, isKVStorage, isSQLDatabase, type DrizzleClientLike, type DrizzleSqlChunkLike, type DrizzleSqlTagLike, type HyperdriveBindingLike, type HyperdriveMySQLClientFactory, type HyperdrivePostgresClientFactory, type MySQLClientLike, type NuxtHubKVLike, type PostgresClientLike, type RedisLikeClient, type SQLiteClientLike } from './providers';
+export { InMemoryKVStorage, InMemorySQLDatabase, createInMemoryKVProvider, createInMemorySQLProvider } from './providers-memory';
 export { autoDetectAndMigrate, checkMigrationNeeded, clearMigrationCache, clearShardMigrationCache, createMappingsForExistingKeys, createSchemaAcrossShards, discoverExistingPrimaryKeys, discoverExistingRecordsWithColumns, dropSchema, integrateExistingDatabase, listTables, migrateRecord, schemaExists, validateTableForSharding, type IntegrationOptions, type IntegrationResult, type ValidationResult } from './migrations';
 export type { CollegeDBConfig, D1Region, Env, KVListResult, KVStorage, MixedShardingStrategy, OperationType, PreparedStatement, QueryResult, QueryResultMeta, SQLDatabase, ShardCoordinatorState, ShardLocation, ShardMapping, ShardStats, ShardingStrategy } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EACN,GAAG,EACH,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,SAAS,EACT,KAAK,EACL,cAAc,EACd,UAAU,EACV,YAAY,EACZ,OAAO,EACP,gBAAgB,EAChB,YAAY,EACZ,KAAK,EACL,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,EACV,KAAK,EACL,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,EACzB,aAAa,EACb,oBAAoB,EACpB,KAAK,EACL,cAAc,EACd,UAAU,EACV,UAAU,EACV,eAAe,EACf,eAAe,EACf,OAAO,EACP,aAAa,EACb,WAAW,EACX,GAAG,EACH,YAAY,EACZ,QAAQ,EACR,MAAM,UAAU,CAAC;AAElB,YAAY,EACX,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC,OAAO,EACN,wBAAwB,EACxB,6BAA6B,EAC7B,gCAAgC,EAChC,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,EACX,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,4BAA4B,EACjC,KAAK,+BAA+B,EACpC,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACN,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,6BAA6B,EAC7B,wBAAwB,EACxB,2BAA2B,EAC3B,kCAAkC,EAClC,UAAU,EACV,yBAAyB,EACzB,UAAU,EACV,aAAa,EACb,YAAY,EACZ,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,MAAM,cAAc,CAAC;AAGtB,YAAY,EACX,eAAe,EACf,QAAQ,EACR,GAAG,EACH,YAAY,EACZ,SAAS,EACT,qBAAqB,EACrB,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,WAAW,EACX,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EACN,GAAG,EACH,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,SAAS,EACT,KAAK,EACL,cAAc,EACd,UAAU,EACV,YAAY,EACZ,OAAO,EACP,gBAAgB,EAChB,YAAY,EACZ,KAAK,EACL,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,EACV,KAAK,EACL,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,EACzB,aAAa,EACb,oBAAoB,EACpB,KAAK,EACL,cAAc,EACd,UAAU,EACV,UAAU,EACV,eAAe,EACf,MAAM,EACN,WAAW,EACX,eAAe,EACf,OAAO,EACP,aAAa,EACb,WAAW,EACX,GAAG,EACH,YAAY,EACZ,QAAQ,EACR,MAAM,UAAU,CAAC;AAElB,YAAY,EACX,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,YAAY,EACZ,eAAe,EACf,eAAe,EACf,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC,OAAO,EACN,wBAAwB,EACxB,6BAA6B,EAC7B,gCAAgC,EAChC,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,EACX,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,4BAA4B,EACjC,KAAK,+BAA+B,EACpC,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAGjI,OAAO,EACN,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,6BAA6B,EAC7B,wBAAwB,EACxB,2BAA2B,EAC3B,kCAAkC,EAClC,UAAU,EACV,yBAAyB,EACzB,UAAU,EACV,aAAa,EACb,YAAY,EACZ,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,MAAM,cAAc,CAAC;AAGtB,YAAY,EACX,eAAe,EACf,QAAQ,EACR,GAAG,EACH,YAAY,EACZ,SAAS,EACT,qBAAqB,EACrB,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,WAAW,EACX,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,MAAM,SAAS,CAAC"}