@lukso/transaction-decoder 1.0.1-dev.0f1bea5

package/src/shared/cache.ts

@@ -0,0 +1,144 @@
+import type { DataKey, EnhancedInfo } from '../types'
+
+/**
+ * Address identity cache interface
+ * Can be implemented with different backends (LRU, Redis, etc.)
+ */
+export interface AddressIdentityCache {
+  /**
+   * Get cached address data
+   */
+  get(
+    key: DataKey
+  ): EnhancedInfo | undefined | Promise<EnhancedInfo | undefined>
+
+  /**
+   * Set address data in cache
+   */
+  set(key: DataKey, value: EnhancedInfo): void | Promise<void>
+
+  /**
+   * Check if address is in cache
+   */
+  has(key: DataKey): boolean | Promise<boolean>
+
+  /**
+   * Get multiple addresses at once
+   */
+  getMany?(
+    keys: readonly DataKey[]
+  ): Map<DataKey, EnhancedInfo> | Promise<Map<DataKey, EnhancedInfo>>
+
+  /**
+   * Set multiple addresses at once
+   */
+  setMany?(entries: Array<[DataKey, EnhancedInfo]>): void | Promise<void>
+
+  /**
+   * Clear all cached data
+   */
+  clear?(): void | Promise<void>
+}
+
+/**
+ * Type guard to check if value is a promise
+ */
+function isPromise<T>(value: T | Promise<T>): value is Promise<T> {
+  return value instanceof Promise
+}
+
+/**
+ * Helper to convert DataKey to cache key string
+ */
+export function getDataKeyCacheKey(key: DataKey): string {
+  return key.toLowerCase()
+}
+
+/**
+ * Convert a DataKey to the standardized string format
+ * @param dataKey - A hex string (address or address:tokenId)
+ * @returns The same string
+ */
+export function dataKeyToString(dataKey: DataKey): string {
+  return dataKey
+}
+
+/**
+ * Parse a string to a DataKey
+ * @param str - String in format "address" or "address:tokenId"
+ * @returns DataKey as a hex string
+ */
+export function parseDataKey(str: string): DataKey {
+  // Just return the string as-is since DataKey is now always a string
+  return str as DataKey
+}
+
+/**
+ * Create a simple in-memory address cache
+ */
+export function createMemoryAddressIdentityCache(
+  ttlMs: number = 1000 * 60 * 5 // 5 minutes default
+): AddressIdentityCache {
+  const cache = new Map<string, { data: EnhancedInfo; expires: number }>()
+
+  return {
+    get(key: DataKey): EnhancedInfo | undefined {
+      const cacheKey = getDataKeyCacheKey(key)
+      const entry = cache.get(cacheKey)
+
+      if (!entry) return undefined
+
+      if (Date.now() > entry.expires) {
+        cache.delete(cacheKey)
+        return undefined
+      }
+
+      return entry.data
+    },
+
+    set(key: DataKey, value: EnhancedInfo): void {
+      const cacheKey = getDataKeyCacheKey(key)
+      cache.set(cacheKey, {
+        data: value,
+        expires: Date.now() + ttlMs,
+      })
+    },
+
+    has(key: DataKey): boolean {
+      const cacheKey = getDataKeyCacheKey(key)
+      const entry = cache.get(cacheKey)
+
+      if (!entry) return false
+
+      if (Date.now() > entry.expires) {
+        cache.delete(cacheKey)
+        return false
+      }
+
+      return true
+    },
+
+    getMany(keys: DataKey[]): Map<DataKey, EnhancedInfo> {
+      const results = new Map<DataKey, EnhancedInfo>()
+
+      for (const key of keys) {
+        const data = this.get(key)
+        if (data && !isPromise(data)) {
+          results.set(key, data)
+        }
+      }
+
+      return results
+    },
+
+    setMany(entries: Array<[DataKey, EnhancedInfo]>): void {
+      for (const [key, value] of entries) {
+        this.set(key, value)
+      }
+    },
+
+    clear(): void {
+      cache.clear()
+    },
+  }
+}

package/src/shared/constants.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared constants
+ */
+
+export const DECODER_VERSION = '0.1.0'
+
+export const DEFAULT_CONFIG = {
+  endpoint: 'https://api.lukso.network/decoder',
+  batchSize: 100,
+  retryAttempts: 3,
+  timeout: 30000,
+} as const
+
+export const ERROR_CODES = {
+  INVALID_TRANSACTION: 'INVALID_TRANSACTION',
+  DECODING_FAILED: 'DECODING_FAILED',
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  RATE_LIMIT: 'RATE_LIMIT',
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  NOT_FOUND: 'NOT_FOUND',
+} as const

package/src/stubs/tty.ts

@@ -0,0 +1,13 @@
+/**
+ * Stub for Node.js tty module in edge/worker environments
+ */
+
+export const isatty = () => false
+export const ReadStream = class ReadStream {}
+export const WriteStream = class WriteStream {}
+
+export default {
+  isatty,
+  ReadStream,
+  WriteStream,
+}

package/src/stubs/util.ts

@@ -0,0 +1,42 @@
+/**
+ * Stub for Node.js util module in edge/worker environments
+ * Only includes what debug module might use
+ */
+
+export const inspect = (obj: any) => {
+  try {
+    return JSON.stringify(obj, null, 2)
+  } catch {
+    return String(obj)
+  }
+}
+
+export const format = (f: string, ...args: any[]) => {
+  let i = 0
+  return f.replace(/%[sdj%]/g, (x) => {
+    if (x === '%%') return '%'
+    if (i >= args.length) return x
+    switch (x) {
+      case '%s':
+        return String(args[i++])
+      case '%d':
+        return Number(args[i++]).toString()
+      case '%j':
+        try {
+          return JSON.stringify(args[i++])
+        } catch {
+          return '[Circular]'
+        }
+      default:
+        return x
+    }
+  })
+}
+
+export const debuglog = () => () => {}
+
+export default {
+  inspect,
+  format,
+  debuglog,
+}

package/src/types/index.ts

@@ -0,0 +1,154 @@
+/**
+ * Core types for @lukso/decoder
+ */
+
+import type { Signal } from '@preact/signals-core'
+import type { Hex } from 'viem'
+import type { DecoderResult, EnhancedInfo } from '../decoder/types'
+
+// Re-export decoder types
+export type { DecoderResult, EnhancedInfo } from '../decoder/types'
+export { AsyncOperations } from '../decoder/types'
+
+// Key is always a hex string - for tokens it's in the format "address:tokenId"
+export type DataKey = Hex
+
+// Helper type to make all properties deeply readonly
+type DeepReadonly<T> = T extends (infer R)[]
+  ? DeepReadonlyArray<R>
+  : T extends (...args: unknown[]) => unknown
+    ? T
+    : T extends object
+      ? DeepReadonlyObject<T>
+      : T
+
+interface DeepReadonlyArray<T> extends ReadonlyArray<DeepReadonly<T>> {}
+
+type DeepReadonlyObject<T> = {
+  readonly [P in keyof T]: DeepReadonly<T[P]>
+}
+
+/**
+ * State wrapper for address/asset information
+ */
+export interface AddressState {
+  loading: boolean
+  data?: DeepReadonly<EnhancedInfo>
+  error?: string
+  lastUpdated?: number
+}
+
+/**
+ * Transaction decoding status
+ * - raw: No decoding attempted yet
+ * - decoded: Sync decoding complete (phase 1)
+ * - enhanced: ABI retrieval complete (phase 2)
+ * - complete: Address resolution complete (phase 3)
+ * - failed: Decoding failed
+ */
+export type DecodingStatus =
+  | 'raw'
+  | 'decoded'
+  | 'enhanced'
+  | 'complete'
+  | 'failed'
+
+/**
+ * State wrapper for decoded transactions
+ */
+export interface TransactionState {
+  loading: boolean
+  data: DeepReadonly<DecoderResult>
+  addresses: ReadonlyArray<DataKey>
+  error?: string
+  lastUpdated?: number
+  decodingStatus?: DecodingStatus
+  addressesResolved?: boolean
+  resolvedData?: DeepReadonly<DecoderResult> // Transaction with all addresses populated
+}
+
+/**
+ * Options for creating a data model instance
+ */
+export interface DataModelOptions {
+  onMissingKeys?: (keys: DataKey[]) => void
+  onNewTransaction?: (transaction: unknown) => void
+}
+
+/**
+ * Read-only interface for consumers (views, components)
+ * This is the interface available on window.transactionDecoder
+ */
+export interface IDataModelConsumer {
+  // Transaction read methods
+  getTransaction(jsonTransaction: unknown): Signal<TransactionState> | undefined
+  getTransactionByKey(
+    hash: Hex,
+    decoderIndex?: number
+  ): Signal<TransactionState> | undefined
+  getTransactionsByIndex(
+    index: number
+  ): Map<number | null, Signal<TransactionState>> | undefined
+  getTransactionHashByIndex(index: number): Hex | undefined
+  getTransactionCount(): number
+  getDecodedCount(hash: Hex): number
+  getDecodedTransactions(hash: Hex): Array<Signal<TransactionState>>
+  getTransactionsInOrder(): Array<{
+    hash: Hex
+    transactions: Array<Signal<TransactionState>>
+  }>
+
+  // Address read methods
+  getAddress(address: DataKey): Signal<AddressState>
+  getSignal(key: DataKey): Signal<AddressState>
+  subscribe(key: DataKey, callback: (state: AddressState) => void): () => void
+  getState(key: DataKey): AddressState
+  hasData(key: DataKey): boolean
+  getData(key: DataKey): DeepReadonly<EnhancedInfo> | undefined
+  isLoading(key: DataKey): boolean
+  getError(key: DataKey): string | undefined
+
+  // Collection read methods
+  getAllKeys(): ReadonlyArray<DataKey>
+  getAllData(): Readonly<Record<string, AddressState>>
+  getAllTransactions(): Readonly<Record<string, TransactionState>>
+}
+
+/**
+ * Full interface for data management (used by data providers)
+ * Includes all consumer methods plus data modification methods
+ */
+export interface IDataModel extends IDataModelConsumer {
+  // Transaction management methods
+  addTransactions<T extends unknown | unknown[]>(
+    jsonTransactions: T
+  ): T extends unknown[]
+    ? Array<Signal<TransactionState>>
+    : Signal<TransactionState>
+  updateTransactionData(
+    hash: Hex,
+    newData: DecoderResult,
+    decoderIndex?: number
+  ): void
+
+  // Address management methods
+  injectData(dataList: EnhancedInfo[]): void
+  updateData(data: EnhancedInfo): void
+  setLoading(keys: DataKey[]): void
+  setError(key: DataKey, error: string): void
+
+  // Collection management methods
+  getMissingKeys(): DataKey[]
+  getLoadingKeys(): DataKey[]
+
+  // Management methods
+  clear(): void
+  remove(keys: DataKey[]): void
+}
+
+// Global window augmentation (only set by UMD builds or manual createGlobalInstance() call)
+declare global {
+  interface Window {
+    TransactionDecoder?: IDataModelConsumer
+  }
+}

package/src/types/provider.ts

@@ -0,0 +1,46 @@
+/**
+ * Types for data providers
+ */
+
+import type { Address, Hex } from 'viem'
+import type { TransactionState } from '.'
+
+export interface TransactionInput {
+  hash: Hex
+  chainId: number
+  from: Address
+  to?: Address
+  value: string | bigint
+  data: Hex
+  blockNumber?: string | bigint
+  timestamp?: number
+  status?: 'pending' | 'success' | 'failed'
+  metadata?: TransactionState
+}
+
+export interface TransactionUpdate {
+  hash: Hex
+  chainId: number
+  status?: 'pending' | 'success' | 'failed'
+  blockNumber?: string | bigint
+  timestamp?: number
+  metadata?: Partial<TransactionState>
+}
+
+export interface ProviderConfig {
+  apiKey?: string
+  endpoint?: string
+  batchSize?: number
+  retryAttempts?: number
+  timeout?: number
+}
+
+export interface SubmissionResult {
+  success: boolean
+  transactionHash: Hex
+  message?: string
+  error?: {
+    code: string
+    message: string
+  }
+}

package/src/umd.ts

@@ -0,0 +1,13 @@
+/**
+ * UMD entry point for @lukso/transaction-decoder
+ * This file automatically sets up window.TransactionDecoder for CDN usage
+ */
+
+// Import the instance setup function
+import { createGlobalInstance } from './core/instance'
+
+// Re-export everything from the main entry
+export * from './index'
+
+// Automatically create the global instance for UMD builds
+createGlobalInstance()

package/src/utils/debug.ts

@@ -0,0 +1,49 @@
+/**
+ * Debug wrapper for edge/worker environments
+ * This avoids the tty dependency in the debug module
+ */
+
+const debugInstances = new Map<string, boolean>()
+
+// Simple debug implementation that doesn't rely on Node.js modules
+export function createDebug(namespace: string) {
+  // Check if this namespace is enabled
+  const DEBUG = (typeof process !== 'undefined' && process.env?.DEBUG) || ''
+
+  // Simple pattern matching
+  const isEnabled = () => {
+    if (!DEBUG) return false
+    if (DEBUG === '*') return true
+
+    const patterns = DEBUG.split(',').map((p) => p.trim())
+    for (const pattern of patterns) {
+      if (pattern === namespace) return true
+      if (pattern.endsWith('*') && namespace.startsWith(pattern.slice(0, -1)))
+        return true
+      if (pattern.startsWith('-')) {
+        const negPattern = pattern.slice(1)
+        if (negPattern === namespace) return false
+        if (
+          negPattern.endsWith('*') &&
+          namespace.startsWith(negPattern.slice(0, -1))
+        )
+          return false
+      }
+    }
+    return false
+  }
+
+  debugInstances.set(namespace, isEnabled())
+
+  return (...args: any[]) => {
+    if (!debugInstances.get(namespace)) return
+
+    const timestamp = new Date().toISOString()
+    const prefix = `[${timestamp}] ${namespace}`
+
+    // In Cloudflare Workers, console.log is the only option
+    console.log(prefix, ...args)
+  }
+}
+
+export default createDebug

package/src/utils/json-bigint.ts

@@ -0,0 +1,47 @@
+/**
+ * JSON serializer/deserializer that preserves BigInt types
+ *
+ * This implementation uses an 'n' suffix to indicate BigInt values,
+ * ensuring that values that were originally BigInt remain BigInt,
+ * and values that were originally numbers remain numbers.
+ *
+ * Example:
+ * - BigInt(123) serializes to "123n"
+ * - Number(123) serializes to 123
+ *
+ * This is important for blockchain data where some values must be BigInt
+ * (e.g., gas, value, nonce) while others should remain as numbers
+ * (e.g., array indices, status codes).
+ */
+
+export const JSONbigString = {
+  /**
+   * Stringify an object, converting BigInt values to strings with 'n' suffix
+   */
+  stringify: (obj: any, replacer?: any, space?: string | number): string => {
+    return JSON.stringify(
+      obj,
+      (key, value) => {
+        if (typeof value === 'bigint') {
+          return value.toString() + 'n'
+        }
+        return value
+      },
+      space
+    )
+  },
+
+  /**
+   * Parse a JSON string, converting strings ending with 'n' back to BigInt
+   */
+  parse: (text: string): any => {
+    return JSON.parse(text, (key, value) => {
+      if (typeof value === 'string' && /^\d+n$/.test(value)) {
+        return BigInt(value.slice(0, -1))
+      }
+      return value
+    })
+  },
+}
+
+export default JSONbigString