feat(firestore): add public type guards for FieldValue sentinels

[kyungseopk1m]

Summary

Adds five public static type guards on FieldValue so users can detect sentinel values without relying on internal class names like NumericIncrementTransform.

Addresses firebase/firebase-admin-node#2957 (external contribution invited by @ehsannas).

• FieldValue.isServerTimestamp(value)
• FieldValue.isIncrement(value)
• FieldValue.isDecrement(value) — strict subset of isIncrement, true only when the operand is negative
• FieldValue.isArrayUnion(value)
• FieldValue.isArrayRemove(value)

Each guard is a TypeScript type predicate returning value is FieldValue.

Design notes

• Shape matches the "option 1" suggestion in [FR] Public API to Detect FieldValue.increment() firebase/firebase-admin-node#2957.
• isDecrement is documented as a strict subset of isIncrement (same underlying NumericIncrementTransform, narrowed by a negative operand). An alternative "partition" design (isIncrement = positive, isDecrement = negative, zero = neither) was considered; the subset design was chosen so isIncrement consistently behaves as a type detector for any increment sentinel. Happy to flip this if you prefer the partition semantics.
• Increment/decrement amount accessors are deliberately out of scope here — the original issue raised the question but did not commit to an answer. Happy to follow up in a separate PR if wanted.
• Uses instanceof against existing internal transform classes — no new runtime surface, no changes to proto serialization, transforms, or validation paths.

Testing

• New unit coverage in handwritten/firestore/dev/test/field-value.ts for all five guards: match / non-match / primitive / delete-sentinel / cross-sentinel cases, plus explicit isDecrement ⊂ isIncrement assertion.
• mocha build/test/field-value.js → 41 passing.
• Full unit suite (mocha build/test) → 1084 passing, 47 pending (no regressions).

[gemini-code-assist]

Code Review

This pull request introduces several static type guard methods to the FieldValue class—specifically isServerTimestamp, isIncrement, isDecrement, isArrayUnion, and isArrayRemove—to facilitate the identification of sentinel values. The changes include the necessary implementation logic, a private helper for decrement detection, comprehensive unit tests, and updated public type definitions. The feedback suggests adding an isDelete type guard for the delete sentinel to maintain API completeness and consistency across the library.

[gemini-code-assist]

For completeness and API consistency, consider adding a type guard for the delete sentinel as well. Since FieldValue.delete() is a core sentinel value alongside the others introduced here, providing isDelete() would ensure full coverage of the public FieldValue factory methods.

  static isArrayRemove(value: unknown): value is FieldValue {
    return value instanceof ArrayRemoveTransform;
  }

  /**
   * Returns `true` if the provided value is a sentinel returned by
   * {@link FieldValue.delete}.
   *
   * @param value The value to check.
   * @returns `true` if `value` is a delete sentinel.
   *
   * @example
   * ```
   * Firestore.FieldValue.isDelete(Firestore.FieldValue.delete()); // true
   * ```
   */
  static isDelete(value: unknown): value is FieldValue {
    return value instanceof DeleteTransform;
  }

[gemini-code-assist]

If isDelete is added to the implementation, it should also be declared in the public type definitions for consistency.

    static isArrayRemove(value: unknown): value is FieldValue;
    /**
     * Returns `true` if the provided value is a sentinel returned by
     * {@link FieldValue.delete}.
     *
     * @param value The value to check.
     * @returns `true` if `value` is a delete sentinel.
     */
    static isDelete(value: unknown): value is FieldValue;

[kyungseopk1m]

Thanks @gemini-code-assist! Added isDelete (plus its declaration in firestore.d.ts and unit tests) in ca2cc57. The new commit keeps the same instanceof-based pattern as the other four guards.

[gemini-code-assist]

Thanks for the update, @kyungseopk1m. The addition of isDelete and the corresponding updates to the type definitions and unit tests look correct and consistent with the existing instanceof pattern used for the other sentinel guards.