From 9b0a14cd177d187c8997ba1d7b0ddd71329a5c0a Mon Sep 17 00:00:00 2001 From: Giulio Canti Date: Sun, 16 Mar 2025 18:25:39 +0100 Subject: [PATCH 1/3] Add "Troubleshooting" page --- content/astro.config.ts | 5 ++ .../content/docs/docs/troubleshooting/v3.mdx | 65 +++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 content/src/content/docs/docs/troubleshooting/v3.mdx diff --git a/content/astro.config.ts b/content/astro.config.ts index e9a7eb3a2..751d5d523 100644 --- a/content/astro.config.ts +++ b/content/astro.config.ts @@ -319,6 +319,11 @@ export default defineConfig({ label: "Additional Resources", autogenerate: { directory: "docs/additional-resources" }, collapsed: false + }, + { + label: "Troubleshooting", + autogenerate: { directory: "docs/troubleshooting" }, + collapsed: false } ] }) diff --git a/content/src/content/docs/docs/troubleshooting/v3.mdx b/content/src/content/docs/docs/troubleshooting/v3.mdx new file mode 100644 index 000000000..0aeada57d --- /dev/null +++ b/content/src/content/docs/docs/troubleshooting/v3.mdx @@ -0,0 +1,65 @@ +--- +title: Effect (v3) +description: Troubleshooting guide for Effect errors (v3). +sidebar: + order: 1 +--- + +If you get stuck, please try discussing the issue on the Effect [Discord](https://discord.gg/effect-ts) or posting a question to [Stackoverflow](https://stackoverflow.com/questions/tagged/effect-ts). +If you've found a bug, or Effect can't meet your needs, please try [raising an issue](https://github.com/Effect-TS/effect/issues). + +## JSONSchema + +### JSONSchema: Missing jsonSchema annotation + +This error occurs when attempting to generate a JSON Schema for a type that has no direct representation in JSON Schema, such as `bigint`. + +To resolve this, add a `jsonSchema` annotation to specify how the type should be represented. + +For refined schemas, ensure that each refinement includes a `jsonSchema` annotation that describes its constraints. + +For more details, see [Customizing JSON Schema Generation](/docs/schema/json-schema/#customizing-json-schema-generation). + +### JSONSchema: Missing identifier annotation for recursive schemas + +This error occurs when generating a JSON Schema for a recursive or mutually recursive schema that lacks an `identifier` annotation. + +Recursive schemas need a unique `identifier` annotation to ensure correct references in the generated JSON Schema. Without it, the schema generator cannot resolve the self-referencing structure. + +To resolve this, ensure that recursive schemas include an `identifier` annotation. + +For more details, see [Recursive and Mutually Recursive Schemas](/docs/schema/json-schema/#recursive-and-mutually-recursive-schemas). + +### JSONSchema: Unsupported Post Rest Elements + +This error occurs when generating a JSON Schema for a tuple that includes **post-rest elements**, elements appearing after a rest parameter. +JSON Schema does not support this structure. + +**Example** + +```ts twoslash +import { Schema } from "effect" + +// Element after a rest parameter ───┐ +// Rest Parameter ────────────────┐ | +// ▼ ▼ +const schema = Schema.Tuple([], Schema.Number, Schema.String) +``` + +### JSONSchema: Unsupported Key + +This error occurs when attempting to generate a JSON Schema for a structure that includes unsupported key types, such as `symbol`. +JSON Schema only supports string-based keys. + +**Example** + +```ts twoslash +import { Schema } from "effect" + +// Schema with a symbol key (not allowed in JSON Schema) +const schema = Schema.Struct({ + [Symbol.for("my-symbol")]: Schema.String +}) +``` + +as there is no way to represent this in JSON Schema. From 0e6265d2579b8fb7a0c76c76f54fa76aa42a8dec Mon Sep 17 00:00:00 2001 From: Giulio Canti Date: Mon, 17 Mar 2025 07:34:43 +0100 Subject: [PATCH 2/3] Add troubleshooting guidance for missing arbitrary annotation in schemas --- content/src/content/docs/docs/troubleshooting/v3.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/content/src/content/docs/docs/troubleshooting/v3.mdx b/content/src/content/docs/docs/troubleshooting/v3.mdx index 0aeada57d..755240a36 100644 --- a/content/src/content/docs/docs/troubleshooting/v3.mdx +++ b/content/src/content/docs/docs/troubleshooting/v3.mdx @@ -8,6 +8,17 @@ sidebar: If you get stuck, please try discussing the issue on the Effect [Discord](https://discord.gg/effect-ts) or posting a question to [Stackoverflow](https://stackoverflow.com/questions/tagged/effect-ts). If you've found a bug, or Effect can't meet your needs, please try [raising an issue](https://github.com/Effect-TS/effect/issues). +## Arbitrary + +### Arbitrary: Missing arbitrary annotation + +This error occurs when trying to generate an `Arbitrary` instance for a schema that lacks a predefined way to generate sample values. +This commonly happens when the schema defines a custom type that the engine does not recognize. + +To resolve this, add an `arbitrary` annotation that defines how to generate random instances of the custom type. + +For more details, see [Customizing Arbitrary Data Generation](/docs/schema/arbitrary/#customizing-arbitrary-data-generation). + ## JSONSchema ### JSONSchema: Missing jsonSchema annotation From 27c4788190770e6d8805b41536c3ad09cb112ab8 Mon Sep 17 00:00:00 2001 From: Giulio Canti Date: Mon, 17 Mar 2025 13:09:49 +0100 Subject: [PATCH 3/3] Add troubleshooting guidance for missing pretty annotation in schemas --- content/src/content/docs/docs/troubleshooting/v3.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/content/src/content/docs/docs/troubleshooting/v3.mdx b/content/src/content/docs/docs/troubleshooting/v3.mdx index 755240a36..e925f7e8e 100644 --- a/content/src/content/docs/docs/troubleshooting/v3.mdx +++ b/content/src/content/docs/docs/troubleshooting/v3.mdx @@ -74,3 +74,14 @@ const schema = Schema.Struct({ ``` as there is no way to represent this in JSON Schema. + +## Pretty + +### Pretty: Missing pretty annotation + +This error occurs when trying to generate a `Pretty` instance for a schema that lacks a predefined way to compare values. +This commonly happens when the schema defines a custom type that the engine does not recognize. + +To resolve this, add a `pretty` annotation that defines how to compare the custom type. + +For more details, see [Customizing Pretty Printing Generation](/docs/schema/pretty/#customizing-pretty-printer-generation).