@plyaz/db 0.0.0

package/dist/advanced/multi-tenancy/TenantRepository.d.ts

@@ -0,0 +1,292 @@
+import type { DatabaseAdapterType, DatabaseResult, PaginatedResult, QueryOptions } from "@plyaz/types/db";
+/**
+ * TENANT REPOSITORY - Multi-Tenant Database Operations
+ *
+ * Base repository that automatically handles tenant isolation for all database operations.
+ * Ensures data security by automatically filtering records by tenant ID and validating access.
+ *
+ * **RESPONSIBILITIES:**
+ * 1. Tenant Isolation - Automatically filters all queries by current tenant
+ * 2. Access Control - Validates tenant access for all operations
+ * 3. Auto-Assignment - Automatically assigns tenant ID on record creation
+ * 4. Validation - Ensures all operations respect tenant boundaries
+ *
+ * **USAGE PATTERN:**
+ * Extend this class for each entity that requires tenant isolation.
+ *
+ * @template TEntity - The entity type that includes a tenant ID field
+ *
+ * @example
+ * ### Basic Implementation
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ *   tenantId: string; // Required for tenant isolation
+ * }
+ *
+ * class UserRepository extends TenantRepository<User> {
+ *   constructor(adapter: DatabaseAdapterType) {
+ *     super(adapter, 'users');
+ *   }
+ *
+ *   protected getTenantIdField(): keyof User {
+ *     return 'tenantId';
+ *   }
+ *
+ *   // Custom methods with automatic tenant isolation
+ *   async findByEmail(email: string) {
+ *     return this.findMany({ filter: { field: 'email', operator: 'eq', value: email } });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ### Usage with Tenant Context
+ * ```typescript
+ * // Set tenant context (usually in middleware)
+ * TenantContext.set({ id: 'tenant-123', name: 'Acme Corp' });
+ *
+ * const userRepo = new UserRepository(adapter);
+ *
+ * // All operations automatically filtered by tenant
+ * const users = await userRepo.findMany(); // Only returns users for tenant-123
+ * const user = await userRepo.findById('user-456'); // Validates tenant access
+ *
+ * // New records automatically get tenant ID
+ * const newUser = await userRepo.create({
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ *   // tenantId automatically set to 'tenant-123'
+ * });
+ * ```
+ */
+export interface TenantContextType {
+    id: string;
+}
+export interface TenantValidationContext {
+    id: string;
+}
+export declare abstract class TenantRepository<TEntity extends object> {
+    protected adapter: DatabaseAdapterType;
+    protected tableName: string;
+    /**
+     * Creates a new tenant repository instance.
+     *
+     * @param adapter - Database adapter for operations
+     * @param tableName - Name of the database table
+     */
+    constructor(adapter: DatabaseAdapterType, tableName: string);
+    /**
+     * ABSTRACT METHOD - Tenant ID Field Specification
+     *
+     * Must be implemented by subclasses to specify which field contains the tenant ID.
+     * This field is used for automatic filtering and validation.
+     *
+     * @returns The key of the tenant ID field in the entity
+     *
+     * @example
+     * ```typescript
+     * protected getTenantIdField(): keyof User {
+     *   return 'tenantId'; // or 'organizationId', 'companyId', etc.
+     * }
+     * ```
+     */
+    protected abstract getTenantIdField(): keyof TEntity;
+    /**
+     * FIND BY ID - Tenant-Safe Record Retrieval
+     *
+     * Finds a single record by ID with automatic tenant access validation.
+     * Only returns records that belong to the current tenant.
+     *
+     * **SECURITY:** Validates that the found record belongs to the current tenant
+     * **BEHAVIOR:** Returns null if record doesn't exist or belongs to different tenant
+     *
+     * @param id - The unique identifier of the record to find
+     * @returns Promise resolving to the record or null if not found/no access
+     *
+     * @throws {DatabaseError} When ID is invalid or access is denied
+     *
+     * @example
+     * ```typescript
+     * // Set tenant context
+     * TenantContext.set({ id: 'tenant-123' });
+     *
+     * const userRepo = new UserRepository(adapter);
+     *
+     * // Find user - only returns if belongs to tenant-123
+     * const result = await userRepo.findById('user-456');
+     * if (result.success && result.value) {
+     *   console.log('User found:', result.value.name);
+     * } else {
+     *   console.log('User not found or access denied');
+     * }
+     * ```
+     */
+    findById(id: string): Promise<DatabaseResult<TEntity | null>>;
+    /**
+     * FIND MANY - Tenant-Filtered Query
+     *
+     * Finds multiple records with automatic tenant filtering applied.
+     * All results are guaranteed to belong to the current tenant.
+     *
+     * **SECURITY:** Automatically adds tenant filter to all queries
+     * **PERFORMANCE:** Uses database-level filtering for efficiency
+     *
+     * @param options - Optional query options (filters, sorting, pagination)
+     * @returns Promise resolving to paginated results for current tenant only
+     *
+     * @example
+     * ```typescript
+     * // Set tenant context
+     * TenantContext.set({ id: 'tenant-123' });
+     *
+     * const userRepo = new UserRepository(adapter);
+     *
+     * // Get all users for current tenant
+     * const allUsers = await userRepo.findMany();
+     *
+     * // Get active users with pagination
+     * const activeUsers = await userRepo.findMany({
+     *   filter: { field: 'status', operator: 'eq', value: 'active' },
+     *   pagination: { page: 1, limit: 10 },
+     *   sort: { field: 'name', direction: 'asc' }
+     * });
+     *
+     * // Results automatically filtered by tenantId = 'tenant-123'
+     * ```
+     */
+    findMany(options?: QueryOptions): Promise<DatabaseResult<PaginatedResult<TEntity>>>;
+    /**
+     * CREATE - Tenant-Safe Record Creation
+     *
+     * Creates a new record with automatic tenant ID assignment.
+     * The tenant ID is automatically set from the current tenant context.
+     *
+     * **SECURITY:** Automatically assigns current tenant ID to new records
+     * **CONVENIENCE:** No need to manually set tenant ID in application code
+     *
+     * @param entity - The entity data to create (tenant ID will be auto-assigned)
+     * @returns Promise resolving to the created record with tenant ID
+     *
+     * @example
+     * ```typescript
+     * // Set tenant context
+     * TenantContext.set({ id: 'tenant-123' });
+     *
+     * const userRepo = new UserRepository(adapter);
+     *
+     * // Create user - tenantId automatically set to 'tenant-123'
+     * const result = await userRepo.create({
+     *   name: 'John Doe',
+     *   email: 'john@example.com',
+     *   status: 'active'
+     *   // No need to set tenantId - automatically assigned
+     * });
+     *
+     * if (result.success) {
+     *   console.log('Created user:', result.value.id);
+     *   console.log('Tenant ID:', result.value.tenantId); // 'tenant-123'
+     * }
+     * ```
+     */
+    create(entity: Omit<TEntity, "id">): Promise<DatabaseResult<TEntity>>;
+    /**
+     * UPDATE - Tenant-Safe Record Update
+     *
+     * Updates an existing record with tenant access validation.
+     * Only allows updates to records that belong to the current tenant.
+     *
+     * **SECURITY:** Validates tenant access before allowing updates
+     * **SAFETY:** Prevents cross-tenant data modification
+     *
+     * @param id - The unique identifier of the record to update
+     * @param entity - Partial entity data with fields to update
+     * @returns Promise resolving to the updated record
+     *
+     * @throws {DatabaseError} When record not found, access denied, or invalid parameters
+     *
+     * @example
+     * ```typescript
+     * // Set tenant context
+     * TenantContext.set({ id: 'tenant-123' });
+     *
+     * const userRepo = new UserRepository(adapter);
+     *
+     * // Update user - only works if user belongs to tenant-123
+     * const result = await userRepo.update('user-456', {
+     *   name: 'Jane Doe',
+     *   email: 'jane@example.com'
+     * });
+     *
+     * if (result.success) {
+     *   console.log('Updated user:', result.value.name);
+     * } else {
+     *   console.log('Update failed:', result.error?.message);
+     * }
+     * ```
+     */
+    update(id: string, entity: Partial<TEntity>): Promise<DatabaseResult<TEntity>>;
+    /**
+     * DELETE - Tenant-Safe Record Deletion
+     *
+     * Deletes a record with tenant access validation.
+     * Only allows deletion of records that belong to the current tenant.
+     *
+     * **SECURITY:** Validates tenant access before allowing deletion
+     * **SAFETY:** Prevents cross-tenant data deletion
+     *
+     * @param id - The unique identifier of the record to delete
+     * @returns Promise resolving to void on successful deletion
+     *
+     * @throws {DatabaseError} When record not found, access denied, or invalid ID
+     *
+     * @example
+     * ```typescript
+     * // Set tenant context
+     * TenantContext.set({ id: 'tenant-123' });
+     *
+     * const userRepo = new UserRepository(adapter);
+     *
+     * // Delete user - only works if user belongs to tenant-123
+     * const result = await userRepo.delete('user-456');
+     *
+     * if (result.success) {
+     *   console.log('User deleted successfully');
+     * } else {
+     *   console.log('Delete failed:', result.error?.message);
+     * }
+     * ```
+     */
+    delete(id: string): Promise<DatabaseResult<void>>;
+    /**
+     * Validates that the entity is a valid object.
+     * @private
+     * @param entity - The entity to validate
+     * @throws {DatabaseError} When entity is invalid
+     */
+    private validateEntity;
+    /**
+     * Validates that tenant context exists and has an ID.
+     * @private
+     * @param tenant - The tenant context to validate
+     * @throws {DatabaseError} When tenant context is invalid
+     */
+    private validateTenantContext;
+    /**
+     * Validates that the entity has a tenant ID.
+     * @private
+     * @param tenantId - The tenant ID from the entity
+     * @throws {DatabaseError} When tenant ID is missing
+     */
+    private validateEntityTenantId;
+    /**
+     * Validates that the current tenant has access to the entity.
+     * @private
+     * @param entity - The entity to validate access for
+     * @throws {DatabaseError} When access is denied
+     */
+    private validateTenantAccess;
+}
+//# sourceMappingURL=TenantRepository.d.ts.map

package/dist/advanced/multi-tenancy/TenantRepository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TenantRepository.d.ts","sourceRoot":"","sources":["../../../src/advanced/multi-tenancy/TenantRepository.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,YAAY,EACb,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAEH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,8BAAsB,gBAAgB,CAAC,OAAO,SAAS,MAAM;IAQzD,SAAS,CAAC,OAAO,EAAE,mBAAmB;IACtC,SAAS,CAAC,SAAS,EAAE,MAAM;IAR7B;;;;;OAKG;gBAES,OAAO,EAAE,mBAAmB,EAC5B,SAAS,EAAE,MAAM;IAG7B;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,QAAQ,CAAC,gBAAgB,IAAI,MAAM,OAAO;IAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IA0CnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,QAAQ,CACZ,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,cAAc,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;IAiBpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAU3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,MAAM,CACV,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,GACvB,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAsDnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IA8DvD;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IActB;;;;;OAKG;IAEH,OAAO,CAAC,qBAAqB;IAc7B;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAc9B;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;CAkC7B"}

package/dist/advanced/multi-tenancy/index.d.ts

@@ -0,0 +1,3 @@
+export { TenantContext } from "./TenantContext";
+export { TenantRepository } from "./TenantRepository";
+//# sourceMappingURL=index.d.ts.map

package/dist/advanced/multi-tenancy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/advanced/multi-tenancy/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}