rads-db 3.2.21 → 3.2.23

package/integrations/getOpenApiSpec.cjs

@@ -0,0 +1,375 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getOpenApiSpec = getOpenApiSpec;
+function primitiveToOas(type) {
+  switch (type) {
+    case "string":
+      return {
+        type: "string"
+      };
+    case "number":
+      return {
+        type: "number"
+      };
+    case "boolean":
+      return {
+        type: "boolean"
+      };
+    case "Record<string, string>":
+      return {
+        type: "object",
+        additionalProperties: {
+          type: "string"
+        }
+      };
+    case "Record<string, any>":
+      return {
+        type: "object",
+        additionalProperties: true
+      };
+    default:
+      return {};
+  }
+}
+function relationToOas(field, schema) {
+  const properties = {
+    id: {
+      type: "string"
+    }
+  };
+  for (const fname of field.relationDenormFields ?? []) {
+    const relField = schema[field.type]?.fields?.[fname];
+    properties[fname] = relField ? primitiveToOas(relField.type) : {};
+  }
+  return {
+    type: "object",
+    required: ["id"],
+    properties
+  };
+}
+function fieldToOas(field, schema) {
+  const entry = schema[field.type];
+  let itemSchema;
+  if (field.isRelation) {
+    itemSchema = relationToOas(field, schema);
+  } else if (entry) {
+    itemSchema = entry.enumValues ? {
+      type: "string",
+      enum: Object.keys(entry.enumValues)
+    } : {
+      $ref: `#/components/schemas/${field.type}`
+    };
+  } else {
+    itemSchema = primitiveToOas(field.type);
+  }
+  return field.isArray ? {
+    type: "array",
+    items: itemSchema
+  } : itemSchema;
+}
+function buildObjectSchema(entity, schema, allOptional = false) {
+  const properties = {};
+  const required = [];
+  for (const [name, field] of Object.entries(entity.fields ?? {})) {
+    if (field.isInverseRelation) continue;
+    properties[name] = {
+      ...fieldToOas(field, schema),
+      ...(field.comment ? {
+        description: field.comment
+      } : {})
+    };
+    if (!allOptional && field.isRequired) required.push(name);
+  }
+  return {
+    type: "object",
+    ...(entity.comment ? {
+      description: entity.comment
+    } : {}),
+    properties,
+    ...(required.length > 0 ? {
+      required
+    } : {})
+  };
+}
+const whereSchema = {
+  type: "object",
+  additionalProperties: true
+};
+const includeSchema = {
+  type: "object",
+  additionalProperties: true
+};
+const paginationProps = {
+  cursor: {
+    type: "string"
+  },
+  maxItemCount: {
+    type: "integer"
+  },
+  orderBy: {
+    type: "string",
+    description: 'Single order-by expression, e.g. "name_asc"'
+  },
+  orderByArray: {
+    type: "array",
+    items: {
+      type: "string"
+    },
+    description: "Multiple order-by expressions"
+  }
+};
+const getRequestSchema = {
+  type: "object",
+  properties: {
+    where: whereSchema,
+    include: includeSchema
+  }
+};
+const getManyRequestSchema = {
+  type: "object",
+  properties: {
+    where: whereSchema,
+    include: includeSchema,
+    ...paginationProps
+  }
+};
+const getAggRequestSchema = {
+  type: "object",
+  required: ["agg"],
+  properties: {
+    where: whereSchema,
+    agg: {
+      type: "array",
+      items: {
+        type: "string"
+      },
+      description: 'Aggregation operations: "_count", "field_min", "field_max", "field_sum"'
+    },
+    ...paginationProps
+  }
+};
+function jsonBody(s) {
+  return {
+    required: true,
+    content: {
+      "application/json": {
+        schema: s
+      }
+    }
+  };
+}
+function jsonOk(s, description = "Success") {
+  return {
+    "200": {
+      description,
+      content: {
+        "application/json": {
+          schema: s
+        }
+      }
+    }
+  };
+}
+function getOpenApiSpec(options, openApiOptions) {
+  const {
+    db,
+    prefix = "/api/"
+  } = options;
+  const schema = db._schema;
+  const base = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+  const paths = {};
+  const schemas = {};
+  paths[`${base}/me`] = {
+    get: {
+      summary: "Get current user",
+      tags: ["Auth"],
+      responses: jsonOk({
+        type: "object",
+        properties: {
+          userId: {
+            type: "string",
+            nullable: true
+          }
+        }
+      })
+    }
+  };
+  paths[`${base}/uploadFile`] = {
+    post: {
+      summary: "Upload a file",
+      tags: ["Files"],
+      requestBody: jsonBody({
+        type: "object",
+        required: ["blobDataUrl"],
+        properties: {
+          blobDataUrl: {
+            type: "string",
+            description: "Base64 data URL: data:<mime>;base64,<data>"
+          },
+          filename: {
+            type: "string"
+          },
+          containerName: {
+            type: "string"
+          }
+        }
+      }),
+      responses: jsonOk({
+        type: "object",
+        required: ["url"],
+        properties: {
+          url: {
+            type: "string"
+          }
+        }
+      })
+    }
+  };
+  paths[`${base}/radsTunnel`] = {
+    post: {
+      summary: "Direct database method access",
+      tags: ["Tunnel"],
+      requestBody: jsonBody({
+        type: "object",
+        properties: {
+          method: {
+            type: "string",
+            description: "Method to call (getMany, put, _schema, uploadFile, \u2026)"
+          },
+          entity: {
+            type: "string",
+            description: "Entity class name, e.g. TcUser"
+          },
+          args: {
+            description: "Arguments forwarded to the method"
+          }
+        }
+      }),
+      responses: jsonOk({})
+    }
+  };
+  for (const key in schema) {
+    const entity = schema[key];
+    if (!entity.decorators?.entity) continue;
+    const {
+      name,
+      handle,
+      handlePlural
+    } = entity;
+    const tag = name;
+    schemas[name] = buildObjectSchema(entity, schema);
+    schemas[`${name}Put`] = buildObjectSchema(entity, schema, true);
+    schemas[`${name}Put`].required = ["id"];
+    const ref = n => ({
+      $ref: `#/components/schemas/${n}`
+    });
+    paths[`${base}/${handle}`] = {
+      post: {
+        summary: `Get ${name}`,
+        tags: [tag],
+        requestBody: jsonBody(getRequestSchema),
+        responses: jsonOk(ref(name), `${name} object`)
+      },
+      put: {
+        summary: `Create or update ${name}`,
+        tags: [tag],
+        requestBody: jsonBody({
+          type: "object",
+          required: ["data"],
+          properties: {
+            data: ref(`${name}Put`)
+          }
+        }),
+        responses: jsonOk(ref(name), `Updated ${name}`)
+      }
+    };
+    paths[`${base}/${handlePlural}`] = {
+      post: {
+        summary: `Get many ${name} objects`,
+        tags: [tag],
+        requestBody: jsonBody(getManyRequestSchema),
+        responses: jsonOk({
+          type: "object",
+          required: ["nodes"],
+          properties: {
+            nodes: {
+              type: "array",
+              items: ref(name)
+            },
+            cursor: {
+              type: "string",
+              nullable: true
+            }
+          }
+        }, `Paginated list of ${name}`)
+      },
+      put: {
+        summary: `Create or update many ${name} objects`,
+        tags: [tag],
+        requestBody: jsonBody({
+          type: "object",
+          required: ["data"],
+          properties: {
+            data: {
+              type: "array",
+              items: ref(`${name}Put`)
+            }
+          }
+        }),
+        responses: jsonOk({
+          type: "array",
+          items: ref(name)
+        }, `Updated ${name} list`)
+      }
+    };
+    paths[`${base}/${handle}/agg`] = {
+      post: {
+        summary: `Aggregate ${name} data`,
+        tags: [tag],
+        requestBody: jsonBody(getAggRequestSchema),
+        responses: jsonOk({
+          type: "object",
+          additionalProperties: {
+            type: "number",
+            nullable: true
+          }
+        }, `${name} aggregation result`)
+      }
+    };
+  }
+  for (const key in schema) {
+    const entry = schema[key];
+    if (entry.decorators?.entity || schemas[key]) continue;
+    if (entry.enumValues) {
+      schemas[key] = {
+        type: "string",
+        enum: Object.keys(entry.enumValues),
+        ...(entry.comment ? {
+          description: entry.comment
+        } : {})
+      };
+    } else if (entry.fields) {
+      schemas[key] = buildObjectSchema(entry, schema);
+    }
+  }
+  return {
+    openapi: "3.0.3",
+    info: {
+      title: openApiOptions?.title ?? "Rads DB API",
+      version: openApiOptions?.version ?? "1.0.0",
+      ...(openApiOptions?.description ? {
+        description: openApiOptions.description
+      } : {})
+    },
+    ...(openApiOptions?.servers ? {
+      servers: openApiOptions.servers
+    } : {}),
+    paths,
+    components: {
+      schemas
+    }
+  };
+}

package/integrations/getOpenApiSpec.d.ts

@@ -0,0 +1,11 @@
+import type { GetRestRoutesOptions } from '../types';
+export interface OpenApiSpecOptions {
+    title?: string;
+    version?: string;
+    description?: string;
+    servers?: {
+        url: string;
+        description?: string;
+    }[];
+}
+export declare function getOpenApiSpec(options: GetRestRoutesOptions, openApiOptions?: OpenApiSpecOptions): object;

package/integrations/getOpenApiSpec.mjs

@@ -0,0 +1,232 @@
+function primitiveToOas(type) {
+  switch (type) {
+    case "string":
+      return { type: "string" };
+    case "number":
+      return { type: "number" };
+    case "boolean":
+      return { type: "boolean" };
+    case "Record<string, string>":
+      return { type: "object", additionalProperties: { type: "string" } };
+    case "Record<string, any>":
+      return { type: "object", additionalProperties: true };
+    default:
+      return {};
+  }
+}
+function relationToOas(field, schema) {
+  const properties = { id: { type: "string" } };
+  for (const fname of field.relationDenormFields ?? []) {
+    const relField = schema[field.type]?.fields?.[fname];
+    properties[fname] = relField ? primitiveToOas(relField.type) : {};
+  }
+  return { type: "object", required: ["id"], properties };
+}
+function fieldToOas(field, schema) {
+  const entry = schema[field.type];
+  let itemSchema;
+  if (field.isRelation) {
+    itemSchema = relationToOas(field, schema);
+  } else if (entry) {
+    itemSchema = entry.enumValues ? { type: "string", enum: Object.keys(entry.enumValues) } : { $ref: `#/components/schemas/${field.type}` };
+  } else {
+    itemSchema = primitiveToOas(field.type);
+  }
+  return field.isArray ? { type: "array", items: itemSchema } : itemSchema;
+}
+function buildObjectSchema(entity, schema, allOptional = false) {
+  const properties = {};
+  const required = [];
+  for (const [name, field] of Object.entries(entity.fields ?? {})) {
+    if (field.isInverseRelation) continue;
+    properties[name] = {
+      ...fieldToOas(field, schema),
+      ...field.comment ? { description: field.comment } : {}
+    };
+    if (!allOptional && field.isRequired) required.push(name);
+  }
+  return {
+    type: "object",
+    ...entity.comment ? { description: entity.comment } : {},
+    properties,
+    ...required.length > 0 ? { required } : {}
+  };
+}
+const whereSchema = { type: "object", additionalProperties: true };
+const includeSchema = { type: "object", additionalProperties: true };
+const paginationProps = {
+  cursor: { type: "string" },
+  maxItemCount: { type: "integer" },
+  orderBy: { type: "string", description: 'Single order-by expression, e.g. "name_asc"' },
+  orderByArray: { type: "array", items: { type: "string" }, description: "Multiple order-by expressions" }
+};
+const getRequestSchema = {
+  type: "object",
+  properties: { where: whereSchema, include: includeSchema }
+};
+const getManyRequestSchema = {
+  type: "object",
+  properties: { where: whereSchema, include: includeSchema, ...paginationProps }
+};
+const getAggRequestSchema = {
+  type: "object",
+  required: ["agg"],
+  properties: {
+    where: whereSchema,
+    agg: {
+      type: "array",
+      items: { type: "string" },
+      description: 'Aggregation operations: "_count", "field_min", "field_max", "field_sum"'
+    },
+    ...paginationProps
+  }
+};
+function jsonBody(s) {
+  return { required: true, content: { "application/json": { schema: s } } };
+}
+function jsonOk(s, description = "Success") {
+  return { "200": { description, content: { "application/json": { schema: s } } } };
+}
+export function getOpenApiSpec(options, openApiOptions) {
+  const { db, prefix = "/api/" } = options;
+  const schema = db._schema;
+  const base = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+  const paths = {};
+  const schemas = {};
+  paths[`${base}/me`] = {
+    get: {
+      summary: "Get current user",
+      tags: ["Auth"],
+      responses: jsonOk({
+        type: "object",
+        properties: { userId: { type: "string", nullable: true } }
+      })
+    }
+  };
+  paths[`${base}/uploadFile`] = {
+    post: {
+      summary: "Upload a file",
+      tags: ["Files"],
+      requestBody: jsonBody({
+        type: "object",
+        required: ["blobDataUrl"],
+        properties: {
+          blobDataUrl: { type: "string", description: "Base64 data URL: data:<mime>;base64,<data>" },
+          filename: { type: "string" },
+          containerName: { type: "string" }
+        }
+      }),
+      responses: jsonOk({
+        type: "object",
+        required: ["url"],
+        properties: { url: { type: "string" } }
+      })
+    }
+  };
+  paths[`${base}/radsTunnel`] = {
+    post: {
+      summary: "Direct database method access",
+      tags: ["Tunnel"],
+      requestBody: jsonBody({
+        type: "object",
+        properties: {
+          method: { type: "string", description: "Method to call (getMany, put, _schema, uploadFile, \u2026)" },
+          entity: { type: "string", description: "Entity class name, e.g. TcUser" },
+          args: { description: "Arguments forwarded to the method" }
+        }
+      }),
+      responses: jsonOk({})
+    }
+  };
+  for (const key in schema) {
+    const entity = schema[key];
+    if (!entity.decorators?.entity) continue;
+    const { name, handle, handlePlural } = entity;
+    const tag = name;
+    schemas[name] = buildObjectSchema(entity, schema);
+    schemas[`${name}Put`] = buildObjectSchema(entity, schema, true);
+    schemas[`${name}Put`].required = ["id"];
+    const ref = (n) => ({ $ref: `#/components/schemas/${n}` });
+    paths[`${base}/${handle}`] = {
+      post: {
+        summary: `Get ${name}`,
+        tags: [tag],
+        requestBody: jsonBody(getRequestSchema),
+        responses: jsonOk(ref(name), `${name} object`)
+      },
+      put: {
+        summary: `Create or update ${name}`,
+        tags: [tag],
+        requestBody: jsonBody({
+          type: "object",
+          required: ["data"],
+          properties: { data: ref(`${name}Put`) }
+        }),
+        responses: jsonOk(ref(name), `Updated ${name}`)
+      }
+    };
+    paths[`${base}/${handlePlural}`] = {
+      post: {
+        summary: `Get many ${name} objects`,
+        tags: [tag],
+        requestBody: jsonBody(getManyRequestSchema),
+        responses: jsonOk(
+          {
+            type: "object",
+            required: ["nodes"],
+            properties: {
+              nodes: { type: "array", items: ref(name) },
+              cursor: { type: "string", nullable: true }
+            }
+          },
+          `Paginated list of ${name}`
+        )
+      },
+      put: {
+        summary: `Create or update many ${name} objects`,
+        tags: [tag],
+        requestBody: jsonBody({
+          type: "object",
+          required: ["data"],
+          properties: { data: { type: "array", items: ref(`${name}Put`) } }
+        }),
+        responses: jsonOk({ type: "array", items: ref(name) }, `Updated ${name} list`)
+      }
+    };
+    paths[`${base}/${handle}/agg`] = {
+      post: {
+        summary: `Aggregate ${name} data`,
+        tags: [tag],
+        requestBody: jsonBody(getAggRequestSchema),
+        responses: jsonOk(
+          { type: "object", additionalProperties: { type: "number", nullable: true } },
+          `${name} aggregation result`
+        )
+      }
+    };
+  }
+  for (const key in schema) {
+    const entry = schema[key];
+    if (entry.decorators?.entity || schemas[key]) continue;
+    if (entry.enumValues) {
+      schemas[key] = {
+        type: "string",
+        enum: Object.keys(entry.enumValues),
+        ...entry.comment ? { description: entry.comment } : {}
+      };
+    } else if (entry.fields) {
+      schemas[key] = buildObjectSchema(entry, schema);
+    }
+  }
+  return {
+    openapi: "3.0.3",
+    info: {
+      title: openApiOptions?.title ?? "Rads DB API",
+      version: openApiOptions?.version ?? "1.0.0",
+      ...openApiOptions?.description ? { description: openApiOptions.description } : {}
+    },
+    ...openApiOptions?.servers ? { servers: openApiOptions.servers } : {},
+    paths,
+    components: { schemas }
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rads-db",
-  "version": "3.2.21",
+  "version": "3.2.23",
   "description": "Say goodbye to boilerplate code and hello to efficient and elegant syntax.",
   "author": "",
   "license": "ISC",