Implement `OrThrow` Variants for Key CRUD Methods

[teles]

Objective

Add OrThrow variants for the primary CRUD methods in the HolySheets library. These variants will throw exceptions when operations do not find the expected records or fail, providing a more robust and consistent error-handling mechanism for developers using the library.

Methods to Be Created

• findFirstOrThrow
• updateFirstOrThrow
• clearFirstOrThrow
• getSheetIdOrThrow
• deleteFirstOrThrow

Requirements

1. Functionality of OrThrow Methods:

   • Each OrThrow method should replicate the functionality of its corresponding method without the suffix but with the addition of throwing a specific exception (NotFoundError or another appropriate one) if the operation does not find records or fails.

2. Definition of Custom Errors:

   • Create custom error classes, such as NotFoundError, to be used by the OrThrow method variants.
   • Error messages should be clear and informative, facilitating problem identification.

3. Integration with OperationMetadata:

   • Thrown exceptions should include detailed metadata as defined in the OperationMetadata interface.
   • Ensure metadata reflects the operation's status and any relevant details about the failure.

4. Consistency in Interface:

   • The OrThrow variants should follow the same structure and patterns as existing library methods to maintain API consistency.

5. Documentation:

   • Update the library documentation to include descriptions and usage examples for each OrThrow method.
   • Explain when and why to use the OrThrow variants compared to standard methods.

6. Testing:

   • Develop unit and integration tests to ensure that the OrThrow methods throw exceptions as expected in failure scenarios.
   • Verify that methods behave correctly in successful operations.

Acceptance Criteria

• Complete Implementation:

  • All five OrThrow variants are implemented and integrated into the HolySheets library.

• Proper Exception Handling:

  • Exceptions are thrown correctly when operations fail or do not find records.
  • Error messages are clear and helpful for diagnostics.

• Appropriate Metadata:

  • Exceptions include the appropriate metadata as defined in OperationMetadata.

• Updated Documentation:

  • Documentation reflects the new functionalities with illustrative usage examples for the OrThrow methods.

• Comprehensive Test Coverage:

  • The OrThrow methods have adequate test coverage, ensuring their reliability and robustness.

• Compatibility and Consistency:

  • Introduction of OrThrow methods does not negatively impact existing methods.
  • The API maintains a consistent and predictable interface for developers.

Additional Notes

• Error Handling Flexibility:

  • Providing both throwing and non-throwing methods allows developers to choose the approach that best fits their application's needs.

• Future Extensibility:

  • The proposed structure should facilitate the addition of new method variants in the future as the library evolves.

---

Example Usage

try {
  const user = await holysheets.findFirstOrThrow({ email: 'alice@example.com' });
  console.log('User found:', user);
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error('User not found:', error.message);
  } else {
    console.error('Error fetching user:', error);
  }
}

[teles]

All OrThrow variants implemented across every CRUD group:

Find: findFirstOrThrow, findManyOrThrow, findUniqueOrThrow, findLastOrThrow, findAllOrThrow, findSliceOrThrow
Update: updateFirstOrThrow, updateManyOrThrow, updateUniqueOrThrow, updateLastOrThrow
Clear: clearFirstOrThrow, clearManyOrThrow, clearUniqueOrThrow, clearLastOrThrow, clearAllOrThrow, clearSliceOrThrow
Delete: deleteFirstOrThrow, deleteManyOrThrow, deleteUniqueOrThrow, deleteLastOrThrow, deleteAllOrThrow, deleteSliceOrThrow