@solana/options 6.3.1 → 6.3.2-canary-20260313112147

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/options",
-  "version": "6.3.1",
+  "version": "6.3.2-canary-20260313112147",
   "description": "Managing and serializing Rust-like Option types in JavaScript",
   "homepage": "https://www.solanakit.com/api#solanaoptions",
   "exports": {
@@ -33,7 +33,8 @@
   "types": "./dist/types/index.d.ts",
   "type": "commonjs",
   "files": [
-    "./dist/"
+    "./dist/",
+    "./src/"
   ],
   "sideEffects": false,
   "keywords": [
@@ -55,11 +56,11 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/codecs-core": "6.3.1",
-    "@solana/codecs-data-structures": "6.3.1",
-    "@solana/codecs-numbers": "6.3.1",
-    "@solana/codecs-strings": "6.3.1",
-    "@solana/errors": "6.3.1"
+    "@solana/codecs-core": "6.3.2-canary-20260313112147",
+    "@solana/codecs-data-structures": "6.3.2-canary-20260313112147",
+    "@solana/codecs-numbers": "6.3.2-canary-20260313112147",
+    "@solana/codecs-strings": "6.3.2-canary-20260313112147",
+    "@solana/errors": "6.3.2-canary-20260313112147"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 Kit
+ * [`@solana/kit`](https://github.com/anza-xyz/kit/tree/main/packages/kit).
+ *
+ * This package is also part of the [`@solana/codecs` package](https://github.com/anza-xyz/kit/tree/main/packages/codecs)
+ * which acts as an entry point for all codec packages as well as for their documentation.
+ *
+ * @packageDocumentation
+ */
+export * from './option';
+export * from './option-codec';
+export * from './unwrap-option';
+export * from './unwrap-option-recursively';

package/src/option-codec.ts

@@ -0,0 +1,398 @@
+import {
+    assertIsFixedSize,
+    Codec,
+    combineCodec,
+    containsBytes,
+    Decoder,
+    Encoder,
+    fixDecoderSize,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    fixEncoderSize,
+    ReadonlyUint8Array,
+    transformDecoder,
+    transformEncoder,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '@solana/codecs-core';
+import {
+    getBooleanDecoder,
+    getBooleanEncoder,
+    getConstantDecoder,
+    getConstantEncoder,
+    getTupleDecoder,
+    getTupleEncoder,
+    getUnionDecoder,
+    getUnionEncoder,
+    getUnitDecoder,
+    getUnitEncoder,
+} from '@solana/codecs-data-structures';
+import {
+    FixedSizeNumberCodec,
+    FixedSizeNumberDecoder,
+    FixedSizeNumberEncoder,
+    getU8Decoder,
+    getU8Encoder,
+    NumberCodec,
+    NumberDecoder,
+    NumberEncoder,
+} from '@solana/codecs-numbers';
+
+import { isOption, isSome, None, none, Option, OptionOrNullable, Some, some } from './option';
+import { wrapNullable } from './unwrap-option';
+
+/**
+ * Defines the configuration options for {@link Option} codecs.
+ *
+ * The `getOptionCodec` function behaves similarly to {@link getNullableCodec}
+ * but encodes `Option<T>` types instead of `T | null` types.
+ *
+ * This configuration controls how {@link None} values are encoded and how presence
+ * is determined when decoding.
+ *
+ * @typeParam TPrefix - A number codec, encoder, or decoder used as the presence prefix.
+ *
+ * @see {@link getOptionEncoder}
+ * @see {@link getOptionDecoder}
+ * @see {@link getOptionCodec}
+ */
+export type OptionCodecConfig<TPrefix extends NumberCodec | NumberDecoder | NumberEncoder> = {
+    /**
+     * Specifies how {@link None} values are represented in the encoded data.
+     *
+     * - By default, {@link None} values are omitted from encoding.
+     * - `'zeroes'`: The bytes allocated for the value are filled with zeroes. This requires a fixed-size codec for the item.
+     * - Custom byte array: {@link None} values are replaced with a predefined byte sequence. This results in a variable-size codec.
+     *
+     * @defaultValue No explicit `noneValue` is used; {@link None} values are omitted.
+     */
+    noneValue?: ReadonlyUint8Array | 'zeroes';
+
+    /**
+     * The presence prefix used to distinguish between {@link None} and present values.
+     *
+     * - By default, a `u8` prefix is used (`0 = None`, `1 = Some`).
+     * - Custom number codec: Allows defining a different number size for the prefix.
+     * - `null`: No prefix is used; `noneValue` (if provided) determines {@link None}.
+     *   If no `noneValue` is set, {@link None} is identified by the absence of bytes.
+     *
+     * @defaultValue `u8` prefix.
+     */
+    prefix?: TPrefix | null;
+};
+
+/**
+ * Returns an encoder for optional values using the {@link Option} type.
+ *
+ * This encoder serializes an {@link OptionOrNullable} value using a configurable approach:
+ * - By default, a `u8` prefix is used (`0 = None`, `1 = Some`). This can be customized or disabled.
+ * - If `noneValue: 'zeroes'` is set, {@link None} values are encoded as zeroes.
+ * - If `noneValue` is a byte array, {@link None} values are replaced with the provided constant.
+ *
+ * Unlike {@link getNullableEncoder}, this encoder accepts both {@link Option} and {@link Nullable} values.
+ *
+ * For more details, see {@link getOptionCodec}.
+ *
+ * @typeParam TFrom - The type of the main value being encoded.
+ *
+ * @param item - The encoder for the value that may be present.
+ * @param config - Configuration options for encoding optional values.
+ * @returns A `FixedSizeEncoder` or `VariableSizeEncoder` for encoding option values.
+ *
+ * @example
+ * Encoding an optional string.
+ * ```ts
+ * const stringCodec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
+ * const encoder = getOptionEncoder(stringCodec);
+ *
+ * encoder.encode(some('Hi'));
+ * encoder.encode('Hi');
+ * // 0x01020000004869
+ * //   | |       └-- utf8 string content ("Hi").
+ * //   | └-- u32 string prefix (2 characters).
+ * //   └-- 1-byte prefix (Some).
+ *
+ * encoder.encode(none());
+ * encoder.encode(null);
+ * // 0x00
+ * //   └-- 1-byte prefix (None).
+ * ```
+ *
+ * @see {@link getOptionCodec}
+ */
+export function getOptionEncoder<TFrom, TSize extends number>(
+    item: FixedSizeEncoder<TFrom, TSize>,
+    config: OptionCodecConfig<NumberEncoder> & { noneValue: 'zeroes'; prefix: null },
+): FixedSizeEncoder<OptionOrNullable<TFrom>, TSize>;
+export function getOptionEncoder<TFrom>(
+    item: FixedSizeEncoder<TFrom>,
+    config: OptionCodecConfig<FixedSizeNumberEncoder> & { noneValue: 'zeroes' },
+): FixedSizeEncoder<OptionOrNullable<TFrom>>;
+export function getOptionEncoder<TFrom>(
+    item: FixedSizeEncoder<TFrom>,
+    config: OptionCodecConfig<NumberEncoder> & { noneValue: 'zeroes' },
+): VariableSizeEncoder<OptionOrNullable<TFrom>>;
+export function getOptionEncoder<TFrom>(
+    item: Encoder<TFrom>,
+    config?: OptionCodecConfig<NumberEncoder> & { noneValue?: ReadonlyUint8Array },
+): VariableSizeEncoder<OptionOrNullable<TFrom>>;
+export function getOptionEncoder<TFrom>(
+    item: Encoder<TFrom>,
+    config: OptionCodecConfig<NumberEncoder> = {},
+): Encoder<OptionOrNullable<TFrom>> {
+    const prefix = (() => {
+        if (config.prefix === null) {
+            return transformEncoder(getUnitEncoder(), (_boolean: boolean) => undefined);
+        }
+        return getBooleanEncoder({ size: config.prefix ?? getU8Encoder() });
+    })();
+    const noneValue = (() => {
+        if (config.noneValue === 'zeroes') {
+            assertIsFixedSize(item);
+            return fixEncoderSize(getUnitEncoder(), item.fixedSize);
+        }
+        if (!config.noneValue) {
+            return getUnitEncoder();
+        }
+        return getConstantEncoder(config.noneValue);
+    })();
+
+    return getUnionEncoder(
+        [
+            transformEncoder(getTupleEncoder([prefix, noneValue]), (_value: None | null): [boolean, void] => [
+                false,
+                undefined,
+            ]),
+            transformEncoder(getTupleEncoder([prefix, item]), (value: Some<TFrom> | TFrom): [boolean, TFrom] => [
+                true,
+                isOption(value) && isSome(value) ? value.value : value,
+            ]),
+        ],
+        variant => {
+            const option = isOption<TFrom>(variant) ? variant : wrapNullable(variant);
+            return Number(isSome(option));
+        },
+    );
+}
+
+/**
+ * Returns a decoder for optional values using the {@link Option} type.
+ *
+ * This decoder deserializes an `Option<T>` value using a configurable approach:
+ * - By default, a `u8` prefix is used (`0 = None`, `1 = Some`). This can be customized or disabled.
+ * - If `noneValue: 'zeroes'` is set, `None` values are identified by zeroes.
+ * - If `noneValue` is a byte array, `None` values match the provided constant.
+ *
+ * Unlike {@link getNullableDecoder}, this decoder always outputs an {@link Option} type.
+ *
+ * For more details, see {@link getOptionCodec}.
+ *
+ * @typeParam TTo - The type of the main value being decoded.
+ *
+ * @param item - The decoder for the value that may be present.
+ * @param config - Configuration options for decoding optional values.
+ * @returns A `FixedSizeDecoder` or `VariableSizeDecoder` for decoding option values.
+ *
+ * @example
+ * Decoding an optional string with a size prefix.
+ * ```ts
+ * const stringCodec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
+ * const decoder = getOptionDecoder(stringCodec);
+ *
+ * decoder.decode(new Uint8Array([0x01, 0x02, 0x00, 0x00, 0x00, 0x48, 0x69]));
+ * // some('Hi')
+ *
+ * decoder.decode(new Uint8Array([0x00]));
+ * // none()
+ * ```
+ *
+ * @see {@link getOptionCodec}
+ */
+export function getOptionDecoder<TTo, TSize extends number>(
+    item: FixedSizeDecoder<TTo, TSize>,
+    config: OptionCodecConfig<NumberDecoder> & { noneValue: 'zeroes'; prefix: null },
+): FixedSizeDecoder<Option<TTo>, TSize>;
+export function getOptionDecoder<TTo>(
+    item: FixedSizeDecoder<TTo>,
+    config: OptionCodecConfig<FixedSizeNumberDecoder> & { noneValue: 'zeroes' },
+): FixedSizeDecoder<Option<TTo>>;
+export function getOptionDecoder<TTo>(
+    item: FixedSizeDecoder<TTo>,
+    config: OptionCodecConfig<NumberDecoder> & { noneValue: 'zeroes' },
+): VariableSizeDecoder<Option<TTo>>;
+export function getOptionDecoder<TTo>(
+    item: Decoder<TTo>,
+    config?: OptionCodecConfig<NumberDecoder> & { noneValue?: ReadonlyUint8Array },
+): VariableSizeDecoder<Option<TTo>>;
+export function getOptionDecoder<TTo>(
+    item: Decoder<TTo>,
+    config: OptionCodecConfig<NumberDecoder> = {},
+): Decoder<Option<TTo>> {
+    const prefix = (() => {
+        if (config.prefix === null) {
+            return transformDecoder(getUnitDecoder(), () => false);
+        }
+        return getBooleanDecoder({ size: config.prefix ?? getU8Decoder() });
+    })();
+    const noneValue = (() => {
+        if (config.noneValue === 'zeroes') {
+            assertIsFixedSize(item);
+            return fixDecoderSize(getUnitDecoder(), item.fixedSize);
+        }
+        if (!config.noneValue) {
+            return getUnitDecoder();
+        }
+        return getConstantDecoder(config.noneValue);
+    })();
+
+    return getUnionDecoder(
+        [
+            transformDecoder(getTupleDecoder([prefix, noneValue]), () => none<TTo>()),
+            transformDecoder(getTupleDecoder([prefix, item]), ([, value]) => some(value)),
+        ],
+        (bytes, offset) => {
+            if (config.prefix === null && !config.noneValue) {
+                return Number(offset < bytes.length);
+            }
+            if (config.prefix === null && config.noneValue != null) {
+                const zeroValue =
+                    config.noneValue === 'zeroes' ? new Uint8Array(noneValue.fixedSize).fill(0) : config.noneValue;
+                return containsBytes(bytes, zeroValue, offset) ? 0 : 1;
+            }
+            return Number(prefix.read(bytes, offset)[0]);
+        },
+    );
+}
+
+/**
+ * Returns a codec for encoding and decoding optional values using the {@link Option} type.
+ *
+ * This codec serializes and deserializes `Option<T>` values using a configurable approach:
+ * - By default, a `u8` prefix is used (`0 = None`, `1 = Some`).
+ * - If `noneValue: 'zeroes'` is set, `None` values are encoded/decoded as zeroes.
+ * - If `noneValue` is a byte array, `None` values are represented by the provided constant.
+ * - If `prefix: null` is set, the codec determines `None` values solely from `noneValue` or the presence of bytes.
+ *
+ * For more details on the configuration options, see {@link OptionCodecConfig}.
+ *
+ * Note that this behaves similarly to {@link getNullableCodec}, except it
+ * encodes {@link OptionOrNullable} values and decodes {@link Option} values.
+ *
+ * @typeParam TFrom - The type of the main value being encoded.
+ * @typeParam TTo - The type of the main value being decoded.
+ *
+ * @param item - The codec for the value that may be present.
+ * @param config - Configuration options for encoding and decoding option values.
+ * @returns A `FixedSizeCodec` or `VariableSizeCodec` for encoding and decoding option values.
+ *
+ * @example
+ * Encoding and decoding an optional string with a size prefix.
+ * ```ts
+ * const stringCodec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
+ * const codec = getOptionCodec(stringCodec);
+ *
+ * const someBytes = codec.encode(some('Hi'));
+ * // 0x01020000004869
+ * //   | |       └-- utf8 string content ("Hi").
+ * //   | └-- u32 string prefix (2 characters).
+ * //   └-- 1-byte prefix (Some).
+ *
+ * const noneBytes = codec.encode(none());
+ * // 0x00
+ * //   └-- 1-byte prefix (None).
+ *
+ * codec.decode(someBytes); // some('Hi')
+ * codec.decode(noneBytes); // none()
+ * ```
+ *
+ * @example
+ * Encoding nullable values.
+ * ```ts
+ * const stringCodec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
+ * const codec = getOptionCodec(stringCodec);
+ *
+ * const someBytes = codec.encode('Hi'); // 0x01020000004869
+ * const noneBytes = codec.encode(null); // 0x00
+ *
+ * codec.decode(someBytes); // some('Hi')
+ * codec.decode(noneBytes); // none()
+ * ```
+ *
+ * @example
+ * Encoding and decoding an optional number with a fixed size.
+ * ```ts
+ * const codec = getOptionCodec(getU16Codec(), { noneValue: 'zeroes' });
+ *
+ * const someBytes = codec.encode(some(42)); // 0x012a00
+ * const noneBytes = codec.encode(none());   // 0x000000
+ *
+ * codec.decode(someBytes); // some(42)
+ * codec.decode(noneBytes); // none()
+ * ```
+ *
+ * @example
+ * Encoding and decoding {@link None} values with a custom byte sequence and no prefix.
+ * ```ts
+ * const codec = getOptionCodec(getU16Codec(), {
+ *   noneValue: new Uint8Array([0xff, 0xff]),
+ *   prefix: null,
+ * });
+ *
+ * const someBytes = codec.encode(some(42)); // 0x2a00
+ * const noneBytes = codec.encode(none());   // 0xffff
+ *
+ * codec.decode(someBytes); // some(42)
+ * codec.decode(noneBytes); // none()
+ * ```
+ *
+ * @example
+ * Identifying {@link None} values by the absence of bytes.
+ * ```ts
+ * const codec = getOptionCodec(getU16Codec(), { prefix: null });
+ *
+ * const someBytes = codec.encode(some(42)); // 0x2a00
+ * const noneBytes = codec.encode(none());   // new Uint8Array(0)
+ *
+ * codec.decode(someBytes); // some(42)
+ * codec.decode(noneBytes); // none()
+ * ```
+ *
+ * @remarks
+ * Separate {@link getOptionEncoder} and {@link getOptionDecoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getOptionEncoder(getU32Encoder()).encode(some(42));
+ * const value = getOptionDecoder(getU32Decoder()).decode(bytes);
+ * ```
+ *
+ * @see {@link getOptionEncoder}
+ * @see {@link getOptionDecoder}
+ */
+export function getOptionCodec<TFrom, TTo extends TFrom, TSize extends number>(
+    item: FixedSizeCodec<TFrom, TTo, TSize>,
+    config: OptionCodecConfig<NumberCodec> & { noneValue: 'zeroes'; prefix: null },
+): FixedSizeCodec<OptionOrNullable<TFrom>, Option<TTo>, TSize>;
+export function getOptionCodec<TFrom, TTo extends TFrom = TFrom>(
+    item: FixedSizeCodec<TFrom, TTo>,
+    config: OptionCodecConfig<FixedSizeNumberCodec> & { noneValue: 'zeroes' },
+): FixedSizeCodec<OptionOrNullable<TFrom>, Option<TTo>>;
+export function getOptionCodec<TFrom, TTo extends TFrom = TFrom>(
+    item: FixedSizeCodec<TFrom, TTo>,
+    config: OptionCodecConfig<NumberCodec> & { noneValue: 'zeroes' },
+): VariableSizeCodec<OptionOrNullable<TFrom>, Option<TTo>>;
+export function getOptionCodec<TFrom, TTo extends TFrom = TFrom>(
+    item: Codec<TFrom, TTo>,
+    config?: OptionCodecConfig<NumberCodec> & { noneValue?: ReadonlyUint8Array },
+): VariableSizeCodec<OptionOrNullable<TFrom>, Option<TTo>>;
+export function getOptionCodec<TFrom, TTo extends TFrom = TFrom>(
+    item: Codec<TFrom, TTo>,
+    config: OptionCodecConfig<NumberCodec> = {},
+): Codec<OptionOrNullable<TFrom>, Option<TTo>> {
+    type ConfigCast = OptionCodecConfig<NumberCodec> & { noneValue?: ReadonlyUint8Array };
+    return combineCodec(
+        getOptionEncoder<TFrom>(item, config as ConfigCast),
+        getOptionDecoder<TTo>(item, config as ConfigCast),
+    );
+}

package/src/option.ts

@@ -0,0 +1,238 @@
+/**
+ * An implementation of the Rust `Option<T>` type in JavaScript.
+ *
+ * In Rust, optional values are represented using `Option<T>`, which can be either:
+ * - `Some(T)`, indicating a present value.
+ * - `None`, indicating the absence of a value.
+ *
+ * In JavaScript, this is typically represented as `T | null`. However, this approach fails with nested options.
+ * For example, `Option<Option<T>>` in Rust would translate to `T | null | null` in JavaScript, which is equivalent to `T | null`.
+ * This means there is no way to differentiate between `Some(None)` and `None`, making nested options impossible.
+ *
+ * This `Option` type helps solve this by mirroring Rust’s `Option<T>` type.
+ *
+ * ```ts
+ * type Option<T> = Some<T> | None;
+ * type Some<T> = { __option: 'Some'; value: T };
+ * type None = { __option: 'None' };
+ * ```
+ *
+ * @typeParam T - The type of the contained value.
+ *
+ * @example
+ * Here's how you can create `Option` values.
+ *
+ * To improve developer experience, helper functions are available.
+ * TypeScript can infer the type of `T` or it can be explicitly provided.
+ *
+ * ```ts
+ * // Create an option with a value.
+ * some('Hello World');
+ * some<number | string>(123);
+ *
+ * // Create an empty option.
+ * none();
+ * none<number | string>();
+ * ```
+ *
+ * @see {@link Some}
+ * @see {@link None}
+ * @see {@link some}
+ * @see {@link none}
+ */
+export type Option<T> = None | Some<T>;
+
+/**
+ * A flexible type that allows working with {@link Option} values or nullable values.
+ *
+ * It defines a looser type that can be used when encoding {@link Option | Options}.
+ * This allows us to pass `null` or the nested value directly whilst still
+ * supporting the Option type for use-cases that need more type safety.
+ *
+ * @typeParam T - The type of the contained value.
+ *
+ * @example
+ * Accepting both `Option<T>` and `T | null` as input.
+ * ```ts
+ * function double(value: OptionOrNullable<number>) {
+ *   const option = isOption(value) ? value : wrapNullable(value);
+ *   return isSome(option) ? option.value * 2 : 'No value';
+ * }
+ *
+ * double(42);       // 84
+ * double(some(21)); // 42
+ * double(none());   // "No value"
+ * double(null);     // "No value"
+ * ```
+ *
+ * @see {@link Option}
+ * @see {@link isOption}
+ * @see {@link wrapNullable}
+ */
+export type OptionOrNullable<T> = Option<T> | T | null;
+
+/**
+ * Represents an {@link Option} that contains a value.
+ *
+ * This type mirrors Rust’s `Some(T)`, indicating that a value is present.
+ *
+ * For more details, see {@link Option}.
+ *
+ * @typeParam T - The type of the contained value.
+ *
+ * @example
+ * Creating a `Some` value.
+ * ```ts
+ * const value = some(42);
+ * isSome(value); // true
+ * isNone(value); // false
+ * ```
+ *
+ * @see {@link Option}
+ * @see {@link some}
+ * @see {@link isSome}
+ */
+export type Some<T> = Readonly<{ __option: 'Some'; value: T }>;
+
+/**
+ * Represents an {@link Option} that contains no value.
+ *
+ * This type mirrors Rust’s `None`, indicating the absence of a value.
+ *
+ * For more details, see {@link Option}.
+ *
+ * @example
+ * Creating a `None` value.
+ * ```ts
+ * const empty = none();
+ * isNone(empty); // true
+ * isSome(empty); // false
+ * ```
+ *
+ * @see {@link Option}
+ * @see {@link none}
+ * @see {@link isNone}
+ */
+export type None = Readonly<{ __option: 'None' }>;
+
+/**
+ * Creates a new {@link Option} that contains a value.
+ *
+ * This function explicitly wraps a value in an {@link Option} type.
+ *
+ * @typeParam T - The type of the contained value.
+ *
+ * @param value - The value to wrap in an {@link Option}.
+ * @returns An {@link Option} containing the provided value.
+ *
+ * @example
+ * Wrapping a value in an `Option`.
+ * ```ts
+ * const option = some('Hello');
+ * option.value;     // "Hello"
+ * isOption(option); // true
+ * isSome(option);   // true
+ * isNone(option);   // false
+ * ```
+ *
+ * @see {@link Option}
+ * @see {@link Some}
+ */
+export const some = <T>(value: T): Option<T> => ({ __option: 'Some', value });
+
+/**
+ * Creates a new {@link Option} that contains no value.
+ *
+ * This function explicitly represents an absent value.
+ *
+ * @typeParam T - The type of the expected absent value.
+ *
+ * @returns An {@link Option} containing no value.
+ *
+ * @example
+ * Creating an empty `Option`.
+ * ```ts
+ * const empty = none<number>();
+ * isOption(empty); // true
+ * isSome(empty);   // false
+ * isNone(empty);   // true
+ * ```
+ *
+ * @see {@link Option}
+ * @see {@link None}
+ */
+export const none = <T>(): Option<T> => ({ __option: 'None' });
+
+/**
+ * Checks whether the given value is an {@link Option}.
+ *
+ * This function determines whether an input follows the `Option<T>` structure.
+ *
+ * @typeParam T - The type of the contained value.
+ *
+ * @param input - The value to check.
+ * @returns `true` if the value is an {@link Option}, `false` otherwise.
+ *
+ * @example
+ * Checking for `Option` values.
+ * ```ts
+ * isOption(some(42));        // true
+ * isOption(none());          // true
+ * isOption(42);              // false
+ * isOption(null);            // false
+ * isOption("anything else"); // false
+ * ```
+ *
+ * @see {@link Option}
+ */
+export const isOption = <T = unknown>(input: unknown): input is Option<T> =>
+    !!(
+        input &&
+        typeof input === 'object' &&
+        '__option' in input &&
+        ((input.__option === 'Some' && 'value' in input) || input.__option === 'None')
+    );
+
+/**
+ * Checks whether the given {@link Option} contains a value.
+ *
+ * This function acts as a type guard, ensuring the value is a {@link Some}.
+ *
+ * @typeParam T - The type of the contained value.
+ *
+ * @param option - The {@link Option} to check.
+ * @returns `true` if the option is a {@link Some}, `false` otherwise.
+ *
+ * @example
+ * Checking for `Some` values.
+ * ```ts
+ * isSome(some(42)); // true
+ * isSome(none());   // false
+ * ```
+ *
+ * @see {@link Option}
+ * @see {@link Some}
+ */
+export const isSome = <T>(option: Option<T>): option is Some<T> => option.__option === 'Some';
+
+/**
+ * Checks whether the given {@link Option} contains no value.
+ *
+ * This function acts as a type guard, ensuring the value is a {@link None}.
+ *
+ * @typeParam T - The type of the expected value.
+ *
+ * @param option - The {@link Option} to check.
+ * @returns `true` if the option is a {@link None}, `false` otherwise.
+ *
+ * @example
+ * Checking for `None` values.
+ * ```ts
+ * isNone(some(42)); // false
+ * isNone(none());   // true
+ * ```
+ *
+ * @see {@link Option}
+ * @see {@link None}
+ */
+export const isNone = <T>(option: Option<T>): option is None => option.__option === 'None';

package/src/unwrap-option-recursively.ts

@@ -0,0 +1,150 @@
+import { isOption, isSome, None, Some } from './option';
+
+/**
+ * Defines types that should not be recursively unwrapped.
+ *
+ * These types are preserved as-is when using {@link unwrapOptionRecursively}.
+ *
+ * @see {@link unwrapOptionRecursively}
+ */
+type UnUnwrappables =
+    | Date
+    | Int8Array
+    | Int16Array
+    | Int32Array
+    | Uint8Array
+    | Uint16Array
+    | Uint32Array
+    | bigint
+    | boolean
+    | number
+    | string
+    | symbol
+    | null
+    | undefined;
+
+/**
+ * A type that recursively unwraps nested {@link Option} types.
+ *
+ * This type resolves all nested {@link Option} values, ensuring
+ * that deeply wrapped values are properly extracted.
+ *
+ * - If `T` is an {@link Option}, it resolves to the contained value.
+ * - If `T` is a known primitive or immutable type, it remains unchanged.
+ * - If `T` is an object or array, it recursively unwraps any options found.
+ *
+ * The fallback type `U` (default: `null`) is used in place of `None` values.
+ *
+ * @typeParam T - The type to be unwrapped.
+ * @typeParam U - The fallback type for `None` values (defaults to `null`).
+ *
+ * @example
+ * Resolving nested `Option` types.
+ * ```ts
+ * UnwrappedOption<Some<Some<string>>>; // string
+ * UnwrappedOption<None>;               // null
+ * ```
+ *
+ * @example
+ * Resolving options inside objects and arrays.
+ * ```ts
+ * UnwrappedOption<{ a: Some<number>; b: None }>; // { a: number; b: null }
+ * UnwrappedOption<[Some<number>, None]>;         // [number, null]
+ * ```
+ *
+ * @see {@link unwrapOptionRecursively}
+ */
+export type UnwrappedOption<T, U = null> =
+    T extends Some<infer TValue>
+        ? UnwrappedOption<TValue, U>
+        : T extends None
+          ? U
+          : T extends UnUnwrappables
+            ? T
+            : T extends object
+              ? { [key in keyof T]: UnwrappedOption<T[key], U> }
+              : T extends Array<infer TItem>
+                ? Array<UnwrappedOption<TItem, U>>
+                : T;
+
+/**
+ * Recursively unwraps all nested {@link Option} types within a value.
+ *
+ * This function traverses a given value and removes all instances
+ * of {@link Option}, replacing them with their contained values.
+ *
+ * - If an {@link Option} is encountered, its value is extracted.
+ * - If an array or object is encountered, its elements are traversed recursively.
+ * - If `None` is encountered, it is replaced with the fallback value (default: `null`).
+ *
+ * @typeParam T - The type of the input value.
+ * @typeParam U - The fallback type for `None` values (defaults to `null`).
+ *
+ * @param input - The value to unwrap.
+ * @param fallback - A function that provides a fallback value for `None` options.
+ * @returns The recursively unwrapped value.
+ *
+ * @example
+ * Recursively unwrapping nested options.
+ * ```ts
+ * unwrapOptionRecursively(some(some('Hello World'))); // "Hello World"
+ * unwrapOptionRecursively(some(none<string>()));      // null
+ * ```
+ *
+ * @example
+ * Recursively unwrapping options inside objects and arrays.
+ * ```ts
+ * unwrapOptionRecursively({
+ *   a: 'hello',
+ *   b: none(),
+ *   c: [{ c1: some(42) }, { c2: none() }],
+ * });
+ * // { a: "hello", b: null, c: [{ c1: 42 }, { c2: null }] }
+ * ```
+ *
+ * @example
+ * Using a fallback value for `None` options.
+ * ```ts
+ * unwrapOptionRecursively(
+ *   {
+ *     a: 'hello',
+ *     b: none(),
+ *     c: [{ c1: some(42) }, { c2: none() }],
+ *   },
+ *   () => 'Default',
+ * );
+ * // { a: "hello", b: "Default", c: [{ c1: 42 }, { c2: "Default" }] }
+ * ```
+ *
+ * @remarks
+ * This function does not mutate objects or arrays.
+ *
+ * @see {@link Option}
+ * @see {@link UnwrappedOption}
+ */
+export function unwrapOptionRecursively<T>(input: T): UnwrappedOption<T>;
+export function unwrapOptionRecursively<T, U>(input: T, fallback: () => U): UnwrappedOption<T, U>;
+export function unwrapOptionRecursively<T, U = null>(input: T, fallback?: () => U): UnwrappedOption<T, U> {
+    // Types to bypass.
+    if (!input || ArrayBuffer.isView(input)) {
+        return input as UnwrappedOption<T, U>;
+    }
+
+    const next = <X>(x: X) =>
+        (fallback ? unwrapOptionRecursively(x, fallback) : unwrapOptionRecursively(x)) as UnwrappedOption<X, U>;
+
+    // Handle Option.
+    if (isOption(input)) {
+        if (isSome(input)) return next(input.value) as UnwrappedOption<T, U>;
+        return (fallback ? fallback() : null) as UnwrappedOption<T, U>;
+    }
+
+    // Walk.
+    if (Array.isArray(input)) {
+        return input.map(next) as UnwrappedOption<T, U>;
+    }
+    if (typeof input === 'object') {
+        return Object.fromEntries(Object.entries(input).map(([k, v]) => [k, next(v)])) as UnwrappedOption<T, U>;
+    }
+    return input as UnwrappedOption<T, U>;
+}

package/src/unwrap-option.ts

@@ -0,0 +1,64 @@
+import { isSome, none, Option, some } from './option';
+
+/**
+ * Unwraps the value of an {@link Option}, returning its contained value or a fallback.
+ *
+ * This function extracts the value `T` from an `Option<T>` type.
+ * - If the option is {@link Some}, it returns the contained value `T`.
+ * - If the option is {@link None}, it returns the fallback value `U`, which defaults to `null`.
+ *
+ * @typeParam T - The type of the contained value.
+ * @typeParam U - The type of the fallback value (defaults to `null`).
+ *
+ * @param option - The {@link Option} to unwrap.
+ * @param fallback - A function that provides a fallback value if the option is {@link None}.
+ * @returns The contained value if {@link Some}, otherwise the fallback value.
+ *
+ * @example
+ * Unwrapping an `Option` with no fallback.
+ * ```ts
+ * unwrapOption(some('Hello World')); // "Hello World"
+ * unwrapOption(none());              // null
+ * ```
+ *
+ * @example
+ * Providing a custom fallback value.
+ * ```ts
+ * unwrapOption(some('Hello World'), () => 'Default'); // "Hello World"
+ * unwrapOption(none(), () => 'Default');              // "Default"
+ * ```
+ *
+ * @see {@link Option}
+ * @see {@link Some}
+ * @see {@link None}
+ */
+export function unwrapOption<T>(option: Option<T>): T | null;
+export function unwrapOption<T, U>(option: Option<T>, fallback: () => U): T | U;
+export function unwrapOption<T, U = null>(option: Option<T>, fallback?: () => U): T | U {
+    if (isSome(option)) return option.value;
+    return fallback ? fallback() : (null as U);
+}
+
+/**
+ * Wraps a nullable value into an {@link Option}.
+ *
+ * - If the input value is `null`, this function returns {@link None}.
+ * - Otherwise, it wraps the value in {@link Some}.
+ *
+ * @typeParam T - The type of the contained value.
+ *
+ * @param nullable - The nullable value to wrap.
+ * @returns An {@link Option} wrapping the value.
+ *
+ * @example
+ * Wrapping nullable values.
+ * ```ts
+ * wrapNullable('Hello World'); // Option<string> (Some)
+ * wrapNullable<string>(null);  // Option<string> (None)
+ * ```
+ *
+ * @see {@link Option}
+ * @see {@link Some}
+ * @see {@link None}
+ */
+export const wrapNullable = <T>(nullable: T | null): Option<T> => (nullable !== null ? some(nullable) : none<T>());