JavaScript: Set bucket

setBucket(params) fills the value of a byColumn bucket, the partition the app picks at runtime, such as the workspace a user opens. Each bucket column starts empty, and a pull with an empty one fails rather than asking the server for an unpartitioned page. A byOwner bucket needs no call, because the engine fills it with the signed-in user.

Examples#

Declare a runtime bucket#

// src/kizunasync.ts
import { byColumn, defineConfig } from 'kizunasync'
import { createSupabaseKizunaSync } from 'kizunasync/supabase'
import { createWebWorkerDriver } from 'kizunasync/web'
import { supabase } from './supabase-client'

const config = defineConfig({
  tables: { todos: { sync: 'read-write', bucket: byColumn('workspace_id') } },
})

export const kizunasync = createSupabaseKizunaSync({ supabase, driver: createWebWorkerDriver('todos.db'), config })

Open a workspace#

// src/workspace.ts
import { kizunasync } from './kizunasync'

export async function openWorkspace(workspaceId: string): Promise<void> {
  kizunasync.setBucket({ workspace_id: workspaceId })
  await kizunasync.sync()
}

The sync() call pulls the workspace's rows right away instead of at the next poll.

Parameters#

byColumn() and byOwner() on Define config name the bucket columns, and this method is for the byColumn kind. It accepts an owner column as well, but the engine overwrites that value with the owner once the store records one, and again at every later open.

Returns#

void, applied synchronously. The value is forwarded through the engine's command queue, so a pull issued right after this call cannot overtake it. The values it stores change two things.

Errors#

A value the engine refuses surfaces as BUCKET_UNSET on the next engine call rather than on this one, because the call is queued behind the engine's other work. The message tells the two cases apart:

Troubleshooting shows the fix for both.

This call opens the engine when it is the app client's first use. When that open fails, on this call or an earlier one, this method throws the open's typed error, such as ENGINE_UNAVAILABLE or STORE_BUSY.

Notes#

The engine fills a byOwner bucket by itself. The first token the app client hands the engine records the store's owner, the user that token names, and every byOwner column takes that user's id. After a restart the engine fills the column at open from the owner the store kept, with no token and no network needed. A token of another user soft-blocks sync with identity_changed until Reset runs, so switching accounts on one device goes through a reset.

A byColumn value is not restored when the client opens, so set it on every launch before the first pull needs it. A pull that runs earlier fails with BUCKET_UNSET, and the automatic loop retries it on its next attempt.

A value that differs from the one a table already kept, and is not empty, replaces the local scope: the next pull re-bootstraps the table from the beginning, and its boundary drops the rows the new scope does not carry. Queued writes stay in the outbox and push under the new scope regardless, and no remote attachment is deleted. Filling a key the table keeps no value for yet, passing '', or passing the value it already kept replaces nothing. The kept value survives a restart, so reopening the same workspace after a reload re-bootstraps nothing. Switching workspaces inside one session therefore needs no separate reset.

A table provisioned without a bucket column is unpartitioned: the request carries an empty parameter map and server Row Level Security alone decides visibility, under the policies the project declares. A table provisioned with a bucket column refuses an unscoped pull with KZL01. Sync rules and buckets compares the three shapes.

Related reference#

• Define config
• Sync
• Pull once
• Reset
• Swift: Set bucket
• Kotlin: Set bucket