decodeSync

decodeSync is a synchronous decoder.

On decode failure, it throws a native JavaScript Error. The human-readable message is on error.message, and the structured issue tree is on error.cause.

decodeSync is the typed-input variant of decodeUnknownSync, meaning it accepts the schema’s Encoded type as input instead of unknown, so TypeScript enforces the correct input shape at compile time.

The Encoded type is the shape of the data before decoding. For example, consider a simple schema like Schema.String. A string goes in, a string comes out. Both the Encoded type and the Type (the decoded type) are strings. Now consider Schema.NumberFromString. This is a transformation schema. A string goes in (like "42"), and a number comes out (like 42). The Encoded type is string and the Type is number.

1
import { Schema, SchemaIssue } from "effect";
2

3
const schema = Schema.Struct({
4
  name: Schema.String,
5
  age: Schema.NumberFromString, // Encoded: string, Decoded: number
6
});
7

8
const decode = Schema.decodeSync(schema);
9

10
// Happy path
11
const decoded = decode({ name: "Alice", age: "30" });
12
console.log("Decoded Value:", decoded);
13

14
// Error path
15
try {
16
  // age should be string in encoded input
17
  decode({ name: "Alice", age: 30 } as any);
18
} catch (error) {
19
  if (error instanceof Error) {
20
    console.log("Error Message:", error.message);
21

22
    if (SchemaIssue.isIssue(error.cause)) {
23
      console.log("Issue Tree:", error.cause);
24
    }
25
  }
26
}

In the example above, age uses Schema.NumberFromString, so its Encoded input type is string. I intentionally passed a number (30) and used as any to bypass TypeScript so I could demonstrate the runtime error path.

Use decodeSync when you have data that you know matches the encoded shape. For example, you store data in localStorage as { price: "19.99", quantity: "3" }. When you read it back, you know the shape is all strings. You use decodeSync to transform them into numbers.

Difference between decodeUnknownSync and decodeSync

decodeUnknownSync accepts unknown input, while decodeSync accepts the schema’s Encoded input type, so TypeScript can catch shape mismatches before runtime.