feat(use-queue): deprecate api property in favor of details

[megheaiulian]

Summary

This PR deprecates the api property in favor of the more flexible details property. This is a non-breaking change - the api property will continue to work with deprecation warnings until v2.0.0.

Changes

Code Changes

• ✅ Added @deprecated JSDoc tags to api property in TypeScript interfaces
• ✅ Added runtime console warning when api property is used
• ✅ Maintained full backward compatibility

Documentation

• ✅ Created comprehensive migration guide: docs/migration-api-to-details.md
• ✅ Updated README.md with migration examples and patterns
• ✅ Updated CHANGELOG.md for v1.7.0 release

Tests

• ✅ Added deprecation test suite: test/use-queue-deprecation.test.ts
• ✅ 8 test cases covering warnings, content, and backward compatibility
• ✅ TypeScript compilation verified (no errors)

Migration Example

Before (deprecated):

useQueue({
  api: (id, item) => apiUrl('api/items/' + id)
})

After (recommended):

useQueue({
  details: (item) => fetch(apiUrl('api/items/' + item.id)).then(res => res.json())
})

Benefits of details Property

• ✅ Full control over fetch operations, headers, and error handling
• ✅ Modern Promise-based pattern that works with async/await
• ✅ No dependency on deprecated utilities (json(), etc.)
• ✅ More flexible for different backends and data sources

Deprecation Timeline

• v1.7.0 (This PR): Deprecation warnings added, full backward compatibility
• v1.x.x (Future minor releases): api continues working with warnings
• v2.0.0 (Future major release): api property will be removed

What Users Will See

When using the deprecated api property, users will see:

[cosmoz-queue] DEPRECATED: The api property is deprecated and will be removed in v2.0.0. 
Please migrate to the details property for better control and performance.

Migration guide:
  Before: api: (id, item) => apiUrl('api/items/ID')
  After:  details: (item) => fetch(apiUrl('api/items/' + item.id)).then(res => res.json())

See: https://github.com/Neovici/cosmoz-queue#migration-from-api-to-details

Additionally, IDEs will show strikethrough text on the api property with hover documentation.

Migration Guide

See the comprehensive migration guide at docs/migration-api-to-details.md which includes:

• Common migration patterns (7 examples)
• Advanced patterns (10 examples): error handling, auth, timeouts, GraphQL, etc.
• Troubleshooting section (8 common issues)
• Step-by-step instructions

Verification

• ✅ TypeScript compilation: SUCCESS (no errors)
• ✅ All code changes implemented
• ✅ Documentation complete
• ✅ Tests written
• ✅ Backward compatibility maintained
• ✅ Zero breaking changes

Files Changed

Modified (3 files)

• src/queue/use-queue.ts (+43 lines)
• README.md (+136 lines)
• CHANGELOG.md (+36 lines)

Created (3 files)

• docs/migration-api-to-details.md (9.7KB)
• test/use-queue-deprecation.test.ts (3.7KB)
• IMPLEMENTATION_SUMMARY.md (implementation docs)

Checklist

• TypeScript compiles without errors
• Code follows project linting rules
• Documentation updated
• Tests added
• CHANGELOG updated
• Backward compatible (non-breaking)
• Migration guide provided

Related Issues

This implements the deprecation strategy for the api property as discussed in the codebase modernization effort.

---

Ready for review! This is a non-breaking change that prepares users for the future v2.0.0 release while maintaining full backward compatibility.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-02-12 09:14 UTC

[github-actions]

🎉 This PR is included in version 1.6.2 🎉

The release is available on:

• GitHub release
• npm package (@latest dist-tag)

Your semantic-release bot 📦🚀