feat: reorganize query functions, update testing

Author: gmitch215

README.md

@@ -40,7 +40,7 @@ npm install collegedb
 ## Basic Usage
 
 ```typescript
-import { initialize, createSchema, insert, selectByPrimaryKey } from 'collegedb';
+import { initialize, createSchema, run, first } from 'collegedb';
 
 // Initialize with your Cloudflare bindings (existing databases work automatically!)
 initialize({
@@ -57,17 +57,17 @@ initialize({
 await createSchema(env['db-new-shard']);
 
 // Insert data (automatically routed to appropriate shard)
-await insert('user-123', 'INSERT INTO users (id, name, email) VALUES (?, ?, ?)', ['user-123', 'Alice Johnson', 'alice@example.com']);
+await run('user-123', 'INSERT INTO users (id, name, email) VALUES (?, ?, ?)', ['user-123', 'Alice Johnson', 'alice@example.com']);
 
 // Query data (automatically routed to correct shard, works with existing data!)
-const result = await selectByPrimaryKey('existing-user-456', 'SELECT * FROM users WHERE id = ?', ['existing-user-456']);
+const result = await first<User>('existing-user-456', 'SELECT * FROM users WHERE id = ?', ['existing-user-456']);
 
-console.log(result.results[0]); // User data from existing database
+console.log(result); // User data from existing database
 ```
 
-## 🔄 Drop-in Replacement for Existing Databases
+## Drop-in Replacement for Existing Databases
 
-CollegeDB supports **seamless, automatic integration** with existing D1 databases that already contain data. Simply add your existing databases as shards in the configuration - CollegeDB will automatically detect existing data and create the necessary shard mappings **without requiring any manual migration steps**.
+CollegeDB supports **seamless, automatic integration** with existing D1 databases that already contain data. Simply add your existing databases as shards in the configuration. CollegeDB will automatically detect existing data and create the necessary shard mappings **without requiring any manual migration steps**.
 
 ### Requirements for Drop-in Replacement
 
@@ -77,7 +77,7 @@ CollegeDB supports **seamless, automatic integration** with existing D1 database
 4. **KV Namespace**: A Cloudflare KV namespace for storing shard mappings
 
 ```typescript
-import { initialize, selectByPrimaryKey, insert } from 'collegedb';
+import { initialize, first, run } from 'collegedb';
 
 // Add your existing databases as shards - that's it!
 initialize({
@@ -91,10 +91,10 @@ initialize({
 });
 
 // Existing data works immediately! 🎉
-const existingUser = await selectByPrimaryKey('user-from-old-db', 'SELECT * FROM users WHERE id = ?', ['user-from-old-db']);
+const existingUser = await first('user-from-old-db', 'SELECT * FROM users WHERE id = ?', ['user-from-old-db']);
 
 // New data gets distributed automatically
-await insert('new-user-123', 'INSERT INTO users (id, name, email) VALUES (?, ?, ?)', ['new-user-123', 'New User', 'new@example.com']);
+await run('new-user-123', 'INSERT INTO users (id, name, email) VALUES (?, ?, ?)', ['new-user-123', 'New User', 'new@example.com']);
 ```
 
 **That's it!** No migration scripts, no manual mapping creation, no downtime. Your existing data is immediately accessible through CollegeDB's sharding system.
@@ -169,7 +169,7 @@ if (result.success) {
 After integration, initialize CollegeDB with your existing databases as shards:
 
 ```typescript
-import { initialize } from 'collegedb';
+import { initialize, first } from 'collegedb';
 
 // Include existing databases as shards
 initialize({
@@ -184,15 +184,15 @@ initialize({
 });
 
 // Existing data is now automatically routed!
-const user = await selectByPrimaryKey('existing-user-123', 'SELECT * FROM users WHERE id = ?', ['existing-user-123']);
+const user = await first('existing-user-123', 'SELECT * FROM users WHERE id = ?', ['existing-user-123']);
 ```
 
 ### Complete Drop-in Example
 
 The simplest possible integration - just add your existing databases:
 
 ```typescript
-import { initialize, selectByPrimaryKey, insert } from 'collegedb';
+import { initialize, first, run } from 'collegedb';
 
 export default {
 	async fetch(request: Request, env: Env): Promise<Response> {
@@ -208,10 +208,11 @@ export default {
 		});
 
 		// Step 2: Use existing data immediately - no migration needed!
-		const existingUser = await selectByPrimaryKey('user-from-old-db', 'SELECT * FROM users WHERE id = ?', ['user-from-old-db']);
+		// Supports typed queries, inserts, updates, deletes, etc.
+		const existingUser = await first<User>('user-from-old-db', 'SELECT * FROM users WHERE id = ?', ['user-from-old-db']);
 
 		// Step 3: New data gets distributed automatically
-		await insert('new-user-123', 'INSERT INTO users (id, name, email) VALUES (?, ?, ?)', ['new-user-123', 'New User', 'new@example.com']);
+		await run('new-user-123', 'INSERT INTO users (id, name, email) VALUES (?, ?, ?)', ['new-user-123', 'New User', 'new@example.com']);
 
 		return new Response(
 			JSON.stringify({
@@ -313,17 +314,17 @@ for (const [table, pkColumn] of Object.entries(customIntegration)) {
 
 ## 📚 API Reference
 
-| Function                                 | Description                             | Parameters              |
-| ---------------------------------------- | --------------------------------------- | ----------------------- |
-| `initialize(config)`                     | Initialize CollegeDB with configuration | `CollegeDBConfig`       |
-| `createSchema(d1)`                       | Create database schema on a D1 instance | `D1Database`            |
-| `insert(key, sql, bindings)`             | Insert record using primary key routing | `string, string, any[]` |
-| `selectByPrimaryKey(key, sql, bindings)` | Select records by primary key           | `string, string, any[]` |
-| `updateByPrimaryKey(key, sql, bindings)` | Update records by primary key           | `string, string, any[]` |
-| `deleteByPrimaryKey(key, sql, bindings)` | Delete records by primary key           | `string, string, any[]` |
-| `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`                  |
+| Function                       | Description                                  | Parameters              |
+| ------------------------------ | -------------------------------------------- | ----------------------- |
+| `initialize(config)`           | Initialize CollegeDB with configuration      | `CollegeDBConfig`       |
+| `createSchema(d1)`             | Create database schema on a D1 instance      | `D1Database`            |
+| `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[]` |
+| `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`                  |
 
 ### Drop-in Replacement Functions
 

demos/worker-demo.ts

@@ -46,18 +46,7 @@
 
 import type { ExecutionContext } from '@cloudflare/workers-types';
 import { ShardCoordinator } from '../src/durable.js';
-import {
-	createSchemaAcrossShards,
-	deleteByPrimaryKey,
-	flush,
-	getShardStats,
-	initialize,
-	insert,
-	listKnownShards,
-	reassignShard,
-	selectByPrimaryKey,
-	updateByPrimaryKey
-} from '../src/index.js';
+import { createSchemaAcrossShards, first, flush, getShardStats, initialize, listKnownShards, reassignShard, run } from '../src/index.js';
 import type { Env } from '../src/types.js';
 
 // Demo schema for college database
@@ -359,7 +348,7 @@ async function handleCreateUser(request: Request): Promise<Response> {
 		);
 	}
 
-	await insert(userData.id, 'INSERT INTO users (id, name, email) VALUES (?, ?, ?)', [userData.id, userData.name, userData.email || null]);
+	await run(userData.id, 'INSERT INTO users (id, name, email) VALUES (?, ?, ?)', [userData.id, userData.name, userData.email || null]);
 
 	return new Response(
 		JSON.stringify({
@@ -387,9 +376,9 @@ async function handleGetUser(url: URL): Promise<Response> {
 		);
 	}
 
-	const result = await selectByPrimaryKey(userId, 'SELECT * FROM users WHERE id = ?', [userId]);
+	const result = await first(userId, 'SELECT * FROM users WHERE id = ?', [userId]);
 
-	if (result.results.length === 0) {
+	if (!result) {
 		return new Response(
 			JSON.stringify({
 				error: 'User not found'
@@ -403,7 +392,7 @@ async function handleGetUser(url: URL): Promise<Response> {
 
 	return new Response(
 		JSON.stringify({
-			user: result.results[0]
+			user: result
 		}),
 		{
 			headers: { 'Content-Type': 'application/json' }
@@ -427,9 +416,9 @@ async function handleUpdateUser(request: Request): Promise<Response> {
 	}
 
 	// Check if user exists first
-	const existing = await selectByPrimaryKey(userData.id, 'SELECT * FROM users WHERE id = ?', [userData.id]);
+	const existing = await first(userData.id, 'SELECT * FROM users WHERE id = ?', [userData.id]);
 
-	if (existing.results.length === 0) {
+	if (!existing) {
 		return new Response(
 			JSON.stringify({
 				error: 'User not found'
@@ -441,7 +430,7 @@ async function handleUpdateUser(request: Request): Promise<Response> {
 		);
 	}
 
-	await updateByPrimaryKey(userData.id, 'UPDATE users SET name = COALESCE(?, name), email = COALESCE(?, email) WHERE id = ?', [
+	await run(userData.id, 'UPDATE users SET name = COALESCE(?, name), email = COALESCE(?, email) WHERE id = ?', [
 		userData.name,
 		userData.email,
 		userData.id
@@ -472,7 +461,7 @@ async function handleDeleteUser(url: URL): Promise<Response> {
 		);
 	}
 
-	await deleteByPrimaryKey(userId, 'DELETE FROM users WHERE id = ?', [userId]);
+	await run(userId, 'DELETE FROM users WHERE id = ?', [userId]);
 
 	return new Response(
 		JSON.stringify({

examples/advanced-usage.ts

@@ -37,16 +37,7 @@
  * @since 1.0.0
  */
 
-import {
-	createSchema,
-	getShardStats,
-	initialize,
-	insert,
-	listKnownShards,
-	queryOnShard,
-	reassignShard,
-	selectByPrimaryKey
-} from '../src/index.js';
+import { allShard, createSchema, first, getShardStats, initialize, listKnownShards, reassignShard, run } from '../src/index.js';
 import type { CollegeDBConfig, Env } from '../src/types.js';
 
 // Example schema for advanced usage scenarios
@@ -185,7 +176,7 @@ async function handleLoadTest(): Promise<Response> {
 		for (let j = 0; j < batchSize && i + j < userCount; j++) {
 			const userId = `load-test-user-${i + j}`;
 			batch.push(
-				insert(userId, 'INSERT INTO users (id, name, email) VALUES (?, ?, ?)', [
+				run(userId, 'INSERT INTO users (id, name, email) VALUES (?, ?, ?)', [
 					userId,
 					`Load Test User ${i + j}`,
 					`user${i + j}@loadtest.com`
@@ -204,7 +195,7 @@ async function handleLoadTest(): Promise<Response> {
 	for (let i = 0; i < userCount; i += 5) {
 		// Sample every 5th user
 		const userId = `load-test-user-${i}`;
-		readPromises.push(selectByPrimaryKey(userId, 'SELECT * FROM users WHERE id = ?', [userId]));
+		readPromises.push(first(userId, 'SELECT * FROM users WHERE id = ?', [userId]));
 	}
 	await Promise.all(readPromises);
 	const readTime = Date.now() - readStartTime;
@@ -321,7 +312,7 @@ async function handleCrossShardQuery(config: CollegeDBConfig): Promise<Response>
 	// Query each shard directly for aggregate operations
 	for (const [shardName, _] of Object.entries(config.shards)) {
 		try {
-			const result = await queryOnShard(shardName, 'SELECT COUNT(*) as user_count FROM users', []);
+			const result = await allShard(shardName, 'SELECT COUNT(*) as user_count FROM users', []);
 			results.push({
 				shard: shardName,
 				userCount: result.results[0]?.user_count || 0
@@ -336,7 +327,7 @@ async function handleCrossShardQuery(config: CollegeDBConfig): Promise<Response>
 		}
 	}
 
-	const totalUsers = results.reduce((sum, r) => sum + (r.userCount || 0), 0);
+	const totalUsers = results.reduce((sum, r) => sum + (typeof r.userCount === 'number' ? r.userCount : 0), 0);
 
 	return new Response(
 		JSON.stringify({
@@ -357,10 +348,10 @@ async function handleErrorRecovery(): Promise<Response> {
 
 	// Test 1: Query non-existent user
 	try {
-		const result = await selectByPrimaryKey('non-existent-user', 'SELECT * FROM users WHERE id = ?', ['non-existent-user']);
+		const result = await first('non-existent-user', 'SELECT * FROM users WHERE id = ?', ['non-existent-user']);
 		tests.push({
 			test: 'Query non-existent user',
-			passed: result.results.length === 0,
+			passed: !result,
 			details: 'Should return empty results'
 		});
 	} catch (error) {
@@ -389,7 +380,7 @@ async function handleErrorRecovery(): Promise<Response> {
 
 	// Test 3: Malformed SQL
 	try {
-		await selectByPrimaryKey('test-user', 'INVALID SQL STATEMENT', []);
+		await run('test-user', 'INVALID SQL STATEMENT', []);
 		tests.push({
 			test: 'Malformed SQL',
 			passed: false,
@@ -432,7 +423,7 @@ async function handleDemo(): Promise<Response> {
 	// Insert users and track which shard they go to
 	const userPlacements = [];
 	for (const user of demoUsers) {
-		await insert(user.id, 'INSERT INTO users (id, name, email) VALUES (?, ?, ?)', [user.id, user.name, user.email]);
+		await run(user.id, 'INSERT INTO users (id, name, email) VALUES (?, ?, ?)', [user.id, user.name, user.email]);
 
 		// This would require access to the KV to determine actual shard
 		userPlacements.push({

examples/automatic-migration.ts

@@ -24,7 +24,7 @@
  * @since 1.0.0
  */
 
-import { getShardStats, initialize, insert, selectByPrimaryKey, updateByPrimaryKey } from '../src/index.js';
+import { first, getShardStats, initialize, run } from '../src/index.js';
 import type { Env } from '../src/types.js';
 
 export default {
@@ -94,14 +94,14 @@ async function handleAutomaticDemo(env: Env): Promise<Response> {
 
 	for (const userId of sampleExistingIds) {
 		try {
-			const result = await selectByPrimaryKey(userId, 'SELECT * FROM users WHERE id = ?', [userId]);
+			const result = await first(userId, 'SELECT * FROM users WHERE id = ?', [userId]);
 
-			if (result.results.length > 0) {
+			if (result) {
 				results.push({
 					type: 'existing_data',
 					userId,
 					found: true,
-					data: result.results[0],
+					data: result,
 					message: 'Existing data automatically accessible!'
 				});
 			} else {
@@ -129,16 +129,16 @@ async function handleAutomaticDemo(env: Env): Promise<Response> {
 
 	for (const user of newUsers) {
 		try {
-			await insert(user.id, 'INSERT OR REPLACE INTO users (id, name, email) VALUES (?, ?, ?)', [user.id, user.name, user.email]);
+			await run(user.id, 'INSERT OR REPLACE INTO users (id, name, email) VALUES (?, ?, ?)', [user.id, user.name, user.email]);
 
 			// Immediately query it back
-			const result = await selectByPrimaryKey(user.id, 'SELECT * FROM users WHERE id = ?', [user.id]);
+			const result = await first(user.id, 'SELECT * FROM users WHERE id = ?', [user.id]);
 
 			results.push({
 				type: 'new_data',
 				userId: user.id,
 				action: 'inserted_and_retrieved',
-				data: result.results[0],
+				data: result,
 				message: 'New data automatically distributed and queryable!'
 			});
 		} catch (error) {
@@ -152,20 +152,20 @@ async function handleAutomaticDemo(env: Env): Promise<Response> {
 
 	// Step 4: Update existing data if any was found
 	const existingUser = results.find((r) => r.type === 'existing_data' && r.found);
-	if (existingUser) {
+	if (existingUser && existingUser.data) {
 		try {
-			await updateByPrimaryKey(existingUser.userId, 'UPDATE users SET name = ? WHERE id = ?', [
+			await run(existingUser.userId, 'UPDATE users SET name = ? WHERE id = ?', [
 				`${existingUser.data.name} (Updated)`,
 				existingUser.userId
 			]);
 
-			const updatedResult = await selectByPrimaryKey(existingUser.userId, 'SELECT * FROM users WHERE id = ?', [existingUser.userId]);
+			const updatedResult = await first(existingUser.userId, 'SELECT * FROM users WHERE id = ?', [existingUser.userId]);
 
 			results.push({
 				type: 'updated_data',
 				userId: existingUser.userId,
 				action: 'updated_existing',
-				data: updatedResult.results[0],
+				data: updatedResult,
 				message: 'Existing data successfully updated through sharding!'
 			});
 		} catch (error) {

examples/drop-in-replacement.ts

@@ -27,11 +27,11 @@
  */
 
 import {
+	all,
 	discoverExistingPrimaryKeys,
 	initialize,
 	integrateExistingDatabase,
 	listTables,
-	selectByPrimaryKey,
 	validateTableForSharding
 } from '../src/index.js';
 import { KVShardMapper } from '../src/kvmap.js';
@@ -222,7 +222,7 @@ async function handleDemo(env: Env): Promise<Response> {
 
 	for (const userId of sampleUserIds) {
 		try {
-			const result = await selectByPrimaryKey(userId, 'SELECT * FROM users WHERE id = ?', [userId]);
+			const result = await all(userId, 'SELECT * FROM users WHERE id = ?', [userId]);
 
 			results.push({
 				userId,