--- url: /getting-started.md --- # Getting Started Welcome to the Getting Started Guide for SignalDB, a local-first database with signal-based reactivity and real-time synchronization. This guide will help you understand the basics of SignalDB and get you up and running quickly. SignalDB is designed for blazing fast query performance and data persistence, while remaining framework-agnostic. ## Installation Installing SignalDB is simple and easy. It can be installed using npm. Open your terminal and enter the following command: ```bash $ npm install @signaldb/core ``` ## Creating Collections Creating collections is straight forward. ```js import { Collection } from '@signaldb/core' const posts = new Collection() ``` but normally you want to persist your data. Persistence in SignalDB is achieved by giving the collection a data adapter that is backed by a [storage adapter](/data-persistence/). Choose one that fits your needs. Here is an example using [`@signaldb/localstorage`](/reference/localstorage/): ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import createLocalStorageAdapter from '@signaldb/localstorage' const dataAdapter = new DefaultDataAdapter({ storage: name => createLocalStorageAdapter(name), }) const posts = new Collection('posts', dataAdapter) ``` One data adapter serves every collection of your application — it is asked for the storage belonging to each collection by name, so you build it once and pass it to all of them. That's all you have to do. There a also some optional configuration options you find here: [collections reference](/reference/core/collection/) ## Adding data After you've created you first collection, you can start to add documents to it. ```js // ... const postId = await posts.insert({ title: 'Foo', text: 'Lorem ipsum …' }) ``` Writes are asynchronous — the promise resolves once the data layer has confirmed the write, while your queries already show it. You created your first document in SignalDB! Check out the [data manipulation](/data-manipulation/) page to learn how to update and remove documents. ## Querying Getting your documents back is also very easy. ```js // ... const cursor = posts.find({}) console.log(cursor.fetch()) // returns an array with all documents in the collection ``` You've finished the Getting Started Guide! The next steps are getting reactivity to work. Check out the [core concepts about reactivity](/core-concepts/#signals-and-reactivity) to learn how to do this. ## Using SignalDB with AI tools The documentation is also available in a format made for large language models, following the [llms.txt](https://llmstxt.org/) convention: * [`/llms.txt`](/llms.txt) — an index of all documentation pages with a short description each * [`/llms-full.txt`](/llms-full.txt) — the complete documentation in a single file Hand one of them to your coding assistant to give it up-to-date knowledge of SignalDB's API. ## Next steps Now you know the basics about SignalDB. It's time to learn how to integrate it with the framework you're using. Take a look at our guides: * [Angular](/guides/angular/) * [React](/guides/react/) * [Solid](/guides/solid-js/) * [Svelte](/guides/svelte/) * [Vue](/guides/vue/) After that you might want to learn more about the [core concepts of SignalDB](/core-concepts/), how you can [query your data](/queries/) or how to [connect it to your backend](/sync/). --- --- url: /core-concepts.md --- # Core Concepts The following are some key concepts that are important to understanding how to use SignalDB effectively. ## Collections With the `DefaultDataAdapter`, a collection keeps all of its data in memory, making query performance exceptionally fast. Other [data adapters](/data-adapters/) may not: they can read from storage on every query or keep the data in a Web Worker. Users can create collections of documents, where each document is a record in the database. Queries can be run against these collections to retrieve data according to specific criteria. This architecture also plays an important role in achieving optimistic UI strategies. ### Schemaless SignalDB is schema-less, which means you don't need to define a schema for your data before you start using it. This allows you to store any data you want without worrying about defining a schema first. More information on how to define collections and perform queries will be found in the dedicated sections: * [Collections](/reference/core/collection/) * [Queries](/queries/) ### Optimistic UI Optimistic UI is an approach where user interfaces are updated optimistically in response to user actions before the actual server response is received.This approach provides a smoother and more responsive user experience because the UI doesn't have to wait for the server to confirm the success of the action. SignalDB's schema-less nature and reactive querying via reactivity adapters enable the creation of robust, optimistic UI implementations. When a user triggers an action that changes the data, such as submitting a form, SignalDB's reactivity system can immediately update the UI to reflect the intended changes. This is possible because the reactivity adapters automatically propagate changes to the UI components that rely on the affected data. ## Signals and Reactivity As the name suggests, SignalDB's reactivity is based on signals, a concept from functional reactive programming. The concept is quite old, but is becoming popular again since the hype around solidjs in early 2023. Since many signal libraries are currently emerging, SignalDB is designed to be library agnostic. Reactivity adapters in SignalDB enable reactive querying of the documents in a collection. They provide a simple interface that allows you to integrate a signal library. By using reactivity adapters, you can ensure that whenever the data in your collections changes, any reactive queries tied to that data are automatically updated, keeping the state of your application consistent with your data. To learn more about signals, read [The Evolution of Signals in JavaScript](https://dev.to/this-is-learning/the-evolution-of-signals-in-javascript-8ob) by Ryan Carniato (author of SolidJS). Typically, you'll simply use a predefined reactivity adapter for the signal library you're using. Check out the available adapters in the [Reactivity section](/reactivity/) of the documentation. ## Data Adapters A data adapter decides *where a collection's data operations actually happen*. A collection itself only describes the operation — insert this, update what matches that — and hands it to its data adapter, which answers it and reports back what changed. That is the seam that lets the same collection API run against very different arrangements: in memory on the main thread, asynchronously against storage, or in a web worker with only the results crossing back. Which one you pick changes nothing about how you query and write. ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' const dataAdapter = new DefaultDataAdapter() const Posts = new Collection('posts', dataAdapter) ``` See the [data adapters](/data-adapters/) documentation for the adapters that ship with SignalDB and when each of them is the right one. ## Data Persistence Without a storage adapter, the `DefaultDataAdapter` only keeps the data in memory and it will be lost when the memory is flushed (e.g. page reload). Other [data adapters](/data-adapters/) read and write through a storage adapter instead of keeping everything in memory. Normally you don't want to lose data and you want to persist it. This is where storage adapters come in. Storage adapters in SignalDB play a critical role in ensuring that your data remains intact across multiple user sessions or application reloads. These adapters facilitate data persistence by providing a standard interface for storing and retrieving data, thereby abstracting from the specifics of the underlying storage mechanism. A storage adapter provides the necessary code to interact with a specific storage medium, such as localStorage, IndexedDB, or even a remote server. The role of the adapter is to translate the high-level operations that you perform on your data (such as saving or loading a document) into low-level operations that the storage medium can understand. The main benefit of using storage adapters is flexibility. Because they provide an abstraction layer over the storage system, you can switch between different storage systems with minimal impact on the rest of your code. See also the [storage adapters](/data-persistence/) documentation page. --- --- url: /queries.md --- # Querying Data Like most databases, SignalDB lets you query your data. It uses an approach similar to MongoDB, where you can apply selectors to filter your data and use options to control things like sorting, projection, skipping, and limiting the results. When you run a query with `.find()`, the query doesn’t execute right away. Instead, it returns a cursor, which you can use to call methods and get the actual data—just like in MongoDB. This makes it easier to only process what you need. For example, if you just need the `.count()` of a query, you don’t have to load all the data. A unique feature of SignalDB is that all queries are reactive by default. This means if you run a query and use a function on the returned cursor within the `effect` or `autorun` function of your reactivity library, the query will automatically rerun whenever the data changes. ## MongoDB-Style Queries in the Browser SignalDB brings a MongoDB-like query API to the client. Selectors such as `{ age: { $gte: 18 }, tags: { $in: ['admin'] } }`, sort and projection options and cursors work the way MongoDB developers expect, but run against local data in the browser or in Node.js. If you know Meteor's Minimongo, SignalDB will feel familiar: it offers a similar API outside of Meteor, works with any framework through [reactivity adapters](/reactivity/), and adds [persistence](/data-persistence/) and [sync with any backend](/sync/). ## Queries You can query you data by calling the [`.find()`](/reference/core/collection/#find-selector-selector-t-options-options) or [`.findOne()`](/reference/core/collection/#findone-selector-selector-t-options-options) method of your collection. `.findOne()` returns the first found document while `.find()` returns a [cursor](/reference/core/cursor/). ### Reactive or awaited Where you read a query decides how you read it: * **Inside a reactive scope** — an `effect`, an `autorun`, a component's render — read it synchronously. The scope reruns whenever the result changes, so the cursor hands over what it holds right now. * **Everywhere else** — an event handler, a loader, a script, a test — pass `async: true` and await the result. ```js // inside a reactive scope effect(() => { render(collection.find({ status: 'published' }).fetch()) }) // everywhere else const posts = await collection.find({ status: 'published' }, { async: true }).fetch() ``` This holds for every data adapter, including the in-memory default one, where a synchronous read happens to return the data anywhere. A synchronous read outside a reactive scope is almost always a mistake: nothing keeps it up to date, and with an adapter that answers asynchronously it returns a [neutral empty result](#queries-that-are-not-answered-immediately) instead of the data. SignalDB warns about it in the console. A collection without a reactivity adapter has no reactive scope at all, so it is always read with `async: true`. ### Selectors SignalDB uses the [`mingo`](https://www.npmjs.com/package/mingo) library under the hood. It's very similar to MongoDB selectors. Check out their documentation to learn how a selector should look like: https://github.com/kofrasa/mingo ### Options The second parameter you can pass to the `.find()` method are the options. With the options you can control things like sorting, projection, skipping or limiting data. ### Sorting To sort the documention returned by a cursor, you can provide a `sort` object to the options. The object should contain the keys you want to sort and a direction (`1 = ascending`, `-1 = descending`) ```js collection.find({}, { sort: { createdAt: -1 }, }) ``` ### Projection You can also control which fields should be returned in the query. To do this, specify the `fields` object in the `options` of the `.find()` method. ::: tip With the `fields` option you can also control when you query will rerun. If you only query for a field that is not changing, the query will not rerun. Also see [Field-Level Reactitivity](#field-level-reactivity) ::: ```js collection.find({}, { fields: { title: 1 }, }) ``` ### `skip` and `limit` To skip or limit the result of a query, use the `skip` or `limit` options. Both options are optional. ```js collection.find({}, { skip: 10, limit: 10, }) ``` ## Queries that are not answered immediately The default adapter keeps your data in memory and answers a query on the spot. The [async, worker and auto-fetch adapters](/data-adapters/) cannot — they have to go to storage, across a worker boundary, or to a server. SignalDB gives you two ways to deal with that, and which one you want depends on where you are reading from. ### Awaiting the result Pass `async: true` and the cursor's methods resolve to their result instead of returning it: ```js const posts = await collection.find({ status: 'published' }, { async: true }).fetch() const count = await collection.find({}, { async: true }).count() const one = await collection.findOne({ id: 'abc' }, { async: true }) ``` The types follow the option, so a cursor without it stays synchronous and you do not end up awaiting things that were never promises. This is the right form outside a reactive scope: an event handler, a loader, a script. It is not reactive — you get the result once. ### Reading reactively Inside an `effect` or `autorun` you want the query to rerun by itself, so it cannot hand you a promise. The cursor gives you what it has, and until the query has been answered that is a **neutral** result: `fetch()` gives an empty array, `count()` gives zero. That neutral result is indistinguishable from a real one, because empty is a legitimate answer — plenty of queries genuinely match nothing. [`Cursor#isLoading()`](/reference/core/cursor/#⚡️-isloading-reactive) is what lets you tell the two apart: ```js const cursor = collection.find({ status: 'published' }) effect(() => { if (cursor.isLoading()) return renderSpinner() render(cursor.fetch()) }) ``` Rendering "no posts yet" during that window is the bug this prevents. With the default in-memory adapter `isLoading()` is `false` as soon as the collection is ready, so you rarely need it there. ::: tip `isLoading()` is always `false` on an `{ async: true }` cursor — its `fetch()` already waits for the real result, so there is no window to report. The two forms are alternatives, not layers. ::: ## Observing changes Reactive queries rerun a scope and hand you the whole result again. When you need to know *what* changed instead — to drive an animation, keep a third-party widget in step, or log activity — observe the cursor: ```js const cursor = Posts.find({ status: 'published' }, { sort: { createdAt: -1 } }) const stop = cursor.observeChanges({ added: item => {}, addedBefore: (item, before) => {}, changed: (item, previousItem) => {}, changedField: (item, field, oldValue, newValue) => {}, movedBefore: (item, before) => {}, removed: item => {}, }) // later stop() ``` * `added(item)` — an item entered the result. * `addedBefore(item, before)` — the same, with the item it now sits in front of, or `null` when it was added at the end. * `changed(item, previousItem)` — an item in the result changed; you get it as it is now and as it was before. * `changedField(item, field, oldValue, newValue)` — called once per top-level field that differs between the two versions. * `movedBefore(item, before)` — an item changed its position in a sorted result; `before` is the item it now precedes, or `null` at the end. * `removed(item)` — an item left the result, either because it was removed or because it no longer matches. All callbacks are optional, and the items have the collection's `transform` applied. Unless you pass `true` as the second argument (`skipInitial`), the items already in the result are reported through `added` and `addedBefore` straight away. `observeChanges` returns the function that stops observing; call it, or `cursor.cleanup()`, once you are done, otherwise the query stays live. See the [`Cursor` reference](/reference/core/cursor/) for details. ### Collection events A collection is also an event emitter. Its events describe the writes made through its own methods, independent of any query, and fire once the data layer has confirmed the write: ```js const onChanged = (item, modifier, previousItem) => { console.log(`${item.id} changed`, modifier, previousItem) } Posts.on('added', item => {}) Posts.on('changed', onChanged) Posts.on('removed', item => {}) Posts.once('query.error', (error, selector, options) => {}) // later Posts.off('changed', onChanged) ``` * `added(item)` — an item was inserted. * `changed(item, modifier, previousItem)` — an item was updated or replaced: the item as it is now, the modifier (or replacement) that was applied, and the item as it was before. All data adapters shipped with SignalDB report `previousItem`; a custom one may leave it out. * `removed(item)` — an item was removed; fired once per item. * `query.error(error, selector, options)` — a live query failed and will not deliver a result. Its cursor keeps serving the neutral empty result, so this event is the only way to tell a failed query from one that matched nothing. `on` subscribes, `once` subscribes for a single call, `off` unsubscribes the listener you passed to either of them. The full list of events is in the [`Collection` reference](/reference/core/collection/#events). ## Field-Level Reactivity SignalDB introduces a powerful enhancement to its reactivity system called **Field-Level Reactivity**, which ensures that reactive functions (such as `effect` or `autorun`) only rerun when specific fields accessed in your code are changed. Previously, the reactive system would rerun the query if any field in any item of the result set was modified, regardless of whether those fields were actually used in the code. This led to unnecessary reactivity and potential performance bottlenecks, especially with large datasets. ### Key Features * **Field-Level Reactivity**: Reactive reruns now occur only when the fields actually accessed by your code are modified, rather than triggering for all changes in the dataset. * **Item-Level Reactivity**: If a query returns multiple items but you only access fields from specific items, changes in unaccessed items will not trigger a rerun. * **Automatic Field Tracking**: Instead of manually specifying which fields to track using the `fields` option, SignalDB now automatically tracks fields as you access them. This reduces the chance of developer oversight and simplifies code maintenance. ### Opt-In to Field-Level Tracking To enable field-level reactivity, there are three ways to configure field tracking: globally, per collection, or through the options parameter of the `.find()` method. #### 1. Global Configuration To enable field tracking globally for all collections in your application, use the static method `Collection.setFieldTracking`. This ensures that field tracking is active by default across all collections unless overridden. ```js Collection.setFieldTracking(true) // Enables field tracking globally ``` #### 2. Per Collection Configuration To configure field tracking for a specific collection, use the setFieldTracking method on that collection. ```js someCollection.setFieldTracking(true) // Enables field tracking for this collection only ``` #### 3. Enable Field Tracking in `.find()` Options You can enable field tracking on a per-query basis by passing the fieldTracking: true option to the .find() method. When this option is set, reactivity is scoped to the fields you access. ```js effect(() => { const items = someCollection.find({}, { fieldTracking: true }).fetch() // Access the fields you care about here console.log(items[0].name) // Will rerun only if 'name' field of the 0th item changes }) ``` This behavior optimizes your app’s performance by reducing the number of unnecessary reruns. Instead of rerunning every time any field in any document changes, it only reruns when the relevant fields you’re interacting with are modified. ### Benefits of Automatic Field Tracking 1. Improved Performance: By reducing the scope of reactive reruns to only relevant data, SignalDB minimizes computational overhead and maximizes efficiency, particularly in scenarios where queries return large datasets or where irrelevant fields change frequently. 2. Simplified Code: Developers no longer need to manually specify fields to track. With automatic field tracking, the system handles this for you, allowing you to focus on business logic rather than managing reactivity manually. 3. Reduced Developer Error: Manually tracking fields can be error-prone, especially as queries evolve. Automatic field-level reactivity ensures that your queries remain optimal even as your code changes, making it easier to maintain over time. --- --- url: /data-manipulation.md --- # Data manipulation Every write is asynchronous and returns a promise: `insert` resolves to the id of the new item, `updateOne`, `replaceOne` and `removeOne` to `0` or `1`, and `updateMany` and `removeMany` to the number of items they touched. Awaiting a write means waiting for the data layer to confirm it — the change is visible to your queries before that, which is what makes an optimistic UI possible. ## Inserting data To insert data into a collection, use the [`.insert()`](/reference/core/collection/#insert-item-omit-t-id-partial-pick-t-id) method. ```js const id = await collection.insert({ title: 'Hello World' }) ``` ## Updating data To update data in a collection, use the [`.updateOne()`](/reference/core/collection/#updateone-selector-selector-t-modifier-modifier-t-options-upsert-boolean) or [`.updateMany()`](/reference/core/collection/#updatemany-selector-selector-t-modifier-modifier-t-options-upsert-boolean) method. SignalDB uses the [`mingo`](https://www.npmjs.com/package/mingo) library under the hood. It allows modifiers that are very similar to [MongoDB modifiers](https://www.mongodb.com/docs/manual/reference/operator/update/). Check out their documentation to learn how a modifier should look like: https://github.com/kofrasa/mingo#updating-documents ```js const updated = await collection.updateOne({ id: 'xyz' }, { $set: { title: 'Hello SignalDB' }, }) const updatedCount = await collection.updateMany({ title: 'Hello World' }, { $set: { title: 'Hello SignalDB' }, }) ``` ## Replacing items To replace an item in a collection, use the [`.replaceOne()`](/reference/core/collection/#replaceone-selector-selector-t-replacement-omit-t-id-partial-pick-t-id-options-upsert-boolean) method. ```js await collection.replaceOne({ id: 'xyz' }, { title: 'Hello SignalDB' }) ``` ## Deleting data To delete data from a collection, use the [`.removeOne()`](/reference/core/collection/#removeone-selector-selector-t) or [`.removeMany()`](/reference/core/collection/#removemany-selector-selector-t) method. ```js await collection.removeOne({ id: 'xyz' }) await collection.removeMany({ title: 'Hello World' }) ``` ## Batching writes Every write updates the live queries it affects as soon as it is applied. For a handful of writes that belong together — the result of one user action, say — you can hold those updates back until the last of them is done: ```js await Posts.batch(async () => { await Posts.updateOne({ id: 'xyz' }, { $set: { status: 'archived' } }) await Posts.removeMany({ parentId: 'xyz' }) }) ``` The writes themselves are not deferred: each one is applied and emits its events as usual. What waits is the update of every live query the writes affect. When the callback returns, or the promise it returned settles, each affected query is brought up to date once, by comparing its new result against the old one. A callback that throws or rejects still ends the batch. The batch resolves to `undefined`, not to what the callback returned. To batch writes across several collections, pass them to the static form: ```js await Collection.batch([Posts, Comments], async () => { await Posts.removeOne({ id: 'xyz' }) await Comments.removeMany({ postId: 'xyz' }) }) ``` ::: warning Prefer the scoped form `Collection.batch(callback)` without the list of collections batches **every collection in the process**, not only the ones you write to. While it is open no live query anywhere updates, and everything that was held back is flushed at once when it closes. That is fine for a few writes belonging to one event and harmful around anything whose length depends on your data, such as a loop over records from a server. Name the collections whenever you know them. ::: A batch holds the query pipeline, which is why it should stay short. For an operation that spans several `await`s and should wake reactive scopes only once at the end, use [`reactiveTransaction`](/reference/core/reactivetransaction/) instead. --- --- url: /data-persistence.md --- # Storage Adapters Storage adapters in SignalDB provide the mechanism for storing and retrieving data, ensuring that your data is kept safe across sessions and reloads of your application. These adapters interact with the underlying storage medium, such as localStorage, IndexedDB, or even a remote server, and handle the specifics of those storage systems while providing a consistent interface for data operations in your application. Storage adapters are responsible for transforming the high-level operations you perform on your data (such as saving a document or loading a collection) into the low-level operations that the specific storage system can understand and perform. The main benefit of using storage adapters is the abstraction they provide. They allow SignalDB to remain agnostic to the underlying storage system. This means that you can switch between different systems without changing the rest of your code. Not sure which browser storage to use? See [localStorage vs IndexedDB vs OPFS](/browser-storage/) for a comparison. The following storage adapters are currently available: * [IndexedDB](/reference/indexeddb/) * [localStorage](/reference/localstorage/) * [OPFS](/reference/opfs/) * [FileSystem](/reference/fs/) * [Generic file system](/reference/generic-fs/) — the foundation behind the FileSystem and OPFS adapters, for building your own file-based storage A storage adapter is reached through a [data adapter](/data-adapters/), which is what decides *where* the data operations run. Building your own storage adapter for your specific use case is also possible and pretty straightforward. See [`createStorageAdapter`](/reference/core/createstorageadapter/) for more information. ## Why query semantics stay in SignalDB A storage adapter has to answer three questions: *all* items, items *by id*, and the contents of *one index*. That is deliberate, and it is the reason the required interface is as small as it is: ```ts readAll(): Promise readIds(ids: I[]): Promise readIndex(field: string): Promise>> ``` An index is keyed by `serializeValue(value)`, not by the raw field value — that is what SignalDB looks it up with. An adapter that stores raw keys answers nothing for every non-string field and everything for a `$ne` on one. Query semantics live in SignalDB, in one place. A storage backend only has to be able to store things and find them again — it never has to understand `$in`, `$gt`, `$regex`, or how they combine under `$and` and `$or`. That keeps the set of possible backends wide open. Anything that can persist bytes and look something up can be a storage adapter: a file system that maps each index onto a directory, an archive file, a key-value store, a remote endpoint that only offers a fetch-by-key. None of them are excluded for lacking a query language, and none of them can quietly disagree with another about what a selector means. One implementation of the semantics means one place to fix a bug in them and one suite to test them. Letting adapters answer whole queries instead would put the selector semantics into every adapter that opts in, make an adapter's capabilities unpredictable from the outside, and turn "which adapter am I using" into something that changes results rather than just performance. ### Narrowing a read with `query` A backend that *can* read less than everything may implement the optional [`query`](/reference/core/createstorageadapter/#answering-queries-with-query) method. It receives the whole query — selector, sort, window and projection — and answers as much of it as it can, saying what it did and handing back the part of the selector it did not apply. SignalDB applies everything the adapter declined, so the result is the same with or without `query`; only the cost differs. `@signaldb/indexeddb` uses it to turn an equality on the primary key or an indexed field into a key-range read instead of reading the whole store. `query` is consulted by the data adapters that read from storage on every query — [`AsyncDataAdapter`](/reference/core/asyncdataadapter/), [`AutoFetchDataAdapter`](/reference/core/autofetchdataadapter/) and the [`WorkerDataAdapterHost`](/reference/core/workerdataadapter/). The `DefaultDataAdapter` loads everything into memory once and does not use it. ### What this means for your collections The cost of this design is that **SignalDB can only narrow a query down to the indices you declared.** A selector that no index covers is answered by reading the whole collection out of storage and filtering it in JavaScript. That is fine for small collections and for one-off reads, and it is the wrong thing for a collection that grows. So for anything that keeps growing, declare the fields you actually select on as indices when you create the collection: ```ts import { AsyncDataAdapter, Collection } from '@signaldb/core' import createFilesystemAdapter from '@signaldb/fs' const dataAdapter = new AsyncDataAdapter({ storage: name => createFilesystemAdapter(`./data/${name}`), }) const posts = new Collection('posts', dataAdapter, { indices: ['authorId', 'status'], }) ``` Selecting a single item by `id` needs no index. It is resolved directly through the adapter's `readIds` — every storage can look an item up by its id, which is why that is part of the interface rather than something you have to declare. --- --- url: /data-adapters.md --- # Data Adapters A data adapter decides **where a collection's data operations actually happen**. The collection itself does not query, write or store anything. It describes the operation — insert this item, update whatever matches that selector, keep me posted about this query — and hands it to its data adapter. The adapter answers it and reports back what changed. ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' const dataAdapter = new DefaultDataAdapter() const Posts = new Collection('posts', dataAdapter) const Authors = new Collection('authors', dataAdapter) ``` One adapter usually serves every collection of an application. It is asked for the storage belonging to each collection by name, which is why the collection's name is a constructor argument rather than an option. ## Where it sits SignalDB has three extension points, and they answer three different questions: | | Question it answers | | --- | --- | | [`ReactivityAdapter`](/reactivity/) | How do I tell your framework that something changed? | | [`DataAdapter`](/reference/core/dataadapter/) | Where do the data operations run? | | [`StorageAdapter`](/data-persistence/) | How is a document persisted and read back? | A data adapter is the one in the middle. Most of them take a `storage` function and use a storage adapter underneath — the difference between them is not *what* they store but *where and when* the work happens. ## Choosing one ### `DefaultDataAdapter` Keeps the data in memory on the main thread and answers every query from it. Writes are applied immediately and persisted in the background. This is the adapter you want unless something below applies, and the one a collection constructed without an adapter uses. ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import createLocalStorageAdapter from '@signaldb/localstorage' const dataAdapter = new DefaultDataAdapter({ storage: name => createLocalStorageAdapter(name), }) ``` [Reference →](/reference/core/defaultdataadapter/) ### `AsyncDataAdapter` Answers every query by going to storage, without holding the collection in memory. Right when the data does not fit in memory, or when something else can change the underlying storage. ```js import { Collection, AsyncDataAdapter } from '@signaldb/core' import createIndexedDBAdapter from '@signaldb/indexeddb' const dataAdapter = new AsyncDataAdapter({ storage: createIndexedDBAdapter({ databaseName: 'my-app', version: 1, schema: { posts: ['authorId'] }, }), onError: error => reportToCrashReporter(error), retry: { attempts: 5, delay: attempt => 250 * attempt, }, }) const Posts = new Collection('posts', dataAdapter, { indices: ['authorId'] }) ``` * `storage` is called once per collection with its name and is required. * A query that fails is retried before it is given up: `retry.attempts` counts every attempt including the first (default `3`), `retry.delay` returns the wait in milliseconds before the next one (default `100 * 4 ** (attempt - 1)`). Only once every attempt has failed is the query published as failed — see [below](#queries-on-these-adapters-are-asynchronous). * `onError` receives what fails inside the adapter, including a query that has run out of attempts. Without it, the error goes to `console.error`. [Reference →](/reference/core/asyncdataadapter/) ### `WorkerDataAdapter` / `WorkerDataAdapterHost` Runs the data layer in a web worker. `WorkerDataAdapterHost` lives inside the worker and owns the storage; `WorkerDataAdapter` lives on the main thread and talks to it. Right when queries or writes are large enough that doing them on the main thread costs you frames. The worker file constructs the host with the worker's global scope and the storage: ```js // data-worker.js import { WorkerDataAdapterHost } from '@signaldb/core' import createIndexedDBAdapter from '@signaldb/indexeddb' new WorkerDataAdapterHost(self, { id: 'app-data', storage: createIndexedDBAdapter({ databaseName: 'my-app', version: 1, schema: { posts: ['authorId'] }, }), onError: error => console.error('[data worker]', error), }) ``` The main thread starts the worker and hands it to the adapter, which your collections are then constructed with: ```js import { Collection, WorkerDataAdapter } from '@signaldb/core' const worker = new Worker(new URL('./data-worker.js', import.meta.url), { type: 'module', }) const dataAdapter = new WorkerDataAdapter(worker, { id: 'app-data' }) const Posts = new Collection('posts', dataAdapter, { indices: ['authorId'] }) ``` Both halves must use the **same `id`** — every message carries it, and each side ignores messages with a different one. That is what lets several adapters share a worker, or several workers share a page. If you omit it on both sides they agree on the default, `'default-worker-data-adapter'`. The host announces itself when it is constructed. If the main thread does not hear from it within five seconds — the worker failed to load, or the ids do not match — every operation of the adapter fails with `WorkerDataAdapter initialization timed out`. [Reference →](/reference/core/workerdataadapter/) ### `AutoFetchDataAdapter` Fetches a query's items from a remote source the first time that query is registered, and drops them again when nothing is watching it any more. Right for data you want to pull on demand rather than sync in full — the successor to v1's `AutoFetchCollection`. ```js import { Collection, AutoFetchDataAdapter } from '@signaldb/core' import createIndexedDBAdapter from '@signaldb/indexeddb' const dataAdapter = new AutoFetchDataAdapter({ storage: createIndexedDBAdapter({ databaseName: 'my-app-cache', version: 1, schema: { posts: [] }, }), fetchQueryItems: async (collectionName, selector) => { const query = encodeURIComponent(JSON.stringify(selector)) const response = await fetch(`/api/${collectionName}?selector=${query}`) return response.json() // an array of items, each with an `id` }, registerRemoteChange: async (onChange) => { const socket = new WebSocket('wss://example.com/changes') socket.addEventListener('message', () => { void onChange() }) }, }) const Posts = new Collection('posts', dataAdapter) ``` * `storage` is the local cache the fetched items are written to and every query is answered from. Leave it out and the items are cached in memory, so nothing survives a reload. * `fetchQueryItems(collectionName, selector)` is called when a selector is registered by its first observer. It must resolve to an array of items; an item that already exists locally is combined with the fetched one through `mergeItems` (default: a shallow spread, the fetched fields win). * `registerRemoteChange` is called once, when the adapter is constructed. Call the `onChange` it hands you whenever the remote data changed, and every selector that is currently observed is fetched again. * When the last observer of a selector goes away, the adapter waits `purgeDelay` milliseconds (default `10000`, `0` purges at once) and then removes the items that selector fetched, unless another selector that has not been purged yet fetched them as well. Only items a fetch delivered are purged — even if you have written to them since; an item that only ever came from your own writes stays. A query on a selector that is not observed yet is answered once its first fetch has settled: until then `isLoading()` is `true` and the cursor serves its neutral empty result, and an `{ async: true }` read resolves after the fetched items have been stored. The answer then comes from the local cache, which holds the fetched items alongside everything stored earlier. If that fetch fails, the query settles as failed — see `onError` and the collection's `query.error` event. Later fetches of the same selector, triggered by `registerRemoteChange`, arrive as ordinary updates. [Reference →](/reference/core/autofetchdataadapter/) ### Queries on these adapters are asynchronous The async, worker and auto-fetch adapters cannot answer a query on the spot. A reactive cursor serves its neutral result — an empty list, a count of zero — until the answer arrives, so either await the result or check [`Cursor#isLoading()`](/reference/core/cursor/#⚡️-isloading-reactive) inside the reactive scope: ```js // outside a reactive scope: wait for the answer const posts = await Posts.find({ authorId: 'user1' }, { async: true }).fetch() // inside one: tell "not answered yet" apart from "nothing matched" effect(() => { const cursor = Posts.find({ authorId: 'user1' }) if (cursor.isLoading()) return renderSpinner() render(cursor.fetch()) }) ``` A query that fails for good does not throw anywhere — the cursor keeps its neutral result and the collection emits [`query.error`](/queries/#collection-events). See [Queries that are not answered immediately](/queries/#queries-that-are-not-answered-immediately) for the full picture. ## Writing your own A data adapter is one method: ```ts import type { DataAdapter, CollectionBackend } from '@signaldb/core' const myAdapter: DataAdapter = { createCollectionBackend(collection, indices) { // return an object implementing CollectionBackend }, } ``` `createCollectionBackend` is called once per collection and returns the object that answers everything for it: the six write methods, the query registration and reading methods, and two lifecycle methods. The full contract is on the [`DataAdapter` reference page](/reference/core/dataadapter/). Two things are worth knowing before you start. **A query that has not been answered yet publishes a neutral result.** An empty list is a legitimate answer, so a consumer cannot tell "nothing matched" from "not answered yet" by looking at the result. `getQueryState` is what makes the difference visible, and it is why an adapter that can fail must publish `'error'` rather than leaving the query sitting on its empty value forever. **A delta is a promise about the previous result.** When your adapter tells a listener that a query completed, it may pass a [`QueryDelta`](/reference/core/dataadapter/#querydelta) describing how the result changed — which saves the listener from comparing the whole new result against the whole old one. That delta must be relative to what `getQueryResult` returned the last time it was asked. If your adapter layers anything on top of its stored result — an optimistic write still in flight, say — omit the delta while it does. A wrong delta is worse than no delta: it desynchronises the consumer silently and permanently, and omitting it costs nothing but a comparison. --- --- url: /reactivity.md --- # Reactivity & Optimistic UI Today, users demand near-instant feedback from their applications, expecting smooth and seamless interactions. Traditional asynchronous operations can sometimes slow down this experience. That's the reason why SignalDB uses reactivity and makes it easy to achieve an Optimistic UI. ## Understanding Optimistic UI Optimistic UI is a design pattern where the application UI is updated immediately based on the expected result of an action, without waiting for a server's confirmation. It's all about improving the perceived performance of the application and delivering a more responsive user experience. Key benefits of Optimistic UI are an improved User Experience (UX) and a general improved responsiveness of an application. Immediate feedback enhances user confidence in the application. The application feels more faster, since it will not wait for server confirmation and this means there's no noticeable lag for the user. ## SignalDB's Role in Promoting Optimistic UI SignalDB's reactive architecture, combined with its memory storage, forms the backbone for implementing Optimistic UI. The database allows instant updates to the UI based on anticipated changes, which are then synchronized with actual data once it's processed. ### Signals and Reactivity SignalDB harnesses signals, derived from functional reactive programming, to manage reactivity. The resurgence of signals, particularly after the popularity of solidjs in 2023, places SignalDB in a prime position. 1. **Integration with Signal Libraries**: SignalDB's design remains neutral to any particular signal library, offering integration through reactivity adapters. This compatibility ensures an up-to-date UI in tandem with data changes. 2. **Reactivity Adapters**: With these adapters, SignalDB can instantly query documents within a collection reactively. They seamlessly integrate with signal libraries, ensuring auto-updates to reactive queries when data changes. By providing a smooth, responsive user experience, SignalDB ensures that user interactions remain at the forefront of modern web design and functionality. ### Data Persistence and Optimistic UI Where a collection keeps its data is decided by its [data adapter](/data-adapters/): the `DefaultDataAdapter` keeps it in memory, while other data adapters read it from storage or run the queries in a Web Worker. Keeping the data across sessions or reloads is the job of [storage adapters](/data-persistence/), which persist it in localStorage, IndexedDB, OPFS or the file system. When coupled with Optimistic UI, the user's experience remains unaffected even while a write is still on its way to storage. Also check out the [core concepts about reactivity](/core-concepts/#signals-and-reactivity). ## Reactivity Libraries We provide prebuilt reactivity adapters for existing reactivity libraries. If an adapter is missing, feel free to request it by [opening an issue at Github](https://github.com/maxnowack/signaldb/issues/new) or write one at your own. See [createReactivityAdapter](/reference/core/createreactivityadapter/) for more information. For some libraries, it wasn't possible to implement a [`onDispose`](/reference/core/createreactivityadapter/#ondispose-callback-void-dependency-dependency-optional) method in the adapter. That means that you have to [cleanup the cursor](/reference/core/cursor/) manually after the reactive context was closed. There are examples on the specific adapter documentation pages. Make sure that you implement it properly, since not doing this can lead to memory leaks. [Scope checking](/reference/core/createreactivityadapter/#isinscope-boolean-optional) is only supported by a few libraries. Scope checking means, that SignalDB is not able to check if a cursor was created from a reactive scope (([`find`](/reference/core/collection/#find-selector-selector-t-options-options)/[`findOne`](/reference/core/collection/#findone-selector-selector-t-options-options) called in an `effect` function)) and applies the required event handlers used to provide the reactivity. To avoid memory leaks, use an adapter with scope checking or pass `{ reactive: false }` to your options(e.g. `.find({ … }, { reactive: false })`). | Library | Reactivity adapter | Automatic Cleanup | Scope check | |---|---|---|---| | [`@preact/signals-core`](/reference/preact/) | ✅ | ❌ | ❌ | | [`@reactively/core`](/reference/reactively/) | ✅ | ✅ | ❌ | | [`@webreflection/signal`](https://github.com/WebReflection/signal) | ❌ | - | - | | [`alien-signals`](https://github.com/maxnowack/signaldb/issues/1341) | ✅ | ❌ | ❌ | | [`Angular Signals`](/reference/angular/) | ✅ | ❌ | ❌ | | [`Maverick-js Signals`](/reference/maverickjs/) | ✅ | ✅ | ✅ | | [`Meteor Tracker`](/reference/meteor/) | ✅ | ✅ | ✅ | | [`MobX`](/reference/mobx/) | ✅ | ✅ | ❌ | | [`oby`](/reference/oby/) | ✅ | ✅ | ✅ | | [`Qwik`](https://qwik.dev/docs/components/state/) | ❌ | - | - | | [`S.js`](/reference/sjs/) | ✅ | ✅ | ❌ | | [`signal-polyfill`](https://github.com/proposal-signals/signal-polyfill) | ❌ | - | - | | [`signia`](https://signia.tldraw.dev/) | ❌ | - | - | | [`sinuous`](/reference/sinuous/) | ✅ | ✅ | ❌ | | [`Solid Signals`](/reference/solid/) | ✅ | ✅ | ✅ | | [`sprae`](https://github.com/dy/sprae) (see [#858](https://github.com/maxnowack/signaldb/issues/858)) | ✅ | ❌ | ❌ | | [`Svelte Runes`](/reference/svelte/) | ✅ | ✅ | ✅ | | [`ulive`](https://github.com/kethan/ulive) | ❌ | - | - | | [`usignal`](/reference/usignal/) | ✅ | ❌ | ❌ | | [`Vue.js refs`](/reference/vue/) | ✅ | ❌ | ❌ | --- --- url: /sync.md --- # Sync Engine: Synchronization in SignalDB ## Introduction to Sync in SignalDB SignalDB ships with a **sync engine** for [local-first](/local-first/) and [offline-first](/offline-first/) apps. It records every local change, persists the queue of pending changes, pushes them to your backend, pulls remote changes, and resolves conflicts, while your app keeps reading and writing local data. Unlike sync engines that require a specific server or database, SignalDB's sync engine works with any backend: you provide a `pull` and a `push` function. SignalDB is designed to handle synchronization efficiently and flexibly, making it adaptable to various backend systems. At its core, synchronization in SignalDB revolves around ensuring that data across multiple collections remains consistent and up-to-date, whether you are working with a local-first approach or integrating with remote servers. ### High-Level Overview In SignalDB, synchronization is managed by the [`SyncManager`](/reference/sync/#syncmanager) class, which is central to the framework's ability to maintain data consistency. The [`SyncManager`](/reference/sync/#syncmanager) is responsible for coordinating the synchronization process for multiple collections, pulling and pushing data as needed. This centralization provides several key benefits: * **Flexibility**: SignalDB's sync mechanism is designed to work with any backend system, from REST APIs to GraphQL and beyond. This flexibility means you can integrate SignalDB with virtually any data source without worrying about compatibility issues. * **Efficiency**: Instead of handling synchronization for each collection separately, the [`SyncManager`](/reference/sync/#syncmanager) allows you to manage sync operations for all collections from a single instance. This streamlined approach simplifies the development process, reducing the need for repetitive code and minimizing potential synchronization errors. ### Role of the SyncManager The `SyncManager` class plays a pivotal role in SignalDB by: * **Managing Multiple Collections**: A single [`SyncManager`](/reference/sync/#syncmanager) instance can oversee the sync operations for multiple collections simultaneously. This centralized management ensures that changes in one collection can be synchronized with others effectively and efficiently. * **Improving Developer Experience**: By handling synchronization through one class instance, SignalDB enhances developer experience. You no longer need to call sync functions for each collection individually. Instead, you can manage all sync operations through the [`SyncManager`](/reference/sync/#syncmanager), which takes care of coordinating and executing these tasks behind the scenes. * **Conflict Resolution**: SignalDB provides built-in conflict resolution mechanisms to handle situations where data conflicts occur during synchronization. Conflict resolution ensures that the most recent changes are preserved, while maintaining data consistency across all collections. * **Queueing Sync Operations**: The [`SyncManager`](/reference/sync/#syncmanager) queues sync operations to ensure that they are executed in the correct order. This is particularly important when dealing with interdependent collections or when sync operations have dependencies on each other. * **Debouncing Pushes**: To optimize network usage and minimize unnecessary data transfers, the [`SyncManager`](/reference/sync/#syncmanager) debounces push operations. This means that multiple push operations for the same collection are merged into a single operation, reducing the number of network requests and improving performance. This approach not only simplifies your codebase but also helps maintain consistency and reliability across your application's data. ## Local-First Synchronization vs. On-Demand Fetching When it comes to data synchronization, SignalDB offers two primary strategies: local-first synchronization and on-demand fetching. Understanding the differences between these approaches can help you choose the best method for your application's needs. ### Local-First Synchronization In a local-first synchronization approach, data changes are managed and stored locally on the client device. The local data is periodically synchronized with the server, either automatically or manually. This method provides several key benefits: * **Performance**: Local-first syncing ensures that your application remains responsive, as data operations are performed locally before syncing with the server. This reduces the need for constant server interactions, leading to faster data retrieval and updates. * **Offline Support**: With local-first synchronization, users can continue interacting with your application even when they are offline. Changes are queued locally and synchronized once connectivity is restored, ensuring a seamless experience regardless of network conditions. * **Optimistic UI**: This approach allows for a smoother user experience by employing optimistic UI techniques. Users see immediate feedback on their actions (such as form submissions or data updates) while the sync process happens in the background. This eliminates the need for loading spinners or delays in user interactions. ### On-Demand Fetching On-demand fetching involves retrieving data directly from the server whenever it is needed. This method can be more suitable in certain scenarios: * **Up-to-Date Information**: For applications where having the most current data is essential, on-demand fetching guarantees that the latest information is always retrieved from the server. However it can lead to more network requests and potentially slower performance. * **Resource Efficiency**: If the data changes infrequently or if the application primarily relies on the most up-to-date information, on-demand fetching can be more resource-efficient. It reduces the need for local storage and minimizes the complexity of handling local changes. ### Comparison To help you better understand the differences, here's a comparison table highlighting the key aspects of each approach: | Aspect | Local-First Synchronization | On-Demand Fetching | |-------------------------|----------------------------------|----------------------------------| | **Performance** | High - operates locally, independent of server load and latency | Can be slower due to server request times | | **Offline Support** | Strong - allows for offline operations and synchronization later | Limited - relies on continuous connectivity | | **User Experience** | Smooth - uses optimistic UI for immediate feedback | May include delays or loading spinners during data fetch | | **Real-Time Accuracy** | May lag behind the server data if not synced frequently | Always retrieves the latest data from the server | | **Resource Usage** | Higher - requires local storage and management | Lower - no local storage needed | In summary, local-first synchronization is ideal for enhancing performance and offline capabilities, while on-demand fetching is suited for applications that prioritize real-time data accuracy. SignalDB’s flexibility allows you to choose the approach that best fits your use case. ## Syncing with Any Backend SignalDB is designed to offer versatile synchronization capabilities, making it compatible with a wide range of backend systems. Whether you're using REST APIs, GraphQL endpoints, or even custom protocols, SignalDB's modular architecture ensures smooth integration and synchronization. ### Backend-Agnostic Sync Mechanisms SignalDB's synchronization mechanism is inherently backend-agnostic. This means it can connect and sync with virtually any type of backend system without requiring major modifications. The framework abstracts the specifics of the server interactions, allowing developers to focus on integrating their chosen backend without being tied to a particular technology. ### Abstracting Server Interaction Central to this flexibility are the `pull` and `push` functions within the [`SyncManager`](/reference/sync/#syncmanager). These functions act as intermediaries between your application and the backend, abstracting the details of data retrieval and submission. This design ensures that: * **Pull Function**: Retrieves data from the server. You can define how data is fetched, whether it’s through a REST API call, a GraphQL query, or another method. This flexibility allows you to adapt to various server architectures with minimal effort. * **Push Function**: Sends local changes to the server. Similar to the pull function, you can specify how changes are transmitted, ensuring compatibility with your backend's requirements. This includes sending data through HTTP methods, websockets, or custom protocols. Additionally to this two functions, you can also register a function that can be called when the client receives live-updates from the server. With this concept, you can easily implement real-time updates in your application without the need to call the `pull` function everytime. ### Examples of Integration Here’s how SignalDB can be integrated with different backend systems: * **REST APIs**: SignalDB can interact with RESTful endpoints for both pulling and pushing data. For example, a `pull` function might fetch data from `/api/reference/core/collection/todos`, while the `push` function sends updates to the same endpoint. * **GraphQL**: For applications using GraphQL, SignalDB can perform queries and mutations. The `pull` function might execute a GraphQL query to retrieve collection data, and the `push` function could execute a mutation to submit changes. * **Custom Protocols**: If you have a custom backend or protocol, you can implement the `pull` and `push` functions to accommodate these specifics. This ensures that SignalDB remains adaptable to unique or proprietary systems. * **Live Updates**: SignalDB can also work with real-time updates through technologies like WebSockets or server-sent events. By integrating live update mechanisms, SignalDB can maintain real-time data synchronization across all clients. In summary, SignalDB’s design ensures that you can synchronize data seamlessly with any backend system. Its modular approach, with abstracted `pull` and `push` functions, provides the flexibility to integrate with various technologies while maintaining efficient and reliable synchronization. ## Sync Flow & Conflict Resolution SignalDB’s synchronization process is designed to efficiently handle the flow of data between the client and server, ensuring that local changes are correctly synchronized while managing conflicts in a straightforward manner. To do that, SignalDB tracks all changes made locally to the data. This includes insertions, updates, and removals. These changes are logged and queued for synchronization with the server. To handle conflicts, SignalDB uses a "replay" mechanism during synchronization. This involves: * **Replaying Changes**: Local changes are applied to the latest data fetched from the server. This ensures that any conflicts are resolved based on the most recent data. * **Handling Conflicts**: The "last change operation wins" strategy is employed, where changes are replayed on the latest data, and conflicts are resolved by applying the most recent operations. ### Sync Flow SignalDB’s sync process consists of several key steps: * **Client Pulls Data**: The client retrieves the latest data from the server. This is the initial step where the client gets up-to-date information from the backend. In a real-time scenario, this could also be triggered by a live-update from the server that notifies the client about changes. * **Replay Changes**: Any local changes (such as inserts, updates, or removals) since last sync are applied on the new data to check which actual changes need to be pushed to the server. This step ensures that local modifications are applied to the updated data set, maintaining consistency and avoiding overwrites of remote changes. * **Pushes Changes**: After applying local changes to the latest data, the client pushes these changes to the server. This ensures that the server receives and records the client’s updates. * **Pulls Again for Verification**: Finally, the client performs another pull to verify that all changes have been correctly applied and synchronized with the server. The following pseudo code shows the sync flow in detail. It's based on the actual implementation of the sync function, but it's simplified to illustrate the main concepts. ```js async function sync(changes, lastSnapshot, newData) { let dataFromServer = await pullDataFromServer(); if (changes) { let localSnapshot = applyChangesToSnapshot(changes, lastSnapshot); if (hasDifference(localSnapshot, lastSnapshot)) { let newSnapshot = applyChangesToSnapshot(changes, newData); if (hasDifference(newData, newSnapshot)) { pushChangesToServer(newSnapshot); dataFromServer = pullUpdatedData(); } } } updateDataOnCollection(dataFromServer); } ``` ### Conflict Resolution SignalDB uses a “last change operation wins” strategy to handle conflicts during synchronization. Here’s how it works: * **Replay Mechanism**: When the client pulls the latest data, it replays all logged changes on top of this data. This ensures that any modifications made locally are applied to the most recent version of the data from the server. * **Last Change Wins**: In cases where conflicts arise (e.g., when the same item has been modified both locally and on the server), the latest change operation takes precedence. The client's local changes are replayed on the most recent server data, ensuring that the latest state is reflected. This strategy is suitable for many applications because it simplifies conflict resolution by ensuring that the most recent changes are applied. It also helps maintain a consistent state across clients by synchronizing modifications in a clear and predictable manner. This chart illustrates the conflict resolution process: ```mermaid sequenceDiagram Server->>+Client 1: pulls data Client 1-->>Client 1: logs operations A, B Server->>+Client 2: pulls data Client 2-->>Client 2: logs operations C, D Server->>Client 1: pulls latest data Client 1-->>Client 1: replays operations A, B on latest data Client 1->>-Server: pushes data Server->>Client 1: pulls latest data Server->>Client 2: pulls latest data Client 2-->>Client 2: replays operations C, D on latest data Client 2->>-Server: pushes data Server->>Client 2: pulls latest data ``` ## Implementing Synchronization This page describes how remote synchronization could be implemented on the frontend side. ### Creating a [`SyncManager`](/reference/sync/) The `SyncManager` is the main class that handles synchronization. To get started with implementing synchronization in your app, you need to create a [`SyncManager`](/reference/sync/#syncmanager) instance. The `SyncManager` constructor takes an option object as the first and only parameter. This object contains the methods for your `pull` and `push` logic. It also takes a `dataAdapter`. The sync manager keeps three collections of its own — snapshots, changes and sync operations — and that is where they live. Pass the same [data adapter](/data-adapters/) your own collections use, so the bookkeeping is stored alongside your data. Leave it out and it defaults to an in-memory adapter: synchronization works, but a reload loses the record of what was already pushed. With [`@signaldb/indexeddb`](/reference/indexeddb/), the database `schema` has to contain the sync manager's stores as well — see [Using it with a `SyncManager`](/reference/indexeddb/#using-it-with-a-syncmanager). A `reactivity` adapter makes some of the functions provided by the [`SyncManager`](/reference/sync/#syncmanager) reactive (e.g. `isSyncing()`). There is also a `registerRemoteChange` method that can be used to register a method for notifying the [`SyncManager`](/reference/sync/#syncmanager) about remote changes. ```ts import { DefaultDataAdapter } from '@signaldb/core' import { SyncManager } from '@signaldb/sync' import createLocalStorageAdapter from '@signaldb/localstorage' const dataAdapter = new DefaultDataAdapter({ storage: name => createLocalStorageAdapter(name), }) const syncManager = new SyncManager({ dataAdapter, reactivity: someReactivityAdapter, pull: async () => { // your pull logic }, push: async () => { // your push logic }, registerRemoteChange: (collectionOptions, onChange) => { // … } }) ``` ### Adding Collections Before we go in the details of the `pull` and `push` methods, we need to understand how we add collection to our `syncManager`. The `addCollection` method takes two parameters. The first one is the collection itself and the second one is an option object. This object must contain at least a `name` property that will be used to identify the collection in the `syncManager`. You can also pass other informations to the options object. These properties will be passed to your `push` & `pull` methods and can be used to access additionally informations about the collection that are needed for the synchronization (e.g. api endpoint url). This concept also allows you to do things like passing `canRead`/`canWrite` methods to the options that are later on used to check if the user has the necessary permissions to `pull`/`push`. ```ts import { Collection } from '@signaldb/core' const someCollection = new Collection('someCollection', dataAdapter) syncManager.addCollection(someCollection, { name: 'someCollection', apiPath: '/api/someCollection', }) ``` ### Implementing the `pull` method After we've added our collection to the `syncManager`, we can start implementing the `pull` method. The `pull` method is responsible for fetching the latest data from the server and applying it to the collection. The `pull` method is called whenever the `syncAll` or the `sync(name)` method are called. During sync, the `pull` method will be called for each collection that was added to the `syncManager`. It's receiving the collection options, passed to the `addCollection` method, as the first parameter and an object with additional information, like the `lastFinishedSyncStart` and `lastFinishedSyncEnd` timestamps, as the second parameter. The `pull` method must return a promise that resolves to an object with either: * an `items` property containing **_all items_** from the server, without limiting the result set (`syncManager` will internally do a snapshot comparison between the local and the fetched items to determine and apply the changes to the collection): ```ts const syncManager = new SyncManager({ // … pull: async ({ apiPath }) => { const data = await fetch(apiPath).then(res => res.json()) return { items: data } }, // … }) ``` * or a `changes` property containing only changes (`{ added: T[], modified: T[], removed: T[] }`) since the last sync (this is usefull when we do not want to always fetch the full data set from the server): ```ts const syncManager = new SyncManager({ // … pull: async ({ apiPath }, { lastFinishedSyncStart }) => { const data = await fetch(`${apiPath}?since=${lastFinishedSyncStart}`).then(res => res.json()) return { changes: data } }, // … }) ``` ### Implementing the `push` method The `push` method is responsible for sending the changes to the server. The `push` method is called during sync for each collection that was added to the `syncManager` if changes are present. It's receiving the collection options, passed to the `addCollection` method, as the first parameter and an object including the changes that should be sent to the server as the second parameter. The `push` method returns a promise without a resolved value. If an error occurs during the `push`, the sync for the collection will be aborted and the error will be thrown. **There are some errors that need to be handled by yourself. These are normally validation errors (e.g. `4xx` status codes) were the sync shouldn't fail, but the local data should be overwritten with the latest server data.** If you throw these errors in your `push` method, the `syncManager` will keep the changes passed to the `push` method and will try to `push` them again on the next sync. This can lead to a loop where the changes are never pushed successfully to the server. To prevent this, handle those errors in the `push` method and just return afterwards. ```ts const syncManager = new SyncManager({ // … push: async ({ apiPath }, { changes }) => { await Promise.all(changes.added.map(async (item) => { const response = await fetch(apiPath, { method: 'POST', body: JSON.stringify(item) }) if (response.status >= 400 && response.status <= 499) return await response.text() })) await Promise.all(changes.modified.map(async (item) => { const response = await fetch(apiPath, { method: 'PUT', body: JSON.stringify(item) }) if (response.status >= 400 && response.status <= 499) return await response.text() })) // there is also the changes.modifiedFields property that contains the modified fields per item id if you prefer PATCH requests await Promise.all([...changes.modifiedFields.keys()].map(async (itemId) => { const fields = changes.modifiedFields.get(itemId) const item = changes.modified.find(item => item.id === itemId) const change = fields.reduce((memo, field) => { memo[field] = get(item, field) return memo }, {}) const response = await fetch(apiPath, { method: 'PATCH', body: JSON.stringify(change), }) if (response.status >= 400 && response.status <= 499) return await response.text() })) await Promise.all(changes.removed.map(async (item) => { const response = await fetch(apiPath, { method: 'DELETE', body: JSON.stringify(item) }) if (response.status >= 400 && response.status <= 499) return await response.text() })) }, // … }) ``` ### Handle Remote Changes To handle remote changes for a specific collection, you have to get the event handler to call on remote changes through the `registerRemoteChange` method. This method gets the `collectionOptions` as the first parameter and an `onChange` handler a the second parameter. The `onChange` handler can be called after changes were received from the server for the collection that matches the provided `collectionOptions`. The `onChange` handler takes optionally the changes as the first parameter. If the changes are not provided, the `pull` method will be called for the collection. ```ts const syncManager = new SyncManager({ // … registerRemoteChange: (collectionOptions, onChange) => { someRemoteEventSource.addEventListener('change', (collection) => { if (collectionOptions.name === collection) onChange() }) }, // … }) ``` ### Example Implementations #### Simple RESTful API Below is an example implementation of a simple REST API. ```js import { Collection, DefaultDataAdapter, EventEmitter } from '@signaldb/core' import { SyncManager } from '@signaldb/sync' const dataAdapter = new DefaultDataAdapter() const Authors = new Collection('authors', dataAdapter) const Posts = new Collection('posts', dataAdapter) const Comments = new Collection('comments', dataAdapter) const errorEmitter = new EventEmitter() errorEmitter.on('error', (message) => { // display validation errors to the user }) const apiBaseUrl = 'https://example.com/api' const syncManager = new SyncManager({ pull: async ({ apiPath }) => { const data = await fetch(`${apiBaseUrl}${apiPath}`).then(res => res.json()) return { items: data } }, push: async ({ apiPath }, { changes }) => { await Promise.all(changes.added.map(async (item) => { const response = await fetch(apiPath, { method: 'POST', body: JSON.stringify(item) }) const responseText = await response.text() if (response.status >= 400 && response.status <= 499) { errorEmitter.emit('error', responseText) return } })) await Promise.all(changes.modified.map(async (item) => { const response = await fetch(apiPath, { method: 'PUT', body: JSON.stringify(item) }) const responseText = await response.text() if (response.status >= 400 && response.status <= 499) { errorEmitter.emit('error', responseText) return } })) await Promise.all(changes.removed.map(async (item) => { const response = await fetch(apiPath, { method: 'DELETE', body: JSON.stringify(item) }) const responseText = await response.text() if (response.status >= 400 && response.status <= 499) { errorEmitter.emit('error', responseText) return } })) }, }) syncManager.addCollection(Posts, { name: 'posts', apiPath: '/posts', }) syncManager.addCollection(Authors, { name: 'authors', apiPath: '/authors', }) syncManager.addCollection(Comments, { name: 'comments', apiPath: '/comments', }) ``` #### More Examples If you think that an example is definitely missing here, feel free to create a pull request. Also don't hesitate to create a [discussion](https://github.com/maxnowack/signaldb/discussions/new/choose) if you have any questions or need help with your implementation. --- --- url: /orm.md --- # Object-Relational Mapping (ORM) with SignalDB SignalDB provides functionality to add methods to [collections](/reference/core/collection/) and item instances to enable ORM-like behavior. With this functionality, you can also reactively resolve relationships between items in different collections. ## Adding Instance Methods to Collections To add new methods to a specific collection instance, we have to create a new class that inherits from the collection class. With this approach, it's also possible to directly define collection options like the name or the data adapter. In the example below, we create a new class `PostsCollection` that inherits from the `Collection` class and add a new method `findPublishedPosts` to the class. This method returns a `Cursor` to all published posts from the collection. ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' const dataAdapter = new DefaultDataAdapter() class PostsCollection extends Collection { constructor() { super('posts', dataAdapter, { reactivity: /* specify reactivity options */, }) } // instance method to find all published posts findPublishedPosts() { return this.find({ published: true }) } } const Posts = new PostsCollection() const publishedPosts = Posts.findPublishedPosts().fetch() ``` You can use this pattern to add methods to your collection that predefines queries that you use often in your application like in the example above. You can also override existing methods like `removeOne` or `updateOne` to add custom behavior or custom checks to your collection. If you want to check if a user has the permission to delete or update a post for example. ## Adding Instance Methods to Items To add new instance methods to a specific item instance, we have to create a new class for item instances and transform items to an instance of this class using the [`transform` option](/reference/core/collection/#constructor) of the collection. ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' class Post { constructor(data) { Object.assign(this, data) } hasComments() { return this.comments.length > 0 } } const Posts = new Collection('posts', new DefaultDataAdapter(), { transform: item => new Post(item), }) ``` In the example above, we create a new class `Post` that adds a new instance method `hasComments` to the class. This method returns `true` if the post has comments and `false` if not. ## Resolving Relationships With the ORM functionality, you can also resolve relationships between items in different collections. You can even chain them together later on in your code to build complex queries that span multiple collections and also reactively rerun on changes. ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' class Post { constructor(data) { Object.assign(this, data) } getAuthor() { return Users.findOne(this.authorId) } getComments() { return Comments.find({ postId: this.id }) } } class Comment { constructor(data) { Object.assign(this, data) } getAuthor() { return Users.findOne(this.authorId) } } class User { constructor(data) { Object.assign(this, data) } getPosts() { return Posts.find({ authorId: this.id }) } } const dataAdapter = new DefaultDataAdapter() const Posts = new Collection('posts', dataAdapter, { transform: item => new Post(item) }) const Users = new Collection('users', dataAdapter, { transform: item => new User(item) }) const Comments = new Collection('comments', dataAdapter, { transform: item => new Comment(item) }) effect(() => { const lastPost = Posts.findOne({}, { sort: { createdAt: -1 }, }) // get the author of the last comment of the last post const authorOfLastComment = lastPost.getComments().fetch()[0].getAuthor() // get comment count of all posts of the author let commentCount = 0 authorOfLastComment.getPosts().forEach((post) => { commentCount += post.getComments().count() }) }) ``` In the example above, we create three classes `Post`, `Comment`, and `User` that add new instance methods to the classes. These methods resolve relationships between items in different collections. With this functionality, you can move complex queries to the item classes and run them in a more declarative way in your application code. ## TypeScript Support Adding instance methods to collection or item instances requires using a helper class to maintain type safety for the instance class. This is because we need to include all properties in the class interface. ```ts declare interface BaseEntity extends T {} class BaseEntity { constructor(data: T) { Object.assign(this, data) } } ``` With this helper class, you only need to inherit from BaseEntity and provide the item type as a generic parameter to the class. ```ts interface PostType { id: string, title: string, content: string, authorId: string, createdAt: number, } class Post extends BaseEntity { getAuthor() { return Users.findOne(this.authorId) } } ``` ## Solving the N+1 Problem with transformAll While the instance method approach (like `post.getAuthor()`) is convenient for accessing related data on individual items, it can lead to the "N+1 problem" when dealing with multiple items. If you fetch N posts and then call `getAuthor()` on each, you might end up making N additional database queries (1 query for the posts + N queries for the authors). To address this, SignalDB offers an `transformAll` option in the `Collection` constructor. This allows you to define a function that efficiently pre-loads related data in bulk for a set of items *before* they are returned by a query, significantly reducing the number of database operations. ### How transformAll Works The `transformAll` function you provide receives up to three arguments: 1. `items`: An array of items that matched the query's filter, *after* sorting and limiting, but *before* being returned. 2. `fields`: The `fields` projection object specified in the query options (e.g., `{ name: 1, author: 1 }`). 3. `mode`: `{ async: true }` when the query is read with `async: true`, otherwise nothing. Inside this function, you can: 1. **Check `fields`:** Determine if the related data field (e.g., `author`) was actually requested in the query. This prevents unnecessary fetching. 2. **Collect Foreign Keys:** Extract the unique IDs (foreign keys) needed to fetch the related data from the `items` array. 3. **Bulk Fetch:** Perform a *single* query on the related collection (e.g., `Users`) to retrieve all necessary related items at once using the collected keys (e.g., using `$in`). 4. **Map Data:** Return a new list in which each item carries the fetched related object alongside (or instead of) its foreign key. This process happens automatically whenever a query using the relevant `fields` is executed or re-runs due to reactivity. ### Reading related data the way the query is read A query is read [synchronously inside a reactive scope, and with `async: true` everywhere else](/queries/#reactive-or-awaited). The related data has to be read the same way: synchronously, so that a change to it reruns the scope, or awaited, so that an asynchronous read gets the real data instead of a [neutral empty result](/queries/#queries-that-are-not-answered-immediately). Build `transformAll` with [`reactiveOrAsync`](/reference/core/utilities/#reactiveorasync-generator-and-unwrap-value) to write that once. It receives `async` as its first argument, and `yield* unwrap(…)` hands back the result of a read whether it was synchronous or awaited. SignalDB calls `transformAll` with `{ async: true }` for an asynchronous read and awaits it; for every other read it calls it synchronously. ### Example Let's redefine our `Posts` and `Users` collections to use transformAll for fetching authors: ```js import { Collection, DefaultDataAdapter, reactiveOrAsync, unwrap } from '@signaldb/core' import maverickjsReactivityAdapter from '@signaldb/maverickjs' const dataAdapter = new DefaultDataAdapter() // User Collection (No changes needed here for this example) const Users = new Collection('users', dataAdapter, { reactivity: maverickjsReactivityAdapter, }) // Populate Users await Users.insert({ id: 'user1', name: 'Alice' }) await Users.insert({ id: 'user2', name: 'Bob' }) // Post Collection with transformAll const Posts = new Collection('posts', dataAdapter, { reactivity: maverickjsReactivityAdapter, // --- transformAll Function --- transformAll: reactiveOrAsync(function* (async, items, fields) { // 1. Check if the 'author' field is requested if (!fields?.author) return items // 2. Collect unique author IDs const authorIds = [...new Set(items.map(item => item.authorId))] // 3. Bulk fetch authors, the same way the query itself is read const relatedAuthors = yield* unwrap(Users.find({ id: { $in: authorIds } }, { async }).fetch()) // 4. Map authors back to posts return items.map(item => ({ ...item, author: relatedAuthors.find(author => author.id === item.authorId), })) }), }) // Populate Posts await Posts.insert({ id: 'post1', title: 'First Post', authorId: 'user1' }) await Posts.insert({ id: 'post2', title: 'Second Post', authorId: 'user2' }) await Posts.insert({ id: 'post3', title: 'Third Post', authorId: 'user1' }) // --- Usage --- // Query requesting the author field - transformAll runs const postsWithAuthors = await Posts.find({}, { fields: { title: 1, author: 1 }, async: true }).fetch() console.log(postsWithAuthors) /* Output: [ { id: 'post1', title: 'First Post', author: { id: 'user1', name: 'Alice' } }, { id: 'post2', title: 'Second Post', author: { id: 'user2', name: 'Bob' } }, { id: 'post3', title: 'Third Post', author: { id: 'user1', name: 'Alice' } } ] */ // Query NOT requesting the author field - transformAll is skipped for 'author' const postsWithoutAuthors = await Posts.find({}, { fields: { title: 1, authorId: 1 }, async: true }).fetch() console.log(postsWithoutAuthors) /* Output: [ { id: 'post1', title: 'First Post', authorId: 'user1' }, { id: 'post2', title: 'Second Post', authorId: 'user2' }, { id: 'post3', title: 'Third Post', authorId: 'user1' } ] */ ``` `transformAll` **returns** the transformed list rather than modifying `items` in place. Returning `items` unchanged, as the early return above does, is how you say "nothing to do for this query". A plain function that returns the list, without `reactiveOrAsync`, works as well. It is always called synchronously, so it reads related collections synchronously too — reactive inside a scope, but without waiting for an asynchronous adapter on an `async: true` read. ### Reactivity The transformAll process is fully integrated with SignalDB's reactivity system. If the data in the related collection changes (e.g., a user's name is updated), any reactive query that includes the transformAll field will automatically re-run and reflect the changes. ```js import { effect, Users, Posts } from './your-setup'; // Assuming Users, Posts, effect are set up/imported effect(() => { // This query requests the transformAll 'author' field const posts = Posts.find({ id: 'post1' }, { fields: { title: 1, author: 1 } }).fetch() console.log('Post 1 Author:', posts[0]?.author?.name) }) // Initial output: Post 1 Author: Alice // Now, update the related user await Users.updateOne({ id: 'user1' }, { $set: { name: 'Alice Smith' } }) // The effect will re-run automatically due to the change in Users // Updated output: Post 1 Author: Alice Smith ``` An `async: true` read is not reactive, and neither are the reads its `transformAll` makes: it returns the related data as it is at that moment. If the related collection uses an asynchronous [data adapter](/data-adapters/), [`isLoading()`](/reference/core/cursor/#⚡️-isloading-reactive) of the query stays `true` until the queries `transformAll` made have been answered too, so a list is not shown as loaded while its authors are still missing. By using the transformAll option, you can efficiently load related data, avoid the N+1 problem, and maintain reactivity, especially when dealing with lists or collections of items. This approach is often more performant than using instance methods for simple relationship loading in bulk scenarios. --- --- url: /devtools.md --- # Developer Tools ::: warning BETA The developer tools are currently in beta and may not be fully functional or stable. Please report any issues you encounter by opening an issue on [GitHub](https://github.com/maxnowack/signaldb/issues/new). ::: SignalDB provides a set of developer tools to help you debug and inspect the state of your SignalDB instance at runtime. To get started, add the `@signaldb/devtools` package to your `devDependencies` of your project. ```bash npm install --save-dev @signaldb/devtools ``` ## Usage To load the developer tools, you need to import `@signaldb/devtools` somewhere in your frontend code. Make sure that it doesn't get imported in production builds — see [Devtools in production](#devtools-in-production). Now you should see the SignalDB icon in the bottom left corner of your screen. You can open the developer tools by clicking on the icon or by pressing `Ctrl + Shift + S`. Importing the package is all there is to it — the import itself loads the tools, there is nothing to call: ```ts import '@signaldb/devtools' ``` The developer tools will open and you should the following tabs. ::: tip The developer tools will try to resolve names for your collections. Give a collection its name through the constructor: `new Collection('posts', dataAdapter)`. ::: ::: warning Importing the package calls [`Collection.enableDebugMode()`](/reference/core/collection/#enabledebugmode), which since v2 also switches on [`reportLargeQueries()`](/reference/core/collection/#reportlargequeries-rows-number-null) at 500 rows. Expect console output about live queries holding more than that — it is pointing at something worth looking at, see [troubleshooting](/troubleshooting/#the-application-has-slowly-grown-sluggish). ::: ### Devtools in production The package does not exclude itself from production builds. If it is imported there, it loads the tools, switches on debug mode for every collection and logs a warning to the console. Keep it out of production bundles by importing it only in development — with Vite, for instance: ```ts if (import.meta.env.DEV) { void import('@signaldb/devtools') } ``` If you want the tools available in production anyway, import the package lazily behind something you control — a query parameter, a feature flag — so that neither the tools nor debug mode load for ordinary visitors: ```ts if (new URLSearchParams(location.search).has('signaldb-devtools')) { void import('@signaldb/devtools') } ``` ### Data The data tab shows the current state of all of your SignalDB collections. You can inspect the collections, documents and even edit the data directly in the developer tools. ### Queries The queries tab shows all of the queries that have been executed on your SignalDB instance. Tracking all queries can decrease performance. You can deactivate tracking of queries by unticking the checkbox right next to the tab name. ### Mutations The mutations tab shows all of the mutations that have been executed on your SignalDB instance. Tracking all mutations can decrease performance. You can deactivate tracking of mutations by unticking the checkbox right next to the tab name. ### Performance The performance tab shows the time measurements of your queries of your SignalDB instance. You can see how long it took to execute queries. Tracking performance can decrease performance. You can deactivate tracking of performance by unticking the checkbox right next to the tab name. ### Settings The settings tab allows you to configure the developer tools. You can change if the button should be shown (you can still open the developer tools with `Ctrl + Shift + S`) and what should be shown as a badge on the button. You can choose between collection count, query count or disable the badge. ::: tip Also make sure to check out the examples listed in the sidebar. We've included the developer tools there as well. ::: --- --- url: /schema-validation.md --- # Schema Validation in SignalDB Although SignalDB is schema-less by design, it provides a mechanism to validate items against a defined schema before they are saved to the database. This is achieved by emitting a [`validate`](/reference/core/collection/#events) event with the item as its argument. If no handler is registered for this event, the item is automatically considered valid and is saved. However, by registering your own handler for the [`validate`](/reference/core/collection/#events) event, you can enforce custom validation rules and prevent invalid items from being stored by throwing an error. **Key Points:** * **Validation Trigger:** Before an item is saved, the [`validate`](/reference/core/collection/#events) event is emitted. * **Custom Validation:** You can register a handler to check the item against any schema or rule set. * **Default Behavior:** Without a handler, all items are treated as valid. * **Error Handling:** Throwing an error in your handler stops the item from being saved. ## Basic Usage Below is an example of how to register a simple validation for a collection: ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' const Posts = new Collection('posts', new DefaultDataAdapter()) // Register a validation handler that ensures each post has a 'title' Posts.on('validate', (post) => { if (!post.title) { throw new Error('Title is required') } }) // This insertion works because 'title' is provided await Posts.insert({ title: 'Hello, World!' }) // This insertion rejects due to the missing 'title' await Posts.insert({ author: 'Joe' }) ``` ## Advanced Example with Zod For more robust validation, you can integrate a library like [Zod](https://zod.dev) to define and enforce schemas. A dedicated `SchemaCollection` class acts as a wrapper around SignalDB's `Collection`, automatically validating items against a provided Zod schema. This approach ensures both runtime validation and compile-time type safety by inferring types directly from the schema. ```ts import { Collection } from '@signaldb/core' import type { BaseItem, CollectionOptions, DataAdapter } from '@signaldb/core' import type { ZodSchema, infer as ZodInfer } from 'zod' interface SchemaCollectionOptions< T extends ZodSchema>, I, U = ZodInfer, > extends CollectionOptions, I, ZodInfer, U> { schema: T, } class SchemaCollection< T extends ZodSchema>, I = any, U = ZodInfer, > extends Collection, I, ZodInfer, U> { private schema: T constructor( name: string, dataAdapter: DataAdapter, options: SchemaCollectionOptions, ) { super(name, dataAdapter, options) this.schema = options.schema // Automatically validate each item against the Zod schema before saving this.on('validate', (item) => { this.schema.parse(item) }) } } ``` You can now create a collection with schema validation using `SchemaCollection`: ```ts import { DefaultDataAdapter } from '@signaldb/core' import { z } from 'zod' const Posts = new SchemaCollection('posts', new DefaultDataAdapter(), { schema: z.object({ title: z.string(), content: z.string(), }), }) // This insertion is valid because it meets the schema requirements await Posts.insert({ title: 'Hello, World!', content: 'This is a post content.' }) // This insertion rejects because the 'content' field is missing await Posts.insert({ title: 'Hello, World!' }) ``` ## Additional Considerations * **Error Management:** Because writes are asynchronous, a failed validation surfaces as a rejected promise. Await the write and catch it, or the failure ends up in an unhandled rejection instead of in front of the user. * **Extensibility:** While the advanced example uses Zod, you can integrate other validation libraries in a similar manner by modifying the event handler. * **Type-Safety:** Leveraging schema validation with a tool like Zod not only validates runtime data but also infers types, reducing redundancy in your type definitions. By using SignalDB's built-in validation mechanism, you can maintain data integrity even in a flexible, schema-less environment, while still enjoying the benefits of custom validation rules and type safety. --- --- url: /upgrade/v2.md --- # Upgrade to v2 This guide explains what changed in SignalDB v2 and how to migrate your application safely. It focuses on API changes, the new DataAdapter/StorageAdapter split, and practical before/after examples. ## Summary of Breaking Changes * CRUD methods on `Collection` are async now. * `insert`, `insertMany`, `updateOne`, `updateMany`, `replaceOne`, `removeOne`, `removeMany` return Promises. * They resolve to what they returned synchronously in v1: the new ID(s) or the number of affected items (see examples below). * Indices are configured as simple field names: `indices: string[]`. * Persistence was renamed and redesigned: * `PersistenceAdapter` → `StorageAdapter` (new API shape). * `createPersistenceAdapter` → `createStorageAdapter`. * `combinePersistenceAdapters` was removed. * The storage adapters shipped with SignalDB changed their configuration and their storage layout. **Data written by v1 is not read by v2** — see [Storage adapters: your existing data](#storage-adapters-your-existing-data). * `AutoFetchCollection` was removed. Use `AutoFetchDataAdapter` instead. * Persistence events on `Collection` were removed. Each has a different replacement — see [Event Changes](#event-changes). * `createMemoryAdapter` and the `memory` option were removed. * `Collection#resetData()` was removed without replacement. To reload a collection from storage, dispose it and create it again. * Readiness API changed: `.isReady()` (promise) was renamed to `.ready()`. A new reactive `.isReady()` getter was added. * `isLoading()` on the `Collection` no longer describes the initial load. It starts out `false` and is `true` only while an `{ async: true }` query or a write is running. Use `ready()` / `isReady()` for the initial load and `Cursor#isLoading()` for a single query. * Collection constructor: prefer `new Collection(name, dataAdapter, options?)`; deprecated `persistence` option is still accepted and wrapped by `DefaultDataAdapter`. * `SyncManager`: the `persistenceAdapter` option was removed. Use `dataAdapter` instead. * `StorageAdapter.readIndex` now declares `Map>` instead of `Map>`. Only relevant if you wrote your own adapter — see [Custom storage adapters](#custom-storage-adapters-index-keys) below. * Observer semantics changed in two ways — see [Observer events](#observer-events) below. ## Core CRUD API (async) All write operations are asynchronous. Update your call sites to `await` them and adapt to the new return values. Before (v1): ```ts const id = Posts.insert({ title: 'Hello' }) Posts.updateOne({ id }, { $set: { title: 'Hi' } }) Posts.removeOne({ id }) ``` After (v2): ```ts const id = await Posts.insert({ title: 'Hello' }) // returns the inserted ID await Posts.updateOne({ id }, { $set: { title: 'Hi' } }) // resolves to number of updated items await Posts.removeOne({ id }) // resolves to number of removed items ``` Return values in v2: * `insert(item)` → `Promise` (inserted ID) * `insertMany(items)` → `Promise` (inserted IDs) * `updateOne(...)` → `Promise` (0 or 1) * `updateMany(...)` → `Promise` * `replaceOne(...)` → `Promise` (0 or 1) * `removeOne(...)` → `Promise` (0 or 1) * `removeMany(...)` → `Promise` ## Readiness and Loading * Promise-based readiness: `await collection.ready()` replaces `await collection.isReady()`. It resolves once the storage adapter is set up and its data has been loaded. * Reactive readiness: `collection.isReady()` now returns a reactive boolean that turns `true` at the same moment. * Loading states of a single query: [`cursor.isLoading()`](/reference/core/cursor/#⚡️-isloading-reactive) is reactive and `true` until the query has been answered. Use it to tell a query that has not been answered yet from one that legitimately matched nothing — both return an empty list. * Activity of the collection as a whole: * `collection.isPulling()` is a reactive boolean that is `true` while a `find(…, { async: true })` query is running. It does not reflect the initial load from storage or a sync pull. * `collection.isPushing()` is a reactive boolean that is `true` while a write is running. * `collection.isLoading()` is reactive and `true` if either of the two is. It starts as `false`. Before (v1): ```ts await collection.isReady() ``` After (v2): ```ts await collection.ready() // reactive checks (in a reactive context) collection.isReady() // initial load finished collection.find({ published: true }).isLoading() // this query not answered yet ``` ## Indices Configuration Indices are now defined by field names directly. Before (v1): ```ts import { createIndex } from '@signaldb/core' const Posts = new Collection({ indices: [ createIndex('title'), createIndex('author.id'), ], }) ``` After (v2): ```ts const Posts = new Collection({ indices: ['title', 'author.id'], }) ``` Remove any usages of `createIndex` and `createIndexProvider`. Use string field paths instead (dot-notation supported). ## Storage vs. Persistence The persistence layer has been renamed to Storage and modernized. * `PersistenceAdapter` → `StorageAdapter` (new API). * `createPersistenceAdapter` → `createStorageAdapter`. * `combinePersistenceAdapters` was removed. * Persistence-related `Collection` events were removed. See [Event Changes](#event-changes) for what replaces each of them. New `StorageAdapter` API surface: ```ts interface StorageAdapter { // lifecycle setup(): Promise teardown(): Promise // reads readAll(): Promise readIds(ids: I[]): Promise query?(query: StorageQuery): Promise> // optional // indices createIndex(field: string): Promise dropIndex(field: string): Promise readIndex(field: string): Promise>> // writes insert(items: T[]): Promise replace(items: T[]): Promise remove(items: T[]): Promise removeAll(): Promise } ``` Migration tips from old `PersistenceAdapter`: * Move one-time initialization into `setup()`, cleanup into `teardown()`. * Replace “load everything” with `readAll()`; selective lookups go through `readIds()`. * Replace “save/patch” with explicit `insert`, `replace`, `remove`, and `removeAll` operations. * Provide index operations (`createIndex`, `dropIndex`, `readIndex`) if your storage can accelerate queries (dot-notation field names are passed in). Minimal in-memory example for testing: ```ts import { createStorageAdapter } from '@signaldb/core' type Item = { id: string; [k: string]: any } export const memoryStorage = () => { let items: Item[] = [] return createStorageAdapter({ async setup() {}, async teardown() {}, async readAll() { return items }, async readIds(ids) { return items.filter(i => ids.includes(i.id)) }, async createIndex(field) { /* no-op for memory */ }, async dropIndex(field) { /* no-op */ }, async readIndex(field) { return new Map() }, async insert(newItems) { items = [...items, ...newItems] }, async replace(newItems) { const byId = new Map(items.map(i => [i.id, i])) for (const it of newItems) byId.set(it.id, it) items = [...byId.values()] }, async remove(toRemove) { const ids = new Set(toRemove.map(i => i.id)) items = items.filter(i => !ids.has(i.id)) }, async removeAll() { items = [] }, }) } ``` Note: For simple upgrades, you can still pass the deprecated `persistence` option to the `Collection` constructor; v2 wraps it with `DefaultDataAdapter`. Prefer the explicit DataAdapter + StorageAdapter setup for new code. ## Storage adapters: your existing data Every storage adapter shipped with SignalDB changed how it is configured and where it keeps its data, and none of them requires a `@signaldb/core` older than 2.0.0 anymore. **v2 does not read what v1 wrote.** The old data is left untouched, so nothing is lost, but a collection starts out empty after the upgrade until you migrate it once. | Package | v1 | v2 | | --- | --- | --- | | `@signaldb/localstorage` | key `signaldb-collection-` | key `-` (default `signaldb-`), plus one key per declared index | | `@signaldb/indexeddb` | `createIndexedDBAdapter('posts')` — one database per collection (`signaldb-posts`, store `items`) | `createIndexedDBAdapter({ databaseName, version, schema, onUpgrade? })` — one database for all collections, returns the `storage` function for a data adapter | | `@signaldb/fs` | `createFileSystemAdapter('posts.json')` — one JSON file per collection | `createFilesystemAdapter('./data/posts')` — a folder with one file per document under `items/` and one file per indexed value under `index/` | | `@signaldb/opfs` | `createOPFSAdapter('posts.json')` — one file per collection | `createOPFSAdapter('posts')` — a folder, laid out like `@signaldb/fs` | | `@signaldb/generic-fs` | one file per collection | a folder, laid out like `@signaldb/fs`; a custom `Driver` has to be rewritten against the new interface (path building, directory creation, recursive listing) | With `@signaldb/indexeddb`, the `schema` is the complete description of the database: a store that exists but is missing from `schema` is dropped on upgrade. List every collection you use — and, if you pass the same data adapter to the `SyncManager`, its stores as well. ### Migrating the data once Read the v1 data yourself, insert it into the v2 collection, then remove the old copy. For `@signaldb/localstorage`: ```ts await Posts.ready() const legacyKey = 'signaldb-collection-posts' const legacyData = localStorage.getItem(legacyKey) if (legacyData != null) { await Posts.insertMany(JSON.parse(legacyData)) localStorage.removeItem(legacyKey) } ``` If you configured a custom `serialize`/`deserialize` in v1, use your `deserialize` instead of `JSON.parse`. For `@signaldb/indexeddb`, the v1 data is in the database `signaldb-` (or `` if you set `prefix`), in the object store `items`: ```ts /** * Reads every item a v1 IndexedDB adapter stored for a collection. * @param name - The name the v1 adapter was created with. * @returns The stored items. */ function readLegacyItems(name: string) { return new Promise((resolve, reject) => { const request = indexedDB.open(`signaldb-${name}`) request.onerror = () => reject(request.error) request.onsuccess = () => { const database = request.result if (!database.objectStoreNames.contains('items')) { database.close() resolve([]) return } const getAll = database.transaction('items').objectStore('items').getAll() getAll.onerror = () => reject(getAll.error) getAll.onsuccess = () => { database.close() resolve(getAll.result) } } }) } await Posts.ready() const legacyItems = await readLegacyItems('posts') if (legacyItems.length > 0) await Posts.insertMany(legacyItems) indexedDB.deleteDatabase('signaldb-posts') ``` For `@signaldb/fs`, `@signaldb/opfs` and `@signaldb/generic-fs`, point the v2 adapter at a new folder, read the old JSON file once, `insertMany` its contents and delete the file afterwards. ## New DataAdapter Layer v2 introduces a `DataAdapter` abstraction to separate collection behavior from storage mechanics and to enable advanced scenarios. See the [Data Adapters](/data-adapters/) chapter for the full picture. * [`DefaultDataAdapter`](/reference/core/defaultdataadapter/): simple, standard choice that works with a `StorageAdapter`. * [`AsyncDataAdapter`](/reference/core/asyncdataadapter/): async-first flow with explicit storage setup. * [`WorkerDataAdapter` / `WorkerDataAdapterHost`](/reference/core/workerdataadapter/): run data operations in a Web Worker. * [`AutoFetchDataAdapter`](/reference/core/autofetchdataadapter/): replacement for `AutoFetchCollection` (if you previously relied on it). Standard setup with `DefaultDataAdapter` (recommended baseline): ```ts import { Collection, DefaultDataAdapter } from '@signaldb/core' const dataAdapter = new DefaultDataAdapter({ storage: (name) => myStorageFor(name), // returns a StorageAdapter for the given collection name }) const Posts = new Collection('posts', dataAdapter, { indices: ['id', 'authorId', 'createdAt'], }) ``` If you previously used `AutoFetchCollection`, migrate to `AutoFetchDataAdapter`. Keep the same `Collection` constructor pattern shown above but swap the adapter class. ## Collection Constructor Changes The `Collection` constructor now supports two forms: * `new Collection(options?)` (legacy-compatible). The deprecated `persistence` option still works and is wrapped by `DefaultDataAdapter`. * `new Collection(name, dataAdapter, options?)` (recommended): pass a collection name and a `DataAdapter` instance explicitly. Example migrating from v1: Before (v1): ```ts const Posts = new Collection({ name: 'posts', persistence: /* old adapter */ }) ``` After (v2): ```ts import { DefaultDataAdapter } from '@signaldb/core' const dataAdapter = new DefaultDataAdapter({ storage: (name) => myStorageFor(name), }) const Posts = new Collection('posts', dataAdapter, { indices: ['title'] }) ``` ## Removed Memory Adapter `createMemoryAdapter` and the `memory` option were removed. For tests or ephemeral storage, implement a trivial in-memory `StorageAdapter` with `createStorageAdapter` that keeps items in a local array or Map. ## Event Changes All persistence-level events on `Collection` were removed. They described one adapter loading and saving one collection as a whole, which is no longer how data moves. Replace them by what you used them for: | v1 event | v2 replacement | | --- | --- | | `persistence.init` | `await collection.ready()`, or the reactive `collection.isReady()` | | `persistence.pullStarted` / `persistence.pullCompleted` (initial load) | `collection.ready()` / `collection.isReady()` for the collection, [`cursor.isLoading()`](/reference/core/cursor/#⚡️-isloading-reactive) for a single query | | `persistence.pushStarted` / `persistence.pushCompleted` / `persistence.transmitted` | Await the write — with the `DefaultDataAdapter` it resolves once the storage adapter has written it. `collection.isPushing()` reflects running writes reactively. | | `persistence.error` | A failed write rejects its promise. A failure outside of a write — while setting up the storage adapter and loading its data, for instance — goes to the `onError` option of the data adapter ([`DefaultDataAdapter`](/reference/core/defaultdataadapter/), [`AsyncDataAdapter`](/reference/core/asyncdataadapter/), [`AutoFetchDataAdapter`](/reference/core/autofetchdataadapter/)); without it, it is only logged with `console.error`. A collection whose stored data could not be loaded also rejects `ready()`. | | `persistence.received` | No equivalent. A `StorageAdapter` is not notified of changes made outside the collection; changes from a server reach the collection through [`SyncManager`](/sync/) or the `AutoFetchDataAdapter`. | `collection.isPulling()` is not a replacement for the pull events: it is only `true` while a `find(…, { async: true })` query is running. Existing CRUD events remain: `added`, `changed`, `removed` and their corresponding action events (`insert`, `updateOne`, `updateMany`, `replaceOne`, `removeOne`, `removeMany`). A query that fails now announces itself through the new `query.error` event. This matters more than it looks: a cursor whose query failed keeps returning its neutral empty result, which is indistinguishable from a query that legitimately matched nothing. If your application needs to tell the two apart, listen here. ## Observer events Two changes to what `observeChanges` reports. Neither changes the data you end up with — both change how many events you are told about. **`movedBefore` reports the minimal set of moves.** In v1, every item whose neighbouring item had changed was reported as moved, so moving a single item could produce a `movedBefore` for several of them. Applying the reported moves still produces the same order. Consumers that count `movedBefore` calls, or that rely on being notified about items which did not themselves move, will now see fewer events. **`changed` is no longer emitted for a write that matched nothing.** It previously was, whenever the item had still existed at the moment it was read back. ## Custom storage adapters: index keys `StorageAdapter.readIndex` now declares `Map>` rather than `Map>`. The keys always had to be `serializeValue(value)` — that is what SignalDB looks an index up with — but the type did not say so, and an adapter keying its index by the raw field value answered nothing for every non-string field and everything for a `$ne` on one. If your adapter stores raw keys, wrap them: ```ts import { serializeValue } from '@signaldb/core' const key = serializeValue(item[field]) ``` Only string-valued fields were unaffected, which is why this can go unnoticed until someone indexes a number or a boolean. ## SyncManager The `persistenceAdapter` option was removed. Pass a `dataAdapter` instead — the same one your collections use: ```js const syncManager = new SyncManager({ dataAdapter, // … }) ``` `@signaldb/sync` v2 requires `@signaldb/core` 2.0.0 or later. If you create the `SyncManager` without an `id`, its own collections are now named `default-sync-manager-changes`, `default-sync-manager-snapshots` and `default-sync-manager-sync-operations` instead of `undefined-changes` and so on. Unpushed changes and snapshots stored under the old names are not read anymore. Pass `id: 'undefined'` to keep the old names, or — better — choose an `id` and migrate the data once. ## Migration Checklist * Update all write calls to `await` the new async methods and handle new return values. * Replace index providers with `indices: string[]`. * Rename persistence APIs to storage (`createStorageAdapter`, `StorageAdapter`), remove `combinePersistenceAdapters`. * Replace `AutoFetchCollection` with `AutoFetchDataAdapter`. * Switch `await collection.isReady()` to `await collection.ready()` and use reactive `collection.isReady()` where needed. * Check any code that used `collection.isLoading()` to wait for the initial load; use `ready()` / `isReady()` or `cursor.isLoading()` instead. * Replace persistence events as described in [Event Changes](#event-changes) — `ready()`, `cursor.isLoading()`, awaited writes and the data adapter's `onError` — and consider listening for `query.error`. * Migrate the data your v1 storage adapters wrote; v2 does not read it (see [Storage adapters: your existing data](#storage-adapters-your-existing-data)). * Remove `createMemoryAdapter` and the `memory` option; implement an in-memory `StorageAdapter` if necessary. * Remove calls to `resetData()`. * Replace the `SyncManager`'s `persistenceAdapter` option with `dataAdapter`. * In a custom `StorageAdapter`, key `readIndex` by `serializeValue(value)`. * Review anything counting `movedBefore` events or relying on `changed` for a write that matched nothing. If you run into something not covered here, see the changelog for `@signaldb/core` and the API reference, or open a discussion/issue. --- --- url: /changelog/core.md --- # Changelog for [`@signaldb/core`](https://www.npmjs.com/package/@signaldb/core) ## \[2.0.2] - 2026-11-10 ### Fixed * Matching a selector against many items is much faster. Before this fix, every item tested against a selector compiled the selector again, and compiling costs far more than testing an item. This applied to scans, to finding the queries a write affects, and to resolving a write locally. Now each selector is compiled once per scan. A `findOne` that has to scan 10,000 items in memory takes about 3 ms instead of 82 ms, and a scan of 1,000 items about 1 ms instead of 14 ms. * A write through `WorkerDataAdapter` whose selector names `id` together with another condition, such as `{ id, version: { $lt: 3 } }`, is now resolved from the items with that id instead of from every item an active query holds. A hundred such writes against a query holding 1,000 items take about 26 ms instead of 750 ms. Against 4,000 items they take 80 ms instead of 4.7 s. ## \[2.0.1] - 2026-11-10 ### Fixed * A write made to a persisted collection while `DefaultDataAdapter` loads it from storage is no longer lost. Before this fix, the load replaced memory with what `readAll` returned. An item inserted during the first load was missing from `find`/`findOne` until the next page reload, even though storage had it, and inserting the same id again succeeded. During a `fetchItemsFromStorage()` reload, an update was reverted and a removed item came back. Now the result of every write made during a load is applied on top of what storage returned. This holds whether or not storage already had the write, and works the same way for the legacy `persistence` option. * A query that was registered before the `DefaultDataAdapter` finished loading the persisted items now updates once they are loaded. Until now it kept the result it had before the load — usually empty — until a later write touched a matching item, and a `findOne` or `find(...).fetch()` with the same selector and options returned that stale result even after `ready()`. A reactive query run at startup, for instance in a component that renders before the storage answers, now sees the stored items without waiting for `ready()` first. ## \[2.0.0] - 2026-10-27 ### BREAKING CHANGES * `StorageAdapter.readIndex` now declares `Map>` instead of `Map>`. The keys always had to be `serializeValue(value)` — that is what SignalDB looks an index up with — but the type did not say so, and an adapter keying its index by the raw field value answered nothing for every non-string field and everything for a `$ne` on one. If your adapter stores raw keys, wrap them in `serializeValue` from `@signaldb/core`. * The `insert`, `insertMany`, `updateOne`, `updateMany`, `replaceOne`, `removeOne` and `removeMany` methods on the `Collection` are now asynchronous. They resolve to what they always returned: `insert` to the new item's id, `insertMany` to the new ids, `updateOne`, `replaceOne` and `removeOne` to `0` or `1`, and `updateMany` and `removeMany` to the number of items they touched. Await them — a rejected write that nobody awaits, a failed validation for instance, surfaces as an unhandled rejection instead of reaching your error handling. * The `createMemoryAdapter` method and `MemoryAdapter` type were removed. * The `memory` option for a `Collection` was removed. * The `AutoFetchCollection` was removed. Use the `AutoFetchDataAdapter` instead. * `Collection#resetData()` was removed without replacement. To reload a collection from storage, dispose it and create it again. * `isLoading()` on the `Collection` no longer describes the initial load. It is initially `false` and is `true` only while a `find(…, { async: true })` query (`isPulling()`) or a write (`isPushing()`) is running. Code that waited for `isLoading()` to turn `false` before showing data should use `ready()` / `isReady()` for the collection, or `Cursor#isLoading()` for a single query. * Indices on a `Collection` are now specified as an array of strings instead of using `IndexProvider` or `LowLevelIndexProvider` instances. * `PersistenceAdapter` was renamed to `StorageAdapter` and the signature was changed in a non backward compatible way. * The error messages that named the old concept were renamed with it: `No persistence adapter for collection ` is now `No storage adapter for collection `, and the `console.error` for a failed background write says `Error during storage operation in collection `. If you match on either string — in a test, a log filter, or an error reporter's grouping rule — update it. * The `createPersistenceAdapter` method was renamed to `createStorageAdapter`. * The `LoadResponse` type is no longer exported from `@signaldb/core`. It described the shape a `PersistenceAdapter` loaded, which the new `StorageAdapter` does not have. `@signaldb/sync` still uses a type of that name for what a `pull` resolves to, but does not export it either — if you were naming it explicitly, infer it from the `SyncManager` options instead. * The `combinePersistenceAdapters` method was removed. * All persistence events on the `Collection` were removed. * Exports for `createIndexProvider` and `createIndex` were removed. Specify indices as strings instead. * `.isReady()` method on `Collection` was renamed to `.ready()`. A new reactive `.isReady` method was added to check if the collection is ready in a reactive way. * Observing a query now reports the *minimal* set of `movedBefore` events for a reordering. In v1, every item whose neighbouring item had changed was reported as moved, so moving a single item could produce a `movedBefore` for several of them. Applying the reported moves still produces the same order, but consumers that count `movedBefore` calls, or that rely on being notified about items which did not themselves move, will now see fewer events. ### Added * Introduced support to use a `DataAdapter` with a `Collection` to handle data operations in a more structured way. * Added `DefaultDataAdapter` which provides a basic and backward compatible implementation of the `DataAdapter` interface. * Added `AsyncDataAdapter` which provides an asynchronous implementation of the `DataAdapter` interface. * Added `WorkerDataAdapter` and `WorkerDataAdapterHost` which provides a `DataAdapter` implementation that runs in a web worker. * Added `isBatchOperationInProgress` method to `Collection` to check if a batch operation is currently in progress. * Added the previous state (before the update) as an argument to `'changed'` event handlers on the `Collection` and to the `changed` callback of `observeChanges`. This provides additional information to handlers, enabling e.g. history functionality (thanks @robot-controller!) * The write methods of a `CollectionBackend` — `updateOne`, `updateMany` and `replaceOne` — may now resolve to `{ items, previousItems }` instead of a plain array, which is what lets the `'changed'` event report the previous state. Returning a plain array is still valid, so a custom adapter keeps working unchanged; the event then omits its third argument. All adapters shipped with SignalDB report the previous state, which grows a `WorkerDataAdapter` write response by the size of the items the write changed. * The callback passed to `onQueryStateChange` on a `CollectionBackend` may now receive a second argument describing how the query result changed. Existing callbacks are unaffected — the argument is only passed when the adapter can produce it, and adapters that cannot simply omit it. * `CollectionBackend`, `QueryOptions`, `StateChangeCallback`, `WriteResult`, `DetailedWriteResult` and `QueryDelta` are now exported, so a custom `DataAdapter` can name the types it has to implement. `WorkerDataAdapterEndpoint` and `WorkerDataAdapterHostEndpoint` describe what the two halves of the worker adapter need from a `Worker`, so anything with the same shape — a `MessagePort`, a test stub — can take its place. * Queries can be run asynchronously: `find(selector, { async: true })` returns a cursor whose `fetch()`, `count()`, `map()` and `forEach()` resolve to their result instead of returning it. The types follow the option, so a synchronous cursor is still synchronous. This is what makes the `AsyncDataAdapter`, the `WorkerDataAdapter` and the `AutoFetchDataAdapter` usable — they cannot answer a query on the spot. `AnyFindOptions`, `AsyncFindOptions` and `SyncFindOptions` are exported for naming the two forms. * A `StorageAdapter` may implement an optional `query` method that answers a whole query — selector, sort, window and projection — as far as its backend can, and reports what it applied; SignalDB applies the rest. It lets a backend that can read less than everything answer a bounded query without reading the whole collection first. It is consulted by the `AsyncDataAdapter`, the `AutoFetchDataAdapter` and the `WorkerDataAdapterHost`; adapters without it keep working unchanged. `StorageQuery` and `StorageQueryAnswer` are exported for implementing it. * Added `Cursor.isLoading()`, which reports whether the query behind a cursor has produced an outcome yet. A query that has not been answered publishes a *neutral* result — an empty array, a zero — and that is indistinguishable from a real one, because empty is a legitimate answer. This is the only way to tell the two apart, and it matters as soon as you use an adapter that does not answer on the spot. * Added `Cursor.applyDelta(delta)`, which brings a cursor up to date from a description of what changed rather than by re-running its query, falling back to `requery()` when the delta does not fit. For integrations that receive deltas from a data adapter themselves. * Added a new `query.error` event on the `Collection`. A query backing a live cursor that fails keeps serving its neutral empty result, which a consumer cannot distinguish from "no data" — this event is how you find out. * `serializeValue`, `get`, `reactiveOrAsync` and `unwrap` are now exported. `serializeValue` is the one a custom `StorageAdapter` needs: it produces the keys `readIndex` is looked up with. * `QueryStateAccessor` is exported, for supplying a `Cursor` with the query state it reports through `isLoading()`. * `Collection.batch` accepts the collections to batch: `Collection.batch([a, b], () => …)`. Without them it still batches every collection in the process, which defers every live query everywhere until the batch ends — fine for a few writes belonging to one event, and harmful around a loop whose length is data-dependent. * Added `Collection.reportLargeQueries(rows)`, which reports each live query holding more than `rows` rows once, together with the stack that registered it. `enableDebugMode()` switches it on at 500 rows. A reactive query registered from a long-lived place keeps its cost for the lifetime of the application, and there is otherwise nothing to see: the query works, and its price only shows up as an application that has grown slow. * A `transformAll` can now read related data the same way its query is read. An asynchronous read (`{ async: true }`) calls it with `{ async: true }` as a third argument and awaits a promise returned for it, so a `transformAll` built with `reactiveOrAsync` reads related collections reactively inside a reactive scope and with `{ async: true }` — not reactively, but waiting for the real data — everywhere else. A plain `transformAll` that returns the items keeps working unchanged; one that returns a promise for a synchronous read now throws instead of handing the promise to the cursor. ### Changed * A write is now propagated to live queries as a description of what changed, instead of by re-running each affected query and comparing its new result against the previous one. A write that touches one item costs the size of that change rather than the size of every result on screen. * `WorkerDataAdapterHost` sends the full result only the first time a query is answered; every update after that carries just the change. Editing one field of one row no longer serialises the entire result set across the worker boundary. * `WorkerDataAdapter` answers `isReady()` from the promise it already started when the collection registered, instead of asking the worker again every time. Readiness happens once and never goes back, but each question used to cost a round trip — and callers ask often: a helper awaiting `ready()` before touching each record turned a thousand-record sync into a thousand extra messages. * `DefaultDataAdapter`, `AsyncDataAdapter` and `WorkerDataAdapterHost` bring a query's result up to date from its previous result where they can, instead of reading the whole collection back from storage on every write. Queries using `limit` or `skip`, and projected queries that are also sorted, still re-execute, because their previous result cannot answer the change on its own. * `WorkerDataAdapter` routes every worker message through a single listener instead of adding one per query and per pending request. Previously each incoming message was offered to every listener in turn, and each of them re-serialised its own selector to decide the message was not for it. * A write that leaves a query's result unchanged no longer notifies that query's observers at all, and no longer produces a message across the worker boundary. * `WorkerDataAdapter` no longer shows a write before the worker confirms it when the item it modifies is known only through a projected query. Applying a modifier to a projected item produces something that is not the item, and a selector naming a projected-away field would no longer match it. The write itself is unaffected; it simply becomes visible when the worker answers rather than immediately. * `updateOne`, `updateMany` and `replaceOne` no longer read the items back from the data layer before writing them. The write's own answer says what changed, and an empty answer is what turns an upsert into an insert. The read still happens when something is listening for `validate`, so a validator can still inspect an item — and refuse the write — before it happens. * `changed` is no longer emitted for a write that matched nothing. It previously was, whenever the item had still existed at the moment it was read back. * A query with a `limit` is now brought up to date from its own window where the window allows it, instead of always being re-executed against the store. A window losing one of its items still needs the store, because what fills the gap is something the window has never held. * Reading a query that is already observed — `fetch()`, `count()`, `isLoading()` and the other reactive cursor methods inside a reactive scope — no longer re-runs the query and compares its whole result with the previous one. Every render of a component showing a live list paid that comparison, although the observer already holds the current result; a read now only hands over the result and registers its dependency. Measured on a live query holding 5000 items, a read on a collection with `transformAll` (which hands out fresh objects every time) drops from about 8 ms to about 3 ms; on a collection without one the comparison was already cheap and the read costs the same as before. * `mingo` is now required at `^7.2.4` instead of `^7.1.1`. An application that pins an older `mingo` 7 has to update it, or it ends up with a second copy in its bundle. ### Fixed * An observation without callbacks — `cursor.observeChanges({})`, used to keep a query live — now keeps it live until it is stopped. It did not count as observing, so the first reactive read of the same cursor that ended took the shared observer down with it and unregistered the query; a cursor waiting on `isLoading()` could then never settle. Calling the returned stop function twice is now harmless as well. * A synchronous read outside of a reactive scope on a collection with a reactivity adapter no longer registers a dependency. Nothing would ever have disposed it, so every such read left a live query behind for the rest of the session in addition to printing the `Cursor.depend()` warning. The read still warns; it now behaves as it did before the warning was introduced. * `Cursor#isLoading()` on a collection whose `transformAll` reads other collections stays `true` until the queries `transformAll` made have been answered too. With an asynchronous data adapter behind the related collection it used to report the list as loaded while the data it is enriched with was still missing — an author shown as absent rather than as loading. Like the query's own state it is latched: a later write that makes `transformAll` read something new does not send a loaded list back into loading. * A `transformAll` that reads another collection no longer leaves a dependency behind when its query is brought up to date after a write. That update runs outside of any reactive scope, so each read of the other collection used to register a live query there that was never released — one more for every write — and printed the `Cursor.depend()` warning. Reads made by a `transformAll` outside of a reactive scope now register nothing; inside one they stay reactive as before. * `insertMany` resolves to the ids in the order of the items passed to it. They were collected as the individual inserts completed, so with a storage adapter that answers out of order the ids did not line up with the items. * `removeOne` emits `removed` only when it removed an item. A `removeOne` that matched nothing emitted `removed` with `undefined`, which a listener reading the item's fields crashed on. * A listener registered with `once` can be removed with `off` before it fires. `once` registered a wrapper, so `off` with the original listener did nothing and the listener still ran. * `ready()` rejects, and `isReady()` stays `false`, when the `DefaultDataAdapter` cannot set up a collection's storage adapter or load its stored items. The error was only passed to `onError` (or logged), and `ready()` resolved as if the stored data had been loaded. If you await `ready()`, handle its rejection; the collection keeps working in memory. * Disposing one collection of a `WorkerDataAdapter` no longer ends the adapter for all of them. It terminated the worker and rejected every call of the other collections with `WorkerDataAdapter is disposed`; now only that collection is unregistered, and the worker is terminated once the last collection is disposed. * The `AutoFetchDataAdapter` answers a query on a newly observed selector only after the first fetch for it has settled. It answered from the local cache at once, so `isLoading()` turned `false` and an `{ async: true }` read resolved — usually to an empty list — before the remote items had arrived, and an application could not tell that list from a real answer. If the first fetch fails, the query now settles as failed instead of with the cached items. * The `AutoFetchDataAdapter` purges the items a selector fetched once its last observer is gone, also after `registerRemoteChange` fetched them again. Every refetch counted the items once more, while a purge released them once, so they were never removed. * The `AutoFetchDataAdapter` works without a `storage` option, caching the fetched items in memory. Every operation failed with `No storage adapter for collection ` instead, although the option is optional. A `fetchQueryItems` that does not resolve to an array is reported as `fetchQueryItems must resolve to an array of items`; the message used to ask for the `{ items }` object of an earlier version. * `observeChanges` passes the field, its old value and its new value to `changedField`, as `ObserveCallbacks` declares. It only passed the item and the field name — and ran the collection's `transform` on the field name, so with a `transform` the second argument was not even the field name. * A query combining an indexed field with an `$or` no longer returns documents that do not match it. The `$or` branches were unioned with the ids the rest of the selector had already narrowed down to, rather than intersected with them, and the optimized selector came back empty — so nothing filtered the surplus out again. `find({ status: 'open', $or: [{ tag: 'a' }, { tag: 'b' }] })` returned every indexed document instead of those satisfying both halves. Only queries whose fields are all indexed were affected, so indexing more made it more likely, not less. * No data adapter reads a whole collection out of storage any more to answer a query that selects several ids at once. `{ id: { $in: [...] } }` is now resolved through the storage adapter's `readIds`, like a single scalar `id` always was, so the query costs the ids it asks for instead of the size of the collection. **This applies to every `insert`**, which checks for existing ids exactly that way — inserting one item into a collection of 2,000 used to read all 2,000 back first. An application reported both: a ledger lookup and each of its writes taking seconds as its history grew. `DefaultDataAdapter`, `AsyncDataAdapter` and `AutoFetchDataAdapter` had the same restriction and were fixed with it. * Fixed a bug in `WorkerDataAdapter` where a query going back to the `'active'` state discarded the result it was holding, leaving readers of that query with nothing to show until the recomputation landed. * Fixed a bug in `WorkerDataAdapter` where a query using `fields` returned an empty result for as long as any write was in flight. Its stored items are projected, and they were being matched against the selector again — which no field the projection had dropped could satisfy. * Fixed `WorkerDataAdapter` letting a failed `registerCollection`, `registerQuery` or `unregisterQuery` escape as an uncaught promise rejection — which a disposed collection produced every time a cursor was cleaned up after it. A query the worker cannot register is now published as failed, so it reaches the collection's `query.error` event instead of waiting forever on an empty result. ## \[1.8.1] - 2026-03-17 ### Fixed * Filter out gone items when getting items from index. This fixes a bug where items that were removed from the collection but were still present in the index and lead to an exception when trying to get the item from the collection. ## \[1.8.0] - 2026-03-13 ### Added * Introduced the `transformAll` option when creating a `Collection`. This allows you to define a function that transform items after they are retrieved from persistence, enabling the integration of data from other collections or external sources (thanks @signalize!) * Added `Collection.resetData()` to clear in-memory state and reload data from the persistence adapter. ### Fixed * Fixed a race condition in SyncManager.dispose() that could cause unhandled "Collection is disposed" errors during organization/context switches while sync operations were still in flight (thanks @shajan-journal!) ## \[1.7.2] - 2026-01-07 ### Changed * Upgraded mingo dependency to v7 ## \[1.7.1] - 2025-08-25 ### Fixed * Fixed index info for `$or` queries with mixed indexed and non-indexed fields ## \[1.7.0] - 2025-07-08 ### Added * Type safety for modifiers in `updateOne`, `updateMany`, and `replaceOne` methods ### Fixed * Fixed a bug where nested array parts where not resolved correctly * Removed non-working `$text` operator from query selector type * Fixed function signature for `$where` operator ## \[1.6.0] - 2025-05-12 ### Added * Introduced `primaryKeyGenerator`. A function that generates a unique ID for the item. If not provided, a default generator will be used (thanks @signalize!) ### Fixed * Improve performance of checking id index * Export `Cursor` type ### Changed * Leverage null and undefined values for indexing ## \[1.5.4] - 2025-05-02 ### Fixed * Fixed a bug where the index wasn't filtered correctly when it was outdated ## \[1.5.3] - 2025-05-02 ### Changed * deep clone items before modifying them ## \[1.5.2] - 2025-04-04 ### Changed * Export `DotNotation` and `GetType` types (thanks @maxfriedmann!) ## \[1.5.1] - 2025-04-01 ### Fixed * Add missing scope check for internal signals ## \[1.5.0] - 2025-03-26 ### Added * Introduce `validation` event to allow schema validation of items in collections. ## \[1.4.0] - 2025-03-19 ### Added * Implemented `{ upsert: true }` option for `updateOne` and `updateMany` methods. * Implemented `replaceOne` method. ### Changed * Check for already existing ids in `updateMany` ### Fixed * Fixed checking for existing ids in `updateOne` and `updateMany`. There was a bug that made it impossible to update the id of an item. ## \[1.3.1] - 2025-02-19 ### Changed * Improved index query performance ## \[1.3.0] - 2025-02-18 ### Added * Implement exclusion of specific items when querying indices (when a selector contains `$nin` or `$ne`) ### Fixed * Emit `getItems` event on collections regardless of an index hit ### Removed * Removed auto-loading of developer tools and moved the loading to the `@signaldb/devtools` package. To load the developer tools, you now need to import `@signaldb/devtools` somewhere in your frontend code. Make sure that it doesn't get imported when running your code in production mode. ## \[1.2.4] - 2025-02-17 ### Changed * Improved type checking of selectors ## \[1.2.3] - 2025-02-11 ### Changed * Replace EventTarget-based emitter with a native implementation (thanks @Jordan-Mysten) ## \[1.2.2] - 2025-02-03 ### Fixed * Fixed check if `@signaldb/devtools` package is available for some environments (addition to [#1359](https://github.com/maxnowack/signaldb/issues/1359)) ## \[1.2.1] - 2025-02-01 ### Fixed * Fixed a bug where the build environment was complaining about missing `@signaldb/devtools` package ([#1359](https://github.com/maxnowack/signaldb/issues/1359)) ### Added * Enabled type checking in query selectors ## \[1.2.0] - 2025-01-13 ### Added * `isReady` method on `Collection` to wait for the collection to be ready ### Changed * Don't load developer tools automatically in production (thanks @lorof) ## \[1.1.0] - 2025-01-10 ### Added * Support for @signaldb/devtools * Allow specifying a name for a collection * Added `Collections.onCreation` method to listen for collection creation * Added `Collections.onDispose` method to listen for collection disposal * Added `Collections.getCollections` method to get all collections ### Changed * Switched from native EventEmitter to custom class that is based on EventTarget * Remove all listeners when disposing a collection ## \[1.0.0] - 2024-12-16 ### Added * Added JSDoc comments to all public APIs * Added method to globally configure field tracking * Added method for configuring field tracking on a collection * Allow configuring field tracking in collection options ### Removed * BREAKING: `createLocalStorageAdapter` was moved to `@signaldb/localstorage` * BREAKING: `createOPFSAdapter` was moved to `@signaldb/opfs` * BREAKING: `createFilesystemAdapter` was moved to `@signaldb/fs` * BREAKING: `PersistentCollection` was removed entirely * BREAKING: `SyncManager` was moved to `@signaldb/sync` * BREAKING: `ReplicatedCollection` was removed entirely * BREAKING: `options` parameter was removed from `combinePersistenceAdapters` * BREAKING: support for old `IndexProviders` was removed --- --- url: /changelog/sync.md --- # Changelog for [`@signaldb/sync`](https://www.npmjs.com/package/@signaldb/sync) ## \[2.0.0] - 2026-10-27 ### BREAKING CHANGES * Removed compatibility with `@signaldb/core` versions below `2.0.0` * Removed `persistenceAdapter` option from `SyncManager` constructor options. Use `dataAdapter` option instead. * Without an `id`, the sync manager's own collections are now named `default-sync-manager-changes`, `default-sync-manager-snapshots` and `default-sync-manager-sync-operations`. They used to be named `undefined-changes` and so on, because the names were built from the `id` option rather than from its default. If you persisted the sync manager's data without setting `id`, the changes not yet pushed and the snapshots under the old names are no longer read: either set `id: 'undefined'` to keep the old names, or let the next sync rebuild the snapshots. With `@signaldb/indexeddb`, rename the stores in your `schema` accordingly. ### Added * `isSyncing(name, true)` returns a `Promise` and reads the active sync operations through an `{ async: true }` query. Use it when the sync manager's `dataAdapter` cannot answer a query on the spot, such as an `AsyncDataAdapter` or a `WorkerDataAdapter`. `isSyncing(name)` stays synchronous and reactive. ### Changed * `addCollection` is generic over the item type of the collection passed to it, so a collection whose item type extends the sync manager's item type can be added without a cast. ### Fixed * `sync()` rejects for a collection whose stored data could not be loaded, and `isReady()` rejects when the sync manager's own collections could not be loaded. Both used to proceed as if the data had been loaded, so a sync could compute its changes against an empty collection. * `isReady()` resolves only once the sync manager's own collections are ready. It resolved immediately, so a sync could start before the stored changes and snapshots had been loaded. * Remote changes delivered with data through `registerRemoteChange` are applied in the collection's sync queue. They could previously run at the same time as a sync of the same collection and interleave with it. ## \[1.3.1] - 2025-04-29 ### Fixed * Fix `computeChanges` method to work with items that have null values ## \[1.3.0] - 2025-04-24 ### Added * Added `rawChanges` array to `push` function parameters to make all changes available during push. * Added `modifiedFields` to `changes` object on `push` to allow patch updates ## \[1.2.2] - 2025-03-20 ### Fixed * Fix version for `@signaldb/core` dependency ## \[1.2.1] - 2025-03-19 ### Changed * Use upserts in `updateOne` internally instead of searching for the document first ### Fixed * Use `replaceOne` internally to replace documents in collections instead of just updating them with `updateOne` ## \[1.2.0] - 2025-03-10 ### Added * Allow configuration of debounce time for pushing changes (thanks @augustpemberton!) ### Fixed * Don't skip debounces when pushing multiple collections (#1470, thanks @augustpemberton!) ## \[1.1.3] - 2025-02-19 ### Changed * Improved sync performance by reducing overhead in internal `applyChanges` method * Improved sync performance by updating only changed documents when applying snapshots ## \[1.1.2] - 2025-02-18 ### Changed * Add indices to internal collections to improve performance ## \[1.1.1] - 2025-01-21 ### Fixed * Explicitly turn of reactivity for internal queries ## \[1.1.0] - 2025-01-13 ### Fixed * Wait until collections persistence was initialized before starting sync ### Added * Allow sync to be paused and resumed with `syncManager.startSync(name)` and `syncManager.pauseSync(name)` (thanks @obedm503) * Added `syncManager.startAll()` and `syncManasger.pauseAll()` to start and pause all collections ## \[1.0.1] - 2025-01-10 ### Changed * Define names for internal collections * Dispose temporary collections in applyChanges function ## \[1.0.0] - 2024-12-16 ### Changed * BREAKING: `SyncManager` does now default to **no persistence** instead of `localStorage` --- --- url: /changelog/devtools.md --- # Changelog for [`@signaldb/devtools`](https://www.npmjs.com/package/@signaldb/devtools) ## \[2.0.0] - 2026-10-27 ### Changed * Importing this package calls `Collection.enableDebugMode()`, which in `@signaldb/core` v2 also switches on `Collection.reportLargeQueries()` at 500 rows. You will therefore see console output naming each live query that holds more than 500 rows, together with the stack that registered it. That report is the point — such a query keeps its cost for the lifetime of the application and is otherwise invisible — but it is new output where there was none. Call `Collection.reportLargeQueries(null)` after the import to switch it off, or a different number to pick your own threshold. * `react` and `react-dom` are now required at `^19.3.0` instead of `^19.2.3`, and `styled-components` at `^6.5.3` instead of `^6.2.0`. An application that pins older versions has to update them, or it ends up with a second copy of each in its bundle. ### Fixed * `import '@signaldb/devtools'` is no longer removed by bundlers. The package declared `"sideEffects": false`, although importing it is the only way to use it, so a bundler that honours the flag — esbuild, Rollup, webpack in production mode — dropped the import and the devtools never loaded. * The Mutations tab now lists `replaceOne` calls, with the replacement document in the Modifier column. They were not recorded at all before. * The Data tab works with `@signaldb/core` v2 again. It read the items from the collection's `memory` option, which v2 removed, and crashed the devtools as soon as a collection was selected. It now shows the collection through a live query, so it works with every data adapter — including the `AsyncDataAdapter` and the `WorkerDataAdapter` — and a write only costs the devtools the size of the change. While the tab shows a collection of more than 500 items, that query is itself reported by `Collection.reportLargeQueries()`. * A test suite that loads the devtools under a DOM environment such as Vitest's `happy-dom` no longer fails at random with `TypeError: Failed to execute 'dispatchEvent' on 'EventTarget': parameter 1 is not of type 'Event'` while every test passes. The devtools delivered each change notification on a 10 ms timer, so a collection created, written or disposed at the end of a test file was announced after the test environment had been torn down. Notifications are now delivered as soon as the code that caused them has finished, so none is left pending when a test ends — and the devtools panel no longer lags 10 ms behind. ## \[1.0.0-beta.4] - 2025-02-18 ### Added * Added logic to load developer tools to this package. To load the developer tools, you now need to import `@signaldb/devtools` somewhere in your frontend code. Make sure that it doesn't get imported when running your code in production mode. ## \[1.0.0-beta.3] - 2025-01-23 ### Changed * Deactivate tracking queries, mutation and performance by default ## \[1.0.0-beta.2] - 2025-01-13 ### Fixed * Fixed version range for `@signaldb/core` peer dependency ## \[1.0.0-beta.1] - 2025-01-10 ### Changed * Improved tables in the UI ## \[1.0.0-beta.0] - 2025-01-10 --- --- url: /changelog/react.md --- # Changelog for [`@signaldb/react`](https://www.npmjs.com/package/@signaldb/react) ## \[2.0.0] - 2026-10-27 ### Added * Accepts `@signaldb/core` v2 as a peer dependency, in addition to 1.x. ## \[1.0.1] - 2025-03-06 ### Fixed * Check for initial render to be completed before forcing a re-render. This fixes warnings in the console about setting state on a not-yet-mounted component. ## \[1.0.0] - 2024-12-16 ### Added * Added JSDoc comments to public API --- --- url: /changelog/fs.md --- # Changelog for [`@signaldb/fs`](https://www.npmjs.com/package/@signaldb/fs) ## \[2.0.0] - 2026-10-27 ### BREAKING CHANGES * Switched to new `StorageAdapter` API. * **The adapter is given a folder, not a file, and the on-disk layout changed with it.** `createFileSystemAdapter('data.json')` used to write one JSON file holding the whole collection; it now takes a directory and writes one file per document under `items/` — sharded over two levels by the document's id — and one file per indexed value under `index/`. A write therefore costs one file rather than a rewrite of the entire collection. Data written by v1 is not read by v2: point the adapter at a fresh directory and import your old JSON file into the collection once, or keep the old file and write a one-off migration that inserts its contents. * Removed compatibility with `@signaldb/core` versions below `2.0.0` ### Fixed * `@signaldb/generic-fs` is no longer bundled into this package. It was already declared as a dependency, so consumers installed it *and* received a second copy compiled into `dist` — about 7 kB of duplicated code in the shipped bundle, and two separate module instances at runtime. The built package is now roughly a third of its previous size. * Custom deserialize function now works correctly when file is empty (thanks to @krolebord!) ## \[1.0.1] - 2025-04-24 ### Fixed * Avoid duplicate ids and unnecessary errors ## \[1.0.0] - 2024-12-16 ### Added * Added JSDoc comments to public API --- --- url: /changelog/generic-fs.md --- # Changelog for [`@signaldb/generic-fs`](https://www.npmjs.com/package/@signaldb/generic-fs) ## \[2.0.0] - 2026-10-27 ### BREAKING CHANGES * Switched to new `StorageAdapter` API. * **A collection is a folder now, not a file.** The driver is given a directory and writes one file per document under `items/` and one file per indexed value under `index/`, so a write costs one file rather than a rewrite of the whole collection. A driver written against the previous single-file interface has to be rewritten against `Driver`, which now describes path building, directory creation and recursive listing alongside reading and writing. * Removed compatibility with `@signaldb/core` versions below `2.0.0` ### Fixed * Custom deserialize function now works correctly when file is empty (thanks to @krolebord!) ## \[1.0.1] - 2025-04-24 ### Fixed * Avoid duplicate ids and unnecessary errors ## \[1.0.0] - 2024-12-16 ### Added * Added JSDoc comments to public API --- --- url: /changelog/indexeddb.md --- # Changelog for [`@signaldb/indexeddb`](https://www.npmjs.com/package/@signaldb/indexeddb) ## \[2.0.0] - 2026-10-27 ### BREAKING CHANGES * Switched to new `StorageAdapter` API. * **One database now holds every collection, and the adapter is configured accordingly.** `createIndexedDBAdapter('posts')` used to open a database of its own per collection (`signaldb-posts`, single store `items`). It now takes a description of one database — `databaseName`, `version` and a `schema` mapping each store name to the fields to index — and returns the `storage` function a data adapter asks for a collection's store. Stores present in the database but absent from `schema` are dropped on upgrade, so the schema is the complete description of what the database holds. The old per-collection databases are untouched and unread: open them yourself once and insert their contents if you need to keep the data. * Removed compatibility with `@signaldb/core` versions below `2.0.0`. ### Added * A query with an equality on the primary key or on an indexed field reads only the matching key range instead of the whole object store, when the collection uses the `AsyncDataAdapter`, the `AutoFetchDataAdapter` or the `WorkerDataAdapter`. Results are unchanged; the remaining selector, sort and window are still applied by SignalDB. ### Fixed * `onUpgrade` receives the version the database is upgraded *from* as `oldVersion`. It received the new version twice, so a migration that branches on `oldVersion` never saw where it was coming from. * Queries on an indexed field that is not a string now return the right documents. The index was keyed by IndexedDB's own keys — the raw values — while SignalDB looks an index up by `serializeValue(value)`, so `{ rank: 3 }` matched nothing and `{ rank: { $ne: 3 } }` matched everything. Only string-valued fields were unaffected, which is why the existing tests did not catch it. ## \[1.1.0] - 2025-05-08 ### Fixed ### Added * Added support for custom database prefix option (thanks to @pierissimo!) ## \[1.0.0] - 2025-01-06 * Initial release --- --- url: /changelog/localstorage.md --- # Changelog for [`@signaldb/localstorage`](https://www.npmjs.com/package/@signaldb/localstorage) ## \[2.0.0] - 2026-10-27 ### BREAKING CHANGES * Switched to new `StorageAdapter` API. * **The localStorage keys changed.** A collection used to live under `signaldb-collection-`; it now lives under `-`, defaulting to `signaldb-`, with one further key per declared index. Data written by v1 is still in localStorage but is not read by v2 — read the old key yourself once and insert its contents into the collection, then remove it. * Removed compatibility with `@signaldb/core` versions below `2.0.0` ### Fixed * Custom deserialize function now works correctly when localStorage is empty (thanks to @krolebord!) ## \[1.0.1] - 2025-04-24 ### Fixed * Avoid duplicate ids and unnecessary errors ## \[1.0.0] - 2024-12-16 ### Added * Added JSDoc comments to public API --- --- url: /changelog/opfs.md --- # Changelog for [`@signaldb/opfs`](https://www.npmjs.com/package/@signaldb/opfs) ## \[2.0.0] - 2026-10-27 ### BREAKING CHANGES * Switched to new `StorageAdapter` API. * **The adapter is given a folder, not a file, and the layout in OPFS changed with it.** `createOPFSAdapter('myCollection.json')` used to write one file holding the whole collection; it now takes a directory and writes one file per document under `items/` and one file per indexed value under `index/`. A write therefore costs one file rather than a rewrite of the entire collection. Data written by v1 is not read by v2 — read the old file once through the File System API and insert its contents into the collection if you need to keep it. * Removed compatibility with `@signaldb/core` versions below `2.0.0` ### Fixed * Custom deserialize function now works correctly when file is empty (thanks to @krolebord!) ## \[1.0.1] - 2025-04-24 ### Fixed * Avoid duplicate ids and unnecessary errors ## \[1.0.0] - 2024-12-16 ### Added * Added JSDoc comments to public API --- --- url: /changelog/angular.md --- # Changelog for [`@signaldb/angular`](https://www.npmjs.com/package/@signaldb/angular) ## \[2.0.0] - 2026-10-27 ### Added * Accepts `@signaldb/core` v2 as a peer dependency, in addition to 1.x. ## \[1.0.6] - 2026-04-10 ### Added * Added support for Angular 21. ## \[1.0.5] - 2025-07-17 ### Added * Added support for Angular 20. ## \[1.0.4] - 2024-12-16 --- --- url: /changelog/maverickjs.md --- # Changelog for [`@signaldb/maverickjs`](https://www.npmjs.com/package/@signaldb/maverickjs) ## \[2.0.0] - 2026-10-27 ### Added * Accepts `@signaldb/core` v2 as a peer dependency, in addition to 1.x. ## \[1.0.0] - 2024-12-16 --- --- url: /changelog/meteor.md --- # Changelog for [`@signaldb/meteor`](https://www.npmjs.com/package/@signaldb/meteor) ## \[2.0.0] - 2026-10-27 ### Added * Accepts `@signaldb/core` v2 as a peer dependency, in addition to 1.x. ## \[1.0.0] - 2024-12-16 ### Added * Added JSDoc comments to public API --- --- url: /changelog/mobx.md --- # Changelog for [`@signaldb/mobx`](https://www.npmjs.com/package/@signaldb/mobx) ## \[2.0.0] - 2026-10-27 ### Added * Accepts `@signaldb/core` v2 as a peer dependency, in addition to 1.x. ## \[1.0.0] - 2024-12-16 --- --- url: /changelog/oby.md --- # Changelog for [`@signaldb/oby`](https://www.npmjs.com/package/@signaldb/oby) ## \[2.0.0] - 2026-10-27 ### Added * Accepts `@signaldb/core` v2 as a peer dependency, in addition to 1.x. ## \[1.0.1] - 2026-04-10 ### Fixed * Fixed error during installation (Thanks @robot-controller!) ## \[1.0.0] - 2024-12-16 --- --- url: /changelog/preact.md --- # Changelog for [`@signaldb/preact`](https://www.npmjs.com/package/@signaldb/preact) ## \[2.0.0] - 2026-10-27 ### BREAKING CHANGES * Requires `@signaldb/core` v2 — the peer dependency is now `^2.0.0-0` and no longer accepts 1.x. Upgrade `@signaldb/core` together with this package. ## \[1.0.0] - 2024-12-16 --- --- url: /changelog/reactively.md --- # Changelog for [`@signaldb/reactively`](https://www.npmjs.com/package/@signaldb/reactively) ## \[2.0.0] - 2026-10-27 ### BREAKING CHANGES * Requires `@signaldb/core` v2 — the peer dependency is now `^2.0.0-0` and no longer accepts 1.x. Upgrade `@signaldb/core` together with this package. ## \[1.0.0] - 2024-12-16 --- --- url: /changelog/sinuous.md --- # Changelog for [`@signaldb/sinuous`](https://www.npmjs.com/package/@signaldb/sinuous) ## \[2.0.0] - 2026-10-27 ### Added * Accepts `@signaldb/core` v2 as a peer dependency, in addition to 1.x. ## \[1.0.0] - 2024-12-16 --- --- url: /changelog/sjs.md --- # Changelog for [`@signaldb/sjs`](https://www.npmjs.com/package/@signaldb/sjs) ## \[2.0.0] - 2026-10-27 ### Added * Accepts `@signaldb/core` v2 as a peer dependency, in addition to 1.x. ## \[1.0.0] - 2024-12-16 --- --- url: /changelog/solid.md --- # Changelog for [`@signaldb/solid`](https://www.npmjs.com/package/@signaldb/solid) ## \[2.0.0] - 2026-10-27 ### Added * Accepts `@signaldb/core` v2 as a peer dependency, in addition to 1.x. ## \[1.0.0] - 2024-12-16 --- --- url: /changelog/svelte.md --- # Changelog for [`@signaldb/svelte`](https://www.npmjs.com/package/@signaldb/svelte) ## \[2.0.0] - 2026-10-27 ### Added * Accepts `@signaldb/core` v2 as a peer dependency, in addition to 1.x. ### Fixed * The package built a copy of all of `@signaldb/core` into its own `dist`, and in doing so moved its entry points: `dist/index.svelte.js` and `dist/index.svelte.d.ts` — the files `package.json` points at — were no longer produced, so importing the package resolved to nothing. This one builds with `tsc` rather than vite and therefore has no `rollupOptions.external`; the repository's TypeScript path mapping pointed `@signaldb/core` at its *sources*, which pulled them into the compilation. The mapping is now cleared for this package, so core resolves to its published types like it does for any consumer. The output is back to two files and ~8 kB instead of 98 files and ~370 kB. ### Changed * Refactored `create` to use a class-based object, and updated `onDispose` to support zero or multiple callbacks. ## \[1.1.1] - 2025-04-04 ### Fixed * Guard `stop` call to prevent `TypeError`s in combination with persistence adapters ## \[1.1.0] - 2025-04-04 ### Changed * Add `onDispose` method to adapter and remove the need for manual cleanup (thanks @signalize!) ## \[1.0.0] - 2025-03-27 ### Added * Initial release of `@signaldb/svelte`. Thanks [@ykrods](https://github.com/ykrods) for the contribution! --- --- url: /changelog/usignal.md --- # Changelog for [`@signaldb/usignal`](https://www.npmjs.com/package/@signaldb/usignal) ## \[2.0.0] - 2026-10-27 ### Added * Accepts `@signaldb/core` v2 as a peer dependency, in addition to 1.x. ## \[1.0.0] - 2024-12-16 --- --- url: /changelog/vue.md --- # Changelog for [`@signaldb/vue`](https://www.npmjs.com/package/@signaldb/vue) ## \[2.0.0] - 2026-10-27 ### Added * Accepts `@signaldb/core` v2 as a peer dependency, in addition to 1.x. ### Changed * Removed `onScopeDispose` and `onDispose` from the reactivity adapter as it was not working as expected ## \[1.0.0] - 2024-12-16 --- --- url: /guides/angular.md --- # Use SignalDB in Angular This guide will show you how to incorporate SignalDB into your Angular app, including setting up collections and using SignalDB’s reactive features within Angular components. ## Requirements Before we begin, ensure you have a basic understanding of Angular and an existing Angular project ready. If not, refer to the [Angular Tutorial](https://angular.dev/tutorials/first-app). It’s also helpful to be familiar with signal-based reactivity. You can learn more about this in the [Core Concepts](/core-concepts/#signals-and-reactivity) section and explore [Angular Signals](https://angular.dev/guide/signals) to see how reactivity is handled in the framework. ## Installing SignalDB To begin, install SignalDB by running this command in your terminal: ```bash npm install @signaldb/core ``` Next, install the Angular-specific reactivity adapter for SignalDB: ```bash npm install @signaldb/angular ``` ## Setting Up SignalDB With SignalDB installed, you’ll now set up a collection and configure the reactivity adapter for Angular: ```js import { Collection, DefaultDataAdapter } from '@signaldb/core'; import angularReactivityAdapter from '@signaldb/angular'; const Posts = new Collection<{ id: string, title: string, author: string }>('posts', new DefaultDataAdapter(), { reactivity: angularReactivityAdapter, }); ``` In this example, we define a `Posts` collection and use the Angular reactivity adapter to enable seamless updates in your Angular components. ## Building an Angular Component Let’s now create an Angular component that uses SignalDB to display and manage a list of posts: ```typescript import { Component, effect } from '@angular/core'; import { RouterOutlet } from '@angular/router'; import { Collection, DefaultDataAdapter } from '@signaldb/core'; import angularReactivityAdapter from '@signaldb/angular'; const Posts = new Collection<{ id: string, title: string, author: string }>('posts', new DefaultDataAdapter(), { reactivity: angularReactivityAdapter, }); @Component({ selector: 'app-root', standalone: true, imports: [RouterOutlet], template: `
  • @for (item of items; track item.title) {
  • {{item.title}} ({{item.author}})
  • }
`, }) export class AppComponent { items: {id: string, title: string, author: string}[] = []; async insertPost() { await Posts.insert({ title: 'Post 1', author: 'Author 1' }); } constructor() { effect((onCleanup) => { const cursor = Posts.find(); this.items = cursor.fetch(); onCleanup(() => { cursor.cleanup(); }); }); } } ``` ### Key Concepts: 1. **Collection Setup**: We create a `Posts` collection with `@signaldb/angular` to enable reactivity. 2. **Component Overview**: The `AppComponent` uses Angular’s `effect()` to automatically update the `items` array whenever the `Posts` collection changes. 3. **Rendering in Template**: The template renders a list of posts using an `@for` loop, and the `insertPost()` method adds a new post when the "Add Post" button is clicked. 4. **Effect Hook**: The `effect()` function handles reactivity, ensuring the component stays in sync with changes in the `Posts` collection. The cleanup function removes the cursor when the component is destroyed. ## Wrapping Up You have now successfully integrated SignalDB into an Angular app and created a reactive component to display and manage posts. With this setup, you can leverage SignalDB’s reactive capabilities to handle data updates and synchronization in your Angular application. ## Next Steps Now that you’ve learned how to use SignalDB in Angular, you maybe want to explore the possibilities how you can synchronize the data with your backend. Take a look at the [Synchronization Overview](/sync/) to get started --- --- url: /guides/react.md --- # Use SignalDB with React In this guide, you will learn how to use SignalDB together with React. We will cover the basic setup and how to use SignalDB in your React project. ## Prerequisites Let's assume you already have basic knowledge of React and already have a React project set up. If you don't, you can follow the [official React documentation](https://react.dev/learn/start-a-new-react-project) to get started. Also a basic understanding of signal-based reactivity is helpful. If you are not familiar with it, you can read about it on the [Core Concepts](/core-concepts/#signals-and-reactivity) page to get an overview. ## Installation First of all, you need to install SignalDB. You can do this by running the following command in your terminal: ```bash npm install @signaldb/core ``` We also need to install a signals library that provides the reactivity for SignalDB. We going to use [Maverick Signals](https://github.com/maverick-js/signals). The following command installs Maverick Signals and the corresponding reactivity adapter for SignalDB: ```bash npm install @maverick-js/signals npm install @signaldb/maverickjs ``` Additionally we need to install the `@signaldb/react` package that provides the React bindings for SignalDB: ```bash npm install @signaldb/react ``` **You can also install all packages at once by running the following command:** ```bash npm install @signaldb/core @maverick-js/signals @signaldb/maverickjs @signaldb/react ``` ## Basic Setup To use SignalDB in your React project, you need to set up your collections and the reactivity adapter. Do this in a file that you can import in your components. ```js // Posts.js import { Collection, DefaultDataAdapter } from '@signaldb/core' import maverickReactivityAdapter from '@signaldb/maverickjs' const Posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: maverickReactivityAdapter, }) export default Posts ``` In another file, you have to setup a react hook that provides the reactivity to your components. We have a helper function for that in the `@signaldb/react` package, so that it is just a one liner for you: ```js // useReactivity.js import { createUseReactivityHook } from '@signaldb/react' import { effect } from '@maverick-js/signals' const useReactivity = createUseReactivityHook(effect) export default useReactivity ``` The `useReactivity` function is a react hook that you can use in your components to make them reactive. It receives a function as the first argument that runs your reactive context. The function reruns whenever the data used inside changes. The return value of the function is the data that you want to use in your component. The `useReactivity` function also takes a dependency list as an optional second argument, similar to the [dependency list of the `useEffect` hook](https://react.dev/reference/react/useEffect#specifying-reactive-dependencies). ## Using SignalDB in your Components Now you can use SignalDB in your components. Here is an example of a simple component that displays a list of posts: ```jsx import React from 'react' import useReactivity from './useReactivity' import Posts from './Posts' const PostList = () => { const posts = useReactivity(() => Posts.find({}).fetch()) return (
    {posts.map(post => (
  • {post.title}
  • ))}
) } ``` In this example, we use the `useReactivity` hook to make the component reactive. The `useReactivity` hook runs the function that fetches the posts from the collection whenever the data changes. The `fetch` method returns an array of all documents in the collection. ## Conclusion That's it! You have successfully set up SignalDB in your React project and created a reactive component that displays a list of posts. You can now use SignalDB in your React project to manage your data and make your components reactive. ## Next Steps Now that you’ve learned how to use SignalDB in React, you maybe want to explore the possibilities how you can synchronize the data with your backend. Take a look at the [Synchronization Overview](/sync/) to get started --- --- url: /guides/solid-js.md --- # Integrating SignalDB with Solid.js This guide walks you through how to set up and use SignalDB within your Solid project. We’ll cover the initial setup steps and demonstrate how to incorporate SignalDB into your Solid components. ## Requirements Before proceeding, make sure you’re familiar with the basics of Solid and have a Solid project ready. If you're new to Solid, check out the [SolidStart Getting Started](https://docs.solidjs.com/solid-start/getting-started) guide. An understanding of signal-based reactivity will also be useful. If you're not familiar with this concept, refer to the [Core Concepts](/core-concepts/#signals-and-reactivity) section or the [Solid Documentation](https://docs.solidjs.com/concepts/signals) for an introduction. ## Installation Begin by installing SignalDB. Run the following command in your terminal: ```bash npm install @signaldb/core ``` Next, install the Solid reactivity adapter to integrate Solid signals with SignalDB: ```bash npm install @signaldb/solid ``` ## Setting Up To integrate SignalDB into your Solid project, define your collections and configure the reactivity adapter. You can create this setup in a file for later use in your components. ```js // Posts.js import { Collection, DefaultDataAdapter } from '@signaldb/core' import solidReactivityAdapter from '@signaldb/solid' const Posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: solidReactivityAdapter, }) export default Posts ``` ## Using SignalDB in Components With the basic setup in place, you can now use SignalDB in your Solid components. Below is an example component that displays a list of posts: ```jsx import { For } from "solid-js"; import Posts from './Posts' const PostList = () => (
  • {post => (
  • {post.title} ({post.author})
  • )}
) ``` In this example, the `.find()` and `.fetch()` methods are used to retrieve data. The component automatically re-renders whenever the `Posts` collection is updated. Click the "Add" button to test the reactivity. ## Final Thoughts You’ve now set up SignalDB in your Solid project and created a reactive component to display posts. With this, you can manage your data effectively and build reactive components in your Solid apps. ## Next Steps Now that you’ve learned how to use SignalDB in Solid, you maybe want to explore the possibilities how you can synchronize the data with your backend. Take a look at the [Synchronization Overview](/sync/) to get started --- --- url: /guides/svelte.md --- # Using SignalDB with Svelte 5 This guide explains how to integrate SignalDB into a Svelte 5 project. You’ll learn how to set up SignalDB collections and use Svelte's runes to manage and display data. ## Prerequisites Before you start, make sure you’re familiar with Svelte basics and have a Svelte 5 project ready to go. If you’re new to Svelte 5, you can take a look at the [Svelte 5 Documentation](https://svelte-5-preview.vercel.app/docs/introduction) to get started. A basic understanding of signal-based reactivity will also be helpful. You can read more about it on the [Core Concepts](/core-concepts/#signals-and-reactivity) page and the [Svelte runes blog post](https://svelte.dev/blog/runes) to understand how reactivity works. ## Installation First, you need to install SignalDB in your project. Open your terminal and run: ```bash npm install @signaldb/core ``` Next, install the [Svelte-specific reactivity adapter for SignalDB](/reference/svelte/): ```bash npm install @signaldb/svelte ``` ## Setting Up SignalDB Once you’ve installed SignalDB, the next step is to set up your collections. Here's how you can define a `Posts` collection with the reactivity configuration for Svelte: ```js import { Collection, DefaultDataAdapter } from "@signaldb/core"; import svelteReactivityAdapter from "@signaldb/svelte"; const Posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: svelteReactivityAdapter, }); let items = $derived(Posts.find({}).fetch()); ``` This code sets up a `Posts` collection and enables reactivity using Svelte’s built-in reactivity features. ## Creating a Svelte Component Now let's create a component that lists posts and allows the user to add new ones. Here's an example: ```svelte
    {#each items as post}
  • {post.title} by {post.author}
  • {/each}
``` ### Explanation: 1. **Reactive Items List**: The `items` array is set using Svelte's reactivity system, and the component automatically updates when the `Posts` collection changes. 2. **UI Interaction**: Clicking the "Add Post" button inserts a new post into the `Posts` collection, which triggers the component to update. 3. **Rendering Posts**: The component renders a list of posts using the `#each` directive, displaying the post title and author. ## Web Worker Compatibility When using SignalDB with Svelte 5 in applications that utilize web workers, the standard reactivity setup can fail in production builds. This happens because Svelte's runes like `$state` aren't defined in web worker contexts. To solve this issue, specify the reactivity adapter only if you're not in a web worker environment: ```js import { Collection, DefaultDataAdapter } from "@signaldb/core"; import svelteReactivityAdapter from "@signaldb/svelte"; // Check if we're in a web worker const isWebWorker = typeof self !== "undefined" && typeof WorkerGlobalScope !== "undefined" && self instanceof WorkerGlobalScope; const Posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: isWebWorker ? undefined : svelteReactivityAdapter, }); ``` This approach ensures your SignalDB collections work properly both in the main thread and in web workers. ## Conclusion You’ve now learned how to set up SignalDB in a Svelte project and create a reactive component to display and add posts. By leveraging Svelte’s reactivity, you can efficiently manage data and create dynamic user interfaces with SignalDB. ## Next Steps Now that you’ve learned how to use SignalDB in Svelte, you maybe want to explore the possibilities how you can synchronize the data with your backend. Take a look at the [Synchronization Overview](/sync/) to get started --- --- url: /guides/vue.md --- # Using SignalDB with Vue This guide will walk you through integrating SignalDB into a Vue project. You’ll learn how to set up collections and use SignalDB with Vue's reactivity system to manage and display data. ## Prerequisites Before you start, make sure you have a basic understanding of Vue and have a Vue project ready. If you’re not familiar with Vue, you can follow the [Vue Getting Started](https://vuejs.org/guide/introduction.html) guide. Familiarity with signal-based reactivity is also useful. For more information, you can review the [Core Concepts](/core-concepts/#signals-and-reactivity) page and the [Vue Documentation](https://vuejs.org/api/reactivity-core.html) to grasp how reactivity works. ## Installation First, you need to add SignalDB to your project. Run the following command in your terminal: ```bash npm install @signaldb/core ``` Additionally, you will need the Vue-specific reactivity adapter for SignalDB: ```bash npm install @signaldb/vue ``` ## Setting Up SignalDB After installing SignalDB, set up your collections and configure the reactivity adapter for Vue. Here's an example of how to define a `Posts` collection: ```vue ``` In this code, we create a `Posts` collection using the Vue reactivity adapter. The `items` array is kept in sync with the collection using `watchEffect`. ::: info The API of Vue doesn't allow [automatic cleanup](/reference/core/createreactivityadapter/#ondispose-callback-void-dependency-dependency-optional) nor [reactive scope checking](/reference/core/createreactivityadapter/#isinscope-boolean-optional). In Vue, the function passed to the `watchEffect()` function gets a `onCleanup` callback that can be used to cleanup the effect. You have to use this to cleanup the cursor manually (see example above). You also must manually disable reactivity when making calls outside your `watchEffect()` function to avoid memory leaks. You can do this by passing `{ reactive: false }` to your options (e.g. `.find({ ... }, { reactive: false })`). ::: ## Building a Vue Component Now, let’s build a Vue component that lists posts and allows you to add new ones: ```vue ``` ### Breakdown: 1. **Reactivity Setup**: The `Posts` collection is set up with `vueReactivityAdapter` to enable Vue's reactivity system. 2. **Reactive Data**: The `items` array is updated reactively using `watchEffect`, ensuring that changes in the `Posts` collection are reflected in the component. 3. **User Interaction**: The `addPost` function adds a new post to the `Posts` collection, and clicking the button triggers this function. 4. **Rendering**: The template uses Vue's `v-for` directive to display each post from the `items` array. ## Conclusion You have successfully integrated SignalDB into a Vue project and created a reactive component to manage and display posts. This setup allows you to take advantage of SignalDB’s reactivity and Vue's capabilities to build dynamic and responsive applications. ## Next Steps Now that you’ve learned how to use SignalDB in Vue, you maybe want to explore the possibilities how you can synchronize the data with your backend. Take a look at the [Synchronization Overview](/sync/) to get started --- --- url: /troubleshooting.md --- # Troubleshooting In this section, we've compiled some common issues you might encounter while using SignalDB and their respective solutions. Keep in mind, that you can always [file an issue](https://github.com/maxnowack/signaldb/issues/new) at our [Github Repository](https://github.com/maxnowack/signaldb). ## Unable to install SignalDB **Problem:** You may encounter issues during the installation of SignalDB using npm. **Solution:** Make sure you have Node.js and npm installed correctly on your machine. You can verify this by running node -v and npm -v in your terminal. Both commands should return a version number. If not, you'll need to install Node.js and npm. ## Errors when creating a new SignalDB instance **Problem:** You may get errors when trying to create a new instance of SignalDB. **Solution:** Check the arguments passed to the `Collection` constructor — `new Collection(name, dataAdapter, options)` — and to the data adapter. Ensure that all required options are present and are of the correct type. If you're using a custom Storage Adapter, Data Adapter or Reactivity Adapter, verify that it correctly implements its interface. ## Problems with data persistence **Problem:** You may notice that your data is not persisting across sessions or application reloads. **Solution:** Verify that the collection's data adapter has a `storage` option that returns a [Storage Adapter](/data-persistence/) for the collection — a `DefaultDataAdapter` without one keeps the data in memory only. If you wrote your own storage adapter, check its `setup`, `readAll`, `insert`, `replace` and `remove` methods for any errors or unexpected behavior. If you're using a built-in adapter like the localStorage adapter, check if there are any limitations, like storage quotas, that might be affecting your application. ## Issues with reactivity **Problem:** Reactive queries aren't updating when the data changes. **Solution:** Check your Reactivity Adapter and ensure it's working correctly. If you're using a custom adapter, ensure that it correctly implements the Reactivity Adapter interface. Make sure the depend and notify methods in your signals are correctly registering dependencies and notifying them when data changes. ## Data not saving to the desired location **Problem:** Data isn't being saved to the location specified in your Storage Adapter. **Solution:** Double-check the implementation of your write methods in your Storage Adapter. Make sure it correctly writes to the intended location. ## Unhandled promise rejection after a write **Problem:** A write seems to do nothing, or the console reports an unhandled promise rejection, for example after a [schema validation](/schema-validation/) failed. **Solution:** Every write — `insert`, `updateOne`, `removeMany` and the rest — is asynchronous and reports failure by rejecting its promise. A validation error thrown from a `validate` listener, a write to a disposed collection, or a storage adapter that failed to persist the change all end up there. Await the write and handle the error where you make it: ```js try { await Posts.insert({ title: '' }) } catch (error) { showValidationMessage(error) } ``` A write you neither await nor give a `.catch()` turns its failure into an unhandled rejection that is easy to miss. ## Error: "No storage adapter for collection \" **Problem:** Operations on a collection fail with `No storage adapter for collection `. **Solution:** The `AsyncDataAdapter`, the `AutoFetchDataAdapter` and the `WorkerDataAdapterHost` read and write everything through a storage adapter, and this collection has none. Check that the `storage` option is set and that the function returns a storage adapter for *this* collection's name — a factory that only knows some names returns `undefined` for the others. (Leaving the option out altogether is fine for the `AutoFetchDataAdapter`, which then caches in memory.) The error also appears for operations that were still running when the collection was disposed. (The `DefaultDataAdapter` never throws it: without storage it simply keeps the collection in memory.) ## A list is empty although there is data **Problem:** A reactive query renders an empty list or a count of zero, at least for a moment, even though matching items exist. **Solution:** With the async, worker and auto-fetch [data adapters](/data-adapters/), a query is not answered the moment you ask for it. Until it is, the cursor returns a neutral result — an empty list, a count of zero — that looks exactly like a query that matched nothing. Check [`Cursor#isLoading()`](/reference/core/cursor/#⚡️-isloading-reactive) in the same reactive scope and only render "nothing found" once it is `false`, or use `{ async: true }` and await the result outside a reactive scope. See [Queries that are not answered immediately](/queries/#queries-that-are-not-answered-immediately). ## A query stays empty without throwing **Problem:** A query stays empty for good, `isLoading()` has turned `false`, and no error was thrown anywhere. **Solution:** The query may have failed. A failed query does not throw into your code — there is no call that could receive the error — so its cursor keeps serving the neutral empty result. The collection reports the failure through its `query.error` event: ```js Posts.on('query.error', (error, selector, options) => { reportToCrashReporter(error) }) ``` The `AsyncDataAdapter` and the `AutoFetchDataAdapter` usually also pass the error to their `onError` option, which logs it to the console by default, but the event is the one place every failed query reaches. See [Collection events](/queries/#collection-events). ## Console: "Cursor.depend() called outside of a reactive scope without async option" **Problem:** The console shows `Cursor.depend() called outside of a reactive scope without async option; consider using { async: true } or wrapping in a reactive scope`. **Solution:** A query was read synchronously — `fetch()`, `count()`, `findOne()` or another cursor method without `async: true` — outside of a reactive scope. Synchronous reads belong inside an `effect`, an `autorun` or a component's render, where the scope reruns when the result changes. Everywhere else, pass `async: true` and await the result: ```js const post = await collection.findOne({ id: 'abc' }, { async: true }) ``` A collection without a reactivity adapter is always read this way. See [Reactive or awaited](/queries/#reactive-or-awaited). ## Console: "Error during storage operation in collection \" **Problem:** The console shows `Error during storage operation in collection `, and data saved in an earlier session is missing. **Solution:** The `DefaultDataAdapter` logs this when the storage adapter of that collection failed to set up or to load the stored items. `collection.ready()` rejects with the same error and `isReady()` stays `false`; the collection keeps working in memory, but without the stored items, and a `SyncManager` refuses to sync it. The logged error says what went wrong — often a storage quota, a blocked database upgrade or a corrupt record. To handle it yourself instead of logging it, pass `onError` to the adapter; it receives the collection name and the error: ```js const dataAdapter = new DefaultDataAdapter({ storage: name => createLocalStorageAdapter(name), onError: (collectionName, error) => reportToCrashReporter(error), }) ``` ## The application has slowly grown sluggish **Problem:** Nothing is obviously wrong, no single operation is slow, but the application feels heavier than it used to. **Solution:** Look for live queries holding far more rows than anything on screen. A reactive query registered from a long-lived place — a module scope, a store, a component that is never unmounted — keeps its cost for the lifetime of the application, and there is nothing to see while it happens: the query works, it is simply expensive on every write. ```js import { Collection } from '@signaldb/core' Collection.reportLargeQueries(500) ``` Each query holding more than that many rows is reported once, together with the stack that registered it, which is what tells you where it came from. [`Collection.enableDebugMode()`](/reference/core/collection/#enabledebugmode) switches this on at 500 rows along with query timings. Two things usually fix what it finds: give the query a `limit` if the UI only shows a page of it, and project it with `fields` if the UI only renders a few columns. If you're facing an issue not covered in this guide, please feel free to [raise an issue](https://github.com/maxnowack/signaldb/issues/new) on the SignalDB GitHub page. Include a clear description of your problem, steps to reproduce it, and any error messages you're seeing. The more information you provide, the easier it will be for the community to assist you. --- --- url: /local-first.md --- # Local-First Software ## What Is Local-First Software? **Local-first software keeps the primary copy of your data on your own device. The app reads and writes locally, and a sync engine exchanges changes with servers and other devices in the background.** The cloud is still useful for backup, multi-device access and collaboration, but the app no longer depends on it to work. This is the opposite of a typical web app, where the server holds the data and the browser only shows a view of it. In a local-first app, every interaction is answered from local data, so the app is fast, works offline, and keeps working even if the server is slow or gone. The term was coined in the 2019 essay [*Local-first software: You own your data, in spite of the cloud*](https://www.inkandswitch.com/essay/local-first/) by Martin Kleppmann, Adam Wiggins, Peter van Hardenberg and Mark McGranaghan at Ink & Switch. Since then, local-first has grown into a movement with its own [community, conferences and tool directory](https://lofi.so/). ## The Seven Ideals of Local-First Software The Ink & Switch essay defines seven ideals that local-first software should aim for: 1. **No spinners: your work at your fingertips.** Reads and writes are local, so the app responds instantly. 2. **Your work is not trapped on one device.** Data syncs across all devices of a user. 3. **The network is optional.** Everything works offline; sync happens when a connection is available. 4. **Seamless collaboration with your colleagues.** Multiple people can work on the same data, ideally in real time. 5. **The Long Now.** Data stays accessible for years, even if the vendor's servers disappear. 6. **Security and privacy by default.** Data on servers can be encrypted end to end. 7. **You retain ultimate ownership and control.** Users can copy, modify and delete their data without asking a service for permission. Few apps fulfil all seven ideals. In practice, "local-first" is used for a spectrum of architectures. Most production apps start with the first three (speed, multi-device and offline) and keep a server as the source of truth. ## How Local-First Apps Work A local-first app has three building blocks: ```mermaid graph LR UI[UI components] -->|reactive queries| DB[(Local database)] UI -->|writes| DB DB -->|persist| S[(Device storage
IndexedDB / OPFS / SQLite)] DB <-->|sync engine
push & pull changes| SV[Server / other devices] ``` 1. **A local database** holds the data the user works with. In the browser it is persisted in [IndexedDB, OPFS or localStorage](/data-persistence/), on mobile usually in SQLite. 2. **Reactive queries** connect the database to the UI. When data changes, whether by a local write or by sync, every affected view updates automatically. 3. **A sync engine** records local changes, pushes them to the server, pulls remote changes and resolves conflicts. Because the UI only ever talks to the local database, [optimistic UI](/optimistic-ui/) and [offline support](/offline-first/) come for free: a write is visible immediately and is synced later. ## Approaches to Local-First Sync The sync engine is the hardest part of a local-first app. There are three common approaches: | Approach | How it works | Typical tools | Good for | |---|---|---|---| | **Server-authoritative sync** | Clients queue local changes and replay them on top of the latest server state; the server decides | SignalDB, RxDB, WatermelonDB, Replicache/Zero | Apps with an existing backend, business rules and permissions on the server | | **Database replication** | A client database replicates a subset of a server database (e.g. Postgres or CouchDB) | PouchDB with CouchDB, ElectricSQL, PowerSync | Apps whose backend is built around that database | | **CRDTs** | Data types that merge concurrent changes automatically, without a central authority | Automerge, Yjs, TinyBase (MergeableStore) | Collaborative editing, peer-to-peer sync | Server-authoritative sync is the most common choice for business applications: it keeps validation, permissions and conflict rules on the server and works with ordinary REST or GraphQL APIs. CRDTs come closest to the "ownership" and "Long Now" ideals, but make server-side validation and schema changes harder. ## Local-First vs. Offline-First vs. Cloud Apps | | Cloud app (thin client) | Offline-first app | Local-first app | |---|---|---|---| | Primary copy of the data | Server | Server, cached on the client | Client device | | Works offline | No | Yes | Yes | | Speed of interactions | Network round trip | Instant for cached data | Instant | | Multi-device and collaboration | Yes (via server) | Yes (via server) | Yes (via sync) | | Data ownership | Vendor | Vendor | User (to varying degrees) | [Offline-first](/offline-first/) describes the *capability* to work without a network. Local-first is the broader *philosophy* that the local copy is the primary one. Technically, both rely on the same foundation: a local database with sync. ## Benefits and Trade-offs **Benefits** * **Instant UI**: no loading spinners for reads or writes. * **Offline support**: the app works on trains, planes and bad Wi-Fi. * **Less backend load**: queries run on the client; the server mainly stores and distributes changes. * **Simpler frontend state**: the local database replaces ad-hoc caches and global stores. **Trade-offs** * **Data has to fit on the device.** You usually sync a user-specific subset, not the whole database. * **Sync and conflicts are real work.** You need a clear conflict strategy and must handle rejected changes. * **Permissions move to the sync layer.** The server must check every pushed change, because clients can no longer be trusted to only call allowed endpoints. * **Schema changes are harder.** Old clients with offline data must keep working after a migration. * **Initial load**: the first sync of a large dataset can take a while. ## Local-First Tools for JavaScript The JavaScript ecosystem offers tools for every layer: * **Local databases with sync**: SignalDB, RxDB, Dexie.js, PouchDB, WatermelonDB, TinyBase, TanStack DB. See the [JavaScript database comparison](/comparison/) for a detailed feature matrix. * **Sync engines for existing databases**: ElectricSQL and PowerSync (Postgres and other databases), Replicache/Zero. * **CRDT libraries**: Automerge, Yjs. * **Hosted local-first platforms**: InstantDB, Jazz, Triplit and others. The [local-first directory on lofi.so](https://lofi.so/directory) lists many more projects. ## Building a Local-First App with SignalDB [SignalDB](/getting-started/) is a reactive local-first database for JavaScript that uses server-authoritative sync with any backend. A local-first setup takes three steps. **1. Create a persisted, reactive collection** using the signal library of your framework (here Solid; adapters exist for Angular, Vue, Preact, Svelte, MobX and [more](/reactivity/#reactivity-libraries)): ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import createIndexedDBAdapter from '@signaldb/indexeddb' import solidReactivityAdapter from '@signaldb/solid' export const dataAdapter = new DefaultDataAdapter({ storage: createIndexedDBAdapter({ databaseName: 'my-app', version: 1, schema: { 'notes': ['archived'], // stores the SyncManager keeps its change queue in 'app-changes': ['collectionName'], 'app-snapshots': ['collectionName'], 'app-sync-operations': ['collectionName', 'status'], }, }), }) export const notes = new Collection('notes', dataAdapter, { reactivity: solidReactivityAdapter, }) ``` **2. Query and write locally.** Queries inside effects re-run when data changes; writes are visible immediately: ```js import { createEffect } from 'solid-js' createEffect(() => { const myNotes = notes.find({ archived: false }, { sort: { updatedAt: -1 } }).fetch() render(myNotes) }) await notes.insert({ text: 'Local-first!', archived: false, updatedAt: Date.now() }) ``` **3. Add sync with your backend.** The [`SyncManager`](/sync/) persists the queue of local changes, pushes them to your API, pulls remote changes and resolves conflicts by replaying local changes on the latest server data: ```js import { SyncManager } from '@signaldb/sync' const syncManager = new SyncManager({ id: 'app', dataAdapter, // the same data adapter the collections use pull: async ({ apiPath }) => ({ items: await fetch(apiPath).then(res => res.json()) }), push: async ({ apiPath }, { changes }) => { await fetch(apiPath, { method: 'POST', body: JSON.stringify(changes) }) }, registerRemoteChange: (options, onChange) => { // e.g. call onChange() when your WebSocket or SSE connection reports new data }, }) syncManager.addCollection(notes, { name: 'notes', apiPath: '/api/notes' }) ``` This covers the first four local-first ideals (instant UI, multi-device, offline, collaboration through the server) while your backend stays the source of truth. There are complete examples for a [plain HTTP API](https://signaldb.js.org/examples/replication-http/), [Supabase](https://signaldb.js.org/examples/supabase/), [Firebase](https://signaldb.js.org/examples/firebase/) and [Appwrite](https://signaldb.js.org/examples/appwrite/). ## Frequently Asked Questions ### What does local-first mean? Local-first means that an application stores the primary copy of its data on the user's device, reads and writes it locally, and synchronizes with servers and other devices in the background. ### What is a local-first database? A database that runs inside the client application (browser, desktop or mobile app), persists data on the device and has a sync mechanism to exchange changes with a server or other clients. ### Is local-first the same as offline-first? Not exactly. Offline-first means the app keeps working without a network. Local-first additionally treats the local copy as the primary one and aims for user ownership of data. Both are built on a local database with sync. ### Do local-first apps still need a server? Usually yes: for sync between devices, backups, collaboration, authentication and permissions. The difference is that the app does not need the server to *work*. ### Do I need CRDTs to build a local-first app? No. CRDTs are one way to merge concurrent changes, well suited for collaborative editing. Many local-first apps use server-authoritative sync instead, where local changes are replayed on the latest server state. SignalDB uses this approach. ## Conclusion Local-first software moves the primary copy of data to the user's device and treats the network as optional. The result is faster, more resilient apps, at the cost of handling sync, conflicts and permissions carefully. For JavaScript developers, the main decision is the local database and its sync model. [Compare the options](/comparison/), or [get started with SignalDB](/getting-started/) to add local-first data to your existing app and backend. --- --- url: /comparison.md --- # JavaScript Database Comparison There are several good databases for building [local-first](/local-first/) and [offline-first](/offline-first/) JavaScript apps. They differ in how they store data, how query results reach your UI, how they sync with a server and what they cost. This page compares **SignalDB, RxDB, Dexie.js, PouchDB, WatermelonDB, TinyBase and TanStack DB** and helps you pick the right one for your project. ::: info About this comparison This page is written by the SignalDB maintainers. We try to be fair and point out where other projects are the better choice. Information was checked against each project's official documentation and repository. **Last reviewed: October 2026.** If something is outdated, please [open an issue](https://github.com/maxnowack/signaldb/issues/new) or [edit this page](https://github.com/maxnowack/signaldb/edit/main/docs/articles/comparison.md). ::: ## At a Glance | | Short description | License | |---|---|---| | **[SignalDB](/getting-started/)** | Reactive in-memory database with MongoDB-like queries, signal-based reactivity, storage adapters and backend-agnostic sync | MIT | | **[RxDB](https://rxdb.info/)** | Feature-rich NoSQL database with pluggable storages and a replication engine | Apache 2.0 core, paid Pro tiers | | **[Dexie.js](https://dexie.org/)** | Minimalistic wrapper for IndexedDB with live queries, optional Dexie Cloud sync service | Apache 2.0 (Dexie Cloud is a paid service with a free tier) | | **[PouchDB](https://pouchdb.com/)** | CouchDB-inspired database for the browser with built-in CouchDB sync | Apache 2.0 | | **[WatermelonDB](https://watermelondb.dev/)** | Lazy-loading reactive database for React and React Native, built on SQLite | MIT | | **[TinyBase](https://tinybase.org/)** | Reactive in-memory store of tables and values with persisters and CRDT-based sync | MIT | | **[TanStack DB](https://tanstack.com/db)** | Reactive client store that extends TanStack Query with collections and live queries (beta) | MIT | ## Feature Comparison | | SignalDB | RxDB | Dexie.js | PouchDB | WatermelonDB | TinyBase | TanStack DB | |---|---|---|---|---|---|---|---| | **Data model** | Document collections | Document collections with JSON schema | IndexedDB tables | Documents (CouchDB model) | Tables and models | Tables and values | Typed collections | | **Query API** | MongoDB-like selectors | Mango (MongoDB-like) queries | Index-based queries (`where()`) | Mango queries via `pouchdb-find`, map/reduce | `Q.where` query builder | TinyQL queries | SQL-like query builder (`from`, `where`, `join`) | | **Reactivity** | Uses the signals of your framework via adapters | RxJS observables, custom reactivity for signals | `liveQuery()` observables, `useLiveQuery` for React | Changes feed | Observables, React helpers | Listeners and React hooks | Live queries with framework hooks | | **Storage (browser)** | IndexedDB, OPFS, localStorage | IndexedDB (via Dexie.js), memory and more; OPFS in paid tiers | IndexedDB | IndexedDB | LokiJS adapter | IndexedDB, localStorage and more via persisters | In memory; data is loaded through collection types | | **Other platforms** | Node.js (file system) | Node.js, Electron, Capacitor, React Native, Tauri (SQLite in paid tiers) | Browser, Electron, Capacitor | Node.js (LevelDB) | iOS, Android (SQLite), Node.js, Windows | Node.js, React Native and more via persisters | Wherever TanStack Query runs | | **Sync** | Built-in sync engine; you implement `pull`/`push` for any backend | Replication engine with plugins (HTTP, GraphQL, WebSocket, CouchDB, Firestore, MongoDB, WebRTC, …) | Dexie Cloud (hosted or self-hosted) or custom | Built-in two-way sync with CouchDB-compatible servers | Sync protocol you implement on your backend | CRDT-based synchronizers (WebSocket, BroadcastChannel, custom) | Through collection types (TanStack Query, ElectricSQL, PowerSync, RxDB, …) | | **Conflict handling** | Local changes replayed on latest server data, last change wins | Conflict handler, customizable | Handled by Dexie Cloud | CouchDB revision model | Handled by your backend | CRDT merge | Depends on the sync source | | **Optimistic UI** | Built in (all writes are local first) | Built in (local first) | Built in (local first) | Built in (local first) | Built in (local first) | Built in (local first) | Built in (optimistic mutations) | | **TypeScript** | ✅ | ✅ | ✅ | Community types | ✅ | ✅ | ✅ | ## SignalDB vs. RxDB [RxDB](https://rxdb.info/) is the most feature-complete project in this list: JSON schemas, migrations, attachments, encryption, many storages, a replication engine with ready-made plugins and support for most JavaScript runtimes. The core is open source (Apache 2.0); performance-oriented storages such as OPFS and SQLite, and some plugins, are part of paid tiers. **How SignalDB differs:** * **Reactivity**: RxDB is built on RxJS observables and can map them to signals with a custom reactivity factory. SignalDB is designed around signals: queries run inside your framework's effects and are tracked by its own reactivity system, with ready-made adapters for Angular, Solid, Vue, Preact, Svelte, MobX and more. * **Scope and size**: SignalDB is deliberately smaller. It focuses on collections, queries, reactivity, persistence and sync, and leaves validation, schemas and storage details to adapters and your own code. * **Cost**: all SignalDB packages, including the OPFS adapter, are MIT-licensed. For a detailed one-to-one comparison with code examples, see [SignalDB vs RxDB](/signaldb-vs-rxdb/). **Choose RxDB if** you need its breadth: many storages, ready-made replication plugins, encryption, React Native/Capacitor support today, or professional support. **Choose SignalDB if** you want a lightweight, signal-native data layer for a web app and sync with your own API. ## SignalDB vs. Dexie.js [Dexie.js](https://dexie.org/) is a minimalistic wrapper around IndexedDB. It queries IndexedDB directly using indexes, which makes it a good fit for large datasets that should not be held in memory. `liveQuery()` turns queries into observables, and `useLiveQuery()` integrates them into React. Sync is available through **Dexie Cloud**, a commercial service with a free tier that can also be self-hosted. **How SignalDB differs:** * **In memory vs. on disk**: By default, SignalDB keeps collections in memory and persists them, which makes queries synchronous and very fast but means all data of a collection is loaded into memory; the `AsyncDataAdapter` answers queries from storage instead. Dexie reads from IndexedDB on demand. * **Queries**: SignalDB uses MongoDB-like selectors on any field. Dexie queries work through the indexes you declare in your schema. * **Sync**: SignalDB syncs with any backend through your own `pull`/`push` functions. Dexie's built-in sync is tied to Dexie Cloud. **Choose Dexie.js if** you work with large amounts of data directly in IndexedDB or want a hosted sync and auth service. **Choose SignalDB if** your dataset fits in memory and you want rich queries, signal-based reactivity and sync with your existing backend. ## SignalDB vs. PouchDB [PouchDB](https://pouchdb.com/) is an Apache project inspired by CouchDB. Its main strength is built-in, battle-tested two-way replication with CouchDB-compatible servers (CouchDB, Couchbase Sync Gateway and others), including revision-based conflict handling. **How SignalDB differs:** * **Backend**: PouchDB shines when your backend speaks the CouchDB replication protocol. SignalDB is backend-agnostic: REST, GraphQL, WebSockets or a BaaS such as [Supabase](/supabase/) or [Firebase](/firebase/). * **Reactivity**: PouchDB exposes a changes feed. SignalDB gives you reactive queries that integrate with your framework's signals. **Choose PouchDB if** you run (or want to run) CouchDB. **Choose SignalDB if** you already have an API that does not speak the CouchDB protocol. ## SignalDB vs. WatermelonDB [WatermelonDB](https://watermelondb.dev/) is built for React and React Native apps with large datasets. It uses SQLite on mobile, loads data lazily, and is optimized to keep app launch fast with tens of thousands of records. Sync works through a protocol that you implement on your backend. **How SignalDB differs:** * **Platform focus**: WatermelonDB is mobile-first. SignalDB targets web apps today; proper React Native support is planned for SignalDB v2. * **Framework**: WatermelonDB is optimized for React. SignalDB works with any framework that has signals. **Choose WatermelonDB if** you build a React Native app with a lot of local data. **Choose SignalDB if** you build a web app with Angular, Vue, Solid, Svelte, React or another framework. ## SignalDB vs. TinyBase [TinyBase](https://tinybase.org/) is a reactive in-memory store organized as tables and values. It has persisters for many storage backends and synchronizers based on a CRDT (`MergeableStore`) that can sync between clients and servers over WebSockets, BroadcastChannel or custom transports. **How SignalDB differs:** * **Data model**: TinyBase stores tabular data (tables, rows, cells). SignalDB stores JSON documents in collections and queries them with MongoDB-like selectors. * **Sync model**: TinyBase merges state with a CRDT, which works well for peer-to-peer and collaborative scenarios. SignalDB syncs with an authoritative backend through `pull` and `push`. **Choose TinyBase if** you want CRDT-based sync or a tabular store with React hooks. **Choose SignalDB if** your server is the source of truth and you want document-style queries. ## SignalDB vs. TanStack DB [TanStack DB](https://tanstack.com/db) extends TanStack Query with normalized collections, live queries and optimistic mutations. Data is loaded into collections from TanStack Query or from sync engines, and queried with a SQL-like query builder that supports joins. TanStack DB is currently in **beta**. **How SignalDB differs:** * **Persistence and offline**: SignalDB persists every collection locally (IndexedDB, OPFS, localStorage) and queues changes for sync, so the app works offline. TanStack DB focuses on the in-memory client store; data is loaded through collection types such as TanStack Query, ElectricSQL, PowerSync or RxDB, which are also responsible for persistence. * **Ecosystem**: TanStack DB integrates tightly with TanStack Query. SignalDB is independent of your data-fetching library. **Choose TanStack DB if** your app already uses TanStack Query and you want live queries with joins on top of it. **Choose SignalDB if** you need local persistence and offline support with your own backend. ## Alternatives to RxDB If you are looking for an RxDB alternative, the right choice depends on why RxDB does not fit: * **You want something smaller and signal-native for a web app**: SignalDB. * **You want to work directly with IndexedDB and large datasets**: Dexie.js. * **Your backend is CouchDB**: PouchDB. * **You build a React Native app with lots of data**: WatermelonDB. * **You want CRDT-based sync**: TinyBase. * **You already use TanStack Query**: TanStack DB. ## Which Database Should You Choose? Ask these questions in this order: 1. **Which platform?** Web only, or also React Native/Electron/Capacitor? Mobile-heavy apps narrow the list to RxDB and WatermelonDB. 2. **Which backend?** If the backend is fixed (CouchDB, a hosted service, your own REST/GraphQL API), choose a database that syncs with it without workarounds. 3. **How much data per user?** If it fits comfortably in memory, in-memory databases (SignalDB, TinyBase, TanStack DB) give you the fastest queries. For very large local datasets, prefer databases that query storage directly (Dexie.js, WatermelonDB, RxDB with an indexed storage). 4. **How should data reach your UI?** Signals (SignalDB), RxJS observables (RxDB), hooks (Dexie.js, TinyBase, TanStack DB) or observables with React helpers (WatermelonDB). 5. **What can you pay for?** All projects are open source, but some features (RxDB Pro, Dexie Cloud) are commercial. ## When SignalDB Is the Right Choice SignalDB fits best when: * you build a **web app** with Angular, Vue, Solid, Svelte, React or another framework with signals; * you want **reactive queries** that plug into your framework's own reactivity; * the data of each user **fits in memory** (thousands to tens of thousands of documents); * you have **an existing backend** (REST, GraphQL, WebSockets, Supabase, Firebase, Appwrite) and want to keep it; * you want **optimistic UI and offline support** without adopting a new backend or a paid service. Start with the [Getting Started guide](/getting-started/), or read more about [offline-first](/offline-first/), [optimistic UI](/optimistic-ui/) and [JavaScript signals](/signals/). ## Frequently Asked Questions ### What is the best local-first database for JavaScript? There is no single best option. RxDB is the most feature-complete, Dexie.js is the most direct IndexedDB wrapper, PouchDB is best with CouchDB, WatermelonDB is built for React Native, TinyBase offers CRDT sync, TanStack DB extends TanStack Query, and SignalDB is a lightweight, signal-native choice for web apps with an existing backend. ### What is the difference between RxDB and Dexie.js? RxDB is a full database with schemas, replication and pluggable storages; one of its storages is built on Dexie.js. Dexie.js is a thin wrapper around IndexedDB with live queries and an optional sync service (Dexie Cloud). ### What is the difference between RxDB and PouchDB? Both are document databases that sync. PouchDB implements the CouchDB replication protocol and works best with CouchDB-compatible servers. RxDB has its own replication engine with plugins for many backends, including CouchDB. ### Is SignalDB free? Yes. SignalDB and all its adapters are open source under the MIT license. --- --- url: /signaldb-vs-rxdb.md --- # SignalDB vs RxDB SignalDB and RxDB are both local-first JavaScript databases: data lives on the client, queries run locally, and changes are synced with a backend. They differ in philosophy. **RxDB is a feature-rich database** with schemas, many storages and a replication engine with ready-made plugins. **SignalDB is a lightweight, signal-native data layer** that plugs into the reactivity of your framework and syncs with any backend through two functions. ::: info About this comparison This page is written by the SignalDB maintainers. Information about RxDB was checked against the [RxDB documentation](https://rxdb.info/) (October 2026). If something is outdated, please [open an issue](https://github.com/maxnowack/signaldb/issues/new). For a comparison with more databases, see the [JavaScript database comparison](/comparison/). ::: ## Overview | | SignalDB | RxDB | |---|---|---| | **Reactivity** | Signals of your framework via adapters (Angular, Solid, Vue, Preact, Svelte, MobX, …) | RxJS observables; custom reactivity factory for signals | | **Data model** | Schema-less document collections; optional validation via a `validate` event | Document collections with a required JSON Schema | | **Queries** | MongoDB-like selectors (powered by [mingo](https://github.com/kofrasa/mingo)), sort, projection, skip, limit | Mango (MongoDB-like) queries with indexes | | **Where queries run** | Against in-memory collections (synchronous) by default; against storage or in a web worker with other data adapters | Through the storage's query engine (asynchronous) | | **Storage** | IndexedDB, OPFS, localStorage, file system; custom adapters | Many storages; IndexedDB (via Dexie.js) and memory are free, OPFS, SQLite and file system storages are in paid tiers | | **Sync** | Built-in sync engine; you implement `pull` and `push` for your API | Replication engine with plugins (HTTP, GraphQL, WebSocket, CouchDB, Firestore, MongoDB, WebRTC, …) | | **Conflicts** | Local changes are replayed on the latest server data; last change wins | Customizable conflict handler per collection | | **Schema migrations** | Not needed (schema-less) | Built-in migration strategies per schema version | | **Extras** | ORM-style relations, indexes, devtools (beta) | Attachments, encryption, key compression, leader election, CRDT plugin, full-text and vector search, and more | | **Platforms** | Browser, Node.js; React Native planned for v2 | Browser, Node.js, Electron, Capacitor, React Native, Expo, Tauri, Deno | | **License** | MIT, all packages free | Apache 2.0 core; paid Pro tiers for premium storages and plugins. The open-source version allows up to 13 open collections in parallel | ## Code Side by Side The same task in both databases: a persisted todo collection, a reactive list of open todos, and an insert. **SignalDB** (here with Preact Signals; other frameworks use their own adapter): ```js import { effect } from '@preact/signals-core' import { Collection, DefaultDataAdapter } from '@signaldb/core' import preactReactivityAdapter from '@signaldb/preact' import createIndexedDBAdapter from '@signaldb/indexeddb' const dataAdapter = new DefaultDataAdapter({ storage: createIndexedDBAdapter({ databaseName: 'my-app', version: 1, schema: { todos: ['completed'] }, }), }) const todos = new Collection('todos', dataAdapter, { reactivity: preactReactivityAdapter, }) effect(() => { const cursor = todos.find({ completed: false }) render(cursor.fetch()) return () => cursor.cleanup() }) await todos.insert({ title: 'Buy milk', completed: false }) ``` **RxDB** (with the free Dexie.js-based IndexedDB storage): ```js import { createRxDatabase } from 'rxdb' import { getRxStorageDexie } from 'rxdb/plugins/storage-dexie' const db = await createRxDatabase({ name: 'app', storage: getRxStorageDexie() }) await db.addCollections({ todos: { schema: { version: 0, primaryKey: 'id', type: 'object', properties: { id: { type: 'string', maxLength: 100 }, title: { type: 'string' }, completed: { type: 'boolean' }, }, required: ['id', 'title', 'completed'], }, }, }) db.todos.find({ selector: { completed: false } }).$.subscribe(render) await db.todos.insert({ id: crypto.randomUUID(), title: 'Buy milk', completed: false }) ``` The difference in style is typical: RxDB asks you to define a schema up front and gives you observables; SignalDB starts schema-less and lets your framework's effects track the query. ## Reactivity: Signals vs. Observables RxDB is built on RxJS. Every query exposes an observable (`.$`) that you subscribe to, and RxDB offers a custom reactivity factory to turn these observables into signals for Angular, Preact, Vue or other libraries. SignalDB is built around signals from the start. You run a normal query inside an effect of your framework (`effect`, `createEffect`, `watchEffect`, `$effect`, `autorun`), and SignalDB registers the dependency through a small [reactivity adapter](/reactivity/). There is no subscription to manage in the component, and query results are plain arrays. **In practice:** if your app already uses RxJS heavily, RxDB fits naturally. If your framework is signal-based (Angular Signals, Solid, Vue, Svelte 5, Preact), SignalDB feels native. See [JavaScript Signals Explained](/signals/) for background. ## Schemas and Validation RxDB requires a JSON Schema for every collection. It uses the schema for indexes, validation, encryption of fields, key compression and versioned migrations. That adds structure and safety, but also upfront work and migration code when the shape of your data changes. SignalDB is schema-less. You can add [validation](/schema-validation/) with any library (e.g. Zod) through the collection's `validate` event, and old documents keep working without migrations. ## Storage and Performance Model With its default [data adapter](/data-adapters/), SignalDB loads each collection into memory and persists changes through a [storage adapter](/data-persistence/). Queries are synchronous and run on the in-memory data, which makes them very fast and allows ad-hoc filters on any field. The trade-off: all documents of a collection must fit into memory. This works well for typical per-user datasets (thousands to tens of thousands of documents). For larger datasets, the `AsyncDataAdapter` answers queries from storage instead of memory, and the `WorkerDataAdapter` moves the data layer into a web worker. RxDB queries go through its storage layer. Depending on the storage, data is read from IndexedDB, OPFS or SQLite on demand, with indexes defined in the schema. This scales to larger datasets, and RxDB offers performance plugins (memory-mapped storage, sharding, workers) for demanding cases; several of those are part of the paid tiers. ## Sync and Backends Both databases sync local changes with a backend, and neither requires a specific server. * **RxDB** has a generic replication protocol plus ready-made plugins for HTTP, GraphQL, WebSocket, CouchDB, Firestore, MongoDB, WebRTC and others. If one of them matches your backend, you get sync with little code. * **SignalDB** has one generic [sync engine](/sync/): you write a `pull` function (fetch data) and a `push` function (send changes), optionally a hook for live updates. That keeps sync close to your existing REST or GraphQL API and your server's validation logic. There are examples for [HTTP](https://signaldb.js.org/examples/replication-http/), [Supabase](https://signaldb.js.org/examples/supabase/), [Firebase](https://signaldb.js.org/examples/firebase/) and [Appwrite](https://signaldb.js.org/examples/appwrite/). ## When to Choose RxDB * You need **React Native, Capacitor, Electron or Tauri** support today. * You want **ready-made replication** with CouchDB, Firestore, GraphQL or WebRTC. * You need **large local datasets** that should not be held in memory. * You need **encryption, attachments, schema migrations** or other advanced plugins. * You want **commercial support** and are fine with paid tiers for premium features. ## When to Choose SignalDB * You build a **web app** with a signal-based framework (Angular, Solid, Vue, Svelte, Preact) or React. * You want **queries that integrate with your framework's reactivity** without RxJS. * Your data per user **fits in memory** and you want fast, ad-hoc queries. * You have **an existing backend** and want to keep full control over the sync logic. * You want a **small, MIT-licensed** library without collection limits or paid tiers. ## Migrating from RxDB to SignalDB Moving from RxDB to SignalDB mostly means: 1. Creating a SignalDB [collection](/reference/core/collection/) for each RxDB collection, with a [storage adapter](/data-persistence/) underneath its [data adapter](/data-adapters/). 2. Translating queries: RxDB's `{ selector: { … } }` becomes the selector itself in SignalDB's `find()`; `sort`, `skip` and `limit` move to the options object. 3. Replacing observable subscriptions (`.$.subscribe`) with queries inside your framework's effects. 4. Re-implementing replication as `pull` and `push` functions of the [`SyncManager`](/sync/). 5. Moving schema rules into a [`validate` handler](/schema-validation/) if you still need them. ## Frequently Asked Questions ### Is SignalDB a replacement for RxDB? For web apps whose data fits in memory and that sync with their own backend, yes. For mobile apps, very large local datasets, or features like encryption and attachments, RxDB is the better fit today. ### Is RxDB free? The RxDB core is open source under the Apache 2.0 license. Premium storages (such as OPFS and SQLite), performance plugins and the removal of the 13-collection limit are part of paid tiers. ### Does SignalDB use RxJS? No. SignalDB integrates with the signal or reactivity library you already use through adapters, without RxJS. ### Which is faster, SignalDB or RxDB? It depends on the workload. With its default data adapter, SignalDB queries in-memory data synchronously, which is very fast for datasets that fit in memory. RxDB with an indexed storage handles larger datasets without loading everything into memory. Benchmark with your own data and queries. --- --- url: /browser-storage.md --- # localStorage vs IndexedDB vs OPFS ## Quick Answer **Use localStorage for a few small settings, IndexedDB for structured application data, and the Origin Private File System (OPFS) for large files or high-performance file-based storage.** localStorage is synchronous and limited to a few megabytes. IndexedDB is asynchronous, transactional and can store large amounts of structured data. OPFS gives each website a private file system with fast synchronous access in Web Workers. | | localStorage | IndexedDB | OPFS | |---|---|---|---| | **Data model** | String key/value pairs | Object stores with indexes and transactions | Files and directories | | **Value types** | Strings only (objects need `JSON.stringify`) | Structured clone: objects, arrays, `Date`, `Blob`, `ArrayBuffer`, `Map`, … | Bytes (text or binary) | | **API style** | Synchronous | Asynchronous (event-based) | Asynchronous; synchronous access handles in dedicated Web Workers | | **Capacity** | Around 5 MB per origin | Quota-based, usually a large share of free disk space | Quota-based, shared with IndexedDB | | **Available in Web Workers** | No | Yes | Yes | | **Querying** | Lookup by key | Lookup by key and indexes, cursors | None (you read files) | | **Blocks the main thread** | Yes, on every read and write | No | No | | **Typical use** | Theme, language, small flags | App data, offline caches, local databases | Large files, binary data, database engines | ## localStorage [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) is the simplest browser storage: a synchronous key/value store for strings that persists across sessions. ```js localStorage.setItem('settings', JSON.stringify({ theme: 'dark' })) const settings = JSON.parse(localStorage.getItem('settings') ?? '{}') ``` **Strengths** * Very simple API, available everywhere. * Synchronous reads are convenient for values needed at startup, such as the color theme. **Limitations** * **Small**: browsers allow around 5 MB per origin. * **Strings only**: everything has to be serialized and parsed, which gets slow for larger data. * **Blocks the main thread**: every access is synchronous, so large reads and writes cause jank. * **No access from Web Workers or Service Workers.** `sessionStorage` has the same API but is cleared when the tab is closed. ## IndexedDB [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) is a transactional database built into every browser. It stores JavaScript values (anything that can be structured-cloned) in object stores, supports indexes for lookups, and runs asynchronously. ```js const request = indexedDB.open('app', 1) request.onupgradeneeded = () => { request.result.createObjectStore('todos', { keyPath: 'id' }) } request.onsuccess = () => { const db = request.result const tx = db.transaction('todos', 'readwrite') tx.objectStore('todos').put({ id: '1', title: 'Buy milk', completed: false }) } ``` **Strengths** * **Large capacity**: limited by the browser's storage quota, not a fixed size. * **Rich values**: stores objects, dates, binary data and blobs without serialization. * **Asynchronous** and available in Web Workers and Service Workers. * **Transactions and indexes** for consistent writes and efficient lookups. **Limitations** * **Verbose, event-based API.** Most developers use a wrapper library or a database built on top (see below). * **Limited query capabilities**: lookups are by key or index; there are no ad-hoc queries on arbitrary fields. * **Schema upgrades** are handled through version numbers and `onupgradeneeded`. ### IndexedDB Wrappers and Libraries Because the raw API is cumbersome, IndexedDB is usually used through a library: * **Thin wrappers** such as [`idb`](https://github.com/jakearchibald/idb) turn the event-based API into promises. * **IndexedDB-first databases** such as [Dexie.js](https://dexie.org/) add a fluent query API and live queries. * **Local databases with IndexedDB persistence** such as [SignalDB](#browser-storage-with-signaldb) or RxDB keep data queryable in memory or through their own query engine, add reactivity and sync, and use IndexedDB only for persistence. See the [JavaScript database comparison](/comparison/) for the differences. ## OPFS (Origin Private File System) The [Origin Private File System](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system) is a file system that the browser provides privately to each origin. It is part of the File System API and is supported in all current major browsers. Unlike the File System Access API, it needs no permission prompt, and its files are not visible to the user. ```js const root = await navigator.storage.getDirectory() const fileHandle = await root.getFileHandle('todos.json', { create: true }) const writable = await fileHandle.createWritable() await writable.write(JSON.stringify([{ id: '1', title: 'Buy milk' }])) await writable.close() const file = await fileHandle.getFile() console.log(JSON.parse(await file.text())) ``` Safari added `createWritable()` later than the rest of OPFS. If you need to support older Safari versions, write through a synchronous access handle in a Web Worker instead. In a dedicated Web Worker, `fileHandle.createSyncAccessHandle()` provides **synchronous, in-place reads and writes**. This is the fastest way to work with files in the browser, and it is what SQLite and other database engines compiled to WebAssembly use for persistence. **Strengths** * **Fast file I/O**, especially with synchronous access handles in workers. * **Ideal for large or binary data** and for database engines that expect a file system. * **Quota-based capacity**, like IndexedDB. **Limitations** * **No queries**: OPFS stores files; structure and indexing are up to you or your library. * **Fastest API only in workers**: synchronous access handles are not available on the main thread. * **Private to the origin**: users cannot open or export the files directly. ## Storage Limits, Quotas and Eviction IndexedDB, OPFS, the Cache API and other storage APIs share **one quota per origin**. Browsers typically allow an origin to use a large share of the available disk space; the exact limits differ between browsers and devices. Check the current usage and quota with: ```js const { usage, quota } = await navigator.storage.estimate() console.log(`${(usage / 1e6).toFixed(1)} MB of ${(quota / 1e6).toFixed(0)} MB used`) ``` By default, storage is **best-effort**: when the device runs low on disk space, the browser may delete the data of origins that were not used recently. For data that must not be lost, request **persistent storage**: ```js const persisted = await navigator.storage.persist() ``` Safari additionally deletes all script-writable storage (including IndexedDB and localStorage) of websites that the user has not interacted with for seven days, unless the site was added to the home screen as a web app. Apps that store important data locally should therefore also sync it to a server. ## When to Use Which * **A handful of small values needed synchronously at startup** (theme, language, feature flags): **localStorage**. * **Structured application data, offline data, caches of API responses**: **IndexedDB**, ideally through a library. * **Large files, binary data, or a database engine that needs a file system**: **OPFS**. * **HTTP responses for offline asset loading**: the **Cache API** in a Service Worker (not covered here). Many apps combine them: settings in localStorage, data in IndexedDB or OPFS, and assets in the Cache API. ## Browser Storage with SignalDB [SignalDB](/getting-started/) is a reactive local database that keeps collections in memory and persists them with a [storage adapter](/data-persistence/). Switching the storage means handing the data adapter a different `storage` function, and your queries, reactivity and sync code stay the same: ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import createLocalStorageAdapter from '@signaldb/localstorage' import createIndexedDBAdapter from '@signaldb/indexeddb' import createOPFSAdapter from '@signaldb/opfs' // small collection in localStorage const localStorageData = new DefaultDataAdapter({ storage: name => createLocalStorageAdapter(name), }) const settings = new Collection('settings', localStorageData) // application data in IndexedDB const indexedDBData = new DefaultDataAdapter({ storage: createIndexedDBAdapter({ databaseName: 'my-app', version: 1, schema: { todos: ['completed'] }, }), }) const todos = new Collection('todos', indexedDBData) // application data as files in OPFS const opfsData = new DefaultDataAdapter({ storage: name => createOPFSAdapter(name), }) const notes = new Collection('notes', opfsData) todos.find({ completed: false }).fetch() // same query API for every storage ``` Because queries run against the in-memory collection, they are synchronous and support MongoDB-like selectors on any field, regardless of which storage you choose. See the adapter references for [localStorage](/reference/localstorage/), [IndexedDB](/reference/indexeddb/) and [OPFS](/reference/opfs/), or [build your own adapter](/reference/core/createstorageadapter/). ## Frequently Asked Questions ### Is IndexedDB better than localStorage? For anything beyond a few small values, yes. IndexedDB is asynchronous, stores structured data without serialization, has a much larger quota and works in Web Workers. localStorage is simpler and synchronous, which is only an advantage for tiny values needed at startup. ### How much data can I store in IndexedDB? There is no fixed limit. IndexedDB is limited by the browser's storage quota for the origin, which is usually a large share of the free disk space. Use `navigator.storage.estimate()` to check it at runtime. ### What is OPFS used for? OPFS is used for fast, private file storage in the browser: large or binary files, and database engines (for example SQLite compiled to WebAssembly) that need a file system with fast synchronous access. ### Is OPFS faster than IndexedDB? For file-style reads and writes in a Web Worker with synchronous access handles, OPFS is typically faster than IndexedDB. For structured data with indexed lookups, IndexedDB is more convenient. Benchmark with your own data before you decide. ### Can browser storage be deleted? Yes. Users can clear site data at any time, browsers may evict best-effort storage under storage pressure, and Safari deletes storage of sites that have not been used for seven days. Request persistent storage with `navigator.storage.persist()` and sync important data to a server. --- --- url: /signals.md --- # JavaScript Signals Explained ## Introduction **JavaScript signals are reactive values: when a signal changes, everything that reads it (computed values, effects, UI) updates automatically, and nothing else does.** They are the reactivity primitive behind Solid, Angular, Preact, Vue's refs and Svelte's runes, and a [TC39 proposal](#the-tc39-signals-proposal) aims to make them part of the language. ```js import { signal, computed, effect } from '@preact/signals-core' const count = signal(0) const double = computed(() => count.value * 2) effect(() => { console.log(`count: ${count.value}, double: ${double.value}`) }) // logs "count: 0, double: 0" count.value = 1 // logs "count: 1, double: 2" ``` This article explains how JavaScript signals work under the hood, [builds a minimal signal from scratch](#build-a-minimal-signal-in-javascript), compares signals with observables, shows the signal APIs of popular frameworks and the [most common pitfalls](#common-pitfalls-with-signals), and shows how you can use signals for more than UI state, for example to [query a local database reactively](#signals-beyond-ui-state-a-reactive-database). ::: info What are JavaScript signals? JavaScript signals are reactive primitives that represent values over time and automatically notify everything that depends on them when they change, enabling fine-grained reactivity without manual subscriptions. ::: ## Understanding Signals in JavaScript Almost every signal implementation is built from three primitives: * **Signal** (also called *state*, *ref* or *atom*): holds a value that can be read and written. * **Computed** (also called *memo* or *derived*): a value derived from other signals. It is cached and only recalculated when one of its dependencies changes. * **Effect**: a function that runs side effects such as rendering, logging or network calls, and re-runs whenever a signal it read has changed. Together they form a dependency graph: signals are the sources, computed values sit in the middle, and effects are the leaves that touch the outside world. You never wire up this graph by hand. Reading a signal inside a computed value or an effect is enough to subscribe to it. Despite the name, JavaScript signals are unrelated to [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal), to process signals such as `SIGINT` in Node.js, and to the `js-signals` event library. See [where the name comes from](#early-beginnings-in-software-engineering). ### Signals and Reactive Programming [Reactive programming](https://en.wikipedia.org/wiki/Reactive_programming) is a declarative programming paradigm concerned with data streams and the propagation of change. In JavaScript, this involves: * **Reactive sources**: values or streams that can be observed. * **Dependents**: computations or components that react to changes of those sources. * **Automatic updates**: when a source changes, its dependents update without explicit commands to re-render or re-fetch. Signals are the "current value" flavour of reactive programming: a signal always has a value, and dependents are tracked automatically. ### Role of the Effect Function in Signals The `effect` function is the bridge between reactive data and the outside world: * **Automatic updates**: an effect re-runs whenever a signal it read during its last run changes. * **Dependency tracking**: it records which signals were read while it ran, so only relevant changes trigger a re-run. * **Resource management**: most implementations let an effect return or register a cleanup function that runs before the next execution and when the effect is disposed, which is the place to remove event listeners or close subscriptions. Effects are meant for side effects. To keep one value in sync with another, use a computed value instead ([see the pitfalls](#writing-to-signals-inside-effects)). ## How Signals Work - Technical Perspective Every signal library does two jobs: it records which computations read which signals, and when a signal is written, it re-runs exactly those computations, in an order that never exposes an inconsistent state. ### Signal Creation and Propagation At its core, a signal holds a value and a set of subscribers. Writing a new value marks the subscribers as stale and schedules them to re-run. For the example from the introduction, the dependency graph looks like this: ```mermaid graph LR count["count (signal)"] --> double["double (computed)"] count --> log["effect: console.log"] double --> log ``` When `count` changes, both `double` and the effect are stale. The effect has to run exactly once, and only after `double` has been recalculated. Getting this right is the hard part of a signal implementation, as the next sections show. ### Dependency Tracking When a signal is read inside a reactive context, such as an effect or a computed value, the runtime records it as a dependency of that context. This is usually implemented with a global "currently running computation" pointer: every signal read checks the pointer and adds the running computation to its subscribers. Dependencies are collected again on every run. If an effect reads `user.value` only while `isLoggedIn.value` is `true`, it depends on `user` only while the user is logged in. This is why signals need no dependency arrays, unlike React's `useEffect`. ### Build a Minimal Signal in JavaScript The quickest way to understand signals is to build one. The following implementation of `signal`, `computed` and `effect` uses the same `.value` API as Preact Signals, so the example from the introduction runs against it unchanged: ```js let currentEffect = null function signal(initialValue) { let value = initialValue const subscribers = new Set() return { get value() { if (currentEffect) subscribers.add(currentEffect) return value }, set value(newValue) { if (Object.is(newValue, value)) return value = newValue for (const subscriber of [...subscribers]) subscriber() }, } } function effect(fn) { const run = () => { const previous = currentEffect currentEffect = run try { fn() } finally { currentEffect = previous } } run() } function computed(fn) { const result = signal(undefined) effect(() => { result.value = fn() }) return { get value() { return result.value }, } } ``` Reading `.value` while an effect runs subscribes that effect, and writing `.value` re-runs every subscriber. Running the introduction example against it shows where this simple approach falls short: ```js const count = signal(0) const double = computed(() => count.value * 2) effect(() => { console.log(`count: ${count.value}, double: ${double.value}`) }) // logs "count: 0, double: 0" count.value = 1 // logs "count: 1, double: 2" // logs "count: 1, double: 2" a second time ``` The effect runs twice for a single write: once because `double` changed and once because `count` changed. This version also never drops old dependencies, cannot dispose an effect, and re-runs everything synchronously on every write. Production libraries solve exactly these problems: * **Glitch-free updates**: each computation runs at most once per change, after all of its dependencies are up to date ([see below](#efficient-state-management)). * **Dynamic dependencies**: subscriptions from the previous run are dropped, so a branch that is no longer taken stops triggering updates. * **Disposal**: an effect can be stopped, and frameworks stop a component's effects when it unmounts. * **Batching and scheduling**: several writes can be grouped so that effects run only once. ### Efficient State Management The double run above is known as the *diamond problem*: `count` reaches the effect over two paths. A naive push-based implementation runs the effect once per path, and if the paths are notified in the wrong order, the effect even sees the new `count` together with the old `double`. Such a temporarily inconsistent state is called a *glitch*. Modern libraries avoid both with a **push-pull** algorithm: 1. **Push**: a write only marks its dependents as *dirty* (or *possibly dirty*), all the way down the graph. Nothing is recalculated yet. 2. **Pull**: when an effect runs or a computed value is read, the library walks back up the graph and recalculates only the computed values whose sources actually changed. If a computed value produces the same result as before, propagation stops there. This makes computed values lazy and cached, and guarantees that every effect runs once per change and never observes an inconsistent state. Preact Signals implements this with version numbers and linked lists. [alien-signals](https://github.com/stackblitz/alien-signals) is a particularly fast push-pull implementation, and Vue 3.6 (in beta as of October 2026) rebuilds its reactivity core on the alien-signals algorithm. ### Batching and Untracked Reads Two more tools are part of almost every signal library. **Batching** groups several writes so that effects run once, with the final state: ```js import { batch, effect, signal } from '@preact/signals-core' const firstName = signal('Ada') const lastName = signal('Lovelace') effect(() => console.log(`${firstName.value} ${lastName.value}`)) // logs "Ada Lovelace" batch(() => { firstName.value = 'Grace' lastName.value = 'Hopper' }) // logs "Grace Hopper" once, never "Grace Lovelace" ``` Frameworks that schedule effects asynchronously, such as Angular, Vue and Svelte, batch synchronous writes automatically. **Untracked reads** read a signal without subscribing to it, for values an effect needs but should not react to: ```js import { effect, signal, untracked } from '@preact/signals-core' const query = signal('signals') const page = signal(1) effect(() => { console.log(`search "${query.value}" on page ${untracked(() => page.value)}`) }) // logs 'search "signals" on page 1' page.value = 2 // no log: the effect does not depend on page query.value = 'observables' // logs 'search "observables" on page 2' ``` The name varies by library: `peek()` and `untracked()` in Preact, `untracked()` in Angular, `untrack()` in Solid and Svelte, and `Signal.subtle.untrack()` in the TC39 proposal. ### Integration with the UI In signal-based frameworks, the renderer itself is an effect. Solid and Svelte 5 compile templates into small effects that update individual DOM nodes, so components run once and there is no virtual DOM to diff. Angular uses the signals read in a template to decide which components to refresh. Preact and Vue still render components with a virtual DOM, but signals limit re-rendering to the components that read a changed value, and Preact can bind a signal directly to a text node. In every case, signals remove most of the glue code that is otherwise needed to keep UI and state in sync. ## When to Use JavaScript Signals Signals pay off wherever state is read in many places and changes often. Consider using signals for: * **UI state** that several parts of the page read: form values, filters, the current selection, the theme. * **Derived data** that has to stay in sync: totals, filtered or sorted lists, validation results. * **Large, frequently updating views** such as dashboards, tables and editors, where re-rendering whole component trees is too slow. * **State shared across components**, without prop drilling or context providers. * **Framework-independent logic**: a signal works the same in a component, a store or a plain module, and is easy to test. Signals are less useful for one-off values that never change, or for modelling sequences of events over time (clicks, WebSocket messages, debounced input). Those are better expressed as [observables or event streams](#signals-vs-observables). ### Benefits of Using Signals in JavaScript * **Fine-grained updates**: only the computations and DOM nodes that depend on a changed value are updated. * **No manual subscriptions**: dependencies are tracked automatically, so there is nothing to forget to unsubscribe. * **Decoupled components**: state can live outside components and be shared without prop drilling or global stores. * **Readable data flow**: derived values are declared once with `computed` instead of being kept in sync by hand. ## Signals vs. Observables Signals and observables (for example [RxJS](https://rxjs.dev/)) are both reactive, but they model different things: | | Signals | Observables (RxJS) | |---|---|---| | Represents | a value that changes over time | a stream of events over time | | Current value | always available (`count.value`, `count()`) | not by default (only e.g. `BehaviorSubject`) | | Dependency tracking | automatic, by reading the signal | explicit, via `subscribe()` and operators | | Unsubscribing | handled by the effect's lifecycle | manual, or via operators like `takeUntil` | | Timing and async | synchronous and glitch-free by design | built for async: `debounceTime`, `switchMap`, retries | | Typical use | UI state, derived data, query results | user input streams, WebSockets, request orchestration | **Rule of thumb:** use signals for *state* that the UI reads, and observables for *events* that need time-based operators. Many apps use both. Angular, for example, ships `toSignal()` and `toObservable()` in `@angular/core/rxjs-interop` to convert between them. ## Signals in Popular Frameworks Every major framework now has a signal-like primitive, under different names: | Framework / library | Create | Derive | Effect | SignalDB adapter | |---|---|---|---|---| | [Solid](https://docs.solidjs.com/concepts/signals) | `createSignal(0)` | `createMemo(() => …)` | `createEffect(() => …)` | [`@signaldb/solid`](/reference/solid/) | | [Angular](https://angular.dev/guide/signals) | `signal(0)` | `computed(() => …)` | `effect(() => …)` | [`@signaldb/angular`](/reference/angular/) | | [Vue](https://vuejs.org/guide/essentials/reactivity-fundamentals.html) | `ref(0)` | `computed(() => …)` | `watchEffect(() => …)` | [`@signaldb/vue`](/reference/vue/) | | [Preact Signals](https://preactjs.com/guide/v10/signals/) | `signal(0)` | `computed(() => …)` | `effect(() => …)` | [`@signaldb/preact`](/reference/preact/) | | [Svelte 5 runes](https://svelte.dev/docs/svelte/what-are-runes) | `$state(0)` | `$derived(…)` | `$effect(() => …)` | [`@signaldb/svelte`](/reference/svelte/) | | [MobX](https://mobx.js.org/) | `observable(…)` | `computed(() => …)` | `autorun(() => …)` | [`@signaldb/mobx`](/reference/mobx/) | | [Qwik](https://qwik.dev/docs/components/state/) | `useSignal(0)` | `useComputed$(() => …)` | `useTask$(({ track }) => …)` | – | | [alien-signals](https://github.com/stackblitz/alien-signals) | `signal(0)` | `computed(() => …)` | `effect(() => …)` | [custom adapter](/reference/core/createreactivityadapter/) | | TC39 proposal | `new Signal.State(0)` | `new Signal.Computed(() => …)` | none built in ([see below](#the-tc39-signals-proposal)) | – | Two of these are changing. **Solid 2.0**, a release candidate as of October 2026, keeps `createSignal` and `createMemo` but splits `createEffect` into a tracked function that reads signals and an untracked function that performs the side effect. **Vue 3.6** (beta) rebuilds its reactivity core on the alien-signals algorithm while keeping the `ref` and `computed` API. **React** has no built-in signals: `useState` re-renders the whole component. You can add signals with a library such as `@preact/signals-react`. SignalDB's [React integration](/guides/react/) wraps any signal library's `effect` in a `useReactivity` hook. A full list of supported libraries is on the [Reactivity](/reactivity/#reactivity-libraries) page. ## Common Pitfalls with Signals Signals remove a lot of bookkeeping, but a few mistakes come up again and again. The examples use Preact Signals, but the same rules apply to every library. ### Reading a Signal Outside a Reactive Context Reading `.value` returns a plain value. Only reads inside an effect, a computed value or a component render are tracked: ```js const count = signal(0) const snapshot = count.value // a number, not a signal effect(() => console.log(snapshot)) // logs 0, and never again count.value = 1 ``` The same applies to destructuring and to passing values around: hand the signal itself (or a getter) to code that should stay reactive, and read it as late as possible. Destructuring props in Solid, or a `reactive()` object in Vue, loses reactivity for the same reason. ### Mutating Objects in Place A signal notifies its dependents when it is assigned a new value. Changing an object or array it holds does not count: ```js const todos = signal(['Write docs']) effect(() => console.log(todos.value.length)) // logs 1 todos.value.push('Ship it') // no log: still the same array todos.value = [...todos.value, 'Celebrate'] // logs 3 ``` Assign a new object or array instead, or use a library with deep reactivity, such as Vue's `ref()`, Svelte 5's `$state` or MobX observables, which track property access through proxies. ### Writing to Signals Inside Effects An effect that writes a signal it also reads triggers itself. Preact throws `Cycle detected`, other libraries loop or warn. Even without a cycle, an effect that copies one value into another signal causes an extra update, and the copy lags behind its source whenever effects are batched or scheduled. Derive the value instead: ```js // Avoid: an effect that copies state into another signal const fullNameCopy = signal('') effect(() => { fullNameCopy.value = `${firstName.value} ${lastName.value}` }) // Prefer: a computed value, always consistent and only calculated when read const fullName = computed(() => `${firstName.value} ${lastName.value}`) ``` ### Forgetting to Dispose Effects An effect stays subscribed to its signals until it is disposed. Frameworks dispose a component's effects when it unmounts, but effects you create yourself, in a store, a module or a test, run until you stop them: ```js const dispose = effect(() => console.log(count.value)) // later, when the effect is no longer needed dispose() ``` An effect that is never disposed keeps running and keeps its callback, and everything the callback references, in memory. ## The TC39 Signals Proposal The [TC39 Signals proposal](https://github.com/tc39/proposal-signals) aims to add a standard `Signal` primitive to JavaScript itself. It reached **Stage 1** in April 2024 and is still at Stage 1 as of October 2026: TC39 is exploring the problem space, and the API can still change significantly. To reach Stage 2, the committee would have to settle on a preferred design backed by draft specification text. The proposal was started by Rob Eisenberg and Daniel Ehrenberg, with design input from the maintainers of Angular, Ember, MobX, Preact, Qwik, RxJS, Solid, Svelte, Vue and others. Its authors compare it to Promises/A+, the community specification that preceded native promises in ES2015: first align the ecosystem on one model, then standardize it. The proposed API has two core classes: ```js const counter = new Signal.State(0) const isEven = new Signal.Computed(() => (counter.get() & 1) === 0) const parity = new Signal.Computed(() => (isEven.get() ? 'even' : 'odd')) counter.set(1) parity.get() // 'odd' ``` Key points: * **It is meant for frameworks, not primarily for app code.** The goal is a shared, interoperable signal graph that frameworks can build on, so that signals from one library can be used in another. * **There is no built-in `effect`.** Effect scheduling is tied to each framework's rendering cycle, so the proposal only provides a low-level `Signal.subtle.Watcher`. A minimal effect on top of it, adapted from the polyfill's README, re-runs callbacks in a microtask: ```js import { Signal } from 'signal-polyfill' let needsEnqueue = true const watcher = new Signal.subtle.Watcher(() => { if (needsEnqueue) { needsEnqueue = false queueMicrotask(processPending) } }) function processPending() { needsEnqueue = true for (const pending of watcher.getPending()) pending.get() watcher.watch() } export function effect(callback) { let cleanup const computed = new Signal.Computed(() => { if (typeof cleanup === 'function') cleanup() cleanup = callback() }) watcher.watch(computed) computed.get() return () => { watcher.unwatch(computed) if (typeof cleanup === 'function') cleanup() } } ``` * **Options and escape hatches are explicit.** Both classes accept an `equals` option that decides when a new value counts as a change. `Signal.subtle` holds the `Watcher`, `untrack()` and introspection helpers for devtools; the `subtle` namespace marks APIs meant for library authors. * **You can try it today** with the [`signal-polyfill`](https://github.com/proposal-signals/signal-polyfill) package (version 0.2 as of October 2026), which its README explicitly marks as not for production use. If the proposal advances, framework-specific signals would become thin wrappers around a native primitive, and libraries such as SignalDB could support all of them through a single integration. ## Signals Beyond UI State: a Reactive Database Signals work well for individual values. Application data, however, is usually a *collection of records* that you filter, sort, persist and sync with a server. Keeping that in hand-written signals quickly turns into a home-made database. [SignalDB](/) is a reactive local database built on this idea: queries run against local collections with a MongoDB-like API, and any query executed inside an effect becomes reactive through the signal library you already use. ```js import { signal, effect } from '@preact/signals-core' import { Collection, DefaultDataAdapter } from '@signaldb/core' import preactReactivityAdapter from '@signaldb/preact' import createIndexedDBAdapter from '@signaldb/indexeddb' const dataAdapter = new DefaultDataAdapter({ storage: createIndexedDBAdapter({ databaseName: 'my-app', version: 1, schema: { todos: ['completed'] }, }), }) const todos = new Collection('todos', dataAdapter, { reactivity: preactReactivityAdapter, }) const showCompleted = signal(false) effect(() => { const cursor = todos.find(showCompleted.value ? {} : { completed: false }) console.log(cursor.fetch()) // re-runs when matching todos or the filter change return () => cursor.cleanup() }) await todos.insert({ title: 'Write docs', completed: false }) // effect re-runs showCompleted.value = true // effect re-runs ``` What this gives you on top of plain signals: * **Works with your signal library**: adapters for Solid, Angular, Vue, Preact, Svelte, MobX and [many more](/reactivity/#reactivity-libraries). * **Persistence**: data is stored in [IndexedDB, OPFS, localStorage or the file system](/data-persistence/) and loaded on start. * **Sync with any backend**: the [sync layer](/sync/) pulls and pushes changes over REST, GraphQL or WebSockets. * **Optimistic UI**: writes are applied locally first, so the UI updates instantly ([learn more](/optimistic-ui/)). ::: tip Try SignalDB Install it with `npm install @signaldb/core` and follow the [Getting Started guide](/getting-started/), or jump straight to the guide for [React](/guides/react/), [Vue](/guides/vue/), [Angular](/guides/angular/), [Svelte](/guides/svelte/) or [Solid](/guides/solid-js/). ::: ## Origins of Signals in Programming The idea of a value that notifies its dependents is much older than today's frameworks. ### Early Beginnings in Software Engineering The word "signal" is older than reactive UIs, which is why a search for it turns up unrelated APIs. Operating systems use signals such as `SIGINT` to notify processes asynchronously, and Node.js exposes them through `process.on('SIGINT', …)`. The DOM's [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) tells code that an operation such as a `fetch()` was cancelled. And [js-signals](https://github.com/millermedeiros/js-signals), inspired by ActionScript's AS3-Signals, is an event messaging library. Today's JavaScript signals share the idea of notification, but model *values* rather than one-off events. ### Influence of Functional Reactive Programming (FRP) Functional Reactive Programming treats data as values that change over time and lets programs declare how other values depend on them. Signals in modern JavaScript are a pragmatic, imperative descendant of this idea: a signal is the current value of such a time-varying quantity. ### Adaptation to Web Development In the browser, observable values appeared early in UI libraries. [Knockout](https://knockoutjs.com/) shipped observables and computed values with automatic dependency tracking in 2010, and Meteor's Tracker and MobX followed similar models. ### The SolidJS Revolution and the Rise of Signals [SolidJS](https://docs.solidjs.com/concepts/intro-to-reactivity) made signals the centre of a UI framework: components run once, and only the DOM nodes that read a signal are updated when it changes. Its performance and simplicity triggered a wave of interest in signals across the ecosystem, documented in Ryan Carniato's article [*The Evolution of Signals in JavaScript*](https://dev.to/thisdotmedia/the-evolution-of-signals-in-javascript-ryan-carniato-5ejn). ### Influence on Other Frameworks Since then, Preact (Preact Signals), Angular (Angular Signals), Svelte (runes in Svelte 5) and Qwik have adopted signals as their reactivity model, and Vue's refs follow the same principle. The convergence of these frameworks led directly to the TC39 proposal. ## Frequently Asked Questions ### Are signals part of JavaScript? Not yet. The [TC39 Signals proposal](#the-tc39-signals-proposal) is at Stage 1, and no browser or JavaScript runtime ships a native `Signal`. Today, signals come from frameworks and libraries such as Solid, Angular, Preact, Vue or Svelte, and you can try the proposed API with `signal-polyfill`. ### Can I use signals without a framework? Yes. `@preact/signals-core` and `alien-signals` are small standalone libraries that work in any JavaScript environment, including Node.js and web workers. The [minimal implementation above](#build-a-minimal-signal-in-javascript) shows that the core idea fits in a few dozen lines. ### Does React have signals? No. React's `useState` triggers a re-render of the component. Libraries such as `@preact/signals-react` add signals to React, and SignalDB integrates with React through its [`useReactivity` hook](/guides/react/). ### What is the difference between signals and observables? A signal always holds a current value and tracks its dependents automatically. An observable emits a stream of events that you subscribe to explicitly. See [Signals vs. Observables](#signals-vs-observables). ### What is the difference between signals and state? "State" is any data that changes over time. A signal is a specific way to hold state: the container knows who reads it and notifies exactly those readers when it changes. ### What is alien-signals? [alien-signals](https://github.com/stackblitz/alien-signals) is a small, very fast signal library built on the push-pull algorithm. Vue 3.6 ports its algorithm into Vue's reactivity core, and the library itself can be used on its own with a `signal`, `computed` and `effect` API. ### Is AbortSignal a JavaScript signal? No. [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) is a DOM API for cancelling asynchronous operations such as `fetch()`. It notifies its listeners once, when the operation is aborted, and holds no reactive value. It only shares the name with the signals described in this article. ### Are signals faster than a virtual DOM? Signals let a framework skip re-rendering and diffing: an update touches only the computations and DOM nodes that read the changed value, while a virtual DOM re-renders a component subtree and compares it with the previous one. The difference matters most for large or frequently updating views. ## Conclusion Signals give JavaScript applications fine-grained, automatic reactivity: hold a value, derive from it, and let effects react to changes. Under the hood, a dependency graph and a push-pull algorithm make sure every computation runs once per change and never sees an inconsistent state. Nearly every modern framework now uses signals, and the TC39 proposal may make them a language feature. When your reactive state grows from single values into collections of records that need queries, persistence and sync, [SignalDB](/getting-started/) brings the same signal-based model to your data layer. --- --- url: /live-updates.md --- # Live Updates in Modern Apps ## Introduction In the realm of modern web applications, the concept of 'live updates' has transformed how users interact with technology. Live updates refer to the dynamic process where content or data on a webpage is updated in real-time without requiring the user to manually refresh the page. This capability is crucial for a wide range of applications, from social media platforms showing new content instantly to financial apps updating stock prices in real time. But live updates aren't just about pulling fresh data from the server; they're also about how changes in the application's state are managed and reflected on the frontend—this is known as frontend reactivity. Frontend reactivity, the focus of our discussion, involves updates that happen within the browser, enabling the application to react instantly to user interactions or data changes. This seamless integration between user actions and application responses enhances the user experience by making apps feel more responsive and interactive. In this blog post, we will explore what live updates entail within the web context, trace their evolution, delve into their technical underpinnings, and showcase how tools like SignalDB can power these interactions by providing sophisticated data handling capabilities. By understanding these mechanisms, developers can create more engaging and dynamic web experiences that meet the expectations of today's users. ## Understanding Live Updates Live updates in web applications refer to the process of changing or refreshing content displayed to the user in real-time as new data becomes available, without any action required from the user, like refreshing the page. This capability is integral to enhancing user interaction and engagement, making applications appear more dynamic and responsive. There are two primary types of live updates: server-sent updates and frontend reactive updates. ### Server-Sent Updates vs. Frontend Reactive Updates 1. **Server-Sent Updates**: * These involve data pushed from the server to the client, typically using technologies like WebSockets or Server-Sent Events (SSE). This approach is used in scenarios where the server needs to broadcast data to multiple clients efficiently, such as in chat applications or live sports scores updates. 2. **Frontend Reactive Updates**: * This type involves updates within the client's browser that reflect changes in the application's state due to user interactions or internal processes. These are not necessarily triggered by the server but are about how the application handles state changes locally to provide a seamless user experience. * Technologies and architectural approaches like React's virtual DOM or Angular's change detection mechanisms are examples of enabling technologies that manage how data changes are reflected in the UI without sending requests to the server. ### The User Experience Benefits Live updates contribute significantly to the user experience by: * **Reducing latency**: Immediate feedback from interactions improves the perceived responsiveness of the application. * **Enhancing engagement**: Continuous updates keep the user informed and engaged, especially important in fast-paced environments like gaming or stock trading platforms. * **Improving performance**: By only updating parts of the UI that need changes, resources are used more efficiently, leading to better performance especially in complex applications. Understanding these types of live updates and their impact on user experience allows developers to better design and implement interactive and responsive web applications. As we delve deeper into how these systems work, we'll explore the mechanisms that enable these live updates and how they can be optimized for modern web development. ## Origins of Frontend Reactivity The evolution of frontend reactivity in web applications is a fascinating journey that highlights the shift from static to dynamic user interfaces. Understanding this history provides context for the current technologies and methods used for implementing live updates. ### The Rise of AJAX The concept of frontend reactivity began to take shape with the advent of AJAX (Asynchronous JavaScript and XML) in the early 2000s. AJAX marked a significant departure from the traditional full-page reload model, allowing web pages to retrieve data from the server asynchronously and update parts of the web page without reloading the whole page. This was the first step towards more interactive and responsive web experiences. ### Advancements with Comet and Long Polling Following AJAX, technologies such as Comet and long polling were developed to improve the responsiveness of web applications further. These technologies aimed to keep a connection open between the server and the client for as long as possible, allowing the server to push updates to the client as soon as new data was available. Although not as efficient as modern solutions, they paved the way for more sophisticated communication protocols. ### Breakthrough with WebSockets The introduction of WebSockets was a major breakthrough in real-time web communication. Unlike previous technologies, WebSockets provide a full-duplex communication channel over a single long-lived connection, allowing messages to be passed back and forth between the client and server with minimal overhead. This technology is fundamental to the modern implementation of live updates, enabling more efficient and faster data transfer. ### The Role of Modern JavaScript Frameworks Modern JavaScript frameworks and libraries like React, Angular, and Vue have integrated reactivity as a core part of their architectures. These frameworks use a virtual DOM to efficiently update the browser's display, reflecting changes in the application's state without requiring a full page reload. They detect changes to the data and automatically re-render only the components affected by those changes, making applications feel quicker and more fluid. ### Summary From AJAX to modern frameworks, the evolution of frontend reactivity has been driven by the need for more interactive and responsive web applications. Each advancement has brought us closer to achieving seamless live updates, culminating in the comprehensive solutions we have today, which combine efficient data transfer methods like WebSockets with sophisticated state management techniques provided by modern frameworks. Understanding this historical context enriches our appreciation of current frontend technologies and sets the stage for discussing how tools like SignalDB integrate within this ecosystem to provide live updates. ## Technical Mechanisms for Live Updates To effectively implement live updates in modern web applications, developers utilize a variety of technical mechanisms that enable reactive behaviors and instantaneous data communication between the client and server. ### State Management and Reactivity 1. **State Management**: At the core of frontend reactivity is state management, which tracks changes in the state of an application and updates the UI accordingly. Tools like Redux, MobX, or Vue's reactivity system help manage state changes across complex applications, ensuring that changes in data are accurately reflected in the UI without unnecessary updates. 2. **Virtual DOM**: Frameworks like React use a virtual DOM to optimize DOM manipulation. The virtual DOM is a lightweight copy of the actual DOM. It allows frameworks to perform diffs between the previous and current states of the UI and batch updates efficiently, minimizing direct interactions with the actual DOM and improving performance. ### Real-Time Data Fetching 1. **WebSockets**: For applications that require a continuous flow of data without the overhead of multiple HTTP requests, WebSockets provide a two-way communication channel between the client and server. This protocol is essential for chat applications, live sports updates, and financial trading platforms where data needs to flow seamlessly in real time. 2. **Server-Sent Events (SSE)**: Unlike WebSockets, SSE is designed for one-way communication from the server to the client, making it ideal for updates like live news feeds or social media streams where the server periodically pushes updates to the client. ### Reactive Programming Reactive programming is a paradigm that facilitates working with asynchronous data streams. Libraries like RxJS provide powerful tools for creating and managing data streams that react to changes, enabling developers to write declarative code that responds to an ever-changing data flow. ## Benefits of Using SignalDB for Live Updates SignalDB offers several distinct advantages for developers aiming to implement live updates in web applications, enhancing both the development experience and the end-user interaction. Here’s how SignalDB stands out as a tool for modern apps: ### Reduced Latency * **Immediate Data Access**: SignalDB's in-memory nature ensures that data access and manipulation are almost instantaneous. This reduced latency is crucial for applications where real-time responsiveness is critical, such as in gaming or real-time analytics. * **Optimized Response Times**: By minimizing the delay between data changes and their reflection in the user interface, SignalDB helps maintain a fluid user experience, essential for keeping users engaged and satisfied. ### Enhanced User Experience * **Seamless State Synchronization**: SignalDB synchronizes the state across all clients seamlessly. Whether it's a chat message or a live stock update, users see changes immediately across all devices without needing to refresh or pull new data manually. * **Consistent and Reliable Updates**: With its built-in mechanisms for handling data consistency, SignalDB ensures that all users have the same view of data at any given time, which is paramount in collaborative environments. ### Developer Efficiency * **Easy Integration with Existing Frameworks**: SignalDB provides adapters for popular frameworks such as [React](/guides/react/), Vue, and Angular, making it easy to integrate into existing projects without extensive modifications. * **Simplified Data Management**: Developers can manage data with simple, MongoDB-like queries, which reduces the complexity typically associated with data handling in real-time scenarios. This simplification speeds up development and reduces the potential for errors. ### Scalability * **Handle Large Volumes of Data**: SignalDB is designed to efficiently manage large volumes of data updates, which is beneficial for applications that scale to a large number of users or require handling significant amounts of data in real-time. * **Adaptability to Traffic Spikes**: The ability of SignalDB to handle sudden increases in data flow or user numbers makes it ideal for applications that experience variable load, ensuring that performance remains consistent. ### Cost-Effectiveness * **Reduce Server Load**: By handling updates efficiently on the client side, SignalDB can reduce the load on servers, potentially lowering server costs and increasing the overall efficiency of the application infrastructure. In conclusion, using SignalDB for live updates offers numerous benefits that can significantly enhance the performance and user experience of web applications. Its capabilities for rapid, consistent, and scalable updates make it an excellent choice for developers looking to build or enhance modern, real-time applications. ## Conclusion Throughout this exploration of live updates in modern web applications, we've delved into the vital role that real-time interactions play in enhancing user experiences. From the early days of AJAX to the sophisticated, reactive frameworks of today, the evolution of live updates has continually pushed the boundaries of what is possible in web development. SignalDB emerges as a particularly powerful tool in this landscape, offering developers a seamless way to implement live updates with minimal overhead and maximum efficiency. By leveraging SignalDB's capabilities, developers can ensure that their applications are not only responsive but also resilient and scalable. This makes SignalDB an excellent choice for any project aiming to deliver high-quality, real-time user experiences. As developers, embracing tools like SignalDB can significantly simplify the complexities associated with real-time data management. The benefits of reduced latency, enhanced user experience, developer efficiency, scalability, and cost-effectiveness are compelling reasons to integrate SignalDB into your development toolkit. In conclusion, the integration of live updates using SignalDB represents a smart investment in the future of web application development. By focusing on creating interactive, engaging, and dynamic experiences, developers can meet and exceed the modern user's expectations for real-time responsiveness and interactivity. Explore SignalDB for your next project and unlock the full potential of live updates to transform how users interact with your applications. --- --- url: /optimistic-ui.md --- # Optimistic UI: What It Is and How to Implement It ## Introduction to Optimistic UI **Optimistic UI is a pattern where the interface shows the result of a user action immediately, before the server has confirmed it, and only corrects itself if the request fails.** Instead of showing a spinner while waiting for the server, the app assumes success. Most requests do succeed. A familiar example is the "like" button in social apps: the heart turns red the moment you tap it. The request to the server happens in the background. If it fails, the heart quietly turns grey again and an error is shown. Optimistic updates make apps feel instant, because the perceived latency of an action drops from a network round trip (often hundreds of milliseconds) to a single render. ::: info What is optimistic UI? Optimistic UI is a frontend pattern in which the interface applies the result of a user action immediately (an *optimistic update*), before the server confirms it, and rolls the change back if the request fails. It replaces loading spinners for everyday actions and makes apps feel instant. ::: ## Optimistic vs. Pessimistic UI The opposite approach, waiting for the server before showing anything, is called *pessimistic UI*. Most apps use both, depending on the action: | | Optimistic UI | Pessimistic UI | |---|---|---| | UI updates | immediately, before the server answers | after the server has confirmed | | Perceived latency | one render | at least one network round trip | | While waiting | nothing, or a subtle pending marker | spinner or disabled button | | On failure | roll back and explain what happened | show an error, there is nothing to undo | | Implementation | track pending changes, roll back, reconcile | simple | | Best for | frequent actions that almost always succeed | payments, irreversible or server-dependent actions | ## Optimistic UI Examples Optimistic UI is everywhere in modern apps. What makes each example work is a clear answer to the question "what happens if the request fails?": | Action | Optimistic feedback | If the request fails | |---|---|---| | Liking a post | the icon fills and the counter goes up | revert both and show a short error | | Sending a chat message | the message appears with a "sending" clock, then a check mark | mark it as failed with a retry button, keep the text | | Adding an item to a list | the item appears at once, slightly faded | remove it and explain why, keep the input | | Reordering with drag and drop | the card stays where it was dropped | animate it back to its old position | | Toggling a setting | the switch flips immediately | flip it back and show an error | | Editing text inline | the new text is shown with a "saving…" hint | keep the edited text in the field and show an error | ## How Optimistic Updates Work Every optimistic update follows the same four steps: 1. **Apply locally**: update the UI state as if the action had succeeded, and remember what it looked like before. 2. **Send the request**: send the change to the server in the background. 3. **Reconcile**: when the server responds, replace the optimistic data with the server's version, for example to get the real ID or a server-side timestamp. 4. **Roll back on failure**: if the request fails, restore the previous state and tell the user. ```mermaid sequenceDiagram participant U as User participant UI as UI / local state participant S as Server U->>UI: Click "Add todo" UI->>UI: Show new todo immediately UI->>S: POST /todos (in background) alt Success S-->>UI: 201 Created (server data) UI->>UI: Replace optimistic item with server data else Failure S-->>UI: Error UI->>UI: Roll back and show error end ``` The hard parts are steps 3 and 4: keeping track of which changes are still pending, applying server responses that arrive out of order, and rolling back correctly when several optimistic changes touch the same data. ### Rolling Back: Snapshots vs. Optimistic Layers The most common way to roll back is a snapshot: remember the state before the update and restore it if the request fails. ```js async function toggle(id) { const snapshot = todos todos = todos.map(todo => (todo.id === id ? { ...todo, done: !todo.done } : todo)) render() try { await api.toggleTodo(id) } catch { todos = snapshot // also reverts every change made after the snapshot render() } } ``` This works as long as only one update is in flight. Toggle two todos quickly, and let the first request fail while the second succeeds: restoring the first snapshot also reverts the second toggle. The UI now shows the second todo as open, although the server has saved it as done. The robust alternative is to keep the confirmed server state and the pending changes apart, and to derive what the user sees from both. Each optimistic change is a *layer* on top of the confirmed state: ```js let confirmed = [] // the last state confirmed by the server let pending = [] // optimistic changes that are still in flight const visibleTodos = () => pending.reduce((todos, change) => change(todos), confirmed) async function toggle(id) { const change = todos => todos.map(todo => ( todo.id === id ? { ...todo, done: !todo.done } : todo )) pending = [...pending, change] render() try { await api.toggleTodo(id) confirmed = change(confirmed) } catch (error) { showError(error.message) } finally { pending = pending.filter(item => item !== change) render() } } ``` A failed change now only removes its own layer, and changes that are still pending stay visible. When the server sends new data, `confirmed` is replaced and the pending changes are applied on top of it again. This is how React's `useOptimistic`, Apollo Client and Convex keep optimistic state, and it is what a local database with a sync queue does for every write ([see below](#the-connection-between-local-databases-and-optimistic-ui)). ## When to Use Optimistic UI Optimistic UI works best when: * the action **almost always succeeds** (likes, toggles, reordering, adding items to a list, editing text); * a failure is **cheap to undo** and easy to explain to the user; * the user benefits from **continuing immediately**, for example when adding several items in a row. Avoid it, or show explicit pending states instead, when: * the outcome **depends on the server** (payments, bookings, stock availability, permission checks); * the action is **irreversible** or has side effects outside the app (sending an email, publishing); * a rollback would **destroy user input** that is hard to recreate. ## Common Pitfalls of Optimistic Updates Most bugs in optimistic interfaces come from a handful of situations: * **Out-of-order responses**: a refetch that started before your update can arrive after it and overwrite the optimistic value with stale data. Cancel or ignore reads that are in flight while a mutation is pending (TanStack Query's `cancelQueries` in `onMutate` does exactly this), or compare versions. * **Temporary IDs**: an item created optimistically needs an ID before the server has assigned one. If the ID changes on confirmation, a list keyed by ID remounts the element, focus and animations are lost, and an edit or delete issued in the meantime refers to an ID the server does not know. Generate IDs on the client, for example with `crypto.randomUUID()`, and let the server accept them. * **Retries and duplicates**: retrying a request whose response was lost can create the same item twice. Make writes idempotent with client-generated IDs or an idempotency key that the server deduplicates. * **Rollbacks that destroy input**: reverting a long comment or form because of a validation error loses the user's work. Keep the input, mark the item as failed, and offer a retry. * **Leaving before the request finishes**: pending changes that only exist in memory are lost when the tab is closed or the device goes offline, although the user already saw them as saved. Persist pending changes, for example in a local database with a sync queue, or warn before unloading the page while requests are pending. * **Silent failures**: an update that quietly disappears is worse than a spinner. Always tell the user when a change has been rolled back. ## Optimistic Updates in React: useOptimistic and React Query In React, there are two common ways to implement optimistic updates for a single mutation. ### React's useOptimistic Hook **React's `useOptimistic` hook** (React 19) shows a temporary state while an async action is running: ```jsx import { useOptimistic } from 'react' function TodoList({ todos, addTodo }) { const [optimisticTodos, addOptimisticTodo] = useOptimistic( todos, (state, newTodo) => [...state, { ...newTodo, pending: true }], ) async function formAction(formData) { const todo = { id: crypto.randomUUID(), title: formData.get('title') } addOptimisticTodo(todo) await addTodo(todo) // when this settles, optimisticTodos falls back to todos } return (
{optimisticTodos.map(todo => (

{todo.title}

))}
) } ``` The optimistic state only exists while the Action runs, so the setter has to be called inside an Action or `startTransition` (a form `action` already is one). When `addTodo` settles, successfully or not, `optimisticTodos` falls back to `todos`. The rollback is automatic, but showing an error message is up to you. ### TanStack Query (React Query) **TanStack Query (React Query)** offers two approaches. The simpler one renders the pending mutation's `variables` next to the list, without touching the cache: ```jsx const { isPending, isError, variables, mutate } = useMutation({ mutationFn: addTodo, onSettled: (data, error, variables, onMutateResult, context) => context.client.invalidateQueries({ queryKey: ['todos'] }), }) // in the list {isPending &&
  • {variables.title}
  • } {isError && (
  • {variables.title}
  • )} ``` The other writes the optimistic value into the query cache, so every component that reads the query updates. It uses the `onMutate`, `onError` and `onSettled` callbacks of a mutation: write the optimistic value into the query cache in `onMutate`, restore the snapshot in `onError`, and refetch in `onSettled`: ```jsx useMutation({ mutationFn: addTodo, onMutate: async (newTodo, context) => { await context.client.cancelQueries({ queryKey: ['todos'] }) const previousTodos = context.client.getQueryData(['todos']) context.client.setQueryData(['todos'], old => [...old, newTodo]) return { previousTodos } }, onError: (error, newTodo, onMutateResult, context) => { context.client.setQueryData(['todos'], onMutateResult.previousTodos) }, onSettled: (data, error, variables, onMutateResult, context) => context.client.invalidateQueries({ queryKey: ['todos'] }), }) ``` This is the snapshot approach from above. The refetch in `onSettled` is what keeps it correct when several mutations overlap: a restored snapshot can briefly undo a newer optimistic change, and the refetch replaces it with the server's state. Both approaches work well for individual actions, but they have the same limits: * Optimistic state lives **per mutation or per component**, and you write the rollback logic yourself. * Pending changes are **lost on reload**, and nothing works **offline**. * Every view that shows the same data has to be updated separately. ## Optimistic Updates in Other Libraries Most data-fetching libraries have a built-in way to apply optimistic updates: | Library | Optimistic update | Rollback | |---|---|---| | [SWR](https://swr.vercel.app/docs/mutation#optimistic-updates) | `mutate(key, updateFn, { optimisticData })` | automatic, controlled by `rollbackOnError` (default `true`) | | [Apollo Client](https://www.apollographql.com/docs/react/performance/optimistic-ui) | `optimisticResponse` option of a mutation | the optimistic layer is discarded on error | | [RTK Query](https://redux-toolkit.js.org/rtk-query/usage/manual-cache-updates#optimistic-updates) | `api.util.updateQueryData()` in `onQueryStarted` | `patchResult.undo()` when `queryFulfilled` rejects | | [Convex](https://docs.convex.dev/client/react/optimistic-updates) | `useMutation(…).withOptimisticUpdate(…)` | rolled back automatically when the mutation completes | | [React](https://react.dev/reference/react/useOptimistic) | `useOptimistic` | reverts when the Action ends | | [TanStack Query](https://tanstack.com/query/latest/docs/framework/react/guides/optimistic-updates) | `setQueryData` in `onMutate`, or the mutation's `variables` | restore the snapshot in `onError` | Outside React, TanStack Query's adapters for Vue, Svelte, Solid and Angular support the same `onMutate` pattern. Native apps follow the same four steps, whatever the framework. ## Understanding Local Databases A local database stores application data on the user's device, for example in the browser's IndexedDB or OPFS, or in SQLite on mobile, and answers queries without a network round trip. Many local databases can also **replicate** data from a server: they keep a local copy in sync with the backend in both directions. This changes how optimistic UI works. ## The Connection Between Local Databases and Optimistic UI With a local database, the UI does not render server responses. It renders the result of **local queries**. Every write goes to the local database first, and the database syncs with the server in the background. That makes every write optimistic by default: * **Apply locally**: writing to the local database *is* the optimistic update. Every view that queries the affected data updates, not just the component that triggered the action. * **Send the request**: the sync layer pushes the change and keeps it queued (and persisted) until the server accepts it, even across reloads and offline periods. * **Reconcile and roll back**: after a push, the next pull brings the server's version of the data into the local database. If the server rejected a change, the server state replaces the local change, which acts as a rollback. Because pending changes are kept in a log and replayed on top of every new server state, this is the [optimistic layer approach](#rolling-back-snapshots-vs-optimistic-layers): a rejected change disappears without touching any other pending change. This is the core idea of [offline-first](/offline-first/) and local-first apps: the UI never waits for the network. ## Optimistic UI with SignalDB [SignalDB](/getting-started/) is a reactive local database that implements this pattern. Queries run inside your framework's effects are reactive, so a local write updates the UI immediately: ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import { SyncManager } from '@signaldb/sync' import createIndexedDBAdapter from '@signaldb/indexeddb' import solidReactivityAdapter from '@signaldb/solid' const dataAdapter = new DefaultDataAdapter({ storage: createIndexedDBAdapter({ databaseName: 'my-app', version: 1, schema: { 'todos': [], // stores the SyncManager keeps its change queue in 'app-changes': ['collectionName'], 'app-snapshots': ['collectionName'], 'app-sync-operations': ['collectionName', 'status'], }, }), }) const todos = new Collection('todos', dataAdapter, { reactivity: solidReactivityAdapter, }) const syncManager = new SyncManager({ id: 'app', dataAdapter, pull: async ({ apiPath }) => ({ items: await fetch(apiPath).then(res => res.json()) }), push: async ({ apiPath }, { changes }) => { const response = await fetch(apiPath, { method: 'POST', body: JSON.stringify(changes) }) if (response.status >= 400 && response.status < 500) { // validation error: don't retry; the next pull restores the server state showError(await response.text()) return } if (!response.ok) throw new Error('Push failed') // network/server error: retried on next sync }, }) syncManager.addCollection(todos, { name: 'todos', apiPath: '/api/todos' }) // In your UI: the new todo appears instantly, before the server has answered await todos.insert({ title: 'Write docs', completed: false }) ``` * **Instant updates everywhere**: every reactive query that matches the new todo re-runs, in every component. * **Retries and offline**: if the push fails because of a network or server error, the change stays queued and is pushed again on the next sync, also after a reload. * **Rollback for rejected changes**: validation errors are handled in `push`; the following pull replaces the local data with the server's version. * **Conflicts**: local changes are replayed on top of the latest server data, and the most recent change wins (see [Sync Flow & Conflict Resolution](/sync/#sync-flow-conflict-resolution)). SignalDB works with the signals of your framework. See the guides for [React](/guides/react/), [Vue](/guides/vue/), [Angular](/guides/angular/), [Svelte](/guides/svelte/) and [Solid](/guides/solid-js/), or the examples for [Supabase](/supabase/) and [Firebase](/firebase/). ## Improving User Experience with Optimistic UI A few UX details make optimistic interfaces trustworthy: * **Mark pending items subtly**, for example with reduced opacity or a small sync icon, so users know a change has not reached the server yet. * **Explain rollbacks**: when a change is reverted, say why ("Couldn't save: title is required") and, if possible, keep the user's input so it can be fixed. * **Show global sync state**: a small "Saving…/All changes saved" indicator is enough. With SignalDB, `syncManager.isSyncing()` can drive it directly. It is reactive when you pass a reactivity adapter to the `SyncManager`. * **Don't fake irreversible actions**: for payments or sends, show a real pending state instead. ## Real-time UI Updates with Local Databases Optimistic UI covers *your own* changes. Changes from other users or devices arrive through sync: with live updates (WebSockets or server-sent events), the server notifies the client, the client pulls the new data into the local database, and every reactive query updates. Local writes and remote changes go through the same path, so the UI code doesn't care where a change came from. See [Real-Time Web Apps](/real-time/) and [Live Updates](/live-updates/) for the underlying techniques. ## Frequently Asked Questions ### What is optimistic UI? A UI pattern that shows the result of an action immediately, assuming it will succeed, and rolls it back if the server reports an error. ### What is the difference between optimistic and pessimistic UI? A pessimistic UI waits for the server's confirmation before showing the result, usually with a spinner. An optimistic UI shows the result first and confirms or corrects it afterwards. See the [comparison table](#optimistic-vs-pessimistic-ui). ### How do you roll back an optimistic update? Keep the previous state (or the list of pending changes) until the server confirms the change. If the request fails, restore that state. With a local database and sync, the next pull from the server restores the authoritative state automatically. ### What is the difference between optimistic UI and optimistic locking? Optimistic locking is a concurrency control technique on the server: a write only succeeds if the record has not changed since it was read, otherwise it is rejected. Optimistic UI is a frontend pattern. Both assume that conflicts are rare and deal with them when they happen, and they work well together: the server rejects a stale write, and the client rolls back its optimistic update. ### Is optimistic UI the same as offline-first? No, but they are closely related. Optimistic UI is about not waiting for the server for a single action. [Offline-first](/offline-first/) applies the same idea to the whole app: all reads and writes are local, and sync runs in the background. ## Conclusion Optimistic UI makes apps feel instant by showing the result of an action before the server confirms it. For single actions, React's `useOptimistic` or React Query's mutation callbacks are enough. When updates overlap, keep pending changes as layers on top of the confirmed state instead of restoring snapshots. When many views share the same data, or the app should keep working offline, a reactive local database such as [SignalDB](/getting-started/) makes every write optimistic by default and handles retries, persistence and reconciliation for you. --- --- url: /real-time.md --- # Real-Time Web Apps ## Introduction In today's fast-paced digital landscape, real-time web applications are not just a luxury—they are a necessity. From live notifications to instant messaging and dynamic dashboards, the ability to process and display data in real time is a fundamental requirement for a wide array of modern applications. This capability dramatically enhances user experience, making interactions seamless and intuitive. But what exactly does "real-time" mean in the context of web development? How have technological advancements shaped the way data is delivered and handled dynamically across the web? And more importantly, how can developers leverage tools like SignalDB to manage real-time data effectively? In this post, we will explore the concept of real-time web applications, trace their origins, delve into the technical mechanisms that power them, and illustrate how SignalDB can be integrated to enhance real-time data handling. By the end of this discussion, you’ll have a clearer understanding of how real-time systems work and the pivotal role that SignalDB plays in building responsive, data-driven web applications. ## Understanding Real-Time in Web Context The term "real-time" in web development refers to the capability of a system to process and respond to user inputs or external events as they occur, without perceptible delay. In practice, this means that any action taken by one user is almost immediately visible to other users, which is essential for applications like online gaming, financial trading platforms, and collaborative tools. ### What Does Real-Time Mean for Users and Developers? For users, real-time functionality translates into instantaneous feedback and interaction. This could range from seeing live comments on a social media post to receiving up-to-the-minute analytics on user behavior. For developers, implementing real-time features means ensuring that the architecture can handle rapid data updates and synchronization across all users and devices. ### Types of Real-Time Web Applications Real-time technology is crucial across various application domains: * **Chat apps** like WhatsApp or Telegram, where messages need to appear the moment they are sent. * **Collaborative applications** such as Google Docs, where multiple users edit documents simultaneously. * **Gaming**, where player actions and game states update in real time. * **Live tracking apps**, useful in logistics to track vehicles or shipments as they move. * **Streaming services**, where video or music is delivered in real time as it is broadcast. These applications rely on the real-time web to deliver a seamless and dynamic user experience, where delays are imperceptible, ensuring engagement and satisfaction. ### Real-Time Data: A Closer Look Handling real-time data effectively requires understanding the flow of data within web applications. This data must be managed in a way that supports immediate retrieval and updates, which is a challenge given the stateless nature of HTTP, the foundation of web communication. Developers often leverage technologies such as WebSockets and Server-Sent Events (SSE) to maintain open connections between the client and server, allowing for the continuous push and pull of data without the need to refresh the web page. In summary, real-time web technologies are designed to create interactive and responsive web experiences, where the data on a webpage is synchronized among users and sessions seamlessly and instantaneously. As we delve deeper into the technical aspects of real-time web apps, we will explore how these technologies achieve such a dynamic interaction model. ## Origins of Real-Time Web Technologies The evolution of real-time web technologies has been a game-changer for developers and end-users alike, transforming static pages into interactive, dynamic experiences. Let's take a look at the key milestones that have shaped the development of real-time capabilities on the web. ### Early Beginnings: The Dynamic Duo of AJAX and Comet The journey toward real-time web applications began with **AJAX (Asynchronous JavaScript and XML)**, which emerged in the early 2000s. AJAX was revolutionary because it allowed web pages to retrieve small amounts of data from the server without having to reload the entire page. This technology paved the way for more dynamic interactions within web pages, laying the foundational concept of real-time data fetching. Following AJAX, **Comet** techniques were developed to allow web servers to push data to the client without the client needing to request it periodically. Comet could be considered a precursor to modern real-time communication methods as it tried to keep a single connection open for continual data push. ### The WebSocket Revolution The introduction of **WebSockets** marked a significant advancement in real-time web technology. Unlike HTTP, which is stateless, WebSockets provide a full-duplex communication channel that allows for continuous data transfer without the overhead of repeated HTTP requests. This made WebSockets ideal for applications that require a persistent, low-latency connection such as online games, chat applications, and live sports updates. ### Server-Sent Events (SSE) **Server-Sent Events (SSE)** is another technology that enables servers to push updates to the client. It is particularly well-suited for unidirectional communication, like pushing updates or notifications from the server to the client. SSE operates over standard HTTP and is easier to implement and debug compared to WebSockets. ### The Role of HTML5 The HTML5 standard has been instrumental in enhancing real-time communication capabilities on the web. It introduced many built-in APIs that support real-time interactions, such as the WebSocket API and the EventSource API for SSE. These technologies have been embraced because they simplify the development of complex real-time applications. ### Modern Frameworks and Libraries Today, many modern frameworks and libraries facilitate the implementation of real-time features. These tools often abstract the underlying complexities of WebSockets and SSE, offering developers a more accessible interface to build real-time applications. Frameworks like **Socket.IO** and **SignalR** manage real-time communication channels, ensuring that data syncs instantly across all users and devices. In summary, the origins of real-time web technologies showcase a gradual evolution from simple asynchronous data fetching to sophisticated, persistent communication channels. These advancements have not only improved the efficiency and responsiveness of web applications but have also greatly enhanced user engagement and satisfaction. ## How Real-Time Web Apps Work (Technical Perspective) Understanding the technical workings behind real-time web applications is essential for developers looking to implement seamless and dynamic user experiences. This section delves into the architectures and technologies that make real-time data processing possible. ### Client-Server Architecture in Real-Time Apps The foundation of any real-time web application is the **client-server architecture**. In this model, the client (browser or mobile app) communicates with a server that processes data and returns responses. For real-time interactions, this architecture is optimized to handle frequent, rapid exchanges of information, often maintaining persistent connections to facilitate instant data transfer. ### Persistent Connections: WebSockets and SSE 1. **WebSockets**: * WebSockets create a continuous connection between the client and server, allowing data to flow freely in both directions without the need to reopen the connection for each exchange. This is ideal for applications that require a high volume of messages, such as chat applications or live sports updates. * The protocol supports message-based data transfer, enabling efficient real-time communication. 2. **Server-Sent Events (SSE)**: * Unlike WebSockets, SSE is designed for unidirectional communication from the server to the client, perfect for applications like live news feeds or stock ticker updates. * SSE works over standard HTTP, making it straightforward to implement on top of existing web infrastructures. ### Polling and Long-Polling Before the widespread adoption of WebSockets and SSE, **polling** was a common technique to simulate real-time capabilities: * **Standard Polling**: The client regularly sends HTTP requests to the server to check for updates. * **Long-Polling**: The server holds the connection open until new data is available or a timeout occurs, reducing the number of requests when compared to standard polling. ### Real-Time Data Handling with SignalDB SignalDB enhances real-time data capabilities by providing an in-memory database that supports reactive data flows: * **In-Memory Storage**: SignalDB stores data in memory, which allows for rapid access and manipulation, crucial for real-time applications. * **Reactivity**: Utilizing reactive programming principles, SignalDB ensures that any changes to the data are immediately propagated to all connected clients. This is achieved through its integration with various reactive libraries and frameworks. ### Technical Challenges and Solutions Implementing real-time functionality comes with its set of challenges, such as dealing with network latency, handling concurrency, and ensuring data integrity across multiple clients. Solutions such as **conflict resolution algorithms** and **data versioning** are often employed to address these issues, ensuring that the application remains robust and responsive under varying network conditions and usage scenarios. ### Optimizing for Performance and Scalability To ensure that real-time web apps can scale effectively, developers must consider: * **Load balancing**: Distributing client connections and data across multiple servers. * **Caching**: Storing frequently accessed data in fast-access storage layers to reduce load times. * **Data compression and batching**: Minimizing the size of data packets and sending them in batches to optimize bandwidth usage. In this technical exploration, we've seen how real-time web applications leverage client-server architectures and various technologies to deliver dynamic, responsive user experiences. As we move forward, the integration of tools like SignalDB can further simplify the development and enhance the capabilities of real-time systems. ## Benefits of Using SignalDB for Real-Time Data SignalDB, designed specifically for handling real-time data in web applications, offers a suite of features that enhance the development and performance of real-time systems. Here are some key benefits of using SignalDB: ### Reduced Latency * **In-Memory Operations**: SignalDB operates primarily in-memory, which dramatically reduces the time it takes to access and manipulate data. This is crucial for applications where response time is critical, such as in financial trading platforms or real-time analytics tools. * **Optimized Data Handling**: With its efficient data storage and retrieval mechanisms, SignalDB ensures minimal delay in the synchronization of data across clients, providing a smoother user experience. ### Ease of Integration * **Framework Agnostic**: SignalDB can be integrated with any JavaScript framework, offering flexibility regardless of the technology stack. This makes it an ideal choice for developers looking to enhance existing applications with real-time capabilities without overhauling their current systems. * **Reactivity Adapters**: SignalDB includes built-in support for various reactivity models, which simplifies the process of connecting the database with the application's UI. These adapters ensure that the UI reflects updates to the data without manual intervention. ### Scalability * **Lightweight Architecture**: The lightweight nature of SignalDB allows it to perform efficiently even as the application scales. This is essential for maintaining performance levels as user numbers increase. * **Adaptable to Growth**: SignalDB's design supports horizontal scaling, which is advantageous for applications expecting growth in user base or data volume. ### Real-Time Synchronization * **Instant Data Updates**: SignalDB ensures that any changes made to the database are instantly reflected across all clients. This feature is key for applications that rely on the latest data, such as collaborative tools and dashboards. * **Consistency and Reliability**: Despite its fast operations, SignalDB does not compromise on the consistency and reliability of the data, ensuring that all users see the same data at the same time. ### Enhanced Developer Experience * **Simplified Data Management**: With its schema-less design and MongoDB-like query language, SignalDB reduces the complexity involved in data management. Developers can perform queries and updates without needing to manage complex relational data schemas. * **Documentation and Community Support**: SignalDB is well-documented and supported by a growing community of developers, which aids in troubleshooting and innovative uses of the technology. In conclusion, SignalDB presents a compelling solution for developers looking to implement real-time features in their applications. Its performance, flexibility, and ease of use not only improve the development process but also enhance the end-user experience by providing fast, reliable, and real-time data interactions. ## Conclusion Throughout this exploration of real-time web applications and SignalDB, we've uncovered the pivotal role that real-time data plays in modern web development. The ability to interact with and respond to data instantaneously is not just a convenience but a critical feature that enhances user experience, engagement, and satisfaction across various applications, from chat platforms to live-tracking systems. SignalDB emerges as a robust solution for managing real-time data with its impressive set of features designed to minimize latency, ensure data consistency, and integrate seamlessly with any JavaScript framework. Its in-memory operation, combined with a schema-less design and support for reactive data flows, simplifies the developer's task, allowing them to focus more on creating dynamic user experiences rather than managing backend complexities. For developers aiming to build or enhance applications with real-time capabilities, SignalDB offers a compelling toolkit that promises not only to meet but exceed the demands of modern real-time data processing. By choosing SignalDB, developers can ensure that their applications are not only responsive and reliable but also scalable and maintainable as user demands evolve. Whether you're just starting with real-time applications or looking to optimize an existing system, the insights and technical strategies discussed here will guide you towards achieving more efficient, effective, and engaging real-time interactions. Embrace the power of real-time data with SignalDB, and unlock new levels of interactivity and performance in your web applications. --- --- url: /offline-first.md --- # Offline-First Databases for JavaScript ## Understanding the Offline-First Approach **An offline-first app reads and writes data locally first and synchronizes with the server in the background.** The network becomes an optimization instead of a requirement: the app starts, shows data and accepts changes even without a connection, and reconciles with the backend once it is back online. The core building block is an **offline-first database**: a database that runs inside the app (in the browser, in Electron or on a mobile device), persists data locally, and keeps a queue of local changes that it syncs with the server. Offline-first matters well beyond "no internet". The same architecture makes apps feel instant on slow or flaky connections, because every interaction is answered from local data, and it makes [optimistic UI](/optimistic-ui/) the default rather than an extra feature. This guide covers the challenges of offline-first development, how offline-first JavaScript databases work, how the popular options compare, and how to build an offline-first app step by step. ## Challenges in Implementing Offline-First Applications Offline-first moves work from the server to the client. These are the problems you need to solve: 1. **Local persistence**: data has to survive reloads and app restarts. In the browser this means IndexedDB, OPFS or localStorage, each with different limits (see [localStorage vs IndexedDB vs OPFS](/browser-storage/)). 2. **Change tracking and sync**: every local insert, update and removal must be recorded and replayed against the server when the connection is back, in the right order. 3. **Conflict resolution**: if the same record was changed locally and on the server, the app needs a deterministic rule for which change wins. 4. **Reactivity**: when synced data arrives, every part of the UI that shows it must update without a reload. 5. **Asset caching**: the app shell (HTML, JavaScript, CSS) must be available offline too, which is the job of a Service Worker, not the database. A good offline-first database handles points 1–4 for you; the Service Worker handles point 5. ## Overview of Reactive JavaScript Databases Most modern offline-first databases for JavaScript are **reactive**: instead of running a query once, you subscribe to it, and the result updates automatically whenever the underlying data changes, whether through a local write or a sync from the server. This is what makes offline-first practical. Without reactivity, every sync would require you to find and refresh every affected view by hand. With a reactive database, the UI is simply a function of the local data, and sync only needs to update that data. ## JavaScript Databases for Offline Applications The table compares popular open-source databases you can use for offline-first JavaScript apps. It focuses on how each one stores data, how you get reactive query results, and how sync works. | Database | Storage | Reactive queries | Sync | License | Good fit for | |---|---|---|---|---|---| | **[SignalDB](/getting-started/)** | In-memory collections, persisted via adapters (IndexedDB, OPFS, localStorage, file system) | MongoDB-like queries, reactive through the signal library you use (Solid, Angular, Vue, Preact, Svelte, MobX, …) | Built-in sync layer: you implement `pull`/`push` for any backend (REST, GraphQL, WebSockets) | MIT | Reactive web apps that need optimistic UI and sync with an existing backend | | **[RxDB](https://rxdb.info/)** | Pluggable storages (IndexedDB, OPFS, SQLite and more; some are paid premium plugins) | Mango (MongoDB-style) queries as RxJS observables | Replication plugins for many backends (HTTP, GraphQL, CouchDB, Firestore, Supabase, …) | Apache 2.0 core, paid premium plugins | Feature-rich offline-first apps across browser, Electron and React Native | | **[Dexie.js](https://dexie.org/)** | IndexedDB wrapper | `liveQuery()` | Via the Dexie Cloud service or your own code | Apache 2.0 | Web apps that want a convenient API directly on top of IndexedDB | | **[PouchDB](https://pouchdb.com/)** | IndexedDB (browser), LevelDB (Node.js) | Changes feed | Built-in two-way sync with CouchDB-compatible servers | Apache 2.0 | Apps with a CouchDB-compatible backend | | **[WatermelonDB](https://watermelondb.dev/)** | SQLite on React Native, LokiJS adapter on the web | Observable queries | Sync protocol you implement on your backend | MIT | React Native apps with large datasets | | **[TinyBase](https://tinybase.org/)** | In-memory store of tables and values, persisted via persisters (IndexedDB, localStorage, SQLite, …) | Listeners and React hooks | Synchronizers based on CRDTs | MIT | Small to medium reactive app state with peer or server sync | | **[TanStack DB](https://tanstack.com/db)** | In-memory collections | Live queries with optimistic mutations | Via collection types (TanStack Query, ElectricSQL and others) | MIT | Apps already using TanStack Query | *Last reviewed: October 2026. Features change quickly. Check each project's documentation before you decide. For a detailed feature matrix and a one-to-one comparison with each project, see the [JavaScript database comparison](/comparison/).* ### Factors to Consider When Choosing a Database * **Backend**: do you already have a REST or GraphQL API? Then you need a database whose sync can talk to *your* API (SignalDB, RxDB). If you can choose the backend, a database with a matching server (PouchDB with CouchDB, a hosted sync service) can save work. * **Framework**: check how query results reach your components. SignalDB plugs into the framework's own signals; RxDB uses RxJS observables; Dexie and TinyBase ship React hooks. * **Platform**: browser only, or also React Native and Electron? Storage options differ per platform. * **Data size**: in-memory databases (SignalDB, TinyBase, TanStack DB) are extremely fast for typical app data, but every record lives in memory. For hundreds of thousands of records, a database that queries storage directly (Dexie, WatermelonDB, RxDB with an indexed storage) is a better fit. * **License and cost**: all options above are open source, but some features (RxDB premium plugins, Dexie Cloud) are commercial. ## SignalDB: A Case Study in Offline-First Applications SignalDB is a reactive, local-first JavaScript database. Here is how it handles the challenges listed above. **1. Local persistence.** Every collection is persisted through a [storage adapter](/data-persistence/) underneath its [data adapter](/data-adapters/). With the default data adapter, data is loaded into memory on start and written back on every change: ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import createIndexedDBAdapter from '@signaldb/indexeddb' export const dataAdapter = new DefaultDataAdapter({ storage: createIndexedDBAdapter({ databaseName: 'my-app', version: 1, schema: { 'todos': ['completed'], // stores the SyncManager below keeps its change queue in 'app-changes': ['collectionName'], 'app-snapshots': ['collectionName'], 'app-sync-operations': ['collectionName', 'status'], }, }), }) const todos = new Collection('todos', dataAdapter) await todos.insert({ title: 'Buy milk', completed: false }) // works offline ``` **2. Change tracking and sync.** The [`SyncManager`](/reference/sync/) records every local change, persists the change queue (so it survives reloads while offline), and calls your `pull` and `push` functions when it syncs: ```js import { SyncManager } from '@signaldb/sync' const syncManager = new SyncManager({ id: 'app', dataAdapter, // the same data adapter the collections use pull: async ({ apiPath }) => { const items = await fetch(apiPath).then(res => res.json()) return { items } }, push: async ({ apiPath }, { changes }) => { await fetch(apiPath, { method: 'POST', body: JSON.stringify(changes) }) }, }) syncManager.addCollection(todos, { name: 'todos', apiPath: '/api/todos' }) syncManager.syncAll() ``` **3. Conflict resolution.** During sync, SignalDB pulls the latest server data and *replays* the local changes on top of it. Only the resulting differences are pushed, and the most recent change operation wins. See [Sync Flow & Conflict Resolution](/sync/#sync-flow-conflict-resolution) for details. **4. Reactivity.** Queries run inside an effect of your signal library are reactive, so data from a sync shows up in the UI immediately (see the framework examples below). Because it is backend-agnostic, SignalDB fits apps that already have an API. There are examples for a [plain HTTP API](https://signaldb.js.org/examples/replication-http/), [Firebase](https://signaldb.js.org/examples/firebase/), [Supabase](https://signaldb.js.org/examples/supabase/) and [Appwrite](https://signaldb.js.org/examples/appwrite/). ## Offline-First in Angular, React and Vue The database layer is the same in every framework. Only the way query results reach your components differs. **Angular** uses Angular Signals through [`@signaldb/angular`](/reference/angular/): ```ts import { effect } from '@angular/core' import { Collection } from '@signaldb/core' import angularReactivityAdapter from '@signaldb/angular' // dataAdapter is the one set up above const todos = new Collection('todos', dataAdapter, { reactivity: angularReactivityAdapter, }) effect((onCleanup) => { const cursor = todos.find({ completed: false }) console.log(cursor.fetch()) // re-runs on local writes and synced changes onCleanup(() => cursor.cleanup()) }) ``` **React** uses the `useReactivity` hook from [`@signaldb/react`](/guides/react/): ```jsx const openTodos = useReactivity(() => todos.find({ completed: false }).fetch()) ``` **Vue** uses Vue's refs through [`@signaldb/vue`](/reference/vue/): ```js watchEffect((onCleanup) => { const cursor = todos.find({ completed: false }) openTodos.value = cursor.fetch() onCleanup(() => cursor.cleanup()) }) ``` Full setup instructions are in the guides for [Angular](/guides/angular/), [React](/guides/react/), [Vue](/guides/vue/), [Svelte](/guides/svelte/) and [Solid](/guides/solid-js/). ## Building Offline-First JavaScript Apps ### Step 1: Understand Offline-First Needs * Identify the data and features users need offline. Not everything has to be available offline. * Plan for users switching between online and offline often, and for long offline periods. ### Step 2: Choose the Right Tools * Pick an offline-first database that matches your backend and framework (see the [comparison](#javascript-databases-for-offline-applications)). * Add a **Service Worker** (for example with Workbox) so the app shell loads offline. ### Step 3: Implement Effective Caching * Cache static assets (HTML, CSS, JavaScript) with a **cache-first** strategy. * Keep *data* in the database, not in the HTTP cache. That way it stays queryable and writable offline. ### Step 4: Handle Data Synchronization * Queue local changes and push them when the app reconnects. A sync layer such as SignalDB's [`SyncManager`](/sync/) does this for you. * Use live updates (WebSockets or server-sent events) to pull remote changes as soon as they happen. ### Step 5: Test Rigorously * Test the first load without a connection, a disconnect in the middle of a write, and conflicting edits on two devices. * Use the browser devtools' offline mode and network throttling. ### Step 6: Optimize User Experience * Show offline status and pending sync state. SignalDB exposes a reactive `isSyncing()` for this. * Never block the UI on the network: write locally, sync in the background. ## Enhanced User Experience (UX) with Reactive Databases Reactive offline-first databases improve UX in three ways: * **Instant feedback**: every action is applied locally first, so there are no loading spinners for writes ([optimistic UI](/optimistic-ui/)). * **Seamless transitions**: going offline or coming back online does not interrupt the user. Sync happens in the background. * **Always up to date**: when synced data arrives, reactive queries update the affected views automatically. To get the most out of this, show a clear offline indicator, communicate pending changes ("3 changes waiting to sync"), and explain conflicts in plain language when they need the user's attention. ## Best Practices and Tips for Offline-First Development ### Best Practices for Offline-First Development 1. **Design for offline from the start.** Retrofitting offline support into an app that assumes the server is always reachable is much harder. 2. **Keep the local dataset focused.** Sync only what the current user needs offline, for example their own projects instead of the whole database. 3. **Make writes idempotent on the server.** Sync may retry a push; the server should handle the same change twice without side effects. 4. **Choose a clear conflict strategy.** "Last write wins" is simple and fits most apps. Collaborative editing of the same text needs specialised approaches such as CRDTs. 5. **Persist the sync queue.** Changes made offline must survive a reload or app restart before they are pushed. ### Common Pitfalls to Avoid * Storing data only in memory or in the HTTP cache: it disappears on reload or cannot be queried offline. * Ignoring storage limits: browsers can evict data under storage pressure. Request persistent storage (`navigator.storage.persist()`) for important data. * Silent conflicts: if your conflict rule can discard user input, make it visible. ## Frequently Asked Questions ### What is an offline-first database? A database that runs inside the client application, stores data locally and synchronizes with a server in the background, so the app keeps working without a network connection. ### What is the difference between offline-first and local-first? Offline-first means the app keeps working without a network. [Local-first](/local-first/) goes further: the local copy is the primary copy of the data, and the server is mainly used for sync, backup and collaboration. An offline-first database is the technical foundation for both. ### Which JavaScript database works offline? All databases in the [comparison above](#javascript-databases-for-offline-applications) work offline. They differ in storage, reactivity and how they sync with your backend. ### Do I need a Service Worker for an offline-first app? For a web app, yes, if it should *load* without a connection: the Service Worker caches the app's files. The offline-first database handles the *data*. ## Conclusion Offline-first apps answer every interaction from local data and sync in the background, which makes them faster and more resilient than apps that depend on the network. The key decision is the database: it has to persist data locally, track and sync changes, resolve conflicts and keep the UI reactive. If you are building a reactive web app with an existing backend, [get started with SignalDB](/getting-started/). It persists data locally, syncs with any API and plugs into the signals of your framework. --- --- url: /reactive-databases.md --- # Reactive JavaScript Databases and Popular JS Frameworks ## Introduction to Reactive JavaScript Databases Imagine a world where your data responds and adapts instantly, with every change reflecting in real-time across your JavaScript applications. This is the realm of **reactive databases**, a transformative approach to data management in dynamic web applications. Unlike traditional databases that require manual refreshes to update data, reactive databases are designed to automatically synchronize and update as data changes, ensuring a seamless and interactive user experience. Why are reactive JavaScript databases crucial for modern web development and interactive web applications? They excel in providing *real-time responsiveness* – crucial in today’s fast-paced digital landscape. Whether it's a social media feed updating with new posts or a financial app reflecting live market changes, reactive databases ensure your application stays current and engaging. Additionally, they simplify the developer's task, eliminating the need for complex coding to manage data updates and state changes. The result? More efficient, maintainable, and scalable JavaScript applications. Adopting a reactive database, such as **SignalDB** in your web development projects, can revolutionize the way you develop and experience web applications. It's not just about storing data; it's about creating an interactive, dynamic environment that enhances user engagement and satisfaction. Stay tuned as we dive deeper into the exciting world of SignalDB and its integration with popular JavaScript frameworks. ## Overview of SignalDB Explore the innovative features of **SignalDB**, a reactive JavaScript database tailored for modern web and app development. SignalDB stands out in the realm of JavaScript development for its unique approach to data management. Unlike traditional databases that operate on a request-response model, SignalDB thrives on reactivity, ensuring data stays synchronized and up-to-date in real-time. What sets SignalDB apart? At its core, SignalDB is built for *real-time data flow*. This means that any changes in the database are immediately propagated to the connected clients, eliminating the need for manual refreshes or polling mechanisms. Whether you're dealing with a handful of users or scaling to thousands, SignalDB maintains its efficiency and responsiveness. This feature is particularly beneficial in applications where timely data updates are crucial, such as in collaborative tools, live analytics platforms, and interactive dashboards. Another hallmark of SignalDB is its *simplicity and ease of integration with major JavaScript frameworks*. It seamlessly fits into the JavaScript ecosystem, aligning perfectly with popular JS frameworks like Angular, Vue, and Solid.js. This compatibility not only enhances developer productivity but also opens doors to creative possibilities in web development. As we progress through this guide, we will explore how SignalDB can be integrated into various JavaScript frameworks, elevating your applications to new heights of interactivity and user engagement. ## Integrating SignalDB with Angular Diving into the world of Angular, integrating SignalDB unlocks a new dimension of reactivity and efficiency. Angular, known for its robustness and powerful features, pairs seamlessly with SignalDB’s real-time data capabilities. This section provides a step-by-step guide to merge these two technologies, creating applications that are not only fast but also intuitively responsive. The first step is establishing a connection between your Angular application and SignalDB. This involves setting up SignalDB as your primary data source and configuring Angular services to interact with it. By leveraging Angular’s dependency injection and observables, data from SignalDB flows naturally into your components, ensuring that your UI updates instantly as your data changes. This synergy is not just about technical integration; it’s about creating an application that feels alive, responsive, and connected. Practical use cases of this integration are vast. Imagine a dashboard application where data updates in real time, reflecting changes without any user intervention. Or a chat application where messages appear instantly, providing a seamless user experience. These scenarios highlight the power of combining Angular’s framework capabilities with the real-time data synchronization of SignalDB. As you embark on this integration journey, remember the keyword focus: "reactive database integration with Angular". It's not just a technical task; it's about enhancing the user experience at every level. ## Using SignalDB in Vue Applications Vue.js, renowned for its simplicity and flexibility, becomes even more powerful when paired with SignalDB. This section delves into how to harness the synergy of SignalDB within Vue applications, elevating them with real-time, reactive data functionalities. Whether you're building dynamic web interfaces or sophisticated single-page applications or real-time data-driven apps with Vue, this combination promises a leap in performance and user experience. Integrating SignalDB in Vue starts with the seamless incorporation into Vue's reactive system. This involves creating a SignalDB instance and making it accessible within Vue's component structure. By leveraging Vue's reactivity system, changes in the database are immediately reflected in the Vue components. This real-time update mechanism is essential for applications that require instant data updates like live content feeds, interactive forums, or dynamic dashboards. A key aspect of this integration is optimizing performance and reactivity. With Vue's efficient data binding and SignalDB's real-time updates, developers can create highly responsive applications with minimal performance overhead. The keyword focus here is "using JavaScript databases with Vue" - a testament to the seamless integration and the enhancement of Vue's capabilities with the power of SignalDB. As you integrate these technologies, remember that the goal is not just technical integration, but also to provide a smooth, engaging user experience. ## Enhancing Solid.js Apps with SignalDB Solid.js, a rising star in the JavaScript world, becomes even more potent when integrated with SignalDB. This section explores how SignalDB can be woven into Solid.js applications, infusing them with unparalleled reactivity and data handling capabilities. If you’re venturing into the realm of Solid.js, enriching it with SignalDB’s reactive prowess is a game-changer for building state-of-the-art web applications. Integrating SignalDB into Solid.js involves leveraging Solid.js’s fine-grained reactivity system. This synergy allows for an intuitive and straightforward way to reflect data changes in real-time. By establishing a connection between Solid.js components and SignalDB, applications gain the ability to update seamlessly and efficiently in response to data changes. This integration is particularly impactful in scenarios where real-time data is crucial, such as in live analytics tools, interactive user interfaces, or real-time collaboration platforms. What sets this integration apart is not just the technical alignment but the enhancement of user experience and application performance. The focus here, "enhancing Solid.js apps with reactive databases", underscores the transformative effect of SignalDB on Solid.js applications. As developers, the aim is to create applications that are not only technically sound but also provide a dynamic and engaging user interface, and integrating SignalDB with Solid.js is a significant step in that direction. ## Cross-Framework Compatibility and Benefits The beauty of SignalDB lies in its versatility and cross-framework compatibility. It’s not confined to any single JavaScript framework, offering a flexible solution adaptable to various environments. This section sheds light on how SignalDB can be a unifying force across different JavaScript frameworks, including but not limited to Angular, Vue, and Solid.js. One of SignalDB’s key strengths is its adaptability. Whether you’re working with the structured environment of Angular, the reactive elegance of Vue, or the fine-grained reactivity of Solid.js, SignalDB integrates seamlessly, bringing its real-time data capabilities to each framework. This adaptability is vital in today’s diverse web development landscape, where choosing the right tools can significantly impact the success of a project. By embracing SignalDB across different frameworks, developers can ensure a consistent and high-quality user experience, regardless of the underlying technology. The benefit extends beyond mere technical integration; it’s about creating applications that are reactive, efficient, and maintainable across different ecosystems. SignalDB’s cross-framework compatibility exemplifies the future of web development - a future where versatility and performance go hand in hand, empowering developers to build better, more responsive web applications. ## Case Studies and Real-World Applications Transcending theory, the real value of SignalDB is best illustrated through case studies and real-world applications. This section delves into practical examples where SignalDB has been effectively utilized, demonstrating its impact on performance improvements and user experience enhancements across various industries. Consider a scenario in an e-commerce platform. By integrating SignalDB, the platform experienced a significant boost in real-time inventory management and dynamic pricing updates, leading to enhanced customer satisfaction and increased sales. Another case study in a social media application reveals how SignalDB enabled instantaneous updates of user feeds and interactions, fostering a more engaging and responsive community. These examples are just the tip of the iceberg. From small startups to large enterprises, SignalDB has proven its worth by providing scalable, real-time data solutions that drive business success. Beyond technical efficiency, these case studies highlight the human aspect of technology – how it can create more dynamic, interactive, and satisfying user experiences. SignalDB isn’t just a database; it’s a tool that breathes life into applications, making them more vibrant and connected to the needs of users. ## Troubleshooting and Common Challenges Embracing new technologies like SignalDB, while exciting, can also bring its set of challenges. This section is dedicated to troubleshooting common issues and providing solutions when integrating SignalDB into various JavaScript frameworks. Our goal is to equip you with the knowledge to navigate these hurdles with confidence. One common challenge is the initial setup and configuration of SignalDB within a project. This can involve nuanced steps specific to each JavaScript framework. Addressing this, we offer clear, detailed guidance to ensure a smooth integration process, whether you are working with Angular, Vue, or Solid.js. Another frequent hurdle is managing data synchronization and handling conflicts, especially in applications with high concurrency. Here, we present best practices and strategies to maintain data integrity and consistency. Debugging is another critical aspect of working with SignalDB. We share insights on how to effectively debug applications, utilizing tools and techniques to quickly identify and resolve issues. By addressing these common challenges, we aim to not only simplify your development process but also enhance the reliability and stability of your applications. Remember, encountering challenges is a natural part of the learning curve, and overcoming them is key to mastering the integration of reactive databases in your JavaScript projects. ## Future Trends and Developments in Reactive Databases As we stand at the forefront of technological innovation, it's crucial to look ahead at the evolving landscape of reactive databases like SignalDB. This section explores upcoming features, trends, and how these advancements might shape the future of JavaScript development. One exciting trend is the increasing integration of artificial intelligence and machine learning within reactive databases. This evolution could lead to smarter, more adaptive data systems that can predict user needs and optimize performance accordingly. Another area of development is enhanced scalability and performance optimizations, ensuring reactive databases like SignalDB can effortlessly handle the growing demands of modern web applications. Furthermore, we anticipate advancements in data security and privacy features, a critical aspect in today's data-driven world. As reactive databases become more prevalent, ensuring data protection and compliance with global standards will be paramount. These developments are not just technical milestones; they represent a shift towards more intelligent, efficient, and secure web applications. Staying abreast of these trends is vital for any developer or organization looking to leverage the full potential of reactive databases in their JavaScript projects. ## Conclusion As we conclude our exploration of integrating reactive JavaScript databases with popular JS frameworks, it's clear that SignalDB represents a significant advancement in web development. The seamless fusion of SignalDB with frameworks like Angular, Vue, and Solid.js not only showcases its versatility but also opens new avenues for creating dynamic, responsive applications. From enhancing user experience to simplifying development processes, the benefits of using SignalDB are manifold. Its real-time data synchronization capabilities bring a new level of interactivity and engagement to web applications, crucial in today's fast-paced digital landscape. Moreover, the insights provided in troubleshooting and future trends offer a comprehensive understanding and preparedness for the evolving world of web development. We encourage developers and organizations to explore the potential of SignalDB in their JavaScript projects. As the digital world continues to evolve, staying ahead of the curve with technologies like SignalDB will be key to building innovative, high-performing web applications. Embrace the journey, and let SignalDB transform your web development experience. --- --- url: /aws-amplify.md --- # Leveraging AWS Amplify with Reactive Databases ## Introduction to AWS Amplify When it comes to building robust full-stack applications, the choice of technology plays a pivotal role in determining both the development experience and the application's performance. In this context, **AWS Amplify** emerges as a game-changer, especially for developers looking to harness the power of cloud services with ease and efficiency. AWS Amplify is a set of tools and services provided by Amazon Web Services that simplifies the process of building scalable mobile and web applications. It is especially lauded for its *seamless integration* with other AWS services, enabling developers to incorporate backend functionalities like authentication, data storage, and API creation without deep diving into the complexities of cloud infrastructure management. At its core, AWS Amplify offers a **declarative interface**, allowing developers to model their application infrastructure in a straightforward manner. This approach is a breath of fresh air, especially for those who are new to cloud services. With Amplify, you can set up environments, manage application content, and configure backend services with just a few commands. One of the standout features of AWS Amplify is its **real-time data synchronization**. This functionality ensures that data remains consistent across different user devices, a critical aspect in today's interconnected digital world. Moreover, Amplify's capability to **scale automatically** in response to application demands makes it an ideal choice for projects that anticipate variable user traffic. For developers who prioritize user experience, Amplify's integration with **AI and ML services** offers an edge. This feature enables the creation of more intuitive and responsive applications, enhancing user engagement. Moreover, AWS Amplify's commitment to security, with features like **user authentication** and **data encryption**, ensures that both developer and user interests are safeguarded. In conclusion, AWS Amplify is not just a tool; it's a catalyst for innovation in full-stack development. Its ability to simplify complex cloud operations, coupled with its scalable and secure infrastructure, makes it an invaluable asset for modern developers. As we delve deeper into the specifics of integrating AWS Amplify with reactive databases, we'll uncover how this powerful tool is revolutionizing the way we build and manage full-stack applications. ## Overview of Reactive Databases Understanding the dynamics of **reactive databases** is crucial in today’s fast-paced web development landscape. These databases represent a paradigm shift, focusing on data that is continuously updated in real-time, a stark contrast to the traditional request-response model. This section delves into the essence of reactive databases, shedding light on their defining characteristics and inherent advantages. At the heart of reactive databases lies the concept of *reactivity*. Unlike traditional databases, reactive databases are designed to push updates to the application as soon as data changes, eliminating the need for constant polling. This approach ensures that the application data is always up-to-date, enhancing the user experience significantly. One of the most compelling features of reactive databases is their **scalability**. In a world where data grows exponentially, these databases excel in handling large volumes of data with minimal latency. They are built to adapt dynamically to varying loads, making them ideal for applications expecting high traffic or dealing with large datasets. Another advantage of using reactive databases is their **efficiency in real-time applications**. Applications like chat systems, live financial tickers, or real-time analytics dashboards thrive on the immediacy of data, which is precisely what reactive databases provide. By ensuring that the latest data is always available, they create an interactive and engaging user experience. Moreover, reactive databases support a more **streamlined development process**. By handling data updates automatically, they reduce the complexity in backend logic, allowing developers to focus more on the frontend and user experience aspects of the application. This leads to not only faster development cycles but also more robust and reliable applications. In conclusion, reactive databases stand out as a transformative technology in the realm of web development. Their ability to provide real-time data updates, coupled with their scalability and efficiency, positions them as a cornerstone technology for modern, dynamic applications. As we explore their integration with AWS Amplify, the potential for creating powerful and responsive full-stack applications becomes increasingly evident. ## Integrating AWS Amplify with Local Databases The fusion of **AWS Amplify** with local databases marks a significant milestone in streamlining full-stack development processes. This integration facilitates an environment where the robust cloud capabilities of AWS Amplify blend seamlessly with the convenience and control of local databases. In this section, we explore the methodologies and best practices for this integration, addressing potential challenges and offering practical solutions. Integrating AWS Amplify with local databases starts with understanding the synchronization process. The goal is to maintain a consistent state between the cloud and local environments. This involves configuring AWS Amplify to interact efficiently with the local database, ensuring data is accurately mirrored and updated in real-time. One best practice is to use **GraphQL APIs** provided by AWS Amplify. These APIs facilitate smooth data operations between the cloud and local databases. Developers can define GraphQL schemas that reflect their data models, allowing for efficient data fetching and updating processes. However, challenges such as data conflict resolution and latency issues can arise. To mitigate these, implementing an effective **conflict resolution strategy** is essential. AWS Amplify provides mechanisms to handle conflicts in data synchronization, ensuring data integrity is maintained. Additionally, optimizing data structures and queries can significantly reduce latency, enhancing overall application performance. Another consideration is **offline functionality**. For applications that require offline access, developers need to implement local data storage solutions that synchronize with the cloud once connectivity is restored. AWS Amplify's offline capabilities and data store features can be leveraged to achieve this, providing a seamless offline to online transition. Security is also a paramount concern. Ensuring that data is securely transmitted and stored requires implementing robust encryption and authentication mechanisms. AWS Amplify's built-in security features can be utilized to safeguard data both in transit and at rest, providing peace of mind to both developers and users. In conclusion, integrating AWS Amplify with local databases, while challenging, offers a pathway to creating more versatile and resilient applications. By following best practices and addressing potential hurdles, developers can harness the best of both worlds, leveraging the power of the cloud and the flexibility of local databases to build superior full-stack applications. ## Benefits of AWS Amplify with Reactive Databases Combining AWS Amplify with reactive databases unlocks a plethora of benefits, paving the way for building scalable, efficient, and user-friendly full-stack applications. This synergy enhances both the development process and the end-user experience, making it a preferred choice for modern web developers. Let's delve into the specific advantages this integration brings to the table. The first and foremost benefit is **enhanced scalability**. AWS Amplify's cloud infrastructure, combined with the dynamic nature of reactive databases, allows applications to effortlessly scale up or down based on user demand. This scalability ensures that applications remain responsive and efficient, regardless of the number of concurrent users or the size of the data being handled. Another significant advantage is the ability to provide **real-time updates**. Reactive databases are inherently designed to update data in real-time. When integrated with AWS Amplify, this translates into an ultra-responsive user experience, where data changes are reflected instantly across all user interfaces. Improving the **user experience** is another critical benefit. The combination of AWS Amplify with reactive databases facilitates the creation of intuitive and interactive applications. Users benefit from up-to-date information and seamless interactions, which is crucial in today's fast-paced digital environment. Furthermore, this integration significantly **optimizes development efforts**. AWS Amplify provides a high-level framework that simplifies complex backend tasks, while reactive databases handle data synchronization and updates efficiently. This combination reduces the development time and resources required, allowing teams to focus on innovating and improving the core functionality of their applications. Lastly, the integration offers **improved data management and security**. AWS Amplify comes with built-in security features that ensure data is securely managed and compliant with various standards. When combined with the robustness of reactive databases, it provides a secure and reliable environment for handling sensitive data. In summary, integrating AWS Amplify with reactive databases brings forth scalability, real-time data updates, enhanced user experience, optimized development, and improved data security. These benefits make it an ideal solution for developers aiming to build cutting-edge, responsive, and robust full-stack applications. ## Full-Stack Development Enhancement The collaboration between **AWS Amplify** and reactive databases represents a significant advancement in the realm of full-stack development. This integration optimizes both backend and frontend development, offering developers a streamlined workflow and end-users a responsive and dynamic experience. In this section, we'll explore how this partnership enhances the full-stack development process with practical examples. Starting on the frontend, developers benefit from AWS Amplify's declarative approach to building user interfaces. With Amplify's JavaScript libraries and UI components, creating interactive and data-driven interfaces becomes remarkably efficient. Developers can easily connect their frontend components to AWS services and reactive databases, ensuring a seamless flow of data and real-time updates. On the backend, AWS Amplify simplifies the creation and management of serverless functions, APIs, and database connections. Developers can define their data models, authentication rules, and API endpoints using a straightforward syntax. This abstraction of backend complexity allows developers to focus on business logic and frontend development, rather than wrestling with infrastructure. Practical examples of full-stack development enhancement include the creation of real-time collaboration tools, such as collaborative document editors or interactive dashboards. With AWS Amplify and reactive databases, developers can implement features like live updates, user collaboration, and data synchronization with ease. Consider an e-commerce application where inventory data needs to be updated in real-time. AWS Amplify can handle the frontend interface, while a reactive database ensures that product availability is instantly reflected. This results in a shopping experience where users always see accurate stock information, leading to increased user satisfaction and fewer abandoned carts. Additionally, the combination of AWS Amplify and reactive databases simplifies the development of data-driven dashboards. Developers can create dashboards that display real-time analytics, financial data, or monitoring metrics. Users can interact with these dashboards, and any changes made are immediately reflected for all users, thanks to the real-time capabilities of reactive databases. In conclusion, AWS Amplify and reactive databases empower developers to create full-stack applications that are not only feature-rich but also highly responsive and dynamic. This enhancement in the development process results in faster time-to-market, improved user experiences, and the ability to innovate and iterate with agility. ## AWS Amplify and Signals Reactivity The synergy between **AWS Amplify** and **signals reactivity** represents a powerful combination that elevates application responsiveness and performance to new heights. In this section, we delve into the concept of signals in reactive programming and how AWS Amplify supports this paradigm, making applications more dynamic and engaging. Signals reactivity, in the context of reactive programming, refers to the ability of an application to respond to changes or events in real-time. This is achieved through the use of signals or streams that carry data and trigger actions when changes occur. This paradigm is particularly valuable in scenarios where immediate feedback and responsiveness are critical, such as online gaming, financial trading, or collaborative document editing. AWS Amplify embraces the principles of signals reactivity by offering features like **real-time data synchronization** and **subscription-based APIs**. These features enable developers to create applications that can listen for changes in data and respond instantly. For example, in a chat application, new messages can be pushed to users' screens as soon as they are sent, creating a smooth and real-time chat experience. One of the key components of signals reactivity is the ability to react to user interactions immediately. With AWS Amplify, developers can easily incorporate user actions and events into their applications. For instance, in a collaborative drawing app, changes made by one user can be instantly reflected on the screens of other users, creating a synchronized drawing experience. Signals reactivity also plays a crucial role in enhancing application performance. By minimizing the need for constant polling or manual data refreshes, applications become more efficient in managing resources and delivering a responsive user interface. AWS Amplify's support for signals reactivity contributes to reduced latency and improved overall performance. In conclusion, the marriage of AWS Amplify and signals reactivity brings forth a transformative approach to application development. Developers can create applications that respond to real-time events and user interactions, resulting in highly engaging and dynamic user experiences. As we look ahead to the future trends of SignalDB and AWS Amplify integration, the possibilities for innovative and responsive applications are boundless. ## Future Trends - SignalDB and AWS Amplify The future of full-stack development is poised for exciting advancements, and one of the most promising trends is the integration of **SignalDB** with **AWS Amplify**. This partnership is expected to reshape how developers build and scale applications, offering enhanced real-time capabilities and improved data management. In this section, we explore the potential developments in this integration and the impact they may have on full-stack development. SignalDB, as a database system designed for real-time data synchronization, aligns perfectly with AWS Amplify's commitment to providing real-time data updates. This synergy is likely to result in more robust and versatile applications that can seamlessly handle data changes in real-time. One anticipated trend is the proliferation of applications with **ultra-responsive user interfaces**. With SignalDB and AWS Amplify, developers can create applications where changes in data are immediately reflected on the user's screen, leading to a smoother and more interactive user experience. This trend is expected to be especially prevalent in collaborative and real-time applications. Moreover, the integration is likely to enable the development of more **intelligent and context-aware applications**. By harnessing the power of real-time data synchronization, applications can adapt to user preferences and behavior in real-time, offering personalized content and recommendations. This trend has the potential to revolutionize user engagement and retention. Another area of development is the **expansion of offline capabilities**. With SignalDB and AWS Amplify, applications can continue to function seamlessly even when offline, with data synchronization occurring once a connection is reestablished. This trend is particularly significant for applications that require uninterrupted access, such as field service apps or remote work tools. Security and compliance are also expected to see improvements. The integration is likely to offer enhanced **security features** for real-time data, ensuring that sensitive information remains protected during transmission and storage. This trend is vital in an era of increasing data privacy concerns and regulations. In conclusion, the future trends of SignalDB and AWS Amplify integration hold great promise for full-stack development. Developers can look forward to creating applications that are not only more responsive and user-centric but also more versatile in handling real-time data. As this integration evolves, the full-stack development landscape is poised for innovation and transformation. ## Challenges and Considerations While the integration of **AWS Amplify** with reactive databases and signals reactivity offers tremendous advantages, it also presents certain challenges and considerations that developers must be mindful of. In this section, we explore these potential hurdles and offer insights into addressing them effectively. One of the primary challenges is **data conflict resolution**. In a real-time environment, conflicts can arise when multiple users attempt to modify the same data simultaneously. Developers need to implement robust conflict resolution strategies to ensure data integrity. AWS Amplify provides mechanisms for conflict detection and resolution, but developers must tailor these solutions to their specific application needs. **Latency** is another consideration, especially in applications where real-time responsiveness is critical. Minimizing latency requires optimizing data structures, queries, and network communication. Developers should focus on efficient data synchronization to keep the application responsive even in high-traffic scenarios. Ensuring **offline functionality** can be complex. While AWS Amplify offers offline support, developers need to plan for scenarios where users may have intermittent connectivity. Implementing a seamless transition between offline and online modes requires careful consideration of data storage and synchronization strategies. Security is paramount, especially when dealing with real-time data updates. Developers should prioritize **data encryption** and **authentication** mechanisms to protect data in transit and at rest. AWS Amplify provides security features, but they should be configured appropriately to meet the application's security requirements. Compatibility with existing systems and legacy databases can be a challenge when integrating with AWS Amplify and reactive databases. Developers may need to invest time in **migrating and transforming data** to fit the new architecture. Planning and testing data migration strategies are essential to avoid disruptions. Lastly, it's crucial to maintain **documentation and training** for development teams. The integration of AWS Amplify with reactive databases introduces new concepts and tools that developers may need to familiarize themselves with. Providing resources and training can facilitate a smoother adoption process. In conclusion, while the benefits of AWS Amplify, reactive databases, and signals reactivity are substantial, developers must navigate challenges related to data conflicts, latency, offline functionality, security, compatibility, and knowledge transfer. Addressing these considerations with careful planning and strategic solutions is essential to realizing the full potential of this integration. ## Conclusion and Recommendations In the ever-evolving landscape of full-stack development, the integration of **AWS Amplify** with reactive databases and signals reactivity emerges as a compelling choice for developers seeking to create scalable, responsive, and innovative applications. As we conclude our exploration of this synergy, let's recap the key takeaways and provide recommendations for those looking to leverage this powerful combination. **Key Takeaways:** 1. AWS Amplify simplifies full-stack development by offering cloud services integration and real-time data synchronization. 2. Reactive databases provide real-time data updates, scalability, and efficiency, enhancing user experiences. 3. Integrating AWS Amplify with local databases requires synchronization, conflict resolution, and offline functionality planning. 4. The combination of AWS Amplify and reactive databases results in enhanced scalability, real-time updates, and improved user experiences. 5. Signals reactivity supported by AWS Amplify enables ultra-responsive applications and streamlined development. 6. The future trends of SignalDB and AWS Amplify integration promise enhanced real-time capabilities and improved data management. 7. Challenges include data conflict resolution, latency optimization, offline functionality, security, compatibility, and knowledge transfer. **Recommendations:** 1. Begin with a clear understanding of your application's real-time requirements and data synchronization needs. 2. Utilize AWS Amplify's declarative approach to simplify backend and frontend development tasks. 3. Implement robust conflict resolution strategies to maintain data integrity in real-time environments. 4. Optimize data structures, queries, and network communication to minimize latency. 5. Plan for offline functionality and seamless transitions between offline and online modes. 6. Prioritize data encryption and authentication to ensure data security in real-time updates. 7. Consider data migration and transformation strategies when integrating with existing systems. 8. Invest in documentation and training to empower development teams with the necessary knowledge. As you embark on your journey of full-stack development with AWS Amplify and reactive databases, remember that this integration opens the door to creating applications that are not only powerful but also dynamic and user-centric. Embrace the opportunities it offers, address the challenges thoughtfully, and stay tuned to the evolving trends to stay at the forefront of innovation in the field. --- --- url: /firebase.md --- # Firebase Offline Persistence with a Reactive Local Database ::: info Short answer Cloud Firestore's web SDK has built-in offline persistence: enable it with `initializeFirestore(app, { localCache: persistentLocalCache() })` and Firestore caches documents in IndexedDB and queues writes while offline. The Realtime Database's web SDK keeps its cache in memory only; disk persistence is available in the Apple and Android SDKs. A reactive local database such as SignalDB is useful on top of that when you want to query local data with your framework's signals, combine Firebase with other data sources, or keep your data layer independent of Firebase. See the runnable [Firebase example](https://signaldb.js.org/examples/firebase/). ::: ## Introduction to Firebase and Reactive Local Databases Imagine building a modern app without the hassle of complex server management. That's where **Firebase**, a powerful Backend-as-a-Service (BaaS), shines. It's not just about offloading server duties; it's about empowering developers to focus on what they do best: creating amazing user experiences. Firebase offers a suite of tools that are both robust and user-friendly, making app development smoother and more efficient. Now, let's talk about the unsung heroes in the realm of app development: **reactive local databases**. These databases, especially ones like SignalDB, are pivotal in creating responsive, dynamic apps. They work seamlessly in the background, managing data locally on the user's device. This results in lightning-fast responses and a smooth user experience, even when the internet connection is spotty. Why combine Firebase with a reactive local database like SignalDB? It's simple: you get the best of both worlds. Firebase handles your backend, database, and analytics, while SignalDB manages your app's local data reactivity. This combination is a powerhouse for modern app development, providing both robust backend services and swift frontend interactions. Integrating Firebase with a local database isn't just about technical prowess; it's about understanding the user's needs. Users expect apps to be fast, reliable, and intuitive. By leveraging Firebase's cloud capabilities and SignalDB's local data management, developers can create apps that not only meet but exceed these expectations. This synergy ensures that your app remains responsive and up-to-date, providing a seamless experience for your users. In essence, combining Firebase with a reactive local database like SignalDB is a strategic move for any developer looking to enhance app performance and user satisfaction. It's not just about building an app; it's about crafting an experience that resonates with users and stands the test of time. So, let's dive deeper into this innovative approach and unlock the full potential of your app development process. ## Firebase Integration with JavaScript Databases Integrating Firebase with JavaScript-based local databases is like bridging two worlds: the cloud and the local environment. This integration allows developers to tap into Firebase's robust cloud infrastructure while maintaining the agility and speed of a local database. But how exactly does this integration work? It's a journey that begins with understanding Firebase's real-time database and Firestore features, and then seamlessly connecting them with JavaScript databases. The benefits of this integration are immense. Firstly, it offers a **real-time synchronization** between the server and local data, ensuring that users always have access to the latest information. Secondly, it provides a **consistent user experience** across devices, as data remains uniform and up-to-date. However, it's not without its challenges. Handling conflicts between local and cloud data, ensuring data integrity, and managing offline data synchronization are some of the hurdles developers may face. To bring these concepts to life, let's consider a case study. Imagine a note-taking app that uses Firebase for cloud storage and a JavaScript local database for immediate data retrieval and storage. When a user creates a note, it's stored locally for instant access and then synchronized with Firebase. This setup ensures that even if the user switches devices, their notes are up-to-date and accessible. Another real-world example is a messaging app. By integrating Firebase, messages are stored and retrieved from the cloud, ensuring they are never lost. But with a local JavaScript database, messages are readily available, providing a smooth and responsive user experience. This dual approach caters to the modern user's need for reliability and speed, making the app more appealing and user-friendly. In conclusion, the integration of Firebase with JavaScript-based local databases is a game-changer in app development. It combines the strength of cloud computing with the efficiency of local data management. By understanding and overcoming the challenges, developers can unlock the full potential of their apps, offering users an experience that's not just functional but also delightful. ## Enhancing App Development with Firebase and SignalDB When it comes to modern app development, the duo of Firebase and SignalDB is akin to a symphony where each element complements the other, creating a harmonious experience for both developers and users. The integration of Firebase's cloud services with SignalDB's local database management transforms the way apps are built, operated, and experienced. SignalDB, a reactive local database, excels in managing data on the device, ensuring rapid data access and manipulation. This local prowess, when combined with Firebase's cloud capabilities, results in a robust and efficient data management system. Apps become more responsive, as data updates are reflected instantaneously, thanks to SignalDB's reactive nature. At the same time, Firebase ensures data integrity and synchronization across platforms and devices. For app developers, this integration translates into several advantages. First, it significantly **reduces development time**, as Firebase provides ready-to-use backend services, and SignalDB handles local data complexities. Second, it offers **improved app performance**, as data is managed efficiently both locally and on the cloud. Lastly, it ensures **seamless offline experiences**, a crucial feature in today’s mobile-first world, where constant connectivity cannot be guaranteed. Implementing this combination, however, requires thoughtful planning. Developers must ensure seamless data flow between Firebase and SignalDB, handle conflict resolution in data synchronization, and maintain data consistency. Practical tips include using Firebase's real-time database for live updates, leveraging SignalDB's reactive features for instant UI updates, and implementing robust error handling and conflict resolution mechanisms. In essence, the union of Firebase and SignalDB is not just about leveraging two technologies; it's about creating a seamless, efficient, and user-friendly app experience. It's a strategic approach that addresses the key needs of modern app development: speed, reliability, and a seamless user experience, both online and offline. By mastering this combination, developers can elevate their apps, making them not just functional but also delightful to use. ## Real-Time Sync with Firebase and Local Databases The magic of modern app development lies in its ability to synchronize data in real-time between the cloud and local storage, and this is where the combination of Firebase and local databases truly shines. It's a dance of data, where every move is synchronized, ensuring a seamless user experience. Firebase, known for its real-time database capabilities, plays a crucial role in this, offering instantaneous updates across all connected devices. Implementing real-time sync involves a sophisticated strategy. The goal is to maintain a delicate balance: ensuring that data updates are reflected promptly while minimizing the load on both the server and the local database. It requires a deep understanding of Firebase's data synchronization mechanisms and the local database's data handling capabilities. By harnessing Firebase's real-time database or Firestore, developers can push or pull data updates to and from the cloud efficiently, ensuring that the user's local database reflects the most current state of data at all times. However, this process is not without its challenges. Network variability and offline scenarios pose significant hurdles. To overcome these, developers must implement intelligent syncing strategies, such as caching important data locally and only syncing essential data changes. This ensures that the app remains functional and up-to-date, even when the internet connection is unstable or unavailable. Addressing common issues in real-time data sync involves handling conflict resolution – what happens when the same data is modified in different ways on different devices? Here, Firebase provides tools to resolve conflicts, ensuring that data integrity is maintained. Another issue is latency, which can be mitigated by optimizing data structures and minimizing the amount of data transferred during each sync. In summary, real-time synchronization between Firebase and local databases is a cornerstone of modern app development. It enhances the user experience by providing up-to-date data, regardless of network conditions. By mastering the art of real-time sync, developers can ensure that their apps are not just functional, but also resilient and reliable, catering to the demands of today's mobile-first world. ## Optimizing Performance and User Experience The integration of Firebase with reactive local databases like SignalDB is a game-changer for optimizing both app performance and user experience. In this digital age, users expect not only functionality but also a seamless and efficient interaction with their apps. The key to achieving this lies in the strategic use of Firebase’s cloud capabilities alongside the speed and responsiveness of SignalDB. Enhancing app performance starts with leveraging Firebase’s efficient backend services. Firebase’s real-time database and Firestore offer a fast and scalable cloud database solution, reducing the load on the local database and ensuring that the most complex queries are handled effortlessly. This allows for quicker data retrieval and an overall smoother app experience. Meanwhile, SignalDB’s reactive nature keeps the app’s interface lively and responsive, updating the UI in real time as data changes, thus maintaining a seamless user experience. The impact on user experience is profound. By ensuring that the app is consistently responsive and reliable, users are more likely to engage and stay longer. For instance, in a social media app, integrating Firebase and SignalDB means that new posts and interactions are updated in real-time, keeping the content fresh and engaging. This not only enhances user satisfaction but also encourages more interaction within the app. Best practices for maintaining high performance include efficient data structuring in Firebase, judicious use of data listeners in SignalDB, and minimizing the synchronization data to what’s essential. Also, developers should focus on handling offline scenarios gracefully, ensuring that users have access to key functionalities even without an internet connection. In conclusion, the synergy between Firebase and SignalDB is more than just a technical integration; it's a pathway to creating applications that are not just powerful and robust but also delightful to use. By optimizing performance and focusing on user experience, developers can create apps that stand out in the crowded digital marketplace, offering users an unmatched experience. ## Security Considerations In the realm of app development, security is not just a feature; it's a cornerstone. When combining Firebase with reactive local databases like SignalDB, security takes on a multifaceted dimension. It's about safeguarding data both in transit and at rest, ensuring that user data remains private and protected against breaches. Firebase, being a Google-backed platform, comes with robust security features. It offers powerful tools like Firebase Authentication for secure user authentication, and Firebase Cloud Firestore's security rules to control access to data stored in the cloud. However, integrating these features with a local database like SignalDB requires a thoughtful approach. Developers must ensure that the same level of security that protects data in the cloud is also applied to data stored locally on the device. Best practices for ensuring data security in this integrated environment include implementing encryption for data stored locally in SignalDB. This ensures that even if a device falls into the wrong hands, the data remains unreadable. Additionally, developers should utilize Firebase’s security rules to manage who has access to what data, preventing unauthorized access and data leaks. Another critical aspect is data privacy. With regulations like GDPR and CCPA, it’s imperative to handle user data with utmost care. This involves not only securing the data but also providing transparency to users about how their data is used. Firebase provides tools to help manage user data and comply with these regulations, but it’s up to developers to implement these practices effectively. In summary, security in the context of Firebase and reactive local databases is a dynamic challenge. It requires a proactive approach, where developers not only utilize the inherent security features of these platforms but also continuously adapt to emerging threats and regulations. By prioritizing security in every aspect of app development, developers can build trust with their users, ensuring the longevity and success of their applications. ## Example Use Cases Typical scenarios where combining Firebase with a reactive local database pays off: * **Apps with intermittent connectivity**, such as field-service or note-taking apps: users keep reading and editing local data, and changes are synced to Firestore once a connection is available. * **Dashboards and lists with complex filters**: data is queried locally with MongoDB-like selectors instead of building a Firestore query and index for every view. * **Apps that combine several data sources**: Firebase data and data from other APIs live in the same local collections and are queried the same way. The main challenges are the same in every scenario: decide which data to sync to each client, handle conflicts consistently, and keep Firestore security rules as the final authority for every write. ## Future Trends and Developments As we peer into the horizon of app development, the fusion of Firebase with reactive local databases like SignalDB hints at exciting future trends and developments. This combination, already powerful, is poised to evolve further, driven by technological advancements and changing user expectations. One emerging trend is the increasing use of machine learning and artificial intelligence within apps. Firebase offers tools like Firebase ML, which can be integrated with local databases to provide more personalized and intelligent app experiences. Imagine an app that not only responds to user input but also anticipates user needs based on their behavior and preferences, all while ensuring data is managed efficiently both locally and in the cloud. Another development is the growing importance of edge computing. As devices become more powerful, the role of local databases in processing and storing data will expand. This shift will allow for more complex operations to be handled locally, reducing latency, and enhancing the user experience. Firebase and SignalDB can play a crucial role in this transition, offering a seamless sync between the edge and the cloud. Additionally, we can expect to see advancements in the realm of data synchronization and conflict resolution. As apps become more complex and user-generated data increases, the need for more sophisticated sync mechanisms will rise. Firebase and SignalDB will likely adapt to these needs, offering more refined and efficient ways to handle data across multiple devices and users. Finally, with the increasing focus on privacy and security, Firebase and SignalDB will continue to evolve to meet these challenges. This might involve more advanced encryption techniques, enhanced privacy controls, and better compliance tools to adhere to global data protection regulations. In conclusion, the future of app development with Firebase and SignalDB is bright and full of potential. As technology advances, this combination will continue to provide developers with the tools they need to create innovative, responsive, and user-friendly apps, keeping pace with the evolving landscape of mobile technology and user expectations. ## Conclusion As we conclude our exploration of combining Firebase with reactive local databases like SignalDB, it's clear that this integration is more than just a technological advancement; it's a paradigm shift in app development. This synergy of cloud and local database technologies has opened new avenues for creating apps that are not only powerful and scalable but also intuitive and user-centric. Through this journey, we've seen how Firebase's robust cloud capabilities complement the real-time, responsive nature of SignalDB, leading to apps that are fast, reliable, and engaging. Whether it’s real-time data synchronization, enhanced user experience, or improved performance, the combination of Firebase and SignalDB addresses the core needs of modern applications and their users. The practical applications of this technology fusion, as illustrated by various case studies, demonstrate its versatility and efficiency. From gaming to health and fitness, the potential uses are vast and varied, proving that this combination is not just a trend but a staple in the future of app development. Looking forward, the landscape of app development continues to evolve, with emerging trends like AI, edge computing, and enhanced data security shaping its future. In this changing environment, Firebase and SignalDB are set to play a pivotal role, offering developers the tools and flexibility to innovate and adapt, while continuing to provide users with exceptional app experiences. In summary, the fusion of Firebase and reactive local databases like SignalDB represents a significant step forward in the world of app development. It empowers developers to create apps that are not only functionally rich but also a delight to use, setting a new standard for what users expect and what developers can achieve. --- --- url: /supabase.md --- # Offline-First Supabase: Optimistic UI with a Local Database ::: info Short answer The Supabase JavaScript client talks to the server directly and has no built-in offline storage or sync queue. To make a Supabase app work offline and update the UI optimistically, put a local database between your UI and Supabase: the app reads and writes locally, and a sync layer pushes changes to Supabase and pulls updates (for example triggered by Supabase Realtime). This article shows how this works with SignalDB. A runnable example is available in the [Supabase example](https://signaldb.js.org/examples/supabase/). ::: ## Introduction to Supabase As the digital world evolves, the need for robust backend solutions becomes increasingly paramount. Enter **Supabase**, a dynamic Backend-as-a-Service (BaaS) platform, rapidly gaining traction in the realm of web and application development. In this exploration, we delve into the core attributes of Supabase, shedding light on how it’s revolutionizing backend services. At its heart, Supabase is more than just a database. It's a complete toolkit designed to streamline backend development. By offering both database and authentication solutions, it simplifies the often intricate process of app development. Whether you're crafting a new social media platform, an e-commerce site, or a personal project, Supabase stands out as a versatile and efficient choice. What makes Supabase an attractive option for developers? Firstly, its user-friendly interface is a breath of fresh air, especially for those embarking on their development journey. With intuitive design and clear documentation, it breaks down barriers, making sophisticated development accessible to all. Additionally, its compatibility with multiple programming languages, including JavaScript, Python, and Ruby, makes it a flexible tool in a developer's arsenal. One of the crown jewels of Supabase is its *real-time capabilities*. Imagine a chat application where messages appear instantly, or a collaborative tool where changes reflect without a page refresh. This is the magic Supabase brings to the table – a seamless, real-time experience that keeps users engaged. But Supabase doesn’t stop there. Its commitment to security and reliability is evident in its robust authentication mechanisms and high-performance infrastructure. From OAuth integrations to row-level security, Supabase ensures that your data is not only accessible but also secure. In summary, Supabase emerges as a beacon of innovation in the BaaS landscape. Its blend of ease-of-use, real-time data handling, and security features make it an invaluable tool for developers looking to bring their creative visions to life. As we venture further into this article, we will explore how Supabase, in concert with client-side databases like SignalDB, is setting a new standard in real-time data synchronization and user experience. ## Understanding Client-Side Databases In the ever-evolving landscape of web development, the role of client-side databases has become increasingly significant. These databases, residing directly in the user's browser, offer a unique blend of responsiveness and user-specific data management. This section demystifies client-side databases and introduces **SignalDB**, a modern solution that elevates client-side data handling to new heights. Client-side databases are pivotal in creating fast and interactive web applications. They store and manage data within the user's browser, leading to quicker access and a smoother user experience. Unlike traditional server-side databases, client-side databases reduce latency, as data doesn't need to travel over a network to reach the user. This immediacy is crucial in applications where speed and responsiveness are key. Enter SignalDB, a cutting-edge client-side database, renowned for its signals-based reactivity, MongoDB-like interface, and comprehensive TypeScript support. SignalDB represents a paradigm shift in how developers approach data storage and manipulation on the client side. Its signals-based reactivity ensures that changes in the database are instantly reflected in the user interface, providing an interactive and dynamic user experience. The MongoDB-like interface of SignalDB is another feather in its cap. For developers familiar with MongoDB, this means a shorter learning curve and the ability to leverage their existing knowledge. Moreover, TypeScript support in SignalDB ensures type safety and enhances code quality, making it an ideal choice for large-scale and complex applications. In essence, client-side databases like SignalDB are not just storage solutions; they are catalysts for creating more efficient, responsive, and user-centric applications. As we delve deeper into the synergy between client-side databases and Supabase, we'll uncover how they collectively enhance real-time data synchronization, providing a seamless and enriched user experience. ## Real-Time Data Synchronization The digital era we inhabit demands not just connectivity, but instantaneity. This is where real-time data synchronization comes into play, a crucial component in modern applications. In this section, we explore its significance and the challenges it poses, particularly in the context of integrating client-side databases like SignalDB with platforms such as Supabase. Real-time data synchronization is the heartbeat of contemporary applications. Whether it's a social media feed updating instantly with new posts, a collaborative tool reflecting changes in real-time, or a financial app showing live market data, the need for immediate data refresh is undeniable. This immediacy not only enhances user experience but also enables a more dynamic and interactive environment, essential in today's fast-paced digital world. However, achieving seamless real-time data synchronization is not without its hurdles. The primary challenge lies in maintaining data consistency across various users and devices. Ensuring that every user sees the most recent data, especially in collaborative environments, requires meticulous handling of data updates and conflicts. Additionally, network latency and offline scenarios add layers of complexity, demanding sophisticated solutions that can handle these variations gracefully. In this landscape, the integration of client-side databases like SignalDB with backend services like Supabase presents an innovative solution. SignalDB's client-side storage and reactivity combined with Supabase's real-time backend capabilities create a synergistic effect. This combination allows for efficient handling of data updates, reduced server load, and an overall smoother user experience. As we progress, we will see how integrating these technologies not only addresses the challenges of real-time data synchronization but also opens new avenues for building more responsive and user-friendly applications. The fusion of client-side and server-side solutions marks a significant step forward in the quest for real-time, seamless data interactions. ## Integrating Supabase with Local JavaScript Databases Building on the foundation of real-time data synchronization, the integration of Supabase with local JavaScript databases, such as SignalDB, marks a significant leap forward. This section navigates through the steps of this integration and addresses the technical considerations and best practices vital for a successful implementation. The union of Supabase and local JavaScript databases is akin to a symphony where each component plays a vital role. Supabase acts as the conductor, managing data on the server side, while local databases like SignalDB handle the client-side data, ensuring immediate access and reactivity. The integration process involves setting up a seamless data flow between these two components, allowing them to communicate effectively and maintain data integrity across both ends. To begin, developers must establish a connection between Supabase and the client-side database. This involves synchronizing data structures and ensuring that data flows smoothly from the server to the client and vice versa. Techniques such as subscribing to Supabase real-time updates and reflecting these changes in the local database are crucial. Additionally, handling conflict resolution and data validation becomes paramount to preserve data consistency and reliability. Technical considerations include managing offline scenarios. A well-integrated system should be able to store changes locally in SignalDB and then sync these changes back to Supabase once connectivity is restored. Moreover, optimizing the data synchronization process to minimize network usage and enhance performance is essential, especially for applications with a large user base or those operating in bandwidth-constrained environments. Best practices in this integration involve maintaining data security, ensuring efficient error handling, and providing a fallback mechanism for when real-time synchronization faces challenges. It's also important to consider user privacy and data compliance, especially when dealing with sensitive information. In conclusion, integrating Supabase with local JavaScript databases like SignalDB requires a thoughtful approach that balances efficiency, reliability, and user experience. This combination, when executed well, paves the way for applications that are not only fast and responsive but also robust and user-centric. Up next, we delve into the nuances of creating an optimistic UI using Supabase, a key aspect of enhancing user interaction and satisfaction. ## Optimistic UI with Supabase Optimistic UI represents a paradigm shift in user interface design, particularly in applications requiring real-time data interactions. This section delves into the concept of optimistic UI and how the integration of Supabase with client-side databases like SignalDB can significantly enhance this user interface paradigm. At its core, an optimistic UI is a design choice where actions taken by users are immediately reflected in the interface, without waiting for server confirmation. This approach assumes success by default, creating a more fluid and responsive user experience. In scenarios where updates need to travel back and forth between the server and the client, this immediacy becomes a game-changer, making applications feel faster and more intuitive. Supabase, with its real-time backend capabilities, lays the groundwork for implementing an optimistic UI. By swiftly handling data operations on the server side, it allows the UI to update instantly, even before the server has completed processing the request. However, the real magic happens when Supabase is paired with a client-side database like SignalDB. SignalDB’s role in this integration is crucial. It stores changes locally, allowing the UI to update immediately, reflecting the user's actions without any perceptible delay. When combined with Supabase, SignalDB syncs these local changes to the server in the background, ensuring data consistency across the application. This setup not only boosts the application's performance but also significantly improves the user experience by providing immediate feedback and reducing wait times. Implementing an optimistic UI using Supabase and SignalDB requires careful consideration of error handling and data validation. In instances where server-side validation fails or conflicts arise, the system must gracefully inform the user and resolve the discrepancies. This involves designing UI elements that can adapt to such scenarios, ensuring a seamless user journey even when exceptions occur. In summary, the combination of Supabase's real-time backend and SignalDB's client-side reactivity offers a powerful toolkit for creating optimistic UIs. This integration empowers developers to build applications that are not only fast and responsive but also intuitive and user-friendly. The next section will explore the specifics of combining Supabase with SignalDB, further highlighting the benefits of this collaboration. ## Combining Supabase with SignalDB The integration of Supabase with SignalDB marks a significant advancement in the development of dynamic and responsive applications. This section provides a detailed exploration of how these two powerful technologies can be combined, the potential use cases they unlock, and the future developments they herald. Supabase and SignalDB, when integrated, offer a harmonious blend of server-side efficiency and client-side reactivity. Supabase serves as a robust backend, managing data storage, authentication, and real-time updates. On the other hand, SignalDB operates on the client-side, offering signals-based reactivity and a MongoDB-like interface, which makes working with data intuitive and efficient. The process of integrating Supabase with SignalDB involves establishing a bidirectional data flow. Changes made in the SignalDB database are reflected in Supabase in real-time, and vice versa. This ensures that data across both platforms is synchronized, providing a consistent and reliable data source for the application. The integration leverages Supabase's real-time capabilities to listen for changes in the database and update the client-side database accordingly. Use cases for this integration are vast and varied. In collaborative applications like online editors or project management tools, this integration allows multiple users to see changes instantaneously, fostering a collaborative and efficient working environment. E-commerce platforms can benefit from real-time inventory updates, enhancing the shopping experience for users. Looking ahead, the combination of Supabase and SignalDB is set to evolve further. We anticipate enhancements in areas such as offline data synchronization, more advanced conflict resolution strategies, and even tighter integration with frontend frameworks. These developments will continue to push the boundaries of what is possible in web and application development, offering more robust, scalable, and user-friendly solutions. In conclusion, the fusion of Supabase and SignalDB is more than just a technical integration; it's a step towards a future where applications are more interactive, responsive, and tailored to the needs of users. As we wrap up this discussion, the final section will summarize the benefits of this powerful combination and reflect on the future of real-time data synchronization in the world of web development. ## Conclusion As we conclude our exploration into the synergistic integration of Supabase with client-side databases like SignalDB, it’s evident that this combination is a game-changer in the realm of web development. This closing section summarizes the key benefits of this integration and casts a vision for the future of real-time data synchronization. The amalgamation of Supabase and SignalDB brings forth a new era of web applications that are not only faster and more efficient but also highly responsive to user interactions. Supabase’s robust backend capabilities, coupled with SignalDB’s client-side reactivity and ease of use, create a seamless experience for both developers and end-users. The resulting applications are quicker to respond, more reliable in terms of data synchronization, and offer a more intuitive and engaging user experience. One of the most significant advantages of this integration is the ability to build applications with an optimistic UI, where user actions are instantly reflected, enhancing the overall user interaction. This approach reduces perceived latency, a crucial factor in user satisfaction and engagement. Furthermore, the combination of these technologies addresses common challenges in real-time data synchronization, such as handling offline scenarios, conflict resolution, and ensuring data consistency across different devices and user sessions. Looking to the future, the landscape of web development is set to be further revolutionized by this integration. We can expect continued advancements in the efficiency of data synchronization, improvements in handling complex data structures, and more intuitive interfaces for developers. As these technologies evolve, they will undoubtedly open new possibilities for creating even more sophisticated and user-centric applications. In conclusion, the integration of Supabase with client-side databases like SignalDB is a significant stride forward in web development. It empowers developers to build applications that are not only technically advanced but also deeply attuned to the needs of the modern user. As we embrace this integration, the future of real-time data synchronization in web applications looks brighter than ever, promising a landscape rich with innovation, efficiency, and unparalleled user experiences. --- --- url: /reference/core/collection.md --- # Collection ```ts import { Collection } from '@signaldb/core' ``` The Collection class is designed to manage and manipulate collections of data, with options for reactivity, transformations and a [data adapter](/data-persistence/) that decides where the data operations actually happen. Collections are schemaless, meaning that you don't need to define a schema for your data before you start using it. This allows you to store any data you want without worrying about defining a schema first. However, it's recommended that you define a typescript interface for the documents in the collection, so that you can benefit from type safety when working with the data. ## Static Methods ### `setFieldTracking(enable: boolean)` Enables or disables field tracking for all collections. See [Field-Level Reactivity](/queries/#field-level-reactivity) for more information. ### `batch(collections?: Collection[], callback: () => void | Promise)` If you need to execute many operations at once in multiple collections, you can use the global `Collection.batch()` method. It runs the callback inside the [instance `batch()`](#batch-callback-void) of each collection, so their live queries are updated once when the batch ends instead of after every write. It returns a promise if the callback does. Pass the collections you are writing to — see the [instance method](#batch-callback-void) for why that matters. ### `getCollections()` Returns an array of all collections that have been created. ### `onCreation(callback: (collection: Collection) => void)` Registers a callback that will be called whenever a new collection is created. The callback will receive the newly created collection as an argument. ### `onDispose(callback: (collection: Collection) => void)` Registers a callback that will be called whenever a collection is disposed. The callback will receive the disposed collection as an argument. ### `enableDebugMode()` Enables debug mode for all collections. This will enable measurements for query timings and other debug information. It also switches on `reportLargeQueries()` at 500 rows. ### `reportLargeQueries(rows: number | null)` Reports each live query holding more than `rows` rows once, together with the stack that registered it. Pass `null` to switch it off again. ```js Collection.reportLargeQueries(500) ``` A reactive query registered from a long-lived place — a module scope, a store, a component that is never unmounted — keeps its cost for the lifetime of the application, and there is otherwise nothing to see: the query works, and its price only shows up much later as an application that has grown slow. This is how you find it. ## Constructor ```js const collection = new Collection(name: string, dataAdapter: DataAdapter, options?: CollectionOptions) ``` Constructs a new Collection object. The name identifies the collection — to its data adapter, which uses it to find the collection's storage, and in the developer tools. Parameters * `name`: The name of the collection. * `dataAdapter`: The [DataAdapter](/reference/core/dataadapter/) that answers this collection's data operations. One data adapter usually serves every collection of an application. * `options` (Optional): An object specifying various options for the collection. Options include: * reactivity: A [ReactivityAdapter](/reactivity/) for enabling reactivity. * transform: A transformation function to be applied to items. The document that should be transformed is passed as the only parameter. The function should return the transformed document (e.g. `(doc: T) => U`) * transformAll: A function that receives all items of a query result at once and returns the transformed list. Useful for resolving relations without an N+1 query — see [ORM](/orm/). An `async: true` read calls it with `{ async: true }` as a third argument and awaits a promise returned for it; build it with [`reactiveOrAsync`](/reference/core/utilities/#reactiveorasync-generator-and-unwrap-value) to read related collections the same way the query is read. * indices: An array of field names to index, e.g. `['authorId', 'status']`. * primaryKeyGenerator: A function that generates a unique ID for the item. If not provided, a default generator will be used. * fieldTracking: Enables [field-level reactivity](/queries/#field-level-reactivity) for this collection. Defaults to the value set with the static [`setFieldTracking()`](#setfieldtracking-enable-boolean). * enableDebugMode: Enables debug mode for this collection. Defaults to `true` once the static [`enableDebugMode()`](#enabledebugmode) was called. A collection can also be constructed with options alone (`new Collection(options?)`), in which case it uses a `DefaultDataAdapter` of its own. That form still accepts the deprecated `name` option and the deprecated `persistence` option — a storage adapter, which is then passed to that `DefaultDataAdapter`. Without `persistence`, the data is kept in memory only. Prefer the `new Collection(name, dataAdapter, options?)` form. ## Methods ### `ready()` Resolves when the storage adapter finished initializing and the collection is ready to be used. This is useful when you need to wait for the collection to be ready before executing any operations directly after creating it. Example: ```ts const collection = new Collection('items', dataAdapter) await collection.ready() await collection.insert({ name: 'Item 1' }) // ... ``` ### `isReady()` ⚡️ this function is reactive! Returns whether the collection is ready, as a reactive value. Use this where you want to render something while the collection is still initializing; use [`ready()`](#ready) where you want to wait for it. ```ts const collection = new Collection('items', dataAdapter) effect(() => { if (!collection.isReady()) return console.log(collection.find().fetch()) }) ``` ### `find(selector?: Selector, options?: Options)` Returns a new [cursor object](/reference/core/cursor/) for the items in the collection that match a given selector and options. Also check out the [queries section](/queries/). Parameters * `selector` (Optional): A [selector](/queries/#selectors) object describing the items to match. Omit it to match all items. * `options` (Optional): Options for the cursor — `sort`, `skip`, `limit`, `fields`, `reactive`, `fieldTracking`, and `async`. Pass `async: true` to get a cursor whose methods resolve to their result instead of returning it. That is what you want outside a reactive scope when the data adapter cannot answer on the spot — see [queries that are not answered immediately](/queries/#queries-that-are-not-answered-immediately). ```js const posts = await collection.find({ status: 'published' }, { async: true }).fetch() ``` ### `findOne(selector: Selector, options?: Options)` Behaves the same like [`.find()`](#find-selector-selector-t-options-options) but doesn't return a cursor. Instead it will directly return the first found document, or `undefined`. The selector is required; pass `{}` to match any document. With `async: true` it returns a promise resolving to that document. ### Loading state Three reactive methods report what the collection is currently doing. All of them register a dependency in a reactive scope. * `isLoading()`: ⚡️ reactive — whether `isPulling()` or `isPushing()` is `true`. Initially `false`. * `isPulling()`: ⚡️ reactive — whether a `find(…, { async: true })` query is currently running. * `isPushing()`: ⚡️ reactive — whether a write is currently running. None of them describes the initial load from storage: use [`ready()`](#ready) or [`isReady()`](#isready) for that. Whether a single query has been answered yet is told by [`Cursor#isLoading()`](/reference/core/cursor/#⚡️-isloading-reactive). ### `insert(item: Omit & Partial>)` Inserts an item into the collection and returns a promise resolving to the ID of the newly inserted item. Also check out the [data manipulation section](/data-manipulation/). ### `insertMany(items: Array & Partial>>)` Inserts multiple items into the collection and returns a promise resolving to the IDs of the newly inserted items. Parameters * `items`: The items to be inserted into the collection. ### `updateMany(selector: Selector, modifier: Modifier, options?: { upsert?: boolean })` Updates multiple items in the collection that match a given selector with the specified modifier and returns a promise resolving to the number of updated items. Also check out the [data manipulation section](/data-manipulation/). Parameters * `selector`: A [selector](/queries/#selectors) object describing the items to match. * `modifier`: An object describing how to modify the matching items. * `options`: An object with additional options. Currently only `upsert` is supported, which will insert a document based on the modifier, if the selector doesn't match any documents. ### `updateOne(selector: Selector, modifier: Modifier, options?: { upsert?: boolean })` Behaves the same like `.updateMany()` but only updates the first found document. ### `replaceOne(selector: Selector, replacement: Omit & Partial>, options?: { upsert?: boolean })` Replaces a single item in the collection that matches a given selector with the specified replacement and returns a promise resolving to `0` or `1`. Also check out the [data manipulation section](/data-manipulation/). Parameters * `selector`: A [selector](/queries/#selectors) object describing the items to match. * `replacement`: The new item that should replace the existing one. * `options`: An object with additional options. Currently only `upsert` is supported, which will insert a document based on the replacement, if the selector doesn't match any documents. ### `removeMany(selector: Selector)` Removes multiple items from the collection that match a given selector and returns a promise resolving to the number of removed items. Parameters * `selector`: A [selector](/queries/#selectors) object describing the items to match. ### `removeOne(selector: Selector)` Behaves the same like `.removeMany()` but only removes the first found document. ### `batch(callback: () => void)` If you need to execute many operations at once, things can get slow because every write updates the collection's live queries. To prevent this, you can use the `.batch()` method: the live queries of this collection are updated once, when the callback has finished, instead of after every write. It returns a promise if the callback does. A batch is not a transaction — writes that succeeded before a failing one are not rolled back. ```js await collection.batch(async () => { await collection.insert({ name: 'Item 1' }) await collection.insert({ name: 'Item 2' }) // … }) ``` If the writes span several collections, pass them to the static `Collection.batch()`: ```js await Collection.batch([posts, authors], async () => { await posts.insert({ title: 'Foo', authorId: 'a1' }) await authors.updateOne({ id: 'a1' }, { $inc: { postCount: 1 } }) }) ``` ::: warning `Collection.batch()` **without** a list of collections batches *every* collection in the process and defers every live query everywhere until the batch ends. That is the right thing for a handful of writes belonging to one event, and the wrong thing around anything whose length depends on the data. Name the collections you are actually writing to. ::: ::: tip For an operation that spans `await`s — a write, then whatever derives from it — reach for [`reactiveTransaction`](/reference/core/reactivetransaction/) instead. It holds only the notification of reactive scopes, not the query pipeline, so it is safe to keep open for as long as the operation takes, and every scope updates once at the end rather than once per phase. ::: ### `isBatchOperationInProgress()` Returns whether this collection is currently batching: during its own [`batch()`](#batch-callback-void), during a scoped `Collection.batch([...])` that names it, and during an unscoped `Collection.batch()` covering every collection. A batch scoped to other collections does not affect it. ### `dispose()` Disposes the collection and all its resources and returns a promise that resolves when that is done. It tears down the collection's storage through its data adapter, removes all event listeners and cleans up all internal data structures. A disposed collection throws when it is used afterwards. ### `getDebugMode()` / `setDebugMode(enable: boolean)` Reads or changes whether debug mode is enabled for this collection. In debug mode, the collection measures its queries and emits additional events for the [developer tools](/devtools/). ### `name` The name the collection was created with. ### `setFieldTracking(enabled: boolean)` Enables or disables field tracking for the collection. See [Field-Level Reactivity](/queries/#field-level-reactivity) for more information. ## Events The Collection class is equipped with a set of events that provide insights into the state and changes within the collection. Subscribe with `on(event, listener)`, unsubscribe with `off(event, listener)`, or use `once(event, listener)` for a single call: ```ts const onChanged = (item, modifier, previousItem) => { console.log('changed', item.id, previousItem, '→', item) } collection.on('changed', onChanged) // … collection.off('changed', onChanged) ``` Here is an overview of the events: * `added`: Triggered when a new item is added to the collection. The event handler receives the added item as an argument. * `changed`: Fired when an existing item in the collection undergoes modification. The event handler receives the modified item, the modifier that was applied and — when the data adapter reports it — the item as it was before the modification. All data adapters shipped with SignalDB report it; a custom one that does not simply omits the third argument. * `removed`: Signaled when an item is removed or deleted from the collection. The event handler receives the removed item. * `validate`: Emitted when an item should be validated. The event handler receives the item as an argument. Validate the item inside of the event handler and throw an error if the item is invalid. This will prevent the item from being inserted or updated. In addition to that, the collection will fire events for each executed method. For example, if you call `.updateOne()`, the collection will fire an `updateOne` event. The event handler will receive the selector and the modifier as arguments. * `find`: Emitted when the `find` method is called. The event handler receives the selector, options and the cursor as arguments. * `findOne`: Triggered when the `findOne` method is called. The event handler receives the selector, options and the returned item as arguments. * `insert`: Fired when the `insert` method is called. The event handler receives the inserted item as an argument. * `updateMany`: Emitted when the `updateMany` method is called. The event handler receives the selector and the modifier as arguments. * `updateOne`: Triggered when the `updateOne` method is called. The event handler receives the selector and the modifier as arguments. * `replaceOne`: Emitted when the `replaceOne` method is called. The event handler receives the selector and the replacement as arguments. * `removeMany`: Emitted when the `removeMany` method is called. The event handler receives the selector as an argument. * `removeOne`: Triggered when the `removeOne` method is called. The event handler receives the selector as an argument. In addition to these, there are events about the queries a collection is serving: * `query.error`: A query backing at least one live cursor failed and will not deliver results. The event handler receives the error, the selector and the options. This event matters more than it looks: a cursor whose query failed keeps returning its neutral empty result, which is indistinguishable from a query that legitimately matched nothing. Listening here is the only way to tell the two apart. * `observer.created`: A live query was registered. The event handler receives the selector and options. * `observer.disposed`: A live query was given up. The event handler receives the selector and options. * `getItems`: Items were read for a selector. The event handler receives the selector. ::: warning Removed in v2 The `persistence.*` events no longer exist. Use [`ready()`](#ready) / [`isReady()`](#isready) for the initial load, `Cursor#isLoading()` for a single query, the promise a write returns for its completion or failure, and the data adapter's `onError` option and `query.error` for other failures. See the [upgrade guide](/upgrade/v2/#event-changes). ::: These events empower developers to build dynamic and responsive applications by reacting to changes in the collection and facilitating synchronization with external data sources. --- --- url: /reference/core/cursor.md --- # Cursor Cursors are a concept that appears in many database systems and are used to iterate over and access data in a controlled manner. A cursor in SignalDB is a pointer to a specific set of rows. It provides an interface to interact with items while offering capabilities like reactivity, transformation, observation of changes, and more. You don't have to create a cursor by yourself. SignalDB is handling that for you and returns the cursor from a [`.find()` call](/reference/core/collection/#find-selector-selector-t-options-options). A cursor created with `find(selector, { async: true })` is an *async cursor*: `forEach()`, `map()`, `fetch()` and `count()` return a promise resolving to their result instead of the result itself, and they register no reactive dependency. See [awaiting the result](/queries/#awaiting-the-result). The following methods are available in the cursor class: ## ⚡️ `forEach(callback: (item: TransformedItem) => void)` *(reactive)* Iterates over each item in the cursor, applying the given callback function. * Parameters: * `callback`: A function that gets executed for each item. * Returns * Nothing (a promise resolving when all items were visited on an async cursor) ::: tip Reactive ⚡️ This method is reactive, so it will rerun automatically when a document is added, removed, or when any of its fields change. You can control when it reruns by using the `fields` option in the `.find()` method to specify which fields to track. Reactivity will only be triggered by changes in the fields you choose. ::: ## ⚡️ `map (callback: (item: TransformedItem) => T)` *(reactive)* Maps each item in the cursor to a new array using the provided callback function. * Parameters: * `callback`: A function that transforms each item. * Returns * An array of transformed items (a promise resolving to it on an async cursor) ::: tip Reactive ⚡️ This method is reactive, so it will rerun automatically when a document is added, removed, or when any of its fields change. You can control when it reruns by using the `fields` option in the `.find()` method to specify which fields to track. Reactivity will only be triggered by changes in the fields you choose. ::: ## ⚡️ `fetch()` *(reactive)* Fetches all the items in the cursor and returns them. * Returns * An array of items (a promise resolving to it on an async cursor) ::: tip Reactive ⚡️ This method is reactive, so it will rerun automatically when a document is added, removed, or when any of its fields change. You can control when it reruns by using the `fields` option in the `.find()` method to specify which fields to track. Reactivity will only be triggered by changes in the fields you choose. ::: ## ⚡️ `count()` *(reactive)* Counts the number of items in the cursor. * Returns * The count of items (a promise resolving to it on an async cursor) ::: tip Reactive ⚡️ This method is reactive, so it will rerun automatically when a document was added or removed from the query. ::: ## ⚡️ `isLoading()` *(reactive)* Reports whether the query behind this cursor has produced an outcome yet. * Returns * `true` while the query has not been answered, `false` once it has completed or failed This is the only thing that tells "still loading" apart from "nothing matched". A query that has not been answered yet publishes a **neutral** result — an empty array from `fetch()`, a zero from `count()` — and that result is indistinguishable from a real one, because empty is a legitimate answer. ```js const cursor = Posts.find({ status: 'published' }) effect(() => { if (cursor.isLoading()) return renderSpinner() renderPosts(cursor.fetch()) }) ``` Whether it is ever `true` depends on the [data adapter](/data-adapters/). With the [`DefaultDataAdapter`](/reference/core/defaultdataadapter/) queries are answered from memory, so it is `false` once the collection is ready. With the [async](/reference/core/asyncdataadapter/), [worker](/reference/core/workerdataadapter/) and [auto-fetch](/reference/core/autofetchdataadapter/) adapters there is a real window in which it is `true`. It is always `false` on an `{ async: true }` cursor, whose `fetch()` awaits the real result anyway — see [awaiting the result](/queries/#awaiting-the-result). On a collection whose [`transformAll`](/orm/#solving-the-n-1-problem-with-transformall) reads other collections, the first result also waits for the queries `transformAll` made, so a list is not reported as loaded while the data it is enriched with is still missing. It reports "no result yet", not "an execution is in flight". A write that re-runs an already-settled query does not flip it back to `true`, so a list does not fall into a loading state every time one of its rows changes. A query that *failed* counts as settled — `isLoading()` returns `false` and the cursor keeps serving its empty result, because a loading state that never ends is the worse answer. Listen for the collection's [`query.error`](/reference/core/collection/#events) event to catch that case. ::: tip Reactive ⚡️ This method is reactive, so it reruns automatically when the query's state changes. ::: ## `observeChanges(callbacks: ObserveCallbacks, skipInitial = false)` This method allows observation of changes in the cursor items. It uses callbacks to notify of different events like addition, removal, changes, etc. * Parameters * `callbacks`: An object of Callback functions for different observation events. * `added(item: T)`gets called when a new item was added to the cursor * `addedBefore(item: T, before: T)`gets called when a new item was added to the cursor and also indicates the position of the new item * `changed(item: T, previousItem: T)` gets called when an item in the cursor was changed, with the item as it was before the change * `changedField(item: T, field: keyof T, oldValue, newValue)` gets called once for every top-level field whose value differs between the previous and the new version of a changed item * `movedBefore(item: T, before: T)`gets called when an item moved its position in the cursor. Only the items that have to move are reported: reordering a list can leave several items at a different index while a single move produces that order, and it is that single move you are told about. * `removed(item: T)`gets called when an item was removed from the cursor * `skipInitial`: A boolean to decide whether to skip the initial observation event. * Returns * A function that, when called, stops observing the changes. ## `requery()` Re-queries the cursor to fetch items and check observers for any changes. ## `applyDelta(delta: QueryDelta)` Brings the cursor up to date from a description of what changed, rather than by re-running the query and comparing the result with the previous one. * Parameters * `delta`: The change, as described by [`QueryDelta`](/reference/core/dataadapter/#querydelta) Falls back to `requery()` when the delta does not fit the result the cursor currently holds, so a caller never has to decide which of the two is safe. The delta has to be relative to the cursor's current result — see [the delta contract](/reference/core/dataadapter/#the-delta-contract). You rarely call this yourself. It exists for integrations that receive deltas from a data adapter and want to avoid the comparison a `requery()` would cost. ## `onCleanup(callback: () => void)` Registers a function to run when the cursor is cleaned up. * Parameters * `callback`: The function to run ## `cleanup()` The cleanup method is used to invoke all the cleanup callbacks. This helps in managing resources and ensuring efficient garbage collection. You have to call this method, if you're using a reactivity adapter, that doesn't support automatic cleanup. ## Constructing a cursor yourself ```ts import { Cursor } from '@signaldb/core' import type { CursorOptions, QueryStateAccessor } from '@signaldb/core' const cursor = new Cursor(getItems, options) ``` This is for integrations that serve a cursor from a data source of their own; an application gets its cursors from [`find()`](/reference/core/collection/#find-selector-selector-t-options-options). * `getItems`: A function returning the current items — or, for an async cursor, a promise resolving to them. * `options` (`CursorOptions`, optional): The [find options](/queries/#options) (`sort`, `skip`, `limit`, `fields`, `reactive`, `fieldTracking`, `async`) plus: * `transform`: Applied to every item the cursor returns. * `bindEvents(requery, applyDelta)`: Called when the cursor starts observing its source, with the functions that update it. Returns the function that stops observing. * `queryState` (`QueryStateAccessor`): Backs [`isLoading()`](#⚡️-isloading-reactive). Without it, the cursor never reports itself as loading. ```ts interface QueryStateAccessor { // whether the query has completed or failed at least once since it was registered hasSettled: () => boolean // subscribes to the query settling; returns a cleanup function onSettled: (callback: () => void) => () => void } ``` --- --- url: /reference/core/reactivetransaction.md --- # reactiveTransaction ```ts import { reactiveTransaction } from '@signaldb/core' ``` Runs a callback as one **reactive transaction**: every reactive scope that would have been notified while it runs is notified once, after it ends. ```js await reactiveTransaction(async () => { await applyCatch() // writes the log rows await runFollower() // derives the counts from them }) // → every screen reading either of them updates once, here ``` Without it, an operation made of several phases wakes its readers once per phase. The user did one thing; the screen re-rendered three times. ## How it differs from `batch` `Collection.batch()` defers the **query pipeline**: while it is open, no cursor requeries at all. That makes it right for a handful of writes issued together, and wrong for anything longer — it has to stay synchronous and short, because everything reading a collection is frozen for its duration. `reactiveTransaction` holds only the last step, the notification of reactive scopes. Queries keep running, results stay current, observers keep diffing; what waits is the wake-up. | | `Collection.batch()` | `reactiveTransaction()` | | --- | --- | --- | | Defers | requeries *and* notifications | notifications only | | Reads inside it | serve the value from before the batch | current | | May span `await`s | no, in practice — everything is frozen meanwhile | yes, that is the point | | Nesting | passthrough: the inner one is a no-op | joins the outer one | | Right for | writes issued together, in one tick | an operation with phases | They compose: a transaction may contain several batches, which is what a real pipeline looks like. ## Behaviour * **Nesting joins.** An inner transaction does not flush; the outermost one does. A pipeline can open one without knowing whether its caller already did. * **Overlap holds.** While *any* transaction is open, notifications are held, and they are flushed when the last one ends. A scope may be woken later than its own transaction ended, never earlier. * **A throw still flushes.** Whatever was written before the failure is real, so its readers are notified. A transaction that swallowed its notifications on failure would leave a screen showing state that is no longer in the database. * **Once per scope.** A transaction that touched one query fifty times wakes it once. * **A disposed query is not woken.** A cursor cleaned up while a transaction is open is dropped from it. * **Synchronous in, synchronous out.** A synchronous callback returns its value directly and flushes before returning. ## `isInReactiveTransaction()` ```ts import { isInReactiveTransaction } from '@signaldb/core' ``` Returns whether a reactive transaction is currently open. Useful for diagnostics and for code that wants to behave differently while notifications are held. ::: warning A transaction that never settles holds notifications for the rest of the process: nothing reactive updates again. Keep the callback's promise on a path that always resolves or rejects. ::: --- --- url: /reference/core/dataadapter.md --- # DataAdapter ```ts import type { DataAdapter, CollectionBackend, QueryOptions, StateChangeCallback, QueryDelta, WriteResult, DetailedWriteResult, } from '@signaldb/core' ``` The interface a [data adapter](/data-adapters/) implements. See the [data adapters](/data-adapters/) chapter for what an adapter is and which of the built-in ones to pick. ## `DataAdapter` ```ts interface DataAdapter { createCollectionBackend( collection: Collection, indices: string[], ): CollectionBackend } ``` Called once per collection. `indices` are the field names the collection was constructed with; an adapter that cannot use indices may ignore them. ## `CollectionBackend` The object that answers everything for one collection. ### Writes ```ts insert(item: T): Promise updateOne(selector: Selector, modifier: Modifier): Promise> updateMany(selector: Selector, modifier: Modifier): Promise> replaceOne(selector: Selector, replacement: Omit & Partial>): Promise> removeOne(selector: Selector): Promise removeMany(selector: Selector): Promise ``` Each resolves to the items it affected. An empty result means nothing matched — which is what turns an upsert into an insert, so it has to be accurate. The three updating writes resolve to a `WriteResult`: ```ts type WriteResult = T[] | { items: T[], previousItems: T[] } ``` Returning the items on their own is still valid, so an existing adapter keeps compiling and behaving as before. An adapter that also knows what the items looked like *before* the write returns the object form instead, and the collection's `'changed'` event then carries that previous state as its third argument. `previousItems[n]` is what `items[n]` was before the write, so an adapter that reports it reports it for every item it changed. ### Queries ```ts registerQuery>(selector: Selector, options: O): void unregisterQuery>(selector: Selector, options: O): void retryQuery?>(selector: Selector, options: O): void getQueryState>(selector: Selector, options: O): 'active' | 'complete' | 'error' getQueryError>(selector: Selector, options: O): Error | null getQueryResult>(selector: Selector, options: O): T[] executeQuery>(selector: Selector, options: O): Promise onQueryStateChange>( selector: Selector, options: O, callback: StateChangeCallback, ): () => void ``` `registerQuery` starts a live query; the returned function of `onQueryStateChange` unsubscribes. `getQueryResult` is synchronous and must always return something — see [the neutral result](#the-neutral-result) below. `retryQuery` is optional so that existing custom adapters keep compiling, and the `Collection` never calls it — it is there for code that holds a backend and wants to re-run a failed query on demand. The `AsyncDataAdapter` implements it and also retries a failed query by itself when a new observer subscribes to it. An adapter that never surfaces an `'error'` state has nothing to implement. ### Lifecycle ```ts dispose(): Promise isReady(): Promise ``` ## `QueryOptions` ```ts interface QueryOptions { sort?: SortSpecifier skip?: number limit?: number fields?: FieldSpecifier } ``` ## `StateChangeCallback` ```ts type StateChangeCallback = ( state: 'active' | 'complete' | 'error', delta?: QueryDelta, ) => void ``` The second argument is optional and only ever accompanies `'complete'`. An adapter that can describe the change passes it; one that cannot omits it, and its listeners fall back to comparing the whole result against the previous one. ## `QueryDelta` ```ts interface QueryDelta { /** Items that were not in the previous result, at their position in the new one. */ added: { index: number, item: T }[] /** Items that were in the previous result and whose contents changed. */ changed: T[] /** Ids of items that are no longer in the result. */ removed: any[] /** Items that stayed, at their new position, because the order around them changed. */ moved: { index: number, id: any }[] /** Length of the resulting array. */ resultCount: number } ``` `resultCount` lets a recipient verify it applied the delta to the result it was computed against. A recipient whose own length disagrees falls back to re-reading the query rather than serving a result it cannot trust. ## What a custom adapter has to uphold ### The neutral result A query that has not been answered yet publishes an empty list, and that empty list is indistinguishable from a real one — because empty is a legitimate answer. `getQueryState` is the only thing that tells the two apart, and [`Cursor#isLoading()`](/reference/core/cursor/) is how a consumer sees it. Two consequences. Publish `'complete'` only once you actually have the answer, not when you start looking for it. And if your adapter can fail, publish `'error'` and record the reason in `getQueryError` — a query left sitting on its neutral value is a consumer staring at an empty screen with nothing to tell them why. ### The delta contract A delta is only ever passed when it is relative to what `getQueryResult` returned the last time it was asked. If your adapter layers anything on top of its stored result — an optimistic write still in flight, for instance — it must omit the delta for as long as it does, because the listener's last result included that layer and your delta does not describe it. A wrong delta is worse than no delta. Omitting it costs the listener one comparison; getting it wrong desynchronises them silently and permanently. ### Cost The cost of a write should scale with the size of the *change*, not with the size of the data or of the results on screen. That is what the delta is for. An adapter that answers every write by re-running each affected query and diffing the results works correctly and gets slower the more the application shows. For an adapter across a serialization boundary — a worker, a socket — the message *size* is a cost paid on the consumer's thread even though the work behind it is not. Send deltas rather than results. --- --- url: /reference/core/defaultdataadapter.md --- # DefaultDataAdapter ```ts import { DefaultDataAdapter } from '@signaldb/core' ``` Keeps every collection in memory on the main thread and answers queries from there. Writes are applied immediately and persisted in the background, which is what makes an [optimistic UI](/optimistic-ui/) fall out for free. This is the adapter to use unless you have a reason not to, and the one a collection constructed without an adapter uses. ## Usage ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import createLocalStorageAdapter from '@signaldb/localstorage' const dataAdapter = new DefaultDataAdapter({ storage: name => createLocalStorageAdapter(name), }) const Posts = new Collection('posts', dataAdapter) const Authors = new Collection('authors', dataAdapter) ``` Without a `storage` function the data lives only in memory and is gone on reload — useful for tests and for data you derive rather than keep. ## Options ```ts new DefaultDataAdapter(options?: { storage?: (name: string) => StorageAdapter | undefined onError?: (name: string, error: Error) => void }) ``` * `storage`: Called once per collection with the collection's name, and returns the [storage adapter](/data-persistence/) that collection persists to. Return `undefined` to keep a particular collection in memory only. * `onError`: Called when setting up a collection's storage adapter or loading its stored items fails; without it, the error is logged with `console.error`. The collection's `ready()` then rejects with the same error and `isReady()` stays `false`, while the collection keeps working in memory. A write whose storage operation fails rejects its own promise instead. ## Queries are synchronous Because the data is in memory, `find().fetch()` returns the result directly and `Cursor#isLoading()` is never `true` after the collection is ready. Waiting for [`collection.ready()`](/reference/core/collection/#ready) is still necessary before the first read: until the storage adapter has loaded, the collection is empty, and an empty result is indistinguishable from a real one. ## Indices The `indices` a collection declares are used here. A selector no index covers is answered by scanning the collection in memory — fine while it is small, and the thing to fix when it grows. See [what this means for your collections](/data-persistence/#what-this-means-for-your-collections). --- --- url: /reference/core/asyncdataadapter.md --- # AsyncDataAdapter ```ts import { AsyncDataAdapter } from '@signaldb/core' ``` Answers every query by going to the [storage adapter](/data-persistence/), without holding the collection in memory. Use it when the data does not fit in memory, or when something other than this process can change the underlying storage and you need the answer to reflect that. ## Usage ```js import { Collection, AsyncDataAdapter } from '@signaldb/core' import createFilesystemAdapter from '@signaldb/fs' const dataAdapter = new AsyncDataAdapter({ storage: name => createFilesystemAdapter(`./data/${name}`), }) const Posts = new Collection('posts', dataAdapter) ``` ## Options ```ts new AsyncDataAdapter(options: { storage: (name: string) => StorageAdapter id?: string onError?: (error: Error) => void retry?: { attempts?: number delay?: (attempt: number) => number } }) ``` * `storage`: Called once per collection with the collection's name, and returns the storage adapter it reads from. Required — an async adapter with nothing to read from has nothing to do. * `id`: A logical name, handy when several adapters run side by side. * `onError`: Called with errors the adapter cannot hand to a caller: a storage adapter that fails to set up, and a live query that still fails after all `retry` attempts (as a `QueryError` naming the collection, selector and attempts; the query is also reported through the collection's `query.error` event). Defaults to `console.error`. * `retry.attempts`: Total attempts for a failing query, including the first. Default `3`. * `retry.delay`: Delay in milliseconds before attempt N+1. Default `100 * 4 ** (attempt - 1)`. ## Queries are asynchronous A query is not answered the moment you ask for it, which changes two things. Until it is answered, the cursor returns its neutral result — an empty list, a count of zero — and that is indistinguishable from a query that legitimately matched nothing. Use [`Cursor#isLoading()`](/reference/core/cursor/) to tell the two apart: ```js const cursor = Posts.find({ status: 'published' }) effect(() => { if (cursor.isLoading()) return renderSpinner() renderPosts(cursor.fetch()) }) ``` And a query can fail. That is what `retry` is for: a query that fails is otherwise a dead end for the rest of the session, because cursors only requery on completion and would keep serving that neutral empty value. After the attempts are used up the query is published as failed, which reaches the collection's [`query.error`](/reference/core/collection/#events) event. ## Indices Only the fields a collection declares as `indices` can narrow a query down before it reaches storage. This matters more here than with the [`DefaultDataAdapter`](/reference/core/defaultdataadapter/): an unindexed selector means reading the whole collection out of storage on every query, not just scanning an array already in memory. --- --- url: /reference/core/workerdataadapter.md --- # WorkerDataAdapter ```ts import { WorkerDataAdapter, WorkerDataAdapterHost } from '@signaldb/core' ``` Runs the data layer in a web worker. The two halves are a pair: * **`WorkerDataAdapterHost`** lives inside the worker. It owns the storage adapters and does the actual querying and writing. * **`WorkerDataAdapter`** lives on the main thread. It is the `DataAdapter` your collections are constructed with, and it forwards everything to the host. Use it when queries or writes are large enough that doing them on the main thread costs you frames. ## Usage Inside the worker: ```js // data-worker.js import { WorkerDataAdapterHost } from '@signaldb/core' import createIndexedDBAdapter from '@signaldb/indexeddb' new WorkerDataAdapterHost(self, { id: 'app-data', storage: createIndexedDBAdapter({ databaseName: 'my-app', version: 1, schema: { posts: ['authorId'] }, }), }) ``` On the main thread: ```js import { Collection, WorkerDataAdapter } from '@signaldb/core' const worker = new Worker(new URL('./data-worker.js', import.meta.url), { type: 'module', }) const dataAdapter = new WorkerDataAdapter(worker, { id: 'app-data' }) const Posts = new Collection('posts', dataAdapter, { indices: ['authorId'], }) ``` The `id` on both sides must match — it is how messages are routed when several adapters share a worker or several workers share a page. Both sides default to `'default-worker-data-adapter'`, so a single pair works without one. ## `WorkerDataAdapter` ```ts new WorkerDataAdapter(worker: WorkerDataAdapterEndpoint, options: { id?: string log?: (message: string, ...args: any[]) => void }) ``` `WorkerDataAdapterEndpoint` is the part of the `Worker` interface this adapter uses, so anything with the same shape works — a `MessagePort`, a `SharedWorker`'s port, or a stub in a test: ```ts interface WorkerDataAdapterEndpoint { addEventListener: (type: 'message', listener: (event: MessageEvent) => void) => void removeEventListener: (type: 'message', listener: (event: MessageEvent) => void) => void postMessage: (message: unknown) => void terminate?: () => void } ``` The adapter waits for the host to announce itself. If no `WorkerDataAdapterHost` with the same `id` answers within 5 seconds — the worker failed to load, or the ids differ — initialization fails with `WorkerDataAdapter initialization timed out`. Disposing a collection unregisters it in the worker; the other collections of the adapter keep working. When the last of them is disposed, the adapter calls `terminate()` on the endpoint, if it has one, and rejects every further call with `WorkerDataAdapter is disposed`. ## `WorkerDataAdapterHost` ```ts new WorkerDataAdapterHost(context: WorkerDataAdapterHostEndpoint, options: { id?: string storage: (name: string) => StorageAdapter onError?: (error: Error) => void log?: (message: string, ...args: any[]) => void }) ``` `WorkerDataAdapterHostEndpoint` is the part of the worker's global scope the host uses — `self` inside a worker: ```ts interface WorkerDataAdapterHostEndpoint { addEventListener: (type: 'message', listener: (event: MessageEvent) => any) => void postMessage: (message: any) => void } ``` * `storage`: Called once per collection with the collection's name. Required. * `onError`: Called when something fails inside the worker. Worth wiring up — an error thrown in a worker with nowhere to go is invisible from the main thread. ## Queries are asynchronous Every answer crosses a message boundary, so a query is not answered the moment you ask for it. As with the [`AsyncDataAdapter`](/reference/core/asyncdataadapter/), the cursor serves its neutral empty result until then, and [`Cursor#isLoading()`](/reference/core/cursor/) is what tells that apart from a query that matched nothing. A write, though, is shown immediately. While it is in flight the adapter layers it onto the results it holds, so your UI does not wait for the round trip. There is one exception. An item the adapter knows only through a **projected** query — one using `fields` — is not shown optimistically. Applying a modifier to an item that has had fields removed produces something that is not the item, and a selector naming a projected-away field would no longer match it. The write still happens; it simply becomes visible when the worker answers rather than immediately. ## The message boundary is a cost Everything crossing between the two halves is serialized on its way out and deserialized on the consumer's main thread. The work behind a message happens in the worker; the *size* of the message does not. That is why the host sends the full result only the first time a query is answered, and only what changed after that, and why a write that leaves a query's result unchanged produces no message at all. If you write your own adapter across such a boundary, do the same — see [the delta contract](/reference/core/dataadapter/#the-delta-contract). Projecting a query with `fields` is the other lever: it is the difference between sending a row and sending the two columns you render. --- --- url: /reference/core/autofetchdataadapter.md --- # AutoFetchDataAdapter ```ts import { AutoFetchDataAdapter } from '@signaldb/core' ``` Fetches a query's items from a remote source the first time that query is registered, and drops them again a while after nothing is watching it any more. Use it for data you want to pull on demand rather than synchronise in full. This is the successor to v1's `AutoFetchCollection`; see the [upgrade guide](/upgrade/v2/) if you are migrating from it. If you want the whole collection kept in step with a server instead, you want [`@signaldb/sync`](/sync/). ## Usage ```js import { Collection, AutoFetchDataAdapter } from '@signaldb/core' const dataAdapter = new AutoFetchDataAdapter({ fetchQueryItems: async (collectionName, selector) => { const response = await fetch(`/api/${collectionName}?q=${encodeURIComponent(JSON.stringify(selector))}`) return response.json() }, }) const Posts = new Collection('posts', dataAdapter) // Registering this query is what triggers the fetch. const cursor = Posts.find({ authorId: 'user1' }) ``` ## Options ```ts new AutoFetchDataAdapter(options: { fetchQueryItems: ( collectionName: string, selector: Selector, ) => Promise storage?: (name: string) => StorageAdapter id?: string onError?: (error: Error) => void registerRemoteChange?: (onChange: () => Promise) => Promise mergeItems?: (a: T, b: T) => T purgeDelay?: number }) ``` * `fetchQueryItems`: Retrieves the items matching a selector from the remote source. Required. It resolves to an array of items, each of which **must** carry an `id`. Resolving to `undefined` — or anything that is not an array — counts as a failed fetch: the queries for that selector are put into the error state and `onError` is called. * `storage`: Called once per collection with the collection's name, and returns the [storage adapter](/data-persistence/) fetched items are cached in. Optional: without it, the fetched items are cached in memory and do not survive a reload. * `id`: A logical name, handy when several adapters run side by side. * `onError`: Called when a fetch fails. * `registerRemoteChange`: Called once at construction. Invoke the callback it hands you whenever the remote source changed and every active query should be re-fetched — a websocket message, a server-sent event. * `mergeItems`: How a freshly fetched item is merged with the one already held. Default is a shallow spread with the fresh item winning. * `purgeDelay`: Milliseconds to wait after a query becomes inactive before its items are purged. `0` purges immediately. Default `10000`. ## The result is not there yet The fetch happens after the query is registered, so the cursor serves its neutral empty result until the answer arrives — and an empty result is a legitimate answer, which makes the two indistinguishable. Use [`Cursor#isLoading()`](/reference/core/cursor/): ```js const cursor = Posts.find({ authorId: 'user1' }) effect(() => { if (cursor.isLoading()) return renderSpinner() renderPosts(cursor.fetch()) }) ``` ## purgeDelay Items fetched for a query are dropped `purgeDelay` milliseconds after the last cursor on that query goes away. The delay exists because navigating away from a view and back again is common, and re-fetching what you had a second ago is waste. Raise it if your users move between views quickly. Lower it, or set it to `0`, if holding the data costs more than fetching it again. --- --- url: /reference/core/createstorageadapter.md --- # createStorageAdapter ```ts import { createStorageAdapter } from '@signaldb/core' ``` While SignalDB comes with a few built-in storage adapters, there may be scenarios where you need to write one for a backend of your own. A storage adapter persists documents and finds them again. Query semantics stay in SignalDB — see [why that is](/data-persistence/#why-query-semantics-stay-in-signaldb); an adapter may optionally narrow a read with [`query`](#answering-queries-with-query). It is reached through a [data adapter](/data-adapters/), which is what decides *where* the data operations run. Create one by calling `createStorageAdapter` with an object implementing `StorageAdapter`: ```ts interface StorageAdapter { // lifecycle setup(): Promise teardown(): Promise // reading readAll(): Promise readIds(ids: I[]): Promise query?(query: StorageQuery): Promise> // indices createIndex(field: string): Promise dropIndex(field: string): Promise readIndex(field: string): Promise>> // writing insert(items: T[]): Promise replace(items: T[]): Promise remove(items: T[]): Promise removeAll(): Promise } ``` * **setup** is called once before the collection is used. Open your connection, create your directory, run your migration here. * **teardown** is called when the collection is disposed. Clean up what `setup` acquired. * **readAll** returns every document. This is what answers a query no index covers, so it is the cost you pay for an unindexed selector. * **readIds** returns the documents for the given ids, in any order, omitting ids that do not exist. Every backend can look something up by its key, which is why this is part of the interface rather than something you declare — `{ id: 'x' }` and `{ id: { $in: [...] } }` are resolved through it. * **query** (optional) answers a whole query as far as the backend can — see [below](#answering-queries-with-query). * **createIndex** / **dropIndex** are called for the fields a collection declares in `indices`. An adapter that cannot index may implement them as no-ops, as long as `readIndex` then reports what it actually has. * **readIndex** returns the index for one field: a map from value to the set of ids carrying it. **The keys are `serializeValue(value)`, not the raw field values** — see below. * **insert**, **replace**, **remove** write and delete the given documents; **removeAll** empties the collection. ## Index keys This is the one part that is easy to get wrong and hard to notice. `readIndex` is keyed by `serializeValue(value)`, because that is what makes `3`, `'3'` and a `Date` comparable as map keys at all — and it is what SignalDB looks the index up with. An adapter that stores its backend's own keys instead answers **nothing** for every non-string field and **everything** for a `$ne` on one. String-valued fields keep working, which is exactly why this can sit unnoticed for a long time. ```ts import { serializeValue } from '@signaldb/core' const key = serializeValue(item[field]) ``` `@signaldb/indexeddb` shipped with this bug in v1 for precisely that reason. ## Answering queries with `query` `query` is optional and a pure optimisation. Without it, a query is answered through `readIds`, `readIndex` or `readAll`, and filtered, sorted, windowed and projected in JavaScript. Implement it when your backend can read *less than everything* for a query — an equality it can turn into a key lookup, an order it can return rows in, a limit it can apply — so that a bounded query does not have to read the whole collection first. ```ts import type { StorageQuery, StorageQueryAnswer } from '@signaldb/core' interface StorageQuery { selector: Selector sort?: SortSpecifier skip?: number limit?: number fields?: FieldSpecifier } interface StorageQueryAnswer { items: T[] residualSelector?: Selector // the part of the selector you did not apply sorted?: boolean // items are in the requested order windowed?: boolean // skip and limit were applied projected?: boolean // items carry only the requested fields } ``` An adapter answers as much as it can and says what it did. Every flag defaults to "no", and SignalDB applies whatever the adapter declined, so partial support is the normal case: translate an equality and hand back a `$regex` as `residualSelector`, sort but leave the window to SignalDB. Omit `residualSelector` (or return `{}`) only if `items` matches the whole selector. Three answers are contradictions, and SignalDB throws on them instead of returning a wrong result: * `windowed` while a `residualSelector` remains — the window was taken over rows that were going to be filtered out. * `windowed` without `sorted` when a sort was requested — a window over an unordered set is an arbitrary subset. * `projected` without `sorted` when the sort is on a field the projection dropped — the rows can no longer be sorted. `readIndex` is not consulted for a query the adapter answered through `query`. `query` is used by the data adapters that read from storage on every query: [`AsyncDataAdapter`](/reference/core/asyncdataadapter/), [`AutoFetchDataAdapter`](/reference/core/autofetchdataadapter/) and the [`WorkerDataAdapterHost`](/reference/core/workerdataadapter/). The `DefaultDataAdapter` keeps a collection in memory and reads it from storage once, through `readAll`. `@signaldb/indexeddb` implements `query` to turn an equality on the primary key or an indexed field into a key-range read; it reports nothing as `sorted`, `windowed` or `projected`. ## Example A minimal in-memory adapter — the shape to start from, and useful in tests: ```ts import { createStorageAdapter, serializeValue } from '@signaldb/core' export default function createMemoryAdapter() { const items = new Map() const indices = new Map>>() const rebuild = () => { indices.forEach((index, field) => { index.clear() items.forEach((item) => { const key = serializeValue((item as any)[field]) if (!index.has(key)) index.set(key, new Set()) index.get(key)?.add(item.id) }) }) } return createStorageAdapter({ setup: () => Promise.resolve(), teardown: () => Promise.resolve(), readAll: () => Promise.resolve([...items.values()]), readIds: ids => Promise.resolve( ids.map(id => items.get(id)).filter(item => item != null) as T[], ), createIndex: (field) => { indices.set(field, new Map()) rebuild() return Promise.resolve() }, dropIndex: (field) => { indices.delete(field) return Promise.resolve() }, readIndex: (field) => { const index = indices.get(field) if (index == null) throw new Error(`No index on "${field}"`) return Promise.resolve(index) }, insert: (newItems) => { newItems.forEach(item => items.set(item.id, item)) rebuild() return Promise.resolve() }, replace: (newItems) => { newItems.forEach(item => items.set(item.id, item)) rebuild() return Promise.resolve() }, remove: (oldItems) => { oldItems.forEach(item => items.delete(item.id)) rebuild() return Promise.resolve() }, removeAll: () => { items.clear() rebuild() return Promise.resolve() }, }) } ``` Wire it up through a data adapter: ```ts import { Collection, DefaultDataAdapter } from '@signaldb/core' const dataAdapter = new DefaultDataAdapter({ storage: () => createMemoryAdapter(), }) const Posts = new Collection('posts', dataAdapter) ``` For a persistent backend, `@signaldb/localstorage` is the smallest real implementation to read, and `@signaldb/generic-fs` shows the shape for anything file-like. --- --- url: /reference/core/createreactivityadapter.md --- # createReactivityAdapter ```ts import { createReactivityAdapter } from '@signaldb/core' ``` A reactivity adapter is a simple object that provides a way for a collection to track dependencies and notify them when changes occur, thereby providing reactivity to your collection. The following code snippets demonstrate the implementation of a reactivity adapter using the `@maverick-js/signals` library. A ReactivityAdapter object can have the following methods. ### `create() -> Dependency` The `create` function creates a new reactive dependency. A `Dependency` object must have at least these two methods: * `depend()`: This method is called when the collection data is read, marking the place in the code as dependent on the collection data. Subsequent changes to the collection data will cause this place to be re-evaluated. * `notify()`: This method is called when the collection data changes, notifying all dependent parts of the code that they need to re-evaluate. You can also include more methods or other data in the dependency which you can access from the [`onDispose`](#ondispose-callback-void-dependency-dependency-optional) method. ```js create: () => { const dep = signal(0) return { depend: () => { dep() }, notify: () => { dep.set(peek(() => dep() + 1)) }, } } ``` ### `isInScope(): boolean` (optional) The `isInScope` function takes no arguments and is used for checking whether SignalDB is called from a reactive scope. If it returns `false`, reactivity is automatically disabled for that query to avoid memory leaks. Without `isInScope`, SignalDB cannot tell, so if you are not in a reactive scope ([`find`](/reference/core/collection/#find-selector-selector-t-options-options)/[`findOne`](/reference/core/collection/#findone-selector-selector-t-options-options) called outside an `effect` function), you have to turn off reactivity manually by adding the `{ reactive: false }` option to the [`find`](/reference/core/collection/#find-selector-selector-t-options-options)/[`findOne`](/reference/core/collection/#findone-selector-selector-t-options-options) method(e.g. `.find({ … }, { reactive: false })`). If you're not doing this, SignalDB setups reactivity unnecessarily and is not able to cleanup this automatically later on. ```js isInScope() { return !!getScope() } ``` ### `onDispose(callback: () -> void, dependency: Dependency)` (optional) This method is used to register a callback to be executed when the reactive computation is disposed. The dependency created in the [`create`](#create-dependency) method, will be passed as the second parameter. This can be useful if a framework requires data from the creation on disposal. The `onDispose` function is optional, but it's highly recommended to implement it whenever it's possible. Without `onDispose`, SignalDB will not be able to clean up resources automatically when they are no longer needed. That means, that you have to call the [`cursor.cleanup()`](/reference/core/cursor/#cleanup) method manually at the end of the computation. Normally there is some way to cleanup things after the computation runs, but it's possible that you cannot implement it in this `onDispose` method (like in the [Angular adapter](/reference/angular/) for example). ```js onDispose: (callback, dependency) => { onDispose(callback) } ``` The above methods are what you need to implement to provide a basic reactivity system to your collection. Here's a complete example of a reactivity adapter: ```js import { signal, peek, getScope, onDispose } from '@maverick-js/signals' import { createReactivityAdapter } from '@signaldb/core' const reactivity = createReactivityAdapter({ create: () => { const dep = signal(0) return { depend: () => { dep() }, notify: () => { dep.set(peek(() => dep() + 1)) }, } }, isInScope: () => !!getScope(), onDispose: (callback) => { onDispose(callback) }, }) export default reactivity ``` Once the `reactivity` object is created, you can use it as the `reactivity` option when creating a new Collection. This will provide the collection with reactivity capabilities. --- --- url: /reference/core/utilities.md --- # Utilities ```ts import { serializeValue, get, isEqual, modify, randomId, EventEmitter, reactiveOrAsync, unwrap, } from '@signaldb/core' ``` `@signaldb/core` exports the helpers it uses internally that are useful when you write an adapter or an integration of your own. They follow the same semantics SignalDB applies itself, so an adapter built on them cannot disagree with SignalDB about what a value or a modifier means. ## `serializeValue(value: any): string | null` Turns a field value into the key an index is stored under: strings as they are, numbers and booleans as their string form, dates as ISO strings, everything else through `JSON.stringify`. `null` and `undefined` both become `null`. A custom [`StorageAdapter`](/reference/core/createstorageadapter/#index-keys) must key the map returned by `readIndex` with exactly this function — it is what SignalDB looks an index up with. ```ts serializeValue(3) // '3' serializeValue(new Date(0)) // '1970-01-01T00:00:00.000Z' serializeValue(undefined) // null ``` ## `get(value: object, path: string)` Reads the value at a path inside an object. Dot notation (`'author.name'`) and bracket notation (`'tags[0]'`) are supported. Returns `undefined` if any part of the path does not exist or the path is malformed. ```ts get({ author: { name: 'Ada' } }, 'author.name') // 'Ada' ``` ## `isEqual(a, b): boolean` Compares two values for deep equality, including arrays, dates and regular expressions. ```ts isEqual({ a: [1, new Date(0)] }, { a: [1, new Date(0)] }) // true ``` ## `modify(item: T, modifier: Modifier): T` Applies a [modifier](/data-manipulation/) to an item and returns the modified copy; the input is not mutated. A modifier without any `$` operator replaces the item as a whole, as it does in `updateOne`. ```ts modify({ a: 1, b: 2 }, { $set: { b: 3 } }) // { a: 1, b: 3 } ``` ## `randomId(): string` Returns a random id of 16 lowercase alphanumeric characters — the default primary key of a collection. It uses `Math.random()` and is therefore not suitable where an id must be unguessable. ## `EventEmitter` The typed event emitter `Collection` is built on. Extend it with a map of event names to listener signatures: ```ts class Store extends EventEmitter<{ saved: (id: string) => void, }> {} const store = new Store() store.on('saved', id => console.log(id)) store.emit('saved', 'a1') ``` It offers `on`/`addListener`, `once`, `off`/`removeListener`, `emit`, `listeners`, `listenerCount`, `removeAllListeners` and `setMaxListeners`. It logs a warning whenever an event has more listeners than the maximum, 100 by default, which usually points at listeners that are never removed. ## `reactiveOrAsync(generator)` and `unwrap(value)` Build a function that can be called both ways SignalDB queries can: synchronously — and therefore reactively — or asynchronously with `{ async: true }` as its last argument. Write the logic once as a generator and `yield* unwrap(…)` every value that may be a promise; `reactiveOrAsync` runs it synchronously or awaits each yielded promise, depending on how it was called. ```ts const getPostWithAuthor = reactiveOrAsync(function* (async: boolean, postId: string) { const post = yield* unwrap(Posts.findOne({ id: postId }, { async })) if (!post) return undefined const author = yield* unwrap(Authors.findOne({ id: post.authorId }, { async })) return { ...post, author } }) getPostWithAuthor('p1') // synchronous and reactive await getPostWithAuthor('p1', { async: true }) // asynchronous ``` The generator receives whether it runs asynchronously as its first argument; pass it on to the queries it makes. Yielding a promise in synchronous mode is a programming error and throws. The returned function exposes its generator as `.generator`, so one such workflow can compose another with `yield* other.generator.call(this, async, …)`. A collection's [`transformAll`](/orm/#reading-related-data-the-way-the-query-is-read) can be built the same way: SignalDB calls it with `{ async: true }` for an asynchronous read and synchronously for every other one. --- --- url: /reference/sync.md --- # SyncManager ```ts import { SyncManager } from '@signaldb/sync' const syncManager = new SyncManager({ pull: async () => { // your pull logic }, push: async () => { // your push logic }, }) syncManager.addCollection(someCollection, { name: 'someCollection', }) ``` The `SyncManager` class in SignalDB is designed to handle the synchronization of collections between your local storage and a remote source. It manages both pushing local changes to the server and pulling updates from the server, ensuring that your data remains consistent and up-to-date. ## Constructor ### `new SyncManager(options)` Creates a new instance of `SyncManager`. #### Parameters * `options` (`Options`): Configuration options for the sync manager. * `pull`: Function to fetch data from the remote source. The function gets the collection options as the first parameter. The second parameter is an object containing the following properties: * `lastFinishedSyncStart`: The start time of the last finished sync (if available). * `lastFinishedSyncEnd`: The end time of the last finished sync (if available). It must return a promise resolving to either `{ items }` — **all** items of the collection on the server, which the sync manager compares against its last snapshot — or `{ changes: { added, modified, removed } }` — only what changed since the last sync. See [implementing the `pull` method](/sync/#implementing-the-pull-method). * `push`: Function to send changes to the remote source. The function gets the collection options as the first parameter. The second parameter is an object that contains the following properties: * `changes`: * `added`: An array of added items. * `modified`: An array of updated items. * `modifiedFields`: A map with the modified fields per item id. * `removed`: An array of removed items. * `rawChanges`: An array of the raw change operations. * `registerRemoteChange`: Optional function to register a callback for remote changes. The callback can also return a cleanup function to remove the listener. * `id`: Optional unique identifier for the sync manager. * `dataAdapter`: Optional [data adapter](/data-adapters/) for the sync manager's own collections — the ones holding its changes, snapshots and sync operations. Pass the same one your collections use so that everything lives in one place. Defaults to a `DefaultDataAdapter`, which keeps that bookkeeping in memory only, so it does not survive a reload. * `reactivity`: Optional reactivity adapter for handling reactivity. * `onError`: Optional function to handle errors. * `autostart`: Optional flag to start syncing automatically after adding collections (default: `true`). * `debounceTime`: Optional time in milliseconds to debounce pushing changes (default: `100`). ## Methods All methods that start, pause or perform work — `removeCollection`, `syncAll`, `sync`, `startSync`, `pauseSync`, `startAll`, `pauseAll`, `pushChanges` and `dispose` — return a promise. Await it, or handle its rejection: a failed sync rejects the promise of the call that started it. ### `addCollection(collection, options)` Adds a collection to the sync manager. #### Parameters * `collection` (`Collection`): The collection to add. * `options` (`SyncOptions`): Configuration options for the collection. Adding a collection registers `added`, `changed` and `removed` listeners on it. Calling `addCollection` again with the same `name` replaces the previous registration instead of adding a second set of listeners. ### `removeCollection(name)` Removes a collection from the sync manager. This pauses the sync process for the collection and detaches all event listeners the sync manager attached to it. The collection itself isn't disposed and stays usable afterwards. Listeners registered by your application are left untouched. #### Parameters * `name` (`string`): The name of the collection. ### `getCollection(name)` (deprecated) Retrieves a collection and its options by name, as a tuple `[collection, options]`. Use [`getCollectionProperties`](#getcollectionproperties-name) instead. ### `getCollectionProperties(name)` Retrieves a registered collection and its options by name. Throws if no collection with that name was added. #### Parameters * `name` (`string`): The name of the collection. #### Returns * An object with the properties `collection` (the `Collection`), `options` (the `SyncOptions` passed to `addCollection`), `readyPromise` (resolves when the collection is ready) and `syncPaused` (`boolean`). ### `syncAll()` Starts the sync process for all collections managed by the sync manager. The returned promise rejects with one combined error if syncing any of the collections failed. ### `isSyncing(name?, async?)` ⚡️ this function is reactive! Checks if a specific collection or any collection is currently being synced. Called in a reactive scope of the `reactivity` adapter passed to the sync manager, it reruns when that changes. #### Parameters * `name` (`string`, optional): The name of the collection. If omitted, checks all collections. * `async` (`boolean`, optional): If `true`, the active sync operations are read through an `{ async: true }` query and a promise is returned. Use this when the sync manager's `dataAdapter` cannot answer a query on the spot — an `AsyncDataAdapter` or a `WorkerDataAdapter` — or when several instances of the application share its storage. #### Returns * `boolean`: `true` if syncing, `false` otherwise. * `Promise` if `async` is `true`. ### `isReady()` Returns a promise that resolves once the sync manager's own collections — changes, snapshots and sync operations — are ready. `sync` and `syncAll` wait for it themselves; you only need it to wait for the sync manager before calling anything else. ### `sync(name, options)` Starts the sync process for a specific collection. #### Parameters * `name` (`string`): The name of the collection. * `options` (`object`, optional): Sync options. * `force` (`boolean`, optional): If `true`, forces the sync process even if no changes are detected. * `onlyWithChanges` (`boolean`, optional): If `true`, syncs only if there are changes. ### `startSync(name)` Setup a collection to be synced with remote changes and enable automatic pushing changes to the remote source. #### Parameters * `name` (`string`): The name of the collection. ### `pauseSync(name)` Pauses the sync process for a collection. This means that the collection will not be synced with remote changes and changes will not automatically be pushed to the remote source. #### Parameters * `name` (`string`): The name of the collection. ### `startAll()` Setup all collections to be synced with remote changes and enable automatic pushing changes to the remote source. ### `pauseAll()` Pauses the sync process for all collections. This means that the collections will not be synced with remote changes and changes will not automatically be pushed to the remote source. ### `pushChanges(name)` Initiates the push process for a collection, syncing only if there are changes. #### Parameters * `name` (`string`): The name of the collection. ### `dispose()` Disposes all internal collections and other data structures. It also detaches the event listeners that the sync manager attached to the registered collections, so those collections can be reused with a new `SyncManager` afterwards (for example on a logout/login cycle). --- --- url: /reference/react.md --- # @signaldb/react ## createUseReactivityHook ```ts import { createUseReactivityHook } from '@signaldb/react' import { effect } from '…' const useReactivity = createUseReactivityHook(effect) ``` This function creates a custom hook that provides reactivity to your components. It takes a function as the single argument that specifies the effect function of a reactive library. The effect function must have the following signature: ```ts (reactiveFunction: () => void) => () => void ``` The provided function is called with a reactive function that should be executed when the reactivity changes. The returned function is the cleanup function that removes the effect. ### Return value `createUseReactivityHook` returns the `useReactivity` hook: ```ts useReactivity(reactiveFunction: () => T, deps?: DependencyList): T ``` * `reactiveFunction` - Runs inside the effect of your reactive library. Its return value is what the hook returns, and the component re-renders whenever a reactive dependency read inside it changes. * `deps` - (Optional) A React dependency list. When one of its values changes, the effect is stopped and `reactiveFunction` runs again in a new one. Default is `[]`. The effect is stopped when the component unmounts. ```jsx const PostList = ({ author }) => { const posts = useReactivity(() => Posts.find({ author }).fetch(), [author]) return
      {posts.map(post =>
    • {post.title}
    • )}
    } ``` Also check out our guide on [how to use SignalDB with React](/guides/react/). --- --- url: /reference/fs.md --- # @signaldb/fs ## createFilesystemAdapter (`default`) ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import createFilesystemAdapter from '@signaldb/fs' const dataAdapter = new DefaultDataAdapter({ storage: name => createFilesystemAdapter(`./data/${name}`), }) const Posts = new Collection('posts', dataAdapter) ``` Function to create a file system adapter for use with a collection. In a Node.js environment there is no browser storage to persist data in, so this adapter stores each collection in a folder on disk (see [Layout on disk](#layout-on-disk) below). Every file is written with `serialize` (JSON by default). A data adapter asks its `storage` function for one adapter per collection and passes the collection's name, which is why the function above derives the folder from that name. ### Parameters * `folderName` - The folder this collection lives in. The adapter creates it if it does not exist. * `options` - (Optional) Configuration object with the following properties: * `serialize` - (Optional) Turns a stored value into a string. Default is `JSON.stringify`. * `deserialize` - (Optional) Reads that string back. Default is `JSON.parse`. ### Layout on disk The adapter is given a **folder**, not a file. Inside it, `items/` holds one file per document — sharded over two levels of subdirectory by the document's id — and `index/` holds one file per indexed value. Writing one document touches one file, so the cost of a write does not grow with the size of the collection. --- --- url: /reference/generic-fs.md --- # @signaldb/generic-fs ```ts import createGenericFSAdapter from '@signaldb/generic-fs' import type { Driver } from '@signaldb/generic-fs' ``` The shared foundation behind [`@signaldb/fs`](/reference/fs/) and [`@signaldb/opfs`](/reference/opfs/). It turns a handful of low-level file operations into a full [storage adapter](/reference/core/createstorageadapter/), so a new file-like backend costs you a driver rather than an adapter. Reach for it when you want to store a collection on something that can create directories, read and write files, and list them — a remote file API, an archive, a virtual filesystem — and you would rather not reimplement sharding and index maintenance. ## createGenericFSAdapter (`default`) ```ts createGenericFSAdapter(driver: Driver, folderName: string) ``` * `driver`: The low-level operations for your backend, see below. * `folderName`: The folder this collection lives in. Returns a `StorageAdapter`, ready to be handed to a [data adapter](/data-adapters/): ```ts import { Collection, DefaultDataAdapter } from '@signaldb/core' import createGenericFSAdapter from '@signaldb/generic-fs' const dataAdapter = new DefaultDataAdapter({ storage: name => createGenericFSAdapter(myDriver, `./data/${name}`), }) const Posts = new Collection('posts', dataAdapter) ``` ## Layout Inside `folderName` the adapter keeps two directories: * `items/` — one file per document, sharded over two levels of subdirectory by the document's id, so a directory never grows without bound. * `index/` — one file per indexed value. A write therefore costs one file, not a rewrite of the whole collection. ## `Driver` ```ts interface Driver { fileNameForId(id: I): Promise fileNameForIndexKey(key: string): Promise joinPath(...parts: string[]): Promise ensureDir(path: string): Promise fileExists(path: string): Promise readObject(path: string): Promise writeObject(path: string, value: T[]): Promise readIndexObject(path: string): Promise[] | null> writeIndexObject(path: string, value: Record[]): Promise listFilesRecursive(directoryPath: string): Promise removeEntry(path: string, options?: { recursive?: boolean }): Promise } ``` * **fileNameForId** turns a document id into a path *relative to* `items/`. This is where sharding happens: `@signaldb/fs` returns `ab/cd/abcdef…` so that a large collection does not put every file in one directory. Whatever you return has to be a legal name for your backend — escape it. * **fileNameForIndexKey** does the same for an index key. Index keys are `serializeValue(value)` and can contain anything a document field can, so this one always needs escaping. * **joinPath** joins path segments the way your backend spells paths. * **ensureDir** creates a directory and its parents, and does nothing if it already exists. * **fileExists** reports whether a path exists. Return `false` rather than throwing when it does not. * **readObject** / **writeObject** read and write one document file. `readObject` returns `null` when the file is missing — that is not an error. * **readIndexObject** / **writeIndexObject** do the same for an index file. * **listFilesRecursive** returns every file under a directory, as paths relative to it. * **removeEntry** deletes a file, or a directory with `{ recursive: true }`. Serialization is yours: `readObject` and `writeObject` decide what a file contains, which is how `@signaldb/fs` and `@signaldb/opfs` offer their `serialize` and `deserialize` options. ## Example [`@signaldb/fs`](/reference/fs/) is the shortest complete driver to read — it implements the interface above against Node's `fs/promises` in about eighty lines. [`@signaldb/opfs`](/reference/opfs/) is the same interface against the browser's Origin Private File System. --- --- url: /reference/indexeddb.md --- # @signaldb/indexeddb ## createIndexedDBAdapter (`default`) ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import createIndexedDBAdapter from '@signaldb/indexeddb' const dataAdapter = new DefaultDataAdapter({ storage: createIndexedDBAdapter({ databaseName: 'my-app', version: 1, schema: { posts: ['authorId'], }, }), }) const Posts = new Collection('posts', dataAdapter) ``` One IndexedDB database holds every collection of your application. You describe that database once — its name, its version and its stores — and `createIndexedDBAdapter` returns the `storage` function a data adapter asks for the store belonging to a collection. Each key of `schema` is a store name and must match the name you give the collection; its value lists the fields to index inside that store. ### Parameters * `options` - An `IndexedDBOptions` object (exported as a type from `@signaldb/indexeddb`): ```ts type IndexedDBOptions = { databaseName?: string, version: number, schema: Record, onUpgrade?: ( database: IDBDatabase, transaction: IDBTransaction, oldVersion: number, newVersion: number | null, ) => Promise, } ``` * `databaseName` - (Optional) The name of the IndexedDB database. Default is `'signaldb'`. * `version` - The version of the database schema, passed to `indexedDB.open()`. Raise it whenever you change `schema`; the stores are only reconciled during a version upgrade. * `schema` - An object describing the stores. Keys are store names, values are the fields to index in that store. Every store uses `id` as its key path, so `id` never needs to be listed. * `onUpgrade` - (Optional) Async callback `(database, transaction, oldVersion, newVersion)` invoked during a version upgrade, before SignalDB reconciles the stores. The upgrade waits for the returned promise. Stores present in the database but absent from `schema` are dropped on upgrade, so the schema is the complete description of what the database holds. ### Examples Basic usage: ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import createIndexedDBAdapter from '@signaldb/indexeddb' const dataAdapter = new DefaultDataAdapter({ storage: createIndexedDBAdapter({ databaseName: 'my-app', version: 1, schema: { users: [] }, }), }) const Users = new Collection('users', dataAdapter) // Insert data — writes are asynchronous await Users.insert({ id: '1', name: 'John Doe' }) // Fetch data const items = Users.find().fetch() console.log(items) // [{ id: '1', name: 'John Doe' }] ``` Several collections in one database, with indices: ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import createIndexedDBAdapter from '@signaldb/indexeddb' const dataAdapter = new DefaultDataAdapter({ storage: createIndexedDBAdapter({ databaseName: 'my-app', version: 2, schema: { 'posts': ['authorId', 'status'], 'authors': [], }, }), }) const Posts = new Collection('posts', dataAdapter, { indices: ['authorId', 'status'], }) const Authors = new Collection('authors', dataAdapter) ``` The fields you list in the store's `schema` entry and the collection's `indices` describe the same thing from two sides: the store has to carry the index, and the collection has to know it may use it. ### Using it with a `SyncManager` When you pass the same data adapter to a [`SyncManager`](/reference/sync/) from `@signaldb/sync`, the sync manager stores its own bookkeeping in three collections of that data adapter, named after its `id`. Each of them needs a store in `schema`, with these indices: | Store | Indices | |---|---| | `-changes` | `collectionName` | | `-snapshots` | `collectionName` | | `-sync-operations` | `collectionName`, `status` | Without an `id`, the sync manager uses `default-sync-manager`, so the stores are `default-sync-manager-changes` and so on. Setting `id` explicitly keeps the store names under your control: ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import createIndexedDBAdapter from '@signaldb/indexeddb' import { SyncManager } from '@signaldb/sync' const dataAdapter = new DefaultDataAdapter({ storage: createIndexedDBAdapter({ databaseName: 'my-app', version: 1, schema: { 'posts': [], 'app-changes': ['collectionName'], 'app-snapshots': ['collectionName'], 'app-sync-operations': ['collectionName', 'status'], }, }), }) const Posts = new Collection('posts', dataAdapter) const syncManager = new SyncManager({ id: 'app', dataAdapter, pull: async () => { /* … */ }, push: async () => { /* … */ }, }) syncManager.addCollection(Posts, { name: 'posts' }) ``` Because stores that are missing from `schema` are dropped on upgrade, leaving these entries out also discards the sync manager's record of unsynced changes the next time you raise `version`. --- --- url: /reference/localstorage.md --- # @signaldb/localstorage ## createLocalStorageAdapter (`default`) ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import createLocalStorageAdapter from '@signaldb/localstorage' const dataAdapter = new DefaultDataAdapter({ storage: name => createLocalStorageAdapter(name), }) const Posts = new Collection('posts', dataAdapter) ``` Function to create a localStorage adapter for use with a collection. The localStorage Adapter is the most straightforward tool for usage within a browser setting. To initiate its use, the only step required is designating a specific name to identify your data. This named data forms a collection that will be stored in the localStorage, from which it can be loaded or saved as needed. A data adapter asks its `storage` function for one adapter per collection and passes the collection's name, which is why the function above simply hands that name on. ### Parameters * `name` - A unique name for the collection. It becomes part of the localStorage keys. * `options` - (Optional) Configuration object with the following properties: * `databaseName` - (Optional) Prefix shared by every key this adapter writes, so several independent databases can live in the same origin. * `serialize` - (Optional) Turns the stored value into a string. Default is `JSON.stringify`. * `deserialize` - (Optional) Reads that string back. Default is `JSON.parse`. --- --- url: /reference/opfs.md --- # @signaldb/opfs **What is OPFS?** The [Origin Private File System](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS) is a private file system that browsers provide to each website (origin). Pages can create, read and write files in it without any permission prompt, and the files are invisible to the user and to other sites. OPFS is part of the File System API and is supported in all current major browsers (Chrome, Edge, Firefox and Safari). Compared to other browser storage (see [localStorage vs IndexedDB vs OPFS](/browser-storage/) for details): | | localStorage | IndexedDB | OPFS | |---|---|---|---| | Data model | string key/value | object store with indexes | files and directories | | API | synchronous | asynchronous (event-based) | asynchronous; fast synchronous access in Web Workers | | Capacity | a few MB per origin | large (quota-based) | large (quota-based) | | Typical use | small settings | structured app data | large files, databases, binary data | `@signaldb/opfs` stores the documents of a SignalDB collection as a folder in OPFS, with one file per document and one file per indexed value. This gives you persistent local storage for your data with a single line of configuration, which is useful for [offline-first](/offline-first/) apps. ## createOPFSAdapter (`default`) ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import createOPFSAdapter from '@signaldb/opfs' const dataAdapter = new DefaultDataAdapter({ storage: name => createOPFSAdapter(name), }) const Posts = new Collection('posts', dataAdapter) ``` Function to create a OPFS adapter for use with a collection. The OPFS Adapter is another way to store data in a browser environment. This adapter is based on the [Origin Private File System API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system). It is a simple and straightforward way to store data in the browser's filesystem. A data adapter asks its `storage` function for one adapter per collection and passes the collection's name, which is why the function above uses that name as the folder. ### Parameters * `folderName` - The folder this collection lives in, relative to the origin private file system root. * `options` - (Optional) Configuration object with the following properties: * `serialize` - (Optional) Turns a stored value into a string. Default is `JSON.stringify`. * `deserialize` - (Optional) Reads that string back. Default is `JSON.parse`. Like the [Filesystem Adapter](/reference/fs/), the adapter is given a **folder** rather than a file: `items/` holds one file per document, `index/` one file per indexed value. ### Requirements The adapter needs `navigator.storage.getDirectory()` and `FileSystemFileHandle#createWritable()` for reading and writing files, and the [Web Locks API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API) (`navigator.locks`): every read and write of a file runs under an exclusive lock named after its path, so tabs and workers of the same origin never interleave a read with a write to the same file. All of these are only available in secure contexts (HTTPS or `localhost`); without them the adapter cannot access its files. The OPFS Adapter is an alternative to the [Filesystem Adapter](https://signaldb.js.org/reference/fs/). The OPFS Adapter can only be used in a browser environment, while the Filesystem Adapter can only be used in a Node.js environment. *Credits to [jamesgibson14](https://github.com/jamesgibson14)* --- --- url: /reference/angular.md --- # @signaldb/angular ## angularReactivityAdapter (`default`) ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import { effect } from '@angular/core' import angularReactivityAdapter from '@signaldb/angular' const posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: angularReactivityAdapter, }) effect((onCleanup) => { const cursor = posts.find({ author: 'John' }) console.log(cursor.count()) onCleanup(() => { cursor.cleanup() }) }) ``` Reactivity adapter for usage with [Angular](https://angular.dev/). The API of Angular doesn't allow [automatic cleanup](/reference/core/createreactivityadapter/#ondispose-callback-void-dependency-dependency-optional) nor [reactive scope checking](/reference/core/createreactivityadapter/#isinscope-boolean-optional). In Angular, the function passed to the `effect()` function gets a `onCleanup` callback that can be used to cleanup the effect. You can use this to cleanup the cursor (see an example below). You also must manually disable reactivity when making calls outside a reactive scope to avoid memory leaks. You can do this by passing `{ reactive: false }` to your options (e.g. `.find({ ... }, { reactive: false })`). In Angular, the introduction of signals has revolutionized the way data changes are communicated within templates and other code components. Signals, in conjunction with SignalDB offer a seamless integration that enhances the reactivity and performance of Angular applications. SignalDB complements Angular's signal mechanism by providing a robust database solution that responds in real-time to data changes. When data in SignalDB changes, it can emit signals that Angular components can listen to, ensuring that the UI is always in sync with the underlying data. This integration not only simplifies state management but also optimizes performance by reducing unnecessary change detection cycles. Developers can leverage this synergy between Angular's signals and SignalDB to build more efficient, reactive, and user-friendly web applications. --- --- url: /reference/maverickjs.md --- # @signaldb/maverickjs ## maverickjsReactivityAdapter (`default`) ```js import { effect } from '@maverick-js/signals' import maverickjsReactivityAdapter from '@signaldb/maverickjs' import { Collection, DefaultDataAdapter } from '@signaldb/core' const posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: maverickjsReactivityAdapter, }) effect(() => { console.log(posts.find({ author: 'John' }).count()) }) ``` Reactivity adapter for usage with [Maverick signals](https://github.com/maverick-js/signals). Maverick.js's signals provide a powerful foundation for reactive programming, and their integration with signaldb showcases this strength vividly. Signals, in essence, are observables in maverick.js that let you store state and react to changes in real-time. When paired with signaldb, developers can gain the advantage of seamlessly creating reactive databases. The maverick.js reactivity adapter for signaldb simplifies this integration. By utilizing the reactivity adapter, the bridge between maverick.js signals and signaldb is streamlined, making it easier for developers to set up and maintain reactivity across their applications. This integration ensures that the data stays up-to-date, responsive, and efficient, all while adhering to the "lazy principle" that advocates for maximum efficiency with minimal burden on the developer. Whether you're looking to build robust UI libraries or simply want a lightweight solution for enhanced reactivity, integrating maverick.js's signals with signaldb via the reactivity adapter is a step in the right direction. --- --- url: /reference/meteor.md --- # @signaldb/meteor ## meteorReactivityAdapter (`default`) ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import meteorReactivityAdapter from '@signaldb/meteor' import { Tracker } from 'meteor/tracker' const posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: meteorReactivityAdapter(Tracker), }) Tracker.autorun(() => { console.log(posts.find({ author: 'John' }).count()) }) ``` Reactivity adapter for usage with [Meteor Tracker](https://docs.meteor.com/api/tracker.html). Meteor Tracker is an integral component of the Meteor framework, offering a seamless dependency tracking system that ensures automatic updates of templates and computations when underlying data sources, such as Session variables or database queries, undergo changes. This dynamic integration is further enhanced when paired with SignalDB. With its signal-based reactivity, SignalDB effortlessly synchronizes with Meteor Tracker's automatic dependency management. Users don't need to manually declare these dependencies; the synergy between Meteor Tracker and SignalDB ensures that it "just works." When a reactive function, like a database query, is invoked, Meteor Tracker intuitively saves the current Computation object. Subsequent changes to the data trigger an "invalidate" action on the Computation, prompting it to rerun and, in turn, rerender the associated template. While applications can leverage the Tracker.autorun feature for routine tasks, advanced functionalities like Tracker.Dependency and onInvalidate callbacks are tailored for package authors aiming to implement new reactive data sources. This seamless integration underscores the power and efficiency of combining Meteor Tracker's automatic dependency tracking with SignalDB's reactive capabilities. --- --- url: /reference/mobx.md --- # @signaldb/mobx ## mobxReactivityAdapter (`default`) ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import mobxReactivityAdapter from '@signaldb/mobx' import { autorun } from 'mobx' const posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: mobxReactivityAdapter, }) autorun(() => { const cursor = posts.find({ author: 'John' }) console.log(cursor.count()) }) ``` Reactivity adapter for usage with [MobX](https://mobx.js.org/). The API of MobX doesn't allow [reactive scope checking](/reactivity/#reactivity-libraries). You must manually disable reactivity when making calls outside a reactive scope to avoid memory leaks. You can do this by passing `{ reactive: false }` to your options (e.g. `.find({ ... }, { reactive: false })`). Integrating signals (or observables) in MobX with signaldb has revolutionized the way state management operates in modern applications. MobX, renowned for its effortless state management capabilities, transparently implements functional reactive programming. Through the use of a MobX reactivity adapter for signaldb, developers can harness the powerful reactivity mechanisms of MobX within the database context of signaldb. When you marry the dynamic, auto-updating nature of MobX observables with signaldb collections, you cultivate an environment where state and data persistency harmoniously coexist. Especially in scenarios where real-time data updates are crucial, this combination ensures that all dependent parts of your codebase are notified and updated whenever underlying data changes. Furthermore, the adaptability of MobX means that it seamlessly meshes with various frameworks, including the versatile signaldb. As the landscape of web development shifts towards more reactive paradigms, integrating MobX with signaldb emerges as a compelling solution for developers seeking efficient, boilerplate-free state management synchronized with a dependable database. If your framework still lacks a reactivity adapter, consider the value addition of integrating MobX and its unparalleled reactivity system into your tech stack. --- --- url: /reference/oby.md --- # @signaldb/oby ## obyReactivityAdapter (`default`) ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import obyReactivityAdapter from '@signaldb/oby' import { effect } from 'oby' const posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: obyReactivityAdapter, }) effect(() => { console.log(posts.find({ author: 'John' }).count()) }) ``` Reactivity adapter for usage with [oby](https://github.com/vobyjs/oby). --- --- url: /reference/preact.md --- # @signaldb/preact **What is `@preact/signals-core`?** It is the framework-independent core of [Preact Signals](https://preactjs.com/guide/v10/signals/): a small library that provides `signal()`, `computed()`, `effect()` and `batch()`. It has no dependency on Preact and can be used in any JavaScript project. `@preact/signals` and `@preact/signals-react` build on it to integrate signals into Preact and React components. For a general introduction, see [JavaScript Signals Explained](/signals/). `@signaldb/preact` connects `@preact/signals-core` to SignalDB: queries on a SignalDB collection that run inside an `effect()` or `computed()` become reactive and re-run whenever matching documents change, locally or through [sync](/sync/). ## preactReactivityAdapter (`default`) ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import preactReactivityAdapter from '@signaldb/preact' import { effect } from '@preact/signals-core' const posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: preactReactivityAdapter, }) effect(() => { const cursor = posts.find({ author: 'John' }) console.log(cursor.count()) return () => { // @preact/signals doesn't allow to do automatic cleanup, so we have to do it ourself cursor.cleanup() } }) ``` Reactivity adapter for usage with [Preact Signals](https://preactjs.com/blog/introducing-signals/). The API of Preact doesn't allow [automatic cleanup](/reference/core/createreactivityadapter/#ondispose-callback-void-dependency-dependency-optional) nor [reactive scope checking](/reference/core/createreactivityadapter/#isinscope-boolean-optional). With Preact Signals, you can return a function from your `effect` that will be called on cleanup. Use this one to cleanup your cursors (see below for an example). You also must manually disable reactivity when making calls outside a reactive scope to avoid memory leaks. You can do this by passing `{ reactive: false }` to your options (e.g. `.find({ ... }, { reactive: false })`). Signals in Preact are designed to provide an efficient way of expressing and managing state, ensuring that applications remain performant irrespective of their complexity. When integrated with SignalDB, these signals can be used to seamlessly synchronize and react to changes in the database. This means that when a signal's value changes in the Preact component, it can automatically reflect the changes in the SignalDB database, and vice versa. This integration provides developers with a streamlined approach to building dynamic, data-driven applications. By combining the reactive principles of Preact signals with the robust capabilities of SignalDB, developers can achieve real-time data updates, ensuring that the user interface is always in sync with the underlying database. This seamless integration not only simplifies state management but also enhances the overall user experience by providing instant feedback and reducing the need for manual data refreshes. --- --- url: /reference/reactively.md --- # @signaldb/reactively ## reactivelyReactivityAdapter (`default`) ```js import { reactive } from '@reactively/core' import { Collection, DefaultDataAdapter } from '@signaldb/core' import reactivelyReactivityAdapter from '@signaldb/reactively' const posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: reactivelyReactivityAdapter, }) reactive(() => { console.log(posts.find({ author: 'John' }).count()) }) ``` Reactivity adapter for usage with [@reactively/core](https://github.com/modderme123/reactively). The API of Reactively doesn't allow [reactive scope checking](/reactivity/#reactivity-libraries). You must manually disable reactivity when making calls outside a reactive scope to avoid memory leaks. You can do this by passing `{ reactive: false }` to your options (e.g. `.find({ ... }, { reactive: false })`). --- --- url: /reference/sinuous.md --- # @signaldb/sinuous ## sinuousReactivityAdapter (`default`) ```js import { api } from 'sinuous' import sinuousReactivityAdapter from '@signaldb/sinuous' import { Collection, DefaultDataAdapter } from '@signaldb/core' const posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: sinuousReactivityAdapter, }) api.subscribe(() => { console.log(posts.find({ author: 'John' }).count()) }) ``` Reactivity adapter for usage with [sinuous](https://sinuous.netlify.app/). The API of Sinuous doesn't allow [reactive scope checking](/reactivity/#reactivity-libraries). You must manually disable reactivity when making calls outside a reactive scope to avoid memory leaks. You can do this by passing `{ reactive: false }` to your options (e.g. `.find({ ... }, { reactive: false })`). --- --- url: /reference/sjs.md --- # @signaldb/sjs ## sjsReactivityAdapter (`default`) ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import sjsReactivityAdapter from '@signaldb/sjs' import S from 's-js' const posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: sjsReactivityAdapter, }) S(() => { console.log(posts.find({ author: 'John' }).count()) }) ``` Reactivity adapter for usage with [S.js](https://github.com/adamhaile/S). The API of S.js doesn't allow [reactive scope checking](/reactivity/#reactivity-libraries). You must manually disable reactivity when making calls outside a reactive scope to avoid memory leaks. You can do this by passing `{ reactive: false }` to your options (e.g. `.find({ ... }, { reactive: false })`). --- --- url: /reference/solid.md --- # @signaldb/solid ## solidReactivityAdapter (`default`) ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import solidReactivityAdapter from '@signaldb/solid' import { createEffect } from 'solid-js' const posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: solidReactivityAdapter, }) createEffect(() => { console.log(posts.find({ author: 'John' }).count()) }) ``` Reactivity adapter for usage with [solid.js](https://www.solidjs.com/docs/latest). The adapter supports [automatic cleanup](/reference/core/createreactivityadapter/#ondispose-callback-void-dependency-dependency-optional) through Solid's `onCleanup` and [reactive scope checking](/reference/core/createreactivityadapter/#isinscope-boolean-optional) through Solid's `getOwner()`: a query made outside a reactive owner (an effect, memo, component or root) is not made reactive, so you don't have to pass `{ reactive: false }` there yourself. Solid-js's integration with SignalDB leverages the power of Solid's reactive primitives to seamlessly connect with SignalDB's reactive local JavaScript database. Solid-js, known for its granular reactivity and efficient data management, provides a robust foundation for SignalDB to build upon. When using Solid-js, developers can effortlessly create and manage signals, which are core reactive primitives. These signals can then be integrated with SignalDB, allowing for real-time data updates and synchronization. This synergy between Solid-js and SignalDB ensures that developers can harness the full potential of both technologies, resulting in a more dynamic and responsive application. By utilizing Solid-js's automatic dependency tracking and SignalDB's MongoDB-like interface, developers can achieve a seamless flow of data, enhancing the overall user experience. In essence, the integration of Solid-js with SignalDB represents the convergence of two powerful technologies, offering developers a streamlined approach to building reactive applications. --- --- url: /reference/svelte.md --- # @signaldb/svelte ## svelteReactivityAdapter (`default`) ```js import { Collection, DefaultDataAdapter } from "@signaldb/core"; import svelteReactivityAdapter from "@signaldb/svelte"; const Posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: svelteReactivityAdapter, }); let items = $derived(Posts.find({}).fetch()); ``` Reactivity adapter for usage with [Svelte 5](https://svelte.dev/). In Svelte, reactivity is built into the very fabric of the framework, eliminating the need for manual change detection cycles. Svelte’s reactive declarations and writable stores automatically track and update state, ensuring that your UI remains consistently in sync with underlying data changes. When paired with SignalDB this natural reactivity is taken to the next level. SignalDB seamlessly integrates with Svelte’s reactive model by emitting live data updates. As changes occur in SignalDB, those updates are immediately propagated to Svelte’s stores, triggering automatic re-rendering of affected components. This ensures that every part of your application reflects the most current data without any extra boilerplate or manual intervention. This combination not only simplifies state management but also enhances performance by reducing unnecessary updates. Developers can leverage this synergy between Svelte’s inherent reactivity and SignalDB’s real-time capabilities to build highly efficient, responsive, and user-friendly web applications. --- --- url: /reference/usignal.md --- # @signaldb/usignal ## usignalReactivityAdapter (`default`) ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import usignalReactivityAdapter from '@signaldb/usignal' import { effect } from 'usignal' const posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: usignalReactivityAdapter, }) effect(() => { const cursor = posts.find({ author: 'John' }) console.log(cursor.count()) return () => { // usignal doesn't allow to do automatic cleanup, so we have to do it ourself cursor.cleanup() } }) ``` Reactivity adapter for usage with [µsignal](https://github.com/WebReflection/usignal). The API of usignal doesn't allow [automatic cleanup](/reference/core/createreactivityadapter/#ondispose-callback-void-dependency-dependency-optional) nor [reactive scope checking](/reference/core/createreactivityadapter/#isinscope-boolean-optional). With usignal, you can return a function from your `effect` that will be called on cleanup. Use this one to cleanup your cursors (see below for an example). You also must manually disable reactivity when making calls outside a reactive scope to avoid memory leaks. You can do this by passing `{ reactive: false }` to your options (e.g. `.find({ ... }, { reactive: false })`). --- --- url: /reference/vue.md --- # @signaldb/vue **Does Vue have signals?** Yes. Vue's `ref()` and `computed()` are signals in everything but name: they hold a value, track who reads them, and trigger updates in `watchEffect()`, `computed()` and templates when the value changes. Vue's documentation describes refs as its equivalent of the signals found in Solid, Preact or Angular. For a general introduction, see [JavaScript Signals Explained](/signals/). `@signaldb/vue` connects this reactivity system to SignalDB: queries on a SignalDB collection that run inside `watchEffect()` (or a `computed()`) become reactive and re-run whenever matching documents are inserted, updated or removed, locally or through [sync](/sync/). ## vueReactivityAdapter (`default`) ```js import { Collection, DefaultDataAdapter } from '@signaldb/core' import vueReactivityAdapter from '@signaldb/vue' import { watchEffect } from 'vue' const posts = new Collection('posts', new DefaultDataAdapter(), { reactivity: vueReactivityAdapter, }) watchEffect((onCleanup) => { const cursor = posts.find({ author: 'John' }) console.log(cursor.count()) onCleanup(() => cursor.cleanup()) }) ``` Reactivity adapter for usage with [Vue](https://vuejs.org/guide/essentials/reactivity-fundamentals.html). ::: info The API of Vue doesn't allow [automatic cleanup](/reference/core/createreactivityadapter/#ondispose-callback-void-dependency-dependency-optional) nor [reactive scope checking](/reference/core/createreactivityadapter/#isinscope-boolean-optional). In Vue, the function passed to the `watchEffect()` function gets a `onCleanup` callback that can be used to cleanup the effect. You have to use this to cleanup the cursor manually (see example above). You also must manually disable reactivity when making calls outside your `watchEffect()` function to avoid memory leaks. You can do this by passing `{ reactive: false }` to your options (e.g. `.find({ ... }, { reactive: false })`). ::: Vue.js is renowned for its powerful reactivity system, enabling developers to effortlessly bind and update the UI based on underlying data changes. Integrating Vue.js with signaldb, particularly with signals (often referred to as refs), is a fusion of two reactivity paradigms. Signals in Vue.js act as reactive reference pointers, and when their underlying values change, any dependent computation or rendering logic responds dynamically. Signaldb's reactivity adapter bridges the gap between Vue’s reactive ecosystem and the database layer. By leveraging this adapter, Vue.js developers can seamlessly synchronize their component state with signaldb collections, ensuring real-time data accuracy. If your Vue.js application doesn't currently implements a reactivity adapter for signaldb, it's straightforward to introduce one. This adapter ensures that dependencies are accurately tracked and efficiently notified when data mutations occur. Thus, integrating Vue.js with signaldb not only enhances the dynamic capabilities of your application but also enriches user experiences with instantaneous data reactivity. --- --- url: /guides.md --- # Guides Welcome to the Guides section of SignalDB. Here you will find a collection of guides that will help you get started with SignalDB and learn how to use it effectively. * [Angular](/guides/angular/) * [React](/guides/react/) * [SolidJS](/guides/solid-js/) * [Svelte 5](/guides/svelte/) * [Vue](/guides/vue/) --- --- url: /reference.md --- # Reference SignalDB consists of several packages of which each has indiviudal exports. ## Base ### `@signaldb/core` * [`Collection`](/reference/core/collection/) * [`Cursor`](/reference/core/cursor/) * [`reactiveTransaction`](/reference/core/reactivetransaction/) * [`DataAdapter`](/reference/core/dataadapter/) * [`DefaultDataAdapter`](/reference/core/defaultdataadapter/) * [`AsyncDataAdapter`](/reference/core/asyncdataadapter/) * [`WorkerDataAdapter`](/reference/core/workerdataadapter/) * [`AutoFetchDataAdapter`](/reference/core/autofetchdataadapter/) * [`createStorageAdapter`](/reference/core/createstorageadapter/) * [`createReactivityAdapter`](/reference/core/createreactivityadapter/) * [Utilities](/reference/core/utilities/) — `serializeValue`, `get`, `isEqual`, `modify`, `randomId`, `EventEmitter`, `reactiveOrAsync`, `unwrap` ### `@signaldb/sync` * [`SyncManager`](/reference/sync/) ## Integrations ### `@signaldb/react` * [`createUseReactivityHook`](/reference/react/) ## Storage Adapters ### `@signaldb/fs` * [`createFileSystemAdapter`](/reference/fs/) ### `@signaldb/generic-fs` * [`createGenericFSAdapter`](/reference/generic-fs/) ### `@signaldb/indexeddb` * [`createIndexedDBAdapter`](/reference/indexeddb/) ### `@signaldb/localstorage` * [`createLocalStorageAdapter`](/reference/localstorage/) ### `@signaldb/opfs` * [`createOPFSAdapter`](/reference/opfs/) ## Reactivity Adapters ### `@signaldb/angular` * [`angularReactivityAdapter`](/reference/angular/) ### `@signaldb/maverickjs` * [`maverickjsReactivityAdapter`](/reference/maverickjs/) ### `@signaldb/meteor` * [`meteorReactivityAdapter`](/reference/meteor/) ### `@signaldb/mobx` * [`mobxReactivityAdapter`](/reference/mobx/) ### `@signaldb/oby` * [`obyReactivityAdapter`](/reference/oby/) ### `@signaldb/preact` * [`preactReactivityAdapter`](/reference/preact/) ### `@signaldb/reactively` * [`reactivelyReactivityAdapter`](/reference/reactively/) ### `@signaldb/sinuous` * [`sinuousReactivityAdapter`](/reference/sinuous/) ### `@signaldb/sjs` * [`sjsReactivityAdapter`](/reference/sjs/) ### `@signaldb/solid` * [`solidReactivityAdapter`](/reference/solid/) ### `@signaldb/usignal` * [`usignalReactivityAdapter`](/reference/usignal/) ### `@signaldb/vue` * [`vueReactivityAdapter`](/reference/vue/)