codehooks-js 1.3.25 → 1.4.0

package/openapi/crudlify-docs.mjs

@@ -0,0 +1,823 @@
+/**
+ * Crudlify route documentation generator
+ * Generates OpenAPI paths and schemas for auto-generated CRUD routes
+ */
+
+import { convertToJsonSchema } from './schema-converter.mjs';
+
+/**
+ * Generate OpenAPI paths and components for crudlify routes
+ * @param {object} schemas - Map of collection name to schema
+ * @param {object} options - Crudlify options
+ * @param {string} [options.prefix] - Route prefix
+ * @returns {Promise<{paths: object, components: object}>}
+ */
+export async function generateCrudlifyPaths(schemas, options = {}) {
+  const prefix = options.prefix || '';
+  const paths = {};
+  const components = { schemas: {} };
+
+  // If no schemas defined, generate generic collection docs
+  if (!schemas || Object.keys(schemas).length === 0) {
+    return generateGenericCrudPaths(prefix);
+  }
+
+  for (const [collection, schemaOrConfig] of Object.entries(schemas)) {
+    // Handle both formats:
+    // { users: zodSchema } - direct schema
+    // { users: { schema: zodSchema } } - wrapped schema
+    let schema = schemaOrConfig;
+    if (schemaOrConfig && typeof schemaOrConfig === 'object' && schemaOrConfig.schema) {
+      schema = schemaOrConfig.schema;
+    }
+
+    // Skip null schemas (allows any data)
+    const hasSchema = schema !== null && schema !== undefined;
+
+    // Check if user provided explicit openApiSchema in config
+    let explicitOpenApiSchema = null;
+    if (schemaOrConfig && typeof schemaOrConfig === 'object' && schemaOrConfig.openApiSchema) {
+      explicitOpenApiSchema = schemaOrConfig.openApiSchema;
+    }
+
+    // Convert schema to JSON Schema
+    let jsonSchema = {
+      type: 'object',
+      additionalProperties: true,
+      description: 'Accepts any valid JSON object (no schema validation)'
+    };
+
+    if (explicitOpenApiSchema) {
+      // User provided explicit OpenAPI schema - use it directly
+      jsonSchema = explicitOpenApiSchema;
+    } else if (hasSchema) {
+      try {
+        jsonSchema = await convertToJsonSchema(schema);
+      } catch (error) {
+        console.warn(`Failed to convert schema for ${collection}:`, error.message);
+      }
+    }
+
+    // Store in components
+    const schemaName = capitalizeFirst(collection);
+    components.schemas[schemaName] = jsonSchema;
+
+    // Collection routes: POST (create), GET (list)
+    const collectionPath = `${prefix}/${collection}`;
+    paths[collectionPath] = {
+      get: generateGetManySpec(collection, schemaName),
+      post: generateCreateSpec(collection, schemaName, hasSchema)
+    };
+
+    // Document routes: GET, PUT, PATCH, DELETE by ID
+    const documentPath = `${prefix}/${collection}/{ID}`;
+    paths[documentPath] = {
+      get: generateGetOneSpec(collection, schemaName),
+      put: generateReplaceSpec(collection, schemaName, hasSchema),
+      patch: generatePatchSpec(collection, schemaName),
+      delete: generateDeleteSpec(collection, schemaName)
+    };
+
+    // Batch operations: PATCH, DELETE by query
+    const byQueryPath = `${prefix}/${collection}/_byquery`;
+    paths[byQueryPath] = {
+      patch: generatePatchManySpec(collection, schemaName),
+      delete: generateDeleteManySpec(collection, schemaName)
+    };
+  }
+
+  return { paths, components };
+}
+
+/**
+ * Generate GET (list) endpoint spec
+ */
+function generateGetManySpec(collection, schemaName) {
+  return {
+    summary: `List ${collection}`,
+    description: `Retrieve a list of ${collection} with optional filtering and pagination`,
+    tags: [capitalizeFirst(collection)],
+    operationId: `list${capitalizeFirst(collection)}`,
+    parameters: [
+      {
+        name: 'q',
+        in: 'query',
+        description: 'MongoDB-style query filter as JSON string, e.g. {"status":"active"}',
+        required: false,
+        schema: { type: 'string' }
+      },
+      {
+        name: 'h',
+        in: 'query',
+        description: 'Query hints as JSON: {"$limit":10,"$offset":0,"$fields":{"name":1},"$sort":{"created":-1}}',
+        required: false,
+        schema: { type: 'string' }
+      },
+      {
+        name: 'limit',
+        in: 'query',
+        description: 'Maximum number of items to return',
+        required: false,
+        schema: { type: 'integer', default: 100 }
+      },
+      {
+        name: 'offset',
+        in: 'query',
+        description: 'Number of items to skip',
+        required: false,
+        schema: { type: 'integer', default: 0 }
+      },
+      {
+        name: 'sort',
+        in: 'query',
+        description: 'Sort field (prefix with - for descending)',
+        required: false,
+        schema: { type: 'string' }
+      }
+    ],
+    responses: {
+      200: {
+        description: `List of ${collection}`,
+        content: {
+          'application/json': {
+            schema: {
+              type: 'array',
+              items: { $ref: `#/components/schemas/${schemaName}` }
+            }
+          }
+        }
+      },
+      400: { description: 'Invalid query parameters' },
+      404: { description: 'Collection schema not found' }
+    }
+  };
+}
+
+/**
+ * Generate POST (create) endpoint spec
+ */
+function generateCreateSpec(collection, schemaName, hasSchema) {
+  return {
+    summary: `Create ${singularize(collection)}`,
+    description: `Create a new document in ${collection}${hasSchema ? ' (validated against schema)' : ''}`,
+    tags: [capitalizeFirst(collection)],
+    operationId: `create${capitalizeFirst(singularize(collection))}`,
+    requestBody: {
+      required: true,
+      description: `${capitalizeFirst(singularize(collection))} data`,
+      content: {
+        'application/json': {
+          schema: { $ref: `#/components/schemas/${schemaName}` }
+        }
+      }
+    },
+    responses: {
+      201: {
+        description: `${capitalizeFirst(singularize(collection))} created successfully`,
+        content: {
+          'application/json': {
+            schema: {
+              allOf: [
+                { $ref: `#/components/schemas/${schemaName}` },
+                {
+                  type: 'object',
+                  properties: {
+                    _id: { type: 'string', description: 'Unique document ID' }
+                  }
+                }
+              ]
+            }
+          }
+        }
+      },
+      400: { description: 'Validation error or invalid request' }
+    }
+  };
+}
+
+/**
+ * Generate GET (one) endpoint spec
+ */
+function generateGetOneSpec(collection, schemaName) {
+  return {
+    summary: `Get ${singularize(collection)} by ID`,
+    description: `Retrieve a single ${singularize(collection)} by its unique identifier`,
+    tags: [capitalizeFirst(collection)],
+    operationId: `get${capitalizeFirst(singularize(collection))}`,
+    parameters: [
+      {
+        name: 'ID',
+        in: 'path',
+        required: true,
+        description: `Unique ${singularize(collection)} identifier`,
+        schema: { type: 'string' }
+      }
+    ],
+    responses: {
+      200: {
+        description: `${capitalizeFirst(singularize(collection))} found`,
+        content: {
+          'application/json': {
+            schema: {
+              allOf: [
+                { $ref: `#/components/schemas/${schemaName}` },
+                {
+                  type: 'object',
+                  properties: {
+                    _id: { type: 'string', description: 'Unique document ID' }
+                  }
+                }
+              ]
+            }
+          }
+        }
+      },
+      404: { description: `${capitalizeFirst(singularize(collection))} not found` }
+    }
+  };
+}
+
+/**
+ * Generate PUT (replace) endpoint spec
+ */
+function generateReplaceSpec(collection, schemaName, hasSchema) {
+  return {
+    summary: `Replace ${singularize(collection)}`,
+    description: `Replace an existing ${singularize(collection)} document entirely${hasSchema ? ' (validated against schema)' : ''}`,
+    tags: [capitalizeFirst(collection)],
+    operationId: `replace${capitalizeFirst(singularize(collection))}`,
+    parameters: [
+      {
+        name: 'ID',
+        in: 'path',
+        required: true,
+        description: `Unique ${singularize(collection)} identifier`,
+        schema: { type: 'string' }
+      }
+    ],
+    requestBody: {
+      required: true,
+      description: `Complete ${singularize(collection)} data`,
+      content: {
+        'application/json': {
+          schema: { $ref: `#/components/schemas/${schemaName}` }
+        }
+      }
+    },
+    responses: {
+      200: {
+        description: `${capitalizeFirst(singularize(collection))} replaced successfully`,
+        content: {
+          'application/json': {
+            schema: {
+              allOf: [
+                { $ref: `#/components/schemas/${schemaName}` },
+                {
+                  type: 'object',
+                  properties: {
+                    _id: { type: 'string', description: 'Unique document ID' }
+                  }
+                }
+              ]
+            }
+          }
+        }
+      },
+      400: { description: 'Validation error' },
+      404: { description: `${capitalizeFirst(singularize(collection))} not found` }
+    }
+  };
+}
+
+/**
+ * Generate PATCH (update) endpoint spec
+ */
+function generatePatchSpec(collection, schemaName) {
+  return {
+    summary: `Update ${singularize(collection)}`,
+    description: `Partially update an existing ${singularize(collection)} document`,
+    tags: [capitalizeFirst(collection)],
+    operationId: `update${capitalizeFirst(singularize(collection))}`,
+    parameters: [
+      {
+        name: 'ID',
+        in: 'path',
+        required: true,
+        description: `Unique ${singularize(collection)} identifier`,
+        schema: { type: 'string' }
+      }
+    ],
+    requestBody: {
+      required: true,
+      description: `Partial ${singularize(collection)} data to update`,
+      content: {
+        'application/json': {
+          schema: {
+            type: 'object',
+            description: 'Fields to update'
+          }
+        }
+      }
+    },
+    responses: {
+      200: {
+        description: `${capitalizeFirst(singularize(collection))} updated successfully`,
+        content: {
+          'application/json': {
+            schema: {
+              allOf: [
+                { $ref: `#/components/schemas/${schemaName}` },
+                {
+                  type: 'object',
+                  properties: {
+                    _id: { type: 'string', description: 'Unique document ID' }
+                  }
+                }
+              ]
+            }
+          }
+        }
+      },
+      400: { description: 'Validation error' },
+      404: { description: `${capitalizeFirst(singularize(collection))} not found` }
+    }
+  };
+}
+
+/**
+ * Generate DELETE endpoint spec
+ */
+function generateDeleteSpec(collection, schemaName) {
+  return {
+    summary: `Delete ${singularize(collection)}`,
+    description: `Delete a ${singularize(collection)} by its unique identifier`,
+    tags: [capitalizeFirst(collection)],
+    operationId: `delete${capitalizeFirst(singularize(collection))}`,
+    parameters: [
+      {
+        name: 'ID',
+        in: 'path',
+        required: true,
+        description: `Unique ${singularize(collection)} identifier`,
+        schema: { type: 'string' }
+      }
+    ],
+    responses: {
+      200: {
+        description: `${capitalizeFirst(singularize(collection))} deleted successfully`,
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              properties: {
+                _id: { type: 'string', description: 'ID of deleted document' }
+              }
+            }
+          }
+        }
+      },
+      404: { description: `${capitalizeFirst(singularize(collection))} not found` }
+    }
+  };
+}
+
+/**
+ * Generate PATCH (batch update) endpoint spec
+ */
+function generatePatchManySpec(collection, schemaName) {
+  return {
+    summary: `Batch update ${collection}`,
+    description: `Update multiple ${collection} documents matching a query`,
+    tags: [capitalizeFirst(collection)],
+    operationId: `updateMany${capitalizeFirst(collection)}`,
+    parameters: [
+      {
+        name: 'q',
+        in: 'query',
+        description: 'MongoDB-style query filter as JSON string',
+        required: true,
+        schema: { type: 'string' }
+      }
+    ],
+    requestBody: {
+      required: true,
+      description: 'Fields to update on matching documents',
+      content: {
+        'application/json': {
+          schema: {
+            type: 'object',
+            description: 'Update operations'
+          }
+        }
+      }
+    },
+    responses: {
+      200: {
+        description: 'Documents updated successfully',
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              properties: {
+                modifiedCount: { type: 'integer', description: 'Number of documents modified' }
+              }
+            }
+          }
+        }
+      },
+      400: { description: 'Invalid query or validation error' },
+      404: { description: 'Collection schema not found' }
+    }
+  };
+}
+
+/**
+ * Generate DELETE (batch) endpoint spec
+ */
+function generateDeleteManySpec(collection, schemaName) {
+  return {
+    summary: `Batch delete ${collection}`,
+    description: `Delete multiple ${collection} documents matching a query`,
+    tags: [capitalizeFirst(collection)],
+    operationId: `deleteMany${capitalizeFirst(collection)}`,
+    parameters: [
+      {
+        name: 'q',
+        in: 'query',
+        description: 'MongoDB-style query filter as JSON string',
+        required: true,
+        schema: { type: 'string' }
+      }
+    ],
+    responses: {
+      200: {
+        description: 'Documents deleted successfully',
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              properties: {
+                deletedCount: { type: 'integer', description: 'Number of documents deleted' }
+              }
+            }
+          }
+        }
+      },
+      400: { description: 'Invalid query' },
+      404: { description: 'Collection schema not found' }
+    }
+  };
+}
+
+/**
+ * Capitalize first letter
+ * @param {string} str
+ * @returns {string}
+ */
+function capitalizeFirst(str) {
+  if (!str) return '';
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Simple singularize (removes trailing 's')
+ * @param {string} str
+ * @returns {string}
+ */
+function singularize(str) {
+  if (!str) return '';
+  if (str.endsWith('ies')) {
+    return str.slice(0, -3) + 'y';
+  }
+  if (str.endsWith('es') && (str.endsWith('sses') || str.endsWith('xes') || str.endsWith('ches') || str.endsWith('shes'))) {
+    return str.slice(0, -2);
+  }
+  if (str.endsWith('s') && !str.endsWith('ss')) {
+    return str.slice(0, -1);
+  }
+  return str;
+}
+
+/**
+ * Generate generic CRUD documentation when no schemas are defined
+ * Documents the /{collection} routes that accept any collection name
+ * @param {string} prefix - Route prefix
+ * @returns {{paths: object, components: object}}
+ */
+function generateGenericCrudPaths(prefix) {
+  const paths = {};
+  const components = {
+    schemas: {
+      Document: {
+        type: 'object',
+        additionalProperties: true,
+        description: 'Any valid JSON object'
+      }
+    }
+  };
+
+  const collectionParam = {
+    name: 'collection',
+    in: 'path',
+    required: true,
+    description: 'Collection name (e.g., users, products, orders)',
+    schema: { type: 'string' }
+  };
+
+  const idParam = {
+    name: 'ID',
+    in: 'path',
+    required: true,
+    description: 'Unique document identifier',
+    schema: { type: 'string' }
+  };
+
+  // Collection routes: /{collection}
+  const collectionPath = `${prefix}/{collection}`;
+  paths[collectionPath] = {
+    get: {
+      summary: 'List documents',
+      description: 'Retrieve documents from any collection with optional filtering and pagination',
+      tags: ['Collections'],
+      operationId: 'listDocuments',
+      parameters: [
+        collectionParam,
+        {
+          name: 'q',
+          in: 'query',
+          description: 'MongoDB-style query filter as JSON string, e.g. {"status":"active"}',
+          required: false,
+          schema: { type: 'string' }
+        },
+        {
+          name: 'h',
+          in: 'query',
+          description: 'Query hints as JSON: {"$limit":10,"$offset":0,"$fields":{"name":1},"$sort":{"created":-1}}',
+          required: false,
+          schema: { type: 'string' }
+        },
+        {
+          name: 'limit',
+          in: 'query',
+          description: 'Maximum number of items to return',
+          required: false,
+          schema: { type: 'integer', default: 100 }
+        },
+        {
+          name: 'offset',
+          in: 'query',
+          description: 'Number of items to skip',
+          required: false,
+          schema: { type: 'integer', default: 0 }
+        }
+      ],
+      responses: {
+        200: {
+          description: 'List of documents',
+          content: {
+            'application/json': {
+              schema: {
+                type: 'array',
+                items: { $ref: '#/components/schemas/Document' }
+              }
+            }
+          }
+        },
+        400: { description: 'Invalid query parameters' }
+      }
+    },
+    post: {
+      summary: 'Create document',
+      description: 'Create a new document in any collection. No schema validation is applied.',
+      tags: ['Collections'],
+      operationId: 'createDocument',
+      parameters: [collectionParam],
+      requestBody: {
+        required: true,
+        description: 'Document data (any valid JSON)',
+        content: {
+          'application/json': {
+            schema: { $ref: '#/components/schemas/Document' }
+          }
+        }
+      },
+      responses: {
+        201: {
+          description: 'Document created successfully',
+          content: {
+            'application/json': {
+              schema: {
+                allOf: [
+                  { $ref: '#/components/schemas/Document' },
+                  {
+                    type: 'object',
+                    properties: {
+                      _id: { type: 'string', description: 'Unique document ID' }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        },
+        400: { description: 'Invalid request body' }
+      }
+    }
+  };
+
+  // Document routes: /{collection}/{ID}
+  const documentPath = `${prefix}/{collection}/{ID}`;
+  paths[documentPath] = {
+    get: {
+      summary: 'Get document by ID',
+      description: 'Retrieve a single document by its unique identifier',
+      tags: ['Collections'],
+      operationId: 'getDocument',
+      parameters: [collectionParam, idParam],
+      responses: {
+        200: {
+          description: 'Document found',
+          content: {
+            'application/json': {
+              schema: {
+                allOf: [
+                  { $ref: '#/components/schemas/Document' },
+                  {
+                    type: 'object',
+                    properties: {
+                      _id: { type: 'string', description: 'Unique document ID' }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        },
+        404: { description: 'Document not found' }
+      }
+    },
+    put: {
+      summary: 'Replace document',
+      description: 'Replace an existing document entirely',
+      tags: ['Collections'],
+      operationId: 'replaceDocument',
+      parameters: [collectionParam, idParam],
+      requestBody: {
+        required: true,
+        description: 'Complete document data',
+        content: {
+          'application/json': {
+            schema: { $ref: '#/components/schemas/Document' }
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: 'Document replaced successfully',
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/Document' }
+            }
+          }
+        },
+        404: { description: 'Document not found' }
+      }
+    },
+    patch: {
+      summary: 'Update document',
+      description: 'Partially update an existing document',
+      tags: ['Collections'],
+      operationId: 'updateDocument',
+      parameters: [collectionParam, idParam],
+      requestBody: {
+        required: true,
+        description: 'Fields to update',
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              description: 'Partial document data'
+            }
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: 'Document updated successfully',
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/Document' }
+            }
+          }
+        },
+        404: { description: 'Document not found' }
+      }
+    },
+    delete: {
+      summary: 'Delete document',
+      description: 'Delete a document by its unique identifier',
+      tags: ['Collections'],
+      operationId: 'deleteDocument',
+      parameters: [collectionParam, idParam],
+      responses: {
+        200: {
+          description: 'Document deleted successfully',
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  _id: { type: 'string', description: 'ID of deleted document' }
+                }
+              }
+            }
+          }
+        },
+        404: { description: 'Document not found' }
+      }
+    }
+  };
+
+  // Batch operations: /{collection}/_byquery
+  const byQueryPath = `${prefix}/{collection}/_byquery`;
+  paths[byQueryPath] = {
+    patch: {
+      summary: 'Batch update documents',
+      description: 'Update multiple documents matching a query',
+      tags: ['Collections'],
+      operationId: 'updateDocuments',
+      parameters: [
+        collectionParam,
+        {
+          name: 'q',
+          in: 'query',
+          description: 'MongoDB-style query filter as JSON string',
+          required: true,
+          schema: { type: 'string' }
+        }
+      ],
+      requestBody: {
+        required: true,
+        description: 'Fields to update on matching documents',
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              description: 'Update operations'
+            }
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: 'Documents updated successfully',
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  modifiedCount: { type: 'integer', description: 'Number of documents modified' }
+                }
+              }
+            }
+          }
+        },
+        400: { description: 'Invalid query' }
+      }
+    },
+    delete: {
+      summary: 'Batch delete documents',
+      description: 'Delete multiple documents matching a query',
+      tags: ['Collections'],
+      operationId: 'deleteDocuments',
+      parameters: [
+        collectionParam,
+        {
+          name: 'q',
+          in: 'query',
+          description: 'MongoDB-style query filter as JSON string',
+          required: true,
+          schema: { type: 'string' }
+        }
+      ],
+      responses: {
+        200: {
+          description: 'Documents deleted successfully',
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  deletedCount: { type: 'integer', description: 'Number of documents deleted' }
+                }
+              }
+            }
+          }
+        },
+        400: { description: 'Invalid query' }
+      }
+    }
+  };
+
+  return { paths, components };
+}