@hiliosai/sdk 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiliosai/sdk",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"

package/src/datasources/base.datasource.ts

@@ -1,13 +1,29 @@
+import type {ServiceBroker} from 'moleculer';
+
+import type {AppContext} from '../types/context';
+
 /**
  * Base datasource interface that all datasources should implement
  * Provides common structure and optional lifecycle methods
  */
-export interface BaseDatasource {
+export interface BaseDatasource<TContext = AppContext> {
   /**
    * Datasource name for identification and logging
    */
   readonly name: string;
 
+  /**
+   * Service broker instance for logging, events, and service calls
+   * Always available after datasource initialization
+   */
+  broker: ServiceBroker;
+
+  /**
+   * Current service context (only available during action execution)
+   * Will be undefined in lifecycle hooks or background tasks
+   */
+  context?: TContext;
+
   /**
    * Optional initialization method
    * Called when datasource is instantiated
@@ -48,24 +64,40 @@ export interface BaseDatasource {
  *   private users: User[] = [];
  *
  *   async findById(id: string): Promise<User | undefined> {
+ *     this.broker?.logger.info('Finding user by ID:', id);
  *     return this.users.find(u => u.id === id);
  *   }
  *
- *   async create(user: User): Promise<User> {
- *     this.users.push(user);
- *     return user;
+ *   async healthCheck(): Promise<boolean> {
+ *     this.broker?.logger.info('Health check for datasource', this.name);
+ *     return true;
  *   }
  * }
  * ```
  */
-export abstract class AbstractDatasource implements BaseDatasource {
+export abstract class AbstractDatasource<TContext = AppContext>
+  implements BaseDatasource<TContext>
+{
   abstract readonly name: string;
 
+  /**
+   * Service broker instance - injected by mixin
+   * Always available after initialization
+   */
+  broker!: ServiceBroker; // Using definite assignment assertion since it's injected
+
+  /**
+   * Current service context - injected per action
+   * Only available during action execution
+   */
+  context?: TContext;
+
   /**
    * Default health check - always returns true
    * Override for custom health check logic
    */
   async healthCheck(): Promise<boolean> {
+    this.broker.logger.info(`Health check for datasource - ${this.name}`);
     return true;
   }
 

package/src/datasources/extensions/index.ts

@@ -0,0 +1,11 @@
+// Export all Prisma extensions for easy importing
+export { softDeleteExtension } from './soft-delete.extension';
+export { createTenantExtension } from './tenant.extension';
+export { retryExtension } from './retry.extension';
+
+// Re-export extension interfaces
+export type {
+  SoftDeleteExtension,
+  AuditTrailExtension,
+  TenantExtension,
+} from '../prisma.datasource';

package/src/datasources/extensions/retry.extension.ts

@@ -0,0 +1,91 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Retry Extension for Prisma Transactions
+ * Automatically retries failed transactions with exponential backoff
+ *
+ * Usage:
+ * ```typescript
+ * import { retryExtension } from './extensions/retry.extension';
+ *
+ * class MyPrismaDS extends PrismaDatasource<PrismaClient> {
+ *   protected applyExtensions(client: PrismaClient) {
+ *     return client.$extends(retryExtension);
+ *   }
+ * }
+ * ```
+ */
+
+export const retryExtension = {
+  name: 'Retry',
+
+  client: {
+    async $retryTransaction<T>(
+      fn: (tx: any) => Promise<T>,
+      options: {
+        maxRetries?: number;
+        baseDelay?: number;
+        maxDelay?: number;
+        retryableErrors?: string[];
+      } = {}
+    ): Promise<T> {
+      const {
+        maxRetries = 3,
+        baseDelay = 100,
+        maxDelay = 5000,
+        retryableErrors = [
+          'P2034', // Transaction failed due to a write conflict
+          'P2002', // Unique constraint failed
+          'P5000', // Raw query failed
+        ],
+      } = options;
+
+      let lastError: Error | undefined;
+
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+          return await (this as any).$transaction(fn, {
+            timeout: 10000,
+            maxWait: 5000,
+          });
+        } catch (error: any) {
+          lastError = error;
+
+          // Check if error is retryable
+          const isRetryable = retryableErrors.some(
+            (code) => error.code === code || error.message?.includes(code)
+          );
+
+          if (!isRetryable || attempt === maxRetries) {
+            throw error;
+          }
+
+          // Calculate delay with exponential backoff and jitter
+          const delay = Math.min(
+            baseDelay * Math.pow(2, attempt) + Math.random() * 100,
+            maxDelay
+          );
+
+          // Log retry attempt (in production, use proper logger)
+          if (
+            typeof globalThis !== 'undefined' &&
+            (globalThis as any).console
+          ) {
+            (globalThis as any).console.warn(
+              `Transaction retry ${
+                attempt + 1
+              }/${maxRetries} after ${delay}ms:`,
+              {
+                error: error.message,
+                code: error.code,
+              }
+            );
+          }
+
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+
+      throw lastError ?? new Error('Transaction failed after maximum retries');
+    },
+  },
+};

package/src/datasources/extensions/soft-delete.extension.ts

@@ -0,0 +1,113 @@
+/**
+ * Soft Delete Extension for Prisma
+ * Automatically handles soft deletes by setting deletedAt instead of removing records
+ *
+ * Usage:
+ * ```typescript
+ * import { softDeleteExtension } from './extensions/soft-delete.extension';
+ *
+ * class MyPrismaDS extends PrismaDatasource<PrismaClient> {
+ *   protected applyExtensions(client: PrismaClient) {
+ *     return client.$extends(softDeleteExtension);
+ *   }
+ * }
+ * ```
+ *
+ * Requires models to have `deletedAt DateTime?` field
+ */
+
+export const softDeleteExtension = {
+  name: 'SoftDelete',
+
+  query: {
+    // Apply to all models
+    $allModels: {
+      // Override findMany to exclude soft deleted records
+      async findMany({args, query}: any) {
+        // Add deletedAt: null filter if not already specified
+        args.where ??= {};
+        if (args.where.deletedAt === undefined) {
+          args.where.deletedAt = null;
+        }
+        return query(args);
+      },
+
+      // Override findUnique to exclude soft deleted records
+      async findUnique({args, query}: any) {
+        args.where ??= {};
+        if (args.where.deletedAt === undefined) {
+          args.where.deletedAt = null;
+        }
+        return query(args);
+      },
+
+      // Override findFirst to exclude soft deleted records
+      async findFirst({args, query}: any) {
+        args.where ??= {};
+        if (args.where.deletedAt === undefined) {
+          args.where.deletedAt = null;
+        }
+        return query(args);
+      },
+
+      // Override delete to set deletedAt instead
+      async delete({args, query}: any) {
+        return query({
+          ...args,
+          data: {deletedAt: new Date()},
+        });
+      },
+
+      // Override deleteMany to set deletedAt instead
+      async deleteMany({args, query}: any) {
+        return query({
+          ...args,
+          data: {deletedAt: new Date()},
+        });
+      },
+    },
+  },
+
+  model: {
+    $allModels: {
+      // Add restore method to all models
+      async restore<T>(this: T, where: any): Promise<any> {
+        const context =
+          (globalThis as any).Prisma?.getExtensionContext?.(this) ?? this;
+
+        return (context as any).update({
+          where,
+          data: {deletedAt: null},
+        });
+      },
+
+      // Add findWithDeleted method to include soft deleted records
+      async findWithDeleted<T>(this: T, args: any): Promise<any> {
+        const context =
+          (globalThis as any).Prisma?.getExtensionContext?.(this) ?? this;
+
+        return (context as any).findMany({
+          ...args,
+          where: {
+            ...args.where,
+            // Don't filter by deletedAt
+          },
+        });
+      },
+
+      // Add findDeleted method to find only soft deleted records
+      async findDeleted<T>(this: T, args: any): Promise<any> {
+        const context =
+          (globalThis as any).Prisma?.getExtensionContext?.(this) ?? this;
+
+        return (context as any).findMany({
+          ...args,
+          where: {
+            ...args.where,
+            deletedAt: {not: null},
+          },
+        });
+      },
+    },
+  },
+};

package/src/datasources/extensions/tenant.extension.ts

@@ -0,0 +1,104 @@
+/**
+ * Multi-Tenant Extension for Prisma
+ * Automatically filters queries by tenant context for multi-tenant applications
+ * 
+ * Usage:
+ * ```typescript
+ * import { createTenantExtension } from './extensions/tenant.extension';
+ * 
+ * class MyPrismaDS extends PrismaDatasource<PrismaClient> {
+ *   protected applyExtensions(client: PrismaClient) {
+ *     return client.$extends(createTenantExtension());
+ *   }
+ * }
+ * ```
+ * 
+ * Requires models to have `tenantId String` field
+ */
+
+interface TenantContext {
+  currentTenantId: string | null;
+}
+
+export function createTenantExtension() {
+  const tenantContext: TenantContext = {
+    currentTenantId: null,
+  };
+
+  return {
+    name: 'Tenant',
+    
+    client: {
+      // Set tenant context
+      $setTenant(tenantId: string) {
+        tenantContext.currentTenantId = tenantId;
+      },
+      
+      // Get current tenant
+      $getCurrentTenant() {
+        return tenantContext.currentTenantId;
+      },
+      
+      // Clear tenant context
+      $clearTenant() {
+        tenantContext.currentTenantId = null;
+      },
+    },
+    
+    query: {
+      $allModels: {
+        // Automatically add tenantId filter to all read operations
+        async findMany({ args, query }: any) {
+          if (tenantContext.currentTenantId) {
+            args.where ??= {};
+            args.where.tenantId ??= tenantContext.currentTenantId;
+          }
+          return query(args);
+        },
+        
+        async findUnique({ args, query }: any) {
+          if (tenantContext.currentTenantId) {
+            args.where ??= {};
+            args.where.tenantId ??= tenantContext.currentTenantId;
+          }
+          return query(args);
+        },
+        
+        async findFirst({ args, query }: any) {
+          if (tenantContext.currentTenantId) {
+            args.where ??= {};
+            args.where.tenantId ??= tenantContext.currentTenantId;
+          }
+          return query(args);
+        },
+        
+        // Automatically add tenantId to create operations
+        async create({ args, query }: any) {
+          if (tenantContext.currentTenantId) {
+            args.data ??= {};
+            args.data.tenantId ??= tenantContext.currentTenantId;
+          }
+          return query(args);
+        },
+        
+        // Add tenantId filter to update operations
+        async update({ args, query }: any) {
+          if (tenantContext.currentTenantId) {
+            args.where ??= {};
+            args.where.tenantId ??= tenantContext.currentTenantId;
+          }
+          return query(args);
+        },
+        
+        // Add tenantId filter to delete operations
+        async delete({ args, query }: any) {
+          if (tenantContext.currentTenantId) {
+            args.where ??= {};
+            args.where.tenantId ??= tenantContext.currentTenantId;
+          }
+          return query(args);
+        },
+      },
+    },
+  };
+}

package/src/datasources/index.ts

@@ -1 +1,3 @@
 export * from './base.datasource';
+export * from './prisma.datasource';
+export * from './extensions';

package/src/datasources/prisma.datasource.ts

@@ -0,0 +1,325 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import {isDev, isTest} from '../env';
+import type {AppContext} from '../types/context';
+import {AbstractDatasource} from './base.datasource';
+
+// Generic Prisma Client interface - will be provided by generated client
+interface PrismaClientLike {
+  $connect(): Promise<void>;
+  $disconnect(): Promise<void>;
+  $queryRaw(
+    query: TemplateStringsArray,
+    ...values: unknown[]
+  ): Promise<unknown>;
+  $transaction<T>(
+    fn: (client: PrismaClientLike) => Promise<T>,
+    options?: {
+      maxWait?: number;
+      timeout?: number;
+    }
+  ): Promise<T>;
+  $extends<T>(extension: T): PrismaClientLike & T;
+  [key: string]: unknown;
+}
+
+// Extension interfaces for common production patterns
+export interface SoftDeleteExtension {
+  // Adds soft delete functionality to models
+  softDelete: {
+    [model: string]: {
+      delete: (args: any) => Promise<any>;
+      deleteMany: (args: any) => Promise<any>;
+      restore: (args: any) => Promise<any>;
+    };
+  };
+}
+
+export interface AuditTrailExtension {
+  // Adds audit trail functionality
+  $auditTrail: {
+    getHistory: (model: string, id: string) => Promise<any[]>;
+    getChanges: (
+      model: string,
+      id: string,
+      from?: Date,
+      to?: Date
+    ) => Promise<any[]>;
+  };
+}
+
+export interface TenantExtension {
+  // Adds multi-tenant filtering
+  $tenant: {
+    setContext: (tenantId: string) => void;
+    getCurrentTenant: () => string | null;
+  };
+}
+
+// Global singleton pattern for Prisma Client
+declare global {
+  var __prisma: PrismaClientLike | undefined;
+}
+
+/**
+ * Prisma datasource that follows singleton pattern and best practices
+ * Supports both provided client instances and automatic initialization
+ *
+ * @example
+ * ```typescript
+ * // Option 1: Let datasource create singleton client
+ * datasources: {
+ *   prisma: PrismaDatasource
+ * }
+ *
+ * // Option 2: Provide custom client
+ * const customClient = new PrismaClient({...});
+ * datasources: {
+ *   prisma: () => new PrismaDatasource(customClient)
+ * }
+ * ```
+ */
+export class PrismaDatasource<
+  TPrismaClient extends PrismaClientLike = PrismaClientLike,
+  TContext = AppContext
+> extends AbstractDatasource<TContext> {
+  readonly name = 'prisma';
+  private _client: TPrismaClient | null = null;
+  private providedClient: TPrismaClient | null = null;
+
+  constructor(prismaClient?: TPrismaClient) {
+    super();
+    this.providedClient = prismaClient ?? null;
+  }
+
+  /**
+   * Get Prisma client instance (singleton pattern)
+   */
+  get client(): TPrismaClient {
+    this._client ??= this.initializePrismaClient();
+
+    // Update tenant context from current service context
+    this.updateTenantFromContext();
+
+    return this._client;
+  }
+
+  /**
+   * Initialize Prisma client using singleton pattern or provided instance
+   */
+  private initializePrismaClient(): TPrismaClient {
+    // Option 1: Use provided client instance
+    if (this.providedClient) {
+      this.broker.logger.info('Using provided PrismaClient instance');
+      return this.providedClient;
+    }
+
+    // Option 2: Use global singleton (recommended for most cases)
+    if (!globalThis.__prisma) {
+      this.broker.logger.info('Creating new PrismaClient singleton');
+      const baseClient = this.createClient();
+      globalThis.__prisma = this.applyExtensions(baseClient);
+    } else {
+      this.broker.logger.info('Using existing PrismaClient singleton');
+    }
+
+    return globalThis.__prisma as TPrismaClient;
+  }
+
+  /**
+   * Create a new Prisma client instance
+   * Override this method in subclasses to provide the actual PrismaClient
+   */
+  protected createClient(): TPrismaClient {
+    throw new Error(
+      'createClient() must be implemented by subclass or provide PrismaClient in constructor. ' +
+        'Example: class MyPrismaDataSource extends PrismaDatasource { ' +
+        'protected createClient() { return new PrismaClient(); } }'
+    );
+  }
+
+  /**
+   * Apply extensions to the Prisma client
+   * Override this method to add production extensions like soft delete, audit trails, etc.
+   */
+  protected applyExtensions(client: TPrismaClient): TPrismaClient {
+    // Base implementation returns client as-is
+    // Override in subclass to add extensions:
+    // return client.$extends(softDeleteExtension).$extends(auditExtension)
+    return client;
+  }
+
+  /**
+   * Get extended client with all applied extensions
+   */
+  get extendedClient(): TPrismaClient {
+    return this.applyExtensions(this.client);
+  }
+
+  /**
+   * Initialize datasource - called after broker injection
+   */
+  async init(): Promise<void> {
+    this.broker.logger.info('Initializing Prisma datasource');
+  }
+
+  /**
+   * Called automatically when context is injected
+   * Sets tenant context from service context if available
+   */
+  private updateTenantFromContext(): void {
+    const tenantId = (this.context as any)?.meta?.tenantId;
+    if (tenantId && typeof tenantId === 'string') {
+      this.setTenantContext(tenantId);
+    }
+  }
+
+  /**
+   * Connect to database - called when service starts
+   */
+  async connect(): Promise<void> {
+    try {
+      this.broker.logger.info('Connecting to database via Prisma');
+      await this.client.$connect();
+      this.broker.logger.info('Successfully connected to database');
+    } catch (error) {
+      this.broker.logger.error('Failed to connect to database:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Disconnect from database - called when service stops
+   */
+  async disconnect(): Promise<void> {
+    try {
+      this.broker.logger.info('Disconnecting from database');
+      await this.client.$disconnect();
+      this.broker.logger.info('Successfully disconnected from database');
+    } catch (error) {
+      this.broker.logger.error('Error disconnecting from database:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Health check - verify database connectivity
+   */
+  async healthCheck(): Promise<boolean> {
+    try {
+      this.broker.logger.info('Running Prisma health check');
+
+      // Simple connectivity test
+      await this.client.$queryRaw`SELECT 1`;
+
+      this.broker.logger.info('Prisma health check passed');
+      return true;
+    } catch (error) {
+      this.broker.logger.error('Prisma health check failed:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Clear/reset data - useful for testing
+   */
+  async clear(): Promise<void> {
+    if (isTest || isDev) {
+      this.broker.logger.warn(
+        'Clearing database (only allowed in test/dev mode)'
+      );
+
+      // Get all model names dynamically
+      const modelNames = Object.keys(this.client).filter(
+        (key) => !key.startsWith('_') && !key.startsWith('$')
+      );
+
+      // Delete all data in reverse order (to handle foreign keys)
+      for (const modelName of modelNames.reverse()) {
+        try {
+          const model = this.client[modelName as keyof TPrismaClient] as {
+            deleteMany?: () => Promise<unknown>;
+          };
+          if (model.deleteMany) {
+            await model.deleteMany();
+          }
+        } catch (error) {
+          // Some models might not support deleteMany, skip them
+          this.broker.logger.debug(`Could not clear ${modelName}:`, error);
+        }
+      }
+    } else {
+      throw new Error(
+        'Database clear is only allowed in test/development environments'
+      );
+    }
+  }
+
+  /**
+   * Transaction wrapper with proper error handling
+   */
+  async transaction<T>(
+    fn: (tx: TPrismaClient) => Promise<T>,
+    options?: {
+      maxWait?: number;
+      timeout?: number;
+    }
+  ): Promise<T> {
+    try {
+      return await this.client.$transaction(
+        (tx) => fn(tx as TPrismaClient),
+        options
+      );
+    } catch (error) {
+      this.broker.logger.error('Transaction failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Set tenant context for multi-tenant applications
+   * Requires tenant extension to be applied
+   */
+  setTenantContext(tenantId: string): void {
+    const tenantClient = this.client as any;
+    if (tenantClient.$setTenant) {
+      tenantClient.$setTenant(tenantId);
+      this.broker.logger.debug('Tenant context set:', {tenantId});
+    } else {
+      this.broker.logger.warn(
+        'Tenant extension not available - setTenantContext ignored'
+      );
+    }
+  }
+
+  /**
+   * Get current tenant context
+   */
+  getCurrentTenant(): string | null {
+    const tenantClient = this.client as any;
+    if (tenantClient.$getCurrentTenant) {
+      return tenantClient.$getCurrentTenant();
+    }
+    return null;
+  }
+
+  /**
+   * Execute with tenant context (automatically restores previous context)
+   */
+  async withTenant<T>(tenantId: string, fn: () => Promise<T>): Promise<T> {
+    const previousTenant = this.getCurrentTenant();
+
+    try {
+      this.setTenantContext(tenantId);
+      return await fn();
+    } finally {
+      if (previousTenant) {
+        this.setTenantContext(previousTenant);
+      } else {
+        const tenantClient = this.client as any;
+        if (tenantClient.$clearTenant) {
+          tenantClient.$clearTenant();
+        }
+      }
+    }
+  }
+}

package/src/index.ts

@@ -4,3 +4,5 @@ export * from './service/define-integration';
 export * from './types';
 export * from './configs';
 export * from './env';
+export * from './datasources';
+export * from './mixins';

package/src/mixins/datasource.mixin.ts

@@ -1,23 +1,11 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import type {ServiceSchema} from 'moleculer';
-import type {BaseDatasource} from '../datasources';
+import type {
+  DatasourceConstructorRegistry,
+  DatasourceInstanceRegistry,
+} from '../middlewares/datasource.middleware';
 import type {AppContext} from '../types/context';
 
-/**
- * Datasource constructor registry type
- * All datasources should implement BaseDatasource interface
- */
-export interface DatasourceConstructorRegistry {
-  [key: string]: new () => BaseDatasource | object;
-}
-
-/**
- * Datasource instance registry type
- */
-export interface DatasourceInstanceRegistry {
-  [key: string]: object;
-}
-
 /**
  * Creates a Moleculer mixin for datasource injection
  * Simple mixin that just instantiates datasources and injects them into context
@@ -59,6 +47,11 @@ export function DatasourceMixin(
      * Initialize datasources and store on service
      */
     async created() {
+      // Inject broker into datasources
+      for (const [, datasource] of Object.entries(datasourceInstances)) {
+        (datasource as any).broker = this.broker;
+      }
+
       // Call init() on datasources that have it
       for (const [, datasource] of Object.entries(datasourceInstances)) {
         if (typeof (datasource as any).init === 'function') {
@@ -102,17 +95,17 @@ export function DatasourceMixin(
     hooks: {
       before: {
         '*': function injectDatasources(ctx) {
+          const datasources = (this as any).$datasources ?? {};
+
+          // Inject current context into all datasources
+          for (const [, datasource] of Object.entries(datasources)) {
+            (datasource as any).context = ctx;
+          }
+
           // Inject datasources into the context
-          (ctx as AppContext).datasources = (this as any).$datasources ?? {};
+          (ctx as AppContext).datasources = datasources;
         },
       },
     },
   };
 }
-
-/**
- * Type helper for services that use the datasource mixin
- */
-export type ServiceWithDatasources<T extends DatasourceInstanceRegistry> = {
-  datasources: T;
-};