@earth-app/collegedb 1.0.8 → 1.1.1

package/dist/router.d.ts

@@ -39,8 +39,8 @@
  * @author CollegeDB Team
  * @since 1.0.0
  */
-import type { D1Database, D1PreparedStatement, D1Result, Request } from '@cloudflare/workers-types';
-import type { CollegeDBConfig, D1Region, ShardStats } from './types.js';
+import type { Request } from '@cloudflare/workers-types';
+import type { CollegeDBConfig, D1Region, PreparedStatement, QueryResult, SQLDatabase, ShardStats } from './types';
 /**
  * Sets up the global configuration for the CollegeDB system. This must be called
  * before any other operations can be performed. The configuration includes KV
@@ -198,7 +198,7 @@ export declare function getClosestRegionFromIP(request: Request): D1Region;
  * await createSchema(env.DB_NEW_SHARD, userSchema);
  * ```
  */
-export declare function createSchema(d1: D1Database, schema: string): Promise<void>;
+export declare function createSchema(d1: SQLDatabase, schema: string): Promise<void>;
 /**
  * Prepares a SQL statement for execution with operation-aware routing.
  *
@@ -207,7 +207,7 @@ export declare function createSchema(d1: D1Database, schema: string): Promise<vo
  * @returns Promise that resolves to a prepared statement
  * @throws {Error} If preparation fails
  */
-export declare function prepare(key: string, sql: string): Promise<D1PreparedStatement>;
+export declare function prepare(key: string, sql: string): Promise<PreparedStatement>;
 /**
  * Executes a statement on the appropriate shard based on the primary key.
  * The primary key is used to determine which shard should store the record,
@@ -270,7 +270,7 @@ export declare function prepare(key: string, sql: string): Promise<D1PreparedSta
  * );
  * ```
  */
-export declare function run<T = Record<string, unknown>>(key: string, sql: string, bindings?: any[]): Promise<D1Result<T>>;
+export declare function run<T = Record<string, unknown>>(key: string, sql: string, bindings?: any[]): Promise<QueryResult<T>>;
 /**
  * Retrieves all records matching the query for a given primary key.
  *
@@ -302,7 +302,7 @@ export declare function run<T = Record<string, unknown>>(key: string, sql: strin
  * console.log(`User has ${postsResult.meta.count} posts`);
  * ```
  */
-export declare function all<T = Record<string, unknown>>(key: string, sql: string, bindings?: any[]): Promise<D1Result<T>>;
+export declare function all<T = Record<string, unknown>>(key: string, sql: string, bindings?: any[]): Promise<QueryResult<T>>;
 /**
  * Retrieves the first record matching the query for a given primary key.
  *
@@ -448,7 +448,7 @@ export declare function getShardStats(): Promise<ShardStats[]>;
  * console.log(`Inserted user with ID: ${result.lastInsertId}`);
  * ```
  */
-export declare function runShard<T = Record<string, unknown>>(shardBinding: string, sql: string, bindings?: any[]): Promise<D1Result<T>>;
+export declare function runShard<T = Record<string, unknown>>(shardBinding: string, sql: string, bindings?: any[]): Promise<QueryResult<T>>;
 /**
  * Bypasses the normal routing logic to execute a query directly on a specified
  * shard. This is useful for administrative operations, cross-shard queries,
@@ -482,7 +482,7 @@ export declare function runShard<T = Record<string, unknown>>(shardBinding: stri
  * );
  * ```
  */
-export declare function allShard<T = Record<string, unknown>>(shardBinding: string, sql: string, bindings?: any[]): Promise<D1Result<T>>;
+export declare function allShard<T = Record<string, unknown>>(shardBinding: string, sql: string, bindings?: any[]): Promise<QueryResult<T>>;
 /**
  * Bypasses the normal routing logic to execute a query directly on a specified
  * shard. This is useful for administrative operations, cross-shard queries,
@@ -522,7 +522,7 @@ export declare function firstShard<T = Record<string, unknown>>(shardBinding: st
  * @returns Promise resolving to an array of results from each shard
  * @since 1.0.4
  */
-export declare function runAllShards<T = Record<string, unknown>>(sql: string, bindings?: any[], batchSize?: number): Promise<D1Result<T>[]>;
+export declare function runAllShards<T = Record<string, unknown>>(sql: string, bindings?: any[], batchSize?: number): Promise<QueryResult<T>[]>;
 /**
  * Executes a query on all shards and returns all matching records from each shard.
  *
@@ -535,7 +535,7 @@ export declare function runAllShards<T = Record<string, unknown>>(sql: string, b
  * @returns Promise resolving to an array of results from each shard
  * @since 1.0.4
  */
-export declare function allAllShards<T = Record<string, unknown>>(sql: string, bindings?: any[], batchSize?: number): Promise<D1Result<T>[]>;
+export declare function allAllShards<T = Record<string, unknown>>(sql: string, bindings?: any[], batchSize?: number): Promise<QueryResult<T>[]>;
 /**
  * Executes a query on all shards and returns the first matching record from each shard.
  *

package/dist/router.d.ts.map

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

package/dist/types.d.ts

@@ -2,8 +2,9 @@
  * @fileoverview TypeScript type definitions for CollegeDB
  *
  * This module contains all the TypeScript interfaces and types used throughout
- * the CollegeDB library. These types provide compile-time safety and enable
- * better developer experience with IDE autocompletion and error checking.
+ * the CollegeDB library. These types provide compile-time safety, provider-
+ * agnostic storage abstractions, and a better developer experience with IDE
+ * autocompletion and error checking.
  *
  * The types are organized into several categories:
  * - Environment and configuration types
@@ -13,7 +14,7 @@
  *
  * @example
  * ```typescript
- * import type { CollegeDBConfig, QueryResult, ShardStats } from './types.js';
+ * import type { CollegeDBConfig, QueryResult, ShardStats } from './types';
  *
  * const config: CollegeDBConfig = {
  *   kv: env.KV,
@@ -25,7 +26,104 @@
  * @author Gregory Mitchell
  * @since 1.0.0
  */
-import type { D1Database, DurableObjectNamespace, KVNamespace } from '@cloudflare/workers-types';
+import type { DurableObjectNamespace } from '@cloudflare/workers-types';
+/**
+ * Result item returned by a key-value store list operation.
+ */
+export interface KVListKey {
+    /** Full key name */
+    name: string;
+    /** Optional absolute expiration timestamp */
+    expiration?: number;
+    /** Optional backend-specific metadata */
+    metadata?: unknown;
+}
+/**
+ * Result payload returned by key-value store list operations.
+ */
+export interface KVListResult {
+    /** The keys that matched the provided list filter */
+    keys: KVListKey[];
+    /** Cursor for paginated list operations (backend-specific) */
+    cursor?: string;
+    /** Whether the list is complete (backend-specific) */
+    list_complete?: boolean;
+}
+/**
+ * Provider-agnostic key-value storage contract.
+ *
+ * This interface is implemented by Cloudflare KV, Redis/Valkey adapters,
+ * and any custom KV backend supported by CollegeDB.
+ */
+export interface KVStorage {
+    /**
+     * Retrieves a value by key. When `type` is `json`, the value should be parsed.
+     */
+    get<T = unknown>(key: string, type: 'json'): Promise<T | null>;
+    get(key: string, type?: 'text'): Promise<string | null>;
+    /**
+     * Stores a value by key.
+     */
+    put(key: string, value: string): Promise<void>;
+    /**
+     * Deletes a key.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Lists keys, optionally filtered by prefix.
+     */
+    list(options?: {
+        prefix?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<KVListResult>;
+}
+/**
+ * Metadata for SQL query execution results.
+ */
+export interface QueryResultMeta {
+    /** Query duration in milliseconds */
+    duration: number;
+    /** Number of changed rows (when available) */
+    changes?: number;
+    /** Last inserted row id (when available) */
+    last_row_id?: number | string;
+    /** Additional provider-specific metadata */
+    [key: string]: unknown;
+}
+/**
+ * Provider-agnostic query result payload.
+ */
+export interface QueryResult<T = Record<string, unknown>> {
+    /** Whether the statement executed successfully */
+    success: boolean;
+    /** Returned rows for the statement */
+    results: T[];
+    /** Execution metadata */
+    meta: QueryResultMeta;
+    /** Optional backend-specific error detail */
+    error?: string;
+}
+/**
+ * Provider-agnostic prepared statement contract.
+ */
+export interface PreparedStatement {
+    /** Binds positional parameters */
+    bind(...bindings: any[]): PreparedStatement;
+    /** Executes a write-oriented statement */
+    run<T = Record<string, unknown>>(): Promise<QueryResult<T>>;
+    /** Executes a query and returns all matching rows */
+    all<T = Record<string, unknown>>(): Promise<QueryResult<T>>;
+    /** Executes a query and returns the first row */
+    first<T = Record<string, unknown>>(): Promise<T | null>;
+}
+/**
+ * Provider-agnostic SQL database contract.
+ */
+export interface SQLDatabase {
+    /** Creates a prepared statement */
+    prepare(sql: string): PreparedStatement;
+}
 /**
  * Available Cloudflare D1 regions for geographic optimization
  */
@@ -66,23 +164,28 @@ export type OperationType = 'read' | 'write';
  * Environment bindings for the Cloudflare Worker
  */
 export interface Env {
-    /** Cloudflare KV namespace for storing primary key to shard mappings */
-    KV: KVNamespace;
+    /** Key-value namespace for storing primary key to shard mappings */
+    KV: KVStorage;
     /** Durable Object binding for shard coordination */
     ShardCoordinator: DurableObjectNamespace;
-    /** D1 database bindings - dynamic based on wrangler.toml */
+    /** Optional Hyperdrive binding for external SQL connectivity */
+    HYPERDRIVE?: {
+        connectionString: string;
+        localConnectionString?: string;
+    };
+    /** D1 database bindings - dynamic based on Wrangler configuration */
     [key: string]: any;
 }
 /**
  * Configuration for the collegedb sharded database
  */
 export interface CollegeDBConfig {
-    /** KV namespace for storing mappings */
-    kv: KVNamespace;
+    /** Key-value provider for storing shard mappings */
+    kv: KVStorage;
     /** Shard coordinator Durable Object */
     coordinator?: DurableObjectNamespace;
-    /** Available D1 database bindings */
-    shards: Record<string, D1Database>;
+    /** Available SQL shard providers */
+    shards: Record<string, SQLDatabase>;
     /** Default shard allocation strategy (can be single strategy or mixed strategy object) */
     strategy?: ShardingStrategy | MixedShardingStrategy;
     /** Target region for location-based sharding */
@@ -109,12 +212,38 @@ export interface CollegeDBConfig {
      */
     debug?: boolean;
     /**
-     * Maximum database size in bytes. Shards that exceed this size will be excluded
-     * from new allocations (existing mappings remain intact).
-     * @default 10683731148 // 9.95 GB, close to D1's 10 GB limit
+     * Maximum database size in bytes. When set, shards that exceed this size are
+     * excluded from new allocations (existing mappings remain intact).
+     *
+     * When omitted, size-based filtering is disabled to avoid extra sizing queries.
+     * This significantly reduces routing latency for write-heavy workloads.
      * @since 1.0.8
      */
     maxDatabaseSize?: number;
+    /**
+     * In-memory TTL for primary key to shard mapping cache.
+     * @default 30000
+     * @since 1.1.0
+     */
+    mappingCacheTtlMs?: number;
+    /**
+     * In-memory TTL for known shard list cache.
+     * @default 10000
+     * @since 1.1.0
+     */
+    knownShardsCacheTtlMs?: number;
+    /**
+     * In-memory TTL for shard size checks when `maxDatabaseSize` is enabled.
+     * @default 30000
+     * @since 1.1.0
+     */
+    sizeCacheTtlMs?: number;
+    /**
+     * Concurrency limit for migration mapping operations.
+     * @default 25
+     * @since 1.1.0
+     */
+    migrationConcurrency?: number;
 }
 /**
  * Shard statistics for monitoring and load balancing

package/dist/types.d.ts.map

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

package/package.json

@@ -4,7 +4,7 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
-  "version": "1.0.8",
+  "version": "1.1.1",
   "files": [
     "dist/**/*",
     "README.md",
@@ -21,30 +21,54 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "test:sandbox": "bun scripts/sandbox/run.ts --db=all --kv=all --include-cloudflare",
+    "test:sandbox:all": "bun scripts/sandbox/run.ts --db=all --kv=all",
+    "test:sandbox:cloudflare": "bun scripts/sandbox/run.ts --cloudflare-only",
+    "test:sandbox:postgres": "bun scripts/sandbox/run.ts --db=postgres --kv=all",
+    "test:sandbox:mysql": "bun scripts/sandbox/run.ts --db=mysql --kv=all",
+    "test:sandbox:mariadb": "bun scripts/sandbox/run.ts --db=mariadb --kv=all",
+    "test:sandbox:sqlite": "bun scripts/sandbox/run.ts --db=sqlite --kv=all",
+    "test:sandbox:drizzle": "bun scripts/sandbox/run.ts --db=all --kv=all --profile=drizzle",
+    "test:sandbox:nuxthub": "bun scripts/sandbox/run.ts --db=all --kv=all --profile=nuxthub",
+    "test:sandbox:hyperdrive": "bun scripts/sandbox/run.ts --db=all --kv=all --profile=hyperdrive",
+    "test:sandbox:redis": "bun scripts/sandbox/run.ts --db=all --kv=redis",
+    "test:sandbox:valkey": "bun scripts/sandbox/run.ts --db=all --kv=valkey",
+    "test:sandbox:postgres+redis": "bun scripts/sandbox/run.ts --db=postgres --kv=redis",
+    "test:sandbox:postgres+valkey": "bun scripts/sandbox/run.ts --db=postgres --kv=valkey",
+    "test:sandbox:mysql+redis": "bun scripts/sandbox/run.ts --db=mysql --kv=redis",
+    "test:sandbox:mysql+valkey": "bun scripts/sandbox/run.ts --db=mysql --kv=valkey",
+    "test:sandbox:mariadb+redis": "bun scripts/sandbox/run.ts --db=mariadb --kv=redis",
+    "test:sandbox:mariadb+valkey": "bun scripts/sandbox/run.ts --db=mariadb --kv=valkey",
+    "test:sandbox:sqlite+redis": "bun scripts/sandbox/run.ts --db=sqlite --kv=redis",
+    "test:sandbox:sqlite+valkey": "bun scripts/sandbox/run.ts --db=sqlite --kv=valkey",
     "prepare": "husky install"
   },
-  "dependencies": {
-    "@cloudflare/workers-types": "^4.20250726.0"
-  },
   "devDependencies": {
-    "@babel/cli": "^7.28.0",
-    "@babel/core": "^7.28.0",
-    "@babel/preset-env": "^7.28.0",
-    "@babel/preset-typescript": "^7.27.1",
+    "@babel/cli": "^7.28.6",
+    "@babel/core": "^7.29.0",
+    "@babel/preset-env": "^7.29.2",
+    "@babel/preset-typescript": "^7.28.5",
+    "@cloudflare/workers-types": "^4.20260415.1",
     "@types/bun": "latest",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@types/pg": "^8.15.6",
+    "@vitest/coverage-v8": "^4.1.4",
+    "drizzle-orm": "^0.45.2",
     "husky": "^9.1.7",
     "jsdoc-babel": "^0.5.0",
-    "lint-staged": "^16.1.2",
-    "prettier": "^3.6.2",
-    "prettier-plugin-organize-imports": "4.1.0",
-    "typedoc": "^0.28.8",
-    "vitest": "^3.2.4"
+    "lint-staged": "^16.4.0",
+    "mysql2": "^3.15.3",
+    "pg": "^8.16.3",
+    "prettier": "^3.8.3",
+    "prettier-plugin-organize-imports": "4.3.0",
+    "redis": "^5.8.2",
+    "typedoc": "^0.28.19",
+    "vitest": "^4.1.4",
+    "wrangler": "^4.64.0"
   },
   "peerDependencies": {
-    "typescript": "^5"
+    "typescript": "^5.8.3"
   },
   "lint-staged": {
-    "*.{js,ts,css,md}": "prettier --write"
+    "*.{js,ts,css,md,json,yml,jsonc}": "prettier --write"
   }
 }