Skip to main content
Version: 0.17

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 (default):

  • Both sides must have exactly the same schema. This is slightly faster and is fine when you deploy Dart-only services or always update all sides together.

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.