Releases: dexie/Dexie.js
Dexie v4.1.0-beta.43
This release contains experimental support for integration with the Y.js library.
[email protected]
- New constructor option
Yprovides the Y.js library to Dexie.import * as Y from 'yjs'; import Dexie from "dexie"; const db = new Dexie("dbname", { Y });
- New schema feature:
<propertyName>:Y- declares virtual property (not an index) holding the Y.Doc instance.db.version(1).stores({ comments: 'id, title, contentDoc:Y' });
- New Y.js provider for Dexie: DexieYProvider.
const comment = await db.comments.get(commentId); try { DexieYProvider.load(comment.contentDoc); await comment.contentDoc.whenLoaded; // waits until loaded. // At this point the doc is loaded, observed and you // can invoke anything from the Y.js ecosystem, such // as a Tiptap or Prosemirror editor. } finally { DexieYProvider.release(comment.contentDoc); }
When using these options, every object retrieved from table containing :Y specifications, will contain an instance of a Y.Doc no matter if that property has been created or not. The property is neither enumerable nor own so JSON.stringify(obj) won't reveleal it. Accessing the Y.Doc will retrieve an empty, unloaded Y.Doc instance.
Rules for Y properties on objects
- Y properties are never nullish. If declared in the dexie schema, they'll exist on all objects from all queries (toArray(), get() etc).
- Y properties are not
own properties. They are set on the prototype of the returned object. - Y properties are readonly, except when adding new objects to a table (using table.add() or bulkAdd())
- If providing a custom Y.Doc to add() or bulkAdd() its udates will be cloned when added.
- If not providing the Y.Doc or setting the Y property to null when adding objects, there will still be an Y.Doc property on query results of the object, since Y props are defined by the schema and cannot be null or undefined.
- Y properties on dexie objects are readonly. You can not replace them with another document or update them using table.update() or collection.modify(). The only way to update Y.Docs is via the Y.js library methods on the document instance.
- Y properties are not loaded until using DexieYProvider.load() or the new react hook
useDocument() - Y.Doc instances are kept in a global cache integrated with FinalizationRegistry. First time you access the getter, it will be created, and will stay in cache until it's garbage collected. This means that you'll always get the same Y.Doc instance when querying the same Y property of a the same object. This holds true even if the there are multiple obj instances representing the same ID in the database. All of these will hold one single instance of the Y.Doc because the cache is connected to the primary key of the parent object.
How it works
Internally, every declared Y property generates a dedicated table for Y.js updates tied to the parent table and the property name. Whenever a document is updated, a new entry in this table is added.
DexieYProvider is responsible of loading and observing updates in both directions.
Integrations
Y.js allows multiple providers on the same document. It is possible to combine DexieYProvider with other providers, but it is also possible for dexie addons to extend the provider behavior - such as adding awareness and sync.
[email protected]
This is the next verison of dexie-cloud-addon that extends the behavior of DexieYProvider to also support awareness and sync over websockets with Dexie Cloud Server.
Bugfixes
No double initial sync
Earlier versions of dexie-cloud-addon performed two initial sync phases also when requireAuth was specified. This is now optimized to only be done in a single authenticated initial sync.
Better migration from vanilla dexie to dexie-cloud
A vanilla Dexie app with multiple versions and upgraders could not make it to the cloud earlier because we previously disallowed using upgraders between versions when using dexie-cloud-addon. With this version, we allow that but make sure that the change tracking and sync is disabled during upgrade transactions. This allows vanilla dexie apps for easier migrating to cloud by allowing them to run the upgraders needed and then activate dexie-cloud and sync.
New Example App
The Dexie Cloud Starter is a new nextjs app that make full use of online text editing, full-text search and dexie cloud authentication, Github SSO and data sharing in realms.
[email protected]
New hook useDocument() makes use of DexieYProvider as a hook rather than loading and releasing imperatively.
function MyComponent(commentId: string) {
// Query comment object:
const comment = useLiveQuery(() => db.comments.get(comentId));
// Use it's document property (might be nullish):
const provider = useDocument(comment?.contentDoc);
// Pass provider and document to some Y.js compliant code in the ecosystem of such (unless nullish)...
return provider
? <CommentEditor doc={comment.contentDoc} provider={provider} />
: null;
}Dexie v4.0.11
v4.0.10
Dexie v4.0.9
Bugfixes
#2011: Dexie returns duplicated object after manually deleting the database and re-populate it
#2064 Failed to execute 'cmp' on 'IDBFactory': The parameter is not a valid key.
#2073 Uses cmp for sortBy
#2078 DexiePromise does not have withResolvers
#2067 useLiveQuery does not update when multiple items are deleted
Note: The Y.js support is released in 4.1.0 in alpha and possible to test but there is still no official release published for it. Also, the API might change from how it is right now. Will need some more testing and documentation before publishing it with release notes
Dexie v4.0.8
Here's a maintainance release with small things so far.
NOTE: We're also working to release a 4.1 later this summer with CRDT support for rich text editing by providing explicit support for Y.js documents into both Dexie.js and Dexie Cloud (#1926)
Solved issues
- #2001 Typings: circular reference on update
- #2004 Add complete ./dist/* to package.json exports
- #2026 Typings error with Table.update()
- #2011 and #2012: bulkPut() of multiple objects with same primary key would result i liveQueries showing multiple results instead of the last entry only (which is the correct result).
PRs:
- #2006 requireAuth with options. Now possible to provide requireAuth: {email, otp, otpId} instead of just requireAuth: true. Useful when implementing magic link authentication.
[email protected]:
- Fix the 10-seconds pause issue: fdd9844
Dexie v4.0.7
- Tighten non-idempotent operations (PR #2000 - mathematical addition or subtraction)
- Align dexie and dexie-cloud-addon versions: 4.0.7
Dexie v4.0.5
Features
New CRDT operations: add() and remove() (#1936)
New operations that works consistently across sync: Mathematical addition/subtraction as well as adding or removing string or numbers from array properties.
Add to set
It is now possible to add items to an array property using a sync consistent operation "add":
import { add } from "dexie";
db.friends.update(friend.id, {
hobbies: add([
"skating",
"football"
])
});Remove from set
import { remove } from "dexie";
db.friends.update(friend.id, {
hobbies: remove([
"curling"
])
});Mathematical addition and subtraction (number)
import { add, remove } from "dexie";
await db.transaction('rw', db.accounts, () => {
db.accounts.update(accountId1, { balance: remove(100) });
db.accounts.update(accountId2, { balance: add(100) });
});Mathematical addition and subtraction (bigint)
import { add, remove } from "dexie";
await db.transaction('rw', db.accounts, () => {
db.accounts.update(accountId1, { balance: remove(100n) });
db.accounts.update(accountId2, { balance: add(100n) });
});Typings
- #1998 TInsertType in table methods on Dexie and Transaction
Bug fixes
[email protected]
Dexie v4.0.4
Dexie v4.0.2
Patch Release
[email protected]
- Fixes issue #1946 - liveQueries of compound index involving auto-incremented primary key as part failed to update.
Fixes issue #1955 - tsconfig.json in root referering to nonexisting tsconfig in non-bundled src directory.Fixed for real in 4.0.4.
[email protected]
- Allow logging in with demo account in default login GUI and customized login GUI. User can write an imported @demo.local address in the email dialog and can skip the OTP step.
Dexie v4.0.1
Dexie 4 Stable
After 3 years is alpha and beta, and a week in RC, Dexie@4 is finally out!
Changed Version Handling (PR #1880)
- Dexie@4 accepts upgrading schema WITHOUT incrementing the version number.
- Dexie@4 is now able to open a previous version of the database without throwing VersionError.
It's still recommended to increment version number when schema has been updated before publishing new versions of an application since it can make opening the db fractions of ms faster. But it's not required.
(If the native version has diverged from the declared version - which happen when extending schema without incrementing version, dexie need to increment the native version to extend schema - and after a page refresh dexie will detect diverged version by catching VersionError and will redo open with the exact installed version under the hood. When measuring the extra time to open an older version in indexedDB and catch VersionError 10,000 times, it only took 1000 ms - 0.1 ms per try (on a macbook pro), so it should be negligible (https://jsfiddle.net/dfahlander/9tg13fwk/19/))
Cache
Non-transactional live queries utilize memory cache to assist in query resolution. It is possible to opt-out from using the cache using the option {cache: 'disabled'}. The cache can greatly improve simple pure range-based live queries and reduce the queries towards IndexedDB by reusing common queries from different components. The cache will be continously developed and optimized further to improve the new paging support in Dexie 5.0.
Workarounds for flaky browsers
Dexie 4 catches various issues in the IndexedDB support for Chrome and Safari. Without dexie@4 transactions and write operations can suddenly fail in modern versions of Chrome and Safari but dexie makes sure to protect the end user from experience any issues. It does this by reopening the database or redoing the transaction when these things happen - all without the developer having to worry about it. See issues #543 and #613. (A close upcoming release on the 4.0-track will also address #1660 and #1829).
Supports Dexie Cloud
With Dexie 4.0, you can optionally use dexie-cloud-addon and connect your local database with a cloud based database. Dexie Cloud is a complete solution for authorization and synchronization of personal data with support for sharing data between users.
Improved Typing
Dexie 4 has some improved typing. Specifically, Collection.modify() and Table.update() use template literals to suggest code completion and type checking of keypaths to update.
Distinguish insert- from output types
The type passed to db.table.add() can be different from the type returned from db.table.get() and tb.table.toArray(). This mirrors reality better since some properties may be optional when adding (such as an auto-incremented primary key or dexie-cloud properties realmId and owner).
The generic type Table<T, TKey> is extended with a 3rd optional parameter TInsertType making it possible to declare a table as such:
class MyDB extends Dexie {
friends!: Table<
{ id: number; name: string; age: number }, // T (id is always there)
number, // TKey (type of primary key)
{ id?: number; name: string; age: number } // TInsertType (id is optional)
>;
}A new helper generic EntityTable<T> also exists as a "don't repeat yourself" sugar on top of this, and will also omit any method on the type. In case the type is a mapped class with helper methods, you are still able to pass simple POJO objects
to add() and put() with only data properties.
interface Friend {
id: number;
name: string;
age: number;
}
class MyDB extends Dexie {
friends!: EntityTable<Friend, 'id'>; // Automatically makes `id` optional when adding and picks its TKey type.
}If using Dexie Cloud, there's a DexieCloudTable<T> generic that will declare the implicit Dexie Cloud properties on the entity correctly for insert- and output types:
interface Friend {
id: string;
name: string;
age: number;
realmId: string;
owner: string;
}
class MyDexieCloudDB extends Dexie {
friends!: DexieCloudTable<Friend, 'id'>; // Makes id, realmId and owner optional on insert operations.
}A solution to dependency issues with mapped classes
In dexie 3, a mapped class that needs to access the database from its methods, will needs to access the a db instance. But it is a bit awkward to tie a method body to the same instance exported from the db module. For example, having two instances of db with different constructor parameters would not work as both would use one of the instances from their method bodies.
In Dexie 4.0, this is solved using a lightweight dependency injection. There is a generic class Entity that your classes may extend from in order to get your database instance injected as a protected property db on every entity instance. Your class methods can then perform queries onto the db without being dependant on the db module of your app. This use case will require a subclassed Dexie declaration though. There will still be cyclic import dependencies but only on the type level.
export class Friend extends Entity<AppDB> {
id!: number;
name!: string;
age!: number;
async birthday() {
return await this.db.friends.update(this.id, (friend) => ++friend.age);
}
}Breaking Changes
No IE11 support
No support for Internet Explorer 11, legacy Edge (non-chromium) nor legacy Safari below version 14.