Skip to main content
Version: dev

Configuration

This page explains the Fory constructor options.

Creating a Fory Instance​

Pass options directly to the constructor:

import 'package:fory/fory.dart';

// defaults — good for most single-service scenarios
final fory = Fory();

// cross-language service with schema evolution
final fory = Fory(
  compatible: true,
  maxDepth: 512,
);

Create one instance per application and reuse it; there is no benefit to creating a new Fory per request.

Options​

compatible​

Set to true when your service needs to handle payloads from code that may have a different version of the same model — for example, when you deploy services independently and cannot guarantee that both sides update at the same time.

final fory = Fory(compatible: true);

When compatible: true:

  • Adding or removing fields on one side does not break the other.
  • Peers must still use the same namespace + typeName (or numeric id) to identify types.

When compatible: false:

  • Both sides must have exactly the same schema. This is slightly faster and is fine when schemas do not change or all services deploy schema changes at the same time.

checkStructVersion​

Relevant only when compatible: false. When true, Fory validates that the schema version in the payload matches the one the receiver knows about, catching accidental schema mismatches at runtime.

final fory = Fory(
  compatible: false,
  checkStructVersion: true, // default
);

This option has no effect when compatible: true.

maxDepth​

Limits how deeply nested an object graph can be. Increase this if you have legitimately deep trees; lower it to reject unexpectedly deep payloads fast.

final fory = Fory(maxDepth: 128);

maxCollectionSize​

Maximum number of elements accepted in any single list, set, or map field. Prevents runaway memory allocation from malformed messages.

final fory = Fory(maxCollectionSize: 100000);

maxBinarySize​

Maximum number of bytes accepted for any single binary blob field.

final fory = Fory(maxBinarySize: 8 * 1024 * 1024);

Defaults​

OptionDefault
compatiblefalse
checkStructVersiontrue
maxDepth256
maxCollectionSize1 048 576
maxBinarySize64 MiB

Cross-Language Notes​

When Fory is used to communicate between services written in different languages:

  • Set compatible: true on all sides if any side needs schema evolution.
  • Use the same numeric IDs or namespace + typeName pairs on every side.
  • Match the compatible setting on both the writing and reading side — mismatching modes will fail.