@avelonjs/neon

@avelonjs/neon is the Neon stack for Avelon: a transaction-capable Postgres database, Neon Auth identity and social login, S3 object storage, and Postgres-backed Signets and queues. Reach for this package when you want the same six contracts @avelonjs/supabase covers, without PostgREST or GoTrue.

Installation

bun add @avelonjs/neon

export NEON_DATABASE_URL=postgresql://user:pass@ep-xxx.us-east-1.aws.neon.tech/neondb?sslmode=require
export NEON_AUTH_URL=https://ep-xxx.neonauth.net
export NEON_S3_BUCKET=avelon-uploads
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

Wire drivers only in avelon.config.ts. Application folders never import @neondatabase/serverless or @aws-sdk/client-s3.

Basic Usage

import { createNeonDatabase } from '@avelonjs/neon'
import type { QueryIR } from '@avelonjs/core'

const db = createNeonDatabase({
  url: process.env.NEON_DATABASE_URL,
  instance: 'primary',
})

const latest: QueryIR = {
  table: 'posts',
  mode: 'select',
  select: ['id', 'title'],
  where: [{ kind: 'null', column: 'published_at', negated: true }],
  relations: [],
  order: [{ column: 'published_at', direction: 'desc' }],
  limit: 10,
}

await db.execute(latest)

Capabilities

rowSecurity stays false. Ward predicates still inject into Query IR. Neon is Postgres, so you can compile RLS yourself through raw(); this package does not ship a PostgREST-shaped syncWards() surface.

Database

Query IR, migrations, and schema checks compile through @avelonjs/postgres/sql, the subpath of that package whose import graph carries no bun specifier, so @avelonjs/neon/database runs on Node as well as Bun. raw() returns the @neondatabase/serverless query function.

Reads, writes, rpc(), and migrations go over Neon's HTTP endpoint, which holds no connection between calls. transaction() is the exception: the callback reads rows before deciding what to issue next, and Neon's HTTP transactions are non-interactive, so the first call opens a WebSocket Pool connection and close() ends it. That path needs a global WebSocket, which Node has from 22 on; on older runtimes set neonConfig.webSocketConstructor before the first transaction.

Import from @avelonjs/neon/database rather than the package root when the runtime is Node. The root barrel also exports the queue and token drivers, which are built on Bun's SQL client.

import { createNeonDatabase } from '@avelonjs/neon'

const db = createNeonDatabase({
  migrations: [
    {
      id: '20260828_create_posts',
      up: ['CREATE TABLE posts (id text PRIMARY KEY, title text NOT NULL)'],
      down: ['DROP TABLE posts'],
    },
  ],
})

await db.plan()
await db.apply()
await db.transaction(async (tx) => {
  await tx.execute({
    table: 'posts',
    mode: 'insert',
    select: [],
    where: [],
    relations: [],
    order: [],
    values: { id: 'post-1', title: 'Hello' },
  })
})

Identity

Neon Auth speaks the Better Auth HTTP surface. The config-time factory receives request-scoped cookies.

import { createNeonIdentity } from '@avelonjs/neon'

const auth = createNeonIdentity({
  authUrl: process.env.NEON_AUTH_URL,
})

export async function currentUser(cookies: import('@avelonjs/core').RequestCookies) {
  return auth(cookies).user()
}

Capabilities: passwords: true, magicLinks: true, oauth: false, organizations: false, mfa: ['totp'], emailVerification: true. After password sign-in you challenge the enrolled TOTP factor and verify the authenticator code. challengeMfa() without an argument uses totp. Email confirmation uses Better Auth's send-and-verify token pair.

import { createNeonIdentity } from '@avelonjs/neon'
import type { RequestCookies } from '@avelonjs/core'

export async function completeTotpAndEmail(cookies: RequestCookies) {
  const identity = createNeonIdentity({
    authUrl: process.env.NEON_AUTH_URL,
  })(cookies)

  await identity.signInWithPassword('jordan@example.com', 'correct-horse-battery')
  const challenge = await identity.challengeMfa('totp')
  await identity.verifyMfa(challenge.id, '123456')
  await identity.sendEmailVerification()
  await identity.verifyEmail('confirmation-token')
}

OAuth linking stays undeclared until a live Neon Auth project exercises that surface in CI.

Social

import { createNeonSocial } from '@avelonjs/neon'

const social = createNeonSocial({
  authUrl: process.env.NEON_AUTH_URL,
})

export async function githubRedirect(callbackUrl: string): Promise<string> {
  return social.redirect('github', callbackUrl)
}

Providers are the literal list github and google. Undeclared providers raise Invalid. A mismatched or missing OAuth state raises Unauthenticated.

Tokens

Neon Auth does not issue named API tokens. Hashed Signets live in Postgres on the Neon database.

import { createNeonTokens } from '@avelonjs/neon'

const tokens = createNeonTokens({
  url: process.env.NEON_DATABASE_URL,
  subject: 'user-1',
})

const issued = await tokens.issue('deployment', { abilities: ['records:read'] })
await tokens.verify(issued.plainText)

Storage

Object bytes persist in S3. Point endpoint at AWS, Cloudflare R2, MinIO, or the in-process LocalS3Server used by conformance. Signed reads are SigV4 query URLs.

import { createNeonStorage } from '@avelonjs/neon'

const disk = createNeonStorage({
  bucket: process.env.NEON_S3_BUCKET,
  instance: 'uploads',
})
await disk.put('avatars/me.bin', new Uint8Array([1, 2, 3]), {
  contentType: 'application/octet-stream',
})
const url = await disk.signedUrl('avatars/me.bin', 60)

Transforms are undeclared in v1 (D28). Signed uploads and listing are deferred.

Queue

Durable jobs use Postgres FOR UPDATE SKIP LOCKED on the Neon database.

import { createNeonQueue } from '@avelonjs/neon'

const queue = createNeonQueue({
  url: process.env.NEON_DATABASE_URL,
})
const id = await queue.enqueue({ name: 'GenerateReport', payload: { reportId: 'report-1' } })
await queue.drain(async (receipt) => {
  if (receipt.id !== id) return
})

Method Reference

Testing

Run the shared suites. Identity and social use Better Auth-shaped local servers. Storage uses LocalS3Server so SigV4 signed reads stay fetchable without AWS. Database, tokens, and queue require a reachable Neon or Postgres URL and fail closed when it is missing.

The database driver talks to Neon's HTTP and WebSocket endpoints, which a plain Postgres does not serve. When the configured URL is not a neon.tech host, tests/neon-local.ts starts both endpoints locally in front of that Postgres, so live conformance exercises the real vendor client end to end.

import { identitySuite, storageSuite } from '@avelonjs/conformance/suites'
import {
  createNeonIdentity,
  createNeonStorage,
  LocalAuthServer,
  LocalS3Server,
} from '@avelonjs/neon'

const auth = new LocalAuthServer()
const authUrl = await auth.start()
identitySuite({
  name: 'neon identity',
  create: () => {
    auth.reset()
    return createNeonIdentity({ authUrl })
  },
  recoveryToken: async (email) => {
    const token = auth.recoveryToken(email)
    if (token === undefined) throw new Error(`No recovery token for ${email}`)
    return token
  },
  emailVerificationToken: async (email) => {
    const token = auth.verificationToken(email)
    if (token === undefined) throw new Error(`No verification token for ${email}`)
    return token
  },
})

const s3 = new LocalS3Server()
const endpoint = await s3.start()
storageSuite({
  name: 'neon storage',
  create: () => createNeonStorage({ endpoint, bucket: 'assay' }),
})

bun test
bun run typecheck
reeve docs:check