@fleet-sdk/common 0.2.2 → 0.3.0

package/dist/index.d.mts

@@ -22,13 +22,13 @@ declare const ergoTreeHeaderFlags: {
 };
 type ErgoTreeHeaderFlag = (typeof ergoTreeHeaderFlags)[keyof typeof ergoTreeHeaderFlags];
 
-type NonMandatoryRegisters = {
-    R4?: HexString;
-    R5?: HexString;
-    R6?: HexString;
-    R7?: HexString;
-    R8?: HexString;
-    R9?: HexString;
+type NonMandatoryRegisters<T = HexString> = {
+    R4?: T;
+    R5?: T;
+    R6?: T;
+    R7?: T;
+    R8?: T;
+    R9?: T;
 };
 
 type TokenId = string;
@@ -49,15 +49,13 @@ type TokenTargetAmount<AmountType> = {
     amount?: AmountType;
 };
 
-type ContextExtension = {
-    [key: number]: HexString | undefined;
+type ContextExtension<T = HexString> = {
+    [key: number]: T | undefined;
 };
-
 type ProverResult = {
     readonly proofBytes: HexString;
     readonly extension: ContextExtension;
 };
-
 type SignedInput = {
     readonly boxId: BoxId;
     readonly spendingProof: ProverResult;
@@ -106,22 +104,21 @@ type SignedTransaction = {
     readonly id: TransactionId;
     readonly inputs: SignedInput[];
     readonly dataInputs: DataInput[];
-    readonly outputs: Box<Amount>[];
+    readonly outputs: Box<string>[];
 };
 
 type BoxId = string;
-type AmountType = string | bigint;
-type BoxBaseType<T extends AmountType, R extends NonMandatoryRegisters> = {
+type BoxBaseType<T extends Amount, R extends NonMandatoryRegisters> = {
     ergoTree: ErgoTreeHex;
     creationHeight: number;
     value: T;
     assets: TokenAmount<T>[];
     additionalRegisters: R;
 };
-type BoxCandidate<T extends AmountType, R extends NonMandatoryRegisters = NonMandatoryRegisters> = BoxBaseType<T, R> & {
+type BoxCandidate<T extends Amount, R extends NonMandatoryRegisters = NonMandatoryRegisters> = BoxBaseType<T, R> & {
     boxId?: BoxId;
 };
-type Box<T extends AmountType, R extends NonMandatoryRegisters = NonMandatoryRegisters> = BoxBaseType<T, R> & {
+type Box<T extends Amount = Amount, R extends NonMandatoryRegisters = NonMandatoryRegisters> = BoxBaseType<T, R> & {
     boxId: BoxId;
     transactionId: TransactionId;
     index: number;
@@ -152,10 +149,10 @@ type BlockHeader = {
     difficulty: string;
     parentId: BlockHeaderId;
     votes: string;
-    size: number;
-    extensionId: HexString;
-    transactionsId: HexString;
-    adProofsId: HexString;
+    size?: number;
+    extensionId?: HexString;
+    transactionsId?: HexString;
+    adProofsId?: HexString;
 };
 type Block = {
     header: BlockHeader;
@@ -166,10 +163,25 @@ type Block = {
 };
 
 type ObjectSelector<T> = (item: T) => T[keyof T];
+/**
+ * Returns the first element of an array.
+ * @param array
+ * @throws an error if the array is empty.
+ */
 declare function first(array: undefined): undefined;
 declare function first<T>(array: ArrayLike<T>): T;
+/**
+ * Returns the last element of an array.
+ * @param array
+ * @throws an error if the array is empty.
+ */
 declare function last(array: undefined): undefined;
 declare function last<T>(array: ArrayLike<T>): T;
+/**
+ * Returns the element at the specified index. Negative indices are counted from the end of the array.
+ * @param array
+ * @param index
+ */
 declare function at(array: undefined, index: number): undefined;
 declare function at<T>(array: ArrayLike<T>, index: number): T;
 /**
@@ -180,14 +192,140 @@ declare function hasDuplicates<T>(array: T[]): boolean;
  * Check for duplicate keys in complex elements
  */
 declare function hasDuplicatesBy<T>(array: T[], selector: ObjectSelector<T>): boolean;
+/**
+ * Turns an array into chunks of the specified size
+ * @param array
+ * @param size
+ *
+ * @example
+ * ```
+ * const array = [1, 2, 3, 4, 5];
+ * const chunks = chunk(array, 2);
+ * console.log(chunks);
+ * // [[1, 2], [3, 4], [5]]
+ * ```
+ */
 declare function chunk<T>(array: T[], size: number): T[][];
+/**
+ * Sorts an array of objects by the specified property
+ * @param array
+ * @param iteratee
+ * @param order
+ *
+ * @example
+ * ```
+ * const array = [{ name: "John", age: 25 }, { name: "Jane", age: 30 }];
+ * const sorted = orderBy(array, (item) => item.age, "desc");
+ * console.log(sorted);
+ * // [{ name: "Jane", age: 30 }, { name: "John", age: 25 }]
+ * ```
+ */
 declare function orderBy<T>(array: T[], iteratee: SortingSelector<T>, order?: SortingDirection): T[];
+/**
+ * Checks if arrays are equal
+ * @param array1
+ * @param array2
+ *
+ * @example
+ * ```
+ * const array1 = [1, 2, 3];
+ * const array2 = [1, 2, 3];
+ * const array3 = [1, 2, 4];
+ * const array4 = [1, 2, 3, 4];
+ * areEqual(array1, array2); // true
+ * areEqual(array1, array3); // false
+ * areEqual(array1, array4); // false
+ * ```
+ */
 declare function areEqual<T>(array1: ArrayLike<T>, array2: ArrayLike<T>): boolean;
+/**
+ * Checks if arrays are equal by the specified property
+ * @param array1
+ * @param array2
+ * @param selector
+ *
+ * @example
+ * ```
+ * const array1 = [{ name: "John", age: 25 }, { name: "Jane", age: 30 }];
+ * const array2 = [{ name: "John", age: 25 }, { name: "Jane", age: 30 }];
+ * const array3 = [{ name: "John", age: 25 }, { name: "Jane", age: 31 }];
+ *
+ * areEqualBy(array1, array2, (item) => item.age); // true
+ * areEqualBy(array1, array3, (item) => item.age); // false
+ * ```
+ */
 declare function areEqualBy<T>(array1: ArrayLike<T>, array2: ArrayLike<T>, selector: ObjectSelector<T>): boolean;
+/**
+ * Checks if the array starts with the specified target
+ * @param array
+ * @param target
+ *
+ * @example
+ * ```
+ * const array = [1, 2, 3, 4, 5];
+ * const target1 = [1, 2];
+ * const target2 = [1, 3];
+ *
+ * startsWith(array, target1); // true
+ * startsWith(array, target2); // false
+ * ```
+ */
 declare function startsWith<T>(array: ArrayLike<T>, target: ArrayLike<T>): boolean;
+/**
+ * Checks if the array ends with the specified target
+ * @param array
+ * @param target
+ *
+ * @example
+ * ```
+ * const array = [1, 2, 3, 4, 5];
+ * const target1 = [4, 5];
+ * const target2 = [3, 5];
+ *
+ * endsWith(array, target1); // true
+ * endsWith(array, target2); // false
+ * ```
+ */
 declare function endsWith<T>(array: ArrayLike<T>, target: ArrayLike<T>): boolean;
+/**
+ * Makes an array unique by removing duplicate elements
+ * @param array
+ *
+ * @example
+ * ```
+ * const array = [1, 2, 3, 3, 4, 5, 5];
+ * const unique = uniq(array);
+ * console.log(unique);
+ * // [1, 2, 3, 4, 5]
+ * ```
+ */
 declare function uniq<T>(array: Array<T>): Array<T>;
+/**
+ * Makes an array unique by removing duplicate elements using the specified property
+ * @param array
+ * @param selector
+ * @param selection
+ *
+ * @example
+ * ```
+ * const array = [{ name: "John", age: 25 }, { name: "Jane", age: 30 }, { name: "John", age: 30 }];
+ * const unique = uniqBy(array, (item) => item.name);
+ * console.log(unique);
+ * // [{ name: "John", age: 25 }, { name: "Jane", age: 30 }]
+ * ```
+ */
 declare function uniqBy<T>(array: Array<T>, selector: ObjectSelector<T>, selection?: "keep-first" | "keep-last"): Array<T>;
+/**
+ * Returns the depth of an array
+ * @param array
+ *
+ * @example
+ * ```
+ * const array = [1, 2, 3, [4, 5, [6, 7]]];
+ * const depth = depthOf(array);
+ * console.log(depth);
+ * // 3
+ */
 declare function depthOf(array: unknown | unknown[]): number;
 
 type NumberLike = string | number | bigint | boolean;
@@ -198,6 +336,10 @@ declare const _10n: bigint;
 declare const _63n: bigint;
 declare const _127n: bigint;
 declare const _128n: bigint;
+/**
+ * Ensure that the given value is a bigint
+ * @param number
+ */
 declare function ensureBigInt(number: NumberLike): bigint;
 type ParsingOptions = {
     /**
@@ -210,6 +352,16 @@ type ParsingOptions = {
      */
     decimalMark?: string;
 };
+/**
+ * Parse a decimal string into a bigint with options
+ * @param decimalStr
+ * @param options
+ *
+ * @example
+ * undecimalize("129.8379183", { decimals: 9 }) // 129837918300n
+ * undecimalize("1", { decimals: 2 }) // 100n
+ * undecimalize("1", 2) // 100n
+ */
 declare function undecimalize(decimalStr: string, options?: ParsingOptions | number): bigint;
 type FormattingOptions = {
     /**
@@ -226,21 +378,135 @@ type FormattingOptions = {
      */
     decimalMark?: string;
 };
+/**
+ * Format a bigint into a decimal string with options
+ * @param value
+ * @param options
+ *
+ * @example
+ * decimalize(129837918300n, { decimals: 9 }) // "129.8379183"
+ * decimalize(100n, { decimals: 2 }) // "1"
+ */
 declare function decimalize(value: Amount, options?: FormattingOptions | number): string;
+/**
+ * Format a bigint percentage into a decimal string with options
+ * @param value
+ * @param percentage
+ * @param precision
+ *
+ * @example
+ * ```
+ * percent(3498n, 1n) // 34n(1%)
+ * percent(3498n, 2n) // 69n(2%)
+ * percent(3498n, 10n) // 349n(10%)
+ * ```
+ *
+ */
 declare function percent(value: bigint, percentage: bigint, precision?: bigint): bigint;
+/**
+ * Sum a collection of numbers by a given iteratee
+ * @param collection
+ * @param iteratee
+ * @param condition
+ *
+ * @example
+ * ```
+ * const values = [
+ *  { key: 1, value: 100n },
+ *  { key: 2, value: 200n },
+ *  { key: 3, value: 300n },
+ *  { key: 4, value: 400n },
+ *  ];
+ *
+ *  sumBy(values, x => x.value) // 1000n
+ *  sumBy(values, x => x.value, x => x.key < 0) // 0n
+ *  sumBy(values, x => x.value, x => x.key % 2 === 0) // 600n
+ */
 declare function sumBy<T>(collection: readonly T[], iteratee: (value: T) => bigint, condition?: (value: T) => boolean): bigint;
+/**
+ * Get the minimum value from a collection of numbers
+ * @param numbers
+ */
 declare function min<T extends bigint | number>(...numbers: T[]): T;
+/**
+ * Get the maximum value from a collection of numbers
+ * @param numbers
+ */
 declare function max<T extends bigint | number>(...numbers: T[]): T;
 
-declare function utxoSum(boxes: MinimalBoxAmounts): BoxSummary;
-declare function utxoSum(boxes: MinimalBoxAmounts, tokenId: TokenId): bigint;
+/**
+ * Calculates the sum of all nanoErgs and tokens in the given boxes.
+ * @param boxes
+ *
+ * @example
+ * ```
+ * const boxes = [
+ *   { value: "10", assets: [{ tokenId: "test", amount: "20" }] },
+ *   { value: 20n, assets: [{ tokenId: "test", amount: 30n }] }
+ * ];
+ *
+ * const sum = utxoSum(boxes);
+ * console.log(sum);
+ * // { nanoErgs: 30n, tokens: [{ tokenId: "test", amount: 50n }] }
+ * ```
+ */
+declare function utxoSum(boxes: MinimalBoxAmountsArray): BoxSummary;
+declare function utxoSum(boxes: MinimalBoxAmountsArray, tokenId: TokenId): bigint;
+/**
+ * Calculates the difference between two utxos or utxo sets.
+ * @param minuend
+ * @param subtrahend
+ *
+ * @example
+ * ```
+ * const minuend = [{ nanoErgs: 30n, tokens: [{ tokenId: "test", amount: 50n }] }];
+ * const subtrahend = [{ nanoErgs: 10n, tokens: [{ tokenId: "test", amount: 20n }] }];
+ * const diff = utxoDiff(minuend, subtrahend);
+ * console.log(diff);
+ * // { nanoErgs: 20n, tokens: [{ tokenId: "test", amount: 30n }] }
+ * ```
+ */
 declare function utxoDiff(minuend: BoxSummary | Box<Amount>[], subtrahend: BoxSummary | Box<Amount>[]): BoxSummary;
+/**
+ * Checks if the given registers are densely packed.
+ * @param registers
+ *
+ * @example
+ * ```
+ * const registers = {
+ *   R4: "deadbeef",
+ *   R6: "cafe",
+ * };
+ * const result = areRegistersDenselyPacked(registers);
+ * console.log(result);
+ * // false
+ */
 declare function areRegistersDenselyPacked(registers: NonMandatoryRegisters): boolean;
-declare function utxoFilter<T extends AmountType>(utxos: Box<T>[], filterParams: UTxOFilterParams<T>): Box<T>[];
-type UTxOFilterParams<T extends AmountType> = {
+/**
+ * Filters the given utxos by the given filter parameters.
+ * @param utxos
+ * @param filterParams
+ */
+declare function utxoFilter<T extends Amount>(utxos: Box<T>[], filterParams: UTxOFilterParams<T>): Box<T>[];
+/**
+ * Parameters for filtering unspent transaction outputs (UTxOs).
+ */
+type UTxOFilterParams<T extends Amount> = {
+    /**
+     * A function that returns a boolean indicating whether a given UTxO should be included in the filtered results.
+     */
     by?: (utxo: Box<T>) => boolean;
+    /**
+     * An object specifying the maximum number of UTxOs and distinct tokens to include in the filtered results.
+     */
     max?: {
+        /**
+         * The maximum number of UTxOs to include in the filtered results.
+         */
         count?: number;
+        /**
+         * The maximum number of distinct tokens to include in the filtered results.
+         */
         aggregatedDistinctTokens?: number;
     };
 };
@@ -248,15 +514,43 @@ type BoxSummary = {
     nanoErgs: bigint;
     tokens: TokenAmount<bigint>[];
 };
-type MinimalBoxAmounts = readonly {
+type MinimalBoxAmountsArray = readonly {
     value: Amount;
     assets: TokenAmount<Amount>[];
 }[];
+/**
+ * Ensures that the value and asset amounts of a given box are represented as BigInts.
+ * @returns A new box object with BigInt representation for the value and asset amounts.
+ */
 declare function ensureUTxOBigInt(box: Box<Amount>): Box<bigint>;
 declare function ensureUTxOBigInt(candidate: BoxCandidate<Amount>): BoxCandidate<bigint>;
 
+/**
+ * Remove undefined values from an object
+ * @param value
+ *
+ * @example
+ * ```
+ * const obj = { a: 1, b: undefined };
+ * const result = clearUndefined(obj);
+ * console.log(result); // { a: 1 }
+ * ```
+ */
 declare function clearUndefined(value: Record<string, unknown>): Record<string, unknown>;
-declare function ensureDefaults<T extends Partial<R>, R extends object = Required<T>>(options: T | undefined, defaults: R): R & T;
+/**
+ * Ensure that the options object has all the default values
+ * @param options
+ * @param defaults
+ *
+ * @example
+ * ```
+ * const options = { a: 1 };
+ * const defaults = { a: 2, b: 3 };
+ * const result = ensureDefaults(options, defaults);
+ * console.log(result); // { a: 1, b: 3 }
+ * ```
+ */
+declare function ensureDefaults<T extends object, R extends object>(options: T | undefined, defaults: R): R & T;
 
 type AssertErrorMessageInput = string | Error | (() => string);
 type Constructable = Function;
@@ -264,10 +558,8 @@ type JSPrimitiveTypes = "string" | "number" | "bigint" | "boolean" | "symbol" |
 declare function assert(condition: boolean, error: AssertErrorMessageInput): asserts condition;
 declare function assertTypeOf<T>(obj: T, expected: JSPrimitiveTypes): asserts obj;
 declare function assertInstanceOf<T>(obj: T, expected: Constructable): asserts obj;
-declare function isEmpty<T extends object>(obj?: T): obj is undefined;
-declare function isEmpty<T>(array?: T[]): array is undefined;
-declare function some<T extends object>(obj?: T): obj is T;
-declare function some<T>(array?: T[]): array is T[];
+declare function isEmpty<T>(target: T | null | undefined): target is undefined | null;
+declare function some<T>(target: T | null | undefined): target is T;
 declare function isTruthy<T>(value?: T): value is NonNullable<T>;
 declare function isFalsy<T>(value?: T): value is undefined;
 declare function isUndefined(v: unknown): v is undefined;
@@ -286,21 +578,71 @@ declare function byteSizeOf(hex: string): number;
 type CollectionAddOptions = {
     index?: number;
 };
+/**
+ * Collection abstract model
+ *
+ * @example
+ * Define a new collection class with internal type `number` and external type `string`
+ * ```
+ * class TestCollection extends Collection<number, string> {
+ *    protected _map(item: string | number): number {
+ *      return Number(item);
+ *    }
+ *    // Some other methods
+ *  }
+ * ```
+ *
+ */
 declare abstract class Collection<InternalType, ExternalType> implements Iterable<InternalType> {
     protected readonly _items: InternalType[];
     constructor();
     protected _isIndexOutOfBounds(index: number): boolean;
     [Symbol.iterator](): Iterator<InternalType>;
+    /**
+     * Number of items in the collection
+     */
     get length(): number;
+    /**
+     * True if the collection is empty
+     */
     get isEmpty(): boolean;
+    /**
+     * Get item at index
+     * @param index
+     * @throws RangeError if index is out of bounds
+     */
     at(index: number): InternalType;
+    /**
+     * Add item to the collection
+     * @param items
+     * @param options
+     * @returns The new length of the collection
+     */
     add(items: OneOrMore<ExternalType>, options?: CollectionAddOptions): number;
     abstract remove(item: unknown): number;
+    /**
+     * Map external type to internal type
+     * @param item
+     * @protected
+     */
     protected abstract _map(item: ExternalType | InternalType): InternalType;
     protected _addOne(item: InternalType | ExternalType, options?: CollectionAddOptions): number;
     protected _addOneOrMore(items: OneOrMore<ExternalType>, options?: CollectionAddOptions): number;
+    /**
+     * Get the collection as an array
+     */
     toArray(): InternalType[];
     reduce<U>(callbackFn: (accumulator: U, currentValue: InternalType, currentIndex: number, array: InternalType[]) => U, initialValue: U): U;
 }
 
-export { AddressType, Amount, AmountType, AssertErrorMessageInput, Base58String, Block, BlockHeader, BlockHeaderId, BlockTransactions, Box, BoxCandidate, BoxId, BoxSummary, BuildOutputType, Collection, CollectionAddOptions, ContextExtension, DataInput, EIP12UnsignedDataInput, EIP12UnsignedInput, EIP12UnsignedTransaction, ErgoTreeHeaderFlag, ErgoTreeHex, FilterPredicate, HexString, MinimalBoxAmounts, Network, NewToken, NonMandatoryRegisters, OneOrMore, PoWSolution, ProverResult, SignedInput, SignedTransaction, SortingDirection, SortingSelector, TokenAmount, TokenId, TokenTargetAmount, TransactionId, UTxOFilterParams, UnsignedInput, UnsignedTransaction, _0n, _10n, _127n, _128n, _1n, _63n, _7n, areEqual, areEqualBy, areRegistersDenselyPacked, assert, assertInstanceOf, assertTypeOf, at, byteSizeOf, chunk, clearUndefined, concatBytes, decimalize, depthOf, endsWith, ensureBigInt, ensureDefaults, ensureUTxOBigInt, ergoTreeHeaderFlags, first, hasDuplicates, hasDuplicatesBy, hasKey, isDefined, isEmpty, isFalsy, isHex, isTruthy, isUndefined, last, max, min, orderBy, percent, some, startsWith, sumBy, undecimalize, uniq, uniqBy, utxoDiff, utxoFilter, utxoSum };
+declare class FleetError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+declare class NotSupportedError extends FleetError {
+    constructor(message?: string);
+}
+declare class BlockchainProviderError extends FleetError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+
+export { AddressType, Amount, AssertErrorMessageInput, Base58String, Block, BlockHeader, BlockHeaderId, BlockTransactions, BlockchainProviderError, Box, BoxCandidate, BoxId, BoxSummary, BuildOutputType, Collection, CollectionAddOptions, ContextExtension, DataInput, EIP12UnsignedDataInput, EIP12UnsignedInput, EIP12UnsignedTransaction, ErgoTreeHeaderFlag, ErgoTreeHex, FilterPredicate, FleetError, HexString, MinimalBoxAmountsArray, Network, NewToken, NonMandatoryRegisters, NotSupportedError, OneOrMore, PoWSolution, ProverResult, SignedInput, SignedTransaction, SortingDirection, SortingSelector, TokenAmount, TokenId, TokenTargetAmount, TransactionId, UTxOFilterParams, UnsignedInput, UnsignedTransaction, _0n, _10n, _127n, _128n, _1n, _63n, _7n, areEqual, areEqualBy, areRegistersDenselyPacked, assert, assertInstanceOf, assertTypeOf, at, byteSizeOf, chunk, clearUndefined, concatBytes, decimalize, depthOf, endsWith, ensureBigInt, ensureDefaults, ensureUTxOBigInt, ergoTreeHeaderFlags, first, hasDuplicates, hasDuplicatesBy, hasKey, isDefined, isEmpty, isFalsy, isHex, isTruthy, isUndefined, last, max, min, orderBy, percent, some, startsWith, sumBy, undecimalize, uniq, uniqBy, utxoDiff, utxoFilter, utxoSum };