@bcts/uniform-resources 1.0.0-alpha.5

package/dist/index.d.cts

@@ -0,0 +1,761 @@
+import { Cbor } from "@bcts/dcbor";
+
+//#region src/error.d.ts
+/**
+ * Error type for UR encoding/decoding operations.
+ */
+declare class URError extends Error {
+  constructor(message: string);
+}
+/**
+ * Error type for invalid UR schemes.
+ */
+declare class InvalidSchemeError extends URError {
+  constructor();
+}
+/**
+ * Error type for unspecified UR types.
+ */
+declare class TypeUnspecifiedError extends URError {
+  constructor();
+}
+/**
+ * Error type for invalid UR types.
+ */
+declare class InvalidTypeError extends URError {
+  constructor();
+}
+/**
+ * Error type for non-single-part URs.
+ */
+declare class NotSinglePartError extends URError {
+  constructor();
+}
+/**
+ * Error type for unexpected UR types.
+ */
+declare class UnexpectedTypeError extends URError {
+  constructor(expected: string, found: string);
+}
+/**
+ * Error type for Bytewords encoding/decoding errors.
+ */
+declare class BytewordsError extends URError {
+  constructor(message: string);
+}
+/**
+ * Error type for CBOR encoding/decoding errors.
+ */
+declare class CBORError extends URError {
+  constructor(message: string);
+}
+type Result<T> = T | Error;
+/**
+ * Helper function to check if a result is an error.
+ */
+declare function isError(result: unknown): result is Error;
+//#endregion
+//#region src/ur-type.d.ts
+/**
+ * Represents a UR (Uniform Resource) type identifier.
+ *
+ * Valid UR types contain only lowercase letters, digits, and hyphens.
+ *
+ * @example
+ * ```typescript
+ * const urType = new URType('test');
+ * console.log(urType.string()); // "test"
+ * ```
+ */
+declare class URType {
+  private readonly _type;
+  /**
+   * Creates a new URType from the provided type string.
+   *
+   * @param urType - The UR type as a string
+   * @throws {InvalidTypeError} If the type contains invalid characters
+   *
+   * @example
+   * ```typescript
+   * const urType = new URType('test');
+   * ```
+   */
+  constructor(urType: string);
+  /**
+   * Returns the string representation of the URType.
+   *
+   * @example
+   * ```typescript
+   * const urType = new URType('test');
+   * console.log(urType.string()); // "test"
+   * ```
+   */
+  string(): string;
+  /**
+   * Checks equality with another URType based on the type string.
+   */
+  equals(other: URType): boolean;
+  /**
+   * Returns the string representation.
+   */
+  toString(): string;
+  /**
+   * Creates a URType from a string, throwing an error if invalid.
+   *
+   * @param value - The UR type string
+   * @returns A new URType instance
+   * @throws {InvalidTypeError} If the type is invalid
+   */
+  static from(value: string): URType;
+  /**
+   * Safely creates a URType, returning an error if invalid.
+   *
+   * @param value - The UR type string
+   * @returns Either a URType or an error
+   */
+  static tryFrom(value: string): URType | InvalidTypeError;
+}
+//#endregion
+//#region src/ur.d.ts
+/**
+ * A Uniform Resource (UR) is a URI-encoded CBOR object.
+ *
+ * URs are defined in [BCR-2020-005: Uniform Resources](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-005-ur.md).
+ *
+ * @example
+ * ```typescript
+ * import { UR } from '@bcts/uniform-resources';
+ * import { CBOR } from '@bcts/dcbor';
+ *
+ * // Create a UR from a CBOR object
+ * const cbor = CBOR.fromArray([1, 2, 3]);
+ * const ur = UR.new('test', cbor);
+ *
+ * // Encode to string
+ * const urString = ur.string();
+ * console.log(urString); // "ur:test/..."
+ *
+ * // Decode from string
+ * const decodedUR = UR.fromURString(urString);
+ * console.log(decodedUR.urTypeStr()); // "test"
+ * ```
+ */
+declare class UR {
+  private readonly _urType;
+  private readonly _cbor;
+  /**
+   * Creates a new UR from the provided type and CBOR data.
+   *
+   * @param urType - The UR type (will be validated)
+   * @param cbor - The CBOR data to encode
+   * @throws {InvalidTypeError} If the type is invalid
+   *
+   * @example
+   * ```typescript
+   * const ur = UR.new('bytes', CBOR.fromString('hello'));
+   * ```
+   */
+  static new(urType: string | URType, cbor: Cbor): UR;
+  /**
+   * Creates a new UR from a UR string.
+   *
+   * @param urString - A UR string like "ur:test/..."
+   * @throws {InvalidSchemeError} If the string doesn't start with "ur:"
+   * @throws {TypeUnspecifiedError} If no type is specified
+   * @throws {NotSinglePartError} If the UR is multi-part
+   * @throws {URError} If decoding fails
+   *
+   * @example
+   * ```typescript
+   * const ur = UR.fromURString('ur:test/lsadaoaxjygonesw');
+   * ```
+   */
+  static fromURString(urString: string): UR;
+  private constructor();
+  /**
+   * Returns the UR type.
+   */
+  urType(): URType;
+  /**
+   * Returns the UR type as a string.
+   */
+  urTypeStr(): string;
+  /**
+   * Returns the CBOR data.
+   */
+  cbor(): Cbor;
+  /**
+   * Returns the string representation of the UR (lowercase, suitable for display).
+   *
+   * @example
+   * ```typescript
+   * const ur = UR.new('test', CBOR.fromArray([1, 2, 3]));
+   * console.log(ur.string()); // "ur:test/lsadaoaxjygonesw"
+   * ```
+   */
+  string(): string;
+  /**
+   * Returns the QR string representation (uppercase, most efficient for QR codes).
+   */
+  qrString(): string;
+  /**
+   * Returns the QR data as bytes (uppercase UR string as UTF-8).
+   */
+  qrData(): Uint8Array;
+  /**
+   * Checks if the UR type matches the expected type.
+   *
+   * @param expectedType - The expected type
+   * @throws {UnexpectedTypeError} If the types don't match
+   */
+  checkType(expectedType: string | URType): void;
+  /**
+   * Returns the string representation.
+   */
+  toString(): string;
+  /**
+   * Checks equality with another UR.
+   */
+  equals(other: UR): boolean;
+}
+//#endregion
+//#region src/ur-encodable.d.ts
+/**
+ * A type that can be encoded to a UR (Uniform Resource).
+ *
+ * Types implementing this interface should be able to convert themselves
+ * to CBOR data and associate that with a UR type identifier.
+ *
+ * @example
+ * ```typescript
+ * class MyType implements UREncodable {
+ *   toCBOR(): CBOR {
+ *     // Convert to CBOR
+ *   }
+ *
+ *   ur(): UR {
+ *     const cbor = this.toCBOR();
+ *     return UR.new('mytype', cbor);
+ *   }
+ * }
+ * ```
+ */
+interface UREncodable {
+  /**
+   * Returns the UR representation of the object.
+   */
+  ur(): UR;
+  /**
+   * Returns the UR string representation of the object.
+   */
+  urString(): string;
+}
+/**
+ * Helper function to check if an object implements UREncodable.
+ */
+declare function isUREncodable(obj: unknown): obj is UREncodable;
+//#endregion
+//#region src/ur-decodable.d.ts
+/**
+ * A type that can be decoded from a UR (Uniform Resource).
+ *
+ * Types implementing this interface should be able to create themselves
+ * from a UR containing their data.
+ *
+ * @example
+ * ```typescript
+ * class MyType implements URDecodable {
+ *   fromUR(ur: UR): MyType {
+ *     const cbor = ur.cbor();
+ *     // Decode from CBOR and return MyType instance
+ *   }
+ *
+ *   fromURString(urString: string): MyType {
+ *     return this.fromUR(UR.fromURString(urString));
+ *   }
+ * }
+ * ```
+ */
+interface URDecodable {
+  /**
+   * Creates an instance of this type from a UR.
+   *
+   * @param ur - The UR to decode from
+   * @returns An instance of this type
+   * @throws If the UR type is wrong or data is malformed
+   */
+  fromUR(ur: UR): unknown;
+  /**
+   * Creates an instance of this type from a UR string.
+   *
+   * This is a convenience method that parses the UR string and then
+   * calls fromUR().
+   *
+   * @param urString - The UR string to decode from (e.g., "ur:type/...")
+   * @returns An instance of this type
+   * @throws If the UR string is invalid or data is malformed
+   */
+  fromURString?(urString: string): unknown;
+}
+/**
+ * Helper function to check if an object implements URDecodable.
+ */
+declare function isURDecodable(obj: unknown): obj is URDecodable;
+//#endregion
+//#region src/ur-codable.d.ts
+/**
+ * A type that can be both encoded to and decoded from a UR.
+ *
+ * This combines the UREncodable and URDecodable interfaces for types
+ * that support bidirectional UR conversion.
+ *
+ * @example
+ * ```typescript
+ * class MyType implements URCodable {
+ *   ur(): UR {
+ *     // Encode to UR
+ *   }
+ *
+ *   urString(): string {
+ *     // Return UR string
+ *   }
+ *
+ *   fromUR(ur: UR): MyType {
+ *     // Decode from UR
+ *   }
+ *
+ *   fromURString(urString: string): MyType {
+ *     // Decode from UR string (convenience method)
+ *     return this.fromUR(UR.fromURString(urString));
+ *   }
+ * }
+ * ```
+ */
+interface URCodable extends UREncodable, URDecodable {}
+/**
+ * Helper function to check if an object implements URCodable.
+ */
+declare function isURCodable(obj: unknown): obj is URCodable;
+//#endregion
+//#region src/multipart-encoder.d.ts
+/**
+ * Encodes a UR as multiple parts using fountain codes.
+ *
+ * This allows large CBOR structures to be split into multiple UR strings
+ * that can be transmitted separately and reassembled. The encoder uses
+ * fountain codes for resilient transmission over lossy channels.
+ *
+ * For single-part URs (small payloads), use the regular UR.string() method.
+ *
+ * @example
+ * ```typescript
+ * const ur = UR.new('bytes', cbor);
+ * const encoder = new MultipartEncoder(ur, 100);
+ *
+ * // Generate all pure parts
+ * while (!encoder.isComplete()) {
+ *   const part = encoder.nextPart();
+ *   console.log(part); // "ur:bytes/1-10/..."
+ * }
+ *
+ * // Generate additional rateless parts for redundancy
+ * for (let i = 0; i < 5; i++) {
+ *   const part = encoder.nextPart();
+ *   console.log(part); // "ur:bytes/11-10/..."
+ * }
+ * ```
+ */
+declare class MultipartEncoder {
+  private readonly _ur;
+  private readonly _fountainEncoder;
+  private _currentIndex;
+  /**
+   * Creates a new multipart encoder for the given UR.
+   *
+   * @param ur - The UR to encode
+   * @param maxFragmentLen - Maximum length of each fragment in bytes
+   * @throws {URError} If encoding fails
+   *
+   * @example
+   * ```typescript
+   * const encoder = new MultipartEncoder(ur, 100);
+   * ```
+   */
+  constructor(ur: UR, maxFragmentLen: number);
+  /**
+   * Returns whether the message fits in a single part.
+   *
+   * For single-part messages, consider using UR.string() directly.
+   */
+  isSinglePart(): boolean;
+  /**
+   * Gets the next part of the encoding.
+   *
+   * Parts 1 through seqLen are "pure" fragments containing one piece each.
+   * Parts beyond seqLen are "mixed" fragments using fountain codes for redundancy.
+   *
+   * @returns The next UR string part
+   *
+   * @example
+   * ```typescript
+   * const part = encoder.nextPart();
+   * // Returns: "ur:bytes/1-3/lsadaoaxjygonesw"
+   * ```
+   */
+  nextPart(): string;
+  /**
+   * Encodes a fountain part as a UR string.
+   */
+  private _encodePart;
+  /**
+   * Encodes part metadata and data into bytes for bytewords encoding.
+   */
+  private _encodePartData;
+  /**
+   * Gets the current part index.
+   */
+  currentIndex(): number;
+  /**
+   * Gets the total number of pure parts.
+   *
+   * Note: Fountain codes can generate unlimited parts beyond this count
+   * for additional redundancy.
+   */
+  partsCount(): number;
+  /**
+   * Checks if all pure parts have been emitted.
+   *
+   * Even after this returns true, you can continue calling nextPart()
+   * to generate additional rateless parts for redundancy.
+   */
+  isComplete(): boolean;
+  /**
+   * Resets the encoder to start from the beginning.
+   */
+  reset(): void;
+}
+//#endregion
+//#region src/multipart-decoder.d.ts
+/**
+ * Decodes multiple UR parts back into a single UR.
+ *
+ * This reassembles multipart URs that were encoded using fountain codes.
+ * The decoder can handle out-of-order reception and packet loss.
+ *
+ * @example
+ * ```typescript
+ * const decoder = new MultipartDecoder();
+ *
+ * for (const urPart of urParts) {
+ *   decoder.receive(urPart);
+ *   if (decoder.isComplete()) {
+ *     const ur = decoder.message();
+ *     break;
+ *   }
+ * }
+ * ```
+ */
+declare class MultipartDecoder {
+  private _urType;
+  private _fountainDecoder;
+  private _decodedMessage;
+  /**
+   * Receives a UR part string.
+   *
+   * @param part - A UR part string (e.g., "ur:bytes/1-10/..." or "ur:bytes/...")
+   * @throws {InvalidSchemeError} If the part doesn't start with "ur:"
+   * @throws {UnexpectedTypeError} If the type doesn't match previous parts
+   */
+  receive(part: string): void;
+  /**
+   * Parses a UR part string to extract type and part info.
+   */
+  private _parsePart;
+  /**
+   * Decodes a multipart UR's fountain part data.
+   */
+  private _decodeFountainPart;
+  /**
+   * Checks if the message is complete.
+   */
+  isComplete(): boolean;
+  /**
+   * Gets the decoded UR message.
+   *
+   * @returns The decoded UR, or null if not yet complete
+   */
+  message(): UR | null;
+  /**
+   * Returns the decoding progress as a fraction (0 to 1).
+   */
+  progress(): number;
+  /**
+   * Resets the decoder to receive a new message.
+   */
+  reset(): void;
+}
+//#endregion
+//#region src/fountain.d.ts
+/**
+ * Fountain code implementation for multipart URs.
+ *
+ * This implements a hybrid fixed-rate and rateless fountain code system
+ * as specified in BCR-2020-005 and BCR-2024-001.
+ *
+ * Key concepts:
+ * - Parts 1-seqLen are "pure" fragments (fixed-rate)
+ * - Parts > seqLen are "mixed" fragments using XOR (rateless)
+ * - Xoshiro256** PRNG ensures encoder/decoder agree on mixing
+ */
+/**
+ * Represents a fountain code part with metadata.
+ */
+interface FountainPart {
+  /** Sequence number (1-based) */
+  seqNum: number;
+  /** Total number of pure fragments */
+  seqLen: number;
+  /** Length of original message */
+  messageLen: number;
+  /** CRC32 checksum of original message */
+  checksum: number;
+  /** Fragment data */
+  data: Uint8Array;
+}
+/**
+ * Splits data into fragments of the specified size.
+ */
+declare function splitMessage(message: Uint8Array, fragmentLen: number): Uint8Array[];
+/**
+ * XOR two Uint8Arrays together.
+ */
+declare function xorBytes(a: Uint8Array, b: Uint8Array): Uint8Array;
+/**
+ * Chooses which fragments to mix for a given sequence number.
+ *
+ * This uses a seeded Xoshiro256** PRNG to deterministically select fragments,
+ * ensuring encoder and decoder agree without explicit coordination.
+ *
+ * @param seqNum - The sequence number (1-based)
+ * @param seqLen - Total number of pure fragments
+ * @param checksum - CRC32 checksum of the message
+ * @returns Array of fragment indices (0-based)
+ */
+declare function chooseFragments(seqNum: number, seqLen: number, checksum: number): number[];
+/**
+ * Mixes the selected fragments using XOR.
+ */
+declare function mixFragments(fragments: Uint8Array[], indices: number[]): Uint8Array;
+/**
+ * Fountain encoder for creating multipart URs.
+ */
+declare class FountainEncoder {
+  private readonly fragments;
+  private readonly messageLen;
+  private readonly checksum;
+  private seqNum;
+  /**
+   * Creates a fountain encoder for the given message.
+   *
+   * @param message - The message to encode
+   * @param maxFragmentLen - Maximum length of each fragment
+   */
+  constructor(message: Uint8Array, maxFragmentLen: number);
+  /**
+   * Returns the number of pure fragments.
+   */
+  get seqLen(): number;
+  /**
+   * Returns whether the message fits in a single part.
+   */
+  isSinglePart(): boolean;
+  /**
+   * Returns whether all pure parts have been emitted.
+   */
+  isComplete(): boolean;
+  /**
+   * Generates the next fountain part.
+   */
+  nextPart(): FountainPart;
+  /**
+   * Returns the current sequence number.
+   */
+  currentSeqNum(): number;
+  /**
+   * Resets the encoder to start from the beginning.
+   */
+  reset(): void;
+}
+/**
+ * Fountain decoder for reassembling multipart URs.
+ */
+declare class FountainDecoder {
+  private seqLen;
+  private messageLen;
+  private checksum;
+  private readonly pureFragments;
+  private readonly mixedParts;
+  /**
+   * Receives a fountain part and attempts to decode.
+   *
+   * @param part - The fountain part to receive
+   * @returns true if the message is now complete
+   */
+  receive(part: FountainPart): boolean;
+  /**
+   * Attempts to extract pure fragments from mixed parts.
+   */
+  private reduceMixedParts;
+  /**
+   * Returns whether all fragments have been received.
+   */
+  isComplete(): boolean;
+  /**
+   * Reconstructs the original message.
+   *
+   * @returns The original message, or null if not yet complete
+   */
+  message(): Uint8Array | null;
+  /**
+   * Returns the progress as a fraction (0 to 1).
+   */
+  progress(): number;
+  /**
+   * Resets the decoder.
+   */
+  reset(): void;
+}
+//#endregion
+//#region src/xoshiro.d.ts
+/**
+ * Xoshiro256** PRNG implementation.
+ *
+ * This is a high-quality, fast pseudo-random number generator used
+ * for deterministic fragment selection in fountain codes.
+ *
+ * Reference: https://prng.di.unimi.it/
+ */
+/**
+ * Xoshiro256** pseudo-random number generator.
+ *
+ * This PRNG is used for deterministic mixing in fountain codes,
+ * allowing both encoder and decoder to agree on which fragments
+ * are combined without transmitting that information.
+ */
+declare class Xoshiro256 {
+  private s;
+  /**
+   * Creates a new Xoshiro256** instance from a seed.
+   *
+   * The seed is hashed using SHA-256 to initialize the state.
+   * For consistent results across encoder/decoder, use the same seed.
+   *
+   * @param seed - The seed bytes (any length)
+   */
+  constructor(seed: Uint8Array);
+  /**
+   * Creates a Xoshiro256** instance from raw state values.
+   * Useful for seeding with specific values.
+   */
+  static fromState(s0: bigint, s1: bigint, s2: bigint, s3: bigint): Xoshiro256;
+  /**
+   * Simple hash function for seeding.
+   * This is a basic implementation - in production use SHA-256.
+   */
+  private hashSeed;
+  /**
+   * Converts 8 bytes to a 64-bit BigInt (little-endian).
+   */
+  private bytesToBigInt;
+  /**
+   * Generates the next 64-bit random value.
+   */
+  next(): bigint;
+  /**
+   * Generates a random double in [0, 1).
+   */
+  nextDouble(): number;
+  /**
+   * Generates a random integer in [low, high).
+   */
+  nextInt(low: number, high: number): number;
+  /**
+   * Generates a random byte [0, 255].
+   */
+  nextByte(): number;
+  /**
+   * Generates an array of random bytes.
+   */
+  nextData(count: number): Uint8Array;
+}
+/**
+ * Creates a seed for the Xoshiro PRNG from message checksum and sequence number.
+ *
+ * This ensures that both encoder and decoder produce the same random sequence
+ * for a given message and part number.
+ */
+declare function createSeed(checksum: number, seqNum: number): Uint8Array;
+//#endregion
+//#region src/utils.d.ts
+/**
+ * Checks if a character is a valid UR type character.
+ * Valid characters are lowercase letters, digits, and hyphens.
+ */
+declare function isURTypeChar(char: string): boolean;
+/**
+ * Checks if a string is a valid UR type.
+ * Valid UR types contain only lowercase letters, digits, and hyphens.
+ */
+declare function isValidURType(urType: string): boolean;
+/**
+ * Validates and returns a UR type, or throws an error if invalid.
+ */
+declare function validateURType(urType: string): string;
+/**
+ * Bytewords for encoding/decoding bytes as words.
+ * See: https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-004-bytewords.md
+ */
+declare const BYTEWORDS: string[];
+declare const BYTEWORDS_MAP: Map<string, number>;
+/**
+ * Bytemojis for encoding/decoding bytes as emojis.
+ * See: https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2024-008-bytemoji.md
+ */
+declare const BYTEMOJIS: string[];
+/**
+ * Encodes a 4-byte slice as a string of bytewords for identification.
+ */
+declare function encodeBytewordsIdentifier(data: Uint8Array): string;
+/**
+ * Encodes a 4-byte slice as a string of bytemojis for identification.
+ */
+declare function encodeBytemojisIdentifier(data: Uint8Array): string;
+/**
+ * Bytewords encoding style.
+ */
+declare enum BytewordsStyle {
+  /** Full 4-letter words separated by spaces */
+  Standard = "standard",
+  /** Full 4-letter words without separators */
+  Uri = "uri",
+  /** First and last character only (minimal) - used by UR encoding */
+  Minimal = "minimal",
+}
+declare const MINIMAL_BYTEWORDS_MAP: Map<string, number>;
+/**
+ * Calculate CRC32 checksum of data.
+ */
+declare function crc32(data: Uint8Array): number;
+/**
+ * Encode data as bytewords with the specified style.
+ * Includes CRC32 checksum.
+ */
+declare function encodeBytewords(data: Uint8Array, style?: BytewordsStyle): string;
+/**
+ * Decode bytewords string back to data.
+ * Validates and removes CRC32 checksum.
+ */
+declare function decodeBytewords(encoded: string, style?: BytewordsStyle): Uint8Array;
+//#endregion
+export { BYTEMOJIS, BYTEWORDS, BYTEWORDS_MAP, BytewordsError, BytewordsStyle, CBORError, FountainDecoder, FountainEncoder, type FountainPart, InvalidSchemeError, InvalidTypeError, MINIMAL_BYTEWORDS_MAP, MultipartDecoder, MultipartEncoder, NotSinglePartError, type Result, TypeUnspecifiedError, UR, type URCodable, type URDecodable, type UREncodable, URError, URType, UnexpectedTypeError, Xoshiro256, chooseFragments, crc32, createSeed, decodeBytewords, encodeBytemojisIdentifier, encodeBytewords, encodeBytewordsIdentifier, isError, isURCodable, isURDecodable, isUREncodable, isURTypeChar, isValidURType, mixFragments, splitMessage, validateURType, xorBytes };
+//# sourceMappingURL=index.d.cts.map