@gravito/ripple 4.0.1 → 5.0.0

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@gravito/ripple",
-  "version": "4.0.1",
+  "sideEffects": false,
+  "version": "5.0.0",
   "description": "Bun-native WebSocket broadcasting for Gravito. Channel-based real-time communication.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -19,6 +20,7 @@
   ],
   "scripts": {
     "build": "bun run build.ts",
+    "build:dts": "bun run build.ts --dts-only",
     "test": "bun test --timeout=10000",
     "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
     "test:coverage": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
@@ -44,7 +46,7 @@
   },
   "homepage": "https://github.com/gravito-framework/gravito#readme",
   "peerDependencies": {
-    "@gravito/core": "^1.6.1",
+    "@gravito/core": "^3.0.0",
     "ioredis": "^5.0.0",
     "nats": "^2.23.0",
     "protobufjs": "^8.0.0",
@@ -65,9 +67,11 @@
     }
   },
   "devDependencies": {
+    "@gravito/core": "workspace:*",
     "@types/ws": "^8.18.1",
     "bun-types": "latest",
     "ioredis": "^5.4.2",
+    "nats": "^2.23.0",
     "protobufjs": "^8.0.0",
     "tinybench": "^6.0.0",
     "typescript": "^5.9.3",

package/dist/atlas/src/DB.d.ts

@@ -1,348 +0,0 @@
-import { type AtlasMetrics, type AtlasTracer } from './observability';
-import type { ShardingManager } from './sharding/ShardingManager';
-import type { AtlasConfig, AtlasConnectionEntry, CacheInterface, ConnectionContract, QueryBuilderContract, QueryResult } from './types';
-/**
- * DB Facade - Static entry point for database operations.
- *
- * Provides a Laravel-style static interface for managing connections,
- * building queries, and executing transactions. Acts as the primary
- * gateway for application-level database interaction.
- *
- * @example
- * ```typescript
- * // Setup
- * DB.configure({
- *   default: 'main',
- *   connections: { main: { driver: 'sqlite', database: ':memory:' } }
- * });
- *
- * // Fluent Querying
- * const users = await DB.table('users').where('id', 1).get();
- *
- * // Raw Execution
- * const stats = await DB.raw('SELECT count(*) FROM users');
- * ```
- */
-export declare class DB {
-    private static manager;
-    private static shardingManagers;
-    private static initialized;
-    private static cache;
-    private static _debug;
-    private static _queryLog;
-    private static readonly MAX_LOG_SIZE;
-    private static queryListener?;
-    /**
-     * Registers a ShardingManager for distributed database architectures.
-     *
-     * @param name - Unique identifier for the sharding cluster
-     * @param manager - The initialized ShardingManager instance
-     */
-    static addShardingManager(name: string, manager: ShardingManager): void;
-    /**
-     * Retrieves a registered ShardingManager.
-     *
-     * @param name - Name of the sharding cluster (defaults to 'default')
-     * @throws Error if the manager is not found
-     */
-    static getShardingManager(name?: string): ShardingManager;
-    /**
-     * Sets the global cache provider for query results.
-     *
-     * @param cache - Implementation of CacheInterface (e.g., Redis, In-Memory).
-     */
-    static setCache(cache: CacheInterface): void;
-    /**
-     * Retrieves the active global cache provider.
-     *
-     * @returns The cache interface or undefined if none is configured.
-     */
-    static getCache(): CacheInterface | undefined;
-    /**
-     * Toggles debug mode for query logging.
-     *
-     * When enabled, executed queries are stored in an internal log with
-     * performance metrics.
-     *
-     * @param enabled - Whether to enable logging.
-     */
-    static debug(enabled?: boolean): void;
-    /**
-     * Indicates if debug mode is currently active.
-     */
-    static isDebug(): boolean;
-    /**
-     * Retrieves the last executed SQL statement with interpolated values.
-     *
-     * Useful for debugging and integration testing.
-     *
-     * @returns The full SQL string or null if no queries were run.
-     */
-    static getLastQuery(): string | null;
-    /**
-     * Retrieves the complete query log for the current session.
-     *
-     * @returns A copy of the query log array.
-     */
-    static getQueryLog(): typeof this._queryLog;
-    /**
-     * Flushes the internal query log.
-     */
-    static clearQueryLog(): void;
-    /**
-     * Records a query execution event.
-     *
-     * @param sql - The SQL statement.
-     * @param bindings - The parameter values.
-     * @param duration - Time taken in ms.
-     * @internal
-     */
-    static logQuery(sql: string, bindings: unknown[], duration: number): void;
-    /**
-     * Interpolates bindings into a SQL string for display purposes.
-     *
-     * Warning: This is only for logging/debugging and NOT for execution
-     * to avoid SQL injection risks.
-     *
-     * @param sql - The SQL template with placeholders.
-     * @param bindings - The values to inject.
-     * @returns The readable SQL string.
-     */
-    private static interpolateBindings;
-    /**
-     * Executes a callback in "pretend" mode where queries are captured but not run.
-     *
-     * Ideal for verifying generated SQL without side effects.
-     *
-     * @param callback - Logic to simulate.
-     * @returns Captured SQL strings and the callback result.
-     *
-     * @example
-     * ```typescript
-     * const { queries } = await DB.pretend(() => User.create({ name: 'Test' }));
-     * ```
-     */
-    static pretend<T>(callback: () => Promise<T>): Promise<{
-        queries: string[];
-        result?: T;
-    }>;
-    private constructor();
-    /**
-     * Retrieves performance metrics from the SQL compiler cache.
-     *
-     * @returns Stats including hit rate and cache utilization.
-     */
-    static getCacheStats(): {
-        size: number;
-        maxSize: number;
-        hitRate: number;
-    };
-    /**
-     * Initializes the database subsystem with the provided configuration.
-     *
-     * Configures the connection manager and observability (Tracing/Metrics).
-     * This method must be called before any database operations.
-     *
-     * @param config - The Atlas configuration object.
-     * @throws {Error} If configuration is invalid.
-     */
-    static configure(config: AtlasConfig): void;
-    /**
-     * Retrieves the global tracer for manual span creation.
-     */
-    static getTracer(): AtlasTracer | undefined;
-    /**
-     * Retrieves the global metrics reporter.
-     */
-    static getMetrics(): AtlasMetrics | undefined;
-    /**
-     * Configures the database using environment variables.
-     *
-     * Looks for standard DB_* variables or DATABASE_URL.
-     *
-     * @param connectionName - The name to assign to the primary connection.
-     */
-    static configureFromEnv(connectionName?: string): void;
-    /**
-     * Loads configuration from a file.
-     *
-     * Automatically detects common patterns like config/database.ts.
-     *
-     * @param configPath - Explicit path to the config file.
-     */
-    static configureFromFile(configPath?: string): Promise<void>;
-    /**
-     * Best-effort configuration using file detection then environment variables.
-     *
-     * @param configPath - Optional path to try first.
-     */
-    static autoConfigure(configPath?: string): Promise<void>;
-    /**
-     * Manually adds a connection to the manager.
-     *
-     * @param name - Unique connection name.
-     * @param config - Connection settings (standard or read/write replica).
-     */
-    static addConnection(name: string, config: AtlasConnectionEntry): void;
-    /**
-     * Adds a connection configured via prefixed environment variables.
-     *
-     * @param name - Connection name.
-     * @param prefix - Env variable prefix (e.g. "READ_ONLY").
-     */
-    static addConnectionFromEnv(name: string, prefix?: string): void;
-    /**
-     * Sets the global default connection.
-     *
-     * @param name - The connection identifier.
-     */
-    static setDefaultConnection(name: string): void;
-    /**
-     * Returns the name of the current default connection.
-     */
-    static getDefaultConnection(): string;
-    /**
-     * Retrieves a connection instance.
-     *
-     * @param name - Name of the connection (defaults to the global default).
-     * @returns The active connection instance.
-     * @throws {Error} If DB is not configured or connection name is unknown.
-     */
-    static connection(name?: string): ConnectionContract;
-    /**
-     * Retrieves the read replica connection for the given connection name.
-     *
-     * Uses round-robin selection across configured read replicas.
-     * Falls back to the primary connection if no replicas are configured.
-     *
-     * @param name - Connection name (defaults to global default)
-     */
-    static readConnection(name?: string): ConnectionContract;
-    /**
-     * Retrieves the write (primary) connection for the given connection name.
-     *
-     * Use this to force a query to run on the primary even inside a read context.
-     *
-     * @param name - Connection name (defaults to global default)
-     */
-    static writeConnection(name?: string): ConnectionContract;
-    /**
-     * Checks if a specific connection has been configured.
-     */
-    static hasConnection(name: string): boolean;
-    /**
-     * Lists all configured connection identifiers.
-     */
-    static getConnectionNames(): string[];
-    /**
-     * Retrieves the raw configuration for a connection.
-     */
-    static getConnectionConfig(name?: string): AtlasConnectionEntry | undefined;
-    /**
-     * Initializes a fluent query builder for a specific table.
-     *
-     * @template T - The row type.
-     * @param tableName - The database table name.
-     * @returns A QueryBuilder instance.
-     */
-    static table<T = Record<string, unknown>>(tableName: string): QueryBuilderContract<T>;
-    /**
-     * Executes a raw SQL statement with telemetry tracking.
-     *
-     * @template T - The expected row type.
-     * @param sql - The SQL string with placeholders.
-     * @param bindings - Array of values.
-     * @returns The raw query result.
-     *
-     * @example
-     * ```typescript
-     * const users = await DB.raw('SELECT * FROM users WHERE active = ?', [true]);
-     * ```
-     */
-    static raw<T = Record<string, unknown>>(sql: string, bindings?: unknown[]): Promise<QueryResult<T>>;
-    /**
-     * Alias for {@link raw}.
-     */
-    static rawQuery<T = Record<string, unknown>>(sql: string, bindings?: unknown[]): Promise<QueryResult<T>>;
-    /**
-     * Executes logic within a managed database transaction.
-     *
-     * Automatically commits on success and rolls back on error.
-     * Receives a connection instance scoped to the transaction.
-     *
-     * @template T - Logic result type.
-     * @param callback - The transactional logic.
-     * @param connectionName - Optional specific connection.
-     * @returns The callback's return value.
-     */
-    static transaction<T>(callback: (connection: ConnectionContract) => Promise<T>, connectionName?: string): Promise<T>;
-    /**
-     * Executes logic within a managed database transaction with automatic retry on serialization/stale data failures.
-     *
-     * Particularly useful for high-concurrency environments utilizing optimistic locking,
-     * where `StaleModelError` is thrown due to concurrent writes.
-     *
-     * @template T - Logic result type.
-     * @param callback - The transactional logic.
-     * @param connectionName - Optional specific connection.
-     * @param maxRetries - Maximum number of retries (default: 5).
-     * @returns The callback's return value.
-     * @throws Rethrows the error if max retries are exceeded.
-     */
-    static transactionWithRetry<T>(callback: (connection: ConnectionContract, attempt: number) => Promise<T>, connectionName?: string, maxRetries?: number): Promise<T>;
-    /**
-     * Manually starts a database transaction.
-     *
-     * Caller is responsible for calling commit() or rollback().
-     *
-     * @param connectionName - Connection to use.
-     * @returns A transaction-scoped connection.
-     * @throws {Error} If the driver does not support transactions.
-     */
-    static beginTransaction(connectionName?: string): Promise<ConnectionContract>;
-    /**
-     * Closes the specified connection.
-     */
-    static disconnect(name?: string): Promise<void>;
-    /**
-     * Closes all managed connections.
-     */
-    static disconnectAll(): Promise<void>;
-    /**
-     * Safely shuts down the database subsystem.
-     */
-    static shutdown(): Promise<void>;
-    /**
-     * Closes and re-opens a connection.
-     */
-    static reconnect(name?: string): Promise<ConnectionContract>;
-    /**
-     * Removes a connection from the internal cache without closing it.
-     */
-    static purge(name?: string): void;
-    /**
-     * Shortcut for starting a query with specific columns.
-     */
-    static select<T = Record<string, unknown>>(tableName: string, columns?: string[]): QueryBuilderContract<T>;
-    /**
-     * Shortcut for inserting records.
-     */
-    static insert<T = Record<string, unknown>>(tableName: string, data: Partial<T> | Partial<T>[]): Promise<T[]>;
-    /**
-     * Shortcut for updating records based on key-value filters.
-     */
-    static update<T = Record<string, unknown>>(tableName: string, where: Record<string, unknown>, data: Partial<T>): Promise<number>;
-    /**
-     * Shortcut for deleting records based on key-value filters.
-     */
-    static delete(tableName: string, where: Record<string, unknown>): Promise<number>;
-    /**
-     * Ensures the DB facade is ready for use.
-     */
-    private static ensureConfigured;
-    /**
-     * Internal reset for testing.
-     * @internal
-     */
-    static _reset(): Promise<void>;
-}

package/dist/atlas/src/OrbitAtlas.d.ts

@@ -1,9 +0,0 @@
-import type { GravitoOrbit, PlanetCore } from '@gravito/core';
-/**
- * Atlas Orbit - Database & ORM Integration
- * Integrates the Atlas ORM engine into the Gravito Core ecosystem.
- * @public
- */
-export declare class OrbitAtlas implements GravitoOrbit {
-    install(core: PlanetCore): Promise<void>;
-}

package/dist/atlas/src/config/defineConfig.d.ts

@@ -1,14 +0,0 @@
-import type { AtlasConfig, AtlasObservabilityConfig, ConnectionConfig, PostgresConfig } from '../types';
-export type { AtlasConfig, AtlasObservabilityConfig, ConnectionConfig, PostgresConfig };
-/**
- * Define configuration with type checking
- */
-export declare function defineConfig(config: AtlasConfig): AtlasConfig;
-/**
- * Load configuration from environment variables with optional prefix
- * Supports both DATABASE_URL and individual DB_* variables
- *
- * @param connectionName - Name for the connection
- * @param prefix - Optional prefix for environment variables (e.g., 'READ' for DB_READ_*)
- */
-export declare function fromEnv(connectionName?: string, prefix?: string): AtlasConfig;

package/dist/atlas/src/config/index.d.ts

@@ -1,7 +0,0 @@
-/**
- * Configuration Module
- * @description Database configuration utilities
- */
-export type { AtlasConfig, ConnectionConfig } from '../types';
-export { defineConfig, fromEnv } from './defineConfig';
-export { loadConfig, loadConfigFile } from './loadConfig';

package/dist/atlas/src/config/loadConfig.d.ts

@@ -1,41 +0,0 @@
-/**
- * Configuration Loader
- * @description Load database configuration from various sources
- */
-import type { AtlasConfig } from '../types';
-/**
- * Load configuration from a TypeScript/JavaScript config file
- *
- * @param configPath - Path to the config file (default: 'config/database.ts' or 'config/database.js')
- * @returns Atlas configuration
- *
- * @example
- * ```typescript
- * // config/database.ts
- * import { defineConfig } from '@gravito/atlas'
- *
- * export default defineConfig({
- *   default: 'default',
- *   connections: {
- *     default: {
- *       driver: 'postgres',
- *       host: 'localhost',
- *       database: 'myapp'
- *     }
- *   }
- * })
- * ```
- */
-export declare function loadConfigFile(configPath?: string): Promise<AtlasConfig>;
-/**
- * Load configuration from multiple sources with priority
- * Priority: 1. Config file, 2. Environment variables, 3. Default
- *
- * @param options - Loading options
- * @returns Atlas configuration
- */
-export declare function loadConfig(options?: {
-    configPath?: string;
-    useEnv?: boolean;
-    envPrefix?: string;
-}): Promise<AtlasConfig>;

package/dist/atlas/src/connection/Connection.d.ts

@@ -1,112 +0,0 @@
-/**
- * Connection
- * @description Represents a database connection
- */
-import type { AtlasMetrics, AtlasTracer } from '../observability';
-import type { ConnectionConfig, ConnectionContract, DriverContract, ExecuteResult, GrammarContract, PoolStats, QueryBuilderContract, QueryResult } from '../types';
-/**
- * Database Connection
- * Wraps a driver and grammar for query building and execution
- */
-export declare class Connection implements ConnectionContract {
-    protected readonly name: string;
-    protected readonly config: ConnectionConfig;
-    protected driver: DriverContract;
-    protected grammar: GrammarContract;
-    protected connected: boolean;
-    protected proxy?: ConnectionContract;
-    protected tracer: AtlasTracer | undefined;
-    protected metrics: AtlasMetrics | undefined;
-    /**
-     * Static query listeners for global observation (e.g. debugging)
-     */
-    static queryListeners: Array<(query: {
-        connection: string;
-        sql: string;
-        bindings: unknown[];
-        duration: number;
-        timestamp: number;
-    }) => void>;
-    constructor(name: string, config: ConnectionConfig);
-    /**
-     * Set the proxy instance for this connection
-     */
-    setProxy(proxy: ConnectionContract): void;
-    /**
-     * Get connection name
-     */
-    getName(): string;
-    /**
-     * Get the underlying driver
-     */
-    getDriver(): DriverContract;
-    /**
-     * Get connection configuration
-     */
-    getConfig(): ConnectionConfig;
-    /**
-     * Get the grammar
-     */
-    getGrammar(): GrammarContract;
-    /**
-     * Get the tracer
-     */
-    getTracer(): AtlasTracer | undefined;
-    /**
-     * Get the metrics
-     */
-    getMetrics(): AtlasMetrics | undefined;
-    /**
-     * Create a new query builder for a table
-     */
-    table<T = Record<string, unknown>>(tableName: string): QueryBuilderContract<T>;
-    /**
-     * Alias for table() for NoSQL connections
-     */
-    collection<T = Record<string, unknown>>(name: string): QueryBuilderContract<T>;
-    /**
-     * Execute raw SQL
-     */
-    raw<T = Record<string, unknown>>(sql: string, bindings?: unknown[]): Promise<QueryResult<T>>;
-    /**
-     * Execute raw SQL statement (INSERT/UPDATE/DELETE)
-     */
-    execute(sql: string, bindings?: unknown[]): Promise<ExecuteResult>;
-    /**
-     * Run a callback within a transaction
-     */
-    transaction<T>(callback: (connection: ConnectionContract) => Promise<T>): Promise<T>;
-    /**
-     * Stream query results for processing large datasets
-     * @param sql - SQL query
-     * @param bindings - Query parameters
-     * @returns Async iterable of result rows
-     */
-    stream<T = Record<string, unknown>>(sql: string, bindings?: unknown[]): AsyncIterable<T>;
-    /**
-     * Get connection pool statistics (if supported by driver)
-     * @returns Pool statistics or null if not supported
-     */
-    getPoolStats(): PoolStats | null;
-    /**
-     * Disconnect from the database
-     */
-    disconnect(): Promise<void>;
-    /**
-     * Connect to the database
-     */
-    connect(): Promise<void>;
-    /**
-     * Ensure connection is established
-     */
-    protected ensureConnected(): Promise<void>;
-    /**
-     * Create the driver instance based on config
-     * Automatically prefers Bun.sql native driver when available (unless explicitly disabled)
-     */
-    protected createDriver(): DriverContract;
-    /**
-     * Create the grammar instance based on config
-     */
-    protected createGrammar(): GrammarContract;
-}