https://github.com/basedwon/picobuf
Picobuf is a powerful and flexible library for working with Protocol Buffers in JavaScript.
https://github.com/basedwon/picobuf
data-modeling encoding foreign-keys protobuf service-oriented
Last synced: 17 days ago
JSON representation
Picobuf is a powerful and flexible library for working with Protocol Buffers in JavaScript.
- Host: GitHub
- URL: https://github.com/basedwon/picobuf
- Owner: basedwon
- License: mit
- Created: 2023-07-01T01:49:19.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2023-08-01T00:51:31.000Z (almost 2 years ago)
- Last Synced: 2025-04-19T09:41:00.539Z (about 1 month ago)
- Topics: data-modeling, encoding, foreign-keys, protobuf, service-oriented
- Language: JavaScript
- Homepage:
- Size: 646 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: docs/contributing.md
- License: LICENSE
Awesome Lists containing this project
README
# Picobuf
> good things come in small packets
[](https://www.npmjs.com/package/picobuf)
[](https://gitlab.com/basedwon/picobuf/-/pipelines)
[](https://gitlab.com/basedwon/picobuf/-/blob/master/LICENSE)
[](https://www.npmjs.com/package/picobuf)
[](https://gitlab.com/basedwon/picobuf)
[](https://github.com/basedwon/picobuf)
[](https://twitter.com/basdwon)
[](https://discordapp.com/users/basedwon)
Picobuf is a powerful and flexible library for working with Protocol Buffers in JavaScript. It makes it easy to define models, enums, and services, and provides an intuitive API for encoding and decoding messages. Check out the [documentation](#documentation) to learn more.
## Features
- **Versatile Data Modeling**: Define your data structures using simple or composite fields, with support for lists and foreign keys.
- **Encoding**: Built-in support for MsgPack and JSON, or bring your own encoder.
- **Object Mode**: Or don't encode the data, rather use Picobuf just for data validation.
- **Validation**: Rest easy knowing all of your nested data meets the defined model's schema.
- **Data types as God intended**: String, Boolean, Number, Integer, Float, JSON, Buffer and Foreign relations
- **Enums**: Tightly manage your data with enumerated fields, ensuring data integrity and simplifying validation.
- **Service Methods**: Define arbitrary service methods and decouple your data models from the rest of your application.
- **Isomorphic**: Picobuf works in both Node.js and the browser.
- **Extendable**: Expand your possibilities with custom field types and validation rules.
## Installation
Install the package with:
```bash
npm install picobuf
```
## Usage
First, import the `Picobuf` library.
```js
import Picobuf from 'picobuf'
```
or
```js
const Picobuf = require('picobuf')
```
Then define your models, enums or services.
```js
// create a picobuf instance
const picobuf = new Picobuf({ User: { name: 'string' }})
// or destructure the named model
const { User } = new Picobuf({ User: { name: 'string' }})
// create an instance of the model
const user = User.create({ name: 'Alice' })
// validate this data (throws an error if invalid)
User.validate(user)
// encode
const encoded = User.encode(user)
// decode
const decoded = User.decode(encoded)
// Enums
const { Types } = new Picobuf({ enums: { Types: { values: ['SEN', 'ACK'] }}})
// or
const Types = pb.createEnum('Types', ['SEN', 'ACK'])
console.log(Types.SEN) // => 'SEN'
console.log(Types.getIndex('SEN')) // => 0
// incorrect enum will throw an error
console.log(Types.SEND) // => Invalid enum "SEND"
// Services
const { echo } = new Picobuf({ services: {
echo: {
ping: { // echo.ping service method
request: 'User', // string reference to model
response: User, // direct use of model instance
}
}
}})
const data = { name: 'Bob' }
const encoded = echo.ping.request.encode(data)
const decoded = echo.ping.request.decode(encoded)
```
## Documentation
- [Basic Usage](/docs/basic-usage.md)
- [Advanced Usage](/docs/advanced-usage.md)
- [API Reference](/docs/api.md)
- [Class Diagram](/docs/class-diagram.md)
## Tests
In order to run the test suite, simply clone the repository and install its dependencies:
```bash
git clone https://gitlab.com/basedwon/picobuf.git
cd picobuf
npm install
```
To run the tests:
```bash
npm test
```
Testing in the browser: *coming soon...*
## Contributing
Thank you! Please see our [contributing guidelines](/docs/contributing.md) for details.
## Donations
If you find this project useful and want to help support further development, please send us some coin. We greatly appreciate any and all contributions. Thank you!
**Bitcoin (BTC):**
```
1JUb1yNFH6wjGekRUW6Dfgyg4J4h6wKKdF
```
**Monero (XMR):**
```
46uV2fMZT3EWkBrGUgszJCcbqFqEvqrB4bZBJwsbx7yA8e2WBakXzJSUK8aqT4GoqERzbg4oKT2SiPeCgjzVH6VpSQ5y7KQ
```
## License
Picobuf is [MIT licensed](https://gitlab.com/basedwon/picobuf/-/blob/master/LICENSE).