protobufjs

This project is developed based on protobufjs.

Introduction

Protocol buffers (protobuf) is a language-neutral, platform-neutral extensible mechanism for serializing structured data. It is used in (data) communication protocols and for data storage. As a flexible, efficient, and automatic structured data serialization method, ProtoBuf is smaller, faster, and simpler than XML.

In this project, protobufjs 7.2.4 has been adapted for use with OpenHarmony.

How to Install

ohpm install @ohos/protobufjs

For details about the OpenHarmony ohpm environment configuration, see OpenHarmony HAR.

Constraints

Compatibility

This project has been verified in the following version:

• DevEco Studio: 6.0.2 Release(6.0.2.642), SDK: API12 Release(5.0.0.71);

Permission Requirements

None

Usage Example

import { user } from './user.js';

@Entry
@Component
struct Index {
  build() {
    Column() {
      Button('Encode and decode')
        .onClick(() => {
          // Create message object
          let message = user.UserLoginResponse.create({
            sessionId: '215135415351435',
            userPrivilege: 'John123',
            isTokenType: false
          });

          // Execution coding
          let bytes: Uint8Array = user.UserLoginResponse.encode(message).finish();

          // Perform decoding and output the result.
          let decoded = user.UserLoginResponse.decode(bytes);
          // print: `sessionId=215135415351435, userPrivilege=John123`.
          console.info(`protobufjs decode result: sessionId=${decoded.sessionId}, userPrivilege=${decoded.userPrivilege}`);
        });
    }
    .width('100%')
    .height('100%');
  }
}

How to Use

1. Define a proto file

Create a proto file in the business directory and define the message body structure according to the .proto file format, for example, user.proto:

syntax = "proto3";

package user;

message UserLoginResponse {
  string sessionId = 1;
  string userPrivilege = 2;
  bool isTokenType = 3;
  int64 formatTimestamp = 5;
  bytes data = 6;
}

2. Generate js and d.ts files

// Install protobufjs globally.
npm install -g protobufjs@7.2.4
  
// Install protobufjs-cli globally.
npm install -g protobufjs-cli

// Run the following commands in the .proto file directory:
pbjs -t static-module -w es6 -o user.js user.proto
pbts user.js -o user.d.ts

3. Update imports in generated files

Modify import * as $protobuf from "protobufjs/minimal"; in the generated JS file to:

// user.js
import $protobuf from '@ohos/protobufjs';
import Long from 'long';
$protobuf.util.Long = Long;
$protobuf.configure();

Modify import * as $protobuf from "protobufjs"; in the generated .d.ts file to:

// user.d.ts
import $protobuf from '@ohos/protobufjs';

4. Install dependency and integrate into project

ohpm install long

Copy generated user.js and user.d.ts into your app, then run create, encode, and decode as shown in the usage example.

encode

import { user } from './user.js';

 let msg = user.UserLoginResponse.create({
     sessionId: "testSynchronouslyLoadProtoFile",
     userPrivilege: "John123",
     isTokenType: false,
     formatTimestamp: 12342222
 });

 let bytes: Uint8Array = user.UserLoginResponse.encode(msg).finish();

decode

let decoded = user.UserLoginResponse.decode(bytes);

5. Using BigInt

// In the generated JS file, add $protobuf.util Set Long to undefined

import Long from 'long';
$protobuf.util.Long = undefined;
$protobuf.configure();

let msg = user.UserLoginResponse.create({
  sessionId: "215135415351435",
  userPrivilege: "John123",
  isTokenType: false,
  formatTimestamp: BigInt("9223372036854775807"),
});

Note: In the user.d.ts code file of this demo, the BigInt type supported by the formatTimestamp property is manually added and not generated through any command.

6. Troubleshooting

• If you see Cannot find module errors, check whether all required dependencies in the protobufjs chain are installed.
• If int64 values are incorrect, verify that $protobuf.util.Long is configured and $protobuf.configure() is called.
• In split-package or HSP scenarios, verify exported paths and package visibility in target modules.

API Reference

API

Name	Type	Parameters	Return Value	Required	OpenHarmony Support	Description
create()	Method	properties?: Object	Object	No	Yes	Creates a message object.
encode()	Method	message: Object, writer?: $protobuf.Writer	$protobuf.Writer	Yes	Yes	Encodes a message.
decode()	Method	reader: $protobuf.Reader/Uint8Array, length?: number	Object	Yes	Yes	Decodes a message.
verify()	Method	message: Object	string/null	Yes	Yes	Verifies the message validity
fromObject()	Method	object: Object	Object	Yes	Yes	Creates a message instance of this type from an object, and converts values to their respective internal types.
toObject()	Method	message: Object, options?: $protobuf.IConversionOptions	Object	Yes	Yes	Converts an array of key-value pairs to an object, omitting undefined values.

About Obfuscation

• For code obfuscation guidance, see Code Obfuscation.
• To keep protobufjs available after obfuscation, add exclusions in your module-level obfuscation-rules.txt:

-keep
./oh_modules/@ohos/protobufjs

New Features

• Improved document structure for installation, examples, and API reference to speed up integration and troubleshooting.

FAQ

1. Missing module dependency errors

Run ohpm install and ensure long plus required transitive dependencies are installed.

2. BigInt/int64 conversion issues

Check whether Long is configured in generated code, or set util.Long to undefined based on your business requirement.

3. Generated import path errors

Ensure protobuf imports in both user.js and user.d.ts are updated to @ohos/protobufjs.

Directory Structure

protobuf
├── AppScope/                     # App-level configuration
├── entry/                        # Demo app
│   └── src/main/ets/pages/       # Demo pages and generated files
├── library/                      # Core library module
│   └── src/main/ets/             # protobufjs source and typings
├── README.md                     # English documentation
├── README_zh.md                  # Chinese documentation
├── CHANGELOG.md                  # Version changelog
└── README.OpenSource             # Open source statement

Contributing

If you encounter issues, submit an Issue. Pull requests are also welcome through PR.

License

This project is licensed under BSD 3-Clause License.