@ydbjs/value

The @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.

Features

• 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

Installation

Install the package using npm:

npm install @ydbjs/value

Usage

Encoding JavaScript Values to YDB Values

import { fromJs } from '@ydbjs/value'
const ydbValue = fromJs({ key: 'value' })

Decoding YDB Values to JavaScript

import { toJs } from '@ydbjs/value'
const jsValue = toJs(ydbValue)

Working with YDB Types

import { Int32Type } from '@ydbjs/value/primitive'
const intType = new Int32Type()

Conversion Stages

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.

Type Conversion Details

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 |

Special Handling for Arrays of Objects

If you pass an array of objects, the converter creates a unified Struct type containing the union of fields from all objects and wraps every field in Optional. Missing fields become null. This allows heterogeneous arrays of objects to be represented as a single List of Structs in YDB.

Example

fromJs([
  { id: 1, name: 'Alice' },
  { id: 2, age: 30 },
])

This will produce a YDB List where each element is a Struct with fields: id, name, and age. Fields not present in an object will be set to null (Optional).

NOT NULL columns

Because fromJs always wraps struct fields in Optional, the resulting type does not match NOT NULL columns on the server side — the query will fail with Can't set NULL or optional value to not null column. fromJs cannot know the target schema, so if you need pinned non-nullable types, construct values explicitly:

import { List } from '@ydbjs/value/list'
import { Struct } from '@ydbjs/value/struct'
import { Text, Uint8, Bytes } from '@ydbjs/value/primitive'

const rows = new List(
  new Struct({ key: new Text('a'), partNumber: new Uint8(0), data: new Bytes(buf) })
)

Or build a StructType once and pass it to new Struct(obj, type) to pin field types across rows.

Utility Exports

• All type and value classes (e.g., Struct, List, Dict, Tuple, Null, Optional, Primitive) are exported for advanced use.
• Conversion is two-way: use fromJs for JS → YDB and toJs for YDB → JS.

Additional Utility Functions

• printYdbValue(value: YdbValue): string — Returns a human-readable string representation of a YDB value.

More Examples

Primitives

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'

Container Types (List, Dict, Tuple, Optional)

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

Complex Values (Struct, Tuple)

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']

Conversion Mechanism

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.

Development

Building the Package

npm run build

Running Tests

npm test

License

This project is licensed under the Apache 2.0 License.

Links

• YDB Documentation
• GitHub Repository
• Issues