Refactor Core Operations to Use withMetadata for Centralized Metadata Management

[teles]

Improve the HolySheets! library by introducing a withMetadata higher-order function to centralize metadata handling across all core operations (e.g., findFirst, findMany, updateFirst). This refactoring aims to enhance maintainability, readability, and consistency while adhering to SOLID principles.

Background

Currently, each core operation manages its own metadata logic, leading to code duplication and reduced clarity. Centralizing this functionality will streamline the codebase and ensure uniform metadata management.

Proposed Changes

1. Create withMetadata HOF:

   • Location: src/utils/operations/withMetadata.ts
   • Functionality: Handles metadata tasks such as timing, status determination, error handling, and metadata creation.
   • Parameters:
     • operationType: Type of operation (e.g., find, update).
     • params: Essential metadata parameters (spreadsheetId, sheetId, ranges, userId).
     • configs: Configuration options (e.g., includeMetadata).
     • callback: Core operation function.

2. Refactor Core Operations:

   • Target Functions: findFirst, findMany, updateFirst, etc.
   • Changes:
     • Extract core logic into separate functions.
     • Wrap these functions with withMetadata to handle metadata.
     • Remove duplicated metadata handling from each operation.

3. Update Type Definitions:

   • Ensure return types align with the new structure, returning single records or null for findFirst and appropriate types for other operations.

4. Enhance Testing:

   • Update existing tests to accommodate the refactored functions.
   • Add tests for withMetadata to verify proper metadata handling.

Benefits

• Single Responsibility: Each function handles one concern, improving code clarity.
• Reusability: withMetadata can be used across all operations, reducing duplication.
• Consistency: Ensures uniform metadata handling throughout the library.
• Maintainability: Simplifies future updates and enhancements.
• Testability: Facilitates easier and more focused unit testing.

Acceptance Criteria

• withMetadata is implemented and correctly handles metadata for all core operations.
• Core operations are successfully refactored to use withMetadata.
• All existing functionalities remain intact and behave as expected.
• Unit tests are updated and pass successfully.
• Documentation is updated to reflect the changes in function signatures and usage patterns.

Tasks

1. Implement withMetadata:

   • Develop the higher-order function with specified metadata handling capabilities.

2. Refactor Core Operations:

   • Update each core operation to utilize withMetadata, ensuring separation of concerns.

3. Update Types and Tests:

   • Adjust TypeScript interfaces and add necessary tests for the new implementation.

4. Documentation:

   • Update README and relevant docs to guide developers on the new usage patterns.

5. Code Review:

   • Ensure all changes adhere to best practices and maintain code quality.

[teles]

No progress yet

No withMetadata HOF exists in the codebase. Each operation still manages its own metadata logic independently.

❌ Still needed:

• Create src/utils/operations/withMetadata.ts with the HOF that centralizes timing, status, error handling and metadata creation.
• Refactor all core operations (findFirst, findMany, updateFirst, etc.) to delegate metadata handling to withMetadata.
• Update type definitions and tests accordingly.