JavaScript SDK
@aurabase/aurabase-js — Node、Bun、Deno、Next.js、React、SvelteKit、Vue 的类型化客户端。涵盖数据库、认证、实时、存储、功能。
一个包裹,四位经理#
pnpm add @aurabase/aurabase-js
SDK 直接包括 Next.js(应用程序路由器、服务器操作、中间件)、Remix、Nuxt 和 SvelteKit 的 @aurabase/aurabase-js/ssr 导出,并具有会话 cookie 和防截断分块的自动管理功能。
创建客户端#
import { createClient } from '@aurabase/aurabase-js'
import type { Database } from './aurabase.types'
export const aura = createClient<Database>(
process.env.NEXT_PUBLIC_AURABASE_URL!,
process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
{ auth: { persistSession: true } }
)
本机服务器端渲染支持#
对于 SSR 架构(Next.js App Router、中间件、服务器操作、SvelteKit),从 @aurabase/aurabase-js/ssr导入 createServerClient 。用户会话自动存储在安全的 httpOnly cookie 中,并为大令牌提供多块支持:
import { createServerClient } from '@aurabase/aurabase-js/ssr'
import { NextResponse, type NextRequest } from 'next/server'
export async function middleware(request: NextRequest) {
let response = NextResponse.next({ request })
const aura = createServerClient(
process.env.NEXT_PUBLIC_AURABASE_URL!,
process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
{
cookies: {
getAll() { return request.cookies.getAll() },
setAll(cookies) {
cookies.forEach(({ name, value, options }) => {
request.cookies.set(name, value)
response.cookies.set(name, value, options)
})
},
},
})
await aura.auth.getSession()
return response
}
从您的架构中生成代码#
npx @aurabase/gen --out lib/aurabase.types.ts (或 aura db generate,在当前文件夹中写入 types.ts )从完整架构(表、视图、枚举、RPC 函数)生成类型文件。插入 createClient<Database> 以输入所有查询。
{
"scripts": {
"types:gen": "npx @aurabase/gen --out src/aurabase.types.ts",
"migrate": "aura db push && pnpm types:gen"
}
}
按服务#
数据库
.from(table).select(cols?)→SelectBuilder<T>.from(table).insert(row)→Promise<{ data, error }>.from(table).update(patch)→UpdateBuilder<T>.from(table).delete()→DeleteBuilder<T>.rpc(fn, args)→Promise<{ data, error }>.nosql.collection(name)→NoSqlCollectionClient(find(),insertOne(),aggregate(),createIndex())
授权
.auth.signUp({ email, password, options? })→Promise<AuraResponse<LoginResponse>>.auth.signInWithPassword({ email, password })→Promise<AuraResponse<LoginResponse>>.auth.signInWithOAuth(provider, opts?) | ({ provider, ... })→Promise<AuraResponse<{ url }>>.auth.getSession()→Promise<{ data: { session }, error }>.auth.signOut()→Promise<AuraResponse<void>>.auth.mfa.enroll() | .auth.mfaEnroll()→Promise<AuraResponse<MfaEnrollResponse>>
实时
.channel(name, config?)→Channelchannel.on(event, filter, cb)→Channelchannel.subscribe()→Channelchannel.send({ type, event, payload })→Promise<void>channel.unsubscribe()→Promise<void>
存储
.storage.from(bucket).upload(path, file, opts?)→Promise<{ data, error }>.storage.from(bucket).download(path)→Promise<Blob>.storage.from(bucket).getPublicUrl(path, opts?)→{ publicUrl }.storage.from(bucket).createSignedUrl(path, expiresIn)→Promise<{ signedUrl }>.storage.from(bucket).remove(paths[])→Promise<{ data, error }>
功能
.functions.invoke(name, { body?, method?, path?, headers?, responseType?, signal?, timeout? })→Promise<{ data, error }>.functions.list()→Promise<{ data: FunctionDef[], error }>.functions.get(nameOrId)→Promise<{ data: FunctionDef, error }>.functions.listJobs({ status?, limit? })→Promise<{ data: Job[], error }>.functions.getJob(jobId)→Promise<{ data: Job, error }>.functions.enqueueJob(functionName, { payload?, delaySecs?, maxAttempts? })→Promise<{ data: Job, error }>.functions.listCronJobs()→Promise<{ data: CronJob[], error }>.functions.createCronJob(name, schedule, functionName, { payload? })→Promise<{ data: CronJob, error }>.functions.deleteCronJob(name)→Promise<{ data, error }>
只有 invoke 对公共 (anon) 密钥开放。 list、 get、 listJobs、 getJob、 enqueueJob、 listCronJobs、 createCronJob 和 deleteCronJob 需要 service_role 密钥并属于您的服务器: FunctionDef 携带函数的源代码和环境变量,因此这些调用会应答403 到公钥。 invoke 将错误报告为 FunctionsHttpError (函数回答错误,任何状态)或 FunctionsRelayError (平台失败:网络、502、503、504),两者均由 @aurabase/aurabase-js导出。
统一形状{数据,错误}#
每个异步方法都会返回 { data, error }。 成功时 error 为 null ,否则为 AuraError 实例(也以别名 AurabaseError导出),其中包含 code、 message、 status和 details。如果您的架构使用超出 Number.MAX_SAFE_INTEGER的 64 位 bigint 值,请在 createClient 选项中传递 { parseBigIntAsString: true } 。
import { AurabaseError } from '@aurabase/aurabase-js'
const { data, error } = await aura.from('users').select('*').single()
if (error) {
if (error.code === 'PGRST116') notFound()
throw error // AuraError / AurabaseError 实例
}