colinhacks · October 30, 2025 20:02 · Apr 30, 2024 · Apr 30, 2024 · Apr 30, 2024
diff --git a/cyclical_data.md b/cyclical_data.md
@@ -1,4 +1,4 @@
-> Adapted from [this recommendation](https://github.com/colinhacks/zod/pull/3447) by @jandockx
+> Adapted from [this recommendation](https://github.com/colinhacks/zod/pull/3447) by [@jandockx](https://github.com/jandockx)
 
 ### Cyclical objects
 

diff --git a/cyclical_data.md b/cyclical_data.md
@@ -1,3 +1,5 @@
+> Adapted from [this recommendation](https://github.com/colinhacks/zod/pull/3447) by @jandockx
+
 ### Cyclical objects
 
 Despite supporting recursive schemas, passing cyclical data into Zod will cause an infinite loop in some cases.

diff --git a/cyclical_data.md b/cyclical_data.md
@@ -0,0 +1,46 @@
+### Cyclical objects
+
+Despite supporting recursive schemas, passing cyclical data into Zod will cause an infinite loop in some cases.
+
+You can protect against cyclical objects starting an infinite loop (at a performance cost) with the following approach
+(using the above `jsonSchema` as an example):
+
+```ts
+function isCircular(v: unknown, visited?: Set<unknown>): boolean {
+  if (v === null || typeof v !== 'object') {
+    return false;
+  }
+
+  if (visited?.has(v)) {
+    return true;
+  }
+
+  const actualVisited = visited ?? new Set<unknown>();
+  actualVisited.add(v);
+
+  if (Array.isArray(v)) {
+    return v.some(av => isCircular(av, actualVisited));
+  }
+
+  return Object.values(v).some(ov => isCircular(ov, actualVisited));
+}
+
+const NotCircular = z.unknown().superRefine((val, ctx) => {
+  if (isCircular(val)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'values cannot be circular data structures',
+      fatal: true
+    });
+
+    return z.NEVER;
+  }
+})
+
+const acircularJSONSchema = NotCircular.pipe(jsonSchema);
+
+acircularJSONSchema.parse(data);
+```
+
+When `NotCircular` fails, `pipe` will not pass the value into the next schema for evaluation, preventing the infinite
+loop.