field.js

"use strict";
module.exports = Field;

// extends ReflectionObject
var ReflectionObject = require("./object");
Field.prototype = Object.create(ReflectionObject.prototype, {
    constructor: {
        value: Field,
        writable: true,
        enumerable: false,
        configurable: true
    }
});
Field.className = "Field";

var Enum  = require("./enum"),
    types = require("./types"),
    util  = require("./util");

var Type; // cyclic

var ruleRe = /^(?:required|optional|repeated)$/;

/**
 * Constructs a new message field instance. Note that {@link MapField|map fields} have their own class.
 * @name Field
 * @classdesc Reflected message field.
 * @extends FieldBase
 * @constructor
 * @param {string} name Unique name within its namespace
 * @param {number} id Unique id within its namespace
 * @param {string} type Value type
 * @param {string|Object.<string,*>} [rule="optional"] Field rule
 * @param {string|Object.<string,*>} [extend] Extended type if different from parent
 * @param {Object.<string,*>} [options] Declared options
 */

/**
 * Constructs a field from a field descriptor.
 * @param {string} name Field name
 * @param {IField} json Field descriptor
 * @returns {Field} Created field
 * @throws {TypeError} If arguments are invalid
 */
Field.fromJSON = function fromJSON(name, json) {
    var field = new Field(name, json.id, json.type, json.rule, json.extend, json.options, json.comment);
    if (json.edition)
        field._edition = json.edition;
    if (json.protoName)
        field.protoName = json.protoName;
    if (json.jsonName !== undefined)
        field.jsonName = json.jsonName;
    else if (json.options && json.options.json_name !== undefined)
        field.jsonName = json.options.json_name;
    field._defaultEdition = "proto3";  // For backwards-compatibility.
    return field;
};

/**
 * Not an actual constructor. Use {@link Field} instead.
 * @classdesc Base class of all reflected message fields. This is not an actual class but here for the sake of having consistent type definitions.
 * @exports FieldBase
 * @extends ReflectionObject
 * @constructor
 * @param {string} name Unique name within its namespace
 * @param {number} id Unique id within its namespace
 * @param {string} type Value type
 * @param {string|Object.<string,*>} [rule="optional"] Field rule
 * @param {string|Object.<string,*>} [extend] Extended type if different from parent
 * @param {Object.<string,*>} [options] Declared options
 * @param {string} [comment] Comment associated with this field
 */
function Field(name, id, type, rule, extend, options, comment) {

    if (util.isObject(rule)) {
        comment = extend;
        options = rule;
        rule = extend = undefined;
    } else if (util.isObject(extend)) {
        comment = options;
        options = extend;
        extend = undefined;
    }

    ReflectionObject.call(this, name, options);

    if (!util.isInteger(id) || id < 0)
        throw TypeError("id must be a non-negative integer");

    if (!util.isString(type))
        throw TypeError("type must be a string");

    if (rule !== undefined && !ruleRe.test(rule = rule.toString().toLowerCase()))
        throw TypeError("rule must be a string rule");

    if (extend !== undefined && !util.isString(extend))
        throw TypeError("extend must be a string");

    /**
     * Field rule, if any.
     * @type {string|undefined}
     */
    this.rule = rule && rule !== "optional" ? rule : undefined; // toJSON

    /**
     * Field type.
     * @type {string}
     */
    this.type = type; // toJSON

    /**
     * Unique field id.
     * @type {number}
     */
    this.id = id; // toJSON, marker

    /**
     * Extended type if different from parent.
     * @type {string|undefined}
     */
    this.extend = extend || undefined; // toJSON

    /**
     * Whether this field is repeated.
     * @type {boolean}
     */
    this.repeated = rule === "repeated";

    /**
     * Whether this field is a map or not.
     * @type {boolean}
     */
    this.map = false;

    /**
     * Message this field belongs to.
     * @type {Type|null}
     */
    this.message = null;

    /**
     * OneOf this field belongs to, if any,
     * @type {OneOf|null}
     */
    this.partOf = null;

    /**
     * The field type's default value.
     * @type {*}
     */
    this.typeDefault = null;

    /**
     * The field's default value on prototypes.
     * @type {*}
     */
    this.defaultValue = null;

    /**
     * Whether this field's value should be treated as a long.
     * @type {boolean}
     */
    this.long = util.Long ? types.long[type] !== undefined : /* istanbul ignore next */ false;

    /**
     * Whether this field's value is a buffer.
     * @type {boolean}
     */
    this.bytes = type === "bytes";

    /**
     * Resolved type if not a basic type.
     * @type {Type|Enum|null}
     */
    this.resolvedType = null;

    /**
     * Sister-field within the extended type if a declaring extension field.
     * @type {Field|null}
     */
    this.extensionField = null;

    /**
     * Sister-field within the declaring namespace if an extended field.
     * @type {Field|null}
     */
    this.declaringField = null;

    /**
     * Comment for this field.
     * @type {string|null}
     */
    this.comment = comment;

    /**
     * Field name as declared in the .proto source, if different from `name`.
     * @type {string|undefined}
     */
    this.protoName = undefined;

    /**
     * JSON name, if different from the derived default.
     * @type {string|undefined}
     */
    this.jsonName = undefined;
}

/**
 * Determines whether this field is required.
 * @name Field#required
 * @type {boolean}
 * @readonly
 */
Object.defineProperty(Field.prototype, "required", {
    get: function() {
        return this._features.field_presence === "LEGACY_REQUIRED";
    }
});

/**
 * Determines whether this field is not required.
 * @name Field#optional
 * @type {boolean}
 * @readonly
 */
Object.defineProperty(Field.prototype, "optional", {
    get: function() {
        return !this.required;
    }
});

/**
 * Determines whether this field uses tag-delimited encoding.  In proto2 this
 * corresponded to group syntax.
 * @name Field#delimited
 * @type {boolean}
 * @readonly
 */
Object.defineProperty(Field.prototype, "delimited", {
    get: function() {
        return this.resolvedType instanceof Type &&
            this._features.message_encoding === "DELIMITED";
    }
});

/**
 * Determines whether this field is packed. Only relevant when repeated.
 * @name Field#packed
 * @type {boolean}
 * @readonly
 */
Object.defineProperty(Field.prototype, "packed", {
    get: function() {
        return this._features.repeated_field_encoding === "PACKED";
    }
});

/**
 * Determines whether this field tracks presence.
 * @name Field#hasPresence
 * @type {boolean}
 * @readonly
 */
Object.defineProperty(Field.prototype, "hasPresence", {
    get: function() {
        if (this.repeated || this.map) {
            return false;
        }
        return this.partOf || // oneofs
            this.declaringField || this.extensionField || // extensions
            this._features.field_presence !== "IMPLICIT";
    }
});

/**
 * The field name as declared in the .proto source (snake_case). Populated on resolve,
 * falling back to `name`. Mirrors `FieldDescriptorProto.name`.
 * @name Field#protoName
 * @type {string}
 * @readonly
 */

/**
 * The JSON name of this field (lowerCamelCase per protoc's `ToJsonName`, or an
 * explicit `[json_name]`). Populated on resolve. This is the key used on ProtoJSON output.
 * @name Field#jsonName
 * @type {string}
 * @readonly
 */

/**
 * @override
 */
Field.prototype.setOption = function setOption(name, value, ifNotSet) {
    return ReflectionObject.prototype.setOption.call(this, name, value, ifNotSet);
};

/**
 * Field descriptor.
 * @interface IField
 * @property {string} [edition] Edition
 * @property {string} [rule="optional"] Field rule
 * @property {string} type Field type
 * @property {number} id Field id
 * @property {Object.<string,*>} [options] Field options
 * @property {string|null} [comment] Field comment
 */

/**
 * Extension field descriptor.
 * @interface IExtensionField
 * @extends IField
 * @property {string} extend Extended type
 */

/**
 * Converts this field to a field descriptor.
 * @param {IToJSONOptions} [toJSONOptions] JSON conversion options
 * @returns {IField} Field descriptor
 */
Field.prototype.toJSON = function toJSON(toJSONOptions) {
    var keepComments = toJSONOptions ? Boolean(toJSONOptions.keepComments) : false;
    return util.toObject([
        "edition"      , this._editionToJSON(),
        "rule"         , this.rule !== "optional" && this.rule || undefined,
        "type"         , this.type,
        "id"           , this.id,
        "extend"       , this.extend,
        "protoName"    , this.protoName !== this.name ? this.protoName : undefined,
        "jsonName"     , this.jsonName !== util.jsonName(this.protoName || this.name) ? this.jsonName : undefined,
        "options"      , this.options,
        "comment"      , keepComments ? this.comment : undefined
    ]);
};

/**
 * Verifies that a resolved type or enum may be referenced by the given field.
 * A symbol declared `local` (edition 2024) is only visible within its own file.
 * If either file name is unknown - programmatic construction, `fromJSON`, bundled
 * common types - the reference cannot be proven to cross files and is allowed.
 * @param {Field} field Referencing field
 * @param {Type|Enum} resolved Resolved type or enum
 * @returns {undefined}
 * @throws {Error} If the referenced symbol is local to another file
 * @inner
 */
function checkVisibility(field, resolved) {
    if (resolved.visibility !== "local")
        return;
    var from = (field.declaringField || field).filename;
    if (!from || !resolved.filename || from === resolved.filename)
        return;
    throw Error("'" + resolved.fullName + "' is local to '" + resolved.filename + "' and cannot be referenced from '" + from + "'");
}

/**
 * Resolves this field's type references.
 * @returns {Field} `this`
 * @throws {Error} If any reference cannot be resolved
 */
Field.prototype.resolve = function resolve() {

    if (this.resolved)
        return this;

    if ((this.typeDefault = types.defaults[this.type]) === undefined) { // if not a basic type, resolve it
        this.resolvedType = (this.declaringField ? this.declaringField.parent : this.parent).lookupTypeOrEnum(this.type);
        checkVisibility(this, this.resolvedType);
        if (this.resolvedType instanceof Type)
            this.typeDefault = null;
        else // instanceof Enum
            this.typeDefault = this.resolvedType.values[Object.keys(this.resolvedType.values)[0]]; // first defined
    } else if (this.options && this.options.proto3_optional) {
        // proto3 scalar value marked optional; should default to null
        this.typeDefault = null;
    }

    // use explicitly set default value if present
    if (this.options && this.options["default"] != null) {
        this.typeDefault = this.options["default"];
        if (this.resolvedType instanceof Enum && typeof this.typeDefault === "string")
            this.typeDefault = this.resolvedType.values[this.typeDefault];
    }

    // remove unnecessary options
    if (this.options) {
        if (this.options.packed !== undefined && this.resolvedType && !(this.resolvedType instanceof Enum))
            delete this.options.packed;
        if (!Object.keys(this.options).length)
            this.options = undefined;
    }

    // convert to internal data type if necesssary
    if (this.long) {
        var unsigned = this.type === "uint64" || this.type === "fixed64";
        this.typeDefault = typeof this.typeDefault === "string"
            ? util.Long.fromString(this.typeDefault, unsigned)
            : util.Long.fromNumber(this.typeDefault, unsigned);

        /* istanbul ignore else */
        if (Object.freeze)
            Object.freeze(this.typeDefault); // long instances are meant to be immutable anyway (i.e. use small int cache that even requires it)

    } else if (types.long[this.type] !== undefined && typeof this.typeDefault === "string") {
        this.typeDefault = parseInt(this.typeDefault, 10);
    } else if (this.bytes && typeof this.typeDefault === "string") {
        var buf;
        if (util.base64.test(this.typeDefault))
            util.base64.decode(this.typeDefault, buf = util.newBuffer(util.base64.length(this.typeDefault)), 0);
        else
            util.utf8.write(this.typeDefault, buf = util.newBuffer(util.utf8.length(this.typeDefault)), 0);
        this.typeDefault = buf;
    }

    // take special care of maps and repeated fields
    if (this.map)
        this.defaultValue = util.emptyObject;
    else if (this.repeated)
        this.defaultValue = util.emptyArray;
    else
        this.defaultValue = this.typeDefault;

    // ensure proper value on prototype
    if (this.parent instanceof Type && this.parent._ctor)
        this.parent._ctor.prototype[this.name] = this.defaultValue;

    // derive the proto/JSON names
    if (this.protoName === undefined)
        this.protoName = this.name;
    if (this.jsonName === undefined)
        this.jsonName = util.jsonName(this.protoName);

    return ReflectionObject.prototype.resolve.call(this);
};

/**
 * Infers field features from legacy syntax that may have been specified differently.
 * in older editions.
 * @param {string|undefined} edition The edition this proto is on, or undefined if pre-editions
 * @returns {object} The feature values to override
 */
Field.prototype._inferLegacyProtoFeatures = function _inferLegacyProtoFeatures(edition) {
    if (edition !== "proto2" && edition !== "proto3") {
        return {};
    }

    var features = {};

    if (this.rule === "required") {
        features.field_presence = "LEGACY_REQUIRED";
    }
    if (this.parent && types.defaults[this.type] === undefined) {
        // We can't use resolvedType because types may not have been resolved yet.  However,
        // legacy groups are always in the same scope as the field so we don't have to do a
        // full scan of the tree.
        var type = this.parent.get(this.type.split(".").pop());
        if (type && type instanceof Type && type.group) {
            features.message_encoding = "DELIMITED";
        }
    }
    if (this.getOption("packed") === true) {
        features.repeated_field_encoding = "PACKED";
    } else if (this.getOption("packed") === false) {
        features.repeated_field_encoding = "EXPANDED";
    }
    return features;
};

/**
 * @override
 */
Field.prototype._resolveFeatures = function _resolveFeatures(edition) {
    return ReflectionObject.prototype._resolveFeatures.call(this, this._edition || edition);
};

/**
 * Decorator function as returned by {@link Field.d} and {@link MapField.d} (TypeScript).
 * @typedef FieldDecorator
 * @type {function}
 * @param {Object} prototype Target prototype
 * @param {string} fieldName Field name
 * @returns {undefined}
 * @deprecated Legacy TypeScript decorator support. Will be removed in a future release.
 */

/**
 * Field decorator (TypeScript).
 * @name Field.d
 * @function
 * @param {number} fieldId Field id
 * @param {"double"|"float"|"int32"|"uint32"|"sint32"|"fixed32"|"sfixed32"|"int64"|"uint64"|"sint64"|"fixed64"|"sfixed64"|"string"|"bool"|"bytes"|Object} fieldType Field type
 * @param {"optional"|"required"|"repeated"} [fieldRule="optional"] Field rule
 * @param {T} [defaultValue] Default value
 * @returns {FieldDecorator} Decorator function
 * @template T extends number | number[] | Long | Long[] | string | string[] | boolean | boolean[] | Uint8Array | Uint8Array[] | Buffer | Buffer[]
 * @deprecated Legacy TypeScript decorator support. Will be removed in a future release.
 */
Field.d = function decorateField(fieldId, fieldType, fieldRule, defaultValue) {

    // submessage: decorate the submessage and use its name as the type
    if (typeof fieldType === "function")
        fieldType = util.decorateType(fieldType).name;

    // enum reference: create a reflected copy of the enum and keep reuseing it
    else if (fieldType && typeof fieldType === "object")
        fieldType = util.decorateEnum(fieldType).name;

    return function fieldDecorator(prototype, fieldName) {
        util.decorateType(prototype.constructor)
            .add(new Field(fieldName, fieldId, fieldType, fieldRule, { "default": defaultValue }));
    };
};

// Sets up cyclic dependencies (called in index-light)
Field._configure = function configure(Type_) {
    Type = Type_;
};

/**
 * Field decorator (TypeScript).
 * @name Field.d
 * @function
 * @param {number} fieldId Field id
 * @param {Constructor<T>|string} fieldType Field type
 * @param {"optional"|"required"|"repeated"} [fieldRule="optional"] Field rule
 * @returns {FieldDecorator} Decorator function
 * @template T extends Message<T>
 * @variation 2
 * @deprecated Legacy TypeScript decorator support. Will be removed in a future release.
 */
// like Field.d but without a default value