[JavaScript] Add ForyField decorator/config for field metadata

[chaokunyang]

Feature Request

Create a ForyField decorator and configuration option for JavaScript/TypeScript to provide field-level metadata for performance and space optimization during xlang serialization.

Is your feature request related to a problem? Please describe

Currently, Fory's JavaScript xlang serialization treats all object fields uniformly:

1. Null checks are always performed - Even for fields that are never null/undefined, Fory writes a null/ref flag (1 byte per field)
2. Reference tracking is always applied (when enabled globally) - Even for fields that won't be shared/cyclic, objects are tracked with hash lookup cost
3. Field names use meta string encoding - In schema evolution mode, field names are encoded using meta string compression, but for fields with long names, this still takes space

These defaults ensure correctness but introduce unnecessary overhead when the developer has more specific knowledge about their data model.

Describe the solution you'd like

Option 1: TypeScript Decorators (Stage 3)

import { ForyClass, ForyField } from '@anthropic/fory';

@ForyClass()
class Foo {
  // Field f1: non-nullable (default), no ref tracking (default)
  // Tag ID 0 provides compact encoding in schema evolution mode
  @ForyField({ id: 0 })
  f1: string;
  
  // Field f2: non-nullable (default), no ref tracking (default)
  @ForyField({ id: 1 })
  f2: Bar;
  
  // Field f3: nullable field that may contain null values
  @ForyField({ id: 2, nullable: true })
  f3: string | null;
  
  // Field parent: shared reference that needs tracking (e.g., for circular refs)
  @ForyField({ id: 3, ref: true, nullable: true })
  parent: Node | null;
  
  // Field with long name: tag ID provides significant space savings
  @ForyField({ id: 4 })
  veryLongFieldNameThatWouldTakeManyBytes: string;
  
  // Explicit opt-out: use field name encoding but get nullable optimization
  @ForyField({ id: -1, nullable: true })
  optionalField: string | null;
}

Option 2: Schema Configuration (No Decorators)

For environments without decorator support:

import { Fory, Type } from '@anthropic/fory';

const fory = new Fory();

// Define type with field metadata
fory.registerType({
  name: 'Foo',
  fields: {
    f1: { type: Type.String, id: 0 },
    f2: { type: Type.Object, id: 1, typeName: 'Bar' },
    f3: { type: Type.String, id: 2, nullable: true },
    parent: { type: Type.Object, id: 3, typeName: 'Node', ref: true, nullable: true },
    veryLongFieldNameThatWouldTakeManyBytes: { type: Type.String, id: 4 },
    optionalField: { type: Type.String, id: -1, nullable: true },
  },
});

// Usage
const foo = { f1: 'hello', f2: bar, f3: null, ... };
const bytes = fory.serialize(foo, 'Foo');

Option 3: Class with Static Schema

import { ForySerializable } from '@anthropic/fory';

class Foo implements ForySerializable {
  f1: string;
  f2: Bar;
  f3: string | null;
  parent: Node | null;
  
  static forySchema = {
    f1: { id: 0 },
    f2: { id: 1 },
    f3: { id: 2, nullable: true },
    parent: { id: 3, ref: true, nullable: true },
    veryLongFieldNameThatWouldTakeManyBytes: { id: 4 },
    optionalField: { id: -1, nullable: true },
  };
}

ForyField Configuration

interface ForyFieldConfig {
  /**
   * Field tag ID for schema evolution mode (REQUIRED).
   * - When >= 0: Uses numeric ID instead of field name for compact encoding
   * - When -1: Explicitly opt-out, use field name with meta string encoding
   * Must be unique within the class (except -1) and stable across versions.
   */
  id: number;
  
  /**
   * Whether this field can be null/undefined.
   * When false (default), Fory skips writing the null flag (saves 1 byte).
   * When true, Fory writes null flag for nullable fields.
   * Default: false (aligned with xlang protocol defaults)
   */
  nullable?: boolean;
  
  /**
   * Whether to track references for this field.
   * When false (default):
   * - Avoids adding the object to reference tracking (saves hash overhead)
   * - Skips writing ref tracking flag
   * When true, enables reference tracking for shared/circular references.
   * Default: false (aligned with xlang protocol defaults)
   */
  ref?: boolean;
}

Design Decision: Required id

The id property is required:

• id: 0 to id: N: Use tag ID encoding (compact)
• id: -1: Explicit opt-out, use field name encoding

Rationale:

1. Explicit control: Using ForyField means opting into explicit control
2. Runtime validation: Can check for duplicate IDs during registration
3. Proven pattern: Similar to protobuf field numbers

Optimization Details

1. nullable: false (Default) Optimization

When nullable: false (default):

• Skip writing the null flag entirely (1 byte saved per field)
• Directly serialize the field value
• Throw error if field value is null or undefined at runtime

2. ref: false (Default) Optimization

When ref: false (default):

• Skip reference tracking Map operations
• Skip ref flag when combined with nullable: false

3. Tag ID Optimization

When id >= 0:

• Field name encoded as varint instead of meta string
• Significant space savings for long field names

Space savings:

Field Name	Meta String (approx)	Tag ID
f1	~2 bytes	1 byte
userName	~6 bytes	1 byte
transactionId	~10 bytes	1 byte

Implementation Notes

1. Decorator Implementation:

   // fory/decorators.ts
   export function ForyField(config: ForyFieldConfig): PropertyDecorator {
     return (target, propertyKey) => {
       const metadata = Reflect.getMetadata('fory:fields', target) || {};
       metadata[propertyKey] = config;
       Reflect.defineMetadata('fory:fields', metadata, target);
     };
   }

2. Schema-based Registration:

   // fory/schema.ts
   class Fory {
     registerType(schema: TypeSchema): void {
       // Validate field IDs are unique
       // Store schema for serialization
     }
     
     serialize(obj: any, typeName: string): Uint8Array {
       const schema = this.schemas.get(typeName);
       // Use schema.fields for optimized serialization
     }
   }

3. Validation:

   • Throw error if duplicate tag IDs (>= 0) in same type
   • Throw error if id < -1
   • Throw error if nullable: false but field is null/undefined

4. TypeScript Type Safety:

   // Type helper for nullable fields
   type NullableField<T> = T | null | undefined;
   
   // Enforce nullable: true for nullable types (via ESLint plugin or similar)

Performance Impact

For an object with 10 fields using default settings (nullable: false, ref: false):

• Space savings: ~20 bytes per object (null + ref flags)
• CPU savings: 10 fewer Map operations per serialization

Additional context

This is the JavaScript/TypeScript equivalent of Java's @ForyField annotation. See Java issue #3000 for the original design discussion.

Protocol spec: https://fory.apache.org/docs/specification/fory_xlang_serialization_spec

[theharsh999]

Hi @chaokunyang 👋
I’d like to work on this feature.

My proposed approach:

1. Start with schema-based configuration (no decorators)
2. Add support for field-level options: id, nullable, ref
3. Keep defaults backward-compatible
4. Add validation for duplicate IDs and invalid configs

Before starting implementation, I’d like to confirm:

• Is schema-based approach preferred first over decorators?
• Is making id mandatory acceptable?
• Should this be implemented only for xlang mode initially?

Once confirmed, I can submit a small PoC PR.

[chaokunyang]

Hi @theharsh999 , thanks for contributing to Apache Fory. I think we can starts from schema-based approach. It's the approach we used currently

[theharsh999]

Thanks for the confirmation!
I’ll start with the schema-based approach and prepare a small, incremental PR focused on field-level options.
I’ll keep it backward-compatible and share a PoC soon.