npm - codehooks-js - Versions diffs - 1.3.24 → 1.4.0 - Mend

codehooks-js 1.3.24 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md +28 -0
package/crudlify/index.mjs +4 -0
package/crudlify/lib/schema/json-schema/index.mjs +35 -19
package/index.js +76 -7
package/openapi/crudlify-docs.mjs +823 -0
package/openapi/generator.mjs +417 -0
package/openapi/index.mjs +221 -0
package/openapi/schema-converter.mjs +668 -0
package/openapi/swagger-ui.mjs +92 -0
package/package.json +12 -3
package/types/index.d.ts +270 -10

package/openapi/swagger-ui.mjs ADDED Viewed

@@ -0,0 +1,92 @@
+/**
+ * Swagger UI HTML generator
+ * Generates HTML that loads Swagger UI from CDN
+ */
+const SWAGGER_UI_VERSION = '5.11.0';
+/**
+ * Generate Swagger UI HTML page
+ * @param {string} specUrl - URL to the OpenAPI JSON spec
+ * @param {object} config - Configuration options
+ * @param {string} [config.title] - Page title
+ * @param {string} [config.oauth2RedirectUrl] - OAuth2 redirect URL
+ * @param {string|null} [config.validatorUrl] - Validator URL (null to disable)
+ * @param {string} [config.favicon] - Favicon URL
+ * @returns {string} HTML string
+ */
+export function generateSwaggerHtml(specUrl, config = {}) {
+  const title = config.title || 'API Documentation';
+  const favicon = config.favicon || 'https://unpkg.com/swagger-ui-dist@' + SWAGGER_UI_VERSION + '/favicon-32x32.png';
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(title)}</title>
+  <link rel="icon" type="image/png" href="${escapeHtml(favicon)}">
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@${SWAGGER_UI_VERSION}/swagger-ui.css">
+  <style>
+    html { box-sizing: border-box; overflow-y: scroll; }
+    *, *:before, *:after { box-sizing: inherit; }
+    body { margin: 0; padding: 0; background: #fafafa; }
+    .swagger-ui .topbar { display: none; }
+    .swagger-ui .info { margin: 30px 0; }
+    .swagger-ui .info .title { font-size: 2em; }
+  </style>
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist@${SWAGGER_UI_VERSION}/swagger-ui-bundle.js" crossorigin></script>
+  <script src="https://unpkg.com/swagger-ui-dist@${SWAGGER_UI_VERSION}/swagger-ui-standalone-preset.js" crossorigin></script>
+  <script>
+    window.onload = function() {
+      const ui = SwaggerUIBundle({
+        url: "${escapeJs(specUrl)}",
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIStandalonePreset
+        ],
+        plugins: [
+          SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: "StandaloneLayout"${config.oauth2RedirectUrl ? `,
+        oauth2RedirectUrl: "${escapeJs(config.oauth2RedirectUrl)}"` : ''}${config.validatorUrl !== undefined ? `,
+        validatorUrl: ${config.validatorUrl === null ? 'null' : `"${escapeJs(config.validatorUrl)}"`}` : ''}
+      });
+      window.ui = ui;
+    };
+  </script>
+</body>
+</html>`;
+}
+/**
+ * Escape HTML special characters
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeHtml(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+/**
+ * Escape string for JavaScript
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeJs(str) {
+  return String(str)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r');
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "codehooks-js",
-  "version": "1.3.24",
+  "version": "1.4.0",
   "type": "module",
   "description": "Codehooks.io official library - provides express.JS like syntax",
   "main": "index.js",
@@ -18,6 +18,11 @@
     "./crudlify/lib/schema/zod/index.mjs",
     "./workflow/index.mjs",
     "./workflow/engine.mjs",
+    "./openapi/index.mjs",
+    "./openapi/generator.mjs",
+    "./openapi/schema-converter.mjs",
+    "./openapi/swagger-ui.mjs",
+    "./openapi/crudlify-docs.mjs",
     "./types",
     "tsconfig.json"
   ],
@@ -44,7 +49,9 @@
     "queue",
     "cron",
     "schedule",
-    "mongodb"
+    "mongodb",
+    "openapi",
+    "swagger"
   ],
   "dependencies": {
     "lodash": "^4.17.21",
@@ -53,6 +60,8 @@
   },
   "devDependencies": {
     "@types/mime": "^3.0.4",
-    "@types/node": "^22.15.19"
+    "@types/node": "^22.15.19",
+    "yup": "^1.7.1",
+    "zod": "^4.3.6"
   }
 }

package/types/index.d.ts CHANGED Viewed

@@ -313,8 +313,9 @@ export type DatastoreAPI = {
   collection: (collection: string) => NoSQLAPI;
   /**
    * - Get object by ID (objectID) or query (NoSQL query {...}), returns a Promise with the object
+   * @throws {Error} Rejects if the object is not found
    */
-  getOne: (collection: string, query: string | object) => Promise<any>;
+  getOne: (collection: string, query: string | object) => Promise<object>;
   /**
    * - Get stream of objects by query
    * * https://codehooks.io/docs/nosql-database-api#getmanycollection-query-options
@@ -322,12 +323,13 @@ export type DatastoreAPI = {
   getMany: (collection: string, query?: object, options?: object) => DataStream;
   /**
    * - Get object by ID (objectID) or query (NoSQL query {...}), returns a Promise with the object (alias for getOne)
+   * @throws {Error} Rejects if the object is not found
    */
-  findOne: (collection: string, query: string | object) => Promise<any>;
+  findOne: (collection: string, query: string | object) => Promise<object>;
   /**
    * - Get object by ID (objectID) or query (NoSQL query {...}), returns a Promise with the object or null if not found
    */
-  findOneOrNull: (collection: string, query: string | object) => Promise<any>;
+  findOneOrNull: (collection: string, query: string | object) => Promise<object | null>;
   /**
    * - Alias for getMany
    * https://codehooks.io/docs/nosql-database-api#getmanycollection-query-options
@@ -344,14 +346,14 @@ export type DatastoreAPI = {
    * @param query string | object
    * @param updateoperators object
    * @param options object - {upsert: true}
-   * @returns Promise<any>
+   * @returns Promise<object>
    */
   updateOne: (
     collection: string,
     query: string | object,
     updateoperators?: object,
     options?: object
-  ) => Promise<any>;
+  ) => Promise<object>;
   /**
    * - Update multiple data objects in a datastore collection.
    * - Input document is patched with the matched database objects
@@ -361,7 +363,7 @@ export type DatastoreAPI = {
     query: object,
     document: object,
     updateoperators?: object
-  ) => Promise<any>;
+  ) => Promise<object>;
   /**
    * - Replace one data object by ID in a datastore collection.
    * - Input document overwrites the matched database object, the _id value is not overwritten.
@@ -369,8 +371,9 @@ export type DatastoreAPI = {
   replaceOne: (
     collection: string,
     query: string | object,
+    document: object,
     options?: object
-  ) => Promise<any>;
+  ) => Promise<object>;
   /**
    * - Replace multiple data objects in a datastore collection.
    * - Input document overwrites the matched database objects. The _id value is not overwritten
@@ -378,16 +381,17 @@ export type DatastoreAPI = {
   replaceMany: (
     collection: string,
     query: object,
+    document: object,
     options?: object
-  ) => Promise<any>;
+  ) => Promise<object>;
   /**
    * - Remove one data object by ID in a collection in the current Datastore
    */
-  removeOne: (collection: string, query: string | object) => Promise<any>;
+  removeOne: (collection: string, query: string | object) => Promise<object>;
   /**
    * - Remove multiple data objects in a collection in the current Datastore
    */
-  removeMany: (collection: string, query: object) => Promise<any>;
+  removeMany: (collection: string, query: object) => Promise<object>;
   /**
    * - Set a key-value pair in the current Datastore
    */
@@ -1081,6 +1085,22 @@ export class Codehooks {
    * @returns Promise with the fetched data
    */
   internalFetch: (url: string, options?: any) => Promise<any>;
+  /**
+   * Enable OpenAPI documentation
+   * @param config - OpenAPI configuration
+   * @param uiPath - Path to serve Swagger UI (default: '/docs')
+   * @returns this for chaining
+   * @example
+   * app.openapi({
+   *   info: {
+   *     title: "My API",
+   *     version: "1.0.0"
+   *   }
+   * }, '/docs');
+   */
+  openapi: (config?: OpenAPIConfig, uiPath?: string) => Codehooks;
+  /** Stored OpenAPI metadata for routes */
+  openApiMeta: Record<string, OpenAPIRouteSpec>;
 }
 declare const _coho: Codehooks;
@@ -1500,4 +1520,244 @@ export type WorkflowEventData = {
   [key: string]: any;
 };
+// ============================================
+// OpenAPI Documentation Types
+// ============================================
+/**
+ * OpenAPI JSON Schema type (subset)
+ */
+export type OpenAPISchema = {
+  type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+  format?: string;
+  items?: OpenAPISchema;
+  properties?: Record<string, OpenAPISchema>;
+  required?: string[];
+  $ref?: string;
+  enum?: any[];
+  default?: any;
+  example?: any;
+  description?: string;
+  nullable?: boolean;
+  allOf?: OpenAPISchema[];
+  oneOf?: OpenAPISchema[];
+  anyOf?: OpenAPISchema[];
+  [key: string]: any;
+};
+/**
+ * OpenAPI Parameter specification
+ */
+export type OpenAPIParameter = {
+  name: string;
+  in: 'path' | 'query' | 'header' | 'cookie';
+  description?: string;
+  required?: boolean;
+  schema: OpenAPISchema;
+  example?: any;
+};
+/**
+ * OpenAPI Request Body specification
+ */
+export type OpenAPIRequestBody = {
+  description?: string;
+  required?: boolean;
+  content: Record<string, { schema: OpenAPISchema; example?: any }>;
+};
+/**
+ * OpenAPI Response specification
+ */
+export type OpenAPIResponse = {
+  description: string;
+  content?: Record<string, { schema: OpenAPISchema; example?: any }>;
+  headers?: Record<string, { description?: string; schema: OpenAPISchema }>;
+};
+/**
+ * OpenAPI Route specification for openapi() wrapper
+ */
+export type OpenAPIRouteSpec = {
+  /** Short summary of what the operation does */
+  summary?: string;
+  /** Verbose explanation of the operation */
+  description?: string;
+  /** Tags for API documentation grouping */
+  tags?: string[];
+  /** Unique operation identifier for code generation */
+  operationId?: string;
+  /** Parameters (path, query, header, cookie) */
+  parameters?: OpenAPIParameter[];
+  /** Request body specification */
+  requestBody?: OpenAPIRequestBody;
+  /** Response specifications by status code */
+  responses?: Record<string, OpenAPIResponse>;
+  /** Security requirements for this operation */
+  security?: Array<Record<string, string[]>>;
+  /** Whether this operation is deprecated */
+  deprecated?: boolean;
+};
+/**
+ * OpenAPI Info object
+ */
+export type OpenAPIInfo = {
+  title?: string;
+  description?: string;
+  version?: string;
+  termsOfService?: string;
+  contact?: { name?: string; url?: string; email?: string };
+  license?: { name: string; url?: string };
+};
+/**
+ * OpenAPI Server object
+ */
+export type OpenAPIServer = {
+  url: string;
+  description?: string;
+  variables?: Record<string, { default: string; enum?: string[]; description?: string }>;
+};
+/**
+ * OpenAPI Tag object
+ */
+export type OpenAPITag = {
+  name: string;
+  description?: string;
+  externalDocs?: { url: string; description?: string };
+};
+/**
+ * Filter operation object passed to the filter function
+ */
+export type OpenAPIFilterOperation = {
+  /** HTTP method (lowercase): 'get', 'post', 'put', 'patch', 'delete' */
+  method: string;
+  /** Route path: '/todos', '/todos/{ID}' */
+  path: string;
+  /** Operation ID if set */
+  operationId?: string;
+  /** Array of tags */
+  tags: string[];
+  /** Operation summary */
+  summary?: string;
+};
+/**
+ * OpenAPI Configuration for app.openapi()
+ */
+export type OpenAPIConfig = {
+  /** OpenAPI Info object */
+  info?: OpenAPIInfo;
+  /** Server definitions */
+  servers?: OpenAPIServer[];
+  /** Custom schemas to add to components */
+  components?: {
+    schemas?: Record<string, OpenAPISchema>;
+    securitySchemes?: Record<string, any>;
+  };
+  /** Global security requirements */
+  security?: Array<Record<string, string[]>>;
+  /** Path to serve the OpenAPI JSON spec (default: '/openapi.json') */
+  specPath?: string;
+  /** Swagger UI configuration */
+  swaggerUi?: {
+    oauth2RedirectUrl?: string;
+    validatorUrl?: string | null;
+    favicon?: string;
+  };
+  /** Tags for grouping endpoints */
+  tags?: OpenAPITag[];
+  /** External documentation */
+  externalDocs?: { url: string; description?: string };
+  /**
+   * Filter function to control which operations appear in the documentation.
+   * Return true to include the operation, false to exclude it.
+   * @example
+   * // Exclude DELETE operations
+   * filter: (op) => op.method !== 'delete'
+   *
+   * // Exclude internal routes
+   * filter: (op) => !op.path.startsWith('/internal')
+   *
+   * // Only include specific tags
+   * filter: (op) => op.tags.includes('Public')
+   */
+  filter?: (op: OpenAPIFilterOperation) => boolean;
+};
+/**
+ * Wrap a route handler with OpenAPI documentation
+ * @param spec - OpenAPI specification for this route
+ * @returns Middleware function with attached metadata
+ * @example
+ * app.get('/users/:id',
+ *   openapi({
+ *     summary: "Get user by ID",
+ *     tags: ["Users"],
+ *     responses: { 200: { description: "Success" } }
+ *   }),
+ *   (req, res) => res.json({ id: req.params.id })
+ * );
+ */
+export function openapi(spec: OpenAPIRouteSpec): (
+  req: httpRequest,
+  res: httpResponse,
+  next: nextFunction
+) => void;
+/**
+ * Helper to create response specification
+ * @param description - Response description
+ * @param schema - Response schema (JSON Schema or Zod/Yup)
+ * @param contentType - Content type (default: 'application/json')
+ */
+export function response(
+  description: string,
+  schema?: OpenAPISchema,
+  contentType?: string
+): OpenAPIResponse;
+/**
+ * Helper to create request body specification
+ * @param schema - Request body schema
+ * @param options - Additional options
+ */
+export function body(
+  schema: OpenAPISchema,
+  options?: { required?: boolean; description?: string; contentType?: string }
+): OpenAPIRequestBody;
+/**
+ * Helper to create path parameter specification
+ * @param name - Parameter name
+ * @param options - Parameter options
+ */
+export function param(
+  name: string,
+  options?: { description?: string; schema?: OpenAPISchema; example?: any }
+): OpenAPIParameter;
+/**
+ * Helper to create query parameter specification
+ * @param name - Parameter name
+ * @param options - Parameter options
+ */
+export function query(
+  name: string,
+  options?: { description?: string; required?: boolean; schema?: OpenAPISchema; example?: any }
+): OpenAPIParameter;
+/**
+ * Helper to create header parameter specification
+ * @param name - Header name
+ * @param options - Parameter options
+ */
+export function header(
+  name: string,
+  options?: { description?: string; required?: boolean; schema?: OpenAPISchema; example?: any }
+): OpenAPIParameter;
 //# sourceMappingURL=index.d.ts.map