Type-safe conversion and manipulation of YDB values and types. Encode/decode between native JS and YDB, with full support for primitives and complex types.
npm install @ydbjs/valueThe @ydbjs/value package provides utilities for working with YDB values and types in JavaScript/TypeScript. It includes classes and functions for encoding, decoding, and converting YDB values to and from native JavaScript types.
- Support for all YDB primitive types (e.g., BOOL, INT32, STRING, etc.)
- Support for complex types like List, Tuple, Struct, Dict, and Optional
- Conversion between YDB values and native JavaScript types
- Type-safe handling of YDB values with TypeScript
Install the package using npm:
``sh`
npm install @ydbjs/value@alpha
`ts`
import { fromJs } from '@ydbjs/value';
const ydbValue = fromJs({ key: 'value' });
`ts`
import { toJs } from '@ydbjs/value';
const jsValue = toJs(ydbValue);
`ts`
import { Int32Type } from '@ydbjs/value/primitive';
const intType = new Int32Type();
Conversion from JavaScript values to YDB server values occurs in three stages:
1. JavaScript value → Value (from @ydbjs/value)
Use the fromJs function to convert a native JavaScript value into a Value instance from the @ydbjs/value package. This step infers the YDB type and wraps the value in a type-safe class.
2. Value → Ydb.Value (protobuf)
Call the .encode() method on the Value instance to produce a protobuf-compatible Ydb.Value object. This object can be sent to the YDB server via gRPC or other supported protocols.
3. Ydb.Value → YDB server
The encoded Ydb.Value is transmitted to the YDB server as part of your request payload.
This multi-stage process ensures type safety, correct serialization, and compatibility with the YDB protocol.
The conversion between JavaScript and YDB types in @ydbjs/value is automatic and based on the structure and type of the input value. Below is a summary of how different JavaScript values are converted:
| JavaScript Value | YDB Type/Class | Notes |
|-------------------------|---------------------|-------|
| boolean | Bool | |number
| (integer) | Int32 | Uses Int32 for integers |number
| (float) | Double | Uses Double for non-integers |bigint
| | Int64 | |string
| | Text | |Date
| | Datetime | |Uint8Array
| | Bytes | |null
| | Null | |Array
| | List | Elements converted recursively. Special handling for arrays of objects, see below |Set
| | Tuple | Elements converted recursively |Map
| | Dict | Keys and values converted recursively |
| Plain object | Struct | Each property converted recursively |
If you pass an array of objects with different sets of fields, the converter will automatically create a unified Struct type containing all fields from all objects. Missing fields in each object will be set as Optional (nullable) in the resulting YDB Struct. This allows you to pass heterogeneous arrays of objects and have them represented as a single List of Structs in YDB.
#### Example
`js`
fromJs([
{id: 1, name: 'Alice'},
{id: 2, age: 30}
])
This will produce a YDB List where each element is a Struct with fields: , name, and age. Fields not present in an object will be set to null (Optional).
- All type and value classes (e.g., Struct, List, Dict, Tuple, Null, Optional, Primitive) are exported for advanced use.fromJs
- Conversion is two-way: use for JS → YDB and toJs for YDB → JS.
---
- printYdbValue(value: YdbValue): string — Returns a human-readable string representation of a YDB value.
---
`ts
import { fromJs, toJs } from '@ydbjs/value';
const intValue = fromJs(42);
const boolValue = fromJs(true);
const stringValue = fromJs('hello');
console.log(toJs(intValue)); // 42
console.log(toJs(boolValue)); // true
console.log(toJs(stringValue)); // 'hello'
`
`ts
import { fromJs, toJs } from '@ydbjs/value';
// List of integers
const ydbList = fromJs([1, 2, 3]);
console.log(toJs(ydbList)); // [1, 2, 3]
// Dictionary (map) from string to int
const ydbDict = fromJs({ a: 1, b: 2 });
console.log(toJs(ydbDict)); // { a: 1, b: 2 }
// Optional value
const ydbOptional = fromJs(null);
console.log(toJs(ydbOptional)); // null
`
`ts
import { fromJs, toJs } from '@ydbjs/value';
// Struct
const ydbStruct = fromJs({ id: 123, name: 'Alice' });
console.log(toJs(ydbStruct)); // { id: 123, name: 'Alice' }
// Tuple (represented as array)
const ydbTuple = fromJs([42, 'foo']);
console.log(toJs(ydbTuple)); // [42, 'foo']
`
---
The conversion between JavaScript and YDB values is handled by the fromJs and toJs functions:
- fromJs(jsValue) encodes a native JavaScript value into a YDB value. The type is inferred automatically from the value structure.toJs(ydbValue)
- decodes a YDB value back to a native JavaScript value, preserving structure and types.
YDB types are represented internally and are inferred automatically based on the structure of the provided value. For complex or nested structures, conversion is also performed automatically.
`sh`
npm run build
`sh``
npm test
This project is licensed under the Apache 2.0 License.