Research
Security News
Quasar RAT Disguised as an npm Package for Detecting Vulnerabilities in Ethereum Smart Contracts
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
@solana/options
Advanced tools
Managing and serializing Rust-like Option types in JavaScript
This package allows us to manage and serialize Rust-like Option types in JavaScript. It can be used standalone, but it is also exported as part of the Solana JavaScript SDK @solana/web3.js@next
.
This package is also part of the @solana/codecs
package which acts as an entry point for all codec packages as well as for their documentation.
In Rust, we define optional values as an Option<T>
type which can either be Some(T)
or None
. This is usually represented as T | null
in the JavaScript world. The issue with this approach is it doesn't work with nested options. For instance, an Option<Option<T>>
in Rust would become a T | null | null
in JavaScript which is equivalent to T | null
. That means, there is no way for us to represent the Some(None)
value in JavaScript or any other nested option.
To solve this issue, this library provides an Option<T>
union type that works very similarly to the Rust Option<T>
type. It is defined as follows:
type Option<T> = Some<T> | None;
type Some<T> = { __option: 'Some'; value: T };
type None = { __option: 'None' };
To improve the developer experience, helper functions are available to help you create options. The type T
of the option can either be inferred by TypeScript or explicitly provided.
// Create an option with a value.
some('Hello World');
some<number | string>(123);
// Create an empty option.
none();
none<number | string>();
This library also provides helper functions to help us identify and manage Option
types.
For instance, you can use the isSome
and isNone
type guards to check whether a given Option
is of the desired type.
isSome(some('Hello World')); // true
isSome(none()); // false
isNone(some('Hello World')); // false
isNone(none()); // true
If you are given a type T | null
, you may also use the wrapNullable
helper function to transform it into an Option<T>
type.
wrapNullable('Hello world'); // Some<string>
wrapNullable(null); // None
Several helpers are available to help you unwrap your options and access their potential value. For instance, the unwrapOption
function transforms an Option<T>
type into T
if the value exits and null
otherwise.
unwrapOption(some('Hello World')); // "Hello World"
unwrapOption(none()); // null
If null
isn’t the value you want to use for None
options, you may provide a custom fallback function as the second argument. Its return value will be assigned to None
options.
unwrapOption(some('Hello World'), () => 'Default'); // "Hello World"
unwrapOption(none(), () => 'Default'); // "Default"
Note that this unwrapOption
function does not recursively unwrap nested options. You may use the unwrapOptionRecursively
function for that purpose instead.
unwrapOptionRecursively(some(some(some('Hello World')))); // "Hello World"
unwrapOptionRecursively(some(some(none<string>()))); // null
The unwrapOptionRecursively
function also walks any object and array it encounters and recursively unwraps any option it identifies in its journey without mutating any object or array.
unwrapOptionRecursively({
a: 'hello',
b: none(),
c: [{ c1: some(42) }, { c2: none() }],
});
// { a: "hello", b: null, c: [{ c1: 42 }, { c2: null }] }
The unwrapOptionRecursively
also accepts a fallback function as a second argument to provide custom values for None
options.
unwrapOptionRecursively(
{
a: 'hello',
b: none(),
c: [{ c1: some(42) }, { c2: none() }],
},
() => 'Default',
);
// { a: "hello", b: "Default", c: [{ c1: 42 }, { c2: "Default" }] }
The getOptionCodec
function behaves exactly the same as the getNullableCodec
except that it encodes Option<T>
types instead of T | null
types.
Namely, it accepts a codec of type T
and returns a codec of type Option<T>
. Note that, when encoding, T
or null
may also be provided directly as input and will be interpreted as Some(T)
or None
respectively. However, when decoding, the output will always be an Option<T>
type.
It stores whether or not the item exists as a boolean prefix using a u8
by default.
const stringCodec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
getOptionCodec(stringCodec).encode('Hi');
getOptionCodec(stringCodec).encode(some('Hi'));
// 0x01020000004869
// | | └-- utf8 string content ("Hi").
// | └-- u32 string prefix (2 characters).
// └-- 1-byte prefix (Some).
getOptionCodec(stringCodec).encode(null);
getOptionCodec(stringCodec).encode(none());
// 0x00
// └-- 1-byte prefix (None).
You may provide a number codec as the prefix
option of the getOptionCodec
function to configure how to store the boolean prefix.
const u32OptionStringCodec = getOptionCodec(stringCodec, {
prefix: getU32Codec(),
});
u32OptionStringCodec.encode(some('Hi'));
// 0x01000000020000004869
// └------┘ 4-byte prefix (Some).
u32OptionStringCodec.encode(none());
// 0x00000000
// └------┘ 4-byte prefix (None).
Additionally, if the item is a FixedSizeCodec
, you may set the noneValue
option to "zeroes"
to also make the returned Option codec a FixedSizeCodec
. To do so, it will pad None
values with zeroes to match the length of existing values.
const codec = getOptionCodec(
fixCodecSize(getUtf8Codec(), 8), // Only works with fixed-size items.
{ noneValue: 'zeroes' },
);
codec.encode(some('Hi'));
// 0x014869000000000000
// | └-- 8-byte utf8 string content ("Hi").
// └-- 1-byte prefix (Some).
codec.encode(none());
// 0x000000000000000000
// | └-- 8-byte of padding to make a fixed-size codec.
// └-- 1-byte prefix (None).
The noneValue
option can also be set to an explicit byte array to use as the padding for None
values. Note that, in this case, the returned codec will not be a FixedSizeCodec
as the byte array representing None
values may be of any length.
const codec = getOptionCodec(getUtf8Codec(), {
noneValue: new Uint8Array([255]), // 0xff means None.
});
codec.encode(some('Hi'));
// 0x014869
// | └-- 2-byte utf8 string content ("Hi").
// └-- 1-byte prefix (Some).
codec.encode(none());
// 0x00ff
// | └-- 1-byte representing None (0xff).
// └-- 1-byte prefix (None).
Last but not least, the prefix
option of the getOptionCodec
function can also be set to null
, meaning no prefix will be used to determine whether the item exists. In this case, the codec will rely on the noneValue
option to determine whether the item is None
.
const codecWithZeroNoneValue = getOptionCodec(getU16Codec(), {
noneValue: 'zeroes', // 0x0000 means None.
prefix: null,
});
codecWithZeroNoneValue.encode(some(42)); // 0x2a00
codecWithZeroNoneValue.encode(none()); // 0x0000
const codecWithCustomNoneValue = getOptionCodec(getU16Codec(), {
noneValue: new Uint8Array([255]), // 0xff means None.
prefix: null,
});
codecWithCustomNoneValue.encode(some(42)); // 0x2a00
codecWithCustomNoneValue.encode(none()); // 0xff
Finally, note that if prefix
is set to null
and no noneValue
is provided, the codec assume that the item exists if and only if some remaining bytes are available to decode. This could be useful to describe data structures that may or may not have additional data to the end of the buffer.
const codec = getOptionCodec(getU16Codec(), { prefix: null });
codec.encode(some(42)); // 0x2a00
codec.encode(none()); // Encodes nothing.
codec.decode(new Uint8Array([42, 0])); // some(42)
codec.decode(new Uint8Array([])); // none()
To recap, here are all the possible configurations of the getOptionCodec
function, using a u16
codec as an example.
encode(some(42)) / encode(none()) | No noneValue (default) | noneValue: "zeroes" | Custom noneValue (0xff ) |
---|---|---|---|
u8 prefix (default) | 0x012a00 / 0x00 | 0x012a00 / 0x000000 | 0x012a00 / 0x00ff |
Custom prefix (u16 ) | 0x01002a00 / 0x0000 | 0x01002a00 / 0x00000000 | 0x01002a00 / 0x0000ff |
No prefix | 0x2a00 / 0x | 0x2a00 / 0x0000 | 0x2a00 / 0xff |
Separate getOptionEncoder
and getOptionDecoder
functions are also available.
const bytes = getOptionEncoder(getU32Encoder()).encode(some(42));
const value = getOptionDecoder(getU32Decoder()).decode(bytes);
To read more about the available codecs and how to use them, check out the documentation of the main @solana/codecs
package.
FAQs
Managing and serializing Rust-like Option types in JavaScript
We found that @solana/options demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 14 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.