@gravito/ripple 4.0.3 → 5.0.0

package/dist/core/src/PlanetCore.d.ts

@@ -183,6 +183,12 @@ export declare class PlanetCore {
     private deferredProviders;
     private bootedProviders;
     private isShuttingDown;
+    /**
+     * Global shutdown timeout in milliseconds (D-10).
+     * If the entire shutdown sequence does not complete within this limit,
+     * a warning is logged and shutdown is force-completed so the process can exit.
+     */
+    private static readonly GLOBAL_SHUTDOWN_TIMEOUT;
     /**
      * Initialize observability asynchronously (metrics, tracing, Prometheus).
      * This is called from constructor but doesn't block initialization.

package/dist/core/src/events/CircuitBreaker.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Event-system CircuitBreaker — standalone copy.
+ *
+ * NOTE: This is intentionally NOT a re-export from @gravito/resilience
+ * to avoid a circular dependency (core <-> resilience):
+ *   @gravito/core -> @gravito/resilience (peerDep of resilience -> core)
+ *
+ * The canonical CB implementation lives in @gravito/resilience.
+ * Keep this file in sync manually if the canonical CB API changes.
+ *
+ * Per D-02 decision recorded in 17-RESEARCH.md.
+ */
 /**
  * Circuit Breaker state enum.
  * @public

package/dist/core/src/exceptions/AuthException.d.ts

@@ -0,0 +1,10 @@
+import { type ExceptionOptions } from './GravitoException';
+import { DomainException } from './DomainException';
+/**
+ * Abstract base class for authentication/authorization-related domain errors.
+ * Used by fortify and sentinel packages.
+ * @public
+ */
+export declare abstract class AuthException extends DomainException {
+    constructor(status: number, code: string, options?: ExceptionOptions);
+}

package/dist/core/src/exceptions/AuthenticationException.d.ts

@@ -1,8 +1,8 @@
-import { GravitoException } from './GravitoException';
+import { DomainException } from './DomainException';
 /**
  * Exception thrown when authentication fails.
  * @public
  */
-export declare class AuthenticationException extends GravitoException {
+export declare class AuthenticationException extends DomainException {
     constructor(message?: string);
 }

package/dist/core/src/exceptions/AuthorizationException.d.ts

@@ -1,8 +1,8 @@
-import { GravitoException } from './GravitoException';
+import { DomainException } from './DomainException';
 /**
  * Exception thrown when user is not authorized to perform an action.
  * @public
  */
-export declare class AuthorizationException extends GravitoException {
+export declare class AuthorizationException extends DomainException {
     constructor(message?: string);
 }

package/dist/core/src/exceptions/CacheException.d.ts

@@ -0,0 +1,9 @@
+import { InfrastructureException, type InfrastructureExceptionOptions } from './InfrastructureException';
+/**
+ * Abstract base class for cache/Redis-related infrastructure errors.
+ * All plasma error classes extend this instead of bare Error.
+ * @public
+ */
+export declare abstract class CacheException extends InfrastructureException {
+    constructor(status: number, code: string, options?: InfrastructureExceptionOptions);
+}

package/dist/core/src/exceptions/CircularDependencyException.d.ts

@@ -1,9 +1,10 @@
 import type { ServiceKey } from '../Container';
+import { SystemException } from './SystemException';
 /**
  * CircularDependencyException - Thrown when the container detects an infinite loop.
  *
  * @module @gravito/core
  */
-export declare class CircularDependencyException extends Error {
+export declare class CircularDependencyException extends SystemException {
     constructor(key: ServiceKey, stack: ServiceKey[]);
 }

package/dist/core/src/exceptions/ConfigurationException.d.ts

@@ -0,0 +1,9 @@
+import { type ExceptionOptions } from './GravitoException';
+import { SystemException } from './SystemException';
+/**
+ * Thrown when the framework encounters an invalid or missing configuration value.
+ * @public
+ */
+export declare class ConfigurationException extends SystemException {
+    constructor(message: string, options?: Omit<ExceptionOptions, 'message'>);
+}

package/dist/core/src/exceptions/DatabaseException.d.ts

@@ -0,0 +1,9 @@
+import { InfrastructureException, type InfrastructureExceptionOptions } from './InfrastructureException';
+/**
+ * Abstract base class for database-related infrastructure errors.
+ * All atlas error classes extend this instead of bare Error.
+ * @public
+ */
+export declare abstract class DatabaseException extends InfrastructureException {
+    constructor(status: number, code: string, options?: InfrastructureExceptionOptions);
+}

package/dist/core/src/exceptions/DomainException.d.ts

@@ -0,0 +1,9 @@
+import { type ExceptionOptions, GravitoException } from './GravitoException';
+/**
+ * Abstract base class for business logic / domain rule violations.
+ * Extend this for exceptions that represent a caller mistake (invalid input, constraint violation, etc.).
+ * @public
+ */
+export declare abstract class DomainException extends GravitoException {
+    constructor(status: number, code: string, options?: ExceptionOptions);
+}

package/dist/core/src/exceptions/InfrastructureException.d.ts

@@ -0,0 +1,17 @@
+import { type ExceptionOptions, GravitoException } from './GravitoException';
+/**
+ * Options for creating an InfrastructureException
+ * @public
+ */
+export interface InfrastructureExceptionOptions extends ExceptionOptions {
+    retryable?: boolean;
+}
+/**
+ * Abstract base class for infrastructure / I/O errors (database, network, filesystem, etc.).
+ * Carries a `retryable` flag that callers can inspect to decide whether the operation should be retried.
+ * @public
+ */
+export declare abstract class InfrastructureException extends GravitoException {
+    readonly retryable: boolean;
+    constructor(status: number, code: string, options?: InfrastructureExceptionOptions);
+}

package/dist/core/src/exceptions/QueueException.d.ts

@@ -0,0 +1,9 @@
+import { InfrastructureException, type InfrastructureExceptionOptions } from './InfrastructureException';
+/**
+ * Abstract base class for message queue infrastructure errors.
+ * Used by quasar and flux packages.
+ * @public
+ */
+export declare abstract class QueueException extends InfrastructureException {
+    constructor(status: number, code: string, options?: InfrastructureExceptionOptions);
+}

package/dist/core/src/exceptions/StorageException.d.ts

@@ -0,0 +1,9 @@
+import { InfrastructureException, type InfrastructureExceptionOptions } from './InfrastructureException';
+/**
+ * Abstract base class for file/object storage infrastructure errors.
+ * Used by constellation, nebula, nebula-s3, freeze, stasis packages.
+ * @public
+ */
+export declare abstract class StorageException extends InfrastructureException {
+    constructor(status: number, code: string, options?: InfrastructureExceptionOptions);
+}

package/dist/core/src/exceptions/StreamException.d.ts

@@ -0,0 +1,9 @@
+import { InfrastructureException, type InfrastructureExceptionOptions } from './InfrastructureException';
+/**
+ * Abstract base class for stream/message processing infrastructure errors.
+ * Used by the stream package (Kafka, RabbitMQ, SQS).
+ * @public
+ */
+export declare abstract class StreamException extends InfrastructureException {
+    constructor(status: number, code: string, options?: InfrastructureExceptionOptions);
+}

package/dist/core/src/exceptions/SystemException.d.ts

@@ -0,0 +1,9 @@
+import { type ExceptionOptions, GravitoException } from './GravitoException';
+/**
+ * Abstract base class for internal framework / system-level errors.
+ * Extend this for exceptions that represent an unexpected or unrecoverable framework state.
+ * @public
+ */
+export declare abstract class SystemException extends GravitoException {
+    constructor(status: number, code: string, options?: ExceptionOptions);
+}

package/dist/core/src/exceptions/ValidationException.d.ts

@@ -1,4 +1,4 @@
-import { GravitoException } from './GravitoException';
+import { DomainException } from './DomainException';
 /**
  * Structure of a validation error
  * @public
@@ -12,7 +12,7 @@ export interface ValidationError {
  * Exception thrown when data validation fails.
  * @public
  */
-export declare class ValidationException extends GravitoException {
+export declare class ValidationException extends DomainException {
     readonly errors: ValidationError[];
     redirectTo?: string;
     input?: unknown;

package/dist/core/src/exceptions/index.d.ts

@@ -1,7 +1,17 @@
 export * from './AuthenticationException';
+export * from './AuthException';
 export * from './AuthorizationException';
+export * from './CacheException';
 export * from './CircularDependencyException';
+export * from './ConfigurationException';
+export * from './DatabaseException';
+export * from './DomainException';
 export * from './GravitoException';
 export * from './HttpException';
+export * from './InfrastructureException';
 export * from './ModelNotFoundException';
+export * from './QueueException';
+export * from './StorageException';
+export * from './StreamException';
+export * from './SystemException';
 export * from './ValidationException';

package/dist/errors/RippleError.d.ts

@@ -3,25 +3,42 @@
  *
  * @module @gravito/ripple/errors
  */
+import { InfrastructureException, type InfrastructureExceptionOptions } from '@gravito/core';
+/**
+ * Error codes for Ripple module operations.
+ * Follows dot-separated namespace convention.
+ */
+export declare const RippleErrorCodes: {
+    readonly CONNECTION_FAILED: "ripple.connection_failed";
+    readonly QUERY_FAILED: "ripple.query_failed";
+    readonly DRIVER_ERROR: "ripple.driver_error";
+    readonly UNSUPPORTED_RUNTIME: "ripple.unsupported_runtime";
+    readonly NOT_INITIALIZED: "ripple.not_initialized";
+    readonly INVALID_OPERATION: "ripple.invalid_operation";
+    readonly SERIALIZATION_FAILED: "ripple.serialization_failed";
+    readonly MIDDLEWARE_ERROR: "ripple.middleware_error";
+};
+export type RippleErrorCode = (typeof RippleErrorCodes)[keyof typeof RippleErrorCodes];
 /**
  * Base error class for Ripple module.
  *
  * Provides structured error handling with error codes and messages.
+ * Extends InfrastructureException for unified error handling across Gravito.
  *
  * @example
  * ```typescript
- * throw new RippleError('INVALID_FORMAT', 'Invalid message format')
+ * throw new RippleError('ripple.invalid_format', 'Invalid message format')
  * ```
  */
-export declare class RippleError extends Error {
-    readonly code: string;
+export declare class RippleError extends InfrastructureException {
     /**
      * Creates a new RippleError instance.
      *
      * @param code - The error code.
      * @param message - The error message.
+     * @param options - Optional infrastructure exception options.
      */
-    constructor(code: string, message: string);
+    constructor(code: string, message: string, options?: InfrastructureExceptionOptions);
 }
 /**
  * Error class for driver-related issues.
@@ -43,6 +60,7 @@ export declare class RippleDriverError extends RippleError {
      *
      * @param code - The error code.
      * @param message - The error message.
+     * @param options - Optional infrastructure exception options.
      */
-    constructor(code: string, message: string);
+    constructor(code: string, message: string, options?: InfrastructureExceptionOptions);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gravito/ripple",
   "sideEffects": false,
-  "version": "4.0.3",
+  "version": "5.0.0",
   "description": "Bun-native WebSocket broadcasting for Gravito. Channel-based real-time communication.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -46,7 +46,7 @@
   },
   "homepage": "https://github.com/gravito-framework/gravito#readme",
   "peerDependencies": {
-    "@gravito/core": "^2.0.0",
+    "@gravito/core": "^3.0.0",
     "ioredis": "^5.0.0",
     "nats": "^2.23.0",
     "protobufjs": "^8.0.0",