@solana/codecs-strings 6.3.1 → 6.3.2-canary-20260313143218

package/src/base64.ts

@@ -0,0 +1,166 @@
+import {
+    combineCodec,
+    createDecoder,
+    createEncoder,
+    toArrayBuffer,
+    transformDecoder,
+    transformEncoder,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '@solana/codecs-core';
+import { SOLANA_ERROR__CODECS__INVALID_STRING_FOR_BASE, SolanaError } from '@solana/errors';
+
+import { assertValidBaseString } from './assertions';
+import { getBaseXResliceDecoder, getBaseXResliceEncoder } from './baseX-reslice';
+
+const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/**
+ * Returns an encoder for base-64 strings.
+ *
+ * This encoder serializes strings using a base-64 encoding scheme,
+ * commonly used for data encoding in URLs, cryptographic keys, and binary-to-text encoding.
+ *
+ * For more details, see {@link getBase64Codec}.
+ *
+ * @returns A `VariableSizeEncoder<string>` for encoding base-64 strings.
+ *
+ * @example
+ * Encoding a base-64 string.
+ * ```ts
+ * const encoder = getBase64Encoder();
+ * const bytes = encoder.encode('hello+world'); // 0x85e965a3ec28ae57
+ * ```
+ *
+ * @see {@link getBase64Codec}
+ */
+export const getBase64Encoder = (): VariableSizeEncoder<string> => {
+    if (__BROWSER__) {
+        return createEncoder({
+            getSizeFromValue: (value: string) => {
+                try {
+                    return (atob as Window['atob'])(value).length;
+                } catch {
+                    throw new SolanaError(SOLANA_ERROR__CODECS__INVALID_STRING_FOR_BASE, {
+                        alphabet,
+                        base: 64,
+                        value,
+                    });
+                }
+            },
+            write(value: string, bytes, offset) {
+                try {
+                    const bytesToAdd = (atob as Window['atob'])(value)
+                        .split('')
+                        .map(c => c.charCodeAt(0));
+                    bytes.set(bytesToAdd, offset);
+                    return bytesToAdd.length + offset;
+                } catch {
+                    throw new SolanaError(SOLANA_ERROR__CODECS__INVALID_STRING_FOR_BASE, {
+                        alphabet,
+                        base: 64,
+                        value,
+                    });
+                }
+            },
+        });
+    }
+
+    if (__NODEJS__) {
+        return createEncoder({
+            getSizeFromValue: (value: string) => Buffer.from(value, 'base64').length,
+            write(value: string, bytes, offset) {
+                assertValidBaseString(alphabet, value.replace(/=/g, ''));
+                const buffer = Buffer.from(value, 'base64');
+                bytes.set(buffer, offset);
+                return buffer.length + offset;
+            },
+        });
+    }
+
+    return transformEncoder(getBaseXResliceEncoder(alphabet, 6), (value: string): string => value.replace(/=/g, ''));
+};
+
+/**
+ * Returns a decoder for base-64 strings.
+ *
+ * This decoder deserializes base-64 encoded strings from a byte array.
+ *
+ * For more details, see {@link getBase64Codec}.
+ *
+ * @returns A `VariableSizeDecoder<string>` for decoding base-64 strings.
+ *
+ * @example
+ * Decoding a base-64 string.
+ * ```ts
+ * const decoder = getBase64Decoder();
+ * const value = decoder.decode(new Uint8Array([0x85, 0xe9, 0x65, 0xa3, 0xec, 0x28, 0xae, 0x57])); // "hello+world"
+ * ```
+ *
+ * @see {@link getBase64Codec}
+ */
+export const getBase64Decoder = (): VariableSizeDecoder<string> => {
+    if (__BROWSER__) {
+        return createDecoder({
+            read(bytes, offset = 0) {
+                const slice = bytes.slice(offset);
+                const value = (btoa as Window['btoa'])(String.fromCharCode(...slice));
+                return [value, bytes.length];
+            },
+        });
+    }
+
+    if (__NODEJS__) {
+        return createDecoder({
+            read: (bytes, offset = 0) => [Buffer.from(toArrayBuffer(bytes), offset).toString('base64'), bytes.length],
+        });
+    }
+
+    return transformDecoder(getBaseXResliceDecoder(alphabet, 6), (value: string): string =>
+        value.padEnd(Math.ceil(value.length / 4) * 4, '='),
+    );
+};
+
+/**
+ * Returns a codec for encoding and decoding base-64 strings.
+ *
+ * This codec serializes strings using a base-64 encoding scheme,
+ * commonly used for data encoding in URLs, cryptographic keys, and binary-to-text encoding.
+ *
+ * @returns A `VariableSizeCodec<string>` for encoding and decoding base-64 strings.
+ *
+ * @example
+ * Encoding and decoding a base-64 string.
+ * ```ts
+ * const codec = getBase64Codec();
+ * const bytes = codec.encode('hello+world'); // 0x85e965a3ec28ae57
+ * const value = codec.decode(bytes);         // "hello+world"
+ * ```
+ *
+ * @remarks
+ * This codec does not enforce a size boundary. It will encode and decode all bytes necessary to represent the string.
+ *
+ * If you need a fixed-size base-64 codec, consider using {@link fixCodecSize}.
+ *
+ * ```ts
+ * const codec = fixCodecSize(getBase64Codec(), 8);
+ * ```
+ *
+ * If you need a size-prefixed base-64 codec, consider using {@link addCodecSizePrefix}.
+ *
+ * ```ts
+ * const codec = addCodecSizePrefix(getBase64Codec(), getU32Codec());
+ * ```
+ *
+ * Separate {@link getBase64Encoder} and {@link getBase64Decoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getBase64Encoder().encode('hello+world');
+ * const value = getBase64Decoder().decode(bytes);
+ * ```
+ *
+ * @see {@link getBase64Encoder}
+ * @see {@link getBase64Decoder}
+ */
+export const getBase64Codec = (): VariableSizeCodec<string> => combineCodec(getBase64Encoder(), getBase64Decoder());

package/src/baseX-reslice.ts

@@ -0,0 +1,147 @@
+import {
+    combineCodec,
+    createDecoder,
+    createEncoder,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '@solana/codecs-core';
+
+import { assertValidBaseString } from './assertions';
+
+/**
+ * Returns an encoder for base-X encoded strings using bit re-slicing.
+ *
+ * This encoder serializes strings by dividing the input into custom-sized bit chunks,
+ * mapping them to an alphabet, and encoding the result into a byte array.
+ * This approach is commonly used for encoding schemes where the alphabet's length is a power of 2,
+ * such as base-16 or base-64.
+ *
+ * For more details, see {@link getBaseXResliceCodec}.
+ *
+ * @param alphabet - The set of characters defining the base-X encoding.
+ * @param bits - The number of bits per encoded chunk, typically `log2(alphabet.length)`.
+ * @returns A `VariableSizeEncoder<string>` for encoding base-X strings using bit re-slicing.
+ *
+ * @example
+ * Encoding a base-X string using bit re-slicing.
+ * ```ts
+ * const encoder = getBaseXResliceEncoder('elho', 2);
+ * const bytes = encoder.encode('hellolol'); // 0x4aee
+ * ```
+ *
+ * @see {@link getBaseXResliceCodec}
+ */
+export const getBaseXResliceEncoder = (alphabet: string, bits: number): VariableSizeEncoder<string> =>
+    createEncoder({
+        getSizeFromValue: (value: string) => Math.floor((value.length * bits) / 8),
+        write(value: string, bytes, offset) {
+            assertValidBaseString(alphabet, value);
+            if (value === '') return offset;
+            const charIndices = [...value].map(c => alphabet.indexOf(c));
+            const reslicedBytes = reslice(charIndices, bits, 8, false);
+            bytes.set(reslicedBytes, offset);
+            return reslicedBytes.length + offset;
+        },
+    });
+
+/**
+ * Returns a decoder for base-X encoded strings using bit re-slicing.
+ *
+ * This decoder deserializes base-X encoded strings by re-slicing the bits of a byte array into
+ * custom-sized chunks and mapping them to a specified alphabet.
+ * This is typically used for encoding schemes where the alphabet's length is a power of 2,
+ * such as base-16 or base-64.
+ *
+ * For more details, see {@link getBaseXResliceCodec}.
+ *
+ * @param alphabet - The set of characters defining the base-X encoding.
+ * @param bits - The number of bits per encoded chunk, typically `log2(alphabet.length)`.
+ * @returns A `VariableSizeDecoder<string>` for decoding base-X strings using bit re-slicing.
+ *
+ * @example
+ * Decoding a base-X string using bit re-slicing.
+ * ```ts
+ * const decoder = getBaseXResliceDecoder('elho', 2);
+ * const value = decoder.decode(new Uint8Array([0x4a, 0xee])); // "hellolol"
+ * ```
+ *
+ * @see {@link getBaseXResliceCodec}
+ */
+export const getBaseXResliceDecoder = (alphabet: string, bits: number): VariableSizeDecoder<string> =>
+    createDecoder({
+        read(rawBytes, offset = 0): [string, number] {
+            const bytes = offset === 0 || offset <= -rawBytes.byteLength ? rawBytes : rawBytes.slice(offset);
+            if (bytes.length === 0) return ['', rawBytes.length];
+            const charIndices = reslice([...bytes], 8, bits, true);
+            return [charIndices.map(i => alphabet[i]).join(''), rawBytes.length];
+        },
+    });
+
+/**
+ * Returns a codec for encoding and decoding base-X strings using bit re-slicing.
+ *
+ * This codec serializes strings by dividing the input into custom-sized bit chunks,
+ * mapping them to a given alphabet, and encoding the result into bytes.
+ * It is particularly suited for encoding schemes where the alphabet's length is a power of 2,
+ * such as base-16 or base-64.
+ *
+ * @param alphabet - The set of characters defining the base-X encoding.
+ * @param bits - The number of bits per encoded chunk, typically `log2(alphabet.length)`.
+ * @returns A `VariableSizeCodec<string>` for encoding and decoding base-X strings using bit re-slicing.
+ *
+ * @example
+ * Encoding and decoding a base-X string using bit re-slicing.
+ * ```ts
+ * const codec = getBaseXResliceCodec('elho', 2);
+ * const bytes = codec.encode('hellolol'); // 0x4aee
+ * const value = codec.decode(bytes);      // "hellolol"
+ * ```
+ *
+ * @remarks
+ * This codec does not enforce a size boundary. It will encode and decode all bytes necessary to represent the string.
+ *
+ * If you need a fixed-size base-X codec, consider using {@link fixCodecSize}.
+ *
+ * ```ts
+ * const codec = fixCodecSize(getBaseXResliceCodec('elho', 2), 8);
+ * ```
+ *
+ * If you need a size-prefixed base-X codec, consider using {@link addCodecSizePrefix}.
+ *
+ * ```ts
+ * const codec = addCodecSizePrefix(getBaseXResliceCodec('elho', 2), getU32Codec());
+ * ```
+ *
+ * Separate {@link getBaseXResliceEncoder} and {@link getBaseXResliceDecoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getBaseXResliceEncoder('elho', 2).encode('hellolol');
+ * const value = getBaseXResliceDecoder('elho', 2).decode(bytes);
+ * ```
+ *
+ * @see {@link getBaseXResliceEncoder}
+ * @see {@link getBaseXResliceDecoder}
+ */
+export const getBaseXResliceCodec = (alphabet: string, bits: number): VariableSizeCodec<string> =>
+    combineCodec(getBaseXResliceEncoder(alphabet, bits), getBaseXResliceDecoder(alphabet, bits));
+
+/** Helper function to reslice the bits inside bytes. */
+function reslice(input: number[], inputBits: number, outputBits: number, useRemainder: boolean): number[] {
+    const output = [];
+    let accumulator = 0;
+    let bitsInAccumulator = 0;
+    const mask = (1 << outputBits) - 1;
+    for (const value of input) {
+        accumulator = (accumulator << inputBits) | value;
+        bitsInAccumulator += inputBits;
+        while (bitsInAccumulator >= outputBits) {
+            bitsInAccumulator -= outputBits;
+            output.push((accumulator >> bitsInAccumulator) & mask);
+        }
+    }
+    if (useRemainder && bitsInAccumulator > 0) {
+        output.push((accumulator << (outputBits - bitsInAccumulator)) & mask);
+    }
+    return output;
+}

package/src/baseX.ts

@@ -0,0 +1,189 @@
+import {
+    combineCodec,
+    createDecoder,
+    createEncoder,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '@solana/codecs-core';
+
+import { assertValidBaseString } from './assertions';
+
+/**
+ * Returns an encoder for base-X encoded strings.
+ *
+ * This encoder serializes strings using a custom alphabet, treating the length of the alphabet as the base.
+ * The encoding process involves converting the input string to a numeric value in base-X, then
+ * encoding that value into bytes while preserving leading zeroes.
+ *
+ * For more details, see {@link getBaseXCodec}.
+ *
+ * @param alphabet - The set of characters defining the base-X encoding.
+ * @returns A `VariableSizeEncoder<string>` for encoding base-X strings.
+ *
+ * @example
+ * Encoding a base-X string using a custom alphabet.
+ * ```ts
+ * const encoder = getBaseXEncoder('0123456789abcdef');
+ * const bytes = encoder.encode('deadface'); // 0xdeadface
+ * ```
+ *
+ * @see {@link getBaseXCodec}
+ */
+export const getBaseXEncoder = (alphabet: string): VariableSizeEncoder<string> => {
+    return createEncoder({
+        getSizeFromValue: (value: string): number => {
+            const [leadingZeroes, tailChars] = partitionLeadingZeroes(value, alphabet[0]);
+            if (!tailChars) return value.length;
+
+            const base10Number = getBigIntFromBaseX(tailChars, alphabet);
+            return leadingZeroes.length + Math.ceil(base10Number.toString(16).length / 2);
+        },
+        write(value: string, bytes, offset) {
+            // Check if the value is valid.
+            assertValidBaseString(alphabet, value);
+            if (value === '') return offset;
+
+            // Handle leading zeroes.
+            const [leadingZeroes, tailChars] = partitionLeadingZeroes(value, alphabet[0]);
+            if (!tailChars) {
+                bytes.set(new Uint8Array(leadingZeroes.length).fill(0), offset);
+                return offset + leadingZeroes.length;
+            }
+
+            // From baseX to base10.
+            let base10Number = getBigIntFromBaseX(tailChars, alphabet);
+
+            // From base10 to bytes.
+            const tailBytes: number[] = [];
+            while (base10Number > 0n) {
+                tailBytes.unshift(Number(base10Number % 256n));
+                base10Number /= 256n;
+            }
+
+            const bytesToAdd = [...Array(leadingZeroes.length).fill(0), ...tailBytes];
+            bytes.set(bytesToAdd, offset);
+            return offset + bytesToAdd.length;
+        },
+    });
+};
+
+/**
+ * Returns a decoder for base-X encoded strings.
+ *
+ * This decoder deserializes base-X encoded strings from a byte array using a custom alphabet.
+ * The decoding process converts the byte array into a numeric value in base-10, then
+ * maps that value back to characters in the specified base-X alphabet.
+ *
+ * For more details, see {@link getBaseXCodec}.
+ *
+ * @param alphabet - The set of characters defining the base-X encoding.
+ * @returns A `VariableSizeDecoder<string>` for decoding base-X strings.
+ *
+ * @example
+ * Decoding a base-X string using a custom alphabet.
+ * ```ts
+ * const decoder = getBaseXDecoder('0123456789abcdef');
+ * const value = decoder.decode(new Uint8Array([0xde, 0xad, 0xfa, 0xce])); // "deadface"
+ * ```
+ *
+ * @see {@link getBaseXCodec}
+ */
+export const getBaseXDecoder = (alphabet: string): VariableSizeDecoder<string> => {
+    return createDecoder({
+        read(rawBytes, offset): [string, number] {
+            const bytes = offset === 0 || offset <= -rawBytes.byteLength ? rawBytes : rawBytes.slice(offset);
+            if (bytes.length === 0) return ['', 0];
+
+            // Handle leading zeroes.
+            let trailIndex = bytes.findIndex(n => n !== 0);
+            trailIndex = trailIndex === -1 ? bytes.length : trailIndex;
+            const leadingZeroes = alphabet[0].repeat(trailIndex);
+            if (trailIndex === bytes.length) return [leadingZeroes, rawBytes.length];
+
+            // From bytes to base10.
+            const base10Number = bytes.slice(trailIndex).reduce((sum, byte) => sum * 256n + BigInt(byte), 0n);
+
+            // From base10 to baseX.
+            const tailChars = getBaseXFromBigInt(base10Number, alphabet);
+
+            return [leadingZeroes + tailChars, rawBytes.length];
+        },
+    });
+};
+
+/**
+ * Returns a codec for encoding and decoding base-X strings.
+ *
+ * This codec serializes strings using a custom alphabet, treating the length of the alphabet as the base.
+ * The encoding process converts the input string into a numeric value in base-X, which is then encoded as bytes.
+ * The decoding process reverses this transformation to reconstruct the original string.
+ *
+ * This codec supports leading zeroes by treating the first character of the alphabet as the zero character.
+ *
+ * @param alphabet - The set of characters defining the base-X encoding.
+ * @returns A `VariableSizeCodec<string>` for encoding and decoding base-X strings.
+ *
+ * @example
+ * Encoding and decoding a base-X string using a custom alphabet.
+ * ```ts
+ * const codec = getBaseXCodec('0123456789abcdef');
+ * const bytes = codec.encode('deadface'); // 0xdeadface
+ * const value = codec.decode(bytes);      // "deadface"
+ * ```
+ *
+ * @remarks
+ * This codec does not enforce a size boundary. It will encode and decode all bytes necessary to represent the string.
+ *
+ * If you need a fixed-size base-X codec, consider using {@link fixCodecSize}.
+ *
+ * ```ts
+ * const codec = fixCodecSize(getBaseXCodec('0123456789abcdef'), 8);
+ * ```
+ *
+ * If you need a size-prefixed base-X codec, consider using {@link addCodecSizePrefix}.
+ *
+ * ```ts
+ * const codec = addCodecSizePrefix(getBaseXCodec('0123456789abcdef'), getU32Codec());
+ * ```
+ *
+ * Separate {@link getBaseXEncoder} and {@link getBaseXDecoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getBaseXEncoder('0123456789abcdef').encode('deadface');
+ * const value = getBaseXDecoder('0123456789abcdef').decode(bytes);
+ * ```
+ *
+ * @see {@link getBaseXEncoder}
+ * @see {@link getBaseXDecoder}
+ */
+export const getBaseXCodec = (alphabet: string): VariableSizeCodec<string> =>
+    combineCodec(getBaseXEncoder(alphabet), getBaseXDecoder(alphabet));
+
+function partitionLeadingZeroes(
+    value: string,
+    zeroCharacter: string,
+): [leadingZeros: string, tailChars: string | undefined] {
+    const [leadingZeros, tailChars] = value.split(new RegExp(`((?!${zeroCharacter}).*)`));
+    return [leadingZeros, tailChars];
+}
+
+function getBigIntFromBaseX(value: string, alphabet: string): bigint {
+    const base = BigInt(alphabet.length);
+    let sum = 0n;
+    for (const char of value) {
+        sum *= base;
+        sum += BigInt(alphabet.indexOf(char));
+    }
+    return sum;
+}
+
+function getBaseXFromBigInt(value: bigint, alphabet: string): string {
+    const base = BigInt(alphabet.length);
+    const tailChars = [];
+    while (value > 0n) {
+        tailChars.unshift(alphabet[Number(value % base)]);
+        value /= base;
+    }
+    return tailChars.join('');
+}