@maravilla-labs/platform 0.1.0

package/ENHANCEMENT_SUMMARY.md

@@ -0,0 +1,111 @@
+# JSDoc Enhancement Summary
+
+## 📋 What Was Added
+
+### 1. Comprehensive Interface Documentation (`types.ts`)
+
+**KvNamespace Interface:**
+- ✅ Detailed method descriptions with parameter explanations
+- ✅ Practical usage examples for each method
+- ✅ Parameter options documentation
+- ✅ Return type explanations
+
+**Database Interface:**
+- ✅ MongoDB-style API documentation
+- ✅ Query filter examples
+- ✅ Update operator documentation
+- ✅ Error handling guidance
+
+**Supporting Types:**
+- ✅ KvListResult with pagination details
+- ✅ DbFindOptions with sorting examples
+- ✅ PlatformEnv usage patterns
+
+### 2. Enhanced Function Documentation (`index.ts`)
+
+**getPlatform():**
+- ✅ Environment detection explanation
+- ✅ Configuration options documentation
+- ✅ Complete usage examples
+- ✅ Development vs production scenarios
+
+**clearPlatformCache():**
+- ✅ Testing utility documentation
+- ✅ Use case explanations
+- ✅ Practical examples
+
+### 3. Internal API Documentation (`remote-client.ts`)
+
+**RemoteKvNamespace & RemoteDatabase:**
+- ✅ Internal implementation details marked with @internal
+- ✅ HTTP client documentation
+- ✅ Error handling patterns
+
+**createRemoteClient():**
+- ✅ Development server integration docs
+- ✅ Multi-tenancy support explanation
+
+### 4. Package Documentation
+
+**File Header:**
+- ✅ Comprehensive package overview
+- ✅ Environment detection explanation
+- ✅ Feature highlights
+- ✅ Quick start examples
+
+### 5. Additional Resources
+
+**JSDOC_GUIDE.md:**
+- ✅ IDE integration instructions
+- ✅ Feature explanations
+- ✅ Usage patterns
+- ✅ Documentation generation guide
+
+**example-usage.ts:**
+- ✅ Practical implementation examples
+- ✅ JSDoc feature demonstrations
+- ✅ Error handling patterns
+
+**Updated README.md:**
+- ✅ JSDoc feature highlights
+- ✅ IDE integration information
+- ✅ Enhanced developer experience section
+
+## 🎯 Developer Experience Improvements
+
+### IDE Features Now Available:
+1. **Hover Documentation**: Detailed explanations appear on hover
+2. **Parameter IntelliSense**: Parameter descriptions while typing
+3. **Auto-completion**: Enhanced suggestions with descriptions
+4. **Example Code**: Practical examples in documentation
+5. **Error Context**: Understanding of error scenarios
+6. **Type Safety**: Combined TypeScript + JSDoc validation
+
+### Supported IDEs:
+- ✅ VS Code (full integration)
+- ✅ WebStorm/IntelliJ (full integration)
+- ✅ Any TypeScript-compatible editor
+
+### Real-world Examples Added:
+- ✅ KV storage patterns (caching, sessions, configuration)
+- ✅ Database operations (CRUD, queries, aggregation)
+- ✅ Multi-tenancy usage
+- ✅ Error handling patterns
+- ✅ Testing scenarios
+
+## 🔧 Technical Fixes
+
+- ✅ Fixed TypeScript type assertion issues in remote-client.ts
+- ✅ Added proper return type annotations
+- ✅ Improved error handling documentation
+- ✅ Enhanced parameter validation docs
+
+## 🚀 Impact
+
+Developers using this package will now get:
+- **Better onboarding**: Clear examples and explanations
+- **Fewer errors**: Understanding of proper usage patterns
+- **Faster development**: IDE assistance while coding
+- **Better maintenance**: Clear API contracts and examples
+
+The JSDoc comments provide a complete reference without leaving the IDE, making the development experience much more streamlined and professional.

package/JSDOC_GUIDE.md

@@ -0,0 +1,98 @@
+# JSDoc Documentation Guide
+
+This package now includes comprehensive JSDoc comments for enhanced developer experience in IDEs.
+
+## IDE Integration
+
+### VS Code
+The JSDoc comments will automatically provide:
+- **Hover tooltips** with detailed descriptions
+- **IntelliSense suggestions** with parameter descriptions
+- **Type information** and examples
+- **Parameter hints** while typing function calls
+
+### WebStorm/IntelliJ
+- Full JSDoc integration with type hints
+- Parameter documentation in completion popups
+- Hover documentation
+
+### Other TypeScript-compatible IDEs
+Most modern IDEs that support TypeScript will display the JSDoc information.
+
+## What's Included
+
+### Function Documentation
+- **Purpose**: Clear description of what each function does
+- **Parameters**: Detailed parameter descriptions with types
+- **Return values**: What the function returns
+- **Examples**: Practical usage examples
+- **Error handling**: When functions might throw errors
+
+### Interface Documentation
+- **Property descriptions**: What each property represents
+- **Usage examples**: How to use the interfaces
+- **Relationships**: How interfaces relate to each other
+
+### Examples in JSDoc
+Each major function includes practical examples showing:
+- Basic usage
+- Advanced scenarios
+- Error handling
+- Best practices
+
+## Using the Documentation
+
+### Getting Platform Instance
+```typescript
+import { getPlatform } from '@maravilla/platform';
+
+// Hover over getPlatform to see full documentation
+const platform = getPlatform({
+  devServerUrl: 'http://localhost:3001',
+  tenant: 'my-app'
+});
+```
+
+### KV Operations
+```typescript
+// Hover over any method to see documentation
+await platform.env.KV.cache.put('key', 'value', {
+  expirationTtl: 3600 // See JSDoc for TTL details
+});
+
+const value = await platform.env.KV.cache.get('key');
+```
+
+### Database Operations
+```typescript
+// Full documentation available in IDE
+const result = await platform.env.DB.insertOne('users', {
+  name: 'John Doe',
+  email: 'john@example.com'
+});
+
+// See parameter documentation while typing
+const users = await platform.env.DB.find('users', 
+  { active: true }, 
+  { limit: 10, sort: { createdAt: -1 } }
+);
+```
+
+## IDE Features Enabled
+
+1. **Parameter IntelliSense**: As you type function parameters, see descriptions
+2. **Hover Documentation**: Hover over any function/method for full docs
+3. **Auto-completion**: Better suggestions with descriptions
+4. **Type Safety**: Combined with TypeScript for full type checking
+5. **Examples**: See practical examples right in your IDE
+
+## Building Documentation
+
+If you want to generate HTML documentation from the JSDoc comments:
+
+```bash
+npm install -g typedoc
+typedoc src/index.ts --out docs
+```
+
+This will generate browsable HTML documentation from the JSDoc comments.

package/README.md

@@ -0,0 +1,284 @@
+# @maravilla/platform
+
+Universal platform client for Maravilla Runtime that provides seamless access to KV, Database, and other platform services in both development and production environments.
+
+## 🎯 Enhanced Developer Experience
+
+This package includes **comprehensive JSDoc documentation** for enhanced IDE support:
+- **IntelliSense** with detailed parameter descriptions
+- **Hover tooltips** with examples and usage guidance  
+- **Type hints** with real-world examples
+- **Auto-completion** with contextual help
+
+> 💡 **IDE Integration**: Works with VS Code, WebStorm, and any TypeScript-compatible editor
+
+## Installation
+
+```bash
+npm install @maravilla/platform
+# or
+pnpm add @maravilla/platform
+# or
+yarn add @maravilla/platform
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { getPlatform } from '@maravilla/platform';
+
+// Auto-detects environment (dev/prod)
+const platform = getPlatform();
+
+// Access platform services
+const { KV, DB } = platform.env;
+```
+
+### Development Mode
+
+In development, the client automatically connects to the Maravilla dev server running on port 3001. Make sure to start the dev server first:
+
+```bash
+# Start the dev server
+maravilla dev --port 3001
+
+# In another terminal, start your app
+npm run dev
+```
+
+### Production Mode
+
+In production, the platform client is injected by the Maravilla runtime automatically. No configuration needed.
+
+## API Reference
+
+### KV Store
+
+Key-Value store for caching and simple data storage.
+
+```typescript
+// Get a value
+const value = await platform.env.KV.get('my-key');
+
+// Set a value with optional TTL (in seconds)
+await platform.env.KV.put('my-key', 'my-value', {
+  expirationTtl: 3600, // Expires in 1 hour
+});
+
+// Delete a value
+await platform.env.KV.delete('my-key');
+
+// List keys with optional prefix
+const keys = await platform.env.KV.list({
+  prefix: 'user:',
+  limit: 100,
+  cursor: 'optional-cursor-for-pagination',
+});
+```
+
+### Database (MongoDB-style API)
+
+Document database with MongoDB-compatible query and update operators.
+
+#### Query Operations
+
+```typescript
+// Find multiple documents
+const users = await platform.env.DB.find('users', {
+  active: true,
+  age: { $gte: 18 },
+});
+
+// Find single document
+const user = await platform.env.DB.findOne('users', {
+  _id: 'user-123',
+});
+
+// With options (limit, skip, sort)
+const posts = await platform.env.DB.find('posts', 
+  { published: true },
+  { 
+    limit: 10,
+    skip: 20,
+    sort: { createdAt: -1 },
+  }
+);
+```
+
+#### Insert Operations
+
+```typescript
+// Insert single document
+const result = await platform.env.DB.insertOne('users', {
+  name: 'John Doe',
+  email: 'john@example.com',
+  createdAt: new Date(),
+});
+console.log(result.insertedId); // Generated ID
+
+// Insert multiple documents
+const results = await platform.env.DB.insertMany('users', [
+  { name: 'Alice', email: 'alice@example.com' },
+  { name: 'Bob', email: 'bob@example.com' },
+]);
+console.log(results.insertedIds); // Array of IDs
+```
+
+#### Update Operations
+
+```typescript
+// Update single document
+await platform.env.DB.updateOne('users',
+  { _id: 'user-123' },
+  { 
+    $set: { name: 'Updated Name' },
+    $inc: { loginCount: 1 },
+    $push: { tags: 'new-tag' },
+  }
+);
+
+// Update multiple documents
+await platform.env.DB.updateMany('users',
+  { status: 'pending' },
+  { $set: { status: 'active' } }
+);
+```
+
+##### Supported Update Operators
+
+- `$set` - Set field values
+- `$unset` - Remove fields
+- `$inc` - Increment numeric values
+- `$push` - Add to array
+- `$pull` - Remove from array
+- `$addToSet` - Add unique value to array
+
+#### Delete Operations
+
+```typescript
+// Delete single document
+await platform.env.DB.deleteOne('users', {
+  _id: 'user-123',
+});
+
+// Delete multiple documents
+const result = await platform.env.DB.deleteMany('users', {
+  inactive: true,
+  lastLogin: { $lt: thirtyDaysAgo },
+});
+console.log(result.deletedCount);
+```
+
+### Storage (Coming Soon)
+
+Object storage for files and large data.
+
+```typescript
+// Future API
+await platform.env.STORAGE.put('file-key', buffer);
+const file = await platform.env.STORAGE.get('file-key');
+await platform.env.STORAGE.delete('file-key');
+```
+
+## Environment Detection
+
+The client automatically detects the environment:
+
+1. **Development**: When `MARAVILLA_DEV_SERVER` env var is set (automatically set by vite-plugin)
+2. **Production**: When running inside Maravilla runtime (global `__MARAVILLA_PLATFORM__` is available)
+3. **Fallback**: Returns a mock platform for testing
+
+## TypeScript Support
+
+Full TypeScript support with comprehensive JSDoc documentation:
+
+```typescript
+import type { Platform, KVNamespace, Database } from '@maravilla/platform';
+
+function myFunction(platform: Platform) {
+  const kv: KVNamespace = platform.env.KV;
+  const db: Database = platform.env.DB;
+  
+  // Hover over any method to see detailed documentation
+  // Get parameter hints as you type
+}
+```
+
+### IDE Features
+- **Parameter IntelliSense**: See parameter descriptions while typing
+- **Method Documentation**: Hover for detailed explanations and examples
+- **Type Safety**: Full TypeScript integration with runtime type checking
+- **Error Context**: Understand what errors might be thrown and when
+
+> 📖 **See [JSDOC_GUIDE.md](./JSDOC_GUIDE.md) for detailed IDE integration information**
+
+## Framework Integration
+
+### SvelteKit
+
+```typescript
+// src/routes/+page.server.ts
+import { getPlatform } from '@maravilla/platform';
+
+export async function load() {
+  const platform = getPlatform();
+  const data = await platform.env.KV.get('my-data');
+  
+  return {
+    data: data ? JSON.parse(data) : null,
+  };
+}
+```
+
+### Nuxt (Coming Soon)
+
+```typescript
+// server/api/data.ts
+export default defineEventHandler(async (event) => {
+  const platform = getPlatform();
+  const data = await platform.env.DB.find('items', {});
+  return data;
+});
+```
+
+### Next.js (Coming Soon)
+
+```typescript
+// app/api/route.ts
+import { getPlatform } from '@maravilla/platform';
+
+export async function GET() {
+  const platform = getPlatform();
+  const value = await platform.env.KV.get('key');
+  return Response.json({ value });
+}
+```
+
+## Error Handling
+
+All methods throw errors that should be handled:
+
+```typescript
+try {
+  const data = await platform.env.KV.get('key');
+} catch (error) {
+  console.error('Failed to get KV value:', error);
+  // Handle error appropriately
+}
+```
+
+## Development Tips
+
+1. **Start Dev Server First**: Always start `maravilla dev` before your app dev server
+2. **Use Namespaces**: Prefix your KV keys to avoid collisions (e.g., `user:123`, `cache:api:...`)
+3. **Handle Missing Data**: Always check for null/undefined when getting values
+4. **Use TTL**: Set expiration for cache entries to avoid stale data
+5. **Batch Operations**: Use `insertMany`/`updateMany` for better performance
+
+## License
+
+Proprietary. © 2025 SOLUTAS GmbH, Switzerland. All rights reserved.
+Use is governed by the root LICENSE file or a separate written agreement
+with SOLUTAS GmbH.