@zenstackhq/server 3.1.0 → 3.2.0

package/dist/api.js

@@ -3,17 +3,156 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
 
 // src/api/rest/index.ts
 import { clone, enumerate, lowerCaseFirst, paramCase } from "@zenstackhq/common-helpers";
-import { ORMError, ORMErrorReason } from "@zenstackhq/orm";
+import { ORMError as ORMError2, ORMErrorReason } from "@zenstackhq/orm";
 import { Decimal as Decimal2 } from "decimal.js";
-import SuperJSON2 from "superjson";
+import SuperJSON3 from "superjson";
 import tsjapi from "ts-japi";
 import { match as match2 } from "ts-pattern";
 import UrlPattern from "url-pattern";
+import z2 from "zod";
+import { fromError } from "zod-validation-error/v4";
+
+// src/api/common/procedures.ts
+import { ORMError } from "@zenstackhq/orm";
+var PROCEDURE_ROUTE_PREFIXES = "$procs";
+function getProcedureDef(schema, proc) {
+  const procs = schema.procedures ?? {};
+  if (!Object.prototype.hasOwnProperty.call(procs, proc)) {
+    return void 0;
+  }
+  return procs[proc];
+}
+__name(getProcedureDef, "getProcedureDef");
+function mapProcedureArgs(procDef, payload) {
+  const params = Object.values(procDef.params ?? {});
+  if (params.length === 0) {
+    if (typeof payload === "undefined") {
+      return void 0;
+    }
+    if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+      const envelope2 = payload;
+      const argsPayload2 = Object.prototype.hasOwnProperty.call(envelope2, "args") ? envelope2.args : void 0;
+      if (typeof argsPayload2 === "undefined") {
+        return payload;
+      }
+      if (argsPayload2 && typeof argsPayload2 === "object" && !Array.isArray(argsPayload2)) {
+        if (Object.keys(argsPayload2).length === 0) {
+          return payload;
+        }
+      }
+    }
+    throw new Error("procedure does not accept arguments");
+  }
+  if (typeof payload === "undefined" && params.every((p) => p.optional)) {
+    return void 0;
+  }
+  if (typeof payload === "undefined") {
+    throw new Error("missing procedure arguments");
+  }
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("procedure payload must be an object");
+  }
+  const envelope = payload;
+  const argsPayload = Object.prototype.hasOwnProperty.call(envelope, "args") ? envelope.args : void 0;
+  if (typeof argsPayload === "undefined") {
+    if (params.every((p) => p.optional)) {
+      return payload;
+    }
+    throw new Error("missing procedure arguments");
+  }
+  if (!argsPayload || typeof argsPayload !== "object" || Array.isArray(argsPayload)) {
+    throw new Error("procedure `args` must be an object");
+  }
+  const obj = argsPayload;
+  for (const key of Object.keys(obj)) {
+    if (!params.some((p) => p.name === key)) {
+      throw new Error(`unknown procedure argument: ${key}`);
+    }
+  }
+  for (const p of params) {
+    if (!Object.prototype.hasOwnProperty.call(obj, p.name)) {
+      if (p.optional) {
+        continue;
+      }
+      throw new Error(`missing procedure argument: ${p.name}`);
+    }
+  }
+  return payload;
+}
+__name(mapProcedureArgs, "mapProcedureArgs");
+
+// src/api/common/schemas.ts
 import z from "zod";
+var loggerSchema = z.union([
+  z.enum([
+    "debug",
+    "info",
+    "warn",
+    "error"
+  ]).array(),
+  z.function()
+]);
+
+// src/api/common/utils.ts
+import SuperJSON from "superjson";
+async function processSuperJsonRequestPayload(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload) || !("meta" in payload)) {
+    return {
+      result: payload,
+      error: void 0
+    };
+  }
+  const { meta, ...rest } = payload;
+  if (meta?.serialization) {
+    try {
+      return {
+        result: SuperJSON.deserialize({
+          json: rest,
+          meta: meta.serialization
+        }),
+        error: void 0
+      };
+    } catch (err) {
+      return {
+        result: void 0,
+        error: `failed to deserialize request payload: ${err.message}`
+      };
+    }
+  }
+  return {
+    result: rest,
+    error: void 0
+  };
+}
+__name(processSuperJsonRequestPayload, "processSuperJsonRequestPayload");
+function unmarshalQ(value, meta) {
+  let parsedValue;
+  try {
+    parsedValue = JSON.parse(value);
+  } catch {
+    throw new Error('invalid "q" query parameter');
+  }
+  if (meta) {
+    let parsedMeta;
+    try {
+      parsedMeta = JSON.parse(meta);
+    } catch {
+      throw new Error('invalid "meta" query parameter');
+    }
+    if (parsedMeta.serialization) {
+      return SuperJSON.deserialize({
+        json: parsedValue,
+        meta: parsedMeta.serialization
+      });
+    }
+  }
+  return parsedValue;
+}
+__name(unmarshalQ, "unmarshalQ");
 
 // src/api/utils.ts
 import { Decimal } from "decimal.js";
-import SuperJSON from "superjson";
+import SuperJSON2 from "superjson";
 import { match } from "ts-pattern";
 import { fromError as fromError3 } from "zod-validation-error/v3";
 import { fromError as fromError4 } from "zod-validation-error/v4";
@@ -32,13 +171,13 @@ ${error}` : ""}`);
 }
 __name(log, "log");
 function registerCustomSerializers() {
-  SuperJSON.registerCustom({
+  SuperJSON2.registerCustom({
     isApplicable: /* @__PURE__ */ __name((v) => Decimal.isDecimal(v), "isApplicable"),
     serialize: /* @__PURE__ */ __name((v) => v.toJSON(), "serialize"),
     deserialize: /* @__PURE__ */ __name((v) => new Decimal(v), "deserialize")
   }, "Decimal");
   if (globalThis.Buffer) {
-    SuperJSON.registerCustom({
+    SuperJSON2.registerCustom({
       isApplicable: /* @__PURE__ */ __name((v) => Buffer.isBuffer(v), "isApplicable"),
       serialize: /* @__PURE__ */ __name((v) => v.toString("base64"), "serialize"),
       deserialize: /* @__PURE__ */ __name((v) => Buffer.from(v, "base64"), "deserialize")
@@ -170,55 +309,55 @@ var RestApiHandler = class {
   };
   filterParamPattern = new RegExp(/^filter(?<match>(\[[^[\]]+\])+)$/);
   // zod schema for payload of creating and updating a resource
-  createUpdatePayloadSchema = z.object({
-    data: z.object({
-      type: z.string(),
-      attributes: z.object({}).passthrough().optional(),
-      relationships: z.record(z.string(), z.object({
-        data: z.union([
-          z.object({
-            type: z.string(),
-            id: z.union([
-              z.string(),
-              z.number()
+  createUpdatePayloadSchema = z2.object({
+    data: z2.object({
+      type: z2.string(),
+      attributes: z2.object({}).passthrough().optional(),
+      relationships: z2.record(z2.string(), z2.object({
+        data: z2.union([
+          z2.object({
+            type: z2.string(),
+            id: z2.union([
+              z2.string(),
+              z2.number()
             ])
           }),
-          z.array(z.object({
-            type: z.string(),
-            id: z.union([
-              z.string(),
-              z.number()
+          z2.array(z2.object({
+            type: z2.string(),
+            id: z2.union([
+              z2.string(),
+              z2.number()
             ])
           }))
         ])
       })).optional()
     }),
-    meta: z.object({}).passthrough().optional()
+    meta: z2.object({}).passthrough().optional()
   }).strict();
   // zod schema for updating a single relationship
-  updateSingleRelationSchema = z.object({
-    data: z.object({
-      type: z.string(),
-      id: z.union([
-        z.string(),
-        z.number()
+  updateSingleRelationSchema = z2.object({
+    data: z2.object({
+      type: z2.string(),
+      id: z2.union([
+        z2.string(),
+        z2.number()
       ])
     }).nullable()
   });
   // zod schema for updating collection relationship
-  updateCollectionRelationSchema = z.object({
-    data: z.array(z.object({
-      type: z.string(),
-      id: z.union([
-        z.string(),
-        z.number()
+  updateCollectionRelationSchema = z2.object({
+    data: z2.array(z2.object({
+      type: z2.string(),
+      id: z2.union([
+        z2.string(),
+        z2.number()
       ])
     }))
   });
-  upsertMetaSchema = z.object({
-    meta: z.object({
-      operation: z.literal("upsert"),
-      matchFields: z.array(z.string()).min(1)
+  upsertMetaSchema = z2.object({
+    meta: z2.object({
+      operation: z2.literal("upsert"),
+      matchFields: z2.array(z2.string()).min(1)
     })
   });
   // all known types and their metadata
@@ -231,6 +370,7 @@ var RestApiHandler = class {
   externalIdMapping;
   constructor(options) {
     this.options = options;
+    this.validateOptions(options);
     this.idDivider = options.idDivider ?? DEFAULT_ID_DIVIDER;
     const segmentCharset = options.urlSegmentCharset ?? "a-zA-Z0-9-_~ %";
     this.modelNameMapping = options.modelNameMapping ?? {};
@@ -251,6 +391,25 @@ var RestApiHandler = class {
     this.buildTypeMap();
     this.buildSerializers();
   }
+  validateOptions(options) {
+    const schema = z2.strictObject({
+      schema: z2.object(),
+      log: loggerSchema.optional(),
+      endpoint: z2.string().min(1),
+      pageSize: z2.union([
+        z2.number().int().positive(),
+        z2.literal(Infinity)
+      ]).optional(),
+      idDivider: z2.string().min(1).optional(),
+      urlSegmentCharset: z2.string().min(1).optional(),
+      modelNameMapping: z2.record(z2.string(), z2.string()).optional(),
+      externalIdMapping: z2.record(z2.string(), z2.string()).optional()
+    });
+    const parseResult = schema.safeParse(options);
+    if (!parseResult.success) {
+      throw new Error(`Invalid options: ${fromError(parseResult.error)}`);
+    }
+  }
   get schema() {
     return this.options.schema;
   }
@@ -311,6 +470,16 @@ var RestApiHandler = class {
       path = "/" + path;
     }
     try {
+      if (path.startsWith("/$procs/")) {
+        const proc = path.split("/")[2];
+        return await this.processProcedureRequest({
+          client,
+          method,
+          proc,
+          query,
+          requestBody
+        });
+      }
       switch (method) {
         case "GET": {
           let match4 = this.matchUrlPattern(path, "single");
@@ -384,7 +553,7 @@ var RestApiHandler = class {
     } catch (err) {
       if (err instanceof InvalidValueError) {
         return this.makeError("invalidValue", err.message);
-      } else if (err instanceof ORMError) {
+      } else if (err instanceof ORMError2) {
         return this.handleORMError(err);
       } else {
         return this.handleGenericError(err);
@@ -395,6 +564,71 @@ var RestApiHandler = class {
     return this.makeError("unknownError", err instanceof Error ? `${err.message}
 ${err.stack}` : "Unknown error");
   }
+  async processProcedureRequest({ client, method, proc, query, requestBody }) {
+    if (!proc) {
+      return this.makeProcBadInputErrorResponse("missing procedure name");
+    }
+    const procDef = getProcedureDef(this.schema, proc);
+    if (!procDef) {
+      return this.makeProcBadInputErrorResponse(`unknown procedure: ${proc}`);
+    }
+    const isMutation = !!procDef.mutation;
+    if (isMutation) {
+      if (method !== "POST") {
+        return this.makeProcBadInputErrorResponse("invalid request method, only POST is supported");
+      }
+    } else {
+      if (method !== "GET") {
+        return this.makeProcBadInputErrorResponse("invalid request method, only GET is supported");
+      }
+    }
+    const argsPayload = method === "POST" ? requestBody : query;
+    const { result: processedArgsPayload, error } = await processSuperJsonRequestPayload(argsPayload);
+    if (error) {
+      return this.makeProcBadInputErrorResponse(error);
+    }
+    let procInput;
+    try {
+      procInput = mapProcedureArgs(procDef, processedArgsPayload);
+    } catch (err) {
+      return this.makeProcBadInputErrorResponse(err instanceof Error ? err.message : "invalid procedure arguments");
+    }
+    try {
+      log(this.log, "debug", () => `handling "$procs.${proc}" request`);
+      const clientResult = await client.$procs?.[proc](procInput);
+      const toSerialize = this.toPlainObject(clientResult);
+      const { json, meta } = SuperJSON3.serialize(toSerialize);
+      const responseBody = {
+        data: json
+      };
+      if (meta) {
+        responseBody.meta = {
+          serialization: meta
+        };
+      }
+      return {
+        status: 200,
+        body: responseBody
+      };
+    } catch (err) {
+      log(this.log, "error", `error occurred when handling "$procs.${proc}" request`, err);
+      if (err instanceof ORMError2) {
+        throw err;
+      }
+      return this.makeProcGenericErrorResponse(err);
+    }
+  }
+  makeProcBadInputErrorResponse(message) {
+    const resp = this.makeError("invalidPayload", message, 400);
+    log(this.log, "debug", () => `sending error response: ${JSON.stringify(resp)}`);
+    return resp;
+  }
+  makeProcGenericErrorResponse(err) {
+    const message = err instanceof Error ? err.message : "unknown error";
+    const resp = this.makeError("unknownError", message, 500);
+    log(this.log, "debug", () => `sending error response: ${JSON.stringify(resp)}`);
+    return resp;
+  }
   async processSingleRead(client, type, resourceId, query) {
     const typeInfo = this.getModelInfo(type);
     if (!typeInfo) {
@@ -716,7 +950,7 @@ ${err.stack}` : "Unknown error");
   processRequestBody(requestBody) {
     let body = requestBody;
     if (body.meta?.serialization) {
-      body = SuperJSON2.deserialize({
+      body = SuperJSON3.deserialize({
         json: body,
         meta: body.meta.serialization
       });
@@ -1160,7 +1394,7 @@ ${err.stack}` : "Unknown error");
     this.injectCompoundId(model, itemsWithId);
     const serialized = await serializer.serialize(itemsWithId, options);
     const plainResult = this.toPlainObject(serialized);
-    const { json, meta } = SuperJSON2.serialize(plainResult);
+    const { json, meta } = SuperJSON3.serialize(plainResult);
     const result = json;
     if (meta) {
       result.meta = {
@@ -1785,9 +2019,11 @@ ${err.stack}` : "Unknown error");
 
 // src/api/rpc/index.ts
 import { lowerCaseFirst as lowerCaseFirst2, safeJSONStringify } from "@zenstackhq/common-helpers";
-import { ORMError as ORMError2, ORMErrorReason as ORMErrorReason2 } from "@zenstackhq/orm";
-import SuperJSON3 from "superjson";
+import { ORMError as ORMError3, ORMErrorReason as ORMErrorReason2 } from "@zenstackhq/orm";
+import SuperJSON4 from "superjson";
 import { match as match3 } from "ts-pattern";
+import z3 from "zod";
+import { fromError as fromError2 } from "zod-validation-error/v4";
 registerCustomSerializers();
 var RPCApiHandler = class {
   static {
@@ -1796,6 +2032,17 @@ var RPCApiHandler = class {
   options;
   constructor(options) {
     this.options = options;
+    this.validateOptions(options);
+  }
+  validateOptions(options) {
+    const schema = z3.strictObject({
+      schema: z3.object(),
+      log: loggerSchema.optional()
+    });
+    const parseResult = schema.safeParse(options);
+    if (!parseResult.success) {
+      throw new Error(`Invalid options: ${fromError2(parseResult.error)}`);
+    }
   }
   get schema() {
     return this.options.schema;
@@ -1810,6 +2057,15 @@ var RPCApiHandler = class {
     if (parts.length !== 0 || !op || !model) {
       return this.makeBadInputErrorResponse("invalid request path");
     }
+    if (model === PROCEDURE_ROUTE_PREFIXES) {
+      return this.handleProcedureRequest({
+        client,
+        method: method.toUpperCase(),
+        proc: op,
+        query,
+        requestBody
+      });
+    }
     model = lowerCaseFirst2(model);
     method = method.toUpperCase();
     let args;
@@ -1834,11 +2090,12 @@ var RPCApiHandler = class {
       case "aggregate":
       case "groupBy":
       case "count":
+      case "exists":
         if (method !== "GET") {
           return this.makeBadInputErrorResponse("invalid request method, only GET is supported");
         }
         try {
-          args = query?.["q"] ? this.unmarshalQ(query["q"], query["meta"]) : {};
+          args = query?.["q"] ? unmarshalQ(query["q"], query["meta"]) : {};
         } catch {
           return this.makeBadInputErrorResponse('invalid "q" query parameter');
         }
@@ -1860,7 +2117,7 @@ var RPCApiHandler = class {
           return this.makeBadInputErrorResponse("invalid request method, only DELETE is supported");
         }
         try {
-          args = query?.["q"] ? this.unmarshalQ(query["q"], query["meta"]) : {};
+          args = query?.["q"] ? unmarshalQ(query["q"], query["meta"]) : {};
         } catch (err) {
           return this.makeBadInputErrorResponse(err instanceof Error ? err.message : 'invalid "q" query parameter');
         }
@@ -1882,7 +2139,7 @@ var RPCApiHandler = class {
         data: clientResult
       };
       if (clientResult) {
-        const { json, meta } = SuperJSON3.serialize(clientResult);
+        const { json, meta } = SuperJSON4.serialize(clientResult);
         responseBody = {
           data: json
         };
@@ -1900,13 +2157,75 @@ var RPCApiHandler = class {
       return response;
     } catch (err) {
       log(this.options.log, "error", `error occurred when handling "${model}.${op}" request`, err);
-      if (err instanceof ORMError2) {
+      if (err instanceof ORMError3) {
         return this.makeORMErrorResponse(err);
       } else {
         return this.makeGenericErrorResponse(err);
       }
     }
   }
+  async handleProcedureRequest({ client, method, proc, query, requestBody }) {
+    if (!proc) {
+      return this.makeBadInputErrorResponse("missing procedure name");
+    }
+    const procDef = getProcedureDef(this.options.schema, proc);
+    if (!procDef) {
+      return this.makeBadInputErrorResponse(`unknown procedure: ${proc}`);
+    }
+    const isMutation = !!procDef.mutation;
+    if (isMutation) {
+      if (method !== "POST") {
+        return this.makeBadInputErrorResponse("invalid request method, only POST is supported");
+      }
+    } else {
+      if (method !== "GET") {
+        return this.makeBadInputErrorResponse("invalid request method, only GET is supported");
+      }
+    }
+    let argsPayload = method === "POST" ? requestBody : void 0;
+    if (method === "GET") {
+      try {
+        argsPayload = query?.["q"] ? unmarshalQ(query["q"], query["meta"]) : void 0;
+      } catch (err) {
+        return this.makeBadInputErrorResponse(err instanceof Error ? err.message : 'invalid "q" query parameter');
+      }
+    }
+    const { result: processedArgsPayload, error } = await processSuperJsonRequestPayload(argsPayload);
+    if (error) {
+      return this.makeBadInputErrorResponse(error);
+    }
+    let procInput;
+    try {
+      procInput = mapProcedureArgs(procDef, processedArgsPayload);
+    } catch (err) {
+      return this.makeBadInputErrorResponse(err instanceof Error ? err.message : "invalid procedure arguments");
+    }
+    try {
+      log(this.options.log, "debug", () => `handling "$procs.${proc}" request`);
+      const clientResult = await client.$procs?.[proc](procInput);
+      const { json, meta } = SuperJSON4.serialize(clientResult);
+      const responseBody = {
+        data: json
+      };
+      if (meta) {
+        responseBody.meta = {
+          serialization: meta
+        };
+      }
+      const response = {
+        status: 200,
+        body: responseBody
+      };
+      log(this.options.log, "debug", () => `sending response for "$procs.${proc}" request: ${safeJSONStringify(response)}`);
+      return response;
+    } catch (err) {
+      log(this.options.log, "error", `error occurred when handling "$procs.${proc}" request`, err);
+      if (err instanceof ORMError3) {
+        return this.makeORMErrorResponse(err);
+      }
+      return this.makeGenericErrorResponse(err);
+    }
+  }
   isValidModel(client, model) {
     return Object.keys(client.$schema.models).some((m) => lowerCaseFirst2(m) === lowerCaseFirst2(model));
   }
@@ -1950,8 +2269,8 @@ var RPCApiHandler = class {
     }).with(ORMErrorReason2.REJECTED_BY_POLICY, () => {
       status = 403;
       error.rejectedByPolicy = true;
-      error.rejectReason = err.rejectedByPolicyReason;
       error.model = err.model;
+      error.rejectReason = err.rejectedByPolicyReason;
     }).with(ORMErrorReason2.DB_QUERY_ERROR, () => {
       status = 400;
       error.dbErrorCode = err.dbErrorCode;
@@ -1970,7 +2289,7 @@ var RPCApiHandler = class {
     const { meta, ...rest } = args ?? {};
     if (meta?.serialization) {
       try {
-        args = SuperJSON3.deserialize({
+        args = SuperJSON4.deserialize({
           json: rest,
           meta: meta.serialization
         });
@@ -1988,29 +2307,6 @@ var RPCApiHandler = class {
       error: void 0
     };
   }
-  unmarshalQ(value, meta) {
-    let parsedValue;
-    try {
-      parsedValue = JSON.parse(value);
-    } catch {
-      throw new Error('invalid "q" query parameter');
-    }
-    if (meta) {
-      let parsedMeta;
-      try {
-        parsedMeta = JSON.parse(meta);
-      } catch {
-        throw new Error('invalid "meta" query parameter');
-      }
-      if (parsedMeta.serialization) {
-        return SuperJSON3.deserialize({
-          json: parsedValue,
-          meta: parsedMeta.serialization
-        });
-      }
-    }
-    return parsedValue;
-  }
 };
 export {
   RPCApiHandler,