prisma-sharding 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,180 @@
+# Prisma Sharding
+
+Lightweight database sharding library for Prisma with connection pooling, health monitoring, and circuit breaker support.
+
+## Installation
+
+```bash
+yarn add prisma-sharding
+# or
+npm install prisma-sharding
+```
+
+## Quick Start
+
+```typescript
+import { PrismaSharding } from 'prisma-sharding';
+import { PrismaClient } from '@/generated/prisma';
+import { PrismaPg } from '@prisma/adapter-pg';
+
+const sharding = new PrismaSharding<PrismaClient>({
+  shards: [
+    { id: 'shard_1', url: process.env.SHARD_1_URL! },
+    { id: 'shard_2', url: process.env.SHARD_2_URL! },
+    { id: 'shard_3', url: process.env.SHARD_3_URL! },
+  ],
+  strategy: 'modulo', // 'modulo' | 'consistent-hash'
+  createClient: (url) => {
+    const adapter = new PrismaPg({ connectionString: url, max: 10 });
+    return new PrismaClient({ adapter });
+  },
+});
+
+// Initialize connections
+await sharding.connect();
+```
+
+## Usage
+
+### Get Shard by Key
+
+```typescript
+// Get client for existing user (routed by user ID)
+const client = sharding.getShard(userId);
+const user = await client.user.findUnique({ where: { id: userId } });
+
+// Get shard with metadata
+const { client, shardId } = sharding.getShardWithInfo(userId);
+```
+
+### Random Shard (New Records)
+
+```typescript
+// Get random shard for creating new user (ensures even distribution)
+const client = sharding.getRandomShard();
+const newUser = await client.user.create({ data: { email, username } });
+```
+
+### Cross-Shard Search
+
+```typescript
+// Find user by email across ALL shards (parallel execution)
+const { result: user, client } = await sharding.findFirst(async (c) =>
+  c.user.findFirst({ where: { email } })
+);
+
+if (user && client) {
+  // Continue operations on the found shard
+  await client.user.update({
+    where: { id: user.id },
+    data: { lastLogin: new Date() },
+  });
+}
+```
+
+### Execute on All Shards
+
+```typescript
+// Get counts from all shards
+const counts = await sharding.runOnAll(async (client) => client.user.count());
+const totalUsers = counts.reduce((sum, count) => sum + count, 0);
+
+// With detailed results (includes errors)
+const results = await sharding.runOnAllWithDetails(async (client, shardId) => {
+  return { shardId, count: await client.user.count() };
+});
+```
+
+### Health Monitoring
+
+```typescript
+// Get health of all shards
+const health = sharding.getHealth();
+// Returns: [{ shardId, isHealthy, latencyMs, lastChecked, ... }]
+
+// Get specific shard health
+const shard1Health = sharding.getHealthByShard('shard_1');
+```
+
+### Lifecycle
+
+```typescript
+// Graceful shutdown
+await sharding.disconnect();
+
+// Check connection status
+if (sharding.isConnected()) {
+  // ...
+}
+```
+
+## Configuration
+
+| Option                    | Type                            | Default    | Description                               |
+| ------------------------- | ------------------------------- | ---------- | ----------------------------------------- |
+| `shards`                  | `ShardConfig[]`                 | Required   | Array of shard configurations             |
+| `strategy`                | `'modulo' \| 'consistent-hash'` | `'modulo'` | Routing algorithm                         |
+| `createClient`            | `(url, shardId) => TClient`     | Required   | Factory function to create Prisma clients |
+| `healthCheckIntervalMs`   | `number`                        | `30000`    | Health check frequency                    |
+| `circuitBreakerThreshold` | `number`                        | `3`        | Failures before marking unhealthy         |
+| `logger`                  | `ShardingLogger`                | Console    | Custom logger                             |
+
+### Shard Config
+
+```typescript
+interface ShardConfig {
+  id: string; // Unique identifier (e.g., 'shard_1')
+  url: string; // PostgreSQL connection string
+  weight?: number; // Optional weight for distribution
+  isReadReplica?: boolean;
+}
+```
+
+## Routing Strategies
+
+### Modulo (Default)
+
+Simple and fast. Uses `hash(key) % shardCount` for routing.
+
+```typescript
+strategy: 'modulo';
+```
+
+### Consistent Hash
+
+Minimizes data movement when adding/removing shards.
+
+```typescript
+strategy: 'consistent-hash';
+```
+
+## Error Handling
+
+```typescript
+import { ShardingError, ConfigError, ConnectionError, RoutingError } from 'prisma-sharding';
+
+try {
+  const client = sharding.getShard(userId);
+} catch (error) {
+  if (error instanceof ConnectionError) {
+    console.error(`Shard ${error.shardId} unavailable`);
+  }
+}
+```
+
+## Custom Logger
+
+```typescript
+const sharding = new PrismaSharding({
+  // ...config,
+  logger: {
+    info: (msg) => myLogger.info(msg),
+    warn: (msg) => myLogger.warn(msg),
+    error: (msg) => myLogger.error(msg),
+  },
+});
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,126 @@
+interface ShardConfig {
+    id: string;
+    url: string;
+    weight?: number;
+    isReadReplica?: boolean;
+}
+interface PoolConfig {
+    maxConnections?: number;
+    idleTimeoutMs?: number;
+    connectionTimeoutMs?: number;
+}
+interface ShardHealth {
+    shardId: string;
+    isHealthy: boolean;
+    latencyMs: number;
+    lastChecked: Date;
+    errorCount: number;
+    consecutiveFailures: number;
+}
+interface ShardInstance<TClient> {
+    config: ShardConfig;
+    client: TClient;
+    health: ShardHealth;
+}
+interface ShardResult<TClient> {
+    shardId: string;
+    client: TClient;
+}
+interface CrossShardResult<T> {
+    shardId: string;
+    result: T | null;
+    error?: Error;
+}
+interface FindFirstResult<T, TClient> {
+    result: T | null;
+    shardId: string | null;
+    client: TClient | null;
+}
+type RoutingStrategy = 'modulo' | 'consistent-hash';
+interface ShardingConfig<TClient> {
+    shards: ShardConfig[];
+    strategy?: RoutingStrategy;
+    createClient: (url: string, shardId: string) => TClient;
+    pool?: PoolConfig;
+    healthCheckIntervalMs?: number;
+    circuitBreakerThreshold?: number;
+    logger?: ShardingLogger;
+}
+interface ShardingLogger {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+}
+type ClientFactory<TClient> = (url: string, shardId: string) => TClient;
+
+declare class PrismaSharding<TClient> {
+    private manager;
+    private router;
+    private config;
+    private logger;
+    private connected;
+    constructor(config: ShardingConfig<TClient>);
+    private validateConfig;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    private ensureConnected;
+    getShard(key: string): TClient;
+    getShardById(shardId: string): TClient;
+    getShardWithInfo(key: string): ShardResult<TClient>;
+    getRandomShard(): TClient;
+    getRandomShardWithInfo(): ShardResult<TClient>;
+    findFirst<T>(finder: (client: TClient) => Promise<T | null>): Promise<FindFirstResult<T, TClient>>;
+    runOnAll<T>(operation: (client: TClient, shardId: string) => Promise<T>): Promise<T[]>;
+    runOnAllWithDetails<T>(operation: (client: TClient, shardId: string) => Promise<T>): Promise<CrossShardResult<T>[]>;
+    getHealth(): ShardHealth[];
+    getHealthByShard(shardId: string): ShardHealth | undefined;
+    getAllClients(): TClient[];
+    getHealthyClients(): TClient[];
+    getShardCount(): number;
+    getShardIds(): string[];
+    isConnected(): boolean;
+}
+
+declare class ShardingError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+declare class ConfigError extends ShardingError {
+    constructor(message: string);
+}
+declare class ConnectionError extends ShardingError {
+    readonly shardId: string;
+    constructor(message: string, shardId: string);
+}
+declare class RoutingError extends ShardingError {
+    constructor(message: string);
+}
+
+declare const DEFAULTS: {
+    readonly POOL_MAX_CONNECTIONS: 10;
+    readonly POOL_IDLE_TIMEOUT_MS: 10000;
+    readonly POOL_CONNECTION_TIMEOUT_MS: 5000;
+    readonly HEALTH_CHECK_INTERVAL_MS: 30000;
+    readonly CIRCUIT_BREAKER_THRESHOLD: 3;
+    readonly CONSISTENT_HASH_VIRTUAL_NODES: 150;
+};
+declare const ERROR_MESSAGES: {
+    readonly NO_SHARDS: "At least one shard must be configured";
+    readonly SHARD_NOT_FOUND: (id: string) => string;
+    readonly NO_HEALTHY_SHARDS: "No healthy shards available";
+    readonly INVALID_STRATEGY: (s: string) => string;
+    readonly NOT_CONNECTED: "Sharding not connected. Call connect() first";
+    readonly ALREADY_CONNECTED: "Sharding already connected";
+    readonly MISSING_CLIENT_FACTORY: "createClient function is required";
+    readonly INVALID_SHARD_URL: (id: string) => string;
+};
+
+declare function hashString(str: string): number;
+declare function validateUrl(url: string): boolean;
+declare function createDefaultLogger(): {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+};
+
+export { type ClientFactory, ConfigError, ConnectionError, type CrossShardResult, DEFAULTS, ERROR_MESSAGES, type FindFirstResult, type PoolConfig, PrismaSharding, RoutingError, type RoutingStrategy, type ShardConfig, type ShardHealth, type ShardInstance, type ShardResult, type ShardingConfig, ShardingError, type ShardingLogger, createDefaultLogger, hashString, validateUrl };

package/dist/index.d.ts

@@ -0,0 +1,126 @@
+interface ShardConfig {
+    id: string;
+    url: string;
+    weight?: number;
+    isReadReplica?: boolean;
+}
+interface PoolConfig {
+    maxConnections?: number;
+    idleTimeoutMs?: number;
+    connectionTimeoutMs?: number;
+}
+interface ShardHealth {
+    shardId: string;
+    isHealthy: boolean;
+    latencyMs: number;
+    lastChecked: Date;
+    errorCount: number;
+    consecutiveFailures: number;
+}
+interface ShardInstance<TClient> {
+    config: ShardConfig;
+    client: TClient;
+    health: ShardHealth;
+}
+interface ShardResult<TClient> {
+    shardId: string;
+    client: TClient;
+}
+interface CrossShardResult<T> {
+    shardId: string;
+    result: T | null;
+    error?: Error;
+}
+interface FindFirstResult<T, TClient> {
+    result: T | null;
+    shardId: string | null;
+    client: TClient | null;
+}
+type RoutingStrategy = 'modulo' | 'consistent-hash';
+interface ShardingConfig<TClient> {
+    shards: ShardConfig[];
+    strategy?: RoutingStrategy;
+    createClient: (url: string, shardId: string) => TClient;
+    pool?: PoolConfig;
+    healthCheckIntervalMs?: number;
+    circuitBreakerThreshold?: number;
+    logger?: ShardingLogger;
+}
+interface ShardingLogger {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+}
+type ClientFactory<TClient> = (url: string, shardId: string) => TClient;
+
+declare class PrismaSharding<TClient> {
+    private manager;
+    private router;
+    private config;
+    private logger;
+    private connected;
+    constructor(config: ShardingConfig<TClient>);
+    private validateConfig;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    private ensureConnected;
+    getShard(key: string): TClient;
+    getShardById(shardId: string): TClient;
+    getShardWithInfo(key: string): ShardResult<TClient>;
+    getRandomShard(): TClient;
+    getRandomShardWithInfo(): ShardResult<TClient>;
+    findFirst<T>(finder: (client: TClient) => Promise<T | null>): Promise<FindFirstResult<T, TClient>>;
+    runOnAll<T>(operation: (client: TClient, shardId: string) => Promise<T>): Promise<T[]>;
+    runOnAllWithDetails<T>(operation: (client: TClient, shardId: string) => Promise<T>): Promise<CrossShardResult<T>[]>;
+    getHealth(): ShardHealth[];
+    getHealthByShard(shardId: string): ShardHealth | undefined;
+    getAllClients(): TClient[];
+    getHealthyClients(): TClient[];
+    getShardCount(): number;
+    getShardIds(): string[];
+    isConnected(): boolean;
+}
+
+declare class ShardingError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+declare class ConfigError extends ShardingError {
+    constructor(message: string);
+}
+declare class ConnectionError extends ShardingError {
+    readonly shardId: string;
+    constructor(message: string, shardId: string);
+}
+declare class RoutingError extends ShardingError {
+    constructor(message: string);
+}
+
+declare const DEFAULTS: {
+    readonly POOL_MAX_CONNECTIONS: 10;
+    readonly POOL_IDLE_TIMEOUT_MS: 10000;
+    readonly POOL_CONNECTION_TIMEOUT_MS: 5000;
+    readonly HEALTH_CHECK_INTERVAL_MS: 30000;
+    readonly CIRCUIT_BREAKER_THRESHOLD: 3;
+    readonly CONSISTENT_HASH_VIRTUAL_NODES: 150;
+};
+declare const ERROR_MESSAGES: {
+    readonly NO_SHARDS: "At least one shard must be configured";
+    readonly SHARD_NOT_FOUND: (id: string) => string;
+    readonly NO_HEALTHY_SHARDS: "No healthy shards available";
+    readonly INVALID_STRATEGY: (s: string) => string;
+    readonly NOT_CONNECTED: "Sharding not connected. Call connect() first";
+    readonly ALREADY_CONNECTED: "Sharding already connected";
+    readonly MISSING_CLIENT_FACTORY: "createClient function is required";
+    readonly INVALID_SHARD_URL: (id: string) => string;
+};
+
+declare function hashString(str: string): number;
+declare function validateUrl(url: string): boolean;
+declare function createDefaultLogger(): {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+};
+
+export { type ClientFactory, ConfigError, ConnectionError, type CrossShardResult, DEFAULTS, ERROR_MESSAGES, type FindFirstResult, type PoolConfig, PrismaSharding, RoutingError, type RoutingStrategy, type ShardConfig, type ShardHealth, type ShardInstance, type ShardResult, type ShardingConfig, ShardingError, type ShardingLogger, createDefaultLogger, hashString, validateUrl };