Docs & Typing: Improve upsert docs, add operations type hints, test J…

[SanjanaG-01]

Summary

This PR introduces three maintenance-focused improvements to the TinyDB codebase:

• Adds precise type hints to operation helpers
• Improves documentation clarity for upsert
• Adds a regression test for unsafe JSONStorage initialization

All changes align with TinyDB’s maintenance-mode guidelines and focus on correctness, clarity, and developer experience.

---

Changes

1. Type Hints for Operations

File: tinydb/operations.py

• Added explicit type annotations (Callable, Mapping, Any, etc.) to all operation functions:
  • delete
  • add
  • subtract
  • set
  • increment
  • decrement
• Improves IDE autocompletion, static analysis, and readability.
• No runtime behavior changes.

---

2. Documentation Improvement for upsert

File: tinydb/table.py

• Updated the upsert docstring to clearly state that all matching documents are updated, not just a single document.
• Helps prevent misunderstandings for users coming from other databases where upsert semantics differ.

---

3. New Test Case for JSONStorage Warnings

File: tests/test_storages.py

• Added test_json_invalid_mode_warning.
• Verifies that JSONStorage emits a UserWarning when initialized with an unsafe access mode (e.g. 'w').
• Ensures this safety behavior remains enforced through future changes.

---

Verification

• Ran pytest locally — all tests pass, including the newly added test.
• Manually validated type hints against standard typing usage.
• No breaking changes introduced.

---

Type of Change

• Documentation improvement
• Typing / developer-experience improvement
• Test coverage improvement
• New feature
• Breaking change