@hugomrdias/foxer 0.0.1

package/src/utils/hash.ts

@@ -0,0 +1,17 @@
+/**
+ * Normalizes hash strings so comparisons are case-insensitive.
+ */
+export function normalizeHash(hash: string): string {
+  return hash.toLowerCase()
+}
+
+/**
+ * Compares two optional hash strings for equality.
+ */
+export function hashEquals(
+  left: string | null | undefined,
+  right: string | null | undefined
+): boolean {
+  if (left == null || right == null) return left === right
+  return normalizeHash(left) === normalizeHash(right)
+}

package/src/utils/json.ts

@@ -0,0 +1,11 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: its ok */
+type Reviver = (key: string, value: any) => any
+
+export function deserialize<type>(value: string, reviver?: Reviver): type {
+  return JSON.parse(value, (key, value_) => {
+    let value = value_
+    if (value?.__type === 'bigint') value = BigInt(value.value)
+    if (value?.__type === 'Map') value = new Map(value.value)
+    return reviver?.(key, value) ?? value
+  })
+}

package/src/utils/logger.ts

@@ -0,0 +1,149 @@
+import pc from 'picocolors'
+import type { DestinationStream, LevelWithSilent } from 'pino'
+import pino from 'pino'
+import type { Simplify } from 'type-fest'
+import { stringify } from 'viem'
+import { formatLogDuration } from './format.ts'
+
+export type LogMode = 'pretty' | 'json'
+export type LogLevel = Simplify<LevelWithSilent>
+export type Logger = ReturnType<typeof createLogger>
+
+export function createLogger({
+  level,
+  mode,
+}: {
+  level: LogLevel
+  mode: LogMode
+}) {
+  const stream: DestinationStream = {
+    write(logString: string) {
+      const log = JSON.parse(logString) as Log
+      const prettyLog = format(log)
+      // biome-ignore lint/suspicious/noConsole: logging to console
+      console.log(prettyLog)
+    },
+  }
+  const errorSerializer = pino.stdSerializers.wrapErrorSerializer((error) => {
+    error.meta = Array.isArray(error.meta) ? error.meta.join('\n') : error.meta
+    // @ts-expect-error - type is not defined in the error serializer
+    error.type = undefined
+    return error
+  })
+  let logger: pino.Logger
+
+  if (mode === 'pretty') {
+    logger = pino(
+      {
+        level,
+        serializers: {
+          error: errorSerializer,
+        },
+        // Removes "pid" and "hostname" properties from the log.
+        base: undefined,
+      },
+      stream
+    )
+  } else {
+    logger = pino({
+      level,
+      serializers: {
+        error: errorSerializer,
+      },
+      // Removes "pid" and "hostname" properties from the log.
+      base: undefined,
+    })
+  }
+  return logger
+}
+
+type Log = {
+  // Pino properties
+  level: 50 | 40 | 30 | 20 | 10
+  time: number
+
+  msg: string
+
+  duration?: number
+  error?: Error
+} & Record<string, unknown>
+
+const INTERNAL_KEYS = ['level', 'time', 'msg', 'duration', 'error']
+
+const levels = {
+  50: { label: 'ERROR', colorLabel: pc.red('ERROR') },
+  40: { label: 'WARN ', colorLabel: pc.yellow('WARN ') },
+  30: { label: 'INFO ', colorLabel: pc.green('INFO ') },
+  20: { label: 'DEBUG', colorLabel: pc.blue('DEBUG') },
+  10: { label: 'TRACE', colorLabel: pc.gray('TRACE') },
+} as const
+
+const timeFormatter = new Intl.DateTimeFormat(undefined, {
+  hour: '2-digit',
+  minute: '2-digit',
+  second: '2-digit',
+  fractionalSecondDigits: 3,
+  hour12: false,
+})
+
+const format = (log: Log) => {
+  const time = timeFormatter.format(new Date(log.time))
+  const levelObject = levels[log.level ?? 30]
+
+  let prettyLog: string[]
+  if (pc.isColorSupported) {
+    const level = levelObject.colorLabel
+    const messageText = pc.reset(log.msg)
+
+    let keyText = ''
+
+    for (const key of Object.keys(log)) {
+      if (INTERNAL_KEYS.includes(key)) continue
+      const value =
+        typeof log[key] === 'string' ? log[key] : stringify(log[key])
+      keyText += ` ${key}=${value}`
+    }
+
+    let durationText = ''
+    if (log.duration) {
+      durationText = ` ${pc.gray(`(${formatLogDuration(log.duration)})`)}`
+    }
+
+    prettyLog = [
+      `${pc.dim(time)} ${level} ${messageText}${pc.dim(keyText)}${durationText}`,
+    ]
+  } else {
+    const level = levelObject.label
+
+    let keyText = ''
+    for (const key of Object.keys(log)) {
+      if (INTERNAL_KEYS.includes(key)) continue
+      const value =
+        typeof log[key] === 'string' ? log[key] : stringify(log[key])
+      keyText += ` ${key}=${value}`
+    }
+
+    let durationText = ''
+    if (log.duration) {
+      durationText = ` (${formatLogDuration(log.duration)})`
+    }
+
+    prettyLog = [`${time} ${level} ${log.msg}${keyText}${durationText}`]
+  }
+
+  if (log.error) {
+    if (log.error.stack) {
+      prettyLog.push(log.error.stack)
+    } else {
+      prettyLog.push(`${log.error.name}: ${log.error.message}`)
+    }
+
+    if (typeof log.error === 'object' && 'where' in log.error) {
+      prettyLog.push(`where: ${log.error.where as string}`)
+    }
+    if (typeof log.error === 'object' && 'meta' in log.error) {
+      prettyLog.push(log.error.meta as string)
+    }
+  }
+  return prettyLog.join('\n')
+}

package/src/utils/shutdown.ts

@@ -0,0 +1,36 @@
+import { asyncExitHook, gracefulExit } from 'exit-hook'
+import type { Logger } from 'pino'
+
+export function createExit({
+  logger,
+  stop,
+}: {
+  logger: Logger
+  stop: () => Promise<void>
+}) {
+  asyncExitHook(
+    async () => {
+      logger.warn('shutting down...')
+      await stop()
+      logger.info('shutdown complete')
+      process.exit(0)
+    },
+    {
+      wait: 300,
+    }
+  )
+}
+
+export function registerUnhandled({ logger }: { logger: Logger }) {
+  process.on('uncaughtException', (error, origin) => {
+    if (!origin || origin === 'uncaughtException') {
+      logger.error({ error }, 'uncaught exception')
+      gracefulExit(1)
+    }
+  })
+
+  process.on('unhandledRejection', (error) => {
+    logger.error({ error }, 'unhandled rejection')
+    gracefulExit(1)
+  })
+}

package/src/utils/timer.ts

@@ -0,0 +1,8 @@
+/**
+ * Measures the elapsed wall clock time in milliseconds (ms) between two points.
+ * @returns A function returning the elapsed time in milliseconds (ms).
+ */
+export function startClock() {
+  const start = performance.now()
+  return () => performance.now() - start
+}

package/src/utils/types.ts

@@ -0,0 +1,87 @@
+import type { Abi, ExtractAbiEvent, ExtractAbiEventNames } from 'abitype'
+import type { UnknownObject } from '../types'
+
+export type EnsureUniqueTuple<
+  tuple extends readonly unknown[],
+  seen = never,
+> = tuple extends readonly [
+  infer head,
+  ...infer tail extends readonly unknown[],
+]
+  ? head extends seen
+    ? never
+    : readonly [head, ...EnsureUniqueTuple<tail, seen | head>]
+  : tuple
+
+export type MergedContractEvents<
+  contracts,
+  contractName extends keyof contracts & string = keyof contracts & string,
+> = {
+  [name in contractName]: contracts[name] extends {
+    events: readonly (infer eventName extends string)[]
+  }
+    ? `${name}:${eventName}`
+    : never
+}[contractName]
+
+export interface ContractConfig<
+  abi extends Abi,
+  events extends
+    readonly ExtractAbiEventNames<abi>[] = readonly ExtractAbiEventNames<abi>[],
+> {
+  /** Contract application byte interface. */
+  abi: abi
+  /** Contract address. */
+  address: `0x${string}`
+  /** Block number at which to start indexing events (inclusive). If `undefined`, events will be processed from block 0. Default: `undefined` */
+  startBlock?: bigint
+  /** Block number at which to stop indexing events (inclusive). If `undefined`, events will be processed in real-time. Default: `undefined`. */
+  endBlock?: bigint
+  /** Events to index. No duplicates allowed.*/
+  events: EnsureUniqueTuple<events>
+}
+
+export type GetContract<contract = unknown> = contract extends {
+  abi: infer abi extends Abi
+}
+  ? contract extends {
+      events: infer events extends readonly ExtractAbiEventNames<abi>[]
+    }
+    ? // 1. Contract has a valid abi and events
+      ContractConfig<abi, events>
+    : // 2. Contract has a valid abi
+      ContractConfig<abi>
+  : // 3. Contract has an invalid abi
+    ContractConfig<Abi>
+
+export type ContractsConfig<contracts> = UnknownObject extends contracts
+  ? // contracts empty, return empty
+    UnknownObject
+  : {
+      [name in keyof contracts]: GetContract<contracts[name]>
+    }
+
+export type EventKey = `${string}:${string}`
+
+export type ContractNameFromEventKey<C extends EventKey> =
+  C extends `${infer ContractName}:${string}` ? ContractName : never
+
+export type EventNameFromEventKey<K extends string> =
+  K extends `${string}:${infer EventName}` ? EventName : never
+
+export type ContractAbiByEventKey<
+  C extends ContractsConfig<NonNullable<unknown>>,
+  Event extends EventKey,
+> = C[Extract<ContractNameFromEventKey<Event>, keyof C>] extends {
+  abi: infer ContractAbi extends Abi
+}
+  ? ContractAbi
+  : Abi
+
+export type ContractAbiEventByEventKey<
+  C extends ContractsConfig<NonNullable<unknown>>,
+  Event extends EventKey,
+> = ExtractAbiEvent<
+  ContractAbiByEventKey<C, Event>,
+  EventNameFromEventKey<Event>
+>

package/template/biome.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://biomejs.dev/schemas/latest/schema.json",
+  "vcs": {
+    "enabled": false,
+    "clientKind": "git",
+    "useIgnoreFile": false
+  },
+  "files": {
+    "ignoreUnknown": false
+  },
+  "formatter": {
+    "enabled": true,
+    "formatWithErrors": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineEnding": "lf",
+    "lineWidth": 80,
+    "attributePosition": "auto",
+    "includes": ["**"]
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "jsxQuoteStyle": "double",
+      "quoteProperties": "asNeeded",
+      "trailingCommas": "es5",
+      "semicolons": "asNeeded",
+      "arrowParentheses": "always",
+      "bracketSpacing": true,
+      "bracketSameLine": false,
+      "quoteStyle": "single",
+      "attributePosition": "auto"
+    },
+    "globals": ["document", "navigator", "window"]
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on",
+        "useSortedAttributes": "on"
+      }
+    }
+  }
+}

package/template/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "foxer-repo",
+  "version": "0.0.0",
+  "description": "",
+  "main": "index.js",
+  "private": true,
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "lint": "pnpm -r --if-present run lint",
+    "build": "pnpm -r --if-present run build",
+    "lint:fix": "biome check --write ."
+  },
+  "keywords": [],
+  "license": "MIT",
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.5"
+  }
+}

package/template/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+packages:
+  - 'apps/*'
+  - 'packages/*'

package/template/tsconfig.json

@@ -0,0 +1,37 @@
+{
+  "compilerOptions": {
+    /* Projects */
+    "incremental": true,
+    "composite": true,
+    // Emit
+
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "removeComments": true,
+
+    // Language and Environment
+    "lib": ["ESNext", "DOM"],
+    "target": "ESNext",
+    "moduleDetection": "force",
+
+    // Modules
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "resolveJsonModule": true,
+    "rewriteRelativeImportExtensions": true,
+
+    // Interop Constraints
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "esModuleInterop": true,
+
+    // Type Checking
+    "strict": true,
+    "noImplicitOverride": true,
+
+    // Completeness
+    "skipLibCheck": true
+  }
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["./**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}