s3db.js 12.1.0 → 12.2.0

package/src/plugins/api/routes/resource-routes.js

@@ -299,6 +299,91 @@ export function createResourceRoutes(resource, version, config = {}) {
   return app;
 }
 
+/**
+ * Create relational routes for a resource relation
+ * @param {Object} sourceResource - Source s3db.js Resource instance
+ * @param {string} relationName - Name of the relation (e.g., 'posts', 'profile')
+ * @param {Object} relationConfig - Relation configuration from RelationPlugin
+ * @param {string} version - Resource version (e.g., 'v1')
+ * @returns {Hono} Hono app with relational routes
+ */
+export function createRelationalRoutes(sourceResource, relationName, relationConfig, version) {
+  const app = new Hono();
+  const resourceName = sourceResource.name;
+  const relatedResourceName = relationConfig.resource;
+
+  // GET /{version}/{resource}/:id/{relation}
+  // Examples: GET /v1/users/user123/posts, GET /v1/users/user123/profile
+  app.get('/:id', asyncHandler(async (c) => {
+    const id = c.req.param('id');
+    const query = c.req.query();
+
+    // Check if source resource exists
+    const source = await sourceResource.get(id);
+    if (!source) {
+      const response = formatter.notFound(resourceName, id);
+      return c.json(response, response._status);
+    }
+
+    // Use RelationPlugin's include feature to load the relation
+    const result = await sourceResource.get(id, {
+      include: [relationName]
+    });
+
+    const relatedData = result[relationName];
+
+    // Check if relation exists
+    if (!relatedData) {
+      // Return appropriate response based on relation type
+      if (relationConfig.type === 'hasMany' || relationConfig.type === 'belongsToMany') {
+        // For *-to-many relations, return empty array
+        const response = formatter.list([], {
+          total: 0,
+          page: 1,
+          pageSize: 100,
+          pageCount: 0
+        });
+        return c.json(response, response._status);
+      } else {
+        // For *-to-one relations, return 404
+        const response = formatter.notFound(relatedResourceName, 'related resource');
+        return c.json(response, response._status);
+      }
+    }
+
+    // Return appropriate format based on relation type
+    if (relationConfig.type === 'hasMany' || relationConfig.type === 'belongsToMany') {
+      // For *-to-many, return list format
+      const items = Array.isArray(relatedData) ? relatedData : [relatedData];
+      const limit = parseInt(query.limit) || 100;
+      const offset = parseInt(query.offset) || 0;
+
+      // Apply pagination
+      const paginatedItems = items.slice(offset, offset + limit);
+
+      const response = formatter.list(paginatedItems, {
+        total: items.length,
+        page: Math.floor(offset / limit) + 1,
+        pageSize: limit,
+        pageCount: Math.ceil(items.length / limit)
+      });
+
+      // Set pagination headers
+      c.header('X-Total-Count', items.length.toString());
+      c.header('X-Page-Count', Math.ceil(items.length / limit).toString());
+
+      return c.json(response, response._status);
+    } else {
+      // For *-to-one, return single resource format
+      const response = formatter.success(relatedData);
+      return c.json(response, response._status);
+    }
+  }));
+
+  return app;
+}
+
 export default {
-  createResourceRoutes
+  createResourceRoutes,
+  createRelationalRoutes
 };

package/src/plugins/api/server.js

@@ -7,7 +7,7 @@
 import { Hono } from 'hono';
 import { serve } from '@hono/node-server';
 import { swaggerUI } from '@hono/swagger-ui';
-import { createResourceRoutes } from './routes/resource-routes.js';
+import { createResourceRoutes, createRelationalRoutes } from './routes/resource-routes.js';
 import { errorHandler } from './utils/error-handler.js';
 import * as formatter from './utils/response-formatter.js';
 import { generateOpenAPISpec } from './utils/openapi-generator.js';
@@ -51,6 +51,11 @@ export class ApiServer {
     this.isRunning = false;
     this.openAPISpec = null;
 
+    // Detect if RelationPlugin is installed
+    this.relationsPlugin = this.options.database?.plugins?.relation ||
+                          this.options.database?.plugins?.RelationPlugin ||
+                          null;
+
     this._setupRoutes();
   }
 
@@ -165,12 +170,10 @@ export class ApiServer {
 
       // API Documentation UI endpoint
       if (this.options.docsUI === 'swagger') {
-        // Swagger UI (legacy, less pretty)
         this.app.get('/docs', swaggerUI({
           url: '/openapi.json'
         }));
       } else {
-        // Redoc (modern, beautiful design!)
         this.app.get('/docs', (c) => {
           return c.html(`<!DOCTYPE html>
 <html lang="en">
@@ -197,6 +200,11 @@ export class ApiServer {
     // Setup resource routes
     this._setupResourceRoutes();
 
+    // Setup relational routes if RelationPlugin is active
+    if (this.relationsPlugin) {
+      this._setupRelationalRoutes();
+    }
+
     // Global error handler
     this.app.onError((err, c) => {
       return errorHandler(err, c);
@@ -257,6 +265,74 @@ export class ApiServer {
     }
   }
 
+  /**
+   * Setup relational routes (when RelationPlugin is active)
+   * @private
+   */
+  _setupRelationalRoutes() {
+    if (!this.relationsPlugin || !this.relationsPlugin.relations) {
+      return;
+    }
+
+    const { database } = this.options;
+    const relations = this.relationsPlugin.relations;
+
+    if (this.options.verbose) {
+      console.log('[API Plugin] Setting up relational routes...');
+    }
+
+    for (const [resourceName, relationsDef] of Object.entries(relations)) {
+      const resource = database.resources[resourceName];
+      if (!resource) {
+        if (this.options.verbose) {
+          console.warn(`[API Plugin] Resource '${resourceName}' not found for relational routes`);
+        }
+        continue;
+      }
+
+      // Skip plugin resources unless explicitly included
+      if (resourceName.startsWith('plg_') && !this.options.resources[resourceName]) {
+        continue;
+      }
+
+      const version = resource.config?.currentVersion || resource.version || 'v1';
+
+      for (const [relationName, relationConfig] of Object.entries(relationsDef)) {
+        // Only create routes for relations that should be exposed via API
+        // Skip belongsTo relations (they're just reverse lookups, not useful as endpoints)
+        if (relationConfig.type === 'belongsTo') {
+          continue;
+        }
+
+        // Check if relation should be exposed (default: yes, unless explicitly disabled)
+        const resourceConfig = this.options.resources[resourceName];
+        const exposeRelation = resourceConfig?.relations?.[relationName]?.expose !== false;
+
+        if (!exposeRelation) {
+          continue;
+        }
+
+        // Create relational routes
+        const relationalApp = createRelationalRoutes(
+          resource,
+          relationName,
+          relationConfig,
+          version
+        );
+
+        // Mount relational routes at /{version}/{resource}/:id/{relation}
+        this.app.route(`/${version}/${resourceName}/:id/${relationName}`, relationalApp);
+
+        if (this.options.verbose) {
+          console.log(
+            `[API Plugin] Mounted relational route: /${version}/${resourceName}/:id/${relationName} ` +
+            `(${relationConfig.type} -> ${relationConfig.resource})`
+          );
+        }
+      }
+    }
+  }
+
   /**
    * Start the server
    * @returns {Promise<void>}

package/src/plugins/api/utils/openapi-generator.js

@@ -100,6 +100,12 @@ function generateResourceSchema(resource) {
 
   const attributes = resource.config?.attributes || resource.attributes || {};
 
+  // Extract resource description (supports both string and object format)
+  const resourceDescription = resource.config?.description;
+  const attributeDescriptions = typeof resourceDescription === 'object'
+    ? (resourceDescription.attributes || {})
+    : {};
+
   // Add system-generated id field (always present in responses)
   properties.id = {
     type: 'string',
@@ -114,7 +120,7 @@ function generateResourceSchema(resource) {
       const baseType = mapFieldTypeToOpenAPI(fieldDef.type);
       properties[fieldName] = {
         ...baseType,
-        description: fieldDef.description || undefined
+        description: fieldDef.description || attributeDescriptions[fieldName] || undefined
       };
 
       if (fieldDef.required) {
@@ -142,7 +148,8 @@ function generateResourceSchema(resource) {
 
       properties[fieldName] = {
         ...baseType,
-        ...rules
+        ...rules,
+        description: attributeDescriptions[fieldName] || undefined
       };
 
       if (rules.required) {
@@ -787,6 +794,113 @@ The response includes pagination metadata in the \`pagination\` object with tota
   return paths;
 }
 
+/**
+ * Generate OpenAPI paths for relational routes
+ * @param {Object} resource - Source s3db.js Resource instance
+ * @param {string} relationName - Name of the relation
+ * @param {Object} relationConfig - Relation configuration
+ * @param {string} version - Resource version
+ * @param {Object} relatedSchema - OpenAPI schema for related resource
+ * @returns {Object} OpenAPI paths for relation
+ */
+function generateRelationalPaths(resource, relationName, relationConfig, version, relatedSchema) {
+  const resourceName = resource.name;
+  const basePath = `/${version}/${resourceName}/{id}/${relationName}`;
+  const relatedResourceName = relationConfig.resource;
+  const isToMany = relationConfig.type === 'hasMany' || relationConfig.type === 'belongsToMany';
+
+  const paths = {};
+
+  paths[basePath] = {
+    get: {
+      tags: [resourceName],
+      summary: `Get ${relationName} of ${resourceName}`,
+      description: `Retrieve ${relationName} (${relationConfig.type}) associated with this ${resourceName}. ` +
+                   `This endpoint uses the RelationPlugin to efficiently load related data` +
+                   (relationConfig.partitionHint ? ` via the '${relationConfig.partitionHint}' partition.` : '.'),
+      parameters: [
+        {
+          name: 'id',
+          in: 'path',
+          required: true,
+          description: `${resourceName} ID`,
+          schema: { type: 'string' }
+        },
+        ...(isToMany ? [
+          {
+            name: 'limit',
+            in: 'query',
+            description: 'Maximum number of items to return',
+            schema: { type: 'integer', default: 100, minimum: 1, maximum: 1000 }
+          },
+          {
+            name: 'offset',
+            in: 'query',
+            description: 'Number of items to skip',
+            schema: { type: 'integer', default: 0, minimum: 0 }
+          }
+        ] : [])
+      ],
+      responses: {
+        200: {
+          description: 'Successful response',
+          content: {
+            'application/json': {
+              schema: isToMany ? {
+                type: 'object',
+                properties: {
+                  success: { type: 'boolean', example: true },
+                  data: {
+                    type: 'array',
+                    items: relatedSchema
+                  },
+                  pagination: {
+                    type: 'object',
+                    properties: {
+                      total: { type: 'integer' },
+                      page: { type: 'integer' },
+                      pageSize: { type: 'integer' },
+                      pageCount: { type: 'integer' }
+                    }
+                  }
+                }
+              } : {
+                type: 'object',
+                properties: {
+                  success: { type: 'boolean', example: true },
+                  data: relatedSchema
+                }
+              }
+            }
+          },
+          ...(isToMany ? {
+            headers: {
+              'X-Total-Count': {
+                description: 'Total number of related records',
+                schema: { type: 'integer' }
+              },
+              'X-Page-Count': {
+                description: 'Total number of pages',
+                schema: { type: 'integer' }
+              }
+            }
+          } : {})
+        },
+        404: {
+          description: `${resourceName} not found` + (isToMany ? '' : ' or no related resource exists'),
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/Error' }
+            }
+          }
+        }
+      }
+    }
+  };
+
+  return paths;
+}
+
 /**
  * Generate complete OpenAPI 3.0 specification
  * @param {Object} database - s3db.js Database instance
@@ -803,12 +917,42 @@ export function generateOpenAPISpec(database, config = {}) {
     resources: resourceConfigs = {}
   } = config;
 
+  // Build resources table for description
+  const resourcesTableRows = [];
+  for (const [name, resource] of Object.entries(database.resources)) {
+    // Skip plugin resources unless explicitly configured
+    if (name.startsWith('plg_') && !resourceConfigs[name]) {
+      continue;
+    }
+
+    const version = resource.config?.currentVersion || resource.version || 'v1';
+    const resourceDescription = resource.config?.description;
+    const descText = typeof resourceDescription === 'object'
+      ? resourceDescription.resource
+      : resourceDescription || 'No description';
+
+    resourcesTableRows.push(`| ${name} | ${descText} | \`/${version}/${name}\` |`);
+  }
+
+  // Build enhanced description with resources table
+  const enhancedDescription = `${description}
+
+## Available Resources
+
+| Resource | Description | Base Path |
+|----------|-------------|-----------|
+${resourcesTableRows.join('\n')}
+
+---
+
+For detailed information about each endpoint, see the sections below.`;
+
   const spec = {
     openapi: '3.1.0',
     info: {
       title,
       version,
-      description,
+      description: enhancedDescription,
       contact: {
         name: 's3db.js',
         url: 'https://github.com/forattini-dev/s3db.js'
@@ -903,6 +1047,9 @@ export function generateOpenAPISpec(database, config = {}) {
   // Generate paths for each resource
   const resources = database.resources;
 
+  // Detect RelationPlugin
+  const relationsPlugin = database.plugins?.relation || database.plugins?.RelationPlugin || null;
+
   for (const [name, resource] of Object.entries(resources)) {
     // Skip plugin resources unless explicitly configured
     if (name.startsWith('plg_') && !resourceConfigs[name]) {
@@ -924,14 +1071,57 @@ export function generateOpenAPISpec(database, config = {}) {
     // Merge paths
     Object.assign(spec.paths, paths);
 
-    // Add tag
+    // Add tag with description support
+    const resourceDescription = resource.config?.description;
+    const tagDescription = typeof resourceDescription === 'object'
+      ? resourceDescription.resource
+      : resourceDescription || `Operations for ${name} resource`;
+
     spec.tags.push({
       name: name,
-      description: `Operations for ${name} resource`
+      description: tagDescription
     });
 
     // Add schema to components
     spec.components.schemas[name] = generateResourceSchema(resource);
+
+    // Generate relational paths if RelationPlugin is active
+    if (relationsPlugin && relationsPlugin.relations && relationsPlugin.relations[name]) {
+      const relationsDef = relationsPlugin.relations[name];
+
+      for (const [relationName, relationConfig] of Object.entries(relationsDef)) {
+        // Skip belongsTo relations (not useful as REST endpoints)
+        if (relationConfig.type === 'belongsTo') {
+          continue;
+        }
+
+        // Check if relation should be exposed (default: yes)
+        const exposeRelation = config?.relations?.[relationName]?.expose !== false;
+        if (!exposeRelation) {
+          continue;
+        }
+
+        // Get related resource schema
+        const relatedResource = database.resources[relationConfig.resource];
+        if (!relatedResource) {
+          continue;
+        }
+
+        const relatedSchema = generateResourceSchema(relatedResource);
+
+        // Generate relational paths
+        const relationalPaths = generateRelationalPaths(
+          resource,
+          relationName,
+          relationConfig,
+          version,
+          relatedSchema
+        );
+
+        // Merge relational paths
+        Object.assign(spec.paths, relationalPaths);
+      }
+    }
   }
 
   // Add authentication endpoints if enabled

package/src/plugins/backup/multi-backup-driver.class.js

@@ -22,7 +22,6 @@ export default class MultiBackupDriver extends BaseBackupDriver {
       destinations: [],
       strategy: 'all', // 'all', 'any', 'priority'
       concurrency: 3,
-      requireAll: true, // For backward compatibility
       ...config
     });
 

package/src/plugins/backup.plugin.js

@@ -333,7 +333,7 @@ export class BackupPlugin extends Plugin {
     };
     
     const [ok] = await tryFn(() => 
-      this.database.resource(this.config.backupMetadataResource).insert(metadata)
+      this.database.resources[this.config.backupMetadataResource].insert(metadata)
     );
     
     return metadata;
@@ -341,7 +341,7 @@ export class BackupPlugin extends Plugin {
 
   async _updateBackupMetadata(backupId, updates) {
     const [ok] = await tryFn(() => 
-      this.database.resource(this.config.backupMetadataResource).update(backupId, updates)
+      this.database.resources[this.config.backupMetadataResource].update(backupId, updates)
     );
   }
 
@@ -387,7 +387,7 @@ export class BackupPlugin extends Plugin {
     let sinceTimestamp = null;
     if (type === 'incremental') {
       const [lastBackupOk, , lastBackups] = await tryFn(() =>
-        this.database.resource(this.config.backupMetadataResource).list({
+        this.database.resources[this.config.backupMetadataResource].list({
           filter: {
             status: 'completed',
             type: { $in: ['full', 'incremental'] }
@@ -802,7 +802,7 @@ export class BackupPlugin extends Plugin {
       
       // Merge with metadata from database
       const [metaOk, , metadataRecords] = await tryFn(() => 
-        this.database.resource(this.config.backupMetadataResource).list({
+        this.database.resources[this.config.backupMetadataResource].list({
           limit: options.limit || 50,
           sort: { timestamp: -1 }
         })
@@ -836,7 +836,7 @@ export class BackupPlugin extends Plugin {
    */
   async getBackupStatus(backupId) {
     const [ok, , backup] = await tryFn(() => 
-      this.database.resource(this.config.backupMetadataResource).get(backupId)
+      this.database.resources[this.config.backupMetadataResource].get(backupId)
     );
     
     return ok ? backup : null;
@@ -846,7 +846,7 @@ export class BackupPlugin extends Plugin {
     try {
       // Get all completed backups sorted by timestamp
       const [listOk, , allBackups] = await tryFn(() =>
-        this.database.resource(this.config.backupMetadataResource).list({
+        this.database.resources[this.config.backupMetadataResource].list({
           filter: { status: 'completed' },
           sort: { timestamp: -1 }
         })
@@ -938,7 +938,7 @@ export class BackupPlugin extends Plugin {
           await this.driver.delete(backup.id, backup.driverInfo);
 
           // Delete metadata
-          await this.database.resource(this.config.backupMetadataResource).delete(backup.id);
+          await this.database.resources[this.config.backupMetadataResource].delete(backup.id);
 
           if (this.config.verbose) {
             console.log(`[BackupPlugin] Deleted old backup: ${backup.id}`);
@@ -982,13 +982,6 @@ export class BackupPlugin extends Plugin {
       await this.driver.cleanup();
     }
   }
-
-  /**
-   * Cleanup plugin resources (alias for stop for backward compatibility)
-   */
-  async cleanup() {
-    await this.stop();
-  }
 }
 
 export default BackupPlugin;