feat: add types for array, base64, hex and utf8

array.d.ts

@@ -0,0 +1,24 @@
+/// <reference types="node" />
+
+// >= TypeScript 5.9 made Uint8Array templated with <> and defaulted to ArrayBufferLike
+// which would incorrectly accept SharedArrayBuffer instances.
+// < TypeScript 5.7 doesn't support templates for Uint8Array.
+// So this type is defined as a workaround to evaluate to Uint8Array<ArrayBuffer> on all versions of TypeScript.
+export type Uint8ArrayBuffer = ReturnType<typeof Uint8Array.from>;
+
+/**
+ * Output format for typed array conversions
+ */
+export type OutputFormat = 'uint8' | 'buffer';
+
+/**
+ * Creates a view of a TypedArray in the specified format
+ * Note: This does not copy data - returns a view on the same underlying buffer
+ * @param arr - The input TypedArray
+ * @param format - The desired output format ('uint8' or 'buffer')
+ * @returns A view on the same underlying buffer
+ */
+export function typedView(arr: ArrayBufferView, format: 'uint8'): Uint8Array;
+export function typedView(arr: ArrayBufferView, format: 'buffer'): Buffer;
+export function typedView(arr: ArrayBufferView, format: OutputFormat): Uint8Array | Buffer;
+

base64.d.ts

@@ -0,0 +1,76 @@
+/// <reference types="node" />
+
+import type { OutputFormat, Uint8ArrayBuffer } from './array.js';
+
+/**
+ * Options for base64 encoding
+ */
+export interface ToBase64Options {
+  /** Whether to include padding characters (default: true for base64, false for base64url) */
+  padding?: boolean;
+}
+
+/**
+ * Padding mode for base64 decoding
+ * - true: padding is required
+ * - false: padding is not allowed
+ * - 'both': padding is optional (default for base64)
+ */
+export type PaddingMode = boolean | 'both';
+
+/**
+ * Options for base64 decoding
+ */
+export interface FromBase64Options {
+  /** Output format (default: 'uint8') */
+  format?: OutputFormat;
+  /** Padding mode */
+  padding?: PaddingMode;
+}
+
+/**
+ * Encodes a Uint8Array to a base64 string (RFC 4648)
+ * @param arr - The input bytes
+ * @param options - Encoding options
+ * @returns The base64 encoded string
+ */
+export function toBase64(arr: Uint8ArrayBuffer, options?: ToBase64Options): string;
+
+/**
+ * Encodes a Uint8Array to a base64url string (RFC 4648)
+ * @param arr - The input bytes
+ * @param options - Encoding options (padding defaults to false)
+ * @returns The base64url encoded string
+ */
+export function toBase64url(arr: Uint8ArrayBuffer, options?: ToBase64Options): string;
+
+/**
+ * Decodes a base64 string to bytes
+ * Operates in strict mode for last chunk, does not allow whitespace
+ * @param str - The base64 encoded string
+ * @param options - Decoding options
+ * @returns The decoded bytes
+ */
+export function fromBase64(str: string, options?: FromBase64Options): Uint8ArrayBuffer;
+export function fromBase64(str: string, options: FromBase64Options & { format: 'buffer' }): Buffer;
+
+/**
+ * Decodes a base64url string to bytes
+ * Operates in strict mode for last chunk, does not allow whitespace
+ * @param str - The base64url encoded string
+ * @param options - Decoding options (padding defaults to false)
+ * @returns The decoded bytes
+ */
+export function fromBase64url(str: string, options?: FromBase64Options): Uint8ArrayBuffer;
+export function fromBase64url(str: string, options: FromBase64Options & { format: 'buffer' }): Buffer;
+
+/**
+ * Decodes either base64 or base64url string to bytes
+ * Automatically detects the variant based on characters present
+ * @param str - The base64 or base64url encoded string
+ * @param options - Decoding options
+ * @returns The decoded bytes
+ */
+export function fromBase64any(str: string, options?: FromBase64Options): Uint8ArrayBuffer;
+export function fromBase64any(str: string, options: FromBase64Options & { format: 'buffer' }): Buffer;
+

hex.d.ts

@@ -0,0 +1,22 @@
+/// <reference types="node" />
+
+import type { OutputFormat, Uint8ArrayBuffer } from './array.js';
+
+/**
+ * Encodes a Uint8Array to a lowercase hex string
+ * @param arr - The input bytes
+ * @returns The hex encoded string
+ */
+export function toHex(arr: Uint8ArrayBuffer): string;
+
+/**
+ * Decodes a hex string to bytes
+ * Unlike Buffer.from(), throws on invalid input
+ * @param str - The hex encoded string (case-insensitive)
+ * @param format - Output format (default: 'uint8')
+ * @returns The decoded bytes
+ */
+export function fromHex(str: string, format?: 'uint8'): Uint8ArrayBuffer;
+export function fromHex(str: string, format: 'buffer'): Buffer;
+export function fromHex(str: string, format?: OutputFormat): Uint8ArrayBuffer | Buffer;
+

package.json

@@ -60,16 +60,19 @@
     "/fallback/utf16.js",
     "/fallback/utf8.js",
     "/array.js",
+    "/array.d.ts",
     "/assert.js",
     "/base32.js",
     "/base58.js",
     "/base58check.js",
     "/base64.js",
+    "/base64.d.ts",
     "/bech32.js",
     "/bigint.js",
     "/encoding.js",
     "/encoding-lite.js",
     "/hex.js",
+    "/hex.d.ts",
     "/hex.node.js",
     "/multi-byte.js",
     "/multi-byte.node.js",
@@ -78,18 +81,26 @@
     "/utf16.js",
     "/utf16.node.js",
     "/utf8.js",
+    "/utf8.d.ts",
     "/utf8.node.js",
     "/wif.js"
   ],
   "exports": {
-    "./array.js": "./array.js",
+    "./array.js": {
+      "types": "./array.d.ts",
+      "default": "./array.js"
+    },
     "./base32.js": "./base32.js",
     "./base58.js": "./base58.js",
     "./base58check.js": "./base58check.js",
-    "./base64.js": "./base64.js",
+    "./base64.js": {
+      "types": "./base64.d.ts",
+      "default": "./base64.js"
+    },
     "./bech32.js": "./bech32.js",
     "./bigint.js": "./bigint.js",
     "./hex.js": {
+      "types": "./hex.d.ts",
       "node": "./hex.node.js",
       "default": "./hex.js"
     },
@@ -108,6 +119,7 @@
       "default": "./utf16.js"
     },
     "./utf8.js": {
+      "types": "./utf8.d.ts",
       "node": "./utf8.node.js",
       "default": "./utf8.js"
     },

utf8.d.ts

@@ -0,0 +1,42 @@
+/// <reference types="node" />
+
+import type { OutputFormat, Uint8ArrayBuffer } from './array.js';
+
+/**
+ * Encodes a string to UTF-8 bytes (strict mode)
+ * Throws on invalid Unicode (unpaired surrogates)
+ * @param str - The string to encode
+ * @param format - Output format (default: 'uint8')
+ * @returns The encoded bytes
+ */
+export function utf8fromString(str: string, format?: 'uint8'): Uint8ArrayBuffer;
+export function utf8fromString(str: string, format: 'buffer'): Buffer;
+export function utf8fromString(str: string, format?: OutputFormat): Uint8ArrayBuffer | Buffer;
+
+/**
+ * Encodes a string to UTF-8 bytes (loose mode)
+ * Replaces invalid Unicode with replacement character
+ * @param str - The string to encode
+ * @param format - Output format (default: 'uint8')
+ * @returns The encoded bytes
+ */
+export function utf8fromStringLoose(str: string, format?: 'uint8'): Uint8ArrayBuffer;
+export function utf8fromStringLoose(str: string, format: 'buffer'): Buffer;
+export function utf8fromStringLoose(str: string, format?: OutputFormat): Uint8ArrayBuffer | Buffer;
+
+/**
+ * Decodes UTF-8 bytes to a string (strict mode)
+ * Throws on invalid UTF-8 sequences
+ * @param arr - The bytes to decode
+ * @returns The decoded string
+ */
+export function utf8toString(arr: Uint8ArrayBuffer): string;
+
+/**
+ * Decodes UTF-8 bytes to a string (loose mode)
+ * Replaces invalid sequences with replacement character
+ * @param arr - The bytes to decode
+ * @returns The decoded string
+ */
+export function utf8toStringLoose(arr: Uint8ArrayBuffer): string;
+