feat: add developer tools

.github/workflows/checks.yaml

@@ -107,6 +107,7 @@ jobs:
       - name: unit testing
         run: |
           npm run build -w packages/base/core
+          npm run build -w packages/devtools/devtools
           npm test -- --coverage run
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v5

docs/.vitepress/config.mts

@@ -58,6 +58,7 @@ export default withMermaid({
             { text: 'Data Persistence', link: '/data-persistence/' },
             { text: 'Reactivity', link: '/reactivity/' },
             { text: 'Synchronization', link: '/sync/' },
+            { text: 'Developer Tools', link: '/devtools/' },
             { text: 'Upgrade to v1', link: '/upgrade/v1/' },
           ],
         },

docs/devtools/index.md

@@ -0,0 +1,69 @@
+---
+head:
+- - link
+  - rel: canonical
+    href: https://signaldb.js.org/devtools/
+- - meta
+  - name: og:type
+    content: article
+- - meta
+  - name: og:url
+    content: https://signaldb.js.org/devtools/
+- - meta
+  - name: og:title
+    content: Developer Tools | SignalDB
+- - meta
+  - name: og:description
+    content: Learn how to use the developer tools in SignalDB to debug and inspect the state of your SignalDB instance at runtime.
+- - meta
+  - name: description
+    content: Learn how to use the developer tools in SignalDB to debug and inspect the state of your SignalDB instance at runtime.
+- - meta
+  - name: keywords
+    content: developer tools, SignalDB, debugging, inspecting, state, runtime, queries, mutations, performance
+---
+
+# 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
+
+The developer tools will load automatically when you start your development server. 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`.
+
+The developer tools will open and you should the following tabs.
+
+::: tip
+The developer tools will try to resolve names for your collections. You can provide a name for your collection by passing the `name` property to the options of the collection constructor.
+:::
+
+### 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.

docs/reference/core/collection/index.md

@@ -36,6 +36,22 @@ The Collection class is designed to manage and manipulate collections of data in
 
 Enables or disables field tracking for all collections. See [Field-Level Reactivity](/queries/#field-level-reactivity) for more information.
 
+### `batch(callback: () => void)`
+
+If you need to execute many operations at once in multiple collections, you can use the global `Collection.batch()` method. This method will execute all operations inside the callback without rebuilding the index on every change.
+
+### `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.
+
+### `enableDebugMode()`
+
+Enables debug mode for all collections. This will enable measurements for query timings and other debug information.
+
 ## Constructor
 
 ```js
@@ -46,6 +62,7 @@ Constructs a new Collection object.
 
 Parameters
 * options (Optional): An object specifying various options for the collection. Options include:
+  * name: An optional name for the collection to make it easier to identify. This name will also be used in the developer tools.
   * memory: A [MemoryAdapter](/core-concepts/#memory-adapters) for storing items in memory.
   * reactivity: A [ReactivityAdapter](/reactivity/) for enabling reactivity.
   * persistence: A [PersistenceAdapter](/data-persistence/) for enabling persistent storage.

eslint.config.mjs

@@ -72,6 +72,8 @@ export default tseslint.config(
           args: true,
           props: true,
           refs: true,
+          DevTools: true,
+          Props: true,
         },
       }],
       'unicorn/no-null': 'off',

package.json

@@ -8,7 +8,7 @@
     "test": "vitest",
     "typedoc": "typedoc",
     "coverage": "vitest run --coverage",
-    "build": "(cd packages/base/core && npm run build) && npm run build -w packages/base && npm run build -w packages/integrations && npm run build -w packages/persistence-adapters && npm run build -w packages/reactivity-adapters",
+    "build": "(cd packages/base/core && npm run build) && npm run build -w packages/base && npm run build -w packages/devtools && npm run build -w packages/integrations && npm run build -w packages/persistence-adapters && npm run build -w packages/reactivity-adapters",
     "type-check": "tsc --noEmit",
     "docs:dev": "vitepress dev docs",
     "docs:build": "npm run build && npm run build -w examples && npm run copy -w examples && npm run typedoc && npm run docs:build-vitepress",
@@ -22,6 +22,7 @@
     "packages/integrations/*",
     "packages/persistence-adapters/*",
     "packages/reactivity-adapters/*",
+    "packages/devtools/*",
     "packages/base/*"
   ],
   "devDependencies": {

packages/base/core/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+* Support for @signaldb/devtools
+* Allow specifying a name for a collection
+* Added `Collections.onCreation` method to listen for collection creation
+* Added `Collections.getCollections` method to get all collections
+
 ## [1.0.0] - 2024-12-16
 
 ### Added