diff --git a/array.d.ts b/array.d.ts new file mode 100644 index 0000000..45e58b7 --- /dev/null +++ b/array.d.ts @@ -0,0 +1,24 @@ +/// + +// >= 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 on all versions of TypeScript. +export type Uint8ArrayBuffer = ReturnType; + +/** + * 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; + diff --git a/base64.d.ts b/base64.d.ts new file mode 100644 index 0000000..f381f56 --- /dev/null +++ b/base64.d.ts @@ -0,0 +1,76 @@ +/// + +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; + diff --git a/hex.d.ts b/hex.d.ts new file mode 100644 index 0000000..6250d78 --- /dev/null +++ b/hex.d.ts @@ -0,0 +1,22 @@ +/// + +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; + diff --git a/package.json b/package.json index adaf705..6b0700e 100644 --- a/package.json +++ b/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" }, diff --git a/utf8.d.ts b/utf8.d.ts new file mode 100644 index 0000000..95a7c24 --- /dev/null +++ b/utf8.d.ts @@ -0,0 +1,42 @@ +/// + +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; +