@m-filescorporation/uix-vault-messages

TypeScript/JavaScript library for working with M-Files gRPC messages. Provides type-safe constructors, runtime validation, and helper utilities for gRPC message objects.

Why use this instead of raw gRPC JSON?

Raw gRPC objects are valid, but they are verbose and easy to misuse because many fields are nested or union-like.

This package gives constructor helpers so you write less boilerplate and make fewer shape mistakes.

Example: TypedValue is faster to work with in practice

With helpers, setting and reading typed values is one line each:

import { MFGrpc } from "@m-filescorporation/uix-vault-messages";

const tv = MFGrpc.TypedValue.Text("Contract A");

const text = tv.AsText();
const isNull = tv.IsNull;

Why this is faster than raw object handling:

• No manual union field mapping for each datatype.
• No repeated switch/if logic when reading values.
• Safer conversions (AsText(), AsNumber(), AsDate(), etc.) from one API.

Other places helpers save time

1. ObjID nested path handling:

const objId = new MFGrpc.ObjID();
objId.ID = 123;   // instead of manually setting item_id.internal_id
objId.Type = 0;

2. PropertyValue typed setters:

const pv = new MFGrpc.PropertyValue();
pv.property_def = 1001;
pv.value?.SetText("Document title");

3. SearchConditionArray convenience builders:

const conditions = new MFGrpc.SearchConditionArray();
conditions.AddObjectTypeCondition(0);
conditions.AddDeletedCondition(false);

No global variables are created by this package; use MFGrpc from imports.

Message Types with Helper Utilities

The following message types have enhanced helper properties and methods:

| Message Type | Helper Properties | Helper Methods | |--------------|-------------------|----------------| | ObjID | ID, Type, IsExternal | - | | ObjVer | ID, Type, Version | - | | ObjVerVersion | ID, Type, Version | - | | ObjectVersionEx | ID, ExternalID, Title, Type, Version, Class, IsExternal, IsCheckedOut, IsSingleFileObject, IsDeleted, GUID | GetProperty(), SetProperty(), RemoveProperty() | | TypedValue | IsNull | Set(), AsBool(), AsNumber(), AsDate(), AsText(), AsLookup(), AsLookups() | | PropertyValue | - | SetText(), SetInt(), SetBool(), SetDate(), SetLookup(), SetMultiLookup() | | Lookup | Item, ValueList, Title, Version, Deleted | ToString() | | MultiSelectLookup | Count | Add(), ToArray() | | ItemID | ID, ExternalID, IsExternal | - | | FileVer | ID, Version | - | | SearchConditionArray | Count | Add(), AddPropertyCondition(), AddObjectTypeCondition(), AddDeletedCondition() | | PropertyValueArray | Count | Add(), Get(), Set(), Remove() |

Installation

npm install @m-filescorporation/uix-vault-messages

Quick Start

Full Version (Recommended)

The easiest way to get started - includes pre-bundled message definitions:

import { MFGrpc } from "@m-filescorporation/uix-vault-messages";

// Create gRPC message objects using constructors
const objId = new MFGrpc.ObjID();
objId.type = 0;
objId.item_id = { internal_id: 123 };

// Or initialize with data directly
const objVer = new MFGrpc.ObjVer({
  obj_id: { type: 0, item_id: { internal_id: 123 } },
  version: 1
});

// Serialize to JSON
console.log(JSON.stringify(objVer));

Entry Points

| Entry Point | Bundle Size | Use Case | |-------------|-------------|----------| | @m-filescorporation/uix-vault-messages | ~209.3 KB (CJS) / ~204.7 KB (ESM) | Full features, pre-bundled public messages |

Working with Messages

Creating Objects

const MFiles = getGRPCApi();

// Using constructor
const objId = new MFiles.ObjID();

// Using constructor with initial data
const objId = new MFiles.ObjID({
  type: 0,
  item_id: { internal_id: 42 }
});

Using Helper Properties

Helper properties provide convenient access to nested data:

const MFiles = getGRPCApi();

// ObjID helpers
const objId = new MFiles.ObjID();
objId.ID = 123;        // Sets item_id.internal_id
objId.Type = 0;        // Sets type
console.log(objId.ID); // 123

// ObjectVersionEx helpers
const objVer = new MFiles.ObjectVersionEx(serverResponse);
console.log(objVer.ID);          // Internal ID
console.log(objVer.Title);       // Object title
console.log(objVer.Class);       // Class ID
console.log(objVer.IsCheckedOut); // Check-out status

// TypedValue helpers
const tv = new MFiles.TypedValue();
tv.Set(Datatype.DATATYPE_TEXT, "Hello");
console.log(tv.AsText());  // "Hello"
console.log(tv.IsNull);    // false

// Lookup helpers
const lookup = new MFiles.Lookup();
lookup.Item = 42;
lookup.ValueList = 1;
console.log(lookup.ToString()); // "42"

Working with PropertyValues

const MFiles = getGRPCApi();

// Create and set property value
const pv = new MFiles.PropertyValue();
pv.property_def = 1001;  // Property definition ID
pv.value?.SetText("Document Title");

// Or use SetInt, SetBool, SetDate, SetLookup, etc.
const pvNumber = new MFiles.PropertyValue();
pvNumber.property_def = 1002;
pvNumber.value?.SetInt(42);

Working with ObjectVersionEx

const MFiles = getGRPCApi();

// Assume objVerEx comes from server response
const objVerEx = new MFiles.ObjectVersionEx(serverData);

// Read properties using helpers
console.log(objVerEx.ID);       // 123
console.log(objVerEx.Title);    // "My Document"
console.log(objVerEx.Type);     // 0 (Document)
console.log(objVerEx.Version);  // 5
console.log(objVerEx.Class);    // 1

// Get specific property
const nameProp = objVerEx.GetProperty(1001);
console.log(nameProp?.value?.AsText());

// Modify properties
objVerEx.SetProperty(1001, pv);
objVerEx.RemoveProperty(1002);

Building Search Conditions

const MFiles = getGRPCApi();

const conditions = new MFiles.SearchConditionArray();

// Add object type condition
conditions.AddObjectTypeCondition(0); // Documents

// Add property condition
conditions.AddPropertyCondition(1001, Datatype.DATATYPE_TEXT, "Report");

// Add deleted condition
conditions.AddDeletedCondition(false); // Not deleted

console.log(conditions.Count); // 3

Common Methods

All message objects provide these utility methods:

All message objects provide these utility methods:

| Method | Description | |--------|-------------| | toJSON() | Convert to plain JSON object | | Clone() | Create a deep copy | | Has(field) | Check if field has value | | _className | Get the gRPC message type name |

const objId = new MFiles.ObjID();
objId.type = 0;
objId.item_id = { internal_id: 123 };

// Get class name
console.log(objId._className); // "ObjID"

// Check if field exists
console.log(objId.Has("item_id")); // true

// Clone the object
const copy = objId.Clone();

// Serialize
const json = JSON.stringify(objId);

Nested Objects

Nested message properties are automatically wrapped:

const objId = new MFiles.ObjID();
const itemId = objId.item_id; // Also a wrapped object
console.log(itemId._className); // "ItemID"

Validation

import { ValidateObject, ValidateObjectStrict } from "@m-filescorporation/uix-vault-messages";

// Returns validation result
const result = ValidateObject("ObjID", data);
if (!result.isValid) {
  for (const error of result.errors) {
    console.log(`${error.field}: ${error.message}`);
  }
}

// Throws on validation failure
try {
  ValidateObjectStrict("ObjID", data);
} catch (error) {
  console.error(error.message);
}

Default Values

| gRPC Type | Default Value | |-----------|---------------| | int32, int64, uint32, etc. | 0 | | string | "" | | bool | false | | bytes | new Uint8Array() | | message | null | | enum | 0 | | repeated | [] |

TypeScript Support

The package includes comprehensive TypeScript definitions:

import type { ExtendedMessageType } from "@m-filescorporation/uix-vault-messages";

function processObjId(objId: ExtendedMessageType<"ObjID">) {
  console.log(objId.type);
  console.log(objId.item_id?.internal_id);
}

Helper Functions

import {
  isProxyObject,
  getProxyClassName,
  extractProxyData
} from "@m-filescorporation/uix-vault-messages";

// Check if object is a message proxy
if (isProxyObject(obj)) {
  // Get the message type
  const type = getProxyClassName(obj); // "ObjID"

  // Extract raw data
  const raw = extractProxyData(obj);
}

License

MIT © M-Files Corporation

Generated Helper Methods

This section is generated from spec/dynamic_helpers.json and spec/static_helpers.json.

Dynamic Helpers

LookupExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | ToString() | string | String representation of the Lookup object. |

MultiSelectLookupExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | Add(value: number | Lookup) | ExtendedMessageType<"MultiSelectLookup"> | Adds a new value to the MultiSelectLookup. | | ToString() | string | Returns a string representation of the MultiSelectLookup. |

ObjectVersionExExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | AsObjVer() | ExtendedMessageType<"ObjVer"> | Get as ObjVer object. | | GetFiles() | ExtendedMessageType<"File">[] | Get the files associated with the object. | | GetPrimaryFileIfAvailable() | ExtendedMessageType<"File"> | Gets the primary file of a if available. |

PropertyValueArrayExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | Add(propertyDef: number, type: T, value?: TypedValueValueMap[T]) | ExtendedMessageType<"PropertyValueArray"> | Adds a new property value to the array. | | AddWithTypedValue(propertyDef: number, value: TypedValue) | ExtendedMessageType<"PropertyValueArray"> | Adds a new property value with a TypedValue to the array. |

PropertyValueExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | SetText(value?: string) | void | Set the text value. | | SetMultiText(value?: string) | void | Set the multi-line text value. | | SetBool(value?: boolean) | void | Set the boolean value. | | SetInt(value?: number) | void | Set the integer value. | | SetDate(value?: Date) | void | Set the date value. | | SetLookup(value?: Lookup) | void | Set the lookup value. | | SetFloat(value?: number) | void | Set the float (real number) value. | | SetMultiLookup(value?: Array) | void | Set the multi-select lookup value. | | SetTime(value?: Date) | void | Set the time value. | | SetTimestamp(value?: Date) | void | Set the timestamp value. |

SearchConditionArrayExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | Text(options: FTSFLAGS, condition: ConditionType, value: string) | ExtendedMessageType<"SearchConditionArray"> | Creates a text search condition and adds it to the array. | | Status(type: StatusType, condition: ConditionType, dataType: T, value?: TypedValueValueMap[T]) | ExtendedMessageType<"SearchConditionArray"> | Creates a status search condition and adds it to the array. | | StatusWithTypedValue(type: StatusType, condition: ConditionType, value: TypedValue) | ExtendedMessageType<"SearchConditionArray"> | Creates a status search condition and adds it to the array. | | Property(propertyDef: number, condition: ConditionType, dataType: T, value?: TypedValueValueMap[T]) | ExtendedMessageType<"SearchConditionArray"> | Creates a property search condition and adds it to the array. | | PropertyWithTypedValue(propertyDef: number, condition: ConditionType, value: TypedValue) | ExtendedMessageType<"SearchConditionArray"> | Creates a property search condition and adds it to the array. | | AnyLookupProperty(valueList: number, condition: ConditionType, value: number | Lookup | unknown) | ExtendedMessageType<"SearchConditionArray"> | Creates an any lookup property search condition and adds it to the array. |

TypedValueExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | Set(type: T, value?: TypedValueValueMap[T]) | void | Set the value and type of the TypedValue. | | AsBool() | boolean | Get the value as a boolean. If the value is null, returns null. If the value is not a boolean, throws an error. | | AsNumber() | number | Get the value as a number. If the value is null, returns null. If the value is not a number, throws an error. | | AsDate() | Date | Get the value as a Date. If the value is null, returns null. If the value is not a date/time/timestamp, throws an error. | | AsText() | string | Get the value as text. If the value is null, returns null. If the value is not convertible to text, throws an error. | | AsLookup() | Lookup | Get the value as a Lookup. If the value is null, returns null. If the value is not a lookup, throws an error. | | AsLookups() | Lookup[] | Get the value as an array of Lookups. If the value is null, returns null. If the value is not a multi-select lookup, throws an error. | | GetLookupID() | number | If the TypedValue is of type Lookup, get the ID of the lookup. If the value is null, returns null. If the value is not a lookup, throws an error. | | SetText(value?: string) | void | Set the value as text. | | SetMultiText(value?: string) | void | Set the value as multi-line text. | | SetBool(value?: boolean) | void | Set the value as a boolean. | | SetInt(value?: number) | void | Set the value as an integer. | | SetDate(value?: Date) | void | Set the value as a date. | | SetLookup(value?: Lookup) | void | Set the value as a lookup. | | SetFloat(value?: number) | void | Set the value as a real number. | | SetMultiLookup(value?: Array) | void | Set the value as a multi-select lookup. | | SetTime(value?: Date) | void | Set the value as a time. | | SetTimestamp(value?: Date) | void | Set the value as a timestamp. |

Static Constructors

ExpressionStaticExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | Text(options: FTSFLAGS) | ExtendedMessageType<"Expression"> | Creates a new Text expression. | | Status(type: StatusType) | ExtendedMessageType<"Expression"> | Creates a new Status expression. | | Property(propertyDef: number) | ExtendedMessageType<"Expression"> | Creates a new Property expression for the specified property definition ID. | | AnyLookupProperty(valueList: number) | ExtendedMessageType<"Expression"> | Creates a new AnyLookupProperty expression for the specified value list. |

FileVerStaticExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | Create(id: number, version: number) | ExtendedMessageType<"FileVer"> | Create a new FileVer object with the specified ID and Version. |

ItemIDStaticExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | Create(id: number) | ExtendedMessageType<"ItemID"> | Create a new ItemID object with the specified internal ID. |

LookupStaticExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | Create(item: number, valueList?: number, title?: string) | ExtendedMessageType<"Lookup"> | Create a new Lookup object representing a value list item. |

MultiSelectLookupStaticExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | Create(value: Array<number | Lookup>) | ExtendedMessageType<"MultiSelectLookup"> | Create a new MultiSelectLookup object from an array of Lookup objects or numeric item IDs. If a number is provided, it will be converted to a Lookup with that item ID. |

ObjIDStaticExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | Create(id: number, type?: number) | ExtendedMessageType<"ObjID"> | Create a new ObjID object with the specified type and internal ID. |

ObjVerStaticExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | Create(type: number, internalId: number, version: number) | ExtendedMessageType<"ObjVer"> | Create a new ObjVer object with the specified type, internal ID, and version. |

ObjVerVersionStaticExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | Create(version: number) | ExtendedMessageType<"ObjVerVersion"> | Create a new ObjVerVersion object with the specified internal version number. Automatically assigns the correct ObjVerVersionType based on the version value (-1 => LATEST, otherwise SPECIFIC). |

PropertyValueStaticExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | Create(propertyDef: number, type: T, value?: TypedValueValueMap[T]) | ExtendedMessageType<"PropertyValue"> | Creates a new PropertyValue. | | CreateWithTypedValue(propertyDef: number, value: TypedValue) | ExtendedMessageType<"PropertyValue"> | Creates a new PropertyValue with a TypedValue. | | Text(propertyDef: number, value?: string) | ExtendedMessageType<"PropertyValue"> | Creates a new PropertyValue of type Text. | | Float(propertyDef: number, value?: number) | ExtendedMessageType<"PropertyValue"> | Creates a new PropertyValue of type Real Number (Float). | | Bool(propertyDef: number, value?: boolean) | ExtendedMessageType<"PropertyValue"> | Creates a new PropertyValue of type Boolean. | | Lookup(propertyDef: number, value?: Lookup) | ExtendedMessageType<"PropertyValue"> | Creates a new PropertyValue of type Lookup. | | Date(propertyDef: number, value?: Date) | ExtendedMessageType<"PropertyValue"> | Creates a new PropertyValue of type Date. | | Timestamp(propertyDef: number, value?: Date) | ExtendedMessageType<"PropertyValue"> | Creates a new PropertyValue of type Timestamp. | | MultiLookup(propertyDef: number, value?: Array) | ExtendedMessageType<"PropertyValue"> | Creates a new PropertyValue of type Multi-Select Lookup. | | Int(propertyDef: number, value?: number) | ExtendedMessageType<"PropertyValue"> | Creates a new PropertyValue of type Integer. | | MultiText(propertyDef: number, value?: string) | ExtendedMessageType<"PropertyValue"> | Creates a new PropertyValue of type Multi-Line Text. | | Time(propertyDef: number, value?: Date) | ExtendedMessageType<"PropertyValue"> | Creates a new PropertyValue of type Time. |

SearchConditionArrayStaticExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | Create(conditions?: Array) | ExtendedMessageType<"SearchConditionArray"> | Creates a new SearchConditionArray object. |

SearchConditionStaticExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | Text(options: FTSFLAGS, condition: ConditionType, value: string) | ExtendedMessageType<"SearchCondition"> | Creates a search condition to search for text. | | Status(type: StatusType, condition: ConditionType, dataType: T, value?: TypedValueValueMap[T]) | ExtendedMessageType<"SearchCondition"> | Creates a search condition to search for status. | | StatusWithTypedValue(type: StatusType, condition: ConditionType, value: TypedValue) | ExtendedMessageType<"SearchCondition"> | Creates a search condition to search for status. | | Property(propertyDef: number, condition: ConditionType, dataType: T, value?: TypedValueValueMap[T]) | ExtendedMessageType<"SearchCondition"> | Creates a search condition to search for a property. | | PropertyWithTypedValue(propertyDef: number, condition: ConditionType, value: TypedValue) | ExtendedMessageType<"SearchCondition"> | Creates a search condition to search for a property. | | AnyLookupProperty(valueList: number, condition: ConditionType, value: number | Lookup | unknown) | ExtendedMessageType<"SearchCondition"> | Creates a search condition to search for an any lookup property. |

TypedValueStaticExtensions

| Method Signature | Returns | Description | |------------------|---------|-------------| | Create(type: T, value?: TypedValueValueMap[T]) | ExtendedMessageType<"TypedValue"> | Creates a new TypedValue of the specified type. | | Text(value?: string) | ExtendedMessageType<"TypedValue"> | Creates a new TypedValue of type Text. | | Float(value?: number) | ExtendedMessageType<"TypedValue"> | Creates a new TypedValue of type Real Number (Float). | | Bool(value?: boolean) | ExtendedMessageType<"TypedValue"> | Creates a new TypedValue of type Boolean. | | Lookup(value?: Lookup) | ExtendedMessageType<"TypedValue"> | Creates a new TypedValue of type Lookup. | | Date(value?: Date) | ExtendedMessageType<"TypedValue"> | Creates a new TypedValue of type Date. | | Timestamp(value?: Date) | ExtendedMessageType<"TypedValue"> | Creates a new TypedValue of type Timestamp. | | MultiLookup(value?: Array) | ExtendedMessageType<"TypedValue"> | Creates a new TypedValue of type Multi-Select Lookup. | | Int(value?: number) | ExtendedMessageType<"TypedValue"> | Creates a new TypedValue of type Integer. | | MultiText(value?: string) | ExtendedMessageType<"TypedValue"> | Creates a new TypedValue of type Multi-Line Text. | | Time(value?: Date) | ExtendedMessageType<"TypedValue"> | Creates a new TypedValue of type Time. |