feat: devtools scaffolding

.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

eslint.config.mjs

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

package.json

@@ -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

packages/base/core/__tests__/Collection.spec.ts

@@ -566,6 +566,8 @@ describe('Collection', () => {
     })
 
     it('should toggle debug mode', () => {
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
       Collection.debugMode = false
       const col = new Collection<any>()
 

packages/base/core/src/Collection/index.ts

@@ -26,6 +26,7 @@ export type { ObserveCallbacks } from './Observer'
 export { default as createIndex } from './createIndex'
 
 export interface CollectionOptions<T extends BaseItem<I>, I, U = T> {
+  name?: string,
   memory?: MemoryAdapter,
   reactivity?: ReactivityAdapter,
   transform?: Transform<T, U>,
@@ -136,10 +137,19 @@ export default class Collection<
   I = any,
   U = T,
 > extends EventEmitter<CollectionEvents<T, U>> {
-  static collections: Collection<any, any>[] = []
-  static debugMode = false
-  static batchOperationInProgress = false
-  static fieldTracking = false
+  private static collections: Collection<any, any>[] = []
+  private static debugMode = false
+  private static batchOperationInProgress = false
+  private static fieldTracking = false
+  private static onCreationCallbacks: ((collection: Collection<any>) => void)[] = []
+
+  static getCollections() {
+    return Collection.collections
+  }
+
+  static onCreation(callback: (collection: Collection<any>) => void) {
+    Collection.onCreationCallbacks.push(callback)
+  }
 
   /**
    * Enables debug mode for all collections.
@@ -176,6 +186,7 @@ export default class Collection<
     Collection.batchOperationInProgress = false
   }
 
+  public readonly name: string
   private options: CollectionOptions<T, I, U>
   private persistenceAdapter: PersistenceAdapter<T, I> | null = null
   private isPullingSignal: Signal<boolean>
@@ -196,6 +207,7 @@ export default class Collection<
    * @template I - The type of the unique identifier for the items.
    * @template U - The transformed item type after applying transformations (default is T).
    * @param options - Optional configuration for the collection.
+   * @param options.name - An optional name for the collection.
    * @param options.memory - The in-memory adapter for storing items.
    * @param options.reactivity - The reactivity adapter for observing changes in the collection.
    * @param options.transform - A transformation function to apply to items when retrieving them.
@@ -207,6 +219,7 @@ export default class Collection<
   constructor(options?: CollectionOptions<T, I, U>) {
     super()
     Collection.collections.push(this)
+    this.name = options?.name ?? `${this.constructor.name}-${randomId()}`
     this.options = {
       memory: [],
       ...options,
@@ -373,6 +386,7 @@ export default class Collection<
           this.emit('persistence.error', error instanceof Error ? error : new Error(error as string))
         })
     }
+    Collection.onCreationCallbacks.forEach(callback => callback(this))
   }
 
   /**

packages/base/core/src/devtools.ts

@@ -0,0 +1,38 @@
+import Collection from './Collection'
+
+const devtoolsInProductionWarning = `
+
+
+[@signaldb/core] !! WARNING !!
+You are running @signaldb/devtools in production mode.
+This can have a negative impact on performance and may expose sensitive information.
+Please move @signaldb/devtools to development dependencies to disable it in production.
+
+
+`
+
+async function loadDevtools() {
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
+  return import('@signaldb/devtools')
+    .then(() => true)
+    .catch((error) => {
+      if (error.code === 'MODULE_NOT_FOUND') return false
+      throw error
+    })
+}
+
+/**
+ * Loads the devtools in production mode and logs a warning if in production.
+ */
+export default function loadDevtoolsInProduction() {
+  const isProduction = process.env.NODE_ENV === 'production'
+  void loadDevtools().then((devtoolsLoaded) => {
+    if (!devtoolsLoaded) return
+
+    Collection.enableDebugMode()
+
+    // eslint-disable-next-line no-console
+    if (isProduction) console.warn(devtoolsInProductionWarning)
+  })
+}

packages/base/core/src/index.ts

@@ -1,3 +1,5 @@
+import loadDevtoolsInProduction from './devtools'
+
 export type { default as ReactivityAdapter } from './types/ReactivityAdapter'
 export type { default as MemoryAdapter } from './types/MemoryAdapter'
 export type {
@@ -28,3 +30,5 @@ export { default as createReactivityAdapter } from './createReactivityAdapter'
 export { default as isEqual } from './utils/isEqual'
 export { default as modify } from './utils/modify'
 export { default as randomId } from './utils/randomId'
+
+loadDevtoolsInProduction()

packages/base/core/vite.config.mts

@@ -28,6 +28,7 @@ export default defineConfig({
         format: 'es',
       },
       external: [
+        '@signaldb/devtools',
         'fast-sort',
         'mingo',
         'mingo/updater',