@baasix/baasix 0.1.0

package/dist/services/ItemsService.d.ts

@@ -0,0 +1,273 @@
+import type { QueryOptions as BaseQueryOptions, ServiceParams as BaseServiceParams, OperationOptions, ReadResult } from '../types/index.js';
+export type QueryOptions = BaseQueryOptions;
+export type ServiceParams = BaseServiceParams;
+export type { ReadResult, OperationOptions };
+/**
+ * ItemsService - Core CRUD service for all collections
+ *
+ * Provides:
+ * - Read operations with filters, sorting, pagination, includes
+ * - Create/Update/Delete operations with relation handling
+ * - Permission enforcement and field-level security
+ * - Multi-tenancy support
+ * - Lifecycle hooks integration
+ * - Soft-delete handling
+ */
+export declare class ItemsService {
+    private collection;
+    private accountability?;
+    private tenant?;
+    private table;
+    private primaryKey;
+    private isMultiTenant;
+    constructor(collection: string, params?: ServiceParams);
+    /**
+     * Get primary key column from table (with type safety)
+     */
+    private getPrimaryKeyColumn;
+    /**
+     * Parse ID to correct type (string or number)
+     */
+    private parseId;
+    /**
+     * Extract all table names involved in a query (including relations)
+     * This is CRITICAL for proper cache invalidation
+     */
+    private extractAllTables;
+    /**
+     * Get all involved tables from processed includes
+     * Used for cache invalidation tracking
+     */
+    private getInvolvedTables;
+    /**
+     * Generate cache key from query parameters
+     */
+    private generateCacheKey;
+    /**
+     * Execute query with cache wrapper
+     * Checks cache before querying, stores results after query
+     */
+    private executeWithCache;
+    /**
+     * Invalidate cache for this collection and all related tables
+     * Called after any mutation (create, update, delete)
+     */
+    private invalidateCache;
+    /**
+     * Get role ID from accountability
+     * The auth middleware should always set role.id from the database
+     */
+    private getRoleId;
+    /**
+     * Check if user is administrator
+     */
+    private isAdministrator;
+    /**
+     * Apply tenant context to query filter
+     */
+    private enforceTenantContextFilter;
+    /**
+     * Validate and enforce tenant context on data
+     */
+    private validateAndEnforceTenantContext;
+    /**
+     * Helper to apply nested joins recursively
+     */
+    private applyNestedJoins;
+    /**
+     * Filter relational field attributes based on permission allowed fields
+     *
+     * When a user has permission to access only specific relational fields like:
+     *   - members.id
+     *   - members.fullName
+     *
+     * And they request "members.*", this method ensures only the allowed fields
+     * are included in the query, not all fields from the related table.
+     *
+     * @param processedIncludes - The expanded includes from expandFieldsWithIncludes
+     * @param allowedFields - The allowed fields from permissions (e.g., ['id', 'name', 'members.id', 'members.fullName'])
+     * @param parentPath - The current path prefix for nested relations
+     */
+    private filterIncludesByAllowedFields;
+    /**
+     * Build complete query with filters, sorts, pagination, includes
+     */
+    private buildQuery;
+    /**
+     * Sanitize records by removing auto-added fields that user didn't request
+     * This includes both main collection fields and nested relation fields
+     *
+     * @param records - Records to sanitize
+     * @param userRequestedFields - Expanded direct fields requested by user (before auto-adding primary key)
+     * @param userRequestedIncludes - ProcessedIncludes containing relation field info
+     */
+    private sanitizeAutoAddedFields;
+    /**
+     * Apply field-level permissions
+     */
+    private applyFieldPermissions;
+    /**
+     * Get default values from permissions
+     */
+    private getDefaultValues;
+    /**
+     * Read with two-query approach for HasMany sorting
+     */
+    private readWithHasManyHandling;
+    /**
+     * Check if we need two-query approach for sorting by HasMany relations
+     */
+    private needsHasManyHandling;
+    /**
+     * Read records by query
+     */
+    readByQuery(query?: QueryOptions, bypassPermissions?: boolean): Promise<ReadResult>;
+    /**
+     * Execute aggregate query
+     */
+    private executeAggregateQuery;
+    /**
+     * Read a single record by ID
+     */
+    readOne(id: string | number, query?: QueryOptions, bypassPermissions?: boolean): Promise<any>;
+    /**
+     * Create a new record
+     * Uses createOneCore for the transactional logic and executes after hooks after commit
+     */
+    createOne(data: Record<string, any>, options?: OperationOptions): Promise<string | number>;
+    /**
+     * Internal method to perform core create logic without after hooks
+     * Used by both createOne and createMany to separate transactional data operations
+     * from after hooks that may have side effects (emails, third-party calls)
+     *
+     * @param data - Item data to create
+     * @param transaction - Transaction to use
+     * @param options - Operation options
+     * @returns Object containing item ID, document, modified data, and related tables for cache invalidation
+     */
+    private createOneCore;
+    /**
+     * Create multiple records with transactional safety
+     *
+     * This method ensures that:
+     * 1. All items are created within a single transaction
+     * 2. If any creation fails, all previous creations are rolled back
+     * 3. After hooks (which may have external side effects like emails, API calls)
+     *    are only executed AFTER the transaction is successfully committed
+     *
+     * This prevents situations where:
+     * - Emails are sent for items that were later rolled back
+     * - Third-party systems are notified about changes that didn't persist
+     *
+     * @param items - Array of items to create
+     * @param options - Operation options
+     * @returns Array of created item IDs
+     */
+    createMany(items: Record<string, any>[], options?: OperationOptions): Promise<(string | number)[]>;
+    /**
+     * Internal method to perform core update logic without after hooks
+     * Used by both updateOne and updateMany to separate transactional data operations
+     * from after hooks that may have side effects (emails, third-party calls)
+     *
+     * @param id - Item ID to update
+     * @param data - Item data to update
+     * @param transaction - Transaction to use
+     * @param options - Operation options
+     * @returns Object containing update info for after hooks execution
+     */
+    private updateOneCore;
+    /**
+     * Update multiple records with transactional safety
+     *
+     * This method ensures that:
+     * 1. All items are updated within a single transaction
+     * 2. If any update fails, all previous updates are rolled back
+     * 3. After hooks (which may have external side effects like emails, API calls)
+     *    are only executed AFTER the transaction is successfully committed
+     *
+     * @param updates - Array of objects with id and data to update
+     * @param options - Operation options
+     * @returns Array of updated item IDs
+     */
+    updateMany(updates: {
+        id: string | number;
+        data?: Record<string, any>;
+        [key: string]: any;
+    }[], options?: OperationOptions): Promise<(string | number)[]>;
+    /**
+     * Update a record by ID
+     * Uses updateOneCore for the transactional logic and executes after hooks after commit
+     */
+    updateOne(id: string | number, data: Record<string, any>, options?: OperationOptions): Promise<string | number>;
+    /**
+     * Internal method to perform core delete logic without after hooks
+     * Used by both deleteOne and deleteMany to separate transactional data operations
+     * from after hooks that may have side effects (emails, third-party calls)
+     *
+     * @param id - Item ID to delete
+     * @param transaction - Transaction to use
+     * @param options - Operation options
+     * @returns Object containing delete info for after hooks execution
+     */
+    private deleteOneCore;
+    /**
+     * Delete multiple records with transactional safety
+     *
+     * This method ensures that:
+     * 1. All items are deleted within a single transaction
+     * 2. If any deletion fails, all previous deletions are rolled back
+     * 3. After hooks (which may have external side effects like emails, API calls)
+     *    are only executed AFTER the transaction is successfully committed
+     *
+     * @param ids - Array of item IDs to delete
+     * @param options - Operation options
+     * @returns Array of deleted item IDs
+     */
+    deleteMany(ids: (string | number)[], options?: OperationOptions): Promise<(string | number)[]>;
+    /**
+     * Delete a record by ID
+     * Uses deleteOneCore for the transactional logic and executes after hooks after commit
+     */
+    deleteOne(id: string | number, options?: OperationOptions): Promise<string | number>;
+    /**
+     * Alias for readByQuery
+     */
+    list(query?: QueryOptions, bypassPermissions?: boolean): Promise<ReadResult>;
+    /**
+     * Alias for readOne
+     */
+    read(id: string | number, query?: QueryOptions, bypassPermissions?: boolean): Promise<any>;
+    /**
+     * Alias for createOne
+     */
+    create(data: Record<string, any>, options?: OperationOptions): Promise<string | number>;
+    /**
+     * Alias for updateOne
+     */
+    update(id: string | number, data: Record<string, any>, options?: OperationOptions): Promise<string | number>;
+    /**
+     * Alias for deleteOne
+     */
+    delete(id: string | number, options?: OperationOptions): Promise<string | number>;
+    /**
+     * Restore a soft-deleted record
+     * Only works for collections with paranoid mode enabled
+     */
+    restore(id: string | number, options?: OperationOptions): Promise<string | number>;
+    /**
+     * Create an audit log entry for create/update/delete operations
+     * @param action - The action performed (create, update, delete)
+     * @param entityId - The ID of the entity
+     * @param changes - The changes made (before and after states)
+     * @param transaction - Optional transaction to use
+     */
+    private createAuditLog;
+    /**
+     * Convert date string fields to Date objects for DateTime/Timestamp fields
+     * This is needed because Drizzle expects Date objects for timestamp columns
+     * Note: Date type (date-only) expects strings, not Date objects
+     */
+    private convertDateFields;
+}
+export default ItemsService;
+//# sourceMappingURL=ItemsService.d.ts.map

package/dist/services/ItemsService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ItemsService.d.ts","sourceRoot":"","sources":["../../baasix/services/ItemsService.ts"],"names":[],"mappings":"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"}