@maravilla-labs/platform 0.1.0

package/src/index.ts

@@ -0,0 +1,170 @@
+/**
+ * @fileoverview Maravilla Platform SDK
+ * 
+ * This package provides the main interface for accessing Maravilla runtime services
+ * including Key-Value storage and Database operations. It automatically detects the
+ * runtime environment and provides the appropriate implementation.
+ * 
+ * ## Environment Detection
+ * 
+ * The SDK automatically detects and adapts to different environments:
+ * - **Production**: Uses native Maravilla runtime APIs
+ * - **Development**: Connects to development server via HTTP
+ * - **Testing**: Can be mocked or use development server
+ * 
+ * ## Key Features
+ * 
+ * - **KV Storage**: Cloudflare Workers KV-compatible API for key-value operations
+ * - **Database**: MongoDB-style document database operations
+ * - **Multi-tenancy**: Built-in tenant isolation and support
+ * - **TypeScript**: Fully typed APIs with comprehensive JSDoc comments
+ * - **Development-friendly**: Seamless development server integration
+ * 
+ * @example
+ * ```typescript
+ * import { getPlatform } from '@maravilla/platform';
+ * 
+ * const platform = getPlatform();
+ * 
+ * // KV operations
+ * await platform.env.KV.cache.put('user:123', { name: 'John' });
+ * const user = await platform.env.KV.cache.get('user:123');
+ * 
+ * // Database operations
+ * const userId = await platform.env.DB.insertOne('users', {
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ * });
+ * 
+ * const users = await platform.env.DB.find('users', { active: true });
+ * ```
+ * 
+ * @author Maravilla Team
+ * @since 1.0.0
+ */
+
+import type { Platform } from './types.js';
+import { createRemoteClient } from './remote-client.js';
+
+export * from './types.js';
+
+/**
+ * Global platform instance injected by Maravilla runtime or development tools.
+ * This should not be accessed directly - use getPlatform() instead.
+ * 
+ * @internal
+ */
+
+declare global {
+  var __maravilla_platform: Platform | undefined;
+  var platform: Platform | undefined;
+}
+
+let cachedPlatform: Platform | null = null;
+
+/**
+ * Get the platform instance. This will:
+ * 1. Check if running in Maravilla runtime (global.platform exists)
+ * 2. Check if a platform was injected via vite plugin or hooks
+ * 3. Fall back to remote client for development
+ * 
+ * The platform provides access to KV storage and database operations,
+ * with automatic environment detection for seamless development and production.
+ * 
+ * @param options - Optional configuration for development mode
+ * @param options.devServerUrl - URL of the development server (defaults to MARAVILLA_DEV_SERVER env var or http://localhost:3001)
+ * @param options.tenant - Tenant identifier for multi-tenancy (defaults to MARAVILLA_TENANT env var or 'dev-tenant')
+ * @returns Platform instance with access to KV and database services
+ * 
+ * @example
+ * ```typescript
+ * import { getPlatform } from '@maravilla/platform';
+ * 
+ * // Basic usage (auto-detects environment)
+ * const platform = getPlatform();
+ * 
+ * // Development with custom server
+ * const platform = getPlatform({
+ *   devServerUrl: 'http://localhost:3001',
+ *   tenant: 'my-app'
+ * });
+ * 
+ * // Use KV storage
+ * await platform.env.KV.cache.put('user:123', { name: 'John' });
+ * const user = await platform.env.KV.cache.get('user:123');
+ * 
+ * // Use database
+ * const userId = await platform.env.DB.insertOne('users', {
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ * });
+ * ```
+ */
+export function getPlatform(options?: {
+  devServerUrl?: string;
+  tenant?: string;
+}): Platform {
+  // Return cached if available
+  if (cachedPlatform) {
+    return cachedPlatform;
+  }
+
+  // 1. Check if we're in the real Maravilla runtime
+  if (typeof globalThis !== 'undefined') {
+    // Check for native platform (in production runtime)
+    if (globalThis.platform) {
+      console.log('[platform] Using native Maravilla platform');
+      cachedPlatform = globalThis.platform;
+      return cachedPlatform;
+    }
+
+    // Check for injected platform (from vite plugin or hooks)
+    if (globalThis.__maravilla_platform) {
+      console.log('[platform] Using injected platform');
+      cachedPlatform = globalThis.__maravilla_platform;
+      return cachedPlatform;
+    }
+  }
+
+  // 2. Fall back to remote client for development
+  const devServerUrl = options?.devServerUrl || process.env.MARAVILLA_DEV_SERVER || 'http://localhost:3001';
+  const tenant = options?.tenant || process.env.MARAVILLA_TENANT || 'dev-tenant';
+  
+  console.log(`[platform] Creating remote client for ${devServerUrl}`);
+  cachedPlatform = createRemoteClient(devServerUrl, tenant);
+  
+  // Cache it globally for other modules
+  if (typeof globalThis !== 'undefined') {
+    globalThis.__maravilla_platform = cachedPlatform;
+  }
+  
+  return cachedPlatform;
+}
+
+/**
+ * Clear the cached platform instance (useful for testing).
+ * 
+ * This function resets the internal platform cache and clears any globally
+ * injected platform instances. Subsequent calls to getPlatform() will
+ * re-initialize the platform based on the current environment.
+ * 
+ * @example
+ * ```typescript
+ * import { clearPlatformCache, getPlatform } from '@maravilla/platform';
+ * 
+ * // In tests, clear cache between test cases
+ * afterEach(() => {
+ *   clearPlatformCache();
+ * });
+ * 
+ * // Or when switching between different environments
+ * clearPlatformCache();
+ * const newPlatform = getPlatform({ devServerUrl: 'http://localhost:3002' });
+ * ```
+ */
+export function clearPlatformCache(): void {
+  cachedPlatform = null;
+  if (typeof globalThis !== 'undefined') {
+    globalThis.__maravilla_platform = undefined;
+  }
+}

package/src/remote-client.ts

@@ -0,0 +1,200 @@
+import type { KvNamespace, KvListResult, Database, DbFindOptions } from './types.js';
+
+/**
+ * Remote KV namespace implementation that communicates with a development server.
+ * This class provides the KV interface by making HTTP requests to the dev server.
+ * 
+ * @internal
+ */
+class RemoteKvNamespace implements KvNamespace {
+  constructor(
+    private baseUrl: string,
+    private namespace: string,
+    private headers: Record<string, string>
+  ) {}
+
+  /**
+   * Internal method for making HTTP requests to the dev server.
+   * Handles error responses and authentication headers.
+   * 
+   * @internal
+   */
+  private async fetch(url: string, options: RequestInit = {}) {
+    const response = await fetch(url, {
+      ...options,
+      headers: { ...this.headers, ...options.headers },
+    });
+
+    if (!response.ok && response.status !== 404) {
+      const error = await response.text();
+      throw new Error(`Platform API error: ${response.status} - ${error}`);
+    }
+
+    return response;
+  }
+
+  async get(key: string): Promise<any> {
+    const response = await this.fetch(`${this.baseUrl}/api/kv/${this.namespace}/${key}`);
+    if (response.status === 404) return null;
+    return response.json();
+  }
+
+  async put(key: string, value: any, options?: { expirationTtl?: number }): Promise<void> {
+    const headers: Record<string, string> = {};
+    if (options?.expirationTtl) {
+      headers['X-TTL'] = options.expirationTtl.toString();
+    }
+
+    await this.fetch(`${this.baseUrl}/api/kv/${this.namespace}/${key}`, {
+      method: 'PUT',
+      headers,
+      body: JSON.stringify(value),
+    });
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.fetch(`${this.baseUrl}/api/kv/${this.namespace}/${key}`, {
+      method: 'DELETE',
+    });
+  }
+
+  async list(options?: { prefix?: string; limit?: number; cursor?: string }): Promise<KvListResult> {
+    const response = await this.fetch(`${this.baseUrl}/api/kv/${this.namespace}`, {
+      method: 'POST',
+      body: JSON.stringify(options || {}),
+    });
+    const data = await response.json() as any;
+    return {
+      keys: data.result || [],
+      list_complete: !data.result_info?.cursor,
+      cursor: data.result_info?.cursor,
+    };
+  }
+}
+
+/**
+ * Remote Database implementation that communicates with a development server.
+ * This class provides the Database interface by making HTTP requests to the dev server.
+ * 
+ * @internal
+ */
+class RemoteDatabase implements Database {
+  constructor(
+    private baseUrl: string,
+    private headers: Record<string, string>
+  ) {}
+
+  /**
+   * Internal method for making HTTP requests to the dev server.
+   * Handles error responses and authentication headers.
+   * 
+   * @internal
+   */
+  private async fetch(url: string, options: RequestInit = {}) {
+    const response = await fetch(url, {
+      ...options,
+      headers: { ...this.headers, ...options.headers },
+    });
+
+    if (!response.ok && response.status !== 404) {
+      const error = await response.text();
+      throw new Error(`Platform API error: ${response.status} - ${error}`);
+    }
+
+    return response;
+  }
+
+  async find(collection: string, filter: any = {}, options: DbFindOptions = {}): Promise<any[]> {
+    const response = await this.fetch(`${this.baseUrl}/api/db/${collection}`, {
+      method: 'POST',
+      body: JSON.stringify({ filter, options }),
+    });
+    return response.json() as Promise<any[]>;
+  }
+
+  async findOne(collection: string, filter: any): Promise<any | null> {
+    const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/findOne`, {
+      method: 'POST',
+      body: JSON.stringify(filter),
+    });
+    if (response.status === 404) return null;
+    return response.json();
+  }
+
+  async insertOne(collection: string, document: any): Promise<string> {
+    const response = await this.fetch(`${this.baseUrl}/api/db/${collection}`, {
+      method: 'PUT',
+      body: JSON.stringify(document),
+    });
+    const result = await response.json() as any;
+    return result.id;
+  }
+
+  async updateOne(collection: string, filter: any, update: any): Promise<{ modified: number }> {
+    const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/update`, {
+      method: 'POST',
+      body: JSON.stringify({ filter, update }),
+    });
+    return response.json() as Promise<{ modified: number }>;
+  }
+
+  async deleteOne(collection: string, filter: any): Promise<{ deleted: number }> {
+    const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/delete`, {
+      method: 'DELETE',
+      body: JSON.stringify(filter),
+    });
+    return response.json() as Promise<{ deleted: number }>;
+  }
+
+  async deleteMany(collection: string, filter: any): Promise<{ deleted: number }> {
+    // For now, deleteMany is the same as deleteOne in the remote client
+    // This would need to be implemented properly in the dev server
+    return this.deleteOne(collection, filter);
+  }
+}
+
+/**
+ * Create a remote platform client for development environments.
+ * 
+ * This function creates a platform instance that communicates with a development
+ * server over HTTP. It's used internally by getPlatform() when running in development
+ * mode and no native platform is available.
+ * 
+ * @param baseUrl - The base URL of the development server
+ * @param tenant - The tenant identifier for multi-tenancy support
+ * @returns A platform instance that proxies requests to the development server
+ * 
+ * @internal
+ * 
+ * @example
+ * ```typescript
+ * // This is typically called internally by getPlatform()
+ * const platform = createRemoteClient('http://localhost:3001', 'dev-tenant');
+ * 
+ * // The returned platform works the same as the native one
+ * await platform.env.KV.cache.put('key', 'value');
+ * await platform.env.DB.insertOne('users', { name: 'John' });
+ * ```
+ */
+export function createRemoteClient(baseUrl: string, tenant: string) {
+  const headers = {
+    'Content-Type': 'application/json',
+    'X-Tenant-Id': tenant,
+  };
+
+  // Create KV namespaces proxy that dynamically creates namespace instances
+  const kvProxy = new Proxy({} as Record<string, KvNamespace>, {
+    get(_, namespace: string) {
+      return new RemoteKvNamespace(baseUrl, namespace, headers);
+    }
+  });
+
+  const db = new RemoteDatabase(baseUrl, headers);
+
+  return {
+    env: {
+      KV: kvProxy,
+      DB: db,
+    }
+  };
+}

package/src/types.ts

@@ -0,0 +1,305 @@
+/**
+ * Key-Value namespace interface for storing and retrieving data.
+ * Similar to Cloudflare Workers KV API for familiar developer experience.
+ * 
+ * @example
+ * ```typescript
+ * const platform = getPlatform();
+ * const userKv = platform.env.KV.users;
+ * 
+ * // Store user data
+ * await userKv.put('user:123', { name: 'John', email: 'john@example.com' });
+ * 
+ * // Retrieve user data
+ * const user = await userKv.get('user:123');
+ * 
+ * // List all user keys
+ * const result = await userKv.list({ prefix: 'user:' });
+ * ```
+ */
+export interface KvNamespace {
+  /**
+   * Retrieve a value from the KV namespace.
+   * 
+   * @param key - The key to retrieve
+   * @returns Promise that resolves to the stored value, or null if not found
+   * 
+   * @example
+   * ```typescript
+   * const user = await kv.get('user:123');
+   * if (user) {
+   *   console.log(`Welcome back, ${user.name}!`);
+   * }
+   * ```
+   */
+  get(key: string): Promise<any>;
+
+  /**
+   * Store a value in the KV namespace.
+   * 
+   * @param key - The key to store under
+   * @param value - The value to store (will be JSON serialized)
+   * @param options - Optional configuration
+   * @param options.expirationTtl - Time to live in seconds before the key expires
+   * @returns Promise that resolves when the operation completes
+   * 
+   * @example
+   * ```typescript
+   * // Store permanent data
+   * await kv.put('config:theme', { dark: true });
+   * 
+   * // Store temporary data (expires in 1 hour)
+   * await kv.put('session:abc123', sessionData, { expirationTtl: 3600 });
+   * ```
+   */
+  put(key: string, value: any, options?: { expirationTtl?: number }): Promise<void>;
+
+  /**
+   * Delete a key from the KV namespace.
+   * 
+   * @param key - The key to delete
+   * @returns Promise that resolves when the operation completes
+   * 
+   * @example
+   * ```typescript
+   * await kv.delete('user:123');
+   * ```
+   */
+  delete(key: string): Promise<void>;
+
+  /**
+   * List keys in the KV namespace with optional filtering.
+   * 
+   * @param options - Optional filtering and pagination options
+   * @param options.prefix - Only return keys that start with this prefix
+   * @param options.limit - Maximum number of keys to return (default varies by implementation)
+   * @param options.cursor - Pagination cursor from previous list call
+   * @returns Promise that resolves to a list result with keys and pagination info
+   * 
+   * @example
+   * ```typescript
+   * // List all keys
+   * const all = await kv.list();
+   * 
+   * // List user keys only
+   * const users = await kv.list({ prefix: 'user:' });
+   * 
+   * // Paginated listing
+   * const page1 = await kv.list({ limit: 10 });
+   * if (!page1.list_complete) {
+   *   const page2 = await kv.list({ limit: 10, cursor: page1.cursor });
+   * }
+   * ```
+   */
+  list(options?: { prefix?: string; limit?: number; cursor?: string }): Promise<KvListResult>;
+}
+
+/**
+ * Result object returned by KV list operations.
+ * Contains the matching keys and pagination information.
+ */
+export interface KvListResult {
+  /** Array of matching keys with their metadata */
+  keys: Array<{ 
+    /** The key name */
+    name: string; 
+    /** Unix timestamp when the key expires (if set) */
+    expiration?: number; 
+    /** Custom metadata associated with the key */
+    metadata?: any;
+  }>;
+  /** Whether this result contains all matching keys (true) or more results are available (false) */
+  list_complete: boolean;
+  /** Pagination cursor to use for the next list call, if list_complete is false */
+  cursor?: string;
+}
+
+/**
+ * Database interface for document-based operations.
+ * Provides MongoDB-like API for storing and querying structured data.
+ * 
+ * @example
+ * ```typescript
+ * const platform = getPlatform();
+ * const db = platform.env.DB;
+ * 
+ * // Insert a new user
+ * const userId = await db.insertOne('users', {
+ *   name: 'John Doe',
+ *   email: 'john@example.com',
+ *   createdAt: new Date()
+ * });
+ * 
+ * // Find users by criteria
+ * const activeUsers = await db.find('users', { active: true });
+ * 
+ * // Update a user
+ * await db.updateOne('users', 
+ *   { _id: userId }, 
+ *   { $set: { lastLogin: new Date() } }
+ * );
+ * ```
+ */
+export interface Database {
+  /**
+   * Find multiple documents in a collection.
+   * 
+   * @param collection - The collection name
+   * @param filter - Query filter object (MongoDB-style)
+   * @param options - Optional query options for pagination and sorting
+   * @returns Promise that resolves to an array of matching documents
+   * 
+   * @example
+   * ```typescript
+   * // Find all active users
+   * const users = await db.find('users', { active: true });
+   * 
+   * // Find with pagination and sorting
+   * const recentPosts = await db.find('posts', 
+   *   { published: true },
+   *   { limit: 10, sort: { createdAt: -1 } }
+   * );
+   * ```
+   */
+  find(collection: string, filter?: any, options?: DbFindOptions): Promise<any[]>;
+
+  /**
+   * Find a single document in a collection.
+   * 
+   * @param collection - The collection name
+   * @param filter - Query filter object to match the document
+   * @returns Promise that resolves to the matching document, or null if not found
+   * 
+   * @example
+   * ```typescript
+   * const user = await db.findOne('users', { email: 'john@example.com' });
+   * if (user) {
+   *   console.log(`Found user: ${user.name}`);
+   * }
+   * ```
+   */
+  findOne(collection: string, filter: any): Promise<any | null>;
+
+  /**
+   * Insert a single document into a collection.
+   * 
+   * @param collection - The collection name
+   * @param document - The document to insert
+   * @returns Promise that resolves to the ID of the inserted document
+   * 
+   * @example
+   * ```typescript
+   * const postId = await db.insertOne('posts', {
+   *   title: 'Hello World',
+   *   content: 'This is my first post',
+   *   author: 'john@example.com',
+   *   createdAt: new Date()
+   * });
+   * ```
+   */
+  insertOne(collection: string, document: any): Promise<string>;
+
+  /**
+   * Update a single document in a collection.
+   * 
+   * @param collection - The collection name
+   * @param filter - Query filter to match the document to update
+   * @param update - Update operations (MongoDB-style with $set, $inc, etc.)
+   * @returns Promise that resolves to an object with the number of modified documents
+   * 
+   * @example
+   * ```typescript
+   * const result = await db.updateOne('users',
+   *   { email: 'john@example.com' },
+   *   { $set: { lastLogin: new Date() }, $inc: { loginCount: 1 } }
+   * );
+   * console.log(`Modified ${result.modified} documents`);
+   * ```
+   */
+  updateOne(collection: string, filter: any, update: any): Promise<{ modified: number }>;
+
+  /**
+   * Delete a single document from a collection.
+   * 
+   * @param collection - The collection name
+   * @param filter - Query filter to match the document to delete
+   * @returns Promise that resolves to an object with the number of deleted documents
+   * 
+   * @example
+   * ```typescript
+   * const result = await db.deleteOne('posts', { _id: postId });
+   * console.log(`Deleted ${result.deleted} documents`);
+   * ```
+   */
+  deleteOne(collection: string, filter: any): Promise<{ deleted: number }>;
+
+  /**
+   * Delete multiple documents from a collection.
+   * 
+   * @param collection - The collection name
+   * @param filter - Query filter to match documents to delete
+   * @returns Promise that resolves to an object with the number of deleted documents
+   * 
+   * @example
+   * ```typescript
+   * // Delete all inactive users
+   * const result = await db.deleteMany('users', { active: false });
+   * console.log(`Deleted ${result.deleted} inactive users`);
+   * ```
+   */
+  deleteMany(collection: string, filter: any): Promise<{ deleted: number }>;
+}
+
+/**
+ * Options for database find operations.
+ * Provides MongoDB-style query options for pagination, sorting, and limiting results.
+ */
+export interface DbFindOptions {
+  /** Maximum number of documents to return */
+  limit?: number;
+  /** Number of documents to skip (for pagination) */
+  skip?: number;
+  /** Sort order specification (MongoDB-style: { field: 1 } for ascending, { field: -1 } for descending) */
+  sort?: any;
+}
+
+/**
+ * Platform environment containing all available services.
+ * This is the main interface for accessing KV storage and database operations.
+ */
+export interface PlatformEnv {
+  /** 
+   * Key-Value storage namespaces. Access different KV namespaces by property name.
+   * 
+   * @example
+   * ```typescript
+   * const userCache = platform.env.KV.users;
+   * const sessionStore = platform.env.KV.sessions;
+   * ```
+   */
+  KV: Record<string, KvNamespace>;
+  /** Database interface for document operations */
+  DB: Database;
+}
+
+/**
+ * Main platform interface providing access to all Maravilla runtime services.
+ * This is the primary interface developers will interact with.
+ * 
+ * @example
+ * ```typescript
+ * import { getPlatform } from '@maravilla/platform';
+ * 
+ * const platform = getPlatform();
+ * 
+ * // Use KV storage
+ * await platform.env.KV.cache.put('key', 'value');
+ * 
+ * // Use database
+ * await platform.env.DB.insertOne('users', { name: 'John' });
+ * ```
+ */
+export interface Platform {
+  /** Environment containing all available platform services */
+  env: PlatformEnv;
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "node",
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  target: 'es2022',
+  external: [],
+});