@reventlessdev/reventless-local 3.0.0-alpha.216 → 3.0.0-alpha.217

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.217 (2026-08-12)
+
+### Bug Fixes
+
+* **command:** drop null arguments, and let a caller read why a payload was refused ([bfee0dc](https://github.com/ReventlessDev/reventless-core/commit/bfee0dc37755596ea8bcce1fe2cccdace7759f10))
+
+
 # 3.0.0-alpha.216 (2026-08-12)
 
 **Note:** Version bump only for package @reventlessdev/reventless-local

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-local",
-  "version": "3.0.0-alpha.216",
+  "version": "3.0.0-alpha.217",
   "description": "Local platform for Reventless (in-memory or SQLite backend, for development and testing without AWS)",
   "license": "Apache-2.0",
   "bin": {
@@ -35,18 +35,18 @@
     "sury": "11.0.0-alpha.4",
     "ws": "^8.18.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
+    "@reventlessdev/rescript-mcp-sdk": "1.0.0-alpha.21",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
     "@reventlessdev/rescript-graphql-yoga": "1.0.0-alpha.27",
-    "@reventlessdev/rescript-mcp-sdk": "1.0.0-alpha.21",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.4",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
-    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.76",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.228",
-    "@reventlessdev/reventless-postgres": "3.0.0-alpha.92",
-    "@reventlessdev/reventless-gwt": "1.0.0-alpha.175",
+    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.77",
     "@reventlessdev/reventless-infra": "3.0.0-alpha.137",
+    "@reventlessdev/reventless-gwt": "1.0.0-alpha.176",
+    "@reventlessdev/reventless-postgres": "3.0.0-alpha.93",
     "@reventlessdev/reventless-seed": "1.0.0-alpha.11",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.111"
+    "@reventlessdev/rescript-node": "2.0.0-alpha.4",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.111",
+    "@reventlessdev/reventless-core": "3.0.0-alpha.229"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/adapter/Auth/Auth_GraphqlContext.res

@@ -54,12 +54,10 @@ let extractIdentity = (ctx: JSON.t): Reventless.Identity.t =>
   | _ => Reventless.Identity.anonymous
   }
 
-// Throw a `GraphQLError` from the `graphql` package — yoga's `maskedErrors`
-// option preserves these (only opaque thrown values get masked as
-// "Unexpected error / INTERNAL_SERVER_ERROR"). Mirrors the directive-level
-// `@aws_auth` rejection that AppSync surfaces in production.
-@new @module("graphql")
-external makeGraphqlError: (string, {"extensions": {"code": string}}) => exn = "GraphQLError"
+// An unauthorized caller reads the reason: `GraphQL_CallerError` explains why a
+// resolver has to construct the error rather than throw a bare one. Mirrors the
+// directive-level `@aws_auth` rejection that AppSync surfaces in production.
+let makeGraphqlError = GraphQL_CallerError.make
 
 let unauthorizedError = (~group: string): exn =>
   makeGraphqlError(

package/src/adapter/Auth/Auth_GraphqlContext.res.mjs

@@ -44,6 +44,10 @@ function extractIdentity(ctx) {
   }
 }
 
+function makeGraphqlError(prim0, prim1) {
+  return new Graphql.GraphQLError(prim0, prim1);
+}
+
 function unauthorizedError(group) {
   return new Graphql.GraphQLError(`Unauthorized: requires group "` + group + `"`, {
     extensions: {
@@ -70,6 +74,7 @@ export {
   identityFromAuthResult,
   buildAuthContext,
   extractIdentity,
+  makeGraphqlError,
   unauthorizedError,
   requireGroup,
 }

package/src/adapter/CommandGenerator/CommandGeneratorResolvers_GraphQL.res

@@ -159,6 +159,27 @@ let deriveSdlField = (~fieldName, variantSchema: S.t<unknown>) =>
 
 let handlerRefs: dict<ref<option<CommandGenerator.commandGenerator>>> = Dict.make()
 
+// Run a command through its generator, letting a failure that describes the
+// caller's own request reach them.
+//
+// Without this every such failure arrives as "Unexpected error /
+// INTERNAL_SERVER_ERROR": yoga masks anything that is not a `GraphQLError`, so
+// a payload that does not decode and a database outage read identically from
+// outside. Only errors core marked as the caller's are unwrapped — everything
+// else propagates untouched and stays masked, which is what masking is for.
+let runCommand = async (
+  generateCommand: CommandGenerator.commandGenerator,
+  payload: CommandGenerator.payload,
+) =>
+  try await generateCommand(payload)->Effect.runPromise catch {
+  | e if ReventlessCore.Plugin_ResolverError.isCallerFault(e) =>
+    throw(
+      GraphQL_CallerError.badUserInput(
+        e->JsExn.fromException->Option.flatMap(JsExn.message)->Option.getOr("invalid command"),
+      ),
+    )
+  }
+
 // -- register (Phase 1 — synchronous, Aggregates) ----------------------------
 // Called by Plugin_Builder via aggregateMutationResolverHook before any
 // Output.apply chains fire. Registers SDL + resolver stubs in GraphQL_Server.
@@ -210,7 +231,7 @@ let register = (
               meta: {ip: [], user: identity.userId, info: `Mutation.${field}`},
               identity,
             }
-            let outcome = await generateCommand(payload)->Effect.runPromise
+            let outcome = await runCommand(generateCommand, payload)
             outcome->commandOutcomeToJson
           }
         }
@@ -273,7 +294,7 @@ let registerDcb = (
             meta: {ip: [], user: identity.userId, info: `Mutation.${fieldName}`},
             identity,
           }
-          let outcome = await generateCommand(payload)->Effect.runPromise
+          let outcome = await runCommand(generateCommand, payload)
           outcome->commandOutcomeToJson
         }
       }

package/src/adapter/CommandGenerator/CommandGeneratorResolvers_GraphQL.res.mjs

@@ -1,14 +1,18 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Effect from "effect/Effect";
 import * as Pulumi from "@pulumi/pulumi";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
 import * as Identity$Reventless from "@reventlessdev/reventless-spec/src/types/Identity.res.mjs";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 import * as Message$ReventlessCore from "@reventlessdev/reventless-core/src/Message.res.mjs";
 import * as Authorization$Reventless from "@reventlessdev/reventless-spec/src/types/Authorization.res.mjs";
 import * as CommandTopic$ReventlessCore from "@reventlessdev/reventless-core/src/components/CommandTopic/CommandTopic.res.mjs";
+import * as GraphQL_CallerError$ReventlessLocal from "../GraphQL_CallerError.res.mjs";
+import * as Plugin_ResolverError$ReventlessCore from "@reventlessdev/reventless-core/src/plugin/component/Plugin_ResolverError.res.mjs";
 import * as GraphQL_FragmentGenerator$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/GraphQL_FragmentGenerator.res.mjs";
 
 function extractIdentity(ctx) {
@@ -140,6 +144,18 @@ function deriveSdlField(fieldName, variantSchema) {
 
 let handlerRefs = {};
 
+async function runCommand(generateCommand, payload) {
+  try {
+    return await Effect.runPromise(generateCommand(payload));
+  } catch (raw_e) {
+    let e = Primitive_exceptions.internalToException(raw_e);
+    if (Plugin_ResolverError$ReventlessCore.isCallerFault(e)) {
+      throw GraphQL_CallerError$ReventlessLocal.badUserInput(Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_JsExn.fromException(e), Stdlib_JsExn.message), "invalid command"));
+    }
+    throw e;
+  }
+}
+
 function register(fields, commandSchema, commandAuthorization, server) {
   server.registerTypes([commandResultSdl]);
   let sdlFields = fields.map(field => {
@@ -187,7 +203,7 @@ function register(fields, commandSchema, commandAuthorization, server) {
         meta: payload_meta,
         identity: identity
       };
-      return CommandTopic$ReventlessCore.commandOutcomeToJson(await Effect.runPromise(generateCommand(payload)));
+      return CommandTopic$ReventlessCore.commandOutcomeToJson(await runCommand(generateCommand, payload));
     };
     resolvers[field] = resolver;
   });
@@ -231,7 +247,7 @@ function registerDcb(fieldName, commandSchema, commandAuthorization, server) {
       meta: payload_meta,
       identity: identity
     };
-    return CommandTopic$ReventlessCore.commandOutcomeToJson(await Effect.runPromise(generateCommand(payload)));
+    return CommandTopic$ReventlessCore.commandOutcomeToJson(await runCommand(generateCommand, payload));
   };
   let resolvers = {};
   resolvers[fieldName] = resolver;
@@ -290,6 +306,7 @@ export {
   variantIndexForField,
   deriveSdlField,
   handlerRefs,
+  runCommand,
   register,
   registerDcb,
   bindHandler,

package/src/adapter/GraphQL_CallerError.res

@@ -0,0 +1,19 @@
+// A failure the caller is allowed to read.
+//
+// graphql-yoga's `maskedErrors` replaces any thrown value that is not a
+// `GraphQLError` with "Unexpected error / INTERNAL_SERVER_ERROR". That is the
+// right default — an internal failure's message is not the caller's business —
+// but it also hides the failures that describe the caller's own request, which
+// are the ones they can do something about. Constructing the error through this
+// module is how a resolver says "this one is theirs to read".
+//
+// Mirrors what AppSync surfaces in production, where a resolver's thrown message
+// is returned as the field error.
+
+@new @module("graphql")
+external make: (string, {"extensions": {"code": string}}) => exn = "GraphQLError"
+
+/** A request the server understood and refused — bad input, in GraphQL's own
+    `BAD_USER_INPUT` sense. */
+let badUserInput = (message: string): exn =>
+  make(message, {"extensions": {"code": "BAD_USER_INPUT"}})

package/src/adapter/GraphQL_CallerError.res.mjs

@@ -0,0 +1,16 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Graphql from "graphql";
+
+function badUserInput(message) {
+  return new Graphql.GraphQLError(message, {
+    extensions: {
+      code: "BAD_USER_INPUT"
+    }
+  });
+}
+
+export {
+  badUserInput,
+}
+/* graphql Not a pure module */

package/tests/adapter/CommandAuthorizationTest.res

@@ -198,3 +198,89 @@ describe("CommandGeneratorResolvers_GraphQL — per-constructor authorization",
     },
   )
 })
+
+// ── Caller-fault errors reach the caller ─────────────────────────────────────
+//
+// graphql-yoga masks every thrown value that is not a `GraphQLError` as
+// "Unexpected error / INTERNAL_SERVER_ERROR". That is right for an internal
+// failure and wrong for the failures that describe the caller's own request —
+// a payload that does not decode, a caller who cannot be identified. Core marks
+// those; this is the half that acts on the mark.
+
+@get external errorExtensions: JsExn.t => option<{"code": string}> = "extensions"
+
+let failingFixture = (~namespace: string, ~failWith: unit => unit) => {
+  let server = DomainGraphQL_Server.asInterface
+  let field = `${namespace}_Add`
+  CommandGeneratorResolvers_GraphQL.register(
+    ~fields=[field],
+    ~commandSchema=commandSchema->S.castToUnknown,
+    ~commandAuthorization,
+    ~server,
+  )
+  let generateCommand: ReventlessCore.CommandGenerator.commandGenerator = _payload =>
+    Effect.promise(() => {
+      failWith()
+      Promise.resolve(ReventlessCore.CommandTopic.Accepted({msgId: "unreachable", eventCount: 0}))
+    })
+  CommandGeneratorResolvers_GraphQL.bindHandler(~field, ~generateCommand)
+  switch server.getMutationResolver(field) {
+  | Some(r) => r
+  | None => JsError.throwWithMessage("resolver not registered: " ++ field)
+  }
+}
+
+let invoke = async resolver =>
+  switch await resolver(
+    JSON.Encode.null,
+    JSON.Encode.object(Dict.fromArray([("name", JSON.Encode.string("Books"))])),
+    ctxFor(adminIdentity),
+  ) {
+  | _ => None
+  | exception e => e->JsExn.fromException
+  }
+
+describe("CommandGeneratorResolvers_GraphQL — a failure the caller may read", () => {
+  beforeEach(() => {
+    DomainGraphQL_Server.asInterface.reset()
+  })
+
+  testPromise("a caller-fault failure is rethrown as an unmasked GraphQL error", async () => {
+    let resolver = failingFixture(~namespace="Fault1", ~failWith=() =>
+      ReventlessCore.Plugin_ResolverError.throwCallerFault(
+        `Error: Couldn't decode: Expected string | undefined, received null`,
+      )
+    )
+    let caught = await invoke(resolver)
+    expect((
+      caught->Option.flatMap(JsExn.name),
+      caught->Option.flatMap(errorExtensions)->Option.map(e => e["code"]),
+    ))->toEqual((Some("GraphQLError"), Some("BAD_USER_INPUT")))
+  })
+
+  // The reason is the point: masked, the caller learns only that something
+  // went wrong on a request that is theirs to fix.
+  testPromise("and carries the reason it was given", async () => {
+    let resolver = failingFixture(~namespace="Fault2", ~failWith=() =>
+      ReventlessCore.Plugin_ResolverError.throwCallerFault(
+        "Expected string | undefined, received null",
+      )
+    )
+    let caught = await invoke(resolver)
+    expect(
+      caught
+      ->Option.flatMap(JsExn.message)
+      ->Option.mapOr(false, m => m->String.includes("received null")),
+    )->toBe(true)
+  })
+
+  // The control, and the reason the mark exists: an internal failure is not the
+  // caller's business and must keep being masked.
+  testPromise("an unmarked failure is left to be masked", async () => {
+    let resolver = failingFixture(~namespace="Fault3", ~failWith=() =>
+      JsError.throwWithMessage("connection to the event store was reset")
+    )
+    let caught = await invoke(resolver)
+    expect(caught->Option.flatMap(JsExn.name))->not_->toEqual(Some("GraphQLError"))
+  })
+})

package/tests/adapter/CommandAuthorizationTest.res.mjs

@@ -2,11 +2,14 @@
 
 import * as S from "sury/src/S.res.mjs";
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Effect from "effect/Effect";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Identity$Reventless from "@reventlessdev/reventless-spec/src/types/Identity.res.mjs";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 import * as TestRunner$ReventlessLocal from "../../src/test/TestRunner.res.mjs";
+import * as Plugin_ResolverError$ReventlessCore from "@reventlessdev/reventless-core/src/plugin/component/Plugin_ResolverError.res.mjs";
 import * as DomainGraphQL_Server$ReventlessLocal from "../../src/adapter/DomainGraphQL_Server.res.mjs";
 import * as CommandGeneratorResolvers_GraphQL$ReventlessLocal from "../../src/adapter/CommandGenerator/CommandGeneratorResolvers_GraphQL.res.mjs";
 
@@ -176,6 +179,63 @@ globalThis.describe("CommandGeneratorResolvers_GraphQL — per-constructor autho
   });
 });
 
+function failingFixture(namespace, failWith) {
+  let field = namespace + `_Add`;
+  CommandGeneratorResolvers_GraphQL$ReventlessLocal.register([field], commandSchema, commandAuthorization, DomainGraphQL_Server$ReventlessLocal.asInterface);
+  let generateCommand = _payload => Effect.promise(() => {
+    failWith();
+    return Promise.resolve({
+      TAG: "Accepted",
+      msgId: "unreachable",
+      eventCount: 0
+    });
+  });
+  CommandGeneratorResolvers_GraphQL$ReventlessLocal.bindHandler(field, generateCommand);
+  let r = DomainGraphQL_Server$ReventlessLocal.asInterface.getMutationResolver(field);
+  if (r !== undefined) {
+    return r;
+  } else {
+    return Stdlib_JsError.throwWithMessage("resolver not registered: " + field);
+  }
+}
+
+async function invoke(resolver) {
+  try {
+    await resolver(null, Object.fromEntries([[
+        "name",
+        "Books"
+      ]]), ctxFor(adminIdentity));
+    return;
+  } catch (raw_e) {
+    return Stdlib_JsExn.fromException(Primitive_exceptions.internalToException(raw_e));
+  }
+}
+
+globalThis.describe("CommandGeneratorResolvers_GraphQL — a failure the caller may read", () => {
+  globalThis.beforeEach(() => DomainGraphQL_Server$ReventlessLocal.asInterface.reset());
+  globalThis.test("a caller-fault failure is rethrown as an unmasked GraphQL error", async () => {
+    let resolver = failingFixture("Fault1", () => Plugin_ResolverError$ReventlessCore.throwCallerFault(`Error: Couldn't decode: Expected string | undefined, received null`));
+    let caught = await invoke(resolver);
+    globalThis.expect([
+      Stdlib_Option.flatMap(caught, Stdlib_JsExn.name),
+      Stdlib_Option.map(Stdlib_Option.flatMap(caught, prim => prim.extensions), e => e.code)
+    ]).toEqual([
+      "GraphQLError",
+      "BAD_USER_INPUT"
+    ]);
+  });
+  globalThis.test("and carries the reason it was given", async () => {
+    let resolver = failingFixture("Fault2", () => Plugin_ResolverError$ReventlessCore.throwCallerFault("Expected string | undefined, received null"));
+    let caught = await invoke(resolver);
+    globalThis.expect(Stdlib_Option.mapOr(Stdlib_Option.flatMap(caught, Stdlib_JsExn.message), false, m => m.includes("received null"))).toBe(true);
+  });
+  globalThis.test("an unmarked failure is left to be masked", async () => {
+    let resolver = failingFixture("Fault3", () => Stdlib_JsError.throwWithMessage("connection to the event store was reset"));
+    let caught = await invoke(resolver);
+    globalThis.expect(Stdlib_Option.flatMap(caught, Stdlib_JsExn.name)).not.toEqual("GraphQLError");
+  });
+});
+
 export {
   commandSchema,
   commandAuthorization,
@@ -186,5 +246,7 @@ export {
   getTypename,
   getErrorCode,
   buildFixture,
+  failingFixture,
+  invoke,
 }
 /*  Not a pure module */