rads-db 3.2.20 → 3.2.22

package/dist/config.cjs

@@ -459,7 +459,8 @@ function verifyDefaultValueType(field, ctx2) {
       throw new TypeError(`Default value type is different from field type: '${type}'`);
     }
   } else {
-    if (supportedPrimitiveTypes.includes(type) && getPrimitiveTypeFromDefaultValue(defaultValue2) !== type) {
+    const normalizedType = type.startsWith("Record<") ? "object" : type;
+    if (supportedPrimitiveTypes.includes(type) && getPrimitiveTypeFromDefaultValue(defaultValue2) !== normalizedType) {
       throw new Error(`Default value type is different from field type: '${type}'`);
     }
     if (!ctx2.result[type] && ctx2.typeNodesMap[type])

package/dist/config.mjs

@@ -451,7 +451,8 @@ function verifyDefaultValueType(field, ctx2) {
       throw new TypeError(`Default value type is different from field type: '${type}'`);
     }
   } else {
-    if (supportedPrimitiveTypes.includes(type) && getPrimitiveTypeFromDefaultValue(defaultValue2) !== type) {
+    const normalizedType = type.startsWith("Record<") ? "object" : type;
+    if (supportedPrimitiveTypes.includes(type) && getPrimitiveTypeFromDefaultValue(defaultValue2) !== normalizedType) {
       throw new Error(`Default value type is different from field type: '${type}'`);
     }
     if (!ctx2.result[type] && ctx2.typeNodesMap[type])

package/features/eventSourcing.cjs

@@ -27,24 +27,74 @@ function verifyEventSourcingSetup(schema, effects, options) {
     effects[eventEntityName].push(effect);
   }
 }
+function groupEventsByAggId(docs, aggregateRelationField, eventEntityName) {
+  const docsByAggId = {};
+  const docsById = {};
+  for (const d of docs) {
+    if (!d.doc.id || docsById[d.doc.id]) continue;
+    docsById[d.doc.id] = d.doc;
+    const aggId = d.doc[aggregateRelationField].id;
+    if (!aggId) throw new Error(`Missing ${eventEntityName}.${aggregateRelationField}.id`);
+    if (d.oldDoc && aggId !== d.oldDoc[aggregateRelationField].id) {
+      throw new Error(`Field ${eventEntityName}.${aggregateRelationField}.id cannot be changed`);
+    }
+    if (!docsByAggId[aggId]) docsByAggId[aggId] = [];
+    docsByAggId[aggId].push(d.doc);
+  }
+  return {
+    docsByAggId,
+    docsById
+  };
+}
+function applyEventToAggregate(ev, aggDoc, aggId, p) {
+  const mergedDoc = (0, _radsDb.merge)(aggDoc || {
+    id: aggId
+  }, ev.change);
+  const newAggDoc = p.context.validators[p.entityName](mergedDoc);
+  if (!p.options.freezeEvent?.(ev, p.context, p.ctx)) {
+    ev.beforeChange = aggDoc;
+    const originalChange = ev.change;
+    ev.change = (0, _radsDb.diff)(newAggDoc, aggDoc);
+    handleKeepHistory(p.schema[p.entityName].keepHistoryFields, originalChange, ev);
+  }
+  if (p.ctx.skipPrecomputed) {
+    for (const field of p.schema[p.entityName].precomputedFields || []) {
+      if (p.ctx.skipPrecomputed.includes(field) && mergedDoc[field] !== void 0) {
+        newAggDoc[field] = mergedDoc[field];
+      }
+    }
+  }
+  return newAggDoc;
+}
+function buildAggregateFromEvents(events, aggId, docsById, existingAggregatesById, p) {
+  if (events[0].type !== "creation") throw new Error(`First event must have type = "creation". (type: ${events[0].type}, id: ${events[0].id})`);
+  if (events.slice(1).some(ev => ev.type === "creation")) {
+    throw new Error(`Only first event may have type = "creation"`);
+  }
+  let aggDoc;
+  for (const ev of events) {
+    const newAggDoc = applyEventToAggregate(ev, aggDoc, aggId, p);
+    if (p.options.applyEventIf && !p.options.applyEventIf(ev, p.context, p.ctx)) continue;
+    aggDoc = newAggDoc;
+    if (!p.context.options.keepNulls) (0, _radsDb.cleanEntity)(aggDoc);
+  }
+  if (!aggDoc) return null;
+  return {
+    aggDoc,
+    events,
+    updatedEvents: events.filter(ev => docsById[ev.id]),
+    oldAggDoc: existingAggregatesById[aggDoc.id]
+  };
+}
 function getEffectFor(entityName, aggregateRelationField, eventEntityName, schema, options) {
   return {
     featureName: "eventSourcing",
     async beforePut(context, docs, ctx) {
-      const docsByAggId = {};
-      const docsById = {};
-      for (const d of docs) {
-        if (!d.doc.id || docsById[d.doc.id]) continue;
-        docsById[d.doc.id] = d.doc;
-        const aggId = d.doc[aggregateRelationField].id;
-        if (!aggId) throw new Error(`Missing ${eventEntityName}.${aggregateRelationField}.id`);
-        if (d.oldDoc && aggId !== d.oldDoc[aggregateRelationField].id) {
-          throw new Error(`Field ${eventEntityName}.${aggregateRelationField}.id cannot be changed`);
-        }
-        if (!docsByAggId[aggId]) docsByAggId[aggId] = [];
-        docsByAggId[aggId].push(d.doc);
-      }
-      const existingEvents = await context.drivers[eventEntityName].getAll({
+      const {
+        docsByAggId,
+        docsById
+      } = groupEventsByAggId(docs, aggregateRelationField, eventEntityName);
+      const [existingEvents, existingAggregates] = await Promise.all([context.drivers[eventEntityName].getAll({
         where: {
           [aggregateRelationField]: {
             id_in: _lodash.default.keys(docsByAggId)
@@ -53,47 +103,24 @@ function getEffectFor(entityName, aggregateRelationField, eventEntityName, schem
             id_in: docs.map(d => d.doc.id)
           }
         }
-      }, ctx);
-      const existingEventsByAggId = _lodash.default.groupBy(existingEvents, ev => ev[aggregateRelationField].id);
-      const existingAggregates = await context.drivers[entityName].getAll({
+      }, ctx), context.drivers[entityName].getAll({
         where: {
           id_in: _lodash.default.keys(docsByAggId)
         }
-      }, ctx);
+      }, ctx)]);
+      const existingEventsByAggId = _lodash.default.groupBy(existingEvents, ev => ev[aggregateRelationField].id);
       const existingAggregatesById = _lodash.default.keyBy(existingAggregates, "id");
-      const result = [];
-      for (const aggId in docsByAggId) {
+      const processor = {
+        context,
+        entityName,
+        schema,
+        options,
+        ctx
+      };
+      const result = _lodash.default.compact(_lodash.default.keys(docsByAggId).map(aggId => {
         const events = _lodash.default.orderBy([...docsByAggId[aggId], ...(existingEventsByAggId[aggId] || [])], ["date"], "asc");
-        if (events[0].type !== "creation") throw new Error(`First event must have type = "creation". (type: ${events[0].type}, id: ${events[0].id})`);
-        if (events.slice(1).some(ev => ev.type === "creation")) {
-          throw new Error(`Only first event may have type = "creation"`);
-        }
-        let aggDoc;
-        for (const ev of events) {
-          const newAggDoc = context.validators[entityName]((0, _radsDb.merge)(aggDoc || {
-            id: aggId
-          }, ev.change));
-          if (!options.freezeEvent?.(ev, context, ctx)) {
-            ev.beforeChange = aggDoc;
-            const originalChange = ev.change;
-            ev.change = (0, _radsDb.diff)(newAggDoc, aggDoc);
-            handleKeepHistory(schema[entityName].keepHistoryFields, originalChange, ev);
-          }
-          if (options.applyEventIf && !options.applyEventIf(ev, context, ctx)) {
-            continue;
-          }
-          aggDoc = newAggDoc;
-          if (!context.options.keepNulls) (0, _radsDb.cleanEntity)(aggDoc);
-        }
-        if (aggDoc) {
-          result.push({
-            aggDoc,
-            events,
-            updatedEvents: events.filter(ev => docsById[ev.id]),
-            oldAggDoc: existingAggregatesById[aggDoc.id]
-          });
-        }
-      }
+        return buildAggregateFromEvents(events, aggId, docsById, existingAggregatesById, processor);
+      }));
       await (0, _radsDb.handlePrecomputed)(
       // @ts-expect-error TODO wrong types
       {
@@ -107,7 +134,7 @@ function getEffectFor(entityName, aggregateRelationField, eventEntityName, schem
       })), ctx);
       return result;
     },
-    async afterPut(context, docs, beforePutResult, ctx) {
+    async afterPut(context, _docs, beforePutResult, ctx) {
       const aggs = beforePutResult.map(d => d.aggDoc);
       const hookItems = beforePutResult.map(v => ({
         doc: v.aggDoc,

package/features/eventSourcing.mjs

@@ -19,70 +19,87 @@ function verifyEventSourcingSetup(schema, effects, options) {
     effects[eventEntityName].push(effect);
   }
 }
+function groupEventsByAggId(docs, aggregateRelationField, eventEntityName) {
+  const docsByAggId = {};
+  const docsById = {};
+  for (const d of docs) {
+    if (!d.doc.id || docsById[d.doc.id]) continue;
+    docsById[d.doc.id] = d.doc;
+    const aggId = d.doc[aggregateRelationField].id;
+    if (!aggId) throw new Error(`Missing ${eventEntityName}.${aggregateRelationField}.id`);
+    if (d.oldDoc && aggId !== d.oldDoc[aggregateRelationField].id) {
+      throw new Error(`Field ${eventEntityName}.${aggregateRelationField}.id cannot be changed`);
+    }
+    if (!docsByAggId[aggId]) docsByAggId[aggId] = [];
+    docsByAggId[aggId].push(d.doc);
+  }
+  return { docsByAggId, docsById };
+}
+function applyEventToAggregate(ev, aggDoc, aggId, p) {
+  const mergedDoc = merge(aggDoc || { id: aggId }, ev.change);
+  const newAggDoc = p.context.validators[p.entityName](mergedDoc);
+  if (!p.options.freezeEvent?.(ev, p.context, p.ctx)) {
+    ev.beforeChange = aggDoc;
+    const originalChange = ev.change;
+    ev.change = diff(newAggDoc, aggDoc);
+    handleKeepHistory(p.schema[p.entityName].keepHistoryFields, originalChange, ev);
+  }
+  if (p.ctx.skipPrecomputed) {
+    for (const field of p.schema[p.entityName].precomputedFields || []) {
+      if (p.ctx.skipPrecomputed.includes(field) && mergedDoc[field] !== void 0) {
+        newAggDoc[field] = mergedDoc[field];
+      }
+    }
+  }
+  return newAggDoc;
+}
+function buildAggregateFromEvents(events, aggId, docsById, existingAggregatesById, p) {
+  if (events[0].type !== "creation")
+    throw new Error(`First event must have type = "creation". (type: ${events[0].type}, id: ${events[0].id})`);
+  if (events.slice(1).some((ev) => ev.type === "creation")) {
+    throw new Error(`Only first event may have type = "creation"`);
+  }
+  let aggDoc;
+  for (const ev of events) {
+    const newAggDoc = applyEventToAggregate(ev, aggDoc, aggId, p);
+    if (p.options.applyEventIf && !p.options.applyEventIf(ev, p.context, p.ctx)) continue;
+    aggDoc = newAggDoc;
+    if (!p.context.options.keepNulls) cleanEntity(aggDoc);
+  }
+  if (!aggDoc) return null;
+  return {
+    aggDoc,
+    events,
+    updatedEvents: events.filter((ev) => docsById[ev.id]),
+    oldAggDoc: existingAggregatesById[aggDoc.id]
+  };
+}
 function getEffectFor(entityName, aggregateRelationField, eventEntityName, schema, options) {
   return {
     featureName: "eventSourcing",
     async beforePut(context, docs, ctx) {
-      const docsByAggId = {};
-      const docsById = {};
-      for (const d of docs) {
-        if (!d.doc.id || docsById[d.doc.id]) continue;
-        docsById[d.doc.id] = d.doc;
-        const aggId = d.doc[aggregateRelationField].id;
-        if (!aggId) throw new Error(`Missing ${eventEntityName}.${aggregateRelationField}.id`);
-        if (d.oldDoc && aggId !== d.oldDoc[aggregateRelationField].id) {
-          throw new Error(`Field ${eventEntityName}.${aggregateRelationField}.id cannot be changed`);
-        }
-        if (!docsByAggId[aggId]) docsByAggId[aggId] = [];
-        docsByAggId[aggId].push(d.doc);
-      }
-      const existingEvents = await context.drivers[eventEntityName].getAll(
-        {
-          where: {
-            [aggregateRelationField]: { id_in: _.keys(docsByAggId) },
-            _not: { id_in: docs.map((d) => d.doc.id) }
-          }
-        },
-        ctx
-      );
+      const { docsByAggId, docsById } = groupEventsByAggId(docs, aggregateRelationField, eventEntityName);
+      const [existingEvents, existingAggregates] = await Promise.all([
+        context.drivers[eventEntityName].getAll(
+          {
+            where: {
+              [aggregateRelationField]: { id_in: _.keys(docsByAggId) },
+              _not: { id_in: docs.map((d) => d.doc.id) }
+            }
+          },
+          ctx
+        ),
+        context.drivers[entityName].getAll({ where: { id_in: _.keys(docsByAggId) } }, ctx)
+      ]);
       const existingEventsByAggId = _.groupBy(existingEvents, (ev) => ev[aggregateRelationField].id);
-      const existingAggregates = await context.drivers[entityName].getAll(
-        { where: { id_in: _.keys(docsByAggId) } },
-        ctx
-      );
       const existingAggregatesById = _.keyBy(existingAggregates, "id");
-      const result = [];
-      for (const aggId in docsByAggId) {
-        const events = _.orderBy([...docsByAggId[aggId], ...existingEventsByAggId[aggId] || []], ["date"], "asc");
-        if (events[0].type !== "creation")
-          throw new Error(`First event must have type = "creation". (type: ${events[0].type}, id: ${events[0].id})`);
-        if (events.slice(1).some((ev) => ev.type === "creation")) {
-          throw new Error(`Only first event may have type = "creation"`);
-        }
-        let aggDoc;
-        for (const ev of events) {
-          const newAggDoc = context.validators[entityName](merge(aggDoc || { id: aggId }, ev.change));
-          if (!options.freezeEvent?.(ev, context, ctx)) {
-            ev.beforeChange = aggDoc;
-            const originalChange = ev.change;
-            ev.change = diff(newAggDoc, aggDoc);
-            handleKeepHistory(schema[entityName].keepHistoryFields, originalChange, ev);
-          }
-          if (options.applyEventIf && !options.applyEventIf(ev, context, ctx)) {
-            continue;
-          }
-          aggDoc = newAggDoc;
-          if (!context.options.keepNulls) cleanEntity(aggDoc);
-        }
-        if (aggDoc) {
-          result.push({
-            aggDoc,
-            events,
-            updatedEvents: events.filter((ev) => docsById[ev.id]),
-            oldAggDoc: existingAggregatesById[aggDoc.id]
-          });
-        }
-      }
+      const processor = { context, entityName, schema, options, ctx };
+      const result = _.compact(
+        _.keys(docsByAggId).map((aggId) => {
+          const events = _.orderBy([...docsByAggId[aggId], ...existingEventsByAggId[aggId] || []], ["date"], "asc");
+          return buildAggregateFromEvents(events, aggId, docsById, existingAggregatesById, processor);
+        })
+      );
       await handlePrecomputed(
         // @ts-expect-error TODO wrong types
         { ...context, typeName: entityName },
@@ -91,7 +108,7 @@ function getEffectFor(entityName, aggregateRelationField, eventEntityName, schem
       );
       return result;
     },
-    async afterPut(context, docs, beforePutResult, ctx) {
+    async afterPut(context, _docs, beforePutResult, ctx) {
       const aggs = beforePutResult.map((d) => d.aggDoc);
       const hookItems = beforePutResult.map((v) => ({
         doc: v.aggDoc,

package/integrations/getOpenApiSpec.cjs

@@ -0,0 +1,357 @@
+"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 fieldToOas(field, schema) {
+  const entry = schema[field.type];
+  let itemSchema;
+  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,222 @@
+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 fieldToOas(field, schema) {
+  const entry = schema[field.type];
+  let itemSchema;
+  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.20",
+  "version": "3.2.22",
   "description": "Say goodbye to boilerplate code and hello to efficient and elegant syntax.",
   "author": "",
   "license": "ISC",