JavaScript: Utilities

kizunasync exports a handful of standalone functions, types, and constants beside the client Initializing returns. No other reference page names them, because the composed client already exposes the behavior most of them implement: an application reaches for one of these directly only when it assembles its own ITransfer, IEngineTransport, or ILogger instead of the shipped kizunasync/supabase and kizunasync/web adapters.

Examples#

// kizunasync
import {
  contentKey,
  createLogger,
  createRequestSignal,
  createSignedUrlDownload,
  createTransferTimeoutError,
  INTERNAL_TABLES,
  isArrayRemove,
  isArrayUnion,
  isIncrement,
  isJsonObject,
  mimeForExt,
  noopLogger,
  parseFailureEnvelope,
  readEngineJson,
  reReadsRows,
  SCHEMA,
  SIGNED_URL_TTL_SECONDS,
  TRACKERS,
  type IEngineLeadership,
  type ILoggerOptions,
  type TLogLevel,
} from 'kizunasync'

Bound a fetch by its own deadline#

// src/storage-transfer.ts
import { createRequestSignal } from 'kizunasync'

export async function fetchWithDeadline(url: string): Promise<Response> {
  const { signal, timedOut, release } = createRequestSignal({ timeoutMs: 30_000 })

  try {
    return await fetch(url, { signal })
  } catch (error) {
    throw timedOut() ? new Error(`${url} did not answer within 30 seconds`) : error
  } finally {
    release()
  }
}

Recover a failure that crossed postMessage as text#

// src/engine-host.ts
import { parseFailureEnvelope } from 'kizunasync'

export function rethrowEngineFailures(worker: Worker): void {
  worker.addEventListener('message', (event) => {
    const failure = parseFailureEnvelope(event.data as string)

    if (failure !== null) throw failure
  })
}

Share one logger with the Storage transfer#

// src/storage-transfer.ts
import { createLogger } from 'kizunasync'
import { createSupabaseTransfer } from 'kizunasync/supabase'
import { createWebFileStore } from 'kizunasync/web'
import { supabase } from './supabase-client'

const logger = createLogger({ level: 'warn' })
const fileStore = createWebFileStore()

export const transfer = createSupabaseTransfer({ client: supabase, fileStore, logger })

File paths and MIME types#

Two pure functions behind the attachment pipeline's file naming.

Field transform guards#

Type guards for the three sentinels increment, arrayUnion, and arrayRemove build, for code that narrows an unknown update value before branching on its shape.

Engine call parsing#

The guarded parse every JSON text crossing the engine boundary goes through, and the parser built on it for every bridge's { ok: true, value } | { ok: false, error } call envelope, exported for a host that receives that envelope as text rather than as a return value.

Query re-read events#

The filter behind React: useQuery and Vue: useQuery: which TEngineEvent types can change what a row read would return, so a subscriber re-reads only on those.

Logging#

The factory behind the client's logging option, documented on Initializing, for an application that builds one logger and shares it across more than one adapter.

Request and transfer deadlines#

Two pieces Wait with a deadline is built from, for an adapter that bounds one fetch call directly instead of racing a whole promise.

Signed URL downloads#

The download half of an ITransfer adapter, built once and reused: Create the Storage transfer calls it, and a host with its own Storage layer can call it directly.

Multi-tab engine leadership#

The optional member on IEngineTransport a transport implements when it shares one engine across more than one host, such as the browser worker driver's tabs.

Server schema constants#

The Postgres schema name and object names kizunasync init provisions, exported so client code names them without repeating the literals the SQL pack installs.

Notes#

INTERNAL_TABLES, SCHEMA, and TRACKERS name what the SQL migration in packages/supabase-pack installs. Both sides are kept in lockstep by hand, because the migration is plain SQL and cannot import a TypeScript constant; a rename on one side needs the matching edit on the other.

Related reference#

• Types
• Using transforms
• Wait with a deadline
• Create the Storage transfer
• Open the browser driver
• Initializing
• React: useQuery
• Vue: useQuery