feat(json): support writing long values as strings (#4008)

## Why?



## What does this PR do?



## Related issues

Closes #3997 

## AI Contribution Checklist



- [ ] Substantial AI assistance was used in this PR: `yes` / `no`
- [ ] If `yes`, I included a completed [AI Contribution
Checklist](https://github.com/apache/fory/blob/main/AI_POLICY.md#9-contributor-checklist-for-ai-assisted-prs)
in this PR description and the required `AI Usage Disclosure`.
- [ ] If `yes`, my PR description includes the required `ai_review`
summary and screenshot evidence or equivalent persisted links of the
final clean AI review results from both fresh reviewers described in
`AI_POLICY.md`, the Fory-guided reviewer and the independent general
reviewer, on the current PR diff or current HEAD after the latest code
changes.



## Does this PR introduce any user-facing change?



- [ ] Does this PR introduce any public API change?
- [ ] Does this PR introduce any binary protocol compatibility change?

## Benchmark

Author: chaokunyang

docs/json/kotlin.md

@@ -87,6 +87,12 @@ val text = json.toJson(Account(7u, "Alice"), accountType)
 val decoded = json.fromJson(text, accountType)
 ```
 
+Use `ForyJsonKotlin.builder().writeLongAsString(true)` when signed `Long` and unsigned `ULong`
+values must be emitted as quoted decimal strings. The setting also applies to their declared
+collection and map values, nullable values, Kotlin value classes backed by them, `ULongArray`, and
+the Java Long-like wrappers supported by the core JSON runtime. Readers accept both quoted and
+unquoted integer tokens.
+
 `jsonTypeRef<T>()` is a type token, not a codec lookup. Construct it once and reuse it. A Java
 `Class` or ordinary Java `TypeRef` cannot express distinctions such as `List<Account?>`, `UInt`, or
 a logical value class lowered to a primitive carrier.

docs/json/object-mapping.md

@@ -215,6 +215,7 @@ original key type. Null map keys are rejected.
 | Builder method                         | Default                                   | User-visible effect                                        |
 | -------------------------------------- | ----------------------------------------- | ---------------------------------------------------------- |
 | `writeNullFields(boolean)`             | `false`                                   | Default inclusion of null object properties                |
+| `writeLongAsString(boolean)`           | `false`                                   | Write built-in 64-bit integer values as decimal strings    |
 | `withCodegen(boolean)`                 | `true`                                    | Enable generated object codecs                             |
 | `withAsyncCompilation(boolean)`        | `true`                                    | Compile generated codecs asynchronously                    |
 | `withFieldMode(boolean)`               | `false`                                   | When true, discover fields without getters/setters         |
@@ -225,6 +226,14 @@ original key type. Null map keys are rejected.
 | `registerCodec(type, codec)`           | None                                      | Replace an eligible exact class's complete JSON codec      |
 | `registerMixin(mixinType)`             | None                                      | Apply one annotation Mixin to its exact declared target    |
 
+Enable `writeLongAsString(true)` when 64-bit integer values must pass through JavaScript without
+`Number` precision loss. The setting writes built-in `long`/`Long`, `AtomicLong`,
+`AtomicLongArray`, and `OptionalLong` values as quoted decimal strings. It also follows declared
+Long children through arrays, collections, map values, `Optional<Long>`, `AtomicReference<Long>`,
+and equivalent language-module containers. Readers accept both numeric and quoted integer tokens
+regardless of this setting. Custom codecs and occurrence-level codec or format annotations retain
+their own output shape.
+
 Concurrency-level and buffer-retention limits must be positive. The cached-field-name limit
 applies independently to each reader; zero disables this cache. It bounds only cached field names,
 not names accepted from the input. The buffer-retention setting does not limit JSON input or output

docs/json/scala.md

@@ -41,6 +41,11 @@ val person = json.fromJson(text, classOf[Person])
 ```
 
 Reuse the resulting `ForyJson` instance. It is immutable and thread-safe after construction.
+Use `ForyJsonScala.builder().writeLongAsString(true)` to emit Scala `Long` values, including
+declared collection and map values, `Option[Long]`, `Long`-backed value classes, and Java Long-like
+wrappers as quoted decimal strings. Readers accept both quoted and unquoted integer tokens.
+Use `ScalaTypeRef` when a parameterized declaration contains `Long` because normal JVM signatures
+can erase Scala value-type arguments to `Object`.
 
 ## Case classes and annotations
 

java/fory-json/src/main/java/org/apache/fory/json/ForyJsonBuilder.java

@@ -50,6 +50,7 @@
  */
 public final class ForyJsonBuilder {
   private boolean writeNullFields;
+  private boolean writeLongAsString;
   private boolean codegenEnabled = true;
   private boolean asyncCompilationEnabled = true;
   private boolean propertyDiscoveryEnabled = true;
@@ -80,6 +81,21 @@ public ForyJsonBuilder writeNullFields(boolean writeNullFields) {
     return this;
   }
 
+  /**
+   * Writes signed 64-bit integer values owned by Fory's built-in JSON codecs as quoted decimal
+   * strings. This includes {@code long}/{@link Long}, {@code AtomicLong}, {@code AtomicLongArray},
+   * {@code OptionalLong}, and generic containers whose declared value is {@code Long}. Disabled by
+   * default.
+   *
+   * <p>This setting also applies to corresponding 64-bit unsigned scalar bindings installed by a
+   * language module. Exact custom codecs and occurrence-level codec or format annotations retain
+   * ownership of their complete representation.
+   */
+  public ForyJsonBuilder writeLongAsString(boolean writeLongAsString) {
+    this.writeLongAsString = writeLongAsString;
+    return this;
+  }
+
   /**
    * Enables generated object codecs for supported classes. Enabled by default and automatically
    * disabled on Android. A GraalVM Native Image includes generated codecs for the default
@@ -297,6 +313,7 @@ JsonConfig buildConfig() {
         ModuleInstaller.install(new ArrayList<>(modules), codecRegistry, mixins);
     return new JsonConfig(
         writeNullFields,
+        writeLongAsString,
         effectiveCodegen,
         effectiveAsyncCompilation,
         propertyDiscoveryEnabled,

java/fory-json/src/main/java/org/apache/fory/json/JsonConfig.java

@@ -37,6 +37,7 @@ public final class JsonConfig {
   private static final int MAX_CACHED_FIELD_NAMES = 1 << 29;
 
   private final boolean writeNullFields;
+  private final boolean writeLongAsString;
   private final boolean codegenEnabled;
   private final boolean asyncCompilationEnabled;
   private final boolean propertyDiscoveryEnabled;
@@ -56,6 +57,7 @@ public final class JsonConfig {
 
   JsonConfig(
       boolean writeNullFields,
+      boolean writeLongAsString,
       boolean codegenEnabled,
       boolean asyncCompilationEnabled,
       boolean propertyDiscoveryEnabled,
@@ -72,6 +74,7 @@ public final class JsonConfig {
       List<String> factoryIdentities,
       JsonTypeChecker typeChecker) {
     this.writeNullFields = writeNullFields;
+    this.writeLongAsString = writeLongAsString;
     this.codegenEnabled = codegenEnabled;
     this.asyncCompilationEnabled = asyncCompilationEnabled;
     this.propertyDiscoveryEnabled = propertyDiscoveryEnabled;
@@ -97,6 +100,13 @@ public boolean writeNullFields() {
     return writeNullFields;
   }
 
+  /**
+   * Returns whether built-in signed and module-provided unsigned 64-bit values write as strings.
+   */
+  public boolean writeLongAsString() {
+    return writeLongAsString;
+  }
+
   public boolean codegenEnabled() {
     return codegenEnabled;
   }

java/fory-json/src/main/java/org/apache/fory/json/codec/ArrayCodec.java

@@ -80,6 +80,9 @@ public static <T> ArrayCodec<T> create(Class<T> arrayType, JsonTypeInfo componen
       return bind(IntArrayCodec.INSTANCE);
     } else if (componentType == long.class && componentCodec == ScalarCodecs.LongCodec.PRIMITIVE) {
       return bind(LongArrayCodec.INSTANCE);
+    } else if (componentType == long.class
+        && componentCodec == ScalarCodecs.LongAsStringCodec.PRIMITIVE) {
+      return bind(LongAsStringArrayCodec.INSTANCE);
     } else if (componentType == boolean.class
         && componentCodec == ScalarCodecs.BooleanCodec.PRIMITIVE) {
       return bind(BooleanArrayCodec.INSTANCE);
@@ -106,6 +109,12 @@ public static <T> ArrayCodec<T> create(Class<T> arrayType, JsonTypeInfo componen
           componentTypeInfo.rejectsNull()
               ? BoxedLongArrayCodec.NON_NULL
               : BoxedLongArrayCodec.INSTANCE);
+    } else if (componentType == Long.class
+        && componentCodec == ScalarCodecs.LongAsStringCodec.BOXED) {
+      return bind(
+          componentTypeInfo.rejectsNull()
+              ? BoxedLongAsStringArrayCodec.NON_NULL
+              : BoxedLongAsStringArrayCodec.INSTANCE);
     } else if (componentType == Boolean.class
         && componentCodec == ScalarCodecs.BooleanCodec.BOXED) {
       return bind(
@@ -152,7 +161,8 @@ public static <T> ArrayCodec<T> create(Class<T> arrayType, JsonTypeInfo componen
 
   /** Returns the exact unsigned primitive-array specialization for one semantic array id. */
   @Internal
-  public static <T> ArrayCodec<T> createUnsignedPrimitive(Class<T> arrayType, int typeId) {
+  public static <T> ArrayCodec<T> createUnsignedPrimitive(
+      Class<T> arrayType, int typeId, boolean writeLongAsString) {
     if (arrayType == byte[].class && typeId == Types.UINT8_ARRAY) {
       return bind(ByteArrayCodec.UNSIGNED);
     }
@@ -163,7 +173,10 @@ public static <T> ArrayCodec<T> createUnsignedPrimitive(Class<T> arrayType, int
       return bind(IntArrayCodec.UNSIGNED);
     }
     if (arrayType == long[].class && typeId == Types.UINT64_ARRAY) {
-      return bind(LongArrayCodec.UNSIGNED);
+      return bind(
+          writeLongAsString
+              ? UnsignedLongAsStringArrayCodec.INSTANCE
+              : UnsignedLongArrayCodec.INSTANCE);
     }
     throw new ForyJsonException(
         "Unsigned JSON array semantic id " + typeId + " does not match " + arrayType.getName());
@@ -389,11 +402,10 @@ int readElement(Utf8JsonReader reader) {
   // Keep the signed codec as the exact final loop owner. Routing signed long arrays through a
   // semantic element hook makes C2 inline the root and array loop into one unstable graph; the
   // unsigned codec below owns separate primitive operations so neither warmed path branches.
-  public static final class LongArrayCodec extends ArrayCodec<long[]> {
+  public static class LongArrayCodec extends ArrayCodec<long[]> {
     private static final LongArrayCodec INSTANCE = new LongArrayCodec();
-    private static final ArrayCodec<long[]> UNSIGNED = new UnsignedLongArrayCodec();
 
-    private LongArrayCodec() {
+    protected LongArrayCodec() {
       super(long.class);
     }
 
@@ -734,7 +746,44 @@ private long[] readUtf8LongTail(
     }
   }
 
-  private static final class UnsignedLongArrayCodec extends ArrayCodec<long[]> {
+  /** Exact signed long-array specialization which writes each element as a JSON string. */
+  public static final class LongAsStringArrayCodec extends LongArrayCodec {
+    private static final LongAsStringArrayCodec INSTANCE = new LongAsStringArrayCodec();
+
+    private LongAsStringArrayCodec() {}
+
+    @Override
+    public void writeString(StringJsonWriter writer, long[] value) {
+      if (value == null) {
+        writer.writeNull();
+        return;
+      }
+      writer.writeArrayStart();
+      for (int i = 0; i < value.length; i++) {
+        writer.writeComma(i);
+        writer.writeLongAsString(value[i]);
+      }
+      writer.writeArrayEnd();
+    }
+
+    @Override
+    public void writeUtf8(Utf8JsonWriter writer, long[] value) {
+      if (value == null) {
+        writer.writeNull();
+        return;
+      }
+      writer.writeArrayStart();
+      for (int i = 0; i < value.length; i++) {
+        writer.writeComma(i);
+        writer.writeLongAsString(value[i]);
+      }
+      writer.writeArrayEnd();
+    }
+  }
+
+  private static class UnsignedLongArrayCodec extends ArrayCodec<long[]> {
+    private static final UnsignedLongArrayCodec INSTANCE = new UnsignedLongArrayCodec();
+
     private UnsignedLongArrayCodec() {
       super(long.class);
     }
@@ -867,6 +916,41 @@ private long[] readUnsignedArray(JsonReader reader) {
     }
   }
 
+  private static final class UnsignedLongAsStringArrayCodec extends UnsignedLongArrayCodec {
+    private static final UnsignedLongAsStringArrayCodec INSTANCE =
+        new UnsignedLongAsStringArrayCodec();
+
+    private UnsignedLongAsStringArrayCodec() {}
+
+    @Override
+    public void writeString(StringJsonWriter writer, long[] value) {
+      if (value == null) {
+        writer.writeNull();
+        return;
+      }
+      writer.writeArrayStart();
+      for (int i = 0; i < value.length; i++) {
+        writer.writeComma(i);
+        writer.writeUnsignedLongAsString(value[i]);
+      }
+      writer.writeArrayEnd();
+    }
+
+    @Override
+    public void writeUtf8(Utf8JsonWriter writer, long[] value) {
+      if (value == null) {
+        writer.writeNull();
+        return;
+      }
+      writer.writeArrayStart();
+      for (int i = 0; i < value.length; i++) {
+        writer.writeComma(i);
+        writer.writeUnsignedLongAsString(value[i]);
+      }
+      writer.writeArrayEnd();
+    }
+  }
+
   public static final class BooleanArrayCodec extends ArrayCodec<boolean[]> {
     private static final BooleanArrayCodec INSTANCE = new BooleanArrayCodec();
     private static final int ELEMENT_BYTES = 1;
@@ -2662,12 +2746,12 @@ public Integer[] readUtf8(Utf8JsonReader reader) {
     }
   }
 
-  public static final class BoxedLongArrayCodec extends ArrayCodec<Long[]> {
+  public static class BoxedLongArrayCodec extends ArrayCodec<Long[]> {
     private static final BoxedLongArrayCodec INSTANCE = new BoxedLongArrayCodec(false);
     private static final BoxedLongArrayCodec NON_NULL = new BoxedLongArrayCodec(true);
     private final boolean rejectsNull;
 
-    private BoxedLongArrayCodec(boolean rejectsNull) {
+    protected BoxedLongArrayCodec(boolean rejectsNull) {
       super(Long.class);
       this.rejectsNull = rejectsNull;
     }
@@ -2797,6 +2881,58 @@ public Long[] readUtf8(Utf8JsonReader reader) {
     }
   }
 
+  private static final class BoxedLongAsStringArrayCodec extends BoxedLongArrayCodec {
+    private static final BoxedLongAsStringArrayCodec INSTANCE =
+        new BoxedLongAsStringArrayCodec(false);
+    private static final BoxedLongAsStringArrayCodec NON_NULL =
+        new BoxedLongAsStringArrayCodec(true);
+
+    private final boolean rejectsNull;
+
+    private BoxedLongAsStringArrayCodec(boolean rejectsNull) {
+      super(rejectsNull);
+      this.rejectsNull = rejectsNull;
+    }
+
+    @Override
+    public void writeString(StringJsonWriter writer, Long[] value) {
+      if (value == null) {
+        writer.writeNull();
+        return;
+      }
+      writer.writeArrayStart();
+      for (int i = 0; i < value.length; i++) {
+        writer.writeComma(i);
+        Long element = value[i];
+        if (element == null) {
+          writeReferenceNull(writer, rejectsNull);
+        } else {
+          writer.writeLongAsString(element);
+        }
+      }
+      writer.writeArrayEnd();
+    }
+
+    @Override
+    public void writeUtf8(Utf8JsonWriter writer, Long[] value) {
+      if (value == null) {
+        writer.writeNull();
+        return;
+      }
+      writer.writeArrayStart();
+      for (int i = 0; i < value.length; i++) {
+        writer.writeComma(i);
+        Long element = value[i];
+        if (element == null) {
+          writeReferenceNull(writer, rejectsNull);
+        } else {
+          writer.writeLongAsString(element);
+        }
+      }
+      writer.writeArrayEnd();
+    }
+  }
+
   public static final class BoxedBooleanArrayCodec extends ArrayCodec<Boolean[]> {
     private static final BoxedBooleanArrayCodec INSTANCE = new BoxedBooleanArrayCodec(false);
     private static final BoxedBooleanArrayCodec NON_NULL = new BoxedBooleanArrayCodec(true);

java/fory-json/src/main/java/org/apache/fory/json/codec/CollectionCodec.java

@@ -153,6 +153,9 @@ private static CollectionCodec<?> create(
     if (elementCodec == ScalarCodecs.LongCodec.BOXED) {
       return new LongCollectionCodec(factory, elementTypeInfo);
     }
+    if (elementCodec == ScalarCodecs.LongAsStringCodec.BOXED) {
+      return new LongAsStringCollectionCodec(factory, elementTypeInfo);
+    }
     if (elementCodec == ScalarCodecs.ShortCodec.BOXED) {
       return new ShortCollectionCodec(factory, elementTypeInfo);
     }
@@ -1942,8 +1945,8 @@ Object readUtf8Element(Utf8JsonReader reader) {
     }
   }
 
-  public static final class LongCollectionCodec extends NumberCollectionCodec {
-    private LongCollectionCodec(CollectionFactory factory, JsonTypeInfo elementTypeInfo) {
+  public static class LongCollectionCodec extends NumberCollectionCodec {
+    protected LongCollectionCodec(CollectionFactory factory, JsonTypeInfo elementTypeInfo) {
       super(factory, elementTypeInfo);
     }
 
@@ -1968,6 +1971,17 @@ Object readUtf8Element(Utf8JsonReader reader) {
     }
   }
 
+  private static final class LongAsStringCollectionCodec extends LongCollectionCodec {
+    private LongAsStringCollectionCodec(CollectionFactory factory, JsonTypeInfo elementTypeInfo) {
+      super(factory, elementTypeInfo);
+    }
+
+    @Override
+    void writeNumber(JsonWriter writer, Object value) {
+      writer.writeLongAsString((long) value);
+    }
+  }
+
   public static final class ShortCollectionCodec extends NumberCollectionCodec {
     private ShortCollectionCodec(CollectionFactory factory, JsonTypeInfo elementTypeInfo) {
       super(factory, elementTypeInfo);