@model-ts/graphql 7.2.0 → 7.4.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @model-ts/graphql
 
+## 7.4.0
+
+### Minor Changes
+
+- 6032bfa: Let the JSON scalar declare `@specifiedBy`. `jsonScalar({ specifiedByURL, description })` is exported and returns the built-in JSON scalar with that metadata. Registering `"JSON"` with an annotated `JSONValue`, as in `GraphQL.scalar("JSON", JSONValue.annotate({ specifiedByURL }))`, now keeps the built-in JSON parsing (enum literals rejected at any depth, the ECMA-404 description by default) and takes the annotations' metadata. `Register` infers a schema of unknown values, such as `JSONValue`, as a scalar.
+
+## 7.3.0
+
+### Minor Changes
+
+- ce187d1: Add `where` to models, unions and `DynamoDB`: a pipe step that keeps a loaded item only when a predicate holds. After `load`, a rejected item fails with `ItemNotFoundError` for its key; after `loadOption` or any read of an `Option`, it becomes `Option.none()`.
+
+  Add `publicMessages` to `withErrorPolicy`: a public error with a fixed message reaches clients as only that message and its code, without its own message or declared fields.
+
 ## 7.2.0
 
 ## 7.1.0

package/README.md

@@ -874,6 +874,27 @@ valid Date or parseable date string and serializes to ISO.
 `graphql-type-json` convention. Literal JSON rejects unquoted enum values. For
 stricter validation, use `Schema.Json.annotate({ graphqlType: "JSON" })`.
 
+To give the JSON scalar a `@specifiedBy` URL or its own description, register
+it with an annotated `JSONValue`. The builder keeps the built-in JSON parsing
+and takes `specifiedByURL` and `description` from the annotations:
+
+```ts
+import { JSONValue } from "@model-ts/graphql"
+import { GraphQL, type Register } from "../api/graphql.ts"
+
+const specifiedByURL =
+  "https://ecma-international.org/wp-content/uploads/ECMA-404_2nd_edition_december_2017.pdf"
+const AnnotatedJSON = JSONValue.annotate({ specifiedByURL })
+declare module "../api/graphql.ts" {
+  interface Types extends Register<typeof AnnotatedJSON, "JSON"> {}
+}
+export const JSONType = GraphQL.scalar("JSON", AnnotatedJSON)
+```
+
+The schema then prints `scalar JSON @specifiedBy(url: "...")`. To set the
+metadata on the scalar itself, pass `jsonScalar({ specifiedByURL, description })`
+as the third argument; it has the same parsing as the built-in scalar.
+
 Custom scalars pair a registered name with a Schema codec:
 
 `examples/custom-scalar.ts`
@@ -1057,6 +1078,7 @@ Choose the public error code exposed to clients:
 `examples/error-policy.ts`
 
 ```ts
+import { ItemNotFoundError } from "@model-ts/dynamodb"
 import { createBuilder, ErrorReporter } from "@model-ts/graphql"
 import { Cause, Effect, Layer, Schema } from "effect"
 import type { AppContext, Types } from "../api/graphql.ts"
@@ -1065,8 +1087,12 @@ class AccessDenied extends Schema.TaggedError<AccessDenied>()("AccessDenied", {
   message: Schema.String,
 }) {}
 export const GraphQL = createBuilder<Types, AppContext>().withErrorPolicy({
-  public: [AccessDenied],
-  publicCodes: { AccessDenied: "ACCESS_DENIED" },
+  public: [AccessDenied, ItemNotFoundError],
+  publicCodes: {
+    AccessDenied: "ACCESS_DENIED",
+    ItemNotFoundError: "NOT_FOUND",
+  },
+  publicMessages: { ItemNotFoundError: "Not found" },
 })
 export const Reporting = Layer.succeed(ErrorReporter, {
   report: ({ cause, coordinate, phase }) =>
@@ -1087,6 +1113,14 @@ arbitrary thrown exception does not make it public. This policy also applies to
 custom scalar callbacks and abstract-type resolution. Ordinary graphql-js
 document diagnostics remain available to clients.
 
+Some errors are safe to report but carry fields that are not, such as the
+storage key of an `ItemNotFoundError`. Give their tag a fixed message in
+`publicMessages`: clients then get only that message and the error's code, here
+`{ message: "Not found", extensions: { code: "NOT_FOUND" } }`, and never the
+error's own message or fields. The keys must be tags of the `public` errors. A
+field that lists the error in its `errors` union still returns it as a union
+member with its declared fields.
+
 Provide `Reporting` alongside the application's service layers, for example with
 `Layer.mergeAll(Sandbox.layerMemory(), Reporting)`. The optional `ErrorReporter`
 receives the original Effect cause, field coordinate, and phase for masked
@@ -1261,6 +1295,7 @@ functions such as `executor` are separate exports, not builder methods.
 | `ExecutionResult`, `FormattedExecutionResult`                 | Direct graphql-js results and formatted executor results          |
 | `ErrorReporter`                                               | Optional service for masked-failure telemetry                     |
 | `ID`, `DateTime`, `JSONValue`                                 | Built-in input schemas                                            |
+| `jsonScalar({ specifiedByURL?, description? })`               | The built-in JSON scalar, with its own metadata                   |
 | `id`, `input`, `defaulted`                                    | Package-level schema annotation helpers                           |
 | `Connection`, `Edge`, `PageInfo`, `ConnectionArgs`            | Structural pagination types                                       |
 | `@model-ts/graphql/Testing`                                   | Test clients, the graphql tag, and normalized snapshots           |