版本说明

Supabase.js是Supabase数据库服务的官方JavaScript客户端库,用于与Supabase API进行交互。 最新版本Supabase.js v2带来了一系列令人振奋的新特性、更新和改进,使开发者在构建现代Web应用程序时拥有更加强大和灵活的工具。

让我们深入了解这些新功能,并看看它们如何改进您的Supabase体验!接下来,我们将逐步探索Supabase.js v2的亮点和特性,帮助您更好地了解这个新版本。

首先需要用npm install @supabase/supabase-js安装最新版本。

明确的构造器选项

构造函数中的所有客户端特定选项都是键入库的。PR:

1const supabase = createClient(apiURL, apiKey, {
2  db: {
3    schema: 'public',
4  },
5  auth: {
6    storage: AsyncStorage,
7    autoRefreshToken: true,
8    persistSession: true,
9    detectSessionInUrl: true,
10  },
11  realtime: {
12    channels,
13    endpoint,
14  },
15  global: {
16    fetch: customFetch,
17    headers: DEFAULT_HEADERS,
18  },
19})

支持typescript#

这些库现在支持typescript。

1// v2 - definitions are injected in `createClient()`
2import type { Database } from './DatabaseDefinitions'
3const supabase = createClient<Database>(SUPABASE_URL, ANON_KEY)
4const { data } = await supabase.from('messages').select().match({ id: 1 })
5
6// v1 -- previously definitions were injected in the `from()` method
7supabase.from<Definitions['Message']>('messages').select('*')

类型可以通过CLI生成。

supabase start
supabase gen types typescript --local > DatabaseDefinitions.ts

数据操作返回最小值

.insert() / .upsert() / .update() / .delete() 默认情况下不返回行:PR.

以前,这些方法默认返回插入/更新/删除的行(这引起了一些混乱),你可以通过指定 "returning: 'minimal'"选择不返回它。现在的默认行为是不返回记录。要返回插入/更新/删除的行,请在最后添加一个.select()的调用,例如:

1const { data, error } = await supabase
2    .from('my_table')
3    .delete()
4    .eq('id', 1)
5    .select()

新的排序默认值

.order()现在默认为Postgres的默认值:PR

以前nullsFirst默认为false,这意味着null是最后排序的。这对性能是不利的,例如,如果该列使用NULLS FIRST的索引(这是索引的默认方向)。

Cookies和localstorage命名空间#

Auth库中的存储密钥名称已经改变,包括项目参考,这意味着现有的网站如果将其JWT到期时间设置为较长的时间,可能会发现他们的用户在这次升级中被注销。

1const defaultStorageKey = `sb-${new URL(this.authUrl).hostname.split('.')[0]}-auth-token`

新的授权类型

类型化已经被重新设计。Session接口现在保证它总是有access_token, refresh_tokenuser

1interface Session {
2    provider_token?: string | null
3    access_token: string
4    expires_in?: number
5    expires_at?: number
6    refresh_token: string
7    token_type: string
8    user: User
9}

新的认证方法

我们将删除signIn()方法,改用更明确的函数签名。 signInWithPassword(), signInWithOtp(), 和 signInWithOtp().

1// v2
2const { data } = await supabase.auth.signInWithPassword({
3  email: 'hello@example',
4  password: 'pass',
5})
6// v1
7const { data } = await supabase.auth.signIn({
8  email: 'hello@example',
9  password: 'pass',
10})

新的实时方法

在Realtime库中有一个新的channel()方法,它将被用于我们的多人游戏更新。

1supabase
2  .channel('any_string_you_want')
3  .on('presence', { event: 'track' }, (payload) => {
4    console.log(payload)
5  })
6  .subscribe()
7
8supabase
9  .channel('any_string_you_want')
10  .on(
11    'postgres_changes',
12    {
13      event: 'INSERT',
14      schema: 'public',
15      table: 'movies',
16    },
17    (payload) => {
18      console.log(payload)
19    }
20  )
21  .subscribe()

我们将废弃以前用于监听postgres变化的`.from().on().subscribe()'方法。

废弃的setAuth()#

废弃并删除了setAuth()。要设置一个自定义的access_token jwt,请将自定义的头信息传入提供的createClient()方法:(PR)

所有变化

  • supabase-js
    • shouldThrowOnError已被删除,直到所有客户端库都支持该选项(PR)。
  • postgrest-js
    • TypeScript的类型已被重新设计 PR
    • 对函数参数、类型等使用undefined而不是null
    • 一些功能现在已经过时了:
      • 过滤器缩写(例如:cscontains)。
      • 响应中的 "body"(相对于 "data")。
      • 通过".insert() "方法进行 "上载"。
      • PostgrestClient上的auth方法
      • 客户端级别的`throwOnError'方法
  • Gotrue-js
    • supase-js客户端允许传递一个storageKey参数,这将允许用户设置本地存储中用于存储会话的密钥。默认情况下,这将与supabase项目参考文献一起被命名为空间。(PR)
    • signIn方法现在分为signInWithPassword, signInWithOtp, signInWithOAuth (PR)
    • 弃用并删除了session(), user(),改用getSession()。如果用户已经登录,getSession()将总是返回一个有效的会话,这意味着不再有随机注销。(PR)
    • 废弃并删除了对multitab'支持的设置,因为getSession()`和gotrue的重用间隔设置已经处理了多个标签的会话管理(PR)
    • 不再抛出随机错误,gotrue-js v2总是返回一个自定义的错误类型:(PR)
      • AuthSessionMissingError(AuthSession错误)
        • 表示预期有一个会话,但没有。
      • AuthNoCookieError表示预期有cookie,但没有。
        • 表示期望有一个cookie,但没有。
      • AuthInvalidCredentialsError表示期望有一个cookie但没有。
        • 表示传递了不正确的凭证。
    • 将 "api "命名空间更名为 "admin","admin "命名空间将只包含只能在受信任的服务器端环境中使用的方法,并配有服务角色密钥
    • resetPasswordForEmailgetUserupdateUser移至GoTrueClient,这意味着它们可以从supabase.auth命名空间访问supabase-js,而不是通过supabase.auth.api来访问它们。
    • 删除了sendMobileOTP, sendMagicLinkEmail,改用signInWithOtp
    • 删除了signInWithEmail, signInWithPhone,改为signInWithPassword
    • 删除了 "用电子邮件签名"、"用电话签名",改为 "签名"。
    • 用 "updateUser "代替了 "update"。
  • Storage-js
    • 返回类型更加严格。函数类型曾经表明,即使没有错误,返回的数据也可能是空的。现在我们使用联合类型,只有在出现错误时才将数据标记为空,反之亦然。(PR)
    • uploadupdate函数返回上传对象的路径作为path参数。以前的返回值是将桶的名称预置在路径上,这使得该值难以传递给其他storage-js方法,因为所有的方法都是单独获取桶的名称和路径。我们还选择将返回值称为path而不是Key(PR)
    • getPublicURL只返回数据对象中的公共URL。这与我们的其他方法保持一致,只在数据对象内返回。没有错误返回,因为这个方法不能抛出一个错误(PR)
    • createSignedUrl'和createSignedUrls'中,签名的URL将以signedUrl'而不是signedURL'返回(PR)
    • createSignedUrlcreateSignedUrlsgetPublicUrl返回的URL进行编码(PR)
    • createsignedUrl曾经直接返回一个URL,并在数据对象中。这是不一致的。现在我们在所有方法中都只返回数据对象中的值。(PR)
    • createBucket返回一个数据对象,而不是直接返回桶的名字。(PR)
    • 固定了元数据的类型 (PR)
    • 更好的错误类型使其更容易快速追踪到出错的原因。
    • SupabaseStorageClient不再被导出。使用 "StorageClient "代替。(PR)。
  • Realtime-js
    • RealtimeSubscription类不再存在,被RealtimeChannel取代。
    • RealtimeClientdisconnect方法现在返回类型为void。以前它返回的类型是Promise<{ error: Error | null; data: boolean }
    • SupabaseClient类中删除了removeAllSubscriptionsremoveSubscription方法。
    • 删除了 "SupabaseRealtimeClient "类。
    • 删除了 "SupabaseQueryBuilder "类。
    • 删除了 "SupabaseEventTypes "类型。
      • 考虑将其重命名为 "RealtimePostgresChangeEvents",并将其移至 "realtime-js "版本。
    • 删除了.from('table').on('INSERT', () ⇒ {}).subscribe(),以支持新的实时客户端API。