s3db.js 11.2.5 → 11.3.1

package/mcp/tools/stats.js

@@ -0,0 +1,281 @@
+/**
+ * Stats & Monitoring Tools
+ * Provides database statistics, cache metrics, and resource stats
+ */
+
+export const statsTools = [
+  {
+    name: 'dbGetStats',
+    description: 'Get database statistics including costs and cache performance',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: []
+    }
+  },
+  {
+    name: 'dbClearCache',
+    description: 'Clear all cached data or cache for specific resource',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        resourceName: {
+          type: 'string',
+          description: 'Name of specific resource to clear cache (optional - if not provided, clears all cache)'
+        }
+      },
+      required: []
+    }
+  },
+  {
+    name: 'resourceGetStats',
+    description: 'Get detailed statistics for a specific resource',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        resourceName: {
+          type: 'string',
+          description: 'Name of the resource'
+        },
+        includePartitionStats: {
+          type: 'boolean',
+          description: 'Include partition statistics',
+          default: true
+        }
+      },
+      required: ['resourceName']
+    }
+  },
+  {
+    name: 'cacheGetStats',
+    description: 'Get detailed cache statistics including hit/miss ratios and memory usage',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        resourceName: {
+          type: 'string',
+          description: 'Get stats for specific resource (optional - gets all if not provided)'
+        }
+      },
+      required: []
+    }
+  }
+];
+
+export function createStatsHandlers(server) {
+  return {
+    async dbGetStats(args, database) {
+      server.ensureConnected(database);
+
+      const stats = {
+        database: {
+          connected: database.isConnected(),
+          bucket: database.bucket,
+          keyPrefix: database.keyPrefix,
+          version: database.s3dbVersion,
+          resourceCount: Object.keys(database.resources || {}).length,
+          resources: Object.keys(database.resources || {})
+        },
+        costs: null,
+        cache: null
+      };
+
+      // Get costs from client if available
+      if (database.client && database.client.costs) {
+        stats.costs = {
+          total: database.client.costs.total,
+          totalRequests: database.client.costs.requests.total,
+          requestsByType: { ...database.client.costs.requests },
+          eventsByType: { ...database.client.costs.events },
+          estimatedCostUSD: database.client.costs.total
+        };
+      }
+
+      // Get cache stats from plugins if available
+      try {
+        const cachePlugin = database.pluginList?.find(p => p.constructor.name === 'CachePlugin');
+        if (cachePlugin && cachePlugin.driver) {
+          const cacheSize = await cachePlugin.driver.size();
+          const cacheKeys = await cachePlugin.driver.keys();
+
+          stats.cache = {
+            enabled: true,
+            driver: cachePlugin.driver.constructor.name,
+            size: cacheSize,
+            maxSize: cachePlugin.driver.maxSize || 'unlimited',
+            ttl: cachePlugin.driver.ttl || 'no expiration',
+            keyCount: cacheKeys.length,
+            sampleKeys: cacheKeys.slice(0, 5) // First 5 keys as sample
+          };
+        } else {
+          stats.cache = { enabled: false };
+        }
+      } catch (error) {
+        stats.cache = { enabled: false, error: error.message };
+      }
+
+      return {
+        success: true,
+        stats
+      };
+    },
+
+    async dbClearCache(args, database) {
+      server.ensureConnected(database);
+      const { resourceName } = args;
+
+      try {
+        const cachePlugin = database.pluginList?.find(p => p.constructor.name === 'CachePlugin');
+        if (!cachePlugin || !cachePlugin.driver) {
+          return {
+            success: false,
+            message: 'Cache is not enabled or available'
+          };
+        }
+
+        if (resourceName) {
+          // Clear cache for specific resource
+          const resource = server.getResource(database, resourceName);
+          await cachePlugin.clearCacheForResource(resource);
+
+          return {
+            success: true,
+            message: `Cache cleared for resource: ${resourceName}`
+          };
+        } else {
+          // Clear all cache
+          await cachePlugin.driver.clear();
+
+          return {
+            success: true,
+            message: 'All cache cleared'
+          };
+        }
+      } catch (error) {
+        return {
+          success: false,
+          message: `Failed to clear cache: ${error.message}`
+        };
+      }
+    },
+
+    async resourceGetStats(args, database) {
+      server.ensureConnected(database);
+      const { resourceName, includePartitionStats = true } = args;
+      const resource = server.getResource(database, resourceName);
+
+      try {
+        const stats = {
+          success: true,
+          resource: resourceName,
+          totalDocuments: await resource.count(),
+          schema: {
+            attributeCount: Object.keys(resource.attributes || {}).length,
+            attributes: Object.keys(resource.attributes || {})
+          },
+          configuration: {
+            behavior: resource.behavior,
+            timestamps: resource.config.timestamps,
+            paranoid: resource.config.paranoid,
+            asyncPartitions: resource.config.asyncPartitions
+          }
+        };
+
+        // Partition stats
+        if (includePartitionStats && resource.config.partitions) {
+          stats.partitions = {
+            count: Object.keys(resource.config.partitions).length,
+            details: {}
+          };
+
+          for (const [partitionName, partitionConfig] of Object.entries(resource.config.partitions)) {
+            try {
+              const partitionCount = await resource.count({ partition: partitionName });
+              stats.partitions.details[partitionName] = {
+                fields: Object.keys(partitionConfig.fields || {}),
+                documentCount: partitionCount
+              };
+            } catch (error) {
+              stats.partitions.details[partitionName] = {
+                fields: Object.keys(partitionConfig.fields || {}),
+                error: error.message
+              };
+            }
+          }
+        }
+
+        return stats;
+      } catch (error) {
+        return {
+          success: false,
+          error: error.message,
+          resource: resourceName
+        };
+      }
+    },
+
+    async cacheGetStats(args, database) {
+      server.ensureConnected(database);
+      const { resourceName } = args;
+
+      try {
+        const cachePlugin = database.pluginList?.find(p => p.constructor.name === 'CachePlugin');
+
+        if (!cachePlugin || !cachePlugin.driver) {
+          return {
+            success: false,
+            message: 'Cache is not enabled or available'
+          };
+        }
+
+        const allKeys = await cachePlugin.driver.keys();
+        const cacheSize = await cachePlugin.driver.size();
+
+        const stats = {
+          success: true,
+          enabled: true,
+          driver: cachePlugin.driver.constructor.name,
+          totalKeys: allKeys.length,
+          totalSize: cacheSize,
+          config: {
+            maxSize: cachePlugin.driver.maxSize || 'unlimited',
+            ttl: cachePlugin.driver.ttl || 'no expiration'
+          }
+        };
+
+        // Resource-specific stats if requested
+        if (resourceName) {
+          const resourceKeys = allKeys.filter(key => key.includes(`resource=${resourceName}`));
+          stats.resource = {
+            name: resourceName,
+            keys: resourceKeys.length,
+            sampleKeys: resourceKeys.slice(0, 5)
+          };
+        } else {
+          // Group by resource
+          const byResource = {};
+          for (const key of allKeys) {
+            const match = key.match(/resource=([^/]+)/);
+            if (match) {
+              const res = match[1];
+              byResource[res] = (byResource[res] || 0) + 1;
+            }
+          }
+          stats.byResource = byResource;
+        }
+
+        // Memory stats for memory cache
+        if (cachePlugin.driver.constructor.name === 'MemoryCache' && cachePlugin.driver.getMemoryStats) {
+          stats.memory = cachePlugin.driver.getMemoryStats();
+        }
+
+        return stats;
+      } catch (error) {
+        return {
+          success: false,
+          error: error.message
+        };
+      }
+    }
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3db.js",
-  "version": "11.2.5",
+  "version": "11.3.1",
   "description": "Use AWS S3, the world's most reliable document storage, as a database with this ORM.",
   "main": "dist/s3db.cjs.js",
   "module": "dist/s3db.es.js",
@@ -10,7 +10,7 @@
   "bin": {
     "s3db.js": "./bin/cli.js",
     "s3db": "./bin/cli.js",
-    "s3db-mcp": "./mcp/server.js"
+    "s3db-mcp": "./mcp/entrypoint.js"
   },
   "repository": {
     "type": "git",
@@ -30,7 +30,13 @@
     "cloud-database",
     "metadata-encoding",
     "s3-database",
-    "serverless"
+    "serverless",
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "claude",
+    "ai-tools",
+    "llm"
   ],
   "type": "module",
   "sideEffects": false,
@@ -52,7 +58,7 @@
     "dist/",
     "src/",
     "bin/cli.js",
-    "mcp/server.js",
+    "mcp/",
     "README.md",
     "PLUGINS.md",
     "SECURITY.md",
@@ -129,8 +135,11 @@
     "https://github.com/sponsors/forattini-dev"
   ],
   "scripts": {
-    "build": "rollup -c",
-    "build:cli": "rollup -c rollup.cli.config.mjs",
+    "build": "npm run build:core",
+    "build:core": "rollup -c",
+    "build:cli": "echo '✅ CLI uses ES modules directly from bin/cli.js (no build needed)'",
+    "build:mcp": "echo '✅ MCP uses ES modules directly from mcp/entrypoint.js (no build needed)'",
+    "build:all": "npm run build:core && npm run build:cli && npm run build:mcp",
     "build:binaries": "./scripts/scripts/build-binaries.sh",
     "dev": "rollup -c -w",
     "test": "pnpm run test:js && pnpm run test:ts",
@@ -145,6 +154,7 @@
     "benchmark:partitions": "node docs/benchmarks/partitions-matrix.js",
     "release:check": "./scripts/pre-release-check.sh",
     "validate:types": "pnpm run test:ts && echo 'TypeScript definitions are valid!'",
-    "test:ts:runtime": "tsx tests/typescript/types-runtime-simple.ts"
+    "test:ts:runtime": "tsx tests/typescript/types-runtime-simple.ts",
+    "test:mcp": "node mcp/entrypoint.js --help"
   }
 }

package/src/database.class.js

@@ -1006,7 +1006,7 @@ export class Database extends EventEmitter {
       autoDecrypt: config.autoDecrypt !== undefined ? config.autoDecrypt : true,
       hooks: hooks || {},
       versioningEnabled: this.versioningEnabled,
-      strictValidation: this.strictValidation,
+      strictValidation: config.strictValidation !== undefined ? config.strictValidation : this.strictValidation,
       map: config.map,
       idGenerator: config.idGenerator,
       idSize: config.idSize,

package/src/resource.class.js

@@ -540,6 +540,85 @@ export class Resource extends AsyncEventEmitter {
     return true;
   }
 
+  /**
+   * Find orphaned partitions (partitions that reference non-existent fields)
+   * @returns {Object} Object with orphaned partition names as keys and details as values
+   * @example
+   * const orphaned = resource.findOrphanedPartitions();
+   * // Returns: { byRegion: { missingFields: ['region'], definition: {...} } }
+   */
+  findOrphanedPartitions() {
+    const orphaned = {};
+
+    if (!this.config.partitions) {
+      return orphaned;
+    }
+
+    for (const [partitionName, partitionDef] of Object.entries(this.config.partitions)) {
+      if (!partitionDef.fields) {
+        continue;
+      }
+
+      const missingFields = [];
+      for (const fieldName of Object.keys(partitionDef.fields)) {
+        if (!this.fieldExistsInAttributes(fieldName)) {
+          missingFields.push(fieldName);
+        }
+      }
+
+      if (missingFields.length > 0) {
+        orphaned[partitionName] = {
+          missingFields,
+          definition: partitionDef,
+          allFields: Object.keys(partitionDef.fields)
+        };
+      }
+    }
+
+    return orphaned;
+  }
+
+  /**
+   * Remove orphaned partitions (partitions that reference non-existent fields)
+   * WARNING: This will modify the resource configuration and should be followed by uploadMetadataFile()
+   * @param {Object} options - Options
+   * @param {boolean} options.dryRun - If true, only returns what would be removed without modifying (default: false)
+   * @returns {Object} Object with removed partition names and details
+   * @example
+   * // Dry run to see what would be removed
+   * const toRemove = resource.removeOrphanedPartitions({ dryRun: true });
+   * console.log('Would remove:', toRemove);
+   *
+   * // Actually remove orphaned partitions
+   * const removed = resource.removeOrphanedPartitions();
+   * await database.uploadMetadataFile(); // Save changes to S3
+   */
+  removeOrphanedPartitions({ dryRun = false } = {}) {
+    const orphaned = this.findOrphanedPartitions();
+
+    if (Object.keys(orphaned).length === 0) {
+      return {};
+    }
+
+    if (dryRun) {
+      return orphaned;
+    }
+
+    // Remove orphaned partitions from config
+    for (const partitionName of Object.keys(orphaned)) {
+      delete this.config.partitions[partitionName];
+    }
+
+    // Emit event for tracking
+    this.emit('orphanedPartitionsRemoved', {
+      resourceName: this.name,
+      removed: Object.keys(orphaned),
+      details: orphaned
+    });
+
+    return orphaned;
+  }
+
   /**
    * Apply a single partition rule to a field value
    * @param {*} value - The field value

package/src/s3db.d.ts

@@ -763,7 +763,9 @@ declare module 's3db.js' {
       data: any; 
     }>;
     validatePartitions(): void;
-    
+    findOrphanedPartitions(): Record<string, { missingFields: string[]; definition: PartitionConfig; allFields: string[] }>;
+    removeOrphanedPartitions(options?: { dryRun?: boolean }): Record<string, { missingFields: string[]; definition: PartitionConfig; allFields: string[] }>;
+
     // Partition operations
     getPartitionKey(options: { partitionName: string; id: string; data: any }): string;
     getFromPartition(options: { id: string; partitionName: string; partitionValues?: Record<string, any> }): Promise<any>;