|
1 | 1 | # @tanstack/db |
2 | 2 |
|
| 3 | +## 0.0.29 |
| 4 | + |
| 5 | +### Patch Changes |
| 6 | + |
| 7 | +- Automatically restart collections from cleaned-up state when operations are called ([#285](https://github.com/TanStack/db/pull/285)) |
| 8 | + |
| 9 | + Collections in a `cleaned-up` state now automatically restart when operations like `insert()`, `update()`, or `delete()` are called on them. This matches the behavior of other collection access patterns and provides a better developer experience by avoiding unnecessary errors. |
| 10 | + |
| 11 | +- Add collection index system for optimized queries and subscriptions ([#257](https://github.com/TanStack/db/pull/257)) |
| 12 | + |
| 13 | + This release introduces a comprehensive index system for collections that enables fast lookups and query optimization: |
| 14 | + |
| 15 | +- Enabled live queries to use the collection indexes ([#258](https://github.com/TanStack/db/pull/258)) |
| 16 | + |
| 17 | + Live queries now use the collection indexes for many queries, using the optimized query pipeline to push where clauses to the collection, which is then able to use the index to filter the data. |
| 18 | + |
| 19 | +- Added an auto-indexing system that creates indexes on collection eagerly when querying, this is a performance optimization that can be disabled by setting the autoIndex option to `off`. ([#292](https://github.com/TanStack/db/pull/292)) |
| 20 | + |
| 21 | +- feat: Replace string-based errors with named error classes for better error handling ([#297](https://github.com/TanStack/db/pull/297)) |
| 22 | + |
| 23 | + This comprehensive update replaces all string-based error throws throughout the TanStack DB codebase with named error classes, providing better type safety and developer experience. |
| 24 | + |
| 25 | + ## New Features |
| 26 | + - **Root `TanStackDBError` class** - all errors inherit from a common base for unified error handling |
| 27 | + - **Named error classes** organized by package and functional area |
| 28 | + - **Type-safe error handling** using `instanceof` checks instead of string matching |
| 29 | + - **Package-specific error definitions** - each adapter has its own error classes |
| 30 | + - **Better IDE support** with autocomplete for error types |
| 31 | + |
| 32 | + ## Package Structure |
| 33 | + |
| 34 | + ### Core Package (`@tanstack/db`) |
| 35 | + |
| 36 | + Contains generic errors used across the ecosystem: |
| 37 | + - Collection configuration, state, and operation errors |
| 38 | + - Transaction lifecycle and mutation errors |
| 39 | + - Query building, compilation, and execution errors |
| 40 | + - Storage and serialization errors |
| 41 | + |
| 42 | + ### Adapter Packages |
| 43 | + |
| 44 | + Each adapter now exports its own specific error classes: |
| 45 | + - **`@tanstack/electric-db-collection`**: Electric-specific errors |
| 46 | + - **`@tanstack/trailbase-db-collection`**: TrailBase-specific errors |
| 47 | + - **`@tanstack/query-db-collection`**: Query collection specific errors |
| 48 | + |
| 49 | + ## Breaking Changes |
| 50 | + - Error handling code using string matching will need to be updated to use `instanceof` checks |
| 51 | + - Some error messages may have slight formatting changes |
| 52 | + - Adapter-specific errors now need to be imported from their respective packages |
| 53 | + |
| 54 | + ## Migration Guide |
| 55 | + |
| 56 | + ### Core DB Errors |
| 57 | + |
| 58 | + **Before:** |
| 59 | + |
| 60 | + ```ts |
| 61 | + try { |
| 62 | + collection.insert(data) |
| 63 | + } catch (error) { |
| 64 | + if (error.message.includes("already exists")) { |
| 65 | + // Handle duplicate key error |
| 66 | + } |
| 67 | + } |
| 68 | + ``` |
| 69 | + |
| 70 | + **After:** |
| 71 | + |
| 72 | + ```ts |
| 73 | + import { DuplicateKeyError } from "@tanstack/db" |
| 74 | + |
| 75 | + try { |
| 76 | + collection.insert(data) |
| 77 | + } catch (error) { |
| 78 | + if (error instanceof DuplicateKeyError) { |
| 79 | + // Type-safe error handling |
| 80 | + } |
| 81 | + } |
| 82 | + ``` |
| 83 | + |
| 84 | + ### Adapter-Specific Errors |
| 85 | + |
| 86 | + **Before:** |
| 87 | + |
| 88 | + ```ts |
| 89 | + // Electric collection errors were imported from @tanstack/db |
| 90 | + import { ElectricInsertHandlerMustReturnTxIdError } from "@tanstack/db" |
| 91 | + ``` |
| 92 | + |
| 93 | + **After:** |
| 94 | + |
| 95 | + ```ts |
| 96 | + // Now import from the specific adapter package |
| 97 | + import { ElectricInsertHandlerMustReturnTxIdError } from "@tanstack/electric-db-collection" |
| 98 | + ``` |
| 99 | + |
| 100 | + ### Unified Error Handling |
| 101 | + |
| 102 | + **New:** |
| 103 | + |
| 104 | + ```ts |
| 105 | + import { TanStackDBError } from "@tanstack/db" |
| 106 | + |
| 107 | + try { |
| 108 | + // Any TanStack DB operation |
| 109 | + } catch (error) { |
| 110 | + if (error instanceof TanStackDBError) { |
| 111 | + // Handle all TanStack DB errors uniformly |
| 112 | + console.log("TanStack DB error:", error.message) |
| 113 | + } |
| 114 | + } |
| 115 | + ``` |
| 116 | + |
| 117 | + ## Benefits |
| 118 | + - **Type Safety**: All errors now have specific types that can be caught with `instanceof` |
| 119 | + - **Unified Error Handling**: Root `TanStackDBError` class allows catching all library errors with a single check |
| 120 | + - **Better Package Separation**: Each adapter manages its own error types |
| 121 | + - **Developer Experience**: Better IDE support with autocomplete for error types |
| 122 | + - **Maintainability**: Error definitions are co-located with their usage |
| 123 | + - **Consistency**: Uniform error handling patterns across the entire codebase |
| 124 | + |
| 125 | + All error classes maintain the same error messages and behavior while providing better structure and package separation. |
| 126 | + |
3 | 127 | ## 0.0.28 |
4 | 128 |
|
5 | 129 | ### Patch Changes |
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments