feat(plugin): category

Author: Akryum

docs/guide/plugin/setup.md

@@ -20,6 +20,38 @@ export default definePlugin({
 
 The `setup` function is called when the plugin is registered. It receives a `pluginApi` object that contains useful methods to customize the store.
 
+## Category
+
+Plugins can be categorized to define their role in the data flow. The available categories are:
+
+- `virtual`: Plugins that provide virtual/in-memory collections that do not have any persistent storage.
+- `local`: Plugins that handle local data sources in the current device, such as saving it to a client-side database or storage such as IndexedDB or LocalStorage.
+- `remote`: Plugins that handle remote data sources, such as REST APIs or GraphQL APIs.
+- `processing`: Plugins that process data, such as transforming or validating it.
+
+By default plugins will be sorted based on their category in the following order:
+
+1. `virtual`
+2. `local`
+3. `remote`
+4. `processing`
+
+You can customize the sorting using the `before` and `after` options (see [Sorting plugins](#sorting-plugins)).
+
+```ts{5-7}
+import { definePlugin } from '@rstore/vue'
+
+export default definePlugin({
+  name: 'my-plugin',
+  // Will be after 'virtual' and 'local' plugins
+  // and before 'processing' plugins
+  category: 'remote',
+  setup(pluginApi) {
+    // Plugin code goes here
+  },
+})
+```
+
 ## Hooks
 
 Hooks are the primary way to extend the functionality of the store. They allow you to run custom code at different points in the lifecycle of the store. The hooks are called in the order they are defined.
@@ -117,14 +149,32 @@ export default definePlugin({
 
 ## Sorting plugins
 
-Plugins are sorted based on their dependencies. You can specify that a plugin should be loaded before or after another plugin using the `before` and `after` options:
+Plugins are sorted based on their dependencies and category. You can specify that a plugin should be loaded before or after another plugin or category using the `before` and `after` options:
 
 ```ts
 import { definePlugin } from '@rstore/vue'
 
 export default definePlugin({
   name: 'my-plugin',
-  before: ['another-plugin'],
-  after: ['yet-another-plugin'],
+  before: {
+    plugins: ['another-plugin'],
+    categories: ['remote'],
+  },
+  after: {
+    plugins: ['yet-another-plugin'],
+    categories: ['virtual'],
+  },
 })
 ```
+
+Each property of `before` and `after` is optional, you can either specify `plugins`, `categories`, or both.
+
+::: warning
+Be mindful of circular dependencies when using `before` and `after`. For example, if Plugin A is set to load after Plugin B, and Plugin B is set to load after Plugin A, this will create a circular dependency that cannot be resolved. The system will detect such circular dependencies and handle them gracefully by skipping the remaining sorting rules (with a warning printed to the console).
+
+Prioritization is done in the following order:
+
+- `before.plugins` and `after.plugins` have the highest priority.
+- `before.categories` and `after.categories` have the next priority.
+- Default category order is applied last.
+:::

packages/core/src/plugin.ts

@@ -1,4 +1,4 @@
-import type { CollectionDefaults, HookPayload, Plugin, RegisteredPlugin, StoreCore, StoreSchema } from '@rstore/shared'
+import type { CollectionDefaults, HookPayload, Plugin, PluginCategory, RegisteredPlugin, StoreCore, StoreSchema } from '@rstore/shared'
 
 const mergedCollectionDefaultsFields = [
   'computed',
@@ -63,18 +63,31 @@ export function definePlugin(plugin: Plugin): Plugin {
   return plugin
 }
 
+const pluginCategories: PluginCategory[] = [
+  'virtual',
+  'local',
+  'remote',
+  'processing',
+]
+
 export function sortPlugins(plugins: RegisteredPlugin[]): RegisteredPlugin[] {
   const pluginByName = new Map<string, RegisteredPlugin>()
   const beforeRelations = new Map<string, Set<string>>()
   const afterRelations = new Map<string, Set<string>>()
 
+  // Cache plugins by category for better performance
+  const pluginsByCategory = new Map<PluginCategory, RegisteredPlugin[]>()
+  for (const category of pluginCategories) {
+    pluginsByCategory.set(category, plugins.filter(p => p.category === category))
+  }
+
   // Process before/after relationships
   for (const plugin of plugins) {
     pluginByName.set(plugin.name, plugin)
 
-    // Process 'before' relationships
-    if (plugin.before) {
-      for (const beforeName of plugin.before) {
+    // Process 'before' relationships (highest priority)
+    if (plugin.before?.plugins) {
+      for (const beforeName of plugin.before.plugins) {
         if (!beforeRelations.has(plugin.name)) {
           beforeRelations.set(plugin.name, new Set())
         }
@@ -87,9 +100,9 @@ export function sortPlugins(plugins: RegisteredPlugin[]): RegisteredPlugin[] {
       }
     }
 
-    // Process 'after' relationships
-    if (plugin.after) {
-      for (const afterName of plugin.after) {
+    // Process 'after' relationships (highest priority)
+    if (plugin.after?.plugins) {
+      for (const afterName of plugin.after.plugins) {
         if (!afterRelations.has(plugin.name)) {
           afterRelations.set(plugin.name, new Set())
         }
@@ -101,28 +114,102 @@ export function sortPlugins(plugins: RegisteredPlugin[]): RegisteredPlugin[] {
         beforeRelations.get(afterName)!.add(plugin.name)
       }
     }
+
+    // Process 'before' category relationships (medium priority)
+    if (plugin.before?.categories) {
+      for (const beforeCategory of plugin.before.categories) {
+        const categoryPlugins = pluginsByCategory.get(beforeCategory as PluginCategory) || []
+        for (const p of categoryPlugins) {
+          if (p.name !== plugin.name) {
+            if (!beforeRelations.has(plugin.name)) {
+              beforeRelations.set(plugin.name, new Set())
+            }
+            beforeRelations.get(plugin.name)!.add(p.name)
+
+            if (!afterRelations.has(p.name)) {
+              afterRelations.set(p.name, new Set())
+            }
+            afterRelations.get(p.name)!.add(plugin.name)
+          }
+        }
+      }
+    }
+
+    // Process 'after' category relationships (medium priority)
+    if (plugin.after?.categories) {
+      for (const afterCategory of plugin.after.categories) {
+        const categoryPlugins = pluginsByCategory.get(afterCategory as PluginCategory) || []
+        for (const p of categoryPlugins) {
+          if (p.name !== plugin.name) {
+            if (!afterRelations.has(plugin.name)) {
+              afterRelations.set(plugin.name, new Set())
+            }
+            afterRelations.get(plugin.name)!.add(p.name)
+
+            if (!beforeRelations.has(p.name)) {
+              beforeRelations.set(p.name, new Set())
+            }
+            beforeRelations.get(p.name)!.add(plugin.name)
+          }
+        }
+      }
+    }
+  }
+
+  // Add default category ordering based on pluginCategories array (lowest priority)
+  for (let i = 0; i < pluginCategories.length - 1; i++) {
+    const currentCategory = pluginCategories[i]!
+    const nextCategory = pluginCategories[i + 1]!
+
+    const currentPlugins = pluginsByCategory.get(currentCategory) || []
+    const nextPlugins = pluginsByCategory.get(nextCategory) || []
+
+    for (const current of currentPlugins) {
+      for (const next of nextPlugins) {
+        if (!beforeRelations.has(current.name)) {
+          beforeRelations.set(current.name, new Set())
+        }
+        beforeRelations.get(current.name)!.add(next.name)
+
+        if (!afterRelations.has(next.name)) {
+          afterRelations.set(next.name, new Set())
+        }
+        afterRelations.get(next.name)!.add(current.name)
+      }
+    }
   }
 
   // Topological sort using depth-first search
   const sorted: RegisteredPlugin[] = []
   const visited = new Set<string>()
   const visiting = new Set<string>()
+  const circularDependencies = new Set<string>()
 
-  function visit(name: string) {
+  function visit(name: string, path: string[] = []) {
     if (visited.has(name))
-      return
+      return true
+    if (circularDependencies.has(name))
+      return false
     if (visiting.has(name)) {
-      throw new Error(`Circular dependency detected for plugin ${name}`)
+      const cycle = [...path, name].join(' -> ')
+      console.warn(`[rstore] Circular dependency detected: ${cycle}`)
+      circularDependencies.add(name)
+      return false
     }
 
     visiting.add(name)
+    path.push(name)
 
     // Process 'after' dependencies first (they should come before this plugin)
     const afterDeps = afterRelations.get(name)
     if (afterDeps) {
       for (const afterName of afterDeps) {
         if (pluginByName.has(afterName)) {
-          visit(afterName)
+          if (!visit(afterName, [...path])) {
+            // If we encounter a circular dependency, we'll still continue with other plugins
+            // but skip this dependency
+            console.warn(`[rstore] Skipping circular dependency from ${name} to ${afterName}`)
+          }
         }
       }
     }
@@ -134,6 +221,8 @@ export function sortPlugins(plugins: RegisteredPlugin[]): RegisteredPlugin[] {
     if (plugin) {
       sorted.push(plugin)
     }
+
+    return true
   }
 
   // Process all plugins
@@ -143,5 +232,12 @@ export function sortPlugins(plugins: RegisteredPlugin[]): RegisteredPlugin[] {
     }
   }
 
+  // Handle any remaining plugins that weren't visited due to circular dependencies
+  for (const plugin of plugins) {
+    if (!sorted.includes(plugin)) {
+      sorted.push(plugin)
+    }
+  }
+
   return sorted
 }