@talismn/util 0.5.5 → 0.5.7

package/dist/index.d.mts

@@ -0,0 +1,270 @@
+import * as tailwind_merge from 'tailwind-merge';
+import { OperatorFunction, Observable, Subject, ReplaySubject } from 'rxjs';
+import BigNumber from 'bignumber.js';
+
+declare const addTrailingSlash: (url: string) => string;
+
+/**
+ * Javascript's `Math` library for `BigInt`.
+ * Taken from https://stackoverflow.com/questions/51867270/is-there-a-library-similar-to-math-that-supports-javascript-bigint/64953280#64953280
+ */
+declare const BigMath: {
+    abs(x: bigint): bigint;
+    sign(x: bigint): 0n | 1n | -1n;
+    min(value: bigint, ...values: bigint[]): bigint;
+    max(value: bigint, ...values: bigint[]): bigint;
+};
+
+declare const classNames: (...classLists: tailwind_merge.ClassNameValue[]) => string;
+declare const cn: (...classLists: tailwind_merge.ClassNameValue[]) => string;
+
+/**
+ * In TypeScript, a deferred promise refers to a pattern that involves creating a promise that can be
+ * resolved or rejected at a later point in time, typically by code outside of the current function scope.
+ *
+ * This pattern is often used when dealing with asynchronous operations that involve multiple steps or when
+ * the result of an operation cannot be immediately determined.
+ */
+declare function Deferred<T>(): {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: unknown) => void;
+    isPending: () => boolean;
+    isResolved: () => boolean;
+    isRejected: () => boolean;
+};
+
+/** biome-ignore-all lint/complexity/noBannedTypes: legacy */
+type FunctionPropertyNames<T> = {
+    [K in keyof T]: T[K] extends Function ? K : never;
+}[keyof T];
+type FunctionProperties<T> = Pick<T, FunctionPropertyNames<T>>;
+type NonFunctionPropertyNames<T> = {
+    [K in keyof T]: T[K] extends Function ? never : K;
+}[keyof T];
+type NonFunctionProperties<T> = Pick<T, NonFunctionPropertyNames<T>>;
+
+/**
+ * An rxjs operator which:
+ *
+ * 1. Emits the first value it receives from the source observable, then:
+ * 2. Debounces any future values by `timeout` ms.
+ */
+declare const firstThenDebounce: <T>(timeout: number) => OperatorFunction<T, T>;
+
+declare const MAX_DECIMALS_FORMAT = 12;
+/**
+ * Custom decimal number formatting for Talisman
+ * note that the NumberFormat().format() call is the ressource heavy part, it's not worth trying to optimize other parts
+ * @param num input number
+ * @param digits number of significant digits to display
+ * @param locale locale used to format the number
+ * @param options formatting options
+ * @returns the formatted value
+ */
+declare const formatDecimals: (num?: string | number | null | BigNumber, digits?: number, options?: Partial<Intl.NumberFormatOptions>, locale?: string) => string;
+
+declare const formatPrice: (price: number, currency: string, compact: boolean) => string;
+
+type LoadableError = {
+    name: string;
+    message: string;
+};
+type Loadable<T = unknown> = {
+    status: "loading";
+    data?: T;
+    error?: undefined;
+} | {
+    status: "success";
+    data: T;
+    error?: undefined;
+} | {
+    status: "error";
+    data?: T;
+    error: LoadableError;
+};
+type LoadableStatus = Loadable["status"];
+type LoadableOptions = {
+    getError?: (error: unknown) => LoadableError;
+    refreshInterval?: number;
+};
+declare function getLoadable$<T>(factory: () => Promise<T>, options?: LoadableOptions): Observable<Loadable<T>>;
+
+type GetLoadableQueryParams<TArgs extends unknown[], TResult> = {
+    namespace: string;
+    args: TArgs;
+    queryFn: (args: TArgs, signal: AbortSignal) => Promise<TResult>;
+    refreshInterval?: number;
+    defaultValue?: TResult;
+};
+/**
+ * Thin wrapper around getQuery$ that returns Loadable<T> and optionally
+ * primes the stream with a loading state using the provided default value.
+ *
+ * TODO: consolidate with getQuery$
+ */
+declare const getLoadableQuery$: <TArgs extends unknown[], TResult>(params: GetLoadableQueryParams<TArgs, TResult>) => Observable<Loadable<TResult>>;
+
+type QueryStatus = "loading" | "loaded" | "error";
+type QueryResult<T, S extends QueryStatus = "loading" | "loaded" | "error"> = S extends "loading" ? {
+    status: "loading";
+    data: T | undefined;
+    error: undefined;
+} : S extends "loaded" ? {
+    status: "loaded";
+    data: T;
+    error: undefined;
+} : {
+    status: "error";
+    data: undefined;
+    error: unknown;
+};
+type QueryOptions<Output, Args> = {
+    namespace: string;
+    args: Args;
+    queryFn: (args: Args, signal: AbortSignal) => Promise<Output>;
+    defaultValue?: Output;
+    refreshInterval?: number;
+    serializer?: (args: Args) => string;
+};
+/**
+ * Creates a shared observable for executing queries with caching, loading states, and automatic refresh capabilities.
+ *
+ * @example
+ * ```typescript
+ * const userQuery$ = getQuery$({
+ *   namespace: 'users',
+ *   args: { userId: 123 },
+ *   queryFn: async ({ userId }) => fetchUser(userId),
+ *   defaultValue: null,
+ *   refreshInterval: 30000
+ * });
+ *
+ * userQuery$.subscribe(result => {
+ *   if (result.status === 'loaded') {
+ *     console.log(result.data);
+ *   }
+ * });
+ * ```
+ *
+ * @deprecated use getLoadableQuery$ instead
+ */
+declare const getQuery$: <Output, Args>({ namespace, args, queryFn, defaultValue, refreshInterval, serializer, }: QueryOptions<Output, Args>) => Observable<QueryResult<Output>>;
+
+/**
+ * When using react-rxjs hooks and state observables, the options are used as weak map keys.
+ * This means that if the options object is recreated on each render, the observable will be recreated as well.
+ * This utility function allows you to create a shared observable based on a namespace and arguments that, so react-rxjs can reuse the same observables
+ *
+ * @param namespace
+ * @param args
+ * @param createObservable
+ * @param serializer
+ * @returns
+ */
+declare const getSharedObservable: <Args, Output, ObsOutput = Observable<Output>>(namespace: string, args: Args, createObservable: (args: Args) => ObsOutput, serializer?: (args: Args) => string) => ObsOutput;
+
+declare function hasOwnProperty<X, Y extends PropertyKey>(obj: X, prop: Y): obj is X & Record<Y, unknown>;
+
+declare const isAbortError: (error: unknown) => boolean;
+
+declare function isArrayOf<T, P extends Array<unknown>>(array: unknown[], func: new (...args: P) => T): array is T[];
+
+declare const isAscii: (str: string) => boolean;
+
+declare const isBigInt: (value: unknown) => value is bigint;
+
+declare const isBooleanTrue: <T>(x: T | null | undefined) => x is T;
+
+type HexString = `0x${string}`;
+declare const REGEX_HEX_STRING: RegExp;
+declare const isHexString: (value: unknown) => value is HexString;
+
+/**
+ * WARNING: This function only checks against null or undefined, it does not coerce the value.
+ * ie: false and 0 are considered not nil
+ * Use isTruthy instead for a regular coercion check.
+ *
+ * @param value
+ * @returns whether the value is neither null nor undefined
+ */
+declare const isNotNil: <T>(value: T | null | undefined) => value is T;
+
+declare const isPromise: <T = any>(value: any) => value is Promise<T>;
+
+/**
+ * Tests to see if an object is an RxJS {@link Subject}.
+ */
+declare function isSubject<T>(object?: Subject<T> | object): object is Subject<T>;
+
+declare const isTruthy: <T>(value: T | null | undefined) => value is T;
+
+/**
+ * An RxJS operator that keeps the source observable alive for a specified duration
+ * after all subscribers have unsubscribed. This prevents expensive re-subscriptions
+ * when subscribers come and go frequently.
+ *
+ * @param keepAliveMs - Duration in milliseconds to keep the source alive after last unsubscription
+ * @returns MonoTypeOperatorFunction that can be used in pipe()
+ *
+ * @example
+ * ```typescript
+ * const data$ = expensive_api_call$.pipe(
+ *   keepAlive(3000) // Keep alive for 3 seconds
+ * );
+ * ```
+ */
+declare const keepAlive: <T>(timeout: number) => OperatorFunction<T, T>;
+
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+declare function planckToTokens(planck: string, tokenDecimals: number): string;
+declare function planckToTokens(planck: string, tokenDecimals?: number): string | undefined;
+declare function planckToTokens(planck?: string, tokenDecimals?: number): string | undefined;
+
+/**
+ * Turns a value into a {@link ReplaySubject} of size 1.
+ *
+ * If the value is already a {@link ReplaySubject}, it will be returned as-is.
+ *
+ * If the value is a {@link Promise}, it will be awaited,
+ * and the awaited value will be published into the {@link ReplaySubject} when it becomes available.
+ *
+ * For any other type of value, it will be immediately published into the {@link ReplaySubject}.
+ */
+declare const replaySubjectFrom: <T>(initialValue: T | Promise<T> | ReplaySubject<T>) => ReplaySubject<T>;
+
+declare const sleep: (ms: number) => Promise<void>;
+
+/**
+ * Takes a subject and splits it into two parts:
+ *
+ * 1. A function to submit new values into the subject.
+ * 2. An observable for subscribing to new values from the subject.
+ *
+ * This can be helpful when, to avoid bugs, you want to expose only one
+ * of these parts to external code and keep the other part private.
+ */
+declare function splitSubject<T>(subject: Subject<T>): readonly [(value: T) => void, Observable<T>];
+
+declare const throwAfter: (ms: number, reason: string) => Promise<never>;
+
+declare function tokensToPlanck(tokens: string, tokenDecimals: number): string;
+declare function tokensToPlanck(tokens: string, tokenDecimals?: number): string | undefined;
+declare function tokensToPlanck(tokens?: string, tokenDecimals?: number): string | undefined;
+
+/**
+ * @name validateHexString
+ * @description Checks if a string is a hex string. Required to account for type differences between different polkadot libraries
+ * @param {string} str - string to check
+ * @returns {`0x${string}`} - boolean
+ * @example
+ * validateHexString("0x1234") // "0x1234"
+ * validateHexString("1234") // Error: Expected a hex string
+ * validateHexString(1234) // Error: Expected a string
+ **/
+declare const validateHexString: (str: string) => `0x${string}`;
+
+export { BigMath, Deferred, type FunctionProperties, type FunctionPropertyNames, type GetLoadableQueryParams, type HexString, type Loadable, type LoadableOptions, type LoadableStatus, MAX_DECIMALS_FORMAT, type NonFunctionProperties, type NonFunctionPropertyNames, type Prettify, type QueryResult, type QueryStatus, REGEX_HEX_STRING, addTrailingSlash, classNames, cn, firstThenDebounce, formatDecimals, formatPrice, getLoadable$, getLoadableQuery$, getQuery$, getSharedObservable, hasOwnProperty, isAbortError, isArrayOf, isAscii, isBigInt, isBooleanTrue, isHexString, isNotNil, isPromise, isSubject, isTruthy, keepAlive, planckToTokens, replaySubjectFrom, sleep, splitSubject, throwAfter, tokensToPlanck, validateHexString };

package/dist/index.d.ts

@@ -0,0 +1,270 @@
+import * as tailwind_merge from 'tailwind-merge';
+import { OperatorFunction, Observable, Subject, ReplaySubject } from 'rxjs';
+import BigNumber from 'bignumber.js';
+
+declare const addTrailingSlash: (url: string) => string;
+
+/**
+ * Javascript's `Math` library for `BigInt`.
+ * Taken from https://stackoverflow.com/questions/51867270/is-there-a-library-similar-to-math-that-supports-javascript-bigint/64953280#64953280
+ */
+declare const BigMath: {
+    abs(x: bigint): bigint;
+    sign(x: bigint): 0n | 1n | -1n;
+    min(value: bigint, ...values: bigint[]): bigint;
+    max(value: bigint, ...values: bigint[]): bigint;
+};
+
+declare const classNames: (...classLists: tailwind_merge.ClassNameValue[]) => string;
+declare const cn: (...classLists: tailwind_merge.ClassNameValue[]) => string;
+
+/**
+ * In TypeScript, a deferred promise refers to a pattern that involves creating a promise that can be
+ * resolved or rejected at a later point in time, typically by code outside of the current function scope.
+ *
+ * This pattern is often used when dealing with asynchronous operations that involve multiple steps or when
+ * the result of an operation cannot be immediately determined.
+ */
+declare function Deferred<T>(): {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: unknown) => void;
+    isPending: () => boolean;
+    isResolved: () => boolean;
+    isRejected: () => boolean;
+};
+
+/** biome-ignore-all lint/complexity/noBannedTypes: legacy */
+type FunctionPropertyNames<T> = {
+    [K in keyof T]: T[K] extends Function ? K : never;
+}[keyof T];
+type FunctionProperties<T> = Pick<T, FunctionPropertyNames<T>>;
+type NonFunctionPropertyNames<T> = {
+    [K in keyof T]: T[K] extends Function ? never : K;
+}[keyof T];
+type NonFunctionProperties<T> = Pick<T, NonFunctionPropertyNames<T>>;
+
+/**
+ * An rxjs operator which:
+ *
+ * 1. Emits the first value it receives from the source observable, then:
+ * 2. Debounces any future values by `timeout` ms.
+ */
+declare const firstThenDebounce: <T>(timeout: number) => OperatorFunction<T, T>;
+
+declare const MAX_DECIMALS_FORMAT = 12;
+/**
+ * Custom decimal number formatting for Talisman
+ * note that the NumberFormat().format() call is the ressource heavy part, it's not worth trying to optimize other parts
+ * @param num input number
+ * @param digits number of significant digits to display
+ * @param locale locale used to format the number
+ * @param options formatting options
+ * @returns the formatted value
+ */
+declare const formatDecimals: (num?: string | number | null | BigNumber, digits?: number, options?: Partial<Intl.NumberFormatOptions>, locale?: string) => string;
+
+declare const formatPrice: (price: number, currency: string, compact: boolean) => string;
+
+type LoadableError = {
+    name: string;
+    message: string;
+};
+type Loadable<T = unknown> = {
+    status: "loading";
+    data?: T;
+    error?: undefined;
+} | {
+    status: "success";
+    data: T;
+    error?: undefined;
+} | {
+    status: "error";
+    data?: T;
+    error: LoadableError;
+};
+type LoadableStatus = Loadable["status"];
+type LoadableOptions = {
+    getError?: (error: unknown) => LoadableError;
+    refreshInterval?: number;
+};
+declare function getLoadable$<T>(factory: () => Promise<T>, options?: LoadableOptions): Observable<Loadable<T>>;
+
+type GetLoadableQueryParams<TArgs extends unknown[], TResult> = {
+    namespace: string;
+    args: TArgs;
+    queryFn: (args: TArgs, signal: AbortSignal) => Promise<TResult>;
+    refreshInterval?: number;
+    defaultValue?: TResult;
+};
+/**
+ * Thin wrapper around getQuery$ that returns Loadable<T> and optionally
+ * primes the stream with a loading state using the provided default value.
+ *
+ * TODO: consolidate with getQuery$
+ */
+declare const getLoadableQuery$: <TArgs extends unknown[], TResult>(params: GetLoadableQueryParams<TArgs, TResult>) => Observable<Loadable<TResult>>;
+
+type QueryStatus = "loading" | "loaded" | "error";
+type QueryResult<T, S extends QueryStatus = "loading" | "loaded" | "error"> = S extends "loading" ? {
+    status: "loading";
+    data: T | undefined;
+    error: undefined;
+} : S extends "loaded" ? {
+    status: "loaded";
+    data: T;
+    error: undefined;
+} : {
+    status: "error";
+    data: undefined;
+    error: unknown;
+};
+type QueryOptions<Output, Args> = {
+    namespace: string;
+    args: Args;
+    queryFn: (args: Args, signal: AbortSignal) => Promise<Output>;
+    defaultValue?: Output;
+    refreshInterval?: number;
+    serializer?: (args: Args) => string;
+};
+/**
+ * Creates a shared observable for executing queries with caching, loading states, and automatic refresh capabilities.
+ *
+ * @example
+ * ```typescript
+ * const userQuery$ = getQuery$({
+ *   namespace: 'users',
+ *   args: { userId: 123 },
+ *   queryFn: async ({ userId }) => fetchUser(userId),
+ *   defaultValue: null,
+ *   refreshInterval: 30000
+ * });
+ *
+ * userQuery$.subscribe(result => {
+ *   if (result.status === 'loaded') {
+ *     console.log(result.data);
+ *   }
+ * });
+ * ```
+ *
+ * @deprecated use getLoadableQuery$ instead
+ */
+declare const getQuery$: <Output, Args>({ namespace, args, queryFn, defaultValue, refreshInterval, serializer, }: QueryOptions<Output, Args>) => Observable<QueryResult<Output>>;
+
+/**
+ * When using react-rxjs hooks and state observables, the options are used as weak map keys.
+ * This means that if the options object is recreated on each render, the observable will be recreated as well.
+ * This utility function allows you to create a shared observable based on a namespace and arguments that, so react-rxjs can reuse the same observables
+ *
+ * @param namespace
+ * @param args
+ * @param createObservable
+ * @param serializer
+ * @returns
+ */
+declare const getSharedObservable: <Args, Output, ObsOutput = Observable<Output>>(namespace: string, args: Args, createObservable: (args: Args) => ObsOutput, serializer?: (args: Args) => string) => ObsOutput;
+
+declare function hasOwnProperty<X, Y extends PropertyKey>(obj: X, prop: Y): obj is X & Record<Y, unknown>;
+
+declare const isAbortError: (error: unknown) => boolean;
+
+declare function isArrayOf<T, P extends Array<unknown>>(array: unknown[], func: new (...args: P) => T): array is T[];
+
+declare const isAscii: (str: string) => boolean;
+
+declare const isBigInt: (value: unknown) => value is bigint;
+
+declare const isBooleanTrue: <T>(x: T | null | undefined) => x is T;
+
+type HexString = `0x${string}`;
+declare const REGEX_HEX_STRING: RegExp;
+declare const isHexString: (value: unknown) => value is HexString;
+
+/**
+ * WARNING: This function only checks against null or undefined, it does not coerce the value.
+ * ie: false and 0 are considered not nil
+ * Use isTruthy instead for a regular coercion check.
+ *
+ * @param value
+ * @returns whether the value is neither null nor undefined
+ */
+declare const isNotNil: <T>(value: T | null | undefined) => value is T;
+
+declare const isPromise: <T = any>(value: any) => value is Promise<T>;
+
+/**
+ * Tests to see if an object is an RxJS {@link Subject}.
+ */
+declare function isSubject<T>(object?: Subject<T> | object): object is Subject<T>;
+
+declare const isTruthy: <T>(value: T | null | undefined) => value is T;
+
+/**
+ * An RxJS operator that keeps the source observable alive for a specified duration
+ * after all subscribers have unsubscribed. This prevents expensive re-subscriptions
+ * when subscribers come and go frequently.
+ *
+ * @param keepAliveMs - Duration in milliseconds to keep the source alive after last unsubscription
+ * @returns MonoTypeOperatorFunction that can be used in pipe()
+ *
+ * @example
+ * ```typescript
+ * const data$ = expensive_api_call$.pipe(
+ *   keepAlive(3000) // Keep alive for 3 seconds
+ * );
+ * ```
+ */
+declare const keepAlive: <T>(timeout: number) => OperatorFunction<T, T>;
+
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+declare function planckToTokens(planck: string, tokenDecimals: number): string;
+declare function planckToTokens(planck: string, tokenDecimals?: number): string | undefined;
+declare function planckToTokens(planck?: string, tokenDecimals?: number): string | undefined;
+
+/**
+ * Turns a value into a {@link ReplaySubject} of size 1.
+ *
+ * If the value is already a {@link ReplaySubject}, it will be returned as-is.
+ *
+ * If the value is a {@link Promise}, it will be awaited,
+ * and the awaited value will be published into the {@link ReplaySubject} when it becomes available.
+ *
+ * For any other type of value, it will be immediately published into the {@link ReplaySubject}.
+ */
+declare const replaySubjectFrom: <T>(initialValue: T | Promise<T> | ReplaySubject<T>) => ReplaySubject<T>;
+
+declare const sleep: (ms: number) => Promise<void>;
+
+/**
+ * Takes a subject and splits it into two parts:
+ *
+ * 1. A function to submit new values into the subject.
+ * 2. An observable for subscribing to new values from the subject.
+ *
+ * This can be helpful when, to avoid bugs, you want to expose only one
+ * of these parts to external code and keep the other part private.
+ */
+declare function splitSubject<T>(subject: Subject<T>): readonly [(value: T) => void, Observable<T>];
+
+declare const throwAfter: (ms: number, reason: string) => Promise<never>;
+
+declare function tokensToPlanck(tokens: string, tokenDecimals: number): string;
+declare function tokensToPlanck(tokens: string, tokenDecimals?: number): string | undefined;
+declare function tokensToPlanck(tokens?: string, tokenDecimals?: number): string | undefined;
+
+/**
+ * @name validateHexString
+ * @description Checks if a string is a hex string. Required to account for type differences between different polkadot libraries
+ * @param {string} str - string to check
+ * @returns {`0x${string}`} - boolean
+ * @example
+ * validateHexString("0x1234") // "0x1234"
+ * validateHexString("1234") // Error: Expected a hex string
+ * validateHexString(1234) // Error: Expected a string
+ **/
+declare const validateHexString: (str: string) => `0x${string}`;
+
+export { BigMath, Deferred, type FunctionProperties, type FunctionPropertyNames, type GetLoadableQueryParams, type HexString, type Loadable, type LoadableOptions, type LoadableStatus, MAX_DECIMALS_FORMAT, type NonFunctionProperties, type NonFunctionPropertyNames, type Prettify, type QueryResult, type QueryStatus, REGEX_HEX_STRING, addTrailingSlash, classNames, cn, firstThenDebounce, formatDecimals, formatPrice, getLoadable$, getLoadableQuery$, getQuery$, getSharedObservable, hasOwnProperty, isAbortError, isArrayOf, isAscii, isBigInt, isBooleanTrue, isHexString, isNotNil, isPromise, isSubject, isTruthy, keepAlive, planckToTokens, replaySubjectFrom, sleep, splitSubject, throwAfter, tokensToPlanck, validateHexString };