feat: implement @pubkey-cache/resolver and @pubkey-cache/server

.changeset/two-oranges-dress.md

@@ -0,0 +1,8 @@
+---
+'@pubkey-cache/resolver': major
+'@pubkey-cache/server': major
+'@pubkey-cache/react': major
+'@pubkey-cache/core': major
+---
+
+implement @pubkey-cache/resolver and @pubkey-cache/server

.github/workflows/bundlesize.yml

@@ -5,7 +5,7 @@ on:
     branches:
       - main
   pull_request:
-    types: [synchronize, opened, reopened]
+    types: [ synchronize, opened, reopened ]
 
 env:
   # Among other things, opts out of Turborepo telemetry
@@ -31,7 +31,11 @@ jobs:
           version: current
 
       - name: Build
-        run: pnpm turbo compile:js --concurrency=${TURBO_CONCURRENCY:-1}
+        run: pnpm turbo compile:js compile:typedefs --concurrency=${TURBO_CONCURRENCY:-1}
 
       - name: BundleMon
         uses: lironer/bundlemon-action@v1
+        env:
+          # Always compare to the main branch; prevents stacked PRs from being
+          # compared to the wrong mergebase (ie. the PR beneath the current one)
+          CI_TARGET_BRANCH: main

examples/node-redis/.env.example

@@ -0,0 +1,7 @@
+DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/<blah>
+HELIUS_API_KEY=foo-bar-baz-qux
+HOSTNAME=localhost
+PORT=3080
+REDIS_URL=redis://localhost:6379
+RESOLVERS=helius-nft-holders:5FusHaKEKjfKsmQwXNrhFcFABGGxu7iYCdbvyVSRe3Ri|helius-token-holders:Ds52CDgqdWbTWsua1hgT3AuSSy4FNx2Ezge1br3jQ14a
+VERBOSE=true

examples/node-redis/.gitignore

@@ -0,0 +1,5 @@
+.env
+.turbo
+/tmp
+dist
+node_modules

examples/node-redis/.prettierignore

@@ -0,0 +1,6 @@
+# Add files here to ignore them from prettier formatting
+dist
+coverage
+node_modules
+tmp
+pnpm-lock.yaml

examples/node-redis/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "arrowParens": "always",
+  "printWidth": 120,
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "all"
+}

examples/node-redis/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bram Borggreve https://github.com/beeman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

examples/node-redis/README.md

@@ -0,0 +1,3 @@
+# node-redis
+
+Example node.js app that uses @pubkey-cache/resolver to cache data into redis.

examples/node-redis/docker-compose.yml

@@ -0,0 +1,7 @@
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - '6379:6379'
+    volumes:
+      - ./tmp/redis:/data

examples/node-redis/eslint.config.mjs

@@ -0,0 +1,26 @@
+import globals from 'globals'
+
+import baseConfig from '../../eslint.config.mjs'
+
+export default [
+  {
+    ignores: ['**/dist', '**/*.css'],
+  },
+  ...baseConfig,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.es2020,
+      },
+      parserOptions: {
+        project: './tsconfig.json',
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-misused-promises': 'off',
+      '@typescript-eslint/no-unsafe-argument': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/restrict-template-expressions': 'error',
+    },
+  },
+]

examples/node-redis/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "node-redis",
+  "version": "0.0.0",
+  "description": "",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "dev": "esrun --watch src/index.ts",
+    "dev:server": "esrun --watch src/server.ts",
+    "dev:services": "docker compose up",
+    "start": "esrun src/index.ts",
+    "compile:js": "tsc -p ./tsconfig.json",
+    "preview": "vite preview",
+    "style:fix": "pnpm eslint --fix src && pnpm prettier --log-level warn --ignore-unknown --write ./*",
+    "test:lint": "TERM_OVERRIDE=\"${TURBO_HASH:+dumb}\" TERM=${TERM_OVERRIDE:-$TERM} jest -c ../../node_modules/@pubkey-cache/test-config/jest-lint.config.ts --rootDir . --silent --testMatch '<rootDir>src/**/*.{ts,tsx}'",
+    "test:prettier": "TERM_OVERRIDE=\"${TURBO_HASH:+dumb}\" TERM=${TERM_OVERRIDE:-$TERM} jest -c ../../node_modules/@pubkey-cache/test-config/jest-prettier.config.ts --rootDir . --silent",
+    "test:typecheck": "tsc"
+  },
+  "keywords": [],
+  "author": "Bram Borggreve",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "@types/prompts": "^2.4.9",
+    "dotenv": "^16.4.7",
+    "globals": "^15.14.0",
+    "prettier": "^3.4.2",
+    "typescript": "~5.7.2"
+  },
+  "dependencies": {
+    "@pubkey-cache/resolver": "workspace:*",
+    "@pubkey-cache/server": "workspace:*",
+    "@solana/web3.js": "1",
+    "esrun": "^3.2.26",
+    "h3": "^1.15.1",
+    "helius-sdk": "^1.4.2",
+    "ioredis": "^5.5.0",
+    "listhen": "^1.9.0",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2",
+    "unstorage": "^1.15.0"
+  }
+}

examples/node-redis/src/commands/command-balance.ts

@@ -0,0 +1,40 @@
+import prompts from 'prompts'
+
+import { ensureValidPublicKey } from '../lib/ensure-valid-public-key'
+import { Context } from '../lib/get-context'
+import { Command } from './command'
+
+let previousPublicKey: string | undefined
+
+export const commandBalance: Command = {
+  action: async (ctx: Context) => {
+    const { publicKey } = await prompts({
+      initial: previousPublicKey,
+      message: 'Enter a public key',
+      name: 'publicKey',
+      type: 'text',
+      validate: (publicKey) => {
+        try {
+          ensureValidPublicKey(publicKey)
+          return true
+          // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        } catch (error: unknown) {
+          return false
+        }
+      },
+    })
+    if (publicKey !== previousPublicKey) {
+      previousPublicKey = publicKey
+    }
+    try {
+      const address = ensureValidPublicKey(publicKey)
+      const balance = await ctx.connection.getBalance(address)
+
+      return [null, `${balance / 10 ** 9} SOL`]
+    } catch (error) {
+      return [new Error(error as string), null]
+    }
+  },
+  description: 'Get the balance for a public key',
+  name: 'balance',
+}

examples/node-redis/src/commands/command-discord-log.ts

@@ -0,0 +1,31 @@
+import pico from 'picocolors'
+import prompts from 'prompts'
+
+import { getContext } from '../lib/get-context'
+import { Command } from './command'
+
+const ctx = getContext()
+export const commandDiscordLog: Command = {
+  action: async () => {
+    try {
+      const { name } = await prompts({
+        message: "What's your name?",
+        name: 'name',
+        type: 'text',
+        validate: (name) => name.length > 0,
+      })
+
+      await ctx.discordLog({
+        level: 'info',
+        message: `This is a "Hello, ${name}" from the cli`,
+        title: 'Test Title',
+      })
+
+      return [null, pico.blue(`Hello ${pico.green(name)}!`)]
+    } catch (error) {
+      return [new Error(error as string), null]
+    }
+  },
+  description: 'Test the discord log',
+  name: 'discord-log',
+}

examples/node-redis/src/commands/command-genesis-hash.ts

@@ -0,0 +1,16 @@
+import { Context } from '../lib/get-context'
+import { Command } from './command'
+
+export const commandGenesisHash: Command = {
+  action: async (ctx: Context) => {
+    try {
+      const genesisHash = await ctx.connection.getGenesisHash()
+
+      return [null, genesisHash]
+    } catch (error) {
+      return [new Error(error as string), null]
+    }
+  },
+  description: 'Get the genesis hash',
+  name: 'genesis-hash',
+}

examples/node-redis/src/commands/command-hello.ts

@@ -0,0 +1,23 @@
+import pico from 'picocolors'
+import prompts from 'prompts'
+
+import { Command } from './command'
+
+export const commandHello: Command = {
+  action: async () => {
+    try {
+      const { name } = await prompts({
+        message: "What's your name?",
+        name: 'name',
+        type: 'text',
+        validate: (name) => name.length > 0,
+      })
+
+      return [null, pico.blue(`Hello ${pico.green(name)}!`)]
+    } catch (error) {
+      return [new Error(error as string), null]
+    }
+  },
+  description: 'Say hello',
+  name: 'hello',
+}

examples/node-redis/src/commands/command-help.ts

@@ -0,0 +1,11 @@
+import pico from 'picocolors'
+
+import { Command } from './command'
+
+export const commandHelp: Command = {
+  action: () => {
+    return [null, pico.yellow(`I'm not helpful but you could add some help here.`)]
+  },
+  description: 'Show help',
+  name: 'help',
+}

examples/node-redis/src/commands/command-nft-holders.ts

@@ -0,0 +1,47 @@
+import { resolverHeliusNftHolders } from '@pubkey-cache/resolver'
+import prompts from 'prompts'
+
+import { ensureValidPublicKey } from '../lib/ensure-valid-public-key'
+import { getConfig } from '../lib/get-config'
+import { Context } from '../lib/get-context'
+import { Command } from './command'
+
+let previousValue: string | undefined
+const config = getConfig()
+
+export const commandNftHolders: Command = {
+  action: async (ctx: Context) => {
+    const { collection } = await prompts({
+      initial: previousValue,
+      message: 'Enter the public key of the collection',
+      name: 'collection',
+      type: 'text',
+      validate: (publicKey) => {
+        try {
+          ensureValidPublicKey(publicKey)
+          return true
+          // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        } catch (error: unknown) {
+          return false
+        }
+      },
+    })
+    if (collection !== previousValue) {
+      previousValue = collection
+    }
+    try {
+      ensureValidPublicKey(collection)
+      const result = await resolverHeliusNftHolders({
+        collection,
+        helius: ctx.helius,
+        verbose: config.verbose,
+      })
+
+      return [null, result]
+    } catch (error) {
+      return [new Error(error as string), null]
+    }
+  },
+  description: 'Get the holders of an NFT collection',
+  name: 'nft-holders',
+}

examples/node-redis/src/commands/command-resolver-sync-all.ts

@@ -0,0 +1,49 @@
+import { resolve, storeResolverResultMap } from '@pubkey-cache/resolver'
+
+import { getConfig } from '../lib/get-config'
+import { getContext } from '../lib/get-context'
+import { Command } from './command'
+
+export const commandResolverSyncAll: Command = {
+  action: async () => {
+    const { resolvers, verbose } = getConfig()
+    const context = getContext()
+    const startTime = new Date().getTime()
+    const results: string[] = []
+
+    try {
+      for (const resolver of resolvers) {
+        const startTimeResolver = new Date().getTime()
+        const resultMap = await resolve({ context, resolver, verbose })
+
+        const { writeCount } = await storeResolverResultMap({
+          path: resolver.id,
+          resultMap,
+          storage: context.storage,
+        })
+        const endTimeResolver = new Date().getTime()
+        const durationResolver = endTimeResolver - startTimeResolver
+
+        results.push(
+          `Synced resolver ${resolver.id}, wrote ${writeCount} items to storage (${durationResolver / 1000} seconds)`,
+        )
+        await context.discordLog({
+          level: 'info',
+          message: `Wrote ${writeCount} items to storage (${durationResolver / 1000} seconds)`,
+          title: `Synced ${resolver.type} ${resolver.address}`,
+          url: `https://explorer.solana.com/address/${resolver.address}`,
+        })
+      }
+
+      const endTime = new Date().getTime()
+      const duration = endTime - startTime
+      results.push(`Duration ${duration / 1000} seconds`)
+
+      return [null, results]
+    } catch (error) {
+      return [new Error(error as string), null]
+    }
+  },
+  description: 'Sync all resolvers',
+  name: 'resolver-sync-all',
+}