Merge pull request #11 from valtiojs/global

Global

Author: overthemike

examples/README.md

@@ -0,0 +1,166 @@
+# Valtio Plugin Examples
+
+This directory contains examples demonstrating how to use the Valtio Plugin System.
+
+## Examples
+
+### 1. Logging Plugin (`logging-plugin.ts`)
+
+A comprehensive example showing:
+
+- ✅ **Global Plugin Registration**: Register plugins that affect all proxy instances
+- ✅ **TypeScript Support**: Full autocomplete and type safety when importing from 'valtio'
+- ✅ **Plugin API Access**: Access plugin methods via `proxy.pluginId` 
+- ✅ **Lifecycle Hooks**: Implement `onInit`, `beforeChange`, `afterChange` hooks
+- ✅ **Method Chaining**: Use `proxy.use().method()` pattern
+- ✅ **Instance Creation**: Create independent proxy instances with `proxy.createInstance()`
+
+## Running the Examples
+
+### Prerequisites
+
+Make sure you have the plugin built:
+
+```bash
+npm run build
+```
+
+### Quick Start
+
+```bash
+# Run the JavaScript example (easiest)
+node examples/logging-example.js
+
+# Verify TypeScript compiles correctly
+npx tsc --noEmit examples/typescript-example.ts
+
+# Run TypeScript example with tsx (if you have it installed)
+npx tsx examples/typescript-example.ts
+```
+
+### Available Examples
+
+1. **`logging-example.js`** - JavaScript version, runs immediately
+2. **`logging-plugin.ts`** - Full TypeScript version with detailed documentation  
+3. **`typescript-example.ts`** - Focused on TypeScript autocomplete features
+
+## Key Features Demonstrated
+
+### TypeScript Module Augmentation
+
+When you import any export from this package, the `proxy` from 'valtio' automatically gets enhanced:
+
+```typescript
+import { proxy } from 'valtio'
+import { ValtioPlugin } from 'valtio-plugin' // This enables augmentation
+
+// Now you have full TypeScript support:
+proxy.use(myPlugin)           // ✅ Autocomplete
+proxy.clearPlugins()          // ✅ Autocomplete  
+proxy.createInstance()        // ✅ Autocomplete
+proxy.getPlugins()           // ✅ Autocomplete
+```
+
+### Plugin API Access
+
+Access your plugins as properties with full typing:
+
+```typescript
+const loggingPlugin = createLoggingPlugin()
+proxy.use(loggingPlugin)
+
+// Access with TypeScript support
+const logger = proxy.logger as LoggingPlugin
+logger.info('Hello world!')    // ✅ Autocomplete
+logger.getLogCount()          // ✅ Autocomplete
+```
+
+### Global vs Instance Plugins
+
+```typescript
+// Global plugins affect ALL proxy instances
+proxy.use(globalLoggingPlugin)
+
+const store1 = proxy({ count: 0 })    // Logging enabled
+const store2 = proxy({ name: 'John' }) // Logging enabled
+
+// Instance plugins only affect that instance
+const instance = proxy.createInstance()
+instance.use(instanceOnlyPlugin)
+
+const store3 = instance({ value: 'test' }) // Both global AND instance plugins
+const store4 = proxy({ other: 'data' })     // Only global plugins
+```
+
+## Creating Your Own Plugins
+
+### Basic Plugin Structure
+
+```typescript
+import { ValtioPlugin } from 'valtio-plugin'
+
+const myPlugin: ValtioPlugin = {
+  id: 'my-plugin',           // Required: unique identifier
+  name: 'My Plugin',         // Optional: display name
+  
+  // Lifecycle hooks (all optional)
+  onInit: () => {
+    console.log('Plugin initialized')
+  },
+  
+  onAttach: (proxyFactory) => {
+    console.log('Plugin attached to factory')
+  },
+  
+  beforeChange: (path, newValue, oldValue, state) => {
+    console.log(`Changing ${path.join('.')}`)
+    return true // Return false to prevent the change
+  },
+  
+  afterChange: (path, newValue, state) => {
+    console.log(`Changed ${path.join('.')}`)
+  },
+  
+  onSubscribe: (proxyObject, callback) => {
+    console.log('New subscription created')
+  },
+  
+  alterSnapshot: (snapshot) => {
+    // Modify snapshot before it's returned
+    return { ...snapshot, _modified: true }
+  },
+  
+  // Custom plugin methods
+  myMethod: () => 'Hello from plugin!',
+  customAction: (data: any) => { /* do something */ }
+}
+```
+
+### Plugin with TypeScript Interface
+
+```typescript
+interface MyPlugin extends ValtioPlugin {
+  myMethod: () => string
+  customAction: (data: any) => void
+}
+
+const createMyPlugin = (): MyPlugin => ({
+  id: 'my-plugin',
+  myMethod: () => 'Hello!',
+  customAction: (data) => console.log(data)
+})
+
+// Usage with typing
+proxy.use(createMyPlugin())
+const plugin = proxy['my-plugin'] as MyPlugin
+plugin.myMethod() // ✅ Full TypeScript support
+```
+
+## Best Practices
+
+1. **Use unique plugin IDs** to avoid conflicts
+2. **Implement TypeScript interfaces** for better developer experience  
+3. **Handle errors gracefully** in plugin hooks
+4. **Use global plugins sparingly** - they affect all proxy instances
+5. **Prefer instance plugins** for application-specific functionality
+6. **Document your plugin APIs** for other developers

examples/autocomplete-demo.ts

@@ -0,0 +1,43 @@
+/**
+ * TypeScript Autocomplete Demo
+ * 
+ * Open this file in VS Code or your TypeScript-enabled editor
+ * to see the autocomplete in action!
+ */
+
+import { proxy } from 'valtio'
+import { ValtioPlugin } from '../src/index'
+
+// Simple plugin for demonstration
+const demoPlugin: ValtioPlugin = {
+  id: 'demo',
+  sayHello: () => 'Hello from plugin!'
+}
+
+// Register the plugin
+proxy.use(demoPlugin)
+
+// 🎯 TRY THIS: Place your cursor after the dot and see the autocomplete!
+
+// Global proxy methods (these should all have autocomplete):
+proxy.use          // ✅ Should show: (pluginOrPlugins: ValtioPlugin | ValtioPlugin[]) => typeof proxy
+proxy.clearPlugins // ✅ Should show: () => void
+proxy.getPlugins   // ✅ Should show: () => readonly ValtioPlugin[]
+proxy.removePlugin // ✅ Should show: (pluginId: string) => boolean
+proxy.createInstance // ✅ Should show: () => ProxyFactory
+proxy.subscribe    // ✅ Should show: subscribe function
+proxy.snapshot     // ✅ Should show: snapshot function
+
+// Plugin access (these should work too):
+const plugin = (proxy as any).demo // Should be accessible
+
+// Instance methods (these should have autocomplete):
+const instance = proxy.createInstance()
+instance.use       // ✅ Should show: (pluginOrPlugins: ValtioPlugin | ValtioPlugin[]) => ProxyFactory
+instance.dispose   // ✅ Should show: () => void
+instance.subscribe // ✅ Should show: subscribe function
+instance.snapshot  // ✅ Should show: snapshot function
+
+console.log('✅ If you see autocomplete for all the methods above, the TypeScript augmentation is working!')
+
+export {}

examples/logging-example.js

@@ -0,0 +1,100 @@
+/**
+ * Simple Logging Plugin Example (JavaScript)
+ * 
+ * This demonstrates the logging plugin functionality using the built dist files.
+ */
+
+import { proxy } from '../dist/index.js'
+
+// Create the logging plugin
+const createLoggingPlugin = () => {
+  let logCount = 0
+  
+  const log = (level, message) => {
+    const timestamp = new Date().toISOString()
+    console.log(`[${timestamp}] [${level.toUpperCase()}] ${message}`)
+    logCount++
+  }
+
+  return {
+    id: 'logger',
+    name: 'Logging Plugin',
+    
+    // Lifecycle hooks
+    onInit: () => {
+      log('info', '🚀 Logging plugin initialized')
+    },
+    
+    beforeChange: (path, newValue, oldValue) => {
+      log('debug', `📝 Changing ${path.join('.')} from ${JSON.stringify(oldValue)} to ${JSON.stringify(newValue)}`)
+      return true // Allow the change
+    },
+    
+    afterChange: (path, newValue) => {
+      log('info', `✅ Changed ${path.join('.')} to ${JSON.stringify(newValue)}`)
+    },
+    
+    // Plugin API methods
+    debug: (message) => log('debug', message),
+    info: (message) => log('info', message),
+    warn: (message) => log('warn', message),
+    error: (message) => log('error', message),
+    getLogCount: () => logCount
+  }
+}
+
+// Example usage
+console.log('=== Valtio Plugin System - Logging Example ===\n')
+
+// 1. Create and register the global logging plugin
+const loggingPlugin = createLoggingPlugin()
+proxy.use(loggingPlugin)
+
+// 2. Access plugin methods
+const logger = proxy.logger
+
+// 3. Use plugin methods directly
+logger.info('Logger is ready! 🎉')
+logger.debug('This is a debug message')
+
+// 4. Create a store - the plugin will automatically log changes
+const userStore = proxy({
+  name: 'John Doe',
+  age: 30,
+  preferences: {
+    theme: 'dark',
+    notifications: true
+  }
+})
+
+// 5. Make changes - watch the logging in action
+logger.info('Making changes to user store...')
+
+userStore.name = 'Jane Smith'
+userStore.age = 25
+userStore.preferences.theme = 'light'
+userStore.preferences.notifications = false
+
+// 6. Add new properties
+logger.info('Adding new properties...')
+userStore.email = '[email protected]'
+
+// 7. Show log statistics
+console.log(`\n📊 Total log entries: ${logger.getLogCount()}`)
+
+// 8. Demonstrate other global proxy methods
+logger.info('Demonstrating other proxy methods...')
+
+const allPlugins = proxy.getPlugins()
+console.log(`📦 Registered plugins: ${allPlugins.map(p => p.name || p.id).join(', ')}`)
+
+// 9. Create an instance to show the difference
+const instance = proxy.createInstance()
+const instanceStore = instance({ count: 0 })
+
+logger.info('Created instance store - this change will be logged by global plugin')
+instanceStore.count = 42
+
+console.log('\n✅ Example completed! Check the logs above to see the plugin in action.')
+
+export { createLoggingPlugin }